@poodle64/ui 2026.8.10 → 2026.8.12

package/dist/components/ui/schema-form/dispatch.js

@@ -0,0 +1,139 @@
+import { WIDGET_KINDS } from './types.js';
+const KNOWN = new Set(WIDGET_KINDS);
+/** The primitive JSON Schema types a `tags` widget can carry as array items. */
+const TAGGABLE = new Set(['string', 'number', 'integer']);
+/** JSON Schema `format` → the input type that renders it. */
+const FORMAT_WIDGETS = {
+    password: 'password',
+    date: 'date',
+    time: 'time',
+    'date-time': 'datetime'
+};
+/** The first `type` a subschema declares (JSON Schema allows an array of them). */
+export function schemaType(schema) {
+    const t = schema?.type;
+    if (Array.isArray(t))
+        return t.find((entry) => entry !== 'null') ?? t[0];
+    return t;
+}
+/** Does this subschema carry a closed set of values a select can list? */
+export function enumOptions(schema) {
+    if (!schema)
+        return null;
+    const withEnum = schema;
+    if (Array.isArray(withEnum.enum)) {
+        return withEnum.enum.map((value) => ({ value, label: String(value) }));
+    }
+    // The `oneOf: [{ const, title }]` spelling — how a server labels its enum.
+    if (Array.isArray(withEnum.oneOf) && withEnum.oneOf.every((entry) => 'const' in entry)) {
+        return withEnum.oneOf.map((entry) => ({
+            value: entry.const,
+            label: entry.title ?? String(entry.const)
+        }));
+    }
+    return null;
+}
+/**
+ * Resolve a Control to a widget.
+ *
+ * @param schema  the subschema the Control's scope resolved to, or `undefined`
+ *                if the scope resolved to nothing at all.
+ * @param options the Control's `options` object from the UI schema.
+ */
+export function pickWidget(schema, options = {}) {
+    // 1. A scope that resolves to nothing is the most fundamental defect there is
+    //    — flag it before anything else, hint or no hint.
+    if (!schema) {
+        return {
+            widget: 'unknown',
+            reason: 'unresolved-scope',
+            detail: 'no such property in the JSON Schema'
+        };
+    }
+    // 2. An explicit hint wins — and an unrecognised one is LOUD, never a default.
+    //    `format` is the JSON Forms spelling; `widget` is accepted because the
+    //    estate's outgoing x-ui vocabulary used it, so a migrating server does
+    //    not have to change both documents at once.
+    const hint = options.format ?? options.widget;
+    if (typeof hint === 'string') {
+        if (KNOWN.has(hint)) {
+            // A select or a radio group over nothing renders as an empty box — which
+            // is the vanishing act this whole component exists to stop, one level
+            // down from an unrecognised hint.
+            if ((hint === 'select' || hint === 'radio') && !enumOptions(schema)?.length) {
+                return {
+                    widget: 'unknown',
+                    reason: 'no-options',
+                    detail: `the "${hint}" widget needs a closed value set, and this subschema declares no enum or oneOf`
+                };
+            }
+            return { widget: hint };
+        }
+        return {
+            widget: 'unknown',
+            reason: 'unknown-widget',
+            detail: `no widget is registered for "${hint}"`
+        };
+    }
+    if (hint !== undefined) {
+        return {
+            widget: 'unknown',
+            reason: 'unknown-widget',
+            detail: `widget hint must be a string, got ${typeof hint}`
+        };
+    }
+    // 3. The two boolean options JSON Forms itself defines.
+    const type = schemaType(schema);
+    if (options.multi === true && type === 'string')
+        return { widget: 'textarea' };
+    if (options.slider === true && (type === 'number' || type === 'integer'))
+        return { widget: 'slider' };
+    // 4. Derive from the schema.
+    const closedSet = enumOptions(schema);
+    if (closedSet) {
+        if (!closedSet.length) {
+            return {
+                widget: 'unknown',
+                reason: 'no-options',
+                detail: 'the subschema declares an empty enum, so there is nothing to choose from'
+            };
+        }
+        return { widget: 'select' };
+    }
+    switch (type) {
+        case 'boolean':
+            return { widget: 'switch' };
+        case 'integer':
+        case 'number':
+            return { widget: 'number' };
+        case 'string': {
+            const format = schema.format;
+            if (format && FORMAT_WIDGETS[format])
+                return { widget: FORMAT_WIDGETS[format] };
+            return { widget: 'text' };
+        }
+        case 'array': {
+            const items = schema.items;
+            const itemType = Array.isArray(items) ? undefined : schemaType(items);
+            if (itemType && TAGGABLE.has(itemType))
+                return { widget: 'tags' };
+            return {
+                widget: 'unknown',
+                reason: 'unsupported-array',
+                detail: `array items are ${itemType ? `"${itemType}"` : 'unspecified'}; only string, number and integer items render as tags`
+            };
+        }
+        case 'object':
+            return {
+                widget: 'unknown',
+                reason: 'object-control',
+                detail: 'an object needs a layout with Controls for its properties, not one Control'
+            };
+        default:
+            return {
+                widget: 'unknown',
+                reason: 'unsupported-type',
+                detail: type ? `no widget renders type "${type}"` : 'the subschema declares no type'
+            };
+    }
+}

