UN-4287 [FEAT] Add the v1 text inputs on one field frame

frontend/src/v1/README.md

@@ -114,6 +114,24 @@ is convention.
 - `CodeEditor` uses Monaco from its default CDN, as v0 does. Never call
   `loader.config()` in v1: the loader is shared with v0.
 
+## Text inputs
+
+- Text controls come from `components/ui/form/` (`Input`, `Textarea`,
+  `PromptTextarea`, `SearchField`, `SecretField`) inside a `Field`, which
+  ties the label, helper and error text to the control. A control the Field
+  cannot name with `<label for>` (a radiogroup) takes `labelId` from
+  `useFieldControl` as `aria-labelledby`. A trigger that is itself the frame
+  (a select) uses `fieldFrameVariants({ focus: "self" })`.
+- A Field holds one form control. Every control under it that reads the
+  Field's context takes the same id and description, and a control that does
+  not read it (a native `<select>`) is left unlabelled. Give a min/max pair a
+  Field each.
+- A control's own `invalid`, `disabled` and `readOnly` win over its Field's.
+- An overlay (Dialog, Popover, Menu) that can hold a `SearchField` must call
+  `event.preventDefault()` in `onEscapeKeyDown` when
+  `isEscapeClearTarget(event)` is true, so Escape clears the search before it
+  closes the overlay.
+
 ## Version switch and route registry
 
 v0's router (`routes/Router.jsx`) wraps its routes in `VersionSwitch`, which

frontend/src/v1/components/ui/form/ErrorText.tsx

@@ -0,0 +1,19 @@
+import { cn } from "@v1/lib/cn";
+import type { ComponentProps, JSX } from "react";
+
+export type ErrorTextProps = ComponentProps<"p">;
+
+/** A validation message. role="alert" makes screen readers announce it when it is rendered, so render it only while there is an error. */
+export function ErrorText({
+  className,
+  ...props
+}: ErrorTextProps): JSX.Element {
+  return (
+    <p
+      role="alert"
+      data-slot="error-text"
+      className={cn("ui:text-caption ui:text-destructive", className)}
+      {...props}
+    />
+  );
+}

frontend/src/v1/components/ui/form/Field.test.tsx

