@ultimat3/ui 2.0.0 → 3.0.0

package/CATALOG.md

@@ -146,7 +146,7 @@ Native checkbox with a token-drawn indicator. The label element wraps the input,
 | `name` | `string` | — |  |
 | `value` | `string` | — |  |
 | `checked` | `boolean` | — |  |
-| `indeterminate` | `boolean` | — | Tri-state for "some children selected". Mirrored to `aria-checked`. |
+| `indeterminate` | `boolean` | — | Tri-state for "some children selected". The ONLY thing mirrored to `aria-checked`. |
 | `disabled` | `boolean` | — |  |
 | `required` | `boolean` | — |  |
 | `description` | `string` | — |  |
@@ -230,7 +230,7 @@ Renders <time datetime="<ISO instant>"> with text formatted in the context time
 
 ### Dialog
 
-Modal built on native <dialog>: the platform gives us the top layer, the backdrop, inert background content, and Escape-to-close for free. We add the labelled heading, the close affordance, and body scroll locking.
+Modal built on native <dialog>: the platform gives us the top layer, the backdrop, inert background content, and Escape-to-close for free. We add the labelled heading and the close affordance. Body scroll locking is one CSS rule in `tokens/reset.scss` (`html:has(dialog:modal)`) rather than anything here, so it covers Drawer too and cannot leak when a close path throws.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -355,7 +355,7 @@ A file picker that keeps the platform control and dresses it. The native button
 
 ### Form
 
-Form shell. Owns the one thing every form needs and always forgets: a top-of-form error summary that is focusable and announced on submit.
+Form shell. Owns the one thing every form needs and always forgets: a top-of-form error summary that is announced (the Alert inside it is a live region) and that TAKES focus when an error arrives — the focus move is what makes the summary reachable at all, since its id is internal.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -680,7 +680,7 @@ Flex layout primitive. Gap comes from the space scale as a custom property, so t
 
 ### Switch
 
-Boolean toggle with immediate effect (as opposed to Checkbox, which is part of a form submit). `role="switch"` on a native checkbox keeps keyboard behaviour.
+Boolean toggle with immediate effect (as opposed to Checkbox, which is part of a form submit). `role="switch"` on a native checkbox keeps keyboard behaviour — and its checked state, which is why nothing here writes `aria-checked`: `role="switch"` maps the host `checked` state on its own, and an attribute mirroring it never updates on the no-JS path, where ARIA would then outrank the truth and announce the switch stuck in whichever position it was rendered in.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -770,18 +770,19 @@ Theme control. `toggle` flips light/dark; `select` also offers "system", which c
 
 ### ToastRegion
 
-Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message (screen readers require that).
+Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message. That ordering is the whole point: a live region created with its content already in it is not announced by most screen readers, which is why `aria-live` sits on the persistent <ol> here and NOT on the <li> each Toast renders.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `children` | `JSX.Element` | yes |  |
 | `label` | `string` | yes | Already-translated landmark name, e.g. "Notifications". |
+| `politeness` | `Politeness` | — | How the region announces. `polite` waits for a pause and is right for everything an app routinely confirms; `assertive` interrupts whatever the user is being read, so it belongs only to a region that carries errors alone. One region, one politeness — mixing tones inside one list cannot work, because the live semantics belong to the list, not to the message. |
 | `placement` | `'block-end-inline-end' \| 'block-start-inline-end' \| 'block-end-center'` | — |  |
 | `class` | `string` | — |  |
 
 ### Toast
 
-Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message (screen readers require that).
+Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message. That ordering is the whole point: a live region created with its content already in it is not announced by most screen readers, which is why `aria-live` sits on the persistent <ol> here and NOT on the <li> each Toast renders.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -795,7 +796,7 @@ Transient notification. ToastRegion is the single live region for the app; indiv
 
 ### Toolbar
 
-The control strip above a table or a list: filters and search at the inline start, actions at the inline end. `role="toolbar"` with the same roving-tabindex helper Tabs uses, so arrow keys move between controls and the strip costs one Tab stop instead of a dozen.
+The control strip above a table or a list: filters and search at the inline start, actions at the inline end. `role="toolbar"` with the same roving-tabindex helper Tabs uses, so arrow keys move between the strip's buttons. It is NOT one tab stop: the strip holds arbitrary children it cannot reach into to set an initial `tabindex`, and a search field at the inline start keeps its own arrow keys, so making the strip a single stop would strand every control past it.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|

