@nxgt/material-vue 0.21.0 → 0.22.0

package/README.md

@@ -5,38 +5,47 @@ drag-and-drop, i18n and `Icon`. Built on Tailwind CSS v4 and shadcn-vue
 (Reka UI), with Pinia for widget state and vee-validate for forms.
 
 It is the Vue mirror of [`@nxgt/material`](https://www.npmjs.com/package/@nxgt/material)
-(React). Component names match wherever both libraries ship the same thing;
-the [catalogue](#components) lists the React equivalent for each entry.
+(React). Component names, categories, documentation pages and preview images
+match wherever both libraries ship the same thing; the [catalogue](#components)
+lists the React equivalent for each entry.
 
 ## At a glance
 
-- **380+ exported components in 169 catalogue entries**, grouped in 12
-  categories in the [catalogue](#components): from shadcn-vue primitives to
-  kanban, event calendar, charts, documentation pages, rich-text editor, PDF
-  reader and media player.
+- **170 catalogue entries in 12 categories**, nearly all with a preview
+  ([Components](#components), and the [gallery](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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 reader and media player.
 - **Form fields, standalone or vee-validate.** Each field works with `v-model`,
-  and most have a `*FormField` wrapper that binds to a vee-validate form by `name`.
-  See [Form fields](#form-fields).
-- **Helpers**: `cn`, `clientOnly`, date, number and string utilities, Pinia
-  store factories (`defineLocalStore`, …) and composables (`useTheme`,
-  `useIsMobile`, …). See [Helpers](#helpers).
-- **i18n built in**: `I18nProvider`, ICU messages, English and French strings
-  for every component, and a way to merge in your own resources.
-- **Nuxt module**: auto-imports components and composables, and installs Pinia.
-- **SSR-safe barrels**: browser-only widgets (PDF, Monaco, webcam, player) are
-  lazy and client-only.
+  and most have a `*FormField` wrapper that binds to a vee-validate form by
+  `name`. The [forms guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/forms.md) covers Zod
+  validation, composite values, config-driven forms and server errors.
+- **Helpers** ([helpers guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/helpers.md)): `cn`,
+  `clientOnly`, date, number and string utilities, a Zod error map, Pinia store
+  factories in `/lib`, and composables (`useTheme`, `useIsMobile`, …) in
+  `/composables`.
+- **i18n** ([i18n guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/i18n.md)): an `I18nProvider`
+  with ICU messages and shipped `en` / `fr` strings. Your app merges in its own
+  resources.
+- **PDF documents** ([PDF guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/pdf.md)):
+  `@nxgt/material-vue/pdf` builds PDF files from plain data, in the browser or
+  a Nuxt server route, with the same document model as `@nxgt/material/print`.
+- **Nuxt module**: auto-imports components and composables, and installs Pinia
+  ([SSR and Nuxt](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/ssr.md)).
+- **SSR-safe barrels**: no browser globals at import, and browser-only widgets
+  (PDF, Monaco, webcam, player) are lazy and client-only.
+- **React sister**: `@nxgt/material` uses the same names, categories and pages.
 
 ## Contents
 
 - [Install](#install)
-- [Setup](#setup): styles, Pinia and router, icons, Nuxt
+- [Setup](#setup)
 - [Subpaths](#subpaths)
 - [Usage](#usage)
-- [Maps](#maps)
+- [Guides](#guides)
 - [Components](#components)
-- [Helpers](#helpers)
-- [SSR](#ssr)
 - [Traps](#traps)
+- [Documentation](#documentation)
 - [Development](#development)
 - [License](#license)
 
@@ -58,10 +67,14 @@ stores silently split between two instances.
 | `vue-router` | `^4.5 \|\| ^5` | app shell, `LinkButton`, `useSearchParam`, `useNavigationHandler` |
 | `vee-validate` | `^4.15` | every `*FormField` and the built-in forms (attributes, contacts, …) |
 | `@tanstack/vue-table` | `^9` | `DataTable` |
-| `@vueuse/core` | `^13 \|\| ^14` | `useIsMobile`, `useTheme`, `ScrollProgress` (`useScroll` / `useWindowScroll`), `CopyButton` (`useClipboard`), prop forwarding in primitives |
+| `@vueuse/core` | `^13 \|\| ^14` | `useIsMobile`, `useTheme`, `ScrollProgress`, `CopyButton`, prop forwarding in primitives |
+| `leaflet`, `@vue-leaflet/vue-leaflet` | `^1.9`, `^0.10` | optional: only for `@nxgt/material-vue/map` |
+| `react`, `@react-pdf/renderer` | `^18.2 \|\| ^19`, `^4.9` | optional: only to render with `@nxgt/material-vue/pdf` |
 | `nuxt` | `>=3.13` | optional: only for `@nxgt/material-vue/nuxt` |
 
-The tarball ships `dist/`, plus `lib/styles.css` and `lib/nuxt`. There is no
+The tarball ships `dist/`, `docs/`, the stylesheets (`lib/styles.css`, the
+component stylesheets it imports, `lib/components/**/*.css`, and
+`lib/map/map.css`) and the Nuxt module (`lib/nuxt`, with the `lib/vite/index.ts` it imports). There is no
 `postinstall` build.
 
 ## Setup
@@ -77,32 +90,18 @@ Import the stylesheet **explicitly**, in your Tailwind v4 entry, right after
 @import "@nxgt/material-vue/styles.css";
 ```
 
-Nothing injects it for you, on purpose:
-
-- Tailwind v4 builds **one** `@theme` from a single CSS graph. `@theme` /
-  `@utility` only apply when `styles.css` is imported in the same file as
-  `@import "tailwindcss"`; a second stylesheet (for example another Nuxt
-  `css[]` entry) starts a second pipeline, and the tokens never reach the app.
-- Tailwind CSS IntelliSense reads the theme from that entry file. An explicit
-  import lets it autocomplete the library tokens (`bg-primary`,
-  `text-error-foreground`, `rounded-lg`, …) in your templates.
-
-Tailwind v4 does not scan `node_modules`. `styles.css` already declares
-`@source "../dist"`, so your build generates the utilities used inside the
-components. You don't need an extra `@source`.
-
-| Import | What is in it |
-| --- | --- |
-| `@import "@nxgt/material-vue/styles.css"` | source Tailwind v4 tokens, `@theme`, `@utility`: **this** is what a Tailwind app imports |
-| `@import "@nxgt/material-vue"` | `style` condition of the root export → `dist/material-vue.css`: compiled, self-contained CSS (tokens + every utility the components use), for apps without Tailwind |
-
-Do not import both in the same app.
+`styles.css` is the **source** `@theme` layer and already declares the
+`@source` that makes your build generate the utilities used inside the
+components. It only applies when imported in the same file as
+`@import "tailwindcss"`: a second stylesheet (another Nuxt `css[]` entry)
+starts a second pipeline and the tokens never reach the app. Apps without
+Tailwind import the compiled `@nxgt/material-vue` style condition instead —
+never both. Details in [theming](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/theming.md).
 
 ### Pinia and router
 
-Interactive widgets keep their UI state in Pinia stores created per instance,
-so Pinia must be installed before mount. The app shell and link buttons read
-the current route, so install vue-router as well:
+Widgets keep their UI state in Pinia stores created per instance, and the app
+shell and link buttons read the current route:
 
 ```ts
 // main.ts
@@ -126,20 +125,17 @@ import { Icon } from '@nxgt/material-vue/components';
 </script>
 
 <template>
-  <Icon name="atom" />                          <!-- /assets/icons/sprites/duotone.svg#atom -->
-  <Icon name="gear" type="solid" />             <!-- /assets/icons/sprites/solid.svg#gear -->
-  <Icon name="gear" family="sharp" type="solid" /> <!-- /assets/icons/sprites/sharp-solid.svg#gear -->
+  <Icon name="atom" />  <!-- /assets/icons/sprites/duotone.svg#atom -->
 </template>
 ```
 
-`type` defaults to `duotone` and `family` to `classic`. Serve the sprite
-sheets from `public/assets/icons/sprites/<file>.svg`. This package does **not**
-ship them, because the Font Awesome Pro licence does not cover redistribution
-inside a library. A missing sheet renders nothing: no error, no fallback.
+Serve the sprite sheets from `public/assets/icons/sprites/<file>.svg`. This
+package does **not** ship them: the Font Awesome Pro licence does not cover
+redistribution inside a library. A missing sheet renders nothing, with no error
+and no fallback.
 
-Some components draw an `Icon` themselves: the app shell menu, the mobile menu
-button, `LanguageSwitcher`, `LoadMoreButton` and the `toasts` helpers. Other
-glyphs come from Lucide and are bundled.
+The other glyphs are Lucide, from `@lucide/vue`: a dependency of this package,
+left out of `dist/` and installed with it.
 
 ### Nuxt
 
@@ -151,76 +147,40 @@ export default defineNuxtConfig({
 	modules: ['@nxgt/material-vue/nuxt'],
 	css: ['~/assets/css/main.css'], // imports styles.css, see above
 	vite: { plugins: [tailwindcss()] },
-	nxgtMaterial: {
-		// prefix: 'Nxgt',     // <NxgtButton />
-		// components: true,   // auto-import components
-		// imports: true,      // auto-import composables and i18n helpers
-	},
 });
 ```
 
-The module:
-
-- Auto-imports components and composables
-- Installs Pinia when the host app has none
-- Pre-bundles CommonJS dependencies (`jsbarcode`) for Vite
-
-It does **not** add the stylesheet. Import it yourself as shown in
-[Styles](#styles).
+The module auto-imports components and composables and installs Pinia; it
+does not add the stylesheet. Options and the client-only widgets are in
+[SSR and Nuxt](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/ssr.md).
 
 ## Subpaths
 
 | Specifier | What is in it |
 | --- | --- |
 | `@nxgt/material-vue` | every barrel below, plus the compiled `style` condition (`dist/material-vue.css`, for apps without Tailwind) |
-| `@nxgt/material-vue/components` | UI components and `*FormField` wrappers |
-| `@nxgt/material-vue/map` | Leaflet maps, markers, a location field — **its own entry, not in the barrel** ([Maps](#maps)) |
-| `@nxgt/material-vue/composables` | `useTheme`, `useIsClient`, `useIsMobile`, `useSearchParam`, … |
-| `@nxgt/material-vue/dnd` | drag-and-drop primitives |
-| `@nxgt/material-vue/i18n` | `I18nProvider`, `mergeResources`, `createTranslator`, … |
-| `@nxgt/material-vue/lib` | `cn`, `clientOnly`, date/number/string utils, Pinia store factories |
+| `@nxgt/material-vue/components` | UI components and `*FormField` wrappers ([Components](#components)) |
+| `@nxgt/material-vue/map` | Leaflet maps, markers, a location field — **its own entry, not in the barrel** ([maps guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/maps.md)) |
+| `@nxgt/material-vue/pdf` | PDF files from plain data: builders, `usePdf`, `PdfDownloadButton`, `pdfResponse` — **its own entry, not in the barrel** ([PDF guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/pdf.md)) |
+| `@nxgt/material-vue/composables` | `useTheme`, `useIsClient`, `useIsMobile`, `useSearchParam`, … ([helpers](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/helpers.md)) |
+| `@nxgt/material-vue/dnd` | drag-and-drop primitives ([helpers](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/helpers.md)) |
+| `@nxgt/material-vue/i18n` | `I18nProvider`, `mergeResources`, `createTranslator`, `translateMaterial`, … ([i18n guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/i18n.md)) |
+| `@nxgt/material-vue/lib` | `cn`, `clientOnly`, date/number/string utils, Zod error map, Pinia store factories ([helpers](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/helpers.md)) |
 | `@nxgt/material-vue/models` | `Status<T>` |
 | `@nxgt/material-vue/types` | shared function types |
 | `@nxgt/material-vue/styles.css` | source Tailwind v4 tokens: **this** is what a Tailwind app imports |
 | `@nxgt/material-vue/map.css` | leaflet's stylesheet, for the apps that use `./map`. Not part of `styles.css` |
 | `@nxgt/material-vue/nuxt` | Nuxt module |
+| `@nxgt/material-vue/vite` | `pdfkitStandardFonts()`, a Vite plugin for a server that inlines `/pdf` with no `node_modules` at runtime ([PDF guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/pdf.md#fonts-on-a-fully-inlined-server)) |
 
 ## Usage
 
-### Components
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue';
-import { Button, Icon } from '@nxgt/material-vue/components';
-
-const saving = ref(false);
-</script>
-
-<template>
-  <Button variant="filled" color="primary" :loading="saving" @click="saving = true">
-    <Icon name="plus" />
-    Add
-  </Button>
-</template>
-```
-
-`Button` and `IconButton` take `variant` (`filled`, `tonal`, `outlined`,
-`ghost`, `link`) × `color` (`primary`, `secondary`, `success`, `info`,
-`warning`, `error`, `default`), plus `size`, `loading` and `tooltip`.
-
-### Form fields
-
-Every field is usable on its own with `v-model`. Most also have a vee-validate
-wrapper in the same barrel (`TextField` → `TextFormField`): the wrapper takes
-`name` instead of `v-model` and shows the validation error as helper text.
-
 ```vue
 <script setup lang="ts">
 import { useForm } from 'vee-validate';
-import { Button, EmailFormField, TextFormField } from '@nxgt/material-vue/components';
+import { Button, EmailFormField, Icon, TextFormField } from '@nxgt/material-vue/components';
 
-const { handleSubmit } = useForm({ initialValues: { name: '', email: '' } });
+const { handleSubmit, isSubmitting } = useForm({ initialValues: { name: '', email: '' } });
 const onSubmit = handleSubmit((values) => console.log(values));
 </script>
 
@@ -228,625 +188,408 @@ const onSubmit = handleSubmit((values) => console.log(values));
   <form @submit="onSubmit">
     <TextFormField name="name" label="Name" required />
     <EmailFormField name="email" label="Email" />
-    <Button type="submit">Save</Button>
+    <Button type="submit" variant="filled" color="primary" :loading="isSubmitting">
+      <Icon name="paper-plane" />
+      Invite
+    </Button>
   </form>
 </template>
 ```
 
-For translated Zod messages, register the error map once:
-`z.config({ customError: zodLocaleError() })` (from `@nxgt/material-vue/lib`).
+An `IconButton` needs an accessible name: pass `aria-label` (it reaches the
+`<button>`), or a `tooltip`, which names it when there is no `aria-label`.
 
-### i18n
+`TextFormField` is the vee-validate wrapper of `TextField`: it takes `name`
+instead of `v-model` and shows the validation error as helper text. Every field
+has the same pair. [Getting started](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/getting-started.md) walks
+through a first screen.
 
-This package owns the i18n **mechanism**, and your app owns the resource
-**content**. Everything it ships lives under one namespace per language,
-`material`. `mergeResources` deep-merges your bundle over it, so you can
-override single strings (`material.command.title`). In development each
-override is reported with `console.warn`.
+### Amounts and dates in your locale
 
 ```ts
-// src/i18n.ts
-import {
-	createTranslator,
-	createTypedTranslation,
-	type FlatObject,
-	mergeResources,
-	resources as materialResources,
-} from '@nxgt/material-vue/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);
-```
+import { createFormatters, formatAmount, formatDate } from '@nxgt/material-vue/lib';
+import { useFormatters } from '@nxgt/material-vue/composables';
 
-```vue
-<!-- App.vue: mount once, above everything that translates -->
-<template>
-  <I18nProvider default-language="en">
-    <RouterView />
-  </I18nProvider>
-</template>
-```
+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
 
-Inside any child component, `const { t, i18n } = useTranslation()` gives you
-`t` plus `i18n.language` and `i18n.changeLanguage`. Only `I18nProvider` holds
-the language. Without it, components fall back to their English copy.
-Messages use ICU MessageFormat, and a missing key is returned verbatim.
+const { formatAmount: amount } = useFormatters({ timeZone: 'Europe/Paris' }); // in setup: follows I18nProvider
+const server = createFormatters({ locale: 'fr-FR', timeZone: 'Europe/Paris' }); // a server route
+```
 
-### App shell
+Since 0.22.0 each currency keeps its own decimals;
+`{ fractionDigits: 2 }` keeps two. Options and server rendering:
+[Printing](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/printing.md#formatamount-and-formatdate).
 
-The shell does not build or filter the menu: `items` is a prop, and every
-`label` must already be translated. `footer: true` pins an entry to the bottom
-of the sidebar. The shell holds no session, so the avatar comes from
-`avatar-src` or the `avatar` slot.
+### A PDF from any source
 
 ```vue
 <script setup lang="ts">
-import {
-	ActivityLayout,
-	LanguageSwitcher,
-	type MenuItem,
-	ThemeToggle,
-} from '@nxgt/material-vue/components';
-
-const items: MenuItem[] = [
-	{ label: 'Home', url: '/', icon: 'house' },
-	{ label: 'Settings', url: '/settings', icon: 'gear', footer: true },
-];
+import { PdfReader } from '@nxgt/material-vue/components';
+
+defineProps<{ blob: Blob; bytes: Uint8Array; token: string }>();
 </script>
 
 <template>
-  <ActivityLayout :items="items" avatar-src="/me.png">
-    <template #brand><img src="/logo.svg" alt="Acme" class="h-8" /></template>
-    <template #header-actions>
-      <LanguageSwitcher />
-      <ThemeToggle />
-    </template>
-    <RouterView />
-  </ActivityLayout>
+  <PdfReader file="/documents/contract.pdf" />                                   <!-- a URL -->
+  <PdfReader :file="blob" file-name="INV-1042.pdf" />                            <!-- a Blob or File -->
+  <PdfReader :file="bytes" />                                                    <!-- an ArrayBuffer or Uint8Array, copied -->
+  <PdfReader :file="{ url: '/api/documents/42', httpHeaders: { Authorization: `Bearer ${token}` } }" />
 </template>
 ```
 
-Always fill the `brand` slot, because the default one is a placeholder. The
-active entry is the **longest** matching `url` across the whole menu, matched
-segment by segment (`/admin` does not cover `/administrators`).
-`AppBreadcrumb` lists every matched route that declares
-`meta: { breadcrumb: 'Settings' }` (a string, or a function of the route).
+Give the parent a height. More: [PdfReader](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#pdfreader).
 
-### Local stores
+### PDF documents
 
-Widgets keep their UI state in Pinia stores that are local to each instance.
-Use the same factory for your own components: every call from a component
-`setup()` gets its own store id.
+`@nxgt/material-vue/pdf` renders real PDF files from plain data, with the same
+document model as `@nxgt/material/print`. Its peers are optional:
+`bun add react @react-pdf/renderer@^4.9` in the app that renders.
 
 ```ts
-import { defineLocalStore } from '@nxgt/material-vue/lib';
-
-export const useCounterStore = defineLocalStore<{ count: number }>('counter', {
-	state: () => ({ count: 0 }),
-	actions: {
-		increment(this: { count: number }) {
-			this.count += 1;
-		},
-	},
-});
-
-// in setup(): const store = useCounterStore({ count: 5 });
-```
-
-## Maps
-
-`@nxgt/material-vue/map` mirrors the React package's `@nxgt/material/map`:
-`Map`, `Marker`, `LocationMarker`, `LocationPreview`, `MapActions`, the
-`LocationField` / `LocationFormField` pair, and the `useGeolocation` composable
-they share.
-
-```sh
-bun add leaflet @vue-leaflet/vue-leaflet
+// shared/invoice-pdf.ts
+import { definePdfDocument, header, keyValue, page, table } from '@nxgt/material-vue/pdf';
+
+export type Invoice = { number: string; customer: string; lines: { item: string; amount: number }[] };
+
+export const invoicePdf = definePdfDocument((invoice: Invoice, language = 'en') => ({
+  language,
+  pages: [
+    page({
+      pageNumbers: true,
+      header: [header({ title: 'Invoice', reference: invoice.number })],
+      body: [
+        keyValue([{ label: 'Customer', value: invoice.customer }]),
+        table({
+          columns: [{ label: 'Item', flex: 3 }, { label: 'Amount', align: 'right' }],
+          rows: invoice.lines.map((line) => [line.item, { amount: line.amount, currency: 'EUR' }]),
+        }),
+      ],
+    }),
+  ],
+}));
 ```
 
 ```vue
+<!-- in the browser; usePdf(() => invoicePdf(invoice)) gives { blob, url, loading, error, download } -->
 <script setup lang="ts">
-import '@nxgt/material-vue/map.css';
-import { LocationFormField } from '@nxgt/material-vue/map';
+import { PdfDownloadButton } from '@nxgt/material-vue/pdf';
+import { type Invoice, invoicePdf } from '~~/shared/invoice-pdf';
+
+defineProps<{ invoice: Invoice }>();
 </script>
 
 <template>
-  <LocationFormField name="address" label="Address" />
+  <PdfDownloadButton :document="() => invoicePdf(invoice, 'fr')" :file-name="invoice.number" />
 </template>
 ```
 
-Both are **optional peers**: an app that renders no map never has leaflet in its
-tree. `useGeolocation` wraps `@vueuse/core`'s, a peer this package already
-requires, rather than adding a second geolocation dependency.
-
-### What `Map` does when you pass nothing
+```ts
+// server/api/invoices/[id].pdf.get.ts: a Nitro route
+import { pdfResponse } from '@nxgt/material-vue/pdf';
+import { invoicePdf } from '~~/shared/invoice-pdf';
 
-```vue
-<Map class="size-96">
-  <Marker :position="[48.8566, 2.3522]" />
-</Map>
+export default defineEventHandler(async (event) =>
+  pdfResponse(invoicePdf(await getInvoice(getRouterParam(event, 'id')!), 'fr'), { fileName: 'invoice' }));
 ```
 
-An `LMap` with an OpenStreetMap tile layer and a zoom control, `use-global-leaflet`
-off so it uses the copy it `import()`s itself. The defaults match the React
-entry's, and are not neutral:
+`usePdf` does nothing on the server. Options, fonts on an inlined server and
+runtimes: [PDF documents](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/pdf.md).
 
-| 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 |
-| `zoomControl` | `false` | leaflet's *own* control, off because the component renders an `LControlZoom` at `topleft`. Passing `true` gives you two. |
-
-`useGeolocation` passes `enableHighAccuracy: false` and a 5 s timeout to
-`@vueuse/core`, and returns `coords` as `{ latitude, longitude } | null` — null
-until the first fix, rather than the two `NaN`s vueuse starts with.
-
-**This entry is not auto-registered by the Nuxt module.** Every other component
-is; this one is imported explicitly, because auto-registration would make
-leaflet resolvable from an app that never renders a map.
-
-**Rendering.** `@vue-leaflet/vue-leaflet` loads leaflet with `import()` when a
-component mounts, so — unlike the React mirror, where `react-leaflet` imports it
-statically — this entry *can* be imported in a server process without throwing.
-Leaflet still only initialises in a browser, so the container renders empty until
-it mounts: under Nuxt, wrap it in `<ClientOnly>`.
-
-`MinimapControl` is the one thing the React entry has and this one does not: it
-is built on `@react-leaflet/core`'s internals, which have no counterpart here.
-The React `Marker`'s component-marker dependency has none either — here an
-arbitrary marker is `LIcon`'s slot, which is the Vue-native way:
+## Guides
 
-```vue
-<Marker :position="[5.44, 10.07]">
-  <template #icon><MyPin /></template>
-  <template #tooltip>Warehouse</template>
-</Marker>
-```
+Each area a consumer starts from has its own page under `docs/guides/`.
 
+| Guide | Read it when |
+| --- | --- |
+| [Forms](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/forms.md) | wiring fields to vee-validate and Zod, composite values (contacts, opening hours), config-driven `Field`, server errors, what each field emits |
+| [i18n](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/guides/app-shell.md) | laying out an app with `ActivityLayout`, its `items`, the active entry and breadcrumbs (vue-router) |
+| [Theming](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/guides/printing.md) | printable documents built from the `Print*` components |
+| [PDF documents](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/pdf.md) | PDF files from data with `@nxgt/material-vue/pdf`: builders, `usePdf`, `PdfDownloadButton`, a Nitro route with `pdfResponse`, fonts on an inlined server |
+| [Maps](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/maps.md) | using `@nxgt/material-vue/map` — optional leaflet peers, `map.css`, what `Map` does when you pass nothing |
+| [SSR and Nuxt](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/ssr.md) | rendering on a server or with Nuxt: the module, what the barrels guarantee, `clientOnly` for browser-only code |
+| [Helpers](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/helpers.md) | the non-component subpaths: `/lib`, `/composables`, `/i18n`, `/models`, `/types`, `/dnd` |
 
 ## Components
 
-All components are exported from `@nxgt/material-vue/components` and from the
-root barrel. The name before `·` is the standalone component, and the name
-after it is the vee-validate wrapper. "+ parts" means the family also exports
-sub-components (`CardHeader`, `CardContent`, …). The last column is the
-matching export in [`@nxgt/material`](https://www.npmjs.com/package/@nxgt/material),
-or `—` when the React library has none.
+Everything below is imported from `@nxgt/material-vue/components` (the map
+from `@nxgt/material-vue/map`). Each name links to its entry in
+[`docs/components/`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/README.md) — the preview, an
+example and the options that matter. In the *Component* column, `·` separates
+a field from its vee-validate wrapper, and "+ parts" means the family exports
+more sub-components. The last column gives the matching export in
+[`@nxgt/material`](https://www.npmjs.com/package/@nxgt/material), or `—`
+when React has none. `Combobox` and `FilesFormField` are React entries with
+no Vue counterpart; they keep a row, and their page says what to use
+instead.
 
 ### Primitives
 
-Thin shadcn-vue / Reka UI building blocks, styled with the library tokens.
-
-| Component | What it does | @nxgt/material |
-| --- | --- | --- |
-| `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Collapsible sections, single or multiple open. | `Accordion` |
-| `Avatar`, `AvatarImage`, `AvatarFallback` | Round image with a fallback (initials). | `Avatar` |
-| `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | Surface with header, body and footer areas. | `Card` |
-| `Checkbox` | Checkbox with checked and indeterminate states. | `Checkbox` |
-| `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | Shows or hides one region. | `Collapsible` |
-| `Input` | Styled native input with `v-model`. | `Input` |
-| `InputGroup`, `InputGroupAddon`, `InputGroupInput`, `InputGroupButton`, `InputGroupText`, `InputGroupTextarea` | Input or textarea with inline addons, buttons and text. | `InputGroup` |
-| `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator` | Slot-by-slot one-time-code input. | — |
-| `Label` | Form label; `with-asterisk` marks it required. | `Label` |
-| `NativeSelect`, `NativeSelectOption`, `NativeSelectOptGroup` | Styled native `<select>` with `v-model`. | — |
-| `RadioGroup`, `RadioGroupItem` | Radio primitives (see `RadioGroupField` for the labelled field). | `RadioGroupBase`, `RadioGroupItem` |
-| `ScrollArea`, `ScrollBar` | Scroll container with styled scrollbars. | — |
-| `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem` + parts | Select primitives (see `SelectField` for the labelled field). | `Select` |
-| `Separator` | Horizontal or vertical rule. | `Separator` |
-| `Slider` | Range slider primitive, one or more thumbs. | `Slider` |
-| `Switch` | Switch; with `label` or `placeholder` it renders as a field row. | `Switch` |
-| `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableEmpty` + parts | Styled table markup. | `Table` |
-| `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | Tabbed panels. | `Tabs` |
-| `Textarea` | Styled native textarea with `v-model`. | `Textarea` |
-| `Toggle`, `ToggleGroup`, `ToggleGroupItem` | Pressable toggle and single/multiple toggle groups. | `Toggle`, `ToggleGroup` |
-| `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` | Split panes resized by dragging a handle. | `ResizableGroup`, `ResizablePanel`, `ResizableSeparator` |
-| `Typography` | Text on the type scale (`headline-large`, `title-medium`, `body-small`, …). | `Typography` |
-| `AnchorHeading` | Heading with a hover copy-link (always visible on the phone). | `AnchorHeading` |
-| `Kbd`, `KbdShortcut` | Keyboard key; `KbdShortcut` renders `['mod', 'k']` as ⌘/Ctrl glyphs. | `Kbd`, `KbdShortcut` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-accordion.webp" width="120" alt="Accordion"> | [`Accordion`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-collapsible.webp" width="120" alt="Collapsible"> | [`Collapsible`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-card.webp" width="120" alt="Card"> | [`Card`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-typography.webp" width="120" alt="Typography"> | [`Typography`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-anchorheading.webp" width="120" alt="AnchorHeading"> | [`AnchorHeading`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-label.webp" width="120" alt="Label"> | [`Label`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#label) | Form label with an optional required asterisk. | `Label` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-helpertext.webp" width="120" alt="HelperText"> | [`HelperText`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#helpertext) | Hint or error message under a field. | `HelperText` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-extendedlabel.webp" width="120" alt="ExtendedLabel"> | [`ExtendedLabel`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-input.webp" width="120" alt="Input"> | [`Input`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#input) | Styled native `<input>`. | `Input` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-textarea.webp" width="120" alt="Textarea"> | [`Textarea`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#textarea) | Styled native `<textarea>`. | `Textarea` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-inputgroup.webp" width="120" alt="InputGroup"> | [`InputGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-icon.webp" width="120" alt="Icon"> | [`Icon`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-kbd.webp" width="120" alt="Kbd"> | [`Kbd`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/primitives-separator.webp" width="120" alt="Separator"> | [`Separator`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#separator) | Horizontal or vertical divider. | `Separator` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-table.webp" width="120" alt="Table"> | [`Table`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#table), `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableEmpty` + parts | Styled semantic table inside a scrollable wrapper. | `Table` (same parts; no `TableEmpty`) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-tabs.webp" width="120" alt="Tabs"> | [`Tabs`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#tabs), `TabsList`, `TabsTrigger`, `TabsContent`, `Tabs` | Tabs whose triggers can take an icon. | `Tabs` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-toggle.webp" width="120" alt="Toggle"> | [`Toggle`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#toggle), `ToggleGroup`, `ToggleGroupItem` | Pressable on / off button: default or outline, three sizes. | `Toggle` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-togglegroup.webp" width="120" alt="ToggleGroup"> | [`Toggle`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#togglegroup), `ToggleGroup`, `ToggleGroupItem` | Single or multiple toggle group sharing variant and size. | `ToggleGroup`, `ToggleGroupItem`, `ToggleGroupSeparator` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-activity.webp" width="120" alt="Activity"> | [`Activity`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#activity) | Keeps its content mounted and hides it with a boolean `visible`. | `Activity` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/primitives-scrollarea.webp" width="120" alt="ScrollArea"> | [`ScrollArea`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/primitives.md#scrollarea), `ScrollBar` | Scroll container with a thin custom scrollbar that matches the theme. | `ScrollArea`, `ScrollBar` |
 
 ### Buttons & actions
 
-| Component | What it does | @nxgt/material |
-| --- | --- | --- |
-| `Button` | Button with 5 variants × 7 colours, sizes, `loading` spinner and `tooltip`. | `Button` |
-| `IconButton` | Round icon-only button with the same variants and colours. | `IconButton` |
-| `ButtonGroup` | Lays out related buttons as one group. | `ButtonGroup` |
-| `ResponsiveButton` | Label on desktop, icon only on mobile; `expanded` forces either. | `ResponsiveButton` |
-| `LinkButton`, `IconLinkButton`, `ResponsiveLinkButton` | Buttons that navigate with vue-router (`to`, `replace`, `target`). | `LinkButton`, `IconLinkButton`, `ResponsiveLinkButton` |
-| `SplitButton` | Main action plus a chevron menu filled by the `menu` slot. | `SplitButton` |
-| `CopyButton` | Copies `value` to the clipboard and flips its tooltip to "Copied". | `CopyButton` |
-| `HighlightText` | Marks case-insensitive matches of a query inside a string (`splitMatch`). | `HighlightText` |
-| `LoadMoreButton` | Responsive "Load more" button with a refresh icon. | `LoadMoreButton` |
-| `ScrollToTop` | Floating button shown past `threshold` px that scrolls back up. | `ScrollToTop` |
-| `ActionCard` | Card with title, description and an active indicator. | `ActionCard` |
-| `Chip` | Compact pill; clickable with `@click`, dismissible with `@dismiss`. | `Chip` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/buttons-actions-button.webp" width="120" alt="Button"> | [`Button`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/buttons-actions-iconbutton.webp" width="120" alt="IconButton"> | [`IconButton`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/buttons-and-actions.md#iconbutton) | Icon-only button with an optional tooltip. | `IconButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/buttons-actions-buttongroup.webp" width="120" alt="ButtonGroup"> | [`ButtonGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/buttons-and-actions.md#buttongroup) | Joins adjacent buttons into one control. | `ButtonGroup` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/buttons-actions-splitbutton.webp" width="120" alt="SplitButton"> | [`SplitButton`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/buttons-actions-responsivebutton.webp" width="120" alt="ResponsiveButton"> | [`ResponsiveButton`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/buttons-and-actions.md#responsivebutton) | Shows its label on desktop and collapses to icon-only on mobile. | `ResponsiveButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/buttons-actions-linkbutton.webp" width="120" alt="LinkButton"> | [`LinkButton`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/buttons-and-actions.md#linkbutton), `IconLinkButton`, `ResponsiveLinkButton` | The button styles rendered as `vue-router` links. | `LinkButton`, `IconLinkButton`, `ResponsiveLinkButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/buttons-actions-copybutton.webp" width="120" alt="CopyButton"> | [`CopyButton`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/buttons-and-actions.md#copybutton) | Copies a value to the clipboard and briefly shows a check mark. | `CopyButton`, `CopyValue` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/buttons-actions-highlighttext.webp" width="120" alt="HighlightText"> | [`HighlightText`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/buttons-actions-loadmorebutton.webp" width="120" alt="LoadMoreButton"> | [`LoadMoreButton`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/buttons-actions-scrolltotop.webp" width="120" alt="ScrollToTop"> | [`ScrollToTop`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/buttons-actions-actioncard.webp" width="120" alt="ActionCard"> | [`ActionCard`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/buttons-actions-themetoggle.webp" width="120" alt="ThemeToggle"> | [`ThemeToggle`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/buttons-actions-languageswitcher.webp" width="120" alt="LanguageSwitcher"> | [`LanguageSwitcher`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/buttons-and-actions.md#languageswitcher) | Globe button with a menu of the `I18nProvider` languages. | `LanguageSwitcher` |
 
 ### Form fields
 
-Every field takes `label`, `helperText`, `error`, `required`, `disabled` and
-`v-model`.
-
-| Component | What it does | @nxgt/material |
-| --- | --- | --- |
-| `TextField` · `TextFormField` | Labelled text input. | `TextField` · `TextFormField` |
-| `EmailField` · `EmailFormField` | Email input (`autocomplete="email"`). | `EmailField` · `EmailFormField` |
-| `PasswordField` · `PasswordFormField` | Password with show/hide and an optional strength meter (`show-strength`). | `PasswordField` · `PasswordFormField` |
-| `UrlField` · `UrlFormField` | URL input (`autocomplete="url"`). | `UrlField` · `UrlFormField` |
-| `PhoneField` · `PhoneFormField` | Phone input with a country menu, parsed with libphonenumber-js. | `PhoneField` · `PhoneFormField` |
-| `NumberField` · `NumberFormField` | Number input with `min`/`max`/`step` and stepper buttons. | `NumberField` · `NumberFormField` |
-| `CurrencyField` · `CurrencyFormField` | Amount formatted for the current language; `currency` defaults to EUR. | `CurrencyField` · `CurrencyFormField` |
-| `PercentField` · `PercentFormField` | Number field bounded to 0–100. | `PercentField` · `PercentFormField` |
-| `TextareaField` · `TextareaFormField` | Textarea with `min-rows`/`max-rows` and an optional character count. | `TextareaField` · `TextareaFormField` |
-| `SearchField` · `SearchFormField` | Search input with optional debounce (`debounce-ms`) and loading state. | `SearchField` · `SearchFormField` |
-| `ColorField` · `ColorFormField` | Colour picker plus a hex text input. | `ColorField` · `ColorFormField` |
-| `OtpField` · `OtpFormField` | One-time code boxes (`length`, default 6). | `OtpField` · `OtpFormField` |
-| `InputGroupField` · `InputGroupFormField` | Labelled input with `leading` / `trailing` addon slots. | `InputGroupField` · `InputGroupFormField` |
-| `InlineEdit` | Text that switches to an input and emits `save`. | `InlineEdit` · `InlineEditFormField` |
-| `RatingField` · `RatingFormField` | Star rating (`max`, default 5), clearable. | `RatingField` · `RatingFormField` |
-| `SliderField` · `SliderFormField` | Labelled slider, single value or range, with a readout. | `Slider` · `SliderFormField` |
-| `SwitchField` · `SwitchFormField` | Labelled switch row bound to a boolean. | `Switch` · `SwitchFormField` |
-| `HelperText` | Hint or error line under a field. | `HelperText` |
-| `Field` | Renders any field from a config object (`{ type: 'text' \| 'select' \| 'date' \| … }`). | `Field` |
-| `Contacts`, `ContactItem`, `ContactDialog` · `ContactsFormField` | Typed contact list (phone, email, …) with an add/edit dialog. | `Contacts` · `ContactsFormField` |
-| `PostalAddress`, `PostalAddressDialog` · `PostalAddressFormField` | Shows a postal address and edits it in a dialog. | `PostalAddress` · `PostalAddressFormField` |
-| `OpeningHours`, `OpeningHoursItem`, `OpeningHoursDialog` · `OpeningHoursFormField` | Weekly opening hours with a per-slot dialog. | `OpeningHours` · `OpeningHoursFormField` |
-| `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm` · `AttributesFormField` | Defines custom typed attributes (text, number, select, date, …). | `AttributesField` · `AttributesFormField` |
-| `AttributeValuesForm`, `AttributeValueFormField` · `AttributeValuesFormFieldSet` | Fills in values for a list of attribute definitions. | `AttributeValuesForm` · `AttributeValuesFormFieldSet` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-field.webp" width="120" alt="Field"> | [`Field`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/form-fields.md#field) | Renders the field matching a config `type` (text, select, date, upload, otp…). | `Field`, `FormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-textfield.webp" width="120" alt="TextField"> | [`TextField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-textareafield.webp" width="120" alt="TextareaField"> | [`TextareaField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-emailfield.webp" width="120" alt="EmailField"> | [`EmailField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-passwordfield.webp" width="120" alt="PasswordField"> | [`PasswordField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-numberfield.webp" width="120" alt="NumberField"> | [`NumberField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-percentfield.webp" width="120" alt="PercentField"> | [`PercentField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/form-fields.md#percentfield) · `PercentFormField` | `NumberField` with a `%` suffix. | `PercentField`, `PercentFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-currencyfield.webp" width="120" alt="CurrencyField"> | [`CurrencyField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-phonefield.webp" width="120" alt="PhoneField"> | [`PhoneField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-urlfield.webp" width="120" alt="UrlField"> | [`UrlField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-searchfield.webp" width="120" alt="SearchField"> | [`SearchField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/form-fields.md#searchfield) · `SearchFormField` | Search icon, clear button and spinner, with a debounced `value-change` event. | `SearchField`, `SearchFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-colorfield.webp" width="120" alt="ColorField"> | [`ColorField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-otpfield.webp" width="120" alt="OtpField"> | [`OtpField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/form-fields.md#otpfield) · `OtpFormField`, `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator` | One-time code input of configurable length. | `OtpField`, `OtpFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-inputgroupfield.webp" width="120" alt="InputGroupField"> | [`InputGroupField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-inlineedit.webp" width="120" alt="InlineEdit"> | [`InlineEdit`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/form-fields.md#inlineedit) | Click-to-edit text with save and cancel. | `InlineEdit`, `InlineEditFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-countryfield.webp" width="120" alt="CountryField"> | [`CountryField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-timezonefield.webp" width="120" alt="TimezoneField"> | [`TimezoneField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-ratingfield.webp" width="120" alt="RatingField"> | [`RatingField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-slider.webp" width="120" alt="Slider"> | [`SliderField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/form-fields.md#slider) · `SliderFormField`, `Slider` | Labelled single or range slider with a value readout. | `Slider`, `SliderFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-switch.webp" width="120" alt="Switch"> | [`SwitchField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/form-fields.md#switch) · `SwitchFormField`, `Switch` | Toggle switch, optionally in a labelled, bordered row. | `Switch`, `SwitchFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-attributes.webp" width="120" alt="Attributes"> | [`AttributesField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/form-fields.md#attributes), `AttributesList`, `AttributeDialog`, `AttributeForm` · `AttributesFormField`, `AttributeValuesForm`, `AttributeValueFormField` · `AttributeValuesFormFieldSet` | Editor for typed custom attributes (string, number, date, select, rich text…). `AttributesField` takes `error` and `helperText`; `AttributesFormField` takes `helperText` and follows `resetForm` / `setFieldValue`. | `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm`, `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/form-fields-contacts.webp" width="120" alt="Contacts"> | [`Contacts`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-postaladdress.webp" width="120" alt="PostalAddress"> | [`PostalAddress`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/form-fields-openinghours.webp" width="120" alt="OpeningHours"> | [`OpeningHours`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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 |
-| --- | --- | --- |
-| `Calendar` + parts | Date grid with month and year navigation. | `Calendar` |
-| `DateField` · `DateFormField` | Date picker in a popover, optional time (`show-time-picker`). | `DateField` · `DateFormField` |
-| `DateRangeField` · `DateRangeFormField` | From/to range picker. | `DateRangeField` · `DateRangeFormField` |
-| `TimeField` · `TimeFormField` | Time picker in a popover, bound to a `Date`. | `TimeField` · `TimeFormField` |
-| `TimePicker` | Inline hour and minute inputs; emits `change` with a `Date`. | `TimePicker` |
-| `DurationField` · `DurationFormField` | Hours + minutes, stored as total minutes. | `DurationField` · `DurationFormField` |
-| `TimezoneField` · `TimezoneFormField` | Searchable IANA timezone picker. | `TimezoneField` · `TimezoneFormField` |
-| `RelativeTime` | "3 minutes ago" for a date, in the current language. | `RelativeTime` |
-| `EventChip` | Coloured event pill with time, all-day and continuation markers. | `EventChip` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/date-time-calendar.webp" width="120" alt="Calendar"> | [`Calendar`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/date-and-time.md#calendar) + parts | Day-picker calendar built on Reka UI, with optional month and year selects and `min-value` / `max-value` bounds. | `Calendar`, `CalendarDayButton` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/date-time-datefield.webp" width="120" alt="DateField"> | [`DateField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/date-time-daterangefield.webp" width="120" alt="DateRangeField"> | [`DateRangeField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/date-time-timefield.webp" width="120" alt="TimeField"> | [`TimeField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/date-time-timepicker.webp" width="120" alt="TimePicker"> | [`TimePicker`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/date-time-durationfield.webp" width="120" alt="DurationField"> | [`DurationField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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 |
-| --- | --- | --- |
-| `SelectField` · `SelectFormField` | Labelled select from `options`. | `SelectField` · `SelectFormField` |
-| `ComboboxField` · `ComboboxFormField` | Searchable single select. | `ComboboxField` · `ComboboxFormField` |
-| `Autocomplete` · `AutocompleteFormField` | Type-ahead single or multiple select; `free-solo` accepts new values. | `Autocomplete` · `AutocompleteFormField` |
-| `CountryField` · `CountryFormField` | Country picker with flags, single or multiple. | `CountryField` · `CountryFormField` |
-| `CheckboxGroup` · `CheckboxGroupFormField` | Checkbox list bound to `string[]`. | `CheckboxGroup` · `CheckboxGroupFormField` |
-| `RadioGroupField` · `RadioGroupFormField` | Labelled radio list from `options`. | `RadioGroup` · `RadioGroupFormField` |
-| `SelectCardField` · `SelectCardFormField` | Options as selectable cards (title, description), single or multiple. | `SelectCardField` · `SelectCardFormField` |
-| `CheckCardField` · `CheckCardFormField` | A boolean shown as two cards (yes / no). | `CheckCardField` · `CheckCardFormField` |
-| `SelectChipField` · `SelectChipFormField` | Options as chips, single or multiple. | `SelectChipField` · `SelectChipFormField` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-select.webp" width="120" alt="Select"> | [`Select`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#select), `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem` + parts, `NativeSelect`, `NativeSelectOption`, `NativeSelectOptGroup` | Select primitives with groups, labels and scroll buttons, plus a styled native `<select>`. | `Select` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-selectfield.webp" width="120" alt="SelectField"> | [`SelectField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#selectfield) · `SelectFormField` | Labelled select built from `options`. | `SelectField`, `SelectFormField` |
+| — | [Combobox](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#combobox) | The raw combobox primitives are not in `@nxgt/material-vue`. Use [`ComboboxField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#comboboxfield) for a searchable single select, [`Autocomplete`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#autocomplete) for several values or free text, or the `Command` parts (Overlays & menus) for a hand-built list. | `Combobox` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-comboboxfield.webp" width="120" alt="ComboboxField"> | [`ComboboxField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#comboboxfield) · `ComboboxFormField` | Labelled, searchable single select over `{ value, label }` options, in a popover. | `ComboboxField`, `ComboboxFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-autocomplete.webp" width="120" alt="Autocomplete"> | [`Autocomplete`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#autocomplete) · `AutocompleteFormField` | Single or multiple (chips) autocomplete with free-solo values and a query event. | `Autocomplete`, `AutocompleteFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-checkbox.webp" width="120" alt="Checkbox"> | [`Checkbox`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#checkbox) | Reka UI checkbox with an indeterminate state; pair it with a `Label`. | `Checkbox`, `CheckboxFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-checkboxgroup.webp" width="120" alt="CheckboxGroup"> | [`CheckboxGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/selection-choice-radiogroup.webp" width="120" alt="RadioGroup"> | [`RadioGroupField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#radiogroup) · `RadioGroupFormField`, `RadioGroup`, `RadioGroupItem` | Labelled radio group built from `options`, horizontal or vertical. | `RadioGroup`, `RadioGroupItem`, `RadioGroupFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-checkcardfield.webp" width="120" alt="CheckCardField"> | [`CheckCardField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/selection-choice-selectcardfield.webp" width="120" alt="SelectCardField"> | [`SelectCardField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#selectcardfield) · `SelectCardFormField` | Single or multiple choice shown as selectable cards. | `SelectCardField`, `SelectCardFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-selectchipfield.webp" width="120" alt="SelectChipField"> | [`SelectChipField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/selection-choice-transferlist.webp" width="120" alt="TransferList"> | [`TransferList`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/selection-choice-sortablelist.webp" width="120" alt="SortableList"> | [`SortableList`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#sortablelist), `SortableHandle` · `SortableListFormField` | Searchable list of strings you reorder by dragging or with the keyboard. | `SortableList`, `SortableListFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/selection-choice-switcher.webp" width="120" alt="Switcher"> | [`Switcher`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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 |
-| --- | --- | --- |
-| `AccordionCard` | Accordion built from an `items` array (`title`, `content`). | `AccordionCard` |
-| `AvatarGroup` | Overlapping avatars; extras past `max` collapse into "+N". | `AvatarGroup` |
-| `Description` | Label and value pair, hidden when the value is empty. | `Description` |
-| `SummaryData` | Label/value rows, stacked or `inline`. | `SummaryData` |
-| `EntityHeader` | Title with a row of metadata. | `EntityHeader` |
-| `StatCard` | KPI tile: label, value, hint and a coloured delta. | `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` |
-| `ExtendedLabel` | Section heading with an accent bar and a `trailing` slot. | `ExtendedLabel` |
-| `Timeline`, `TimelineItem` | Vertical event list with tones and timestamps. | `Timeline`, `TimelineItem` |
-| `QRCode` | QR code for `value` (`size`, colours, error `level`). | `QRCode` |
-| `Barecode` | Barcode drawn on a canvas with JsBarcode (`CODE128` by default). | `Barecode` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-avatar.webp" width="120" alt="Avatar"> | [`Avatar`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#avatar), `AvatarImage`, `AvatarFallback` | Round image with a fallback that shows while it loads or when it fails. | `Avatar`, `AvatarImage`, `AvatarFallback` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-avatargroup.webp" width="120" alt="AvatarGroup"> | [`AvatarGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#avatargroup) | Overlapping avatars with a `+N` overflow. | `AvatarGroup` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-badge.webp" width="120" alt="Badge"> | [`Badge`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-countbadge.webp" width="120" alt="CountBadge"> | [`CountBadge`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#countbadge) | Count in the corner of its content, capped at `99+` and hidden at 0. | `CountBadge` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-chip.webp" width="120" alt="Chip"> | [`Chip`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-statcard.webp" width="120" alt="StatCard"> | [`StatCard`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-metric-cards.webp" width="120" alt="Metric cards"> | [`TrendCard`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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. | same names |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-card-presets.webp" width="120" alt="Card presets"> | [`FeatureCard`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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. | same names |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-statusindicator.webp" width="120" alt="StatusIndicator"> | [`StatusIndicator`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-summarydata.webp" width="120" alt="SummaryData"> | [`SummaryData`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-description.webp" width="120" alt="Description"> | [`Description`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-entityheader.webp" width="120" alt="EntityHeader"> | [`EntityHeader`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-listtile.webp" width="120" alt="ListTile"> | [`ListTile`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#listtile) | Row with leading / trailing slots, title and subtitle; a link with `href`, otherwise a button. `size="sm"` is the dense row. | `ListTile` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-accordioncard.webp" width="120" alt="AccordionCard"> | [`AccordionCard`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#accordioncard) | Renders `items` (title, content) as a styled accordion. | `AccordionCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-timeline.webp" width="120" alt="Timeline"> | [`Timeline`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#timeline), `TimelineItem`, `RelativeTime` | Vertical event timeline with toned markers and relative times. | `Timeline`, `TimelineItem`, `RelativeTime` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-eventchip.webp" width="120" alt="EventChip"> | [`EventChip`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-codeblock.webp" width="120" alt="CodeBlock"> | [`CodeBlock`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-markdown.webp" width="120" alt="Markdown"> | [`Markdown`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#markdown) | Markdown with KaTeX math and mermaid diagrams (client-only). Fences reuse `CodeBlock`. `ChatMarkdown` renders through it. | `Markdown` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-terminal.webp" width="120" alt="Terminal"> | [`Terminal`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-figure.webp" width="120" alt="Figure"> | [`Figure`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#figure) | Framed media with an optional caption. | `Figure` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-display-apioperation.webp" width="120" alt="ApiEndpoint"> | [`ApiEndpoint`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-paramtable.webp" width="120" alt="ParamTable"> | [`ParamTable`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-qrcode.webp" width="120" alt="QRCode"> | [`QRCode`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-display-barecode.webp" width="120" alt="Barecode"> | [`Barecode`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-display.md#barecode) | 1D barcode. | `Barecode` |
 
 ### Data table, filter & lists
 
-| Component | What it does | @nxgt/material |
-| --- | --- | --- |
-| `DataTable` | TanStack table with sorting, filtering, row selection, expandable rows, pagination and load-more. | `DataTable` |
-| `DataTableColumnHeader`, `DataTablePagination`, `DataTableViewOptions` | Sortable header, pager with page size, column visibility menu. | `DataTableColumnHeader`, `DataTablePagination`, `DataTableViewOptions` |
-| `Filter` · `FilterFormField` | Filter panel built from a schema (15 field types), shown inline or in a dialog, sheet, drawer or popover. It supports presets, URL sync and storage. | `Filter` · `FilterFormField` |
-| `FilterProvider`, `FilterTrigger`, `FilterChips`, `FilterContent`, `FilterGroups`, `FilterGroup`, `FilterField`, `FilterActions`, `FilterPresets` | Filter parts for composing your own layout. | `FilterProvider`, `FilterChips`, `FilterContent`, `FilterGroups`, `FilterGroup`, `FilterField`, `FilterActions`, `FilterPresets` |
-| `FilterInline`, `FilterDialog`, `FilterSheet`, `FilterDrawer`, `FilterPopover` | Each filter container on its own. | `FilterInline`, `FilterDialog`, `FilterSheet`, `FilterDrawer`, `FilterPopover` |
-| `TransferList` · `TransferListFormField` | Available/selected panes with search, move buttons and drag-and-drop. | `TransferList` · `TransferListFormField` |
-| `SortableList`, `SortableHandle` · `SortableListFormField` | Searchable list you reorder by dragging; `v-model` is the ordered values. | `SortableList`, `SortableHandle` · `SortableListFormField` |
-| `Tree`, `TreeItem` | Expandable tree with none, single or multiple selection. | `Tree`, `TreeItem` |
-| `ListTile` | Row with title, subtitle and leading/trailing slots; a link or a button. `size="sm"` is the dense row. | `ListTile` |
-| `DndProvider`, `Draggable`, `Droppable`, `DraggableDroppable`, `SortableProvider`, `Sortable`, `DragHandle`, `DndOverlay` | Drag-and-drop primitives with a dnd-kit-style API, also on `/dnd`. | `DndProvider`, `Draggable`, `Droppable`, `DraggableDroppable`, `SortableProvider`, `Sortable`, `DragHandle`, `DndOverlay` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-table-filter-lists-datatable.webp" width="120" alt="DataTable"> | [`DataTable`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/data-table-filter-lists-filter.webp" width="120" alt="Filter"> | [`Filter`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-table-filter-and-lists.md#filter) · `FilterFormField`, `FilterProvider`, `FilterTrigger`, `FilterChips`, `FilterContent`, `FilterGroups`, `FilterGroup`, `FilterField`, `FilterActions`, `FilterPresets` | 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-vue@0/docs/components/data-table-filter-and-lists.md#filterinline-filterpopover-filterdialog-filtersheet-filterdrawer), `FilterDialog`, `FilterSheet`, `FilterDrawer`, `FilterPopover` | 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-vue@0/docs/previews/data-table-filter-lists-pagination.webp" width="120" alt="Pagination"> | [`Pagination`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-table-filter-and-lists.md#pagination), `PaginationContent`, `PaginationItem`, `PaginationFirst`, `PaginationLast` + parts | Pagination primitives on Reka UI's `Pagination`, with first / last buttons and ellipses. | `Pagination` (parts), `PaginationBar` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-table-filter-lists-tree.webp" width="120" alt="Tree"> | [`Tree`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-table-filter-and-lists.md#tree), `TreeItem` | Expandable tree with none, single or multiple selection and keyboard navigation. | `Tree`, `TreeItem`, `useTree` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/data-table-filter-lists-drag-and-drop.webp" width="120" alt="Drag and drop"> | [`DndProvider`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/data-table-filter-and-lists.md#drag-and-drop), `Draggable`, `Droppable`, `DraggableDroppable`, `SortableProvider`, `Sortable`, `DragHandle`, `DndOverlay` | Drag-and-drop primitives; see [dnd](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/helpers.md#nxgtmaterial-vuednd). | `DndProvider`, `Draggable`, `Droppable`, `Sortable`, `DragHandle` |
 
 ### Navigation & layout
 
-| Component | What it does | @nxgt/material |
-| --- | --- | --- |
-| `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` | App shell: sidebar from `items`, header with a mobile menu sheet, route breadcrumb and page frame. | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
-| `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarMenuItem`, `SidebarMenuLabel` | Collapsible navigation column (`v-model:expanded`). | `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarMenuItem`, `SidebarMenuLabel` |
-| `NavigationRail` | Narrow vertical rail for icon buttons. | `NavigationRail` |
-| `TopAppBar`, `BottomAppBar` | Horizontal app bars; the bottom bar styles icon buttons with an active state. | `TopAppBar`, `BottomAppBar` |
-| `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage` + parts | Breadcrumb trail. | `Breadcrumb` |
-| `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationFirst`, `PaginationLast` + parts | Page navigation links. | `Pagination`, `PaginationBar` |
-| `Tabs` | See Primitives. | `Tabs` |
-| `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` | Horizontal or vertical steps with per-step status. | `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` |
-| `Figure` | Framed media with an optional caption. | `Figure` |
-| `Doc`, `DocPage`, `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress` | Documentation site shell: sidebar from `md`, TOC 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` |
-| `ListDetailsLayout` (`.List`, `.Details`, `.Trigger`) | List and details panes with a switchable active view. | `ListDetailsLayout` |
-| `PaneLayout` (`.Pane`, `.Content`, `.Trigger`) | Content with a toggleable side pane that becomes a sheet on mobile. | `PaneLayout` |
-| `ThreadLayout` | Centred page frame with `header` and `stepper` slots. | `ThreadLayout` |
-| `ResponsiveGrid` | Container-query grid, from 1 to 5 columns. | `ResponsiveGrid` |
-| `Background` | Full-viewport gradient backdrop. | `Background` |
-| `Activity` | Keeps its content mounted and toggles it with `visible`. | `Activity` |
-| `Switcher` | Dropdown to switch the current item (workspace, account, …). | `Switcher` |
-| `ThemeToggle` | Light / dark / system toggle backed by `useTheme`. | `ThemeToggle` |
-| `LanguageSwitcher` | Language menu wired to `I18nProvider`; disabled without it. | `LanguageSwitcher` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/navigation-layout-appshell.webp" width="120" alt="ActivityLayout"> | [`ActivityLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/navigation-and-layout.md#activitylayout), `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` | 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-vue@0/docs/guides/app-shell.md). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/navigation-layout-sidebar.webp" width="120" alt="Sidebar"> | [`Sidebar`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-topappbar.webp" width="120" alt="TopAppBar"> | [`TopAppBar`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-breadcrumb.webp" width="120" alt="Breadcrumb"> | [`Breadcrumb`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/navigation-and-layout.md#breadcrumb), `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage` + parts | Breadcrumb primitives. | `Breadcrumb` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/navigation-layout-listdetailslayout.webp" width="120" alt="ListDetailsLayout"> | [`ListDetailsLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/navigation-and-layout.md#listdetailslayout) (`.List`, `.Details`, `.Trigger`), `PaneLayout` (`.Pane`, `.Content`, `.Trigger`), `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-vue@0/docs/previews/navigation-layout-responsivegrid.webp" width="120" alt="ResponsiveGrid"> | [`ResponsiveGrid`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-resizable.webp" width="120" alt="ResizableGroup"> | [`ResizablePanelGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/navigation-and-layout.md#resizablegroup), `ResizablePanel`, `ResizableHandle` | Resizable panels with an optional grip handle. | `ResizableGroup`, `ResizablePanel`, `ResizableSeparator` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/navigation-layout-skiplink.webp" width="120" alt="SkipLink"> | [`SkipLink`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-pager.webp" width="120" alt="Pager"> | [`Pager`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-seealso.webp" width="120" alt="SeeAlso"> | [`SeeAlso`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-toc.webp" width="120" alt="Toc"> | [`Toc`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-stepper.webp" width="120" alt="Stepper"> | [`Stepper`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/navigation-and-layout.md#stepper) | Clickable horizontal or vertical steps with status and progress; compact on mobile. | `Stepper` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/navigation-layout-steps.webp" width="120" alt="Steps"> | [`Steps`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-hero.webp" width="120" alt="Hero"> | [`Hero`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/navigation-layout-doc.webp" width="120" alt="Doc"> | [`Doc`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/navigation-and-layout.md#doc), `DocPage`, `DocTopbar`, `DocSidebar`, `DocToc`, `DocPager`, `DocSearch`, `DocChildCards`, `DocSeeAlso`, `DocEmpty`, `DocProgress`, `DocHeader`, `DocCopyMarkdown` | Documentation site shell: sidebar from `md`, TOC rail from `xl`. Reading bar, copy-as-markdown, child cards, see also, and a 404 slot. Storybook `Navigation & layout/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-vue@0/docs/previews/navigation-layout-background.webp" width="120" alt="Background"> | [`Background`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/navigation-and-layout.md#background) | Full-viewport gradient with blurred colour blobs; centres its content. | `Background` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/navigation-layout-navigationrail.webp" width="120" alt="NavigationRail"> | [`NavigationRail`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/navigation-and-layout.md#navigationrail) | Narrow vertical rail for icon buttons. | `NavigationRail` (placeholder) |
 
 ### Overlays & menus
 
-| Component | What it does | @nxgt/material |
-| --- | --- | --- |
-| `Dialog`, `DialogTrigger`, `DialogContent`, `DialogScrollContent` + parts | Modal dialog. | `Dialog` |
-| `CustomDialog` | Dialog with `title` and `description` props. | `CustomDialog` |
-| `AlertDialog`, `AlertDialogContent`, `AlertDialogAction`, `AlertDialogCancel` + parts | Blocking modal that needs an explicit answer. | `AlertDialog` |
-| `CustomAlertDialog` | Alert dialog with `title` and `description` props. | `CustomAlertDialog` |
-| `ConfirmDialog` | Confirm/cancel modal with a `destructive` variant and `loading`. | `ConfirmDialog` |
-| `ConfirmationDialog` | Confirm/cancel modal toned by `variant` and `color` (warning by default). | `ConfirmationDialog` |
-| `Sheet`, `SheetTrigger`, `SheetContent` + parts | Panel sliding in from a screen edge. | `Sheet` |
-| `Drawer`, `DrawerTrigger`, `DrawerContent` + parts | Drawer panel. | `Drawer` |
-| `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverAnchor` | Anchored floating panel. | `Popover` |
-| `HoverCard`, `HoverCardTrigger`, `HoverCardContent` | Card shown on hover. | `HoverCard` |
-| `Tooltip`, `TooltipProvider`, `TooltipTrigger`, `TooltipContent` | Hint on hover or focus. | `Tooltip` |
-| `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem` + parts | Menu opened from a trigger, with checkbox, radio and sub-menus. | `DropdownMenu` |
-| `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem` + parts | Right-click menu. | `ContextMenu` |
-| `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem` + parts | Desktop-style menu bar. | `Menubar` |
-| `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandItem` + parts | Command palette with search, groups and shortcuts. | `Command`, `CommandDialog` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/overlays-menus-dialog.webp" width="120" alt="Dialog"> | [`Dialog`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/overlays-and-menus.md#dialog), `DialogTrigger`, `DialogContent`, `DialogScrollContent` + parts | Modal dialog parts with a close button. | `Dialog` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/overlays-menus-sheet.webp" width="120" alt="Sheet"> | [`Sheet`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/overlays-and-menus.md#sheet), `SheetTrigger`, `SheetContent` + parts | Panel that slides in from any edge. | `Sheet` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/overlays-menus-drawer.webp" width="120" alt="Drawer"> | [`Drawer`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/overlays-and-menus.md#drawer), `DrawerTrigger`, `DrawerContent` + parts | Swipeable bottom or side drawer (Reka UI's drawer). | `Drawer` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/overlays-menus-popover.webp" width="120" alt="Popover"> | [`Popover`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/overlays-menus-hovercard.webp" width="120" alt="HoverCard"> | [`HoverCard`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/overlays-menus-tooltip.webp" width="120" alt="Tooltip"> | [`Tooltip`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/overlays-and-menus.md#tooltip), `TooltipProvider`, `TooltipTrigger`, `TooltipContent` | Tooltip on a trigger. `Tooltip` is the root: compose it with `TooltipTrigger` and `TooltipContent`, inside a `TooltipProvider`. | `Tooltip` (same parts, plus the `content` shorthand) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/overlays-menus-dropdownmenu.webp" width="120" alt="DropdownMenu"> | [`DropdownMenu`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/overlays-and-menus.md#dropdownmenu), `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem` + parts | Menu with checkbox and radio items, submenus, shortcuts and a destructive item. Items take `variant="error"` (red); `"destructive"` is a deprecated alias. | `DropdownMenu` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/overlays-menus-contextmenu.webp" width="120" alt="ContextMenu"> | [`ContextMenu`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/overlays-and-menus.md#contextmenu), `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem` + parts | Right-click menu with the same kinds of items. Items take `variant="error"`, like `DropdownMenuItem`. | `ContextMenu` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/overlays-menus-menubar.webp" width="120" alt="Menubar"> | [`Menubar`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/overlays-and-menus.md#menubar), `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem` + parts | Desktop-style menubar. Items take `variant="error"`, like `DropdownMenuItem`. | `Menubar` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/overlays-menus-command.webp" width="120" alt="Command"> | [`Command`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/overlays-and-menus.md#command), `CommandDialog`, `CommandInput`, `CommandList`, `CommandItem` + parts | 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 |
-| --- | --- | --- |
-| `Alert` | Inline message with a title, description and tone. | `Alert` |
-| `Banner` | Full-width notice (`info`, `success`, `warning`, `error`), optionally dismissible. | `Banner` |
-| `Toaster`, `Toast`, `toast`, `toasts` | vue-sonner toasts; `toasts.success` / `error` / `info` / `warning` / `loading` / `dismiss`. | `Toaster`, `Toast`, `toast`, `toasts` |
-| `Progress`, `ProgressField`, `CircularProgress` | Linear bar, labelled bar, and ring with a label. | `Progress`, `ProgressField`, `CircularProgress` |
-| `ScrollProgress` | Hairline that tracks window or a scrollable `target` (`@vueuse/core` `useWindowScroll` / `useScroll`). `DocProgress` composes it. | `ScrollProgress` |
-| `Spinner` | Loading spinner in several styles and colours. | `Spinner` |
-| `Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonTable` | Loading placeholders. | `Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonTable` |
-| `EmptyState` | Icon in a tinted well, title, description and action; not-found, unauthorized, generic, empty, offline, search and maintenance presets. | `EmptyState` |
-| `StatusIndicator` | Status dot with a tone, optionally pulsing. | `StatusIndicator` |
-| `Badge` | Pill label in the semantic tones. | `Badge` |
-| `CountBadge` | Numeric badge capped at `max` ("99+"). | `CountBadge` |
-| `Notifications` | Notification bell (popover or panel) with filters, categories, read and dismiss. | `Notifications` |
-| `HydrateLoading` | Full-screen spinner over the gradient backdrop while the app boots. | `HydrateLoading` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-alert.webp" width="120" alt="Alert"> | [`Alert`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/feedback-status-banner.webp" width="120" alt="Banner"> | [`Banner`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/feedback-status-alertdialog.webp" width="120" alt="AlertDialog"> | [`AlertDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#alertdialog), `AlertDialogContent`, `AlertDialogAction`, `AlertDialogCancel` + parts | Parts for a blocking confirmation dialog. | `AlertDialog` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-confirmdialog.webp" width="120" alt="ConfirmDialog"> | [`ConfirmDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#confirmdialog), `ConfirmationDialog`, `CustomAlertDialog` | Controlled confirm / cancel dialog. `ConfirmationDialog` brings its own trigger and icon; `CustomAlertDialog` is the free-form alert-dialog variant. | `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-customdialog.webp" width="120" alt="CustomDialog"> | [`CustomDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#customdialog) | Ready-made dialog with trigger, icon, title, body and footer. The `#trigger` slot is the trigger itself (as-child): put a `Button` in it, not inside another button. | `CustomDialog` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-emptystate.webp" width="120" alt="EmptyState"> | [`EmptyState`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/feedback-status-progress.webp" width="120" alt="Progress"> | [`Progress`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#progress), `ProgressField`, `CircularProgress` | Linear bar, circular ring with a label, and a labelled progress field. | `Progress`, `CircularProgress`, `ProgressField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-scrollprogress.webp" width="120" alt="ScrollProgress"> | [`ScrollProgress`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#scrollprogress) | Hairline that tracks the window or a scrollable `target` (VueUse `useWindowScroll` / `useScroll`). `DocProgress` composes it. | `ScrollProgress` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-spinner.webp" width="120" alt="Spinner"> | [`Spinner`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#spinner) | Loading spinner in several styles and colours. | `Spinner` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-toast.webp" width="120" alt="Toast"> | [`Toaster`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#toast), `Toast`, `toast`, `toasts` | 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-vue@0/docs/previews/feedback-status-skeleton.webp" width="120" alt="Skeleton"> | [`Skeleton`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#skeleton), `SkeletonText`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonTable` | Loading placeholder and ready-made shapes. | `Skeleton` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-hydrateloading.webp" width="120" alt="HydrateLoading"> | [`HydrateLoading`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/feedback-and-status.md#hydrateloading) | Full-area spinner shown while hydrating. | `HydrateLoading` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/feedback-status-notifications.webp" width="120" alt="Notifications"> | [`Notifications`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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 |
-| --- | --- | --- |
-| `UploadField` · `UploadFormField` | File picker bound to `File` or `File[]`. | `UploadField` · `UploadFormField` |
-| `NetworkUploadField` · `NetworkUploadFormField` | Drop zone that uploads through your `onUpload(file, onProgress)`, with progress, retry and replace. | `NetworkUploadField` · `NetworkUploadFormField` |
-| `S3UploadField` · `S3UploadFormField` | Same drop zone, uploading to presigned URLs from `getPresignedUrl`. | `S3UploadField` · `S3UploadFormField` |
-| `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | Single image upload with preview. | `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` |
-| `FileList`, `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | File rows with size and remove; the field variants upload. | `FileList`, `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` |
-| `ImageCropper`, `ImageCropperDialog` | Crop, zoom and rotate an image, then emit the cropped `File`. | `ImageCropper`, `ImageCropperDialog` |
-| `Camera` | Webcam preview, device choice and photo capture (client-only). | — |
-| `Gallery`, `LightboxGallery`, `MiniGallery` | Image/video gallery (grid, masonry, justified, carousel, …) with lightbox and selection. | `Gallery`, `LightboxGallery`, `MiniGallery` |
-| `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` | Embla carousel with previous/next buttons. | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` |
-| `PdfReader`, `PdfToolbar`, `PdfSidebar`, `PdfPageList`, `PdfThumbnailSidebar`, `PdfOutlineSidebar` | PDF viewer with zoom, fit, rotate, search, thumbnails and outline (client-only). `PdfViewer` is a deprecated alias. | `PdfReader`, `PdfToolbar`, `PdfSidebar`, `PdfPageList`, `PdfThumbnailSidebar`, `PdfOutlineSidebar` |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/media-files-s3uploadfield.webp" width="120" alt="S3UploadField"> | [`S3UploadField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#s3uploadfield-networkuploadfield) · `S3UploadFormField`, `NetworkUploadField` · `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-vue@0/docs/previews/media-files-uploadfield.webp" width="120" alt="UploadField"> | [`UploadField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#uploadfield) · `UploadFormField` | Labelled file input holding the chosen `File`. | `UploadField`, `UploadFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/media-files-filelist.webp" width="120" alt="FileList"> | [`FileList`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/components/media-and-files.md#filesformfield) | Not in `@nxgt/material-vue`. For a list of file URLs use [`FileListFormField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#filelist); for typed URLs with suggestions, an `AutocompleteFormField` with `free-solo` (see [Selection & choice](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/selection-and-choice.md#autocomplete)). | `FilesFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/media-files-imagefield.webp" width="120" alt="ImageField"> | [`ImageField`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/media-files-imagecropper.webp" width="120" alt="ImageCropper"> | [`ImageCropper`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/media-files-gallery.webp" width="120" alt="Gallery"> | [`Gallery`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/media-files-carousel.webp" width="120" alt="Carousel"> | [`Carousel`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/media-files-pdfreader.webp" width="120" alt="PdfReader"> | [`PdfReader`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#pdfreader), `PdfToolbar`, `PdfSidebar`, `PdfPageList`, `PdfThumbnailSidebar`, `PdfOutlineSidebar` | Client-only PDF reader with zoom, rotation, search, thumbnails, outline and print. | `PdfReader`, `PdfViewer` (same parts) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/media-files-stxplayer.webp" width="120" alt="StxPlayer"> | [`StxPlayer`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#stxplayer), `StxPlayerProvider`, `StxPlayerViewport`, `StxPlayerControls`, `StxPlayerQueue`, `StxPlayerMini`, `StxPlayerExtras` | 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-vue@0/docs/components/media-and-files.md#videoplayer) (deprecated) | Deprecated alias of `StxPlayer`. | `VideoPlayer` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/media-files-camera.webp" width="120" alt="Camera"> | [`Camera`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#camera) | Webcam preview with device selection and a still capture. | — (a story only, not exported) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/media-files-print.webp" width="120" alt="Print components"> | [`PrintHeader`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#print-components), `PrintSection`, `PrintCard`, `PrintCardField`, `PrintInfoRow`, `PrintBadge`, `PrintTable`, `PrintTableHeader`, `PrintTableRow`, `PrintTableCell`, `PrintTotals`, `PrintTotalRow` | Inline-styled blocks for printable documents (invoice, receipt, report), with a shared `tw`. | `@nxgt/material/print` (same part names, rendered with `@react-pdf/renderer`) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/media-files-map.webp" width="120" alt="Map"> | [`Map`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/media-and-files.md#map), `Marker`, `LocationMarker`, `LocationPreview`, `MapActions`, `LocationField` · `LocationFormField` (from `@nxgt/material-vue/map`) | Leaflet map with markers, controls and a location field. It is not in the component barrel: it lives in `@nxgt/material-vue/map`, with `leaflet` and `@vue-leaflet/vue-leaflet` as **optional peer dependencies** (install them to use it), and its stylesheet is `@nxgt/material-vue/map.css`, which is not part of `styles.css`. The entry imports cleanly under SSR, but leaflet only initialises in a browser: in Nuxt wrap the map in `<ClientOnly>`. The Nuxt module does not auto-register these components — import them where you use them. The [maps guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/maps.md) covers the peers, SSR and the defaults. | `Map`, `LocationField`, `LocationFormField` (`@nxgt/material/map`) |
 
 ### Rich widgets
 
-| Component | What it does | @nxgt/material |
-| --- | --- | --- |
-| `ChatInbox`, `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer`, `ChatMarkdown` | Chat kit: inbox (list + thread, container queries from `@md`), messages, markdown, retry and copy, and a composer. | `ChatInbox`, `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer`, `ChatMarkdown` |
-| `ChatConversationItem`, `ChatMessageSeparator`, `ChatReactionGroup`, `ChatTypingIndicator`, `ChatComposerAttachments` + parts | Conversation list row, date separator, reactions, typing dots and attachments. | `ChatConversationItem`, `ChatMessageSeparator`, `ChatReactionGroup`, `ChatTypingIndicator`, `ChatComposerAttachments` |
-| `Kanban` | Board with columns, swimlane groups, WIP limits, drag-and-drop, search and quick add. | `Kanban` |
-| `EventCalendar` | Month, week, work-week, day and agenda views; drag, resize and create events. | `EventCalendar` |
-| `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `ScatterChart`, `HeatmapChart`, `FunnelChart`, `ChartContainer` | ECharts wrappers themed from the CSS tokens, with loading and empty states. | `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `ScatterChart`, `HeatmapChart`, `FunnelChart`, `ChartContainer` |
-| `EmojiPicker`, `EmojiList` | Shared picker. ChatComposer `emojis`, Markdown `:shortcode:`, RTE toolbar. | `EmojiPicker`, `EmojiList` |
-| `MentionList` | `@` mention list from an `items` prop (local search). ChatComposer and the RTE suggestion list use it. | `MentionList` |
-| `RichTextEditor` · `RichTextEditorFormField` | Tiptap editor: toolbar, tables, images, mentions, callouts, character limit. | `RichTextEditor` · `RichTextEditorFormField` |
-| `CodeEditor` | Monaco editor with a language picker and word wrap (client-only). | `CodeEditor` · `CodeEditorFormField` |
-| `CodeBlock`, `CodeDiff`, `JsonViewer`, `CodeGroup` | Highlighted code, side-by-side diff, collapsible JSON tree, and tabbed samples. | `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` |
-| `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` |
-| `StxPlayer`, `StxPlayerProvider`, `StxPlayerViewport`, `StxPlayerControls`, `StxPlayerQueue`, `StxPlayerMini`, `StxPlayerExtras` | Audio/video player with a queue, captions and a `full` or `mini` layout (client-only). `VideoPlayer` is a deprecated alias. | `StxPlayer`, `StxPlayerProvider`, `StxPlayerViewport`, `StxPlayerControls`, `StxPlayerQueue`, `StxPlayerMini`, `StxPlayerExtras` |
-| `Quiz`, `QuestionCard` | Quiz and question cards composed from Card, ActionCard, GaugeCard, ChecklistCard, ProgressField and TextField. Container queries. | `Quiz`, `QuestionCard` |
-| `PrintHeader`, `PrintSection`, `PrintCard`, `PrintCardField`, `PrintInfoRow`, `PrintBadge` | Inline-styled blocks for printable documents. | `PrintHeader`, `PrintSection`, `PrintCard`, `PrintCardField`, `PrintInfoRow`, `PrintBadge` |
-| `PrintTable`, `PrintTableHeader`, `PrintTableRow`, `PrintTableCell`, `PrintTotals`, `PrintTotalRow` | Printable table with totals. | `PrintTable`, `PrintTableHeader`, `PrintTableRow`, `PrintTableCell`, `PrintTotals`, `PrintTotalRow` |
-
-## Helpers
-
-Non-visual exports, by subpath. Signatures are shortened: `?` marks an
-optional argument.
-
-### `@nxgt/material-vue/lib`
-
-| Export | What it does |
-| --- | --- |
-| `cn(...classes)` | Merges class names (clsx + tailwind-merge). |
-| `clientOnly(component)` | Renders `component` only after mount, in the browser. Pair it with `defineAsyncComponent(() => import(…))`. |
-| `DATE_UTILS.format(iso, fmt?, locale?)` | Formats an ISO string with date-fns (`'PP'` by default); returns `-` when empty. |
-| `DATE_UTILS.parseFromTimestring('HH:mm')`, `DATE_UTILS.parseFromISOString(iso?)` | Parses a time string or an ISO string into a `Date`. |
-| `formatDateRangeFilter({ from, to })` | Converts a date range to ISO start/end of day, or `undefined`. |
-| `formatNumber(value, { language?, ...Intl.NumberFormatOptions })` | `Intl.NumberFormat` with the language per call; returns `''` for NaN. |
-| `STRING_UTILS`, `enumToKebabCase(value?)`, `joinTruthyParts(parts, separator?)`, `splitMatch(text, query)` | `FOO_BAR` → `foo-bar`; joins the non-empty parts; splits a string around case-insensitive matches. |
-| `STYLES_UTILS.colorFromVariable(name, alpha?)`, `STYLES_UTILS.cssSize(value)` | CSS variable to `rgb(from var(--x) …)`; number to `px`. |
-| `safeGetItem(key, default)`, `safeSetItem(key, value)`, `safeRemoveItem(key)`, `LOCALE_STORE_UTILS` | `localStorage` access that never throws, with JSON for non-strings. |
-| `uniqueArray(array)`, `findByKey(array, key, value)`, `findByKeyIn(array, key, values)` | De-duplicates; finds one or many items by a key. |
-| `useFindByKey(items, key)`, `useFindById(items)` | The same lookups bound to one list. |
-| `buildFieldOptions(values, { valueKey, label })` | Maps records to `{ value, label }` options (a path or a function for `label`). |
-| `pick(obj, keys)`, `omit(obj, keys)`, `cleanObject(obj, cleanNulls?)`, `cast<T>(value)`, `castAsync<T>(promise)` | Object helpers; `cleanObject` drops `undefined` (and `null`). |
-| `ifEmptyString(value, fallback)`, `ifEmptyList(value, fallback)` | Returns `fallback` for an empty string or list. |
-| `objectToFormData(obj)`, `formDataToObject(formData)`, `convertToFormData(files, fieldName?)` | `FormData` conversions; files go under `files` by default. |
-| `searchParams(request)`, `searchParam(request, key)` | Reads query parameters from a `Request` (server handlers). |
-| `isExternalHref(href)` | True for `http(s):` and `mailto:` — new tab, not in-app. |
-| `delay(ms)` | Promise that resolves after `ms`. |
-| `renderSlot(slot, context)`, `ContentSlot<T>` | Resolves a prop that is either a VNode or a function of `context`. |
-| `zodLocaleError()`, `parsedType(data)` | Zod v4 error map translated through `material.zod.*`: `z.config({ customError: zodLocaleError() })`. |
-
-Pinia store factories. Every store is local to the component instance that
-creates it. The React library uses Redux Toolkit slices for the same jobs:
-
-| Export | What it does | @nxgt/material |
-| --- | --- | --- |
-| `defineLocalStore(name, { state, actions?, getters? })` | Returns a factory; call it in `setup()`, optionally with initial state, to get this instance's store. | `useSliceReducer` |
-| `localStoreId(name)`, `resolveStoreState(base, overrides?)` | Per-instance store id and the state merge behind `defineLocalStore`. | `resolveSliceState` |
-| `defineStatusStore(name, initial?, actions?)` | `status` / `data` / `error` store with `start`, `success`, `error`, `reset`. | `createStatusSlice` |
-| `defineStatusesStore(name, initial, actions?)` | The same, keyed by path (`start('users')`, `statusOf('users')`). | `createStatusesSlice` |
-| `runStatus(store, fn)` | Runs an async function through a status store (start, then success or error). | `createAsyncSlice` |
-| `defineFilterStore(name, initial, actions?)` | `filter` + `sort` store with `updateFilter` and `resetFilter`. | `createSliceWithFilter` |
-| `defineStepFormStore(name, initialValues?, actions?)` | Multi-step form: `step`, `values`, `isDirty`, `updateStep`, `updateFormValues`, `reset`. | `createStepFormSlice` |
-| `createPinia`, `setActivePinia`, `storeToRefs` | Re-exported from `pinia`. | — |
-
-### `@nxgt/material-vue/composables`
-
-These are the React library's `@nxgt/material/hooks`, with the same names.
-
-| Export | What it does |
-| --- | --- |
-| `useTheme()` | `{ theme, preference, updateTheme }`: light/dark/system stored in `localStorage.theme`, toggles the `dark` class. |
-| `resolveTheme(stored, prefersDark)`, `applyResolvedTheme(theme)` | The pure logic behind `useTheme`, safe on the server. |
-| `useIsClient()` | `Ref<boolean>` that turns `true` after mount; use it for hydration-safe branches. |
-| `useIsMobile()` | `Ref<boolean>`, `true` below 768 px. |
-| `useHeadingSpy(ids, onActive, options?)` | IntersectionObserver over heading ids (`useIntersectionObserver`); reports the topmost visible one. |
-| `useLocalizedDate()` | `{ format, locale, language }`: `DATE_UTILS.format` in the `I18nProvider` language. |
-| `useNumberFormatter()` | `{ formatNumber, formatCurrency }` in the current language. |
-| `useOptions(items, { value, label, filter?, expanded? })`, `buildOptions(items, config)` | Maps records to `{ value, label }` options, as a computed or a plain array. |
-| `extractNode(connection)` | Unwraps a GraphQL `edges[].node` connection into an array. |
-| `useSearchParam(name)` | Computed value of one query parameter (vue-router). |
-| `useNavigationHandler(to, { replace? })`, `useNavigationHandlers(routes)` | Returns click handlers that push or replace a route. |
-| `useAllowedTransitions(current, transitions, configs)` | Lists the workflow actions allowed from the current status. |
-
-### `@nxgt/material-vue/i18n`
-
-| Export | What it does |
-| --- | --- |
-| `I18nProvider`, `provideI18n(options)` | Owns the language. Props: `defaultLanguage`, `initialLanguage` (for SSR), `storageKey`, `supportedLanguages`, `onLanguageChange`. |
-| `useI18nContext()`, `useOptionalI18nContext()` | `{ language, supportedLanguages, changeLanguage }`; the first throws without a provider, the second returns `null`. |
-| `mergeResources(base, app)` | Deep, per-language merge of this package's bundle and yours; your leaf keys win. |
-| `createTranslator(resources)`, `translate`, `getLanguage()` | ICU translator over a bundle (`translate` is bound to the base bundle); missing keys are returned as-is. |
-| `createTypedTranslation(translate)` | Builds your app's `useTranslation()`, which returns `{ t, i18n: { language, changeLanguage } }`. |
-| `useMaterialTranslation()` | Translator for this package's own `material.*` keys, with an English fallback. |
-| `resources`, `LANGUAGE_KEY`, `FALLBACK_LANGUAGE`, `SUPPORTED_LANGUAGES` | Base bundle (`en`, `fr`), the storage key (`language`) and defaults. |
-| `FlatObject`, `Path`, `Language`, `MaterialLocaleKey`, `Translate`, `TranslationContext` | Types for deriving your `LocaleKey` union. |
-
-### `@nxgt/material-vue/models`
-
-| Export | What it does |
-| --- | --- |
-| `Status<T>` | `{ status: 'idle' \| 'loading' \| 'success' \| 'error'; data?; error? }`, the shape the status stores use. |
-
-### `@nxgt/material-vue/types`
-
-| Export | What it does |
-| --- | --- |
-| `PromiseOr<T>` | `T \| Promise<T>`. |
-| `FunctionOr<T, R>`, `AsyncFunctionOr<T, R>` | A value, or a function (or async function) that computes it. |
-| `Predicate<T>`, `AsyncPredicate<T>` | `(arg: T) => boolean`, sync or async. |
+| Preview | Component | What it does | @nxgt/material |
+| --- | --- | --- | --- |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/rich-widgets-chat-overview.webp" width="120" alt="Chat kit"> | [`ChatInbox`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/rich-widgets.md#chat-kit), `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer`, `ChatMarkdown`, `ChatConversationItem`, `ChatMessageSeparator`, `ChatReactionGroup`, `ChatTypingIndicator`, `ChatComposerAttachments` + parts | 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-vue@0/docs/previews/rich-widgets-kanban.webp" width="120" alt="Kanban"> | [`Kanban`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/rich-widgets-eventcalendar.webp" width="120" alt="EventCalendar"> | [`EventCalendar`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/rich-widgets-charts-areachart.webp" width="120" alt="Charts"> | [`BarChart`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/rich-widgets.md#charts), `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `ScatterChart`, `HeatmapChart`, `FunnelChart`, `ChartContainer` | ECharts charts themed from the CSS tokens, with loading and empty states (`ChartContainer`). | same names (Nivo) |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/rich-widgets-emojipicker.webp" width="120" alt="EmojiPicker"> | [`EmojiPicker`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/rich-widgets-mentionlist.webp" width="120" alt="MentionList"> | [`MentionList`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/rich-widgets.md#mentionlist) | `@` mention list from an `items` prop (local search). ChatComposer and the RTE suggestion list use it. `filterMentions(items, query, limit?, { match: 'prefix' \| 'substring' })` filters the same way (default `'substring'`); the editor's `mentions.suggestions` takes `(string \| MentionItem)[]`. | `MentionList` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/rich-widgets-richtexteditor.webp" width="120" alt="RichTextEditor"> | [`RichTextEditor`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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-vue@0/docs/previews/rich-widgets-codeeditor.webp" width="120" alt="CodeEditor"> | [`CodeEditor`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/rich-widgets.md#codeeditor) | Monaco editor field with a label and a language switch. | `CodeEditor`, `CodeEditorFormField` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/previews/rich-widgets-quiz.webp" width="120" alt="Quiz"> | [`Quiz`](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/rich-widgets.md#quiz), `QuestionCard` | Quiz and question cards composed from Card, ActionCard, GaugeCard, ChecklistCard, Progress and TextField. Container queries. | `Quiz`, `QuestionCard` |
 
-### `@nxgt/material-vue/dnd`
-
-The drag-and-drop layer used by kanban, transfer list, sortable list and
-calendar. The components are listed in the [catalogue](#data-table-filter--lists).
-
-| Export | What it does |
-| --- | --- |
-| `arrayMove(array, from, to)`, `insertIds(list, ids, before?)` | Moves one item; inserts `ids` into `list` before an id (or at the end). |
-| `closestCenter`, `pointerWithin`, `rectIntersection` | Collision detection strategies. |
-| `verticalListSortingStrategy`, `horizontalListSortingStrategy` | Sorting strategies for `SortableProvider`. |
-| `useDndItem()`, `useDndActiveId()` | Context of the enclosing draggable item; id of the item being dragged. |
-| `CSS`, `composeRefs(...refs)` | `CSS.Transform.toString(transform)` for inline styles; merges template refs. |
-
-### Component utilities (`@nxgt/material-vue/components`)
+## Traps
 
-Pure helpers exported next to the components that use them.
+The ones that cost the most time. Every error message, with its fix, is in
+[troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/troubleshooting.md).
 
-| Export | What it does |
+| Symptom | Fix |
 | --- | --- |
-| `formatFileSize(bytes)`, `formatCount(count, max?)`, `formatStatDelta(delta)`, `formatRelativeTime(value, options?)` | Display formatting for file sizes, counters (`99+`), KPI deltas and relative times. |
-| `isEmail(value)`, `isUrl(value)`, `normalizeUrl(value)`, `normalizeHex(value)`, `scorePassword(value)` | Validation and normalisation behind the matching fields. |
-| `parseNumberInput(raw)`, `clampNumber(value, min?, max?)`, `stepNumber(value, direction, step?)`, `parseCurrencyInput(raw)` | Locale-tolerant number parsing (`1.234,5` or `1,234.5`) and stepping. |
-| `minutesToParts(total)`, `partsToMinutes(hours, minutes)`, `clampRating(value, max?)` | Duration and rating conversions. |
-| `parsePhoneInput`, `toE164`, `formatInternational`, `formatNational`, `isValidPhoneNumber`, `PHONE_COUNTRIES`, `flagEmoji` | Phone parsing and formatting (libphonenumber-js) and the country list. |
-| `TIMEZONES`, `timezoneLabel(tz, language?)`, `timezoneCity(tz)`, `toCalendarDate(date)`, `fromDateValue(value, base?)` | Timezone list and labels with UTC offset; `Date` ↔ calendar-date conversions. |
-| `copyToClipboard(text)`, `debounce(fn, ms)` | Clipboard write; debounced function. |
-| `findActiveMenuItem(path, items)`, `partitionMenu(items)` | The app shell's longest-match and footer rules. |
-| `dataTableFeatures`, `useColumnHelpers()`, `useDeleteRowsHandler(onDelete?)` | TanStack feature set, column helpers and a confirm-then-delete handler for `DataTable`. |
-| `renderBarcode(canvas, value, options)`, `renderQrModel(options)`, `highlightCode(code, language?)` | Barcode, QR and syntax highlighting without the component. |
-| `cropImageToFile(src, area, options?)`, `IMAGE_CROP_ASPECTS` | Crops an image into a `File`; preset aspect ratios. |
-
-## SSR
-
-An SSR app that bundles this package (`ssr.noExternal: ['@nxgt/material-vue']`)
-evaluates every module the barrels reach at **boot**, whether or not a page
-renders the component.
-
-- **Browser-only widgets are already deferred.** `PdfReader` and its parts,
-  `Camera`, `StxPlayer`, `CodeEditor` and `CodeDiff` load their dependency
-  with `import()` and render through `clientOnly`. Do the same for your own
-  browser-only code, because a `typeof window` guard does nothing when the
-  *import* itself is the side effect:
-
-  ```ts
-  import { defineAsyncComponent } from 'vue';
-  import { clientOnly } from '@nxgt/material-vue/lib';
-
-  export const MapView = clientOnly(defineAsyncComponent(() => import('./map-view.vue')));
-  ```
-
-- **The build checks both halves of this.** `bun run build` imports every built
-  entry in a runtime with no DOM, and fails if any entry statically reaches a
-  dependency that must stay behind `import()`. So a barrel that starts dragging
-  a browser-only module into your server is caught here, not at your boot.
-- **A barrel drags its dependencies into YOUR bundle, even ones nothing
-  renders.** That is a bundler problem as much as a runtime one: the React
-  sibling `@nxgt/material` shipped `@react-pdf/renderer` in its barrel, which
-  pulled in `pdfkit`, whose standard fonts cannot be resolved inside a bundle —
-  three servers answered nothing at all, on every route, with every check green.
-  It is fixed there by a separate `@nxgt/material/print` entry. If you add a
-  dependency of that kind here, it gets its own entry too.
-- **Maps are their own entry, for the same reason.** `@nxgt/material-vue/map` is
-  the only entry that reaches `leaflet`, which reads `window` while it is
-  evaluated. `bun run build` fails if another one does. See [Maps](#maps).
-- **Language on first render.** Pass `initial-language` (from a cookie or
-  `Accept-Language`) to `I18nProvider` so the server and the client agree.
-- **Never `<svg><title>`.** Some SSR frameworks hoist `<title>` into the
-  document head, which causes a hydration mismatch. Use `role="img"` +
-  `aria-label`; `Icon` already does.
-
-## Traps
-
-| Symptom | Cause | Fix |
-| --- | --- | --- |
-| Components render unstyled, no console error | `styles.css` is not in the same file as `@import "tailwindcss"` | import it right after `@import "tailwindcss"` in your entry CSS |
-| `Icon`, menu icons or toast icons are blank | sprite sheet not served | `public/assets/icons/sprites/<style>.svg` |
-| `getActivePinia()` was called but there was no active Pinia | Pinia not installed | `app.use(createPinia())` before mount (the Nuxt module does it) |
-| App shell, `AppBreadcrumb` or `LinkButton` throws on `useRoute` | vue-router not installed | `app.use(router)` |
-| `useI18nContext must be used within an I18nProvider` | your `useTranslation()` runs outside the provider | mount `I18nProvider` above the component |
-| `ReferenceError: DOMMatrix` at server boot | a static `pdfjs-dist` import in your own code | `import()` + `clientOnly` |
-| Built server answers nothing (`curl` → `000`) on every route, log names a module it cannot find | a bundled dependency whose own loader resolves paths at runtime — pdfkit's `#standard-fonts/*` is the known one, through `@react-pdf/renderer` | do not import such a dependency from a barrel; take it from its own entry (`@nxgt/material/print` in the React package) or leave the library external in your server build |
-| Map renders as an empty box under SSR | leaflet initialises in the browser only | wrap it in `<ClientOnly>`; it is not an error ([Maps](#maps)) |
-| `Cannot find package 'leaflet'` | the map peers are optional | `bun add leaflet @vue-leaflet/vue-leaflet` |
-| Map tiles render with no controls or broken layout | leaflet's CSS missing | `import '@nxgt/material-vue/map.css'` — it is not part of `styles.css` |
-| `jsbarcode` has no default export (Vite, no Nuxt) | CommonJS dependency not pre-bundled | `optimizeDeps.include: ['@nxgt/material-vue > jsbarcode']` |
-| Both CSS files loaded, duplicated tokens | `styles.css` and the root `style` export imported together | keep one: `styles.css` with Tailwind, the compiled CSS without |
+| Components render unstyled, no console error | import `styles.css` right after `@import "tailwindcss"`, in the same file ([getting started](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/getting-started.md#styles)) |
+| `<Icon>` is blank | serve `public/assets/icons/sprites/<style>.svg` |
+| `getActivePinia()` was called but there was no active Pinia | `app.use(createPinia())` before mount (the Nuxt module does it) |
+| A map renders as an empty box under SSR, or `Cannot find package 'leaflet'` | wrap it in `<ClientOnly>`; `bun add leaflet @vue-leaflet/vue-leaflet` ([maps](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/maps.md#browser-only)) |
+| `PdfPeerMissingError: … needs the optional peers` when rendering a PDF | `bun add react @react-pdf/renderer@^4.9` |
+| `Cannot find module '#standard-fonts/Helvetica'` on every request of a server with no `node_modules` | `nxgtMaterial: { pdf: { bundleStandardFonts: true } }`, or `pdfkitStandardFonts()` from `/vite` ([PDF guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/pdf.md#fonts-on-a-fully-inlined-server)) |
+| CSS or a test selecting `[data-variant=destructive]` on a menu item stops matching | menu items render `data-variant="error"`, for `variant="error"` and the deprecated `"destructive"` alike: select `[data-variant=error]` |
+
+## Documentation
+
+- [docs/README.md](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/README.md) — every page, and when to read it
+- [Components gallery](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/components/README.md) — one page per category, a preview per component
+- [Forms guide](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/guides/forms.md)
+- [Troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/troubleshooting.md) — every error message, and
+  [how to report a bug](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/docs/troubleshooting.md#reporting-a-bug)
+- [Roadmap](https://cdn.jsdelivr.net/npm/@nxgt/material-vue@0/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 storybook   # http://localhost:6006
-bun run test
+bun run build          # what consumers read
+bun run storybook      # http://localhost:6006
+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