najm-kit 2.9.0 → 2.11.0

package/README.md

@@ -123,7 +123,7 @@ Changing the state updates the complete theme immediately. Use
 `stringifyNajmThemeConfig(theme)` when persisting it, and parse settings loaded
 from an API or local storage with `parseNajmThemeConfig` before applying them.
 
-## Components
+## Components
 
 Import from `najm-kit`:
 
@@ -142,47 +142,297 @@ import { Form, FormInput, useNForm } from 'najm-kit';
 |----------|-----------|
 | Actions | NButton, IconButton, toggleVariants |
 | Forms | Input, Textarea, Label, Select, Checkbox, RadioGroup, Switch, DateInput, FileInput, ImageInput, AvatarInput |
-| Feedback | Alert, Badge, Progress, Spinner, Toast |
+| Feedback | Alert, Badge, Progress, Spinner, Toast, NLoadingState, NErrorState, NEmptyState, NForbiddenState, NNotFoundState |
 | Layout | Card, Sheet, Dialog, Popover, DropdownMenu, Tabs |
-| Data | Table (NTable), StatCard, DetailList |
-| Overlays | Command palette, Tooltip, Toast |
-
-## Global form development tools
-
-Enable schema-driven test values once on the full application provider. Every
-`NForm` and `WizardForm` below it then fills from its Zod schema when F8 is
-pressed; applications do not need a second provider or a form-fill helper.
-
-```tsx
-import { NajmAppProvider } from "najm-kit/app";
-
-<NajmAppProvider formDevTools>
-  <App />
-</NajmAppProvider>;
-```
-
-Pass a boolean to control it from application settings:
-
-```tsx
-<NajmAppProvider formDevTools={formFillEnabled}>
-  <App />
-</NajmAppProvider>
-```
-
-Forms with live relation options can override only those fields. The provider
-still owns enablement and Najm Kit still owns schema traversal and generation.
-
-```tsx
-<NForm
-  schema={orderSchema}
-  devTools={{ overrides: { customerId: customerOptions } }}
-  onSubmit={saveOrder}
->
-  {/* fields */}
-</NForm>
-```
-
-## ImageInput and AvatarInput
+| Data | Table (NTable), StatCard, DetailList, CredentialsCard |
+| Overlays | Command palette, Tooltip, Toast |
+
+## Images and avatars
+
+Three components, one fallback rule. Each tries its sources in order, tries a
+source at most once, and discards what it knows about a failure the moment the
+sources change.
+
+### `NImage` — plain `<img>`
+
+For a logo or an icon whose box the caller's CSS already owns. No layout is
+invented, and `onError` is forwarded rather than swallowed.
+
+```tsx
+import { NImage } from 'najm-kit';
+
+<NImage src={logo} fallback="/brand/logo.svg" alt="Acme" className="h-8 w-auto" />
+```
+
+### `NAvatar` — person or record
+
+The image is a native `<img>` loaded directly by the browser, so a same-origin
+protected route works with the session the page already has, and the package
+needs no knowledge of which routes are protected.
+
+```tsx
+import { NAvatar } from 'najm-kit';
+
+<NAvatar
+  src={member.image}
+  fallbackSrc={stockPortrait}
+  version={member.imageRevision}
+  title={member.name}
+  subtitle={member.role}
+  size="lg"
+/>
+```
+
+- The primary source is tried first, then `fallbackSrc`, then the initials.
+- `version` (or `srcVersion`) is appended as `?v=…` to every remote source, so a
+  re-upload is not served from cache. `data:` and `blob:` sources are left alone.
+- Initials stay visible until an image paints and come back if every source
+  fails — a transparent PNG never shows letters through itself.
+- `imageProps` reaches the element for `loading`, `sizes`, `crossOrigin`,
+  `referrerPolicy`, and the load/error handlers. It defaults to `loading="lazy"`,
+  and supplied handlers are composed with the fallback chain rather than
+  replacing it.
+
+### `NNextImage` — optimized, from `najm-kit/next`
+
+Same fallback contract with Next's optimizer, layout reservation, `fill`, and
+`sizes`. It lives only in the `najm-kit/next` entry, because the root package
+stays installable without Next.
+
+```tsx
+import { NNextImage } from 'najm-kit/next';
+
+// A public asset: let the optimizer resize and re-encode it.
+<NNextImage src="/covers/spring.png" alt="Spring" width={64} height={64} />
+```
+
+For an asset the browser must fetch directly — one behind an authenticated route,
+typically — the *application* says so:
+
+```tsx
+<NNextImage
+  src={record.image}
+  alt={record.name}
+  fill
+  sizes="64px"
+  unoptimized
+/>
+```
+
+`unoptimized` is passed at the call site rather than inferred from the URL:
+which routes are protected is the application's fact, not something a package
+can read off a path. It changes delivery mechanics only — session validation,
+permissions, privacy projection, and what bytes come back all remain the
+backend's.
+
+## Status badges
+
+`<NBadge status="…" />` already maps a broad lifecycle vocabulary onto the
+semantic colors, so it is correct without configuration:
+
+```tsx
+import { NBadge } from 'najm-kit';
+
+<NBadge status="out_for_delivery" />   // warning, "Out For Delivery"
+<NBadge status="nebulous" />           // neutral, "Nebulous"
+```
+
+What an application usually adds on top is the same three things at every call
+site: its look, its shape, and its own translated label. Declare them once:
+
+```tsx
+<NajmAppProvider
+  badgeDefaults={{
+    look: 'soft',
+    shape: 'pill',
+    statusLabelKeys: {
+      active: 'status.active',
+      out_for_delivery: 'status.outForDelivery',
+    },
+  }}
+>
+```
+
+`badgeDefaults` lives on `NajmUIProvider` and is inherited by
+`NajmNextUIProvider` and `NajmAppProvider`, so there is one place to set it.
+The keys are the application's catalog keys, resolved through the same `t` the
+provider already has — this package ships no status catalog. A language change
+recomputes every label without a remount.
+
+Resolution, most specific first:
+
+1. An explicit prop beats every provider default.
+2. `label` beats string children; string children beat the provider's label.
+3. A `statusLabels` literal beats a `statusLabelKeys` catalog lookup.
+4. An unmapped status is humanized (`pending_review` → `Pending Review`).
+5. A per-instance `statusMap`/`iconMap` merges over the provider's, so
+   overriding one status costs one status.
+6. Provider status defaults apply **only** when `status` is set —
+   `<NBadge>Beta</NBadge>` keeps the ordinary content-badge look.
+
+Statuses are matched through one rule, exported as `normalizeStatusToken`, so
+`Out-For-Delivery `, `out for delivery`, and `out_for_delivery` are the same
+key for colors, icons, and labels alike. Badge text is presentation: it renames
+nothing in the backend and validates no lifecycle transition.
+
+## Feedback states
+
+Five public state components cover the reusable cases every application
+otherwise repeats: `NLoadingState`, `NErrorState`, `NEmptyState`,
+`NForbiddenState`, and `NNotFoundState`. They share one layout frame and one
+provider-defaults channel, so an application configures its copy once and
+every consumer below inherits it.
+
+### Surfaces
+
+Three layouts, one prop. `surface` selects the frame:
+
+| `surface` | Use it for | What it does |
+| --- | --- | --- |
+| `"inline"` (default) | A small slot inside an existing component | Legacy sizing, no landmark |
+| `"panel"` | A table body, card body, dialog, or sheet | Centered with a minimum height, no page gutter, no landmark |
+| `"page"` | A real route-level state | Uses page spacing from the design config; renders through a non-`<main>` root |
+
+`NLoadingState.fullScreen` keeps its fixed viewport overlay regardless of
+surface — it always wins.
+
+```tsx
+import { NLoadingState, NErrorState, NEmptyState } from 'najm-kit';
+
+// Inline (default): drop into a card or section.
+<NLoadingState label="Loading orders..." />
+
+// Panel: table body or dialog content.
+<NEmptyState surface="panel" title="No orders yet" icon={Inbox} />
+
+// Page: route-level empty state. Never introduces a second <main>.
+<NErrorState
+  surface="page"
+  title="Dashboard unavailable"
+  message="We are working on it."
+  onRetry={() => refetch()}
+/>
+```
+
+### Provider defaults
+
+Pass one `feedbackDefaults` map to `NajmUIProvider` (or to `NajmAppProvider`
+through it) and every feedback state beneath uses it. There is one place for
+loading, empty, error, retry, forbidden, and not-found labels, and a single
+language change recomputes them all without remounting the tree.
+
+```tsx
+import { NajmAppProvider } from 'najm-kit/app';
+
+<NajmAppProvider
+  feedbackDefaults={{
+    labels: {
+      loadingLabel: 'Chargement…',
+      emptyTitle: 'Aucune donnée',
+      errorTitle: 'Une erreur est survenue',
+      retryLabel: 'Réessayer',
+      forbiddenTitle: 'Accès refusé',
+      forbiddenDescription: 'Vous n\'avez pas la permission.',
+      notFoundTitle: 'Page introuvable',
+      notFoundDescription: 'La page demandée n\'existe pas.',
+    },
+    labelKeys: {
+      emptyTitle: 'common.empty',
+      errorTitle: 'common.error',
+    },
+  }}
+>
+  <App />
+</NajmAppProvider>
+```
+
+Resolution order, most specific first:
+
+1. An explicit component prop.
+2. A literal in `feedbackDefaults.labels`.
+3. A translated `feedbackDefaults.labelKeys` value resolved through the
+   provider's existing structural `t` function.
+4. The current packaged English fallback, when that field has one.
+
+Generic `NErrorState.message` and `NEmptyState.description` deliberately have
+no packaged fallback — the no-provider render must look the same as it did
+before this contract shipped. A configured `errorMessage` opts the generic
+error state into rendering a body; absent that opt-in, the existing
+no-body render is preserved.
+
+### Forbidden and not-found
+
+Two first-class preset states for the routes every application grows:
+
+```tsx
+import { NForbiddenState, NNotFoundState } from 'najm-kit';
+
+// Forbidden: provider copy + ShieldOff icon + page surface by default.
+<NForbiddenState
+  action={<Link href="/dashboard">Back to dashboard</Link>}
+/>
+
+// Not found: provider copy + Compass icon + page surface by default.
+<NNotFoundState
+  action={<Link href="/dashboard">Back to dashboard</Link>}
+/>
+```
+
+Both are presentation only. They do not know the dashboard URL, render a
+Next `Link`, redirect, or write route metadata — those belong to the
+application's `not-found.tsx` / `forbidden/page.tsx` files.
+
+### Root and `najm-kit/app` imports
+
+Both entries export the same five state components. Pick the one that matches
+your boundary:
+
+```tsx
+// Client feature code: import from the root barrel.
+import { NEmptyState } from 'najm-kit';
+
+// Next Server Component route: import from najm-kit/app, which is the
+// Client Component boundary. A route file can render a state component
+// without authoring a local "use client" wrapper.
+import { NNotFoundState } from 'najm-kit/app';
+```
+
+## Global form development tools
+
+Enable schema-driven test values once on the full application provider. Every
+`NForm` and `WizardForm` below it then fills from its Zod schema when F8 is
+pressed; applications do not need a second provider or a form-fill helper.
+
+```tsx
+import { NajmAppProvider } from "najm-kit/app";
+
+<NajmAppProvider formDevTools>
+  <App />
+</NajmAppProvider>;
+```
+
+Pass a boolean to control it from application settings:
+
+```tsx
+<NajmAppProvider formDevTools={formFillEnabled}>
+  <App />
+</NajmAppProvider>
+```
+
+Forms with live relation options can override only those fields. The provider
+still owns enablement and Najm Kit still owns schema traversal and generation.
+
+```tsx
+<NForm
+  schema={orderSchema}
+  devTools={{ overrides: { customerId: customerOptions } }}
+  onSubmit={saveOrder}
+>
+  {/* fields */}
+</NForm>
+```
+
+## ImageInput and AvatarInput
 
 `ImageInput` and `AvatarInput` ship with a resilient preview contract so
 consumers do not need to wrap them with application-specific preview
