@rokkit/actions 1.0.0-next.105 → 1.0.0-next.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.105",
+  "version": "1.0.0-next.107",
   "description": "Contains generic actions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -30,9 +30,11 @@
     }
   },
   "dependencies": {
-    "ramda": "^0.30.1"
+    "ramda": "^0.30.1",
+    "@rokkit/core": "latest"
   },
   "devDependencies": {
-    "@rokkit/helpers": "1.0.0-next.104"
+    "@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,259 @@
+import { on } from 'svelte/events'
+import { getClosestAncestorWithAttribute, getEventForKey } from './utils.js'
+import { getPathFromKey } from '@rokkit/core'
+
+/**
+ * Key mappings for different navigation directions
+ */
+const KEY_MAPPINGS = {
+	horizontal: {
+		prev: ['ArrowLeft'],
+		next: ['ArrowRight'],
+		collapse: ['ArrowUp'],
+		expand: ['ArrowDown'],
+		select: ['Enter'],
+		toggle: ['Space'],
+		delete: ['Delete', 'Backspace']
+	},
+	vertical: {
+		prev: ['ArrowUp'],
+		next: ['ArrowDown'],
+		collapse: ['ArrowLeft'],
+		expand: ['ArrowRight'],
+		select: ['Enter'],
+		toggle: ['Space'],
+		delete: ['Delete', 'Backspace']
+	}
+}
+
+/**
+ * Navigator class to handle keyboard and mouse navigation
+ * @class
+ */
+class NavigatorController {
+	/**
+	 * @param {HTMLElement} root - The root element
+	 * @param {Object} wrapper - The data wrapper object
+	 * @param {Object} options - Configuration options
+	 */
+	constructor(root, wrapper, options = {}) {
+		this.root = root
+		this.wrapper = wrapper
+		this.options = options
+		this.keyMappings = KEY_MAPPINGS[options?.direction || 'vertical']
+
+		this.handleKeyUp = this.handleKeyUp.bind(this)
+		this.handleClick = this.handleClick.bind(this)
+	}
+
+	/**
+	 * Initialize event listeners
+	 */
+	init() {
+		return [on(this.root, 'keyup', this.handleKeyUp), on(this.root, 'click', this.handleClick)]
+	}
+
+	/**
+	 * Check if modifier keys are pressed
+	 * @param {Event} event - The event object
+	 * @returns {boolean} - Whether modifier keys are pressed
+	 */
+	hasModifierKey(event) {
+		return event.ctrlKey || event.metaKey || event.shiftKey
+	}
+
+	/**
+	 * Handle keyboard events
+	 * @param {KeyboardEvent} event - The keyboard event
+	 */
+	handleKeyUp(event) {
+		const { key } = event
+
+		const eventName = getEventForKey(this.keyMappings, key)
+
+		if (!eventName) return
+
+		const handled = this.processKeyAction(eventName, event)
+
+		if (handled) {
+			event.stopPropagation()
+		}
+	}
+
+	/**
+	 * Process a key action based on its type
+	 * @param {string} eventName - The mapped event name
+	 * @param {KeyboardEvent} event - The original keyboard event
+	 * @returns {boolean} - Whether the event was handled
+	 */
+	processKeyAction(eventName, event) {
+		const actionHandlers = {
+			prev: () => this.handleNavigationKey('prev', this.hasModifierKey(event)),
+			next: () => this.handleNavigationKey('next', this.hasModifierKey(event)),
+			expand: () => this.executeAction('expand'),
+			collapse: () => this.executeAction('collapse'),
+			select: () => this.executeAction('select'),
+			toggle: () => this.executeAction('extend'),
+			delete: () => this.executeAction('delete')
+		}
+
+		const handler = actionHandlers[eventName]
+		if (handler) {
+			return handler() !== false
+		}
+
+		return false
+	}
+
+	/**
+	 * Handle navigation key presses (arrows)
+	 * @param {string} direction - The direction to move ('prev' or 'next')
+	 * @param {boolean} hasModifier - Whether modifier keys are pressed
+	 * @returns {boolean} - Whether the action was handled
+	 */
+	handleNavigationKey(direction, hasModifier) {
+		// First move in the specified direction
+		const moved = this.executeAction(direction)
+
+		if (!moved) return false
+
+		// If modifier key is pressed and multiSelect is enabled, extend selection
+		if (hasModifier && this.wrapper.multiSelect) {
+			this.executeAction('extend')
+		} else {
+			// Otherwise just select the current item
+			this.executeAction('select')
+		}
+
+		// Always emit a move event for navigation
+		this.emitActionEvent('move')
+		return true
+	}
+
+	/**
+	 * Handle click events
+	 * @param {MouseEvent} event - The click event
+	 */
+	handleClick(event) {
+		const node = getClosestAncestorWithAttribute(event.target, 'data-path')
+
+		if (!node) return
+
+		const path = getPathFromKey(node.getAttribute('data-path'))
+		// Check if click was on a toggle icon
+		const toggleIconClicked = this.handleToggleIconClick(path, event.target)
+
+		if (toggleIconClicked) return
+
+		// Move to the clicked item
+		this.wrapper.moveTo(path)
+
+		// Handle selection based on modifier keys
+		if (this.hasModifierKey(event) && this.wrapper.multiSelect) {
+			this.executeAction('extend', path)
+		} else {
+			this.executeAction('select', path)
+		}
+		this.executeAction('toggle', path)
+		event.stopPropagation()
+	}
+
+	/**
+	 * Handle clicks on toggle icons
+	 * @param {number[]} path - The path of the item to perform the action on
+	 * @param {HTMLElement} target - The clicked element
+	 * @returns {boolean} - Whether a toggle icon was clicked and handled
+	 */
+	handleToggleIconClick(path, target) {
+		const isIcon = target.tagName.toLowerCase() === 'rk-icon'
+		const state = target.getAttribute('data-state')
+		if (!isIcon || !['closed', 'opened'].includes(state)) return false
+
+		return this.executeAction('toggle', path)
+	}
+
+	/**
+	 * Execute an action if available
+	 * @param {string} actionName - The name of the action to execute
+	 * @param {number[]} path - The path of the item to perform the action on
+	 * @returns {boolean} - Whether the action was executed
+	 */
+	executeAction(actionName, path) {
+		// Get the action function based on action name
+		const action = this.getActionFunction(actionName)
+
+		if (action) {
+			const executed = path ? action(path) : action()
+			if (executed) this.emitActionEvent(actionName)
+
+			return executed
+		}
+		return false
+	}
+
+	/**
+	 * Get the appropriate action function based on action name and conditions
+	 * @param {string} actionName - The name of the action
+	 * @returns {Function|null} - The action function or null if not available
+	 */
+	getActionFunction(actionName) {
+		// Basic navigation and selection actions always available
+		const actions = {
+			prev: () => this.wrapper.movePrev(),
+			next: () => this.wrapper.moveNext(),
+			select: (path) => this.wrapper.select(path),
+			collapse: (path) => this.wrapper.collapse(path),
+			expand: (path) => this.wrapper.expand(path),
+			toggle: (path) => this.wrapper.toggleExpansion(path),
+			extend: (path) => this.wrapper.extendSelection(path),
+			delete: () => this.wrapper.delete()
+		}
+
+		return actions[actionName] || null
+	}
+
+	/**
+	 * Emit an action event
+	 * @param {string} eventName - The name of the event to emit
+	 */
+	emitActionEvent(eventName) {
+		const data = {
+			path: this.wrapper.currentNode?.path,
+			value: this.wrapper.currentNode?.value
+		}
+
+		// For select events, include selected nodes
+		if (['select', 'extend'].includes(eventName)) {
+			data.selected = Array.from(this.wrapper.selectedNodes.values()).map((node) => node.value)
+			// Normalize selection events to 'select'
+			eventName = 'select'
+		} else if (['prev', 'next'].includes(eventName)) {
+			eventName = 'move'
+		}
+
+		this.root.dispatchEvent(
+			new CustomEvent('action', {
+				detail: {
+					eventName,
+					data
+				}
+			})
+		)
+	}
+}
+
+/**
+ * Navigator action for Svelte components
+ * @param {HTMLElement} root - The root element
+ * @param {Object} params - Parameters including wrapper and options
+ */
+export function navigator(root, { wrapper, options }) {
+	const controller = new NavigatorController(root, wrapper, options)
+
+	$effect(() => {
+		const cleanupFunctions = controller.init()
+		return () => {
+			cleanupFunctions.forEach((cleanup) => cleanup())
+		}
+	})
+}

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
+	}
+}