@karni/ui 0.3.1 → 0.4.0

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

@@ -1,7 +1,8 @@
 /**
  * Barrel-facing path for <ResourceForm>. The implementation lives in
- * ./form/ (resource form builder); every contract-pinned export name is
+ * ./form/ (resource form builder). Every contract-pinned export name is
  * re-exported here so src/index.ts keeps resolving this module.
  */
-export { ResourceForm } from './form/ResourceForm';
-export type { ResourceFormProps, FieldOverride, KarniFieldProps } from './form/ResourceForm';
+export { ResourceForm, defaultResourceFormSlots } from './form/ResourceForm';
+export type { ResourceFormProps, ResourceFormSlots, FieldOverride, KarniFieldProps, } from './form/ResourceForm';
+export type { ResourceFormErrorSummaryProps, ResourceFormFieldError, ResourceFormForbiddenProps, ResourceFormLoadingProps, ResourceFormSubmitErrorProps, } from './form/form-states';

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

@@ -1,7 +1,9 @@
 /**
  * Barrel-facing path for <ResourceSelect>. The implementation lives in
- * ./select/ (resource form builder); every contract-pinned export name is
+ * ./select/ (resource form builder). Every contract-pinned export name is
  * re-exported here so src/index.ts keeps resolving this module.
  */
 export { ResourceSelect } from './select/ResourceSelect';
 export type { ResourceSelectProps } from './select/ResourceSelect';
+export { defaultResourceSelectSlots } from './select/select-states';
+export type { ResourceSelectChipProps, ResourceSelectEmptyProps, ResourceSelectLoadingProps, ResourceSelectOptionProps, ResourceSelectSlots, } from './select/select-states';

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

@@ -2,10 +2,16 @@
  * Public entry for ResourceTable (owner: resource table builder).
  *
  * The implementation lives in ./table/ (ResourceTable + filter bar +
- * pagination controls + bulk select, contract "ResourceTable" + D5); this
+ * pagination controls + bulk select, contract "ResourceTable" + D5). This
  * module keeps the barrel's import path and exported names stable.
  */
 export { ResourceTable } from './table/ResourceTable';
-export type { ResourceTableProps } from './table/ResourceTable';
+export type { BulkResult, ResourceTableDensity, ResourceTableKeyboardNavigation, ResourceTableProps, } from './table/ResourceTable';
 export type { ResourceColumn } from './table/derive-columns';
-export type { BulkAction } from './table/BulkActionsBar';
+export type { BulkAction, BulkActionReturn, BulkOutcome } from './table/BulkActionsBar';
+export { defaultResourceTableSlots } from './table/slots';
+export type { ResourceTableBulkActionsProps, ResourceTableForbiddenProps, ResourceTableLoadingProps, ResourceTableNoRecordsProps, ResourceTableNoResultsProps, ResourceTableOfflineProps, ResourceTablePaginationProps, ResourceTableRowCardProps, ResourceTableSlots, } from './table/slots';
+export type { ResourceTableActiveFilter } from './table/states';
+export type { ResourceTableCardField } from './table/RowCard';
+export { createHistoryStateStore } from './table/url-state';
+export type { ResourceTableStateStore } from './table/url-state';

package/dist/src/components/resource/audit-fields.d.ts

@@ -3,7 +3,7 @@ import { FieldDef } from '../../schema/types';
 export declare const AUDIT_FIELDS: readonly string[];
 /**
  * True for a schema field that is one of AUDIT_FIELDS. The backend always
- * emits these readOnly; a writable field that merely shares a name (a natural
+ * emits these readOnly. A writable field that merely shares a name (a natural
  * `id` key, say) is domain data and is never treated as audit.
  */
 export declare function isAuditField(field: Pick<FieldDef, "name" | "readOnly">): boolean;

package/dist/src/components/resource/detail/ResourceDetail.d.ts

