@nxgt/material-vue 0.21.0 → 0.23.0

package/docs/guides/printing.md

@@ -0,0 +1,391 @@
+# Printing
+
+This page covers building printable documents (invoices, receipts, reports)
+with the print blocks of `@nxgt/material-vue`, and turning them into paper or
+a PDF.
+
+The print blocks are ordinary Vue components that render `<div>`s and
+`<span>`s with **inline styles**, so they look the same on screen, on paper and
+in any HTML-to-PDF tool, whatever your theme or Tailwind setup. You print them
+with the browser (`window.print()`) or hand the page to an HTML-to-PDF step.
+Nothing to install: they are in `@nxgt/material-vue/components`. To produce a
+PDF file without a browser, see [PDF documents](pdf.md) and
+[below](#html-print-blocks-or-pdf).
+
+```vue
+<!-- invoice-document.vue -->
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+  commonPrintStyles,
+  formatAmount,
+  formatDate,
+  PrintHeader,
+  PrintInfoRow,
+  PrintSection,
+  PrintTable,
+  PrintTableCell,
+  PrintTableHeader,
+  PrintTableRow,
+  PrintTotalRow,
+  PrintTotals,
+  tw,
+} from '@nxgt/material-vue/components';
+import type { Invoice } from './types';
+
+const props = defineProps<{ invoice: Invoice }>();
+
+const total = computed(() =>
+  props.invoice.lines.reduce((sum, line) => sum + line.quantity * line.unitPrice, 0),
+);
+</script>
+
+<template>
+  <div class="invoice" :style="tw(commonPrintStyles.page)">
+    <PrintHeader title="Invoice" :reference="invoice.number" logo-text="ACME" />
+    <PrintSection title="Details">
+      <PrintInfoRow label="Issued" :value="formatDate(invoice.issuedAt)" />
+      <PrintInfoRow label="Customer" :value="invoice.customer" />
+    </PrintSection>
+    <PrintTable>
+      <PrintTableHeader>
+        <PrintTableCell is-header :flex="3">Item</PrintTableCell>
+        <PrintTableCell is-header text-align="right">Qty</PrintTableCell>
+        <PrintTableCell is-header text-align="right">Amount</PrintTableCell>
+      </PrintTableHeader>
+      <PrintTableRow v-for="(line, index) in invoice.lines" :key="line.label" :is-alt="index % 2 === 1">
+        <PrintTableCell :flex="3">{{ line.label }}</PrintTableCell>
+        <PrintTableCell text-align="right">{{ line.quantity }}</PrintTableCell>
+        <PrintTableCell text-align="right">
+          {{ formatAmount(line.quantity * line.unitPrice, invoice.currency) }}
+        </PrintTableCell>
+      </PrintTableRow>
+    </PrintTable>
+    <PrintTotals>
+      <PrintTotalRow label="Total" :value="formatAmount(total, invoice.currency)" last />
+    </PrintTotals>
+  </div>
+</template>
+```
+
+```ts
+// types.ts
+export type Line = { label: string; quantity: number; unitPrice: number };
+export type Invoice = { number: string; issuedAt: string; customer: string; currency: string; lines: Line[] };
+```
+
+## The building blocks
+
+They render plain DOM, so they work anywhere a component does, including a
+server render. Colours and sizes are fixed (slate text, a dark `#1e293b` table
+header, sizes in `pt`), not taken from your theme tokens, so a document does not
+change with dark mode.
+
+| Component | Props | Renders |
+| --- | --- | --- |
+| `PrintHeader` | `title: string`, `subtitle?`, `reference?`, `reference-prefix?` (`'#'`), `logo?`, `logo-alt?`, `logo-text?`, `qr-data-url?` | A band with the title centred, a logo on the left and a QR image on the right when you pass them. See [below](#printheader) |
+| `PrintSection` | `title: string`, `class?: string`; default slot | A titled block. `class` is a `tw` string, not a CSS class (default `mb-3.5`) |
+| `PrintInfoRow` | `label: string`, `value?: string \| number`; default slot | A label / value line. The default slot (a `PrintBadge`, a link) replaces `value` |
+| `PrintCard` | `class?: string`; default slot | A bordered row of fields (`class` is a `tw` string) |
+| `PrintCardField` | `label: string`, `value?: string \| null` | A label over a value. **Renders nothing when `value` is empty** |
+| `PrintTable`, `PrintTableHeader` | default slot | Table section and its header row |
+| `PrintTableRow` | `is-alt?: boolean`; default slot | A row; `is-alt` shades it |
+| `PrintTableCell` | `is-header?: boolean`, `flex?: number` (`1`), `text-align?: 'left' \| 'right' \| 'center'` (`'left'`) | A cell. With no slot content it prints `—` |
+| `PrintTotals`, `PrintTotalRow` | `label: string`, `value: string`, `last?: boolean` | The totals block; `last` is the bold grand-total row on the dark band |
+| `PrintBadge` | `color?: string`, `class?: string`; default slot | A pill; `color` is a CSS colour for its background |
+
+`tw(classes)` turns a small set of Tailwind-like class names into a Vue style
+object, for your own blocks between them; `commonPrintStyles` holds the class
+strings the components are built from (`page`, `divider`, `infoGrid`,
+`notesSection`, …), so your blocks can match them:
+
+```vue
+<script setup lang="ts">
+import { commonPrintStyles, tw } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <div :style="tw(commonPrintStyles.notesSection)">
+    <p :style="tw(commonPrintStyles.notesText)">Payment received by bank transfer.</p>
+  </div>
+</template>
+```
+
+`tw` is not Tailwind. It knows:
+
+- colours `primary`, `secondary`, `muted`, `border`, `headerBg`, `headerText`,
+  `rowAlt`, `white`, `logoBg`, `qrBg`, `black` and `slate-50` … `slate-900`, as
+  `bg-*`, `text-*` and `border-*`;
+- `font-sans` (Helvetica), `font-serif` (Times-Roman), `font-mono` (Courier),
+  `font-bold`, `uppercase`, `leading-normal`, `tracking-tight`, `tracking-wide`;
+- `flex-row`, `flex-col`, `flex-1`, `items-center`, `items-end`,
+  `justify-center`, `justify-between`, `self-start`;
+- `border`, `border-b`, `rounded`, `rounded-xs`, `rounded-lg`, `rounded-xl`;
+- `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `m*`, `gap`, `w`, `h` with the steps
+  `0`, `0.5`, `1`, `1.5`, `2`, `2.5`, `3`, `3.5`, `4`, `7`, `8`, `32`, `xs`, or an
+  arbitrary value (`p-[12pt]`, `w-[220pt]`, `text-[9pt]`).
+
+**Anything else is dropped without a warning.**
+
+**Every length comes out with a unit**, because Vue writes inline styles as
+given and a browser drops a unitless length. The steps, radii and tracking are
+in points, as in `@nxgt/material`'s react-pdf (`p-4` gives
+`{ padding: '12pt' }`, `gap-1.5` `'4.5pt'`); `border` and `border-b` are 1 px
+(`border-b` on the bottom side only); an arbitrary value keeps the unit you
+wrote (`p-[12pt]`, `text-[10px]`).
+
+### `PrintHeader`
+
+```vue
+<script setup lang="ts">
+import { PrintHeader } from '@nxgt/material-vue/components';
+
+defineProps<{ number: string; qr: string }>();
+</script>
+
+<template>
+  <PrintHeader
+    title="Invoice"
+    subtitle="Acme Inc. · 12 rue de la Paix, Paris"
+    :reference="number"
+    :logo="{ src: '/brand/logo.png', width: 96, height: 32 }"
+    :qr-data-url="qr"
+  />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` | `string` | required | The document title, centred. |
+| `subtitle` | `string` | — | A smaller muted line under the title. |
+| `reference` | `string` | — | The document number, under the title. |
+| `reference-prefix` | `string` | `'#'` | Printed before `reference`: `reference-prefix="No. "` gives `No. INV-2044`, `reference-prefix=""` the bare number. |
+| `logo` | `string \| { src: string; width?: number; height?: number }` | — | An image on the left: a URL or a data URL, or an object with its size in points (`72`×`48` by default). It is scaled to fit that box (`object-fit: contain`), never cropped. |
+| `logo-alt` | `string` | `''` | Vue only (a react-pdf image has no alt). The logo's text alternative. Empty by default, which marks the logo decorative: the title and subtitle beside it usually name the issuer. Give one when the logo says something they do not. |
+| `logo-text` | `string` | — | Text in a grey `72`×`48` pt box on the left, when there is no `logo`. No box when neither is given. |
+| `qr-data-url` | `string \| null` | — | A QR code already rendered as an image data URL, `60`×`60` pt on the right. No box without one. |
+
+```ts
+type PrintHeaderProps = {
+  title: string;
+  subtitle?: string;
+  reference?: string;
+  referencePrefix?: string;
+  logo?: string | { src: string; width?: number; height?: number };
+  logoAlt?: string;
+  logoText?: string;
+  qrDataUrl?: string | null;
+};
+```
+
+The left and right sides take the width of the wider one, so the title stays
+centred whether you pass a logo, a QR code, both or neither. For a logo that
+must print on a server or in a headless browser, a data URL
+(`data:image/png;base64,…`) avoids a second request.
+
+**Changed in 0.22.0:** with no `logo` and no `logo-text` the
+header no longer draws a grey "LOGO" placeholder, and with no `qr-data-url` no
+empty QR box. Pass `logo-text="LOGO"` to keep the old box. See
+[troubleshooting](../troubleshooting.md#the-printheader-logo-box-disappeared-after-upgrading).
+
+### `formatAmount` and `formatDate`
+
+```ts
+function formatAmount(
+  value: number | null | undefined,
+  currency?: string | null,
+  options?: { locale?: string; fractionDigits?: number },
+): string;
+function formatDate(
+  value: string | number | Date | null | undefined,
+  options?: { locale?: string; timeZone?: string; dateStyle?: 'full' | 'long' | 'medium' | 'short'; timeStyle?: 'full' | 'long' | 'medium' | 'short' },
+): string;
+```
+
+```ts
+import { formatAmount, formatDate } from '@nxgt/material-vue/lib';
+
+formatAmount(1234.5, 'EUR', { locale: 'fr-FR' });   // '1 234,50 €'
+formatAmount(1234.5, 'JPY', { locale: 'en-US' });   // '¥1,235' (the yen has no decimals)
+formatAmount(1.5, 'KWD', { locale: 'en-US' });      // 'KWD 1.500' (three)
+formatAmount(1234.5, 'JPY', { fractionDigits: 2 }); // '¥1,234.50', two decimals whatever the currency
+formatAmount(1234.5);                               // '1,234.50' (no currency: two decimals)
+formatAmount(null);                                 // '—'
+formatAmount(1234.5, 'EURO');                       // '1234.50 EURO' (malformed currency code)
+
+formatDate('2026-03-01', { locale: 'en-US' });      // 'Mar 1, 2026', in every time zone
+formatDate('2026-03-01T23:30:00Z', { locale: 'fr-FR', timeZone: 'Europe/Paris' }); // '2 mars 2026'
+formatDate(new Date(), { timeStyle: 'short' });     // date and time
+formatDate(undefined);                              // '—'
+formatDate('not a date');                           // 'not a date'
+```
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `locale` | the runtime's locale | BCP 47 tag (`'fr-FR'`), for both functions. |
+| `fractionDigits` | the currency's own (ISO 4217), or 2 without a currency | `formatAmount` decimals, clamped to 0–20 (the range every `Intl` accepts; engines before ES2023 throw above 20). `NaN` or `Infinity` counts as not given, as in `CurrencyField`. Pass `2` to keep the output of 0.21.0 and before. |
+| `timeZone` | the runtime's time zone | `formatDate`, for values with a time. A date-only string (`YYYY-MM-DD`) always keeps its calendar day. |
+| `dateStyle` / `timeStyle` | `'medium'` / none | `formatDate` styles; `timeStyle` is ignored for a date-only value. |
+
+They are pure `Intl` helpers, in `@nxgt/material-vue/lib` as in
+`@nxgt/material`, and still exported from `/components` and the root barrel
+next to the print components.
+
+**Server rendering.** Without `locale` and `timeZone` they use the runtime's,
+so a server and a French browser print different strings. In a component, bind
+them to the `I18nProvider` language (`en` without a provider); it is
+auto-imported in Nuxt:
+
+```vue
+<script setup lang="ts">
+import { PrintInfoRow, PrintTotalRow } from '@nxgt/material-vue/components';
+import { useFormatters } from '@nxgt/material-vue/composables'; // auto-imported in Nuxt
+
+const props = defineProps<{ total: number; issuedAt: string }>();
+const { formatAmount, formatDate } = useFormatters({ timeZone: 'Europe/Paris' });
+</script>
+
+<template>
+  <PrintTotalRow label="Total" :value="formatAmount(props.total, 'EUR')" last />
+  <PrintInfoRow label="Issued" :value="formatDate(props.issuedAt)" />
+</template>
+```
+
+Outside a component (a Nuxt server route), bind them once:
+
+```ts
+import { createFormatters } from '@nxgt/material-vue/lib';
+
+const { formatAmount, formatDate } = createFormatters({ locale: 'fr-FR', timeZone: 'Europe/Paris' });
+formatAmount(1234.5, 'EUR'); // '1 234,50 €'
+```
+
+**Changed in 0.22.0:** amounts use their currency's own
+decimals (JPY and KRW show none, KWD, BHD and OMR show three) where every
+currency used to get two, and a date-only string keeps its day instead of
+showing the previous day west of UTC. Pass `{ fractionDigits: 2 }` to keep two
+decimals.
+
+## Rendering the document
+
+**In the browser**, print the page. Hide everything but the document, and
+tell the browser to keep the background colours: by default it drops them, and
+the table header and the grand-total row are white text on a dark background.
+
+```vue
+<script setup lang="ts">
+import { Button } from '@nxgt/material-vue/components';
+import InvoiceDocument from './invoice-document.vue';
+import type { Invoice } from './types';
+
+defineProps<{ invoice: Invoice }>();
+
+function print() {
+  window.print();
+}
+</script>
+
+<template>
+  <Button class="print:hidden" variant="outlined" @click="print">Print</Button>
+  <InvoiceDocument :invoice="invoice" />
+</template>
+```
+
+```css
+/* the app's stylesheet */
+@media print {
+  @page { size: A4; margin: 0; }
+  body * { visibility: hidden; }
+  .invoice, .invoice * { visibility: visible; }
+  .invoice {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    print-color-adjust: exact;
+    -webkit-print-color-adjust: exact;
+  }
+}
+```
+
+The browser's print dialog also offers "Save as PDF". For a cleaner page, give
+the document a route of its own, outside the app shell, and open it in a new
+tab before printing.
+
+**On a server**, render that route with a headless browser and ask for a PDF.
+This is your dependency, not this package's; with Playwright:
+
+```ts
+import { chromium } from 'playwright';
+
+export async function invoicePdf(url: string): Promise<Uint8Array> {
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    await page.goto(url, { waitUntil: 'networkidle' });
+    return await page.pdf({ format: 'A4', printBackground: true });
+  } finally {
+    await browser.close();
+  }
+}
+```
+
+`printBackground: true` is the headless equivalent of `print-color-adjust:
+exact`.
+
+### Showing a PDF from a protected route
+
+`PdfReader` (from `@nxgt/material-vue/components`) opens that PDF from the
+route that serves it, with the headers the route needs, and Download saves it
+under `file-name`:
+
+```vue
+<script setup lang="ts">
+import { PdfReader } from '@nxgt/material-vue/components';
+
+const props = defineProps<{ invoiceId: string; token: string }>();
+</script>
+
+<template>
+  <div class="h-[600px]">
+    <PdfReader
+      :file="{ url: `/api/invoices/${props.invoiceId}.pdf`, httpHeaders: { Authorization: `Bearer ${props.token}` } }"
+      :file-name="`${props.invoiceId}.pdf`"
+    />
+  </div>
+</template>
+```
+
+It opens the bytes too (a `Blob`, an `ArrayBuffer` or a `Uint8Array`), and
+they stay usable after the reader opened them. See
+[PdfReader](../components/media-and-files.md#pdfreader).
+
+## HTML print blocks or `/pdf`
+
+Two ways to print, for two jobs:
+
+| | `Print*` blocks (`/components`) | [`@nxgt/material-vue/pdf`](pdf.md) |
+| --- | --- | --- |
+| What you write | Vue components, laid out like a page | a plain-data document, from builders |
+| Output | HTML: `window.print()`, "Save as PDF", or a headless browser | a real PDF file: `Blob`, bytes, a download, a server `Response` |
+| On a server | through Playwright or another headless browser | `pdfResponse` in a Nitro route, Node 18+ or Bun |
+| Install | nothing | `react` and `@react-pdf/renderer` (optional peers) |
+| Pages | the browser paginates | page size, margins, repeated header, footer and page numbers |
+| Right-to-left and complex scripts | yes, the browser shapes them | no: the PDF engine does not shape Arabic or Hebrew reliably |
+
+Use the blocks to print what the user sees, or when a headless browser is
+already part of your stack. Use `/pdf` for a file that is produced on demand
+(an invoice route, an email attachment), for documents shared with a React app
+(the same model as `@nxgt/material/print`), or when you need page numbers and
+a repeated header without print CSS.
+
+Coming from React's `@nxgt/material/print`: its document model and output
+functions (`pdfDocument`, `definePdfDocument`, `downloadPdf`, `pdfResponse`,
+`definePrintColumns`, …) are in `@nxgt/material-vue/pdf` under the same names.
+Its react-pdf components have no Vue version; the blocks above share their
+names and props (`PrintHeader`, `PrintTable`, `PrintTotals`, …) but render
+HTML: import them from `@nxgt/material-vue/components`, pass props in
+kebab-case (`is-header`, `text-align`, `qr-data-url`), and replace `Document`
+and `Page` with a `div` styled `tw(commonPrintStyles.page)`. `PrintDocument`,
+`PrintDataTable`, `PrintKeyValue` and `PrintMetric` have none: use `/pdf`'s
+`page`, `dataTable`, `keyValueOf` and `metric`.

package/docs/guides/ssr.md

@@ -0,0 +1,280 @@
+# SSR
+
+This page is for an app that renders on a server — Nuxt, or a Vite SSR
+server of your own. It lists what the package guarantees and the few things
+you must do yourself.
+
+The usual setup bundles the package into the server build. The Nuxt module
+does it for you ([below](#nuxt)); a hand-written Vite SSR app says so itself:
+
+```ts
+// vite.config.ts
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [vue()],
+  ssr: { noExternal: ['@nxgt/material-vue', '@nxgt/material-core'] },
+});
+```
+
+`@nxgt/material-core` is a dependency of this package that its built code
+imports by name: bundle it together with `@nxgt/material-vue`, or a server run
+without it in `node_modules` fails at boot with
+[`Cannot find package '@nxgt/material-core'`](../troubleshooting.md#cannot-find-package-nxgtmaterial-core).
+
+With that, **every module the barrels reach is evaluated when the server
+boots**, whether or not a page renders the component. A browser global touched
+at import time would crash the server before it answers anything.
+
+## What the package guarantees
+
+- **Every entry is safe to import in a runtime without a DOM.**
+  `@nxgt/material-vue`, `/components`, `/composables`, `/i18n`, `/lib`,
+  `/dnd`, `/models`, `/types`, `/map`, `/pdf` and `/vite` touch no `window`,
+  `document` or `DOMMatrix` at module scope. This is checked on every build, see
+  [what `verify:ssr` checks](#what-verifyssr-checks).
+- **Browser-only widgets render nothing on the server.** They load their
+  heavy dependency with `import()` and are wrapped in `clientOnly`, so they
+  appear after hydration, with no mismatch:
+
+  | Component | Why it is browser-only |
+  | --- | --- |
+  | `PdfReader`, `PdfSidebar`, `PdfPageList`, `PdfThumbnailSidebar` | `pdfjs-dist` runs `new DOMMatrix()` when it is imported |
+  | `CodeEditor`, `CodeDiff` | Monaco |
+  | `Camera` | `getUserMedia` |
+  | `StxPlayer` | media element APIs |
+  | the charts (`BarChart`, `AreaChart`, `HeatmapChart`, …) | ECharts draws on a canvas it sizes from the DOM |
+  | `ImageCropper` (its canvas) | canvas cropping |
+  | `RichTextEditor` (its editor) | Tiptap / ProseMirror |
+  | mermaid diagrams inside `Markdown` | mermaid renders in the browser; the rest of the Markdown renders on the server |
+
+- **The map entry is importable, but draws in the browser only.**
+  `@nxgt/material-vue/map` is its own entry because `leaflet` and
+  `@vue-leaflet/vue-leaflet` are optional peers, and no other entry may reach
+  them. `@vue-leaflet/vue-leaflet` loads leaflet with `import()` when a map
+  mounts, so importing `/map` on a server is safe; the map itself renders an
+  empty container until it mounts in the browser. See
+  [maps](maps.md#browser-only).
+
+## What `verify:ssr` checks
+
+`bun run build` ends with `verify:ssr`, which fails the build — before a
+release can be published — in three cases:
+
+1. **An entry throws when imported without a DOM.** Every built JavaScript
+   entry (`main`, `components`, `composables`, `dnd`, `i18n`, `lib`, `map`,
+   `models`, `pdf`, `types`, `vite`) is imported in Bun, a runtime with no
+   `document`, `window` or `DOMMatrix` — what a server does at boot.
+2. **An entry statically reaches a dependency that must stay behind
+   `import()`.** Today that is `pdfjs-dist` and `@react-pdf/renderer`. The
+   check follows static imports transitively and ignores `import()`, which is
+   exactly the shape that keeps such a dependency out of your server's boot —
+   and lets `/pdf` import where its optional peers are not installed.
+3. **An optional peer is reached from an entry other than its own.**
+   `leaflet` and `@vue-leaflet/vue-leaflet` belong to `map`; `react` and
+   `@react-pdf/renderer` to `pdf`. An app that renders no map, or no PDF,
+   never has them in its graph.
+
+What it does **not** prove: that a component renders correctly on a server,
+or hydrates without a mismatch. Only rendering a page in your app shows that.
+It also does not cover the Nuxt module, which is TypeScript source that Nuxt
+loads at build time, not a runtime entry.
+
+## Nuxt
+
+```ts
+// nuxt.config.ts
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineNuxtConfig({
+  modules: ['@nxgt/material-vue/nuxt'],
+  css: ['~/assets/css/main.css'],
+  vite: { plugins: [tailwindcss()] },
+});
+```
+
+The module adds `@nxgt/material-vue` to `build.transpile`, so the package is
+bundled into the Nitro server and its barrels are evaluated at boot — which is
+why the guarantees above matter. It also installs Pinia when the app has none,
+and auto-registers the components and composables (options in
+[getting started](../getting-started.md#nuxt)).
+
+What to know in a Nuxt app:
+
+- **The browser-only widgets need nothing from you.** `PdfReader`, `Camera`,
+  `StxPlayer`, the charts and the rest of the table above are already
+  client-only, and the module registers them like any other component:
+
+  ```vue
+  <template>
+    <PdfReader file="/files/contract.pdf" />
+  </template>
+  ```
+
+- **A map goes in `<ClientOnly>`.** The map components are not
+  auto-registered (their peers are optional), and leaflet initialises in the
+  browser only:
+
+  ```vue
+  <script setup lang="ts">
+  import '@nxgt/material-vue/map.css';
+  import { Map } from '@nxgt/material-vue/map';
+  </script>
+
+  <template>
+    <ClientOnly>
+      <Map :center="[48.8566, 2.3522]" :zoom="12" class="h-80" />
+    </ClientOnly>
+  </template>
+  ```
+
+- **A PDF from `@nxgt/material-vue/pdf`** is imported where you use it, like
+  the map. `usePdf` renders nothing on the server, and a Nitro route answers
+  with `pdfResponse`; a server with no `node_modules` needs
+  `nxgtMaterial: { pdf: { bundleStandardFonts: true } }` ([PDF documents](pdf.md)).
+- **Your own browser-only component**: name it `*.client.vue` (Nuxt then
+  leaves it out of the server bundle), or use `clientOnly` +
+  `defineAsyncComponent` as in the next section. Wrapping a statically
+  imported component in `<ClientOnly>` gates the render but still evaluates
+  its module on the server.
+- **Language and theme**: pass the request's language to `I18nProvider`
+  ([i18n](i18n.md#server-rendering)) and emit the theme boot script from
+  `app.head` ([theming](theming.md#no-flash-on-load-a-boot-script)).
+
+## Your own browser-only code: `import()` + `clientOnly`
+
+When a dependency touches the DOM at import time, a `typeof window` guard
+around the call does nothing: by then the module has already been evaluated.
+Defer the **import**, and gate the **render**:
+
+```vue
+<!-- ChartEditor.vue: imports something that reads `window` at module scope -->
+<template>
+  <div>…</div>
+</template>
+```
+
+```ts
+// chart-editor.ts: evaluated on the server
+import { defineAsyncComponent } from 'vue';
+import { clientOnly } from '@nxgt/material-vue/lib';
+
+export const ChartEditor = clientOnly(defineAsyncComponent(() => import('./ChartEditor.vue')));
+```
+
+```ts
+function clientOnly<P extends object>(component: Component<P>): Component<P>;
+```
+
+- It renders nothing on the server **and** on the first client render, so
+  hydration compares an empty node with an empty node. The component mounts
+  right after; with `defineAsyncComponent`, that is when its chunk is loaded.
+- Attributes and slots are passed through to the wrapped component.
+- Nested `clientOnly` components inside an already-gated subtree render
+  straight through, without a second blank frame.
+- For a conditional inside a component, `useIsClient()` from
+  `@nxgt/material-vue/composables` is a `Ref<boolean>` that is `false` on the
+  server and the first render, then `true`.
+
+## Hydration
+
+**Never name an SVG with `<svg><title>`.** Some SSR setups treat `<title>` as
+document metadata and move it out of the SVG on the server, while the client
+renders it inline: a hydration mismatch. Name an icon with `role="img"` and
+`aria-label` instead; `Icon`, `Spinner` and `CircularProgress` already do.
+
+```vue
+<svg role="img" aria-label="Upload" viewBox="0 0 24 24">…</svg>
+```
+
+State the server cannot know must be resolved the same way on both sides:
+
+| What | On the server | Do this |
+| --- | --- | --- |
+| Language | no `localStorage`: `default-language` | Resolve it from the request and pass `initial-language` to `I18nProvider`. See [i18n](i18n.md#server-rendering) |
+| Theme | no preference: light | An inline boot script in `<head>` for the first paint. `useTheme()` reads the stored preference after mount, so it hydrates without a mismatch. See [theming](theming.md#no-flash-on-load-a-boot-script) |
+| Viewport, `prefers-color-scheme` | `useIsMobile()`, `PaneLayout` and `ListDetailsLayout` answer for `provideSSRWidth()`'s width, or a 1024 px desktop: `false`; the color scheme is light | Nothing: the first client render answers the same, then a phone or a dark screen switches. To render a phone's layout on the server, `provideSSRWidth(width, app)` from `@vueuse/core` with a width you infer from the request, and the same width on the client (serialised into the payload) so the first client render matches: see [the same width on both sides](#the-same-width-on-the-server-and-the-client) |
+| `formatAmount`, `formatDate` | the server's locale and time zone, unless you pass them | Use `useFormatters({ timeZone })`, which follows the `I18nProvider` language, or pass `locale` and `timeZone` (`createFormatters` binds them). A date-only `YYYY-MM-DD` is the same everywhere. See [printing](printing.md#formatamount-and-formatdate) |
+| Step form (`defineStepFormStore`) | no `localStorage`: step 0 | Nothing: a hydrating client renders step 0 too, then resumes. See [forms](forms.md#a-multi-step-form) |
+| `Filter` `persistence` (`localStorage` / `sessionStorage` / URL) | no storage: the default values | Nothing: stored values are read once mounted, so the page hydrates without a mismatch, then they show (the `Guides/SSR/Filter persistence` story) |
+| Zod messages | no `localStorage`: `zodLocaleError()` writes English | Pass the request's language: `zodLocaleError({ language: () => requestLanguage() })`. See [i18n](i18n.md#zod-messages) |
+
+### The same width on the server and the client
+
+To render a phone's layout on the server, give `provideSSRWidth()` a width
+you infer from the request, and give the client the **same** width for its
+first render: `useIsMobile()`, `PaneLayout`, `ListDetailsLayout` and the other
+width-dependent components answer for it on both sides, then switch to the
+real screen once mounted. A client that provides nothing answers for 1024 px,
+which differs from a phone width the server used — a hydration mismatch.
+
+With your own Vite SSR entries, send the width with the page:
+
+```ts
+// entry-server.ts
+import { provideSSRWidth } from '@vueuse/core';
+import { renderToString } from 'vue/server-renderer';
+import { createApp } from './main';
+
+export async function render(url: string, userAgent: string) {
+  // Your guess from the request: a user agent, or the Sec-CH-Viewport-Width hint.
+  const width = /Mobi|Android|iPhone/i.test(userAgent) ? 390 : 1024;
+  const { app } = createApp(url);
+  provideSSRWidth(width, app);
+  const html = await renderToString(app);
+  // Into the page, before the client entry's <script>.
+  const head = `<script>window.__SSR_WIDTH__ = ${JSON.stringify(width)}</script>`;
+  return { html, head };
+}
+```
+
+```ts
+// entry-client.ts
+import { provideSSRWidth } from '@vueuse/core';
+import { createApp } from './main';
+
+declare global {
+  interface Window {
+    __SSR_WIDTH__?: number;
+  }
+}
+
+const { app } = createApp(location.pathname);
+provideSSRWidth(window.__SSR_WIDTH__ ?? null, app);
+app.mount('#app');
+```
+
+In Nuxt, `useState` is that payload: its value is serialised on the server and
+read back on the client, where the initialiser does not run again.
+
+```ts
+// plugins/ssr-width.ts
+import { provideSSRWidth } from '@vueuse/core';
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const width = useState('ssr-width', () => {
+    const userAgent = useRequestHeaders(['user-agent'])['user-agent'] ?? '';
+    return /Mobi|Android|iPhone/i.test(userAgent) ? 390 : 1024;
+  });
+  provideSSRWidth(width.value, nuxtApp.vueApp);
+});
+```
+
+## Symptoms
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `ReferenceError: window is not defined` at server boot | `leaflet` (or another browser-only module) imported statically by your server code | Import maps from `@nxgt/material-vue/map` only, never `leaflet` directly; `clientOnly(defineAsyncComponent(() => import('./MapView.vue')))` for your own |
+| `ReferenceError: DOMMatrix is not defined` at server boot | a static `pdfjs-dist` import in your own code | `import()` + `clientOnly`, or use `PdfReader` |
+| Built server fails at boot with `Cannot find package '@nxgt/material-core'` | the library bundled into the server, its core left out | Add `@nxgt/material-core` wherever `@nxgt/material-vue` is in `ssr.noExternal` or `--external` ([troubleshooting](../troubleshooting.md#cannot-find-package-nxgtmaterial-core)) |
+| Built server answers nothing on every route; its log names a module it cannot find | a bundled dependency whose loader resolves paths at runtime | Keep such a dependency out of your server bundle (`import()` + `clientOnly`), or leave it external |
+| A map renders as an empty box on the first paint | leaflet initialises in the browser only | Expected: wrap it in `<ClientOnly>` ([maps](maps.md#browser-only)) |
+| `getActivePinia()` was called but there was no active Pinia | a widget rendered on the server before Pinia was installed | `app.use(createPinia())` in the server entry too; in Nuxt the module does it |
+| Text flips language right after load | no `initial-language` | Pass the request's language ([i18n](i18n.md#server-rendering)) |
+| Hydration mismatch around an icon | an `<svg><title>` in your markup | `role="img"` + `aria-label` |
+| Hydration mismatch on a phone around a `ResponsiveButton`, the app shell or a `DataTable`, or on a dark screen around a code block, 0.21.0 or earlier | the server answered "desktop, light", the phone's first render its own screen | upgrade ([troubleshooting](../troubleshooting.md#hydration-completed-but-contains-mismatches)) |
+| Hydration mismatch on a page with a `TimeField`, 0.21.0 or earlier | the server rendered the phone (dialog) trigger, a desktop client the popover one | upgrade ([troubleshooting](../troubleshooting.md#hydration-completed-but-contains-mismatches)) |
+
+More entries, with the full message and fix, are in
+[troubleshooting](../troubleshooting.md).