@karni/ui 0.3.1 → 0.4.0

package/dist/src/components/resource/table/url-state.d.ts

@@ -0,0 +1,67 @@
+import { FilterValue } from '../../../hooks/types';
+import { FieldDef } from '../../../schema/types';
+/**
+ * Where a table keeps its view state. The table only touches its own
+ * (namespaced) keys.
+ *
+ * An adapter for a router reads the router's current search params in
+ * `read`, navigates in `write`, and either calls the `subscribe` listener
+ * when the params change or simply passes a new store object on each change
+ * (the table re-reads whenever the store changes).
+ */
+export interface ResourceTableStateStore {
+    /** Every current query value by key. */
+    read(): Readonly<Record<string, string>>;
+    /**
+     * Merge `changes` into the URL (`null` removes a key). `push` adds a
+     * history entry (page, sort, filter changes). Otherwise the current entry
+     * is replaced (a search refined while typing, a page clamped).
+     */
+    write(changes: Readonly<Record<string, string | null>>, options: {
+        push: boolean;
+    }): void;
+    /** Call `onChange` when the values change outside the table. Returns an unsubscribe. */
+    subscribe(onChange: () => void): () => void;
+}
+/**
+ * The default store: the browser's URL through `window.history`
+ * (`pushState` / `replaceState`, `popstate` for Back and Forward). Other
+ * query parameters and the hash are kept.
+ */
+export declare function createHistoryStateStore(): ResourceTableStateStore;
+/** The view a table shows: what the URL holds for it. */
+export interface TableView {
+    page: number;
+    pageSize: number;
+    /** DRF ordering ("-starts_at,title"), where "" is "no ordering". */
+    ordering: string;
+    search: string;
+    filters: Readonly<Record<string, FilterValue>>;
+}
+export interface TableViewDefaults {
+    pageSize: number;
+    ordering: string;
+    /** Page sizes a URL may ask for. Anything else falls back to the default. */
+    pageSizes: readonly number[];
+}
+/** Encodes one filter value for the URL (arrays comma-joined). */
+export declare function encodeFilter(value: FilterValue): string | null;
+/** Decodes a URL value back to the type the filter control and the API expect. */
+export declare function decodeFilter(raw: string, field: FieldDef): FilterValue;
+/** Drops cleared filters so "no filter" has one representation. */
+export declare function compactFilters(filters: Readonly<Record<string, FilterValue>>): Record<string, FilterValue>;
+export type SetTableView = (patch: Partial<TableView>, options: {
+    push: boolean;
+}) => void;
+export interface UseTableViewOptions {
+    /** False keeps the view in component state only (the URL is untouched). */
+    syncUrl: boolean;
+    /** Where the URL state lives. Default: `window.history`. */
+    store?: ResourceTableStateStore;
+    namespace: string;
+    defaults: TableViewDefaults;
+    /** The fields the filter bar offers: only these are read from the URL. */
+    filterFields: readonly FieldDef[];
+}
+/** The table's view state, from the URL (or component state) with a setter. */
+export declare function useTableView(options: UseTableViewOptions): [TableView, SetTableView];

package/dist/src/components/resource/table/use-container-width.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The width of an element, kept current with a ResizeObserver. ResourceTable
+ * switches to cards from its own container's width, not the viewport's, so a
+ * table in a narrow sidebar or a split view lays out for the room it has.
+ * `undefined` until measured (and where there is no layout, as in jsdom), so
+ * the table keeps its default layout rather than guessing.
+ * Internal to @karni/ui.
+ */
+import * as React from "react";
+export declare function useContainerWidth(ref: React.RefObject<HTMLElement | null>): number | undefined;

package/dist/src/components/resource/testapp-fixtures.d.ts

