@joewinke/jatui 0.3.1 → 0.5.0

package/CLAUDE.md

@@ -65,11 +65,12 @@ 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). 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?` |
+| `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 — submenus open on parent-item focus **without stealing focus into the submenu**; ArrowRight is the explicit "enter the submenu" gesture) **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()`). `autoFocus` (default true) can be set false to suppress auto-focus of the first item on open. | `open` (bindable), `x`, `y`, `items: ContextMenuItem[]`, `header?`, `zIndex?`, `autoFocus?`, `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) |
+| `PresenceStack` | "Who's here" avatar stack for live-collaboration UI — max `maxVisible` avatars + "+N more" overflow bubble, tooltip per avatar ("X is editing FIELD" / "X is viewing"). Purely presentational — feed it viewers from any presence source (e.g. an SSE-backed presence composable). | `viewers: PresenceViewer[]`, `maxVisible?` (default 5), `size?`, `class?` |
 | `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?` |
+| `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`; a flat `actions[]` with `{label, onSelect, destructive?}`; and now `groups[]` for dropdown-menu actions (each group is one button on the bar that opens a menu of `{label, onSelect}` items — same shape as `BulkAction`). Flat + grouped can be mixed. Reach for `FloatingActionBar` directly only when you need finer per-item dropdown styling (dot colors, icon snippets). | `selection: Set \| Array \| number`, `actions?: BulkAction[]`, `groups?: BulkActionGroup[]`, `onClear?`, `loading?`, `countLabel?` |
 
 ### Media
 
