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

package/package.json

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

package/src/navigator.old.svelte.js

@@ -0,0 +1,260 @@
+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/navigator.svelte.js

@@ -1,98 +1,106 @@
 import { on } from 'svelte/events'
-import { getClosestAncestorWithAttribute, getEventForKey } from './utils.js'
-import { getPathFromKey } from '@rokkit/core'
+import { omit } from 'ramda'
+import { getClickAction, getKeyboardAction, getPathFromEvent } from './utils'
 
-const Horizontal = {
-	prev: ['ArrowLeft'],
-	next: ['ArrowRight'],
-	collapse: ['ArrowUp'],
-	expand: ['ArrowDown'],
-	select: ['Enter']
-}
+const defaultOptions = { horizontal: false, nested: false, enabled: true }
 
-const Vertical = {
-	prev: ['ArrowUp'],
-	next: ['ArrowDown'],
-	collapse: ['ArrowLeft'],
-	expand: ['ArrowRight'],
-	select: ['Enter']
+const EVENT_MAP = {
+	first: ['move'],
+	last: ['move'],
+	previous: ['move'],
+	next: ['move'],
+	select: ['move', 'select'],
+	extend: ['move', 'select'],
+	collapse: ['toggle'],
+	expand: ['toggle'],
+	toggle: ['toggle']
 }
 
 /**
- * Get actions for the navigator
+ * The last only indicates that if there is an array only the last event is fired.
+ * This is crucial because a click event needs to fire both move and select,
+ * however the keyboard should only fire the select event because we are already
+ * on the current item
  *
- * @param {import('./types.js').DataWrapper} wrapper - The navigator wrapper
- * @param {HTMLElement} root - The root element
- * @returns {import('./types.js').NavigatorActions} - The navigator actions
+ * @param {HTMLElement} root
+ * @param {*} controller
+ * @param {*} name
  */
-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
+export function emitAction(root, controller, name, lastOnly = false) {
+	const events = lastOnly ? EVENT_MAP[name].slice(-1) : EVENT_MAP[name]
+
+	events.forEach((event) => {
+		root.dispatchEvent(
+			new CustomEvent('action', {
+				detail: {
+					name: event,
+					data: { value: controller.focused, selected: controller.selected }
+				}
+			})
+		)
+	})
 }
 
-function handleIconClick(target, wrapper) {
-	const isIcon = target.tagName.toLowerCase() === 'rk-icon'
-	const state = isIcon ? target.getAttribute('data-state') : null
+/*
+ * Generic action handler for keyboard events.
+ *
+ * @param {Record<string, () => void>} actions
+ * @param {KeyboardEvent} event
+ */
+export function handleAction(event, handler, path) {
+	if (handler) {
+		event.preventDefault()
+		event.stopPropagation()
 
-	if (state === 'closed') {
-		wrapper.expand()
-	} else if (state === 'opened') {
-		wrapper.collapse()
+		return handler(path)
 	}
-	return ['closed', 'opened'].includes(state)
+	return false
 }
 
+function getHandlers(wrapper) {
+	return {
+		first: () => wrapper.moveFirst(),
+		last: () => wrapper.moveLast(),
+		previous: () => wrapper.movePrev(),
+		next: () => wrapper.moveNext(),
+		collapse: () => wrapper.collapse(),
+		expand: () => wrapper.expand(),
+		select: (path) => wrapper.select(path),
+		extend: (path) => wrapper.extendSelection(path),
+		toggle: (path) => wrapper.toggleExpansion(path)
+	}
+}
 /**
- * Handle keyboard events
+ * A svelte action function that captures keyboard evvents and emits event for corresponding movements.
  *
- * @param {HTMLElement} root
- * @param {import('./types.js').NavigatorConfig} options - Custom key mappings
+ * @param {HTMLElement} node
+ * @param {import('./types').NavigableOptions} options
+ * @returns {import('./types').SvelteActionReturn}
  */
-export function navigator(root, { wrapper, options }) {
-	const keyMappings = options?.direction === 'horizontal' ? Horizontal : Vertical
-	const actions = getActions(wrapper, root)
+export function navigator(node, options) {
+	const { wrapper } = options
+	const config = { ...defaultOptions, ...omit(['wrapper'], options) }
+	const handlers = getHandlers(wrapper)
 
-	/**
-	 * Handle keyboard events
-	 *
-	 * @param {KeyboardEvent} event
-	 */
-	const keyup = (event) => {
-		const { key } = event
-
-		const eventName = getEventForKey(keyMappings, key)
-		if (eventName) {
-			actions[eventName]()
-		}
+	const handleKeydown = (event) => {
+		const action = getKeyboardAction(event, config)
+		const handled = handleAction(event, handlers[action])
+		if (handled) emitAction(node, options.wrapper, action, true)
 	}
 
-	const click = (event) => {
-		const node = getClosestAncestorWithAttribute(event.target, 'data-path')
+	const handleClick = (event) => {
+		const action = getClickAction(event)
+		const path = getPathFromEvent(event)
+		const handled = handleAction(event, handlers[action], 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()
-		}
+		if (handled) emitAction(node, options.wrapper, action)
 	}
 
 	$effect(() => {
-		const cleanupKeyupEvent = on(root, 'keyup', keyup)
-		const cleanupClickEvent = on(root, 'click', click)
+		const cleanup = [on(node, 'keyup', handleKeydown), on(node, 'click', handleClick)]
+
 		return () => {
-			cleanupKeyupEvent()
-			cleanupClickEvent()
+			cleanup.forEach((fn) => fn())
 		}
 	})
 }

package/src/types.js

@@ -48,3 +48,16 @@
  * @property {Navigator} wrapper     - Whether the navigator is enabled
  * @property {NavigatorOptions} options   - Whether the navigator is vertical or horizontal
  */
+
+/**
+ * @typedef {Object} Controller
+ * @property {Function} moveNext
+ * @property {Function} movePrev
+ * @property {Function} moveFirst
+ * @property {Function} moveLast
+ * @property {Function} [expand]
+ * @property {Function} [collapse]
+ * @property {Function} select
+ * @property {Function} extendSelection
+ * @property {Function} [toggleExpansion]
+ */

package/src/utils.js

@@ -49,20 +49,147 @@ export function handleAction(actions, event) {
  * @param {import('./types').NavigableHandlers} handlers
  */
 export function getKeyboardActions(options, handlers) {
+	const { horizontal, nested } = options
 	if (!options.enabled) return {}
 
-	const movement = options.horizontal
+	const common = {
+		Enter: handlers.select,
+		' ': handlers.select
+	}
+	const movement = 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 }
+	const change = horizontal
+		? { ArrowUp: handlers.collapse, ArrowDown: handlers.expand }
+		: { ArrowLeft: handlers.collapse, ArrowRight: handlers.expand }
+
+	if (nested) return { ...common, ...movement, ...change }
+	return { ...common, ...movement }
+}
+
+/**
+ * Finds and returns an index path based on data-path attribute
+ *
+ * @param {MouseEvent} event
+ * @returns {number[]|null} null or index path array
+ */
+export function getPathFromEvent(event) {
+	const node = getClosestAncestorWithAttribute(event.target, 'data-path')
+	return node?.getAttribute('data-path')
+	// return node ? getPathFromKey(node.getAttribute('data-path')) : null
+}
+
+/**
+ * Creates a keyboard action mapping based on navigation options
+ *
+ * @param {Object} options - Navigation options
+ * @param {boolean} options.horizontal - Whether navigation is horizontal
+ * @param {boolean} options.nested - Whether navigation is nested
+ * @returns {Object} Mapping of keys to actions
+ */
+function createKeyboardActionMap(options) {
+	const { horizontal, nested } = options
+
+	// Define movement actions based on horizontal option
+	const movementActions = horizontal
+		? { ArrowLeft: 'previous', ArrowRight: 'next' }
+		: { ArrowUp: 'previous', ArrowDown: 'next' }
+
+	// Define expand/collapse actions for nested option
+	const nestedActions = nested
+		? horizontal
+			? { ArrowUp: 'collapse', ArrowDown: 'expand' }
+			: { ArrowLeft: 'collapse', ArrowRight: 'expand' }
 		: {}
+
+	// Common actions regardless of options
+	const commonActions = {
+		Enter: 'select',
+		' ': 'select',
+		Home: 'first',
+		End: 'last'
+	}
+
+	// Combine all possible actions
 	return {
-		Enter: handlers.select,
-		' ': handlers.select,
-		...movement,
-		...change
+		...commonActions,
+		...movementActions,
+		...nestedActions
 	}
 }
+
+/**
+ * Creates a keyboard action mapping based on navigation options
+ *
+ * @param {Object} options - Navigation options
+ * @param {boolean} options.horizontal - Whether navigation is horizontal
+ * @param {boolean} options.nested - Whether navigation is nested
+ * @returns {Object} Mapping of keys to actions
+ */
+function createModifierKeyboardActionMap(options) {
+	const { horizontal } = options
+	const common = { ' ': 'extend', Home: 'first', End: 'last' }
+	const directional = horizontal
+		? { ArrowLeft: 'first', ArrowRight: 'last' }
+		: { ArrowUp: 'first', ArrowDown: 'last' }
+	return { ...common, ...directional }
+}
+/**
+ * Identifies if an element is a collapsible icon
+ * @param {HTMLElement} target
+ * @returns
+ */
+function isNodeToggle(target) {
+	return (
+		target &&
+		target.getAttribute('data-tag') === 'icon' &&
+		['closed', 'opened'].includes(target.getAttribute('data-state'))
+	)
+}
+/**
+ * Determines an action based on a keyboard event and navigation options
+ *
+ * @param {KeyboardEvent} event - The keyboard event
+ * @param {Object} options - Navigation options
+ * @param {boolean} options.horizontal - Whether navigation is horizontal
+ * @param {boolean} options.nested - Whether navigation is nested
+ * @returns {string|null} The determined action or null if no action matches
+ */
+export const getKeyboardAction = (event, options) => {
+	const { key, ctrlKey, metaKey } = event
+
+	// Check for modifier keys first (highest priority)
+	if (ctrlKey || metaKey) {
+		const modifierMap = createModifierKeyboardActionMap(options)
+		return modifierMap[key] || null
+	}
+
+	// Get the action map based on options
+	const actionMap = createKeyboardActionMap(options)
+
+	// Return the action or null if no matching key
+	return actionMap[key] || null
+}
+
+/**
+ * Determines an action based on a click event
+ *
+ * @param {MouseEvent} event - The click event
+ * @returns {string} The determined action
+ */
+export const getClickAction = (event) => {
+	const { ctrlKey, metaKey, target } = event
+
+	// Check for modifier keys first (highest priority)
+	if (ctrlKey || metaKey) {
+		return 'extend'
+	}
+
+	// Check if clicked on icon with collapsed/expanded state
+	if (isNodeToggle(target) || isNodeToggle(target.parentElement)) {
+		return 'toggle'
+	}
+
+	// Default action
+	return 'select'
+}