@karni/ui 0.0.0-stage → 0.3.1

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 — strings (or arrays of strings) on file-kind
+ * fields are the backend's display URLs, not new uploads — from a PATCH
+ * payload (D2).
+ */
+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`); 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,29 @@
+import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+export type ChangeAction = "create" | "update" | "delete" | "restore";
+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; each success refreshes the resource's cached lists and items. */
+export declare function useResourceMutations<T = Record<string, unknown>>(resource: string, options?: ResourceMutationsOptions): ResourceMutations<T>;

package/dist/src/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @karni/ui public barrel.
+ *
+ * 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 { 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 { Button, buttonVariants } from './components/primitives/button';
+export type { ButtonProps, ButtonVariantProps } from './components/primitives/button';
+export { Input } from './components/primitives/input';
+export type { InputProps } from './components/primitives/input';
+export { Textarea } from './components/primitives/textarea';
+export type { TextareaProps } from './components/primitives/textarea';
+export { Select, SelectRoot, SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectLabel, SelectItem, SelectSeparator, KARNI_SELECT_EMPTY, } from './components/primitives/select';
+export type { SelectOption, SelectProps } from './components/primitives/select';
+export { Checkbox } from './components/primitives/checkbox';
+export type { CheckboxProps } from './components/primitives/checkbox';
+export { Switch } from './components/primitives/switch';
+export type { SwitchProps } from './components/primitives/switch';
+export { Label } from './components/primitives/label';
+export type { LabelProps } from './components/primitives/label';
+export { Tabs, TabsList, TabsTrigger, TabsContent } from './components/primitives/tabs';
+export { DropdownMenu, DropdownMenuTrigger, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuLabel, DropdownMenuSeparator, } from './components/primitives/dropdown-menu';
+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 { 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 { 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 { AUDIT_FIELDS } from './components/resource/audit-fields';
+export { karniKeys } from './hooks/keys';
+export { useResourceList } from './hooks/useResourceList';
+export { useResourceItem } from './hooks/useResourceItem';
+export { useResourceMutations } from './hooks/useResourceMutations';
+export type { ResourceMutations } from './hooks/useResourceMutations';
+export type { Paginated, FilterValue, ResourceListParams, ResourceItemParams, ResourceMutationsOptions, } from './hooks/types';
+export { createKarniClient, KarniApiError } from './schema/client';
+export type { KarniClient, KarniClientOptions, KarniQueryValue, KarniRequestOptions, } from './schema/client';
+export { KarniProvider, useKarniClient } from './schema/provider';
+export type { KarniProviderProps } from './schema/provider';
+export { useSchema } from './schema/useSchema';
+export type { UseSchemaResult } from './schema/useSchema';
+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 { 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 { 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 { 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';

package/dist/src/lib/cn.d.ts

@@ -0,0 +1,8 @@
+import { ClassValue } from 'clsx';
+/**
+ * Merges class names: clsx semantics for conditionals plus tailwind-merge
+ * conflict resolution, so consumer-supplied `className` always wins over a
+ * component's own Tailwind classes. Every @karni/ui component funnels its
+ * `className` prop through this.
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/src/lib/roles.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Component role registry (enforcement contract §4 + F11).
+ *
+ * Every top-level component claims a semantic role ("data-table",
+ * "resource-form", …) at module scope. Two components claiming the same role
+ * is a conflict: it throws at import time (so vitest and the dev server both
+ * surface it) and `scripts/generate-manifest.mjs` fails the build on the same
+ * duplicate via a static scan of these call sites.
+ *
+ * Conventions:
+ * - The `role` argument MUST be a string literal — the build-time scan rejects
+ *   any non-literal first argument.
+ * - Same role + same component name is idempotent (modules re-evaluate under
+ *   HMR and across test files).
+ * - Replacing on purpose is explicit and must carry a reason:
+ *   `{ replace: true, reason: "<why>" }` — an empty reason throws.
+ * - Under Vite HMR (`import.meta.hot`) an accidental conflict logs a
+ *   console.error and replaces instead of throwing, so a rename mid-edit does
+ *   not kill the dev server.
+ * - The registry reflects imported modules only (accepted v0.1 trade-off).
+ */
+export interface RegisterComponentRoleOptions {
+    /** Replace an existing registration on purpose. Requires `reason`. */
+    replace?: boolean;
+    /** Why the replacement is intentional — required with `replace: true`. */
+    reason?: string;
+}
+/**
+ * Test-only override for HMR detection; pass `null` to restore the default.
+ * Not exported from the package barrel.
+ * @internal
+ */
+export declare function __setHotDetectorForTests(detector: (() => boolean) | null): void;
+/**
+ * Test-only registry reset. Not exported from the package barrel.
+ * @internal
+ */
+export declare function __resetRoleRegistryForTests(): void;
+/**
+ * Claims a UI role (such as `data-table`) for a component, so a second component with the same role fails the build. The first argument must be a string literal
+ * (build-scan convention, F11).
+ */
+export declare function registerComponentRole(role: string, component: string, options?: RegisterComponentRoleOptions): void;
+/** Snapshot of the current registry ({ role: component }) for tooling. */
+export declare function getRoleRegistry(): Readonly<Record<string, string>>;

package/dist/src/lib/variants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hand-rolled cva-style variant utility (no extra dependency).
+ *
+ * Every class string appears whole in source (contract D7): a variant map
+ * value is a complete Tailwind class list, selected — never concatenated —
+ * at call time and merged through cn().
+ */
+/** A map of variant group name → allowed value → whole Tailwind class string. */
+export type VariantShape = Record<string, Record<string, string>>;
+/** The props accepted for a given variant shape (each group optional). */
+export type VariantSelection<V extends VariantShape> = {
+    [K in keyof V]?: Extract<keyof V[K], string> | null;
+};
+export interface VariantsConfig<V extends VariantShape> {
+    /** Classes always applied, before any variant classes. */
+    base?: string;
+    variants: V;
+    defaultVariants?: VariantSelection<V>;
+    /** Extra classes applied when every listed variant value is selected. */
+    compoundVariants?: ReadonlyArray<VariantSelection<V> & {
+        className: string;
+    }>;
+}
+export type VariantFn<V extends VariantShape> = (props?: VariantSelection<V> & {
+    className?: string;
+}) => string;
+/**
+ * Extracts the variant props of a variant function, for typing component
+ * props: `type ButtonVariantProps = VariantProps<typeof buttonVariants>`.
+ */
+export type VariantProps<F> = F extends VariantFn<infer V> ? VariantSelection<V> : never;
+/** Builds a typed class-name function from variant definitions, the way every themed component declares its looks. */
+export declare function variants<V extends VariantShape>(config: VariantsConfig<V>): VariantFn<V>;

package/dist/src/schema/client.d.ts

@@ -0,0 +1,90 @@
+/**
+ * createKarniClient — the typed fetch wrapper every @karni/ui layer sits on
+ * (contract "Schema client" + D6).
+ *
+ * Responsibilities:
+ * - URL joining + query-string serialization (arrays become repeated keys,
+ *   null/undefined are dropped),
+ * - JSON request/response handling; a FormData body is passed through
+ *   untouched with NO manual Content-Type (the D2 multipart rule),
+ * - DRF error passthrough: non-2xx responses throw KarniApiError carrying the
+ *   parsed body (field errors / detail / non_field_errors) verbatim,
+ * - auth hook points per D6's client-owns-tokens design: the auth layer (not
+ *   React) registers token injection, extra headers (session CSRF),
+ *   credentials mode and a 401 handler via `setAuthHooks`. The client calls
+ *   `onUnauthorized` at most ONCE per request and retries at most ONCE — a
+ *   request that 401s again after a successful refresh is surfaced, never
+ *   re-triggers refresh (the single-flight refresh promise itself lives in
+ *   the auth layer behind this hook).
+ */
+export interface KarniClientOptions {
+    /**
+     * Origin (plus optional path prefix) requests resolve against, e.g.
+     * "https://api.example.com" or "" for same-origin. Paths that already start
+     * with the prefix are not double-prefixed, so operation paths taken from
+     * the OpenAPI document ("/api/events/") work with any baseUrl.
+     */
+    baseUrl: string;
+    /** Path of the OpenAPI document. Default "/api/schema/". */
+    schemaUrl?: string;
+    /** Initial access-token getter; `setAuthHooks` can replace it later (D6). */
+    getAccessToken?: () => string | null;
+    /** Custom fetch implementation (tests, SSR). Resolved per request. */
+    fetch?: typeof globalThis.fetch;
+}
+export type KarniQueryValue = string | number | boolean | ReadonlyArray<string | number | boolean> | null | undefined;
+export interface KarniRequestOptions {
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    query?: Record<string, KarniQueryValue>;
+    /** JSON-serialized unless it is FormData (multipart rule D2). */
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /**
+     * Skip the 401 → onUnauthorized → retry cycle for this request. The auth
+     * layer sets it on its own login/refresh/logout calls so a failing refresh
+     * can never recurse into another refresh (D6).
+     */
+    skipAuthRefresh?: boolean;
+}
+/**
+ * Hook points the auth layer registers on the client (D6). Keys present in
+ * the object passed to `setAuthHooks` override the current value (an explicit
+ * `undefined` clears one); absent keys are kept.
+ */
+export interface KarniAuthHooks {
+    /** Called before every request; a non-null return is sent as Bearer. */
+    getAccessToken?: () => string | null;
+    /**
+     * Called once when a request gets a 401 (unless `skipAuthRefresh`). Return
+     * true to retry the request once with freshly-injected credentials, false
+     * to surface the error. Single-flight refresh lives behind this hook.
+     */
+    onUnauthorized?: (error: KarniApiError) => Promise<boolean>;
+    /** Extra headers merged into every request (session-mode X-CSRFToken). */
+    getHeaders?: () => Record<string, string>;
+    /** fetch credentials mode; session mode sets "include". */
+    credentials?: RequestCredentials;
+}
+/** Thrown for non-2xx responses; `data` carries the parsed DRF error body. */
+export declare class KarniApiError extends Error {
+    readonly status: number;
+    /** Parsed body when JSON (field errors, detail, non_field_errors), else text. */
+    readonly data: unknown;
+    constructor(status: number, data: unknown, message?: string);
+}
+export interface KarniClient {
+    readonly baseUrl: string;
+    readonly schemaUrl: string;
+    request<T>(path: string, options?: KarniRequestOptions): Promise<T>;
+    /**
+     * The same request (auth, query, 401 retry) returning the raw `Response`
+     * instead of a parsed body — for file downloads (`GET /<resource>/export/`).
+     * Non-2xx responses still throw `KarniApiError` with the parsed error body.
+     */
+    requestRaw(path: string, options?: KarniRequestOptions): Promise<Response>;
+    /** D6 hook point: the auth layer wires tokens/CSRF/401 handling here. */
+    setAuthHooks(hooks: KarniAuthHooks): void;
+}
+/** Creates the fetch client every hook in this package uses: base URL, JSON and multipart bodies, DRF errors as `KarniApiError`, and auth hooks. */
+export declare function createKarniClient(options: KarniClientOptions): KarniClient;

package/dist/src/schema/parse.d.ts

@@ -0,0 +1,101 @@
+import { ParsedSchema } from './types';
+export interface KarniRelationExtension {
+    resource?: string;
+    many?: boolean;
+}
+export interface SchemaObject {
+    default?: unknown;
+    $ref?: string;
+    type?: string | readonly string[];
+    format?: string;
+    title?: string;
+    description?: string;
+    enum?: ReadonlyArray<string | number | null>;
+    nullable?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    required?: readonly string[];
+    properties?: Record<string, SchemaObject>;
+    items?: SchemaObject;
+    allOf?: readonly SchemaObject[];
+    oneOf?: readonly SchemaObject[];
+    anyOf?: readonly SchemaObject[];
+    maxLength?: number;
+    minLength?: number;
+    minimum?: number;
+    maximum?: number;
+    "x-karni-relation"?: KarniRelationExtension;
+    [extension: string]: unknown;
+}
+export interface ParameterObject {
+    name?: string;
+    in?: string;
+    required?: boolean;
+    schema?: SchemaObject;
+    [extension: string]: unknown;
+}
+export interface MediaTypeObject {
+    schema?: SchemaObject;
+    [extension: string]: unknown;
+}
+export interface RequestBodyObject {
+    content?: Record<string, MediaTypeObject>;
+    required?: boolean;
+    [extension: string]: unknown;
+}
+export interface ResponseObject {
+    description?: string;
+    content?: Record<string, MediaTypeObject>;
+    [extension: string]: unknown;
+}
+export interface OperationObject {
+    operationId?: string;
+    parameters?: readonly ParameterObject[];
+    requestBody?: RequestBodyObject;
+    responses?: Record<string, ResponseObject>;
+    "x-karni-resource"?: string;
+    [extension: string]: unknown;
+}
+export interface PathItemObject {
+    get?: OperationObject;
+    post?: OperationObject;
+    put?: OperationObject;
+    patch?: OperationObject;
+    delete?: OperationObject;
+    [extension: string]: unknown;
+}
+export interface OpenApiDocument {
+    openapi?: string;
+    paths?: Record<string, PathItemObject>;
+    components?: {
+        schemas?: Record<string, SchemaObject>;
+        [extension: string]: unknown;
+    };
+    "x-karni-auth-mode"?: string;
+    [extension: string]: unknown;
+}
+/** "starts_at" → "Starts at"; "is_public" → "Is public". */
+export declare function humanize(name: string): string;
+/**
+ * Resolves $ref chains and unwraps single-member allOf, merging siblings over
+ * the resolved target (so `{allOf: [$ref StatusEnum], readOnly: true}` yields
+ * the enum schema plus readOnly). Cycle-guarded; a cycle resolves to {}.
+ */
+export declare function resolveSchema(doc: OpenApiDocument, schema: SchemaObject | undefined, seen?: readonly string[]): SchemaObject | undefined;
+/**
+ * Splits drf-spectacular's generated choice list ("* `draft` - Draft" per
+ * line, appended to a ChoiceField's description) into labels by value and
+ * the human help text that remains (undefined when nothing remains). The
+ * raw list is markdown a form would otherwise show verbatim as help text.
+ */
+export declare function choiceLabels(description: string | undefined): {
+    labels?: Record<string, string>;
+    rest?: string;
+};
+/**
+ * Parses an OpenAPI document (fetched from the backend's schemaUrl) into the
+ * normalized registry. Tolerates anything it does not understand: unknown
+ * constructs become kind "unknown" fields, paths without x-karni-resource are
+ * ignored, and a malformed document yields an empty registry.
+ */
+export declare function parseOpenApi(input: unknown): ParsedSchema;