@@ -0,0 +1,210 @@
+import { screen } from "@testing-library/react";
+import { renderV1 } from "@v1/test";
+import type { JSX } from "react";
+import { expect, it } from "vitest";
+import { ErrorText } from "./ErrorText";
+import { Field } from "./Field";
+import { fieldFrameVariants } from "./FieldFrame";
+import { useFieldControl } from "./field-context";
+import { Input } from "./Input";
+import { Label } from "./Label";
+import { PromptTextarea } from "./PromptTextarea";
+import { SearchField } from "./SearchField";
+import { SecretField } from "./SecretField";
+import { Textarea } from "./Textarea";
+
+/** Every text control, rendered with the given props. */
+const CONTROLS: [string, (props: ControlProps) => JSX.Element][] = [
+  ["Input", (p) => <Input {...p} />],
+  ["Textarea", (p) => <Textarea {...p} />],
+  ["PromptTextarea", (p) => <PromptTextarea {...p} />],
+  ["SearchField", (p) => <SearchField {...p} />],
+  ["SecretField", (p) => <SecretField {...p} />],
+];
+
+type ControlProps = Readonly<{
+  invalid?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  "aria-label"?: string;
+}>;
+
+const frameOf = (control: HTMLElement) =>
+  control.closest("[data-slot=field-frame]") as HTMLElement;
+
+it.each(CONTROLS)("associates the Field label with a %s", (_, make) => {
+  renderV1(<Field label="Name">{make({})}</Field>);
+  const named = screen.getByLabelText("Name");
+  expect(named.dataset.slot).toBe("control");
+});
+
+it.each(
+  CONTROLS,
+)("wires a %s to the Field's error, helper and states", (_, make) => {
+  renderV1(
+    <Field label="Name" id="name" helperText="Help" error="Bad" disabled>
+      {make({})}
+    </Field>,
+  );
+  const control = screen.getByLabelText("Name") as HTMLInputElement;
+  expect(control.getAttribute("aria-invalid")).toBe("true");
+  expect(control.getAttribute("aria-describedby")).toBe(
+    "name-helper name-error",
+  );
+  expect(control.disabled).toBe(true);
+  expect(frameOf(control).hasAttribute("data-invalid")).toBe(true);
+  expect(frameOf(control).hasAttribute("data-disabled")).toBe(true);
+});
+
+it.each(
+  CONTROLS,
+)("marks a standalone %s from its own state props", (_, make) => {
+  const { rerender } = renderV1(make({ "aria-label": "C" }));
+  const control = () => screen.getByLabelText("C") as HTMLInputElement;
+  expect(control().hasAttribute("aria-invalid")).toBe(false);
+  for (const flag of ["data-invalid", "data-disabled", "data-readonly"]) {
+    expect(frameOf(control()).hasAttribute(flag)).toBe(false);
+  }
+  rerender(make({ "aria-label": "C", invalid: true, readOnly: true }));
+  expect(control().getAttribute("aria-invalid")).toBe("true");
+  expect(control().readOnly).toBe(true);
+  expect(frameOf(control()).hasAttribute("data-invalid")).toBe(true);
+  expect(frameOf(control()).hasAttribute("data-readonly")).toBe(true);
+  rerender(make({ "aria-label": "C", disabled: true }));
+  expect(control().disabled).toBe(true);
+  expect(frameOf(control()).hasAttribute("data-disabled")).toBe(true);
+});
+
+it.each([
+  ["Input", <Input key="i" id="own" />],
+  ["Textarea", <Textarea key="t" id="own" />],
+])("names a %s that has its own id: the Field's id wins", (_, control) => {
+  renderV1(<Field label="Name">{control}</Field>);
+  const named = screen.getByLabelText("Name");
+  expect(named.id).not.toBe("own");
+  expect(document.querySelector("label")?.htmlFor).toBe(named.id);
+});
+
+it("associates a standalone Label through htmlFor", () => {
+  renderV1(
+    <>
+      <Label htmlFor="api-key">API key</Label>
+      <Input id="api-key" />
+    </>,
+  );
+  expect(screen.getByLabelText("API key").id).toBe("api-key");
+});
+
+it("describes the control by its helper text, and adds the error when it appears", () => {
+  const { rerender } = renderV1(
+    <Field label="Name" helperText="As shown on invoices">
+      <Input />
+    </Field>,
+  );
+  const input = screen.getByLabelText("Name");
+  const helper = screen.getByText("As shown on invoices");
+  expect(input.getAttribute("aria-describedby")).toBe(helper.id);
+  expect(input.hasAttribute("aria-invalid")).toBe(false);
+  expect(screen.queryByRole("alert")).toBeNull();
+
+  rerender(
+    <Field label="Name" helperText="As shown on invoices" error="Required">
+      <Input />
+    </Field>,
+  );
+  const alert = screen.getByRole("alert");
+  expect(alert.textContent).toBe("Required");
+  expect(input.getAttribute("aria-invalid")).toBe("true");
+  expect(input.getAttribute("aria-describedby")).toBe(
+    `${helper.id} ${alert.id}`,
+  );
+  expect(
+    input.closest("[data-slot=field-frame]")?.hasAttribute("data-invalid"),
+  ).toBe(true);
+});
+
+it("keeps the control's own description after the field's", () => {
+  renderV1(
+    <Field label="Name" helperText="Help" id="name">
+      <Input aria-describedby="extra" />
+    </Field>,
+  );
+  const input = screen.getByLabelText("Name");
+  expect(input.id).toBe("name");
+  expect(input.getAttribute("aria-describedby")).toMatch(/ extra$/);
+});
+
+it("passes disabled and read-only from the field to the control and frame", () => {
+  renderV1(
+    <>
+      <Field label="Off" disabled>
+        <Input />
+      </Field>
+      <Field label="Fixed" readOnly>
+        <Textarea />
+      </Field>
+    </>,
+  );
+  const off = screen.getByLabelText("Off") as HTMLInputElement;
+  const fixed = screen.getByLabelText("Fixed") as HTMLTextAreaElement;
+  expect(off.disabled).toBe(true);
+  expect(off.parentElement?.hasAttribute("data-disabled")).toBe(true);
+  expect(fixed.readOnly).toBe(true);
+  expect(fixed.parentElement?.hasAttribute("data-readonly")).toBe(true);
+});
+
+it("renders ErrorText as an alert so it is announced", () => {
+  renderV1(<ErrorText>Bad value</ErrorText>);
+  expect(screen.getByRole("alert").textContent).toBe("Bad value");
+});
+
+// FormField (P1-T06) passes `error` into Field, so this precedence is what a form control gets.
+it.each(
+  CONTROLS,
+)("a %s's own invalid, disabled and readOnly win over its Field's", (_, make) => {
+  renderV1(
+    <Field label="Name" error="x" disabled readOnly>
+      {make({ invalid: false, disabled: false, readOnly: false })}
+    </Field>,
+  );
+  const control = screen.getByLabelText("Name") as HTMLInputElement;
+  expect(control).not.toHaveAttribute("aria-invalid");
+  expect(control).toBeEnabled();
+  expect(control.readOnly).toBe(false);
+  expect(frameOf(control)).not.toHaveAttribute("data-invalid");
+});
+
+it("invalid={false} on a Field keeps its error text but not the invalid mark", () => {
+  renderV1(
+    <Field label="Name" error="Taken" invalid={false}>
+      <Input />
+    </Field>,
+  );
+  const control = screen.getByLabelText("Name");
+  expect(control).not.toHaveAttribute("aria-invalid");
+  expect(screen.getByText("Taken")).toBeInTheDocument();
+});
+
+it("gives the label an id that useFieldControl hands to a group control", () => {
+  function Group() {
+    const { labelId } = useFieldControl({});
+    return <div role="radiogroup" aria-labelledby={labelId} />;
+  }
+  renderV1(
+    <Field id="plan" label="Plan">
+      <Group />
+    </Field>,
+  );
+  expect(screen.getByRole("radiogroup", { name: "Plan" })).toBeInTheDocument();
+  expect(screen.getByText("Plan")).toHaveAttribute("id", "plan-label");
+});
+
+it("fieldFrameVariants: focus within rings on the control, focus self on the frame", () => {
+  expect(fieldFrameVariants()).toContain(
+    "ui:has-[[data-slot=control]:focus-visible]:focus-ring",
+  );
+  const self = fieldFrameVariants({ focus: "self" });
+  expect(self).toContain("ui:focus-visible:focus-ring");
+  expect(self).not.toContain("has-[[data-slot=control]");
+  expect(self).toContain("ui:data-readonly:bg-muted");
+});

