@formwright/core 0.1.0 → 0.2.2

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { ReadSignal, WriteSignal, Dispose } from './reactive.js';
-export { batch, computed, effect, isTracking, signal, untrack } from './reactive.js';
+import { ReadSignal, WriteSignal, Dispose } from '@formwright/reactive';
+export { Dispose, ReadSignal, WriteSignal, batch, computed, effect, isTracking, signal, untrack } from '@formwright/reactive';
 import { FieldValue, Condition, ValidationSchema, ProviderRef, FieldOption, Resolvable, FieldSchema, FormSchema } from '@formwright/schema';
-export { Condition, FieldOption, FieldSchema, FieldValue, FormSchema } from '@formwright/schema';
+export { Condition, FieldOption, FieldSchema, FieldType, FieldValue, FormSchema } from '@formwright/schema';
 
 /**
  * Condition engine — evaluates the sandboxed JSONLogic-style {@link Condition}
@@ -86,17 +86,28 @@ declare class FieldState {
     /** Discriminant for the {@link FieldNode} union (leaf vs group/collection). */
     readonly kind: "field";
     readonly id: string;
-    readonly schema: FieldSchema;
+    /** A globally-unique DOM id for the control (collection rows reuse `id`, so this must be unique). */
+    readonly domId: string;
+    /** The field's schema — mutable at runtime via {@link patchSchema}. */
+    schema: FieldSchema;
     readonly value: WriteSignal<FieldValue>;
     readonly error: WriteSignal<string | null>;
     readonly touched: WriteSignal<boolean>;
     readonly visible: ReadSignal<boolean>;
     readonly enabled: ReadSignal<boolean>;
     readonly required: ReadSignal<boolean>;
-    private readonly validator;
-    constructor(schema: FieldSchema, initial: FieldValue, getValue: ValueGetter);
-    /** Run validation, store and return the error (or null). Hidden fields never error. */
-    validate(): string | null;
+    /** Bumps whenever the schema is patched — renderers re-render the field on change. */
+    readonly revision: ReadSignal<number>;
+    private validator;
+    private readonly rev;
+    private readonly stepActive;
+    constructor(schema: FieldSchema, initial: FieldValue, getValue: ValueGetter, stepActive?: ReadSignal<boolean>);
+    /** Merge a partial schema in at runtime (change type, label, options, validation, …). */
+    patchSchema(partial: Partial<FieldSchema>): void;
+    /** Run validation, store and return the error (or null). Hidden / inactive-step fields never error. */
+    validate(options?: {
+        allSteps?: boolean;
+    }): string | null;
     reset(value: FieldValue): void;
 }
 
