@nxgt/material 2.1.0 → 2.2.0

package/docs/guides/helpers.md

@@ -0,0 +1,277 @@
+# Helpers
+
+This page is the reference for the non-component subpaths: `/lib`, `/hooks`,
+`/i18n`, `/models`, `/types` and `/dnd`, each with a table and one example.
+Everything here, except `/dnd`, is also re-exported from the root
+`@nxgt/material` barrel, and `/dnd` is also in `/components`.
+
+`@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. See [SSR](ssr.md). |
+| `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; `undefined` when empty. |
+| `formatNumber(value, { language?, ...Intl.NumberFormatOptions })` | `Intl.NumberFormat` with a language shortcut (`'en-US'` by default); `''` for `NaN`. |
+| `formatAmount(value, currency?, { locale?, fractionDigits? })`, `formatDate(value, { locale?, timeZone?, dateStyle?, timeStyle? })` | An amount in its currency's own decimals (two without a currency) and a medium date, in the runtime's locale unless you pass one; a date-only `YYYY-MM-DD` keeps its day in every time zone; `'—'` when empty. See [printing](printing.md#formatamount-and-formatdate). |
+| `createFormatters({ locale?, timeZone? })` | `{ formatAmount, formatDate }` bound to a locale and time zone, for a server route or a PDF document; options per call win. |
+| `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); a string default reads the raw string. Grouped as `LOCALE_STORE_UTILS`. |
+| `slugify(value)` | `'Crème brûlée!'` → `'creme-brulee'`. |
+| `enumToKebabCase(value)`, `joinTruthyParts(parts, sep = ', ')`, `splitMatch(text, query)` | `SOME_ENUM` → `some-enum`; joins the truthy parts only; splits a string around case-insensitive matches (`{ text, match }[]`). Grouped with `slugify` as `STRING_UTILS`. |
+| `STYLES_UTILS.colorFromVariable(name, alpha?)` | `rgb(from var(--name) r g b / alpha)` for a theme token. |
+| `searchParams(request)`, `searchParam(request, key)` | Reads the query string of a Fetch `Request` (loaders, actions). |
+| `isExternalHref(href)` | True for `http(s):`, protocol-relative `//` and `mailto:`: open in a new tab, not in-app. |
+| `buildFieldOptions(values, { valueKey, label })` | Maps records to `{ value, label }` options by path or label function. Its type currently accepts only `string[]`; use `buildOptions` from `/hooks` for records. |
+| `zodLocaleError(options?)` | Zod v4 `customError` that translates issues through `material.zod.*`: `z.config({ customError: zodLocaleError() })`. Options: `storageKey`, `language`, `translate` (your merged translator). English on a server. See [forms](forms.md#validation-messages). |
+| `parsedType(data)` | Runtime type name used for Zod's `{received}` placeholder. |
+
+```tsx
+import { cn, DATE_UTILS, formatNumber, searchParam, splitMatch } from '@nxgt/material/lib';
+
+export function OrderRow({ order, query }: { order: { ref: string; total: number; createdAt: string; late: boolean }; query: string }) {
+  return (
+    <tr className={cn('border-b', order.late && 'text-error')}>
+      <td>
+        {splitMatch(order.ref, query).map((part, i) =>
+          part.match ? <mark key={i}>{part.text}</mark> : <span key={i}>{part.text}</span>,
+        )}
+      </td>
+      <td>{DATE_UTILS.format(order.createdAt)}</td>
+      <td>{formatNumber(order.total, { language: 'fr-FR', style: 'currency', currency: 'EUR' })}</td>
+    </tr>
+  );
+}
+
+// in a loader or action
+export function pageFrom(request: Request) {
+  return Number(searchParam(request, 'page') ?? '1');
+}
+```
+
+### Redux Toolkit helpers
+
+Same subpath. This is the state pattern behind filter, gallery, kanban and
+player, usable as a store slice or as local component state.
+
+| 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)`. `reset` restores `status` only, not `data` / `error`. |
+| `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`. `updateStep` also writes the state to `localStorage` under `name`, a new store resumes from it, and `reset` clears it. See [forms](forms.md#a-multi-step-form). |
+| `createSliceWithFilter({ name, initialState, … })` | Adds `updateFilter` and `resetFilter` for a `{ filter, sort }` state. |
+| `createAsyncSlice` | `buildCreateSlice` with the `asyncThunk` creator enabled. |
+
+```tsx
+import { useEffect } from 'react';
+import { Alert, Spinner } from '@nxgt/material/components';
+import { createStatusSlice, useSliceReducer } from '@nxgt/material/lib';
+
+type Profile = { name: string };
+
+const profileSlice = createStatusSlice<Profile, {}, {}, 'profile'>({ name: 'profile' });
+
+export function ProfileName({ id }: { id: string }) {
+  const [state, { start, success, error }] = useSliceReducer(profileSlice);
+
+  useEffect(() => {
+    start();
+    fetch(`/api/profiles/${id}`)
+      .then((response) => response.json() as Promise<Profile>)
+      .then(success)
+      .catch((reason: Error) => error(reason.message));
+  }, [id, start, success, error]);
+
+  if (state.status === 'loading') return <Spinner />;
+  if (state.status === 'error') return <Alert variant="error" title={state.error} />;
+  return <span>{state.data?.name}</span>;
+}
+```
+
+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. See [theming](theming.md#usetheme). |
+| `resolveTheme(stored, prefersDark)`, `applyResolvedTheme(theme)` | The pure theme logic behind `useTheme`, for a boot script. |
+| `useIsClient()` | `false` on the server and first render, `true` after mount: a hydration guard. |
+| `useIsMobile()` | `true` below 768 px. `false` on the server and while hydrating, so SSR HTML is the desktop layout; a phone switches right after. |
+| `useHeadingSpy(ids, onActive, options?)` | IntersectionObserver over heading ids; reports the topmost visible one. |
+| `useLocalizedDate()` | `{ language, locale, format }`: `DATE_UTILS.format` bound to the `I18nProvider` language (`en` without a provider). |
+| `useNumberFormatter()` | `{ formatNumber, formatCurrency }`: `Intl.NumberFormat` with the options you pass, bound to the `I18nProvider` language (`en-US` without a provider). For what `formatAmount` does not cover: percentages, units, compact notation. |
+| `useFormatters({ locale?, timeZone? })` | `formatAmount` and `formatDate` bound to the `I18nProvider` language (`en` without a provider), so server and browser print the same string for a date-only value, or when you pass `timeZone`. **Use it for money**: the currency's own decimals (`fractionDigits` overrides), `—` for an empty value, the same decimals as `CurrencyField`, and the same output as the PDF builders. See [printing](printing.md#formatamount-and-formatdate). |
+| `useOptions(items, { value, label, filter?, expanded? })` | Memoised `{ value, label }` options for selects; `label` can be a key, a list of keys joined by spaces, or a function. `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. |
+
+```tsx
+import { useState } from 'react';
+import { SelectField } from '@nxgt/material/components';
+import { useFormatters, useLocalizedDate, useOptions } from '@nxgt/material/hooks';
+
+type Customer = { id: string; firstName: string; lastName: string; archived: boolean; balance: number; since: string };
+
+export function CustomerPicker({ customers }: { customers: Customer[] }) {
+  const [id, setId] = useState('');
+  const options = useOptions(customers, {
+    value: 'id',
+    label: ['firstName', 'lastName'],
+    filter: (c) => !c.archived,
+  });
+  const { format } = useLocalizedDate();
+  const { formatAmount } = useFormatters();
+  const picked = customers.find((c) => c.id === id);
+
+  return (
+    <div className="grid gap-2">
+      <SelectField label="Customer" value={id} onValueChange={setId} options={options} />
+      {picked && (
+        <p>
+          Since {format(picked.since)}: {formatAmount(picked.balance, 'EUR')}
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+`useOptions` memoises on its arguments: pass a stable `filter` (defined outside
+the component, or with `useCallback`) when the list is long.
+
+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, changeLanguage, supportedLanguages }`; 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. `useMaterialTranslation().t(key, fallback)` returns `fallback` without a provider. |
+| `translateMaterial(language, key, fallback, values?)` | The same as `useMaterialTranslation().t`, with the language passed as a value: no provider, no hook. For a PDF `footer` function or a server. `'fr-CA'` reads `fr`; an unknown language formats `fallback`. |
+| `getLanguage()` | Language read from `localStorage`, else `FALLBACK_LANGUAGE`. |
+| `LANGUAGE_KEY`, `FALLBACK_LANGUAGE`, `SUPPORTED_LANGUAGES` | Storage key (`'language'`), fallback (`'en'`) and supported languages (`en`, `fr`). |
+
+Types: `FlatObject`, `Path`, `Language`, `MaterialLocaleKey`, `Translate`,
+`TranslationContext`, `ResourceBundle`, `I18nContextValue`,
+`I18nProviderProps`. Vue adds `provideI18n()` for apps that provide the
+context from `setup()` instead of the component.
+
+```ts
+import { translate } from '@nxgt/material/i18n';
+
+translate('material.command.title');           // in the stored language
+translate('material.command.title', {}, 'fr'); // in French
+```
+
+Wiring your own strings, SSR and Zod messages: [i18n](i18n.md).
+
+## `@nxgt/material/models`, `/types`
+
+| Export | What it does |
+| --- | --- |
+| `Status<T>` | `{ data?: T \| null, status: 'idle' \| 'loading' \| 'success' \| 'error', error?: string }`: 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; a promise or an async function computing it. |
+| `Predicate<T>`, `AsyncPredicate<T>` | `(arg) => boolean` and its async form. |
+
+```ts
+import type { Status } from '@nxgt/material/models';
+import type { FunctionOr, PromiseOr } from '@nxgt/material/types';
+
+type Invoice = { id: string };
+
+const idle: Status<Invoice[]> = { status: 'idle' };
+
+function resolveTitle(title: FunctionOr<number, string>, count: number): string {
+  return typeof title === 'function' ? title(count) : title;
+}
+
+async function save(write: () => PromiseOr<void>) {
+  await write();
+}
+```
+
+## `@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`. |
+
+```tsx
+import { useState } from 'react';
+import { ListTile } from '@nxgt/material/components';
+import {
+  arrayMove,
+  DndProvider,
+  DragHandle,
+  Droppable,
+  Sortable,
+  SortableProvider,
+} from '@nxgt/material/dnd';
+
+export function ReorderableList() {
+  const [items, setItems] = useState(['Alpha', 'Beta', 'Gamma', 'Delta']);
+
+  return (
+    <DndProvider
+      onDragEnd={({ active, over }) => {
+        if (!over || active.id === over.id) return;
+        setItems((current) =>
+          arrayMove(current, current.indexOf(String(active.id)), current.indexOf(String(over.id))),
+        );
+      }}
+    >
+      <Droppable id="list" className="flex w-72 flex-col gap-1 rounded-lg border p-2">
+        <SortableProvider items={items}>
+          {items.map((item) => (
+            <Sortable key={item} id={item} asSlot>
+              <div className="rounded border border-transparent">
+                <ListTile title={item} leading={<DragHandle label="Drag" />} />
+              </div>
+            </Sortable>
+          ))}
+        </SortableProvider>
+      </Droppable>
+    </DndProvider>
+  );
+}
+```
+
+A sortable list of strings bound to a form is ready-made:
+`SortableList` / `SortableListFormField` ([forms](forms.md#what-each-field-emits)).

package/docs/guides/i18n.md

@@ -0,0 +1,386 @@
+# i18n
+
+This page covers how to show the components in French or English, switch
+language at runtime, type your own strings, and translate Zod messages. The
+package owns the i18n **mechanism**. Your app owns the resource **content**.
+
+```tsx
+import { I18nProvider } from '@nxgt/material/i18n';
+import { LanguageSwitcher } from '@nxgt/material/components';
+
+export function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <I18nProvider defaultLanguage="en">
+      <LanguageSwitcher />
+      {children}
+    </I18nProvider>
+  );
+}
+```
+
+That is enough for the package's own strings (empty states, dialogs, table
+pagination, field hints…) to follow the language. `LanguageSwitcher` lists the
+provider's `supportedLanguages` and changes the language for the whole tree,
+with no reload.
+
+## Without a provider
+
+Every component keeps working with no `I18nProvider` mounted: it renders its
+built-in English copy. Adopting i18n later is additive.
+
+That copy is formatted like a translation, so counts and positions are filled
+in: a stepper reads `Step 01`, a Kanban WIP badge `3/5`, a quiz
+`Question 2 of 5`, never `Step {step}` or `{count}/{max}`. This holds on a
+server too. The same happens under a provider when the language's bundle lacks
+a key.
+
+Your own components can do the same with `useMaterialTranslation()`, whose
+`t(key, fallback, values)` formats `fallback` with `values` when there is no
+provider or no string for `key`:
+
+```tsx
+import { useMaterialTranslation } from '@nxgt/material/i18n';
+
+const { t } = useMaterialTranslation();
+t('material.stepper.step', 'Step {step}', { step: 2 }); // 'Step 2', 'Étape 2' in French
+```
+
+Where a hook cannot run (outside React, on a server, in a PDF `footer`
+function that react-pdf calls while laying out pages), `translateMaterial`
+takes the language as a value instead of reading a provider:
+
+```ts
+import { translateMaterial } from '@nxgt/material/i18n';
+
+translateMaterial('fr', 'material.print.page-of', 'Page {page} of {pages}', { page: 2, pages: 5 }); // 'Page 2 sur 5'
+translateMaterial('fr-CA', 'material.print.page', 'Page {page}', { page: 2 });                     // French: 'Page 2'
+translateMaterial('de', 'material.print.page-of', 'Page {page} of {pages}', { page: 2, pages: 5 }); // no German bundle: 'Page 2 of 5'
+```
+
+```ts
+function translateMaterial(
+  language: string | null | undefined,
+  key: MaterialLocaleKey,
+  fallback: string,
+  values?: TranslationContext,
+): string;
+```
+
+## Wiring your own strings
+
+Keep your strings in your own namespaces, merge them with the package's
+bundle, and build a typed translator and hook **once**:
+
+```ts
+// i18n/resources.ts
+export const resources = {
+  en: {
+    app: {
+      greeting: 'Hello {name}',
+      cart: '{count, plural, =0 {Your cart is empty} one {# item} other {# items}}',
+    },
+  },
+  fr: {
+    app: {
+      greeting: 'Bonjour {name}',
+      cart: '{count, plural, =0 {Votre panier est vide} one {# article} other {# articles}}',
+    },
+  },
+};
+```
+
+```ts
+// i18n/index.ts
+import {
+  createTranslator,
+  createTypedTranslation,
+  type FlatObject,
+  mergeResources,
+  resources as materialResources,
+} from '@nxgt/material/i18n';
+import { resources as appResources } from './resources';
+
+export const resources = mergeResources(materialResources, appResources);
+export type LocaleKey = keyof FlatObject<typeof resources.en, string>;
+export const translate = createTranslator<LocaleKey>(resources);
+export const useTranslation = createTypedTranslation<LocaleKey>(translate);
+```
+
+```tsx
+// any component under <I18nProvider>
+import { useTranslation } from './i18n';
+
+export function CartSummary({ name, count }: { name: string; count: number }) {
+  const { t, i18n } = useTranslation();
+  return (
+    <p>
+      {t('app.greeting', { name })}: {t('app.cart', { count })}
+      <button type="button" onClick={() => i18n.changeLanguage('fr')}>FR</button>
+    </p>
+  );
+}
+```
+
+- `LocaleKey` is the union of every leaf path (`'app.greeting'`,
+  `'material.command.title'`, …), so a typo in a key is a type error.
+- Messages are [ICU MessageFormat](https://formatjs.github.io/docs/core-concepts/icu-syntax/)
+  (`intl-messageformat`): `{name}`, plurals, selects.
+- **A missing key is returned as-is** (`t('app.nope')` → `'app.nope'`). A
+  message that is not valid ICU is logged with `console.error` and returned
+  unformatted. Neither throws.
+- `useTranslation()` from `createTypedTranslation` must be called under
+  `I18nProvider`; it throws otherwise (see `useI18nContext` below).
+
+```ts
+function createTranslator<K extends string>(
+  bundle: Record<string, any>,
+  getLanguage?: (() => Language) | Language, // default: reads localStorage
+): (key: K, context?: TranslationContext, language?: (() => Language) | Language) => string;
+
+function createTypedTranslation<K extends string>(translate: Translate<K>): () => {
+  t: (key: K, context?: TranslationContext) => string;
+  i18n: { language: Language; changeLanguage: (value: Language) => void };
+};
+```
+
+`translate` from your `i18n/index.ts` also works outside React: loaders,
+toasts, table column definitions. Without a third argument it reads the
+language from `localStorage` (`'en'` on a server), so pass one where you know
+it: `translate('app.greeting', { name }, 'fr')`.
+
+## `I18nProvider`
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `defaultLanguage` | `Language` | `'en'` | Used when nothing valid is stored |
+| `initialLanguage` | `Language` | — | Used as-is for the first render when supported, and `localStorage` is not read. Set it in SSR. See [below](#server-rendering) |
+| `storageKey` | `string` | `'language'` | `localStorage` key the choice is read from and written to |
+| `supportedLanguages` | `Language[]` | `['en', 'fr']` | What `changeLanguage` accepts and `LanguageSwitcher` lists |
+| `onLanguageChange` | `(language) => void` | — | Called after a successful change: save it to a cookie, a profile, analytics |
+
+`changeLanguage` with an unsupported value logs
+`[@nxgt/material] Unsupported language: "de".` and does nothing. If storage is
+unavailable (private mode, quota), the language still changes for the session.
+
+Reading the state:
+
+```ts
+import { useI18nContext, useOptionalI18nContext } from '@nxgt/material/i18n';
+
+const { language, changeLanguage, supportedLanguages } = useI18nContext(); // throws outside the provider
+const context = useOptionalI18nContext(); // null outside the provider
+```
+
+`Language` is `'en' | 'fr'`: the languages the package ships strings for. A
+third language is not in the type today, so adding one to
+`supportedLanguages` takes a cast. The runtime accepts it: your translator
+uses your strings for it, and the components fall back to their English copy,
+formatted.
+
+```tsx
+const LANGUAGES = ['en', 'fr', 'de'] as Language[];
+
+<I18nProvider supportedLanguages={LANGUAGES}>{children}</I18nProvider>;
+```
+
+## The `material` namespace
+
+The package's own strings live under one top-level namespace per language,
+`material` (`material.command.title`, `material['empty-state'].*`, …).
+`mergeResources` deep-merges per language (`lodash.merge`): keys unique to
+either side are kept, and where both define the same leaf, **your value
+wins**.
+
+The copy components render on their own comes from this namespace: empty
+states, dialogs, pickers, the rich-text editor's toolbar, menus, node dialogs,
+slash menu, font names and table-caption alignment
+(`material['rich-text-editor'].*`), the carousel arrows' screen-reader text,
+the camera, the autocomplete's `Add "…"` and empty state, the QR code and
+barcode accessible names, the calendar's navigation tooltips
+(`material.calendar.*`), the data table's selection checkboxes, the filter's
+presets and `Min`/`Max` fields, the `variant="4"` spinner's label,
+`ScrollToTop`, the network upload field's `Retry`/`Remove`, the map's
+`You are here` and zoom buttons, and the icon-only close button of
+`DialogClose`, `DrawerClose`, `SheetClose` and `SheetContent`'s
+`withCloseButton`. The other icon-only buttons are named from it too: the
+`Sidebar` toggle (`material.sidebar.toggle`), the data table's row expander
+(`material.table.labels.toggle-row`), a chip's remove button — `Chip`,
+`ComboboxChip` and the `Autocomplete` chips, "Remove {label}"
+(`material.chip.dismiss-label`) — the `LocationPreview` trigger
+(`material.map.preview` / `preview-named`), and the delete button of the
+deprecated `ContactItem` / `OpeningHoursItem` (`material.contacts.buttons.remove`,
+`material['opening-hours'].buttons.remove`). `PrintDocument`'s page numbers
+read `material.print.page-of` ("Page {page} of {pages}", "Page {page} sur
+{pages}") and `material.print.page` ("Page {page}"), and a `PrintDataTable`
+reads `material.print.table.total` ("Total", "Total") for its totals row and
+`material.print.table.empty` ("No rows", "Aucune ligne") for an empty table,
+unless you pass `totalLabel` or `emptyText`; a PDF does not see your
+app's provider, so pass `PrintDocument` its `language` (see
+[printing](printing.md#translating-built-in-strings-in-a-pdf)). The keys and the French
+are the same in `@nxgt/material-vue`, so one set of overrides fits both. Text
+you pass yourself always wins over the translation: a `label`,
+`Autocomplete`'s `freeSoloLabel` and `empty`, the editor's `options.labels`,
+`QRCode`'s `title`, `Barecode`'s `aria-label`, `CarouselPrevious`/`CarouselNext`
+children, `Spinner`'s and `ScrollToTop`'s `aria-label`, `LocationMarker`'s
+`tooltip`, text children or an `aria-label` on `DialogClose`,
+`DrawerClose` and `SheetClose`, and `ComboboxChip`'s `removeLabel`.
+
+Smaller labels follow the language the same way: the filter's empty state and
+`+N more` chip (`material.filter.empty` / `more`) and the Yes/No, From, Until
+and Up to of its chips (`material.filter.value.*`; `formatFilterValue` takes
+those words as an optional third argument); the `aria-label` of `Breadcrumb`
+and `Pagination` and the breadcrumb ellipsis's "More"
+(`material.breadcrumb.*`, `material.pagination.label`), and `DocHeader`'s
+breadcrumb (`material.doc.breadcrumb`); `MessageCard`'s "Unread"
+(`material.cards.unread`); the network upload field's "Replace {name}", "Upload
+failed", its type, size and count errors (`material.upload.replace-named`,
+`failed`, `invalid-type`, `too-large`, `max-files`; an error keeps the language
+it was raised in) and the drop zone's "Max {size}" and "Up to {count} files"
+(`material.upload.dropzone.max-size` / `max-files`); the editor's
+placeholder, which follows a language change without rebuilding the editor,
+and its emoji buttons (`material['rich-text-editor'].placeholder` /
+`insert-emoji`); `CircularProgress`'s "Progress: {value}%"
+(`material['circular-progress'].label`); `StxPlayer`'s "Media player" for a
+track without a title (`material['stx-player'].label`); `PaneLayoutPane`'s
+sheet title on a phone (`material['pane-layout']['sheet-title']`);
+`JsonViewer`'s "Empty JSON" (`material['json-viewer'].empty`);
+`TimePicker`'s AM/PM (`material['time-picker'].am` / `pm`, "a.m." / "p.m." in
+French); and the names of `DurationField`'s inputs, "Hours" and "Minutes"
+(`material['duration-field']['hours-label']` / `minutes-label`). `material.pagination.first` / `last`,
+`material.carousel.roledescription` / `slide` and
+`material.attributes.buttons.add-option` are there for `@nxgt/material-vue`'s
+`PaginationFirst`, `PaginationLast`, carousel and attribute options, so the
+bundles hold the same keys. Your `placeholder`, `sheetTitle` and `aria-label` still
+win.
+
+To format filter values yourself in the provider's language, pass
+`formatFilterValue` the same words `FilterChips` uses (`FilterValueWords`; the
+English is `FILTER_VALUE_WORDS`):
+
+```tsx
+const { t } = useMaterialTranslation();
+const words: FilterValueWords = {
+  yes: t('material.filter.value.yes', 'Yes'),
+  no: t('material.filter.value.no', 'No'),
+  from: (value) => t('material.filter.value.from', 'From {value}', { value }),
+  until: (value) => t('material.filter.value.until', 'Until {value}', { value }),
+  upTo: (value) => t('material.filter.value.up-to', 'Up to {value}', { value }),
+};
+formatFilterValue(field, value, words); // "À partir de 5" in French
+```
+
+The editor's slash menu matches what you type against the translated title
+and description and against the English ones, ignoring accents: in French,
+`/titre`, `/heading` and `/separateur` all work.
+
+Some strings are still English in every language, among them the filter's
+validation messages, the camera's error messages, the editor's callout type
+names and default block content, and the names of the emoji picker's category
+tabs. File sizes (`2.0 KB`) and the filter chips' dates are not formatted for
+the provider's language.
+
+```tsx
+// Under <I18nProvider defaultLanguage="fr">
+<CarouselNext />            // screen reader: "Diapositive suivante"
+<Autocomplete freeSolo … /> // typing "Qwik" offers "Ajouter « Qwik »"
+<QRCode value={url} />      // role="img" aria-label="Code QR"
+<Spinner variant="4" />     // role="img" aria-label="Chargement..."
+```
+
+That override is visible only through **your** translator. The components
+translate through the package's own bundle, so defining
+`material.command.title` in your resources changes what
+`t('material.command.title')` returns in your code, but not the title
+`CommandDialog` renders.
+
+Each time `mergeResources` runs outside production, overlapping leaves are
+reported, one line per language:
+
+```text
+[@nxgt/material] i18n resource override for language "en": material.command.title. App resources take precedence over the base bundle at these keys.
+```
+
+If you see that warning and did not mean it, move your key out of `material`.
+
+## Zod messages
+
+```ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material/lib';
+
+z.config({ customError: zodLocaleError() });
+```
+
+The error map formats Zod v4 issues from `material.zod.*`. It is independent
+of the provider: by default it reads `localStorage.language` itself (`'fr'` →
+French, anything else → English) and formats from the package's bundle. On a
+server, or when storage cannot be read, it writes English.
+
+Three options line it up with the rest of your i18n:
+
+```ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material/lib';
+import { translate } from './i18n'; // createTranslator(mergeResources(...)), above
+
+z.config({
+  customError: zodLocaleError({
+    storageKey: 'lang', // the storageKey you gave I18nProvider
+    translate, // your overrides of material.zod.* apply
+  }),
+});
+```
+
+- `storageKey`: where the language is read from. Default `'language'`.
+- `language`: a language, or a function returning one, used instead of
+  storage. Use it on a server, where you know the request's language.
+- `translate`: the translator to format with. Default: the package's own.
+
+Examples and per-field overrides are in [forms](forms.md#validation-messages).
+
+## Server rendering
+
+On the server there is no `localStorage`, so without help the server renders
+`defaultLanguage` and a French visitor's browser switches after hydration: a
+mismatch. Resolve the language from the request and pass it as
+`initialLanguage`, then persist changes where the server can read them:
+
+```tsx
+import { I18nProvider, type Language } from '@nxgt/material/i18n';
+
+export function pickLanguage(request: Request): Language {
+  const cookie = request.headers.get('cookie')?.match(/(?:^|; )lang=(en|fr)/)?.[1];
+  if (cookie === 'en' || cookie === 'fr') return cookie;
+  return request.headers.get('accept-language')?.toLowerCase().startsWith('fr') ? 'fr' : 'en';
+}
+
+export function AppI18n({ language, children }: { language: Language; children: React.ReactNode }) {
+  return (
+    <I18nProvider
+      initialLanguage={language}
+      onLanguageChange={(next) => {
+        document.cookie = `lang=${next}; path=/; max-age=31536000; samesite=lax`;
+      }}
+    >
+      {children}
+    </I18nProvider>
+  );
+}
+```
+
+`language` comes from your loader (`pickLanguage(request)`), and is returned to
+the page so server and client start from the same value. More on server
+rendering in [SSR](ssr.md).
+
+## Dates and numbers
+
+`useLocalizedDate()` and `useNumberFormatter()` from `@nxgt/material/hooks`
+bind date-fns and `Intl.NumberFormat` to the provider's language. For money
+and dates shown to a user, `useFormatters()` (`formatAmount`, `formatDate`)
+prints what the PDF builders print, with the decimals `CurrencyField` shows. See
+[helpers](helpers.md#nxgtmaterialhooks).
+
+## Reference
+
+Everything `@nxgt/material/i18n` exports is listed in
+[helpers](helpers.md#nxgtmateriali18n).