@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/skip-link/skip-link.tsx

@@ -0,0 +1,34 @@
+import { forwardRef, type ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+
+export interface SkipLinkProps extends ComponentProps<"a"> {
+  /** The id of the landmark to jump to. Defaults to "main-content". */
+  targetId?: string;
+}
+
+/**
+ * The first focusable element of an application: invisible until focused, then a
+ * token-styled pill pinned to the top-start corner. Give the target element
+ * `id={targetId}` and `tabIndex={-1}` so focus actually lands there.
+ */
+export const SkipLink = forwardRef<HTMLAnchorElement, SkipLinkProps>(function SkipLink(
+  { targetId = "main-content", className, children, ...props },
+  ref,
+) {
+  return (
+    <a
+      ref={ref}
+      data-slot="skip-link"
+      href={`#${targetId}`}
+      className={cn(
+        "sr-only focus-visible:not-sr-only focus-visible:absolute focus-visible:start-4 focus-visible:top-4 focus-visible:z-50",
+        "focus-visible:rounded-md focus-visible:bg-card focus-visible:px-3 focus-visible:py-2 focus-visible:text-body focus-visible:text-foreground focus-visible:shadow-ring-md",
+        "focus-ring",
+        className,
+      )}
+      {...props}
+    >
+      {children ?? "Skip to main content"}
+    </a>
+  );
+});

package/src/components/slider/slider.tsx

@@ -124,7 +124,7 @@ export const Slider = forwardRef<ElementRef<typeof SliderPrimitive.Root>, Slider
               aria-valuetext={ariaValueText}
               {...safeThumbProps}
               className={cn(
-                "block size-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+                "block size-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-ring disabled:pointer-events-none disabled:opacity-50",
                 safeThumbProps?.className,
               )}
             />

package/src/components/slider-number/slider-number.stories.tsx

@@ -109,7 +109,10 @@ export const DragThenReset: Story = {
     thumb.focus();
     await userEvent.keyboard("{ArrowRight}{ArrowRight}{ArrowRight}");
     const numberInput = canvas.getByRole("spinbutton", { name: "Temperature" });
-    await expect(numberInput).toHaveValue(0.3);
+    // Text spinbutton (locale-formatted): string display + numeric aria-valuenow.
+    await expect(numberInput).toHaveValue("0.3");
+    await expect(numberInput).toHaveAttribute("aria-valuenow", "0.3");
+    await expect(thumb).toHaveAttribute("aria-valuenow", "0.3");
 
     const resetBtn = canvas.getByRole("button", { name: "Reset" });
     await expect(resetBtn).not.toBeDisabled();

package/src/components/slider-number/slider-number.test.tsx

@@ -10,7 +10,7 @@ describe("SliderNumber", () => {
       "aria-valuenow",
       "0.5",
     );
-    expect(screen.getByRole("spinbutton", { name: "Temperature" })).toHaveValue(0.5);
+    expect(screen.getByRole("spinbutton", { name: "Temperature" })).toHaveValue("0.5");
   });
 
   it("rounds slider-driven and typed values identically (lockstep)", async () => {

package/src/components/sonner/sonner.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { useEffect, useState } from "react";
 import { Toaster as SonnerToaster, toast } from "sonner";
 import { resolveThemeIsDark } from "@elabs-ai/components-tokens";

package/src/components/spinner/spinner.test.tsx

@@ -0,0 +1,18 @@
+import { createRef } from "react";
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Spinner } from "./spinner";
+
+describe("Spinner", () => {
+  it("renders with its default accessible label", () => {
+    render(<Spinner />);
+    expect(screen.getByRole("status", { name: "Loading" })).toBeInTheDocument();
+  });
+
+  it("forwards its ref to the rendered svg", () => {
+    const ref = createRef<SVGSVGElement>();
+    render(<Spinner ref={ref} />);
+    expect(ref.current).toBeInstanceOf(SVGSVGElement);
+    expect(ref.current).toBe(screen.getByRole("status", { name: "Loading" }));
+  });
+});

package/src/components/spinner/spinner.tsx

@@ -1,19 +1,29 @@
+"use client";
+
+import { forwardRef } from "react";
 import { Loader2 } from "lucide-react";
 import { cn } from "../../lib/cn";
+import { useLocale } from "../locale-provider";
 
 export interface SpinnerProps extends React.SVGProps<SVGSVGElement> {
-  /** Accessible label; defaults to "Loading". */
+  /** Accessible label; defaults to the localized "Loading…" microcopy. */
   label?: string;
 }
 
 /** Indeterminate spinner with an accessible label. */
-export function Spinner({ className, label = "Loading", ...props }: SpinnerProps) {
+export const Spinner = forwardRef<SVGSVGElement, SpinnerProps>(function Spinner(
+  { className, label, ...props },
+  ref,
+) {
+  const { t } = useLocale();
   return (
     <Loader2
+      ref={ref}
+      data-slot="spinner"
       role="status"
-      aria-label={label}
+      aria-label={label ?? t("ui.spinner.label")}
       className={cn("size-4 animate-spin text-muted-foreground", className)}
       {...props}
     />
   );
-}
+});

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

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

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

@@ -4,7 +4,23 @@ import { SplitPanel } from "./split-panel";
 const meta = {
   title: "Layout/SplitPanel",
   component: SplitPanel,
-  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "A fixed two-pane layout with per-pane surface tones — panes the user can drag to " +
+          "resize are `Layout/Resizable`, see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
+          '`SplitPanel` sizes the start pane with a CSS grid track (`startSize`, e.g. `"320px"`, ' +
+          '`"40%"`, `"1fr"`) rather than a percentage, so layout is predictable in tests and SSR ' +
+          "with no client-side measurement. The three-tone `plain`/`muted`/`card` ground-offset " +
+          "system on `startTone`/`endTone` is exported as `splitPaneVariants` — apply it to a " +
+          "`ResizablePanel` for the identical tiering on a draggable layout.",
+      },
+    },
+  },
 } satisfies Meta<typeof SplitPanel>;
 export default meta;
 type Story = StoryObj<typeof meta>;
