@terpjs/react-core 0.8.0 → 0.10.0

package/src/ui/Button.test.tsx

@@ -38,10 +38,78 @@ describe("Button", () => {
     expect(button.textContent).toBe("iDo it");
   });
 
+  it("names a non-default size and leaves the standard control unmarked", () => {
+    // md is the absence of an attribute, because the standard control's geometry IS the base
+    // rule — the shape density already uses, where "comfortable" matches no rule either. So
+    // this asserts the absence as deliberately as it asserts the presence: stamping
+    // data-size="md" would be harmless but would make the sheet's two-rule split read as an
+    // omission.
+    const { rerender } = render(<Button size="sm">Small</Button>);
+    expect(screen.getByRole("button", { name: "Small" })).toHaveAttribute("data-size", "sm");
+    rerender(<Button size="lg">Large</Button>);
+    expect(screen.getByRole("button", { name: "Large" })).toHaveAttribute("data-size", "lg");
+    rerender(<Button>Standard</Button>);
+    const standard = screen.getByRole("button", { name: "Standard" });
+    expect(standard.hasAttribute("data-size")).toBe(false);
+    expect(standard.getAttribute("style")).toBeNull();
+  });
+
+  it("fills its container from an attribute rather than an inline width", () => {
+    // The point of the prop: `style={{ width: "100%" }}` is the only other way there, and app
+    // modules may not write it (ADR 0059) — so full width was a shape the framework could
+    // produce and its consumers could not ask for. The absence of a style attribute is the
+    // half that matters, because an inline width would outrank the app theme.css that ADR 0094
+    // exists to empower.
+    render(<Button fullWidth>Wide</Button>);
+    const button = screen.getByRole("button", { name: "Wide" });
+    expect(button).toHaveAttribute("data-full-width", "true");
+    expect(button.getAttribute("style")).toBeNull();
+  });
+
+  it("marks a loading button busy, disables it, and shows the spinner in the icon slot", () => {
+    render(
+      <Button loading icon={<span data-testid="ico">i</span>}>
+        Saving
+      </Button>,
+    );
+    const button = screen.getByRole("button", { name: "Saving" });
+    expect(button).toHaveAttribute("data-loading", "true");
+    expect(button).toHaveAttribute("aria-busy", "true");
+    // Disabled, so a second click cannot start the same request twice — the reason the state
+    // exists at all rather than being decoration on a still-live control.
+    expect(button).toBeDisabled();
+    // The spinner REPLACES the icon rather than joining it, so the button's width does not
+    // jump as it enters and leaves the state.
+    expect(screen.queryByTestId("ico")).toBeNull();
+    expect(button.querySelector('[data-terp="spinner-ring"]')).not.toBeNull();
+    expect(button.getAttribute("style")).toBeNull();
+  });
+
+  it("keeps a loading button disabled even when the caller says otherwise", () => {
+    // `disabled={false}` and `loading` together is a real combination — a form that computes
+    // one from validity and the other from the request in flight — and the request has to
+    // win, or the state is advisory.
+    render(
+      <Button loading disabled={false}>
+        Saving
+      </Button>,
+    );
+    expect(screen.getByRole("button", { name: "Saving" })).toBeDisabled();
+  });
+
   it("still forwards an explicit style, so framework callers keep their escape", () => {
-    // The sheet owns the base; a one-off geometry override (LoginView's full-width submit)
-    // is inline and therefore still wins, which is the boundary ADR 0094 draws between
-    // styling policy and a measured value.
+    // The sheet owns the base, and the escape still has to work: a caller may pass a measured
+    // value the sheet has no business owning, and it wins because a style attribute outranks
+    // any author rule (ADR 0094 §3).
+    //
+    // This comment has now cited three different homes for the same 100%, which is the useful
+    // part of it. First it was LoginView's inline style. Then a rule on the login form's group,
+    // because a fixed 100% is layout policy rather than a measured value and the sheet could
+    // reach it — with a prop declined as API the package did not need for one internal caller.
+    // Now it is `fullWidth`, because the constraint that mattered was never the internal caller:
+    // app modules may not write `style` at all, so full width was a shape the framework could
+    // produce and its consumers could not ask for. The group rule is gone and LoginView passes
+    // the prop. The escape below is unaffected either way, which is why it is still here.
     render(<Button style={{ width: "100%" }}>Wide</Button>);
     expect(screen.getByRole("button", { name: "Wide" }).style.width).toBe("100%");
   });

