@rokkit/forms 1.0.0-next.125 → 1.0.0-next.128

package/src/lib/builder.svelte.js

@@ -1,7 +1,43 @@
 import { deriveSchemaFromValue } from './schema.js'
 import { deriveLayoutFromValue } from './layout.js'
 import { getSchemaWithLayout } from './fields.js'
-import { omit } from 'ramda'
+import { createLookupManager } from './lookup.svelte.js'
+import { validateField as validateFieldValue, validateAll as validateAllFields } from './validation.js'
+
+/**
+ * Deep-clone a plain value (primitives, plain objects, arrays).
+ * Uses JSON round-trip which handles $state proxies safely.
+ * @param {any} value
+ * @returns {any}
+ */
+function deepClone(value) {
+	if (value === null || value === undefined || typeof value !== 'object') return value
+	return JSON.parse(JSON.stringify(value))
+}
+
+/**
+ * Deep equality check for plain values (primitives, plain objects, arrays).
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ */
+function deepEqual(a, b) {
+	if (a === b) return true
+	if (a === null || a === undefined || b === null || b === undefined) return a === b
+	if (typeof a !== typeof b) return false
+	if (typeof a !== 'object') return false
+	if (Array.isArray(a) !== Array.isArray(b)) return false
+
+	if (Array.isArray(a)) {
+		if (a.length !== b.length) return false
+		return a.every((val, i) => deepEqual(val, b[i]))
+	}
+
+	const keysA = Object.keys(a)
+	const keysB = Object.keys(b)
+	if (keysA.length !== keysB.length) return false
+	return keysA.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key]))
+}
 
 /**
  * @typedef {Object} FormElement
@@ -19,6 +55,7 @@ import { omit } from 'ramda'
  * @property {Object} [props.message] - Validation message object
  * @property {string} [props.message.state] - Message state: 'error', 'warning', 'info', 'success'
  * @property {string} [props.message.text] - Message text content
+ * @property {boolean} [props.dirty] - Whether field value differs from initial
  */
 
 /**
@@ -28,6 +65,9 @@ export class FormBuilder {
 	/** @type {Object} */
 	#data = $state({})
 
+	/** @type {Object} - Snapshot of data at construction (or last snapshot()) */
+	#initialData = {}
+
 	/** @type {Object} */
 	#schema = $state({})
 
