Update UI alignment docs (#10303)

# Objective

- Address inconsistent term usage in the docs for the alignment
properties for UI nodes. Fixes #10218
- `JustifyContent::Stretch` is missing despite being supported by Taffy,
being as the default value for Grids, so it should be added to Bevy as
well

## Solution

- Consistently provide links to the mdn site for the css equivalent
- Match (mostly) the documentation given on the pub struct and the
underlying enums
- Use the term `items` consistently to refer each child in the container
- Add `JustifyContent::Stretch` and map it to Taffy

## Migration Guide

- The `JustifyContents` enum has been expanded to include
`JustifyContents::Stretch`.
This commit is contained in:
CrumbsTrace 2023-10-29 16:32:11 +01:00 committed by GitHub
parent 0c2c52a0cd
commit e9a0d6ccc5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 81 additions and 51 deletions

View file

@ -218,6 +218,7 @@ impl From<JustifyContent> for Option<taffy::style::JustifyContent> {
JustifyContent::FlexStart => taffy::style::JustifyContent::FlexStart.into(),
JustifyContent::FlexEnd => taffy::style::JustifyContent::FlexEnd.into(),
JustifyContent::Center => taffy::style::JustifyContent::Center.into(),
JustifyContent::Stretch => taffy::style::JustifyContent::Stretch.into(),
JustifyContent::SpaceBetween => taffy::style::JustifyContent::SpaceBetween.into(),
JustifyContent::SpaceAround => taffy::style::JustifyContent::SpaceAround.into(),
JustifyContent::SpaceEvenly => taffy::style::JustifyContent::SpaceEvenly.into(),

View file

@ -216,7 +216,8 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio>
pub aspect_ratio: Option<f32>,
/// - For Flexbox containers, sets default cross-axis alignment of the child items.
/// Used to control how each individual item is aligned by default within the space they're given.
/// - For Flexbox containers, sets default cross axis alignment of the child items.
/// - For CSS Grid containers, controls block (vertical) axis alignment of children of this grid container within their grid areas.
///
/// This value is overridden if [`AlignSelf`] on the child node is set.
@ -224,7 +225,8 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-items>
pub align_items: AlignItems,
/// - For Flexbox containers, this property has no effect. See `justify_content` for main-axis alignment of flex items.
/// Used to control how each individual item is aligned by default within the space they're given.
/// - For Flexbox containers, this property has no effect. See `justify_content` for main axis alignment of flex items.
/// - For CSS Grid containers, sets default inline (horizontal) axis alignment of child items within their grid areas.
///
/// This value is overridden if [`JustifySelf`] on the child node is set.
@ -232,7 +234,8 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items>
pub justify_items: JustifyItems,
/// - For Flexbox items, controls cross-axis alignment of the item.
/// Used to control how the specified item is aligned within the space it's given.
/// - For Flexbox items, controls cross axis alignment of the item.
/// - For CSS Grid items, controls block (vertical) axis alignment of a grid item within its grid area.
///
/// If set to `Auto`, alignment is inherited from the value of [`AlignItems`] set on the parent node.
@ -240,7 +243,8 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-self>
pub align_self: AlignSelf,
/// - For Flexbox items, this property has no effect. See `justify_content` for main-axis alignment of flex items.
/// Used to control how the specified item is aligned within the space it's given.
/// - For Flexbox items, this property has no effect. See `justify_content` for main axis alignment of flex items.
/// - For CSS Grid items, controls inline (horizontal) axis alignment of a grid item within its grid area.
///
/// If set to `Auto`, alignment is inherited from the value of [`JustifyItems`] set on the parent node.
@ -248,12 +252,14 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-self>
pub justify_self: JustifySelf,
/// - For Flexbox containers, controls alignment of lines if flex_wrap is set to [`FlexWrap::Wrap`] and there are multiple lines of items.
/// Used to control how items are distributed.
/// - For Flexbox containers, controls alignment of lines if `flex_wrap` is set to [`FlexWrap::Wrap`] and there are multiple lines of items.
/// - For CSS Grid containers, controls alignment of grid rows.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-content>
pub align_content: AlignContent,
/// Used to control how items are distributed.
/// - For Flexbox containers, controls alignment of items in the main axis.
/// - For CSS Grid containers, controls alignment of grid columns.
///
@ -443,27 +449,31 @@ impl Default for Style {
}
}
/// How items are aligned according to the cross axis
/// Used to control how each individual item is aligned by default within the space they're given.
/// - For Flexbox containers, sets default cross axis alignment of the child items.
/// - For CSS Grid containers, controls block (vertical) axis alignment of children of this grid container within their grid areas.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-items>
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)]
pub enum AlignItems {
/// The items are packed in their default position as if no alignment was applied.
Default,
/// Items are packed towards the start of the axis.
/// The items are packed towards the start of the axis.
Start,
/// Items are packed towards the end of the axis.
/// The items are packed towards the end of the axis.
End,
/// Items are packed towards the start of the axis, unless the flex direction is reversed;
/// The items are packed towards the start of the axis, unless the flex direction is reversed;
/// then they are packed towards the end of the axis.
FlexStart,
/// Items are packed towards the end of the axis, unless the flex direction is reversed;
/// The items are packed towards the end of the axis, unless the flex direction is reversed;
/// then they are packed towards the start of the axis.
FlexEnd,
/// Items are aligned at the center.
/// The items are packed along the center of the axis.
Center,
/// Items are aligned at the baseline.
/// The items are packed such that their baselines align.
Baseline,
/// Items are stretched across the whole cross axis.
/// The items are stretched to fill the space they're given.
Stretch,
}
@ -477,21 +487,25 @@ impl Default for AlignItems {
}
}
/// How items are aligned according to the main axis
/// Used to control how each individual item is aligned by default within the space they're given.
/// - For Flexbox containers, this property has no effect. See `justify_content` for main axis alignment of flex items.
/// - For CSS Grid containers, sets default inline (horizontal) axis alignment of child items within their grid areas.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items>
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)]
pub enum JustifyItems {
/// The items are packed in their default position as if no alignment was applied.
Default,
/// Items are packed towards the start of the axis.
/// The items are packed towards the start of the axis.
Start,
/// Items are packed towards the end of the axis.
/// The items are packed towards the end of the axis.
End,
/// Items are aligned at the center.
/// The items are packed along the center of the axis
Center,
/// Items are aligned at the baseline.
/// The items are packed such that their baselines align.
Baseline,
/// Items are stretched across the whole main axis.
/// The items are stretched to fill the space they're given.
Stretch,
}
@ -505,8 +519,11 @@ impl Default for JustifyItems {
}
}
/// How this item is aligned according to the cross axis.
/// Overrides [`AlignItems`].
/// Used to control how the specified item is aligned within the space it's given.
/// - For Flexbox items, controls cross axis alignment of the item.
/// - For CSS Grid items, controls block (vertical) axis alignment of a grid item within its grid area.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-self>
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)]
pub enum AlignSelf {
@ -522,11 +539,11 @@ pub enum AlignSelf {
/// This item will be aligned with the end of the axis, unless the flex direction is reversed;
/// then it will be aligned with the start of the axis.
FlexEnd,
/// This item will be aligned at the center.
/// This item will be aligned along the center of the axis.
Center,
/// This item will be aligned at the baseline.
Baseline,
/// This item will be stretched across the whole cross axis.
/// This item will be stretched to fill the container.
Stretch,
}
@ -540,8 +557,11 @@ impl Default for AlignSelf {
}
}
/// How this item is aligned according to the main axis.
/// Overrides [`JustifyItems`].
/// Used to control how the specified item is aligned within the space it's given.
/// - For Flexbox items, this property has no effect. See `justify_content` for main axis alignment of flex items.
/// - For CSS Grid items, controls inline (horizontal) axis alignment of a grid item within its grid area.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-self>
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)]
pub enum JustifySelf {
@ -551,11 +571,11 @@ pub enum JustifySelf {
Start,
/// This item will be aligned with the end of the axis.
End,
/// This item will be aligned at the center.
/// This item will be aligned along the center of the axis.
Center,
/// This item will be aligned at the baseline.
Baseline,
/// This item will be stretched across the whole main axis.
/// This item will be stretched to fill the space it's given.
Stretch,
}
@ -569,34 +589,35 @@ impl Default for JustifySelf {
}
}
/// Defines how each line is aligned within the flexbox.
/// Used to control how items are distributed.
/// - For Flexbox containers, controls alignment of lines if `flex_wrap` is set to [`FlexWrap::Wrap`] and there are multiple lines of items.
/// - For CSS Grid containers, controls alignment of grid rows.
///
/// It only applies if [`FlexWrap::Wrap`] is present and if there are multiple lines of items.
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-content>
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)]
pub enum AlignContent {
/// The items are packed in their default position as if no alignment was applied.
Default,
/// Each line moves towards the start of the cross axis.
/// The items are packed towards the start of the axis.
Start,
/// Each line moves towards the end of the cross axis.
/// The items are packed towards the end of the axis.
End,
/// Each line moves towards the start of the cross axis, unless the flex direction is reversed; then the line moves towards the end of the cross axis.
/// The items are packed towards the start of the axis, unless the flex direction is reversed;
/// then the items are packed towards the end of the axis.
FlexStart,
/// Each line moves towards the end of the cross axis, unless the flex direction is reversed; then the line moves towards the start of the cross axis.
/// The items are packed towards the end of the axis, unless the flex direction is reversed;
/// then the items are packed towards the start of the axis.
FlexEnd,
/// Each line moves towards the center of the cross axis.
/// The items are packed along the center of the axis.
Center,
/// Each line will stretch to fill the remaining space.
/// The items are stretched to fill the container along the axis.
Stretch,
/// Each line fills the space it needs, putting the remaining space, if any,
/// between the lines.
/// The items are distributed such that the gap between any two items is equal.
SpaceBetween,
/// The gap between the first and last items is exactly the same as the gap between items.
/// The gaps are distributed evenly.
/// The items are distributed such that the gap between and around any two items is equal.
SpaceEvenly,
/// Each line fills the space it needs, putting the remaining space, if any,
/// around the lines.
/// The items are distributed such that the gap between and around any two items is equal, with half-size gaps on either end.
SpaceAround,
}
@ -610,28 +631,36 @@ impl Default for AlignContent {
}
}
/// Defines how items are aligned according to the main axis
/// Used to control how items are distributed.
/// - For Flexbox containers, controls alignment of items in the main axis.
/// - For CSS Grid containers, controls alignment of grid columns.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content>
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)]
pub enum JustifyContent {
/// The items are packed in their default position as if no alignment was applied.
Default,
/// Items are packed toward the start of the axis.
/// The items are packed towards the start of the axis.
Start,
/// Items are packed toward the end of the axis.
/// The items are packed towards the end of the axis.
End,
/// Pushed towards the start, unless the flex direction is reversed; then pushed towards the end.
/// The items are packed towards the start of the axis, unless the flex direction is reversed;
/// then the items are packed towards the end of the axis.
FlexStart,
/// Pushed towards the end, unless the flex direction is reversed; then pushed towards the start.
/// The items are packed towards the end of the axis, unless the flex direction is reversed;
/// then the items are packed towards the start of the axis.
FlexEnd,
/// Centered along the main axis.
/// The items are packed along the center of the axis.
Center,
/// Remaining space is distributed between the items.
/// The items are stretched to fill the container along the axis.
Stretch,
/// The items are distributed such that the gap between any two items is equal.
SpaceBetween,
/// Remaining space is distributed around the items.
SpaceAround,
/// Like [`JustifyContent::SpaceAround`] but with even spacing between items.
/// The items are distributed such that the gap between and around any two items is equal.
SpaceEvenly,
/// The items are distributed such that the gap between and around any two items is equal, with half-size gaps on either end.
SpaceAround,
}
impl JustifyContent {