@poodle64/ui 2026.10.11 → 2026.10.13

package/README.md

@@ -357,6 +357,19 @@ section you are reading, both panes scrolling independently from `md`.
 | `sections`    | Groups of `NavItem`, bare items, or a mix: the rail's own vocabulary.         |
 | `currentPath` | Which row is the page. Prefix-matched on the segment boundary, as the rail is. |
 | `listLabel`   | The list's accessible name. Defaults to `Settings sections`.                   |
+| `selected`, `onSelect` | A single-route app (no `/settings/*` routes): instead of `currentPath`, pass sections as `{ id, label, icon? }`, the current `id` and a callback. Rows become buttons; the app owns the state. |
+
+A setting inside a section is a `SettingsRow`: `label`, optional `description`, the control as children (a Switch, a Select, a Button), and `controlId` to tie the label to the control. Use it in `<Panel pad={false}>`; the row carries its own padding and the rule between rows.
+
+```svelte
+<SettingsShell sections={[{ items: [{ id: 'library', label: 'Library' }] }]} selected={active} onSelect={(id) => (active = id)}>
+	<Panel title="Library" pad={false}>
+		<SettingsRow label="Rescan on start" description="Look for new files at launch." controlId="rescan">
+			<Switch id="rescan" bind:checked={rescan} />
+		</SettingsRow>
+	</Panel>
+</SettingsShell>
+```
 
 A row at the settings ROOT (`/settings`) needs `exact: true`, or its prefix match
 keeps it lit on every section beneath it alongside the section's own row.

package/dist/components/ui/app-dialog/app-dialog.svelte

@@ -81,7 +81,7 @@
 				</span>
 			{/if}
 			<div class="min-w-0 flex-1">
