@nxgt/material 2.4.2 → 2.6.0

package/docs/components/data-table-filter-and-lists.md

@@ -23,7 +23,7 @@ each other, so either can be used alone.
 
 ![DataTable](../previews/data-table-filter-lists-datatable.webp)
 
-TanStack Table v9 with sorting, filtering, selection, expandable rows, pagination or load-more, and column visibility.
+TanStack Table v9 with sorting, filtering, selection, expandable rows, pagination or load-more, column visibility, skeleton rows while loading and your own empty state.
 
 ```tsx
 import {
@@ -52,7 +52,8 @@ function PeopleTable({ people }: { people: Person[] }) {
 
 Parts: `DataTable`; `DataTableColumnHeader` (a sortable header with a hide
 action); `DataTablePagination` and `DataTableViewOptions` (used by the table,
-exported for a table of your own); `useColumnHelpers<T>()` returns a
+exported for a table of your own; `DataTablePagination` takes `disabled`);
+`useColumnHelpers<T>()` returns a
 `columnHelper` bound to the table's features and `predefinedColumns()` —
 `select` (checkboxes) and `expand` (a toggle for `renderExpandedRow`, named
 "Toggle row details" (`material.table.labels.toggle-row`) with `aria-expanded`);
@@ -71,6 +72,61 @@ table enables, for typing your own column defs.
 | `onLoadMore` / `isLoadingMore` | `() => void` / `boolean` | — | adds a "load more" button under the rows |
 | `options` | `{ showPage?: boolean; showSelected?: boolean }` | both `true` | parts of the footer |
 | `showHeader` | `boolean` | hidden on mobile | header row |
+| `loading` | `boolean` | `false` | skeleton rows, or the current rows dimmed; `aria-busy`; controls disabled |
+| `loadingRows` | `number` | the page size | how many skeleton rows |
+| `empty` | `ReactNode \| ({ filtered }) => ReactNode` | icon and "No data available" | content of the empty row, spanning every visible column |
+
+### Loading and empty states
+
+```tsx
+import { DataTable, useColumnHelpers } from '@nxgt/material/components';
+
+type Person = { id: string; name: string; email: string };
+
+function PeopleTable({
+  people,
+  isFetching,
+}: {
+  people: Person[];
+  isFetching: boolean;
+}) {
+  const { columnHelper } = useColumnHelpers<Person>();
+  const columns = [
+    columnHelper.accessor('name', { header: 'Name' }),
+    columnHelper.accessor('email', { header: 'Email' }),
+  ];
+
+  return (
+    <DataTable
+      data={people}
+      columns={columns}
+      loading={isFetching}
+      loadingRows={5}
+      empty={({ filtered }) =>
+        filtered ? 'No person matches these filters.' : 'No people yet.'
+      }
+    />
+  );
+}
+```
+
+While `loading` is `true`, the table is `aria-busy` and a visually
+hidden status says "Loading data…" (`material.table.loading`). With no row to
+show, the body is `loadingRows` skeleton rows (default: the page size), one
+cell per visible column. With rows already shown — a refresh — the rows stay
+where they are, dimmed and `inert`, rather than being swapped for
+skeletons: the table keeps its height, so nothing below it jumps when the data
+arrives. Sorting (`DataTableColumnHeader`), the `select` column's "Select
+all", the toolbar's native controls (it
+is a disabled `<fieldset>`, so every input or button you render there, a
+filter or an export, is disabled
+too) and pagination are disabled meanwhile.
+
+When no row is left after filtering, the empty state is one `TableEmpty`
+cell spanning every visible column: today's icon and "No data available" by
+default, or your own content, told whether rows exist but none matches the
+filters (`filtered`); content that renders nothing gets the default.
+`DataTableEmpty` and `DataTableEmptyState` type the prop and its argument.
 
 For the TanStack API itself (column helpers, features, row models), see
 [TanStack Table v9](https://tanstack.com/table/latest).
@@ -116,7 +172,10 @@ const schema: FilterSchema = {
 A field's `type` is one of `text`, `number`, `select`, `multi-select`, `date`,
 `date-range`, `number-range`, `checkbox-group`, `radio-group`,
 `chips-multiple`, `chips-single`, `slider`, `slider-range`, `switch` or
-`custom`; `schema.groups` puts fields in collapsible sections.
+`custom`; `schema.groups` puts fields in collapsible sections. A
+`number-range` or `slider-range` is a `role="group"` named by its `label`,
+with its inputs named by their part ("Min" / "Max", or the slider's
+"<label> Minimum" / "<label> Maximum"): `getByRole('group', { name: 'Price' })`.
 
 Parts: `Filter` (one component, `variant` picks the layout);
 `FilterProvider` + `FilterContent` + `FilterActions` to lay the panel out
@@ -174,9 +233,39 @@ import { PaginationBar } from '@nxgt/material/components';
 <PaginationBar page={page} pageCount={12} onPageChange={setPage} />
 ```
 