frontend/src/v1/components/ui/form/Field.tsx

@@ -0,0 +1,77 @@
+import { cn } from "@v1/lib/cn";
+import { type JSX, type ReactNode, useId, useMemo } from "react";
+import { ErrorText } from "./ErrorText";
+import { FieldContext, type FieldContextValue } from "./field-context";
+import { HelperText } from "./HelperText";
+import { Label } from "./Label";
+
+export type FieldProps = Readonly<{
+  label: ReactNode;
+  helperText?: ReactNode;
+  /** Shown as ErrorText and marks the control invalid unless `invalid` says otherwise. */
+  error?: ReactNode;
+  invalid?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /** The control's id, which replaces any id on the control itself; generated when omitted. */
+  id?: string;
+  className?: string;
+  /**
+   * One form control. The Field gives its id, description and state to every
+   * control that reads its context, so two controls would share one id, and a
+   * control that does not read it (a native `<select>`) is not labelled.
+   */
+  children: ReactNode;
+}>;
+
+/** Label, control, helper and error text, wired together: the label names the control and the control is described by the texts. */
+export function Field({
+  label,
+  helperText,
+  error,
+  invalid,
+  disabled = false,
+  readOnly = false,
+  id,
+  className,
+  children,
+}: FieldProps): JSX.Element {
+  const generatedId = useId();
+  const controlId = id ?? `${generatedId}control`;
+  // Derived from the control id, so a caller that passes `id` gets stable ids.
+  const labelId = `${controlId}-label`;
+  const helperId = helperText ? `${controlId}-helper` : undefined;
+  const errorId = error ? `${controlId}-error` : undefined;
+  const isInvalid = invalid ?? Boolean(error);
+
+  const context = useMemo<FieldContextValue>(
+    () => ({
+      controlId,
+      labelId,
+      describedBy: [helperId, errorId].filter(Boolean).join(" ") || undefined,
+      invalid: isInvalid,
+      disabled,
+      readOnly,
+    }),
+    [controlId, labelId, helperId, errorId, isInvalid, disabled, readOnly],
+  );
+
+  return (
+    <FieldContext value={context}>
+      <div data-slot="field" className={cn("ui:grid ui:gap-1.5", className)}>
+        <Label
+          id={labelId}
+          htmlFor={controlId}
+          data-disabled={disabled ? "" : undefined}
+        >
+          {label}
+        </Label>
+        {children}
+        {helperText ? (
+          <HelperText id={helperId}>{helperText}</HelperText>
+        ) : null}
+        {error ? <ErrorText id={errorId}>{error}</ErrorText> : null}
+      </div>
+    </FieldContext>
+  );
+}

