@rokkit/actions 1.0.0-next.99 → 1.0.2

package/src/kbd.js

@@ -0,0 +1,191 @@
+/**
+ * Gets horizontal movement actions based on text direction
+ * @param {Object} handlers - Handler functions
+ * @param {string} [dir='ltr'] - Text direction ('ltr' or 'rtl')
+ * @returns {Object} Object mapping arrow keys to movement handlers
+ */
+function getHorizontalMovementActions(handlers, dir = 'ltr') {
+	return dir === 'rtl'
+		? { ArrowRight: handlers.previous, ArrowLeft: handlers.next }
+		: { ArrowLeft: handlers.previous, ArrowRight: handlers.next }
+}
+
+/**
+ * Gets vertical movement actions (not affected by direction)
+ * @param {Object} handlers - Handler functions
+ * @returns {Object} Object mapping arrow keys to movement handlers
+ */
+function getVerticalMovementActions(handlers) {
+	return { ArrowUp: handlers.previous, ArrowDown: handlers.next }
+}
+
+/**
+ * Gets horizontal expand/collapse actions (not affected by direction)
+ * @param {Object} handlers - Handler functions
+ * @returns {Object} Object mapping arrow keys to expand/collapse handlers
+ */
+function getHorizontalExpandActions(handlers) {
+	return { ArrowUp: handlers.collapse, ArrowDown: handlers.expand }
+}
+
+/**
+ * Gets vertical expand/collapse actions based on text direction
+ * @param {Object} handlers - Handler functions
+ * @param {string} [dir='ltr'] - Text direction ('ltr' or 'rtl')
+ * @returns {Object} Object mapping arrow keys to expand/collapse handlers
+ */
+function getVerticalExpandActions(handlers, dir = 'ltr') {
+	return dir === 'rtl'
+		? { ArrowRight: handlers.collapse, ArrowLeft: handlers.expand }
+		: { ArrowLeft: handlers.collapse, ArrowRight: handlers.expand }
+}
+
+/**
+ * Gets common selection actions
+ * @param {Object} handlers - Handler functions
+ * @returns {Object} Object mapping keys to selection handlers
+ */
+function getCommonActions(handlers) {
+	return {
+		Enter: handlers.select,
+		' ': handlers.select
+	}
+}
+
+// Default navigation options
+export const defaultNavigationOptions = {
+	orientation: 'vertical',
+	dir: 'ltr',
+	nested: false,
+	enabled: true,
+	typeahead: false
+}
+
+/**
+ * Gets keyboard action handlers based on orientation and direction
+ * @param {Object} options - Configuration options
+ * @param {Object} handlers - Event handler functions
+ * @returns {Object} Object mapping key presses to handler functions
+ */
+export function getKeyboardActions(options, handlers) {
+	const { orientation, dir, nested, enabled } = { ...defaultNavigationOptions, ...options }
+
+	if (!enabled) return {}
+
+	const common = getCommonActions(handlers)
+
+	// Determine movement actions based on orientation
+	const isHorizontal = orientation === 'horizontal'
+	const movement = isHorizontal
+		? getHorizontalMovementActions(handlers, dir)
+		: getVerticalMovementActions(handlers)
+
+	// If not nested, we don't need expand/collapse actions
+	if (!nested) {
+		return { ...common, ...movement }
+	}
+
+	// Determine expand/collapse actions based on orientation
+	const expandCollapse = isHorizontal
+		? getHorizontalExpandActions(handlers)
+		: getVerticalExpandActions(handlers, dir)
+
+	return { ...common, ...movement, ...expandCollapse }
+}
+
+function buildHorizontalMovementMap(dir) {
+	return dir === 'rtl'
+		? { ArrowRight: 'previous', ArrowLeft: 'next' }
+		: { ArrowLeft: 'previous', ArrowRight: 'next' }
+}
+
+function buildVerticalNestedMap(dir) {
+	return dir === 'rtl'
+		? { ArrowRight: 'collapse', ArrowLeft: 'expand' }
+		: { ArrowLeft: 'collapse', ArrowRight: 'expand' }
+}
+
+function buildNestedActions(isHorizontal, dir) {
+	if (isHorizontal) return { ArrowUp: 'collapse', ArrowDown: 'expand' }
+	return buildVerticalNestedMap(dir)
+}
+
+/**
+ * Creates a keyboard action mapping based on navigation options
+ *
+ * @param {Object} options - Navigation options
+ * @param {string} options.orientation - Whether navigation is horizontal or vertical
+ * @param {string} options.dir - Text direction ('ltr' or 'rtl')
+ * @param {boolean} options.nested - Whether navigation is nested
+ * @returns {Object} Mapping of keys to actions
+ */
+export function createKeyboardActionMap(options) {
+	const { orientation, dir, nested } = options
+	const isHorizontal = orientation === 'horizontal'
+
+	const movementActions = isHorizontal
+		? buildHorizontalMovementMap(dir)
+		: { ArrowUp: 'previous', ArrowDown: 'next' }
+
+	const nestedActions = nested ? buildNestedActions(isHorizontal, dir) : {}
+
+	const commonActions = {
+		Enter: 'select',
+		' ': 'select',
+		Home: 'first',
+		End: 'last'
+	}
+
+	return { ...commonActions, ...movementActions, ...nestedActions }
+}
+
+/**
+ * Creates a keyboard action mapping for modifier keys based on navigation options
+ *
+ * @param {Object} options - Navigation options
+ * @param {string} options.orientation - Whether navigation is horizontal or vertical
+ * @returns {Object} Mapping of keys to actions
+ */
+export function createModifierKeyboardActionMap(options) {
+	const isHorizontal = options.orientation === 'horizontal'
+	const common = { ' ': 'extend', Home: 'first', End: 'last' }
+	const directional = isHorizontal
+		? { ArrowLeft: 'first', ArrowRight: 'last' }
+		: { ArrowUp: 'first', ArrowDown: 'last' }
+	return { ...common, ...directional }
+}
+
+/**
+ * Creates a keyboard action mapping for shift key combinations
+ *
+ * @returns {Object} Mapping of keys to actions
+ */
+export function createShiftKeyboardActionMap() {
+	return { ' ': 'range' }
+}
+
+const KEY_LAYER_RESOLVERS = {
+	shift: (key, _opts) => createShiftKeyboardActionMap()[key] || null,
+	modifier: (key, opts) => createModifierKeyboardActionMap(opts)[key] || null,
+	plain: (key, opts) => createKeyboardActionMap(opts)[key] || null
+}
+
+function getKeyLayer(ctrlKey, metaKey, shiftKey) {
+	if (ctrlKey) return 'modifier'
+	if (metaKey) return 'modifier'
+	if (shiftKey) return 'shift'
+	return 'plain'
+}
+
+/**
+ * Gets the keyboard action for a key event
+ * @param {KeyboardEvent} event - The keyboard event
+ * @param {Object} options - Configuration options
+ * @returns {string|null} The action to perform, or null if no action is defined
+ */
+export function getKeyboardAction(event, options = {}) {
+	const { key, ctrlKey, metaKey, shiftKey } = event
+	const mergedOptions = { ...defaultNavigationOptions, ...options }
+	const layer = getKeyLayer(ctrlKey, metaKey, shiftKey)
+	return KEY_LAYER_RESOLVERS[layer](key, mergedOptions)
+}