@@ -112,11 +123,13 @@ declare class FieldState {
  * are skipped by validation.
  */
 
-/** A node in the field tree: a leaf field, a nested object, or a repeatable list. */
-type FieldNode = FieldState | GroupNode | CollectionNode;
+/** A node in the field tree: a leaf field, a nested object, a repeatable list, or a wizard. */
+type FieldNode = FieldState | GroupNode | CollectionNode | StepsNode | StepNode;
 /** Resolves a referenced field name to its current value, walking enclosing scopes. */
 type Scope = ValueGetter;
 type Dict = Record<string, unknown>;
+/** True for fields that render content but contribute nothing to the payload. */
+declare function isPresentational(type: string): boolean;
 /** A nested object field: produces `{ ...visible child values }`. */
 declare class GroupNode {
     readonly kind: "group";
@@ -129,7 +142,7 @@ declare class GroupNode {
     readonly enabled: ReadSignal<boolean>;
     /** The scope a child uses: resolve a name among siblings, else delegate upward. */
     readonly scope: Scope;
-    constructor(schema: FieldSchema, parentScope: Scope, initial: Dict);
+    constructor(schema: FieldSchema, parentScope: Scope, initial: Dict, stepActive?: ReadSignal<boolean>);
     reset(initial: Dict): void;
 }
 /** One row of a {@link CollectionNode}: a group with a stable identity key. */
@@ -160,13 +173,52 @@ declare class CollectionNode {
     removeAt(index: number): void;
     reset(initial: Dict[]): void;
 }
+/** One step of a {@link StepsNode}: a titled section of nested fields. */
+declare class StepNode {
+    readonly kind: "step";
+    readonly id: string;
+    readonly schema: FieldSchema;
+    readonly children: readonly FieldNode[];
+    readonly byName: ReadonlyMap<string, FieldNode>;
+    readonly value: ReadSignal<Dict>;
+    readonly visible: ReadSignal<boolean>;
+    readonly enabled: ReadSignal<boolean>;
+    readonly scope: Scope;
+    /** True when this step is the active step in its parent wizard. */
+    readonly active: ReadSignal<boolean>;
+    constructor(schema: FieldSchema, parentScope: Scope, initial: Dict, active: ReadSignal<boolean>);
+    reset(initial: Dict): void;
+}
+/** A multi-step wizard: shows one {@link StepNode} at a time with next/back navigation. */
+declare class StepsNode {
+    readonly kind: "steps";
+    readonly id: string;
+    readonly schema: FieldSchema;
+    readonly steps: readonly StepNode[];
+    readonly byName: Map<string, StepNode>;
+    readonly value: ReadSignal<Dict>;
+    readonly visible: ReadSignal<boolean>;
+    readonly enabled: ReadSignal<boolean>;
+    readonly currentStep: WriteSignal<number>;
+    readonly scope: Scope;
+    constructor(schema: FieldSchema, parentScope: Scope, initial: Dict);
+    /** Validate every leaf in the step at `index` (defaults to the current step). */
+    validateStep(index?: number): boolean;
+    /** Advance to the next step after optionally validating the current one. Returns false if blocked. */
+    next(): boolean;
+    /** Go back one step (no validation). */
+    prev(): void;
+    /** Jump to a step by index (does not validate). */
+    goTo(index: number): void;
+    reset(initial: Dict): void;
+}
 /** Build the top-level field tree for a form, rooted at `rootScope`. */
 declare function buildTree(schemas: readonly FieldSchema[], initial: Dict): {
     nodes: FieldNode[];
     byName: Map<string, FieldNode>;
     scope: Scope;
 };
-/** Visit every leaf {@link FieldState} in a node list (descends groups/collections). */
+/** Visit every leaf {@link FieldState} in a node list (descends groups/collections/steps). */
 declare function eachLeaf(nodes: readonly FieldNode[], visit: (leaf: FieldState) => void): void;
 
 /**
@@ -185,6 +237,15 @@ declare function eachLeaf(nodes: readonly FieldNode[], visit: (leaf: FieldState)
 /** Form values — nested for `group` (object) and `collection` (array) fields. */
 type FormValues = Record<string, unknown>;
 type FormErrors = Record<string, string | null>;
+/** The outcome of {@link Form.submit} — resolved for both success and failure. */
+type SubmitResult = {
+    readonly ok: true;
+    readonly data: unknown;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+    readonly errors?: FormErrors;
+};
 /** A transform applied to values before submission. */
 type Transform = (values: FormValues, form: Form) => unknown;
 /** Handlers referenced by name from the schema's `submit` block. */
@@ -196,12 +257,18 @@ interface FormOptions {
     readonly handlers?: Record<string, SuccessHandler | ErrorHandler>;
     /** Override the network send (defaults to `fetch` against `submit.endpoint`). */
     readonly send?: (payload: unknown, form: Form) => Promise<unknown>;
+    /**
+     * Persist entered values under this `localStorage` key and restore them on the
+     * next load — so a refresh before submitting keeps the form filled. Cleared on
+     * a successful submit.
+     */
+    readonly persistKey?: string;
 }
 /** Renders a {@link Form} into a host node; returns a disposer. Provided by a renderer package. */
 interface FormRenderer {
     mount(form: Form, host: Element): Dispose;
 }
-type EventName = "submit" | "success" | "error" | "change";
+type EventName = "submit" | "success" | "error" | "change" | "action";
 type Listener = (payload: unknown) => void;
 /** Register the renderer used by {@link Form.mount} when none is passed explicitly. */
 declare function setDefaultRenderer(renderer: FormRenderer): void;
@@ -223,6 +290,7 @@ declare class Form {
     private readonly rootByName;
     private readonly listeners;
     private disposeRenderer;
+    private disposePersist;
     constructor(schema: FormSchema | unknown, initialValues?: FormValues, options?: FormOptions);
     /** All leaf fields keyed by dotted path (e.g. `items.name`, `contacts.0.email`). */
     get fields(): ReadonlyMap<string, FieldState>;
@@ -233,16 +301,36 @@ declare class Form {
     /** Apply a value to a specific leaf node (used by the renderer). */
     setFieldValue(field: FieldState, value: FieldValue): void;
     setError(id: string, error: string | null): void;
+    /** Patch one field's schema at runtime (change type, label, options, validation, …). */
+    setFieldSchema(path: string, partial: Partial<FieldSchema>): void;
+    /** Patch many fields' schemas at once: `form.patch({ state: { type: "text" }, … })`. */
+    patch(updates: Record<string, Partial<FieldSchema>>): void;
     setErrors(errors: FormErrors): void;
     get isSubmitting(): ReadSignal<boolean>;
     /** Validate every (visible) leaf field; returns true when the whole form is valid. */
-    validate(): boolean;
-    /** Run the submission pipeline: validate → transform → send → onSuccess/onError. */
-    submit(): Promise<unknown>;
+    validate(options?: {
+        allSteps?: boolean;
+    }): boolean;
+    /** Find the first `steps` container in the field tree (if any). */
+    findSteps(): StepsNode | undefined;
+    /**
+     * Run the submission pipeline: validate → transform → send → onSuccess/onError.
+     * Pass an inline `transform` to shape the final payload, e.g.
+     * `form.submit((values) => ({ ...values, source: "web" }))`.
+     *
+     * Always **resolves** with a {@link SubmitResult} — never throws — so you can
+     * handle both outcomes from the API in one place:
+     * `const res = await form.submit(); res.ok ? res.data : res.error`.
+     */
+    submit(transform?: (values: FormValues, form: Form) => unknown): Promise<SubmitResult>;
     reset(values?: FormValues): void;
+    /** Trigger a named form action: runs its handler (from options) and emits "action". */
+    action(name: string): void;
     /** Mount into a host element using the given renderer (or the registered default). */
     mount(host: Element, renderer?: FormRenderer | null): Dispose;
     destroy(): void;
+    /** Remove the cached draft from `localStorage` (called on a successful submit). */
+    private clearPersisted;
     on(event: EventName, listener: Listener): Dispose;
     private emit;
     private collectErrors;
@@ -256,4 +344,4 @@ declare class FormValidationError extends Error {
     constructor(errors: FormErrors);
 }
 
-export { type CollectionItem, CollectionNode, Dispose, type ErrorHandler, type FieldNode, FieldState, type FieldValidator, Form, type FormErrors, type FormOptions, type FormRenderer, FormValidationError, type FormValues, GroupNode, type I18nProvider, type Providers, type QueryProvider, type QueryResult, ReadSignal, type Scope, type SuccessHandler, type ThemeProvider, type Transform, type ValueGetter, WriteSignal, buildTree, compileValidator, defaultValueFor, eachLeaf, evaluateCondition, isProviderRef, referencedFields, resolve, resolveQuery, setDefaultRenderer };
+export { type CollectionItem, CollectionNode, type ErrorHandler, type FieldNode, FieldState, type FieldValidator, Form, type FormErrors, type FormOptions, type FormRenderer, FormValidationError, type FormValues, GroupNode, type I18nProvider, type Providers, type QueryProvider, type QueryResult, type Scope, StepNode, StepsNode, type SubmitResult, type SuccessHandler, type ThemeProvider, type Transform, type ValueGetter, buildTree, compileValidator, defaultValueFor, eachLeaf, evaluateCondition, isPresentational, isProviderRef, referencedFields, resolve, resolveQuery, setDefaultRenderer };