@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/spec-playground/spec-playground.stories.tsx

@@ -0,0 +1,156 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, waitFor, within } from "storybook/test";
+import { Card, CardContent, CardHeader, CardTitle } from "../card";
+import {
+  SpecPlayground,
+  type SpecPlaygroundError,
+  type SpecPlaygroundExample,
+  type SpecPlaygroundValidation,
+} from "./spec-playground";
+
+/** A tiny spec for the stories: a titled list. The validator is a fake, not a real catalog. */
+interface ListSpec {
+  title: string;
+  items: string[];
+}
+
+function validateListSpec(json: unknown): SpecPlaygroundValidation<ListSpec> {
+  const errors: SpecPlaygroundError[] = [];
+  if (typeof json !== "object" || json === null || Array.isArray(json)) {
+    return { ok: false, errors: [{ path: "$", code: "type", message: "must be an object" }] };
+  }
+  const record = json as Record<string, unknown>;
+  if (typeof record.title !== "string") {
+    errors.push({ path: "$.title", code: "missing", message: "title is required" });
+  }
+  if (!Array.isArray(record.items)) {
+    errors.push({ path: "$.items", code: "type", message: "items must be an array" });
+  } else {
+    record.items.forEach((item, index) => {
+      if (typeof item !== "string") {
+        errors.push({ path: `$.items[${index}]`, code: "type", message: "must be a string" });
+      }
+    });
+  }
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, spec: json as ListSpec };
+}
+
+function renderListSpec(spec: ListSpec) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{spec.title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <ul className="list-disc ps-5 text-body">
+          {spec.items.map((item) => (
+            <li key={item}>{item}</li>
+          ))}
+        </ul>
+      </CardContent>
+    </Card>
+  );
+}
+
+const pretty = (value: unknown) => JSON.stringify(value, null, 2);
+
+const EXAMPLES: SpecPlaygroundExample[] = [
+  {
+    id: "launch",
+    label: "Launch checklist",
+    value: pretty({ title: "Launch checklist", items: ["Freeze scope", "Run the gates", "Ship"] }),
+  },
+  {
+    id: "groceries",
+    label: "Groceries",
+    value: pretty({ title: "Groceries", items: ["Oats", "Lemons"] }),
+  },
+];
+
+const meta = {
+  title: "Display/SpecPlayground",
+  component: SpecPlayground,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "A live spec editor: JSON on the left, what it renders on the right (stacked below 1024 px). The host supplies the validator, the renderer and optionally a code editor; errors list under the editor as `path · code · message`, and the render keeps the last valid spec until the text validates again. These stories use the default textarea editor and a fake validator.",
+      },
+    },
+  },
+  args: {
+    examples: EXAMPLES,
+    validate: validateListSpec,
+    render: renderListSpec,
+    debounceMs: 250,
+  },
+} satisfies Meta<typeof SpecPlayground<ListSpec>>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A valid example, rendered. */
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("status")).toHaveTextContent("Valid");
+    await expect(
+      canvas.getByText("Launch checklist", { selector: "[data-slot=card-title]" }),
+    ).toBeVisible();
+  },
+};
+
+/** Break the spec, see the validator’s error and the last valid render; fix it again. */
+export const EditErrorFix: Story = {
+  args: { onChange: fn() },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const editor = canvas.getByRole("textbox", { name: "Spec (JSON)" });
+    await userEvent.clear(editor);
+    await userEvent.type(editor, '{{ "items": [["one"] }');
+    await waitFor(() => expect(canvas.getByRole("status")).toHaveTextContent("1 error"));
+    const error = canvas.getByRole("button", { name: /\$\.title/ });
+    await expect(error).toHaveAttribute("data-code", "missing");
+    await expect(canvas.getByText("Showing last valid")).toBeVisible();
+    await userEvent.click(error);
+    await expect(editor).toHaveFocus();
+    await userEvent.click(canvas.getByRole("button", { name: "Reset" }));
+    await waitFor(() => expect(canvas.getByRole("status")).toHaveTextContent("Valid"));
+    await expect(canvas.queryByText("Showing last valid")).toBeNull();
+  },
+};
+
+/** Text that is not JSON: a parse-error chip and no render yet. */
+export const ParseError: Story = {
+  args: { defaultValue: '{ "title": "Half', examples: [] },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("status")).toHaveTextContent("Parse error");
+    await expect(canvas.getByText("Nothing valid to render yet.")).toBeVisible();
+  },
+};
+
+/** Valid JSON the validator rejects, with nothing valid seen yet. */
+export const Invalid: Story = {
+  args: { defaultValue: pretty({ title: 3, items: ["ok", 4] }) },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("status")).toHaveTextContent("2 errors");
+    await expect(canvas.getAllByRole("listitem")).toHaveLength(2);
+  },
+};
+
+/** The examples menu replaces the editor text. */
+export const LoadExample: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: "Load example" }));
+    const body = within(canvasElement.ownerDocument.body);
+    await userEvent.click(await body.findByRole("menuitem", { name: "Groceries" }));
+    await waitFor(() =>
+      expect(canvas.getByText("Groceries", { selector: "[data-slot=card-title]" })).toBeVisible(),
+    );
+  },
+};

