@joewinke/jatui 0.55.0 → 0.56.0

package/CLAUDE.md

@@ -86,9 +86,9 @@ Then import:
 | `ActivityHeatmap` | GitHub-style activity-per-day calendar (calls/day, tasks closed/day): 7 weekday rows × week columns, default range = last 12 months, `weekStart`, 4-step `color-mix` ramp from one theme `tone` (no hex), one floating tooltip, legend + summary ("1,204 calls in the last year"). `role="grid"` with ONE tab stop: arrows move by day (↑↓) / week (←→), PgUp/PgDn 4 weeks, Home/End row ends, mod+Home/End range ends, Enter/Space select. Pure layout helpers exported (`buildHeatmap`, `moveHeatFocus`). | `data` (`{date, count}[]` or `getDate`/`getCount`), `start?`/`end?`, `weekStart?`, `unit?` ('call' or ['call','calls']), `formatLabel?`, `tone?`, `levels?`, `levelOf?`, `compact?`, `showLegend?`/`showWeekdays?`/`showMonths?`, `summary?`, `selected` (bindable), `onSelectDay?(date, count)`, `locale?` |
 | `StatusBadge` | Status indicator with dot | `status: StatusValue`, `label` |
 | `Card` | Content card container | `title`, `children` (snippet) |
-| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. **Escape is owned by the dialog element itself** (not the window handler) — Modal focuses the dialog on open, so `trapKeys`' stopPropagation would otherwise swallow Esc before the window listener sees it; a Modal opened inside a host Drawer closes before the drawer. The component ships its own open-state `.modal-box` opacity rule, so it renders under DaisyUI 5 with no host global override. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number`, `trapKeys?`, `closeOnEscape?` |
+| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. **On open, focus goes to the first fillable field** (WAI-ARIA APG): a `[data-autofocus]`/`autofocus` element, else the first enabled **rendered** text-entry control (readOnly/disabled textareas excluded, unrendered candidates skipped), else the dialog itself — `initialFocus` overrides the order (`'dialog'` restores the old container focus); the focus landing is verified, else the container is focused. When the dialog is the fallback focus, **Escape is owned by the dialog element itself** (not the window handler), so `trapKeys`' stopPropagation can't swallow Esc; a Modal opened inside a host Drawer closes before the drawer. The component ships its own open-state `.modal-box` opacity rule, so it renders under DaisyUI 5 with no host global override. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number`, `trapKeys?`, `closeOnEscape?`, `initialFocus?` |
 | `ConfirmModal` | Yes/no confirmation dialog | `open` (bindable), `title`, `message`, `onConfirm`, `onCancel` |
-| `Drawer` | Slide-out side panel. Header ✕ is a `CloseButton`; the body carries `use:scrollEdge` (opt out with `scrollEdge={false}`). | `open` (bindable), `side`, `scrollEdge?`, `children` (snippet) |
+| `Drawer` | Slide-out side panel. Header ✕ is a `CloseButton`; the body carries `use:scrollEdge` (opt out with `scrollEdge={false}`). On open it focuses the first fillable field ([data-autofocus]/autofocus, else first enabled **rendered** text-entry control, else the panel) — `initialFocus` (`null` opts out). | `open` (bindable), `side`, `initialFocus?`, `scrollEdge?`, `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` |
@@ -106,7 +106,7 @@ Then import:
 | `BatchJobTable` | Generic queue runner (harvested from vid-gen's BatchGenerator) — `<BatchJobTable generics T>` over bindable `JobRow<T>[]`; host supplies async `run(data, {signal, attempt, reportProgress})`. Concurrency cap, optional per-run `processLimit` (quota budget), rolling-average ETA, per-row status badge / progress / elapsed / retry / skip / cancel / reorder — each cell a snippet override (`statusCell`, `progressCell`, `elapsedCell`, `actionsCell`), host data columns via `headers` + `cells`, extra toolbar content via `toolbar`. Uses `showToast` / `showConfirm` (mount `ToastHost` + `ConfirmDialog`). Exposes `start()`/`pause()`/`cancel()`/`retryFailed()`/`clearFinished()`. Pure scheduling helpers exported too (`nextJobsToStart`, `moveJob`, `summarizeJobs`, `toJobRows`). | `jobs` (bindable), `run`, `concurrencyLimit?` (3), `processLimit?`, `autoStart?`, `notify?`, `confirmDestructive?`, `onJobDone?`, `onJobFailed?`, `onBatchDone?` |
 | `QuotaMeter` | "312 / 500 credits · resets in 4h 10m" bar — warning tint at `warnAt`, error at 100%. Presentational; the host owns the ledger. | `used`, `limit`, `resetsAt?`, `label?`, `unit?`, `warnAt?` (0.8), `size?` |
 | `VariantMatrixPicker` | Category/option chip grid for building a combinatorial variant matrix (harvested from vid-gen's FrameVariantGenerator, presets stripped — caller-supplied `categories`). Each category tab shows a live selection count and an additive/multiplicative badge: multiplicative selections cartesian-multiply the total, additive ones stack flat onto every combination. Live combination count in the footer; algebra exported separately as pure functions (`generateCombinations`, `countCombinations`, `variantCategoryMode`, `findVariantOption`, `generateVariantFilename`). | `categories: VariantCategory[]`, `selected` (bindable `VariantSelection`), `forceMode?`, `showCount?` (true), `countLabel?`, `onChange?`, `class?` |
-| `BottomSheet` | Mobile bottom sheet (upstreamed from the JAT IDE — jatui-rl7w6.2): drag handle with pointer capture, backdrop close, optional header. `snap='dual'` enables the inspector pattern — peek → expanded snap heights with flick-momentum release (fast flick ≥ 0.5 px/ms wins over position; flick down from peek dismisses) and `visualViewport` keyboard avoidance so content clears the soft keyboard. | `open` (bindable), `title?`, `zIndex?` (70), `fullHeight?`, `snap?` ('single'\|'dual'), `peekFraction?` (0.4), `expandedFraction?` (0.9), `onclose?`, `children` (snippet) |
+| `BottomSheet` | Mobile bottom sheet (upstreamed from the JAT IDE — jatui-rl7w6.2): drag handle with pointer capture, backdrop close, optional header. `snap='dual'` enables the inspector pattern — peek → expanded snap heights with flick-momentum release (fast flick ≥ 0.5 px/ms wins over position; flick down from peek dismisses) and `visualViewport` keyboard avoidance so content clears the soft keyboard. | `open` (bindable), `title?`, `zIndex?` (70), `fullHeight?`, `snap?` ('single'\|'dual'), `peekFraction?` (0.4), `expandedFraction?` (0.9), `onclose?`, `initialFocus?` ('first-input': [data-autofocus]/autofocus, else first enabled **rendered** text-entry control, else the panel; `null` opts out), `children` (snippet) |
 
 ### Agent surfaces (BoardUI wave 2)
 

package/dist/components/AmbienceToggle.svelte

@@ -25,6 +25,11 @@
 	 *     relayed — we never proxy a third-party stream.
 	 *   - A playing playlist shows its current track's attribution (title,
 	 *     composer, license) under the playlist item and its section row.
+	 *   - With a menu or submenu open, the mouse wheel over that surface
+	 *     adjusts volume (wheel up = louder, ~5% per notch; the list still
+	 *     scrolls while it has room) — the wheel escapes to the page the moment
+	 *     the pointer leaves the surface. Each surface (panel and any open
+	 *     submenu) carries its own non-passive listener; never window.
 	 *
 	 * A11y: the trigger is `aria-pressed` while playing and carries the full
 	 * menu-button wiring (`aria-expanded` / `aria-haspopup` / `aria-controls`).
@@ -129,6 +134,65 @@
 		const x = Math.max(margin, Math.min(panel.left + 16, viewport.width - margin - width));
 		return { x, y: row.bottom + 2, side: 'over' };
 	}
+
+	// --- wheel volume over the open surfaces (jatui-xomny) -------------------
+
+	/** One mouse-wheel notch in pixel mode — Chrome/WebKit ship ±100 per notch. */
+	export const WHEEL_NOTCH_PX = 100;
+	/** One mouse-wheel notch in line mode — Firefox ships ±3 lines per notch. */
+	export const WHEEL_NOTCH_LINES = 3;
+	/** Volume change per wheel notch, on the 0-100 slider scale. */
+	export const WHEEL_STEP_PCT = 5;
+
+	/**
+	 * A wheel delta normalized into notch units (~1 = one physical notch):
+	 * pixel deltas divide by ~100 px, Firefox's line mode by 3 lines, and a
+	 * page-mode delta counts as one notch. Trackpads emit small pixel deltas
+	 * continuously — those are meant to accumulate (see wheelVolumeSteps),
+	 * not to step on every event.
+	 */
+	export function wheelNotches(deltaY: number, deltaMode: number): number {
+		if (deltaY === 0) return 0;
+		if (deltaMode === 1) return deltaY / WHEEL_NOTCH_LINES; // lines
+		if (deltaMode === 2) return deltaY; // one page ≈ one notch
+		return deltaY / WHEEL_NOTCH_PX; // pixels (deltaMode 0)
+	}
+
+	/**
+	 * Accumulate a wheel delta into `acc` and return the WHOLE volume steps it
+	 * adds up to, in volume terms — positive = louder (wheel up), negative =
+	 * quieter (wheel down) — 0 while a partial notch is still pending. The
+	 * remainder stays in `acc.value` across events, so trackpad pixel deltas
+	 * accumulate and one wheel notch lands as about one step.
+	 */
+	export function wheelVolumeSteps(
+		acc: { value: number },
+		deltaY: number,
+		deltaMode: number
+	): number {
+		acc.value += wheelNotches(deltaY, deltaMode);
+		// Wheel down (positive delta) quiets — flip the sign into volume steps.
+		// +0 normalizes Math.trunc's negative zero, which toBe/toEqual treat as
+		// a different value from 0.
+		const steps = Math.trunc(-acc.value) + 0;
+		if (steps !== 0) acc.value += steps; // consume the whole steps
+		return steps;
+	}
+
+	/**
+	 * The volume (0..1) after `steps` wheel steps: ±`stepPct` per step on the
+	 * 0-100 slider scale, clamped to 0-100. The math runs on the rounded
+	 * slider percent, so the result never carries float dust past what the
+	 * slider itself would produce for the same value.
+	 */
+	export function volumeAfterSteps(
+		volume: number,
+		steps: number,
+		stepPct = WHEEL_STEP_PCT
+	): number {
+		const next = Math.round(volume * 100) + steps * stepPct;
+		return Math.min(100, Math.max(0, next)) / 100;
+	}
 </script>
 
 <script lang="ts">
@@ -190,10 +254,18 @@
 	let panelRef = $state<HTMLDivElement | null>(null);
 	let subRef = $state<HTMLDivElement | null>(null);
 	let glyphRef = $state<HTMLSpanElement | null>(null);
+	/** The volume section (header + slider) at the top of the panel. */
+	let volumeRef = $state<HTMLDivElement | null>(null);
 
 	let playError = $state(false);
 	let track = $state<PlaylistState['track']>(null);
 
+	// Wheel-volume accumulator over the open surfaces (jatui-xomny): carries
+	// the pending partial notch between wheel events so trackpad pixel deltas
+	// accumulate into whole steps. Reset every time the menu opens; shared by
+	// the panel and its submenus for continuity.
+	const wheelAcc = { value: 0 };
+
 	const scapes = $derived(items.filter((i): i is Scape => !isAmbienceLink(i)));
 	const currentItem = $derived(items.find((s) => s.id === currentId) ?? null);
 	const currentLabel = $derived(currentItem?.label ?? currentId);
@@ -260,9 +332,10 @@
 	});
 
 	// While open: click-outside dismissal (capture phase, so a press that
-	// begins outside never reaches the page first) and APG focus movement into
-	// the menu — focus the first nav item once the panel exists. A resize
-	// closes an open submenu (its position is stale).
+	// begins outside never reaches the page first), the non-passive wheel
+	// listener on the PANEL element (never window — see onSurfaceWheel), and
+	// APG focus movement into the menu — focus the first nav item once the
+	// panel exists. A resize closes an open submenu (its position is stale).
 	$effect(() => {
 		if (!open) return;
 		const panel = panelRef;
@@ -276,12 +349,26 @@
 		const onResize = () => closeSubmenu(false);
 		document.addEventListener('pointerdown', onDocPointerDown, true);
 		window.addEventListener('resize', onResize);
+		panel.addEventListener('wheel', onPanelWheel, { passive: false });
 		return () => {
 			document.removeEventListener('pointerdown', onDocPointerDown, true);
 			window.removeEventListener('resize', onResize);
+			panel.removeEventListener('wheel', onPanelWheel);
 		};
 	});
 
+	// Non-passive wheel on any open submenu too (jatui-xomny): over the
+	// submenu the wheel is volume with the same rule — a list that can still
+	// scroll keeps scrolling. The submenu is a SIBLING of the panel (never
+	// clipped by its scroll box), so it carries its own listener.
+	$effect(() => {
+		const sub = subRef;
+		if (!open || !sub || subGroup === null) return;
+		const onSubWheel = (e: WheelEvent) => onSurfaceWheel(e, sub, false);
+		sub.addEventListener('wheel', onSubWheel, { passive: false });
+		return () => sub.removeEventListener('wheel', onSubWheel);
+	});
+
 	// Keep an open submenu inside the viewport vertically once its real
 	// height is known.
 	$effect(() => {
@@ -328,6 +415,7 @@
 		items = snapshot(); // freshest registry snapshot for the menu
 		effectivePlacement = resolvePlacement();
 		subGroup = null;
+		wheelAcc.value = 0; // a fresh menu starts from no pending wheel delta
 		open = true;
 	}
 
@@ -433,6 +521,74 @@
 		engine.setVolume(v / 100);
 	}
 
+	// --- wheel volume over the open surfaces (jatui-xomny) -------------------
+	// While the menu (or one of its submenus) is open the wheel adjusts volume
+	// instead of scrolling the page — EXCEPT over a scrollable list that can
+	// still move in the wheel's direction, where the wheel stays a scroll. The
+	// listeners are non-passive on the surface elements (the panel and any
+	// open submenu — the submenu is a SIBLING of the panel, so it needs its
+	// own) and are only attached while open, so a wheel anywhere else scrolls
+	// the page exactly as before.
+
+	/**
+	 * The elements a native wheel scroll could move for a target inside
+	 * `surface`: every HTMLElement from the target up to and including the
+	 * surface itself (the panel and each submenu are their own
+	 * `overflow-y-auto` scroll containers).
+	 */
+	function scrollablesBetween(target: Node, surface: HTMLElement): HTMLElement[] {
+		const out: HTMLElement[] = [];
+		let el: Node | null = target;
+		while (el && el !== surface) {
+			if (el instanceof HTMLElement) out.push(el);
+			el = el.parentNode;
+		}
+		out.push(surface);
+		return out;
+	}
+
+	/** Can `el` still move in the wheel's direction? (1px epsilon: a list
+	 *  sitting at its edge with sub-pixel scrollTop is at the end.) */
+	function canScrollFurther(el: HTMLElement, down: boolean): boolean {
+		const style = getComputedStyle(el);
+		const scrolls =
+			(style.overflowY === 'auto' || style.overflowY === 'scroll') &&
+			el.scrollHeight > el.clientHeight;
+		if (!scrolls) return false;
+		return down ? el.scrollTop + el.clientHeight < el.scrollHeight - 1 : el.scrollTop > 1;
+	}
+
+	/**
+	 * The shared wheel handler for one open surface. `hasVolume` marks the
+	 * panel — the surface that owns the volume section, where the wheel is
+	 * ALWAYS volume (it is a control, not a list). Over the list rows the
+	 * wheel stays a scroll while some scrollable under the pointer can still
+	 * move that way; past the end (or when the list is shorter than the
+	 * surface) it steps the volume instead of letting the scroll escape to
+	 * the page.
+	 */
+	function onSurfaceWheel(e: WheelEvent, surface: HTMLElement, hasVolume: boolean) {
+		const target = e.target as Node | null;
+		if (!target || !surface.contains(target)) return;
+		// Vertical wheel only — shift+wheel is horizontal scrolling.
+		if (e.deltaY === 0) return;
+		const down = e.deltaY > 0;
+		const overVolume = hasVolume && (volumeRef?.contains(target) ?? false);
+		const hijack =
+			overVolume || !scrollablesBetween(target, surface).some((el) => canScrollFurther(el, down));
+		if (!hijack) return; // native scroll — never preventDefault, never step
+
+		e.preventDefault();
+		const steps = wheelVolumeSteps(wheelAcc, e.deltaY, e.deltaMode);
+		if (steps !== 0) engine.setVolume(volumeAfterSteps(volume, steps));
+	}
+
+	function onPanelWheel(e: WheelEvent) {
+		const panel = panelRef;
+		if (!panel) return;
+		onSurfaceWheel(e, panel, true);
+	}
+
 	// --- pointer path to the menu: press-and-hold ----------------------------
 	function onPointerDown(e: PointerEvent) {
 		longPressed = false;
@@ -657,7 +813,7 @@
 			onscroll={() => closeSubmenu(false)}
 		>
 			<!-- Volume: a real slider in the roving set; it owns its own arrows. -->
-			<div role="none" class="mb-1 border-b border-base-content/10 px-2 pb-2.5 pt-1.5">
+			<div role="none" bind:this={volumeRef} class="mb-1 border-b border-base-content/10 px-2 pb-2.5 pt-1.5">
 				<div class="mb-1.5 flex items-center justify-between">
 					<span class="text-jatui-label text-base-content/60">Volume</span>
 					<span class="text-2xs text-base-content/50 tabular-nums">{sliderValue}%</span>

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

@@ -24,6 +24,11 @@
  *     relayed — we never proxy a third-party stream.
  *   - A playing playlist shows its current track's attribution (title,
  *     composer, license) under the playlist item and its section row.
+ *   - With a menu or submenu open, the mouse wheel over that surface
+ *     adjusts volume (wheel up = louder, ~5% per notch; the list still
+ *     scrolls while it has room) — the wheel escapes to the page the moment
+ *     the pointer leaves the surface. Each surface (panel and any open
+ *     submenu) carries its own non-passive listener; never window.
  *
  * A11y: the trigger is `aria-pressed` while playing and carries the full
  * menu-button wiring (`aria-expanded` / `aria-haspopup` / `aria-controls`).
@@ -91,6 +96,37 @@ export declare function placeSubmenu(row: {
     y: number;
     side: 'left' | 'right' | 'over';
 };
+/** One mouse-wheel notch in pixel mode — Chrome/WebKit ship ±100 per notch. */
+export declare const WHEEL_NOTCH_PX = 100;
+/** One mouse-wheel notch in line mode — Firefox ships ±3 lines per notch. */
+export declare const WHEEL_NOTCH_LINES = 3;
+/** Volume change per wheel notch, on the 0-100 slider scale. */
+export declare const WHEEL_STEP_PCT = 5;
+/**
+ * A wheel delta normalized into notch units (~1 = one physical notch):
+ * pixel deltas divide by ~100 px, Firefox's line mode by 3 lines, and a
+ * page-mode delta counts as one notch. Trackpads emit small pixel deltas
+ * continuously — those are meant to accumulate (see wheelVolumeSteps),
+ * not to step on every event.
+ */
+export declare function wheelNotches(deltaY: number, deltaMode: number): number;
+/**
+ * Accumulate a wheel delta into `acc` and return the WHOLE volume steps it
+ * adds up to, in volume terms — positive = louder (wheel up), negative =
+ * quieter (wheel down) — 0 while a partial notch is still pending. The
+ * remainder stays in `acc.value` across events, so trackpad pixel deltas
+ * accumulate and one wheel notch lands as about one step.
+ */
+export declare function wheelVolumeSteps(acc: {
+    value: number;
+}, deltaY: number, deltaMode: number): number;
+/**
+ * The volume (0..1) after `steps` wheel steps: ±`stepPct` per step on the
+ * 0-100 slider scale, clamped to 0-100. The math runs on the rounded
+ * slider percent, so the result never carries float dust past what the
+ * slider itself would produce for the same value.
+ */
+export declare function volumeAfterSteps(volume: number, steps: number, stepPct?: number): number;
 import type { Ambience } from '../ambience/types';
 type $$ComponentProps = {
     /** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. Section order/labels come from the engine's `groups` option. */

package/dist/components/BottomSheet.svelte

@@ -30,6 +30,7 @@
 	import { scrollEdge as scrollEdgeAction } from '../actions/scrollEdge';
 	import { onMount, untrack } from 'svelte';
 	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+	import { focusDialogTarget, type InitialFocus } from '../utils/dialogFocus';
 	import type { Snippet } from 'svelte';
 	import { fly, fade } from 'svelte/transition';
 	import { cubicOut } from 'svelte/easing';
@@ -52,6 +53,7 @@
 		shortcutRegistry,
 		shortcutContext = 'bottom-sheet',
 		scrollEdge = true,
+		initialFocus = 'first-input',
 		children
 	}: {
 		open?: boolean;
@@ -75,9 +77,27 @@
 		shortcutContext?: string;
 		/** Soft progressive-blur fade at the top of the content once it scrolls (`use:scrollEdge`). Ignored with `fullHeight` (the slot owns scrolling). Default true. */
 		scrollEdge?: boolean;
+		/**
+		 * What to focus when the sheet opens. Default `'first-input'`:
+		 * [data-autofocus]/[autofocus] inside the panel, else the first enabled
+		 * text-entry control, else the panel itself. `'dialog'` focuses the
+		 * panel without searching; an HTMLElement or CSS selector targets
+		 * exactly that; `null` disables auto-focus entirely.
+		 */
+		initialFocus?: InitialFocus | null;
 		children?: Snippet;
 	} = $props();
 
+	// On open, focus the first fillable field — WAI-ARIA APG dialog pattern:
+	// focus the first field the user is expected to fill. See
+	// utils/dialogFocus.ts for the resolution order. `initialFocus = null`
+	// opts out entirely.
+	let panelElement: HTMLElement | undefined = $state();
+	$effect(() => {
+		if (!open || initialFocus === null) return;
+		focusDialogTarget(panelElement ?? null, { initialFocus, fallback: panelElement ?? null });
+	});
+
 	// While open, a modal shortcut context keeps the host page's registry
 	// shortcuts from firing behind it.
 	$effect(() => {
@@ -234,6 +254,7 @@
 		class="fixed bottom-0 inset-x-0 flex flex-col bg-base-100 rounded-t-2xl border-t border-base-300 shadow-2xl"
 		style="z-index: {zIndex + 1}; {panelHeightStyle} transform: translateY({dragCurrentY}px); opacity: {dragOpacity}; transition: {isDragging ? 'none' : 'transform 0.15s ease, opacity 0.15s ease, height 0.2s ease'};"
 		role="dialog"
+		bind:this={panelElement}
 		tabindex="-1"
 		aria-modal="true"
 		aria-label={title || 'Bottom sheet'}

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

@@ -1,4 +1,5 @@
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+import { type InitialFocus } from '../utils/dialogFocus';
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     open?: boolean;
@@ -22,6 +23,14 @@ type $$ComponentProps = {
     shortcutContext?: string;
     /** Soft progressive-blur fade at the top of the content once it scrolls (`use:scrollEdge`). Ignored with `fullHeight` (the slot owns scrolling). Default true. */
     scrollEdge?: boolean;
+    /**
+     * What to focus when the sheet opens. Default `'first-input'`:
+     * [data-autofocus]/[autofocus] inside the panel, else the first enabled
+     * text-entry control, else the panel itself. `'dialog'` focuses the
+     * panel without searching; an HTMLElement or CSS selector targets
+     * exactly that; `null` disables auto-focus entirely.
+     */
+    initialFocus?: InitialFocus | null;
     children?: Snippet;
 };
 declare const BottomSheet: import("svelte").Component<$$ComponentProps, {}, "open">;

package/dist/components/ConfirmModal.svelte

@@ -3,6 +3,7 @@
   import { cubicOut } from 'svelte/easing';
   import { untrack } from 'svelte';
   import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+  import { focusDialogTarget, type InitialFocus } from '../utils/dialogFocus';
 
   let {
     open = $bindable(true),
@@ -17,6 +18,7 @@
     oncancel,
     shortcutRegistry,
     shortcutContext = 'confirm-modal',
+    initialFocus = 'first-input',
   } = $props<{
     open?: boolean
     title?: string
@@ -32,6 +34,14 @@
     shortcutRegistry?: ShortcutRegistry
     /** Context name pushed while open. Default `'confirm-modal'`. */
     shortcutContext?: string
+    /**
+     * What to focus when the modal opens (see utils/dialogFocus.ts).
+     * Default `'first-input'` resolves [data-autofocus]/[autofocus], then a
+     * text-entry control, then falls back to the dialog box itself — a
+     * confirm dialog has no text field, so it lands on the safe dialog
+     * element, never the destructive button.
+     */
+    initialFocus?: InitialFocus
   }>()
 
   // While open, a modal shortcut context keeps the host page's registry
@@ -59,11 +69,7 @@
     if (typeof document === 'undefined') return
     if (open) {
       previousFocus = document.activeElement as HTMLElement
-      requestAnimationFrame(() => {
-        if (modalBox?.contains(document.activeElement)) return
-        const first = modalBox?.querySelector<HTMLElement>(FOCUSABLE)
-        ;(first ?? modalBox)?.focus()
-      })
+      focusDialogTarget(modalBox, { initialFocus, fallback: modalBox })
     } else if (previousFocus) {
       previousFocus.focus?.()
       previousFocus = null

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

@@ -1,4 +1,5 @@
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+import { type InitialFocus } from '../utils/dialogFocus';
 type $$ComponentProps = {
     open?: boolean;
     title?: string;
@@ -14,6 +15,14 @@ type $$ComponentProps = {
     shortcutRegistry?: ShortcutRegistry;
     /** Context name pushed while open. Default `'confirm-modal'`. */
     shortcutContext?: string;
+    /**
+     * What to focus when the modal opens (see utils/dialogFocus.ts).
+     * Default `'first-input'` resolves [data-autofocus]/[autofocus], then a
+     * text-entry control, then falls back to the dialog box itself — a
+     * confirm dialog has no text field, so it lands on the safe dialog
+     * element, never the destructive button.
+     */
+    initialFocus?: InitialFocus;
 };
 declare const ConfirmModal: import("svelte").Component<$$ComponentProps, {}, "open">;
 type ConfirmModal = ReturnType<typeof ConfirmModal>;

package/dist/components/Drawer.svelte

@@ -12,6 +12,7 @@
 	import { scrollEdge as scrollEdgeAction } from '../actions/scrollEdge';
 	import { untrack, type Snippet } from 'svelte';
 	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+	import { focusDialogTarget, type InitialFocus } from '../utils/dialogFocus';
 
 	interface Props {
 		open?: boolean;
@@ -45,6 +46,15 @@
 		shortcutRegistry?: ShortcutRegistry;
 		/** Context name pushed while open. Default `'drawer'`. */
 		shortcutContext?: string;
+		/**
+		 * What to focus when the drawer opens. Default `'first-input'`:
+		 * [data-autofocus]/[autofocus] inside the panel, else the first enabled
+		 * text-entry control (text-like input, textarea, contenteditable —
+		 * never the header close button), else the panel itself. `'dialog'`
+		 * focuses the panel without searching for a field. An HTMLElement or
+		 * CSS selector targets exactly that; `null` disables auto-focus entirely.
+		 */
+		initialFocus?: InitialFocus | null;
 		onclose?: () => void;
 		class?: string;
 		headerActions?: Snippet;
@@ -67,6 +77,7 @@
 		trapKeys = true,
 		shortcutRegistry,
 		shortcutContext = 'drawer',
+		initialFocus = 'first-input',
 		onclose,
 		class: className = '',
 		headerActions,
@@ -96,6 +107,17 @@
 		onclose?.();
 	}
 
+	let panelElement: HTMLElement | undefined = $state();
+
+	// On open, focus the first fillable field — WAI-ARIA APG dialog pattern:
+	// focus the first field the user is expected to fill. See
+	// utils/dialogFocus.ts for the resolution order. `initialFocus = null`
+	// opts out entirely.
+	$effect(() => {
+		if (!open || initialFocus === null) return;
+		focusDialogTarget(panelElement ?? null, { initialFocus, fallback: panelElement ?? null });
+	});
+
 	function handleKeydown(e: KeyboardEvent) {
 		if (e.key === 'Escape' && open) {
 			e.stopImmediatePropagation();
@@ -140,6 +162,7 @@
 		? 'z-[101] translate-x-0'
 		: '-z-10 ' + (position === 'right' ? 'translate-x-full' : '-translate-x-full')} {className}"
 	role="dialog"
+	bind:this={panelElement}
 	aria-modal={open}
 	aria-label={title}
 	aria-hidden={!open}

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

@@ -1,5 +1,6 @@
 import { type Snippet } from 'svelte';
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+import { type InitialFocus } from '../utils/dialogFocus';
 interface Props {
     open?: boolean;
     title?: string;
@@ -32,6 +33,15 @@ interface Props {
     shortcutRegistry?: ShortcutRegistry;
     /** Context name pushed while open. Default `'drawer'`. */
     shortcutContext?: string;
+    /**
+     * What to focus when the drawer opens. Default `'first-input'`:
+     * [data-autofocus]/[autofocus] inside the panel, else the first enabled
+     * text-entry control (text-like input, textarea, contenteditable —
+     * never the header close button), else the panel itself. `'dialog'`
+     * focuses the panel without searching for a field. An HTMLElement or
+     * CSS selector targets exactly that; `null` disables auto-focus entirely.
+     */
+    initialFocus?: InitialFocus | null;
     onclose?: () => void;
     class?: string;
     headerActions?: Snippet;

package/dist/components/InputDialog.svelte

@@ -30,7 +30,12 @@
 		if (visible && opts) {
 			value = '';
 			error = null;
-			tick().then(() => inputRef?.focus());
+			// Focus AND select the input (jatui-fo6o8) so a replacement value
+			// can be typed over immediately without a select-all gesture.
+			tick().then(() => {
+				inputRef?.focus();
+				inputRef?.select();
+			});
 		}
 	});
 

package/dist/components/Modal.svelte

@@ -9,6 +9,7 @@
 	import CloseButton from './CloseButton.svelte';
 	import { onMount, untrack } from 'svelte';
 	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+	import { focusDialogTarget, type InitialFocus } from '../utils/dialogFocus';
 	import { fly, fade } from 'svelte/transition';
 	import { cubicOut } from 'svelte/easing';
 
@@ -51,6 +52,15 @@
 		shortcutRegistry?: ShortcutRegistry;
 		/** Context name pushed while open. Default `'modal'`. */
 		shortcutContext?: string;
+		/**
+		 * What to focus when the modal opens. Default `'first-input'`:
+		 * [data-autofocus]/[autofocus] inside the dialog, else the first enabled
+		 * text-entry control (text-like input, textarea, contenteditable —
+		 * never the header close button), else the dialog itself. `'dialog'`
+		 * restores the old container-focus behaviour for read-only/confirm
+		 * dialogs. An HTMLElement or CSS selector targets exactly that.
+		 */
+		initialFocus?: InitialFocus;
 		onclose?: () => void;
 		onopen?: () => void;
 		header?: import('svelte').Snippet;
@@ -75,6 +85,7 @@
 		trapKeys = true,
 		shortcutRegistry,
 		shortcutContext = 'modal',
+		initialFocus = 'first-input',
 		onclose,
 		onopen,
 		header,
@@ -112,7 +123,11 @@
 		if (open) {
 			previousFocus = document.activeElement as HTMLElement;
 			document.body.style.overflow = 'hidden';
-			requestAnimationFrame(() => modalElement?.focus());
+			// Focus the first fillable field, not the dialog box — see
+			// utils/dialogFocus.ts for the resolution order. Falls back to the
+			// dialog itself when there is no text field, so Escape handling
+			// (owned on the dialog element) keeps working as before.
+			focusDialogTarget(modalElement, { initialFocus, fallback: modalElement });
 			onopen?.();
 		} else {
 			document.body.style.overflow = '';
@@ -143,13 +158,13 @@
 
 	function handleKeyDown(event: KeyboardEvent) {
 		// Escape is owned HERE on the dialog element, not by <svelte:window>.
-		// Modal focuses the dialog (tabindex=-1) on open, so in the default state
-		// keydown dispatches from the dialog itself — and the trapKeys
-		// stopPropagation below (which under Svelte 5 delegated events also
-		// blocks every window listener) would swallow Escape before the window
-		// handler could act: Esc did nothing unless focus was in a text field.
-		// Handling it at element level also guarantees a Modal opened inside a
-		// host Drawer closes before the drawer does.
+		// When no text field matched, Modal focuses the dialog (tabindex=-1) on
+		// open, so in that state keydown dispatches from the dialog itself — and
+		// the trapKeys stopPropagation below (which under Svelte 5 delegated
+		// events also blocks every window listener) would swallow Escape before
+		// the window handler could act. Handling it at element level also
+		// guarantees a Modal opened inside a host Drawer closes before the
+		// drawer does.
 		if (open && event.key === 'Escape' && closeOnEscape) {
 			event.preventDefault();
 			event.stopPropagation();

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

@@ -1,4 +1,5 @@
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+import { type InitialFocus } from '../utils/dialogFocus';
 interface Props {
     open?: boolean;
     title?: string;
@@ -38,6 +39,15 @@ interface Props {
     shortcutRegistry?: ShortcutRegistry;
     /** Context name pushed while open. Default `'modal'`. */
     shortcutContext?: string;
+    /**
+     * What to focus when the modal opens. Default `'first-input'`:
+     * [data-autofocus]/[autofocus] inside the dialog, else the first enabled
+     * text-entry control (text-like input, textarea, contenteditable —
+     * never the header close button), else the dialog itself. `'dialog'`
+     * restores the old container-focus behaviour for read-only/confirm
+     * dialogs. An HTMLElement or CSS selector targets exactly that.
+     */
+    initialFocus?: InitialFocus;
     onclose?: () => void;
     onopen?: () => void;
     header?: import('svelte').Snippet;

package/dist/utils/dialogFocus.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Dialog focus resolution (jatui-fo6o8)
+ *
+ * Shared rule for every surface that opens an overlay dialog/panel
+ * (Modal, Drawer, BottomSheet, Confirm*, InputDialog): on open, focus in
+ * this order —
+ *
+ *   1. an element with [data-autofocus] or the `autofocus` attribute inside
+ *      the container (a consumer's explicit opt-in);
+ *   2. else the first ENABLED, RENDERED text-entry control in the body
+ *      (not the header close button — buttons never qualify anyway): a
+ *      text-like <input>, an enabled <textarea>, or a contenteditable
+ *      element;
+ *   3. else the container element itself (today's behaviour — keeps Escape
+ *      working for read-only / confirm dialogs, see Modal's Escape note).
+ *
+ * "Rendered" matters: a focus() on an element that is not actually visible
+ * (display:none, inside a collapsed <details>, a [hidden]/[inert] ancestor,
+ * or visibility:hidden) is a silent no-op that leaves focus on <body>, which
+ * breaks the dialog's own Escape handling (Modal owns Escape on the dialog
+ * element). Unrendered candidates are skipped, and after focusing the target
+ * is verified to actually hold focus — else the fallback/container is
+ * focused instead.
+ *
+ * WAI-ARIA APG dialog pattern: focus the first field the user is expected
+ * to fill. `initialFocus` overrides the whole order —
+ *
+ *   - `HTMLElement` / `string` (a CSS selector, resolved inside the
+ *     container): focus exactly that; falls through to the default order
+ *     when the selector matches nothing.
+ *   - `'dialog'`: always focus the container (old behaviour — right for
+ *     read-only / confirm dialogs).
+ *   - `'first-input'` (default): the 1→2→3 order above.
+ */
+export type InitialFocus = HTMLElement | string | 'dialog' | 'first-input';
+export interface FocusOptions {
+    /** Explicit target. Default `'first-input'`. */
+    initialFocus?: InitialFocus | null;
+    /** Element to focus when nothing matches. Default the container itself. */
+    fallback?: HTMLElement | null;
+}
+/** True for an element a user can type into: text-like input, enabled textarea, contenteditable. */
+export declare function isTextEntryControl(el: Element): boolean;
+/**
+ * Resolve the element a dialog should focus when it opens, per the order
+ * above. Returns null when nothing matches and there is no fallback.
+ */
+export declare function resolveDialogFocusTarget(container: HTMLElement | null, opts?: FocusOptions): HTMLElement | null;
+/**
+ * Focus a resolved target on the next frame (after the open transition has
+ * mounted the content). Mirrors the previous `requestAnimationFrame` timing
+ * so focus lands on real DOM, not a mounting tree.
+ */
+export declare function focusDialogTarget(container: HTMLElement | null, opts?: FocusOptions, rq?: typeof requestAnimationFrame): void;

package/dist/utils/dialogFocus.js

@@ -0,0 +1,153 @@
+/**
+ * Dialog focus resolution (jatui-fo6o8)
+ *
+ * Shared rule for every surface that opens an overlay dialog/panel
+ * (Modal, Drawer, BottomSheet, Confirm*, InputDialog): on open, focus in
+ * this order —
+ *
+ *   1. an element with [data-autofocus] or the `autofocus` attribute inside
+ *      the container (a consumer's explicit opt-in);
+ *   2. else the first ENABLED, RENDERED text-entry control in the body
+ *      (not the header close button — buttons never qualify anyway): a
+ *      text-like <input>, an enabled <textarea>, or a contenteditable
+ *      element;
+ *   3. else the container element itself (today's behaviour — keeps Escape
+ *      working for read-only / confirm dialogs, see Modal's Escape note).
+ *
+ * "Rendered" matters: a focus() on an element that is not actually visible
+ * (display:none, inside a collapsed <details>, a [hidden]/[inert] ancestor,
+ * or visibility:hidden) is a silent no-op that leaves focus on <body>, which
+ * breaks the dialog's own Escape handling (Modal owns Escape on the dialog
+ * element). Unrendered candidates are skipped, and after focusing the target
+ * is verified to actually hold focus — else the fallback/container is
+ * focused instead.
+ *
+ * WAI-ARIA APG dialog pattern: focus the first field the user is expected
+ * to fill. `initialFocus` overrides the whole order —
+ *
+ *   - `HTMLElement` / `string` (a CSS selector, resolved inside the
+ *     container): focus exactly that; falls through to the default order
+ *     when the selector matches nothing.
+ *   - `'dialog'`: always focus the container (old behaviour — right for
+ *     read-only / confirm dialogs).
+ *   - `'first-input'` (default): the 1→2→3 order above.
+ */
+const TEXT_INPUT_TYPES = new Set([
+    'text',
+    'search',
+    'url',
+    'tel',
+    'email',
+    'password',
+    'number',
+    '',
+    undefined
+]);
+/** True for an element a user can type into: text-like input, enabled textarea, contenteditable. */
+export function isTextEntryControl(el) {
+    if (el instanceof HTMLTextAreaElement) {
+        if (el.disabled || el.readOnly)
+            return false;
+        return true;
+    }
+    if (el instanceof HTMLInputElement) {
+        if (el.disabled || el.readOnly)
+            return false;
+        return TEXT_INPUT_TYPES.has(el.getAttribute('type') ?? undefined);
+    }
+    if (el.getAttribute?.('contenteditable') === 'true' || el.isContentEditable)
+        return true;
+    return false;
+}
+/** True when the element is not actually rendered, so focusing it is a
+ * silent no-op. Checks that cannot be evaluated (non-DOM test fakes) are
+ * treated as rendered. */
+function isUnrendered(el) {
+    if (typeof el.getClientRects === 'function' && el.getClientRects().length === 0)
+        return true;
+    if (typeof el.closest === 'function' && el.closest('[hidden], [inert]'))
+        return true;
+    if (typeof window !== 'undefined' && typeof window.getComputedStyle === 'function') {
+        if (window.getComputedStyle(el).visibility === 'hidden')
+            return true;
+    }
+    return false;
+}
+/** Enabled + attribute-level enabled (not disabled/aria-disabled/hidden). */
+function isEnabled(el) {
+    if (el.hasAttribute('disabled'))
+        return false;
+    if (el.getAttribute('aria-disabled') === 'true')
+        return false;
+    if (el.hasAttribute('hidden'))
+        return false;
+    return true;
+}
+/**
+ * Resolve the element a dialog should focus when it opens, per the order
+ * above. Returns null when nothing matches and there is no fallback.
+ */
+export function resolveDialogFocusTarget(container, opts = {}) {
+    if (!container)
+        return null;
+    const { initialFocus: initialFocusProp = 'first-input', fallback } = opts;
+    let initialFocus = initialFocusProp;
+    // Explicit 'dialog' — the old behaviour, verbatim.
+    if (initialFocus === 'dialog')
+        return container;
+    // Explicit element.
+    if (initialFocus instanceof HTMLElement)
+        return initialFocus;
+    // Explicit selector (any string other than the 'first-input' sentinel),
+    // resolved INSIDE the container. A miss falls through
+    // to the default first-input order (a consumer selector targeting a
+    // conditionally-rendered field shouldn't strand focus on the dialog).
+    if (typeof initialFocus === 'string' && initialFocus !== 'first-input') {
+        const found = container.querySelector(initialFocus);
+        if (found)
+            return found;
+        initialFocus = 'first-input';
+    }
+    // null opts out of auto-focus entirely (Drawer/BottomSheet): return only
+    // the explicit fallback, never the container.
+    if (initialFocus === null)
+        return fallback ?? null;
+    if (initialFocus !== 'first-input' && initialFocus != null)
+        return null;
+    // 1. Consumer's explicit autofocus opt-ins.
+    const autofocused = container.querySelector('[data-autofocus], [autofocus]:not(input[autofocus][type="hidden"])');
+    if (autofocused && isEnabled(autofocused) && !isUnrendered(autofocused))
+        return autofocused;
+    // 2. First enabled, rendered text-entry control in the body. Buttons
+    //    (including the header close ✕) never qualify, so the header is safe
+    //    to include.
+    const candidates = container.querySelectorAll('input, textarea, [contenteditable="true"], [contenteditable=""]');
+    for (const el of candidates) {
+        if (isEnabled(el) && !isUnrendered(el) && isTextEntryControl(el))
+            return el;
+    }
+    // 3. The dialog/panel itself.
+    return fallback ?? container;
+}
+/**
+ * Focus a resolved target on the next frame (after the open transition has
+ * mounted the content). Mirrors the previous `requestAnimationFrame` timing
+ * so focus lands on real DOM, not a mounting tree.
+ */
+export function focusDialogTarget(container, opts = {}, rq = requestAnimationFrame.bind(window)) {
+    rq(() => {
+        const target = resolveDialogFocusTarget(container, opts);
+        if (!target)
+            return;
+        target.focus();
+        // Verify the focus actually landed — a focus() on an unrendered or
+        // otherwise unfocusable element is a silent no-op that leaves focus on
+        // <body>, which breaks the dialog's own Escape handling (Modal owns
+        // Escape on the dialog element). Fall back to the container.
+        if (typeof document !== 'undefined' && document.activeElement !== target) {
+            const fallbackEl = opts.fallback ?? container;
+            if (fallbackEl)
+                fallbackEl.focus();
+        }
+    });
+}

package/package.json

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