@tangle-network/ui 11.11.8 → 11.13.0

package/src/primitives/card-anatomy.stories.tsx

@@ -0,0 +1,51 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./card";
+import { Heading } from "./heading";
+
+const meta = {
+  title: "Primitives/Card/Anatomy",
+  component: Card,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Card>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const AlignedParts: Story = {
+  render: () => <div className="max-w-lg space-y-6">
+    <Heading variant="page">Activity details</Heading>
+    <Card data-anatomy="full">
+      <CardHeader data-part="header"><CardTitle as="h2">Latest result</CardTitle><CardDescription>One heading level below the page.</CardDescription></CardHeader>
+      <CardContent data-part="content">The header, body and footer share one horizontal gutter.</CardContent>
+      <CardFooter data-part="footer"><Button type="button" variant="outline">View result</Button></CardFooter>
+    </Card>
+    <Card data-anatomy="standalone"><CardContent data-part="content">Content-only cards retain their top padding.</CardContent></Card>
+  </div>,
+  play: ({ canvasElement }) => {
+    const parts = Array.from(canvasElement.querySelectorAll<HTMLElement>('[data-anatomy="full"] > [data-part]'));
+    const styles = parts.map((part) => getComputedStyle(part));
+    const gutter = styles[0]?.paddingLeft;
+    if (!gutter || parseFloat(gutter) <= 0 || styles.some((style) => style.paddingLeft !== gutter || style.paddingRight !== gutter)) {
+      throw new Error("Card parts do not share a nonzero horizontal gutter");
+    }
+    if (parseFloat(styles[1]!.paddingTop) !== 0 || parseFloat(styles[2]!.paddingTop) !== 0) {
+      throw new Error("Stacked card parts duplicate top padding");
+    }
+    const standalone = canvasElement.querySelector<HTMLElement>('[data-anatomy="standalone"] > [data-part]')!;
+    const style = getComputedStyle(standalone);
+    if (parseFloat(style.paddingTop) <= 0 || style.paddingTop !== style.paddingBottom) {
+      throw new Error("Content-only card lost its top padding");
+    }
+  },
+};
+
+function ActionCard() {
+  const [count, setCount] = useState(0);
+  return <Card hover className="max-w-sm">
+    <CardHeader><CardTitle as="h2">Decorative hover, native action</CardTitle><CardDescription>Tab to the button; Enter and Space both work.</CardDescription></CardHeader>
+    <CardContent><p role="status">Opened {count} times</p></CardContent>
+    <CardFooter><Button type="button" onClick={() => setCount((value) => value + 1)}>Open details</Button></CardFooter>
+  </Card>;
+}
+export const KeyboardAction: Story = { render: () => <ActionCard /> };

package/src/primitives/card.test.tsx

@@ -0,0 +1,71 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CardTitleProps } from "./card";
+
+describe("Card anatomy", () => {
+  it("keeps the existing default title tag and heading ref", () => {
+    const ref = createRef<HTMLHeadingElement>();
+    render(<CardTitle ref={ref} id="card-title">Details</CardTitle>);
+    expect(ref.current).toBe(screen.getByRole("heading", { level: 3 }));
+    expect(ref.current).toHaveAttribute("id", "card-title");
+  });
+
+  it.each([1, 2, 3, 4, 5, 6] as const)("allows an h%i without changing its visual treatment", (level) => {
+    const { rerender } = render(<CardTitle>Details</CardTitle>);
+    const classes = screen.getByRole("heading").className;
+    rerender(<CardTitle as={`h${level}` as CardTitleProps["as"]}>Details</CardTitle>);
+    expect(screen.getByRole("heading", { level }).className).toBe(classes);
+  });
+
+  it("preserves native attributes and caller classes", () => {
+    render(<CardTitle as="h2" role="presentation" className="text-xl" data-kind="summary">Summary</CardTitle>);
+    const title = screen.getByText("Summary");
+    expect(title).toHaveAttribute("role", "presentation");
+    expect(title).toHaveAttribute("data-kind", "summary");
+    expect(title).toHaveClass("text-xl");
+  });
+
+  it("uses the same gutter on every part and only removes subsequent top padding", () => {
+    render(<Card>
+      <CardHeader data-testid="header"><CardTitle>Details</CardTitle><CardDescription>Prose</CardDescription></CardHeader>
+      <CardContent data-testid="content">Body</CardContent>
+      <CardFooter data-testid="footer">Footer</CardFooter>
+    </Card>);
+    for (const part of ["header", "content", "footer"]) {
+      expect(screen.getByTestId(part)).toHaveClass("p-4");
+      expect(screen.getByTestId(part)).not.toHaveClass("p-6");
+    }
+    expect(screen.getByTestId("content")).toHaveClass("[&:not(:first-child)]:pt-0");
+    expect(screen.getByTestId("footer")).toHaveClass("[&:not(:first-child)]:pt-0");
+    // These are class/DOM contracts, not a browser-computed padding assertion.
+    expect(screen.getByText("Prose").tagName).toBe("P");
+  });
+
+  it("does not strip the top padding unconditionally from content-only cards", () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<Card><CardContent ref={ref}>Standalone</CardContent></Card>);
+    expect(ref.current).toHaveClass("p-4");
+    expect(ref.current).not.toHaveClass("pt-0");
+    expect(ref.current?.matches(":first-child")).toBe(true);
+  });
+
+  it("keeps hover decorative and leaves keyboard activation to a real button", async () => {
+    const user = userEvent.setup();
+    const activate = vi.fn();
+    const ref = createRef<HTMLDivElement>();
+    render(<Card ref={ref} hover>
+      <CardContent><button type="button" onClick={activate}>Open details</button></CardContent>
+    </Card>);
+    expect(ref.current?.tagName).toBe("DIV");
+    expect(ref.current).not.toHaveAttribute("tabindex");
+    expect(ref.current).not.toHaveAttribute("role");
+    expect(ref.current).not.toHaveClass("cursor-pointer");
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Open details" })).toHaveFocus();
+    await user.keyboard("{Enter}");
+    await user.keyboard(" ");
+    expect(activate).toHaveBeenCalledTimes(2);
+  });
+});

