@rokkit/actions 1.0.0-next.127 → 1.0.0-next.129

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./types.js";
+export { Navigator } from "./navigator.js";
+export { Trigger } from "./trigger.js";
 export { keyboard } from "./keyboard.svelte.js";
 export { pannable } from "./pannable.svelte.js";
 export { swipeable } from "./swipeable.svelte.js";
@@ -13,3 +15,4 @@ export { reveal } from "./reveal.svelte.js";
 export { hoverLift } from "./hover-lift.svelte.js";
 export { magnetic } from "./magnetic.svelte.js";
 export { ripple } from "./ripple.svelte.js";
+export { buildKeymap, resolveAction, ACTIONS } from "./keymap.js";

package/dist/keymap.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Build a complete keymap for the given options.
+ *
+ * Returns three layers — plain, shift, ctrl — each mapping key name → action name.
+ * Call resolveAction(event, keymap) to look up the action for a keyboard event.
+ *
+ * @param {Object} [options]
+ * @param {'vertical'|'horizontal'} [options.orientation='vertical']
+ * @param {'ltr'|'rtl'} [options.dir='ltr']
+ * @param {boolean} [options.collapsible=false]
+ * @returns {{ plain: Record<string, string>, shift: Record<string, string>, ctrl: Record<string, string> }}
+ */
+export function buildKeymap({ orientation, dir, collapsible }?: {
+    orientation?: "vertical" | "horizontal" | undefined;
+    dir?: "ltr" | "rtl" | undefined;
+    collapsible?: boolean | undefined;
+}): {
+    plain: Record<string, string>;
+    shift: Record<string, string>;
+    ctrl: Record<string, string>;
+};
+/**
+ * Resolve the action for a keyboard event given a pre-built keymap.
+ * Returns null if the key has no binding.
+ *
+ * @param {KeyboardEvent} event
+ * @param {{ plain: Record<string, string>, shift: Record<string, string>, ctrl: Record<string, string> }} keymap
+ * @returns {string|null}
+ */
+export function resolveAction(event: KeyboardEvent, keymap: {
+    plain: Record<string, string>;
+    shift: Record<string, string>;
+    ctrl: Record<string, string>;
+}): string | null;
+export { ACTIONS } from "./nav-constants.js";

package/dist/nav-constants.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Navigator constants — keyboard actions, key bindings, and typeahead config.
+ * These are used by the Navigator class and keymap builder.
+ */
+export const ACTIONS: Readonly<{
+    next: "next";
+    prev: "prev";
+    first: "first";
+    last: "last";
+    expand: "expand";
+    collapse: "collapse";
+    select: "select";
+    extend: "extend";
+    range: "range";
+    cancel: "cancel";
+}>;
+export const PLAIN_FIXED: {
+    Enter: "select";
+    ' ': "select";
+    Home: "first";
+    End: "last";
+    Escape: "cancel";
+};
+export const CTRL_FIXED: {
+    ' ': "extend";
+    Home: "first";
+    End: "last";
+};
+export const SHIFT_FIXED: {
+    ' ': "range";
+};
+export const ARROWS: {
+    'vertical-ltr': {
+        move: {
+            ArrowUp: "prev";
+            ArrowDown: "next";
+        };
+        nested: {
+            ArrowLeft: "collapse";
+            ArrowRight: "expand";
+        };
+    };
+    'vertical-rtl': {
+        move: {
+            ArrowUp: "prev";
+            ArrowDown: "next";
+        };
+        nested: {
+            ArrowRight: "collapse";
+            ArrowLeft: "expand";
+        };
+    };
+    horizontal: {
+        move: {
+            ArrowLeft: "prev";
+            ArrowRight: "next";
+        };
+        nested: {
+            ArrowUp: "collapse";
+            ArrowDown: "expand";
+        };
+    };
+};
+/** Milliseconds of inactivity before the typeahead buffer resets. */
+export const TYPEAHEAD_RESET_MS: 500;

package/dist/navigator.d.ts

