@fuzdev/fuz_app 0.115.0 → 0.117.0

package/dist/ui/AppShell.svelte

@@ -4,114 +4,442 @@
 	 * a fresh `SidebarState` if `sidebar_state` is not supplied) so descendants
 	 * can read sidebar visibility and toggle it. Optionally binds a global
 	 * keyboard shortcut and renders a built-in toggle button (or a custom one
-	 * via the `toggle_button` snippet).
+	 * via the `toggle_button` snippet) while the sidebar is enabled. Requires
+	 * the SvelteKit runtime — it closes the overlay from `afterNavigate`.
+	 *
+	 * Two modes, split by the state's `narrow_query`. Outside it the sidebar
+	 * sits beside the content, padded by `--sidebar_offset`, following
+	 * `show_sidebar_wide`. Inside it the sidebar starts closed and opens as an
+	 * overlay over a scrim, following `show_sidebar_narrow`; the content is
+	 * `inert` while it's open, and navigation, Escape, a scrim click, or
+	 * widening out of narrow mode closes it. Escape never prevents the
+	 * default, so the browser's close requests stay intact; it does nothing
+	 * while a modal (`:modal`) is open, or when a window `keydown` listener
+	 * registered before the overlay opened swallows it (a contextmenu, say).
+	 *
+	 * The open overlay is a modal dialog: the sidebar takes `role="dialog"`,
+	 * `aria-modal`, `tabindex="-1"`, and `sidebar_label` as its name, and
+	 * focus moves into it, to its first control that takes focus, else to the
+	 * sidebar itself — the content went inert and dropped it. The attributes
+	 * key on the open overlay, which reads the viewport — that's what keeps
+	 * the wide sidebar from ever being a dialog — and the server render
+	 * matches hydration because the overlay always starts closed, as with the
+	 * content's `inert`. `aria-modal` lets assistive tech hide everything
+	 * outside the sidebar, the built-in toggle included, so a sidebar whose
+	 * screen-reader users need a close control beyond Escape and navigation
+	 * renders its own.
+	 *
+	 * Closing with Escape, the keyboard shortcut, or a scrim click returns
+	 * focus to what opened the overlay, or else to the first element whose
+	 * `aria-controls` names the sidebar's id and that takes it — when focus
+	 * was inside the sidebar or had fallen to the body. The id is the state's
+	 * `sidebar_id` when set, so a toggle outside the shell can carry
+	 * `aria-controls` too; Safari doesn't focus a clicked button, so without
+	 * it a mouse-opened overlay has no opener to return to.
+	 *
+	 * The shell's rules sit in two cascade layers nested under `fuz_app`.
+	 * `fuz_app.app_shell_base`, in the scoped style, holds the base and state
+	 * rules, which apply in both modes; `fuz_app.app_shell_narrow` overrides
+	 * some of them from a style element in `svelte:head` carrying
+	 * `media={narrow_query}`, so the server render paints the right mode
+	 * before hydration and the markup's classes never depend on the viewport.
+	 * The narrow layer is ordered after the base layer, so it wins whatever
+	 * the selectors' specificity or the sheets' order. Its rules are global —
+	 * they match every `.app-shell` on the page — so shells mounted at the
+	 * same time must share a `narrow_query`. Pages served under a strict CSP
+	 * need `style-src-elem 'unsafe-inline'` or the hash of that constant style.
+	 *
+	 * Public class hooks: `.app-shell` (root, with state classes `.wide-open` /
+	 * `.narrow-open`), `.app-shell-content`, `.app-shell-sidebar`,
+	 * `.app-shell-scrim`, `.app-shell-toggle`, `.app-shell-toggle-glyph`. Any
+	 * unlayered rule beats both layers at any specificity, so overrides need
+	 * no specificity games; to layer them instead, order `fuz_app` first
+	 * (`@layer fuz_app, overrides;`) in a sheet that loads before the shell.
+	 * The same rule means an unlayered reset overrides the shell too — the
+	 * fuz_css reset zeroes `padding`, `margin`, and `border` on every element —
+	 * so the layers set none of those. The one they need, the content's
+	 * wide offset, goes through `--sidebar_offset`: the layers set it on
+	 * `.app-shell-content` (`--sidebar_width` while the wide sidebar is open,
+	 * else `0px`), and one unlayered rule at (0,0,1) reads it into the
+	 * content's `padding-left`. Descendants of the content can read it too.
+	 * Override the offset by setting `--sidebar_offset` on
+	 * `.app-shell-content` or with a `padding-left` rule there; a `padding`
+	 * shorthand there overrides it as well. Like any unlayered override,
+	 * these apply in both modes, open or closed; to change only the wide open
+	 * offset, target `.app-shell.wide-open > .app-shell-content` inside the
+	 * narrow query's negation — the state classes don't track the viewport,
+	 * so `.wide-open` stays set in narrow mode too. CSS variables:
+	 * `--sidebar_bg`, `--sidebar_z_index` (default `200` in both modes; the toggle sits one
+	 * above), `--sidebar_scrim_bg`, `--sidebar_width` (set from the
+	 * `sidebar_width` prop; always the configured width, not the offset), and
+	 * `--sidebar_offset`.
 	 *
 	 * @module
 	 */
 
-	import type { Snippet } from 'svelte';
+	import { flushSync, type Snippet } from 'svelte';
 	import type { SvelteHTMLElements } from 'svelte/elements';
+	import { on } from 'svelte/events';
+	import { afterNavigate } from '$app/navigation';
 	import { is_editable, swallow } from '@fuzdev/fuz_util/dom.ts';
 
 	import { SidebarState, sidebar_state_context } from './sidebar_state.svelte.js';
 
