rich-react-component 0.1.0

package/dist/remote/RemoteComboBox.d.ts

@@ -0,0 +1,21 @@
+import { ComboBoxProps } from '../base';
+import { HttpClient } from './http/HttpClient';
+export interface RemoteComboBoxProps<TValue extends string | number = string, TResponse = unknown> extends Omit<ComboBoxProps<TValue>, "options" | "loading"> {
+    url: string;
+    params?: Record<string, unknown>;
+    /** Key read off each raw remote item to produce the option's `value` (doc section 4). */
+    valueMember: string;
+    /** Key read off each raw remote item to produce the option's `label`. */
+    displayMember: string;
+    /** Escape hatch for response envelopes beyond bare array / `{ items: [...] }` (doc section 11). */
+    mapResponse?: (response: TResponse) => unknown[];
+    client?: HttpClient;
+    enabled?: boolean;
+}
+/**
+ * Adds remote-loading behavior to Base ComboBox by composing it — this is
+ * NOT a second independent ComboBox implementation (doc section 20). All
+ * selection/keyboard/popup UI behavior is Base ComboBox's; this component
+ * only owns fetch lifecycle + raw-item -> SelectOption mapping.
+ */
+export declare function RemoteComboBox<TValue extends string | number = string, TResponse = unknown>({ url, params, valueMember, displayMember, mapResponse, client, enabled, ...comboBoxProps }: RemoteComboBoxProps<TValue, TResponse>): import("react").JSX.Element;

package/dist/remote/RemoteDataGrid.d.ts

@@ -0,0 +1,24 @@
+import { DataGridProps } from '../base';
+import { HttpClient } from './http/HttpClient';
+export interface RemoteDataGridProps<TRow, TResponse = unknown> extends Omit<DataGridProps<TRow>, "rows" | "loading" | "error" | "page" | "pageSize" | "totalCount" | "onPageChange" | "sort" | "onSortChange"> {
+    url: string;
+    /** Additional filter params (e.g. `{ countryId }`) — page/pageSize/sort are managed internally. */
+    params?: Record<string, unknown>;
+    mapResponse?: (response: TResponse) => TRow[];
+    /**
+     * Extension point: read a total row count out of the raw response, when
+     * the backend provides one. Strongly recommended — without it, pagination
+     * falls back to a has-more heuristic (a full page implies "at least one
+     * more page exists") which cannot show an exact page count.
+     */
+    getTotalCount?: (response: TResponse) => number | undefined;
+    pageSize?: number;
+    client?: HttpClient;
+}
+/**
+ * Adds paging/sorting-against-a-server-endpoint behavior to Base DataGrid
+ * by composing it. All table rendering, selection, and pagination/sort UI
+ * remain Base DataGrid's — this component only owns request params
+ * (page/pageSize/sort/filters) and response mapping (doc section 10).
+ */
+export declare function RemoteDataGrid<TRow, TResponse = unknown>({ url, params, mapResponse, getTotalCount, pageSize, client, ...dataGridProps }: RemoteDataGridProps<TRow, TResponse>): import("react").JSX.Element;

package/dist/remote/RemoteMultiSelect.d.ts

@@ -0,0 +1,13 @@
+import { MultiSelectProps } from '../base';
+import { HttpClient } from './http/HttpClient';
+export interface RemoteMultiSelectProps<TValue extends string | number = string, TResponse = unknown> extends Omit<MultiSelectProps<TValue>, "options" | "loading"> {
+    url: string;
+    params?: Record<string, unknown>;
+    valueMember: string;
+    displayMember: string;
+    mapResponse?: (response: TResponse) => unknown[];
+    client?: HttpClient;
+    enabled?: boolean;
+}
+/** Same reuse pattern as RemoteComboBox/RemoteSelect, composing Base MultiSelect. */
+export declare function RemoteMultiSelect<TValue extends string | number = string, TResponse = unknown>({ url, params, valueMember, displayMember, mapResponse, client, enabled, ...multiSelectProps }: RemoteMultiSelectProps<TValue, TResponse>): import("react").JSX.Element;

package/dist/remote/RemoteSelect.d.ts

