@joewinke/jatui 0.1.10 → 0.1.19

package/README.md

@@ -0,0 +1,123 @@
+# @joewinke/jatui
+
+Shared Svelte 5 component library for JAT projects.
+
+## Installation
+
+```bash
+npm install @joewinke/jatui
+```
+
+Requires Svelte 5 and DaisyUI 5 as peer dependencies.
+
+---
+
+## Dialog Utilities
+
+`ConfirmDialog` and `InputDialog` are global, promise-based dialogs that replace the browser's native `confirm()` / `prompt()`. They're keyboard-accessible, animated, and theme-aware.
+
+### Setup — wire into root layout
+
+Mount both components once at the app root so they're always available:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { ConfirmDialog, InputDialog } from '@joewinke/jatui';
+</script>
+
+<slot />
+
+<ConfirmDialog />
+<InputDialog />
+```
+
+---
+
+### `showConfirm(opts)` → `Promise<boolean>`
+
+Shows a modal confirmation dialog. Resolves `true` if the user confirms, `false` if they cancel or the timeout expires.
+
+```typescript
+import { showConfirm } from '@joewinke/jatui';
+
+const ok = await showConfirm({
+  title: 'Delete project?',
+  body: 'This cannot be undone.',
+  danger: true,
+  timeoutMs: 10000,         // auto-cancel after 10 s; progress bar drains to zero
+  confirmLabel: 'Delete',   // default: 'Confirm' (danger) / 'OK' (non-danger)
+  cancelLabel: 'Keep',      // default: 'Cancel'
+});
+
+if (ok) {
+  await deleteProject(id);
+}
+```
+
+**Options (`ConfirmOptions`):**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | required | Dialog heading |
+| `body` | `string` | — | Supporting detail text |
+| `danger` | `boolean` | `true` | Red styling + terminal icon when `true`; info styling otherwise |
+| `timeoutMs` | `number` | `8000` | Auto-cancel after this many ms; `0` disables the timer |
+| `confirmLabel` | `string` | `'Confirm'` / `'OK'` | Confirm button label |
+| `cancelLabel` | `string` | `'Cancel'` | Cancel button label |
+
+**Keyboard:** `Enter` confirms · `Escape` cancels · focus starts on Cancel (safe default for destructive actions).
+
+---
+
+### `showInput(opts)` → `Promise<string | null>`
+
+Shows a modal text-input dialog. Resolves with the typed string on confirm, `null` on cancel.
+
+```typescript
+import { showInput } from '@joewinke/jatui';
+
+const name = await showInput({
+  title: 'Rename project',
+  body: 'Enter a new name for this project.',
+  placeholder: 'My project',
+  maxLength: 60,
+  validate: (v) => v.trim().length < 2 ? 'Name must be at least 2 characters.' : null,
+});
+
+if (name !== null) {
+  await renameProject(id, name.trim());
+}
+```
+
+**Options (`InputOptions`):**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | required | Dialog heading |
+| `body` | `string` | — | Supporting detail text |
+| `placeholder` | `string` | — | Input placeholder text |
+| `maxLength` | `number` | — | `maxlength` cap on the input field |
+| `validate` | `(value: string) => string \| null` | — | Return an error message to block submission, `null` to allow it |
+| `confirmLabel` | `string` | `'OK'` | Confirm button label |
+| `cancelLabel` | `string` | `'Cancel'` | Cancel button label |
+
+**Keyboard:** `Enter` submits (runs `validate` first) · `Escape` cancels · input is focused on open.
+
+---
+
+### Migration guide — replacing native `confirm()` / `prompt()`
+
+```diff
+- if (!confirm('Are you sure you want to delete this?')) return;
++ if (!await showConfirm({ title: 'Delete this?', danger: true })) return;
+```
+
+```diff
+- const name = prompt('Enter a new name:', currentName);
+- if (name === null) return;
++ const name = await showInput({ title: 'Rename', placeholder: currentName });
++ if (name === null) return;
+```
+
+Both dialogs are non-blocking (`await`), keyboard-navigable, and respect the app's DaisyUI theme. Unlike native dialogs they don't pause the JavaScript event loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.1.10",
+  "version": "0.1.19",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -44,6 +44,8 @@
     "vite": "^6.0.0"
   },
   "dependencies": {
+    "diff": "^9.0.0",
+    "libphonenumber-js": "^1.12.41",
     "pdfjs-dist": "^5.6.205",
     "svelte-dnd-action": "^0.9.69"
   }

package/src/lib/actions/railNav.ts

@@ -0,0 +1,473 @@
+/**
+ * Keyboard-rail navigation primitive — action + composable.
+ *
+ * A drawer / form is a vertical sequence of "rungs". Focus starts in the first
+ * field. Up / Down (and j / k when NOT typing) step between rungs. Left / Right
+ * acts on the focused rung (cycle a value, switch a tab, open a picker). Escape
+ * pops focus out of a field back to the container, then fires `onEscape`.
+ *
+ * Rungs are ordinary HTML elements tagged with a `data-rail-id` attribute (or
+ * whatever attribute `attr` specifies). The consumer supplies an `order` array
+ * of ids that defines traversal; ids whose element is not currently rendered
+ * in the container are skipped at move time.
+ *
+ * ─── CSS contract ─────────────────────────────────────────────────────────────
+ *
+ * The controller applies two classes to rung host elements. Style them in your
+ * stylesheet (or in a parent scope):
+ *
+ *   .rail-focus   — persistent: applied to the currently active rung host. Use
+ *                   `:focus-visible` / `:has(:focus-visible)` inside the rule so
+ *                   only keyboard-driven focus shows a visible ring.
+ *
+ *   .rail-cycled  — transient (~280ms): applied when Left / Right changes a
+ *                   rung's value via `rail.bump(host)`. Use for a brief pulse
+ *                   that confirms the value changed.
+ *
+ * ─── Usage — action form (simplest) ──────────────────────────────────────────
+ *
+ *   <div use:railNav={{
+ *     order: () => ['title', 'type', 'priority'],
+ *     onAction: (id, dir, host) => cycleField(id, dir),
+ *     onEscape: () => closeDrawer(),
+ *   }}>
+ *     <input data-rail-id="title" />
+ *     <div   data-rail-id="type"     tabindex="-1">…</div>
+ *     <div   data-rail-id="priority" tabindex="-1">…</div>
+ *   </div>
+ *
+ * ─── Usage — composable form ──────────────────────────────────────────────────
+ *
+ *   const rail = createRailNav({
+ *     container: panelEl,
+ *     order: () => currentOrder,
+ *     onAction: (id, dir, host) => { rail.bump(host); cycleField(id, dir); },
+ *     onEscape: () => closeDrawer(),
+ *   });
+ *
+ *   // Wire both listeners on the container:
+ *   panelEl.addEventListener('keydown',  (e) => rail.handleKeydown(e));
+ *   panelEl.addEventListener('focusin',  (e) => rail.handleFocusin(e));
+ *
+ * ─── How to wire a drawer to railNav ──────────────────────────────────────────
+ *
+ *   1. Tag each rung host with `data-rail-id`:
+ *        <div data-rail-id="type" tabindex="-1">…</div>
+ *
+ *   2. Apply the action (or composable) to the drawer panel:
+ *        <div bind:this={panel} use:railNav={{ order, onAction, onEscape }} …>
+ *
+ *   3. Handle Left/Right in `onAction` and call `rail.bump(host)` on change:
+ *        onAction: (id, dir, host) => { formData[id] = cycle(opts[id], …, dir); rail.bump(host); }
+ */
+
+import type { Action } from 'svelte/action';
+
+// ─── Public types ──────────────────────────────────────────────────────────────
+
+export interface RailNavOptions {
+	/**
+	 * Rung id order, top → bottom. May be a plain array or a getter (called on
+	 * every navigation event so reactive lists stay in sync).
+	 */
+	order: string[] | (() => string[]);
+
+	/**
+	 * Called when Left / Right is pressed on a non-text rung.
+	 * `dir` is `1` for Right and `-1` for Left.
+	 * Call `rail.bump(host)` inside this handler if you want the pulse effect.
+	 */
+	onAction?: (rungId: string, dir: 1 | -1, host: HTMLElement) => void;
+
+	/**
+	 * Called when Escape is pressed while focus is already on (or has been
+	 * popped back to) the container itself. Typically closes the drawer / modal.
+	 */
+	onEscape?: () => void;
+
+	/**
+	 * Optional: when a child popover currently owns keyboard focus, return `true`
+	 * here to suppress rail navigation. Escape will call `onPopoverEscape` first.
+	 */
+	isPopoverOpen?: () => boolean;
+
+	/** Called on Escape when `isPopoverOpen()` returns true. */
+	onPopoverEscape?: () => void;
+
+	/**
+	 * When `true` (default), keystrokes on non-text rungs are stopped from
+	 * bubbling to window-level listeners behind a modal.
+	 */
+	trap?: boolean;
+
+	/**
+	 * Attribute used as the rung identifier. Default: `'data-rail-id'`.
+	 * The controller looks for elements matching `[<attr>="<id>"]`.
+	 */
+	attr?: string;
+
+	/**
+	 * The container element to search for rung hosts.
+	 *
+	 * Required for `createRailNav`. The `railNav` action fills this automatically
+	 * from the action's `node`.
+	 */
+	container?: HTMLElement;
+}
+
+export interface RailNavController {
+	/**
+	 * Feed a keydown event. Returns `true` if the event was consumed.
+	 * Attach to the container's `keydown` listener (or `onkeydown` in Svelte).
+	 */
+	handleKeydown(event: KeyboardEvent): boolean;
+
+	/**
+	 * Feed a focusin event so the controller can track which rung the user
+	 * Tabbed into. Attach to the container's `focusin` listener.
+	 */
+	handleFocusin(event: FocusEvent): void;
+
+	/** Step one rung in direction `1` (down) or `-1` (up). Wraps around. */
+	moveRung(dir: 1 | -1): void;
+
+	/** Focus the rung with the given id. No-op if the element is not rendered. */
+	focus(id: string): void;
+
+	/**
+	 * Re-derive the current rung list after a conditional rung appears or
+	 * disappears. The action calls this automatically in its `update` hook.
+	 * Call manually in the composable form after reactive state changes.
+	 */
+	refresh(): void;
+
+	/** The id of the last rung that received focus, or `''` if none. */
+	currentId(): string;
+
+	/**
+	 * Applies the transient `rail-cycled` class to `host` for ~280ms.
+	 * Call this inside `onAction` when a Left / Right key changes a value.
+	 */
+	bump(host: HTMLElement | null): void;
+}
+
+// ─── Exported helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Cycle through `list`, returning the item `dir` steps from `current`.
+ * Wraps around. Returns `current` unchanged when the list is empty.
+ *
+ * @example
+ *   cycle(['bug', 'feature', 'task'], 'feature',  1)  // → 'task'
+ *   cycle(['bug', 'feature', 'task'], 'bug',      -1)  // → 'task'
+ *   cycle(['a', 'b'],                'z',          1)  // → 'a'  (not found → start)
+ */
+export function cycle<T>(list: readonly T[], current: T, dir: 1 | -1): T {
+	if (list.length === 0) return current;
+	const i = list.indexOf(current);
+	// When `current` is not in the list, treat it as if we're at position -1
+	// so that `dir=1` lands at index 0 (the first item) and `dir=-1` lands at
+	// the last item — matching the "not found → start from the beginning" idiom.
+	const base = i === -1 ? -1 : i;
+	return list[(((base + dir) % list.length) + list.length) % list.length];
+}
+
+// ─── Internals ─────────────────────────────────────────────────────────────────
+
+const BUMP_DURATION_MS = 280;
+const RAIL_FOCUS_CLASS = 'rail-focus';
+const RAIL_CYCLED_CLASS = 'rail-cycled';
+
+interface OptsRef {
+	current: RailNavOptions;
+}
+
+function resolveOrder(opts: RailNavOptions): string[] {
+	return typeof opts.order === 'function' ? opts.order() : opts.order;
+}
+
+function resolveAttr(opts: RailNavOptions): string {
+	return opts.attr ?? 'data-rail-id';
+}
+
+/** Return all currently-rendered rung hosts in the rail order. */
+function resolveHosts(optsRef: OptsRef): HTMLElement[] {
+	const { container } = optsRef.current;
+	if (!container) return [];
+	const attr = resolveAttr(optsRef.current);
+	const order = resolveOrder(optsRef.current);
+	return order
+		.map((id) => container.querySelector<HTMLElement>(`[${attr}="${id}"]`))
+		.filter((el): el is HTMLElement => !!el);
+}
+
+/**
+ * Focus the most appropriate control inside a rung host:
+ *
+ *  1. If the host itself is directly focusable (input / select / textarea /
+ *     button / [contenteditable] / [tabindex]), focus it.
+ *  2. Otherwise search for a real field before a trigger button. We use an
+ *     explicit selector for real fields first because `querySelector` resolves
+ *     by document order — a label's `<button>` can appear before the field it
+ *     accompanies (e.g. a voice-mic button before a contenteditable).
+ *  3. Fall back to any `.sd-trigger,button` (SearchDropdown trigger etc.).
+ *  4. Last resort: focus the host itself (requires tabindex on the host).
+ */
+function focusRailHost(host: HTMLElement): void {
+	if (
+		host.matches('input,select,textarea,button,[contenteditable="true"],[tabindex]')
+	) {
+		host.focus();
+		return;
+	}
+	const inner =
+		host.querySelector<HTMLElement>('[contenteditable="true"],input,select,textarea') ??
+		host.querySelector<HTMLElement>('.sd-trigger,button');
+	(inner ?? host).focus();
+}
+
+function makeController(optsRef: OptsRef): RailNavController {
+	let _currentRailId = '';
+	let _lastFocusedHost: HTMLElement | null = null;
+
+	function applyFocusClass(host: HTMLElement | null): void {
+		if (_lastFocusedHost && _lastFocusedHost !== host) {
+			_lastFocusedHost.classList.remove(RAIL_FOCUS_CLASS);
+		}
+		if (host) host.classList.add(RAIL_FOCUS_CLASS);
+		_lastFocusedHost = host;
+	}
+
+	function bump(host: HTMLElement | null): void {
+		if (!host) return;
+		host.classList.remove(RAIL_CYCLED_CLASS);
+		void host.offsetWidth; // reflow so the animation restarts on rapid presses
+		host.classList.add(RAIL_CYCLED_CLASS);
+		setTimeout(() => host.classList.remove(RAIL_CYCLED_CLASS), BUMP_DURATION_MS);
+	}
+
+	function focus(id: string): void {
+		const { container } = optsRef.current;
+		if (!container) return;
+		const attr = resolveAttr(optsRef.current);
+		const host = container.querySelector<HTMLElement>(`[${attr}="${id}"]`);
+		if (host) {
+			focusRailHost(host);
+			applyFocusClass(host);
+			_currentRailId = id;
+		} else {
+			container.focus();
+		}
+	}
+
+	function moveRung(dir: 1 | -1): void {
+		const hosts = resolveHosts(optsRef);
+		if (hosts.length === 0) return;
+		const attr = resolveAttr(optsRef.current);
+		const ids = hosts.map((h) => h.getAttribute(attr)!);
+
+		// Anchor on the actually-focused rung first. Fall back to the last tracked
+		// rung (covers focus parked on the container after an Escape pop-out).
+		const active = document.activeElement as HTMLElement | null;
+		const activeFocused = (
+			active?.closest<HTMLElement>(`[${attr}]`)
+		)?.getAttribute(attr);
+		const fromId =
+			activeFocused && ids.includes(activeFocused) ? activeFocused : _currentRailId;
+
+		let pos = fromId ? ids.indexOf(fromId) : -1;
+		if (pos === -1) pos = dir === 1 ? -1 : hosts.length;
+		const next = (((pos + dir) % hosts.length) + hosts.length) % hosts.length;
+		focusRailHost(hosts[next]);
+		applyFocusClass(hosts[next]);
+		_currentRailId = ids[next];
+	}
+
+	function refresh(): void {
+		// Re-derive hosts; re-apply focus class if the current rung is still rendered
+		// (DOM may have been reconstructed by Svelte's reactive updates).
+		const hosts = resolveHosts(optsRef);
+		const attr = resolveAttr(optsRef.current);
+		for (const h of hosts) {
+			if (h.getAttribute(attr) === _currentRailId) {
+				applyFocusClass(h);
+				return;
+			}
+		}
+	}
+
+	function handleFocusin(event: FocusEvent): void {
+		const attr = resolveAttr(optsRef.current);
+		const order = resolveOrder(optsRef.current);
+		const host = (event.target as HTMLElement | null)?.closest<HTMLElement>(
+			`[${attr}]`
+		);
+		const id = host?.getAttribute(attr);
+		// Only track rungs that are in the rail order. Tabbing into an off-rail
+		// control (e.g. a description textarea) leaves the last real rung intact
+		// so Up / Down can resume from it after the user tabs back out.
+		if (id && order.includes(id)) {
+			_currentRailId = id;
+			applyFocusClass(host!);
+		}
+	}
+
+	function handleKeydown(event: KeyboardEvent): boolean {
+		const opts = optsRef.current;
+		const el = document.activeElement as HTMLElement | null;
+		const tag = el?.tagName;
+		const isTextField =
+			!!el &&
+			(tag === 'INPUT' || tag === 'TEXTAREA' || el.isContentEditable === true);
+		const isMultiline =
+			!!el && (tag === 'TEXTAREA' || el.isContentEditable === true);
+		const hasMod = event.metaKey || event.ctrlKey || event.altKey;
+
+		// Modal trap — stop non-text keystrokes from bubbling to window-level page
+		// listeners (e.g., a listNav attached to `window`). Text-field keystrokes
+		// propagate normally so typing in the drawer doesn't interfere.
+		const trap = opts.trap !== false;
+		if (trap && !isTextField) event.stopPropagation();
+
+		// Escape cascade:
+		//  1. popover open → close popover (e.g. project dropdown)
+		//  2. focus inside a descendant control → pop back to container
+		//  3. focus already on the container (or just popped) → call onEscape
+		if (event.key === 'Escape' && !hasMod) {
+			const popoverOpen = opts.isPopoverOpen?.() ?? false;
+			if (popoverOpen) {
+				event.preventDefault();
+				opts.onPopoverEscape?.();
+				return true;
+			}
+			const { container } = opts;
+			if (container && el && el !== container && container.contains(el)) {
+				event.preventDefault();
+				container.focus();
+				return true;
+			}
+			event.preventDefault();
+			opts.onEscape?.();
+			return true;
+		}
+
+		// Rail motion — suppressed when a popover is open or a modifier is held.
+		const popoverOpen = opts.isPopoverOpen?.() ?? false;
+		if (!hasMod && !popoverOpen) {
+			// Vertical: ArrowDown / j step down; ArrowUp / k step up.
+			// j / k are blocked in ANY text field; arrows are blocked only inside
+			// multiline fields so the caret can still move line-by-line.
+			const goDown = event.key === 'ArrowDown' || event.key === 'j';
+			const goUp = event.key === 'ArrowUp' || event.key === 'k';
+			if (goDown || goUp) {
+				const isVimKey = event.key === 'j' || event.key === 'k';
+				const blocked = isVimKey ? isTextField : isMultiline;
+				if (!blocked) {
+					event.preventDefault();
+					moveRung(goDown ? 1 : -1);
+					return true;
+				}
+			}
+
+			// Horizontal: ArrowLeft / ArrowRight dispatch to `onAction`.
+			// Skipped inside text fields so caret-left / caret-right keep working.
+			if (
+				(event.key === 'ArrowLeft' || event.key === 'ArrowRight') &&
+				!isTextField
+			) {
+				event.preventDefault();
+				const attr = resolveAttr(opts);
+				// Prefer the element that actually has DOM focus, then fall back to
+				// the last tracked rung (focus parked on the container after pop-out).
+				const focusedHost =
+					(el?.closest<HTMLElement>(`[${attr}]`)) ??
+					(opts.container && _currentRailId
+						? opts.container.querySelector<HTMLElement>(
+								`[${attr}="${_currentRailId}"]`
+							)
+						: null);
+				if (focusedHost && opts.onAction) {
+					const rungId = focusedHost.getAttribute(attr) ?? '';
+					opts.onAction(
+						rungId,
+						event.key === 'ArrowRight' ? 1 : -1,
+						focusedHost
+					);
+				}
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	return {
+		handleKeydown,
+		handleFocusin,
+		moveRung,
+		focus,
+		refresh,
+		currentId: () => _currentRailId,
+		bump,
+	};
+}
+
+// ─── Composable ────────────────────────────────────────────────────────────────
+
+/**
+ * Imperative composable — use when you already own keydown / focusin handlers
+ * and want `railNav` to decide whether to consume the event.
+ *
+ * You **must** supply `options.container` and wire both events:
+ *
+ *   const rail = createRailNav({ container: panel, order, onAction, onEscape });
+ *   panel.addEventListener('keydown', (e) => rail.handleKeydown(e));
+ *   panel.addEventListener('focusin', (e) => rail.handleFocusin(e));
+ */
+export function createRailNav(options: RailNavOptions): RailNavController {
+	const ref: OptsRef = { current: options };
+	return makeController(ref);
+}
+
+// ─── Action ────────────────────────────────────────────────────────────────────
+
+/**
+ * Svelte action — attaches `keydown` and `focusin` listeners to `node` and
+ * handles rung stepping, horizontal action dispatch, and Escape cascade.
+ *
+ * @example
+ *   <div use:railNav={{ order, onAction, onEscape }}>
+ *     <input data-rail-id="title" />
+ *     <div   data-rail-id="type"     tabindex="-1">…</div>
+ *     <div   data-rail-id="priority" tabindex="-1">…</div>
+ *   </div>
+ */
+export const railNav: Action<HTMLElement, RailNavOptions | undefined> = (
+	node,
+	initial = { order: [] }
+) => {
+	const ref: OptsRef = { current: { ...initial, container: node } };
+	const controller = makeController(ref);
+
+	function onKeydown(e: KeyboardEvent) {
+		controller.handleKeydown(e);
+	}
+
+	function onFocusin(e: FocusEvent) {
+		controller.handleFocusin(e);
+	}
+
+	node.addEventListener('keydown', onKeydown);
+	node.addEventListener('focusin', onFocusin);
+
+	return {
+		update(next: RailNavOptions | undefined = { order: [] }) {
+			ref.current = { ...next, container: node };
+			controller.refresh();
+		},
+		destroy() {
+			node.removeEventListener('keydown', onKeydown);
+			node.removeEventListener('focusin', onFocusin);
+		},
+	};
+};