najm-kit 2.7.1 → 2.7.2

package/CHANGELOG.md

@@ -1,112 +1,112 @@
-# Changelog
-
-## 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.
-- `logo` accepts a render prop, `({ collapsed, isMobile }) => ReactNode`, alongside the existing node. It receives the state the sidebar actually resolved — including whatever `autoCollapseAt` decided — which consumers previously had to approximate with their own responsive classes, guessing at a breakpoint the sidebar had already computed. The mobile drawer always reports `collapsed: false`, matching how it renders. Exported as `SidebarLogoRender`.
-
-## 2.6.1
-
-- Fixed the non-card `NPageHeader` bleed never taking effect. 2.6.0 cancelled the page padding with the Tailwind utilities `-mt-[var(--najm-section-gap,0px)]` and `-mx-[var(--najm-page-gutter,0px)]`, which only work if the consuming app's Tailwind build happens to emit those arbitrary classes — they exist nowhere but inside this package's bundle, so a consumer could load a stylesheet without them and the header stayed exactly where it was. The offsets are inline styles now and no longer depend on the consumer's CSS pipeline.
-
-## 2.6.0
-
-- Added `NThemePresets`, and wired it into `NThemeCustomizer` through `presets`, `selectedPresetId`, `presetsStatus`, `savedDesign`, `onPresetSelect`, `onPresetSave`, `onPresetDelete`, and `presetLabels`. The picker renders only when a host supplies both `presets` and `onPresetSelect`. It is presentational: the host owns where presets live and what saving one means, and selecting a row hands the design back so it can be previewed before anything is stored. Each row draws a swatch strip from the design's own `sidebar`, `primary`, `secondary`, `accent`, and `background` tokens; the selected row's check sits left in the success colour and per-row delete sits right. Omit `onPresetSave` or `onPresetDelete` to hide those controls. Deleting is pointer-only — Radix owns roving focus inside the listbox.
-- **`NPageHeader` in non-card mode is now flush.** It rendered as a full-bleed bar (`border-b`, no radius) but still sat inside the padding `NPageLayout` applies, so it floated below and inside the page gutter and its bottom rule never met the sidebar header's. It now cancels that padding, and its base height goes `min-h-12` → `min-h-14` to match `NSidebarHeader`. **Non-card page headers move up and out to the page edges, and grow 8px below `sm`.** Card mode is unchanged.
-- `NPageLayout` publishes its resolved spacing as `--najm-page-gutter` and `--najm-section-gap`. Descendants could not previously cancel the page padding: a design config resolves the gutter to a literal, so the pre-existing `--page-gutter` / `--section-gap` variables only ever held the fallbacks. Full-bleed children should negate these, with `0px` fallbacks so they stay inert outside `NPageLayout`.
-- Fixed `SelectInput` discarding `SelectItemType.icon`. The prop was declared but `renderItems` rendered the label alone, so every per-item icon was silently dropped. Items with an icon now render it before a truncating label; items without one are unchanged.
-
-## 2.5.0
-
-- Added `NTableDefaultsProvider`, so an application supplies `paginationLabels` once instead of at every table. Labels merge per key, most specific first: a table's own `paginationLabels` override the provider's for the keys it sets, the provider covers the rest, and anything neither supplies falls back to the packaged English. Also exports `useNTableDefaults` and the `NTableDefaults` type.
-- `value` is passed through the provider unmemoized; memoize it in the caller, or every table below re-renders with the shell.
-
-## 2.4.0
-
-- `NTablePagination` renders numbered page buttons instead of `Page X of Y`. The window shows the first and last page, the current page, and one page either side, collapsing the rest into at most two gaps. The slot count is constant for any result longer than the window, so the bar does not change width as the reader pages through it, and a gap never stands in for a single page — that slot goes to the page instead.
-- Added `paginationVariant`, defaulting to `"numbered"`. Pass `"compact"` to keep the previous position text with first/previous/next/last controls. **This changes the default appearance of every paginated `NTable`.**
-- The numbered variant drops the first/last double chevrons, because page 1 and page N are now single-click targets of their own. Previous and next remain. The compact variant is unchanged.
-- Numbered pages fall back to compact on their own when the page count is not trustworthy — that is, under `manualPagination` with no `pageCount` supplied, where TanStack infers a count from the rows it happens to hold rather than from a result total. Numbering that would invite clicks on pages that may not exist is not rendered.
-- Below the `sm` breakpoint the numbers give way to the position text; seven page buttons plus the rows-per-page select do not fit a phone.
-- Added `paginationLabels` so the bar can be localized: `rowsPerPage`, `pagination`, `goToPage`, `currentPage`, `firstPage`, `previousPage`, `nextPage`, `lastPage`, `pageOf`, and `rowsSelected`. All optional, all falling back to the previous English strings.
-- Pagination chevrons now mirror under `dir="rtl"`. They previously pointed against the reading direction in right-to-left layouts.
-- The page controls are wrapped in a labelled `nav`, and the current page carries `aria-current="page"`.
-- Exported `buildPageItems` and `NTablePageItem` for consumers that need the same windowing outside the table.
-
-## 2.2.1
-
-- Fixed a regression in 2.2.0: the dynamic page size reported under `manualPagination` could oscillate. Card row height is measured from rendered cards, so it grows as images decode; feeding that back into the page size refetched, re-rendered, re-measured, and refetched again. A list visibly settled from one page size to another with the loading skeleton flashing twice. The report is now allowed once per container geometry, which does not depend on the rows inside it, so it terminates. A resize still re-arms it, and the debounce still waits for the measurement to settle before reporting.
-
-## 2.2.0
-
-- Added `cardPagination` mode `infinite`: card lists continue on scroll instead of behind a button. No control and no end-of-list element render while the list is healthy. The continuation button appears only after an append failure, as the retry target.
-- Infinite continuation is owned by `NTableCards`, so the sentinel lives inside the card list's own `NajmScroll` viewport and uses it as the observer root. An appending page renders shaped card placeholders at the grid tail rather than a spinner in a fixed strip, and the polite `aria-live` announcement of appended row counts is preserved.
-- `cardPagination: { mode: "all" }` is now honored in table mode as well as cards: every supplied row renders and no pagination controls are shown.
-- `dynamicHeight` now takes effect under `manualPagination`. The measured page size is reported through the ordinary `onPaginationChange` callback, debounced, so server-paginated tables fill their container while the consumer keeps ownership of fetching. `maxHeight` stays caller-owned under manual pagination, and no page size is reported before the first measurement.
-- Added `calculateCardPageSize`, floored to whole card rows, published as `calculatedCardPageSize`. A card grid page no longer ends in a ragged partial row. This deliberately differs from `calculateCardSkeletonCount`, which ceils because overfilling placeholders is harmless.
-- Removed the deprecated `baseUrl` compiler option from the package tsconfig; `paths` resolves relative to the config file.
-
-## 2.1.56
-
-- Honor `showIcon` on NTable `select` and `combobox` filters. The leading filter icon is still shown by default; pass `showIcon: false` on a filter to hide it.
-
-## 2.1.55
-
-- Added controlled remote-search and loading-state props to `ComboboxInput` and `FormInput type="combobox"` while preserving client filtering by default.
-
-## 2.1.53 - 2026-08-05
-
-- Add typed `NBarChart`, `NLineChart`, `NPieChart`, and `NStatusBreakdown`
-  components with caller-formatted generic data, accessible summaries, empty
-  states, responsive RTL-safe layouts, and shape-matched loading skeletons.
-- Default chart colors to the live `--chart-1` through `--chart-5` theme
-  variables, cycle deterministically after five items, and retain explicit
-  per-series/item color overrides.
-- Add preset and numeric chart diameter contracts to `NPieChart` and
-  `NDonutCard`, including narrow-container shrinking without clipped legends.
-- Make `NDonutCard` item colors optional and add accessible loading states to
-  `NDonutCard` and `NStatCard`.
-- Add public API tests, component tests, README guidance, and playground
-  examples for the chart and loading contracts.
-
-## 2.1.49 - 2026-08-04
-
-### ImageInput and AvatarInput
-
-- Add `previewAlt`, `fallbackImage`, `fallbackAlt`, `unavailableContent`,
-  `imageClassName`, `onPreviewError`, `replaceAriaLabel`, and `clearAriaLabel`
-  to `ImageInputProps`. `AvatarInput` forwards every new prop unchanged.
-- Preview sources resolve in this priority order: `value`, `fallbackImage`,
-  `defaultImage`. Candidate URLs are deduplicated so a failing primary URL is
-  never retried through multiple stages. When every candidate fails, the
-  broken `<img>` is unmounted and `unavailableContent` (or a neutral default)
-  is rendered in its place.
-- `imageVersion` is appended safely to relative, absolute, queried, and
-  fragmented URLs. `data:`, `blob:`, `javascript:`, and `file:` URLs are
-  left unchanged.
-- Expose `data-image-input-state="empty" | "preview" | "fallback" | "unavailable"`
-  on the preview container for styling, testing, and consumer diagnostics.
-- File selection is race-safe: stale `FileReader` completions cannot replace
-  a newer value. Object URLs created by the component are tracked so
-  consumer-owned blob URLs are never revoked.
-- Replace and clear controls are real `<button>` elements, are reachable
-  with the keyboard, and stay visible on touch and coarse-pointer devices.
-  Only on `(hover: hover) and (pointer: fine)` desktops do the controls fall
-  back to a hover/focus reveal. `focus-visible` always restores visibility.
-- Use logical positioning (`end-*`) so the clear button works correctly in
-  RTL layouts.
-- Re-export `ImageInputPreviewSource` and `ImageInputPreviewError` from
-  `najm-kit/components/inputs` and the package root.
-
-## 2.1.48 - 2026-08-04
-
-- Keep responsive card row actions visible on phone, tablet, and touch input,
-  while retaining hover and keyboard-focus reveal on fine-pointer desktops.
-- Size table and card loading skeletons from the measured body and active grid,
-  and keep loading borders, radius, color, and shadow aligned with loaded
-  surfaces.
-- Add the exported `NTableCardPagination` and `NTableLoadMorePagination`
-  contracts for paged, complete supplied-data, and explicit server-backed Load
-  more card presentation, including guarded append/retry behavior and accessible
-  loading, result, error, and terminal feedback.
+# Changelog
+
+## 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.
+- `logo` accepts a render prop, `({ collapsed, isMobile }) => ReactNode`, alongside the existing node. It receives the state the sidebar actually resolved — including whatever `autoCollapseAt` decided — which consumers previously had to approximate with their own responsive classes, guessing at a breakpoint the sidebar had already computed. The mobile drawer always reports `collapsed: false`, matching how it renders. Exported as `SidebarLogoRender`.
+
+## 2.6.1
+
+- Fixed the non-card `NPageHeader` bleed never taking effect. 2.6.0 cancelled the page padding with the Tailwind utilities `-mt-[var(--najm-section-gap,0px)]` and `-mx-[var(--najm-page-gutter,0px)]`, which only work if the consuming app's Tailwind build happens to emit those arbitrary classes — they exist nowhere but inside this package's bundle, so a consumer could load a stylesheet without them and the header stayed exactly where it was. The offsets are inline styles now and no longer depend on the consumer's CSS pipeline.
+
+## 2.6.0
+
+- Added `NThemePresets`, and wired it into `NThemeCustomizer` through `presets`, `selectedPresetId`, `presetsStatus`, `savedDesign`, `onPresetSelect`, `onPresetSave`, `onPresetDelete`, and `presetLabels`. The picker renders only when a host supplies both `presets` and `onPresetSelect`. It is presentational: the host owns where presets live and what saving one means, and selecting a row hands the design back so it can be previewed before anything is stored. Each row draws a swatch strip from the design's own `sidebar`, `primary`, `secondary`, `accent`, and `background` tokens; the selected row's check sits left in the success colour and per-row delete sits right. Omit `onPresetSave` or `onPresetDelete` to hide those controls. Deleting is pointer-only — Radix owns roving focus inside the listbox.
+- **`NPageHeader` in non-card mode is now flush.** It rendered as a full-bleed bar (`border-b`, no radius) but still sat inside the padding `NPageLayout` applies, so it floated below and inside the page gutter and its bottom rule never met the sidebar header's. It now cancels that padding, and its base height goes `min-h-12` → `min-h-14` to match `NSidebarHeader`. **Non-card page headers move up and out to the page edges, and grow 8px below `sm`.** Card mode is unchanged.
+- `NPageLayout` publishes its resolved spacing as `--najm-page-gutter` and `--najm-section-gap`. Descendants could not previously cancel the page padding: a design config resolves the gutter to a literal, so the pre-existing `--page-gutter` / `--section-gap` variables only ever held the fallbacks. Full-bleed children should negate these, with `0px` fallbacks so they stay inert outside `NPageLayout`.
+- Fixed `SelectInput` discarding `SelectItemType.icon`. The prop was declared but `renderItems` rendered the label alone, so every per-item icon was silently dropped. Items with an icon now render it before a truncating label; items without one are unchanged.
+
+## 2.5.0
+
+- Added `NTableDefaultsProvider`, so an application supplies `paginationLabels` once instead of at every table. Labels merge per key, most specific first: a table's own `paginationLabels` override the provider's for the keys it sets, the provider covers the rest, and anything neither supplies falls back to the packaged English. Also exports `useNTableDefaults` and the `NTableDefaults` type.
+- `value` is passed through the provider unmemoized; memoize it in the caller, or every table below re-renders with the shell.
+
+## 2.4.0
+
+- `NTablePagination` renders numbered page buttons instead of `Page X of Y`. The window shows the first and last page, the current page, and one page either side, collapsing the rest into at most two gaps. The slot count is constant for any result longer than the window, so the bar does not change width as the reader pages through it, and a gap never stands in for a single page — that slot goes to the page instead.
+- Added `paginationVariant`, defaulting to `"numbered"`. Pass `"compact"` to keep the previous position text with first/previous/next/last controls. **This changes the default appearance of every paginated `NTable`.**
+- The numbered variant drops the first/last double chevrons, because page 1 and page N are now single-click targets of their own. Previous and next remain. The compact variant is unchanged.
+- Numbered pages fall back to compact on their own when the page count is not trustworthy — that is, under `manualPagination` with no `pageCount` supplied, where TanStack infers a count from the rows it happens to hold rather than from a result total. Numbering that would invite clicks on pages that may not exist is not rendered.
+- Below the `sm` breakpoint the numbers give way to the position text; seven page buttons plus the rows-per-page select do not fit a phone.
+- Added `paginationLabels` so the bar can be localized: `rowsPerPage`, `pagination`, `goToPage`, `currentPage`, `firstPage`, `previousPage`, `nextPage`, `lastPage`, `pageOf`, and `rowsSelected`. All optional, all falling back to the previous English strings.
+- Pagination chevrons now mirror under `dir="rtl"`. They previously pointed against the reading direction in right-to-left layouts.
+- The page controls are wrapped in a labelled `nav`, and the current page carries `aria-current="page"`.
+- Exported `buildPageItems` and `NTablePageItem` for consumers that need the same windowing outside the table.
+
+## 2.2.1
+
+- Fixed a regression in 2.2.0: the dynamic page size reported under `manualPagination` could oscillate. Card row height is measured from rendered cards, so it grows as images decode; feeding that back into the page size refetched, re-rendered, re-measured, and refetched again. A list visibly settled from one page size to another with the loading skeleton flashing twice. The report is now allowed once per container geometry, which does not depend on the rows inside it, so it terminates. A resize still re-arms it, and the debounce still waits for the measurement to settle before reporting.
+
+## 2.2.0
+
+- Added `cardPagination` mode `infinite`: card lists continue on scroll instead of behind a button. No control and no end-of-list element render while the list is healthy. The continuation button appears only after an append failure, as the retry target.
+- Infinite continuation is owned by `NTableCards`, so the sentinel lives inside the card list's own `NajmScroll` viewport and uses it as the observer root. An appending page renders shaped card placeholders at the grid tail rather than a spinner in a fixed strip, and the polite `aria-live` announcement of appended row counts is preserved.
+- `cardPagination: { mode: "all" }` is now honored in table mode as well as cards: every supplied row renders and no pagination controls are shown.
+- `dynamicHeight` now takes effect under `manualPagination`. The measured page size is reported through the ordinary `onPaginationChange` callback, debounced, so server-paginated tables fill their container while the consumer keeps ownership of fetching. `maxHeight` stays caller-owned under manual pagination, and no page size is reported before the first measurement.
+- Added `calculateCardPageSize`, floored to whole card rows, published as `calculatedCardPageSize`. A card grid page no longer ends in a ragged partial row. This deliberately differs from `calculateCardSkeletonCount`, which ceils because overfilling placeholders is harmless.
+- Removed the deprecated `baseUrl` compiler option from the package tsconfig; `paths` resolves relative to the config file.
+
+## 2.1.56
+
+- Honor `showIcon` on NTable `select` and `combobox` filters. The leading filter icon is still shown by default; pass `showIcon: false` on a filter to hide it.
+
+## 2.1.55
+
+- Added controlled remote-search and loading-state props to `ComboboxInput` and `FormInput type="combobox"` while preserving client filtering by default.
+
+## 2.1.53 - 2026-08-05
+
+- Add typed `NBarChart`, `NLineChart`, `NPieChart`, and `NStatusBreakdown`
+  components with caller-formatted generic data, accessible summaries, empty
+  states, responsive RTL-safe layouts, and shape-matched loading skeletons.
+- Default chart colors to the live `--chart-1` through `--chart-5` theme
+  variables, cycle deterministically after five items, and retain explicit
+  per-series/item color overrides.
+- Add preset and numeric chart diameter contracts to `NPieChart` and
+  `NDonutCard`, including narrow-container shrinking without clipped legends.
+- Make `NDonutCard` item colors optional and add accessible loading states to
+  `NDonutCard` and `NStatCard`.
+- Add public API tests, component tests, README guidance, and playground
+  examples for the chart and loading contracts.
+
+## 2.1.49 - 2026-08-04
+
+### ImageInput and AvatarInput
+
+- Add `previewAlt`, `fallbackImage`, `fallbackAlt`, `unavailableContent`,
+  `imageClassName`, `onPreviewError`, `replaceAriaLabel`, and `clearAriaLabel`
+  to `ImageInputProps`. `AvatarInput` forwards every new prop unchanged.
+- Preview sources resolve in this priority order: `value`, `fallbackImage`,
+  `defaultImage`. Candidate URLs are deduplicated so a failing primary URL is
+  never retried through multiple stages. When every candidate fails, the
+  broken `<img>` is unmounted and `unavailableContent` (or a neutral default)
+  is rendered in its place.
+- `imageVersion` is appended safely to relative, absolute, queried, and
+  fragmented URLs. `data:`, `blob:`, `javascript:`, and `file:` URLs are
+  left unchanged.
+- Expose `data-image-input-state="empty" | "preview" | "fallback" | "unavailable"`
+  on the preview container for styling, testing, and consumer diagnostics.
+- File selection is race-safe: stale `FileReader` completions cannot replace
+  a newer value. Object URLs created by the component are tracked so
+  consumer-owned blob URLs are never revoked.
+- Replace and clear controls are real `<button>` elements, are reachable
+  with the keyboard, and stay visible on touch and coarse-pointer devices.
+  Only on `(hover: hover) and (pointer: fine)` desktops do the controls fall
+  back to a hover/focus reveal. `focus-visible` always restores visibility.
+- Use logical positioning (`end-*`) so the clear button works correctly in
+  RTL layouts.
+- Re-export `ImageInputPreviewSource` and `ImageInputPreviewError` from
+  `najm-kit/components/inputs` and the package root.
+
+## 2.1.48 - 2026-08-04
+
+- Keep responsive card row actions visible on phone, tablet, and touch input,
+  while retaining hover and keyboard-focus reveal on fine-pointer desktops.
+- Size table and card loading skeletons from the measured body and active grid,
+  and keep loading borders, radius, color, and shadow aligned with loaded
+  surfaces.
+- Add the exported `NTableCardPagination` and `NTableLoadMorePagination`
+  contracts for paged, complete supplied-data, and explicit server-backed Load
+  more card presentation, including guarded append/retry behavior and accessible
+  loading, result, error, and terminal feedback.

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

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
-import React__default, { ReactNode } from 'react';
+import React__default from 'react';
+import { a as NTablePaginationLabels, e as NajmTranslate } from './paginationLabels-CY2PvbMj.js';
 
 type NajmMode = 'light' | 'dark';
 type NajmAccent = 'neutral' | 'emerald' | 'green' | 'slate' | 'blue' | 'violet';