+```tsx
+import {
+	Pagination,
+	PaginationContent,
+	PaginationFirst,
+	PaginationItem,
+	PaginationLast,
+	PaginationLink,
+} from '@nxgt/material/components';
+
+<Pagination>
+	<PaginationContent>
+		<PaginationItem>
+			<PaginationFirst href="?page=1" />
+		</PaginationItem>
+		<PaginationItem>
+			<PaginationLink href="?page=2" isActive>
+				2
+			</PaginationLink>
+		</PaginationItem>
+		<PaginationItem>
+			<PaginationLast href="?page=12" />
+		</PaginationItem>
+	</PaginationContent>
+</Pagination>;
+```
+
 Parts: `Pagination`, `PaginationContent`, `PaginationItem`,
-`PaginationLink` (`isActive`), `PaginationPrevious`, `PaginationNext`,
-`PaginationEllipsis` for link-based pagination; `PaginationBar` for the
+`PaginationLink` (`isActive`), `PaginationFirst`, `PaginationPrevious`,
+`PaginationNext`, `PaginationLast`, `PaginationEllipsis` for link-based
+pagination (first / previous / next / last take an optional `label` and
+`icon`; their names are translated, `material.pagination.*`, and the text
+hides below `sm`); `PaginationBar` for the
 stateful one; `paginationItems(page, pageCount, siblingCount)` for the
 window alone.
 
@@ -188,7 +277,7 @@ window alone.
 | `siblingCount` | `number` | `1` | pages shown on each side of the current one |
 | `disabled` | `boolean` | — | disables every button |
 
-**Storybook:** `Data table, filter & lists/Pagination` · **Vue:** `Pagination` (parts), `PaginationFirst`, `PaginationLast`
+**Storybook:** `Data table, filter & lists/Pagination` · **Vue:** `Pagination` (parts), `PaginationFirst`, `PaginationLast`, `PaginationLink`, `PaginationBar`, `paginationItems`
 
 ---
 
@@ -230,6 +319,11 @@ own) and `TreeItem` (one row); `findTreeNode` and `flattenVisibleTree`.
 Arrow keys move and expand / collapse, Home / End jump, Enter and Space
 select.
 
+Tab lands on the focused row, or on the first visible row when that one is
+filtered or folded away; mounting a `Tree` does not move focus. `useTree`
+returns that row as `tabbableId`: give it `tabindex="0"` in a tree you build
+yourself.
+
 **Storybook:** `Data table, filter & lists/Tree` · **Vue:** `Tree`, `TreeItem`, `useTree`
 
 ---

package/docs/components/date-and-time.md

@@ -105,7 +105,7 @@ calendar is labelled by the trigger, so named by the label.
 **Emits:** `Date | undefined`.
 **Form wrapper:** `DateFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Date & time/DateField` · **Vue:** `DateField`, `DateFormField`
+**Storybook:** `Date & time/DateField` · **Vue:** `DateField`, `DateFormField` (`disabled-days`, same rules)
 
 ---
 
@@ -113,7 +113,7 @@ calendar is labelled by the trigger, so named by the label.
 
 ![DateRangeField](../previews/date-time-daterangefield.webp)
 
