@nxgt/material-vue 0.21.0 → 0.23.0

package/docs/guides/maps.md

@@ -0,0 +1,265 @@
+# Maps
+
+This page covers rendering Leaflet maps, markers and a location field with
+`@nxgt/material-vue/map`, and rendering them only in the browser.
+
+```bash
+bun add leaflet @vue-leaflet/vue-leaflet
+bun add -d @types/leaflet   # for the LatLng type in your own code
+```
+
+Those two are **optional peers**: an app that renders no map never has Leaflet
+in its tree. Then load Leaflet's stylesheet once, next to your app's CSS:
+
+```ts
+import '@nxgt/material-vue/map.css';
+```
+
+It is not part of `styles.css` (it is `@import "leaflet/dist/leaflet.css"`, and
+resolves only when `leaflet` is installed). Without it tiles render with no
+controls and a broken layout.
+
+```vue
+<script setup lang="ts">
+import '@nxgt/material-vue/map.css';
+import { Map, Marker } from '@nxgt/material-vue/map';
+</script>
+
+<template>
+  <Map class="size-96" :center="[48.8566, 2.3522]">
+    <Marker :position="[48.8566, 2.3522]" reference>
+      <template #tooltip>Head office</template>
+    </Marker>
+  </Map>
+</template>
+```
+
+`Map` shadows the global `Map` constructor in the module that imports it. When
+that module also needs the global one, import the component as `MapComponent`,
+the same export under another name.
+
+## Browser only
+
+**This entry can be imported without a DOM, but it only renders in a
+browser.** `@vue-leaflet/vue-leaflet` loads `leaflet` with `import()` when a
+map mounts, and nothing in this entry imports `leaflet` at module scope, so a
+server process can evaluate `@nxgt/material-vue/map` without throwing (the
+package's build checks it). Leaflet itself still only initialises in the
+browser: on the server, and until the component mounts, the map is an empty
+box.
+
+- **An SPA has nothing to do.** There is no server pass.
+- **Nuxt**: wrap the map in `<ClientOnly>`, and import it where you use it.
+  The Nuxt module does **not** auto-register the map components, so an app
+  that renders no map never resolves the optional peers:
+
+```vue
+<!-- pages/contact.vue -->
+<script setup lang="ts">
+import '@nxgt/material-vue/map.css';
+import { Map, Marker } from '@nxgt/material-vue/map';
+</script>
+
+<template>
+  <ClientOnly>
+    <Map class="h-80 w-full" :center="[48.8566, 2.3522]">
+      <Marker :position="[48.8566, 2.3522]" reference />
+    </Map>
+  </ClientOnly>
+</template>
+```
+
+- **Another SSR setup**: render it through `clientOnly`, which renders nothing
+  on the server and on the first client render, then mounts it:
+
+```ts
+// office-map.ts
+import { defineAsyncComponent } from 'vue';
+import { clientOnly } from '@nxgt/material-vue/lib';
+
+export const OfficeMap = clientOnly(defineAsyncComponent(() => import('./office-map.vue')));
+```
+
+Your own code is a different matter: a **value** import of `leaflet`
+(`import L from 'leaflet'`, `import { latLng } from 'leaflet'`) in a module the
+server evaluates throws `ReferenceError: window is not defined` at boot.
+Import its types with `import type`, or keep that module behind `import()`.
+See [SSR](ssr.md) and
+[troubleshooting](../troubleshooting.md#referenceerror-window-is-not-defined).
+
+## `Map`
+
+An `LMap` from `@vue-leaflet/vue-leaflet` with an OpenStreetMap tile layer and a
+zoom control, using the copy of Leaflet it imports itself
+(`use-global-leaflet` off). Its defaults are not neutral:
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `center` | `[number, number]` | the visitor's position, else `[5.44087, 10.06843]` (Yaoundé) | Where the map opens. Optional: see below |
+| `zoom` | `number` | `13` | Initial zoom |
+| `scroll-wheel-zoom` | `boolean` | `false` | A map inside a scrolling page does not capture the wheel |
+| `zoom-control` | `boolean` | `false` | Leaflet's *own* control. Off because `Map` renders an `LControlZoom` at `topleft`; `true` gives you two |
+| `class` | `string` | — | Added to `size-full ring-1 ring-primary rounded`. The map needs a height: give the map or its parent one |
+
+Those are the only props. The default slot takes markers, controls and any
+`@vue-leaflet/vue-leaflet` layer.
+
+**`Map` asks the browser for the visitor's location when it mounts, whether or
+not you pass `center`.** It calls `useGeolocation()` unconditionally, which
+starts watching the position on setup. `center` only decides where the map
+opens. `LocationMarker` and `MapActions` watch the position too; `LocationField`
+and `LocationPreview` render a `Map`, so they prompt when their dialog or hover
+card opens. For a map that must never prompt, compose `LMap` and `LTileLayer`
+from `@vue-leaflet/vue-leaflet` yourself; `Marker` works inside any `LMap`.
+
+**Without `center`, `Map` opens on a default position** (Yaoundé, as in
+`@nxgt/material`) and moves to the visitor once the browser reports one. If
+they refuse, it stays on the default. `LocationMarker` and the "My position"
+button of `MapActions` appear only once the position is known.
+
+The tile URL (`https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png`) is fixed.
+It needs no key, and it is subject to the OpenStreetMap tile usage policy.
+
+## Markers and controls
+
+| Export | Props, slots, events | What it does |
+| --- | --- | --- |
+| `Marker` | `position: [number, number]`, `draggable?`, `reference?`; slots `#icon`, `#tooltip`, `#popup`; `@change(position: LatLng)` | A marker. With `reference` it is drawn as a map pin (Lucide `MapPin`), with an `#icon` slot as your own markup; otherwise Leaflet's default icon. `@change` fires when a drag ends |
+| `LocationMarker` | slots `#icon`, `#tooltip`, `#popup`; `@change` | A pin on the visitor's position; renders nothing until the position is known. Its tooltip reads "You are here" (`material.map.you-are-here`, translated under `I18nProvider`) unless you fill `#tooltip`. Unlike React's, it does not pan the map |
+| `MapActions` | `position?: 'topleft' \| 'topright' \| 'bottomleft' \| 'bottomright'` (`'topleft'`), `class?` | Zoom in / out buttons, named from `material.map.zoom-in` / `zoom-out` (translated under `I18nProvider`), plus a "My position" button (`material.map.my-position`) that pans to the visitor, shown once the position is known. Outside a `Map` the buttons do nothing |
+| `LocationPreview` | `position: [number, number]`, `name?: string`; default slot | A hover card with a small map (zoom 15) of `position`. The default trigger is named "Preview {name}", or "Preview location" without a `name` (`material.map.preview-named` / `preview`, translated under `I18nProvider`). The default slot replaces the trigger button. The map mounts only while the card is open |
+| `useGeolocation(options?)` | `{ enableHighAccuracy?, timeout?, maximumAge?, immediate? }` | `@vueuse/core`'s `useGeolocation`, with `enableHighAccuracy: false`, a 5 s `timeout` and `maximumAge: 0` unless you pass your own |
+| `POSITION_CLASSES` | — | The Leaflet corner class names, for your own controls |
+| `LatLngTuple` | — | `[number, number]`, the one position shape every component here takes |
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import type { LatLng } from 'leaflet';
+import { type LatLngTuple, Map, MapActions, Marker } from '@nxgt/material-vue/map';
+
+const position = ref<LatLngTuple>([45.764, 4.8357]);
+
+function onChange(next: LatLng) {
+  position.value = [next.lat, next.lng];
+}
+</script>
+
+<template>
+  <Map class="h-96" :center="position">
+    <MapActions position="topright" />
+    <Marker :position="position" draggable reference @change="onChange">
+      <template #tooltip>{{ position[0].toFixed(4) }}, {{ position[1].toFixed(4) }}</template>
+    </Marker>
+  </Map>
+</template>
+```
+
+```ts
+function useGeolocation(options?: {
+  enableHighAccuracy?: boolean; // false
+  timeout?: number;             // 5000
+  maximumAge?: number;          // 0
+  immediate?: boolean;          // true: start watching on setup
+}): {
+  coords: ComputedRef<{ latitude: number; longitude: number } | null>;
+  locatedAt: Ref<number | null>;
+  error: Ref<GeolocationPositionError | null>;
+  resume: () => void;
+  pause: () => void;
+};
+```
+
+`coords` is `null` until the first fix, and stays `null` when the visitor
+refuses or the browser has no geolocation, so `if (coords.value)` is enough.
+
+## `LocationField` and `LocationFormField`
+
+A read-only text field showing `lat - lng`, a hover preview on the leading
+icon while there is a value, and a dialog with a draggable pin on the trailing
+button. The value is a
+`[lat, lng]` tuple rounded to 7 decimals, or `null`.
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { Button } from '@nxgt/material-vue/components';
+import { LocationFormField } from '@nxgt/material-vue/map';
+
+type Venue = { position: [number, number] | null };
+
+const emit = defineEmits<{ save: [values: Venue] }>();
+
+const { handleSubmit } = useForm<Venue>({ initialValues: { position: [48.8566, 2.3522] } });
+const onSubmit = handleSubmit((values) => emit('save', values));
+</script>
+
+<template>
+  <form class="grid gap-4" @submit="onSubmit">
+    <LocationFormField
+      name="position"
+      label="Location"
+      dialog-title="Drag the pin to the entrance"
+      close-label="Done"
+    />
+    <Button type="submit">Save</Button>
+  </form>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `[number, number] \| null` | — | Standalone `LocationField` only. `LocationFormField` takes `name` inside a vee-validate form |
+| `placeholder` | `string` | `material.location-field.placeholder` ("No location selected") | Shown while the value is `null` |
+| `dialog-title` | `string` | `material.location-field.dialog-title` ("Choose a location") | Dialog title, and the trailing button's `aria-label` |
+| `close-label` | `string` | `material.location-field.confirm` ("OK") | The dialog's button; on an empty field it also commits the pin's position (below) |
+| `map-class` | `string` | — | Class on the dialog's map |
+| `disabled`, `read-only` | `boolean` | — | The pin cannot be dragged |
+
+The rest are `TextField` props (`label`, `helper-text`, `required`, `name`, …).
+**Emits:** `update:modelValue` with `[number, number]`, on each drag end, and
+on OK when the field was empty.
+
+- **An empty value is an empty field.** With `null` the input is empty (the
+  placeholder shows) and there is no hover preview. The dialog still needs a
+  start, so its pin starts at `5.44087, 10.06843`; dragging the pin writes
+  its position, and OK on an empty field writes where the pin was last dragged
+  to (the start, if it was not). That holds even when the parent does not pass
+  the value back. Start from a real default when you have one.
+- The default copy is translated through the `material` namespace
+  (`material.location-field.placeholder`, `.dialog-title`, `.confirm`; `en`
+  and `fr`); pass `placeholder`, `dialog-title` or `close-label` to override
+  it.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { LocationField } from '@nxgt/material-vue/map';
+
+const position = ref<[number, number] | null>(null); // an empty field until OK or a drag
+</script>
+
+<template>
+  <LocationField v-model="position" label="Venue" placeholder="Pick the venue" />
+</template>
+```
+
+- `LocationFormField` shows the vee-validate error as helper text, like every
+  `*FormField` ([forms](forms.md#the-pair)).
+
+## Differences from `@nxgt/material/map`
+
+- **Importable on a server.** React's entry throws `window is not defined` when
+  imported without a DOM, because `react-leaflet` imports Leaflet statically.
+  This one does not; it still renders only in the browser.
+- **No `MinimapControl`.** React's is built on `@react-leaflet/core` internals,
+  which have no Vue counterpart. `Map` has no `showMinicardControl` prop.
+- **Markers take slots, not props**: `#tooltip`, `#popup` and `#icon` instead of
+  `tooltip`, `popup` and `icon`. An arbitrary marker is `LIcon`'s slot, so there
+  is no component-marker dependency. `reference` draws the pin; it does not make
+  the map fly to the marker.
+- **Positions are `[number, number]`**, not Leaflet's `LatLngExpression`:
+  `@vue-leaflet/vue-leaflet` does not accept a `{ lat, lng }` literal for its
+  `center` and `lat-lng` props.
+- **`useGeolocation`** wraps `@vueuse/core` (already a peer) rather than
+  `react-geolocated`, and returns `coords` rather than `react-geolocated`'s shape.

package/docs/guides/pdf.md

@@ -0,0 +1,312 @@
+# PDF documents
+
+This page covers `@nxgt/material-vue/pdf`: real PDF files built from plain
+data, downloaded in the browser or served from a Nuxt server route.
+
+```bash
+bun add react @react-pdf/renderer@^4.9   # optional peers, needed only by this entry
+```
+
+The entry's types refer to React's (the renderer is react-pdf): a TypeScript
+app with `skipLibCheck: false` also needs `@types/react` as a dev dependency.
+
+```ts
+// invoice-pdf.ts
+import { definePdfDocument, definePrintColumns, dataTable, header, keyValue, page } from '@nxgt/material-vue/pdf';
+
+export type Line = { item: string; amount: number };
+export type Invoice = { number: string; customer: string; issuedAt: string; lines: Line[] };
+
+const columns = definePrintColumns<Line>([
+  { key: 'item', label: 'Item', flex: 3 },
+  { key: 'amount', label: 'Amount', format: 'amount', total: 'sum' },
+]);
+
+export const invoicePdf = definePdfDocument((invoice: Invoice, language = 'en') => ({
+  meta: { title: `Invoice ${invoice.number}` },
+  language,
+  pages: [
+    page({
+      pageNumbers: true,
+      header: [header({ title: 'Invoice', reference: invoice.number, logoText: 'ACME' })],
+      body: [
+        keyValue([
+          { label: 'Customer', value: invoice.customer },
+          { label: 'Issued', value: { date: invoice.issuedAt } },
+        ]),
+        dataTable(columns, invoice.lines, { currency: 'EUR' }),
+      ],
+    }),
+  ],
+}));
+```
+
+`invoicePdf(invoice)` returns a `PdfDocument`: plain JSON, no functions, no
+`Date`, no bytes. Every function below renders it. Annotate the template's
+data parameter; extra parameters may take defaults (`language = 'en'`). The
+template's own signature is the type: do not pass it as a generic
+(`definePdfDocument<Invoice>(…)` does not compile). Left unannotated,
+the data parameter is `unknown`: reading a property of it fails to compile in
+the template (`'invoice' is of type 'unknown'`), so annotate it or narrow it
+first.
+
+## The model and its builders
+
+```ts
+type PdfDocument = {
+  version: 1;          // stamped by pdfDocument() and definePdfDocument()
+  meta?: { title?: string; author?: string; subject?: string; keywords?: string; creator?: string; producer?: string };
+  language?: string;   // built-in strings ('en', 'fr') and the PDF's language
+  locale?: string;     // how amounts, dates and numbers print; `language` by default
+  timeZone?: string;
+  theme?: PdfThemeOverrides;
+  pages: PdfPage[];    // each page shell starts a new page and flows over as many as it needs
+};
+```
+
+| Page option | Default | Effect |
+| --- | --- | --- |
+| `size` | `'A4'` | `'A3'`, `'A4'`, `'A5'`, `'LETTER'`, `'LEGAL'` or `[width, height]` in points |
+| `orientation` | `'portrait'` | `'landscape'` swaps width and height |
+| `margins` | `{ top: 21, right: 24, bottom: 21, left: 24 }` | Points: one number, or `top` / `right` / `bottom` / `left` / `x` / `y` |
+| `header`, `footer` | — | Nodes repeated at the top and bottom of every page |
+| `footerHeight` | `24` | Space kept at the bottom for the footer and page numbers |
+| `pageNumbers` | off | `true` prints "Page 2 of 5" centred; `{ align, format: 'page-of' \| 'page' }` |
+| `watermark` | — | A string, or `{ text, opacity (0.08), angle (35), color, fontSize (72) }` |
+
+| Builder | Node |
+| --- | --- |
+| `heading(text, level?)`, `text(content, { variant?, style? })` | a title (1–3); a paragraph, or runs `{ text, bold?, italic?, color?, href? }` |
+| `stack(children, opts?)`, `row(children, opts?)`, `section(title, children)` | layout |
+| `table({ columns, rows, footer?, … })`, `dataTable(columns, rows, opts?)` | a table of values; `dataTable` builds one from `definePrintColumns` |
+| `keyValue(items, opts?)`, `keyValueOf(fields, data, opts?)` | label and value pairs, in 1 or 2 columns |
+| `totals(rows)`, `metric({ label, value, hint?, delta? })`, `badge(text, color?)` | figures |
+| `header({ title, subtitle?, reference?, logo?, logoText?, qrDataUrl? })` | the title block |
+| `image(src, opts?)`, `link(href, text)` | a PNG or JPEG (URL or data URL); a link |
+| `spacer(points)`, `divider()`, `pageBreak()`, `pageNumber(opts?)` | spacing, a rule, a new page, "Page 2 of 5" where you put it |
+
+A cell or value is a `PrintValue`: text, a number, `{ amount, currency }`,
+`{ date }` or `{ number, style: 'percent' }`. It is formatted only when the
+document renders, with its `locale` and `timeZone`, so a document built on a
+server prints in the reader's locale.
+
+`definePrintColumns<T>()` returns its argument, typed so every `key` is
+checked against `T`; `dataTable(columns, rows, { currency, totalLabel,
+striped, repeatHeader, keepRowsWhole, emptyText, hideWhenEmpty })` and
+`keyValueOf(columns, row, { currency, columns, keepEmpty })` read rows
+through it.
+
+| Column field | Effect |
+| --- | --- |
+| `key`, or `id` + `accessor(row, index)` | the value: a property of the row, or a computed one |
+| `label` | header text (the label in `keyValueOf`) |
+| `format` | `'amount'`, `'date'`, `'number'`, `'percent'` (a fraction: `0.2` is `20%`), or `(value, row) => string` |
+| `currency` | ISO 4217 code for `'amount'`, or `(row) => code`; else the table's `currency` |
+| `total` | `'sum'` (finite numbers only; an `amount` column whose rows carry more than one currency gets an empty total), or `(rows) => number \| string \| null` |
+| `width`, `flex`, `align` | points or `'25%'`; share of the rest (1); `'right'` by default for figures |
+
+Without `totalLabel`, the totals row reads "Total" in the document's
+language. A colour is a theme name (`'primary'`, `'muted'`, …) or a CSS
+colour; `defaultPdfTheme` holds the defaults, and `theme.colors` overrides
+them. `theme.fonts` (`sans`, `serif`, `mono`) names the font families; the
+defaults (Helvetica, Times-Roman, Courier) are PDF standard fonts, which need
+no registration. `pdfDocument(options)` stamps `version` on a single document.
+
+The same column definitions feed your own layout too — an HTML table, a CSV —
+through the helpers underneath `dataTable`:
+
+```ts
+resolvePrintTable(columns, rows, options?): { columns; rows: PrintValue[][]; footer: PrintValue[][]; empty: boolean }
+resolvePrintFields(fields, row, options?): { label: string; value: PrintValue }[]
+toPrintValue(column, value, row, options?): PrintValue   // one cell
+formatPrintValue(value, { locale?, timeZone?, empty? }?): string // '—' when empty
+isEmptyPrintValue(value): boolean
+resolvePdfTheme(overrides?): PdfTheme          // defaultPdfTheme with your overrides
+resolvePdfColor(color, theme): string | undefined // a theme name or CSS colour to a colour
+```
+
+`PdfDocumentSource` is the type of `PdfDownloadButton`'s `document` prop.
+
+## In the browser: `usePdf` and `PdfDownloadButton`
+
+```vue
+<script setup lang="ts">
+import { PdfReader } from '@nxgt/material-vue/components';
+import { PdfDownloadButton, usePdf } from '@nxgt/material-vue/pdf';
+import { type Invoice, invoicePdf } from './invoice-pdf';
+
+const props = defineProps<{ invoice: Invoice }>();
+const { blob, loading, error, refresh } = usePdf(() => invoicePdf(props.invoice, 'fr'), {
+  fileName: props.invoice.number,
+});
+const onError = (cause: unknown) => console.error(cause); // or your toast
+</script>
+
+<template>
+  <PdfDownloadButton :document="() => invoicePdf(invoice, 'fr')" :file-name="invoice.number" @error="onError" />
+  <button v-if="error" @click="refresh">Try again</button>
+  <div v-else-if="blob" class="h-[600px]"><PdfReader :file="blob" :file-name="`${invoice.number}.pdf`" /></div>
+  <p v-else-if="loading">Rendering…</p>
+</template>
+```
+
+```ts
+function usePdf(
+  source: MaybeRefOrGetter<PdfDocument | null | undefined>,
+  options?: { fileName?: string; immediate?: boolean; custom?: Record<string, PdfCustomRenderer> },
+): {
+  blob: Readonly<Ref<Blob | null>>;
+  url: Readonly<Ref<string | null>>;   // object URL of blob, revoked when replaced or when the scope ends
+  loading: Readonly<Ref<boolean>>;
+  error: Readonly<Ref<Error | null>>;  // blob and url are null then
+  refresh: () => Promise<void>;
+  download: (fileName?: string) => Promise<void>; // reuses the rendered blob when it is current
+};
+```
+
+- **It does nothing on the server.** In SSR the refs stay empty; in a
+  component the first render starts once it is mounted, so hydration sees the
+  server's markup (`loading` false, no `url`). It renders again whenever
+  `source` changes (watched deeply). With `immediate: false` only `refresh()`
+  and `download()` render, and only in a browser.
+- The `fileName` option is read once, when `usePdf` is called: for a name
+  that follows changing props, pass it to `download(fileName)` instead.
+- A `null` source clears everything. A render overtaken by a newer document
+  is dropped.
+- `download()` saves the document `source` holds when you call it: after
+  `source` changed in the same tick, it waits for that render instead of
+  saving the previous file.
+
+`PdfDownloadButton` renders its `document` (a `PdfDocument`, or a function
+returning one or a promise of one, called on click) and saves it as
+`file-name` (`document.pdf` by default). It shows a loading state while it
+renders, takes `disabled`, emits `error`, and its default label is the
+library's translated "Download"; the default slot replaces it. Without an
+`@error` listener a failure is rethrown, so it reaches
+`app.config.errorHandler` (or the console) instead of vanishing — bind
+`@error` to show it yourself.
+
+**Storybook:** `Media & files/PdfDownloadButton` (a download, `@error`, and the
+rethrow a parent's `onErrorCaptured` sees) · **React:** none.
+
+`downloadPdf(doc | blob, { fileName })` and `openPdf(doc | blob, { fileName })`
+do the same from your own handler. `openPdf` opens the tab before rendering so
+a popup blocker lets it through, and downloads the file when the tab is
+blocked all the same. Object URLs are revoked after 60 seconds.
+
+## On a server: `pdfResponse`
+
+```ts
+// server/api/invoices/[id].pdf.get.ts (Nuxt / Nitro)
+import { pdfResponse } from '@nxgt/material-vue/pdf';
+import { invoicePdf } from '~~/shared/invoice-pdf'; // the template above, shared with the pages
+
+// getInvoice: your own function, from server/utils
+export default defineEventHandler(async (event) => {
+  const invoice = await getInvoice(getRouterParam(event, 'id')!);
+  return pdfResponse(invoicePdf(invoice, 'fr'), { fileName: invoice.number });
+});
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `fileName` | `string` | `'document.pdf'` | `Content-Disposition` name; `.pdf` is added when missing |
+| `disposition` | `'inline' \| 'attachment'` | `'attachment'` | `'inline'` shows it in the browser's viewer |
+| `headers` | `HeadersInit` | — | More headers; `Content-Type`, `Content-Length`, `Content-Disposition` are always the PDF's |
+| `custom` | `Record<string, PdfCustomRenderer>` | — | Renderers for `{ type: 'custom', name }` nodes |
+
+The file name is sent as ASCII and as UTF-8 (RFC 6266), so accents survive.
+For bytes that are not a response (an attachment, a file), or a stream that
+starts before the last page is written (without `Content-Length`):
+
+```ts
+import { writeFile } from 'node:fs/promises';
+import { contentDisposition, renderPdfBuffer, renderPdfStream } from '@nxgt/material-vue/pdf';
+
+await writeFile('INV-42.pdf', await renderPdfBuffer(doc)); // Uint8Array
+
+return new Response(await renderPdfStream(doc), {           // Web ReadableStream
+  headers: { 'Content-Type': 'application/pdf', 'Content-Disposition': contentDisposition('inline', 'report.pdf') },
+});
+```
+
+`contentDisposition(disposition: 'inline' | 'attachment', fileName: string): string`
+builds the same header `pdfResponse` sends, for a response of your own.
+
+| Function | Returns | Runs on |
+| --- | --- | --- |
+| `renderPdfBlob(doc, opts?)` | `Promise<Blob>` | browser, Node 18+, Bun |
+| `renderPdfBuffer(doc, opts?)` | `Promise<Uint8Array>` | browser, Node 18+, Bun |
+| `renderPdfStream(doc, opts?)` | `Promise<ReadableStream<Uint8Array>>` | Node 18+, Bun |
+| `pdfResponse(doc, opts?)` | `Promise<Response>` | Node 18+, Bun |
+| `downloadPdf`, `openPdf`, `usePdf`, `PdfDownloadButton` | — | browser |
+
+**Edge runtimes** (Cloudflare Workers, Vercel Edge, Deno Deploy) are not a
+supported target: the server functions are built and tested for Node 18+ and
+Bun. Deploy the Nitro server with a Node or Bun preset, or render in the
+browser ([troubleshooting](../troubleshooting.md#pdf-rendering-fails-on-an-edge-runtime)).
+
+## Shared templates with `@nxgt/material`
+
+The model, the builders and the renderer are the same code in
+`@nxgt/material/print` (React) and here. A template written against one
+compiles against the other by changing its import, and renders the same
+pages; only the default `meta.creator` names the library. A document is
+plain data, so one built by a React app's API renders in a Vue app, and back:
+
+```ts
+const doc: PdfDocument = await $fetch(`/api/invoices/${id}/document`); // built by either library
+await downloadPdf(doc, { fileName: id });
+```
+
+## Built-in strings
+
+"Page 2 of 5", the table's "Total" and the empty-table text come from this
+library's `material.print.*` strings, in English and French, picked by the
+document's `language` (`'fr-CA'` reads `fr`; another language prints
+English). Your app's current language does not reach a document: pass it in,
+as `invoicePdf(invoice, language)` does above.
+
+## Fonts on a fully inlined server
+
+The PDFs use the fourteen standard PDF fonts, loaded by pdfkit at runtime from
+a specifier no bundler resolves. Nitro keeps `@react-pdf/renderer` external by
+default, where that works. When the runtime image has **no `node_modules`**
+(the server inlined into one artifact), bundle the fonts in:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@nxgt/material-vue/nuxt'],
+  nxgtMaterial: { pdf: { bundleStandardFonts: true } },
+});
+```
+
+```ts
+// vite.config.ts (a Vite SSR server without Nuxt)
+import { pdfkitStandardFonts } from '@nxgt/material-vue/vite';
+
+export default defineConfig({
+  plugins: [pdfkitStandardFonts()],
+  ssr: { noExternal: ['@nxgt/material-vue', '@nxgt/material-core'] },
+});
+```
+
+`@nxgt/material-core`, which the library's built code imports by name, is
+bundled with it: leave it out and the server fails at boot with
+[`Cannot find package '@nxgt/material-core'`](../troubleshooting.md#cannot-find-package-nxgtmaterial-core).
+
+The plugin fails the build if a reference survives, rather than the first
+request ([troubleshooting](../troubleshooting.md#cannot-find-module-standard-fontshelvetica)).
+
+## Errors
+
+Rendering without `react` or `@react-pdf/renderer` throws a
+`PdfPeerMissingError` whose message is the install command (importing and
+building documents still work). A document with an unknown node `type`, a
+`version` other than `1`, or a `custom` node with no renderer throws a
+`[pdf] …` error before any page is drawn. Render functions reject with them,
+`usePdf` returns them as `error`, and `PdfDownloadButton` emits them (or
+rethrows them when nothing listens to `@error`); each
+message is in [troubleshooting](../troubleshooting.md#pdf-documents). The Nuxt
+module does not auto-import this entry: import from `@nxgt/material-vue/pdf`.