@karni/ui 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,113 @@
+/**
+ * @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, 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';
+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 { 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, 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';
+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, 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, 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, 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, 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';

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/primitives/registry.d.ts

@@ -0,0 +1,81 @@
+import { ButtonProps } from '../components/primitives/button';
+import { CheckboxProps } from '../components/primitives/checkbox';
+import { InputProps } from '../components/primitives/input';
+import { LabelProps } from '../components/primitives/label';
+import { SkeletonProps } from '../components/primitives/skeleton';
+import { SwitchProps } from '../components/primitives/switch';
+import { TextareaProps } from '../components/primitives/textarea';
+/**
+ * The primitive registry: a project renders Karni's components with its own
+ * design system's primitives.
+ *
+ *   <KarniProvider client={client} primitives={{ button: Button, input: Input }}>
+ *
+ * Every Karni primitive (Button, Input, Select's parts, ...) looks itself up
+ * here before rendering, so ResourceTable, ResourceForm and the rest render
+ * the project's button and inputs while keeping their schema-driven
+ * behaviour. A role that is not registered renders Karni's own.
+ *
+ * Contracts: a registered component receives exactly the props Karni's
+ * primitive takes (ButtonProps, InputProps, ...) and the ref. shadcn/ui's
+ * components match them as they are. Any other design system registers a
+ * small adapter. `select` is a family: Radix parts share a context, so its
+ * parts are replaced together or not at all.
+ *
+ * A registered component may wrap Karni's own (`(props) => <Button
+ * className="..." {...props} />`): inside it, that role resolves to Karni's
+ * primitive again, so the wrapper does not call itself.
+ */
+import type * as SelectPrimitive from "@radix-ui/react-select";
+import * as React from "react";
+type WithRef<P, T> = React.ComponentType<P & React.RefAttributes<T>>;
+/** The parts of a Radix-compatible select (what shadcn/ui's select.tsx exports). */
+export interface KarniSelectParts {
+    Root: React.ComponentType<SelectPrimitive.SelectProps>;
+    Trigger: WithRef<SelectPrimitive.SelectTriggerProps, HTMLButtonElement>;
+    Value: WithRef<SelectPrimitive.SelectValueProps, HTMLSpanElement>;
+    Content: WithRef<SelectPrimitive.SelectContentProps, HTMLDivElement>;
+    Item: WithRef<SelectPrimitive.SelectItemProps, HTMLDivElement>;
+    Group: WithRef<SelectPrimitive.SelectGroupProps, HTMLDivElement>;
+    Label: WithRef<SelectPrimitive.SelectLabelProps, HTMLDivElement>;
+    Separator: WithRef<SelectPrimitive.SelectSeparatorProps, HTMLDivElement>;
+}
+/** Every role a project can fill with its own component. */
+export interface KarniPrimitives {
+    button: WithRef<ButtonProps, HTMLButtonElement>;
+    input: WithRef<InputProps, HTMLInputElement>;
+    textarea: WithRef<TextareaProps, HTMLTextAreaElement>;
+    checkbox: WithRef<CheckboxProps, HTMLButtonElement>;
+    switch: WithRef<SwitchProps, HTMLButtonElement>;
+    label: WithRef<LabelProps, HTMLLabelElement>;
+    skeleton: WithRef<SkeletonProps, HTMLDivElement>;
+    select: KarniSelectParts;
+}
+/** A role that is one component (not a family of parts). */
+export type KarniPrimitiveRole = Exclude<keyof KarniPrimitives, "select">;
+/** The project's replacements: any subset of the roles. */
+export type KarniPrimitiveOverrides = Partial<KarniPrimitives>;
+export interface KarniPrimitivesProviderProps {
+    /** Role -> the project's component. Merged over any registry above it. */
+    value: KarniPrimitiveOverrides;
+    children?: React.ReactNode;
+}
+/**
+ * Registers the project's primitives for everything inside it. KarniProvider
+ * renders one from its `primitives` prop, and you can nest another to change
+ * a subtree.
+ */
+export declare function KarniPrimitivesProvider({ value, children, }: KarniPrimitivesProviderProps): React.ReactElement;
+/** The registered primitives in scope (the roles the project replaced). */
+export declare function useKarniPrimitives(): KarniPrimitiveOverrides;
+/**
+ * Makes a Karni primitive defer to the registry.
+ * @internal
+ */
+export declare function overridable<P extends object, T>(role: KarniPrimitiveRole, Default: React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>>): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>>;
+/**
+ * Makes one part of Karni's select defer to a registered `select` family.
+ * @internal
+ */
+export declare function overridableSelectPart<K extends keyof KarniSelectParts, C extends KarniSelectParts[K]>(part: K, Default: C): C;
+export {};

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 and 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, with the parsed DRF error body in `data`. */
+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;

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

@@ -0,0 +1,20 @@
+import { QueryClient } from '@tanstack/react-query';
+import { ReactElement, ReactNode } from 'react';
+import { KarniPrimitiveOverrides } from '../primitives/registry';
+import { KarniClient } from './client';
+export interface KarniProviderProps {
+    client: KarniClient;
+    /** Bring your own QueryClient. One is created (once) when omitted. */
+    queryClient?: QueryClient;
+    /**
+     * The project's own primitives, by role: `{ button: Button, input: Input }`.
+     * Every Karni component then renders them in place of Karni's (see
+     * KarniPrimitivesProvider for the contract).
+     */
+    primitives?: KarniPrimitiveOverrides;
+    children?: ReactNode;
+}
+/** Rendered once at the app root, it provides the Karni client and a TanStack QueryClient to everything inside it. */
+export declare function KarniProvider(props: KarniProviderProps): ReactElement;
+/** Returns the Karni client from `KarniProvider` and throws a descriptive error outside one. */
+export declare function useKarniClient(): KarniClient;

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

