@karni/ui 0.0.0-stage → 0.3.1

package/dist/src/components/resource/form/ResourceForm.d.ts

@@ -0,0 +1,50 @@
+import { Control, FieldValues } from 'react-hook-form';
+import { FieldDef } from '../../../schema/types';
+import * as React from "react";
+/** Props passed to a custom field component (the `fields` escape hatch). */
+export interface KarniFieldProps {
+    field: FieldDef;
+    name: string;
+    label: string;
+    required: boolean;
+    control: Control<FieldValues>;
+    error?: string;
+    disabled?: boolean;
+    /** Pass-through from FieldOverride.props. */
+    props?: Record<string, unknown>;
+}
+export interface FieldOverride {
+    component?: React.ComponentType<KarniFieldProps>;
+    label?: string;
+    hidden?: boolean;
+    props?: Record<string, unknown>;
+}
+export interface ResourceFormProps {
+    resource: string;
+    /** Present → edit mode: loads the UNEXPANDED item, PATCHes dirty fields only (D10). */
+    id?: string | number;
+    defaultValues?: Record<string, unknown>;
+    onSuccess?: (result: Record<string, unknown>) => void;
+    onError?: (error: unknown) => void;
+    fields?: Record<string, FieldOverride>;
+    /** Custom RHF-registered nodes appended after the derived fields. */
+    extraFields?: React.ReactNode;
+    transformSubmit?: (values: Record<string, unknown>) => Record<string, unknown>;
+    /** Replaces the submit row. */
+    actions?: React.ReactNode;
+    className?: string;
+}
+/**
+ * Schema-driven create and edit form for one resource: inputs, validation and
+ * server errors derived from the OpenAPI schema.
+ *
+ * Contract "ResourceForm" + D2/D3/D10.
+ *
+ * Create mode POSTs every prepared value; edit mode loads the UNEXPANDED
+ * detail record and PATCHes only dirty fields at top-level granularity, with
+ * emptied nullable fields sent as null (D3). DRF 400 bodies map onto field
+ * errors via setError (non_field_errors → root). Escape hatches: per-field
+ * overrides (`fields`), `extraFields`, `transformSubmit` and the `actions`
+ * slot.
+ */
+export declare function ResourceForm(props: ResourceFormProps): React.ReactElement;

package/dist/src/components/resource/form/field-inputs.d.ts

@@ -0,0 +1,20 @@
+import { Control, FieldValues } from 'react-hook-form';
+import { FieldDef } from '../../../schema/types';
+/**
+ * Default per-kind inputs for <ResourceForm> (contract: string → Input,
+ * text → Textarea, number/integer → Input[type=number], boolean → Switch,
+ * date/datetime → native inputs, enum → Select, relation → ResourceSelect
+ * (multiple for many), file → FileUpload, json → Textarea with validation).
+ */
+import * as React from "react";
+export interface DefaultFieldControlProps {
+    field: FieldDef;
+    control: Control<FieldValues>;
+    inputId: string;
+    describedBy?: string;
+    invalid: boolean;
+    disabled?: boolean;
+    /** FieldOverride.props pass-through, spread onto the rendered input. */
+    inputProps?: Record<string, unknown>;
+}
+export declare function DefaultFieldControl({ field, control, inputId, describedBy, invalid, disabled, inputProps, }: DefaultFieldControlProps): React.ReactElement;

package/dist/src/components/resource/form/fixtures.d.ts

@@ -0,0 +1,24 @@
+import { FieldDef, ResourceSchema } from '../../../schema/types';
+export declare const eventFields: readonly FieldDef[];
+export declare const eventSchema: ResourceSchema;
+export declare const venueFields: readonly FieldDef[];
+export declare const venueSchema: ResourceSchema;
+export interface VenueRecord extends Record<string, unknown> {
+    id: number;
+    name: string;
+    city: string;
+}
+export declare const venues: readonly VenueRecord[];
+export declare const venueById: Readonly<Record<string, VenueRecord>>;
+export declare const tags: ReadonlyArray<Record<string, unknown>>;
+/** UNEXPANDED detail record, as edit mode receives it (D10). */
+export declare const eventRecord: Record<string, unknown>;
+/**
+ * Minimal drf-spectacular-shaped document (OAS 3.0.3,
+ * COMPONENT_SPLIT_REQUEST=True): split request/response components,
+ * x-karni-resource on list ops, x-karni-relation on pk fields and
+ * x-karni-auth-mode at the root (api contract B13/B14).
+ */
+export declare const demoOpenApiDocument: Record<string, unknown>;
+/** msw handlers for stories: schema document + events/venues/tags endpoints. */
+export declare const demoHandlers: import('msw').HttpHandler[];

