@godxjp/ui 32.2.2 → 32.3.0

package/README.md

@@ -18,7 +18,7 @@ npm i @godxjp/ui
 
 <!-- agent-catalog-counts:start -->
 
-The catalog — 161 components, 2193 tokens, 43 cardinal rules — is published in two forms from one
+The catalog — 161 components, 2195 tokens, 43 cardinal rules — is published in two forms from one
 source. **Entry point for either: [`AGENTS.md`](AGENTS.md).**
 <!-- agent-catalog-counts:end -->
 
@@ -55,7 +55,7 @@ static files straight from this public repo — no hosting, no deploy step:
 | [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 47 KB | all 161 as name + group + tagline — **fetch this first** |
 | [`agent/components/<Name>.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json) | 1 KB–37 KB | one file per component, each with its `importPath` — **this is the route to take** |
 | [`agent/components.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json) | 1.2 MB | all 161 entries in one file — most URL fetchers truncate this silently; prefer the per-component files |
-| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 845 KB | all 2193 design tokens, their values and why they exist |
+| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 846 KB | all 2195 design tokens, their values and why they exist |
 | [`agent/vocabulary.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json) | 7 KB | the controlled prop vocabulary |
 | [`agent/rules.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json) | 21 KB | the 43 cardinal rules |
 <!-- prettier-ignore-end -->

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 32.2.2.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 32.3.0.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.
@@ -56,10 +56,10 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 43 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2193 design tokens, each tagged with its `tier`. **If you were handed a
+4. `tokens.json` — 2195 design tokens, each tagged with its `tier`. **If you were handed a
    brand, read the 211 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1870 `component` entries are per-part knobs; reach for one only when a role is
+   1872 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 26 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
@@ -145,7 +145,7 @@ has stopped following the brand.
 |---|---|---|---|
 | `foundation` | 211 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** Handed a brand colour, this is where it goes: `:root { --primary: <H> <S>% <L>%; }` (HSL components, no `hsl()` wrapper) |
 | `semantic` | 112 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
-| `component` | 1870 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
+| `component` | 1872 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
 
 A token whose `value` is `initial` is not empty and not broken: `initial` is the guaranteed-invalid
 value, so the real default is computed where the element paints it. Set it and yours wins.

package/agent/components/Alert.json

@@ -66,6 +66,7 @@
     "DON'T suppress the icon with `icon={false}` unless there is a deliberate design reason; the icon is the primary a11y cue for sighted users since the root already carries `role=\"alert\"` for screen readers.",
     "BANNER (`variant=\"banner\"`): place it FULL-BLEED at the top of the surface it warns about — directly under the Topbar inside AppShell's children for shell-wide attention (past-due subscription, active support session), or as the first child of a page. Its inline inset defaults to the page gutter (--space-page-active-x) and its geometry is owned by the `--banner-*` tokens; never fake a strip with `className` overrides. At most ONE per surface.",
     "CALLOUT (`variant=\"callout\"`): for content that is PART of the document being read — a docs admonition, a CMS note, a policy caveat. It renders `role=\"note\"` and never announces. Map Markdown `[!NOTE]`/`[!TIP]`/`[!IMPORTANT]`/`[!WARNING]`/`[!CAUTION]` straight onto `kind`. DON'T pass `onDismiss` (prose is not dismissed) and DON'T use a callout for something that just HAPPENED — that is the default or banner variant, which announce.",
+    "LIVE OR NOT (gh#1271): static, unchanging guidance → `variant=\"callout\"` (not a live region, `role=\"note\"`); `role=\"alert\"`/`role=\"status\"` (the default and banner variants) are for messages that appear in response to something — a failed save, a sync that finished. A hint that is on the page when it loads is not a status message (WCAG 4.1.3), so it must not announce on every render.",
     "DO NOT use `Alert` for transient ephemeral feedback (e.g. 'saved successfully'). Use `toast()` from sonner + `<Toaster>` for that. `Alert` is for persistent, page-scoped banners that stay visible until the user acts or dismisses."
   ],
   "useCases": [

package/agent/components/DatePicker.json

@@ -87,6 +87,11 @@
       "name": "showWeek",
       "type": "boolean"
     },