package/CLAUDE.md

@@ -29,6 +29,11 @@ Tier 5. Imports `@ultimat3/core`, `schema`, `i18n`, `money`, `time`. Never `http
 - **`inert-render.test.ts` must not assume which factory its `.tsx` compiled to.** `@ultimat3/render`'s `index.ts` installs a process-global `Bun.plugin` `onLoad` for `/\.tsx$/` at import, and `bun test` is one process — so any file in the run that imports render first makes every ui component after it compile to render's `h` instead of the file's own inert copy. The walker recognises both (`Symbol.for('ultimate.render.jsx')`, off the global registry, never an import), and the first test in the describe asserts a component returned a node it recognises. Without both halves the file silently rendered `"[object Object]"` and 26 assertions were decided by shard packing.
 - **Components are not unit-tested through a renderer.** `.tsx` compiles to `@ultimat3/render`'s `h`, which this package may not import, so every rule lives in a pure module beside the component (`icon-glyph.ts`, `accordion-view.ts`, `combobox-filter.ts`, `infinite-scroll-view.ts`) and *that* is what the tests assert.
 - Formatting logic lives in a pure `*-view.ts` next to the component (`money-view.ts`, `date-time-view.ts`) so it is testable with no renderer. Every other renderer-free core follows the same rule under its own name (`sort-state.ts`, `image-source.ts`) — the `.tsx` holds markup, never a rule.
+- **The rule being pure is not enough — the WIRING has to be tested too.** `createRovingTabindex` was correct and `Menu` handed it `[role="menuitem"]`, so a disabled item made every item after it unreachable and every assertion in the package still passed. `src/jsx-probe.ts` reads the props an element actually carries (a `tabindex`, an `aria-live`, an `onKeyDown`, a `ref`) and `src/fake-dom.ts` gives it a DOM where a disabled control REFUSES focus, exactly as the real one does. Both are test-only and neither is in `index.ts`. `components/interaction.test.ts` is where a keyboard or form-participation claim gets proven; asserting the pure helper alone is how these shipped.
+- **A roving group excludes disabled items from both answers** — the set arrows walk and the one item holding the tab stop (`src/roving.ts`). `focus()` on a disabled control is a no-op, so a disabled item left in the list pins the reducer on its index forever. And a control that answers arrows itself (`handlesOwnArrowKeys`) keeps them: a `Toolbar` exists to hold a search field.
+- **Live semantics belong to the container that outlives the message.** `ToastRegion`'s `<ol>` carries `aria-live`; a `Toast` is a plain `<li>`. A region created with its content already inside it is not announced, and a `role="status"` on the `<li>` also strips its `listitem` semantics.
+- **`aria-checked` never mirrors a native `checked`.** ARIA outranks host state in the accessibility tree, and on the no-JS path this package supports there is nothing to rewrite the attribute after the user ticks the box. `Checkbox` writes only `'mixed'` (an IDL property with no attribute form, so ARIA is the only server-side lever); `Switch` writes none at all, over a `biome-ignore` that says why.
+- **Generated source is a CODE sink.** `build-icons.ts` writes modules every app EXECUTES at import, from data fetched over the network, so an attribute value goes through `JSON.stringify` and never `'${value}'` — and `SAFE_ATTR_VALUE` refuses anything that is not glyph geometry one layer earlier. `iconElements` guards tags and attribute NAMES; it has never guarded a value. Malformed upstream data is `X_UI_INVALID_VALUE`; only the generator's real environment faults (no network, no biome binary) are `X_UI_RUNTIME_MISSING`.
 
 ## Files
 
@@ -46,6 +51,10 @@ Tier 5. Imports `@ultimat3/core`, `schema`, `i18n`, `money`, `time`. Never `http
 | `src/theme/brand.ts` | `defineTheme()` — the ONE brand-override seam; there is no SCSS `@use ... with ()` path |
 | `src/tokens/contrast.ts` | WCAG ratios over the channel tokens; `contrast.test.ts` gates AA in both themes |
 | `src/catalog/` | parses `components/*.tsx` into `CATALOG.md`; `bun run catalog` writes it, `catalog.test.ts` fails on drift |
