@rokkit/forms 1.7.0 → 1.8.0

package/dist/lib/state/FormValidation.svelte.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The form's validation messages, keyed by field path, and the ways of producing them.
+ *
+ * Which fields are VISIBLE is the element builder's knowledge (a hidden `showWhen` field has
+ * no element), so it arrives as a function rather than a dependency on the elements — which in
+ * turn read these messages.
+ */
+export class FormValidation {
+    /**
+     * @param {{
+     *   values: import('./FormValues.svelte.js').FormValues,
+     *   definition: import('./FormDefinition.svelte.js').FormDefinition,
+     *   steps: import('./FormSteps.svelte.js').FormSteps,
+     *   visiblePaths: () => string[]
+     * }} parts
+     */
+    constructor({ values, definition, steps, visiblePaths }: {
+        values: import("./FormValues.svelte.js").FormValues;
+        definition: import("./FormDefinition.svelte.js").FormDefinition;
+        steps: import("./FormSteps.svelte.js").FormSteps;
+        visiblePaths: () => string[];
+    });
+    set map(value: {});
+    /** Every message, by field path. */
+    get map(): {};
+    /** One field's message, or null. */
+    message(path: any): any;
+    /** Set a field's message; a null message removes it. */
+    set(path: any, message: any): void;
+    clear(): void;
+    /** No message is an error. */
+    get isValid(): boolean;
+    /** Error messages, with their paths. */
+    get errors(): any[];
+    /** Every message with its path, most severe first. */
+    get sorted(): any[];
+    /** Validate one field against its schema, and record the result. Null without a schema. */
+    validateField(path: any): import("../validation.js").ValidationMessage | null;
+    /**
+     * Validate the whole form. A multi-step form validates every step at once; a flat one keeps
+     * only the results for fields currently visible.
+     */
+    validateAll(): Object;
+    /**
+     * Validate one step's fields, replacing their messages and leaving every other field's alone.
+     * A non-step index is trivially valid.
+     */
+    validateStep(index: any): boolean;
+    /** Drop the messages of fields that are no longer visible (a `showWhen` just hid them). */
+    clearHidden(): void;
+    #private;
+}

package/dist/lib/state/FormValidation.svelte.js

