@handamade/psi-react 0.19.0 → 0.21.0

package/docs/MenuItem.md

@@ -45,5 +45,5 @@ This component has no `--psi-menu-item-*` tokens — its styling binds scale tok
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/MenuSeparator.md

@@ -32,5 +32,5 @@ This component has no `--psi-menu-separator-*` tokens — its styling binds scal
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/NavBar.md

@@ -9,7 +9,9 @@ Top navigation bar with brand, nav-link, and trailing-action slots.
 |---|---|---|---|---|
 | `brand` | `ReactNode` | — | no | Brand slot (wordmark / logo link), leading edge. |
 | `actions` | `ReactNode` | — | no | Trailing actions slot (theme switch, CTA). |
-| `children` | `ReactNode` | — | no | Nav links. |
+| `children` | `ReactNode` | — | no | Nav links. The `<nav>` renders only when there are children, so a bar with a brand and actions and no links has no empty landmark (D88). |
+| `navLabel` | `string` | — | no | Accessible name of the links' `<nav>` (its `aria-label`). Rest props land on the `<header>`, so this is the only way to label the `<nav>` (D88). |
+| `fluid` | `boolean` | false | no | Lay the row out at full width: it drops `psi-container` (the centred max-width column) and keeps the `--psi-gutter` side padding. For an application header over a full-width frame (D88). |
 | `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the header element. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
 
@@ -28,5 +30,5 @@ Override `--psi-navbar-*` custom properties at any scope; interactive states der
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/NavGroup.md

@@ -0,0 +1,40 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# NavGroup
+
+A collapsible group of `NavItem`s in a `NavTree` (D88). Controlled-only, like `Tabs` (D67): `open` and `onOpenChange` are required and nothing is remembered. Renders a native `<button aria-expanded aria-controls>` over a `<ul>` that is `hidden` when closed, so the items leave the layout and the accessibility tree while `aria-controls` keeps naming an element. The chevron turns with the state and is `aria-hidden`: the label and `aria-expanded` carry the meaning.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `label` | `ReactNode` | — | yes | The group's visible label, such as "Reports". |
+| `open` | `boolean` | — | yes | Whether the group's items are shown. Controlled. |
+| `onOpenChange` | `(open: boolean) => void` | — | yes | Called with the next state when the button is pressed. The group never changes `open` itself. |
+| `children` | `ReactNode` | — | yes | `NavItem`s of the group. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Enter / Space | Activates the group's native button, which asks the parent to open or close the group through onOpenChange. |
+
+Controlled-only: open and onOpenChange are required and the group never changes its own state. Renders a <button type="button"> with aria-expanded and aria-controls naming its <ul>, which carries `hidden` when closed, so the links leave the layout and the accessibility tree while aria-controls still resolves. The chevron is aria-hidden and turns on a duration token; the label and aria-expanded carry the meaning.
+
+## Theming
+
+Override `--psi-nav-tree-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/NavItem.md

@@ -0,0 +1,40 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# NavItem
+
+One entry of a `NavTree` (D88): an `<li>` that styles the single anchor inside it. Router apps pass their own link as the child, so it keeps its `href`, `aria-current` and handlers; `href` is for plain links and for presets, where the compose tree can hold only manifest components and a raw `<a>` is not one. The current page is never marked by colour alone: medium weight, a raised surface and a bar at the inline start.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `children` | `ReactNode` | — | yes | Without `href`: one anchor, your router's link — put `aria-current="page"` on the current one. With `href`: the link's text. |
+| `href` | `string` | — | no | Render the anchor yourself (D88), for a plain link or a preset: the `<li>` holds `<a href>` with `children` as its text. Router apps leave it out and pass their own link as the child, so the link keeps its own handlers. |
+| `current` | `boolean` | — | no | Mark the link as the current page (`aria-current="page"`). Only with `href`; a link you pass as a child carries its own `aria-current`. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLLIElement>` | — | no | Forwarded ref to the `<li>`. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Enter | Follows the link inside it (native anchor behavior); the link is the consumer's router link. |
+
+An <li> that styles the one anchor inside it. Router apps pass their own link as the child and set aria-current="page" on the current one; with href the NavItem renders the anchor itself (for plain links and presets) and current sets aria-current="page" on it. The current page is marked by weight, a raised surface and an inline-start bar, never by colour alone, and the focus ring is drawn inset on the anchor.
+
+## Theming
+
+Override `--psi-nav-tree-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/NavTree.md