package/src/primitives/card.tsx

@@ -1,10 +1,12 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
+import { Heading } from "./heading";
 
 const Card = React.forwardRef<
   HTMLDivElement,
   React.HTMLAttributes<HTMLDivElement> & {
     variant?: "default" | "glass" | "sandbox" | "elevated";
+    /** Decorative border feedback only. Put actions in a native button or link. */
     hover?: boolean;
   }
 >(({ className, variant = "default", hover = false, ...props }, ref) => {
@@ -22,7 +24,7 @@ const Card = React.forwardRef<
         "rounded-[var(--radius-lg)] border text-card-foreground transition-[border-color,box-shadow]",
         "duration-[var(--transition-default)]",
         variants[variant],
-        hover && "cursor-pointer hover:border-[var(--border-strong)]",
+        hover && "hover:border-[var(--border-strong)]",
         className,
       )}
       {...props}
@@ -43,16 +45,22 @@ const CardHeader = React.forwardRef<
 ));
 CardHeader.displayName = "CardHeader";
 
-const CardTitle = React.forwardRef<
-  HTMLHeadingElement,
-  React.HTMLAttributes<HTMLHeadingElement>
->(({ className, ...props }, ref) => (
-  <h3
-    ref={ref}
-    className={cn("font-semibold leading-none tracking-tight", className)}
-    {...props}
-  />
-));
+export interface CardTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  /** Heading level appropriate to the surrounding document; h3 remains the default. */
+  as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+}
+
+const CardTitle = React.forwardRef<HTMLHeadingElement, CardTitleProps>(
+  ({ className, as = "h3", ...props }, ref) => (
+    <Heading
+      ref={ref}
+      variant="subsection"
+      as={as}
+      className={className}
+      {...props}
+    />
+  ),
+);
 CardTitle.displayName = "CardTitle";
 
 const CardDescription = React.forwardRef<
@@ -71,7 +79,11 @@ const CardContent = React.forwardRef<
   HTMLDivElement,
   React.HTMLAttributes<HTMLDivElement>
 >(({ className, ...props }, ref) => (
-  <div ref={ref} className={cn("p-4 pt-0", className)} {...props} />
+  <div
+    ref={ref}
+    className={cn("p-4 [&:not(:first-child)]:pt-0", className)}
+    {...props}
+  />
 ));
 CardContent.displayName = "CardContent";
 
@@ -81,7 +93,7 @@ const CardFooter = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn("flex items-center p-6 pt-0", className)}
+    className={cn("flex flex-wrap items-center gap-2 p-4 [&:not(:first-child)]:pt-0", className)}
     {...props}
   />
 ));

