@zeroman.yang/react-auto-components 0.1.1 → 0.1.3

package/README.md

@@ -12,7 +12,9 @@ A standalone, schema-driven component library for React 19, covering forms, tabl
 
 ## Project status
 
-The current version is 0.1.1 and APIs may still change. React 19 is required. The package provides ESM and TypeScript declarations. Existing components default to Chinese; AutoChat defaults to English. Built-in text can be translated through AutoConfigProvider.config.t.
+The current version is 0.1.3 and APIs may still change. React 19 is required. The package provides ESM and TypeScript declarations. Built-in interface text defaults to English and can be translated through AutoConfigProvider.config.t.
+
+Agents: start at [llms.txt](llms.txt). It indexes the behavior docs, error codes, JSON registries, and Playwright ids.
 
 Install with `pnpm add @zeroman.yang/react-auto-components` (npm and yarn work the same way). React 19 and react-dom 19 are peer dependencies. Import the stylesheet once: `import "@zeroman.yang/react-auto-components/style.css"`.
 
@@ -126,12 +128,24 @@ The t callback receives a message key and a fallback. Preserve numbered placehol
 | Component       | Capabilities                                                                                                                                                                                                     |
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | AutoForm        | Native field types, virtualized options, cascading selection, upload adapters, custom rendering, dependent fields, conditional visibility, async validation, controlled state, input preservation after failures |
-| AutoSearchPanel | Basic/advanced conditions, manual/instant search, reset, sort tags, a shared query AST, and RSQL serialization                                                                                                   |
+| AutoSearch | Basic/advanced conditions, manual/instant search, reset, sort tags, a shared query AST, and RSQL serialization                                                                                                   |
 | AutoTable       | Local/remote data, multi-column sorting, column filters, pagination, stable selection, virtualization, tree/detail expansion, summaries, merged cells, CRUD, context menus, and copy                             |
 | AutoDialog      | Declarative/imperative APIs, isolated providers, drafts, close guards, focus management, dragging, fullscreen, and async submission                                                                              |
 | AutoTabs        | Horizontal/vertical layouts, nesting, permissions, disabled tabs, preserved panel state, and refresh                                                                                                        |
 | AutoMenu        | Sidebar navigation with icons, descriptions, badges, nested groups, permissions, and a collapsible icon rail                                                                                                     |
-| AutoChat | Caller-owned message rendering, optional virtualization, streaming follow, anchored history loading, send/stop composer, and custom actions |
+| AutoChat | Caller-owned message rendering, optional virtualization, streaming follow, anchored history loading, send/stop composer, and custom actions. [Behavior](docs/auto-chat.md) |
+
+Behavior contracts, including what a thrown callback does: [AutoForm](docs/auto-form.md), [AutoSearch](docs/auto-search.md), [AutoTable](docs/auto-table.md), [AutoDialog](docs/auto-dialog.md), [AutoTabs](docs/auto-tabs.md), [AutoMenu](docs/auto-menu.md). Developer error codes: [errors.md](docs/errors.md).
+
+## Preconditions
+
+Import the stylesheet once: `import "@zeroman.yang/react-auto-components/style.css"`. Without it, `--auto-text` is unset and the page is unstyled. Development mode warns `RAC-CSS-MISSING`.
+
+`AutoConfigProvider` is optional. Defaults are namespace `"auto"`, size `"medium"`, density `"comfortable"`, top labels, and `localStorage`. The namespace is prefixed onto `${namespace}:table:${id}` and `${namespace}:draft:${draftKey}`. Two apps on one origin that both keep `"auto"` share those keys.
+
+`AutoDialogProvider` is required for `useAutoDialog()` and is not provided by `AutoConfigProvider`. `<AutoDialog open>` does not need it.
+
+`exceljs` is an optional dependency used only by `@zeroman.yang/react-auto-components/xlsx`. CSV and JSON export work without it. A missing adapter or a missing `exceljs` install fails with `RAC-TABLE-XLSX` or `RAC-XLSX-DEP`.
 
 Table layout, sorting, filtering, and export each support named presets and independent versions. Persistence defaults to localStorage; remote adapters can be injected. JSON/CSV export is built in. XLSX uses an optional, separate adapter:
 

package/dist/adapters/xlsx.d.ts