package/src/keyboard.svelte.js

@@ -0,0 +1,59 @@
+import { on } from 'svelte/events'
+import { getClosestAncestorWithAttribute, getEventForKey } from './utils.js'
+
+/**
+ * Default key mappings
+ * @type {import('./types.js').KeyboardConfig}
+ */
+const defaultKeyMappings = {
+	remove: ['Backspace', 'Delete'],
+	submit: ['Enter'],
+	add: /^[a-zA-Z]$/
+}
+
+/**
+ * Handle keyboard events
+ *
+ * @param {HTMLElement} root
+ * @param {import('./types.js').KeyboardConfig} options - Custom key mappings
+ */
+export function keyboard(root, options = null) {
+	const keyMappings = options ?? defaultKeyMappings
+
+	/**
+	 * Handle keyboard events
+	 *
+	 * @param {KeyboardEvent} event
+	 */
+	const keyup = (event) => {
+		const { key } = event
+
+		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 }))
+		}
+	}
+
+	const click = (event) => {
+		const node = getClosestAncestorWithAttribute(event.target, 'data-key')
+
+		if (node) {
+			const key = node.getAttribute('data-key')
+			const eventName = getEventForKey(keyMappings, key)
+
+			if (eventName) {
+				root.dispatchEvent(new CustomEvent(eventName, { detail: key }))
+			}
+		}
+	}
+
+	$effect(() => {
+		const cleanupKeyupEvent = on(root, 'keyup', keyup)
+		const cleanupClickEvent = on(root, 'click', click)
+		return () => {
+			cleanupKeyupEvent()
+			cleanupClickEvent()
+		}
+	})
+}

package/src/keymap.js

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

package/src/lib/event-manager.js

