@poodle64/ui 2026.9.23 → 2026.10.0

package/README.md

@@ -568,7 +568,7 @@ remembered, not what the house looks like.
 was before the feature existed — gated, not assumed:
 
 ```sh
-node harness/additivity.mjs ui-v2026.8.3
+node harness/additivity.mjs ee0db12   # ui 2026.8.3
 # 15 surface/viewport pairs, 105 compared fields (including the screenshot hash)
 # IDENTICAL on every field and every pixel against an explicit texture="none".
 ```
@@ -1379,7 +1379,7 @@ pnpm run check         # svelte-check
 pnpm run test:browser  # build the harness and drive it in a real browser
 
 # Before releasing a change that claims to be additive (minutes, not seconds):
-node harness/additivity.mjs ui-v2026.8.3
+node harness/additivity.mjs ee0db12   # ui 2026.8.3
 ```
 
 `pnpm test` includes the gates that compile the built package through the real
@@ -1410,7 +1410,7 @@ non-zero and naming the field on any difference.
 
 1. Change a component; bump `version` in `package.json` (CalVer).
 2. `pnpm build`, which runs `svelte-package` then `publint` (package.json/exports sanity).
-3. Commit, tag `ui-v<version>`, push the tag.
-4. `.github/workflows/publish-kit-typescript.yaml` (repo root) runs on that push and publishes via npm
-   OIDC trusted publishing: `gh run list -R radar-hooves/app-factory --workflow=publish-kit-typescript.yaml`.
+3. Merge to main. No tag.
+4. `.github/workflows/publish-kit-typescript.yaml` (repo root) runs on that push and publishes the new
+   version via npm OIDC trusted publishing: `gh run list -R radar-hooves/app-factory --workflow=publish-kit-typescript.yaml`.
    Confirm with `npm view @poodle64/ui version`.

package/dist/components/settings/index.d.ts

@@ -0,0 +1,3 @@
+import SettingsPage, { type SettingsDocument, type SettingValue } from './settings-page.svelte';
+export { nestSchema, nestValues, settingsLayout } from './nest.js';
+export { SettingsPage, SettingsPage as default, type SettingsDocument, type SettingValue };

package/dist/components/settings/index.js

@@ -0,0 +1,3 @@
+import SettingsPage, {} from './settings-page.svelte';
+export { nestSchema, nestValues, settingsLayout } from './nest.js';
+export { SettingsPage, SettingsPage as default };

package/dist/components/settings/nest.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The settings API is flat, keyed by dotted names (`intelligence.extraction_model`),
+ * and `<SchemaForm>` reads a `.` in a property name as a path. These nest the flat
+ * document along those paths, so every key is addressable, the change it reports
+ * carries the key back as `change.path`, and settings group by their domain. The
+ * form's generated layout does not descend into an object, so `settingsLayout`
+ * gives it one: a Group per domain, a Control per setting.
+ */
+import type { JsonSchema, UISchemaElement } from '../ui/schema-form/index.js';
+/** `{ 'a.b': 1, c: 2 }` → `{ a: { b: 1 }, c: 2 }`. */
+export declare function nestValues(flat: Record<string, unknown>): Record<string, unknown>;
+/** The same nesting for a flat object schema: each path segment becomes an object group. */
+export declare function nestSchema(schema: JsonSchema): JsonSchema;
+/** The layout `<SchemaForm>` renders a nested settings schema with; a group's label is its segment in sentence case. */
+export declare function settingsLayout(schema: JsonSchema): UISchemaElement;

package/dist/components/settings/nest.js

@@ -0,0 +1,58 @@
+/**
+ * The settings API is flat, keyed by dotted names (`intelligence.extraction_model`),
+ * and `<SchemaForm>` reads a `.` in a property name as a path. These nest the flat
+ * document along those paths, so every key is addressable, the change it reports
+ * carries the key back as `change.path`, and settings group by their domain. The
+ * form's generated layout does not descend into an object, so `settingsLayout`
+ * gives it one: a Group per domain, a Control per setting.
+ */
+/** `{ 'a.b': 1, c: 2 }` → `{ a: { b: 1 }, c: 2 }`. */
+export function nestValues(flat) {
+    const root = {};
+    for (const [key, value] of Object.entries(flat)) {
+        const parts = key.split('.');
+        const leaf = parts.pop() ?? key;
+        let node = root;
+        for (const part of parts) {
+            node = (node[part] ??= {});
+        }
+        node[leaf] = value;
+    }
+    return root;
+}
+/** The same nesting for a flat object schema: each path segment becomes an object group. */
+export function nestSchema(schema) {
+    const properties = {};
+    for (const [key, property] of Object.entries(schema.properties ?? {})) {
+        const parts = key.split('.');
+        const leaf = parts.pop() ?? key;
+        let node = properties;
+        for (const part of parts) {
+            node = (node[part] ??= { type: 'object', properties: {} }).properties ??= {};
+        }
+        node[leaf] = property;
+    }
+    return { ...schema, properties };
+}
+/** The layout `<SchemaForm>` renders a nested settings schema with; a group's label is its segment in sentence case. */
+export function settingsLayout(schema) {
+    const layout = {
+        type: 'VerticalLayout',
+        elements: layoutElements(schema, '#')
+    };
+    return layout;
+}
+function layoutElements(schema, scope) {
+    return Object.entries(schema.properties ?? {}).map(([key, child]) => {
+        const childScope = `${scope}/properties/${key}`;
+        if (child.type === 'object' && child.properties) {
+            const label = key.replaceAll('_', ' ');
+            return {
+                type: 'Group',
+                label: label.charAt(0).toUpperCase() + label.slice(1),
+                elements: layoutElements(child, childScope)
+            };
+        }
+        return { type: 'Control', scope: childScope };
+    });
+}

package/dist/components/settings/settings-page.svelte

@@ -0,0 +1,159 @@
+<!--
+	The runtime settings page for app-slices' settings routes: every declared
+	Setting, rendered from the JSON Schema `GET <endpoint>/` returns, nested by
+	dot path and laid out one group per domain (`nest.ts`), so an app that
+	declares a setting adds no code here. `<SchemaForm>` has no per-field reset,
+	so "default versus override, reset in one act" (the operator's own ask) is
+	the panel below it. An app mounts it as its settings route's whole body.
+-->
+<script lang="ts" module>
+	import type { JsonSchema } from '../ui/schema-form/index.js';
+
+	export type SettingValue = boolean | number | string;
+
+	/** What `GET <endpoint>/` answers: app-slices' `SettingsDocument`. */
+	export type SettingsDocument = {
+		schema: JsonSchema;
+		value: Record<string, SettingValue>;
+		defaults: Record<string, SettingValue>;
+	};
+</script>
+
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import { toast } from 'svelte-sonner';
+	import { Button } from '../ui/button/index.js';
+	import { LoadingState } from '../ui/loading-state/index.js';
+	import { PageHeader } from '../ui/page-header/index.js';
+	import { Panel } from '../ui/panel/index.js';
+	import { SchemaForm, type SchemaFormChange } from '../ui/schema-form/index.js';
+	import { nestSchema, nestValues, settingsLayout } from './nest.js';
+
+	let {
+		/** The app's settings routes, defaulting to where the factory mounts them. */
+		endpoint = '/api/settings',
+		title = 'Application',
+		subtitle = "Runtime settings this deployment's operator can change without a code change or a deploy.",
+		/** What a 401 does: the app's own re-authentication (its API client's redirect), since only the app knows its sign-in. */
+		onunauthorized
+	}: {
+		endpoint?: string;
+		title?: string;
+		subtitle?: string;
+		onunauthorized?: () => void;
+	} = $props();
+
+	const TIMEOUT_MS = 30_000;
+
+	let doc = $state<SettingsDocument | null>(null);
+	let loadError = $state<string | null>(null);
+	/** What `<SchemaForm>` renders: the flat document nested by dot path; the flat one stays the state. */
+	let formSchema = $derived(doc ? nestSchema(doc.schema) : null);
+	let formValue = $derived(doc ? nestValues(doc.value) : {});
+	let formLayout = $derived(formSchema ? settingsLayout(formSchema) : undefined);
+	/** Keys whose effective value differs from its default — derived, never a second copy to disagree with the API. */
+	let overridden = $derived(
+		doc ? Object.keys(doc.value).filter((key) => doc!.value[key] !== doc!.defaults[key]) : []
+	);
+
+	/** The body on success, or the household error body's `message` (`{"error", "message"}`). */
+	async function call<T>(
+		path: string,
+		init: RequestInit = {}
+	): Promise<{ data: T } | { failure: string }> {
+		let response: Response;
+		try {
+			response = await fetch(`${endpoint}/${path}`, {
+				...init,
+				credentials: 'include',
+				signal: AbortSignal.timeout(TIMEOUT_MS)
+			});
+		} catch {
+			return { failure: 'The server could not be reached.' };
+		}
+		if (response.status === 401) onunauthorized?.();
+		const body = await response.json().catch(() => null);
+		if (response.ok && body !== null) return { data: body as T };
+		if (response.ok) return { failure: 'The server did not answer with settings.' };
+		return { failure: body?.message ?? `The server answered ${response.status}.` };
+	}
+
+	async function load() {
+		const result = await call<SettingsDocument>('');
+		if ('failure' in result) {
+			loadError = result.failure;
+			return;
+		}
+		loadError = null;
+		doc = result.data;
+	}
+
+	onMount(load);
+
+	async function save(key: string, path: string, init: RequestInit, failure: string) {
+		const result = await call<{ value: SettingValue }>(path, init);
+		if ('failure' in result) {
+			toast.error(failure, { description: result.failure });
+			return false;
+		}
+		doc!.value[key] = result.data.value;
+		return true;
+	}
+
+	async function handleChange(_next: Record<string, unknown>, change: SchemaFormChange) {
+		if (!doc) return;
+		const key = change.path;
+		const previous = doc.value[key];
+		doc.value[key] = change.value as SettingValue;
+		const saved = await save(
+			key,
+			encodeURIComponent(key),
+			{
+				method: 'PATCH',
+				headers: { 'content-type': 'application/json' },
+				body: JSON.stringify({ value: change.value })
+			},
+			'Could not save the setting'
+		);
+		if (!saved && previous !== undefined) doc.value[key] = previous;
+	}
+
+	function reset(key: string) {
+		void save(key, `${encodeURIComponent(key)}/reset`, { method: 'POST' }, 'Could not reset the setting');
+	}
+
+	function label(key: string): string {
+		const properties = (doc!.schema as { properties?: Record<string, { title?: string }> }).properties;
+		return properties?.[key]?.title ?? key;
+	}
+</script>
+
+<PageHeader {title} {subtitle} />
+
+{#if loadError}
+	<Panel title="Could not load settings" tone="destructive">{loadError}</Panel>
+{:else if !doc}
+	<LoadingState message="Loading…" class="mt-16" />
+{:else}
+	<Panel title="Settings">
+		<SchemaForm schema={formSchema!} uischema={formLayout} value={formValue} onChange={handleChange} />
+	</Panel>
+
+	{#if overridden.length}
+		<Panel title="Overridden from default" subtitle="{overridden.length} changed">
+			<ul class="grid gap-2">
+				{#each overridden as key (key)}
+					<li class="flex items-center justify-between gap-4">
+						<span class="text-sm">
+							{label(key)}
+							<span class="text-muted-foreground font-mono text-xs">
+								default: {doc.defaults[key]}
+							</span>
+						</span>
+						<Button variant="outline" size="sm" onclick={() => reset(key)}>Reset</Button>
+					</li>
+				{/each}
+			</ul>
+		</Panel>
+	{/if}
+{/if}

package/dist/components/settings/settings-page.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { JsonSchema } from '../ui/schema-form/index.js';
+export type SettingValue = boolean | number | string;
+/** What `GET <endpoint>/` answers: app-slices' `SettingsDocument`. */
+export type SettingsDocument = {
+    schema: JsonSchema;
+    value: Record<string, SettingValue>;
+    defaults: Record<string, SettingValue>;
+};
+type $$ComponentProps = {
+    endpoint?: string;
+    title?: string;
+    subtitle?: string;
+    onunauthorized?: () => void;
+};
+declare const SettingsPage: import("svelte").Component<$$ComponentProps, {}, "">;
+type SettingsPage = ReturnType<typeof SettingsPage>;
+export default SettingsPage;

package/dist/components/ui/input-group/input-group-input.svelte.d.ts

@@ -2,7 +2,7 @@ declare const InputGroupInput: import("svelte").Component<(Omit<import("svelte/e
     type: "file";
     files?: FileList;
 } | {
-    type?: "number" | "month" | "url" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "email" | "week" | "date" | "time" | "image" | "datetime-local" | "password" | "range";
+    type?: "number" | "month" | "url" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "email" | "week" | "date" | "time" | "datetime-local" | "image" | "password" | "range";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.9.23",
+	"version": "2026.10.0",
 	"description": "Household shared component layer: shadcn-svelte primitives (bits-ui) plus the composed page chrome every app builds its routes from, restyled by each app's @poodle64/design-tokens alias layer. One fix reaches every app.",
 	"type": "module",
 	"license": "MIT",
@@ -42,6 +42,10 @@
 			"types": "./dist/components/alerts/index.d.ts",
 			"svelte": "./dist/components/alerts/index.js"
 		},
+		"./settings": {
+			"types": "./dist/components/settings/index.d.ts",
+			"svelte": "./dist/components/settings/index.js"
+		},
 		"./*": {
 			"types": "./dist/components/ui/*/index.d.ts",
 			"svelte": "./dist/components/ui/*/index.js"

package/registry/component-map.json

@@ -1,7 +1,7 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.9.23",
+		"version": "2026.10.0",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
 		"componentCount": 61,

package/registry/component-map.md

@@ -1,7 +1,7 @@
 # @poodle64/ui — situation → component map
 
 <!-- GENERATED by scripts/generate-registry.mjs from scripts/situations.json + package source. DO NOT EDIT. -->
-Generated from `@poodle64/ui@2026.9.23`. 61 components, 17 situations.
+Generated from `@poodle64/ui@2026.10.0`. 61 components, 17 situations.
 
 **Read this before writing a `<div>`.** Find the SITUATION you are in below, then compose the component named for it — do not hand-build it from raw `Card` or utility classes. Import is `import { Name } from '<import path>'`. Props marked `?` are optional. This map is the retrieval step the [`frontend-design` skill] makes mandatory; the [CHI 2026 study] measured composing-from-a-registry at 95% design-system compliance against 71% for writing the CSS from a prose style guide.