@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/field/field.tsx

@@ -0,0 +1,342 @@
+"use client";
+
+import {
+  cloneElement,
+  forwardRef,
+  useCallback,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useState,
+  type ComponentPropsWithoutRef,
+  type ElementRef,
+  type HTMLAttributes,
+  type ReactElement,
+} from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "../../lib/cn";
+import { hasRenderableContent } from "../../lib/has-renderable-content";
+import { Label } from "../label";
+import { FieldContext, useFieldContext, type FieldContextValue } from "./field-context";
+
+// ── FieldRoot ─────────────────────────────────────────────────────────────
+
+export interface FieldRootProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Whether the field is currently invalid. Drives `aria-invalid` on every
+   * `FieldControl` and error styling on `FieldLabel` — independent of
+   * whether a `FieldError` with content is actually mounted, so a caller can
+   * mark the control invalid before its message has settled.
+   */
+  invalid?: boolean;
+  /** Whether the field is required. Drives `aria-required` on every `FieldControl`. */
+  required?: boolean;
+}
+
+/**
+ * Compound-anatomy field: `FieldRoot` owns id generation and `aria-describedby`
+ * composition; `FieldLabel`/`FieldControl`/`FieldDescription`/`FieldError` read
+ * that state from context and can be composed in ANY order/layout — including
+ * more than one `FieldControl` in one row (e.g. first/last name) or a
+ * `FieldDescription` placed before the control. Mirrors the same accessibility
+ * wiring `FieldRow` (`../field-row`) already validated (id/`aria-describedby`/
+ * `aria-invalid`/`role="alert"`), adapted to a shared lifted-state context so
+ * it holds across independently-composed parts; `FieldRow` remains the
+ * convenience wrapper for the common single-control case and is unaffected by
+ * this addition (#43).
+ *
+ * @example
+ * ```tsx
+ * <FieldRoot invalid={!!error} required>
+ *   <FieldLabel>{label}</FieldLabel>
+ *   <FieldControl><Input /></FieldControl>
+ *   <FieldDescription>{helpText}</FieldDescription>
+ *   <FieldError>{error}</FieldError>
+ * </FieldRoot>
+ * ```
+ */
+export const FieldRoot = forwardRef<HTMLDivElement, FieldRootProps>(function FieldRoot(
+  { invalid = false, required = false, className, children, ...props },
+  ref,
+) {
+  // Each `FieldDescription`/`FieldError` INSTANCE generates and registers its
+  // own id (see below) — two lists, not one shared slot per part type, so
+  // more than one of either part under one `FieldRoot` gets distinct ids
+  // instead of colliding, and unmounting one instance only ever removes that
+  // instance's own id from its own list (never a sibling's).
+  const [descriptionIds, setDescriptionIds] = useState<readonly string[]>([]);
+  const registerDescription = useCallback((descId: string) => {
+    setDescriptionIds((prev) => (prev.includes(descId) ? prev : [...prev, descId]));
+  }, []);
+  const unregisterDescription = useCallback((descId: string) => {
+    setDescriptionIds((prev) => (prev.includes(descId) ? prev.filter((x) => x !== descId) : prev));
+  }, []);
+
+  const [errorIds, setErrorIds] = useState<readonly string[]>([]);
+  const registerError = useCallback((errId: string) => {
+    setErrorIds((prev) => (prev.includes(errId) ? prev : [...prev, errId]));
+  }, []);
+  const unregisterError = useCallback((errId: string) => {
+    setErrorIds((prev) => (prev.includes(errId) ? prev.filter((x) => x !== errId) : prev));
+  }, []);
+
+  // Fixed semantic order — every description before every error — regardless
+  // of DOM order or registration order, so "description placed before the
+  // control" reorders the VISIBLE layout without reordering the announced
+  // description, and a second description/error is appended rather than
+  // replacing the first.
+  const describedBy = useMemo(() => {
+    const ids = [...descriptionIds, ...errorIds];
+    return ids.length > 0 ? ids.join(" ") : undefined;
+  }, [descriptionIds, errorIds]);
+
+  // `FieldLabel`'s `htmlFor` can only point to ONE control, so it binds to
+  // whichever `FieldControl` registers FIRST (JSX/mount order) — the common
+  // single-control case gets this for free; a multi-control row (e.g.
+  // first/last name) still labels the first field, and every additional
+  // control needs its own explicit `id` the same way any two form controls
+  // would (no new coordination prop invented for this).
+  const [controlOrder, setControlOrder] = useState<readonly string[]>([]);
+  const registerControl = useCallback((controlId: string) => {
+    setControlOrder((prev) => (prev.includes(controlId) ? prev : [...prev, controlId]));
+  }, []);
+  const unregisterControl = useCallback((controlId: string) => {
+    setControlOrder((prev) =>
+      prev.includes(controlId) ? prev.filter((x) => x !== controlId) : prev,
+    );
+  }, []);
+  const labelFor = controlOrder[0];
+
+  const value = useMemo<FieldContextValue>(
+    () => ({
+      labelFor,
+      registerControl,
+      unregisterControl,
+      invalid,
+      required,
+      describedBy,
+      registerDescription,
+      unregisterDescription,
+      registerError,
+      unregisterError,
+    }),
+    [
+      labelFor,
+      registerControl,
+      unregisterControl,
+      invalid,
+      required,
+      describedBy,
+      registerDescription,
+      unregisterDescription,
+      registerError,
+      unregisterError,
+    ],
+  );
+
+  return (
+    <FieldContext.Provider value={value}>
+      <div ref={ref} data-slot="field" className={cn("space-y-2", className)} {...props}>
+        {children}
+      </div>
+    </FieldContext.Provider>
+  );
+});
+
+// ── FieldLabel ────────────────────────────────────────────────────────────
+
+export const FieldLabel = forwardRef<
+  ElementRef<typeof Label>,
+  ComponentPropsWithoutRef<typeof Label>
+>(function FieldLabel({ className, ...props }, ref) {
+  const { labelFor, invalid } = useFieldContext("FieldLabel");
+  return (
+    <Label
+      ref={ref}
+      htmlFor={labelFor}
+      data-slot="field-label"
+      className={cn(
+        "transition-colors duration-fast ease-standard",
+        invalid && "text-destructive-text",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+// ── FieldControl ──────────────────────────────────────────────────────────
+
+export interface FieldControlProps {
+  /**
+   * The single field control (`Input`, `Textarea`, `Select`, …). Receives
+   * `id`/`aria-describedby`/`aria-invalid`/`aria-required` via a Radix
+   * `Slot` — must be a single element that forwards those props to a real
+   * form control. Compose more than one `FieldControl` inside one
+   * `FieldRoot` for a multi-control row (each gets its own independent id;
+   * give every control but the first its own explicit `id`, the same way
+   * you would for any two form controls that must not collide). `FieldLabel`
+   * can only associate with ONE control (the first to mount), so give every
+   * OTHER control in the row its own `aria-label` — a shared visual label
+   * plus a placeholder is not a real accessible name for the rest.
+   */
+  children: ReactElement<{
+    id?: string;
+    "aria-describedby"?: string;
+  }>;
+}
+
+export const FieldControl = forwardRef<ElementRef<typeof Slot>, FieldControlProps>(
+  function FieldControl({ children }, ref) {
+    const { invalid, required, describedBy, registerControl, unregisterControl } =
+      useFieldContext("FieldControl");
+    // Independent per-instance fallback id — guarantees uniqueness with no
+    // coordination needed when more than one `FieldControl` shares a
+    // `FieldRoot` (e.g. a first/last-name row).
+    const generatedId = useId();
+
+    // Same "child wins, but COMPOSE rather than discard" merge FieldRow uses:
+    // Radix `Slot` merges child props OVER slot props, so a control that
+    // already carries its own `id`/`aria-describedby` must not silently lose
+    // the label association / description-error wiring.
+    const control = children;
+    const childProps = control.props;
+    const id = childProps.id ?? generatedId;
+    const composedDescribedBy =
+      [childProps["aria-describedby"] ?? null, describedBy ?? null].filter(Boolean).join(" ") ||
+      undefined;
+
+    useLayoutEffect(() => {
+      registerControl(id);
+      return () => unregisterControl(id);
+    }, [id, registerControl, unregisterControl]);
+
+    return (
+      <Slot
+        ref={ref}
+        id={id}
+        aria-describedby={composedDescribedBy}
+        aria-invalid={invalid}
+        aria-required={required || undefined}
+        data-slot="field-control"
+      >
+        {cloneElement(control, { id, "aria-describedby": composedDescribedBy })}
+      </Slot>
+    );
+  },
+);
+
+// ── FieldDescription ──────────────────────────────────────────────────────
+
+/**
+ * Optional field help text. Renders nothing — and registers no
+ * `aria-describedby` reference — when `children` is falsy (`false`/`0`/`""`/
+ * `null`/`undefined`), an empty array, or an array containing only falsy
+ * values (`{list.map(...)}` on an empty list; `[a && "x", b && "y"]` with
+ * both false) — matching `FieldRow`'s `description ? … : null` convention:
+ * `{hint && <FieldDescription>{hint}</FieldDescription>}` is the supported
+ * way to express "no description".
+ *
+ * **Known limit:** a child that is itself a COMPONENT that renders nothing
+ * (returns `null`/an empty fragment) is not knowable from the element
+ * before render, so it still produces an empty paragraph that
+ * `aria-describedby` points at. `FieldRow` and the wider React ecosystem
+ * share this limit — pass a falsy child instead of a component that may
+ * render nothing.
+ */
+export const FieldDescription = forwardRef<
+  HTMLParagraphElement,
+  HTMLAttributes<HTMLParagraphElement>
+>(function FieldDescription({ className, children, id, ...props }, ref) {
+  const { registerDescription, unregisterDescription } = useFieldContext("FieldDescription");
+  // Own id per INSTANCE — two `FieldDescription`s under one `FieldRoot` (a hint
+  // above the control and a hint below it) must not collide on one shared id.
+  const instanceId = useId();
+  const generatedId = `${instanceId}-description`;
+  // Caller-supplied `id` wins — same "child wins" resolution `FieldControl`
+  // already uses (`childProps.id ?? generatedId`). Resolving ONE effective id
+  // up front, and destructuring `id` out of `...props` above, means the value
+  // registered into `aria-describedby` and the value actually rendered on the
+  // `<p>` can never diverge (PR #97 review finding 3).
+  const descriptionId = id ?? generatedId;
+  // Same falsy-content convention `FieldRow` uses (`description ? … : null`)
+  // — see `hasRenderableContent` (`../../lib/has-renderable-content`) for
+  // the full rationale, shared with `FieldError` below and `FieldRow`.
+  const hasContent = hasRenderableContent(children);
+
+  useLayoutEffect(() => {
+    if (!hasContent) return undefined;
+    registerDescription(descriptionId);
+    return () => unregisterDescription(descriptionId);
+  }, [hasContent, descriptionId, registerDescription, unregisterDescription]);
+
+  if (!hasContent) return null;
+
+  return (
+    <p
+      ref={ref}
+      id={descriptionId}
+      data-slot="field-description"
+      className={cn("text-body text-muted-foreground", className)}
+      {...props}
+    >
+      {children}
+    </p>
+  );
+});
+
+// ── FieldError ────────────────────────────────────────────────────────────
+
+/**
+ * Validation error text, announced via `role="alert"`. Renders nothing —
+ * and registers no `aria-describedby` reference — when `children` is falsy
+ * (`false`/`0`/`""`/`null`/`undefined`), an empty array, or an array
+ * containing only falsy values (`{errors.map(...)}` on an empty array is
+ * exactly how a real form renders "no errors") — matching `FieldRow`'s
+ * `error ? … : null` convention: `{error && <FieldError>{error}</FieldError>}`
+ * is the supported way to express "no error".
+ *
+ * **Known limit:** a child that is itself a COMPONENT that renders nothing
+ * (returns `null`/an empty fragment) is not knowable from the element
+ * before render, so it still produces an empty `role="alert"` element that
+ * `aria-describedby` points at (a screen reader announces an empty alert).
+ * `FieldRow` and the wider React ecosystem share this limit — pass a falsy
+ * child instead of a component that may render nothing.
+ */
+export const FieldError = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLParagraphElement>>(
+  function FieldError({ className, children, id, ...props }, ref) {
+    const { registerError, unregisterError } = useFieldContext("FieldError");
+    // Own id per INSTANCE — same reasoning as `FieldDescription`.
+    const instanceId = useId();
+    const generatedId = `${instanceId}-error`;
+    // Caller-supplied `id` wins — same resolution as `FieldDescription`/
+    // `FieldControl` (PR #97 review finding 3: this had the identical
+    // ordering bug as `FieldDescription`).
+    const errorId = id ?? generatedId;
+    // Same falsy-content convention as `FieldDescription`/`FieldRow`'s
+    // `error ? … : null` — see `hasRenderableContent`
+    // (`../../lib/has-renderable-content`) for the full rationale.
+    const hasContent = hasRenderableContent(children);
+
+    useLayoutEffect(() => {
+      if (!hasContent) return undefined;
+      registerError(errorId);
+      return () => unregisterError(errorId);
+    }, [hasContent, errorId, registerError, unregisterError]);
+
+    if (!hasContent) return null;
+
+    return (
+      <p
+        ref={ref}
+        id={errorId}
+        role="alert"
+        data-slot="field-error"
+        className={cn("text-body font-medium text-destructive-text", className)}
+        {...props}
+      >
+        {children}
+      </p>
+    );
+  },
+);

package/src/components/field/index.ts

@@ -0,0 +1,9 @@
+export {
+  FieldRoot,
+  FieldLabel,
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  type FieldRootProps,
+  type FieldControlProps,
+} from "./field";

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

@@ -1,3 +1,4 @@
+import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect } from "storybook/test";
 import { Input } from "../input";
@@ -12,7 +13,7 @@ const meta = {
     docs: {
       description: {
         component:
-          "Label/description/error/aria-describedby wiring for a single field OUTSIDE a react-hook-form context. See Forms/Form for the RHF-bound equivalent.",
+          "Label/description/error/aria-describedby wiring for a single field OUTSIDE a react-hook-form context. See Forms/Form for the RHF-bound equivalent.\n\n**Runtime-agnostic (#26).** `FieldRow` never imports `react-hook-form` — it renders entirely from plain `label`/`description`/`error` props, so it works just as readily with a `useState`-controlled field, Formik, Final Form, TanStack Form or a bespoke reducer. `react-hook-form`/`@hookform/resolvers` are optional peers of `@elabs-ai/components-ui`, so a consumer who only uses `FieldRow` never installs or bundles either — the RHF-bound `Form` family lives on the separate `@elabs-ai/components-ui/form` subpath. See the “Driven by external state” story below for a worked, non-RHF example (including the error state), and `docs/CONSUMING.md` for the Formik and plain-`useState` snippets. Reach for the RHF-bound `Form`/`FormField` family (Forms/Form) instead once the field already lives inside a `react-hook-form` `<FormProvider>` — `FieldRow` covers the gap outside it, it does not replace that family.",
       },
     },
   },
@@ -112,3 +113,86 @@ export const WithTextarea: Story = {
     expect(canvas.getByRole("textbox")).toHaveFocus();
   },
 };
+
+// A small local email-shape check — deliberately NOT `event.target.checkValidity()`.
+// Verified against real `<input type="email">` constraint validation (#26
+// fix-round-1 finding 2): the native HTML5 email format does NOT require a
+// dot in the domain, so `checkValidity()` treats "jane@invalid" as VALID —
+// it would not reproduce the contradiction this demo exists to guard
+// against. A `local-part@domain.tld` regex is the smallest check that
+// actually agrees with "looks like a real email", so it can't clear the
+// error for "@", "jane@" or "jane@invalid" the way the old
+// `value.includes("@")` predicate did.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Stands a plain `useState`-controlled value in for "any runtime" (a bespoke
+ * reducer, Formik's `meta.error`, TanStack Form's `field.state.meta.errors`,
+ * …) — `FieldRow` only ever reads the `label`/`description`/`error` props it
+ * is handed, so the same shape works for all of them. No `FormProvider`/RHF
+ * context exists anywhere in this component's tree.
+ */
+function EmailField({ initialValue }: { initialValue: string }) {
+  const [value, setValue] = useState(initialValue);
+  const error = EMAIL_RE.test(value) ? undefined : "Enter a valid email address.";
+
+  return (
+    <div className="w-72">
+      <FieldRow label="Email" description="We'll only use this to send receipts." error={error}>
+        <Input type="email" value={value} onChange={(event) => setValue(event.target.value)} />
+      </FieldRow>
+    </div>
+  );
+}
+
+/**
+ * Issue #26's fourth ask: a worked example of `FieldRow` driven by a form
+ * runtime that is NOT react-hook-form — this is the story the docs and PR
+ * point readers at as "starts already invalid so the `aria-invalid`/
+ * `role="alert"` wiring is visible without interaction". Its play function
+ * therefore only ASSERTS the error state; it never resolves it, so the
+ * canvas a reader inspects (both in the story view and on the autodocs page,
+ * where Storybook runs `play` on mount the same way) stays on the
+ * documented error state. See "Driven by external state — validity
+ * transitions" below for the invalid→valid interaction instead (#26
+ * fix-round-1 finding 1 — the previous version of this story cleared its own
+ * error inside `play`, so the state the docs claimed to show never actually
+ * survived a render).
+ */
+export const RuntimeAgnostic: Story = {
+  name: "Driven by external state (no react-hook-form)",
+  render: () => <EmailField initialValue="not-an-email" />,
+  play: async ({ canvas }) => {
+    const input = canvas.getByRole("textbox");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+    const alert = canvas.getByRole("alert");
+    expect(alert).toHaveTextContent("Enter a valid email address.");
+    expect(input.getAttribute("aria-describedby")?.split(" ")).toContain(alert.id);
+  },
+};
+
+/**
+ * The invalid→valid half of the lifecycle, kept in its own story so the
+ * documented error example above (`RuntimeAgnostic`) never settles into the
+ * success state on render (#26 fix-round-1 finding 1). Also locks finding
+ * 2: "jane@invalid" has an `@` but no valid domain and must NOT clear the
+ * error — `value.includes("@")` used to accept it.
+ */
+export const RuntimeAgnosticValidation: Story = {
+  name: "Driven by external state — validity transitions",
+  render: () => <EmailField initialValue="not-an-email" />,
+  play: async ({ canvas, userEvent }) => {
+    const input = canvas.getByRole("textbox");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+
+    await userEvent.clear(input);
+    await userEvent.type(input, "jane@invalid");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+    expect(canvas.getByRole("alert")).toHaveTextContent("Enter a valid email address.");
+
+    await userEvent.clear(input);
+    await userEvent.type(input, "jane@example.com");
+    expect(input).toHaveAttribute("aria-invalid", "false");
+    expect(canvas.queryByRole("alert")).toBeNull();
+  },
+};

package/src/components/field-row/field-row.test.tsx

@@ -185,4 +185,149 @@ describe("FieldRow", () => {
     for (const id of frDescribedBy) expect(document.getElementById(id)).not.toBeNull();
     expect(frInput).toHaveAttribute("aria-invalid", "true");
   });
+
+  // #26 — the runtime-agnostic contract: FieldRow must wire aria-invalid /
+  // aria-describedby / role="alert" from PLAIN external state (any form
+  // runtime — a bespoke reducer, Formik's `meta.error`, TanStack Form's
+  // `field.state.meta.errors`, …), with NO react-hook-form FormProvider
+  // mounted anywhere in the tree. This locks the story's documented example:
+  // if FieldRow ever grew an accidental RHF coupling (e.g. reading
+  // useFormContext internally), this render would throw before any
+  // assertion below ran.
+  it("wires aria-invalid + aria-describedby from a field driven entirely by external state, with no form-runtime provider mounted", () => {
+    function ExternallyControlledField({ error }: { error?: string }) {
+      // Stands in for "any form runtime": FieldRow only ever reads the
+      // label/description/error props it is handed, whatever produced them.
+      return (
+        <FieldRow label="Email" error={error}>
+          <Input value="" onChange={() => {}} />
+        </FieldRow>
+      );
+    }
+
+    const { rerender } = render(<ExternallyControlledField />);
+    const input = screen.getByRole("textbox");
+    expect(input).toHaveAttribute("aria-invalid", "false");
+    expect(input).not.toHaveAttribute("aria-describedby");
+    expect(screen.queryByRole("alert")).toBeNull();
+
+    rerender(<ExternallyControlledField error="Enter a valid email address." />);
+    const errorNode = screen.getByRole("alert");
+    expect(errorNode).toHaveTextContent("Enter a valid email address.");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+    expect(input.getAttribute("aria-describedby")).toBe(errorNode.id);
+  });
+
+  // #93 (B) — FieldRow used bare truthiness (`error ? … : null`) to gate the
+  // alert, the id contribution and aria-invalid, so an empty/all-falsy ARRAY
+  // (every array is truthy in JS) still produced a referenced, empty
+  // role="alert" and marked the control invalid with nothing to explain why.
+  // `Field*` already handles this shape correctly (field.test.tsx) — this
+  // locks the same behavior on FieldRow.
+  it("renders no error element, no aria-invalid, and no aria-describedby reference for an empty array or an array of only falsy children", () => {
+    const { rerender } = render(
+      <FieldRow label="Email" error={[]}>
+        <Input />
+      </FieldRow>,
+    );
+    let input = screen.getByRole("textbox");
+    expect(screen.queryByRole("alert")).toBeNull();
+    expect(input).toHaveAttribute("aria-invalid", "false");
+    expect(input).not.toHaveAttribute("aria-describedby");
+
+    rerender(
+      <FieldRow label="Email" error={[false, null]}>
+        <Input />
+      </FieldRow>,
+    );
+    input = screen.getByRole("textbox");
+    expect(screen.queryByRole("alert")).toBeNull();
+    expect(input).toHaveAttribute("aria-invalid", "false");
+    expect(input).not.toHaveAttribute("aria-describedby");
+  });
+
+  // Mirrors field.test.tsx's round-4 fix: `Children.toArray` drops
+  // null/undefined/booleans but KEEPS "" (and 0), so ["", ""] survives
+  // toArray with length 2 and must still be treated as no content.
+  it("renders no error element for an array of only empty strings", () => {
+    render(
+      <FieldRow label="Email" error={["", ""]}>
+        <Input />
+      </FieldRow>,
+    );
+    const input = screen.getByRole("textbox");
+    expect(screen.queryByRole("alert")).toBeNull();
+    expect(input).toHaveAttribute("aria-invalid", "false");
+    expect(input).not.toHaveAttribute("aria-describedby");
+  });
+
+  it("renders no description element and no aria-describedby reference for an empty array or an array of only falsy children", () => {
+    const { container, rerender } = render(
+      <FieldRow label="Bio" description={[]}>
+        <Input />
+      </FieldRow>,
+    );
+    let input = screen.getByRole("textbox");
+    expect(container.querySelector('[data-slot="field-row-description"]')).toBeNull();
+    expect(input).not.toHaveAttribute("aria-describedby");
+
+    rerender(
+      <FieldRow label="Bio" description={[false, null]}>
+        <Input />
+      </FieldRow>,
+    );
+    input = screen.getByRole("textbox");
+    expect(container.querySelector('[data-slot="field-row-description"]')).toBeNull();
+    expect(input).not.toHaveAttribute("aria-describedby");
+  });
+
+  it("renders no description element for an array of only empty strings", () => {
+    const { container } = render(
+      <FieldRow label="Bio" description={["", ""]}>
+        <Input />
+      </FieldRow>,
+    );
+    const input = screen.getByRole("textbox");
+    expect(container.querySelector('[data-slot="field-row-description"]')).toBeNull();
+    expect(input).not.toHaveAttribute("aria-describedby");
+  });
+
+  // Positive control — the fix above must not suppress a real error: a
+  // non-empty `error` still renders the alert, the aria-describedby
+  // reference and aria-invalid="true".
+  it("still renders the alert, the aria-describedby reference and aria-invalid=true for a non-empty error", () => {
+    render(
+      <FieldRow label="Email" error="Required.">
+        <Input />
+      </FieldRow>,
+    );
+    const input = screen.getByRole("textbox");
+    const alert = screen.getByRole("alert");
+    expect(alert).toHaveTextContent("Required.");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+    expect(input.getAttribute("aria-describedby")).toBe(alert.id);
+  });
+
+  // #93 (A) — KNOWN LIMIT, not desired behavior — mirrors field.test.tsx's
+  // FieldError pin: a value that is itself a component returning `null` is
+  // not knowable from the element before render (a React ecosystem-wide
+  // limit), so it still produces an empty `role="alert"` referenced by
+  // aria-describedby. This test PINS the current, documented-limit behavior
+  // so a future change to it is a deliberate decision, not a silent
+  // regression — it is not an endorsement. See the "Known limit" note on
+  // `FieldRowProps.error`.
+  it("[KNOWN LIMIT] still renders an empty, referenced alert when error is a component that renders null", () => {
+    function RendersNull() {
+      return null;
+    }
+    render(
+      <FieldRow label="Email" error={<RendersNull />}>
+        <Input />
+      </FieldRow>,
+    );
+    const input = screen.getByRole("textbox");
+    const alert = screen.getByRole("alert");
+    expect(alert).toBeEmptyDOMElement();
+    expect(input.getAttribute("aria-describedby")).toBe(alert.id);
+  });
 });