@rokkit/actions 1.0.0-next.104 → 1.0.0-next.106

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.104",
+  "version": "1.0.0-next.106",
   "description": "Contains generic actions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -11,6 +11,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "prepublishOnly": "tsc --project tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "build": "bun clean && bun prepublishOnly"
+  },
   "files": [
     "src/**/*.js",
     "src/**/*.svelte"
@@ -25,13 +30,11 @@
     }
   },
   "dependencies": {
-    "ramda": "^0.30.1"
+    "ramda": "^0.30.1",
+    "@rokkit/core": "latest"
   },
   "devDependencies": {
-    "@rokkit/helpers": "1.0.0-next.104"
-  },
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "pnpm clean && pnpm prepublishOnly"
+    "@rokkit/helpers": "latest",
+    "@rokkit/states": "latest"
   }
-}
+}

package/src/delegate.svelte.js

@@ -0,0 +1,34 @@
+import { EventManager } from './lib'
+
+/**
+ * Svelte action function for forwarding keyboard events from a parent element to a child.
+ * The child is selected using a CSS selector passed in the options object.
+ * Optionally, you can specify which keyboard events you want to forward: "keydown", "keyup", and/or "keypress".
+ * By default, all three events are forwarded.
+ *
+ * @param {HTMLElement} element - The parent element from which keyboard events will be forwarded.
+ * @param {import('./types').PushDownOptions} options - The options object.
+ * @returns {{destroy: Function}}
+ */
+export function delegateKeyboardEvents(
+	element,
+	{ selector, events = ['keydown', 'keyup', 'keypress'] }
+) {
+	const child = element.querySelector(selector)
+	const handlers = {}
+	const manager = EventManager(element)
+
+	function forwardEvent(event) {
+		child.dispatchEvent(new KeyboardEvent(event.type, event))
+	}
+
+	$effect(() => {
+		if (child) {
+			events.forEach((event) => {
+				handlers[event] = forwardEvent
+			})
+			manager.update(handlers)
+		}
+		return () => manager.reset()
+	})
+}

package/src/dismissable.svelte.js

@@ -0,0 +1,33 @@
+import { on } from 'svelte/events'
+const KEYCODE_ESC = 27
+
+/**
+ * A svelte action function that captures clicks outside the element or escape keypress
+ * emits a `dismiss` event. This is useful for closing a modal or dropdown.
+ *
+ * @param {HTMLElement} node
+ */
+export function dismissable(node) {
+	const handleClick = (event) => {
+		if (node && !node.contains(event.target) && !event.defaultPrevented) {
+			node.dispatchEvent(new CustomEvent('dismiss'))
+		}
+	}
+
+	const keyup = (event) => {
+		if (event.keyCode === KEYCODE_ESC || event.key === 'Escape') {
+			event.stopPropagation()
+			node.dispatchEvent(new CustomEvent('dismiss', { detail: node }))
+		}
+	}
+
+	$effect(() => {
+		const cleanupClickEvent = on(document, 'click', handleClick)
+		const cleanupKeyupEvent = on(document, 'keyup', keyup)
+
+		return () => {
+			cleanupClickEvent()
+			cleanupKeyupEvent()
+		}
+	})
+}

package/src/fillable.svelte.js

