@rokkit/forms 1.1.18 → 1.1.19

package/src/FieldLayout.svelte

@@ -1,14 +1,38 @@
-<script>
-	import { getContext } from 'svelte'
+<script lang="ts">
+	import { getContext, type Component } from 'svelte'
 	import { omit } from 'ramda'
-	import InputField from './input/InputField.svelte'
+	import InputField from './InputField.svelte'
 	import FieldLayout from './FieldLayout.svelte'
 
-	const registry = getContext('registry')
+	type Registry = {
+		wrappers: Record<string, Component<Record<string, unknown>>>
+		components: Record<string, Component<Record<string, unknown>>>
+	}
 
-	let { value = $bindable({}), schema = {}, path = [], onchange } = $props()
+	type LayoutSchema = {
+		wrapper?: string
+		key?: string
+		component?: string
+		elements?: LayoutSchema[]
+		props?: Record<string, unknown>
+		[key: string]: unknown
+	}
 
-	let Wrapper = registry.wrappers[schema.wrapper] ?? registry.wrappers.default
+	/** Recursive field-value tree: each node is itself an indexable record of nodes. */
+	type FieldTree = { [key: string]: FieldTree }
+
+	type Props = {
+		value?: FieldTree
+		schema?: LayoutSchema
+		path?: string[]
+		onchange?: (value: unknown) => void
+	}
+
+	const registry = getContext<Registry>('registry')
+
+	let { value = $bindable({}), schema = {}, path = [], onchange }: Props = $props()
+
+	let Wrapper = registry.wrappers[schema.wrapper ?? ''] ?? registry.wrappers.default
 	let wrapperProps = omit(['wrapper', 'elements', 'key'], schema)
 </script>
 
@@ -34,7 +58,11 @@
 				<Component {...item.props} value={item.key ? value[item.key] : null} />
 			{:else}
 				{@const name = elementPath.join('.')}
-				<InputField {name} bind:value={value[item.key]} {...item.props} {onchange} />
+				{#if item.key}
+					<InputField {name} bind:value={value[item.key]} {...item.props} {onchange} />
+				{:else}
+					<InputField {name} {...item.props} {onchange} />
+				{/if}
 			{/if}
 		{/each}
 	</Wrapper>

package/src/FormRenderer.svelte

@@ -1,20 +1,71 @@
-<script>
+<script lang="ts">
 	/**
 	 * FormRenderer component with snippet-based rendering
 	 * Handles defaultInput, info, separator, display components, and custom child snippet selection.
 	 * Supports form submission with validate-before-submit, loading state, and optional action buttons.
 	 */
 
-	import { onMount, untrack } from 'svelte'
+	import { onMount, untrack, type Snippet, type Component } from 'svelte'
 	import InputField from './InputField.svelte'
 	import InfoField from './InfoField.svelte'
 	import { FormBuilder } from './lib/builder.svelte.js'
+	import type { LookupConfig } from './lib/lookup.svelte.js'
 	import { defaultRenderers } from './lib/renderers.js'
 	import DisplayTable from './display/DisplayTable.svelte'
 	import DisplayCardGrid from './display/DisplayCardGrid.svelte'
 	import DisplaySection from './display/DisplaySection.svelte'
 	import DisplayList from './display/DisplayList.svelte'
 
+	/** A single element produced by FormBuilder.elements. */
+	type FormElement = {
+		scope?: string
+		type?: string
+		value?: unknown
+		override?: boolean
+		props?: Record<string, unknown> & {
+			elements?: FormElement[]
+		}
+	}
+
+	type ValidateMode = 'blur' | 'change' | 'manual'
+
+	type ExternalValidation = { state?: string; text?: string } | null | undefined
+
+	type ActionsContext = {
+		submitting: boolean
+		isValid: boolean
+		isDirty: boolean
+		submit: (e: Event) => void | Promise<void>
+		reset: () => void
+	}
+
+	type Props = {
+		/** Optional external builder instance */
+		builder?: FormBuilder
+		/** Direct data prop (alternative to builder) */
+		data?: Record<string, unknown>
+		schema?: Record<string, unknown> | null
+		layout?: Record<string, unknown> | null
+		/** Lookup configurations */
+		lookups?: Record<string, LookupConfig>
+		/** Validation mode */
+		validateOn?: ValidateMode
+		/** Custom type renderers (merged with defaults) */
+		renderers?: Record<string, Component<Record<string, unknown>>>
+		onupdate?: (data: Record<string, unknown>) => void
+		onvalidate?: (fieldPath: string, value: unknown, event: string) => ExternalValidation
+		onselect?: (selected: unknown, item: unknown) => void
+		onsubmit?: (
+			data: Record<string, unknown>,
+			meta: { isValid: boolean; errors: unknown[] }
+		) => void | Promise<void>
+		/** Custom actions snippet */
+		actions?: Snippet<[ActionsContext]>
+		className?: string
+		/** Custom snippet rendered when an element opts into an override */
+		child?: Snippet<[FormElement]>
+	} & Record<string, unknown>
+
 	let {
 		// Optional external builder instance
 		builder = undefined,
@@ -50,7 +101,7 @@
 
 		// Pass through any other props
 		...props
-	} = $props()
+	}: Props = $props()
 
 	// Merged renderer registry
 	const allRenderers = $derived({ ...defaultRenderers, ...renderers })