@@ -297,6 +298,10 @@ import type {
 // ImageVariantSpec    — { name, width, height, fit?, background? }
 // VariantResult       — { name, url, width, height, backgroundRemovalFailed? }
 // VariantState        — union: idle | loading | done (VariantResult) | error (message)
+
+// PresenceStack types
+import type { PresenceViewer } from "jatui"
+// PresenceViewer — { user_id, name, avatar_url?, typing_scope? }
 ```
 
 ## Live Demos

package/dist/components/BulkActionBar.svelte

@@ -5,10 +5,16 @@
 	 * 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.
+	 * Under the hood a thin wrapper over `FloatingActionBar`.
 	 *
-	 * Usage:
+	 * For actions that group naturally under a common menu (e.g. "Move to
+	 * Stage" with 5 stage options), pass `groups[]` alongside `actions[]`.
+	 * Each group renders as a single button that opens a dropdown of its
+	 * `actions` — same `{ label, onSelect, destructive?, variant?, icon? }`
+	 * shape as flat actions. Flat + grouped can be mixed; flat actions
+	 * render first, then grouped dropdowns.
+	 *
+	 * Usage — flat only:
 	 *
 	 *     const nav = listNav({ selectable: true });
 	 *
@@ -22,10 +28,22 @@
 	 *       ]}
 	 *       onClear={() => nav.clearSelection()}
 	 *     />
+	 *
+	 * Usage — grouped:
+	 *
+	 *     <BulkActionBar
+	 *       selection={nav.selection}
+	 *       actions={[{ label: 'Delete', onSelect: del, destructive: true }]}
+	 *       groups={[
+	 *         { label: 'Stage', actions: STAGES.map((s) => ({
+	 *             label: s.name, onSelect: () => moveTo(s.id),
+	 *         })) },
+	 *       ]}
+	 *     />
 	 */
 
 	import FloatingActionBar from './FloatingActionBar.svelte';
-	import type { ActionButton } from './FloatingActionBar.svelte';
+	import type { ActionButton, ActionDropdown } from './FloatingActionBar.svelte';
 
 	export interface BulkAction {
 		label: string;
@@ -41,11 +59,28 @@
 		id?: string;
 	}
 
+	export interface BulkActionGroup {
+		/** Button label — clicking opens the dropdown. */
+		label: string;
+		/** Optional SVG path string for a 24×24 icon on the group button. */
+		icon?: string;
+		/** Actions rendered inside the dropdown. `destructive` on a nested action
+		 * currently only affects semantics for readers — the dropdown item row
+		 * is styled uniformly. */
+		actions: BulkAction[];
+		/** Dropdown-button variant. Default 'default'. */
+		variant?: ActionDropdown['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[];
+		/** Flat actions rendered as top-level buttons. */
+		actions?: BulkAction[];
+		/** Grouped actions rendered as dropdown buttons. */
+		groups?: BulkActionGroup[];
 		/** Called when the user clicks the built-in Clear button. */
 		onClear?: () => void;
 		/** Loading state — disables all actions and shows a spinner. */
@@ -54,7 +89,14 @@
 		countLabel?: string;
 	}
 
-	let { selection, actions, onClear, loading = false, countLabel = 'selected' }: Props = $props();
+	let {
+		selection,
+		actions = [],
+		groups = [],
+		onClear,
+		loading = false,
+		countLabel = 'selected',
+	}: Props = $props();
 
 	const count = $derived(
 		typeof selection === 'number'
@@ -73,6 +115,26 @@
 			onclick: a.onSelect,
 		})),
 	);
+
+	const mappedDropdowns = $derived<ActionDropdown[]>(
+		groups.map((g) => ({
+			id: g.id ?? g.label,
+			label: g.label,
+			icon: g.icon,
+			variant: g.variant ?? 'default',
+			items: g.actions.map((a) => ({
+				label: a.label,
+				onclick: a.onSelect,
+			})),
+		})),
+	);
 </script>
 
-<FloatingActionBar {count} actions={mapped} {loading} {onClear} {countLabel} />
+<FloatingActionBar
+	{count}
+	actions={mapped}
+	dropdowns={mappedDropdowns}
+	{loading}
+	{onClear}
+	{countLabel}
+/>

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

@@ -1,4 +1,4 @@
-import type { ActionButton } from './FloatingActionBar.svelte';
+import type { ActionButton, ActionDropdown } from './FloatingActionBar.svelte';
 export interface BulkAction {
     label: string;
     /** Optional SVG path string for a 24×24 icon. */
@@ -12,11 +12,27 @@ export interface BulkAction {
     /** Unique key (defaults to label). */
     id?: string;
 }
+export interface BulkActionGroup {
+    /** Button label — clicking opens the dropdown. */
+    label: string;
+    /** Optional SVG path string for a 24×24 icon on the group button. */
+    icon?: string;
+    /** Actions rendered inside the dropdown. `destructive` on a nested action
+     * currently only affects semantics for readers — the dropdown item row
+     * is styled uniformly. */
+    actions: BulkAction[];
+    /** Dropdown-button variant. Default 'default'. */
+    variant?: ActionDropdown['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[];
+    /** Flat actions rendered as top-level buttons. */
+    actions?: BulkAction[];
+    /** Grouped actions rendered as dropdown buttons. */
+    groups?: BulkActionGroup[];
     /** Called when the user clicks the built-in Clear button. */
     onClear?: () => void;
     /** Loading state — disables all actions and shows a spinner. */

package/dist/components/ContextMenu.svelte

@@ -58,6 +58,14 @@
 		class?: string;
 		/** Called after the menu closes, regardless of cause. */
 		onClose?: () => void;
+		/**
+		 * Move focus to the first item on open. Default `true` for top-level
+		 * menus; the component sets this to `false` when it recursively renders
+		 * itself as a nested submenu so that arrow-navigating over a parent item
+		 * with a submenu doesn't yank keyboard focus out of the parent row.
+		 * ArrowRight from the parent explicitly focuses into the submenu.
+		 */
+		autoFocus?: boolean;
 	}
 
 	let {
@@ -68,7 +76,8 @@
 		header,
 		zIndex = 70,
 		class: className = '',
-		onClose
+		onClose,
+		autoFocus = true
 	}: Props = $props();
 
 	// Submenu state — index into `items` of the currently-open submenu (if any),
@@ -194,6 +203,16 @@
 				e.stopPropagation();
 				const buttons = menuItemButtons();
 				openSubmenuAt(buttons[idx], idx);
+				// ArrowRight is an explicit "enter the submenu" gesture — focus
+				// its first item. Hover/onfocus open the submenu without moving
+				// focus (see autoFocus prop on the recursive instance).
+				const el = menuEl;
+				requestAnimationFrame(() => {
+					const first = el?.querySelector(
+						':scope > [role="menu"] > button[role="menuitem"]:not(:disabled)'
+					) as HTMLButtonElement | null;
+					first?.focus();
+				});
 			}
 			return;
 		}
@@ -224,7 +243,7 @@
 	// 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) {
+		if (open && menuEl && autoFocus) {
 			const el = menuEl;
 			requestAnimationFrame(() => {
 				const buttons = Array.from(
@@ -307,6 +326,7 @@
 				y={submenuY}
 				items={items[submenuIndex].submenu ?? []}
 				zIndex={zIndex + 1}
+				autoFocus={false}
 				onClose={closeSubmenu}
 			/>
 		{/if}

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

@@ -16,6 +16,14 @@ interface Props {
     class?: string;
     /** Called after the menu closes, regardless of cause. */
     onClose?: () => void;
+    /**
+     * Move focus to the first item on open. Default `true` for top-level
+     * menus; the component sets this to `false` when it recursively renders
+     * itself as a nested submenu so that arrow-navigating over a parent item
+     * with a submenu doesn't yank keyboard focus out of the parent row.
+     * ArrowRight from the parent explicitly focuses into the submenu.
+     */
+    autoFocus?: boolean;
 }
 declare const ContextMenu: import("svelte").Component<Props, {}, "open">;
 type ContextMenu = ReturnType<typeof ContextMenu>;

package/dist/components/PresenceStack.svelte

@@ -0,0 +1,64 @@
+<!--
+  PresenceStack — "who's here" avatar stack for live-collaboration UI
+  (mos-hwduf.4.4). Purely presentational: feed it a PresenceViewer[] from
+  any presence source (e.g. a host app's SSE-backed presence composable).
+
+  Shows up to maxVisible avatars in input order with a "+N more" overflow
+  bubble. Each avatar carries a tooltip: "{name} is editing {typing_scope}"
+  when typing_scope is set, else "{name} is viewing".
+-->
+<script lang="ts">
+	import type { PresenceViewer } from '../types/presence';
+	import Avatar from './messaging/Avatar.svelte';
+	import Tooltip from './Tooltip.svelte';
+
+	interface Props {
+		viewers: PresenceViewer[];
+		maxVisible?: number;
+		size?: 'xs' | 'small' | 'medium' | 'large';
+		class?: string;
+	}
+
+	let { viewers = [], maxVisible = 5, size = 'small', class: className = '' }: Props = $props();
+
+	const visible = $derived(viewers.slice(0, maxVisible));
+	const overflow = $derived(viewers.slice(maxVisible));
+
+	function tipFor(viewer: PresenceViewer): string {
+		const who = viewer.name ?? 'Someone';
+		return viewer.typing_scope ? `${who} is editing ${viewer.typing_scope}` : `${who} is viewing`;
+	}
+
+	const overflowTip = $derived(overflow.map((v) => v.name ?? 'Someone').join(', '));
+
+	const overflowSizeClasses: Record<string, string> = {
+		xs: 'w-5 h-5 text-[8px]',
+		small: 'w-8 h-8 text-xs',
+		medium: 'w-10 h-10 text-sm',
+		large: 'w-12 h-12 text-base'
+	};
+</script>
+
+<div class="flex -space-x-2 {className}">
+	{#each visible as viewer (viewer.user_id)}
+		<Tooltip content={tipFor(viewer)} display="inline-block">
+			<div class="border-2 border-base-100 rounded-full">
+				<Avatar name={viewer.name ?? '?'} avatarUrl={viewer.avatar_url} {size} />
+			</div>
+		</Tooltip>
+	{/each}
+
+	{#if overflow.length > 0}
+		<Tooltip content={overflowTip} display="inline-block">
+			<div class="border-2 border-base-100 rounded-full">
+				<div
+					class="bg-neutral text-neutral-content rounded-full flex items-center justify-center {overflowSizeClasses[
+						size
+					]}"
+				>
+					<span class="font-bold">+{overflow.length}</span>
+				</div>
+			</div>
+		</Tooltip>
+	{/if}
+</div>

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

@@ -0,0 +1,10 @@
+import type { PresenceViewer } from '../types/presence';
+interface Props {
+    viewers: PresenceViewer[];
+    maxVisible?: number;
+    size?: 'xs' | 'small' | 'medium' | 'large';
+    class?: string;
+}
+declare const PresenceStack: import("svelte").Component<Props, {}, "">;
+type PresenceStack = ReturnType<typeof PresenceStack>;
+export default PresenceStack;

package/dist/index.d.ts

@@ -38,9 +38,11 @@ export { default as SortDropdown } from './components/SortDropdown.svelte';
 export { default as InlineEdit } from './components/InlineEdit.svelte';
 export { default as FloatingActionBar } from './components/FloatingActionBar.svelte';
 export { default as BulkActionBar } from './components/BulkActionBar.svelte';
-export type { BulkAction } from './components/BulkActionBar.svelte';
+export type { BulkAction, BulkActionGroup } from './components/BulkActionBar.svelte';
 export { default as HunkDiffView } from './components/HunkDiffView.svelte';
 export { default as Tooltip } from './components/Tooltip.svelte';
+export { default as PresenceStack } from './components/PresenceStack.svelte';
+export type { PresenceViewer } from './types/presence';
 export { default as DirtyFormHost } from './components/DirtyFormHost.svelte';
 export { createDirtyGuard } from './utils/dirtyGuard';
 export type { DirtyGuard, DirtyGuardOptions, BeforeNavigateFn } from './utils/dirtyGuard';

package/dist/index.js

@@ -45,6 +45,7 @@ export { default as BulkActionBar } from './components/BulkActionBar.svelte';
 export { default as HunkDiffView } from './components/HunkDiffView.svelte';
 // Primitives — accessibility + form-editor scaffolding
 export { default as Tooltip } from './components/Tooltip.svelte';
+export { default as PresenceStack } from './components/PresenceStack.svelte';
 export { default as DirtyFormHost } from './components/DirtyFormHost.svelte';
 export { createDirtyGuard } from './utils/dirtyGuard';
 export { default as MediaLightbox } from './components/MediaLightbox.svelte';

package/dist/types/presence.d.ts

@@ -0,0 +1,8 @@
+/** One user currently viewing (and optionally editing a field of) an entity. */
+export interface PresenceViewer {
+    user_id: string;
+    name: string | null;
+    avatar_url?: string | null;
+    /** Field/scope the user is actively editing, or null/absent if just viewing. */
+    typing_scope?: string | null;
+}

package/dist/types/presence.js

@@ -0,0 +1,3 @@
+// Live-collaboration presence types — framework-agnostic wire shape shared by
+// any "who's viewing/editing this" feature (e.g. an SSE `presence.updated` event).
+export {};

package/package.json

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