Merge pull request #2561 from Shopify/js-text-stack-docs

Updated the docs for POS Stack

packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stack.doc.ts

@@ -32,113 +32,111 @@ const data: ReferenceEntityTemplateSchema = {
       anchorLink: 'examples',
       title: 'Examples',
       sectionContent: `
-The following examples will demonstrate some, but not all of the abilities of the \`Stack\` component. In all the following examples we will be applying \`horizontalPadding\` of \`ExtraExtraLarge\`, since this is the default that we use on POS when we wrap our screens. For simplicity, these examples use the React version of the \`Stack\` component, but the same results will be achieved by using the same props with the regular JS library.
+The following examples will demonstrate some, but not all of the abilities of the \`Stack\` component. For simplicity, these examples use the React version of the \`Stack\` component, but the same results will be achieved by using the same properties with the regular JS library.
 `,
     },
     {
       type: 'Generic',
-      anchorLink: 'horizontal-default',
-      title: 'Horizontal Stack with default values',
+      anchorLink: 'inline-default',
+      title: 'Inline Stack with default values',
       sectionContent: `
-In this example, we specify \`horizontal\` for the \`direction\`. We don't specify the \`flex\`, which means it's 0 by default. However, \`horizontal\` stacks will always stretch to fill from the left to the right of the screen. As you can see, we have two small buttons occupying just the amount of space that they need, at the left side of the \`Stack\`. This is because \`alignment\` is set to \`flex-end\` by default.
+In this example, we specify \`inline\` for the \`direction\`. As you can see, we have two small buttons occupying just the amount of space that they need, at the left side of the \`Stack\`. This is because \`justifyContent\` is set to \`start\` by default. We also include a \`gap\` of "200".
 `,
       codeblock: generateCodeBlockForStack(
-        'Horizontal Stack with default values',
-        'horizontal-default',
+        'Inline Stack with default values',
+        'inline-default',
       ),
-      image: 'extension-stack-horizontal.png',
+      image: 'extension-stack-inline.png',
     },
     {
       type: 'Generic',
-      anchorLink: 'horizontal-flex-children',
-      title: 'Horizontal Stack with flexChildren',
+      anchorLink: 'inline-flex-children',
+      title: 'Inline Stack with flexChildren',
       sectionContent: `
-Similar to the example above, but this time we are specifying \`flexChildren\` to be \`true\`. This means that the two buttons will take up the max amount of space that they can within the \`horizontal\` stack.
+Similar to the example above, but this time we are specifying \`flexChildren\` to be \`true\`. This means that the two buttons will take up the max amount of space that they can within the \`inline\` stack.
       `,
       codeblock: generateCodeBlockForStack(
-        'Horizontal Stack with flexChildren',
-        'horizontal-flex-children',
+        'Inline Stack with flexChildren',
+        'inline-flex-children',
       ),
-      image: 'extension-stack-horizontal-flexChildren.png',
+      image: 'extension-stack-inline-flexChildren.png',
     },
     {
       type: 'Generic',
-      anchorLink: 'horizontal-center-children',
-      title: 'Horizontal Stack with centered children',
+      anchorLink: 'inline-center-children',
+      title: 'Inline Stack with centered children',
       sectionContent: `
-You can also center elements in your \`horizontal\` stack. For this, you can specify the \`alignment\` to be \`center\`. However, in this case you also want \`flexChildren\` to be \`false\` (which is the default), so that the children can take up the minimal amount of space that they need, and be centered.
+You can also center elements in your \`inline\` stack. For this, you can specify the \`justifyContent\` to be \`center\`. However, in this case you also want \`flexChildren\` to be \`false\` (which is the default), so that the children can take up the minimal amount of space that they need, and be centered.
 `,
       codeblock: generateCodeBlockForStack(
-        'Horizontal Stack with centered children',
-        'horizontal-center-children',
+        'Inline Stack with centered children',
+        'inline-center-children',
       ),
-      image: 'extension-stack-horizontal-centered.png',
+      image: 'extension-stack-inline-centered.png',
     },
     {
       type: 'Generic',
-      anchorLink: 'horizontal-end-children',
-      title: 'Horizontal Stack with children at the end',
-      sectionContent: `
-To make the children be aligned to the end of your \`horizontal\` container, you just need to specify \`alignment\` to be \`flex-end\`. Note that in the first example, the children were at the start of the container. This is because the default value is \`flex-start\`.
-`,
+      anchorLink: 'inline-align-items-center',
+      title: 'Inline Stack with vertical axis centering',
+      sectionContent: `Here we have an \`inline\` stack with two children. The first is a block stack with two buttons, and the second is a single button. Since the first element has a greater intrinsic height, our main inline stack's intrinsic height is also increased. We can center both children component along the main axis (x-axis) by setting the \`alignItems\` property to \`center\`.`,
       codeblock: generateCodeBlockForStack(
-        'Horizontal Stack with children at the end',
-        'horizontal-end-children',
+        'Inline Stack with vertical axis centering',
+        'inline-align-items-center',
       ),
-      image: 'extension-stack-horizontal-flex-end.png',
+      image: 'extension-stack-inline-align-items-center.png',
     },
     {
       type: 'Generic',
-      anchorLink: 'vertical',
-      title: 'Vertical Stack',
+      anchorLink: 'block',
+      title: 'Block Stack',
       sectionContent: `
-You can specify your \`Stack\` to layout its children vertically by setting \`direction\` to \`vertical\`.
+You can specify your \`Stack\` to layout its children vertically by setting the \`direction\` property to \`block\`.
   `,
-      codeblock: generateCodeBlockForStack('Vertical Stack', 'vertical'),
-      image: 'extension-stack-vertical.png',
+      codeblock: generateCodeBlockForStack('Block Stack', 'block'),
+      image: 'extension-stack-block.png',
     },
     {
       type: 'Generic',
-      anchorLink: 'vertical-center-children',
-      title: 'Vertical Stack with centered children',
+      anchorLink: 'extension-stack-block-space-between',
+      title: 'Block Stack with space between children',
       sectionContent: `
-You can center your stack's children along the \`vertical\` axis by setting the \`alignment\` to \`center\`. However, because \`vertical\` stacks only take up the minimal amount of \`vertical\` space required when \`flex\` is set to \`0\` (which is by default), you will need to set \`flex\` to \`1\`
+ Here we are spacing out the children of our block stack by setting \`justifyContent\` to \`space-between\` in order to space the children out as much as possible along the vertical axis. Note that in this example, we removed the wrapping \`ScrollView\` in order to introduce a custom height by setting the \`blockSize\` to \`50%\`. We are also adding \`inlinePadding\` of \`450\` in order to mimic the padding applied to the UI Extension screen header.
 `,
       codeblock: generateCodeBlockForStack(
-        'Vertical Stack with centered children',
-        'vertical-center-children',
+        'Block Stack with space between children',
+        'block-space-between',
       ),
-      image: 'extension-stack-vertical-center.png',
+      image: 'extension-stack-block-space-between.png',
     },
     {
       type: 'Generic',
-      anchorLink: 'vertical-bottom-children',
-      title: 'Vertical Stack with children at the bottom',
+      anchorLink: 'block-center-all',
+      title: 'Block Stack centered on both axes',
       sectionContent: `
-You can set your children to the bottom of your \`vertical\` stack by setting \`alignment\` to \`flex-end\`. As explained in the previous example, you also need to set \`flex\` to \`1\`, since the default is \`0\`, which will make your container only take up the minimum amount of space it needs.
+You can center your block stack on the vertical axis by setting \`justifyContent\` to \`center\`. Next, you can set a custom size on your block stack by setting the \`blockSize\` and \`inlineSize\`. In this example we set them to \`50%\` and \`100%\` respectively. We can then center our elements along both axis of the stack by setting justifyContent to \`center\` to center the children vertically, and setting both \`alignContent\` and \`alignItems\` to \`center\`.
 `,
       codeblock: generateCodeBlockForStack(
-        'Vertical Stack with children at the bottom',
-        'vertical-bottom-children',
+        'Block Stack centered on both axes',
+        'block-center-all',
       ),
-      image: 'extension-stack-vertical-flex-end.png',
+      image: 'extension-stack-block-center-all.png',
     },
     {
       type: 'Generic',
       anchorLink: 'nested',
       title: 'Nested Stack',
       sectionContent: `
-Now that we've run through a few examples of what a \`Stack\` can do, let's move on to something more complex. You can nest multiple Stacks of different configurations to achieve a more complex UI. In this example, we will create a row that displays several labels and an icon. This will mimic some of the basic rows that you can find across different POS screens.
+Now that we've run through a few examples of what a stack can do, let's move on to something more complex. You can nest multiple stacks of different configurations to achieve a more complex UI. In this example, we will create a row that displays several labels and an icon. This will mimic some of the basic rows that you can find across different POS screens.
 
-Let's put the \`Selectable\` aside for now; we'll get to that later. If you look at the first \`Stack\`, this is our parent \`Stack\`. We've set its \`direction\` to \`horizontal\` and its \`alignment\` to \`space-between\`. Then, we've added some vertical and horizontal padding (as highlighted in the screenshot).
+Let's put the \`Selectable\` aside for now; we'll get to that later. The first stack is which we can refer to as the parent stack, is set to inline. It has two main children, a block stack on the left, and an inline stack on the right. To space them out completely along the horizontal axis, we set our parent inline stack's \`justifyContent\` to \`space-between\`. We also specify the \`inlineSize\` to be \`100%\` to take up the full width of the screen.
 
-As you can see, there are two child Stacks. Because the parent \`Stack\` is set to \`space-between\`, these two child Stacks are spread to each end of the parent horizontal \`Stack\`. Both of these child Stacks occupy the amount of space they need, but not more.
+The first child stack (the block stack) simply has a gap of 100 to space out the two \`Text\` components.
 
-The first child \`Stack\` is a simple vertical \`Stack\` that stacks the two left labels. It specifies the \`spacing\` to be \`0.5\` (the default is \`1\`, and this was a bit too much).
+The second child stack (the inline stack) has a gap of 600 to space out the \`Text\` and the \`Icon\`. We also set the \`alignItems\` and \`alignContent\` properties to \`center\` to center the \`Text\` and \`Icon\` within their stack.
 
-The second child \`Stack\` has another nested \`Stack\`. Let's discuss the nested \`Stack\` first. This is a horizontal \`Stack\` that lays out a text label and an icon horizontally. We then apply a bit of padding. That horizontal \`Stack\` is wrapped in a vertical \`Stack\`. The reason for this is to align the horizontal \`Stack\` on the center of the vertical axis, giving it a nicer appearance. Without it, the horizontal \`Stack\` would be located at the same height as the "Hello world!" \`Text\` on the left side of our row. But by specifying a \`flex\` of \`1\`, we are telling the vertical \`Stack\` to take as much vertical space as it can within its parent container. And then we specify an alignment of center, which lays out its child horizontal \`Stack\` on the center of its vertical axis.
+However, we also need to the \`alignItems\` and \`alignContent\` properties to \`center\` on the parent inline stack to center the two children stacks along the vertical axis.
 
-Finally, we can return to the \`Selectable\`. You'll notice that we've wrapped the entire \`Stack\` in a \`Selectable\`. This makes the entire \`Stack\` within the \`Selectable\` become a tappable surface, with an \`onPress\` handler, which is part of the \`Selectable\` component. It also gives a nice highlight effect when you tap, as you can see in the screenshot.
+Finally, we can return to the \`Selectable\`. You'll notice that we've wrapped the entire stack in a \`Selectable\`. This makes the entire stack within the \`Selectable\` become a tappable surface, with an \`onPress\` handler, which is part of the \`Selectable\` component. It also gives a nice highlight effect when you tap, as you can see in the screenshot.
 `,
       codeblock: generateCodeBlockForStack('Nested Stack', 'nested'),
       image: 'extension-stack-nested.png',
@@ -149,7 +147,7 @@ Finally, we can return to the \`Selectable\`. You'll notice that we've wrapped t
   thumbnail: 'stack-thumbnail.png',
   defaultExample: {
     image: 'stack-default.png',
-    codeblock: generateCodeBlockForStack('Stack', 'horizontal-default'),
+    codeblock: generateCodeBlockForStack('Stack', 'inline-default'),
   },
 };
 

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/stack/block-center-all.tsx

@@ -0,0 +1,15 @@
+<Screen name="Stack" title="Stack">
+  <Stack
+    direction="block"
+    justifyContent="center"
+    alignContent="center"
+    alignItems="center"
+    inlineSize="100%"
+    paddingInline="450"
+    blockSize="50%"
+    gap="200"
+  >
+    <Button title="hello" />
+    <Button title="hello" />
+  </Stack>
+</Screen>;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/stack/block-space-between.tsx

@@ -0,0 +1,12 @@
+<Screen name="Stack" title="Stack">
+  <Stack
+    direction="block"
+    justifyContent="space-between"
+    paddingInline="450"
+    blockSize="50%"
+    gap="200"
+  >
+    <Button title="hello" />
+    <Button title="hello" />
+  </Stack>
+</Screen>;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/stack/block.tsx

@@ -0,0 +1,6 @@
+<Screen name="Stack" title="Stack">
+  <Stack direction="block" paddingInline="450" gap="200">
+    <Button title="hello" />
+    <Button title="hello" />
+  </Stack>
+</Screen>;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/stack/inline-align-items-center.tsx

@@ -0,0 +1,16 @@
+<Screen name="Stack" title="Stack">
+  <ScrollView>
+    <Stack
+      direction="inline"
+      alignItems="center"
+      alignContent="center"
+      gap="200"
+    >
+      <Stack direction="block" gap="200">
+        <Button title="hello" />
+        <Button title="hello" />
+      </Stack>
+      <Button title="hello" />
+    </Stack>
+  </ScrollView>
+</Screen>;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/stack/inline-center-children.tsx

@@ -0,0 +1,8 @@
+<Screen name="Stack" title="Stack">
+  <ScrollView>
+    <Stack direction="inline" gap="200" justifyContent="center">
+      <Button title="Hello" />
+      <Button title="Hello" />
+    </Stack>
+  </ScrollView>
+</Screen>;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/stack/inline-default.tsx

@@ -0,0 +1,8 @@
+<Screen name="Home" title="Home">
+  <ScrollView>
+    <Stack direction="inline" gap="200">
+      <Button title="Hello" />
+      <Button title="Hello" />
+    </Stack>
+  </ScrollView>
+</Screen>;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/stack/inline-flex-children.tsx

@@ -0,0 +1,8 @@
+<Screen name="Stack" title="Stack">
+  <ScrollView>
+    <Stack direction="inline" gap="200" flexChildren>
+      <Button title="Hello" />
+      <Button title="Hello" />
+    </Stack>
+  </ScrollView>
+</Screen>;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/stack/nested.tsx

@@ -1,26 +1,28 @@
-<Screen name="Home">
-  <Selectable onPress={() => console.log('You tapped this row!')}>
-    // Parent stack
+<Screen name="Stack" title="Stack">
+  <Selectable onPress={() => {}}>
     <Stack
-      direction="horizontal"
-      alignment="space-between"
-      paddingVertical={'Medium'}
-      paddingHorizontal={'ExtraExtraLarge'}
+      direction="inline"
+      justifyContent="space-between"
+      inlineSize="100%"
+      alignContent="center"
+      alignItems="center"
+      paddingInline="450"
+      paddingBlock="600"
     >
-      // First child stack
-      <Stack direction="vertical" spacing={0.5}>
+      <Stack direction="block" gap="100">
         <Text>Hello world!</Text>
         <Text variant="captionRegular">
           This is an example of nested stacks!
         </Text>
       </Stack>
-      // Second child stack
-      <Stack direction="vertical" flex={1} alignment="center">
-        // Horizontal stack for the right label and chevron icon
-        <Stack direction="horizontal" spacing={2}>
-          <Text variant="captionRegular">Let's go!</Text>
-          <Icon name="chevron-right" />
-        </Stack>
+      <Stack
+        direction="inline"
+        alignItems="center"
+        alignContent="center"
+        gap="600"
+      >
+        <Text variant="captionRegular">Let's go!</Text>
+        <Icon name="chevron-right" />
       </Stack>
     </Stack>
   </Selectable>