Rename Points/points to Length/length in many APIs (#459)

⚠️ 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.

README.md

@@ -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()
         },
@@ -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],

RELEASES.md

@@ -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.

benches/benches/flexbox.rs

@@ -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()
     };
@@ -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()
     };

benches/benches/grid.rs

@@ -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 {
@@ -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)
     }
@@ -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,
                 )
             },
@@ -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,
                 )
             },

benches/src/random_style.rs

@@ -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))
         }

benches/src/yoga_helpers.rs

@@ -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)),
     }
 }

docs/morphorm-style-properties.md

@@ -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!

examples/basic.rs

@@ -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()
         },

examples/flexbox_gap.rs

@@ -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],
     )?;
 

examples/grid_holy_grail.rs

@@ -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()
     };
 
@@ -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(())

examples/nested.rs

@@ -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()
     })?;
 
@@ -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()
     })?;
 

scripts/gentest/src/main.rs

@@ -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();
@@ -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();
@@ -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();
@@ -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!(),

scripts/gentest/test_helper.js

@@ -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();
@@ -51,7 +51,7 @@ class TrackSizingParser {
         }
       }
 
-      throw new Error (`Invalid start of token ${char}`);
+      throw new Error(`Invalid start of token ${char}`);
     }
   }
 
@@ -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' };
@@ -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 };
 }
@@ -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;
 }
@@ -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;
 }
 
@@ -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({
@@ -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.
@@ -305,4 +305,4 @@ window.onload = function () {
   } catch (e) {
     console.error(e);
   }
-}
+};