@@ -0,0 +1,115 @@
+import { on } from 'svelte/events'
+/**
+ * Initialize empty fillable element style and add listener for click
+ *
+ * @param {HTMLCollection} blanks
+ * @param {EventListener} click
+ */
+function initialize(blanks, click) {
+	const registry = []
+	Array.from(blanks).forEach((blank, ref) => {
+		blank.innerHTML = '?'
+		blank.classList.add('empty')
+		blank.name = `fill-${ref}`
+		blank['data-index'] = ref
+		const cleanup = on(blank, 'click', click)
+		registry.push(cleanup)
+	})
+	return registry
+}
+
+/**
+ * Fill current blank with provided option
+ *
+ * @param {HTMLCollection} blanks
+ * @param {Array<import('./types.js').FillableData>} options
+ * @param {*} current
+ */
+function fill(blanks, { options, current }, node) {
+	if (current > -1 && current < Object.keys(blanks).length) {
+		const index = options.findIndex(({ actualIndex }) => actualIndex === current)
+		if (index > -1) {
+			blanks[current].innerHTML = options[index].value
+			blanks[current].classList.remove('empty')
+			blanks[current].classList.add('filled')
+			node.dispatchEvent(
+				new CustomEvent('fill', {
+					detail: {
+						index: current,
+						value: options[index].value
+					}
+				})
+			)
+		}
+	}
+}
+
+/**
+ * Clear all fillable elements
+ *
+ * @param {EventListener} event
+ * @param {HTMLElement} node
+ */
+function clear(event, node, options) {
+	const item = options.find(({ value }) => value === event.target.innerHTML)
+	event.target.innerHTML = '?'
+	event.target.classList.remove('filled')
+	event.target.classList.remove('pass')
+	event.target.classList.remove('fail')
+	event.target.classList.add('empty')
+
+	node.dispatchEvent(
+		new CustomEvent('remove', {
+			detail: {
+				index: event.target['data-index'],
+				value: item.value
+			}
+		})
+	)
+}
+
+/**
+ * Validate the filled values
+ *
+ * @param {HTMLCollection} blanks
+ * @param {import('./types').FillOptions} data
+ */
+function validate(blanks, data) {
+	Object.keys(blanks).forEach((_, ref) => {
+		const index = data.options.findIndex(({ actualIndex }) => actualIndex === ref)
+		if (index > -1)
+			blanks[ref].classList.add(
+				data.options[index].expectedIndex === data.options[index].actualIndex ? 'pass' : 'fail'
+			)
+	})
+}
+
+/**
+ * Action for filling a <del>?</del> element in html block.
+ *
+ * @param {HTMLElement} node
+ * @param {import('./types').FillOptions} options
+ * @returns
+ */
+export function fillable(node, data) {
+	const blanks = node.getElementsByTagName('del')
+
+	function click(event) {
+		if (event.target.innerHTML !== '?') {
+			clear(event, node, data.options)
+		} else {
+			data.current = event.target['data-index']
+			fill(blanks, data, node)
+		}
+	}
+
+	$effect(() => {
+		const registry = initialize(blanks, click)
+
+		if (data.check) validate(blanks, data)
+
+		return () => {
+			registry.forEach((cleanup) => cleanup())
+		}
+	})
+}

package/src/index.js

@@ -1,3 +1,12 @@
 // skipcq: JS-E1004 - Needed for exposing all types
 export * from './types.js'
 export { keyboard } from './keyboard.svelte.js'
+export { pannable } from './pannable.svelte.js'
+export { swipeable } from './swipeable.svelte.js'
+export { navigator } from './navigator.svelte.js'
+export { themable } from './themable.svelte.js'
+export { skinnable } from './skinnable.svelte.js'
+export { dismissable } from './dismissable.svelte.js'
+export { navigable } from './navigable.svelte.js'
+export { fillable } from './fillable.svelte.js'
+export { delegateKeyboardEvents } from './delegate.svelte.js'

package/src/keyboard.svelte.js

