@joewinke/jatui 0.2.8 → 0.2.10

package/CLAUDE.md

@@ -65,6 +65,8 @@ Then import:
 | `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?` |
+| `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?` |
 
 ### Media
 

package/dist/components/ContextMenu.svelte

@@ -21,18 +21,25 @@
 	 *     y={cm.y}
 	 *     header={cm.target?.name}
 	 *     items={[
-	 *       { label: "Preview",    onSelect: () => preview(cm.target) },
+	 *       { label: "Preview",    icon: "👁️", onSelect: () => preview(cm.target) },
 	 *       { label: "Copy URL",   onSelect: () => copy(cm.target) },
 	 *       { divider: true },
 	 *       { label: "Delete", variant: "danger", onSelect: () => del(cm.target) },
 	 *     ]}
 	 *   />
+	 *
+	 * 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.
 	 */
 
 	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;
@@ -84,16 +91,57 @@
 
 	// Virtual anchor tracks the cursor position; rebuilt whenever x or y change.
 	let anchor = $derived(makeVirtualAnchor(x, y));
+
+	let menuEl = $state<HTMLDivElement | null>(null);
+
+	function menuItemButtons(): HTMLButtonElement[] {
+		if (!menuEl) return [];
+		return Array.from(menuEl.querySelectorAll('button[role="menuitem"]:not(:disabled)'));
+	}
+
+	function handleKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape') {
+			close();
+			return;
+		}
+		if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) return;
+		const buttons = menuItemButtons();
+		if (!buttons.length) return;
+		e.preventDefault();
+		const current = buttons.indexOf(document.activeElement as HTMLButtonElement);
+		let next: HTMLButtonElement;
+		if (e.key === 'ArrowDown') next = buttons[(current + 1 + buttons.length) % buttons.length];
+		else if (e.key === 'ArrowUp') next = buttons[(current - 1 + buttons.length) % buttons.length];
+		else if (e.key === 'Home') next = buttons[0];
+		else next = buttons[buttons.length - 1];
+		next.focus();
+	}
+
+	// Move focus into the menu (first item) whenever it opens — the floating
+	// action's returnFocusTarget already captured the pre-open activeElement
+	// by the time this effect runs, so focus-return-on-close still works.
+	$effect(() => {
+		if (open && menuEl) {
+			const el = menuEl;
+			requestAnimationFrame(() => {
+				const buttons = Array.from(
+					el.querySelectorAll('button[role="menuitem"]:not(:disabled)')
+				) as HTMLButtonElement[];
+				buttons[0]?.focus();
+			});
+		}
+	});
 </script>
 
 {#if open}
 	<div
+		bind:this={menuEl}
 		role="menu"
 		tabindex="-1"
 		class="min-w-[200px] bg-base-200 border border-base-300 rounded-md py-1 {className}"
 		style="z-index: {zIndex};"
 		use:floating={{ anchor, placement: 'bottom-start', flip: true, shift: true, offset: 2, onDismiss: close }}
-		onkeydown={(e) => e.key === 'Escape' && close()}
+		onkeydown={handleKeydown}
 	>
 		{#if header}
 			<p
@@ -110,13 +158,14 @@
 				<button
 					type="button"
 					role="menuitem"
-					class="w-full text-left px-3 py-1.5 text-sm transition-colors
+					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)}
 				>
