@rokkit/forms 1.6.0 → 1.8.0

package/README.md

@@ -73,10 +73,12 @@ import { FormBuilder } from '@rokkit/forms'
 const form = new FormBuilder(data, schema, layout)
 
 // form.elements → [{ scope, type, value, props }, ...]
+// A field path is a JSON Forms scope ('#/address/city') or the bare path ('address/city')
 form.updateField('#/name', 'Alice')
 form.validateField('#/name')
-form.validateAll()
-form.isDirty('#/name') // true if value differs from initial
+form.validate() // every visible field, including those inside groups
+form.isFieldDirty('#/name') // true if the value differs from the initial snapshot
+form.isDirty // any field changed
 ```
 
 ### Validation

package/dist/lib/builder.svelte.d.ts

@@ -1,280 +1,132 @@
 /**
- * FormBuilder class for dynamically generating forms from data structures
+ * The state behind a schema-driven form — a COMPOSITION of job classes (`./state/`), each
+ * owning one concern:
+ *
+ *   values → definition → steps → validation → lookups, and `elements` derived from them all
+ *   by the pure `buildElements` (`./elements.js`).
+ *
+ * It holds almost no logic itself: `next()` (validate the step, then advance), `updateField()`
+ * (write, drop hidden messages, re-fetch dependent lookups) and `getVisibleData()` are the only
+ * methods that span two jobs. Everything else is the public API FormRenderer, MultiStep and
+ * consumers use, kept as delegations so none of them changed when the class was taken apart.
  */
 export class FormBuilder {
     /**
-     * Create a new FormBuilder instance
      * @param {Record<string, unknown>} [data={}] - Initial data object
-     * @param {Object|null} [schema=null] - Optional schema override
-     * @param {Object|null} [layout=null] - Optional layout override
+     * @param {Object|null} [schema=null] - Schema; derived from the data when omitted
+     * @param {Object|null} [layout=null] - Layout; derived from the schema, else the data, when omitted
      * @param {Object<string, import('./lookup.svelte.js').LookupConfig>} [lookups={}] - Lookup configurations
      */
     constructor(data?: Record<string, unknown>, schema?: Object | null, layout?: Object | null, lookups?: {
         [x: string]: import("./lookup.svelte.js").LookupConfig;
     });
-    /** @type {FormElement[]} */
-    elements: FormElement[];
-    /** True when currentStep can advance to the next step */
-    canAdvance: boolean;
-    /** Combined schema+layout (scoped elements only) */
+    /** The form's data and its dirty baseline. */
+    values: FormValues;
+    /** Schema and layout, and how each derives from the other. */
+    definition: FormDefinition;
+    /** Multi-step navigation. */
+    steps: FormSteps;
+    /** Validation messages, and the ways of producing them. Suffixed: `validation` is the public map. */
+    validationState: FormValidation;
+    /** Fields whose options come from elsewhere, and what they depend on. */
+    lookups: FormLookups;
+    /** @type {import('./elements.js').FormElement[]} */
+    elements: import("./elements.js").FormElement[];
+    set data(value: {});
+    get data(): {};
+    /**
+     * Every method taking a field path accepts a bare slash path (`'settings/distance'`) or a
+     * JSON Forms scope (`'#/settings/distance'`) — see `toFieldPath`.
+     */
+    getValue(path: any): any;
+    /**
+     * Write a field, then drop messages of fields a `showWhen` just hid, then clear and re-fetch
+     * the lookups that depend on it.
+     * @param {string} path
+     * @param {any} value
+     * @param {boolean} [triggerLookups=true]
+     */
+    updateField(scopeOrPath: any, value: any, triggerLookups?: boolean): void;
+    /** The data without hidden fields' values. Does not mutate the data. */
+    getVisibleData(): {
+        [k: string]: any;
+    };
+    get isDirty(): boolean;
+    /** Top-level fields that differ from the initial snapshot. */
+    get dirtyFields(): SvelteSet<string>;
+    isFieldDirty(fieldPath: any): boolean;
+    /** Make the current data the baseline — after a successful save. */
+    snapshot(): void;
+    /** Restore the baseline and clear every message. */
+    reset(): void;
+    set schema(value: {});
+    /** Setting it may re-derive the layout — see FormDefinition. */
+    get schema(): {};
+    set layout(value: {});
+    /** A null layout derives from the schema, else the data. */
+    get layout(): {};
+    /** Schema merged with the scoped layout elements. */
     get combined(): any;
-    /**
-     * Set the data
-     * @param {Record<string, unknown>} value - New data object
-     */
-    set data(value: Record<string, unknown>);
-    /**
-     * Get the current data
-     * @returns {Record<string, unknown>} Current data object
-     */
-    get data(): Record<string, unknown>;
-    /**
-     * Set the schema
-     * @param {Object} value - New schema object
-     *
-     * When the caller explicitly provides a schema, that schema is the source
-     * of truth for which fields exist — the layout may have been derived
-     * earlier from empty/partial data and would silently hide those fields.
-     * Re-derive the layout from the new schema so the two stay consistent,
-     * unless the caller has already installed an explicit non-empty layout.
-     */
-    set schema(value: Object);
-    /**
-     * Get the current schema
-     * @returns {Object} Current schema object
-     */
-    get schema(): Object;
-    /**
-     * Set the layout
-     * @param {Object} value - New layout object
-     */
-    set layout(value: Object);
-    /**
-     * Get the current layout
-     * @returns {Object} Current layout object
-     */
-    get layout(): Object;
-    /**
-     * Set validation messages for fields
-     * @param {Object} value - Validation object with field paths as keys
-     */
-    set validation(value: Object);
-    /**
-     * Get the current validation state
-     * @returns {Object} Current validation object
-     */
-    get validation(): Object;
-    /**
-     * Get the lookup manager
-     * @returns {ReturnType<typeof createLookupManager>|null}
-     */
-    get lookupManager(): ReturnType<typeof createLookupManager> | null;
-    /**
-     * Configure lookups for the form
-     * @param {Object<string, import('./lookup.svelte.js').LookupConfig>} lookups - Lookup configurations
-     */
-    setLookups(lookups: {
-        [x: string]: import("./lookup.svelte.js").LookupConfig;
-    }): void;
-    /**
-     * Get lookup state for a field
-     * @param {string} fieldPath - Field path
-     * @returns {{ options: any[], loading: boolean, error: string|null, fields: Object, disabled: boolean }|null}
-     */
-    getLookupState(fieldPath: string): {
-        options: any[];
-        loading: boolean;
-        error: string | null;
-        fields: Object;
-        disabled: boolean;
-    } | null;
-    /**
-     * Check if a field is disabled due to unmet lookup dependencies
-     * @param {string} path - Field path
-     * @returns {boolean}
-     */
-    isFieldDisabled(path: string): boolean;
-    /**
-     * Manually refresh a field's lookup with the current form data
-     * @param {string} path - Field path
-     * @returns {Promise<void>}
-     */
-    refreshLookup(path: string): Promise<void>;
-    /**
-     * Check if a field has a lookup configured
-     * @param {string} fieldPath - Field path
-     * @returns {boolean}
-     */
-    hasLookup(fieldPath: string): boolean;
-    /**
-     * Initialize all lookups
-     * @returns {Promise<void>}
-     */
-    initializeLookups(): Promise<void>;
-    /**
-     * Update a specific field value
-     * @param {string} path - Field path (e.g., 'count', 'settings/distance')
-     * @param {any} value - New value
-     * @param {boolean} [triggerLookups=true] - Whether to trigger dependent lookups
-     */
-    updateField(path: string, value: any, triggerLookups?: boolean): void;
-    /**
-     * Get a field value by path
-     * @param {string} path - Field path
-     * @returns {any} Field value
-     */
-    getValue(path: string): any;
-    /**
-     * Set validation message for a specific field
-     * @param {string} fieldPath - Field path (without '#/' prefix)
-     * @param {Object|null} message - Validation message object or null to clear
-     * @param {string} message.state - Message state: 'error', 'warning', 'info', 'success'
-     * @param {string} message.text - Message text content
-     */
+    set validation(value: {});
+    /** The validation messages, by field path. */
+    get validation(): {};
+    /** @param {string} fieldPath @param {Object|null} message - null clears it */
     setFieldValidation(fieldPath: string, message: Object | null): void;
-    /**
-     * Clear all validation messages
-     */
     clearValidation(): void;
-    /**
-     * Validate a single field by path
-     * @param {string} fieldPath - Field path (without '#/' prefix)
-     * @returns {import('./validation.js').ValidationMessage|null} Validation result
-     */
-    validateField(fieldPath: string): import("./validation.js").ValidationMessage | null;
-    /**
-     * Validate all fields, populate validation state
-     * @returns {Object} Validation results keyed by field path
-     */
+    /** @returns {import('./validation.js').ValidationMessage|null} */
+    validateField(fieldPath: any): import("./validation.js").ValidationMessage | null;
+    /** Validate the whole form (every step of a wizard; the visible fields of a flat form). */
     validate(): Object;
-    /**
-     * Get form data with hidden field values stripped out
-     * Hidden fields are those absent from this.elements (the derived list)
-     * Does not mutate this.#data
-     * @returns {Record<string, unknown>} Filtered data containing only visible field keys
-     */
-    getVisibleData(): Record<string, unknown>;
-    /**
-     * Whether all fields pass validation (no error-state messages)
-     * @returns {boolean}
-     */
+    /** Validate one step's fields. */
+    validateStep(index: any): boolean;
+    isStepValid(index?: number): boolean;
     get isValid(): boolean;
-    /**
-     * Array of current error messages with paths
-     * @returns {Array<{path: string, state: string, text: string}>}
-     */
+    /** @returns {Array<{path: string, state: string, text: string}>} */
     get errors(): Array<{
         path: string;
         state: string;
         text: string;
     }>;
-    /**
-     * Array of all validation messages with paths, ordered by severity
-     * @returns {Array<{path: string, state: string, text: string}>}
-     */
+    /** @returns {Array<{path: string, state: string, text: string}>} most severe first */
     get messages(): Array<{
         path: string;
         state: string;
         text: string;
     }>;
-    /**
-     * Whether any field has been modified from its initial value
-     * @returns {boolean}
-     */
-    get isDirty(): boolean;
-    /**
-     * Set of field paths that differ from their initial values
-     * @returns {Set<string>}
-     */
-    get dirtyFields(): Set<string>;
-    /**
-     * Check if a single field has been modified from its initial value
-     * @param {string} fieldPath - Field path (without '#/' prefix)
-     * @returns {boolean}
-     */
-    isFieldDirty(fieldPath: string): boolean;
-    /**
-     * Update the initial data snapshot to the current data.
-     * Call after a successful save to clear dirty state.
-     */
-    snapshot(): void;
-    /**
-     * Reset form data to initial snapshot and clear validation
-     */
-    reset(): void;
-    /** True when the layout contains step elements */
     get isMultiStep(): any;
-    /** Number of step elements in the layout */
     get totalSteps(): any;
-    /** Zero-based index of the active step */
     get currentStep(): number;
-    /**
-     * Validate the current step and advance if valid.
-     * @returns {boolean} true if advanced, false if validation failed
-     */
+    get canAdvance(): boolean;
+    /** Validate the current step, and advance only if it passes. */
     next(): boolean;
-    /**
-     * Move to the previous step without validation.
-     * @returns {boolean} true if moved, false if already on first step
-     */
+    /** Back one step, without validating. */
     prev(): boolean;
-    /**
-     * Navigate to a previously visited step (index < currentStep).
-     * @param {number} index - Target step index
-     */
-    goToStep(index: number): void;
-    /**
-     * Validate all fields in a given step. Defaults to currentStep.
-     * @param {number} [index] - Step index (defaults to currentStep)
-     * @returns {boolean} true if no errors
-     */
-    isStepValid(index?: number): boolean;
-    /**
-     * Validate all fields belonging to a step by index.
-     * @param {number} index - Step index
-     * @returns {boolean} true if no errors
-     */
-    validateStep(index: number): boolean;
+    /** Return to a visited step. */
+    goToStep(index: any): void;
+    /** The underlying lookup manager, or null for a form without lookups. */
+    get lookupManager(): Object | null;
+    /** @param {Object<string, import('./lookup.svelte.js').LookupConfig>} lookups */
+    setLookups(lookups: {
+        [x: string]: import("./lookup.svelte.js").LookupConfig;
+    }): void;
+    /** @returns {{ options: any[], loading: boolean, error: string|null, fields: Object, disabled: boolean }|null} */
+    getLookupState(fieldPath: any): {
+        options: any[];
+        loading: boolean;
+        error: string | null;
+        fields: Object;
+        disabled: boolean;
+    } | null;
+    /** Disabled because a field its lookup depends on is not set yet. */
+    isFieldDisabled(path: any): any;
+    refreshLookup(path: any): Promise<void>;
+    hasLookup(fieldPath: any): any;
+    initializeLookups(): Promise<void>;
     #private;
 }
-export type FormElement = {
-    /**
-     * - JSON Pointer path (e.g., '#/email', '#/user/name')
-     */
-    scope: string;
-    /**
-     * - Input type (text, number, range, checkbox, select, etc.)
-     */
-    type: string;
-    /**
-     * - Current value from data
-     */
-    value: any;
-    /**
-     * - Whether to use custom child snippet (from layout)
-     */
-    override: boolean;
-    /**
-     * - Merged properties from schema + layout + validation
-     */
-    props: {
-        label?: string | undefined;
-        description?: string | undefined;
-        placeholder?: string | undefined;
-        required?: boolean | undefined;
-        min?: number | undefined;
-        max?: number | undefined;
-        message?: {
-            /**
-             * - Message state: 'error', 'warning', 'info', 'success'
-             */
-            state?: string | undefined;
-            /**
-             * - Message text content
-             */
-            text?: string | undefined;
-        } | undefined;
-        dirty?: boolean | undefined;
-    };
-};
-import { createLookupManager } from './lookup.svelte.js';
+import { FormValues } from './state/FormValues.svelte.js';
+import { FormDefinition } from './state/FormDefinition.svelte.js';
+import { FormSteps } from './state/FormSteps.svelte.js';
+import { FormValidation } from './state/FormValidation.svelte.js';
+import { FormLookups } from './state/FormLookups.svelte.js';
+import { SvelteSet } from 'svelte/reactivity';