@rokkit/actions 1.0.0-next.98 → 1.0.1

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/navigable.svelte.js

@@ -0,0 +1,40 @@
+import { on } from 'svelte/events'
+import { getKeyboardActions, defaultNavigationOptions } from './kbd'
+
+// Handle keyboard events
+function handleAction(actions, event) {
+	if (event.key in actions) {
+		event.preventDefault()
+		event.stopPropagation()
+		actions[event.key]()
+	}
+}
+/**
+ * A svelte action function that captures keyboard evvents and emits event for corresponding movements.
+ *
+ * @param {HTMLElement} node
+ * @param {import('./types').NavigableOptions} options
+ * @returns {import('./types').SvelteActionReturn}
+ */
+export function navigable(node, options) {
+	const handlers = {
+		previous: () => node.dispatchEvent(new CustomEvent('previous')),
+		next: () => node.dispatchEvent(new CustomEvent('next')),
+		collapse: () => node.dispatchEvent(new CustomEvent('collapse')),
+		expand: () => node.dispatchEvent(new CustomEvent('expand')),
+		select: () => node.dispatchEvent(new CustomEvent('select'))
+	}
+
+	let actions = {}
+	const handleKeydown = (event) => handleAction(actions, event)
+
+	$effect(() => {
+		// Use defaultNavigationOptions from kbd.js
+		const props = { ...defaultNavigationOptions, ...options }
+		actions = getKeyboardActions(props, handlers)
+
+		const cleanup = on(node, 'keyup', handleKeydown)
+
+		return () => cleanup()
+	})
+}

package/src/navigator.js

@@ -1,182 +1,272 @@
-import { handleAction } from './utils'
-import { noop, isNested, hasChildren, isExpanded } from '@rokkit/core'
-import {
-	moveNext,
-	movePrevious,
-	pathFromIndices,
-	indicesFromPath,
-	getCurrentNode
-} from './hierarchy'
-import { mapKeyboardEventsToActions } from './lib'
 /**
- * Keyboard navigation for Lists and NestedLists. The data is either nested or not and is not
- * expected to switch from nested to simple list or vice-versa.
+ * Navigator
  *
- * @param {HTMLElement}                        element - Root element for the actionn
- * @param {import('./types').NavigatorOptions} options - Configuration options for the action
- * @returns
+ * 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()
+ *   })
  */
