@poodle64/ui 2026.9.16 → 2026.9.18

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

@@ -0,0 +1,111 @@
+<script lang="ts">
+	/**
+	 * The settings destination: a grouped section list beside the section you are
+	 * reading, inside AppShell's content area.
+	 *
+	 * Two PANES, not a panel and not a drawer. The distinction is load-bearing:
+	 * a panel overlays and closes, and this package carries a standing directive
+	 * against side panels for work you are actually doing. These panes divide and
+	 * persist, each scrolling on its own, so a long settings page never pushes the
+	 * section list out of reach.
+	 *
+	 * The list renders through AppNav rather than a row renderer of its own, and
+	 * that is the whole reason this component is small. AppNav already owns the
+	 * group eyebrow, the active row's leading edge and tint and weight, the
+	 * `aria-current="page"`, the segment-safe prefix match, truncation, and the
+	 * density ramp — and it is exported in its own right precisely so a navigation
+	 * list that belongs in a PAGE is built from the same affordance rather than
+	 * hand-copied. The estate has already paid for the alternative once: one app's
+	 * inner nav had reimplemented the active indicator independently of its own
+	 * top bar. A second row renderer here would re-commit that drift one
+	 * destination down, on the one surface every app is about to adopt at once.
+	 *
+	 * Grouping is by WHOSE setting it is — the person's, then the workspace's —
+	 * because that is the only split a reader can predict: "yours" changes what
+	 * you see, "this company" changes what everyone sees. A group whose `items`
+	 * is empty renders nothing (`toGroups` drops it), so an app with no personal
+	 * sections yet can leave the group in its list rather than stubbing a row that
+	 * leads nowhere.
+	 *
+	 * One label per row, nothing beneath it. A description long enough to be worth
+	 * reading does not fit a 240px column: every one of them truncated to an
+	 * ellipsis and told the reader less than the label already did (measured
+	 * 16/09/2026 in a consumer, removed there the same day). The page introduces
+	 * its own sections — that is what Panel's `description` is for.
+	 *
+	 * No "Settings" heading. The shell's bar names the section it is on as of
+	 * 2026.9.16, so a heading here is the same word twice, one above the other.
+	 *
+	 * BELOW md the list STACKS above the content and the page scrolls as one.
+	 * A horizontally scrollable strip of the same rows was the obvious
+	 * alternative and loses on the requirement it was meant to serve — every
+	 * section reachable in one tap. A strip fits about two and a half rows at
+	 * 375px, so the rest are behind a sideways swipe with no scrollbar to
+	 * advertise them: a swipe THEN a tap, where a stack is a scroll the reader is
+	 * already doing. It also has to drop the group labels for width, which throws
+	 * away the one split the reader could predict, and it needs a second row
+	 * renderer in a horizontal mode — the drift this component exists to avoid.
+	 *
+	 * USE IT WITH `padded={false}` on AppShell. The list's border and tint have to
+	 * reach the content area's edges or the two panes read as a floating card, and
+	 * this component pads its own content pane to the shell's own rhythm
+	 * (`CONTENT_PADDING`) so the settings destination is not the one route whose
+	 * text sits somewhere else.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import AppNav from '../app-shell/app-nav.svelte';
+	import { CONTENT_PADDING } from '../app-shell/padding.js';
+	import type { NavSource } from '../app-shell/types.js';
+	import { cn, type WithElementRef } from '../../../utils.js';
+
+	let {
+		sections,
+		currentPath,
+		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();
+</script>
+
+<div bind:this={ref} class={cn('ds-settings', className)} {...restProps}>
+	<!--
+		Width, tint and rule as utilities rather than in styles.css, because AppNav
+		declares `flex-1` on this same element: a base-layer `flex: none` loses to
+		a utility by layer, whatever order it is written in, while a utility passed
+		through `cn()` is resolved by tailwind-merge — `flex-none` and `flex-1` are
+		one group, so the last one wins and it is this one.
+
+		15rem (240px) is measured, not picked: it is the width at which a
+		two-word section label ("Overhead suppliers", "Delegation limits") sits on
+		one line beside its icon at comfortable density.
+	-->
+	<AppNav
+		nav={sections}
+		{currentPath}
+		label={listLabel}
+		class="border-border bg-muted/30 flex-none border-b md:w-60 md:border-b-0 md:border-e"
+	/>
+	<div class={cn('ds-settings-pane', CONTENT_PADDING)}>
+		{@render children()}
+	</div>
+</div>

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

@@ -0,0 +1,78 @@
+/**
+     * The settings destination: a grouped section list beside the section you are
+     * reading, inside AppShell's content area.
+     *
+     * Two PANES, not a panel and not a drawer. The distinction is load-bearing:
+     * a panel overlays and closes, and this package carries a standing directive
+     * against side panels for work you are actually doing. These panes divide and
+     * persist, each scrolling on its own, so a long settings page never pushes the
+     * section list out of reach.
+     *
+     * The list renders through AppNav rather than a row renderer of its own, and
+     * that is the whole reason this component is small. AppNav already owns the
+     * group eyebrow, the active row's leading edge and tint and weight, the
+     * `aria-current="page"`, the segment-safe prefix match, truncation, and the
+     * density ramp — and it is exported in its own right precisely so a navigation
+     * list that belongs in a PAGE is built from the same affordance rather than
+     * hand-copied. The estate has already paid for the alternative once: one app's
+     * inner nav had reimplemented the active indicator independently of its own
+     * top bar. A second row renderer here would re-commit that drift one
+     * destination down, on the one surface every app is about to adopt at once.
+     *
+     * Grouping is by WHOSE setting it is — the person's, then the workspace's —
+     * because that is the only split a reader can predict: "yours" changes what
+     * you see, "this company" changes what everyone sees. A group whose `items`
+     * is empty renders nothing (`toGroups` drops it), so an app with no personal
+     * sections yet can leave the group in its list rather than stubbing a row that
+     * leads nowhere.
+     *
+     * One label per row, nothing beneath it. A description long enough to be worth
+     * reading does not fit a 240px column: every one of them truncated to an
+     * ellipsis and told the reader less than the label already did (measured
+     * 16/09/2026 in a consumer, removed there the same day). The page introduces
+     * its own sections — that is what Panel's `description` is for.
+     *
+     * No "Settings" heading. The shell's bar names the section it is on as of
+     * 2026.9.16, so a heading here is the same word twice, one above the other.
+     *
+     * BELOW md the list STACKS above the content and the page scrolls as one.
+     * A horizontally scrollable strip of the same rows was the obvious
+     * alternative and loses on the requirement it was meant to serve — every
+     * section reachable in one tap. A strip fits about two and a half rows at
+     * 375px, so the rest are behind a sideways swipe with no scrollbar to
+     * advertise them: a swipe THEN a tap, where a stack is a scroll the reader is
+     * already doing. It also has to drop the group labels for width, which throws
+     * away the one split the reader could predict, and it needs a second row
+     * renderer in a horizontal mode — the drift this component exists to avoid.
+     *
+     * USE IT WITH `padded={false}` on AppShell. The list's border and tint have to
+     * reach the content area's edges or the two panes read as a floating card, and
+     * this component pads its own content pane to the shell's own rhythm
+     * (`CONTENT_PADDING`) so the settings destination is not the one route whose
+     * text sits somewhere else.
+     */
+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>> & {
+    /**
+     * 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;
+};
+declare const SettingsShell: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type SettingsShell = ReturnType<typeof SettingsShell>;
+export default SettingsShell;

package/dist/styles.css

@@ -770,27 +770,24 @@
 		color: var(--ds-nav-ink);
 	}
 
-	/* The disclosed rows. The indent is measured against the parent's own
-	   geometry rather than picked: .ds-nav-item pads 0.625rem and the icon is
-	   1.125rem, so the icon's centre line sits at 1.1875rem — where the guide
-	   border goes — and 0.625rem of padding here plus the child's own 0.625rem
-	   lands its label at 2.5rem, exactly under the parent's. The border is a real
-	   affordance at fifteen rows, not decoration: it is what makes the run
-	   scannable as one section. */
 	/* The disclosed rows carry no guide rule. Indentation and the children's own
 	   icons already read as one group, and a line down the side is a second
-	   signal for a grouping that was never ambiguous. The indent is still
-	   measured against the parent's geometry rather than picked: `.ds-nav-item`
-	   pads 0.625rem and the icon is 1.125rem, so 1.1875rem plus 0.625rem here
-	   plus the child's own 0.625rem lands its label at 2.5rem, exactly under the
-	   parent's. */
+	   signal for a grouping that was never ambiguous. 8f39b02 removed the rule
+	   but not the 1px it was contributing to the indent (design-system#38): the
+	   border sat between this margin and this padding, so the child label
+	   landed 1px further right than the padding alone now gives it. Restored
+	   here instead, so the geometry — not a rule nobody can see — still carries
+	   it: `.ds-nav-item` pads 0.625rem and the icon is 1.125rem, so 1.1875rem
+	   (margin) + 0.625rem plus the former border's 1px (this padding) +
+	   0.625rem (the child's own padding) lands its label at 2.5rem, exactly
+	   under the parent's. */
 	.ds-nav-children {
 		display: flex;
 		flex-direction: column;
 		gap: 0.125rem;
 		margin-top: 0.125rem;
 		margin-left: 1.1875rem;
-		padding-left: 0.625rem;
+		padding-left: calc(0.625rem + 1px);
 	}
 
 	/* The rail's foot: where you configure the app, and which build you are on.
@@ -881,6 +878,64 @@
 		padding-inline: 0;
 	}
 
+	/* The settings destination's two panes (SettingsShell).
+
+	   Only the SHAPE is here; the list's width, tint and rule are utilities on the
+	   AppNav element itself, because AppNav declares `flex-1` there and a
+	   base-layer `flex: none` would lose to it by layer order rather than by
+	   position — the cascade trap recorded against `.ds-nav`'s ink. What is left is
+	   the axis swap and the scroll bounding, which nothing else declares.
+
+	   48rem is Tailwind's own --breakpoint-md, written literally for the reason
+	   `.ds-shell-rail` writes it literally: a media query cannot read a custom
+	   property, so an app that retunes md retunes this with it. */
+	.ds-settings {
+		display: flex;
+		flex-direction: column;
+		flex: 1 1 auto;
+	}
+
+	/* `min-height: 0` is what buys the two independent scrollers, and it is
+	   deliberately NOT set below md. A flex item is floored at its content height
+	   unless it is allowed to shrink past it, so without this neither pane ever
+	   scrolls and the whole content area does instead. Below md that floor is
+	   exactly what is wanted: the list stacks above the content and the page
+	   scrolls as one, which is the only sane arrangement on a phone — two nested
+	   scrollers at 375px is the sideways-scroll hazard this package already carries
+	   a gate for. */
+	@media (min-width: 48rem) {
+		.ds-settings {
+			flex-direction: row;
+			min-height: 0;
+		}
+	}
+
+	.ds-settings-pane {
+		flex: 1 1 auto;
+		min-width: 0;
+	}
+
+	/* The pane stacks its sections itself, so a settings page writes a run of
+	   Panels and no wrapper — the framing markup this surface exists to stop a
+	   consumer writing. 1.25rem is the package's existing section rhythm, the same
+	   gap `.ds-dialog-section` puts between adjacent sections.
+
+	   A margin rule rather than `display: flex; gap`, because at md and up this box
+	   is a height-bounded scroller: as a flex column its children carry
+	   `flex-shrink: 1` and get squashed toward min-content before the scrollbar is
+	   ever reached, so a tall section would compress instead of scrolling. Block
+	   flow overflows, which is what a scroller wants. */
+	.ds-settings-pane > * + * {
+		margin-top: 1.25rem;
+	}
+
+	@media (min-width: 48rem) {
+		.ds-settings-pane {
+			min-height: 0;
+			overflow-y: auto;
+		}
+	}
+
 	/* A hard ceiling on the whole shell, in the one unit that names the actual
 	   drawn surface rather than a percentage of an ancestor. `.ds-shell` is
 	   already `flex` with `overflow-hidden` in the component markup, which

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.9.16",
+	"version": "2026.9.18",
 	"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,11 +1,11 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.9.16",
+		"version": "2026.9.18",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 57,
-		"situationCount": 15
+		"componentCount": 60,
+		"situationCount": 17
 	},
 	"situations": [
 		{
@@ -33,6 +33,13 @@
 					"import": "@poodle64/ui/stat-list",
 					"props": "items, title?, info?",
 					"insteadOf": "a hand-built <dl> or a stack of label/value <div>s"
+				},
+				{
+					"name": "FactGrid",
+					"dir": "fact-grid",
+					"import": "@poodle64/ui/fact-grid",
+					"props": "facts",
+					"insteadOf": "the same figures inside a Panel or DetailPanel that already supplies the card — StatList's own border would nest a box in a box; FactGrid is the borderless, wrapping-grid answer for that spot"
 				}
 			]
 		},
@@ -150,8 +157,8 @@
 					"name": "Panel",
 					"dir": "panel",
 					"import": "@poodle64/ui/panel",
-					"props": "children, title?, subtitle?, icon?, action?, pad?",
-					"insteadOf": "raw Card + CardHeader + CardTitle assembled by hand on every route"
+					"props": "children, title?, subtitle?, description?, icon?, action?, footer?, tone?, pad?",
+					"insteadOf": "raw Card + CardHeader + CardTitle assembled by hand on every route; also the settings section — there is no separate SettingsSection, `description` wraps, `footer` carries Save/Cancel, `tone=\"destructive\"` is the danger zone"
 				}
 			]
 		},
@@ -274,6 +281,20 @@
 				}
 			]
 		},
+		{
+			"key": "document-evidence",
+			"title": "A document a machine read, with evidence outlined",
+			"description": "One page at a time, fitted to its pane both ways so an A4 statement and a tall receipt alike fill it, with what a reading points at outlined on the page — a hovered or clicked region with its label, a dashed 'where it looked' set, and a focus that zooms in and centres. The app supplies the page render (image, PDF canvas, anything) and the region coordinates as page fractions; this owns the fit/zoom/pan and the overlay only.",
+			"components": [
+				{
+					"name": "PageCanvas",
+					"dir": "page-canvas",
+					"import": "@poodle64/ui/page-canvas",
+					"props": "pageCount, page, currentPage?, regions?, lookedRegions?, activeRegionId?, focusedRegionId?, zoom?",
+					"insteadOf": "a hand-built page viewer per app (godswood's DocumentViewer, pebblestone's PdfViewer) each re-deriving fit/zoom/pan, now with no way to outline what was read (#839)"
+				}
+			]
+		},
 		{
 			"key": "page-frame",
 			"title": "The frame every route shares",
@@ -323,6 +344,20 @@
 				}
 			]
 		},
+		{
+			"key": "settings-destination",
+			"title": "The settings destination",
+			"description": "The one settings surface: a grouped section list beside the section you are reading, inside AppShell’s content area (give AppShell padded={false}). Sections are grouped by whose setting it is — the person’s, then the workspace’s. The sections themselves are Panels.",
+			"components": [
+				{
+					"name": "SettingsShell",
+					"dir": "settings-shell",
+					"import": "@poodle64/ui/settings-shell",
+					"props": "sections, children, currentPath?, listLabel?",
+					"insteadOf": "a hand-built two-pane settings layout, or a card of tab links in a grid, per app"
+				}
+			]
+		},
 		{
 			"key": "dialog-and-overlay",
 			"title": "A dialog or overlay",

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.16`. 57 components, 15 situations.
+Generated from `@poodle64/ui@2026.9.18`. 60 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.
 
@@ -23,6 +23,7 @@ _A block of plain figures read at a glance — an 'at a glance' strip — where
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
 | `StatList` | `@poodle64/ui/stat-list` | `items, title?, info?` | a hand-built <dl> or a stack of label/value <div>s |
+| `FactGrid` | `@poodle64/ui/fact-grid` | `facts` | the same figures inside a Panel or DetailPanel that already supplies the card — StatList's own border would nest a box in a box; FactGrid is the borderless, wrapping-grid answer for that spot |
 
 ## Comparing magnitudes across rows
 
@@ -81,7 +82,7 @@ _The generic titled card every route reaches for — an optional header with ico
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
-| `Panel` | `@poodle64/ui/panel` | `children, title?, subtitle?, icon?, action?, pad?` | raw Card + CardHeader + CardTitle assembled by hand on every route |
+| `Panel` | `@poodle64/ui/panel` | `children, title?, subtitle?, description?, icon?, action?, footer?, tone?, pad?` | raw Card + CardHeader + CardTitle assembled by hand on every route; also the settings section — there is no separate SettingsSection, `description` wraps, `footer` carries Save/Cancel, `tone="destructive"` is the danger zone |
 
 ## A form the app itself describes
 
@@ -118,6 +119,14 @@ _The estate's shared document-library surfaces — a faceted catalogue, one coll
 | `DocumentDetail` | `@poodle64/ui/document-detail` | `document, loading?, error?, collectionHref?, onOpenCollection?, actions?, children?` | a bespoke document page: identity dl, locations, tags and memberships hand-laid-out per app |
 | `SearchResults` | `@poodle64/ui/search-results` | `results, query?, total?, loading?, error?, resultHref?, onOpen?, onRetry?` | a hand-built ranked hit list minting its own highlight and relevance styling |
 
+## A document a machine read, with evidence outlined
+
+_One page at a time, fitted to its pane both ways so an A4 statement and a tall receipt alike fill it, with what a reading points at outlined on the page — a hovered or clicked region with its label, a dashed 'where it looked' set, and a focus that zooms in and centres. The app supplies the page render (image, PDF canvas, anything) and the region coordinates as page fractions; this owns the fit/zoom/pan and the overlay only._
+
+| Component | Import | Key props | Reach for it instead of |
+| --- | --- | --- | --- |
+| `PageCanvas` | `@poodle64/ui/page-canvas` | `pageCount, page, currentPage?, regions?, lookedRegions?, activeRegionId?, focusedRegionId?, zoom?` | a hand-built page viewer per app (godswood's DocumentViewer, pebblestone's PdfViewer) each re-deriving fit/zoom/pan, now with no way to outline what was read (#839) |
+
 ## The frame every route shares
 
 _The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column._
@@ -131,6 +140,14 @@ _The standing chrome — the app shell and its nav, the one page-title treatment
 | `ContextColumn` | `@poodle64/ui/context-column` | `stats, statsTitle?, statsInfo?, detail?, ariaLabel?` | a hand-built right-hand <aside> with a stat card and a detail pane |
 | `AppIdentity` | `@poodle64/ui/app-identity` | `user, workspace?, role?, entitlements?, onSignOut, onAccountSettings?, onSwitchTheme?` | a hand-rolled account/avatar dropdown wired to raw DropdownMenu.* + Avatar.* |
 
+## The settings destination
+
+_The one settings surface: a grouped section list beside the section you are reading, inside AppShell’s content area (give AppShell padded={false}). Sections are grouped by whose setting it is — the person’s, then the workspace’s. The sections themselves are Panels._
+
+| 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 |
+
 ## A dialog or overlay
 
 _A modal task and the pieces around it — the dialog frame, a section within its body, a ⌘K palette, an inline (i) hint._