@rokkit/forms 1.0.0-next.132 → 1.0.0-next.134

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jerry Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,251 +1,195 @@
 # @rokkit/forms
 
-Schema-driven form rendering for Svelte 5. Generate dynamic forms from data, schema, and layout definitions.
+Schema-driven form builder and renderer for Svelte 5 applications.
 
 ## Installation
 
 ```bash
+npm install @rokkit/forms
+# or
 bun add @rokkit/forms
 ```
 
-## Core Concepts
+## Overview
 
-### FormBuilder
+`@rokkit/forms` generates dynamic forms from a data object, a JSON Schema definition, and a layout configuration. Both schema and layout can be auto-derived from data, so you can get a working form with zero configuration. The `FormBuilder` class produces a reactive `elements[]` array; the `FormRenderer` component renders it.
 
-Takes `(data, schema, layout)` and produces a reactive `elements[]` array. Each element describes a form field with its type, current value, and merged properties.
+## Usage
 
-```js
-import { FormBuilder } from '@rokkit/forms'
+### Minimal — auto-derive everything
 
-const builder = new FormBuilder(
-  { name: 'Alice', age: 30 },     // data
-  schema,                           // optional — auto-derived from data
-  layout                            // optional — auto-derived from data
-)
+```svelte
+<script>
+  import { FormRenderer } from '@rokkit/forms'
 
-// builder.elements → [{ scope, type, value, props }, ...]
+  let data = $state({ name: '', age: 0, active: true })
+</script>
+
+<FormRenderer bind:data />
 ```
 
-If `schema` is `null`, it is auto-derived from the data using `deriveSchemaFromValue()`. If `layout` is `null`, it is auto-derived using `deriveLayoutFromValue()`.
+Schema and layout are inferred from the data shape automatically.
 
-### Schema
+### With explicit schema and layout
 
-JSON-Schema-like type definitions. Supports: `string`, `number`, `integer`, `boolean`, `array`, `object`, `date`.
+```svelte
+<script>
+  import { FormRenderer } from '@rokkit/forms'
 
-```js
-const schema = {
-  type: 'object',
-  properties: {
-    name: { type: 'string' },
-    size: { type: 'string', enum: ['sm', 'md', 'lg'] },
-    count: { type: 'integer', min: 0, max: 100 },
-    active: { type: 'boolean' }
+  let data = $state({ name: '', role: 'viewer', count: 5, active: false })
+
+  const schema = {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      role: { type: 'string', enum: ['viewer', 'editor', 'admin'] },
+      count: { type: 'integer', min: 0, max: 100 },
+      active: { type: 'boolean' }
+    }
+  }
+
+  const layout = {
+    type: 'vertical',
+    elements: [
+      { scope: '#/name', label: 'Full Name', props: { placeholder: 'Enter name' } },
+      { scope: '#/role', label: 'Role' },
+      { scope: '#/count', label: 'Count' },
+      { type: 'separator' },
+      { scope: '#/active', label: 'Active' }
+    ]
   }
-}
+</script>
+
+<FormRenderer bind:data {schema} {layout} onupdate={(val) => console.log(val)} />
 ```
 
-### Layout
+### FormBuilder (imperative)
 
-Controls rendering order, grouping, labels, and component-specific props. Uses JSON Pointer scopes (`#/fieldName`).
+Use `FormBuilder` directly when you need to drive forms outside of `FormRenderer`:
 
 ```js
-const layout = {
-  type: 'vertical',
-  elements: [
-    { scope: '#/name', label: 'Full Name', props: { placeholder: 'Enter name' } },
-    { scope: '#/size', label: 'Size', props: { options: ['sm', 'md', 'lg'] } },
-    { scope: '#/count', label: 'Count' },
-    { type: 'separator' },
-    { scope: '#/active', label: 'Active' },
-    { scope: '#/total', label: 'Total', readonly: true }
-  ]
-}
+import { FormBuilder } from '@rokkit/forms'
+
+const form = new FormBuilder(data, schema, layout)
+
+// form.elements → [{ scope, type, value, props }, ...]
+form.updateField('#/name', 'Alice')
+form.validateField('#/name')
+form.validateAll()
+form.isDirty('#/name') // true if value differs from initial
 ```
 
-### Type Resolution
+### Validation
 
