@elabs-ai/components-ui 4.0.0

package/src/components/alert/alert.stories.tsx

@@ -0,0 +1,156 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AlertTriangle, CheckCircle2, Info } from "lucide-react";
+import { expect } from "storybook/test";
+import { Alert, AlertDescription, AlertTitle } from "./alert";
+const meta = {
+  title: "States/Alert",
+  component: Alert,
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      description: "Visual tone of the alert banner.",
+      control: { type: "select" },
+      options: ["default", "info", "success", "warning", "destructive"],
+      table: { category: "Appearance" },
+    },
+    role: {
+      description:
+        'ARIA role. Use "alert" for assertive announcements or "group" for panels with focusable controls.',
+      control: { type: "select" },
+      options: ["alert", "group", "status"],
+      table: { category: "Accessibility" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the alert container.",
+      control: "text",
+      table: { category: "Styling" },
+    },
+    children: {
+      description: "Compose AlertTitle and AlertDescription inside.",
+      control: false,
+      table: { category: "Content" },
+    },
+  },
+} satisfies Meta<typeof Alert>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Info_: Story = {
+  name: "Info",
+  render: () => (
+    <Alert variant="info" className="max-w-md">
+      <Info />
+      <AlertTitle>Heads up</AlertTitle>
+      <AlertDescription>This deploy includes a schema migration.</AlertDescription>
+    </Alert>
+  ),
+};
+export const Destructive: Story = {
+  render: () => (
+    <Alert variant="destructive" className="max-w-md">
+      <AlertTriangle />
+      <AlertTitle>Error</AlertTitle>
+      <AlertDescription>Your session has expired.</AlertDescription>
+    </Alert>
+  ),
+};
+
+/**
+ * `default` and `success` were selectable in the controls panel
+ * (`argTypes.variant.options`) but never actually rendered by any story
+ * (#388) — so neither one ever reached the blocking interaction + axe job.
+ * This renders them alongside `info`/`warning` to close that gap.
+ *
+ * `destructive` is intentionally NOT repeated here: it already has its own
+ * dedicated `Destructive` story above, with a known, separately-tracked
+ * contrast exemption (`states-alert--destructive` in
+ * scripts/a11y-baseline.json, #381) — folding it into this new story id would
+ * launder that pre-existing violation onto a brand-new, unbaselined surface.
+ */
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex max-w-md flex-col gap-3">
+      <Alert variant="default">
+        <AlertTitle>Default</AlertTitle>
+        <AlertDescription>Neutral tone — no semantic status implied.</AlertDescription>
+      </Alert>
+      <Alert variant="info">
+        <Info />
+        <AlertTitle>Info</AlertTitle>
+        <AlertDescription>This deploy includes a schema migration.</AlertDescription>
+      </Alert>
+      <Alert variant="success">
+        <CheckCircle2 />
+        <AlertTitle>Success</AlertTitle>
+        <AlertDescription>Your changes were saved.</AlertDescription>
+      </Alert>
+      <Alert variant="warning">
+        <AlertTriangle />
+        <AlertTitle>Warning</AlertTitle>
+        <AlertDescription>Double-check before continuing.</AlertDescription>
+      </Alert>
+    </div>
+  ),
+};
+
+/**
+ * `AlertTitle` defaults to `<h5>` (unchanged) but accepts `as` to render at a
+ * different heading level, avoiding a skipped-level jump when the alert sits
+ * inline in a form under an `<h2>`/`<h3>` (#329).
+ *
+ * Uses `variant="warning"`, not `"destructive"` — the destructive variant's
+ * text-on-tint contrast is a pre-existing, separately tracked issue
+ * (`states-alert--destructive` in scripts/a11y-baseline.json) unrelated to
+ * this fix; reusing it here would launder a second, avoidable a11y violation
+ * into a brand-new story.
+ */
+export const InlineFormError: Story = {
+  render: () => (
+    <div className="flex max-w-md flex-col gap-3">
+      <h2 className="text-title font-semibold text-foreground">Payment details</h2>
+      <Alert variant="warning">
+        <AlertTriangle />
+        <AlertTitle as="h3">Card declined</AlertTitle>
+        <AlertDescription>Your card was declined — try another payment method.</AlertDescription>
+      </Alert>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const heading = canvas.getByRole("heading", { level: 3, name: "Card declined" });
+    await expect(heading.tagName).toBe("H3");
+  },
+};
+
+/**
+ * `AlertDescription` gains an opt-in `measure` prop that caps genuine prose to
+ * a readable line length (`max-w-prose`, ~65ch) instead of running edge to
+ * edge in a wide alert (#339). Off by default.
+ */
+export const DescriptionMeasure: Story = {
+  render: () => (
+    <div className="flex w-[900px] flex-col gap-4">
+      <Alert variant="info" className="w-full">
+        <Info />
+        <AlertTitle>Uncapped (default)</AlertTitle>
+        <AlertDescription>
+          This migration note runs the full width of a very wide alert banner, which makes it
+          materially harder to scan once the line gets long enough for the eye to lose its place
+          between lines.
+        </AlertDescription>
+      </Alert>
+      <Alert variant="info" className="w-full">
+        <Info />
+        <AlertTitle>Capped via `measure`</AlertTitle>
+        <AlertDescription measure>
+          This migration note is capped to a readable prose measure even inside a very wide banner,
+          so each line stays short enough to read comfortably.
+        </AlertDescription>
+      </Alert>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const capped = canvas.getByText(/capped to a readable prose measure/);
+    await expect(capped).toHaveClass("max-w-prose");
+    const uncapped = canvas.getByText(/runs the full width/);
+    await expect(uncapped).not.toHaveClass("max-w-prose");
+  },
+};

