From 066e3662460998ab9916d049ea0b381edd64930f Mon Sep 17 00:00:00 2001 From: Nick Gerleman Date: Tue, 12 Mar 2024 15:17:57 -0700 Subject: [PATCH] Fill out "About Yoga", "Laying out a Yoga tree" , and "Styling" (#1591) 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 --- website-next/docs/about-yoga.md | 8 +- website-next/docs/examples/_category_.json | 4 - .../docs/getting-started/laying-out-a-tree.md | 7 - .../getting-started/laying-out-a-tree.mdx | 178 ++++++++++++++++++ website-next/docs/getting-started/styling.md | 7 - website-next/docs/img/wireframe-example.svg | 105 +++++++++++ website-next/docs/styling/_category_.json | 4 + .../{examples => styling}/align-content.mdx | 2 +- .../align-items-self.mdx | 2 +- .../{examples => styling}/aspect-ratio.mdx | 0 .../docs/{examples => styling}/display.mdx | 0 .../flex-basis-grow-shrink.mdx | 0 .../{examples => styling}/flex-direction.mdx | 8 +- .../docs/{examples => styling}/flex-wrap.mdx | 2 +- .../docs/{examples => styling}/gap.mdx | 0 website-next/docs/styling/index.md | 43 +++++ .../{examples => styling}/justify-content.mdx | 0 .../layout-direction.mdx | 0 .../margin-padding-border.mdx | 0 .../min-max-width-height.mdx | 0 .../docs/{examples => styling}/position.mdx | 0 .../{examples => styling}/width-height.mdx | 0 website-next/docusaurus.config.js | 2 +- 23 files changed, 345 insertions(+), 27 deletions(-) delete mode 100644 website-next/docs/examples/_category_.json delete mode 100644 website-next/docs/getting-started/laying-out-a-tree.md create mode 100644 website-next/docs/getting-started/laying-out-a-tree.mdx delete mode 100644 website-next/docs/getting-started/styling.md create mode 100644 website-next/docs/img/wireframe-example.svg create mode 100644 website-next/docs/styling/_category_.json rename website-next/docs/{examples => styling}/align-content.mdx (97%) rename website-next/docs/{examples => styling}/align-items-self.mdx (93%) rename website-next/docs/{examples => styling}/aspect-ratio.mdx (100%) rename website-next/docs/{examples => styling}/display.mdx (100%) rename website-next/docs/{examples => styling}/flex-basis-grow-shrink.mdx (100%) rename website-next/docs/{examples => styling}/flex-direction.mdx (87%) rename website-next/docs/{examples => styling}/flex-wrap.mdx (91%) rename website-next/docs/{examples => styling}/gap.mdx (100%) create mode 100644 website-next/docs/styling/index.md rename website-next/docs/{examples => styling}/justify-content.mdx (100%) rename website-next/docs/{examples => styling}/layout-direction.mdx (100%) rename website-next/docs/{examples => styling}/margin-padding-border.mdx (100%) rename website-next/docs/{examples => styling}/min-max-width-height.mdx (100%) rename website-next/docs/{examples => styling}/position.mdx (100%) rename website-next/docs/{examples => styling}/width-height.mdx (100%) diff --git a/website-next/docs/about-yoga.md b/website-next/docs/about-yoga.md index a335a363..391d9a42 100644 --- a/website-next/docs/about-yoga.md +++ b/website-next/docs/about-yoga.md @@ -4,4 +4,10 @@ sidebar_position: 1 # About Yoga -Fill this section in with high-level information about Yoga and its goals. E.g. constraints in, boxes out, not a UI framework. +Yoga is an embeddable layout system used in popular UI frameworks like React Native. Yoga itself is not a UI framework, and does not do any drawing itself. Yoga's only responsibility is determining the size and position of boxes. + +![layout wireframe](./img/wireframe-example.svg) + +Yoga supports a familiar subset of CSS, mostly focused on Flexbox. This gives users a familiar model, and enables sharing code between native platforms and the browser. + +Yoga is written in C++, with a public C API. This allows Yoga to be used by a wide variety of languages, via both offficial and unofficial bindings. diff --git a/website-next/docs/examples/_category_.json b/website-next/docs/examples/_category_.json deleted file mode 100644 index 493215de..00000000 --- a/website-next/docs/examples/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Examples", - "position": 4 -} diff --git a/website-next/docs/getting-started/laying-out-a-tree.md b/website-next/docs/getting-started/laying-out-a-tree.md deleted file mode 100644 index 1d78d311..00000000 --- a/website-next/docs/getting-started/laying-out-a-tree.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Laying out a Yoga tree - -Introduction which covers basic APIs for creating then laying out a Yoga tree, then reading the layout output. diff --git a/website-next/docs/getting-started/laying-out-a-tree.mdx b/website-next/docs/getting-started/laying-out-a-tree.mdx new file mode 100644 index 00000000..b6f7bab2 --- /dev/null +++ b/website-next/docs/getting-started/laying-out-a-tree.mdx @@ -0,0 +1,178 @@ +--- +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Laying out a Yoga tree + +Each box in Yoga is represented as a **Yoga Node**. These nodes form a tree which is used to store both input styles, and output layout results. + +## Building a Yoga tree + +Yoga nodes may be created, styled, and linked together. See [Styling](../styling/) for a more comprehensive reference of how to style a Yoga Node. + + + + + +```cpp +#include + +YGNodeRef root = YGNodeNew(); +YGNodeStyleSetFlexDirection(root, YGFlexDirectionRow); +YGNodeStyleSetWidth(root, 100.0f); +YGNodeStyleSetHeight(root, 100.0f); + +YGNodeRef child0 = YGNodeNew(); +YGNodeStyleSetFlexGrow(child0, 1.0f); +YGNodeStyleSetMargin(child0, YGEdgeRight, 10.0f); +YGNodeInsertChild(root, child0, 0.0f); + +YGNodeRef child1 = YGNodeNew(); +YGNodeStyleSetFlexGrow(child1, 1.0f); +YGNodeInsertChild(root, child1, 1.0f); +``` + +:::warning + +Yoga Nodes are not freed automatically and should be discarded when no longer needed. Individual nodes may be freed by calling `YGNodeFree(node)`, or an entire Yoga tree may be freed by calling `YGNodeFreeRecursive(node)`. + +::: + + + + + +```java +import com.facebook.yoga.YogaEdge; +import com.facebook.yoga.YogaFlexDirection; +import com.facebook.yoga.YogaNode; +import com.facebook.yoga.YogaNodeFactory; +import com.facebook.yoga.YogaPositionType; + +YogaNode root = YogaNodeFactory.create(); +root.setFlexDirection(YogaFlexDirection.ROW); +root.setWidth(100.0f); +root.setHeight(100.0f); + +YogaNode child0 = YogaNodeFactory.create(); +child0.setFlexGrow(1.0f); +child0.setMargin(YogaEdge.Right, 10.0f); +root.addChildAt(child0, 0.0f); + +YogaNode child1 = YogaNodeFactory.create(); +child1.setFlexGrow(1.0f); +root.addChildAt(child1, 1.0f); +``` + +:::info + +Java backed Yoga Nodes are garbage collected, and do not need to manually be freed. + +::: + + + + + +```ts +import Yoga, {Edge, FlexDirection, PositionType} from 'yoga-layout'; + +const root = Yoga.Node.create(); +root.setFlexDirection(FlexDirection.Row); +root.setWidth(100); +root.setHeight(100); + +const child0 = Yoga.Node.create(); +child0.setFlexGrow(1); +child0.setMargin(Edge.Right, 10); +root.insertChild(child0, 0); + +const child1 = Yoga.Node.create(); +child1.setFlexGrow(1); +root.insertChild(child1, 1); +``` + +:::warning + +Yoga Nodes are not freed automatically and should be discarded when no longer needed. Individual nodes may be freed by calling `node.free()`, or an entire Yoga tree may be freed by calling `node.freeRecursive()`. + +A future revision of JavaScript bindings for Yoga may move to garbage collection to remove this requirement. + +::: + + + + +## Laying out the tree + +The full tree of Yoga nodes is laid out all at once. This layout may be constrained to a passed `availableWidth` and `availableHeight`, or may be allowed to expand infinitely in a given axis by passing Undefined. + + + + + +```cpp +YGNodeCalculateLayout(root, YGUndefined, YGUndefined, YGDirectionLTR); +``` + + + + + +```java +root.calculateLayout(YogaConstants.UNDEFINED, YogaConstants.UNDEFINED); +``` + +:::info + +A tree of Java Yoga nodes may be laid out in RTL by setting the `direction` of the root node. + +::: + + + + + +```ts +root.calculateLayout(undefined, undefined, Direction.LTR); +``` + + + + +## Reading layout results + +Layout results are now written to each Yoga node. This includes an offset relative to the node's parent, along with dimensions, and the resolved values for margin, border, and padding for each physical edge. + + + + + +```cpp +float left = YGNodeLayoutGetLeft(child0); +float height = YGNodeLayoutGetHeight(child0); +``` + + + + + +```java +float left = child0.getLayoutX(); +float height = child0.getLayoutHeight(); +``` + + + + + +```ts +const left = child0.getComputedLeft(); +const height = child0.getComputedHeight(); +``` + + + diff --git a/website-next/docs/getting-started/styling.md b/website-next/docs/getting-started/styling.md deleted file mode 100644 index a9cc7de3..00000000 --- a/website-next/docs/getting-started/styling.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Styling - -Talk about setting Yoga styles, units, logical edges, any quirks/invalidation, style defaults. diff --git a/website-next/docs/img/wireframe-example.svg b/website-next/docs/img/wireframe-example.svg new file mode 100644 index 00000000..01c44c58 --- /dev/null +++ b/website-next/docs/img/wireframe-example.svg @@ -0,0 +1,105 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/website-next/docs/styling/_category_.json b/website-next/docs/styling/_category_.json new file mode 100644 index 00000000..b48b6c41 --- /dev/null +++ b/website-next/docs/styling/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Styling", + "position": 4 +} diff --git a/website-next/docs/examples/align-content.mdx b/website-next/docs/styling/align-content.mdx similarity index 97% rename from website-next/docs/examples/align-content.mdx rename to website-next/docs/styling/align-content.mdx index e3e8c211..fb315ade 100644 --- a/website-next/docs/examples/align-content.mdx +++ b/website-next/docs/styling/align-content.mdx @@ -7,7 +7,7 @@ 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/examples/flex-wrap). +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. diff --git a/website-next/docs/examples/align-items-self.mdx b/website-next/docs/styling/align-items-self.mdx similarity index 93% rename from website-next/docs/examples/align-items-self.mdx rename to website-next/docs/styling/align-items-self.mdx index 53e3b183..6c8c7e3e 100644 --- a/website-next/docs/examples/align-items-self.mdx +++ b/website-next/docs/styling/align-items-self.mdx @@ -7,7 +7,7 @@ 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/examples/justify-content) but instead of +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. diff --git a/website-next/docs/examples/aspect-ratio.mdx b/website-next/docs/styling/aspect-ratio.mdx similarity index 100% rename from website-next/docs/examples/aspect-ratio.mdx rename to website-next/docs/styling/aspect-ratio.mdx diff --git a/website-next/docs/examples/display.mdx b/website-next/docs/styling/display.mdx similarity index 100% rename from website-next/docs/examples/display.mdx rename to website-next/docs/styling/display.mdx diff --git a/website-next/docs/examples/flex-basis-grow-shrink.mdx b/website-next/docs/styling/flex-basis-grow-shrink.mdx similarity index 100% rename from website-next/docs/examples/flex-basis-grow-shrink.mdx rename to website-next/docs/styling/flex-basis-grow-shrink.mdx diff --git a/website-next/docs/examples/flex-direction.mdx b/website-next/docs/styling/flex-direction.mdx similarity index 87% rename from website-next/docs/examples/flex-direction.mdx rename to website-next/docs/styling/flex-direction.mdx index f8223299..fec3dc24 100644 --- a/website-next/docs/examples/flex-direction.mdx +++ b/website-next/docs/styling/flex-direction.mdx @@ -11,16 +11,16 @@ 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/examples/flex-wrap) is enabled then +**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/examples/flex-wrap) is enabled then +**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/examples/flex-wrap) is enabled then +**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/examples/flex-wrap) is enabled then +**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. diff --git a/website-next/docs/examples/flex-wrap.mdx b/website-next/docs/styling/flex-wrap.mdx similarity index 91% rename from website-next/docs/examples/flex-wrap.mdx rename to website-next/docs/styling/flex-wrap.mdx index 96a728a7..aa93e023 100644 --- a/website-next/docs/examples/flex-wrap.mdx +++ b/website-next/docs/styling/flex-wrap.mdx @@ -8,7 +8,7 @@ import Playground from '@site/src/components/Playground'; 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/examples/align-content) can be used to specify how the +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. diff --git a/website-next/docs/examples/gap.mdx b/website-next/docs/styling/gap.mdx similarity index 100% rename from website-next/docs/examples/gap.mdx rename to website-next/docs/styling/gap.mdx diff --git a/website-next/docs/styling/index.md b/website-next/docs/styling/index.md new file mode 100644 index 00000000..3e5f478e --- /dev/null +++ b/website-next/docs/styling/index.md @@ -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. diff --git a/website-next/docs/examples/justify-content.mdx b/website-next/docs/styling/justify-content.mdx similarity index 100% rename from website-next/docs/examples/justify-content.mdx rename to website-next/docs/styling/justify-content.mdx diff --git a/website-next/docs/examples/layout-direction.mdx b/website-next/docs/styling/layout-direction.mdx similarity index 100% rename from website-next/docs/examples/layout-direction.mdx rename to website-next/docs/styling/layout-direction.mdx diff --git a/website-next/docs/examples/margin-padding-border.mdx b/website-next/docs/styling/margin-padding-border.mdx similarity index 100% rename from website-next/docs/examples/margin-padding-border.mdx rename to website-next/docs/styling/margin-padding-border.mdx diff --git a/website-next/docs/examples/min-max-width-height.mdx b/website-next/docs/styling/min-max-width-height.mdx similarity index 100% rename from website-next/docs/examples/min-max-width-height.mdx rename to website-next/docs/styling/min-max-width-height.mdx diff --git a/website-next/docs/examples/position.mdx b/website-next/docs/styling/position.mdx similarity index 100% rename from website-next/docs/examples/position.mdx rename to website-next/docs/styling/position.mdx diff --git a/website-next/docs/examples/width-height.mdx b/website-next/docs/styling/width-height.mdx similarity index 100% rename from website-next/docs/examples/width-height.mdx rename to website-next/docs/styling/width-height.mdx diff --git a/website-next/docusaurus.config.js b/website-next/docusaurus.config.js index 97b74b7f..57d6e725 100644 --- a/website-next/docusaurus.config.js +++ b/website-next/docusaurus.config.js @@ -102,7 +102,7 @@ export default { }, { label: 'Examples', - to: '/docs/examples/align-content', + to: '/docs/styling/align-content', }, ], },