@@ -0,0 +1,93 @@
+/**
+ * Normalized schema registry types (karni-ui-contract.md "Schema client" + D1).
+ *
+ * The OpenAPI document served by the karni backend (drf-spectacular, OAS 3.0.3,
+ * COMPONENT_SPLIT_REQUEST=True per api contract B14) is parsed ONCE into these
+ * shapes. Every generic component consumes FieldDef/ResourceSchema, never raw
+ * OpenAPI.
+ */
+export type FieldKind = "string" | "text" | "number" | "integer" | "boolean" | "date" | "datetime" | "enum" | "relation" | "file" | "json" | "array" | "unknown";
+/** Derived from the x-karni-relation vendor extension (api contract B13). */
+export interface RelationRef {
+    resource: string;
+    many: boolean;
+}
+export interface FieldDef {
+    name: string;
+    /** Humanized from the property name (or the schema `title` when present). */
+    label: string;
+    kind: FieldKind;
+    /** From the CREATE request body's required array only (D1). */
+    required: boolean;
+    /** Flagged readOnly OR present only in the response component (D1). */
+    readOnly: boolean;
+    /** Flagged writeOnly OR present only in the request component (D1). */
+    writeOnly: boolean;
+    nullable: boolean;
+    /** Enum members. BlankEnum's "" and NullEnum's null are never members (D1/D3). */
+    enumValues?: ReadonlyArray<string | number>;
+    /** Choice labels by value, from drf-spectacular's "* `value` - Label" description lines. */
+    enumLabels?: Readonly<Record<string, string>>;
+    /** The schema's `default` (a model default): forms start from it on create. */
+    default?: unknown;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    format?: string;
+    /** Schema `description`, surfaced as field help text. */
+    description?: string;
+    /** Present only when x-karni-relation was emitted (degrades gracefully). */
+    relation?: RelationRef;
+    /**
+     * Underlying pk value type of a relation field, derived from the property's
+     * own emitted type/format, never assumed (D3). Drives zodFor's relation
+     * value schema (uuid string vs integer).
+     */
+    relationValueType?: "uuid" | "integer" | "string";
+    /** Declaration order in the schema (response props first, request-only appended). */
+    order: number;
+}
+/**
+ * An operation's `x-karni-access` rule as the backend publishes it: the access
+ * predicate governing the operation, e.g. `{"role": ["staff"]}`,
+ * `{"owned": "organizer"}`, `{"any": [...]}`. A display hint only: the server
+ * enforces it.
+ */
+export type KarniAccessRule = Readonly<Record<string, unknown>>;
+export interface OperationDef {
+    path: string;
+    method: "get" | "post" | "put" | "patch" | "delete";
+    operationId?: string;
+    /** Declared query parameter names. The filter bar derives from these (D5). */
+    queryParams: readonly string[];
+    /** Allowed expand keys when the expand param declares an enum (D5). */
+    expandEnum?: readonly string[];
+    /** True when the operation declares a `search` query parameter (api B14). */
+    hasSearch?: boolean;
+    /** The operation's `x-karni-access` rule, when the backend published one. */
+    access?: KarniAccessRule;
+}
+export interface ResourceSchema {
+    /** Router prefix, e.g. "events" (from x-karni-resource). */
+    resource: string;
+    operations: {
+        list?: OperationDef;
+        detail?: OperationDef;
+        create?: OperationDef;
+        update?: OperationDef;
+        remove?: OperationDef;
+        /** `GET /<resource>/export/`: the list as a CSV/XLSX file (karni.transfer, P6). */
+        export?: OperationDef;
+        /** `POST /<resource>/import/`: the import flow (upload, preview, commit). */
+        import?: OperationDef;
+    };
+    /** Ordered by declaration. Unknown constructs land as kind "unknown". */
+    fields: readonly FieldDef[];
+}
+/** The whole parsed registry, produced once per schema fetch by parseOpenApi. */
+export interface ParsedSchema {
+    /** Keyed by router prefix (x-karni-resource). */
+    resources: Record<string, ResourceSchema>;
+    /** From the schema root's x-karni-auth-mode (api B14). Undefined when absent. */
+    authMode?: "jwt" | "session";
+}

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

@@ -0,0 +1,21 @@
+import { UseQueryResult } from '@tanstack/react-query';
+import { ParsedSchema, ResourceSchema } from './types';
+/** D4-pinned query key for the parsed schema document. */
+export declare const SCHEMA_QUERY_KEY: readonly ["karni", "$schema"];
+/**
+ * The whole parsed registry (resources + root x-karni-auth-mode). Internal to
+ * the package: the auth layer reads `data.authMode` from here. Apps use
+ * useSchema(resource).
+ */
+export declare function useParsedSchema(): UseQueryResult<ParsedSchema>;
+export interface UseSchemaResult {
+    data: ResourceSchema | undefined;
+    isLoading: boolean;
+    error: unknown;
+    /** Fetches the schema document again: what a "Try again" after a failed load calls. */
+    refetch?: () => void;
+    /** True while the schema document is being fetched (the first load or a retry). */
+    isFetching?: boolean;
+}
+/** Returns one resource's parsed schema (fields, types, relations, operations) from the backend's OpenAPI document, fetched once per app. */
+export declare function useSchema(resource: string): UseSchemaResult;