@@ -247,93 +497,157 @@ 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.
-
-## 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
+`AvatarInput` forwards every preview and accessibility prop unchanged while
+preserving its circular, size, fill, and camera-icon defaults.
+
+## Credentials handover
+
+`NCredentialsCard` renders the recurring "show a freshly generated secret
+once, let the operator hand it over, never show it again" surface. It owns
+the frame, the description-list semantics, the copy flow, the failure
+handling, and the accessible feedback. Every domain label — title,
+description, field labels, action labels, and any translated toast — stays
+with the application.
+
+```tsx
+import { NCredentialsCard, NButton } from "najm-kit";
+import { KeyRound, Phone } from "lucide-react";
+
+<NCredentialsCard
+  title={t("staff.access.created")}
+  description={t("staff.access.oneTimeHint")}
+  fields={[
+    { label: t("common.phone"), value: credentials.phone, icon: Phone },
+    { label: t("staff.access.initialPassword"), value: credentials.password, icon: KeyRound },
+  ]}
+  copyLabel={t("common.copyDetails")}
+  copiedLabel={t("common.copied")}
+  copyErrorLabel={t("common.copyError")}
+  actions={<NButton onClick={() => pop()}>{t("common.done")}</NButton>}
+/>
+```
+
+Behaviour worth knowing:
+
+- `fields` renders as a `<dl>` of `<dt>`/`<dd>` pairs. Values default to
+  monospaced and mid-string wrapping so secrets stay readable on every
+  width.
+- The header icon defaults to a check mark and is always rendered when a
+  header is shown. Pass `icon={SomeLucideIcon}` to replace it; pass any
+  supported `NIconSource` to swap in a logo, image, or remote URL.
+- The Copy button resolves text through `copyText` when supplied, otherwise
+  joins `${label}: ${value}` with `\n` in field order. The button is
+  disabled while the clipboard write is pending. Success swaps the label to
+  `copiedLabel` and a check icon; failure swaps to `copyErrorLabel` and a
+  warning icon. Either state reverts to idle after roughly two seconds.
+- The copy button renders before any consumer `actions` so a Done-style
+  dismiss stays the last tab stop and never gets pressed before the secret
+  is actually copied.
+- Missing `navigator.clipboard`, rejected `writeText`, and synchronously
+  thrown `copyText` / `writeText` all land in the error state and call
+  `onCopyError` instead of rethrowing. State updates and revert timers are
+  guarded, so unmounting during a pending copy, or starting a second copy
+  while the first success state is still showing, never fire stale setters.
+- Status is announced through a polite `aria-live` region. The visible swap
+  is the primary feedback — no toast is emitted by the component.
+- Packaged English fallbacks exist for `copyLabel`, `copiedLabel`, and
+  `copyErrorLabel` only. Title, description, and every field label are the
+  application's text; a consumer that omits them gets no text, not English.
+- Spacing uses logical properties only, so a `dir="rtl"` tree needs no
+  override. Each value also carries `dir="auto"`, isolating it from the
+  surrounding paragraph direction: a phone number or password inherited into an
+  RTL tree otherwise *paints* reordered (`+1 555 0100` as `0100 555 1+`) even
+  though the DOM and the copied text are correct. A value whose first strong
+  character is Arabic still renders right-to-left.
+
+When you only want consumer buttons and no built-in copy, pass
+`hideCopyAction`. Pass `copyText` to format the copied text differently
+(one CSV line per field, a JSON blob, a single concatenated value, …).
+
+## 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';
@@ -397,116 +711,116 @@ Notes:
 - The columns the TanStack table receives are already filtered, so the
   settings menu will not list `visible: false` columns.
 