@@ -1,30 +1,128 @@
+import { FieldDef } from '../../../schema/types';
+import { ErrorSlotProps } from '../../../states/ErrorState';
 import * as React from "react";
+type Item = Record<string, unknown>;
 export interface ResourceDetailFieldOverride {
     label?: string;
     hidden?: boolean;
     render?: (value: unknown, item: Record<string, unknown>) => React.ReactNode;
 }
+/** What the `Loading` slot receives. */
+export interface ResourceDetailLoadingProps {
+    /** The domain fields the record will show, in order. Undefined while the schema loads. */
+    fields: readonly FieldDef[] | undefined;
+    /** The audit fields of the "Record" group. Undefined while the schema loads. */
+    auditFields: readonly FieldDef[] | undefined;
+    /** True once loading has taken longer than SLOW_AFTER_MS (500ms): show the placeholder now. */
+    slow: boolean;
+}
+/** What the `Error` slot receives: ErrorSlotProps plus the `back` prop. */
+export interface ResourceDetailErrorProps extends ErrorSlotProps {
+    /** The way out of the screen (the `back` prop). */
+    back?: React.ReactNode;
+}
+/** What the `NotFound` slot receives (the backend answered 404). */
+export interface ResourceDetailNotFoundProps {
+    error: unknown;
+    /** The resource in words, singular: "event". */
+    resourceLabel: string;
+    back?: React.ReactNode;
+}
+/** What the `Deleted` slot receives, after a delete from this view succeeded. */
+export interface ResourceDetailDeletedProps {
+    item: Item;
+    resourceLabel: string;
+    back?: React.ReactNode;
+}
+/** What the `EmptyValue` slot receives: a visible field with no value. */
+export interface ResourceDetailEmptyValueProps {
+    field: FieldDef;
+}
+/** What the `DeleteDialog` slot receives: the confirmation before a delete. */
+export interface ResourceDetailDeleteDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    item: Item;
+    /** displayLabel(item): "Launch party". */
+    itemLabel: string;
+    resourceLabel: string;
+    onConfirm: () => void;
+    /** True while the delete request runs. */
+    pending: boolean;
+    /** The failed attempt's error (null before an attempt and while one runs). */
+    error: unknown;
+}
+/**
+ * The replaceable parts of ResourceDetail. Pass any subset as `slots`.
+ * `defaultResourceDetailSlots` holds Karni's own, to wrap them.
+ */
+export interface ResourceDetailSlots {
+    /** The field placeholders while the record loads (the header is ResourceDetail's own). */
+    Loading: React.ComponentType<ResourceDetailLoadingProps>;
+    /** Any failure but a 404: offline, server error, 403, ... */
+    Error: React.ComponentType<ResourceDetailErrorProps>;
+    /** The backend answered 404: the record does not exist or is outside the user's scope. */
+    NotFound: React.ComponentType<ResourceDetailNotFoundProps>;
+    /** A visible field whose value is empty. */
+    EmptyValue: React.ComponentType<ResourceDetailEmptyValueProps>;
+    /** The delete confirmation. */
+    DeleteDialog: React.ComponentType<ResourceDetailDeleteDialogProps>;
+    /** Shown in place of the record once it is deleted from this view. */
+    Deleted: React.ComponentType<ResourceDetailDeletedProps>;
+}
 export interface ResourceDetailProps {
     resource: string;
     id: string | number;
     fields?: Record<string, ResourceDetailFieldOverride>;
-    /** Appended below the field list (e.g. a child <ResourceTable>). */
+    /** Appended below the field list (e.g. a child <ResourceTable>), even while the record loads. */
     sections?: ReadonlyArray<React.ReactNode>;
     expand?: readonly string[];
-    title?: React.ReactNode;
-    actions?: React.ReactNode;
+    /** The heading. A function receives the loaded record. A placeholder stands in until then. */
+    title?: React.ReactNode | ((item: Item) => React.ReactNode);
+    /** Shown in the header next to Edit and Delete. A function receives the loaded record. */
+    actions?: React.ReactNode | ((item: Item) => React.ReactNode);
+    /** The resource in words, singular, for messages ("Couldn't find this event"). Default: from `resource`. */
+    resourceLabel?: string;
+    /** A way back (a link or button to the list), shown when the record is missing, fails or is deleted. */
+    back?: React.ReactNode;
+    /** Shows an Edit button that calls this with the record. */
+    onEdit?: (item: Item) => void;
+    /** Whether the user may edit this record (the role, the record's state). Default true. */
+    canEdit?: boolean | ((item: Item) => boolean);
+    /** Shows a Delete button, which asks for confirmation first. */
+    enableDelete?: boolean;
+    /** Whether the user may delete this record. Default true. */
+    canDelete?: boolean | ((item: Item) => boolean);
+    /** Called after a confirmed delete succeeded (navigate away from here). */
+    onDeleted?: (item: Item) => void;
+    /** Replace parts of the view: Loading, Error, NotFound, EmptyValue, DeleteDialog, Deleted. */
+    slots?: Partial<ResourceDetailSlots>;
     className?: string;
 }
