@elabs-ai/components-ui 4.0.0

package/src/components/spinner/spinner.stories.tsx

@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Spinner } from "./spinner";
+const meta = {
+  title: "Display/Spinner",
+  component: Spinner,
+  tags: ["autodocs"],
+  argTypes: {
+    label: {
+      description:
+        'Accessible label read by screen readers (role="status" + aria-label). Default: "Loading".',
+      control: "text",
+      table: { category: "Content" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn() — use to control size and color.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof Spinner>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = { render: () => <Spinner className="size-6" /> };
+export const Large: Story = { render: () => <Spinner className="size-10" /> };
+export const CustomLabel: Story = {
+  render: () => <Spinner className="size-6" label="Processing…" />,
+};

package/src/components/spinner/spinner.tsx

@@ -0,0 +1,19 @@
+import { Loader2 } from "lucide-react";
+import { cn } from "../../lib/cn";
+
+export interface SpinnerProps extends React.SVGProps<SVGSVGElement> {
+  /** Accessible label; defaults to "Loading". */
+  label?: string;
+}
+
+/** Indeterminate spinner with an accessible label. */
+export function Spinner({ className, label = "Loading", ...props }: SpinnerProps) {
+  return (
+    <Loader2
+      role="status"
+      aria-label={label}
+      className={cn("size-4 animate-spin text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}

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

@@ -0,0 +1 @@
+export { SplitPanel, type SplitPanelProps, type SplitPanelTone } from "./split-panel";

package/src/components/split-panel/split-panel.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { SplitPanel } from "./split-panel";
+
+const meta = {
+  title: "Layout/SplitPanel",
+  component: SplitPanel,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof SplitPanel>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const MasterDetail: Story = {
+  render: () => (
+    <div className="h-[400px]">
+      <SplitPanel
+        startSize="280px"
+        start={<div className="space-y-2 p-4 text-body">List pane</div>}
+        end={<div className="p-6 text-body text-muted-foreground">Detail pane</div>}
+      />
+    </div>
+  ),
+};
+
+/**
+ * Ground-offset tiering: the detail pane is RAISED as a white card (`endTone="card"`)
+ * on the page/list ground, so it reads as a distinct surface in every theme without a
+ * heavier divider — a card is lighter than the ground in both light and dark (in light
+ * the page itself is recessed below white; see research/structural-design 08 §H). A
+ * `muted` list well is a light-theme-only enhancement (in dark, `--surface-muted` reads
+ * lighter than `--card`), so this demo keeps the list `plain` to read correctly across
+ * all three themes.
+ */
+export const Tiered: Story = {
+  render: () => (
+    <div className="h-[400px] bg-background p-4">
+      <SplitPanel
+        startSize="280px"
+        endTone="card"
+        divider={false}
+        className="rounded-lg"
+        endClassName="rounded-e-lg"
+        start={
+          <div className="space-y-2 p-4 text-body">
+            <p className="font-medium">Produced assets</p>
+            <p className="text-muted-foreground">board-note.md</p>
+            <p className="text-muted-foreground">q3-vs-q2.csv</p>
+          </div>
+        }
+        end={
+          <div className="space-y-3 p-6 text-body">
+            <p className="font-medium">board-note.md</p>
+            <p className="text-muted-foreground">
+              The raised detail card lifts off the list/page ground by surface offset.
+            </p>
+          </div>
+        }
+      />
+    </div>
+  ),
+};

package/src/components/split-panel/split-panel.test.tsx

@@ -0,0 +1,38 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { SplitPanel } from "./split-panel";
+
+describe("SplitPanel", () => {
+  it("renders both panes", () => {
+    const { getByText } = render(<SplitPanel start={<>List</>} end={<>Detail</>} />);
+    expect(getByText("List")).toBeInTheDocument();
+    expect(getByText("Detail")).toBeInTheDocument();
+  });
+
+  // The pane content is bare text, so getByText returns the pane <div> itself.
+  it("defaults to plain tone (no ground offset) and a divider on the end pane", () => {
+    const { getByText } = render(<SplitPanel start={<>List</>} end={<>Detail</>} />);
+    const startPane = getByText("List");
+    const endPane = getByText("Detail");
+    expect(startPane.className).not.toMatch(/bg-surface-muted|bg-card/);
+    expect(endPane.className).not.toMatch(/bg-surface-muted|bg-card/);
+    expect(endPane.className).toMatch(/border-s/);
+  });
+
+  it("applies the ground-offset tones: muted well + raised card", () => {
+    const { getByText } = render(
+      <SplitPanel
+        startTone="muted"
+        endTone="card"
+        divider={false}
+        start={<>List</>}
+        end={<>Detail</>}
+      />,
+    );
+    expect(getByText("List").className).toMatch(/bg-surface-muted/);
+    const endPane = getByText("Detail");
+    expect(endPane.className).toMatch(/bg-card/);
+    expect(endPane.className).toMatch(/shadow-sm/);
+    expect(endPane.className).not.toMatch(/border-s/);
+  });
+});

package/src/components/split-panel/split-panel.tsx

@@ -0,0 +1,95 @@
+import { type ReactNode } from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/cn";
+
+/**
+ * Per-pane surface tone — the ground-offset tiering axis (research 08 §H, #193).
+ * `plain` keeps the ambient ground (default; non-breaking). `card` RAISES the pane as
+ * a white `bg-card` + `shadow-sm` and is robust across all three themes — a card is
+ * lighter than the page ground in BOTH light and dark, so it always reads as raised.
+ * `muted` (`bg-surface-muted`) reads as a recessed well ONLY in light themes; in dark
+ * themes `--surface-muted` is lighter than `--card`, so a `muted` pane reads as a faint
+ * raised tint, not a recess (dark-mode layering only goes UP — there is no surface below
+ * the page ground). For a guaranteed cross-theme raise/recess contrast, raise the focus
+ * pane with `card` and leave the other `plain`.
+ */
+const paneToneVariants = cva("min-h-0 min-w-0 overflow-auto", {
+  variants: {
+    tone: {
+      plain: "",
+      muted: "bg-surface-muted",
+      card: "bg-card shadow-sm",
+    },
+  },
+  defaultVariants: { tone: "plain" },
+});
+
+export type SplitPanelTone = NonNullable<VariantProps<typeof paneToneVariants>["tone"]>;
+
+export interface SplitPanelProps {
+  start: ReactNode;
+  end: ReactNode;
+  /** Layout axis. Defaults to "horizontal" (side-by-side). */
+  direction?: "horizontal" | "vertical";
+  /**
+   * Size of the START pane as a CSS grid track (e.g. "320px", "40%", "1fr").
+   * The END pane fills the remainder. Defaults to "1fr" (equal split).
+   */
+  startSize?: string;
+  /** Show a thin divider between panes. Defaults to true. */
+  divider?: boolean;
+  /** Surface tone of the START pane (ground-offset tiering). Defaults to "plain". */
+  startTone?: SplitPanelTone;
+  /** Surface tone of the END pane (ground-offset tiering). Defaults to "plain". */
+  endTone?: SplitPanelTone;
+  className?: string;
+  startClassName?: string;
+  endClassName?: string;
+}
+
+/**
+ * Two-pane layout for master/detail, editor/preview and inspector workflows.
+ * Static sizing by design (predictable in tests/SSR); for drag-to-resize wrap
+ * with a resize hook or compose `react-resizable-panels` at the app level.
+ *
+ * For a master/detail surface where the detail should read as a raised card on a
+ * recessed list, use `startTone="muted" endTone="card"` (ground-offset tiering).
+ */
+export function SplitPanel({
+  start,
+  end,
+  direction = "horizontal",
+  startSize = "1fr",
+  divider = true,
+  startTone = "plain",
+  endTone = "plain",
+  className,
+  startClassName,
+  endClassName,
+}: SplitPanelProps) {
+  const isHorizontal = direction === "horizontal";
+  const style = isHorizontal
+    ? { gridTemplateColumns: `${startSize} minmax(0, 1fr)` }
+    : { gridTemplateRows: `${startSize} minmax(0, 1fr)` };
+  return (
+    <div
+      className={cn(
+        "grid h-full w-full",
+        isHorizontal ? "grid-flow-col" : "grid-flow-row",
+        className,
+      )}
+      style={style}
+    >
+      <div className={cn(paneToneVariants({ tone: startTone }), startClassName)}>{start}</div>
+      <div
+        className={cn(
+          paneToneVariants({ tone: endTone }),
+          divider && (isHorizontal ? "border-s" : "border-t"),
+          endClassName,
+        )}
+      >
+        {end}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1 @@
+export { StatePanel, statePanelVariants, type StatePanelProps } from "./state-panel";

package/src/components/state-panel/state-panel.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "../button";
+import { StatePanel } from "./state-panel";
+
+const meta = {
+  title: "States/StatePanel",
+  component: StatePanel,
+  tags: ["autodocs"],
+  argTypes: {
+    kind: {
+      control: "select",
+      options: ["empty", "error", "loading"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+  },
+} satisfies Meta<typeof StatePanel>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Empty: Story = {
+  args: {
+    kind: "empty",
+    title: "No projects yet",
+    description: "Create your first project to get started.",
+    actions: <Button size="sm">New project</Button>,
+  },
+};
+
+export const Error: Story = {
+  args: {
+    kind: "error",
+    actions: (
+      <Button size="sm" variant="outline">
+        Retry
+      </Button>
+    ),
+  },
+};
+
+export const ErrorCustom: Story = {
+  name: "Error (custom title)",
+  args: {
+    kind: "error",
+    title: "Failed to load data",
+    description: "The server returned an unexpected response.",
+    actions: (
+      <Button size="sm" variant="outline">
+        Try again
+      </Button>
+    ),
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    kind: "loading",
+    loadingLabel: "Loading workspace…",
+  },
+};
+
+export const LoadingLarge: Story = {
+  name: "Loading (large spinner)",
+  args: {
+    kind: "loading",
+    size: "lg",
+    loadingLabel: "Fetching results…",
+  },
+};
+
+export const EmptyNoIcon: Story = {
+  name: "Empty (no icon, no actions)",
+  args: {
+    kind: "empty",
+    title: "Nothing here",
+    description: "Items will appear here once available.",
+  },
+};

package/src/components/state-panel/state-panel.test.tsx

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { StatePanel } from "./state-panel";
+
+describe("StatePanel", () => {
+  it("renders empty kind with title and description", () => {
+    render(<StatePanel kind="empty" title="No items" description="Nothing here yet" />);
+    expect(screen.getByText("No items")).toBeInTheDocument();
+    expect(screen.getByText("Nothing here yet")).toBeInTheDocument();
+    // No ARIA role on empty panels
+    expect(screen.queryByRole("status")).toBeNull();
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  it("renders error kind with role=alert, structural eyebrow, and default copy", () => {
+    render(<StatePanel kind="error" />);
+    const alert = screen.getByRole("alert");
+    expect(alert).toBeInTheDocument();
+    // Structural eyebrow label — non-color cue for monochrome themes (#179).
+    expect(screen.getByText("Error")).toBeInTheDocument();
+    expect(screen.getByText("Something went wrong")).toBeInTheDocument();
+    expect(screen.getByText("An unexpected error occurred. Please try again.")).toBeInTheDocument();
+    // data-kind attribute hook for future CSS targeting.
+    expect(alert).toHaveAttribute("data-kind", "error");
+  });
+
+  it("renders error kind with custom title", () => {
+    render(<StatePanel kind="error" title="Custom error" description="Custom description" />);
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText("Custom error")).toBeInTheDocument();
+    expect(screen.getByText("Custom description")).toBeInTheDocument();
+  });
+
+  it("renders loading kind with role=status and live region", () => {
+    render(<StatePanel kind="loading" loadingLabel="Loading data…" />);
+    const status = screen.getByRole("status");
+    expect(status).toBeInTheDocument();
+    expect(status).toHaveAttribute("aria-live", "polite");
+    expect(screen.getByText("Loading data…")).toBeInTheDocument();
+  });
+
+  it("renders loading kind with default label", () => {
+    render(<StatePanel kind="loading" />);
+    expect(screen.getByText("Loading…")).toBeInTheDocument();
+  });
+
+  it("renders actions when provided", () => {
+    render(
+      <StatePanel kind="empty" title="Empty" actions={<button type="button">New item</button>} />,
+    );
+    expect(screen.getByRole("button", { name: "New item" })).toBeInTheDocument();
+  });
+
+  it("renders custom icon when provided", () => {
+    render(
+      <StatePanel
+        kind="empty"
+        title="Custom icon"
+        icon={<span data-testid="custom-icon">icon</span>}
+      />,
+    );
+    expect(screen.getByTestId("custom-icon")).toBeInTheDocument();
+  });
+});

package/src/components/state-panel/state-panel.tsx

@@ -0,0 +1,167 @@
+import { type ReactNode } from "react";
+import { CircleAlert } from "lucide-react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/cn";
+
+// ─── Variants ────────────────────────────────────────────────────────────────
+
+export const statePanelVariants = cva(
+  [
+    "flex flex-col items-center justify-center gap-3 rounded-xl px-6 py-12 text-center",
+    "animate-in fade-in slide-in-from-bottom-2 duration-base ease-entrance",
+  ],
+  {
+    variants: {
+      kind: {
+        empty: "border border-dashed bg-surface",
+        // error: primary cue is color (destructive bg/border); structural cue
+        // (border-s-4 + border-border-strong top strip) survives monochrome /
+        // a monochrome palette so the panel is distinguishable from empty/loading even
+        // without hue. border-border-strong satisfies WCAG 1.4.11 non-text contrast.
+        error: "border border-destructive/30 bg-destructive/5 border-s-4 border-s-border-strong",
+        loading: "",
+      },
+    },
+    defaultVariants: { kind: "empty" },
+  },
+);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface StatePanelProps extends VariantProps<typeof statePanelVariants> {
+  /**
+   * The visual/semantic kind of state.
+   * - `"empty"` — neutral "nothing here yet" (dashed border, surface bg).
+   * - `"error"` — recoverable failure (destructive border/bg, alert role).
+   * - `"loading"` — in-progress (spinner, status/live-region role).
+   */
+  kind?: "empty" | "error" | "loading";
+  /** Heading text. */
+  title?: ReactNode;
+  /** Supporting description below the title. */
+  description?: ReactNode;
+  /**
+   * Icon or illustration shown above the title.
+   * For `"error"` defaults to a built-in warning triangle.
+   * For `"loading"` defaults to an animated spinner.
+   */
+  icon?: ReactNode;
+  /** Accessible label for the spinner in loading state. @default "Loading…" */
+  loadingLabel?: string;
+  /** Spinner size (loading kind only). @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Primary / secondary action buttons. */
+  actions?: ReactNode;
+  className?: string;
+}
+
+// ─── Default icons ────────────────────────────────────────────────────────────
+
+const sizeMap: Record<string, string> = { sm: "size-4", md: "size-6", lg: "size-8" };
+
+function DefaultSpinner({ size = "md" }: { size?: "sm" | "md" | "lg" }) {
+  return (
+    <svg
+      className={cn("animate-spin text-muted-foreground", sizeMap[size])}
+      viewBox="0 0 24 24"
+      fill="none"
+      aria-hidden="true"
+    >
+      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 0 1 8-8v4a4 4 0 0 0-4 4H4Z" />
+    </svg>
+  );
+}
+
+function DefaultErrorIcon() {
+  // Use the Lucide CircleAlert icon (solid ring + exclamation) for the error state.
+  // Rendered at size-10 so it reads clearly even at small panel sizes.
+  return <CircleAlert className="size-10" aria-hidden="true" />;
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+/**
+ * Unified state panel covering empty, error, and loading states.
+ * Replaces the three separate `EmptyState` / `ErrorState` / `LoadingState` components
+ * while keeping those as back-compat thin wrappers.
+ */
+export function StatePanel({
+  kind = "empty",
+  title,
+  description,
+  icon,
+  loadingLabel = "Loading…",
+  size = "md",
+  actions,
+  className,
+}: StatePanelProps) {
+  const isLoading = kind === "loading";
+  const isError = kind === "error";
+
+  // Role: loading → status + live region; error → alert; empty → (none needed).
+  const roleProps = isLoading
+    ? ({ role: "status", "aria-live": "polite" } as const)
+    : isError
+      ? ({ role: "alert" } as const)
+      : {};
+
+  // Default title / description fallbacks for error state (mirroring old ErrorState).
+  const resolvedTitle = title ?? (isError ? "Something went wrong" : undefined);
+  const resolvedDescription =
+    description ?? (isError ? "An unexpected error occurred. Please try again." : undefined);
+
+  // Resolve displayed icon.
+  let resolvedIcon: ReactNode;
+  if (icon !== undefined) {
+    resolvedIcon = icon;
+  } else if (isLoading) {
+    resolvedIcon = <DefaultSpinner size={size} />;
+  } else if (isError) {
+    resolvedIcon = <DefaultErrorIcon />;
+  }
+
+  return (
+    <div data-kind={kind} className={cn(statePanelVariants({ kind }), className)} {...roleProps}>
+      {/* Error eyebrow: "Error" label shown above the icon so the panel reads
+          as an error structurally even in monochrome themes. The
+          eyebrow uses text-destructive which resolves to a drawable
+          foreground at high decoration — combined with the thick left border from
+          statePanelVariants it gives two non-color structural cues. */}
+      {isError && (
+        <span className="text-xs font-semibold uppercase tracking-widest text-destructive">
+          Error
+        </span>
+      )}
+
+      {resolvedIcon ? (
+        // Error icon keeps text-destructive (not muted) so it stays visible even
+        // when rendered at low contrast. In monochrome themes the icon shape
+        // (CircleAlert) carries the cue; the color is supplemental.
+        <div
+          className={cn("[&_svg]:size-10", isError ? "text-destructive" : "text-muted-foreground")}
+        >
+          {resolvedIcon}
+        </div>
+      ) : null}
+
+      {(resolvedTitle || resolvedDescription) && (
+        <div className="space-y-1">
+          {resolvedTitle && (
+            <h3 className="text-sm font-semibold text-foreground">{resolvedTitle}</h3>
+          )}
+          {resolvedDescription && (
+            <p className="mx-auto max-w-sm text-sm text-muted-foreground">{resolvedDescription}</p>
+          )}
+        </div>
+      )}
+
+      {/* Loading label (visually shown as supporting text; also the live-region content). */}
+      {isLoading && loadingLabel && (
+        <span className="text-sm text-muted-foreground">{loadingLabel}</span>
+      )}
+
+      {actions ? <div className="mt-1 flex items-center gap-2">{actions}</div> : null}
+    </div>
+  );
+}

package/src/components/status-badge/index.ts

@@ -0,0 +1,18 @@
+export {
+  StatusBadge,
+  StatusIcon,
+  statusBadgeVariants,
+  fromTimelineStatus,
+  isCustomStatus,
+  STATUSES,
+  STATUS_LABELS,
+  STATUS_TONES,
+  STATUS_ROLE,
+  STATUS_TONE_ICONS,
+  type Status,
+  type StatusBadgeProps,
+  type StatusIconProps,
+  type StatusTone,
+  type CustomStatus,
+  type TimelineStatus,
+} from "./status-badge";