@nxgt/material-vue 0.21.0 → 0.22.0

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

@@ -0,0 +1,857 @@
+# Media & files
+
+Uploaders, file lists, images, galleries, PDF and media players, a camera and
+printable documents — plus Leaflet maps, which live outside the barrel in
+`@nxgt/material-vue/map`. Every upload field has a form wrapper; see the
+[forms guide](../guides/forms.md) for wiring them into a vee-validate 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 holding the chosen `File` |
+| <img src="../previews/media-files-filelist.webp" width="96" alt=""> | [FileList](#filelist) | File list with type icons, size, download and remove |
+| | [FilesFormField](#filesformfield) | Not in `@nxgt/material-vue` |
+| <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) | Client-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` |
+| <img src="../previews/media-files-camera.webp" width="96" alt=""> | [Camera](#camera) | Webcam preview with device selection and a still capture |
+| <img src="../previews/media-files-print.webp" width="96" alt=""> | [Print components](#print-components) | Inline-styled blocks for printable documents (invoice, receipt, report) |
+| <img src="../previews/media-files-map.webp" width="96" alt=""> | [Map](#map) | Leaflet map, markers and a location field (`@nxgt/material-vue/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.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { NetworkUploadField, S3UploadField } from '@nxgt/material-vue/components';
+
+const attachments = ref<string[]>([]);
+const contract = ref<string | null>();
+
+async function getPresignedUrl(file: 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).
+async function upload(file: File, onProgress?: (percent: number) => void) {
+  onProgress?.(100);
+  return `https://files.example.com/${file.name}`;
+}
+</script>
+
+<template>
+  <S3UploadField
+    v-model="attachments"
+    mode="multiple"
+    label="Attachments"
+    helper-text="PDF or images, up to 5 MB each"
+    accept="application/pdf,image/*"
+    :max-size="5 * 1024 * 1024"
+    :max-files="5"
+    :get-presigned-url="getPresignedUrl"
+  />
+  <NetworkUploadField v-model="contract" mode="single" label="Contract" :on-upload="upload" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'multiple'` | — (required) | `v-model` is a `string` or a `string[]` |
+| `onUpload` | `(file, onProgress?) => Promise<string>` | — | `NetworkUploadField` only (required); the resolved string becomes the value |
+| `getPresignedUrl` | `(file) => Promise<{ uploadUrl, publicUrl, headers? }>` | — | `S3UploadField` only (required); 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
+`helper-text`, 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]')`.
+
+**Emits:** `update:modelValue` — `string | string[] | null | undefined`.
+**Form wrapper:** `S3UploadFormField`, `NetworkUploadFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair).
+**Storybook:** `Media & files/S3UploadField`, `Media & files/NetworkUploadField` · **React:** `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField`
+
+---
+
+## UploadField
+
+![UploadField](../previews/media-files-uploadfield.webp)
+
+Labelled file input holding the chosen `File`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Icon, UploadField } from '@nxgt/material-vue/components';
+
+const file = ref<File | File[]>();
+</script>
+
+<template>
+  <UploadField
+    v-model="file"
+    label="Signed contract"
+    placeholder="Choose a file"
+    helper-text="PDF, up to 10 MB"
+    accept="application/pdf"
+    trailing="Browse"
+  >
+    <template #leading>
+      <Icon name="file" class="size-4" />
+    </template>
+  </UploadField>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `File \| File[]` | — | the picked file (a `File[]` with `multiple`); the field shows its name |
+| `multiple` | `boolean` | `false` | pick several files |
+| `accept` | `string` | — | file input `accept` |
+| `label` | `string` | — | shown above, with `*` when `required` |
+| `required` | `boolean` | — | the asterisk, `required` on the file input, and a "required" description on the field group (below) |
+| `trailing` | `string` | — | text of the browse button; the `#trailing` slot replaces the button |
+| `#leading` | slot | — | adornment before the file name |
+| `error` | `boolean` | `false` | red outline; `helperText` becomes the error |
+
+Unlike React's `UploadField`, which only shows a `value` string, the Vue field
+keeps the `File` itself in `v-model`. 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 a `trailing` button (prop or slot), that
+button is the tab stop; without one, 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.')`. A `group` may not
+carry `aria-invalid`, so with `error` it is described by `helper-text` instead
+and outlined through `data-invalid`; `aria-invalid` is on the file input. With
+a trailing button and no `helper-text`, the group is described by a visually
+hidden "This value is not valid." (`material.zod.default`, translated), because
+that button, the tab stop then, carries no `aria-invalid`; without one, the
+file input is the tab stop and says it itself.
+
+**Emits:** `update:modelValue` — `File | File[] | undefined`.
+**Form wrapper:** `UploadFormField` — stores the `File` (or `File[]` with
+`multiple`), see [forms](../guides/forms.md#the-pair).
+**Storybook:** `Media & files/UploadField` · **React:** `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.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FileList, FileListField, type FileListItem } from '@nxgt/material-vue/components';
+
+const items: FileListItem[] = [
+  { 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' },
+];
+const attachments = ref<string[]>([]);
+
+async function upload(file: File) {
+  return `https://files.example.com/${file.name}`;
+}
+</script>
+
+<template>
+  <FileList :items="items" @remove="(item) => console.log('remove', item.id)" />
+
+  <FileListField
+    v-model="attachments"
+    label="Attachments"
+    helper-text="Stored as URLs after upload."
+    :on-upload="upload"
+  />
+</template>
+```
+
+Parts: `FileList` (display only), `FileListField` (uploads through `onUpload`),
+`FileListS3Field` (uploads through `getPresignedUrl`, like `S3UploadField`),
+and the `formatFileSize` helper.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `FileListItem[]` | — | `FileList`: `{ id, name, size?, href?, type?, disabled? }`; `href` adds a download link, an `image/*` `type` an image icon |
+| `@remove` | `(item) => void` | — | `FileList`: listening shows a remove button per row |
+| `loading` | `boolean` | `false` | `FileList`: skeleton rows |
+| `empty` | `string` (or `#empty` slot) | `"No files"` | shown when there is nothing to list |
+| `aria-label` | `string` | `'Files'` (`material.file-list.label`, translated) | `FileList`: the list's accessible name; your value wins |
+| `v-model` | `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 `helper-text` 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
+`max-files` hides the dropzone. The dropzone is outlined through
+`data-invalid`.
+
+**Emits:** `update:modelValue` — `string[]` (field variants).
+**Form wrapper:** `FileListFormField`, `FileListS3FormField` — `name` inside a vee-validate form, see [forms](../guides/forms.md#the-pair).
+**Storybook:** `Media & files/FileList`, `Media & files/FileListField` · **React:** `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField`
+
+---
+
+## FilesFormField
+
+Not in `@nxgt/material-vue`. For a list of file URLs use
+[`FileListFormField`](#filelist); for typed URLs with suggestions, an
+`AutocompleteFormField` with `free-solo` (see [Selection & choice](selection-and-choice.md#autocomplete)).
+
+**Storybook:** — · **React:** `FilesFormField`
+
+---
+
+## ImageField
+
+![ImageField](../previews/media-files-imagefield.webp)
+
+Single image upload with preview and progress.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ImageField } from '@nxgt/material-vue/components';
+
+const avatar = ref<string | null>();
+
+async function upload(file: File) {
+  return `https://files.example.com/${file.name}`;
+}
+</script>
+
+<template>
+  <ImageField
+    v-model="avatar"
+    class="w-80"
+    label="Avatar"
+    required
+    description="Avatars must comply with our policies."
+    helper-text="Stored as a URL after upload."
+    :on-upload="upload"
+  />
+</template>
+```
+
+Parts: `ImageField` (uploads through `onUpload`), `ImageS3Field` (through
+`getPresignedUrl`).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `string` | — | the stored image URL |
+| `onUpload` / `getPresignedUrl` | see [S3UploadField](#s3uploadfield-networkuploadfield) | — | how the file is sent (required) |
+| `accept` | `string` | `'image/*'` | file input `accept` |
+| `maxSize` | `number` (bytes) | — | larger files are rejected before upload |
+| `description` | `string` (or `#description` slot) | — | text beside the thumbnail |
+| `buttonText` | `string` | `"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 `helper-text` (or the upload's error message) instead, or, for an
+`error` with neither `helper-text` 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`.
+
+**Emits:** `update:modelValue` — `string | null | undefined`.
+**Form wrapper:** `ImageFormField`, `ImageS3FormField` — `name` inside a vee-validate form, see [forms](../guides/forms.md#the-pair).
+**Storybook:** `Media & files/ImageField` · **React:** `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField`
+
+---
+
+## ImageCropper
+
+![ImageCropper](../previews/media-files-imagecropper.webp)
+
+Crop with zoom, rotation, aspect presets and a round shape; outputs a `File`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  Button,
+  ImageCropper,
+  ImageCropperDialog,
+  type ImageCropResult,
+} from '@nxgt/material-vue/components';
+
+const open = ref(false);
+
+function onCrop({ file }: ImageCropResult) {
+  console.log('upload', file.name);
+}
+</script>
+
+<template>
+  <ImageCropper
+    src="/uploads/portrait.jpg"
+    crop-shape="round"
+    :aspect="1"
+    file-name="avatar.png"
+    @crop="onCrop"
+  />
+
+  <ImageCropperDialog v-model:open="open" src="/uploads/cover.jpg" title="Crop the cover" @crop="onCrop">
+    <template #trigger>
+      <Button>Crop photo</Button>
+    </template>
+  </ImageCropperDialog>
+</template>
+```
+
+Parts: `ImageCropper` (inline), `ImageCropperDialog` (the same in a dialog, closed
+after `@crop`), and the `cropImageToFile` / `canvasToFile` helpers.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `src` | `string` | — (required) | image to crop (URL or object URL) |
+| `@crop` | `({ 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` |
+| `@cancel` | `() => void` | — | `ImageCropper`: listening shows a Cancel button |
+| `v-model:open` / `#trigger` | `boolean` / slot | — | `ImageCropperDialog`: controlled with `v-model:open`, or leave it out and the `#trigger` slot opens it |
+
+**Storybook:** `Media & files/ImageCropper` · **React:** `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.
+
+```vue
+<script setup lang="ts">
+import {
+  Gallery,
+  type GalleryItem,
+  LightboxGallery,
+  MiniGallery,
+} from '@nxgt/material-vue/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' },
+];
+</script>
+
+<template>
+  <Gallery :items="items" preset="grid" selectable @selection-change="(ids) => console.log(ids)" />
+
+  <LightboxGallery :items="items">
+    <template #trigger>
+      <button type="button">Open gallery</button>
+    </template>
+  </LightboxGallery>
+
+  <MiniGallery :items="items" :max-items="5" />
+</template>
+```
+
+Parts: `Gallery` (every layout), `LightboxGallery` (`preset="lightbox"`: only a
+trigger, opens full screen), `MiniGallery` (`preset="compact"`: a thumbnail strip
+with a `+N` tile), and `useGallery` for a custom shell.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `GalleryItem[]` | — (required) | `{ 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` | `false` | checkboxes on tiles; `@selection-change(ids)` |
+| `v-model:open` / `defaultOpen` | `boolean` | `false` | control the lightbox |
+| `@delete` | `(item) => void` | — | listening adds a delete button on each tile |
+
+**Storybook:** `Media & files/Gallery`, `Media & files/LightboxGallery`, `Media & files/MiniGallery` · **React:** `Gallery`, `LightboxGallery`, `MiniGallery`
+
+---
+
+## Carousel
+
+![Carousel](../previews/media-files-carousel.webp)
+
+Embla carousel with keyboard navigation.
+
+```vue
+<script setup lang="ts">
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselNext,
+  CarouselPrevious,
+} from '@nxgt/material-vue/components';
+
+const slides = ['/slides/1.jpg', '/slides/2.jpg', '/slides/3.jpg'];
+</script>
+
+<template>
+  <Carousel class="w-full max-w-xl" :opts="{ align: 'start', loop: true }">
+    <CarouselContent>
+      <CarouselItem v-for="src in slides" :key="src" class="basis-1/2">
+        <img :src="src" alt="" class="aspect-video w-full rounded object-cover" />
+      </CarouselItem>
+    </CarouselContent>
+    <CarouselPrevious />
+    <CarouselNext />
+  </Carousel>
+</template>
+```
+
+Parts: `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, and `useCarousel` inside them.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `opts` | `CarouselOptions` (Embla options) | — | `align`, `loop`, `slidesToScroll`… |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | scroll axis (← / → navigate either way) |
+| `plugins` | `CarouselPlugin` (Embla plugins) | — | autoplay, class names… |
+| `setApi` / `@init-api` | `(api: CarouselApi) => void` | — | the Embla API, for a counter or custom controls |
+
+**Storybook:** `Media & files/Carousel` · **React:** `Carousel` (same parts)
+
+---
+
+## PdfReader
+
+![PdfReader](../previews/media-files-pdfreader.webp)
+
+Client-only PDF reader with zoom, rotation, search, thumbnails, outline and print.
+
+```vue
+<script setup lang="ts">
+import { PdfReader } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <div class="h-[600px]">
+    <PdfReader
+      file="/documents/contract.pdf"
+      default-fit-mode="width"
+      @load-error="(error) => console.error(error)"
+    />
+  </div>
+</template>
+```
+
+The reader fills its parent: give the parent a height. `pdfjs-dist` is loaded
+lazily and the component mounts on the client only (it renders nothing during
+SSR), so importing it in a Nuxt app 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:
+
+```vue
+<PdfReader :file="invoiceBlob" file-name="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 it in a `shallowRef` rather
+than building a new one in the template.
+
+Parts: `PdfReader` (`PdfViewer` is a deprecated alias), `PdfToolbar`, `PdfSidebar`,
+`PdfThumbnailSidebar`, `PdfOutlineSidebar`, `PdfPageList`, and the
+`usePdfReader` composable for building your own layout.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `file` | `PdfSource \| null` | — (required) | 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` |
+| `@page-change` | `(page: number) => void` | — | current page changed |
+| `@load-success` / `@load-error` | `(numPages)` / `(error: Error)` | — | document loaded / failed |
+| `onDownload` / `onPrint` | `() => void` | — | replace the toolbar's built-in download / print |
+| `externalLinkTarget` | `PdfExternalLinkTarget`: `'_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. `@page-change` 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"`. Thumbnails carry no
+links. A note shows its icon and opens its popup when clicked; notes and shapes
+are styled with pdf.js's annotation layer rules, which come with the reader's
+text layer styles in both `styles.css` and the compiled CSS. Form fields are not
+drawn.
+
+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 `:page-sizes`
+for their placeholders. A document of your own loads with pdf.js's
+`getDocument(await toPdfjsParams(file))`: `toPdfjsParams` takes any `PdfSource`
+and resolves to what `getDocument` takes, bytes copied so your buffer is not
+detached. `toPdfjsSource` does the same synchronously, a `Blob` staying a
+`Blob`. Both are exported beside `usePdfReader`.
+
+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
+`@page-change` 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.
+
+Each listener runs once per event. The `onPageChange`, `onLoadSuccess` and
+`onLoadError` props are deprecated aliases of the three events and go in 1.0.
+
+**Storybook:** `Media & files/PdfReader` · **React:** `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.
+
+```vue
+<script setup lang="ts">
+import { StxPlayer, type StxTrack } from '@nxgt/material-vue/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' },
+];
+</script>
+
+<template>
+  <StxPlayer :tracks="tracks" loop @track-change="(index, track) => console.log(track.title)" />
+</template>
+```
+
+Parts: `StxPlayer`, and for a custom shell `StxPlayerProvider`,
+`StxPlayerViewport`, `StxPlayerControls`, `StxPlayerExtras`, `StxPlayerQueue`,
+`StxPlayerMini`, `useStxPlayer`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `tracks` | `StxTrack[]` | — (required) | `{ 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 |
+| `@track-change` | `(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. `StxPlayer` mounts on the client only.
+
+**Storybook:** `Media & files/StxPlayer` · **React:** `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:** — · **React:** `VideoPlayer`
+
+---
+
+## Camera
+
+![Camera](../previews/media-files-camera.webp)
+
+Webcam preview with device selection and a still capture.
+
+```vue
+<script setup lang="ts">
+import { Camera } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <div class="w-[640px]">
+    <Camera />
+  </div>
+</template>
+```
+
+It asks for camera permission when it mounts, lists the devices, streams the
+selected one and shows the captured photo under the preview; the stream is
+stopped on unmount. It mounts on the client only. `Camera` takes only `class`
+and emits nothing: the capture stays inside the component. The helpers
+`isCameraSupported`, `getCameraDevices`, `requestCameraPermissions` and
+`capturePhotoFromVideo` are exported for building your own.
+
+**Storybook:** `Media & files/Camera` · **React:** — (a story only, not exported)
+
+---
+
+## Print components
+
+![Print](../previews/media-files-print.webp)
+
+Inline-styled blocks for printable documents (invoice, receipt, report), with a shared `tw`.
+
+They are ordinary Vue components exported from `@nxgt/material-vue/components`:
+every style is inline (`tw` turns a Tailwind-like class string into a `style`
+object), so a document looks the same in the page, in the browser's print
+dialog (`window.print()`, *Save as PDF*) and in an HTML-to-PDF service, with no
+stylesheet to ship alongside. For a real PDF file built from data (the same
+model as React's `@nxgt/material/print`), see
+[`@nxgt/material-vue/pdf`](../guides/pdf.md).
+
+```vue
+<script setup lang="ts">
+import {
+  PrintHeader,
+  PrintInfoRow,
+  PrintSection,
+  PrintTable,
+  PrintTableCell,
+  PrintTableHeader,
+  PrintTableRow,
+  PrintTotalRow,
+  PrintTotals,
+  commonPrintStyles,
+  formatAmount,
+  tw,
+} from '@nxgt/material-vue/components';
+
+const pageStyle = tw(commonPrintStyles.page);
+</script>
+
+<template>
+  <div class="w-[640px] bg-white" :style="pageStyle">
+    <PrintHeader title="Invoice" reference="INV-2044" logo-text="ACME" />
+    <PrintSection title="Customer">
+      <PrintInfoRow label="Name" value="Acme Inc." />
+    </PrintSection>
+    <PrintTable>
+      <PrintTableHeader>
+        <PrintTableCell is-header :flex="3">Item</PrintTableCell>
+        <PrintTableCell is-header text-align="right">Amount</PrintTableCell>
+      </PrintTableHeader>
+      <PrintTableRow>
+        <PrintTableCell :flex="3">Consulting</PrintTableCell>
+        <PrintTableCell text-align="right">{{ formatAmount(1200, 'USD') }}</PrintTableCell>
+      </PrintTableRow>
+    </PrintTable>
+    <PrintTotals>
+      <PrintTotalRow label="Total" :value="formatAmount(1200, 'USD')" last />
+    </PrintTotals>
+  </div>
+</template>
+```
+
+Parts: `PrintHeader`, `PrintSection`, `PrintInfoRow`, `PrintCard`,
+`PrintCardField`, `PrintTable`, `PrintTableHeader`, `PrintTableRow`,
+`PrintTableCell`, `PrintTotals`, `PrintTotalRow`, `PrintBadge`, plus `tw`,
+`commonPrintStyles`, `formatAmount` and `formatDate`.
+
+`PrintHeader` with your logo, a subtitle and a QR code:
+
+```vue
+<script setup lang="ts">
+import { PrintHeader } from '@nxgt/material-vue/components';
+
+defineProps<{ qr: string }>(); // a data URL, rendered beforehand
+</script>
+
+<template>
+  <PrintHeader
+    title="Invoice"
+    subtitle="Acme Inc."
+    reference="INV-2044"
+    reference-prefix="No. "
+    :logo="{ src: '/logo.png', width: 96, height: 32 }"
+    :qr-data-url="qr"
+  />
+</template>
+```
+
+**Changed in 0.22.0:** with no `logo` and no `logo-text`,
+`PrintHeader` no longer draws a grey "LOGO" placeholder, and with no
+`qr-data-url` no empty QR box; the title stays centred. Pass `logo-text="LOGO"`
+to keep the old box.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `PrintHeader` `title` / `subtitle` | `string` | — | document title (required), and a smaller line under it |
+| `PrintHeader` `reference` / `referencePrefix` | `string` | — / `'#'` | the document's number, printed after `referencePrefix` (`#INV-2044`) |
+| `PrintHeader` `logo` | `string \| { src, width?, height? }` | — | a URL or data URL on the left, `72`×`48` pt by default, scaled to fit (`object-fit: contain`) |
+| `PrintHeader` `logoAlt` | `string` | `''` | Vue only: the logo's alt text; empty marks it decorative, as the title beside it usually names the issuer |
+| `PrintHeader` `logoText` | `string` | — | text in a grey box on the left when there is no `logo`; no box when neither is given |
+| `PrintHeader` `qrDataUrl` | `string \| null` | — | a QR code image (data URL) on the right; no box without one |
+| `PrintTableCell` `flex` | `number` | `1` | column width share |
+| `PrintTableCell` `textAlign` / `isHeader` | `'left' \| 'right' \| 'center'` / `boolean` | `'left'` / `false` | alignment; header styling |
+| `PrintTableRow` `isAlt` | `boolean` | `false` | zebra background |
+| `PrintTotalRow` `label` / `value` / `last` | `string` / `string` / `boolean` | — | a totals line; `last` makes it bold |
+| `PrintBadge` `color` | `string` | — | badge background |
+
+**Storybook:** `Media & files/Print` · **React:** `@nxgt/material/print` (same part names, rendered with `@react-pdf/renderer`)
+
+---
+
+## 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-vue/map`, with `leaflet` and
+`@vue-leaflet/vue-leaflet` as **optional peer dependencies** (install them to
+use it), and its stylesheet is `@nxgt/material-vue/map.css`, which is not part
+of `styles.css`. The entry imports cleanly under SSR, but leaflet only
+initialises in a browser: in Nuxt wrap the map in `<ClientOnly>`. The Nuxt
+module does not auto-register these components — import them where you use
+them. The [maps guide](../guides/maps.md) covers the peers, SSR and the defaults.
+
+```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]" />
+  </Map>
+</template>
+```
+
+Parts: `Map` (also exported as `MapComponent`), `Marker`, `LocationMarker`,
+`LocationPreview`, `MapActions`, `LocationField` · `LocationFormField`,
+`useGeolocation`. React's `MinimapControl` has no Vue counterpart.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `center` | `[number, number]` | visitor's geolocation, else `[5.44087, 10.06843]` | where the map opens. `Map` asks for location permission whether or not you pass it ([maps](../guides/maps.md#map)) |
+| `zoom` | `number` | `13` | initial zoom |
+| `scrollWheelZoom` | `boolean` | `false` | the wheel scrolls the page, not the map |
+| `zoomControl` | `boolean` | `false` | leaflet's own control; the component already renders one |
+| `Marker` `position` | `[number, number]` | — (required) | where the pin goes; `draggable`, `reference` (the reference pin) |
+
+A `LocationField` with a `null` value shows an empty input with a translated
+placeholder (`material.location-field.placeholder`); OK on an empty field
+commits where the pin was last dragged, or its start. Its dialog title and
+button come from `material.location-field.dialog-title` and `.confirm`;
+`placeholder`, `dialog-title` and `close-label` override them:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { LocationField } from '@nxgt/material-vue/map';
+
+const position = ref<[number, number] | null>(null);
+</script>
+
+<template>
+  <LocationField v-model="position" label="Venue" placeholder="Pick the venue" />
+</template>
+```
+
+**Emits:** `LocationField` `update:modelValue` — `[number, number]`, on each
+drag end and on OK when the field was empty.
+**Form wrapper:** `LocationFormField` — `name` inside a vee-validate form, see [forms](../guides/forms.md#the-pair).
+**Storybook:** `Media & files/Map` · **React:** `Map`, `LocationField`, `LocationFormField` (`@nxgt/material/map`)
+
+---
+
+## Not documented here
+
+Nothing in this category is left out. `Camera`, which `@nxgt/material` keeps
+to Storybook, is exported here — see [Camera](#camera).