frontend/src/v1/components/ui/form/FieldAction.test.tsx

@@ -0,0 +1,21 @@
+import { screen } from "@testing-library/react";
+import { renderV1 } from "@v1/test";
+import { expect, it, vi } from "vitest";
+import { FieldAction } from "./FieldAction";
+
+it("is a named button that does not submit its form", async () => {
+  const onSubmit = vi.fn((event: { preventDefault: () => void }) =>
+    event.preventDefault(),
+  );
+  const onClick = vi.fn();
+  const { user } = renderV1(
+    <form onSubmit={onSubmit}>
+      <FieldAction label="Copy" onClick={onClick} />
+    </form>,
+  );
+  const button = screen.getByRole("button", { name: "Copy" });
+  expect(button.getAttribute("title")).toBe("Copy");
+  await user.click(button);
+  expect(onClick).toHaveBeenCalledOnce();
+  expect(onSubmit).not.toHaveBeenCalled();
+});

frontend/src/v1/components/ui/form/FieldAction.tsx

@@ -0,0 +1,30 @@
+import { cn } from "@v1/lib/cn";
+import type { ComponentProps, JSX } from "react";
+
+export type FieldActionProps = Omit<ComponentProps<"button">, "aria-label"> &
+  Readonly<{
+    /** The accessible name; also shown as the tooltip, since the button shows only an icon. */
+    label: string;
+  }>;
+
+/** An icon button inside a field frame, such as Reveal, Copy or Clear. */
+export function FieldAction({
+  label,
+  className,
+  type = "button",
+  ...props
+}: FieldActionProps): JSX.Element {
+  return (
+    <button
+      type={type}
+      aria-label={label}
+      title={label}
+      data-slot="field-action"
+      className={cn(
+        "ui:inline-flex ui:size-6 ui:shrink-0 ui:cursor-pointer ui:items-center ui:justify-center ui:rounded-sm ui:border-0 ui:bg-transparent ui:p-0 ui:text-muted-foreground ui:hover:bg-accent ui:hover:text-foreground ui:focus-visible:focus-ring ui:aria-pressed:text-foreground ui:disabled:pointer-events-none ui:disabled:opacity-50 ui:[&>svg]:size-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}