package/src/primitives/heading.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Heading } from "./heading";
+
+const meta = {
+  title: "Primitives/Heading",
+  component: Heading,
+  parameters: { layout: "padded" },
+  args: { variant: "page", children: "Activity across your workspace" },
+  argTypes: {
+    variant: { control: "select", options: ["display", "hero", "page", "section", "subsection", "eyebrow"] },
+    as: { control: "select", options: ["h1", "h2", "h3", "h4", "h5", "h6", "p"] },
+  },
+} satisfies Meta<typeof Heading>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+export const IndependentSemantics: Story = {
+  args: { variant: "page", as: "h2", children: "Page-sized title in a nested surface" },
+};
+export const Hierarchy: Story = {
+  render: () => <main className="space-y-6">
+    <Heading variant="eyebrow">Workspace</Heading>
+    <Heading variant="page">Activity</Heading>
+    <section className="space-y-4">
+      <Heading variant="section">Recent items</Heading>
+      <Heading variant="subsection">Build details</Heading>
+      <p className="text-muted-foreground">Eyebrows are labels, not extra headings.</p>
+    </section>
+  </main>,
+  play: ({ canvasElement }) => {
+    const tags = Array.from(canvasElement.querySelectorAll("h1,h2,h3,h4,h5,h6")).map((node) => node.tagName).join(",");
+    if (tags !== "H1,H2,H3") throw new Error(`Unexpected heading hierarchy: ${tags}`);
+  },
+};

package/src/primitives/heading.test.tsx

@@ -0,0 +1,56 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Heading, type HeadingVariant } from "./heading";
+
+const roles: [HeadingVariant, string][] = [
+  ["display", "H1"], ["hero", "H2"], ["page", "H1"],
+  ["section", "H2"], ["subsection", "H3"], ["eyebrow", "P"],
+];
+
+describe("Heading", () => {
+  it.each(roles)("gives %s its existing default element", (variant, tag) => {
+    render(<Heading variant={variant}>Title</Heading>);
+    expect(screen.getByText("Title").tagName).toBe(tag);
+  });
+
+  it.each(roles)("maps Sandbox's %s role without emitting an invalid ARIA role", (role, tag) => {
+    render(<Heading role={role}>Title</Heading>);
+    const title = screen.getByText("Title");
+    expect(title.tagName).toBe(tag);
+    expect(title).not.toHaveAttribute("role");
+  });
+
+  it("changes semantics without changing the visual variant", () => {
+    const { rerender } = render(<Heading variant="page">Title</Heading>);
+    const classes = screen.getByRole("heading", { level: 1 }).className;
+    rerender(<Heading variant="page" as="h4">Title</Heading>);
+    expect(screen.getByRole("heading", { level: 4 }).className).toBe(classes);
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+  });
+
+  it("lets an explicit variant win over the existing visual-role input", () => {
+    render(<Heading variant="section" role="page">Title</Heading>);
+    expect(screen.getByRole("heading", { level: 2 })).not.toHaveAttribute("role");
+  });
+
+  it("forwards native roles, refs and HTML attributes", () => {
+    const ref = createRef<HTMLElement>();
+    render(<Heading ref={ref} variant="eyebrow" as="div" role="note" id="scope" className="custom" data-scope="all">Scope</Heading>);
+    const note = screen.getByRole("note");
+    expect(ref.current).toBe(note);
+    expect(note).toHaveAttribute("id", "scope");
+    expect(note).toHaveAttribute("data-scope", "all");
+    expect(note).toHaveClass("custom");
+  });
+
+  it("keeps a page, section and nested title in document order", () => {
+    render(<main>
+      <Heading variant="page">Activity</Heading>
+      <Heading variant="eyebrow">Last day</Heading>
+      <Heading variant="section">Recent activity</Heading>
+      <Heading variant="subsection">Details</Heading>
+    </main>);
+    expect(screen.getAllByRole("heading").map((node) => node.tagName)).toEqual(["H1", "H2", "H3"]);
+  });
+});

package/src/primitives/heading.tsx