-The FormBuilder determines input type from the schema:
+```js
+import { validateField, validateAll, patterns } from '@rokkit/forms'
 
-| Schema type | Condition | Input type |
-|---|---|---|
-| `string` | has `enum` or `options` | `select` |
-| `string` | default | `text` |
-| `boolean` | — | `checkbox` |
-| `number`/`integer` | has `min` and `max` | `range` |
-| `number`/`integer` | default | `number` |
-| any | `readonly: true` | `info` |
-| — | no `scope` | `separator` |
+const result = validateField(value, { required: true, pattern: patterns.email })
+// result → { state: 'error', text: 'Invalid email address' } | null
+```
 
-### Layout Props
+### Dependent lookups with createLookup
 
-The `props` field in layout elements passes component-specific configuration:
+`createLookup` creates a reactive dropdown data source that can depend on other field values:
 
 ```js
-// Select with string options
-{ scope: '#/size', props: { options: ['sm', 'md', 'lg'] } }
+import { createLookup } from '@rokkit/forms'
 
-// Select with object options and field mapping
-{ scope: '#/color', props: {
-  options: [{ name: 'Red', hex: '#f00' }, { name: 'Blue', hex: '#00f' }],
-  fields: { text: 'name', value: 'hex' }
-}}
+// Fetch from a URL template — {region} is replaced by the current field value
+const countriesLookup = createLookup({ url: '/api/countries?region={region}' })
 
-// Readonly info display
-{ scope: '#/total', readonly: true }
+// Async fetch function — receives current dependency values
+const citiesLookup = createLookup({
+  fetch: async (deps) => {
+    if (!deps.country) return { disabled: true, options: [] }
+    return { options: await getCities(deps.country) }
+  }
+})
 
-// Separator (no scope)
-{ type: 'separator' }
+// Client-side filter — no network request
+const filteredLookup = createLookup({
+  source: allOptions,
+  filter: (item, deps) => item.region === deps.region
+})
 ```
 
-## Components
-
-### FormRenderer
+### Custom field rendering
 
-Renders a complete form from data + schema + layout:
+Override individual fields with your own components using the `child` snippet and `override: true` in the layout:
 
 ```svelte
 <script>
   import { FormRenderer } from '@rokkit/forms'
 
-  let data = $state({ name: '', size: 'md', active: true })
+  const layout = {
+    type: 'vertical',
+    elements: [
+      { scope: '#/tags', label: 'Tags', override: true },
+      { scope: '#/name', label: 'Name' }
+    ]
+  }
 </script>
 
-<FormRenderer bind:data {schema} {layout} />
-```
-
-**Props:**
-- `data` (bindable) — form data object
-- `schema` — JSON schema (optional, auto-derived)
-- `layout` — layout definition (optional, auto-derived)
-- `onupdate` — callback when data changes
-- `onvalidate` — callback for field validation
-- `child` — snippet for custom field rendering (receives `element`)
-
-**Custom field rendering:**
-
-```svelte
 <FormRenderer bind:data {schema} {layout}>
   {#snippet child(element)}
-    <MyCustomInput value={element.value} {...element.props} />
+    <!-- rendered for elements with override: true -->
+    <TagInput value={element.value} onchange={(v) => form.updateField(element.scope, v)} />
   {/snippet}
 </FormRenderer>
 ```
 
-Set `override: true` on layout elements to route them to the `child` snippet.
-
-### InputField
+## Type resolution
 
-Wraps an input with label, description, and validation message:
+`FormBuilder` maps schema types to input types automatically:
 
-```svelte
-<InputField name="email" type="email" value={email} label="Email" onchange={handleChange} />
-```
+| Schema type          | Condition                         | Input type  |
+| -------------------- | --------------------------------- | ----------- |
+| `string`             | has `enum` or `options` in layout | `select`    |
+| `string`             | default                           | `text`      |
+| `boolean`            | —                                 | `checkbox`  |
+| `number` / `integer` | has both `min` and `max`          | `range`     |
+| `number` / `integer` | default                           | `number`    |
+| any                  | `readonly: true` in layout        | `info`      |
+| —                    | no `scope`                        | `separator` |
 
