@poodle64/ui 2026.9.19 → 2026.9.20

package/README.md

@@ -402,6 +402,64 @@ all three serve any route:
 truncates. Carry one or the other. A page writes a run of `Panel`s and no
 wrapper: the pane stacks them on the package's section rhythm itself.
 
+### A working list beside a page's own content
+
+AppShell has no second-column slot, on purpose: a module's own **pages**
+belong in the rail (`NavItem.children`), never a hand-rolled column beside it.
+A module's **data** (a queue, an inbox, a working list of things waiting on
+the user) is a different situation, not navigation, so it belongs in the page
+beside the content it serves, exactly as the settings destination does.
+`ListShell` is that shape: a foldable list, in the rail's own chrome, that
+vanishes entirely when closed and hands the freed width back to the page.
+
+```svelte
+<script lang="ts">
+	import AppShell from '@poodle64/ui/app-shell';
+	import ListShell from '@poodle64/ui/list-shell';
+
+	// Bind it to whatever already persists a user preference for this module:
+	// a module-scoped `.svelte.ts` store backed by localStorage, or the app's
+	// own settings. ListShell holds no storage of its own.
+	let listOpen = $state(true);
+</script>
+
+<!-- padded={false}: the list has to reach the content area's edge, flush
+     against the rail, or it reads as a floating card. -->
+<AppShell {nav} currentPath={page.url.pathname} padded={false}>
+	<div class="flex min-h-0 flex-1">
+		<ListShell title="Waiting on you" bind:open={listOpen}>
+			{#snippet actions()}
+				<Button size="icon" variant="outline" aria-label="Add documents"><Plus /></Button>
+			{/snippet}
+			<!-- tabs, group headings, rows: entirely this module's own -->
+		</ListShell>
+		<div class="min-w-0 flex-1">
+			{#if !listOpen}
+				<!-- The reopen control is this module's own markup, at whatever
+				     position it chooses; ListShell never places it. -->
+				<Button onclick={() => (listOpen = true)} aria-expanded={listOpen}>
+					Waiting on you <Badge>{waitingCount}</Badge>
+				</Button>
+			{/if}
+			<!-- the module's own content -->
+		</div>
+	</div>
+</AppShell>
+```
+
+| Prop       | Purpose                                                                      |
+| ---------- | ----------------------------------------------------------------------------- |
+| `title`    | The list's heading, in the shell's display face.                              |
+| `open`     | Bindable. Not persisted by this component; bind it to what already persists a preference for this module. |
+| `label`    | The landmark's accessible name. Defaults to `title`.                          |
+| `actions`  | Leading header actions beside the title: an "Add" button, a filter.           |
+
+Width is fixed at 25rem (400px) and not a prop, the same anti-drift discipline
+`SettingsShell` applies to its own 240px: one width, chosen once, rather than
+every module guessing its own. Below `md` this never renders, at either state,
+since a 400px column has nowhere to go beside a rail that is already a drawer
+there; a module's phone view is its own route.
+
 ### The content measure
 
 How wide the page body may get, chosen once in the layout from a scale of four:

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

@@ -0,0 +1,2 @@
+export { default as ListShell } from './list-shell.svelte';
+export { default } from './list-shell.svelte';

package/dist/components/ui/list-shell/index.js

@@ -0,0 +1,2 @@
+export { default as ListShell } from './list-shell.svelte';
+export { default } from './list-shell.svelte';

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

