@joewinke/jatui 0.3.0 → 0.3.1

package/CLAUDE.md

@@ -58,14 +58,14 @@ 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). 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. | `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}`) |

package/dist/components/ContextMenu.svelte

@@ -31,42 +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';
-
-	/**
-	 * `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';
-	};
-
-	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` is provided. */
-		onSelect?: () => void;
-		/** If set, clicking the item submits a form built from this config. */
-		submit?: SubmitConfig;
-		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. */
@@ -98,14 +71,43 @@
 		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;
+		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);
 		}
@@ -113,6 +115,12 @@
 		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');
@@ -138,19 +146,67 @@
 
 	// 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;
@@ -172,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}
@@ -198,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,35 +1,4 @@
-/**
- * `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';
-};
-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` is provided. */
-    onSelect?: () => void;
-    /** If set, clicking the item submits a form built from this config. */
-    submit?: SubmitConfig;
-    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/Modal.svelte

@@ -23,7 +23,13 @@
 		contentClass?: string;
 		ariaLabel?: string;
 		dismissible?: boolean;
-		zIndex?: number;
+		/**
+		 * Stacking z-index. Accepts a numeric literal (`9040`) or any CSS
+		 * `z-index` string, including CSS custom properties
+		 * (`"var(--z-lightbox)"`). Strings are used as-is; numbers are
+		 * coerced to strings. Default `1000`.
+		 */
+		zIndex?: string | number;
 		/**
 		 * When true (default), keydown events fired inside the modal are stopped
 		 * from propagating to window — preventing page-level list/keyboard
@@ -183,7 +189,7 @@
 	<dialog
 		bind:this={modalElement}
 		class={modalClass}
-		style="z-index: {zIndex}"
+		style="z-index: {typeof zIndex === 'number' ? String(zIndex) : zIndex}"
 		aria-modal="true"
 		aria-label={ariaLabel || title}
 		open

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

@@ -11,7 +11,13 @@ interface Props {
     contentClass?: string;
     ariaLabel?: string;
     dismissible?: boolean;
-    zIndex?: number;
+    /**
+     * Stacking z-index. Accepts a numeric literal (`9040`) or any CSS
+     * `z-index` string, including CSS custom properties
+     * (`"var(--z-lightbox)"`). Strings are used as-is; numbers are
+     * coerced to strings. Default `1000`.
+     */
+    zIndex?: string | number;
     /**
      * When true (default), keydown events fired inside the modal are stopped
      * from propagating to window — preventing page-level list/keyboard

package/dist/index.d.ts

@@ -98,7 +98,7 @@ export type { ShortenedLink } from './components/LinkShortener.svelte';
 export type { SearchDropdownOption, SearchDropdownGroup } from './components/SearchDropdown.svelte';
 export type { ChipSuggestion, SuggestionGroup, ChipInfo } from './components/ChipInput.svelte';
 export type { SortOption } from './components/SortDropdown.svelte';
-export type { ContextMenuItem, SubmitConfig as ContextMenuSubmitConfig } from './components/ContextMenu.svelte';
+export type { ContextMenuItem, ActionItem as ContextMenuActionItem, DividerItem as ContextMenuDividerItem, SubmitConfig as ContextMenuSubmitConfig } from './components/ContextMenu.types.js';
 export type { DisplaySegment } from './components/InlineEdit.svelte';
 export type { ActionButton, ActionDropdown, DropdownItem } from './components/FloatingActionBar.svelte';
 export type { SelectOption } from './components/SelectInput.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",