DaddyFrosty/yoga
1
0
Fork 0
Code Issues 96 Pull Requests 31 Actions Packages Projects Releases 33 Wiki Activity

Fill out "About Yoga", "Laying out a Yoga tree" , and "Styling" (#1591)

Browse Source 
Summary:
Pull Request resolved: https://github.com/facebook/yoga/pull/1591

Adds initial documentation to these sections.

Reviewed By: joevilches

Differential Revision: D54708141

fbshipit-source-id: b2c1ac20573840833a3e5fde8c7b53f2770cecbd
This commit is contained in:
Nick Gerleman
2024-03-12 15:17:57 -07:00
committed by Facebook GitHub Bot
parent a0a09b4570
commit 066e366246
23 changed files with 345 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
website-next/docs/styling/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Styling",
"position": 4
}

42
website-next/docs/styling/align-content.mdx Normal file
View File

@@ -0,0 +1,42 @@
---
sidebar_position: 1
---
import Playground from '@site/src/components/Playground';
# Align Content
Align content defines the distribution of lines along the cross-axis. This only
has effect when items are wrapped to multiple lines using [`flex wrap`](/docs/styling/flex-wrap).
**Flex start (default)**: Align wrapped lines to the start of the container's cross axis.
**Flex end**: Align wrapped lines to the end of the container's cross axis.
**Stretch**: Stretch wrapped lines to match the `height` of the container's cross axis.
**Center**: Align wrapped lines in the center of the container's cross axis.
**Space between**: Evenly space wrapped lines across the container's main axis, distributing
remaining space between the lines.
**Space around**: Evenly space wrapped lines across the container's main axis, distributing
remaining space around the lines. Compared to `space between` using
`space around` will result in space being distributed to the begining of
the first lines and end of the last line.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 250,
height: 250,
padding: 10,
alignContent: 'flex-start',
flexWrap: 'wrap'
}}>
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
</Node>
</Layout>`} />

47
website-next/docs/styling/align-items-self.mdx Normal file
View File

@@ -0,0 +1,47 @@
---
sidebar_position: 2
---
import Playground from '@site/src/components/Playground';
# Align Items
Align items describes how to align children along the cross axis of their container.
Align items is very similar to [`justify content`](/docs/styling/justify-content) but instead of
applying to the main axis, `align items` applies to the cross axis.
**Stretch (default)**: Stretch children of a container to match the `height` of the container's cross axis.
**Flex start**: Align children of a container to the start of the container's cross axis.
**Flex end**: Align children of a container to the end of the container's cross axis.
**Center**: Align children of a container in the center of the container's cross axis.
**Baseline**: Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.
# Align Self
Align self has the same options and effect as `align items` but instead of
affecting the children within a container, you can apply this property to
a single child to change its alignment within its parent. `align self`
overrides any option set by the parent with `align items`.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 250,
height: 250,
padding: 10,
alignItems: 'flex-start'
}}>
<Node
style={{
margin: 5,
height: 50,
width: 50,
alignSelf: 'center'
}}/>
<Node style={{margin: 5, height: 50, width: 50}} />
</Node>
</Layout>`} />

27
website-next/docs/styling/aspect-ratio.mdx Normal file
View File

@@ -0,0 +1,27 @@
---
sidebar_position: 3
---
import Playground from '@site/src/components/Playground';
# Aspect Ratio
The `aspect ratio` property in Yoga has the following properties:
- Accepts any floating point value > 0, the default is undefined.
- Defined as the ratio between the `width` and the `height` of a node e.g. if a node has an aspect ratio of 2 then its `width` is twice the size of its `height`.
- Respects the `min` and `max` dimensions of an item.
- Has higher priority than `flex grow`
- If `aspect ratio`, `width`, and `height` are set then the cross axis dimension is overridden.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
}}>
<Node style={{margin: 5, height: 50, aspectRatio: 1.0}} />
<Node style={{margin: 5, height: 50, aspectRatio: 1.5}} />
</Node>
</Layout>`} />

25
website-next/docs/styling/display.mdx Normal file
View File

@@ -0,0 +1,25 @@
---
sidebar_position: 4
---
import Playground from '@site/src/components/Playground';
# Display
Display controls which layout specification to follow.
**Flex (default)**: The CSS Flexible Box Model specification.
**None**: The node is removed from the layout tree and will not be visible.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
}}>
<Node style={{margin: 5, height: 50, display: 'flex'}} />
<Node style={{margin: 5, height: 50, display: 'none'}} />
</Node>
</Layout>`} />