package/src/components/spec-playground/spec-playground.test.tsx

@@ -0,0 +1,106 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { locateJsonPath, parseJsonPath } from "./locate-json-path";
+import { SpecPlayground, type SpecPlaygroundValidation } from "./spec-playground";
+
+interface Spec {
+  title: string;
+}
+
+const validate = (json: unknown): SpecPlaygroundValidation<Spec> =>
+  typeof (json as Spec | null)?.title === "string"
+    ? { ok: true, spec: json as Spec }
+    : { ok: false, errors: [{ path: "$.title", code: "missing", message: "title is required" }] };
+
+const renderSpec = (spec: Spec) => <p data-testid="rendered">{spec.title}</p>;
+
+afterEach(() => vi.useRealTimers());
+
+describe("SpecPlayground", () => {
+  it("renders a valid spec with a valid status", () => {
+    render(
+      <SpecPlayground defaultValue='{"title":"Hello"}' validate={validate} render={renderSpec} />,
+    );
+    expect(screen.getByTestId("rendered")).toHaveTextContent("Hello");
+    expect(screen.getByRole("status")).toHaveTextContent("Valid");
+  });
+
+  it("validates after the debounce, lists the error and keeps the last valid render", () => {
+    vi.useFakeTimers();
+    render(
+      <SpecPlayground
+        defaultValue='{"title":"Hello"}'
+        validate={validate}
+        render={renderSpec}
+        debounceMs={250}
+      />,
+    );
+    const editor = screen.getByRole("textbox", { name: "Spec (JSON)" });
+    fireEvent.change(editor, { target: { value: '{\n  "name": "x"\n}' } });
+    // Not yet: validation trails the edit.
+    expect(screen.getByRole("status")).toHaveTextContent("Valid");
+    act(() => void vi.advanceTimersByTime(250));
+    expect(screen.getByRole("status")).toHaveTextContent("1 error");
+    const error = screen.getByRole("button", { name: /\$\.title/ });
+    expect(error).toHaveAttribute("data-code", "missing");
+    expect(screen.getByText("Showing last valid")).toBeInTheDocument();
+    expect(screen.getByTestId("rendered")).toHaveTextContent("Hello");
+    expect(editor).toHaveAttribute("aria-invalid", "true");
+
+    fireEvent.change(editor, { target: { value: '{"title":"Fixed"}' } });
+    act(() => void vi.advanceTimersByTime(250));
+    expect(screen.getByRole("status")).toHaveTextContent("Valid");
+    expect(screen.queryByText("Showing last valid")).toBeNull();
+    expect(screen.getByTestId("rendered")).toHaveTextContent("Fixed");
+  });
+
+  it("reports a parse error and moves the caret to an error's line", () => {
+    const onErrorSelect = vi.fn();
+    render(
+      <SpecPlayground
+        defaultValue={'{\n  "other": 1\n}'}
+        validate={validate}
+        render={renderSpec}
+        onErrorSelect={onErrorSelect}
+      />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: /\$\.title/ }));
+    expect(onErrorSelect).toHaveBeenCalledWith(expect.objectContaining({ code: "missing" }), 1);
+  });
+
+  it("shows a parse-error status for text that is not JSON", () => {
+    render(<SpecPlayground defaultValue="{ nope" validate={validate} render={renderSpec} />);
+    expect(screen.getByRole("status")).toHaveTextContent("Parse error");
+    expect(screen.getByText("Nothing valid to render yet.")).toBeInTheDocument();
+  });
+
+  it("uses the editor slot instead of the textarea when given", () => {
+    render(
+      <SpecPlayground
+        defaultValue='{"title":"Hello"}'
+        validate={validate}
+        render={renderSpec}
+        editor={<div data-testid="custom-editor" />}
+      />,
+    );
+    expect(screen.getByTestId("custom-editor")).toBeInTheDocument();
+    expect(screen.queryByRole("textbox")).toBeNull();
+  });
+});
+
+describe("locateJsonPath", () => {
+  const text =
+    '{\n  "root": {\n    "children": [\n      "a",\n      { "props": {} }\n    ]\n  }\n}';
+
+  it("parses both path styles", () => {
+    expect(parseJsonPath("$.tiles[3].layout.w")).toEqual(["tiles", 3, "layout", "w"]);
+    expect(parseJsonPath("root.children[2].props")).toEqual(["root", "children", 2, "props"]);
+  });
+
+  it("finds the deepest existing prefix", () => {
+    expect(locateJsonPath(text, "root.children[1].props.label")).toBe(5);
+    expect(locateJsonPath(text, "root.children")).toBe(3);
+    expect(locateJsonPath(text, "$.missing")).toBe(1);
+    expect(locateJsonPath("{ nope", "$.a")).toBeUndefined();
+  });
+});

