@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/copyable-value/copyable-value.tsx

@@ -72,7 +72,7 @@ export const CopyableValue = forwardRef<HTMLButtonElement, CopyableValueProps>(
             // only resting affordance, so a value inside a heading or a KPI
             // still looks like a value, not a link.
             "inline-flex items-baseline gap-1 rounded-sm underline decoration-dotted decoration-muted-foreground underline-offset-4",
-            "hover:decoration-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            "hover:decoration-foreground focus-ring",
             "transition-colors duration-fast ease-standard motion-reduce:transition-none",
             className,
           )}

package/src/components/dialog/dialog.tsx

@@ -149,7 +149,7 @@ export const DialogContent = forwardRef<
         {children}
         <DialogPrimitive.Close
           data-slot="dialog-close"
-          className="absolute end-4 top-4 rounded-md p-1 text-muted-foreground opacity-70 transition-opacity hover:opacity-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          className="absolute end-4 top-4 rounded-md p-1 text-muted-foreground opacity-70 transition-opacity hover:opacity-100 focus-ring"
           aria-label="Close"
         >
           <svg
@@ -275,7 +275,7 @@ export const DialogBody = forwardRef<HTMLDivElement, DialogBodyProps>(function D
       // focusable content.
       tabIndex={tabIndex ?? 0}
       className={cn(
-        "-m-1 min-h-0 overflow-y-auto overscroll-contain p-1 scroll-p-1 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "-m-1 min-h-0 overflow-y-auto overscroll-contain p-1 scroll-p-1 focus-ring",
         className,
       )}
       {...props}

package/src/components/dropdown-menu/dropdown-menu.stories.tsx

@@ -147,7 +147,7 @@ export const SubmenuRadioAndCheckbox: Story = {
 };
 
 /**
- * Three-theme sweep (a durable, `test-storybook`-run artifact rather than a
+ * Cross-theme sweep (a durable, `test-storybook`-run artifact rather than a
  * one-off manual `preview.tsx` toggle). `<ThemeProvider>` (not a plain
  * `data-theme` wrapper `<div>`) because it writes the attribute onto the
  * DOCUMENT ROOT — this menu's Radix `Portal` mounts its content on

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

@@ -1,11 +1,37 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { EmptyState } from "./empty-state";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const source = readFileSync(join(__dirname, "empty-state.tsx"), "utf8");
+
 describe("EmptyState", () => {
   it("renders title and description", () => {
     render(<EmptyState title="Empty" description="Nothing here" />);
     expect(screen.getByText("Empty")).toBeInTheDocument();
     expect(screen.getByText("Nothing here")).toBeInTheDocument();
   });
+
+  it("clamps a passed icon to the fixed 40×40 slot, matching its documented behavior (#47)", () => {
+    // EmptyState only ever forwards `icon` to StatePanel, whose fixed-size
+    // icon slot clamps it via `[&_svg]:size-10` — it never forwards
+    // `illustration`, whose slot is unclamped. Lock the REAL behavior so it
+    // can't silently drift further from whatever the JSDoc claims.
+    render(<EmptyState title="X" icon={<svg data-testid="passed-icon" />} />);
+    const svg = screen.getByTestId("passed-icon");
+    expect(svg.parentElement?.className ?? "").toContain("size-10");
+  });
+
+  it("JSDoc claims only what `icon` actually does — does not promise an unclamped illustration slot (#47)", () => {
+    // #47 finding C: the JSDoc said "icon/illustration" but the component
+    // only ever forwards `icon` (still clamped to 40x40). A reader passing a
+    // larger illustration through `icon` expecting it to render at full size
+    // would be surprised by the clamp. The doc must describe the clamp, not
+    // the capability the deprecated wrapper doesn't have.
+    expect(source).not.toMatch(/icon\/illustration/i);
+    expect(source).toMatch(/clamp/i);
+  });
 });

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

@@ -8,7 +8,12 @@ import { StatePanel } from "../state-panel/state-panel";
 export interface EmptyStateProps {
   title: ReactNode;
   description?: ReactNode;
-  /** Optional icon/illustration shown above the title. */
+  /**
+   * Optional icon shown above the title, clamped to a fixed 40×40 (this
+   * wrapper only ever forwards `icon` to `StatePanel`, never `illustration`
+   * — for a larger, unclamped illustration use
+   * `StatePanel kind="empty" illustration={...}` directly).
+   */
   icon?: ReactNode;
   /** Primary/secondary actions. */
   actions?: ReactNode;

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

@@ -111,8 +111,7 @@ export const expandDialogPanesVariants = cva("grid min-h-0 gap-3 overflow-hidden
  * and a pane holding only text has no focusable child to scroll from. Pass
  * `tabIndex={-1}` when the pane always contains its own focusable content.
  */
-const paneClass =
-  "min-h-0 min-w-0 overflow-auto overscroll-contain focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+const paneClass = "min-h-0 min-w-0 overflow-auto overscroll-contain focus-ring";
 
 export interface ExpandDialogPanesProps
   extends

package/src/components/field/field-context.ts

@@ -0,0 +1,59 @@
+import { createContext, use } from "react";
+
+/**
+ * Shared, lifted state for the `Field*` compound anatomy (`FieldRoot` +
+ * `FieldLabel`/`FieldControl`/`FieldDescription`/`FieldError`). `FieldRoot`
+ * is the only place this state is produced; every part reads the INTERFACE
+ * below rather than receiving positional props, so parts can be composed in
+ * any order/layout (compound-component + lifted-state convention — see
+ * `.claude/rules/component-api.md` "Composition patterns").
+ */
+export interface FieldContextValue {
+  /**
+   * The id `FieldLabel`'s `htmlFor` points to — the FIRST `FieldControl`
+   * mounted under this `FieldRoot`, by JSX order (self-registered; see
+   * `registerControl`). `undefined` until a control has registered.
+   */
+  labelFor: string | undefined;
+  /** Registers a `FieldControl`'s resolved id (called while it is mounted). */
+  registerControl: (id: string) => void;
+  /** Unregisters a `FieldControl`'s id (called on unmount / when its id changes). */
+  unregisterControl: (id: string) => void;
+  /** `FieldRoot`'s `invalid` prop — drives `aria-invalid` on every `FieldControl` and error styling on `FieldLabel`. */
+  invalid: boolean;
+  /** `FieldRoot`'s `required` prop — drives `aria-required` on every `FieldControl`. */
+  required: boolean;
+  /**
+   * The composed `aria-describedby` value from every mounted `FieldDescription`/
+   * `FieldError` instance WITH content, descriptions first (in mount order),
+   * then errors (in mount order) — a fixed semantic order regardless of DOM
+   * position, so more than one of either part (or reordering them relative to
+   * `FieldControl`) never scrambles the announced order. `undefined` when
+   * nothing is registered.
+   */
+  describedBy: string | undefined;
+  /**
+   * Registers one `FieldDescription` INSTANCE's own id (called while it has
+   * content). Each instance generates and registers its own id — this is not
+   * a single shared slot, so more than one `FieldDescription` under one
+   * `FieldRoot` is supported without id collisions.
+   */
+  registerDescription: (id: string) => void;
+  /** Unregisters one `FieldDescription` instance's id (on unmount / when content is cleared). Removes only that instance's id. */
+  unregisterDescription: (id: string) => void;
+  /** Registers one `FieldError` instance's own id (called while it has content). Same per-instance contract as `registerDescription`. */
+  registerError: (id: string) => void;
+  /** Unregisters one `FieldError` instance's id (on unmount / when content is cleared). Removes only that instance's id. */
+  unregisterError: (id: string) => void;
+}
+
+export const FieldContext = createContext<FieldContextValue | null>(null);
+
+/** Reads the shared `Field*` context; throws with the calling component's name when used outside a `FieldRoot`. */
+export function useFieldContext(component: string): FieldContextValue {
+  const ctx = use(FieldContext);
+  if (!ctx) {
+    throw new Error(`<${component}> must be rendered inside a <FieldRoot>.`);
+  }
+  return ctx;
+}

package/src/components/field/field.stories.tsx

@@ -0,0 +1,142 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { Input } from "../input";
+import { FieldRoot, FieldLabel, FieldControl, FieldDescription, FieldError } from "./field";
+
+const meta = {
+  title: "Forms/Field",
+  component: FieldRoot,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A compound field anatomy — `FieldRoot` + `FieldLabel`/`FieldControl`/`FieldDescription`/`FieldError` — for callers who need to COMPOSE a field layout `FieldRow` (Forms/FieldRow) can't express: more than one control in one row, or a description placed before the control. Every part reads shared context (`FieldRoot` owns id generation and `aria-describedby` composition), so they can be arranged in any order/layout. `FieldRow` remains the convenience wrapper for the common single-control case and is unaffected (#43).",
+      },
+    },
+  },
+} satisfies Meta<typeof FieldRoot>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="w-72">
+      <FieldRoot>
+        <FieldLabel>Name</FieldLabel>
+        <FieldControl>
+          <Input placeholder="Jane Doe" />
+        </FieldControl>
+      </FieldRoot>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const input = canvas.getByRole("textbox");
+    expect(input).not.toHaveAttribute("aria-describedby");
+    expect(input).toHaveAttribute("aria-invalid", "false");
+    expect(canvas.getByText("Name")).toHaveAttribute("for", input.id);
+  },
+};
+
+export const WithDescriptionAndError: Story = {
+  name: "With description and error",
+  render: () => (
+    <div className="w-72">
+      <FieldRoot invalid required>
+        <FieldLabel>API key</FieldLabel>
+        <FieldControl>
+          <Input placeholder="sk-…" />
+        </FieldControl>
+        <FieldDescription>Found in your account settings.</FieldDescription>
+        <FieldError>Enter a valid API key.</FieldError>
+      </FieldRoot>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const input = canvas.getByRole("textbox");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+    expect(input).toHaveAttribute("aria-required", "true");
+    const describedBy = input.getAttribute("aria-describedby")?.split(" ") ?? [];
+    expect(describedBy).toHaveLength(2);
+    expect(canvas.getByText("Found in your account settings.").id).toBe(describedBy[0]);
+    const alert = canvas.getByRole("alert");
+    expect(alert).toHaveTextContent("Enter a valid API key.");
+    expect(alert.id).toBe(describedBy[1]);
+  },
+};
+
+/**
+ * #43's first motivating case: `FieldRow`'s `children: ReactElement` can only
+ * ever wrap ONE control, so a first/last-name row (or a control plus an
+ * inline unit suffix) can't be expressed. Here two `FieldControl`s share one
+ * `FieldRoot` — each gets its own independent `id` (given explicitly, the
+ * same way any two form controls would need distinct ids) while both read
+ * the SAME `invalid`/`aria-describedby` wiring from context. `FieldLabel`'s
+ * `htmlFor` can only point to ONE control (the first), so each `Input` also
+ * carries its own `aria-label` — a shared visual label plus a placeholder is
+ * not enough of an accessible name for the second control (axe:
+ * `label-title-only`).
+ */
+export const TwoControlsInOneRow: Story = {
+  name: "Two controls in one row",
+  render: () => (
+    <div className="w-96">
+      <FieldRoot invalid>
+        <FieldLabel>Name</FieldLabel>
+        <div className="flex gap-2">
+          <FieldControl>
+            <Input id="first-name" aria-label="First name" placeholder="First name" />
+          </FieldControl>
+          <FieldControl>
+            <Input id="last-name" aria-label="Last name" placeholder="Last name" />
+          </FieldControl>
+        </div>
+        <FieldError>Both first and last name are required.</FieldError>
+      </FieldRoot>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const first = canvas.getByPlaceholderText("First name");
+    const last = canvas.getByPlaceholderText("Last name");
+    expect(first.id).toBe("first-name");
+    expect(last.id).toBe("last-name");
+    expect(first.id).not.toBe(last.id);
+
+    const alert = canvas.getByRole("alert");
+    expect(first).toHaveAttribute("aria-invalid", "true");
+    expect(last).toHaveAttribute("aria-invalid", "true");
+    expect(first.getAttribute("aria-describedby")).toBe(alert.id);
+    expect(last.getAttribute("aria-describedby")).toBe(alert.id);
+  },
+};
+
+/**
+ * #43's second motivating case: `FieldRow` always renders description AFTER
+ * the control. Here `FieldDescription` is placed BEFORE `FieldControl` in
+ * JSX — the visible order follows the JSX order, but `aria-describedby`
+ * wiring is unaffected either way (`FieldRoot` composes it from context, not
+ * DOM position).
+ */
+export const DescriptionBeforeControl: Story = {
+  name: "Description between label and control",
+  render: () => (
+    <div className="w-72">
+      <FieldRoot>
+        <FieldLabel>Bio</FieldLabel>
+        <FieldDescription>Shown on your public profile.</FieldDescription>
+        <FieldControl>
+          <Input placeholder="Tell us about yourself…" />
+        </FieldControl>
+      </FieldRoot>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const input = canvas.getByRole("textbox");
+    const description = canvas.getByText("Shown on your public profile.");
+    expect(input.getAttribute("aria-describedby")).toBe(description.id);
+    // The description renders before the control in the DOM, matching JSX order.
+    expect(
+      description.compareDocumentPosition(input) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  },
+};