@@ -0,0 +1,78 @@
+import { RequestHandler } from 'msw';
+import { ChangeHistoryPage } from '../../hooks/useChangeHistory';
+import { ImportDescription, ImportJob } from '../../hooks/useResourceImport';
+/** The OpenAPI document `/api/schema/` serves for the testapp (a superuser's view). */
+export declare const testappOpenApi: Record<string, unknown>;
+/**
+ * The per-role document of a role `Karni.field_roles` hides `fields` of the
+ * Event from: the fields are absent from it, as they are from the payload.
+ */
+export declare function openApiHidingEventFields(fields: readonly string[]): Record<string, unknown>;
+export declare const DEMO_EVENT_ID = "3f6f75d8-f305-48a8-9587-32884b211936";
+export declare const demoVenue: {
+    id: string;
+    name: string;
+    city: string;
+};
+/** A testapp Event as `GET /api/events/<id>/?expand=venue` returns it. */
+export declare const demoEvent: Record<string, unknown>;
+/** The same Event as a role that may not read `fields` receives it: the keys are absent, not null. */
+export declare function eventHiding(fields: readonly string[]): Record<string, unknown>;
+/**
+ * How one endpoint answers: "ok", "pending" (never answers: the loading
+ * state), "network" (the request fails, as offline), a status with an
+ * optional DRF body, or a delay before answering "ok".
+ */
+export type Outcome = "ok" | "pending" | "network" | {
+    status: number;
+    body?: unknown;
+} | {
+    delayMs: number;
+};
+/** The 404 Karni answers for a row outside the read scope: the scope is named, existence is not. */
+export declare const SCOPED_NOT_FOUND: {
+    readonly status: 404;
+    readonly body: {
+        readonly detail: "No Event matches the given query. Rows are limited by EventViewSet.access read=Granted().";
+    };
+};
+export interface DetailBackend {
+    schema?: Outcome;
+    /** The document `/api/schema/` serves (default: the testapp snapshot). */
+    openApi?: Record<string, unknown>;
+    event?: Outcome;
+    /** The payload `GET /api/events/<id>/` answers (default: demoEvent). */
+    record?: Record<string, unknown>;
+    remove?: Outcome;
+    history?: Outcome;
+    historyPage?: ChangeHistoryPage;
+}
+/** msw handlers for the schema, one Event, its delete and its history. */
+export declare function detailBackend(options?: DetailBackend): RequestHandler[];
+export declare const demoHistory: ChangeHistoryPage;
+/** What `GET /api/events/import/` answers. */
+export declare const demoImportDescription: ImportDescription;
+export declare const DEMO_JOB_ID = "6b1f0e9a-3c2d-4e5f-8a7b-9c0d1e2f3a4b";
+/** An import job in any state (default: just uploaded). */
+export declare function demoJob(partial?: Partial<ImportJob>): ImportJob;
+/** A preview: most rows import, two are refused with the reason. */
+export declare const previewedJob: ImportJob;
+export declare const doneJob: ImportJob;
+export interface ImportBackend {
+    describe?: Outcome;
+    upload?: Outcome;
+    /** The job uploads create (default: demoJob()). */
+    uploaded?: ImportJob;
+    /** Answers of `GET .../import/<job>/` after a preview or commit started, in turn: polling. */
+    polls?: readonly ImportJob[];
+    preview?: Outcome;
+    previewed?: ImportJob;
+    commit?: Outcome;
+    committed?: ImportJob;
+}
+/**
+ * msw handlers for `/api/events/import/…`: describe, upload, poll, preview,
+ * commit. `GET .../import/<job>/` answers the job as the last step left it
+ * (after `polls`, while those last), as the backend does.
+ */
+export declare function importBackend(options?: ImportBackend): RequestHandler[];

package/dist/src/components/stat/stat.d.ts

@@ -1,24 +1,54 @@
 import * as React from "react";
+/** What the `Label`, `Value` and `Icon` slots receive. */
+export interface StatSlotProps {
+    children: React.ReactNode;
+}
+/** What the `Delta` slot receives. */
+export interface StatDeltaProps {
+    /** The `delta` prop: a number, or any node. */
+    delta: number | React.ReactNode;
+    /** The `formatDelta` prop (or the default signed format). */
+    formatDelta: (delta: number) => string;
+}
+/** The parts of the tile a project can replace (`slots={{ Delta: GoodWhenDown }}`). */
+export interface StatSlots {
+    /** What the number measures. */
+    Label: React.ComponentType<StatSlotProps>;
+    /** The headline value. */
+    Value: React.ComponentType<StatSlotProps>;
+    /** The change indicator. The default treats a rise as neutral and a fall as destructive. */
+    Delta: React.ComponentType<StatDeltaProps>;
+    /** Wraps `icon`. Decorative, hidden from assistive tech. */
+    Icon: React.ComponentType<StatSlotProps>;
+}
 export interface StatProps extends React.HTMLAttributes<HTMLDivElement> {
     /** What the number measures ("Active users"). */
     label: React.ReactNode;
-    /** The headline value — preformatted string or any node. */
+    /** The headline value: a preformatted string or any node. */
     value: React.ReactNode;
     /**
-     * Change indicator. A number renders a signed figure with an up/down arrow
-     * (negative numbers use the destructive token) plus screen-reader context;
-     * any other node renders verbatim in the delta slot.
+     * Change indicator. A number renders a signed figure with an up, down or
+     * flat marker (negative numbers use the destructive token) plus
+     * screen-reader context. Any other node renders verbatim in the delta slot.
      */
     delta?: number | React.ReactNode;
     /** Formats a numeric `delta` (default: signed, locale formatted). */
     formatDelta?: (delta: number) => string;
     /** Optional icon slot, top-right. */
     icon?: React.ReactNode;
+    /** True while the value loads: a placeholder replaces the value and the delta. */
+    loading?: boolean;
+    /** Replaces the Label, Value, Delta or Icon. See StatSlots. */
+    slots?: Partial<StatSlots>;
 }