-### Input
-
-Type dispatcher — renders the appropriate input component based on `type`:
-
-- `text`, `email`, `password`, `url`, `tel` — text inputs
-- `number` — numeric input
-- `range` — slider
-- `checkbox` — checkbox
-- `select` — dropdown (uses `@rokkit/ui` Select)
-- `date`, `time`, `datetime-local`, `month`, `week` — date/time inputs
-- `color` — color picker
-- `file` — file upload
-- `textarea` — multiline text
-- `radio` — radio group
-
-### InfoField
-
-Read-only display of a label and value:
+## Components
 
-```svelte
-<InfoField label="Total" value={42} />
-```
+| Component          | Description                                                           |
+| ------------------ | --------------------------------------------------------------------- |
+| `FormRenderer`     | Renders a complete form from data + schema + layout                   |
+| `Input`            | Type-dispatching input — renders the right control for a given `type` |
+| `InputField`       | Input wrapped with label, description, and validation message         |
+| `InfoField`        | Read-only label + value display                                       |
+| `ValidationReport` | Displays a list of validation messages                                |
 
-## Lib Utilities
+## Utilities
 
 ```js
-import { getSchemaWithLayout, findAttributeByPath } from '@rokkit/forms'
-import { deriveSchemaFromValue } from '@rokkit/forms/lib'
-import { deriveLayoutFromValue } from '@rokkit/forms/lib'
+import {
+  deriveSchemaFromValue, // infer JSON schema from a data object
+  deriveLayoutFromValue, // generate a default vertical layout from data
+  getSchemaWithLayout, // merge schema attributes with layout elements
+  findAttributeByPath, // look up a schema attribute by JSON Pointer path
+  validateField, // validate a single value against schema constraints
+  validateAll, // validate all fields in a FormBuilder
+  patterns // regex patterns: email, url, phone, etc.
+} from '@rokkit/forms'
 ```
 
-- `deriveSchemaFromValue(data)` — infer schema from a data object
-- `deriveLayoutFromValue(data)` — generate default vertical layout from data
-- `getSchemaWithLayout(schema, layout)` — merge schema attributes with layout elements
-- `findAttributeByPath(scope, schema)` — find schema attribute by JSON Pointer path
-
 ## Theming
 
-Form field styles are provided by `@rokkit/themes`. The components use data-attribute selectors:
-
-| Selector | Purpose |
-|---|---|
-| `[data-form-root]` | Form container |
-| `[data-form-field]` | Field wrapper |
-| `[data-form-separator]` | Separator between fields |
-| `[data-field-root]` | Input field root |
-| `[data-field]` | Field inner wrapper |
-| `[data-field-type="..."]` | Type-specific layout (checkbox, info, select) |
-| `[data-field-info]` | Info/readonly value display |
-| `[data-input-root]` | Input element wrapper |
-| `[data-description]` | Help text |
-| `[data-message]` | Validation message |
-
-## Future Enhancements
-
-### Toggle/Switch as Checkbox Alternative
-
-Use `@rokkit/ui` Toggle or Switch components as alternatives to the native checkbox for boolean fields. The layout could specify the preferred component:
-
-```js
-{ scope: '#/active', label: 'Active', props: { component: 'switch' } }
-```
-
-### Toggle as Select Alternative
+Components use `data-*` attribute selectors. Apply styles via `@rokkit/themes` or target these hooks directly:
 
-For fields with a small number of options, a Toggle (radio-style button group) can replace Select for better UX:
+| Selector                  | Purpose              |
+| ------------------------- | -------------------- |
+| `[data-form-root]`        | Form container       |
+| `[data-form-field]`       | Field wrapper        |
+| `[data-form-separator]`   | Separator element    |
+| `[data-field-root]`       | Input field root     |
+| `[data-field-type="..."]` | Type-specific layout |
+| `[data-description]`      | Help text            |
+| `[data-message]`          | Validation message   |
 
