@nxgt/material 2.1.0 → 2.2.0

package/docs/components/media-and-files.md

@@ -0,0 +1,901 @@
+# Media & files
+
+Uploaders, file lists, images, galleries, PDF and media players — plus the two
+browser-only entries that live outside the barrel: PDF printing
+(`@nxgt/material/print`) and Leaflet maps (`@nxgt/material/map`). Every upload
+field has a form wrapper; see the [forms guide](../guides/forms.md) for wiring
+them into a form.
+
+| | Component | What it does |
+| --- | --- | --- |
+| <img src="../previews/media-files-s3uploadfield.webp" width="96" alt=""> | [S3UploadField, NetworkUploadField](#s3uploadfield-networkuploadfield) | Drag-and-drop uploader with progress, retry, previews and size / count limits |
+| <img src="../previews/media-files-uploadfield.webp" width="96" alt=""> | [UploadField](#uploadfield) | Labelled file input showing the chosen file's name |
+| <img src="../previews/media-files-filelist.webp" width="96" alt=""> | [FileList](#filelist) | File list with type icons, size, download and remove |
+| | [FilesFormField](#filesformfield) | Free-solo autocomplete of file URLs, with image thumbnails |
+| <img src="../previews/media-files-imagefield.webp" width="96" alt=""> | [ImageField](#imagefield) | Single image upload with preview and progress |
+| <img src="../previews/media-files-imagecropper.webp" width="96" alt=""> | [ImageCropper](#imagecropper) | Crop with zoom, rotation, aspect presets and a round shape |
+| <img src="../previews/media-files-gallery.webp" width="96" alt=""> | [Gallery, LightboxGallery, MiniGallery](#gallery-lightboxgallery-minigallery) | Image / video gallery with a lightbox and selection |
+| <img src="../previews/media-files-carousel.webp" width="96" alt=""> | [Carousel](#carousel) | Embla carousel with keyboard navigation |
+| <img src="../previews/media-files-pdfreader.webp" width="96" alt=""> | [PdfReader](#pdfreader) | Browser-only PDF reader with zoom, search, thumbnails and print |
+| <img src="../previews/media-files-stxplayer.webp" width="96" alt=""> | [StxPlayer](#stxplayer) | Video / audio player with a queue, captions and mini layout |
+| | [VideoPlayer](#videoplayer) | Deprecated alias of `StxPlayer` |
+| | [Print components](#print-components) | `PrintDocument` page shell and `@react-pdf/renderer` building blocks for PDF documents, and `downloadPdf`, `openPdf`, `usePdfFile` and `pdfResponse` to get the file |
+| <img src="../previews/media-files-map.webp" width="96" alt=""> | [Map](#map) | Leaflet map, markers and a location field (`@nxgt/material/map`) |
+
+## S3UploadField, NetworkUploadField
+
+![S3UploadField](../previews/media-files-s3uploadfield.webp)
+![NetworkUploadField](../previews/media-files-networkuploadfield.webp)
+
+Drag-and-drop uploader with progress, retry, previews and size / count limits. The S3 variant uploads through a presigned PUT.
+
+```tsx
+import { useState } from 'react';
+import { NetworkUploadField, S3UploadField } from '@nxgt/material/components';
+
+function Attachments() {
+  const [value, setValue] = useState<string[]>([]);
+  return (
+    <S3UploadField
+      mode="multiple"
+      label="Attachments"
+      helperText="PDF or images, up to 5 MB each"
+      accept="application/pdf,image/*"
+      maxSize={5 * 1024 * 1024}
+      maxFiles={5}
+      value={value}
+      onValueChange={setValue}
+      getPresignedUrl={async (file) => {
+        const res = await fetch(`/api/uploads?name=${encodeURIComponent(file.name)}`);
+        return res.json(); // { uploadUrl, publicUrl, headers? }
+      }}
+    />
+  );
+}
+
+// Your own transport: resolve with the stored value (URL, key or id).
+<NetworkUploadField
+  mode="single"
+  label="Contract"
+  onUpload={async (file, onProgress) => {
+    onProgress?.(100);
+    return `https://files.example.com/${file.name}`;
+  }}
+/>;
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'multiple'` | — (required) | `value` is a `string` or a `string[]` |
+| `onUpload` | `(file, onProgress?) => Promise<string>` | — | `NetworkUploadField` only; the resolved string becomes the value |
+| `getPresignedUrl` | `(file) => Promise<{ uploadUrl, publicUrl, headers? }>` | — | `S3UploadField` only; PUTs the file to `uploadUrl`, stores `publicUrl` |
+| `accept` | `string` | — | file input `accept`, also shown under the drop zone |
+| `maxSize` | `number` (bytes) | — | larger files are rejected before upload |
+| `maxFiles` | `number` | — | `mode="multiple"` only; the drop zone is disabled once reached |
+| `onRemove` | `(value) => void \| Promise<void>` | — | called when a committed file is removed (delete it server-side here) |
+| `resolveUrl` | `(value) => string \| null \| undefined` | — | turns a stored key into an `<img src>` so saved images preview |
+
+The field is a `group` named by its `label`. The drop zone is a `button`, which
+may not carry `aria-invalid`: with `error` it is described by `helperText`, or
+without one by a visually hidden "This value is not valid."
+(`material.zod.default`, translated), and outlined through `data-invalid`.
+Once a file hides the drop zone (`mode="single"` with a value), or it is
+disabled (`maxFiles` reached, or `disabled`), the group carries that
+description instead, so the error is still said: with `error` and that
+`helperText`, `getByRole('group', { name: 'Contract' })` has
+`toHaveAccessibleDescription('Add the signed contract.')`. The label names the
+group, so to set files in a test, reach the input through it:
+`getByRole('group', { name: 'Contract' }).locator('input[type=file]')`.
+
+**Form wrapper:** `S3UploadFormField`, `NetworkUploadFormField` — `control` and `name`, see
+[forms](../guides/forms.md).
+**Storybook:** `Media & files/S3UploadField`, `Media & files/NetworkUploadField` · **Vue:** `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField`
+
+---
+
+## UploadField
+
+![UploadField](../previews/media-files-uploadfield.webp)
+
+Labelled file input showing the chosen file's name.
+
+```tsx
+import { File as FileIcon } from 'lucide-react';
+import { useState } from 'react';
+import { UploadField } from '@nxgt/material/components';
+
+function Contract() {
+  const [file, setFile] = useState<File>();
+  return (
+    <UploadField
+      label="Signed contract"
+      placeholder="Choose a file"
+      helperText="PDF, up to 10 MB"
+      accept="application/pdf"
+      leading={<FileIcon />}
+      trailing="Browse"
+      value={file?.name}
+      onChange={(event) => setFile(event.target.files?.[0])}
+    />
+  );
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | — | shown above, with `*` when `required` |
+| `required` | `boolean` | — | the asterisk, `required` on the file input, and a "required" description on the field group (below) |
+| `value` | `string` | — | text shown in the field (the file name); the component keeps no file state |
+| `onChange` | `ChangeEventHandler<HTMLInputElement>` | — | the native file input's change event |
+| `leading` / `trailing` | `ReactNode` | — | adornments; `trailing` is rendered as the browse button |
+| `error` | `boolean` | — | red outline; `helperText` becomes the error |
+
+The box is tinted while it shows a `value`, and not while it shows the
+`placeholder`.
+
+It no more than wraps an `<input type="file">`: nothing is uploaded. For uploads
+with progress use [NetworkUploadField](#s3uploadfield-networkuploadfield).
+
+The file input is visually hidden, not `hidden`: with `required`, a submit with
+no file stops on it and the browser shows its own "select a file" message there
+(a `hidden` input cannot be focused, so the browser used to block the submit
+with only a console error). With `trailing`, the browse button is the tab stop;
+without it, the input is. The field's controls sit in a `group` named by the
+label. With `required`, the group's description is a visually hidden "This
+field is required." (`material.zod.required`, translated): `getByRole('group',
+{ name: 'Signed contract' })` and `toHaveAccessibleDescription('This field is
+required.')`. With `error`, the box is outlined (`data-invalid`),
+`aria-invalid` is on the file input, and `helperText` describes the group. With
+`trailing` and no `helperText`, the group is described by a visually hidden
+"This value is not valid." (`material.zod.default`, translated), because the
+browse button, the tab stop then, carries no `aria-invalid`; without
+`trailing`, the file input is the tab stop and says it itself.
+
+**Form wrapper:** `UploadFormField` — stores the `File` (or `File[]` with
+`multiple`), see [forms](../guides/forms.md).
+**Storybook:** `Media & files/UploadField` · **Vue:** `UploadField`, `UploadFormField`
+
+---
+
+## FileList
+
+![FileList](../previews/media-files-filelist.webp)
+![FileListField](../previews/media-files-filelistfield.webp)
+
+File list with type icons, size, download and remove. The field variants upload with progress.
+
+```tsx
+import { useState } from 'react';
+import { FileList, FileListField } from '@nxgt/material/components';
+
+<FileList
+  items={[
+    { id: '1', name: 'PO-1842.pdf', size: 248_832, href: '/files/PO-1842.pdf' },
+    { id: '2', name: 'site-photo.jpg', size: 1_572_864, type: 'image/jpeg' },
+  ]}
+  onRemove={(item) => console.log('remove', item.id)}
+/>;
+
+function Attachments() {
+  const [value, setValue] = useState<string[]>([]);
+  return (
+    <FileListField
+      label="Attachments"
+      helperText="Stored as URLs after upload."
+      value={value}
+      onValueChange={setValue}
+      onUpload={async (file) => `https://files.example.com/${file.name}`}
+    />
+  );
+}
+```
+
+Parts: `FileList` (display only), `FileListField` (uploads through `onUpload`),
+`FileListS3Field` (uploads through `getPresignedUrl`, like `S3UploadField`).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `FileListItem[]` | — | `FileList`: `{ id, name, size?, href?, type?, disabled? }`; `href` adds a download link, an `image/*` `type` an image icon |
+| `onRemove` | `(item) => void` | — | `FileList`: shows a remove button per row |
+| `loading` | `boolean` | `false` | `FileList`: skeleton rows |
+| `empty` | `ReactNode` | `"No files"` | shown when there is nothing to list |
+| `value` / `onValueChange` | `string[]` | `[]` | field variants: the stored URLs |
+| `onUpload` / `getPresignedUrl` | see [S3UploadField](#s3uploadfield-networkuploadfield) | — | field variants: how a file is sent |
+| `required` | `boolean` | — | field variants: the asterisk, and a "required" description on the field group (below) |
+
+The dropzone is a button, and a button may not carry `aria-required`, so the
+field's list and dropzone sit in a `group` named by the label. With `required`,
+the group's description is a visually hidden "This field is required."
+(`material.zod.required`, translated): `getByRole('group', { name:
+'Attachments' })` and `toHaveAccessibleDescription('This field is required.')`.
+Neither a `group` nor a `button` may carry `aria-invalid`, so with `error` the
+group is described by `helperText` instead, or without one by a visually hidden
+"This value is not valid." (`material.zod.default`, translated). Only the
+group: a screen reader reads it on entering the group, so describing the
+dropzone as well read the error twice, and the group still says it once
+`maxFiles` hides the dropzone. The dropzone is outlined through `data-invalid`.
+
+**Form wrapper:** `FileListFormField`, `FileListS3FormField` — see [forms](../guides/forms.md).
+**Storybook:** `Media & files/FileList`, `Media & files/FileListField` · **Vue:** `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField`
+
+---
+
+## FilesFormField
+
+No preview: it has no story of its own. It is an [`Autocomplete`](selection-and-choice.md)
+bound to React Hook Form.
+
+Free-solo autocomplete of file URLs, with image thumbnails.
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { FilesFormField } from '@nxgt/material/components';
+
+function Gallery() {
+  const { control } = useForm<{ photos: string[] }>({ defaultValues: { photos: [] } });
+  return (
+    <FilesFormField
+      control={control}
+      name="photos"
+      mode="multiple"
+      label="Photos"
+      placeholder="Paste an image URL"
+      image
+      imageLinkBuilder={(key) => `https://cdn.example.com/${key}`}
+    />
+  );
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'multiple'` | — (required) | one URL or a list |
+| `image` | `boolean` | — | selected values show a thumbnail instead of a file icon |
+| `imageLinkBuilder` | `(value) => string` | — | maps a stored key to the thumbnail `src` |
+| `options` | `{ value, label }[]` | `[]` | suggestions; any typed value is accepted too |
+| `freeSolo` | `boolean` | `true` | accept values that are not in `options` |
+
+**Form wrapper:** it is one — `control` and `name`, see [forms](../guides/forms.md).
+**Storybook:** — · **Vue:** —
+
+---
+
+## ImageField
+
+![ImageField](../previews/media-files-imagefield.webp)
+
+Single image upload with preview and progress.
+
+```tsx
+import { useState } from 'react';
+import { ImageField } from '@nxgt/material/components';
+
+function Avatar() {
+  const [value, setValue] = useState<string>();
+  return (
+    <ImageField
+      label="Avatar"
+      required
+      description="Avatars must comply with our policies."
+      helperText="Stored as a URL after upload."
+      value={value}
+      onValueChange={(next) => setValue(next ?? undefined)}
+      onUpload={async (file) => `https://files.example.com/${file.name}`}
+    />
+  );
+}
+```
+
+Parts: `ImageField` (uploads through `onUpload`), `ImageS3Field` (through
+`getPresignedUrl`).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `onValueChange` | `string` | — | the stored image URL |
+| `onUpload` / `getPresignedUrl` | see [S3UploadField](#s3uploadfield-networkuploadfield) | — | how the file is sent |
+| `accept` | `string` | `'image/*'` | file input `accept` |
+| `description` | `ReactNode` | — | text beside the thumbnail |
+| `buttonText` | `ReactNode` | `"Choose image"` | the pick button label |
+| `placeholder` | `string` | bundled placeholder image | shown while there is no value |
+| `resolveUrl` | `(value) => string \| null \| undefined` | — | maps a stored key to a URL for the preview |
+| `required` | `boolean` | — | the asterisk, and a "required" description on the field group (below) |
+
+A file picker is a button, and a button may not carry `aria-required`, so the
+field's controls sit in a `group` named by the label. With `required`, the
+group's description is a visually hidden "This field is required."
+(`material.zod.required`, translated): `getByRole('group', { name: 'Avatar' })`
+and `toHaveAccessibleDescription('This field is required.')`. A `group` may not
+carry `aria-invalid`, so with `error` (or a failed upload) the group is
+described by `helperText` (or the upload's error message) instead, or, for an
+`error` with neither `helperText` nor a failure message, or a failed upload
+with no message of its own, by a visually hidden "This value is not valid."
+(`material.zod.default`, translated), and outlined through `data-invalid`.
+
+**Form wrapper:** `ImageFormField`, `ImageS3FormField` — see [forms](../guides/forms.md).
+**Storybook:** `Media & files/ImageField` · **Vue:** `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField`
+
+---
+
+## ImageCropper
+
+![ImageCropper](../previews/media-files-imagecropper.webp)
+
+Crop with zoom, rotation, aspect presets and a round shape; outputs a `File`.
+
+```tsx
+import { Button, ImageCropper, ImageCropperDialog } from '@nxgt/material/components';
+
+<ImageCropper
+  src="/uploads/portrait.jpg"
+  cropShape="round"
+  aspect={1}
+  fileName="avatar.png"
+  onCrop={({ file }) => upload(file)}
+/>;
+
+<ImageCropperDialog
+  src="/uploads/cover.jpg"
+  title="Crop the cover"
+  trigger={<Button>Crop photo</Button>}
+  onCrop={({ file, area }) => upload(file)}
+/>;
+```
+
+Parts: `ImageCropper` (inline), `ImageCropperDialog` (the same in a dialog, closed
+after `onCrop`).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `src` | `string` | — | image to crop (URL or object URL) |
+| `onCrop` | `({ file, area }) => void` | — | receives the cropped `File` and the pixel area |
+| `aspect` | `number` | — | fixes the ratio and hides the presets; omitted, the user picks free / 1:1 / 4:3 / 16:9 / 3:4 |
+| `cropShape` | `'rect' \| 'round'` | `'rect'` | round mask for avatars |
+| `fileName` | `string` | — | name of the produced `File` |
+| `onCancel` | `() => void` | — | `ImageCropper`: shows a Cancel button |
+| `open` / `onOpenChange` / `trigger` | | — | `ImageCropperDialog`: controlled or trigger-opened |
+
+**Storybook:** `Media & files/ImageCropper` · **Vue:** `ImageCropper`, `ImageCropperDialog`
+
+---
+
+## Gallery, LightboxGallery, MiniGallery
+
+![Gallery](../previews/media-files-gallery.webp)
+![LightboxGallery](../previews/media-files-lightboxgallery.webp)
+![MiniGallery](../previews/media-files-minigallery.webp)
+
+Image / video gallery (grid, masonry, justified, carousel…) with a lightbox and selection.
+
+```tsx
+import {
+  Gallery,
+  type GalleryItem,
+  LightboxGallery,
+  MiniGallery,
+} from '@nxgt/material/components';
+
+const items: GalleryItem[] = [
+  { id: '1', src: '/photos/peaks.jpg', title: 'Mountain View', width: 800, height: 800 },
+  { id: '2', src: '/photos/forest.jpg', title: 'Forest Path', width: 800, height: 600 },
+  { id: '3', src: '/videos/waves.mp4', kind: 'video', poster: '/photos/waves.jpg' },
+];
+
+<Gallery items={items} preset="grid" selectable onSelectionChange={console.log} />;
+
+<LightboxGallery items={items} trigger={<button type="button">Open gallery</button>} />;
+
+<MiniGallery items={items} maxItems={5} />;
+```
+
+Parts: `Gallery` (every layout), `LightboxGallery` (`preset="lightbox"`: only a
+trigger, opens full screen), `MiniGallery` (`preset="compact"`: a thumbnail strip
+with a `+N` tile).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `GalleryItem[]` | — | `{ id, src, alt?, title?, description?, thumbnail?, kind?, poster?, width?, height? }` |
+| `preset` | `'album' \| 'grid' \| 'masonry' \| 'photos' \| 'product' \| 'stories' \| 'compact' \| 'lightbox'` | `'album'` | layout + lightbox defaults in one word |
+| `layout` | `'grid' \| 'masonry' \| 'justified' \| 'featured' \| 'carousel' \| 'strip' \| 'none'` | from `preset` | overrides the preset's layout |
+| `columns` / `aspect` | `number` / `'square' \| 'video' \| 'portrait' \| 'landscape' \| 'auto'` | from `preset` | grid shape |
+| `lightbox` | `boolean` | from `preset` | click opens the full-screen viewer (zoom, download, keyboard) |
+| `selectable` | `boolean` | — | checkboxes on tiles; `onSelectionChange(ids)` |
+| `open` / `defaultOpen` / `onOpenChange` | `boolean` | — | control the lightbox |
+| `onDelete` | `(item) => void` | — | adds a delete button on each tile |
+
+**Storybook:** `Media & files/Gallery`, `Media & files/LightboxGallery`, `Media & files/MiniGallery` · **Vue:** `Gallery`, `LightboxGallery`, `MiniGallery`
+
+---
+
+## Carousel
+
+![Carousel](../previews/media-files-carousel.webp)
+
+Embla carousel with keyboard navigation.
+
+```tsx
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselNext,
+  CarouselPrevious,
+} from '@nxgt/material/components';
+
+<Carousel opts={{ align: 'start', loop: true }} className="w-full max-w-xl">
+  <CarouselContent>
+    {['/slides/1.jpg', '/slides/2.jpg', '/slides/3.jpg'].map((src) => (
+      <CarouselItem key={src} className="basis-1/2">
+        <img src={src} alt="" className="aspect-video w-full rounded object-cover" />
+      </CarouselItem>
+    ))}
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+Parts: `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `opts` | Embla `EmblaOptionsType` | — | `align`, `loop`, `slidesToScroll`… |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | scroll axis (← / → navigate either way) |
+| `plugins` | Embla plugins | — | autoplay, class names… |
+| `setApi` | `(api) => void` | — | the Embla API, for a counter or custom controls |
+
+**Storybook:** `Media & files/Carousel` · **Vue:** `Carousel` (same parts)
+
+---
+
+## PdfReader
+
+![PdfReader](../previews/media-files-pdfreader.webp)
+
+Browser-only PDF reader with zoom, rotation, search, thumbnails, outline and print.
+
+```tsx
+import { PdfReader } from '@nxgt/material/components';
+
+<div className="h-[600px]">
+  <PdfReader
+    file="/documents/contract.pdf"
+    defaultFitMode="width"
+    onLoadError={(error) => console.error(error)}
+  />
+</div>
+```
+
+The reader fills its parent: give the parent a height. `react-pdf` is loaded
+lazily and the component renders on the client only, so importing it from a
+server bundle is safe. A cross-origin `file` URL must be served with CORS
+headers. With `httpHeaders` such as `Authorization`, the browser first sends
+a preflight request: the server must list those headers in
+`Access-Control-Allow-Headers`, and answer `withCredentials` with
+`Access-Control-Allow-Credentials: true`.
+
+`file` also takes the document itself, or a URL that needs a token:
+
+```tsx
+<PdfReader file={invoiceBlob} fileName="INV-1042.pdf" />       // a Blob or a File
+<PdfReader file={bytes} />                                      // an ArrayBuffer or a Uint8Array
+<PdfReader file={{ url: '/api/documents/42', httpHeaders: { Authorization: `Bearer ${token}` } }} />
+```
+
+Bytes are copied, so your buffer stays usable after the reader opened it (pdf.js
+empties the buffer it is given). The document reloads only when it changes: a
+URL with the same headers, even in a new object on each render, keeps the view;
+a Blob or a buffer is compared by identity, so keep the same object between
+renders (`useMemo`, state) rather than building a new one each time.
+
+Parts: `PdfReader`, `PdfToolbar`, `PdfSidebar`,
+`PdfThumbnailSidebar`, `PdfOutlineSidebar`, `PdfPageList`, and for building
+your own layout the `usePdfReader` and `usePdfSource` hooks, `toPdfjsSource`
+and `toPdfjsParams` (types `PdfExternalLinkTarget`, `PdfjsSourceParams`,
+`PdfjsUrlParams`). `PdfViewer` is a deprecated
+alias of `PdfReader`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `file` | `PdfSource \| null` | — | a URL (`string` or `URL`), a `File` or `Blob`, an `ArrayBuffer` or `Uint8Array`, or `{ url, httpHeaders?, withCredentials? }`; `null` shows the empty state |
+| `fileName` | `string` | the `File`'s name, else the URL's last segment, else `document.pdf` (translated: `material.pdf-reader.default-file-name`) | name Download saves under, `.pdf` added when missing; pass it when the URL ends in an id, or for a Blob or bytes. Ignored when `onDownload` is set |
+| `defaultFitMode` | `'width' \| 'page' \| 'custom'` | `'width'` | initial zoom mode |
+| `initialPage` | `number` | `1` | page shown first |
+| `initialScale` | `number` | `1` | zoom when the fit mode is `custom` |
+| `onPageChange` | `(page) => void` | — | current page changed |
+| `onLoadSuccess` / `onLoadError` | `(numPages)` / `(error)` | — | document loaded / failed |
+| `onDownload` / `onPrint` | `() => void` | — | replace the toolbar's built-in download / print |
+| `externalLinkTarget` | `'_blank' \| '_self' \| '_parent' \| '_top'` | `'_blank'` | where a link to a website inside the PDF opens |
+
+Download and Print use the bytes the reader already loaded, so a cross-origin
+document saves under its name and prints without being downloaded again. When
+those bytes are gone, a URL is fetched, with its `httpHeaders` and
+`withCredentials`; a Blob or bytes are saved as they are. A URL that cannot be
+fetched opens in a new tab, except a URL with `httpHeaders`, which would load
+there without them: Download and Print then do nothing.
+
+A protected PDF asks for its password (in a field named "Password", translated:
+`material.pdf-reader.password-label`) and says when it is wrong. Escape closes
+the search bar when it is open, before any dialog around the reader sees it;
+otherwise the dialog gets it. `onPageChange` reports a page inside the
+document, once per change.
+
+The zoom button opens a menu (fit width, fit page, 50% to 200%) that works from
+the keyboard: Enter or Space opens it, the arrows move, Enter picks and Escape
+closes it; its button is named after the current zoom ("Zoom level 150%",
+translated: `material.pdf-reader.zoom-menu`). In fullscreen it, and the
+toolbar's tooltips, open inside the reader. An outline entry without a title
+reads "Untitled" (`material.pdf-reader.untitled`).
+
+Links inside the PDF are clickable: one to another page scrolls to it, one to a
+website opens in a new tab, whatever the PDF asks (`externalLinkTarget` picks
+another target), with `rel="noopener noreferrer nofollow"`. A note in the PDF
+shows its icon and opens its popup when clicked. The text layer (selection,
+search highlights) and the annotation layer (links, notes) are styled by
+react-pdf's own CSS, which comes in both `styles.css` (a Tailwind app) and the
+compiled `dist/material.css`: nothing to import yourself.
+
+Fit width and fit page use each page's own size, turned by its own `/Rotate` (a
+page the PDF shows landscape is drawn and fitted landscape): the zoom fits the
+widest and the tallest of the first 25 pages, read when the document opens, so a
+document mixing A4, Letter and landscape pages keeps one zoom: none of them is
+wider than the reader in fit width, or larger than it in fit page. The zoom
+settles once those pages are read and does not move while you read: sizes are
+read 25 pages at a time, and a page further on never changes it (a wider one
+scrolls sideways in fit width). However small the page, the fit stops at 500%.
+Building your own layout with `usePdfReader`, pass the loaded document to
+`handlers.onDocumentLoadSuccess` so it can read the sizes, and `state.pageSizes`
+(a `PdfPageSize[]`: `width` and `height` in points, and `rotate`, the page's own
+`/Rotate`, left out when 0) to `PdfPageList` and `PdfSidebar` as `pageSizes` for
+their placeholders. Give your own react-pdf `Document` the source from
+`usePdfSource(file)` (or `toPdfjsSource`, and `toPdfjsParams` for pdf.js's
+`getDocument`), all exported beside `usePdfReader`: they take any `PdfSource`,
+keep one object per document, and copy bytes, so your buffer is not detached:
+
+```tsx
+const source = usePdfSource(file); // null while there is no file
+return source && <Document file={source}>{/* your pages */}</Document>;
+```
+
+Search reads every page, drawn or not, and counts every match, ignoring case,
+accents, ligatures and the width of white space; the counter reads `0/N` until
+you move to a match. Enter or F3 moves to the next match, and Shift+Enter or
+Shift+F3 to the previous one, showing its page. `PdfPageList` takes
+`highlight` (a `PdfSearchHighlight`) from `PdfReader` itself; in a layout of
+your own, pass `searchQuery` instead and it marks the query in each text run.
+
+The reader opens on `initialPage` (the last page when it is past the end, and
+again when `file` changes: a new URL or new headers, or another Blob or buffer
+object; an equal inline `{ url, httpHeaders }` does not count), and the page
+number follows scrolling: the page most on screen is the current page, and
+`onPageChange` reports it. It also reports the page the reader moves to itself:
+an `initialPage` clamped to the last page, and `initialPage` again when a new
+file opens on another page than the one shown.
+
+**Storybook:** `Media & files/PdfReader` · **Vue:** `PdfReader`, `PdfViewer` (same parts)
+
+---
+
+## StxPlayer
+
+![StxPlayer](../previews/media-files-stxplayer.webp)
+
+Video / audio player with a queue, captions, playback rate, PiP, and full or mini layouts.
+
+```tsx
+import { StxPlayer, type StxTrack } from '@nxgt/material/components';
+
+const tracks: StxTrack[] = [
+  {
+    id: 'intro',
+    kind: 'video',
+    src: '/media/intro.mp4',
+    title: 'Getting started',
+    artist: 'Product team',
+    artwork: '/media/intro.jpg',
+    captions: [{ src: '/media/intro.en.vtt', label: 'English', srclang: 'en', default: true }],
+  },
+  { id: 'ep1', kind: 'audio', src: '/media/ep1.mp3', title: 'Episode 1', artist: 'The podcast' },
+];
+
+<StxPlayer tracks={tracks} loop onTrackChange={(index, track) => console.log(track.title)} />;
+```
+
+Parts: `StxPlayer`, and for a custom shell `StxPlayerProvider`,
+`StxPlayerViewport`, `StxPlayerControls`, `StxPlayerExtras`, `StxPlayerQueue`,
+`StxPlayerMini`, `useStxPlayer`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `tracks` | `StxTrack[]` | — | `{ id, src, kind: 'video' \| 'audio', title, artist?, album?, artwork?, captions? }` |
+| `layout` | `'full' \| 'mini'` | `'full'` | the full player or a compact bar |
+| `showQueue` | `boolean` | `true` | the track list beside the player |
+| `autoPlay` | `boolean` | `false` | start on load (browsers block it unless muted) |
+| `loop` | `boolean` | `false` | wrap from the last track to the first |
+| `defaultIndex` / `currentIndex` | `number` | `0` | uncontrolled / controlled current track |
+| `onTrackChange` | `(index, track) => void` | — | the current track changed |
+
+Playback uses the browser's `<video>` / `<audio>`: a format the browser cannot
+decode (H.264 MP4 in a Chromium build without proprietary codecs) shows the
+player's error state with a Retry button. The preview is the audio story.
+
+**Storybook:** `Media & files/StxPlayer` · **Vue:** `StxPlayer` (same parts)
+
+---
+
+## VideoPlayer
+
+Deprecated alias of `StxPlayer`.
+
+No preview: it is [`StxPlayer`](#stxplayer) under another name
+(`VideoPlayerProps` and `VideoPlayerTrack` alias its types) — use `StxPlayer`.
+
+**Storybook:** — · **Vue:** `VideoPlayer`
+
+---
+
+## Print components
+
+No preview: these render PDF with `@react-pdf/renderer`, not DOM, so there is
+nothing for Storybook to capture. They live in their own entry,
+`@nxgt/material/print`, with `@react-pdf/renderer` and `react-pdf-tailwind` as
+optional peers — read the [printing guide](../guides/printing.md) before bundling
+it into an SSR server.
+
+A page shell and `@react-pdf/renderer` building blocks for printable PDF
+documents, with a shared `tw`.
+
+```tsx
+import {
+  PrintDocument,
+  PrintHeader,
+  PrintSection,
+  PrintInfoRow,
+  PrintTable,
+  PrintTableHeader,
+  PrintTableRow,
+  PrintTableCell,
+  PrintTotals,
+  PrintTotalRow,
+} from '@nxgt/material/print';
+
+<PrintDocument
+  title="Invoice INV-2044"
+  pageNumbers
+  header={<PrintHeader title="Invoice" reference="INV-2044" logoText="ACME" />}
+  footer="Acme Inc. · 12 Main Street"
+>
+  <PrintSection title="Customer">
+    <PrintInfoRow label="Name" value="Acme Inc." />
+  </PrintSection>
+  <PrintTable>
+    <PrintTableHeader>
+      <PrintTableCell isHeader flex={3}>Item</PrintTableCell>
+      <PrintTableCell isHeader textAlign="right">Amount</PrintTableCell>
+    </PrintTableHeader>
+    <PrintTableRow>
+      <PrintTableCell flex={3}>Consulting</PrintTableCell>
+      <PrintTableCell textAlign="right">1 200.00</PrintTableCell>
+    </PrintTableRow>
+  </PrintTable>
+  <PrintTotals>
+    <PrintTotalRow label="Total" value="1 200.00" last />
+  </PrintTotals>
+</PrintDocument>;
+```
+
+Parts: `PrintDocument`, `PrintHeader`, `PrintSection`, `PrintInfoRow`,
+`PrintCard`, `PrintCardField`, `PrintTable`, `PrintTableHeader`,
+`PrintTableRow`, `PrintTableCell`, `PrintTotals`, `PrintTotalRow`,
+`PrintBadge`, `PrintDataTable`, `PrintKeyValue`, `PrintMetric`,
+`PrintMetrics`, plus `tw`, `commonPrintStyles`, `formatAmount`, `formatDate`,
+`definePrintColumns` and the helpers `resolvePrintTable`,
+`resolvePrintFields`, `toPrintValue` and `formatPrintValue`.
+
+**To get the file**, pass the document to one function: `downloadPdf`
+saves it, `openPdf` opens it in a new tab (a download when a popup blocker
+stops the tab), `usePdfFile` keeps a preview current, and `pdfResponse`
+answers a server route (Node 18+ or Bun).
+
+```tsx
+import { useMemo } from 'react';
+import { Button, PdfReader } from '@nxgt/material/components';
+import { downloadPdf, openPdf, usePdfFile } from '@nxgt/material/print';
+import { InvoiceDocument, type Invoice } from './invoice-document';
+
+export function InvoicePdf({ invoice }: { invoice: Invoice }) {
+  const doc = useMemo(() => <InvoiceDocument invoice={invoice} />, [invoice]); // a new element would render again
+  const { blob } = usePdfFile(doc);
+  return (
+    <>
+      <Button onClick={() => downloadPdf(blob ?? doc, { fileName: invoice.number })}>Download</Button>
+      <Button onClick={() => openPdf(blob ?? doc, { fileName: invoice.number })}>Open</Button>
+      <div className="h-[600px]">
+        <PdfReader file={blob} fileName={`${invoice.number}.pdf`} />
+      </div>
+    </>
+  );
+}
+```
+
+```tsx
+// a server route
+import { pdfResponse } from '@nxgt/material/print';
+import { InvoiceDocument } from './invoice-document';
+import { getInvoice } from './invoices.server';
+
+export const loader = async ({ params }: { params: { id: string } }) =>
+  pdfResponse(<InvoiceDocument invoice={await getInvoice(params.id)} />, { fileName: params.id });
+```
+
+`renderPdfBlob`, `renderPdfBuffer` (a `Uint8Array`) and `renderPdfStream` (a
+Web stream, on a server) return the file itself. Each takes a
+`PrintDocument` element or a document written as plain data with
+`pdfDocument` and its builders (experimental). Options, runtimes and the
+data model: [printing guide](../guides/printing.md#rendering-the-document).
+
+**`PrintDocument`** takes the place of react-pdf's `Document` + `Page`; pass
+it to the functions above, or to `pdf()`, `renderToBuffer()` or `PDFViewer`.
+Its children flow over as many pages as they need.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `size` | `'A3' \| 'A4' \| 'A5' \| 'LETTER' \| 'LEGAL' \| [number, number]` | `'A4'` | page size; a tuple is width and height in points |
+| `orientation` | `'portrait' \| 'landscape'` | `'portrait'` | |
+| `margins` | `number \| { top, right, bottom, left, x, y }` | `{ top: 21, right: 24, bottom: 21, left: 24 }` | points; a side wins over its axis |
+| `header` | `ReactNode` | — | repeated at the top of every page, such as a `PrintHeader` |
+| `footer` | `ReactNode \| ({ pageNumber, totalPages }) => string` | — | repeated at the bottom of every page; a function runs outside React, so no hooks |
+| `footerHeight` | `number` | `24` | the band kept at the bottom for the footer and page numbers |
+| `pageNumbers` | `boolean \| { align?: 'left' \| 'center' \| 'right'; format?: 'page-of' \| 'page' }` | off | "Page 2 of 5" (`'page-of'`) or "Page 2" (`'page'`), translated, in the footer row |
+| `watermark` | `string \| { text, opacity?, angle?, color?, fontSize? }` | — | rotated text behind the content; `0.08`, `35`°, `72` pt |
+| `title`, `author`, `subject`, `keywords` | `string` | — | PDF metadata |
+| `creator` / `producer` | `string` | `'@nxgt/material'` / `creator` | PDF metadata |
+| `language` | `string` | the `I18nProvider` around the document, then `'en'` | page-number strings and the PDF's language; the app's provider does not reach `pdf()` |
+| `locale` / `timeZone` | `string` | `language` / the runtime's | how the blocks format amounts and dates |
+
+**`PrintHeader`** is the title block: a logo on the left, the title,
+subtitle and reference centred, a QR code on the right.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` | `string` | — | required |
+| `subtitle` | `string` | — | under the title |
+| `reference` | `string` | — | printed as `#INV-2044` |
+| `referencePrefix` | `string` | `'#'` | what goes before `reference` |
+| `logo` | `string \| { src, width?, height? }` | — | a PNG or JPEG URL or data URL, 72×48 pt, `contain` |
+| `logoText` | `string` | — | text in a grey box, when there is no `logo` |
+| `qrDataUrl` | `string \| null` | — | a QR code already rendered as a PNG data URL |
+
+**Changed in 2.2.0:** with neither `logo` nor `logoText` it draws no `LOGO`
+placeholder, and with no `qrDataUrl` no empty QR box; the title stays
+centred. `logoText="LOGO"` keeps the old box. French amounts
+(`formatAmount(…, { locale: 'fr-FR' })`) also print correctly in the blocks
+now, where `1 234,50 €` used to come out as `1/234,50 €`.
+
+Page numbers, footers and translation: [printing guide](../guides/printing.md#the-page-shell-printdocument).
+
+**`PrintDataTable`**, **`PrintKeyValue`** and **`PrintMetric`** (new in
+2.2.0) print from data instead of cells written by hand: a table from
+`definePrintColumns` and plain rows, with its header repeated on each page it
+crosses and a totals row; one record as label and value pairs; figures in a
+row. Amounts and dates follow the `PrintDocument`'s locale.
+
+```tsx
+import {
+  definePrintColumns,
+  PrintDataTable,
+  PrintDocument,
+  PrintKeyValue,
+  PrintMetric,
+  PrintMetrics,
+} from '@nxgt/material/print';
+
+type Line = { description: string; quantity: number; amount: number };
+
+const columns = definePrintColumns<Line>([
+  { key: 'description', label: 'Item', flex: 3 },
+  { key: 'quantity', label: 'Qty', format: 'number', width: 40 },
+  { key: 'amount', label: 'Amount', format: 'amount', total: 'sum' },
+]);
+
+<PrintDocument language="fr" pageNumbers>
+  <PrintMetrics>
+    <PrintMetric label="Revenue" value={12400} format="amount" currency="EUR" delta={4} />
+    <PrintMetric label="Orders" value={87} />
+  </PrintMetrics>
+  <PrintKeyValue
+    columns={2}
+    items={[
+      { label: 'Customer', value: 'Acme Inc.' },
+      { label: 'Issued', value: { date: '2026-03-01' } },
+    ]}
+  />
+  <PrintDataTable
+    columns={columns}
+    rows={[{ description: 'Consulting', quantity: 2, amount: 1200 }]}
+    currency="EUR"
+  />
+</PrintDocument>;
+```
+
+`PrintDataTable`:
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `columns` | `PrintColumn<T>[]` | — | required; from `definePrintColumns<T>()`: `key` or `id` + `accessor`, `label`, `width`, `flex`, `align`, `format`, `currency`, `total` |
+| `rows` | `T[]` | — | required; amounts must be numbers (a string prints `—`) |
+| `currency` | `string` | — | ISO 4217 code for `amount` columns that name none |
+| `totalLabel` | `string` | "Total", translated | first cell of the totals row, printed when a column has a `total` |
+| `striped` | `boolean` | `true` | shades every other row |
+| `repeatHeader` | `boolean` | `true` | the header again on each page the table crosses |
+| `keepRowsWhole` | `boolean` | `true` | a row never splits across pages |
+| `emptyText` | `string` | "No rows", translated | the one muted row of an empty table |
+| `hideWhenEmpty` | `boolean` | `false` | an empty table prints nothing |
+
+`PrintKeyValue`:
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `{ label: string; value: PrintValue }[]` | — | the pairs; or `data` + `fields` |
+| `data` + `fields` | `T` + `PrintColumn<T>[]` | — | one record through the same column definitions as a table |
+| `currency` | `string` | — | with `data`: for `amount` fields that name none |
+| `columns` | `1 \| 2` | `1` | one or two columns of pairs |
+| `keepEmpty` | `boolean` | `false` | print empty values as `—` instead of skipping them |
+
+`PrintMetric` (several in a `PrintMetrics` row):
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `label` | `string` | — | required |
+| `value` | `PrintValue` | — | required; a number, text, `{ amount, currency }`, `{ date }` |
+| `format` | `'amount' \| 'date' \| 'number' \| 'percent'` | — | applied to a number `value` |
+| `currency` | `string` | — | for `format="amount"` |
+| `hint` | `string` | — | caption under the figure |
+| `delta` | `number` | — | a change in percent: `4` prints `+4%`, `-2` prints `-2%` |
+
+Columns, totals, page breaks and the helpers for your own blocks:
+[printing guide](../guides/printing.md#tables-from-columns-and-rows).
+
+**Storybook:** — · **Vue:** `PrintHeader`, `PrintSection`, `PrintTable`, `PrintTotals`, `PrintCard`
+
+---
+
+## Map
+
+![Map](../previews/media-files-map.webp)
+
+Leaflet map with markers, controls and a location field. It is not in the
+component barrel: it lives in `@nxgt/material/map`, is **browser-only** (leaflet
+reads `window` at import) and its stylesheet is `@nxgt/material/map.css`, which is
+not part of `styles.css`. The [maps guide](../guides/maps.md) covers the optional
+peers, SSR and the defaults.
+
+```tsx
+import '@nxgt/material/map.css';
+import { Map, Marker } from '@nxgt/material/map';
+
+<Map className="size-96" center={[48.8566, 2.3522]}>
+  <Marker position={[48.8566, 2.3522]} />
+</Map>
+```
+
+Parts: `Map` (also exported as `MapComponent`), `Marker`, `LocationMarker`,
+`LocationPreview`, `MapActions`, `MinimapControl`, `LocationField` ·
+`LocationFormField`, `useGeolocation`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `center` | `LatLngExpression` | visitor's geolocation, else `[5.44087, 10.06843]` | **omitting it asks the browser for location permission** |
+| `zoom` | `number` | `13` | initial zoom |
+| `scrollWheelZoom` | `boolean` | `false` | the wheel scrolls the page, not the map |
+| `showMinicardControl` | `boolean` | `true` | inset minimap, top right |
+| `zoomControl` | `boolean` | `false` | leaflet's own control; the component already renders one |
+
+**Form wrapper:** `LocationFormField` — see [forms](../guides/forms.md).
+**Storybook:** `Media & files/Map` · **Vue:** —
+
+---
+
+## Not documented here
+
+`Media & files/Camera` exists in Storybook only: the `Camera` component is not
+exported from the package, so it has no entry on this page.