package/dist/src/components/resource/form/prepare.d.ts

@@ -0,0 +1,54 @@
+import { FieldDef } from '../../../schema/types';
+export type FormValues = Record<string, unknown>;
+/** "published_on" / "draft-mode" → "Published on" / "Draft mode". */
+export declare function humanizeValue(value: string): string;
+/** ISO-8601 (any offset) → the local "YYYY-MM-DDTHH:mm" a datetime-local input needs. */
+export declare function toDatetimeLocal(value: string): string;
+/**
+ * datetime-local value ("YYYY-MM-DDTHH:mm[:ss]", implicitly local) →
+ * ISO-8601 with an explicit UTC offset, per the submit rule in the contract.
+ * Values that already carry a zone pass through untouched.
+ */
+export declare function toIsoWithOffset(value: string): string;
+/**
+ * D3 dirtiness at TOP-LEVEL field granularity: a react-hook-form dirtyFields
+ * entry counts as dirty when anything in its subtree is truthy, and the whole
+ * field value is then sent (DRF PATCH replaces whole field values).
+ */
+export declare function isDirtyEntry(entry: unknown): boolean;
+export interface BuildFormValuesInput {
+    fields: readonly FieldDef[];
+    /** Edit mode: the UNEXPANDED detail record (D10). Wins over defaultValues. */
+    item?: Record<string, unknown>;
+    defaultValues?: Record<string, unknown>;
+}
+/**
+ * Builds the react-hook-form value map: every form field gets a defined,
+ * controlled-input-safe initial value. Unmatched `defaultValues` keys are kept
+ * verbatim (they seed `extraFields`).
+ */
+export declare function buildFormValues({ fields, item, defaultValues }: BuildFormValuesInput): FormValues;
+export interface JsonFieldError {
+    name: string;
+    message: string;
+}
+export interface PrepareSubmitInput {
+    /** The writable schema fields rendered by the form. */
+    fields: readonly FieldDef[];
+    /** Resolver output from handleSubmit. */
+    raw: FormValues;
+    mode: "create" | "update";
+    /** react-hook-form dirtyFields; only consulted in "update" mode (D3). */
+    dirtyFields?: Record<string, unknown>;
+}
+export interface PreparedSubmit {
+    values: Record<string, unknown>;
+    /** Per-field validation failures (invalid JSON) that must block the submit. */
+    jsonErrors: JsonFieldError[];
+}
+/**
+ * The D3 submit pipeline. Create mode sends every defined value; update mode
+ * sends only fields whose dirtyFields subtree is truthy — always the WHOLE
+ * field value. Keys without a schema field (extraFields) pass through as-is.
+ */
+export declare function prepareSubmit({ fields, raw, mode, dirtyFields, }: PrepareSubmitInput): PreparedSubmit;

package/dist/src/components/resource/history/ChangeHistory.d.ts

@@ -0,0 +1,18 @@
+import * as React from "react";
+export interface ChangeHistoryProps {
+    resource: string;
+    id: string | number;
+    /** Entries to show (the backend paginates; default: the API's page size). */
+    pageSize?: number;
+    title?: React.ReactNode;
+    /** Shown when the row has no recorded changes. */
+    empty?: React.ReactNode;
+    className?: string;
+}
+/**
+ * The field-level change history of one row: when, by whom, what changed
+ * from what to what. Reads `GET /<resource>/<id>/history/` (models that opt
+ * in with `class Karni: audit = True`); fields the role may not see are
+ * already absent from each diff, redacted ones say so.
+ */
+export declare function ChangeHistory({ resource, id, pageSize, title, empty, className, }: ChangeHistoryProps): React.ReactElement;

