From 20e05881a8cd0a77adae1f4860fca9926e20eb41 Mon Sep 17 00:00:00 2001
From: Joe Vilches <joevilches@meta.com>
Date: Wed, 13 Mar 2024 14:07:44 -0700
Subject: [PATCH] Add insets documentation (#1618)

Summary:
Pull Request resolved: https://github.com/facebook/yoga/pull/1618

tsia

Reviewed By: NickGerleman

Differential Revision: D54830359

fbshipit-source-id: 999a7fa3659b41ae532dd00e5df739e91f23905b
---
 website-next/docs/styling/insets.mdx   | 62 ++++++++++++++++++++++++++
 website-next/docs/styling/position.mdx |  6 +--
 2 files changed, 65 insertions(+), 3 deletions(-)
 create mode 100644 website-next/docs/styling/insets.mdx

diff --git a/website-next/docs/styling/insets.mdx b/website-next/docs/styling/insets.mdx
new file mode 100644
index 00000000..266a68fe
--- /dev/null
+++ b/website-next/docs/styling/insets.mdx
@@ -0,0 +1,62 @@
+---
+sidebar_position: 8.5
+---
+
+import Playground from '@site/src/components/Playground';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Insets
+
+Insets refer to the position property that you can assign to an edge
+(not to be confused with [position type](/docs/styling/position)) using one of the following
+APIs:
+<Tabs groupId="language">
+<TabItem value="cpp" label="C/C++">
+```cpp
+YGNodeStyleSetPosition(node, edge, position);
+```
+</TabItem>
+<TabItem value="java" label="Java">
+```java
+node.setPosition(edge, position);
+```
+</TabItem>
+<TabItem value="ts" label="Typescript">
+```typescript
+node.setPosition(edge, position);
+```
+</TabItem>
+</Tabs>
+This property will offset the node in a specific way depending on
+what [position type](/docs/styling/position) the node has.
+
+* If the node is static then insets have no effect.
+* If the node is relative then insets will move the node the designated amount
+from where the node would normally be in the container. Each inset property
+is relative to the node's corresponding physical edge. So `YGNodeStyleSetPosition(node, YGEdgeRight, 10.0f)` will offset the node
+so that the right edge is 10 units away from where the right edge would be originally.
+* If the node is aboslute then insets will move the node the designated amount away from
+the node's [containing block](/docs/advanced/containing-block). So `YGNodeStyleSetPosition(node, YGEdgeRight, 10.0f)`
+will offset the node so that the right edge is 10 units away from the [containing block's](/docs/advanced/containing-block)
+right edge.
+
+In the event that a node has a fixed size and opposite insets are defined
+(e.g. a value assigned to the right edge and left edge) then the left and top edge will have priority.
+
+<Playground code={`<Layout config={{useWebDefaults: false}}>
+  <Node
+    style={{
+      width: 200,
+      height: 200,
+    }}>
+    <Node
+      style={{
+        height: 50,
+        width: 50,
+        top: 50,
+        left: 50,
+      }}
+    />
+  </Node>
+</Layout>`} />
diff --git a/website-next/docs/styling/position.mdx b/website-next/docs/styling/position.mdx
index 75adcfec..fdcd2e4b 100644
--- a/website-next/docs/styling/position.mdx
+++ b/website-next/docs/styling/position.mdx
@@ -8,14 +8,14 @@ import Playground from '@site/src/components/Playground';
 
 **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.
+[Insets](/docs/styling/insets) will offset the node from its normal position within its container.
 This node will always form a [containing block](/docs/advanced/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](/docs/advanced/containing-block).
+its siblings. [Insets](/docs/styling/insets) will offset the node from its [containing block](/docs/advanced/containing-block).
 
-**Static**: This node behaves like relative except it will ignore insets and will not
+**Static**: This node behaves like relative except it will ignore [insets](/docs/styling/insets) and will not
 form a [containing block](/docs/advanced/containing-block).
 
 <Playground code={`<Layout config={{useWebDefaults: false}}>