najm-kit 2.7.0 → 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/NBrandingContext-dkADu8JS.d.ts

@@ -0,0 +1,82 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface NBrandingValue {
+    /** Used as the logo's `alt` when the logo does not set one. */
+    appName?: string;
+    logoExpanded?: ReactNode | string;
+    /** Falls back to `logoExpanded`. */
+    logoCollapsed?: ReactNode | string;
+    /** Swapped in when a `string` logo fails to load. */
+    logoFallback?: string;
+    logoHref?: string;
+}
+/**
+ * What a Najm branding endpoint returns, as the marks the chrome needs.
+ *
+ * Accepted anywhere branding goes *in* so an application hands over its API
+ * payload unchanged instead of renaming two fields at every call site. Fields
+ * beyond these are ignored: excess-property checks only fire on object
+ * literals, so passing a wider response object — auth logos, a revision — type
+ * checks and drops what the chrome has no use for.
+ */
+interface NBrandingPayload {
+    sidebarLogoExpandedPath?: string | null;
+    sidebarLogoCollapsedPath?: string | null;
+}
+/** Resolved marks, an endpoint payload, or both. */
+type NBrandingInput = NBrandingValue & NBrandingPayload;
+/**
+ * Projects an input onto the marks `useNBranding` publishes.
+ *
+ * Explicit marks win over payload fields, so an application already passing
+ * `logoExpanded` — or a `ReactNode` logo, which no payload can express — is
+ * unaffected by the wider input type.
+ */
+declare function normalizeBranding(input?: NBrandingInput): NBrandingValue;
+/** Returns `null` outside a provider, so every consumer stays optional. */
+declare function useNBranding(): NBrandingValue | null;
+/**
+ * Publishes the app's marks once, so shells stop threading a `logo` through
+ * every surface that shows one. `NSidebar` reads this when no `logo` prop is
+ * given; an explicit `logo` always wins.
+ *
+ * Unlike `NSidebarProvider` this owns no state — the values are resolved by the
+ * app (usually server-side) and only forwarded, so memoizing on the fields is
+ * correct here.
+ */
+declare function NBrandingProvider({ children, appName, logoExpanded, logoCollapsed, logoFallback, logoHref, }: Readonly<NBrandingValue & {
+    children: ReactNode;
+}>): react_jsx_runtime.JSX.Element;
+interface NBrandingEditorValue {
+    branding: NBrandingValue;
+    /**
+     * Merges a patch over the current marks. Inert while controlled.
+     *
+     * Takes the endpoint payload shape too, so a settings surface hands back the
+     * response it just received rather than renaming its fields first.
+     */
+    setBranding: (patch: NBrandingInput) => void;
+}
+/**
+ * Lets a settings surface swap the app's marks without a reload.
+ *
+ * Returns `null` outside `NBrandingStateProvider`, so a branding editor stays
+ * mountable in an app that resolves its logos once and never changes them.
+ *
+ * Only the *display* values live here. Where the assets are stored, who may
+ * replace them, and what happens to a superseded upload are the application's
+ * concerns, and folding them in would make this a branding backend.
+ */
+declare function useNBrandingEditor(): NBrandingEditorValue | null;
+interface NBrandingStateProviderProps {
+    children: ReactNode;
+    /** Controlled marks. When given, `setBranding` is inert. */
+    branding?: NBrandingInput;
+    /** Seeds marks this provider owns from then on; ignored after mount. */
+    initialBranding?: NBrandingInput;
+}
+/** `NBrandingProvider` with the marks held as state an editor can write. */
+declare function NBrandingStateProvider({ children, branding, initialBranding, }: Readonly<NBrandingStateProviderProps>): react_jsx_runtime.JSX.Element;
+
+export { type NBrandingInput as N, type NBrandingEditorValue as a, type NBrandingPayload as b, NBrandingProvider as c, NBrandingStateProvider as d, type NBrandingStateProviderProps as e, type NBrandingValue as f, useNBrandingEditor as g, normalizeBranding as n, useNBranding as u };

