@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

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

@@ -0,0 +1,284 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Avatar } from "../avatar";
+import { Button } from "../button";
+import { Input } from "../input";
+import { Label } from "../label";
+import { Stack } from ".";
+
+/**
+ * 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;
+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" />
+      <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>
+  ),
+};
+
+export const Vertical: Story = {
+  args: {
+    direction: "vertical",
+    gap: 6,
+  },
+  render: (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} 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>
+  ),
+};
+
+/**
+ * `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>
+  ),
+};
+
+/**
+ * `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 chip rows.
+ */
+export const Wrap: Story = {
+  render: () => (
+    <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>
+  ),
+};
+
+/**
+ * `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 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
+      </Stack>
+      <Stack
+        grow
+        direction="vertical"
+        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 font-mono">flex: 1</span>
+      </Stack>
+    </Stack>
+  ),
+};
+
+/**
+ * `as` renders the Stack as a different HTML element for semantic markup.
+ * Children of a `ul` stack should be `li` elements.
+ */
+export const As: Story = {
+  render: () => (
+    <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 = {
+  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="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>
+      </Stack>
+    </Stack>
+  ),
+};

package/src/components/stack/stack.test.tsx

@@ -0,0 +1,134 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Stack } from "../../components";
+
+describe("Stack", () => {
+  describe("rendering", () => {
+    it("renders with data-slot='stack'", () => {
+      render(<Stack />);
+      expect(document.querySelector('[data-slot="stack"]')).toBeTruthy();
+    });
+
+    it("renders children", () => {
+      render(
+        <Stack>
+          <span data-testid="child">hello</span>
+        </Stack>,
+      );
+      expect(screen.getByTestId("child")).toBeTruthy();
+    });
+
+    it("renders as div by default", () => {
+      const { container } = render(<Stack />);
+      expect(container.firstChild?.nodeName).toBe("DIV");
+    });
+  });
+
+  describe("as prop", () => {
+    it("renders as custom element type", () => {
+      const { container } = render(<Stack as="section" />);
+      expect(container.firstChild?.nodeName).toBe("SECTION");
+    });
+  });
+
+  describe("inline prop", () => {
+    it("uses flex by default", () => {
+      render(<Stack />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveClass("flex");
+    });
+
+    it("uses inline-flex when inline=true", () => {
+      render(<Stack inline />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveClass(
+        "inline-flex",
+      );
+    });
+  });
+
+  describe("grow prop", () => {
+    it("applies flex-1 when grow=true", () => {
+      render(<Stack grow />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveClass(
+        "flex-1",
+      );
+    });
+
+    it("does not apply flex-1 by default", () => {
+      render(<Stack />);
+      expect(document.querySelector('[data-slot="stack"]')).not.toHaveClass(
+        "flex-1",
+      );
+    });
+  });
+
+  describe("direction prop", () => {
+    it("sets flexDirection to row by default", () => {
+      render(<Stack />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveStyle(
+        "flex-direction: row",
+      );
+    });
+
+    it("sets flexDirection to column when vertical", () => {
+      render(<Stack direction="vertical" />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveStyle(
+        "flex-direction: column",
+      );
+    });
+  });
+
+  describe("reverse prop", () => {
+    it("sets flexDirection to row-reverse when reverse=true", () => {
+      render(<Stack reverse />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveStyle(
+        "flex-direction: row-reverse",
+      );
+    });
+
+    it("sets flexDirection to column-reverse when vertical+reverse", () => {
+      render(<Stack direction="vertical" reverse />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveStyle(
+        "flex-direction: column-reverse",
+      );
+    });
+  });
+
+  describe("style props", () => {
+    it("sets justifyContent from justify prop", () => {
+      render(<Stack justify="center" />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveStyle(
+        "justify-content: center",
+      );
+    });
+
+    it("sets alignItems from align prop", () => {
+      render(<Stack align="flex-end" />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveStyle(
+        "align-items: flex-end",
+      );
+    });
+
+    it("sets flexWrap to wrap when wrap=true", () => {
+      render(<Stack wrap />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveStyle(
+        "flex-wrap: wrap",
+      );
+    });
+
+    it("sets custom gap value", () => {
+      render(<Stack gap={16} />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveStyle(
+        "gap: 16px",
+      );
+    });
+  });
+
+  describe("className", () => {
+    it("applies className", () => {
+      render(<Stack className="custom-stack" />);
+      expect(document.querySelector('[data-slot="stack"]')).toHaveClass(
+        "custom-stack",
+      );
+    });
+  });
+});

package/src/components/stack/stack.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import { ComponentProps, CSSProperties, ElementType } from "react";
+import { cn } from "../../lib";
+
+interface StackProps extends ComponentProps<"div"> {
+  as?: ElementType;
+  inline?: boolean;
+  direction?: "horizontal" | "vertical";
+  reverse?: boolean;
+  justify?: CSSProperties["justifyContent"];
+  align?: CSSProperties["alignItems"];
+  gap?: CSSProperties["gap"];
+  wrap?: CSSProperties["flexWrap"] | boolean;
+  grow?: boolean;
+}
+
+export const Stack = ({
+  as: Tag = "div",
+  inline = false,
+  direction = "horizontal",
+  reverse = false,
+  justify,
+  align,
+  gap = 8,
+  wrap,
+  grow = false,
+  className,
+  style,
+  ...props
+}: StackProps) => {
+  const flexDirection =
+    `${direction === "vertical" ? "column" : "row"}${reverse ? "-reverse" : ""}` as CSSProperties["flexDirection"];
+
+  return (
+    <Tag
+      className={cn(
+        inline ? "inline-flex" : "flex",
+        grow && "flex-1",
+        className,
+      )}
+      style={{
+        flexDirection,
+        justifyContent: justify,
+        alignItems: align,
+        gap,
+        flexWrap: wrap === true ? "wrap" : wrap === false ? undefined : wrap,
+        ...style,
+      }}
+      data-slot="stack"
+      {...props}
+    />
+  );
+};

package/src/components/stepper/index.ts

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