65
website-next/docs/styling/flex-basis-grow-shrink.mdx Normal file
View File

@@ -0,0 +1,65 @@
---
sidebar_position: 5
---
import Playground from '@site/src/components/Playground';
# Flex Basis, Grow, and Shrink
**Flex basis**: is an axis-independent way of providing the default size of an item
along the main axis. Setting the flex basis of a child is similar to setting the `width` of that
child if its parent is a container with `flex direction: row` or setting the `height` of a child
if its parent is a container with `flex direction: column`. The flex basis of an item is the
default size of that item, the size of the item before any flex grow and flex shrink
calculations are performed.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
}}>
<Node style={{margin: 5, flexBasis: 50}} />
</Node>
</Layout>`} />
**Flex grow**: describes how any space within a container should be distributed
among its children along the main axis. After laying out its children, a container will
distribute any remaining space according to the flex grow values specified by its children.
Flex grow accepts any floating point value >= 0, with 0 being the default value.
A container will distribute any remaining space among its children weighted by the child’s flex grow value.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
}}>
<Node style={{margin: 5, flexGrow: 0.25}} />
<Node style={{margin: 5, flexGrow: 0.75}} />
</Node>
</Layout>`} />
**Flex shrink**: describes how to shrink children along the main axis in the
case that the total size of the children overflow the size of the container on the main axis.
flex shrink is very similar to flex grow and can be thought of in the same way if
any overflowing size is considered to be negative remaining space.
These two properties also work well together by allowing children to grow and shrink as needed.
Flex shrink accepts any floating point value >= 0, with 1 being the default value.
A container will shrink its children weighted by the child’s flex shrink value.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
}}>
<Node style={{margin: 5, flexShrink: 5, height: 150}} />
<Node style={{margin: 5, flexShrink: 10, height: 150}} />
</Node>
</Layout>`} />

37
website-next/docs/styling/flex-direction.mdx Normal file
View File

@@ -0,0 +1,37 @@
---
sidebar_position: 6
---
import Playground from '@site/src/components/Playground';
# Flex Direction
Flex direction controls the direction in which children of a node are laid out.
This is also referred to as the main axis. The main axis is the direction in
which children are laid out. The cross axis is the axis perpendicular to the
main axis, or the axis which wrapping lines are laid out in.
**Column (default)**: Align children from top to bottom. If [wrapping](/docs/styling/flex-wrap) is enabled then
the next line will start to the left first item on the top of the container.
**Row**: Align children from left to right. If [wrapping](/docs/styling/flex-wrap) is enabled then
the next line will start under the first item on the left of the container.
**Row reverse**: Align children from right to left. If [wrapping](/docs/styling/flex-wrap) is enabled then
the next line will start under the first item on the right of the container.
**Column reverse**: Align children from bottom to top. If [wrapping](/docs/styling/flex-wrap) is enabled then
the next line will start to the left first item on the bottom of the container.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
flexDirection: 'column'
}}>
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
</Node>
</Layout>`} />

33
website-next/docs/styling/flex-wrap.mdx Normal file
View File