@@ -0,0 +1,14 @@
+export class Navigator {
+    /**
+     * @param {HTMLElement} root
+     * @param {import('@rokkit/states').Wrapper} wrapper
+     * @param {{ orientation?: string, dir?: string, collapsible?: boolean }} [options]
+     */
+    constructor(root: HTMLElement, wrapper: import("@rokkit/states").Wrapper, options?: {
+        orientation?: string;
+        dir?: string;
+        collapsible?: boolean;
+    });
+    destroy(): void;
+    #private;
+}

package/dist/reveal.svelte.d.ts

@@ -1,6 +1,7 @@
 /**
  * Scroll-triggered reveal action using IntersectionObserver.
  * Applies CSS transitions (opacity + translate) when element enters viewport.
+ * When stagger > 0, applies reveal to each child element independently.
  *
  * @param {HTMLElement} node
  * @param {RevealOptions} [options]
@@ -10,6 +11,7 @@
  * @property {string} [distance='1.5rem'] Slide distance (CSS unit)
  * @property {number} [duration=600] Animation duration (ms)
  * @property {number} [delay=0] Delay before animation starts (ms)
+ * @property {number} [stagger=0] Delay increment per child in ms (0 = disabled)
  * @property {boolean} [once=true] Only animate once
  * @property {number} [threshold=0.1] IntersectionObserver threshold (0–1)
  * @property {string} [easing='cubic-bezier(0.4, 0, 0.2, 1)'] CSS easing function
@@ -18,6 +20,7 @@ export function reveal(node: HTMLElement, options?: RevealOptions): void;
 /**
  * Scroll-triggered reveal action using IntersectionObserver.
  * Applies CSS transitions (opacity + translate) when element enters viewport.
+ * When stagger > 0, applies reveal to each child element independently.
  */
 export type RevealOptions = {
     /**
@@ -36,6 +39,10 @@ export type RevealOptions = {
      * Delay before animation starts (ms)
      */
     delay?: number | undefined;
+    /**
+     * Delay increment per child in ms (0 = disabled)
+     */
+    stagger?: number | undefined;
     /**
      * Only animate once
      */

package/dist/trigger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Trigger
+ *
+ * Manages dropdown open/close from a trigger button.
+ * Pairs with Navigator (on the dropdown) to form a complete dropdown component.
+ *
+ * Responsibilities:
+ *   - click on trigger     → toggle open/close
+ *   - Enter / Space        → toggle open/close
+ *   - ArrowDown            → open (callback can focus first item)
+ *   - ArrowUp              → open (callback can focus last item)
+ *   - Escape (document)    → close + return focus to trigger
+ *   - Click outside (doc)  → close
+ *
+ * Usage:
+ *   const trigger = new Trigger(triggerEl, containerEl, {
+ *     onopen: () => { isOpen = true },
+ *     onclose: () => { isOpen = false },
+ *     onlast: () => { wrapper.last(null) }  // optional: ArrowUp opens at end
+ *   })
+ *   // …
+ *   trigger.destroy()
+ */
+export class Trigger {
+    /**
+     * @param {HTMLElement} trigger    — the trigger button element
+     * @param {HTMLElement} container  — the menu root (for click-outside detection)
+     * @param {{ onopen: () => void, onclose: () => void, onlast?: () => void, isOpen: () => boolean }} callbacks
+     */
+    constructor(trigger: HTMLElement, container: HTMLElement, { onopen, onclose, onlast, isOpen }: {
+        onopen: () => void;
+        onclose: () => void;
+        onlast?: () => void;
+        isOpen: () => boolean;
+    });
+    get isOpen(): boolean;
+    open(): void;
+    close(): void;
+    destroy(): void;
+    #private;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.127",
+  "version": "1.0.0-next.129",
   "description": "Contains generic actions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",

package/src/index.js

@@ -1,5 +1,8 @@
 // skipcq: JS-E1004 - Needed for exposing all types
 export * from './types.js'
+export { Navigator } from './navigator.js'
+export { Trigger } from './trigger.js'
+export { buildKeymap, resolveAction, ACTIONS } from './keymap.js'
 export { keyboard } from './keyboard.svelte.js'
 export { pannable } from './pannable.svelte.js'
 export { swipeable } from './swipeable.svelte.js'

package/src/keymap.js

@@ -0,0 +1,81 @@
+/**
+ * List Keymap
+ *
+ * Maps keyboard inputs to semantic actions.
+ *
+ * Design principle: orientation is just a rotation of arrow key assignments.
+ *
+ *   vertical ltr  up/down  = prev/next    left/right = collapse/expand  (when collapsible)
+ *   vertical rtl  up/down  = prev/next    right/left = collapse/expand  (expand/collapse reversed)
+ *   horizontal    left/right = prev/next  up/down    = collapse/expand  (dir ignored — use CSS flex-reverse for RTL)
+ *
+ * ─── Actions ────────────────────────────────────────────────────────────────
+ *
+ *   next       focus next visible item, skip disabled
+ *   prev       focus previous visible item, skip disabled
+ *   first      jump to first visible item
+ *   last       jump to last visible item
+ *   expand     when collapsible: expand collapsed group
+ *              if already expanded: move focus to first child
+ *              on leaf: no-op
+ *   collapse   when collapsible: collapse expanded group
+ *              if already collapsed or leaf: move focus to parent
+ *              at root level: no-op
+ *   select     activate the focused item
+ *   extend     toggle individual selection (multiselect ctrl/cmd + space)
+ *   range      select contiguous range (multiselect shift + space)
+ */
+
+import { PLAIN_FIXED, CTRL_FIXED, SHIFT_FIXED, ARROWS } from './nav-constants.js'
+export { ACTIONS } from './nav-constants.js'
+
+function getArrows(orientation, dir) {
+	if (orientation === 'horizontal') return ARROWS.horizontal
+	return ARROWS[`vertical-${dir}`]
+}
+
+// ─── buildKeymap ──────────────────────────────────────────────────────────────
+
+/**
+ * Build a complete keymap for the given options.
+ *
+ * Returns three layers — plain, shift, ctrl — each mapping key name → action name.
+ * Call resolveAction(event, keymap) to look up the action for a keyboard event.
+ *
+ * @param {Object} [options]
+ * @param {'vertical'|'horizontal'} [options.orientation='vertical']
+ * @param {'ltr'|'rtl'} [options.dir='ltr']
+ * @param {boolean} [options.collapsible=false]
+ * @returns {{ plain: Record<string, string>, shift: Record<string, string>, ctrl: Record<string, string> }}
+ */
+export function buildKeymap({ orientation = 'vertical', dir = 'ltr', collapsible = false } = {}) {
+	const arrows = getArrows(orientation, dir)
+
+	return {
+		plain: {
+			...PLAIN_FIXED,
+			...arrows.move,
+			...(collapsible ? arrows.nested : {})
+		},
+		shift: { ...SHIFT_FIXED },
+		ctrl: { ...CTRL_FIXED }
+	}
+}
+
+// ─── resolveAction ────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the action for a keyboard event given a pre-built keymap.
+ * Returns null if the key has no binding.
+ *
+ * @param {KeyboardEvent} event
+ * @param {{ plain: Record<string, string>, shift: Record<string, string>, ctrl: Record<string, string> }} keymap
+ * @returns {string|null}
+ */
+export function resolveAction(event, keymap) {
+	const { key, ctrlKey, metaKey, shiftKey } = event
+
+	if (shiftKey && !ctrlKey && !metaKey) return keymap.shift[key] ?? null
+	if (ctrlKey || metaKey) return keymap.ctrl[key] ?? null
+	return keymap.plain[key] ?? null
+}

package/src/nav-constants.js

@@ -0,0 +1,61 @@
+/**
+ * Navigator constants — keyboard actions, key bindings, and typeahead config.
+ * These are used by the Navigator class and keymap builder.
+ */
+
+// ─── Navigator actions ────────────────────────────────────────────────────────
+
+export const ACTIONS = Object.freeze({
+	next: 'next',
+	prev: 'prev',
+	first: 'first',
+	last: 'last',
+	expand: 'expand',
+	collapse: 'collapse',
+	select: 'select',
+	extend: 'extend',
+	range: 'range',
+	cancel: 'cancel' // Escape — close dropdown, deselect, or dismiss
+})
+
+// ─── Keymap: fixed key bindings (orientation-independent) ────────────────────
+
+export const PLAIN_FIXED = {
+	Enter: ACTIONS.select,
+	' ': ACTIONS.select,
+	Home: ACTIONS.first,
+	End: ACTIONS.last,
+	Escape: ACTIONS.cancel
+}
+
+export const CTRL_FIXED = {
+	' ': ACTIONS.extend,
+	Home: ACTIONS.first,
+	End: ACTIONS.last
+}
+
+export const SHIFT_FIXED = {
+	' ': ACTIONS.range
+}
+
+// ─── Keymap: arrow key assignments per orientation/direction ──────────────────
+
+export const ARROWS = {
+	'vertical-ltr': {
+		move: { ArrowUp: ACTIONS.prev, ArrowDown: ACTIONS.next },
+		nested: { ArrowLeft: ACTIONS.collapse, ArrowRight: ACTIONS.expand }
+	},
+	'vertical-rtl': {
+		move: { ArrowUp: ACTIONS.prev, ArrowDown: ACTIONS.next },
+		nested: { ArrowRight: ACTIONS.collapse, ArrowLeft: ACTIONS.expand }
+	},
+	horizontal: {
+		move: { ArrowLeft: ACTIONS.prev, ArrowRight: ACTIONS.next },
+		nested: { ArrowUp: ACTIONS.collapse, ArrowDown: ACTIONS.expand }
+	}
+}
+
+// ─── Typeahead ────────────────────────────────────────────────────────────────
+
+/** Milliseconds of inactivity before the typeahead buffer resets. */
+export const TYPEAHEAD_RESET_MS = 500

package/src/navigator.js

@@ -0,0 +1,250 @@
+/**
+ * Navigator
+ *
+ * Wires DOM events on a root element to Wrapper actions.
+ * Designed as a plain class so it works as a Svelte action or standalone.
+ *
+ * Responsibilities:
+ *   - keydown   → keymap lookup → wrapper action (+ scrollIntoView)
+ *   - click     → click action lookup → wrapper action
+ *   - focusin   → find nearest data-path → wrapper.moveTo(path)
+ *                 if no data-path found (tabbed into container) → redirect to focusedKey
+ *   - focusout  → detect when focus leaves the list entirely → call wrapper.blur()
+ *   - typeahead → buffer printable chars → wrapper.findByText → wrapper.moveTo
+ *
+ * Usage:
+ *   const nav = new Navigator(rootEl, wrapper, { collapsible: true })
+ *   // …
+ *   nav.destroy()
+ *
+ * Or as a Svelte action (use inside $effect):
+ *   $effect(() => {
+ *     const nav = new Navigator(node, wrapper, options)
+ *     return () => nav.destroy()
+ *   })
+ */
+
+import { TYPEAHEAD_RESET_MS } from './nav-constants.js'
+import { buildKeymap, resolveAction } from './keymap.js'
+
+// ─── Click action resolution ──────────────────────────────────────────────────
+
+/**
+ * Determine the action for a mouse click based on modifiers and target.
+ * Group headers marked with data-accordion-trigger dispatch 'toggle'.
+ *
+ * @param {MouseEvent} event
+ * @returns {string}
+ */
+function getClickAction(event) {
+	const { shiftKey, ctrlKey, metaKey, target } = event
+
+	if (shiftKey && !ctrlKey && !metaKey) return 'range'
+	if (ctrlKey || metaKey) return 'extend'
+	if (target.closest('[data-accordion-trigger]')) return 'toggle'
+	return 'select'
+}
+
+// ─── Path resolution ──────────────────────────────────────────────────────────
+
+/**
+ * Walk up the DOM from target to find the nearest element with data-path.
+ * Returns null if none found within root.
+ *
+ * @param {EventTarget} target
+ * @param {HTMLElement} root
+ * @returns {string|null}
+ */
+function getPath(target, root) {
+	let el = /** @type {HTMLElement|null} */ (target)
+	while (el && el !== root) {
+		if (el.dataset?.path !== undefined) return el.dataset.path
+		el = el.parentElement
+	}
+	return null
+}
+
+// ─── Navigator ────────────────────────────────────────────────────────────────
+
+export class Navigator {
+	#root
+	#wrapper
+	#keymap
+
+	// Typeahead state
+	#buffer = ''
+	#bufferTimer = null
+
+	/**
+	 * @param {HTMLElement} root
+	 * @param {import('@rokkit/states').Wrapper} wrapper
+	 * @param {{ orientation?: string, dir?: string, collapsible?: boolean }} [options]
+	 */
+	constructor(root, wrapper, options = {}) {
+		this.#root = root
+		this.#wrapper = wrapper
+		this.#keymap = buildKeymap(options)
+
+		root.addEventListener('keydown', this.#onKeydown)
+		root.addEventListener('click', this.#onClick)
+		root.addEventListener('focusin', this.#onFocusin)
+		root.addEventListener('focusout', this.#onFocusout)
+	}
+
+	destroy() {
+		this.#root.removeEventListener('keydown', this.#onKeydown)
+		this.#root.removeEventListener('click', this.#onClick)
+		this.#root.removeEventListener('focusin', this.#onFocusin)
+		this.#root.removeEventListener('focusout', this.#onFocusout)
+		this.#clearTypeahead()
+	}
+
+	// ─── Keydown ────────────────────────────────────────────────────────────
+
+	#onKeydown = (/** @type {KeyboardEvent} */ event) => {
+		// Typeahead: single printable character (no modifiers except shift for caps)
+		if (this.#tryTypeahead(event)) return
+
+		const action = resolveAction(event, this.#keymap)
+		if (!action) return
+
+		// Links handle Enter/Space natively — browser fires a synthetic click
+		if (action === 'select' && event.target.closest('a[href]')) return
+
+		event.preventDefault()
+		event.stopPropagation()
+
+		// Resolve current path from the focused element so all actions get context
+		const path = getPath(document.activeElement, this.#root)
+		this.#dispatch(action, path)
+
+		// Scroll focused item into view after keyboard navigation
+		this.#syncFocus()
+	}
+
+	// ─── Click ──────────────────────────────────────────────────────────────
+
+	#onClick = (/** @type {MouseEvent} */ event) => {
+		const path = getPath(event.target, this.#root)
+		if (path === null) return
+
+		const action = getClickAction(event)
+
+		// Links: let browser navigate naturally, still update state
+		if (!event.target.closest('a[href]')) {
+			event.preventDefault()
+		}
+
+		this.#dispatch(action, path)
+		// No scrollIntoView — user clicked where they wanted
+	}
+
+	// ─── Focusin ────────────────────────────────────────────────────────────
+
+	#onFocusin = (/** @type {FocusEvent} */ event) => {
+		const path = getPath(event.target, this.#root)
+
+		if (path !== null) {
+			// Focused a specific item (click, programmatic focus, or tab with roving tabindex)
+			this.#wrapper.moveTo(path)
+			return
+		}
+
+		// Focused the container itself (user tabbed in, no roving tabindex item yet)
+		// Redirect focus to the currently focused item, or first item if none
+		const targetKey = this.#wrapper.focusedKey
+		const selector = targetKey
+			? `[data-path="${targetKey}"]`
+			: '[data-path]:not([disabled])'
+		const el = /** @type {HTMLElement|null} */ (this.#root.querySelector(selector))
+		if (el) {
+			el.focus()
+			// focusin will re-fire with the item as target, handled above
+		}
+	}
+
+	// ─── Focusout ───────────────────────────────────────────────────────────
+
+	#onFocusout = (/** @type {FocusEvent} */ event) => {
+		// relatedTarget is the element receiving focus next
+		// If it's null or outside this root, focus left the list
+		const next = /** @type {Node|null} */ (event.relatedTarget)
+		if (!next || !this.#root.contains(next)) {
+			// Focus left the list — wrapper can react (e.g. close a dropdown)
+			this.#wrapper.blur?.()
+		}
+	}
+
+	// ─── Dispatch ───────────────────────────────────────────────────────────
+
+	/**
+	 * Call wrapper[action](path) for every action.
+	 * Movement methods (next/prev/first/last/expand/collapse) ignore the path.
+	 * Selection methods (select/extend/range/toggle) use it.
+	 * If path is null for a selection action the wrapper falls back to focusedKey.
+	 *
+	 * @param {string} action
+	 * @param {string|null} path
+	 */
+	#dispatch(action, path) {
+		this.#wrapper[action]?.(path)
+	}
+
+	// ─── Focus + scroll ──────────────────────────────────────────────────────
+
+	#syncFocus() {
+		const key = this.#wrapper.focusedKey
+		if (!key) return
+		const el = /** @type {HTMLElement|null} */ (this.#root.querySelector(`[data-path="${key}"]`))
+		if (!el) return
+		if (el !== document.activeElement) el.focus()
+		el.scrollIntoView?.({ block: 'nearest', inline: 'nearest' })
+	}
+
+	// ─── Typeahead ───────────────────────────────────────────────────────────
+
+	/**
+	 * Handle printable character keys for typeahead search.
+	 * Returns true if the event was consumed.
+	 *
+	 * @param {KeyboardEvent} event
+	 * @returns {boolean}
+	 */
+	#tryTypeahead(event) {
+		const { key, ctrlKey, metaKey, altKey } = event
+
+		// Only single printable characters, no modifier combos
+		if (ctrlKey || metaKey || altKey) return false
+		if (key.length !== 1) return false
+		if (key === ' ') return false // Space is a keymap action, not typeahead
+
+		const startAfter = this.#buffer.length === 0 ? this.#wrapper.focusedKey : null
+		this.#buffer += key
+
+		// Cancel the existing reset timer but keep the accumulated buffer
+		if (this.#bufferTimer) {
+			clearTimeout(this.#bufferTimer)
+			this.#bufferTimer = null
+		}
+		this.#bufferTimer = setTimeout(() => this.#clearTypeahead(), TYPEAHEAD_RESET_MS)
+
+		const matchKey = this.#wrapper.findByText(this.#buffer, startAfter)
+		if (matchKey !== null) {
+			event.preventDefault()
+			event.stopPropagation()
+			this.#wrapper.moveTo(matchKey)
+			this.#syncFocus()
+			return true
+		}
+
+		return false
+	}
+
+	#clearTypeahead() {
+		this.#buffer = ''
+		if (this.#bufferTimer) {
+			clearTimeout(this.#bufferTimer)
+			this.#bufferTimer = null
+		}
+	}
+}

package/src/reveal.svelte.js

@@ -1,6 +1,7 @@
 /**
  * Scroll-triggered reveal action using IntersectionObserver.
  * Applies CSS transitions (opacity + translate) when element enters viewport.
+ * When stagger > 0, applies reveal to each child element independently.
  *
  * @param {HTMLElement} node
  * @param {RevealOptions} [options]
@@ -10,6 +11,7 @@
  * @property {string} [distance='1.5rem'] Slide distance (CSS unit)
  * @property {number} [duration=600] Animation duration (ms)
  * @property {number} [delay=0] Delay before animation starts (ms)
+ * @property {number} [stagger=0] Delay increment per child in ms (0 = disabled)
  * @property {boolean} [once=true] Only animate once
  * @property {number} [threshold=0.1] IntersectionObserver threshold (0–1)
  * @property {string} [easing='cubic-bezier(0.4, 0, 0.2, 1)'] CSS easing function
@@ -21,6 +23,7 @@ export function reveal(node, options = {}) {
 			distance: '1.5rem',
 			duration: 600,
 			delay: 0,
+			stagger: 0,
 			once: true,
 			threshold: 0.1,
 			easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
@@ -31,39 +34,80 @@ export function reveal(node, options = {}) {
 			typeof window !== 'undefined' &&
 			window.matchMedia('(prefers-reduced-motion: reduce)').matches
 
-		// Set CSS custom properties for the transition
-		node.style.setProperty('--reveal-duration', `${opts.duration}ms`)
-		node.style.setProperty('--reveal-distance', opts.distance)
-		node.style.setProperty('--reveal-easing', opts.easing)
+		const isStagger = opts.stagger > 0
 
-		// Apply direction attribute (CSS uses this for initial translate)
-		node.setAttribute('data-reveal', opts.direction)
+		function applyReveal(el) {
+			el.style.setProperty('--reveal-duration', `${opts.duration}ms`)
+			el.style.setProperty('--reveal-distance', opts.distance)
+			el.style.setProperty('--reveal-easing', opts.easing)
+			el.setAttribute('data-reveal', opts.direction)
+		}
+
+		function cleanReveal(el) {
+			el.removeAttribute('data-reveal')
+			el.removeAttribute('data-reveal-visible')
+			el.style.removeProperty('--reveal-duration')
+			el.style.removeProperty('--reveal-distance')
+			el.style.removeProperty('--reveal-easing')
+			el.style.removeProperty('transition-delay')
+		}
 
-		if (opts.delay > 0) {
-			node.style.transitionDelay = `${opts.delay}ms`
+		if (isStagger) {
+			Array.from(node.children).forEach((child) => applyReveal(child))
+		} else {
+			applyReveal(node)
+			if (opts.delay > 0) {
+				node.style.transitionDelay = `${opts.delay}ms`
+			}
 		}
 
 		if (reducedMotion) {
-			node.setAttribute('data-reveal-visible', '')
+			if (isStagger) {
+				Array.from(node.children).forEach((child) => child.setAttribute('data-reveal-visible', ''))
+			} else {
+				node.setAttribute('data-reveal-visible', '')
+			}
 			node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: true } }))
 			return () => {
-				node.removeAttribute('data-reveal')
-				node.removeAttribute('data-reveal-visible')
-				node.style.removeProperty('--reveal-duration')
-				node.style.removeProperty('--reveal-distance')
-				node.style.removeProperty('--reveal-easing')
+				if (isStagger) {
+					Array.from(node.children).forEach((child) => cleanReveal(child))
+				} else {
+					cleanReveal(node)
+				}
 			}
 		}
 
+		let timers = []
+
 		const observer = new IntersectionObserver(
 			(entries) => {
 				for (const entry of entries) {
 					if (entry.isIntersecting) {
-						node.setAttribute('data-reveal-visible', '')
+						if (isStagger) {
+							timers.forEach((t) => clearTimeout(t))
+							const kids = Array.from(node.children)
+							timers = kids.map((child, i) => {
+								if (!child.hasAttribute('data-reveal')) applyReveal(child)
+								return setTimeout(
+									() => child.setAttribute('data-reveal-visible', ''),
+									opts.delay + i * opts.stagger
+								)
+							})
+						} else {
+							node.setAttribute('data-reveal-visible', '')
+						}
 						node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: true } }))
 						if (opts.once) observer.unobserve(node)
 					} else if (!opts.once) {
-						node.removeAttribute('data-reveal-visible')
+						if (isStagger) {
+							timers.forEach((t) => clearTimeout(t))
+							timers = []
+							Array.from(node.children).forEach((child) =>
+								child.removeAttribute('data-reveal-visible')
+							)
+						} else {
+							node.removeAttribute('data-reveal-visible')
+						}
 						node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: false } }))
 					}
 				}
@@ -74,13 +118,13 @@ export function reveal(node, options = {}) {
 		observer.observe(node)
 
 		return () => {
+			timers.forEach((t) => clearTimeout(t))
 			observer.disconnect()
-			node.removeAttribute('data-reveal')
-			node.removeAttribute('data-reveal-visible')
-			node.style.removeProperty('--reveal-duration')
-			node.style.removeProperty('--reveal-distance')
-			node.style.removeProperty('--reveal-easing')
-			if (opts.delay > 0) node.style.removeProperty('transition-delay')
+			if (isStagger) {
+				Array.from(node.children).forEach((child) => cleanReveal(child))
+			} else {
+				cleanReveal(node)
+			}
 		}
 	})
 }

package/src/trigger.js

@@ -0,0 +1,112 @@
+/**
+ * Trigger
+ *
+ * Manages dropdown open/close from a trigger button.
+ * Pairs with Navigator (on the dropdown) to form a complete dropdown component.
+ *
+ * Responsibilities:
+ *   - click on trigger     → toggle open/close
+ *   - Enter / Space        → toggle open/close
+ *   - ArrowDown            → open (callback can focus first item)
+ *   - ArrowUp              → open (callback can focus last item)
+ *   - Escape (document)    → close + return focus to trigger
+ *   - Click outside (doc)  → close
+ *
+ * Usage:
+ *   const trigger = new Trigger(triggerEl, containerEl, {
+ *     onopen: () => { isOpen = true },
+ *     onclose: () => { isOpen = false },
+ *     onlast: () => { wrapper.last(null) }  // optional: ArrowUp opens at end
+ *   })
+ *   // …
+ *   trigger.destroy()
+ */
+
+export class Trigger {
+	#trigger
+	#container
+	#onopen
+	#onclose
+	#onlast
+	#isOpenFn
+
+	/**
+	 * @param {HTMLElement} trigger    — the trigger button element
+	 * @param {HTMLElement} container  — the menu root (for click-outside detection)
+	 * @param {{ onopen: () => void, onclose: () => void, onlast?: () => void, isOpen: () => boolean }} callbacks
+	 */
+	constructor(trigger, container, { onopen, onclose, onlast, isOpen }) {
+		this.#trigger = trigger
+		this.#container = container
+		this.#onopen = onopen
+		this.#onclose = onclose
+		this.#onlast = onlast
+		this.#isOpenFn = isOpen
+
+		trigger.addEventListener('click', this.#handleClick)
+		trigger.addEventListener('keydown', this.#handleKeydown)
+		document.addEventListener('click', this.#handleDocClick, true)
+		document.addEventListener('keydown', this.#handleDocKeydown)
+	}
+
+	get isOpen() { return this.#isOpenFn() }
+
+	open() {
+		if (this.isOpen) return
+		this.#onopen()
+	}
+
+	close() {
+		if (!this.isOpen) return
+		this.#onclose()
+		this.#trigger.focus()
+	}
+
+	// ─── Trigger element listeners ────────────────────────────────────────────
+
+	#handleClick = (event) => {
+		// Ignore clicks from interactive children (e.g. tag remove buttons)
+		const closest = event.target.closest('button, [role="button"], a, input, select, textarea')
+		if (closest && closest !== this.#trigger) return
+		if (this.isOpen) this.close()
+		else this.open()
+	}
+
+	#handleKeydown = (event) => {
+		const { key } = event
+		if (key === 'Enter' || key === ' ') {
+			event.preventDefault()
+			if (this.isOpen) this.close()
+			else this.open()
+		} else if (key === 'ArrowDown') {
+			event.preventDefault()
+			this.open()
+		} else if (key === 'ArrowUp') {
+			event.preventDefault()
+			this.open()
+			this.#onlast?.()
+		}
+	}
+
+	// ─── Document-level listeners ─────────────────────────────────────────────
+
+	#handleDocClick = (event) => {
+		if (!this.isOpen) return
+		if (!this.#container.contains(event.target)) this.close()
+	}
+
+	#handleDocKeydown = (event) => {
+		if (!this.isOpen || event.key !== 'Escape') return
+		event.preventDefault()
+		this.close()
+	}
+
+	// ─── Cleanup ──────────────────────────────────────────────────────────────
+
+	destroy() {
+		this.#trigger.removeEventListener('click', this.#handleClick)
+		this.#trigger.removeEventListener('keydown', this.#handleKeydown)
+		document.removeEventListener('click', this.#handleDocClick, true)
+		document.removeEventListener('keydown', this.#handleDocKeydown)
+	}
+}