package/dist/src/components/resource/import/ResourceImport.d.ts

@@ -0,0 +1,18 @@
+import { ImportJob } from '../../../hooks/useResourceImport';
+import * as React from "react";
+export interface ResourceImportProps {
+    resource: string;
+    title?: React.ReactNode;
+    /** Called when a commit finishes (the job is `done`). */
+    onDone?: (job: ImportJob) => void;
+    className?: string;
+}
+/**
+ * Import a CSV or XLSX file into a resource: upload, map columns to fields,
+ * preview (the mandatory dry run — N created / updated / skipped with every
+ * row's errors), then commit. Drives `/<resource>/import/…`; the backend
+ * validates every row through the same serializer the API uses, keeps rows
+ * inside the user's scope and refuses fields the role may not write. Large
+ * files run in the background with progress.
+ */
+export declare function ResourceImport({ resource, title, onDone, className, }: ResourceImportProps): React.ReactElement;

package/dist/src/components/resource/select/ResourceSelect.d.ts

@@ -0,0 +1,36 @@
+import * as React from "react";
+export interface ResourceSelectProps {
+    resource: string;
+    value: string | number | ReadonlyArray<string | number> | null;
+    onChange: (value: string | number | Array<string | number> | null) => void;
+    multiple?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    /** Defaults to displayLabel(). */
+    getOptionLabel?: (item: Record<string, unknown>) => React.ReactNode;
+    /** Extra filter params sent with the search request. */
+    filter?: Record<string, string | number | boolean>;
+    id?: string;
+    className?: string;
+    /** Page size for the option request (only the first page is fetched, D8). */
+    pageSize?: number;
+    /** Set false to hide the clear affordance (which emits null). Default true. */
+    clearable?: boolean;
+    /** Debounce for the ?search= request in ms. Default 300 (D8). */
+    searchDebounceMs?: number;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}
+/**
+ * Searchable picker for a related row, querying the related resource as you type.
+ *
+ * Contract D8.
+ *
+ * A text input drives a debounced `?search=` list request; options render in
+ * a NON-MODAL Radix Popover whose auto-focus is prevented so keyboard focus
+ * never leaves the input. The input implements the ARIA 1.2 combobox pattern
+ * (combobox → listbox with aria-activedescendant). Pre-selected ids that were
+ * never seen in a result page are resolved through detail fetches, and the
+ * clear affordance emits `null`.
+ */
+export declare function ResourceSelect(props: ResourceSelectProps): React.ReactElement;

package/dist/src/components/resource/select/use-debounced-value.d.ts

@@ -0,0 +1,2 @@
+/** Returns `value` after it has been stable for `delayMs` (D8: search debounce). */
+export declare function useDebouncedValue<T>(value: T, delayMs: number): T;

package/dist/src/components/resource/table/BulkActionsBar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Selected-count toolbar for ResourceTable's bulk select (D5): shows how many
+ * rows are selected (selection persists across pages), a clear affordance and
+ * one button per configured bulk action.
+ * Internal to @karni/ui — the public surface is ResourceTable's props.
+ */
+import * as React from "react";
+export interface BulkAction {
+    label: React.ReactNode;
+    onClick: (selectedIds: string[]) => void;
+    destructive?: boolean;
+}
+export interface BulkActionsBarProps {
+    /** Row ids (String(row.id), D5) currently selected, across all pages. */
+    selectedIds: readonly string[];
+    bulkActions: ReadonlyArray<BulkAction>;
+    onClear: () => void;
+    className?: string;
+}
+export declare function BulkActionsBar(props: BulkActionsBarProps): React.ReactElement;

package/dist/src/components/resource/table/ExportButtons.d.ts

@@ -0,0 +1,17 @@
+import { ResourceListParams } from '../../../hooks/types';
+import { ExportFormat } from '../../../hooks/useResourceImport';
+/**
+ * ResourceTable's export buttons (karni.transfer, ADR 0002 P6): one per
+ * format, each downloading `GET /<resource>/export/` with the table's current
+ * filters, search and ordering — the backend applies the row scope and the
+ * role's field visibility, so the file is exactly what the table may show.
+ *
+ * Internal to @karni/ui — the public surface is ResourceTable's `exportFormats`.
+ */
+import * as React from "react";
+export interface ExportButtonsProps {
+    resource: string;
+    params: ResourceListParams;
+    formats: readonly ExportFormat[];
+}
+export declare function ExportButtons({ resource, params, formats, }: ExportButtonsProps): React.ReactElement;