@@ -0,0 +1,33 @@
---
sidebar_position: 7
---
import Playground from '@site/src/components/Playground';
# Flex Wrap
The `flex wrap` property is set on containers and controls what happens when
children overflow the size of the container along the main axis. By default
children are forced into a single line (which can shrink nodes). When wrapping lines [`align content`](/docs/styling/align-content) can be used to specify how the
lines are placed in the container.
**No wrap (default)**: No wrapping and children might shrink as a result.
**Wrap**: Nodes are wrapped into multiple lines along the main axis if needed.
**Wrap reverse**: Behaves the same as `wrap` but the order of the lines is reversed.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 250,
height: 250,
padding: 10,
flexWrap: 'wrap'
}}>
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
</Node>
</Layout>`} />

5
website-next/docs/styling/gap.mdx Normal file
View File

@@ -0,0 +1,5 @@
---
sidebar_position: 8
---
# Gap

43
website-next/docs/styling/index.md Normal file
View File

@@ -0,0 +1,43 @@
---
sidebar_position: 2
---
# Styling
Each Yoga node has an associated style. Nodes may be styled using similar properties to CSS, with some caveats.
## Default styles
The default Yoga node style is similar to a box on web set to `display: flex`, with a few notable exceptions:
1. `flex-direction` defaults to `column` instead of `row`
2. `align-content` defaults to `flex-start` instead of `stretch`
3. `flex-shrink` defaults to `0` instead of `1`
4. `position` defaults to `relative` instead of `static`
Yoga may be [configured](../getting-started/configuring-yoga.md) to align to the defaults on web for `flex-direction`, `align-content`, and `flex-shrink` by setting the `UseWebDefaults` flag.
:::warning
Because `UseWebDefaults` was established before the introduction of `position: 'static'`, it does not change the default `position`, in order to preserve compatibility.
:::
## Edges
Margin, padding, position, and border, are set against an Edge, which may be:
1. Relative to writing direction (start/end)
2. A physical edge (top/right/left/bottom)
3. A collection of edges (vertical/horizontal/all)
A style value may be set against multiple Edge values at once, with precedence given in the above order.
## Units
Yoga does not operate on CSS units like `px` or `em`. Yoga instead works on "points", representing an arbitrary, canonical absolute unit (usually mapped to display independent pixels), along with percentage. Other units should be absolutized before being given to Yoga.
## Non-standard properties
Yoga's `aspect-ratio` property was added before the same property was added to CSS, and may act subtlety different. These differences may be reconciled in a future version of Yoga.
Yoga's `flex` shorthand will act as `flex-grow` if positive, or `flex-shrink` if negative.

43
website-next/docs/styling/justify-content.mdx Normal file
View File

@@ -0,0 +1,43 @@
---
sidebar_position: 9
---
import Playground from '@site/src/components/Playground';
# Justify Content
Justify content describes how to align children within the main axis of their container.
For example, you can use this property to center a child horizontally within a container
with `flex direction` set to `row` or vertically within a container with `flex direction`
set to `column`.
**Flex start (default)**: Align children of a container to the start of the container's main axis.
**Flex end**: Align children of a container to the end of the container's main axis.
**Center**: Align children of a container in the center of the container's main axis.
**Space between**: Evenly space of children across the container's main axis, distributing
remaining space between the children.
**Space around**: Evenly space of children across the container's main axis, distributing
remaining space around the children. Compared to `space between` using
`space around` will result in space being distributed to the beginning of
the first child and end of the last child.
**Space evenly**: Evenly distributed within the alignment container along the main axis.
The spacing between each pair of adjacent items, the main-start edge and the first item,
and the main-end edge and the last item, are all exactly the same.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
justifyContent: 'flex-start'
}}>
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
</Node>
</Layout>`} />

34
website-next/docs/styling/layout-direction.mdx Normal file
View File