package/src/components/alert/alert.test.tsx

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Alert, AlertDescription, AlertTitle } from "./alert";
+describe("Alert", () => {
+  it("renders with role=alert and a title", () => {
+    render(
+      <Alert>
+        <AlertTitle>Heads up</AlertTitle>
+      </Alert>,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText("Heads up")).toBeInTheDocument();
+  });
+
+  // --- AlertTitle `as` seam + ref-type fix (#329) ---
+  it("AlertTitle defaults to <h5> (byte-identical to pre-#329 output)", () => {
+    render(<AlertTitle>Default level</AlertTitle>);
+    const heading = screen.getByRole("heading", { level: 5, name: "Default level" });
+    expect(heading.tagName).toBe("H5");
+  });
+
+  it("AlertTitle renders the requested heading level via `as` (#329)", () => {
+    render(<AlertTitle as="h3">Inline error</AlertTitle>);
+    const heading = screen.getByRole("heading", { level: 3, name: "Inline error" });
+    expect(heading.tagName).toBe("H3");
+    expect(heading).toHaveClass("mb-1", "font-medium", "leading-none", "tracking-tight");
+  });
+
+  // --- AlertDescription `measure` cap (#339) ---
+  it("AlertDescription has no max-w cap by default (#339)", () => {
+    render(<AlertDescription>Short note</AlertDescription>);
+    expect(screen.getByText("Short note")).not.toHaveClass("max-w-prose");
+  });
+
+  it("AlertDescription caps to a readable measure when `measure` is set (#339)", () => {
+    render(
+      <AlertDescription measure>
+        Genuine prose that should not run edge to edge in a wide alert.
+      </AlertDescription>,
+    );
+    const el = screen.getByText(/Genuine prose/);
+    expect(el).toHaveClass("max-w-prose");
+    expect(el).toHaveClass("text-muted-foreground");
+  });
+
+  // role override seam (#191, research 11 §B.3): a pending decision with
+  // focusable controls must be a labelled region, not an assertive live region.
+  it("accepts a role override (default stays alert)", () => {
+    render(
+      <Alert aria-label="Pending decision" role="group">
+        <AlertTitle>Approve this?</AlertTitle>
+      </Alert>,
+    );
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+    expect(screen.getByRole("group", { name: "Pending decision" })).toBeInTheDocument();
+  });
+});

