@karni/ui 0.0.0-stage → 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/table/use-debounced-value.d.ts

@@ -0,0 +1 @@
+export declare function useDebouncedValue<T>(value: T, delayMs: number): T;

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

@@ -0,0 +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: a preformatted string or any node. */
+    value: React.ReactNode;
+    /**
+     * 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: `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

@@ -0,0 +1,36 @@
+import type * as React from "react";
+/**
+ * Module-level toast store.
+ *
+ * `useToast()` can be called anywhere (no provider requirement beyond a
+ * mounted <Toaster/>): toasts are pushed into this store and every mounted
+ * Toaster/useToast subscriber re-renders via useSyncExternalStore.
+ */
+export type ToastVariant = "default" | "success" | "error" | "info";
+export interface ToastOptions {
+    /** Stable id (defaults to an auto-generated one). Re-using an id replaces. */
+    id?: string;
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    variant?: ToastVariant;
+    /** Per-toast auto-dismiss override in ms (Toaster default otherwise). */
+    duration?: number;
+    /** Action slot (e.g. an "Undo" button), rendered inside the toast. */
+    action?: React.ReactNode;
+}
+export interface ToastInstance extends ToastOptions {
+    id: string;
+    variant: ToastVariant;
+}
+export interface ToastHandle {
+    id: string;
+    dismiss: () => void;
+}
+type Listener = () => void;
+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). */
+export declare function resetToastStore(): void;
+export {};

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

@@ -0,0 +1,66 @@
+import { VariantProps } from '../../lib/variants';
+import { ToastVariant } from './toast-store';
+import * as React from "react";
+/**
+ * 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: {
+        default: string;
+        success: string;
+        error: string;
+        info: string;
+    };
+}>;
+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;
+    /** Swipe-to-dismiss direction (default "right"). */
+    swipeDirection?: "right" | "left" | "up" | "down";
+    /** Accessible label prefix announced with each toast (Radix Provider). */
+    label?: string;
+    /** 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 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, className, viewportClassName, toastClassName, slots, }: ToasterProps): React.ReactElement;

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

@@ -0,0 +1,24 @@
+import { ToastHandle, ToastInstance, ToastOptions } from './toast-store';
+import * as React from "react";
+export interface UseToastResult {
+    /** Currently visible toasts (rendered by <Toaster/>). */
+    toasts: readonly ToastInstance[];
+    /** Full-control entry point: show any ToastOptions. */
+    toast: (options: ToastOptions) => ToastHandle;
+    /** Shorthand: success variant. */
+    success: (title: React.ReactNode, options?: Omit<ToastOptions, "variant">) => ToastHandle;
+    /** Shorthand: error variant. */
+    error: (title: React.ReactNode, options?: Omit<ToastOptions, "variant">) => ToastHandle;
+    /** Shorthand: info variant. */
+    info: (title: React.ReactNode, options?: Omit<ToastOptions, "variant">) => ToastHandle;
+    /** Dismiss one toast by id, or all when called without arguments. */
+    dismiss: (id?: string) => void;
+}
+/**
+ * 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
+ * to use in effects and callbacks without dependency churn.
+ */
+export declare function useToast(): UseToastResult;

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