@@ -0,0 +1,149 @@
+<script lang="ts">
+	/**
+	 * ListShell — a module's working list, folded away and brought back by the
+	 * app that owns it, beside the content it serves.
+	 *
+	 * AppShell carries no second-column slot for this on purpose: `sidebar` was
+	 * such a slot until 2026.8.11, and what it produced was two apps rendering a
+	 * module's own PAGES beside the rail while the other seven rendered them
+	 * inside it — the shell shape differing per app, and in one app per module.
+	 * Operator ruling, 21/08/2026: no app supports an additional sidebar; a
+	 * section's own pages roll out beneath it in the rail (`NavItem.children`).
+	 * That ruling is about NAVIGATION. A working list is not navigation — it is
+	 * data the module owns (a queue of things waiting on the user), and
+	 * `20-sveltekit-frontend.md` already answers where that belongs: "a column
+	 * that is not NavItem-shaped … belongs in the page beside the content it
+	 * serves." `ContextColumn` is the household's other proof this is a real,
+	 * sanctioned shape — a page-level flanking `<aside>`, not a shell slot.
+	 *
+	 * So this is a companion to AppShell, exactly as `SettingsShell` is: the
+	 * shell provides ONE chrome (the rail, the bar, the content frame), and any
+	 * module reaches for this to add a foldable list beside its own content,
+	 * inside AppShell's content area. Every module gets the same list, not a
+	 * hand-rolled column per module — which is the actual thing the 21/08/2026
+	 * ruling exists to prevent, still true one level down.
+	 *
+	 * USE IT WITH `padded={false}` on AppShell, exactly as `SettingsShell`
+	 * requires: the list has to reach the content area's edge — flush against
+	 * the rail, with no gap — or it reads as a floating card rather than chrome.
+	 * It paints itself in the rail's OWN chrome tokens (`bg-shell`,
+	 * `text-shell-foreground`) for the same reason: a list that is chrome reads
+	 * as chrome, not as a panel someone built inside the page.
+	 *
+	 * Width is fixed at 25rem (400px), measured off the operator's approved
+	 * mockup (radar-hooves/godswood#839, Focus-List.dc.html) rather than picked,
+	 * and not exposed as a prop — the same anti-drift discipline `SettingsShell`
+	 * applies to its own 240px: one width, chosen once, or ten modules each
+	 * guess their own.
+	 *
+	 * Open/closed is the CALLER's state (`open`, bindable), the same way
+	 * AppShell's own `collapsed` is: bind it to persist the choice across
+	 * reloads (a module-scoped `$state` in a `.svelte.ts` file, synced to
+	 * `localStorage` — `svelte-basics.md` §shared state — or the app's own
+	 * settings store). This component holds no storage of its own, on purpose:
+	 * a module that already persists user preferences server-side should not
+	 * gain a second, disagreeing mechanism here.
+	 *
+	 * When `open` is false this renders NOTHING — no placeholder, no rail — so
+	 * the content beside it gets the freed width back, exactly like the
+	 * operator's mockup (Focus-Run.dc.html). Reopening it is deliberately NOT
+	 * this component's job: the fold toggle only exists while the list is open
+	 * (inside its own header, where the mockup puts it); the reopen affordance
+	 * — a "Waiting on you 338" pill, a bare icon, wherever the module wants it —
+	 * is the CALLER's own markup, driving the same bound `open`. Fixing that
+	 * button's position here would be exactly the one-shape-per-module drift
+	 * this file exists to end; the module's own page already earned that
+	 * decision by owning the content beside this list. A caller's reopen
+	 * control should carry `aria-expanded={open}` itself, so the two controls
+	 * (this one, and the caller's) read as one continuous toggle to a screen
+	 * reader even though only one is ever in the document at a time:
+	 *
+	 *     <button onclick={() => (open = true)} aria-expanded={open}>
+	 *       Waiting on you <Badge>{waitingCount}</Badge>
+	 *     </button>
+	 *
+	 * Below `md` this never renders, at either state: the rail is already a
+	 * drawer there, and a 400px column has nowhere to go beside it. Godswood's
+	 * own answer is a dedicated phone route for the same list (Phone.dc.html);
+	 * that choice is the app's, not this component's — it only gets out of the
+	 * way so the app's own mobile route can render undisturbed.
+	 *
+	 * The header is chrome (title, the fold toggle, and an optional leading
+	 * `actions` snippet for a module-specific control — an "Add" button in the
+	 * mockup). Everything below it — tabs, grouped headings, the rows
+	 * themselves — is the module's own `children`, exactly as `SettingsShell`
+	 * hands its list body to the caller rather than describing a row shape of
+	 * its own. A queue is not the only thing this list will ever hold.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+	import PanelLeftClose from '@lucide/svelte/icons/panel-left-close';
+
+	let {
+		title,
+		label = title,
+		open = $bindable(true),
+		actions,
+		children,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLElement>> & {
+		/** The list's heading, in the shell's display face. */
+		title: string;
+		/**
+		 * The landmark's accessible name. Defaults to `title` — the visible
+		 * heading already says what this is, so a module only sets `label`
+		 * separately when the heading text would not stand alone as a name
+		 * (WCAG 2.4.1), e.g. a heading that leads with a live count.
+		 */
+		label?: string;
+		/**
+		 * Whether the list is open. Bindable, and NOT persisted by this
+		 * component — bind it to whatever the module already uses to persist a
+		 * user preference across a reload.
+		 */
+		open?: boolean;
+		/** Leading header actions beside the title — an "Add" button, a filter. */
+		actions?: Snippet;
+		/** The list body: tabs, group headings, rows — entirely the module's own. */
+		children: Snippet;
+	} = $props();
+
+	const listId = $props.id();
+</script>
+
+{#if open}
+	<aside
+		bind:this={ref}
+		id={listId}
+		aria-label={label}
+		class={cn(
+			'bg-shell text-shell-foreground border-border hidden w-[25rem] flex-none flex-col border-e md:flex',
+			className
+		)}
+		{...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">
+				{title}
+			</h2>
+			{#if actions}{@render actions()}{/if}
+			<button
+				type="button"
+				onclick={() => (open = false)}
+				aria-expanded="true"
+				aria-controls={listId}
+				aria-label={`Fold ${label} away`}
+				title={`Fold ${label} away`}
+				class="text-shell-muted-foreground hover:text-shell-foreground border-border grid size-9 flex-none place-items-center rounded-md border transition-colors"
+			>
+				<PanelLeftClose class="size-4" />
+			</button>
+		</div>
+		<div class="flex min-h-0 flex-1 flex-col overflow-y-auto">
+			{@render children()}
+		</div>
+	</aside>
+{/if}

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

@@ -0,0 +1,103 @@
+/**
+     * ListShell — a module's working list, folded away and brought back by the
+     * app that owns it, beside the content it serves.
+     *
+     * AppShell carries no second-column slot for this on purpose: `sidebar` was
+     * such a slot until 2026.8.11, and what it produced was two apps rendering a
+     * module's own PAGES beside the rail while the other seven rendered them
+     * inside it — the shell shape differing per app, and in one app per module.
+     * Operator ruling, 21/08/2026: no app supports an additional sidebar; a
+     * section's own pages roll out beneath it in the rail (`NavItem.children`).
+     * That ruling is about NAVIGATION. A working list is not navigation — it is
+     * data the module owns (a queue of things waiting on the user), and
+     * `20-sveltekit-frontend.md` already answers where that belongs: "a column
+     * that is not NavItem-shaped … belongs in the page beside the content it
+     * serves." `ContextColumn` is the household's other proof this is a real,
+     * sanctioned shape — a page-level flanking `<aside>`, not a shell slot.
+     *
+     * So this is a companion to AppShell, exactly as `SettingsShell` is: the
+     * shell provides ONE chrome (the rail, the bar, the content frame), and any
+     * module reaches for this to add a foldable list beside its own content,
+     * inside AppShell's content area. Every module gets the same list, not a
+     * hand-rolled column per module — which is the actual thing the 21/08/2026
+     * ruling exists to prevent, still true one level down.
+     *
+     * USE IT WITH `padded={false}` on AppShell, exactly as `SettingsShell`
+     * requires: the list has to reach the content area's edge — flush against
+     * the rail, with no gap — or it reads as a floating card rather than chrome.
+     * It paints itself in the rail's OWN chrome tokens (`bg-shell`,
+     * `text-shell-foreground`) for the same reason: a list that is chrome reads
+     * as chrome, not as a panel someone built inside the page.
+     *
+     * Width is fixed at 25rem (400px), measured off the operator's approved
+     * mockup (radar-hooves/godswood#839, Focus-List.dc.html) rather than picked,
+     * and not exposed as a prop — the same anti-drift discipline `SettingsShell`
+     * applies to its own 240px: one width, chosen once, or ten modules each
+     * guess their own.
+     *
+     * Open/closed is the CALLER's state (`open`, bindable), the same way
+     * AppShell's own `collapsed` is: bind it to persist the choice across
+     * reloads (a module-scoped `$state` in a `.svelte.ts` file, synced to
+     * `localStorage` — `svelte-basics.md` §shared state — or the app's own
+     * settings store). This component holds no storage of its own, on purpose:
+     * a module that already persists user preferences server-side should not
+     * gain a second, disagreeing mechanism here.
+     *
+     * When `open` is false this renders NOTHING — no placeholder, no rail — so
+     * the content beside it gets the freed width back, exactly like the
+     * operator's mockup (Focus-Run.dc.html). Reopening it is deliberately NOT
+     * this component's job: the fold toggle only exists while the list is open
+     * (inside its own header, where the mockup puts it); the reopen affordance
+     * — a "Waiting on you 338" pill, a bare icon, wherever the module wants it —
+     * is the CALLER's own markup, driving the same bound `open`. Fixing that
+     * button's position here would be exactly the one-shape-per-module drift
+     * this file exists to end; the module's own page already earned that
+     * decision by owning the content beside this list. A caller's reopen
+     * control should carry `aria-expanded={open}` itself, so the two controls
+     * (this one, and the caller's) read as one continuous toggle to a screen
+     * reader even though only one is ever in the document at a time:
+     *
+     *     <button onclick={() => (open = true)} aria-expanded={open}>
+     *       Waiting on you <Badge>{waitingCount}</Badge>
+     *     </button>
+     *
+     * Below `md` this never renders, at either state: the rail is already a
+     * drawer there, and a 400px column has nowhere to go beside it. Godswood's
+     * own answer is a dedicated phone route for the same list (Phone.dc.html);
+     * that choice is the app's, not this component's — it only gets out of the
+     * way so the app's own mobile route can render undisturbed.
+     *
+     * The header is chrome (title, the fold toggle, and an optional leading
+     * `actions` snippet for a module-specific control — an "Add" button in the
+     * mockup). Everything below it — tabs, grouped headings, the rows
+     * themselves — is the module's own `children`, exactly as `SettingsShell`
+     * hands its list body to the caller rather than describing a row shape of
+     * its own. A queue is not the only thing this list will ever hold.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLElement>> & {
+    /** The list's heading, in the shell's display face. */
+    title: string;
+    /**
+     * The landmark's accessible name. Defaults to `title` — the visible
+     * heading already says what this is, so a module only sets `label`
+     * separately when the heading text would not stand alone as a name
+     * (WCAG 2.4.1), e.g. a heading that leads with a live count.
+     */
+    label?: string;
+    /**
+     * Whether the list is open. Bindable, and NOT persisted by this
+     * component — bind it to whatever the module already uses to persist a
+     * user preference across a reload.
+     */
+    open?: boolean;
+    /** Leading header actions beside the title — an "Add" button, a filter. */
+    actions?: Snippet;
+    /** The list body: tabs, group headings, rows — entirely the module's own. */
+    children: Snippet;
+};
+declare const ListShell: import("svelte").Component<$$ComponentProps, {}, "open" | "ref">;
+type ListShell = ReturnType<typeof ListShell>;
+export default ListShell;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.9.19",
+	"version": "2026.9.20",
 	"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.9.19",
+		"version": "2026.9.20",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 60,
+		"componentCount": 61,
 		"situationCount": 17
 	},
 	"situations": [
@@ -298,7 +298,7 @@
 		{
 			"key": "page-frame",
 			"title": "The frame every route shares",
-			"description": "The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column.",
+			"description": "The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column, a foldable working list beside the page's own content.",
 			"components": [
 				{
 					"name": "AppShell",
@@ -335,6 +335,13 @@
 					"props": "stats, statsTitle?, statsInfo?, detail?, ariaLabel?",
 					"insteadOf": "a hand-built right-hand <aside> with a stat card and a detail pane"
 				},
+				{
+					"name": "ListShell",
+					"dir": "list-shell",
+					"import": "@poodle64/ui/list-shell",
+					"props": "title, children, label?, open?, actions?",
+					"insteadOf": "a module hand-rolling its own foldable second column beside the rail — a queue, an inbox, a working list"
+				},
 				{
 					"name": "AppIdentity",
 					"dir": "app-identity",

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.19`. 60 components, 17 situations.
+Generated from `@poodle64/ui@2026.9.20`. 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.
 
@@ -129,7 +129,7 @@ _One page at a time, fitted to its pane both ways so an A4 statement and a tall
 
 ## 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._
+_The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column, a foldable working list beside the page's own content._
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
@@ -138,6 +138,7 @@ _The standing chrome — the app shell and its nav, the one page-title treatment
 | `Segmented` | `@poodle64/ui/segmented` | `value, options, label, size?` | a hand-built row of aria-pressed buttons for a small fixed choice |
 | `PageHeader` | `@poodle64/ui/page-header` | `title?, eyebrow?, breadcrumbs?, icon?, subtitle?, info?, meta?, actions?` | a hand-written <h1> and title bar (the drift gate fails this) |
 | `ContextColumn` | `@poodle64/ui/context-column` | `stats, statsTitle?, statsInfo?, detail?, ariaLabel?` | a hand-built right-hand <aside> with a stat card and a detail pane |
+| `ListShell` | `@poodle64/ui/list-shell` | `title, children, label?, open?, actions?` | a module hand-rolling its own foldable second column beside the rail — a queue, an inbox, a working list |
 | `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