taffy

The MSRV for this release is 1.71.

Added

• Support for the self-start and self-end alignment keywords (AlignItems::SELF_START/SELF_END and safe variants). These resolve against the direction of the item itself rather than that of its container, so they only differ from start/end when the item's direction differs from its container's. Supported for align-self/align-items and justify-self/justify-items on both in-flow and absolutely positioned Flexbox and Grid items (#1074)

• Support for display: flow-root. The new Display::FlowRoot variant lays out children using the block layout algorithm but always establishes a new block formatting context (its margins do not collapse with those of its children, it contains its own floats, and it avoids external floats)

Changed

• Numeric style helpers (length, percent, fr, flex) now accept Input: Into<f64> instead of Input: Into<f32>. This allows bare float literals such as length(800.0) to be used without triggering the float_literal_f32_fallback future-compatibility lint, while widening the set of accepted numeric input types (#974)
• Grid: grid_template_areas is now Option<GridTemplateAreas<S>>, where the new GridTemplateAreas struct includes row_count/column_count fields. This allows templates containing unnamed (.) cells beyond the extents of the named areas (e.g. grid-template-areas: "a .") to be represented.
• Block/float: BlockContext::place_floated_box takes an additional adjoins_unresolved_strut: bool parameter indicating whether the float is being placed while the position of the current margin-collapse strut is still unresolved

Fixed

A large number of miscelaneous bug fixes are included in this release:

• Flexbox: clamp the flex base size, automatic minimum size and hypothetical main/cross sizes with min/max sizes transferred through the aspect ratio, instead of baking them into the item's used min/max sizes (#989)
• Flexbox: resolve justify-content: start/end and align-self: start/end/self-start/self-end as writing-mode relative (rather than flex-relative) in the static position of absolutely positioned children; use the flex-relative start for justify-content: space-between/normal, and a fallback of start for align-self: baseline (#1072)
• Flexbox: only let auto margins on absolutely positioned children absorb free space when the box is inset-constrained in that axis; otherwise they resolve to zero per CSS2 §10.3.7/§10.6.4 (#1072)
• Grid: jump the auto-placement search past entire colliding occupied intervals rather than advancing one track at a time (#1038)
• Grid: resolve the grid lines used by absolutely positioned items to the edges of the adjacent tracks, so that free space distributed by align-content/justify-content is not included in the abspos grid area (#1071)
• Grid: exclude absolutely positioned children from the implicit grid size estimate, as they do not take part in grid placement and must not create implicit tracks. Previously their out-of-range lines resolved to phantom implicit tracks instead of being treated as auto (#1075)
• Grid: align an empty grid (one whose tracks have all collapsed) within its container, rather than always placing it at the start (#1078)
• Grid: only distribute space "beyond limits" to tracks whose max track sizing function is max-content (or fit-content()) (#1033)
• Grid: don't clamp an explicitly specified preferred or minimum size by the spanned tracks' fixed max track sizing functions when computing an item's minimum contribution (#1022)
• Grid: ignore the tracks' growth limits when distributing an item's intrinsic size contribution "beyond limits" (#1022)
• Grid: convert the container's min/max size to a content-box size before using it in the track sizing algorithm (#1023)
• Grid: compute the flex factor sum over only the spanned tracks eligible to receive space when distributing intrinsic size contributions to flexible tracks (#1019)
• Grid: don't grow tracks past their growth limits when distributing free space to multiple tracks with asymmetric limits (#1001)
• Block/Grid: measure Layout::content_size from the container's padding-box origin and include the container's own end-side padding, matching Flexbox and browser scrollWidth/scrollHeight semantics. Grid items in tracks that overflow the container now also contribute their position within the container, not just their own size (#1051)
• Block: don't stretch-size replaced elements; an auto width now resolves to the intrinsic size (#1002)
• Block: don't let boxes that establish an independent formatting context overlap floats: they narrow to fit beside the float, or move down below it if they don't fit (#991)
• Block: detect floats placed by the subtree of a preceding in-flow sibling, not just floats among direct siblings, when placing a box that establishes an independent formatting context (#1049)
• Block: apply a negative margin as usual on a BFC root's float-free side, instead of clamping it to the containing block edge (#1061)
• Block: compute clearance from the hypothetical position of the cleared element (including its collapsed top margin), supporting negative clearance (#1042)
• Block: prevent the cleared element's top margin from collapsing with preceding margins and with the parent's top margin (#1043)
• Block: force clearance for floats placed while the position of the enclosing margin-collapse strut is unresolved, and position such floats including the pending collapsible margins (#1046)
• Block: collapse the top and bottom margins of a self-collapsing element with clearance with each other and apply them inside the parent, rather than collapsing them with the parent's bottom margin (#1044)
• Block/float: treat clear as a no-op when no float has been placed on the relevant side(s) (#1041)
• Block: allow elements containing only floated children to be collapsed through (#1040)
• Block/float: record zero-width floats in the float context, so their edge acts as an obstacle for boxes establishing an independent formatting context (#1062)
• Block/float: a float establishes a new block formatting context, so its margins no longer collapse with the margins of its children (#1065)
• Block/float: honour CSS2 §9.5.1 rules 3 & 7 when placing floats: a float unconstrained by other floats may overflow its containing block, but one placed beside another float may not (#1064)
• Block/float: apply CSS2 §9.5.1 rule 5 (float ceiling) and clear past zero-sized floats, which occupy no float segment and so were previously ignored when positioning later floats and cleared elements (#1056)
• Block/float: sum float contributions when computing a float container's intrinsic width under definite available space (clamped between the widest single float and the available width), instead of dropping them entirely (#1055)

Fixed

• Block: return margin-collapsing outputs from vertical axis ComputeSize calls (#976)

This release container a couple of critical fixes for layout/caching bugs in the 0.12.0 release.

Fixed

• Block: don't commit deferred in-flow layouts to the tree when only computing size (#971)
• Block: pass through the requested run_mode when performing final layout on in-flow children, instead of always using MeasureSize (#972)

The MSRV for this release is 1.71.

Block: support for align-content (#959)

Block containers now implement align_content along the block axis for their in-flow children.

More correct caching logic

• The cache key now includes the axis, parent size, and available space, and ignores available space in an axis when a known dimension is set there. This is a performance hit (~10% in common cases, ~60% in pathalogically ones) but is necessary for correctness. It does also enable early-return optimizations (in cases where only the horizontal size is needed, which can allow that performance to be recouped in some cases (#911)

Fixed

• Flexbox: fall back to safe align-self of start on absolute-position overflow (#958)
• Block: derive definite height from aspect-ratio at final layout. A block container with aspect-ratio and an automatic height now becomes definite when its width is filled/stretched, so children's percentage heights resolve correctly and the ratio is preserved (#965)

The MSRV for this release is 1.71.

Implemented safe alignment keywords (#952)

Taffy now implements safe alignment (in addition to unsafe alignment).

The alignment style types are now structs consisting of an AlignmentKeyword and an AlignmentSafety modifier. For most users this will mean changing from using enum variants like AlignContent::Start to associated constants like AlignContent::START.

This change applies to the AlignContent, JustifyContent, AlignItems, JustifyItems, AlignSelf, and JustifySelf types.

Fixed

• Grid: resolve item percentages against grid area rather than grid container (#960)

Fixed

• CSS Grid auto-repeat and minimum-size handling (#946)

The MSRV for this release is 1.71.

Support for direction

The direction property is now supported, allowing for RTL layout of boxes in Block, Flexbox, and CSS Grid layout modes.

Support for floats

The float and clear properties are now supported. Support consists of a general-purpose FloatContext in the compute module, and integration of float layout into Block layout. Block layout now also has a BlockContext that allows a FloatContext to be shared across an entire Block formatting context.

Float support is feature flagged by the float_layout feature.

Support for parsing styles from CSS string (#929)

All of Taffy's style types (except the top-level Style struct) now have FromStr implementations that parses the type from the CSS representation of that value (e.g. 30px or 50% for LengthPercentage. A future version of Taffy will likely add support for parsing Style from ;-seperated CSS.

CSS parsing is feature flagged by the parse feature.

Changed

• Make DetailedGridTracksInfo struct accessible from a public module (#899)
• Add TaffyTree::write_tree method to debug print the tree into an arbitrary writer (#925)
• The cache set and set APIs now take &LayoutInput rather than individual values (#933)

Fixed

• Flexbox: apply gap even when there are auto margins (#938)

Fixed

• Fix wrong size propogation for absolute elements (#878)
• Fix bounds check in CellOccupancyMatrix::last_of_type (#890)
• Use doc_cfg instead of doc_auto_cfg (#868)

Changed

• Upgraded grid dependency from 0.18 to 1.0 (#864)

Fixed

• Flexbox: don't apply cross-axis stretch alignment to children with auto margins (#861)

Support for named grid lines and grid areas

Taffy now supports named grid lines and areas.

As these rely on arbitrary user-provided strings, Taffy's Style struct is now generic
over a string-like type (via the CheapCloneStr trait). Additionally as the grid feature is optional,
it has a PhantomData field of that type to make type inference work.

Changed

• PrintTree and RoundTree: use Layout instead of &Layout (#849).
• Renamed TrackSizingFunction to GridTemplateComponent
• Renamed NonRepeatedTrackSizingFunction to TrackSizingFunction
• The Repeat variant of GridTemplateComponent now contains a new GridTemplateRepetition struct, which allows
  line names to be specifed in addition to tracks.
• The way that grid styles are exposed in the low-level API is now a lot more generic with many associated types.

Added

• GridTemplateArea struct and Style::grid_template_areas field
• Style::grid_template_column_names and Style::grid_template_row_names fields. If non-empty, these
  should have length of exactly one greater than the corresponding grid_template_column/grid_template_rows style.

Fixed

• Fix serde feature on 32bit targets (#845)

Fixed

• Fix: Calculate correct new grid size when expanding cell_occupancy_matrix in the negative direction (#843)

Added

• Impl GridItemStyle and BlockContainerStyle for Style (#832).

Highlights

The big feature in this release is support for calc() values in the low-level API.

To use this API:

• Implement the resolve_calc_value method when implementing the LayoutPartialTree trait.
• Pass a type-erased pointer (*const ()) to constructors like LengthPercentage::calc(...)

Taffy treats the pointer as an opaque value (excepting that it uses the low 3 bits as a tag) which it will pass to LayoutPartialTree::resolve_calc_value along with a percentage resolution basis when it needs to resolve the value.

Changed

• The representation of many "size" types is now a tagged pointer than an enum. This is to enable calc(). The effected types are LengthPercentage, LengthPercentageAuto, Dimension, MinTrackSizingFunction, and MaxTrackSizingFunction types.

Added

• Special-case "compressible replaced elements" in grid sizing algorithm (#807) This allows for more correct sizing of "replaced" elements such as images that are children of flexbox or grid containers.

Fixed

• Grid: Fix infinite loop due to float precision in grid layout maximise tracks step (#792)
• Grid: Fix removed wrong addition, causing items to be misplaced. (#817)
• Grid: Fix grid placement for items with fixed primary axis (#818)
• Leaf layout: don't set available space to max-size (#819)

Fixed

• Add #[inline] annotation to some methods on TaffyTree (#802)
• Add TaffyTree::remove_children_range method (#802)

Fixed

• Fix infinite loop due to float precision in grid layout maximise tracks step (#792)

Fixed

• Grid: only stretch auto tracks if content-alignment is stretch (#783)

Fixed

• Fix detailed grid info for empty grid (#782)

Fixed

• Make TaffyTree::detailed_layout_info take &self rather than &mut self (#779)

Added

• The ability to access computed track sizes and item positions of a CSS Grid layout (#772). This information can be accessed using the LayoutGridContainer::set_detailed_grid_info method in the low-level API or the TaffyTree::detailed_layout_info method in the high-level API.

Fixed

• Improve interaction of abspos children of block containers with margin collapsing (#760)

Added

• Add TaffyTree::unrounded_layout getter (#765)

Removed

• The num-traits dependency was removed (#761) (#762)

Changed

• BREAKING: The cache_mut method on the LayoutPartialTree trait has been replaced with a separate CacheTree trait. This allows Taffy to be more easily used without caching or with a custom cache implementation.
• BREAKING: the TaffyTree::set_children method now removes the children from their previous parent (if they have one).

Added

• Helper methods to retrieve content-box sizes were added to Layout

Fixes

• Block: ignore margin collapsing when computing static position of abspos items (#747)

Fixes

• Fix: clamp indefinite available space by min- and max- size as appropriate (#742)

Fixes

• Fix calculation of auto-fill/auto-fit repetition count when container has a definite percentage size (#722)
• Fix min-size style not affecting intrinsic sizes (#723)
• Fix documentation of dirty and mark_dirty functions (#724)
• Fix intrinsic size of scroll containers that have a small explicit flex-basis (#728)

Highlights

• The Style struct has been "traitified". This supports Taffy's integration in Servo and generally makes Taffy more flexible. The Style struct still exists and implements the new traits so existing uses of Taffy will continue to work as before.
• The box-sizing style is supported
• Computed margins are output in Layout

Fixes

• Fix print_tree() when rounding is disabled (#680)
• Absolute Insets should be resolved against the container size minus border (#666)
• Fix flooring hypothetical_main_size by computed min size (#689)
• Fix flex line cross-size determination (#690)
• Fix panics in the grid algorithm (#691)
• Fix resolving flexible lengths (WPT css/flexbox-multiline-min-max test) (#692)
• Fix wrapping when a max main size style is present (#694)
• Fix case where Taffy allowed margins to collapse through an element when it shouldn't have (#695)

Added

• Legacy text align (for laying out <center> and <div align="..">) is supported
• Add is_table for block items (#701)
• Impl Debug and Clone for Cache (#688)
• Implement Debug and PartialEq for tree types (#697)

• Fix block stretch sizing (don't always apply stretch sizing to block containers) (#674)
• Fix computation of intrinsic main size when it depends on a child's known cross size (#673)
• Fix panic when GridLine 0 is specified (#671)
• Docs: Document feature flags and scrape examples (#672)
• Docs: Update cosmic-text example to cosmic-text 0.12 (#670)

• Fix: Clamp block item stretch widths by their min and max width (#664)
• Fix: Auto margin computation in block layout (#663)

The changes in 0.5 are relatively small but the new measure function parameter is a breaking change so it requires a minor version bump.

• Added: A style: &Style parameter has been added to measure functions.
• Added: The MaybeMath, MaybeResolve, and ResolveOrZero traits have been made public.
• Fix: use SizingMode::Inherent when sizing absolute children of flexbox nodes.

Fixes

• Content alignment (align-content/justify-content) behaviour was updated to match the latest spec (and Chrome 123+) (#635)
• Ensure that root Flexbox nodes are floored by their padding-border (#651, #655)
• Use grid area size not available space when applying aspect ratio to grid containers (#656)

Fixes

• Fix compilation error in evenly_sized_tracks style helper in recent versions of rustc caused by a change/regression in type inference (#643). Note that 3rd-party code that call style helpers that take an Into<f32> parameter may still be affected by this issue, but they should be able to fix on their side by clarifying the type passed in

• Fixed: single-line flex-container should clamp the line's cross-size (#638)
• Reduced binary footprint of Taffy from around 300kb to around 150kb (#636)

• Fixed: CSS Grid track sizing not respecting growth limits in some circumstances (#624)

Highlights

• Support for CSS Block layout (display: block)
• Support for the overflow property (+ scrollbar_width for overflow: scroll)
• Improved measure function API
• Completely refactored low-level API
• Simplified module hierarchy (+ most types/functions are now exported from the crate root)
• Expanded set of examples which better document integration with other layout systems (e.g. text layout)
• Computed values for padding and border are now output into the Layout struct

Block layout

Support for CSS Block layout has been added. This can be used via the new Display::Block variant of the Display enum. Note that full flow layout: inline, inline-block and float layout have not been implemented. The use case supported is block container nodes which contain block-level children.

Overflow property

Support has been added for a new overflow style property with Visible, Clip, Hidden, and Scroll values (Auto is not currently implemented). Additionally a scrollbar_width property has been added to control the size of scrollbars for nodes with Overflow::Scroll set.

• Overflow is settable indpendently in each axis.
• Visible and Clip will produce layouts equivalent to the Taffy 0.3. Clip will affect the new content_size output by restricting it to the available space.
• Hidden and Scroll affect layout by changing the automatic minimum size of Flexbox and Grid children
• Scroll additionally reserves scrollbar_width pixels for a scrollbar in the opposite axis to which scrolling is enabled. Scroll with scrollbar_width set to zero is equivalent to Hidden.

Measure function changes

The "measure function" API for integrating Taffy with other measurement systems (such as text layout) has been changed to be more flexible and to interact better with borrow checking (you can now borrow external data in your measure function!).

• There are no longer per-node measure functions.
• There is now a single "global" measure function, and a per-node "context" of a user-defined type
• The Taffy tree is now a generic TaffyTree<T> where T is the "context" type.
• The measure function is now called for all leaf nodes (nodes without children). If you wish to maintain compatibility with the previous behaviour then your measure function should return Size::ZERO for leaf nodes whose context is None.

If you are not using measure functions, then the only change you will need to make is from:

let mut tree = Taffy::new();

to

let mut tree : TaffyTree<()> = TaffyTree::new();

And generally update any uses of Taffy in your codebase to TaffyTree<()>.

If you are using measure functions then you will need to make some bigger (but straightforward) changes. The following Taffy 0.3 code:

let mut tree = Taffy::new();
let leaf = tree.new_leaf_with_measure(
  Style::DEFAULT,
  |known_dimensions: Size<Option<f32>>, available_space: Size<AvailableSpace>| Size { width: 100.0, height: 200.0 }
);
tree.compute_layout(leaf, Size::MAX_CONTENT);

Should become something like the following with Taffy 0.4:

let mut tree : TaffyTree<Size> = TaffyTree::new();
let leaf = tree.new_leaf_with_context(Style::DEFAULT, Size { width: 100.0, height: 200.0 });
tree.compute_layout_with_measure(
  leaf,
  Size::MAX_CONTENT,
  |known_dimensions: Size<Option<f32>>, available_space: Size<AvailableSpace>, node_id: NodeId, node_context: Option<Size>| {
    node_context.unwrap_or(Size::ZERO)
  }
);

Note that:

• You can choose any type instead of Size in the above example. This includes your own custom type (which can be an enum or a trait object).
• If you don't need a context then you can use () for the context type
• As the single "global" measure function passed to compute_layout_with_measure only needs to exist for the duration of a single layout run, it can (mutably) borrow data from it's environment

Low-level API (LayoutTree trait) refactor

The low-level API has been completely reworked:

• The LayoutTree trait has been split into 5 smaller traits which live in the taffy::tree:traits module (along with their associated documentation)
• The following methods have been removed from split LayoutTree traits entirely: parent, is_childless, measure_node, needs_measure, and mark_dirty.
• taffy::node::Node has been replaced with taffy::NodeId. This should make it much easier to implement the low-level traits as the underlying type backing the node id now a u64 rather than a slotmap::DefaultKey.
• Support for running each layout algorithm individually on a single node via the following top-level functions:
  • compute_flexbox_layout
  • compute_grid_layout
  • compute_block_layout
  • compute_leaf_layout
  • compute_root_layout
  • compute_hidden_layout

It is believed that nobody was previously using the low-level API so we are not providing a migration guide. However, along with the refactor we have greatly improved both the documentation and have added examples using the new API, both of which are linked to from the main documentation page.

Module hierarchy changes

The specific changes are detailed below. However for most users the most significant change will be that almost all types are now re-exported from the root module. This means that module specific imports like use taffy::layout::Layout can now in almost all cases be replaced with the simpler use taffy::Layout.

Specific changes:

• The math module has been made private
• The axis module has been merged into the geometry module
• The debug module is no longer public. The print_tree function is now accessible under util.
• All types from the node, data, layout, error and cache modules have been moved to the the tree module.
• The layout_flexbox() function has been removed from the prelude. Use taffy::compute_flexbox_layout instead.

Many APIs have been renamed to replace points or Points with length or Length

This new name better describes one-dimensional 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:

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

Other Changes

• The Taffy type was renamed to TaffyTree and made generic of a context parameter
• The Flexbox algorithm has now been moved behind the flexbox feature. The flexbox feature is enabled by default.
• The justify_self property has been moved behind the grid feature.
• Fixed misspelling: RunMode::PeformLayout renamed into RunMode::PerformLayout (added missing r).
• serde dependency has been made compatible with no_std environments
• slotmap dependency has been made compatible with no_std environments
• Added insert_child_at_index() method to the TaffyTree. This can be used to insert a child node at any position instead of just the end.
• Added total_node_count() method to the TaffyTree which returns the total number of nodes in the tree.
• Added get_disjoint_node_context_mut() method to the TaffyTree. This can be used to safely get multiple mutable borrows at the same time.

Fixes

• Fix compilation error in evenly_sized_tracks style helper in recent versions of rustc caused by a change/regression in type inference (#643). Note that 3rd-party code that call style helpers that take an Into<f32> parameter may still be affected by this issue, but they should be able to fix on their side by clarifying the type passed in

Fixes

• Fix computation of Flexbox automatic minimum size when grid or flexbox child has an explicit width/height style set (#576)

Added

• Added total_node_count method to the Taffy struct. Returns the total number of nodes in the tree.

Fixes

• Improve performance of flexbox columns

Fixes

• Fix justify-content and align-content when free space is negative (content overflows container) (#549) (#551)

Fixes

• Flex: Fix issue where constraints were not being propagated, causing nodes with inherent aspect-ratio (typically images) to not apply that aspect-ratio (#545) (Fixes bevyengine/bevy#9841)

Fixes

• Fix rounding accumulation bug (#521) (Fixes #501 and bevyengine/bevy#8911)

• Flexbox: pass correct cross-axis available space when computing an item's intrinsic main size (#522)(Fixes bevyengine/bevy#9350)

• Flexbox: Subtract child margin not parent margin when computing stretch-alignment known size

• Grid: Make CSS Grid algorithm correctly apply max width/height and available space when it is the root node (#491)

• Grid: Fix CSS Grid "auto track" / placement bugs #481

  • Fix divide by zero when using grid_auto_rows/grid_auto_columns with zero negative implicit tracks
  • Fix over counting of tracks (leading to incorrect container heights) when auto-placing in grids that contain negative implicit tracks.
  • Fix axis conflation in auto-placement code when grid_auto_flow is column
  • Fix assignment of auto track sizes when initializing negative implicit tracks

• Leaf: Apply margins to leaf nodes when computing available space for measure functions

• Leaf: Reserve space for padding/borders in nodes with measure functions (#497)

  NOTE: This has the potential to break layouts relying on the old behaviour. However, such layouts would be relying on a style having no effect, so it is judged that such layouts are unlikely to exist in the wild. If this turns out not to be true then this fix will be reverted on the 0.3.x branch.

Dependencies

• Upgrade grid to 0.10. This eliminates the transitive dependency on no-std-compat.

Fixes

• Fix caching issue when toggling display:none on and off

Fixes

• Fix exponential blowup when laying out trees containing nodes with min and max sizes.

Fixes

• Fix sizing of children when the available_space < min_size (#407)

Fixes

• Fix caching bug where a cached result would sometimes be incorrectly used when the amount of available space increased (bevyengine/bevy#8111) and (bevyengine/bevy#8124)

Fixes

• Fix incorrect min-content size for flex-wrap: wrap nodes (bevyengine/bevy#8082)

Fixes

• Fix: Make padding and border floor node sizes (#372)
• Fix: Prevent percentages contributing to min-content sizes (#388) (also fixes bevyengine/bevy#8017)

Fixes

• Fix: Ignore align_content when flex_wrap is set to nowrap (#383)

Fixes

• Fix display: none when it is set on a flexbox child (#380)
• Fix display: none when it is set on a grid child (#381)

Fixes

• Fix display: none when it is set for the only node in the hierarchy (#377)

Added

• Added enable_rounding and disable_rounding methods to the Taffy struct which enable consumers of Taffy to obtain unrounded f32 values for the computed layouts if they want them. Rounding remains enabled by default.

Fixes

• Fixed rounding algorithm such that it never leaves gaps between adjacent nodes (#369)
• Fixed compiling with the grid feature disabled (#370)
• Fixed compiling with the std feature disabled

Fixes

• Allow partial nested values to be deserialized into a Style using the serde feature.

Fixes

• The serde feature now works when the grid feature is enabled

Highlights

• CSS Grid algorithm support
• Style helper functions

See below for details of breaking changes.

New Feature: CSS Grid

We very excited to report that we now have support for CSS Grid layout. This is in addition to the existing Flexbox layout support, and the two modes interoperate. You can set a node to use Grid layout by setting the display property to Display::Grid.

Learning Resources

Taffy implements the CSS Grid specification faithfully, so documentation designed for the web should translate cleanly to Taffy's implementation. If you are interested in learning how to use CSS Grid, we would recommend the following resources:

• CSS Grid Garden. This is an interactive tutorial/game that allows you to learn the essential parts of CSS Grid in a fun engaging way.
• A Complete Guide To CSS Grid by CSS Tricks. This is detailed guide with illustrations and comprehensive written explanation of the different Grid properties and how they work.

Supported Features & Properties

In addition to the usual sizing/spacing properties (size, min_size, padding, margin, etc), the following Grid style properties are supported on Grid Containers:

Property	Explanation
grid-template-columns	The track sizing functions of the grid's explicit columns
grid-template-rows	The track sizing functions of the grid's explicit rows
grid-auto-rows	Track sizing functions for the grid's implicitly generated rows
grid-auto-columns	Track sizing functions for the grid's implicitly generated columns
grid-auto-flow	Whether auto-placed items are placed row-wise or column-wise. And sparsely or densely.
gap	The size of the vertical and horizontal gaps between grid rows/columns
align-content	Align grid tracks within the container in the inline (horizontal) axis
justify-content	Align grid tracks within the container in the block (vertical) axis
align-items	Align the child items within their grid areas in the inline (horizontal) axis
justify-items	Align the child items within their grid areas in the block (vertical) axis

And the following Grid style properties are supported on Grid Items (children):

Property	Explanation
grid-row	The (row) grid line the item starts at (or a span)
grid-column	The (column) grid line the item end at (or a span)
align-self	Align the item within it's grid area in the inline (horizontal) axis. Overrides align-items.
justify-self	Align the item within it's grid area in the block (vertical) axis. Overrides justify-items.

The following properties and features are not currently supported:

• Subgrids
• Masonry grid layout
• Named grid lines
• Named areas: grid-template-areas and grid-area
• grid-template or grid shorthand

Example

See examples/grid_holy_grail.rs for an example using Taffy to implement the so-called Holy Grail Layout. If you want to run this example, the don't forget the enable the CSS Grid cargo feature:

cargo run --example grid_holy_grail --features grid

New Feature: Style Helpers

Ten new helper functions have added to the taffy prelude. These helper functions have short, intuitive names, and have generic return types which allow them to magically return the correct type depending on context. They make defining styles much easier, and means you won't typically need to use types like Dimension or TrackSizingFunction directly.

For example, instead of:

let size : Size<Dimension> = Size { width: Dimension::Points(100.0), height: Dimension::Percent(50.0) };

you can now write

let size : Size<Dimension> = Size { width: points(100.0), height: percent(50.0) };

And that same helper function will work other types like LengthPercentage and MinTrackSizingFunction that also have a Points variant. There are also generic impl's for Size<T>, Rect<T> and Line<T> which means if your node is the same size in all dimensions you can even write

let size : Size<Dimension> = points(100.0);

Available style helpers:

<table> <thead><tr><th>Type(s)</th><th colspan="2">Helpers that work with that type</th></tr></thead> <tbody> <tr> <td rowspan="3"><code>LengthPercentage</code></td> <td><code>zero()</code></td> <td>Generates a <code>Points</code> variant with the value <code>0.0</code></td> </tr> <tr> <td><code>points(val: f32)</code></td> <td>Generates a <code>Points</code> variant with the specified value</td> </tr> <tr> <td><code>percent(val: f32)</code></td> <td>Generates a <code>Percent</code> variant with the specified value.<br />Note that the scale of 0-1 not 0-100.</td> </tr> <tr> <td rowspan="2"><code>LengthPercentageAuto</code><br /><code>Dimension</code></td> <td colspan="2"><i>All helpers from <code>LengthPercentage</code> and...</i></td> </tr> <tr> <td><code>auto()</code></td> <td>Generates an <code>Auto</code> variant</td> </tr> <tr> <td rowspan="3"><code>MinTrackSizingFunction</code></td> <td colspan="2"><i>All helpers from <code>LengthPercentageAuto</code>/<code>Dimension</code> and...</i></td> </tr> <tr> <td><code>min_content()</code></td> <td>Generates an <code>MinContent</code> variant</td> </tr> <tr> <td><code>max_content()</code></td> <td>Generates an <code>MinContent</code> variant</td> </tr> <tr> <td rowspan="3"><code>MaxTrackSizingFunction</code></td> <td colspan="2"><i>All helpers from <code>MinTrackSizingFunction</code> and...</i></td> </tr> <tr> <td><code>fit_content(limit: LengthPercentage)</code></td> <td>Generates a <code>FitContent</code> variant with the specified limit.<br />Nest the <code>points</code> or <code>percent</code> helper inside this function to specified the limit.</td> </tr> <tr> <td><code>fr(fraction: f32)</code></td> <td>Generates a <code>Fraction</code> (<code>fr</code>) variant with the specified flex fraction </td> </tr> <tr> <td rowspan="3"><code>NonRepeatingTrackSizingFunction</code></td> <td colspan="2"><i>All helpers from <code>MaxTrackSizingFunction</code> and...</i></td> </tr> <tr> <td><code>minmax(min: MinTrackSizingFunction, max: MaxTrackSizingFunction)</code></td> <td>Equivalent to CSS <code>minmax()</code> function.</td> </tr> <tr> <td><code>flex(fraction: f32)</code></td> <td>Equivalent to CSS <code>minmax(0px, 1fr)</code>. This is likely what you want if you want evenly sized rows/columns.</td> </tr> <tr> <td rowspan="2"><code>TrackSizingFunction</code></td> <td colspan="2"><i>All helpers from <code>NonRepeatingTrackSizingFunction</code> and...</i></td> </tr> <tr> <td><code>repeat(rep: GridTrackRepetition, tracks: Vec<TrackSizingFunction>)</code></td> <td>Equivalent to css <code>repeat()</code> function.</td> </tr> <tr> <td><code>Vec<TrackSizingFunction></code></td> <td><code>evenly_sized_tracks(count: u16)</code></td> <td>Equivalent to CSS <code>repeat(count, minmax(0px, 1fr)</code></td> </tr> <tr> <td rowspan="3"><code>AvailableSpace</code></td> <td><code>auto()</code></td> <td>Generates an <code>Auto</code> variant</td> </tr> <tr> <td><code>min_content()</code></td> <td>Generates an <code>MinContent</code> variant</td> </tr> <tr> <td><code>max_content()</code></td> <td>Generates an <code>MinContent</code> variant</td> </tr> <tr> <td><code>Size<T></code></td> <td colspan="2">Any helper that works for <code>T</code> will also work for <code>Size<T></code> and will set both <code>width</code> and <code>height</code> to that value</td> </tr> <tr> <td><code>Rect<T></code></td> <td colspan="2">Any helper that works for <code>T</code> will also work for <code>Rect<T></code> and will set <code>top</code>, <code>left</code>, <code>bottom</code>, and <code>right</code> to that value</td> </tr> </tbody> </table>

Breaking API changes

Changes to alignment style types

• AlignContent and JustifyContent has been merged.
  • JustifyContent is now an alias of AlignContent and contains the Stretch variant.
  • This variant will be ignored (falling back to Start) when applied Flexbox containers. It is valid value for Grid containers.
• AlignItems and AlignSelf have been merged.
  • The Auto variant of AlignSelf has been removed. You should now use Option::None if you wish to specify AlignSelf::Auto.
  • AlignSelf is now an alias of AlignItems.
  • JustifyItems and JustifySelf aliases have been added. These properties have no affect on Flexbox containers, but apply to Grid containers.
• Default impls have been removed from all alignment types. This is because the correct default varies by property, and the types are now shared between multiple properties. The Style struct still has a default for each alignment property, so this is considered unlikely to affect you in practice.

Strict style types

• New types LengthPercentage and LengthPercentageAuto have been added.
  • LengthPercentage is like Dimension but only contains the Points and Percent variants, which allows us to increase type safety for properties that don't support the Auto value.
  • LengthPercentageAuto is currently identical to Dimension but will allow us to expand dimension in future to support values like MinContent, MaxContent and FitContent.
• Some style properties have been updated to use either LengthPercentage or LengthPercentageAuto instead of Dimension. You will need to update your code, but it is recommended that you use the new style helpers (see above) rather than using the new types directly (although you certainly can use them directly if you want to).

Position properties renamed

• The position property is now renamed to inset and is now in line with CSS inset specs
• The position_type property is now renamed to position and is now in line with CSS position specs. The PositionType enum has been similarly renamed to Position.

Changes to LayoutTree

• Added generic associated type to LayoutTree for a ChildIter, an iterator on the children of a given node.
• Changed the children method of LayoutTree to return the ChildIter generic associated type to allow for custom tree storage implementations which do not store the children of a node contiguously.
• Added child_count method to LayoutTree for querying the number of children of a node. Required because the children method now returns an iterator instead of an array.
• Added is_childless method to LayoutTree for querying whether a node has no children.

AvailableSpace has been moved

The AvailableSpace enum has been moved from the layout module to the style module. If you are importing it via the prelude then you will unaffected by the change.

Fixes

• Flexbox nodes sized under a min-content constraint now size correctly (#291)
• Aspect ratio is now applied correctly in many circumstances
• Absolutely positioned items now apply margins correctly
• Min/max size are now applied correctly
• Inset applied incorrectly to relatively positioned flexbox children when both top and bottom or left and right were specified (#348)
• Fix case where column-gap style could be used in place of row-gap style (when using a percentage gap with an indefinite container size)

Removed

• Removed top_from_points, bot_from_points, top_from_percent, and bot_from_percent methods removed from Rect<Dimension>. These functions were incredibly specific for an unusual use case, so we would be surprised if anyone was using them. Please use the new style helpers instead.
• Removed min_main_size, max_main_size, min_cross_size, max_cross_size, and cross_size methods from Style. Use the more general cross and main methods directly on the size, min_size, and max_size properties instead.
• Removed main_margin_start, main_margin_end, cross_margin_start, cross_margin_end from Style. Use the more general main_start, main_end, cross_start, and cross_end on the margin property instead.

Fixes

• Border or padding on the horizontal axis could, in some cases, increase the height of nodes.