+    {
+      "description": "How the day panel's month caption is drawn (react-day-picker `captionLayout`, forwarded to Calendar). Default `label`. `dropdown` turns month and year into selects; without minDate/maxDate the year list spans 100 years back to the current year.",
+      "name": "captionLayout",
+      "type": "\"label\" | \"dropdown\" | \"dropdown-months\" | \"dropdown-years\""
+    },
     {
       "description": "Which period the PANEL opens on, independently of the value (antd `defaultPickerValue`), and — as in antd — RE-APPLIED every time the panel opens, not only at mount. Use it for 'open on the fiscal year's start month' or 'open on the month of the row being edited'.",
       "name": "defaultPickerValue",
@@ -266,6 +271,7 @@
     "DO test by filling the input directly: `await user.type(screen.getByRole('combobox'), '2026-04-15')`. With `range`, the two edges are named textboxes (From / To). The panel is secondary and not required for testing.",
     "DO use `minDate` / `maxDate` to restrict what is selectable — they are enforced on the panel AND on typed entry, so the keyboard is not a way around the rule the mouse obeys.",
     "DON'T place two DatePickers side by side to fake a from~to pair — that is `range`, which is one control, one shell and one value.",
+    "DO use captionLayout=\"dropdown\" for a birth date or any far-away date — the year select reaches 1999 in one pick instead of ~320 arrow clicks; also set `maxDate` when the date can lie in the future (the year list stops at the current year).",
     "DO use `defaultPickerValue` when the panel should open somewhere other than the value — it is the only way to say it, and it re-applies on every open.",
     "DON'T reach for `inputReadOnly` to switch the control off; it only sets the input's readonly attribute (the panel still opens). `disabled` is the inert one.",
     "DON'T hand-roll a date text input + calendar popover — this component IS that pattern at WAI-ARIA combobox spec level."

package/agent/components/EmptyState.json

@@ -47,6 +47,12 @@
       "description": "Render the title as a non-heading element (p/div) instead of a heading — for a compact/section empty state inside a section that already owns its heading, so the message is not announced as a heading and cannot skip an outline level. Overrides titleLevel.",
       "name": "titleAs",
       "type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"p\" | \"div\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Announce the empty state as a status message (`role=\"status\"`). Default false since gh#1271: a static empty state (\"No invoices yet\") is content, not an update. Rule of thumb — on the page when it loads → leave it off; APPEARS because the user just searched or filtered and nothing matched → `live`.",
+      "name": "live",
+      "type": "boolean"
     }
   ],
   "related": [
@@ -59,6 +65,7 @@
   "storyPath": "data-display/empty-state.tsx",
   "tagline": "Centred empty placeholder with icon, title, description, and optional CTA.",
   "usage": [
+    "DO decide whether the empty state is a STATUS MESSAGE (gh#1271). It is not a live region by default: a static \"No records yet\" that is there when the page loads would otherwise be announced as an update on every render (WCAG 4.1.3 covers content that CHANGES). Pass `live` (→ `role=\"status\"`) only when it appears as the result of a user action — a search or filter that matched nothing: `<EmptyState live icon={SearchIcon} title=\"No matching invoices\" />`. Inside `DataTable` do neither — its empty cell already carries `aria-live=\"polite\"`.",
     "DO always pass `title` — it is the only required prop and renders a heading (`<h3>` by default); omitting it causes a blank silent render with no visible error.",
     "DO set `titleLevel` to match the page outline (page h1 → section h2 → nested h3) so the empty state does not trigger a heading-order violation. Choose the level for OUTLINE position, never for visual size — the size never changes with the level. When the empty state sits in a section that already has its own heading, use `titleAs=\"p\"` so the message is not a heading at all.",
     "DO use `tone=\"success\"` (or warning/destructive/info) for a semantic confirmation/alert zero-state — it recolours the icon medallion from the role token; do NOT hand-roll a `.ui-success-state` class that scopes `--empty-state-icon-*`.",

package/agent/components/Form.json

@@ -74,6 +74,7 @@
     "DO rely on mobile-first collapse: `layout='horizontal'` automatically stacks to vertical below `collapseBelow` (default `md`). Pass `collapseBelow={false}` only when a field MUST stay label-beside-control even on phones.",
     "DO use `columns` for multi-field forms (e.g. `columns={2}`) — it reuses ResponsiveGrid (1 column on small screens, more on md/lg). Span a wide field across columns with `<FormField colSpan={2}>`.",
     "ROW RHYTHM IS THE SAME ON EVERY PATH: a grid of FormFields hands its row spacing to the grid's own `row-gap` (--form-grid-row-gap, defaulting to --form-field-row-gap) instead of the per-field margin a stacked Form uses. So `columns={1}` — and any `columns={n}` form once a narrow container collapses it to one column — is pixel-identical to a Form with no `columns`, and a hand-written `<ResponsiveGrid columns={2}>` of FormFields inside a `CardContent` (what a form with several titled Card sections has to write) matches `columns={2}` exactly. Retune --form-field-row-gap to move every path together; --form-grid-row-gap / --form-grid-column-gap to retune the grid rows / gutter alone. Never add margin to a FormField to space a grid row: a per-item margin inside a grid misaligns row 1 and double-counts the track gap.",
+    "ACTION ROW in a horizontal form (gh#1271): the submit/cancel buttons go in `<FormField label={false}><Flex gap=\"sm\" wrap>…buttons…</Flex></FormField>` as the LAST field. A label-less field renders no label cell and its control is pinned to the control column (gh#709), so the first button's left edge is the inputs' left edge, it follows `labelWidth`, and it collapses with the fields below `collapseBelow`; `wrap` lets the row break onto a second line on a phone. Requires `labelWidth` on the Form — unset, each label column is as wide as its own text and nothing can align with it. DON'T use `staticText` for buttons (it is the read-only VALUE slot), DON'T push the row with a hand-written padding, and DON'T float it to the far end of the card, away from the column the eye just went down. This is the row for a form INSIDE a card or section; a form that is the whole page puts its primary + cancel in the PageContainer footer instead (docs/general/button/examples/form-actions.tsx).",
     "DON'T hand-roll a `<form>` + Flex stack for spacing — `<Form>` provides the vertical rhythm and the layout context FormField reads. Wire react-hook-form by spreading `onSubmit={handleSubmit(...)}` onto `<Form>`.",
     "SERVER ERROR BAG: pass `errors={form.errors}` (Inertia) ONCE on `<Form>`, give each field a `name`, and put `<FormErrors />` at the top of the form. A named field resolves its message from the bag automatically (no per-field `error={errors.x}`), and FormErrors catches validation errors on hidden/derived keys (`action_mode`, `page`, a source-record id) that no visible field could display — without it those submits fail SILENTLY.",
     "SIBLING FORMS: an edit screen split into several Card+Form sections shares ONE bag by wrapping the region in `<FormErrorsProvider errors={form.errors}>` instead of passing `errors` to each Form — the section Forms (without their own `errors`) join the shared registry, and one `<FormErrors />` anywhere in the region renders the unclaimed remainder."

package/agent/components/FormField.json

@@ -26,7 +26,7 @@
       "type": "string"
     },
     {
-      "description": "Field label above the control.",
+      "description": "Field label above the control. `false` renders no label row; in a horizontal form the content still sits in the control column — the action row (gh#1271).",
       "name": "label",
       "required": true,
       "type": "ReactNode"
@@ -112,6 +112,7 @@
   "tagline": "Wraps a control with label, helper, and error; injects the accessible name (aria-labelledby), description (aria-describedby) and validation (aria-errormessage/aria-invalid/aria-required) contract onto the child, which forwards it to its real semantic focus target. Reads the parent Form's layout (vertical/horizontal) — overridable per field.",
   "usage": [
     "DO pass the same string to both `id` on `<FormField>` and `id` on the child control — the component wires `<Label htmlFor={id}>`, and builds `{id}-helper` / `{id}-error` ids for `aria-describedby`. If the ids diverge the label click and screen-reader announcements break.",
+    "NO LABEL: `label={false}` renders no label row and reserves no label space; in a horizontal form the content still sits in the CONTROL column (gh#709). That is the canonical action row under a horizontal form (gh#1271): `<FormField label={false}><Flex gap=\"sm\" wrap><Button type=\"submit\">Save</Button><Button variant=\"outline\">Cancel</Button></Flex></FormField>`. A label-less field around a CONTROL must name the control itself (a `<Checkbox>label</Checkbox>`, an `aria-label`).",
     "DO pass a SINGLE React element as `children`. FormField calls `React.cloneElement` on it to inject `aria-describedby`, `aria-required`, and `aria-invalid` — if you pass a fragment or multiple nodes, cloneElement silently skips the injection and a11y attributes are lost.",
     "COMPOSITE CHILD: when the single child is a layout wrapper — a `Flex` holding a range from/to pair or a 年/月 input+select combo — the label still reaches every control inside. FormField publishes its label through FieldNameContext and each control's semantic focus target (Input's `<input>`, Select's `role=combobox` trigger, and everything composed on them) adopts it as a LAST-RESORT accessible name; a control's own `aria-label`/`aria-labelledby` always wins, so set a per-control `aria-label` (e.g. 開始日/終了日) when the two halves should announce distinct names. The wrapper itself renders as a named `role='group'` (see Flex).",
     "DO reach for `staticText` (not `children` with a bare string/span) for a read-only field mixed into an otherwise-editable Form — e.g. an immutable name/email row above an editable role Select on the same Members-edit card. It renders with the exact typography `Descriptions.Item`'s value uses, and — because it IS a FormField reading the same Form context — it lines up with every other field's label column, `labelAlign`, and row-to-row gap automatically. A bare string as `children` instead triggers the dev-mode 'expected a single React element child' warning and has no typography contract at all.",

package/agent/components/MobileShell.json

@@ -21,7 +21,7 @@
       "type": "ReactNode"
     },
     {
-      "description": "The sticky action bar pinned above the tab bar — the screen's primary verb (Scan, Save, Hand over) and at most one secondary. It sits OUTSIDE the scroll region, so it is always reachable with no `position: sticky` and no scroll-padding hack, and it takes the home-indicator inset whenever no tabBar follows it.",
+      "description": "The sticky action bar pinned above the tab bar — the screen's primary verb (Scan, Save, Hand over) and at most one secondary. It sits OUTSIDE the scroll region, so it is always reachable with no `position: sticky` and no scroll-padding hack, and it takes the home-indicator inset whenever no tabBar follows it. In a `height='viewport'` shell the action bar plus the tab bar publish their summed block size as `--toast-sticky-bar-height`, so the `Toaster` stack sits above the bottom chrome instead of over the primary verb (gh#1271).",
       "name": "actions",
       "type": "ReactNode"
     },

package/agent/components/PageContainer.json

@@ -103,7 +103,7 @@
     },
     {
       "defaultValue": "false",
-      "description": "Pin footer to viewport bottom on scroll — pairs with variant=\"narrow\".",
+      "description": "Pin footer to viewport bottom on scroll — pairs with variant=\"narrow\". While the pinned footer is VISIBLE (always, or once revealed under `footerReveal=\"onScroll\"`), it publishes its block size as `--toast-sticky-bar-height` on `<html>` and the `Toaster` stack rises above it, so a toast never covers the Save/Submit button that raised it (gh#1271). Cleared on unmount or while a reveal footer is parked below the fold.",
       "name": "stickyFooter",
       "type": "boolean"
     },

package/agent/components/Toaster.json

@@ -40,7 +40,8 @@
     "DO: Tune how long toasts stay with the `--toast-duration` token in the theme (default 4000ms) rather than a `duration` prop on every mount. Never truncate a toast's body — it wraps.",
     "DO: Let the wrapper handle theming — it uses `useDocumentTheme()` to sync with the document `dark` class and `prefers-color-scheme` automatically. Never pass a hardcoded `theme` prop unless you are deliberately overriding.",
     "DON'T: Use `Toaster` for persistent errors or blocking confirmations. Toasts auto-dismiss; they are not a substitute for `Alert` (inline persistent warnings) or `Dialog` (decisions requiring user input).",
-    "DO: Pass `position` to relocate the stack if a persistent sidebar/footer would obscure the default `bottom-right`. The wrapper already sets a safe `mobileOffset`; don't add redundant mobile offsets unless your layout differs."
+    "DO: Pass `position` to relocate the stack if a persistent sidebar would obscure the default `bottom-right`. The wrapper already sets a safe `mobileOffset`; don't add redundant mobile offsets unless your layout differs.",
+    "DON'T: Hand-tune `offset` to dodge a sticky action bar. The bottom offset (desktop 24px, mobile `--toast-mobile-offset`) already adds `--toast-sticky-bar-height`, which a visible `PageContainer stickyFooter` or `MobileShell` action/tab bar publishes at runtime, so the stack clears it on its own (gh#1271). For bottom chrome the library does not render (an app's own fixed bar), set `--toast-offset-bottom` once in theme.css — it is added on desktop and mobile alike."
   ],
   "useCases": [
     "After a successful form save (invoice, journal entry, vendor record) — show `toast.success(\"保存しました\")` to confirm without blocking navigation.",

package/agent/components.json

@@ -748,7 +748,7 @@
       },
       {
         "defaultValue": "false",
-        "description": "Pin footer to viewport bottom on scroll — pairs with variant=\"narrow\".",
+        "description": "Pin footer to viewport bottom on scroll — pairs with variant=\"narrow\". While the pinned footer is VISIBLE (always, or once revealed under `footerReveal=\"onScroll\"`), it publishes its block size as `--toast-sticky-bar-height` on `<html>` and the `Toaster` stack rises above it, so a toast never covers the Save/Submit button that raised it (gh#1271). Cleared on unmount or while a reveal footer is parked below the fold.",
         "name": "stickyFooter",
         "type": "boolean"
       },