@@ -28,7 +44,7 @@ export const MasterDetail: Story = {
  * 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.
+ * every theme.
  */
 export const Tiered: Story = {
   render: () => (

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

@@ -19,6 +19,26 @@ describe("SplitPanel", () => {
     expect(endPane.className).toMatch(/border-s/);
   });
 
+  // Issue #163 — WCAG 1.4.11: with both tones "plain" (the shipped default),
+  // the hairline is the ONLY cue between the two panes (no fill/elevation
+  // difference), so it must be the strong, ≥3:1 rung — `border-strong ≥ 3:1
+  // on --card/--background` is proven for every theme in
+  // `@elabs-ai/components-tokens`'s `themes-contrast.test.ts`; this test locks
+  // that `SplitPanel` actually reaches for that token in this configuration,
+  // not just the bare `border-s`/`border-t` class the previous assertion
+  // above already passed on the unfixed code.
+  it("plain/plain divider uses the strong (≥3:1) border rung, not the subtle default", () => {
+    const { getByText } = render(<SplitPanel start={<>List</>} end={<>Detail</>} />);
+    expect(getByText("Detail").className).toMatch(/border-border-strong/);
+  });
+
+  it("muted/card tones keep the subtle divider rung — the fill difference already carries the boundary", () => {
+    const { getByText } = render(
+      <SplitPanel startTone="muted" endTone="card" start={<>List</>} end={<>Detail</>} />,
+    );
+    expect(getByText("Detail").className).not.toMatch(/border-border-strong/);
+  });
+
   it("applies the ground-offset tones: muted well + raised card", () => {
     const { getByText } = render(
       <SplitPanel

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

@@ -5,15 +5,20 @@ 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
+ * a white `bg-card` + `shadow-sm` and is robust across every theme — 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`.
+ *
+ * Exported so the same tone system reaches a `Layout/Resizable` pane — a draggable
+ * `ResizablePanel` composes `splitPaneVariants({ tone })` for the identical ground-offset
+ * tiering `SplitPanel` gives its `startTone`/`endTone`, instead of a hand-rolled second
+ * copy of these three classes. See `Layout/Resizable`'s `Tiered` story.
  */
-const paneToneVariants = cva("min-h-0 min-w-0 overflow-auto", {
+export const splitPaneVariants = cva("min-h-0 min-w-0 overflow-auto", {
   variants: {
     tone: {
       plain: "",
@@ -24,7 +29,7 @@ const paneToneVariants = cva("min-h-0 min-w-0 overflow-auto", {
   defaultVariants: { tone: "plain" },
 });
 
-export type SplitPanelTone = NonNullable<VariantProps<typeof paneToneVariants>["tone"]>;
+export type SplitPanelTone = NonNullable<VariantProps<typeof splitPaneVariants>["tone"]>;
 
 export interface SplitPanelProps {
   start: ReactNode;
@@ -49,8 +54,12 @@ export interface SplitPanelProps {
 
 /**
  * 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.
+ * Static sizing by design (predictable in tests/SSR) — `startSize` is a CSS grid
+ * track (`"320px"`, `"40%"`, `"1fr"`), not a percentage. For panes the user can
+ * drag to resize, reach for `Layout/Resizable`'s `ResizablePanelGroup`/
+ * `ResizablePanel`/`ResizableHandle` instead and apply `splitPaneVariants({ tone })`
+ * to a panel for the same ground-offset tiering. See
+ * [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).
  *
  * 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).
@@ -80,11 +89,22 @@ export function SplitPanel({
       )}
       style={style}
     >
-      <div className={cn(paneToneVariants({ tone: startTone }), startClassName)}>{start}</div>
+      <div className={cn(splitPaneVariants({ tone: startTone }), startClassName)}>{start}</div>
       <div
         className={cn(
-          paneToneVariants({ tone: endTone }),
-          divider && (isHorizontal ? "border-s" : "border-t"),
+          splitPaneVariants({ tone: endTone }),
+          divider &&
+            (isHorizontal ? "border-s" : "border-t") +
+              // #163 — with both panes "plain" there is no fill/elevation
+              // difference between them, so the hairline is the ONLY cue and
+              // must clear the 3:1 non-text bar (WCAG 1.4.11):
+              // `border-border-strong` (`border-strong ≥ 3:1 on --card/
+              // --background` is proven for every theme in
+              // @elabs-ai/components-tokens's themes-contrast.test.ts).
+              // With either tone "muted"/"card" the fill change already
+              // carries the boundary, so the subtle default rung stays —
+              // the redundant-cue exemption in styling-and-tokens.md.
+              (startTone === "plain" && endTone === "plain" ? " border-border-strong" : ""),
           endClassName,
         )}
       >

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

@@ -1,6 +1,11 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Button } from "../button";
 import { StatePanel } from "./state-panel";
+import {
+  EmptyListIllustration,
+  NoAccessIllustration,
+  ErrorIllustration,
+} from "../../illustrations";
 
 const meta = {
   title: "States/StatePanel",
@@ -78,3 +83,50 @@ export const EmptyNoIcon: Story = {
     description: "Items will appear here once available.",
   },
 };
+
+export const WithIllustration: Story = {
+  name: "Empty (with illustration, #24)",
+  args: {
+    kind: "empty",
+    title: "No projects yet",
+    description: "Create your first project to get started.",
+    illustration: <EmptyListIllustration />,
+    actions: <Button size="sm">New project</Button>,
+  },
+};
+
+export const NoAccess: Story = {
+  name: "Empty (no-access illustration)",
+  args: {
+    // "No access" is a blocked/informational state, not a system failure —
+    // kind stays "empty" (no alarm-red "Error" eyebrow) rather than "error".
+    kind: "empty",
+    title: "You don’t have access",
+    description: "Ask a workspace admin to grant you permission.",
+    illustration: <NoAccessIllustration />,
+    actions: (
+      <Button size="sm" variant="outline">
+        Request access
+      </Button>
+    ),
+  },
+};
+
+export const ErrorWithIllustration: Story = {
+  name: "Error (with illustration, #24 P0-2)",
+  args: {
+    // The one panel `kind` that re-tints the illustration slot (`text-destructive`)
+    // — pairing it with an illustration is what surfaces whether the accent
+    // follows the tint or clashes against it. See P0-2 in the fix-round review:
+    // no shipped story previously rendered an illustration inside `kind="error"`.
+    kind: "error",
+    title: "Failed to load data",
+    description: "The server returned an unexpected response.",
+    illustration: <ErrorIllustration />,
+    actions: (
+      <Button size="sm" variant="outline">
+        Try again
+      </Button>
+    ),
+  },
+};

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

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { StatePanel } from "./state-panel";
+import {
+  EmptyListIllustration,
+  ErrorIllustration,
+  ILLUSTRATION_ACCENT_VAR,
+} from "../../illustrations";
 
 describe("StatePanel", () => {
   it("renders empty kind with title and description", () => {
@@ -24,6 +29,48 @@ describe("StatePanel", () => {
     expect(alert).toHaveAttribute("data-kind", "error");
   });
 
+  it("error eyebrow uses the destructive INK rung, not the fill rung (#40)", () => {
+    // The eyebrow is running TEXT on the panel's own `bg-destructive/5` wash, so
+    // it must reach for `text-destructive-text` (>= 4.5:1, the text-rung
+    // contract) — never the bare `text-destructive` fill rung, whose contract
+    // is only the 3:1 mark bar. See styling-and-tokens.md "Which status rung a
+    // graphical MARK reaches for" (#381).
+    render(<StatePanel kind="error" />);
+    const eyebrow = screen.getByText("Error");
+    expect(eyebrow.className).toContain("text-destructive-text");
+    expect(eyebrow.className).not.toMatch(/(?<!-)\btext-destructive\b(?!-)/);
+  });
+
+  it("error icon keeps the destructive FILL rung (a mark, not text)", () => {
+    // Inverse of the eyebrow lock above: an icon IS a mark, so it correctly
+    // stays on the fill rung — the fix must not "tidy" it onto -text too.
+    const { container } = render(<StatePanel kind="error" />);
+    const iconWrapper = container.querySelector("svg")?.parentElement;
+    expect(iconWrapper?.className ?? "").toMatch(/\btext-destructive\b/);
+    expect(iconWrapper?.className ?? "").not.toContain("text-destructive-text");
+  });
+
+  it("error rail carries the width cue (border-s-4) AND a destructive-family colour, not the neutral border-strong grey (#71)", () => {
+    // The rail's WIDTH (4px vs 1px) is the monochrome-survivable structural
+    // cue (per styling-and-tokens.md's border/border-strong decision test);
+    // its HUE should match the rest of the destructive family, not fall back
+    // to the neutral `border-strong` rung — that reads as a CSS-specificity
+    // bug, a 4px grey rail beside three red hairlines, not a deliberate
+    // accent (#71).
+    const { container } = render(<StatePanel kind="error" />);
+    const root = container.firstChild as HTMLElement;
+    expect(root.className).toMatch(/\bborder-s-4\b/);
+    expect(root.className).toMatch(/\bborder-s-destructive\b/);
+    expect(root.className).not.toMatch(/\bborder-s-border-strong\b/);
+  });
+
+  it("empty kind's rail carries neither the error width nor its destructive colour", () => {
+    const { container } = render(<StatePanel kind="empty" />);
+    const root = container.firstChild as HTMLElement;
+    expect(root.className).not.toMatch(/\bborder-s-4\b/);
+    expect(root.className).not.toMatch(/\bborder-s-destructive\b/);
+  });
+
   it("renders error kind with custom title", () => {
     render(<StatePanel kind="error" title="Custom error" description="Custom description" />);
     expect(screen.getByRole("alert")).toBeInTheDocument();
@@ -61,4 +108,82 @@ describe("StatePanel", () => {
     );
     expect(screen.getByTestId("custom-icon")).toBeInTheDocument();
   });
+
+  it("renders an illustration without the size-10 icon clamp, decoratively (#24)", () => {
+    const { container } = render(
+      <StatePanel kind="empty" title="No items" illustration={<EmptyListIllustration />} />,
+    );
+    const svg = container.querySelector("svg");
+    expect(svg).not.toBeNull();
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+    // The illustration's own wrapper must NOT carry the `[&_svg]:size-10`
+    // clamp the default icon slot uses — its rem sizing governs instead.
+    const wrapper = svg?.parentElement;
+    expect(wrapper?.className ?? "").not.toContain("size-10");
+  });
+
+  it("illustration path renders the title at the subtitle role, distinct from the icon path's text-body (#47)", () => {
+    // A 112px+ illustration needs a heavier title to group with — bumping the
+    // title to `text-subtitle` (styling-and-tokens.md's typography-scale
+    // roles) only on the illustration path, so the plain `icon` path (a
+    // fixed 40x40 glyph) stays byte-identical to before.
+    const { container: withIllustration } = render(
+      <StatePanel kind="empty" title="No items" illustration={<EmptyListIllustration />} />,
+    );
+    const titleWithIllustration = withIllustration.querySelector("h3");
+    expect(titleWithIllustration?.className ?? "").toContain("text-subtitle");
+    expect(titleWithIllustration?.className ?? "").not.toMatch(/\btext-body\b/);
+
+    const { container: withIcon } = render(
+      <StatePanel kind="empty" title="No items" icon={<span data-testid="i" />} />,
+    );
+    const titleWithIcon = withIcon.querySelector("h3");
+    expect(titleWithIcon?.className ?? "").toMatch(/\btext-body\b/);
+    expect(titleWithIcon?.className ?? "").not.toContain("text-subtitle");
+  });
+
+  it("error-kind illustration retints the accent to the TEXT rung, distinct from the retinted subject's FILL rung (#48)", () => {
+    // StatePanel wraps the illustration slot in `text-destructive` (the FILL
+    // rung — a mark, per styling-and-tokens.md "which status rung a
+    // graphical MARK reaches for") for kind="error". If the ambient
+    // `--illustration-accent` override it sets ALSO resolved to
+    // `--destructive`, the accent would collapse onto the subject the moment
+    // both read the same token (#48 finding 2). It must resolve to the TEXT
+    // rung instead — matching the convention every other illustration's own
+    // default fallback already uses (`--primary-text`, `--success-text`).
+    const { container } = render(<StatePanel kind="error" illustration={<ErrorIllustration />} />);
+    const svg = container.querySelector("svg");
+    const wrapper = svg?.parentElement as HTMLElement;
+    expect(wrapper.className).toMatch(/\btext-destructive\b/);
+    expect(wrapper.style.getPropertyValue(ILLUSTRATION_ACCENT_VAR)).toBe("var(--destructive-text)");
+    // Sanity: ErrorIllustration's own fallback (used when no ambient override
+    // is set) also reaches for the TEXT rung, not the FILL token the subject
+    // above just read.
+    const accentRect = container.querySelector("rect");
+    expect(accentRect?.getAttribute("style") ?? "").toContain("--destructive-text");
+  });
+
+  it("prefers illustration over icon when both are given", () => {
+    render(
+      <StatePanel
+        kind="empty"
+        title="Both given"
+        icon={<span data-testid="custom-icon">icon</span>}
+        illustration={<EmptyListIllustration />}
+      />,
+    );
+    expect(screen.queryByTestId("custom-icon")).toBeNull();
+  });
+
+  it("titleAs renders the requested heading level (#385)", () => {
+    render(<StatePanel kind="empty" title="No data" titleAs="h2" />);
+    const heading = screen.getByRole("heading", { level: 2, name: "No data" });
+    expect(heading.tagName).toBe("H2");
+  });
+
+  it("default titleAs is still h3 — unchanged output for every existing caller (#385)", () => {
+    render(<StatePanel kind="empty" title="No data" />);
+    const heading = screen.getByRole("heading", { level: 3, name: "No data" });
+    expect(heading.tagName).toBe("H3");
+  });
 });