@terpjs/react-core 0.9.0 → 0.11.0

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>
+  );
 }

package/src/ui/Menu.tsx

@@ -9,7 +9,17 @@ import type { PopoverAlign, PopoverPlacement, PopoverRootMarker, PopoverRootVari
 
 export interface MenuProps {
   trigger: ReactNode;
-  triggerLabel: UiText;
+  /**
+   * The trigger's accessible name, as `aria-label`.
+   *
+   * Optional, and omitting it is a claim rather than a shortcut: `aria-label` REPLACES the
+   * subtree text in the accessible name, so a trigger that renders its own visible label
+   * must not carry one — naming it something else hides what the user can see and leaves a
+   * voice-control user with no spoken label that matches it (WCAG 2.5.3, Label in Name).
+   * Pass it whenever the trigger's content is an icon, initials or anything `aria-hidden`,
+   * which is every packaged caller but `UserMenu`'s expanded form.
+   */
+  triggerLabel?: UiText;
   children: (api: { close: (restoreFocus?: boolean) => void }) => ReactNode;
   open?: boolean;
   defaultOpen?: boolean;
@@ -73,11 +83,12 @@ export function Menu({
       data-owner={owner}
       trigger={
         // Its own marker rather than the shared `iconbutton` it used to borrow. That marker
-        // is worn by sixteen visually different sites — the shell's two header toggles, four
+        // is worn by seventeen visually different sites — the shell's two header toggles, four
         // pagination arrows, a toast dismisser, the combobox's clear button, the calendar's
         // month arrows, the DataView's expand toggle, the view-options panel's two reorder
-        // arrows and the DataView toolbar's clear-search button and two layout toggles — and it
-        // has no base rule at all, because each is styled by where it sits.
+        // arrows, the DataView toolbar's clear-search button and two layout toggles, and the
+        // password field's reveal toggle — and its base rule carries a transition and nothing
+        // else, because the GEOMETRY of each is decided by where it sits.
         // This one is an outlined control with a border, a radius and control
         // typography, and it is also the trigger whose root marker is about to become
         // configurable, so a `[data-terp="popover"] > [data-terp="iconbutton"]` structural
@@ -86,7 +97,7 @@ export function Menu({
         <button
           type="button"
           data-terp="menu-trigger"
-          aria-label={resolve(triggerLabel)}
+          aria-label={triggerLabel === undefined ? undefined : resolve(triggerLabel)}
           aria-haspopup="menu"
         >
           {trigger}

package/src/ui/Popover.tsx

@@ -237,6 +237,19 @@ export function Popover({
           // lives in the sheet with everything else instead of travelling as an object.
           data-owner={owner ?? rootMarker ?? "popover"}
           tabIndex={-1}
+          // Tab closes the panel and restores focus to the trigger FIRST, then lets the default
+          // action run from there — the contract `Menu` already implements, and for the reason
+          // written out at that call site. The panel is portalled to the end of document.body,
+          // so with no Tab branch the sequential-navigation starting point stayed inside a node
+          // at the wrong end of the document: Tab out of the panel landed past every piece of
+          // page content, and Shift+Tab landed on the last focusable element on the page rather
+          // than back on the control that opened it. Deliberately not a focus TRAP — a popover
+          // is a non-modal disclosure, and trapping would be a stronger promise than it makes.
+          onKeyDown={(event) => {
+            if (event.key === "Tab") {
+              close(true);
+            }
+          }}
           // Only the measured part is inline: the left/top the layout effect computes from
           // the trigger's rect and clamps against the viewport, and the visibility that
           // hides the panel for the frame before that measurement exists. Everything the

package/src/ui/Radio.tsx

@@ -1,5 +1,5 @@
 import { useId, useState } from "react";
-import type { InputHTMLAttributes, ReactNode } from "react";
+import type { ChangeEvent, InputHTMLAttributes } from "react";
 
 import { injectTerpStyles } from "../styles";
 import { useUiText } from "../uiText";
@@ -28,7 +28,15 @@ export function Radio({ label, value, checked, defaultChecked, onChange, style,
         value={value}
         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>
@@ -45,7 +53,6 @@ export interface RadioGroupProps {
   label: UiText;
   name?: string;
   options?: readonly RadioOption[];
-  children?: ReactNode;
   value?: string;
   defaultValue?: string;
   onChange?: (value: string) => void;
@@ -57,7 +64,6 @@ export function RadioGroup({
   label,
   name,
   options,
-  children,
   value,
   defaultValue,
   onChange,
@@ -95,7 +101,6 @@ export function RadioGroup({
             }}
           />
         ))}
-        {children}
       </div>
     </fieldset>
   );

package/src/ui/Select.test.tsx

@@ -0,0 +1,232 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { UiTextProvider } from "../uiText";
+import { Select } from "./Select";
+import type { SelectOption } from "./Select";
+
+afterEach(cleanup);
+
+type Status = "open" | "doing" | "done";
+
+const STATUSES: SelectOption<Status>[] = [
+  { value: "open", label: "Open" },
+  { value: "doing", label: "In progress" },
+  { value: "done", label: "Done", disabled: true },
+];
+
+describe("Select — the options list", () => {
+  it("renders one option per entry, in order, with the disabled flag applied", () => {
+    render(<Select aria-label="Status" options={STATUSES} defaultValue="open" />);
+    const options = screen.getAllByRole("option") as HTMLOptionElement[];
+    expect(options.map((option) => [option.value, option.textContent])).toEqual([
+      ["open", "Open"],
+      ["doing", "In progress"],
+      ["done", "Done"],
+    ]);
+    // The flag has to reach the element rather than only the data, which is the half a
+    // "renders three options" assertion would miss.
+    expect(options.map((option) => option.disabled)).toEqual([false, false, true]);
+  });
+
+  it("resolves a label descriptor through the active resolver, not just a plain string", () => {
+    // `label` is a UiText, so a translated catalog has to reach it — a component that
+    // rendered `String(label)` would print "[object Object]" and this is what says so.
+    render(
+      <UiTextProvider resolveText={(text) => (typeof text === "string" ? text : `nl:${text.id}`)}>
+        <Select
+          aria-label="Status"
+          options={[{ value: "open", label: { id: "status.open", message: "Open" } }]}
+        />
+      </UiTextProvider>,
+    );
+    expect(screen.getByRole("option")).toHaveTextContent("nl:status.open");
+  });
+
+  it("shows the placeholder as the selected row, not just as an option", () => {
+    // The selection is the assertion, and the markup-only version of this test was green
+    // against a real bug. HTML's selectedness algorithm picks the first option that is NOT
+    // disabled, so a disabled placeholder row is skipped and the control opens on the first
+    // real choice: measured, `value=open, selectedIndex=1`, with a "Choose a status" row sitting
+    // in the list that the user never saw. Every markup assertion below passed throughout.
+    render(<Select aria-label="Status" options={STATUSES} placeholder="Choose a status" />);
+    const select = screen.getByRole("combobox") as HTMLSelectElement;
+    expect(select.value).toBe("");
+    expect(select.selectedIndex).toBe(0);
+    expect(select.options[0]!.textContent).toBe("Choose a status");
+    // Still disabled and still empty-valued: an enabled placeholder is re-selectable, and a
+    // non-empty value would submit the prompt text as data.
+    expect(select.options[0]!.disabled).toBe(true);
+    expect(select.options[0]!.value).toBe("");
+  });
+
+  it("lets an explicit value win over the placeholder", () => {
+    // The other half: starting empty is a default for the unpinned case, not an override. A
+    // caller who pins a value gets it, and the placeholder stays in the list as the row they
+    // came from.
+    render(
+      <Select aria-label="Status" options={STATUSES} placeholder="Choose" defaultValue="doing" />,
+    );
+    const select = screen.getByRole("combobox") as HTMLSelectElement;
+    expect(select.value).toBe("doing");
+    expect(select.selectedIndex).toBe(2);
+  });
+
+  it("resolves a placeholder descriptor too, not only a plain string", () => {
+    // `placeholder` is typed `UiText`, and a `string`-only version would have compiled just as
+    // well while rendering "[object Object]" on screen — the string test above cannot tell the
+    // two apart, so this is the assertion that can.
+    //
+    // (An earlier version of this comment claimed `SelectHTMLAttributes` already declares
+    // `placeholder?: string` and that the union therefore intersects with it. It does not:
+    // `placeholder` is declared on `AllHTMLAttributes`, `InputHTMLAttributes` and
+    // `TextareaHTMLAttributes` only. There is no intersection here, and the prop is simply
+    // ours.)
+    render(
+      <UiTextProvider resolveText={(text) => (typeof text === "string" ? text : `nl:${text.id}`)}>
+        <Select
+          aria-label="Status"
+          options={STATUSES}
+          placeholder={{ id: "status.choose", message: "Choose a status" }}
+        />
+      </UiTextProvider>,
+    );
+    expect(screen.getAllByRole("option")[0]).toHaveTextContent("nl:status.choose");
+  });
+
+  it("hands onValueChange the selected value, and still fires the raw onChange", () => {
+    const onValueChange = vi.fn();
+    const onChange = vi.fn();
+    render(
+      <Select
+        aria-label="Status"
+        options={STATUSES}
+        defaultValue="open"
+        onValueChange={onValueChange}
+        onChange={onChange}
+      />,
+    );
+    fireEvent.change(screen.getByRole("combobox"), { target: { value: "doing" } });
+    expect(onValueChange).toHaveBeenCalledWith("doing");
+    // Both, not one instead of the other: a caller that needs the element keeps its event.
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange.mock.calls[0]![0].target.value).toBe("doing");
+  });
+
+  it("calls onValueChange without an options list too", () => {
+    // The typed callback is on the value props, not on the options branch, so the raw-children
+    // form gets it as well. Worth pinning: putting it on one branch only would be the
+    // works-in-one-branch defect the union exists to prevent.
+    const onValueChange = vi.fn();
+    render(
+      <Select aria-label="Status" defaultValue="open" onValueChange={onValueChange}>
+        <option value="open">Open</option>
+        <option value="doing">In progress</option>
+      </Select>,
+    );
+    fireEvent.change(screen.getByRole("combobox"), { target: { value: "doing" } });
+    expect(onValueChange).toHaveBeenCalledWith("doing");
+  });
+});
+
+describe("Select — what did not change", () => {
+  it("still renders raw option children unchanged, and carries the shared control marker", () => {
+    render(
+      <Select aria-label="Status" defaultValue="doing">
+        <option value="open">Open</option>
+        <option value="doing">In progress</option>
+      </Select>,
+    );
+    const select = screen.getByRole("combobox");
+    expect(select).toHaveAttribute("data-terp", "input");
+    expect((select as HTMLSelectElement).value).toBe("doing");
+    expect(screen.getAllByRole("option")).toHaveLength(2);
+  });
+
+  it("renders no inline style in either form", () => {
+    // ADR 0094 §3 as an assertion rather than a claim: the control's surface, the focus ring
+    // and the chevron are all sheet rules keyed on `data-terp="input"`, and the inline-style
+    // ledger is exact-equality per file — so a style attribute here would fail markers.test.ts
+    // as well, one release later and further from the cause.
+    const { container } = render(
+      <>
+        <Select aria-label="A" options={STATUSES} />
+        <Select aria-label="B">
+          <option value="open">Open</option>
+        </Select>
+      </>,
+    );
+    for (const select of container.querySelectorAll("select")) {
+      expect(select.getAttribute("style")).toBeNull();
+    }
+  });
+
+  it("still accepts a multiple select with an array value", () => {
+    // A regression this file exists to prevent, because it happened. The first version of the
+    // options work put the narrowed `value?: T` on BOTH branches, which quietly made
+    // `<Select multiple value={["a", "b"]}>` a typecheck error — a shape a raw `<select>` has
+    // and this component had always accepted. Nothing in the repo used it, so no gate noticed;
+    // it was found by probing the type rather than by running the suite.
+    //
+    // The narrowing only earns anything where `T` can be inferred, which is the options list.
+    // So the raw-children branch keeps `SelectHTMLAttributes` untouched, and this case is the
+    // assertion that says so. It has to COMPILE as much as pass.
+    render(
+      <Select aria-label="Tags" multiple value={["a", "b"]} onChange={() => {}}>
+        <option value="a">A</option>
+        <option value="b">B</option>
+        <option value="c">C</option>
+      </Select>,
+    );
+    const select = screen.getByRole("listbox") as HTMLSelectElement;
+    expect(select.multiple).toBe(true);
+    expect([...select.selectedOptions].map((option) => option.value)).toEqual(["a", "b"]);
+  });
+
+  it("still accepts a numeric value with numeric option children", () => {
+    // The other shape the over-eager narrowing broke: `value?: string | number` is what
+    // `SelectHTMLAttributes` declares, and a rank ladder rendered as numbers is the obvious
+    // caller — `UserCreate` was written that way before it moved to an options list.
+    render(
+      <Select aria-label="Rank" value={20} onChange={() => {}}>
+        <option value={10}>Viewer</option>
+        <option value={20}>Editor</option>
+      </Select>,
+    );
+    expect((screen.getByRole("combobox") as HTMLSelectElement).value).toBe("20");
+  });
+
+  it("keeps React's own read-only diagnostic for a value with no handler", () => {
+    // The change that removed this was an unconditional onChange wrapper: React's
+    // `checkControlledValueProps` short-circuits on `props.onChange`, so attaching one always
+    // silenced the "you provided a `value` prop to a form field without an `onChange` handler"
+    // warning. The control then looked editable, never updated, and said nothing about it —
+    // strictly worse than before the options list existed. The wrapper is attached only when
+    // there is something to call.
+    const errors = vi.spyOn(console, "error").mockImplementation(() => {});
+    render(<Select aria-label="Status" options={STATUSES} value="open" />);
+    const logged = errors.mock.calls.map((call) => String(call[0])).join(" ");
+    errors.mockRestore();
+    expect(logged).toContain("without an `onChange` handler");
+  });
+
+  it("still renders with neither options nor children", () => {
+    // Legal before this component took an options list — a screen that renders its select
+    // before its choices have loaded — so `children` stays optional on that branch. Making it
+    // required was an unannounced breaking type change that nothing in the repo exercised.
+    render(<Select aria-label="Empty" />);
+    expect(screen.getByRole("combobox")).toBeInTheDocument();
+    expect(screen.queryAllByRole("option")).toHaveLength(0);
+  });
+
+  it("forwards arbitrary select attributes to the element", () => {
+    render(
+      <Select aria-label="Status" options={STATUSES} name="status" required disabled />,
+    );
+    const select = screen.getByRole("combobox") as HTMLSelectElement;
+    expect(select.name).toBe("status");
+    expect(select.required).toBe(true);
+    expect(select.disabled).toBe(true);
+  });
+});

package/src/ui/Select.tsx

@@ -1,17 +1,186 @@
-import type { SelectHTMLAttributes } from "react";
+import type { ChangeEvent, ReactNode, SelectHTMLAttributes } from "react";
 
 import { injectTerpStyles } from "../styles";
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
 
 injectTerpStyles();
 
-export type SelectProps = SelectHTMLAttributes<HTMLSelectElement>;
+/**
+ * One choice in a {@link Select}'s `options` list.
+ *
+ * `value` is the type parameter rather than `string`, which is the whole point of the list
+ * existing: a closed enum passed here checks its own members, so a typo is a typecheck error
+ * instead of an option nobody can select. `ComboboxOption` is the same shape without the
+ * parameter, and it can follow the day something asks — widening it is additive.
+ */
+export interface SelectOption<T extends string = string> {
+  value: T;
+  /** Display text; a {@link UiText} descriptor so a translated label is expressible. */
+  label: UiText;
+  disabled?: boolean;
+}
+
+/** Everything a raw `<select>` accepts, minus what the two forms disagree about. */
+type SelectBase = Omit<
+  SelectHTMLAttributes<HTMLSelectElement>,
+  "children" | "value" | "defaultValue"
+>;
+
+/** The unselected state a `placeholder` occupies — an empty value, as HTML spells it. */
+type Unselected = "";
 
 /**
- * Token-styled select — use instead of a raw `<select>` (the module-boundary rule). Pass
- * `<option>` children as usual. The `data-terp="input"` marker opts the element into the
- * shared control surface and focus ring; the sheet replaces the native affordance with an
- * SVG chevron so the control looks the same on every platform (ADR 0094).
+ * Props: the shared surface, plus a union over the two ways to give a `<select>` its choices.
+ *
+ * Four things here were each arrived at by breaking the alternative and measuring it, so they
+ * are worth stating rather than rediscovering.
+ *
+ * **`onValueChange` sits outside the union, and its parameter is `NoInfer`.** Inside the union
+ * the prop has two signatures and TypeScript cannot contextually type a parameter across a
+ * union of signatures: `onValueChange={(value) => …}` came back as an implicit `any`, which
+ * under `noImplicitAny` is an error the caller must paper over with an annotation — very nearly
+ * the cast this prop exists to remove. Outside the union it infers, but then the *callback*
+ * becomes an inference site for `T`: with raw children,
+ * `<Select onValueChange={setStatus}><option value="dong"/></Select>` took `T` from `setStatus`
+ * and never compared the children to it, so the one thing the prop promises to prevent was
+ * exactly what it allowed. `NoInfer` leaves the options list as the only inference site.
+ *
+ * **The value narrowing is on the options branch only.** Narrowing `value` to `T` is what
+ * removes `as Status`, but `T` can only come from an options list — so on the raw-children
+ * branch the same narrowing buys nothing and costs two shapes a `<select>` genuinely has:
+ * `multiple` with a `readonly string[]` value, and a numeric `value`.
+ *
+ * **A placeholder widens the value to `""`.** HTML's own selectedness algorithm picks the first
+ * option that is *not disabled*, so a disabled placeholder row is skipped and the control opens
+ * on the first real choice — measured: `value=open, selectedIndex=1`. Showing the placeholder
+ * means the select's value is the empty string, which is therefore part of the type rather than
+ * something a caller has to cast to.
+ *
+ * **The two forms are a union.** Rendering `options` while silently ignoring `children` would be
+ * a prop that works in one branch and does nothing in the other. `children` stays optional,
+ * though: a `<Select>` with no choices yet was legal before this component took an options list
+ * and still is.
  */
-export function Select(props: SelectProps) {
-  return <select data-terp="input" {...props} />;
+export type SelectProps<T extends string = string> = SelectBase & {
+  /**
+   * The selected value, typed.
+   *
+   * With `options` given, `T` is inferred from them, so the callback is checked against the
+   * choices. With raw children there is nothing to infer from and `T` stays `string` — which
+   * is deliberate: nothing checks hand-written `<option>` values, so a narrower promise here
+   * would be a false one.
+   */
+  onValueChange?: (value: NoInfer<T>) => void;
+} & (
+    | {
+        /** The choices, as data. Mutually exclusive with `children`. */
+        options: readonly SelectOption<T>[];
+        /**
+         * A leading, disabled, empty-valued row — the "choose one" case.
+         *
+         * `placeholder` is not an attribute a `<select>` honours, so this renders the
+         * `<option value="" disabled>` every app was writing by hand, AND selects it when the
+         * caller has pinned no value of their own. Both halves are needed: without the second
+         * the row exists and is never shown.
+         */
+        placeholder?: UiText;
+        /**
+         * `NoInfer` is load-bearing. Without it `value` is a second inference site for `T`, so
+         * `value="dong"` beside a `SelectOption<Status>[]` list widens the parameter to
+         * `Status | "dong"` and compiles — the value checked against a type it helped choose.
+         */
+        value?: NoInfer<T> | Unselected;
+        defaultValue?: NoInfer<T> | Unselected;
+        children?: never;
+      }
+    | {
+        options?: never;
+        value?: SelectHTMLAttributes<HTMLSelectElement>["value"];
+        defaultValue?: SelectHTMLAttributes<HTMLSelectElement>["defaultValue"];
+        children?: ReactNode;
+      }
+  );
+
+/**
+ * Token-styled select — use instead of a raw `<select>` (the module-boundary rule).
+ *
+ * Two forms. Pass `options` (with `onValueChange` for a typed callback) when the choices are
+ * data, which is the common case and the one that had no support: a closed enum needed a
+ * hand-written `<option>` per member plus a cast on the way out, so every app grew its own
+ * `EnumSelect<T>` wrapper. Or pass `<option>` children as before, unchanged.
+ *
+ * The `data-terp="input"` marker opts the element into the shared control surface and focus
+ * ring; the sheet replaces the native affordance with an SVG chevron so the control looks the
+ * same on every platform (ADR 0094). Neither form renders an inline style.
+ */
+export function Select<T extends string = string>(props: SelectProps<T>) {
+  const resolve = useUiText();
+  // Destructured from a cast rather than in the signature: the branches of the union do not
+  // both declare these keys, so naming them as parameters would widen the parameter type to
+  // the intersection and lose the exclusivity the union exists to enforce.
+  const {
+    options,
+    placeholder,
+    children,
+    onChange,
+    onValueChange,
+    value,
+    defaultValue,
+    ...rest
+  } = props as SelectBase & {
+    options?: readonly SelectOption<T>[];
+    placeholder?: UiText;
+    children?: ReactNode;
+    onValueChange?: (value: string) => void;
+    value?: string | number | readonly string[];
+    defaultValue?: string | number | readonly string[];
+  };
+
+  // A placeholder the browser never selects is the row existing without the feature working,
+  // so an unpinned select with one starts empty. Only when the caller pinned neither, and only
+  // as `defaultValue` — passing both is a React warning, and pinning `value` would make every
+  // placeholder select controlled.
+  const startsUnselected =
+    placeholder !== undefined && value === undefined && defaultValue === undefined;
+
+  // Attached only when there is something to call. An unconditional handler silences React's
+  // own "you provided a `value` prop to a form field without an `onChange` handler" guard, so a
+  // caller who forgot the handler would get a control that looks editable, never updates, and
+  // says nothing about it.
+  const handlesChange = onChange !== undefined || onValueChange !== undefined;
+
+  return (
+    <select
+      data-terp="input"
+      {...rest}
+      value={value}
+      defaultValue={startsUnselected ? "" : defaultValue}
+      onChange={
+        handlesChange
+          ? (event: ChangeEvent<HTMLSelectElement>) => {
+              onChange?.(event);
+              onValueChange?.(event.target.value);
+            }
+          : undefined
+      }
+    >
+      {options === undefined ? (
+        children
+      ) : (
+        <>
+          {placeholder !== undefined && (
+            <option value="" disabled>
+              {resolve(placeholder)}
+            </option>
+          )}
+          {options.map((option) => (
+            <option key={option.value} value={option.value} disabled={option.disabled}>
+              {resolve(option.label)}
+            </option>
+          ))}
+        </>
+      )}
+    </select>
+  );
 }

package/src/ui/Switch.tsx

@@ -1,4 +1,4 @@
-import type { InputHTMLAttributes } from "react";
+import type { ChangeEvent, InputHTMLAttributes } from "react";
 
 import { injectTerpStyles } from "../styles";
 import { useUiText } from "../uiText";
@@ -26,7 +26,15 @@ export function Switch({ label, checked, defaultChecked, onChange, style, ...res
         data-terp="switch"
         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>