package/src/components/spec-playground/spec-playground.tsx

@@ -0,0 +1,351 @@
+"use client";
+
+import {
+  forwardRef,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ForwardedRef,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { Braces, ChevronDown, CircleAlert, CircleCheck, RotateCcw } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { useControllableState } from "../../lib/use-controllable-state";
+import { Badge } from "../badge";
+import { Button } from "../button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "../dropdown-menu";
+import { Textarea } from "../textarea";
+import { lineOfParseError, locateJsonPath, offsetOfLine } from "./locate-json-path";
+
+/** One problem a validator reports — the shape both the A2UI and DashboardSpec validators use. */
+export interface SpecPlaygroundError {
+  /** JSON-path-like address of the problem (`root.children[2].props.label`, `$.tiles[0]`). */
+  path: string;
+  /** The validator's machine-readable code (`missing-prop`, `overlap`, …). */
+  code: string;
+  message: string;
+}
+
+/** What `validate` returns: the typed spec, or the validator's own errors. */
+export type SpecPlaygroundValidation<TSpec> =
+  | { ok: true; spec: TSpec }
+  | { ok: false; errors: readonly SpecPlaygroundError[] };
+
+/** An entry in the `Load example` menu. */
+export interface SpecPlaygroundExample {
+  id: string;
+  label: string;
+  /** The JSON text loaded into the editor. */
+  value: string;
+}
+
+/** The playground's status: what the last validated text turned out to be. */
+export type SpecPlaygroundStatus = "valid" | "invalid" | "parse-error";
+
+/** Every string the playground renders — pass your own to localize it. */
+export interface SpecPlaygroundLabels {
+  /** Accessible name of the default textarea editor. */
+  editor: string;
+  /** Accessible name of the rendered-result region. */
+  preview: string;
+  /** Accessible name of the error list. */
+  errors: string;
+  /** Trigger of the examples menu. */
+  loadExample: string;
+  /** Resets the editor to its initial text. */
+  reset: string;
+  /** Status chip: the text validates. */
+  valid: string;
+  /** Status chip: the validator reported `count` errors. */
+  errorCount: (count: number) => string;
+  /** Status chip: the text is not JSON. */
+  parseError: string;
+  /** Shown over the render when it is the last valid spec, not the current text. */
+  showingLastValid: string;
+  /** Shown in the render pane before any text has validated. */
+  nothingValid: string;
+  /** Suffix naming the editor line an error points at. */
+  line: (line: number) => string;
+}
+
+export const DEFAULT_SPEC_PLAYGROUND_LABELS: SpecPlaygroundLabels = {
+  editor: "Spec (JSON)",
+  preview: "Rendered result",
+  errors: "Problems",
+  loadExample: "Load example",
+  reset: "Reset",
+  valid: "Valid",
+  errorCount: (count) => (count === 1 ? "1 error" : `${count} errors`),
+  parseError: "Parse error",
+  showingLastValid: "Showing last valid",
+  nothingValid: "Nothing valid to render yet.",
+  line: (line) => `line ${line}`,
+};
+
+export interface SpecPlaygroundProps<TSpec> extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> {
+  /** The JSON text (controlled). */
+  value?: string;
+  /** Initial JSON text (uncontrolled); also what `Reset` restores. Default: the first example. */
+  defaultValue?: string;
+  /** Called with the new text on every edit, example load and reset. */
+  onChange?: (value: string) => void;
+  /** Checks the parsed JSON; the errors shown are exactly the ones it returns. */
+  validate: (json: unknown) => SpecPlaygroundValidation<TSpec>;
+  /** Renders a validated spec. */
+  render: (spec: TSpec) => ReactNode;
+  /** Entries of the `Load example` menu (the menu is hidden without any). */
+  examples?: readonly SpecPlaygroundExample[];
+  /**
+   * The editor. Bind it to `value`/`onChange` yourself. Default: a `Textarea`, so the
+   * playground works without a code editor.
+   */
+  editor?: ReactNode;
+  /**
+   * Called when an error is chosen, with the editor line its path resolves to — move a custom
+   * editor's caret there. The default textarea handles this itself.
+   */
+  onErrorSelect?: (error: SpecPlaygroundError, line: number | undefined) => void;
+  /** Milliseconds between the last edit and validation. Default 250. */
+  debounceMs?: number;
+  labels?: Partial<SpecPlaygroundLabels>;
+}
+
+type Checked<TSpec> =
+  | { status: "valid"; spec: TSpec; errors: readonly SpecPlaygroundError[] }
+  | { status: "invalid" | "parse-error"; errors: readonly SpecPlaygroundError[] };
+
+function check<TSpec>(
+  text: string,
+  validate: (json: unknown) => SpecPlaygroundValidation<TSpec>,
+): Checked<TSpec> {
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { status: "parse-error", errors: [{ path: "", code: "parse-error", message }] };
+  }
+  const result = validate(json);
+  return result.ok
+    ? { status: "valid", spec: result.spec, errors: [] }
+    : { status: "invalid", errors: result.errors };
+}
+
+function SpecPlaygroundInner<TSpec>(
+  {
+    value: valueProp,
+    defaultValue,
+    onChange,
+    validate,
+    render,
+    examples = [],
+    editor,
+    onErrorSelect,
+    debounceMs = 250,
+    labels: labelsProp,
+    className,
+    ...props
+  }: SpecPlaygroundProps<TSpec>,
+  ref: ForwardedRef<HTMLDivElement>,
+) {
+  const labels = { ...DEFAULT_SPEC_PLAYGROUND_LABELS, ...labelsProp };
+  const initial = defaultValue ?? examples[0]?.value ?? "";
+  const [resetValue] = useState(initial);
+  const [value, setValue] = useControllableState(valueProp, initial, onChange);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // Validation trails the text by `debounceMs`; the first render validates immediately.
+  const [settled, setSettled] = useState(value);
+  useEffect(() => {
+    if (settled === value) return;
+    const timer = setTimeout(() => setSettled(value), debounceMs);
+    return () => clearTimeout(timer);
+  }, [value, settled, debounceMs]);
+
+  const checked = useMemo(() => check(settled, validate), [settled, validate]);
+
+  // The last spec that validated — kept on screen while the current text does not.
+  const lastValidRef = useRef<{ spec: TSpec } | null>(null);
+  if (checked.status === "valid") lastValidRef.current = { spec: checked.spec };
+  const shown = checked.status === "valid" ? { spec: checked.spec } : lastValidRef.current;
+  const stale = checked.status !== "valid" && shown !== null;
+
+  const lineOf = (error: SpecPlaygroundError) =>
+    error.code === "parse-error"
+      ? lineOfParseError(settled, error.message)
+      : locateJsonPath(settled, error.path);
+
+  const selectError = (error: SpecPlaygroundError) => {
+    const line = lineOf(error);
+    if (onErrorSelect) return onErrorSelect(error, line);
+    const textarea = textareaRef.current;
+    if (!textarea) return;
+    const offset = line === undefined ? 0 : offsetOfLine(textarea.value, line);
+    textarea.focus();
+    textarea.setSelectionRange(offset, offset);
+  };
+
+  const errorListId = `${props.id ?? "spec-playground"}-errors`;
+  const hasErrors = checked.errors.length > 0;
+
+  return (
+    <div
+      ref={ref}
+      data-slot="spec-playground"
+      data-status={checked.status}
+      className={cn("grid min-w-0 gap-4 lg:grid-cols-2", className)}
+      {...props}
+    >
+      <div data-slot="spec-playground-source" className="flex min-w-0 flex-col gap-3">
+        <div data-slot="spec-playground-toolbar" className="flex flex-wrap items-center gap-2">
+          <span role="status" aria-live="polite" className="me-auto">
+            <Badge
+              data-slot="spec-playground-status"
+              data-status={checked.status}
+              variant={
+                checked.status === "valid"
+                  ? "success"
+                  : checked.status === "invalid"
+                    ? "destructive"
+                    : "warning"
+              }
+              className="gap-1"
+            >
+              {checked.status === "valid" ? (
+                <CircleCheck aria-hidden="true" size={14} />
+              ) : checked.status === "invalid" ? (
+                <CircleAlert aria-hidden="true" size={14} />
+              ) : (
+                <Braces aria-hidden="true" size={14} />
+              )}
+              {checked.status === "valid"
+                ? labels.valid
+                : checked.status === "invalid"
+                  ? labels.errorCount(checked.errors.length)
+                  : labels.parseError}
+            </Badge>
+          </span>
+          {examples.length > 0 ? (
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button variant="outline" size="sm" data-slot="spec-playground-examples">
+                  {labels.loadExample}
+                  <ChevronDown aria-hidden="true" size={14} />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                {examples.map((example) => (
+                  <DropdownMenuItem
+                    key={example.id}
+                    data-example-id={example.id}
+                    onSelect={() => setValue(example.value)}
+                  >
+                    {example.label}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          ) : null}
+          <Button
+            variant="ghost"
+            size="sm"
+            data-slot="spec-playground-reset"
+            onClick={() => setValue(resetValue)}
+          >
+            <RotateCcw aria-hidden="true" size={14} />
+            {labels.reset}
+          </Button>
+        </div>
+        <div data-slot="spec-playground-editor" className="min-h-80 min-w-0">
+          {editor ?? (
+            <Textarea
+              ref={textareaRef}
+              data-slot="spec-playground-textarea"
+              aria-label={labels.editor}
+              aria-invalid={hasErrors || undefined}
+              aria-describedby={hasErrors ? errorListId : undefined}
+              spellCheck={false}
+              value={value}
+              onChange={(event) => setValue(event.target.value)}
+              className="h-80 min-h-80 resize-y font-mono text-code"
+            />
+          )}
+        </div>
+        {hasErrors ? (
+          <ol
+            id={errorListId}
+            aria-label={labels.errors}
+            data-slot="spec-playground-errors"
+            className="flex flex-col gap-1"
+          >
+            {checked.errors.map((error) => {
+              const line = lineOf(error);
+              return (
+                <li key={`${error.path}|${error.code}|${error.message}`}>
+                  <button
+                    type="button"
+                    data-slot="spec-playground-error"
+                    data-path={error.path}
+                    data-code={error.code}
+                    onClick={() => selectError(error)}
+                    className="focus-ring flex w-full min-w-0 flex-wrap items-baseline gap-x-2 rounded-md border-s-2 border-s-destructive px-2 py-1 text-start text-caption hover:bg-muted"
+                  >
+                    {error.path ? <code className="font-mono text-code">{error.path}</code> : null}
+                    <span className="font-mono text-code text-destructive-text">{error.code}</span>
+                    <span className="min-w-0 break-words text-muted-foreground">
+                      {error.message}
+                    </span>
+                    {line !== undefined ? (
+                      <span className="text-meta text-muted-foreground">{labels.line(line)}</span>
+                    ) : null}
+                  </button>
+                </li>
+              );
+            })}
+          </ol>
+        ) : null}
+      </div>
+      <section
+        aria-label={labels.preview}
+        data-slot="spec-playground-preview"
+        data-stale={stale ? "" : undefined}
+        className="flex min-w-0 flex-col gap-2"
+      >
+        {stale ? (
+          <Badge variant="outline" data-slot="spec-playground-stale" className="self-start">
+            {labels.showingLastValid}
+          </Badge>
+        ) : null}
+        {shown ? (
+          render(shown.spec)
+        ) : (
+          <p className="text-caption text-muted-foreground">{labels.nothingValid}</p>
+        )}
+      </section>
+    </div>
+  );
+}
+
+/**
+ * A live spec editor: JSON on the left, what it renders on the right (stacked below 1024 px).
+ * Edits are validated after a short pause by the host's own `validate`; its errors are listed
+ * under the editor (`path · code · message`, click to jump to the line) and the render keeps
+ * the last valid spec, marked as such, until the text validates again. The editor, validator
+ * and renderer all come from the host — this component owns only the loop between them.
+ */
+export const SpecPlayground = forwardRef(SpecPlaygroundInner) as <TSpec>(
+  props: SpecPlaygroundProps<TSpec> & { ref?: Ref<HTMLDivElement> },
+) => ReactElement;
+(SpecPlayground as { displayName?: string }).displayName = "SpecPlayground";

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/state-panel/state-panel.stories.tsx

@@ -84,8 +84,9 @@ export const EmptyNoIcon: Story = {
   },
 };
 
+/** #24 — the empty state gained a spot illustration slot beside title/description. */
 export const WithIllustration: Story = {
-  name: "Empty (with illustration, #24)",
+  name: "Empty (with illustration)",
   args: {
     kind: "empty",
     title: "No projects yet",
@@ -112,8 +113,9 @@ export const NoAccess: Story = {
   },
 };
 
+/** #24 P0-2 — the error state carries the same illustration slot as empty. */
 export const ErrorWithIllustration: Story = {
-  name: "Error (with illustration, #24 P0-2)",
+  name: "Error (with illustration)",
   args: {
     // The one panel `kind` that re-tints the illustration slot (`text-destructive`)
     // — pairing it with an illustration is what surfaces whether the accent