@@ -0,0 +1,39 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# NavTree
+
+A navigation tree (D88): a `<nav aria-label>` around a `<ul>` of `NavItem`s and `NavGroup`s. Native elements only — *Tab* moves through the group buttons and the links of open groups; there is no roving focus and no `role="menu"` or `role="tree"`, because site navigation is a list of links, not a widget. Router-agnostic: pass your router's link inside each `NavItem`, with `aria-current="page"` on the current one.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `aria-label` | `string` | — | yes | Accessible name of the navigation landmark, such as "Main". Required: an app has more than one `<nav>` (a header's, a sidebar's), and an unnamed one is indistinguishable from the rest. Declared here rather than inherited so docgen keeps it in the manifest (D60). |
+| `children` | `ReactNode` | — | yes | `NavItem`s and `NavGroup`s — each renders an `<li>`. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the `<nav>`. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab / Shift+Tab | Moves through the group buttons and the links of open groups in document order. There is no roving focus and no arrow-key model: it is a list of links, not a menu or a tree widget. |
+
+A native <nav> around a <ul>, named by the required aria-label (an app has more than one navigation landmark). No role="menu" or role="tree" is used (D88). Router-agnostic: the consumer passes its router's link inside each NavItem.
+
+## Theming
+
+Override `--psi-nav-tree-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Pagination.md

@@ -29,5 +29,5 @@ This component has no `--psi-pagination-*` tokens — its styling binds scale to
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Panel.md

@@ -35,5 +35,5 @@ Override `--psi-panel-*` custom properties at any scope.
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Select.md

@@ -37,5 +37,5 @@ Override `--psi-select-*` custom properties at any scope; interactive states der
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Skeleton.md

@@ -0,0 +1,50 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# Skeleton
+
+A loading placeholder. It is not a live region: it renders no `role` and no `aria-live`, and it is always `aria-hidden="true"`, so assistive tech skips it entirely. Put `aria-busy` on the region the skeleton stands for — that is what tells a screen reader the content is coming. Its width fills the container; size the container, not the skeleton. The pulse is an opacity animation that stops under `prefers-reduced-motion: reduce` (D86).
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `variant` | `"text" \| "block"` | text | no | `text` renders `lines` stacked bars; `block` one box. |
+| `lines` | `number` | 1 | no | Number of text lines; the last of several is shorter. Text only. |
+| `size` | `24 \| 32 \| 40 \| 48` | 40 | no | Height of a block, from the size scale. Block only. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the underlying `<div>`. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+
+
+Not a live region: it renders no role and no aria-live, and it is always aria-hidden="true", so assistive tech skips it entirely. Put aria-busy="true" on the region the skeleton stands for (a table body, a card, a list) and remove it when the content arrives; that, not the skeleton, is what tells a screen reader the content is loading. Not focusable. The pulse is an opacity animation that stops under prefers-reduced-motion: reduce, because zeroing the duration of an infinite alternating animation flickers instead of stopping (D86).
+
+## Theming
+
+Override `--psi-skeleton-*` custom properties at any scope.
+
+## Variant guidance
+
+- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.
+- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.
+- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.
+- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.
+- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.
+- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.
+- **danger** — Destructive action. Delete, remove, disconnect.
+- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.
+- **success | warning** — Status communication (Tag only). Status badges, labels.
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/SkipLink.md

@@ -0,0 +1,40 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# SkipLink
+
+A link to the page's main content, invisible until it takes keyboard focus and then fixed at the inline-start top corner on a surface, drawing the shared focus ring (D88). Render it first in the document. No script: native fragment navigation moves focus to a target that is focusable, so the next *Tab* continues from inside it. `AppShell`'s `main` is one (`tabIndex={-1}`); a bare `<main>` is not, so give it one. A modal `Dialog` makes the rest of the document inert, so the link never needs to beat one. A `ToastRegion` is on the native top layer, which paints above everything whatever its `z-index`: do not place one at `top-start` (its default is `bottom-end`) in an app with a skip link, or it covers the focused link.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `href` | `string` | — | yes | Fragment of the element to skip to, such as `"#main"`. The target must be focusable (`tabIndex={-1}` is enough), or focus does not move. |
+| `children` | `ReactNode` | — | yes | Visible text, such as "Skip to content". |
+| `ref` | `Ref<HTMLAnchorElement>` | — | no | Forwarded ref to the anchor. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab | Takes focus and becomes visible at the inline-start top corner, drawing the shared focus ring. Put it first in the document so it is the first tab stop. |
+| Enter | Follows the fragment href: focus moves to the target, and the next Tab continues from inside it. |
+
+A native anchor, visually hidden until it is focused (:focus-visible) and with no script (D88). Fragment navigation moves focus only to a focusable target, so the element named by href must be focusable: tabIndex={-1} is enough, and AppShell's main has it. A modal Dialog makes the link inert, so it never needs to beat one. A ToastRegion is on the native top layer and paints over the focused link whatever its z-index: do not place one at top-start in an app with a skip link.
+
+## Theming
+
+Override `--psi-skip-link-*` custom properties at any scope.
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Switch.md

@@ -33,5 +33,5 @@ Override `--psi-switch-*` custom properties at any scope.
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Tab.md

@@ -36,5 +36,5 @@ This component has no `--psi-tab-*` tokens — its styling binds scale tokens on
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TabList.md

@@ -37,5 +37,5 @@ This component has no `--psi-tab-list-*` tokens — its styling binds scale toke
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TabPanel.md

@@ -35,5 +35,5 @@ This component has no `--psi-tab-panel-*` tokens — its styling binds scale tok
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Table.md

@@ -34,5 +34,5 @@ Override `--psi-table-*` custom properties at any scope; interactive states deri
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableBody.md

@@ -1,7 +1,7 @@
 <!-- Generated by emit-docs.ts — do not edit. -->
 # TableBody
 
-`<tbody>` wrapper.
+`<tbody>` wrapper. Remaining attributes land on it (D85) — `aria-busy` while a page of rows loads, say.
 
 ## Props
 
@@ -9,6 +9,7 @@
 |---|---|---|---|---|
 | `children` | `ReactNode` | — | yes | The body TableRows. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableSectionElement>` | — | no | Forwarded ref to the `<tbody>`. |
 
 ## Theming
 
