@terpjs/react-core 0.10.0 → 0.12.0

package/src/ui/Combobox.test.tsx

@@ -127,3 +127,93 @@ describe("Combobox", () => {
     expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
   });
 });
+
+describe("Combobox multiple", () => {
+  it("accumulates a set, keeps the list open, and clears the filter between picks", () => {
+    // The reason this mode exists: a set-valued field had no control, and the absence
+    // produced comma-separated text boxes with the legal values in a grey hint beside them
+    // — a closed enum typed as free text, so validation the value set could have enforced
+    // was lost. Picking one member of a set is almost never the last thing a user wants, so
+    // the list staying open is the behaviour, not a detail.
+    const onChange = vi.fn();
+    render(<Combobox multiple aria-label="Fields" options={options} onChange={onChange} />);
+    const input = screen.getByRole("combobox", { name: "Fields" });
+
+    fireEvent.focus(input);
+    fireEvent.click(screen.getByRole("option", { name: "Netherlands" }));
+    expect(onChange).toHaveBeenLastCalledWith(["nl"], [options[0]]);
+    // Still open, and the filter is empty so the next pick starts from the whole list.
+    expect(screen.getByRole("listbox")).toBeInTheDocument();
+    expect(input).toHaveValue("");
+
+    fireEvent.click(screen.getByRole("option", { name: "France" }));
+    expect(onChange).toHaveBeenLastCalledWith(["nl", "fr"], [options[0], options[3]]);
+
+    // Selecting an already-chosen option removes it — one control, both directions.
+    fireEvent.click(screen.getByRole("option", { name: "Netherlands" }));
+    expect(onChange).toHaveBeenLastCalledWith(["fr"], [options[3]]);
+  });
+
+  it("says it is multi-selectable and marks every chosen option", () => {
+    render(<Combobox multiple aria-label="Fields" options={options} defaultValue={["nl", "fr"]} defaultOpen />);
+    expect(screen.getByRole("listbox")).toHaveAttribute("aria-multiselectable", "true");
+    expect(screen.getByRole("option", { name: "Netherlands" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("option", { name: "France" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("option", { name: "Belgium" })).toHaveAttribute("aria-selected", "false");
+  });
+
+  it("gives every token a remove control whose name says which token it removes", () => {
+    // N identical "Remove" buttons is not a keyboard-accessible token field: the name has to
+    // carry the option, or a screen-reader user cannot tell which one they are about to
+    // remove. These are real buttons and real tab stops — the accessible half of the
+    // Backspace shortcut rather than a duplicate of it, because a shortcut is only
+    // discoverable if you already know about it.
+    const onChange = vi.fn();
+    render(
+      <Combobox multiple aria-label="Fields" options={options} defaultValue={["nl", "fr"]} onChange={onChange} />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Remove Netherlands" }));
+    expect(onChange).toHaveBeenLastCalledWith(["fr"], [options[3]]);
+  });
+
+  it("removes the last token on Backspace only when the filter is empty", () => {
+    const onChange = vi.fn();
+    render(
+      <Combobox multiple aria-label="Fields" options={options} defaultValue={["nl", "fr"]} onChange={onChange} />,
+    );
+    const input = screen.getByRole("combobox", { name: "Fields" });
+
+    // With text in the box, Backspace belongs to the text: eating a token here would
+    // delete a selection while the user thinks they are correcting a typo.
+    fireEvent.change(input, { target: { value: "Bel" } });
+    fireEvent.keyDown(input, { key: "Backspace" });
+    expect(onChange).not.toHaveBeenCalled();
+
+    fireEvent.change(input, { target: { value: "" } });
+    fireEvent.keyDown(input, { key: "Backspace" });
+    expect(onChange).toHaveBeenLastCalledWith(["nl"], [options[0]]);
+  });
+
+  it("keeps a controlled set when the parent declines the change", () => {
+    // The same invariant single mode has: the control shows what the prop says, not what
+    // was clicked. A token that appears because it was clicked and not because the parent
+    // accepted it is a field that disagrees with the state it is bound to.
+    const onChange = vi.fn();
+    render(
+      <Combobox multiple aria-label="Fields" options={options} value={["nl"]} onChange={onChange} defaultOpen />,
+    );
+    fireEvent.click(screen.getByRole("option", { name: "France" }));
+    expect(onChange).toHaveBeenLastCalledWith(["nl", "fr"], [options[0], options[3]]);
+    expect(screen.getByRole("button", { name: "Remove Netherlands" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Remove France" })).toBeNull();
+  });
+
+  it("clears the whole set through the clear control", () => {
+    const onChange = vi.fn();
+    render(
+      <Combobox multiple clearable aria-label="Fields" options={options} defaultValue={["nl", "fr"]} onChange={onChange} />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Clear all selections" }));
+    expect(onChange).toHaveBeenLastCalledWith([], []);
+  });
+});

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
@@ -79,17 +241,25 @@ export function Combobox({
     // 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)) {
+    // 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).toLowerCase().includes(normalized));
-  }, [options, query, resolve, selectedOption]);
+  }, [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) {
@@ -98,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);
@@ -107,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") {
@@ -175,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:
@@ -185,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}
@@ -203,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}
@@ -211,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();
@@ -233,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

@@ -4,7 +4,7 @@ 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";
 
@@ -51,7 +51,7 @@ export function DatePicker({
   min,
   max,
   disabled = false,
-  placeholder = "Select date",
+  placeholder,
   "aria-label": ariaLabel,
   "aria-invalid": ariaInvalid,
   defaultOpen = false,
@@ -66,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) {
@@ -121,7 +128,7 @@ export function DateRangePicker({
   min,
   max,
   disabled = false,
-  placeholder = "Select date range",
+  placeholder,
   "aria-label": ariaLabel,
   "aria-invalid": ariaInvalid,
   defaultOpen = false,
@@ -136,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)}`;
@@ -203,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);
@@ -344,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>)}

package/src/ui/Tabs.test.tsx

@@ -27,3 +27,31 @@ describe("Tabs", () => {
     expect(onChange).toHaveBeenCalledWith("audit");
   });
 });
+
+describe("Tabs with a single tab", () => {
+  it("renders the content bare, with no tablist to choose from", () => {
+    // A tab set over one tab costs a row of the screen to offer nothing, and to a screen
+    // reader it is worse than decorative: it announces "tab 1 of 1" and the only
+    // affordance is already selected.
+    render(<Tabs label="Sections" tabs={[{ value: "only", label: "Only", content: "Body" }]} />);
+    expect(screen.queryByRole("tablist")).toBeNull();
+    expect(screen.queryByRole("tab")).toBeNull();
+    // The panel goes too: a tabpanel exists to be labelled by the tab that reveals it, and
+    // there is nothing left to reveal.
+    expect(screen.queryByRole("tabpanel")).toBeNull();
+    expect(screen.getByText("Body")).toBeInTheDocument();
+  });
+
+  it("keeps the chrome when that single tab is disabled", () => {
+    // Here the tab set carries real information — this section exists and is unavailable —
+    // and rendering its content bare would show what the caller marked unreachable.
+    render(
+      <Tabs
+        label="Sections"
+        tabs={[{ value: "only", label: "Only", content: "Body", disabled: true }]}
+      />,
+    );
+    expect(screen.getByRole("tablist")).toBeInTheDocument();
+    expect(screen.getByRole("tab", { name: "Only" })).toBeDisabled();
+  });
+});

package/src/ui/Tabs.tsx

@@ -38,6 +38,20 @@ export function Tabs({ tabs, value, defaultValue, onChange, label }: TabsProps)
   // interpolate caller strings into ids is written out at AppShell's nav-group labels.
   const selectedIndex = tabs.findIndex((tab) => tab.value === selectedTab?.value);
 
+  // One usable tab is not a choice, so it gets no chrome. A tablist over a single tab costs
+  // a row of the screen to offer nothing, and it is worse than decorative to a screen
+  // reader: the set announces "tab 1 of 1" and the only affordance is already selected.
+  // Rendering the content bare also drops the tabpanel, which is correct rather than
+  // convenient — a panel exists to be labelled by the tab that reveals it, and there is
+  // no revealing left to do.
+  //
+  // A single DISABLED tab keeps the chrome, deliberately: there the tab set is carrying
+  // real information (this section exists and is unavailable), and silently rendering its
+  // content would show what the caller marked unreachable.
+  if (tabs.length === 1 && !tabs[0]?.disabled) {
+    return <>{tabs[0]?.content}</>;
+  }
+
   function select(next: string) {
     if (value === undefined) {
       setUncontrolledValue(next);