+/** The default pieces of the tile, for wrapping one. */
+export declare const defaultStatSlots: StatSlots;
 /**
  * KPI tile: label, value, optional delta and icon.
  *
- * Escape hatches: `value`/`delta`/`icon` accept arbitrary nodes,
- * `formatDelta` overrides numeric formatting, `className` merges via cn().
+ * Escape hatches: `slots` replaces the Label, Value, Delta or Icon (a Delta
+ * for metrics where down is good, say), `value`/`delta`/`icon` accept
+ * arbitrary nodes, `formatDelta` overrides numeric formatting, and `className`
+ * merges via cn().
  */
 export declare const Stat: React.ForwardRefExoticComponent<StatProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/toast/toast-store.d.ts

@@ -31,6 +31,6 @@ export declare function subscribeToToasts(listener: Listener): () => void;
 export declare function getToasts(): readonly ToastInstance[];
 export declare function dismissToast(id?: string): void;
 export declare function addToast(options: ToastOptions): ToastHandle;
-/** Test helper — clears all toasts and listeners' state (not in the barrel). */
+/** Test helper: clears all toasts and listeners' state (not in the barrel). */
 export declare function resetToastStore(): void;
 export {};

package/dist/src/components/toast/toaster.d.ts

@@ -1,8 +1,9 @@
 import { VariantProps } from '../../lib/variants';