package/src/components/alert/alert.tsx

@@ -0,0 +1,91 @@
+import { forwardRef, type HTMLAttributes } from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/cn";
+
+export const alertVariants = cva(
+  "relative w-full rounded-lg border px-4 py-3 text-sm [&>svg]:absolute [&>svg]:start-4 [&>svg]:top-4 [&>svg]:size-4 [&>svg]:text-current [&>svg~*]:ps-7",
+  {
+    variants: {
+      variant: {
+        default: "bg-card text-card-foreground",
+        info: "border-info/40 bg-info/10 text-foreground",
+        success: "border-success/40 bg-success/10 text-foreground",
+        warning: "border-warning/50 bg-warning/10 text-foreground",
+        destructive:
+          "border-destructive/40 bg-destructive/10 text-destructive [&>svg]:text-destructive",
+      },
+    },
+    defaultVariants: { variant: "default" },
+  },
+);
+
+export const Alert = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>
+>(function Alert(
+  // `role` is an explicit override seam (default "alert"): a PENDING decision
+  // containing focusable controls (e.g. @elabs-ai/components-ai ApprovalCard) must be a
+  // labelled region (`role="group"` + aria-labelledby), not an assertive live
+  // region (research/structural-design/11 §B.3).
+  { className, variant, role = "alert", ...props },
+  ref,
+) {
+  return (
+    <div ref={ref} role={role} className={cn(alertVariants({ variant }), className)} {...props} />
+  );
+});
+
+export interface AlertTitleProps extends HTMLAttributes<HTMLHeadingElement> {
+  /**
+   * Render at a different heading level to fit the surrounding document
+   * outline (#329). The visual (`mb-1 font-medium leading-none
+   * tracking-tight`) is identical at every level. @default "h5"
+   */
+  as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+}
+
+// Ref type matches the rendered element (`HTMLHeadingElement` for every `as`
+// value) — previously mismatched to `HTMLParagraphElement` (#329).
+export const AlertTitle = forwardRef<HTMLHeadingElement, AlertTitleProps>(function AlertTitle(
+  { className, as: Tag = "h5", ...props },
+  ref,
+) {
+  return (
+    <Tag
+      ref={ref}
+      className={cn("mb-1 font-medium leading-none tracking-tight", className)}
+      {...props}
+    />
+  );
+});
+
+export interface AlertDescriptionProps extends HTMLAttributes<HTMLParagraphElement> {
+  /**
+   * Cap the line length to a readable prose measure (`max-w-prose`, ~65ch)
+   * for genuine paragraph content (#339). Off by default — short,
+   * label-style descriptions should stay full width.
+   */
+  measure?: boolean;
+}
+
+// NOTE (#329 AC): checked for the same ref-type mismatch as `AlertTitle` —
+// `AlertDescription` renders a `<div>`, not a heading, so it needs no `as`
+// heading seam. Its own generic (`HTMLParagraphElement` on a rendered `<div>`)
+// is a pre-existing, unrelated mismatch; left as-is (out of scope for #329,
+// which is scoped to heading semantics, and not requested by #339 either) to
+// avoid a ref-type change unrelated to either issue's acceptance criteria.
+export const AlertDescription = forwardRef<HTMLParagraphElement, AlertDescriptionProps>(
+  function AlertDescription({ className, measure, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "text-sm [&_p]:leading-relaxed text-muted-foreground",
+          measure && "max-w-prose",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);

package/src/components/alert/index.ts

@@ -0,0 +1,8 @@
+export {
+  Alert,
+  AlertTitle,
+  type AlertTitleProps,
+  AlertDescription,
+  type AlertDescriptionProps,
+  alertVariants,
+} from "./alert";

package/src/components/alert-dialog/alert-dialog.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor, within } from "storybook/test";
+import { Button } from "../button";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "./alert-dialog";
+const meta = {
+  title: "Overlays/AlertDialog",
+  component: AlertDialog,
+  tags: ["autodocs"],
+  argTypes: {
+    open: {
+      description: "Controlled open state of the dialog.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    defaultOpen: {
+      description: "Uncontrolled initial open state.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    onOpenChange: {
+      description: "Callback when the open state changes.",
+      control: false,
+      table: { category: "Events" },
+    },
+  },
+} satisfies Meta<typeof AlertDialog>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="destructive">Delete</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+          <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction>Delete</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  ),
+  // Opens the alert dialog (portalled to body), asserts the title and both action
+  // buttons are visible, then cancels to close it.
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    await userEvent.click(canvas.getByRole("button", { name: /delete/i }));
+    const body = within(canvasElement.ownerDocument.body);
+    const dialog = await body.findByRole("alertdialog");
+    await waitFor(() => expect(within(dialog).getByText("Are you sure?")).toBeVisible());
+    await waitFor(() =>
+      expect(within(dialog).getByRole("button", { name: /cancel/i })).toBeVisible(),
+    );
+    await waitFor(() =>
+      expect(within(dialog).getByRole("button", { name: /delete/i })).toBeVisible(),
+    );
+    // Cancel dismisses the dialog
+    await userEvent.click(within(dialog).getByRole("button", { name: /cancel/i }));
+  },
+};

