@poodle64/ui 2026.8.11 → 2026.8.13

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;

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

@@ -0,0 +1,153 @@
+<script lang="ts">
+	import { createAjv, Generate, type UISchemaElement } from '@jsonforms/core';
+	import Panel from '../panel/panel.svelte';
+	import SchemaFormElement from './schema-form-element.svelte';
+	import UnknownField from './widgets/unknown-field.svelte';
+	import { setSchemaFormContext } from './context.js';
+	import { addressedPaths, getAt, setAt, unmappedFields } from './data.js';
+	import { cn } from '../../../utils.js';
+	import type { SchemaFormProps } from './types.js';
+
+	/**
+	 * Render a form the server described: a JSON Schema for what the value IS,
+	 * and a JSON Forms UI Schema for how it is laid out.
+	 *
+	 * This component knows nothing about any application. It takes the two
+	 * documents, the current value and a change handler; it performs no fetch,
+	 * holds no endpoint, and names no service. That is what lets the engine
+	 * behind the schema be swapped without touching a consumer — and what lets
+	 * three apps that each hand-rolled this converge on one renderer.
+	 *
+	 * `@jsonforms/core` is used HEADLESS — for JSON-Pointer scope resolution,
+	 * rule evaluation and Ajv only. The renderers are this package's own and
+	 * dispatch to this package's own widgets; there is no official Svelte
+	 * renderer for JSON Forms and the community one carries no external
+	 * validation.
+	 *
+	 * THE ONE NON-NEGOTIABLE RULE: nothing renders silently as nothing. An
+	 * unknown widget hint, an unknown element type, a scope that resolves to
+	 * nothing, or a schema property the layout never mentions each renders as a
+	 * flagged fallback carrying `data-schema-form-unknown`. The renderers this
+	 * replaces failed all four ways in silence, and shipped that way for months.
+	 */
+	let {
+		schema,
+		uischema,
+		value,
+		onChange,
+		disabled = false,
+		idPrefix = 'sf',
+		class: className
+	}: SchemaFormProps = $props();
+
+	// One Ajv for the life of the form: rule conditions and validation both use
+	// it, and compiling per keystroke would be the whole cost of the component.
+	const ajv = createAjv();
+
+	// No UI schema is a legitimate mode, not an error: generating one from the
+	// schema is the only arrangement in which a field CANNOT be missing from the
+	// layout, so it is the safe default rather than a blank form.
+	const layout = $derived(uischema ?? (Generate.uiSchema(schema) as UISchemaElement));
+
+	const addressed = $derived(addressedPaths(layout));
+	const unmapped = $derived(unmappedFields(schema, addressed));
+
+	/**
+	 * Validation messages by dot path. Ajv is asked about a CLONE, because
+	 * `createAjv` enables `useDefaults` and would otherwise write defaults into
+	 * the caller's value behind its back.
+	 */
+	const errors = $derived.by(() => {
+		const byPath: Record<string, string[]> = {};
+		try {
+			const validate = ajv.compile(schema as object);
+			const probe = structuredClone($state.snapshot(value));
+			if (validate(probe)) return byPath;
+			for (const error of validate.errors ?? []) {
+				const missing = (error.params as { missingProperty?: string })?.missingProperty;
+				const instance = error.instancePath.replace(/^\//, '').split('/').filter(Boolean).join('.');
+				const path = missing ? [instance, missing].filter(Boolean).join('.') : instance;
+				if (!path) continue;
+				(byPath[path] ??= []).push(missing ? 'Required' : (error.message ?? 'is invalid'));
+			}
+		} catch {
+			// A schema Ajv will not compile, or a value it will not clone, is still
+			// a form this renderer can lay out — it simply cannot be validated.
+			// Never let a validation problem blank the form: that is the failure
+			// mode this whole component exists to remove.
+			return byPath;
+		}
+		return byPath;
+	});
+
+	setSchemaFormContext({
+		get schema() {
+			return schema;
+		},
+		get data() {
+			return value;
+		},
+		get disabled() {
+			return disabled;
+		},
+		get idPrefix() {
+			return idPrefix;
+		},
+		get errors() {
+			return errors;
+		},
+		ajv,
+		change(path, next) {
+			onChange(setAt($state.snapshot(value) as Record<string, unknown>, path, next), {
+				path,
+				value: next
+			});
+		}
+	});
+</script>
+
+<div class={cn('grid gap-4', className)} data-schema-form="">
+	<SchemaFormElement element={layout} />
+
+	{#if unmapped.length}
+		<!--
+			The defect this section exists for: in the renderer being retired, three
+			whole top-level config groups never rendered because their names were
+			absent from a hardcoded order. Nothing failed, nothing warned — the
+			groups were simply not there. A field the layout does not mention is now
+			the loudest thing on the page instead of the quietest.
+		-->
+		<Panel
+			title="Not in the layout"
+			subtitle="{unmapped.length} field{unmapped.length === 1 ? '' : 's'} no Control addresses"
+			data-schema-form-unmapped=""
+		>
+			<p class="text-muted-foreground mb-3 text-xs">
+				The JSON Schema describes {unmapped.length === 1 ? 'this field' : 'these fields'} but the UI
+				schema never {unmapped.length === 1 ? 'mentions it' : 'mentions them'}. Add a Control for
+				each; until then {unmapped.length === 1 ? 'it is' : 'they are'} edited raw here rather than
+				disappearing.
+			</p>
+			<div class="grid gap-3">
+				{#each unmapped as field (field.path)}
+					<UnknownField
+						id="{idPrefix}-unmapped-{field.path.replace(/[^a-zA-Z0-9_-]/g, '-')}"
+						label={(field.schema as { title?: string }).title ?? field.path}
+						scope={field.scope}
+						path={field.path}
+						schema={field.schema}
+						reason={field.reason}
+						{disabled}
+						detail="no Control in the UI schema addresses this property"
+						value={getAt(value, field.path)}
+						onchange={(next) =>
+							onChange(
+								setAt($state.snapshot(value) as Record<string, unknown>, field.path, next),
+								{ path: field.path, value: next }
+							)}
+					/>
+				{/each}
+			</div>
+		</Panel>
+	{/if}
+</div>

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

@@ -0,0 +1,4 @@
+import type { SchemaFormProps } from './types.js';
+declare const SchemaForm: import("svelte").Component<SchemaFormProps, {}, "">;
+type SchemaForm = ReturnType<typeof SchemaForm>;
+export default SchemaForm;

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

@@ -0,0 +1,61 @@
+import type { JsonSchema, UISchemaElement } from '@jsonforms/core';
+export type { JsonSchema, UISchemaElement };
+/**
+ * The widgets `<SchemaForm>` can dispatch a Control to. This list IS the
+ * contract: a hint naming anything outside it resolves to `'unknown'` and
+ * renders loudly, it does not fall back to a default control and it never
+ * renders nothing.
+ */
+export declare const WIDGET_KINDS: readonly ["text", "textarea", "password", "number", "slider", "date", "time", "datetime", "select", "radio", "switch", "checkbox", "tags"];
+export type WidgetKind = (typeof WIDGET_KINDS)[number] | 'unknown';
+/**
+ * Why something could not be rendered as a real control. Every value is
+ * surfaced in the DOM as `data-unknown-reason`, so a consuming app's own gate
+ * can assert on it, and so a screenshot of a broken form says WHY it is broken.
+ */
+export type UnknownReason = 
+/** `options.format`/`options.widget` named a widget this package does not ship. */
+'unknown-widget'
+/** The UI schema element's `type` is not in the JSON Forms vocabulary this renderer walks. */
+ | 'unknown-element'
+/** The Control's `scope` pointer resolves to nothing in the JSON Schema. */
+ | 'unresolved-scope'
+/** The Control has no `scope` at all. */
+ | 'missing-scope'
+/** The resolved subschema has a `type` no widget covers. */
+ | 'unsupported-type'
+/** A Control addressing an object — an object needs a layout, not a control. */
+ | 'object-control'
+/** A hint asked for a closed value set, but the subschema declares none. */
+ | 'no-options'
+/** An array whose items are not primitives; `tags` cannot represent it. */
+ | 'unsupported-array'
+/** The JSON Schema describes this field but the UI schema never mentions it. */
+ | 'not-in-layout';
+/** The change `<SchemaForm>` emits alongside the next whole value. */
+export interface SchemaFormChange {
+    /** Dot path of the field that changed, e.g. `tuning.depth`. */
+    path: string;
+    /** The field's new value. */
+    value: unknown;
+}
+export interface SchemaFormProps {
+    /** The JSON Schema describing the object being edited. */
+    schema: JsonSchema;
+    /**
+     * The JSON Forms UI Schema describing the layout. Omit it and one is
+     * generated from the schema, which is the only mode in which no field can
+     * be missing from the layout.
+     */
+    uischema?: UISchemaElement;
+    /** The current value. `<SchemaForm>` never mutates it. */
+    value: Record<string, unknown>;
+    /** Called with the next whole value and the single field that changed. */
+    onChange: (next: Record<string, unknown>, change: SchemaFormChange) => void;
+    /** Disable every control in the form. */
+    disabled?: boolean;
+    /** Prefix for generated element ids, when two forms share a page. */
+    idPrefix?: string;
+    /** Extra classes on the form's root element. */
+    class?: string;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The widgets `<SchemaForm>` can dispatch a Control to. This list IS the
+ * contract: a hint naming anything outside it resolves to `'unknown'` and
+ * renders loudly, it does not fall back to a default control and it never
+ * renders nothing.
+ */
+export const WIDGET_KINDS = [
+    'text',
+    'textarea',
+    'password',
+    'number',
+    'slider',
+    'date',
+    'time',
+    'datetime',
+    'select',
+    'radio',
+    'switch',
+    'checkbox',
+    'tags'
+];

package/dist/components/ui/schema-form/widgets/radio-field.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+	import Label from '../../label/label.svelte';
+
+	/**
+	 * A closed value set as a visible row of choices, for the case where a select
+	 * hides the options a user needs to compare. Composed here for the same
+	 * reason as the slider: the package ships no radio group, and its only caller
+	 * is an enum Control that asked for `options.format: "radio"`.
+	 *
+	 * Native inputs, one `name` per field, so arrow-key roving and the radiogroup
+	 * role come from the platform rather than from markup that has to be right.
+	 */
+	let {
+		id,
+		name,
+		value,
+		options,
+		disabled = false,
+		describedBy,
+		onchange
+	}: {
+		id: string;
+		name: string;
+		value: unknown;
+		options: { value: unknown; label: string }[];
+		disabled?: boolean;
+		describedBy?: string;
+		onchange: (next: unknown) => void;
+	} = $props();
+</script>
+
+<div {id} role="radiogroup" aria-labelledby="{id}-label" aria-describedby={describedBy} class="flex flex-wrap gap-x-4 gap-y-2">
+	{#each options as option, index (String(option.value))}
+		<div class="flex items-center gap-1.5">
+			<input
+				id="{id}-{index}"
+				{name}
+				{disabled}
+				type="radio"
+				value={String(option.value)}
+				checked={option.value === value}
+				class="accent-primary focus-visible:ring-ring/50 size-4 outline-none focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50"
+				onchange={() => onchange(option.value)}
+			/>
+			<Label for="{id}-{index}" class="font-normal">{option.label}</Label>
+		</div>
+	{/each}
+</div>

package/dist/components/ui/schema-form/widgets/radio-field.svelte.d.ts

@@ -0,0 +1,15 @@
+type $$ComponentProps = {
+    id: string;
+    name: string;
+    value: unknown;
+    options: {
+        value: unknown;
+        label: string;
+    }[];
+    disabled?: boolean;
+    describedBy?: string;
+    onchange: (next: unknown) => void;
+};
+declare const RadioField: import("svelte").Component<$$ComponentProps, {}, "">;
+type RadioField = ReturnType<typeof RadioField>;
+export default RadioField;

package/dist/components/ui/schema-form/widgets/slider-field.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+	/**
+	 * A bounded numeric field as a track plus a live readout.
+	 *
+	 * Composed here rather than imported: the package ships no slider, and the
+	 * only caller is a Control whose subschema carries `minimum`/`maximum`. It is
+	 * a native `<input type="range">` so the keyboard, ARIA and touch behaviour
+	 * are the platform's; the only styling is the accent utility, which resolves
+	 * through the palette, so an app that changes `--ds-color-primary` changes
+	 * the track with it.
+	 */
+	let {
+		id,
+		value,
+		min,
+		max,
+		step = 1,
+		disabled = false,
+		describedBy,
+		onchange
+	}: {
+		id: string;
+		value: number | undefined;
+		min: number;
+		max: number;
+		step?: number;
+		disabled?: boolean;
+		describedBy?: string;
+		onchange: (next: number) => void;
+	} = $props();
+
+	const current = $derived(typeof value === 'number' && Number.isFinite(value) ? value : min);
+</script>
+
+<div class="flex items-center gap-3">
+	<input
+		{id}
+		{min}
+		{max}
+		{step}
+		{disabled}
+		type="range"
+		value={current}
+		aria-describedby={describedBy}
+		class="accent-primary focus-visible:ring-ring/50 h-8 w-full cursor-pointer rounded-lg outline-none focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50"
+		oninput={(event) => onchange(Number((event.currentTarget as HTMLInputElement).value))}
+	/>
+	<output for={id} class="ds-tabular text-muted-foreground w-10 shrink-0 text-right text-xs"
+		>{current}</output
+	>
+</div>

package/dist/components/ui/schema-form/widgets/slider-field.svelte.d.ts

@@ -0,0 +1,13 @@
+type $$ComponentProps = {
+    id: string;
+    value: number | undefined;
+    min: number;
+    max: number;
+    step?: number;
+    disabled?: boolean;
+    describedBy?: string;
+    onchange: (next: number) => void;
+};
+declare const SliderField: import("svelte").Component<$$ComponentProps, {}, "">;
+type SliderField = ReturnType<typeof SliderField>;
+export default SliderField;

package/dist/components/ui/schema-form/widgets/tags-field.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+	import X from '@lucide/svelte/icons/x';
+	import Badge from '../../badge/badge.svelte';
+	import Input from '../../input/input.svelte';
+
+	/**
+	 * An array of primitives as removable chips plus one entry field.
+	 *
+	 * Composed here because the package ships no tags input and an array of
+	 * strings is the commonest non-scalar in a server-described config (allowed
+	 * hosts, enabled features, ignore globs). Enter or comma commits; Backspace
+	 * on an empty field removes the last chip, which is the behaviour every tags
+	 * input has and the one users try first.
+	 *
+	 * Item coercion follows the subschema: a `number`/`integer` item schema means
+	 * the array stays numeric rather than quietly becoming strings.
+	 */
+	let {
+		id,
+		value,
+		itemType = 'string',
+		disabled = false,
+		placeholder = 'Add and press Enter',
+		describedBy,
+		onchange
+	}: {
+		id: string;
+		value: unknown[] | undefined;
+		itemType?: string;
+		disabled?: boolean;
+		placeholder?: string;
+		describedBy?: string;
+		onchange: (next: unknown[]) => void;
+	} = $props();
+
+	let draft = $state('');
+
+	const items = $derived(Array.isArray(value) ? value : []);
+
+	const coerce = (text: string): unknown => {
+		if (itemType !== 'number' && itemType !== 'integer') return text;
+		const parsed = Number(text);
+		return Number.isFinite(parsed) ? parsed : text;
+	};
+
+	function add() {
+		const text = draft.trim();
+		if (!text) return;
+		const next = coerce(text);
+		if (!items.some((item) => item === next)) onchange([...items, next]);
+		draft = '';
+	}
+
+	function removeAt(index: number) {
+		onchange(items.filter((_, position) => position !== index));
+	}
+
+	function onkeydown(event: KeyboardEvent) {
+		if (event.key === 'Enter' || event.key === ',') {
+			event.preventDefault();
+			add();
+			return;
+		}
+		if (event.key === 'Backspace' && draft === '' && items.length) removeAt(items.length - 1);
+	}
+</script>
+
+<div class="grid gap-1.5">
+	{#if items.length}
+		<ul class="flex flex-wrap gap-1.5" aria-label="Current values">
+			{#each items as item, index (`${String(item)}-${index}`)}
+				<li>
+					<Badge variant="secondary" class="h-6 gap-1 pr-1">
+						<span class="font-mono">{String(item)}</span>
+						<button
+							type="button"
+							{disabled}
+							aria-label="Remove {String(item)}"
+							class="hover:bg-muted hover:text-foreground text-muted-foreground focus-visible:ring-ring/50 flex size-5 items-center justify-center rounded-full outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50"
+							onclick={() => removeAt(index)}
+						>
+							<X class="size-3" aria-hidden="true" />
+						</button>
+					</Badge>
+				</li>
+			{/each}
+		</ul>
+	{/if}
+	<Input
+		{id}
+		{disabled}
+		{placeholder}
+		bind:value={draft}
+		aria-describedby={describedBy}
+		{onkeydown}
+		onblur={add}
+	/>
+</div>

package/dist/components/ui/schema-form/widgets/tags-field.svelte.d.ts

@@ -0,0 +1,12 @@
+type $$ComponentProps = {
+    id: string;
+    value: unknown[] | undefined;
+    itemType?: string;
+    disabled?: boolean;
+    placeholder?: string;
+    describedBy?: string;
+    onchange: (next: unknown[]) => void;
+};
+declare const TagsField: import("svelte").Component<$$ComponentProps, {}, "">;
+type TagsField = ReturnType<typeof TagsField>;
+export default TagsField;