package/dist/{NajmUIProvider-BsCoDjHH.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.
  *
@@ -328,7 +214,13 @@ interface NajmPreferencesProviderProps {
     onThemeChange?: (theme: NajmMode) => void | Promise<void>;
     /** Persist the new time zone. Rejections propagate to `setTimeZone`. */
     onTimeZoneChange?: (timeZone: string) => void | Promise<void>;
-    /** Sanitize a time zone before it is stored. Defaults to identity. */
+    /**
+     * Sanitize a time zone before it is stored.
+     *
+     * Defaults to an IANA check that falls back to `DEFAULT_TIME_ZONE`, which is
+     * what every application wanted from the callback it used to have to supply.
+     * Pass one to narrow further — a fixed set backing a picker, say.
+     */
     normalizeTimeZone?: (value: string) => string;
 }
 /**
@@ -354,42 +246,37 @@ 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;
     /**
-     * The design config handed to `NajmDesignProvider`.
+     * The design config handed to `NajmDesignProvider`, owned by the application.
      *
      * Optional, and deliberately so: an application with no runtime theme editor
      * has nothing to put here, and requiring it was the only reason such an
      * application still had to author a provider file just to hold a constant.
+     *
+     * Prefer `initialDesign` for a theme editor. Passing `design` means the
+     * application holds the draft state itself, which is the file this provider
+     * exists to delete.
      */
     design?: NajmDesignConfig;
-    /** Forwarded to `NajmDesignProvider`. */
+    /**
+     * Seeds design state this provider owns from then on; ignored after mount.
+     * A theme editor drives it through `useNajmDesignEditor`.
+     */
+    initialDesign?: NajmDesignConfig;
+    /**
+     * Forwarded to `NajmDesignProvider`, merged over a `min-h-full` default.
+     *
+     * The default is not decoration. `NajmThemeProvider` renders a real `div`
+     * between the document body and the application, and a block box of
+     * automatic height severs any `h-full` chain below it — every application
+     * mounting this at the root was passing the same class back to repair that.
+     * It is inert where it is not needed: a percentage `min-height` against an
+     * auto-height parent imposes no constraint.
+     *
+     * Merged with `cn`, so a conflicting utility here still wins.
+     */
     className?: string;
     /**
      * Translator for the pagination labels. Omit it and the packaged English
@@ -426,6 +313,6 @@ interface NajmUIProviderProps extends Omit<NajmPreferencesProviderProps, "childr
  * an application with a runtime theme editor hoist preferences above its
  * design context without forking this component.
  */
-declare function NajmUIProvider({ children, design, className, t, paginationKeyPrefix, tableDefaults, initialTheme, initialTimeZone, onThemeChange, onTimeZoneChange, normalizeTimeZone, }: NajmUIProviderProps): react_jsx_runtime.JSX.Element;
+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 NajmThemeProviderProps as a, type NajmAppearance as b, type NajmMode as c, type NajmDesignConfig 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

@@ -1,8 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Translations } from 'najm-i18n';
+import { N as NBrandingInput } from '../NBrandingContext-dkADu8JS.js';
 import { NajmNextUIProviderProps } from './next.js';
 import 'react';
-import '../NajmUIProvider-BsCoDjHH.js';
+import '../NajmUIProvider-ClpHD-55.js';
+import '../paginationLabels-CY2PvbMj.js';
 
 /** Branding shown by the kit's chrome. Purely presentational values. */
 interface NajmAppBranding {
@@ -29,7 +31,54 @@ interface NajmAppProviderProps extends Omit<NajmNextUIProviderProps, 't'> {
      * would discard that work to re-render the same strings from the server.
      */
     languageEndpoint?: string;
-    branding?: NajmAppBranding;
+    /**
+     * The product name, used as the logo's `alt` and by the kit's chrome.
+     *
+     * Separate from `initialBranding` because it is a constant rather than
+     * something a branding editor swaps, and because it is the one mark no
+     * 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
+     * to delete.
+     */
+    branding?: NBrandingInput;
+    /**
+     * Seeds marks this provider owns from then on; ignored after mount. A
+     * branding editor swaps them through `useNBrandingEditor`.
+     *
+     * Takes a branding endpoint's payload as-is — `sidebarLogoExpandedPath` and
+     * `sidebarLogoCollapsedPath` are read straight off it, and unrelated fields
+     * are ignored — so the application forwards its response rather than
+     * renaming two keys here.
+     */
+    initialBranding?: NBrandingInput;
 }
 /**
  * The whole UI provider stack for a Najm application, as one component.
@@ -43,9 +92,13 @@ interface NajmAppProviderProps extends Omit<NajmNextUIProviderProps, 't'> {
  * and an application that wants different query policy should not have to fork
  * a provider to get it. Mount them above this, from their own packages.
  *
- * Design is optional. Applications that resolve a design config at runtime — a
- * theme editor — compute it above and pass it down; everything else omits it.
+ * Design and branding are optional, and both are *uncontrolled* through their
+ * `initial*` props: an application with a runtime theme or branding editor
+ * seeds them from the server once and drives them afterwards through
+ * `useNajmDesignEditor` and `useNBrandingEditor`, rather than holding a draft
+ * state machine of its own above this provider. The controlled `design` and
+ * `branding` props still work for applications that already do.
  */
-declare function NajmAppProvider({ translations, initialLanguage, defaultLanguage, languageEndpoint, ...props }: NajmAppProviderProps): react_jsx_runtime.JSX.Element;
+declare function NajmAppProvider({ translations, initialLanguage, defaultLanguage, languageEndpoint, appName, initialBranding, ...props }: NajmAppProviderProps): react_jsx_runtime.JSX.Element;
 
 export { type NajmAppBranding, NajmAppProvider, type NajmAppProviderProps };