@@ -0,0 +1,140 @@
+import { SvelteSet } from 'svelte/reactivity'
+import { validateField as validateOne, validateAll } from '../validation.js'
+import { stepPaths } from './FormSteps.svelte.js'
+
+/** Severity order for `sorted`; anything unlisted sorts last. */
+const SEVERITY = { error: 0, warning: 1, info: 2, success: 3 }
+
+/**
+ * The form's validation messages, keyed by field path, and the ways of producing them.
+ *
+ * Which fields are VISIBLE is the element builder's knowledge (a hidden `showWhen` field has
+ * no element), so it arrives as a function rather than a dependency on the elements — which in
+ * turn read these messages.
+ */
+export class FormValidation {
+	#values
+	#definition
+	#steps
+	#visiblePaths
+	#map = $state({})
+
+	/**
+	 * @param {{
+	 *   values: import('./FormValues.svelte.js').FormValues,
+	 *   definition: import('./FormDefinition.svelte.js').FormDefinition,
+	 *   steps: import('./FormSteps.svelte.js').FormSteps,
+	 *   visiblePaths: () => string[]
+	 * }} parts
+	 */
+	constructor({ values, definition, steps, visiblePaths }) {
+		this.#values = values
+		this.#definition = definition
+		this.#steps = steps
+		this.#visiblePaths = visiblePaths
+	}
+
+	/** Every message, by field path. */
+	get map() {
+		return this.#map
+	}
+	set map(value) {
+		this.#map = value
+	}
+
+	/** One field's message, or null. */
+	message(path) {
+		return this.#map[path] || null
+	}
+
+	/** Set a field's message; a null message removes it. */
+	set(path, message) {
+		if (message) {
+			this.#map = { ...this.#map, [path]: message }
+			return
+		}
+		const { [path]: _removed, ...rest } = this.#map
+		this.#map = rest
+	}
+
+	clear() {
+		this.#map = {}
+	}
+
+	/** No message is an error. */
+	get isValid() {
+		return Object.values(this.#map).every((msg) => msg.state !== 'error')
+	}
+
+	/** Error messages, with their paths. */
+	get errors() {
+		return Object.entries(this.#map)
+			.filter(([, msg]) => msg.state === 'error')
+			.map(([path, msg]) => ({ path, ...msg }))
+	}
+
+	/** Every message with its path, most severe first. */
+	get sorted() {
+		return Object.entries(this.#map)
+			.filter(([, msg]) => msg !== null && msg !== undefined)
+			.map(([path, msg]) => ({ path, ...msg }))
+			.sort((a, b) => (SEVERITY[a.state] ?? 4) - (SEVERITY[b.state] ?? 4))
+	}
+
+	/** Validate one field against its schema, and record the result. Null without a schema. */
+	validateField(path) {
+		const schema = this.#definition.fieldSchema(path)
+		if (!schema) return null
+		const result = validateOne(this.#values.get(path), schema, this.#definition.fieldLabel(path))
+		this.set(path, result)
+		return result
+	}
+
+	/**
+	 * Validate the whole form. A multi-step form validates every step at once; a flat one keeps
+	 * only the results for fields currently visible.
+	 */
+	validateAll() {
+		const { schema, layout } = this.#definition
+		if (this.#steps.isMultiStep) {
+			const results = validateAll(this.#values.data, schema, {
+				...layout,
+				elements: this.#steps.allStepElements
+			})
+			this.#map = results
+			return results
+		}
+		const visible = new SvelteSet(this.#visiblePaths())
+		const results = Object.fromEntries(
+			Object.entries(validateAll(this.#values.data, schema, layout)).filter(([path]) =>
+				visible.has(path)
+			)
+		)
+		this.#map = results
+		return results
+	}
+
+	/**
+	 * Validate one step's fields, replacing their messages and leaving every other field's alone.
+	 * A non-step index is trivially valid.
+	 */
+	validateStep(index) {
+		const step = this.#steps.step(index)
+		if (!step) return true
+		const { schema, layout } = this.#definition
+		const results = validateAll(this.#values.data, schema, {
+			...layout,
+			elements: step.elements ?? []
+		})
+		for (const path of new SvelteSet(stepPaths(step.elements)))
+			this.set(path, results[path] ?? null)
+		return Object.values(results).every((msg) => msg?.state !== 'error')
+	}
+
+	/** Drop the messages of fields that are no longer visible (a `showWhen` just hid them). */
+	clearHidden() {
+		const visible = new SvelteSet(this.#visiblePaths())
+		const kept = Object.fromEntries(Object.entries(this.#map).filter(([path]) => visible.has(path)))
+		if (Object.keys(kept).length !== Object.keys(this.#map).length) this.#map = kept
+	}
+}

package/dist/lib/state/FormValues.svelte.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A form's data, and how it differs from where it started.
+ *
+ * The initial snapshot is deliberately NOT reactive: it is a baseline, read by the dirty
+ * getters, and taking a new one (after a save) must not by itself re-render anything.
+ */
+export class FormValues {
+    /** @param {Record<string, unknown>} data */
+    constructor(data?: Record<string, unknown>);
+    set data(value: {});
+    get data(): {};
+    /** @param {string} path */
+    get(path: string): any;
+    /** Write one value; the data gets a new root, so readers of `data` re-run. */
+    set(path: any, value: any): void;
+    /** The value a path held in the snapshot. */
+    initial(path: any): any;
+    get isDirty(): boolean;
+    /** Top-level keys whose value differs from the snapshot. */
+    get dirtyFields(): SvelteSet<string>;
+    /** @param {string} path */
+    isFieldDirty(path: string): boolean;
+    /** Make the current data the new baseline — after a successful save. */
+    snapshot(): void;
+    /** Restore the baseline. */
+    reset(): void;
+    #private;
+}
+import { SvelteSet } from 'svelte/reactivity';

package/dist/lib/state/FormValues.svelte.js

@@ -0,0 +1,69 @@
+import { SvelteSet } from 'svelte/reactivity'
+import { deepClone, deepEqual, getPath, setPath } from '../values.js'
+
+/**
+ * A form's data, and how it differs from where it started.
+ *
+ * The initial snapshot is deliberately NOT reactive: it is a baseline, read by the dirty
+ * getters, and taking a new one (after a save) must not by itself re-render anything.
+ */
+export class FormValues {
+	#data = $state({})
+	#initial = {}
+
+	/** @param {Record<string, unknown>} data */
+	constructor(data = {}) {
+		this.#data = data
+		this.#initial = deepClone(data)
+	}
+
+	get data() {
+		return this.#data
+	}
+	set data(value) {
+		this.#data = value
+	}
+
+	/** @param {string} path */
+	get(path) {
+		return getPath(this.#data, path)
+	}
+
+	/** Write one value; the data gets a new root, so readers of `data` re-run. */
+	set(path, value) {
+		this.#data = path.includes('/')
+			? setPath(this.#data, path, value)
+			: { ...this.#data, [path]: value }
+	}
+
+	/** The value a path held in the snapshot. */
+	initial(path) {
+		return getPath(this.#initial, path)
+	}
+
+	get isDirty() {
+		return !deepEqual(this.#data, this.#initial)
+	}
+
+	/** Top-level keys whose value differs from the snapshot. */
+	get dirtyFields() {
+		const current = this.#data ?? {}
+		const keys = new SvelteSet([...Object.keys(current), ...Object.keys(this.#initial ?? {})])
+		return new SvelteSet([...keys].filter((k) => !deepEqual(current[k], this.#initial?.[k])))
+	}
+
+	/** @param {string} path */
+	isFieldDirty(path) {
+		return !deepEqual(this.get(path), this.initial(path))
+	}
+
+	/** Make the current data the new baseline — after a successful save. */
+	snapshot() {
+		this.#initial = deepClone(this.#data)
+	}
+
+	/** Restore the baseline. */
+	reset() {
+		this.#data = deepClone(this.#initial)
+	}
+}

package/dist/lib/validation.js

@@ -1,3 +1,5 @@
+import { schemaAt } from './schema.js'
+
 /**
  * Validation utility for FormBuilder
  * Provides field validation functions that return message objects
@@ -174,33 +176,6 @@ export const patterns = {
 	creditCard: /^\d{4}\s?\d{4}\s?\d{4}\s?\d{4}$/
 }
 
-/**
- * Get field schema by path
- * @private
- * @param {string} fieldPath - Field path
- * @param {Object} schema - Schema object
- * @returns {Object|null} Field schema
- */
-function getFieldSchema(fieldPath, schema) {
-	/* v8 ignore start -- unreachable: the only caller is validateElement, reached
-	   from validateAll, which already returns early on !schema.properties. */
-	if (!schema.properties) return null
-	/* v8 ignore stop */
-
-	const keys = fieldPath.split('/')
-	let current = schema.properties
-
-	for (const key of keys) {
-		if (current && current[key]) {
-			current = current[key]
-		} else {
-			return null
-		}
-	}
-
-	return current
-}
-
 /**
  * Get value by path from data object
  * @private
@@ -273,10 +248,12 @@ export function validateField(value, fieldSchema, fieldLabel = 'Field') {
  * @private
  */
 function validateElement(element, data, schema, results) {
+	// A group's children are fields too — validated at any depth, not just the top level.
+	for (const child of element.elements ?? []) validateElement(child, data, schema, results)
 	if (!element.scope) return
 
 	const fieldPath = element.scope.replace(/^#\//, '')
-	const fieldSchema = getFieldSchema(fieldPath, schema)
+	const fieldSchema = schemaAt(schema, fieldPath)
 	const fieldLabel = element.label || element.title || fieldPath
 	const value = getValueByPath(data, fieldPath)
 

package/dist/lib/values.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure helpers over plain form values — primitives, plain objects and arrays, addressed by
+ * slash paths (`'settings/distance'`).
+ */
+/**
+ * Deep-clone a plain value. A JSON round-trip, which also unwraps `$state` proxies safely.
+ * @param {any} value
+ * @returns {any}
+ */
+export function deepClone(value: any): any;
+/**
+ * Structural equality for plain values. Nullish equals only itself; an array never equals an
+ * object.
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ */
+export function deepEqual(a: any, b: any): boolean;
+/**
+ * The value at a slash path, or undefined — also when the path runs through a non-object.
+ * @param {any} data
+ * @param {string} path
+ */
+export function getPath(data: any, path: string): any;
+/**
+ * A copy of `data` with `value` at the slash path — every object along the path is copied, so
+ * the original is untouched and reactive readers see a new root.
+ * @param {Record<string, any>} data
+ * @param {string} path
+ * @param {any} value
+ */
+export function setPath(data: Record<string, any>, path: string, value: any): {
+    [x: string]: any;
+};
+/**
+ * A field path in its canonical, bare form. Accepts a JSON Forms scope as well — `'#/addr/city'`
+ * and `'addr/city'` name the same field — so the convention layouts are written in is also safe
+ * to pass to the API. (Unnormalised, `'#/name'` wrote to a `'#'` key.)
+ * @param {string} path - anything else (a missing path) passes through unchanged
+ * @returns {string}
+ */
+export function toFieldPath(path: string): string;

package/dist/lib/values.js

@@ -0,0 +1,90 @@
+/**
+ * Pure helpers over plain form values — primitives, plain objects and arrays, addressed by
+ * slash paths (`'settings/distance'`).
+ */
+
+/**
+ * Deep-clone a plain value. A JSON round-trip, which also unwraps `$state` proxies safely.
+ * @param {any} value
+ * @returns {any}
+ */
+export function deepClone(value) {
+	if (value === null || value === undefined || typeof value !== 'object') return value
+	return JSON.parse(JSON.stringify(value))
+}
+
+const isNullish = (v) => v === null || v === undefined
+
+/** Same-shaped containers: both objects, and both arrays or both not. */
+const sameContainer = (a, b) =>
+	typeof a === 'object' && typeof b === 'object' && Array.isArray(a) === Array.isArray(b)
+
+function equalArrays(a, b) {
+	return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]))
+}
+
+function equalObjects(a, b) {
+	const keys = Object.keys(a)
+	return (
+		keys.length === Object.keys(b).length &&
+		keys.every((k) => Object.hasOwn(b, k) && deepEqual(a[k], b[k]))
+	)
+}
+
+/**
+ * Structural equality for plain values. Nullish equals only itself; an array never equals an
+ * object.
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ */
+export function deepEqual(a, b) {
+	if (a === b) return true
+	if (isNullish(a) || isNullish(b) || !sameContainer(a, b)) return false
+	return Array.isArray(a) ? equalArrays(a, b) : equalObjects(a, b)
+}
+
+/**
+ * The value at a slash path, or undefined — also when the path runs through a non-object.
+ * @param {any} data
+ * @param {string} path
+ */
+export function getPath(data, path) {
+	if (!path) return undefined
+	let current = data
+	for (const key of path.split('/')) {
+		if (!current || typeof current !== 'object') return undefined
+		current = current[key]
+	}
+	return current
+}
+
+/**
+ * A copy of `data` with `value` at the slash path — every object along the path is copied, so
+ * the original is untouched and reactive readers see a new root.
+ * @param {Record<string, any>} data
+ * @param {string} path
+ * @param {any} value
+ */
+export function setPath(data, path, value) {
+	const keys = path.split('/')
+	const root = { ...data }
+	let current = root
+	for (const key of keys.slice(0, -1)) {
+		current[key] = { ...current[key] }
+		current = current[key]
+	}
+	current[keys[keys.length - 1]] = value
+	return root
+}
+
+/**
+ * A field path in its canonical, bare form. Accepts a JSON Forms scope as well — `'#/addr/city'`
+ * and `'addr/city'` name the same field — so the convention layouts are written in is also safe
+ * to pass to the API. (Unnormalised, `'#/name'` wrote to a `'#'` key.)
+ * @param {string} path - anything else (a missing path) passes through unchanged
+ * @returns {string}
+ */
+export function toFieldPath(path) {
+	return typeof path === 'string' && path.startsWith('#/') ? path.slice(2) : path
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/forms",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Form building components for Rokkit applications",
   "repository": {
     "type": "git",