najm-kit 2.7.2 → 2.8.0

package/CHANGELOG.md

@@ -1,6 +1,23 @@
-# Changelog
-
-## 2.6.2
+# Changelog
+
+## 2.8.0 - 2026-08-08
+
+- Added server-safe `najm-kit/format` helpers for currency minor units,
+  numbers, percentages, dates, times, relative time, tokens, local date inputs,
+  and slugs. Client applications can use the same contract reactively through
+  `NajmFormatProvider` and `useNajmFormat`.
+- Added the server-safe `najm-kit/pagination` offset protocol, including bounded
+  page creation, total-aware continuation, probe-row continuation for APIs
+  without totals, and query cleanup that preserves meaningful `false` and `0`.
+- Added the optional-peer `najm-kit/query` entry with offset infinite-query and
+  responsive paged/card-list hooks, plus shared card-pagination adapters and
+  localized continuation labels.
+- Extended `NajmAppProvider` with formatting locale, currency, and placeholder
+  configuration so applications can bind language, time zone, and formatting
+  without another host bridge provider.
+- Added shared media-query/card-viewport helpers and avatar-source utilities.
+
+## 2.6.2
 
 - Added `NSidebarProvider` and `useNSidebar`, so sidebar state can be read from a distance. `NSidebar` renders beside the page content rather than around it, which left applications hand-rolling a context to hand `setMobileOpen` down to a page header — a wrapper component plus an aliased import at every call site. Wrap the shell in `NSidebarProvider` and `NPageHeader` now resolves both `onSidebarOpen` and `mobileBreakpoint` from it, so a header nested anywhere below renders a working mobile trigger with no props threaded to it. Also exports the `NSidebarContextValue` type.
 - `NSidebar` resolves its open and collapsed state as explicit prop → surrounding provider → internal state. Passing `collapsed`, `mobileOpen`, `onCollapsedChange`, or `onMobileOpenChange` keeps behaving exactly as before, and a sidebar with no provider around it still owns its own state, so this is additive for every existing consumer.

package/README.md

@@ -212,10 +212,93 @@ Key behaviors:
   a newer value, and object URLs created by the component are tracked so
   consumer-owned blob URLs are never revoked.
 