@@ -25,5 +26,5 @@ This component has no `--psi-table-body-*` tokens — its styling binds scale to
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableCaption.md

@@ -0,0 +1,39 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# TableCaption
+
+`<caption>` — the table's name, above it, and an optional detail line (D85). It names the table for assistive tech, which an `aria-label` on the `Table` would also do, but a caption is visible. A token-paged list has no page numbers to land on, so after a page change the consumer moves focus here: give it `tabIndex={-1}`, put the range in `detail`, and call `focus()` on the ref. The ring is the shared one (D82), drawn inside the caption's box. Remaining attributes land on the element.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `children` | `ReactNode` | — | yes | The name line — what the table lists. Also the table's accessible name. |
+| `detail` | `ReactNode` | — | no | An optional second line: the range shown, say — "Rows 51–100 of more than 100,000". |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableCaptionElement>` | — | no | Forwarded ref to the `<caption>`, so focus can be moved to it. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab | Not a tab stop. With tabIndex={-1} the consumer moves focus to it after a page change, and the shared ring is drawn inside the caption. |
+
+Renders <caption>, which names the table for assistive tech and is visible, unlike an aria-label on Table. Put the range in `detail` ("Rows 51–100 of more than 100,000") so that moving focus to the caption after a token-paged page change reads the new range (D85). Remaining attributes land on the element.
+
+## Theming
+
+This component has no `--psi-table-caption-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableCell.md

@@ -1,15 +1,18 @@
 <!-- Generated by emit-docs.ts — do not edit. -->
 # TableCell
 
-`<td>`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose.
+`<td>`, or `<th scope="row">` with `rowHeader`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose. Remaining attributes land on the cell (D85).
 
 ## Props
 
 | Prop | Type | Default | Required | Description |
 |---|---|---|---|---|
 | `numeric` | `boolean` | — | no | Right-aligns and renders tabular figures (D62). |