package/src/ui/Button.tsx

@@ -1,13 +1,39 @@
 import type { ButtonHTMLAttributes, ReactNode } from "react";
 
+import { InlineSpinner } from "../LoadingState";
 import { injectTerpStyles } from "../styles";
 
 injectTerpStyles();
 
 export type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
 
+/** Control size: `"md"` is the standard control and needs no attribute (see below). */
+export type ButtonSize = "sm" | "md" | "lg";
+
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: ButtonVariant;
+  /**
+   * Control size (default `"md"`). Changes the height, the horizontal padding and the label
+   * size together; composes with `data-density`, so a `"sm"` button inside a compact subtree
+   * is shorter still.
+   */
+  size?: ButtonSize;
+  /**
+   * The action is in flight: shows a spinner in the icon slot, marks the control
+   * `aria-busy` and disables it, so a second click cannot start the request twice.
+   *
+   * The spinner replaces `icon` rather than joining it, which keeps the button's width from
+   * jumping as it enters and leaves the state.
+   */
+  loading?: boolean;
+  /**
+   * Fill the container's inline size instead of the label's.
+   *
+   * It exists because the alternative was `style={{ width: "100%" }}`, which app modules may
+   * not write (ADR 0059) — so full width was a shape the framework could produce and its
+   * consumers could not ask for.
+   */
+  fullWidth?: boolean;
   /** Optional leading icon, rendered before `children` (e.g. `<Icon name="plus" />`). */
   icon?: ReactNode;
 }
@@ -20,23 +46,50 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  * matched on the `data-terp` / `data-variant` attributes set below (ADR 0094). So the
  * variant is a fact about the element rather than a style object chosen in here — which
  * is what a test should assert, and what an app's `theme.css` can restyle.
+ *
+ * `size`, `loading` and `fullWidth` are all closed sets, so all three are attributes with a
+ * rule each (ADR 0094 §3). Two details about how they are stamped are deliberate:
+ *
+ * `data-size` appears only for `"sm"` and `"lg"`. The standard control's geometry IS the base
+ * rule, so `md` is the absence of an attribute — the same shape density takes, where
+ * "comfortable" is the token sheet's `:root` value and the attribute for it matches no rule.
+ * (`data-variant` is stamped even for its default because `primary` has a rule of its own;
+ * the two idioms differ for that reason rather than by accident.)
+ *
+ * `loading` sets `disabled` as well, and the sizes are expressed as a `calc()` off the
+ * density token rather than as heights of their own, so density keeps composing with all
+ * three sizes without a second family of tokens to keep in step.
  */
 export function Button({
   variant = "primary",
+  size = "md",
+  loading = false,
+  fullWidth = false,
   icon,
   type = "button",
+  disabled,
   children,
   ...rest
 }: ButtonProps) {
+  const leading = loading ? <InlineSpinner size={14} /> : icon;
   return (
-    <button type={type} data-terp="button" data-variant={variant} {...rest}>
-      {icon !== undefined && (
+    <button
+      type={type}
+      data-terp="button"
+      data-variant={variant}
+      data-size={size === "md" ? undefined : size}
+      data-loading={loading ? "true" : undefined}
+      data-full-width={fullWidth ? "true" : undefined}
+      disabled={disabled === true || loading}
+      aria-busy={loading ? true : undefined}
+      {...rest}
+    >
+      {leading !== undefined && leading !== null && (
         <span aria-hidden="true" data-terp="button-icon">
-          {icon}
+          {leading}
         </span>
       )}
       {children}
     </button>
   );
 }
-

package/src/ui/Card.test.tsx

@@ -41,4 +41,17 @@ describe("Card", () => {
     const card = screen.getByText("alleen inhoud").closest('[data-terp="card"]');
     expect(card?.querySelector('[data-terp="card-header"]')).toBeNull();
   });
+  it("names the plain variant and leaves the boxed default unmarked", () => {
+    // The chrome-less titled region. A variant rather than a `Section` component of its own,
+    // because a chrome-less region is this element with three declarations removed — a second
+    // component would have meant six more markers describing the same DOM, and a `Surface` is
+    // a Card with no title, which this already is.
+    const { rerender } = render(<Card variant="plain" title="Plain">body</Card>);
+    const plain = screen.getByRole("heading", { name: "Plain" }).closest("section");
+    expect(plain).toHaveAttribute("data-variant", "plain");
+    rerender(<Card title="Boxed">body</Card>);
+    const boxed = screen.getByRole("heading", { name: "Boxed" }).closest("section");
+    expect(boxed!.hasAttribute("data-variant")).toBe(false);
+    expect(boxed!.getAttribute("style")).toBeNull();
+  });
 });