@@ -160,121 +161,6 @@ declare const NAJM_COMPONENT_NAMES: readonly NajmComponentName[];
 declare const RADIUS_VALUE_MAP: Record<string, string>;
 declare function resolveRadiusValue(radius: NajmComponentRadius | undefined): string | undefined;
 
-/**
- * How the page controls present position within the result.
- *
- * `numbered` renders a windowed list of page buttons. `compact` renders the
- * `Page X of Y` text with first/previous/next/last controls.
- *
- * `numbered` needs a trustworthy page count. Under `manualPagination` that
- * means the application must pass a `pageCount` derived from a real result
- * total, or — when its endpoint reports no total — pass `hasNextPage` and no
- * `pageCount` at all, which renders the unbounded bar described on the NTable
- * prop. With neither, the bar falls back to `compact` on its own rather than
- * inviting clicks on pages that may not exist.
- *
- * What it must never be handed is a `pageCount` that is really a lower bound,
- * such as `pageIndex + 2`. That reads as a two-page result on page one and a
- * three-page result on page two, so the bar grows a number per click with
- * nothing to say why. NTable warns in development when it catches a count
- * moving in lockstep with the page index.
- */
-type NTablePaginationVariant = "numbered" | "compact";
-/**
- * Accessible names and visible copy for the page controls.
- *
- * Every field is optional and falls back to English. Supply them to localize —
- * the numbered variant is mostly digits, but its controls still need names.
- */
-interface NTablePaginationLabels {
-    /** Labels the rows-per-page select. Defaults to `"Rows/page"`. */
-    rowsPerPage?: string;
-    /** Accessible name of the whole page control group. Defaults to `"Pagination"`. */
-    pagination?: string;
-    /** Accessible name for one page button, given a 1-based page. */
-    goToPage?: (page: number) => string;
-    /** Accessible name of the current page button, given a 1-based page. */
-    currentPage?: (page: number) => string;
-    firstPage?: string;
-    previousPage?: string;
-    nextPage?: string;
-    lastPage?: string;
-    /** The `compact` variant's position text, given 1-based values. */
-    pageOf?: (page: number, pageCount: number) => string;
-    /**
-     * The position text when the result has no known total, given the 1-based
-     * page. Defaults to `"Page X"` — there is no `of Y` to state, and repeating
-     * the moving lower bound there would be the same lie the numbered bar avoids.
-     */
-    pageOfUnknown?: (page: number) => string;
-    /** The selection summary, given selected and total row counts. */
-    rowsSelected?: (selected: number, total: number) => string;
-}
-interface NTableLoadMorePagination {
-    /** Render the supplied rows as one card list with an explicit continuation control. */
-    mode: "load-more";
-    /** Whether the owning application has another server page available. */
-    hasNextPage: boolean;
-    /** True while the owning application is appending the next page. */
-    loadingMore?: boolean;
-    /** A controlled append error. Existing rows remain rendered and the control becomes Retry. */
-    loadMoreError?: ReactNode;
-    /** Fetch exactly one additional page. Najm Kit never constructs or owns the request. */
-    onLoadMore: () => unknown | Promise<unknown>;
-    loadMoreLabel?: string;
-    loadingMoreLabel?: string;
-    retryLabel?: string;
-    endLabel?: string;
-    loadMoreErrorLabel?: string;
-    /** Localize the polite announcement made after appended rows arrive. */
-    itemsLoadedLabel?: (count: number) => string;
-}
-interface NTableInfinitePagination {
-    /**
-     * Render the supplied rows as one card list that continues automatically when
-     * the end of the list scrolls into view. No control and no end-of-list
-     * element are rendered while the list is healthy; the continuation button
-     * appears only after an append failure, as the retry target.
-     */
-    mode: "infinite";
-    /** Whether the owning application has another server page available. */
-    hasNextPage: boolean;
-    /** True while the owning application is appending the next page. */
-    loadingMore?: boolean;
-    /** A controlled append error. Existing rows remain rendered and Retry appears. */
-    loadMoreError?: ReactNode;
-    /** Fetch exactly one additional page. Najm Kit never constructs or owns the request. */
-    onLoadMore: () => unknown | Promise<unknown>;
-    /**
-     * Distance ahead of the list end at which the next page is requested.
-     * Defaults to `"80px"`.
-     */
-    rootMargin?: string;
-    loadingMoreLabel?: string;
-    retryLabel?: string;
-    loadMoreErrorLabel?: string;
-    /** Localize the polite announcement made after appended rows arrive. */
-    itemsLoadedLabel?: (count: number) => string;
-}
-/**
- * Presentation policy used while NTable is actually rendering cards.
- *
- * `paged` preserves the existing page controls. `all` renders every supplied
- * row without a footer, in card and table modes alike. `load-more` renders
- * every supplied row and adds a guarded, accessible continuation control.
- * `infinite` renders every supplied row and continues on scroll instead.
- *
- * Applications remain responsible for fetching, accumulating, filtering,
- * sorting, authorization, and privacy. `all` renders exactly the rows it is
- * given and never fetches, so a caller that has not loaded the whole set must
- * not select it.
- */
-type NTableCardPagination = {
-    mode?: "paged";
-} | {
-    mode: "all";
-} | NTableLoadMorePagination | NTableInfinitePagination;
-
 /**
  * Defaults every `NTable` beneath the provider inherits.
  *
@@ -360,31 +246,6 @@ declare function useNajmTheme(): Pick<NajmPreferencesContextValue, "theme" | "se
 /** The live time zone and a setter that persists through `onTimeZoneChange`. */
 declare function useNajmTimeZone(): Pick<NajmPreferencesContextValue, "timeZone" | "setTimeZone">;
 
