@allhailai/formfoundry-core 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,1112 @@
+import { ZodTypeAny } from 'zod';
+import * as React from 'react';
+import React__default from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type FormFoundryEventName = 'created' | 'destroying' | 'settled' | 'input' | 'commit' | 'reset' | 'message-added' | 'message-removed' | string;
+type FormFoundryEventListener = (payload: unknown) => void;
+interface FormFoundryEventEmitter {
+    /** Register a listener for an event. Returns an unregister function. */
+    on: (event: FormFoundryEventName, listener: FormFoundryEventListener) => () => void;
+    /** Register a one-time listener. Automatically removed after first call. */
+    once: (event: FormFoundryEventName, listener: FormFoundryEventListener) => () => void;
+    /** Emit an event with a payload. */
+    emit: (event: FormFoundryEventName, payload?: unknown) => void;
+    /** Remove all listeners for an event, or all events if no name given. */
+    off: (event?: FormFoundryEventName) => void;
+}
+/** Create a new event emitter for a node. */
+declare function createEventEmitter(): FormFoundryEventEmitter;
+
+/**
+ * A locale message can be a static string or a function for dynamic messages.
+ * Strings support `{label}`, `{name}`, and `{args.N}` interpolation tokens.
+ *
+ * Examples:
+ * - `"{label} is required."`
+ * - `(ctx) => \`\${ctx.label} must be at least \${ctx.args[0]} characters.\``
+ */
+type LocaleMessage = string | ((ctx: MessageContext) => string);
+/**
+ * Context passed to dynamic message functions and used for interpolation.
+ */
+interface MessageContext {
+    /** Human-readable field label (falls back to name if not set) */
+    label: string;
+    /** Field name (the programmatic key) */
+    name: string;
+    /** Rule arguments (e.g., ['8'] for min:8) */
+    args: unknown[];
+    /** Form-level values (for cross-field messages) */
+    values: Record<string, unknown>;
+}
+/**
+ * A locale is a complete set of validation messages for a language.
+ */
+interface FormFoundryLocale {
+    /** Locale code (e.g., 'en', 'es', 'fr') */
+    code: string;
+    /** Human-readable name (e.g., 'English', 'Español') */
+    name: string;
+    /** Rule name → message mapping */
+    messages: Record<string, LocaleMessage>;
+}
+/**
+ * Interpolate tokens in a message string.
+ *
+ * Supported tokens:
+ * - `{label}` → field label
+ * - `{name}` → field name
+ * - `{args.0}`, `{args.1}`, etc. → rule arguments by index
+ * - `{0}`, `{1}`, etc. → shorthand for args
+ */
+declare function interpolate(template: string, ctx: MessageContext): string;
+/**
+ * Resolve a locale message for a given rule and context.
+ */
+declare function resolveLocaleMessage(locale: FormFoundryLocale, ruleName: string, ctx: MessageContext): string;
+/** Register a locale. */
+declare function registerLocale(locale: FormFoundryLocale): void;
+/** Set the active locale by code. */
+declare function setActiveLocale(code: string): void;
+/** Get the active locale. Returns `en` fallback if not found. */
+declare function getActiveLocale(): FormFoundryLocale | undefined;
+/** Get a specific locale by code. */
+declare function getLocale(code: string): FormFoundryLocale | undefined;
+/** List all registered locale codes. */
+declare function getRegisteredLocales(): string[];
+
+/**
+ * A middleware function for a hook.
+ * Receives the current payload and a `next` function to call the next middleware.
+ * Must return the (potentially transformed) payload.
+ */
+type FormFoundryMiddleware<T> = (payload: T, next: (payload: T) => T) => T;
+/**
+ * A single hook dispatcher. Maintains a stack of middleware and dispatches payloads through them.
+ */
+interface FormFoundryHookDispatcher<T> {
+    /** Register a middleware function. Returns an unregister function. */
+    use: (middleware: FormFoundryMiddleware<T>) => () => void;
+    /** Dispatch a payload through the middleware chain (synchronous). */
+    dispatch: (payload: T) => T;
+    /**
+     * Dispatch a payload through the middleware chain, awaiting any async
+     * middleware. BUG-34 fix: prevents Promises from being stored as values
+     * when plugins use async transformations.
+     */
+    dispatchAsync: (payload: T) => Promise<T>;
+}
+/**
+ * All lifecycle hooks available on a node.
+ *
+ * - `init`    — Runs when the node is created. Payload: the node itself.
+ * - `input`   — Runs when node.input(value) is called. Payload: the new value.
+ * - `commit`  — Runs when a value is committed (after debounce). Payload: the committed value.
+ * - `prop`    — Runs when a prop changes. Payload: { prop, value }.
+ * - `message` — Runs when a message is added to the store. Payload: the message.
+ * - `submit`  — Runs on form submission. Payload: the form values.
+ */
+interface FormFoundryHooks {
+    init: FormFoundryHookDispatcher<unknown>;
+    input: FormFoundryHookDispatcher<unknown>;
+    commit: FormFoundryHookDispatcher<unknown>;
+    prop: FormFoundryHookDispatcher<{
+        prop: string;
+        value: unknown;
+    }>;
+    message: FormFoundryHookDispatcher<unknown>;
+    submit: FormFoundryHookDispatcher<Record<string, unknown>>;
+}
+/** Create a fresh set of lifecycle hooks for a node. */
+declare function createHooks(): FormFoundryHooks;
+
+/** Message categories for filtering */
+type FormFoundryMessageType = 'validation' | 'state' | 'ui' | 'error';
+/**
+ * A single message in the node's store.
+ * Rich enough to support i18n, submission blocking, and visibility control.
+ */
+interface FormFoundryMessage {
+    /** Unique key identifying this message (e.g., rule name like 'required') */
+    key: string;
+    /** Category for filtering (validation, state, ui, error) */
+    type: FormFoundryMessageType;
+    /** The message content — typically a human-readable string */
+    value: string;
+    /** Whether this message blocks form submission (default: true for validation) */
+    blocking: boolean;
+    /** Whether this message should be shown to end users (default: true) */
+    visible: boolean;
+    /** Optional metadata for i18n, custom plugins, etc. */
+    meta: Record<string, unknown>;
+}
+/**
+ * Create a message with sensible defaults.
+ * Only `key` and `value` are required — everything else has defaults.
+ */
+declare function createMessage(partial: Partial<FormFoundryMessage> & {
+    key: string;
+    value: string;
+}): FormFoundryMessage;
+interface FormFoundryMessageStore {
+    /** All messages in the store */
+    readonly messages: Map<string, FormFoundryMessage>;
+    /** Add or replace a message by key */
+    set: (message: FormFoundryMessage) => void;
+    /** Remove a message by key */
+    remove: (key: string) => void;
+    /** Get a message by key */
+    get: (key: string) => FormFoundryMessage | undefined;
+    /** Check if a message with this key exists */
+    has: (key: string) => boolean;
+    /** Clear all messages, optionally filtered by type */
+    clear: (type?: FormFoundryMessageType) => void;
+    /** Get all messages of a given type */
+    filter: (type: FormFoundryMessageType) => FormFoundryMessage[];
+    /** Get all visible messages (for display) */
+    visible: () => FormFoundryMessage[];
+    /** Check if any blocking messages exist */
+    hasBlocking: () => boolean;
+    /** Get all blocking messages */
+    blocking: () => FormFoundryMessage[];
+    /** Subscribe to store changes */
+    on: (listener: (store: FormFoundryMessageStore) => void) => () => void;
+    /**
+     * Batch multiple store operations into a single notification.
+     * Suppresses intermediate notifications during the batch.
+     */
+    batch: (fn: () => void) => void;
+}
+declare function createMessageStore(): FormFoundryMessageStore;
+
+type LedgerCounterFilter = (message: FormFoundryMessage) => boolean;
+interface LedgerCounter {
+    /** Current count */
+    readonly count: number;
+    /** Name of this counter (for debugging) */
+    readonly name: string;
+}
+interface FormFoundryLedger {
+    /** Create a counter that tracks messages matching a filter. */
+    count: (name: string, filter: LedgerCounterFilter) => LedgerCounter;
+    /** Get all counters. */
+    counters: () => LedgerCounter[];
+    /** Recalculate all counters from the current store. */
+    recalculate: () => void;
+    /** Cleanup all subscriptions. */
+    destroy: () => void;
+}
+/** Create a ledger attached to a message store. */
+declare function createLedger(store: FormFoundryMessageStore): FormFoundryLedger;
+
+/** The three fundamental node types, mirroring FormKit's tree model. */
+type FormFoundryNodeType = 'input' | 'list' | 'group';
+/**
+ * Controls when validation runs for a field.
+ *
+ * - `blur`   — On blur, then reactively after first blur (default)
+ * - `live`   — On every change (debounced)
+ * - `submit` — Only on form submission
+ * - `dirty`  — On change, but only after value differs from default
+ */
+type ValidationBehavior = 'blur' | 'live' | 'submit' | 'dirty';
+/** A validation rule — either a FormKit-style string, array syntax, or Zod schema. */
+type ValidationSpec = string | Array<[string, ...unknown[]]> | ZodTypeAny;
+/**
+ * Plugin function. Receives the node after creation.
+ * May return a cleanup function called on node destruction.
+ */
+type FormFoundryPlugin = (node: FormFoundryNode) => void | (() => void);
+interface FormFoundryNodeConfig {
+    /** Validation spec — string rules, array rules, or Zod schema */
+    validation?: ValidationSpec;
+    /** When validation runs */
+    validationBehavior?: ValidationBehavior;
+    /** Debounce for async / live validation in ms */
+    validationDebounce?: number;
+    /** Default (initial) value */
+    defaultValue?: unknown;
+    /** Plugins applied to this node (and inherited by children) */
+    plugins?: FormFoundryPlugin[];
+    /** i18n message overrides */
+    messages?: Record<string, string | ((args: string[]) => string)>;
+    /** Arbitrary config data that cascades to children */
+    [key: string]: unknown;
+}
+interface FormFoundryNode {
+    /** Unique identifier (stable across renders via React useId when in React context) */
+    id: string;
+    /** Field name — used as the key in parent group's value object */
+    name: string;
+    /** Node type: input (leaf), list (array), or group (object/form) */
+    type: FormFoundryNodeType;
+    parent: FormFoundryNode | null;
+    children: FormFoundryNode[];
+    /** The committed value. For groups: Record<string, unknown>. For lists: unknown[]. */
+    value: unknown;
+    /** Uncommitted value (set via input(), before commit hook runs) */
+    _value: unknown;
+    touched: boolean;
+    dirty: boolean;
+    disabled: boolean;
+    /** True if no blocking messages exist */
+    readonly valid: boolean;
+    /** Convenience: visible validation error strings */
+    readonly errors: string[];
+    /** Message store: validation errors, UI messages, blocking states */
+    store: FormFoundryMessageStore;
+    /** Lifecycle hooks (middleware dispatchers) */
+    hooks: FormFoundryHooks;
+    /** Event emitter (fire-and-forget observation, unlike hooks) */
+    events: FormFoundryEventEmitter;
+    /** Ledger for O(1) message counting across the tree */
+    ledger: FormFoundryLedger;
+    /** Resolved config (node → parent → provider chain) */
+    config: FormFoundryNodeConfig;
+    /** Per-instance props (take precedence over config) */
+    props: Record<string, unknown>;
+    /**
+     * Set a new value asynchronously.
+     * Runs 'input' hook → debounce → 'commit' hook → updates value.
+     */
+    input: (value: unknown) => Promise<void>;
+    /** Add a child node (for group/list nodes) */
+    addChild: (child: FormFoundryNode, index?: number) => void;
+    /** Remove a child node */
+    removeChild: (child: FormFoundryNode) => void;
+    /** Destroy this node (cleanup, unregister from parent) */
+    destroy: () => void;
+    /** Walk the tree depth-first, calling fn for each node */
+    walk: (fn: (node: FormFoundryNode) => void) => void;
+    /** Find a descendant by name path (e.g., 'address.city') */
+    at: (path: string) => FormFoundryNode | undefined;
+    /**
+     * Reset this node (and children) to default values.
+     * Clears touched, dirty, and validation messages.
+     */
+    reset: (value?: unknown) => void;
+    /**
+     * Returns a promise that resolves when all async operations
+     * (validation, debounced inputs) have completed.
+     */
+    settle: () => Promise<void>;
+    /**
+     * Programmatically submit this form node.
+     * Triggers validation → runs submit hook → calls the registered submit handler.
+     * Only meaningful on group nodes that represent forms — no-op on input/list nodes.
+     * Returns a Promise that resolves when submission completes.
+     *
+     * Wired by `<Form>` on mount. Use `getNode(id).submit()` for cross-form coordination.
+     */
+    submit: () => Promise<void>;
+}
+interface FormFoundryGlobalConfig {
+    validationBehavior?: ValidationBehavior;
+    validationDebounce?: number;
+    /** Default classes for anatomy slots */
+    classConfig?: Record<string, string>;
+    /** i18n validation messages (simple override) */
+    messages?: Record<string, string | ((args: string[]) => string)>;
+    /** Active i18n locale for label-aware messages */
+    locale?: FormFoundryLocale;
+}
+
+type RegistryEvent = 'registered' | 'unregistered';
+type RegistryListener = (event: RegistryEvent, id: string, node: FormFoundryNode) => void;
+/**
+ * Subscribe to node registration/unregistration events.
+ * Returns an unsubscribe function.
+ *
+ * Used by `useFormNode` to detect when a form mounts after the hook is called.
+ */
+declare function subscribeToRegistry(fn: RegistryListener): () => void;
+/**
+ * Retrieve any registered node by its ID from anywhere in the application.
+ * This is the FormFoundry equivalent of FormKit's `getNode(id)`.
+ */
+declare function getNode(id: string): FormFoundryNode | undefined;
+/**
+ * Register a node in the global registry.
+ * Called automatically by `createNode` — you typically don't call this directly.
+ */
+declare function registerNode(node: FormFoundryNode): void;
+/**
+ * Remove a node from the global registry.
+ * Called automatically on `node.destroy()` — you typically don't call this directly.
+ */
+declare function unregisterNode(id: string): void;
+/**
+ * Clear the entire global registry.
+ * Useful for test cleanup and SSR scenarios.
+ *
+ * **Note:** This does NOT clear registry listeners. Mounted `useFormNode`
+ * hooks still need their listeners to detect re-registration. If you need
+ * to clear listeners too (e.g. between isolated tests), call
+ * `clearRegistryListeners()` separately after unmounting the React tree.
+ */
+declare function clearGlobalRegistry(): void;
+/**
+ * Clear all registry listeners.
+ * BUG-D1 fix: prevents listener leaks in SSR and test environments where
+ * `clearGlobalRegistry()` is called between renders/tests without first
+ * unmounting the React tree.
+ *
+ * **Call this AFTER unmounting your React tree** (e.g., in `afterEach`).
+ */
+declare function clearRegistryListeners(): void;
+/**
+ * Get a snapshot of all registered node IDs.
+ * Useful for debugging.
+ */
+declare function getRegisteredNodeIds(): string[];
+
+interface CreateNodeOptions {
+    /** Node type: 'input' (default), 'list', or 'group' */
+    type?: FormFoundryNodeType;
+    /** Field name (used as key in parent group) */
+    name?: string;
+    /** Initial value */
+    value?: unknown;
+    /** Optional stable ID (auto-generated if not provided) */
+    id?: string;
+    /** Configuration (cascades to children) */
+    config?: FormFoundryNodeConfig;
+    /** Children nodes (for group/list types) */
+    children?: FormFoundryNode[];
+    /** Parent node */
+    parent?: FormFoundryNode;
+    /** Plugins to apply */
+    plugins?: FormFoundryPlugin[];
+    /** Per-instance props (override config) */
+    props?: Record<string, unknown>;
+}
+/**
+ * Resolve a config key by walking up the node tree.
+ * node.config → parent.config → grandparent.config → ...
+ */
+declare function resolveConfig(node: FormFoundryNode, key: string): unknown;
+declare function createNode(options?: CreateNodeOptions): FormFoundryNode;
+
+declare const defaultMessages: Record<string, string | ((args: string[]) => string)>;
+/**
+ * Resolve a validation message for a given rule.
+ *
+ * Resolution order:
+ * 1. Custom messages (per-field or per-form overrides)
+ * 2. Active i18n locale (if registered)
+ * 3. Default English messages (fallback)
+ *
+ * The `label` and `name` parameters are optional. When provided with
+ * an active locale, messages will use {label} interpolation.
+ */
+declare function resolveMessage(ruleName: string, args: string[], customMessages?: Record<string, string | ((args: string[]) => string)>, label?: string, name?: string): string;
+
+/**
+ * A validation rule function.
+ * Receives the value, parsed arguments, and context.
+ * Returns an error string (or null for valid), may be async.
+ */
+type ValidationRuleFn = (value: unknown, args: unknown[], context: ValidationContext) => string | null | Promise<string | null>;
+/**
+ * Context passed to every validation rule.
+ * Gives access to sibling field values for cross-field validation.
+ */
+interface ValidationContext {
+    /** All form values — for cross-field rules like `confirm` */
+    values: Record<string, unknown>;
+    /** The field's name */
+    name: string;
+    /** The field's label (for error messages) */
+    label?: string;
+}
+/**
+ * Rule hints modify default validation behavior.
+ *
+ * - `debounce` — debounce this rule (async, in ms)
+ * - `empty`    — run this rule even when the value is empty
+ * - `force`    — don't stop on this rule's failure, run remaining rules
+ * - `optional` — this rule produces non-blocking messages
+ */
+interface RuleHints {
+    debounce?: number;
+    empty?: boolean;
+    force?: boolean;
+    optional?: boolean;
+}
+/**
+ * A parsed validation rule — the output of parseRules.
+ */
+interface ParsedRule {
+    /** Rule name (e.g., 'required', 'email', 'min') */
+    name: string;
+    /** Arguments parsed from the rule spec (e.g., ['6'] for 'min:6') */
+    args: unknown[];
+    /** Hint modifiers parsed from the rule spec */
+    hints: RuleHints;
+    /** If provided directly as a function (array syntax with inline fn) */
+    handler?: ValidationRuleFn;
+}
+
+/**
+ * Parse a validation spec into structured rules.
+ *
+ * Accepts:
+ * - `string` — pipe-delimited rules: `"required|email|min:6"`
+ * - `Array<[string, ...unknown[]]>` — array syntax: `[['required'], ['min', 6]]`
+ * - `Array<string | ValidationRuleFn | [string, ...unknown[]]>` — mixed
+ */
+declare function parseRules(spec: string | Array<string | ValidationRuleFn | [string, ...unknown[]]>): ParsedRule[];
+
+/**
+ * Register a custom validation rule globally.
+ *
+ * ```ts
+ * registerRule('unique', async (value, args, ctx) => {
+ *   const exists = await checkUnique(value)
+ *   return exists ? 'This value is already taken' : null
+ * })
+ * ```
+ */
+declare function registerRule(name: string, rule: ValidationRuleFn): void;
+/**
+ * Get a validation rule by name.
+ * Checks custom rules first, then built-in rules.
+ */
+declare function getRule(name: string): ValidationRuleFn | undefined;
+/**
+ * Check if a rule with this name exists.
+ */
+declare function hasRule(name: string): boolean;
+/**
+ * Remove a custom rule registration.
+ */
+declare function unregisterRule(name: string): void;
+
+declare const builtInRules: {
+    required: ValidationRuleFn;
+    email: ValidationRuleFn;
+    url: ValidationRuleFn;
+    min: ValidationRuleFn;
+    max: ValidationRuleFn;
+    minLength: ValidationRuleFn;
+    maxLength: ValidationRuleFn;
+    matches: ValidationRuleFn;
+    confirm: ValidationRuleFn;
+    alpha: ValidationRuleFn;
+    alphanumeric: ValidationRuleFn;
+    date: ValidationRuleFn;
+    between: ValidationRuleFn;
+    number: ValidationRuleFn;
+    accepted: ValidationRuleFn;
+    alpha_spaces: ValidationRuleFn;
+    contains_alpha: ValidationRuleFn;
+    contains_alphanumeric: ValidationRuleFn;
+    contains_alpha_spaces: ValidationRuleFn;
+    contains_lowercase: ValidationRuleFn;
+    contains_uppercase: ValidationRuleFn;
+    contains_numeric: ValidationRuleFn;
+    contains_symbol: ValidationRuleFn;
+    date_after: ValidationRuleFn;
+    date_before: ValidationRuleFn;
+    date_between: ValidationRuleFn;
+    date_format: ValidationRuleFn;
+    ends_with: ValidationRuleFn;
+    is: ValidationRuleFn;
+    length: ValidationRuleFn;
+    lowercase: ValidationRuleFn;
+    not: ValidationRuleFn;
+    require_one: ValidationRuleFn;
+    starts_with: ValidationRuleFn;
+    symbol: ValidationRuleFn;
+    uppercase: ValidationRuleFn;
+};
+
+/**
+ * Validate a value against a Zod schema.
+ * Returns an array of FormFoundryMessages for any validation errors.
+ */
+declare function validateWithZod(schema: ZodTypeAny, value: unknown): FormFoundryMessage[];
+/**
+ * Validate form-level values against a Zod schema.
+ * Returns a map of field name → error messages.
+ */
+declare function validateFormWithZod(schema: ZodTypeAny, values: Record<string, unknown>): Record<string, string[]>;
+
+/**
+ * Run a validation spec against a value and return messages for any failures.
+ *
+ * Respects rule hints:
+ * - Rules are skipped on empty values (unless `+empty` hint or rule is `required`)
+ * - Execution stops on first failure (unless `*force` hint)
+ * - `?optional` marks messages as non-blocking
+ */
+declare function runValidation(spec: string | Array<string | Function | [string, ...unknown[]]>, value: unknown, context: ValidationContext, customMessages?: Record<string, string | ((args: string[]) => string)>): Promise<FormFoundryMessage[]>;
+
+interface FormMetaContextValue {
+    /** Whether the form is currently submitting */
+    isSubmitting: boolean;
+    /** Whether all fields are valid (no blocking messages) */
+    isValid: boolean;
+    /** Aggregated errors by field name */
+    errors: Record<string, string[]>;
+    /** Register a field node */
+    register: (name: string, node: FormFoundryNode) => void;
+    /** Unregister a field node */
+    unregister: (name: string) => void;
+    /** BUG-29 fix: update validate callback without re-registering node in tree */
+    updateValidateCallback?: (name: string, validate: () => Promise<void>) => void;
+    /** Get a registered node by name */
+    getNode: (name: string) => FormFoundryNode | undefined;
+    /** Trigger validation for a specific field or all fields */
+    triggerValidation: (name?: string) => Promise<boolean>;
+    /** Whether error messages should be shown (e.g., after failed submission) */
+    showErrors: boolean;
+    /** Global config */
+    config: FormFoundryGlobalConfig;
+    /** The form's root node */
+    formNode: FormFoundryNode | null;
+    /** Reset the form to default values, clearing dirty/touched/errors state */
+    reset: (values?: Record<string, unknown>) => void;
+    /** Number of times the form has been submitted */
+    submitCount: number;
+    /** Inject external errors (e.g., from server-side validation) */
+    setExternalErrors: (errors: Record<string, string | string[]>) => void;
+    /** Clear all external errors */
+    clearExternalErrors: () => void;
+    /** Whether the form is globally disabled (e.g., during submission) */
+    isDisabled: boolean;
+}
+declare const FormMetaContext: React.Context<FormMetaContextValue>;
+declare function useFormMeta(): FormMetaContextValue;
+
+interface FormValuesContextValue {
+    /** All form values as key-value map */
+    values: Record<string, unknown>;
+    /** Get a single field value by name */
+    getValue: (name: string) => unknown;
+    /** Set a single field value by name */
+    setValue: (name: string, value: unknown) => void;
+}
+declare const FormValuesContext: React.Context<FormValuesContextValue>;
+declare function useFormValues(): FormValuesContextValue;
+
+interface FormContextValue {
+    values: FormValuesContextValue;
+    meta: FormMetaContextValue;
+}
+/**
+ * Access both form values and meta contexts.
+ * Use this when you need both; prefer `useFormValues()` or `useFormMeta()`
+ * individually when possible to minimize re-renders.
+ */
+declare function useFormContext(): FormContextValue;
+
+interface UseFormFoundryFieldOptions {
+    /** Field name — required */
+    name: string;
+    /** Validation spec: string rules, array rules, or Zod schema */
+    validation?: ValidationSpec | string | Array<unknown> | object;
+    /** When validation runs */
+    validationBehavior?: ValidationBehavior;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Per-field plugins */
+    plugins?: FormFoundryPlugin[];
+    /** Whether the field is disabled */
+    disabled?: boolean;
+    /** Label for validation messages */
+    label?: string;
+    /** Input type identifier for print renderer (e.g., 'text', 'checkbox', 'select') */
+    inputType?: string;
+    /** Options for select/radio/checkboxgroup (stored for print renderer) */
+    selectOptions?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    /** Fields this field depends on (for cross-field validation) */
+    dependsOn?: string[];
+}
+interface UseFormFoundryFieldReturn {
+    value: unknown;
+    error: string | null;
+    errors: string[];
+    touched: boolean;
+    dirty: boolean;
+    valid: boolean;
+    onChange: (value: unknown) => void;
+    onBlur: () => void;
+    fieldProps: {
+        value: unknown;
+        onChange: (value: unknown) => void;
+        onBlur: () => void;
+        'aria-invalid'?: boolean;
+        'aria-describedby'?: string;
+        id: string;
+        name: string;
+        disabled?: boolean;
+    };
+    id: string;
+    node: FormFoundryNode;
+}
+declare function useFormFoundryField(options: UseFormFoundryFieldOptions): UseFormFoundryFieldReturn;
+
+/**
+ * React hook that resolves a FormFoundryNode by ID from the global registry.
+ * Re-renders when the node's state changes (commit, reset, validation).
+ * Automatically resolves deferred nodes via registry subscription.
+ *
+ * Equivalent to FormKit's `useFormKitNodeById`.
+ *
+ * @param id - The node ID to resolve, or undefined to skip
+ * @returns The resolved node, or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * const slotNode = useFormNode('slot-form')
+ * if (slotNode?.dirty) { ... }
+ * await slotNode?.submit()
+ * ```
+ */
+declare function useFormNode(id: string | undefined): FormFoundryNode | undefined;
+/**
+ * React hook that resolves multiple FormFoundryNode instances by ID.
+ * Re-renders when any tracked node's state changes.
+ * Automatically resolves deferred nodes via registry subscription.
+ *
+ * @param ids - Array of node IDs to resolve
+ * @returns A Map of ID → node (or undefined if not found)
+ *
+ * @example
+ * ```tsx
+ * const nodes = useFormNodes(['task-form', 'slot-form'])
+ * const isDirty = [...nodes.values()].some(n => n?.dirty)
+ * const canSave = [...nodes.values()].every(n => n?.valid ?? true)
+ *
+ * await Promise.allSettled(
+ *   [...nodes.values()].map(n => n?.submit())
+ * )
+ * ```
+ */
+declare function useFormNodes(ids: string[]): Map<string, FormFoundryNode | undefined>;
+
+/**
+ * Print mode:
+ * - `'blank'` — renders empty fields with lines/boxes for hand-filling
+ * - `'filled'` — renders current form values as static text
+ * - `'current'` — alias for `'filled'`
+ */
+type PrintMode = 'blank' | 'filled' | 'current';
+/**
+ * Options for the `useFormPrint` hook and `PrintOverlay` component.
+ */
+interface PrintOptions {
+    /** Print mode. Default: 'filled' */
+    mode?: PrintMode;
+    /** Title displayed at the top of the printed form */
+    title?: string;
+    /** Subtitle (e.g., date, form reference) */
+    subtitle?: string;
+    /** Footer text at the bottom */
+    footer?: string;
+    /** Extra CSS class name for the print root */
+    className?: string;
+}
+/**
+ * Describes a single field for the print renderer.
+ * Built from form context data at print time.
+ */
+interface PrintFieldDescriptor {
+    /** Field name (key in form values) */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Input type (e.g., 'text', 'checkbox', 'select') */
+    type: string;
+    /** Current value (used in 'filled' mode) */
+    value: unknown;
+    /** Options for select/radio/checkboxgroup fields */
+    options?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+}
+
+/**
+ * A form-level resolver function.
+ * Takes all form values and returns field-level errors.
+ */
+type FormFoundryResolver = (values: Record<string, unknown>) => Promise<{
+    errors: Record<string, string[]>;
+}>;
+/**
+ * Create a resolver from a Zod schema.
+ *
+ * ```ts
+ * const resolver = zodResolver(z.object({
+ *   email: z.string().email(),
+ *   password: z.string().min(8),
+ * }))
+ * ```
+ */
+declare function zodResolver(schema: ZodTypeAny): FormFoundryResolver;
+
+/**
+ * Imperative handle for programmatic form control.
+ * Access via React ref or via `getNode(id).submit()` on the form's node.
+ */
+interface FormFoundryHandle {
+    /** Programmatically trigger validation + submission. */
+    submit: () => Promise<void>;
+    /** Reset the form to default (or provided) values. */
+    reset: (values?: Record<string, unknown>) => void;
+    /** Get a snapshot of current form values. */
+    getValues: () => Record<string, unknown>;
+    /** Check if all fields are currently valid. */
+    isValid: () => boolean;
+    /** Print the form in the specified mode ('blank' | 'filled' | 'current'). */
+    printForm: (options?: PrintOptions) => void;
+}
+interface FormProps {
+    /** Stable form ID — enables `getNode(id).submit()` for cross-form coordination */
+    id?: string;
+    /** React ref for imperative access (convenience wrapper over node API) */
+    ref?: React__default.Ref<FormFoundryHandle>;
+    /** Called on successful submission with all form values */
+    onSubmit: (values: Record<string, unknown>) => void | Promise<void>;
+    /** Called on every submit attempt, even if validation fails */
+    onSubmitRaw?: (values: Record<string, unknown>) => void;
+    /** Initial field values */
+    defaultValues?: Record<string, unknown>;
+    /** Form-level Zod schema validation */
+    schema?: ZodTypeAny;
+    /** Alternative resolver pattern (React Hook Form style) */
+    resolver?: FormFoundryResolver;
+    /** Plugins applied to all fields in this form */
+    plugins?: FormFoundryPlugin[];
+    /** Default validation behavior for all fields */
+    validationBehavior?: ValidationBehavior;
+    /** Show error summary on submit failure */
+    showErrors?: boolean;
+    /** Auto-disable all fields during submission (default: true) */
+    disableOnSubmit?: boolean;
+    /** Render as a different element (default: 'form') */
+    as?: React__default.ElementType;
+    /** Children */
+    children: React__default.ReactNode;
+    /** Optional className */
+    className?: string;
+}
+declare function Form({ id: formId, ref, onSubmit, onSubmitRaw, defaultValues, schema, resolver, plugins, validationBehavior, showErrors: showErrorsProp, disableOnSubmit, as: Component, children, className, }: FormProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Named section keys for the field anatomy.
+ * Each maps to a part of the rendered field structure.
+ *
+ * outer → wrapper → label + prefix + inner(input) + suffix + help + messages(message)
+ */
+type FormFoundrySectionKey = 'outer' | 'wrapper' | 'label' | 'prefix' | 'inner' | 'suffix' | 'input' | 'help' | 'messages' | 'message';
+/**
+ * Every adapter input component receives these props.
+ * Typed with a generic TValue for the field's value type.
+ */
+interface FormFoundryInputProps<TValue = unknown> {
+    name: string;
+    value?: TValue;
+    onChange?: (value: TValue) => void;
+    onBlur?: () => void;
+    error?: string | null;
+    errors?: string[];
+    touched?: boolean;
+    dirty?: boolean;
+    valid?: boolean;
+    disabled?: boolean;
+    id?: string;
+    defaultValue?: TValue;
+    label?: React__default.ReactNode;
+    help?: React__default.ReactNode;
+    placeholder?: string;
+    validation?: string | Array<unknown> | object;
+    validationBehavior?: string;
+    classNames?: Partial<Record<FormFoundrySectionKey, string>>;
+    'data-formfoundry'?: string;
+    'data-touched'?: boolean;
+    'data-invalid'?: boolean;
+    'data-dirty'?: boolean;
+    type?: string;
+    options?: Array<{
+        label: string;
+        value: string | number;
+    }> | Array<string>;
+}
+/**
+ * What an adapter package exports.
+ * Used to register all inputs from an adapter at once.
+ */
+interface FormFoundryAdapter {
+    /** Adapter name (e.g., 'baseui', 'shadcn', 'plain-html') */
+    name: string;
+    /** Create a registry pre-populated with this adapter's inputs */
+    createRegistry: () => InputRegistry;
+}
+
+interface InputRegistry {
+    /** Register a component for a type key */
+    register: (type: string, component: React__default.ComponentType<FormFoundryInputProps>) => void;
+    /** Get a registered component by type key */
+    get: (type: string) => React__default.ComponentType<FormFoundryInputProps> | undefined;
+    /** Check if a type key is registered */
+    has: (type: string) => boolean;
+    /** List all registered type keys */
+    keys: () => string[];
+}
+declare const InputRegistryContext: React__default.Context<InputRegistry | null>;
+declare function useInputRegistry(): InputRegistry;
+/**
+ * Create a new InputRegistry instance.
+ * Pass initial entries as a record of type → component.
+ */
+declare function createRegistry(entries?: Record<string, React__default.ComponentType<FormFoundryInputProps>>): InputRegistry;
+/**
+ * Create the default (empty) registry.
+ * Adapter packages add their inputs via the registry.
+ */
+declare function createDefaultRegistry(): InputRegistry;
+
+interface FormFoundryProviderProps {
+    config?: {
+        validationBehavior?: ValidationBehavior;
+        validationDebounce?: number;
+        classConfig?: Record<string, string>;
+        messages?: Record<string, string | ((args: string[]) => string)>;
+    };
+    /** Active locale for i18n message resolution */
+    locale?: FormFoundryLocale;
+    registry?: InputRegistry;
+    plugins?: FormFoundryPlugin[];
+    children: React__default.ReactNode;
+}
+declare function FormFoundryProvider({ config, locale, registry, plugins, children, }: FormFoundryProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FormFoundrySchemaInput {
+    /** Registry key (e.g., 'text', 'select', 'checkbox') */
+    $formfoundry: string;
+    /** Field name */
+    name: string;
+    /** Conditional rendering — function predicate */
+    if?: (values: Record<string, unknown>) => boolean;
+    /** Forwarded as props to the resolved component */
+    [key: string]: unknown;
+}
+interface FormFoundrySchemaElement {
+    /** HTML element tag (e.g., 'div', 'h1', 'section') */
+    $el: string;
+    /** HTML attributes */
+    attrs?: Record<string, unknown>;
+    /** Children — text content or nested schema nodes */
+    children?: string | FormFoundrySchemaNode[];
+    /** Conditional rendering */
+    if?: (values: Record<string, unknown>) => boolean;
+}
+interface FormFoundrySchemaComponent {
+    /** Component key from the library prop */
+    $cmp: string;
+    /** Component props */
+    props?: Record<string, unknown>;
+    /** Children — text content or nested schema nodes */
+    children?: string | FormFoundrySchemaNode[];
+    /** Conditional rendering */
+    if?: (values: Record<string, unknown>) => boolean;
+}
+/**
+ * If/then/else conditional block.
+ * Renders `then` schema if `if` predicate is true, otherwise renders `else`.
+ */
+interface FormFoundrySchemaConditional {
+    /** Predicate function */
+    if: (values: Record<string, unknown>) => boolean;
+    /** Schema nodes to render when predicate is true */
+    then: FormFoundrySchemaNode[];
+    /** Schema nodes to render when predicate is false (optional) */
+    else?: FormFoundrySchemaNode[];
+}
+/**
+ * Loop construct.
+ * Repeats children for each item in the iterable.
+ *
+ * ```ts
+ * { for: ['item', 'index', items], children: [...] }
+ * ```
+ */
+interface FormFoundrySchemaLoop {
+    /** [itemName, indexName, iterable] — iterable can be an array or a key into data */
+    for: [string, string, unknown[] | string];
+    /** Schema nodes to repeat for each item */
+    children: FormFoundrySchemaNode[];
+}
+type FormFoundrySchemaNode = FormFoundrySchemaInput | FormFoundrySchemaElement | FormFoundrySchemaComponent | FormFoundrySchemaConditional | FormFoundrySchemaLoop;
+interface SchemaRendererProps {
+    /** Array of schema nodes to render */
+    schema: FormFoundrySchemaNode[];
+    /** Component library for $cmp references */
+    library?: Record<string, React__default.ComponentType<Record<string, unknown>>>;
+    /** Reactive data available in schema predicates (merged with form values) */
+    data?: Record<string, unknown>;
+}
+declare function SchemaRenderer({ schema, library, data }: SchemaRendererProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Expression prefix. Strings starting with this are treated as expressions.
+ */
+declare const EXPRESSION_PREFIX = "$: ";
+/**
+ * Check if a value is an expression string (starts with `$: `).
+ */
+declare function isExpression(value: unknown): value is string;
+/**
+ * Check if a value is a simple variable reference (starts with `$` but not `$: `).
+ */
+declare function isVariableRef(value: unknown): value is string;
+/**
+ * Evaluate a `$: ` prefixed expression string against a data context.
+ *
+ * ```ts
+ * evaluateExpression('$: "Hello " + $name', { name: 'World' })
+ * // → 'Hello World'
+ * ```
+ */
+declare function evaluateExpression(expression: string, data: Record<string, unknown>): unknown;
+/**
+ * Resolve a `$variable` reference against a data context.
+ *
+ * ```ts
+ * resolveVariableRef('$user.name', { user: { name: 'Alice' } })
+ * // → 'Alice'
+ * ```
+ */
+declare function resolveVariableRef(ref: string, data: Record<string, unknown>): unknown;
+/**
+ * Resolve any schema value — if it's an expression or variable ref, evaluate it.
+ * Otherwise return it as-is.
+ */
+declare function resolveSchemaValue(value: unknown, data: Record<string, unknown>): unknown;
+
+/**
+ * Apply plugins to a node and collect cleanup functions.
+ */
+declare function applyPlugins(node: FormFoundryNode, plugins: FormFoundryPlugin[]): Array<() => void>;
+/**
+ * Create a plugin that logs all node value changes.
+ * Useful for debugging.
+ */
+declare function createDebugPlugin(prefix?: string): FormFoundryPlugin;
+/**
+ * Create a plugin that auto-trims string values.
+ */
+declare function createAutoTrimPlugin(): FormFoundryPlugin;
+
+declare const en: FormFoundryLocale;
+
+interface FormPrintButtonProps {
+    /** Print options (mode, title, subtitle, footer) */
+    options?: PrintOptions;
+    /** Button label text. Default: 'Print' */
+    children?: React__default.ReactNode;
+    /** Extra className for the button */
+    className?: string;
+    /** Disabled state */
+    disabled?: boolean;
+}
+/**
+ * A button that prints the enclosing `<Form>` when clicked.
+ * Must be rendered inside a `<Form>` component.
+ *
+ * @example
+ * ```tsx
+ * <Form onSubmit={handleSubmit}>
+ *   <TextInput name="name" label="Name" />
+ *   <FormPrintButton options={{ mode: 'blank', title: 'Contact Form' }}>
+ *     🖨️ Print Blank
+ *   </FormPrintButton>
+ * </Form>
+ * ```
+ */
+declare function FormPrintButton({ options, children, className, disabled, }: FormPrintButtonProps): react_jsx_runtime.JSX.Element;
+
+interface FormPrintViewProps {
+    /** Array of field descriptors to render */
+    fields: PrintFieldDescriptor[];
+    /** Print mode — 'blank' for empty fields, 'filled' for current values */
+    mode: PrintMode;
+    /** Optional title shown at the top of the print view */
+    title?: string;
+    /** Optional subtitle (e.g., date, form ID) */
+    subtitle?: string;
+    /** Optional footer text */
+    footer?: string;
+    /** Optional extra className for the root element */
+    className?: string;
+    /** Whether this is a screen preview (adds border/shadow styling) */
+    preview?: boolean;
+}
+declare function FormPrintView({ fields, mode, title, subtitle, footer, className, preview, }: FormPrintViewProps): react_jsx_runtime.JSX.Element;
+
+interface PrintOverlayProps {
+    /** Field descriptors to render */
+    fields: PrintFieldDescriptor[];
+    /** Print mode */
+    mode: PrintMode;
+    /** Title for the print header */
+    title?: string;
+    /** Subtitle for the print header */
+    subtitle?: string;
+    /** Footer text */
+    footer?: string;
+    /** Extra className */
+    className?: string;
+    /** Whether the overlay is active (default: true) */
+    open?: boolean;
+}
+/**
+ * Overlay that renders `FormPrintView` hidden on screen but visible
+ * during `@media print`. No portal needed — uses CSS to control visibility.
+ *
+ * @example
+ * ```tsx
+ * <PrintOverlay
+ *   fields={descriptors}
+ *   mode="filled"
+ *   title="Patient Intake Form"
+ * />
+ * ```
+ */
+declare function PrintOverlay({ fields, mode, title, subtitle, footer, className, open, }: PrintOverlayProps): react_jsx_runtime.JSX.Element | null;
+
+interface UseFormPrintReturn {
+    /** Trigger the browser print dialog with a print-optimized form view */
+    printForm: (overrides?: PrintOptions) => void;
+    /** Get current field descriptors (useful for custom print UIs) */
+    getFieldDescriptors: (mode?: PrintMode) => PrintFieldDescriptor[];
+}
+/**
+ * Hook that provides form printing capabilities.
+ * Must be used inside a `<Form>` component.
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const { printForm } = useFormPrint({ title: 'Contact Form' })
+ *   return (
+ *     <Form onSubmit={handleSubmit}>
+ *       <TextInput name="name" label="Name" />
+ *       <button type="button" onClick={() => printForm({ mode: 'blank' })}>
+ *         Print Blank
+ *       </button>
+ *     </Form>
+ *   )
+ * }
+ * ```
+ */
+declare function useFormPrint(defaultOptions?: PrintOptions): UseFormPrintReturn;
+
+export { type CreateNodeOptions, EXPRESSION_PREFIX, Form, type FormContextValue, type FormFoundryAdapter, type FormFoundryEventEmitter, type FormFoundryEventListener, type FormFoundryEventName, type FormFoundryGlobalConfig, type FormFoundryHandle, type FormFoundryHookDispatcher, type FormFoundryHooks, type FormFoundryInputProps, type FormFoundryLedger, type FormFoundryLocale, type FormFoundryMessage, type FormFoundryMessageStore, type FormFoundryMessageType, type FormFoundryMiddleware, type FormFoundryNode, type FormFoundryNodeConfig, type FormFoundryNodeType, type FormFoundryPlugin, FormFoundryProvider, type FormFoundryProviderProps, type FormFoundryResolver, type FormFoundrySchemaComponent, type FormFoundrySchemaConditional, type FormFoundrySchemaElement, type FormFoundrySchemaInput, type FormFoundrySchemaLoop, type FormFoundrySchemaNode, type FormFoundrySectionKey, FormMetaContext, type FormMetaContextValue, FormPrintButton, type FormPrintButtonProps, FormPrintView, type FormPrintViewProps, type FormProps, FormValuesContext, type FormValuesContextValue, type InputRegistry, InputRegistryContext, type LedgerCounter, type LedgerCounterFilter, type LocaleMessage, type MessageContext, type ParsedRule, type PrintFieldDescriptor, type PrintMode, type PrintOptions, PrintOverlay, type PrintOverlayProps, type RegistryEvent, type RegistryListener, type RuleHints, SchemaRenderer, type SchemaRendererProps, type UseFormFoundryFieldOptions, type UseFormFoundryFieldReturn, type UseFormPrintReturn, type ValidationBehavior, type ValidationContext, type ValidationRuleFn, type ValidationSpec, applyPlugins, builtInRules, clearGlobalRegistry, clearRegistryListeners, createAutoTrimPlugin, createDebugPlugin, createDefaultRegistry, createEventEmitter, createHooks, createLedger, createMessage, createMessageStore, createNode, createRegistry, defaultMessages, en as enLocale, evaluateExpression, getActiveLocale, getLocale, getNode, getRegisteredLocales, getRegisteredNodeIds, getRule, hasRule, interpolate, isExpression, isVariableRef, parseRules, registerLocale, registerNode, registerRule, resolveConfig, resolveLocaleMessage, resolveMessage, resolveSchemaValue, resolveVariableRef, runValidation, setActiveLocale, subscribeToRegistry, unregisterNode, unregisterRule, useFormContext, useFormFoundryField, useFormMeta, useFormNode, useFormNodes, useFormPrint, useFormValues, useInputRegistry, validateFormWithZod, validateWithZod, zodResolver };