+| `src/roving.ts` | the pure rules of a keyboard group: navigable set, tab stop, who keeps their own arrows |
+| `src/fake-dom.ts` | TEST-ONLY: a DOM where a disabled control refuses focus. Never exported from `index.ts` |
+| `src/jsx-probe.ts` | TEST-ONLY: a component's node tree, so a test can assert the props and call the handlers an element carries |
+| `src/components/style-classes.test.ts` | the build error behind "every `styles['x']` a component names is declared in its own `.module.scss`" — under `bun test` a `.module.scss` import resolves to the file PATH, so no render can catch a dead class |
 
 ## Assumed peer contracts
 

package/README.md

@@ -61,7 +61,7 @@ Four composites cover the frame of an app screen. Below them are `Container`,
 | `AppShell` | skip link + `header` / `nav` / `main` / `footer` landmarks on a CSS grid | the frame every screen sits in — one per document |
 | `PageHeader` | breadcrumbs, the page's one `h1`, description, actions | the top of a screen |
 | `Section` | a labelled `section` with a real heading and `aria-labelledby` | second-level structure inside a page |
-| `Toolbar` | `role="toolbar"` strip, start + end slots, arrow-key roving | filters and actions above a table or list |
+| `Toolbar` | `role="toolbar"` strip, start + end slots, arrow-key roving between its buttons (`As of 2026-08`) | filters and actions above a table or list |
 
 `AppShell` holds no state: below `md` the sidebar becomes a band above the content,
 and an off-canvas menu is `Drawer` — the one component that already does that.
@@ -262,6 +262,26 @@ renditions and the data-URI blur placeholder are build-pipeline steps
 of this package. The component emits what it is handed and fabricates nothing —
 no variants it was not given, no dimensions it did not measure.
 
+## Keyboard groups
+
+`As of 2026-08`: a roving group — `Menu`, `Tabs`, `Toolbar` — is one Tab stop into a set of
+controls, and arrows move within it. Three rules, all of them in `src/roving.ts` and all of them
+enforced by tests:
+
+| Rule | Why |
+|---|---|
+| a disabled item is in neither the navigable set nor the tab stop (`MENU_ITEM_SELECTOR`, `TAB_SELECTOR`, `tabStopIndex`) | `focus()` on a disabled control is a **no-op**, so a disabled item left in the list pins the reducer on its index and hides everything after it |
+| the tab stop is the selection, or the first **enabled** item (`tabStopIndex`) | a group whose only tab stop is disabled cannot be entered at all |
+| a control that answers arrows itself keeps them (`handlesOwnArrowKeys`) | `Toolbar` exists to hold a search field, and stealing ArrowRight from it eats the keystroke moving the caret |
+
+`Toolbar` is deliberately **not** a single Tab stop: it holds arbitrary children it cannot reach
+into to set an initial `tabindex`, and a search field at its inline start keeps its own arrows —
+one stop there would strand every control past it.
+
+`As of 2026-08`, `ToastRegion` owns the live region, not `Toast`: the `<ol>` carries `aria-live`
+and outlives every message, because a region created with its content already inside it is not announced. One region,
+one politeness — `politeness="assertive"` for a region that carries errors alone.
+
 ## Theme resolution
 
 `explicit choice in localStorage` → `OS preference`. `setTheme()` persists,
@@ -280,7 +300,7 @@ Content-Security-Policy: script-src 'self' 'sha256-…'   # themeInlineScriptCsp
 | `X_TOKEN_UNKNOWN` | a token role the SCSS source does not define — including a `defineTheme()` override of a role, radius or font slot that is not in the scale |
 | `X_THEME_INVALID` | a theme other than `light` / `dark` |
 | `X_UI_RUNTIME_MISSING` | a DOM render with no registered Solid runtime, `<UiProvider>` on the server, or `browserThemeEnv()` off-DOM. A server render with no runtime is **not** one of them — it gets `INERT_SOLID_RUNTIME` |
