@boxcustodia/library 2.0.0-alpha.13 → 2.0.0-alpha.14

package/src/components/stack/stack.stories.tsx

@@ -6,17 +6,26 @@ import { Label } from "../label";
 import { Stack } from ".";
 
 /**
- * Layout primitive that composes children along a horizontal or vertical axis using flexbox.
- * Supports polymorphic rendering via `as` for semantic HTML (ul, nav, section, etc.).
- * `reverse` inverts the flex direction without exposing raw CSS values.
- * `grow` makes the container fill available space (`flex: 1`).
+ * Layout primitive that arranges children along a horizontal or vertical axis using flexbox.
+ * Polymorphic via `as` for semantic HTML (`ul`, `nav`, `section`, ...).
+ * `reverse` flips the axis without exposing raw CSS values.
+ * `grow` applies `flex: 1` to fill remaining space.
+ * `inline` switches the container to `inline-flex` for flowing with surrounding text.
  */
 const meta: Meta<typeof Stack> = {
   title: "Components/Stack",
   component: Stack,
+  parameters: {
+    layout: "centered",
+  },
   args: {
     gap: 8,
   },
+  argTypes: {
+    as: { control: false },
+    className: { control: false },
+    children: { control: false },
+  },
 };
 
 export default meta;
@@ -25,11 +34,15 @@ type Story = StoryObj<typeof Stack>;
 export const Default: Story = {
   args: {
     align: "center",
+    gap: 12,
   },
   render: (args) => (
     <Stack {...args}>
       <Avatar src="https://i.pravatar.cc/150?img=12" alt="Sara Lane" />
-      <span className="font-semibold text-lg">Sara Lane</span>
+      <Stack direction="vertical" gap={2}>
+        <span className="font-semibold text-sm">Sara Lane</span>
+        <span className="text-xs text-muted-foreground">Product Designer</span>
+      </Stack>
     </Stack>
   ),
 };