@@ -0,0 +1,17 @@
+import { SelectProps } from '../base';
+import { HttpClient } from './http/HttpClient';
+export interface RemoteSelectProps<TValue extends string | number = string, TResponse = unknown> extends Omit<SelectProps<TValue>, "options" | "loading"> {
+    url: string;
+    params?: Record<string, unknown>;
+    valueMember: string;
+    displayMember: string;
+    mapResponse?: (response: TResponse) => unknown[];
+    client?: HttpClient;
+    enabled?: boolean;
+}
+/**
+ * Same reuse pattern as RemoteComboBox: composes Base Select instead of
+ * reimplementing it (doc section 20). Thin — only fetch lifecycle +
+ * valueMember/displayMember mapping belong here.
+ */
+export declare function RemoteSelect<TValue extends string | number = string, TResponse = unknown>({ url, params, valueMember, displayMember, mapResponse, client, enabled, ...selectProps }: RemoteSelectProps<TValue, TResponse>): import("react").JSX.Element;

package/dist/remote/hooks/useDebouncedValue.d.ts

@@ -0,0 +1 @@
+export declare function useDebouncedValue<T>(value: T, delayMs: number): T;

package/dist/remote/hooks/useRemoteData.d.ts

@@ -0,0 +1,31 @@
+import { HttpClient } from '../http/HttpClient';
+export type RemoteState = "idle" | "loading" | "success" | "empty" | "error";
+export interface UseRemoteDataOptions<TResponse, TItem> {
+    client?: HttpClient;
+    /** `null`/`undefined` disables fetching entirely (e.g. RemoteAutoComplete below minSearchLength). */
+    url: string | null | undefined;
+    params?: Record<string, unknown>;
+    mapResponse: (response: TResponse) => TItem[];
+    enabled?: boolean;
+}
+export interface UseRemoteDataResult<TItem> {
+    state: RemoteState;
+    items: TItem[];
+    error: Error | null;
+    reload: () => void;
+}
+/**
+ * The one place remote/API data fetching lifecycle logic lives. Every
+ * Remote Component (RemoteComboBox, RemoteAutoComplete, RemoteDataGrid)
+ * composes this instead of writing its own fetch effect (doc section 6).
+ *
+ * Handles, per doc sections 5/7/8:
+ *  - stable request identity: params are compared by serialized *value*,
+ *    not object reference, so a new `{ ...params }` literal each render
+ *    does not cause an infinite request loop.
+ *  - request cancellation via AbortController.
+ *  - stale-response protection via a monotonically increasing request id,
+ *    which still guards correctness even if abort doesn't win the race.
+ *  - a consistent idle/loading/success/empty/error state model.
+ */
+export declare function useRemoteData<TResponse, TItem>({ client, url, params, mapResponse, enabled, }: UseRemoteDataOptions<TResponse, TItem>): UseRemoteDataResult<TItem>;

package/dist/remote/http/HttpClient.d.ts