@@ -37,9 +77,21 @@ export class FormBuilder {
 	/** @type {Object} */
 	#validation = $state({})
 
+	/** @type {Object<string, import('./lookup.svelte.js').LookupConfig>} */
+	#lookupConfigs = $state({})
+
+	/** @type {ReturnType<typeof createLookupManager>|null} */
+	#lookupManager = $state(null)
+
 	/** @type {FormElement[]} */
 	elements = $derived(this.#buildElements())
-	combined = $derived(getSchemaWithLayout(this.schema, this.layout))
+
+	/** Combined schema+layout (scoped elements only) */
+	get combined() {
+		const scopedElements = (this.#layout?.elements ?? []).filter((el) => el.scope)
+		const scopedLayout = { ...this.#layout, elements: scopedElements }
+		return getSchemaWithLayout(this.#schema, scopedLayout)
+	}
 	/**
 	 * Get the current data
 	 * @returns {Object} Current data object
@@ -109,19 +161,99 @@ export class FormBuilder {
 	 * @param {Object} [data={}] - Initial data object
 	 * @param {Object|null} [schema=null] - Optional schema override
 	 * @param {Object|null} [layout=null] - Optional layout override
+	 * @param {Object<string, import('./lookup.svelte.js').LookupConfig>} [lookups={}] - Lookup configurations
 	 */
-	constructor(data = {}, schema = null, layout = null) {
+	constructor(data = {}, schema = null, layout = null, lookups = {}) {
 		this.#data = data
+		this.#initialData = deepClone(data)
 		this.schema = schema
 		this.layout = layout
+		this.#lookupConfigs = lookups
+		if (Object.keys(lookups).length > 0) {
+			this.#lookupManager = createLookupManager(lookups)
+		}
+	}
+
+	/**
+	 * Get the lookup manager
+	 * @returns {ReturnType<typeof createLookupManager>|null}
+	 */
+	get lookupManager() {
+		return this.#lookupManager
+	}
+
+	/**
+	 * Configure lookups for the form
+	 * @param {Object<string, import('./lookup.svelte.js').LookupConfig>} lookups - Lookup configurations
+	 */
+	setLookups(lookups) {
+		this.#lookupConfigs = lookups
+		this.#lookupManager = createLookupManager(lookups)
+	}
+
+	/**
+	 * 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) {
+		if (!this.#lookupManager) return null
+		const lookup = this.#lookupManager.getLookup(fieldPath)
+		if (!lookup) return null
+		return {
+			options: lookup.options,
+			loading: lookup.loading,
+			error: lookup.error,
+			fields: lookup.fields,
+			disabled: lookup.disabled
+		}
+	}
+
+	/**
+	 * Check if a field is disabled due to unmet lookup dependencies
+	 * @param {string} path - Field path
+	 * @returns {boolean}
+	 */
+	isFieldDisabled(path) {
+		return this.#lookupManager?.getLookup(path)?.disabled ?? false
+	}
+
+	/**
+	 * Manually refresh a field's lookup with the current form data
+	 * @param {string} path - Field path
+	 * @returns {Promise<void>}
+	 */
+	async refreshLookup(path) {
+		const lookup = this.#lookupManager?.getLookup(path)
+		if (lookup) await lookup.fetch(this.#data)
+	}
+
+	/**
+	 * Check if a field has a lookup configured
+	 * @param {string} fieldPath - Field path
+	 * @returns {boolean}
+	 */
+	hasLookup(fieldPath) {
+		return this.#lookupManager?.hasLookup(fieldPath) ?? false
+	}
+
+	/**
+	 * Initialize all lookups
+	 * @returns {Promise<void>}
+	 */
+	async initializeLookups() {
+		if (this.#lookupManager) {
+			await this.#lookupManager.initialize(this.#data)
+		}
 	}
 
 	/**
 	 * 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, value) {
+	updateField(path, value, triggerLookups = true) {
 		// Simple path handling for now - can be enhanced for nested objects
 		const keys = path.split('/')
 		if (keys.length === 1) {
@@ -137,6 +269,20 @@ export class FormBuilder {
 			current[keys[keys.length - 1]] = value
 			this.#data = updatedData
 		}
+
+		// Trigger dependent lookups if configured
+		if (triggerLookups && this.#lookupManager) {
+			// Clear dependent field values synchronously before lookup re-fetch
+			for (const [depPath, lookup] of this.#lookupManager.lookups) {
+				if (lookup.dependsOn.includes(path)) {
+					const depKeys = depPath.split('/')
+					if (depKeys.length === 1) {
+						this.#data = { ...this.#data, [depKeys[0]]: null }
+					}
+				}
+			}
+			this.#lookupManager.handleFieldChange(path, this.#data)
+		}
 	}
 
 	/**
@@ -165,20 +311,62 @@ export class FormBuilder {
 	 * @returns {FormElement[]} Array of form elements
 	 */
 	#buildElements() {
-		// if (!this.#schema || !this.#layout || !this.#layout.elements) {
-		// 	return []
-		// }
-
 		try {
-			// Use getSchemaWithLayout to combine schema and layout
-			// const combined = getSchemaWithLayout(this.#schema, this.#layout)
-			// Convert combined elements to FormElement format
-			return this.combined.elements
-				.map((element) => this.#convertToFormElement(element))
-				.filter((element) => element !== null)
+			const result = []
+			const layoutElements = this.#layout?.elements ?? []
+			// Track which layout elements have scopes (for schema merge)
+			// Exclude display-* elements — they are handled separately
+			const scopedElements = layoutElements.filter(
+				(el) => el.scope && !el.type?.startsWith('display-')
+			)
+			const scopedLayout = { ...this.#layout, elements: scopedElements }
+			const combined = getSchemaWithLayout(this.#schema, scopedLayout)
+
+			// Build a map of combined elements by key for lookup
+			const combinedMap = new Map()
+			for (const el of combined.elements ?? []) {
+				if (el.key) combinedMap.set(el.key, el)
+			}
+
+			// Iterate original layout order to preserve separators and other non-scoped elements
+			for (const layoutEl of layoutElements) {
+				if (layoutEl.type?.startsWith('display-')) {
+					// Display element — resolve data from scope if present
+					const scope = layoutEl.scope ?? null
+					const fieldPath = scope?.replace(/^#\//, '')
+					const value = fieldPath ? this.getValue(fieldPath) : null
+					const { type: displayType, scope: _s, ...displayProps } = layoutEl
+					result.push({
+						type: displayType,
+						scope,
+						value,
+						override: false,
+						props: displayProps
+					})
+				} else if (!layoutEl.scope) {
+					// Non-scoped element (separator, etc.)
+					const { type: separatorType, ...separatorProps } = layoutEl
+					result.push({
+						type: separatorType ?? 'separator',
+						scope: null,
+						value: null,
+						override: false,
+						props: separatorProps
+					})
+				} else {
+					// Extract key from scope
+					const key = layoutEl.scope.replace(/^#\//, '').split('/').pop()
+					const combinedEl = combinedMap.get(key)
+					if (combinedEl) {
+						const formEl = this.#convertToFormElement(combinedEl)
+						if (formEl) result.push(formEl)
+					}
+				}
+			}
+			return result
 		} catch (error) {
 			// If getSchemaWithLayout fails, fall back to basic element creation
-			console.warn('Failed to build elements:', error)
+			console.warn('Failed to build elements:', error) // eslint-disable-line no-console
 			return this.#buildBasicElements()
 		}
 	}
@@ -226,12 +414,13 @@ export class FormBuilder {
 			label: label || fieldPath,
 			...layoutProps,
 			message: this.#validation[fieldPath] || null,
+			dirty: this.isFieldDirty(fieldPath),
 			type
 		}
 
 		return {
 			scope,
-			// type,
+			type,
 			value,
 			override,
 			props
@@ -265,22 +454,45 @@ export class FormBuilder {
 				this.#convertToFormElement(child, fieldPath)
 			)
 
+			// Group elements have top-level properties (label, etc.) from combineNestedElementsWithSchema
+			const { key: _k, elements: _e, override: _o, props: groupProps, ...topLevelProps } =
+				element
+
 			return {
 				scope,
 				type: 'group',
 				value,
 				override: element.override || false,
 				props: {
-					...props,
+					...topLevelProps,
+					...groupProps,
 					elements: nestedElements,
 					message: this.#validation[fieldPath] || null
 				}
 			}
 		}
 
-		// Determine input type based on schema type
+		// Readonly fields render as info display
+		if (props.readonly) {
+			const validationMessage = this.#validation[fieldPath] || null
+			return {
+				scope,
+				type: 'info',
+				value,
+				override: element.override || false,
+				props: { ...props, type: 'info', message: validationMessage }
+			}
+		}
+
+		// Determine input type — renderer hint takes priority
 		let type = 'text'
-		if (props.type) {
+		if (props.renderer) {
+			// Explicit renderer override — use as-is, resolveRenderer handles lookup
+			type = props.renderer
+		} else if (props.format && !['text', 'number'].includes(props.format)) {
+			// Format hint maps to input type (email, url, tel, color, date, etc.)
+			type = props.format
+		} else if (props.type) {
 			switch (props.type) {
 				case 'number':
 				case 'integer':
@@ -290,11 +502,11 @@ export class FormBuilder {
 					type = 'checkbox'
 					break
 				case 'string':
-					if (props.enum) {
+					if (props.enum || props.options) {
 						type = 'select'
 						// Map enum values to options format expected by select inputs
-						if (Array.isArray(props.enum)) {
-							props.options = props.enum //.map((val) => ({ value: val, label: val }))
+						if (Array.isArray(props.enum) && !props.options) {
+							props.options = props.enum
 						}
 					} else {
 						type = 'text'
@@ -306,19 +518,29 @@ export class FormBuilder {
 			}
 		}
 
-		// Add validation message if exists
+		// Add validation message and dirty state
 		const validationMessage = this.#validation[fieldPath] || null
 
 		// Compose final props
 		const finalProps = {
 			...props,
 			type,
-			message: validationMessage
+			message: validationMessage,
+			dirty: this.isFieldDirty(fieldPath)
+		}
+
+		// Inject lookup state (options, loading, disabled, fields) when present
+		const lookupState = this.getLookupState(fieldPath)
+		if (lookupState) {
+			if (lookupState.options?.length > 0) finalProps.options = lookupState.options
+			if (lookupState.loading) finalProps.loading = true
+			if (lookupState.disabled) finalProps.disabled = true
+			if (lookupState.fields && !finalProps.fields) finalProps.fields = lookupState.fields
 		}
 
 		return {
 			scope,
-			// type,
+			type,
 			value,
 			override: element.override || false,
 			props: finalProps
@@ -336,7 +558,8 @@ export class FormBuilder {
 		if (message) {
 			this.#validation = { ...this.#validation, [fieldPath]: message }
 		} else {
-			this.#validation = omit([fieldPath], this.#validation)
+			const { [fieldPath]: _, ...rest } = this.#validation
+			this.#validation = rest
 		}
 	}
 
@@ -348,12 +571,184 @@ export class FormBuilder {
 	}
 
 	/**
-	 * Reset form to initial state
+	 * Validate a single field by path
+	 * @param {string} fieldPath - Field path (without '#/' prefix)
+	 * @returns {import('./validation.js').ValidationMessage|null} Validation result
+	 */
+	validateField(fieldPath) {
+		const fieldSchema = this.#getFieldSchema(fieldPath)
+		if (!fieldSchema) return null
+
+		const value = this.getValue(fieldPath)
+		const label = this.#getFieldLabel(fieldPath)
+		const result = validateFieldValue(value, fieldSchema, label)
+
+		this.setFieldValidation(fieldPath, result)
+		return result
+	}
+
+	/**
+	 * Validate all fields, populate validation state
+	 * @returns {Object} Validation results keyed by field path
+	 */
+	validate() {
+		const results = validateAllFields(this.#data, this.#schema, this.#layout)
+		this.#validation = results
+		return results
+	}
+
+	/**
+	 * Whether all fields pass validation (no error-state messages)
+	 * @returns {boolean}
+	 */
+	get isValid() {
+		return Object.values(this.#validation).every((msg) => msg.state !== 'error')
+	}
+
+	/**
+	 * Array of current error messages with paths
+	 * @returns {Array<{path: string, state: string, text: string}>}
+	 */
+	get errors() {
+		return Object.entries(this.#validation)
+			.filter(([, msg]) => msg.state === 'error')
+			.map(([path, msg]) => ({ path, ...msg }))
+	}
+
+	/**
+	 * Array of all validation messages with paths, ordered by severity
+	 * @returns {Array<{path: string, state: string, text: string}>}
+	 */
+	get messages() {
+		const order = { error: 0, warning: 1, info: 2, success: 3 }
+		return Object.entries(this.#validation)
+			.filter(([, msg]) => msg !== null && msg !== undefined)
+			.map(([path, msg]) => ({ path, ...msg }))
+			.sort((a, b) => (order[a.state] ?? 4) - (order[b.state] ?? 4))
+	}
+
+	// ── Dirty Tracking ────────────────────────────────────────
+
+	/**
+	 * Whether any field has been modified from its initial value
+	 * @returns {boolean}
+	 */
+	get isDirty() {
+		return !deepEqual(this.#data, this.#initialData)
+	}
+
+	/**
+	 * Set of field paths that differ from their initial values
+	 * @returns {Set<string>}
+	 */
+	get dirtyFields() {
+		const dirty = new Set()
+		this.#collectDirtyFields(this.#data, this.#initialData, '', dirty)
+		return dirty
+	}
+
+	/**
+	 * Check if a single field has been modified from its initial value
+	 * @param {string} fieldPath - Field path (without '#/' prefix)
+	 * @returns {boolean}
+	 */
+	isFieldDirty(fieldPath) {
+		const current = this.getValue(fieldPath)
+		const initial = this.#getInitialValue(fieldPath)
+		return !deepEqual(current, initial)
+	}
+
+	/**
+	 * Update the initial data snapshot to the current data.
+	 * Call after a successful save to clear dirty state.
+	 */
+	snapshot() {
+		this.#initialData = deepClone(this.#data)
+	}
+
+	/**
+	 * Get a field's initial value by path
+	 * @private
+	 * @param {string} path - Field path
+	 * @returns {any} Initial field value
+	 */
+	#getInitialValue(path) {
+		if (!path) return undefined
+
+		const keys = path.split('/')
+		let current = this.#initialData
+		for (const key of keys) {
+			if (current && typeof current === 'object') {
+				current = current[key]
+			} else {
+				return undefined
+			}
+		}
+		return current
+	}
+
+	/**
+	 * Recursively collect dirty field paths by comparing current vs initial
+	 * @private
+	 * @param {any} current - Current data (sub)tree
+	 * @param {any} initial - Initial data (sub)tree
+	 * @param {string} prefix - Path prefix
+	 * @param {Set<string>} dirty - Accumulator set
+	 */
+	#collectDirtyFields(current, initial, prefix, dirty) {
+		const allKeys = new Set([
+			...Object.keys(current ?? {}),
+			...Object.keys(initial ?? {})
+		])
+
+		for (const key of allKeys) {
+			const path = prefix ? `${prefix}/${key}` : key
+			const curVal = current?.[key]
+			const initVal = initial?.[key]
+
+			if (!deepEqual(curVal, initVal)) {
+				dirty.add(path)
+			}
+		}
+	}
+
+	/**
+	 * Get schema definition for a field path
+	 * @private
+	 * @param {string} fieldPath - Field path
+	 * @returns {Object|null} Field schema
+	 */
+	#getFieldSchema(fieldPath) {
+		if (!this.#schema?.properties) return null
+		const keys = fieldPath.split('/')
+		let current = this.#schema.properties
+		for (const key of keys) {
+			if (current && current[key]) {
+				current = current[key]
+			} else {
+				return null
+			}
+		}
+		return current
+	}
+
+	/**
+	 * Get label for a field from layout
+	 * @private
+	 * @param {string} fieldPath - Field path
+	 * @returns {string} Field label
+	 */
+	#getFieldLabel(fieldPath) {
+		const scope = `#/${fieldPath}`
+		const layoutEl = this.#layout?.elements?.find((el) => el.scope === scope)
+		return layoutEl?.label || layoutEl?.title || fieldPath
+	}
+
+	/**
+	 * Reset form data to initial snapshot and clear validation
 	 */
 	reset() {
-		this.#data = {}
-		// this.#schema = {}
-		// this.#layout = {}
+		this.#data = deepClone(this.#initialData)
 		this.#validation = {}
 	}
 }

package/src/lib/fields.js

@@ -7,7 +7,7 @@ import { omit, pick } from 'ramda'
  * @param {import('../types').LayoutSchema} attribute
  */
 function combineArrayElementsWithSchema(element, attribute) {
-	// eslint-disable-next-line no-use-before-define
+	 
 	const schema = getSchemaWithLayout(attribute.props.items, element.schema)
 	return {
 		...attribute,
@@ -76,7 +76,7 @@ function combineElementWithSchema(element, schema) {
 	let attribute = findAttributeByPath(scope, schema)
 
 	if (Array.isArray(element.elements)) {
-		// eslint-disable-next-line no-use-before-define
+		 
 		attribute = combineNestedElementsWithSchema(element, attribute, schema)
 	} else if (element.schema || attribute.props?.type === 'array') {
 		attribute = combineArrayElementsWithSchema(element, attribute)

package/src/lib/layout.js

@@ -13,7 +13,7 @@ function deriveElementLayout(val, scope, label) {
 		return {
 			title: label,
 			scope: path,
-			// eslint-disable-next-line no-use-before-define
+			 
 			...deriveLayoutFromValue(val, path)
 		}
 	}
@@ -40,7 +40,7 @@ function deriveObjectLayout(value, scope) {
  * @returns {import('../types').DataLayout}
  */
 function deriveArrayLayout(value, scope) {
-	// eslint-disable-next-line no-use-before-define
+	 
 	const schema = deriveLayoutFromValue(value[0], '#')
 	return {
 		scope,