@@ -37,52 +50,154 @@ export const Default: Story = {
 export const Vertical: Story = {
   args: {
     direction: "vertical",
+    gap: 6,
   },
   render: (args) => (
-    <Stack {...args}>
+    <Stack {...args} className="w-72">
       <Label>Username</Label>
       <Input type="text" placeholder="Enter your username" />
     </Stack>
   ),
 };
 
+/**
+ * `inline` swaps `flex` for `inline-flex` so the Stack flows with surrounding inline content
+ * instead of breaking onto a new line.
+ */
+export const Inline: Story = {
+  render: () => (
+    <p className="text-sm max-w-sm leading-7">
+      Press{" "}
+      <Stack
+        inline
+        align="center"
+        gap={4}
+        className="px-2 py-0.5 rounded border bg-muted text-xs font-medium"
+      >
+        <span>⌘</span>
+        <span>K</span>
+      </Stack>{" "}
+      to open the command palette from anywhere in the app.
+    </p>
+  ),
+};
+
 /**
  * `reverse` flips the axis direction without needing to know the underlying CSS value
  * (`row-reverse` or `column-reverse`).
  */
 export const Reverse: Story = {
   render: () => (
-    <Stack direction="vertical" gap={16}>
-      <Stack align="center" gap={8}>
-        <span className="text-sm text-muted-foreground w-24">horizontal</span>
-        <Stack gap={8}>
-          <Button>First</Button>
-          <Button variant="secondary">Second</Button>
-          <Button variant="outline">Third</Button>
+    <Stack direction="vertical" gap={16} className="w-[420px]">
+      {(
+        [
+          { label: "horizontal", reverse: false },
+          { label: "reverse", reverse: true },
+        ] as const
+      ).map(({ label, reverse }) => (
+        <Stack key={label} direction="vertical" gap={6}>
+          <span className="text-xs text-muted-foreground uppercase tracking-wide">
+            {label}
+          </span>
+          <Stack
+            reverse={reverse}
+            gap={8}
+            className="border rounded-lg p-3 bg-muted/30"
+          >
+            <Button size="sm">First</Button>
+            <Button size="sm" variant="secondary">
+              Second
+            </Button>
+            <Button size="sm" variant="outline">
+              Third
+            </Button>
+          </Stack>
         </Stack>
-      </Stack>
-      <Stack align="center" gap={8}>
-        <span className="text-sm text-muted-foreground w-24">reverse</span>
-        <Stack reverse gap={8}>
-          <Button>First</Button>
-          <Button variant="secondary">Second</Button>
-          <Button variant="outline">Third</Button>
+      ))}
+    </Stack>
+  ),
+};
+
+/**
+ * `justify` maps to `justify-content`. Controls distribution along the main axis.
+ */
+export const Justify: Story = {
+  render: () => (
+    <Stack direction="vertical" gap={10} className="w-[420px]">
+      {(
+        [
+          "flex-start",
+          "center",
+          "flex-end",
+          "space-between",
+          "space-evenly",
+        ] as const
+      ).map((value) => (
+        <Stack key={value} direction="vertical" gap={4}>
+          <span className="text-xs text-muted-foreground font-mono">
+            {value}
+          </span>
+          <Stack justify={value} className="border rounded-lg p-3 bg-muted/30">
+            <Button size="sm">A</Button>
+            <Button size="sm" variant="secondary">
+              B
+            </Button>
+          </Stack>
         </Stack>
-      </Stack>
+      ))}
+    </Stack>
+  ),
+};
+
+/**
+ * `align` maps to `align-items`. Controls placement along the cross axis.
+ */
+export const Align: Story = {
+  render: () => (
+    <Stack direction="vertical" gap={10} className="w-[420px]">
+      {(["flex-start", "center", "flex-end", "stretch"] as const).map(
+        (value) => (
+          <Stack key={value} direction="vertical" gap={4}>
+            <span className="text-xs text-muted-foreground font-mono">
+              {value}
+            </span>
+            <Stack
+              align={value}
+              gap={8}
+              className="border rounded-lg p-3 bg-muted/30 h-20"
+            >
+              <Button size="sm">A</Button>
+              <Button size="sm" variant="secondary">
+                B
+              </Button>
+            </Stack>
+          </Stack>
+        ),
+      )}
     </Stack>
   ),
 };
 
 /**
  * `wrap` enables `flex-wrap` so children overflow onto the next line instead of shrinking.
- * Useful for tag lists, badge groups, and responsive card grids.
+ * Useful for tag lists, badge groups, and responsive chip rows.
  */
 export const Wrap: Story = {
   render: () => (
-    <Stack wrap="wrap" gap={8} className="max-w-[300px]">
-      {Array.from({ length: 10 }, (_, i) => (
-        <Button key={i} variant="outline" size="sm">
-          Tag {i + 1}
+    <Stack wrap gap={8} className="max-w-[320px]">
+      {[
+        "React",
+        "TypeScript",
+        "Vite",
+        "Tailwind",
+        "Storybook",
+        "Base UI",
+        "Bun",
+        "Vitest",
+        "Playwright",
+      ].map((tag) => (
+        <Button key={tag} size="sm" variant="outline">
+          {tag}
         </Button>
       ))}
     </Stack>
@@ -90,23 +205,28 @@ export const Wrap: Story = {
 };
 
 /**
- * `grow` applies `flex: 1` to the Stack, making it fill the remaining space of its parent.
+ * `grow` applies `flex: 1` so the Stack fills the remaining space of its parent.
  * Useful for sidebars, split panes, and full-height layouts.
  */
 export const Grow: Story = {
   render: () => (
-    <Stack className="h-[120px] border rounded p-2">
-      <div className="w-16 bg-muted rounded flex items-center justify-center text-xs">
+    <Stack gap={8} className="h-32 w-[420px] border rounded-lg p-2 bg-muted/30">
+      <Stack
+        align="center"
+        justify="center"
+        className="w-20 rounded-md bg-background border text-xs font-medium"
+      >
         Fixed
-      </div>
+      </Stack>
       <Stack
         grow
         direction="vertical"
-        gap={4}
-        className="bg-muted/40 rounded p-2"
+        justify="center"
+        gap={2}
+        className="rounded-md bg-background border px-3"
       >
         <span className="text-xs font-medium">Grows to fill</span>
-        <span className="text-xs text-muted-foreground">flex: 1</span>
+        <span className="text-xs text-muted-foreground font-mono">flex: 1</span>
       </Stack>
     </Stack>
   ),
@@ -118,73 +238,43 @@ export const Grow: Story = {
  */
 export const As: Story = {
   render: () => (
-    <Stack as="ul" direction="vertical" gap={4} className="list-none p-0 m-0">
-      <li>Item one</li>
-      <li>Item two</li>
-      <li>Item three</li>
-    </Stack>
-  ),
-};
-
-export const Justify: Story = {
-  render: () => (
-    <Stack direction="vertical" gap={12}>
-      {(
-        [
-          "flex-start",
-          "center",
-          "flex-end",
-          "space-between",
-          "space-evenly",
-        ] as const
-      ).map((value) => (
-        <Stack key={value} direction="vertical" gap={4}>
-          <span className="text-xs text-muted-foreground">{value}</span>
-          <Stack justify={value} className="border rounded p-2">
-            <Button size="sm">A</Button>
-            <Button size="sm" variant="secondary">
-              B
-            </Button>
-          </Stack>
-        </Stack>
-      ))}
-    </Stack>
-  ),
-};
-
-export const Align: Story = {
-  render: () => (
-    <Stack direction="vertical" gap={12} className="w-fit">
-      {(["flex-start", "center", "flex-end"] as const).map((value) => (
-        <Stack key={value} direction="vertical" gap={4}>
-          <span className="text-xs text-muted-foreground">{value}</span>
-          <Stack align={value} className="border rounded p-2 h-20">
-            <Button size="sm">A</Button>
-            <Button size="sm" variant="secondary">
-              B
-            </Button>
-          </Stack>
-        </Stack>
+    <Stack
+      as="ul"
+      direction="vertical"
+      gap={4}
+      className="list-none p-0 m-0 w-64"
+    >
+      {["Dashboard", "Projects", "Team", "Settings"].map((item) => (
+        <li
+          key={item}
+          className="px-3 py-2 rounded-md hover:bg-muted text-sm cursor-pointer"
+        >
+          {item}
+        </li>
       ))}
     </Stack>
   ),
 };
 
+/**
+ * Stacks compose freely. Nest a vertical Stack inside a horizontal one to build
+ * media objects, list items, and card headers without bespoke layout components.
+ */
+/**
+ * `gap` accepts any `CSSProperties["gap"]` value — numbers (treated as `px`),
+ * unit strings (`"1rem"`, `"0.5em"`), percentages, or `calc()` expressions.
+ */
 export const Nested: Story = {
-  args: {
-    align: "center",
-    gap: 16,
-  },
-  render: (args) => (
-    <Stack {...args}>
+  render: () => (
+    <Stack align="center" gap="1rem" className="w-[420px]">
       <Avatar
         className="w-16 h-16"
         src="https://i.pravatar.cc/150?img=12"
         alt="Sara Lane"
       />
-      <Stack direction="vertical" gap={4}>
-        <span className="font-semibold text-lg">Sara Lane</span>
-        <span className="text-sm text-muted-foreground max-w-[360px]">
+      <Stack direction="vertical" gap="0.25rem" grow>
+        <span className="font-semibold text-base">Sara Lane</span>
+        <span className="text-sm text-muted-foreground">
           Senior product designer with 8 years of experience building design
           systems and component libraries for cross-functional teams.
         </span>

package/src/components/stack/stack.tsx

@@ -9,7 +9,7 @@ interface StackProps extends ComponentProps<"div"> {
   justify?: CSSProperties["justifyContent"];
   align?: CSSProperties["alignItems"];
   gap?: CSSProperties["gap"];
-  wrap?: CSSProperties["flexWrap"];
+  wrap?: CSSProperties["flexWrap"] | boolean;
   grow?: boolean;
 }
 
@@ -42,7 +42,7 @@ export const Stack = ({
         justifyContent: justify,
         alignItems: align,
         gap,
-        flexWrap: wrap,
+        flexWrap: wrap === true ? "wrap" : wrap === false ? undefined : wrap,
         ...style,
       }}
       data-slot="stack"

package/src/components/stepper/index.ts

@@ -1 +1 @@
-export * from "./Stepper";
+export * from "./stepper";