@@ -0,0 +1,34 @@
---
sidebar_position: 10
---
import Playground from '@site/src/components/Playground';
# Layout Direction
Layout direction specifies the direction in which children and text
in a hierarchy should be laid out. Layout direction also effects what
edge `start` and `end` refer to. By default Yoga lays out with `LTR`
layout direction. In this mode `start` refers to `left` and `end`
refers to `right`. When localizing your apps for markets with RTL languages
you should customize this by either by passing a direction
to the `CalculateLayout` call or by setting the direction on the root node.
**LTR (default)**: Text and children and laid out from left to right. Styles applied
the start of an element are applied on the left side.
**RTL**: Text and children and laid out from right to left. Styles applied the
start of an element are applied on the right side.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
direction: 'ltr'
}}>
<Node style={{margin: 5, height: 50, width: 50}} />
<Node style={{margin: 5, height: 50, width: 50}} />
</Node>
</Layout>`} />

40
website-next/docs/styling/margin-padding-border.mdx Normal file
View File

@@ -0,0 +1,40 @@
---
sidebar_position: 11
---
import Playground from '@site/src/components/Playground';
# Margin, Padding, and Border
**Margin**: affects the spacing around the outside of a node. A node with margin
will offset itself from the bounds of its parent but also offset the
location of any siblings. The margin of a node contributes to the total size
of its parent if the parent is auto sized.
**Padding**: affects the size of the node it is applied to. Padding in Yoga acts as if
`box-sizing: border-box;` was set. That is padding will not add to the total size
of an element if it has an explicit size set. For auto sized nodes padding will increase
the size of the node as well as offset the location of any children.
**Border**: in Yoga acts exactly like padding and only exists as a seperate property so
that higher level frameworks get a hint as to how thick to draw a border. Yoga however
does not do any drawing so just uses this information during layout where border
acts exactly like padding.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10,
}}>
<Node
style={{
margin: 5,
padding: 20,
borderWidth: 20,
height: 50
}}/>
<Node style={{height: 50}} />
</Node>
</Layout>`} />

48
website-next/docs/styling/min-max-width-height.mdx Normal file
View File

@@ -0,0 +1,48 @@
---
sidebar_position: 12
---
import Playground from '@site/src/components/Playground';
# Min/Max Width and Height
These properties set the maximum and minimum size constraints of an element.
They have higher priority than all other properties and will always be respected.
Constraints can be specified as either absolute pixel values or as percentages of their
parent's size. By default all these constraints are `undefined`.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 250,
height: 250,
padding: 10
}}>
<Node style={{margin: 5, height: 25}} />
<Node
style={{
margin: 5,
height: 100,
maxHeight: 25
}}/>
<Node
style={{
margin: 5,
height: 25,
minHeight: 50
}}/>
<Node
style={{
margin: 5,
height: 25,
maxWidth: 25
}}/>
<Node
style={{
margin: 5,
height: 25,
width: 25,
minWidth: 50
}}/>
</Node>
</Layout>`} />

36
website-next/docs/styling/position.mdx Normal file
View File

@@ -0,0 +1,36 @@
---
sidebar_position: 11
---
import Playground from '@site/src/components/Playground';
# Position
**Relative (default)**: This node is laid out according to the specified flow of the flex container it is apart of.
That is, it particpates in the flexbox algorithm and will take up space within the container, unlike `absolute`.
Insets (`left`, `right`, `top`, `bottom`, etc) will offset the node from its normal position within its container.
This node will always form a [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).
**Absolute**: This node is removed from the specified flow of the flex container it is apart of.
Absolute nodes do not take up space in its flex container and will not affect the position of
its siblings. Insets will offset the node from its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).
**Static**: This node behaves like `relative` except it will ignore insets and will not
form a [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10
}}>
<Node
style={{
margin: 5,
height: 50,
position: 'relative'
}}/>
</Node>
</Layout>`} />

36
website-next/docs/styling/width-height.mdx Normal file
View File

@@ -0,0 +1,36 @@
---
sidebar_position: 14
---
import Playground from '@site/src/components/Playground';
# Width and Height
The `width` property specifies the width of the node's border box (the collective size of the node's content, padding, and border).
Similarly `height` property specifies the height of the node's border box.
Both `width` and `height` can take following values:
**Auto**: The default Value, Yoga calculates the width/height for the node based
on its content, whether that is other children, text, or an image.
**Pixels**: Defines the width/height in absolute pixels. Depending on other properties set on
the Yoga node this may or may not be the final dimension of the node.
**Percentage**: Defines the width or height in percentage of its [containing block's](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block) width or height respectively.
<Playground code={`<Layout config={{useWebDefaults: false}}>
<Node
style={{
width: 200,
height: 200,
padding: 10
}}>
<Node
style={{
margin: 5,
height: 50,
width: 50,
}}/>
</Node>
</Layout>`} />