+	// what can take focus from the keyboard, narrowed further by `tabIndex`
+	const FOCUSABLE_SELECTOR =
+		'a[href], area[href], button, input, select, textarea, iframe, summary, [tabindex], [contenteditable]';
+
 	const {
 		children,
 		sidebar,
 		sidebar_width = 180,
+		sidebar_label = 'sidebar',
 		sidebar_state: sidebar_state_prop,
 		keyboard_shortcut = false,
 		show_toggle = true,
 		toggle_button,
+		class: class_prop,
 		...rest
 	}: SvelteHTMLElements['div'] & {
 		children: Snippet;
 		sidebar: Snippet;
 		/**
-		 * Sidebar width in pixels when shown.
+		 * Sidebar width in pixels when shown; in narrow mode capped at `85vw`.
 		 * @default 180
 		 */
 		sidebar_width?: number;
+		/**
+		 * Accessible name for the sidebar while it's the narrow-mode overlay,
+		 * announced as a modal dialog.
+		 * @default 'sidebar'
+		 */
+		sidebar_label?: string;
 		/** Optional pre-built `SidebarState` for sharing visibility across shells. */
 		sidebar_state?: SidebarState;
 		/**
-		 * Single-key shortcut that toggles the sidebar (e.g. `'b'`). `false` disables.
+		 * Single-key shortcut that toggles the sidebar (e.g. `'b'`) while it's
+		 * enabled and no modal is open — the persistent sidebar in wide mode,
+		 * the overlay in narrow mode. `false` disables.
 		 * @default false
 		 */
 		keyboard_shortcut?: string | false;
 		/**
-		 * Whether to render the built-in (or custom) toggle button.
+		 * Whether to render the built-in (or custom) toggle button. It renders
+		 * only while the sidebar is enabled either way.
 		 * @default true
 		 */
 		show_toggle?: boolean;
-		/** Custom toggle-button renderer; receives the title, visibility, and toggle callback. */
-		toggle_button?: Snippet<[{ title: string; show_sidebar: boolean; toggle: () => void }]>;
+		/**
+		 * Custom toggle-button renderer; receives the title, visibility, toggle
+		 * callback, and the sidebar element's id. Give the button
+		 * `class="app-shell-toggle"` so it stacks above the sidebar and scrim
+		 * (it renders as a direct child of the root) — the z-index applies only
+		 * to a positioned button, so position it (e.g. `position: fixed`) — and
+		 * `aria-controls={sidebar_id}` so closing can return focus to it.
+		 * `show_sidebar` is viewport-dependent: the server renders it as in wide
+		 * mode, so rendering it as visible content changes on hydration at
+		 * narrow widths — attributes are repaired, but key visible content on
+		 * CSS or the viewport-free fields instead.
+		 */
+		toggle_button?: Snippet<
+			[{ title: string; show_sidebar: boolean; toggle: () => void; sidebar_id: string }]
+		>;
 	} = $props();
 
+	const uid = $props.id();
+
+	let fallback_sidebar_state: SidebarState | undefined;
 	const get_sidebar_state = sidebar_state_context.set(
-		() => sidebar_state_prop ?? new SidebarState()
+		() => sidebar_state_prop ?? (fallback_sidebar_state ??= new SidebarState())
 	);
 	const sidebar_state = $derived(get_sidebar_state());
 
-	const sidebar_width_px = $derived(sidebar_state.show_sidebar ? sidebar_width : 0);
+	const sidebar_id = $derived(sidebar_state.sidebar_id ?? `${uid}-sidebar`);
+
+	// viewport-free, so the server and hydration renders agree
+	const wide_open = $derived(sidebar_state.enabled && sidebar_state.show_sidebar_wide);
+	const narrow_open = $derived(sidebar_state.enabled && sidebar_state.show_sidebar_narrow);
+	// viewport-dependent, only for `inert` and input handling (always `false` in SSR)
+	const overlay_open = $derived(sidebar_state.narrow && narrow_open);
 
 	const button_title = $derived(
 		(sidebar_state.show_sidebar ? 'hide sidebar' : 'show sidebar') +
 			(keyboard_shortcut ? ` [${keyboard_shortcut}]` : '')
 	);
+
+	let sidebar_el: HTMLElement | undefined = $state();
+	let opener: HTMLElement | null = null;
+
+	afterNavigate(() => sidebar_state.close_narrow());
+
+	// widening out of narrow mode closes the overlay; the wide preference is untouched
+	$effect(() => {
+		if (!sidebar_state.narrow) sidebar_state.close_narrow();
+	});
+
+	const on_escape = (e: KeyboardEvent): void => {
+		if (e.key !== 'Escape' || e.defaultPrevented || !overlay_open) return;
+		// an open modal dialog owns Escape; not preventing the default leaves the
+		// browser's close requests (dialog `cancel`, `popover="auto"`) intact
+		if (document.querySelector(':modal')) return;
+		close_overlay();
+	};
+
+	// closes the overlay, returning focus when it was inside the sidebar or had
+	// fallen to the body — the inert content drops focus opened from within it
+	const close_overlay = (): void => {
+		const active = document.activeElement;
+		const should_return_focus =
+			!active || active === document.body || !!sidebar_el?.contains(active);
+		// flush so the content is no longer `inert` when focus returns into it
+		flushSync(() => sidebar_state.close_narrow());
+		if (should_return_focus) return_focus();
+	};
+
+	// focuses `el`, returning whether it took focus — disabled, hidden, and
+	// inert elements refuse it
+	const try_focus = (el: HTMLElement): boolean => {
+		el.focus();
+		return document.activeElement === el;
+	};
+
+	// the opener if it's still there and takes focus, else the first toggle that
+	// does — Safari doesn't focus a clicked button, so the opener can be `null`
+	const return_focus = (): void => {
+		if (opener?.isConnected && try_focus(opener)) return;
+		for (const toggle of document.querySelectorAll<HTMLElement>('[aria-controls]')) {
+			// `aria-controls` is an id list
+			const ids = toggle.getAttribute('aria-controls')!.split(/\s+/);
+			if (ids.includes(sidebar_id) && try_focus(toggle)) return;
+		}
+	};
+
+	// the first control in the sidebar that takes focus, else the sidebar itself
+	// (`tabindex="-1"` while it's the overlay); `tabIndex` screens out what only
+	// script can focus
+	const focus_sidebar = (): void => {
+		if (!sidebar_el) return;
+		for (const el of sidebar_el.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)) {
+			if (el.tabIndex >= 0 && try_focus(el)) return;
+		}
+		sidebar_el.focus();
+	};
+
+	// while the overlay is open, remember what had focus (to return it on
+	// close), move focus into the sidebar — the content just went inert, which
+	// drops its focus — and listen for Escape, registered now, not at mount, so
+	// window listeners mounted earlier (a contextmenu's, say) see Escape first
+	// and can swallow it
+	$effect(() => {
+		if (!overlay_open) return;
+		const active = document.activeElement;
+		// never an element in the sidebar, which hides again on close
+		opener =
+			active instanceof HTMLElement && active !== document.body && !sidebar_el?.contains(active)
+				? active
+				: null;
+		focus_sidebar();
+		return on(window, 'keydown', on_escape);
+	});
 </script>
 
