@dorsk/tsumikit 0.23.0 → 0.24.0

package/README.md

@@ -57,15 +57,91 @@ import { Button, Field, Input, Modal, ThemePicker } from '@dorsk/tsumikit';
 
 ## Theming
 
-- 17 themes ship (dark, light, sepia, **colorblind** — Okabe-Ito —, plus mocha,
-  dracula, nord, tokyonight, gruvbox, solarized, rosepine, onedark, everforest,
-  monokai, amoled, highcontrast).
-- A new theme = one entry in `THEMES` (`stores/theme.svelte.ts`) + one
-  `[data-theme="id"]` block in `variables.css`. Nothing else changes.
+- 23 themes ship (light, highcontrast, gruvboxlight, solarizedlight,
+  everforestlight, rosepinedawn, latte, nordlight, tokyoday, kanagawalotus,
+  sepia, dark, **colorblind** — Okabe-Ito —, mocha, dracula, nord, tokyonight,
+  gruvbox, solarized, rosepine, onedark, everforest, monokai, amoled).
 - `<ThemePicker />` and `<FontScalePicker />` wire the stores to the UI. Theme
   is persisted to `localStorage` and applied with no flash (head snippet in
   `app.html`) and updates the mobile `<meta name="theme-color">`.
 
+### Stylesheets
+
+`@dorsk/tsumikit/styles/app.css` is a shell over five files you can import
+individually, in this order:
+
+```css
+@import '@dorsk/tsumikit/styles/tokens.css';
+@import '@dorsk/tsumikit/styles/themes.css'; /* optional */
+@import '@dorsk/tsumikit/styles/reset.css';
+@import '@dorsk/tsumikit/styles/utilities.css';
+@import '@dorsk/tsumikit/styles/syntax.css';
+@import './brand.css';
+```
+
+| export | contents |
+| --- | --- |
+| `styles/tokens.css` | `:root` only — every token the kit reads (`--c-*` palette, `--bg`/`--text`/`--accent` aliases, type scale, spacing, radii, shadows, fonts, `--control-height`, …). Theme-less. |
+| `styles/themes.css` | the built-in `[data-theme="id"]` blocks, one per `THEMES` entry. |
+| `styles/reset.css` | reset + element defaults. |
+| `styles/utilities.css` | `.container`, `.stack`, `.row`, `.sr-only`, icon sizing, … |
+| `styles/syntax.css` | highlight.js / Prism class → `--syn-*` mapping. |
+
+`styles/variables.css` = `tokens.css` + `themes.css` (kept for compatibility).
+Nothing is wrapped in `@layer`: kit rules are unlayered so component-scoped
+styles cascade exactly as before, and a consumer stylesheet imported **after**
+the kit wins on source order at equal specificity. Do not put brand overrides
+inside a `@layer` of your own — layered rules lose to the kit's unlayered ones.
+
+### Your own theme, without vendoring
+
+```ts
+// +layout.ts (or any module that runs before first render)
+import { theme } from '@dorsk/tsumikit';
+theme.register({ id: 'kusaritoi', label: 'Kusaritoi', icon: '鎖', themeColor: '#2a2a2a', mode: 'dark' });
+theme.setDefault('kusaritoi');
+```
+
+```css
+/* brand.css — imported after the kit stylesheet(s) */
+@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono&display=swap');
+:root { --font-mono: 'JetBrains Mono', ui-monospace, monospace; }
+
+[data-theme='kusaritoi'] {
+  color-scheme: dark;
+  --c-bg: #2a2a2a;         --c-bg-elev: #323232;    --c-bg-elev-2: #3a3a3a;
+  --c-surface: #323232;    --c-border: #484848;     --c-border-strong: #585858;
+  --c-text: #e8e8e8;       --c-text-muted: #b0b0b0; --c-text-faint: #808080;
+  --c-accent: #5ac8c8;     --c-accent-ink: #0d1f1f; --c-accent-dim: #3a8a8a;
+  --c-blue: #5a9fd4;       --c-amber: #d9a543;      --c-red: #e06060;
+  --c-green: #6abf69;      --c-violet: #b48ef0;     --c-gold: #d9a543;
+  --c-teal: #5ac8c8;
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --shadow-md: 0 6px 20px rgba(0, 0, 0, 0.5);
+  --shadow-lg: 0 12px 40px rgba(0, 0, 0, 0.6);
+  --mach-bg-sl: 45% 24%;   --mach-fg-sl: 70% 82%;   --mach-border-sl: 45% 40%;
+}
+```
+
+Contract for a `[data-theme='x']` block: all nineteen `--c-*` palette tokens,
+`--shadow-sm|md|lg`, `--mach-bg-sl|fg-sl|border-sl`, and `color-scheme: light`
+for a light theme (`:root` defaults to dark, so dark themes may omit it).
+`--md-code-bg` is optional (derives from `--c-blue`). Everything else (`--bg`,
+`--text`, `--syn-*`, …) is an alias in `tokens.css` and follows automatically.
+
+- `theme.register(def | def[])` appends to `theme.all` (built-ins first); an
+  entry with a built-in `id` replaces that built-in. `icon` and `themeColor` are
+  optional. `ThemePicker` reads `theme.all`, so registered themes appear at once.
+- `theme.setDefault(id)` is the theme used when `localStorage` holds nothing
+  valid — set the same id as `data-theme` in your `app.html` so the no-flash
+  snippet and the store agree. A persisted id that only becomes valid after
+  `register()` is picked up as soon as it is registered.
+- Only the palette or only the fonts? Import `tokens.css` + your `brand.css`
+  and skip `themes.css`; or import the full `app.css` and override `:root`
+  tokens after it. Never copy the kit files.
+- Adding a built-in theme to the kit = one entry in `THEMES`
+  (`stores/theme.svelte.ts`) + one block in `styles/themes.css`.
+
 ## Components
 
 **Atoms:** Text, Heading, Button, Input, Textarea, Select, Switch, Checkbox,