+/** Karni's own slots, exported so a project can wrap one instead of rewriting it. */
+export declare const defaultResourceDetailSlots: ResourceDetailSlots;
 /**
  * Schema-driven read view of one row: every readable field, labelled and formatted.
  *
- * Contract "ResourceDetail": a definition list of
- * every non-writeOnly field — domain fields first (schema order), then the
- * audit fields (AUDIT_FIELDS: id, created_at, updated_at, created_by,
- * updated_by) in a visually muted "Record" group. Relations render through
- * displayLabel when the object is expanded (the field is in `expand`), else
- * as the raw id in <code>. Escape hatches: per-field `fields` overrides
- * (label/hidden/render — audit fields included), appended `sections`, and the
- * title/actions header slots.
+ * Contract "ResourceDetail": a definition list of every non-writeOnly field
+ * the payload carries, with domain fields first (schema order), then the audit
+ * fields (AUDIT_FIELDS: id, created_at, updated_at, created_by, updated_by)
+ * in a visually muted "Record" group. A field the role may not read
+ * (`Karni.field_roles`) is absent from the per-role schema and the payload,
+ * so it has no row at all. A visible field with no value shows EmptyValue
+ * (a dash, read as "empty"). Relations render through displayLabel when the
+ * object is expanded (the field is in `expand`), else as the raw id in <code>.
+ *
+ * States: a placeholder in the record's own layout while it loads (drawn
+ * after 500ms, the header in place from the start). A 404 shows "Couldn't
+ * find this <resource>", and Karni also answers 404 for a record outside the
+ * user's scope. Everything else shows describeError's words, with "Try again"
+ * when it can help (it refetches the schema too when that failed). Offline
+ * says so and reloads when the connection returns.
+ *
+ * Escape hatches: per-field `fields` overrides (label/hidden/render, audit
+ * fields included), appended `sections`, the title/actions header, the
+ * `canEdit`/`canDelete` predicates, and `slots` for every state.
  */
 export declare function ResourceDetail(props: ResourceDetailProps): React.ReactElement;
+export {};

package/dist/src/components/resource/empty-value.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+/** What a screen reader says for a field that has no value. */
+export declare const EMPTY_VALUE_LABEL = "empty";
+export interface EmptyValueProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Read by screen readers in place of the dash. Default "empty". */
+    label?: string;
+}
+/**
+ * A field that has no value (null, "", an empty list), the same in every
+ * Karni component: ResourceTable's cells, ResourceDetail's rows and
+ * ChangeHistory's before/after values. Sighted users see a muted en dash,
+ * and screen readers hear "empty" instead of "dash" or nothing.
+ *
+ * A field the role may not read is never rendered as empty: it has no row
+ * or cell at all, so an empty value never hints that a hidden one exists.
+ */
+export declare const EmptyValue: React.ForwardRefExoticComponent<EmptyValueProps & React.RefAttributes<HTMLSpanElement>>;

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