+| `colSpan` | `number` | — | no | Columns the cell spans — an empty-state row spanning the table (D85). |
+| `rowHeader` | `boolean` | — | no | Renders `<th scope="row">` instead of `<td>`: the cell that names its row, an identifier say, so a screen reader reads it with every cell in the row (D85). Styled as a cell, at medium weight. |
 | `children` | `ReactNode` | — | no | Cell content. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableCellElement>` | — | no | Forwarded ref to the cell element. |
 
 ## Theming
 
@@ -26,5 +29,5 @@ This component has no `--psi-table-cell-*` tokens — its styling binds scale to
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableHead.md

@@ -9,6 +9,7 @@
 |---|---|---|---|---|
 | `children` | `ReactNode` | — | yes | The header TableRow. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableSectionElement>` | — | no | Forwarded ref to the `<thead>`. |
 
 ## Theming
 
@@ -25,5 +26,5 @@ This component has no `--psi-table-head-*` tokens — its styling binds scale to
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableHeaderCell.md

@@ -11,6 +11,7 @@
 | `numeric` | `boolean` | — | no | Right-aligns and renders tabular figures (D62). |
 | `children` | `ReactNode` | — | no | Header label. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableCellElement>` | — | no | Forwarded ref to the `<th>`. |
 
 ## Theming
 
@@ -27,5 +28,5 @@ This component has no `--psi-table-header-cell-*` tokens — its styling binds s
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableRow.md

@@ -11,6 +11,7 @@
 | `selectLabel` | `string` | — | no | Accessible name for this row's selection checkbox. |
 | `children` | `ReactNode` | — | yes | The row's cells. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableRowElement>` | — | no | Forwarded ref to the `<tr>`. |
 
 ## Theming
 
@@ -27,5 +28,5 @@ This component has no `--psi-table-row-*` tokens — its styling binds scale tok
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Tabs.md

@@ -37,5 +37,5 @@ Override `--psi-tabs-*` custom properties at any scope; interactive states deriv
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Tag.md

@@ -47,5 +47,5 @@ Override `--psi-tag-*` custom properties at any scope.
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Toast.md

@@ -1,7 +1,7 @@
 <!-- Generated by emit-docs.ts — do not edit. -->
 # Toast
 
-A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.
+A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. `politeness` (D83) only tells the region which wrapper to use. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.
 
 ## Props
 
@@ -11,6 +11,8 @@ A single transient notification card (D64). Controlled and presentational: it ho
 | `children` | `ReactNode` | — | yes | The message. |
 | `action` | `ReactNode` | — | no | Trailing affordance — a ghost Button (Undo, Retry, View). |
 | `onDismiss` | `(() => void)` | — | no | When provided, renders the dismiss button and calls this. Toast does not remove itself; the owner disposes. |
