@nxgt/material 2.7.1 → 2.8.0

package/docs/troubleshooting.md

@@ -19,6 +19,26 @@ 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)
+
+**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 with new content blocks clicks](#a-confirmationdialog-reopened-with-new-content-blocks-clicks)
+- [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**
 
@@ -73,18 +93,24 @@ 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)
 - [`Camera components must be used inside <Camera>`](#camera-components-must-be-used-inside-camera)
 - [`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)
+- [`` Cannot update a component (`DataTable`) while rendering a different component ``](#cannot-update-a-component-datatable-while-rendering-a-different-component)
 - [`Failed to execute 'exitFullscreen' on 'Document': Document not active`](#failed-to-execute-exitfullscreen-on-document-document-not-active)
 - [A `SwitchFormField` shows no validation message](#a-switchformfield-shows-no-validation-message)
 - [A `TimeFormField` shows its error on a desktop but not on a phone](#a-timeformfield-shows-its-error-on-a-desktop-but-not-on-a-phone)
+- [`setError(…, { shouldFocus: true })` or a failed submit does not focus the field](#seterror--shouldfocus-true--or-a-failed-submit-does-not-focus-the-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)
 - [`touchedFields` stays empty after leaving a field, or `mode: 'onBlur'` never validates](#touchedfields-stays-empty-after-leaving-a-field-or-mode-onblur-never-validates)
 - [`TypeError: values.map is not a function` (a `SliderFormField`)](#typeerror-valuesmap-is-not-a-function)
 - [An end-to-end test no longer finds `aria-expanded` on a `ResponsiveButton`](#an-end-to-end-test-no-longer-finds-aria-expanded-on-a-responsivebutton)
@@ -104,20 +130,36 @@ words in your error.
 - [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 `CheckboxGroup`](#a-test-no-longer-finds-aria-invalid-on-a-checkboxgroup)
 - [A test no longer finds `aria-invalid` on a `Switch` row or an `Autocomplete`'s chips](#a-test-no-longer-finds-aria-invalid-on-a-switch-row-or-an-autocompletes-chips)
+- [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)
+- [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 `className` on `ActivityLayout` now styles the whole shell](#a-classname-on-activitylayout-now-styles-the-whole-shell)
+- [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 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)
+- [A test no longer finds a calendar day by its number, or by "Today" or "selected"](#a-test-no-longer-finds-a-calendar-day-by-its-number-or-by-today-or-selected)
 - [`#<name>` no longer finds a `SwitchFormField` or `CheckboxFormField`](#name-no-longer-finds-a-switchformfield-or-checkboxformfield)
 - [`#<name>` or `#<option value>` no longer finds a radio or checkbox group or one of its options](#name-or-option-value-no-longer-finds-a-radio-or-checkbox-group-or-one-of-its-options)
+- [`#<name>` no longer finds a text, OTP, number, date or picker form field, or a second form's field has no name](#name-no-longer-finds-a-text-otp-number-date-or-picker-form-field-or-a-second-forms-field-has-no-name)
+- [A double click or Enter submits a form twice, or a test finds `aria-busy` in an idle `Button`](#a-double-click-or-enter-submits-a-form-twice-or-a-test-finds-aria-busy-in-an-idle-button)
 - [An empty `UploadField` or `TimeField` is no longer tinted](#an-empty-uploadfield-or-timefield-is-no-longer-tinted)
 - [`ConfirmDialog` buttons stay in English](#confirmdialog-buttons-stay-in-english)
 - [A `ConfirmationDialog` opened with `open` no longer closes](#a-confirmationdialog-opened-with-open-no-longer-closes)
 - [A menu item selected by `[data-variant=destructive]` stops matching](#a-menu-item-selected-by-data-variantdestructive-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 `Stepper` step selected by `#step-N` stops matching](#a-stepper-step-selected-by-step-n-stops-matching)
 - [Keys typed right after opening a dialog, sheet or drawer land inside it](#keys-typed-right-after-opening-a-dialog-sheet-or-drawer-land-inside-it)
+- [Focus moves into a dialog although `onOpenAutoFocus` prevented it](#focus-moves-into-a-dialog-although-onopenautofocus-prevented-it)
 - [A `TimePicker` test expects AM / PM to add 12 hours, or a click on the pressed half to switch to PM](#a-timepicker-test-expects-am--pm-to-add-12-hours-or-a-click-on-the-pressed-half-to-switch-to-pm)
 - [Focus is no longer in a `Tree` after it renders](#focus-is-no-longer-in-a-tree-after-it-renders)
 - [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 `onRowClick` ran](#a-row-does-not-navigate-after-onrowclick-ran)
 - [A `DataTable` Previous or Next button is disabled](#a-datatable-previous-or-next-button-is-disabled)
+- [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**
 
@@ -332,6 +374,386 @@ public/assets/icons/sprites/sharp-solid.svg ← <Icon name="atom" family="sharp"
 
 Serve one sheet per style you use, from your own Font Awesome Pro kit.
 
+### 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 `className` 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` (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 sonner styles itself still fades in from opacity 0: a plain
+`toast('…')` or `toast.success('…')` from `sonner`, or `sonnerToast` from this
+package. Show it 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:** Radix 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 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 Radix 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:
+
+```tsx
+import { inertOthers } from '@nxgt/material-core/inert-others';
+
+// content: your layer's content element, in state (a callback ref).
+useEffect(
+	() => (open && content ? inertOthers(content) : undefined),
+	[open, content],
+);
+```
+
+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:
+
+```tsx
+// before: the tone is replaced by the raw token
+<Button variant="tonal" color="error" className="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 `className` 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:
+
+```tsx
+// before
+<p className="text-sm text-error">Enter a valid email</p>
+// after
+<p className="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 `asChild`, 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 `className`. With `asChild`, put the label in a `<span>`:
+
+```tsx
+<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 className="w-full">Continue</Button>
+<Button asChild>
+	<a href="/pay"><span>Continue to the payment details</span></a>
+</Button>
+```
+
+## 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, 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 Sonner's own
+`Toaster` (`import { Toaster } from 'sonner'`), or passes a bottom `position`,
+which applies on every screen.
+**Fix:** mount the `Toaster` from `@nxgt/material/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`:
+
+```tsx
+<Toaster />                          // top-center on a phone
+<Toaster mobileOffset={{ 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
+Sonner read that as a hover, so the toast stayed paused.
+**Fix:** update, and mount the `Toaster` from `@nxgt/material/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. Sonner's own `Toaster`
+(`import { Toaster } from '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` 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 with new content blocks clicks
+
+**When:** a `ConfirmationDialog` or a `ConfirmDialog` (or a `Dialog`,
+`AlertDialog` or `Sheet` of your own) closes on Confirm and your page opens it
+again straight away with the next step's title and text. The second dialog
+shows, but its Confirm does nothing: a click lands on the dimmed overlay.
+Giving the dialog a `key` per step made it go away.
+**Why:** Radix portals the overlay and the content to `<body>` separately, and
+each leaves when its own exit animation ends: the overlay's (150ms) before the
+content's (200ms for a dialog, 300ms for a sheet). Reopened between the two,
+the new overlay was appended after the content still on the page and, at the
+same `z-index`, painted over it. Nothing was left behind once both closed:
+`<body>` got its `pointer-events` back.
+**Fix:** update: the overlay is now kept under its content. The `key` is no
+longer needed; one dialog whose `title` follows the step is enough:
+
+```tsx
+const [step, setStep] = useState(0);
+const [open, setOpen] = useState(false);
+
+<ConfirmationDialog
+  open={open}
+  onOpenChange={setOpen}
+  title={steps[step].title}
+  onConfirm={async () => {
+    if (step === 0) {
+      setStep(1);
+      await saveDraft(); // the dialog has closed; reopen it with step 2
+      setOpen(true);
+    }
+  }}
+/>
+```
+
+### 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:** Radix hands Escape to the highest overlay only, and an overlay stops
+being one when its content leaves the page, not when it closes. 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. Moving focus back to the `Sheet` sooner would not help:
+Radix listens for Escape on the document, wherever focus is.
+**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
+`onEscapeKeyDown` still runs first, on both presses; preventing the default
+while yours is closing keeps the key from being forwarded:
+
+```tsx
+const [confirm, setConfirm] = useState(false);
+
+<AlertDialog open={confirm} onOpenChange={setConfirm}>
+  <AlertDialogContent
+    onEscapeKeyDown={(event) => {
+      if (!confirm) event.preventDefault(); // closing: the Sheet stays open
+    }}
+  >
+    …
+  </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 `linkComponent`, with the same contract as the app shell's: it
+takes `href`, spreads every other prop and forwards `ref`. React Router's
+`Link` takes `to`, so wrap it:
+
+```tsx
+import { Link } from 'react-router';
+import type { AppShellLinkComponent } from '@nxgt/material/components';
+import { ListTile } from '@nxgt/material/components';
+
+// Hoisted, outside the render: not a new component on every render.
+const RouterLink: AppShellLinkComponent = ({ href, ...props }) => (
+  <Link to={href} {...props} />
+);
+
+<ListTile title="Notifications" href="/settings/notifications" linkComponent={RouterLink} />
+```
+
+### 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`. 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`
@@ -1184,8 +1606,59 @@ z.config({ customError: zodLocaleError({ storageKey: 'lang', translate }) });
 z.config({ customError: zodLocaleError({ language: () => requestLanguage() }) });
 ```
 
+### A calendar's weekday row is in English on a French page
+
+**When:** under `<I18nProvider>` set to French, a `DateField`,
+`DateRangeField` or `Calendar` names its days in French but its weekday row
+reads "Su", "Mo"… and the week starts on Sunday.
+**Why:** before the calendar followed the provider's language, it took
+react-day-picker's default English `locale`, which shapes the weekday row
+("cccccc"), its labels ("Monday") and the first day of the week.
+**Fix:** update: the `locale` prop, else the `I18nProvider` language, else
+English drives the whole calendar, weekday row included ("lu", "ma"…, Monday
+first, each header labelled "lundi"…). To force another language on one
+calendar, pass its date-fns locale:
+
+```tsx
+import { enUS } from 'react-day-picker/locale';
+
+<DateField locale={enUS} label="Delivery date" value={date} onValueChange={setDate} />
+```
+
+react-day-picker 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 sub-component or a context hook used outside the
@@ -1299,7 +1772,34 @@ try {
 ```
 
 Serve the app over `https` (or `localhost`) in any environment where copying
-must work. `CopyButton` does not throw. It uses a different clipboard fallback.
+must work. `CopyButton` does not throw: it awaits the same write and, 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" (`failedLabel`,
+`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 holds the button and its status; wrap a CopyButton that has siblings
+expect(await within(button.parentElement!).findByRole('status')).toHaveTextContent('Copied');
+```
 
 ### `Upload failed with status 403`
 
@@ -1342,6 +1842,30 @@ Apply it on the bucket, with your own origin.
 <FilterProvider schema={schema} presetConfig={{ enabled: true, maxPresets: 50 }}>
 ```
 
+### `` Cannot update a component (`DataTable`) while rendering a different component ``
+
+**When:** in the dev server's console, in an end-to-end run, now and then,
+mostly in Firefox under Playwright, after a `DataTable` got new `data` (a page,
+a search). The other component varies (`CheckboxProvider`, `Presence`, a
+`DataTableRow`, a column header), and a production build names them with
+minified names (a minified name stands for `DataTable`). The same run may log
+it for `RouterProvider` too.
+
+**Why:** TanStack Table resets the expanded rows in a microtask after `data`
+changes. Before the fix, `DataTable` set its state for that reset even when no
+row was expanded; in a browser that runs pending microtasks while React
+renders, that update landed during another component's render and React
+warned. The `RouterProvider` one is React Router's route discovery resolving
+at the same moment: the same browser behaviour, not something the app or the
+table does.
+
+**Fix:** upgrade to the `@nxgt/material` release that lists this fix in its
+changelog: `DataTable` no longer sets state when no row is expanded, so the
+reset cannot land as an update during another component's render. Nothing to
+change in the app when no row is expanded; with a row expanded, a new `data`
+still resets it, and the warning can still appear. If it still names
+`RouterProvider`, it is harmless and outside `DataTable`.
+
 ### `Failed to execute 'exitFullscreen' on 'Document': Document not active`
 
 **When:** as an unhandled promise rejection in the console (or a failing test
@@ -1394,6 +1918,63 @@ on a desktop and on a phone alike: closing the picker with OK hands focus back
 to the trigger, and the next Tab or click elsewhere touches it. See the next
 entry.
 
+### `setError(…, { shouldFocus: true })` or a failed submit does not focus the field
+
+**When:** a form wired with `*FormField`s: `handleSubmit` fails validation, or
+you call `form.setError('email', { message }, { shouldFocus: true })`, and
+focus stays where it was. Before the release that lists this fix only: every
+`*FormField` (and the config-driven `FormField`), the plain text inputs
+included, ignored `shouldFocusError`, `setError(…, { shouldFocus: true })` and
+`setFocus(name)`.
+**Why:** React Hook Form focuses a field by calling `focus()` on the `ref`
+that `Controller` gives to `field.ref`. The wrappers did not hand it to any
+element, so React Hook Form had nothing to focus (and `setFocus('email')` did
+nothing either).
+**Fix:** upgrade to the release that lists this fix in its changelog: every `*FormField` (and `FormField`) forwards
+`field.ref`, to its input, or, for a field made of several controls, to a
+handle that focuses the first one a user can reach (the select's trigger, the
+first chip, the file picker's button, the first of the two date inputs). For
+a field of your own, give `field.ref` to the control:
+
+```tsx
+<Controller
+  control={control}
+  name="nickname"
+  render={({ field }) => <input {...field} />}
+/>
+```
+
+A form whose error is shown by a field that is not mounted (a closed tab, a
+collapsed section) cannot take focus: React Hook Form skips it silently, so
+open the section before calling `setError`.
+
+`setFocus(name)` uses the same `ref`, so a sign-in step that calls
+`setFocus('password')` or `setFocus('code')` on mount puts focus in its
+`PasswordFormField` or `OtpFormField` (Storybook: `Guides/Forms/Focus on
+error`, `Set Focus Password` and `Set Focus Otp`).
+
+### 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` and the config-driven `FormField` (`chips-single`, `chips-multiple`).
+**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/react';
+
+const topics = screen.getByRole('group', { name: 'Topics' });
+const design = within(topics).getByRole('button', { name: 'Design' });
+expect(design).toHaveAttribute('aria-pressed', 'true');
+```
+
 ### `touchedFields` stays empty after leaving a field, or `mode: 'onBlur'` never validates
 
 **When:** a `*FormField` keeps `formState.touchedFields` (and
@@ -1543,16 +2124,22 @@ await page.getByRole('slider', { name: 'Price Minimum' }).press('ArrowRight');
 
 **When:** after upgrading to 2.2.0, `getByRole('textbox', { name: 'Email*' })`
 (or any role query whose name ends in `*`) finds nothing for a field whose
-`Label` has `withAsterisk` (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 `withAsterisk` (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:
 
@@ -1568,6 +2155,12 @@ 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 end-to-end test no longer finds `aria-expanded` on a `ResponsiveButton`
 
 **When:** after upgrading to 2.2.0, a spec that selects
@@ -1888,6 +2481,23 @@ await expect(page.getByRole('switch', { name: 'Notifications' })).toHaveAttribut
 await expect(page.getByRole('combobox', { name: '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(screen.getByLabelText('Enter OTP')).toHaveAttribute('aria-invalid', 'true');
+// A slot's red border, if a test must see it:
+await expect(container.querySelector('[data-slot="input-otp-slot"]')).toHaveAttribute('data-invalid');
+```
+
 ### A test no longer finds the breadcrumb's home button
 
 **When:** after upgrading, `getByRole('button', { name: 'Home' })` finds
@@ -1906,6 +2516,137 @@ 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');
+```
+
+### 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"`:
+
+```tsx
+<ActivityLayout items={items} scroll="container">
+```
+
+### A `className` on `ActivityLayout` now styles the whole shell
+
+**When:** after upgrading, the classes passed to `<ActivityLayout className="…">`
+(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:** `className` used to land on the inner layout box; it now reaches the
+outer element, `[data-slot=activity-layout]`, with the other props.
+**Fix:** keep on `ActivityLayout` only the classes meant for the whole shell,
+and move the rest to the screen: `ActivityContent`'s `className`, or an
+element of your own inside it:
+
+```tsx
+<ActivityLayout items={items} className="bg-muted">
+  <ActivityContent title="Invoices" className="gap-6">…</ActivityContent>
+</ActivityLayout>
+```
+
+### 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` (it was a `div`); and the shell's content region is the
+page's `<main>`. The phone menu sheet had no name; 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 `titleAs` or `CardTitle`'s `as` (`'div'` for no heading). An app
+with its own `<main>` passes `contentAs="div"`.
+
+### `[data-test="typogaphy"]` finds nothing
+
+**When:** after upgrading, a selector on `data-test="typogaphy"` finds no
+`Typography`.
+**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 test no longer finds a tooltip on an entry of an expanded sidebar
+
+**When:** after upgrading, a test hovers or focuses a `SidebarMenuItem` of an
+expanded `Sidebar` (or an entry of the phone menu sheet) and waits for
+`getByRole('tooltip', { name: 'Inbox' })`, which never appears.
+**Why:** an entry's label is its tooltip only while the 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. A `tooltip` you pass
+is still shown, collapsed or expanded.
+**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 must
+have one:
+
+```tsx
+<SidebarMenuItem icon={<Inbox />} tooltip="3 unread">Inbox</SidebarMenuItem>
+```
+
+### A test no longer finds a calendar day by its number, or by "Today" or "selected"
+
+**When:** after upgrading, `getByRole('gridcell', { name: '1' })` or
+`getByRole('button', { name: 'Thursday, October 1st, 2026' })` finds nothing in
+a `Calendar`, `DateField`, `DateRangeField` or `EventCalendar`'s date picker; so
+do names with "Today, " or ", selected" in them; 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. "Today" and "selected" are no longer in
+the name: 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={enUS}` (from `react-day-picker/locale`) 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.
+
 ### `#<name>` no longer finds a `SwitchFormField` or `CheckboxFormField`
 
 **When:** after upgrading, a selector such as `#notifications`, or a
@@ -1950,6 +2691,68 @@ await page.locator('#married').getByRole('radio', { name: 'Yes' }).check();
 await page.locator('#married-0').check(); // the first option
 ```
 
+### `#<name>` no longer finds a text, OTP, number, date or picker form field, or a second form's field has no name
+
+**When:** two forms on one page have a field with the same `name` (a sign-in
+and a sign-up form both with `email`, two steps of a code check both with
+`code`), and the second field has no accessible name: its label points at the
+first form's input. Or, after upgrading, a selector such as `#email`, or a
+`<label htmlFor="email">` of your own, no longer reaches the input of
+`<TextFormField name="email">`.
+**Why:** the text-like wrappers (`TextFormField`, `TextareaFormField`,
+`EmailFormField`, `PasswordFormField`, `UrlFormField`, `NumberFormField`,
+`CurrencyFormField`, `PercentFormField`, `InputGroupFormField`,
+`PhoneFormField`, `OtpFormField`, `ColorFormField`, `TimezoneFormField`,
+`RatingFormField`, the date and time wrappers, `ComboboxFormField`,
+`AutocompleteFormField`, `TreeSelectFormField`, `FilesFormField`,
+`LocationFormField`) gave the control the field's `name` as its `id`, so two
+forms sharing a name had two elements with one `id`. Without an `id` of yours,
+the control now gets a generated one (`useId`), as the bare fields always did
+and as `@nxgt/material-vue` does.
+**Fix:** select by role and name, by `name`, or pass the `id` you rely on:
+
+```tsx
+await page.getByRole('textbox', { name: 'Email' }).fill('ada@example.com');
+await page.locator('[name="email"]').fill('ada@example.com');
+// or keep a fixed id
+<TextFormField control={control} name="email" id="sign-in-email" label="Email" />
+```
+
+### A double click or Enter submits a form twice, or a test finds `aria-busy` in an idle `Button`
+
+**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 asChild loading><a onClick={save}>` still calls
+`save`. Or, after upgrading, a markup assertion such as
+`expect(html).not.toContain('aria-busy')` fails on a `Button` that is not
+loading.
+**Why:** `loading` blocked clicks only once the busy state had rendered, a
+`loading` that turns true after an `await` (a mutation's `isPending` behind an
+async resolver) left a window for the second click, and an `asChild` child's
+own `onClick` ran before the guard. A loading `Button` now sets
+`aria-busy="true"` and `aria-disabled="true"` (it set neither before) and
+cancels every click in the capture phase — the click Enter in a field sends to
+the form's submit button included — so neither your handler, the child's nor
+an ancestor's runs. It still sets no native `disabled` and stays focusable.
+Busy buttons show a progress cursor: the class string of every `Button` now
+holds `aria-busy:cursor-progress`, which a plain `toContain('aria-busy')`
+matches.
+**Fix:** pass React Hook Form's `formState.isSubmitting`, which is true as soon
+as `handleSubmit` starts; for a `loading` that turns true later, add
+`lockOnClick`. In a test, check the attribute, not the string:
+
+```tsx
+<Button type="submit" loading={formState.isSubmitting}>Sign in</Button>
+<Button type="submit" loading={mutation.isPending} lockOnClick>Sign in</Button>
+
+expect(screen.getByRole('button', { name: 'Sign in' })).toHaveAttribute('aria-busy', 'true');
+expect(renderToStaticMarkup(<Button>Save</Button>)).not.toMatch(/\saria-busy=/);
+```
+
+A `form.requestSubmit()` of your own fires no click, so the guard does not
+see it: check `formState.isSubmitting` before calling it (see
+[Forms](./guides/forms.md)).
+
 ### An empty `UploadField` or `TimeField` is no longer tinted
 
 **When:** after upgrading, an `UploadField` showing its `placeholder`, or a
@@ -2023,6 +2826,21 @@ render `data-variant="error"`, and both use the `error` colour.
 [data-slot='menubar-item'][data-variant='error'] { font-weight: 600; }
 ```
 
+### 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: Radix'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 `Stepper` step selected by `#step-N` stops matching
 
 **When:** after upgrading to 2.5.0, a test or a stylesheet that targets a
@@ -2075,7 +2893,9 @@ await dialog.getByRole('button', { name: 'Save' }).click();
 
 To put focus on something else when an overlay opens, prevent the default in
 `onOpenAutoFocus` and focus it yourself; to keep focus where it was (a
-non-modal panel the user keeps typing behind), only prevent the default:
+non-modal panel the user keeps typing behind), only prevent the default — on
+a modal one focus then goes to its content, as the page behind is inert
+([details](#focus-moves-into-a-dialog-although-onopenautofocus-prevented-it)):
 
 ```tsx
 const saveButtonRef = useRef<HTMLButtonElement>(null);
@@ -2094,6 +2914,34 @@ const saveButtonRef = useRef<HTMLButtonElement>(null);
 A `Drawer` also takes Vaul's `autoFocus={false}`, which does the same as
 preventing the default.
 
+### Focus moves into a dialog although `onOpenAutoFocus` prevented it
+
+**When:** a modal `Dialog`, `Sheet`, `Drawer` or `AlertDialog` whose
+`onOpenAutoFocus` 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`):
+
+```tsx
+const nameRef = useRef<HTMLInputElement>(null);
+
+<DialogContent
+  onOpenAutoFocus={(event) => {
+    event.preventDefault();
+    nameRef.current?.focus();
+  }}
+>
+  <Input ref={nameRef} aria-label="Name" />
+</DialogContent>
+```
+
 ### A `TimePicker` test expects AM / PM to add 12 hours, or a click on the pressed half to switch to PM
 
 **When:** after upgrading to 2.6.0, a test (or code of yours) around a
@@ -2199,6 +3047,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 `maxHeight` (a number of pixels, or any CSS length) where the table should scroll inside a box:
+
+```tsx
+<DataTable data={rows} columns={columns} maxHeight={400} />
+```
+
+`maxHeight` 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 `showHeader` — `false` everywhere, or your own breakpoint:
+
+```tsx
+<DataTable data={rows} columns={columns} showHeader={false} />
+<DataTable data={rows} columns={columns} showHeader={!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:
+
+```tsx
+<DataTable data={rows} columns={columns} scrollLabel="Invoices" />
+```
+
+```ts
+page.getByRole('region', { name: 'Invoices' });
+```
+
+### A `DataTable` toolbar is gone
+
+**When:** a `DataTable` is given `actions` that render nothing (`() => null`, `false`), and a test looked for the toolbar's `fieldset` (`[data-slot="header"]`).
+**Why:** the toolbar is rendered only when it has content (yours, or `showViewOptions`): 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.
+
 ---
 
 ---