package/dist/src/components/resource/table/FilterBar.d.ts

@@ -0,0 +1,29 @@
+import { FilterValue } from '../../../hooks/types';
+import { FieldDef } from '../../../schema/types';
+/**
+ * ResourceTable's search box + declared-params-derived filter bar (D5).
+ *
+ * The parent decides WHICH fields filter (enum/boolean/relation fields ∩ the
+ * list operation's declared query params, cap 4, `filters` prop overrides);
+ * this component only renders the controls:
+ * - enum   → clearable <Select> ("All" clears),
+ * - boolean → clearable Yes/No <Select>,
+ * - relation → <ResourceSelect> (multiple for many-relations).
+ *
+ * Internal to @karni/ui — the public surface is ResourceTable's props.
+ */
+import * as React from "react";
+export interface FilterBarProps {
+    /** Whether the list operation declares a `search` query param. */
+    searchEnabled: boolean;
+    searchValue: string;
+    onSearchChange: (value: string) => void;
+    searchPlaceholder?: string;
+    /** Already-derived filter fields, in render order. */
+    filterFields: readonly FieldDef[];
+    values: Readonly<Record<string, FilterValue>>;
+    onFilterChange: (field: FieldDef, value: FilterValue) => void;
+    className?: string;
+}
+/** Search box + up to four filter controls in one wrapping row. */
+export declare function FilterBar(props: FilterBarProps): React.ReactElement;

package/dist/src/components/resource/table/PaginationControls.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ResourceTable's server-mode pagination row (DRF PageNumberPagination:
+ * `{count, next, previous, results}` with `page` / `page_size` params).
+ * Internal to @karni/ui — the public surface is ResourceTable's props.
+ */
+import * as React from "react";
+export interface PaginationControlsProps {
+    /** 1-based current page. */
+    page: number;
+    pageCount: number;
+    /** Total item count across all pages (DRF `count`). */
+    totalCount: number;
+    /** From DRF `previous` / `next` — the server is the authority. */
+    hasPrevious: boolean;
+    hasNext: boolean;
+    onPageChange: (page: number) => void;
+    className?: string;
+}
+export declare function PaginationControls(props: PaginationControlsProps): React.ReactElement;

package/dist/src/components/resource/table/ResourceTable.d.ts

