@nxgt/material 3.5.0 → 3.7.0

package/docs/guides/drawing.md

@@ -0,0 +1,499 @@
+# Drawing
+
+`@nxgt/material/draw` draws diagrams, badges, charts of your own and
+illustrations from **code**: a scene of plain data, or JSX primitives, becomes
+accessible SVG that follows the theme, is safe under a strict Content Security
+Policy and is the same on the server and in the browser. The same scene also
+becomes a standalone SVG string, a PNG, a PDF block, a hand-drawn sketch or an
+animation.
+
+This page is the React side: how to use it in an app. The scene model, the
+path builder, arrows, text metrics, paints and the exact options of each
+function are in the [reference of `@nxgt/material-core`](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md);
+the component's props are in [Rich widgets](../components/rich-widgets.md#drawing).
+Nothing is repeated between them: this guide links to a section when the detail
+lives there.
+
+- [Set up](#set-up)
+- [A first drawing](#a-first-drawing)
+- [On a server](#on-a-server)
+- [Content Security Policy](#content-security-policy)
+- [Colours: roles and tones](#colours-roles-and-tones)
+- [Accessibility](#accessibility)
+- [Events and focus](#events-and-focus)
+- [Shapes and layout](#shapes-and-layout)
+- [Sketch](#sketch)
+- [Animate](#animate)
+- [PNG](#png)
+- [PDF](#pdf)
+- [E-mail](#e-mail)
+- [Troubleshooting](#troubleshooting)
+
+## Set up
+
+Four entries, each only loaded by the apps that use it:
+
+| Import | For |
+| --- | --- |
+| `@nxgt/material/draw` | `Drawing`, the JSX primitives, the builders (`scene`, `rect`, `path`, `text`...), `toSVG`, the shapes and the layout helpers |
+| `@nxgt/material/draw/sketch` | the hand-drawn style: `Sketch`, `sketch` |
+| `@nxgt/material/draw/animate` | `drawOn`, `appear`, `useDrawingControls`, `MorphDrawing`, `useSceneMorph`, `morphScenes` |
+| `@nxgt/material/draw/png` | `drawingToPng`, `downloadDrawingPng` |
+
+`Drawing` is not in `@nxgt/material/components` nor in the main entry: a page
+that draws nothing pays nothing. The role colours and the animations are
+classes of `@nxgt/material/styles.css`, which your app already imports for the
+rest of the library (see [Getting started](../getting-started.md)); without it
+a drawing is drawn in black.
+
+`Drawing`, `Sketch` and the animation hooks use React hooks, and the built
+entries (`dist/draw.js`, `dist/draw-sketch.js`, `dist/draw-animate.js`) carry
+no `'use client'` directive: render them from a file of yours that starts with
+`'use client'`. The builders, `sketch`, `drawOn`, `appear`, `morphScenes` and
+`toSVG` are plain functions and run anywhere, a Server Component included.
+
+## A first drawing
+
+JSX, for a drawing that belongs to one component:
+
+```tsx
+'use client';
+
+import { Circle, Drawing, Rect, Text } from '@nxgt/material/draw';
+
+export function ReleaseStatus() {
+	return (
+		<Drawing w={200} h={80} title="Release status: shipped">
+			<Rect x={0} y={0} w={200} h={80} r={16} fill="primary-container" />
+			<Circle cx={36} cy={40} r={14} fill="primary" />
+			<Text x={64} y={46} fill="on-primary-container">Shipped</Text>
+		</Drawing>
+	);
+}
+```
+
+A scene, for a drawing you compute, store or send as JSON:
+
+```tsx
+'use client';
+
+import { Drawing, path, rect, scene, text, tone } from '@nxgt/material/draw';
+
+const flow = scene({ w: 240, h: 120 }, [
+	rect({ x: 8, y: 8, w: 224, h: 104, r: 16, fill: 'primary-container', stroke: 'outline' }),
+	path((p) => p.moveTo(24, 90).curveTo(60, 20, 120, 20, 200, 60), {
+		stroke: tone('success'),
+		strokeWidth: 3,
+		arrow: { end: 'triangle' },
+	}),
+	text('Shipped', { x: 120, y: 64, anchor: 'middle', size: 18, weight: 600, fill: 'on-primary-container' }),
+]);
+
+export const Flow = () => <Drawing scene={flow} title="Release flow" />;
+```
+
+The `<svg>` scales to its container (`max-width: 100%`): size it with
+`className`. Keep a scene in a module constant or a `useMemo`: a new object on
+every render compiles again.
+
+## On a server
+
+A scene is JSON, so a loader can build it and the component draws it, on the
+server and again, identically, in the browser (no hydration mismatch: ids are
+derived from `useId`, numbers are rounded the same way, wrapped text breaks with
+Inter's metrics and is refined by the browser only after mount):
+
+```tsx
+// routes/report.tsx (React Router)
+import { Drawing, rect, scene } from '@nxgt/material/draw';
+import { useLoaderData } from 'react-router';
+
+export async function loader() {
+	const sales = await loadSales(); // [{ month, total }]
+	return {
+		chart: scene({ w: 300, h: 100 }, sales.map((s, i) =>
+			rect({ x: i * 24, y: 100 - s.total, w: 20, h: s.total, fill: 'primary' }),
+		)),
+	};
+}
+
+export default function Report() {
+	const { chart } = useLoaderData<typeof loader>();
+	return <Drawing scene={chart} title="Sales by month" />;
+}
+```
+
+A resource route can send the same scene as a file, with no React:
+
+```ts
+import { toSVG } from '@nxgt/material/draw';
+
+export async function loader() {
+	const svg = toSVG(await buildBadge(), { standalone: true, title: 'Build passing', theme: 'light' });
+	return new Response(svg, { headers: { 'Content-Type': 'image/svg+xml' } });
+}
+```
+
+Never use `Math.random()`, the clock or a measurement while building a scene
+that is drawn on both sides: they differ. A seed makes randomness the same
+([Sketch](#sketch) takes one).
+
+## Content Security Policy
+
+Nothing a drawing renders needs `style-src-attr 'unsafe-inline'`:
+
+- no `style` attribute anywhere: geometry, colour and opacity are presentation
+  attributes, role colours and animations are classes;
+- no `<style>` element and no `insertRule` on the React path (a `<style>` exists
+  only when you ask `toSVG` for `standalone` and `embedStyles`, for a file);
+- `assertSafeDrawing` runs on every compile and refuses `on*` attributes, `style`,
+  `url()` to anything but a local `#id`, an `href` that is not `http(s)`,
+  relative or a `data:` PNG/JPEG/GIF/WebP, and non-finite numbers. A scene loaded
+  from JSON is checked before it is drawn;
+- an `image` with an `http(s)` URL is a request your page makes: keep `img-src`
+  in your policy.
+
+Check a scene you did not write yourself:
+
+```ts
+import { assertSafeDrawing } from '@nxgt/material/draw';
+
+try {
+	assertSafeDrawing(JSON.parse(untrustedJson));
+} catch (error) {
+	reject(error); // "Unsafe drawing at <image>: href must be http(s), relative or data:image …"
+}
+```
+
+The exact rules are in the [reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#safety-csp);
+the other components' CSP needs are in the [CSP guide](csp.md).
+
+## Colours: roles and tones
+
+A fill, a stroke or a gradient stop is a **role**, a **tone** or a free colour.
+
+```tsx
+<Drawing w={240} h={60} title="Three kinds of colour">
+	<Rect x={0} y={0} w={70} h={60} r={12} fill="tertiary-container" stroke="outline" />
+	<Rect x={85} y={0} w={70} h={60} r={12} fill={tone('success', 'container')} />
+	<Rect x={170} y={0} w={70} h={60} r={12} fill="#7c4dff" />
+</Drawing>
+```
+
+- **Roles** follow Material 3's names and read the theme through the classes of
+  `styles.css`: `primary`, `on-primary`, `primary-container`,
+  `on-primary-container` (the same four for `secondary`, `tertiary` and `error`),
+  `surface`, `on-surface`, `surface-container`, `on-surface-variant`, `outline`,
+  `outline-variant`, `success`, `info`, `warning`, `neutral`. `ROLES` lists them
+  and `ROLE_VARS` gives each one's CSS variable (`on-primary-container` is
+  `--primary-text`, `outline` is `--muted-foreground`).
+  They follow light and dark, scoped themes and a retheme with no re-render.
+- **Tones**: `tone('success')`, `tone('success', 'container')` (variants `base`,
+  `text`, `on`, `container`) name a theme tone or an app tone of your own, the
+  ones the [tones channel](theming.md) defines. One element can use one app tone;
+  a fill in one app tone and a stroke in another throws, so put them on two
+  nodes in a group.
+- **Free colours** (`#hex`, `rgb()`, `hsl()`, `oklch()`...) are written as they
+  are: they do not follow the theme.
+
+Out of React the roles have no stylesheet, so `toSVG` writes colours itself:
+`colors: 'literal'` (the default) uses the hex of `DRAW_PALETTE.light` or `.dark`
+(`theme`) and `palette: { primary: '#0a7' }` overrides tokens;
+`colors: 'vars'` writes `var(--primary, #485096)`, which follows the page's theme
+when the SVG is inline in it.
+
+```ts
+import { DRAW_PALETTE, toSVG } from '@nxgt/material/draw';
+
+toSVG(art, { theme: 'dark' }); // literal dark hex
+toSVG(art, { colors: 'vars' }); // inline in a themed page
+toSVG(art, { palette: { ...DRAW_PALETTE.light, primary: '#0a7c59' } });
+```
+
+The full mapping and the palette are in the
+[reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#colours).
+
+## Accessibility
+
+A `Drawing` takes `title` **or** `decorative`; the type refuses neither.
+
+```tsx
+<Drawing scene={chart} title="Sales by month, rising" />      {/* role="img" aria-label */}
+<Drawing scene={flourish} decorative />                        {/* aria-hidden */}
+```
+
+- The name is an `aria-label`, never a `<title>` element: React 19 would hoist a
+  `<title>` into the document's head.
+- A drawing with an interactive node is `role="group"`, because an image cannot
+  hold focusable children; a decorative one cannot hold an interactive node and
+  throws `A decorative drawing has an interactive node: give the Drawing a title instead`.
+- Write the title as what the picture says, not "chart": it is what a reader
+  gets in place of the picture. Describe long data in the page next to it.
+- Do not rely on colour alone: `error` and `success` read the same to someone who
+  cannot tell red from green, so add a shape or a label.
+- Under `prefers-reduced-motion` the animations do not run (see [Animate](#animate)).
+
+## Events and focus
+
+A node is interactive when it has a handler or `interactive: true`. It then
+becomes focusable (`tabindex="0"`), is a `role="button"` when it has `onClick`
+(Enter and Space click it) and shows a focus ring on `:focus-visible`. Give it a
+`label`: that is its accessible name.
+
+In scene mode, events go by node `id`:
+
+```tsx
+'use client';
+
+import { Drawing, rect, scene } from '@nxgt/material/draw';
+import { useState } from 'react';
+
+const board = scene({ w: 220, h: 70 }, [
+	rect({ id: 'todo', label: 'To do', interactive: true, x: 0, y: 0, w: 100, h: 70, r: 12, fill: 'surface-container', stroke: 'outline' }),
+	rect({ id: 'done', label: 'Done', interactive: true, x: 120, y: 0, w: 100, h: 70, r: 12, fill: 'success' }),
+]);
+
+export function Board() {
+	const [picked, setPicked] = useState('');
+	return (
+		<>
+			<Drawing
+				scene={board}
+				title="Board columns"
+				handlers={{ todo: { onPointerEnter: () => setPicked('todo') } }}
+				onNodeClick={(id) => setPicked(id)}
+			/>
+			<p aria-live="polite">{picked}</p>
+		</>
+	);
+}
+```
+
+In JSX the primitives take `onClick`, `onPointerEnter`, `onPointerLeave`,
+`onPointerDown`, `onPointerUp`, `onFocus`, `onBlur` and `onKeyDown`; set
+`interactive` on a server-rendered `Drawing` so the first markup already says
+it is a group. There is no drag: drawings are for showing, not for editing.
+
+## Shapes and layout
+
+Material 3 Expressive's shapes are nodes (`shape('cookie-9', { x, y, w, h, fill })`
+or `m3-cookie-9`; `SHAPE_NAMES` lists them), and `bbox`, `stack`, `grid`, `align`
+and `distribute` place nodes by their real boxes. Both come from
+`@nxgt/material/draw`, by name: a bundler keeps only what you import.
+
+```tsx
+import { Drawing, Path, shape } from '@nxgt/material/draw';
+
+<Drawing w={120} h={120} title="A cookie">
+	<Path node={shape('cookie-9', { x: 10, y: 10, w: 100, h: 100, fill: 'tertiary' })} />
+</Drawing>;
+```
+
+**A name clash.** The builders `text` and `image` of `/draw` have the names of the
+PDF blocks in `@nxgt/material/print`. A file that uses both renames one:
+
+```tsx
+import { text as drawText, rect, scene } from '@nxgt/material/draw';
+import { drawing, page, pdfDocument, text } from '@nxgt/material/print';
+
+const badge = scene({ w: 120, h: 40 }, [
+	rect({ x: 0, y: 0, w: 120, h: 40, r: 20, fill: 'primary' }),
+	drawText('v3', { x: 60, y: 26, anchor: 'middle', fill: 'on-primary' }),
+]);
+
+pdfDocument({ pages: [page({ body: [text('Release 3'), drawing(badge, { width: 120 })] })] });
+```
+
+The units of shapes, `morph` and the layout helpers are in the
+[reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#shapes-and-morphs-nxgtmaterial-coredrawshapes).
+
+## Sketch
+
+`Sketch` draws what is inside it by hand: strokes in two wobbling passes, loose
+ellipses, hatched fills. The wobble is seeded, so the server and the browser draw
+the same lines.
+
+```tsx
+'use client';
+
+import { Drawing, Rect, Text } from '@nxgt/material/draw';
+import { Sketch } from '@nxgt/material/draw/sketch';
+
+export const Wireframe = () => (
+	<Sketch seed={7} roughness={1.2} fill="cross-hatch">
+		<Drawing w={200} h={80} title="A sketched button">
+			<Rect id="go" label="Go" x={10} y={10} w={180} h={60} r={12} fill="primary" stroke="primary" onClick={go} />
+			<Text x={100} y={46} anchor="middle" fill="on-primary">Go</Text>
+		</Drawing>
+	</Sketch>
+);
+```
+
+On plain data, `sketch(scene, options)` returns a scene, which `toSVG`, a PNG or a
+PDF draws like any other. Ids, labels, events and the focus ring survive; text and
+images are left as they are.
+
+```ts
+import { toSVG } from '@nxgt/material/draw';
+import { sketch } from '@nxgt/material/draw/sketch';
+
+const rough = toSVG(sketch(flow, { seed: 3, fill: 'hachure' }), { title: 'Release flow' });
+```
+
+Options and the hatch maths: [reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#sketchy-style-nxgtmaterial-coredrawsketch).
+
+## Animate
+
+Entry animations are data: `drawOn(scene)` traces the strokes one after the next
+and fades the fills in, `appear(scene)` fades and grows the nodes. They only add
+class names that `styles.css` animates, so a server renders them and the CSP
+stays clean. `useDrawingControls(ref)` replays them, and `MorphDrawing` springs
+one scene into another.
+
+```tsx
+'use client';
+
+import { Drawing, scene, shape } from '@nxgt/material/draw';
+import { drawOn, MorphDrawing, useDrawingControls } from '@nxgt/material/draw/animate';
+import { useRef, useState } from 'react';
+
+const flow = drawOn(flowScene, { dur: 'l' }); // outside the component: a stable scene
+const cookie = scene({ w: 120, h: 120 }, [shape('cookie-9', { id: 'blob', x: 10, y: 10, w: 100, h: 100, fill: 'primary-container' })]);
+const heart = scene({ w: 120, h: 120 }, [shape('heart', { id: 'blob', x: 10, y: 10, w: 100, h: 100, fill: 'tertiary-container' })]);
+
+export function Demo() {
+	const ref = useRef<SVGSVGElement>(null);
+	const { replay } = useDrawingControls(ref);
+	const [liked, setLiked] = useState(false);
+	return (
+		<>
+			<Drawing ref={ref} scene={flow} title="Release flow" />
+			<button type="button" onClick={replay}>Replay</button>
+			<button type="button" aria-pressed={liked} onClick={() => setLiked(!liked)}>
+				<MorphDrawing from={cookie} to={heart} active={liked} title={liked ? 'Liked' : 'Not liked'} />
+			</button>
+		</>
+	);
+}
+```
+
+- Under `prefers-reduced-motion` nothing moves and the last frame shows at once.
+- The delay between two nodes is `--nxgt-draw-stagger` (60 ms a step): set it on
+  the drawing or an ancestor.
+- `MorphDrawing` morphs the closed paths both scenes share by `id`; every other
+  node switches to the target at once. `useSceneMorph` cross-fades them instead.
+- A standalone `toSVG` file has no stylesheet, so its classes do nothing and the
+  drawing simply shows (`embedStyles: true` adds a small one).
+
+Options of `drawOn`, `appear` and `morphScenes`:
+[reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#animation-nxgtmaterial-coredrawanimate).
+
+## PNG
+
+`drawingToPng` makes a PNG in the browser from a scene or from a live `<svg>`, with
+the colours the page shows (roles are resolved through the theme, so a dark page
+gives a dark PNG; `colorsFrom` picks another element's theme).
+
+```tsx
+'use client';
+
+import { Drawing } from '@nxgt/material/draw';
+import { downloadDrawingPng, drawingToPng } from '@nxgt/material/draw/png';
+import { useRef } from 'react';
+
+export function Exportable() {
+	const ref = useRef<SVGSVGElement>(null);
+	return (
+		<>
+			<Drawing ref={ref} scene={flow} title="Release flow" />
+			<button type="button" onClick={() => downloadDrawingPng(ref.current ?? flow, 'release-flow', { scale: 2 })}>
+				Save as PNG
+			</button>
+			<button type="button" onClick={async () => upload(await drawingToPng(flow, { background: 'var(--background)' }))}>
+				Upload
+			</button>
+		</>
+	);
+}
+```
+
+- `scale` is pixels per drawing unit (2 by default); the PNG is transparent unless
+  you pass a `background`.
+- An `image` with a URL is fetched and inlined first. A cross-origin image needs
+  CORS headers, or a `data:` URL (the error names the URL; see
+  [the troubleshooting entry](../troubleshooting.md#drawingtopng-cannot-read-the-image-url-reason)).
+- Text uses the system fallback font: the page's web fonts do not reach an SVG
+  drawn as an image, so a line may be a little wider or narrower than on the page.
+- From a live `<svg>`, what the stylesheet hides stays hidden: the focus rings of
+  interactive nodes do not show in the image.
+- Browser only; the entry imports on a server and touches nothing until you call it.
+
+## PDF
+
+A scene prints as vectors in a PDF document made with `@nxgt/material/print`:
+`drawing(scene, { width?, align? })` in a document written as data, or
+`PrintDrawing` inside `PrintDocument`. The engine is the same compile as the
+screen; the PDF is not a browser, so colour roles take the document theme where it
+has them (`primary`, `secondary`, `success`, `error`) and the light palette
+otherwise, text is Helvetica, patterns print as a solid colour and a mask is
+dropped with a warning. The table of what differs is in the
+[reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#in-a-pdf-document-drawing-in-nxgtmaterial-corepdfmodel),
+and the document side in the [printing guide](printing.md#drawings-in-a-document).
+
+```tsx
+import { drawing, page, PrintDocument, PrintDrawing, pdfDocument } from '@nxgt/material/print';
+
+const doc = pdfDocument({ pages: [page({ body: [drawing(flow, { width: 400, align: 'center' })] })] });
+
+const Report = () => (
+	<PrintDocument>
+		<PrintDrawing scene={flow} width={400} align="center" />
+	</PrintDocument>
+);
+```
+
+`/print` also exports `text` and `image`: see the [name clash](#shapes-and-layout).
+
+## E-mail
+
+An e-mail client is neither a browser nor a PDF viewer, and many (Gmail and
+Outlook among them) do not show SVG. There is no server-side raster in the
+library: choose by what your readers' clients do.
+
+- **Clients that render SVG** (and a web view of the message): send
+  `toSVG(scene, { standalone: true, theme: 'light' })` as an attachment or an
+  `<img src>` URL. Its colours are literal hex, so it needs no stylesheet and no
+  CSS variable, and it has no `style` attribute.
+- **Everyone else**: make a PNG in a browser (an admin page, a preview button)
+  with `drawingToPng(scene, { scale: 2, background: '#ffffff' })`, store it, and
+  point an `<img src="https://…/chart.png" width="480" alt="Sales by month">` at
+  it. Pass a `background`: a transparent PNG shows the reader's own colours behind it.
+
+```ts
+import { toSVG } from '@nxgt/material/draw';
+
+const attachment = {
+	filename: 'sales.svg',
+	contentType: 'image/svg+xml',
+	content: toSVG(chart, { standalone: true, title: 'Sales by month', theme: 'light' }),
+};
+```
+
+Give the `<img>` an `alt` that says what the picture says: it is all a client
+that blocks images shows.
+
+## Troubleshooting
+
+Every message a drawing throws is listed with its cause and fix:
+
+- [Drawing in the troubleshooting page](../troubleshooting.md#drawing): a decorative drawing with an
+  interactive node, `Unsafe drawing at <tag>`, an unknown shape name, a PNG that
+  fails on an image, a drawing with no colours, a Server Component that imports
+  `Drawing`.
+- The engine's own errors (`Invalid colour`, `Invalid path data`, `Tones "a" and
+  "b" meet on one element`, `[pdf] A drawing mask is not supported`) are in the
+  [core troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#drawing).
+
+Text that wraps one character differently from the page is not an error: widths
+are Inter's until the browser re-measures after mount (`exactText={false}` keeps
+the metrics' breaks).

package/docs/guides/printing.md

@@ -1016,6 +1016,7 @@ it:
 | `badge` | `badge(text, color?)` | A pill |
 | `header` | `header({ title, subtitle?, reference?, referencePrefix?, logo?, logoText?, qrDataUrl? })` | The title block, as `PrintHeader`; `referencePrefix` is printed before `reference`, `'#'` by default |
 | `image` | `image(src, { width?, height?, fit? })` | A PNG or JPEG, from a URL or a data URL |
+| `drawing` | `drawing(scene, { width?, align? })` | A [vector drawing](#drawings-in-a-document) (a scene from `@nxgt/material-core/draw`), as vectors |
 | `link` | `link(href, text)` | A link |
 | `spacer`, `divider`, `pageBreak` | `spacer(points)`, `divider()`, `pageBreak()` | Space, a rule, a new page |
 | `pageNumber` | `pageNumber({ format?, align?, scope? })` | "Page 2 of 5", where you put it (in a `footer`, say); `scope: 'group'` counts within the page group, see [Page groups](#page-groups-numbering-that-restarts) |
@@ -1042,6 +1043,52 @@ table({
 // locale 'fr-FR': 1 avr. 2026 · 1 234,50 €     locale 'en-US': Apr 1, 2026 · €1,234.50
 ```
 
+### Drawings in a document
+
+A drawing is a scene (plain data from the builders of `@nxgt/material/draw`). `drawing(scene, { width?, align? })` puts it in a
+document as vectors, and `PrintDrawing` does the same inside `PrintDocument`:
+
+```tsx
+import { circle, rect, scene, text as drawText } from '@nxgt/material/draw';
+import { drawing, page, PrintDocument, PrintDrawing, pdfDocument } from '@nxgt/material/print';
+
+const art = scene({ w: 240, h: 120 }, [
+  rect({ x: 8, y: 8, w: 224, h: 104, r: 16, fill: 'primary-container' }),
+  circle({ cx: 48, cy: 60, r: 22, fill: 'success' }),
+  drawText('Shipped', { x: 120, y: 66, anchor: 'middle', size: 18, weight: 600 }),
+]);
+
+// As data:
+const doc = pdfDocument({ pages: [page({ body: [drawing(art, { width: 400, align: 'center' })] })] });
+
+// As components:
+export const Report = () => (
+  <PrintDocument title="Report">
+    <PrintDrawing scene={art} width={400} align="center" />
+  </PrintDocument>
+);
+```
+
+`width` is in points and defaults to the scene's own width; the height keeps its
+aspect. `@nxgt/material/print` and `@nxgt/material/draw` both export `text` and `image`: import the
+drawing's as `drawText` (and `image` as `drawImage`).
+
+What changes in a PDF:
+
+- **Colours.** A role takes the document theme's colour where it has one
+  (`primary`, `secondary`, `success`, `error`), otherwise the light palette's.
+- **Text is Helvetica**, not Inter (the theme's `fonts` apply), and `maxWidth` wraps
+  with Helvetica's widths. Bold is printed twice a hair apart and italic is a
+  skew, so selecting bold text copies it twice.
+- **A `pattern` or `hatch`** prints as a solid of its colour, and **a `mask` is
+  dropped** with a warning (`console.warn`, or the `warn` render option).
+- **An `image`** is placed over the drawing and follows the `translate` and
+  `scale` of its groups; it sits above everything else, and one under a rotation
+  is dropped with a warning.
+
+The full table is in the [drawing reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#in-a-pdf-document-drawing-in-nxgtmaterial-corepdfmodel).
+Vue's `/pdf` does not re-export `drawing` yet (tracked in the Vue drawing issue); import it from `@nxgt/material-core/pdf/model` meanwhile.
+
 ### Page groups: numbering that restarts
 
 A document made of one entry of `pages` per person (a report card per