-				<Dialog.Title class="font-display text-lg leading-tight font-semibold tracking-tight"
+				<Dialog.Title class="font-display text-lg leading-tight font-semibold tracking-[var(--ds-font-display-tracking,-0.025em)]"
 					>{title}</Dialog.Title
 				>
 				{#if subtitle}

package/dist/components/ui/app-shell/app-nav.svelte

@@ -35,6 +35,8 @@
 		collapsed = false,
 		label = 'Primary',
 		onNavigate,
+		selected,
+		onSelect,
 		firstLink = $bindable(null),
 		class: className
 	}: {
@@ -47,6 +49,15 @@
 		label?: string;
 		/** Fired after any nav link activates — AppShell uses it to shut the drawer. */
 		onNavigate?: () => void;
+		/**
+		 * State-driven mode, for a single-route app whose sections swap in place.
+		 * With `onSelect` set each row is a BUTTON that calls it with the item's
+		 * `href` (the key; it is never navigated to), and the row whose key equals
+		 * `selected` is the current one. Children are not disclosed in this mode.
+		 * SettingsShell is the caller; an app passes `id`s there, not hrefs.
+		 */
+		selected?: string;
+		onSelect?: (key: string) => void;
 		/**
 		 * The first rendered link, bound out. AppShell moves focus here when this
 		 * list is the content of an overlay, so a keyboard user lands inside the
@@ -167,28 +178,10 @@
 		still the active row. A childless item never reaches this at all —
 		`hasActiveNavChild` is false for it — so the flat case is untouched.
 	-->
-	{@const within = hasActiveNavChild(item, currentPath)}
-	{@const active = !within && isNavItemActive(item, currentPath)}
-	<a
-		bind:this={
-			() => firstLink,
-			(node) => {
-				if (opts.first) firstLink = node;
-			}
-		}
-		id={opts.labelId}
-		href={item.href}
-		class="ds-nav-item"
-		data-active={active ? 'true' : undefined}
-		data-within={within ? 'true' : undefined}
-		data-child={opts.child ? 'true' : undefined}
-		aria-current={active ? 'page' : undefined}
-		title={collapsed ? item.label : undefined}
-		target={item.external ? '_blank' : undefined}
-		rel={item.external ? 'noreferrer noopener' : undefined}
-		onclick={onNavigate}
-		onkeydown={onNavKeydown}
-	>
+	{@const stateful = onSelect !== undefined}
+	{@const within = !stateful && hasActiveNavChild(item, currentPath)}
+	{@const active = stateful ? item.href === selected : !within && isNavItemActive(item, currentPath)}
+	{#snippet body()}
 		{#if active}
 			<span class="ds-nav-indicator"></span>
 		{/if}
@@ -205,7 +198,51 @@
 		{#if item.badge !== undefined && !collapsed}
 			<span class="ds-nav-badge">{item.badge}</span>
 		{/if}
-	</a>
+	{/snippet}
+	{#if stateful}
+		<button
+			bind:this={
+				() => firstLink,
+				(node) => {
+					if (opts.first) firstLink = node;
+				}
+			}
+			type="button"
+			class="ds-nav-item w-full text-start"
+			data-active={active ? 'true' : undefined}
+			aria-current={active ? 'true' : undefined}
+			title={collapsed ? item.label : undefined}
+			onclick={() => {
+				onSelect(item.href);
+				onNavigate?.();
+			}}
+		>
+			{@render body()}
+		</button>
+	{:else}
+		<a
+			bind:this={
+				() => firstLink,
+				(node) => {
+					if (opts.first) firstLink = node;
+				}
+			}
+			id={opts.labelId}
+			href={item.href}
+			class="ds-nav-item"
+			data-active={active ? 'true' : undefined}
+			data-within={within ? 'true' : undefined}
+			data-child={opts.child ? 'true' : undefined}
+			aria-current={active ? 'page' : undefined}
+			title={collapsed ? item.label : undefined}
+			target={item.external ? '_blank' : undefined}
+			rel={item.external ? 'noreferrer noopener' : undefined}
+			onclick={onNavigate}
+			onkeydown={onNavKeydown}
+		>
+			{@render body()}
+		</a>
+	{/if}
 {/snippet}
 
 <nav

package/dist/components/ui/app-shell/app-nav.svelte.d.ts

@@ -9,6 +9,15 @@ type $$ComponentProps = {
     label?: string;
     /** Fired after any nav link activates — AppShell uses it to shut the drawer. */
     onNavigate?: () => void;
+    /**
+     * State-driven mode, for a single-route app whose sections swap in place.
+     * With `onSelect` set each row is a BUTTON that calls it with the item's
+     * `href` (the key; it is never navigated to), and the row whose key equals
+     * `selected` is the current one. Children are not disclosed in this mode.
+     * SettingsShell is the caller; an app passes `id`s there, not hrefs.
+     */
+    selected?: string;
+    onSelect?: (key: string) => void;
     /**
      * The first rendered link, bound out. AppShell moves focus here when this
      * list is the content of an overlay, so a keyboard user lands inside the

package/dist/components/ui/app-shell/app-shell.svelte

@@ -457,7 +457,7 @@
 					slot to re-earn a behaviour the shell could give everyone is the shell
 					failing to ship something good.
 				-->
-				<span class="font-display text-body hidden font-semibold tracking-tight sm:inline"
+				<span class="font-display text-body hidden font-semibold tracking-[var(--ds-font-display-tracking,-0.025em)] sm:inline"
 					>{brandTitle}</span
 				>
 			{/if}

package/dist/components/ui/list-shell/list-shell.svelte

@@ -62,7 +62,7 @@
 		{...restProps}
 	>
 		<div class="flex flex-none items-center gap-2 px-5 pt-5 pb-3">
-			<h2 class="font-display text-display flex-1 truncate font-semibold tracking-tight">
+			<h2 class="font-display text-display flex-1 truncate font-semibold tracking-[var(--ds-font-display-tracking,-0.025em)]">
 				{title}
 			</h2>
 			{#if actions}{@render actions()}{/if}

package/dist/components/ui/page-header/page-header.svelte

@@ -95,7 +95,7 @@
 			{/if}
 			{#if title}
 				<div class="flex items-center gap-2">
-					<h1 class="font-display text-display leading-tight font-semibold tracking-[-0.02em]">
+					<h1 class="font-display text-display leading-tight font-semibold tracking-[var(--ds-font-display-tracking,-0.02em)]">
 						{title}
 					</h1>
 					{#if info}

package/dist/components/ui/settings-row/index.d.ts

@@ -0,0 +1,2 @@
+export { default as SettingsRow } from './settings-row.svelte';
+export { default } from './settings-row.svelte';

package/dist/components/ui/settings-row/index.js

@@ -0,0 +1,2 @@
+export { default as SettingsRow } from './settings-row.svelte';
+export { default } from './settings-row.svelte';

package/dist/components/ui/settings-row/settings-row.svelte

@@ -0,0 +1,52 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+
+	// One setting: its name and what it does on the left, its control on the
+	// right (a Switch, a Select, a Button). Every settings page in the estate
+	// hand-built this, and each spaced it differently.
+	//
+	// Put rows in a Panel with `pad={false}`: the row carries its own padding so
+	// the rule between adjacent rows runs edge to edge, and the first row has no
+	// rule above it.
+	let {
+		label,
+		description,
+		controlId,
+		children,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+		label: string;
+		/** What the setting does or costs; wraps beneath the label. */
+		description?: string;
+		/** The control's `id`: the label then names it (click focuses, screen reader announces). */
+		controlId?: string;
+		/** The control. */
+		children: Snippet;
+	} = $props();
+</script>
+
+<div
+	bind:this={ref}
+	data-slot="settings-row"
+	class={cn(
+		'border-border flex flex-wrap items-center justify-between gap-x-6 gap-y-2 border-t px-4 py-3 first:border-t-0',
+		className
+	)}
+	{...restProps}
+>
+	<div class="min-w-48 flex-1">
+		{#if controlId}
+			<label for={controlId} class="text-body block leading-tight font-medium">{label}</label>
+		{:else}
+			<div class="text-body leading-tight font-medium">{label}</div>
+		{/if}
+		{#if description}
+			<p class="text-muted-foreground mt-1 text-sm">{description}</p>
+		{/if}
+	</div>
+	<div class="flex flex-none items-center gap-2">{@render children()}</div>
+</div>

package/dist/components/ui/settings-row/settings-row.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+    label: string;
+    /** What the setting does or costs; wraps beneath the label. */
+    description?: string;
+    /** The control's `id`: the label then names it (click focuses, screen reader announces). */
+    controlId?: string;
+    /** The control. */
+    children: Snippet;
+};
+declare const SettingsRow: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type SettingsRow = ReturnType<typeof SettingsRow>;
+export default SettingsRow;

package/dist/components/ui/settings-shell/index.d.ts

@@ -1,2 +1,3 @@
 export { default as SettingsShell } from './settings-shell.svelte';
+export type { SettingsSection, SettingsSectionGroup } from './settings-shell.svelte';
 export { default } from './settings-shell.svelte';

package/dist/components/ui/settings-shell/settings-shell.svelte

@@ -1,3 +1,19 @@
+<script lang="ts" module>
+	import type { IconComponent } from '../app-shell/types.js';
+
+	/** A section of a single-route app: identified by `id`, switched by state. */
+	export interface SettingsSection {
+		id: string;
+		label: string;
+		icon?: IconComponent;
+		badge?: string | number;
+	}
+	export interface SettingsSectionGroup {
+		heading?: string;
+		items: SettingsSection[];
+	}
+</script>
+
 <script lang="ts">
 	/**
 	 * The settings destination: a grouped section list beside the section you are
@@ -59,32 +75,67 @@
 	import type { NavSource } from '../app-shell/types.js';
 	import { cn, type WithElementRef } from '../../../utils.js';
 
+	type Shared = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+		/** The list's accessible name. */
+		listLabel?: string;
+		children: Snippet;
+	};
+
 	let {
 		sections,
 		currentPath,
+		selected,
+		onSelect,
 		listLabel = 'Settings sections',
 		children,
 		ref = $bindable(null),
 		class: className,
 		...restProps
-	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
-		/**
-		 * The sections, as the package's own navigation vocabulary: groups of
-		 * `NavItem` (`{ heading, items }`), bare items, or a mix. The same type the
-		 * rail takes, so a row is the same row everywhere in the household and an
-		 * app types its settings list against something it already has.
-		 *
-		 * A row at the settings ROOT (`/settings`) needs `exact: true`, or its
-		 * prefix match keeps it lit on every section beneath it alongside the
-		 * section's own row.
-		 */
-		sections: NavSource;
-		/** The active path. Apps pass `page.url.pathname`, as they do to AppShell. */
-		currentPath?: string;
-		/** The list's accessible name. */
-		listLabel?: string;
-		children: Snippet;
-	} = $props();
+	}: Shared &
+		(
+			| {
+					/**
+					 * ROUTED: the sections, as the package's own navigation vocabulary:
+					 * groups of `NavItem` (`{ heading, items }`), bare items, or a mix.
+					 * The same type the rail takes, so a row is the same row everywhere
+					 * in the household.
+					 *
+					 * A row at the settings ROOT (`/settings`) needs `exact: true`, or
+					 * its prefix match keeps it lit on every section beneath it.
+					 */
+					sections: NavSource;
+					/** The active path. Apps pass `page.url.pathname`, as to AppShell. */
+					currentPath?: string;
+					selected?: undefined;
+					onSelect?: undefined;
+			  }
+			| {
+					/**
+					 * STATE-DRIVEN, for a single-route app whose sections swap in place
+					 * (canonical-app-shape §Applicability): groups of `SettingsSection`
+					 * (`{ id, label, icon? }`) rather than `NavItem`, since nothing is
+					 * navigated to. Rows are buttons; `selected` is the current `id` and
+					 * `onSelect` fires with the `id` that was chosen. The app owns the
+					 * state, so a deep link or a failure that opens a section just sets
+					 * `selected`.
+					 */
+					sections: readonly (SettingsSection | SettingsSectionGroup)[];
+					selected: string;
+					onSelect: (id: string) => void;
+					currentPath?: undefined;
+			  }
+		) = $props();
+
+	/** The state-driven sections as the rail's vocabulary, the `id` standing as the key. */
+	const nav = $derived<NavSource>(
+		onSelect
+			? (sections as readonly (SettingsSection | SettingsSectionGroup)[]).map((entry) =>
+					'items' in entry
+						? { heading: entry.heading, items: entry.items.map(({ id, ...rest }) => ({ ...rest, href: id })) }
+						: (({ id, ...rest }) => ({ ...rest, href: id }))(entry)
+				)
+			: (sections as NavSource)
+	);
 </script>
 
 <div bind:this={ref} class={cn('ds-settings', className)} {...restProps}>