@@ -0,0 +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). */
+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
+     * `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, 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).
+     */
+    detail(resource: string, id: string | number, params?: ResourceItemParams): readonly unknown[];
+};

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

@@ -0,0 +1,44 @@
+/**
+ * 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:
+ * - 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
+ *   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
+ * 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
+ * payload passes through untouched (graceful degradation).
+ *
+ * Internal module: not re-exported from the barrel.
+ */
+/** True when any top-level value is a File, or an array containing one (D2). */
+export declare function containsFile(values: Record<string, unknown>): boolean;
+/** Encodes a payload as FormData per the D2 rules above. */
+export declare function toFormData(values: Record<string, unknown>): FormData;
+/**
+ * D2 dispatch: FormData when a top-level File is present, the payload itself
+ * (JSON-serialized by the client) otherwise. Applies to create AND PATCH.
+ */
+export declare function encodeBody(values: Record<string, unknown>): Record<string, unknown> | FormData;
+/**
+ * Extracts the file-kind field names of `resource` from the cached parsed
+ * schema (`karniKeys.schema()`'s cache entry). Every access is guarded: an
+ * absent cache entry or an unexpected shape yields an empty set, never a
+ * throw.
+ */
+export declare function fileFieldNames(cachedSchema: unknown, resource: string): ReadonlySet<string>;
+/**
+ * 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

@@ -0,0 +1,25 @@
+import { ResourceItemParams, ResourceListParams } from './types';
+/** Canonical param value shape stored inside query keys (D4). */
+export type NormalizedParamValue = string | readonly string[] | NormalizedParams;
+export type NormalizedParams = {
+    readonly [key: string]: NormalizedParamValue;
+};
+/**
+ * Flattens ResourceListParams into the query record sent to the server.
+ * Explicit params win over a `filters` entry of the same name. Empty
+ * `search`/`ordering` strings and empty `expand` arrays are omitted (they
+ * describe "no constraint", and sending them would fragment the cache).
+ */
+export declare function buildListQuery(params?: ResourceListParams): Record<string, string | readonly string[]>;
+/** Detail requests only carry `expand` (api contract B9). */
+export declare function buildItemQuery(params?: ResourceItemParams): Record<string, string>;
+/**
+ * D4 normalization: drop undefined/null, sort keys recursively, stringify
+ * values as they hit the query string. The result is what `karniKeys` embeds
+ * in list keys.
+ */
+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. */
+export declare function detailPath(resource: string, id: string | number): string;

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

@@ -0,0 +1,41 @@
+import { QueryKey } from '@tanstack/react-query';
+/** DRF PageNumberPagination page shape returned by every list endpoint. */
+export interface Paginated<T> {
+    count: number;
+    next: string | null;
+    previous: string | null;
+    results: 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
+ * (they mean "no constraint", not "filter by null").
+ */
+export type FilterValue = string | number | boolean | ReadonlyArray<string | number | boolean> | null | undefined;
+/** Maps to page / page_size / ordering / search / expand + filter passthrough. */
+export interface ResourceListParams {
+    /** 1-based page number (`page`). */
+    page?: number;
+    /** Page size (`page_size`). */
+    pageSize?: number;
+    /** DRF ordering expression, e.g. `"-created_at"` (`ordering`). */
+    ordering?: string;
+    /** 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>;
+    /** Relation paths to expand, comma-joined into `expand` (api B9). */
+    expand?: readonly string[];
+}
+export interface ResourceItemParams {
+    /** Relation paths to expand, comma-joined into `expand` (api B9). */
+    expand?: readonly string[];
+}
+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
+     * also invalidate the cached schema document.
+     */
+    invalidateKeys?: readonly QueryKey[];
+}

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

@@ -0,0 +1,30 @@
+import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+/** `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;
+    actor: {
+        id: string | number;
+        email?: string;
+    } | null;
+    action: ChangeAction;
+    /** `{ field: [old, new] }`. A redacted field carries `"[redacted]"` on both sides. */
+    diff: Record<string, [unknown, unknown]>;
+    fields_changed: string[];
+}
+export interface ChangeHistoryPage {
+    count: number;
+    next: string | null;
+    previous: string | null;
+    results: ChangeLogEntry[];
+}
+export interface ChangeHistoryParams {
+    /** Entries per page (the backend caps it). Default: the API's page size. */
+    pageSize?: number;
+    page?: number;
+}
+/** The query key of one row's change history. */
+export declare function changeHistoryKey(resource: string, id: string | number, params?: ChangeHistoryParams): readonly unknown[];
+/** Fetches one row's field-level change history (`GET /<resource>/<id>/history/`) for models with `audit = True`. */
+export declare function useChangeHistory(resource: string, id: string | number, params?: ChangeHistoryParams, options?: Omit<UseQueryOptions<ChangeHistoryPage>, "queryKey" | "queryFn">): UseQueryResult<ChangeHistoryPage>;

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

