@nxgt/material-vue 0.21.0 → 0.22.0

package/docs/guides/helpers.md

@@ -0,0 +1,421 @@
+# Helpers
+
+This page is the reference for the non-component subpaths: `/lib`,
+`/composables`, `/i18n`, `/models`, `/types` and `/dnd`, each with a table and
+one example, plus the pure helpers `/components` exports next to the
+components that use them. Everything here is also re-exported from the root
+`@nxgt/material-vue` barrel, and `/dnd` is also in `/components`.
+
+`@nxgt/material` (React) uses the **same names** for the plain functions; the
+differences are listed under each table. React's `/hooks` is
+`/composables` here, and its Redux Toolkit helpers are Pinia store factories.
+
+<a id="nxgtmateriallib"></a>
+
+## `@nxgt/material-vue/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 on the first client render, and mounts only after `onMounted`. Pair it with `defineAsyncComponent(() => import(…))`. See [SSR](ssr.md). |
+| `renderSlot(slot, context)`, `ContentSlot<T>` | Resolves a `ContentSlot`: a `VNode`, a string or number, or a `(context) => VNode \| string \| number`. |
+| `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. Also on `/components`. See [printing](printing.md#formatamount-and-formatdate). |
+| `createFormatters({ locale?, timeZone? })` | `{ formatAmount, formatDate }` bound to a locale and time zone, for a server route; options per call win. |
+| `DATE_UTILS` | `format(iso, 'PP', locale?)` (`'-'` when empty), `parseFromTimestring('HH:mm')`, `parseFromISOString(iso?)` (`null` when empty), `formatDateRangeFilter`. |
+| `formatDateRangeFilter(range)` | Turns a `{ from?: Date, to?: Date }` 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`. |
+| `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 (skipping `undefined`) 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)` | `{ findByKey(value), findByKeyIn(values) }` bound to a list. Plain functions, not computed: they read the array you passed. |
+| `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; a string default reads the raw string. A failure is logged with `console.warn` (`Failed to restore state for key "…"`) and the default is returned. 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. |
+| `STYLES_UTILS.cssSize(value)` | `240` → `'240px'`, a string unchanged, `undefined` for empty. Vue does not add `px` to a numeric inline style the way React does. |
+| `searchParams(request)`, `searchParam(request, key)` | Reads the query string of a Fetch `Request` (a server handler, an edge function). |
+| `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; `valueKey` and a string `label` are paths (`'owner.name'`), or `label` is a function. |
+| `zodLocaleError(options?)` | Zod v4 `customError` that translates issues through `material.zod.*`: `z.config({ customError: zodLocaleError() })`. Options `storageKey`, `language`, `translate` (type `ZodLocaleErrorOptions`): see [below](#zodlocaleerror-limits). |
+| `parsedType(data)` | Runtime type name used for Zod's `{received}` placeholder. |
+
+```vue
+<script setup lang="ts">
+import { cn, DATE_UTILS, formatNumber, splitMatch } from '@nxgt/material-vue/lib';
+
+defineProps<{
+  order: { ref: string; total: number; createdAt: string; late: boolean };
+  query: string;
+}>();
+</script>
+
+<template>
+  <tr :class="cn('border-b', order.late && 'text-error')">
+    <td>
+      <template v-for="(part, i) in splitMatch(order.ref, query)" :key="i">
+        <mark v-if="part.match">{{ part.text }}</mark>
+        <span v-else>{{ part.text }}</span>
+      </template>
+    </td>
+    <td>{{ DATE_UTILS.format(order.createdAt) }}</td>
+    <td>{{ formatNumber(order.total, { language: 'fr-FR', style: 'currency', currency: 'EUR' }) }}</td>
+  </tr>
+</template>
+```
+
+```ts
+// in a server handler that receives a Fetch Request
+import { searchParam } from '@nxgt/material-vue/lib';
+
+export function pageFrom(request: Request) {
+  return Number(searchParam(request, 'page') ?? '1');
+}
+```
+
+Differences from React:
+
+- **`buildFieldOptions` accepts records** (React's type only accepts `string[]`).
+- `STYLES_UTILS.cssSize` exists only here.
+
+### `zodLocaleError` limits
+
+```ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material-vue/lib';
+import { translate } from './i18n'; // createTranslator(mergeResources(...))
+
+z.config({ customError: zodLocaleError({ storageKey: 'lang', translate }) });
+```
+
+- By default it reads the language from `localStorage.language` on every
+  issue: `fr` gives French, anything else English. An `I18nProvider` with
+  another `storage-key` is followed only if you pass the same `storageKey`.
+- By default it formats from the package's own bundle, so `material.zod.*`
+  strings you merged with `mergeResources` apply only if you pass your
+  translator as `translate`.
+- On a server, or where storage cannot be read, it writes English without
+  throwing. Pass `language` (a language, or a function returning one) to use
+  the request's language instead of storage.
+
+More in [forms](forms.md#validation-messages).
+
+<a id="redux-toolkit-helpers"></a>
+
+### Pinia store factories
+
+Same subpath. This is the state pattern behind filter, gallery, kanban and
+player, and the same factories work for your own components. Every store is
+**local to the component instance that creates it**: the factory mints a new
+store id with Vue's `useId()`, so two galleries on one page never share state.
+Pinia must be installed (`app.use(createPinia())`, or the Nuxt module).
+
+| Export | What it does | React |
+| --- | --- | --- |
+| `defineLocalStore(name, { state, actions?, getters? })` | Returns a factory; call it in `setup()`, optionally with a partial initial state, to get this instance's store. | `useSliceReducer` |
+| `localStoreId(name)`, `resolveStoreState(base, overrides?)` | The per-instance id (`name:<useId>`) and the shallow state merge. | `resolveSliceState` |
+| `defineStatusStore<T>(name, initial?, actions?)` | A `Status<T>` store with `start()`, `success(data)`, `error(message)` and `reset()`. `reset` restores `status`, `data` and `error`. | `createStatusSlice` |
+| `defineStatusesStore(name, initial, actions?)` | The same over a record of named `Status` entries: `start(path)`, `success({ path, data })`, `error({ path, message })`, `reset(path)`, `statusOf(path)`. | `createStatusesSlice` |
+| `runStatus(store, fn)` | Runs an async function through a status store: `start`, then `success(data)` or `error(message)`. Returns the data and **re-throws** the error. | `createAsyncSlice` |
+| `defineFilterStore(name, initial, actions?)` | A `{ filter, sort }` store with `updateFilter({ filter?, sort? })` (merges) and `resetFilter()`. | `createSliceWithFilter` |
+| `defineStepFormStore<T>(name, initialValues?, actions?)` | Multi-step form: `step`, `values`, `isDirty`, with `updateStep(n \| fn)`, `updateFormValues(values \| fn)`, `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). | `createStepFormSlice` |
+| `createPinia`, `setActivePinia`, `storeToRefs`, `Pinia` | Re-exported from `pinia`. | — |
+
+```vue
+<script setup lang="ts">
+import { onMounted } from 'vue';
+import { Alert, Spinner } from '@nxgt/material-vue/components';
+import { defineStatusStore, runStatus } from '@nxgt/material-vue/lib';
+
+type Profile = { name: string };
+
+const useProfileStore = defineStatusStore<Profile>('profile');
+
+const props = defineProps<{ id: string }>();
+const profile = useProfileStore();
+
+onMounted(() => {
+  runStatus(profile, () =>
+    fetch(`/api/profiles/${props.id}`).then((response) => response.json() as Promise<Profile>),
+  ).catch(() => {
+    // already recorded in profile.error
+  });
+});
+</script>
+
+<template>
+  <Spinner v-if="profile.status === 'loading'" />
+  <Alert v-else-if="profile.status === 'error'" variant="error" :title="profile.error" />
+  <span v-else>{{ profile.data?.name }}</span>
+</template>
+```
+
+A store of your own, with actions typed through `this`:
+
+```ts
+import { defineLocalStore } from '@nxgt/material-vue/lib';
+
+type Counter = { count: number };
+
+export const useCounterStore = defineLocalStore<Counter>('counter', {
+  state: () => ({ count: 0 }),
+  actions: {
+    increment(this: Counter) {
+      this.count += 1;
+    },
+  },
+});
+
+// in setup(): const counter = useCounterStore({ count: 5 });
+```
+
+- **Call the factory once per component, inside `setup()`.** Each call mints a
+  new id, so two calls in one component give two stores. Outside `setup()`
+  (a test), the id falls back to a counter.
+- The factory's return type is `any`: type the store yourself where it
+  matters.
+- React's `useActions` and `useSliceSelector` have no counterpart: a Pinia
+  store's actions are already bound, and a `computed` is the selector.
+
+<a id="nxgtmaterialhooks"></a>
+
+## `@nxgt/material-vue/composables`
+
+React's `@nxgt/material/hooks`, with the same names. Under the Nuxt module
+they are auto-imported.
+
+| Export | What it does |
+| --- | --- |
+| `useTheme()` | `{ theme, preference, updateTheme }`: light / dark / system, stored in `localStorage.theme`, applied as the `dark` class. `theme` and `preference` are reactive getters. See [theming](theming.md#usetheme). |
+| `resolveTheme(stored, prefersDark)`, `applyResolvedTheme(theme)` | The pure theme logic behind `useTheme`, for a boot script. `applyResolvedTheme` does nothing without a `document`. |
+| `useIsClient()` | `Ref<boolean>`: `false` on the server and first render, `true` after mount: a hydration guard. |
+| `useIsMobile()` | `Ref<boolean>`, `true` below 768 px (`@vueuse/core`'s `useMediaQuery`). On the server and in a component's first client render (an SPA's too) it answers for `provideSSRWidth()`'s width, or a 1024 px desktop (`false`), so hydration matches; a phone switches once the component mounts. Called outside a component (a Pinia setup store), it reads the screen straight away. |
+| `useHeadingSpy(ids, onActive, options?)` | IntersectionObserver over heading ids (a ref, getter or array); 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. 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). The language and the options (values, refs or getters) are read on each call, so a template follows them; 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? })` | A `ComputedRef` of `{ value, label }` options for selects; `label` can be a key, a list of keys joined by spaces, or a function. `buildOptions` is the plain version. |
+| `extractNode(connection)` | Unwraps a GraphQL `{ edges: [{ node }] }` connection into an array. |
+| `useSearchParam(name)` | `ComputedRef<string \| null>` of one query parameter (`vue-router`; the first one when repeated). |
+| `useNavigationHandler(to, { replace? })`, `useNavigationHandlers(routes)` | Click handlers that push or replace a route (`vue-router`). |
+| `useAllowedTransitions(status, transitions, configs)` | Status-machine actions (icon, colour, label, dialog copy) allowed from the current status. Plain array, computed once per call. |
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { SelectField } from '@nxgt/material-vue/components';
+import { buildOptions, useFormatters, useLocalizedDate } from '@nxgt/material-vue/composables';
+
+type Customer = { id: string; firstName: string; lastName: string; archived: boolean; balance: number; since: string };
+
+const props = defineProps<{ customers: Customer[] }>();
+
+const id = ref('');
+const options = computed(() =>
+  buildOptions(props.customers, {
+    value: 'id',
+    label: ['firstName', 'lastName'],
+    filter: (c) => !c.archived,
+  }),
+);
+const { format } = useLocalizedDate();
+const { formatAmount } = useFormatters();
+const picked = computed(() => props.customers.find((c) => c.id === id.value));
+</script>
+
+<template>
+  <div class="grid gap-2">
+    <SelectField v-model="id" label="Customer" :options="options" />
+    <p v-if="picked">
+      Since {{ format(picked.since) }}: {{ formatAmount(picked.balance, 'EUR') }}
+    </p>
+  </div>
+</template>
+```
+
+`useOptions(items, config)` is `computed(() => buildOptions(items, config))`:
+it follows changes **inside** the array you passed, not a new array. When the
+list is a prop the parent replaces, write the `computed` over `props.x`
+yourself, as above.
+
+<a id="nxgtmateriali18n"></a>
+
+## `@nxgt/material-vue/i18n`
+
+| Export | What it does |
+| --- | --- |
+| `I18nProvider` | Holds the current language (props `default-language`, `initial-language` for SSR, `storage-key`, `supported-languages`, `on-language-change`). |
+| `provideI18n(options)` | The same, from a `setup()` of your own instead of the component. Returns the context. |
+| `useI18nContext()`, `useOptionalI18nContext()` | Reads `{ language, changeLanguage, supportedLanguages }` (a reactive object: do not destructure `language`); 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()` composable returning `{ t, i18n: { language, changeLanguage } }`. |
+| `translate`, `useMaterialTranslation()` | Translator / composable bound to the package's own `material.*` keys. `useMaterialTranslation().t(key, fallback, values?)` formats `fallback` with `values` when there is no provider or no string for `key`. |
+| `translateMaterial(language, key, fallback, values?)` | The package's own `material.*` strings for a language passed as a value (`'fr-CA'` reads `fr`), with no provider and no composable: for a server or a PDF callback. A language or key the bundle lacks formats `fallback`. See [i18n](i18n.md#outside-a-component). |
+| `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`, `LanguageProvider`,
+`MaterialLocaleKey`, `Translate`, `TranslationContext`, `ResourceBundle`,
+`MergedResources`, `I18nContextValue`, `I18nProviderProps`.
+
+```ts
+import { translate } from '@nxgt/material-vue/i18n';
+
+translate('material.command.title');           // in the stored language
+translate('material.command.title', {}, 'fr'); // in French
+```
+
+One difference from React to know about: the `useTranslation()` that
+`createTypedTranslation` builds reads the language once, when the component is
+set up. See
+[troubleshooting](../troubleshooting.md#text-stays-in-the-old-language-after-changelanguage)
+for a composable that follows `changeLanguage`.
+
+Wiring your own strings, SSR and Zod messages: [i18n](i18n.md).
+
+<a id="nxgtmaterialmodels-types"></a>
+
+## `@nxgt/material-vue/models`, `/types`
+
+| Export | What it does |
+| --- | --- |
+| `Status<T>` | `{ data?: T \| null, status: 'idle' \| 'loading' \| 'success' \| 'error', error?: string }`: the shape the status stores 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-vue/models';
+import type { FunctionOr, PromiseOr } from '@nxgt/material-vue/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();
+}
+```
+
+<a id="nxgtmaterialdnd"></a>
+
+## `@nxgt/material-vue/dnd`
+
+The drag-and-drop layer used by kanban, transfer list, sortable list and the
+event calendar, also in `/components`. It is written for Vue and has **no
+`@dnd-kit` dependency**; the names and the event shapes follow `@dnd-kit`, so
+code ported from React reads the same.
+
+| Export | What it does |
+| --- | --- |
+| `DndProvider`, `DndOverlay` | The drag context (collision detection, `disabled`) and the floating drag preview. Events: `@drag-start`, `@drag-move`, `@drag-over`, `@drag-end`, `@drag-cancel`, each with `{ active, over, delta }` (also accepted as `on-drag-*` function props). |
+| `Draggable`, `Droppable`, `DraggableDroppable`, `DragHandle` | Primitives for free drag, drop zones, nested boards and handles. Each takes `id`, `data?`, `disabled?`, `as-slot?`. |
+| `Sortable`, `SortableProvider` | A sortable item (`handle-only?`) and its list context (`items`, `strategy?`). |
+| `useDndItem()`, `useDndActiveId()` | The enclosing item's drag state (or `null`); a `ComputedRef` of the id being dragged. |
+| `insertIds(list, ids, before?, max?)`, `arrayMove(array, from, to)`, `composeRefs(...refs)` | Pure list and template-ref helpers. |
+| `closestCenter`, `pointerWithin`, `rectIntersection`, `verticalListSortingStrategy`, `horizontalListSortingStrategy`, `CSS` | Collision detection, sorting strategies and `CSS.Transform.toString(transform)` for inline styles. |
+
+Types: `DragStartEvent`, `DragMoveEvent`, `DragOverEvent`, `DragEndEvent`,
+`DragCancelEvent`, `CollisionDetection`, `SortingStrategy`, `UniqueIdentifier`,
+and the props type of each component.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ListTile } from '@nxgt/material-vue/components';
+import {
+  arrayMove,
+  DndProvider,
+  DragHandle,
+  Droppable,
+  Sortable,
+  SortableProvider,
+  type DragEndEvent,
+} from '@nxgt/material-vue/dnd';
+
+const items = ref(['Alpha', 'Beta', 'Gamma', 'Delta']);
+
+function onDragEnd({ active, over }: DragEndEvent) {
+  if (!over || active.id === over.id) return;
+  const current = items.value;
+  items.value = arrayMove(current, current.indexOf(String(active.id)), current.indexOf(String(over.id)));
+}
+</script>
+
+<template>
+  <DndProvider @drag-end="onDragEnd">
+    <Droppable id="list" class="flex w-72 flex-col gap-1 rounded-lg border p-2">
+      <SortableProvider :items="items">
+        <Sortable v-for="item in items" :id="item" :key="item">
+          <div class="rounded border border-transparent">
+            <ListTile :title="item">
+              <template #leading>
+                <DragHandle label="Drag" />
+              </template>
+            </ListTile>
+          </div>
+        </Sortable>
+      </SortableProvider>
+    </Droppable>
+  </DndProvider>
+</template>
+```
+
+`Draggable`, `Droppable`, `Sortable` and `useDndActiveId` throw
+`Dnd components must be used within DndProvider` outside a provider;
+`DragHandle` outside an item does nothing. React's `sensors` prop exists for
+compatibility, and only an empty array means something: it disables dragging.
+
+A sortable list of strings bound to a form is ready-made:
+`SortableList` / `SortableListFormField` ([forms](forms.md#what-each-field-emits)).
+
+## Component utilities
+
+Pure helpers exported from `@nxgt/material-vue/components` (and the root
+barrel) next to the components that use them: the same logic, without
+rendering the component.
+
+| Export | What it does |
+| --- | --- |
+| `formatFileSize(bytes)`, `formatCount(count, max = 99)`, `formatStatDelta(delta)`, `formatRelativeTime(value, options?)` | File sizes (`'1.2 MB'`), counters (`'99+'`), KPI deltas and relative times. |
+| `isEmail(value)`, `isUrl(value)`, `normalizeUrl(value)`, `normalizeHex(value)`, `scorePassword(value)` | The validation and normalisation behind `EmailField`, `UrlField`, `ColorField` and `PasswordField`. |
+| `parseNumberInput(raw)`, `clampNumber(value, min?, max?)`, `stepNumber(value, direction, step?)`, `parseCurrencyInput(raw)` | Locale-tolerant number parsing (`1.234,5` or `1,234.5` → `1234.5`; `null` when empty) and stepping. |
+| `minutesToParts(total)`, `partsToMinutes(hours, minutes)`, `clampRating(value, max = 5)` | Duration and rating conversions. |
+| `parsePhoneInput(raw, iso = 'FR')`, `toE164(country, national)`, `formatInternational(raw, iso = 'FR')`, `formatNational`, `isValidPhoneNumber`, `PHONE_COUNTRIES`, `flagEmoji(iso)` | Phone parsing and formatting (`libphonenumber-js`) and the country list. |
+| `TIMEZONES`, `timezoneLabel(tz, language = 'en')`, `timezoneCity(tz)`, `toCalendarDate(date)`, `fromDateValue(value, base?)` | Timezone list and labels with their UTC offset; `Date` ↔ calendar-date conversions for the date fields. |
+| `copyToClipboard(text)`, `debounce(fn, ms)` | Clipboard write (throws `Clipboard is not available` outside a secure context); a debounced function. |
+| `findActiveMenuItem(path, items)`, `partitionMenu(items)` | The app shell's longest-match and footer rules. See [app shell](app-shell.md#which-entry-is-active). |
+| `dataTableFeatures`, `useColumnHelpers()`, `useDeleteRowsHandler(onDelete?)` | The TanStack feature set, column helpers and a confirm-then-delete handler for `DataTable`. |
+| `renderBarcode(element, value, options)`, `renderQrModel(options)`, `highlightCode(code, language?)` | Barcode, QR matrix and syntax highlighting without the component. |
+| `cropImageToFile(src, area, options?)`, `IMAGE_CROP_ASPECTS` | Crops an image into a `File`; the preset aspect ratios. |
+| `formatFilterValue(field, value, words = FILTER_VALUE_WORDS)`, `FilterValueWords` | A filter chip's text (`'Yes'`, `'From 5'`); pass translated words for another language ([i18n](i18n.md)). |
+| `validateFile(file, options)`, `getValidationMessage(error, options, t?)`, `getUploadErrorMessage(error, t?)` | The upload field's checks and messages; `t` (`UploadMessageTranslate`) translates them, English without it. |
+| `parseJsonSource(source)` | What `JsonViewer` parses: `{ ok: true, value }`, or `{ ok: false, message }`; a blank source also sets `empty: true`. |
+| `formatAmount(value, currency?, options?)`, `formatDate(value, options?)`, `tw(classes)`, `commonPrintStyles` | Print helpers (the two formatters are also on `/lib`). See [printing](printing.md). |
+
+```ts
+import {
+  clampNumber,
+  formatCount,
+  formatFileSize,
+  isEmail,
+  parseNumberInput,
+  toE164,
+} from '@nxgt/material-vue/components';
+
+formatFileSize(1_250_000);                 // '1.2 MB'
+formatCount(142);                          // '99+'
+isEmail(' ada@example.com ');              // true
+clampNumber(parseNumberInput('1.234,5') ?? 0, 0, 1000); // 1000
+toE164('FR', '06 12 34 56 78');            // '+33612345678'
+```