tawasuyu/taffy

A high performance rust-powered UI layout library

Rust 1077HTML 1008Markdown 12TOML 83209 Definitions

Clone over HTTPS, with plain git

⎇ devin/1785205225-fix-grid-track-limit-overflow docs/style-properties.md Markdown · 83 lines · 9.8 KB History raw

Implement `safe` and `unsafe` overflow-position alignment keywords (#952) d1ff7e339 · Ritesh · 4 months ago

1# Style Properties
2
3Y = Supported in spec and implemented in Taffy
4~Y = Implemented in Taffy, but not thoroughly tested
5N = Supported in spec but not implemented in Taffy
6\- = Not applicable to layout mode
71-5 = Priorities for a phased implementation of CSS Grid
8
9| Property                 | Flex | Grid | Type                                  | Stack | Heap   | Description                                                                                 |
10| ---                      | ---  | ---  | ---                                   | ---   | -      | ---                                                                                         |
11| **Layout Mode**          |      |      |                                       |       |        |                                                                                             |
12| `display`                | Y    | Y    | `Display`                             | 1     | -      | What layout strategy should be used?                                                        |
13| **Position**             |      |      |                                       |       | -      |                                                                                             |
14| `position`               | Y    | Y    | `Position`                            | 1     | -      | Absolute vs. in-flow position                                                               |
15| `inset`                  | Y    | Y    | `Rect<LengthPercentageAuto>`          | 32    | -      | How should the position of this element be tweaked relative to the layout defined?          |
16| **Item size**            |      |      |                                       |       |        |                                                                                             |
17| `size`                   | Y    | Y    | `Size<Dimension>`                     | 16    | -      | The nominal height and width of item                                                        |
18| `min_size`               | Y    | Y    | `Size<Dimension>`                     | 16    | -      | The minimum height and width of the item                                                    |
19| `max_size`               | Y    | Y    | `Size<Dimension>`                     | 16    | -      | The maximum height and width of the item                                                    |
20| `aspect_ratio`           | Y    | 3    | `Option<f32>`                         | 4     | -      | The preferred aspect ratio (calculated as width divided by height)                          |
21| **Item spacing**         |      |      |                                       |       |        |                                                                                             |
22| `padding`                | Y    | ~Y   | `Rect<LengthPercentage>`              | 32    | -      | How large should the padding be on each side?                                               |
23| `border`                 | Y    | ~Y   | `Rect<LengthPercentage>`              | 32    | -      | How large should the border be on each side?                                                |
24| `margin`                 | Y    | ~Y   | `Rect<LengthPercentageAuto>`          | 32    | -      | How large should the margin be on each side?                                                |
25| `gap`                    | Y    | Y    | `Size<LengthPercentage>`              | 16    | -      | The size of the vertical and horizontal gaps between flex items / grid rows                 |
26| **Alignment**            |      |      |                                       |       |        |                                                                                             |
27| `align_content`          | Y    | Y    | `AlignContent`                        | 2     | -      | How should content contained within this item be aligned relative to the cross axis?        |
28| `justify_content`        | Y    | Y    | `AlignContent`                        | 2     | -      | How should content contained within this item be aligned relative to the main axis?         |
29| `align_items`            | Y    | Y    | `AlignItems`                          | 2     | -      | How should items be aligned relative to the cross axis?                                     |
30| `align_self`             | Y    | Y    | `Option<AlignItems>`                  | 2     | -      | Should this item violate the cross axis alignment specified by its parent's [`AlignItems`]? |
31| `justify_items`          | -    | Y    | `AlignItems`                          | 2     | -      | How should items be aligned relative to the main axis?                                      |
32| `justify_self`           | -    | Y    | `Option<AlignItems>`                  | 2     | -      | Should this item violate the main axis alignment specified by its parent's [`AlignItems`]?  |
33| **Flexbox**              |      |      |                                       |       |        |                                                                                             |
34| `flex_direction`         | Y    | -    | `FlexDirection`                       | 1     | -      | Which direction does the main axis flow in?                                                 |
35| `flex_wrap`              | Y    | -    | `FlexWrap`                            | 1     | -      | Should elements wrap, or stay in a single line?                                             |
36| `flex_basis`             | Y    | -    | `Dimension`                           | 8     | -      | Sets the initial main axis size of the item                                                 |
37| `flex_grow`              | Y    | -    | `f32`                                 | 4     | -      | The relative rate at which this item grows when it is expanding to fill space               |
38| `flex_shrink`            | Y    | -    | `f32`                                 | 4     | -      | The relative rate at which this item shrinks when it is contracting to fit into space       |
39| **CSS Grid (Container)** |      |      |                                       |       |        |                                                                                             |
40| `grid_template_columns`  | -    | Y    | `Vec<TrackSizingFunction>`            | 24    | 32 * N | The track sizing functions of the grid's explicit columns                                   |
41| `grid_template_rows`     | -    | Y    | `Vec<TrackSizingFunction>`            | 24    | 32 * N | The track sizing functions of the grid's explicit rows                                      |
42| `grid_template_areas`    | -    | 5    | -                                     | -     | -      | Defines named grid areas                                                                    |
43| `grid_auto_rows`         | -    | Y    | `Vec<NonRepeatedTrackSizingFunction>` | 24    | 20 * N | Track sizing functions for the grid's implicitly generated rows                             |
44| `grid_auto_columns`      | -    | Y    | `Vec<NonRepeatedTrackSizingFunction>` | 24    | 20 * N | Track sizing functions for the grid's implicitly generated columns                          |
45| `grid_auto_flow`         | -    | Y    | `GridAutoFlow`                        | 1     | -      | Whether auto-placed items are placed row-wise or column-wise. And sparsely or densely.      |
46| **CSS Grid (Child)**     |      |      |                                       |       |        |                                                                                             |
47| `grid_row`               | -    | Y    | `Line<GridPlacement>`                 | 8     | -      | The vertical (row) placement of a grid item                                                 |
48| `grid_column`            | -    | Y    | `Line<GridPlacement>`                 | 8     | -      | The horizontal (row) placement of a grid item                                               |
49| `grid_area`              | -    | 5    | -                                     | -     | -      | Accepts either shorthand row/column-start/end or a named grid area                          |
50
51## Safe and unsafe overflow alignment
52
53`AlignItems` and `AlignContent` (and their aliases `AlignSelf`, `JustifyItems`, `JustifySelf`,
54`JustifyContent`) are structs with two orthogonal fields:
55
56```rust
57pub struct AlignContent {
58    pub keyword: AlignContentKeyword,   // Start, End, FlexStart, FlexEnd, Center,
59                                        // Stretch, SpaceBetween, SpaceEvenly, SpaceAround
60    pub safety: AlignmentSafety,        // Safe | Unsafe
61}
62```
63
64For ergonomics every CSS spelling is exposed as an associated constant — `AlignContent::Start`,
65`AlignContent::SafeStart`, `AlignItems::SafeFlexEnd`, etc. — so call sites read identically to
66the previous enum form.
67
68The `safety` field corresponds to the spec's
69[overflow-position keyword](https://www.w3.org/TR/css-align-3/#overflow-values). When the
70alignment subject would overflow its alignment container, `AlignmentSafety::Safe` falls back
71to logical `Start` so the start edge of the content stays visible. `AlignmentSafety::Unsafe`
72(the default) keeps the requested alignment even when that causes overflow at the start edge.
73
74The spec only defines `safe`/`unsafe` against the position keywords `start`, `end`,
75`flex-start`, `flex-end`, `center`. Combinations such as `safe stretch`, `safe baseline`, and
76`safe space-between` are rejected by the parser when the `parse` feature is enabled, and the
77compute pass treats them as `Unsafe` if a value somehow reaches it via manual struct
78construction.
79
80Use the `is_safe()` method to check the safety modifier and `keyword()` to retrieve the bare
81position keyword. The `safe`/`unsafe` overflow-position keyword is supported by both the
82Flexbox and CSS Grid layout algorithms for both content-level (`align-content`,
83`justify-content`) and self-level (`align-self`, `justify-self`) alignment.

style-properties.md

Style Properties

Y = Supported in spec and implemented in Taffy ~Y = Implemented in Taffy, but not thoroughly tested N = Supported in spec but not implemented in Taffy - = Not applicable to layout mode 1-5 = Priorities for a phased implementation of CSS Grid

Property	Flex	Grid	Type	Stack	Heap	Description
Layout Mode
`display`	Y	Y	`Display`	1	-	What layout strategy should be used?
Position					-
`position`	Y	Y	`Position`	1	-	Absolute vs. in-flow position
`inset`	Y	Y	`Rect<LengthPercentageAuto>`	32	-	How should the position of this element be tweaked relative to the layout defined?
Item size
`size`	Y	Y	`Size<Dimension>`	16	-	The nominal height and width of item
`min_size`	Y	Y	`Size<Dimension>`	16	-	The minimum height and width of the item
`max_size`	Y	Y	`Size<Dimension>`	16	-	The maximum height and width of the item
`aspect_ratio`	Y	3	`Option<f32>`	4	-	The preferred aspect ratio (calculated as width divided by height)
Item spacing
`padding`	Y	~Y	`Rect<LengthPercentage>`	32	-	How large should the padding be on each side?
`border`	Y	~Y	`Rect<LengthPercentage>`	32	-	How large should the border be on each side?
`margin`	Y	~Y	`Rect<LengthPercentageAuto>`	32	-	How large should the margin be on each side?
`gap`	Y	Y	`Size<LengthPercentage>`	16	-	The size of the vertical and horizontal gaps between flex items / grid rows
Alignment
`align_content`	Y	Y	`AlignContent`	2	-	How should content contained within this item be aligned relative to the cross axis?
`justify_content`	Y	Y	`AlignContent`	2	-	How should content contained within this item be aligned relative to the main axis?
`align_items`	Y	Y	`AlignItems`	2	-	How should items be aligned relative to the cross axis?
`align_self`	Y	Y	`Option<AlignItems>`	2	-	Should this item violate the cross axis alignment specified by its parent's [`AlignItems`]?
`justify_items`	-	Y	`AlignItems`	2	-	How should items be aligned relative to the main axis?
`justify_self`	-	Y	`Option<AlignItems>`	2	-	Should this item violate the main axis alignment specified by its parent's [`AlignItems`]?
Flexbox
`flex_direction`	Y	-	`FlexDirection`	1	-	Which direction does the main axis flow in?
`flex_wrap`	Y	-	`FlexWrap`	1	-	Should elements wrap, or stay in a single line?
`flex_basis`	Y	-	`Dimension`	8	-	Sets the initial main axis size of the item
`flex_grow`	Y	-	`f32`	4	-	The relative rate at which this item grows when it is expanding to fill space
`flex_shrink`	Y	-	`f32`	4	-	The relative rate at which this item shrinks when it is contracting to fit into space
CSS Grid (Container)
`grid_template_columns`	-	Y	`Vec<TrackSizingFunction>`	24	32 * N	The track sizing functions of the grid's explicit columns
`grid_template_rows`	-	Y	`Vec<TrackSizingFunction>`	24	32 * N	The track sizing functions of the grid's explicit rows
`grid_template_areas`	-	5	-	-	-	Defines named grid areas
`grid_auto_rows`	-	Y	`Vec<NonRepeatedTrackSizingFunction>`	24	20 * N	Track sizing functions for the grid's implicitly generated rows
`grid_auto_columns`	-	Y	`Vec<NonRepeatedTrackSizingFunction>`	24	20 * N	Track sizing functions for the grid's implicitly generated columns
`grid_auto_flow`	-	Y	`GridAutoFlow`	1	-	Whether auto-placed items are placed row-wise or column-wise. And sparsely or densely.
CSS Grid (Child)
`grid_row`	-	Y	`Line<GridPlacement>`	8	-	The vertical (row) placement of a grid item
`grid_column`	-	Y	`Line<GridPlacement>`	8	-	The horizontal (row) placement of a grid item
`grid_area`	-	5	-	-	-	Accepts either shorthand row/column-start/end or a named grid area

Safe and unsafe overflow alignment

AlignItems and AlignContent (and their aliases AlignSelf, JustifyItems, JustifySelf, JustifyContent) are structs with two orthogonal fields:

pub struct AlignContent {
    pub keyword: AlignContentKeyword,   // Start, End, FlexStart, FlexEnd, Center,
                                        // Stretch, SpaceBetween, SpaceEvenly, SpaceAround
    pub safety: AlignmentSafety,        // Safe | Unsafe
}

For ergonomics every CSS spelling is exposed as an associated constant — AlignContent::Start, AlignContent::SafeStart, AlignItems::SafeFlexEnd, etc. — so call sites read identically to the previous enum form.

The safety field corresponds to the spec's overflow-position keyword. When the alignment subject would overflow its alignment container, AlignmentSafety::Safe falls back to logical Start so the start edge of the content stays visible. AlignmentSafety::Unsafe (the default) keeps the requested alignment even when that causes overflow at the start edge.

The spec only defines safe/unsafe against the position keywords start, end, flex-start, flex-end, center. Combinations such as safe stretch, safe baseline, and safe space-between are rejected by the parser when the parse feature is enabled, and the compute pass treats them as Unsafe if a value somehow reaches it via manual struct construction.

Use the is_safe() method to check the safety modifier and keyword() to retrieve the bare position keyword. The safe/unsafe overflow-position keyword is supported by both the Flexbox and CSS Grid layout algorithms for both content-level (align-content, justify-content) and self-level (align-self, justify-self) alignment.