-					{item.label}
+					{#if item.icon}<span class="shrink-0">{item.icon}</span>{/if}
+					<span class="truncate">{item.label}</span>
 				</button>
 			{/if}
 		{/each}

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

@@ -1,5 +1,7 @@
 type ActionItem = {
     label: string;
+    /** Optional leading icon — a single emoji/glyph, rendered before the label. */
+    icon?: string;
     onSelect: () => void;
     variant?: 'default' | 'danger';
     disabled?: boolean;

package/dist/components/ContextMenuTrigger.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+	/**
+	 * ContextMenuTrigger — wraps content with the standard right-click +
+	 * "⋯" touch-affordance pattern, backed by ContextMenu.
+	 *
+	 * Right-click anywhere in the wrapped area opens the menu at the cursor.
+	 * A small "⋯" button (visible on hover/focus for mouse, always visible on
+	 * coarse/touch pointers) opens the same menu anchored to itself, so the
+	 * action is reachable without a right-click gesture.
+	 *
+	 * Usage:
+	 *   <ContextMenuTrigger
+	 *     items={[
+	 *       { label: "Duplicate", icon: "📄", onSelect: () => duplicate(page) },
+	 *       { divider: true },
+	 *       { label: "Delete", variant: "danger", onSelect: () => del(page) },
+	 *     ]}
+	 *   >
+	 *     <PageCard {page} />
+	 *   </ContextMenuTrigger>
+	 */
+
+	import type { Snippet } from 'svelte';
+	import ContextMenu from './ContextMenu.svelte';
+	import type { ContextMenuItem } from './ContextMenu.svelte';
+
+	interface Props {
+		/** Ordered list of items and dividers to render in the menu. */
+		items: ContextMenuItem[];
+		/** Optional small italic label rendered above the items. */
+		header?: string;
+		/** Wrapped content. */
+		children: Snippet;
+		/** aria-label for the "⋯" touch-trigger button. Default "More actions". */
+		triggerLabel?: string;
+		/** Hide the "⋯" button — e.g. right-click-only contexts. Default false. */
+		hideButton?: boolean;
+		/** Stacking context z-index, forwarded to ContextMenu. Default 70. */
+		zIndex?: number;
+		/** Additional CSS class for the wrapper element. */
+		class?: string;
+	}
+
+	let {
+		items,
+		header,
+		children,
+		triggerLabel = 'More actions',
+		hideButton = false,
+		zIndex = 70,
+		class: className = ''
+	}: Props = $props();
+
+	let cm = $state({ open: false, x: 0, y: 0 });
+
+	function openAt(x: number, y: number) {
+		cm = { open: true, x, y };
+	}
+
+	function handleContextMenu(e: MouseEvent) {
+		e.preventDefault();
+		openAt(e.clientX, e.clientY);
+	}
+
+	function handleTriggerClick(e: MouseEvent) {
+		const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+		openAt(rect.left, rect.bottom);
+	}
+</script>
+
+<div class="group relative {className}" role="group" oncontextmenu={handleContextMenu}>
+	{@render children()}
+	{#if !hideButton}
+		<button
+			type="button"
+			class="btn btn-xs btn-circle bg-base-100/85 backdrop-blur-sm shadow-sm absolute top-1 right-1 z-10 opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100"
+			aria-label={triggerLabel}
+			onclick={handleTriggerClick}
+		>
+			⋯
+		</button>
+	{/if}
+</div>
+
+<ContextMenu bind:open={cm.open} x={cm.x} y={cm.y} {items} {header} {zIndex} />

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

@@ -0,0 +1,41 @@
+/**
+     * ContextMenuTrigger — wraps content with the standard right-click +
+     * "⋯" touch-affordance pattern, backed by ContextMenu.
+     *
+     * Right-click anywhere in the wrapped area opens the menu at the cursor.
+     * A small "⋯" button (visible on hover/focus for mouse, always visible on
+     * coarse/touch pointers) opens the same menu anchored to itself, so the
+     * action is reachable without a right-click gesture.
+     *
+     * Usage:
+     *   <ContextMenuTrigger
+     *     items={[
+     *       { label: "Duplicate", icon: "📄", onSelect: () => duplicate(page) },
+     *       { divider: true },
+     *       { label: "Delete", variant: "danger", onSelect: () => del(page) },
+     *     ]}
+     *   >
+     *     <PageCard {page} />
+     *   </ContextMenuTrigger>
+     */
+import type { Snippet } from 'svelte';
+import type { ContextMenuItem } from './ContextMenu.svelte';
+interface Props {
+    /** Ordered list of items and dividers to render in the menu. */
+    items: ContextMenuItem[];
+    /** Optional small italic label rendered above the items. */
+    header?: string;
+    /** Wrapped content. */
+    children: Snippet;
+    /** aria-label for the "⋯" touch-trigger button. Default "More actions". */
+    triggerLabel?: string;
+    /** Hide the "⋯" button — e.g. right-click-only contexts. Default false. */
+    hideButton?: boolean;
+    /** Stacking context z-index, forwarded to ContextMenu. Default 70. */
+    zIndex?: number;
+    /** Additional CSS class for the wrapper element. */
+    class?: string;
+}
+declare const ContextMenuTrigger: import("svelte").Component<Props, {}, "">;
+type ContextMenuTrigger = ReturnType<typeof ContextMenuTrigger>;
+export default ContextMenuTrigger;

package/dist/dnd/createDndBoard.js

@@ -45,17 +45,29 @@ export function createDndBoard(opts) {
 		}
 	}
 
-	$.user_effect(function () {
-		opts.items();
-
-		if ($.safe_get(dragging) || inFlight > 0) {
-			seedQueued = true;
-
-			return;
-		}
+	// Seed synchronously at creation so the render mirror is populated for the very
+	// first render — SSR (where effects never run) and a client mount where items
+	// are already present. Without this the grid renders empty until an effect
+	// fires.
+	seed();
+
+	// Reactive re-seed on items() change — CLIENT ONLY. createDndBoard ships as a
+	// client build (svelte/internal/client); creating this effect during SSR calls
+	// user_effect with no active reaction → effect_orphan (a 500 on any page that
+	// server-renders a board). The synchronous seed above covers the SSR render.
+	if (typeof window !== 'undefined') {
+		$.user_effect(function () {
+			opts.items();
+
+			if ($.safe_get(dragging) || inFlight > 0) {
+				seedQueued = true;
+
+				return;
+			}
 
-		seed();
-	});
+			seed();
+		});
+	}
 
 	function placementFrom(dropTargets) {
 		var _a;
@@ -219,7 +231,9 @@ export function createDndBoard(opts) {
 		});
 	}
 
-	$.user_effect(function () {
+	// Drag monitor — CLIENT ONLY (same effect_orphan reason as the seed effect;
+	// monitorForElements also needs the DOM, which does not exist during SSR).
+	if (typeof window !== 'undefined') $.user_effect(function () {
 		return monitorForElements({
 			canMonitor(_a) {
 				var source = _a.source;

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export type { InputOptions } from './stores/inputDialog';
 export { default as SearchDropdown } from './components/SearchDropdown.svelte';
 export { default as FilterDropdown } from './components/FilterDropdown.svelte';
 export { default as ContextMenu } from './components/ContextMenu.svelte';
+export { default as ContextMenuTrigger } from './components/ContextMenuTrigger.svelte';
 export { default as ChipInput } from './components/ChipInput.svelte';
 export { default as ResizableDivider } from './components/ResizableDivider.svelte';
 export { default as DateRangePicker } from './components/DateRangePicker.svelte';

package/dist/index.js

@@ -20,6 +20,7 @@ export { showInput, submitInput, cancelInput, getPendingInput } from './stores/i
 export { default as SearchDropdown } from './components/SearchDropdown.svelte';
 export { default as FilterDropdown } from './components/FilterDropdown.svelte';
 export { default as ContextMenu } from './components/ContextMenu.svelte';
+export { default as ContextMenuTrigger } from './components/ContextMenuTrigger.svelte';
 export { default as ChipInput } from './components/ChipInput.svelte';
 export { default as ResizableDivider } from './components/ResizableDivider.svelte';
 export { default as DateRangePicker } from './components/DateRangePicker.svelte';

package/package.json

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