@joewinke/jatui 0.4.0 → 0.5.0

package/CLAUDE.md

@@ -68,6 +68,7 @@ Then import:
 | `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`; 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?` |
 
@@ -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/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

@@ -41,6 +41,8 @@ export { default as BulkActionBar } 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.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",