@poodle64/ui 2026.8.11 → 2026.8.13

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

@@ -0,0 +1,42 @@
+import { type JsonSchema, type UISchemaElement } from '@jsonforms/core';
+import type { UnknownReason } from './types.js';
+/**
+ * Reading and writing a value at a dot path, and the walk that decides which
+ * schema properties the layout never mentioned.
+ *
+ * Dot paths are JSON Forms' own addressing (`toDataPath('#/properties/a/properties/b')`
+ * → `a.b`), so a property name containing a literal `.` is not addressable —
+ * the same limitation the wire format itself carries.
+ */
+export declare const scopeToPath: (scope: string) => string;
+/** Read the value at a dot path, or `undefined`. */
+export declare function getAt(data: unknown, path: string): unknown;
+/**
+ * Return a copy of `data` with `path` set to `value`. Every object along the
+ * way is copied, so a consumer holding the previous value still holds the
+ * previous value — a `$state` consumer and an immutable store both work.
+ */
+export declare function setAt(data: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+/** Every UI schema element in the tree, depth first. */
+export declare function walkElements(element: UISchemaElement | undefined): UISchemaElement[];
+/** The dot paths every Control in the tree addresses. */
+export declare function addressedPaths(uischema: UISchemaElement | undefined): Set<string>;
+export interface UnmappedField {
+    /** Dot path of the property nothing in the layout addresses. */
+    path: string;
+    /** JSON Pointer scope, so the fix is a copy-paste into the UI schema. */
+    scope: string;
+    schema: JsonSchema;
+    reason: UnknownReason;
+}
+/**
+ * Every schema property no Control addresses.
+ *
+ * This is the check that would have caught the estate's live defect: three
+ * whole top-level config groups never rendered because their names were absent
+ * from a hardcoded GROUP_ORDER, and a missing group produced no output and no
+ * error. Here a group nothing addresses is reported ONCE, at the group — the
+ * walk does not descend into a subtree the layout ignores entirely, so an
+ * unmentioned group is one loud entry rather than forty.
+ */
+export declare function unmappedFields(root: JsonSchema, addressed: Set<string>, node?: JsonSchema, scope?: string, path?: string): UnmappedField[];

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

@@ -0,0 +1,97 @@
+import { resolveSchema, toDataPath } from '@jsonforms/core';
+/**
+ * Reading and writing a value at a dot path, and the walk that decides which
+ * schema properties the layout never mentioned.
+ *
+ * Dot paths are JSON Forms' own addressing (`toDataPath('#/properties/a/properties/b')`
+ * → `a.b`), so a property name containing a literal `.` is not addressable —
+ * the same limitation the wire format itself carries.
+ */
+export const scopeToPath = (scope) => toDataPath(scope);
+/** Read the value at a dot path, or `undefined`. */
+export function getAt(data, path) {
+    if (!path)
+        return data;
+    let node = data;
+    for (const key of path.split('.')) {
+        if (node === null || typeof node !== 'object')
+            return undefined;
+        node = node[key];
+    }
+    return node;
+}
+/**
+ * Return a copy of `data` with `path` set to `value`. Every object along the
+ * way is copied, so a consumer holding the previous value still holds the
+ * previous value — a `$state` consumer and an immutable store both work.
+ */
+export function setAt(data, path, value) {
+    const keys = path.split('.');
+    const root = { ...data };
+    let node = root;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        const child = node[key];
+        node[key] = child && typeof child === 'object' && !Array.isArray(child)
+            ? { ...child }
+            : {};
+        node = node[key];
+    }
+    node[keys[keys.length - 1]] = value;
+    return root;
+}
+/** Every UI schema element in the tree, depth first. */
+export function walkElements(element) {
+    if (!element)
+        return [];
+    const children = element.elements ?? [];
+    return [element, ...children.flatMap(walkElements)];
+}
+/** The dot paths every Control in the tree addresses. */
+export function addressedPaths(uischema) {
+    const paths = new Set();
+    for (const element of walkElements(uischema)) {
+        const scope = element.scope;
+        if (element.type === 'Control' && typeof scope === 'string' && scope.startsWith('#')) {
+            paths.add(scopeToPath(scope));
+        }
+    }
+    return paths;
+}
+/**
+ * Every schema property no Control addresses.
+ *
+ * This is the check that would have caught the estate's live defect: three
+ * whole top-level config groups never rendered because their names were absent
+ * from a hardcoded GROUP_ORDER, and a missing group produced no output and no
+ * error. Here a group nothing addresses is reported ONCE, at the group — the
+ * walk does not descend into a subtree the layout ignores entirely, so an
+ * unmentioned group is one loud entry rather than forty.
+ */
+export function unmappedFields(root, addressed, node = root, scope = '#', path = '') {
+    const properties = node.properties;
+    if (!properties)
+        return [];
+    const found = [];
+    for (const [key, raw] of Object.entries(properties)) {
+        const childPath = path ? `${path}.${key}` : key;
+        const childScope = `${scope}/properties/${key}`;
+        // `resolveSchema` follows any $ref, so a property behind a definition is
+        // judged on the schema it actually resolves to.
+        const child = resolveSchema(root, childScope, root) ?? raw;
+        // Addressed BY ITSELF: a Control points at this property. Whatever it does
+        // with it is that Control's business — do not descend and second-guess it.
+        if (addressed.has(childPath))
+            continue;
+        // Addressed BELOW: some Control points inside it, so the layout knows about
+        // this subtree and only some of its leaves are missing.
+        if ([...addressed].some((addressedPath) => addressedPath.startsWith(`${childPath}.`))) {
+            found.push(...unmappedFields(root, addressed, child, childScope, childPath));
+            continue;
+        }
+        // Addressed nowhere: report it here, once, and do not descend — an
+        // unmentioned group is one loud entry, not forty.
+        found.push({ path: childPath, scope: childScope, schema: child, reason: 'not-in-layout' });
+    }
+    return found;
+}

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

@@ -0,0 +1,35 @@
+import type { JsonSchema } from '@jsonforms/core';
+import { type UnknownReason, type WidgetKind } from './types.js';
+/**
+ * Control → widget resolution, as a pure function so the table can be asserted
+ * without rendering anything.
+ *
+ * THE RULE THIS FILE EXISTS FOR: every branch that cannot produce a real widget
+ * returns `{ widget: 'unknown', reason }`. There is no branch that returns
+ * nothing, and no branch that quietly substitutes a default for a hint it did
+ * not understand. The estate's previous home-grown renderer had both, and a
+ * `widget: "dropdown"` hint therefore rendered no input at all for months
+ * without anyone noticing.
+ */
+export interface WidgetChoice {
+    widget: WidgetKind;
+    /** Present exactly when `widget === 'unknown'`. */
+    reason?: UnknownReason;
+    /** Human-readable specifics for the flagged render, e.g. the rejected hint. */
+    detail?: string;
+}
+/** The first `type` a subschema declares (JSON Schema allows an array of them). */
+export declare function schemaType(schema: JsonSchema | undefined): string | undefined;
+/** Does this subschema carry a closed set of values a select can list? */
+export declare function enumOptions(schema: JsonSchema | undefined): {
+    value: unknown;
+    label: string;
+}[] | 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 declare function pickWidget(schema: JsonSchema | undefined, options?: Record<string, unknown>): WidgetChoice;

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;