-If you need to inspect or build your own effective column list, the same
-pure helper is exported as `filterResponsiveColumns`. The literal class
-map is also exported as `hiddenBelowClasses`, and
-`resolveHiddenBelowClass(breakpoint)` returns the class for a single
-breakpoint or `undefined` when no breakpoint is set.
-
-## NTable responsive cards, loading, and pagination
-
-Responsive row actions are visible by default on phone, tablet, and coarse or
-non-hover pointers. Fine-pointer desktop layouts may reveal them on hover, but
-keyboard focus always reveals the action. Applications still decide which menu
-items exist through `menu`, `onView`, `onEdit`, and `onDelete`; visibility does
-not grant an action or replace server authorization.
-
-When `dynamicHeight` is enabled, table and card loading skeletons measure the
-available body. Table rows use the same header/row geometry as dynamic page
-sizing, while cards measure the active grid columns, card height, and gap. The
-loading surface also follows the loaded `bordered`, design recipe, radius,
-border color, shadow, and `classNames.content`/`classNames.cards` contract.
-
-Use `cardPagination` to choose pagination presentation whenever the effective
-rendered mode is cards:
-
-- `{ mode: "paged" }` (the default) preserves existing pagination.
-- `{ mode: "all" }` renders every row already supplied and hides the footer.
-- `{ mode: "load-more", ... }` renders every supplied row and provides a
-  guarded, keyboard-operable Load more/Retry control with polite loading,
-  appended-result, and end-of-list announcements.
-
-`showPagination={false}` remains an absolute presentation override and hides
-both numbered controls and Load more. In table mode, existing controlled and
-manual server pagination remains unchanged.
-
-```tsx
-import { NTable, type NTableCardPagination } from "najm-kit";
-
-const cardPagination: NTableCardPagination = {
-  mode: "load-more",
-  hasNextPage: query.hasNextPage,
-  loadingMore: query.isFetchingNextPage,
-  loadMoreError: query.isFetchNextPageError
-    ? "The next page could not be loaded."
-    : undefined,
-  onLoadMore: () => query.fetchNextPage(),
-  loadMoreLabel: "Load more",
-  loadingMoreLabel: "Loading more...",
-  retryLabel: "Retry",
-  endLabel: "No more results.",
-};
-
-<NTable
-  data={query.data?.pages.flatMap((page) => page.rows) ?? []}
-  columns={columns}
-  getRowId={(row) => row.id}
-  renderCard={ResultCard}
-  cardPagination={cardPagination}
-/>
-```
-
-The application owns the query, cursor/offset, accumulated pages, cache
-invalidation, search/filter/sort semantics, authorization, and privacy
-projection. Najm Kit never imports React Query, calls an endpoint, invents a
-page size, or treats supplied rows as proof that every database row is loaded.
-Client sorting and filtering cover the rows currently supplied unless the
-application implements matching server-side behavior.
-
-For a responsive screen that uses current-page data in desktop table mode and
-accumulated pages in card mode, keep those two query shapes in the application
-and pass the appropriate `data`. Crossing the `<640px` responsive-card
-breakpoint does not overwrite the user's chosen view, pagination position,
-sorting, filters, expansion, or row selection.
-
-## Theme-backed charts
-
-`NBarChart`, `NLineChart`, `NPieChart`, and `NStatusBreakdown` accept generic
-caller-formatted data and use `--chart-1` through `--chart-5` by default.
-Colors repeat deterministically after the fifth series or item; set `color` on
-an exceptional series/item to override that one value. Each chart accepts
-`loading`/`loadingLabel` and renders an accessible shape-matched skeleton.
-`NPieChart` and `NDonutCard` accept `size="sm" | "md" | "lg"` or a numeric
-pixel diameter and shrink within narrow containers.
-
-```tsx
-import { NBarChart, NPieChart } from "najm-kit";
-
-const data = [
-  { id: "jan", label: "Jan", values: { received: 12, refunded: 2 } },
-  { id: "feb", label: "Feb", values: { received: 18, refunded: 1 } },
-];
-
-<NBarChart
-  title="Monthly activity"
-  data={data}
-  series={[
-    { id: "received", label: "Received" },
-    { id: "refunded", label: "Refunded" },
-  ]}
-  valueFormatter={(value) => `${value} MAD`}
-/>
-
-<NPieChart
-  title="Status"
-  size={132}
-  items={[
-    { id: "active", label: "Active", value: 8 },
-    { id: "pending", label: "Pending", value: 3 },
-  ]}
-/>
-```
-
+If you need to inspect or build your own effective column list, the same
+pure helper is exported as `filterResponsiveColumns`. The literal class
+map is also exported as `hiddenBelowClasses`, and
+`resolveHiddenBelowClass(breakpoint)` returns the class for a single
+breakpoint or `undefined` when no breakpoint is set.
+
+## NTable responsive cards, loading, and pagination
+
+Responsive row actions are visible by default on phone, tablet, and coarse or
+non-hover pointers. Fine-pointer desktop layouts may reveal them on hover, but
+keyboard focus always reveals the action. Applications still decide which menu
+items exist through `menu`, `onView`, `onEdit`, and `onDelete`; visibility does
+not grant an action or replace server authorization.
+
+When `dynamicHeight` is enabled, table and card loading skeletons measure the
+available body. Table rows use the same header/row geometry as dynamic page
+sizing, while cards measure the active grid columns, card height, and gap. The
+loading surface also follows the loaded `bordered`, design recipe, radius,
+border color, shadow, and `classNames.content`/`classNames.cards` contract.
+
+Use `cardPagination` to choose pagination presentation whenever the effective
+rendered mode is cards:
+
+- `{ mode: "paged" }` (the default) preserves existing pagination.
+- `{ mode: "all" }` renders every row already supplied and hides the footer.
+- `{ mode: "load-more", ... }` renders every supplied row and provides a
+  guarded, keyboard-operable Load more/Retry control with polite loading,
+  appended-result, and end-of-list announcements.
+
+`showPagination={false}` remains an absolute presentation override and hides
+both numbered controls and Load more. In table mode, existing controlled and
+manual server pagination remains unchanged.
+
+```tsx
+import { NTable, type NTableCardPagination } from "najm-kit";
+
+const cardPagination: NTableCardPagination = {
+  mode: "load-more",
+  hasNextPage: query.hasNextPage,
+  loadingMore: query.isFetchingNextPage,
+  loadMoreError: query.isFetchNextPageError
+    ? "The next page could not be loaded."
+    : undefined,
+  onLoadMore: () => query.fetchNextPage(),
+  loadMoreLabel: "Load more",
+  loadingMoreLabel: "Loading more...",
+  retryLabel: "Retry",
+  endLabel: "No more results.",
+};
+
+<NTable
+  data={query.data?.pages.flatMap((page) => page.rows) ?? []}
+  columns={columns}
+  getRowId={(row) => row.id}
+  renderCard={ResultCard}
+  cardPagination={cardPagination}
+/>
+```
+
+The application owns the query, cursor/offset, accumulated pages, cache
+invalidation, search/filter/sort semantics, authorization, and privacy
+projection. Najm Kit never imports React Query, calls an endpoint, invents a
+page size, or treats supplied rows as proof that every database row is loaded.
+Client sorting and filtering cover the rows currently supplied unless the
+application implements matching server-side behavior.
+
+For a responsive screen that uses current-page data in desktop table mode and
+accumulated pages in card mode, keep those two query shapes in the application
+and pass the appropriate `data`. Crossing the `<640px` responsive-card
+breakpoint does not overwrite the user's chosen view, pagination position,
+sorting, filters, expansion, or row selection.
+
+## Theme-backed charts
+
+`NBarChart`, `NLineChart`, `NPieChart`, and `NStatusBreakdown` accept generic
+caller-formatted data and use `--chart-1` through `--chart-5` by default.
+Colors repeat deterministically after the fifth series or item; set `color` on
+an exceptional series/item to override that one value. Each chart accepts
+`loading`/`loadingLabel` and renders an accessible shape-matched skeleton.
+`NPieChart` and `NDonutCard` accept `size="sm" | "md" | "lg"` or a numeric
+pixel diameter and shrink within narrow containers.
+
+```tsx
+import { NBarChart, NPieChart } from "najm-kit";
+
+const data = [
+  { id: "jan", label: "Jan", values: { received: 12, refunded: 2 } },
+  { id: "feb", label: "Feb", values: { received: 18, refunded: 1 } },
+];
+
+<NBarChart
+  title="Monthly activity"
+  data={data}
+  series={[
+    { id: "received", label: "Received" },
+    { id: "refunded", label: "Refunded" },
+  ]}
+  valueFormatter={(value) => `${value} MAD`}
+/>
+
+<NPieChart
+  title="Status"
+  size={132}
+  items={[
+    { id: "active", label: "Active", value: 8 },
+    { id: "pending", label: "Pending", value: 3 },
+  ]}
+/>
+```
+
 ### Server-backed combobox search
 
 `ComboboxInput` and `FormInput type="combobox"` can delegate filtering to a