@@ -0,0 +1,76 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/** Visual roles ported from sandbox-ui/src/primitives/heading.tsx. */
+export type HeadingVariant =
+  | "display"
+  | "hero"
+  | "page"
+  | "section"
+  | "subsection"
+  | "eyebrow";
+
+// Keep Brand's existing size, leading, tracking and weight tokens. The literal
+// fallbacks are the existing Sandbox treatment, not a second type scale.
+const VARIANT_CLASS: Record<HeadingVariant, string> = {
+  display:
+    "font-display font-bold text-foreground text-[length:var(--font-size-display,3rem)] leading-[var(--line-height-display,1.05)] tracking-[var(--tracking-tight,-0.02em)]",
+  hero: "font-display font-bold text-foreground text-[length:var(--font-size-hero,2.5rem)] leading-[1.1] tracking-[var(--tracking-tight,-0.02em)]",
+  page: "font-display font-semibold text-foreground text-[length:var(--font-size-3xl,1.875rem)] leading-[var(--line-height-heading,1.15)] tracking-[var(--tracking-tight,-0.02em)]",
+  section:
+    "font-display font-semibold text-foreground text-[length:var(--font-size-xl,1.25rem)] leading-[1.3] tracking-[var(--tracking-snug,-0.01em)]",
+  subsection:
+    "font-semibold text-foreground text-[length:var(--font-size-lg,1rem)] leading-[1.4]",
+  eyebrow:
+    "font-semibold uppercase text-muted-foreground text-[length:var(--font-size-sm,0.75rem)] leading-none tracking-[var(--tracking-wide,0.08em)]",
+};
+
+const DEFAULT_TAG: Record<HeadingVariant, React.ElementType> = {
+  display: "h1",
+  hero: "h2",
+  page: "h1",
+  section: "h2",
+  subsection: "h3",
+  eyebrow: "p",
+};
+
+export interface HeadingProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "role"> {
+  /** Visual treatment, independent of the rendered element. Defaults to section. */
+  variant?: HeadingVariant;
+  /** Semantic element; changing it does not change the visual variant. */
+  as?: React.ElementType;
+  /**
+   * Native ARIA role, or Sandbox's existing visual-role input. Only the six
+   * legacy visual values are consumed; they are never emitted as ARIA roles.
+   * Prefer variant for new code. An explicit variant wins over a legacy role.
+   */
+  role?: React.AriaRole | HeadingVariant;
+}
+
+/**
+ * One renderer for page, section and card titles. Use at most one default
+ * display/page h1 per page; choose `as` according to the document hierarchy.
+ */
+const Heading = React.forwardRef<HTMLElement, HeadingProps>(
+  ({ variant, role, as, className, ...props }, ref) => {
+    const legacyVariant =
+      role && Object.prototype.hasOwnProperty.call(VARIANT_CLASS, role)
+        ? (role as HeadingVariant)
+        : undefined;
+    const visualVariant = variant ?? legacyVariant ?? "section";
+    const Tag = as ?? DEFAULT_TAG[visualVariant];
+
+    return (
+      <Tag
+        ref={ref}
+        className={cn("[overflow-wrap:anywhere]", VARIANT_CLASS[visualVariant], className)}
+        role={legacyVariant ? undefined : role}
+        {...props}
+      />
+    );
+  },
+);
+Heading.displayName = "Heading";
+
+export { Heading };

package/src/primitives/index.ts

@@ -9,6 +9,7 @@ export {
   CardDescription,
   CardContent,
 } from "./card";
+export type { CardTitleProps } from "./card";
 
 export {
   Dialog,
@@ -72,6 +73,7 @@ export {
   TableCell,
   TableCaption,
 } from "./table";
+export type { TableProps } from "./table";
 
 export { Tabs, TabsList, TabsTrigger, TabsContent } from "./tabs";
 
@@ -122,6 +124,12 @@ export type { CodeBlockProps, InlineCodeProps } from "./code-block";
 
 export { ThemeToggle, useTheme } from "./theme-toggle";
 
+export { Heading } from "./heading";
+export type { HeadingProps, HeadingVariant } from "./heading";
+
+export { PageShell } from "./page-shell";
+export type { PageShellProps } from "./page-shell";
+
 export { PageHeader } from "./page-header";
 export type { PageHeaderProps } from "./page-header";
 

package/src/primitives/input.stories.tsx

@@ -1,5 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import { useId } from 'react'
 import { Input, Textarea } from './input'
+import { Label } from './label'
 
 const meta: Meta<typeof Input> = {
   title: 'Primitives/Input',
@@ -111,3 +113,29 @@ export const Overview: Story = {
     </div>
   ),
 }
+
+export const FieldRelationships: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Repeated labels must focus their own fields. Inspect accessible descriptions: caller help, hints, and errors coexist. The final field uses an explicit ID and the standalone shared Label.',
+      },
+    },
+  },
+  render: function FieldRelationships() {
+    const id = useId()
+    const descriptionId = `${id}-instructions`
+    return (
+      <div className="flex w-96 flex-col gap-4">
+        <p id={descriptionId}>Shared instructions: choose a descriptive name.</p>
+        <Input label="Name" hint="First name." aria-describedby={descriptionId} />
+        <Input label="Name" hint="Second name." error="A name is required." aria-describedby={descriptionId} />
+        <Textarea label="Name" hint="Explain the name." error="More detail is needed." aria-describedby={descriptionId} />
+        <div className="space-y-1.5">
+          <Label htmlFor={`${id}-explicit`}>External label</Label>
+          <Input id={`${id}-explicit`} hint="Explicit field ID is preserved." />
+        </div>
+      </div>
+    )
+  },
+}