+import { ToastVariant } from './toast-store';
 import * as React from "react";
 /**
- * Per-variant toast styling — colors resolve through --karni-* tokens only
- * (success leans on primary, error on destructive, info on muted).
+ * Per-variant toast styling, with colors that resolve through --karni-* tokens
+ * only (success leans on primary, error on destructive, info on muted).
  */
 export declare const toastVariants: import('../..').VariantFn<{
     variant: {
@@ -13,6 +14,28 @@ export declare const toastVariants: import('../..').VariantFn<{
     };
 }>;
 export type ToastVariantProps = VariantProps<typeof toastVariants>;
+/** What the `Title` and `Description` slots receive. */
+export interface ToasterSlotProps {
+    children: React.ReactNode;
+    variant: ToastVariant;
+}
+/** What the `CloseButton` slot receives. */
+export interface ToasterCloseButtonProps {
+    /** Its accessible name ("Dismiss"). */
+    label: string;
+    variant: ToastVariant;
+    /** Removes the toast. */
+    dismiss: () => void;
+}
+/** The parts of each toast a project can replace (`slots={{ CloseButton: MyClose }}`). */
+export interface ToasterSlots {
+    Title: React.ComponentType<ToasterSlotProps>;
+    Description: React.ComponentType<ToasterSlotProps>;
+    /** The top-right dismiss button. */
+    CloseButton: React.ComponentType<ToasterCloseButtonProps>;
+}
+/** The default pieces of a toast, for wrapping one. */
+export declare const defaultToasterSlots: ToasterSlots;
 export interface ToasterProps {
     /** Auto-dismiss duration in ms for toasts without their own (default 5000). */
     duration?: number;
@@ -20,14 +43,24 @@ export interface ToasterProps {
     swipeDirection?: "right" | "left" | "up" | "down";
     /** Accessible label prefix announced with each toast (Radix Provider). */
     label?: string;
-    /** Extra classes for the viewport (position/stacking escape hatch). */
+    /** Extra classes for the viewport, the list the toasts render in. */
+    className?: string;
+    /** Same as `className` (kept for compatibility). */
     viewportClassName?: string;
     /** Extra classes for every toast root. */
     toastClassName?: string;
+    /** Replaces the Title, Description or CloseButton of every toast (see ToasterSlots). */
+    slots?: Partial<ToasterSlots>;
 }
 /**
  * Renders the toasts pushed through useToast(). Mount exactly one near the
- * app root. Position defaults to the bottom-right corner; override with
- * `viewportClassName` (it merges via cn(), so e.g. "top-0 bottom-auto" wins).
+ * app root. Position defaults to the bottom-right corner. Override it with
+ * `className` (it merges via cn(), so e.g. "top-0 bottom-auto" wins).
+ *
+ * Keyboard and screen readers: an error is announced at once (assertive),
+ * other toasts politely. F8 moves focus to the toasts. Tab reaches each one
+ * and its buttons, and Escape dismisses the focused toast. A toast's timer
+ * pauses while the pointer is over the toasts or focus is inside them, and
+ * while the window is in the background.
  */
-export declare function Toaster({ duration, swipeDirection, label, viewportClassName, toastClassName, }: ToasterProps): React.ReactElement;
+export declare function Toaster({ duration, swipeDirection, label, className, viewportClassName, toastClassName, slots, }: ToasterProps): React.ReactElement;

package/dist/src/components/toast/use-toast.d.ts

@@ -18,7 +18,7 @@ export interface UseToastResult {
  * Imperative toast API + the live toast list.
  *
  * Requires a mounted <Toaster/> somewhere in the tree to actually render the
- * toasts; the functions themselves are stable module-level references, safe
+ * toasts. The functions themselves are stable module-level references, safe
  * to use in effects and callbacks without dependency churn.
  */
 export declare function useToast(): UseToastResult;

package/dist/src/hooks/keys.d.ts

@@ -1,24 +1,24 @@
 import { ResourceItemParams, ResourceListParams } from './types';
-/** TanStack Query keys for the schema, a resource, its lists and its items; invalidate `karniKeys.resource(name)` to refresh every view of a resource. */
+/** TanStack Query keys for the schema, a resource, its lists and its items (invalidate `karniKeys.resource(name)` to refresh every view of a resource). */
 export declare const karniKeys: {
     /** Cache key of the parsed OpenAPI schema document. */
     schema(): readonly unknown[];
     /**
-     * The invalidation root for one resource — every list and detail key of
+     * The invalidation root for one resource. Every list and detail key of
      * `resource` lives under this prefix.
      */
     resource(resource: string): readonly unknown[];
     /**
      * Key for one list page. Params are normalized (D4): undefined/null
      * dropped, keys sorted recursively, values stringified as they hit the
-     * query string — `{search: "x", page: 2}` and `{page: 2, search: "x"}`
+     * query string, so `{search: "x", page: 2}` and `{page: 2, search: "x"}`
      * share one entry.
      */
     list(resource: string, params?: ResourceListParams): readonly unknown[];
     /**
      * Key for one item. The id is always stringified, so `detail("events", 5)`
      * and `detail("events", "5")` share one entry. Params (expand) append a
-     * normalized fifth element — see the module docs.
+     * normalized fifth element (see the module docs).
      */
     detail(resource: string, id: string | number, params?: ResourceItemParams): readonly unknown[];
 };

package/dist/src/hooks/multipart.d.ts

@@ -2,20 +2,20 @@
  * Mutation body encoding (contract D2) + PATCH file-URL omission.
  *
  * D2: after the form's `transformSubmit` has run, a payload containing any
- * top-level `File` (or an array containing one) is encoded as `FormData`;
- * everything else is sent as JSON. FormData rules:
+ * top-level `File` (or an array containing one) is encoded as `FormData`.
+ * Everything else is sent as JSON. FormData rules:
  * - arrays append as repeated keys,
  * - plain objects/arrays-of-objects (json fields) are JSON-stringified,
  * - numbers/booleans are stringified,
- * - `null`/`undefined` entries are OMITTED — multipart cannot express null
- *   (DRF would parse the string "null"); to null a field, send a JSON PATCH
+ * - `null`/`undefined` entries are OMITTED: multipart cannot express null
+ *   (DRF would parse the string "null"). To null a field, send a JSON PATCH
  *   without the file field instead,
  * - Content-Type is never set manually: fetch derives the multipart boundary.
  *
  * PATCH omission (D2): a string value on a file-kind field is the unchanged
- * display URL the backend returned (D1: response-side `format: uri`); sending
+ * display URL the backend returned (D1: response-side `format: uri`). Sending
  * it back would 400 ("not a file"), so it is dropped from PATCH payloads.
- * Field kinds come from the cached parsed schema when present; without it the
+ * Field kinds come from the cached parsed schema when present. Without it the
  * payload passes through untouched (graceful degradation).
  *
  * Internal module: not re-exported from the barrel.
@@ -37,8 +37,8 @@ export declare function encodeBody(values: Record<string, unknown>): Record<stri
  */
 export declare function fileFieldNames(cachedSchema: unknown, resource: string): ReadonlySet<string>;
 /**
- * Drops unchanged file values — strings (or arrays of strings) on file-kind
- * fields are the backend's display URLs, not new uploads — from a PATCH
- * payload (D2).
+ * Drops unchanged file values from a PATCH payload (D2). Strings (or arrays
+ * of strings) on file-kind fields are the backend's display URLs, not new
+ * uploads.
  */
 export declare function omitUnchangedFileUrls(values: Record<string, unknown>, fileFields: ReadonlySet<string>): Record<string, unknown>;

package/dist/src/hooks/params.d.ts

@@ -21,5 +21,5 @@ export declare function buildItemQuery(params?: ResourceItemParams): Record<stri
 export declare function normalizeParams(value: Record<string, unknown>): NormalizedParams;
 /** `/events/` for resource "events" (the DRF router prefix, api B13). */
 export declare function listPath(resource: string): string;
-/** `/events/5/` — ids are encoded so UUIDs and slugs are safe. */
+/** `/events/5/`. Ids are encoded so UUIDs and slugs are safe. */
 export declare function detailPath(resource: string, id: string | number): string;

package/dist/src/hooks/types.d.ts

@@ -8,7 +8,7 @@ export interface Paginated<T> {
 }
 /**
  * A single filter value as accepted by the backend's FilterSet (api B5/B6).
- * Arrays become repeated query keys; `null`/`undefined` entries are dropped
+ * Arrays become repeated query keys. `null`/`undefined` entries are dropped
  * (they mean "no constraint", not "filter by null").
  */
 export type FilterValue = string | number | boolean | ReadonlyArray<string | number | boolean> | null | undefined;
@@ -20,7 +20,7 @@ export interface ResourceListParams {
     pageSize?: number;
     /** DRF ordering expression, e.g. `"-created_at"` (`ordering`). */
     ordering?: string;
-    /** Full-text search term (`search`); empty string is treated as unset. */
+    /** Full-text search term (`search`). An empty string is treated as unset. */
     search?: string;
     /** Extra filter params, spread flat into the query string. Explicit params above win on a name clash. */
     filters?: Record<string, FilterValue>;
@@ -34,7 +34,7 @@ export interface ResourceItemParams {
 export interface ResourceMutationsOptions {
     /**
      * Extra query keys invalidated after any successful mutation, on top of
-     * ["karni", resource]. Never pass the bare ["karni"] root (D4) — it would
+     * ["karni", resource]. Never pass the bare ["karni"] root (D4). It would
      * also invalidate the cached schema document.
      */
     invalidateKeys?: readonly QueryKey[];

package/dist/src/hooks/useChangeHistory.d.ts

@@ -1,5 +1,6 @@
 import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
-export type ChangeAction = "create" | "update" | "delete" | "restore";
+/** `transition`: a StateField moved along a declared transition (`diff` holds `[from, to]`). */
+export type ChangeAction = "create" | "update" | "delete" | "restore" | "transition";
 export interface ChangeLogEntry {
     id: number;
     timestamp: string;
@@ -8,7 +9,7 @@ export interface ChangeLogEntry {
         email?: string;
     } | null;
     action: ChangeAction;
-    /** `{ field: [old, new] }`; a redacted field carries `"[redacted]"` on both sides. */
+    /** `{ field: [old, new] }`. A redacted field carries `"[redacted]"` on both sides. */
     diff: Record<string, [unknown, unknown]>;
     fields_changed: string[];
 }

package/dist/src/hooks/useResourceImport.d.ts

@@ -26,7 +26,7 @@ export interface ImportDescription {
     fields: ImportColumn[];
     /** The mapping the user last confirmed for this resource (header → field). */
     mapping: Record<string, string>;
-    /** Files with more rows than this run in Celery; poll the job. */
+    /** Files with more rows than this run in Celery. Poll the job. */
     inline_rows: number;
     max_rows: number;
     key: string | null;
@@ -91,7 +91,7 @@ export interface UseImportJobOptions {
 export declare function useImportJob(resource: string, jobId: string | undefined, options?: UseImportJobOptions): UseQueryResult<ImportJob>;
 export interface UploadImportInput {
     file: File;
-    /** An explicit mapping; otherwise the backend suggests or remembers one. */
+    /** An explicit mapping. Otherwise the backend suggests or remembers one. */
     mapping?: Record<string, string>;
 }
 export interface PreviewImportInput {

package/dist/src/hooks/useResourceMutations.d.ts

@@ -1,6 +1,6 @@
 import { UseMutationResult } from '@tanstack/react-query';
 import { ResourceMutationsOptions } from './types';
-/** Result bundle — the three mutations, each a full TanStack mutation object. */
+/** Result bundle: the three mutations, each a full TanStack mutation object. */
 export interface ResourceMutations<T> {
     create: UseMutationResult<T, unknown, Record<string, unknown>>;
     update: UseMutationResult<T, unknown, {
@@ -9,5 +9,5 @@ export interface ResourceMutations<T> {
     }>;
     remove: UseMutationResult<void, unknown, string | number>;
 }
-/** Create, update and remove mutations for a resource; each success refreshes the resource's cached lists and items. */
+/** Create, update and remove mutations for a resource that refresh the resource's cached lists and items on each success. */
 export declare function useResourceMutations<T = Record<string, unknown>>(resource: string, options?: ResourceMutationsOptions): ResourceMutations<T>;

package/dist/src/hooks/useUnsavedChangesGuard.d.ts

@@ -0,0 +1,31 @@
+/** What the leave warning says. Browsers show their own text for reloads and closed tabs. */
+export declare const UNSAVED_CHANGES_MESSAGE = "You have unsaved changes. Leave without saving them?";
+export interface UseUnsavedChangesGuardOptions {
+    /** Controlled mode: whether something is unsaved. Omit it and call `setDirty` instead. */
+    dirty?: boolean;
+    /** Turns the guard off without unmounting it (an opt-out). Default true. */
+    enabled?: boolean;
+    /** Warn on reload, tab close and links out of the app (`beforeunload`). Default true. */
+    beforeUnload?: boolean;
+    /** The question `shouldBlock` asks. Default UNSAVED_CHANGES_MESSAGE. */
+    message?: string;
+    /** Asks the user whether to leave and returns true to leave. Default `window.confirm`. */
+    confirm?: (message: string) => boolean;
+}
+export interface UnsavedChangesGuard {
+    /** Whether something is unsaved (re-renders when it changes). */
+    dirty: boolean;
+    /** Reports the form's state. Pass it as ResourceForm's `onDirtyChange`. */
+    setDirty: (dirty: boolean) => void;
+    /** The latest state, read synchronously (for a router blocker's callback). */
+    isDirty: () => boolean;
+    /**
+     * For a router's blocker: true when there are unsaved changes and the user
+     * chose to stay, false (let the navigation happen) otherwise.
+     */
+    shouldBlock: () => boolean;
+    /** The question asked before leaving. */
+    message: string;
+}
+/** Tracks unsaved changes, warns on reload or close, and gives a router blocker what it needs. */
+export declare function useUnsavedChangesGuard(options?: UseUnsavedChangesGuardOptions): UnsavedChangesGuard;

package/dist/src/index.d.ts

@@ -4,13 +4,24 @@
  * Every public name of the package is re-exported here, explicitly, so that
  * scripts/generate-manifest.mjs can parse this file and emit dist/manifest.json
  * (contract D7). Keep exports in the explicit `export { ... } from` /
- * `export type { ... } from` form — no `export *`.
+ * `export type { ... } from` form, never `export *`.
  */
 export { cn } from './lib/cn';
 export { registerComponentRole, getRoleRegistry } from './lib/roles';
 export type { RegisterComponentRoleOptions } from './lib/roles';
 export { variants } from './lib/variants';
 export type { VariantShape, VariantSelection, VariantsConfig, VariantFn, VariantProps, } from './lib/variants';
+export { describeError, errorSummary } from './states/describe-error';
+export type { KarniErrorContext, KarniErrorDescription, KarniErrorKind, } from './states/describe-error';
+export { ErrorState, PermissionDenied } from './states/ErrorState';
+export type { ErrorSlotProps, ErrorStateProps, PermissionDeniedProps } from './states/ErrorState';
+export { PendingButton } from './states/PendingButton';
+export type { PendingButtonProps } from './states/PendingButton';
+export { SLOW_AFTER_MS, useDelayedFlag, useOnlineStatus } from './states/hooks';
+export { KARNI_THEME_SCRIPT, THEME_STORAGE_KEY, ThemeProvider, ThemeToggle, useTheme, } from './theme/theme';
+export type { ResolvedTheme, ThemePreference, ThemeProviderProps, ThemeToggleProps, } from './theme/theme';
+export { KarniPrimitivesProvider, useKarniPrimitives } from './primitives/registry';
+export type { KarniPrimitiveOverrides, KarniPrimitiveRole, KarniPrimitives, KarniPrimitivesProviderProps, KarniSelectParts, } from './primitives/registry';
 export { Button, buttonVariants } from './components/primitives/button';
 export type { ButtonProps, ButtonVariantProps } from './components/primitives/button';
 export { Input } from './components/primitives/input';
@@ -31,21 +42,28 @@ export { Skeleton } from './components/primitives/skeleton';
 export type { SkeletonProps } from './components/primitives/skeleton';
 export { ResourceTable } from './components/resource/ResourceTable';
 export type { ResourceTableProps, ResourceColumn, BulkAction, } from './components/resource/ResourceTable';
-export { ResourceForm } from './components/resource/ResourceForm';
-export type { ResourceFormProps, FieldOverride, KarniFieldProps, } from './components/resource/ResourceForm';
-export { ResourceDetail } from './components/resource/ResourceDetail';
-export type { ResourceDetailProps, ResourceDetailFieldOverride, } from './components/resource/ResourceDetail';
-export { ResourceSelect } from './components/resource/ResourceSelect';
-export type { ResourceSelectProps } from './components/resource/ResourceSelect';
-export { ChangeHistory } from './components/resource/history/ChangeHistory';
-export type { ChangeHistoryProps } from './components/resource/history/ChangeHistory';
+export { createHistoryStateStore, defaultResourceTableSlots, } from './components/resource/ResourceTable';
+export type { BulkActionReturn, BulkOutcome, BulkResult, ResourceTableActiveFilter, ResourceTableBulkActionsProps, ResourceTableCardField, ResourceTableDensity, ResourceTableForbiddenProps, ResourceTableKeyboardNavigation, ResourceTableLoadingProps, ResourceTableNoRecordsProps, ResourceTableNoResultsProps, ResourceTableOfflineProps, ResourceTablePaginationProps, ResourceTableRowCardProps, ResourceTableSlots, ResourceTableStateStore, } from './components/resource/ResourceTable';
+export type { KarniAccessRule } from './schema/types';
+export { ResourceForm, defaultResourceFormSlots } from './components/resource/ResourceForm';
+export type { ResourceFormProps, ResourceFormSlots, ResourceFormErrorSummaryProps, ResourceFormFieldError, ResourceFormForbiddenProps, ResourceFormLoadingProps, ResourceFormSubmitErrorProps, FieldOverride, KarniFieldProps, } from './components/resource/ResourceForm';
+export { UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from './hooks/useUnsavedChangesGuard';
+export type { UnsavedChangesGuard, UseUnsavedChangesGuardOptions, } from './hooks/useUnsavedChangesGuard';
+export { ResourceDetail, defaultResourceDetailSlots } from './components/resource/ResourceDetail';
+export type { ResourceDetailProps, ResourceDetailFieldOverride, ResourceDetailSlots, ResourceDetailLoadingProps, ResourceDetailErrorProps, ResourceDetailNotFoundProps, ResourceDetailDeletedProps, ResourceDetailEmptyValueProps, ResourceDetailDeleteDialogProps, } from './components/resource/ResourceDetail';
+export { ResourceSelect, defaultResourceSelectSlots } from './components/resource/ResourceSelect';
+export type { ResourceSelectProps, ResourceSelectSlots, ResourceSelectChipProps, ResourceSelectEmptyProps, ResourceSelectLoadingProps, ResourceSelectOptionProps, } from './components/resource/ResourceSelect';
+export { ChangeHistory, defaultChangeHistorySlots, } from './components/resource/history/ChangeHistory';
+export type { ChangeHistoryProps, ChangeHistorySlots, ChangeHistoryLoadingProps, ChangeHistoryEmptyProps, ChangeHistoryEntryProps, } from './components/resource/history/ChangeHistory';
 export { useChangeHistory, changeHistoryKey } from './hooks/useChangeHistory';
 export type { ChangeAction, ChangeLogEntry, ChangeHistoryPage, ChangeHistoryParams, } from './hooks/useChangeHistory';
-export { ResourceImport } from './components/resource/import/ResourceImport';
-export type { ResourceImportProps } from './components/resource/import/ResourceImport';
+export { ResourceImport, defaultResourceImportSlots, } from './components/resource/import/ResourceImport';
+export type { ResourceImportProps, ResourceImportSlots, ResourceImportLoadingProps, ImportProgressProps, ImportSummaryProps, ImportProblemsProps, ImportConfirmProps, } from './components/resource/import/ResourceImport';
 export { useImportDescribe, useImportJob, useImportActions, downloadResourceExport, downloadImportTemplate, importDescribeKey, importJobKey, isImportInFlight, } from './hooks/useResourceImport';
 export type { ExportFormat, ImportActions, ImportColumn, ImportColumnKind, ImportDescription, ImportJob, ImportProblem, ImportResult, ImportStatus, PreviewImportInput, UploadImportInput, UseImportJobOptions, } from './hooks/useResourceImport';
 export { displayLabel } from './components/resource/displayLabel';
+export { EmptyValue, EMPTY_VALUE_LABEL } from './components/resource/empty-value';
+export type { EmptyValueProps } from './components/resource/empty-value';
 export { AUDIT_FIELDS } from './components/resource/audit-fields';
 export { karniKeys } from './hooks/keys';
 export { useResourceList } from './hooks/useResourceList';
@@ -63,33 +81,33 @@ export { zodFor } from './schema/zod';
 export type { FieldKind, RelationRef, FieldDef, OperationDef, ResourceSchema, } from './schema/types';
 export { AuthProvider, useAuth } from './auth/provider';
 export type { AuthProviderProps, AuthContextValue } from './auth/provider';
-export { AuthGuard } from './auth/AuthGuard';
-export type { AuthGuardProps } from './auth/AuthGuard';
-export { LoginForm } from './auth/LoginForm';
-export type { LoginFormProps } from './auth/LoginForm';
+export { AuthGuard, defaultAuthGuardSlots } from './auth/AuthGuard';
+export type { AuthGuardProps, AuthGuardSlots, AuthGuardAnonymousProps, AuthGuardDeniedProps, } from './auth/AuthGuard';
+export { LoginForm, defaultLoginFormSlots } from './auth/LoginForm';
+export type { LoginFormProps, LoginFormSlots, LoginFormErrorProps } from './auth/LoginForm';
 export { usePermission } from './auth/usePermission';
 export type { PermissionHelpers } from './auth/usePermission';
 export { createLocalStorageTokenStorage, createMemoryTokenStorage } from './auth/storage';
 export type { TokenStorage } from './auth/storage';
 export type { KarniUser, AuthStatus, LoginResult } from './auth/types';
-export { Page } from './components/page/page';
-export type { PageProps } from './components/page/page';
-export { Layout } from './components/layout/layout';
-export type { LayoutProps, LayoutNavItem } from './components/layout/layout';
+export { Page, defaultPageSlots } from './components/page/page';
+export type { PageProps, PageSlots, PageHeaderProps, PageSlotContentProps, } from './components/page/page';
+export { Layout, defaultLayoutSlots } from './components/layout/layout';
+export type { LayoutProps, LayoutNavItem, LayoutSlots, LayoutHeaderProps, LayoutSidebarProps, LayoutNavLinkProps, LayoutMobileDrawerProps, LayoutSkipLinkProps, LayoutRouteFocusOptions, } from './components/layout/layout';
 export { KarniMark } from './components/brand/karni-mark';
 export type { KarniMarkProps } from './components/brand/karni-mark';
-export { Modal, ModalClose } from './components/modal/modal';
-export type { ModalProps } from './components/modal/modal';
-export { Toaster, toastVariants } from './components/toast/toaster';
-export type { ToasterProps, ToastVariantProps } from './components/toast/toaster';
+export { Modal, ModalClose, ModalTitle, ModalDescription, defaultModalSlots, } from './components/modal/modal';
+export type { ModalProps, ModalSlots, ModalHeaderProps, ModalFooterProps, ModalCloseButtonProps, } from './components/modal/modal';
+export { Toaster, toastVariants, defaultToasterSlots } from './components/toast/toaster';
+export type { ToasterProps, ToastVariantProps, ToasterSlots, ToasterSlotProps, ToasterCloseButtonProps, } from './components/toast/toaster';
 export { useToast } from './components/toast/use-toast';
 export type { UseToastResult } from './components/toast/use-toast';
 export type { ToastHandle, ToastInstance, ToastOptions, ToastVariant, } from './components/toast/toast-store';
-export { EmptyState } from './components/empty-state/empty-state';
-export type { EmptyStateProps } from './components/empty-state/empty-state';
-export { FileUpload } from './components/file-upload/FileUpload';
-export type { FileUploadProps, FileUploadRejectReason } from './components/file-upload/FileUpload';
-export { Stat } from './components/stat/stat';
-export type { StatProps } from './components/stat/stat';
-export { DataChart } from './components/chart/data-chart';
-export type { DataChartProps, DataChartKind, DataChartPoint, DataChartSeries, DataChartTooltipContext, } from './components/chart/data-chart';
+export { EmptyState, defaultEmptyStateSlots } from './components/empty-state/empty-state';
+export type { EmptyStateProps, EmptyStateSlots, EmptyStateSlotProps, } from './components/empty-state/empty-state';
+export { FileUpload, defaultFileUploadSlots } from './components/file-upload/FileUpload';
+export type { FileUploadProps, FileUploadRejectReason, FileUploadSlots, FileUploadDropzoneProps, FileUploadFileRowProps, } from './components/file-upload/FileUpload';
+export { Stat, defaultStatSlots } from './components/stat/stat';
+export type { StatProps, StatSlots, StatSlotProps, StatDeltaProps } from './components/stat/stat';
+export { DataChart, defaultDataChartSlots } from './components/chart/data-chart';
+export type { DataChartProps, DataChartKind, DataChartPoint, DataChartSeries, DataChartTooltipContext, DataChartSlots, DataChartTooltipProps, DataChartLegendProps, DataChartEmptyProps, DataChartLoadingProps, } from './components/chart/data-chart';