-export function navigator(element, options) {
-	const { fields, enabled = true, vertical = true, idPrefix = 'id-' } = options
-	let items = [],
-		path = null,
-		currentNode = null
-
-	if (!enabled) return { destroy: noop }
-
-	const update = (input) => {
-		const previousNode = currentNode
-		items = input.items
-		path = pathFromIndices(input.indices ?? [], items, fields)
-		currentNode = getCurrentNode(path)
-
-		if (previousNode !== currentNode && currentNode) {
-			const indices = indicesFromPath(path)
-			const current = element.querySelector(`#${idPrefix}${indices.join('-')}`)
-			if (current) {
-				current.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
-			}
-		}
+
+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) return 'range'
+	if (ctrlKey) return 'extend'
+	if (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
+}
 
-	const next = () => {
-		const previousNode = currentNode
-		path = moveNext(path, items, fields)
-		currentNode = getCurrentNode(path)
-		if (previousNode !== currentNode) moveTo(element, path, currentNode, idPrefix)
+// ─── Navigator ────────────────────────────────────────────────────────────────
+
+export class Navigator {
+	#root
+	#wrapper
+	#keymap
+	#containScroll
+
+	// Typeahead state
+	#buffer = ''
+	#bufferTimer = null
+
+	/**
+	 * @param {HTMLElement} root
+	 * @param {import('@rokkit/states').Wrapper} wrapper
+	 * @param {{ orientation?: string, dir?: string, collapsible?: boolean, containScroll?: boolean }} [options]
+	 */
+	constructor(root, wrapper, options = {}) {
+		this.#root = root
+		this.#wrapper = wrapper
+		this.#keymap = buildKeymap(options)
+		this.#containScroll = options.containScroll ?? false
+
+		root.addEventListener('keydown', this.#onKeydown)
+		root.addEventListener('click', this.#onClick)
+		root.addEventListener('focusin', this.#onFocusin)
+		root.addEventListener('focusout', this.#onFocusout)
+		if (this.#containScroll) {
+			root.addEventListener('wheel', this.#onWheel, { passive: false })
+		}
 	}
 
-	const previous = () => {
-		const previousNode = currentNode
-		path = movePrevious(path)
-		if (path.length > 0) {
-			currentNode = getCurrentNode(path)
-			if (previousNode !== currentNode) moveTo(element, path, currentNode, idPrefix)
+	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)
+		if (this.#containScroll) {
+			this.#root.removeEventListener('wheel', this.#onWheel)
 		}
+		this.#clearTypeahead()
 	}
-	const select = () => {
-		if (currentNode) emit('select', element, indicesFromPath(path), currentNode)
+
+	// ─── 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()
 	}
-	const collapse = () => {
-		if (currentNode) {
-			const expanded = isExpanded(currentNode, path[path.length - 1].fields)
-			if (expanded) {
-				toggle()
-			} else if (path.length > 0) {
-				path = path.slice(0, -1)
-				currentNode = getCurrentNode(path)
-				select()
-			}
+
+	// ─── 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
 	}
-	const expand = () => {
-		if (currentNode && hasChildren(currentNode, path[path.length - 1].fields)) {
-			toggle()
+
+	// ─── 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
 		}
 	}
-	function toggle() {
-		const expanded = isExpanded(currentNode, path[path.length - 1].fields)
-		const event = expanded ? 'collapse' : 'expand'
-		currentNode[path[path.length - 1].fields.isOpen] = !expanded
-		emit(event, element, indicesFromPath(path), currentNode)
-	}
-	const handlers = { next, previous, select, collapse, expand }
 
-	update(options)
+	// ─── Wheel ──────────────────────────────────────────────────────────────
 
-	const nested = isNested(items, fields)
-	const actions = mapKeyboardEventsToActions(handlers, {
-		horizontal: !vertical,
-		nested
-	})
+	#onWheel = (/** @type {WheelEvent} */ event) => {
+		// Prevent the wheel event from bubbling to parent scroll containers.
+		// Native scroll chaining is handled via CSS overscroll-behavior: contain.
+		event.stopPropagation()
+	}
 
-	const handleKeyDown = (event) => handleAction(actions, event)
+	// ─── Focusout ───────────────────────────────────────────────────────────
 
-	const handleClick = (event) => {
-		event.stopPropagation()
-		const target = findParentWithDataPath(event.target, element)
-		const indices = !target
-			? []
-			: target.dataset.path
-					.split(',')
-					.filter((item) => item !== '')
-					.map((item) => Number(item))
-
-		if (indices.length > 0 && event.target.tagName !== 'DETAIL') {
-			path = pathFromIndices(indices, items, fields)
-			currentNode = getCurrentNode(path)
-			if (hasChildren(currentNode, path[path.length - 1].fields)) {
-				currentNode[path[path.length - 1].fields.isOpen] =
-					!currentNode[path[path.length - 1].fields.isOpen]
-				const eventName = currentNode[path[path.length - 1].fields.isOpen] ? 'expand' : 'collapse'
-				emit(eventName, element, indices, currentNode)
-			} else if (currentNode !== null) emit('select', element, indices, currentNode)
-			emit('move', element, indices, currentNode)
-			// emit('select', element, indices, currentNode)
+	#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?.()
 		}
 	}
 
-	element.addEventListener('keydown', handleKeyDown)
-	element.addEventListener('click', handleClick)
+	// ─── Dispatch ───────────────────────────────────────────────────────────
 
-	return {
-		update,
-		destroy() {
-			element.removeEventListener('keydown', handleKeyDown)
-			element.removeEventListener('click', handleClick)
-		}
+	/**
+	 * 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)
 	}
-}
 
-/**
- * Move to the element with the given path
- *
- * @param {HTMLElement} element
- * @param {*} path
- * @param {*} currentNode
- * @param {*} idPrefix
- */
-export function moveTo(element, path, currentNode, idPrefix) {
-	const indices = indicesFromPath(path)
-	const current = element.querySelector(`#${idPrefix}${indices.join('-')}`)
-	if (current) current.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
+	// ─── Focus + scroll ──────────────────────────────────────────────────────
 
-	emit('move', element, indices, currentNode)
-}
+	#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' })
+	}
 
-/**
- * Find the parent element with data-path attribute
- *
- * @param {HTMLElement} element
- * @param {HTMLElement} root
- * @returns {HTMLElement}
- */
-export function findParentWithDataPath(element, root) {
-	if (element.hasAttribute('data-path')) return element
-	let parent = element.parentNode
+	// ─── Typeahead ───────────────────────────────────────────────────────────
 
-	while (parent && parent !== root && !parent.hasAttribute('data-path')) {
-		parent = parent.parentNode
+	#isPrintableKey(key, ctrlKey, metaKey, altKey) {
+		if (ctrlKey) return false
+		if (metaKey) return false
+		if (altKey) return false
+		if (key.length !== 1) return false
+		return key !== ' '
 	}
 
-	return parent !== root ? parent : null
-}
+	#appendBuffer(key) {
+		const startAfter = this.#buffer.length === 0 ? this.#wrapper.focusedKey : null
+		this.#buffer += key
+		if (this.#bufferTimer) {
+			clearTimeout(this.#bufferTimer)
+			this.#bufferTimer = null
+		}
+		this.#bufferTimer = setTimeout(() => this.#clearTypeahead(), TYPEAHEAD_RESET_MS)
+		return startAfter
+	}
 
-/**
- * Emit a custom event on the element with the path and node as detail
- *
- * @param {string} event
- * @param {HTMLElement} element
- * @param {Array<integer>} indices
- * @param {*} node
- */
-function emit(event, element, indices, node) {
-	element.dispatchEvent(
-		new CustomEvent(event, {
-			detail: {
-				path: indices,
-				node
-			}
-		})
-	)
+	/**
+	 * 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
+
+		if (!this.#isPrintableKey(key, ctrlKey, metaKey, altKey)) return false
+
+		const startAfter = this.#appendBuffer(key)
+
+		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
+		}
+	}
 }