+| `politeness` | `"polite" \| "assertive"` | — | no | Which live wrapper ToastRegion routes this toast into (D83). Unset, the variant decides: neutral and success are polite, warning and danger assertive. Set it when the kind of event, not its tone, decides — the outcome of the user's own action may interrupt even when it succeeded. |
+| `statusLabel` | `string \| null` | — | no | The visually hidden status word (D83). A string replaces the default ("Success:", "Warning:", "Error:") — pass the translated word; `null` drops it. Unset keeps the default, and `neutral` has none. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
 | `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the underlying `<div>`. |
 
@@ -21,7 +23,7 @@ A single transient notification card (D64). Controlled and presentational: it ho
 | Tab | Reaches the action and the dismiss button in DOM order. Esc is not a dismissal — a toast is not modal and traps nothing. |
 | Enter / Space | Activates the focused action or dismiss button. |
 
-Presentational and controlled (D64): onDismiss reports and the owner disposes; Toast never removes itself. It carries no role/aria-live of its own — politeness belongs to ToastRegion's two persistent wrappers. The variant's meaning is announced by a visually hidden status word ("Success:", "Warning:", "Error:"), never by colour and icon shape alone; the icon is aria-hidden. neutral has no status and gets no prefix. The dismiss button requires no props — it is labelled "Dismiss notification".
+Presentational and controlled (D64): onDismiss reports and the owner disposes; Toast never removes itself. It carries no role/aria-live of its own — politeness belongs to ToastRegion's two persistent wrappers. The variant's meaning is announced by a visually hidden status word ("Success:", "Warning:", "Error:"), never by colour and icon shape alone; the icon is aria-hidden. neutral has no status and gets no prefix. statusLabel replaces that word with a translated one, or drops it with null (D83). politeness tells ToastRegion which wrapper speaks the toast; unset, the variant decides. The dismiss button requires no props — it is labelled "Dismiss notification".
 
 ## Theming
 
@@ -48,5 +50,5 @@ Override `--psi-toast-*` custom properties at any scope.
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/ToastProvider.md

@@ -36,5 +36,5 @@ This component has no `--psi-toast-provider-*` tokens — its styling binds scal
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/ToastRegion.md

@@ -1,7 +1,7 @@
 <!-- Generated by emit-docs.ts — do not edit. -->
 # ToastRegion
 
-The positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover="manual"`, not `"auto"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `variant` off each child, the same Children.map technique Table uses for select-all injection. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group.
+The positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover="manual"`, not `"auto"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `politeness`, then `variant`, off each child — the same Children.map technique Table uses for select-all injection. `politeness` wins (D83): the owner of an announcement knows what kind of event it is, and tone is only the default. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group. Remaining HTML attributes, `data-*` included, are spread onto the root element (D83). That is how an application marks the region `data-react-aria-top-layer`, so that a React Aria overlay — which hides everything outside itself with `aria-hidden` — leaves the two live regions exposed. The region's own attributes always win.
 
 ## Props
 
@@ -9,7 +9,7 @@ The positioned live region that holds the toast stack (D64). Two things here are
 |---|---|---|---|---|
 | `placement` | `"top-start" \| "top-end" \| "bottom-start" \| "bottom-end"` | bottom-end | no | Corner the stack occupies. |
 | `aria-label` | `string` | Notifications | no | Accessible name for the region. |
-| `children` | `ReactNode` | — | yes | The toast stack — `Toast` elements, routed to a live wrapper by variant. |
+| `children` | `ReactNode` | — | yes | The stack — `Toast` and `Announcement` elements, each routed to a live wrapper by its `politeness`, or by a Toast's variant when it names none. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
 | `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the region element. |
 
@@ -19,7 +19,7 @@ The positioned live region that holds the toast stack (D64). Two things here are
 |---|---|
 | Tab | Moves into the stacked toasts' controls in DOM order; the region itself is not focusable. |
 
-Renders two always-present live wrappers — role="status"/aria-live="polite" and role="alert"/aria-live="assertive" — and routes each toast into one by variant (neutral/success polite, warning/danger assertive). Both stay in the DOM when the queue is empty: a live region announces mutations to a subtree that already existed, so a wrapper mounting with its first toast would leave that toast unannounced. Sits on the native top layer via popover="manual", so a toast raised from inside a modal Dialog is still painted above the backdrop and still announced — though showModal() makes everything outside the dialog inert, so it cannot be clicked until the dialog closes; manual (not auto) means no light dismiss, so the click that raised the toast cannot close it. The region is click-through (pointer-events: none) and each toast takes its own clicks back.
+Renders two always-present live wrappers — role="status"/aria-live="polite" and role="alert"/aria-live="assertive" — and routes each child into one. A Toast or an Announcement that names its politeness goes where it says (D83); a Toast that names none is routed by variant (neutral/success polite, warning/danger assertive). Whatever it holds, the region contains exactly two live regions. Remaining HTML attributes, data-* included, land on the root element, so it can be marked data-react-aria-top-layer and stay exposed while a React Aria overlay is open. Both stay in the DOM when the queue is empty: a live region announces mutations to a subtree that already existed, so a wrapper mounting with its first toast would leave that toast unannounced. Sits on the native top layer via popover="manual", so a toast raised from inside a modal Dialog is still painted above the backdrop and still announced — though showModal() makes everything outside the dialog inert, so it cannot be clicked until the dialog closes; manual (not auto) means no light dismiss, so the click that raised the toast cannot close it. The region is click-through (pointer-events: none) and each toast takes its own clicks back.
 
 ## Theming
 
@@ -36,5 +36,5 @@ This component has no `--psi-toast-region-*` tokens — its styling binds scale
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="end" of Fields (D87).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.