@joewinke/jatui 0.34.2 → 0.36.1

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

@@ -11,6 +11,11 @@ export interface ActionButton {
     key?: string;
     /** Called when clicked */
     onclick: () => void;
+    /** Dimmed, non-interactive button (mardukos). */
+    disabled?: boolean;
+    /** When set, the button is disabled and shows a spinner + this text
+     * instead of the label (mardukos per-action loading). */
+    loadingText?: string | null;
 }
 export interface DropdownItem {
     /** Display label */

package/dist/components/KeyboardShortcutsOverlay.svelte

@@ -39,9 +39,32 @@
 	 *   <KeyboardShortcutsOverlay {registry}>
 	 *     {#snippet extra()}<div>…custom footer…</div>{/snippet}
 	 *   </KeyboardShortcutsOverlay>
+	 *
+	 * ── Host / contributor mode ───────────────────────────────────────────
+	 *
+	 * An app shell can mount ONE global host overlay; every other instance
+	 * on the page then contributes its sections to the host instead of
+	 * self-rendering, so exactly one `?` overlay exists no matter how many
+	 * surfaces mount the component:
+	 *
+	 *   // App shell (layout.svelte):
+	 *   <KeyboardShortcutsOverlay mode="host" />
+	 *
+	 *   // A page with its own shortcut set:
+	 *   <KeyboardShortcutsOverlay {sections} sectionTitle="Inbox" />
+	 *
+	 * `mode` defaults to `'auto'`: the instance contributes to the host when
+	 * one is mounted, and self-renders when there isn't (the portal /
+	 * contract-page fallback). Force self-rendering with
+	 * `mode="standalone"`.
 	 */
 	import type { Snippet } from 'svelte';
 	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+	import {
+		keyboardShortcutHub,
+		type ShortcutContribution,
+		type ShortcutSectionLike
+	} from '../utils/keyboardShortcutHub';
 
 	export interface KeyboardShortcut {
 		key: string;
@@ -67,7 +90,27 @@
 		extraSections,
 		extra,
 		title = 'Keyboard Shortcuts',
-		open = $bindable(false)
+		open = $bindable(false),
+		/**
+		 * Host / contributor mode.
+		 *  - `'host'`: this instance IS the global overlay — it registers
+		 *    with the hub and aggregates contributions from other instances.
+		 *  - `'auto'` (default): contribute to the host when one exists,
+		 *    otherwise self-render (the portal / contract-page fallback).
+		 *  - `'standalone'`: never defer, always self-render.
+		 */
+		mode = 'auto',
+		/**
+		 * Label under which this instance's sections appear in the host
+		 * panel when contributing. Ignored when self-rendering.
+		 */
+		sectionTitle = 'Page shortcuts',
+		/**
+		 * Show the closed-state "press ?" hint pill (bottom-right).
+		 * `showHint={false}` opts out — e.g. on contributor instances that
+		 * defer to the host's own hint.
+		 */
+		showHint = true
 	}: {
 		shortcuts?: KeyboardShortcut[];
 		/**
@@ -97,6 +140,9 @@
 		extra?: Snippet;
 		title?: string;
 		open?: boolean;
+		mode?: 'auto' | 'host' | 'standalone';
+		sectionTitle?: string;
+		showHint?: boolean;
 	} = $props();
 
 	let isOpen = $state(open);
@@ -108,19 +154,103 @@
 		open = isOpen;
 	});
 
-	// Registry sections are snapshotted on open — BEFORE pushing the overlay's
-	// own modal context, which would otherwise hide every page context.
+	// ── Registry → sections ─────────────────────────────────────────────
+	// Registry sections are kept live via `registry.subscribe()` so the host
+	// panel always reflects the current context stack. The overlay pushes its
+	// own modal context while open, which hides the page contexts underneath —
+	// that push is what suppresses page shortcuts behind the modal.
 	let registrySections = $state<ShortcutSection[] | null>(null);
 	$effect(() => {
-		if (!isOpen || !registry) return;
+		if (!registry) return;
 		registrySections = registry.toSections();
+		return registry.subscribe(() => {
+			registrySections = registry.toSections();
+		});
+	});
+	$effect(() => {
+		if (!isOpen || !registry) return;
 		return registry.pushContext('keyboard-shortcuts-overlay', { modal: true });
 	});
 
-	const shownSections = $derived(
+	// ── Hub wiring ──────────────────────────────────────────────────────
+	let hubHasHost = $state(keyboardShortcutHub.hasHost);
+	let hubContributions = $state<ShortcutContribution[]>(keyboardShortcutHub.getContributions());
+	$effect(() => {
+		return keyboardShortcutHub.subscribe(() => {
+			hubHasHost = keyboardShortcutHub.hasHost;
+			hubContributions = keyboardShortcutHub.getContributions();
+		});
+	});
+
+	// A 'host' instance registers itself with the hub while mounted.
+	$effect(() => {
+		if (mode !== 'host') return;
+		return keyboardShortcutHub.registerHost({
+			open: () => {
+				isOpen = true;
+			},
+			toggle: () => {
+				isOpen = !isOpen;
+			}
+		});
+	});
+
+	// Whether this instance self-renders or defers to the host.
+	const isHost = $derived(mode === 'host');
+	const isContributor = $derived(mode !== 'host' && mode !== 'standalone' && hubHasHost);
+
+	// This instance's own sections (precedence: sections > registry > null).
+	const ownSections = $derived(
 		sections && sections.length > 0 ? sections : registry ? registrySections : null
 	);
 
+	// Contributing instances hand their sections to the hub. `extraSections`
+	// ride along too — they belong to the page, not the overlay itself.
+	const contributionId = `kso-${Math.random().toString(36).slice(2, 10)}`;
+	$effect(() => {
+		if (!isContributor) return;
+		const primary = ownSections ?? [];
+		if (primary.length === 0 && (!extraSections || extraSections.length === 0)) return;
+		const contribution: ShortcutContribution = {
+			id: contributionId,
+			sectionTitle,
+			sections: primary,
+			registrySections: extraSections ?? []
+		};
+		return keyboardShortcutHub.contribute(contribution);
+	});
+
+	// Contributing instances forward external `open` requests to the host —
+	// they can't open themselves.
+	$effect(() => {
+		if (!isContributor) return;
+		if (!open) return;
+		keyboardShortcutHub.requestOpen();
+		isOpen = false;
+	});
+
+	function flattenSections(secs: ShortcutSectionLike[]): SectionEntry[] {
+		return secs.flatMap((s) => s.shortcuts);
+	}
+
+	// Host panel content: own sections plus every contributor's sections,
+	// each grouped under its sectionTitle.
+	const hostSections = $derived.by(() => {
+		if (!isHost) return null;
+		const primary = ownSections ?? (shortcuts.length > 0 ? [{ title, shortcuts }] : []);
+		const contributed: ShortcutSection[] = hubContributions.flatMap((c) => [
+			{ title: c.sectionTitle, shortcuts: flattenSections(c.sections) },
+			...(c.registrySections ?? []).map((s) => ({ title: s.title, shortcuts: s.shortcuts }))
+		]);
+		return [...primary, ...contributed];
+	});
+
+	// What actually renders in the panel.
+	const shownSections = $derived(isHost ? hostSections : ownSections);
+	const shownFlatShortcuts = $derived(
+		isHost || (shownSections && shownSections.length > 0) ? [] : shortcuts
+	);
+
 	// Track which key label is currently depressed
 	let depressedKey = $state<string | null>(null);
 	let depressTimer: ReturnType<typeof setTimeout> | null = null;
@@ -143,6 +273,8 @@
 		if (e.key === '?') {
 			// `?` is always Shift+/. Don't trigger while typing — would swallow the char.
 			if (isTypingTarget(e.target)) return;
+			// A contributor doesn't own `?` — the host's own listener handles it.
+			if (isContributor) return;
 			e.preventDefault();
 			isOpen = !isOpen;
 			return;
@@ -236,7 +368,7 @@
 						{/each}
 					{/each}
 				{:else}
-					{#each shortcuts as { key, description }, i (key + '::' + i)}
+					{#each shownFlatShortcuts as { key, description }, i (key + '::' + i)}
 						<div class="kso-row">
 							<kbd
 								class="kso-key"
@@ -279,6 +411,13 @@
 			</div>
 		</div>
 	</div>
+{:else if showHint && !isContributor}
+	<!-- Closed-state hint — press ? to open. Contributors that defer to a
+	     host stay silent: the host renders its own hint. -->
+	<div class="kso-hint" aria-hidden="true">
+		<kbd class="kso-hint-key">?</kbd>
+		<span class="kso-hint-text">for shortcuts</span>
+	</div>
 {/if}
 
 <style>
@@ -419,6 +558,39 @@
 		border-color: oklch(0.45 0.06 240);
 	}
 
+	.kso-hint {
+		position: fixed;
+		right: 1rem;
+		bottom: 1rem;
+		z-index: 50;
+		display: flex;
+		align-items: center;
+		gap: 0.45rem;
+		padding: 0.3rem 0.65rem;
+		background: oklch(0.18 0.02 250 / 0.85);
+		border: 1px solid oklch(0.30 0.03 250);
+		border-radius: 0.5rem;
+		color: oklch(0.85 0.02 250);
+		font-size: 0.78rem;
+		pointer-events: none;
+		animation: kso-fade 0.15s ease-out;
+	}
+
+	.kso-hint-key {
+		font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+		font-size: 0.72rem;
+		background: oklch(0.25 0.02 250);
+		border: 1px solid oklch(0.35 0.02 250);
+		border-bottom-width: 2px;
+		border-radius: 0.3rem;
+		padding: 0.05rem 0.45rem;
+		color: oklch(0.93 0.02 250);
+	}
+
+	.kso-hint-text {
+		color: oklch(0.72 0.02 250);
+	}
+
 	@keyframes kso-fade {
 		from {
 			opacity: 0;
@@ -430,7 +602,8 @@
 
 	@media (prefers-reduced-motion: reduce) {
 		.kso-backdrop,
-		.kso-panel {
+		.kso-panel,
+		.kso-hint {
 			animation: none !important;
 		}
 		.kso-key {

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

@@ -38,6 +38,24 @@
      *   <KeyboardShortcutsOverlay {registry}>
      *     {#snippet extra()}<div>…custom footer…</div>{/snippet}
      *   </KeyboardShortcutsOverlay>
+     *
+     * ── Host / contributor mode ───────────────────────────────────────────
+     *
+     * An app shell can mount ONE global host overlay; every other instance
+     * on the page then contributes its sections to the host instead of
+     * self-rendering, so exactly one `?` overlay exists no matter how many
+     * surfaces mount the component:
+     *
+     *   // App shell (layout.svelte):
+     *   <KeyboardShortcutsOverlay mode="host" />
+     *
+     *   // A page with its own shortcut set:
+     *   <KeyboardShortcutsOverlay {sections} sectionTitle="Inbox" />
+     *
+     * `mode` defaults to `'auto'`: the instance contributes to the host when
+     * one is mounted, and self-renders when there isn't (the portal /
+     * contract-page fallback). Force self-rendering with
+     * `mode="standalone"`.
      */
 import type { Snippet } from 'svelte';
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
@@ -84,6 +102,9 @@ type $$ComponentProps = {
     extra?: Snippet;
     title?: string;
     open?: boolean;
+    mode?: 'auto' | 'host' | 'standalone';
+    sectionTitle?: string;
+    showHint?: boolean;
 };
 declare const KeyboardShortcutsOverlay: import("svelte").Component<$$ComponentProps, {}, "open">;
 type KeyboardShortcutsOverlay = ReturnType<typeof KeyboardShortcutsOverlay>;