@joewinke/jatui 0.2.33 → 0.3.1

package/CLAUDE.md

@@ -58,21 +58,25 @@ Then import:
 | `Badge` | Status/label badge | `variant`, `size`, `children` (snippet) |
 | `StatusBadge` | Status indicator with dot | `status: StatusValue`, `label` |
 | `Card` | Content card container | `title`, `children` (snippet) |
-| `Modal` | Dialog overlay | `open` (bindable), `title`, `children` (snippet) |
+| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number` |
 | `ConfirmModal` | Yes/no confirmation dialog | `open` (bindable), `title`, `message`, `onConfirm`, `onCancel` |
 | `Drawer` | Slide-out side panel | `open` (bindable), `side`, `children` (snippet) |
 | `LoadingSpinner` | Spinner animation | `size`, `color` |
 | `Sparkline` | Inline mini chart | `data: number[]`, `width`, `height`, `color` |
 | `LazyImage` | Image with lazy loading + placeholder | `src`, `alt`, `placeholder` |
 | `HunkDiffView` | Side-by-side diff with line numbers, red/green backgrounds, strikethrough on removed lines, inline word-level highlights via the `diff` lib. Used for reviewing YAML/text changes per hunk. | `oldText: string \| null`, `newText: string \| null`, `unified?: boolean` |
-| `ContextMenu` | Floating right-click (or programmatic) action menu, positioned via `use:floating` at a cursor point. Real `<button>`s, per-item `icon`/`variant`/`disabled`, dividers, click-outside + Escape dismiss, arrow-key/Home/End roving nav (focus starts on the first item). | `open` (bindable), `x`, `y`, `items: ContextMenuItem[]`, `header?`, `zIndex?`, `onClose?` |
+| `ContextMenu` | Floating right-click (or programmatic) action menu, positioned via `use:floating` at a cursor point. Real `<button>`s, per-item `icon`/`variant`/`disabled`, dividers, click-outside + Escape dismiss, arrow-key/Home/End roving nav (focus starts on the first item). Items may declare `submit: SubmitConfig` to POST to a SvelteKit form action instead of (or in addition to) `onSelect` — a hidden `<form>` is built, requestSubmit()ed, then removed, so `use:enhance` fires exactly like a regular form submission. **Items also support nested `submenu: ContextMenuItem[]`** (right-side popover on hover/focus/ArrowRight, chevron indicator, ArrowLeft/Escape closes just the submenu) **and inline `content: Snippet`** (replaces the default icon+label row with an arbitrary widget — the wrapping button still closes the menu, so widgets that shouldn't must `event.stopPropagation()`). | `open` (bindable), `x`, `y`, `items: ContextMenuItem[]`, `header?`, `zIndex?`, `onClose?` |
 | `ContextMenuTrigger` | Wraps content with the standard right-click + "⋯" touch affordance, backed by `ContextMenu`. Use instead of hand-rolling `oncontextmenu` + a kebab button per row/card. | `items: ContextMenuItem[]`, `children` (snippet), `header?`, `triggerLabel?`, `hideButton?`, `zIndex?`, `class?` |
+| `Tooltip` | Component-shaped wrapper around the shared `use:tooltip` action — for cases where you can't easily add an attribute to the target element (wrap a chip / badge / icon in the tooltip instead). Warm/cool window + `aria-describedby` are shared with the action. Prefer `use:tooltip` directly when you own the element. | `content: string`, `placement?`, `delayMs?`, `disabled?`, `display?`, `children` (snippet) |
+| `DirtyFormHost` | Composable form dirty-state manager — renders your form body plus a floating "Unsaved changes" pill + Cancel button; wires `beforeunload` and (optional) SvelteKit `beforeNavigate`. Callers who want bespoke pill/Cancel chrome use `createDirtyGuard()` directly and skip the component. Extracted from the F12 pattern in `/admin/roles/[id]`. | `baseline: T`, `current: T`, `onCancel?`, `beforeNavigate?`, `discardPrompt?`, `equals?`, `hideChrome?`, `children` (snippet with `{dirty, cancel}`) |
+| `BulkActionBar` | Floating action bar that appears when a `listNav` selection is non-empty. Simpler API than `FloatingActionBar` (takes a `Set`, `Array`, or plain number for `selection`, and a flat `actions[]` with `{label, onSelect, destructive?}`) — reach for `FloatingActionBar` directly when you need dropdown groups. | `selection: Set \| Array \| number`, `actions: BulkAction[]`, `onClear?`, `loading?`, `countLabel?` |
 
 ### Media
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
 | `MediaWorkbench` | Full-featured image editor modal — upload, AI generate, AI edit, background removal, annotation canvas. **Preferred over `SmartImageEditor` for new image fields.** Two-column modal: preview left, 4 action tabs right (Generate, Edit, Remove BG, Annotate). Save uploads blob to `uploadEndpoint` or emits `onComplete`. Requires proxy endpoints from jst-23w1l.2. | `value` (bindable `string \| null`), `uploadEndpoint?` (default `/api/media`), `onComplete?`, `accept?` |
+| `MediaLightbox` | Full-screen media preview — z-9040 backdrop, arrow-key paging when given an array, `+/-/0` zoom, download action, Escape/backdrop close. **Use this for the general "just show it big" case** — replaces hand-rolled `fixed inset-0 z-[9040]` modals. For annotated / markup-overlaid image previews, use `ImageLightbox` instead. | `src?`, `filename?`, `kind?: 'image' \| 'video'`, `downloadUrl?`, `items?: MediaItem[]`, `initialIndex?`, `onClose?`, `zIndex?` |
 | `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker) and talk-time legend. **Every intelligence prop is optional** — a bare mp4 still gets the scrubber, hover-time card, wheel volume and keyboard map, and each pane lights up as its data arrives (nothing shifts layout when diarization lands late). Wheel means volume over the video (shift = seek) and zoom over the band. | `src`, `chapters?`, `speakers?`, `transcript?`, `bookmarks?`, `waveform?`, `talkTime?`, `startAt?`, `poster?`, `captionsSrc?`, `transcriptPosition?` (`'below' \| 'side'`), `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
 
 **`VideoPlayer` vs `TranscriptPlayer`:** VideoPlayer is the generalization — it does everything TranscriptPlayer does plus the timeline band, and its props are structurally compatible with TranscriptPlayer's (`TranscriptSegment[]`, `TranscriptChapter[]`, `TranscriptBookmark[]`, `TranscriptSpeakerTalkTime[]` all pass straight through). `TranscriptPlayer` stays exported and unchanged for the existing meeting-recordings viewer; use `VideoPlayer` for anything new.
@@ -212,6 +216,25 @@ import { loadGoogleMapsAPI, isGoogleMapsLoaded } from 'jatui'
 await loadGoogleMapsAPI({ apiKey, libraries: ['marker', 'geometry'] })
 ```
 