-```js
-{ scope: '#/size', label: 'Size', props: { component: 'toggle', options: ['sm', 'md', 'lg'] } }
-```
-
-**Constraints:**
-- **Text options**: max 3 options (beyond 3, text labels overflow in compact layouts)
-- **Icon-only options**: max 5 options (icons are more compact)
-- When the option count exceeds these limits, fall back to Select automatically
-
-### MultiSelect for Array Values
-
-When the value is an array and `options` is present in the layout, render a MultiSelect component instead of a single-value Select:
-
-```js
-// Schema: tags is an array
-{ tags: { type: 'array', items: { type: 'string' } } }
-
-// Layout: options provided → MultiSelect
-{ scope: '#/tags', label: 'Tags', props: { options: ['bug', 'feature', 'docs'] } }
-```
-
-### Connected/Dependent Props
-
-Support cascading dependencies between fields — changing one field's value updates another field's options. For example, selecting a country updates the available cities:
-
-```js
-const lookups = {
-  city: {
-    dependsOn: 'country',
-    fetch: async (country) => getCitiesForCountry(country)
-  }
-}
-
-const builder = new FormBuilder(data, schema, layout, lookups)
-await builder.initializeLookups()
-```
+---
 
-The `FormBuilder` already has `lookupManager` infrastructure for this pattern. The remaining work is:
-- Auto-wiring lookup state (options, loading) into element props
-- UI indicators for loading state on dependent fields
-- Debouncing rapid changes to parent fields
+Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.

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