@@ -1,7 +1,13 @@
+/**
+ * Optional XLSX writer. Loads `exceljs` on first call.
+ * `exceljs` is an optionalDependency: a normal install can omit it, and the failure is this error rather than a missing-module stack.
+ * Pass the function to `AutoTable` `exportXlsx`. CSV and JSON do not need it.
+ * `sheetName` defaults to `"Data"`. Returns an ArrayBuffer.
+ */
 export declare function exportXlsx(data: {
     headers: string[];
     rows: unknown[][];
 }, options: {
     fileName: string;
     sheetName?: string;
-}): Promise<import("exceljs").Buffer>;
+}): Promise<ArrayBuffer>;

package/dist/components/AutoChat/types.d.ts

@@ -39,7 +39,14 @@ export interface AutoChatLabels {
     tool: string;
     error: string;
 }
+/**
+ * Conversation shell. Message text is the host's: a string is rendered as text, anything else is your React node.
+ * `onSend` rejection keeps the draft and shows a generic error. See the `onSend` prop.
+ * Defaults: `height` `"100%"`, `autoFollow` `true`, `composer` `true`, `sendOnEnter` `true`,
+ * `messageLayout` `"role"`, `estimatedMessageHeight` `120`, `overscan` `6`.
+ */
 export interface AutoChatProps<T extends AutoChatMessage = AutoChatMessage> {
+    /** Newest message last. Ids must stay stable while a reply streams. */
     messages: readonly T[];
     /** Own Markdown, code, tool output and attachment rendering in the host. */
     renderMessage?: (message: T, context: {

package/dist/components/AutoDialog/index.d.ts

@@ -1,6 +1,13 @@
 import { type ReactNode } from "react";
 import type { ComponentSize, Field } from "../../core/types";
+/** Why a dialog closed. `"submit"` only happens after `onSubmit` resolves and `beforeClose` allows it. */
 export type CloseReason = "cancel" | "close" | "submit";
+/**
+ * Dialog content. Provide `fields` for a schema form, or `content` for custom nodes.
+ * `onSubmit` rejection keeps the dialog open and shows `error.message`. Values stay.
+ * `beforeClose` returning `false` cancels the close. Throwing also cancels it and shows the message.
+ * `draftKey` persists the draft at `${namespace}:draft:${draftKey}` until a successful submit clears it.
+ */
 export interface DialogOptions<T extends object> {
     title: string;
     description?: string;
@@ -8,7 +15,15 @@ export interface DialogOptions<T extends object> {
     fields?: readonly Field<T>[];
     defaultValue?: Partial<T>;
     draftKey?: string;
+    /**
+     * Resolve to close (after `beforeClose`). Reject or throw to stay open and show the message.
+     * A failed `validate()` does not call this.
+     */
     onSubmit?: (values: T) => void | Promise<void>;
+    /**
+     * Return `false` to keep the dialog open. Throw to keep it open and show `error.message`.
+     * Runs for submit, cancel, and dismiss.
+     */
     beforeClose?: (reason: CloseReason) => boolean | Promise<boolean>;
     onClose?: (reason: CloseReason) => void;
     size?: ComponentSize;

package/dist/components/AutoForm/types.d.ts

@@ -1,5 +1,11 @@
 import type { CSSProperties, ReactNode, Ref } from "react";
 import type { Field, FieldName, AutoFormLayout } from "../../core/types";
+/**
+ * Imperative form API.
+ * `validate` resolves `false` when a visible field fails or an upload is still running. It does not throw.
+ * `reset` restores `defaultValue` (or the object you pass) and clears errors.
+ * `setValue` runs that field's `onChange` patch. `focus` focuses the control for `name`.
+ */
 export interface AutoFormHandle<T extends object> {
     validate(): Promise<boolean>;
     reset(values?: T): void;
@@ -7,17 +13,39 @@ export interface AutoFormHandle<T extends object> {
     setValue<K extends FieldName<T>>(name: K, value: T[K]): void;
     focus(name: FieldName<T>): void;
 }
+/**
+ * Schema form. Pass `value` to control it; otherwise the form keeps state and reports it through `onChange`.
+ * `onSubmit` runs only after validation. A rejection keeps the values, shows `error.message`, and does not reset.
+ * Field `rules` and `onChange` have their own failure behavior. See docs/auto-form.md.
+ *
+ * `columns` defaults to `2`. `actions` defaults to `true` (submit + reset).
+ * Label layout defaults come from `AutoConfigProvider` (`labelPosition` `"top"`, `labelWidth` `"auto"`).
+ */
 export interface AutoFormProps<T extends object> extends AutoFormLayout {
+    /** Checked schema. Use `unsafeField` only to bypass a discriminant on purpose. */
     fields: readonly Field<T>[];
+    /** Controlled value. The form copies it in when it differs from internal state. */
     value?: T;
+    /** Used for the uncontrolled initial value and for reset. Field `defaultValue` fills gaps. */
     defaultValue?: Partial<T>;
+    /** Fires after every accepted edit. Omit it to keep state inside the form. */
     onChange?: (value: T) => void;
+    /**
+     * Called with the full value after validation passes.
+     * Resolve to finish. Reject to keep the draft and show the error under the actions.
+     */
     onSubmit?: (value: T) => void | Promise<void>;
+    /** Called after a successful reset, including the reset button. */
     onReset?: () => void;
+    /** Blocks edits and submit. Default `false`. */
     disabled?: boolean;
+    /** Renders values without inputs. Default `false`. */
     readOnly?: boolean;
+    /** Grid column count. Default `2`. */
     columns?: number;
+    /** Render the built-in submit and reset buttons. Default `true`. Set `false` when the parent supplies buttons. */
     actions?: boolean;
+    /** Defaults to the built-in "Submit", translated with `config.t`. */
     submitLabel?: string;
     resetLabel?: string;
     extraActions?: ReactNode;

package/dist/components/AutoMenu/index.d.ts

@@ -14,8 +14,15 @@ export interface AutoMenuItem extends Access {
     /** Sub-menu entries; clicking a parent toggles its expansion. */
     children?: readonly AutoMenuItem[];
 }
+/**
+ * Sidebar navigation. `value` is the selected leaf id. Omit it to use internal state starting at `defaultValue`.
+ * `onChange` is not caught. A cyclic `children` list is dropped so a bad schema cannot recurse forever.
+ * `collapsible` defaults to `false`. `collapsed` controls the icon rail; otherwise `defaultCollapsed` (default `false`) is used.
+ * Items that are hidden, disabled by an ancestor, or rejected by `canAccess` are not rendered.
+ */
 export interface AutoMenuProps {
     items: readonly AutoMenuItem[];
+    /** Selected leaf id. Pass it to control selection. */
     value?: string;
     defaultValue?: string;
     onChange?: (id: string, item: AutoMenuItem, path: readonly string[]) => void;

package/dist/components/AutoSearch/index.d.ts

@@ -0,0 +1,40 @@
+import { type QueryNode } from "../../core/query";
+import type { Field, AutoFormLayout } from "../../core/types";
+/**
+ * Search form that emits a {@link QueryNode} plus the raw values.
+ * `mode` defaults to `"manual"` (search on submit). `"instant"` also searches on every change.
+ * `columns` defaults to `3`.
+ * A thrown `onSearch` is caught by the inner form: values stay, and the error string is shown. Reset is not implied.
+ * Empty values are omitted. `match: "isNull"` is the exception and matches null.
+ * `match: "between"` requires a two-item value. See docs/auto-search.md.
+ */
+export interface AutoSearchProps<T extends object> extends AutoFormLayout {
+    fields: readonly Field<T>[];
+    value?: T;
+    defaultValue?: Partial<T>;
+    /** Fires when the draft changes, including reset. */
+    onChange?: (values: T) => void;
+    /**
+     * Required. Receives the built query and the values.
+     * Reject or throw to keep the draft and show `error.message`.
+     */
+    onSearch: (query: QueryNode, values: T) => void;
+    /** Default `"manual"`. `"instant"` searches on each change as well as on submit. */
+    mode?: "manual" | "instant";
+    /** Default `3`. */
+    columns?: number;
+    disabled?: boolean;
+    searchLabel?: string;
+    resetLabel?: string;
+    extraActions?: React.ReactNode;
+    sortTags?: readonly {
+        id: string;
+        label: string;
+        onRemove: () => void;
+    }[];
+}
+export declare function AutoSearch<T extends object>({ fields, value, defaultValue, onChange, onSearch, mode, columns, labelPosition, labelAlign, labelWidth, density: ownDensity, size: ownSize, disabled, searchLabel, resetLabel, extraActions, sortTags, }: AutoSearchProps<T>): import("react").JSX.Element;
+/** @deprecated Use {@link AutoSearchProps}. */
+export type AutoSearchPanelProps<T extends object> = AutoSearchProps<T>;
+/** @deprecated Use {@link AutoSearch}. */
+export declare const AutoSearchPanel: typeof AutoSearch;

package/dist/components/AutoTable/registry.d.ts

@@ -0,0 +1,8 @@
+import type { ColumnRegistry, SourceLoader } from "../../core/registry";
+import type { AutoColumn, AutoTableProps, DataSource, RowAction } from "./types";
+/** Copy registry functions onto a column. A function already on the column wins. */
+export declare function resolveColumn<T extends object>(column: AutoColumn<T>, registry: Record<string, ColumnRegistry>): AutoColumn<T>;
+/** `data` wins, then `dataSource`, then `config.sources[source]`. */
+export declare function resolveDataSource<T extends object>(props: AutoTableProps<T>, sources: Record<string, SourceLoader>): DataSource<T> | undefined;
+/** `onClick` wins. Otherwise call `config.rowActions[action]`. */
+export declare function resolveRowAction<T>(action: RowAction<T>, registry: Record<string, (row: object) => void | Promise<void>>): (row: T) => void | Promise<void>;

package/dist/components/AutoTable/types.d.ts

@@ -1,24 +1,41 @@
-import type { AutoSearchPanelProps } from "../AutoSearchPanel";
+import type { AutoSearchProps } from "../AutoSearch";
 import type { CSSProperties, ReactNode, Ref } from "react";
 import type { Access, ComponentSize, Field, FieldName, Option, TableDensity } from "../../core/types";
 import type { QueryNode } from "../../core/query";
 export interface TableSort {
+    /** Column key. */
     id: string;
     desc: boolean;
 }
+/**
+ * The query sent to `dataSource` and stored for local filtering.
+ * `pageIndex` is zero-based. `pageSize` defaults from the `pageSize` prop (`10`).
+ */
 export interface TableQuery {
     pageIndex: number;
     pageSize: number;
     sort: TableSort[];
+    /** Same AST as `AutoSearch` `onSearch`. */
     filter: QueryNode;
 }
+/**
+ * One page of a remote table. Called again when the query changes; the previous call is aborted.
+ * Reject to show `error.message` and a retry button. Resolve `{ rows, total }`.
+ * `total` is the full filtered count, not the page length. Export walks pages until `total` is covered.
+ */
 export type DataSource<T> = (query: TableQuery, context: {
     signal: AbortSignal;
 }) => Promise<{
     rows: T[];
     total: number;
 }>;
+/** `"page"` is the current page. `"filtered"` is every local match, or every remote page when exporting. `"selected"` is the selection. */
 export type RowScope = "page" | "filtered" | "selected";
+/**
+ * One column. `key` must be a field of `T`.
+ * `type` only affects formatting (`date`, `percentage`, …). It is not a form field type.
+ * Omit `columns` and the table uses the keys of the first row, skipping keys that start with `_auto_`.
+ */
 export interface AutoColumn<T extends object> extends Access {
     key: FieldName<T>;
     label?: string;
@@ -35,32 +52,64 @@ export interface AutoColumn<T extends object> extends Access {
     format?: (value: T[FieldName<T>], row: T) => string | number;
     render?: (value: T[FieldName<T>], row: T, index: number) => ReactNode;
     sort?: (a: T, b: T) => number;
+    /**
+     * Key in `AutoConfigProvider` `config.columns`.
+     * Fills `render`, `format`, `sort`, and `exportFormat` when that function is omitted.
+     * A function on the column wins. An unknown key warns `RAC-COLUMN-COMPONENT` and the cell uses the default format.
+     */
+    component?: string;
     export?: boolean;
     exportFormat?: (row: T) => unknown;
     summary?: boolean | ((rows: readonly T[]) => ReactNode);
     merge?: boolean;
     copyable?: boolean;
 }
+/**
+ * A row menu action. `onClick` rejection is caught and shown in the table status for about 2.5s.
+ * The row is not removed unless your handler changes `data`.
+ */
 export interface RowAction<T> {
     id: string;
     label: string;
     hidden?: (row: T) => boolean;
     disabled?: (row: T) => boolean;
-    onClick: (row: T) => void | Promise<void>;
+    /**
+     * Key in `config.rowActions`. Used when `onClick` is omitted. `onClick` wins.
+     * Neither one warns `RAC-ROW-ACTION` when the item is chosen.
+     */
+    action?: string;
+    onClick?: (row: T) => void | Promise<void>;
 }
+/**
+ * `refresh` re-runs `dataSource`. `reset` clears sort, filter, selection, and saved layout back to the column defaults.
+ * `export` rejects are caught; the status shows the translated message. `"xlsx"` without `exportXlsx` throws `RAC-TABLE-XLSX`.
+ */
 export interface AutoTableHandle<T> {
     refresh(): void;
     reset(): void;
+    /** `id` is the `rowKey` string. No-op when that id is not in the loaded rows. */
     scrollToRow(id: string): void;
     getSelectedRows(): T[];
     export(format: "csv" | "json" | "xlsx", scope?: RowScope): Promise<void>;
 }
+/**
+ * Shared table props. Pass exactly one of `data` or `dataSource` ({@link AutoTableProps}).
+ * `id` is required: settings are stored at `${namespace}:table:${id}`. An empty id warns in dev (`RAC-TABLE-ID`).
+ * `rowKey` must be unique per loaded row. Duplicates warn in dev (`RAC-TABLE-ROWID`).
+ */
 export interface TableBaseProps<T extends object> {
+    /** Stable id. Becomes the localStorage / settings key together with `namespace`. */
     id: string;
     columns?: readonly AutoColumn<T>[];
+    /**
+     * Identity of a row. A field name is stringified. A function should return a stable unique string.
+     * Selection, expansion, and `scrollToRow` all use it.
+     */
     rowKey: FieldName<T> | ((row: T) => string);
     title?: string;
+    /** Default `10`. */
     pageSize?: number;
+    /** Default `true`. */
     pagination?: boolean;
     query?: TableQuery;
     onQueryChange?: (query: TableQuery) => void;
@@ -71,7 +120,7 @@ export interface TableBaseProps<T extends object> {
     size?: ComponentSize;
     density?: TableDensity;
     searchFields?: readonly Field<T>[];
-    searchLayout?: Pick<AutoSearchPanelProps<T>, "columns" | "labelPosition" | "labelAlign" | "labelWidth" | "density" | "size">;
+    searchLayout?: Pick<AutoSearchProps<T>, "columns" | "labelPosition" | "labelAlign" | "labelWidth" | "density" | "size">;
     formFields?: readonly Field<T>[];
     onAdd?: (values: T) => void | Promise<void>;
     onEdit?: (row: T, values: T) => void | Promise<void>;
@@ -89,6 +138,11 @@ export interface TableBaseProps<T extends object> {
     /** Server aggregates for the complete filtered result, keyed by column. */
     summaryValues?: Partial<Record<FieldName<T>, ReactNode>>;
     versions?: Partial<Record<"layout" | "sort" | "filter" | "export", string | number>>;
+    /**
+     * Required for `format: "xlsx"`. CSV and JSON work without it.
+     * The packaged adapter is `exportXlsx` from `@zeroman.yang/react-auto-components/xlsx` and needs the optional `exceljs` dependency.
+     * Missing adapter: thrown `RAC-TABLE-XLSX`, UI string "Configure the XLSX export adapter".
+     */
     exportXlsx?: (data: {
         headers: string[];
         rows: unknown[][];
@@ -98,10 +152,22 @@ export interface TableBaseProps<T extends object> {
     empty?: ReactNode;
     ref?: Ref<AutoTableHandle<T>>;
 }
+/**
+ * Local rows, a remote page function, or a `config.sources` key. Pass exactly one.
+ * `source` looks up `AutoConfigProvider` `config.sources`. An unknown key warns
+ * `RAC-TABLE-SOURCE` and the table shows that message with retry.
+ * Passing more than one owner is a type error.
+ */
 export type AutoTableProps<T extends object> = TableBaseProps<T> & ({
     data: readonly T[];
     dataSource?: never;
+    source?: never;
 } | {
     data?: never;
     dataSource: DataSource<T>;
+    source?: never;
+} | {
+    data?: never;
+    dataSource?: never;
+    source: string;
 });

package/dist/components/AutoTabs/index.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from "react";
 import type { Access, ComponentDensity, ComponentSize } from "../../core/types";
+export * from "./useAutoTabsWorkspace";
 export interface AutoTab extends Access {
     id: string;
     label: string;
@@ -13,17 +14,35 @@ export interface AutoTab extends Access {
     loading?: boolean;
     onRefresh?: () => void;
     defaultActive?: string;
+    /** Shows a close button when the group also supplies `onClose`. */
+    closable?: boolean;
 }
+/**
+ * Tab list. `value` is the path of selected ids from the root, so nested tabs are `["parent", "child"]`.
+ * `mode` defaults to `"horizontal"`. `keepMounted` defaults to `true` (hidden panels stay mounted; `false` unmounts them).
+ * `onChange` and `onRefresh` are not caught. A throw leaves the previously selected tab in place only if you never committed the change.
+ * Disabled tabs are skipped when choosing the default selection. Hidden tabs and failed `canAccess` are removed.
+ */
 export interface AutoTabsProps {
     items: readonly AutoTab[];
+    /** Controlled selection path. Omit to let the tabs keep state from `defaultValue`. */
     value?: readonly string[];
     defaultValue?: readonly string[];
+    /** Fires with the full path and the tab that was chosen. Not caught if it throws. */
     onChange?: (path: readonly string[], item: AutoTab) => void;
-    /** Tab orientation. Use AutoMenu for hierarchical navigation. */
+    /** Tab orientation. Use AutoMenu for hierarchical navigation. Default `"horizontal"`. */
     mode?: "horizontal" | "vertical";
+    /**
+     * Default `true`: inactive panels stay mounted and keep state.
+     * `false` unmounts them, so local state inside panel content is destroyed.
+     */
     keepMounted?: boolean;
+    /** Mount a panel on its first visit. Combine with `keepMounted` to retain visited panels. Default `false`. */
+    lazy?: boolean;
+    /** Requests removal; the owner must update `items`. Nested groups report the full path. */
+    onClose?: (path: readonly string[], item: AutoTab) => void;
     extra?: ReactNode;
     size?: ComponentSize;
     density?: ComponentDensity;
 }
-export declare function AutoTabs({ items, value, defaultValue, onChange, mode, keepMounted, extra, size: ownSize, density: ownDensity, }: AutoTabsProps): import("react").JSX.Element;
+export declare function AutoTabs({ items, value, defaultValue, onChange, mode, keepMounted, lazy, onClose, extra, size: ownSize, density: ownDensity, }: AutoTabsProps): import("react").JSX.Element;

package/dist/components/AutoTabs/useAutoTabsWorkspace.d.ts

@@ -0,0 +1,65 @@
+import { type ReactNode } from "react";
+import type { Access, StorageAdapter } from "../../core/types";
+import type { AutoTab, AutoTabsProps } from "./index";
+/** Only JSON data is persisted; components and callbacks belong in the page registry. */
+export type AutoTabsJSON = null | boolean | number | string | readonly AutoTabsJSON[] | {
+    readonly [key: string]: AutoTabsJSON;
+};
+export interface AutoWorkspaceTab {
+    /** Stable business identity. Opening an existing id activates it without replacing its draft. */
+    id: string;
+    page: string;
+    title?: string;
+    params?: AutoTabsJSON;
+    state?: AutoTabsJSON;
+    /** Cannot be closed. Pinned default tabs are also restored if missing from storage. */
+    pinned?: boolean;
+}
+export interface AutoWorkspacePage extends Access {
+    title: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    hidden?: boolean | (() => boolean);
+    /** Validate persisted parameters/state against the application's current schema. */
+    validate?: (tab: Readonly<AutoWorkspaceTab>) => boolean;
+    render: (context: {
+        tab: Readonly<AutoWorkspaceTab>;
+        /** Replaces this tab's persisted state. Use null to clear it. */
+        setState: (state: AutoTabsJSON | ((previous: AutoTabsJSON | undefined) => AutoTabsJSON)) => boolean;
+    }) => ReactNode;
+}
+export interface AutoTabsWorkspaceOptions {
+    /** Storage key is `${namespace}:tabs:${workspaceId}`. Include user/tenant identity when needed. */
+    workspaceId: string;
+    pages: Readonly<Record<string, AutoWorkspacePage>>;
+    defaultTabs?: readonly AutoWorkspaceTab[];
+    defaultActiveId?: string;
+    /** Default sessionStorage. `false` keeps everything in memory. An adapter uses the provider's storage contract. */
+    storage?: "session" | "local" | StorageAdapter | false;
+    /** False or a rejection cancels the close. Rejections propagate from `close()`. */
+    beforeClose?: (tab: Readonly<AutoWorkspaceTab>) => boolean | Promise<boolean>;
+    /** Storage failures leave the workspace usable in memory. */
+    onPersistenceError?: (error: unknown) => void;
+}
+export interface AutoTabsWorkspace {
+    /** False until the client has restored storage, avoiding hydration differences and premature page requests. */
+    ready: boolean;
+    tabs: readonly AutoWorkspaceTab[];
+    activeId: string | undefined;
+    items: readonly AutoTab[];
+    /** Spread onto AutoTabs. Defaults to lazy mounting and retaining visited panels. */
+    tabsProps: Pick<AutoTabsProps, "items" | "value" | "onChange" | "onClose" | "keepMounted" | "lazy">;
+    /** Returns false before restoration or for an unknown, disabled, inaccessible, or invalid page. */
+    open: (tab: AutoWorkspaceTab) => boolean;
+    activate: (id: string) => boolean;
+    /** Selects the next available neighbor when the active tab is closed. Concurrent closes of one id are ignored. */
+    close: (id: string) => Promise<boolean>;
+    setTabState: (id: string, state: AutoTabsJSON | ((previous: AutoTabsJSON | undefined) => AutoTabsJSON)) => boolean;
+}
+/**
+ * Manages a flat group of dynamic pages without depending on a router.
+ * Restoration runs after mount. Tabs, selection, parameters and explicit page state survive refresh;
+ * arbitrary component state does not. Use one owner per storage key and await `ready` before opening pages.
+ * Changing the namespace, workspaceId or storage adapter switches to an independent workspace.
+ */
+export declare function useAutoTabsWorkspace(options: AutoTabsWorkspaceOptions): AutoTabsWorkspace;

package/dist/core/AutoConfigProvider.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import type { ColumnRegistry, SourceLoader } from "./registry";
 import type { Access, AutoFormLayout, ComponentDensity, ComponentSize, FieldContext, SettingsAdapter, StorageAdapter, TableDensity, Values } from "./types";
 export interface TableGlobalConfig {
     density?: TableDensity;
@@ -12,7 +13,20 @@ export interface MenuGlobalConfig {
     density?: ComponentDensity;
     size?: ComponentSize;
 }
+/**
+ * App-wide defaults. The provider is optional.
+ * With no provider, `namespace` is `"auto"`, `size` is `"medium"`, `density` is `"comfortable"`,
+ * form labels sit on top, `t` returns the key, `canAccess` allows everything, and storage is `localStorage`.
+ *
+ * `namespace` is prepended to persisted keys: `${namespace}:table:${tableId}` and `${namespace}:draft:${draftKey}`.
+ * Two apps on one origin that both leave `"auto"` share table settings and dialog drafts. Set a distinct namespace per app.
+ * This provider does not mount dialogs. `useAutoDialog()` still needs `AutoDialogProvider`.
+ */
 export interface AutoServices {
+    /**
+     * Storage prefix. Default `"auto"`.
+     * Change it when more than one app on the same origin uses tables or dialog drafts.
+     */
     namespace: string;
     size?: ComponentSize;
     density?: ComponentDensity;
@@ -25,7 +39,20 @@ export interface AutoServices {
     storage: StorageAdapter;
     settings?: SettingsAdapter;
     notify: (message: string, level: "success" | "error") => void;
+    /** Custom field widgets, keyed for `Field.component`. */
     fields: Record<string, (context: FieldContext<Values>) => ReactNode>;
+    /**
+     * Column render, format, sort, and export functions, keyed for `AutoColumn.component`.
+     * A function on the column wins over the registry.
+     */
+    columns: Record<string, ColumnRegistry>;
+    /** Row menu handlers, keyed for `RowAction.action` when `onClick` is omitted. */
+    rowActions: Record<string, (row: object) => void | Promise<void>>;
+    /**
+     * Remote table loaders, keyed for `AutoTable` `source`.
+     * The registered function must return rows of that table's model.
+     */
+    sources: Record<string, SourceLoader>;
 }
 export declare function AutoConfigProvider({ config, children, }: {
     config?: Partial<AutoServices>;

package/dist/core/config.d.ts

@@ -1,4 +1,4 @@
-import type { Option, StorageAdapter } from "./types";
+import type { AnyField, Field, Option, StorageAdapter } from "./types";
 export declare function resolve<V, T>(value: V | ((values: T) => V) | undefined, values: T, fallback: V): V;
 export declare function defaults<T extends object>(fields: readonly {
     name?: string;
@@ -6,5 +6,10 @@ export declare function defaults<T extends object>(fields: readonly {
 }[], initial?: Partial<T>): T;
 export declare function normalizeOptions(options: readonly Option[]): readonly Option[];
 export declare const safeStorage: StorageAdapter;
+/**
+ * Skip the {@link Field} discriminant. `select` without `options` then compiles.
+ * Dev mode still warns. Prefer a typed `Field<T>` literal.
+ */
+export declare function unsafeField<T extends object>(field: AnyField<T>): Field<T>;
 export declare function errorMessage(error: unknown): string;
 export declare function equal(a: unknown, b: unknown): boolean;

package/dist/core/dev.d.ts

@@ -0,0 +1,27 @@
+/** The field props dev mode can check without knowing T. */
+interface WarnField {
+    name?: string;
+    type?: string;
+    options?: unknown;
+    render?: unknown;
+    component?: string;
+    defaultValue?: unknown;
+    match?: string;
+}
+/** Forget dev-warning dedupe and the one-shot CSS check. Tests only. */
+export declare function resetDevChecks(): void;
+/**
+ * Warn for field contracts that `AnyField` / `unsafeField` can bypass.
+ * `values` is the current form value, so a controlled scalar on a date range is visible.
+ */
+export declare function warnFields(component: string, fields: readonly WarnField[] | undefined, values?: object): void;
+export declare function warnRowKeys<T extends object>(rows: readonly T[] | undefined, rowKey: keyof T | ((row: T) => string)): void;
+export declare function warnTableId(id: string, namespace: string): void;
+/**
+ * style.css sets `--auto-text` on `:root`. If it is missing, the page is unstyled and the DOM does not say why.
+ * Warns once per page load.
+ */
+export declare function warnIfStylesMissing(): void;
+export declare function useLibraryStyles(): void;
+export declare function useFieldWarnings(component: string, fields: readonly WarnField[] | undefined, values?: object): void;
+export {};

package/dist/core/errors.d.ts

@@ -0,0 +1,20 @@
+/** Developer errors. UI strings stay on `userKey` and go through `config.t`. */
+export declare class RacError extends Error {
+    /** Stable id. Anchors live in docs/errors.md. */
+    readonly code: string;
+    /**
+     * Built-in UI sentence (English source, translated by `config.t`).
+     * Absent when the failure is only for the developer console.
+     */
+    readonly userKey?: string;
+    constructor(component: string, code: string, problem: string, fix: string, userKey?: string);
+}
+/** One shape for thrown errors and dev warnings: component, fact, repair, code, doc anchor. */
+export declare function racMessage(component: string, code: string, problem: string, fix: string): string;
+/** `console.warn` once per problem. No-op in production. */
+export declare function devWarn(component: string, code: string, problem: string, fix: string): void;
+export declare function resetDevWarnings(): void;
+/** What a bad value looks like in a warning. Not a serialized payload. */
+export declare function valueKind(value: unknown): string;
+/** Translated UI text for a caught error. RacError uses `userKey`; anything else uses `error.message`. */
+export declare function userText(tr: (message: string, values?: readonly unknown[]) => string, error: unknown): string;

package/dist/core/query.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Filter tree shared by search panels and tables.
+ * A `"between"` condition's `value` must be a two-item array. `"in"` must be an array.
+ * `isQueryNode` rejects other shapes before they are evaluated.
+ */
 export type QueryNode = {
     kind: "condition";
     field: string;
@@ -10,6 +15,10 @@ export type QueryNode = {
     children: readonly QueryNode[];
 };
 export declare const emptyQuery: QueryNode;
+/**
+ * The search slice of a field. `buildQuery` reads only these props.
+ * `match: "between"` expects the form value to be `[from, to]`. A scalar warns in dev and does not match rows.
+ */
 export interface SearchField {
     name?: string;
     match?: "eq" | "in" | "contains" | "between" | "isNull";