+<svelte:head>
+	{#if sidebar_state.narrow_query !== null}
+		<style media={sidebar_state.narrow_query}>
+			@layer fuz_app.app_shell_base, fuz_app.app_shell_narrow;
+			@layer fuz_app.app_shell_narrow {
+				.app-shell > .app-shell-content {
+					--sidebar_offset: 0px;
+				}
+				.app-shell > .app-shell-sidebar {
+					visibility: hidden;
+					translate: -100% 0;
+					width: min(var(--sidebar_width), 85vw);
+				}
+				.app-shell.narrow-open > .app-shell-sidebar {
+					visibility: visible;
+					translate: none;
+				}
+				.app-shell.narrow-open > .app-shell-scrim {
+					display: block;
+				}
+				.app-shell > .app-shell-toggle .app-shell-toggle-glyph {
+					scale: -1 1;
+				}
+				.app-shell.narrow-open > .app-shell-toggle .app-shell-toggle-glyph {
+					scale: none;
+				}
+				@media (prefers-reduced-motion: no-preference) {
+					.app-shell > .app-shell-sidebar {
+						transition:
+							translate 150ms ease-out,
+							visibility 0s 150ms;
+					}
+					.app-shell.narrow-open > .app-shell-sidebar {
+						transition:
+							translate 150ms ease-out,
+							visibility 0s;
+					}
+				}
+			}
+		</style>
+	{/if}
+</svelte:head>
+
 <svelte:window
 	onkeydowncapture={(e) => {
-		if (keyboard_shortcut && e.key === keyboard_shortcut && !is_editable(e.target)) {
-			sidebar_state.toggle_sidebar();
+		if (
+			keyboard_shortcut &&
+			sidebar_state.enabled &&
+			e.key === keyboard_shortcut &&
+			!is_editable(e.target) &&
+			// a modal owns the keyboard, even one opened from the overlay
+			!document.querySelector(':modal')
+		) {
+			// closing the overlay returns focus like Escape; the rest just toggles
+			if (overlay_open) {
+				close_overlay();
+			} else {
+				sidebar_state.toggle_sidebar();
+			}
 			swallow(e);
 		}
 	}}
 />
 
-<div {...rest} style:--sidebar_width="{sidebar_width_px}px">
-	<div class="content" style:padding-left="var(--sidebar_width)">
+<div
+	{...rest}
+	class={['app-shell', class_prop, { 'wide-open': wide_open, 'narrow-open': narrow_open }]}
+	style:--sidebar_width="{sidebar_width}px"
+>
+	<div class="app-shell-content" inert={overlay_open}>
 		{@render children()}
 	</div>
-	<div class="sidebar" style:width="var(--sidebar_width)">
-		{@render sidebar()}
-	</div>
-	{#if show_toggle}
+	<!-- pointer-only dismissal; Escape is the keyboard path -->
+	<div class="app-shell-scrim" aria-hidden="true" onclick={close_overlay}></div>
+	{#if show_toggle && sidebar_state.enabled}
 		{#if toggle_button}
 			{@render toggle_button({
 				title: button_title,
 				show_sidebar: sidebar_state.show_sidebar,
-				toggle: () => sidebar_state.toggle_sidebar()
+				toggle: () => sidebar_state.toggle_sidebar(),
+				sidebar_id
 			})}
 		{:else}
 			<button
 				type="button"
-				class="position:fixed bottom:0 left:0 icon_button plain border-radius:0 border_top_right_radius_sm"
-				aria-label={button_title}
+				class="app-shell-toggle position:fixed bottom:0 left:0 icon_button plain border-radius:0 border_top_right_radius_sm"
+				aria-label="sidebar"
+				aria-keyshortcuts={keyboard_shortcut || undefined}
+				aria-expanded={sidebar_state.show_sidebar}
+				aria-controls={sidebar_id}
 				title={button_title}
 				onclick={() => sidebar_state.toggle_sidebar()}
 			>
-				{sidebar_state.show_sidebar ? '\u2190' : '\u2192'}
+				<span class="app-shell-toggle-glyph" aria-hidden="true">←</span>
 			</button>
 		{/if}
 	{/if}
+	<!-- open, the overlay is a modal dialog whose `tabindex="-1"` makes it focus's
+		fallback target; the wide sidebar stays a plain element, so a click on its
+		background doesn't take focus. The a11y rule can't see the value is only
+		ever -1. -->
+	<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+	<div
+		class="app-shell-sidebar"
+		id={sidebar_id}
+		role={overlay_open ? 'dialog' : undefined}
+		aria-modal={overlay_open ? 'true' : undefined}
+		aria-label={overlay_open ? sidebar_label : undefined}
+		tabindex={overlay_open ? -1 : undefined}
+		bind:this={sidebar_el}
+	>
+		{@render sidebar()}
+	</div>
 </div>
 
 <style>
-	.sidebar {
-		position: fixed;
-		top: 0;
-		left: 0;
-		height: 100%;
-		overflow: auto;
-		scrollbar-width: thin;
-		background: var(--sidebar_bg, var(--shade_05));
+	/*
+	 * The shell's rules sit in `fuz_app.app_shell_base`. The narrow overrides live
+	 * in the `media` style in `svelte:head`, in `fuz_app.app_shell_narrow`, which
+	 * this order statement puts after the base layer — so they win regardless of
+	 * specificity (these selectors carry the scope hash) or of which sheet loads
+	 * first. The head style opens with the same statement; repeating it here pins
+	 * the order whichever sheet the browser meets first.
+	 */
+	@layer fuz_app.app_shell_base, fuz_app.app_shell_narrow;
+
+	/*
+	 * Never put a property the fuz_css reset sets (`padding`, `margin`, `border`,
+	 * `box-sizing`, and their longhands) in a layer: the reset is unlayered, so it
+	 * beats every layered declaration and the layered value computes to the
+	 * reset's. Route such a value through a custom property the layers set, read
+	 * by an unlayered rule. The content offset is the one case: the layers set
+	 * `--sidebar_offset`, and this rule reads it. It's unscoped at (0,0,1) — above
+	 * the reset's (0,0,0), below any class selector — so a consumer rule on
+	 * `.app-shell-content` overrides it without matching specificity.
+	 */
+	:global(div:where(.app-shell > .app-shell-content)) {
+		padding-left: var(--sidebar_offset, 0px);
 	}
 
-	.content {
-		display: flex;
-		flex-direction: column;
-		min-height: 100vh;
+	@layer fuz_app.app_shell_base {
+		.app-shell-content {
+			--sidebar_offset: 0px;
+			display: flex;
+			flex-direction: column;
+			min-height: 100vh;
+		}
+		.app-shell.wide-open > .app-shell-content {
+			--sidebar_offset: var(--sidebar_width);
+		}
+
+		.app-shell-sidebar {
+			position: fixed;
+			top: 0;
+			left: 0;
+			width: var(--sidebar_width);
+			height: 100%;
+			overflow: auto;
+			overscroll-behavior: contain;
+			scrollbar-width: thin;
+			background: var(--sidebar_bg, var(--shade_05));
+			z-index: var(--sidebar_z_index, 200);
+			visibility: hidden;
+		}
+		.app-shell.wide-open > .app-shell-sidebar {
+			visibility: visible;
+		}
+
+		.app-shell-scrim {
+			display: none;
+			position: fixed;
+			inset: 0;
+			z-index: var(--sidebar_z_index, 200);
+			background: var(--sidebar_scrim_bg, var(--darken_40));
+		}
+
+		/*
+		 * The toggle and its glyph may be consumer markup from the `toggle_button`
+		 * snippet, which never carries this component's scope hash, so they're
+		 * matched by their public class names under the scoped root. The glyph
+		 * rules go through the root's own toggle so an outer shell's state never
+		 * reaches a nested shell's glyph.
+		 */
+		.app-shell > :global(.app-shell-toggle) {
+			z-index: calc(var(--sidebar_z_index, 200) + 1);
+		}
+		.app-shell > :global(.app-shell-toggle) :global(.app-shell-toggle-glyph) {
+			display: inline-block;
+			scale: -1 1;
+		}
+		.app-shell.wide-open > :global(.app-shell-toggle) :global(.app-shell-toggle-glyph) {
+			scale: none;
+		}
+
+		/* a modal in the sidebar is in the top layer but inherits its visibility */
+		.app-shell-sidebar :global(:modal) {
+			visibility: visible;
+		}
 	}
 </style>

package/dist/ui/AppShell.svelte.d.ts

@@ -3,39 +3,130 @@
      * a fresh `SidebarState` if `sidebar_state` is not supplied) so descendants
      * can read sidebar visibility and toggle it. Optionally binds a global
      * keyboard shortcut and renders a built-in toggle button (or a custom one
-     * via the `toggle_button` snippet).
+     * via the `toggle_button` snippet) while the sidebar is enabled. Requires
+     * the SvelteKit runtime — it closes the overlay from `afterNavigate`.
+     *
+     * Two modes, split by the state's `narrow_query`. Outside it the sidebar
+     * sits beside the content, padded by `--sidebar_offset`, following
+     * `show_sidebar_wide`. Inside it the sidebar starts closed and opens as an
+     * overlay over a scrim, following `show_sidebar_narrow`; the content is
+     * `inert` while it's open, and navigation, Escape, a scrim click, or
+     * widening out of narrow mode closes it. Escape never prevents the
+     * default, so the browser's close requests stay intact; it does nothing
+     * while a modal (`:modal`) is open, or when a window `keydown` listener
+     * registered before the overlay opened swallows it (a contextmenu, say).
+     *
+     * The open overlay is a modal dialog: the sidebar takes `role="dialog"`,
+     * `aria-modal`, `tabindex="-1"`, and `sidebar_label` as its name, and
+     * focus moves into it, to its first control that takes focus, else to the
+     * sidebar itself — the content went inert and dropped it. The attributes
+     * key on the open overlay, which reads the viewport — that's what keeps
+     * the wide sidebar from ever being a dialog — and the server render
+     * matches hydration because the overlay always starts closed, as with the
+     * content's `inert`. `aria-modal` lets assistive tech hide everything
+     * outside the sidebar, the built-in toggle included, so a sidebar whose
+     * screen-reader users need a close control beyond Escape and navigation
+     * renders its own.
+     *
+     * Closing with Escape, the keyboard shortcut, or a scrim click returns
+     * focus to what opened the overlay, or else to the first element whose
+     * `aria-controls` names the sidebar's id and that takes it — when focus
+     * was inside the sidebar or had fallen to the body. The id is the state's
+     * `sidebar_id` when set, so a toggle outside the shell can carry
+     * `aria-controls` too; Safari doesn't focus a clicked button, so without
+     * it a mouse-opened overlay has no opener to return to.
+     *
+     * The shell's rules sit in two cascade layers nested under `fuz_app`.
+     * `fuz_app.app_shell_base`, in the scoped style, holds the base and state
+     * rules, which apply in both modes; `fuz_app.app_shell_narrow` overrides
+     * some of them from a style element in `svelte:head` carrying
+     * `media={narrow_query}`, so the server render paints the right mode
+     * before hydration and the markup's classes never depend on the viewport.
+     * The narrow layer is ordered after the base layer, so it wins whatever
+     * the selectors' specificity or the sheets' order. Its rules are global —
+     * they match every `.app-shell` on the page — so shells mounted at the
+     * same time must share a `narrow_query`. Pages served under a strict CSP
+     * need `style-src-elem 'unsafe-inline'` or the hash of that constant style.
+     *
+     * Public class hooks: `.app-shell` (root, with state classes `.wide-open` /
+     * `.narrow-open`), `.app-shell-content`, `.app-shell-sidebar`,
+     * `.app-shell-scrim`, `.app-shell-toggle`, `.app-shell-toggle-glyph`. Any
+     * unlayered rule beats both layers at any specificity, so overrides need
+     * no specificity games; to layer them instead, order `fuz_app` first
+     * (`@layer fuz_app, overrides;`) in a sheet that loads before the shell.
+     * The same rule means an unlayered reset overrides the shell too — the
+     * fuz_css reset zeroes `padding`, `margin`, and `border` on every element —
+     * so the layers set none of those. The one they need, the content's
+     * wide offset, goes through `--sidebar_offset`: the layers set it on
+     * `.app-shell-content` (`--sidebar_width` while the wide sidebar is open,
+     * else `0px`), and one unlayered rule at (0,0,1) reads it into the
+     * content's `padding-left`. Descendants of the content can read it too.
+     * Override the offset by setting `--sidebar_offset` on
+     * `.app-shell-content` or with a `padding-left` rule there; a `padding`
+     * shorthand there overrides it as well. Like any unlayered override,
+     * these apply in both modes, open or closed; to change only the wide open
+     * offset, target `.app-shell.wide-open > .app-shell-content` inside the
+     * narrow query's negation — the state classes don't track the viewport,
+     * so `.wide-open` stays set in narrow mode too. CSS variables:
+     * `--sidebar_bg`, `--sidebar_z_index` (default `200` in both modes; the toggle sits one
+     * above), `--sidebar_scrim_bg`, `--sidebar_width` (set from the
+     * `sidebar_width` prop; always the configured width, not the offset), and
+     * `--sidebar_offset`.
      *
      * @module
      */
-import type { Snippet } from 'svelte';
+import { type Snippet } from 'svelte';
 import type { SvelteHTMLElements } from 'svelte/elements';
 import { SidebarState } from './sidebar_state.svelte.js';
 type $$ComponentProps = SvelteHTMLElements['div'] & {
     children: Snippet;
     sidebar: Snippet;
     /**
-     * Sidebar width in pixels when shown.
+     * Sidebar width in pixels when shown; in narrow mode capped at `85vw`.
      * @default 180
      */
     sidebar_width?: number;
+    /**
+     * Accessible name for the sidebar while it's the narrow-mode overlay,
+     * announced as a modal dialog.
+     * @default 'sidebar'
+     */
+    sidebar_label?: string;
     /** Optional pre-built `SidebarState` for sharing visibility across shells. */
     sidebar_state?: SidebarState;
     /**
-     * Single-key shortcut that toggles the sidebar (e.g. `'b'`). `false` disables.
+     * Single-key shortcut that toggles the sidebar (e.g. `'b'`) while it's
+     * enabled and no modal is open — the persistent sidebar in wide mode,
+     * the overlay in narrow mode. `false` disables.
      * @default false
      */
     keyboard_shortcut?: string | false;
     /**
-     * Whether to render the built-in (or custom) toggle button.
+     * Whether to render the built-in (or custom) toggle button. It renders
+     * only while the sidebar is enabled either way.
      * @default true
      */
     show_toggle?: boolean;
-    /** Custom toggle-button renderer; receives the title, visibility, and toggle callback. */
-    toggle_button?: Snippet<[{
-        title: string;
-        show_sidebar: boolean;
-        toggle: () => void;
-    }]>;
+    /**
+     * Custom toggle-button renderer; receives the title, visibility, toggle
+     * callback, and the sidebar element's id. Give the button
+     * `class="app-shell-toggle"` so it stacks above the sidebar and scrim
+     * (it renders as a direct child of the root) — the z-index applies only
+     * to a positioned button, so position it (e.g. `position: fixed`) — and
+     * `aria-controls={sidebar_id}` so closing can return focus to it.
+     * `show_sidebar` is viewport-dependent: the server renders it as in wide
+     * mode, so rendering it as visible content changes on hydration at
+     * narrow widths — attributes are repaired, but key visible content on
+     * CSS or the viewport-free fields instead.
+     */
+    toggle_button?: Snippet<[
+        {
+            title: string;
+            show_sidebar: boolean;
+            toggle: () => void;
+            sidebar_id: string;
+        }
+    ]>;
 };
 declare const AppShell: import("svelte").Component<$$ComponentProps, {}, "">;
 type AppShell = ReturnType<typeof AppShell>;

package/dist/ui/AppShell.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppShell.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/AppShell.svelte"],"names":[],"mappings":"AAGA;;;;;;;;OAQI;AACJ,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAyB,MAAM,2BAA2B,CAAC;AAE/E,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0FAA0F;IAC1F,aAAa,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAC,CAAC;CACxF,CAAC;AAmEH,QAAA,MAAM,QAAQ,sDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"AppShell.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/AppShell.svelte"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4EI;AACJ,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAK1D,OAAO,EAAE,YAAY,EAAyB,MAAM,2BAA2B,CAAC;AAE/E,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,OAAO,CACtB;QAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,OAAO,CAAC;YAAC,MAAM,EAAE,MAAM,IAAI,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE;KAAC,CAClF,CAAC;CACF,CAAC;AAsLH,QAAA,MAAM,QAAQ,sDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/ui/CLAUDE.md

@@ -76,10 +76,150 @@ pattern rather than reintroducing prop-drilling.
 ## Shell + layout
 
 - `AppShell.svelte` — sidebar-and-main shell. Props: `children`,
-  `sidebar` (Snippet), `sidebar_width = 180`, `sidebar_state?`,
-  `keyboard_shortcut?`, `show_toggle?`, `toggle_button?`.
-  Provisions `sidebar_state_context` internally (creates a fresh
-  `SidebarState` if `sidebar_state` prop is not supplied).
+  `sidebar` (Snippet), `sidebar_width = 180`, `sidebar_label = 'sidebar'`
+  (the open overlay's accessible name), `sidebar_state?`,
+  `keyboard_shortcut?`, `show_toggle?`, `toggle_button?` (receives
+  `{title, show_sidebar, toggle, sidebar_id}`). Provisions
+  `sidebar_state_context` internally (creates one `SidebarState` if the
+  `sidebar_state` prop is not supplied). Requires the SvelteKit runtime
+  (`afterNavigate` from `$app/navigation`). The toggle renders only while
+  `show_toggle && sidebar_state.enabled`, before the sidebar in the DOM;
+  the built-in one is a disclosure (`aria-expanded` + `aria-controls`
+  pointing at the sidebar's id — `SidebarState.sidebar_id` when set, else
+  one from `$props.id()`) with the static name
+  `aria-label="sidebar"`, a dynamic `title`, `aria-keyshortcuts` when
+  `keyboard_shortcut` is set, and a `←` glyph CSS mirrors when closed.
+  The shortcut acts only while the sidebar is enabled, on the current
+  mode's field (so it drives the overlay at narrow widths).
+  - **Custom toggles** (`toggle_button`): give the button
+    `class="app-shell-toggle"` — it renders as a direct child of the root,
+    where a `:global` rule (the snippet's markup carries no scope hash)
+    stacks it one above the sidebar; the z-index applies only to a
+    positioned button, so position it (e.g. `position: fixed`, like the
+    built-in one) — and `aria-controls={sidebar_id}`, which the
+    focus fallback looks up (the first match that takes focus wins).
+    `show_sidebar` is viewport-dependent (the server renders it as wide):
+    attributes are repaired on hydration, but visible content keyed on it
+    changes at narrow widths, so key visible content on CSS or the
+    viewport-free fields.
+  - **Toggles outside the shell** (a top nav's hamburger) set
+    `SidebarState`'s `sidebar_id` option and carry
+    `aria-controls={sidebar_state.sidebar_id}`, so the focus fallback finds
+    them too. `aria-controls` is read as an id list. A set id assumes one
+    shell per state — shells sharing it at the same time would render the
+    same id.
+  - **Two modes, split by `SidebarState.narrow_query`.** Wide: the sidebar
+    sits beside the content (padded by `--sidebar_offset`) and follows
+    `show_sidebar_wide`. Narrow: it starts closed and opens as an overlay
+    (capped at `85vw`) over a scrim, following `show_sidebar_narrow`; the
+    content is `inert` while open. The overlay closes on navigation
+    (`afterNavigate` inside `AppShell` — consumers write nothing), Escape,
+    a scrim click, and widening out of narrow mode (a crossing `$effect`).
+  - **The open overlay is a modal dialog.** While it's open the sidebar
+    carries `role="dialog"`, `aria-modal="true"`, and `aria-label` from
+    `sidebar_label`. They key on the open overlay (`overlay_open`), which
+    reads the viewport — that's what keeps the persistent wide sidebar (the
+    same element) from ever being a dialog — and the server render matches
+    hydration because the overlay always starts closed, as with `inert`.
+    Opening moves
+    focus into it — the content went `inert`, which dropped focus — to the
+    first control that takes focus (`tabIndex >= 0`, checked after each
+    `focus()`), else to the sidebar itself, `tabindex="-1"` while it's the
+    overlay (script-focusable, skipped by Tab; the wide sidebar has none, so
+    a click on its background leaves focus where it was). No focus trap:
+    `inert` already keeps Tab out of the content, and the built-in toggle
+    stays Tab-reachable as a close control. `aria-modal` lets assistive
+    tech hide everything outside the sidebar, the toggle included
+    (Chromium keeps it exposed; WebKit may not), so a sidebar whose
+    screen-reader users need a close control beyond Escape and navigation
+    renders its own.
+  - **Escape** is a window `keydown` listener registered by an `$effect`
+    only while the overlay is open, so listeners registered earlier (a
+    contextmenu's, mounted with the page) see Escape first and can swallow
+    it. It never calls `preventDefault`, so the browser's close requests
+    (dialog `cancel`, `popover="auto"`) stay intact, and it bails while a
+    modal is open (`document.querySelector(':modal')` matches). An open
+    `popover="auto"` isn't `:modal`, so one Escape closes it and the overlay
+    together. Closing is `flushSync`ed so the content leaves `inert` before
+    focus returns. When focus was inside the sidebar or had fallen to `body`
+    (opening from the content makes it `inert`, which drops focus there), it
+    goes back to the opener if still connected and focusable, else to the
+    first `[aria-controls]` naming the sidebar's id that takes focus (Safari
+    doesn't focus a clicked button, so the opener can be `null`). A
+    narrow-mode close from `keyboard_shortcut` or a scrim click goes through
+    the same close-and-return path; wide mode just toggles. The shortcut
+    bails on an open modal too, so pressing it inside a dialog opened from
+    the overlay doesn't close the overlay behind it.
+  - **No hydration flash.** The mode rules sit in two cascade layers
+    nested under `fuz_app`. `@layer fuz_app.app_shell_base` in the scoped
+    `<style>` holds the base and state rules, which apply in both modes;
+    the narrow overrides are one `<style media={narrow_query}>` in
+    `<svelte:head>` (Svelte attribute-escapes the query; the CSS text is
+    constant), inside `@layer fuz_app.app_shell_narrow`, rendered only
+    while `narrow_query` isn't `null`. Both sheets open with
+    `@layer fuz_app.app_shell_base, fuz_app.app_shell_narrow;`, so the
+    narrow layer wins whatever the selectors' specificity (the scoped ones
+    carry the hash) and whichever sheet the browser meets first — a
+    client-mounted shell appending its head style late changes nothing.
+    The root's state classes read only the viewport-free fields, so the
+    server render and hydration agree and CSS picks the mode; `narrow` only
+    drives `inert`, ARIA, and input routing. The narrow rules are unscoped
+    (they match every `.app-shell` by plain class names), so shells mounted
+    at the same time must share a `narrow_query`. CSP: needs
+    `style-src-elem 'unsafe-inline'` (fuz_ui's CSP default allows it) or
+    the style's hash.
+  - **Layer names are namespaced** under one top-level `fuz_app` layer, so
+    they can't collide with a consumer's and a consumer that layers its own
+    CSS has one name to order against: `@layer fuz_app, overrides;` in a
+    sheet that loads before the shell puts `overrides` above it.
+  - **Never layer a property the reset sets.** fuz_css's reset
+    (`*, ::before, ::after, ::backdrop`) sets `box-sizing`, `border`,
+    `margin`, and `padding`, and it's unlayered, so it beats every layered
+    declaration of those at any specificity. The shell routes such a value
+    through a custom property the layers set and one unlayered rule reads.
+    The content offset is the one case: the layers set `--sidebar_offset`
+    on `.app-shell-content` (`--sidebar_width` under `.wide-open`, `0px`
+    otherwise and in the narrow layer), and
+    `:global(div:where(.app-shell > .app-shell-content)) { padding-left: var(--sidebar_offset, 0px) }`
+    reads it, unscoped at (0,0,1) — above the reset's (0,0,0), below any
+    class selector. The SSR test fails any layered `padding*`, `margin*`,
+    `border*`, or `box-sizing` declaration. No other layered declaration
+    overlaps the reset or fuz_css's element base rules (the sidebar, scrim,
+    and content are `div`s and the glyph a `span`, which fuz_css leaves
+    unstyled; the toggle's only layered property is `z-index`, which
+    `button`'s base rule doesn't set).
+  - **Public class hooks**: `.app-shell` (state classes `.wide-open` /
+    `.narrow-open`), `.app-shell-content`, `.app-shell-sidebar`,
+    `.app-shell-scrim`, `.app-shell-toggle`, `.app-shell-toggle-glyph`.
+    **Any unlayered rule overrides the shell**, at any specificity and in
+    any sheet order, so no specificity matching is needed. The flip side
+    is the reset case above: an unlayered rule that sets a property the
+    shell layers wins over it, which is why the shell keeps reset-owned
+    properties out of its layers. A consumer's own layered rules order
+    against `fuz_app` by first appearance in the document, so keep
+    overrides unlayered or order `fuz_app` first. The rules that must
+    reach consumer markup are `:global` under the scoped root: the toggle's
+    z-index (`.app-shell > .app-shell-toggle`), the glyph mirroring
+    (`.app-shell > .app-shell-toggle .app-shell-toggle-glyph`, so a custom
+    toggle can reuse `.app-shell-toggle-glyph` inside its
+    `.app-shell-toggle`; going through the root's own toggle keeps an outer
+    shell's state off a nested shell's glyph), and
+    `.app-shell-sidebar :modal { visibility: visible }`, which keeps a
+    top-layer dialog opened from the sidebar shown while the sidebar hides.
+  - **CSS variables**: `--sidebar_width` (always the configured width, set
+    from the prop — not the effective offset), `--sidebar_offset` (the
+    effective offset, set on `.app-shell-content`: `--sidebar_width` while
+    the wide sidebar is open, else `0px`; the content's descendants can
+    read it, e.g. to inset a fixed header), `--sidebar_bg` (default
+    `--shade_05`), `--sidebar_z_index` (default `200` in both modes; the
+    scrim shares it, the toggle sits one above), `--sidebar_scrim_bg`
+    (default `--darken_40`). Override the offset by setting
+    `--sidebar_offset` or writing a `padding-left` rule on
+    `.app-shell-content`; a consumer `padding` shorthand there overrides it
+    too. Either applies in both modes and open or closed, since the state
+    classes don't track the viewport — wrap it in the narrow query's negation
+    to keep narrow mode at `0px`. To change only the wide open offset, target
+    `.app-shell.wide-open > .app-shell-content`, also inside that negation.
 - `ColumnLayout.svelte` — fixed `aside` column + fluid `children`
   column; `column_width = '280px'`.
 - `MenuLink.svelte` — SvelteKit `<a>` with `selected` derived from
@@ -87,8 +227,22 @@ pattern rather than reintroducing prop-drilling.
   Exact matches additionally get `aria-current="page"`. Takes `path`
   (resolved via `resolve` from `$app/paths`). The `.highlighted` name is
   intentionally free for orthogonal emphasis (badges, recent activity).
-- `sidebar_state.svelte.ts` — `SidebarState` (with `activate()` cleanup
-  pattern, optional reactive `enabled` getter), `sidebar_state_context`.
+- `sidebar_state.svelte.ts` — `SidebarState`, `sidebar_state_context`,
+  `SIDEBAR_NARROW_QUERY_DEFAULT` (`'(max-width: 800px)'`). Options:
+  `enabled?` (reactive getter overriding the internal field) and
+  `narrow_query?` (`null` disables narrow mode; must contain parentheses
+  since it feeds both CSS `media` and `MediaQuery`, which would auto-wrap a
+  paren-less query while CSS wouldn't — throws in DEV), and `sidebar_id?`
+  (the sidebar element's id, read back as the readonly `sidebar_id`, `null`
+  when unset — for toggles outside `AppShell`). Visibility is two
+  viewport-free fields, `show_sidebar_wide` (default `true`, the desktop
+  preference narrow interactions never touch) and `show_sidebar_narrow`
+  (default `false`). `narrow` is the viewport match (`false` in SSR);
+  `show_sidebar` is the effective visibility for the current mode and its
+  setter writes that mode's field, as does `toggle_sidebar` (routed at call
+  time). `close_narrow()` closes the overlay. `activate()` enables and
+  shows wide; its disposer clears `enabled` and both fields — pair with
+  `$effect` for scoped activation.
 
 ## Auth forms
 
@@ -381,7 +535,8 @@ format_scope, global_label)` helper — `global_label = null` renders no
   `format_scope?: FormatScope` prop — same shape as the context, prop
   wins when supplied.
 - `sidebar_state_context` — `() => SidebarState`. Provisioned by
-  `AppShell`.
+  `AppShell`. A toggle reading it for `aria-controls` needs the state's
+  `sidebar_id` option set (see Shell + layout).
 
 ## Popovers
 

package/dist/ui/sidebar_state.svelte.d.ts

@@ -3,8 +3,19 @@
  * `sidebar_state_context`; consumers read `show_sidebar` and call
  * `toggle_sidebar` / `activate`.
  *
+ * Visibility is two viewport-free fields — `show_sidebar_wide` (the persistent
+ * sidebar beside the content) and `show_sidebar_narrow` (the overlay below
+ * `narrow_query`) — so server and client render the same classes and CSS picks
+ * which field is in effect. `narrow` reads the viewport and is only for input
+ * handling and ARIA, never for markup that must match SSR.
+ *
  * @module
  */
+/**
+ * Default `narrow_query` — below 800px the sidebar overlays the content and
+ * starts closed.
+ */
+export declare const SIDEBAR_NARROW_QUERY_DEFAULT = "(max-width: 800px)";
 /**
  * Svelte context carrying a reactive `SidebarState` accessor. Set by
  * `ui/AppShell.svelte` (creates a fresh `SidebarState` if not supplied);
@@ -22,20 +33,80 @@ export interface SidebarStateOptions {
      * auto-returns `false` while the getter returns `false`.
      */
     enabled?: () => boolean;
+    /**
+     * Media query under which the sidebar overlays the content and starts
+     * closed. It feeds both `AppShell`'s CSS `media` attribute and a
+     * `MediaQuery`, so it must be a full query with parentheses
+     * (`'(max-width: 900px)'`, not `'max-width: 900px'`). `null` disables
+     * narrow mode.
+     * @default SIDEBAR_NARROW_QUERY_DEFAULT
+     */
+    narrow_query?: string | null;
+    /**
+     * The sidebar element's `id`. Set it when a toggle outside `AppShell` needs
+     * `aria-controls` — the relationship closing the overlay also follows to
+     * return focus when the opener didn't take it (Safari doesn't focus a
+     * clicked button). Omitted, `AppShell` generates one, which only its own
+     * toggle knows. Set, it assumes one shell per state: shells mounted at
+     * the same time with this state would render the same id.
+     */
+    sidebar_id?: string;
 }
 export declare class SidebarState {
     #private;
+    /** The media query for narrow mode, or `null` when narrow mode is disabled. */
+    readonly narrow_query: string | null;
+    /** The sidebar element's `id`, or `null` to let `AppShell` generate one. */
+    readonly sidebar_id: string | null;
+    /**
+     * Whether the sidebar shows beside the content outside narrow mode — the
+     * desktop preference. Narrow-mode interactions never touch it.
+     */
+    show_sidebar_wide: boolean;
+    /** Whether the narrow-mode overlay is open. */
+    show_sidebar_narrow: boolean;
+    /**
+     * Creates the state, subscribing to `narrow_query` unless it is `null`.
+     *
+     * @param options - enabled getter, narrow-mode query, and sidebar id
+     * @throws Error in DEV when `narrow_query` has no parentheses — `MediaQuery`
+     *   would auto-wrap it but CSS `media` would not, so they'd disagree
+     */
+    constructor(options?: SidebarStateOptions);
     get enabled(): boolean;
     set enabled(value: boolean);
+    /**
+     * Whether the viewport matches `narrow_query`. Always `false` during SSR
+     * and when `narrow_query` is `null`. Read it for input handling and ARIA
+     * only — markup that must match the server render should key on
+     * `show_sidebar_wide` / `show_sidebar_narrow` instead.
+     */
+    get narrow(): boolean;
+    /**
+     * Effective visibility for the current mode: `false` while disabled,
+     * otherwise `show_sidebar_narrow` in narrow mode and `show_sidebar_wide`
+     * outside it. The setter writes the current mode's field.
+     */
     get show_sidebar(): boolean;
     set show_sidebar(value: boolean);
-    constructor(options?: SidebarStateOptions);
+    /**
+     * Sets the current mode's visibility, routed by `narrow` at call time.
+     *
+     * @param value - the new visibility, defaults to the inverse of `show_sidebar`
+     */
     toggle_sidebar(value?: boolean): void;
+    /**
+     * Closes the narrow-mode overlay, leaving the wide preference untouched.
+     * `AppShell` calls it on navigation, Escape, scrim click, and when the
+     * viewport widens out of narrow mode.
+     */
+    close_narrow(): void;
     /**
      * Show the sidebar and enable the toggle. The returned disposer hides
      * and disables on cleanup — pair with `$effect` for scoped activation.
      *
-     * @mutates `this` - sets `enabled` and `show_sidebar`; disposer clears both
+     * @mutates `this` - sets `enabled` and `show_sidebar_wide`; the disposer
+     *   clears `enabled`, `show_sidebar_wide`, and `show_sidebar_narrow`
      */
     activate(): () => void;
 }

package/dist/ui/sidebar_state.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidebar_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/sidebar_state.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;2CAAwB,YAAY;4BAAZ,YAAY;uBAAZ,YAAY,WAAZ,YAAY;CAAG,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CACxB;AAED,qBAAa,YAAY;;IAKxB,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAEzB;IAED,IAAI,YAAY,IAAI,OAAO,CAG1B;IAED,IAAI,YAAY,CAAC,KAAK,EAAE,OAAO,EAE9B;gBAEW,OAAO,CAAC,EAAE,mBAAmB;IAIzC,cAAc,CAAC,KAAK,GAAE,OAA4B,GAAG,IAAI;IAIzD;;;;;OAKG;IACH,QAAQ,IAAI,MAAM,IAAI;CAQtB"}
+{"version":3,"file":"sidebar_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/sidebar_state.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;GAGG;AACH,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;2CAAwB,YAAY;4BAAZ,YAAY;uBAAZ,YAAY,WAAZ,YAAY;CAAG,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,YAAY;;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAoB;IAE9C,+CAA+C;IAC/C,mBAAmB,EAAE,OAAO,CAAqB;IAMjD;;;;;;OAMG;gBACS,OAAO,CAAC,EAAE,mBAAmB;IAczC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAEzB;IAED;;;;;OAKG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,OAAO,CAG1B;IAED,IAAI,YAAY,CAAC,KAAK,EAAE,OAAO,EAM9B;IAED;;;;OAIG;IACH,cAAc,CAAC,KAAK,GAAE,OAA4B,GAAG,IAAI;IAIzD;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAIpB;;;;;;OAMG;IACH,QAAQ,IAAI,MAAM,IAAI;CAStB"}

package/dist/ui/sidebar_state.svelte.js

@@ -3,9 +3,22 @@
  * `sidebar_state_context`; consumers read `show_sidebar` and call
  * `toggle_sidebar` / `activate`.
  *
+ * Visibility is two viewport-free fields — `show_sidebar_wide` (the persistent
+ * sidebar beside the content) and `show_sidebar_narrow` (the overlay below
+ * `narrow_query`) — so server and client render the same classes and CSS picks
+ * which field is in effect. `narrow` reads the viewport and is only for input
+ * handling and ARIA, never for markup that must match SSR.
+ *
  * @module
  */
+import { DEV } from 'esm-env';
+import { MediaQuery } from 'svelte/reactivity';
 import { create_context } from '@fuzdev/fuz_ui/context_helpers.ts';
+/**
+ * Default `narrow_query` — below 800px the sidebar overlays the content and
+ * starts closed.
+ */
+export const SIDEBAR_NARROW_QUERY_DEFAULT = '(max-width: 800px)';
 /**
  * Svelte context carrying a reactive `SidebarState` accessor. Set by
  * `ui/AppShell.svelte` (creates a fresh `SidebarState` if not supplied);
@@ -13,41 +26,100 @@ import { create_context } from '@fuzdev/fuz_ui/context_helpers.ts';
  */
 export const sidebar_state_context = create_context();
 export class SidebarState {
+    /** The media query for narrow mode, or `null` when narrow mode is disabled. */
+    narrow_query;
+    /** The sidebar element's `id`, or `null` to let `AppShell` generate one. */
+    sidebar_id;
+    /**
+     * Whether the sidebar shows beside the content outside narrow mode — the
+     * desktop preference. Narrow-mode interactions never touch it.
+     */
+    show_sidebar_wide = $state.raw(true);
+    /** Whether the narrow-mode overlay is open. */
+    show_sidebar_narrow = $state.raw(false);
     #get_enabled;
     #enabled = $state.raw(true);
-    #show_sidebar = $state.raw(true);
+    #narrow_media;
+    /**
+     * Creates the state, subscribing to `narrow_query` unless it is `null`.
+     *
+     * @param options - enabled getter, narrow-mode query, and sidebar id
+     * @throws Error in DEV when `narrow_query` has no parentheses — `MediaQuery`
+     *   would auto-wrap it but CSS `media` would not, so they'd disagree
+     */
+    constructor(options) {
+        this.#get_enabled = options?.enabled;
+        const narrow_query = options?.narrow_query === undefined ? SIDEBAR_NARROW_QUERY_DEFAULT : options.narrow_query;
+        if (DEV && narrow_query !== null && !narrow_query.includes('(')) {
+            throw new Error(`SidebarState narrow_query must include parentheses, got '${narrow_query}' — try '(${narrow_query})'`);
+        }
+        this.narrow_query = narrow_query;
+        this.sidebar_id = options?.sidebar_id ?? null;
+        this.#narrow_media = narrow_query === null ? null : new MediaQuery(narrow_query, false);
+    }
     get enabled() {
         return this.#get_enabled?.() ?? this.#enabled;
     }
     set enabled(value) {
         this.#enabled = value;
     }
+    /**
+     * Whether the viewport matches `narrow_query`. Always `false` during SSR
+     * and when `narrow_query` is `null`. Read it for input handling and ARIA
+     * only — markup that must match the server render should key on
+     * `show_sidebar_wide` / `show_sidebar_narrow` instead.
+     */
+    get narrow() {
+        return this.#narrow_media?.current ?? false;
+    }
+    /**
+     * Effective visibility for the current mode: `false` while disabled,
+     * otherwise `show_sidebar_narrow` in narrow mode and `show_sidebar_wide`
+     * outside it. The setter writes the current mode's field.
+     */
     get show_sidebar() {
         if (!this.enabled)
             return false;
-        return this.#show_sidebar;
+        return this.narrow ? this.show_sidebar_narrow : this.show_sidebar_wide;
     }
     set show_sidebar(value) {
-        this.#show_sidebar = value;
-    }
-    constructor(options) {
-        this.#get_enabled = options?.enabled;
+        if (this.narrow) {
+            this.show_sidebar_narrow = value;
+        }
+        else {
+            this.show_sidebar_wide = value;
+        }
     }
+    /**
+     * Sets the current mode's visibility, routed by `narrow` at call time.
+     *
+     * @param value - the new visibility, defaults to the inverse of `show_sidebar`
+     */
     toggle_sidebar(value = !this.show_sidebar) {
         this.show_sidebar = value;
     }
+    /**
+     * Closes the narrow-mode overlay, leaving the wide preference untouched.
+     * `AppShell` calls it on navigation, Escape, scrim click, and when the
+     * viewport widens out of narrow mode.
+     */
+    close_narrow() {
+        this.show_sidebar_narrow = false;
+    }
     /**
      * Show the sidebar and enable the toggle. The returned disposer hides
      * and disables on cleanup — pair with `$effect` for scoped activation.
      *
-     * @mutates `this` - sets `enabled` and `show_sidebar`; disposer clears both
+     * @mutates `this` - sets `enabled` and `show_sidebar_wide`; the disposer
+     *   clears `enabled`, `show_sidebar_wide`, and `show_sidebar_narrow`
      */
     activate() {
         this.enabled = true;
-        this.show_sidebar = true;
+        this.show_sidebar_wide = true;
         return () => {
             this.enabled = false;
-            this.show_sidebar = false;
+            this.show_sidebar_wide = false;
+            this.show_sidebar_narrow = false;
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.115.0",
+  "version": "0.117.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",