Skip to content

Commit

Permalink
Rename Points/points to Length/length in many APIs (#459)
Browse files Browse the repository at this point in the history
⚠️ This is a fairly disruptive breaking changes,
although the fix for users is mostly search-and-replace.

The old name for this one-dimensional length:

* Suggests PostScript points, but is documented as an abstract unit:
  “Users of Taffy may define what they correspond to in their application
   (pixels, logical pixels, mm, etc) as they see fit.”

* Is spelled similar to the two-dimensional `Point` though its meaning is unrelated.

* In CSS syntax, `1px = 0.75pt` but the former is much more commonly used.
  When [parsing CSS into a `Style`](#440)
  we’ll probably want the default mapping to be `1px` => 1f32 abstract unit,
  so naming the abstract unit "points" would be confusing.
  • Loading branch information
SimonSapin authored Apr 21, 2023
1 parent d52ab8f commit 55abeaf
Show file tree
Hide file tree
Showing 693 changed files with 4,274 additions and 4,251 deletions.
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,15 @@ let mut taffy = Taffy::new();
let header_node = taffy
.new_leaf(
Style {
size: Size { width: points(800.0), height: points(100.0) },
size: Size { width: length(800.0), height: length(100.0) },
..Default::default()
},
).unwrap();

let body_node = taffy
.new_leaf(
Style {
size: Size { width: points(800.0), height: auto() },
size: Size { width: length(800.0), height: auto() },
flex_grow: 1.0,
..Default::default()
},
Expand All @@ -46,7 +46,7 @@ let root_node = taffy
.new_with_children(
Style {
flex_direction: FlexDirection::Column,
size: Size { width: points(800.0), height: points(600.0) },
size: Size { width: length(800.0), height: length(600.0) },
..Default::default()
},
&[header_node, body_node],
Expand Down
26 changes: 26 additions & 0 deletions RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,32 @@

## Unreleased

### Breaking

Many APIs have been renamed to replace `points` or `Points` with `length` or `Length`.
This new name better describes one-dimentional measure of space in some unspecified unit
which is often unrelated to the PostScript point or the CSS `pt` unit.

This also removes a misleading similarity with the 2D `Point`,
whose components can have any unit and are not even necessarily absolute lengths.

Example usage change:

```diff
use taffy::prelude::*;

// …

let header_node = taffy
.new_leaf(
Style {
- size: Size { width: points(800.0), height: points(100.0) },
+ size: Size { width: length(800.0), height: length(100.0) },
..Default::default()
},
).unwrap();
```

### Removed

- `layout_flexbox()` has been removed from the prelude. Use `FlexboxAlgorithm::perform_layout()` instead.
Expand Down
4 changes: 2 additions & 2 deletions benches/benches/flexbox.rs
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ fn build_yoga_deep_hierarchy(node_count: u32, branching_factor: u32) -> (yg::Yog
/// A deep tree that matches the shape and styling that yoga use on their benchmarks
fn build_taffy_huge_nested_hierarchy(node_count: u32, branching_factor: u32) -> (Taffy, NodeId) {
let style = Style {
size: Size { width: Dimension::Points(10.0), height: Dimension::Points(10.0) },
size: Size { width: Dimension::Length(10.0), height: Dimension::Length(10.0) },
flex_grow: 1.0,
..Default::default()
};
Expand All @@ -115,7 +115,7 @@ fn build_taffy_huge_nested_hierarchy(node_count: u32, branching_factor: u32) ->
/// A deep tree that matches the shape and styling that yoga use on their benchmarks
fn build_yoga_huge_nested_hierarchy(node_count: u32, branching_factor: u32) -> (yg::YogaTree, yg::NodeId) {
let style = Style {
size: Size { width: Dimension::Points(10.0), height: Dimension::Points(10.0) },
size: Size { width: Dimension::Length(10.0), height: Dimension::Length(10.0) },
flex_grow: 1.0,
..Default::default()
};
Expand Down
10 changes: 5 additions & 5 deletions benches/benches/grid.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ use taffy::style::Style;

/// Build a random leaf node
fn build_random_leaf(taffy: &mut Taffy, _rng: &mut ChaCha8Rng) -> NodeId {
taffy.new_with_children(Style { size: points(20.0), ..Default::default() }, &[]).unwrap()
taffy.new_with_children(Style { size: length(20.0), ..Default::default() }, &[]).unwrap()
}

fn random_grid_track<R: Rng>(rng: &mut R) -> TrackSizingFunction {
Expand All @@ -22,9 +22,9 @@ fn random_grid_track<R: Rng>(rng: &mut R) -> TrackSizingFunction {
} else if switch < 0.5 {
fr(1.0)
} else if switch < 0.6 {
minmax(points(0.0), fr(1.0))
minmax(length(0.0), fr(1.0))
} else if switch < 0.8 {
points(40.0)
length(40.0)
} else {
percent(0.3)
}
Expand Down Expand Up @@ -110,7 +110,7 @@ fn taffy_benchmarks(c: &mut Criterion) {
|b, &track_count| {
b.iter_batched(
|| build_grid_flat_hierarchy(track_count, track_count),
|(mut taffy, root)| taffy.compute_layout(root, points(12000.0)).unwrap(),
|(mut taffy, root)| taffy.compute_layout(root, length(12000.0)).unwrap(),
criterion::BatchSize::SmallInput,
)
},
Expand All @@ -128,7 +128,7 @@ fn taffy_benchmarks(c: &mut Criterion) {
|b, &(levels, tracks)| {
b.iter_batched(
|| build_taffy_deep_grid_hierarchy(levels, tracks),
|(mut taffy, root)| taffy.compute_layout(root, points(12000.0)).unwrap(),
|(mut taffy, root)| taffy.compute_layout(root, length(12000.0)).unwrap(),
criterion::BatchSize::SmallInput,
)
},
Expand Down
2 changes: 1 addition & 1 deletion benches/src/random_style.rs
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ impl Randomizeable for Dimension {
if switch < 0.2 {
Dimension::Auto
} else if switch < 0.8 {
Dimension::Points(rng.gen_range(0.0..500.0))
Dimension::Length(rng.gen_range(0.0..500.0))
} else {
Dimension::Percent(rng.gen_range(0.0..1.0))
}
Expand Down
2 changes: 1 addition & 1 deletion benches/src/yoga_helpers.rs
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ pub fn new_with_children(
fn into_yg_units(dim: impl Into<tf::Dimension>) -> yg::StyleUnit {
match dim.into() {
tf::Dimension::Auto => yg::StyleUnit::Auto,
tf::Dimension::Points(val) => yg::StyleUnit::Point(yg::OrderedFloat(val)),
tf::Dimension::Length(val) => yg::StyleUnit::Point(yg::OrderedFloat(val)),
tf::Dimension::Percent(val) => yg::StyleUnit::Percent(yg::OrderedFloat(val)),
}
}
Expand Down
2 changes: 1 addition & 1 deletion docs/morphorm-style-properties.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ pub enum PositionType {

```rust
pub enum Units {
Pixels(f32), // = Dimension::Points
Pixels(f32), // = Dimension::Length
Percentage(f32), // = Dimension::Percent
Auto, // = Dimension::Auto
Stretch(f32), // No equivalent in Taffy!
Expand Down
2 changes: 1 addition & 1 deletion examples/basic.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ fn main() -> Result<(), taffy::TaffyError> {

let node = taffy.new_with_children(
Style {
size: Size { width: Dimension::Points(100.0), height: Dimension::Points(100.0) },
size: Size { width: Dimension::Length(100.0), height: Dimension::Length(100.0) },
justify_content: Some(JustifyContent::Center),
..Default::default()
},
Expand Down
4 changes: 2 additions & 2 deletions examples/flexbox_gap.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ use taffy::prelude::*;
fn main() -> Result<(), taffy::TaffyError> {
let mut taffy = Taffy::new();

let child_style = Style { size: Size { width: points(20.0), height: points(20.0) }, ..Default::default() };
let child_style = Style { size: Size { width: length(20.0), height: length(20.0) }, ..Default::default() };
let child0 = taffy.new_leaf(child_style.clone())?;
let child1 = taffy.new_leaf(child_style.clone())?;
let child2 = taffy.new_leaf(child_style.clone())?;

let root = taffy.new_with_children(
Style { gap: Size { width: points(10.0), height: zero() }, ..Default::default() },
Style { gap: Size { width: length(10.0), height: zero() }, ..Default::default() },
&[child0, child1, child2],
)?;

Expand Down
8 changes: 4 additions & 4 deletions examples/grid_holy_grail.rs
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ fn main() -> Result<(), taffy::TaffyError> {
// Setup the grid
let root_style = Style {
display: Display::Grid,
size: Size { width: points(800.0), height: points(600.0) },
grid_template_columns: vec![points(250.0), fr(1.0), points(250.0)],
grid_template_rows: vec![points(150.0), fr(1.0), points(150.0)],
size: Size { width: length(800.0), height: length(600.0) },
grid_template_columns: vec![length(250.0), fr(1.0), length(250.0)],
grid_template_rows: vec![length(150.0), fr(1.0), length(150.0)],
..default()
};

Expand All @@ -41,7 +41,7 @@ fn main() -> Result<(), taffy::TaffyError> {
let root = taffy.new_with_children(root_style, &[header, left_sidebar, content_area, right_sidebar, footer])?;

// Compute layout and print result
taffy.compute_layout(root, Size { width: points(800.0), height: points(600.0) })?;
taffy.compute_layout(root, Size { width: length(800.0), height: length(600.0) })?;
taffy::util::print_tree(&taffy, root);

Ok(())
Expand Down
4 changes: 2 additions & 2 deletions examples/nested.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ fn main() -> Result<(), taffy::TaffyError> {

// left
let child_t1 = taffy.new_leaf(Style {
size: Size { width: Dimension::Points(5.0), height: Dimension::Points(5.0) },
size: Size { width: Dimension::Length(5.0), height: Dimension::Length(5.0) },
..Default::default()
})?;

Expand All @@ -20,7 +20,7 @@ fn main() -> Result<(), taffy::TaffyError> {

// right
let child_t2 = taffy.new_leaf(Style {
size: Size { width: Dimension::Points(5.0), height: Dimension::Points(5.0) },
size: Size { width: Dimension::Length(5.0), height: Dimension::Length(5.0) },
..Default::default()
})?;

Expand Down
16 changes: 8 additions & 8 deletions scripts/gentest/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -643,9 +643,9 @@ fn generate_length_percentage(dimen: &serde_json::Map<String, Value>) -> TokenSt

match unit {
Value::String(ref unit) => match unit.as_ref() {
"points" => {
"px" => {
let value = value();
quote!(taffy::style::LengthPercentage::Points(#value))
quote!(taffy::style::LengthPercentage::Length(#value))
}
"percent" => {
let value = value();
Expand All @@ -664,9 +664,9 @@ fn generate_length_percentage_auto(dimen: &serde_json::Map<String, Value>) -> To
match unit {
Value::String(ref unit) => match unit.as_ref() {
"auto" => quote!(taffy::style::LengthPercentageAuto::Auto),
"points" => {
"px" => {
let value = value();
quote!(taffy::style::LengthPercentageAuto::Points(#value))
quote!(taffy::style::LengthPercentageAuto::Length(#value))
}
"percent" => {
let value = value();
Expand All @@ -685,9 +685,9 @@ fn generate_dimension(dimen: &serde_json::Map<String, Value>) -> TokenStream {
match unit {
Value::String(ref unit) => match unit.as_ref() {
"auto" => quote!(taffy::style::Dimension::Auto),
"points" => {
"px" => {
let value = value();
quote!(taffy::style::Dimension::Points(#value))
quote!(taffy::style::Dimension::Length(#value))
}
"percent" => {
let value = value();
Expand Down Expand Up @@ -817,10 +817,10 @@ fn generate_scalar_definition(track_definition: &serde_json::Map<String, Value>)
"auto" => quote!(auto()),
"min-content" => quote!(min_content()),
"max-content" => quote!(max_content()),
"points" | "percent" | "fraction" => {
"px" | "percent" | "fraction" => {
let value = value();
match unit() {
"points" => quote!(points(#value)),
"px" => quote!(length(#value)),
"percent" => quote!(percent(#value)),
"fraction" => quote!(fr(#value)),
_ => unreachable!(),
Expand Down
32 changes: 16 additions & 16 deletions scripts/gentest/test_helper.js
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ class TrackSizingParser {
// console.debug(this.index, char);

// Skip whitespace
if (char === ' ') { this.index++; continue;}
if (char === ' ') { this.index++; continue; }

if (TrackSizingParser.INITIAL_CHAR_REGEX.test(char)) {
const token = this._parseItem();
Expand All @@ -51,7 +51,7 @@ class TrackSizingParser {
}
}

throw new Error (`Invalid start of token ${char}`);
throw new Error(`Invalid start of token ${char}`);
}
}

Expand Down Expand Up @@ -98,9 +98,9 @@ function parseRepetition(input) {
}

function parseDimension(input, options = { allowFrUnits: false }) {
if (options.allowFrUnits && input.endsWith('fr')) return { unit: 'fraction', value: parseFloat(input.replace('fr','')) };
if (input.endsWith('px')) return { unit: 'points', value: parseFloat(input.replace('px','')) };
if (input.endsWith('%')) return { unit: 'percent', value: parseFloat(input.replace('%','')) / 100 };
if (options.allowFrUnits && input.endsWith('fr')) return { unit: 'fraction', value: parseFloat(input.replace('fr', '')) };
if (input.endsWith('px')) return { unit: 'px', value: parseFloat(input.replace('px', '')) };
if (input.endsWith('%')) return { unit: 'percent', value: parseFloat(input.replace('%', '')) / 100 };
if (input === 'auto') return { unit: 'auto' };
if (input === 'min-content') return { unit: 'min-content' };
if (input === 'max-content') return { unit: 'max-content' };
Expand Down Expand Up @@ -136,15 +136,15 @@ function parseEdges(edges) {
const right = parseDimension(edges.right);
const top = parseDimension(edges.top);
const bottom = parseDimension(edges.bottom);

if (!left && !right && !top && !bottom) return undefined;
return { left, right, top, bottom };
}

function parseSize(size) {
const width = parseDimension(size.width);
const height = parseDimension(size.height);

if (!width && !height) return undefined;
return { width, height };
}
Expand All @@ -155,7 +155,7 @@ function parseGaps(style) {
return { row: gaps[0], column: gaps[1] ?? gaps[0] };
}
if (style.rowGap || style.columnGap) {
return { row: parseDimension(style.rowGap), column: parseDimension(style.columnGap) }
return { row: parseDimension(style.rowGap), column: parseDimension(style.columnGap) };
}
return undefined;
}
Expand All @@ -174,9 +174,9 @@ function parseGridAutoFlow(input) {
}

function parseGridPosition(input) {
if (input === 'auto') return { kind: 'auto' }
if (/^span +\d+$/.test(input)) return { kind: 'span', value: parseInt(input.replace(/[^\d]/g, ''), 10)}
if (/^-?\d+$/.test(input)) return { kind: 'line', value: parseInt(input, 10)}
if (input === 'auto') return { kind: 'auto' };
if (/^span +\d+$/.test(input)) return { kind: 'span', value: parseInt(input.replace(/[^\d]/g, ''), 10) };
if (/^-?\d+$/.test(input)) return { kind: 'line', value: parseInt(input, 10) };
return undefined;
}

Expand Down Expand Up @@ -226,9 +226,9 @@ function describeElement(e) {

gap: parseGaps(e.style),

size: parseSize({width: e.style.width, height: e.style.height}),
minSize: parseSize({width: e.style.minWidth, height: e.style.minHeight}),
maxSize: parseSize({width: e.style.maxWidth, height: e.style.maxHeight}),
size: parseSize({ width: e.style.width, height: e.style.height }),
minSize: parseSize({ width: e.style.minWidth, height: e.style.minHeight }),
maxSize: parseSize({ width: e.style.maxWidth, height: e.style.maxHeight }),
aspectRatio: parseRatio(e.style.aspectRatio),

margin: parseEdges({
Expand Down Expand Up @@ -295,7 +295,7 @@ function describeElement(e) {
useRounding: e.getAttribute("data-test-rounding") !== "false",

children: Array.from(e.children).map(c => describeElement(c)),
}
};
}

// Useful when developing this script. Logs the parsed style to the console when any test fixture is opened in a browser.
Expand All @@ -305,4 +305,4 @@ window.onload = function () {
} catch (e) {
console.error(e);
}
}
};
Loading

0 comments on commit 55abeaf

Please sign in to comment.