@@ -113,6 +189,32 @@ edge-to-edge sections — inside AppShell's main column use `size="none"` instea
 Children can bleed to the column edge with
 `margin-inline: calc(-1 * var(--container-gutter))`.
 
+### ResizablePanel
+
+Inline by default: `panel` shares the row with `children` on its `side`, drag the
+edge or use the arrow keys/Home/End on the separator, collapse it with the edge
+chevron; `width`/`minWidth`/`maxWidth` (px numbers or CSS lengths such as
+`'12rem'`) and `widthKey` persist the width. `mode="overlay"` turns it into a
+fixed non-modal drawer (`role="dialog"`) on the viewport edge: `bind:open`,
+`onclose` fires on Escape, scrim click or the edge control, `scrim={false}` drops
+the dim backdrop, `fullWidthBelow="960px"` makes the drawer span the viewport (no
+handle, no scrim) on small screens, and `clampToViewport` (default true) keeps a
+stored width inside a shrunken window. `children` is optional in overlay mode.
+
+```svelte
+<ResizablePanel mode="overlay" side="right" label="Conversation" bind:open
+  width={720} minWidth={360} maxWidth="90vw" widthKey="conv-w" fullWidthBelow="960px">
+  {#snippet panel()}…{/snippet}
+</ResizablePanel>
+```
+
+`Scrim` (`onclose`, `hideBelow`, `z`, `label`) is the drawer's backdrop atom,
+exported for custom overlays: click or Escape (document-level) calls `onclose`.
+`resizeHandle` is the shared drag action behind every grip: `use:resizeHandle={{
+side, min, max, step, onwidth, oncommit, onreset, onactive, measure }}` gives
+any element pointer-capture + rAF-coalesced dragging, arrow/Home/End keys and
+double-click reset; the width defaults to the element's parent box.
+
 ### Stacked distribution + legend
 
 `SegmentedProgress mode="stacked"` turns the bar into one shared track whose slice