@@ -0,0 +1,72 @@
+import { ColumnDef, SortingState } from '@tanstack/react-table';
+import { KarniQueryValue } from '../../../schema/client';
+import { ExportFormat } from '../../../hooks/useResourceImport';
+import { BulkAction } from './BulkActionsBar';
+import { ResourceColumn } from './derive-columns';
+import * as React from "react";
+export type { BulkAction, ResourceColumn };
+export declare const DEFAULT_PAGE_SIZE = 25;
+export interface ResourceTableProps<T = Record<string, unknown>> {
+    resource: string;
+    /**
+     * Per-field overrides. Naming a default-hidden field (an audit field such
+     * as `created_at`, or a json/file field) shows it; `hidden: true` hides one.
+     */
+    columns?: ReadonlyArray<ResourceColumn<T>>;
+    /**
+     * Show the audit columns (AUDIT_FIELDS: id, created_at, updated_at,
+     * created_by, updated_by) after the domain columns, and let audit fields
+     * into the derived filter bar. Default false: they are hidden.
+     */
+    showAuditFields?: boolean;
+    /** TanStack ColumnDef pass-through, appended after derived columns. */
+    extraColumns?: ReadonlyArray<ColumnDef<T>>;
+    /** Full escape hatch, applied last over the derived + merged columns. */
+    columnsOverride?: (derived: Array<ColumnDef<T>>) => Array<ColumnDef<T>>;
+    rowActions?: (row: T) => React.ReactNode;
+    /** Passing this enables the default edit row action. */
+    onEdit?: (row: T) => void;
+    /** Enables the default delete row action (uses useResourceMutations). */
+    enableDelete?: boolean;
+    bulkActions?: ReadonlyArray<BulkAction>;
+    onRowClick?: (row: T) => void;
+    /**
+     * `expand` query values. Default: single-relation field names ∩ the list
+     * operation's expand enum — never guessed beyond the schema (D5).
+     */
+    expand?: readonly string[];
+    initialSorting?: SortingState;
+    /** Sent as `page_size`. Default 25. */
+    pageSize?: number;
+    /**
+     * Field names to build the filter bar from; `false` disables it. Default:
+     * (enum/boolean/relation fields) ∩ declared list query params, domain
+     * fields first, audit fields only with `showAuditFields`, cap 4 (D5).
+     * Only enum, boolean and relation fields get controls.
+     */
+    filters?: readonly string[] | false;
+    /**
+     * Fixed filters sent with every request and hidden from the filter bar —
+     * e.g. `{ event: eventId }` for "the bookings of this event". A user filter
+     * on the same field never overrides them.
+     */
+    params?: Readonly<Record<string, KarniQueryValue>>;
+    /**
+     * Export buttons (one per format) when the resource serves
+     * `GET /<resource>/export/` — every Karni BaseViewSet does. The file carries
+     * the table's current filters, search and ordering; the backend applies the
+     * row scope and field visibility. Default `["csv", "xlsx"]`; `false` hides them.
+     */
+    exportFormats?: readonly ExportFormat[] | false;
+    /** Extra toolbar content, rendered to the right of the search/filter row. */
+    toolbar?: React.ReactNode;
+    /** Replaces the default EmptyState when the list has no results. */
+    empty?: React.ReactNode;
+    /** Rendered under the pagination row. */
+    footer?: React.ReactNode;
+    /** Overrides displayLabel() for relation cells (and the delete confirm). */
+    getRowLabel?: (row: Record<string, unknown>) => string;
+    className?: string;
+}
+/** Schema-driven data table for one resource: columns, sorting, filters, search, pagination, row actions and bulk select, all derived from the OpenAPI schema. */
+export declare function ResourceTable<T = Record<string, unknown>>(props: ResourceTableProps<T>): React.ReactElement;

package/dist/src/components/resource/table/demo-fixtures.d.ts

@@ -0,0 +1,25 @@
+import { RequestHandler } from 'msw';
+export interface DemoEvent {
+    id: number;
+    created_at: string;
+    updated_at: string;
+    created_by: number | null;
+    updated_by: number | null;
+    title: string;
+    starts_at: string;
+    capacity: number | null;
+    status: "DRAFT" | "PUBLISHED";
+    is_public: boolean;
+    organizer: number | null;
+    venue: number | null;
+    tags: number[];
+}
+export declare const DEMO_EVENT_COUNT = 57;
+/** Titles run opposite to ids so title-ascending differs from the default order. */
+export declare function makeDemoEvents(count?: number): DemoEvent[];
+export declare const eventsOpenApi: Record<string, unknown>;
+/**
+ * msw handlers for the demo backend. Register per test with
+ * `server.use(...demoHandlers())` or per story via `parameters.msw.handlers`.
+ */
+export declare function demoHandlers(events?: DemoEvent[]): RequestHandler[];

package/dist/src/components/resource/table/derive-columns.d.ts

@@ -0,0 +1,33 @@
+import { ColumnDef } from '@tanstack/react-table';
+import { FieldDef } from '../../../schema/types';
+import * as React from "react";
+/** Per-field override merged over the schema-derived column. */
+export interface ResourceColumn<T = Record<string, unknown>> {
+    field: string;
+    header?: React.ReactNode;
+    cell?: (row: T) => React.ReactNode;
+    hidden?: boolean;
+    sortable?: boolean;
+}
+type RowLabeler = (row: Record<string, unknown>) => string;
+/**
+ * Default cell renderer for a schema field's value. Exported for reuse by
+ * custom cells that want the stock formatting for other fields.
+ */
+export declare function renderFieldCell(field: FieldDef, value: unknown, getRowLabel?: RowLabeler): React.ReactNode;
+export interface DeriveColumnsArgs<T> {
+    fields: readonly FieldDef[];
+    columns?: ReadonlyArray<ResourceColumn<T>>;
+    getRowLabel?: RowLabeler;
+    /** Show every audit field (AUDIT_FIELDS) without naming each in `columns`. */
+    showAuditFields?: boolean;
+}
+/**
+ * Builds the derived column set: domain columns (schema order), then any
+ * shown audit columns (AUDIT_FIELDS order), then `columns` entries naming
+ * fields the schema does not declare — plain accessor columns (escape hatch
+ * for computed or server-extra keys). `columns` overrides merge onto their
+ * fields; naming a default-skipped field (json, audit, ...) shows it.
+ */
+export declare function deriveColumns<T>(args: DeriveColumnsArgs<T>): Array<ColumnDef<T>>;
+export {};