-| `X_UI_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors or one dimension without the other, a heading level off 1–6, a `defineTheme()` value that is not a token value, an `<Icon>` glyph with a tag/attribute/colour outside `ICON_TAGS`, two `Accordion` items sharing an id, `InfiniteScroll` with `hasMore` and no `nextHref`, or a negative `debounce` window |
+| `X_UI_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors or one dimension without the other, a heading level off 1–6, a `defineTheme()` value that is not a token value, an `<Icon>` glyph with a tag/attribute/colour outside `ICON_TAGS`, two `Accordion` items sharing an id, `InfiniteScroll` with `hasMore` and no `nextHref`, a negative `debounce` window, or (`As of 2026-08`) upstream icon data `bun run icons` refuses (not an object, no renderable nodes, an attribute value that is not glyph geometry) |
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -39,10 +39,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/i18n": "2.0.0",
-    "@ultimat3/money": "2.0.0",
-    "@ultimat3/time": "2.0.0"
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/i18n": "3.0.0",
+    "@ultimat3/money": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/a11y.ts

@@ -2,6 +2,7 @@
 // The decision logic is pure (and tested); only the thin shells touch the DOM.
 
 import type { Direction } from '@ultimat3/i18n';
+import { handlesOwnArrowKeys } from './roving';
 
 export const FOCUSABLE_SELECTOR = [
   'a[href]',
@@ -66,26 +67,46 @@ export interface FocusTrap {
 }
 
 /**
- * Cycles Tab within `root` and restores focus to the previously active element
- * on release — the behaviour Dialog and Drawer both need.
+ * Cycles Tab within `root`, moves focus into it on `activate`, and restores focus to the element
+ * that had it on `release` — what `Menu` and `Popover` need, because a panel unmounted with focus
+ * inside it resets focus to `<body>` and the next Tab restarts at the top of the document.
+ *
+ * The listener sits on `document`, not on `root`: a keydown while focus is OUTSIDE never reaches
+ * `root`, so a trap listening on its own root can never recapture focus that already left — the
+ * branch that pulls it back was unreachable by construction. Every branch still tests
+ * `root.contains`, so the trap only acts while it is the active one.
  */
 export function createFocusTrap(root: HTMLElement): FocusTrap {
   let previous: HTMLElement | null = null;
 
+  /**
+   * The empty-panel fallback, and the reason it needs a line of its own: a plain `<div>` is not
+   * focusable, so `focus()` on it is a no-op that reports nothing — and `Menu` and `Popover` both
+   * hand this trap exactly that. `tabindex="-1"` is the one value that makes an element reachable
+   * programmatically without putting it in the Tab order, so the root never becomes a stop of its
+   * own (`FOCUSABLE_SELECTOR` excludes `-1`). A root that already declares one keeps it.
+   */
+  function focusRoot(): void {
+    if (root.getAttribute('tabindex') === null) root.tabIndex = -1;
+    root.focus();
+  }
+
   function onKeyDown(event: KeyboardEvent): void {
     if (event.key !== 'Tab') return;
     const items = focusableWithin(root);
     if (items.length === 0) {
       event.preventDefault();
+      focusRoot();
       return;
     }
     const first = items[0] as HTMLElement;
     const last = items[items.length - 1] as HTMLElement;
     const active = document.activeElement;
-    if (event.shiftKey && (active === first || !root.contains(active))) {
+    const outside = !root.contains(active);
+    if (event.shiftKey && (outside || active === first)) {
       event.preventDefault();
       last.focus();
-    } else if (!event.shiftKey && active === last) {
+    } else if (!event.shiftKey && (outside || active === last)) {
       event.preventDefault();
       first.focus();
     }
@@ -94,11 +115,13 @@ export function createFocusTrap(root: HTMLElement): FocusTrap {
   return {
     activate() {
       previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
-      root.addEventListener('keydown', onKeyDown);
-      (focusableWithin(root)[0] ?? root).focus();
+      document.addEventListener('keydown', onKeyDown);
+      const first = focusableWithin(root)[0];
+      if (first === undefined) focusRoot();
+      else first.focus();
     },
     release() {
-      root.removeEventListener('keydown', onKeyDown);
+      document.removeEventListener('keydown', onKeyDown);
       previous?.focus();
     },
   };
@@ -151,11 +174,19 @@ export function createRovingTabindex(
   return (event) => {
     const items = getItems();
     const active = document.activeElement;
+    // A control with its own arrow-key behaviour keeps it. A group cannot know whether the caret
+    // in the Input it contains was about to move, so it never guesses — it declines.
+    if (handlesOwnArrowKeys(active)) return;
     // Focus may sit on nothing, on `<body>`, or on a non-HTML element (an SVG child): none of
     // those are in `items`, and all of them mean "start from the first item".
     const current = active instanceof HTMLElement ? items.indexOf(active) : -1;
-    const next = nextRovingIndex(Math.max(current, 0), event.key, items.length, options);
-    if (next === current || next < 0) return;
+    const start = Math.max(current, 0);
+    const next = nextRovingIndex(start, event.key, items.length, options);
+    // Compared against `start`, the value the reducer was actually given — not the unclamped
+    // `current`. A key the reducer does not navigate answers its own input, so comparing against
+    // `-1` made every such key (Tab included) look like a move and steal focus out of whatever
+    // held it whenever the active element was not one of the group's items.
+    if (next === start || next < 0) return;
     event.preventDefault();
     for (const [index, item] of items.entries()) {
       item.tabIndex = index === next ? 0 : -1;

package/src/components/Checkbox.tsx

@@ -13,7 +13,7 @@ export interface CheckboxProps {
   name?: string | undefined;
   value?: string | undefined;
   checked?: boolean | undefined;
-  /** Tri-state for "some children selected". Mirrored to `aria-checked`. */
+  /** Tri-state for "some children selected". The ONLY thing mirrored to `aria-checked`. */
   indeterminate?: boolean | undefined;
   disabled?: boolean | undefined;
   required?: boolean | undefined;
@@ -36,7 +36,12 @@ export function Checkbox(props: CheckboxProps): JSX.Element {
         checked={props.checked === true}
         disabled={props.disabled === true}
         required={props.required === true}
-        aria-checked={props.indeterminate === true ? 'mixed' : ariaBool(props.checked === true)}
+        // Only "mixed" is set here. `indeterminate` is an IDL property with no attribute form, so
+        // ARIA is the sole server-side lever for it — whereas a plain checked/unchecked box already
+        // maps from the native `checked` state, and an `aria-checked` mirroring it would FREEZE the
+        // announced state: on the no-JS path a user ticks the box, the native state changes, the
+        // attribute does not, and ARIA wins in the accessibility tree.
+        aria-checked={props.indeterminate === true ? 'mixed' : undefined}
         aria-describedby={props['aria-describedby']}
         aria-invalid={ariaBool(props['aria-invalid'])}
         onChange={props.onChange}

package/src/components/Dialog.tsx

@@ -1,6 +1,7 @@
-// Modal built on native <dialog>: the platform gives us the top layer, the
-// backdrop, inert background content, and Escape-to-close for free. We add the
-// labelled heading, the close affordance, and body scroll locking.
+// Modal built on native <dialog>: the platform gives us the top layer, the backdrop, inert
+// background content, and Escape-to-close for free. We add the labelled heading and the close
+// affordance. Body scroll locking is one CSS rule in `tokens/reset.scss` (`html:has(dialog:modal)`)
+// rather than anything here, so it covers Drawer too and cannot leak when a close path throws.
 
 import type { JSX } from 'solid-js';
 import { useId } from '../a11y';

package/src/components/Dropzone.tsx

@@ -12,7 +12,7 @@ import { useUi } from '../theme/context';
 import { solid } from '../theme/solid-adapter';
 import styles from './Dropzone.module.scss';
 import type { FileSelection } from './file-input-view';
-import { progressPercent, selectFiles } from './file-input-view';
+import { adoptDroppedFiles, progressPercent, selectFiles } from './file-input-view';
 
 export interface DropzoneProps {
   /** Already-translated instruction. Required — it is the control's accessible name. */
@@ -45,6 +45,7 @@ export function Dropzone(props: DropzoneProps): JSX.Element {
   const rt = solid();
   const [over, setOver] = rt.createSignal(false);
   const fallbackId = useId('dropzone');
+  let input: HTMLInputElement | undefined;
   const inputId = (): string => props.id ?? fallbackId;
   const percent = (): number => progressPercent(props.progress ?? 0);
 
@@ -72,12 +73,19 @@ export function Dropzone(props: DropzoneProps): JSX.Element {
       onDrop={(event: DragEvent) => {
         event.preventDefault();
         setOver(false);
-        if (props.disabled !== true) offer(event.dataTransfer?.files);
+        if (props.disabled === true) return;
+        // The input first, then the callback: a drop that only reaches `onSelect` leaves the real
+        // control empty, and the form the label sits in submits nothing.
+        adoptDroppedFiles(input, event.dataTransfer?.files);
+        offer(event.dataTransfer?.files);
       }}
     >
       <span class={styles['label']}>{props.label}</span>
       {props.hint === undefined ? null : <span class={styles['hint']}>{props.hint}</span>}
       <input
+        ref={(el: HTMLInputElement) => {
+          input = el;
+        }}
         class={styles['input']}
         type="file"
         id={inputId()}

package/src/components/Field.tsx

@@ -52,13 +52,7 @@ export function Field(props: FieldProps): JSX.Element {
   });
 
   return (
-    <div
-      class={cx(
-        styles['field'],
-        props.error === undefined ? undefined : styles['invalid'],
-        props.class,
-      )}
-    >
+    <div class={cx(styles['field'], props.class)}>
       <label class={styles['label']} for={id}>
         {props.label}
         {props.required === true ? (

package/src/components/Form.tsx

@@ -1,9 +1,11 @@
-// Form shell. Owns the one thing every form needs and always forgets: a
-// top-of-form error summary that is focusable and announced on submit.
+// Form shell. Owns the one thing every form needs and always forgets: a top-of-form error summary
+// that is announced (the Alert inside it is a live region) and that TAKES focus when an error
+// arrives — the focus move is what makes the summary reachable at all, since its id is internal.
 
 import type { JSX } from 'solid-js';
 import { useId } from '../a11y';
 import { cx } from '../cx';
+import { solid } from '../theme/solid-adapter';
 import { Alert } from './Alert';
 import styles from './Form.module.scss';
 import type { SpaceStep } from './variants';
@@ -25,7 +27,17 @@ export interface FormProps {
 }
 
 export function Form(props: FormProps): JSX.Element {
+  const rt = solid();
   const summaryId = useId('form-error');
+  let summary: HTMLDivElement | undefined;
+
+  // `tabindex="-1"` alone was a focus target nothing ever aimed at: `summaryId` is internal, so no
+  // caller could move focus here, and the component never did either. A failed submit that leaves
+  // focus on the button leaves a keyboard user to hunt for what went wrong.
+  rt.createEffect(() => {
+    if (props.error !== undefined) summary?.focus();
+  });
+
   return (
     <form
       class={cx(styles['form'], props.class)}
@@ -38,7 +50,14 @@ export function Form(props: FormProps): JSX.Element {
       onSubmit={props.onSubmit}
     >
       {props.error === undefined ? null : (
-        <div id={summaryId} tabindex="-1" class={styles['summary']}>
+        <div
+          ref={(el: HTMLDivElement) => {
+            summary = el;
+          }}
+          id={summaryId}
+          tabindex="-1"
+          class={styles['summary']}
+        >
           <Alert tone="danger" title={props.errorTitle}>
             {props.error}
           </Alert>

package/src/components/Menu.tsx

@@ -2,8 +2,9 @@
 // Distinct from Select — a menu runs commands, it does not hold a form value.
 
 import type { JSX } from 'solid-js';
-import { createRovingTabindex, useId } from '../a11y';
+import { createFocusTrap, createRovingTabindex, useId } from '../a11y';
 import { cx } from '../cx';
+import { MENU_ITEM_SELECTOR, tabStopIndex } from '../roving';
 import { useUi } from '../theme/context';
 import { solid } from '../theme/solid-adapter';
 import styles from './Menu.module.scss';
@@ -42,11 +43,14 @@ export function Menu(props: MenuProps): JSX.Element {
   let root: HTMLDivElement | undefined;
   let list: HTMLDivElement | undefined;
 
+  // Disabled items are excluded from BOTH answers — the list arrows walk and the one item that
+  // carries the tab stop — because `focus()` on a disabled button silently does nothing.
   const onKeyDown = createRovingTabindex(
     () =>
-      list === undefined ? [] : Array.from(list.querySelectorAll<HTMLElement>('[role="menuitem"]')),
+      list === undefined ? [] : Array.from(list.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR)),
     { orientation: 'vertical', dir: ui.dir },
   );
+  const tabStop = (): number => tabStopIndex(props.items);
 
   rt.createEffect(() => {
     if (!props.open || typeof document === 'undefined') return;
@@ -58,9 +62,15 @@ export function Menu(props: MenuProps): JSX.Element {
     };
     document.addEventListener('pointerdown', onPointerDown, true);
     document.addEventListener('keydown', onEscape);
+    // Closing unmounts the panel with focus inside it, which resets focus to <body> and makes the
+    // next Tab restart at the top of the document. The trap moves focus in on open and hands it
+    // back to the trigger on close, so Escape returns the user where they were.
+    const trap = list === undefined ? undefined : createFocusTrap(list);
+    trap?.activate();
     rt.onCleanup(() => {
       document.removeEventListener('pointerdown', onPointerDown, true);
       document.removeEventListener('keydown', onEscape);
+      trap?.release();
     });
   });
 
@@ -93,7 +103,7 @@ export function Menu(props: MenuProps): JSX.Element {
               type="button"
               role="menuitem"
               class={cx(styles['item'], item.destructive === true && styles['destructive'])}
-              tabindex={index === 0 ? 0 : -1}
+              tabindex={index === tabStop() ? 0 : -1}
               disabled={item.disabled === true}
               onClick={() => {
                 item.onSelect();

package/src/components/Pagination.tsx

@@ -27,7 +27,14 @@ export function Pagination(props: PaginationProps): JSX.Element {
   const ui = useUi();
   const previous = (): string => props.labelPrevious ?? ui.t(UI_KEYS.previous);
   const next = (): string => props.labelNext ?? ui.t(UI_KEYS.next);
-  const cursorMode = (): boolean => props.page === undefined || props.totalPages === undefined;
+  // A cursor present means cursor mode, exactly as `page`'s own doc says. The inverted form —
+  // "cursor mode when a number is MISSING" — silently dropped the cursor and paged by number the
+  // moment a caller passed both, which is the shape a list that knows its total naturally has.
+  const cursorMode = (): boolean =>
+    props.nextCursor !== undefined ||
+    props.prevCursor !== undefined ||
+    props.page === undefined ||
+    props.totalPages === undefined;
 
   return (
     <nav class={cx(styles['pagination'], props.class)} aria-label={ui.t(UI_KEYS.page)}>

package/src/components/Popover.tsx

@@ -3,7 +3,7 @@
 // flips sides automatically under `dir="rtl"`.
 
 import type { JSX } from 'solid-js';
-import { useId } from '../a11y';
+import { createFocusTrap, useId } from '../a11y';
 import { cx } from '../cx';
 import { solid } from '../theme/solid-adapter';
 import styles from './Popover.module.scss';
@@ -32,6 +32,7 @@ export function Popover(props: PopoverProps): JSX.Element {
   const panelId = useId('popover');
   const triggerId = `${panelId}-trigger`;
   let root: HTMLDivElement | undefined;
+  let panel: HTMLDivElement | undefined;
 
   rt.createEffect(() => {
     if (!props.open || typeof document === 'undefined') return;
@@ -43,9 +44,15 @@ export function Popover(props: PopoverProps): JSX.Element {
     };
     document.addEventListener('pointerdown', onPointerDown, true);
     document.addEventListener('keydown', onKeyDown);
+    // Closing unmounts the panel with focus inside it, which drops focus to <body> and makes the
+    // next Tab restart at the top of the document. The trap moves focus into the panel on open and
+    // hands it back to the trigger on close.
+    const trap = panel === undefined ? undefined : createFocusTrap(panel);
+    trap?.activate();
     rt.onCleanup(() => {
       document.removeEventListener('pointerdown', onPointerDown, true);
       document.removeEventListener('keydown', onKeyDown);
+      trap?.release();
     });
   });
 
@@ -59,6 +66,9 @@ export function Popover(props: PopoverProps): JSX.Element {
       {props.trigger({ id: triggerId, 'aria-expanded': props.open, 'aria-controls': panelId })}
       {props.open ? (
         <div
+          ref={(el: HTMLDivElement) => {
+            panel = el;
+          }}
           id={panelId}
           role="dialog"
           aria-label={props.label}

package/src/components/Select.tsx

@@ -38,8 +38,11 @@ export interface SelectProps {
  * is also what keeps an unset field unsubmittable: that option is `disabled`.
  */
 export function Select(props: SelectProps): JSX.Element {
-  const current = props.value ?? '';
-  const matched = props.options.some((option) => option.value === current);
+  // Thunks, not setup-time reads: a prop read once at setup never tracks, so under a client Solid
+  // runtime the selection would freeze at whatever the first render saw (ThemeToggle already feeds
+  // this a signal). Every other value-formatting component in the package wraps its read the same way.
+  const current = (): string => props.value ?? '';
+  const matched = (): boolean => props.options.some((option) => option.value === current());
   return (
     <span class={cx(styles['wrap'], styles[`size-${props.size ?? 'md'}`], props.class)}>
       <select
@@ -54,7 +57,7 @@ export function Select(props: SelectProps): JSX.Element {
         onChange={props.onChange}
       >
         {props.placeholder === undefined ? null : (
-          <option value="" disabled selected={!matched}>
+          <option value="" disabled selected={!matched()}>
             {props.placeholder}
           </option>
         )}
@@ -62,7 +65,7 @@ export function Select(props: SelectProps): JSX.Element {
           <option
             value={option.value}
             disabled={option.disabled === true}
-            selected={option.value === current}
+            selected={option.value === current()}
           >
             {option.label}
           </option>

package/src/components/Switch.tsx

@@ -1,8 +1,10 @@
-// Boolean toggle with immediate effect (as opposed to Checkbox, which is part of
-// a form submit). `role="switch"` on a native checkbox keeps keyboard behaviour.
+// Boolean toggle with immediate effect (as opposed to Checkbox, which is part of a form submit).
+// `role="switch"` on a native checkbox keeps keyboard behaviour — and its checked state, which is
+// why nothing here writes `aria-checked`: `role="switch"` maps the host `checked` state on its own,
+// and an attribute mirroring it never updates on the no-JS path, where ARIA would then outrank the
+// truth and announce the switch stuck in whichever position it was rendered in.
 
 import type { JSX } from 'solid-js';
-import { ariaBool } from '../a11y';
 import { cx } from '../cx';
 import styles from './Switch.module.scss';
 
@@ -26,12 +28,17 @@ export function Switch(props: SwitchProps): JSX.Element {
       <input
         class={styles['input']}
         type="checkbox"
+        // The rule reads ARIA alone; this element's state comes from the HOST language. Applying
+        // `role="switch"` to a native checkbox is the recommended technique precisely because the
+        // browser maps the element's own checkedness onto it — and an `aria-checked` mirroring
+        // `props.checked` is WORSE than absent: on the no-JS path nothing rewrites it after the
+        // user toggles the box, and ARIA outranks host state in the accessibility tree.
+        // biome-ignore lint/a11y/useAriaPropsForRole: native checkedness supplies the state
         role="switch"
         id={props.id}
         name={props.name}
         checked={props.checked === true}
         disabled={props.disabled === true}
-        aria-checked={ariaBool(props.checked === true)}
         aria-describedby={props['aria-describedby']}
         onChange={props.onChange}
       />

package/src/components/Table.tsx

@@ -21,9 +21,11 @@ export interface TableProps {
 
 export function Table(props: TableProps): JSX.Element {
   return (
-    // tabindex makes the scroll region keyboard-reachable, which is required
-    // whenever a scrollable element has no focusable children.
-    <section class={cx(styles['scroller'], props.class)} tabindex="0" aria-label={props.caption}>
+    // tabindex makes the scroll region keyboard-reachable, which is required whenever a scrollable
+    // element has no focusable children. No `aria-label`: it would OVERRIDE the <caption> as the
+    // accessible name rather than add to it, naming the scroll box the same thing as the table
+    // inside it — and a <section> with no name is generic, so the table keeps its own caption.
+    <section class={cx(styles['scroller'], props.class)} tabindex="0">
       <table
         class={cx(
           styles['table'],