@@ -100,8 +151,10 @@
 		one line beside its icon at comfortable density.
 	-->
 	<AppNav
-		nav={sections}
+		{nav}
 		{currentPath}
+		{selected}
+		{onSelect}
 		label={listLabel}
 		class="border-border bg-muted/30 flex-none border-b md:w-60 md:border-b-0 md:border-e"
 	/>

package/dist/components/ui/settings-shell/settings-shell.svelte.d.ts

@@ -1,3 +1,15 @@
+import type { IconComponent } from '../app-shell/types.js';
+/** A section of a single-route app: identified by `id`, switched by state. */
+export interface SettingsSection {
+    id: string;
+    label: string;
+    icon?: IconComponent;
+    badge?: string | number;
+}
+export interface SettingsSectionGroup {
+    heading?: string;
+    items: SettingsSection[];
+}
 /**
      * The settings destination: a grouped section list beside the section you are
      * reading, inside AppShell's content area.
@@ -55,24 +67,41 @@ import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import type { NavSource } from '../app-shell/types.js';
 import { type WithElementRef } from '../../../utils.js';
-type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+type Shared = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+    /** The list's accessible name. */
+    listLabel?: string;
+    children: Snippet;
+};
+type $$ComponentProps = Shared & ({
     /**
-     * The sections, as the package's own navigation vocabulary: groups of
-     * `NavItem` (`{ heading, items }`), bare items, or a mix. The same type the
-     * rail takes, so a row is the same row everywhere in the household and an
-     * app types its settings list against something it already has.
+     * ROUTED: the sections, as the package's own navigation vocabulary:
+     * groups of `NavItem` (`{ heading, items }`), bare items, or a mix.
+     * The same type the rail takes, so a row is the same row everywhere
+     * in the household.
      *
-     * A row at the settings ROOT (`/settings`) needs `exact: true`, or its
-     * prefix match keeps it lit on every section beneath it alongside the
-     * section's own row.
+     * A row at the settings ROOT (`/settings`) needs `exact: true`, or
+     * its prefix match keeps it lit on every section beneath it.
      */
     sections: NavSource;
-    /** The active path. Apps pass `page.url.pathname`, as they do to AppShell. */
+    /** The active path. Apps pass `page.url.pathname`, as to AppShell. */
     currentPath?: string;
-    /** The list's accessible name. */
-    listLabel?: string;
-    children: Snippet;
-};
+    selected?: undefined;
+    onSelect?: undefined;
+} | {
+    /**
+     * STATE-DRIVEN, for a single-route app whose sections swap in place
+     * (canonical-app-shape §Applicability): groups of `SettingsSection`
+     * (`{ id, label, icon? }`) rather than `NavItem`, since nothing is
+     * navigated to. Rows are buttons; `selected` is the current `id` and
+     * `onSelect` fires with the `id` that was chosen. The app owns the
+     * state, so a deep link or a failure that opens a section just sets
+     * `selected`.
+     */
+    sections: readonly (SettingsSection | SettingsSectionGroup)[];
+    selected: string;
+    onSelect: (id: string) => void;
+    currentPath?: undefined;
+});
 declare const SettingsShell: import("svelte").Component<$$ComponentProps, {}, "ref">;
 type SettingsShell = ReturnType<typeof SettingsShell>;
 export default SettingsShell;