package/dist/src/components/resource/table/table-utils.d.ts

@@ -0,0 +1,24 @@
+import { SortingState } from '@tanstack/react-table';
+/**
+ * Maps TanStack sorting state to the DRF `ordering` query parameter.
+ * Column ids equal schema field names verbatim — that IS the ordering
+ * contract (D5) — so `[{id: "title", desc: true}]` becomes `-title`.
+ */
+export declare function sortingToOrdering(sorting: SortingState): string | undefined;
+/**
+ * Duck-typed 404 check (works with KarniApiError or any error exposing a
+ * numeric `status`), used for the D5 page-clamp: a list 404 with page > 1
+ * decrements the page and refetches as loading, never as an error.
+ */
+export declare function isNotFoundError(error: unknown): boolean;
+export declare function pageCountFor(count: number | undefined, pageSize: number): number;
+/** Safe record view of an unknown row (rows are plain JSON objects). */
+export declare function asRecord(value: unknown): Record<string, unknown>;
+/** Best-effort human message from a KarniApiError-shaped or plain Error. */
+export declare function errorMessage(error: unknown): string;
+/**
+ * Display label for an enum member: ALL_CAPS and lower_snake constants are
+ * prettified ("DRAFT" → "Draft", "in_progress" → "In progress"); mixed-case
+ * values ("iOS") pass through untouched.
+ */
+export declare function enumLabel(value: string | number, labels?: Readonly<Record<string, string>>): string;

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

@@ -0,0 +1,24 @@
+import * as React from "react";
+export interface StatProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** What the number measures ("Active users"). */
+    label: React.ReactNode;
+    /** The headline value — preformatted string or any node. */
+    value: React.ReactNode;
+    /**
+     * Change indicator. A number renders a signed figure with an up/down arrow
+     * (negative numbers use the destructive token) plus screen-reader context;
+     * any other node renders verbatim in the delta slot.
+     */
+    delta?: number | React.ReactNode;
+    /** Formats a numeric `delta` (default: signed, locale formatted). */
+    formatDelta?: (delta: number) => string;
+    /** Optional icon slot, top-right. */
+    icon?: React.ReactNode;
+}
+/**
+ * KPI tile: label, value, optional delta and icon.
+ *
+ * Escape hatches: `value`/`delta`/`icon` accept arbitrary nodes,
+ * `formatDelta` overrides numeric formatting, `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,33 @@
+import { VariantProps } from '../../lib/variants';
+import * as React from "react";
+/**
+ * Per-variant toast styling — colors resolve through --karni-* tokens only
+ * (success leans on primary, error on destructive, info on muted).
+ */
+export declare const toastVariants: import('../..').VariantFn<{
+    variant: {
+        default: string;
+        success: string;
+        error: string;
+        info: string;
+    };
+}>;
+export type ToastVariantProps = VariantProps<typeof toastVariants>;
+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 (position/stacking escape hatch). */
+    viewportClassName?: string;
+    /** Extra classes for every toast root. */
+    toastClassName?: string;
+}
+/**
+ * Renders the toasts pushed through useToast(). Mount exactly one near the
+ * app root. Position defaults to the bottom-right corner; override with
+ * `viewportClassName` (it merges via cn(), so e.g. "top-0 bottom-auto" wins).
+ */
+export declare function Toaster({ duration, swipeDirection, label, viewportClassName, toastClassName, }: 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 — `{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[];
+};