@@ -17,8 +17,8 @@ const defaultKeyMappings = {
  * @param {HTMLElement} root
  * @param {import('./types.js').KeyboardConfig} options - Custom key mappings
  */
-export function keyboard(root, options = defaultKeyMappings) {
-	const keyMappings = options || defaultKeyMappings
+export function keyboard(root, options = null) {
+	const keyMappings = options ?? defaultKeyMappings
 
 	/**
 	 * Handle keyboard events
@@ -27,8 +27,9 @@ export function keyboard(root, options = defaultKeyMappings) {
 	 */
 	const keyup = (event) => {
 		const { key } = event
-		const eventName = getEventForKey(keyMappings, key)
 
+		const eventName = getEventForKey(keyMappings, key)
+		// verify that the target is a child of the root element?
 		if (eventName) {
 			root.dispatchEvent(new CustomEvent(eventName, { detail: key }))
 		}
@@ -48,7 +49,7 @@ export function keyboard(root, options = defaultKeyMappings) {
 	}
 
 	$effect(() => {
-		const cleanupKeyupEvent = on(document, 'keyup', keyup)
+		const cleanupKeyupEvent = on(root, 'keyup', keyup)
 		const cleanupClickEvent = on(root, 'click', click)
 		return () => {
 			cleanupKeyupEvent()

package/src/lib/event-manager.js

@@ -0,0 +1,67 @@
+import { on } from 'svelte/events'
+
+/**
+ * Reset an event listener.
+ * @param {string} event - The event name.
+ * @param {Object} registry - The object containing the event listeners.
+ */
+function resetEvent(event, registry) {
+	if (typeof registry[event] === 'function') {
+		registry[event]()
+		delete registry[event]
+	}
+}
+
+/**
+ * EventManager class to manage event listeners on an element.
+ *
+ * @param {HTMLElement} element  - The element to listen for events on.
+ * @param {Object}      handlers - An object with event names as keys and event handlers as values.
+ * @returns {Object} - An object with methods to activate, reset, and update the event listeners.
+ */
+export function EventManager(element, handlers = {}, enabled = true) {
+	const registeredEvents = {}
+	const options = { handlers, enabled }
+
+	/**
+	 * Activate the event listeners.
+	 */
+	function activate() {
+		if (options.enabled) {
+			Object.entries(options.handlers).forEach(([event, handler]) => {
+				resetEvent(event, registeredEvents)
+				registeredEvents[event] = on(element, event, handler)
+			})
+		}
+	}
+
+	/**
+	 * Reset the event listeners.
+	 */
+	function reset() {
+		Object.keys(registeredEvents).forEach((event) => {
+			resetEvent(event, registeredEvents)
+		})
+	}
+
+	/**
+	 * Update the event listeners.
+	 *
+	 * @param {Object} newHandlers - An object with event names as keys and event handlers as values.
+	 * @param {boolean} enabled - Whether to enable or disable the event listeners.
+	 */
+	function update(newHandlers = handlers, enabled = true) {
+		const hasChanged = handlers !== newHandlers
+
+		if (!enabled) reset()
+
+		if (hasChanged) {
+			options.handlers = newHandlers
+			options.enabled = enabled
+			activate()
+		}
+	}
+
+	activate()
+	return { reset, update }
+}

package/src/lib/index.js

@@ -0,0 +1,3 @@
+// skipcq: JS-E1004 - Needed for exposing all functions
+export * from './internal'
+export { EventManager } from './event-manager'

package/src/lib/internal.js

@@ -0,0 +1,33 @@
+/**
+ * Sets up event handlers based on the given options.
+ * Returns whether or not the event handlers are listening.
+ *
+ * @param {HTMLElement} element
+ * @param {import('../types').EventHandlers} listeners
+ * @param {import('../types').TraversableOptions} options
+ * @returns {void}
+ */
+export function setupListeners(element, listeners, options) {
+	const { enabled } = { enabled: true, ...options }
+	if (enabled) {
+		Object.entries(listeners).forEach(([event, listener]) =>
+			element.addEventListener(event, listener)
+		)
+	}
+}
+
+/**
+ * Removes event handlers based on the given options.
+ * Returns whether or not the event handlers are listening.
+ *
+ * @param {HTMLElement} element
+ * @param {import('../types').EventHandlers} listeners
+ * @returns {void}
+ */
+export function removeListeners(element, listeners) {
+	if (listeners) {
+		Object.entries(listeners).forEach(([event, listener]) => {
+			element.removeEventListener(event, listener)
+		})
+	}
+}

package/src/navigable.svelte.js

@@ -0,0 +1,31 @@
+import { on } from 'svelte/events'
+import { handleAction, getKeyboardActions } from './utils'
+
+const defaultOptions = { horizontal: true, nested: false, enabled: true }
+/**
+ * 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(() => {
+		const props = { ...defaultOptions, ...options }
+		actions = getKeyboardActions(props, handlers)
+		const cleanup = on(node, 'keyup', handleKeydown)
+
+		return () => cleanup()
+	})
+}

package/src/navigator.svelte.js

@@ -0,0 +1,98 @@
+import { on } from 'svelte/events'
+import { getClosestAncestorWithAttribute, getEventForKey } from './utils.js'
+import { getPathFromKey } from '@rokkit/core'
+
+const Horizontal = {
+	prev: ['ArrowLeft'],
+	next: ['ArrowRight'],
+	collapse: ['ArrowUp'],
+	expand: ['ArrowDown'],
+	select: ['Enter']
+}
+
+const Vertical = {
+	prev: ['ArrowUp'],
+	next: ['ArrowDown'],
+	collapse: ['ArrowLeft'],
+	expand: ['ArrowRight'],
+	select: ['Enter']
+}
+
+/**
+ * Get actions for the navigator
+ *
+ * @param {import('./types.js').DataWrapper} wrapper - The navigator wrapper
+ * @param {HTMLElement} root - The root element
+ * @returns {import('./types.js').NavigatorActions} - The navigator actions
+ */
+function getActions(wrapper, root) {
+	const actions = {
+		prev: () => wrapper.movePrev(),
+		next: () => wrapper.moveNext(),
+		select: () => {
+			wrapper.select()
+			root.dispatchEvent(new CustomEvent('activate'))
+		},
+		collapse: () => wrapper.collapse?.(),
+		expand: () => wrapper.expand?.()
+	}
+	return actions
+}
+
+function handleIconClick(target, wrapper) {
+	const isIcon = target.tagName.toLowerCase() === 'rk-icon'
+	const state = isIcon ? target.getAttribute('data-state') : null
+
+	if (state === 'closed') {
+		wrapper.expand()
+	} else if (state === 'opened') {
+		wrapper.collapse()
+	}
+	return ['closed', 'opened'].includes(state)
+}
+
+/**
+ * Handle keyboard events
+ *
+ * @param {HTMLElement} root
+ * @param {import('./types.js').NavigatorConfig} options - Custom key mappings
+ */
+export function navigator(root, { wrapper, options }) {
+	const keyMappings = options?.direction === 'horizontal' ? Horizontal : Vertical
+	const actions = getActions(wrapper, root)
+
+	/**
+	 * Handle keyboard events
+	 *
+	 * @param {KeyboardEvent} event
+	 */
+	const keyup = (event) => {
+		const { key } = event
+
+		const eventName = getEventForKey(keyMappings, key)
+		if (eventName) {
+			actions[eventName]()
+		}
+	}
+
+	const click = (event) => {
+		const node = getClosestAncestorWithAttribute(event.target, 'data-path')
+
+		if (node) {
+			const iconClicked = handleIconClick(event.target, wrapper)
+			const path = getPathFromKey(node.getAttribute('data-path'))
+			wrapper.select(path, event.ctrlKey || event.metaKey)
+			root.dispatchEvent(new CustomEvent('activate'))
+			if (!iconClicked) wrapper.toggleExpansion()
+		}
+	}
+
+	$effect(() => {
+		const cleanupKeyupEvent = on(root, 'keyup', keyup)
+		const cleanupClickEvent = on(root, 'click', click)
+		return () => {
+			cleanupKeyupEvent()
+			cleanupClickEvent()
+		}
+	})
+}

package/src/pannable.svelte.js

@@ -0,0 +1,66 @@
+import { omit } from 'ramda'
+import { removeListeners, setupListeners } from './lib'
+
+/**
+ * Handles the panning event.
+ *
+ * @param {HTMLElement}              node   - The node where the event is dispatched.
+ * @param {Event}                    event  - The event object.
+ * @param {string}                   name   - The name of the event.
+ * @param {import('./types').Coords} coords - The previous coordinates of the event.
+ */
+function handleEvent(node, event, name, coords) {
+	const x = event.clientX ?? event.touches[0].clientX
+	const y = event.clientY ?? event.touches[0].clientY
+	const detail = { x, y }
+
+	if (name === 'panmove') {
+		detail.dx = x - coords.x
+		detail.dy = y - coords.y
+	}
+
+	event.stopPropagation()
+	event.preventDefault()
+	node.dispatchEvent(new CustomEvent(name, { detail }))
+	return omit(['dx', 'dy'], detail)
+}
+
+/**
+ * Makes an element pannable with mouse or touch events.
+ *
+ * @param {HTMLElement} node The DOM element to apply the panning action.
+ */
+export function pannable(node) {
+	let coords = { x: 0, y: 0 }
+	const listeners = { primary: {}, secondary: {} }
+
+	function start(event) {
+		coords = handleEvent(node, event, 'panstart', coords)
+		setupListeners(window, listeners.secondary)
+	}
+
+	function move(event) {
+		coords = handleEvent(node, event, 'panmove', coords)
+	}
+
+	function stop(event) {
+		coords = handleEvent(node, event, 'panend', coords)
+		removeListeners(window, listeners.secondary)
+	}
+
+	listeners.primary = {
+		mousedown: start,
+		touchstart: start
+	}
+	listeners.secondary = {
+		mousemove: move,
+		mouseup: stop,
+		touchmove: move,
+		touchend: stop
+	}
+
+	$effect(() => {
+		setupListeners(node, listeners.primary)
+		return () => removeListeners(node, listeners.primary)
+	})
+}

package/src/skinnable.svelte.js

@@ -0,0 +1,12 @@
+/**
+ * Applies theme variables to an element
+ * @param {HTMLElement} node - Element to apply variables to
+ * @param {Object.<string, string>} variables - CSS variables and their values
+ */
+export function skinnable(node, variables) {
+	$effect(() => {
+		Object.entries(variables).forEach(([key, value]) => {
+			node.style.setProperty(key, value)
+		})
+	})
+}

package/src/swipeable.svelte.js

@@ -0,0 +1,140 @@
+import { EventManager } from './lib'
+
+const defaultOptions = {
+	horizontal: true,
+	vertical: false,
+	threshold: 100,
+	enabled: true,
+	minSpeed: 300
+}
+
+/**
+ * Calculates and returns the distance and duration of the swipe.
+ *
+ * @param {Event} event - The event object that initiated the touchEnd.
+ * @param {object} track - The tracking object holding the start of the touch action.
+ * @returns {{distance: {x: number, y: number}, duration: number}} The distance swiped (x and y) and the duration of the swipe.
+ */
+function getTouchMetrics(event, track) {
+	const touch = event.changedTouches ? event.changedTouches[0] : event
+	const distX = touch.clientX - track.startX
+	const distY = touch.clientY - track.startY
+	const duration = (new Date().getTime() - track.startTime) / 1000
+	return { distance: { x: distX, y: distY }, duration }
+}
+
+/**
+ * Checks if the swipe was fast enough according to the minimum speed requirement.
+ *
+ * @param {{x: number, y: number}} distance - The distance of the swipe action.
+ * @param {number}                 duration - The duration of the swipe action in seconds.
+ * @param {number}                 minSpeed - The minimum speed threshold for the swipe action.
+ * @returns {boolean}              True if the swipe is fast enough, otherwise false.
+ */
+function isSwipeFastEnough(distance, duration, minSpeed) {
+	const speed = Math.max(Math.abs(distance.x), Math.abs(distance.y)) / duration
+	return speed > minSpeed
+}
+
+/**
+ * Returns the swipe direction based on the distance in the x and y axis.
+ *
+ * @param {number} distX - The distance in the x axis.
+ * @param {number} distY - The distance in the y axis.
+ * @returns {string} The swipe direction.
+ */
+function getSwipeDirection(distX, distY) {
+	if (Math.abs(distX) > Math.abs(distY)) {
+		return distX > 0 ? 'Right' : 'Left'
+	} else {
+		return distY > 0 ? 'Down' : 'Up'
+	}
+}
+
+/**
+ * Determines swipe validity and direction based on horizontal/vertical preferences and thresholds.
+ *
+ * @param {{x: number, y: number}} distance - The distance of the swipe.
+ * @param {object} options - Configuration options such as direction preferences and thresholds.
+ * @returns {{isValid: boolean, direction?: string}} Object indicating whether the swipe is valid, and if so, its direction.
+ */
+function getSwipeDetails(distance, options) {
+	const isHorizontalSwipe = options.horizontal && Math.abs(distance.x) >= options.threshold
+	const isVerticalSwipe = options.vertical && Math.abs(distance.y) >= options.threshold
+	if (isHorizontalSwipe || isVerticalSwipe) {
+		return {
+			isValid: true,
+			direction: getSwipeDirection(distance.x, distance.y)
+		}
+	}
+	return { isValid: false }
+}
+
+/**
+ * Handles the touch start event.
+ *
+ * @param {Event} event
+ * @param {import(./types).TouchTracker} track
+ */
+function touchStart(event, track) {
+	const touch = event.touches ? event.touches[0] : event
+	track.startX = touch.clientX
+	track.startY = touch.clientY
+	track.startTime = new Date().getTime()
+}
+
+/**
+ * Handles the touch end event and triggers a swipe event if the criteria are met.
+ *
+ * @param {Event}       event   - The event object representing the touch or mouse event.
+ * @param {HTMLElement} node    - The HTML element on which the swipe event will be dispatched.
+ * @param {object}      options - Configuration options for determining swipe behavior.
+ * @param {object}      track   - An object tracking the start point and time of the touch or swipe action.
+ */
+function touchEnd(event, node, options, track) {
+	const { distance, duration } = getTouchMetrics(event, track)
+	if (!isSwipeFastEnough(distance, duration, options.minSpeed)) return
+
+	const swipeDetails = getSwipeDetails(distance, options)
+	if (!swipeDetails.isValid) return
+	node.dispatchEvent(new CustomEvent(`swipe${swipeDetails.direction}`))
+}
+
+/**
+ * Returns the listeners for the swipeable action.
+ * @param {HTMLElement} node - The node where the event is dispatched.
+ * @param {import(./types).SwipeableOptions} options - The options for the swipe.
+ * @param {import(./types).TouchTracker} track - The tracking object.
+ * @returns {import(./types).Listeners}
+ */
+function getListeners(node, options, track) {
+	if (!options.enabled) return {}
+
+	const listeners = {
+		touchend: (e) => touchEnd(e, node, options, track),
+		touchstart: (e) => touchStart(e, track),
+		mousedown: (e) => touchStart(e, track),
+		mouseup: (e) => touchEnd(e, node, options, track)
+	}
+	return listeners
+}
+
+/**
+ * A svelte action function that captures swipe actions and emits event for corresponding movements.
+ *
+ * @param {HTMLElement} node
+ * @param {import(./types).SwipeableOptions} options
+ * @returns {import('./types').SvelteActionReturn}
+ */
+export function swipeable(node, options = defaultOptions) {
+	const track = {}
+	const manager = EventManager(node)
+
+	$effect(() => {
+		const props = { ...defaultOptions, ...options }
+		const listeners = getListeners(node, props, track)
+		manager.update(listeners, props.enabled)
+
+		return () => manager.reset()
+	})
+}

package/src/themable.svelte.js

@@ -0,0 +1,46 @@
+const DEFAULT_THEME = { style: 'rokkit', mode: 'dark', density: 'comfortable' }
+
+/**
+ * Update the theme attributes when the state changes.
+ *
+ * @param {HTMLElement} root
+ * @param {import('./types.js').ThemableConfig} options - Custom key mappings
+ */
+export function themable(root, options) {
+	const { theme = DEFAULT_THEME, storageKey } = options ?? {}
+
+	if (storageKey) {
+		// Initial load from storage
+		theme.load(storageKey)
+
+		// Save changes to storage
+		$effect(() => {
+			theme.save(storageKey)
+		})
+
+		// Handle storage events
+		const handleStorage = (event) => {
+			if (event.key === storageKey && event.newValue !== null) {
+				try {
+					const newTheme = JSON.parse(event.newValue)
+					theme.update(newTheme)
+				} catch (e) {
+					// eslint-disable-next-line no-console
+					console.warn(`Failed to parse theme from storage event for key "${storageKey}"`, e)
+				}
+			}
+		}
+		// Set up storage event listener
+		$effect.root(() => {
+			window.addEventListener('storage', handleStorage)
+			return () => window.removeEventListener('storage', handleStorage)
+		})
+	}
+	$effect(() => {
+		root.dataset.style = theme.style
+		root.dataset.mode = theme.mode
+		root.dataset.density = theme.density
+
+		// if (storageKey) theme.save(storageKey)
+	})
+}

package/src/types.js

@@ -8,3 +8,43 @@
 /**
  * @typedef {Object<string, (string[]|RegExp) >} KeyboardConfig
  */
+
+/**
+ * @typedef {'vertical'|'horizontal'} Direction
+ */
+
+/**
+ * @typedef {Object} NavigatorOptions
+ * @property {boolean}   enabled     - Whether the navigator is enabled
+ * @property {Direction} direction   - Whether the navigator is vertical or horizontal
+ * @property {boolean}   multiselect - Whether the navigator supports multiple selections
+ */
+
+/**
+ * @typedef {Object} DataWrapper
+ * @property {Function} moveNext
+ * @property {Function} movePrev
+ * @property {Function} moveFirst
+ * @property {Function} moveLast
+ * @property {Function} expand
+ * @property {Function} collapse
+ * @property {Function} select
+ * @property {Function} toggleExpansion
+ */
+
+/**
+ * @typedef {Object} NavigatorActions
+ * @property {Function} next
+ * @property {Function} prev
+ * @property {Function} first
+ * @property {Function} last
+ * @property {Function} expand
+ * @property {Function} collapse
+ * @property {Function} select
+ */
+
+/**
+ * @typedef {Object} NavigatorConfig
+ * @property {Navigator} wrapper     - Whether the navigator is enabled
+ * @property {NavigatorOptions} options   - Whether the navigator is vertical or horizontal
+ */

package/src/utils.js

@@ -1,3 +1,5 @@
+import { find, toPairs } from 'ramda'
+
 /**
  * Finds the closest ancestor of the given element that has the given attribute.
  *
@@ -11,8 +13,6 @@ export function getClosestAncestorWithAttribute(element, attribute) {
 	return getClosestAncestorWithAttribute(element.parentElement, attribute)
 }
 
-import * as R from 'ramda'
-
 /**
  * Get the event name for a given key.
  * @param {import('./types.js').KeyboardConfig} keyMapping
@@ -20,9 +20,49 @@ import * as R from 'ramda'
  * @returns {string|null} - The event name or null if no match is found.
  */
 export const getEventForKey = (keyMapping, key) => {
+	// eslint-disable-next-line no-unused-vars
 	const matchEvent = ([eventName, keys]) =>
 		(Array.isArray(keys) && keys.includes(key)) || (keys instanceof RegExp && keys.test(key))
 
-	const event = R.find(matchEvent, R.toPairs(keyMapping))
+	const event = find(matchEvent, toPairs(keyMapping))
 	return event ? event[0] : null
 }
+
+/*
+ * Generic action handler for keyboard events.
+ *
+ * @param {Record<string, () => void>} actions
+ * @param {KeyboardEvent} event
+ */
+export function handleAction(actions, event) {
+	if (event.key in actions) {
+		event.preventDefault()
+		event.stopPropagation()
+		actions[event.key]()
+	}
+}
+
+/**
+ *  Maps keys to actions based on the configuration.
+ *
+ * @param {import('./types').NavigableOptions} options
+ * @param {import('./types').NavigableHandlers} handlers
+ */
+export function getKeyboardActions(options, handlers) {
+	if (!options.enabled) return {}
+
+	const movement = options.horizontal
+		? { ArrowLeft: handlers.previous, ArrowRight: handlers.next }
+		: { ArrowUp: handlers.previous, ArrowDown: handlers.next }
+	const change = options.nested
+		? options.horizontal
+			? { ArrowUp: handlers.collapse, ArrowDown: handlers.expand }
+			: { ArrowLeft: handlers.collapse, ArrowRight: handlers.expand }
+		: {}
+	return {
+		Enter: handlers.select,
+		' ': handlers.select,
+		...movement,
+		...change
+	}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Jerry Thomas
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.