package/src/ui/Card.tsx

@@ -7,8 +7,27 @@ import type { UiText } from "../uiText";
 
 injectTerpStyles();
 
+/** Chrome, or none: `"plain"` keeps the heading and drops the box. */
+export type CardVariant = "boxed" | "plain";
+
 export interface CardProps
   extends Omit<HTMLAttributes<HTMLElement>, "style" | "title"> {
+  /**
+   * Whether the block carries a box (default `"boxed"`) or just its heading (`"plain"`).
+   *
+   * `"plain"` is the labelled-region case: a titled group inside something that is already a
+   * surface, where a second border reads as a frame around a frame. The commonest instance is
+   * a section whose body is a `DataView` — boxed, the table gets a border inside a border and
+   * loses its full width.
+   *
+   * It is a variant rather than a `Section` component of its own, and that is a decision worth
+   * knowing. A chrome-less titled region is exactly this element with three declarations
+   * removed: `Card` already renders a `<section>` with an `<h3>` and stacks its children on
+   * the token scale. A second component would have meant six more markers describing the same
+   * DOM, and a `Surface` — the third name the diagnosis suggested — is a `Card` with no title,
+   * which this already is. Two names for one box is the `LoadingButton` mistake.
+   */
+  variant?: CardVariant;
   /** Optional section heading, rendered as an `<h3>` in the card's header row. */
   title?: UiText;
   /** Optional muted one-liner under the title (what this block is about). */
@@ -31,6 +50,7 @@ export interface CardProps
  * spacing scale.
  */
 export function Card({
+  variant = "boxed",
   title,
   description,
   actions,
@@ -42,7 +62,14 @@ export function Card({
   const resolve = useUiText();
   const hasHeader = title !== undefined || actions !== undefined;
   return (
-    <Component {...rest} data-terp="card" data-gap={String(gap)}>
+    <Component
+      {...rest}
+      data-terp="card"
+      // `boxed` is the base rule, so its attribute would describe the default twice — the
+      // idiom density, Button's `md` and Grid's `auto` all use.
+      data-variant={variant === "boxed" ? undefined : variant}
+      data-gap={String(gap)}
+    >
       {hasHeader ? (
         <div data-terp="card-header">
           <div data-terp="card-heading">

package/src/ui/Checkbox.tsx

@@ -1,4 +1,4 @@
-import type { InputHTMLAttributes } from "react";
+import type { ChangeEvent, InputHTMLAttributes } from "react";
 
 import { injectTerpStyles } from "../styles";
 import { useUiText } from "../uiText";
@@ -25,7 +25,15 @@ export function Checkbox({ label, checked, defaultChecked, onChange, style, ...r
         data-terp="checkbox"
         checked={checked}
         defaultChecked={defaultChecked}
-        onChange={(event) => onChange?.(event.currentTarget.checked)}
+        // Attached only when there is something to call, exactly as Select does and for the
+        // reason stated there: an unconditional handler silences React's own "you provided a
+        // `checked` prop to a form field without an `onChange` handler" guard, so a caller who
+        // pinned `checked` and forgot the handler gets a control that looks operable, never
+        // changes, and says nothing about it. The spread form is what keeps the prop absent
+        // rather than present-and-undefined, which React treats as the same mistake.
+        {...(onChange !== undefined
+          ? { onChange: (event: ChangeEvent<HTMLInputElement>) => onChange(event.currentTarget.checked) }
+          : {})}
       />
       <span>{resolve(label)}</span>
     </label>

package/src/ui/Combobox.test.tsx

@@ -31,6 +31,55 @@ describe("Combobox", () => {
     expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
   });
 
+  it("matches a needle that the host's own case fold would have hidden", () => {
+    // The filter used to fold with `toLocaleLowerCase`, which asks the host what lowercase means.
+    // Turkish has two i's, and folded there `Italy` becomes `ıtaly` — dotless — which does not
+    // contain the `i` the user typed. Every option with a capital I disappeared for a Turkish
+    // visitor and for nobody else, and folding BOTH sides the same way does not help: the needle
+    // comes from a keyboard and the haystack from a server.
+    //
+    // The host is simulated rather than assumed, because the suite runs on nl-NL and a test that
+    // merely typed `i` would pass under the bug here and fail only in Istanbul. The prototype
+    // patch is scoped to this test and restored in `finally`.
+    const original = String.prototype.toLocaleLowerCase;
+    // Confirm the hazard is real on this ICU build before relying on it as the mechanism.
+    expect(original.call("Italy", "tr")).not.toContain("i");
+    String.prototype.toLocaleLowerCase = function turkish(this: string) {
+      return original.call(this, "tr");
+    };
+    try {
+      render(
+        <Combobox
+          aria-label="Country"
+          options={[...options, { value: "it", label: "Italy" }]}
+          onChange={vi.fn()}
+        />,
+      );
+      const input = screen.getByRole("combobox", { name: /Country/ });
+      fireEvent.focus(input);
+      // BOTH cases, because each catches a different half and neither catches the other.
+      //
+      // Lowercase is the real defect: the user types the dotted `i` their keyboard produces,
+      // Turkish folds the label to the dotless `ıtaly`, and the option vanishes. The ORIGINAL
+      // code folded both sides with the host locale, which is self-consistent — "ıtal" does
+      // occur in "ıtaly" — so a capital-I needle passes under the very bug this test exists
+      // for. The first version of this test asserted only the capital, and was green against
+      // it.
+      //
+      // Capital is still needed: it is the only case that fails when the NEEDLE alone reverts
+      // to the host fold, which lowercase cannot see because folding "ital" changes nothing.
+      for (const needle of ["ital", "Ital"]) {
+        fireEvent.change(input, { target: { value: needle } });
+        expect(
+          screen.getByRole("option", { name: "Italy" }),
+          `typing ${needle} must still match Italy on a Turkish host`,
+        ).toBeInTheDocument();
+      }
+    } finally {
+      String.prototype.toLocaleLowerCase = original;
+    }
+  });
+
   it("supports controlled value, Field labels, ARIA active option and keyboard navigation", () => {
     const onChange = vi.fn();
     render(

package/src/ui/Combobox.tsx

@@ -72,11 +72,17 @@ export function Combobox({
   const isOpen = open && disabled !== true;
 
   const renderedOptions = useMemo(() => {
-    const normalized = query.trim().toLocaleLowerCase();
+    // `toLowerCase`, not the locale-aware fold: this decides whether a substring MATCHES, and a
+    // match is not a presentation question for the host to answer. Folded against a Turkish host,
+    // `Item` becomes `ıtem` — dotless — which does not contain the `i` the user typed, so every
+    // option with a capital I disappears for a Turkish visitor and for nobody else.
+    // Folding both sides with the same host locale does not rescue it: the needle comes from a
+    // keyboard and the haystack from a server, and the two agree only when the fold is invariant.
+    const normalized = query.trim().toLowerCase();
     if (normalized.length === 0 || selectedOption !== null && query === resolve(selectedOption.label)) {
       return options;
     }
-    return options.filter((option) => resolve(option.label).toLocaleLowerCase().includes(normalized));
+    return options.filter((option) => resolve(option.label).toLowerCase().includes(normalized));
   }, [options, query, resolve, selectedOption]);
   const enabledOptions = renderedOptions.filter((option) => !option.disabled);
   const activeOption = renderedOptions.find((option) => option.value === activeValue) ?? enabledOptions[0] ?? null;

package/src/ui/DatePicker.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useId, useMemo, useRef, useState } from "react";
 import type { KeyboardEvent } from "react";
 
+import { formatDate } from "../format";
 import { useLocale } from "../locale";
 import { injectTerpStyles } from "../styles";
 import { useUiText } from "../uiText";
@@ -414,13 +415,34 @@ function useDateLocale() {
   return useLocale()?.locale;
 }
 
-function formatDate(date: Date, locale: string | undefined) {
-  return new Intl.DateTimeFormat(locale, { year: "numeric", month: "short", day: "numeric" }).format(date);
+// `formatDate` used to live here, three functions deep in a file about calendars, and it was the
+// only general-purpose locale-correct date rendering in the package. It is `../format` now and
+// imported back; the three below stay, because a spoken day, a grid caption and a column header
+// are calendar parts rather than general formatting.
+//
+// They are cached for the reason `../format` caches its own: constructing an Intl formatter costs
+// far more than using one — measured at roughly 55x on this repository's Node — and the spoken-day
+// formatter runs once per DAY CELL, so an open calendar built 42 of them per render and a further
+// seven for the column headers.
+const CALENDAR_FORMATTERS = new Map<string, Intl.DateTimeFormat>();
+
+function calendarFormatter(
+  locale: string | undefined,
+  kind: "full" | "month" | "weekday",
+  options: Intl.DateTimeFormatOptions,
+): Intl.DateTimeFormat {
+  const key = `${kind}|${locale ?? ""}`;
+  let formatter = CALENDAR_FORMATTERS.get(key);
+  if (formatter === undefined) {
+    formatter = new Intl.DateTimeFormat(locale, options);
+    CALENDAR_FORMATTERS.set(key, formatter);
+  }
+  return formatter;
 }
 
 /** The whole date, spoken: what a day cell announces, since its text is only a number. */
 function formatFullDate(date: Date, locale: string | undefined) {
-  return new Intl.DateTimeFormat(locale, {
+  return calendarFormatter(locale, "full", {
     weekday: "long",
     day: "numeric",
     month: "long",
@@ -429,12 +451,13 @@ function formatFullDate(date: Date, locale: string | undefined) {
 }
 
 function formatMonth(date: Date, locale: string | undefined) {
-  return new Intl.DateTimeFormat(locale, { year: "numeric", month: "long" }).format(date);
+  return calendarFormatter(locale, "month", { year: "numeric", month: "long" }).format(date);
 }
 
 function weekdayNames(locale: string | undefined) {
   const base = new Date(2024, 0, 7);
-  return Array.from({ length: 7 }, (_, index) => new Intl.DateTimeFormat(locale, { weekday: "short" }).format(addDays(base, index)));
+  const formatter = calendarFormatter(locale, "weekday", { weekday: "short" });
+  return Array.from({ length: 7 }, (_, index) => formatter.format(addDays(base, index)));
 }
 
 function normalizeRange(value: DateRangeValue): DateRangeValue {

package/src/ui/Input.test.tsx

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Field } from "../Field";
+import { Input } from "./Input";
+
+afterEach(cleanup);
+
+describe("Input", () => {
+  it("renders a bare input for every type but password", () => {
+    // The wrapper exists for exactly one type. Two child selectors in the sheet reach for
+    // `data-terp="input"` as a DIRECT child — the toolbar search and the resource-list create
+    // field — and both would break against a wrapper, so "only password wraps" is a fact those
+    // rules depend on rather than an implementation detail.
+    const { container, rerender } = render(<Input type="text" defaultValue="" />);
+    expect(container.firstElementChild?.tagName).toBe("INPUT");
+    rerender(<Input type="search" defaultValue="" />);
+    expect(container.firstElementChild?.tagName).toBe("INPUT");
+    rerender(<Input defaultValue="" />);
+    expect(container.firstElementChild?.tagName).toBe("INPUT");
+    rerender(<Input type="password" defaultValue="" />);
+    expect(container.firstElementChild?.getAttribute("data-terp")).toBe("input-password");
+  });
+
+  it("reveals and re-hides the value, and its NAME is what says which it will do", () => {
+    // One encoding of the state, not two. The name swaps, and there is deliberately no
+    // `aria-pressed`: a toggle announced as "Hide password, pressed" claims the value is hidden
+    // and shown at once. It also keeps this button outside the sheet's shared hover guard, which
+    // excludes `[aria-pressed="true"]` and would leave the revealed toggle with no hover at all.
+    render(<Input type="password" aria-label="Password" defaultValue="hunter2" />);
+    const input = screen.getByLabelText("Password");
+    expect(input).toHaveAttribute("type", "password");
+    const toggle = screen.getByRole("button", { name: "Show password" });
+    expect(toggle).not.toHaveAttribute("aria-pressed");
+    fireEvent.click(toggle);
+    expect(input).toHaveAttribute("type", "text");
+    const now = screen.getByRole("button", { name: "Hide password" });
+    expect(now).not.toHaveAttribute("aria-pressed");
+    fireEvent.click(now);
+    expect(input).toHaveAttribute("type", "password");
+  });
+
+  it("does not submit the form it sits in", () => {
+    // A button inside a form defaults to type="submit". A reveal toggle that posted the form
+    // would be a data-loss bug reachable by one click, and no visual lane could see it.
+    render(<Input type="password" aria-label="Password" defaultValue="" />);
+    expect(screen.getByRole("button", { name: "Show password" })).toHaveAttribute("type", "button");
+  });
+
+  it("keeps Field's aria on the input, not on the wrapper", () => {
+    // The one that would have shipped silently. `Field` clones its control to inject
+    // `aria-describedby` and `aria-invalid`, and the sheet's invalid border is
+    // `input[data-terp="input"][aria-invalid="true"]` — a single-element selector. If the spread
+    // landed on the wrapper span, the attribute would sit on one element and the marker on
+    // another, the selector would match neither, and every password field with a hint or an error
+    // would quietly lose its red border. There is one such field in the example app today.
+    render(
+      <Field label="Password" hint="At least 16 characters" error="Too short">
+        <Input type="password" defaultValue="" />
+      </Field>,
+    );
+    const input = screen.getByLabelText("Password");
+    expect(input.tagName).toBe("INPUT");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+    expect(input).toHaveAttribute("data-terp", "input");
+    const described = (input.getAttribute("aria-describedby") ?? "").split(" ").filter(Boolean);
+    expect(described).toHaveLength(2);
+    // And the wrapper carries none of it.
+    const wrapper = input.parentElement!;
+    expect(wrapper).toHaveAttribute("data-terp", "input-password");
+    expect(wrapper).not.toHaveAttribute("aria-invalid");
+    expect(wrapper).not.toHaveAttribute("aria-describedby");
+  });
+
+  it("is named by the label TEXT, so the toggle's own name cannot join it", () => {
+    // `Field` wraps the control in a `<label>`, so the toggle is a label descendant, and a label
+    // takes its name from everything inside it. Chromium duly computed "Password Show password"
+    // for this input until `Field` started pointing `aria-labelledby` at the label's text span.
+    //
+    // WHAT THIS TEST CAN AND CANNOT SEE, because the first version of it was worthless: jsdom's
+    // accessible-name implementation does NOT walk into a descendant's `aria-label`, so
+    // `toHaveAccessibleName("Password")` passed here while the real browser disagreed. It asserted
+    // the deviation, not the fix. So the wiring is what is pinned here — the attribute exists and
+    // resolves to the label text — and the computed NAME is asserted in a real engine, in
+    // apps/workbench/visual/computed.spec.ts against the admin-user-create specimen.
+    render(
+      <Field label="Password">
+        <Input type="password" defaultValue="" />
+      </Field>,
+    );
+    const input = screen.getByLabelText("Password");
+    expect(input.tagName).toBe("INPUT");
+    const labelledBy = input.getAttribute("aria-labelledby");
+    expect(labelledBy).not.toBeNull();
+    expect(document.getElementById(labelledBy!)?.textContent).toBe("Password");
+    // The toggle keeps its own name; asserting it were unlabelled would be the wrong fix.
+    expect(screen.getByRole("button", { name: "Show password" })).toBeInTheDocument();
+  });
+
+  it("disables its toggle when the field itself is disabled or read-only", () => {
+    // A field the caller switched off is switched off as a whole. Otherwise the value stays
+    // unreachable while the control beside it still reveals it.
+    const { rerender } = render(<Input type="password" aria-label="Password" disabled />);
+    expect(screen.getByRole("button", { name: "Show password" })).toBeDisabled();
+    rerender(<Input type="password" aria-label="Password" readOnly />);
+    expect(screen.getByRole("button", { name: "Show password" })).toBeDisabled();
+    rerender(<Input type="password" aria-label="Password" />);
+    expect(screen.getByRole("button", { name: "Show password" })).toBeEnabled();
+  });
+
+  it("keeps a revealed password out of spellcheck, autocorrect and autocapitalisation", () => {
+    // Revealing swaps the type to `text`, which in some engines makes the value a candidate for
+    // all three — two of which would rewrite what the user typed.
+    render(<Input type="password" aria-label="Password" defaultValue="" />);
+    const input = screen.getByLabelText("Password");
+    fireEvent.click(screen.getByRole("button", { name: "Show password" }));
+    expect(input).toHaveAttribute("type", "text");
+    expect(input).toHaveAttribute("spellcheck", "false");
+    expect(input).toHaveAttribute("autocorrect", "off");
+    expect(input).toHaveAttribute("autocapitalize", "none");
+  });
+});

package/src/ui/Input.tsx

@@ -1,6 +1,9 @@
+import { useState } from "react";
 import type { InputHTMLAttributes } from "react";
 
+import { Icon } from "../icons";
 import { injectTerpStyles } from "../styles";
+import { useStrings } from "../uiText";
 
 injectTerpStyles();
 
@@ -11,7 +14,67 @@ export type InputProps = InputHTMLAttributes<HTMLInputElement>;
  * The `data-terp="input"` marker is the whole styling hook: it carries the shared control
  * surface, the focus ring, the hover border and the disabled treatment from the injected
  * sheet, with the element type deciding the geometry (ADR 0094).
+ *
+ * `type="password"` additionally grows a reveal toggle, and it is the TYPE that decides rather
+ * than a prop, for the reason the sheet already gives about `input` and `textarea`: "only their
+ * geometry differs, so the element type carries that — no second attribute for a distinction the
+ * tag name already makes." A `PasswordInput` export would be the `LoadingButton` mistake, a second
+ * name for one `<input>`.
+ *
+ * An app cannot build this itself, which is why it belongs here rather than in a recipe. The toggle
+ * needs a positioned wrapper, and `BOUNDARY_SPEC` refuses both `style` and `className` in module
+ * files — exactly the `Button.fullWidth` case: a shape the framework can produce and its consumers
+ * cannot ask for.
  */
-export function Input(props: InputProps) {
-  return <input data-terp="input" {...props} />;
+export function Input({ type, ...rest }: InputProps) {
+  const strings = useStrings();
+  const [revealed, setRevealed] = useState(false);
+
+  if (type !== "password") {
+    return <input data-terp="input" type={type} {...rest} />;
+  }
+
+  // A field the caller has switched off is switched off as a whole. Without this the value stays
+  // hidden and unreachable while the control beside it still reveals it — a disabled field with a
+  // working button in it.
+  const inert = rest.disabled === true || rest.readOnly === true;
+
+  return (
+    <span data-terp="input-password">
+      {/*
+        `rest` spreads onto the INPUT, never onto the wrapper, and that is load-bearing rather than
+        tidy. `Field` clones its control to inject `aria-describedby` and `aria-invalid`, and the
+        sheet's invalid border is `input[data-terp="input"][aria-invalid="true"]` — a single-element
+        selector. Land those on the span and the attribute matches nothing while the marker sits on
+        a different element, so the red border silently disappears for every password field with a
+        hint or an error. There is one live today.
+      */}
+      <input
+        data-terp="input"
+        type={revealed ? "text" : "password"}
+        // Revealing swaps the type to `text`, and a text input is a candidate for spellcheck,
+        // autocorrect and autocapitalisation in engines that apply them — none of which a password
+        // wants, and two of which would silently rewrite what the user typed on a phone. Declared
+        // before the spread so a caller can still override them.
+        spellCheck={false}
+        autoCorrect="off"
+        autoCapitalize="none"
+        {...rest}
+      />
+      <button
+        type="button"
+        data-terp="iconbutton"
+        disabled={inert}
+        // No `aria-pressed`. The name already carries the state — it swaps between "Show password"
+        // and "Hide password" — and encoding it twice makes the two disagree: a toggle announced
+        // as "Hide password, pressed" claims the value is hidden and shown at once. It also keeps
+        // this button out of the shared hover guard, which excludes `[aria-pressed="true"]` and
+        // would otherwise leave the revealed toggle with no hover feedback at all.
+        aria-label={revealed ? strings.hidePassword : strings.showPassword}
+        onClick={() => setRevealed((on) => !on)}
+      >
+        <Icon name={revealed ? "eye-off" : "eye"} />
+      </button>
+    </span>
+  );
 }