@terpjs/react-core 0.9.0 → 0.11.0

package/src/ui/Combobox.tsx

@@ -2,7 +2,7 @@ import { useEffect, useId, useMemo, useRef, useState } from "react";
 import type { InputHTMLAttributes, KeyboardEvent } from "react";
 
 import { injectTerpStyles } from "../styles";
-import { useUiText } from "../uiText";
+import { useStrings, useUiText } from "../uiText";
 import type { UiText } from "../uiText";
 
 injectTerpStyles();
@@ -13,12 +13,9 @@ export interface ComboboxOption {
   disabled?: boolean;
 }
 
-export interface ComboboxProps
+interface ComboboxCommonProps
   extends Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "children" | "role"> {
   options: readonly ComboboxOption[];
-  value?: string | null;
-  defaultValue?: string | null;
-  onChange?: (value: string | null, option: ComboboxOption | null) => void;
   loading?: boolean;
   loadingText?: UiText;
   noOptionsText?: UiText;
@@ -33,15 +30,181 @@ export interface ComboboxProps
   defaultOpen?: boolean;
 }
 
-/** Filterable ARIA combobox/typeahead with controlled or uncontrolled single selection. */
-export function Combobox({
+/** One selection, or none. */
+export interface ComboboxSingleProps extends ComboboxCommonProps {
+  multiple?: false;
+  value?: string | null;
+  defaultValue?: string | null;
+  onChange?: (value: string | null, option: ComboboxOption | null) => void;
+}
+
+/** A SET of selections, rendered as removable tokens. */
+export interface ComboboxMultipleProps extends ComboboxCommonProps {
+  multiple: true;
+  value?: readonly string[];
+  defaultValue?: readonly string[];
+  onChange?: (values: readonly string[], options: readonly ComboboxOption[]) => void;
+  /** Accessible name for a token's remove control; the option's label is appended. */
+  removeLabel?: UiText;
+}
+
+/**
+ * A mode rather than a second component, and the union is the point: `multiple` decides the
+ * shape of `value`, `defaultValue` and `onChange` together, so handing a plain string to a
+ * multiple combobox — or an array to a single one — is a typecheck error rather than a
+ * runtime surprise. Same reasoning as `ICON_NAMES`: a mistake that the compiler can hold is
+ * not worth discovering in a browser.
+ */
+export type ComboboxProps = ComboboxSingleProps | ComboboxMultipleProps;
+
+function isMultiple(props: ComboboxProps): props is ComboboxMultipleProps {
+  return props.multiple === true;
+}
+
+/**
+ * Filterable ARIA combobox/typeahead, single or multiple.
+ *
+ * **Why `multiple` is here rather than in a component of its own.** A set-valued field had no
+ * sanctioned control at all, and the absence did not stop anyone: it produced comma-separated
+ * text boxes with the legal values listed in a grey hint beside them — a closed enum typed as
+ * free text, so the validation the value set could have enforced was simply lost. That is
+ * ADR 0096's principle rather than a preference: a seam that does not cover the common case is
+ * a hole, because the compliant path is unavailable and code goes around it.
+ *
+ * It is a mode because the hard parts already exist here. The listbox, the filtering, the
+ * active-option model, the outside-click close and the whole `aria-activedescendant` wiring
+ * are the same; what differs is that a selection is a set, that choosing one keeps the list
+ * open, and that the selections need somewhere to live. A second component would have had to
+ * re-derive all of the first list and would drift from it.
+ */
+export function Combobox(props: ComboboxProps) {
+  return isMultiple(props) ? <MultiCombobox {...props} /> : <SingleCombobox {...props} />;
+}
+
+function MultiCombobox(props: ComboboxMultipleProps) {
+  const { value, defaultValue, onChange, removeLabel, ...rest } = props;
+  const resolve = useUiText();
+  const strings = useStrings();
+  const [uncontrolled, setUncontrolled] = useState<readonly string[]>(defaultValue ?? []);
+  const selected = value ?? uncontrolled;
+  const byValue = useMemo(
+    () => new Map(props.options.map((option) => [option.value, option])),
+    [props.options],
+  );
+  // Order follows the SELECTION, not the option list: a token row that reorders itself when a
+  // later option is picked moves the target a user was about to click.
+  const selectedOptions = selected.flatMap((v) => {
+    const option = byValue.get(v);
+    return option === undefined ? [] : [option];
+  });
+
+  function commitValues(next: readonly string[]) {
+    if (value === undefined) {
+      setUncontrolled(next);
+    }
+    onChange?.(
+      next,
+      next.flatMap((v) => {
+        const option = byValue.get(v);
+        return option === undefined ? [] : [option];
+      }),
+    );
+  }
+
+  function toggle(option: ComboboxOption) {
+    commitValues(
+      selected.includes(option.value)
+        ? selected.filter((v) => v !== option.value)
+        : [...selected, option.value],
+    );
+  }
+
+  return (
+    <ComboboxShell
+      {...rest}
+      multiple
+      selectedValues={selected}
+      onSelectOption={toggle}
+      onClearSelection={() => commitValues([])}
+      tokens={selectedOptions.map((option) => (
+        <span key={option.value} data-terp="combobox-token">
+          {resolve(option.label)}
+          <button
+            type="button"
+            data-terp="combobox-token-remove"
+            // The label carries the option, so a screen reader hears which token this
+            // removes rather than one of N identical "Remove" buttons.
+            aria-label={`${resolve(removeLabel ?? strings.comboboxRemove)} ${resolve(option.label)}`}
+            disabled={rest.disabled}
+            onClick={() => commitValues(selected.filter((v) => v !== option.value))}
+          >
+            ×
+          </button>
+        </span>
+      ))}
+      onRemoveLast={() => {
+        const last = selected.at(-1);
+        if (last !== undefined) {
+          commitValues(selected.slice(0, -1));
+        }
+      }}
+    />
+  );
+}
+
+function SingleCombobox({ multiple: _multiple, ...props }: ComboboxSingleProps) {
+  const { value, defaultValue = null, onChange, ...rest } = props;
+  const resolve = useUiText();
+  const [uncontrolled, setUncontrolled] = useState<string | null>(defaultValue);
+  const selectedValue = value ?? uncontrolled;
+  const selectedOption = props.options.find((option) => option.value === selectedValue) ?? null;
+
+  return (
+    <ComboboxShell
+      {...rest}
+      multiple={false}
+      selectedValues={selectedValue === null ? [] : [selectedValue]}
+      // The input mirrors the selection's label in single mode, which is the whole
+      // difference in how the text box behaves between the two.
+      mirroredLabel={selectedOption === null ? "" : resolve(selectedOption.label)}
+      onSelectOption={(option) => {
+        if (value === undefined) {
+          setUncontrolled(option.value);
+        }
+        onChange?.(option.value, option);
+      }}
+      onClearSelection={() => {
+        if (value === undefined) {
+          setUncontrolled(null);
+        }
+        onChange?.(null, null);
+      }}
+    />
+  );
+}
+
+interface ShellProps extends ComboboxCommonProps {
+  multiple: boolean;
+  selectedValues: readonly string[];
+  onSelectOption: (option: ComboboxOption) => void;
+  onClearSelection: () => void;
+  mirroredLabel?: string;
+  tokens?: readonly React.ReactNode[];
+  onRemoveLast?: () => void;
+}
+
+function ComboboxShell({
   options,
-  value,
-  defaultValue = null,
-  onChange,
+  multiple,
+  selectedValues,
+  onSelectOption,
+  onClearSelection,
+  mirroredLabel = "",
+  tokens,
+  onRemoveLast,
   loading = false,
-  loadingText = "Loading…",
-  noOptionsText = "No options",
+  loadingText,
+  noOptionsText,
   clearable = false,
   defaultOpen = false,
   disabled,
@@ -51,18 +214,17 @@ export function Combobox({
   placeholder,
   style,
   ...rest
-}: ComboboxProps) {
+}: ShellProps) {
   const resolve = useUiText();
+  const strings = useStrings();
   const baseId = useId();
   const rootRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
-  const [uncontrolledValue, setUncontrolledValue] = useState<string | null>(defaultValue);
-  const selectedValue = value ?? uncontrolledValue;
-  const selectedOption = options.find((option) => option.value === selectedValue) ?? null;
-  const [query, setQuery] = useState(() => (selectedOption ? resolve(selectedOption.label) : ""));
+  const chosen = useMemo(() => new Set(selectedValues), [selectedValues]);
+  const [query, setQuery] = useState(mirroredLabel);
   const [open, setOpen] = useState(defaultOpen);
   const [activeValue, setActiveValue] = useState<string | null>(
-    defaultOpen ? selectedOption?.value ?? null : null,
+    defaultOpen ? selectedValues[0] ?? null : null,
   );
 
   // What the DOM should say, as opposed to what the state happens to hold. The listbox render
@@ -72,18 +234,32 @@ export function Combobox({
   const isOpen = open && disabled !== true;
 
   const renderedOptions = useMemo(() => {
-    const normalized = query.trim().toLocaleLowerCase();
-    if (normalized.length === 0 || selectedOption !== null && query === resolve(selectedOption.label)) {
+    // `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();
+    // The second clause is single-mode only: there the box MIRRORS the chosen label, so the
+    // text equalling that label means "nothing typed yet" rather than a filter. In multiple
+    // mode the box is only ever a filter — there is no one label to mirror — so a query that
+    // happens to equal an option's label must still filter to it.
+    if (normalized.length === 0 || (!multiple && mirroredLabel !== "" && query === mirroredLabel)) {
       return options;
     }
-    return options.filter((option) => resolve(option.label).toLocaleLowerCase().includes(normalized));
-  }, [options, query, resolve, selectedOption]);
+    return options.filter((option) => resolve(option.label).toLowerCase().includes(normalized));
+  }, [multiple, mirroredLabel, options, query, resolve]);
   const enabledOptions = renderedOptions.filter((option) => !option.disabled);
   const activeOption = renderedOptions.find((option) => option.value === activeValue) ?? enabledOptions[0] ?? null;
 
   useEffect(() => {
-    setQuery(selectedOption ? resolve(selectedOption.label) : "");
-  }, [resolve, selectedOption]);
+    // Only single mode mirrors: in multiple mode this would erase what the user is typing
+    // every time a token changes, which is exactly when they are mid-search for the next one.
+    if (!multiple) {
+      setQuery(mirroredLabel);
+    }
+  }, [multiple, mirroredLabel]);
 
   useEffect(() => {
     if (!open) {
@@ -92,7 +268,7 @@ export function Combobox({
     function onPointerDown(event: PointerEvent | MouseEvent) {
       if (rootRef.current !== null && event.target instanceof Node && !rootRef.current.contains(event.target)) {
         setOpen(false);
-        setQuery(selectedOption ? resolve(selectedOption.label) : "");
+        setQuery(multiple ? "" : mirroredLabel);
       }
     }
     document.addEventListener("pointerdown", onPointerDown);
@@ -101,19 +277,37 @@ export function Combobox({
       document.removeEventListener("pointerdown", onPointerDown);
       document.removeEventListener("mousedown", onPointerDown);
     };
-  }, [open, resolve, selectedOption]);
+  }, [multiple, mirroredLabel, open]);
 
   function commit(option: ComboboxOption | null) {
     if (option?.disabled) {
       return;
     }
-    if (value === undefined) {
-      setUncontrolledValue(option?.value ?? null);
+    if (option === null) {
+      onClearSelection();
+      setQuery("");
+      setOpen(false);
+      setActiveValue(null);
+      return;
     }
-    setQuery(option ? (value === undefined ? resolve(option.label) : selectedOption ? resolve(selectedOption.label) : "") : "");
+    onSelectOption(option);
+    if (multiple) {
+      // The list STAYS OPEN and the filter is cleared: picking one member of a set is
+      // almost never the last thing the user wants, and closing after each pick makes
+      // choosing three options three round trips through the control.
+      setQuery("");
+      setActiveValue(option.value);
+      return;
+    }
+    // `mirroredLabel`, never the clicked option's label. In a CONTROLLED combobox the
+    // parent may decline the change — `value` stays what it was — and the box has to keep
+    // showing what the prop says rather than what was clicked. Uncontrolled reaches the
+    // same place one render later: the selection changes, `mirroredLabel` changes with it,
+    // and the mirror effect above sets the box. So this line is correct in both modes for
+    // the same reason, which the previous three-way conditional was doing by hand.
+    setQuery(mirroredLabel);
     setOpen(false);
-    setActiveValue(option?.value ?? null);
-    onChange?.(option?.value ?? null, option);
+    setActiveValue(option.value);
   }
 
   function moveActive(direction: 1 | -1 | "first" | "last") {
@@ -169,7 +363,16 @@ export function Combobox({
         if (open) {
           event.preventDefault();
           setOpen(false);
-          setQuery(selectedOption ? resolve(selectedOption.label) : "");
+          setQuery(multiple ? "" : mirroredLabel);
+        }
+        break;
+      case "Backspace":
+        // Only with an empty box, so this never eats a character. It is the shortcut every
+        // token field has, and it is an ADDITION to the per-token remove buttons rather than
+        // a replacement: a keyboard user who does not know the shortcut can still tab to a
+        // token and press it.
+        if (multiple && query.length === 0) {
+          onRemoveLast?.();
         }
         break;
       default:
@@ -179,7 +382,8 @@ export function Combobox({
 
   return (
     <div ref={rootRef} data-terp="combobox">
-      <div data-terp="combobox-field">
+      <div data-terp="combobox-field" data-multiple={multiple ? "true" : undefined}>
+        {tokens}
         <input
           {...rest}
           ref={inputRef}
@@ -197,7 +401,9 @@ export function Combobox({
             onFocus?.(event);
             if (!disabled) {
               setOpen(true);
-              setActiveValue(selectedOption?.value ?? enabledOptions[0]?.value ?? null);
+              setActiveValue(
+                (multiple ? null : selectedValues[0] ?? null) ?? enabledOptions[0]?.value ?? null,
+              );
             }
           }}
           onBlur={onBlur}
@@ -205,18 +411,15 @@ export function Combobox({
             setQuery(event.currentTarget.value);
             setOpen(true);
             setActiveValue(null);
-            if (selectedValue !== null && value === undefined) {
-              setUncontrolledValue(null);
-            }
           }}
           onKeyDown={handleKeyDown}
           style={style}
         />
-        {clearable && !disabled && query.length > 0 && (
+        {clearable && !disabled && (query.length > 0 || (multiple && chosen.size > 0)) && (
           <button
             type="button"
             data-terp="iconbutton"
-            aria-label="Clear selection"
+            aria-label={multiple ? strings.clearAllSelections : strings.clearSelection}
             onClick={() => {
               commit(null);
               inputRef.current?.focus();
@@ -227,16 +430,25 @@ export function Combobox({
         )}
       </div>
       {isOpen && (
-        <div id={`${baseId}-listbox`} role="listbox" data-terp="combobox-list">
+        <div
+          id={`${baseId}-listbox`}
+          role="listbox"
+          aria-multiselectable={multiple ? true : undefined}
+          data-terp="combobox-list"
+        >
           {loading ? (
-            <div role="status" data-terp="combobox-empty">{resolve(loadingText)}</div>
+            <div role="status" data-terp="combobox-empty">
+              {resolve(loadingText ?? strings.comboboxLoading)}
+            </div>
           ) : renderedOptions.length === 0 ? (
-            <div data-terp="combobox-empty">{resolve(noOptionsText)}</div>
+            <div data-terp="combobox-empty">
+              {resolve(noOptionsText ?? strings.comboboxNoOptions)}
+            </div>
           ) : (
             renderedOptions.map((option) => {
               const label = resolve(option.label);
               const active = option.value === activeOption?.value;
-              const selected = option.value === selectedValue;
+              const selected = chosen.has(option.value);
               return (
                 <button
                   key={option.value}

package/src/ui/DatePicker.tsx

@@ -1,9 +1,10 @@
 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";
+import { useStrings, useUiText } from "../uiText";
 import type { UiText } from "../uiText";
 import { Popover } from "./Popover";
 
@@ -50,7 +51,7 @@ export function DatePicker({
   min,
   max,
   disabled = false,
-  placeholder = "Select date",
+  placeholder,
   "aria-label": ariaLabel,
   "aria-invalid": ariaInvalid,
   defaultOpen = false,
@@ -65,8 +66,15 @@ export function DatePicker({
   // was clicking the disabled trigger.
   const [open, setOpen] = useState(defaultOpen && !disabled);
   const locale = useDateLocale();
+  const strings = useStrings();
   const resolve = useUiText();
-  const formatted = selected === null ? resolve(placeholder) : formatDate(selected, locale);
+  // Falls back to the string TABLE rather than to a literal default on the prop. A
+  // `placeholder = "Select date"` default is overridable and still untranslatable: a plain
+  // string resolves as-is, so an app that does not pass the prop shows English in every
+  // locale. Reaching the table means the app's own catalogue answers when the caller says
+  // nothing, which is the whole point of having one.
+  const formatted =
+    selected === null ? resolve(placeholder ?? strings.selectDate) : formatDate(selected, locale);
 
   function commit(next: Date) {
     if (value === undefined) {
@@ -120,7 +128,7 @@ export function DateRangePicker({
   min,
   max,
   disabled = false,
-  placeholder = "Select date range",
+  placeholder,
   "aria-label": ariaLabel,
   "aria-invalid": ariaInvalid,
   defaultOpen = false,
@@ -135,9 +143,10 @@ export function DateRangePicker({
   // was clicking the disabled trigger.
   const [open, setOpen] = useState(defaultOpen && !disabled);
   const locale = useDateLocale();
+  const strings = useStrings();
   const resolve = useUiText();
   const formatted = selected.start === null
-    ? resolve(placeholder)
+    ? resolve(placeholder ?? strings.selectDateRange)
     : selected.end === null
       ? `${formatDate(selected.start, locale)} –`
       : `${formatDate(selected.start, locale)} – ${formatDate(selected.end, locale)}`;
@@ -202,6 +211,7 @@ interface CalendarProps {
 }
 
 function Calendar({ mode, locale, visibleSeed, selected = null, range, min, max, onSelect, onRangeSelect, onEscape }: CalendarProps) {
+  const strings = useStrings();
   const gridId = useId();
   const titleId = useId();
   const minDate = normalizeDate(min);
@@ -343,9 +353,9 @@ function Calendar({ mode, locale, visibleSeed, selected = null, range, min, max,
     // wcag2a/aa tags the lane runs, so opening the calendar in stage 4 did not surface it.
     <div role="dialog" aria-modal="false" aria-labelledby={titleId} data-terp="calendar">
       <div data-terp="calendar-header">
-        <button type="button" data-terp="iconbutton" aria-label="Previous month" onClick={() => changeMonth(-1)}>‹</button>
+        <button type="button" data-terp="iconbutton" aria-label={strings.previousMonth} onClick={() => changeMonth(-1)}>‹</button>
         <div id={titleId} data-terp="calendar-title">{formatMonth(month, locale)}</div>
-        <button type="button" data-terp="iconbutton" aria-label="Next month" onClick={() => changeMonth(1)}>›</button>
+        <button type="button" data-terp="iconbutton" aria-label={strings.nextMonth} onClick={() => changeMonth(1)}>›</button>
       </div>
       <div data-terp="calendar-week" aria-hidden="true">
         {weekdays.map((day) => <div key={day} data-terp="calendar-weekday">{day}</div>)}
@@ -414,13 +424,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 +460,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");
+  });
+});