-From / to range picked in a popover calendar.
+From / to range picked in a popover calendar, with presets and times.
 
 ```tsx
 import { type DateRange, DateRangeField } from '@nxgt/material/components';
@@ -128,10 +128,13 @@ export function Stay() {
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `value` | `DateRange` | — | `{ from: Date \| undefined; to?: Date }` |
-| `onValueChange` | `(value?: DateRange) => void` | — | called on each click: `to` is unset after the first |
+| `onValueChange` | `(value?: DateRange) => void` | — | called on each click: after the first, `to` is the same day as `from` |
 | `placeholder`, `label`, `helperText`, `error`, `required` | | — | `placeholder` is the trigger's text; `label` and `helperText` sit beside it; `error` and `required` its state |
 | `disabled` | `boolean` | — | disables the field: the trigger cannot be focused or opened |
 | `disabledDays` | react-day-picker's `Matcher \| Matcher[]` | — | days that cannot be picked (the calendar's `disabled`) |
+| `presets` | `readonly DateRangePresetOption[]` | — (no list) | one-click ranges beside the calendar: built-in ids (`DATE_RANGE_PRESET_IDS`) and `{ label, range }` of your own |
+| `withTime` | `boolean` | `false` | a time of day on each end, under the calendar, and on the trigger; the popover stays open until OK |
+| `minDate`, `maxDate` | `Date` | — | the first and last day that can be picked (the calendar's, as are `disablePast` / `disableFuture`) |
 
 Every other `Calendar` prop is passed to the calendar; it opens on the
 month of `value.from`. `id`, `aria-describedby` and `data-*` attributes go on
@@ -148,11 +151,103 @@ trigger in the field's root `div` (`data-slot="date-range-field"`, which takes
 rendered alone, shows only the value: use the field for the label and the
 helper text. The open calendar is labelled by the trigger.
 
-**Emits:** `DateRange | undefined` — `{ from, to }`, where `to` stays
-`undefined` until the second day is picked.
+### Presets
+
+`presets` lists one-click ranges beside the calendar (above it on a narrow
+screen), in the order you give them. A built-in id is translated
+(`material.date-range-field.preset.<id>`); a preset of your own is
+`{ label, range }`, where `range` is `{ from, to }` or `(now) => ({ from, to })`.
+
+```tsx
+import {
+	type DateRange,
+	DateRangeField,
+	type DateRangePreset,
+} from '@nxgt/material/components';
+import { useState } from 'react';
+
+const lastQuarter: DateRangePreset = {
+	label: 'Last quarter',
+	range: (now) => {
+		const start = new Date(now.getFullYear(), Math.floor(now.getMonth() / 3) * 3 - 3, 1);
+		return { from: start, to: new Date(start.getFullYear(), start.getMonth() + 3, 0) };
+	},
+};
+
+export function Report() {
+	const [period, setPeriod] = useState<DateRange | undefined>();
+	return (
+		<DateRangeField
+			label="Period"
+			value={period}
+			onValueChange={setPeriod}
+			maxDate={new Date()}
+			presets={['today', 'last-7-days', 'this-month', 'last-month', lastQuarter]}
+		/>
+	);
+}
+```
+
+| Built-in id | Range |
+| --- | --- |
+| `today`, `yesterday` | that day |
+| `last-7-days`, `last-30-days` | ends today and counts it |
+| `this-month`, `this-year` | from the first day to today |
+| `last-month` | the whole previous month |
+
+A built-in range starts at 00:00 (and with `withTime` ends at 23:59); your
+own ranges keep the times you gave them. Picking a preset sets the value and
+closes the popover (with `withTime` it stays open); open again, the calendar
+is on that range's month. The list is a group named "Presets"
+(`material.date-range-field.presets`) of buttons in the tab order, and the
+one whose days are the value's has `aria-pressed="true"`. A preset is
+disabled when its range starts before `minDate`, ends after `maxDate`, or
+either end is one of `disabledDays`; the days between are not checked, as the
+calendar lets a range span a disabled day.
+The built-in presets use the current date when the popover opens; there is
+no `now` prop, and none is planned. A preset of your own whose end comes
+before its start is disabled.
+
+### Times
+
+`withTime` adds two `TimePicker`s under the calendar, in groups named
+"Start time" and "End time" (`material.date-range-field.start-time`,
+`.end-time`), each disabled until its end has a day, and an OK button
+(`material.buttons.ok`) that closes the popover. The trigger shows each end
+with its time (date-fns `Pp`).
+
+```tsx
+import { type DateRange, DateRangeField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Booking() {
+	const [slot, setSlot] = useState<DateRange | undefined>();
+	return (
+		<DateRangeField
+			label="Booking"
+			value={slot}
+			onValueChange={setSlot}
+			withTime
+			presets={['today']}
+		/>
+	);
+}
+```
+
+A day picked on the calendar keeps the time that end had; a new start is
+00:00 and a new end 23:59, as a built-in preset ends, so a filter on
+`<= to` keeps the last day. On the same day, an end time set before the
+start time becomes the start time.
+
+Without `withTime`, a picked day is at 00:00. (`@nxgt/material-vue` gives
+it the current time of day.)
+
+**Emits:** `DateRange | undefined` — `{ from, to }`, where the first day
+picked is both `from` and `to` (react-day-picker's `addToRange`) until the
+second day is picked.
 **Form wrapper:** `DateRangeFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Date & time/DateRangeField` · **Vue:** `DateRangeField`, `DateRangeFormField`
+**Storybook:** `Date & time/DateRangeField` (stories `DisabledDays`, `MinMaxDates`, `Presets`, `DisabledPresets`, `WithTime`) · **Vue:** `DateRangeField`, `DateRangeFormField` (`disabled-days`, `presets`, `with-time`, `min-date` / `max-date`; without time, a picked day carries the current time of day there, 00:00 here)
 
 ---
 
@@ -235,6 +330,11 @@ export function Clock() {
 | `label` | `ReactNode` | — | header text |
 | `footer` | `ReactNode` | — | under the inputs (the OK button in `TimeField`) |
 
+The hours and minutes inputs are named "Hours" and "Minutes"
+(`material.time-picker.hours`, `.minutes`). AM / PM shows the half of the day
+`date` is in, so a date changed from outside shows its own; switching it moves
+the time 12 hours, and a click on the pressed half changes nothing.
+
 **Emits:** `Date | undefined`. No form wrapper — use `TimeFormField`.
 **Storybook:** `Date & time/TimePicker` · **Vue:** `TimePicker`
 

package/docs/components/feedback-and-status.md

@@ -227,7 +227,7 @@ built on `AlertDialog`, so it does not close on an outside click. Put
 `AlertDialogCancel` / `AlertDialogAction` in its `footer`.
 
 **Storybook:** `Feedback & status/ConfirmDialog`, `Feedback & status/ConfirmationDialog`,
-`Feedback & status/CustomAlertDialog` · **Vue:** `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog`
+`Feedback & status/CustomAlertDialog` · **Vue:** `ConfirmDialog`, `ConfirmationDialog` (`form-options` + `#form` slot for `renderForm`), `CustomAlertDialog`
 
 ---
 
@@ -415,7 +415,7 @@ toasts.dismiss(id);
 | --- | --- | --- | --- |
 | `title` / `description` | `ReactNode` | preset title for `success`, `error`, `loading` | toast text |
 | `icon` | `ReactNode` (`toast`) · icon name (`toasts.custom`) | preset icon | leading icon |
-| `action` | `{ label, onClick? }` or `(dismiss) => ReactNode` | a translated “Close” for `success`, `info`, `error` | trailing button |
+| `action` | `ToastAction`: `{ label, onClick? }` or `(dismiss) => ReactNode` | a translated “Close” for `success`, `info`, `error` | trailing button: `onClick`, then the toast closes; or what the function renders, given `dismiss` |
 | `options` | Sonner `ExternalToast` | `duration: 5000` for presets, `Infinity` for `loading` | passed to Sonner (`id`, `duration`, `position`…) |
 
 The toast id defaults to the title, so two toasts with the same title
@@ -423,7 +423,8 @@ replace each other; pass `options: { id }` to show both. `Toaster` is Sonner's
 and takes its props (`position`, `expand`, `richColors`…). `Toast` is the
 component each toast renders, for use with `sonnerToast.custom`.
 
-**Storybook:** `Feedback & status/Toast` · **Vue:** `Toaster`, `toast`, `toasts`, `Toast`
+**Types:** `ToastAction`, `ToastProps`, `ToastMethodProps`.
+**Storybook:** `Feedback & status/Toast` · **Vue:** `Toaster`, `toast`, `toasts`, `Toast` (`ToastAction` type)
 
 ---
 

package/docs/components/form-fields.md

@@ -218,6 +218,7 @@ export function Quantity() {
 | `hideSteppers` | `boolean` | `false` | hides the +/− buttons |
 | `suffix` | `ReactNode` | — | unit after the input |
 | `aria-label` | `string` | — | names the input when it has no `label` (a part of a larger field) |
+| `aria-labelledby` | `string` | — | names the input by another element's id (a part of a larger field) |
 
 **Emits:** `number | null`.
 **Form wrapper:** `NumberFormField` — `control` and `name`, see
@@ -412,10 +413,41 @@ export function Code() {
 | `error` | `boolean` | — | error colour on the slots |
 | `id` | `string` | from `useId()` | the input's id, which the label points to; the generated one is the same on the server and the client |
 
+`InputOTP`, `InputOTPGroup`, `InputOTPSlot` and `InputOTPSeparator` are the
+parts `OtpField` is built from (`input-otp`), for a layout of your own — no
+label, no helper text:
+
+```tsx
+import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Pin() {
+	const [pin, setPin] = useState('');
+	return (
+		<InputOTP aria-label="PIN" maxLength={4} value={pin} onChange={setPin}>
+			<InputOTPGroup>
+				<InputOTPSlot index={0} />
+				<InputOTPSlot index={1} />
+			</InputOTPGroup>
+			<InputOTPSeparator />
+			<InputOTPGroup>
+				<InputOTPSlot index={2} />
+				<InputOTPSlot index={3} />
+			</InputOTPGroup>
+		</InputOTP>
+	);
+}
+```
+
+`InputOTP` takes `input-otp`'s `OTPInput` props (`maxLength`, `value`,
+`onChange`, `pattern`, …) plus `containerClassName`; `InputOTPSlot` takes the
+`index` it shows; `InputOTPSeparator` is a `separator` with a dash, or your
+children.
+
 **Emits:** `string` (the digits typed so far).
 **Form wrapper:** `OtpFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Form fields/OtpField` · **Vue:** `OtpField`, `OtpFormField`, `InputOTP`
+**Storybook:** `Form fields/OtpField` · **Vue:** `OtpField`, `OtpFormField`, `InputOTP` (same parts)
 
 ---
 
@@ -475,10 +507,13 @@ import { InlineEdit } from '@nxgt/material/components';
 | `placeholder` | `string` | "Click to edit" | shown while empty |
 | `disabled` | `boolean` | `false` | read-only text |
 
+Enter, Escape, Save and Cancel return focus to the field, while a click
+elsewhere saves and leaves focus where it went.
+
 **Emits:** `string`, trimmed, on save only.
 **Form wrapper:** `InlineEditFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Form fields/InlineEdit` · **Vue:** `InlineEdit`
+**Storybook:** `Form fields/InlineEdit` · **Vue:** `InlineEdit`, `InlineEditFormField`
 
 ---
 
@@ -605,15 +640,25 @@ import { Slider } from '@nxgt/material/components';
 Each thumb (`role="slider"`) is named by an `aria-labelledby` or `aria-label`
 you pass, else by the label (a vertical slider does not show it, and it still
 names the thumbs); a range's thumbs add "Minimum" and "Maximum":
-`getByRole('slider', { name: 'Price Minimum' })`. `aria-invalid` (or `error`)
-goes on every thumb too, not on the root `span`.
+`getByRole('slider', { name: 'Price Minimum' })`. A labelled range is also a
+`role="group"` named by the label, and its readout inputs are named
+"Minimum" and "Maximum" (`material.slider.minimum` / `maximum`), so two range
+sliders are told apart. A single value's readout input is named as its thumb
+is, and "Value" (`material.slider.value`) when nothing names the slider.
+`aria-invalid` (or `error`) goes on every thumb too,
+not on the root `span`.
+
+`SliderField` is the same component under `@nxgt/material-vue`'s name (an
+alias, `SliderFieldProps` for its props), so code reads the same in both
+libraries; neither name is deprecated, and the full naming alignment is
+planned for 3.0.
 
 **Emits:** `number[]`. `SliderFormField` stores a plain `number` when the
 form's value is a number, and `number[]` when it is an array — the default
 value decides.
 **Form wrapper:** `SliderFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Form fields/Slider` · **Vue:** `Slider`, `SliderField`, `SliderFormField`
+**Storybook:** `Form fields/Slider` · **Vue:** `Slider`, `SliderField` (`ticks`, `leading` / `trailing` or their slots), `SliderFormField`
 
 ---
 
@@ -656,6 +701,11 @@ while the switch is on, from `checked` or, uncontrolled, from `defaultChecked` a
 `[data-checked="true"]` (a bare `[data-checked]` also matches rows that are
 off). `data-filed` says the same and is deprecated: it goes in 3.0.
 
+`SwitchField` is the same component under `@nxgt/material-vue`'s name (an
+alias, `SwitchFieldProps` for its props), so code reads the same in both
+libraries; neither name is deprecated, and the full naming alignment is
+planned for 3.0.
+
 **Emits:** `boolean`.
 **Form wrapper:** `SwitchFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).

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

@@ -11,6 +11,7 @@ them into a form.
 | <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 |
+| <img src="../previews/media-files-filepreview.webp" width="96" alt=""> | [FilePreview](#filepreview) | One file previewed by its type: image, PDF, video, audio, text, or a download card |
 | | [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 |
@@ -19,6 +20,7 @@ them into a form.
 | <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` |
