@nxgt/material 2.1.0 → 2.2.0

package/docs/troubleshooting.md

@@ -0,0 +1,2149 @@
+# Troubleshooting
+
+Each entry has the message you see (or the symptom, when nothing is printed) as
+its heading, then when it appears, why, and the fix. Search this page for the
+words in your error.
+
+## Index
+
+**Install**
+
+- [`Cannot find package '@react-pdf/renderer'`](#cannot-find-package-react-pdfrenderer)
+- [`Conflicting peer dependency: @react-pdf/renderer` (`ERESOLVE`)](#conflicting-peer-dependency-react-pdfrenderer)
+- [`Cannot find package 'leaflet'`](#cannot-find-package-leaflet)
+- [`Invalid hook call. Hooks can only be called inside of the body of a function component`](#invalid-hook-call-hooks-can-only-be-called-inside-of-the-body-of-a-function-component)
+- [`is missing the following properties from type 'Pick<any, "variant" | "color">'`](#is-missing-the-following-properties-from-type-pickany-variant--color)
+
+**Styles & assets**
+
+- [Components render unstyled, with no error](#components-render-unstyled-with-no-error)
+- [`<Icon>` renders nothing](#icon-renders-nothing)
+
+**SSR & build**
+
+- [`ReferenceError: window is not defined`](#referenceerror-window-is-not-defined)
+- [`ReferenceError: DOMMatrix is not defined`](#referenceerror-dommatrix-is-not-defined)
+- [`ReferenceError: document is not defined`](#referenceerror-document-is-not-defined)
+- [`Hydration failed because the server rendered HTML didn't match the client`](#hydration-failed-because-the-server-rendered-html-didnt-match-the-client)
+- [`A tree hydrated but some attributes of the server rendered HTML didn't match the client properties` (a `TimeField`)](#a-tree-hydrated-but-some-attributes-of-the-server-rendered-html-didnt-match-the-client-properties)
+- [`` `useMedia` When server side rendering, defaultState should be defined to prevent a hydration mismatches. ``](#usemedia-when-server-side-rendering-defaultstate-should-be-defined-to-prevent-a-hydration-mismatches)
+- [`useMatches must be used within a data router`](#usematches-must-be-used-within-a-data-router)
+
+**Printing**
+
+- [`Cannot find module '#standard-fonts/Helvetica'`](#cannot-find-module-standard-fontshelvetica)
+- [`still references '#standard-fonts/' after the transform`](#still-references-standard-fonts-after-the-transform)
+- [`Module '"@nxgt/material"' has no exported member 'PrintHeader'`](#module-nxgtmaterial-has-no-exported-member-printheader)
+- [`Module '"@nxgt/material"' has no exported member 'formatAmount'`](#module-nxgtmaterial-has-no-exported-member-formatamount)
+- [An amount in yen shows no decimals, or one in dinars shows three](#an-amount-in-yen-shows-no-decimals-or-one-in-dinars-shows-three)
+- [A date shows the day before](#a-date-shows-the-day-before)
+- [`Invalid hook call` in a `PrintDocument` `footer` function](#invalid-hook-call-in-a-printdocument-footer-function)
+- [Body text runs under the footer or the page number](#body-text-runs-under-the-footer-or-the-page-number)
+- [The `LOGO` box in `PrintHeader` is gone after upgrading](#the-logo-box-in-printheader-is-gone-after-upgrading)
+- [French amounts print with a slash, as in `1/234,50`](#french-amounts-print-with-a-slash-as-in-123450)
+- [An amount column prints `—` instead of the amount](#an-amount-column-prints--instead-of-the-amount)
+- [The table header does not repeat on the next page](#the-table-header-does-not-repeat-on-the-next-page)
+- [The PDF tab does not open](#the-pdf-tab-does-not-open)
+- [`renderToBuffer is a Node specific API`](#rendertobuffer-is-a-node-specific-api)
+- [`renderToStream is a Node specific API`](#rendertostream-is-a-node-specific-api)
+- [PDF rendering fails on an edge runtime](#pdf-rendering-fails-on-an-edge-runtime)
+- [`usePdfFile` renders on every render](#usepdffile-renders-on-every-render)
+- [`[pdf] No renderer for the custom node`](#pdf-no-renderer-for-the-custom-node)
+- [`[pdf] Unknown node type`](#pdf-unknown-node-type)
+- [`[pdf] Unsupported document version`](#pdf-unsupported-document-version)
+- [`'invoice' is of type 'unknown'` in a `definePdfDocument` template](#invoice-is-of-type-unknown-in-a-definepdfdocument-template)
+
+**Maps**
+
+- [The map has no controls, or its tiles are scattered](#the-map-has-no-controls-or-its-tiles-are-scattered)
+- [The browser asks for location permission when a map renders](#the-browser-asks-for-location-permission-when-a-map-renders)
+- [The map shows two zoom controls](#the-map-shows-two-zoom-controls)
+
+**i18n**
+
+- [`useI18nContext must be used within an I18nProvider`](#usei18ncontext-must-be-used-within-an-i18nprovider)
+- [`[@nxgt/material] i18n resource override for language`](#nxgtmaterial-i18n-resource-override-for-language)
+- [`[@nxgt/material] Unsupported language`](#nxgtmaterial-unsupported-language)
+- [`Hydration failed because the server rendered text didn't match the client`](#hydration-failed-because-the-server-rendered-text-didnt-match-the-client)
+- [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)
+
+**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)
+- [`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)
+- [`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)
+- [`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)
+- [A multi-step form reopens at a later step](#a-multi-step-form-reopens-at-a-later-step)
+- [An end-to-end test no longer finds a `LinkButton` by the `button` role](#an-end-to-end-test-no-longer-finds-a-linkbutton-by-the-button-role)
+- [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 a chip's remove button by the exact name `Remove`](#a-test-no-longer-finds-a-chips-remove-button-by-the-exact-name-remove)
+- [A test no longer finds a pagination, breadcrumb or other built-in label by its English name](#a-test-no-longer-finds-a-pagination-breadcrumb-or-other-built-in-label-by-its-english-name)
+- [A test no longer finds an icon badge by role `button`, or an `Icon` named "Icon {name}" inside a button](#a-test-no-longer-finds-an-icon-badge-by-role-button-or-an-icon-named-icon-name-inside-a-button)
+- [`An invalid form control with name='…' is not focusable` (an `UploadField`)](#an-invalid-form-control-with-name-is-not-focusable)
+- [A `DateField` or `DateRangeField` with `disabled` still opens](#a-datefield-or-daterangefield-with-disabled-still-opens)
+- [An `id`, `aria-describedby` or `data-testid` on a `DateField`, `DateRangeField` or `TimeField` is not on the trigger](#an-id-aria-describedby-or-data-testid-on-a-datefield-daterangefield-or-timefield-is-not-on-the-trigger)
+- [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)
+- [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 the breadcrumb's home button](#a-test-no-longer-finds-the-breadcrumbs-home-button)
+- [`#<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)
+- [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)
+- [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)
+
+**PDF reader**
+
+- [`'PdfViewer' is deprecated`](#pdfviewer-is-deprecated)
+- [Download saves the PDF as `document.pdf`](#download-saves-the-pdf-as-documentpdf)
+- [Download does nothing, or opens the PDF instead of saving it](#download-does-nothing-or-opens-the-pdf-instead-of-saving-it)
+- [`SecurityError: Blocked a frame with origin` when printing](#securityerror-blocked-a-frame-with-origin-when-printing)
+- [A password-protected or broken PDF leaves the reader blank](#a-password-protected-or-broken-pdf-leaves-the-reader-blank)
+- [Escape closes the whole dialog around a `PdfReader`](#escape-closes-the-whole-dialog-around-a-pdfreader)
+- [`onPageChange` reports page 0 or a page past the end](#onpagechange-reports-page-0-or-a-page-past-the-end)
+- [Pages are cut off, or too small, in fit width or fit page](#pages-are-cut-off-or-too-small-in-fit-width-or-fit-page)
+- [Search misses matches, or counts 0/0 until you press Enter](#search-misses-matches-or-counts-00-until-you-press-enter)
+- [`initialPage` is ignored, or the page number does not follow scrolling](#initialpage-is-ignored-or-the-page-number-does-not-follow-scrolling)
+- [`Type 'Blob' is not assignable to type 'string | File | null'` on `PdfReader`](#type-blob-is-not-assignable-to-type-string--file--null-on-pdfreader)
+- [`PdfReader cannot open [object …]`](#pdfreader-cannot-open-object-)
+- [`The PDF file is empty, i.e. its size is zero bytes.`](#the-pdf-file-is-empty-ie-its-size-is-zero-bytes)
+- [The PDF reloads, and goes back to its first page, on every render](#the-pdf-reloads-and-goes-back-to-its-first-page-on-every-render)
+- [The PDF goes back to its first page when the access token is refreshed](#the-pdf-goes-back-to-its-first-page-when-the-access-token-is-refreshed)
+- [`An internal link leading to page 3 was clicked, but neither <Document> was provided with onItemClick…`](#an-internal-link-leading-to-page-3-was-clicked-but-neither-document-was-provided-with-onitemclick)
+- [A `DropdownMenu` opened in fullscreen does not show](#a-dropdownmenu-opened-in-fullscreen-does-not-show)
+- [A tooltip does not show in fullscreen](#a-tooltip-does-not-show-in-fullscreen)
+- [A PDF page shows sideways in `PdfReader`](#a-pdf-page-shows-sideways-in-pdfreader)
+- [The zoom changes by itself while a long PDF is open](#the-zoom-changes-by-itself-while-a-long-pdf-is-open)
+- [A link in a PDF replaces the page the reader is on](#a-link-in-a-pdf-replaces-the-page-the-reader-is-on)
+- [`onPageChange` is not called when `initialPage` is past the end, or after a new file](#onpagechange-is-not-called-when-initialpage-is-past-the-end-or-after-a-new-file)
+- [Reporting a bug](#reporting-a-bug)
+
+---
+
+## Install
+
+### `Cannot find package '@react-pdf/renderer'`
+
+**When:** at build or at the first import of `@nxgt/material/print`, after
+upgrading to 2.0.0. Bun prints `Cannot find module`, Vite `Failed to resolve
+import`, for the same cause.
+**Why:** since 2.0.0, `@react-pdf/renderer` and `react-pdf-tailwind` are
+optional peers, so an app that does not print never installs them. An app that
+does print has to install them itself.
+**Fix:**
+
+```sh
+bun add @react-pdf/renderer@^4.9 react-pdf-tailwind
+```
+
+### `Conflicting peer dependency: @react-pdf/renderer`
+
+**When:** installing or upgrading to `@nxgt/material` 2.2.0 or later in an app
+that already has `@react-pdf/renderer` older than 4.9. npm stops with
+`ERESOLVE could not resolve`; Bun warns
+`incorrect peer dependency "@react-pdf/renderer@4.5.1"`.
+**Why:** 2.2.0 raised the optional peer's floor from `^4.5.1` to `^4.9`, and
+the copy in your lockfile no longer satisfies it.
+**Fix:**
+
+```sh
+bun add @react-pdf/renderer@^4.9
+# or: npm i @react-pdf/renderer@^4.9
+```
+
+`--legacy-peer-deps` silences the error but keeps a renderer the print
+entry is not tested against.
+
+### `Cannot find package 'leaflet'`
+
+**When:** at build or at the first import of `@nxgt/material/map`. The missing
+name may also be `react-leaflet`, `@react-leaflet/core`,
+`@adamscybot/react-leaflet-component-marker` or `react-geolocated`.
+**Why:** all five are optional peers, so an app that renders no map never has
+leaflet in its tree. An app that uses `./map` installs them.
+**Fix:**
+
+```sh
+bun add leaflet react-leaflet @react-leaflet/core \
+  @adamscybot/react-leaflet-component-marker react-geolocated
+```
+
+### `Invalid hook call. Hooks can only be called inside of the body of a function component`
+
+**When:** on the first render of any component from this package, often in an
+app whose own components work fine.
+**Why:** the app and this package resolve **two copies** of `react` (or of
+`react-dom`, `react-redux`, `react-hook-form`). They are peers because they
+must be one instance: a hook from one copy cannot run inside a renderer from
+the other. It also happens with two copies of `@nxgt/material` itself, for
+example when another library you depend on pins an older major.
+**Fix:**
+
+```sh
+bun pm ls --all | grep -E ' (react|react-dom|@nxgt/material)@'
+```
+
+```ts
+// vite.config.ts — a linked or workspace copy is the usual culprit
+export default defineConfig({
+  resolve: { dedupe: ['react', 'react-dom', 'react-redux', 'react-hook-form'] },
+});
+```
+
+Every name must appear once in the `ls` output. Install the required peers in
+the app itself (see [Getting started](getting-started.md#install)) so the package resolves the
+app's copy.
+
+### `is missing the following properties from type 'Pick<any, "variant" | "color">'`
+
+**When:** type-checking against a **locally packed or linked** build (`bun pm
+pack`, `bun link`, a `file:` dependency), typically on `ConfirmationDialog`,
+and props such as `children` or `title` accept anything.
+**Why:** that build's declaration files import
+`'../../../node_modules/react'` instead of `'react'`. The path exists in the
+library's checkout, not in your install, so TypeScript types `ReactNode` and
+`ComponentProps` as `any`, and a `Pick<any, …>` makes every picked key
+required. Until this was fixed, a `build-storybook` in the library's checkout rewrote
+`dist/lib` this way. Versions published to npm were built cleanly and do not
+have it.
+**Fix:** rebuild the library, then pack it again. The build and `bun pm pack`
+now fail if any declaration file imports through `node_modules/`:
+
+```sh
+bun run build && bun run verify:dts && bun pm pack
+```
+
+## Styles & assets
+
+### Components render unstyled, with no error
+
+**When:** on the first page load. Components have their structure but no
+spacing, colour or layout, and the console is clean.
+**Why:** Tailwind v4 does not scan `node_modules`. Unless you point it at this
+package, it never sees the utilities the components use, so it does not
+generate them. Nothing warns about it.
+**Fix:**
+
+```css
+/* the app's root stylesheet, in this order */
+@import "tailwindcss";
+@import "@nxgt/material/styles.css";
+@source "../node_modules/@nxgt/material/";
+```
+
+Point `@source` at `node_modules` relative to that stylesheet. In a Tailwind
+app, do not also import the compiled `dist/material.css`. That file is for apps
+without Tailwind.
+
+Before 2.2.0, `PdfReader`'s text and annotation layers (selection, search
+highlights, links, notes) stayed unstyled in a Tailwind app even with this
+setup: their CSS reached only `dist/material.css`. `styles.css` imports it now;
+on an older version, add `@import "react-pdf/dist/Page/TextLayer.css";` and
+`@import "react-pdf/dist/Page/AnnotationLayer.css";` after it.
+
+Before 2.2.0 too, `Markdown` maths, `RichTextEditor` code blocks,
+`ImageCropper`, `CodeBlock`, and `ButtonGroup`, `BottomAppBar`,
+`ContactItem`, `OpeningHoursItem`, `AttributeForm` and `AttributeValuesForm`
+were unstyled or unlaid-out in a Tailwind app, for the same reason. For the
+first three, on an older version, add the ones you use after it:
+
+```css
+@import "katex/dist/katex.min.css";
+@import "highlight.js/styles/github-dark.css";
+@import "react-easy-crop/react-easy-crop.css";
+```
+
+`CodeBlock`'s theme and the other components' CSS have no file you can
+import before 2.2.0: upgrade.
+
+### `<Icon>` renders nothing
+
+**When:** every `Icon` (and anything that uses one) is blank. The network tab
+shows a `404` for `/assets/icons/sprites/<style>.svg`.
+**Why:** `Icon` references a sprite sheet at a root-relative URL on your own
+origin. This package does not ship the Font Awesome Pro sheets, because the
+licence does not allow redistributing them. A missing sheet renders nothing,
+with no fallback.
+**Fix:**
+
+```text
+public/assets/icons/sprites/duotone.svg   ← <Icon name="atom" />  (type defaults to duotone)
+public/assets/icons/sprites/solid.svg     ← <Icon name="atom" type="solid" />
+public/assets/icons/sprites/sharp-solid.svg ← <Icon name="atom" family="sharp" type="solid" />
+```
+
+Serve one sheet per style you use, from your own Font Awesome Pro kit.
+
+## SSR & build
+
+### `ReferenceError: window is not defined`
+
+**When:** in the server log of an SSR app, at boot or on the first request
+that renders a map. The page is blank.
+**Why:** `leaflet` reads `window` while it is being *evaluated*, so importing
+it in node or bun throws before any of this package's code runs.
+`@nxgt/material/map` is the only entry that reaches leaflet. It cannot be
+imported on a server, by design.
+**Fix:**
+
+```tsx
+// location-picker.client.tsx
+import '@nxgt/material/map.css';
+import { type ComponentProps, lazy } from 'react';
+import { clientOnly } from '@nxgt/material/lib';
+
+const LocationFormField = lazy(() =>
+  import('@nxgt/material/map').then((m) => ({ default: m.LocationFormField })),
+);
+
+export const LocationPicker = clientOnly(
+  (props: ComponentProps<typeof LocationFormField>) => <LocationFormField {...props} />,
+);
+```
+
+The dynamic `import()` keeps leaflet out of the server's module graph, and
+`clientOnly` renders nothing until the component has mounted in the browser.
+A `typeof window` guard around the JSX is not enough, because the *import* is
+what throws. An SPA has no server pass and needs none of this.
+
+### `ReferenceError: DOMMatrix is not defined`
+
+**When:** at server boot in an SSR app, after adding `react-pdf` or
+`pdfjs-dist` yourself.
+**Why:** `pdfjs-dist` runs `new DOMMatrix()` when it is imported, and a server
+has no `DOMMatrix`. This package's own `PdfReader` already loads
+it lazily. You meet this error when your own code imports it statically.
+**Fix:**
+
+```tsx
+import { lazy } from 'react';
+import { clientOnly } from '@nxgt/material/lib';
+
+const Document = lazy(() => import('react-pdf').then((m) => ({ default: m.Document })));
+
+export const Preview = clientOnly(({ file }: { file: string }) => <Document file={file} />);
+```
+
+Or render `PdfReader` from `@nxgt/material/components`, which already does this.
+
+### `ReferenceError: document is not defined`
+
+**When:** at server boot, from any `import '@nxgt/material'`, on versions
+before 1.16.5.
+**Why:** two dependencies of the rich-text editors were bundled with their
+browser builds, which touch `document` and `DOMParser` when they are imported.
+Fixed in 1.16.5, and `bun run build` in this package now fails if any entry
+throws without a DOM.
+**Fix:**
+
+```sh
+bun add @nxgt/material@latest
+```
+
+If it persists on a current version, the stack names the dependency. Please
+report it (see [Reporting a bug](#reporting-a-bug)).
+
+### `Hydration failed because the server rendered HTML didn't match the client`
+
+**When:** in the browser console of an SSR app, on every page, with nothing
+visibly broken. React then discards the server HTML and renders the page again
+on the client, so a click that lands before that is lost.
+**Why:** React 19 hoists `<title>` into the document head. An `<svg>` labelled
+with a `<title>` child is emitted as `<title></title>` by the server but
+rendered inline by the client. This package's `Icon`, `Spinner` and
+`CircularProgress` do not do this. Your own SVGs might.
+**Fix:**
+
+```tsx
+// not: <svg><title>Logo</title>…</svg>
+<svg role="img" aria-label="Logo" viewBox="0 0 24 24">…</svg>
+```
+
+If the diff under the message shows translated text instead, see the
+[i18n entry](#hydration-failed-because-the-server-rendered-text-didnt-match-the-client).
+
+### `A tree hydrated but some attributes of the server rendered HTML didn't match the client properties`
+
+**When:** in the browser console of an SSR app on a desktop, on a page with a
+`TimeField` or `TimeFormField`, before 2.2.0. The server log also printed:
+`` `useMedia` When server side rendering, defaultState should be defined to prevent a hydration mismatches. ``
+**Why:** the field opens its picker in a popover on a desktop and in a dialog
+under 768 px, and asked `useMedia` without a default. A server has no screen,
+so it rendered the phone trigger; a desktop's first render was the popover
+trigger, with different attributes (its `id`, `name`, `data-*`). React keeps
+the server's attributes ("This won't be patched up").
+**Fix:** upgrade. The server and the first client render are now both the
+desktop trigger; a phone switches to the dialog once mounted.
+
+### `` `useMedia` When server side rendering, defaultState should be defined to prevent a hydration mismatches. ``
+
+**When:** in the server log of an SSR app, before 2.2.0, on a page with an
+`AppHeader`, `AppBreadcrumb`, `DataTable`, `ResponsiveButton`, `ThemeToggle`,
+`CodeBlock`, `CodeDiff`, `JsonViewer`, `CodeEditor`, `Doc` or `Stepper`, or
+with your own `useIsMobile()` / `useTheme()`. The browser console of a phone
+(of a dark-mode desktop, for the code blocks; of a desktop, for `Stepper`)
+then shows
+[`Hydration failed because the server rendered HTML didn't match the client`](#hydration-failed-because-the-server-rendered-html-didnt-match-the-client).
+**Why:** those components asked react-use's `useMedia` whether the screen is
+narrow (or dark) with no answer for the server, which has no screen. The
+server rendered "no", and a client whose answer was "yes" rendered something
+else on its first pass. React then threw the server HTML away.
+**Fix:** upgrade. The server and a hydrating client now render the desktop,
+light answer, and the client switches right after hydrating. A page rendered
+only in the browser reads the real answer from its first render, as before.
+`Stepper` logged this line until 2.2.0, and a desktop hydrating its server
+HTML showed the mismatch (it asks whether the screen is wide); upgrade and
+drop any `clientOnly(Stepper)` you added for it.
+
+### `useMatches must be used within a data router`
+
+**When:** rendering `ActivityLayout` or `AppBreadcrumb`.
+**Why:** `AppBreadcrumb` reads each route's `handle.breadcrumb` through
+`useMatches()`, which only works under a data router. `<BrowserRouter>` and
+`<MemoryRouter>` are not data routers. The same message appears if the app and
+this package resolve two copies of `react-router`.
+**Fix:**
+
+```tsx
+import { createBrowserRouter, RouterProvider } from 'react-router';
+
+const router = createBrowserRouter(routes);
+<RouterProvider router={router} />;
+// in tests and stories: createMemoryRouter(routes) + RouterProvider
+```
+
+Check `bun pm ls --all | grep ' react-router@'` lists one version.
+
+## Printing
+
+### `Cannot find module '#standard-fonts/Helvetica'`
+
+**When:** a built SSR server answers nothing on every route, `/health`
+included, and a container healthcheck never passes. The server log shows this
+message on each request. Node may print it as `Package import specifier
+"#standard-fonts/Helvetica" is not defined`.
+**Why:** `@nxgt/material/print` reaches `pdfkit`, which loads its standard
+fonts with `createRequire(import.meta.url)('#standard-fonts/<name>')`. That is
+a specifier private to pdfkit and called at runtime, so no bundler resolves it.
+Once pdfkit is bundled into the server, the call is rooted in your build
+directory and fails.
+**Fix:** choose based on whether the runtime image keeps `node_modules`.
+
+```ts
+// Image keeps node_modules: leave the library external.
+// vite.config.ts: keep '@nxgt/material' OUT of ssr.noExternal,
+// and pass `--external @nxgt/material` to the bundle step.
+
+// Image ships the bundle alone: inline the fonts.
+import { pdfkitStandardFonts } from '@nxgt/material/vite';
+
+export default defineConfig({
+  plugins: [pdfkitStandardFonts(), reactRouter()], // first in the list
+});
+```
+
+Neither `resolve.alias` (the string never reaches the resolver) nor
+`--external pdfkit` (transitive, so it cannot resolve from the app:
+`Cannot find package 'pdfkit'`) fixes it.
+
+### `still references '#standard-fonts/' after the transform`
+
+**When:** at build, from `pdfkitStandardFonts()`, with the rest of the message
+`pdfkit changed how it loads its standard fonts`.
+**Why:** a `pdfkit` release changed how it loads its fonts, so the plugin can
+no longer rewrite those calls. It fails the build on purpose, so the failure
+doesn't reach your server's first request.
+**Fix:** leave the library external for now (see the entry above), or pin the
+last `pdfkit` that built, and please report it (see
+[Reporting a bug](#reporting-a-bug)) with the `pdfkit` version.
+
+```json
+{ "overrides": { "pdfkit": "<last version that built>" } }
+```
+
+### `Module '"@nxgt/material"' has no exported member 'PrintHeader'`
+
+**When:** type-checking (`TS2305`) or bundling (`"PrintHeader" is not exported
+by …`) after upgrading to 2.0.0. The name may be any print component or `tw`.
+**Why:** 2.0.0 moved the print components out of the barrel into their own
+entry, so that apps that do not print no longer pull `pdfkit`.
+**Fix:**
+
+```ts
+import { PrintHeader, PrintTable, tw } from '@nxgt/material/print';
+```
+
+Then install the two optional peers (see
+[`Cannot find package '@react-pdf/renderer'`](#cannot-find-package-react-pdfrenderer)).
+
+### `Module '"@nxgt/material"' has no exported member 'formatAmount'`
+
+**When:** on 2.0.0 and 2.0.1 only, for `formatAmount` or `formatDate` imported
+from the barrel or from `@nxgt/material/lib`.
+**Why:** they moved to `@nxgt/material/print` with the print components in
+2.0.0. They are pure `Intl` helpers, and 2.1.0 puts them back on the barrel and
+`./lib`.
+**Fix:**
+
+```sh
+bun add @nxgt/material@^2.1.0
+```
+
+```ts
+import { formatAmount, formatDate } from '@nxgt/material/lib';
+```
+
+Upgrade rather than importing them from `./print`, which would make a screen
+depend on the PDF peers.
+
+### An amount in yen shows no decimals, or one in dinars shows three
+
+**When:** from 2.2.0, `formatAmount(1234.5, 'JPY')` gives `¥1,235` where it gave
+`¥1,234.50`, and `formatAmount(1.5, 'KWD')` gives `KWD 1.500`. A snapshot or a
+test that asserted the old string fails. The same goes for what a
+`CurrencyField` / `CurrencyFormField` shows once the amount is committed: a
+`JPY` field shows `1,235`, a `KWD` one `1.500` (the emitted number is not
+rounded).
+**Why:** amounts now use their currency's own decimals (ISO 4217): none for
+JPY and KRW, three for KWD, BHD and OMR, two for EUR, USD, GBP and most others,
+whose output does not change. Two decimals for every currency was a bug on
+invoices.
+**Fix:** update the expectation, or keep two decimals where you need them:
+
+```ts
+formatAmount(1234.5, 'JPY', { fractionDigits: 2 }); // '¥1,234.50'
+```
+
+```tsx
+<CurrencyField label="Price" currency="JPY" fractionDigits={2} value={price} onChange={setPrice} />
+```
+
+### A date shows the day before
+
+**When:** before 2.2.0, `formatDate('2026-03-01')` printed `Feb 28, 2026` on a
+machine or server west of UTC (the Americas).
+**Why:** a date-only string was read as midnight UTC, which is still the
+previous evening there.
+**Fix:** upgrade: from 2.2.0 a `YYYY-MM-DD` value keeps its calendar day in
+every time zone. For a value with a time, pass the time zone you mean:
+
+```ts
+formatDate('2026-03-01T23:30:00Z', { timeZone: 'Europe/Paris' }); // 'Mar 2, 2026'
+```
+
+### `Invalid hook call` in a `PrintDocument` `footer` function
+
+**When:** rendering a `PrintDocument` whose `footer` is a function that calls
+a hook (`useMaterialTranslation`, `useFormatters`, your own).
+**Why:** react-pdf calls the function once per page while it lays the pages
+out, outside React, so no hook can run there. It returns text only.
+**Fix:** compute what it needs in the component, and only read it in the
+function; or pass an element instead of a function.
+
+```tsx
+import { formatDate, PrintDocument } from '@nxgt/material/print';
+import { translateMaterial } from '@nxgt/material/i18n';
+
+function Report({ issuedAt, language }: { issuedAt: string; language: string }) {
+  const issued = formatDate(issuedAt, { locale: language }); // here, not in the footer
+  return (
+    <PrintDocument
+      language={language}
+      footer={({ pageNumber, totalPages }) =>
+        `${issued} · ${translateMaterial(language, 'material.print.page-of', 'Page {page} of {pages}', { page: pageNumber, pages: totalPages })}`
+      }
+    >
+      {/* … */}
+    </PrintDocument>
+  );
+}
+```
+
+`translateMaterial` is not a hook, so it is safe inside the function.
+
+### Body text runs under the footer or the page number
+
+**When:** a `PrintDocument` with a `footer` of more than one line, or a large
+font, prints its last body lines behind the footer.
+**Why:** the page keeps a band of `footerHeight` points (24 by default) above
+the bottom margin for the footer and page numbers; a taller footer grows up
+out of it, over the body.
+**Fix:** make the band as tall as the footer:
+
+```tsx
+<PrintDocument footer={<LegalNotice />} footerHeight={48} pageNumbers>
+  {/* … */}
+</PrintDocument>
+```
+
+### The `LOGO` box in `PrintHeader` is gone after upgrading
+
+**When:** from 2.2.0, a `PrintHeader` with no `logo` and no `logoText` prints
+no grey `LOGO` box on the left, and one with no `qrDataUrl` no empty box on
+the right. A visual snapshot changes.
+**Why:** a document with no logo printed the word `LOGO`. A side you do not
+fill is now left empty, and the title stays centred.
+**Fix:** pass your logo, or keep the old box:
+
+```tsx
+<PrintHeader title="Invoice" logo={logoDataUrl} />
+<PrintHeader title="Invoice" logoText="LOGO" />
+```
+
+### French amounts print with a slash, as in `1/234,50`
+
+**When:** before 2.2.0, `formatAmount(1234.5, 'EUR', { locale: 'fr-FR' })`
+printed `1/234,50 €` in a PDF, while the same string showed `1 234,50 €` on
+screen.
+**Why:** `Intl` separates French thousands with a narrow no-break space
+(U+202F), which the PDF standard fonts do not have.
+**Fix:** upgrade to 2.2.0 or later: `PrintSection`, `PrintInfoRow`,
+`PrintTableCell`, `PrintTotalRow`, `PrintCardField` and `PrintBadge` replace
+that character before printing. Text you put in your own react-pdf `Text` is
+not rewritten:
+
+```ts
+formatAmount(1234.5, 'EUR', { locale: 'fr-FR' }).replace(/\u202f/g, '\u00a0');
+```
+
+### An amount column prints `—` instead of the amount
+
+**When:** a `PrintDataTable` column or a `PrintKeyValue` field with
+`format: 'amount'` (or `'number'`, `'percent'`) prints `—` where a figure
+should be, and a `total: 'sum'` leaves those rows out.
+**Why:** the value is a string, such as `'12.50'` from a JSON API or a
+decimal column. These formats take a finite `number` only; anything else is
+treated as empty, and `'sum'` counts it as zero.
+**Fix:** hand the rows over with numbers:
+
+```ts
+const rows = lines.map((line) => ({ ...line, amount: Number(line.amount) }));
+```
+
+or read the column through an accessor:
+
+```ts
+{ id: 'amount', label: 'Amount', accessor: (line) => Number(line.amount), format: 'amount', total: 'sum' }
+```
+
+### The table header does not repeat on the next page
+
+**When:** a table runs over two pages and the second page starts with rows
+and no header.
+**Why:** a table built from `PrintTable`, `PrintTableHeader` and
+`PrintTableRow` prints its header once, where you wrote it. A
+`PrintDataTable` repeats its header on every page the table crosses unless
+you passed `repeatHeader={false}`; it does not print a header on a page the
+table does not reach, such as a page holding only what follows the table.
+**Fix:** build the table with `PrintDataTable`, and leave `repeatHeader` on:
+
+```tsx
+<PrintDataTable columns={columns} rows={lines} currency="EUR" />
+```
+
+See [Tables from columns and rows](guides/printing.md#tables-from-columns-and-rows).
+
+### The PDF tab does not open
+
+**When:** `openPdf` saves the file instead of opening a tab, or the browser
+shows a "pop-up blocked" icon in the address bar.
+**Why:** a browser opens a new tab only while it still counts a click as the
+user's. `openPdf` opens its tab before rendering for that reason, but when it
+runs after an `await` (a fetch of the data, say), in an effect or from a
+timer, the click no longer counts and the popup blocker stops the tab.
+`openPdf` then downloads the file instead, so the user still gets it.
+**Fix:** call `openPdf` first thing in the click handler. When the data has to
+load first, render the file ahead of the click with `usePdfFile` and pass its
+`blob`:
+
+```tsx
+// the tab is opened before anything is awaited
+<Button onClick={() => openPdf(<InvoiceDocument invoice={invoice} />, { fileName: invoice.number })}>Open</Button>
+
+// or: the file is already rendered when the user clicks
+const { blob } = usePdfFile(doc);
+<Button disabled={!blob} onClick={() => blob && openPdf(blob, { fileName: invoice.number })}>Open</Button>
+```
+
+See [In the browser](guides/printing.md#in-the-browser-downloadpdf-and-openpdf).
+
+### `renderToBuffer is a Node specific API`
+
+**When:** on a server, from `pdfResponse` or `renderPdfBuffer` (or react-pdf's
+own `renderToBuffer`). The message goes on: `You're either using this method in
+a browser, or your bundler is not loading react-pdf from the appropriate web
+build.`
+**Why:** `@react-pdf/renderer` ships a Node build and a browser build, and the
+browser build throws this for every Node API. A server bundle got the browser
+build: a bundler resolving the `browser` field or condition for the server,
+or a worker or edge target, which has no Node build to pick.
+**Fix:** leave `@react-pdf/renderer` out of the server bundle so the runtime
+loads it from `node_modules`, and render on Node 18+ or Bun:
+
+```ts
+// vite.config.ts
+export default defineConfig({ ssr: { external: ['@react-pdf/renderer'] } });
+
+// next.config.ts
+export default { serverExternalPackages: ['@react-pdf/renderer'] };
+```
+
+In the browser, use `renderPdfBlob`, `downloadPdf` or `openPdf`; they never
+call a Node API. On an edge runtime, see
+[PDF rendering fails on an edge runtime](#pdf-rendering-fails-on-an-edge-runtime).
+
+### `renderToStream is a Node specific API`
+
+**When:** calling `renderPdfStream`, in a browser or in a server bundle that
+got react-pdf's browser build.
+**Why:** `renderPdfStream` returns a stream that only react-pdf's Node build
+can produce; there is no browser version.
+**Fix:** in the browser, render a `Blob` instead; on a server, the fix is
+[the one above](#rendertobuffer-is-a-node-specific-api).
+
+```ts
+const blob = await renderPdfBlob(doc); // browser and server
+```
+
+### PDF rendering fails on an edge runtime
+
+**When:** a route on Vercel Edge, Cloudflare Workers or Deno Deploy that calls
+`pdfResponse` or another output function fails, often with
+`renderToBuffer is a Node specific API`, a missing `fs`, `stream` or `Buffer`,
+or a bundle over the size limit.
+**Why:** `@react-pdf/renderer` and pdfkit need Node APIs these runtimes do
+not have. They are not supported.
+**Fix:** run that route on a Node 18+ or Bun runtime, or render in the
+browser with `downloadPdf`. In Next.js:
+
+```ts
+// app/invoices/[id]/pdf/route.tsx
+export const runtime = 'nodejs';
+```
+
+See [Runtimes](guides/printing.md#runtimes).
+
+### `usePdfFile` renders on every render
+
+**When:** `loading` flips back to `true` each time the component renders, a
+`PdfReader` fed by the hook reloads, or the CPU stays busy.
+**Why:** `usePdfFile` renders again whenever its document is a new value, and
+a JSX element (or a model built inline) is a new value on every render. So is
+a `custom` object written inline.
+**Fix:** build the document with `useMemo`, keyed on its data:
+
+```tsx
+const doc = useMemo(() => <InvoiceDocument invoice={invoice} />, [invoice]);
+const { blob, loading } = usePdfFile(doc);
+```
+
+### `[pdf] No renderer for the custom node`
+
+**When:** rendering a document model, with the rest of the message
+``"signature": pass it in `custom` when rendering.``
+**Why:** the model holds a `{ type: 'custom', name: 'signature' }` node, and
+the function that renders it was given no renderer under that name.
+**Fix:** pass the renderer to whichever function renders the document:
+
+```tsx
+await pdfResponse(doc, { custom: { signature: (props) => <Text>{String(props.name)}</Text> } });
+```
+
+See [Custom nodes](guides/printing.md#custom-nodes).
+
+### `[pdf] Unknown node type`
+
+**When:** rendering a document model, as `[pdf] Unknown node type "chart".`
+**Why:** a node's `type` is not one this version renders: a typo in
+hand-written JSON, or a document built by a newer version of the package.
+**Fix:** build nodes with the builders (`heading()`, `table()`, …), which
+TypeScript checks, or upgrade the package that renders the document.
+
+### `[pdf] Unsupported document version`
+
+**When:** rendering a document model, as `[pdf] Unsupported document version
+2: this version renders version 1.`
+**Why:** the document's `version` is not `1`, the only one this package
+renders.
+**Fix:** build the document with `pdfDocument()` or `definePdfDocument()`,
+which stamp `version: 1`, rather than by hand.
+
+### `'invoice' is of type 'unknown'` in a `definePdfDocument` template
+
+**When:** compiling a template whose data parameter has no type,
+`definePdfDocument((invoice) => ({ … invoice.number … }))`. Before 2.2.0
+the error was at the call instead: `Argument of type 'Invoice' is not
+assignable to parameter of type 'never'`.
+**Why:** the template's own signature is its type, so an unannotated data
+parameter is `unknown`.
+**Fix:** annotate it (do not pass a generic):
+
+```ts
+export const invoicePdf = definePdfDocument((invoice: Invoice, language = 'en') => ({
+  language,
+  pages: [page({ body: [heading(invoice.number)] })],
+}));
+```
+
+## Maps
+
+### The map has no controls, or its tiles are scattered
+
+**When:** a `Map` renders tiles in the wrong places, or with no zoom buttons or
+attribution, and no error.
+**Why:** leaflet's stylesheet is missing. It ships as
+`@nxgt/material/map.css` and is not part of `styles.css`, because it depends
+on the optional `leaflet` peer.
+**Fix:**
+
+```tsx
+import '@nxgt/material/map.css';
+```
+
+### The browser asks for location permission when a map renders
+
+**When:** as soon as a `Map` mounts, whether or not it has a `center`.
+**Why:** `Map` asks for the visitor's position on mount (through
+`react-geolocated`); `center` only decides where it centres, the position
+being used when `center` is absent. No prop turns the request off today.
+**Fix:** mount the map only once the visitor asks for it, so the prompt comes
+with a reason:
+
+```tsx
+import { Button } from '@nxgt/material/components';
+import { Map, Marker } from '@nxgt/material/map';
+import { useState } from 'react';
+
+function StoreMap() {
+  const [shown, setShown] = useState(false);
+  if (!shown) return <Button onClick={() => setShown(true)}>Show the map</Button>;
+  return (
+    <Map center={[48.8566, 2.3522]} className="size-96">
+      <Marker position={[48.8566, 2.3522]} />
+    </Map>
+  );
+}
+```
+
+### The map shows two zoom controls
+
+**When:** after passing `zoomControl` to `Map`.
+**Why:** `Map` already renders its own zoom control at `topleft`.
+`zoomControl={true}` adds leaflet's built-in control as well.
+**Fix:**
+
+```tsx
+<Map center={center} /> {/* leave zoomControl at its default, false */}
+```
+
+## i18n
+
+### `useI18nContext must be used within an I18nProvider`
+
+**When:** the first render of a component that calls `useI18nContext()` (for
+example your language switcher).
+**Why:** language state lives only in `I18nProvider`, and this hook throws
+when there is none above it. It also throws when the provider and the hook come
+from two copies of `@nxgt/material` (see
+[Invalid hook call](#invalid-hook-call-hooks-can-only-be-called-inside-of-the-body-of-a-function-component)).
+**Fix:**
+
+```tsx
+import { I18nProvider } from '@nxgt/material/i18n';
+
+<I18nProvider defaultLanguage="en">
+  <App />
+</I18nProvider>
+```
+
+For a component that must also work without a provider, use
+`useOptionalI18nContext()`, which returns `null` instead of throwing.
+
+### `[@nxgt/material] i18n resource override for language`
+
+**When:** in the console outside production, when `mergeResources` runs. It is
+followed by the list of keys, e.g. `"en": material.command.title. App resources
+take precedence over the base bundle at these keys.`
+**Why:** your resources define leaves under the `material` namespace, which
+this package reserves for its own strings. The override reaches your app's
+own translator only: the package's components translate from their own
+bundle, so their text does **not** change.
+**Fix:**
+
+```ts
+// app resources: keep your strings in your own namespaces
+export const resources = {
+  en: { app: { title: 'Orders' } },       // not en.material.*
+  fr: { app: { title: 'Commandes' } },
+};
+```
+
+To change a component's wording, pass the text through its props (most take a
+`label`, `title` or `placeholder`). The warning does not print in production.
+
+### `[@nxgt/material] Unsupported language`
+
+**When:** in the console on `changeLanguage(...)`, e.g.
+`Unsupported language: "fr-FR".` The language does not change.
+**Why:** the value is not in the provider's `supportedLanguages`, which
+defaults to the languages of the base bundle (`en`, `fr`). A full locale such
+as `navigator.language` is not a language code.
+**Fix:**
+
+```tsx
+import { type Language, useI18nContext } from '@nxgt/material/i18n';
+
+const { changeLanguage, supportedLanguages } = useI18nContext();
+const code = navigator.language.slice(0, 2);
+if (supportedLanguages.includes(code as Language)) changeLanguage(code as Language);
+```
+
+### `Hydration failed because the server rendered text didn't match the client`
+
+**When:** in an SSR app with a stored language other than the default. The
+diff shows the same string in two languages.
+**Why:** without `initialLanguage`, `I18nProvider` reads `localStorage` on the
+client, which the server cannot see. The server renders `defaultLanguage`, the
+client its stored one.
+**Fix:**
+
+```tsx
+// resolve the language on the server (cookie, Accept-Language) and pass it
+<I18nProvider
+  initialLanguage={languageFromRequest}
+  onLanguageChange={(lang) => { document.cookie = `language=${lang}; path=/`; }}
+>
+  <App />
+</I18nProvider>
+```
+
+When `initialLanguage` is supported, `localStorage` is not read, so both
+renders agree. `onLanguageChange` keeps the cookie in step for the next request.
+
+### A translation key is rendered instead of its text
+
+**When:** a component shows `app.orders.title` (or a `material.*` key) as its
+text.
+**Why:** `createTranslator` returns a missing key as-is instead of throwing.
+The key is absent from the bundle you passed it, or from the current language.
+If the message has invalid ICU syntax, the raw message is returned and the
+parse error is logged with `console.error`.
+**Fix:**
+
+```ts
+// pass the merged bundle, and define the key in every language
+export const resources = mergeResources(materialResources, appResources);
+export const translate = createTranslator<LocaleKey>(resources);
+```
+
+Typing the translator with `LocaleKey` (see the [i18n guide](guides/i18n.md#wiring-your-own-strings)) turns a
+misspelt key into a type error.
+
+### A label shows `{count}` or another placeholder
+
+**When:** a label reads `Step {step}`, `{count}/{max}` or `{count} items`
+instead of `Step 01`, `3/5` or `3 items`.
+**Why:** before 2.2.0, a component rendered with no
+`I18nProvider` returned its English fallback without filling in its values.
+Since then the fallback is formatted with its values, provider or not. If it
+still happens, the message was called without the value it names (or has a
+stray `{`): the raw text is returned, and outside production a
+`[@nxgt/material] Could not format the fallback` warning names it.
+**Fix:** update `@nxgt/material`. In your own components, pass the values
+with the fallback:
+
+```ts
+const { t } = useMaterialTranslation();
+t('material.stepper.step', 'Step {step}', { step: 2 }); // not t(key, 'Step {step}')
+```
+
+### Zod messages ignore the language, or your `material.zod.*` strings
+
+**When:** `zodLocaleError()` writes English although the user chose French,
+or ignores a `material.zod.*` string you merged with `mergeResources`.
+**Why:** by default it reads the language from `localStorage.language` and
+formats from the package's own bundle. An `I18nProvider` with another
+`storageKey` writes elsewhere; your merged bundle reaches only your own
+translator. On a server there is no `localStorage`, so it writes English.
+**Fix:**
+
+```ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material/lib';
+import { translate } from './i18n'; // createTranslator(mergeResources(...))
+
+z.config({ customError: zodLocaleError({ storageKey: 'lang', translate }) });
+// on a server, where you know the request's language:
+z.config({ customError: zodLocaleError({ language: () => requestLanguage() }) });
+```
+
+## Runtime
+
+### `must be used within` / `must be used inside`
+
+**When:** on render, from a sub-component or a context hook used outside the
+component that provides its state. The exact messages:
+
+| Message | Wrap it in |
+| --- | --- |
+| `useCarousel must be used within a <Carousel />` | `Carousel` |
+| `Gallery components must be used inside <Gallery>` | `Gallery` |
+| `useFilterContext must be used within a FilterProvider` | `FilterProvider` |
+| `usePaneLayout must be used within a PaneLayout` | `PaneLayout` |
+| `useListDetails must be used within a ListDetailsLayout` | `ListDetailsLayout` |
+| `useStxPlayerContext must be used within StxPlayer` | `StxPlayer` |
+| `Quiz components must be used inside <Quiz>` | `Quiz` |
+| `EventCalendar components must be used inside <EventCalendar>` | `EventCalendar` |
+| `Kanban components must be used inside <Kanban>` | `Kanban` |
+| `Notification components must be used inside <Notifications>` | `Notifications` |
+| `Doc components must be used inside <Doc>` | `Doc` |
+
+**Why:** these widgets share state through React context. Their parts, and the
+hooks that read that context, only work below the root component. A portal
+does not break this, but a second copy of `@nxgt/material` does (see
+[Invalid hook call](#invalid-hook-call-hooks-can-only-be-called-inside-of-the-body-of-a-function-component)).
+**Fix:**
+
+```tsx
+import { FilterProvider, useFilterContext } from '@nxgt/material/components';
+
+function ActiveCount() {
+  const { state } = useFilterContext(); // fine: rendered below FilterProvider
+  return <span>{Object.keys(state.values).length}</span>;
+}
+
+<FilterProvider schema={schema}>
+  <ActiveCount />
+</FilterProvider>;
+```
+
+### `Clipboard is not available`
+
+**When:** calling `copyToClipboard(value)` on a page served over plain `http`
+from a host other than `localhost`, in a browser that blocks clipboard access,
+or on the server.
+**Why:** it uses `navigator.clipboard.writeText`, which browsers expose only in
+secure contexts.
+**Fix:**
+
+```ts
+import { copyToClipboard } from '@nxgt/material/components';
+
+try {
+  await copyToClipboard(value);
+} catch {
+  // show the value for manual copy instead
+}
+```
+
+Serve the app over `https` (or `localhost`) in any environment where copying
+must work. `CopyButton` does not throw. It uses a different clipboard fallback.
+
+### `Upload failed with status 403`
+
+**When:** an `S3UploadField` upload fails. The error reaches `onError(file,
+error)`. The status may be any non-2xx.
+**Why:** the storage rejected the `PUT` to the presigned URL. For `403` the
+usual causes are an expired URL, or a `Content-Type` that differs from the
+one the URL was signed with.
+**Fix:**
+
+```ts
+const getPresignedUrl = async (file: File) => {
+  const { uploadUrl, publicUrl } = await api.presign({ name: file.name, contentType: file.type });
+  // send exactly the headers the URL was signed with
+  return { uploadUrl, publicUrl, headers: { 'Content-Type': file.type } };
+};
+```
+
+### `Network error during upload`
+
+**When:** an `S3UploadField` upload fails immediately. The browser console
+shows a CORS error for the storage host.
+**Why:** the browser blocked the cross-origin `PUT`. The bucket's CORS rules
+do not allow your origin, the `PUT` method, or the headers you send.
+**Fix:**
+
+```json
+[{ "AllowedOrigins": ["https://app.example.com"], "AllowedMethods": ["PUT"], "AllowedHeaders": ["*"] }]
+```
+
+Apply it on the bucket, with your own origin.
+
+### `Maximum number of presets (20) reached`
+
+**When:** in the console when saving a filter preset. The preset is not saved.
+**Why:** `presetConfig.maxPresets` caps saved presets, and defaults to `20`.
+**Fix:**
+
+```tsx
+<FilterProvider schema={schema} presetConfig={{ enabled: true, maxPresets: 50 }}>
+```
+
+### `Failed to execute 'exitFullscreen' on 'Document': Document not active`
+
+**When:** as an unhandled promise rejection in the console (or a failing test
+run) when a `StxPlayer` that was fullscreen or in picture-in-picture unmounts,
+typically as a page, frame or test tears down. Versions before 2.2.0 only.
+**Why:** the player's cleanup exited fullscreen without catching the promise;
+once the document is inactive the browser rejects it.
+**Fix:** upgrade to 2.2.0, where refused fullscreen and picture-in-picture
+changes are caught. On an older version, ignore that rejection in tests:
+
+```ts
+// vitest setup
+window.addEventListener('unhandledrejection', (event) => {
+  if (String(event.reason).includes('Document not active')) event.preventDefault();
+});
+```
+
+### A `SwitchFormField` shows no validation message
+
+**When:** a `Switch` or `SwitchFormField` without a `placeholder`: the field is
+invalid (red border when it has a `label`) but no message appears, and your own
+`helperText` is not shown either. Versions before 2.2.0 only.
+**Why:** the switch only rendered its helper line when it had a `placeholder`.
+A form wrapper passes the validation message as `helperText`, so it vanished.
+**Fix:** upgrade to 2.2.0, where `helperText` shows under the row or under the
+bare switch. On an older version, give the switch a `placeholder`:
+
+```tsx
+<SwitchFormField control={control} name="terms" label="Terms" placeholder="I accept the terms" />
+```
+
+### A `TimeFormField` shows its error on a desktop but not on a phone
+
+**When:** a form with `mode: 'onBlur'` or `'onTouched'` (or code reading
+`touchedFields`), on a screen under 768 px: leaving the time picker neither
+validates the field nor marks it touched, so its error waits for the submit.
+Versions before 2.2.0 only.
+**Why:** under 768 px the picker opens in a dialog, and that branch did not
+pass `onBlur` to the picker, as the desktop popover does. React Hook Form never
+heard the field lose focus.
+**Fix:** upgrade to 2.2.0. On an older version, validate on change as well,
+which does not depend on the blur:
+
+```tsx
+const form = useForm<Values>({ mode: 'all' }); // change and blur
+```
+
+From 2.2.0 the field is touched when focus leaves the trigger and the picker,
+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.
+
+### `touchedFields` stays empty after leaving a field, or `mode: 'onBlur'` never validates
+
+**When:** a `*FormField` keeps `formState.touchedFields` (and
+`getFieldState(name).isTouched`) empty after the user tabs or clicks out of
+it, so an "errors once touched" pattern never shows anything, and a form with
+`mode: 'onBlur'` or `'onTouched'` shows no message until submit. In 2.1.0 and
+earlier, about twenty wrappers never called React Hook Form's `field.onBlur`
+(`SelectFormField`, `ComboboxFormField`, `ColorFormField`, `RatingFormField`,
+`OtpFormField`, `CheckboxFormField`, the dialog editors, the uploads, the
+config-driven `FormField` for most types, …), and others called it too early,
+when focus moved to their own button or popover.
+**Why:** a wrapper calls `field.onBlur` when focus **leaves the field and
+anything it opened**. Focus that moves into its popover, its listbox or its
+dialog is still in the field, so opening a picker is not leaving it; the
+field is left when focus then reaches another element of the page, or
+nothing. On 2.2.0 or later, `touchedFields` still empty after that means one
+of:
+
+- your form's `mode` is `'onSubmit'` (the default): the field is touched, but
+  nothing validates until the first submit — that is React Hook Form's rule,
+  and the wrappers do not change it;
+- your own field in a `Controller` does not pass `field.onBlur` to its
+  control;
+- focus went from the field straight into an overlay that appeared while the
+  field had focus, that the field does not name as its popup and that no
+  other control names either, such as a new toast's button: it counts as the
+  field's own until focus comes back to the page. (Another field's freshly
+  opened list, which its trigger names, is leaving: see
+  [forms](guides/forms.md#touched-on-blur).)
+- your app portals overlays somewhere other than straight under `<body>`: the
+  field's own popover then looks like the page, and opening it touches the
+  field early;
+- the field is a `FilterFormField`, touched when it is applied, not on blur;
+- the user clicked a button-only field (`SelectCardFormField`,
+  `SelectChipFormField`, the stars of a `RatingFormField`, the add button of a
+  dialog editor) in Safari, or in Firefox on macOS: those browsers do not
+  focus a button on click, so focus never entered the field and there is
+  nothing to leave — as for a native `<button onBlur>`. Keyboard users, and
+  other browsers, are not affected.
+
+**Fix:** upgrade to 2.2.0, and pick the `mode` that validates when you want:
+
+```tsx
+const form = useForm<Values>({
+  mode: 'onTouched', // first blur, then every change
+  resolver: zodResolver(schema),
+});
+```
+
+For a field of your own, pass `field.onBlur` to the control that loses focus:
+
+```tsx
+<Controller
+  control={form.control}
+  name="nickname"
+  render={({ field }) => (
+    <input value={field.value} onChange={field.onChange} onBlur={field.onBlur} />
+  )}
+/>
+```
+
+What counts as leaving, per kind of field:
+[forms](guides/forms.md#touched-on-blur).
+
+### `TypeError: values.map is not a function`
+
+**When:** a `SliderFormField` with one thumb crashes (in `SliderReadout`) as
+soon as its form holds a number for it: after the first change, or with a
+numeric default value such as `defaultValues: { volume: 40 }`. 2.1.0 and
+earlier.
+**Why:** the wrapper stores one thumb's value as a number, as documented in
+[What each field emits](guides/forms.md#what-each-field-emits), but passed
+that number back to the slider, which expects an array of thumb values.
+**Fix:** upgrade to 2.2.0, which wraps the number in an array for the slider.
+On an older version, give the field an array default and keep an array:
+
+```tsx
+useForm({ defaultValues: { volume: [40] } }); // an array stays an array
+```
+
+### A multi-step form reopens at a later step
+
+**When:** a wizard built on `createStepFormSlice` opens at the step (and with
+the values) a user left it at, after a reload or on a later visit. From 2.2.0.
+**Why:** `updateStep` stores the state under the slice `name`, and from 2.2.0
+the slice resumes from it; earlier versions stored it and never read it back.
+**Fix:** call `reset()` when the wizard is finished or abandoned (it clears the
+entry), and give each wizard its own `name`:
+
+```tsx
+onNext={(v) => {
+  onDone({ ...values, ...v } as Signup);
+  reset(); // clears localStorage['signup-wizard']
+}}
+```
+
+In an SSR app the server renders step 0. A wizard rendered with
+`useSliceReducer` resumes once it has hydrated, so hydration matches without
+wrapping it in `clientOnly`; a slice kept in a Redux store needs the recipe in
+[forms](guides/forms.md#a-multi-step-form).
+
+### An end-to-end test no longer finds a `LinkButton` by the `button` role
+
+**When:** after upgrading to 2.2.0, a spec such as
+`getByRole('button', { name: 'Open order' })` times out on a `LinkButton`,
+`IconLinkButton` or `ResponsiveLinkButton`.
+**Why:** they used to render a `<button>` inside the router's `<a>`: two
+interactive elements, two tab stops. From 2.2.0 they render the `<a>` alone,
+styled as the button, so its role is `link`.
+**Fix:**
+
+```ts
+await page.getByRole('link', { name: 'Open order' }).click();
+```
+
+Collapsed `ResponsiveButton`s (the `Filter` trigger on a phone, for one) now
+keep their label as screen-reader text, so `getByRole('button', { name })`
+finds them too.
+
+### A test no longer finds a date or time picker by the `button` role, or a slider thumb by the exact name `Minimum`
+
+**When:** after upgrading to 2.2.0, a spec such as
+`getByRole('button', { name: /Delivery date/ })` finds nothing for a
+`DateField`, `DateRangeField` or `TimeField` (or their `*FormField`), or
+`getByRole('slider', { name: 'Minimum' })` finds nothing for a range
+`Slider` (in Testing Library, or in Playwright with `exact: true`: Playwright
+matches a string name as a substring by default, so it still finds it).
+**Why:** a required field now says so on the element a screen reader lands
+on, and a `button` may not carry `aria-required`. The picker trigger is a
+`combobox` (it opens a dialog to pick the value), named by an `aria-label` you
+pass (which on a `DateField` or `DateRangeField` used to name the calendar),
+else by the field's label, else by its `placeholder`, instead of by all of its text. A slider's
+thumbs are now named by the field's label too, so a
+range's are "Price Minimum" and "Price Maximum", and a labelled
+`TransferList`'s panes are "Team Available" and "Team Selected". (The
+`RatingField` stars are also a `radiogroup` now, named by the label.)
+**Fix:** find the control by its role and its full name:
+
+```ts
+const date = page.getByRole('combobox', { name: 'Delivery date' });
+await date.click();
+await expect(date).toHaveAttribute('aria-required', 'true'); // when required
+await page.getByRole('slider', { name: 'Price Minimum' }).press('ArrowRight');
+```
+
+### An end-to-end test no longer finds a required field by a name ending in `*`
+
+**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
+radiogroup, the editor's textbox, the list's listbox, or, for a file picker,
+a group described as "This field is required.").
+**Fix:** find the field by its label alone, and check that it is required
+separately:
+
+```ts
+// Testing Library + jest-dom: toBeRequired() accepts `required`, and
+// `aria-required` on a textbox, combobox, listbox or radiogroup
+expect(screen.getByRole('textbox', { name: 'Email' })).toBeRequired();
+// a slider thumb: toHaveAttribute('aria-required', 'true'); a file picker's
+// group: toHaveAccessibleDescription('This field is required.')
+
+// Playwright: a native input carries `required`, the other controls `aria-required`
+await expect(page.getByRole('textbox', { name: 'Email' })).toHaveAttribute('required');
+await expect(page.getByRole('combobox', { name: 'Delivery date' })).toHaveAttribute('aria-required', 'true');
+```
+
+### An end-to-end test no longer finds `aria-expanded` on a `ResponsiveButton`
+
+**When:** after upgrading to 2.2.0, a spec that selects
+`[aria-expanded="true"]` / `[aria-expanded="false"]` on a `ResponsiveButton`,
+a `ResponsiveLinkButton`, a `LoadMoreButton` or an `EntityHeader` action, or
+asserts `toHaveAttribute('aria-expanded', …)` on one, finds nothing.
+**Why:** the attribute said whether the label was showing. `aria-expanded`
+tells a screen reader the button opens something, so each of them was
+announced as "collapsed" or "expanded" while controlling nothing. From 2.2.0
+it is gone. A `ResponsiveButton` used as a popover, drawer or menu trigger
+(the `Filter` trigger, the data table's view options) still carries the
+trigger's own `aria-expanded`, which follows the overlay.
+**Fix:** find the button by its name, which it keeps collapsed or not, and
+check whether its label is showing instead:
+
+```ts
+const button = page.getByRole('button', { name: 'New order' });
+await expect(button.getByText('New order')).toBeVisible(); // expanded
+await expect(button.getByText('New order')).toHaveClass(/sr-only/); // collapsed
+```
+
+### A test no longer finds a chip's remove button by the exact name `Remove`
+
+**When:** after upgrading to 2.2.0, `getByRole('button', { name: 'Remove' })`
+(Testing Library, or Playwright with `exact: true`) finds nothing next to a
+dismissible `Chip` whose `label` shows text, or a `ComboboxChip` whose children
+are text; or `{ name: 'Icon chevron-down' }` / `{ name: 'Icon trash' }` finds
+nothing on the data table's row expander or a `ContactItem` /
+`OpeningHoursItem` delete button.
+**Why:** a row of chips was a row of buttons all called "Remove", and a screen
+reader could not tell them apart. The button is now named after its chip,
+"Remove Paris" ("Retirer Paris" in French, from `material.chip.dismiss-label`).
+The tooltip still reads "Remove". The row expander and the delete buttons
+were named after their icon; they are now "Toggle row details" (with
+`aria-expanded`), "Remove Contact" and "Remove". The same release names
+buttons that had no name at all, so a spec may now find them by role: the
+`Sidebar` toggle ("Toggle sidebar"), the `LocationPreview` trigger ("Preview
+location", or "Preview {name}"), and each `Autocomplete` chip's remove button
+(a real button now, where it used to be a `div`). All of them follow
+`I18nProvider`, so a spec running in French finds the French name.
+**Fix:** find the button by the chip's label:
+
+```ts
+await page.getByRole('button', { name: 'Remove Paris' }).click();
+// any chip's: Playwright matches a string as a substring by default
+await page.getByRole('button', { name: 'Remove' }).first().click();
+```
+
+### A test no longer finds a pagination, breadcrumb or other built-in label by its English name
+
+**When:** after upgrading to 2.2.0, under a French `I18nProvider`, a selector
+such as `getByRole('navigation', { name: 'pagination' })`,
+`getByLabel('Replace report.pdf')`, `getByText('No filters available')` or
+`getByRole('img', { name: 'Progress: 40%' })` finds nothing.
+**Why:** these labels were English in every language; they now follow
+`I18nProvider`, with the same keys and French as `@nxgt/material-vue`:
+
+| English | French | Key (`material.…`) |
+| --- | --- | --- |
+| `breadcrumb` / `pagination` (the `nav`'s name) | `Fil d'Ariane` / `Pagination` | `breadcrumb.label`, `pagination.label` |
+| `More` (breadcrumb ellipsis) | `Plus` | `breadcrumb.more` |
+| `Breadcrumb` (`DocHeader`) | `Fil d'Ariane` | `doc.breadcrumb` |
+| `No filters available`, `+2 more` | `Aucun filtre disponible`, `+2 de plus` | `filter.empty`, `filter.more` |
+| `Yes` / `No`, `From 5`, `Until …`, `Up to 9` (filter chips) | `Oui` / `Non`, `À partir de 5`, `Jusqu'au …`, `Jusqu'à 9` | `filter.value.*` |
+| `Unread` (`MessageCard`) | `Non lu` | `cards.unread` |
+| `Replace {name}`, `Upload failed` | `Remplacer {name}`, `Échec de l'envoi` | `upload.replace-named`, `upload.failed` |
+| `File type not accepted`, `File exceeds maximum size of …`, `Maximum of 3 files reached` | `Type de fichier non accepté`, `Le fichier dépasse la taille maximale de …`, `Maximum de 3 fichiers atteint` | `upload.invalid-type`, `upload.too-large`, `upload.max-files` |
+| `Write something …`, `Insert {name} emoji` (editor) | `Écrire quelque chose…`, `Insérer l'emoji {name}` | `rich-text-editor.placeholder`, `rich-text-editor.insert-emoji` |
+| `Progress: 40%` | `Progression : 40 %` | `circular-progress.label` |
+| `Media player` (`StxPlayer`, track without a title) | `Lecteur multimédia` | `stx-player.label` |
+| `Side Panel` (`PaneLayoutPane` on a phone) | `Panneau latéral` | `pane-layout.sheet-title` |
+| `Empty JSON` (`JsonViewer`) | `JSON vide` | `json-viewer.empty` |
+| `AM` / `PM` (`TimePicker`) | `a.m.` / `p.m.` | `time-picker.am`, `time-picker.pm` |
+
+In English only one text changed: the upload count error for a single file
+now reads "Maximum of 1 file reached".
+**Fix:** select by the name in the language the test runs in, by a pattern
+that accepts both, or pass your own label, which always wins:
+
+```ts
+await expect(page.getByRole('navigation', { name: /^(pagination|Pagination)$/ })).toBeVisible();
+```
+
+```tsx
+<Pagination aria-label="Results pages">…</Pagination>
+```
+
+### A test no longer finds an icon badge by role `button`, or an `Icon` named "Icon {name}" inside a button
+
+**When:** after upgrading to 2.2.0, one of these finds nothing:
+
+- `getByRole('button')` on the icon badge of a `Contacts`, `OpeningHours`,
+  `PostalAddress`, `AttributesList` or `FileListField` row, the
+  `NetworkUploadField` file preview, the `EntityHeader`, `ConfirmationDialog`
+  or `AppSidebar` icon, the `Stepper` info icon, the `AccordionCard` chevron or
+  a map marker's default pin — or a count of buttons comes out lower;
+- `getByRole('img', { name: 'Icon trash' })` on an `Icon` inside a named
+  `IconButton`, `InputGroupButton` or `IconLinkButton`, or inside one of the
+  badges above (`Icon atom` in the `AppSidebar` brand, `Icon file` in a
+  `FileListField` row or the `NetworkUploadField` preview).
+
+**Why:** each badge was a `<button>` that did nothing when pressed, with no
+name: a useless tab stop (except the disabled `NetworkUploadField` preview) that a screen reader announced as "button". It is
+now a `<span>` with `aria-hidden="true"` and the same look. A `Contacts` badge
+is `role="img"`, named by the contact type ("Phone"), since the row's title
+hides the type once it has a label. The `AccordionCard` header, which was a
+`<div>` only reachable through that chevron, is now itself the `<button>`,
+with `aria-expanded`. An `Icon` inside a named button repeated the button's
+name ("Delete, Icon trash"); it is now `aria-hidden`, unless you gave it an
+`aria-label` of your own. Outside a named button, an `Icon` is still named
+"Icon {name}" by default.
+**Fix:** select the badge by what it shows, not by role, and the control by
+its own name:
+
+```ts
+// a Contacts badge
+await expect(page.getByRole('img', { name: 'Phone' })).toBeVisible();
+// an AccordionCard header
+await page.getByRole('button', { name: 'Shipping' }).click();
+// the button, not the icon inside it
+await page.getByRole('button', { name: 'Delete' }).click();
+```
+
+If you passed an `IconButton` as `ConfirmationDialog`'s `icon`, pass the glyph
+alone and style the badge with `iconProps={{ variant, color }}`: the dialog
+already wraps it in a badge, and yours is now a button inside a `<span>`.
+
+### `An invalid form control with name='…' is not focusable`
+
+**When:** submitting a form with an empty `required` `UploadField`, before
+2.2.0: nothing happens and this is the only trace, in the console.
+**Why:** the field's `<input type="file">` was `hidden`. The browser refuses the
+submit because the required input is empty, but cannot focus a hidden control
+to show why.
+**Fix:** upgrade. The input is now visually hidden but focusable, so the submit
+stops on it with the browser's own "select a file" message. If you validate
+with React Hook Form (`UploadFormField`) and do not want the browser's check,
+put `noValidate` on the `<form>`.
+
+### A `DateField` or `DateRangeField` with `disabled` still opens
+
+**When:** before 2.2.0, `disabled` (or `DateFormField` in a disabled React
+Hook Form field) left the trigger clickable; the calendar opened with every day
+greyed out.
+**Why:** the props were spread onto the `Calendar`, where `disabled` is
+react-day-picker's day rule, so `true` meant "every day".
+**Fix:** upgrade: `disabled` now disables the trigger. A day rule goes in
+`disabledDays` (a non-boolean `disabled` still works, for now):
+
+```tsx
+<DateField label="Delivery" disabledDays={{ dayOfWeek: [0] }} />
+```
+
+The same release moves `id`, `aria-describedby` and `data-*` to the trigger:
+see the next entry.
+
+### An `id`, `aria-describedby` or `data-testid` on a `DateField`, `DateRangeField` or `TimeField` is not on the trigger
+
+**When:** before 2.2.0: `getByTestId` finds the calendar (and only while the
+popover is open) rather than the field, and a hint in `aria-describedby` is
+not read as the field's description. On a `TimeField` the attributes landed
+on the inner box on a desktop and nowhere on a phone. No error is printed.
+**Why:** the field's root is a popover (or, for a `TimeField` on a phone, a
+dialog), which renders no element of its own, so the props went on to the
+calendar or the picker inside it.
+**Fix:** upgrade: `id`, `aria-describedby` and every `data-*` attribute now go
+on the trigger, the `combobox` that has focus. A test that relied on the old
+place finds the calendar by its role instead:
+
+```tsx
+<DateRangeField label="Stay" data-testid="stay" aria-describedby="stay-hint" />
+
+screen.getByTestId('stay'); // the trigger, open or closed
+screen.getByRole('grid'); // the calendar, once open
+```
+
+The `DateRangeField` trigger also carries `data-slot="date-range-field-trigger"`
+where it had `popover-trigger`, as `DateField`'s carries `date-field-trigger`:
+a selector on the old value now matches nothing.
+
+### A test no longer finds the label or helper text inside a date or time picker's trigger
+
+**When:** after upgrading to 2.2.0, `within(trigger).getByText('Delivery date')`
+or a selector such as `[data-slot="date-field-trigger"] label` finds nothing
+for a `DateField`, `DateRangeField` or `TimeField` (or their `*FormField`); a
+`className` meant for the trigger button now sizes the whole field; or a
+`DateFieldTrigger`, `DateRangeFieldTrigger` or `TimeFieldTrigger` rendered on
+its own shows no label and no helper text. No error is printed.
+**Why:** the `Label` and the helper text were inside the trigger `<button>`. A
+`<label>` is interactive content, which a button may not hold, and a screen
+reader read the helper text as part of the value. They now sit beside the
+button, in the field's root `div` (`data-slot="date-field"`,
+`date-range-field` or `time-field`), which also takes `className`. The trigger
+(`data-slot="…-trigger"`, still carrying your `id`, `aria-describedby` and
+`data-*`) points at them: `aria-labelledby` the Label, `aria-describedby` the
+helper text, then your ids. The Label is `for` the trigger, so a click on it
+still opens the picker. The `*Trigger` components now render only what the
+button shows; their `label`, `helperText` and `labelId` are ignored. A disabled field
+dims its trigger only, no longer its label and helper text. On a
+`TimeField` the default `data-pw` (the `name`, or `time-field`) is on the root
+`div` too, as it was on the box inside the button; on a `DateField` or
+`DateRangeField` it stays on the trigger.
+**Fix:** find the trigger by its name and description, and the whole field by
+its root:
+
+```ts
+const date = page.getByRole('combobox', { name: 'Delivery date' });
+await expect(date).toHaveAccessibleDescription('We deliver Monday to Saturday.');
+const field = page.locator('[data-slot="date-field"]'); // label, trigger, helper
+```
+
+### A test no longer finds a `DurationField` input by the field's label, or a `Slider`'s `aria-label` on its root
+
+**When:** after upgrading to 2.2.0, `getByRole('textbox', { name: 'Duration' })`
+finds nothing for a `DurationField`, or `aria-label` / `aria-invalid` is no
+longer on a `Slider`'s root `span` (`data-slot="slider"`).
+**Why:** the Label was `for` the hours input only, so the minutes input had no
+name. The field is now a `group` named by its Label and described by its
+helper text, and each input is named by its part, "Hours" and "Minutes"
+(`material.duration-field.hours-label` / `minutes-label`). A `Slider`'s root is
+a plain `span`, where a name or `aria-invalid` is neither allowed nor read: an
+`aria-label` or `aria-labelledby` you pass now names every thumb (through
+`aria-labelledby`), and `aria-invalid` (or `error`) goes on every thumb, and a vertical `Slider`'s `label`, which it does not
+show, still names them.
+**Fix:** find the part inside the group, and the thumb by its name:
+
+```ts
+const duration = page.getByRole('group', { name: 'Duration' });
+await duration.getByRole('textbox', { name: 'Minutes' }).fill('30');
+const volume = page.getByRole('slider', { name: 'Volume' });
+await expect(volume).toHaveAttribute('aria-invalid', 'true');
+```
+
+### A test no longer finds `aria-invalid` on an upload field's group or drop zone
+
+**When:** after upgrading to 2.2.0, `[aria-invalid]` or `toHaveAttribute('aria-invalid')`
+finds nothing on the `ImageField` frame, the `FileListField` or
+`NetworkUploadField` / `S3UploadField` drop zone, or the `UploadField` box.
+**Why:** ARIA 1.2 does not allow `aria-invalid` on a `group` or a `button`
+(or a plain `div`). The error is now a description, and the red outline comes
+from `data-invalid`. It describes one element per field, so a screen reader
+reads it once: the drop zone for `NetworkUploadField` / `S3UploadField` (the field's `group`
+once a file hides the drop zone or it is disabled), the `group` named by the label for
+`UploadField`, `ImageField` and `FileListField`. An `error` without `helperText` is described by a visually
+hidden "This value is not valid." (`material.zod.default`); for `UploadField`
+only with `trailing`, since otherwise its file input carries `aria-invalid`.
+**Fix:** assert the description on that element, or the data attribute:
+
+```ts
+const zone = page.getByRole('button', { name: /drag & drop/i });
+await expect(zone).toHaveAccessibleDescription('Add a file.');
+await expect(zone).toHaveAttribute('data-invalid', 'true');
+
+// FileListField, ImageField, UploadField, and NetworkUploadField /
+// S3UploadField once the drop zone is hidden or disabled: the group
+const files = page.getByRole('group', { name: 'Attachments' });
+await expect(files).toHaveAccessibleDescription('Add at least one file.');
+```
+
+### A test no longer finds `aria-invalid` on a `CheckboxGroup`
+
+**When:** after upgrading, `[aria-invalid]` or `toHaveAttribute('aria-invalid')`
+finds nothing on a `CheckboxGroup` or `CheckboxGroupFormField` in error.
+**Why:** `CheckboxGroupFormField` passed `aria-invalid` to `CheckboxGroup`,
+which put it on its wrapper `div`, where ARIA does not allow it. The wrapper
+is now a `role="group"` named by its `label`, and the error is its
+description: the helper text (the error message, in a form wrapper), or a
+visually hidden "This value is not valid." (`material.zod.default`) when there
+is none. A `CheckboxGroupFormField` in error with no message that shows your
+`helperText` is described by both: "<helperText> This value is not valid.".
+`RadioGroup` keeps `aria-invalid` on its `radiogroup`, where it is allowed.
+**Fix:** find the group by its question and assert its description:
+
+```ts
+const channels = page.getByRole('group', { name: 'Contact channels' });
+await expect(channels).toHaveAccessibleDescription('Pick at least one.');
+```
+
+### A test no longer finds `aria-invalid` on a `Switch` row or an `Autocomplete`'s chips
+
+**When:** after upgrading to 2.2.0, `[aria-invalid]` on the bordered row of a
+`Switch` with a `label`, or on the `div` around an `Autocomplete`'s chips,
+finds nothing although the field is in error.
+**Why:** ARIA does not allow `aria-invalid` on a plain `div`. It is now on the
+control alone: the `switch` button, and the `Autocomplete`'s `combobox` input.
+The row and the chips box show the error with a red border.
+**Fix:** assert it on the control:
+
+```ts
+await expect(page.getByRole('switch', { name: 'Notifications' })).toHaveAttribute('aria-invalid', 'true');
+await expect(page.getByRole('combobox', { name: 'Country' })).toHaveAttribute('aria-invalid', 'true');
+```
+
+### A test no longer finds the breadcrumb's home button
+
+**When:** after upgrading, `getByRole('button', { name: 'Home' })` finds
+nothing in an `AppBreadcrumb` (or the `ActivityLayout` around it), or a
+selector such as `nav a li` or `nav a button` stops matching.
+**Why:** the home crumb was a `<button>` inside the link, and every crumb's
+`<li>` sat inside its `<a>`: two nested controls, and an `<ol>` holding
+something other than `<li>`s. Each crumb is now `<li><a>…</a></li>`, and the
+home icon is the link itself, named "Home" (`material.app-shell.home`,
+translated). Pressing it still goes to the router's root: its `basename`, or `/`.
+**Fix:** find it as a link:
+
+```ts
+await page.getByRole('navigation', { name: 'breadcrumb' })
+  .getByRole('link', { name: 'Home' })
+  .click();
+```
+
+### `#<name>` no longer finds a `SwitchFormField` or `CheckboxFormField`
+
+**When:** after upgrading, a selector such as `#notifications`, or a
+`<label htmlFor="notifications">` of your own, no longer reaches the control of
+`<SwitchFormField name="notifications">` or `<CheckboxFormField name="notifications">`.
+**Why:** the wrappers gave the control the field's `name` as its `id`, so two
+forms on one page with the same field (a sign-in and a sign-up form both with
+`remember`) had two elements with one `id`, and a label in one form toggled the
+other form's control. Without an `id` of yours, the control now gets a
+generated one, as the bare `Switch` and `Checkbox` always did.
+`RadioGroupFormField` and `CheckboxGroupFormField` had the same problem, and
+their options too: see
+[the next entry](#name-or-option-value-no-longer-finds-a-radio-or-checkbox-group-or-one-of-its-options).
+**Fix:** select by role and name, by `name`, or pass the `id` you rely on:
+
+```tsx
+await page.getByRole('switch', { name: 'Notifications' }).click();
+await page.locator('[name="notifications"]').click();
+// or keep a fixed id
+<SwitchFormField control={control} name="notifications" id="notifications" label="Notifications" />
+```
+
+### `#<name>` or `#<option value>` no longer finds a radio or checkbox group or one of its options
+
+**When:** after upgrading, a selector such as `#married` no longer reaches
+`<RadioGroupFormField name="married">` or `<CheckboxGroupFormField name="married">`,
+or `#yes` (or a `<label htmlFor="yes">` of your own) no longer reaches the
+option whose `value` is `yes` in a `RadioGroup` or `CheckboxGroup`.
+**Why:** the wrappers gave the group the field's `name` as its `id`, and every
+group gave each option its `value` as `id`. Two yes/no questions in one form
+therefore had two inputs with `id="yes"`: both "Yes" labels pointed at the
+first one, and clicking the second question's label answered the first. The
+group now takes your `id`, or a generated one, and option *i* is
+`` `${id}-${i}` ``.
+**Fix:** pass the group the `id` you rely on, then find an option by its role
+and name inside it, or by its index:
+
+```tsx
+<RadioGroupFormField control={control} name="married" id="married" options={yesNo} />
+
+await page.locator('#married').getByRole('radio', { name: 'Yes' }).check();
+await page.locator('#married-0').check(); // the first option
+```
+
+### An empty `UploadField` or `TimeField` is no longer tinted
+
+**When:** after upgrading, an `UploadField` showing its `placeholder`, or a
+`TimeField` with no value, has the light background of an empty field instead
+of the primary tint.
+**Why:** `inputDefaultClassNames` tints an `<input>` while it is not showing its
+placeholder (`not-placeholder-shown:`). Those two fields, and the `Switch` row,
+are `div`s styled with those classes, and a `div` never shows a placeholder,
+so they were tinted all the time. They are now tinted when they hold a value
+(the `Switch` row: while it is on), like an `<input>`.
+**Fix:** nothing to do for these fields. If you style a `div` of your own with
+`inputDefaultClassNames`, it has the same problem: on such a `div` the tint is
+always on, so turn it off while there is no value (with `cn`, whose
+tailwind-merge drops the earlier tint).
+
+```tsx
+import { cn, inputDefaultClassNames } from '@nxgt/material';
+
+<div className={cn(inputDefaultClassNames, !hasValue && 'not-placeholder-shown:bg-muted/5')}>
+```
+
+### `ConfirmDialog` buttons stay in English
+
+**When:** a `ConfirmDialog` or `ConfirmationDialog` without
+`confirmLabel` / `cancelLabel` (`confirmText` / `cancelText`) shows "Confirm"
+and "Cancel" whatever the language. Versions before 2.2.0 only.
+**Why:** the defaults were hard-coded English strings.
+**Fix:** upgrade to 2.2.0, where they come from
+`material.confirm-dialog.confirm` / `.cancel` (English and French), which an
+app may override like any `material.*` string. On an older version, pass the
+labels yourself:
+
+```tsx
+<ConfirmDialog confirmLabel={t('app.confirm')} cancelLabel={t('app.cancel')} {...props} />
+```
+
+### A `ConfirmationDialog` opened with `open` no longer closes
+
+**When:** after upgrading to 2.2.0, a `ConfirmationDialog` given `open` (to
+show it straight away) but no `onOpenChange` stays open: Cancel, Confirm,
+Escape and the close button do nothing.
+**Why:** before 2.2.0, `open` only seeded the dialog's own state, and the
+dialog then opened and closed itself. Since 2.2.0, `open` makes it controlled,
+as with every Radix dialog: it shows what `open` says, and closing is a call to
+`onOpenChange` that your state has to follow.
+**Fix:** to open it initially and let it manage itself, pass `defaultOpen`; to
+control it, pass `onOpenChange` with `open`:
+
+```tsx
+<ConfirmationDialog defaultOpen title="Archive order" onConfirm={archive} />
+
+// or, controlled
+const [open, setOpen] = useState(true);
+<ConfirmationDialog open={open} onOpenChange={setOpen} title="Archive order" onConfirm={archive} />
+```
+
+### A menu item selected by `[data-variant=destructive]` stops matching
+
+**When:** your CSS, or a test, targets `[data-variant=destructive]` on a
+`MenubarItem`, and stops matching after upgrading to 2.2.0.
+**Why:** `MenubarItem` takes `variant="error"`, as `DropdownMenuItem` and
+`ContextMenuItem` do, and keeps `"destructive"` as a deprecated alias. Both
+render `data-variant="error"`, and both use the `error` colour.
+**Fix:** select `[data-variant=error]`, and write `variant="error"`:
+
+```tsx
+<MenubarItem variant="error" onSelect={remove}>Delete</MenubarItem>
+```
+
+```css
+[data-slot='menubar-item'][data-variant='error'] { font-weight: 600; }
+```
+
+### Keys typed right after opening a dialog, sheet or drawer land inside it
+
+**When:** after upgrading, a test (or code of yours) that opens a `Dialog`,
+`AlertDialog`, `Sheet` or `Drawer` and then types or presses a key without
+first clicking or focusing something types into the overlay's first field, or
+presses its first button, instead of the element that had focus. A check such
+as `expect(opener).toHaveFocus()` right after opening fails; an alert dialog
+now has its Cancel focused, so Enter cancels rather than confirming.
+**Why:** before 2.2.0, `DialogContent`, `AlertDialogContent`,
+`SheetContent` and `DrawerContent` cancelled Radix's (and Vaul's) open
+auto-focus, so a modal opened with focus left behind it, on a page a keyboard
+or screen-reader user could no longer reach. That fails WCAG 2.4.3 (focus
+order). A modal now moves focus into itself when it opens, as the WAI-ARIA
+dialog pattern asks: to its first control, to its content when it has none,
+and to `AlertDialogCancel` in an alert dialog (to its first control when it
+has no Cancel). Closing still hands focus back to the element that opened it.
+**Fix:** in a test, act on the element you mean rather than on whatever has
+focus, which is what a user does:
+
+```ts
+await page.getByRole('button', { name: 'Rename' }).click();
+const dialog = page.getByRole('dialog');
+await dialog.getByRole('textbox', { name: 'Name' }).fill('report.pdf');
+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:
+
+```tsx
+const saveButtonRef = useRef<HTMLButtonElement>(null);
+
+<DialogContent
+  onOpenAutoFocus={(event) => {
+    event.preventDefault();
+    saveButtonRef.current?.focus();
+  }}
+>
+  {/* … */}
+  <Button ref={saveButtonRef}>Save</Button>
+</DialogContent>
+```
+
+A `Drawer` also takes Vaul's `autoFocus={false}`, which does the same as
+preventing the default.
+
+---
+
+## PDF reader
+
+### `'PdfViewer' is deprecated`
+
+**When:** after upgrading to 2.2.0, your editor strikes through `PdfViewer`,
+or a lint rule such as `@typescript-eslint/no-deprecated` reports it.
+**Why:** before 2.2.0 the `@deprecated` tag meant for the old alias
+`PdfViewer` sat one comment too high and struck through `PdfReader` instead.
+**Fix:** import `PdfReader`. It is the same component with the same props:
+
+```tsx
+import { PdfReader } from '@nxgt/material/components';
+
+<PdfReader file="/documents/contract.pdf" />
+```
+
+### Download saves the PDF as `document.pdf`
+
+**When:** the toolbar's Download button saves every URL document as
+`document.pdf`. Seen with versions before 2.2.0.
+**Why:** those versions hard-coded the name for a URL, and had no way to pass
+one. Since 2.2.0 the name is the `fileName` prop, then a `File`'s own name,
+then the last segment of the URL's path, and `document.pdf` only when there is
+none; `.pdf` is added when missing.
+**Fix:** update `@nxgt/material`, and pass `fileName` when the URL ends in an
+id or in `pdf` rather than a useful name:
+
+```tsx
+<PdfReader file="/api/invoices/1042/pdf" fileName="INV-1042" />
+```
+
+### Download does nothing, or opens the PDF instead of saving it
+
+**When:** clicking Download saves nothing in Firefox or Safari, or the
+downloads list shows the file as failed; or, for a document on another origin,
+the browser navigates to it instead of saving it. Seen with versions before
+2.2.0.
+**Why:** the object URL was revoked right after `click()`, before those
+browsers read it, and the link was never attached to the page. For a URL on
+another origin, browsers ignore the `download` attribute and follow the link.
+Since 2.2.0 the link is attached and the URL lives for a minute. A URL
+document is saved from the bytes the reader already loaded, so it is not
+downloaded again; the URL is fetched when those bytes are gone, and opened in
+a new tab only when that fails too (no CORS headers, or an error status); a
+popup blocker may stop that tab. A `{ url, httpHeaders }` source is fetched
+with its headers and never opened in a tab, which would load it without them:
+when that fetch fails (a refused CORS preflight, a 401), Download and Print do
+nothing.
+**Fix:** update `@nxgt/material`. For a cross-origin URL, serve it with CORS
+headers, as the reader needs them to render it anyway; with `httpHeaders`,
+list them in `Access-Control-Allow-Headers`. To handle a failure yourself,
+pass `onDownload` / `onPrint`.
+
+### `SecurityError: Blocked a frame with origin` when printing
+
+**When:** clicking Print on a document served from another origin throws an
+uncaught `SecurityError` in the console and nothing prints. Seen with versions
+before 2.2.0.
+**Why:** the reader printed the URL itself in a hidden frame, and a page may
+not call `print()` on a frame from another origin. Since 2.2.0 it prints a
+same-origin copy of the loaded bytes, and opens the document in a new tab when
+the browser still refuses (a popup blocker may stop that tab).
+**Fix:** update `@nxgt/material`. To print differently, pass your own
+`onPrint`.
+
+### A password-protected or broken PDF leaves the reader blank
+
+**When:** a `PdfReader` shows only its toolbar: no password field for a
+protected PDF, no message for a URL that fails, and no spinner while a
+document loads. Seen with versions before 2.2.0.
+**Why:** react-pdf renders its children only once the document has loaded, and
+the loading, error and password overlays were children, so none of them ever
+showed. Since 2.2.0 they render beside the document until it loads. The
+password form also says "Incorrect password. Try again."
+(`material.pdf-reader.password-incorrect`) after a wrong one, marks the field
+`aria-invalid`, announces the message and focuses the field again; once the
+right password opens the document, the pages show.
+**Fix:** update `@nxgt/material`. On an older version, `onLoadError` lets you
+show your own message for a URL that fails; a protected PDF raises no error,
+so it stays blank there.
+
+### Escape closes the whole dialog around a `PdfReader`
+
+**When:** a `PdfReader` inside this package's `Dialog`, `Sheet` or `Drawer`
+(Radix): with the reader's search bar open, Escape closes the whole dialog
+instead of the search bar. With a dialog of your own that listens for Escape
+in the bubble phase, Escape never closed it at all. Seen with versions before
+2.2.0.
+**Why:** Radix dismisses its layers from a capture-phase listener on
+`document`, which runs before the reader's own key handler. The reader then
+called `preventDefault()` on every Escape, too late for Radix and wrongly for
+everyone else. Since 2.2.0 the reader closes its open search bar from a
+capture listener on `window`, which runs first, and leaves every other Escape
+alone: the first Escape closes the search bar, the next one the dialog.
+**Fix:** update `@nxgt/material`.
+
+### `onPageChange` reports page 0 or a page past the end
+
+**When:** the page callback receives `0`, or `numPages + 1`, from the Previous
+and Next keys or a number typed in the page field; or it fires again for the
+page already shown. Seen with versions before 2.2.0.
+**Why:** the reader clamped the page it showed but reported the page it was
+asked for. Since 2.2.0 it reports the clamped page, and only when the page
+changes.
+**Fix:** update `@nxgt/material`. A clamp you added in the callback can go.
+
+### Pages are cut off, or too small, in fit width or fit page
+
+**When:** a `PdfReader` with `defaultFitMode` `'width'` or `'page'` shows an
+A4 or landscape page wider than the reader, cut at the bottom, or smaller than
+the room it has; pages not drawn yet keep a Letter-sized gap. Seen with
+versions before 2.2.0.
+**Why:** the fit assumed every page was US Letter (612 × 792 points) and
+ignored each page's own size. It also measured the reader before the page area
+existed, so it fitted an 800 × 600 box whatever the reader's size. Since 2.2.0
+the reader reads every page's size, 25 pages at a time. It fits the widest
+and the tallest of the first 25 pages with one zoom for the whole document
+rather than one per page, and sizes each placeholder and
+thumbnail from its own page.
+**Fix:** update `@nxgt/material`. On an older version,
+`defaultFitMode="custom"` with an `initialScale` of your own avoids the wrong
+fit.
+
+### Search misses matches, or counts 0/0 until you press Enter
+
+**When:** the `PdfReader` search bar counts `0/0` while you type, finds only
+the first match in each line, misses a word split across two runs of text,
+misses `Café` when you type `cafe`, and never counts pages you have not
+scrolled to. Seen with versions before 2.2.0.
+**Why:** the search only counted the highlights already drawn, and highlighted
+the first case-insensitive match in each text run. Since 2.2.0 it reads the
+text of every page, drawn or not, as you type. Every match counts, including
+one split across runs, and case, accents, ligatures and the width of white
+space are ignored. The counter reads `0/N` until you move to a match, and
+Enter, F3 or the up and down buttons beside the counter show the match's page
+and mark it.
+**Fix:** update `@nxgt/material`.
+
+### `initialPage` is ignored, or the page number does not follow scrolling
+
+**When:** a `PdfReader` with `initialPage` opens on page 1 while its page
+field says the page you asked for; scrolling through the document leaves the
+page field, `onPageChange` and the highlighted thumbnail on the page you
+started from. Seen with versions before 2.2.0.
+**Why:** the reader scrolled to a page only when the page number changed, so
+the page it opened on was never scrolled to, and nothing watched the scroll.
+Since 2.2.0 it opens on `initialPage` once the page area is measured and the
+pages above it have their size (or after 2 seconds), and keeps it in place
+while the zoom settles, until you scroll or click in the page area; a number
+past the end opens the last page, a new `file` opens on `initialPage` again,
+and the page most on screen becomes the current page as you scroll. A page you
+ask for (keys, page field, thumbnail, outline, search) is scrolled to and
+reported once, not each page passed on the way. Only the reader's page area
+scrolls: the page around it no longer jumps to line the reader up.
+**Fix:** update `@nxgt/material`.
+
+### `Type 'Blob' is not assignable to type 'string | File | null'` on `PdfReader`
+
+**When:** before 2.2.0, passing a `Blob`, an `ArrayBuffer` or a `Uint8Array` to
+`file` (a `Uint8Array` shows as `Uint8Array<ArrayBufferLike>`). An inline
+`{ url, httpHeaders }` fails with `Object literal may only specify known
+properties, and 'url' does not exist in type 'File'` instead.
+**Why:** `file` took only a URL or a `File` then.
+**Fix:** upgrade; from 2.2.0 `file` takes all of them:
+
+```sh
+bun add @nxgt/material@^2.2.0
+```
+
+On an older version, wrap a Blob in a `File`
+(`new File([blob], 'invoice.pdf')`), or pass an object URL.
+
+### `PdfReader cannot open [object …]`
+
+The full message is `PdfReader cannot open [object Object]: pass a URL, a Blob,
+an ArrayBuffer, a Uint8Array or { url, httpHeaders }.`
+
+**When:** rendering `PdfReader` throws this `TypeError`.
+**Why:** `file` is none of the sources the reader opens: an object without
+`url` (such as `{ path }` or `{ href }`), a number, or a response not read
+yet.
+**Fix:** pass the URL, or read the response into a Blob first:
+
+```ts
+const file = await (await fetch('/api/report')).blob();
+```
+
+### `The PDF file is empty, i.e. its size is zero bytes.`
+
+**When:** `PdfReader` shows "Failed to load document" with this message, for
+an `ArrayBuffer` or a `Uint8Array`.
+**Why:** the buffer has no bytes: it was detached, transferred to a worker by
+pdf.js (another viewer, your own `getDocument` call) or by `postMessage`,
+before the reader got it. From 2.2.0 the reader copies the bytes it is given,
+so it never detaches your buffer itself.
+**Fix:** in a layout of your own, give react-pdf's `Document` the source from
+`usePdfSource(file)` (exported beside `usePdfReader` since 2.2.0), which copies
+bytes. Otherwise pass a copy to whatever transfers it, or keep the bytes as a
+`Blob`:
+
+```ts
+pdfjs.getDocument({ data: bytes.slice(0) }); // your own pdf.js call gets a copy
+const blob = new Blob([bytes], { type: 'application/pdf' }); // or keep a Blob
+```
+
+### The PDF reloads, and goes back to its first page, on every render
+
+**When:** `file` is a `Blob`, an `ArrayBuffer` or a `Uint8Array` built during
+render.
+**Why:** a Blob or a buffer is compared by identity: a new object is a new
+document. A URL, even an inline `{ url, httpHeaders }` object, is compared by
+its URL and headers, so it does not reload.
+**Fix:** keep the same object between renders:
+
+```tsx
+const file = useMemo(() => new Blob([bytes], { type: 'application/pdf' }), [bytes]);
+<PdfReader file={file} fileName="report.pdf" />
+```
+
+### The PDF goes back to its first page when the access token is refreshed
+
+**When:** `file` is `{ url, httpHeaders }` and the app renews its token, so
+`httpHeaders.Authorization` changes while the same document is open.
+**Why:** the headers are part of what identifies the document, as a
+different token may be a different user: new headers load the document
+again, and the reader starts again from `initialPage`.
+**Fix:** keep the headers the same while the document is open (a token
+that lives as long as the page does), or fetch the file once yourself and
+pass the Blob:
+
+```tsx
+function Contract({ id, token }: { id: string; token: string }) {
+  const [file, setFile] = useState<Blob | null>(null);
+  // Only a new document fetches again; a new token does not.
+  useEffect(() => {
+    let cancelled = false;
+    fetch(`/api/documents/${id}`, { headers: { Authorization: `Bearer ${token}` } })
+      .then((response) => response.blob())
+      .then((blob) => {
+        if (!cancelled) setFile(blob);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [id]);
+  return <PdfReader file={file} />;
+}
+```
+
+### `An internal link leading to page 3 was clicked, but neither <Document> was provided with onItemClick…`
+
+**When:** clicking a link inside the PDF (a table of contents, "see page 3")
+does nothing, and the console logs this react-pdf warning. Versions before
+2.2.0, when the target page was not drawn yet.
+**Why:** react-pdf scrolled to the page only if it was already on screen or
+close to it.
+**Fix:** update `@nxgt/material`: from 2.2.0 an internal link goes through the
+reader, like the page field, and the page number follows. In a layout of your
+own on react-pdf, pass `onItemClick={({ pageNumber }) => goToPage(pageNumber)}` to
+`Document`.
+
+### A `DropdownMenu` opened in fullscreen does not show
+
+**When:** an element of yours is in fullscreen (`requestFullscreen()`), and
+a `DropdownMenu` opened inside it stays invisible, though its button says it
+is open.
+**Why:** the menu is placed at the end of `body`, and in fullscreen the
+browser shows only the fullscreen element.
+**Fix:** place it in the fullscreen element with `DropdownMenuContent`'s
+`container` (from 2.2.0); `PdfReader`'s zoom menu does this itself:
+
+```tsx
+import { useState } from 'react';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+} from '@nxgt/material/components';
+
+const [container, setContainer] = useState<Element | null>(null); // in your component
+
+<DropdownMenu onOpenChange={(open) => open && setContainer(document.fullscreenElement)}>
+  <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
+  <DropdownMenuContent container={container}>…</DropdownMenuContent>
+</DropdownMenu>
+```
+
+### A tooltip does not show in fullscreen
+
+**When:** an element is in fullscreen (a `PdfReader` after its Fullscreen
+button, or your own `requestFullscreen()`), and hovering a button with a tooltip
+shows nothing. Seen with versions before 2.2.0.
+**Why:** the tooltip was placed at the end of `body`, and in fullscreen the
+browser shows only the fullscreen element.
+**Fix:** update `@nxgt/material`: a tooltip opens inside the element in
+fullscreen. To place it elsewhere, pass `container` to `Tooltip` or
+`TooltipContent`.
+
+### A PDF page shows sideways in `PdfReader`
+
+**When:** a page that other viewers show landscape (a scanned page, a wide
+table) is drawn portrait, its content turned a quarter, and the fit zoom and
+the gap it takes are those of a portrait page. Seen with versions before 2.2.0.
+**Why:** the page asks to be shown turned (`/Rotate` in the PDF), and the
+reader drew every page at its own rotation only, 0 until you pressed Rotate.
+Since 2.2.0 it adds the page's `/Rotate` to its own, for the page, its
+thumbnail, its placeholder and the fit.
+**Fix:** update `@nxgt/material`.
+
+### The zoom changes by itself while a long PDF is open
+
+**When:** in fit width or fit page, a `PdfReader` on a long document mixing
+page sizes shrinks its zoom a moment after it opened, sometimes while you are
+reading. Seen with versions before 2.2.0.
+**Why:** the fit took the largest of the page sizes read so far, and the sizes
+arrive 25 pages at a time: a larger page read later moved the zoom. Since
+2.2.0 the fit uses the first 25 pages, read together when the document
+opens, and never moves after that; a wider page further on scrolls sideways in
+fit width. The fit also stops at 500%, where a tiny page used to fit to any
+zoom.
+**Fix:** update `@nxgt/material`. To keep one zoom from the start, use
+`defaultFitMode="custom"` with an `initialScale`.
+
+### A link in a PDF replaces the page the reader is on
+
+**When:** clicking a web address inside a document shown by `PdfReader`
+navigates the tab away from your app. Seen with versions before 2.2.0.
+**Why:** the link opened as the PDF asked, which is the same tab unless the link
+says a new window. Since 2.2.0 it opens in a new tab.
+**Fix:** update `@nxgt/material`. `externalLinkTarget` picks another target,
+such as `'_self'` for the previous behaviour.
+
+### `onPageChange` is not called when `initialPage` is past the end, or after a new file
+
+**When:** `initialPage` is larger than the document, and the reader opens on the
+last page without reporting it; or `file` changes and the reader goes back to
+`initialPage` while your page state keeps the old number. Seen with versions
+before 2.2.0.
+**Why:** only pages you moved to were reported, not the pages the reader moved
+to itself. Since 2.2.0 both are reported, once.
+**Fix:** update `@nxgt/material`. A page you kept in sync by hand can go.
+
+---
+
+## Reporting a bug
+
+If an error comes from inside this package and none of the entries above
+applies, report it to the maintainers at <stevegires@gmail.com> with the
+`@nxgt/material` version, the full message, whether the app is SSR or SPA, and
+the bundler and its version.