@nxgt/material 1.0.4 → 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,14 +3,47 @@
 React component library: primitives, form fields, layout shell, `DataTable`,
 drag-and-drop, i18n, and `Icon`. Tailwind CSS v4 + Base UI.
 
+## At a glance
+
+- **148 catalogue entries in 12 categories** ([Components](#components)).
+  They cover primitives and overlays as well as data tables, filters, kanban,
+  calendars, charts, chat, rich-text and code editors, PDF and media players.
+- **Form fields ship in pairs.** Each one has a standalone component
+  (`TextField`) and a React Hook Form wrapper (`TextFormField`). Both are in
+  the same barrel.
+- **Helpers** ([Helpers](#helpers)): `cn`, `clientOnly`, date, number,
+  storage and URL utilities, a Zod error map, and Redux Toolkit slice
+  factories in `/lib`. Theme, i18n-aware formatting and option hooks are in
+  `/hooks`.
+- **i18n** ([i18n](#i18n)): an `I18nProvider` with ICU messages and shipped
+  `en` / `fr` strings. Your app merges in its own resources.
+- **SSR-safe barrels** ([SSR](#ssr)): no browser globals at import, and
+  browser-only widgets are wrapped in `clientOnly`.
+- **Vue sister**: `@nxgt/material-vue` uses the same names. The catalogue's
+  last column gives the Vue export for each entry.
+
+## Contents
+
+- [Install](#install)
+- [Setup](#setup)
+- [Subpaths](#subpaths)
+- [Usage](#usage)
+- [Components](#components)
+- [Helpers](#helpers)
+- [SSR](#ssr)
+- [Traps](#traps)
+- [Development](#development)
+- [License](#license)
+
 ## Install
 
 ```bash
 bun add @nxgt/material
 ```
 
-Public on npmjs; no token. **Required peers** — the app must resolve the same
-copy, or hooks throw and tokens come from two builds:
+It is public on npmjs, so no token is needed. **Required peers**: the app must
+resolve the same copy of each, otherwise hooks throw and tokens come from two
+builds.
 
 ```bash
 bun add react react-dom react-hook-form react-redux @reduxjs/toolkit @tanstack/react-table react-use
@@ -19,10 +52,10 @@ bun add react react-dom react-hook-form react-redux @reduxjs/toolkit @tanstack/r
 | Peer | Used by |
 | --- | --- |
 | `react`, `react-dom` `^19` | everything |
-| `react-hook-form` | every `*FormField` |
-| `react-redux`, `@reduxjs/toolkit` | `DataTable`, filter, gallery, kanban, player |
+| `react-hook-form` `^7` | every `*FormField` |
+| `react-redux` `^9`, `@reduxjs/toolkit` `^2` | `DataTable`, filter, gallery, kanban, player, slice helpers |
 | `@tanstack/react-table` `^9` | `DataTable` |
-| `react-use` | assorted hooks |
+| `react-use` `^17` | `useTheme`, `useIsMobile`, other hooks |
 
 The tarball is `dist/`, not `lib/`. There is no `postinstall` build.
 
@@ -39,17 +72,18 @@ In the app's root stylesheet, in this order:
 ```
 
 `styles.css` is the **source** `@theme` layer (colours, `--radius`, `dark`,
-fonts) so it runs through *your* Tailwind build. `@source` is required and
-silent when missing: Tailwind v4 does not scan `node_modules`, so without it
-every utility used *inside* a component is absent and the UI renders unstyled.
+fonts), so it runs through *your* Tailwind build. The `@source` line is
+required, and nothing warns you when it is missing. Tailwind v4 does not scan
+`node_modules`, so without it every utility used *inside* a component is
+missing and the UI renders unstyled.
 
-Import it **explicitly**, nothing injects it: Tailwind v4 builds one `@theme`
-from a single CSS graph, and Tailwind CSS IntelliSense reads the tokens from
-this entry file to autocomplete them in your components.
+Import it **explicitly**, because nothing injects it. Tailwind v4 builds one
+`@theme` from a single CSS graph, and Tailwind CSS IntelliSense reads the
+tokens from this entry file to autocomplete them in your components.
 
 In a Tailwind app, do not also import the compiled `style` condition on
-`@nxgt/material` (`dist/material.css`). Take the tokens; let the app produce
-the utilities. The compiled file is for apps without Tailwind.
+`@nxgt/material` (`dist/material.css`). Take the tokens and let the app
+generate the utilities. The compiled file is for apps without Tailwind.
 
 ### Icons
 
@@ -62,25 +96,26 @@ import { Icon } from '@nxgt/material/components';
 // → /assets/icons/sprites/duotone.svg#atom
 ```
 
-Serve Font Awesome Pro sheets from `public/assets/icons/sprites/<style>.svg`.
-This package does **not** ship them: the FA Pro licence covers use in your
-own products, not redistribution inside a library. `files` includes
-`"!dist/assets"` so a local build cannot leak them into a tarball. A missing
-sheet renders as nothing — no error, no fallback.
+Serve the Font Awesome Pro sprite sheets from
+`public/assets/icons/sprites/<style>.svg`. This package does **not** ship them:
+the FA Pro licence covers use in your own products, not redistribution inside
+a library. `files` includes `"!dist/assets"` so a local build cannot leak them
+into a tarball. A missing sheet renders nothing, with no error and no fallback.
 
 ## Subpaths
 
 | Specifier | What is in it |
 | --- | --- |
-| `@nxgt/material` | default barrel + compiled `style` condition (`dist/material.css`, for apps without Tailwind) |
-| `@nxgt/material/components` | UI components and `*FormField` wrappers |
-| `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useMobile`, `useSearchParam`, … |
-| `@nxgt/material/dnd` | `@dnd-kit` primitives |
-| `@nxgt/material/i18n` | `I18nProvider`, `mergeResources`, `createTranslator` |
-| `@nxgt/material/lib` | `cn`, `clientOnly`, date/number/upload, `useSliceReducer` |
-| `@nxgt/material/models` | status types |
-| `@nxgt/material/types` | shared function types |
-| `@nxgt/material/styles.css` | source Tailwind v4 tokens — **this** is what the app imports |
+| `@nxgt/material` | Everything below in one barrel, plus the compiled `style` condition (`dist/material.css`, for apps without Tailwind) |
+| `@nxgt/material/components` | UI components and `*FormField` wrappers ([Components](#components)) |
+| `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useIsMobile`, `useLocalizedDate`, … ([hooks](#nxgtmaterialhooks)) |
+| `@nxgt/material/dnd` | `@dnd-kit` primitives ([dnd](#nxgtmaterialdnd)) |
+| `@nxgt/material/i18n` | `I18nProvider`, `mergeResources`, `createTranslator` ([i18n](#nxgtmateriali18n)) |
+| `@nxgt/material/lib` | `cn`, `clientOnly`, date, number and storage utilities, `useSliceReducer` ([lib](#nxgtmateriallib)) |
+| `@nxgt/material/models` | `Status<T>` |
+| `@nxgt/material/types` | shared function types (`PromiseOr`, `FunctionOr`, …) |
+| `@nxgt/material/styles.css` | source Tailwind v4 tokens. **This** is the file the app imports |
+
 ## Usage
 
 ### Components
@@ -96,8 +131,9 @@ import { Button, Icon } from '@nxgt/material/components';
 
 ### Form fields
 
-Every field has a standalone (`TextField`) and a React Hook Form wrapper
-(`TextFormField`) in the same barrel. Wrappers take `control` + `name`.
+Each field has a standalone component (`TextField`) and a React Hook Form
+wrapper (`TextFormField`) in the same barrel. The wrappers take `control` and
+`name`.
 
 ```tsx
 import { TextFormField, Button } from '@nxgt/material/components';
@@ -113,9 +149,11 @@ const form = useForm({ defaultValues: { email: '' } });
 
 ### i18n
 
-This package owns the **mechanism**; the app owns resource **content**. The
-reserved namespace is `material` — `mergeResources` is a shallow per-language
-merge, so an app-side `material` key silently shadows every string we ship.
+This package owns the i18n **mechanism**, and the app owns the resource
+**content**. This package's strings live under the `material` namespace.
+`mergeResources` deep-merges your bundle over it per language, so you can
+override one string (`material.command.title`) without losing the rest. Every
+overridden key is reported with `console.warn` outside production.
 
 ```ts
 import {
@@ -140,16 +178,20 @@ export const useTranslation = createTypedTranslation<LocaleKey>(translate);
 </I18nProvider>
 ```
 
-Language state lives only in `I18nProvider`. Components in this package fall
-back to their English copy if the provider is not mounted. Messages are ICU
-MessageFormat; a missing key is returned verbatim.
+Language state lives only in `I18nProvider`. If the provider is not mounted,
+the components in this package fall back to their English copy. Messages use
+ICU MessageFormat, and a missing key is returned as-is.
+
+To translate Zod messages as well, add
+`z.config({ customError: zodLocaleError() })`, with `zodLocaleError` from
+`@nxgt/material/lib`.
 
 ### App shell
 
-`items` is a prop — the shell does not build or filter the menu. `label` is
-already translated (`ReactNode`), not a key. `footer: true` pins an entry;
-do not rely on "last item". `avatar` and `headerActions` are props: the shell
-holds no session.
+`items` is a prop: the shell does not build or filter the menu. Each `label`
+is already translated (a `ReactNode`), not a key. Set `footer: true` to pin an
+entry to the footer; being last in the list does not do it. `avatar` and
+`headerActions` are props too, because the shell holds no session.
 
 ```tsx
 import { ActivityLayout, ActivityContent } from '@nxgt/material/components';
@@ -164,24 +206,355 @@ const items = [
 </ActivityLayout>
 ```
 
-The active entry is the **longest** match across the whole menu, segment-aware
-(`/admin` does not cover `/administrators`). `AppBreadcrumb` reads
-`handle.breadcrumb` off `useMatches()` and needs a data router
+The active entry is the **longest** match across the whole menu. Matching is
+segment-aware, so `/admin` does not cover `/administrators`. `AppBreadcrumb`
+reads `handle.breadcrumb` from `useMatches()`, so it needs a data router
 (`createMemoryRouter` + `RouterProvider`, not `MemoryRouter`).
 
+## Components
+
+Everything below is imported from `@nxgt/material/components`. In the
+*Component* column, `·` separates a field from its React Hook Form wrapper.
+The last column gives the matching export in `@nxgt/material-vue`, or `—` when
+Vue has none. "(same parts)" means Vue exports the same sub-components.
+
+### Primitives
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Collapsible sections with a rotating chevron and animated content. | `Accordion` (same parts) |
+| `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | A single show / hide region and its trigger. | `Collapsible` (same parts) |
+| `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | Card surface with header, action slot, content and footer. | `Card` (same parts) |
+| `Typography` | Text in the Material type scale (headline, title, body, caption…). | `Typography` |
+| `Label` | Form label with an optional required asterisk. | `Label` |
+| `HelperText` | Hint or error message under a field. | `HelperText` |
+| `ExtendedLabel` | Section title with an animated accent underline and a trailing slot. | `ExtendedLabel` |
+| `Input` | Styled native `<input>`. | `Input` |
+| `Textarea` | Styled native `<textarea>`. | `Textarea` |
+| `InputGroup`, `InputGroupAddon`, `InputGroupInput`, `InputGroupButton`, `InputGroupText`, `InputGroupTextarea` | Input with inline or block addons, buttons and text. | `InputGroup` (same parts) |
+| `Icon` | Font Awesome sprite icon by name and style (duotone by default), labelled with `role="img"`. | `Icon` |
+| `Kbd`, `KbdShortcut` | One keyboard key, or a key combination with platform glyphs. | `Kbd`, `KbdShortcut` |
+| `Separator` | Horizontal or vertical divider. | `Separator` |
+| `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption` | Styled semantic table inside a scrollable wrapper. | `Table` (same parts), `TableEmpty` |
+| `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | Tabs whose triggers can take an icon. | `Tabs` (same parts) |
+| `Toggle` | Pressable on / off button: default or outlined, three sizes. | `Toggle` |
+| `ToggleGroup`, `ToggleGroupItem`, `ToggleGroupSeparator` | Single or multiple toggle group sharing variant and size. | `ToggleGroup`, `ToggleGroupItem` |
+| `Activity` | React `<Activity>` switched by a boolean `visible`. | `Activity` |
+
+### Buttons & actions
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `Button` | Filled, tonal, outlined, ghost or link button in seven colours, with a loading state. | `Button` |
+| `IconButton` | Icon-only button with an optional tooltip. | `IconButton` |
+| `ButtonGroup` | Joins adjacent buttons into one control. | `ButtonGroup` |
+| `SplitButton` | Main action plus a dropdown menu of secondary actions. | `SplitButton` |
+| `ResponsiveButton` | Shows its label on desktop and collapses to icon-only on mobile. | `ResponsiveButton` |
+| `LinkButton`, `IconLinkButton`, `ResponsiveLinkButton` | The button styles rendered as `react-router` links. | `LinkButton`, `IconLinkButton`, `ResponsiveLinkButton` |
+| `CopyButton`, `CopyValue` | Copies a value to the clipboard and briefly shows a check mark. `CopyValue` displays the value next to the button. | `CopyButton` |
+| `LoadMoreButton` | "Load more" button for cursor pagination; icon-only with a tooltip unless `expanded`. | `LoadMoreButton` |
+| `ScrollToTop` | Floating button that appears past a scroll threshold. | `ScrollToTop` |
+| `ActionCard` | Clickable card with icon, title, description and active indicator. | `ActionCard` |
+| `ThemeToggle` | Light / dark / system switch that stores and applies the choice. | `ThemeToggle` |
+| `LanguageSwitcher` | Globe button with a menu of the `I18nProvider` languages. | `LanguageSwitcher` |
+
+### Form fields
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `Field` · `FormField` | Renders the field matching a config `type` (text, select, date, upload, otp…). | `Field` |
+| `TextField` · `TextFormField` | Labelled input with leading / trailing adornments and helper text. | `TextField`, `TextFormField` |
+| `TextareaField` · `TextareaFormField` | Labelled textarea with row sizing and a `maxLength` counter. | `TextareaField`, `TextareaFormField` |
+| `EmailField` · `EmailFormField` | Validates on blur; shows a `mailto:` button once the address is valid. | `EmailField`, `EmailFormField` |
+| `PasswordField` · `PasswordFormField` | Show / hide toggle and an optional strength meter (`scorePassword`). | `PasswordField`, `PasswordFormField` |
+| `NumberField` · `NumberFormField` | Emits `number \| null`, with min / max / step clamping, +/− buttons and a suffix. | `NumberField`, `NumberFormField` |
+| `PercentField` · `PercentFormField` | `NumberField` with a `%` suffix. | `PercentField`, `PercentFormField` |
+| `CurrencyField` · `CurrencyFormField` | Amount formatted to the locale on blur, with a currency suffix (EUR by default). | `CurrencyField`, `CurrencyFormField` |
+| `PhoneField` · `PhoneFormField` | International number with a country picker; emits E.164. | `PhoneField`, `PhoneFormField` |
+| `UrlField` · `UrlFormField` | Validates on blur; open-in-new-tab and copy buttons. | `UrlField`, `UrlFormField` |
+| `SearchField` · `SearchFormField` | Search icon, clear button and spinner, with a debounced `onValueChange`. | `SearchField`, `SearchFormField` |
+| `ColorField` · `ColorFormField` | Hex input with a colour picker in a popover. | `ColorField`, `ColorFormField` |
+| `OtpField` · `OtpFormField` | One-time code input of configurable length. | `OtpField`, `OtpFormField`, `InputOTP` |
+| `InputGroupField` · `InputGroupFormField` | Labelled `InputGroup` with addons and helper text. | `InputGroupField`, `InputGroupFormField` |
+| `InlineEdit` · `InlineEditFormField` | Click-to-edit text with save and cancel. | `InlineEdit` |
+| `CountryField` · `CountryFormField` | Single or multiple country picker with flags. | `CountryField`, `CountryFormField` |
+| `TimezoneField` · `TimezoneFormField` | Searchable IANA timezone picker with localised labels. | `TimezoneField`, `TimezoneFormField` |
+| `RatingField` · `RatingFormField` | Star rating with hover preview, click-to-clear and a read-only mode. | `RatingField`, `RatingFormField` |
+| `Slider` · `SliderFormField` | Labelled single or range slider with an editable value and ticks. | `Slider`, `SliderField`, `SliderFormField` |
+| `Switch` · `SwitchFormField` | Toggle switch, optionally in a labelled, bordered row. | `Switch`, `SwitchField`, `SwitchFormField` |
+| `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm` · `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField` | Editor for typed custom attributes (string, number, date, select, rich text…). | `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm`, `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField` |
+| `Contacts`, `ContactItem`, `ContactDialog` · `ContactsFormField` | Typed contact list (phone, email, URL…) with an add / edit dialog. | `Contacts`, `ContactItem`, `ContactDialog`, `ContactsFormField` |
+| `PostalAddress`, `PostalAddressDialog` · `PostalAddressFormField` | Address card with an edit dialog. | `PostalAddress`, `PostalAddressDialog`, `PostalAddressFormField` |
+| `OpeningHours`, `OpeningHoursDialog`, `OpeningHoursItem` · `OpeningHoursFormField` | Weekly opening hours with an add / edit dialog. | `OpeningHours`, `OpeningHoursDialog`, `OpeningHoursItem`, `OpeningHoursFormField` |
+
+### Date & time
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `Calendar`, `CalendarDayButton` | Day-picker calendar with a year view, a today shortcut and `disablePast` / `disableFuture`. | `Calendar` (Reka parts) |
+| `DateField` · `DateFormField` | Labelled trigger that opens a calendar popover, with an optional time picker. | `DateField`, `DateFormField` |
+| `DateRangeField` · `DateRangeFormField` | From / to range picked in a popover calendar. | `DateRangeField`, `DateRangeFormField` |
+| `TimeField` · `TimeFormField` | Opens a `TimePicker` in a popover, or in a dialog on mobile. | `TimeField`, `TimeFormField` |
+| `TimePicker` | Hour and minute inputs with AM / PM and auto-advancing focus. | `TimePicker` |
+| `DurationField` · `DurationFormField` | Hours and minutes combined into a total in minutes. | `DurationField`, `DurationFormField` |
+
+### Selection & choice
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`… | Select primitives with groups, labels and scroll buttons. | `Select` (same parts), `NativeSelect` |
+| `SelectField` · `SelectFormField` | Labelled select built from `options`, with `renderOption`. | `SelectField`, `SelectFormField` |
+| `Combobox`, `ComboboxInput`, `ComboboxContent`, `ComboboxList`, `ComboboxItem`, `ComboboxChips`… | Base UI combobox primitives: input, popup list, groups and chips. | — |
+| `ComboboxField` · `ComboboxFormField` | Labelled, searchable single select over `{ value, label }` options. | `ComboboxField`, `ComboboxFormField` |
+| `Autocomplete`, `AutocompleteChips` · `AutocompleteFormField` | Single or multiple (chips) autocomplete with free-solo values and a query callback. | `Autocomplete`, `AutocompleteFormField` |
+| `Checkbox` · `CheckboxFormField` | Checkbox with label, helper text and an indeterminate state. | `Checkbox` |
+| `CheckboxGroup` · `CheckboxGroupFormField` | Checkbox list built from `options`, valued as `string[]`. | `CheckboxGroup`, `CheckboxGroupFormField` |
+| `RadioGroup`, `RadioGroupItem` · `RadioGroupFormField` | Labelled radio group built from `options`, horizontal or vertical. | `RadioGroupField`, `RadioGroup`, `RadioGroupFormField` |
+| `CheckCardField` · `CheckCardFormField` | A yes / no choice shown as two selectable cards. | `CheckCardField`, `CheckCardFormField` |
+| `SelectCardField` · `SelectCardFormField` | Single or multiple choice shown as `ActionCard`s. | `SelectCardField`, `SelectCardFormField` |
+| `SelectChipField` · `SelectChipFormField` | Single or multiple choice shown as toggleable chips. | `SelectChipField`, `SelectChipFormField` |
+| `TransferList` · `TransferListFormField` | Two-pane picker with search, drag-and-drop, reordering and a `max`. | `TransferList`, `TransferListFormField` |
+| `SortableList` · `SortableListFormField` | Searchable list of strings you reorder by dragging or with the keyboard. | `SortableList`, `SortableListFormField` |
+| `Switcher` | Dropdown for switching the active workspace or account, with an avatar. | `Switcher` |
+
+### Data display
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarBase` | Image with a fallback and an optional online / offline dot. | `Avatar`, `AvatarImage`, `AvatarFallback` |
+| `AvatarGroup` | Overlapping avatars with a `+N` overflow. | `AvatarGroup` |
+| `Badge` | Pill label: default, secondary, error, success, info, warning, outlined. | `Badge` |
+| `CountBadge` | Count in the corner of its children, capped at `99+` and hidden at 0. | `CountBadge` |
+| `Chip` | Pill with leading, avatar and trailing slots, an active state and a dismiss button. | `Chip` |
+| `StatCard` | KPI tile with value, hint, icon, toned delta and a loading skeleton. | `StatCard` |
+| `StatusIndicator` | Coloured status dot with an optional pulse and label. | `StatusIndicator` |
+| `SummaryData` | Label / value pairs as a grid or inline; hides empty values. | `SummaryData` |
+| `Description` | Read-only label / value pair that renders nothing when empty. | `Description` |
+| `EntityHeader` | Page header with icon, title, status, metadata and actions. | `EntityHeader` |
+| `ListTile` | Row with leading / trailing slots, title and subtitle; becomes a link or button when interactive. | `ListTile` |
+| `AccordionCard` | Renders `items` (title, content) as a styled accordion. | `AccordionCard` |
+| `Timeline`, `TimelineItem`, `RelativeTime` | Vertical event timeline with toned icons and relative times. | `Timeline`, `TimelineItem`, `RelativeTime` |
+| `EventChip` | Calendar event pill with time, all-day and continuation edges. | `EventChip` |
+| `CodeBlock`, `CodeDiff`, `JsonViewer` | Highlighted code with line numbers and copy, a Monaco diff, and a collapsible JSON tree. | `CodeBlock`, `CodeDiff`, `JsonViewer` |
+| `QRCode` | QR code on a padded tile, with an optional centred logo. | `QRCode` |
+| `Barecode` | 1D barcode. | `Barecode` |
+
+### Data table, filter & lists
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `DataTable`, `DataTableColumnHeader`, `DataTablePagination`, `DataTableViewOptions` | TanStack Table v9 with sorting, filtering, selection, expandable rows, pagination or load-more, and column visibility. | `DataTable`, `DataTableColumnHeader`, `DataTablePagination`, `DataTableViewOptions` |
+| `Filter`, `FilterProvider`, `FilterContent`, `FilterChips`, `FilterPresets` · `FilterFormField` | Schema-driven filters with chips, presets, validation, and URL or storage persistence. | `Filter`, `FilterProvider`, `FilterContent`, `FilterChips`, `FilterPresets`, `FilterFormField` |
+| `FilterInline`, `FilterPopover`, `FilterDialog`, `FilterSheet`, `FilterDrawer` | The filter panel shown inline, or in a popover, dialog, sheet or drawer. | `FilterInline`, `FilterPopover`, `FilterDialog`, `FilterSheet`, `FilterDrawer` |
+| `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationBar`… | Pagination primitives. `PaginationBar` adds a sibling window with ellipses. | `Pagination` (parts), `PaginationFirst`, `PaginationLast` |
+| `Tree`, `TreeItem`, `useTree` | Expandable tree with none, single or multiple selection and keyboard navigation. | `Tree`, `TreeItem`, `useTree` |
+| `DndProvider`, `Draggable`, `Droppable`, `Sortable`, `DragHandle`… | Drag-and-drop primitives; see [dnd](#nxgtmaterialdnd). | `DndProvider`, `Draggable`, `Droppable`, `Sortable`, `DragHandle` |
+
+### Navigation & layout
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` | App shell: sidebar built from `items`, a header with a mobile sheet, route breadcrumbs and a titled page. See [App shell](#app-shell). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
+| `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarMenuItem`, `SidebarMenuLabel` | Collapsible navigation sidebar with icons, tooltips and active items. | `Sidebar` (same parts) |
+| `TopAppBar`, `BottomAppBar` | Top bar surface, and a bottom bar of icon actions with an active state. | `TopAppBar`, `BottomAppBar` |
+| `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Breadcrumb primitives. | `Breadcrumb` (same parts) |
+| `ListDetailsLayout`, `PaneLayout`, `ThreadLayout` | List / details that collapses to one view on mobile, a side pane that becomes a sheet, and a centred column. | `ListDetailsLayout`, `PaneLayout`, `ThreadLayout` |
+| `ResponsiveGrid` | Container-query grid that grows from 1 to 5 columns. | `ResponsiveGrid` |
+| `ResizableGroup`, `ResizablePanel`, `ResizableSeparator` | Resizable panels with an optional grip handle. | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` |
+| `Stepper`, `StepperIndicator` | Clickable horizontal or vertical steps with status and progress; compact on mobile. | `Stepper` |
+| `Background` | Full-viewport gradient with blurred colour blobs; centres its children. | `Background` |
+| `NavigationRail` | Placeholder: renders an empty rail container and takes no props yet. | `NavigationRail` |
+
+### Overlays & menus
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`… | Modal dialog parts with an icon close button. | `Dialog` (same parts), `DialogScrollContent` |
+| `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetFooter`… | Panel that slides in from any edge. | `Sheet` (same parts) |
+| `Drawer`, `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerTitle`, `DrawerFooter`… | Swipeable bottom or side drawer (Vaul). | `Drawer` (same parts) |
+| `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverAnchor` | Floating panel anchored to a trigger. | `Popover` (same parts) |
+| `HoverCard`, `HoverCardTrigger`, `HoverCardContent` | Card shown on pointer hover. | `HoverCard` (same parts) |
+| `Tooltip`, `TooltipProvider`, `TooltipTrigger`, `TooltipContent` | Tooltip. The `Tooltip` shorthand wraps its children and shows `content`. | `Tooltip` (same parts) |
+| `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuSub`… | Menu with checkbox and radio items, submenus, shortcuts and an error item. | `DropdownMenu` (same parts) |
+| `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`… | Right-click menu with the same kinds of items. | `ContextMenu` (same parts) |
+| `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`… | Desktop-style menubar. | `Menubar` (same parts) |
+| `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandItem`… | Command palette with filtering, groups and shortcuts. `CommandDialog` shows it in a modal. | `Command`, `CommandDialog` (same parts) |
+
+### Feedback & status
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `Alert` | Callout with icon, title and description in seven tones. | `Alert` |
+| `Banner` | Dismissible info / success / warning / error banner with an action. | `Banner` |
+| `AlertDialog`, `AlertDialogContent`, `AlertDialogAction`, `AlertDialogCancel`… | Parts for a blocking confirmation dialog. | `AlertDialog` (same parts) |
+| `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog` | Confirm / cancel dialog with async loading. `ConfirmationDialog` adds a trigger and an optional Zod form. | `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog` |
+| `CustomDialog` | Ready-made dialog with trigger, icon, title, body and footer. | `CustomDialog` |
+| `EmptyState` | Icon, title, description and action, with not-found, unauthorized, generic and empty presets. | `EmptyState` |
+| `Progress`, `CircularProgress`, `ProgressField` | Linear bar, circular ring with a label, and a labelled progress field. | `Progress`, `CircularProgress`, `ProgressField` |
+| `Spinner` | Loading spinner in several styles and colours. | `Spinner` |
+| `Toaster`, `toast`, `toasts`, `Toast` | Sonner toasts with icon and action. `toasts` provides `success` / `error` / `warning` / `info` / `loading` presets. | `Toaster`, `toast`, `toasts`, `Toast` |
+| `Skeleton`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonText`, `SkeletonTable` | Loading placeholder and ready-made shapes. | `Skeleton` (same parts) |
+| `HydrateLoading` | Full-area spinner shown while hydrating. | `HydrateLoading` |
+| `Notifications` | Notification centre as a bell popover with an unread count, or as an inline panel, with filters and read / dismiss. | `Notifications` |
+
+### Media & files
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `S3UploadField`, `NetworkUploadField` · `S3UploadFormField`, `NetworkUploadFormField` | Drag-and-drop uploader with progress, retry, previews and size / count limits. The S3 variant uploads through a presigned PUT. | `S3UploadField`, `NetworkUploadField`, `S3UploadFormField`, `NetworkUploadFormField` |
+| `UploadField` · `UploadFormField` | Labelled file input showing the chosen file's name. | `UploadField`, `UploadFormField` |
+| `FileList`, `FileListField`, `FileListS3Field` · `FileListFormField`, `FileListS3FormField` | File list with type icons, size, download and remove. The field variants upload with progress. | `FileList`, `FileListField`, `FileListS3Field`, `FileListFormField`, `FileListS3FormField` |
+| `FilesFormField` | Free-solo autocomplete of file URLs, with image thumbnails. | — |
+| `ImageField`, `ImageS3Field` · `ImageFormField`, `ImageS3FormField` | Single image upload with preview and progress. | `ImageField`, `ImageS3Field`, `ImageFormField`, `ImageS3FormField` |
+| `ImageCropper`, `ImageCropperDialog` | Crop with zoom, rotation, aspect presets and a round shape; outputs a `File`. | `ImageCropper`, `ImageCropperDialog` |
+| `Gallery`, `LightboxGallery`, `MiniGallery` | Image / video gallery (grid, masonry, justified, carousel…) with a lightbox and selection. | `Gallery`, `LightboxGallery`, `MiniGallery` |
+| `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` | Embla carousel with keyboard navigation. | `Carousel` (same parts) |
+| `PdfReader`, `PdfViewer`, `PdfToolbar`, `PdfSidebar`, `PdfPageList`… | Browser-only PDF reader with zoom, rotation, search, thumbnails, outline and print. | `PdfReader`, `PdfViewer` (same parts) |
+| `StxPlayer`, `StxPlayerProvider`, `StxPlayerMini`, `StxPlayerQueue`… | Video / audio player with a queue, captions, playback rate, PiP, and full or mini layouts. | `StxPlayer` (same parts) |
+| `VideoPlayer` | Deprecated alias of `StxPlayer`. | `VideoPlayer` |
+| `PrintHeader`, `PrintSection`, `PrintTable`, `PrintTotals`, `PrintCard`… | `@react-pdf/renderer` building blocks for printable PDF documents, with a shared `tw`. | `PrintHeader`, `PrintSection`, `PrintTable`, `PrintTotals`, `PrintCard` |
+
+### Rich widgets
+
+| Component | What it does | @nxgt/material-vue |
+| --- | --- | --- |
+| `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer`, `ChatConversationItem`… | Chat kit: auto-scrolling list, streaming and tool messages, a composer with attachments, and markdown. | `ChatThread`, `ChatMessageList`, `ChatMessage`, `ChatComposer` (same parts) |
+| `Kanban` | Board with columns, swimlanes, WIP limits, search, and drag-and-drop cards and columns. | `Kanban` |
+| `EventCalendar` | Month / week / day / agenda calendar with drag, resize and slot creation. | `EventCalendar` |
+| `AreaChart`, `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `ScatterChart`, `FunnelChart`, `HeatmapChart` | Nivo charts themed from the CSS tokens, with loading and empty states (`ChartContainer`). | same names |
+| `RichTextEditor` · `RichTextEditorFormField` | Tiptap editor with toolbar, bubble menu, slash commands, mentions, tables, emoji and images. | `RichTextEditor`, `RichTextEditorFormField` |
+| `CodeEditor` · `CodeEditorFormField` | Monaco editor field with a label and a language switch. | `CodeEditor` |
+| `Quiz`, `QuestionCard` | Multi-step quiz with choice, boolean and text questions, answer reveal and scoring. | `Quiz`, `QuestionCard` |
+
+`@nxgt/material-vue` also has components with no React counterpart here:
+`Camera`, `ScrollArea`, `NativeSelect` and the `InputOTP` primitives.
+
+## Helpers
+
+Everything below is also re-exported from the root `@nxgt/material` barrel.
+The Vue sister, `@nxgt/material-vue`, uses the **same names** for the plain
+functions; the differences are listed under each table.
+
+### `@nxgt/material/lib`
+
+| Export | What it does |
+| --- | --- |
+| `cn(...classes)` | `clsx` + `tailwind-merge`: joins conditional classes, last Tailwind utility wins. |
+| `clientOnly(Component)` | Wraps a component so it renders nothing on the server and mounts only on the client. |
+| `renderSlot(slot, context)` | Resolves a `ContentSlot` — a `ReactNode` or a `(context) => ReactNode`. |
+| `DATE_UTILS` | `format(iso, 'PP', locale?)` (`'-'` when empty), `parseFromTimestring('HH:mm')`, `parseFromISOString`, `formatDateRangeFilter`. |
+| `formatDateRangeFilter(range)` | Turns a day-picker range into `{ from, to }` ISO strings at start / end of day. |
+| `formatNumber(value, { language?, ...Intl.NumberFormatOptions })` | `Intl.NumberFormat` with a language shortcut (`'en-US'` by default). |
+| `ifEmptyString(value, fallback)`, `ifEmptyList(value, fallback)` | Returns the fallback when the string / array is null or empty. |
+| `objectToFormData(obj)`, `formDataToObject(formData)` | Converts a flat object to `FormData` (skipping nullish values) and back. |
+| `convertToFormData(files, fieldName = 'files')` | Appends one file or a list of files to a new `FormData`. |
+| `uniqueArray(array)` | De-duplicates an array. |
+| `findByKey(array, key, value)`, `findByKeyIn(array, key, values)` | Finds the first item / every item whose `key` matches. |
+| `useFindByKey(items, key)`, `useFindById(items)` | Memoised `findByKey` / `findByKeyIn` bound to a list. |
+| `pick(obj, keys)`, `omit(obj, keys)` | Typed pick / omit for one key or a list. |
+| `cleanObject(obj, cleanNulls?)` | Drops `undefined` (and optionally `null`) properties. |
+| `cast<T>(value)`, `castAsync<T>(promise)` | Type-only casts. |
+| `delay(ms)` | Promise that resolves after `ms`. |
+| `safeGetItem(key, default)`, `safeSetItem(key, value)`, `safeRemoveItem(key)` | JSON `localStorage` access that never throws (SSR, private mode). Grouped as `LOCALE_STORE_UTILS`. |
+| `enumToKebabCase(value)`, `joinTruthyParts(parts, sep = ', ')` | `SOME_ENUM` → `some-enum`; joins the truthy parts only. Grouped as `STRING_UTILS`. |
+| `STYLES_UTILS.colorFromVariable(name, alpha?)` | `rgb(from var(--name) r g b / alpha)` for a theme token. |
+| `searchParams(request)`, `searchParam(request, key)` | Reads the query string of a Fetch `Request` (loaders, actions). |
+| `buildFieldOptions(values, { valueKey, label })` | Maps records to `{ value, label }` options by path or label function. |
+| `zodLocaleError()` | Zod v4 `customError` that translates issues through `material.zod.*`: `z.config({ customError: zodLocaleError() })`. |
+| `parsedType(data)` | Runtime type name used for Zod's `{received}` placeholder. |
+
+**Redux Toolkit helpers** (same subpath) — the state pattern behind filter,
+gallery, kanban and player:
+
+| Export | What it does |
+| --- | --- |
+| `useSliceReducer(slice, initialState?)` | Runs an RTK slice as *local* component state via `useReducer`; returns `[state, boundActions]`. |
+| `resolveSliceState(base, overrides?)` | Merges a slice's initial state with partial overrides. |
+| `useSliceSelector(state, selector)` | Memoised selector over local slice state. |
+| `useActions(actionCreators, deps?)` | Binds action creators to the store `dispatch` (`react-redux`). |
+| `createStatusSlice({ name, … })` | Slice over a `Status<T>` with `reset`, `start`, `success(data)` and `error(message)`. |
+| `createStatusesSlice({ name, initialState, … })` | Same for a record of named `Status` entries, addressed by path. |
+| `createStepFormSlice({ name, initialState? })` | Multi-step form: `step`, `values`, `isDirty`, with `updateStep`, `updateFormValues`, `reset`. |
+| `createSliceWithFilter({ name, initialState, … })` | Adds `updateFilter` and `resetFilter` for a `{ filter, sort }` state. |
+| `createAsyncSlice` | `buildCreateSlice` with the `asyncThunk` creator enabled. |
+
+Vue: the Redux helpers are Pinia store factories — `defineLocalStore`
+(per-instance store, like `useSliceReducer`), `defineStatusStore`,
+`defineStatusesStore`, `defineStepFormStore`, `defineFilterStore`,
+`resolveStoreState`, plus `runStatus`. `createAsyncSlice`, `useActions` and
+`useSliceSelector` have no Vue counterpart.
+
+### `@nxgt/material/hooks`
+
+| Export | What it does |
+| --- | --- |
+| `useTheme()` | `{ theme, preference, updateTheme }`: light / dark / system, stored in `localStorage`, applied as the `dark` class. |
+| `resolveTheme(stored, prefersDark)`, `applyResolvedTheme(theme)` | The pure theme logic behind `useTheme`, usable in an inline boot script. |
+| `useIsClient()` | `false` on the server and first render, `true` after mount — a hydration guard. |
+| `useIsMobile()` | `true` below 768 px. |
+| `useLocalizedDate()` | `{ language, locale, format }`: `DATE_UTILS.format` bound to the `I18nProvider` language. |
+| `useNumberFormatter()` | `{ formatNumber, formatCurrency }` bound to the `I18nProvider` language. |
+| `useOptions(items, { value, label, filter?, expanded? })` | Memoised `{ value, label }` options for selects; `buildOptions` is the non-hook version. |
+| `extractNode(connection)` | Unwraps a GraphQL `{ edges: [{ node }] }` connection into an array. |
+| `useSearchParam(name)` | One query-string value from the router (`react-router`). |
+| `useNavigationHandler(to, options?)`, `useNavigationHandlers(routes)` | Stable click handlers that navigate (`react-router`). |
+| `useAllowedTransitions(status, transitions, configs)` | Status-machine actions (icon, colour, label, dialog copy) allowed from the current status. |
+
+Vue: `@nxgt/material-vue/composables`, same names.
+
+### `@nxgt/material/i18n`
+
+| Export | What it does |
+| --- | --- |
+| `I18nProvider` | Holds the current language (props `defaultLanguage`, `initialLanguage` for SSR, `storageKey`, `supportedLanguages`, `onLanguageChange`). |
+| `useI18nContext()`, `useOptionalI18nContext()` | Reads `{ language, setLanguage, … }`; the first throws outside the provider, the second returns `null`. |
+| `mergeResources(base, app)` | Deep, per-language merge (`lodash.merge`) of the package bundle and yours; your leaf keys win, and each override is warned about outside production. |
+| `resources` | The package's `en` / `fr` bundle, namespace `material`. |
+| `createTranslator(resources, getLanguage?)` | ICU MessageFormat translator; a missing key comes back verbatim. |
+| `createTypedTranslation(translate)` | Turns a translator into a typed `useTranslation()` hook. |
+| `translate`, `useMaterialTranslation()` | Translator / hook bound to the package's own `material.*` keys. |
+| `getLanguage()` | Language read from `localStorage`, else `FALLBACK_LANGUAGE`. |
+| `LANGUAGE_KEY`, `FALLBACK_LANGUAGE`, `SUPPORTED_LANGUAGES` | Storage key (`'language'`), fallback and supported languages (`en`, `fr`). |
+
+Types: `FlatObject`, `Path`, `Language`, `MaterialLocaleKey`, `Translate`,
+`TranslationContext`, `ResourceBundle`. Vue adds `provideI18n()` for apps that
+provide the context from `setup()` instead of the component.
+
+### `@nxgt/material/models`, `/types`
+
+| Export | What it does |
+| --- | --- |
+| `Status<T>` | `{ data?, status: 'idle' \| 'loading' \| 'success' \| 'error', error? }` — the shape the status slices manage. |
+| `PromiseOr<T>`, `FunctionOr<T, R>`, `AsyncFunctionOr<T, R>` | A value or a promise; a value or a function computing it. |
+| `Predicate<T>`, `AsyncPredicate<T>` | `(arg) => boolean` and its async form. |
+
+### `@nxgt/material/dnd`
+
+The drag-and-drop layer on `@dnd-kit`, also in `/components`:
+
+| Export | What it does |
+| --- | --- |
+| `DndProvider`, `DndOverlay` | The `DndContext` (sensors, collision detection) and the floating drag preview. |
+| `Draggable`, `Droppable`, `DraggableDroppable`, `DragHandle` | Primitives for free drag, drop zones, nested boards and handles. |
+| `Sortable`, `SortableProvider` | A sortable item and its list context. |
+| `useDndItem`, `useDndActiveId` | The item's drag state; the id being dragged. |
+| `insertIds`, `arrayMove`, `composeRefs` | Pure list and ref helpers. |
+| `closestCenter`, `pointerWithin`, `rectIntersection`, `verticalListSortingStrategy`, `horizontalListSortingStrategy`, `CSS` | Re-exported from `@dnd-kit`. |
+
 ## SSR
 
 An SSR app that bundles this package (`ssr.noExternal: ['@nxgt/material']`)
-evaluates every module the barrels reach at **boot**, whether or not a page
-renders the component.
+runs every module the barrels reach when the server **boots**, whether or not
+a page renders the component.
 
-- **Nothing browser-only at module scope.** `pdfjs-dist` runs `new DOMMatrix()`
-  at import. Reach it through `import()` and wrap the component with
-  `clientOnly` from `@nxgt/material/lib`. A `typeof window` guard around a
-  statement does nothing when the *import* is the side effect.
+- **Nothing browser-only at module scope.** `pdfjs-dist` runs
+  `new DOMMatrix()` at import. Load it with `import()` and wrap the component
+  in `clientOnly` from `@nxgt/material/lib`. A `typeof window` guard around a
+  statement does nothing when the *import* itself is the side effect.
 - **Never `<svg><title>`.** React 19 hoists `<title>` as document metadata:
-  server emits `<title></title>`, client renders the text, hydration discards
-  the whole tree. Use `role="img"` + `aria-label` (`Icon` already does).
+  the server emits `<title></title>` while the client renders the text, and
+  the hydration mismatch makes React discard the whole tree. Use
+  `role="img"` + `aria-label` instead (`Icon` already does).
 
 ## Traps
 
@@ -189,7 +562,7 @@ renders the component.
 | --- | --- | --- |
 | Components render unstyled, no console error | Tailwind did not scan the package | `@source "../node_modules/@nxgt/material/"` |
 | `<Icon>` is blank | sprite sheet not served | `public/assets/icons/sprites/<style>.svg` |
-| Package strings vanish after adding i18n | app declared `material` | never a top-level `material` key in app resources |
+| Package strings change after adding i18n | your resources define keys under `material` | keep app strings in your own namespaces; `console.warn` lists each override in development |
 | Hydration mismatch on every page | `<svg><title>` | `role="img"` + `aria-label` |
 | `ReferenceError: DOMMatrix` at server boot | static `react-pdf` import | `import()` + `clientOnly` |
 
@@ -201,3 +574,8 @@ bun run build      # what consumers read
 bun run storybook
 bun run test
 ```
+
+## License
+
+[MIT](https://opensource.org/license/mit). The `LICENSE` file ships in the
+package.