@poodle64/ui 2026.10.8 → 2026.10.9

package/README.md

@@ -118,6 +118,7 @@ rather than rebuilding it:
 | `document-detail`                               | One document's surface: identity fields, locations, tags and collection memberships, each section present exactly when its data is. Membership links are the app's own via `collectionHref`.                                                                                                                                                                            |
 | `search-results`                                | A ranked retrieval answer: title, the matched passage with accent-tinted highlights, source chip, mapped state and a mono relevance figure per hit; plus the before-any-search and matched-nothing empties.                                                                                                                                                             |
 | `ledger`                                        | The one ledger every module draws: dated rows of money, coins or units, two lines a row, grouped by the viewer's period, the viewer's columns and running balance. See [The ledger](#the-ledger).                                                                                                                                                                       |
+| `resize-handle`                                 | The drag edge of a side panel: pointer, arrow keys, double-click reset, remembered width, ceiling measured against the content beside it. AppShell's rail uses it; an app with its own `<aside>` renders `<ResizeHandle bind:width storageKey="…" />` as the aside's last child (positioned) and sets the aside's width from `width`. |
 
 **The application shell** (`app-shell`, `command-palette`). Page chrome is not
 what makes an app feel like an app either — the shell is. Five household

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

@@ -94,6 +94,7 @@
 	import { activeNavLabel, matchesPrefix, toItems, type NavSource } from './types.js';
 	import { provideShellControls, type ShellControlsSlot } from './controls.js';
 	import { cn } from '../../../utils.js';
+	import ResizeHandle from '../resize-handle/resize-handle.svelte';
 
 	let {
 		nav,
@@ -254,81 +255,8 @@
 
 	// Rail width is a personal preference: localStorage, one key across apps.
 	// A drag below RAIL_SNAP collapses; the width survives and returns on expand.
-	const RAIL_KEY = 'ds-shell-rail-width';
-	const RAIL_MIN = 200;
-	const RAIL_MAX = 420;
-	const RAIL_SNAP = 170;
-	const RAIL_STEP = 16;
 	let railWidth = $state<number | null>(null);
 	let resizing = $state(false);
-	$effect(() => {
-		try {
-			const stored = Number(localStorage.getItem(RAIL_KEY));
-			if (stored >= RAIL_MIN && stored <= RAIL_MAX) railWidth = stored;
-		} catch {
-			/* storage unavailable: the default width stands */
-		}
-	});
-	function clampRail(next: number) {
-		return Math.min(RAIL_MAX, Math.max(RAIL_MIN, Math.round(next)));
-	}
-	function setRailWidth(next: number) {
-		railWidth = clampRail(next);
-		try {
-			localStorage.setItem(RAIL_KEY, String(railWidth));
-		} catch {
-			/* storage unavailable: the width lasts the session */
-		}
-	}
-	function startResize(event: PointerEvent) {
-		const handle = event.currentTarget as HTMLElement;
-		const rail = handle.parentElement as HTMLElement;
-		const startX = event.clientX;
-		const startWidth = rail.getBoundingClientRect().width;
-		const before = railWidth;
-		resizing = true;
-		handle.setPointerCapture(event.pointerId);
-		const move = (e: PointerEvent) => {
-			const next = startWidth + (e.clientX - startX);
-			if (next < RAIL_SNAP) {
-				// A collapse keeps the width it had; only a resize stores one.
-				railWidth = before;
-				collapsed = true;
-				stop();
-			} else {
-				railWidth = clampRail(next);
-			}
-		};
-		const stop = () => {
-			resizing = false;
-			if (!collapsed && railWidth !== null) setRailWidth(railWidth);
-			handle.removeEventListener('pointermove', move);
-			handle.removeEventListener('pointerup', stop);
-			handle.removeEventListener('pointercancel', stop);
-			if (handle.hasPointerCapture(event.pointerId)) handle.releasePointerCapture(event.pointerId);
-		};
-		handle.addEventListener('pointermove', move);
-		handle.addEventListener('pointerup', stop);
-		handle.addEventListener('pointercancel', stop);
-	}
-	function resizeByKey(event: KeyboardEvent) {
-		const current = railWidth ?? RAIL_MIN + (RAIL_MAX - RAIL_MIN) / 4;
-		if (event.key === 'ArrowLeft') setRailWidth(current - RAIL_STEP);
-		else if (event.key === 'ArrowRight') setRailWidth(current + RAIL_STEP);
-		else if (event.key === 'Home') resetRailWidth();
-		else if (event.key === 'End') setRailWidth(RAIL_MAX);
-		else return;
-		event.preventDefault();
-	}
-	/** Back to the package default (Home, or a double-click on the handle). */
-	function resetRailWidth() {
-		railWidth = null;
-		try {
-			localStorage.removeItem(RAIL_KEY);
-		} catch {
-			/* storage unavailable */
-		}
-	}
 
 	// The measure is resolved ONCE, and the class and the attribute both read
 	// that one answer. Two independently-worded conditionals looked symmetric
@@ -696,25 +624,14 @@
 				</div>
 			{/if}
 			{#if collapsible && !railCollapsed && !mobileNavOpen}
-				<!-- The rail's right edge: drag to resize, drag past the snap to
-				     collapse, arrows to nudge, Home to reset, double-click to reset.
-				     A focusable separator is the ARIA window-splitter pattern. -->
-				<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
-				<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
-				<div
-					role="separator"
-					aria-orientation="vertical"
-					aria-label="Resize sidebar"
-					aria-valuenow={railWidth ?? undefined}
-					aria-valuemin={RAIL_MIN}
-					aria-valuemax={RAIL_MAX}
-					tabindex="0"
-					class="ds-shell-rail-handle"
-					onpointerdown={startResize}
-					onkeydown={resizeByKey}
-					ondblclick={resetRailWidth}
+				<ResizeHandle
+					bind:width={railWidth}
+					bind:dragging={resizing}
+					storageKey="ds-shell-rail-width"
+					snap={170}
+					onsnap={() => (collapsed = true)}
 					data-testid="ds-rail-resize"
-				></div>
+				/>
 			{/if}
 		</aside>
 	{/if}

package/dist/components/ui/resize-handle/index.d.ts

@@ -0,0 +1,2 @@
+import Root from './resize-handle.svelte';
+export { Root, Root as ResizeHandle };

package/dist/components/ui/resize-handle/index.js

@@ -0,0 +1,4 @@
+import Root from './resize-handle.svelte';
+export { Root, 
+//
+Root as ResizeHandle };

package/dist/components/ui/resize-handle/resize-handle.svelte

@@ -0,0 +1,140 @@
+<script lang="ts">
+	/**
+	 * The drag edge of a resizable side panel: the one implementation behind
+	 * AppShell's rail, for an app whose sidebar is its own element.
+	 *
+	 * Render it as the LAST child of the panel, and give the panel
+	 * `position: relative` (or sticky) and `width: <width>px` while `width` is
+	 * set. It owns the pointer drag, the keyboard (arrows nudge, Home resets,
+	 * End takes the maximum), the double-click reset and persistence; the panel
+	 * owns how the number is applied.
+	 *
+	 * The ceiling is measured against the CONTENT beside the panel, not the
+	 * window: the panel's parent is the row, so the panel can never grow past
+	 * `row width - minContent`, whatever the screen.
+	 */
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn } from '../../../utils.js';
+
+	let {
+		width = $bindable(null),
+		dragging = $bindable(false),
+		min = 200,
+		max = 420,
+		minContent = 480,
+		step = 16,
+		snap,
+		onsnap,
+		storageKey,
+		label = 'Resize sidebar',
+		class: className,
+		...rest
+	}: Omit<HTMLAttributes<HTMLDivElement>, 'role'> & {
+		/** Panel width in px; `null` is the panel's own default. */
+		width?: number | null;
+		/** True during a pointer drag: switch the panel's width transition off. */
+		dragging?: boolean;
+		min?: number;
+		max?: number;
+		/** Least width the content beside the panel keeps. */
+		minContent?: number;
+		/** Arrow-key nudge in px. */
+		step?: number;
+		/** A drag below this calls `onsnap` (collapse) and keeps the old width. */
+		snap?: number;
+		onsnap?: () => void;
+		/** localStorage key; one per app. Omitted, nothing is stored. */
+		storageKey?: string;
+		label?: string;
+	} = $props();
+
+	$effect(() => {
+		if (!storageKey) return;
+		try {
+			const stored = Number(localStorage.getItem(storageKey));
+			if (stored >= min && stored <= max) width = stored;
+		} catch {
+			/* storage unavailable: the default width stands */
+		}
+	});
+
+	let handle: HTMLElement;
+	const panel = () => handle.parentElement as HTMLElement;
+	const clamp = (next: number) => {
+		const row = panel().parentElement?.getBoundingClientRect().width || Infinity;
+		const ceiling = Math.max(min, Math.min(max, row - minContent));
+		return Math.min(ceiling, Math.max(min, Math.round(next)));
+	};
+	const store = (value: number | null) => {
+		if (!storageKey) return;
+		try {
+			if (value === null) localStorage.removeItem(storageKey);
+			else localStorage.setItem(storageKey, String(value));
+		} catch {
+			/* storage unavailable: the width lasts the session */
+		}
+	};
+	const set = (next: number) => {
+		width = clamp(next);
+		store(width);
+	};
+	const reset = () => {
+		width = null;
+		store(null);
+	};
+
+	let drag: { x: number; start: number; before: number | null } | null = null;
+	function down(event: PointerEvent) {
+		drag = { x: event.clientX, start: panel().getBoundingClientRect().width, before: width };
+		dragging = true;
+		handle.setPointerCapture(event.pointerId);
+	}
+	function move(event: PointerEvent) {
+		if (!drag) return;
+		const next = drag.start + event.clientX - drag.x;
+		if (snap !== undefined && next < snap) {
+			width = drag.before;
+			end(event);
+			onsnap?.();
+		} else width = clamp(next);
+	}
+	function end(event: PointerEvent) {
+		if (!drag) return;
+		const moved = width !== drag.before;
+		drag = null;
+		dragging = false;
+		if (handle.hasPointerCapture(event.pointerId)) handle.releasePointerCapture(event.pointerId);
+		if (moved && width !== null) store(width);
+	}
+	function key(event: KeyboardEvent) {
+		const current = width ?? panel().getBoundingClientRect().width;
+		if (event.key === 'ArrowLeft') set(current - step);
+		else if (event.key === 'ArrowRight') set(current + step);
+		else if (event.key === 'Home') reset();
+		else if (event.key === 'End') set(max);
+		else return;
+		event.preventDefault();
+	}
+</script>
+
+<!-- A focusable separator is the ARIA window-splitter pattern. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div
+	bind:this={handle}
+	role="separator"
+	aria-orientation="vertical"
+	aria-label={label}
+	aria-valuenow={width ?? undefined}
+	aria-valuemin={min}
+	aria-valuemax={max}
+	tabindex="0"
+	class={cn('ds-resize-handle', className)}
+	onpointerdown={down}
+	onpointermove={move}
+	onpointerup={end}
+	onpointercancel={end}
+	onkeydown={key}
+	ondblclick={reset}
+	{...rest}
+></div>

package/dist/components/ui/resize-handle/resize-handle.svelte.d.ts

@@ -0,0 +1,36 @@
+/**
+     * The drag edge of a resizable side panel: the one implementation behind
+     * AppShell's rail, for an app whose sidebar is its own element.
+     *
+     * Render it as the LAST child of the panel, and give the panel
+     * `position: relative` (or sticky) and `width: <width>px` while `width` is
+     * set. It owns the pointer drag, the keyboard (arrows nudge, Home resets,
+     * End takes the maximum), the double-click reset and persistence; the panel
+     * owns how the number is applied.
+     *
+     * The ceiling is measured against the CONTENT beside the panel, not the
+     * window: the panel's parent is the row, so the panel can never grow past
+     * `row width - minContent`, whatever the screen.
+     */
+import type { HTMLAttributes } from 'svelte/elements';
+type $$ComponentProps = Omit<HTMLAttributes<HTMLDivElement>, 'role'> & {
+    /** Panel width in px; `null` is the panel's own default. */
+    width?: number | null;
+    /** True during a pointer drag: switch the panel's width transition off. */
+    dragging?: boolean;
+    min?: number;
+    max?: number;
+    /** Least width the content beside the panel keeps. */
+    minContent?: number;
+    /** Arrow-key nudge in px. */
+    step?: number;
+    /** A drag below this calls `onsnap` (collapse) and keeps the old width. */
+    snap?: number;
+    onsnap?: () => void;
+    /** localStorage key; one per app. Omitted, nothing is stored. */
+    storageKey?: string;
+    label?: string;
+};
+declare const ResizeHandle: import("svelte").Component<$$ComponentProps, {}, "width" | "dragging">;
+type ResizeHandle = ReturnType<typeof ResizeHandle>;
+export default ResizeHandle;

package/dist/styles.css

@@ -968,6 +968,7 @@
 		top: 0;
 		height: 100dvh;
 		width: var(--ds-shell-rail-width);
+		max-width: 50%;
 		transition: width 200ms ease;
 	}
 
@@ -1038,28 +1039,23 @@
 		transition: none;
 	}
 
