@nxgt/material-vue 0.26.1 → 0.27.0

package/docs/troubleshooting.md

@@ -18,21 +18,50 @@ words in your error.
 
 - [Components render unstyled, with no error](#components-render-unstyled-with-no-error)
 - [`<Icon>` renders nothing](#icon-renders-nothing)
+- [An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry](#an-accessibility-audit-reports-low-contrast-on-a-badge-a-button-a-toast-or-a-menu-entry)
+- [`ARIA hidden element must not be focusable or contain focusable elements`](#aria-hidden-element-must-not-be-focusable-or-contain-focusable-elements)
+- [An accessibility audit reports low contrast on a tonal or outlined button, a selected list tile or a hovered badge link](#an-accessibility-audit-reports-low-contrast-on-a-tonal-or-outlined-button-a-selected-list-tile-or-a-hovered-badge-link)
+- [An accessibility audit reports low contrast on error text in the dark theme](#an-accessibility-audit-reports-low-contrast-on-error-text-in-the-dark-theme)
+- [Dialogs, toasts or buttons no longer animate](#dialogs-toasts-or-buttons-no-longer-animate)
+- [A Button's label overflows a card on a phone](#a-buttons-label-overflows-a-card-on-a-phone)
 - [`JsBarcode is not a function`](#jsbarcode-is-not-a-function)
 - [A `LinkButton` selected as a `button` stops matching](#a-linkbutton-selected-as-a-button-stops-matching)
 - [A `Toc`, `Pager`, `SeeAlso` or `ScrollProgress` inside `Doc` selected by `data-slot` stops matching](#a-toc-pager-seealso-or-scrollprogress-inside-doc-selected-by-data-slot-stops-matching)
 - [A `ResponsiveButton` selected by `[aria-expanded]` stops matching](#a-responsivebutton-selected-by-aria-expanded-stops-matching)
+- [A menu no longer blocks the page, or a `ResponsiveButton` has no `useIsMobile` behaviour](#a-menu-no-longer-blocks-the-page-or-a-responsivebutton-has-no-useismobile-behaviour)
 - [A menu item selected by `[data-variant=destructive]` stops matching](#a-menu-item-selected-by-data-variantdestructive-stops-matching)
 - [A `Stepper` step selected by `#step-N` stops matching](#a-stepper-step-selected-by-step-n-stops-matching)
 - [A test no longer finds a date or time picker by the `button` role, or a slider thumb by the exact name `Minimum`](#a-test-no-longer-finds-a-date-or-time-picker-by-the-button-role-or-a-slider-thumb-by-the-exact-name-minimum)
 - [An end-to-end test no longer finds a required field by a name ending in `*`](#an-end-to-end-test-no-longer-finds-a-required-field-by-a-name-ending-in-)
 - [A test no longer finds `aria-invalid` on an upload field's group or drop zone](#a-test-no-longer-finds-aria-invalid-on-an-upload-fields-group-or-drop-zone)
 - [A test no longer finds `aria-invalid` on a `Switch` row or an `Autocomplete` box](#a-test-no-longer-finds-aria-invalid-on-a-switch-row-or-an-autocomplete-box)
+- [A test no longer finds `aria-invalid` on an `OtpField` slot](#a-test-no-longer-finds-aria-invalid-on-an-otpfield-slot)
 - [A test no longer finds the breadcrumb's home button](#a-test-no-longer-finds-the-breadcrumbs-home-button)
+- [A test no longer finds a sidebar entry by the `button` role](#a-test-no-longer-finds-a-sidebar-entry-by-the-button-role)
+- [A test no longer finds a tooltip on an entry of an expanded sidebar](#a-test-no-longer-finds-a-tooltip-on-an-entry-of-an-expanded-sidebar)
+- [The app shell's page scrolls instead of its content, or a full-height screen collapses](#the-app-shells-page-scrolls-instead-of-its-content-or-a-full-height-screen-collapses)
+- [A test finds a new heading or a second `main`, or no longer finds a title in a `div`](#a-test-finds-a-new-heading-or-a-second-main-or-no-longer-finds-a-title-in-a-div)
+- [`[data-test="typogaphy"]` finds nothing](#data-testtypogaphy-finds-nothing)
+- [A `class` on `ActivityLayout` now styles the whole shell](#a-class-on-activitylayout-now-styles-the-whole-shell)
+- [A test no longer finds a calendar day by its number](#a-test-no-longer-finds-a-calendar-day-by-its-number)
 - [A `QRCode`'s `aria-label` is no longer on its wrapper](#a-qrcodes-aria-label-is-no-longer-on-its-wrapper)
 - [A `CheckboxGroup` or `RadioGroupField` option selected by `#<id>-<value>` stops matching](#a-checkboxgroup-or-radiogroupfield-option-selected-by-id-value-stops-matching)
 - [A `Table`'s `id`, `aria-*` or `style` is no longer on its scrolling container](#a-tables-id-aria--or-style-is-no-longer-on-its-scrolling-container)
 
+**Feedback**
+
+- [A toast with an action never goes away](#a-toast-with-an-action-never-goes-away)
+- [A toast covers the form's button on a phone](#a-toast-covers-the-forms-button-on-a-phone)
+- [A toast never goes away after a tap](#a-toast-never-goes-away-after-a-tap)
+- [A toast's action cannot be clicked while a dialog is open](#a-toasts-action-cannot-be-clicked-while-a-dialog-is-open)
+- [A `ConfirmationDialog` reopened at once stays closed](#a-confirmationdialog-reopened-at-once-stays-closed)
+- [The first Escape after closing a nested dialog does nothing](#the-first-escape-after-closing-a-nested-dialog-does-nothing)
+
+**Navigation**
+
+- [A `ListTile` link reloads the whole page](#a-listtile-link-reloads-the-whole-page)
+- [The phone menu needs two Escapes to close, or a tooltip shows over it](#the-phone-menu-needs-two-escapes-to-close-or-a-tooltip-shows-over-it)
+
 **SSR & build**
 
 - [`ReferenceError: window is not defined`](#referenceerror-window-is-not-defined)
@@ -48,6 +77,8 @@ words in your error.
 - [`injection "Symbol(route location)" not found`](#injection-symbolroute-location-not-found)
 - [A `*FormField` is missing from the submitted values, or never shows an error](#a-formfield-is-missing-from-the-submitted-values-or-never-shows-an-error)
 - [`meta.touched` stays false after leaving a field](#metatouched-stays-false-after-leaving-a-field)
+- [A failed submit does not focus the first invalid field](#a-failed-submit-does-not-focus-the-first-invalid-field)
+- [A test that finds a chip by `aria-selected` or `getByRole('option')` no longer finds it](#a-test-that-finds-a-chip-by-aria-selected-or-getbyroleoption-no-longer-finds-it)
 - [A multi-step form reopens at a later step](#a-multi-step-form-reopens-at-a-later-step)
 - [The form could not be loaded.](#the-form-could-not-be-loaded)
 
@@ -92,11 +123,14 @@ words in your error.
 - [A translation key is rendered instead of its text](#a-translation-key-is-rendered-instead-of-its-text)
 - [A label shows `{count}` or another placeholder](#a-label-shows-count-or-another-placeholder)
 - [Zod messages ignore the language, or your `material.zod.*` strings](#zod-messages-ignore-the-language-or-your-materialzod-strings)
+- [A test asserting the old Zod string length text fails](#a-test-asserting-the-old-zod-string-length-text-fails)
+- [A calendar's weekday row is in English on a French page](#a-calendars-weekday-row-is-in-english-on-a-french-page)
 
 **Runtime**
 
 - [`must be used within` / `must be used inside` (context providers)](#must-be-used-within--must-be-used-inside)
 - [`Clipboard is not available`](#clipboard-is-not-available)
+- [A test no longer finds `CopyButton` by "Copied", or its name changes](#a-test-no-longer-finds-copybutton-by-copied-or-its-name-changes)
 - [`Upload failed with status 403`](#upload-failed-with-status-403)
 - [`Network error during upload`](#network-error-during-upload)
 - [`Maximum number of presets (20) reached`](#maximum-number-of-presets-20-reached)
@@ -113,6 +147,7 @@ words in your error.
 - [A test no longer finds the label or helper text inside a date or time picker's trigger](#a-test-no-longer-finds-the-label-or-helper-text-inside-a-date-or-time-pickers-trigger)
 - [A test no longer finds a `DurationField` input by the field's label, or a `Slider`'s `aria-label` on its root](#a-test-no-longer-finds-a-durationfield-input-by-the-fields-label-or-a-sliders-aria-label-on-its-root)
 - [An `AlertDialog` focuses its Cancel although `@open-auto-focus` prevented it](#an-alertdialog-focuses-its-cancel-although-open-auto-focus-prevented-it)
+- [Focus moves into a dialog although `@open-auto-focus` prevented it](#focus-moves-into-a-dialog-although-open-auto-focus-prevented-it)
 - [A `CustomDialog` or `ConfirmationDialog` no longer opens from its `#trigger`](#a-customdialog-or-confirmationdialog-no-longer-opens-from-its-trigger)
 - [A form with a required `Switch` no longer submits](#a-form-with-a-required-switch-no-longer-submits)
 - [A `RichTextEditor` became editable after upgrading](#a-richtexteditor-became-editable-after-upgrading)
@@ -121,7 +156,12 @@ words in your error.
 - [A link or button in the first column of a `DataTable` with `getRowHref`](#a-link-or-button-in-the-first-column-of-a-datatable-with-getrowhref)
 - [A row does not navigate after `@row-click` ran](#a-row-does-not-navigate-after-row-click-ran)
 - [A `DataTable` Previous or Next button is disabled](#a-datatable-previous-or-next-button-is-disabled)
+- [A double click or Enter submits a form twice, or a test no longer finds a loading `Button` disabled](#a-double-click-or-enter-submits-a-form-twice-or-a-test-no-longer-finds-a-loading-button-disabled)
 - [A `DataTable` shows a sorting or a selection the URL never got](#a-datatable-shows-a-sorting-or-a-selection-the-url-never-got)
+- [A `DataTable` no longer scrolls inside a 400px box](#a-datatable-no-longer-scrolls-inside-a-400px-box)
+- [A `DataTable` shows its header row on a phone](#a-datatable-shows-its-header-row-on-a-phone)
+- [A test's `getByRole('region')` finds more than one region](#a-tests-getbyroleregion-finds-more-than-one-region)
+- [A `DataTable` toolbar is gone](#a-datatable-toolbar-is-gone)
 
 **PDF reader**
 
@@ -397,6 +437,21 @@ const button = screen.getByRole('button', { name: 'New order' });
 expect(within(button).getByText('New order')).toHaveClass('sr-only'); // collapsed
 ```
 
+### A menu no longer blocks the page, or a `ResponsiveButton` has no `useIsMobile` behaviour
+
+**When:** after upgrading, clicking outside an open `DropdownMenu` (or
+`LanguageSwitcher`) reaches the element under the pointer and the page can
+still scroll; or `ResponsiveButton` shows its label in a test whose
+`matchMedia` says "mobile".
+**Why:** `DropdownMenu` is non-modal by default now: Reka's modal menu marked
+the rest of the page `aria-hidden` while its buttons and links stayed
+focusable (axe `aria-hidden-focus`). `ResponsiveButton` and
+`ResponsiveLinkButton` collapse with a CSS `max-md` media query instead of a
+JS effect, so the label is in the DOM at every width and jsdom (which applies
+no CSS) always shows it.
+**Fix:** pass `modal` to `DropdownMenu` to restore the old behaviour; force a
+collapsed button in a test with `:expanded="false"`.
+
 ### A menu item selected by `[data-variant=destructive]` stops matching
 
 **When:** your CSS, or a test, targets `[data-variant=destructive]` on a
@@ -512,6 +567,23 @@ await expect(page.getByRole('switch', { name: 'Notifications' })).toHaveAttribut
 await expect(page.getByLabel('Country')).toHaveAttribute('aria-invalid', 'true');
 ```
 
+### A test no longer finds `aria-invalid` on an `OtpField` slot
+
+**When:** `[data-slot="input-otp-slot"][aria-invalid]` (or
+`getAllByRole(…)` filtered on `aria-invalid`) finds nothing although the
+`OtpField` has `error`.
+**Why:** ARIA does not allow `aria-invalid` on a plain `div`, and a slot is
+a presentational box: the one element a screen reader reads is the hidden
+input, which keeps `aria-invalid="true"`. A slot shows the error with a red
+border from `data-invalid`.
+**Fix:** assert it on the input, found by the field's label:
+
+```ts
+await expect(page.getByLabel('Enter OTP')).toHaveAttribute('aria-invalid', 'true');
+// A slot's red border, if a test must see it:
+await expect(page.locator('[data-slot="input-otp-slot"]').first()).toHaveAttribute('data-invalid');
+```
+
 ### A test no longer finds the breadcrumb's home button
 
 **When:** after upgrading, `getByRole('button', { name: 'Home' })` finds
@@ -529,6 +601,141 @@ await page.getByRole('navigation', { name: 'breadcrumb' })
   .click();
 ```
 
+### A test no longer finds a sidebar entry by the `button` role
+
+**When:** after upgrading, `getByRole('button', { name: 'Invoices' })` finds
+nothing among the entries of an `ActivityLayout`, `AppSidebar` or `AppHeader`'s
+menu sheet.
+**Why:** each entry used to be a `<button>` that navigated on click. It is now
+a real `<a href>`, so its role is `link`, and the current page's entry carries
+`aria-current="page"`. The icon inside is decorative (`aria-hidden`), so the
+link's name is its label alone, "Invoices", and an exact name matches.
+**Fix:** find it as a link:
+
+```ts
+const invoices = page.getByRole('link', { name: 'Invoices' });
+await invoices.click();
+await expect(invoices).toHaveAttribute('aria-current', 'page');
+```
+
+### A test no longer finds a tooltip on an entry of an expanded sidebar
+
+**When:** after upgrading, a test hovers or focuses an entry of an expanded
+`ActivityLayout` or `AppSidebar` sidebar (or of the phone menu sheet) and
+waits for `getByRole('tooltip', { name: 'Inbox' })`, which never appears.
+**Why:** the shell's entries no longer pass their label as `tooltip`. A
+`SidebarMenuItem` shows its label as a tooltip only while its `Sidebar` is
+collapsed; expanded, the label is already on screen, and a tooltip repeating
+it opened over the first entry as focus moved into the menu sheet, where it
+took the first Escape. A `tooltip` you pass is still shown, collapsed or
+expanded, and a collapsed entry with no `tooltip` now shows its label, where
+it showed nothing before.
+**Fix:** find the entry by the label it shows —
+`getByRole('link', { name: 'Inbox' })` — or collapse the sidebar first when
+the test is about the tooltip. Pass `tooltip` when an expanded entry of your
+own `Sidebar` must have one:
+
+```vue
+<SidebarMenuItem href="/inbox" tooltip="3 unread">Inbox</SidebarMenuItem>
+```
+
+### The app shell's page scrolls instead of its content, or a full-height screen collapses
+
+**When:** after upgrading, the whole page scrolls under an `ActivityLayout`
+rather than the box inside it; a test or a script that scrolled the shell's
+inner box (`[data-slot=activity-layout] .overflow-auto`) finds nothing to
+scroll; or a screen sized `h-full` to fill the shell (a map, a board) is only
+as high as its content.
+**Why:** the shell was `100lvw × 100lvh` and scrolled its content inside
+itself: the page was a scrollbar's width wider than the window, and on a phone
+the bottom of the content sat under the browser's toolbar. It is now `100%`
+wide and at least `100dvh` high, and the document scrolls; the header and the
+desktop sidebar are sticky.
+**Fix:** scroll the window in a test (`window.scrollTo`, or let the browser
+scroll an element into view). For a screen that manages its own height, opt
+back into the in-shell scrolling with `scroll="container"`:
+
+```vue
+<ActivityLayout :items="items" scroll="container">
+```
+
+### A test finds a new heading or a second `main`, or no longer finds a title in a `div`
+
+**When:** after upgrading, `getAllByRole('heading')` returns more than it did,
+a selector such as `div[data-slot=card-title]` finds nothing, or an
+accessibility check reports more than one `main` landmark in an app that
+renders its own `<main>` around `ActivityLayout`.
+**Why:** `ActivityContent`'s title is now a heading, `h1` by default; a
+`CardTitle` is an `h3`; and the shell's content region is the page's
+`<main>`. The phone menu sheet was named "Open menu", like its button; it is
+now named "Navigation" (`material.app-shell.navigation`):
+`getByRole('dialog', { name: 'Navigation' })`.
+**Fix:** find titles by role and level —
+`getByRole('heading', { level: 1, name: 'Invoices' })` — and pick another
+level with `title-as` or `CardTitle`'s `as` (`'div'` for no heading). An app
+with its own `<main>` passes `content-as="div"`.
+
+### `[data-test="typogaphy"]` finds nothing
+
+**When:** after upgrading, a selector on `data-test="typogaphy"` finds no
+`Typography` or `HelperText`.
+**Why:** the attribute was misspelled; it now reads `data-test="typography"`.
+**Fix:** select `[data-test="typography"]` — or better, the text or the role
+the user sees.
+
+### A `class` on `ActivityLayout` now styles the whole shell
+
+**When:** after upgrading, the classes passed to `<ActivityLayout class="…">`
+(a padding, a background, a gap) land around the sidebar and the header too,
+not only around the content, or a selector on the inner box finds them
+missing.
+**Why:** `class` used to land on the inner layout box; it now reaches the
+outer element, `[data-slot=activity-layout]`, with the other attributes — as
+`className` does in `@nxgt/material`.
+**Fix:** keep on `ActivityLayout` only the classes meant for the whole shell,
+and move the rest to the screen: `ActivityContent`'s `class`, or an element
+of your own inside it:
+
+```vue
+<ActivityLayout :items="items" class="bg-muted">
+  <ActivityContent title="Invoices" class="gap-6">…</ActivityContent>
+</ActivityLayout>
+```
+
+### A test no longer finds a calendar day by its number
+
+**When:** after upgrading, `getByRole('gridcell', { name: '1' })` finds nothing
+in a `Calendar`, `DateField`, `DateRangeField` or `EventCalendar`'s date picker,
+while `getByRole('button', { name: 'Thursday, October 1, 2026' })` (the old
+name, which is also the new one) still does; or
+`getByRole('gridcell', { name: '1', exact: true })` used to match both the 1st
+and the next month's 1st, shown as an outside day.
+**Why:** a day is now named by its full localized date and nothing else:
+"Thursday, October 1, 2026" (in French "jeudi 1 octobre 2026"), on the button
+and on the cell (`gridcell`) around it, which used to be named by its text,
+"1". The chosen day carries `aria-selected="true"` on its cell and a
+"Selected" description on its button, today `aria-current="date"` on both. The
+days of the neighbouring months are named by their own dates ("Wednesday,
+September 30, 2026"), so a bare number matches no day at all. The language is
+the calendar's `locale`, else the active `I18nProvider` language, else English:
+under a French provider the names, the heading and the weekday row are now
+French, so pass `locale="en"` to keep English.
+**Fix:** pick the day by its date, exactly, and assert the state; compute
+today's name instead of writing it:
+
+```ts
+const name = (date: Date) =>
+	new Intl.DateTimeFormat('en', { dateStyle: 'full' }).format(date);
+
+const day = page.getByRole('gridcell', { name: 'Thursday, October 1, 2026', exact: true });
+await day.getByRole('button').click();
+await expect(day).toHaveAttribute('aria-selected', 'true');
+await expect(page.getByRole('button', { name: 'Thursday, October 1, 2026' })).toHaveAccessibleDescription('Selected');
+await expect(page.getByRole('gridcell', { name: name(new Date()) })).toHaveAttribute('aria-current', 'date');
+```
+
+`getByRole('button', { name: 'Thursday, October 1, 2026', exact: true })` finds the same day.
+
 ### A `QRCode`'s `aria-label` is no longer on its wrapper
 
 **When:** after upgrading, `div[aria-label="…"]` (or a
@@ -609,16 +816,22 @@ page.locator('[data-slot="table-container"]'); // the scrolling container
 
 **When:** after upgrading to 0.22.0, `getByRole('textbox', { name: 'Email*' })`
 (or any role query whose name ends in `*`) finds nothing for a field whose
-`Label` has `with-asterisk` (a `required` field). Queries on the label's text,
-`getByLabelText` and Playwright's `getByLabel`, still see the `*`: match it
-loosely in `getByLabelText` (`getByLabelText(/^Email/)`); Playwright's
-`getByLabel('Email')` already matches a substring.
-**Why:** screen readers used to read the asterisk ("Email star" or "Email*"),
-so it is now `aria-hidden`. The field's own `required` / `aria-required` says it is required,
-and every field of this library now sets it on the element a screen reader
-lands on (the input, the picker's combobox, the slider thumbs, the rating's
+`Label` has `with-asterisk` (a `required` field). Since the release that drew the
+asterisk with CSS, `getByLabelText('Email*')` and Playwright's
+`getByLabel('Email *')` find nothing either; and the other way round,
+`getByLabel('Email', { exact: true })` and `getByLabelText('Email')` now match
+a required field, which a `*` in the label's text used to prevent.
+**Why:** screen readers read the asterisk ("Email star" or "Email*"), and
+Testing Library and Playwright compare the label's text, `aria-hidden` or not.
+The `*` is now drawn by a CSS pseudo-element with an empty `content`
+(`label.css`, imported by the stylesheet), so it is in no text and no name. The
+field's own `required` / `aria-required` says it is required, and every field
+of this library sets it on the element a screen reader lands on (the input, the
+picker's combobox, the select's trigger, the slider thumbs, the rating's
 radiogroup, the editor's textbox, the list's listbox, or, for a file picker,
-a group described as "This field is required.").
+a group described as "This field is required."). A `SelectField`'s trigger is
+now named by its label (`aria-labelledby`), so `getByRole('combobox', { name:
+'Framework' })` finds it.
 **Fix:** find the field by its label alone, and check that it is required
 separately:
 
@@ -634,6 +847,401 @@ await expect(page.getByRole('textbox', { name: 'Email' })).toHaveAttribute('requ
 await expect(page.getByRole('combobox', { name: 'Delivery date' })).toHaveAttribute('aria-required', 'true');
 ```
 
+Custom CSS that targeted the old `<span class="text-error">` should target
+`[data-slot="label-text"][data-required]::after` instead; the recipe is in
+[Label](components/primitives.md#label). The mark is drawn by the package stylesheet, so a
+snapshot of the DOM no longer contains it, and it stays visible in
+forced-colors mode.
+
+### An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry
+
+**When:** axe (or Lighthouse) reports `color-contrast` on a `Badge` with
+`variant="success"`, `"info"`, `"warning"` or `"secondary"`; on a filled
+`secondary`, `success`, `info` or `warning` `Button` or `IconButton` in the
+dark theme; on a filled `Button` or `IconButton` while it is hovered, focused
+or pressed; on muted text on a `bg-muted` surface (an `Alert`
+`variant="foreground"`, the default `Timeline` marker, code) or on the
+"paper" tint; on a toast's title or description while it enters, or its X
+button; or on the muted text (a shortcut, the `LanguageSwitcher` code) of a
+highlighted menu entry, or on a calendar's weekday row in the dark theme.
+**Why:** the colours come from your tokens and the components' state tints.
+Before this fix, concretely: the light `--secondary`,
+`--success`, `--info` and `--warning` gave their near-white text 4.3:1,
+3.5:1, 2.5:1 and 3.4:1; the light `--muted-foreground` read 4.3:1 on
+`--muted` and 4.4:1 on the paper tint, and the dark `--muted` was the light,
+near-white value, so muted text on `bg-muted` failed in the dark theme too;
+in the dark theme a filled `secondary`, `success`, `info` or `warning` button
+gave 4.3:1, 3.5:1, 2.5:1 and 3.4:1, and its hover, focus and pressed tints
+less; in the light theme a filled button faded toward the page when hovered,
+focused or pressed (`/90`, `/80`, `/70`: down to 3.1:1 pressed); a library
+toast started at opacity 0, so an audit run while it entered measured its
+text faded; and the toast and the highlighted entry used the muted colour on
+a background it does not reach 4.5:1 on; the dark `--muted-foreground` of a
+calendar's weekday row reached 3.7:1 on a popover. If the audit still fails, your
+stylesheet overrides one of those tokens, a `class` of your own puts the old
+state tints back, or you still ship one of those versions.
+**Fix:** update, remove the override, or pick a colour that keeps 4.5:1 with
+its `-foreground`:
+
+```css
+:root {
+  --info: oklch(0.5 0.165 254.624); /* 5.8:1 with --info-foreground */
+}
+```
+
+A toast the library renders, through `toast()` or `toasts.*` from
+`@nxgt/material-vue` (vue-sonner's `toast.custom` path, marked
+`data-styled="false"`), no longer fades its text in: the wrapper stays opaque
+while it slides in, so an audit run while it enters measures the settled
+colours. A toast vue-sonner styles itself still fades in from opacity 0: a
+plain `toast('…')` or `toast.success('…')` from `vue-sonner`, `sonnerToast`
+from this package, and, for now, the toasts `Notifications` shows with
+`toast-on-arrival` and the messages of `AttributesField`. Show your own
+through `toasts.*` instead. If a library toast still reports its title as low
+contrast, an override of `[data-sonner-toast]` sets its `opacity` back to 0
+on mount.
+
+The muted text on a `bg-muted` surface (an `Alert` `variant="foreground"`, the
+default `Timeline` marker) and on the "paper" tint failed in the shipped
+palette too (4.3:1 and 4.4:1 in light; the dark `--muted` was the light one).
+They pass since the `--muted` and `--muted-foreground` tokens changed: if
+yours still fail, you override them.
+
+In the dark theme, a filled `secondary` `Button` gave its near-white text
+4.3:1, a `tonal` secondary one 3.9:1 (3.4:1 on `--card`), and a filled
+`success`, `info` or `warning` one 3.5:1, 2.5:1 and 3.4:1. The dark
+`--secondary` is brighter (`oklch(0.66 ...)`, 6.5:1 as text on
+`--background`), and the filled `secondary`, `success`, `info` and `warning`
+`Button`s and `IconButton`s are tinted in the dark theme
+(`dark:bg-secondary/70`, `dark:bg-success/60`, …) so their text keeps 4.5:1.
+A filled button given a background of your own through `className` loses the
+tint in dark mode: add a matching `dark:` one.
+
+### `ARIA hidden element must not be focusable or contain focusable elements`
+
+**When:** an accessibility audit (axe, Lighthouse, the Storybook
+accessibility panel) runs while a `Dialog`, `Sheet`, `Drawer`,
+`AlertDialog`, `CommandDialog`, a `Select` list, a `ContextMenu`, or a
+`modal` `DropdownMenu` or `Popover` is open, and reports `aria-hidden-focus`
+on the page behind it: its buttons, links and fields.
+**Why:** reka marks the rest of the page `aria-hidden` while a modal layer
+is open and leaves it focusable; a control the tab order reaches inside an
+`aria-hidden` subtree is what the rule reports. A version of @nxgt/material-vue that
+reports it predates the inert background.
+**Fix:** upgrade: the page behind a modal layer of this library is `inert`
+as well — out of the tab order and of the accessibility tree — and the rule
+passes. Live regions (the `Toaster`) stay reachable. Do not exclude
+`[aria-hidden]` or `[data-aria-hidden]` from the audit: it hides real
+failures. A layer of yours built on reka directly (not on these
+components) still marks the page `aria-hidden` only; make the rest of the
+page inert with core's `inertOthers`, which keeps live regions and counts
+nested layers:
+
+```ts
+import { inertOthers } from '@nxgt/material-core/inert-others';
+import { nextTick, ref, watch } from 'vue';
+
+const open = ref(false);
+// A template ref on your layer's content: an element or a component.
+const content = ref();
+
+watch(open, (isOpen, _, onCleanup) => {
+  if (!isOpen) return;
+  let undo: (() => void) | undefined;
+  let closed = false;
+  nextTick(() => {
+    // Closed before the tick: do not mark the page.
+    if (!closed) undo = inertOthers(content.value?.$el ?? content.value);
+  });
+  onCleanup(() => {
+    closed = true;
+    undo?.();
+  });
+});
+```
+
+Elements mounted after the layer opens are not made inert: mount them
+first, or pass them to `inertOthers` in `keep` when they must stay
+reachable.
+
+### An accessibility audit reports low contrast on a tonal or outlined button, a selected list tile or a hovered badge link
+
+**When:** axe (or Lighthouse) reports `color-contrast` on a `tonal` or
+`outlined` `Button` or `IconButton` (`primary` in the dark theme, `error`,
+`warning` and `success`), at rest or hovered, focused or pressed; on the
+subtitle of a selected `ListTile`; or on a `Badge` link while it is hovered.
+**Why:** those variants drew their text in the token itself, and some tokens
+do not reach 4.5:1 as text on the page and on their own tint: the dark
+`--primary` is a dark indigo (2.2:1 on `--card`), the light `--error` gave
+3.6:1 on its tonal tint, `--warning` 4.3:1, the dark `--success` 4.0:1 on
+`--card`. The selected tile's tint brought the muted subtitle to 4.4:1, and a
+`Badge` link faded toward the page on hover (`/90`: down to 3.0:1 for `info`
+in the dark theme). A release that has the fix mixes those tones from the
+tokens, toward black in the light theme and toward white in the dark one; if
+the audit still fails, a text colour of your own replaces the tone, or a
+token of yours is too light (or, in the dark theme, too dark) to read as text.
+**Fix:** update, then drop the text colour you put on the button, or check
+your token against the page at 4.5:1:
+
+```vue
+<!-- before: the tone is replaced by the raw token -->
+<Button variant="tonal" color="error" class="text-error">Delete</Button>
+<!-- after -->
+<Button variant="tonal" color="error">Delete</Button>
+```
+
+A `Badge` link of your own with a hover fade such as `[a&]:hover:bg-error/90`
+in its `class` puts the fade back: darken instead, as in
+`[a&]:hover:bg-[color-mix(in_oklab,var(--color-error)_90%,black)]` (with
+your badge's colour in place of `error`). A
+subtitle colour of your own on a selected `ListTile` must reach 4.5:1 on
+`bg-primary/15`.
+
+### An accessibility audit reports low contrast on error text in the dark theme
+
+**When:** an error message, a validation hint or a red value of your own, in
+the dark theme, fails 4.5:1 (about 4.2:1 on the page, 3.8:1 on a card); the
+catalogue's own field messages pass.
+**Why:** it is drawn with `text-error`, the fill colour. The dark `--error` is
+kept dark enough for near-white text on a filled error surface, which makes it
+too dark to read as text on the dark surfaces. Error text has its own token,
+`--error-text`, lightened in the dark theme (5.9:1 on `--background`, 5.3:1 on
+`--card`).
+**Fix:** draw text with `text-error-text`; keep `text-error` for fills,
+borders and icons that stand alone. On a `Button` or `IconButton` drop the
+class instead: the tone already colours the text:
+
+```vue
+<!-- before -->
+<p class="text-sm text-error">Enter a valid email</p>
+<!-- after -->
+<p class="text-sm text-error-text">Enter a valid email</p>
+```
+
+Setting `--error` or `--error-text` on an element below the root (a `style`
+on a section) changes nothing: `@theme` resolves `--color-error-text` on the
+root. Below the root, set `--color-error-text` (and `--color-error` for fills)
+on that element, or put the override on the root.
+
+### Dialogs, toasts or buttons no longer animate
+
+**When:** a transition or an animation of a catalogue component does not run
+on your machine, while it does on a colleague's.
+**Why:** the operating system has "Reduce motion" on. `styles.css` honours
+`prefers-reduced-motion: reduce` for every component (dialogs, sheets, menus,
+toasts, buttons) and leaves only the `Spinner` and
+`animate-spin` elements turning.
+**Fix:** none is needed, this is the intended behaviour. To test the animated
+version, turn the setting off (or, in Chrome DevTools, Rendering, "Emulate CSS
+media feature prefers-reduced-motion": no-preference). To keep one animation
+for everyone, override it with an `!important` rule on that element inside
+`@media (prefers-reduced-motion: reduce)`.
+
+### A Button's label overflows a card on a phone
+
+**When:** on a narrow screen, a `Button` with a long label sticks out of its
+card, dialog or column (a 349 px button in a 343 px card), or its label is
+clipped at both ends with no "…".
+**Why:** before this change, the button took its label's whole width
+(`width: max-content`) whatever its container. A button is now never wider
+than its container (`max-width: 100%`), and its text is put in a
+`<span data-slot="button-label">` (one span per run of text, so `Delete {name}?` is one piece) that shrinks and ends in "…". The reverse
+is the same change: a button that grew past its container now truncates.
+The ellipsis needs the text as the button's own child: with `as-child`, text
+inside the child element is clipped without one.
+**Fix:** update. Then pick, for each long label: leave the ellipsis (give a
+`title` so a sighted user can read it whole; the accessible name already
+is), let it break onto lines with `wrap`, or give the button a width of
+your own through `class`. With `as-child`, put the label in a `<span>`:
+
+```vue
+<template>
+  <Button title="Continue to the payment details">Continue to the payment details</Button>
+  <Button wrap>Continue to the payment details and confirm the order</Button>
+  <Button class="w-full">Continue</Button>
+  <Button as-child>
+    <a href="/pay"><span>Continue to the payment details</span></a>
+  </Button>
+</template>
+```
+
+## Feedback
+
+### A toast with an action never goes away
+
+**When:** a test, or a user, waits for a toast to disappear by itself, and one
+that carries an `action` (`toast({ action })`, or `toasts.info({ action })`
+and the other presets with your own action) is still there.
+**Why:** a toast with an `action` is persistent: `toast()` sets
+`options.duration` to `Infinity` (WCAG 2.2.1: a timed toast can vanish before
+a keyboard or screen-reader user reaches its button). Without an `action` a
+preset times out after 5 seconds.
+**Fix:** pass a duration, or close it:
+
+```ts
+toasts.info({ action, options: { duration: 8000 } }); // times out again
+toasts.dismiss(id); // or toasts.dismiss() for all of them
+```
+
+Users close it with its X button (named "Close", or "Fermer" in French),
+with Escape while focus is inside it, or with the action itself. In a test,
+click `getByRole('button', { name: 'Close' })` or call `toasts.dismiss()`.
+
+### A toast covers the form's button on a phone
+
+**When:** on a phone, a toast shows across the bottom of the screen, over a
+form's submit button (or anything else kept at the bottom), until it goes.
+**Why:** under 600px wide, vue-sonner lays toasts out across the whole width,
+and its default `position` is `bottom-right`, so the bottom of the screen. The
+`Toaster` now shows them at the top (`top-center`) on a phone when it is given
+no `position`; it still covers the bottom when the app mounts vue-sonner's own
+`Toaster` (`import { Toaster } from 'vue-sonner'`), or passes a bottom
+`position`, which applies on every screen.
+**Fix:** mount the `Toaster` from `@nxgt/material-vue/components`, and drop a
+bottom `position` unless the bottom is what you want on phones too. When a
+sticky header must stay visible above the toasts, raise the phone offset's
+`top`:
+
+```vue
+<Toaster />                          <!-- top-center on a phone -->
+<Toaster :mobile-offset="{ top: 72 }" />
+<Toaster position="bottom-center" /> <!-- bottom-center on every screen -->
+```
+
+### A toast never goes away after a tap
+
+**When:** on a phone (or any touch screen), a toast that should time out stays
+on the screen after the user tapped it, and only goes after a tap somewhere
+else.
+**Why:** a toast pauses while a mouse hovers it (WCAG 2.2.1). After a tap, the
+browser emulates a mouse that arrives over the toast and never leaves, and
+vue-sonner read that as a hover, so the toast stayed paused.
+**Fix:** update, and mount the `Toaster` from `@nxgt/material-vue/components`:
+it ignores the hover a tap emulates (`@nxgt/material-core/touch-hover`), so a
+tapped toast pauses while the finger is down and goes after its duration; a
+mouse still pauses it. vue-sonner's own `Toaster`
+(`import { Toaster } from 'vue-sonner'`) keeps the old behaviour. A toast with an
+`action` is meant to stay: see
+[A toast with an action never goes away](#a-toast-with-an-action-never-goes-away).
+
+### A toast's action cannot be clicked while a dialog is open
+
+**When:** a toast with an `action` (or a close button) shows over an open
+`Dialog`, `AlertDialog`, `Sheet` or `Drawer`: the pointer does nothing on it,
+or a click on it closes the dialog.
+**Why:** a modal layer sets `pointer-events: none` on `<body>`, and the
+`Toaster` inherited it, so its toasts could not be clicked; the layer also
+counted a pointer down on a toast as outside the dialog.
+**Fix:** update `@nxgt/material-vue` and mount its `Toaster`: it sets
+`pointer-events: auto`, and the modal contents treat a pointer down or a focus
+inside the `Toaster` as inside, so the action runs and the dialog stays open.
+Sonner's own `Toaster` keeps the old behaviour.
+
+### A `ConfirmationDialog` reopened at once stays closed
+
+**When:** a `ConfirmationDialog` with `v-model:open` (or `:open` and
+`@update:open`) closes on Confirm and your `update:open` handler sets `open`
+back to `true` in the same tick, to show the next step. `open` is `true`, the
+dialog is shut, and setting `open = true` again does nothing. Giving the
+dialog a `:key` per step made it go away.
+**Why:** the dialog kept its own copy of `open`, synced by a watch. Set to
+`false` then `true` before Vue flushed, `open` never changed as far as the
+watch could see, and the copy stayed `false`.
+**Fix:** update: a dialog whose parent listens to `update:open` now shows
+exactly what `open` says. No `:key` needed; one dialog whose `title` follows
+the step is enough:
+
+```vue
+<ConfirmationDialog
+  v-model:open="open"
+  :title="steps[step].title"
+  @confirm="step === 0 ? (step = 1, (open = true)) : finish()"
+/>
+```
+
+Reopened a little later (after an `await`), it already worked, and no overlay
+is left above the content: reka keeps the overlay and the content in one
+teleport, in order.
+
+### The first Escape after closing a nested dialog does nothing
+
+**When:** an `AlertDialog` (a `ConfirmationDialog`, a `Dialog`, a `Sheet` or a
+`Drawer`) opened over another overlay — a `Sheet` with a Delete that asks for
+confirmation — is closed with Escape or Cancel, and the user presses Escape
+again at once to close the `Sheet` too. The `Sheet` stays open; a second
+Escape, a moment later, closes it. A test that presses Escape twice in a row
+fails the same way.
+**Why:** reka hands Escape to the highest overlay only, and a dialog stops
+being one when its content leaves the page, not when it closes (with
+`unmountOnHide`, its default). The closed alert stays on the page for its
+exit animation (200ms for a dialog, 300ms for a sheet, 500ms for a drawer):
+an Escape pressed meanwhile went to it, and it was already closed.
+**Fix:** update: `AlertDialogContent`, `DialogContent`, `SheetContent` and
+`DrawerContent` now press Escape again, for the overlay below, once a
+content that was closing has left. Nothing to change in your code. Your
+`@escape-key-down` still runs first, on both presses; preventing the default
+while yours is closing keeps the key from being forwarded:
+
+```vue
+<AlertDialog v-model:open="confirm">
+  <!-- closing: the Sheet stays open -->
+  <AlertDialogContent @escape-key-down="(event) => !confirm && event.preventDefault()">
+    …
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+With no overlay below, the forwarded Escape reaches the page's own `keydown`
+handlers; an app shortcut that should ignore it can check `event.isTrusted` or
+`event.defaultPrevented`.
+
+In a test, wait for the `Sheet` to leave the DOM (the forwarded Escape lands
+a few frames after the alert has gone) and look it up by selector rather
+than by role: the closing alert still hides the page from the accessibility
+tree.
+
+## Navigation
+
+### A `ListTile` link reloads the whole page
+
+**When:** a `ListTile` with an `href` is clicked inside a router app: the
+browser loads the document again, the page flashes, and client state is lost.
+**Why:** by default the tile renders a plain `<a href>`, which needs no router
+and so cannot navigate on the client.
+**Fix:** pass `link-component`, with the same contract as the app shell's: a
+component that takes `href` and lets the other attributes fall through to its
+root. `RouterLink` takes `to`, so wrap it:
+
+```ts
+// app-link.ts
+import { defineComponent, h } from 'vue';
+import { RouterLink } from 'vue-router';
+
+export const AppLink = defineComponent({
+  props: { href: { type: String, required: true } },
+  setup:
+    (props, { slots, attrs }) =>
+    () =>
+      h(RouterLink, { ...attrs, to: props.href }, slots),
+});
+```
+
+```vue
+<ListTile title="Notifications" href="/settings/notifications" :link-component="AppLink" />
+```
+
+### The phone menu needs two Escapes to close, or a tooltip shows over it
+
+**When:** on a phone, the menu sheet of `ActivityLayout` or `AppHeader` opens
+with a tooltip repeating the first entry's label over the menu, and a plain
+open sheet needs two Escapes to close: the first one closes the tooltip.
+**Why:** the entries of the sheet's expanded sidebar carried a tooltip, and
+focus lands on the first entry as the sheet opens, which opened its tooltip;
+the tooltip's own layer takes the first Escape.
+**Fix:** update `@nxgt/material-vue`. An entry of an expanded `Sidebar` now shows no
+tooltip, since it shows its label; a collapsed one keeps it, and an explicit
+`tooltip` is always shown. A `SidebarMenuItem` of your own needs no change.
+
 ## SSR & build
 
 ### `ReferenceError: window is not defined`
@@ -958,6 +1566,61 @@ const { value, handleBlur } = useField<string>('nickname');
 What counts as leaving, per kind of field:
 [forms](guides/forms.md#touched-on-blur).
 
+### A failed submit does not focus the first invalid field
+
+**When:** `handleSubmit` fails validation (or you call `setFieldError`) and
+focus stays on the submit button, with the error out of view. There is no
+`shouldFocusError` option to turn on.
+**Why:** vee-validate never moves focus: `handleSubmit(onValid, onInvalid)`
+only reports `{ errors }`. (React Hook Form focuses by itself; that is a
+React-only behaviour.)
+**Fix:** from the release that lists this fix in its changelog, every
+`*FormField` marks its element with
+`data-field-name="<name>"`, and `focusFirstInvalid` / `focusField` from
+`@nxgt/material-vue/lib` use it to focus the first control a user can reach in
+the field, whatever its shape (an input, a select trigger, the first chip, a
+file picker's button):
+
+```vue
+<script setup lang="ts">
+import { focusField, focusFirstInvalid } from '@nxgt/material-vue/lib';
+import { useForm } from 'vee-validate';
+
+const { handleSubmit, setFieldError } = useForm();
+const onSubmit = handleSubmit(save, ({ errors }) => focusFirstInvalid(errors));
+
+// A server error on one field:
+// setFieldError('email', 'Already used'); focusField('email');
+</script>
+```
+
+`focusFirstInvalid(errors)` takes the first field **in page order** that has
+an error, not the first key of `errors`. Pass a `scope` element as the last
+argument to look inside one form of a page that has several. A field that is
+not mounted (a closed tab) cannot take focus: the function returns `false`.
+
+### A test that finds a chip by `aria-selected` or `getByRole('option')` no longer finds it
+
+**When:** after upgrading past the release that lists this fix, a test (or
+an end-to-end locator) that picked a `SelectChipField` chip with
+`[aria-selected="true"]`, `getByRole('option', { name })` or
+`toHaveAttribute('aria-selected', 'true')` finds nothing, and the same for
+`SelectChipFormField`.
+**Why:** the chips are toggle buttons: `aria-selected` is not allowed on a
+button, so a chosen chip is now `aria-pressed="true"`, in `single` mode too
+(pressing the chosen chip clears it). The chips sit in a `role="group"`
+named by the label and described by the help text. `SelectCardField` is
+unchanged.
+**Fix:** query the group, then the chip as a button:
+
+```ts
+import { screen, within } from '@testing-library/vue';
+
+const topics = screen.getByRole('group', { name: 'Topics' });
+const design = within(topics).getByRole('button', { name: 'Design' });
+expect(design).toHaveAttribute('aria-pressed', 'true');
+```
+
 ### A multi-step form reopens at a later step
 
 **When:** a wizard built on `defineStepFormStore` opens at the step (and with
@@ -1558,8 +2221,58 @@ z.config({ customError: zodLocaleError({ language: () => requestLanguage() }) })
 
 See [helpers](guides/helpers.md#zodlocaleerror-limits).
 
+### A calendar's weekday row is in English on a French page
+
+**When:** under `<I18nProvider>` set to French, a `DateField`,
+`DateRangeField` or `Calendar` shows "S", "M", "T"… and starts the week on
+Sunday.
+**Why:** before the calendar followed the provider's language, it took reka's
+default `en-US` locale, which shapes the weekday row and the first day of the
+week.
+**Fix:** update: a `Calendar`'s `locale` prop, else the `I18nProvider`
+language, else English drives the whole calendar, weekday row included ("L",
+"M"…, Monday first, each header labelled "lundi"…). `DateField` and
+`DateRangeField` follow the provider; to force another language on one
+calendar, pass `locale`:
+
+```vue
+<Calendar v-model="date" locale="en" />
+```
+
+reka hides the weekday row from assistive tech (`<thead aria-hidden>`); in a
+test, find a day by its full date instead
+(`getByRole('gridcell', { name: 'jeudi 1 octobre 2026' })`).
+
 ## Runtime
 
+### A test asserting the old Zod string length text fails
+
+**When:** after upgrading past the release that lists this fix, a test or a
+snapshot that asserted a string length message from `zodLocaleError` fails:
+it expected `This value is too small: it must be at least 3 characters.`
+(French `Cette valeur est trop petite : …`) and gets `Must contain at least 3
+characters.` (`Doit contenir au moins 3 caractères.`).
+**Why:** a string's `min` and `max` read as a length now, through
+the keys `material.zod.too_small_string_inclusive` / `_exclusive` and
+`material.zod.too_big_string_inclusive` / `_exclusive`, which pluralize the
+count: `z.string().min(1)` says `Must contain at least 1 character.` /
+`Doit contenir au moins 1 caractère.`. A number, a list, a set or a file
+keeps the "too large / too small" wording. A French `invalid_format` noun
+opens with a capital too (`Adresse e-mail invalide.`).
+**Fix:** update the expected text, or override the new keys in your app's
+`material.zod.*` resources to keep your own wording (an override of
+`too_small_inclusive` no longer applies to strings):
+
+```json
+{
+  "material": {
+    "zod": {
+      "too_small_string_inclusive": "At least {minimum, plural, one {# character} other {# characters}}, please."
+    }
+  }
+}
+```
+
 ### `must be used within` / `must be used inside`
 
 **When:** on render, from a part of a widget or a context composable used
@@ -1642,8 +2355,34 @@ try {
 ```
 
 Serve the app over `https` (or `localhost`) in any environment where copying
-must work. `CopyButton` does not throw: it uses `@vueuse/core`'s
-`useClipboard`, and in an insecure context it silently copies nothing.
+must work. `CopyButton` does not throw: it awaits the same write and, in an insecure
+context or when the clipboard refuses it, shows "Copy failed" ([details](#a-test-no-longer-finds-copybutton-by-copied-or-its-name-changes)).
+
+### A test no longer finds `CopyButton` by "Copied", or its name changes
+
+**When:** a test clicks a `CopyButton` and looks for a button named
+`Copied`, or reads the tooltip, or the copy "succeeds" in a page where the
+clipboard is not available.
+**Why:** the button's accessible name is now always its `label` (`Copy`). The
+outcome is a visually hidden `role="status"` (polite) region next to the
+button, so a screen reader announces it without a rename. "Copied" shows only
+after the clipboard write resolved; a rejected write (permission denied, an
+insecure origin, no Clipboard API) shows "Copy failed" (`failed-label`,
+`material.copy.failed`).
+**Fix:** stub the clipboard and read the status next to the button. A bare
+`getByRole('status')` is ambiguous: every `CopyButton` renders one, and so do
+`Banner`, `DataTable` and the skeletons.
+
+```ts
+Object.defineProperty(navigator, 'clipboard', {
+  configurable: true,
+  value: { writeText: vi.fn().mockResolvedValue(undefined) }, // or mockRejectedValue(new Error('denied'))
+});
+const button = screen.getByRole('button', { name: 'Copy' });
+await user.click(button);
+// the parent is the CopyButton's own root
+expect(await within(button.parentElement!).findByRole('status')).toHaveTextContent('Copied');
+```
 
 ### `Upload failed with status 403`
 
@@ -1973,7 +2712,9 @@ await expect(volume).toHaveAttribute('aria-invalid', 'true');
 **When:** with 0.21.0 or earlier, an `AlertDialogContent` whose
 `@open-auto-focus` calls `event.preventDefault()` still moves focus to its
 `AlertDialogCancel` a moment after opening, where `DialogContent`,
-`SheetContent` and `DrawerContent` keep focus where it was.
+`SheetContent` and `DrawerContent` leave it to you (where focus then goes
+behind a modal layer: [Focus moves into a dialog although
+`@open-auto-focus` prevented it](#focus-moves-into-a-dialog-although-open-auto-focus-prevented-it)).
 **Why:** reka focuses the Cancel a tick after the alert dialog opens without
 checking whether the event was prevented, and the dialog's focus trap then
 keeps focus inside.
@@ -1990,6 +2731,29 @@ takes no focus until the next task: focus it from a `setTimeout` if you want it.
 <AlertDialogContent @open-auto-focus="(event) => event.preventDefault()">
 ```
 
+### Focus moves into a dialog although `@open-auto-focus` prevented it
+
+**When:** a modal `Dialog`, `Sheet`, `Drawer` or `AlertDialog` whose
+`@open-auto-focus` calls `event.preventDefault()` and focuses nothing: focus
+lands on the layer's content, not on the element that had it before it
+opened.
+**Why:** the page behind a modal layer is `inert`, and an inert element
+cannot keep focus: the browser would drop it on `<body>`, where a keyboard
+or screen-reader user is nowhere. The layer takes it instead (its content
+has `tabindex="-1"`); closing still hands focus back to the element that
+opened it.
+**Fix:** focus what you want inside the layer in the handler; to keep
+focus on the page behind, make the layer non-modal (`:modal="false"` on
+`Dialog`, `Sheet` or `Drawer`):
+
+```vue
+<DialogContent
+  @open-auto-focus="(event) => { event.preventDefault(); nameInput?.focus(); }"
+>
+  <input ref="nameInput" aria-label="Name" />
+</DialogContent>
+```
+
 ### A `CustomDialog` or `ConfirmationDialog` no longer opens from its `#trigger`
 
 **When:** after upgrading to 0.22.0, clicking what you put in the `#trigger`
@@ -2164,6 +2928,41 @@ Anything else that must not make the row follow its link on a click (a custom wi
 />
 ```
 
+### A double click or Enter submits a form twice, or a test no longer finds a loading `Button` disabled
+
+**When:** a sign-in or save form is submitted twice by a quick double click,
+or by Enter pressed twice in a field, although its submit button has
+`loading`; or `<Button as-child loading><a @click="save">` still calls
+`save`. Or, after upgrading, a test expecting a loading `Button` to be
+`disabled` (or to skip it with Tab) fails.
+**Why:** a `loading` that turns true only after an `await` (a mutation's
+pending flag behind an async check) left a window for the second click. And a
+loading `Button` used to set the native `disabled`, which drops focus to
+`<body>` while the form works. It now sets `aria-busy="true"` and
+`aria-disabled="true"` and cancels every click before your `@click` — the
+click Enter in a field sends to the form's submit button included — so
+neither your handler, an `as-child` child's nor an ancestor's runs, and stays
+focusable, as `@nxgt/material`'s does. With `as-child` the busy attributes,
+the click guard and the spinner land on the child element: the spinner goes
+inside it, and the child stays the same element (focus, your template ref)
+while `loading` turns on and off.
+**Fix:** pass `useForm`'s `isSubmitting`, which is true as soon as
+`handleSubmit` starts; for a `loading` that turns true later, add
+`lock-on-click`. In a test, check the busy state, not `disabled`:
+
+```vue
+<Button type="submit" :loading="isSubmitting">Sign in</Button>
+<Button type="submit" :loading="isPending" lock-on-click>Sign in</Button>
+```
+
+```ts
+expect(screen.getByRole('button', { name: 'Sign in' })).toHaveAttribute('aria-busy', 'true');
+```
+
+A `form.requestSubmit()` of your own fires no click, so the guard does not
+see it: check `isSubmitting` before calling it (see
+[Forms](./guides/forms.md)).
+
 ### A `DataTable` shows a sorting or a selection the URL never got
 
 **When:** a `DataTable` has `:sorting` (or `:row-selection`) bound to state you derive from the URL, with no `@update:sorting` (or `@update:row-selection`), and clicking a header changes the arrow while the rows and the URL stay as they were.
@@ -2181,6 +2980,49 @@ Anything else that must not make the row follow its link on a click (a custom wi
 />
 ```
 
+### A `DataTable` no longer scrolls inside a 400px box
+
+**When:** after upgrading, a long `DataTable` is as tall as its rows and the page scrolls, where its rows used to scroll inside a box about 400px tall.
+**Why:** the table capped its own height (`max-h-[400px]` on `[data-slot="table-wrapper"]`, and viewport-based caps on it and on `[data-slot="data-table"]` in the stylesheet). On a phone that made a scroll inside the page's scroll, so the cap is now opt-in.
+**Fix:** pass `max-height` (a number of pixels, or any CSS length) where the table should scroll inside a box:
+
+```vue
+<DataTable :data="rows" :columns="columns" :max-height="400" />
+```
+
+`max-height` is the supported way: it also keeps the header row in view while the rows scroll. A `max-height` rule of your own on `[data-slot="table-wrapper"]` still works, and the box still becomes the named, focusable scroll region once it overflows.
+
+### A `DataTable` shows its header row on a phone
+
+**When:** after upgrading, a `DataTable` under 768px wide shows its header row, which it used to hide.
+**Why:** without the header a phone lost the column names, sorting and "Select all", so the header now shows at every width. The table scrolls sideways, in its own region, when the columns do not fit.
+**Fix:** nothing, usually. To hide it again, pass `show-header` — `false` everywhere, or your own breakpoint:
+
+```vue
+<DataTable :data="rows" :columns="columns" :show-header="false" />
+<DataTable :data="rows" :columns="columns" :show-header="!isPhone" />
+```
+
+### A test's `getByRole('region')` finds more than one region
+
+**When:** a test or an axe check runs on a page with a `DataTable` wider than its box, and a query for the `region` role now also finds the table.
+**Why:** while its content overflows, the table's scroll box (`[data-slot="table-wrapper"]`) is a keyboard-focusable `region` named "Scrollable table" (`material.table.labels.scroll-region`), so a keyboard user can scroll it (axe `scrollable-region-focusable`). It is not a region while it fits, nor on the server.
+**Fix:** query your region by name, and give the table a name of its own where a page holds several:
+
+```vue
+<DataTable :data="rows" :columns="columns" scroll-label="Invoices" />
+```
+
+```ts
+page.getByRole('region', { name: 'Invoices' });
+```
+
+### A `DataTable` toolbar is gone
+
+**When:** a `DataTable` is given `actions` or an `#actions` slot that renders nothing (a `v-if` left out, `null`), and a test looked for the toolbar's `fieldset` (`[data-slot="header"]`).
+**Why:** the toolbar is rendered only when it has content (yours, or `show-view-options`): an empty `<fieldset>` is a nameless group to a screen reader.
+**Fix:** look for what the toolbar holds (a filter by its label, the view options by "View"), not for the `fieldset` itself. A component of yours that renders nothing still counts as content: render it conditionally instead.
+
 ---
 
 ---