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

@@ -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.

website-next/docs/examples/_category_.json

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

website-next/docs/getting-started/laying-out-a-tree.md

@@ -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.

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.
+
+<Tabs groupId="language">
+
+<TabItem value="cpp" label="C/C++">
+
+```cpp
+#include <yoga/Yoga.h>
+
+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)`.
+
+:::
+
+</TabItem>
+
+<TabItem value="java" label="Java">
+
+```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.
+
+:::
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```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.
+
+:::
+
+</TabItem>
+</Tabs>
+
+## 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.
+
+<Tabs groupId="language">
+
+<TabItem value="cpp" label="C/C++">
+
+```cpp
+YGNodeCalculateLayout(root, YGUndefined, YGUndefined, YGDirectionLTR);
+```
+
+</TabItem>
+
+<TabItem value="java" label="Java">
+
+```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.
+
+:::
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```ts
+root.calculateLayout(undefined, undefined, Direction.LTR);
+```
+
+</TabItem>
+</Tabs>
+
+## 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.
+
+<Tabs groupId="language">
+
+<TabItem value="cpp" label="C/C++">
+
+```cpp
+float left = YGNodeLayoutGetLeft(child0);
+float height = YGNodeLayoutGetHeight(child0);
+```
+
+</TabItem>
+
+<TabItem value="java" label="Java">
+
+```java
+float left = child0.getLayoutX();
+float height = child0.getLayoutHeight();
+```
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```ts
+const left = child0.getComputedLeft();
+const height = child0.getComputedHeight();
+```
+
+</TabItem>
+</Tabs>

website-next/docs/getting-started/styling.md

@@ -1,7 +0,0 @@
----
-sidebar_position: 3
----
-
-# Styling
-
-Talk about setting Yoga styles, units, logical edges, any quirks/invalidation, style defaults.

website-next/docs/styling/_category_.json

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

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.
 

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.

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.
 
 <Playground code={`<Layout config={{useWebDefaults: false}}>

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.

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.

website-next/docusaurus.config.js

@@ -102,7 +102,7 @@ export default {
               },
               {
                 label: 'Examples',
-                to: '/docs/examples/align-content',
+                to: '/docs/styling/align-content',
               },
             ],
           },