-	/* The resize handle: a 6px grab strip astride the rail's right edge, md+
-	   only, showing the border colour under the pointer and keyboard focus. */
-	.ds-shell-rail-handle {
-		display: none;
-	}
-	@media (min-width: 48rem) {
-		.ds-shell-rail-handle {
-			display: block;
-			position: absolute;
-			inset-block: 0;
-			right: -3px;
-			width: 6px;
-			cursor: col-resize;
-			z-index: 1;
-			touch-action: none;
-		}
-		.ds-shell-rail-handle:hover,
-		.ds-shell-rail-handle:focus-visible {
-			background: var(--ds-color-primary);
-			opacity: 0.4;
-			outline: none;
-		}
+	/* The resize handle (<ResizeHandle>): a 6px grab strip astride the right
+	   edge of the panel it is the last child of, showing the primary colour
+	   under the pointer and keyboard focus. The panel must be positioned. */
+	.ds-resize-handle {
+		position: absolute;
+		inset-block: 0;
+		right: -3px;
+		width: 6px;
+		cursor: col-resize;
+		z-index: 1;
+		touch-action: none;
+	}
+	.ds-resize-handle:hover,
+	.ds-resize-handle:focus-visible {
+		background: var(--ds-color-primary);
+		opacity: 0.4;
+		outline: none;
 	}
 
 	/* The content measure: the shell's content box is ONE element in four

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.10.8",
+	"version": "2026.10.9",
 	"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,13 +1,27 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.10.8",
+		"version": "2026.10.9",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 67,
-		"situationCount": 18
+		"componentCount": 68,
+		"situationCount": 19
 	},
 	"situations": [
+		{
+			"key": "resizable-panel",
+			"title": "A side panel the user can widen or narrow",
+			"description": "An app's own sidebar or list pane that needs a drag edge: pointer, arrow keys, double-click reset, remembered width. AppShell's rail already has it.",
+			"components": [
+				{
+					"name": "ResizeHandle",
+					"dir": "resize-handle",
+					"import": "@poodle64/ui/resize-handle",
+					"props": "width?, dragging?, min?, max?, minContent?, step?, snap?, onsnap?, storageKey?, label?",
+					"insteadOf": "a hand-written pointer-drag and localStorage width on your own <aside>"
+				}
+			]
+		},
 		{
 			"key": "single-figure",
 			"title": "A single labelled figure",

package/registry/component-map.md

@@ -1,13 +1,21 @@
 # @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.8`. 67 components, 18 situations.
+Generated from `@poodle64/ui@2026.10.9`. 68 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.
 
 [`frontend-design` skill]: the household rule that loads before any UI code.
 [CHI 2026 study]: 10.1145/3772363.3798616
 
+## A side panel the user can widen or narrow
+
+_An app's own sidebar or list pane that needs a drag edge: pointer, arrow keys, double-click reset, remembered width. AppShell's rail already has it._
+
+| Component | Import | Key props | Reach for it instead of |
+| --- | --- | --- | --- |
+| `ResizeHandle` | `@poodle64/ui/resize-handle` | `width?, dragging?, min?, max?, minContent?, step?, snap?, onsnap?, storageKey?, label?` | a hand-written pointer-drag and localStorage width on your own <aside> |
+
 ## A single labelled figure
 
 _One headline metric that earns a tile — a figure with a label, an optional unit, and the state of the thing it measures._