@joewinke/jatui 0.22.0 → 0.23.0

package/dist/components/InfiniteGrid.svelte

@@ -0,0 +1,305 @@
+<!--
+  InfiniteGrid — cursor-paged infinite-scroll grid (jatui-m4uz3.4).
+
+  Harvested from chimaro's InfiniteMediaGrid. The Supabase query, GalleryItem
+  and media types are gone; what's left is the paging machinery behind a
+  two-prop API:
+
+    <InfiniteGrid loadMore={(cursor, { signal }) => api.list({ cursor, signal })}>
+      {#snippet renderItem(item)}<MyCard {item} />{/snippet}
+    </InfiniteGrid>
+
+  `loadMore(cursor)` resolves `{ items, nextCursor, total? }`; `nextCursor: null`
+  means the end. Change `resetKey` (a query, a filter object…) to start over —
+  the in-flight request is aborted and a late page for the old key is dropped
+  (see infiniteGridLoader.ts for the race/dedupe/empty-vs-exhausted rules).
+
+  Sharp edges handled here, in the DOM half:
+    - Short pages: if the sentinel is still on screen after a page renders, the
+      next page loads immediately (an IntersectionObserver won't re-fire for a
+      target whose visibility never changed, so chimaro stalled on tall screens).
+    - Scroll anchoring: every non-item row (skeletons, spinner, sentinel, footer)
+      is `overflow-anchor: none`, so the browser anchors to a real item and the
+      "loading more" row can't drag the viewport down with it as items land
+      above it (which re-triggered the sentinel → runaway loads).
+    - Scroll root: `root` if given, else the nearest scrollable ancestor, else
+      the viewport — no more `.content-area` class sniffing.
+-->
+<script lang="ts" module>
+	export type { InfinitePage, InfiniteLoadContext, InfiniteLoadFn, InfiniteLoaderState } from './infiniteGridLoader';
+</script>
+
+<script lang="ts" generics="T, C = unknown">
+	import { onDestroy, tick, untrack, type Snippet } from 'svelte';
+	import Button from './Button.svelte';
+	import Empty from './basic/Empty.svelte';
+	import LoadingSpinner from './LoadingSpinner.svelte';
+	import {
+		createInfiniteLoader,
+		type InfiniteLoadFn,
+		type InfiniteLoaderState
+	} from './infiniteGridLoader';
+
+	interface Props {
+		/** Fetch one page. `cursor` is null for the first page. Honour `signal` to cancel. */
+		loadMore: InfiniteLoadFn<T, C>;
+		/** Render one cell. */
+		renderItem: Snippet<[T, number]>;
+		/** Stable identity for keyed rendering + cross-page de-dupe. Default: `item.id`. */
+		getKey?: (item: T) => unknown;
+		/** Change to reset and reload from the first page (query, filters, sort…). */
+		resetKey?: unknown;
+		/** Fixed column count. Omit for responsive auto-fill driven by `minItemWidth`. */
+		columns?: number;
+		/** Minimum cell width for auto-fill columns (CSS length or px number). */
+		minItemWidth?: string | number;
+		/** Grid gap (CSS length). */
+		gap?: string;
+		/** Scroll container. Default: nearest scrollable ancestor, else the viewport. */
+		root?: HTMLElement | null;
+		/** Start loading this many px before the sentinel scrolls into view. */
+		loadAhead?: number;
+		/** Placeholder cells shown while the first page loads. */
+		skeletonCount?: number;
+		/** Custom placeholder cell. */
+		skeleton?: Snippet;
+		/** Custom empty state (loaded, zero items). */
+		empty?: Snippet;
+		/** Custom end-of-list footer (loaded, some items, no more pages). */
+		end?: Snippet<[number, number | undefined]>;
+		/** Custom error row. Call `retry` to re-request the failed page. */
+		error?: Snippet<[unknown, () => void]>;
+		emptyText?: string;
+		/** Footer text for the exhausted state. Return '' to hide it. */
+		endText?: (count: number, total: number | undefined) => string;
+		/** Accessible name for the list. */
+		ariaLabel?: string;
+		class?: string;
+		itemClass?: string;
+		/** Fires on every loader transition (items, status, empty/exhausted…). */
+		onStateChange?: (state: InfiniteLoaderState<T, C>) => void;
+	}
+
+	let {
+		loadMore,
+		renderItem,
+		getKey,
+		resetKey = undefined,
+		columns,
+		minItemWidth = '10rem',
+		gap = 'var(--jatui-space-base, 0.5rem)',
+		root,
+		loadAhead = 400,
+		skeletonCount = 12,
+		skeleton,
+		empty,
+		end,
+		error,
+		emptyText = 'Nothing here yet.',
+		endText = (count, total) => `Showing all ${total ?? count} items`,
+		ariaLabel = 'Results',
+		class: className = '',
+		itemClass = '',
+		onStateChange
+	}: Props = $props();
+
+	function keyOf(item: T): unknown {
+		if (getKey) return getKey(item);
+		if (item && typeof item === 'object' && 'id' in item) return (item as { id: unknown }).id;
+		return item;
+	}
+
+	// The closures read the CURRENT props, so a new loadMore/getKey is picked up
+	// on the next request without rebuilding the loader.
+	const loader = createInfiniteLoader<T, C>({
+		load: (cursor, ctx) => loadMore(cursor, ctx),
+		getKey: (item) => keyOf(item),
+		onChange: (s) => {
+			view = s;
+			onStateChange?.(s);
+		}
+	});
+	let view = $state.raw<InfiniteLoaderState<T, C>>(loader.state);
+
+	let sentinelEl = $state<HTMLElement>();
+	let scrollRoot: HTMLElement | null = null;
+	let destroyed = false;
+
+	const loading = $derived(view.status === 'loading');
+	const showSkeleton = $derived(!view.initialized && view.status !== 'error');
+	const trackStyle = $derived(
+		columns
+			? `--ig-cols: repeat(${columns}, minmax(0, 1fr)); --ig-gap: ${gap};`
+			: `--ig-cols: repeat(auto-fill, minmax(min(${typeof minItemWidth === 'number' ? `${minItemWidth}px` : minItemWidth}, 100%), 1fr)); --ig-gap: ${gap};`
+	);
+	const announcement = $derived.by(() => {
+		if (view.status === 'error') return 'Failed to load more items.';
+		if (view.empty) return emptyText;
+		if (view.exhausted) return `All ${view.items.length} items loaded.`;
+		if (view.initialized && view.status === 'idle' && view.lastPageCount > 0)
+			return `Loaded ${view.lastPageCount} more items.`;
+		return '';
+	});
+
+	function findScrollRoot(el: HTMLElement): HTMLElement | null {
+		for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+			const oy = getComputedStyle(p).overflowY;
+			if (oy === 'auto' || oy === 'scroll' || oy === 'overlay') return p;
+		}
+		return null;
+	}
+
+	/** Geometric check, not the IO flag: the flag lags a frame behind fresh DOM. */
+	function sentinelInRange(): boolean {
+		if (!sentinelEl) return false;
+		const top = sentinelEl.getBoundingClientRect().top;
+		const bottom = scrollRoot ? scrollRoot.getBoundingClientRect().bottom : window.innerHeight;
+		return top <= bottom + loadAhead;
+	}
+
+	/** Load pages until the sentinel is off screen, the list ends, or it errors. */
+	async function pump() {
+		while (!destroyed) {
+			const generation = loader.state.generation;
+			await loader.loadNext();
+			if (destroyed || loader.state.generation !== generation || loader.state.status !== 'idle') return;
+			await tick();
+			if (!sentinelInRange()) return;
+		}
+	}
+
+	/** Start over from the first page. */
+	export function reset() {
+		loader.reset();
+		void pump();
+	}
+
+	/** Re-request the page that failed. */
+	export function retry() {
+		void loader.retry().then(() => {
+			if (loader.state.status === 'idle') void pump();
+		});
+	}
+
+	// First load + reload whenever resetKey changes.
+	$effect(() => {
+		void resetKey;
+		untrack(reset);
+	});
+
+	$effect(() => {
+		const el = sentinelEl;
+		if (!el) return;
+		scrollRoot = root === undefined ? findScrollRoot(el) : root;
+		const io = new IntersectionObserver(
+			(entries) => {
+				if (entries.some((e) => e.isIntersecting)) void pump();
+			},
+			{ root: scrollRoot, rootMargin: `0px 0px ${loadAhead}px 0px` }
+		);
+		io.observe(el);
+		return () => io.disconnect();
+	});
+
+	onDestroy(() => {
+		destroyed = true;
+		loader.destroy();
+	});
+</script>
+
+<div class="jatui-infinite-grid {className}">
+	<ul class="ig-track" style={trackStyle} aria-label={ariaLabel} aria-busy={loading}>
+		{#if showSkeleton}
+			{#each { length: skeletonCount } as _, i (i)}
+				<li class="ig-placeholder" aria-hidden="true">
+					{#if skeleton}{@render skeleton()}{:else}<div class="skeleton aspect-square w-full"></div>{/if}
+				</li>
+			{/each}
+		{:else}
+			{#each view.items as item, i (keyOf(item))}
+				<li class="ig-item min-w-0 {itemClass}">{@render renderItem(item, i)}</li>
+			{/each}
+		{/if}
+	</ul>
+
+	{#if view.initialized && loading}
+		<div class="ig-row flex justify-center py-4">
+			<LoadingSpinner size="sm" text="Loading more…" textPosition="right" />
+		</div>
+	{:else if view.status === 'error'}
+		<div class="ig-row">
+			{#if error}
+				{@render error(view.error, retry)}
+			{:else}
+				<div class="flex flex-col items-center gap-2 py-6 text-sm" role="alert">
+					<span class="text-error">
+						{view.items.length ? "Couldn't load more items." : "Couldn't load items."}
+					</span>
+					<Button size="sm" variant="outline" onclick={retry}>Retry</Button>
+				</div>
+			{/if}
+		</div>
+	{:else if view.empty}
+		<div class="ig-row">
+			{#if empty}{@render empty()}{:else}<Empty copy={emptyText} />{/if}
+		</div>
+	{:else if view.exhausted}
+		<div class="ig-row">
+			{#if end}
+				{@render end(view.items.length, view.total)}
+			{:else if endText(view.items.length, view.total)}
+				<p class="text-base-content/50 py-4 text-center text-sm">
+					{endText(view.items.length, view.total)}
+				</p>
+			{/if}
+		</div>
+	{/if}
+
+	<!-- Always mounted so the observer is set up once; pump() decides whether to load. -->
+	<div bind:this={sentinelEl} class="ig-row ig-sentinel" aria-hidden="true"></div>
+
+	<div class="sr-only" aria-live="polite">{announcement}</div>
+</div>
+
+<style>
+	.jatui-infinite-grid {
+		min-width: 0;
+	}
+
+	.ig-track {
+		display: grid;
+		grid-template-columns: var(--ig-cols);
+		gap: var(--ig-gap);
+		list-style: none;
+		margin: 0;
+		padding: 0;
+	}
+
+	.ig-item {
+		animation: ig-enter var(--motion-enter, 200ms) var(--motion-glide, ease-out) both;
+	}
+
+	/* Scroll anchoring: only real items may be chosen as the anchor node. */
+	.ig-placeholder,
+	.ig-row {
+		overflow-anchor: none;
+	}
+
+	.ig-sentinel {
+		height: 1px;
+		pointer-events: none;
+	}
+
+	@keyframes ig-enter {
+		from {
+			opacity: 0;
+			transform: translateY(4px);
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.ig-item {
+			animation: none;
+		}
+	}
+</style>

package/dist/components/InfiniteGrid.svelte.d.ts

@@ -0,0 +1,71 @@
+export type { InfinitePage, InfiniteLoadContext, InfiniteLoadFn, InfiniteLoaderState } from './infiniteGridLoader';
+import { type Snippet } from 'svelte';
+import { type InfiniteLoadFn, type InfiniteLoaderState } from './infiniteGridLoader';
+declare function $$render<T, C = unknown>(): {
+    props: {
+        /** Fetch one page. `cursor` is null for the first page. Honour `signal` to cancel. */
+        loadMore: InfiniteLoadFn<T, C>;
+        /** Render one cell. */
+        renderItem: Snippet<[T, number]>;
+        /** Stable identity for keyed rendering + cross-page de-dupe. Default: `item.id`. */
+        getKey?: (item: T) => unknown;
+        /** Change to reset and reload from the first page (query, filters, sort…). */
+        resetKey?: unknown;
+        /** Fixed column count. Omit for responsive auto-fill driven by `minItemWidth`. */
+        columns?: number;
+        /** Minimum cell width for auto-fill columns (CSS length or px number). */
+        minItemWidth?: string | number;
+        /** Grid gap (CSS length). */
+        gap?: string;
+        /** Scroll container. Default: nearest scrollable ancestor, else the viewport. */
+        root?: HTMLElement | null;
+        /** Start loading this many px before the sentinel scrolls into view. */
+        loadAhead?: number;
+        /** Placeholder cells shown while the first page loads. */
+        skeletonCount?: number;
+        /** Custom placeholder cell. */
+        skeleton?: Snippet;
+        /** Custom empty state (loaded, zero items). */
+        empty?: Snippet;
+        /** Custom end-of-list footer (loaded, some items, no more pages). */
+        end?: Snippet<[number, number | undefined]>;
+        /** Custom error row. Call `retry` to re-request the failed page. */
+        error?: Snippet<[unknown, () => void]>;
+        emptyText?: string;
+        /** Footer text for the exhausted state. Return '' to hide it. */
+        endText?: (count: number, total: number | undefined) => string;
+        /** Accessible name for the list. */
+        ariaLabel?: string;
+        class?: string;
+        itemClass?: string;
+        /** Fires on every loader transition (items, status, empty/exhausted…). */
+        onStateChange?: (state: InfiniteLoaderState<T, C>) => void;
+    };
+    exports: {
+        reset: () => void;
+        retry: () => void;
+    };
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T, C = unknown> {
+    props(): ReturnType<typeof $$render<T, C>>['props'];
+    events(): ReturnType<typeof $$render<T, C>>['events'];
+    slots(): ReturnType<typeof $$render<T, C>>['slots'];
+    bindings(): "";
+    exports(): {
+        reset: () => void;
+        retry: () => void;
+    };
+}
+interface $$IsomorphicComponent {
+    new <T, C = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T, C>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T, C>['props']>, ReturnType<__sveltets_Render<T, C>['events']>, ReturnType<__sveltets_Render<T, C>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T, C>['bindings']>;
+    } & ReturnType<__sveltets_Render<T, C>['exports']>;
+    <T, C = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<T, C>['props']> & {}): ReturnType<__sveltets_Render<T, C>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+declare const InfiniteGrid: $$IsomorphicComponent;
+type InfiniteGrid<T, C = unknown> = InstanceType<typeof InfiniteGrid<T, C>>;
+export default InfiniteGrid;

package/dist/components/InfiniteSearchGrid.svelte

@@ -0,0 +1,131 @@
+<!--
+  InfiniteSearchGrid — search box + InfiniteGrid (jatui-m4uz3.4).
+
+  Harvested from chimaro's InfiniteSearchGrid, minus its global searchStore,
+  Supabase client and media types. The query is debounced, then becomes the
+  grid's `resetKey`: each new query aborts the in-flight page and drops any late
+  page for the previous one, so typing fast never interleaves result sets.
+
+    <InfiniteSearchGrid search={(q, cursor, { signal }) => api.search({ q, cursor, signal })}>
+      {#snippet renderItem(item)}<MyCard {item} />{/snippet}
+    </InfiniteSearchGrid>
+
+  Every other InfiniteGrid prop (columns, minItemWidth, getKey, root, skeleton,
+  end, error…) passes straight through.
+-->
+<script lang="ts" generics="T, C = unknown">
+	import { onDestroy, type ComponentProps, type Snippet } from 'svelte';
+	import InfiniteGrid from './InfiniteGrid.svelte';
+	import Empty from './basic/Empty.svelte';
+	import type { InfiniteLoadContext, InfinitePage } from './infiniteGridLoader';
+
+	type GridProps = ComponentProps<typeof InfiniteGrid<T, C>>;
+
+	interface Props extends Omit<GridProps, 'loadMore' | 'resetKey' | 'empty' | 'emptyText'> {
+		/** Fetch one page of results for `query`. `cursor` is null for the first page. */
+		search: (query: string, cursor: C | null, ctx: InfiniteLoadContext) => Promise<InfinitePage<T, C>>;
+		/** The (raw, undebounced) query text. */
+		query?: string;
+		/** Debounce between the last keystroke and the request. */
+		debounceMs?: number;
+		/** Below this many (trimmed) characters no request is made and `prompt` shows. 0 = browse with an empty query. */
+		minQueryLength?: number;
+		placeholder?: string;
+		/** Accessible label for the search field. */
+		searchLabel?: string;
+		/** Shown while the query is shorter than `minQueryLength`. */
+		promptText?: string;
+		prompt?: Snippet;
+		/** Empty-state text for a query with zero results. */
+		noResultsText?: (query: string) => string;
+		noResults?: Snippet<[string]>;
+		/** Extra controls rendered beside the search field (filters, sort…). */
+		toolbar?: Snippet;
+	}
+
+	let {
+		search,
+		query = $bindable(''),
+		debounceMs = 300,
+		minQueryLength = 0,
+		placeholder = 'Search…',
+		searchLabel = 'Search',
+		promptText = 'Start typing to search.',
+		prompt,
+		noResultsText = (q) => (q ? `No results for “${q}”.` : 'Nothing here yet.'),
+		noResults,
+		toolbar,
+		ariaLabel = 'Search results',
+		...gridProps
+	}: Props = $props();
+
+	let committed = $state(query.trim());
+	let timer: ReturnType<typeof setTimeout> | undefined;
+
+	function commit() {
+		clearTimeout(timer);
+		committed = query.trim();
+	}
+
+	// Debounce: external writes to `query` (bind:query) go through the same path.
+	$effect(() => {
+		const next = query.trim();
+		clearTimeout(timer);
+		if (next === committed) return;
+		timer = setTimeout(() => (committed = next), next === '' ? 0 : debounceMs);
+	});
+
+	onDestroy(() => clearTimeout(timer));
+
+	const ready = $derived(committed.length >= minQueryLength);
+
+	function onkeydown(e: KeyboardEvent) {
+		if (e.key === 'Enter') {
+			e.preventDefault();
+			commit();
+		} else if (e.key === 'Escape' && query) {
+			e.preventDefault();
+			e.stopPropagation();
+			query = '';
+			commit();
+		}
+	}
+</script>
+
+<div class="flex flex-col gap-3">
+	<div class="flex flex-wrap items-center gap-2">
+		<label class="input input-bordered flex min-w-0 flex-1 items-center gap-2">
+			<svg class="size-4 opacity-50" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
+				<circle cx="11" cy="11" r="7" /><path d="m20 20-3.5-3.5" stroke-linecap="round" />
+			</svg>
+			<input
+				type="search"
+				class="grow"
+				bind:value={query}
+				{placeholder}
+				aria-label={searchLabel}
+				autocomplete="off"
+				{onkeydown}
+			/>
+		</label>
+		{#if toolbar}{@render toolbar()}{/if}
+	</div>
+
+	{#if ready}
+		<InfiniteGrid
+			{...gridProps}
+			{ariaLabel}
+			resetKey={committed}
+			emptyText={noResultsText(committed)}
+			loadMore={(cursor, ctx) => search(committed, cursor, ctx)}
+		>
+			{#snippet empty()}
+				{#if noResults}{@render noResults(committed)}{:else}<Empty copy={noResultsText(committed)} />{/if}
+			{/snippet}
+		</InfiniteGrid>
+	{:else if prompt}
+		{@render prompt()}
+	{:else}
+		<Empty copy={promptText} />
+	{/if}
+</div>

package/dist/components/InfiniteSearchGrid.svelte.d.ts

@@ -0,0 +1,67 @@
+import { type Snippet } from 'svelte';
+import type { InfiniteLoadContext, InfinitePage } from './infiniteGridLoader';
+declare function $$render<T, C = unknown>(): {
+    props: Omit<{
+        loadMore: import("./infiniteGridLoader").InfiniteLoadFn<T, C>;
+        renderItem: Snippet<[T, number]>;
+        getKey?: ((item: T) => unknown) | undefined;
+        resetKey?: unknown;
+        columns?: number;
+        minItemWidth?: string | number;
+        gap?: string;
+        root?: HTMLElement | null;
+        loadAhead?: number;
+        skeletonCount?: number;
+        skeleton?: Snippet;
+        empty?: Snippet;
+        end?: Snippet<[number, number | undefined]>;
+        error?: Snippet<[unknown, () => void]> | undefined;
+        emptyText?: string;
+        endText?: ((count: number, total: number | undefined) => string) | undefined;
+        ariaLabel?: string;
+        class?: string;
+        itemClass?: string;
+        onStateChange?: ((state: import("./infiniteGridLoader").InfiniteLoaderState<T, C>) => void) | undefined;
+    }, "empty" | "loadMore" | "resetKey" | "emptyText"> & {
+        /** Fetch one page of results for `query`. `cursor` is null for the first page. */
+        search: (query: string, cursor: C | null, ctx: InfiniteLoadContext) => Promise<InfinitePage<T, C>>;
+        /** The (raw, undebounced) query text. */
+        query?: string;
+        /** Debounce between the last keystroke and the request. */
+        debounceMs?: number;
+        /** Below this many (trimmed) characters no request is made and `prompt` shows. 0 = browse with an empty query. */
+        minQueryLength?: number;
+        placeholder?: string;
+        /** Accessible label for the search field. */
+        searchLabel?: string;
+        /** Shown while the query is shorter than `minQueryLength`. */
+        promptText?: string;
+        prompt?: Snippet;
+        /** Empty-state text for a query with zero results. */
+        noResultsText?: (query: string) => string;
+        noResults?: Snippet<[string]>;
+        /** Extra controls rendered beside the search field (filters, sort…). */
+        toolbar?: Snippet;
+    };
+    exports: {};
+    bindings: "query";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T, C = unknown> {
+    props(): ReturnType<typeof $$render<T, C>>['props'];
+    events(): ReturnType<typeof $$render<T, C>>['events'];
+    slots(): ReturnType<typeof $$render<T, C>>['slots'];
+    bindings(): "query";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T, C = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T, C>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T, C>['props']>, ReturnType<__sveltets_Render<T, C>['events']>, ReturnType<__sveltets_Render<T, C>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T, C>['bindings']>;
+    } & ReturnType<__sveltets_Render<T, C>['exports']>;
+    <T, C = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<T, C>['props']> & {}): ReturnType<__sveltets_Render<T, C>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+declare const InfiniteSearchGrid: $$IsomorphicComponent;
+type InfiniteSearchGrid<T, C = unknown> = InstanceType<typeof InfiniteSearchGrid<T, C>>;
+export default InfiniteSearchGrid;

package/dist/components/KeyboardShortcutsOverlay.svelte

@@ -15,7 +15,17 @@
 	 *     { key: 'k / ↑', description: 'Focus previous item' },
 	 *     { key: 'Enter', description: 'Open detail' },
 	 *   ]} />
+	 *
+	 * Or feed it from a shortcut registry (createShortcutRegistry) — the
+	 * overlay lists whatever can fire right now, grouped by context, and
+	 * pushes a modal context while open so page shortcuts don't fire behind it:
+	 *
+	 *   <KeyboardShortcutsOverlay {registry} />
+	 *
+	 * Precedence: `sections` > `registry` > `shortcuts`. The overlay owns `?` —
+	 * don't register it in the registry too.
 	 */
+	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
 
 	export interface KeyboardShortcut {
 		key: string;
@@ -37,6 +47,7 @@
 	let {
 		shortcuts = [],
 		sections,
+		registry,
 		title = 'Keyboard Shortcuts',
 		open = $bindable(false)
 	}: {
@@ -47,6 +58,11 @@
 		 * precedence over the flat `shortcuts` prop.
 		 */
 		sections?: ShortcutSection[];
+		/**
+		 * Shortcut registry to read sections from (active contexts, top of
+		 * the stack first). Ignored when `sections` is given.
+		 */
+		registry?: ShortcutRegistry;
 		title?: string;
 		open?: boolean;
 	} = $props();
@@ -60,6 +76,19 @@
 		open = isOpen;
 	});
 
+	// Registry sections are snapshotted on open — BEFORE pushing the overlay's
+	// own modal context, which would otherwise hide every page context.
+	let registrySections = $state<ShortcutSection[] | null>(null);
+	$effect(() => {
+		if (!isOpen || !registry) return;
+		registrySections = registry.toSections();
+		return registry.pushContext('keyboard-shortcuts-overlay', { modal: true });
+	});
+
+	const shownSections = $derived(
+		sections && sections.length > 0 ? sections : registry ? registrySections : null
+	);
+
 	// Track which key label is currently depressed
 	let depressedKey = $state<string | null>(null);
 	let depressTimer: ReturnType<typeof setTimeout> | null = null;
@@ -104,7 +133,15 @@
 		if (!pressed) return false;
 		// Match single-char labels directly
 		const parts = keyLabel.split(/\s*\/\s*/);
-		return parts.some(p => p.trim() === pressed || p.trim().toLowerCase() === pressed.toLowerCase());
+		const p = pressed.toLowerCase();
+		return parts.some((part) => {
+			const t = part.trim();
+			if (t === pressed || t.toLowerCase() === p) return true;
+			// Combo labels ("Ctrl+K", "⇧⌘K") — match on the key itself.
+			const base = (t.length > 1 && t.includes('+') ? t.slice(t.lastIndexOf('+', t.length - 2) + 1) : t)
+				.replace(/^[⌃⌥⇧⌘]+/, '');
+			return base !== t && base.toLowerCase() === p;
+		});
 	}
 
 	$effect(() => {
@@ -143,8 +180,8 @@
 				</button>
 			</div>
 			<div class="kso-list">
-				{#if sections && sections.length > 0}
-					{#each sections as section, sIdx (section.title + '::' + sIdx)}
+				{#if shownSections && shownSections.length > 0}
+					{#each shownSections as section, sIdx (section.title + '::' + sIdx)}
 						<div class="kso-section-title">{section.title}</div>
 						{#each section.shortcuts as { key, description, color }, i (section.title + '::' + key + '::' + i)}
 							<div class="kso-row">