docs[DST-509]:Revise <Stack> page (#4105)

* revise stack page update demos * update * save * update page * Create nervous-toys-kick.md * update sentence description * correction * remove default * update alternatives * removed none values from align style props * changed it back * upate * update split related stuff * a more complex demo for nested stacks * fix test * added bit of explaination
marigold-ui · Aug 15, 2024 · a9f3fad · a9f3fad
1 parent e6780b4
commit a9f3fad
Show file tree

Hide file tree

Showing 9 changed files with 172 additions and 80 deletions.
diff --git a/.changeset/nervous-toys-kick.md b/.changeset/nervous-toys-kick.md
@@ -0,0 +1,5 @@
+---
+"@marigold/docs": patch
+---
+
+docs[DST-509]:Revise `<Stack>` page
diff --git a/docs/content/components/layout/stack/stack-horizontal.demo.tsx b/docs/content/components/layout/stack/stack-horizontal.demo.tsx
@@ -1,15 +1,30 @@
-import { Stack, Text } from '@marigold/components';
+import { Divider, Stack } from '@marigold/components';
+import { Rectangle } from '@/ui/Rectangle';
 
 export default () => (
-  <>
-    <Stack space={4}>
-      <Text>Left</Text>
+  <Stack space={4}>
+    <Stack space={4} alignX="left">
+      <Rectangle height="30px" width="50px">
+        <div className="text-text-primary-muted m-auto">Left</div>
+      </Rectangle>
+      <Rectangle height="30px" width="50px" />
+      <Rectangle height="30px" width="50px" />
     </Stack>
+    <Divider />
     <Stack space={4} alignX="center">
-      <Text>Center</Text>
+      <Rectangle height="30px" width="50px">
+        <div className="text-text-primary-muted m-auto">Center</div>
+      </Rectangle>
+      <Rectangle height="30px" width="50px" />
+      <Rectangle height="30px" width="50px" />
     </Stack>
+    <Divider />
     <Stack space={4} alignX="right">
-      <Text>Right</Text>
+      <Rectangle height="30px" width="50px">
+        <div className="text-text-primary-muted m-auto">Right</div>
+      </Rectangle>
+      <Rectangle height="30px" width="50px" />
+      <Rectangle height="30px" width="50px" />
     </Stack>
-  </>
+  </Stack>
 );
diff --git a/docs/content/components/layout/stack/stack-nested.demo.tsx b/docs/content/components/layout/stack/stack-nested.demo.tsx
@@ -1,20 +1,29 @@
-import { Headline, Stack, Text } from '@marigold/components';
+import { Inline, Split, Stack } from '@marigold/components';
+import { Rectangle } from '@/ui/Rectangle';
 
 export default () => (
-  <Stack space={8}>
-    <Stack space={4}>
-      <Headline level={2}>Stack Content #1</Headline>
-      <Text>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</Text>
-      <Text>
-        Phasellus ipsum tortor, aliquet dapibus fermentum in, mollis vel metus.
-      </Text>
-    </Stack>
-    <Stack space={4}>
-      <Headline level={2}>Stack Content #2</Headline>
-      <Text>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</Text>
-      <Text>
-        Phasellus ipsum tortor, aliquet dapibus fermentum in, mollis vel metus.
-      </Text>
-    </Stack>
+  <Stack space={10}>
+    <div className="border-border bg-bg-body rounded-sm border-2 border-dashed p-2">
+      <Inline space={8}>
+        <Stack space={2} stretch>
+          <Rectangle height="30px" width="100%" />
+          <Rectangle height="30px" width="100%" />
+          <Rectangle height="30px" width="100%" />
+        </Stack>
+        <Stack space={2}>
+          <Rectangle height="30px" width="70px" />
+          <Rectangle height="30px" width="70px" />
+          <Rectangle height="30px" width="70px" />
+        </Stack>
+        <Split />
+        <Stack space={2}>
+          <Rectangle height="30px" width="70px" />
+          <Rectangle height="30px" width="70px" />
+          <Rectangle height="30px" width="70px" />
+        </Stack>
+      </Inline>
+    </div>
+    <Rectangle height="50px" />
+    <Rectangle height="50px" />
   </Stack>
 );
diff --git a/docs/content/components/layout/stack/stack-spacing.demo.tsx b/docs/content/components/layout/stack/stack-spacing.demo.tsx
@@ -1,19 +1,10 @@
-import { Headline, Stack, Text } from '@marigold/components';
+import { Stack } from '@marigold/components';
+import { Rectangle } from '@/ui/Rectangle';
 
 export default () => (
   <Stack space={8}>
-    <Headline level={2}>Header</Headline>
-    <Text>
-      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
-      dignissim dapibus elit, vel egestas felis pharetra non. Cras malesuada,
-      massa nec ultricies efficitur, lectus ante consequat magna, a porttitor
-      massa ex ut quam.
-    </Text>
-    <Text>
-      Phasellus ipsum tortor, aliquet dapibus fermentum in, mollis vel metus.
-      Vestibulum malesuada ante eu velit malesuada, nec ultricies sapien
-      finibus. Aenean rutrum in sem a ullamcorper. Integer ut euismod urna.
-      Interdum et malesuada fames ac ante ipsum primis in faucibus.
-    </Text>
+    <Rectangle height="50px" />
+    <Rectangle height="50px" />
+    <Rectangle height="50px" />
   </Stack>
 );
diff --git a/docs/content/components/layout/stack/stack-vertical.demo.tsx b/docs/content/components/layout/stack/stack-vertical.demo.tsx
@@ -1,11 +1,36 @@
-import { Stack, Text } from '@marigold/components';
+import { Divider, Stack } from '@marigold/components';
+import { Rectangle } from '@/ui/Rectangle';
 
 export default () => (
-  <div className="h-52 bg-slate-200 p-2">
-    <Stack space={4} stretch alignY="bottom">
-      <Text>Lirum</Text>
-      <Text>Larum</Text>
-      <Text>Löffelstiel!</Text>
-    </Stack>
-  </div>
+  <>
+    <div className="h-52 bg-slate-200 p-2">
+      <Stack space={4} stretch alignY="top">
+        <Rectangle height="30px">
+          <div className="text-text-primary-muted m-auto">Top</div>
+        </Rectangle>
+        <Rectangle height="30px" />
+        <Rectangle height="30px" />
+      </Stack>
+    </div>
+    <Divider />
+    <div className="h-52 bg-slate-200 p-2">
+      <Stack space={4} stretch alignY="center">
+        <Rectangle height="30px">
+          <div className="text-text-primary-muted m-auto">Center</div>
+        </Rectangle>
+        <Rectangle height="30px" />
+        <Rectangle height="30px" />
+      </Stack>
+    </div>
+    <Divider />
+    <div className="h-52 bg-slate-200 p-2">
+      <Stack space={4} stretch alignY="bottom">
+        <Rectangle height="30px">
+          <div className="text-text-primary-muted m-auto">Bottom</div>
+        </Rectangle>
+        <Rectangle height="30px" />
+        <Rectangle height="30px" />
+      </Stack>
+    </div>
+  </>
 );
diff --git a/docs/content/components/layout/stack/stack.mdx b/docs/content/components/layout/stack/stack.mdx
@@ -1,46 +1,103 @@
 ---
 title: Stack
-caption: Component to stack elements.
+caption: Display children vertically with giving space between.
+badge: updated
 ---
 
-The `<Stack>` component is a layout component that is there to stack its children. It has a flexbox context similar like the [`<Inline>`](/components/inline/).
+The `<Stack>` component is a responsive layout component based on [CSS Flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox). The stack is basically a flexbox column that acts as a container that aligns its children vertically in new lines. The component should be used wherever you need to arrange elements stacked on top of each other.
 
-The component should be used anywhere were elements are stacked one atop another. It is also possible to nest if needed.
+Use the stack component in combination with other layout components to easily [create customized layouts](../../concepts/layouts).
 
-`<Stack>` uses the spaces from the given theme, but you can use [`<Split>`](/components/split/) to add bigger spacing. You can also align the elements horizontal and vertical.
+## Usage
 
-## Import
+The use of `<Stack>` is recommended if you have two or more elements that must be the same distance apart. For the space you have to use our supported [space values](../../introduction/design-tokens#spacing).
 
-```tsx
-import { Stack } from '@marigold/components';
-```
+In this example you can see, the space prop ensures that each child is separated by the same space which maintains visual consistency.
 
-## Props
+<ComponentDemo file="./stack-spacing.demo.tsx" />
 
-<PropsTable component={title} />
+### Different alignment
 
-## Examples
+Of course you can align the elements inside of the stack vertically and horizontally. This is useful if you need to place certain items at a certain position. For vertical alignment you need to set the `alignY` property and the `stretch` property to true. The `stretch` property stretches the stack to fill the space of the parent element.
 
-### Spacing
+With the vertical align you can align the children on `top`, `center` or `bottom`.
 
-This example shows how to use the `space` property. You can see the large space between the elements.
+<ComponentDemo file="./stack-vertical.demo.tsx" />
 
-<ComponentDemo file="./stack-spacing.demo.tsx" />
+For horizontal alignment of the children, the children need to have a defined width given so it can align inside the stack container.
 
-### Nested
+To align the children horizontal you have to use the `alignX` property. Options are `right`, `center` and `left`.
 
-The `<Stack>` component can also be nested in another `<Stack>`. So you can build complex structures and constructs but without breaking layout.
+<ComponentDemo file="./stack-horizontal.demo.tsx" />
 
-<ComponentDemo file="./stack-nested.demo.tsx" />
+### Nested stacks
 
-### Horizontal Alignment
+Sometimes you may need complexer layouts to arrange your elements, with the stack component you can also nest stacks within stacks. So you can build complex structures and constructs but without breaking the layout.
 
-The example shows the `alignX` prop, which is used to align the children horizontal. Options are `right`, `center` and `left`. Default is set to `none`.
+The following example shows how stacks can be nested within each other. You see how a stack will behave with a [inline](../layout/inline) and [split](../layout/split) component.
 
-<ComponentDemo file="./stack-horizontal.demo.tsx" />
+<ComponentDemo file="./stack-nested.demo.tsx" />
+
+## Props
 
-### Vertical Alignment
+<StorybookHintMessage component={title} />
 
-You can use the vertical alignment just with the `stretch` prop when its set to true. The `stretch` property stretches to fill the space of the element. With the vertical align you can align the children on `top`, `center` or `bottom`. Default is set to `none`.
+<PropsTable component={title} />
 
-<ComponentDemo file="./stack-vertical.demo.tsx" />
+## Alternative components
+
+<ul>
+  <li>
+    [Inline](../layout/inline): If you need to have the elements displayed in a
+    row you should use our inline component.
+  </li>
+</ul>
+
+## Related
+
+<TeaserList
+  items={[
+    {
+      title: 'Building layouts',
+      href: '../../concepts/layouts',
+      caption: 'Learn how to build layouts.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth={1.5}
+          stroke="currentColor"
+          className="size-6"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M2.25 7.125C2.25 6.504 2.754 6 3.375 6h6c.621 0 1.125.504 1.125 1.125v3.75c0 .621-.504 1.125-1.125 1.125h-6a1.125 1.125 0 0 1-1.125-1.125v-3.75ZM14.25 8.625c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v8.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 0 1-1.125-1.125v-8.25ZM3.75 16.125c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v2.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 0 1-1.125-1.125v-2.25Z"
+          />
+        </svg>
+      ),
+    },
+    {
+      title: 'Split',
+      href: '../layout/split',
+      caption: 'Adds space between two elments in a flex layout.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth={1.5}
+          stroke="currentColor"
+          className="size-6"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M7.5 21 3 16.5m0 0L7.5 12M3 16.5h13.5m0-13.5L21 7.5m0 0L16.5 12M21 7.5H7.5"
+          />
+        </svg>
+      ),
+    },
+  ]}
+/>
diff --git a/packages/components/src/Breakout/Breakout.test.tsx b/packages/components/src/Breakout/Breakout.test.tsx
@@ -54,13 +54,9 @@ test('supports height prop', () => {
 });
 
 test('no align set', () => {
-  render(
-    <Breakout alignY="none" alignX="none" height="200px">
-      breakout
-    </Breakout>
-  );
+  render(<Breakout height="200px">breakout</Breakout>);
   const breakout = screen.getByText(/breakout/);
   expect(breakout.className).toMatchInlineSnapshot(
-    `"col-start-[1_!important] col-end-[-1_!important] w-full flex h-[--height]"`
+    `"col-start-[1_!important] col-end-[-1_!important] w-full justify-start items-center flex h-[--height]"`
   );
 });
diff --git a/packages/components/src/Stack/Stack.tsx b/packages/components/src/Stack/Stack.tsx
@@ -18,13 +18,11 @@ export interface StackProps extends GapSpaceProp {
 
   /**
    * Horizontal alignment for the children.
-   * @default none
    */
   alignX?: keyof typeof alignment.vertical.alignmentX;
 
   /**
    * Vertical alignment for the children.
-   * @default none
    */
   alignY?: keyof typeof alignment.vertical.alignmentY;
 }

diff --git a/packages/system/src/style-props.tsx b/packages/system/src/style-props.tsx
@@ -472,27 +472,23 @@ export const paddingBottom = {
 export const alignment = {
   vertical: {
     alignmentX: {
-      none: undefined,
       left: 'items-start',
       center: 'items-center',
       right: 'items-end',
     },
     alignmentY: {
-      none: undefined,
       top: 'justify-start',
       center: 'justify-center',
       bottom: 'justify-end',
     },
   },
   horizontal: {
     alignmentY: {
-      none: undefined,
       top: 'items-start',
       center: 'items-center',
       bottom: 'items-end',
     },
     alignmentX: {
-      none: undefined,
       left: 'justify-start',
       center: 'justify-center',
       right: 'justify-end',