@rokkit/forms 1.0.0-next.124 → 1.0.0-next.127

package/README.md

@@ -0,0 +1,251 @@
+# @rokkit/forms
+
+Schema-driven form rendering for Svelte 5. Generate dynamic forms from data, schema, and layout definitions.
+
+## Installation
+
+```bash
+bun add @rokkit/forms
+```
+
+## Core Concepts
+
+### FormBuilder
+
+Takes `(data, schema, layout)` and produces a reactive `elements[]` array. Each element describes a form field with its type, current value, and merged properties.
+
+```js
+import { FormBuilder } from '@rokkit/forms'
+
+const builder = new FormBuilder(
+  { name: 'Alice', age: 30 },     // data
+  schema,                           // optional — auto-derived from data
+  layout                            // optional — auto-derived from data
+)
+
+// builder.elements → [{ scope, type, value, props }, ...]
+```
+
+If `schema` is `null`, it is auto-derived from the data using `deriveSchemaFromValue()`. If `layout` is `null`, it is auto-derived using `deriveLayoutFromValue()`.
+
+### Schema
+
+JSON-Schema-like type definitions. Supports: `string`, `number`, `integer`, `boolean`, `array`, `object`, `date`.
+
+```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' }
+  }
+}
+```
+
+### Layout
+
+Controls rendering order, grouping, labels, and component-specific props. Uses JSON Pointer scopes (`#/fieldName`).
+
+```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 }
+  ]
+}
+```
+
+### Type Resolution
+
+The FormBuilder determines input type from the schema:
+
+| 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` |
+
+### Layout Props
+
+The `props` field in layout elements passes component-specific configuration:
+
+```js
+// Select with string options
+{ scope: '#/size', props: { options: ['sm', 'md', 'lg'] } }
+
+// Select with object options and field mapping
+{ scope: '#/color', props: {
+  options: [{ name: 'Red', hex: '#f00' }, { name: 'Blue', hex: '#00f' }],
+  fields: { text: 'name', value: 'hex' }
+}}
+
+// Readonly info display
+{ scope: '#/total', readonly: true }
+
+// Separator (no scope)
+{ type: 'separator' }
+```
+
+## Components
+
+### FormRenderer
+
+Renders a complete form from data + schema + layout:
+
+```svelte
+<script>
+  import { FormRenderer } from '@rokkit/forms'
+
+  let data = $state({ name: '', size: 'md', active: true })
+</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} />
+  {/snippet}
+</FormRenderer>
+```
+
+Set `override: true` on layout elements to route them to the `child` snippet.
+
+### InputField
+
+Wraps an input with label, description, and validation message:
+
+```svelte
+<InputField name="email" type="email" value={email} label="Email" onchange={handleChange} />
+```
+
+### 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:
+
+```svelte
+<InfoField label="Total" value={42} />
+```
+
+## Lib Utilities
+
+```js
+import { getSchemaWithLayout, findAttributeByPath } from '@rokkit/forms'
+import { deriveSchemaFromValue } from '@rokkit/forms/lib'
+import { deriveLayoutFromValue } from '@rokkit/forms/lib'
+```
+
+- `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
+
+For fields with a small number of options, a Toggle (radio-style button group) can replace Select for better UX:
+
+```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

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

@@ -0,0 +1,5 @@
+export { default as DisplayValue } from "./DisplayValue.svelte";
+export { default as DisplaySection } from "./DisplaySection.svelte";
+export { default as DisplayTable } from "./DisplayTable.svelte";
+export { default as DisplayCardGrid } from "./DisplayCardGrid.svelte";
+export { default as DisplayList } from "./DisplayList.svelte";

package/dist/src/index.d.ts

@@ -1,5 +1,14 @@
 export { FormBuilder } from "./lib/builder.svelte.js";
+export { deriveSchemaFromValue } from "./lib/schema.js";
+export { deriveLayoutFromValue } from "./lib/layout.js";
 export { default as FormRenderer } from "./FormRenderer.svelte";
 export { default as Input } from "./Input.svelte";
 export { default as InputField } from "./InputField.svelte";
+export { default as InfoField } from "./InfoField.svelte";
+export { default as ValidationReport } from "./ValidationReport.svelte";
+export * from "./display";
 export * from "./input";
+export { createLookup, createLookupManager, clearLookupCache } from "./lib/lookup.svelte.js";
+export { validateField, validateAll, createMessage, patterns } from "./lib/validation.js";
+export { defaultRenderers, resolveRenderer } from "./lib/renderers.js";
+export { getSchemaWithLayout, findAttributeByPath } from "./lib/fields.js";

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

@@ -1,3 +1,4 @@
+export { default as ArrayEditor } from "./ArrayEditor.svelte";
 export { default as InputCheckbox } from "./InputCheckbox.svelte";
 export { default as InputColor } from "./InputColor.svelte";
 export { default as InputDate } from "./InputDate.svelte";
@@ -10,9 +11,11 @@ export { default as InputPassword } from "./InputPassword.svelte";
 export { default as InputRadio } from "./InputRadio.svelte";
 export { default as InputRange } from "./InputRange.svelte";
 export { default as InputSelect } from "./InputSelect.svelte";
+export { default as InputSwitch } from "./InputSwitch.svelte";
 export { default as InputTel } from "./InputTel.svelte";
 export { default as InputText } from "./InputText.svelte";
 export { default as InputTextArea } from "./InputTextArea.svelte";
 export { default as InputTime } from "./InputTime.svelte";
+export { default as InputToggle } from "./InputToggle.svelte";
 export { default as InputUrl } from "./InputUrl.svelte";
 export { default as InputWeek } from "./InputWeek.svelte";

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

@@ -14,6 +14,7 @@
  * @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
  */
 /**
  * FormBuilder class for dynamically generating forms from data structures
@@ -24,11 +25,15 @@ 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?: Object, schema?: Object | null, layout?: Object | null);
+    constructor(data?: Object, schema?: Object | null, layout?: Object | null, lookups?: {
+        [x: string]: import("./lookup.svelte.js").LookupConfig;
+    });
     /** @type {FormElement[]} */
     elements: FormElement[];
-    combined: any;
+    /** Combined schema+layout (scoped elements only) */
+    get combined(): any;
     /**
      * Set the data
      * @param {Object} value - New data object
@@ -69,12 +74,60 @@ export class FormBuilder {
      * @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): void;
+    updateField(path: string, value: any, triggerLookups?: boolean): void;
     /**
      * Get a field value by path
      * @param {string} path - Field path
@@ -94,7 +147,62 @@ export class FormBuilder {
      */
     clearValidation(): void;
     /**
-     * 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: string): import("./validation.js").ValidationMessage | null;
+    /**
+     * Validate all fields, populate validation state
+     * @returns {Object} Validation results keyed by field path
+     */
+    validate(): Object;
+    /**
+     * Whether all fields pass validation (no error-state messages)
+     * @returns {boolean}
+     */
+    get isValid(): boolean;
+    /**
+     * Array of current error messages with paths
+     * @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}>}
+     */
+    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;
     #private;
@@ -136,5 +244,7 @@ export type FormElement = {
              */
             text?: string | undefined;
         } | undefined;
+        dirty?: boolean | undefined;
     };
 };
+import { createLookupManager } from './lookup.svelte.js';

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

@@ -0,0 +1,87 @@
+/**
+ * Creates a lookup provider for a field
+ * @param {LookupConfig} config - Lookup configuration
+ * @returns {Object} Lookup provider with reactive state
+ */
+export function createLookup(config: LookupConfig): Object;
+/**
+ * Creates a lookup manager for a form with multiple lookups
+ * @param {Object<string, LookupConfig>} lookupConfigs - Map of field paths to lookup configs
+ * @returns {Object} Lookup manager
+ */
+export function createLookupManager(lookupConfigs: {
+    [x: string]: LookupConfig;
+}): Object;
+/**
+ * Clears the entire lookup cache
+ */
+export function clearLookupCache(): void;
+export type LookupConfig = {
+    /**
+     * - URL template with optional placeholders (e.g., '/api/cities?country={country}')
+     */
+    url?: string | undefined;
+    /**
+     * - Async function replacing URL template
+     */
+    fetch?: ((formData: any) => Promise<any[]>) | undefined;
+    /**
+     * - Pre-loaded array for filter pattern
+     */
+    source?: any[] | undefined;
+    /**
+     * - Client-side filter applied to source
+     */
+    filter?: ((items: any[], formData: any) => any[]) | undefined;
+    /**
+     * - Custom cache key for fetch hooks (no caching when absent)
+     */
+    cacheKey?: ((formData: any) => string) | undefined;
+    /**
+     * - Field paths this lookup depends on
+     */
+    dependsOn?: string[] | undefined;
+    /**
+     * - Field mapping for the response data
+     */
+    fields?: Object | undefined;
+    /**
+     * - Cache duration in milliseconds (default: 5 minutes)
+     */
+    cacheTime?: number | undefined;
+    /**
+     * - Transform response data to options array
+     */
+    transform?: ((data: any) => any[]) | undefined;
+};
+export type LookupState = {
+    /**
+     * - Current options
+     */
+    options: any[];
+    /**
+     * - Whether lookup is in progress
+     */
+    loading: boolean;
+    /**
+     * - Error message if lookup failed
+     */
+    error: string | null;
+    /**
+     * - Whether field is disabled (deps not met)
+     */
+    disabled: boolean;
+};
+/**
+ * Cache entry structure
+ */
+export type CacheEntry = {
+    /**
+     * - Cached options
+     */
+    data: any[];
+    /**
+     * - When the cache was created
+     */
+    timestamp: number;
+};

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

@@ -0,0 +1,23 @@
+/**
+ * Resolve a renderer component for a form element.
+ *
+ * Resolution order:
+ * 1. Explicit `renderer` name in element props → custom registry
+ * 2. Element type → registry lookup
+ * 3. Fallback → InputText
+ *
+ * @param {{ type: string, props?: { renderer?: string } }} element
+ * @param {Record<string, import('svelte').Component>} renderers - Merged registry
+ * @returns {import('svelte').Component}
+ */
+export function resolveRenderer(element: {
+    type: string;
+    props?: {
+        renderer?: string;
+    };
+}, renderers: Record<string, import("svelte").Component>): import("svelte").Component;
+/**
+ * Default renderer registry mapping type strings to components.
+ * @type {Record<string, import('svelte').Component>}
+ */
+export const defaultRenderers: Record<string, import("svelte").Component>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/forms",
-  "version": "1.0.0-next.124",
+  "version": "1.0.0-next.127",
   "module": "src/index.js",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -25,14 +25,16 @@
       "types": "./dist/index.d.ts",
       "import": "./src/index.js",
       "svelte": "./src/index.js"
+    },
+    "./lib": {
+      "import": "./src/lib/index.js"
     }
   },
   "dependencies": {
     "@rokkit/core": "latest",
+    "@rokkit/data": "latest",
     "@rokkit/states": "latest",
     "@rokkit/ui": "latest",
-    "@rokkit/bits-ui": "latest",
-    "ramda": "^0.31.3",
-    "valibot": "^1.1.0"
+    "ramda": "^0.32.0"
   }
 }

package/src/FieldLayout.svelte

@@ -4,16 +4,9 @@
 	import InputField from './input/InputField.svelte'
 	import FieldLayout from './FieldLayout.svelte'
 
-	// const dispatch = createEventDispatcher()
 	const registry = getContext('registry')
 
-	export let value = {}
-	export let schema = {}
-	export let path = []
-
-	function handle() {
-		dispatch('change', value)
-	}
+	let { value = $bindable({}), schema = {}, path = [], onchange } = $props()
 
 	let Wrapper = registry.wrappers[schema.wrapper] ?? registry.wrappers.default
 	let wrapperProps = omit(['wrapper', 'elements', 'key'], schema)
@@ -33,15 +26,15 @@
 
 			{#if nested}
 				{#if item.key}
-					<FieldLayout {...props} schema={item} bind:value={value[item.key]} on:change={handle} />
+					<FieldLayout {...props} schema={item} bind:value={value[item.key]} {onchange} />
 				{:else}
-					<FieldLayout {...props} schema={item} bind:value on:change={handle} />
+					<FieldLayout {...props} schema={item} bind:value {onchange} />
 				{/if}
 			{:else if Component}
 				<Component {...item.props} value={item.key ? value[item.key] : null} />
 			{:else}
 				{@const name = elementPath.join('.')}
-				<InputField {name} bind:value={value[item.key]} {...item.props} on:change={handle} />
+				<InputField {name} bind:value={value[item.key]} {...item.props} {onchange} />
 			{/if}
 		{/each}
 	</Wrapper>