package/dist/components/ui/schema-form/index.d.ts

@@ -0,0 +1,5 @@
+export { default as SchemaForm } from './schema-form.svelte';
+export { default } from './schema-form.svelte';
+export { pickWidget, enumOptions, schemaType, type WidgetChoice } from './dispatch.js';
+export { addressedPaths, unmappedFields, scopeToPath, getAt, setAt } from './data.js';
+export { WIDGET_KINDS, type WidgetKind, type UnknownReason, type SchemaFormChange, type SchemaFormProps, type JsonSchema, type UISchemaElement } from './types.js';

package/dist/components/ui/schema-form/index.js

@@ -0,0 +1,5 @@
+export { default as SchemaForm } from './schema-form.svelte';
+export { default } from './schema-form.svelte';
+export { pickWidget, enumOptions, schemaType } from './dispatch.js';
+export { addressedPaths, unmappedFields, scopeToPath, getAt, setAt } from './data.js';
+export { WIDGET_KINDS } from './types.js';

package/dist/components/ui/schema-form/schema-form-control.svelte

@@ -0,0 +1,146 @@
+<script lang="ts">
+	import { isEnabled, resolveSchema, type ControlElement } from '@jsonforms/core';
+	import Label from '../label/label.svelte';
+	import SchemaFormWidget from './schema-form-widget.svelte';
+	import UnknownField from './widgets/unknown-field.svelte';
+	import { getSchemaFormContext } from './context.js';
+	import { pickWidget } from './dispatch.js';
+	import { getAt, scopeToPath } from './data.js';
+	import type { JsonSchema } from './types.js';
+
+	/**
+	 * One Control: resolve its scope against the JSON Schema, choose a widget,
+	 * and frame it with its label, description and validation message.
+	 *
+	 * Every way this can fail — no scope, a scope that resolves to nothing, a
+	 * widget hint nobody registered — leaves through `<UnknownField>`, never
+	 * through a branch that renders nothing.
+	 */
+	let { element }: { element: ControlElement } = $props();
+
+	const form = getSchemaFormContext();
+
+	const scope = $derived(typeof element.scope === 'string' ? element.scope : '');
+	const path = $derived(scope ? scopeToPath(scope) : '');
+	const subschema = $derived(
+		scope ? (resolveSchema(form.schema, scope, form.schema) as JsonSchema | undefined) : undefined
+	);
+	const options = $derived((element.options ?? {}) as Record<string, unknown>);
+	const choice = $derived(pickWidget(subschema, options));
+
+	const value = $derived(path ? getAt(form.data, path) : undefined);
+	const id = $derived(`${form.idPrefix}-${(path || 'unscoped').replace(/[^a-zA-Z0-9_-]/g, '-')}`);
+
+	/** `maxDepth` / `max_depth` → `Max depth`, when nothing supplied a title. */
+	const humanise = (key: string) =>
+		key
+			.replace(/[_-]+/g, ' ')
+			.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+			.replace(/^./, (first) => first.toUpperCase());
+
+	const label = $derived(
+		(typeof element.label === 'string' && element.label) ||
+			(subschema as { title?: string } | undefined)?.title ||
+			humanise(path.split('.').pop() || scope || 'Field')
+	);
+
+	const description = $derived((subschema as { description?: string } | undefined)?.description);
+
+	// `required` lives on the PARENT object schema, so read it from there rather
+	// than guessing from the field.
+	const required = $derived.by(() => {
+		const parentScope = scope.replace(/\/properties\/[^/]+$/, '');
+		const key = scope.split('/').pop() ?? '';
+		const parent =
+			parentScope === '#' || parentScope === ''
+				? form.schema
+				: (resolveSchema(form.schema, parentScope, form.schema) as JsonSchema | undefined);
+		return ((parent as { required?: string[] } | undefined)?.required ?? []).includes(key);
+	});
+
+	const errors = $derived(form.errors[path] ?? []);
+	const disabled = $derived(
+		form.disabled ||
+			options.readonly === true ||
+			!isEnabled(element, form.data, '', form.ajv, undefined)
+	);
+
+	const describedBy = $derived(
+		[description ? `${id}-description` : null, errors.length ? `${id}-error` : null]
+			.filter(Boolean)
+			.join(' ') || undefined
+	);
+
+	// A toggle reads as "control, then what it toggles"; everything else reads as
+	// "label, then the field". Both are still one labelled field.
+	const inline = $derived(choice.widget === 'switch' || choice.widget === 'checkbox');
+
+	const commit = (next: unknown) => form.change(path, next);
+</script>
+
+{#if !scope}
+	<UnknownField
+		{id}
+		label={typeof element.label === 'string' ? element.label : 'Control'}
+		scope="(none)"
+		path=""
+		value={undefined}
+		reason="missing-scope"
+		detail="this Control carries no scope, so there is no property to edit"
+	/>
+{:else if choice.widget === 'unknown'}
+	<UnknownField
+		{id}
+		{label}
+		{scope}
+		{path}
+		{value}
+		{disabled}
+		schema={subschema}
+		reason={choice.reason ?? 'unsupported-type'}
+		detail={choice.detail ?? 'this control could not be rendered'}
+		onchange={commit}
+	/>
+{:else}
+	<div class="grid gap-1.5" data-schema-form-field={path}>
+		{#snippet widget()}
+			<SchemaFormWidget
+				{choice}
+				schema={subschema as JsonSchema}
+				{value}
+				{id}
+				{label}
+				{scope}
+				{path}
+				{disabled}
+				{describedBy}
+				name={path}
+				onchange={commit}
+			/>
+		{/snippet}
+		{#snippet fieldLabel()}
+			<Label for={id} id="{id}-label" class={disabled ? 'opacity-50' : undefined}>
+				{label}{#if required}<span class="text-status-error" aria-hidden="true">&nbsp;*</span
+					><span class="sr-only"> (required)</span>{/if}
+			</Label>
+		{/snippet}
+
+		{#if inline}
+			<!-- A toggle reads as "control, then what it toggles". -->
+			<div class="flex items-center gap-2.5">
+				{@render widget()}
+				{@render fieldLabel()}
+			</div>
+		{:else}
+			{@render fieldLabel()}
+			{@render widget()}
+		{/if}
+
+		{#if description}
+			<p id="{id}-description" class="text-muted-foreground text-xs">{description}</p>
+		{/if}
+		{#if errors.length}
+			<p id="{id}-error" class="text-status-error text-xs">{errors.join('. ')}</p>
+		{/if}
+	</div>
+{/if}

package/dist/components/ui/schema-form/schema-form-control.svelte.d.ts

@@ -0,0 +1,7 @@
+import { type ControlElement } from '@jsonforms/core';
+type $$ComponentProps = {
+    element: ControlElement;
+};
+declare const SchemaFormControl: import("svelte").Component<$$ComponentProps, {}, "">;
+type SchemaFormControl = ReturnType<typeof SchemaFormControl>;
+export default SchemaFormControl;

package/dist/components/ui/schema-form/schema-form-element.svelte

@@ -0,0 +1,105 @@
+<script lang="ts">
+	import { isVisible, type ControlElement, type UISchemaElement } from '@jsonforms/core';
+	import Panel from '../panel/panel.svelte';
+	import * as Tabs from '../tabs/index.js';
+	import SchemaFormControl from './schema-form-control.svelte';
+	import UnknownField from './widgets/unknown-field.svelte';
+	import Self from './schema-form-element.svelte';
+	import { getSchemaFormContext } from './context.js';
+
+	/**
+	 * One node of the UI Schema tree, recursively.
+	 *
+	 * The vocabulary walked here is JSON Forms' own: VerticalLayout,
+	 * HorizontalLayout, Group, Categorization/Category, Control and Label. An
+	 * element type outside it renders as a flagged fallback — the previous
+	 * renderers treated an unknown node as nothing to do, which is how a nested
+	 * hint became inert without any signal.
+	 *
+	 * SHOW/HIDE is evaluated here rather than inside the control, so a rule on a
+	 * Group hides the whole group, which is what an author writing one means.
+	 */
+	let { element }: { element: UISchemaElement } = $props();
+
+	const form = getSchemaFormContext();
+
+	const visible = $derived(isVisible(element, form.data, '', form.ajv, undefined));
+	const children = $derived(((element as { elements?: UISchemaElement[] }).elements ?? []));
+	const label = $derived(
+		typeof (element as { label?: unknown }).label === 'string'
+			? ((element as { label: string }).label)
+			: undefined
+	);
+</script>
+
+{#if visible}
+	{#if element.type === 'VerticalLayout'}
+		<div class="grid gap-4" data-schema-form-layout="vertical">
+			{#each children as child, index (index)}
+				<Self element={child} />
+			{/each}
+		</div>
+	{:else if element.type === 'HorizontalLayout'}
+		<!-- Columns of equal width on a wide viewport, one stack below it. The
+		     column count follows the element count, so a layout never needs a
+		     breakpoint written per form. -->
+		<div class="grid gap-4 sm:auto-cols-fr sm:grid-flow-col" data-schema-form-layout="horizontal">
+			{#each children as child, index (index)}
+				<Self element={child} />
+			{/each}
+		</div>
+	{:else if element.type === 'Group'}
+		<Panel title={label} data-schema-form-layout="group">
+			<div class="grid gap-4">
+				{#each children as child, index (index)}
+					<Self element={child} />
+				{/each}
+			</div>
+		</Panel>
+	{:else if element.type === 'Categorization'}
+		{@const categories = children.filter((child) => isVisible(child, form.data, '', form.ajv, undefined))}
+		{#if categories.length}
+			<Tabs.Root value="category-0" data-schema-form-layout="categorization">
+				<Tabs.List>
+					{#each categories as category, index (index)}
+						<Tabs.Trigger value="category-{index}">
+							{(category as { label?: string }).label ?? `Section ${index + 1}`}
+						</Tabs.Trigger>
+					{/each}
+				</Tabs.List>
+				{#each categories as category, index (index)}
+					<Tabs.Content value="category-{index}" class="pt-4">
+						<div class="grid gap-4">
+							{#each (category as { elements?: UISchemaElement[] }).elements ?? [] as child, position (position)}
+								<Self element={child} />
+							{/each}
+						</div>
+					</Tabs.Content>
+				{/each}
+			</Tabs.Root>
+		{/if}
+	{:else if element.type === 'Category'}
+		<!-- A Category outside a Categorization is still a section of fields. -->
+		<div class="grid gap-4" data-schema-form-layout="category">
+			{#each children as child, index (index)}
+				<Self element={child} />
+			{/each}
+		</div>
+	{:else if element.type === 'Control'}
+		<SchemaFormControl element={element as ControlElement} />
+	{:else if element.type === 'Label'}
+		<p class="text-2xs text-muted-foreground font-semibold tracking-wide uppercase">
+			{(element as { text?: string }).text ?? label ?? ''}
+		</p>
+	{:else}
+		<UnknownField
+			id="unknown-element"
+			label={label ?? element.type}
+			scope="(ui schema element)"
+			path=""
+			reason="unknown-element"
+			detail={`"${element.type}" is not a UI schema element this renderer knows`}
+			value={element}
+		/>
+	{/if}
+{/if}

package/dist/components/ui/schema-form/schema-form-element.svelte.d.ts

@@ -0,0 +1,7 @@
+import { type UISchemaElement } from '@jsonforms/core';
+type $$ComponentProps = {
+    element: UISchemaElement;
+};
+declare const SchemaFormElement: import("svelte").Component<$$ComponentProps, {}, "">;
+type SchemaFormElement = ReturnType<typeof SchemaFormElement>;
+export default SchemaFormElement;

package/dist/components/ui/schema-form/schema-form-widget.svelte

@@ -0,0 +1,169 @@
+<script lang="ts">
+	import Input from '../input/input.svelte';
+	import Textarea from '../textarea/textarea.svelte';
+	import Switch from '../switch/switch.svelte';
+	import Checkbox from '../checkbox/checkbox.svelte';
+	import * as Select from '../select/index.js';
+	import SliderField from './widgets/slider-field.svelte';
+	import TagsField from './widgets/tags-field.svelte';
+	import RadioField from './widgets/radio-field.svelte';
+	import UnknownField from './widgets/unknown-field.svelte';
+	import { enumOptions, schemaType, type WidgetChoice } from './dispatch.js';
+	import type { JsonSchema } from './types.js';
+
+	/**
+	 * The widget dispatch table: one branch per `WidgetKind`, and a final `:else`
+	 * that is itself the loud fallback rather than nothing. There is deliberately
+	 * no silent arm in this file — that is the whole contract.
+	 */
+	let {
+		choice,
+		schema,
+		value,
+		id,
+		name,
+		label,
+		scope,
+		path,
+		disabled = false,
+		describedBy,
+		onchange
+	}: {
+		choice: WidgetChoice;
+		schema: JsonSchema;
+		value: unknown;
+		id: string;
+		name: string;
+		label: string;
+		scope: string;
+		path: string;
+		disabled?: boolean;
+		describedBy?: string;
+		onchange: (next: unknown) => void;
+	} = $props();
+
+	const type = $derived(schemaType(schema));
+	const options = $derived(enumOptions(schema) ?? []);
+	const bounds = $derived(schema as { minimum?: number; maximum?: number; multipleOf?: number });
+	const items = $derived((schema as { items?: JsonSchema }).items);
+
+	const text = $derived(value === undefined || value === null ? '' : String(value));
+	/** The string key bits-ui addresses an option by; enum values may be numbers. */
+	const selected = $derived(value === undefined || value === null ? '' : String(value));
+
+	const commitNumber = (raw: string) => {
+		if (raw.trim() === '') return onchange(undefined);
+		const parsed = Number(raw);
+		onchange(Number.isFinite(parsed) ? parsed : raw);
+	};
+
+	const commitEnum = (key: string) => {
+		const match = options.find((option) => String(option.value) === key);
+		onchange(match ? match.value : key);
+	};
+</script>
+
+{#if choice.widget === 'text' || choice.widget === 'password' || choice.widget === 'date' || choice.widget === 'time' || choice.widget === 'datetime'}
+	<Input
+		{id}
+		{name}
+		{disabled}
+		type={choice.widget === 'datetime'
+			? 'datetime-local'
+			: choice.widget === 'text'
+				? 'text'
+				: choice.widget}
+		value={text}
+		aria-describedby={describedBy}
+		oninput={(event) => onchange((event.currentTarget as HTMLInputElement).value)}
+	/>
+{:else if choice.widget === 'textarea'}
+	<Textarea
+		{id}
+		{name}
+		{disabled}
+		value={text}
+		aria-describedby={describedBy}
+		oninput={(event) => onchange((event.currentTarget as HTMLTextAreaElement).value)}
+	/>
+{:else if choice.widget === 'number'}
+	<Input
+		{id}
+		{name}
+		{disabled}
+		type="number"
+		min={bounds.minimum}
+		max={bounds.maximum}
+		step={bounds.multipleOf ?? (type === 'integer' ? 1 : undefined)}
+		value={text}
+		aria-describedby={describedBy}
+		oninput={(event) => commitNumber((event.currentTarget as HTMLInputElement).value)}
+	/>
+{:else if choice.widget === 'slider'}
+	<SliderField
+		{id}
+		{disabled}
+		{describedBy}
+		value={typeof value === 'number' ? value : undefined}
+		min={bounds.minimum ?? 0}
+		max={bounds.maximum ?? 100}
+		step={bounds.multipleOf ?? (type === 'integer' ? 1 : 0.01)}
+		onchange={(next) => onchange(next)}
+	/>
+{:else if choice.widget === 'select'}
+	<Select.Root type="single" value={selected} onValueChange={commitEnum} {disabled} {name}>
+		<Select.Trigger {id} class="w-full" aria-describedby={describedBy}>
+			{options.find((option) => String(option.value) === selected)?.label ?? 'Select…'}
+		</Select.Trigger>
+		<Select.Content>
+			{#each options as option (String(option.value))}
+				<Select.Item value={String(option.value)} label={option.label}>{option.label}</Select.Item>
+			{/each}
+		</Select.Content>
+	</Select.Root>
+{:else if choice.widget === 'radio'}
+	<RadioField {id} {name} {value} {options} {disabled} {describedBy} onchange={(next) => onchange(next)} />
+{:else if choice.widget === 'switch'}
+	<Switch
+		{id}
+		{name}
+		{disabled}
+		checked={value === true}
+		aria-describedby={describedBy}
+		onCheckedChange={(next: boolean) => onchange(next)}
+	/>
+{:else if choice.widget === 'checkbox'}
+	<Checkbox
+		{id}
+		{name}
+		{disabled}
+		checked={value === true}
+		aria-describedby={describedBy}
+		onCheckedChange={(next: boolean) => onchange(next === true)}
+	/>
+{:else if choice.widget === 'tags'}
+	<TagsField
+		{id}
+		{disabled}
+		{describedBy}
+		value={Array.isArray(value) ? value : undefined}
+		itemType={schemaType(items) ?? 'string'}
+		onchange={(next) => onchange(next)}
+	/>
+{:else}
+	<!-- `unknown`, and the unreachable case of a WidgetKind with no branch above.
+	     Both land loudly: a widget kind this file forgot is exactly the class of
+	     defect that made a field vanish in the renderers this one replaces. -->
+	<UnknownField
+		{id}
+		{label}
+		{scope}
+		{path}
+		{value}
+		{schema}
+		{disabled}
+		reason={choice.reason ?? 'unknown-widget'}
+		detail={choice.detail ?? `no branch renders the "${choice.widget}" widget`}
+		onchange={(next) => onchange(next)}
+	/>
+{/if}

package/dist/components/ui/schema-form/schema-form-widget.svelte.d.ts

@@ -0,0 +1,18 @@
+import { type WidgetChoice } from './dispatch.js';
+import type { JsonSchema } from './types.js';
+type $$ComponentProps = {
+    choice: WidgetChoice;
+    schema: JsonSchema;
+    value: unknown;
+    id: string;
+    name: string;
+    label: string;
+    scope: string;
+    path: string;
+    disabled?: boolean;
+    describedBy?: string;
+    onchange: (next: unknown) => void;
+};
+declare const SchemaFormWidget: import("svelte").Component<$$ComponentProps, {}, "">;
+type SchemaFormWidget = ReturnType<typeof SchemaFormWidget>;
+export default SchemaFormWidget;