-`AvatarInput` forwards every preview and accessibility prop unchanged while
-preserving its circular, size, fill, and camera-icon defaults.
-
-## Hooks
+`AvatarInput` forwards every preview and accessibility prop unchanged while
+preserving its circular, size, fill, and camera-icon defaults.
+
+## Formatting
+
+Pure formatters are available from the server-safe `najm-kit/format` entry.
+Money values are integer minor units and use the currency's own exponent (for
+example MAD has two decimals, JPY zero, and KWD three).
+
+```ts
+import { formatCurrency, formatDate, slugify } from 'najm-kit/format';
+
+formatCurrency(12_500, { locale: 'fr-MA', currency: 'MAD' });
+formatDate('2026-08-08T20:00:00Z', {
+  locale: 'fr-MA',
+  timeZone: 'Africa/Casablanca',
+});
+slugify('Najm Format & Pagination');
+```
+
+Client code can use the active locale, time zone, currency, and placeholder
+through `useNajmFormat`. `NajmAppProvider` mounts the format provider for you:
+
+```tsx
+import { NajmAppProvider } from 'najm-kit/app';
+import { useNajmFormat } from 'najm-kit';
+
+<NajmAppProvider
+  translations={translations}
+  currency="MAD"
+  locales={{ en: 'en-MA', fr: 'fr-MA' }}
+>
+  <App />
+</NajmAppProvider>
+
+function Total({ value }: { value: number }) {
+  return <span>{useNajmFormat().money(value)}</span>;
+}
+```
+
+## Offset pagination and queries
+
+`najm-kit/pagination` is server-safe and framework-independent. It accepts
+endpoints that return either `{ rows, total }` or a bare row array. When no
+total exists it probes for one extra row; when a total exists continuation is
+calculated without another request.
+
+```ts
+import {
+  createOffsetPagination,
+  fetchOffsetPage,
+} from 'najm-kit/pagination';
+
+const pagination = createOffsetPagination(pageIndex, pageSize);
+const page = await fetchOffsetPage(
+  ({ limit, offset }) => api.orders.list({ limit, offset }),
+  pagination,
+);
+```
+
+React Query consumers install the optional `@tanstack/react-query` peer and use
+the isolated `najm-kit/query` entry. `useResponsiveOffsetList` resolves numbered
+desktop paging versus card continuation and exposes props that plug directly
+into `NTable` and `createCardPagination`.
+
+```tsx
+import { NTable, createCardPagination } from 'najm-kit';
+import { useResponsiveOffsetList } from 'najm-kit/query';
+
+const list = useResponsiveOffsetList({
+  queryKey: ['orders'],
+  fetchPage: ({ limit, offset }) => api.orders.list({ limit, offset }),
+  strategy: 'paged',
+});
+
+<NTable
+  data={list.data}
+  columns={columns}
+  manualPagination
+  pageCount={list.pageCount}
+  pagination={list.pagination}
+  onPaginationChange={list.onPaginationChange}
+  cardPagination={createCardPagination(list, labels)}
+/>
+```
+
+## Hooks
 
 ```tsx
 import { useKeyboard } from 'najm-kit';

package/dist/{NajmUIProvider-ClpHD-55.d.ts → NajmUIProvider-BSbXaqak.d.ts}

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
 import React__default from 'react';
-import { a as NTablePaginationLabels, e as NajmTranslate } from './paginationLabels-CY2PvbMj.js';
+import { b as NTablePaginationLabels, N as NajmTranslate } from './paginationLabels-dZLSNxfo.js';
 
 type NajmMode = 'light' | 'dark';
 type NajmAccent = 'neutral' | 'emerald' | 'green' | 'slate' | 'blue' | 'violet';

package/dist/adapters/app.d.ts

@@ -3,8 +3,8 @@ import { Translations } from 'najm-i18n';
 import { N as NBrandingInput } from '../NBrandingContext-dkADu8JS.js';
 import { NajmNextUIProviderProps } from './next.js';
 import 'react';
-import '../NajmUIProvider-ClpHD-55.js';
-import '../paginationLabels-CY2PvbMj.js';
+import '../NajmUIProvider-BSbXaqak.js';
+import '../paginationLabels-dZLSNxfo.js';
 
 /** Branding shown by the kit's chrome. Purely presentational values. */
 interface NajmAppBranding {

package/dist/adapters/app.mjs

@@ -1,8 +1,9 @@
 'use client';
-import { NBrandingStateProvider, NajmFormatProvider } from '../chunk-QOP7L6RD.mjs';
+import { NBrandingStateProvider, NajmFormatProvider } from '../chunk-PCPMAEKP.mjs';
 import { NajmNextUIProvider } from '../chunk-IRFFSAO2.mjs';
 import '../chunk-USZUOJMK.mjs';
 import '../chunk-KVZACF4G.mjs';
+import '../chunk-JABLSOQN.mjs';
 import * as React from 'react';
 import { I18nProvider, useTranslation } from 'najm-i18n/react';
 import { jsx } from 'react/jsx-runtime';

package/dist/adapters/next.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React__default from 'react';
-import { N as NajmUIProviderProps } from '../NajmUIProvider-ClpHD-55.js';
-import '../paginationLabels-CY2PvbMj.js';
+import { N as NajmUIProviderProps } from '../NajmUIProvider-BSbXaqak.js';
+import '../paginationLabels-dZLSNxfo.js';
 
 interface NextLinkAdapterProps extends Record<string, any> {
     href: string;

package/dist/cardPagination-Bwf3tEeN.d.ts

@@ -0,0 +1,65 @@
+import { N as NajmTranslate, a as NTableCardPagination } from './paginationLabels-dZLSNxfo.js';
+
+/**
+ * How a list continues.
+ *
+ * - `paged` — numbered pages on desktop, scroll continuation on card viewports.
+ * - `infinite` — scroll continuation everywhere.
+ * - `all` — one request for the whole set, no controls. Only valid for a list
+ *   with a proven bound.
+ */
+type ListStrategy = "all" | "infinite" | "paged";
+/** The presentation mode resolved for the current viewport and strategy. */
+type ResolvedListMode = "all" | "infinite" | "paged";
+interface CardPaginationState {
+    /**
+     * The resolved mode. When omitted, `cardViewport` alone decides — a card
+     * viewport continues on scroll, a desktop one paginates.
+     */
+    mode?: ResolvedListMode;
+    cardViewport?: boolean;
+    hasNextPage: boolean;
+    loadingMore: boolean;
+    /**
+     * Truthy when the last append failed. The value is not rendered — the message
+     * shown is `loadMoreError` from the labels, so a thrown `Error` or an API
+     * envelope can be passed straight through without leaking its text into the UI.
+     */
+    loadMoreError?: unknown;
+    onLoadMore: () => unknown | Promise<unknown>;
+}
+interface CardPaginationLabels {
+    loadMoreError?: string;
+    retryLabel?: string;
+    itemsLoaded?: (count: number) => string;
+}
+declare const DEFAULT_CARD_PAGINATION_KEY_PREFIX = "common.pagination";
+type DefaultCardPaginationPrefix = typeof DEFAULT_CARD_PAGINATION_KEY_PREFIX;
+/** The three catalog keys `buildCardPaginationLabels` reads under `Prefix`. */
+type CardPaginationKey<Prefix extends string = DefaultCardPaginationPrefix> = `${Prefix}.itemsLoaded` | `${Prefix}.loadMoreError` | `${Prefix}.retryLoadMore`;
+/**
+ * Projects a translator onto the three card-continuation labels, matching
+ * `buildPaginationLabels` — same prefix convention, same key-per-field naming.
+ *
+ * The keys are named in the type, not just built at runtime, so an application
+ * whose `t` is typed to a generated union of its catalog can pass it directly
+ * and have the three keys verified against that union.
+ */
+declare function buildCardPaginationLabels<Prefix extends string = DefaultCardPaginationPrefix>(t: NajmTranslate<CardPaginationKey<Prefix>>, prefix?: Prefix): CardPaginationLabels;
+/**
+ * Builds the `cardPagination` prop from the state a paged list already holds.
+ *
+ * The three modes are not interchangeable presentations of one thing: `paged`
+ * hands page-size control back to NTable, which measures the container and
+ * reports the size it wants through `onPaginationChange`; `all` renders exactly
+ * what it is given and shows no controls; `infinite` is the only one that needs
+ * continuation wiring, which is why the other two ignore the labels entirely.
+ *
+ * The second argument takes a translator as well as a label bundle. That is the
+ * common case — a list page has `t` in hand and nothing else to say about these
+ * three strings — and passing it here rather than pre-building labels also means
+ * the lookups only happen in `infinite` mode, where they are rendered.
+ */
+declare function createCardPagination<Prefix extends string = DefaultCardPaginationPrefix>(state: CardPaginationState, labels?: CardPaginationLabels | NajmTranslate<CardPaginationKey<Prefix>>, prefix?: Prefix): NTableCardPagination;
+
+export { type CardPaginationKey as C, DEFAULT_CARD_PAGINATION_KEY_PREFIX as D, type ListStrategy as L, type ResolvedListMode as R, type CardPaginationLabels as a, type CardPaginationState as b, buildCardPaginationLabels as c, createCardPagination as d };

package/dist/chunk-2NX2VKS2.mjs

@@ -0,0 +1,42 @@
+// src/lib/pagination.ts
+var DEFAULT_PAGE_SIZE = 25;
+var DEFAULT_MAX_PAGE_SIZE = 100;
+function toApiPage(result) {
+  return Array.isArray(result) ? { rows: result, total: null } : result;
+}
+function createOffsetPagination(pageIndex = 0, pageSize = DEFAULT_PAGE_SIZE, { maxLimit = DEFAULT_MAX_PAGE_SIZE } = {}) {
+  const safePageIndex = Math.max(0, Math.trunc(pageIndex));
+  const safePageSize = Math.min(maxLimit, Math.max(1, Math.trunc(pageSize)));
+  return { limit: safePageSize, offset: safePageIndex * safePageSize };
+}
+function getPageIndex({ limit, offset }) {
+  return Math.floor(Math.max(0, offset) / Math.max(1, limit));
+}
+async function fetchOffsetPage(fetchPage, pagination, { maxLimit = DEFAULT_MAX_PAGE_SIZE } = {}) {
+  const requestedLimit = Math.min(maxLimit, Math.max(1, pagination.limit));
+  const probeLimit = requestedLimit < maxLimit ? requestedLimit + 1 : requestedLimit;
+  const page = toApiPage(
+    await fetchPage({ limit: probeLimit, offset: pagination.offset })
+  );
+  const rows = page.rows.slice(0, requestedLimit);
+  const nextOffset = pagination.offset + rows.length;
+  if (page.total !== null) {
+    return {
+      rows,
+      hasNextPage: nextOffset < page.total,
+      nextOffset,
+      total: page.total
+    };
+  }
+  const hasNextPage = page.rows.length > requestedLimit || probeLimit === requestedLimit && page.rows.length === requestedLimit && toApiPage(await fetchPage({ limit: 1, offset: nextOffset })).rows.length > 0;
+  return { rows, hasNextPage, nextOffset, total: null };
+}
+function cleanQuery(query) {
+  return Object.fromEntries(
+    Object.entries(query).filter(
+      ([, value]) => value !== void 0 && value !== null && value !== ""
+    )
+  );
+}
+
+export { DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE, cleanQuery, createOffsetPagination, fetchOffsetPage, getPageIndex };

package/dist/chunk-F5KXJCCJ.mjs

@@ -0,0 +1 @@
+

package/dist/chunk-JABLSOQN.mjs

@@ -0,0 +1,114 @@
+// src/format/format.ts
+var DEFAULT_PLACEHOLDER = "\u2014";
+var numberFormats = /* @__PURE__ */ new Map();
+var dateFormats = /* @__PURE__ */ new Map();
+function numberFormat(locale, options) {
+  const key = `${locale}|${options ? JSON.stringify(options) : ""}`;
+  let format = numberFormats.get(key);
+  if (!format) {
+    format = new Intl.NumberFormat(locale, options);
+    numberFormats.set(key, format);
+  }
+  return format;
+}
+function dateFormat(locale, options) {
+  const key = `${locale}|${JSON.stringify(options)}`;
+  let format = dateFormats.get(key);
+  if (!format) {
+    format = new Intl.DateTimeFormat(locale, options);
+    dateFormats.set(key, format);
+  }
+  return format;
+}
+function minorUnitScale(locale, currency) {
+  const digits = numberFormat(locale, { style: "currency", currency }).resolvedOptions().maximumFractionDigits ?? 2;
+  return 10 ** digits;
+}
+function toDate(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+function isBlank(value) {
+  return value === null || value === void 0 || value === "";
+}
+function formatCurrency(minorUnits, { locale, currency, placeholder = DEFAULT_PLACEHOLDER }) {
+  if (!currency) {
+    throw new Error(
+      "formatCurrency requires a `currency`. Set it on NajmFormatProvider or pass it here."
+    );
+  }
+  if (minorUnits === null || minorUnits === void 0) return placeholder;
+  if (!Number.isSafeInteger(minorUnits)) return placeholder;
+  return numberFormat(locale, {
+    style: "currency",
+    currency
+  }).format(minorUnits / minorUnitScale(locale, currency));
+}
+function formatNumber(value, { locale, placeholder = DEFAULT_PLACEHOLDER }, options) {
+  if (value === null || value === void 0 || !Number.isFinite(value)) {
+    return placeholder;
+  }
+  return numberFormat(locale, options).format(value);
+}
+function formatPercent(value, config, fractionDigits = 0) {
+  return formatNumber(value, config, {
+    style: "percent",
+    minimumFractionDigits: fractionDigits,
+    maximumFractionDigits: fractionDigits
+  });
+}
+function formatDate(value, {
+  locale,
+  timeZone,
+  placeholder = DEFAULT_PLACEHOLDER
+}, options = { dateStyle: "medium" }) {
+  if (isBlank(value)) return placeholder;
+  const date = toDate(value);
+  if (!date) return placeholder;
+  return dateFormat(locale, { ...options, timeZone }).format(date);
+}
+function formatDateTime(value, config, options = {
+  dateStyle: "short",
+  timeStyle: "short"
+}) {
+  return formatDate(value, config, options);
+}
+function formatTime(value, config) {
+  return formatDate(value, config, { timeStyle: "short" });
+}
+var RELATIVE_UNITS = [
+  ["year", 31536e6],
+  ["month", 2592e6],
+  ["day", 864e5],
+  ["hour", 36e5],
+  ["minute", 6e4],
+  ["second", 1e3]
+];
+function formatRelativeTime(value, { locale, placeholder = DEFAULT_PLACEHOLDER }, now = Date.now()) {
+  if (isBlank(value)) return placeholder;
+  const date = toDate(value);
+  if (!date) return placeholder;
+  const elapsed = date.getTime() - (now instanceof Date ? now.getTime() : now);
+  const format = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+  for (const [unit, ms] of RELATIVE_UNITS) {
+    if (Math.abs(elapsed) >= ms) {
+      return format.format(Math.trunc(elapsed / ms), unit);
+    }
+  }
+  return format.format(0, "second");
+}
+function humanizeToken(value) {
+  return value.trim().replace(/[_-]+/g, " ").replace(/\s+/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function localDateInput(date = /* @__PURE__ */ new Date()) {
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+function slugify(value, { upperCase = false, maxLength = 160 } = {}) {
+  const normalized = value.normalize("NFD").replace(/[\u0300-\u036f]/g, "").trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, maxLength);
+  const slug = normalized || crypto.randomUUID().slice(0, 8);
+  return upperCase ? slug.toUpperCase() : slug;
+}
+
+export { DEFAULT_PLACEHOLDER, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, formatRelativeTime, formatTime, humanizeToken, localDateInput, slugify };

package/dist/chunk-OUS7OYVA.mjs

@@ -0,0 +1,54 @@
+import { useCallback, useSyncExternalStore } from 'react';
+
+// src/hooks/useMediaQuery.ts
+function useMediaQuery(query, serverSnapshot = false) {
+  const subscribe = useCallback(
+    (onStoreChange) => {
+      const media = window.matchMedia(query);
+      media.addEventListener("change", onStoreChange);
+      return () => media.removeEventListener("change", onStoreChange);
+    },
+    [query]
+  );
+  return useSyncExternalStore(
+    subscribe,
+    () => window.matchMedia(query).matches,
+    () => serverSnapshot
+  );
+}
+var DEFAULT_CARD_BREAKPOINT = 1024;
+function useCardViewport(breakpoint = DEFAULT_CARD_BREAKPOINT) {
+  return useMediaQuery(`(max-width: ${breakpoint - 1}px)`);
+}
+function useDesktopTableMode(breakpoint = DEFAULT_CARD_BREAKPOINT) {
+  return useMediaQuery(`(min-width: ${breakpoint}px)`) ? "table" : "cards";
+}
+
+// src/components/table/cardPagination.ts
+var DEFAULT_CARD_PAGINATION_KEY_PREFIX = "common.pagination";
+function buildCardPaginationLabels(t, prefix) {
+  const scope = prefix ?? DEFAULT_CARD_PAGINATION_KEY_PREFIX;
+  return {
+    loadMoreError: t(`${scope}.loadMoreError`),
+    retryLabel: t(`${scope}.retryLoadMore`),
+    itemsLoaded: (count) => t(`${scope}.itemsLoaded`, { count })
+  };
+}
+function createCardPagination(state, labels = {}, prefix) {
+  const mode = state.mode ?? (state.cardViewport ? "infinite" : "paged");
+  if (mode === "paged") return { mode: "paged" };
+  if (mode === "all") return { mode: "all" };
+  const resolved = typeof labels === "function" ? buildCardPaginationLabels(labels, prefix) : labels;
+  return {
+    mode: "infinite",
+    hasNextPage: state.hasNextPage,
+    loadingMore: state.loadingMore,
+    loadMoreError: state.loadMoreError ? resolved.loadMoreError : void 0,
+    onLoadMore: state.onLoadMore,
+    retryLabel: resolved.retryLabel,
+    loadMoreErrorLabel: resolved.loadMoreError,
+    itemsLoadedLabel: resolved.itemsLoaded
+  };
+}
+
+export { DEFAULT_CARD_BREAKPOINT, DEFAULT_CARD_PAGINATION_KEY_PREFIX, buildCardPaginationLabels, createCardPagination, useCardViewport, useDesktopTableMode, useMediaQuery };

package/dist/{chunk-QOP7L6RD.mjs → chunk-PCPMAEKP.mjs}

@@ -1,4 +1,5 @@
 import { useNajmPreferencesContext } from './chunk-USZUOJMK.mjs';
+import { humanizeToken, DEFAULT_PLACEHOLDER, formatRelativeTime, formatTime, formatDateTime, formatDate, formatPercent, formatNumber, formatCurrency } from './chunk-JABLSOQN.mjs';
 import * as React from 'react';
 import { createContext, useContext, useMemo, useState, useCallback } from 'react';
 import { jsx } from 'react/jsx-runtime';
@@ -62,109 +63,6 @@ function NBrandingStateProvider({
 }
 function noop() {
 }
-
-// src/format/format.ts
-var DEFAULT_PLACEHOLDER = "\u2014";
-var numberFormats = /* @__PURE__ */ new Map();
-var dateFormats = /* @__PURE__ */ new Map();
-function numberFormat(locale, options) {
-  const key = `${locale}|${options ? JSON.stringify(options) : ""}`;
-  let format = numberFormats.get(key);
-  if (!format) {
-    format = new Intl.NumberFormat(locale, options);
-    numberFormats.set(key, format);
-  }
-  return format;
-}
-function dateFormat(locale, options) {
-  const key = `${locale}|${JSON.stringify(options)}`;
-  let format = dateFormats.get(key);
-  if (!format) {
-    format = new Intl.DateTimeFormat(locale, options);
-    dateFormats.set(key, format);
-  }
-  return format;
-}
-function minorUnitScale(locale, currency) {
-  const digits = numberFormat(locale, { style: "currency", currency }).resolvedOptions().maximumFractionDigits ?? 2;
-  return 10 ** digits;
-}
-function toDate(value) {
-  const date = value instanceof Date ? value : new Date(value);
-  return Number.isNaN(date.getTime()) ? null : date;
-}
-function isBlank(value) {
-  return value === null || value === void 0 || value === "";
-}
-function formatCurrency(minorUnits, { locale, currency, placeholder = DEFAULT_PLACEHOLDER }) {
-  if (!currency) {
-    throw new Error(
-      "formatCurrency requires a `currency`. Set it on NajmFormatProvider or pass it here."
-    );
-  }
-  if (minorUnits === null || minorUnits === void 0) return placeholder;
-  if (!Number.isSafeInteger(minorUnits)) return placeholder;
-  return numberFormat(locale, {
-    style: "currency",
-    currency
-  }).format(minorUnits / minorUnitScale(locale, currency));
-}
-function formatNumber(value, { locale, placeholder = DEFAULT_PLACEHOLDER }, options) {
-  if (value === null || value === void 0 || !Number.isFinite(value)) {
-    return placeholder;
-  }
-  return numberFormat(locale, options).format(value);
-}
-function formatPercent(value, config, fractionDigits = 0) {
-  return formatNumber(value, config, {
-    style: "percent",
-    minimumFractionDigits: fractionDigits,
-    maximumFractionDigits: fractionDigits
-  });
-}
-function formatDate(value, {
-  locale,
-  timeZone,
-  placeholder = DEFAULT_PLACEHOLDER
-}, options = { dateStyle: "medium" }) {
-  if (isBlank(value)) return placeholder;
-  const date = toDate(value);
-  if (!date) return placeholder;
-  return dateFormat(locale, { ...options, timeZone }).format(date);
-}
-function formatDateTime(value, config, options = {
-  dateStyle: "short",
-  timeStyle: "short"
-}) {
-  return formatDate(value, config, options);
-}
-function formatTime(value, config) {
-  return formatDate(value, config, { timeStyle: "short" });
-}
-var RELATIVE_UNITS = [
-  ["year", 31536e6],
-  ["month", 2592e6],
-  ["day", 864e5],
-  ["hour", 36e5],
-  ["minute", 6e4],
-  ["second", 1e3]
-];
-function formatRelativeTime(value, { locale, placeholder = DEFAULT_PLACEHOLDER }, now = Date.now()) {
-  if (isBlank(value)) return placeholder;
-  const date = toDate(value);
-  if (!date) return placeholder;
-  const elapsed = date.getTime() - (now instanceof Date ? now.getTime() : now);
-  const format = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
-  for (const [unit, ms] of RELATIVE_UNITS) {
-    if (Math.abs(elapsed) >= ms) {
-      return format.format(Math.trunc(elapsed / ms), unit);
-    }
-  }
-  return format.format(0, "second");
-}
-function humanizeToken(value) {
-  return value.trim().replace(/[_-]+/g, " ").replace(/\s+/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
-}
 var NajmFormatContext = React.createContext(
   null
 );
@@ -215,4 +113,4 @@ function useNajmFormat() {
   return value;
 }
 
-export { DEFAULT_PLACEHOLDER, NBrandingProvider, NBrandingStateProvider, NajmFormatProvider, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, formatRelativeTime, formatTime, humanizeToken, normalizeBranding, useNBranding, useNBrandingEditor, useNajmFormat, useNajmFormatContext };
+export { NBrandingProvider, NBrandingStateProvider, NajmFormatProvider, normalizeBranding, useNBranding, useNBrandingEditor, useNajmFormat, useNajmFormatContext };

package/dist/format.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Locale-aware value formatting.
+ *
+ * Pure functions with no React and no DOM: every input arrives through
+ * `NajmFormatConfig`. `NajmFormatProvider` binds them to the live locale and
+ * time zone, and is what an application normally uses — these are exported for
+ * the server, where there is no context to read.
+ */
+/** Rendered in place of a value that is absent or not formattable. */
+declare const DEFAULT_PLACEHOLDER = "\u2014";
+interface NajmFormatConfig {
+    /** BCP 47 tag handed to `Intl`, e.g. `"fr-MA"`. */
+    locale: string;
+    /**
+     * IANA zone every date is rendered in. Omitted means the host zone, which is
+     * the runtime's guess rather than the user's preference — supply it.
+     */
+    timeZone?: string;
+    /** ISO 4217 code for `formatCurrency`, e.g. `"MAD"`. */
+    currency?: string;
+    /** Defaults to an em dash. */
+    placeholder?: string;
+}
+/**
+ * Formats an integer count of minor units — cents, centimes — as currency.
+ *
+ * Minor units are the input because money that survives a round trip is an
+ * integer; a major-unit float cannot represent 0.1 exactly and has no business
+ * in a ledger. A non-integer input is refused rather than rounded, since at
+ * this layer it means the caller has already lost precision upstream.
+ */
+declare function formatCurrency(minorUnits: number | null | undefined, { locale, currency, placeholder }: NajmFormatConfig): string;
+declare function formatNumber(value: number | null | undefined, { locale, placeholder }: NajmFormatConfig, options?: Intl.NumberFormatOptions): string;
+declare function formatPercent(value: number | null | undefined, config: NajmFormatConfig, fractionDigits?: number): string;
+declare function formatDate(value: Date | number | string | null | undefined, { locale, timeZone, placeholder, }: NajmFormatConfig, options?: Intl.DateTimeFormatOptions): string;
+declare function formatDateTime(value: Date | number | string | null | undefined, config: NajmFormatConfig, options?: Intl.DateTimeFormatOptions): string;
+declare function formatTime(value: Date | number | string | null | undefined, config: NajmFormatConfig): string;
+/**
+ * Renders a timestamp as distance from now — "3 days ago", "in 2 hours".
+ *
+ * Time zone is not a parameter: an elapsed duration is the same in every zone.
+ */
+declare function formatRelativeTime(value: Date | number | string | null | undefined, { locale, placeholder }: NajmFormatConfig, now?: Date | number): string;
+/**
+ * Turns a machine token into readable text: `out_for_delivery` → `Out For
+ * Delivery`.
+ *
+ * The fallback for a value with no catalog entry, not a substitute for one.
+ * Anything user-visible and known in advance belongs in the translations.
+ */
+declare function humanizeToken(value: string): string;
+/**
+ * Today as `YYYY-MM-DD` in the host's zone, for `<input type="date">`.
+ *
+ * Not `toISOString().slice(0, 10)`, which is the same line everyone writes and
+ * is wrong west of UTC for the first hours of the day: it converts to UTC
+ * first, so a date picker in Casablanca opens on tomorrow. The parts are read
+ * off the local calendar instead.
+ *
+ * Deliberately host-zone rather than preference-zone. This produces the value a
+ * date *input* round-trips, and that control is bound to the machine the user
+ * is typing on; `formatDate` is what renders a date for reading.
+ */
+declare function localDateInput(date?: Date): string;
+interface SlugifyOptions {
+    /** Uppercases the result, for an identifier conventionally read in caps. */
+    upperCase?: boolean;
+    /** Longest slug produced, before the case change. Defaults to 160. */
+    maxLength?: number;
+}
+/**
+ * Turns a label into a URL- and identifier-safe token: `Épicerie Fine` →
+ * `epicerie-fine`.
+ *
+ * Accents are folded rather than dropped. Stripping them outright is the usual
+ * one-liner and it silently eats letters — `Épicerie` becomes `picerie` — which
+ * is a poor slug in exactly the languages most likely to need one.
+ *
+ * A value with nothing to transliterate — Arabic or CJK, where folding has no
+ * ASCII to fall back to — yields a random token rather than an empty string.
+ * Empty is never a usable slug, and returning one pushes the failure to a
+ * uniqueness constraint far from the cause.
+ */
+declare function slugify(value: string, { upperCase, maxLength }?: SlugifyOptions): string;
+
+export { DEFAULT_PLACEHOLDER, type NajmFormatConfig, type SlugifyOptions, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, formatRelativeTime, formatTime, humanizeToken, localDateInput, slugify };

package/dist/format.mjs

@@ -0,0 +1,2 @@
+import './chunk-F5KXJCCJ.mjs';
+export { DEFAULT_PLACEHOLDER, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, formatRelativeTime, formatTime, humanizeToken, localDateInput, slugify } from './chunk-JABLSOQN.mjs';