@@ -1502,7 +1502,7 @@
         "type": "ReactNode"
       },
       {
-        "description": "The sticky action bar pinned above the tab bar — the screen's primary verb (Scan, Save, Hand over) and at most one secondary. It sits OUTSIDE the scroll region, so it is always reachable with no `position: sticky` and no scroll-padding hack, and it takes the home-indicator inset whenever no tabBar follows it.",
+        "description": "The sticky action bar pinned above the tab bar — the screen's primary verb (Scan, Save, Hand over) and at most one secondary. It sits OUTSIDE the scroll region, so it is always reachable with no `position: sticky` and no scroll-padding hack, and it takes the home-indicator inset whenever no tabBar follows it. In a `height='viewport'` shell the action bar plus the tab bar publish their summed block size as `--toast-sticky-bar-height`, so the `Toaster` stack sits above the bottom chrome instead of over the primary verb (gh#1271).",
         "name": "actions",
         "type": "ReactNode"
       },
@@ -4656,6 +4656,12 @@
         "description": "Render the title as a non-heading element (p/div) instead of a heading — for a compact/section empty state inside a section that already owns its heading, so the message is not announced as a heading and cannot skip an outline level. Overrides titleLevel.",
         "name": "titleAs",
         "type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"p\" | \"div\""
+      },
+      {
+        "defaultValue": "false",
+        "description": "Announce the empty state as a status message (`role=\"status\"`). Default false since gh#1271: a static empty state (\"No invoices yet\") is content, not an update. Rule of thumb — on the page when it loads → leave it off; APPEARS because the user just searched or filtered and nothing matched → `live`.",
+        "name": "live",
+        "type": "boolean"
       }
     ],
     "related": [
@@ -4668,6 +4674,7 @@
     "storyPath": "data-display/empty-state.tsx",
     "tagline": "Centred empty placeholder with icon, title, description, and optional CTA.",
     "usage": [
+      "DO decide whether the empty state is a STATUS MESSAGE (gh#1271). It is not a live region by default: a static \"No records yet\" that is there when the page loads would otherwise be announced as an update on every render (WCAG 4.1.3 covers content that CHANGES). Pass `live` (→ `role=\"status\"`) only when it appears as the result of a user action — a search or filter that matched nothing: `<EmptyState live icon={SearchIcon} title=\"No matching invoices\" />`. Inside `DataTable` do neither — its empty cell already carries `aria-live=\"polite\"`.",
       "DO always pass `title` — it is the only required prop and renders a heading (`<h3>` by default); omitting it causes a blank silent render with no visible error.",
       "DO set `titleLevel` to match the page outline (page h1 → section h2 → nested h3) so the empty state does not trigger a heading-order violation. Choose the level for OUTLINE position, never for visual size — the size never changes with the level. When the empty state sits in a section that already has its own heading, use `titleAs=\"p\"` so the message is not a heading at all.",
       "DO use `tone=\"success\"` (or warning/destructive/info) for a semantic confirmation/alert zero-state — it recolours the icon medallion from the role token; do NOT hand-roll a `.ui-success-state` class that scopes `--empty-state-icon-*`.",
@@ -5695,6 +5702,7 @@
       "DO rely on mobile-first collapse: `layout='horizontal'` automatically stacks to vertical below `collapseBelow` (default `md`). Pass `collapseBelow={false}` only when a field MUST stay label-beside-control even on phones.",
       "DO use `columns` for multi-field forms (e.g. `columns={2}`) — it reuses ResponsiveGrid (1 column on small screens, more on md/lg). Span a wide field across columns with `<FormField colSpan={2}>`.",
       "ROW RHYTHM IS THE SAME ON EVERY PATH: a grid of FormFields hands its row spacing to the grid's own `row-gap` (--form-grid-row-gap, defaulting to --form-field-row-gap) instead of the per-field margin a stacked Form uses. So `columns={1}` — and any `columns={n}` form once a narrow container collapses it to one column — is pixel-identical to a Form with no `columns`, and a hand-written `<ResponsiveGrid columns={2}>` of FormFields inside a `CardContent` (what a form with several titled Card sections has to write) matches `columns={2}` exactly. Retune --form-field-row-gap to move every path together; --form-grid-row-gap / --form-grid-column-gap to retune the grid rows / gutter alone. Never add margin to a FormField to space a grid row: a per-item margin inside a grid misaligns row 1 and double-counts the track gap.",
+      "ACTION ROW in a horizontal form (gh#1271): the submit/cancel buttons go in `<FormField label={false}><Flex gap=\"sm\" wrap>…buttons…</Flex></FormField>` as the LAST field. A label-less field renders no label cell and its control is pinned to the control column (gh#709), so the first button's left edge is the inputs' left edge, it follows `labelWidth`, and it collapses with the fields below `collapseBelow`; `wrap` lets the row break onto a second line on a phone. Requires `labelWidth` on the Form — unset, each label column is as wide as its own text and nothing can align with it. DON'T use `staticText` for buttons (it is the read-only VALUE slot), DON'T push the row with a hand-written padding, and DON'T float it to the far end of the card, away from the column the eye just went down. This is the row for a form INSIDE a card or section; a form that is the whole page puts its primary + cancel in the PageContainer footer instead (docs/general/button/examples/form-actions.tsx).",
       "DON'T hand-roll a `<form>` + Flex stack for spacing — `<Form>` provides the vertical rhythm and the layout context FormField reads. Wire react-hook-form by spreading `onSubmit={handleSubmit(...)}` onto `<Form>`.",
       "SERVER ERROR BAG: pass `errors={form.errors}` (Inertia) ONCE on `<Form>`, give each field a `name`, and put `<FormErrors />` at the top of the form. A named field resolves its message from the bag automatically (no per-field `error={errors.x}`), and FormErrors catches validation errors on hidden/derived keys (`action_mode`, `page`, a source-record id) that no visible field could display — without it those submits fail SILENTLY.",
       "SIBLING FORMS: an edit screen split into several Card+Form sections shares ONE bag by wrapping the region in `<FormErrorsProvider errors={form.errors}>` instead of passing `errors` to each Form — the section Forms (without their own `errors`) join the shared registry, and one `<FormErrors />` anywhere in the region renders the unclaimed remainder."
@@ -5734,7 +5742,7 @@
         "type": "string"
       },
       {
-        "description": "Field label above the control.",
+        "description": "Field label above the control. `false` renders no label row; in a horizontal form the content still sits in the control column — the action row (gh#1271).",
         "name": "label",
         "required": true,
         "type": "ReactNode"
@@ -5820,6 +5828,7 @@
     "tagline": "Wraps a control with label, helper, and error; injects the accessible name (aria-labelledby), description (aria-describedby) and validation (aria-errormessage/aria-invalid/aria-required) contract onto the child, which forwards it to its real semantic focus target. Reads the parent Form's layout (vertical/horizontal) — overridable per field.",
     "usage": [
       "DO pass the same string to both `id` on `<FormField>` and `id` on the child control — the component wires `<Label htmlFor={id}>`, and builds `{id}-helper` / `{id}-error` ids for `aria-describedby`. If the ids diverge the label click and screen-reader announcements break.",
+      "NO LABEL: `label={false}` renders no label row and reserves no label space; in a horizontal form the content still sits in the CONTROL column (gh#709). That is the canonical action row under a horizontal form (gh#1271): `<FormField label={false}><Flex gap=\"sm\" wrap><Button type=\"submit\">Save</Button><Button variant=\"outline\">Cancel</Button></Flex></FormField>`. A label-less field around a CONTROL must name the control itself (a `<Checkbox>label</Checkbox>`, an `aria-label`).",
       "DO pass a SINGLE React element as `children`. FormField calls `React.cloneElement` on it to inject `aria-describedby`, `aria-required`, and `aria-invalid` — if you pass a fragment or multiple nodes, cloneElement silently skips the injection and a11y attributes are lost.",
       "COMPOSITE CHILD: when the single child is a layout wrapper — a `Flex` holding a range from/to pair or a 年/月 input+select combo — the label still reaches every control inside. FormField publishes its label through FieldNameContext and each control's semantic focus target (Input's `<input>`, Select's `role=combobox` trigger, and everything composed on them) adopts it as a LAST-RESORT accessible name; a control's own `aria-label`/`aria-labelledby` always wins, so set a per-control `aria-label` (e.g. 開始日/終了日) when the two halves should announce distinct names. The wrapper itself renders as a named `role='group'` (see Flex).",
       "DO reach for `staticText` (not `children` with a bare string/span) for a read-only field mixed into an otherwise-editable Form — e.g. an immutable name/email row above an editable role Select on the same Members-edit card. It renders with the exact typography `Descriptions.Item`'s value uses, and — because it IS a FormField reading the same Form context — it lines up with every other field's label column, `labelAlign`, and row-to-row gap automatically. A bare string as `children` instead triggers the dev-mode 'expected a single React element child' warning and has no typography contract at all.",
@@ -7344,6 +7353,11 @@
         "name": "showWeek",
         "type": "boolean"
       },
+      {
+        "description": "How the day panel's month caption is drawn (react-day-picker `captionLayout`, forwarded to Calendar). Default `label`. `dropdown` turns month and year into selects; without minDate/maxDate the year list spans 100 years back to the current year.",
+        "name": "captionLayout",
+        "type": "\"label\" | \"dropdown\" | \"dropdown-months\" | \"dropdown-years\""
+      },
       {
         "description": "Which period the PANEL opens on, independently of the value (antd `defaultPickerValue`), and — as in antd — RE-APPLIED every time the panel opens, not only at mount. Use it for 'open on the fiscal year's start month' or 'open on the month of the row being edited'.",
         "name": "defaultPickerValue",
@@ -7523,6 +7537,7 @@
       "DO test by filling the input directly: `await user.type(screen.getByRole('combobox'), '2026-04-15')`. With `range`, the two edges are named textboxes (From / To). The panel is secondary and not required for testing.",
       "DO use `minDate` / `maxDate` to restrict what is selectable — they are enforced on the panel AND on typed entry, so the keyboard is not a way around the rule the mouse obeys.",
       "DON'T place two DatePickers side by side to fake a from~to pair — that is `range`, which is one control, one shell and one value.",
+      "DO use captionLayout=\"dropdown\" for a birth date or any far-away date — the year select reaches 1999 in one pick instead of ~320 arrow clicks; also set `maxDate` when the date can lie in the future (the year list stops at the current year).",
       "DO use `defaultPickerValue` when the panel should open somewhere other than the value — it is the only way to say it, and it re-applies on every open.",
       "DON'T reach for `inputReadOnly` to switch the control off; it only sets the input's readonly attribute (the panel still opens). `disabled` is the inert one.",
       "DON'T hand-roll a date text input + calendar popover — this component IS that pattern at WAI-ARIA combobox spec level."
@@ -7891,6 +7906,7 @@
       "DON'T suppress the icon with `icon={false}` unless there is a deliberate design reason; the icon is the primary a11y cue for sighted users since the root already carries `role=\"alert\"` for screen readers.",
       "BANNER (`variant=\"banner\"`): place it FULL-BLEED at the top of the surface it warns about — directly under the Topbar inside AppShell's children for shell-wide attention (past-due subscription, active support session), or as the first child of a page. Its inline inset defaults to the page gutter (--space-page-active-x) and its geometry is owned by the `--banner-*` tokens; never fake a strip with `className` overrides. At most ONE per surface.",
       "CALLOUT (`variant=\"callout\"`): for content that is PART of the document being read — a docs admonition, a CMS note, a policy caveat. It renders `role=\"note\"` and never announces. Map Markdown `[!NOTE]`/`[!TIP]`/`[!IMPORTANT]`/`[!WARNING]`/`[!CAUTION]` straight onto `kind`. DON'T pass `onDismiss` (prose is not dismissed) and DON'T use a callout for something that just HAPPENED — that is the default or banner variant, which announce.",
+      "LIVE OR NOT (gh#1271): static, unchanging guidance → `variant=\"callout\"` (not a live region, `role=\"note\"`); `role=\"alert\"`/`role=\"status\"` (the default and banner variants) are for messages that appear in response to something — a failed save, a sync that finished. A hint that is on the page when it loads is not a status message (WCAG 4.1.3), so it must not announce on every render.",
       "DO NOT use `Alert` for transient ephemeral feedback (e.g. 'saved successfully'). Use `toast()` from sonner + `<Toaster>` for that. `Alert` is for persistent, page-scoped banners that stay visible until the user acts or dismisses."
     ],
     "useCases": [
@@ -7946,7 +7962,8 @@
       "DO: Tune how long toasts stay with the `--toast-duration` token in the theme (default 4000ms) rather than a `duration` prop on every mount. Never truncate a toast's body — it wraps.",
       "DO: Let the wrapper handle theming — it uses `useDocumentTheme()` to sync with the document `dark` class and `prefers-color-scheme` automatically. Never pass a hardcoded `theme` prop unless you are deliberately overriding.",
       "DON'T: Use `Toaster` for persistent errors or blocking confirmations. Toasts auto-dismiss; they are not a substitute for `Alert` (inline persistent warnings) or `Dialog` (decisions requiring user input).",
-      "DO: Pass `position` to relocate the stack if a persistent sidebar/footer would obscure the default `bottom-right`. The wrapper already sets a safe `mobileOffset`; don't add redundant mobile offsets unless your layout differs."
+      "DO: Pass `position` to relocate the stack if a persistent sidebar would obscure the default `bottom-right`. The wrapper already sets a safe `mobileOffset`; don't add redundant mobile offsets unless your layout differs.",
+      "DON'T: Hand-tune `offset` to dodge a sticky action bar. The bottom offset (desktop 24px, mobile `--toast-mobile-offset`) already adds `--toast-sticky-bar-height`, which a visible `PageContainer stickyFooter` or `MobileShell` action/tab bar publishes at runtime, so the stack clears it on its own (gh#1271). For bottom chrome the library does not render (an app's own fixed bar), set `--toast-offset-bottom` once in theme.css — it is added on desktop and mobile alike."
     ],
     "useCases": [
       "After a successful form save (invoice, journal entry, vendor record) — show `toast.success(\"保存しました\")` to confirm without blocking navigation.",

package/agent/index.json

@@ -4,7 +4,7 @@
     "components": 161,
     "patterns": 24,
     "rules": 43,
-    "tokens": 2193,
+    "tokens": 2195,
     "vocabulary": 14
   },
   "files": [
@@ -48,19 +48,19 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v32.2.2/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v32.3.0/agent/index.json"
   },
   "source": "mcp/src/data — the same data @godxjp/ui-mcp serves — plus the foundation and semantic token tiers, read from src/tokens/*.css",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
   "tokenTiers": {
     "component": "per-part knobs, --{component}-{part}-{property}; usually leave these alone",
     "counts": {
-      "component": 1870,
+      "component": 1872,
       "foundation": 211,
       "semantic": 112
     },
     "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
     "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
   },
-  "version": "32.2.2"
+  "version": "32.3.0"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 161 components, 2193 design tokens,
-> 43 cardinal rules. This file is the entry point for AI agents. Catalog version 32.2.2.
+> A Japanese-enterprise React design system: 161 components, 2195 design tokens,
+> 43 cardinal rules. This file is the entry point for AI agents. Catalog version 32.3.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@32.2.2`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@32.3.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -18,7 +18,7 @@ that can only fetch URLs.
 - [components-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 47 KB — all 161 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
 - [components/<Name>.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json): one file per component (1 KB–37 KB, median 6 KB). Read the index, then fetch only the ones you chose — this is the selective route, and the reason you do not need the blob.
 - [components.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json): 1.2 MB — every entry in one file. Most URL fetchers truncate a response this size without saying so; prefer the per-component files.
-- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 211 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 112 `semantic` roles, 1870 `component` knobs.
+- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 211 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 112 `semantic` roles, 1872 `component` knobs.
 - [vocabulary.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json): the controlled prop vocabulary — which prop name means what, across every component.
 - [rules.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json): 43 cardinal rules.
 - [anti-ai-tells.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/anti-ai-tells.json): 26 shapes that make generated UI look generated, each with its fix.
@@ -26,7 +26,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v32.2.2/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v32.3.0/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/agent/tokens.json

@@ -7541,6 +7541,18 @@
     "tier": "component",
     "value": "16px"
   },
+  {
+    "description": "Extra clearance the toast stack keeps above the viewport's bottom edge, ADDED to the gutter on both desktop (sonner's 24px) and mobile (`--toast-mobile-offset`) — gh#1271. `0px` = the stack sits where it always did. A service whose layout pins its own bottom chrome (a fixed bar the library does not render) sets it once in theme.css. Never unitless `0`: it is a `calc()` term, and a bare number there invalidates the whole offset.",
+    "name": "--toast-offset-bottom",
+    "tier": "component",
+    "value": "0px"
+  },
+  {
+    "description": "RUNTIME-PUBLISHED, not a theme knob (gh#1271). A mounted, visible sticky action bar — `PageContainer stickyFooter`, or `MobileShell actions`/`tabBar` in a viewport shell — writes its block size here inline on <html> (`src/lib/toast-clearance.ts`), and the Toaster adds it to its bottom offset so the stack never covers the primary action. Removed again when the bar unmounts or is hidden, which falls back to this `0px`. Set `--toast-offset-bottom` instead of this one: the runtime value overwrites any theme value.",
+    "name": "--toast-sticky-bar-height",
+    "tier": "component",
+    "value": "0px"
+  },
   {
     "description": "Rule #24 companion for the overlay ✕ (gh#1138): the 24px floor is the WCAG 2.5.8 AA minimum for a mouse; under a finger the target lifts to the 44px tap floor the control ladder already uses. Only the hit area grows (the `::after` above the glyph) — the 16px paint stays put.",
     "name": "--dialog-close-size",

package/dist/components/data-display/empty-state.d.ts

@@ -1,3 +1,3 @@
 import type { EmptyStateProp } from "../../props/components/data-display.prop.js";
 export type { EmptyStateProp, EmptyStateProp as EmptyStateProps, } from "../../props/components/data-display.prop.js";
-export declare function EmptyState({ icon: Icon, title, description, action, variant, tone, titleLevel, titleAs, className, }: EmptyStateProp): import("react").JSX.Element;
+export declare function EmptyState({ icon: Icon, title, description, action, variant, tone, titleLevel, titleAs, live, className, }: EmptyStateProp): import("react").JSX.Element;

package/dist/components/data-display/empty-state.js

@@ -10,6 +10,7 @@ function EmptyState({
   tone = "muted",
   titleLevel = 3,
   titleAs,
+  live = false,
   className
 }) {
   const TitleTag = titleAs ?? `h${titleLevel}`;
@@ -19,7 +20,7 @@ function EmptyState({
       "data-slot": "empty-state",
       "data-variant": variant,
       "data-tone": tone,
-      role: "status",
+      role: live ? "status" : void 0,
       className: cn("ui-empty-state", className),
       children: [
         Icon && variant !== "compact" && /* @__PURE__ */ jsx("div", { className: "ui-empty-state-icon", children: /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true" }) }),

package/dist/components/data-entry/calendar.js

@@ -87,7 +87,11 @@ function Calendar({
          * navigation" while the two buttons INSIDE that container said 前の月へ and 次の月へ. Nothing
          * failed and nothing warned; the only reader affected was the one using a screen reader.
          */
-        labelNav: labels?.labelNav ?? (() => t("dataEntry.calendar.nav", { label: ariaLabel ?? t("dataEntry.calendar.name") }))
+        labelNav: labels?.labelNav ?? (() => t("dataEntry.calendar.nav", { label: ariaLabel ?? t("dataEntry.calendar.name") })),
+        // The two caption selects (`captionLayout="dropdown"`) are named the same way — react-day-
+        // picker's defaults are English literals whatever the locale (gh#1271).
+        labelMonthDropdown: labels?.labelMonthDropdown ?? (() => t("dataEntry.calendar.monthDropdown") ?? "Month"),
+        labelYearDropdown: labels?.labelYearDropdown ?? (() => t("dataEntry.calendar.yearDropdown") ?? "Year")
       },
       className: cn("ui-calendar", className),
       "data-width": width === "full" ? "full" : void 0,
@@ -97,6 +101,17 @@ function Calendar({
         month: cn("ui-calendar-month", classNames?.month),
         month_caption: cn("ui-calendar-caption", classNames?.month_caption),
         caption_label: cn("ui-calendar-caption-label", classNames?.caption_label),
+        /*
+         * `captionLayout="dropdown"` slots (gh#1271). Naming a slot REPLACES react-day-picker's own
+         * class, so with these set nothing of `.rdp-dropdown*` applies and control.css owns the whole
+         * look: a native `<select>` laid invisibly over a label + chevron that reads as a compact
+         * control. Unnamed, the selects fell back to the vendor sheet under our caption rules.
+         */
+        dropdowns: cn("ui-calendar-dropdowns", classNames?.dropdowns),
+        dropdown_root: cn("ui-calendar-dropdown-root", classNames?.dropdown_root),
+        dropdown: cn("ui-calendar-dropdown", classNames?.dropdown),
+        months_dropdown: cn("ui-calendar-months-dropdown", classNames?.months_dropdown),
+        years_dropdown: cn("ui-calendar-years-dropdown", classNames?.years_dropdown),
         // z-10 is load-bearing: `month` below is position:relative and later in the DOM, so
         // without a z-index it paints OVER these buttons — they render but never receive the
         // click (the month caption swallows it) and the calendar looks frozen.

package/dist/components/data-entry/date-picker.js

@@ -77,6 +77,7 @@ function DatePicker(props) {
     placement = "bottom-start",
     renderExtraFooter,
     showSummary = true,
+    captionLayout = "label",
     size,
     status,
     variant,
@@ -114,7 +115,7 @@ function DatePicker(props) {
   const allowed = (date) => pickerDateAllowed(date, minimum, maximum, disabledDate);
   const display = (date) => format || showTime ? formatPickerDate(date, format, locale, Boolean(showTime)) : toIsoPeriod(date, picker);
   const displayAll = (date) => Array.isArray(date) ? date.map((day) => display(day)).join(", ") : display(date);
-  const parse = (text2) => parsePickerDate(text2, format, parseFormat, Boolean(showTime)) ?? parseIsoPeriod(text2, picker);
+  const parse = (text2, strict = false) => parsePickerDate(text2, format, parseFormat, Boolean(showTime), strict) ?? parseIsoPeriod(text2, picker);
   const periodDate = (date) => pickerPeriodStart(date, picker, dayPickerLocale);
   const fieldA11y = range ? pickGroupFieldA11y(ariaProps) : pickFieldA11y(ariaProps);
   const identity = useFieldIdentity({ id, name, "data-field": fieldA11y["data-field"] });
@@ -241,13 +242,13 @@ function DatePicker(props) {
       choose(void 0);
       return;
     }
-    const parsed = parse(raw);
+    const parsed = parse(raw, true);
     if (parsed && allowed(parsed)) choose(parsed);
   };
-  const commitEdge = (edge, raw) => {
+  const commitEdge = (edge, raw, strict = false) => {
     if (edgeDisabled(edge)) return;
     const trimmed = raw.trim();
-    const parsed = parse(trimmed);
+    const parsed = parse(trimmed, strict);
     if (trimmed && (!parsed || !allowed(parsed))) return;
     if (!trimmed && !allowEmpty[edge === "from" ? 0 : 1]) return;
     const base = working;
@@ -274,11 +275,20 @@ function DatePicker(props) {
       const next = periodDate(parsed);
       emit(next);
       setText(display(parsed));
+    } else if (!preserveInvalidOnBlur) {
+      setText(displayAll(committedSingle));
     }
     setOpen(false);
   };
   const enterEdge = (edge) => () => {
-    commitEdge(edge, edge === "from" ? fromText : toText);
+    const raw = edge === "from" ? fromText : toText;
+    const parsed = parse(raw);
+    commitEdge(edge, raw);
+    if (raw.trim() && (!parsed || !allowed(parsed)) && !preserveInvalidOnBlur) {
+      const fallback = display(edge === "from" ? committedRange?.from : committedRange?.to);
+      if (edge === "from") setFromText(fallback);
+      else setToText(fallback);
+    }
     setOpen(false);
   };
   const displayIsCanonical = !format && !showTime && !multiple && !needConfirm && !preserveInvalidOnBlur && picker === "date";
@@ -426,6 +436,7 @@ function DatePicker(props) {
     endMonth: maximum,
     showToday,
     showClose,
+    captionLayout,
     onClose: () => setOpen(false)
   };
   const renderDayPanel = () => range ? /* @__PURE__ */ jsx(
@@ -608,13 +619,15 @@ function DatePicker(props) {
         onChange: (event) => {
           if (edge === "from") setFromText(event.target.value);
           else setToText(event.target.value);
-          commitEdge(edge, event.target.value);
+          commitEdge(edge, event.target.value, true);
         },
         onBlur: (event) => {
-          if (preserveInvalidOnBlur) return;
           const parsed = parse(event.target.value);
           const accepted = parsed && allowed(parsed) ? parsed : void 0;
           const fallback = edge === "from" ? committedRange?.from : committedRange?.to;
+          if (accepted && +periodDate(accepted) !== +(fallback ?? NaN))
+            commitEdge(edge, event.target.value);
+          if (preserveInvalidOnBlur) return;
           const next = accepted ? display(accepted) : display(fallback);
           if (edge === "from") setFromText(next);
           else setToText(next);
@@ -704,6 +717,8 @@ function DatePicker(props) {
           onBlur: (event) => {
             const parsed = parse(event.target.value);
             const accepted = parsed && allowed(parsed) && timeAllowed(parsed) ? parsed : void 0;
+            if (accepted && !multiple && !needConfirm && +periodDate(accepted) !== +(committedSingle ?? NaN))
+              emit(periodDate(accepted));
             if (!preserveInvalidOnBlur)
               setText(accepted ? display(accepted) : displayAll(committedSingle));
           }

package/dist/components/data-entry/record-picker.js

@@ -486,25 +486,31 @@ const DialogPicker = React.forwardRef(function DialogPicker2({
                 ))
               }
             ) : null,
-            /* @__PURE__ */ jsx(Command, { shouldFilter: false, split: isMultiple, className: "ui-record-picker-list", children: status === "error" ? /* @__PURE__ */ jsx(
-              EmptyState,
-              {
-                variant: "compact",
-                tone: "destructive",
-                title: t("dataEntry.recordPicker.error"),
-                action: /* @__PURE__ */ jsx(
-                  Button,
-                  {
-                    variant: "outline",
-                    size: "sm",
-                    onClick: () => void load(query, filterValues),
-                    children: t("common.retry")
-                  }
-                )
-              }
+            /* @__PURE__ */ jsx(Command, { shouldFilter: false, split: isMultiple, className: "ui-record-picker-list", children: status === "error" ? (
+              // `live` on both outcomes below: each answers the user's own query (gh#1271 —
+              // EmptyState is no longer a live region by default).
+              /* @__PURE__ */ jsx(
+                EmptyState,
+                {
+                  live: true,
+                  variant: "compact",
+                  tone: "destructive",
+                  title: t("dataEntry.recordPicker.error"),
+                  action: /* @__PURE__ */ jsx(
+                    Button,
+                    {
+                      variant: "outline",
+                      size: "sm",
+                      onClick: () => void load(query, filterValues),
+                      children: t("common.retry")
+                    }
+                  )
+                }
+              )
             ) : status === "loading" ? /* @__PURE__ */ jsx("div", { role: "status", className: "ui-record-picker-status", children: t("dataEntry.recordPicker.loading") }) : visible.length === 0 ? /* @__PURE__ */ jsx(
               EmptyState,
               {
+                live: true,
                 variant: "compact",
                 title: notFoundContent ?? t("dataEntry.recordPicker.empty")
               }

package/dist/components/feedback/sonner.js

@@ -99,8 +99,11 @@ function Toaster({ style, richColors = true, toastOptions, ...props }) {
         ...style
       },
       position: "bottom-right",
+      offset: {
+        bottom: "calc(24px + var(--toast-offset-bottom) + var(--toast-sticky-bar-height))"
+      },
       mobileOffset: {
-        bottom: "var(--toast-mobile-offset)",
+        bottom: "calc(var(--toast-mobile-offset) + var(--toast-offset-bottom) + var(--toast-sticky-bar-height))",
         right: "var(--toast-mobile-offset)"
       },
       duration: tokenDuration,