@nxgt/material-vue 0.20.0 → 0.22.0

package/docs/troubleshooting.md

@@ -0,0 +1,2202 @@
+# 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 'leaflet'`](#cannot-find-package-leaflet)
+- [`Cannot read properties of null (reading 'ce')`](#cannot-read-properties-of-null-reading-ce)
+- [`Missing "./print" specifier in "@nxgt/material-vue" package`](#missing-print-specifier-in-nxgtmaterial-vue-package)
+- [`Cannot find package 'lucide-vue-next'`](#cannot-find-package-lucide-vue-next)
+- [`` [@nxgt/material-vue/pdf] Rendering a PDF needs the optional peers `react` and `@react-pdf/renderer`: bun add react @react-pdf/renderer@^4.9 ``](#nxgtmaterial-vuepdf-rendering-a-pdf-needs-the-optional-peers-react-and-react-pdfrenderer-bun-add-react-react-pdfrenderer49)
+
+**Styles & assets**
+
+- [Components render unstyled, with no error](#components-render-unstyled-with-no-error)
+- [`<Icon>` renders nothing](#icon-renders-nothing)
+- [`JsBarcode is not a function`](#jsbarcode-is-not-a-function)
+- [A `LinkButton` selected as a `button` stops matching](#a-linkbutton-selected-as-a-button-stops-matching)
+- [A `Toc`, `Pager`, `SeeAlso` or `ScrollProgress` inside `Doc` selected by `data-slot` stops matching](#a-toc-pager-seealso-or-scrollprogress-inside-doc-selected-by-data-slot-stops-matching)
+- [A `ResponsiveButton` selected by `[aria-expanded]` stops matching](#a-responsivebutton-selected-by-aria-expanded-stops-matching)
+- [A menu item selected by `[data-variant=destructive]` stops matching](#a-menu-item-selected-by-data-variantdestructive-stops-matching)
+- [A test no longer finds a date or time picker by the `button` role, or a slider thumb by the exact name `Minimum`](#a-test-no-longer-finds-a-date-or-time-picker-by-the-button-role-or-a-slider-thumb-by-the-exact-name-minimum)
+- [An end-to-end test no longer finds a required field by a name ending in `*`](#an-end-to-end-test-no-longer-finds-a-required-field-by-a-name-ending-in-)
+- [A test no longer finds `aria-invalid` on an upload field's group or drop zone](#a-test-no-longer-finds-aria-invalid-on-an-upload-fields-group-or-drop-zone)
+- [A test no longer finds `aria-invalid` on a `Switch` row or an `Autocomplete` box](#a-test-no-longer-finds-aria-invalid-on-a-switch-row-or-an-autocomplete-box)
+- [A test no longer finds the breadcrumb's home button](#a-test-no-longer-finds-the-breadcrumbs-home-button)
+- [A `QRCode`'s `aria-label` is no longer on its wrapper](#a-qrcodes-aria-label-is-no-longer-on-its-wrapper)
+- [A `CheckboxGroup` or `RadioGroupField` option selected by `#<id>-<value>` stops matching](#a-checkboxgroup-or-radiogroupfield-option-selected-by-id-value-stops-matching)
+
+**SSR & build**
+
+- [`ReferenceError: window is not defined`](#referenceerror-window-is-not-defined)
+- [`ReferenceError: DOMMatrix is not defined`](#referenceerror-dommatrix-is-not-defined)
+- [`ReferenceError: localStorage is not defined`](#referenceerror-localstorage-is-not-defined)
+- [`Hydration completed but contains mismatches.`](#hydration-completed-but-contains-mismatches)
+- [`Failed to resolve component: LocationFormField`](#failed-to-resolve-component-locationformfield)
+
+**Pinia, router & forms**
+
+- [`"getActivePinia()" was called but there was no active Pinia`](#getactivepinia-was-called-but-there-was-no-active-pinia)
+- [`injection "Symbol(route location)" not found`](#injection-symbolroute-location-not-found)
+- [A `*FormField` is missing from the submitted values, or never shows an error](#a-formfield-is-missing-from-the-submitted-values-or-never-shows-an-error)
+- [`meta.touched` stays false after leaving a field](#metatouched-stays-false-after-leaving-a-field)
+- [A multi-step form reopens at a later step](#a-multi-step-form-reopens-at-a-later-step)
+
+**Printing**
+
+- [The table header and the total row print blank](#the-table-header-and-the-total-row-print-blank)
+- [A `tw()` class has no effect](#a-tw-class-has-no-effect)
+- [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)
+- [The `PrintHeader` "LOGO" box disappeared after upgrading](#the-printheader-logo-box-disappeared-after-upgrading)
+
+**PDF documents**
+
+- [`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)
+- [`renderToStream is a Node specific API` / `renderToBuffer is a Node specific API`](#rendertostream-is-a-node-specific-api--rendertobuffer-is-a-node-specific-api)
+- [PDF rendering fails on an edge runtime](#pdf-rendering-fails-on-an-edge-runtime)
+- [`[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)
+
+**Maps**
+
+- [The map has no controls, or its tiles are scattered](#the-map-has-no-controls-or-its-tiles-are-scattered)
+- [A map is an empty box on the server-rendered page](#a-map-is-an-empty-box-on-the-server-rendered-page)
+- [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)
+- [A `LocationField` stays `null` after OK](#a-locationfield-stays-null-after-ok)
+- [`Map container not found.`](#map-container-not-found)
+
+**i18n**
+
+- [`useI18nContext must be used within an I18nProvider`](#usei18ncontext-must-be-used-within-an-i18nprovider)
+- [`[@nxgt/material-vue] i18n resource override for language`](#nxgtmaterial-vue-i18n-resource-override-for-language)
+- [`[@nxgt/material-vue] Unsupported language`](#nxgtmaterial-vue-unsupported-language)
+- [Text stays in the old language after `changeLanguage`](#text-stays-in-the-old-language-after-changelanguage)
+- [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 restore state for key`](#failed-to-restore-state-for-key)
+- [An `IconButton` has no accessible name](#an-iconbutton-has-no-accessible-name)
+- [An `Icon` is named "Icon {name}" although you passed `aria-label`](#an-icon-is-named-icon-name-although-you-passed-aria-label)
+- [An end-to-end test no longer finds the `Close` or `Zoom in` button](#an-end-to-end-test-no-longer-finds-the-close-or-zoom-in-button)
+- [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 a chip's remove button by the exact name `Remove`, or a `LocationPreview` by its place name](#a-test-no-longer-finds-a-chips-remove-button-by-the-exact-name-remove-or-a-locationpreview-by-its-place-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)
+- [An `id`, `aria-describedby` or `data-testid` on a `DateField`, `DateRangeField` or `TimeField` is nowhere in the page](#an-id-aria-describedby-or-data-testid-on-a-datefield-daterangefield-or-timefield-is-nowhere-in-the-page)
+- [A test no longer finds the label or helper text inside a date or time picker's trigger](#a-test-no-longer-finds-the-label-or-helper-text-inside-a-date-or-time-pickers-trigger)
+- [A test no longer finds a `DurationField` input by the field's label, or a `Slider`'s `aria-label` on its root](#a-test-no-longer-finds-a-durationfield-input-by-the-fields-label-or-a-sliders-aria-label-on-its-root)
+- [An `AlertDialog` focuses its Cancel although `@open-auto-focus` prevented it](#an-alertdialog-focuses-its-cancel-although-open-auto-focus-prevented-it)
+- [A `CustomDialog` or `ConfirmationDialog` no longer opens from its `#trigger`](#a-customdialog-or-confirmationdialog-no-longer-opens-from-its-trigger)
+- [A form with a required `Switch` no longer submits](#a-form-with-a-required-switch-no-longer-submits)
+- [A `RichTextEditor` became editable after upgrading](#a-richtexteditor-became-editable-after-upgrading)
+- [Focus falls to `<body>` when a controlled `Drawer` closes](#focus-falls-to-body-when-a-controlled-drawer-closes)
+
+**PDF reader**
+
+- [A `PdfReader` event listener runs twice](#a-pdfreader-event-listener-runs-twice)
+- [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 wrong PDF password gives no feedback](#a-wrong-pdf-password-gives-no-feedback)
+- [Escape does not close the dialog around a `PdfReader`](#escape-does-not-close-the-dialog-around-a-pdfreader)
+- [`@page-change` reports page 0 or a page past the end](#page-change-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)
+- [Links in a PDF do nothing in `PdfReader`](#links-in-a-pdf-do-nothing-in-pdfreader)
+- [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)
+- [`@page-change` is not called when `initialPage` is past the end, or after a new file](#page-change-is-not-called-when-initialpage-is-past-the-end-or-after-a-new-file)
+- [Reporting a bug](#reporting-a-bug)
+
+---
+
+## Install
+
+### `Cannot find package 'leaflet'`
+
+**When:** at build or at the first import of `@nxgt/material-vue/map` or
+`@nxgt/material-vue/map.css`. The missing name may also be
+`@vue-leaflet/vue-leaflet`, or the CSS step may fail on
+`leaflet/dist/leaflet.css`.
+**Why:** both 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 @vue-leaflet/vue-leaflet
+bun add -d @types/leaflet
+```
+
+### `Cannot read properties of null (reading 'ce')`
+
+**When:** on the first render of a component from this package that has a
+slot, often in an app whose own components work fine. Older Vue versions print
+`(reading 'isCE')`. Stores or injections that "reset" between the app and the
+package are the same problem.
+**Why:** the app and this package resolve **two copies** of `vue` (or of
+`pinia`, `vue-router`, `vee-validate`). They are peers because they must be one
+instance: a component compiled against one copy cannot render inside the other
+copy's renderer, and a `provide` from one copy is invisible to `inject` from the
+other. It also happens with two copies of `@nxgt/material-vue` itself.
+**Fix:**
+
+```sh
+bun pm ls --all | grep -E ' (vue|pinia|vue-router|vee-validate|@nxgt/material-vue)@'
+```
+
+```ts
+// vite.config.ts — a linked or workspace copy is the usual culprit
+export default defineConfig({
+  resolve: { dedupe: ['vue', 'pinia', 'vue-router', 'vee-validate'] },
+});
+```
+
+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.
+
+### `Missing "./print" specifier in "@nxgt/material-vue" package`
+
+**When:** at build (Vite), or as `Cannot find module '@nxgt/material-vue/print'`
+when type-checking, usually in code written for `@nxgt/material`.
+**Why:** some React subpaths have another name in Vue:
+
+| React | Vue |
+| --- | --- |
+| `@nxgt/material/print` | the document model and output functions (`pdfDocument`, `downloadPdf`, `pdfResponse`, …) are in `@nxgt/material-vue/pdf` ([PDF documents](guides/pdf.md)); the HTML `Print*` components, `tw` and `formatAmount` are in `@nxgt/material-vue/components` ([printing](guides/printing.md)) |
+| `@nxgt/material/hooks` | `@nxgt/material-vue/composables` |
+| `@nxgt/material/vite` | `@nxgt/material-vue/vite` (from 0.22.0) |
+
+**Fix:**
+
+```ts
+import { downloadPdf, pdfDocument } from '@nxgt/material-vue/pdf';
+import { formatAmount, PrintHeader, tw } from '@nxgt/material-vue/components';
+import { useTheme } from '@nxgt/material-vue/composables';
+```
+
+### `` [@nxgt/material-vue/pdf] Rendering a PDF needs the optional peers `react` and `@react-pdf/renderer`: bun add react @react-pdf/renderer@^4.9 ``
+
+**When:** the first time a document is rendered (`renderPdfBuffer`,
+`pdfResponse`, `usePdf`, `PdfDownloadButton`, …), in the browser or on a
+server. Importing `@nxgt/material-vue/pdf` and building documents work without
+them. The error is a `PdfPeerMissingError`; its `cause` is the failed import.
+**Why:** `react` and `@react-pdf/renderer` are optional peers, loaded only when
+a document is rendered, so an app that never renders one does not install
+them.
+**Fix:** install them in the app that renders (the server's too, when a route
+calls `pdfResponse`):
+
+```sh
+bun add react @react-pdf/renderer@^4.9
+```
+
+```ts
+import { PdfPeerMissingError, renderPdfBuffer } from '@nxgt/material-vue/pdf';
+
+try {
+  await renderPdfBuffer(doc);
+} catch (error) {
+  if (error instanceof PdfPeerMissingError) console.error(error.message, error.cause);
+  else throw error;
+}
+```
+
+### `Cannot find package 'lucide-vue-next'`
+
+**When:** at build or at dev-server start after upgrading to 0.22.0, in an app
+that imports icons from `lucide-vue-next` without listing it in its own
+`package.json`. Vite prints `Failed to resolve import "lucide-vue-next"`.
+**Why:** `lucide-vue-next` is deprecated upstream, and this package no longer
+depends on it: every icon comes from `@lucide/vue`, which it already depended
+on. An app that got `lucide-vue-next` through this package no longer has it.
+**Fix:** import from `@lucide/vue`, or add `lucide-vue-next` to your own
+dependencies:
+
+```sh
+bun add @lucide/vue
+```
+
+```diff
+-import { Trash2 } from 'lucide-vue-next';
++import { Trash2 } from '@lucide/vue';
+```
+
+Lucide 1.x redrew some glyphs; check the icons you use.
+
+## 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:** `styles.css` is not in the **same file** as `@import "tailwindcss"`.
+Tailwind v4 builds one theme per CSS graph: imported from a second stylesheet
+(for example a second entry in Nuxt's `css` array), the package's `@theme` and
+utilities go to a pipeline your app never reads. Nothing warns about it.
+**Fix:**
+
+```css
+/* the app's root stylesheet */
+@import "tailwindcss";
+@import "@nxgt/material-vue/styles.css";
+```
+
+You do **not** need an `@source` for this package: `styles.css` already
+declares `@source "../dist"`, so your build scans the compiled components.
+Import either this source stylesheet (with Tailwind) or the compiled CSS
+(`@import "@nxgt/material-vue"`, without Tailwind), never both: the tokens are
+then defined twice and your overrides may lose. See
+[Getting started](getting-started.md#styles).
+
+In 0.21.0 and earlier, `Markdown` maths, `RichTextEditor` code blocks,
+toasts, `ImageCropper`, `Spinner`, and `ButtonGroup`, `ContactItem`,
+`OpeningHoursItem`, `AttributeForm` and `AttributeValuesForm` stayed unstyled
+or unlaid-out in a Tailwind app even with this setup: their CSS reached only
+the compiled stylesheet. From 0.22.0, `styles.css` imports it. On an older
+version, add after it what you use of:
+
+```css
+@import "katex/dist/katex.min.css";
+@import "highlight.js/styles/github-dark.css";
+@import "vue-sonner/style.css";
+@import "vue-advanced-cropper/dist/style.css";
+```
+
+The other components' CSS has no file you can import before then: upgrade
+to 0.22.0.
+
+`ImageCropper` also lacked vue-advanced-cropper's stylesheet in the compiled
+stylesheet up to 0.21.0: an app without Tailwind adds
+`@import "vue-advanced-cropper/dist/style.css";` on an older version too.
+
+### `<Icon>` renders nothing
+
+**When:** every `Icon` (and anything that uses one: the app shell menu, the
+mobile menu button, `LanguageSwitcher`, `LoadMoreButton`, the `toasts`
+helpers) 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. Under
+Nuxt, `public/` is at the project root.
+
+### `JsBarcode is not a function`
+
+**When:** rendering `Barecode` (or calling `renderBarcode`) in a Vite app
+without the Nuxt module. The browser may instead report that `jsbarcode` does
+not provide an export named `default`.
+**Why:** `jsbarcode` is CommonJS. Vite does not pre-bundle the dependencies of
+a package it treats as source, so the browser receives the raw CommonJS file.
+The Nuxt module adds the fix for you.
+**Fix:**
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  optimizeDeps: { include: ['@nxgt/material-vue > jsbarcode'] },
+});
+```
+
+### A `LinkButton` selected as a `button` stops matching
+
+**When:** your CSS, or a test (`getByRole('button')`), targets the `<button>`
+inside a `LinkButton`, `IconLinkButton` or `ResponsiveLinkButton`, and stops
+matching after an update.
+**Why:** they rendered a `<button>` inside an `<a>`, two nested interactive
+elements. They now render one `<a>` styled as the button.
+**Fix:** select the link:
+
+```ts
+screen.getByRole('link', { name: 'Documentation' });
+```
+
+### A `Toc`, `Pager`, `SeeAlso` or `ScrollProgress` inside `Doc` selected by `data-slot` stops matching
+
+**When:** after an update to 0.22.0, CSS or a test that targets
+`[data-slot="toc"]`, `"pager"`, `"see-also"` or `"scroll-progress"` inside a
+`Doc` page no longer matches.
+**Why:** `DocToc`, `DocPager`, `DocSeeAlso` and `DocProgress` always passed
+their own `data-slot` (`doc-toc`, `doc-pager`, `doc-see-also`, `doc-progress`),
+but the inner components ignored a passed `data-slot`, so the plain names
+rendered. They now honour it.
+**Fix:** select the `doc-*` value inside `Doc`, or accept both:
+
+```ts
+page.locator('[data-slot="doc-toc"], [data-slot="toc"]');
+```
+
+### A `ResponsiveButton` selected by `[aria-expanded]` stops matching
+
+**When:** your CSS, or a test, targets `[aria-expanded="true"]` /
+`[aria-expanded="false"]` on a `ResponsiveButton`, `ResponsiveLinkButton` or
+`LoadMoreButton`, and stops matching after an update.
+**Why:** the attribute said whether the label was showing. `aria-expanded`
+tells a screen reader the button opens something, so each was announced as
+"collapsed" or "expanded" while controlling nothing; it is gone. Used as a
+popover, drawer or menu trigger (the `Filter` trigger, the data table's view
+options), the button still carries the trigger's own `aria-expanded`.
+**Fix:** find the button by its name, which it keeps collapsed or not, and
+check whether the label is showing instead:
+
+```ts
+const button = screen.getByRole('button', { name: 'New order' });
+expect(within(button).getByText('New order')).toHaveClass('sr-only'); // collapsed
+```
+
+### A menu item selected by `[data-variant=destructive]` stops matching
+
+**When:** your CSS, or a test, targets `[data-variant=destructive]` on a
+`DropdownMenuItem`, `ContextMenuItem` or `MenubarItem`, and stops matching
+after an update. In 0.21.0 and earlier, a `ContextMenuItem` or `MenubarItem`
+with `variant="destructive"` was also not red.
+**Why:** menu items take `variant="error"`, React's name, and keep
+`"destructive"` as a deprecated alias. Both render `data-variant="error"`, and
+their colours now come from the `error` theme token (the old context-menu and
+menubar colour had no token, so Tailwind generated nothing).
+**Fix:** select `[data-variant=error]`, and write `variant="error"`:
+
+```vue
+<DropdownMenuItem variant="error" @select="remove">Delete</DropdownMenuItem>
+```
+
+```css
+[data-slot='dropdown-menu-item'][data-variant='error'] { font-weight: 600; }
+```
+
+### 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 0.22.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
+`SliderField`, or `getByRole('listbox', { name: 'Selected' })` for a labelled
+`TransferList` (in Testing Library, or in Playwright with `exact: true`:
+Playwright matches a string name as a substring by default, so it still finds
+them).
+**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, 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');
+```
+
+### A test no longer finds `aria-invalid` on an upload field's group or drop zone
+
+**When:** after upgrading to 0.22.0, `[aria-invalid]` or
+`toHaveAttribute('aria-invalid')`
+finds nothing on the `UploadField` box, the `ImageField` frame, or the
+`FileListField` / `NetworkUploadField` / `S3UploadField` drop zone.
+**Why:** ARIA 1.2 does not allow `aria-invalid` on a `group` or a `button`.
+The `helper-text` given with `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 `helper-text` is
+described by a visually hidden "This value is not valid."
+(`material.zod.default`).
+**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.'); // the helper-text
+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 `Switch` row or an `Autocomplete` box
+
+**When:** after upgrading to 0.22.0, `[aria-invalid]` on the bordered row of a
+`Switch` with a `label`, or on the box around an `Autocomplete`'s chips and
+input, 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 (a bare `Switch` in error set it nowhere
+before), and the `Autocomplete`'s input. The row and the 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.getByLabel('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 button` stops matching.
+**Why:** the home crumb was a `<button>` inside the link: two nested controls,
+which a screen reader announces as both. The home icon is now the link itself,
+named "Home" (`material.app-shell.home`, translated). Pressing it still goes to
+`/`.
+**Fix:** find it as a link:
+
+```ts
+await page.getByRole('navigation', { name: 'breadcrumb' })
+  .getByRole('link', { name: 'Home' })
+  .click();
+```
+
+### A `QRCode`'s `aria-label` is no longer on its wrapper
+
+**When:** after upgrading, `div[aria-label="…"]` (or a
+`toHaveAttribute('aria-label')` on the `data-slot="qrcode"` wrapper) finds
+nothing for a `<QRCode aria-label="…">`.
+**Why:** the attribute fell through to the wrapper `div`, where it named
+nothing, while the `<svg role="img">` kept "QR code" (or `title`). It is now a
+declared prop that names the svg, and wins over `title`, as in
+`@nxgt/material`.
+**Fix:** find the code by role and name:
+
+```ts
+await expect(page.getByRole('img', { name: 'Scan to pay' })).toBeVisible();
+```
+
+### A `CheckboxGroup` or `RadioGroupField` option selected by `#<id>-<value>` stops matching
+
+**When:** after upgrading to 0.22.0, `#contact-email` (or
+`label[for="plan-pro"]`) finds nothing in a `CheckboxGroup`, `RadioGroupField`
+or their `*FormField`.
+**Why:** an option's id was the group's id joined to its `value`, so a value
+with a space (`'by email'`) gave an invalid id and a label pointing nowhere.
+It is now the option's index, `` `${id}-${index}` ``, as in `@nxgt/material`.
+**Fix:** select by role and name, which does not depend on ids:
+
+```ts
+await page.getByRole('group', { name: 'Contact channels' })
+  .getByRole('checkbox', { name: 'Email' })
+  .check();
+await page.getByRole('radiogroup', { name: 'Plan' })
+  .getByRole('radio', { name: 'Pro' })
+  .check();
+```
+
+Or use the index: `#contact-0` is the first option.
+
+The same release moves the attributes you put on a `RadioGroupField` (other
+than `class` and `style`), such as `data-testid`, from its layout `div` to the
+`radiogroup` itself, and drops an `aria-invalid` you put on a `CheckboxGroup`,
+which a `group` may not carry: assert its description instead,
+`await expect(group).toHaveAccessibleDescription('Pick at least one.')`. A
+`CheckboxGroupFormField` touched and invalid with no message yet, showing your
+`helper-text`, is described by "<helper-text> This value is not valid.": the
+hidden hint sits inside the helper element, so match its text with
+`getByText('Pick any.', { exact: false })` or the description with a RegExp.
+
+### An end-to-end test no longer finds a required field by a name ending in `*`
+
+**When:** after upgrading to 0.22.0, `getByRole('textbox', { name: 'Email*' })`
+(or any role query whose name ends in `*`) finds nothing for a field whose
+`Label` has `with-asterisk` (a `required` field). Queries on the label's text,
+`getByLabelText` and Playwright's `getByLabel`, still see the `*`: match it
+loosely in `getByLabelText` (`getByLabelText(/^Email/)`); Playwright's
+`getByLabel('Email')` already matches a substring.
+**Why:** screen readers used to read the asterisk ("Email star" or "Email*"),
+so it is now `aria-hidden`. The field's own `required` / `aria-required` says it is required,
+and every field of this library now sets it on the element a screen reader
+lands on (the input, the picker's combobox, the slider thumbs, the rating's
+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');
+```
+
+## SSR & build
+
+### `ReferenceError: window is not defined`
+
+**When:** in the server log of an SSR app, at boot or on the first request.
+The page is blank.
+**Why:** a module your server evaluates imports a browser-only dependency at
+module scope. The usual one is `leaflet`, which reads `window` while it is
+being *evaluated*: a value import (`import L from 'leaflet'`,
+`import { latLng } from 'leaflet'`) in your own code throws before anything
+renders. `@nxgt/material-vue/map` itself does not do this: it can be imported on
+a server (the package's build checks every entry without a DOM).
+**Fix:** import Leaflet's types only, and keep browser-only code behind
+`import()`:
+
+```ts
+import type { LatLng } from 'leaflet'; // erased by the compiler: safe
+```
+
+```ts
+// location-picker.ts
+import { defineAsyncComponent } from 'vue';
+import { clientOnly } from '@nxgt/material-vue/lib';
+
+export const LocationPicker = clientOnly(
+  defineAsyncComponent(() => import('./location-picker.vue')),
+);
+```
+
+The dynamic `import()` keeps the dependency out of the server's module graph,
+and `clientOnly` renders nothing until the component has mounted in the
+browser. A `typeof window` guard is not enough, because the *import* is what
+throws. Under Nuxt, a `.client.vue` component or `<ClientOnly>` does the render
+half. See [SSR](guides/ssr.md).
+
+### `ReferenceError: DOMMatrix is not defined`
+
+**When:** at server boot in an SSR app, after adding `pdfjs-dist` (or a
+wrapper around it) 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:**
+
+```ts
+import { defineAsyncComponent } from 'vue';
+import { clientOnly } from '@nxgt/material-vue/lib';
+
+// my-pdf-view.vue is the only module that imports pdfjs-dist
+export const MyPdfView = clientOnly(defineAsyncComponent(() => import('./my-pdf-view.vue')));
+```
+
+Or render `PdfReader` from `@nxgt/material-vue/components`, which already does
+this.
+
+### `ReferenceError: localStorage is not defined`
+
+**When:** on a server, with `@nxgt/material-vue` 0.21.0 or earlier, when a Zod
+schema fails validation after `z.config({ customError: zodLocaleError() })` ran
+in that process (a Nuxt server route or a shared module that validates on both
+sides). A browser that blocks storage threw a `SecurityError` the same way.
+**Why:** those versions read `localStorage` on every issue, without a guard, to
+pick the language. Since 0.22.0, `zodLocaleError` reads it
+safely and writes English where there is no `localStorage` or it cannot be
+read.
+**Fix:** update `@nxgt/material-vue`. On a server, where you know the
+request's language, pass it so messages are not always English:
+
+```ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material-vue/lib';
+
+z.config({ customError: zodLocaleError({ language: () => requestLanguage() }) });
+```
+
+`requestLanguage` is yours: read the cookie or `Accept-Language` of the
+current request, as in [i18n](guides/i18n.md#server-rendering).
+
+### `Hydration completed but contains mismatches.`
+
+**When:** in the browser console of an SSR app, after warnings such as
+`Hydration text content mismatch on …`. Vue patches the page in place, so it
+usually looks right, but the mismatched parts render twice.
+**Why:** the server and the first client render disagree. The common causes
+with this package:
+
+- **The language.** Without `initial-language`, `I18nProvider` reads
+  `localStorage` on the client, which the server cannot see: the server renders
+  `default-language`, the client its stored one. The warning shows the same
+  string in two languages.
+- **`TimeField` in 0.21.0 or earlier**: the server rendered its phone
+  (dialog) trigger and a desktop the popover one. Upgrade.
+- **On a phone or a dark screen, 0.21.0 or earlier**: `ResponsiveButton`,
+  `AppHeader`, `AppBreadcrumb`, `DataTable`, `Stepper` (and your own
+  `useIsMobile()`), or the code blocks and `ThemeToggle` (`useTheme()`), asked
+  `useMediaQuery` with no server answer: the server said "desktop, light" and
+  the first client render said otherwise. Upgrade: both now answer for
+  `provideSSRWidth()`'s width, or a 1024 px desktop, and a light scheme, and
+  the client switches right after.
+- **A stored theme, 0.21.0 or earlier**: `useTheme()` read the stored
+  preference in the first client render, so a stored `dark` changed
+  `ThemeToggle` (and your own markup that reads `useTheme()`) before
+  hydration. Upgrade: the first client render now reads `system`, like the
+  server, and the stored choice follows once mounted.
+- **`provideSSRWidth()` on the server only**: `useIsMobile()`,
+  `PaneLayout`, `ListDetailsLayout` and the other width-dependent components
+  answer for `provideSSRWidth()`'s width on the server *and* in the first
+  client render. Provide the same width on the client (serialise it into the
+  page payload, or `useState` in Nuxt), or the client answers for 1024 px and
+  differs from a phone width the server used. See
+  [the same width on both sides](guides/ssr.md#the-same-width-on-the-server-and-the-client).
+- **Browser-only state rendered straight away**: the date or time zone, or
+  a `localStorage` value of your own. The server cannot know them.
+- **An `<svg>` labelled with a `<title>` child** in your own markup. Some SSR
+  setups move `<title>` into the document head. This package's `Icon`,
+  `Spinner` and `CircularProgress` do not use one.
+
+**Fix:**
+
+```vue
+<!-- resolve the language on the server (cookie, Accept-Language) and pass it -->
+<I18nProvider :initial-language="languageFromRequest" :on-language-change="saveLanguageCookie">
+  <RouterView />
+</I18nProvider>
+```
+
+```vue
+<!-- browser-only state (a local date): render it after mount -->
+<script setup lang="ts">
+import { useIsClient } from '@nxgt/material-vue/composables';
+
+const isClient = useIsClient();
+</script>
+
+<template>
+  <p v-if="isClient">Now: {{ new Date().toLocaleTimeString() }}</p>
+</template>
+```
+
+For your SVGs, use `role="img"` and `aria-label` instead of `<title>`. The
+full list is in [SSR](guides/ssr.md#hydration) and
+[i18n](guides/i18n.md#server-rendering).
+
+### `Failed to resolve component: LocationFormField`
+
+**When:** a Vue warning in a Nuxt app, for a component you used in a template
+without importing it. It renders nothing. The name may be any map component
+(`Map`, `Marker`, `LocationField`, …) or `I18nProvider`.
+**Why:** the Nuxt module auto-registers what `@nxgt/material-vue/components`
+exports, and nothing else. The map components are left out on purpose, so an
+app that renders no map never resolves the optional peers; `I18nProvider`
+lives in `/i18n`. With the module's `prefix` option set, the auto-registered
+names carry it too (`<NxgtButton />`).
+**Fix:**
+
+```vue
+<script setup lang="ts">
+import { LocationFormField } from '@nxgt/material-vue/map';
+import { I18nProvider } from '@nxgt/material-vue/i18n';
+</script>
+```
+
+## Pinia, router & forms
+
+### `"getActivePinia()" was called but there was no active Pinia`
+
+**When:** on the first render of a widget that keeps state (filter, gallery,
+kanban, event calendar, player, upload fields, chat, PDF reader, …), or when you
+call a store factory from `@nxgt/material-vue/lib`. The full message ends with
+`Are you trying to use a store before calling "app.use(pinia)"?`.
+**Why:** every stateful widget keeps its UI state in a Pinia store created per
+instance. Pinia is a required peer and must be installed before mount, on the
+server entry too in an SSR app.
+**Fix:**
+
+```ts
+// main.ts
+import { createPinia } from 'pinia';
+import { createApp } from 'vue';
+import App from './App.vue';
+
+createApp(App).use(createPinia()).mount('#app');
+```
+
+The Nuxt module installs Pinia when the app has none. In a unit test, call
+`setActivePinia(createPinia())` (both re-exported from
+`@nxgt/material-vue/lib`) before mounting.
+
+### `injection "Symbol(route location)" not found`
+
+**When:** a Vue warning, followed by a `TypeError` such as `Cannot read
+properties of undefined (reading 'path')`, when rendering `ActivityLayout`,
+`AppSidebar`, `AppBreadcrumb`, a `LinkButton`, or calling `useSearchParam` /
+`useNavigationHandler`. For the link buttons the warning names
+`Symbol(router)`.
+**Why:** those read the current route or navigate through `vue-router`, a
+required peer. Without an installed router there is nothing to inject. Two
+copies of `vue-router` give the same message.
+**Fix:**
+
+```ts
+// main.ts
+import { createPinia } from 'pinia';
+import { createApp } from 'vue';
+import App from './App.vue';
+import { router } from './router'; // createRouter({ history: createWebHistory(), routes })
+
+createApp(App).use(createPinia()).use(router).mount('#app');
+// in tests and stories: createRouter({ history: createMemoryHistory(), routes })
+```
+
+See [app shell](guides/app-shell.md#it-needs-a-router).
+
+### A `*FormField` is missing from the submitted values, or never shows an error
+
+**When:** a `TextFormField` (or any `*FormField`) renders and accepts input,
+but `handleSubmit` receives the values without it, and the schema's error
+never appears under it. There is no warning.
+**Why:** a `*FormField` registers with the nearest vee-validate form **above
+it** in the component tree, through `useField(name)`. With no form above, it
+becomes a standalone field: it keeps its own value and has no schema. The usual
+cause is calling `useForm()` in a child or sibling component, or in a
+composable called from one, instead of in the component that renders the
+fields (or one of its ancestors).
+**Fix:**
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { Button, TextFormField } from '@nxgt/material-vue/components';
+
+// useForm in THIS component: every field below it registers with this form
+const { handleSubmit } = useForm({ initialValues: { name: '' } });
+const onSubmit = handleSubmit((values) => console.log(values));
+</script>
+
+<template>
+  <form @submit="onSubmit">
+    <TextFormField name="name" label="Name" />
+    <Button type="submit">Save</Button>
+  </form>
+</template>
+```
+
+Also check that `name` is the exact key of your values (`address.city` for a
+nested one). Schemas and messages: [forms](guides/forms.md#the-pair).
+
+### `meta.touched` stays false after leaving a field
+
+**When:** a `*FormField` keeps `meta.touched` (`useIsFieldTouched(name)`,
+`useForm().meta`) at `false` after the user tabs or clicks out of it, so an
+"errors once touched" pattern never shows anything, and an empty required
+field shows no message until submit. In 0.21.0 and earlier, no wrapper but
+`RichTextEditorFormField` and `FilterFormField` called vee-validate's
+`handleBlur`, so this was every field.
+**Why:** a wrapper marks its field touched 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 a recent release, `meta.touched` still false after that means one
+of:
+
+- your own field calls `useField` without wiring `handleBlur`;
+- focus went from the field straight into an overlay that appeared while
+  the field had focus, such as a new toast's button: a layer mounted on
+  `<body>` since focus entered the field, that no other control names
+  (`aria-controls`), 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 teleports 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.
+
+**Fix:** upgrade to 0.22.0. For a field of your own, call
+`handleBlur` from its control's `blur` event — the `true` validates too, as
+the wrappers do:
+
+```vue
+<script setup lang="ts">
+import { useField } from 'vee-validate';
+
+const { value, handleBlur } = useField<string>('nickname');
+</script>
+
+<template>
+  <input v-model="value" @blur="handleBlur($event, true)">
+</template>
+```
+
+What counts as leaving, per kind of field:
+[forms](guides/forms.md#touched-on-blur).
+
+### A multi-step form reopens at a later step
+
+**When:** a wizard built on `defineStepFormStore` opens at the step (and with
+the values) a user left it at, after a reload or on a later visit. From 0.22.0.
+**Why:** `updateStep` stores the state in `localStorage` under the store
+`name`, and from that release a new store 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`:
+
+```ts
+function finish(part: Pick<Signup, 'company'>) {
+  emit('done', { ...values.value, ...part } as Signup);
+  wizard.reset(); // clears localStorage['signup-wizard']
+}
+```
+
+In an SSR app the server renders step 0. A client hydrating that page renders
+step 0 too and resumes at the stored step once mounted, so hydration matches
+without `clientOnly`: see [forms](guides/forms.md#a-multi-step-form).
+
+## Printing
+
+### The table header and the total row print blank
+
+**When:** on paper or in a PDF, the table header and the grand-total row are
+empty bands, although they look right on screen.
+**Why:** their text is white on a dark background, and browsers drop
+background colours when printing unless told otherwise.
+**Fix:**
+
+```css
+@media print {
+  .invoice { print-color-adjust: exact; -webkit-print-color-adjust: exact; }
+}
+```
+
+With a headless browser, pass `printBackground: true` to `page.pdf()`. See
+[printing](guides/printing.md#rendering-the-document).
+
+### A `tw()` class has no effect
+
+**When:** a class in `tw('…')`, or in the `class` prop of `PrintSection`,
+`PrintCard` or `PrintBadge`, changes nothing.
+**Why:** `tw` is not Tailwind. It knows a short list of classes (the print
+colours, a few layout, font and border classes, and a small spacing scale) and
+drops anything else without a warning. The `class` prop of those three blocks
+is a `tw` string, not a CSS class.
+**Fix:** use a class from the list in
+[printing](guides/printing.md#the-building-blocks), an arbitrary value
+(`text-[11pt]`, `w-[180pt]`), or a plain `style`:
+
+```vue
+<PrintSection title="Notes" class="mb-[12pt]">
+  <p :style="{ fontStyle: 'italic' }">Payment received by bank transfer.</p>
+</PrintSection>
+```
+
+### An amount in yen shows no decimals, or one in dinars shows three
+
+**When:** from 0.22.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'
+```
+
+```vue
+<CurrencyField v-model="price" label="Price" currency="JPY" :fraction-digits="2" />
+```
+
+### A date shows the day before
+
+**When:** up to 0.21.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 0.22.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'
+```
+
+### The `PrintHeader` "LOGO" box disappeared after upgrading
+
+**When:** from 0.22.0, a `PrintHeader` with no `logo-text`
+prints no grey "LOGO" box on the left, and one with no `qr-data-url` no empty
+box on the right. A screenshot or a test that expected them fails.
+**Why:** the placeholder was the default. The header now draws a logo only when
+you pass `logo` (an image) or `logo-text`, and a QR box only around a QR image;
+the title stays centred either way.
+**Fix:** pass your logo, or the text to keep the old box:
+
+```vue
+<PrintHeader title="Invoice" reference="INV-2044" logo="/brand/logo.png" />
+<PrintHeader title="Invoice" reference="INV-2044" logo-text="LOGO" />
+```
+
+See [printing](guides/printing.md#printheader).
+
+## PDF documents
+
+### `Cannot find module '#standard-fonts/Helvetica'`
+
+**When:** on **every request** of a server that renders with
+`@nxgt/material-vue/pdf`, health checks included, once it is built into a
+single artifact that runs without `node_modules`.
+**Why:** pdfkit, under `@react-pdf/renderer`, loads its standard fonts with a
+runtime `require('#standard-fonts/<name>')`, a specifier private to pdfkit
+that no bundler resolves. Inlined into your server, the call looks for it next
+to your build output. Nitro keeps the renderer external by default, where
+pdfkit finds its fonts; this appears when it is inlined.
+**Fix:** bundle the fonts in. In Nuxt:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@nxgt/material-vue/nuxt'],
+  nxgtMaterial: { pdf: { bundleStandardFonts: true } },
+});
+```
+
+In a Vite SSR server:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { pdfkitStandardFonts } from '@nxgt/material-vue/vite';
+
+export default defineConfig({
+  plugins: [pdfkitStandardFonts()],
+  ssr: { noExternal: ['@nxgt/material-vue'] },
+});
+```
+
+When the runtime image keeps `node_modules`, leaving the renderer external
+works too, and keeps pdfkit out of the artifact. A `resolve.alias` for
+`#standard-fonts/` does not help: the specifier is a string passed to
+`require` at runtime, never seen by the resolver. See
+[PDF documents](guides/pdf.md#fonts-on-a-fully-inlined-server).
+
+### `still references '#standard-fonts/' after the transform`
+
+**When:** at build, from the `nxgt-material:pdfkit-standard-fonts` plugin
+(added by `pdfkitStandardFonts()` or the Nuxt `pdf.bundleStandardFonts`
+option).
+**Why:** a pdfkit release changed how it loads its standard fonts, and the
+plugin could not rewrite every call. It fails the build on purpose, rather
+than ship a server that fails on its first request.
+**Fix:** pin `@react-pdf/renderer` (and so pdfkit) to the version that built,
+and upgrade `@nxgt/material-vue` when a release supports the new pdfkit. Please
+report it (see [Reporting a bug](#reporting-a-bug)) with the `pdfkit` version.
+
+### `renderToStream is a Node specific API` / `renderToBuffer is a Node specific API`
+
+**When:** calling `renderPdfStream` in a browser, or `renderPdfStream`,
+`renderPdfBuffer` or `pdfResponse` on a server whose bundle resolved
+react-pdf's browser build.
+**Why:** on a server those use react-pdf's `renderToStream` and
+`renderToBuffer`, which exist only in its Node build; its browser build throws
+this.
+**Fix:** in the browser, use `renderPdfBlob`, `downloadPdf` or `usePdf`. On a
+server, let the server load react-pdf's Node build: keep
+`@react-pdf/renderer` external (Nitro's default).
+
+```ts
+const blob = await renderPdfBlob(doc); // browser and server
+```
+
+### PDF rendering fails on an edge runtime
+
+**When:** a route deployed to Cloudflare Workers, Vercel Edge or Deno Deploy
+that calls `pdfResponse` or another render function fails.
+**Why:** the server functions are built and tested for Node 18+ and Bun only;
+edge runtimes are not a supported target.
+**Fix:** deploy that route with a Node or Bun preset, or render in the browser
+with `downloadPdf` or `usePdf`.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({ nitro: { preset: 'node-server' } });
+```
+
+See [PDF documents](guides/pdf.md#on-a-server-pdfresponse).
+
+### `[pdf] No renderer for the custom node`
+
+The full message is ``[pdf] No renderer for the custom node "signature": pass it in `custom` when rendering.``
+
+**When:** rendering a document with a `{ type: 'custom', name }` node.
+**Why:** no renderer of that `name` was passed in the `custom` option.
+**Fix:** pass one to the function that renders (it returns react-pdf
+elements):
+
+```ts
+await renderPdfBuffer(doc, {
+  custom: { signature: (props, context) => /* react-pdf elements, e.g. createElement(Text, …) */ null },
+});
+```
+
+### `[pdf] Unknown node type`
+
+**When:** rendering a document, for example `[pdf] Unknown node type "chart".`
+**Why:** a `type` this version does not know: a typo in hand-written JSON, or
+a document built by a newer version.
+**Fix:** use a builder (`heading`, `table`, …) rather than a literal, and
+render with the version that built the document.
+
+### `[pdf] Unsupported document version`
+
+**When:** rendering a document whose `version` is not `1`, as
+`[pdf] Unsupported document version 2: this version renders version 1.`
+**Why:** the renderer reads version 1 only.
+**Fix:** build documents with `pdfDocument` or `definePdfDocument`, which stamp
+`version: 1`, or upgrade the library that renders.
+
+## 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-vue/map.css` and is not part of `styles.css`, because it depends
+on the optional `leaflet` peer.
+**Fix:**
+
+```ts
+import '@nxgt/material-vue/map.css';
+```
+
+### A map is an empty box on the server-rendered page
+
+**When:** in an SSR app, the map's space is empty in the page source and until
+the page has loaded. There is no error.
+**Why:** expected. Leaflet initialises in the browser only, when the component
+mounts.
+**Fix:** wrap it so the server renders nothing (or a placeholder) instead of
+an empty box:
+
+```vue
+<ClientOnly>
+  <Map class="h-80" :center="[48.8566, 2.3522]" />
+  <template #fallback><Skeleton class="h-80" /></template>
+</ClientOnly>
+```
+
+Outside Nuxt, use `clientOnly` from `@nxgt/material-vue/lib`. See
+[maps](guides/maps.md#browser-only).
+
+### The browser asks for location permission when a map renders
+
+**When:** as soon as a `Map`, `LocationMarker` or `MapActions` mounts, whether
+or not the map has a `center`; for `LocationField` and `LocationPreview`, when
+their dialog or hover card opens.
+**Why:** they watch the visitor's position (through `useGeolocation`) on setup.
+`center` only decides where the map opens. 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:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button } from '@nxgt/material-vue/components';
+import { Map, Marker } from '@nxgt/material-vue/map';
+
+const shown = ref(false);
+</script>
+
+<template>
+  <Button v-if="!shown" @click="shown = true">Show the map</Button>
+  <Map v-else class="size-96" :center="[48.8566, 2.3522]">
+    <Marker :position="[48.8566, 2.3522]" reference />
+  </Map>
+</template>
+```
+
+For a map that must never prompt, compose `LMap` and `LTileLayer` from
+`@vue-leaflet/vue-leaflet` yourself.
+
+### The map shows two zoom controls
+
+**When:** after passing `zoom-control` to `Map`, or adding `MapActions`.
+**Why:** `Map` already renders its own zoom control at `topleft`.
+`zoom-control` adds Leaflet's built-in one, and `MapActions` has zoom buttons
+of its own.
+**Fix:**
+
+```vue
+<Map :center="center" /> <!-- leave zoom-control at its default, false -->
+```
+
+With `MapActions`, put it in another corner (`position="topright"`) or keep one
+of the two.
+
+### A `LocationField` stays `null` after OK
+
+**When:** with `@nxgt/material-vue` 0.21.0 or earlier, the field shows
+`5.44087 - 10.06843`, the user opens the dialog and presses OK without
+dragging, and the value is still `null` (a required `LocationFormField` still
+fails).
+**Why:** those versions displayed the fallback position for a `null` value,
+but only a drag of the pin wrote a value; OK only closed the dialog. Since
+0.22.0, a `null` value shows an empty input with a placeholder,
+and OK on an empty field commits the last position the pin was dragged to, or
+its start.
+**Fix:** update `@nxgt/material-vue`. To open the dialog somewhere else than
+the default start, give the form a real initial position:
+
+```ts
+const { handleSubmit } = useForm({ initialValues: { position: [48.8566, 2.3522] as [number, number] } });
+```
+
+### `Map container not found.`
+
+**When:** with 0.21.0 or earlier, a `LocationField` dialog (or any `Map` under a
+`v-if`) is closed right after it opened, before leaflet had loaded: the console
+shows an unhandled rejection, `Error: Map container not found.`, sometimes
+followed by `Cannot read properties of undefined (reading 'appendChild')`.
+Nothing is broken on the page.
+**Why:** `@vue-leaflet/vue-leaflet` imports leaflet in an async `onMounted`,
+then builds the map on its element. Unmounted in between, the element is gone
+and leaflet throws from the hook; the layers and controls inside do the same
+against the removed map.
+**Fix:** upgrade: `Map` ignores those errors, from vue-leaflet's own components
+only, once it is unmounting. A map you compose from `LMap` yourself needs the
+same guard around it:
+
+```vue
+<script setup lang="ts">
+import { LMap, LTileLayer } from '@vue-leaflet/vue-leaflet';
+import { onBeforeUnmount, onErrorCaptured } from 'vue';
+
+let unmounting = false;
+onBeforeUnmount(() => (unmounting = true));
+onErrorCaptured((_error, instance) => {
+  const type: unknown = instance?.$.type;
+  const name = (type as { name?: string } | undefined)?.name ?? '';
+  const fromLeaflet = type === LMap || type === LTileLayer || /^L[A-Z]/.test(name);
+  return unmounting && fromLeaflet ? false : undefined;
+});
+</script>
+```
+
+## i18n
+
+### `useI18nContext must be used within an I18nProvider`
+
+**When:** the first render of a component that calls `useI18nContext()`, or the
+`useTranslation()` that `createTypedTranslation` builds (for example your
+language switcher).
+**Why:** language state lives only in `I18nProvider`, and this composable
+throws when there is none above it. It also throws when the provider and the
+composable come from two copies of `@nxgt/material-vue` (see
+[two copies](#cannot-read-properties-of-null-reading-ce)). The Nuxt module
+does not register `I18nProvider`.
+**Fix:**
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { I18nProvider } from '@nxgt/material-vue/i18n';
+</script>
+
+<template>
+  <I18nProvider default-language="en">
+    <RouterView />
+  </I18nProvider>
+</template>
+```
+
+`provideI18n()` in the root component's `setup()` does the same without the
+component. For a component that must also work without a provider, use
+`useOptionalI18nContext()`, which returns `null` instead of throwing.
+
+### `[@nxgt/material-vue] 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-vue] 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 `supported-languages`, which
+defaults to the languages of the base bundle (`en`, `fr`). A full locale such
+as `navigator.language` is not a language code.
+**Fix:**
+
+```ts
+import { type Language, useI18nContext } from '@nxgt/material-vue/i18n';
+
+const { changeLanguage, supportedLanguages } = useI18nContext();
+const code = navigator.language.slice(0, 2);
+if (supportedLanguages.includes(code as Language)) changeLanguage(code as Language);
+```
+
+### Text stays in the old language after `changeLanguage`
+
+**When:** the package's components switch language, but some of your own
+strings stay in the previous one until the component is mounted again.
+**Why:** the code copies the language out of the reactive context:
+`const { language } = useI18nContext()` (or out of `useTranslation().i18n`)
+reads it once, at setup. Releases up to 0.21.0 did this inside the
+`useTranslation()` that `createTypedTranslation` builds; it now reads the
+language on every call.
+**Fix:** keep the object and read `language` from it when you translate:
+
+```ts
+const i18n = useI18nContext(); // not: const { language } = useI18nContext()
+const title = computed(() => translate('app.greeting', { name: 'Ada' }, i18n.language));
+```
+
+### 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}`, `+{count} more` or
+`{count} items` instead of `Step 01`, `3/5`, `+2 more` or `3 items` (kanban
+WIP limits, event calendar, gallery, quiz, JSON viewer, rating cards,
+screen-reader text of `CountBadge`).
+**Why:** in `@nxgt/material-vue` 0.21.0 and earlier, a component rendered with
+no `I18nProvider` returned its English fallback without filling in its values.
+Since 0.22.0 the fallback is formatted with its values,
+provider or not, on the client and on a server. 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-vue] Could not format the fallback` warning names it.
+**Fix:** update `@nxgt/material-vue`. 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
+`storage-key` 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-vue/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() }) });
+```
+
+See [helpers](guides/helpers.md#zodlocaleerror-limits).
+
+## Runtime
+
+### `must be used within` / `must be used inside`
+
+**When:** on render, from a part of a widget or a context composable 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` |
+| `useTransferListContext must be used within TransferList` | `TransferList` |
+| `StxPlayer components must be used inside <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` |
+| `Camera components must be used inside <Camera>` | `Camera` |
+| `Dnd components must be used within DndProvider` | `DndProvider` |
+
+**Why:** these widgets share state through `provide` / `inject`. Their parts,
+and the composables that read that state, only work below the root component.
+A teleport (a dialog, a popover) does not break this, but a second copy of
+`@nxgt/material-vue` does (see
+[two copies](#cannot-read-properties-of-null-reading-ce)).
+**Fix:**
+
+```vue
+<!-- active-count.vue: rendered inside <FilterProvider :schema="schema"> -->
+<script setup lang="ts">
+import { useFilterContext } from '@nxgt/material-vue/components';
+
+const filter = useFilterContext(); // fine: this component is below FilterProvider
+</script>
+
+<template>
+  <span>{{ filter.activeFilterCount }}</span>
+</template>
+```
+
+### `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-vue/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 `@vueuse/core`'s
+`useClipboard`, and in an insecure context it silently copies nothing.
+
+### `Upload failed with status 403`
+
+**When:** an `S3UploadField` upload fails. The error reaches the `on-error`
+callback, `(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:**
+
+```vue
+<FilterProvider :schema="schema" :preset-config="{ enabled: true, maxPresets: 50 }">
+  <!-- … -->
+</FilterProvider>
+```
+
+### `Failed to restore state for key`
+
+**When:** a `console.warn` naming a `localStorage` key, from `safeGetItem`
+(also `Failed to store state` / `Failed to remove state` from `safeSetItem`,
+`safeRemoveItem`). The default value is used and nothing throws.
+**Why:** the stored value is not valid JSON while the default is not a string
+(it was written by other code, or by hand), or storage is blocked or full.
+**Fix:** remove the bad value, or read it with a string default, which returns
+the raw string:
+
+```ts
+import { safeGetItem, safeRemoveItem } from '@nxgt/material-vue/lib';
+
+safeRemoveItem('filters');
+const raw = safeGetItem('filters', ''); // a string default skips JSON.parse
+```
+
+### An `IconButton` has no accessible name
+
+**When:** a screen reader announces an `IconButton` as just "button", or an
+accessibility check flags it, although you passed `aria-label`. Seen with
+`@nxgt/material-vue` 0.21.0 and earlier; a `tooltip` named it, which is why
+some code passes a `tooltip` only to get a name.
+**Why:** those versions dropped `aria-label` before the `<button>`: Vue hands
+the declared prop over as `ariaLabel`, and the component read
+`aria-label`. Since 0.22.0 it reaches the `<button>`; a
+`tooltip` names it only when there is no `aria-label`.
+**Fix:** update `@nxgt/material-vue` and pass `aria-label`. A `tooltip` added
+only to name the button can go:
+
+```vue
+<IconButton name="trash" color="error" aria-label="Delete" />
+```
+
+### An `Icon` is named "Icon {name}" although you passed `aria-label`
+
+**When:** `getByRole('img', { name: 'Delete' })` fails, or a screen reader
+announces "Icon trash", although the `Icon` has `aria-label="Delete"`. The same
+happens on `ScrollProgress` ("Scroll progress"), `FileList` ("Files") and
+`Tree` ("Tree"): your `aria-label` is replaced by the default. Seen with
+`@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** Vue hands a declared `aria-label` prop over as `ariaLabel`, and these
+components read `aria-label`, so they always fell back to their default.
+**Fix:** update `@nxgt/material-vue`; your `aria-label` then wins:
+
+```vue
+<Icon name="trash" aria-label="Delete" />
+```
+
+### An end-to-end test no longer finds the `Close` or `Zoom in` button
+
+**When:** after an update, under a French `I18nProvider`,
+`getByRole('button', { name: 'Close' })` or `{ name: 'Zoom in' }` times out on
+a dialog, sheet or `DialogFooter` close button, or on the map's zoom buttons.
+Seen from 0.22.0.
+**Why:** those labels were English in every language; they now follow
+`I18nProvider` (`material.buttons.close`, `material.map.zoom-in`,
+`material.map.zoom-out`, `material.map.my-position`), so in French they read
+"Fermer", "Zoom avant", "Zoom arrière" and "Ma position".
+**Fix:** select by the name in the language the test runs in, or by a pattern
+that accepts both:
+
+```ts
+await page.getByRole('button', { name: /^(Close|Fermer)$/ }).click();
+```
+
+### A test no longer finds a pagination, breadcrumb or other built-in label by its English name
+
+**When:** after an update (0.22.0 and later), under a French
+`I18nProvider`, a selector such as `getByRole('button', { name: 'Next Page' })`,
+`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`:
+
+| English | French | Key (`material.…`) |
+| --- | --- | --- |
+| `First`, `Previous`, `Next`, `Last` (pagination buttons), `Page 2` (a page button's name) | `Première`, `Précédent`, `Suivant`, `Dernière`, `Page 2` | `pagination.first`, `previous`, `next`, `last`, `page` |
+| `More pages`, `pagination` (the `nav`'s name) | `Plus de pages`, `Pagination` | `pagination.more`, `pagination.label` |
+| `breadcrumb` (the `nav`'s name), `More` | `Fil d'Ariane`, `Plus` | `breadcrumb.label`, `breadcrumb.more` |
+| `Breadcrumb` (`DocHeader`) | `Fil d'Ariane` | `doc.breadcrumb` |
+| `Command Palette`, `Search for a command to run...` (`CommandDialog`) | `Palette de commandes`, `Recherchez une commande à exécuter...` | `command.title`, `command.description` |
+| `carousel`, `slide` (`aria-roledescription`) | `carrousel`, `diapositive` | `carousel.roledescription`, `carousel.slide` |
+| `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` |
+| `Add option` (attribute options) | `Ajouter une option` | `attributes.buttons.add-option` |
+| `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` |
+
+Two names changed in English too. The pagination buttons were named by
+reka-ui, "First Page", "Previous Page", "Next Page" and "Last Page"; they are
+now named by their text, "First", "Previous", "Next" and "Last", as in
+`@nxgt/material`. 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 page.getByRole('button', { name: /^(Next|Suivant)$/ }).click();
+```
+
+```vue
+<PaginationNext aria-label="Next results" />
+```
+
+### A test no longer finds a chip's remove button by the exact name `Remove`, or a `LocationPreview` by its place name
+
+**When:** after an update (0.22.0 and later),
+`getByRole('button', { name: 'Remove' })` (Testing Library, or Playwright with
+`exact: true`) finds nothing next to a dismissible `Chip` that shows text
+(its `label`, or its default slot when given), such as an `Autocomplete`
+chip; `getByRole('button', { name: 'Paris' })` finds nothing on the default
+trigger of `<LocationPreview name="Paris">`; 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 `LocationPreview` trigger was named by
+the bare place name, or by an English "Preview location"; it is now
+"Preview Paris" / "Preview location" (`material.map.preview-named` /
+`material.map.preview`, "Aperçu : Paris" / "Aperçu de l'emplacement" in
+French). 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 `Sidebar` toggle had no name at all and is now "Toggle
+sidebar".
+**Fix:** find the button by its full name, in the language the test runs in:
+
+```ts
+await page.getByRole('button', { name: 'Remove Paris' }).click();
+await page.getByRole('button', { name: 'Preview Paris' }).hover();
+```
+
+### A test no longer finds an icon badge by role `button`, or an `Icon` named "Icon {name}" inside a button
+
+**When:** in 0.22.0 and later, one of these finds nothing:
+
+- `getByRole('button')` on the icon badge of a `FileListField` row, the
+  `NetworkUploadField` file preview, the `EntityHeader`, `ConfirmationDialog`
+  or `AppSidebar` icon, the `Stepper` info icon or the `AccordionCard`
+  chevron — or a count of buttons comes out lower;
+- `getByRole('img', { name: 'Icon trash' })` on an `Icon` inside a named
+  `IconButton`, `InputGroupButton` or `IconLinkButton`, on the badge of a
+  `Contacts`, `OpeningHours`, `PostalAddress` or `AttributesList` row, or on
+  an icon inside one of the badges above (`Icon atom` in the `AppSidebar`
+  brand, `Icon file` in a `FileListField` row or the `NetworkUploadField`
+  preview, an `Icon` in `EntityHeader`'s `#icon` slot).
+
+**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" (the
+`AccordionCard` chevron was even a button inside the trigger button). It is
+now a `<span>` with `aria-hidden="true"` and the same look; the list-row badges,
+already `<div>`s, are hidden too. 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. 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();
+// the button, not the icon inside it
+await page.getByRole('button', { name: 'Delete' }).click();
+```
+
+### `An invalid form control with name='…' is not focusable`
+
+**When:** submitting a form with an empty `required` `UploadField`, with
+0.21.0 or earlier: 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 vee-validate
+validates the form (`UploadFormField`) and you do not want the browser's check,
+put `novalidate` on the `<form>`.
+
+### An `id`, `aria-describedby` or `data-testid` on a `DateField`, `DateRangeField` or `TimeField` is nowhere in the page
+
+**When:** with 0.21.0 or earlier: `getByTestId` finds nothing, a hint is not read as
+the field's description, a listener never fires. No error is printed.
+**Why:** the field's root is a popover (or a dialog), which renders no element.
+**Fix:** upgrade: the attributes now go on the trigger, the `combobox`, so
+`getByTestId` and `aria-describedby` work. Since 0.22.0 the trigger
+is named by the field's label, and so is the open calendar: see the next entry.
+
+The `DateRangeField` trigger also carries `data-slot="date-range-field-trigger"`
+(it was `popover-trigger`) and the default `data-pw` (the `name`, or
+`date-range-field`), which was on the box inside it: a selector on the old
+`data-slot` matches nothing, and one on `data-pw` now finds the button.
+
+### A test no longer finds the label or helper text inside a date or time picker's trigger
+
+**When:** with 0.22.0 or later, `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
+`class` meant for the trigger button now sizes the whole field; or the
+trigger's `id` is no longer `reka-popover-trigger-…`. 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 `class`. 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 always has an id for it (yours, else a
+generated one), and it labels the open calendar. On a `TimeField`
+the default `data-pw` (the `name`, or `time-field`) is on the root `div`, 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:** with 0.22.0 or later, `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"`, `SliderField`'s
+`error` included).
+**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` goes on every thumb, so a vertical `Slider` (which has no field label) is named.
+**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');
+```
+
+### An `AlertDialog` focuses its Cancel although `@open-auto-focus` prevented it
+
+**When:** with 0.21.0 or earlier, an `AlertDialogContent` whose
+`@open-auto-focus` calls `event.preventDefault()` still moves focus to its
+`AlertDialogCancel` a moment after opening, where `DialogContent`,
+`SheetContent` and `DrawerContent` keep focus where it was.
+**Why:** reka focuses the Cancel a tick after the alert dialog opens without
+checking whether the event was prevented, and the dialog's focus trap then
+keeps focus inside.
+**Fix:** upgrade: `AlertDialogContent` now honours the prevented default, and
+the `AlertDialogCancel` of this package takes no focus until reka's call is
+past. It is found by its `data-slot="alert-dialog-cancel"`: reka's own
+`AlertDialogCancel`, or one given another `data-slot`, keeps the old
+behaviour. Opening still moves focus in when you do not prevent it: to the
+Cancel, to the first control when there is no Cancel, or to the content when
+there is no control. With the opt-out, the Cancel
+takes no focus until the next task: focus it from a `setTimeout` if you want it.
+
+```vue
+<AlertDialogContent @open-auto-focus="(event) => event.preventDefault()">
+```
+
+### A `CustomDialog` or `ConfirmationDialog` no longer opens from its `#trigger`
+
+**When:** after upgrading to 0.22.0, clicking what you put in the `#trigger`
+slot does nothing, or the page warns that a component could not forward
+attributes. The slot holds plain text, several elements, or a component that
+renders no element of its own.
+**Why:** the slot used to be wrapped in a `<button>` of its own, so a `Button`
+there was a button inside a button. The trigger is now merged into the one
+element you pass (`as-child`): that element receives the click handler and
+the `aria-*` attributes. Plain text has no element to receive them.
+**Fix:** put one focusable element in the slot, such as a `Button`:
+
+```vue
+<ConfirmationDialog title="Archive order" @confirm="archive">
+  <template #trigger>
+    <Button variant="outlined">Archive</Button>
+  </template>
+</ConfirmationDialog>
+```
+
+### A form with a required `Switch` no longer submits
+
+**When:** after upgrading to 0.22.0, pressing submit in a `<form>` does nothing
+while a `Switch`, `SwitchField` or `SwitchFormField` with `required` and a
+`name` is off; the browser may show "Please tick this box if you want to
+proceed".
+**Why:** `required` used to draw only the label's asterisk. It now reaches the
+switch, which is announced as required (`aria-required`), and its hidden input
+is `required`, so the browser's native validation blocks the submit, as for a
+required checkbox.
+**Fix:** leave `required` on a switch that must be on (an agreement); drop it
+from one that may stay off. A form that validates itself (vee-validate) can
+turn native validation off with `novalidate`:
+
+```vue
+<form novalidate @submit="onSubmit">
+  <SwitchFormField name="terms" label="I accept the terms" required />
+</form>
+```
+
+### A `RichTextEditor` became editable after upgrading
+
+**When:** after upgrading to 0.22.0, a `RichTextEditor` or
+`RichTextEditorFormField` without `editable`, used to show stored text, lets
+the user type into it.
+**Why:** Vue turns an absent `Boolean` prop into `false`, so in 0.21.0 an
+editor without `editable` was read-only, against its documented default. The
+props now keep their defaults, and `editable` defaults to `true`.
+**Fix:** pass `:editable="false"` where the editor only displays content:
+
+```vue
+<RichTextEditor v-model:content="notes" :editable="false" />
+```
+
+### Focus falls to `<body>` when a controlled `Drawer` closes
+
+**When:** with 0.21.0 or earlier, a `Drawer` you open yourself (`v-model:open`
+from a button of yours, no `DrawerTrigger`) leaves focus on `<body>` when it
+closes, so a keyboard or screen reader user starts again from the top of the
+page. `Dialog`, `Sheet` and `AlertDialog` hand focus back to that button.
+**Why:** reka's drawer returns focus to its trigger only, and a controlled
+drawer has none.
+**Fix:** upgrade to 0.22.0: `DrawerContent` records the element that had focus when
+the drawer opened and focuses it again on close, unless focus already went
+somewhere else or your `@close-auto-focus` calls `event.preventDefault()`.
+On an older version, focus the button yourself:
+
+```vue
+<script setup lang="ts">
+import { Button, Drawer, DrawerContent } from '@nxgt/material-vue';
+import { ref, useTemplateRef } from 'vue';
+
+const open = ref(false);
+const opener = useTemplateRef<InstanceType<typeof Button>>('opener');
+</script>
+
+<template>
+  <Button ref="opener" @click="open = true">Filters</Button>
+  <Drawer v-model:open="open">
+    <DrawerContent
+      @close-auto-focus="(event) => { event.preventDefault(); opener?.$el.focus(); }"
+    >
+      …
+    </DrawerContent>
+  </Drawer>
+</template>
+```
+
+---
+
+## PDF reader
+
+### A `PdfReader` event listener runs twice
+
+**When:** a `PdfReader` listener (`@page-change`, `@load-success`,
+`@load-error`, or the same handler passed as `:onPageChange`) runs twice for
+one event: a page counted twice in analytics, a toast shown twice. Seen with
+`@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** those versions declared `onPageChange`, `onLoadSuccess` and
+`onLoadError` as props *and* emitted the matching events. Vue stores
+`@page-change="fn"` as `onPageChange`, so the reader called `fn` once as the
+prop and once through `emit`. Since 0.22.0 it makes one call
+per event, whichever way the handler is bound.
+**Fix:** update `@nxgt/material-vue`. A guard you added to ignore the second
+call can go. Listen with the events; the three props still work but are
+deprecated and go in 1.0:
+
+```vue
+<PdfReader :file="url" @page-change="onPage" @load-success="onLoaded" />
+```
+
+### Download saves the PDF as `document.pdf`
+
+**When:** the toolbar's Download button saves every URL document as
+`document.pdf`. Seen with `@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** those versions hard-coded the name for a URL, and had no way to pass
+one. Since 0.22.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-vue`, and pass `file-name` when the URL ends
+in an id or in `pdf` rather than a useful name:
+
+```vue
+<PdfReader file="/api/invoices/1042/pdf" file-name="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
+`@nxgt/material-vue` 0.21.0 and earlier.
+**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 0.22.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-vue`. 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
+`@nxgt/material-vue` 0.21.0 and earlier.
+**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 0.22.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-vue`. To print differently, pass your own
+`onPrint`.
+
+### A wrong PDF password gives no feedback
+
+**When:** after a wrong password the password field just empties, with nothing
+saying why. Seen with `@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** pdf.js says whether it needs a password or the one given was wrong,
+and the reader ignored it. Since 0.22.0 the form says
+"Incorrect password. Try again." (`material.pdf-reader.password-incorrect`)
+after each wrong password, marks the field `aria-invalid`, announces the
+message and focuses the field again.
+**Fix:** update `@nxgt/material-vue`. Override the key to reword the message.
+
+### Escape does not close the dialog around a `PdfReader`
+
+**When:** a `PdfReader` inside a `Dialog`, `Sheet` or any overlay that closes
+on Escape: pressing Escape while the reader has focus does nothing. Seen with
+`@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** the reader called `preventDefault()` on every Escape, to close its
+search bar even when it was not open, and reka-ui ignores a prevented Escape.
+Since 0.22.0 it handles Escape only when the search bar is
+open, and then stops it there, so the first Escape closes the search bar and
+the next one the dialog.
+**Fix:** update `@nxgt/material-vue`.
+
+### `@page-change` 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 `@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** the reader clamped the page it showed but reported the page it was
+asked for. Since 0.22.0 it reports the clamped page, and
+only when the page changes.
+**Fix:** update `@nxgt/material-vue`. 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
+`@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** the fit assumed every page was US Letter (612 × 792 points) and ignored
+each page's own size. Since 0.22.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-vue`. On an older version,
+`default-fit-mode="custom"` with an `:initial-scale` 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 `@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** the search only counted the highlights already drawn, and highlighted
+the first case-insensitive match in each text run. Since 0.22.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-vue`.
+
+### `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, `@page-change` and the highlighted thumbnail on the page you
+started from. Seen with `@nxgt/material-vue` 0.21.0 and earlier.
+**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 0.22.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-vue`.
+
+### `Type 'Blob' is not assignable to type 'string | File | null'` on `PdfReader`
+
+**When:** up to 0.21.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 0.22.0 `file` takes all of them. 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:** `PdfReader` shows "Failed to load document" with this message.
+**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 0.22.0 the reader copies the bytes it
+is given, so it never detaches your buffer itself.
+**Fix:** in a layout of your own, load the document from `toPdfjsParams(file)`
+(exported beside `usePdfReader` since 0.22.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 in the
+template or a computed that runs again.
+**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:
+
+```vue
+<script setup lang="ts">
+import { onMounted, shallowRef } from 'vue';
+
+const file = shallowRef<Blob | null>(null);
+onMounted(async () => {
+  file.value = await (await fetch('/api/report')).blob();
+});
+</script>
+
+<template>
+  <PdfReader :file="file" file-name="report.pdf" />
+</template>
+```
+
+### 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:
+
+```vue
+<script setup lang="ts">
+import { shallowRef, watch } from 'vue';
+
+const props = defineProps<{ id: string; token: string }>();
+const file = shallowRef<Blob | null>(null);
+// Only a new document fetches again; a new token does not.
+watch(
+  () => props.id,
+  async (id, _previous, onCleanup) => {
+    let cancelled = false;
+    onCleanup(() => {
+      cancelled = true;
+    });
+    const response = await fetch(`/api/documents/${id}`, {
+      headers: { Authorization: `Bearer ${props.token}` },
+    });
+    const blob = await response.blob();
+    if (!cancelled) file.value = blob;
+  },
+  { immediate: true },
+);
+</script>
+
+<template>
+  <PdfReader :file="file" />
+</template>
+```
+
+### Links in a PDF do nothing in `PdfReader`
+
+**When:** clicking a link inside the document (a table of contents, a
+"see page 3", a web address) does nothing. `@nxgt/material-vue` 0.21.0 and
+earlier.
+**Why:** the reader drew each page and its text, but not its links (pdf.js's
+annotation layer), which `@nxgt/material` already drew.
+**Fix:** update `@nxgt/material-vue`: an internal link goes to its page, an
+external one opens in a new tab by default, with
+`rel="noopener noreferrer nofollow"`; `external-link-target="_self"` opens it
+in place instead. Notes show their icon and open their popup. Thumbnails stay
+without links.
+
+```vue
+<PdfReader file="/files/contract.pdf" external-link-target="_self" />
+```
+
+### 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
+`to` (from 0.22.0); `PdfReader`'s zoom menu does this itself:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+} from '@nxgt/material-vue/components';
+
+const container = ref<HTMLElement>();
+function onOpen(open: boolean) {
+  const element = document.fullscreenElement;
+  if (open) container.value = element instanceof HTMLElement ? element : undefined;
+}
+</script>
+
+<template>
+  <DropdownMenu @update:open="onOpen">
+    <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
+    <DropdownMenuContent :to="container">…</DropdownMenuContent>
+  </DropdownMenu>
+</template>
+```
+
+### 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 `@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** the tooltip was placed at the end of `body`, and in fullscreen the
+browser shows only the fullscreen element.
+**Fix:** update `@nxgt/material-vue`: a tooltip opens inside the element in
+fullscreen. To place it elsewhere, pass `TooltipContent`'s `to`.
+
+### 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 `@nxgt/material-vue` 0.21.0
+and earlier.
+**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
+0.22.0 it adds the page's `/Rotate` to its own, for the page, its
+thumbnail, its placeholder and the fit.
+**Fix:** update `@nxgt/material-vue`.
+
+### 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 `@nxgt/material-vue` 0.21.0 and earlier.
+**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 0.22.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-vue`. To keep one zoom from the start, use
+`default-fit-mode="custom"` with an `:initial-scale`.
+
+### `@page-change` 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
+`@nxgt/material-vue` 0.21.0 and earlier.
+**Why:** only pages you moved to were reported, not the pages the reader moved
+to itself. Since 0.22.0 both are reported, once.
+**Fix:** update `@nxgt/material-vue`. 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-vue` version, the full message, whether the app is SSR (Nuxt,
+Vite SSR) or SPA, and the bundler and its version.