@@ -0,0 +1,31 @@
+export interface HttpRequestOptions {
+    params?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface HttpClient {
+    get<TResponse>(url: string, options?: HttpRequestOptions): Promise<TResponse>;
+}
+export declare class HttpError extends Error {
+    status: number;
+    statusText: string;
+    url: string;
+    constructor(status: number, statusText: string, url: string);
+}
+export interface CreateHttpClientOptions {
+    baseUrl?: string;
+    /** Injectable fetch implementation — used by tests, could also route through a wrapped/instrumented fetch. */
+    fetcher?: typeof fetch;
+    /**
+     * Extension point for cross-cutting concerns the doc explicitly defers
+     * (authorization, tenant headers, interceptors) without building them now
+     * (doc section 6: only establish extension points where justified).
+     */
+    buildRequestInit?: (url: string, init: RequestInit) => RequestInit;
+}
+/**
+ * The single place Remote Components go through to talk to a backend.
+ * Base Components never import this (enforced by dependency direction, not
+ * just convention — Base has no dependency on `remote/*` at all).
+ */
+export declare function createHttpClient(options?: CreateHttpClientOptions): HttpClient;
+export declare const defaultHttpClient: HttpClient;

package/dist/remote/index.d.ts

@@ -0,0 +1,9 @@
+export * from './http/HttpClient';
+export * from './hooks/useRemoteData';
+export * from './hooks/useDebouncedValue';
+export * from './mapping';
+export * from './RemoteComboBox';
+export * from './RemoteAutoComplete';
+export * from './RemoteDataGrid';
+export * from './RemoteSelect';
+export * from './RemoteMultiSelect';

package/dist/remote/mapping.d.ts

@@ -0,0 +1,8 @@
+import { SelectOption } from '../base';
+/**
+ * Handles the two common response envelopes (bare array, `{ items: [...] }`)
+ * explicitly (doc section 11). Anything else must be handled via an
+ * explicit `mapResponse` — no guessing beyond these two conventions.
+ */
+export declare function defaultArrayNormalization(response: unknown): unknown[];
+export declare function toSelectOption<TValue extends string | number>(raw: unknown, valueMember: string, displayMember: string): SelectOption<TValue>;

package/dist/smart/SmartAction.d.ts

@@ -0,0 +1,14 @@
+import { SmartRuntimeContext } from './runtime';
+import { SmartActionMetadata } from './types';
+export interface SmartActionProps {
+    metadata: SmartActionMetadata;
+    ctx: Pick<SmartRuntimeContext, "actions" | "translate">;
+}
+/**
+ * Composes Base Button, not a second button implementation (doc §16/§20) —
+ * the only component-shaped thing action metadata currently resolves to.
+ * Unlike field metadata, an action's `component: "Button"` never needs a
+ * registry lookup: there is exactly one action UI shape, so there is
+ * nothing to resolve between.
+ */
+export declare function SmartAction({ metadata, ctx }: SmartActionProps): import("react").JSX.Element | null;

package/dist/smart/SmartActions.d.ts

@@ -0,0 +1,14 @@
+import { SmartRuntimeContext } from './runtime';
+import { SmartFormMetadata } from './types';
+export interface SmartActionsProps {
+    metadata: SmartFormMetadata;
+    ctx: Pick<SmartRuntimeContext, "actions" | "translate">;
+}
+/**
+ * A thin iteration helper over SmartAction — the action-side counterpart
+ * of SmartForm (doc §09/§15). Maps `metadata.actions` to SmartActions and
+ * nothing else: no layout, no spacing, no handler logic of its own. The
+ * consuming screen wraps this in whatever layout (Stack, a form footer,
+ * a toolbar) it needs.
+ */
+export declare function SmartActions({ metadata, ctx }: SmartActionsProps): import("react").JSX.Element | null;

package/dist/smart/SmartField.d.ts

@@ -0,0 +1,18 @@
+import { ReactElement } from 'react';
+import { SmartRuntimeContext } from './runtime';
+import { SmartFieldMetadata } from './types';
+export interface SmartFieldProps {
+    metadata: SmartFieldMetadata;
+    ctx: SmartRuntimeContext;
+}
+/**
+ * Given one field's metadata, resolves it into whatever Base/Remote
+ * component its `component` discriminant maps to (doc §09/§14) — it owns
+ * no UI of its own, only delegates to `ctx.registry`.
+ *
+ * Also wires the mechanical dependency tracking every metadata-driven
+ * field needs (doc §06): a consuming screen no longer calls
+ * useSmartDependencies by hand per field, SmartField does it here and
+ * reports which field needed the refresh, not just which value changed.
+ */
+export declare function SmartField({ metadata, ctx }: SmartFieldProps): ReactElement | null;

package/dist/smart/SmartForm.d.ts

@@ -0,0 +1,19 @@
+import { SmartRuntimeContext } from './runtime';
+import { SmartFormMetadata } from './types';
+export interface SmartFormProps {
+    metadata: SmartFormMetadata;
+    ctx: SmartRuntimeContext;
+}
+/**
+ * A thin iteration helper over SmartField (doc §09/§15/§18 decision 4) —
+ * it owns no field values, evaluates no business rule, and decides no
+ * layout. Its only two responsibilities: fail the whole form closed on an
+ * unsupported schema version instead of rendering a partially-understood
+ * form (doc §12, reusing Alert rather than a bespoke error UI), and map
+ * each field's metadata to a SmartField.
+ *
+ * A SmartField used standalone (outside SmartForm) is responsible for its
+ * own schemaVersion check — this component is the only place that check
+ * happens automatically.
+ */
+export declare function SmartForm({ metadata, ctx }: SmartFormProps): import("react").JSX.Element;

package/dist/smart/actionRegistry.d.ts

@@ -0,0 +1,11 @@
+export type SmartActionHandler = () => void;
+export interface SmartActionRegistry {
+    register(id: string, handler: SmartActionHandler): void;
+    resolve(id: string): SmartActionHandler | undefined;
+}
+/**
+ * Metadata carries an action id, never a function (doc §08/§11 — no
+ * executable code from the server, ever). The application registers the
+ * real handler once; Smart only looks it up by id.
+ */
+export declare function createSmartActionRegistry(): SmartActionRegistry;

package/dist/smart/componentRegistry.d.ts

@@ -0,0 +1,24 @@
+import { ReactElement } from 'react';
+import { SmartFieldMetadata } from './types';
+import { SmartRuntimeContext } from './runtime';
+export type SmartResolver<M extends SmartFieldMetadata = SmartFieldMetadata> = (metadata: M, ctx: SmartRuntimeContext) => ReactElement | null;
+export interface SmartComponentRegistry {
+    register<M extends SmartFieldMetadata>(component: M["component"], resolver: SmartResolver<M>): void;
+    resolve(metadata: SmartFieldMetadata, ctx: SmartRuntimeContext): ReactElement | null;
+    has(component: string): boolean;
+}
+/**
+ * Keyed by the `component` discriminant — not a switch, not a plugin
+ * framework (doc §04). Type safety lives at the register()/resolve()
+ * generic boundary; internal storage type-erases to `SmartResolver`, the
+ * same escape hatch any typed registry needs, isolated to this one
+ * function. No component type is privileged: Phase 2's built-in Input/
+ * ComboBox/DatePicker/DataGrid resolvers will register through this exact
+ * same call an application uses for a custom component.
+ *
+ * An unresolved `component` value never falls back to an unrelated
+ * component (doc §12) — resolve() returns null and warns once per unknown
+ * component name, so a field silently disappears from the form instead of
+ * rendering the wrong thing.
+ */
+export declare function createSmartComponentRegistry(): SmartComponentRegistry;

package/dist/smart/dataSourceRegistry.d.ts

@@ -0,0 +1,17 @@
+import { HttpClient } from '../remote';
+export interface SmartDataSourceDefinition {
+    url: string;
+    /** Defaults to Remote's own defaultHttpClient when omitted, same as RemoteComboBox etc. already do. */
+    client?: HttpClient;
+}
+export interface SmartDataSourceRegistry {
+    register(id: string, definition: SmartDataSourceDefinition): void;
+    resolve(id: string): SmartDataSourceDefinition | undefined;
+}
+/**
+ * Backs the id-based indirection decided in doc §09/§18 (decision 2):
+ * metadata never carries a raw URL, only an id an application registers
+ * once. The application owns environment/hostname/auth wiring in one
+ * place — Smart never needs to know it exists.
+ */
+export declare function createSmartDataSourceRegistry(initial?: Record<string, SmartDataSourceDefinition>): SmartDataSourceRegistry;

package/dist/smart/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Smart layer — Phases 1-5 complete (approved architecture, see the
+ * "Smart Components" design doc):
+ *   Phase 1 — metadata types, the three registries, the headless
+ *             useSmartField/useSmartDependencies engine.
+ *   Phase 2 — built-in Input/ComboBox/DatePicker resolvers + SmartField.
+ *   Phase 3 — SmartForm, a thin iteration helper over SmartField.
+ *   Phase 4 — built-in DataGrid resolver + declarative column metadata.
+ *   Phase 5 — useSmartAction/SmartAction/SmartActions (the action-side
+ *             counterpart of useSmartField/SmartField/SmartForm), and
+ *             localized boolean-column formatting in the DataGrid
+ *             resolver.
+ */
+export * from './types';
+export * from './componentRegistry';
+export * from './dataSourceRegistry';
+export * from './actionRegistry';
+export * from './runtime';
+export * from './useSmartField';
+export * from './useSmartDependencies';
+export * from './useSmartAction';
+export * from './resolvers';
+export * from './SmartField';
+export * from './SmartForm';
+export * from './SmartAction';
+export * from './SmartActions';

package/dist/smart/resolvers/comboBoxResolver.d.ts

@@ -0,0 +1,10 @@
+import { SmartResolver } from '../componentRegistry';
+import { ComboBoxMetadata } from '../types';
+/**
+ * Composes RemoteComboBox, not ComboBox directly (doc §04 — Base vs. Remote
+ * is inferred from the metadata shape: ComboBoxMetadata always carries a
+ * `dataSource`, so this field is always remote-backed). RemoteComboBox in
+ * turn composes Base ComboBox, so no selection/keyboard/popup behavior is
+ * duplicated anywhere in this chain.
+ */
+export declare const comboBoxResolver: SmartResolver<ComboBoxMetadata>;

package/dist/smart/resolvers/dataGridResolver.d.ts

@@ -0,0 +1,11 @@
+import { SmartResolver } from '../componentRegistry';
+import { DataGridMetadata } from '../types';
+/**
+ * Composes RemoteDataGrid, not Base DataGrid directly (doc §04 — inferred
+ * from `dataSource` the same way ComboBoxMetadata is). Column metadata is
+ * translated into a real `DataGridColumn<TRow>[]` and handed straight to
+ * the existing grid — no second grid engine, no filtering/grouping DSL
+ * (doc §10, matching the original library's own DataGrid scope
+ * restraint).
+ */
+export declare const dataGridResolver: SmartResolver<DataGridMetadata>;

package/dist/smart/resolvers/datePickerResolver.d.ts

@@ -0,0 +1,3 @@
+import { SmartResolver } from '../componentRegistry';
+import { DatePickerMetadata } from '../types';
+export declare const datePickerResolver: SmartResolver<DatePickerMetadata>;

package/dist/smart/resolvers/index.d.ts

@@ -0,0 +1,13 @@
+import { SmartComponentRegistry } from '../componentRegistry';
+import { comboBoxResolver } from './comboBoxResolver';
+import { dataGridResolver } from './dataGridResolver';
+import { datePickerResolver } from './datePickerResolver';
+import { inputResolver } from './inputResolver';
+export { comboBoxResolver, dataGridResolver, datePickerResolver, inputResolver };
+/**
+ * Registers Input/ComboBox/DatePicker/DataGrid through the exact same
+ * `register()` call an application uses for a custom component (doc §04 —
+ * no privileged core; a custom "PatientSelector" resolver is registered
+ * the same way).
+ */
+export declare function registerBuiltInResolvers(registry: SmartComponentRegistry): void;

package/dist/smart/resolvers/inputResolver.d.ts

@@ -0,0 +1,8 @@
+import { SmartResolver } from '../componentRegistry';
+import { InputMetadata } from '../types';
+/**
+ * Composes Base Input (doc §03/§20 — reuse, not a second text-field
+ * implementation). The only thing this file owns is translating resolved
+ * metadata into Input's existing prop contract.
+ */
+export declare const inputResolver: SmartResolver<InputMetadata>;

package/dist/smart/runtime.d.ts

@@ -0,0 +1,26 @@
+import { SmartActionRegistry } from './actionRegistry';
+import { SmartComponentRegistry } from './componentRegistry';
+import { SmartDataSourceRegistry } from './dataSourceRegistry';
+/**
+ * What a resolver/SmartField needs to turn one piece of metadata into
+ * component props. Deliberately owns no canonical field values of its own
+ * (doc §05/§18 decision 3) — `values` is always a read-only snapshot the
+ * caller supplies, the same controlled shape any Base field already uses
+ * via `value`/`onChange`.
+ */
+export interface SmartRuntimeContext {
+    values: Record<string, unknown>;
+    onFieldChange: (name: string, value: unknown) => void;
+    registry: SmartComponentRegistry;
+    dataSources: SmartDataSourceRegistry;
+    actions: SmartActionRegistry;
+    /** Absent = fall back to metadata's raw `label`/`helpText`/etc. strings (doc §07). */
+    translate?: (key: string) => string;
+    /**
+     * Mechanical signal only — "`fieldName`'s metadata needs refreshing
+     * because `changedField` changed." Never evaluates why; SmartField wires
+     * this to useSmartDependencies automatically for every field, so a
+     * consuming screen no longer calls the hook by hand.
+     */
+    onMetadataRefreshNeeded?: (fieldName: string, changedField: string) => void;
+}

package/dist/smart/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Metadata contracts for the Smart layer (architecture proposal, approved —
+ * see the "Smart Components" design doc). A discriminated union, not one
+ * universal object — the same split Base already uses between
+ * FieldIdentity/FieldState/FieldPresentation, one layer up. Components
+ * compose only the mixins that apply to them.
+ *
+ * This module is pure data shape. It renders nothing and calls nothing —
+ * resolvers (src/smart/resolvers) are the only files that turn it into UI.
+ */
+export interface SmartFieldIdentity {
+    /** Binding key — looked up against a runtime `values` record, never owned by Smart itself. */
+    name: string;
+    /**
+     * Field names whose *value* this field's configuration depends on.
+     * Mechanical only: it tells Smart when to ask the backend for fresh
+     * metadata, never what the backend's answer should be (doc §06 — business
+     * rules stay server-owned).
+     */
+    dependsOn?: string[];
+}
+export interface SmartFieldState {
+    visible?: boolean;
+    readOnly?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+}
+export interface SmartPresentation {
+    label?: string;
+    /** Semantic key, resolved via a caller-supplied `translate`. Wins over `label` when both are present (doc §07). */
+    labelKey?: string;
+    placeholder?: string;
+    helpText?: string;
+}
+export interface SmartValidation {
+    validationMessage?: string;
+    /** Semantic key, resolved via a caller-supplied `translate`. Wins over `validationMessage` when both are present. */
+    validationMessageKey?: string;
+}
+/**
+ * A data-source request parameter is either a literal or a reference to
+ * another field's current value — never a magic string like "$CountryId"
+ * (doc §06/§09).
+ */
+export type SmartParamValue = {
+    kind: "static";
+    value: unknown;
+} | {
+    kind: "field";
+    field: string;
+};
+export interface SmartDataSourceRef {
+    /** Id registered in a SmartDataSourceRegistry — never a raw URL (doc §09/§11/§18 decision 2). */
+    id: string;
+    params?: Record<string, SmartParamValue>;
+}
+export interface InputMetadata extends SmartFieldIdentity, SmartFieldState, SmartPresentation, SmartValidation {
+    component: "Input";
+    maxLength?: number;
+}
+export interface ComboBoxMetadata extends SmartFieldIdentity, SmartFieldState, SmartPresentation, SmartValidation {
+    component: "ComboBox";
+    valueMember: string;
+    displayMember: string;
+    dataSource: SmartDataSourceRef;
+}
+export interface DatePickerMetadata extends SmartFieldIdentity, SmartFieldState, SmartPresentation, SmartValidation {
+    component: "DatePicker";
+    minDate?: string;
+    maxDate?: string;
+}
+export interface SmartDataGridColumn {
+    key: string;
+    header?: string;
+    headerKey?: string;
+    sortable?: boolean;
+    visible?: boolean;
+    format?: "text" | "date" | "currency" | "boolean";
+}
+export interface DataGridMetadata extends SmartFieldIdentity, SmartFieldState, SmartPresentation, SmartValidation {
+    component: "DataGrid";
+    columns: SmartDataGridColumn[];
+    dataSource: SmartDataSourceRef;
+    /** Row field each row's unique identity is read from — DataGrid always needs a stable key. */
+    rowKey: string;
+    /**
+     * Top-level key on the raw response holding a total row count (e.g.
+     * "total" for a `{ items, total }` envelope) — a declarative field-name
+     * reference, the same pattern as `valueMember`/`displayMember` on
+     * ComboBoxMetadata, never a function (doc §07/§24). Omit to fall back to
+     * RemoteDataGrid's has-more heuristic.
+     */
+    totalCountField?: string;
+}
+/**
+ * Add a new component type by adding a member here, not by widening an
+ * existing one (doc §03 — the trade for type safety is that a new component
+ * type needs a client-side union member before the backend can use it).
+ */
+export type SmartFieldMetadata = InputMetadata | ComboBoxMetadata | DatePickerMetadata | DataGridMetadata;
+export interface SmartActionMetadata {
+    id: string;
+    component: "Button";
+    visible?: boolean;
+    enabled?: boolean;
+    label?: string;
+    labelKey?: string;
+}
+export interface SmartFormMetadata {
+    /** Mandatory. An unsupported version fails the whole form closed (doc §12) — never a partial render. */
+    schemaVersion: string;
+    fields: SmartFieldMetadata[];
+    actions?: SmartActionMetadata[];
+}

package/dist/smart/useSmartAction.d.ts

@@ -0,0 +1,36 @@
+import { SmartActionRegistry, SmartActionHandler } from './actionRegistry';
+import { SmartActionMetadata, SmartFormMetadata } from './types';
+export interface UseSmartActionOptions {
+    actions: SmartActionRegistry;
+    /** Absent = fall back to metadata's raw `label` string (doc §07). */
+    translate?: (key: string) => string;
+}
+export interface ResolvedSmartAction {
+    metadata: SmartActionMetadata;
+    visible: boolean;
+    /**
+     * `metadata.enabled` ANDed with "a handler actually exists" — metadata
+     * saying `enabled: true` cannot make an action clickable if the
+     * application never registered a handler for its id (doc §12 fail-safe:
+     * an unregistered action renders disabled, never a no-op that looks
+     * clickable).
+     */
+    enabled: boolean;
+    label?: string;
+    handler?: SmartActionHandler;
+}
+/**
+ * Resolves one already-known action's metadata. Pure function, mirrors
+ * `resolveSmartFieldMetadata` — action metadata carries an id, never a
+ * function; the real handler comes from the application-owned
+ * `SmartActionRegistry` (doc §08/§16), looked up here by that id.
+ */
+export declare function resolveSmartActionMetadata(metadata: SmartActionMetadata, options: UseSmartActionOptions): ResolvedSmartAction;
+/**
+ * Looks an action up by id in `formMetadata.actions` and resolves it via
+ * `resolveSmartActionMetadata` — the action-side counterpart of
+ * `useSmartField`. Returns `undefined` when no action with that id is
+ * declared, the same "not present = left alone" convention `useSmartField`
+ * uses for fields.
+ */
+export declare function useSmartAction(id: string, formMetadata: SmartFormMetadata | undefined, options: UseSmartActionOptions): ResolvedSmartAction | undefined;

package/dist/smart/useSmartDependencies.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mechanical dependency tracking only (doc §06/§10): watches the fields a
+ * piece of metadata declared via `dependsOn` and calls
+ * `onMetadataRefreshNeeded` once per field whose value actually changed
+ * since the last render. It never evaluates *why* a change matters — that
+ * stays server-owned; this hook only decides *when to ask again*.
+ *
+ * Uses the same "stable value-based identity" strategy as useRemoteData's
+ * `paramsKey` (serialize, compare by value, not by object/array reference)
+ * to avoid the exact infinite-loop failure mode the original architecture
+ * doc warns against for Remote's own params.
+ */
+export declare function useSmartDependencies(dependsOn: string[] | undefined, values: Record<string, unknown>, onMetadataRefreshNeeded?: (changedField: string) => void): void;

package/dist/smart/useSmartField.d.ts

@@ -0,0 +1,47 @@
+import { SmartFieldMetadata, SmartFormMetadata } from './types';
+export interface UseSmartFieldOptions {
+    values: Record<string, unknown>;
+    /** Absent = fall back to metadata's raw `label`/`helpText`/etc. strings. */
+    translate?: (key: string) => string;
+}
+export interface ResolvedSmartField<M extends SmartFieldMetadata = SmartFieldMetadata> {
+    metadata: M;
+    visible: boolean;
+    readOnly: boolean;
+    disabled: boolean;
+    required: boolean;
+    label?: string;
+    placeholder?: string;
+    helpText?: string;
+    validationMessage?: string;
+    /**
+     * Only present for metadata carrying a `dataSource` (ComboBox/DataGrid).
+     * Resolved from `dataSource.params` + the current `values` snapshot —
+     * ready to pass straight through as a Remote component's `params` prop
+     * (doc §06). Field-name lookups that miss simply resolve to `undefined`,
+     * same as reading a missing key off any plain object.
+     */
+    params?: Record<string, unknown>;
+}
+/**
+ * Resolves one already-known metadata object. Pure function of its
+ * arguments — no React state, no effect, no fetch. Exported separately from
+ * `useSmartField` so a component-registry resolver that already holds a
+ * specific field's metadata (as `SmartResolver` hands it) can reuse this
+ * exact translate/params logic instead of re-deriving it (doc §04's
+ * resolvers and `useSmartField`'s by-name lookup are two entry points onto
+ * the same resolution, not two implementations).
+ */
+export declare function resolveSmartFieldMetadata<M extends SmartFieldMetadata = SmartFieldMetadata>(metadata: M, options: UseSmartFieldOptions): ResolvedSmartField<M>;
+/**
+ * The headless engine every Smart component composes (doc §05/§18 —
+ * Smart Runtime owns no canonical state). Looks a field up by name in
+ * `formMetadata` and resolves it via `resolveSmartFieldMetadata`. Anything
+ * not present in the metadata map is left alone: a field with no matching
+ * metadata entry returns `undefined`, meaning "not driven by metadata," not
+ * "hidden."
+ *
+ * A future SmartField component will call this directly, the same way
+ * RemoteComboBox composes useRemoteData instead of writing its own effect.
+ */
+export declare function useSmartField<M extends SmartFieldMetadata = SmartFieldMetadata>(name: string, formMetadata: SmartFormMetadata | undefined, options: UseSmartFieldOptions): ResolvedSmartField<M> | undefined;