@@ -1,5 +1,8 @@
-import { Control, FieldValues } from 'react-hook-form';
+import { Control, FieldValues, Mode } from 'react-hook-form';
 import { FieldDef } from '../../../schema/types';
+import { ErrorSlotProps } from '../../../states/ErrorState';
+import { ResourceLabel } from '../resource-names';
+import { ResourceFormErrorSummaryProps, ResourceFormForbiddenProps, ResourceFormLoadingProps, ResourceFormSubmitErrorProps } from './form-states';
 import * as React from "react";
 /** Props passed to a custom field component (the `fields` escape hatch). */
 export interface KarniFieldProps {
@@ -19,12 +22,31 @@ export interface FieldOverride {
     hidden?: boolean;
     props?: Record<string, unknown>;
 }
+/**
+ * The replaceable parts of ResourceForm (`slots`). Each default is in
+ * `defaultResourceFormSlots`.
+ */
+export interface ResourceFormSlots {
+    /** While the schema or the edited row loads. */
+    Loading: React.ComponentType<ResourceFormLoadingProps>;
+    /** A failed load of the schema or the row, with retry when it can help. */
+    Error: React.ComponentType<ErrorSlotProps>;
+    /** A 403 while loading the row: the role cannot edit it. */
+    Forbidden: React.ComponentType<ResourceFormForbiddenProps>;
+    /** After a failed submit with more than one problem: every one, each field focusable. */
+    ErrorSummary: React.ComponentType<ResourceFormErrorSummaryProps>;
+    /** A submit that failed for a reason other than the values (offline, 403, 409, 5xx). */
+    SubmitError: React.ComponentType<ResourceFormSubmitErrorProps>;
+}
+/** ResourceForm's own slot components, for wrapping rather than rewriting. */
+export declare const defaultResourceFormSlots: ResourceFormSlots;
 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;
+    /** Called with every failed submit's error (the form shows it as well). */
     onError?: (error: unknown) => void;
     fields?: Record<string, FieldOverride>;
     /** Custom RHF-registered nodes appended after the derived fields. */
@@ -32,7 +54,41 @@ export interface ResourceFormProps {
     transformSubmit?: (values: Record<string, unknown>) => Record<string, unknown>;
     /** Replaces the submit row. */
     actions?: React.ReactNode;
+    /** The submit button's text. Default "Create" or "Save changes". */
+    submitLabel?: React.ReactNode;
     className?: string;
+    /** Replaces parts of the form: loading, load error, permission, error summary, submit error. */
+    slots?: Partial<ResourceFormSlots>;
+    /**
+     * When a field first validates (react-hook-form's `mode`). Default "onBlur":
+     * a field is checked when the user leaves it, never on every keystroke.
+     */
+    validationMode?: Mode;
+    /**
+     * When a field validates again after a submit (react-hook-form's
+     * `reValidateMode`). Default "onBlur". Independently of both, a field that
+     * shows an error re-validates on every change, so the error clears as soon
+     * as the value is fixed.
+     */
+    reValidateMode?: Exclude<Mode, "onTouched" | "all">;
+    /** Focus the first field when the form appears. Default: true to create, false to edit. */
+    autoFocus?: boolean;
+    /**
+     * Warn before the page unloads with unsaved changes (`beforeunload`).
+     * Default true. Pass false to opt out. In-app navigation: see `onDirtyChange`.
+     */
+    guardUnsavedChanges?: boolean;
+    /**
+     * Called when the form gains or loses unsaved changes, and with false just
+     * before `onSuccess`. Feed it to `useUnsavedChangesGuard().setDirty` and
+     * the router's blocker to stop in-app navigation away from a dirty form.
+     */
+    onDirtyChange?: (dirty: boolean) => void;
+    /**
+     * How the resource is named in messages. The default is derived from
+     * `resource` ("events" → "event").
+     */
+    resourceLabel?: ResourceLabel;
 }
 /**
  * Schema-driven create and edit form for one resource: inputs, validation and
@@ -40,11 +96,14 @@ export interface ResourceFormProps {
  *
  * Contract "ResourceForm" + D2/D3/D10.
  *
- * Create mode POSTs every prepared value; edit mode loads the UNEXPANDED
+ * 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.
+ * emptied nullable fields sent as null (D3). Fields validate when they lose
+ * focus. A failed submit keeps every typed value, puts DRF's messages on their
+ * fields (a summary lists them when more than one fails) and moves focus there.
+ * Any other failure (offline, 403, 409, 5xx) is a banner with "Try again" when
+ * it can help. Escape hatches: per-field overrides (`fields`), `extraFields`,
+ * `transformSubmit`, `actions`, `slots`, `validationMode` / `reValidateMode`
+ * and `guardUnsavedChanges` / `onDirtyChange`.
  */
 export declare function ResourceForm(props: ResourceFormProps): React.ReactElement;

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

@@ -5,16 +5,30 @@ import { FieldDef } from '../../../schema/types';
  * 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).
