@elabs-ai/components-ui 4.0.0

package/src/components/checkbox/checkbox.stories.tsx

@@ -0,0 +1,119 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { Checkbox } from "./checkbox";
+import { Label } from "../label";
+const meta = {
+  title: "Forms/Checkbox",
+  component: Checkbox,
+  tags: ["autodocs"],
+  argTypes: {
+    checked: {
+      description: 'Controlled checked state. Use `"indeterminate"` for mixed state.',
+      control: { type: "select" },
+      options: [true, false, "indeterminate"],
+      table: { category: "State" },
+    },
+    defaultChecked: {
+      description: "Uncontrolled initial checked state.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    disabled: {
+      description: "Disables the checkbox.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    required: {
+      description: "Marks the checkbox as required in a form context.",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    onCheckedChange: {
+      description: "Called when the checked state changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the root element.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof Checkbox>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Checkbox id="terms" defaultChecked />
+      <Label htmlFor="terms">Accept terms</Label>
+    </div>
+  ),
+  // Starts checked (defaultChecked); clicking toggles the reflected aria-checked state.
+  play: async ({ canvas, userEvent }) => {
+    const box = canvas.getByRole("checkbox");
+    await expect(box).toHaveAttribute("aria-checked", "true");
+    await userEvent.click(box);
+    await expect(box).toHaveAttribute("aria-checked", "false");
+  },
+};
+
+const CHILDREN = ["Alpha", "Beta", "Gamma"];
+
+/**
+ * A real tri-state "select all" group (#348) — the master shows
+ * `indeterminate` (a dash, visually distinct from `checked`'s tick) when
+ * some-but-not-all children are checked, `checked` when all are, and
+ * `unchecked` when none are.
+ */
+function TriStateGroup() {
+  const [checkedIds, setCheckedIds] = useState<string[]>([CHILDREN[0]!]);
+  const allChecked = checkedIds.length === CHILDREN.length;
+  const someChecked = checkedIds.length > 0 && !allChecked;
+  const masterState = allChecked ? true : someChecked ? "indeterminate" : false;
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center gap-2">
+        <Checkbox
+          id="select-all"
+          checked={masterState}
+          onCheckedChange={(next) => setCheckedIds(next ? [...CHILDREN] : [])}
+        />
+        <Label htmlFor="select-all">Select all</Label>
+      </div>
+      <div className="ms-6 flex flex-col gap-2">
+        {CHILDREN.map((child) => (
+          <div key={child} className="flex items-center gap-2">
+            <Checkbox
+              id={child}
+              checked={checkedIds.includes(child)}
+              onCheckedChange={(next) =>
+                setCheckedIds((prev) =>
+                  next ? [...prev, child] : prev.filter((id) => id !== child),
+                )
+              }
+            />
+            <Label htmlFor={child}>{child}</Label>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export const TriState: Story = {
+  render: () => <TriStateGroup />,
+  // One child is pre-checked, so the master starts indeterminate. Checking
+  // the remaining children flips it to fully checked.
+  play: async ({ canvas, userEvent }) => {
+    const master = canvas.getByRole("checkbox", { name: "Select all" });
+    await expect(master).toHaveAttribute("aria-checked", "mixed");
+    await expect(master).toBeVisible();
+
+    await userEvent.click(canvas.getByRole("checkbox", { name: "Beta" }));
+    await userEvent.click(canvas.getByRole("checkbox", { name: "Gamma" }));
+    await expect(master).toHaveAttribute("aria-checked", "true");
+  },
+};

package/src/components/checkbox/checkbox.test.tsx

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Checkbox } from "./checkbox";
+describe("Checkbox", () => {
+  it("toggles checked state", async () => {
+    render(<Checkbox aria-label="c" />);
+    const box = screen.getByRole("checkbox", { name: "c" });
+    expect(box).toHaveAttribute("data-state", "unchecked");
+    await userEvent.click(box);
+    expect(box).toHaveAttribute("data-state", "checked");
+  });
+
+  // #348 — indeterminate renders a visually distinct glyph (Minus), not Check.
+  // The swap is CSS-only (`group-data-[state=indeterminate]:` on each icon,
+  // mirroring the `data-[state=checked]:` pattern already used elsewhere in
+  // the library) so jsdom — which doesn't evaluate Tailwind's stylesheet —
+  // can only assert the WIRING: both glyphs render, and each carries the
+  // selector that shows it for the correct state. The actual rendered
+  // visibility is verified in a real browser via the Storybook story/test.
+  it("renders both glyphs with the indeterminate/checked CSS toggle wired correctly", () => {
+    const { container } = render(<Checkbox checked="indeterminate" aria-label="select all" />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute("aria-checked", "mixed");
+    expect(container.querySelector('[data-state="indeterminate"]')).toBeInTheDocument();
+
+    const minus = container.querySelector("svg.lucide-minus");
+    const check = container.querySelector("svg.lucide-check");
+    expect(minus).toBeInTheDocument();
+    expect(check).toBeInTheDocument();
+    // Minus is shown ONLY when indeterminate; Check is hidden then.
+    expect(minus).toHaveClass("group-data-[state=indeterminate]:block");
+    expect(check).toHaveClass("group-data-[state=indeterminate]:hidden");
+  });
+
+  it("keeps the Check glyph (not Minus) for the plain checked state", () => {
+    render(<Checkbox checked={true} aria-label="c" />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute("data-state", "checked");
+    expect(screen.getByRole("checkbox")).toHaveAttribute("aria-checked", "true");
+  });
+});

package/src/components/checkbox/checkbox.tsx

@@ -0,0 +1,34 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from "react";
+import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
+import { Check, Minus } from "lucide-react";
+import { cn } from "../../lib/cn";
+
+export const Checkbox = forwardRef<
+  ElementRef<typeof CheckboxPrimitive.Root>,
+  ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
+>(function Checkbox({ className, ...props }, ref) {
+  return (
+    <CheckboxPrimitive.Root
+      ref={ref}
+      className={cn(
+        "peer size-4 shrink-0 rounded-sm border border-input shadow-sm transition-colors duration-fast ease-standard",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+        "disabled:cursor-not-allowed disabled:opacity-50",
+        "data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
+        className,
+      )}
+      {...props}
+    >
+      {/*
+       * `group` + `data-[state]` (Radix sets `data-state` on the Indicator
+       * itself: "checked" | "indeterminate") swaps the glyph purely via CSS —
+       * `Minus` for indeterminate, `Check` for checked — so the two states
+       * are visually distinct instead of both drawing a checkmark (#348).
+       */}
+      <CheckboxPrimitive.Indicator className="group flex items-center justify-center text-current animate-in zoom-in-95 fade-in duration-fast ease-entrance">
+        <Check className="size-3.5 group-data-[state=indeterminate]:hidden" />
+        <Minus className="hidden size-3.5 group-data-[state=indeterminate]:block" />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+});

package/src/components/checkbox/index.ts

@@ -0,0 +1 @@
+export { Checkbox } from "./checkbox";

package/src/components/collapsible/collapsible.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { Button } from "../button";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "./collapsible";
+const meta = {
+  title: "Disclosure/Collapsible",
+  component: Collapsible,
+  tags: ["autodocs"],
+  argTypes: {
+    open: {
+      description: "Controlled open state.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    defaultOpen: {
+      description: "Uncontrolled: whether open on first render.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    onOpenChange: {
+      description: "Callback fired when the open state changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    disabled: {
+      description: "Prevents the user from toggling the collapsible.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn().",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof Collapsible>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <Collapsible className="w-80 space-y-2">
+      <CollapsibleTrigger asChild>
+        <Button variant="outline" size="sm">
+          Toggle details
+        </Button>
+      </CollapsibleTrigger>
+      <CollapsibleContent className="rounded-md border p-3 text-body text-muted-foreground">
+        Hidden details revealed.
+      </CollapsibleContent>
+    </Collapsible>
+  ),
+  // Clicking the trigger toggles the content panel open.
+  play: async ({ canvas, userEvent }) => {
+    const trigger = canvas.getByRole("button", { name: "Toggle details" });
+    // Initially closed — content is not visible.
+    await expect(trigger).toBeInTheDocument();
+    await userEvent.click(trigger);
+    // After click, the content should be in the DOM and becoming visible.
+    const content = await canvas.findByText("Hidden details revealed.");
+    await expect(content).toBeInTheDocument();
+  },
+};

package/src/components/collapsible/collapsible.tsx

@@ -0,0 +1,22 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from "react";
+import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
+import { cn } from "../../lib/cn";
+
+export const Collapsible = CollapsiblePrimitive.Root;
+export const CollapsibleTrigger = CollapsiblePrimitive.CollapsibleTrigger;
+
+export const CollapsibleContent = forwardRef<
+  ElementRef<typeof CollapsiblePrimitive.CollapsibleContent>,
+  ComponentPropsWithoutRef<typeof CollapsiblePrimitive.CollapsibleContent>
+>(function CollapsibleContent({ className, ...props }, ref) {
+  return (
+    <CollapsiblePrimitive.CollapsibleContent
+      ref={ref}
+      className={cn(
+        "overflow-hidden data-[state=open]:animate-collapsible-down data-[state=closed]:animate-collapsible-up data-[state=open]:[--tw-ease:var(--ease-entrance)] data-[state=closed]:[--tw-ease:var(--ease-exit)]",
+        className,
+      )}
+      {...props}
+    />
+  );
+});

package/src/components/collapsible/index.ts

@@ -0,0 +1 @@
+export { Collapsible, CollapsibleTrigger, CollapsibleContent } from "./collapsible";

package/src/components/collapsible-panel/index.ts

@@ -0,0 +1,8 @@
+export {
+  useCollapsiblePanel,
+  type CollapsiblePanelAttrs,
+  type CollapsiblePanelSide,
+  type CollapsiblePanelState,
+  type UseCollapsiblePanelOptions,
+  type UseCollapsiblePanelReturn,
+} from "./use-collapsible-panel";

package/src/components/collapsible-panel/use-collapsible-panel.test.tsx

@@ -0,0 +1,93 @@
+import { describe, expect, it, vi } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+
+import { useCollapsiblePanel } from "./use-collapsible-panel";
+
+describe("useCollapsiblePanel (#190)", () => {
+  it("is uncontrolled by default (defaultOpen=true) and toggles", () => {
+    const { result } = renderHook(() => useCollapsiblePanel());
+    expect(result.current.open).toBe(true);
+    expect(result.current.state).toBe("expanded");
+    expect(result.current.attrs).toEqual({ "data-state": "expanded", "data-side": "left" });
+
+    act(() => result.current.toggle());
+    expect(result.current.open).toBe(false);
+    expect(result.current.state).toBe("collapsed");
+    expect(result.current.attrs["data-state"]).toBe("collapsed");
+  });
+
+  it("respects defaultOpen=false and setOpen with an updater fn", () => {
+    const { result } = renderHook(() => useCollapsiblePanel({ defaultOpen: false }));
+    expect(result.current.state).toBe("collapsed");
+    act(() => result.current.setOpen((o) => !o));
+    expect(result.current.state).toBe("expanded");
+  });
+
+  it("controlled mode: the `open` prop wins and never flips to uncontrolled", () => {
+    const onOpenChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ open }: { open: boolean }) => useCollapsiblePanel({ open, onOpenChange }),
+      { initialProps: { open: false } },
+    );
+    expect(result.current.state).toBe("collapsed");
+
+    // setOpen does NOT mutate internal state in controlled mode — it only
+    // notifies; the prop stays the source of truth.
+    act(() => result.current.setOpen(true));
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    expect(result.current.open).toBe(false);
+
+    rerender({ open: true });
+    expect(result.current.state).toBe("expanded");
+  });
+
+  it("uncontrolled mode still notifies onOpenChange", () => {
+    const onOpenChange = vi.fn();
+    const { result } = renderHook(() => useCollapsiblePanel({ onOpenChange }));
+    act(() => result.current.toggle());
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+    expect(result.current.open).toBe(false);
+  });
+
+  it("data-side follows the side option", () => {
+    const { result } = renderHook(() => useCollapsiblePanel({ side: "right" }));
+    expect(result.current.attrs["data-side"]).toBe("right");
+  });
+
+  it("default fragments use the gated motion utilities (duration-base ease-linear)", () => {
+    const { result } = renderHook(() => useCollapsiblePanel());
+    expect(result.current.spacerClassName).toBe(
+      "relative w-(--collapsible-panel-width) bg-transparent transition-[width] duration-base ease-linear group-data-[state=collapsed]:w-0",
+    );
+    expect(result.current.containerClassName).toBe(
+      "fixed inset-y-0 z-10 hidden h-svh w-(--collapsible-panel-width) transition-[left,right,width] duration-base ease-linear md:flex left-0 group-data-[state=collapsed]:left-[calc(var(--collapsible-panel-width)*-1)]",
+    );
+  });
+
+  // The byte-identity lock (#190 acceptance): configured with Sidebar's
+  // literals, the hook must emit EXACTLY the class fragments sidebar.tsx
+  // shipped before the extraction (the pre-#190 strings, copied verbatim).
+  it("emits Sidebar's original fragments byte-identically when given its literals", () => {
+    const sidebarOptions = {
+      widthClassName: "w-(--sidebar-width)",
+      spacerCollapsedClassName: "group-data-[collapsible=offcanvas]:w-0",
+      containerSlideClassNames: {
+        left: "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]",
+        right: "right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
+      },
+    } as const;
+
+    const left = renderHook(() => useCollapsiblePanel({ side: "left", ...sidebarOptions }));
+    expect(left.result.current.spacerClassName).toBe(
+      "relative w-(--sidebar-width) bg-transparent transition-[width] duration-base ease-linear group-data-[collapsible=offcanvas]:w-0",
+    );
+    expect(left.result.current.containerClassName).toBe(
+      "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-base ease-linear md:flex left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]",
+    );
+
+    const right = renderHook(() => useCollapsiblePanel({ side: "right", ...sidebarOptions }));
+    expect(right.result.current.containerClassName).toBe(
+      "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-base ease-linear md:flex right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
+    );
+  });
+});

package/src/components/collapsible-panel/use-collapsible-panel.ts

@@ -0,0 +1,159 @@
+"use client";
+
+/**
+ * useCollapsiblePanel — THE canonical collapsing-panel mechanism (#190,
+ * research 09 §B.2/§E.1).
+ *
+ * Extracted from Sidebar's collapse (sidebar.tsx): an always-mounted,
+ * two-element width tween — a gap SPACER that reserves/releases the inline
+ * width (`transition-[width] duration-base ease-linear`, collapsing to `w-0`)
+ * and a fixed CONTAINER that slides off-screen
+ * (`transition-[left,right,width] duration-base ease-linear`). `duration-base`
+ * is the gated `--t-base` motion token, so reduced-motion is honoured for free
+ * (pure CSS — the shared base stays motion-free, research 09 decision 2).
+ *
+ * The hook owns:
+ *   - the state machine — controlled + uncontrolled `open` per
+ *     component-api.md (`isControlled = open !== undefined`, never flips
+ *     modes) with `setOpen`/`toggle`;
+ *   - the `data-state`/`data-side` attrs for the group element;
+ *   - the assembly of the two class fragments in the canonical order.
+ *
+ * Width / collapse-trigger / slide utilities are passed as LITERAL class
+ * strings by the consumer (Tailwind's scanner must see each literal in
+ * source — a template-interpolated class is never generated), with
+ * state-keyed defaults for a generic panel. Sidebar passes its
+ * `--sidebar-width` + `group-data-[collapsible=offcanvas]` literals and gets
+ * back its exact original fragments (the byte-identical re-point).
+ *
+ * Fork-prevention: a second gap-spacer + fixed-slide width tween outside this
+ * folder fails `pnpm collapse-fork:check` (scripts/check-collapse-fork.mjs).
+ */
+import { useCallback, useMemo, useState } from "react";
+import { cn } from "../../lib/cn";
+
+export type CollapsiblePanelSide = "left" | "right";
+export type CollapsiblePanelState = "expanded" | "collapsed";
+
+/**
+ * State-keyed defaults for a generic panel: the consumer wraps the panel in a
+ * `group` element carrying `attrs` and sets `--collapsible-panel-width` on it.
+ */
+const DEFAULT_WIDTH_CLASSNAME = "w-(--collapsible-panel-width)";
+const DEFAULT_SPACER_COLLAPSED_CLASSNAME = "group-data-[state=collapsed]:w-0";
+const DEFAULT_CONTAINER_SLIDE_CLASSNAMES: Record<CollapsiblePanelSide, string> = {
+  left: "left-0 group-data-[state=collapsed]:left-[calc(var(--collapsible-panel-width)*-1)]",
+  right: "right-0 group-data-[state=collapsed]:right-[calc(var(--collapsible-panel-width)*-1)]",
+};
+
+export interface UseCollapsiblePanelOptions {
+  /** Which edge the panel lives on. Default `"left"`. */
+  side?: CollapsiblePanelSide;
+  /** Controlled open state (`isControlled = open !== undefined`). */
+  open?: boolean;
+  /** Uncontrolled initial open state. Default `true`. */
+  defaultOpen?: boolean;
+  /** Called with the next open state on `setOpen`/`toggle`. */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * Literal expanded-width utility (e.g. `"w-(--sidebar-width)"`). Must be a
+   * literal in the consumer's source so Tailwind generates it.
+   */
+  widthClassName?: string;
+  /**
+   * Literal collapsed-state utility for the gap spacer (e.g.
+   * `"group-data-[collapsible=offcanvas]:w-0"`).
+   */
+  spacerCollapsedClassName?: string;
+  /**
+   * Literal off-screen slide utilities for the fixed container, keyed by side
+   * (e.g. `left: "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]"`).
+   */
+  containerSlideClassNames?: Record<CollapsiblePanelSide, string>;
+}
+
+/** Data attributes for the panel's `group` element. */
+export interface CollapsiblePanelAttrs {
+  "data-state": CollapsiblePanelState;
+  "data-side": CollapsiblePanelSide;
+}
+
+export interface UseCollapsiblePanelReturn {
+  /** Resolved open state (controlled prop wins). */
+  open: boolean;
+  /** `"expanded"` when open, `"collapsed"` when closed. */
+  state: CollapsiblePanelState;
+  side: CollapsiblePanelSide;
+  /** Set the open state (accepts a value or an updater fn). */
+  setOpen: (open: boolean | ((open: boolean) => boolean)) => void;
+  toggle: () => void;
+  /** `data-state`/`data-side` for the group element wrapping both fragments. */
+  attrs: CollapsiblePanelAttrs;
+  /** The gap-spacer fragment: reserves/releases the inline width. */
+  spacerClassName: string;
+  /** The fixed-container fragment: slides the panel off-screen. */
+  containerClassName: string;
+}
+
+export function useCollapsiblePanel({
+  side = "left",
+  open: openProp,
+  defaultOpen = true,
+  onOpenChange,
+  widthClassName = DEFAULT_WIDTH_CLASSNAME,
+  spacerCollapsedClassName = DEFAULT_SPACER_COLLAPSED_CLASSNAME,
+  containerSlideClassNames = DEFAULT_CONTAINER_SLIDE_CLASSNAMES,
+}: UseCollapsiblePanelOptions = {}): UseCollapsiblePanelReturn {
+  // Controlled/uncontrolled per component-api.md: controlled iff the `open`
+  // prop is provided; the mode never flips mid-life.
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const isControlled = openProp !== undefined;
+  const open = isControlled ? openProp : uncontrolledOpen;
+
+  const setOpen = useCallback(
+    (value: boolean | ((open: boolean) => boolean)) => {
+      const next = typeof value === "function" ? value(open) : value;
+      if (!isControlled) setUncontrolledOpen(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange, open],
+  );
+
+  const toggle = useCallback(() => setOpen((o) => !o), [setOpen]);
+
+  const state: CollapsiblePanelState = open ? "expanded" : "collapsed";
+
+  // The two class fragments — the Sidebar collapse mechanism verbatim
+  // (research 09 §A.1): assembly order is part of the contract (it is what
+  // keeps Sidebar's emitted className strings byte-identical).
+  const spacerClassName = useMemo(
+    () =>
+      cn(
+        "relative",
+        widthClassName,
+        "bg-transparent transition-[width] duration-base ease-linear",
+        spacerCollapsedClassName,
+      ),
+    [spacerCollapsedClassName, widthClassName],
+  );
+  const containerClassName = useMemo(
+    () =>
+      cn(
+        "fixed inset-y-0 z-10 hidden h-svh",
+        widthClassName,
+        "transition-[left,right,width] duration-base ease-linear md:flex",
+        containerSlideClassNames[side],
+      ),
+    [containerSlideClassNames, side, widthClassName],
+  );
+
+  const attrs = useMemo<CollapsiblePanelAttrs>(
+    () => ({ "data-state": state, "data-side": side }),
+    [side, state],
+  );
+
+  return useMemo(
+    () => ({ open, state, side, setOpen, toggle, attrs, spacerClassName, containerClassName }),
+    [open, state, side, setOpen, toggle, attrs, spacerClassName, containerClassName],
+  );
+}

package/src/components/color-picker/color-picker.stories.tsx

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { useState } from "react";
+import { ColorPicker } from "./color-picker";
+
+const meta = {
+  title: "Forms/ColorPicker",
+  component: ColorPicker,
+  tags: ["autodocs"],
+  argTypes: {
+    value: {
+      description: "Controlled color token name or raw hex string.",
+      control: "text",
+      table: { category: "State" },
+    },
+    defaultValue: {
+      description: "Uncontrolled initial color value.",
+      control: "text",
+      table: { category: "State" },
+    },
+    allowCustom: {
+      description: "Show a free-form hex input below the swatches (not theme-aware).",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    swatches: {
+      description: "Subset of ColorToken names to display as swatches.",
+      control: false,
+      table: { category: "Content" },
+    },
+    onValueChange: {
+      description: "Called when the selected color changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    "aria-label": {
+      description: "Accessible label for the trigger button.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the root element.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof ColorPicker>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { defaultValue: "chart-1" },
+  // Opens the popover, confirms the swatch radiogroup is visible.
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByRole("button", { name: /pick color/i });
+    await expect(trigger).toBeInTheDocument();
+    await userEvent.click(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    const group = await body.findByRole("radiogroup", { name: /color swatches/i });
+    await expect(group).toBeInTheDocument();
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [color, setColor] = useState<string>("primary");
+    return (
+      <div className="flex flex-col gap-2">
+        <ColorPicker value={color} onValueChange={setColor} />
+        <p className="text-body text-muted-foreground">Selected: {color}</p>
+      </div>
+    );
+  },
+};
+
+export const ChartTokensOnly: Story = {
+  args: {
+    defaultValue: "chart-1",
+    swatches: ["chart-1", "chart-2", "chart-3", "chart-4", "chart-5"],
+  },
+};
+
+export const WithCustomHex: Story = {
+  args: { defaultValue: "primary", allowCustom: true },
+};
+
+export const StatusTokens: Story = {
+  args: {
+    defaultValue: "success",
+    swatches: ["success", "warning", "destructive", "info"],
+  },
+};