@@ -68,7 +119,7 @@
 	// Sync external data prop changes to builder (effect only tracks `data`, not formBuilder.data,
 	// to avoid a proxy-vs-raw-value comparison loop)
 	$effect(() => {
-		formBuilder.data = data
+		if (data !== undefined) formBuilder.data = data
 	})
 
 	$effect(() => {
@@ -80,7 +131,7 @@
 	})
 
 	// Apply external validation result for a field path
-	function applyExternalValidation(fieldPath, value, event) {
+	function applyExternalValidation(fieldPath: string, value: unknown, event: string) {
 		if (!onvalidate) return
 		const result = onvalidate(fieldPath, value, event)
 		if (result && typeof result === 'object' && result.state) {
@@ -89,8 +140,8 @@
 	}
 
 	// Handle field value changes
-	function handleFieldChange(element, newValue) {
-		const fieldPath = element.scope.replace(/^#\//, '')
+	function handleFieldChange(element: FormElement, newValue: unknown) {
+		const fieldPath = (element.scope ?? '').replace(/^#\//, '')
 		formBuilder.updateField(fieldPath, newValue)
 		data = formBuilder.data
 		if (onupdate) onupdate(data)
@@ -99,8 +150,8 @@
 	}
 
 	// Handle blur events for validation
-	function handleFieldBlur(element) {
-		const fieldPath = element.scope.replace(/^#\//, '')
+	function handleFieldBlur(element: FormElement) {
+		const fieldPath = (element.scope ?? '').replace(/^#\//, '')
 		const currentValue = formBuilder.getValue(fieldPath)
 		if (validateOn === 'blur') formBuilder.validateField(fieldPath)
 		applyExternalValidation(fieldPath, currentValue, 'blur')
@@ -108,20 +159,20 @@
 
 	// Submission state
 	let submitting = $state(false)
-	let formRoot = $state(null)
+	let formRoot = $state<HTMLElement | null>(null)
 
 	// Focus the first invalid field in the form
 	function focusFirstError() {
 		const firstError = formBuilder.errors[0]
 		if (!firstError || !formRoot) return
-		const field = formRoot.querySelector(
+		const field = formRoot.querySelector<HTMLElement>(
 			`[data-scope="#/${firstError.path}"] input, [data-scope="#/${firstError.path}"] select, [data-scope="#/${firstError.path}"] textarea`
 		)
 		field?.focus?.()
 	}
 
 	// Handle form submission: validate → focus first error → call onsubmit → snapshot
-	async function handleSubmit(e) {
+	async function handleSubmit(e: Event) {
 		e.preventDefault()
 		if (submitting || !onsubmit) return
 
@@ -149,6 +200,23 @@
 		formBuilder.reset()
 		data = formBuilder.data
 	}
+
+	// Narrow a dynamic display value into an array of records for list/table/card displays
+	function toRecordArray(value: unknown): Array<Record<string, unknown>> {
+		return Array.isArray(value) ? (value.filter((v) => v !== null && typeof v === 'object') as Array<Record<string, unknown>>) : []
+	}
+
+	// Narrow a dynamic display value into a record for section displays
+	function toRecord(value: unknown): Record<string, unknown> {
+		return value !== null && typeof value === 'object' && !Array.isArray(value)
+			? (value as Record<string, unknown>)
+			: {}
+	}
+
+	// Narrow a dynamic prop value into a display string
+	function asText(value: unknown): string | undefined {
+		return typeof value === 'string' ? value : undefined
+	}
 </script>
 
 <!-- Form container: <form> when onsubmit provided, <div> otherwise -->
@@ -229,7 +297,7 @@
 {/if}
 
 <!-- Render a single element by type -->
-{#snippet renderElement(element)}
+{#snippet renderElement(element: FormElement)}
 	{#if element.type === 'separator'}
 		<div data-form-separator></div>
 	{:else if element.type === 'group'}
@@ -242,20 +310,20 @@
 			{/each}
 		</fieldset>
 	{:else if element.type === 'display-table'}
-		<DisplayTable data={element.value} {...element.props} {onselect} />
+		<DisplayTable data={toRecordArray(element.value)} {...element.props} {onselect} />
 	{:else if element.type === 'display-cards'}
-		<DisplayCardGrid data={element.value} {...element.props} {onselect} />
+		<DisplayCardGrid data={toRecordArray(element.value)} {...element.props} {onselect} />
 	{:else if element.type === 'display-section'}
-		<DisplaySection data={element.value} {...element.props} />
+		<DisplaySection data={toRecord(element.value)} {...element.props} />
 	{:else if element.type === 'display-list'}
-		<DisplayList data={element.value} {...element.props} />
+		<DisplayList data={toRecordArray(element.value)} {...element.props} />
 	{:else if element.type === 'info'}
 		<div data-form-field data-scope={element.scope}>
 			<InfoField
 				name={element.scope}
 				value={element.value}
-				label={element.props?.label}
-				description={element.props?.description}
+				label={asText(element.props?.label)}
+				description={asText(element.props?.description)}
 			/>
 		</div>
 	{:else if element.override && child}

package/src/InfoField.svelte

@@ -1,5 +1,13 @@
-<script>
-	let { class: className, name, value, label, description } = $props()
+<script lang="ts">
+	type Props = {
+		class?: string
+		name?: string
+		value?: unknown
+		label?: string
+		description?: string
+	}
+
+	let { class: className, name, value, label, description }: Props = $props()
 </script>
 
 <div

package/src/Input.svelte

@@ -1,5 +1,17 @@
-<script>
+<script lang="ts">
 	import { defaultRenderers, resolveRenderer } from './lib/renderers.js'
+	import type { Component } from 'svelte'
+
+	type Props = {
+		type?: string
+		value?: unknown
+		onchange?: ((value: unknown) => void) | null
+		oninput?: ((value: unknown) => void) | null
+		onfocus?: ((event: FocusEvent) => void) | null
+		onblur?: ((event: FocusEvent) => void) | null
+		icon?: string | null
+		renderers?: Record<string, Component<Record<string, unknown>>>
+	} & Record<string, unknown>
 
 	let {
 		type = 'text',
@@ -11,7 +23,7 @@
 		icon = null,
 		renderers = {},
 		...restProps
-	} = $props()
+	}: Props = $props()
 
 	const allRenderers = $derived({ ...defaultRenderers, ...renderers })
 	const extraProps = $derived(type === 'integer' ? { step: '1' } : {})

package/src/InputField.svelte

@@ -1,5 +1,38 @@
-<script>
+<script lang="ts">
 	import Input from './Input.svelte'
+	import type { Component } from 'svelte'
+
+	type FieldMessage = { state?: string; text?: string }
+
+	type Props = {
+		class?: string
+		name?: string
+		value?: unknown
+		type?: string
+		required?: boolean
+		status?: string
+		disabled?: boolean
+		dirty?: boolean
+		message?: FieldMessage | string
+		nolabel?: boolean
+		icon?: string
+		label?: string
+		description?: string
+		onchange?: (value: unknown) => void
+		onblur?: () => void
+		id?: string
+		renderers?: Record<string, Component<Record<string, unknown>>>
+		/**
+		 * Field layout — controls how the label and input are arranged.
+		 *
+		 * - `stacked` (default) — label above input. Best for form pages
+		 *   with full-width inputs and long labels.
+		 * - `inline` — label and input on the same row (label takes a
+		 *   fixed leading column). Best for compact control panels —
+		 *   playground knob rows, settings dialogs, tweak editors.
+		 */
+		variant?: 'stacked' | 'inline'
+	} & Record<string, unknown>
 
 	let {
 		class: className,
@@ -18,18 +51,9 @@
 		onchange,
 		id,
 		renderers,
-		/**
-		 * Field layout — controls how the label and input are arranged.
-		 *
-		 * - `stacked` (default) — label above input. Best for form pages
-		 *   with full-width inputs and long labels.
-		 * - `inline` — label and input on the same row (label takes a
-		 *   fixed leading column). Best for compact control panels —
-		 *   playground knob rows, settings dialogs, tweak editors.
-		 */
 		variant = 'stacked',
 		...restProps
-	} = $props()
+	}: Props = $props()
 
 	let rootProps = $derived(id !== null && id !== undefined ? { id } : {})
 	let properties = $derived({
@@ -38,13 +62,16 @@
 		...restProps,
 		name
 	})
+
+	let messageState = $derived(typeof message === 'object' ? message?.state : undefined)
+	let messageText = $derived(typeof message === 'object' ? message?.text : message)
 </script>
 
 <div
 	data-field-root
 	{...rootProps}
 	class={className}
-	data-field-state={status ?? message?.state}
+	data-field-state={status ?? messageState}
 	data-field-type={type}
 	data-field-required={required}
 	data-field-disabled={disabled}
@@ -63,8 +90,8 @@
 		<div data-description>{description}</div>
 	{/if}
 	{#if message}
-		<div data-message data-message-state={message?.state ?? 'info'}>
-			{message?.text ?? message}
+		<div data-message data-message-state={messageState ?? 'info'}>
+			{messageText}
 		</div>
 	{/if}
 </div>

package/src/StatusList.svelte

@@ -1,14 +1,33 @@
-<script>
+<script lang="ts">
 	/**
 	 * StatusList — grouped summary of validation messages
 	 * Groups items by severity (error, warning, info, success) with count headers.
 	 * Supports click-to-focus via onclick callback.
 	 */
 
-	const SEVERITY_ORDER = ['error', 'warning', 'info', 'success']
-	const SEVERITY_LABELS = { error: 'error', warning: 'warning', info: 'info', success: 'success' }
+	type Severity = 'error' | 'warning' | 'info' | 'success'
 
-	let { items = [], onclick = undefined, class: className = '' } = $props()
+	type StatusItem = {
+		state: Severity
+		path: string
+		text: string
+	}
+
+	type Props = {
+		items?: StatusItem[]
+		onclick?: (path: string) => void
+		class?: string
+	}
+
+	const SEVERITY_ORDER: Severity[] = ['error', 'warning', 'info', 'success']
+	const SEVERITY_LABELS: Record<Severity, string> = {
+		error: 'error',
+		warning: 'warning',
+		info: 'info',
+		success: 'success'
+	}
+
+	let { items = [], onclick = undefined, class: className = '' }: Props = $props()
 
 	const grouped = $derived(
 		SEVERITY_ORDER.map((state) => ({

package/src/StepIndicator.svelte

@@ -1,22 +1,24 @@
-<script>
+<script lang="ts">
 	/**
 	 * StepIndicator — standalone presentational component showing multi-step form progress.
 	 * Place anywhere on the page; wire to FormBuilder.currentStep and FormBuilder.goToStep.
 	 */
 
-	let {
-		steps = [],
-		current = 0,
-		onclick = undefined
-	} = $props()
+	type Props = {
+		steps?: string[]
+		current?: number
+		onclick?: (index: number) => void
+	}
+
+	let { steps = [], current = 0, onclick = undefined }: Props = $props()
 
-	function stepState(index) {
+	function stepState(index: number): 'complete' | 'current' | 'upcoming' {
 		if (index < current) return 'complete'
 		if (index === current) return 'current'
 		return 'upcoming'
 	}
 
-	function handleClick(index) {
+	function handleClick(index: number) {
 		if (index < current) onclick?.(index)
 	}
 </script>

package/src/display/DisplayCardGrid.svelte

@@ -1,4 +1,4 @@
-<script>
+<script lang="ts">
 	/**
 	 * Renders an array of objects as a responsive card grid.
 	 * Each card displays fields with formatted values.
@@ -6,17 +6,34 @@
 	import DisplayValue from './DisplayValue.svelte'
 	import { SvelteSet } from 'svelte/reactivity'
 
-	let { data = [], fields = [], select, title, onselect, class: className = '' } = $props()
+	type DisplayField = {
+		key: string
+		label?: string
+		format?: string
+	}
+
+	type DisplayItem = Record<string, unknown>
+
+	type Props = {
+		data?: DisplayItem[]
+		fields?: DisplayField[]
+		select?: 'one' | 'many'
+		title?: string
+		onselect?: (selected: DisplayItem | DisplayItem[], item: DisplayItem) => void
+		class?: string
+	}
+
+	let { data = [], fields = [], select, title, onselect, class: className = '' }: Props = $props()
 
 	let selectedIndex = $state(-1)
-	let selectedIndices = new SvelteSet()
+	let selectedIndices = new SvelteSet<number>()
 
-	function selectOne(item, index) {
+	function selectOne(item: DisplayItem, index: number) {
 		selectedIndex = index
 		onselect?.(item, item)
 	}
 
-	function selectMany(item, index) {
+	function selectMany(item: DisplayItem, index: number) {
 		const next = new SvelteSet(selectedIndices)
 		if (next.has(index)) {
 			next.delete(index)
@@ -28,13 +45,13 @@
 		onselect?.(selected, item)
 	}
 
-	function handleCardClick(item, index) {
+	function handleCardClick(item: DisplayItem, index: number) {
 		if (!select) return
 		if (select === 'one') selectOne(item, index)
 		else if (select === 'many') selectMany(item, index)
 	}
 
-	function isSelected(index) {
+	function isSelected(index: number) {
 		if (select === 'one') return selectedIndex === index
 		if (select === 'many') return selectedIndices.has(index)
 		return false

package/src/display/DisplayList.svelte

@@ -1,10 +1,23 @@
-<script>
+<script lang="ts">
 	/**
 	 * Renders an array of objects as a styled list.
 	 */
 	import DisplayValue from './DisplayValue.svelte'
 
-	let { data = [], fields = [], title, class: className = '' } = $props()
+	type DisplayField = {
+		key: string
+		label?: string
+		format?: string
+	}
+
+	type Props = {
+		data?: Array<Record<string, unknown>>
+		fields?: DisplayField[]
+		title?: string
+		class?: string
+	}
+
+	let { data = [], fields = [], title, class: className = '' }: Props = $props()
 </script>
 
 <div data-display-list class={className}>

package/src/display/DisplaySection.svelte

@@ -1,10 +1,22 @@
-<script>
+<script lang="ts">
 	/**
 	 * Renders an object as key-value pairs (detail/summary view).
 	 */
 	import DisplayValue from './DisplayValue.svelte'
 
-	let { data = {}, fields = [], title } = $props()
+	type DisplayField = {
+		key: string
+		label?: string
+		format?: string
+	}
+
+	type Props = {
+		data?: Record<string, unknown>
+		fields?: DisplayField[]
+		title?: string
+	}
+
+	let { data = {}, fields = [], title }: Props = $props()
 </script>
 
 <div data-display-section>

package/src/display/DisplayTable.svelte

@@ -1,14 +1,33 @@
-<script>
+<script lang="ts">
 	/**
 	 * Wraps @rokkit/ui Table for display-only rendering from layout schema.
 	 * Maps display columns (key/label/format) to TableColumn format.
 	 */
 	import { Table } from '@rokkit/ui'
+	import type { TableColumn } from '@rokkit/ui'
 
-	let { data = [], columns = [], select, title, onselect, class: className = '' } = $props()
+	type DisplayColumn = {
+		key: string
+		label?: string
+		sortable?: boolean
+		width?: string
+		align?: 'left' | 'center' | 'right'
+		format?: string
+	}
+
+	type Props = {
+		data?: Array<Record<string, unknown>>
+		columns?: DisplayColumn[]
+		select?: 'one' | 'many'
+		title?: string
+		onselect?: (value: unknown, row: Record<string, unknown>) => void
+		class?: string
+	}
+
+	let { data = [], columns = [], select, title, onselect, class: className = '' }: Props = $props()
 
 	// Map display columns → Table columns with formatters
-	const tableColumns = $derived(
+	const tableColumns = $derived<TableColumn[]>(
 		columns.map((col) => ({
 			name: col.key,
 			label: col.label ?? col.key,
@@ -19,7 +38,7 @@
 		}))
 	)
 
-	function formatDuration(minutes) {
+	function formatDuration(minutes: number): string {
 		const h = Math.floor(minutes / 60)
 		const m = minutes % 60
 		if (h > 0 && m > 0) return `${h}h ${m}m`
@@ -27,23 +46,27 @@
 		return `${m}m`
 	}
 
-	const formatters = {
+	function toDate(v: unknown): Date {
+		if (v instanceof Date) return v
+		if (typeof v === 'number') return new Date(v)
+		return new Date(String(v))
+	}
+
+	const formatters: Record<string, (v: unknown) => string> = {
 		currency: (v) =>
-			new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(v),
-		datetime: (v) => new Date(v).toLocaleString(),
-		duration: (v) => formatDuration(v),
-		number: (v) => new Intl.NumberFormat().format(v),
+			new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(Number(v)),
+		datetime: (v) => toDate(v).toLocaleString(),
+		duration: (v) => formatDuration(Number(v)),
+		number: (v) => new Intl.NumberFormat().format(Number(v)),
 		boolean: (v) => (v ? '✓' : '✗')
 	}
 
 	/**
 	 * Create a cell formatter function for a given display format.
-	 * @param {string} format
-	 * @returns {(value: unknown) => string}
 	 */
-	function createFormatter(format) {
+	function createFormatter(format: string): (value: unknown) => string {
 		const fn = formatters[format] ?? String
-		return (value) => {
+		return (value: unknown) => {
 			if (value === null || value === undefined) return '—'
 			return fn(value)
 		}