+ *
+ * Every control receives react-hook-form's ref (so a failed submit can move
+ * focus to it), `aria-invalid`, `aria-describedby` (help text and error) and,
+ * where its role supports it, `aria-required`. A field that shows an error
+ * re-validates on every change, so the error goes away as soon as the value
+ * is fixed. A field without one validates when it loses focus.
  */
 import * as React from "react";
 export interface DefaultFieldControlProps {
     field: FieldDef;
     control: Control<FieldValues>;
     inputId: string;
+    /** The label's id, for controls whose popup needs naming too (ResourceSelect's list). */
+    labelId?: string;
     describedBy?: string;
     invalid: boolean;
+    /** Sets `aria-required` on controls whose role supports it. */
+    required?: boolean;
     disabled?: boolean;
+    /** Re-validate on every change while the field shows an error. Default true. */
+    revalidateWhileInvalid?: 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;
+/** Kinds whose control role cannot carry aria-required (their label says "required" instead). */
+export declare const KINDS_WITHOUT_ARIA_REQUIRED: ReadonlySet<string>;
+export declare function DefaultFieldControl({ field, control, inputId, labelId, describedBy, invalid, required, disabled, revalidateWhileInvalid, inputProps, }: DefaultFieldControlProps): React.ReactElement;

package/dist/src/components/resource/form/form-states.d.ts

@@ -0,0 +1,87 @@
+import { FieldDef } from '../../../schema/types';
+import { ErrorSlotProps } from '../../../states/ErrorState';
+/**
+ * The states <ResourceForm> shows around its fields, as replaceable slots:
+ * the loading skeleton, the permission panel, the error summary after a
+ * failed submit and the banner for a submit that failed for another reason.
+ * Their defaults are exported (`defaultResourceFormSlots`) so a project can
+ * wrap them rather than rewrite them.
+ */
+import * as React from "react";
+/**
+ * A field's label-to-control gap as Tailwind 3's `space-y` draws it: a top
+ * margin on every child after the first. Tailwind 4's `space-y` puts a bottom
+ * margin on the inline <label> instead, which an inline element ignores, so
+ * the gap is spelled out to render the same under both.
+ */
+export declare const FIELD_GAP = "[&>:not([hidden])~:not([hidden])]:mt-2";
+/** The submit row, shared by the form and its skeleton so nothing moves when the form arrives. */
+export declare const SUBMIT_ROW = "flex items-center justify-end gap-3 pt-2";
+export interface ResourceFormLoadingProps {
+    /**
+     * The fields the form will render, labels already overridden, once the
+     * schema is known (edit mode while the row loads). Undefined while the
+     * schema itself loads.
+     */
+    fields?: readonly FieldDef[];
+    /** "create" or "update". */
+    mode: "create" | "update";
+    /** The submit button's label, so the skeleton's button has the real one's width. */
+    submitLabel: React.ReactNode;
+    /** False when the form's `actions` prop replaces the submit row. */
+    showSubmitRow: boolean;
+}
+export interface ResourceFormForbiddenProps {
+    /** The verb the role lacks: "edit". */
+    action: string;
+    /** What it applies to: "this event". */
+    resource: string;
+}
+/** One entry of the error summary. */
+export interface ResourceFormFieldError {
+    /** The field's name. Absent for a message that belongs to no field. */
+    name?: string;
+    /** The field's label, as the form shows it. */
+    label?: string;
+    message: string;
+    /** Moves focus to the field's input. Absent for a message that belongs to no field. */
+    focus?: () => void;
+    /** `#<the input's id>`, for a link to the field. */
+    href?: string;
+}
+export interface ResourceFormErrorSummaryProps {
+    /** "2 fields need attention", or what failed when no field did. */
+    title: string;
+    errors: readonly ResourceFormFieldError[];
+}
+export interface ResourceFormSubmitErrorProps extends ErrorSlotProps {
+    /** Edit mode, after a conflict: loads the latest version of the row (typed values are kept). */
+    onReload?: () => void;
+    /** True while that reload runs. */
+    reloading?: boolean;
+}
+/**
+ * The loading state: the form's own layout with shimmering controls. Once the
+ * schema is known it has the real field count, kinds, labels and help text,
+ * and the submit row sits where the real one will, so nothing shifts when the
+ * values arrive.
+ */
+export declare function ResourceFormSkeleton({ fields, submitLabel, showSubmitRow, }: ResourceFormLoadingProps): React.ReactElement;
+/** The 403-on-load state: the role cannot edit this row, said plainly. */
+export declare function ResourceFormForbidden({ action, resource, }: ResourceFormForbiddenProps): React.ReactElement;
+/** A failed load, with "Try again" when it can help. */
+export declare function ResourceFormLoadError(props: ErrorSlotProps): React.ReactElement;
+/**
+ * Every problem after a failed submit, at the top of the form, each field a
+ * link that moves focus to it (links wrap like text, so a long message keeps
+ * its bullet on its first line). Announced when it appears.
+ */
+export declare function ResourceFormErrorSummary({ title, errors, }: ResourceFormErrorSummaryProps): React.ReactElement;
+/**
+ * A submit that failed for a reason other than the values (offline, the
+ * server, permission, a conflict): a compact banner above the fields, in
+ * describeError's plain words, with "Try again" when it can help and "Load
+ * the latest version" after a conflict. The values the user typed stay in
+ * the fields.
+ */
+export declare function ResourceFormSubmitError({ error, context, onRetry, retrying, onReload, reloading, }: ResourceFormSubmitErrorProps): React.ReactElement;

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

@@ -38,7 +38,7 @@ export interface PrepareSubmitInput {
     /** Resolver output from handleSubmit. */
     raw: FormValues;
     mode: "create" | "update";
-    /** react-hook-form dirtyFields; only consulted in "update" mode (D3). */
+    /** react-hook-form dirtyFields, only consulted in "update" mode (D3). */
     dirtyFields?: Record<string, unknown>;
 }
 export interface PreparedSubmit {
@@ -47,8 +47,8 @@ export interface PreparedSubmit {
     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
+ * The D3 submit pipeline. Create mode sends every defined value. Update mode
+ * sends only fields whose dirtyFields subtree is truthy, and 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/form/server-errors.d.ts

@@ -0,0 +1,14 @@
+export interface MappedServerErrors {
+    /** Field path → its messages, joined into one sentence run. */
+    fields: Record<string, string>;
+    /** Messages that belong to no field the form shows. */
+    root: string[];
+}
+export interface MapServerErrorsOptions {
+    /** Whether the form renders an input for `path` ("title", "address.city"). */
+    isField: (path: string) => boolean;
+    /** How a path is named in a form-level message. The default humanizes it. */
+    labelOf?: (path: string) => string;
+}
+/** Splits a DRF error body into field messages and form-level messages. */
+export declare function mapServerErrors(data: unknown, { isField, labelOf }: MapServerErrorsOptions): MappedServerErrors;

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

@@ -1,18 +1,60 @@
+import { ChangeLogEntry } from '../../../hooks/useChangeHistory';
+import { ErrorSlotProps } from '../../../states/ErrorState';
 import * as React from "react";
+/** What the `Loading` slot receives. */
+export interface ChangeHistoryLoadingProps {
+    /** How many entry placeholders to draw. */
+    rows: number;
+    /** True once loading has taken longer than SLOW_AFTER_MS (500ms): show the placeholder now. */
+    slow: boolean;
+}
+/** What the `Empty` slot receives: the row has no recorded change. */
+export interface ChangeHistoryEmptyProps {
+    /** The `empty` prop ("No changes recorded." by default). */
+    children: React.ReactNode;
+}
+/** What the `Entry` slot receives: one recorded change. */
+export interface ChangeHistoryEntryProps {
+    entry: ChangeLogEntry;
+}
+/**
+ * The replaceable parts of ChangeHistory. Pass any subset as `slots`.
+ * `defaultChangeHistorySlots` holds Karni's own, to wrap them.
+ */
+export interface ChangeHistorySlots {
+    Loading: React.ComponentType<ChangeHistoryLoadingProps>;
+    /** Any failure: offline, server error, 403, a model that keeps no history (404). */
+    Error: React.ComponentType<ErrorSlotProps>;
+    Empty: React.ComponentType<ChangeHistoryEmptyProps>;
+    /** One entry of the list (rendered inside its <li>). */
+    Entry: React.ComponentType<ChangeHistoryEntryProps>;
+}
 export interface ChangeHistoryProps {
     resource: string;
     id: string | number;
-    /** Entries to show (the backend paginates; default: the API's page size). */
+    /** 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;
+    /** The resource in words, singular, for messages ("the history of this event"). Default: from `resource`. */
+    resourceLabel?: string;
+    /** Replace parts of the list: Loading, Error, Empty, Entry. */
+    slots?: Partial<ChangeHistorySlots>;
     className?: string;
 }
+/** Karni's own slots, exported so a project can wrap one instead of rewriting it. */
+export declare const defaultChangeHistorySlots: ChangeHistorySlots;
 /**
  * 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.
+ * in with `class Karni: audit = True`). Fields the role may not see are
+ * already absent from each diff, redacted ones say so, and an empty value
+ * is the shared EmptyValue (a dash, read as "empty").
+ *
+ * States: entry placeholders while it loads (drawn after 500ms), failures
+ * in describeError's words with "Try again" when it can help. A 403 reads
+ * "You can't view the history of this <resource>". Offline says so and
+ * reloads when the connection returns. Escape hatch: `slots`.
  */
-export declare function ChangeHistory({ resource, id, pageSize, title, empty, className, }: ChangeHistoryProps): React.ReactElement;
+export declare function ChangeHistory({ resource, id, pageSize, title, empty, resourceLabel, slots, className, }: ChangeHistoryProps): React.ReactElement;

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

@@ -1,18 +1,84 @@
-import { ImportJob } from '../../../hooks/useResourceImport';
+import { ImportJob, ImportProblem, ImportResult } from '../../../hooks/useResourceImport';
+import { ErrorSlotProps } from '../../../states/ErrorState';
 import * as React from "react";
+/** What the `Loading` slot receives while the import description loads. */
+export interface ResourceImportLoadingProps {
+    /** True once loading has taken longer than SLOW_AFTER_MS (500ms): show the placeholder now. */
+    slow: boolean;
+}
+/** What the `Progress` slot receives while the backend previews or commits a job. */
+export interface ImportProgressProps {
+    job: ImportJob;
+}
+/** What the `Summary` slot receives: a preview's or a commit's counts. */
+export interface ImportSummaryProps {
+    job: ImportJob;
+    result: ImportResult;
+}
+/** What the `Problems` slot receives: the rows the backend refused, with why. */
+export interface ImportProblemsProps {
+    job: ImportJob;
+    problems: readonly ImportProblem[];
+}
+/** What the `ConfirmCommit` slot receives: the step between a preview and its commit. */
+export interface ImportConfirmProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    job: ImportJob;
+    /** The preview's counts: what the commit will do. */
+    result: ImportResult;
+    /** The resource in words, plural: "events". */
+    resourceLabel: string;
+    onConfirm: () => void;
+    /** True while the commit request runs. */
+    pending: boolean;
+    /** Why the last commit attempt failed (null before an attempt and while one runs). */
+    error: unknown;
+}
+/**
+ * The replaceable parts of ResourceImport. Pass any subset as `slots`.
+ * `defaultResourceImportSlots` holds Karni's own, to wrap them.
+ */
+export interface ResourceImportSlots {
+    /** The upload form's placeholder while the import description loads. */
+    Loading: React.ComponentType<ResourceImportLoadingProps>;
+    /** A failure: loading what the import accepts, an upload, a preview. */
+    Error: React.ComponentType<ErrorSlotProps>;
+    /** A running preview or commit. */
+    Progress: React.ComponentType<ImportProgressProps>;
+    /** Created / updated / skipped counts. */
+    Summary: React.ComponentType<ImportSummaryProps>;
+    /** The table of rows with errors. */
+    Problems: React.ComponentType<ImportProblemsProps>;
+    /** The confirmation before a commit. */
+    ConfirmCommit: React.ComponentType<ImportConfirmProps>;
+}
 export interface ResourceImportProps {
     resource: string;
     title?: React.ReactNode;
     /** Called when a commit finishes (the job is `done`). */
     onDone?: (job: ImportJob) => void;
+    /** The resource in words, plural, for messages ("You can't import events"). Default: from `resource`. */
+    resourceLabel?: string;
+    /** Replace parts of the flow: Loading, Error, Progress, Summary, Problems, ConfirmCommit. */
+    slots?: Partial<ResourceImportSlots>;
     className?: string;
 }
+/** Karni's own slots, exported so a project can wrap one instead of rewriting it. */
+export declare const defaultResourceImportSlots: ResourceImportSlots;
 /**
  * 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.
+ * preview (the mandatory dry run, which shows N created / updated / skipped
+ * with every row's errors), confirm, 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.
+ *
+ * States: a placeholder in the form's layout while the import description
+ * loads (drawn after 500ms). When that fails the form is not shown: a 403
+ * reads "You can't import <resource>". A failed upload keeps the chosen file,
+ * offers "Try again" when it can help and moves focus to the error. Offline
+ * requests wait for the connection and say so. Escape hatch: `slots`.
  */
-export declare function ResourceImport({ resource, title, onDone, className, }: ResourceImportProps): React.ReactElement;
+export declare function ResourceImport({ resource, title, onDone, resourceLabel, slots, className, }: ResourceImportProps): React.ReactElement;

package/dist/src/components/resource/nouns.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The words a resource's messages use: "events" → "event" ("Couldn't find
+ * this event"), "loose-slots" → "loose slots" ("You can't import loose
+ * slots"). English rules only. Every component that words a message takes
+ * a `resourceLabel` prop to name the resource in the project's own words.
+ *
+ * Internal to @karni/ui.
+ */
+/** The router prefix as words: "loose-slots" → "loose slots". */
+export declare function pluralNoun(resource: string): string;
+/** One of the resource: "events" → "event", "categories" → "category", "addresses" → "address". */
+export declare function singularNoun(resource: string): string;