@poodle64/ui 2026.8.10 → 2026.8.12

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;

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

@@ -0,0 +1,123 @@
+<script lang="ts">
+	import TriangleAlert from '@lucide/svelte/icons/triangle-alert';
+	import StatusBadge from '../../status-badge/status-badge.svelte';
+	import Input from '../../input/input.svelte';
+	import Label from '../../label/label.svelte';
+	import type { JsonSchema, UnknownReason } from '../types.js';
+	import { schemaType } from '../dispatch.js';
+
+	/**
+	 * THE LOUD FALLBACK — the reason this package exists rather than a fourth
+	 * hand-rolled renderer.
+	 *
+	 * The estate's outgoing renderers failed silently in three ways: an
+	 * unrecognised `widget` hint rendered no input, a config group missing from a
+	 * hardcoded order rendered nothing at all, and a nested hint was simply
+	 * inert. Every one of those made the field VANISH, and a form with a missing
+	 * field looks exactly like a form. Nobody noticed for months.
+	 *
+	 * So there is no silent branch anywhere in `<SchemaForm>`: everything the
+	 * renderer cannot dispatch lands here, and here always renders. It says what
+	 * it could not do, names the pointer so the fix is a copy-paste, shows the
+	 * value that would otherwise have been lost, and keeps it editable whenever
+	 * editing a raw value is safe — which is when the value is a primitive. An
+	 * object or an array is shown, not edited: a text box over structured data
+	 * is a data-loss affordance, not a fallback.
+	 */
+	let {
+		label,
+		scope,
+		path,
+		reason,
+		detail,
+		value,
+		schema,
+		disabled = false,
+		id,
+		onchange
+	}: {
+		label: string;
+		/** JSON Pointer this control addressed, or the property's own pointer. */
+		scope: string;
+		/** Dot path into the value. */
+		path: string;
+		reason: UnknownReason;
+		/** What specifically could not be done, in one sentence. */
+		detail: string;
+		value: unknown;
+		schema?: JsonSchema;
+		disabled?: boolean;
+		id: string;
+		/** Emitted when the raw editor commits a primitive. */
+		onchange?: (next: unknown) => void;
+	} = $props();
+
+	// Editing is offered only where a text box can round-trip the value without
+	// destroying structure: a primitive, or an absent value under a primitive
+	// schema. Anything structured is shown read-only.
+	const declared = $derived(schemaType(schema));
+	const structural = $derived(
+		(value !== null && typeof value === 'object') || declared === 'object' || declared === 'array'
+	);
+	const editable = $derived(!structural);
+
+	const raw = $derived(
+		value === undefined || value === null
+			? ''
+			: typeof value === 'object'
+				? JSON.stringify(value, null, 2)
+				: String(value)
+	);
+
+	/** Coerce the typed text back to the schema's declared type where it can. */
+	function commit(text: string) {
+		if (declared === 'number' || declared === 'integer') {
+			const parsed = text.trim() === '' ? undefined : Number(text);
+			onchange?.(parsed !== undefined && Number.isFinite(parsed) ? parsed : text);
+			return;
+		}
+		if (declared === 'boolean') {
+			if (text === 'true' || text === 'false') return onchange?.(text === 'true');
+		}
+		onchange?.(text);
+	}
+</script>
+
+<div
+	role="group"
+	aria-label="Unrecognised field: {label}"
+	data-schema-form-unknown=""
+	data-unknown-reason={reason}
+	data-path={path}
+	class="border-status-warning/50 bg-status-warning/5 grid gap-2 rounded-lg border border-dashed p-3"
+>
+	<div class="flex flex-wrap items-center gap-2">
+		<TriangleAlert class="text-status-warning size-4 shrink-0" aria-hidden="true" />
+		<span class="text-body font-semibold">{label}</span>
+		<StatusBadge status="warning" label="Unrecognised control" />
+	</div>
+
+	<p class="text-muted-foreground text-xs">
+		{detail}. Rendered raw and unstyled so the value is not lost, at
+		<code class="font-mono">{scope}</code>
+	</p>
+
+	{#if editable}
+		<Label for={id} class="text-2xs text-muted-foreground uppercase">Raw value</Label>
+		<Input
+			{id}
+			{disabled}
+			value={raw}
+			class="font-mono"
+			oninput={(event) => commit((event.currentTarget as HTMLInputElement).value)}
+		/>
+	{:else}
+		<pre
+			data-schema-form-unknown-readonly=""
+			class="bg-surface-1 border-border text-muted-foreground max-h-48 overflow-auto rounded-md border p-2 font-mono text-xs">{raw ||
+				'(no value)'}</pre>
+		<p class="text-muted-foreground text-xs">
+			Structured value: shown, not edited, so nothing is silently rewritten.
+		</p>
+	{/if}
+</div>

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

@@ -0,0 +1,20 @@
+import type { JsonSchema, UnknownReason } from '../types.js';
+type $$ComponentProps = {
+    label: string;
+    /** JSON Pointer this control addressed, or the property's own pointer. */
+    scope: string;
+    /** Dot path into the value. */
+    path: string;
+    reason: UnknownReason;
+    /** What specifically could not be done, in one sentence. */
+    detail: string;
+    value: unknown;
+    schema?: JsonSchema;
+    disabled?: boolean;
+    id: string;
+    /** Emitted when the raw editor commits a primitive. */
+    onchange?: (next: unknown) => void;
+};
+declare const UnknownField: import("svelte").Component<$$ComponentProps, {}, "">;
+type UnknownField = ReturnType<typeof UnknownField>;
+export default UnknownField;

package/dist/components/ui/search-results/index.d.ts

@@ -0,0 +1,3 @@
+export { default as SearchResults } from './search-results.svelte';
+export { default } from './search-results.svelte';
+export type { LibraryBadge, LibrarySearchResult, SearchSnippetSegment } from '../library-browse/types.js';

package/dist/components/ui/search-results/index.js

@@ -0,0 +1,2 @@
+export { default as SearchResults } from './search-results.svelte';
+export { default } from './search-results.svelte';