package/dist/components/atoms/Scrim.svelte

@@ -0,0 +1,81 @@
+<script lang="ts">
+	import { browser } from '../../env';
+
+	let {
+		onclose,
+		hideBelow,
+		z = 'var(--z-drawer)',
+		label = 'Close'
+	}: {
+		/** Called on click anywhere on the scrim and on Escape (document-level). */
+		onclose?: () => void;
+		/** Viewport width (CSS length) under which the scrim is not rendered,
+		 *  for overlays that go full-bleed on small screens. */
+		hideBelow?: string;
+		/** z-index; defaults to the drawer layer. */
+		z?: string | number;
+		/** Accessible name of the click target. */
+		label?: string;
+	} = $props();
+
+	let hidden = $state(false);
+
+	$effect(() => {
+		if (!browser || !hideBelow) {
+			hidden = false;
+			return;
+		}
+		const query = matchMedia(`(max-width: ${hideBelow})`);
+		const sync = () => {
+			hidden = query.matches;
+		};
+		sync();
+		query.addEventListener('change', sync);
+		return () => query.removeEventListener('change', sync);
+	});
+
+	$effect(() => {
+		if (!browser) return;
+		const onKeydown = (event: KeyboardEvent) => {
+			if (event.key !== 'Escape' || event.defaultPrevented) return;
+			event.preventDefault();
+			onclose?.();
+		};
+		document.addEventListener('keydown', onKeydown);
+		return () => document.removeEventListener('keydown', onKeydown);
+	});
+</script>
+
+{#if !hidden}
+	<button
+		type="button"
+		class="scrim"
+		style:z-index={z}
+		aria-label={label}
+		tabindex="-1"
+		onclick={() => onclose?.()}
+		data-tsu="Scrim"
+	></button>
+{/if}
+
+<style>
+	.scrim {
+		position: fixed;
+		inset: 0;
+		padding: 0;
+		border: 0;
+		background: color-mix(in srgb, var(--bg) 45%, transparent);
+		cursor: default;
+		animation: scrim-fade 0.18s var(--ease);
+	}
+	@keyframes scrim-fade {
+		from {
+			opacity: 0;
+		}
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.scrim {
+			animation: none;
+		}
+	}
+</style>

package/dist/components/atoms/Scrim.svelte.d.ts

@@ -0,0 +1,14 @@
+type $$ComponentProps = {
+    /** Called on click anywhere on the scrim and on Escape (document-level). */
+    onclose?: () => void;
+    /** Viewport width (CSS length) under which the scrim is not rendered,
+     *  for overlays that go full-bleed on small screens. */
+    hideBelow?: string;
+    /** z-index; defaults to the drawer layer. */
+    z?: string | number;
+    /** Accessible name of the click target. */
+    label?: string;
+};
+declare const Scrim: import("svelte").Component<$$ComponentProps, {}, "">;
+type Scrim = ReturnType<typeof Scrim>;
+export default Scrim;

package/dist/components/layouts/ResizablePanel.svelte

@@ -1,8 +1,9 @@
 <script lang="ts">
-	import { onDestroy, type Snippet } from 'svelte';
+	import type { Snippet } from 'svelte';
 	import { browser } from '../../env';
 	import Icon from '../atoms/Icon.svelte';
-	import { createFrameBatcher } from './resizable-panel-frame.js';
+	import Scrim from '../atoms/Scrim.svelte';
+	import { resizeHandle, resolveLength } from './resizable-panel-frame.js';
 	import { parseStoredCollapsed, parseStoredWidth } from './resizable-panel-persistence';
 
 	let {
@@ -18,23 +19,31 @@
 		persistCollapsed = true,
 		resizeStep = 16,
 		handlePlacement = 'bottom',
-		stickyHandle = true
+		stickyHandle = true,
+		mode = 'inline',
+		open = $bindable(false),
+		onclose,
+		scrim,
+		fullWidthBelow,
+		clampToViewport = true
 	}: {
 		/** Content shown while the panel is expanded. */
 		panel: Snippet;
-		/** Main content beside the panel. */
-		children: Snippet;
+		/** Main content beside the panel (optional in overlay mode). */
+		children?: Snippet;
 		/** Physical edge occupied by the panel. */
 		side?: 'left' | 'right';
-		/** Accessible name for the panel landmark. */
+		/** Accessible name for the panel landmark / dialog. */
 		label?: string;
 		/** Initial expanded width in pixels. */
 		width?: number;
-		minWidth?: number;
-		maxWidth?: number;
+		/** Pixel number or CSS length (`'12rem'`, `'30vw'`). */
+		minWidth?: number | string;
+		/** Pixel number or CSS length (`'40rem'`, `'90vw'`). */
+		maxWidth?: number | string;
 		/** localStorage key used to restore the expanded width. */
 		widthKey?: string;
-		/** Bindable collapsed state. */
+		/** Bindable collapsed state (inline mode). */
 		collapsed?: boolean;
 		/** Persist collapsed state as `${widthKey}:collapsed`. */
 		persistCollapsed?: boolean;
@@ -45,23 +54,69 @@
 		/** Keep the collapse handle in view when the panel scrolls past the
 		 *  viewport, repositioning on scroll/resize via requestAnimationFrame. */
 		stickyHandle?: boolean;
+		/** `inline` shares the row with `children`; `overlay` fixes the panel to
+		 *  its viewport edge as a non-modal drawer above the page. */
+		mode?: 'inline' | 'overlay';
+		/** Bindable drawer visibility (overlay mode). */
+		open?: boolean;
+		/** Overlay mode: Escape, scrim click or the edge control closed the drawer. */
+		onclose?: () => void;
+		/** Overlay mode: dim the page behind the drawer; clicking it closes (default true). */
+		scrim?: boolean;
+		/** Overlay mode: viewport width (CSS length) under which the drawer spans
+		 *  the full viewport and hides its resize handle and scrim. */
+		fullWidthBelow?: string;
+		/** Overlay mode: cap the width at the viewport and re-clamp on window resize. */
+		clampToViewport?: boolean;
 	} = $props();
 
 	let root: HTMLDivElement;
+	let panelEl = $state<HTMLElement | null>(null);
 	let handleEl = $state<HTMLButtonElement | null>(null);
 	let panelWidth = $state<number>();
 	let resizing = $state(false);
 	let restored = false;
 	let stickyShift = $state(0);
+	let viewportWidth = $state<number>();
+	let lengthTick = $state(0);
+	let fullBleed = $state(false);
 
-	const boundedMin = $derived(Math.max(1, Math.min(minWidth, maxWidth)));
-	const boundedMax = $derived(Math.max(boundedMin, maxWidth));
+	const overlay = $derived(mode === 'overlay');
+	const shown = $derived(overlay ? open : !collapsed);
+	const showScrim = $derived(overlay && open && (scrim ?? true));
+
+	function measureLength(css: string) {
+		if (!browser || !root) return undefined;
+		console.count('measure ' + css);
+		const probe = document.createElement('div');
+		probe.style.cssText = `position:absolute;visibility:hidden;pointer-events:none;width:${css}`;
+		root.appendChild(probe);
+		const measured = probe.getBoundingClientRect().width;
+		probe.remove();
+		return measured;
+	}
+
+	const minPx = $derived.by(() => {
+		void lengthTick;
+		return resolveLength(minWidth, measureLength) ?? 180;
+	});
+	const maxPx = $derived.by(() => {
+		void lengthTick;
+		return resolveLength(maxWidth, measureLength) ?? 480;
+	});
+	const viewportCap = $derived(
+		overlay && clampToViewport && viewportWidth ? viewportWidth : Number.POSITIVE_INFINITY
+	);
+	const boundedMin = $derived(Math.max(1, Math.min(minPx, maxPx, viewportCap)));
+	const boundedMax = $derived(Math.max(boundedMin, Math.min(maxPx, viewportCap)));
 	const currentWidth = $derived(
 		Math.round(Math.max(boundedMin, Math.min(panelWidth ?? width, boundedMax)))
 	);
-	const toggleLabel = $derived(collapsed ? `Expand ${label}` : `Collapse ${label}`);
+	const toggleLabel = $derived(
+		overlay ? `Close ${label}` : collapsed ? `Expand ${label}` : `Collapse ${label}`
+	);
 	const toggleIcon = $derived(
-		collapsed
+		!overlay && collapsed
 			? side === 'left'
 				? 'chevron-right'
 				: 'chevron-left'
@@ -73,6 +128,7 @@
 	$effect(() => {
 		if (!browser || restored) return;
 		restored = true;
+		lengthTick += 1;
 		if (!widthKey) return;
 
 		const savedWidth = parseStoredWidth(
@@ -90,28 +146,70 @@
 		}
 	});
 
-	function persistWidth() {
-		if (browser && widthKey) localStorage.setItem(widthKey, String(currentWidth));
+	$effect(() => {
+		if (!browser) return;
+		const sync = () => {
+			console.count('sync');
+			viewportWidth = window.innerWidth;
+			lengthTick += 1;
+		};
+		sync();
+		addEventListener('resize', sync);
+		return () => removeEventListener('resize', sync);
+	});
+
+	$effect(() => {
+		if (!browser || !overlay || !fullWidthBelow) {
+			fullBleed = false;
+			return;
+		}
+		console.count('bleed');
+		const query = matchMedia(`(max-width: ${fullWidthBelow})`);
+		const sync = () => {
+			fullBleed = query.matches;
+		};
+		sync();
+		query.addEventListener('change', sync);
+		return () => query.removeEventListener('change', sync);
+	});
+
+	$effect(() => {
+		if (!browser || !overlay || !open) return;
+		console.count('escape');
+		const onKeydown = (event: KeyboardEvent) => {
+			if (event.key !== 'Escape' || event.defaultPrevented) return;
+			event.preventDefault();
+			close();
+		};
+		document.addEventListener('keydown', onKeydown);
+		return () => document.removeEventListener('keydown', onKeydown);
+	});
+
+	$effect(() => {
+		if (!browser || !overlay || !open || !panelEl) return;
+		console.count('focus');
+		const previous = document.activeElement as HTMLElement | null;
+		if (!panelEl.contains(previous)) panelEl.focus({ preventScroll: true });
+		return () => {
+			if (previous?.isConnected && document.activeElement === document.body) previous.focus();
+		};
+	});
+
+	function persistWidth(nextWidth: number) {
+		if (browser && widthKey) localStorage.setItem(widthKey, String(nextWidth));
 	}
 
-	function setWidth(nextWidth: number, persist = true) {
+	function setWidth(nextWidth: number) {
 		panelWidth = Math.round(Math.max(boundedMin, Math.min(nextWidth, boundedMax)));
-		if (persist) persistWidth();
 	}
 
-	const pointerWidths = createFrameBatcher<number>(
-		(callback) => requestAnimationFrame(callback),
-		(handle) => cancelAnimationFrame(handle),
-		(nextWidth) => setWidth(nextWidth, false)
-	);
-
 	// Keep the collapse handle within the viewport (and its panel) while a long
 	// panel scrolls past the fold. Scroll fires often, so coalesce recomputes
 	// into one per animation frame.
 	let stickyFrame: number | undefined;
 
 	function computeSticky() {
-		if (!stickyHandle || !root || !handleEl) {
+		if (!stickyHandle || overlay || !root || !handleEl) {
 			stickyShift = 0;
 			return;
 		}
@@ -139,7 +237,7 @@
 	}
 
 	$effect(() => {
-		if (!browser || !stickyHandle) {
+		if (!browser || !stickyHandle || overlay) {
 			stickyShift = 0;
 			return;
 		}
@@ -154,69 +252,22 @@
 		};
 	});
 
-	onDestroy(() => pointerWidths.discard());
+	function close() {
+		if (!open) return;
+		open = false;
+		onclose?.();
+	}
 
 	function toggle() {
+		if (overlay) {
+			close();
+			return;
+		}
 		collapsed = !collapsed;
 		if (browser && widthKey && persistCollapsed) {
 			localStorage.setItem(`${widthKey}:collapsed`, String(collapsed));
 		}
 	}
-
-	function widthFromPointer(clientX: number) {
-		const bounds = root.getBoundingClientRect();
-		return side === 'left' ? clientX - bounds.left : bounds.right - clientX;
-	}
-
-	function startResize(event: PointerEvent) {
-		resizing = true;
-		(event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
-		event.preventDefault();
-	}
-
-	function resize(event: PointerEvent) {
-		if (!resizing) return;
-		pointerWidths.schedule(widthFromPointer(event.clientX));
-	}
-
-	function finishResize(event: PointerEvent) {
-		if (!resizing) return;
-		const finalWidth = Math.round(
-			Math.max(boundedMin, Math.min(widthFromPointer(event.clientX), boundedMax))
-		);
-		pointerWidths.flush(finalWidth);
-		resizing = false;
-		try {
-			(event.currentTarget as HTMLElement).releasePointerCapture(event.pointerId);
-		} catch {
-			// Pointer capture may already have been released by the browser.
-		}
-		if (browser && widthKey) localStorage.setItem(widthKey, String(finalWidth));
-	}
-
-	function resizeWithKeyboard(event: KeyboardEvent) {
-		let nextWidth: number | undefined;
-		const direction = side === 'left' ? 1 : -1;
-
-		switch (event.key) {
-			case 'ArrowLeft':
-				nextWidth = currentWidth - resizeStep * direction;
-				break;
-			case 'ArrowRight':
-				nextWidth = currentWidth + resizeStep * direction;
-				break;
-			case 'Home':
-				nextWidth = boundedMin;
-				break;
-			case 'End':
-				nextWidth = boundedMax;
-				break;
-		}
-
-		if (nextWidth === undefined) return;
-		event.preventDefault();
-		setWidth(nextWidth);
-	}
 </script>
 
 <div
@@ -224,52 +275,74 @@
 	class="panel-layout"
 	class:left={side === 'left'}
 	class:right={side === 'right'}
-	class:collapsed
+	class:collapsed={!overlay && collapsed}
+	class:overlay
+	class:full-bleed={fullBleed}
 	class:resizing
 	style="--panel-width: {currentWidth}px"
 	data-tsu="ResizablePanel"
 >
-	<aside aria-label={label} class="panel">
-		{#if !collapsed}
-			<div class="panel-content">{@render panel()}</div>
-			<!-- The separator role is interactive when focusable and wired to the
-			     required arrow/Home/End keyboard behavior. -->
-			<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
-			<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
-			<div
-				class="resize-handle"
-				role="separator"
-				tabindex="0"
-				aria-label={`Resize ${label}`}
-				aria-orientation="vertical"
-				aria-valuemin={boundedMin}
-				aria-valuemax={boundedMax}
-				aria-valuenow={currentWidth}
-				onkeydown={resizeWithKeyboard}
-				onpointerdown={startResize}
-				onpointermove={resize}
-				onpointerup={finishResize}
-				onpointercancel={finishResize}
-			></div>
-		{/if}
+	{#if showScrim}
+		<Scrim onclose={close} hideBelow={fullWidthBelow} label={`Close ${label}`} />
+	{/if}
 
-		<button
-			bind:this={handleEl}
-			type="button"
-			class="collapse-control"
-			class:top={handlePlacement === 'top'}
-			class:bottom={handlePlacement === 'bottom'}
-			aria-label={toggleLabel}
-			aria-expanded={!collapsed}
-			title={toggleLabel}
-			style="transform: translateY({stickyShift}px)"
-			onclick={toggle}
+	{#if !overlay || open}
+		<svelte:element
+			this={overlay ? 'div' : 'aside'}
+			bind:this={panelEl}
+			aria-label={label}
+			class="panel"
+			role={overlay ? 'dialog' : undefined}
+			aria-modal={overlay ? 'false' : undefined}
+			tabindex={overlay ? -1 : undefined}
 		>
-			<Icon name={toggleIcon} size={14} />
-		</button>
-	</aside>
+			{#if shown}
+				<div class="panel-content">{@render panel()}</div>
+				<!-- The separator role is interactive when focusable and wired to the
+				     required arrow/Home/End keyboard behavior by the resizeHandle action. -->
+				<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+				<div
+					class="resize-handle"
+					role="separator"
+					tabindex="0"
+					aria-label={`Resize ${label}`}
+					aria-orientation="vertical"
+					aria-valuemin={boundedMin}
+					aria-valuemax={boundedMax}
+					aria-valuenow={currentWidth}
+					use:resizeHandle={{
+						side,
+						min: boundedMin,
+						max: boundedMax,
+						step: resizeStep,
+						measure: () => currentWidth,
+						onwidth: setWidth,
+						oncommit: persistWidth,
+						onactive: (active) => (resizing = active)
+					}}
+				></div>
+			{/if}
 
-	<div class="main">{@render children()}</div>
+			<button
+				bind:this={handleEl}
+				type="button"
+				class="collapse-control"
+				class:top={handlePlacement === 'top'}
+				class:bottom={handlePlacement === 'bottom'}
+				aria-label={toggleLabel}
+				aria-expanded={overlay ? undefined : !collapsed}
+				title={toggleLabel}
+				style="transform: translateY({stickyShift}px)"
+				onclick={toggle}
+			>
+				<Icon name={toggleIcon} size={14} />
+			</button>
+		</svelte:element>
+	{/if}
+
+	{#if children}
+		<div class="main">{@render children()}</div>
+	{/if}
 </div>
 
 <style>
@@ -443,9 +516,54 @@
 		}
 	}
 
+	/* Overlay mode: a fixed non-modal drawer on the viewport edge. The page
+	   (`.main`) flows as normal underneath; the handle overhang is a viewport
+	   edge, so the container clamp does not apply. */
+	.panel-layout.overlay {
+		display: block;
+		container: none;
+	}
+	.overlay .panel {
+		position: fixed;
+		inset-block: 0;
+		left: 0;
+		z-index: var(--z-drawer);
+		width: min(var(--panel-current-width), 100vw);
+		box-shadow: var(--shadow-md);
+		outline: none;
+		animation: panel-slide-left 0.18s var(--ease);
+	}
+	.overlay.right .panel {
+		right: 0;
+		left: auto;
+		animation-name: panel-slide-right;
+	}
+	.overlay .resize-handle {
+		--handle-shift: -6px;
+	}
+	.overlay.full-bleed .panel {
+		width: 100vw;
+		border: 0;
+		box-shadow: none;
+	}
+	.overlay.full-bleed .resize-handle {
+		display: none;
+	}
+	@keyframes panel-slide-left {
+		from {
+			transform: translateX(-100%);
+		}
+	}
+	@keyframes panel-slide-right {
+		from {
+			transform: translateX(100%);
+		}
+	}
+
 	@media (prefers-reduced-motion: reduce) {
 		.panel {
 			transition: none;
+			animation: none;
 		}
 	}
 </style>