@@ -600,116 +914,116 @@ only, after a real `image` and before the role's gender variant:
 ```ts
 getPersonImage({ image: child.image, role: "child", gender: child.gender, fallback: child.placeholder });
 ```
-
-
-## Server UI bootstrap (`najm-kit/server`, `najm-kit/server/react`)
-
-An application that renders its own theme and its own logos on the server ends
-up writing the same module every time: fetch the public endpoints, unwrap the
-`data` envelope, validate the payload, fall back to the built-in assets when
-any of that fails, and run the resources in parallel. These two entries own
-that mechanism. What stays with the application is what is genuinely
-application-specific — how a request reaches its own backend, which paths it
-serves, what a valid payload looks like, what the factory values are, and where
-a diagnostic goes.
-
-Neither entry is re-exported from `najm-kit`, `najm-kit/next`, or
-`najm-kit/app`. `najm-kit/server` imports no React at all, so a route handler
-or a plain script can use it.
-
-### The application's one server module
-
-```ts
-// src/lib/serverLoader.ts
-import "server-only";
-
-import { parseNajmDesignConfig } from "najm-kit/server";
-import { createReactServerUiBootstrap } from "najm-kit/server/react";
-
-export const serverUi = createReactServerUiBootstrap({
-  fetcher: async (path) => {
-    const { server } = await import("@app/server");
-    return server.fetch(new Request(`http://internal${path}`));
-  },
-  resources: {
-    appearance: {
-      path: "/api/appearance",
-      parse: parseAppearance,          // returns undefined or throws to reject
-      fallback: getFactoryAppearance,  // called per load
-    },
-    branding: {
-      path: "/api/branding",
-      parse: parseBranding,
-      fallback: getFactoryBranding,
-    },
-  },
-  onDiagnostic: (diagnostic) => {
-    console.warn(`[ui-bootstrap] ${diagnostic.resource} ${diagnostic.reason}`, diagnostic);
-  },
-});
-
-export const loadServerUiBootstrap = serverUi.load;
-export const { appearance: loadServerAppearance, branding: loadServerBranding } =
-  serverUi.loaders;
-```
-
-`load()` resolves every resource; `loaders.<name>()` and `loadResource(name)`
-read one off the same resolution. Resource names, payload types, and the number
-of resources are the application's — the snapshot type is inferred from the
-`resources` object, so `snapshot.branding` is your branding type and not a
-package interface.
-
-### Call the factory once, at module scope
-
-`createReactServerUiBootstrap()` builds one `React.cache()` entry. Calling it
-inside a layout, page, or component builds a fresh one per call and shares
-nothing. Every server boundary in a render must import the same module.
-
-The cache is React's, so it is request-scoped and nothing else: separate
-requests never see each other's snapshot or each other's failure, and a
-transient outage is retried on the next request rather than pinned into a
-process-global. That also rules out a module `Map`, a module promise,
-`unstable_cache`, `"use cache"`, or a durable cache here — every one of them
-would leak one visitor's render into another's.
-
-The snapshot is deliberately stable for the length of one render. A settings
-surface that saves appearance or branding updates the client provider and then
-refreshes or navigates into a new render to observe the persisted result.
-
-Outside a render — route handlers, server actions, scripts — use
-`createUiBootstrapLoader()` from `najm-kit/server` directly. There is no request
-cache for `cache()` to write to there, so the adapter would silently re-fetch
-per call.
-
-### Failure behaviour
-
-Resources fall back independently: a branding outage never discards a valid
-appearance. Each failure calls `onDiagnostic` once with a `reason` of
-`fetch-failed`, `response-not-ok`, `invalid-json`, `invalid-envelope`, or
-`invalid-payload`, plus the path and — for a non-success response — the status.
-Diagnostics never carry response bodies, headers, cookies, or raw thrown
-values; `error` is a normalized `"<name>: <message>"` for an `Error` and the
-value's type for anything else.
-
-A `fallback()` that throws is **not** caught. A missing factory theme is the
-application's configuration error, and a second fallback would only hide it.
-
-Falling back is right for *public* appearance and branding, where the worst case
-is a visitor seeing the built-in logo. It is not a general rule: do not route
-authenticated, financial, or privacy-sensitive reads through this, because a
-silent fallback there hides an outage behind plausible-looking data.
-
-### Envelopes
-
-`select` defaults to Najm's `{ data }` envelope. Applications behind a different
-envelope pass their own at the loader level or per resource; returning the
-payload unchanged is a valid selector, and throwing rejects the response as
-`invalid-envelope`.
-
-### Client Components
-
-`najm-kit/server/react` maps the `browser` export condition to a module that
-throws, so importing it from a Client Component fails the build with an
-explanation rather than shipping the application's fetcher and factory values
-into a browser bundle. Seed the client from the server snapshot through
-`NajmAppProvider` instead.
+
+
+## Server UI bootstrap (`najm-kit/server`, `najm-kit/server/react`)
+
+An application that renders its own theme and its own logos on the server ends
+up writing the same module every time: fetch the public endpoints, unwrap the
+`data` envelope, validate the payload, fall back to the built-in assets when
+any of that fails, and run the resources in parallel. These two entries own
+that mechanism. What stays with the application is what is genuinely
+application-specific — how a request reaches its own backend, which paths it
+serves, what a valid payload looks like, what the factory values are, and where
+a diagnostic goes.
+
+Neither entry is re-exported from `najm-kit`, `najm-kit/next`, or
+`najm-kit/app`. `najm-kit/server` imports no React at all, so a route handler
+or a plain script can use it.
+
+### The application's one server module
+
+```ts
+// src/lib/serverLoader.ts
+import "server-only";
+
+import { parseNajmDesignConfig } from "najm-kit/server";
+import { createReactServerUiBootstrap } from "najm-kit/server/react";
+
+export const serverUi = createReactServerUiBootstrap({
+  fetcher: async (path) => {
+    const { server } = await import("@app/server");
+    return server.fetch(new Request(`http://internal${path}`));
+  },
+  resources: {
+    appearance: {
+      path: "/api/appearance",
+      parse: parseAppearance,          // returns undefined or throws to reject
+      fallback: getFactoryAppearance,  // called per load
+    },
+    branding: {
+      path: "/api/branding",
+      parse: parseBranding,
+      fallback: getFactoryBranding,
+    },
+  },
+  onDiagnostic: (diagnostic) => {
+    console.warn(`[ui-bootstrap] ${diagnostic.resource} ${diagnostic.reason}`, diagnostic);
+  },
+});
+
+export const loadServerUiBootstrap = serverUi.load;
+export const { appearance: loadServerAppearance, branding: loadServerBranding } =
+  serverUi.loaders;
+```
+
+`load()` resolves every resource; `loaders.<name>()` and `loadResource(name)`
+read one off the same resolution. Resource names, payload types, and the number
+of resources are the application's — the snapshot type is inferred from the
+`resources` object, so `snapshot.branding` is your branding type and not a
+package interface.
+
+### Call the factory once, at module scope
+
+`createReactServerUiBootstrap()` builds one `React.cache()` entry. Calling it
+inside a layout, page, or component builds a fresh one per call and shares
+nothing. Every server boundary in a render must import the same module.
+
+The cache is React's, so it is request-scoped and nothing else: separate
+requests never see each other's snapshot or each other's failure, and a
+transient outage is retried on the next request rather than pinned into a
+process-global. That also rules out a module `Map`, a module promise,
+`unstable_cache`, `"use cache"`, or a durable cache here — every one of them
+would leak one visitor's render into another's.
+
+The snapshot is deliberately stable for the length of one render. A settings
+surface that saves appearance or branding updates the client provider and then
+refreshes or navigates into a new render to observe the persisted result.
+
+Outside a render — route handlers, server actions, scripts — use
+`createUiBootstrapLoader()` from `najm-kit/server` directly. There is no request
+cache for `cache()` to write to there, so the adapter would silently re-fetch
+per call.
+
+### Failure behaviour
+
+Resources fall back independently: a branding outage never discards a valid
+appearance. Each failure calls `onDiagnostic` once with a `reason` of
+`fetch-failed`, `response-not-ok`, `invalid-json`, `invalid-envelope`, or
+`invalid-payload`, plus the path and — for a non-success response — the status.
+Diagnostics never carry response bodies, headers, cookies, or raw thrown
+values; `error` is a normalized `"<name>: <message>"` for an `Error` and the
+value's type for anything else.
+
+A `fallback()` that throws is **not** caught. A missing factory theme is the
+application's configuration error, and a second fallback would only hide it.
+
+Falling back is right for *public* appearance and branding, where the worst case
+is a visitor seeing the built-in logo. It is not a general rule: do not route
+authenticated, financial, or privacy-sensitive reads through this, because a
+silent fallback there hides an outage behind plausible-looking data.
+
+### Envelopes
+
+`select` defaults to Najm's `{ data }` envelope. Applications behind a different
+envelope pass their own at the loader level or per resource; returning the
+payload unchanged is a valid selector, and throwing rejects the response as
+`invalid-envelope`.
+
+### Client Components
+
+`najm-kit/server/react` maps the `browser` export condition to a module that
+throws, so importing it from a Client Component fails the build with an
+explanation rather than shipping the application's fetcher and factory values
+into a browser bundle. Seed the client from the server snapshot through
+`NajmAppProvider` instead.