@@ -157,6 +157,13 @@ export class FormBuilder {
      * @returns {Object} Validation results keyed by field path
      */
     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 {Object} Filtered data containing only visible field keys
+     */
+    getVisibleData(): Object;
     /**
      * Whether all fields pass validation (no error-state messages)
      * @returns {boolean}

package/dist/src/lib/conditions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Evaluate a showWhen condition against current form data.
+ * Returns true if the field should be shown (condition met or absent).
+ *
+ * @param {{ field: string, equals?: unknown, notEquals?: unknown } | null | undefined} condition
+ * @param {Record<string, unknown>} data - Top-level form data object
+ * @returns {boolean}
+ */
+export function evaluateCondition(condition: {
+    field: string;
+    equals?: unknown;
+    notEquals?: unknown;
+} | null | undefined, data: Record<string, unknown>): boolean;

package/dist/src/lib/conditions.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/index.d.ts

@@ -1,4 +1,5 @@
 export { FormBuilder } from "./builder.svelte.js";
+export { evaluateCondition } from "./conditions.js";
 export { default as FormRenderer } from "./FormRenderer.svelte";
 export { default as Input } from "./Input.svelte";
 export * from "./schema.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/forms",
-  "version": "1.0.0-next.132",
+  "version": "1.0.0-next.134",
   "module": "src/index.js",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -9,14 +9,17 @@
     "access": "public"
   },
   "scripts": {
-    "prepublishOnly": "tsc --project tsconfig.build.json",
+    "prepublishOnly": "cp ../../LICENSE . && tsc --project tsconfig.build.json",
+    "postpublish": "rm -f LICENSE",
     "clean": "rm -rf dist",
     "build": "bun clean && bun prepublishOnly"
   },
   "files": [
     "src/**/*.js",
     "src/**/*.svelte",
-    "dist/**/*.d.ts"
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
   ],
   "exports": {
     "./src": "./src",

package/src/FormRenderer.svelte

@@ -163,7 +163,7 @@
 		// Submit
 		submitting = true
 		try {
-			await onsubmit(data, { isValid: true, errors: [] })
+			await onsubmit(formBuilder.getVisibleData(), { isValid: true, errors: [] })
 			formBuilder.snapshot()
 		} catch {
 			// Consumer handles errors in their onsubmit callback
@@ -193,11 +193,24 @@
 			{@render renderElement(element)}
 		{/each}
 		{#if actions}
-			{@render actions({ submitting, isValid: formBuilder.isValid, isDirty: formBuilder.isDirty, submit: handleSubmit, reset: handleReset })}
+			{@render actions({
+				submitting,
+				isValid: formBuilder.isValid,
+				isDirty: formBuilder.isDirty,
+				submit: handleSubmit,
+				reset: handleReset
+			})}
 		{:else}
 			<div data-form-actions>
-				<button type="button" data-form-reset disabled={!formBuilder.isDirty || submitting} onclick={handleReset}>Reset</button>
-				<button type="submit" data-form-submit disabled={!formBuilder.isDirty || submitting}>Submit</button>
+				<button
+					type="button"
+					data-form-reset
+					disabled={!formBuilder.isDirty || submitting}
+					onclick={handleReset}>Reset</button
+				>
+				<button type="submit" data-form-submit disabled={!formBuilder.isDirty || submitting}
+					>Submit</button
+				>
 			</div>
 		{/if}
 	</form>

package/src/InfoField.svelte

@@ -1,11 +1,5 @@
 <script>
-	let {
-		class: className,
-		name,
-		value,
-		label,
-		description
-	} = $props()
+	let { class: className, name, value, label, description } = $props()
 </script>
 
 <div

package/src/ValidationReport.svelte

@@ -8,11 +8,7 @@
 	const SEVERITY_ORDER = ['error', 'warning', 'info', 'success']
 	const SEVERITY_LABELS = { error: 'error', warning: 'warning', info: 'info', success: 'success' }
 
-	let {
-		items = [],
-		onclick = undefined,
-		class: className = ''
-	} = $props()
+	let { items = [], onclick = undefined, class: className = '' } = $props()
 
 	const grouped = $derived(
 		SEVERITY_ORDER.map((state) => ({
@@ -28,7 +24,11 @@
 			<div data-validation-group data-severity={group.state}>
 				<div data-validation-group-header>
 					<span data-validation-count>{group.items.length}</span>
-					<span>{group.items.length === 1 ? SEVERITY_LABELS[group.state] : `${SEVERITY_LABELS[group.state]}s`}</span>
+					<span
+						>{group.items.length === 1
+							? SEVERITY_LABELS[group.state]
+							: `${SEVERITY_LABELS[group.state]}s`}</span
+					>
 				</div>
 				{#each group.items as item (item.path)}
 					{#if onclick}

package/src/display/DisplayCardGrid.svelte

@@ -5,14 +5,7 @@
 	 */
 	import DisplayValue from './DisplayValue.svelte'
 
-	let {
-		data = [],
-		fields = [],
-		select,
-		title,
-		onselect,
-		class: className = ''
-	} = $props()
+	let { data = [], fields = [], select, title, onselect, class: className = '' } = $props()
 
 	let selectedIndex = $state(-1)
 	let selectedIndices = $state(new Set())

package/src/display/DisplayList.svelte

@@ -4,12 +4,7 @@
 	 */
 	import DisplayValue from './DisplayValue.svelte'
 
-	let {
-		data = [],
-		fields = [],
-		title,
-		class: className = ''
-	} = $props()
+	let { data = [], fields = [], title, class: className = '' } = $props()
 </script>
 
 <div data-display-list class={className}>

package/src/display/DisplayTable.svelte

@@ -5,14 +5,7 @@
 	 */
 	import { Table } from '@rokkit/ui'
 
-	let {
-		data = [],
-		columns = [],
-		select,
-		title,
-		onselect,
-		class: className = ''
-	} = $props()
+	let { data = [], columns = [], select, title, onselect, class: className = '' } = $props()
 
 	// Map display columns → Table columns with formatters
 	const tableColumns = $derived(

package/src/input/ArrayEditor.svelte

@@ -35,13 +35,18 @@
 	)
 
 	function typeDefault(type) {
-		return { string: '', number: 0, integer: 0, boolean: false, array: [], object: {} }[type] ?? null
+		return (
+			{ string: '', number: 0, integer: 0, boolean: false, array: [], object: {} }[type] ?? null
+		)
 	}
 
 	function createDefaultItem(schema) {
 		if (schema.type === 'object') {
 			return Object.fromEntries(
-				Object.entries(schema.properties ?? {}).map(([k, s]) => [k, s.default ?? typeDefault(s.type)])
+				Object.entries(schema.properties ?? {}).map(([k, s]) => [
+					k,
+					s.default ?? typeDefault(s.type)
+				])
 			)
 		}
 		return schema.default ?? typeDefault(schema.type)
@@ -96,8 +101,8 @@
 						type="button"
 						data-array-editor-remove
 						{disabled}
-						onclick={() => removeItem(index)}
-					>Remove</button>
+						onclick={() => removeItem(index)}>Remove</button
+					>
 				{/if}
 			</div>
 		{/each}

package/src/input/InputCheckbox.svelte

@@ -68,6 +68,14 @@
 		{...rest}
 	/>
 	{#if variant !== 'default'}
-		<span class={icon} data-checkbox-icon role="button" tabindex="0" onclick={toggle} onkeydown={(e) => (e.key === 'Enter' || e.key === ' ') && toggle()} aria-hidden="true"></span>
+		<span
+			class={icon}
+			data-checkbox-icon
+			role="button"
+			tabindex="0"
+			onclick={toggle}
+			onkeydown={(e) => (e.key === 'Enter' || e.key === ' ') && toggle()}
+			aria-hidden="true"
+		></span>
 	{/if}
 </div>

package/src/input/InputSelect.svelte

@@ -25,7 +25,9 @@
 	} = $props()
 
 	// Check if options include an empty string (used as "none" option)
-	const hasEmptyOption = $derived(options.some((opt) => opt === '' || (typeof opt === 'object' && opt?.value === '')))
+	const hasEmptyOption = $derived(
+		options.some((opt) => opt === '' || (typeof opt === 'object' && opt?.value === ''))
+	)
 
 	// Filter out empty strings — Select + ProxyItem handles string options natively
 	const filteredOptions = $derived(
@@ -35,7 +37,7 @@
 	)
 
 	// Use placeholder for empty option, or provide a default clear label
-	const effectivePlaceholder = $derived(hasEmptyOption ? (placeholder || 'None') : placeholder)
+	const effectivePlaceholder = $derived(hasEmptyOption ? placeholder || 'None' : placeholder)
 </script>
 
 <Select

package/src/lib/builder.svelte.js

@@ -2,7 +2,11 @@ import { deriveSchemaFromValue } from './schema.js'
 import { deriveLayoutFromValue } from './layout.js'
 import { getSchemaWithLayout } from './fields.js'
 import { createLookupManager } from './lookup.svelte.js'
-import { validateField as validateFieldValue, validateAll as validateAllFields } from './validation.js'
+import { evaluateCondition } from './conditions.js'
+import {
+	validateField as validateFieldValue,
+	validateAll as validateAllFields
+} from './validation.js'
 
 /**
  * Deep-clone a plain value (primitives, plain objects, arrays).
@@ -270,6 +274,9 @@ export class FormBuilder {
 			this.#data = updatedData
 		}
 
+		// Clear stale validation errors for fields that are now hidden
+		this.#clearHiddenValidation()
+
 		// Trigger dependent lookups if configured
 		if (triggerLookups && this.#lookupManager) {
 			// Clear dependent field values synchronously before lookup re-fetch
@@ -305,6 +312,22 @@ export class FormBuilder {
 		return current
 	}
 
+	/**
+	 * Clear validation errors for fields that are no longer visible
+	 * @private
+	 */
+	#clearHiddenValidation() {
+		const visiblePaths = new Set(
+			this.elements.filter((el) => el.scope).map((el) => el.scope.replace(/^#\//, ''))
+		)
+		const cleaned = Object.fromEntries(
+			Object.entries(this.#validation).filter(([path]) => visiblePaths.has(path))
+		)
+		if (Object.keys(cleaned).length !== Object.keys(this.#validation).length) {
+			this.#validation = cleaned
+		}
+	}
+
 	/**
 	 * Build form elements from schema and layout using getSchemaWithLayout
 	 * @private
@@ -354,6 +377,11 @@ export class FormBuilder {
 						props: separatorProps
 					})
 				} else {
+					// Check showWhen condition before processing scoped field
+					if (layoutEl.showWhen && !evaluateCondition(layoutEl.showWhen, this.#data)) {
+						continue
+					}
+
 					// Extract key from scope
 					const key = layoutEl.scope.replace(/^#\//, '').split('/').pop()
 					const combinedEl = combinedMap.get(key)
@@ -455,8 +483,7 @@ export class FormBuilder {
 			)
 
 			// Group elements have top-level properties (label, etc.) from combineNestedElementsWithSchema
-			const { key: _k, elements: _e, override: _o, props: groupProps, ...topLevelProps } =
-				element
+			const { key: _k, elements: _e, override: _o, props: groupProps, ...topLevelProps } = element
 
 			return {
 				scope,
@@ -593,8 +620,31 @@ export class FormBuilder {
 	 */
 	validate() {
 		const results = validateAllFields(this.#data, this.#schema, this.#layout)
-		this.#validation = results
-		return results
+		const visiblePaths = new Set(
+			this.elements.filter((el) => el.scope).map((el) => el.scope.replace(/^#\//, ''))
+		)
+		const filtered = Object.fromEntries(
+			Object.entries(results).filter(([path]) => visiblePaths.has(path))
+		)
+		this.#validation = filtered
+		return filtered
+	}
+
+	/**
+	 * 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 {Object} Filtered data containing only visible field keys
+	 */
+	getVisibleData() {
+		const visiblePaths = new Set(
+			this.elements
+				.filter((el) => el.scope)
+				.map((el) => el.scope.replace(/^#\//, ''))
+		)
+		return Object.fromEntries(
+			Object.entries(this.#data).filter(([key]) => visiblePaths.has(key))
+		)
 	}
 
 	/**
@@ -696,10 +746,7 @@ export class FormBuilder {
 	 * @param {Set<string>} dirty - Accumulator set
 	 */
 	#collectDirtyFields(current, initial, prefix, dirty) {
-		const allKeys = new Set([
-			...Object.keys(current ?? {}),
-			...Object.keys(initial ?? {})
-		])
+		const allKeys = new Set([...Object.keys(current ?? {}), ...Object.keys(initial ?? {})])
 
 		for (const key of allKeys) {
 			const path = prefix ? `${prefix}/${key}` : key

package/src/lib/conditions.js

@@ -0,0 +1,15 @@
+/**
+ * Evaluate a showWhen condition against current form data.
+ * Returns true if the field should be shown (condition met or absent).
+ *
+ * @param {{ field: string, equals?: unknown, notEquals?: unknown } | null | undefined} condition
+ * @param {Record<string, unknown>} data - Top-level form data object
+ * @returns {boolean}
+ */
+export function evaluateCondition(condition, data) {
+  if (!condition) return true
+  const value = data[condition.field]
+  if ('equals' in condition) return value === condition.equals
+  if ('notEquals' in condition) return value !== condition.notEquals
+  return true
+}

package/src/lib/conditions.spec.js

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { evaluateCondition } from './conditions.js'
+
+describe('evaluateCondition', () => {
+  it('returns true when condition is null', () => {
+    expect(evaluateCondition(null, { accountType: 'personal' })).toBe(true)
+  })
+
+  it('returns true when condition is undefined', () => {
+    expect(evaluateCondition(undefined, { accountType: 'personal' })).toBe(true)
+  })
+
+  it('returns true when neither operator is set', () => {
+    expect(evaluateCondition({ field: 'accountType' }, { accountType: 'business' })).toBe(true)
+  })
+
+  describe('equals operator', () => {
+    it('returns true when value matches', () => {
+      expect(
+        evaluateCondition({ field: 'accountType', equals: 'business' }, { accountType: 'business' })
+      ).toBe(true)
+    })
+
+    it('returns false when value does not match', () => {
+      expect(
+        evaluateCondition({ field: 'accountType', equals: 'business' }, { accountType: 'personal' })
+      ).toBe(false)
+    })
+
+    it('returns false when field is absent (undefined)', () => {
+      expect(evaluateCondition({ field: 'accountType', equals: 'business' }, {})).toBe(false)
+    })
+  })
+
+  describe('notEquals operator', () => {
+    it('returns true when value does not match', () => {
+      expect(
+        evaluateCondition(
+          { field: 'accountType', notEquals: 'business' },
+          { accountType: 'personal' }
+        )
+      ).toBe(true)
+    })
+
+    it('returns false when value matches', () => {
+      expect(
+        evaluateCondition(
+          { field: 'accountType', notEquals: 'business' },
+          { accountType: 'business' }
+        )
+      ).toBe(false)
+    })
+
+    it('returns true when field is absent (undefined !== value)', () => {
+      expect(evaluateCondition({ field: 'accountType', notEquals: 'business' }, {})).toBe(true)
+    })
+  })
+})

package/src/lib/fields.js

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

package/src/lib/index.js

@@ -1,4 +1,5 @@
 export { FormBuilder } from './builder.svelte.js'
+export { evaluateCondition } from './conditions.js'
 export { validateField, validateAll, createMessage, patterns } from './validation.js'
 export { default as FormRenderer } from './FormRenderer.svelte'
 export { default as Input } from './Input.svelte'

package/src/lib/layout.js

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

package/src/lib/schema.js

@@ -9,7 +9,6 @@ import { typeOf } from '@rokkit/data'
 function deriveObjectProperties(data) {
 	const properties = {}
 	for (const [key, value] of Object.entries(data)) {
-		 
 		properties[key] = deriveSchemaFromValue(value)
 	}
 	return properties