@@ -1,3 +1,17 @@
+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.
  *
@@ -5,18 +19,19 @@
  * @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 = {}) {
-	let listening = false
+export function EventManager(element, handlers = {}, enabled = true) {
+	const registeredEvents = {}
+	const options = { handlers, enabled }
 
 	/**
 	 * Activate the event listeners.
 	 */
 	function activate() {
-		if (!listening) {
-			Object.entries(handlers).forEach(([event, handler]) =>
-				element.addEventListener(event, handler)
-			)
-			listening = true
+		if (options.enabled) {
+			Object.entries(options.handlers).forEach(([event, handler]) => {
+				resetEvent(event, registeredEvents)
+				registeredEvents[event] = on(element, event, handler)
+			})
 		}
 	}
 
@@ -24,12 +39,9 @@ export function EventManager(element, handlers = {}) {
 	 * Reset the event listeners.
 	 */
 	function reset() {
-		if (listening) {
-			Object.entries(handlers).forEach(([event, handler]) =>
-				element.removeEventListener(event, handler)
-			)
-			listening = false
-		}
+		Object.keys(registeredEvents).forEach((event) => {
+			resetEvent(event, registeredEvents)
+		})
 	}
 
 	/**
@@ -39,12 +51,17 @@ export function EventManager(element, handlers = {}) {
 	 * @param {boolean} enabled - Whether to enable or disable the event listeners.
 	 */
 	function update(newHandlers = handlers, enabled = true) {
-		if (listening !== enabled || handlers !== newHandlers) {
-			reset()
-			handlers = newHandlers
-			if (enabled) activate()
+		const hasChanged = handlers !== newHandlers
+
+		if (!enabled) reset()
+
+		if (hasChanged) {
+			options.handlers = newHandlers
+			options.enabled = enabled
+			activate()
 		}
 	}
 
-	return { activate, reset, update }
+	activate()
+	return { reset, update }
 }

package/src/lib/index.js

@@ -1,5 +1,3 @@
-export { dimensionAttributes, defaultResizerOptions, defaultVirtualListOptions } from './constants'
 // skipcq: JS-E1004 - Needed for exposing all functions
 export * from './internal'
 export { EventManager } from './event-manager'
-export { virtualListViewport } from './viewport'

package/src/lib/internal.js

@@ -1,58 +1,3 @@
-import { compact, hasChildren, isExpanded } from '@rokkit/core'
-
-/**
- * Emits a custom event with the given data.
- *
- * @param {HTMLElement} element
- * @param {string} event
- * @param {*} data
- * @returns {void}
- */
-export function emit(element, event, data) {
-	element.dispatchEvent(new CustomEvent(event, { detail: data }))
-}
-
-/**
- * Maps keyboard events to actions based on the given handlers and options.
- *
- * @param {import('../types').ActionHandlers} handlers
- * @param {import('../types').NavigationOptions} options
- * @returns {import('../types').KeyboardActions}
- */
-export function mapKeyboardEventsToActions(handlers, options) {
-	const { next, previous, select, escape } = handlers
-	const { horizontal, nested } = {
-		horizontal: false,
-		nested: false,
-		...options
-	}
-	const expand = nested ? handlers.expand : null
-	const collapse = nested ? handlers.collapse : null
-
-	return compact({
-		ArrowDown: horizontal ? expand : next,
-		ArrowUp: horizontal ? collapse : previous,
-		ArrowRight: horizontal ? next : expand,
-		ArrowLeft: horizontal ? previous : collapse,
-		Enter: select,
-		Escape: escape,
-		' ': select
-	})
-}
-
-/**
- * Finds the closest ancestor of the given element that has the given attribute.
- *
- * @param {HTMLElement} element
- * @param {string} attribute
- * @returns {HTMLElement|null}
- */
-export function getClosestAncestorWithAttribute(element, attribute) {
-	if (!element) return null
-	if (element.getAttribute(attribute)) return element
-	return getClosestAncestorWithAttribute(element.parentElement, attribute)
-}
-
 /**
  * Sets up event handlers based on the given options.
  * Returns whether or not the event handlers are listening.
@@ -86,100 +31,3 @@ export function removeListeners(element, listeners) {
 		})
 	}
 }
-
-/**
- * Handles the click event.
- * @param {HTMLElement} element - The root element.
- * @param {CurrentItem} current - A reference to the current Item
- * @returns {CurrentItem} The updated current item.
- */
-export function handleItemClick(element, current) {
-	const { item, fields, position } = current
-	const detail = { item, position }
-
-	if (hasChildren(item, fields)) {
-		if (isExpanded(item, fields)) {
-			item[fields.isOpen] = false
-			emit(element, 'collapse', detail)
-		} else {
-			item[fields.isOpen] = true
-			emit(element, 'expand', detail)
-		}
-	} else {
-		emit(element, 'select', detail)
-	}
-	return current
-}
-
-/**
- * Caclulates sum of array values between the given bounds.
- * If a value is null, the default size is used.
- *
- * @param {Array<number|null>} sizes
- * @param {number} lower
- * @param {number} upper
- * @param {number} [defaultSize]
- * @returns {number}
- */
-export function calculateSum(sizes, lower, upper, defaultSize = 40, gap = 0) {
-	return (
-		sizes
-			.slice(lower, upper)
-			.map((size) => size ?? defaultSize)
-			.reduce((acc, size) => acc + size + gap, 0) - gap
-	)
-}
-
-/**
- * Updates the sizes array with the given values.
- *
- * @param {Array<number|null>} sizes
- * @param {Array<number>} values
- * @param {number} [offset]
- * @returns {Array<number|null>}
- */
-export function updateSizes(sizes, values, offset = 0) {
-	const result = [...sizes.slice(0, offset), ...values, ...sizes.slice(offset + values.length)]
-
-	return result
-}
-
-/**
- * Adjusts the viewport to ensure that the bounds contain the given number of items.
- *
- * @param {import('../types').Bounds} current
- * @param {number} count
- * @param {number} visibleCount
- * @returns {import('../types').Bounds}
- */
-export function fixViewportForVisibileCount(current, count, visibleCount) {
-	let { lower, upper } = current
-	if (lower < 0) lower = 0
-	if (lower + visibleCount > count) {
-		upper = count
-		lower = Math.max(0, upper - visibleCount)
-	} else if (lower + visibleCount !== upper) {
-		upper = lower + visibleCount
-	}
-	return { lower, upper }
-}
-
-/**
- * Adjusts the viewport to ensure the given index is visible.
- *
- * @param {number} index
- * @param {import('../types').Bounds} current
- * @param {number} visibleCount
- * @returns {import('../types').Bounds}
- */
-export function fitIndexInViewport(index, current, visibleCount) {
-	let { lower, upper } = current
-	if (index >= upper) {
-		upper = index + 1
-		lower = upper - visibleCount
-	} else if (index < lower) {
-		lower = index
-		upper = lower + visibleCount
-	}
-	return { lower, upper }
-}

package/src/magnetic.svelte.js

@@ -0,0 +1,63 @@
+/**
+ * Magnetic action — element shifts subtly toward the cursor on hover.
+ * Calculates cursor offset from element center and translates proportionally.
+ *
+ * @param {HTMLElement} node
+ * @param {MagneticOptions} [options]
+ *
+ * @typedef {Object} MagneticOptions
+ * @property {number} [strength=0.3] Maximum displacement as fraction of element size (0–1)
+ * @property {number} [duration=300] Transition duration for return to center (ms)
+ */
+
+function resolveMagneticOpts(options) {
+	return { strength: 0.3, duration: 300, ...options }
+}
+
+function isReducedMotion() {
+	return (
+		typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+	)
+}
+
+function applyMagnetic(node, opts) {
+	const originalTransform = node.style.transform
+	const originalTransition = node.style.transition
+
+	node.style.transition = `transform ${opts.duration}ms ease`
+
+	function onMove(e) {
+		const rect = node.getBoundingClientRect()
+		const centerX = rect.left + rect.width / 2
+		const centerY = rect.top + rect.height / 2
+
+		const offsetX = (e.clientX - centerX) * opts.strength
+		const offsetY = (e.clientY - centerY) * opts.strength
+
+		node.style.transition = 'none'
+		node.style.transform = `translate(${offsetX}px, ${offsetY}px)`
+	}
+
+	function onLeave() {
+		node.style.transition = `transform ${opts.duration}ms ease`
+		node.style.transform = originalTransform
+	}
+
+	node.addEventListener('mousemove', onMove)
+	node.addEventListener('mouseleave', onLeave)
+
+	return () => {
+		node.removeEventListener('mousemove', onMove)
+		node.removeEventListener('mouseleave', onLeave)
+		node.style.transform = originalTransform
+		node.style.transition = originalTransition
+	}
+}
+
+export function magnetic(node, options = {}) {
+	$effect(() => {
+		const opts = resolveMagneticOpts(options)
+		if (isReducedMotion()) return
+		return applyMagnetic(node, opts)
+	})
+}