package/src/components/alert-dialog/alert-dialog.tsx

@@ -0,0 +1,104 @@
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ElementRef,
+  type HTMLAttributes,
+} from "react";
+import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
+import { cn } from "../../lib/cn";
+import { buttonVariants } from "../button";
+
+export const AlertDialog = AlertDialogPrimitive.Root;
+export const AlertDialogTrigger = AlertDialogPrimitive.Trigger;
+export const AlertDialogPortal = AlertDialogPrimitive.Portal;
+
+const AlertDialogOverlay = forwardRef<
+  ElementRef<typeof AlertDialogPrimitive.Overlay>,
+  ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Overlay>
+>(function AlertDialogOverlay({ className, ...props }, ref) {
+  return (
+    <AlertDialogPrimitive.Overlay
+      ref={ref}
+      className={cn(
+        "fixed inset-0 z-50 bg-foreground/50 backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export const AlertDialogContent = forwardRef<
+  ElementRef<typeof AlertDialogPrimitive.Content>,
+  ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>
+>(function AlertDialogContent({ className, ...props }, ref) {
+  return (
+    <AlertDialogPortal>
+      <AlertDialogOverlay />
+      <AlertDialogPrimitive.Content
+        ref={ref}
+        className={cn(
+          "fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-card p-6 text-card-foreground shadow-ring-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+          className,
+        )}
+        {...props}
+      />
+    </AlertDialogPortal>
+  );
+});
+
+export function AlertDialogHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex flex-col gap-1.5 text-start", className)} {...props} />;
+}
+export function AlertDialogFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn("flex flex-col-reverse gap-2 sm:flex-row sm:justify-end", className)}
+      {...props}
+    />
+  );
+}
+export const AlertDialogTitle = forwardRef<
+  ElementRef<typeof AlertDialogPrimitive.Title>,
+  ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Title>
+>(function AlertDialogTitle({ className, ...props }, ref) {
+  return (
+    <AlertDialogPrimitive.Title
+      ref={ref}
+      className={cn("text-lg font-semibold", className)}
+      {...props}
+    />
+  );
+});
+export const AlertDialogDescription = forwardRef<
+  ElementRef<typeof AlertDialogPrimitive.Description>,
+  ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Description>
+>(function AlertDialogDescription({ className, ...props }, ref) {
+  return (
+    <AlertDialogPrimitive.Description
+      ref={ref}
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+});
+export const AlertDialogAction = forwardRef<
+  ElementRef<typeof AlertDialogPrimitive.Action>,
+  ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Action>
+>(function AlertDialogAction({ className, ...props }, ref) {
+  return (
+    <AlertDialogPrimitive.Action ref={ref} className={cn(buttonVariants(), className)} {...props} />
+  );
+});
+export const AlertDialogCancel = forwardRef<
+  ElementRef<typeof AlertDialogPrimitive.Cancel>,
+  ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Cancel>
+>(function AlertDialogCancel({ className, ...props }, ref) {
+  return (
+    <AlertDialogPrimitive.Cancel
+      ref={ref}
+      className={cn(buttonVariants({ variant: "outline" }), className)}
+      {...props}
+    />
+  );
+});

package/src/components/alert-dialog/index.ts

@@ -0,0 +1,12 @@
+export {
+  AlertDialog,
+  AlertDialogTrigger,
+  AlertDialogPortal,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from "./alert-dialog";

package/src/components/app-shell/app-shell.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AppShell } from "./app-shell";
+import { TopNav } from "../top-nav";
+import { PageShell } from "../page-shell";
+import { SectionHeader } from "../section-header";
+import { Button } from "../button";
+
+const meta = {
+  title: "Layout/App Shell/Basic",
+  component: AppShell,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof AppShell>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const nav = ["Dashboard", "Projects", "Reports", "Settings"];
+
+export const Default: Story = {
+  render: () => (
+    <div className="h-[600px]">
+      <AppShell
+        sidebar={
+          <nav className="flex h-full w-60 flex-col gap-1 border-e border-sidebar-border bg-sidebar p-3 text-sidebar-foreground">
+            <div className="px-2 pb-3 font-semibold">Brand UI</div>
+            {nav.map((n, i) => (
+              <button
+                key={n}
+                className={
+                  "rounded-md px-3 py-2 text-start text-body font-medium " +
+                  (i === 0
+                    ? "bg-sidebar-accent text-sidebar-accent-foreground"
+                    : "text-sidebar-foreground/80 hover:bg-sidebar-accent/60")
+                }
+              >
+                {n}
+              </button>
+            ))}
+          </nav>
+        }
+        topNav={
+          <TopNav end={<Button size="sm">Invite</Button>}>
+            <span className="text-body font-medium">Dashboard</span>
+          </TopNav>
+        }
+      >
+        <PageShell
+          header={
+            <SectionHeader
+              title="Overview"
+              description="A lightweight generic shell. For full sidebar behavior use the Sidebar primitive."
+            />
+          }
+        >
+          <div className="rounded-xl border bg-card p-6 text-body text-muted-foreground">
+            Main content area.
+          </div>
+        </PageShell>
+      </AppShell>
+    </div>
+  ),
+};

package/src/components/app-shell/app-shell.tsx

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export interface AppShellProps {
+  /** Persistent left navigation (often a <Sidebar />). */
+  sidebar?: ReactNode;
+  /** Top bar (often a <TopNav />). */
+  topNav?: ReactNode;
+  children: ReactNode;
+  className?: string;
+  /** Class for the scrolling main content region. */
+  mainClassName?: string;
+}
+
+/**
+ * App-first layout: fixed-height viewport with an optional sidebar, a top bar,
+ * and a scrollable main region. Pure layout — bring your own nav components.
+ */
+export function AppShell({ sidebar, topNav, children, className, mainClassName }: AppShellProps) {
+  return (
+    <div
+      className={cn("flex h-dvh w-full overflow-hidden bg-background text-foreground", className)}
+    >
+      {sidebar ? <div className="hidden md:flex">{sidebar}</div> : null}
+      <div className="flex min-w-0 flex-1 flex-col">
+        {topNav}
+        <main className={cn("min-h-0 flex-1 overflow-y-auto", mainClassName)}>{children}</main>
+      </div>
+    </div>
+  );
+}

package/src/components/app-shell/index.ts

@@ -0,0 +1 @@
+export { AppShell, type AppShellProps } from "./app-shell";