-/**
- * The translator shape `NajmUIProvider` accepts.
- *
- * Deliberately structural rather than an import from `najm-i18n`: the kit
- * depends on no `najm-*` package, and this signature is satisfied by every
- * mainstream i18n library. The application keeps its catalog and its own
- * language provider.
- */
-type NajmTranslate = (key: string, params?: Record<string, string | number>) => string;
-declare const DEFAULT_PAGINATION_KEY_PREFIX = "common.pagination";
-/**
- * Projects a translator onto the ten pagination labels.
- *
- * Keys are `<prefix>.<field>`, matching the `NTablePaginationLabels` field
- * names one-for-one, so a catalog is readable next to the type. Interpolation
- * params are named for what they are: `page`, `pageCount`, `selected`, `total`.
- *
- * No result is inspected or second-guessed. A translator that echoes missing
- * keys will render those keys — that is the translator's contract to define,
- * and quietly swapping in English would hide the missing entry rather than
- * surface it. Applications that want the packaged English for a given label
- * should omit the key from the prefix and override it via `tableDefaults`.
- */
-declare function buildPaginationLabels(t: NajmTranslate, prefix?: string): NTablePaginationLabels;
-
 interface NajmUIProviderProps extends Omit<NajmPreferencesProviderProps, "children"> {
     children: React$1.ReactNode;
     /**
@@ -454,4 +315,4 @@ interface NajmUIProviderProps extends Omit<NajmPreferencesProviderProps, "childr
  */
 declare function NajmUIProvider({ children, design, initialDesign, className, t, paginationKeyPrefix, tableDefaults, initialTheme, initialTimeZone, onThemeChange, onTimeZoneChange, normalizeTimeZone, }: NajmUIProviderProps): react_jsx_runtime.JSX.Element;
 
-export { type NajmDensity as A, type NajmPreferencesContextValue as B, NajmPreferencesProvider as C, DEFAULT_PAGINATION_KEY_PREFIX as D, type NajmPreferencesProviderProps as E, type NajmSlotStyle as F, type NajmTranslate as G, NajmUIProvider as H, buildPaginationLabels as I, resolveRadiusValue as J, useNTableDefaults as K, useNajmPreferencesContext as L, useNajmTheme as M, type NajmUIProviderProps as N, useNajmTimeZone as O, RADIUS_VALUE_MAP as R, type NajmDesignConfig as a, type NajmThemeProviderProps as b, type NajmAppearance as c, type NajmMode as d, type NajmThemeConfig as e, type NajmAccent as f, type NajmThemeTokens as g, type NajmPreset as h, type NajmComponentName as i, type NajmComponentStyleConfig as j, type NajmComponentThemeConfig as k, type NajmTypographyConfig as l, type NajmLayoutConfig as m, type NajmVariantStyle as n, type NTablePaginationVariant as o, type NTablePaginationLabels as p, type NTableCardPagination as q, type NajmResponsiveBreakpoint as r, type NajmResponsiveValue as s, DEFAULT_TIME_ZONE as t, NAJM_COMPONENT_NAMES as u, type NTableDefaults as v, NTableDefaultsProvider as w, type NTableInfinitePagination as x, type NTableLoadMorePagination as y, type NajmComponentRadius as z };
+export { resolveRadiusValue as A, useNTableDefaults as B, useNajmPreferencesContext as C, DEFAULT_TIME_ZONE as D, useNajmTheme as E, useNajmTimeZone as F, type NajmUIProviderProps as N, RADIUS_VALUE_MAP as R, type NajmDesignConfig as a, type NajmThemeProviderProps as b, type NajmAppearance as c, type NajmMode as d, type NajmThemeConfig as e, type NajmAccent as f, type NajmThemeTokens as g, type NajmPreset as h, type NajmComponentName as i, type NajmComponentStyleConfig as j, type NajmComponentThemeConfig as k, type NajmTypographyConfig as l, type NajmLayoutConfig as m, type NajmVariantStyle as n, type NajmResponsiveBreakpoint as o, type NajmResponsiveValue as p, NAJM_COMPONENT_NAMES as q, type NTableDefaults as r, NTableDefaultsProvider as s, type NajmComponentRadius as t, type NajmDensity as u, type NajmPreferencesContextValue as v, NajmPreferencesProvider as w, type NajmPreferencesProviderProps as x, type NajmSlotStyle as y, NajmUIProvider as z };

package/dist/adapters/app.d.ts

@@ -3,7 +3,8 @@ import { Translations } from 'najm-i18n';
 import { N as NBrandingInput } from '../NBrandingContext-dkADu8JS.js';
 import { NajmNextUIProviderProps } from './next.js';
 import 'react';
-import '../NajmUIProvider-Dj32bd5d.js';
+import '../NajmUIProvider-ClpHD-55.js';
+import '../paginationLabels-CY2PvbMj.js';
 
 /** Branding shown by the kit's chrome. Purely presentational values. */
 interface NajmAppBranding {
@@ -38,6 +39,30 @@ interface NajmAppProviderProps extends Omit<NajmNextUIProviderProps, 't'> {
      * branding endpoint returns. An `appName` inside `initialBranding` wins.
      */
     appName?: string;
+    /**
+     * ISO 4217 code for `useNajmFormat().money`, e.g. `"MAD"`.
+     *
+     * Omitted means the application does not format currency. It is not defaulted
+     * to anything: rendering an amount in the wrong currency is worse than the
+     * error thrown for the missing code.
+     */
+    currency?: string;
+    /**
+     * Maps a `najm-i18n` language onto the BCP 47 tag used for formatting, e.g.
+     * `{ en: "en-MA", fr: "fr-MA" }`.
+     *
+     * The distinction matters because language and region are separate choices:
+     * `fr` alone formats dates and separators the French way, which is not how
+     * they are written in Morocco. Unmapped languages are used as-is.
+     */
+    locales?: Record<string, string>;
+    /**
+     * Fixes the formatting locale, ignoring the active language. Escape hatch for
+     * an application whose language and number formats are genuinely independent.
+     */
+    locale?: string;
+    /** Rendered for absent values. Defaults to an em dash. */
+    formatPlaceholder?: string;
     /**
      * Controlled marks. Prefer `initialBranding` — passing this means the
      * application holds the state itself, which is the file this provider exists

package/dist/adapters/app.mjs

@@ -1,5 +1,5 @@
 'use client';
-import { NBrandingStateProvider } from '../chunk-5LW62RB6.mjs';
+import { NBrandingStateProvider, NajmFormatProvider } from '../chunk-QOP7L6RD.mjs';
 import { NajmNextUIProvider } from '../chunk-IRFFSAO2.mjs';
 import '../chunk-USZUOJMK.mjs';
 import '../chunk-KVZACF4G.mjs';
@@ -12,15 +12,28 @@ function NajmAppUI({
   children,
   branding,
   initialBranding,
+  currency,
+  locale,
+  locales,
+  formatPlaceholder,
   ...props
 }) {
-  const { t } = useTranslation();
+  const { t, language } = useTranslation();
+  const resolved = locale ?? locales?.[language] ?? language;
   return /* @__PURE__ */ jsx(NajmNextUIProvider, { t, ...props, children: /* @__PURE__ */ jsx(
     NBrandingStateProvider,
     {
       branding,
       initialBranding,
-      children
+      children: /* @__PURE__ */ jsx(
+        NajmFormatProvider,
+        {
+          locale: resolved,
+          currency,
+          placeholder: formatPlaceholder,
+          children
+        }
+      )
     }
   ) });
 }
@@ -28,6 +41,10 @@ function NajmAppNoI18n({
   children,
   branding,
   initialBranding,
+  currency,
+  locale,
+  locales,
+  formatPlaceholder,
   ...props
 }) {
   return /* @__PURE__ */ jsx(NajmNextUIProvider, { ...props, children: /* @__PURE__ */ jsx(
@@ -35,7 +52,15 @@ function NajmAppNoI18n({
     {
       branding,
       initialBranding,
-      children
+      children: /* @__PURE__ */ jsx(
+        NajmFormatProvider,
+        {
+          locale: locale ?? "en",
+          currency,
+          placeholder: formatPlaceholder,
+          children
+        }
+      )
     }
   ) });
 }

package/dist/adapters/next.d.ts

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

package/dist/chunk-7J7DWGKB.mjs

@@ -0,0 +1,93 @@
+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 = DEFAULT_CARD_PAGINATION_KEY_PREFIX) {
+  return {
+    loadMoreError: t(`${prefix}.loadMoreError`),
+    retryLabel: t(`${prefix}.retryLoadMore`),
+    itemsLoaded: (count) => t(`${prefix}.itemsLoaded`, { count })
+  };
+}
+function createCardPagination(state, labels = {}) {
+  const mode = state.mode ?? (state.cardViewport ? "infinite" : "paged");
+  if (mode === "paged") return { mode: "paged" };
+  if (mode === "all") return { mode: "all" };
+  return {
+    mode: "infinite",
+    hasNextPage: state.hasNextPage,
+    loadingMore: state.loadingMore,
+    loadMoreError: state.loadMoreError ? labels.loadMoreError : void 0,
+    onLoadMore: state.onLoadMore,
+    retryLabel: labels.retryLabel,
+    loadMoreErrorLabel: labels.loadMoreError,
+    itemsLoadedLabel: labels.itemsLoaded
+  };
+}
+
+// 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_CARD_BREAKPOINT, DEFAULT_CARD_PAGINATION_KEY_PREFIX, DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE, buildCardPaginationLabels, cleanQuery, createCardPagination, createOffsetPagination, fetchOffsetPage, getPageIndex, useCardViewport, useDesktopTableMode, useMediaQuery };