package/dist/components/ui/stat-list/stat-list.svelte

@@ -67,7 +67,7 @@
 					{/if}
 					<span
 						class="ds-tabular text-stat font-mono leading-none font-semibold {item.muted
-							? 'text-muted-foreground/60'
+							? 'text-muted-foreground'
 							: ''}">{item.value}</span
 					>
 					{#if item.sub}

package/dist/styles.css

@@ -446,6 +446,19 @@
 			var(--ds-shadow-sm);
 	}
 
+	/**
+	 * How the display face is set. An app says it once in its palette
+	 * (`--ds-font-display-transform: uppercase; --ds-font-display-tracking:
+	 * 0.04em`) and every place the factory sets --ds-font-display follows: this
+	 * rule for `.font-display`, the components' own tracking, .ds-prose and the
+	 * librarian's markdown. Unset, each falls back to `inherit`, which is what the
+	 * property did before, so an app that sets neither renders as it always did.
+	 */
+	.font-display {
+		text-transform: var(--ds-font-display-transform, inherit);
+		letter-spacing: var(--ds-font-display-tracking, inherit);
+	}
+
 	/** Tabular figures, so a column of numbers aligns. */
 	.ds-tabular {
 		font-variant-numeric: tabular-nums;
@@ -737,7 +750,7 @@
 		   form. The literal keeps this rule correct on its own; the var keeps an
 		   app's override flowing through. */
 		letter-spacing: var(--tracking-eyebrow, 0.06em);
-		color: color-mix(in oklch, var(--ds-nav-ink-muted) 70%, transparent);
+		color: var(--ds-nav-ink-muted);
 	}
 
 	/* A count badge is small text on a tint, so it carries the 4.5:1 text floor
@@ -1144,6 +1157,8 @@
 	.ds-prose h3,
 	.ds-prose h4 {
 		font-family: var(--ds-font-display);
+		text-transform: var(--ds-font-display-transform, inherit);
+		letter-spacing: var(--ds-font-display-tracking, inherit);
 		font-weight: 600;
 		line-height: 1.25;
 		margin-block: var(--ds-spacing-lg) var(--ds-spacing-sm);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.10.11",
+	"version": "2026.10.13",
 	"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",

package/registry/component-map.json

@@ -1,10 +1,10 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.10.11",
+		"version": "2026.10.13",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 68,
+		"componentCount": 69,
 		"situationCount": 19
 	},
 	"situations": [
@@ -416,9 +416,16 @@
 					"name": "SettingsShell",
 					"dir": "settings-shell",
 					"import": "@poodle64/ui/settings-shell",
-					"props": "sections, children, currentPath?, listLabel?",
+					"props": "sections, children, currentPath?, selected?, onSelect?, listLabel?",
 					"insteadOf": "a hand-built two-pane settings layout, or a card of tab links in a grid, per app"
 				},
+				{
+					"name": "SettingsRow",
+					"dir": "settings-row",
+					"import": "@poodle64/ui/settings-row",
+					"props": "label, description?, controlId?, children",
+					"insteadOf": "a hand-built label + description + control row inside a settings Panel (use Panel pad={false})"
+				},
 				{
 					"name": "About",
 					"dir": "about",

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.10.11`. 68 components, 19 situations.
+Generated from `@poodle64/ui@2026.10.13`. 69 components, 19 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.
 
@@ -167,7 +167,8 @@ _The one settings surface: a grouped section list beside the section you are rea
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
-| `SettingsShell` | `@poodle64/ui/settings-shell` | `sections, children, currentPath?, listLabel?` | a hand-built two-pane settings layout, or a card of tab links in a grid, per app |
+| `SettingsShell` | `@poodle64/ui/settings-shell` | `sections, children, currentPath?, selected?, onSelect?, listLabel?` | a hand-built two-pane settings layout, or a card of tab links in a grid, per app |
+| `SettingsRow` | `@poodle64/ui/settings-row` | `label, description?, controlId?, children` | a hand-built label + description + control row inside a settings Panel (use Panel pad={false}) |
 | `About` | `@poodle64/ui/about` | `name, version, description?, brand?, links?, diagnostics?, writeClipboard?` | a per-app About page or dialogue with duplicated version, links and diagnostic copying |
 
 ## A dialog or overlay