package/src/primitives/input.test.tsx

@@ -0,0 +1,161 @@
+import * as React from "react";
+import { act, cleanup, render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Input, Textarea } from "./input";
+import { Label } from "./label";
+
+afterEach(cleanup);
+
+describe.each([
+  ["Input", Input],
+  ["Textarea", Textarea],
+] as const)("%s relationships", (_name, Field) => {
+  it("gives repeated labels distinct, stable IDs and focuses the correct field", async () => {
+    const user = userEvent.setup();
+    const { rerender } = render(<><Field label="Name" /><Field label="Name" /></>);
+    const fields = screen.getAllByRole("textbox");
+    const ids = fields.map((field) => field.id);
+    expect(ids.every(Boolean)).toBe(true);
+    expect(new Set(ids).size).toBe(2);
+    expect(screen.getAllByLabelText("Name")).toEqual(fields);
+    for (const [index, label] of screen.getAllByText("Name", { selector: "label" }).entries()) {
+      expect(label).toHaveAttribute("for", ids[index]);
+      await user.click(label);
+      expect(fields[index]).toHaveFocus();
+    }
+    rerender(<><Field label="Renamed" /><Field label="Renamed" /></>);
+    expect(screen.getAllByRole("textbox").map((field) => field.id)).toEqual(ids);
+  });
+
+  it("preserves an explicit ID and merges caller, hint and error descriptions without duplicates", () => {
+    render(<>
+      <p id="external">External instructions.</p>
+      <Field
+        id="profile"
+        label="Name"
+        hint="Use your full name."
+        error="Name is required."
+        aria-describedby={" external  external\tprofile-hint "}
+        aria-invalid={false}
+      />
+    </>);
+    const field = screen.getByRole("textbox", { name: "Name" });
+    expect(field).toHaveAttribute("id", "profile");
+    expect(field).toHaveAttribute("aria-describedby", "external profile-hint profile-error");
+    expect(screen.getByText("Use your full name.")).toHaveAttribute("id", "profile-hint");
+    expect(screen.getByText("Name is required.")).toHaveAttribute("id", "profile-error");
+    expect(field).toHaveAccessibleDescription("External instructions. Use your full name. Name is required.");
+    expect(field).toHaveAttribute("aria-invalid", "true");
+  });
+
+  it("associates descriptions without a convenience label and removes stale relationships", () => {
+    const { rerender } = render(<Field aria-label="Name" hint="A hint" error="An error" />);
+    const field = screen.getByRole("textbox", { name: "Name" });
+    const id = field.id;
+    expect(id).not.toBe("");
+    expect(field).toHaveAccessibleDescription("A hint An error");
+    rerender(<Field aria-label="Name" hint="A hint" />);
+    expect(field.id).toBe(id);
+    expect(field).toHaveAttribute("aria-describedby", `${id}-hint`);
+    expect(field).not.toHaveAttribute("aria-invalid");
+    expect(document.getElementById(`${id}-error`)).toBeNull();
+    rerender(<Field aria-label="Name" />);
+    const bareField = screen.getByRole("textbox", { name: "Name" });
+    expect(bareField.id).toBe(id);
+    expect(bareField).not.toHaveAttribute("aria-describedby");
+    expect(document.getElementById(`${id}-hint`)).toBeNull();
+  });
+
+  it("preserves the bare-element API and caller invalid states", () => {
+    const { container, rerender } = render(
+      <Field aria-label="Name" aria-describedby="external" aria-invalid="spelling" className="caller-class" />,
+    );
+    const field = screen.getByRole("textbox");
+    expect(container.firstElementChild).toBe(field);
+    expect(container.childElementCount).toBe(1);
+    expect(field).toHaveAttribute("aria-describedby", "external");
+    expect(field).toHaveAttribute("aria-invalid", "spelling");
+    expect(field).toHaveClass("caller-class");
+    rerender(<Field aria-label="Name" aria-invalid={false} />);
+    expect(field).toHaveAttribute("aria-invalid", "false");
+  });
+
+  it("uses the existing Label treatment", () => {
+    render(<><Label className="block">Reference</Label><Field label="Name" /></>);
+    expect(screen.getByText("Name", { selector: "label" }).className)
+      .toBe(screen.getByText("Reference").className);
+  });
+});
+
+it("keeps Input and Textarea IDs distinct even with the same label", () => {
+  render(<><Input label="Notes" /><Textarea label="Notes" /></>);
+  expect(new Set(screen.getAllByRole("textbox").map((field) => field.id)).size).toBe(2);
+});
+
+it("exposes Input's error variant without requiring error text", () => {
+  render(<Input aria-label="Name" variant="error" />);
+  expect(screen.getByRole("textbox")).toHaveAttribute("aria-invalid", "true");
+});
+
+it("forwards native field refs, values and change handlers", async () => {
+  const user = userEvent.setup();
+  const inputRef = React.createRef<HTMLInputElement>();
+  const textareaRef = React.createRef<HTMLTextAreaElement>();
+  const inputChange = vi.fn();
+  const textareaChange = vi.fn();
+  const { unmount } = render(<>
+    <Input ref={inputRef} label="Name" defaultValue="A" onChange={inputChange} />
+    <Textarea ref={textareaRef} label="Notes" defaultValue="B" onChange={textareaChange} />
+  </>);
+  expect(inputRef.current).toBe(screen.getByRole("textbox", { name: "Name" }));
+  expect(textareaRef.current).toBe(screen.getByRole("textbox", { name: "Notes" }));
+  await user.type(inputRef.current!, "lice");
+  await user.type(textareaRef.current!, "ody");
+  expect(inputRef.current).toHaveValue("Alice");
+  expect(textareaRef.current).toHaveValue("Body");
+  expect(inputChange).toHaveBeenCalled();
+  expect(textareaChange).toHaveBeenCalled();
+  unmount();
+  expect(inputRef.current).toBeNull();
+  expect(textareaRef.current).toBeNull();
+});
+
+it("hydrates SSR IDs and all description relationships without mismatch", async () => {
+  const ui = <React.StrictMode>
+    <p id="external">External instructions.</p>
+    <Input label="Name" hint="First hint" />
+    <Input label="Name" error="Required" />
+    <Textarea label="Name" hint="Notes hint" error="Too short" aria-describedby="external" />
+    <Input id="explicit" label="Explicit" hint="Explicit hint" />
+  </React.StrictMode>;
+  const container = document.createElement("div");
+  container.innerHTML = renderToString(ui, { identifierPrefix: "fields-" });
+  document.body.appendChild(container);
+  const serverHTML = container.innerHTML;
+  const serverIds = within(container).getAllByRole("textbox").map((field) => field.id);
+  const recoverableError = vi.fn();
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+  let root: Root | undefined;
+  try {
+    await act(async () => {
+      root = hydrateRoot(container, ui, { identifierPrefix: "fields-", onRecoverableError: recoverableError });
+    });
+    expect(new Set(serverIds).size).toBe(4);
+    expect(within(container).getAllByRole("textbox").map((field) => field.id)).toEqual(serverIds);
+    expect(container.innerHTML).toBe(serverHTML);
+    for (const field of within(container).getAllByRole("textbox")) {
+      for (const id of field.getAttribute("aria-describedby")!.split(" ")) {
+        expect(document.getElementById(id)).not.toBeNull();
+      }
+    }
+    expect(recoverableError).not.toHaveBeenCalled();
+    expect(consoleError).not.toHaveBeenCalled();
+  } finally {
+    await act(async () => { root?.unmount(); });
+    consoleError.mockRestore();
+    container.remove();
+  }
+});