+## Global confirm dialog
+
+```typescript
+import { showConfirm } from "jatui"
+// String body (backwards-compatible):
+if (await showConfirm({ title: "Delete?", body: "This cannot be undone." })) { ... }
+
+// Snippet body — for rich content (conditional warnings, formatted amounts):
+{#snippet warnBody()}
+  <p>You're deleting <strong>{count}</strong> items totalling <strong>{fmt(amount)}</strong>.</p>
+  {#if hasPendingWork}<p class="text-warning mt-2">3 items still processing.</p>{/if}
+{/snippet}
+if (await showConfirm({ title: "Delete?", body: warnBody, danger: true })) { ... }
+```
+
+## Typography utility
+
+`text-2xs` — 11px / 16px line-height / +0.01em tracking. Ships in `styles/rail.css` (already imported by JST). Standardizes the ~13 sites of `text-[10px]` / `text-[0.7rem]` micro-captions across JST routes (timestamps, hint text, footnotes). Sits between Tailwind's `text-xs` (12px) and browser-min legibility.
+
 ## Utilities
 
 ```typescript

package/dist/components/BulkActionBar.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+	/**
+	 * BulkActionBar — floating action bar for listNav selections.
+	 *
+	 * Simpler API than `FloatingActionBar`: takes a `Set` or `Array` of
+	 * selected ids and a flat `actions[]`. Renders nothing when the
+	 * selection is empty; auto-fades in when there is at least one item.
+	 * Under the hood a thin wrapper over `FloatingActionBar` — reach for
+	 * `FloatingActionBar` directly when you need dropdown groups.
+	 *
+	 * Usage:
+	 *
+	 *     const nav = listNav({ selectable: true });
+	 *
+	 *     <ul use:nav>...</ul>
+	 *
+	 *     <BulkActionBar
+	 *       selection={nav.selection}
+	 *       actions={[
+	 *         { label: 'Assign',  onSelect: () => assignBulk(nav.selection) },
+	 *         { label: 'Delete',  onSelect: () => deleteBulk(nav.selection), destructive: true },
+	 *       ]}
+	 *       onClear={() => nav.clearSelection()}
+	 *     />
+	 */
+
+	import FloatingActionBar from './FloatingActionBar.svelte';
+	import type { ActionButton } from './FloatingActionBar.svelte';
+
+	export interface BulkAction {
+		label: string;
+		/** Optional SVG path string for a 24×24 icon. */
+		icon?: string;
+		/** Called when the action is clicked. */
+		onSelect: () => void;
+		/** Renders in the danger variant. Default false. */
+		destructive?: boolean;
+		/** Semantic variant override — takes precedence over `destructive`. */
+		variant?: ActionButton['variant'];
+		/** Unique key (defaults to label). */
+		id?: string;
+	}
+
+	interface Props {
+		/** Current selection — Set, Array, or a plain number. Bar hides when empty/zero. */
+		selection: Set<unknown> | unknown[] | number;
+		/** Actions to render. */
+		actions: BulkAction[];
+		/** Called when the user clicks the built-in Clear button. */
+		onClear?: () => void;
+		/** Loading state — disables all actions and shows a spinner. */
+		loading?: boolean;
+		/** Label for the count. Default "selected". */
+		countLabel?: string;
+	}
+
+	let { selection, actions, onClear, loading = false, countLabel = 'selected' }: Props = $props();
+
+	const count = $derived(
+		typeof selection === 'number'
+			? selection
+			: Array.isArray(selection)
+				? selection.length
+				: selection.size,
+	);
+
+	const mapped = $derived<ActionButton[]>(
+		actions.map((a) => ({
+			id: a.id ?? a.label,
+			label: a.label,
+			icon: a.icon,
+			variant: a.variant ?? (a.destructive ? 'danger' : 'default'),
+			onclick: a.onSelect,
+		})),
+	);
+</script>
+
+<FloatingActionBar {count} actions={mapped} {loading} {onClear} {countLabel} />

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

@@ -0,0 +1,29 @@
+import type { ActionButton } from './FloatingActionBar.svelte';
+export interface BulkAction {
+    label: string;
+    /** Optional SVG path string for a 24×24 icon. */
+    icon?: string;
+    /** Called when the action is clicked. */
+    onSelect: () => void;
+    /** Renders in the danger variant. Default false. */
+    destructive?: boolean;
+    /** Semantic variant override — takes precedence over `destructive`. */
+    variant?: ActionButton['variant'];
+    /** Unique key (defaults to label). */
+    id?: string;
+}
+interface Props {
+    /** Current selection — Set, Array, or a plain number. Bar hides when empty/zero. */
+    selection: Set<unknown> | unknown[] | number;
+    /** Actions to render. */
+    actions: BulkAction[];
+    /** Called when the user clicks the built-in Clear button. */
+    onClear?: () => void;
+    /** Loading state — disables all actions and shows a spinner. */
+    loading?: boolean;
+    /** Label for the count. Default "selected". */
+    countLabel?: string;
+}
+declare const BulkActionBar: import("svelte").Component<Props, {}, "">;
+type BulkActionBar = ReturnType<typeof BulkActionBar>;
+export default BulkActionBar;

package/dist/components/ConfirmDialog.svelte

@@ -104,7 +104,11 @@
 				<div class="cd-title-group">
 					<h3 class="cd-title">{opts.title}</h3>
 					{#if opts.body}
-						<p class="cd-body">{opts.body}</p>
+						{#if typeof opts.body === 'string'}
+							<p class="cd-body">{opts.body}</p>
+						{:else}
+							<div class="cd-body">{@render opts.body()}</div>
+						{/if}
 					{/if}
 				</div>
 			</div>

package/dist/components/ContextMenu.svelte

@@ -31,21 +31,15 @@
 	 * Keyboard: ArrowUp/ArrowDown/Home/End move focus among items, Escape
 	 * dismisses (handled by use:floating), Enter/Space activates the focused
 	 * button natively. Focus moves to the first item when the menu opens and
-	 * returns to the trigger when it closes.
+	 * returns to the trigger when it closes. Items may declare a nested
+	 * `submenu` array — ArrowRight opens it, ArrowLeft returns focus to the
+	 * parent item (and closes the submenu). Items may also carry a `content`
+	 * Snippet to render arbitrary widgets in place of the default label row.
 	 */
 
 	import { floating, makeVirtualAnchor } from '../actions/floating.js';
-
-	type ActionItem = {
-		label: string;
-		/** Optional leading icon — a single emoji/glyph, rendered before the label. */
-		icon?: string;
-		onSelect: () => void;
-		variant?: 'default' | 'danger';
-		disabled?: boolean;
-	};
-	type DividerItem = { divider: true };
-	export type ContextMenuItem = ActionItem | DividerItem;
+	import SelfContextMenu from './ContextMenu.svelte';
+	import type { ActionItem, ContextMenuItem, SubmitConfig } from './ContextMenu.types.js';
 
 	interface Props {
 		/** Whether the menu is currently shown. Bindable. */
@@ -77,33 +71,142 @@
 		onClose
 	}: Props = $props();
 
+	// Submenu state — index into `items` of the currently-open submenu (if any),
+	// plus its viewport anchor coordinates. A single open submenu at a time.
+	let submenuIndex = $state<number | null>(null);
+	let submenuX = $state(0);
+	let submenuY = $state(0);
+
+	function closeSubmenu() {
+		if (submenuIndex === null) return;
+		submenuIndex = null;
+	}
+
 	function close() {
 		if (!open) return;
+		closeSubmenu();
 		open = false;
 		onClose?.();
 	}
 
-	function handleSelect(item: ActionItem) {
+	function openSubmenuAt(el: HTMLElement, index: number) {
+		const rect = el.getBoundingClientRect();
+		submenuX = rect.right;
+		submenuY = rect.top;
+		submenuIndex = index;
+	}
+
+	function handleItemClick(item: ActionItem, index: number, event: MouseEvent) {
 		if (item.disabled) return;
-		item.onSelect();
+		if (item.submenu && item.submenu.length) {
+			// Submenu owner: open (or toggle) instead of firing onSelect/close.
+			const el = event.currentTarget as HTMLElement;
+			if (submenuIndex === index) {
+				closeSubmenu();
+			} else {
+				openSubmenuAt(el, index);
+			}
+			return;
+		}
+		if (item.submit) {
+			submitAction(item.submit);
+		}
+		item.onSelect?.();
 		close();
 	}
 
+	function handleItemPointerEnter(item: ActionItem, index: number, event: PointerEvent) {
+		if (item.disabled || !item.submenu?.length) return;
+		const el = event.currentTarget as HTMLElement;
+		openSubmenuAt(el, index);
+	}
+
+	function submitAction(cfg: SubmitConfig) {
+		if (typeof document === 'undefined') return;
+		const form = document.createElement('form');
+		form.method = cfg.method ?? 'POST';
+		if (cfg.action) form.action = cfg.action;
+		form.enctype = cfg.enctype ?? 'application/x-www-form-urlencoded';
+		form.style.display = 'none';
+		if (cfg.body) {
+			for (const [k, v] of Object.entries(cfg.body)) {
+				const input = document.createElement('input');
+				input.type = 'hidden';
+				input.name = k;
+				input.value = String(v);
+				form.appendChild(input);
+			}
+		}
+		document.body.appendChild(form);
+		form.requestSubmit();
+		// Leave form in DOM briefly so use:enhance handlers can attach; a
+		// microtask cleanup is enough because submission is synchronous.
+		queueMicrotask(() => form.remove());
+	}
+
 	// Virtual anchor tracks the cursor position; rebuilt whenever x or y change.
 	let anchor = $derived(makeVirtualAnchor(x, y));
+	let submenuAnchor = $derived(makeVirtualAnchor(submenuX, submenuY));
 
 	let menuEl = $state<HTMLDivElement | null>(null);
 
 	function menuItemButtons(): HTMLButtonElement[] {
 		if (!menuEl) return [];
-		return Array.from(menuEl.querySelectorAll('button[role="menuitem"]:not(:disabled)'));
+		// Only DIRECT children — don't include nested submenu items when nav-ing
+		// this level.
+		return Array.from(
+			menuEl.querySelectorAll(':scope > button[role="menuitem"]:not(:disabled)')
+		);
+	}
+
+	function focusedItemIndex(): number {
+		if (!menuEl) return -1;
+		const activeBtn = document.activeElement as HTMLElement | null;
+		if (!activeBtn) return -1;
+		const buttons = Array.from(
+			menuEl.querySelectorAll(':scope > button[role="menuitem"]')
+		) as HTMLButtonElement[];
+		return buttons.indexOf(activeBtn as HTMLButtonElement);
 	}
 
 	function handleKeydown(e: KeyboardEvent) {
 		if (e.key === 'Escape') {
+			// If a submenu is open, close only the submenu on Escape; otherwise
+			// dismiss the whole menu.
+			if (submenuIndex !== null) {
+				e.stopPropagation();
+				const activeIdx = submenuIndex;
+				closeSubmenu();
+				// Return focus to the parent item that owned the submenu.
+				const buttons = menuItemButtons();
+				buttons[activeIdx]?.focus();
+				return;
+			}
 			close();
 			return;
 		}
+		if (e.key === 'ArrowRight') {
+			const idx = focusedItemIndex();
+			if (idx < 0) return;
+			const item = items[idx];
+			if (item && !('divider' in item) && item.submenu?.length && !item.disabled) {
+				e.preventDefault();
+				e.stopPropagation();
+				const buttons = menuItemButtons();
+				openSubmenuAt(buttons[idx], idx);
+			}
+			return;
+		}
+		if (e.key === 'ArrowLeft') {
+			// Only meaningful when this instance is itself a submenu — the
+			// parent listens for the resulting close event via onClose.
+			if (submenuIndex !== null) {
+				e.preventDefault();
+				e.stopPropagation();
+				closeSubmenu();
+			}
+			return;
+		}
 		if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) return;
 		const buttons = menuItemButtons();
 		if (!buttons.length) return;
@@ -125,12 +228,17 @@
 			const el = menuEl;
 			requestAnimationFrame(() => {
 				const buttons = Array.from(
-					el.querySelectorAll('button[role="menuitem"]:not(:disabled)')
+					el.querySelectorAll(':scope > button[role="menuitem"]:not(:disabled)')
 				) as HTMLButtonElement[];
 				buttons[0]?.focus();
 			});
 		}
 	});
+
+	// Close any open submenu when the parent menu closes.
+	$effect(() => {
+		if (!open && submenuIndex !== null) submenuIndex = null;
+	});
 </script>
 
 {#if open}
@@ -151,23 +259,56 @@
 			</p>
 		{/if}
 
-		{#each items as item}
+		{#each items as item, i}
 			{#if 'divider' in item}
 				<div class="border-t border-base-300 my-1"></div>
 			{:else}
 				<button
 					type="button"
 					role="menuitem"
+					aria-haspopup={item.submenu?.length ? 'menu' : undefined}
+					aria-expanded={item.submenu?.length ? submenuIndex === i : undefined}
+					aria-label={item.content ? item.label : undefined}
 					class="w-full flex items-center gap-2 text-left px-3 py-1.5 text-sm transition-colors
 						{item.variant === 'danger' ? 'text-error hover:bg-error/10' : 'hover:bg-base-200'}
 						{item.disabled ? 'opacity-50 cursor-not-allowed' : ''}"
 					disabled={item.disabled}
-					onclick={() => handleSelect(item)}
+					onclick={(e) => handleItemClick(item, i, e)}
+					onpointerenter={(e) => handleItemPointerEnter(item, i, e)}
+					onfocus={(e) => {
+						if (item.submenu?.length && !item.disabled) {
+							openSubmenuAt(e.currentTarget as HTMLElement, i);
+						}
+					}}
 				>
-					{#if item.icon}<span class="shrink-0">{item.icon}</span>{/if}
-					<span class="truncate">{item.label}</span>
+					{#if item.content}
+						{@render item.content()}
+					{:else}
+						{#if item.icon}<span class="shrink-0">{item.icon}</span>{/if}
+						<span class="truncate flex-1">{item.label}</span>
+						{#if item.submenu?.length}
+							<span class="text-base-content/50 shrink-0" aria-hidden="true">▸</span>
+						{/if}
+					{/if}
 				</button>
 			{/if}
 		{/each}
+
+		{#if submenuIndex !== null && items[submenuIndex] && !('divider' in items[submenuIndex]) && items[submenuIndex].submenu}
+			<!--
+				Nested INSIDE menuEl so the parent's click-outside detection
+				(`node.contains(e.target)`) treats submenu clicks as "inside".
+				Visually the submenu still renders at its own floating position
+				because it uses `position: fixed` via use:floating.
+			-->
+			<SelfContextMenu
+				open={true}
+				x={submenuX}
+				y={submenuY}
+				items={items[submenuIndex].submenu ?? []}
+				zIndex={zIndex + 1}
+				onClose={closeSubmenu}
+			/>
+		{/if}
 	</div>
 {/if}

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

@@ -1,15 +1,4 @@
-type ActionItem = {
-    label: string;
-    /** Optional leading icon — a single emoji/glyph, rendered before the label. */
-    icon?: string;
-    onSelect: () => void;
-    variant?: 'default' | 'danger';
-    disabled?: boolean;
-};
-type DividerItem = {
-    divider: true;
-};
-export type ContextMenuItem = ActionItem | DividerItem;
+import type { ContextMenuItem } from './ContextMenu.types.js';
 interface Props {
     /** Whether the menu is currently shown. Bindable. */
     open: boolean;

package/dist/components/ContextMenu.types.d.ts

@@ -0,0 +1,62 @@
+import type { Snippet } from 'svelte';
+/**
+ * Shared types for ContextMenu. Extracted from the .svelte file so
+ * svelte-package's .d.ts generation doesn't stumble on the recursive
+ * ContextMenuItem → ActionItem.submenu → ContextMenuItem[] shape (which
+ * caused "Exported variable 'ContextMenu' has or is using private name
+ * 'ActionItem'" during package build).
+ */
+/**
+ * `submit` — post to a SvelteKit form action when the item is clicked.
+ * Renders a hidden `<form method="POST">` with the action + body, then
+ * `requestSubmit()`s it. Use this when the row action should ride the
+ * standard `use:enhance` pipeline (toasts, invalidation, redirects) with
+ * no extra plumbing per row.
+ */
+export type SubmitConfig = {
+    /** SvelteKit action, e.g. "?/delete". Default: current URL. */
+    action?: string;
+    /** HTTP method. Default 'POST'. */
+    method?: 'POST' | 'GET';
+    /** Form fields to send as hidden inputs. */
+    body?: Record<string, string | number | boolean>;
+    /** Enctype. Default 'application/x-www-form-urlencoded'. */
+    enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data';
+};
+export type ActionItem = {
+    label: string;
+    /** Optional leading icon — a single emoji/glyph, rendered before the label. */
+    icon?: string;
+    /** Called when the item is clicked. Optional when `submit` or `submenu` is provided. */
+    onSelect?: () => void;
+    /** If set, clicking the item submits a form built from this config. */
+    submit?: SubmitConfig;
+    /**
+     * Nested submenu items. When present, the item shows a chevron and does
+     * NOT fire `onSelect` on click — hovering, focusing, ArrowRight or Enter
+     * opens the submenu to the right of the parent item (flipping left on
+     * viewport overflow). ArrowLeft or Escape closes just the submenu. Submenus
+     * nest arbitrarily deep.
+     */
+    submenu?: ContextMenuItem[];
+    /**
+     * Custom content rendered in place of the default icon+label row. When
+     * provided, `icon` and `label` are ignored for display but `label`
+     * should still be set for accessibility (used as the button's
+     * aria-label). Use this for inline widgets — segmented toggles, small
+     * inputs, chips — that live inside a menu row without needing a
+     * bespoke shell around the whole menu.
+     *
+     * The wrapping `<button role="menuitem">` still receives clicks (and
+     * closes the menu by default), so any interactive widget in the
+     * snippet that should NOT close the menu must call
+     * `event.stopPropagation()` on its own click handler.
+     */
+    content?: Snippet;
+    variant?: 'default' | 'danger';
+    disabled?: boolean;
+};
+export type DividerItem = {
+    divider: true;
+};
+export type ContextMenuItem = ActionItem | DividerItem;

package/dist/components/ContextMenu.types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/DirtyFormHost.svelte

@@ -0,0 +1,110 @@
+<script lang="ts" generics="T">
+	/**
+	 * DirtyFormHost — declarative wrapper around createDirtyGuard.
+	 *
+	 * Renders your form body plus (optionally) a floating "Unsaved changes"
+	 * pill + Cancel button. Composable API: pass `baseline`, `current`, and
+	 * `onCancel` via props; the host wires beforeunload + (optional) SvelteKit
+	 * beforeNavigate. Consumers who want a bespoke pill/Cancel treatment
+	 * should skip this component and call `createDirtyGuard` directly.
+	 *
+	 * Usage:
+	 *   // in a Svelte component:
+	 *   //   import { beforeNavigate } from '$app/navigation';
+	 *
+	 *   <DirtyFormHost {baseline} current={draft} onCancel={() => draft = { ...baseline }} {beforeNavigate}>
+	 *     {#snippet children({ dirty, cancel })}
+	 *       <form>...form body...</form>
+	 *     {/snippet}
+	 *   </DirtyFormHost>
+	 */
+
+	import { createDirtyGuard, type BeforeNavigateFn } from '../utils/dirtyGuard';
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** Saved (baseline) form value. */
+		baseline: T;
+		/** Current (draft) form value. */
+		current: T;
+		/** Snap back to baseline. */
+		onCancel?: () => void;
+		/** SvelteKit `beforeNavigate` — pass through from `$app/navigation`. */
+		beforeNavigate?: BeforeNavigateFn;
+		/** Discard-prompt string. Default "Discard unsaved changes?" */
+		discardPrompt?: string;
+		/** Custom equality. Default JSON.stringify. */
+		equals?: (a: T, b: T) => boolean;
+		/** Hide the default pill + Cancel chrome and let the snippet render its own. */
+		hideChrome?: boolean;
+		/** Form body. Receives the guard controller as its first arg. */
+		children: Snippet<[{ dirty: boolean; cancel: () => void }]>;
+	}
+
+	let {
+		baseline,
+		current,
+		onCancel,
+		beforeNavigate,
+		discardPrompt,
+		equals,
+		hideChrome = false,
+		children,
+	}: Props = $props();
+
+	const guard = createDirtyGuard<T>({
+		baseline: () => baseline,
+		current: () => current,
+		onCancel,
+		equals,
+		beforeNavigate,
+		discardPrompt,
+	});
+</script>
+
+{@render children({ get dirty() { return guard.dirty; }, cancel: guard.cancel })}
+
+{#if !hideChrome && guard.dirty}
+	<div class="jatui-dirty-chrome" role="status" aria-live="polite">
+		<span class="jatui-dirty-pill">Unsaved changes</span>
+		<button type="button" class="jatui-dirty-cancel" onclick={guard.cancel}>
+			Cancel
+		</button>
+	</div>
+{/if}
+
+<style>
+	.jatui-dirty-chrome {
+		position: fixed;
+		bottom: 1rem;
+		right: 1rem;
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		padding: 0.375rem 0.5rem 0.375rem 0.75rem;
+		background: color-mix(in oklch, var(--color-base-100) 96%, transparent);
+		border: 1px solid var(--color-warning);
+		border-radius: 999px;
+		box-shadow: 0 8px 24px oklch(0 0 0 / 0.28);
+		z-index: 60;
+		font-size: 0.8125rem;
+	}
+	.jatui-dirty-pill {
+		color: var(--color-warning);
+		font-weight: 600;
+	}
+	.jatui-dirty-cancel {
+		padding: 0.1875rem 0.5625rem;
+		font-size: 0.75rem;
+		font-weight: 500;
+		background: transparent;
+		border: 1px solid var(--color-base-300);
+		border-radius: 999px;
+		color: var(--color-base-content);
+		cursor: pointer;
+		transition: background 0.15s;
+	}
+	.jatui-dirty-cancel:hover {
+		background: var(--color-base-200);
+	}
+</style>