+| <img src="../previews/media-files-camera.webp" width="96" alt=""> | [Camera](#camera) | Webcam preview with a start / stop toggle and a still capture |
 | | [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`) |
 
@@ -220,6 +222,75 @@ dropzone as well read the error twice, and the group still says it once
 
 ---
 
+## FilePreview
+
+![FilePreview](../previews/media-files-filepreview.webp)
+
+Previews one file, picked by its MIME type (else its extension): an image, a PDF, a video or audio file, the text of a text, JSON, CSV or Markdown file, and a download card for anything else.
+
+```tsx
+import { useState } from 'react';
+import { FilePreview } from '@nxgt/material/components';
+
+export function Attachment() {
+  const [file, setFile] = useState<File | null>(null);
+  return (
+    <>
+      <input type="file" onChange={(event) => setFile(event.target.files?.[0] ?? null)} />
+      {/* A File or Blob: shown through an object URL, revoked on change and unmount. */}
+      <FilePreview file={file} onError={(error) => console.warn(error)} />
+      {/* A URL: the kind comes from `type`, else the extension; `name` is the alt text. */}
+      <FilePreview file="/api/files/42" type="application/pdf" name="contract.pdf" />
+    </>
+  );
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `file` | `File \| Blob \| string \| null` | — | the file, or its URL; nothing renders without one. A URL must be `http(s):`, relative, `blob:`, or a `data:` URL of an image, video, audio, plain text, CSV, Markdown, JSON or PDF; any other (`javascript:`, `data:text/html`, and also a `data:` URL of XML, TSV or YAML) shows the error state, with no link and nothing loaded |
+| `type` | `string` | the `Blob`'s, or a `data:` URL's | MIME type; picks the kind before the extension does |
+| `name` | `string` | the `File`'s, else the URL's last segment | shown on the card, the image's alt text and the download's file name; "Untitled file" when there is none |
+| `maxTextBytes` | `number` | `262144` (`TEXT_PREVIEW_MAX_BYTES`, 256 KB) | how much of a text kind is read; past it, the preview shows the beginning and says so |
+| `onError` | `(error: unknown) => void` | — | the file could not be read (an HTTP error: `FilePreviewHttpError`, with its `status`; a refused URL: `FilePreviewUnsafeUrlError`) or shown (a broken image, video or audio file) |
+| `className`, other `<figure>` props | | | on the root `<figure>` |
+
+| Kind | Picked by | Renders |
+| --- | --- | --- |
+| `image` | `image/*`; `.png` `.jpg` `.jpeg` `.gif` `.webp` `.avif` `.svg` `.bmp` `.ico` | `<img>`, its alt text the file name |
+| `pdf` | `application/pdf`; `.pdf` | [`PdfReader`](#pdfreader), imported the first time a PDF is previewed; the card when the viewer cannot be loaded. A PDF the reader fails to open leaves the preview `ready`: `PdfReader` shows its own error, and `onError` is not called |
+| `video` | `video/*`; `.mp4` `.m4v` `.webm` `.ogv` `.mov` | `<video controls>` |
+| `audio` | `audio/*`; `.mp3` `.wav` `.ogg` `.oga` `.m4a` `.aac` `.flac` `.opus` | `<audio controls>` |
+| `json` | `application/json`, `text/json`, `*+json`; `.json` | [`JsonViewer`](data-display.md#codeblock) |
+| `markdown` | `text/markdown`, `text/x-markdown`; `.md` `.markdown` | [`Markdown`](data-display.md#markdown), rendered; its links are sanitized like any `Markdown`, but a remote image in it still loads, so an untrusted `.md` can make the browser request a URL of its choosing |
+| `csv` | `text/csv`, `application/csv`, `text/tab-separated-values`; `.csv` `.tsv` | the text, in a `<pre>` |
+| `text` | any other `text/*`, `application/xml`, `application/yaml`, `application/javascript`…; `.txt` `.log` `.xml` `.yaml` `.yml` `.ini` `.toml` | the text, in a `<pre>` |
+| `other` | anything else, `application/octet-stream` without a known extension | a [`FileCard`](data-display.md#card-presets): icon, name, size and type, and a Download link |
+
+A text kind is fetched (a URL) or read (a `Blob`) up to `maxTextBytes` and
+decoded with the `charset` of the response's `Content-Type` (or of the
+`Blob`'s `type`) when the browser's `TextDecoder` supports it, else as UTF-8;
+a JSON or Markdown file cut by the cap is shown as plain text, with "Showing
+the first 256.0 KB of this file." below it. The `<pre>` and the Markdown box
+are regions named "Contents of {name}"; they scroll and take focus, so a
+keyboard can scroll them.
+
+The root is a `<figure>` named "Preview of {name}", with `data-kind` and
+`data-state`: `pending` on the server and in the first client render — an
+empty placeholder, with no object URL made and nothing fetched, so it hydrates
+without a mismatch — then `loading` ("Loading preview…", put into a `status` live region that
+stays mounted, so it is announced), `ready`
+or `error` ("This file could not be previewed.", an `alert`, with a Download
+link when there is something to download). The kind comes from
+`fileKind({ type, name, url })`, exported too, from
+[`@nxgt/material-core/file-preview`](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/README.md#a-files-preview-file-preview).
+Every string is translated (`material.file-preview.*`, see the
+[i18n guide](../guides/i18n.md)).
+
+**Storybook:** `Media & files/FilePreview` · **Vue:** `FilePreview`
+
+---
+
 ## FilesFormField
 
 No preview: it has no story of its own. It is an [`Autocomplete`](selection-and-choice.md)
@@ -256,7 +327,7 @@ function Gallery() {
 | `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:** —
+**Storybook:** — · **Vue:** `FilesFormField`
 
 ---
 
@@ -633,6 +704,51 @@ No preview: it is [`StxPlayer`](#stxplayer) under another name
 
 ---
 
+## Camera
+
+![Camera](../previews/media-files-camera.webp)
+
+Webcam preview with a start / stop toggle and a still capture.
+
+```tsx
+import { Camera } from '@nxgt/material/components';
+
+export function Webcam() {
+	return (
+		<div className="w-[640px]">
+			<Camera />
+		</div>
+	);
+}
+```
+
+It asks for camera permission when it mounts, lists the devices, streams on
+the toggle and shows the captured photo beside the preview; the stream is
+stopped on unmount. **It renders in the browser only, after mount**
+(`clientOnly`): on the server, and on the first client render, it renders
+nothing, so it is safe in an SSR page. `Camera` takes the props of a `div`
+(`className`, …) and has no callback: the capture stays inside the
+component. Each `Camera` keeps its own state.
+
+`Camera` renders its own parts and takes no children. The helpers it runs
+are exported, and the first three are what a webcam UI of your own needs
+(`<video>` + `getUserMedia`):
+
+| Export | What it is |
+| --- | --- |
+| `capturePhotoFromVideo(video, state)` | draws a `<video>` frame on a canvas (`captureSettings`: resolution, quality, format, mirror) and returns `{ capturedImage }` as a data URL, `{ alert }` on failure, `null` when not streaming or on the server |
+| `isCameraSupported()`, `requestCameraPermissions()`, `getCameraDevices()` | the browser checks the component runs |
+| `useCamera()`, `useCameraContext()` | the context `Camera`'s own parts read (`{ videoRef, canvasRef, streamRef, state, actions }`); they throw outside `Camera`, and `Camera` exposes no slot, so they serve its internals and tests, as in `@nxgt/material-vue` |
+| `createCameraStore(preloaded?)` | the Redux store each `Camera` creates for itself, for tests |
+
+Types: `CameraProps`, `CameraState`, `CameraActions`, `CameraContextValue`,
+`CameraAlert`, `CameraDeviceInfo`, `CaptureSettings`, `ImageFormat`,
+`CapturePhotoResult`, `CameraStore`.
+
+**Storybook:** `Media & files/Camera` · **Vue:** `Camera`, `useCamera`, `capturePhotoFromVideo` (`useCameraStore` for the store)
+
+---
+
 ## Print components
 
 No preview: these render PDF with `@react-pdf/renderer`, not DOM, so there is
@@ -892,10 +1008,3 @@ Parts: `Map` (also exported as `MapComponent`), `Marker`, `LocationMarker`,
 
 **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.

package/docs/components/navigation-and-layout.md

@@ -437,6 +437,11 @@ Parts: `Stepper`, `StepperIndicator` (the progress bar alone: `current`,
 | `onChange` | `(index: number) => void` | — | makes steps clickable |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | vertical from `md` only; phones get the compact bar |
 | `renderStepLabel` | `(step, index) => ReactNode` | — | replaces the "Step n" caption |
+| `name` | `string` | — | the stepper's `data-pw` (`stepper` without it), and the prefix of each step's: `<name>-step-N` instead of `step-N` |
+
+Each step is an `<li>` with `data-pw="step-N"` (`<name>-step-N` with `name`),
+N counted from 0, for tests to select; the current step's button carries
+`aria-current="step"`, and a completed or failed step is announced as such.
 
 A server renders the desktop layout (every step), as does a hydrating client;
 a phone switches to the compact bar right after hydrating. A page rendered
@@ -550,7 +555,7 @@ On `DocPage`: `title`, `description`, `badge`, `crumbs`, `editHref`,
 `updatedAt`, and `copyPage` / `copyMarkdown` with `markdown` for the copy
 buttons.
 
-**Storybook:** `Navigation & layout/Doc`, `Navigation & layout/Doc/Api`, `Navigation & layout/Doc/Blocks` · **Vue:** `Doc`, `DocPage`, `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress`
+**Storybook:** `Navigation & layout/Doc`, `Navigation & layout/Doc/Api`, `Navigation & layout/Doc/Blocks` · **Vue:** `Doc`, `DocPage`, `DocTopbar`, `DocSidebar`, `DocNav`, `DocArticle`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress`, `DocLink`, `DefaultDocLink`, `DocCopyPage` (no `linkComponent`: `@navigate`)
 
 ---