@formwright/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+import { ReadSignal, WriteSignal, Dispose } from './reactive.js';
+export { batch, computed, effect, isTracking, signal, untrack } from './reactive.js';
+import { FieldValue, Condition, ValidationSchema, ProviderRef, FieldOption, Resolvable, FieldSchema, FormSchema } from '@formwright/schema';
+export { Condition, FieldOption, FieldSchema, FieldValue, FormSchema } from '@formwright/schema';
+
+/**
+ * Condition engine — evaluates the sandboxed JSONLogic-style {@link Condition}
+ * algebra from a schema against the current form values.
+ *
+ * It is pure and synchronous: `getValue` reads a field. When the evaluator is
+ * called inside an {@link effect}/{@link computed} and `getValue` reads field
+ * signals, the result automatically tracks *only* the fields the condition
+ * references — so a `visibleWhen` re-evaluates exactly when its inputs change.
+ * Conditions are data, never `eval`.
+ */
+
+type ValueGetter = (fieldId: string) => FieldValue;
+/** Evaluate a condition to a boolean. `undefined` conditions default to `true`. */
+declare function evaluateCondition(cond: Condition | undefined, get: ValueGetter, fallback?: boolean): boolean;
+/** Collect the field ids referenced by a condition (for documentation / codegen). */
+declare function referencedFields(cond: Condition | undefined): string[];
+
+/**
+ * Field-level validation — turns a declarative {@link ValidationSchema} into a
+ * pure validator `(value) => error | null`.
+ *
+ * This covers the zero-config built-ins. For richer rules, a field can instead
+ * carry any Standard-Schema-compatible validator (Zod/Valibot/ArkType); the Form
+ * runs whichever is present. Kept dependency-free here so `@formwright/core`
+ * ships with no required runtime deps.
+ */
+
+type FieldValidator = (value: FieldValue) => string | null;
+/** Compile a declarative validation descriptor into a validator function. */
+declare function compileValidator(schema: ValidationSchema): FieldValidator;
+
+/**
+ * Provider system — the host app injects integrations (i18n, data fetching,
+ * theming) that the schema references via sigils (`{ $t }`, `{ $query }`,
+ * `{ $theme }`). Providers expose plain functions (optionally signal-backed),
+ * so when a locale changes or a query resolves, only bound nodes update.
+ */
+
+interface I18nProvider {
+    /** Translate a key with optional interpolation args. */
+    t(key: string, args?: Record<string, FieldValue>): string;
+}
+interface QueryResult<T> {
+    readonly data: T | undefined;
+    readonly loading: boolean;
+    readonly error: unknown;
+}
+interface QueryProvider {
+    /** Return a reactive query result for a key and optional params. */
+    query<T = unknown>(key: string, params?: Record<string, unknown>): ReadSignal<QueryResult<T>>;
+}
+interface ThemeProvider {
+    token(name: string): string;
+}
+interface Providers {
+    readonly i18n?: I18nProvider;
+    readonly query?: QueryProvider;
+    readonly theme?: ThemeProvider;
+    readonly [name: string]: unknown;
+}
+declare function isProviderRef(value: unknown): value is ProviderRef;
+/**
+ * Resolve a {@link Resolvable} to a concrete value using the available providers.
+ * Literals pass through; sigils dispatch to the matching provider. Unresolved
+ * refs fall back to a readable string so the form still renders.
+ */
+declare function resolve<T extends FieldValue | readonly FieldOption[]>(value: Resolvable<T> | undefined, providers: Providers | undefined): T | undefined;
+/** Resolve a `$query` ref to its reactive result signal, or `null` if not a query ref. */
+declare function resolveQuery(value: unknown, providers: Providers | undefined): ReadSignal<QueryResult<unknown>> | null;
+
+/**
+ * Reactive per-field model. Each {@link FieldState} owns the signals for one
+ * field — its value, error, and touched flag — plus computed `visible`,
+ * `enabled`, and `required` derived from the schema's conditions. The renderer
+ * binds directly to these signals, so a change updates only the affected nodes.
+ */
+
+/** Default value for a leaf field with no explicit initial/default. */
+declare function defaultValueFor(type: string): FieldValue;
+declare class FieldState {
+    /** Discriminant for the {@link FieldNode} union (leaf vs group/collection). */
+    readonly kind: "field";
+    readonly id: string;
+    readonly 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;
+    reset(value: FieldValue): void;
+}
+
+/**
+ * Nested field tree — `group` (object) and `collection` (array-of-groups) nodes
+ * on top of the leaf {@link FieldState}.
+ *
+ * Names in conditions resolve **lexically**: a child first looks among its own
+ * siblings, then walks up the enclosing {@link Scope} chain to the form root. So
+ * a field nested inside a group or a collection row can be hidden by an outer
+ * toggle (`{ var: "showDetails" }`) *and* by a sibling in the same row — without
+ * any path syntax. Hidden fields keep their value in the aggregated payload but
+ * 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;
+/** Resolves a referenced field name to its current value, walking enclosing scopes. */
+type Scope = ValueGetter;
+type Dict = Record<string, unknown>;
+/** A nested object field: produces `{ ...visible child values }`. */
+declare class GroupNode {
+    readonly kind: "group";
+    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>;
+    /** The scope a child uses: resolve a name among siblings, else delegate upward. */
+    readonly scope: Scope;
+    constructor(schema: FieldSchema, parentScope: Scope, initial: Dict);
+    reset(initial: Dict): void;
+}
+/** One row of a {@link CollectionNode}: a group with a stable identity key. */
+interface CollectionItem {
+    readonly key: number;
+    readonly group: GroupNode;
+}
+/** A repeatable list of object rows: produces `[{ ... }, { ... }]`. */
+declare class CollectionNode {
+    readonly kind: "collection";
+    readonly id: string;
+    readonly schema: FieldSchema;
+    readonly value: ReadSignal<Dict[]>;
+    readonly visible: ReadSignal<boolean>;
+    readonly enabled: ReadSignal<boolean>;
+    private readonly rows;
+    private readonly parentScope;
+    private readonly itemSchema;
+    private seq;
+    constructor(schema: FieldSchema, parentScope: Scope, initial: Dict[]);
+    /** Reactive list of rows (subscribes the caller to add/remove). */
+    get items(): ReadSignal<CollectionItem[]>;
+    private makeItem;
+    private seedRows;
+    /** Append a new empty row, unless `maxItems` is reached. */
+    add(): void;
+    /** Remove the row at `index`, unless `minItems` would be violated. */
+    removeAt(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). */
+declare function eachLeaf(nodes: readonly FieldNode[], visit: (leaf: FieldState) => void): void;
+
+/**
+ * The {@link Form} class — Formwright's public, class-based, imperative API.
+ *
+ *   const form = new Form(schema, { email: "" }, options);
+ *   form.mount(document.getElementById("root")!);
+ *   await form.submit();
+ *
+ * The instance owns the reactive field graph, validation, the condition engine,
+ * provider wiring, and the submission pipeline. It is render-agnostic: `mount`
+ * delegates to a registered renderer (e.g. `@formwright/dom`), so the same
+ * instance can drive the DOM, a web component, or a framework adapter.
+ */
+
+/** Form values — nested for `group` (object) and `collection` (array) fields. */
+type FormValues = Record<string, unknown>;
+type FormErrors = Record<string, string | null>;
+/** A transform applied to values before submission. */
+type Transform = (values: FormValues, form: Form) => unknown;
+/** Handlers referenced by name from the schema's `submit` block. */
+type SuccessHandler = (result: unknown, form: Form) => void;
+type ErrorHandler = (error: unknown, form: Form) => void;
+interface FormOptions {
+    readonly providers?: Providers;
+    readonly transforms?: Record<string, Transform>;
+    readonly handlers?: Record<string, SuccessHandler | ErrorHandler>;
+    /** Override the network send (defaults to `fetch` against `submit.endpoint`). */
+    readonly send?: (payload: unknown, form: Form) => Promise<unknown>;
+}
+/** 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 Listener = (payload: unknown) => void;
+/** Register the renderer used by {@link Form.mount} when none is passed explicitly. */
+declare function setDefaultRenderer(renderer: FormRenderer): void;
+declare class Form {
+    readonly schema: FormSchema;
+    readonly options: FormOptions;
+    /** Top-level field tree (leaf fields, groups, and collections, in order). */
+    readonly tree: readonly FieldNode[];
+    readonly order: readonly string[];
+    /** Reactive snapshot of all field values (nested for groups/collections). */
+    readonly values: ReadSignal<FormValues>;
+    /** True when the current values differ from the initial values. */
+    readonly isDirty: ReadSignal<boolean>;
+    /** True when no visible field currently has an error. */
+    readonly isValid: ReadSignal<boolean>;
+    private readonly submitting;
+    private readonly initialValues;
+    private readonly initialSnapshot;
+    private readonly rootByName;
+    private readonly listeners;
+    private disposeRenderer;
+    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>;
+    /** Resolve a leaf field by dotted path. Top-level ids work directly. */
+    field(path: string): FieldState | undefined;
+    getValue(path: string): FieldValue;
+    setValue(path: string, value: FieldValue): void;
+    /** 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;
+    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>;
+    reset(values?: FormValues): void;
+    /** Mount into a host element using the given renderer (or the registered default). */
+    mount(host: Element, renderer?: FormRenderer | null): Dispose;
+    destroy(): void;
+    on(event: EventName, listener: Listener): Dispose;
+    private emit;
+    private collectErrors;
+    private applyTransform;
+    private send;
+    private runSuccessHandler;
+    private runErrorHandler;
+}
+declare class FormValidationError extends Error {
+    readonly errors: FormErrors;
+    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 };