@@ -0,0 +1,107 @@
+import { UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { KarniClient } from '../schema/client';
+import { ResourceListParams } from './types';
+export type ExportFormat = "csv" | "xlsx";
+export type ImportColumnKind = "text" | "integer" | "decimal" | "boolean" | "date" | "datetime" | "choice" | "relation" | "relations" | "json" | "file" | "other";
+export interface ImportColumn {
+    name: string;
+    label: string;
+    kind: ImportColumnKind;
+    required: boolean;
+    readable: boolean;
+    writable: boolean;
+    choices: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    /** `app_label.model` of a relation's target. */
+    target: string | null;
+    /** The target field a relation column carries (its natural key), else the id. */
+    lookup: string | null;
+    help: string;
+    /** The column an import matches existing rows on. */
+    key: boolean;
+}
+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. */
+    inline_rows: number;
+    max_rows: number;
+    key: string | null;
+}
+export type ImportStatus = "uploaded" | "previewing" | "previewed" | "committing" | "done" | "failed";
+export interface ImportResult {
+    rows_total: number;
+    created: number;
+    updated: number;
+    unchanged: number;
+    errors: number;
+    skipped: number;
+}
+export interface ImportProblem {
+    /** The line in the file (the header is line 1). */
+    row: number;
+    field: string;
+    message: string;
+}
+export interface ImportJob {
+    id: string;
+    model: string | null;
+    status: ImportStatus;
+    file_name: string;
+    format: string;
+    columns: string[];
+    mapping: Record<string, string>;
+    rows_total: number;
+    rows_done: number;
+    async: boolean;
+    result: ImportResult | null;
+    problems: ImportProblem[];
+    error: string | null;
+    batch: number | null;
+    created_at: string | null;
+    fields?: ImportColumn[];
+}
+/** The query key of a resource's import description. */
+export declare function importDescribeKey(resource: string): readonly unknown[];
+/** The query key of one import job. */
+export declare function importJobKey(resource: string, jobId: string): readonly unknown[];
+/** True while an import job is previewing or committing (the states worth polling). */
+export declare function isImportInFlight(job: ImportJob | undefined): boolean;
+/**
+ * Fetches `GET /<resource>/export/?format=…` with the list's query and saves
+ * it through a temporary object URL. Resolves with the file name. Throws the
+ * `KarniApiError` the backend answered (a 400 with code E803 when the export
+ * is larger than `KARNI_EXPORT_MAX_ROWS`).
+ */
+export declare function downloadResourceExport(client: KarniClient, resource: string, params: ResourceListParams | undefined, format?: ExportFormat): Promise<string>;
+/** Hands a blob to the browser as a download (a no-op outside a DOM, e.g. SSR). */
+export declare function saveBlob(blob: Blob, filename: string): void;
+/** Fetches `GET /<resource>/import/template/?format=…` and saves it (the headers, an example, allowed values). */
+export declare function downloadImportTemplate(client: KarniClient, resource: string, format?: ExportFormat): Promise<string>;
+/** Fetches what a resource's import accepts: its columns, required fields and allowed values. */
+export declare function useImportDescribe(resource: string, options?: Omit<UseQueryOptions<ImportDescription>, "queryKey" | "queryFn">): UseQueryResult<ImportDescription>;
+export interface UseImportJobOptions {
+    /** Polling interval while the job is previewing/committing. Default 1500 ms. */
+    pollMs?: number;
+}
+/** Fetches one import job and polls it while it runs. */
+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. */
+    mapping?: Record<string, string>;
+}
+export interface PreviewImportInput {
+    jobId: string;
+    mapping: Record<string, string>;
+}
+export interface ImportActions {
+    upload: UseMutationResult<ImportJob, unknown, UploadImportInput>;
+    preview: UseMutationResult<ImportJob, unknown, PreviewImportInput>;
+    commit: UseMutationResult<ImportJob, unknown, string>;
+}
+/** Upload, preview and commit mutations for a resource's import jobs. */
+export declare function useImportActions(resource: string): ImportActions;

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

@@ -0,0 +1,4 @@
+import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { ResourceItemParams } from './types';
+/** Fetches one row of a resource (`GET /<resource>/<id>/`), optionally expanded. */
+export declare function useResourceItem<T = Record<string, unknown>>(resource: string, id: string | number, params?: ResourceItemParams, options?: Omit<UseQueryOptions<T>, "queryKey" | "queryFn">): UseQueryResult<T>;

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

@@ -0,0 +1,4 @@
+import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { Paginated, ResourceListParams } from './types';
+/** Fetches one page of a resource's list (`GET /<resource>/`) with filters, search, ordering and `?expand=`. */
+export declare function useResourceList<T = Record<string, unknown>>(resource: string, params?: ResourceListParams, options?: Omit<UseQueryOptions<Paginated<T>>, "queryKey" | "queryFn">): UseQueryResult<Paginated<T>>;

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

@@ -0,0 +1,13 @@
+import { UseMutationResult } from '@tanstack/react-query';
+import { ResourceMutationsOptions } from './types';
+/** 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, {
+        id: string | number;
+        values: Record<string, unknown>;
+    }>;
+    remove: UseMutationResult<void, unknown, string | number>;
+}
+/** 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>;