@nxgt/material 2.1.0 → 2.2.0

package/README.md

@@ -5,37 +5,37 @@ drag-and-drop, i18n, and `Icon`. Tailwind CSS v4 + Base UI.
 
 ## At a glance
 
-- **155 catalogue entries in 12 categories** ([Components](#components)).
+- **168 catalogue entries in 12 categories**, nearly all with a preview
+  ([Components](#components), and the [gallery](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/README.md)).
   They cover primitives and overlays as well as data tables, filters, kanban,
   calendars, charts, chat, documentation pages, rich-text and code editors,
   PDF and media players.
 - **Form fields ship in pairs.** Each one has a standalone component
   (`TextField`) and a React Hook Form wrapper (`TextFormField`). Both are in
-  the same barrel.
-- **Helpers** ([Helpers](#helpers)): `cn`, `clientOnly`, date, number,
-  storage and URL utilities, a Zod error map, and Redux Toolkit slice
-  factories in `/lib`. Theme, i18n-aware formatting and option hooks are in
-  `/hooks`.
-- **i18n** ([i18n](#i18n)): an `I18nProvider` with ICU messages and shipped
-  `en` / `fr` strings. Your app merges in its own resources.
-- **SSR-safe barrels** ([SSR](#ssr)): no browser globals at import, and
-  browser-only widgets are wrapped in `clientOnly`.
-- **Vue sister**: `@nxgt/material-vue` uses the same names. The catalogue's
-  last column gives the Vue export for each entry.
+  the same barrel. The [forms guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/forms.md) covers validation,
+  composite values, config-driven forms and server errors.
+- **Helpers** ([helpers guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/helpers.md)): `cn`, `clientOnly`,
+  date, number, storage and URL utilities, a Zod error map, and Redux Toolkit
+  slice factories in `/lib`. Theme, i18n-aware formatting and option hooks are
+  in `/hooks`.
+- **i18n** ([i18n guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/i18n.md)): an `I18nProvider` with ICU
+  messages and shipped `en` / `fr` strings. Your app merges in its own
+  resources.
+- **SSR-safe barrels** ([SSR guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/ssr.md)): no browser globals at
+  import, and browser-only widgets are wrapped in `clientOnly`.
+- **Vue sister**: `@nxgt/material-vue` uses the same names, categories and
+  pages. The catalogue's last column gives the Vue export for each entry.
 
 ## Contents
 
 - [Install](#install)
 - [Setup](#setup)
 - [Subpaths](#subpaths)
-- [Upgrading to 2.0.0](#upgrading-to-200)
-- [Printing](#printing)
-- [Maps](#maps)
 - [Usage](#usage)
+- [Guides](#guides)
 - [Components](#components)
-- [Helpers](#helpers)
-- [SSR](#ssr)
 - [Traps](#traps)
+- [Documentation](#documentation)
 - [Development](#development)
 - [License](#license)
 
@@ -61,7 +61,17 @@ bun add react react-dom react-hook-form react-redux @reduxjs/toolkit @tanstack/r
 | `@tanstack/react-table` `^9` | `DataTable` |
 | `react-use` `^17` | `useTheme`, `useIsMobile`, `ScrollProgress` (`useScroll` / `useWindowScroll`), `CopyButton` (`useCopyToClipboard`), other hooks |
 
-The tarball is `dist/`, not `lib/`. There is no `postinstall` build.
+**Optional peers**, installed only by the app that imports the entry needing
+them: `@react-pdf/renderer` `^4.9` and `react-pdf-tailwind` `^3` for
+`@nxgt/material/print`; `leaflet`, `react-leaflet`, `@react-leaflet/core`,
+`@adamscybot/react-leaflet-component-marker` and `react-geolocated` for
+`@nxgt/material/map`. The [printing](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/printing.md)
+and [maps](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/maps.md) guides have the install line.
+
+The tarball is the built `dist/`, plus the Tailwind source stylesheet
+(`lib/styles.css` and the component stylesheets it imports,
+`lib/components/**/*.css`), `lib/map/map.css` and `docs/`. There is no
+`postinstall` build.
 
 ## Setup
 
@@ -112,650 +122,394 @@ into a tarball. A missing sheet renders nothing, with no error and no fallback.
 | --- | --- |
 | `@nxgt/material` | Everything below in one barrel, plus the compiled `style` condition (`dist/material.css`, for apps without Tailwind) |
 | `@nxgt/material/components` | UI components and `*FormField` wrappers ([Components](#components)) |
-| `@nxgt/material/print` | PDF documents over `@react-pdf/renderer` — **its own entry, and not in the barrel above** ([Printing](#printing)) |
-| `@nxgt/material/map` | Leaflet maps, markers, a location field — **its own entry, not in the barrel, and browser-only** ([Maps](#maps)) |
-| `@nxgt/material/vite` | build-time helpers for consumers: `pdfkitStandardFonts()` ([Printing](#printing)) |
-| `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useIsMobile`, `useLocalizedDate`, … ([hooks](#nxgtmaterialhooks)) |
-| `@nxgt/material/dnd` | `@dnd-kit` primitives ([dnd](#nxgtmaterialdnd)) |
-| `@nxgt/material/i18n` | `I18nProvider`, `mergeResources`, `createTranslator` ([i18n](#nxgtmateriali18n)) |
-| `@nxgt/material/lib` | `cn`, `clientOnly`, date, number and storage utilities, `useSliceReducer` ([lib](#nxgtmateriallib)) |
+| `@nxgt/material/print` | PDF documents over `@react-pdf/renderer`: the `PrintDocument` page shell, the print blocks, and `PrintDataTable`, `PrintKeyValue` and `PrintMetric` from column definitions and plain rows; documents as plain data (`pdfDocument` and its builders); `downloadPdf`, `openPdf`, `usePdfFile` and `pdfResponse` to get the file in one call — **its own entry, and not in the barrel above** ([printing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/printing.md)) |
+| `@nxgt/material/map` | Leaflet maps, markers, a location field — **its own entry, not in the barrel, and browser-only** ([maps guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/maps.md)) |
+| `@nxgt/material/vite` | build-time helpers for consumers: `pdfkitStandardFonts()` ([printing guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/printing.md)) |
+| `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useIsMobile`, `useLocalizedDate`, … ([helpers](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/helpers.md#nxgtmaterialhooks)) |
+| `@nxgt/material/dnd` | `@dnd-kit` primitives ([helpers](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/helpers.md#nxgtmaterialdnd)) |
+| `@nxgt/material/i18n` | `I18nProvider`, `mergeResources`, `createTranslator` ([i18n guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/i18n.md)) |
+| `@nxgt/material/lib` | `cn`, `clientOnly`, date, number and storage utilities, `useSliceReducer` ([helpers](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/helpers.md#nxgtmateriallib)) |
 | `@nxgt/material/models` | `Status<T>` |
 | `@nxgt/material/types` | shared function types (`PromiseOr`, `FunctionOr`, …) |
 | `@nxgt/material/styles.css` | source Tailwind v4 tokens. **This** is the file the app imports |
 | `@nxgt/material/map.css` | leaflet's stylesheet, for the apps that use `./map`. Not part of `styles.css` |
 
-## Upgrading to 2.0.0
-
-**One breaking change: the print components moved out of the barrel.**
-
-```diff
--import { PrintHeader, PrintTable, tw } from '@nxgt/material';
-+import { PrintHeader, PrintTable, tw } from '@nxgt/material/print';
-```
-
-and, in the app that prints, install what is now an optional peer:
-
-```sh
-bun add @react-pdf/renderer react-pdf-tailwind
-```
-
-Nothing else changed. If your app does not render PDFs there is nothing to do —
-and you gain the thing this release is for: `@react-pdf/renderer` and `pdfkit`
-are no longer in your dependency graph. See [Printing](#printing).
-
-**`formatAmount` and `formatDate` are on the barrel again, from 2.1.0.** They
-went into `@nxgt/material/print` with the components in 2.0.0, which was wrong:
-they are pure `Intl` helpers, they depend on nothing, and a screen that formats
-an amount should not have to import the entry that drags in `pdfkit` — or to
-install two optional peers it has no use for.
-
-```ts
-import { formatAmount, formatDate } from '@nxgt/material';        // 1.x, and 2.1.0+
-import { formatAmount, formatDate } from '@nxgt/material/lib';    // also
-import { formatAmount, formatDate } from '@nxgt/material/print';  // still, for print documents
-```
-
-On **2.0.0 and 2.0.1 only**, `@nxgt/material/print` is the single place they can
-be imported from. Take 2.1.0 instead of rewriting those imports.
-
-## Printing
-
-`@nxgt/material/print` renders PDF documents with `@react-pdf/renderer`
-(`PrintHeader`, `PrintSection`, `PrintCard`, `PrintTable`, `PrintTotals`,
-`PrintBadge`, plus `tw` and the shared styles). It also re-exports
-`formatAmount` and `formatDate`, so a print document takes everything from one
-import — but those two are pure `Intl` helpers and live on the main barrel and
-`@nxgt/material/lib` as well, for the screens that format the same values.
+## Usage
 
 ```tsx
-import { Document, Page } from '@react-pdf/renderer';
-import { PrintHeader, PrintTable } from '@nxgt/material/print';
-```
-
-It is a **separate entry on purpose**, not for tidiness. `@react-pdf/renderer`
-reaches `pdfkit`, and pdfkit loads its fourteen standard fonts through
-`createRequire(import.meta.url)('#standard-fonts/<name>')` — a package-`imports`
-specifier private to pdfkit, called at runtime, which no bundler resolves. Bundle
-it into an SSR server and the literal survives into the artifact, where
-`createRequire` is rooted at the build directory: the server then throws on
-**every request**, `/health` included, and a container healthcheck never goes
-healthy. Three apps shipped that way before the split; until 2.0.0 the plain
-`import '@nxgt/material'` was enough to inherit it.
-
-If you do print from a bundled SSR server, pick by one fact — whether the runtime
-image keeps a `node_modules`:
-
-| Runtime image | What to do |
-| --- | --- |
-| Keeps `node_modules` | leave the library external: `@nxgt/material` **out** of `ssr.noExternal`, and `--external @nxgt/material` in the bundle step. Also keeps ~12 MB of pdfkit out of the artifact |
-| Ships the bundle alone | `pdfkitStandardFonts()` from `@nxgt/material/vite`, first in `plugins` — it inlines the font data so the artifact stays self-contained |
-
-```ts
-import { pdfkitStandardFonts } from '@nxgt/material/vite';
+import { Button, Icon, TextFormField } from '@nxgt/material/components';
+import { useForm } from 'react-hook-form';
 
-export default defineConfig({
-  plugins: [pdfkitStandardFonts(), reactRouter()],
-});
+function InviteForm({ onSubmit }: { onSubmit: (v: { email: string }) => void }) {
+  const form = useForm({ defaultValues: { email: '' } });
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      <TextFormField control={form.control} name="email" label="Email" />
+      <Button type="submit" variant="filled" color="primary">
+        <Icon name="paper-plane" />
+        Invite
+      </Button>
+    </form>
+  );
+}
 ```
 
-`resolve.alias` does not help (the specifier never reaches the resolver) and
-neither does `--external pdfkit` (transitive, so unresolvable from the app).
+`TextFormField` is the React Hook Form wrapper of `TextField`; every field has
+the same pair. [Getting started](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/getting-started.md) walks through a first
+screen.
 
-## Maps
-
-`@nxgt/material/map` renders Leaflet maps: `Map`, `Marker`, `LocationMarker`,
-`LocationPreview`, `MapActions`, `MinimapControl`, the `LocationField` /
-`LocationFormField` pair, and the `useGeolocation` hook they share.
-
-```sh
-bun add leaflet react-leaflet @react-leaflet/core \
-  @adamscybot/react-leaflet-component-marker react-geolocated
-```
+### Amounts and dates in your locale
 
 ```tsx
-import '@nxgt/material/map.css';
-import { LocationFormField } from '@nxgt/material/map';
-```
-
-Those five are **optional peers**, exactly like `@react-pdf/renderer` is for
-[Printing](#printing): an app that renders no map never has leaflet in its tree.
+import { formatAmount, formatDate, createFormatters } from '@nxgt/material/lib';
+import { useFormatters } from '@nxgt/material/hooks';
 
-### What `Map` does when you pass nothing
+formatAmount(1234.5, 'EUR', { locale: 'fr-FR' });  // '1 234,50 €'
+formatAmount(1234.5, 'JPY', { locale: 'en-US' });  // '¥1,235': the currency's own decimals
+formatDate('2026-03-01', { locale: 'en-US' });     // 'Mar 1, 2026' in every time zone
 
-```tsx
-import { Map, Marker } from '@nxgt/material/map';
-
-<Map className="size-96">
-  <Marker position={[48.8566, 2.3522]} />
-</Map>
+const { formatAmount: amount } = useFormatters({ timeZone: 'Europe/Paris' }); // in a component: follows I18nProvider
+const server = createFormatters({ locale: 'fr-FR', timeZone: 'Europe/Paris' }); // outside React
 ```
 
-A `react-leaflet` `MapContainer` with an OpenStreetMap tile layer, a zoom control
-and an inset minimap. The defaults are not neutral:
-
-| Prop | Default | Why it matters |
-| --- | --- | --- |
-| `center` | the visitor's geolocation, falling back to `[5.44087, 10.06843]` (Yaoundé) | **omitting it asks the browser for location permission** — `Map` calls `useGeolocation` itself. Pass a `center` for a map that must not prompt. |
-| `zoom` | `13` | |
-| `scrollWheelZoom` | `false` | a map inside a scrolling page does not capture the wheel |
-| `showMinicardControl` | `true` | the inset minimap, at `topright`, `zoom={6}` |
-| `zoomControl` | `false` | leaflet's *own* control, off because the component renders one at `topleft`. Passing `true` gives you two. |
-
-`useGeolocation` is `react-geolocated` with `enableHighAccuracy: false` and a 5 s
-user-decision timeout, both overridable per call.
-
-**This entry cannot be imported without a DOM, and that is not a bug to fix in
-your app.** `leaflet` reads `window` while it is being evaluated, so
-`import 'leaflet'` in node or bun throws `window is not defined` before any of
-this library's code runs — and `react-leaflet`, `@react-leaflet/core` and the
-component-marker package all import leaflet. So:
-
-- **An SSR app renders these client-side only** — behind `clientOnly` from
-  `@nxgt/material/lib`, or in a `useEffect`. Rendering `<Map>` in a server pass
-  gives a blank page and `window is not defined` in the server log.
-- **An SPA has nothing to do.** There is no server pass to protect.
-- `bun run build` fails if any entry but `map.js` reaches leaflet, the same way
-  it does for print. `scripts/verify-ssr-safe.ts` also skips importing `map.js`
-  on purpose, and says so in its output rather than silently.
-
-This was the package `@nxgt/map` until 2026-09-22. It was extracted precisely
-because leaflet killed SSR consumers, and it came back because an optional-peer
-entry solves that without a second release train — and without the thing the
-split actually cost: `@nxgt/map` pinned `@nxgt/material: ^1.0.0`, so an app
-depending on both could not take the 2.x major at all.
-
-## Usage
+Since 2.2.0 each currency keeps its own decimals; `{ fractionDigits: 2 }` keeps
+two. Options and server rendering: [Printing](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/printing.md#formatamount-and-formatdate).
 
-### Components
+### A PDF from any source
 
 ```tsx
-import { Button, Icon } from '@nxgt/material/components';
+import { PdfReader } from '@nxgt/material/components';
 
-<Button variant="filled" color="primary">
-  <Icon name="plus" />
-  Add
-</Button>
+// blob: Blob, bytes: Uint8Array, token: string, from your app
+<PdfReader file="/documents/contract.pdf" />                        // a URL
+<PdfReader file={blob} fileName="INV-1042.pdf" />                    // a Blob or File, e.g. from @react-pdf/renderer
+<PdfReader file={bytes} />                                           // an ArrayBuffer or Uint8Array, copied
+<PdfReader file={{ url: '/api/documents/42', httpHeaders: { Authorization: `Bearer ${token}` } }} />
 ```
 
-### Form fields
+Give the parent a height. More: [PdfReader](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#pdfreader).
 
-Each field has a standalone component (`TextField`) and a React Hook Form
-wrapper (`TextFormField`) in the same barrel. The wrappers take `control` and
-`name`.
+### A printable PDF
 
 ```tsx
-import { TextFormField, Button } from '@nxgt/material/components';
-import { useForm } from 'react-hook-form';
+import { downloadPdf, formatAmount, pdfResponse, PrintDocument, PrintHeader, PrintInfoRow, PrintSection } from '@nxgt/material/print';
 
-const form = useForm({ defaultValues: { email: '' } });
+const invoice = (
+  <PrintDocument title="Invoice INV-42" language="fr" pageNumbers header={<PrintHeader title="Facture" reference="INV-42" />}>
+    <PrintSection title="Client">
+      <PrintInfoRow label="Total" value={formatAmount(1234.5, 'EUR', { locale: 'fr-FR' })} />
+    </PrintSection>
+  </PrintDocument>
+); // A4, "Page 1 sur 1" at the bottom of every page
 
-<form onSubmit={form.handleSubmit(onSubmit)}>
-  <TextFormField control={form.control} name="email" label="Email" />
-  <Button type="submit">Save</Button>
-</form>
-```
+// in the browser, from a click handler: saves INV-42.pdf
+export const onDownload = () => downloadPdf(invoice, { fileName: 'INV-42' });
 
-### i18n
-
-This package owns the i18n **mechanism**, and the app owns the resource
-**content**. This package's strings live under the `material` namespace.
-`mergeResources` deep-merges your bundle over it per language, so you can
-override one string (`material.command.title`) without losing the rest. Every
-overridden key is reported with `console.warn` outside production.
-
-```ts
-import {
-  I18nProvider,
-  createTranslator,
-  createTypedTranslation,
-  mergeResources,
-  resources as materialResources,
-  type FlatObject,
-} from '@nxgt/material/i18n';
-import { resources as appResources } from './resources';
-
-export const resources = mergeResources(materialResources, appResources);
-export type LocaleKey = keyof FlatObject<typeof resources.en, string>;
-export const translate = createTranslator<LocaleKey>(resources);
-export const useTranslation = createTypedTranslation<LocaleKey>(translate);
+// on a server (Node 18+ or Bun, not an edge runtime): a React Router loader, a Next route handler, Hono
+export const loader = () => pdfResponse(invoice, { fileName: 'INV-42' });
 ```
 
-```tsx
-<I18nProvider defaultLanguage="en">
-  <App />
-</I18nProvider>
-```
+`PrintDocument` replaces react-pdf's `Document` + `Page`: size, margins,
+metadata, a header and footer on every page, translated page numbers, a
+watermark. Its `language` is a prop, because the PDF renders outside your
+`I18nProvider`. `openPdf` opens a new tab, `usePdfFile` keeps a preview
+current, and a document can also be plain data built with `pdfDocument`
+(experimental). More: [Printing](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/printing.md#rendering-the-document).
 
-Language state lives only in `I18nProvider`. If the provider is not mounted,
-the components in this package fall back to their English copy. Messages use
-ICU MessageFormat, and a missing key is returned as-is.
+## Guides
 
-To translate Zod messages as well, add
-`z.config({ customError: zodLocaleError() })`, with `zodLocaleError` from
-`@nxgt/material/lib`.
-
-### App shell
-
-`items` is a prop: the shell does not build or filter the menu. Each `label`
-is already translated (a `ReactNode`), not a key. Set `footer: true` to pin an
-entry to the footer; being last in the list does not do it. `avatar` and
-`headerActions` are props too, because the shell holds no session.
-
-```tsx
-import { ActivityLayout, ActivityContent } from '@nxgt/material/components';
-
-const items = [
-  { label: 'Home', url: '/', icon: 'house' },
-  { label: 'Settings', url: '/settings', icon: 'gear', footer: true },
-];
-
-<ActivityLayout items={items} brand={<Logo />} avatar={<Avatar />}>
-  <Outlet />
-</ActivityLayout>
-```
+Each area a consumer starts from has its own page under `docs/guides/`.
 
-The active entry is the **longest** match across the whole menu. Matching is
-segment-aware, so `/admin` does not cover `/administrators`. `AppBreadcrumb`
-reads `handle.breadcrumb` from `useMatches()`, so it needs a data router
-(`createMemoryRouter` + `RouterProvider`, not `MemoryRouter`).
+| Guide | Read it when |
+| --- | --- |
+| [Forms](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/forms.md) | wiring fields to React Hook Form and Zod, composite values (contacts, opening hours), config-driven `Field`, server errors, what each field emits |
+| [i18n](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/i18n.md) | adding your strings next to the package's, switching language, translated Zod messages, SSR without a text mismatch |
+| [App shell](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/app-shell.md) | laying out an app with `ActivityLayout`, its `items`, the active entry and breadcrumbs (needs a data router) |
+| [Theming](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/theming.md) | changing colours, radius or fonts, dark mode, using the compiled CSS without Tailwind |
+| [Printing](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/printing.md) | producing PDFs with `@nxgt/material/print` and getting the file in one call (download, new tab, preview, server `Response`) — its own entry since 2.0.0, with optional peers and a bundling trap on SSR servers |
+| [Maps](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/maps.md) | using `@nxgt/material/map` — browser-only, optional leaflet peers, `map.css` |
+| [SSR](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/ssr.md) | rendering on a server: what the barrels guarantee, and `import()` + `clientOnly` for browser-only code |
+| [Helpers](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/helpers.md) | the non-component subpaths: `/lib`, `/hooks`, `/i18n`, `/models`, `/types`, `/dnd` |
+
+**Upgrading to 2.x**: print moved to `@nxgt/material/print` in 2.0.0, and
+`formatAmount` / `formatDate` are back on the main entry in 2.1.0, and 2.2.0
+needs `@react-pdf/renderer@^4.9` and drops `PrintHeader`'s `LOGO` placeholder. The diffs
+are in [Getting started](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/getting-started.md#upgrading-to-2x).
 
 ## Components
 
-Everything below is imported from `@nxgt/material/components`. In the
+Everything below is imported from `@nxgt/material/components`. Each name
+links to its entry in [`docs/components/`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/README.md) — the
+preview, an example and the options that matter. In the
 *Component* column, `·` separates a field from its React Hook Form wrapper.
 The last column gives the matching export in `@nxgt/material-vue`, or `—` when
 Vue has none. "(same parts)" means Vue exports the same sub-components.
 
 ### Primitives
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Collapsible sections with a rotating chevron and animated content. | `Accordion` (same parts) |
-| `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | A single show / hide region and its trigger. | `Collapsible` (same parts) |
-| `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | Card surface with header, action slot, content and footer. | `Card` (same parts) |
-| `Typography` | Text in the Material type scale (headline, title, body, caption…). | `Typography` |
-| `AnchorHeading` | Heading with a hover copy-link (always visible on the phone). | `AnchorHeading` |
-| `Label` | Form label with an optional required asterisk. | `Label` |
-| `HelperText` | Hint or error message under a field. | `HelperText` |
-| `ExtendedLabel` | Section title with an animated accent underline and a trailing slot. | `ExtendedLabel` |
-| `Input` | Styled native `<input>`. | `Input` |
-| `Textarea` | Styled native `<textarea>`. | `Textarea` |
-| `InputGroup`, `InputGroupAddon`, `InputGroupInput`, `InputGroupButton`, `InputGroupText`, `InputGroupTextarea` | Input with inline or block addons, buttons and text. | `InputGroup` (same parts) |
-| `Icon` | Font Awesome sprite icon by name and style (duotone by default), labelled with `role="img"`. | `Icon` |
-| `Kbd`, `KbdShortcut` | One keyboard key, or a key combination with platform glyphs. | `Kbd`, `KbdShortcut` |
-| `Separator` | Horizontal or vertical divider. | `Separator` |
-| `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption` | Styled semantic table inside a scrollable wrapper. | `Table` (same parts), `TableEmpty` |
-| `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | Tabs whose triggers can take an icon. `variant="line"` is the quieter pill style. | `Tabs` (same parts) |
-| `Toggle` | Pressable on / off button: default or outlined, three sizes. | `Toggle` |
-| `ToggleGroup`, `ToggleGroupItem`, `ToggleGroupSeparator` | Single or multiple toggle group sharing variant and size. | `ToggleGroup`, `ToggleGroupItem` |
-| `Activity` | React `<Activity>` switched by a boolean `visible`. | `Activity` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-accordion.webp" width="120" alt="Accordion"> | [`Accordion`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#accordion), `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Collapsible sections with a rotating chevron and animated content. | `Accordion` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-collapsible.webp" width="120" alt="Collapsible"> | [`Collapsible`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#collapsible), `CollapsibleTrigger`, `CollapsibleContent` | A single show / hide region and its trigger. | `Collapsible` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-card.webp" width="120" alt="Card"> | [`Card`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#card), `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | Card surface with header, action slot, content and footer. | `Card` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-typography.webp" width="120" alt="Typography"> | [`Typography`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#typography) | Text in the Material type scale (headline, title, body, caption…). | `Typography` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-anchorheading.webp" width="120" alt="AnchorHeading"> | [`AnchorHeading`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#anchorheading) | Heading with a hover copy-link (always visible on the phone). | `AnchorHeading` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-label.webp" width="120" alt="Label"> | [`Label`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#label) | Form label with an optional required asterisk. | `Label` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-helpertext.webp" width="120" alt="HelperText"> | [`HelperText`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#helpertext) | Hint or error message under a field. | `HelperText` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-extendedlabel.webp" width="120" alt="ExtendedLabel"> | [`ExtendedLabel`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#extendedlabel) | Section title with an animated accent underline and a trailing slot. | `ExtendedLabel` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-input.webp" width="120" alt="Input"> | [`Input`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#input) | Styled native `<input>`. | `Input` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-textarea.webp" width="120" alt="Textarea"> | [`Textarea`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#textarea) | Styled native `<textarea>`. | `Textarea` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-inputgroup.webp" width="120" alt="InputGroup"> | [`InputGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#inputgroup), `InputGroupAddon`, `InputGroupInput`, `InputGroupButton`, `InputGroupText`, `InputGroupTextarea` | Input with inline or block addons, buttons and text. | `InputGroup` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-icon.webp" width="120" alt="Icon"> | [`Icon`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#icon) | Font Awesome sprite icon by name and style (duotone by default), labelled with `role="img"`. | `Icon` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-kbd.webp" width="120" alt="Kbd"> | [`Kbd`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#kbd), `KbdShortcut` | One keyboard key, or a key combination with platform glyphs. | `Kbd`, `KbdShortcut` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-separator.webp" width="120" alt="Separator"> | [`Separator`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#separator) | Horizontal or vertical divider. | `Separator` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-scrollarea.webp" width="120" alt="ScrollArea"> | [`ScrollArea`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#scrollarea), `ScrollBar` | Scroll container with a thin custom scrollbar that matches the theme. | `ScrollArea`, `ScrollBar` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-table.webp" width="120" alt="Table"> | [`Table`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#table), `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption` | Styled semantic table inside a scrollable wrapper. | `Table` (same parts), `TableEmpty` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-tabs.webp" width="120" alt="Tabs"> | [`Tabs`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#tabs), `TabsList`, `TabsTrigger`, `TabsContent` | Tabs whose triggers can take an icon. `variant="line"` is the quieter pill style. | `Tabs` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-toggle.webp" width="120" alt="Toggle"> | [`Toggle`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#toggle) | Pressable on / off button: default or outlined, three sizes. | `Toggle` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/primitives-togglegroup.webp" width="120" alt="ToggleGroup"> | [`ToggleGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#togglegroup), `ToggleGroupItem`, `ToggleGroupSeparator` | Single or multiple toggle group sharing variant and size. | `ToggleGroup`, `ToggleGroupItem` |
+| — | [`Activity`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/primitives.md#activity) | React `<Activity>` switched by a boolean `visible`. | `Activity` |
 
 ### Buttons & actions
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `Button` | Filled, tonal, outlined, ghost or link button in seven colours, with a loading state. | `Button` |
-| `IconButton` | Icon-only button with an optional tooltip. | `IconButton` |
-| `ButtonGroup` | Joins adjacent buttons into one control. | `ButtonGroup` |
-| `SplitButton` | Main action plus a dropdown menu of secondary actions. | `SplitButton` |
-| `ResponsiveButton` | Shows its label on desktop and collapses to icon-only on mobile. | `ResponsiveButton` |
-| `LinkButton`, `IconLinkButton`, `ResponsiveLinkButton` | The button styles rendered as `react-router` links. | `LinkButton`, `IconLinkButton`, `ResponsiveLinkButton` |
-| `CopyButton`, `CopyValue` | Copies a value to the clipboard and briefly shows a check mark. `CopyValue` displays the value next to the button. | `CopyButton` |
-| `HighlightText` | Marks case-insensitive matches of a query inside a string (`splitMatch`). | `HighlightText` |
-| `LoadMoreButton` | "Load more" button for cursor pagination; icon-only with a tooltip unless `expanded`. | `LoadMoreButton` |
-| `ScrollToTop` | Floating button that appears past a scroll threshold. | `ScrollToTop` |
-| `ActionCard` | Clickable card with icon, title, description and active indicator. | `ActionCard` |
-| `ThemeToggle` | Light / dark / system switch that stores and applies the choice. | `ThemeToggle` |
-| `LanguageSwitcher` | Globe button with a menu of the `I18nProvider` languages. | `LanguageSwitcher` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-button.webp" width="120" alt="Button"> | [`Button`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#button) | Filled, tonal, outlined, ghost or link button in seven colours, with a loading state. | `Button` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-iconbutton.webp" width="120" alt="IconButton"> | [`IconButton`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#iconbutton) | Icon-only button with an optional tooltip. | `IconButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-buttongroup.webp" width="120" alt="ButtonGroup"> | [`ButtonGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#buttongroup) | Joins adjacent buttons into one control. | `ButtonGroup` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-splitbutton.webp" width="120" alt="SplitButton"> | [`SplitButton`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#splitbutton) | Main action plus a dropdown menu of secondary actions. | `SplitButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-responsivebutton.webp" width="120" alt="ResponsiveButton"> | [`ResponsiveButton`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#responsivebutton) | Shows its label on desktop and collapses to icon-only on mobile, keeping the label for screen readers. | `ResponsiveButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-linkbutton.webp" width="120" alt="LinkButton"> | [`LinkButton`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#linkbutton), `IconLinkButton`, `ResponsiveLinkButton` | The button styles rendered as `react-router` links. | `LinkButton`, `IconLinkButton`, `ResponsiveLinkButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-copybutton.webp" width="120" alt="CopyButton"> | [`CopyButton`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#copybutton), `CopyValue` | Copies a value to the clipboard and briefly shows a check mark. `CopyValue` displays the value next to the button. | `CopyButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-highlighttext.webp" width="120" alt="HighlightText"> | [`HighlightText`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#highlighttext) | Marks case-insensitive matches of a query inside a string (`splitMatch`). | `HighlightText` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-loadmorebutton.webp" width="120" alt="LoadMoreButton"> | [`LoadMoreButton`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#loadmorebutton) | "Load more" button for cursor pagination; icon-only with a tooltip unless `expanded`. | `LoadMoreButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-scrolltotop.webp" width="120" alt="ScrollToTop"> | [`ScrollToTop`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#scrolltotop) | Floating button that appears past a scroll threshold. | `ScrollToTop` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-actioncard.webp" width="120" alt="ActionCard"> | [`ActionCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#actioncard) | Clickable card with icon, title, description and active indicator. | `ActionCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-themetoggle.webp" width="120" alt="ThemeToggle"> | [`ThemeToggle`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#themetoggle) | Light / dark / system switch that stores and applies the choice. | `ThemeToggle` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/buttons-actions-languageswitcher.webp" width="120" alt="LanguageSwitcher"> | [`LanguageSwitcher`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/buttons-and-actions.md#languageswitcher) | Globe button with a menu of the `I18nProvider` languages. | `LanguageSwitcher` |
 
 ### Form fields
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `Field` · `FormField` | Renders the field matching a config `type` (text, select, date, upload, otp…). | `Field` |
-| `TextField` · `TextFormField` | Labelled input with leading / trailing adornments and helper text. | `TextField`, `TextFormField` |
-| `TextareaField` · `TextareaFormField` | Labelled textarea with row sizing and a `maxLength` counter. | `TextareaField`, `TextareaFormField` |
-| `EmailField` · `EmailFormField` | Validates on blur; shows a `mailto:` button once the address is valid. | `EmailField`, `EmailFormField` |
-| `PasswordField` · `PasswordFormField` | Show / hide toggle and an optional strength meter (`scorePassword`). | `PasswordField`, `PasswordFormField` |
-| `NumberField` · `NumberFormField` | Emits `number \| null`, with min / max / step clamping, +/− buttons and a suffix. | `NumberField`, `NumberFormField` |
-| `PercentField` · `PercentFormField` | `NumberField` with a `%` suffix. | `PercentField`, `PercentFormField` |
-| `CurrencyField` · `CurrencyFormField` | Amount formatted to the locale on blur, with a currency suffix (EUR by default). | `CurrencyField`, `CurrencyFormField` |
-| `PhoneField` · `PhoneFormField` | International number with a country picker; emits E.164. | `PhoneField`, `PhoneFormField` |
-| `UrlField` · `UrlFormField` | Validates on blur; open-in-new-tab and copy buttons. | `UrlField`, `UrlFormField` |
-| `SearchField` · `SearchFormField` | Search icon, clear button and spinner, with a debounced `onValueChange`. | `SearchField`, `SearchFormField` |
-| `ColorField` · `ColorFormField` | Hex input with a colour picker in a popover. | `ColorField`, `ColorFormField` |
-| `OtpField` · `OtpFormField` | One-time code input of configurable length. | `OtpField`, `OtpFormField`, `InputOTP` |
-| `InputGroupField` · `InputGroupFormField` | Labelled `InputGroup` with addons and helper text. | `InputGroupField`, `InputGroupFormField` |
-| `InlineEdit` · `InlineEditFormField` | Click-to-edit text with save and cancel. | `InlineEdit` |
-| `CountryField` · `CountryFormField` | Single or multiple country picker with flags. | `CountryField`, `CountryFormField` |
-| `TimezoneField` · `TimezoneFormField` | Searchable IANA timezone picker with localised labels. | `TimezoneField`, `TimezoneFormField` |
-| `RatingField` · `RatingFormField` | Star rating with hover preview, click-to-clear and a read-only mode. | `RatingField`, `RatingFormField` |
-| `Slider` · `SliderFormField` | Labelled single or range slider with an editable value and ticks. | `Slider`, `SliderField`, `SliderFormField` |
-| `Switch` · `SwitchFormField` | Toggle switch, optionally in a labelled, bordered row. | `Switch`, `SwitchField`, `SwitchFormField` |
-| `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm` · `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField` | Editor for typed custom attributes (string, number, date, select, rich text…). | `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm`, `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField` |
-| `Contacts`, `ContactItem`, `ContactDialog` · `ContactsFormField` | Typed contact list (phone, email, URL…) with an add / edit dialog. | `Contacts`, `ContactItem`, `ContactDialog`, `ContactsFormField` |
-| `PostalAddress`, `PostalAddressDialog` · `PostalAddressFormField` | Address card with an edit dialog. | `PostalAddress`, `PostalAddressDialog`, `PostalAddressFormField` |
-| `OpeningHours`, `OpeningHoursDialog`, `OpeningHoursItem` · `OpeningHoursFormField` | Weekly opening hours with an add / edit dialog. | `OpeningHours`, `OpeningHoursDialog`, `OpeningHoursItem`, `OpeningHoursFormField` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-field.webp" width="120" alt="Field"> | [`Field`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#field) · `FormField` | Renders the field matching a config `type` (text, select, date, upload, otp…). | `Field` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-textfield.webp" width="120" alt="TextField"> | [`TextField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#textfield) · `TextFormField` | Labelled input with leading / trailing adornments and helper text. | `TextField`, `TextFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-textareafield.webp" width="120" alt="TextareaField"> | [`TextareaField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#textareafield) · `TextareaFormField` | Labelled textarea with row sizing and a `maxLength` counter. | `TextareaField`, `TextareaFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-emailfield.webp" width="120" alt="EmailField"> | [`EmailField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#emailfield) · `EmailFormField` | Validates on blur; shows a `mailto:` button once the address is valid. | `EmailField`, `EmailFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-passwordfield.webp" width="120" alt="PasswordField"> | [`PasswordField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#passwordfield) · `PasswordFormField` | Show / hide toggle and an optional strength meter (`scorePassword`). | `PasswordField`, `PasswordFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-numberfield.webp" width="120" alt="NumberField"> | [`NumberField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#numberfield) · `NumberFormField` | Emits `number \| null`, with min / max / step clamping, +/− buttons and a suffix. | `NumberField`, `NumberFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-percentfield.webp" width="120" alt="PercentField"> | [`PercentField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#percentfield) · `PercentFormField` | `NumberField` with a `%` suffix. | `PercentField`, `PercentFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-currencyfield.webp" width="120" alt="CurrencyField"> | [`CurrencyField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#currencyfield) · `CurrencyFormField` | Amount formatted to the locale on blur, with the currency's own decimals and a currency suffix (EUR by default). | `CurrencyField`, `CurrencyFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-phonefield.webp" width="120" alt="PhoneField"> | [`PhoneField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#phonefield) · `PhoneFormField` | International number with a country picker; emits E.164. | `PhoneField`, `PhoneFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-urlfield.webp" width="120" alt="UrlField"> | [`UrlField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#urlfield) · `UrlFormField` | Validates on blur; open-in-new-tab and copy buttons. | `UrlField`, `UrlFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-searchfield.webp" width="120" alt="SearchField"> | [`SearchField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#searchfield) · `SearchFormField` | Search icon, clear button and spinner, with a debounced `onValueChange`. | `SearchField`, `SearchFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-colorfield.webp" width="120" alt="ColorField"> | [`ColorField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#colorfield) · `ColorFormField` | Hex input with a colour picker in a popover. | `ColorField`, `ColorFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-otpfield.webp" width="120" alt="OtpField"> | [`OtpField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#otpfield) · `OtpFormField` | One-time code input of configurable length. | `OtpField`, `OtpFormField`, `InputOTP` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-inputgroupfield.webp" width="120" alt="InputGroupField"> | [`InputGroupField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#inputgroupfield) · `InputGroupFormField` | Labelled `InputGroup` with addons and helper text. | `InputGroupField`, `InputGroupFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-inlineedit.webp" width="120" alt="InlineEdit"> | [`InlineEdit`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#inlineedit) · `InlineEditFormField` | Click-to-edit text with save and cancel. | `InlineEdit` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-countryfield.webp" width="120" alt="CountryField"> | [`CountryField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#countryfield) · `CountryFormField` | Single or multiple country picker with flags. | `CountryField`, `CountryFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-timezonefield.webp" width="120" alt="TimezoneField"> | [`TimezoneField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#timezonefield) · `TimezoneFormField` | Searchable IANA timezone picker with localised labels. | `TimezoneField`, `TimezoneFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-ratingfield.webp" width="120" alt="RatingField"> | [`RatingField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#ratingfield) · `RatingFormField` | Star rating with hover preview, click-to-clear and a read-only mode. | `RatingField`, `RatingFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-slider.webp" width="120" alt="Slider"> | [`Slider`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#slider) · `SliderFormField` | Labelled single or range slider with an editable value and ticks. | `Slider`, `SliderField`, `SliderFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-switch.webp" width="120" alt="Switch"> | [`Switch`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#switch) · `SwitchFormField` | Toggle switch, optionally in a labelled, bordered row. | `Switch`, `SwitchField`, `SwitchFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-attributes.webp" width="120" alt="AttributesField"> | [`AttributesField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#attributes), `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm` · `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField` | Editor for typed custom attributes (string, number, date, select, rich text…). | `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm`, `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-contacts.webp" width="120" alt="Contacts"> | [`Contacts`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#contacts), `ContactDialog`, `ContactItem` (deprecated) · `ContactsFormField` | Typed contact list (phone, email, URL…) with an add / edit dialog. | `Contacts`, `ContactItem`, `ContactDialog`, `ContactsFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-postaladdress.webp" width="120" alt="PostalAddress"> | [`PostalAddress`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#postaladdress), `PostalAddressDialog` · `PostalAddressFormField` | Address card with an edit dialog. | `PostalAddress`, `PostalAddressDialog`, `PostalAddressFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/form-fields-openinghours.webp" width="120" alt="OpeningHours"> | [`OpeningHours`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/form-fields.md#openinghours), `OpeningHoursDialog`, `OpeningHoursItem` (deprecated) · `OpeningHoursFormField` | Weekly opening hours with an add / edit dialog. | `OpeningHours`, `OpeningHoursDialog`, `OpeningHoursItem`, `OpeningHoursFormField` |
 
 ### Date & time
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `Calendar`, `CalendarDayButton` | Day-picker calendar with a year view, a today shortcut and `disablePast` / `disableFuture`. | `Calendar` (Reka parts) |
-| `DateField` · `DateFormField` | Labelled trigger that opens a calendar popover, with an optional time picker. | `DateField`, `DateFormField` |
-| `DateRangeField` · `DateRangeFormField` | From / to range picked in a popover calendar. | `DateRangeField`, `DateRangeFormField` |
-| `TimeField` · `TimeFormField` | Opens a `TimePicker` in a popover, or in a dialog on mobile. | `TimeField`, `TimeFormField` |
-| `TimePicker` | Hour and minute inputs with AM / PM and auto-advancing focus. | `TimePicker` |
-| `DurationField` · `DurationFormField` | Hours and minutes combined into a total in minutes. | `DurationField`, `DurationFormField` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/date-time-calendar.webp" width="120" alt="Calendar"> | [`Calendar`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/date-and-time.md#calendar), `CalendarDayButton` | Day-picker calendar with a year view, a today shortcut and `disablePast` / `disableFuture`. | `Calendar` (Reka parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/date-time-datefield.webp" width="120" alt="DateField"> | [`DateField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/date-and-time.md#datefield) · `DateFormField` | Labelled trigger that opens a calendar popover, with an optional time picker. | `DateField`, `DateFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/date-time-daterangefield.webp" width="120" alt="DateRangeField"> | [`DateRangeField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/date-and-time.md#daterangefield) · `DateRangeFormField` | From / to range picked in a popover calendar. | `DateRangeField`, `DateRangeFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/date-time-timefield.webp" width="120" alt="TimeField"> | [`TimeField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/date-and-time.md#timefield) · `TimeFormField` | Opens a `TimePicker` in a popover, or in a dialog on mobile. | `TimeField`, `TimeFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/date-time-timepicker.webp" width="120" alt="TimePicker"> | [`TimePicker`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/date-and-time.md#timepicker) | Hour and minute inputs with AM / PM and auto-advancing focus. | `TimePicker` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/date-time-durationfield.webp" width="120" alt="DurationField"> | [`DurationField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/date-and-time.md#durationfield) · `DurationFormField` | Hours and minutes combined into a total in minutes. | `DurationField`, `DurationFormField` |
 
 ### Selection & choice
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`… | Select primitives with groups, labels and scroll buttons. | `Select` (same parts), `NativeSelect` |
-| `SelectField` · `SelectFormField` | Labelled select built from `options`, with `renderOption`. | `SelectField`, `SelectFormField` |
-| `Combobox`, `ComboboxInput`, `ComboboxContent`, `ComboboxList`, `ComboboxItem`, `ComboboxChips`… | Base UI combobox primitives: input, popup list, groups and chips. | — |
-| `ComboboxField` · `ComboboxFormField` | Labelled, searchable single select over `{ value, label }` options. | `ComboboxField`, `ComboboxFormField` |
-| `Autocomplete`, `AutocompleteChips` · `AutocompleteFormField` | Single or multiple (chips) autocomplete with free-solo values and a query callback. | `Autocomplete`, `AutocompleteFormField` |
-| `Checkbox` · `CheckboxFormField` | Checkbox with label, helper text and an indeterminate state. | `Checkbox` |
-| `CheckboxGroup` · `CheckboxGroupFormField` | Checkbox list built from `options`, valued as `string[]`. | `CheckboxGroup`, `CheckboxGroupFormField` |
-| `RadioGroup`, `RadioGroupItem` · `RadioGroupFormField` | Labelled radio group built from `options`, horizontal or vertical. | `RadioGroupField`, `RadioGroup`, `RadioGroupFormField` |
-| `CheckCardField` · `CheckCardFormField` | A yes / no choice shown as two selectable cards. | `CheckCardField`, `CheckCardFormField` |
-| `SelectCardField` · `SelectCardFormField` | Single or multiple choice shown as `ActionCard`s. | `SelectCardField`, `SelectCardFormField` |
-| `SelectChipField` · `SelectChipFormField` | Single or multiple choice shown as toggleable chips. | `SelectChipField`, `SelectChipFormField` |
-| `TransferList` · `TransferListFormField` | Two-pane picker with search, drag-and-drop, reordering and a `max`. | `TransferList`, `TransferListFormField` |
-| `SortableList` · `SortableListFormField` | Searchable list of strings you reorder by dragging or with the keyboard. | `SortableList`, `SortableListFormField` |
-| `Switcher` | Dropdown for switching the active workspace or account, with an avatar. | `Switcher` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-select.webp" width="120" alt="Select"> | [`Select`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#select), `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`… | Select primitives with groups, labels and scroll buttons. | `Select` (same parts), `NativeSelect` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-selectfield.webp" width="120" alt="SelectField"> | [`SelectField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#selectfield) · `SelectFormField` | Labelled select built from `options`, with `renderOption`. | `SelectField`, `SelectFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-combobox.webp" width="120" alt="Combobox"> | [`Combobox`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#combobox), `ComboboxInput`, `ComboboxContent`, `ComboboxList`, `ComboboxItem`, `ComboboxChips`… | Base UI combobox primitives: input, popup list, groups and chips. | — |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-comboboxfield.webp" width="120" alt="ComboboxField"> | [`ComboboxField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#comboboxfield) · `ComboboxFormField` | Labelled, searchable single select over `{ value, label }` options. | `ComboboxField`, `ComboboxFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-autocomplete.webp" width="120" alt="Autocomplete"> | [`Autocomplete`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#autocomplete), `AutocompleteChips` · `AutocompleteFormField` | Single or multiple (chips) autocomplete with free-solo values and a query callback. | `Autocomplete`, `AutocompleteFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-checkbox.webp" width="120" alt="Checkbox"> | [`Checkbox`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#checkbox) · `CheckboxFormField` | Checkbox with label, helper text and an indeterminate state. | `Checkbox` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-checkboxgroup.webp" width="120" alt="CheckboxGroup"> | [`CheckboxGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#checkboxgroup) · `CheckboxGroupFormField` | Checkbox list built from `options`, valued as `string[]`. | `CheckboxGroup`, `CheckboxGroupFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-radiogroup.webp" width="120" alt="RadioGroup"> | [`RadioGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#radiogroup), `RadioGroupItem` · `RadioGroupFormField` | Labelled radio group built from `options`, horizontal or vertical. | `RadioGroupField`, `RadioGroup`, `RadioGroupFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-checkcardfield.webp" width="120" alt="CheckCardField"> | [`CheckCardField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#checkcardfield) · `CheckCardFormField` | A yes / no choice shown as two selectable cards. | `CheckCardField`, `CheckCardFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-selectcardfield.webp" width="120" alt="SelectCardField"> | [`SelectCardField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#selectcardfield) · `SelectCardFormField` | Single or multiple choice shown as `ActionCard`s. | `SelectCardField`, `SelectCardFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-selectchipfield.webp" width="120" alt="SelectChipField"> | [`SelectChipField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#selectchipfield) · `SelectChipFormField` | Single or multiple choice shown as toggleable chips. | `SelectChipField`, `SelectChipFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-transferlist.webp" width="120" alt="TransferList"> | [`TransferList`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#transferlist) · `TransferListFormField` | Two-pane picker with search, drag-and-drop, reordering and a `max`. | `TransferList`, `TransferListFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-sortablelist.webp" width="120" alt="SortableList"> | [`SortableList`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#sortablelist) · `SortableListFormField` | Searchable list of strings you reorder by dragging or with the keyboard. | `SortableList`, `SortableListFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/selection-choice-switcher.webp" width="120" alt="Switcher"> | [`Switcher`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/selection-and-choice.md#switcher) | Dropdown for switching the active workspace or account, with an avatar. | `Switcher` |
 
 ### Data display
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarBase` | Image with a fallback and an optional online / offline dot. | `Avatar`, `AvatarImage`, `AvatarFallback` |
-| `AvatarGroup` | Overlapping avatars with a `+N` overflow. | `AvatarGroup` |
-| `Badge` | Pill label: default, secondary, error, success, info, warning, outlined. | `Badge` |
-| `CountBadge` | Count in the corner of its children, capped at `99+` and hidden at 0. | `CountBadge` |
-| `Chip` | Pill with leading, avatar and trailing slots, an active state and a dismiss button. | `Chip` |
-| `StatCard` | KPI tile with value, hint, icon, toned delta and a loading skeleton. | `StatCard` |
-| `TrendCard`, `GoalCard`, `BreakdownCard`, `RankCard`, `CompareCard`, `HeatweekCard`, `FunnelCard`, `GaugeCard`, `SparkbarCard`, `DeltaListCard`, `BandCard`, `LatencyCard`, `RatioCard`, `ThresholdCard`, `PaceCard`, `HistogramCard` | Dashboard tiles including compare, heat, funnel, gauge, spark bars, delta list, range band, latency, ratio, threshold, pace and labelled histogram. Container queries. | `TrendCard`, `GoalCard`, `BreakdownCard`, `RankCard`, `CompareCard`, `HeatweekCard`, `FunnelCard`, `GaugeCard`, `SparkbarCard`, `DeltaListCard`, `BandCard`, `LatencyCard`, `RatioCard`, `ThresholdCard`, `PaceCard`, `HistogramCard` |
-| `FeatureCard`, `MediaCard`, `PricingCard`, `ProfileCard`, `QuoteCard`, `OverlayCard`, `SpotlightCard`, `CrewCard`, `SplitCard`, `TicketCard`, `NoticeCard`, `TimelineCard`, `MessageCard`, `EventCard`, `StackCard`, `LinkCard`, `AlbumCard`, `TagCard`, `ReceiptCard`, `ReviewCard`, `OfferCard`, `PlaceCard`, `FileCard`, `StatusCard`, `ScoreCard`, `ShortcutCard`, `ChecklistCard` | Card presets including overlay, ticket, inbox, event, stack, link, album, tags, receipt, review, offer, place, file, status, score, shortcuts and checklist. Container queries. | `FeatureCard`, `MediaCard`, `PricingCard`, `ProfileCard`, `QuoteCard`, `OverlayCard`, `SpotlightCard`, `CrewCard`, `SplitCard`, `TicketCard`, `NoticeCard`, `TimelineCard`, `MessageCard`, `EventCard`, `StackCard`, `LinkCard`, `AlbumCard`, `TagCard`, `ReceiptCard`, `ReviewCard`, `OfferCard`, `PlaceCard`, `FileCard`, `StatusCard`, `ScoreCard`, `ShortcutCard`, `ChecklistCard` |
-| `StatusIndicator` | Coloured status dot with an optional pulse and label. | `StatusIndicator` |
-| `SummaryData` | Label / value pairs as a grid or inline; hides empty values. | `SummaryData` |
-| `Description` | Read-only label / value pair that renders nothing when empty. | `Description` |
-| `EntityHeader` | Page header with icon, title, status, metadata and actions. | `EntityHeader` |
-| `ListTile` | Row with leading / trailing slots, title and subtitle; becomes a link or button when interactive. `size="sm"` is the dense row. | `ListTile` |
-| `AccordionCard` | Renders `items` (title, content) as a styled accordion. | `AccordionCard` |
-| `Timeline`, `TimelineItem`, `RelativeTime` | Vertical event timeline with toned icons and relative times. | `Timeline`, `TimelineItem`, `RelativeTime` |
-| `EventChip` | Calendar event pill with time, all-day and continuation edges. | `EventChip` |
-| `CodeBlock`, `CodeDiff`, `JsonViewer`, `CodeGroup` | Highlighted code with line numbers and copy, a Monaco diff, a collapsible JSON tree, and tabbed samples (`Tabs variant="line"`). | `CodeBlock`, `CodeDiff`, `JsonViewer`, `CodeGroup` |
-| `Markdown` | GFM markdown with KaTeX math and mermaid diagrams (`clientOnly`). Fences reuse `CodeBlock`. `ChatMarkdown` renders through it. | `Markdown` |
-| `Terminal` | Display-only log with prompt, copy, and error/input tones. Container queries. | `Terminal` |
-| `Figure` | Framed media with an optional caption. | `Figure` |
-| `ApiEndpoint`, `ApiOperation` | HTTP method badge, path and copy; `ApiOperation` adds a param table and example `CodeGroup`. | `ApiEndpoint`, `ApiOperation` |
-| `ParamTable` | Name / type / default / description table; stacked cards below `sm`. | `ParamTable` |
-| `QRCode` | QR code on a padded tile, with an optional centred logo. | `QRCode` |
-| `Barecode` | 1D barcode. | `Barecode` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-avatar.webp" width="120" alt="Avatar"> | [`Avatar`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#avatar), `AvatarImage`, `AvatarFallback`, `AvatarBase` | Image with a fallback and an optional online / offline dot. | `Avatar`, `AvatarImage`, `AvatarFallback` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-avatargroup.webp" width="120" alt="AvatarGroup"> | [`AvatarGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#avatargroup) | Overlapping avatars with a `+N` overflow. | `AvatarGroup` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-badge.webp" width="120" alt="Badge"> | [`Badge`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#badge) | Pill label: default, secondary, error, success, info, warning, outlined. | `Badge` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-countbadge.webp" width="120" alt="CountBadge"> | [`CountBadge`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#countbadge) | Count in the corner of its children, capped at `99+` and hidden at 0. | `CountBadge` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-chip.webp" width="120" alt="Chip"> | [`Chip`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#chip) | Pill with leading, avatar and trailing slots, an active state and a dismiss button. | `Chip` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-statcard.webp" width="120" alt="StatCard"> | [`StatCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#statcard) | KPI tile with value, hint, icon, toned delta and a loading skeleton. | `StatCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-metric-cards.webp" width="120" alt="TrendCard"> | [`TrendCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#metric-cards), `GoalCard`, `BreakdownCard`, `RankCard`, `CompareCard`, `HeatweekCard`, `FunnelCard`, `GaugeCard`, `SparkbarCard`, `DeltaListCard`, `BandCard`, `LatencyCard`, `RatioCard`, `ThresholdCard`, `PaceCard`, `HistogramCard`, `Sparkline` | Dashboard tiles including compare, heat, funnel, gauge, spark bars, delta list, range band, latency, ratio, threshold, pace and labelled histogram. Container queries. | `TrendCard`, `GoalCard`, `BreakdownCard`, `RankCard`, `CompareCard`, `HeatweekCard`, `FunnelCard`, `GaugeCard`, `SparkbarCard`, `DeltaListCard`, `BandCard`, `LatencyCard`, `RatioCard`, `ThresholdCard`, `PaceCard`, `HistogramCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-card-presets.webp" width="120" alt="FeatureCard"> | [`FeatureCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#card-presets), `MediaCard`, `PricingCard`, `ProfileCard`, `QuoteCard`, `OverlayCard`, `SpotlightCard`, `CrewCard`, `SplitCard`, `TicketCard`, `NoticeCard`, `TimelineCard`, `MessageCard`, `EventCard`, `StackCard`, `LinkCard`, `AlbumCard`, `TagCard`, `ReceiptCard`, `ReviewCard`, `OfferCard`, `PlaceCard`, `FileCard`, `StatusCard`, `ScoreCard`, `ShortcutCard`, `ChecklistCard` | Card presets including overlay, ticket, inbox, event, stack, link, album, tags, receipt, review, offer, place, file, status, score, shortcuts and checklist. Container queries. | `FeatureCard`, `MediaCard`, `PricingCard`, `ProfileCard`, `QuoteCard`, `OverlayCard`, `SpotlightCard`, `CrewCard`, `SplitCard`, `TicketCard`, `NoticeCard`, `TimelineCard`, `MessageCard`, `EventCard`, `StackCard`, `LinkCard`, `AlbumCard`, `TagCard`, `ReceiptCard`, `ReviewCard`, `OfferCard`, `PlaceCard`, `FileCard`, `StatusCard`, `ScoreCard`, `ShortcutCard`, `ChecklistCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-statusindicator.webp" width="120" alt="StatusIndicator"> | [`StatusIndicator`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#statusindicator) | Coloured status dot with an optional pulse and label. | `StatusIndicator` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-summarydata.webp" width="120" alt="SummaryData"> | [`SummaryData`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#summarydata) | Label / value pairs as a grid or inline; hides empty values. | `SummaryData` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-description.webp" width="120" alt="Description"> | [`Description`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#description) | Read-only label / value pair that renders nothing when empty. | `Description` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-entityheader.webp" width="120" alt="EntityHeader"> | [`EntityHeader`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#entityheader) | Page header with icon, title, status, metadata and actions. | `EntityHeader` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-listtile.webp" width="120" alt="ListTile"> | [`ListTile`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#listtile) | Row with leading / trailing slots, title and subtitle; becomes a link or button when interactive. `size="sm"` is the dense row. | `ListTile` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-accordioncard.webp" width="120" alt="AccordionCard"> | [`AccordionCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#accordioncard) | Renders `items` (title, content) as a styled accordion. | `AccordionCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-timeline.webp" width="120" alt="Timeline"> | [`Timeline`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#timeline), `TimelineItem`, `RelativeTime` | Vertical event timeline with toned icons and relative times. | `Timeline`, `TimelineItem`, `RelativeTime` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-eventchip.webp" width="120" alt="EventChip"> | [`EventChip`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#eventchip) | Calendar event pill with time, all-day and continuation edges. | `EventChip` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-codeblock.webp" width="120" alt="CodeBlock"> | [`CodeBlock`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#codeblock), `CodeDiff`, `JsonViewer`, `CodeGroup` | Highlighted code with line numbers and copy, a Monaco diff, a collapsible JSON tree, and tabbed samples (`Tabs variant="line"`). | `CodeBlock`, `CodeDiff`, `JsonViewer`, `CodeGroup` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-markdown.webp" width="120" alt="Markdown"> | [`Markdown`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#markdown), `MermaidDiagram` | GFM markdown with KaTeX math and mermaid diagrams (`clientOnly`). Fences reuse `CodeBlock`. `ChatMarkdown` renders through it. | `Markdown` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-terminal.webp" width="120" alt="Terminal"> | [`Terminal`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#terminal) | Display-only log with prompt, copy, and error/input tones. Container queries. | `Terminal` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-figure.webp" width="120" alt="Figure"> | [`Figure`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#figure) | Framed media with an optional caption. | `Figure` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-apioperation.webp" width="120" alt="ApiEndpoint"> | [`ApiEndpoint`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#apiendpoint), `ApiOperation` | HTTP method badge, path and copy; `ApiOperation` adds a param table and example `CodeGroup`. | `ApiEndpoint`, `ApiOperation` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-paramtable.webp" width="120" alt="ParamTable"> | [`ParamTable`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#paramtable) | Name / type / default / description table; stacked cards below `sm`. | `ParamTable` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-qrcode.webp" width="120" alt="QRCode"> | [`QRCode`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#qrcode) | QR code on a padded tile, with an optional centred logo. | `QRCode` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-display-barecode.webp" width="120" alt="Barecode"> | [`Barecode`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-display.md#barecode) | 1D barcode. | `Barecode` |
 
 ### Data table, filter & lists
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `DataTable`, `DataTableColumnHeader`, `DataTablePagination`, `DataTableViewOptions` | TanStack Table v9 with sorting, filtering, selection, expandable rows, pagination or load-more, and column visibility. | `DataTable`, `DataTableColumnHeader`, `DataTablePagination`, `DataTableViewOptions` |
-| `Filter`, `FilterProvider`, `FilterContent`, `FilterChips`, `FilterPresets` · `FilterFormField` | Schema-driven filters with chips, presets, validation, and URL or storage persistence. | `Filter`, `FilterProvider`, `FilterContent`, `FilterChips`, `FilterPresets`, `FilterFormField` |
-| `FilterInline`, `FilterPopover`, `FilterDialog`, `FilterSheet`, `FilterDrawer` | The filter panel shown inline, or in a popover, dialog, sheet or drawer. | `FilterInline`, `FilterPopover`, `FilterDialog`, `FilterSheet`, `FilterDrawer` |
-| `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationBar`… | Pagination primitives. `PaginationBar` adds a sibling window with ellipses. | `Pagination` (parts), `PaginationFirst`, `PaginationLast` |
-| `Tree`, `TreeItem`, `useTree` | Expandable tree with none, single or multiple selection and keyboard navigation. | `Tree`, `TreeItem`, `useTree` |
-| `DndProvider`, `Draggable`, `Droppable`, `Sortable`, `DragHandle`… | Drag-and-drop primitives; see [dnd](#nxgtmaterialdnd). | `DndProvider`, `Draggable`, `Droppable`, `Sortable`, `DragHandle` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-table-filter-lists-datatable.webp" width="120" alt="DataTable"> | [`DataTable`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-table-filter-and-lists.md#datatable), `DataTableColumnHeader`, `DataTablePagination`, `DataTableViewOptions` | TanStack Table v9 with sorting, filtering, selection, expandable rows, pagination or load-more, and column visibility. | `DataTable`, `DataTableColumnHeader`, `DataTablePagination`, `DataTableViewOptions` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-table-filter-lists-filter.webp" width="120" alt="Filter"> | [`Filter`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-table-filter-and-lists.md#filter), `FilterProvider`, `FilterContent`, `FilterChips`, `FilterPresets` · `FilterFormField` | Schema-driven filters with chips, presets, validation, and URL or storage persistence. | `Filter`, `FilterProvider`, `FilterContent`, `FilterChips`, `FilterPresets`, `FilterFormField` |
+| — | [`FilterInline`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-table-filter-and-lists.md#filterinline-filterpopover-filterdialog-filtersheet-filterdrawer), `FilterPopover`, `FilterDialog`, `FilterSheet`, `FilterDrawer` | The filter panel shown inline, or in a popover, dialog, sheet or drawer. | `FilterInline`, `FilterPopover`, `FilterDialog`, `FilterSheet`, `FilterDrawer` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-table-filter-lists-pagination.webp" width="120" alt="Pagination"> | [`Pagination`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-table-filter-and-lists.md#pagination), `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationBar`… | Pagination primitives. `PaginationBar` adds a sibling window with ellipses. | `Pagination` (parts), `PaginationFirst`, `PaginationLast` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-table-filter-lists-tree.webp" width="120" alt="Tree"> | [`Tree`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-table-filter-and-lists.md#tree), `TreeItem`, `useTree` | Expandable tree with none, single or multiple selection and keyboard navigation. | `Tree`, `TreeItem`, `useTree` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/data-table-filter-lists-drag-and-drop.webp" width="120" alt="DndProvider"> | [`DndProvider`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/data-table-filter-and-lists.md#drag-and-drop), `Draggable`, `Droppable`, `Sortable`, `DragHandle`… | Drag-and-drop primitives; see [dnd](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/helpers.md#nxgtmaterialdnd). | `DndProvider`, `Draggable`, `Droppable`, `Sortable`, `DragHandle` |
 
 ### Navigation & layout
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` | App shell: sidebar built from `items`, a header with a mobile sheet, route breadcrumbs and a titled page. See [App shell](#app-shell). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
-| `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarMenuItem`, `SidebarMenuLabel` | Collapsible navigation sidebar with icons, tooltips and active items. | `Sidebar` (same parts) |
-| `TopAppBar`, `BottomAppBar` | Top bar surface, and a bottom bar of icon actions with an active state. | `TopAppBar`, `BottomAppBar` |
-| `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Breadcrumb primitives. | `Breadcrumb` (same parts) |
-| `ListDetailsLayout`, `PaneLayout`, `ThreadLayout` | List / details that collapses to one view on mobile, a side pane that becomes a sheet, and a centred column. | `ListDetailsLayout`, `PaneLayout`, `ThreadLayout` |
-| `ResponsiveGrid` | Container-query grid that grows from 1 to 5 columns. | `ResponsiveGrid` |
-| `ResizableGroup`, `ResizablePanel`, `ResizableSeparator` | Resizable panels with an optional grip handle. | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` |
-| `SkipLink` | Skip-to-content control, visible on focus. `DocSkipLink` composes it with `#doc-content`. | `SkipLink` |
-| `Pager` | Previous / next cards for a sequence of pages. `DocPager` composes it. | `Pager` |
-| `SeeAlso` | Related-link list with outbound icons. `DocSeeAlso` composes it. | `SeeAlso` |
-| `Toc` | On-this-page outline with a per-item active bar. Rail from `xl`, collapsible panel below. `DocToc` composes it. | `Toc` |
-| `Stepper`, `StepperIndicator` | Clickable horizontal or vertical steps with status and progress; compact on mobile. | `Stepper` |
-| `Steps`, `StepsItem` | Numbered editorial steps that stay visible on every breakpoint. | `Steps`, `StepsItem` |
-| `Hero` | Landing band with eyebrow, title, supporting copy and actions. | `Hero` |
-| `Doc`, `DocPage`, `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress` | Documentation site shell: sidebar from `md`, TOC rail from `xl`. Reading bar, copy-page / markdown, child cards, see also, and a 404 slot. Storybook `UI/Doc/Api` composes an API page from `DocPage`, `AnchorHeading`, `ApiOperation`, `ParamTable` and `CodeGroup`. | `Doc`, `DocPage`, `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress` |
-| `Background` | Full-viewport gradient with blurred colour blobs; centres its children. | `Background` |
-| `NavigationRail` | Placeholder: renders an empty rail container and takes no props yet. | `NavigationRail` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-appshell.webp" width="120" alt="ActivityLayout"> | [`ActivityLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#activitylayout), `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb`, `AppBreadcrumbItem`, `AppBreadcrumbSeparator` | App shell: sidebar built from `items`, a header with a mobile sheet, route breadcrumbs and a titled page. See the [app shell guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/app-shell.md). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-sidebar.webp" width="120" alt="Sidebar"> | [`Sidebar`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#sidebar), `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarMenuItem`, `SidebarMenuLabel` | Collapsible navigation sidebar with icons, tooltips and active items. | `Sidebar` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-topappbar.webp" width="120" alt="TopAppBar"> | [`TopAppBar`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#topappbar), `BottomAppBar` | Top bar surface, and a bottom bar of icon actions with an active state. | `TopAppBar`, `BottomAppBar` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-breadcrumb.webp" width="120" alt="Breadcrumb"> | [`Breadcrumb`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#breadcrumb), `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Breadcrumb primitives. | `Breadcrumb` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-listdetailslayout.webp" width="120" alt="ListDetailsLayout"> | [`ListDetailsLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#listdetailslayout), `PaneLayout`, `ThreadLayout` | List / details that collapses to one view on mobile, a side pane that becomes a sheet, and a centred column. | `ListDetailsLayout`, `PaneLayout`, `ThreadLayout` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-responsivegrid.webp" width="120" alt="ResponsiveGrid"> | [`ResponsiveGrid`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#responsivegrid) | Container-query grid that grows from 1 to 5 columns. | `ResponsiveGrid` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-resizable.webp" width="120" alt="ResizableGroup"> | [`ResizableGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#resizablegroup), `ResizablePanel`, `ResizableSeparator` | Resizable panels with an optional grip handle. | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-skiplink.webp" width="120" alt="SkipLink"> | [`SkipLink`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#skiplink) | Skip-to-content control, visible on focus. `DocSkipLink` composes it with `#doc-content`. | `SkipLink` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-pager.webp" width="120" alt="Pager"> | [`Pager`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#pager) | Previous / next cards for a sequence of pages. `DocPager` composes it. | `Pager` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-seealso.webp" width="120" alt="SeeAlso"> | [`SeeAlso`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#seealso) | Related-link list with outbound icons. `DocSeeAlso` composes it. | `SeeAlso` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-toc.webp" width="120" alt="Toc"> | [`Toc`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#toc) | On-this-page outline with a per-item active bar. Rail from `xl`, collapsible panel below. `DocToc` composes it. | `Toc` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-stepper.webp" width="120" alt="Stepper"> | [`Stepper`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#stepper), `StepperIndicator` | Clickable horizontal or vertical steps with status and progress; compact on mobile. | `Stepper` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-steps.webp" width="120" alt="Steps"> | [`Steps`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#steps), `StepsItem` | Numbered editorial steps that stay visible on every breakpoint. | `Steps`, `StepsItem` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-hero.webp" width="120" alt="Hero"> | [`Hero`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#hero) | Landing band with eyebrow, title, supporting copy and actions. | `Hero` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-doc.webp" width="120" alt="Doc"> | [`Doc`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#doc), `DocPage`, `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress` | Documentation site shell: sidebar from `md`, TOC rail from `xl`. Reading bar, copy-page / markdown, child cards, see also, and a 404 slot. Storybook `UI/Doc/Api` composes an API page from `DocPage`, `AnchorHeading`, `ApiOperation`, `ParamTable` and `CodeGroup`. | `Doc`, `DocPage`, `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/navigation-layout-background.webp" width="120" alt="Background"> | [`Background`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#background) | Full-viewport gradient with blurred colour blobs; centres its children. | `Background` |
+| — | [`NavigationRail`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/navigation-and-layout.md#navigationrail) | Placeholder: renders an empty rail container and takes no props yet. | `NavigationRail` |
 
 ### Overlays & menus
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`… | Modal dialog parts with an icon close button. | `Dialog` (same parts), `DialogScrollContent` |
-| `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetFooter`… | Panel that slides in from any edge. | `Sheet` (same parts) |
-| `Drawer`, `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerTitle`, `DrawerFooter`… | Swipeable bottom or side drawer (Vaul). | `Drawer` (same parts) |
-| `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverAnchor` | Floating panel anchored to a trigger. | `Popover` (same parts) |
-| `HoverCard`, `HoverCardTrigger`, `HoverCardContent` | Card shown on pointer hover. | `HoverCard` (same parts) |
-| `Tooltip`, `TooltipProvider`, `TooltipTrigger`, `TooltipContent` | Tooltip. The `Tooltip` shorthand wraps its children and shows `content`. | `Tooltip` (same parts) |
-| `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuSub`… | Menu with checkbox and radio items, submenus, shortcuts and an error item. | `DropdownMenu` (same parts) |
-| `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`… | Right-click menu with the same kinds of items. | `ContextMenu` (same parts) |
-| `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`… | Desktop-style menubar. | `Menubar` (same parts) |
-| `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandItem`… | Command palette with filtering, groups and shortcuts. `CommandDialog` shows it in a modal. | `Command`, `CommandDialog` (same parts) |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-dialog.webp" width="120" alt="Dialog"> | [`Dialog`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#dialog), `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`… | Modal dialog parts with an icon close button. | `Dialog` (same parts), `DialogScrollContent` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-sheet.webp" width="120" alt="Sheet"> | [`Sheet`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#sheet), `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetFooter`… | Panel that slides in from any edge. | `Sheet` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-drawer.webp" width="120" alt="Drawer"> | [`Drawer`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#drawer), `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerTitle`, `DrawerFooter`… | Swipeable bottom or side drawer (Vaul). | `Drawer` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-popover.webp" width="120" alt="Popover"> | [`Popover`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#popover), `PopoverTrigger`, `PopoverContent`, `PopoverAnchor` | Floating panel anchored to a trigger. | `Popover` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-hovercard.webp" width="120" alt="HoverCard"> | [`HoverCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#hovercard), `HoverCardTrigger`, `HoverCardContent` | Card shown on pointer hover. | `HoverCard` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-tooltip.webp" width="120" alt="Tooltip"> | [`Tooltip`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#tooltip), `TooltipProvider`, `TooltipTrigger`, `TooltipContent` | Tooltip. The `Tooltip` shorthand wraps its children and shows `content`. | `Tooltip` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-dropdownmenu.webp" width="120" alt="DropdownMenu"> | [`DropdownMenu`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#dropdownmenu), `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuSub`… | Menu with checkbox and radio items, submenus, shortcuts and an error item. | `DropdownMenu` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-contextmenu.webp" width="120" alt="ContextMenu"> | [`ContextMenu`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#contextmenu), `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`… | Right-click menu with the same kinds of items. | `ContextMenu` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-menubar.webp" width="120" alt="Menubar"> | [`Menubar`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#menubar), `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`… | Desktop-style menubar. | `Menubar` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/overlays-menus-command.webp" width="120" alt="Command"> | [`Command`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/overlays-and-menus.md#command), `CommandDialog`, `CommandInput`, `CommandList`, `CommandItem`… | Command palette with filtering, groups and shortcuts. `CommandDialog` shows it in a modal. | `Command`, `CommandDialog` (same parts) |
 
 ### Feedback & status
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `Alert` | Callout with icon, title and description in seven tones. | `Alert` |
-| `Banner` | Dismissible info / success / warning / error banner with an action. | `Banner` |
-| `AlertDialog`, `AlertDialogContent`, `AlertDialogAction`, `AlertDialogCancel`… | Parts for a blocking confirmation dialog. | `AlertDialog` (same parts) |
-| `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog` | Confirm / cancel dialog with async loading. `ConfirmationDialog` adds a trigger and an optional Zod form. | `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog` |
-| `CustomDialog` | Ready-made dialog with trigger, icon, title, body and footer. | `CustomDialog` |
-| `EmptyState` | Icon in a tinted well, title, description and action; not-found, unauthorized, generic, empty, offline, search and maintenance presets. | `EmptyState` |
-| `Progress`, `CircularProgress`, `ProgressField` | Linear bar, circular ring with a label, and a labelled progress field. | `Progress`, `CircularProgress`, `ProgressField` |
-| `ScrollProgress` | Hairline that tracks window or a scrollable `target` (`react-use` `useWindowScroll` / `useScroll`). `DocProgress` composes it. | `ScrollProgress` |
-| `Spinner` | Loading spinner in several styles and colours. | `Spinner` |
-| `Toaster`, `toast`, `toasts`, `Toast` | Sonner toasts with icon and action. `toasts` provides `success` / `error` / `warning` / `info` / `loading` presets. | `Toaster`, `toast`, `toasts`, `Toast` |
-| `Skeleton`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonText`, `SkeletonTable` | Loading placeholder and ready-made shapes. | `Skeleton` (same parts) |
-| `HydrateLoading` | Full-area spinner shown while hydrating. | `HydrateLoading` |
-| `Notifications` | Notification centre as a bell popover with an unread count, or as an inline panel, with filters and read / dismiss. | `Notifications` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-alert.webp" width="120" alt="Alert"> | [`Alert`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#alert) | Callout with icon, title and description in seven tones. | `Alert` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-banner.webp" width="120" alt="Banner"> | [`Banner`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#banner) | Dismissible info / success / warning / error banner with an action. | `Banner` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-alertdialog.webp" width="120" alt="AlertDialog"> | [`AlertDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#alertdialog), `AlertDialogContent`, `AlertDialogAction`, `AlertDialogCancel`… | Parts for a blocking confirmation dialog. | `AlertDialog` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-confirmdialog.webp" width="120" alt="ConfirmDialog"> | [`ConfirmDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#confirmdialog), `ConfirmationDialog`, `CustomAlertDialog` | Confirm / cancel dialog with async loading. `ConfirmationDialog` adds a trigger and an optional Zod form. | `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-customdialog.webp" width="120" alt="CustomDialog"> | [`CustomDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#customdialog) | Ready-made dialog with trigger, icon, title, body and footer. | `CustomDialog` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-emptystate.webp" width="120" alt="EmptyState"> | [`EmptyState`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#emptystate) | Icon in a tinted well, title, description and action; not-found, unauthorized, generic, empty, offline, search and maintenance presets. | `EmptyState` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-progress.webp" width="120" alt="Progress"> | [`Progress`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#progress), `CircularProgress`, `ProgressField` | Linear bar, circular ring with a label, and a labelled progress field. | `Progress`, `CircularProgress`, `ProgressField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-scrollprogress.webp" width="120" alt="ScrollProgress"> | [`ScrollProgress`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#scrollprogress) | Hairline that tracks window or a scrollable `target` (`react-use` `useWindowScroll` / `useScroll`). `DocProgress` composes it. | `ScrollProgress` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-spinner.webp" width="120" alt="Spinner"> | [`Spinner`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#spinner) | Loading spinner in several styles and colours. | `Spinner` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-toast.webp" width="120" alt="Toaster"> | [`Toaster`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#toast), `toast`, `toasts`, `Toast` | Sonner toasts with icon and action. `toasts` provides `success` / `error` / `warning` / `info` / `loading` presets. | `Toaster`, `toast`, `toasts`, `Toast` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-skeleton.webp" width="120" alt="Skeleton"> | [`Skeleton`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#skeleton), `SkeletonAvatar`, `SkeletonCard`, `SkeletonText`, `SkeletonTable` | Loading placeholder and ready-made shapes. | `Skeleton` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-hydrateloading.webp" width="120" alt="HydrateLoading"> | [`HydrateLoading`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#hydrateloading) | Full-area spinner shown while hydrating. | `HydrateLoading` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/feedback-status-notifications.webp" width="120" alt="Notifications"> | [`Notifications`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/feedback-and-status.md#notifications) | Notification centre as a bell popover with an unread count, or as an inline panel, with filters and read / dismiss. | `Notifications` |
 
 ### Media & files
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `S3UploadField`, `NetworkUploadField` · `S3UploadFormField`, `NetworkUploadFormField` | Drag-and-drop uploader with progress, retry, previews and size / count limits. The S3 variant uploads through a presigned PUT. | `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField` |
-| `UploadField` · `UploadFormField` | Labelled file input showing the chosen file's name. | `UploadField`, `UploadFormField` |
-| `FileList`, `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | File list with type icons, size, download and remove. The field variants upload with progress. | `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField` |
-| `FilesFormField` | Free-solo autocomplete of file URLs, with image thumbnails. | — |
-| `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | Single image upload with preview and progress. | `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField` |
-| `ImageCropper`, `ImageCropperDialog` | Crop with zoom, rotation, aspect presets and a round shape; outputs a `File`. | `ImageCropper`, `ImageCropperDialog` |
-| `Gallery`, `LightboxGallery`, `MiniGallery` | Image / video gallery (grid, masonry, justified, carousel…) with a lightbox and selection. | `Gallery`, `LightboxGallery`, `MiniGallery` |
-| `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` | Embla carousel with keyboard navigation. | `Carousel` (same parts) |
-| `PdfReader`, `PdfViewer`, `PdfToolbar`, `PdfSidebar`, `PdfPageList`… | Browser-only PDF reader with zoom, rotation, search, thumbnails, outline and print. | `PdfReader`, `PdfViewer` (same parts) |
-| `StxPlayer`, `StxPlayerProvider`, `StxPlayerMini`, `StxPlayerQueue`… | Video / audio player with a queue, captions, playback rate, PiP, and full or mini layouts. | `StxPlayer` (same parts) |
-| `VideoPlayer` | Deprecated alias of `StxPlayer`. | `VideoPlayer` |
-| `PrintHeader`, `PrintSection`, `PrintTable`, `PrintTotals`, `PrintCard`… | `@react-pdf/renderer` building blocks for printable PDF documents, with a shared `tw`. | `PrintHeader`, `PrintSection`, `PrintTable`, `PrintTotals`, `PrintCard` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-s3uploadfield.webp" width="120" alt="S3UploadField"> | [`S3UploadField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#s3uploadfield-networkuploadfield), `NetworkUploadField` · `S3UploadFormField`, `NetworkUploadFormField` | Drag-and-drop uploader with progress, retry, previews and size / count limits. The S3 variant uploads through a presigned PUT. | `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-uploadfield.webp" width="120" alt="UploadField"> | [`UploadField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#uploadfield) · `UploadFormField` | Labelled file input showing the chosen file's name. | `UploadField`, `UploadFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-filelist.webp" width="120" alt="FileList"> | [`FileList`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#filelist), `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | File list with type icons, size, download and remove. The field variants upload with progress. | `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField` |
+| — | [`FilesFormField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#filesformfield) | Free-solo autocomplete of file URLs, with image thumbnails. | — |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-imagefield.webp" width="120" alt="ImageField"> | [`ImageField`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#imagefield), `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | Single image upload with preview and progress. | `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-imagecropper.webp" width="120" alt="ImageCropper"> | [`ImageCropper`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#imagecropper), `ImageCropperDialog` | Crop with zoom, rotation, aspect presets and a round shape; outputs a `File`. | `ImageCropper`, `ImageCropperDialog` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-gallery.webp" width="120" alt="Gallery"> | [`Gallery`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#gallery-lightboxgallery-minigallery), `LightboxGallery`, `MiniGallery` | Image / video gallery (grid, masonry, justified, carousel…) with a lightbox and selection. | `Gallery`, `LightboxGallery`, `MiniGallery` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-carousel.webp" width="120" alt="Carousel"> | [`Carousel`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#carousel), `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` | Embla carousel with keyboard navigation. | `Carousel` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-pdfreader.webp" width="120" alt="PdfReader"> | [`PdfReader`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#pdfreader), `PdfViewer` (deprecated alias), `PdfToolbar`, `PdfSidebar`, `PdfPageList`… | Browser-only PDF reader with zoom, rotation, search, thumbnails, outline and print. | `PdfReader`, `PdfViewer` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-stxplayer.webp" width="120" alt="StxPlayer"> | [`StxPlayer`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#stxplayer), `StxPlayerProvider`, `StxPlayerMini`, `StxPlayerQueue`… | Video / audio player with a queue, captions, playback rate, PiP, and full or mini layouts. | `StxPlayer` (same parts) |
+| — | [`VideoPlayer`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#videoplayer) | Deprecated alias of `StxPlayer`. | `VideoPlayer` |
+| — | [`PrintDocument`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#print-components), `PrintHeader`, `PrintSection`, `PrintTable`, `PrintTotals`, `PrintCard`, `PrintDataTable`, `PrintKeyValue`, `PrintMetric`… | `@react-pdf/renderer` page shell (size, margins, repeated header and footer, page numbers, watermark) and building blocks for printable PDF documents, with a shared `tw`; tables, detail blocks and figures from column definitions and plain rows. From `@nxgt/material/print`, not `/components`. | `PrintHeader`, `PrintSection`, `PrintTable`, `PrintTotals`, `PrintCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/media-files-map.webp" width="120" alt="Map"> | [`Map`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/media-and-files.md#map), `Marker`, `LocationMarker`, `LocationPreview`, `MapActions`, `MinimapControl` · `LocationField`, `LocationFormField` | Leaflet map, markers, controls and a location field. From `@nxgt/material/map`, not `/components`: browser-only, optional peers, `map.css` ([maps guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/maps.md)). | `Map`, `Marker`, `LocationMarker`, `LocationPreview`, `MapActions` · `LocationField`, `LocationFormField` (`@nxgt/material-vue/map`) |
 
 ### Rich widgets
 
-| Component | What it does | @nxgt/material-vue |
-| --- | --- | --- |
-| `ChatInbox`, `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer`, `ChatConversationItem`… | Chat kit: inbox (list + thread, container queries from `@md`), auto-scrolling list, streaming and tool messages, a composer with attachments, and markdown. | `ChatInbox`, `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer` (same parts) |
-| `Kanban` | Board with columns, swimlanes, WIP limits, search, and drag-and-drop cards and columns. | `Kanban` |
-| `EventCalendar` | Month / week / day / agenda calendar with drag, resize and slot creation. | `EventCalendar` |
-| `AreaChart`, `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `ScatterChart`, `FunnelChart`, `HeatmapChart` | Nivo charts themed from the CSS tokens, with loading and empty states (`ChartContainer`). | same names |
-| `EmojiPicker`, `EmojiList` | Shared picker. `ChatComposer` takes `emojis`; `Markdown` expands `:shortcode:`; the RTE toolbar uses the same picker. | `EmojiPicker`, `EmojiList` |
-| `MentionList` | `@` mention list from an `items` prop (local search). ChatComposer and the RTE suggestion list use it. | `MentionList` |
-| `RichTextEditor` · `RichTextEditorFormField` | Tiptap editor with toolbar, bubble menu, slash commands, mentions, tables, emoji and images. | `RichTextEditor`, `RichTextEditorFormField` |
-| `CodeEditor` · `CodeEditorFormField` | Monaco editor field with a label and a language switch. | `CodeEditor` |
-| `Quiz`, `QuestionCard` | Quiz and question cards composed from Card, ActionCard, GaugeCard, ChecklistCard, ProgressField and TextField. Container queries. | `Quiz`, `QuestionCard` |
+| Preview | Component | What it does | @nxgt/material-vue |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-chat-overview.webp" width="120" alt="ChatInbox"> | [`ChatInbox`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#chat-kit), `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer`, `ChatConversationItem`… | Chat kit: inbox (list + thread, container queries from `@md`), auto-scrolling list, streaming and tool messages, a composer with attachments, and markdown. | `ChatInbox`, `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-kanban.webp" width="120" alt="Kanban"> | [`Kanban`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#kanban) | Board with columns, swimlanes, WIP limits, search, and drag-and-drop cards and columns. | `Kanban` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-eventcalendar.webp" width="120" alt="EventCalendar"> | [`EventCalendar`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#eventcalendar) | Month / week / day / agenda calendar with drag, resize and slot creation. | `EventCalendar` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-charts-areachart.webp" width="120" alt="AreaChart"> | [`AreaChart`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#charts), `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `ScatterChart`, `FunnelChart`, `HeatmapChart` | Nivo charts themed from the CSS tokens, with loading and empty states (`ChartContainer`). | same names |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-emojipicker.webp" width="120" alt="EmojiPicker"> | [`EmojiPicker`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#emojipicker), `EmojiList` | Shared picker. `ChatComposer` takes `emojis`; `Markdown` expands `:shortcode:`; the RTE toolbar uses the same picker. | `EmojiPicker`, `EmojiList` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-mentionlist.webp" width="120" alt="MentionList"> | [`MentionList`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#mentionlist) | `@` mention list from an `items` prop (local search). ChatComposer and the RTE suggestion list use it. | `MentionList` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-richtexteditor.webp" width="120" alt="RichTextEditor"> | [`RichTextEditor`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#richtexteditor) · `RichTextEditorFormField` | Tiptap editor with toolbar, bubble menu, slash commands, mentions, tables, emoji and images. | `RichTextEditor`, `RichTextEditorFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-codeeditor.webp" width="120" alt="CodeEditor"> | [`CodeEditor`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#codeeditor) · `CodeEditorFormField` | Monaco editor field with a label and a language switch. | `CodeEditor` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/previews/rich-widgets-quiz.webp" width="120" alt="Quiz"> | [`Quiz`](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/rich-widgets.md#quiz), `QuestionCard` | Quiz and question cards composed from Card, ActionCard, GaugeCard, ChecklistCard, ProgressField and TextField. Container queries. | `Quiz`, `QuestionCard` |
 
 `@nxgt/material-vue` also has components with no React counterpart here:
-`Camera`, `ScrollArea`, `NativeSelect` and the `InputOTP` primitives.
-
-## Helpers
-
-Everything below is also re-exported from the root `@nxgt/material` barrel.
-The Vue sister, `@nxgt/material-vue`, uses the **same names** for the plain
-functions; the differences are listed under each table.
-
-### `@nxgt/material/lib`
-
-| Export | What it does |
-| --- | --- |
-| `cn(...classes)` | `clsx` + `tailwind-merge`: joins conditional classes, last Tailwind utility wins. |
-| `clientOnly(Component)` | Wraps a component so it renders nothing on the server and mounts only on the client. |
-| `renderSlot(slot, context)` | Resolves a `ContentSlot` — a `ReactNode` or a `(context) => ReactNode`. |
-| `DATE_UTILS` | `format(iso, 'PP', locale?)` (`'-'` when empty), `parseFromTimestring('HH:mm')`, `parseFromISOString`, `formatDateRangeFilter`. |
-| `formatDateRangeFilter(range)` | Turns a day-picker range into `{ from, to }` ISO strings at start / end of day. |
-| `formatNumber(value, { language?, ...Intl.NumberFormatOptions })` | `Intl.NumberFormat` with a language shortcut (`'en-US'` by default). |
-| `ifEmptyString(value, fallback)`, `ifEmptyList(value, fallback)` | Returns the fallback when the string / array is null or empty. |
-| `objectToFormData(obj)`, `formDataToObject(formData)` | Converts a flat object to `FormData` (skipping nullish values) and back. |
-| `convertToFormData(files, fieldName = 'files')` | Appends one file or a list of files to a new `FormData`. |
-| `uniqueArray(array)` | De-duplicates an array. |
-| `findByKey(array, key, value)`, `findByKeyIn(array, key, values)` | Finds the first item / every item whose `key` matches. |
-| `useFindByKey(items, key)`, `useFindById(items)` | Memoised `findByKey` / `findByKeyIn` bound to a list. |
-| `pick(obj, keys)`, `omit(obj, keys)` | Typed pick / omit for one key or a list. |
-| `cleanObject(obj, cleanNulls?)` | Drops `undefined` (and optionally `null`) properties. |
-| `cast<T>(value)`, `castAsync<T>(promise)` | Type-only casts. |
-| `delay(ms)` | Promise that resolves after `ms`. |
-| `safeGetItem(key, default)`, `safeSetItem(key, value)`, `safeRemoveItem(key)` | JSON `localStorage` access that never throws (SSR, private mode). Grouped as `LOCALE_STORE_UTILS`. |
-| `enumToKebabCase(value)`, `joinTruthyParts(parts, sep = ', ')`, `splitMatch(text, query)` | `SOME_ENUM` → `some-enum`; joins the truthy parts only; splits a string around case-insensitive matches. Grouped as `STRING_UTILS`. |
-| `STYLES_UTILS.colorFromVariable(name, alpha?)` | `rgb(from var(--name) r g b / alpha)` for a theme token. |
-| `searchParams(request)`, `searchParam(request, key)` | Reads the query string of a Fetch `Request` (loaders, actions). |
-| `isExternalHref(href)` | True for `http(s):` and `mailto:` — new tab, not in-app. |
-| `buildFieldOptions(values, { valueKey, label })` | Maps records to `{ value, label }` options by path or label function. |
-| `zodLocaleError()` | Zod v4 `customError` that translates issues through `material.zod.*`: `z.config({ customError: zodLocaleError() })`. |
-| `parsedType(data)` | Runtime type name used for Zod's `{received}` placeholder. |
-
-**Redux Toolkit helpers** (same subpath) — the state pattern behind filter,
-gallery, kanban and player:
-
-| Export | What it does |
-| --- | --- |
-| `useSliceReducer(slice, initialState?)` | Runs an RTK slice as *local* component state via `useReducer`; returns `[state, boundActions]`. |
-| `resolveSliceState(base, overrides?)` | Merges a slice's initial state with partial overrides. |
-| `useSliceSelector(state, selector)` | Memoised selector over local slice state. |
-| `useActions(actionCreators, deps?)` | Binds action creators to the store `dispatch` (`react-redux`). |
-| `createStatusSlice({ name, … })` | Slice over a `Status<T>` with `reset`, `start`, `success(data)` and `error(message)`. |
-| `createStatusesSlice({ name, initialState, … })` | Same for a record of named `Status` entries, addressed by path. |
-| `createStepFormSlice({ name, initialState? })` | Multi-step form: `step`, `values`, `isDirty`, with `updateStep`, `updateFormValues`, `reset`. |
-| `createSliceWithFilter({ name, initialState, … })` | Adds `updateFilter` and `resetFilter` for a `{ filter, sort }` state. |
-| `createAsyncSlice` | `buildCreateSlice` with the `asyncThunk` creator enabled. |
-
-Vue: the Redux helpers are Pinia store factories — `defineLocalStore`
-(per-instance store, like `useSliceReducer`), `defineStatusStore`,
-`defineStatusesStore`, `defineStepFormStore`, `defineFilterStore`,
-`resolveStoreState`, plus `runStatus`. `createAsyncSlice`, `useActions` and
-`useSliceSelector` have no Vue counterpart.
-
-### `@nxgt/material/hooks`
-
-| Export | What it does |
-| --- | --- |
-| `useTheme()` | `{ theme, preference, updateTheme }`: light / dark / system, stored in `localStorage`, applied as the `dark` class. |
-| `resolveTheme(stored, prefersDark)`, `applyResolvedTheme(theme)` | The pure theme logic behind `useTheme`, usable in an inline boot script. |
-| `useIsClient()` | `false` on the server and first render, `true` after mount — a hydration guard. |
-| `useIsMobile()` | `true` below 768 px. |
-| `useHeadingSpy(ids, onActive, options?)` | IntersectionObserver over heading ids; reports the topmost visible one. |
-| `useLocalizedDate()` | `{ language, locale, format }`: `DATE_UTILS.format` bound to the `I18nProvider` language. |
-| `useNumberFormatter()` | `{ formatNumber, formatCurrency }` bound to the `I18nProvider` language. |
-| `useOptions(items, { value, label, filter?, expanded? })` | Memoised `{ value, label }` options for selects; `buildOptions` is the non-hook version. |
-| `extractNode(connection)` | Unwraps a GraphQL `{ edges: [{ node }] }` connection into an array. |
-| `useSearchParam(name)` | One query-string value from the router (`react-router`). |
-| `useNavigationHandler(to, options?)`, `useNavigationHandlers(routes)` | Stable click handlers that navigate (`react-router`). |
-| `useAllowedTransitions(status, transitions, configs)` | Status-machine actions (icon, colour, label, dialog copy) allowed from the current status. |
-
-Vue: `@nxgt/material-vue/composables`, same names.
-
-### `@nxgt/material/i18n`
-
-| Export | What it does |
-| --- | --- |
-| `I18nProvider` | Holds the current language (props `defaultLanguage`, `initialLanguage` for SSR, `storageKey`, `supportedLanguages`, `onLanguageChange`). |
-| `useI18nContext()`, `useOptionalI18nContext()` | Reads `{ language, setLanguage, … }`; the first throws outside the provider, the second returns `null`. |
-| `mergeResources(base, app)` | Deep, per-language merge (`lodash.merge`) of the package bundle and yours; your leaf keys win, and each override is warned about outside production. |
-| `resources` | The package's `en` / `fr` bundle, namespace `material`. |
-| `createTranslator(resources, getLanguage?)` | ICU MessageFormat translator; a missing key comes back verbatim. |
-| `createTypedTranslation(translate)` | Turns a translator into a typed `useTranslation()` hook. |
-| `translate`, `useMaterialTranslation()` | Translator / hook bound to the package's own `material.*` keys. |
-| `getLanguage()` | Language read from `localStorage`, else `FALLBACK_LANGUAGE`. |
-| `LANGUAGE_KEY`, `FALLBACK_LANGUAGE`, `SUPPORTED_LANGUAGES` | Storage key (`'language'`), fallback and supported languages (`en`, `fr`). |
-
-Types: `FlatObject`, `Path`, `Language`, `MaterialLocaleKey`, `Translate`,
-`TranslationContext`, `ResourceBundle`. Vue adds `provideI18n()` for apps that
-provide the context from `setup()` instead of the component.
-
-### `@nxgt/material/models`, `/types`
-
-| Export | What it does |
-| --- | --- |
-| `Status<T>` | `{ data?, status: 'idle' \| 'loading' \| 'success' \| 'error', error? }` — the shape the status slices manage. |
-| `PromiseOr<T>`, `FunctionOr<T, R>`, `AsyncFunctionOr<T, R>` | A value or a promise; a value or a function computing it. |
-| `Predicate<T>`, `AsyncPredicate<T>` | `(arg) => boolean` and its async form. |
+`Camera`, `NativeSelect` and the `InputOTP` primitives.
 
-### `@nxgt/material/dnd`
+## Traps
 
-The drag-and-drop layer on `@dnd-kit`, also in `/components`:
+The ones that cost the most time. Every error message, with its fix, is in
+[troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/troubleshooting.md).
 
-| Export | What it does |
+| Symptom | Fix |
 | --- | --- |
-| `DndProvider`, `DndOverlay` | The `DndContext` (sensors, collision detection) and the floating drag preview. |
-| `Draggable`, `Droppable`, `DraggableDroppable`, `DragHandle` | Primitives for free drag, drop zones, nested boards and handles. |
-| `Sortable`, `SortableProvider` | A sortable item and its list context. |
-| `useDndItem`, `useDndActiveId` | The item's drag state; the id being dragged. |
-| `insertIds`, `arrayMove`, `composeRefs` | Pure list and ref helpers. |
-| `closestCenter`, `pointerWithin`, `rectIntersection`, `verticalListSortingStrategy`, `horizontalListSortingStrategy`, `CSS` | Re-exported from `@dnd-kit`. |
-
-## SSR
-
-An SSR app that bundles this package (`ssr.noExternal: ['@nxgt/material']`)
-runs every module the barrels reach when the server **boots**, whether or not
-a page renders the component.
-
-- **Nothing browser-only at module scope.** `pdfjs-dist` runs
-  `new DOMMatrix()` at import. Load it with `import()` and wrap the component
-  in `clientOnly` from `@nxgt/material/lib`. A `typeof window` guard around a
-  statement does nothing when the *import* itself is the side effect.
-- **Print is not in the barrel.** `@nxgt/material/print` is the only entry that
-  reaches `@react-pdf/renderer`, because through it `pdfkit` enters the server
-  bundle and its standard fonts cannot resolve there — a server that throws on
-  every request rather than a fat one. `bun run build` fails if another entry
-  reaches it. See [Printing](#printing).
-- **Maps are not in the barrel either, and are stricter.** `@nxgt/material/map`
-  is the only entry that reaches `leaflet`, which reads `window` at import — so
-  an entry that reached it would kill a consumer's server at boot rather than on
-  a request. Render it client-side only. See [Maps](#maps).
-- **Never `<svg><title>`.** React 19 hoists `<title>` as document metadata:
-  the server emits `<title></title>` while the client renders the text, and
-  the hydration mismatch makes React discard the whole tree. Use
-  `role="img"` + `aria-label` instead (`Icon` already does).
-
-## Traps
-
-| Symptom | Cause | Fix |
-| --- | --- | --- |
-| Components render unstyled, no console error | Tailwind did not scan the package | `@source "../node_modules/@nxgt/material/"` |
-| `<Icon>` is blank | sprite sheet not served | `public/assets/icons/sprites/<style>.svg` |
-| Package strings change after adding i18n | your resources define keys under `material` | keep app strings in your own namespaces; `console.warn` lists each override in development |
-| Hydration mismatch on every page | `<svg><title>` | `role="img"` + `aria-label` |
-| `ReferenceError: DOMMatrix` at server boot | static `react-pdf` import | `import()` + `clientOnly` |
-| Built server answers `000` on every route; log says `Cannot find module '#standard-fonts/Helvetica'` | `@nxgt/material/print` bundled into the server; pdfkit's fonts cannot resolve in a bundle | leave the library external, or `pdfkitStandardFonts()` from `@nxgt/material/vite` ([Printing](#printing)) |
-| `Cannot find package '@react-pdf/renderer'` | 2.0.0 made it an optional peer | `bun add @react-pdf/renderer react-pdf-tailwind` in the app that prints |
-| `window is not defined` at server boot, blank page | `@nxgt/material/map` rendered in a server pass | wrap it in `clientOnly` from `@nxgt/material/lib` ([Maps](#maps)) |
-| `Cannot find package 'leaflet'` | the map peers are optional | `bun add leaflet react-leaflet @react-leaflet/core @adamscybot/react-leaflet-component-marker react-geolocated` |
-| Map tiles render with no controls or broken layout | leaflet's CSS missing | `import '@nxgt/material/map.css'` — it is not part of `styles.css` |
+| Components render unstyled, no console error | `@source "../node_modules/@nxgt/material/";` in your stylesheet |
+| `<Icon>` is blank | serve `public/assets/icons/sprites/<style>.svg` |
+| `window is not defined` at server boot | load `@nxgt/material/map` through `import()` + `clientOnly` ([maps](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/maps.md#browser-only)) |
+| `ERESOLVE` / `Conflicting peer dependency: @react-pdf/renderer` after upgrading | `bun add @react-pdf/renderer@^4.9` ([troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/troubleshooting.md#conflicting-peer-dependency-react-pdfrenderer)) |
+| `renderToBuffer is a Node specific API` on a server, or PDFs fail on an edge runtime | render on Node 18+ or Bun, with react-pdf's Node build ([troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/troubleshooting.md#rendertobuffer-is-a-node-specific-api)) |
+| `Cannot find module '#standard-fonts/Helvetica'` on a built server | leave the library external, or `pdfkitStandardFonts()` ([printing](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/printing.md#bundling-print-into-an-ssr-server)) |
+
+## Documentation
+
+- [docs/README.md](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/README.md) — every page, and when to read it
+- [Components gallery](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/components/README.md) — one page per category, a preview per component
+- [Forms guide](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/guides/forms.md)
+- [Troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/troubleshooting.md) — every error message, and
+  [how to report a bug](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/troubleshooting.md#reporting-a-bug)
+- [Roadmap](https://cdn.jsdelivr.net/npm/@nxgt/material@2/docs/roadmap.md)
+- Storybook: `bun run storybook` in this repository; the sidebar has the same twelve categories
 
 ## Development
 
 ```sh
 bun install
-bun run build      # what consumers read
+bun run build          # what consumers read
 bun run storybook
-bun run test
+bun run test           # unit tests
+bun run test:stories   # every story rendered in Chromium (Vitest browser mode)
+bun run docs:previews  # re-capture docs/previews/*.webp after a visual change
 ```
 
 ## License