@rokkit/actions 1.0.0-next.100 → 1.0.0-next.101

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Jerry Thomas
+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

package/README.md

@@ -1 +1,57 @@
-# Core Components
+# Actions
+
+This package provides a set of actions that can be used to perform various tasks.
+
+## Keyboard
+
+The keyboard action can be used to map keyboard events to actions. The following example shows how to map the `K` key combination to an action:
+
+The default behavior is to listen to keyup events.
+
+- [x] Configuration driven
+- [x] Custom events can be defined
+- [x] Supports mapping an array of keys to an event
+- [x] Supports mapping a regex to an event
+- [ ] Support key modifiers
+- [ ] Support a combination of regex patterns and array of keys
+
+Default configuration
+
+- _add_: alphabet keys cause an `add` event
+- _submit_: enter causes a `submit` event
+- _cancel_: escape causes a `cancel` event
+- _delete_: backspace or delete causes a `delete` event
+
+### Basic Usage
+
+```svelte
+<script>
+  import { keyboard } from '@fumbl/actions'
+
+  function handleKey(event) {
+    console.log(`${event.detail} pressed`)
+  }
+</script>
+
+<div use:keyboard onadd={handleKey}></div>
+```
+
+### Custom Events
+
+```svelte
+<script>
+  import { keyboard } from '@fumbl/actions'
+  function handleKey(event) {
+    console.log(`${event.detail} pressed`)
+  }
+
+  const config = {
+    add: ['a', 'b', 'c'],
+    submit: 'enter',
+    cancel: 'escape',
+    delete: ['backspace', 'delete']
+  }
+</script>
+
+<div use:keyboard={config} onadd={handleKey}></div>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.100",
+  "version": "1.0.0-next.101",
   "description": "Contains generic actions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -11,20 +11,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^3.1.2",
-    "@testing-library/svelte": "^5.2.1",
-    "@types/ramda": "^0.30.2",
-    "@vitest/coverage-v8": "^2.1.1",
-    "@vitest/ui": "~2.1.1",
-    "jsdom": "^25.0.0",
-    "svelte": "^4.2.19",
-    "typescript": "^5.6.2",
-    "vite": "^5.4.6",
-    "vitest": "~2.1.1",
-    "shared-config": "1.0.0-next.100",
-    "validators": "1.0.0-next.100"
-  },
   "files": [
     "src/**/*.js",
     "src/**/*.svelte"
@@ -39,18 +25,13 @@
     }
   },
   "dependencies": {
-    "ramda": "^0.30.1",
-    "@rokkit/core": "1.0.0-next.100",
-    "@rokkit/stores": "1.0.0-next.100"
+    "ramda": "^0.30.1"
+  },
+  "devDependencies": {
+    "@rokkit/helpers": "1.0.0-next.101"
   },
   "scripts": {
-    "format": "prettier --write .",
-    "lint": "eslint --fix .",
-    "test:ci": "vitest run",
-    "test:ui": "vitest --ui",
-    "test": "vitest",
-    "coverage": "vitest run --coverage",
-    "latest": "pnpm upgrade --latest && pnpm test:ci",
-    "release": "pnpm publish --access public"
+    "clean": "rm -rf dist",
+    "build": "pnpm clean && pnpm prepublishOnly"
   }
 }

package/src/index.js

@@ -1,13 +1,3 @@
 // skipcq: JS-E1004 - Needed for exposing all types
-export * from './types'
-// skipcq: JS-E1004 - Needed for exposing collection of functions
-export * from './lib'
-export { fillable } from './fillable'
-export { pannable } from './pannable'
-export { navigable } from './navigable'
-export { navigator } from './navigator'
-export { dismissable } from './dismissable'
-export { themable } from './themeable'
-export { swipeable } from './swipeable'
-export { switchable } from './switchable'
-export { delegateKeyboardEvents } from './delegate'
+export * from './types.js'
+export { keyboard } from './keyboard.svelte.js'

package/src/keyboard.svelte.js

@@ -0,0 +1,58 @@
+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 = defaultKeyMappings) {
+	const keyMappings = options || defaultKeyMappings
+
+	/**
+	 * Handle keyboard events
+	 *
+	 * @param {KeyboardEvent} event
+	 */
+	const keyup = (event) => {
+		const { key } = event
+		const eventName = getEventForKey(keyMappings, key)
+
+		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(document, 'keyup', keyup)
+		const cleanupClickEvent = on(root, 'click', click)
+		return () => {
+			cleanupKeyupEvent()
+			cleanupClickEvent()
+		}
+	})
+}

package/src/types.js

@@ -1,132 +1,10 @@
 /**
- * @typedef SvelteActionReturn
- * @property {() => void} destroy
- * @property {() => void} [update]
+ * @typedef {Object} EventMapping
+ * @property {string} event     - The event name
+ * @property {string[]} [keys]  - The keys that trigger the event
+ * @property {RegExp} [pattern] - The pattern that triggers the event
  */
 
 /**
- * @typedef FillableData
- * @property {string} value
- * @property {integer} actualIndex
- * @property {integer} expectedIndex
+ * @typedef {Object<string, (string[]|RegExp) >} KeyboardConfig
  */
-
-/**
- * @typedef FillOptions
- * @property {Array<FillableData>} options available options to fill
- * @property {integer} current       index of option to be filled
- * @property {boolean} check         validate filled values
- */
-
-/**
- * A part of the path to node in hierarchy
- *
- * @typedef PathFragment
- * @property {integer}                             index  - Index to item in array
- * @property {Array<*>}                            items  - Array of items
- * @property {import('@rokkit/core').FieldMapping} fields - Field mapping for the data
- */
-
-/**
- * Options for the Navigable action
- * @typedef NavigableOptions
- * @property {boolean} horizontal - Navigate horizontally
- * @property {boolean} nested     - Navigate nested items
- * @property {boolean} enabled    - Enable navigation
- */
-
-/**
- * @typedef NavigatorOptions
- * @property {Array<*>}     items           - An array containing the data set to navigate
- * @property {boolean}      [vertical=true] - Identifies whether navigation shoud be vertical or horizontal
- * @property {string}       [idPrefix='id-'] - id prefix used for identifying individual node
- * @property {import('../constants').FieldMapping} fields - Field mapping to identify attributes to be used for state and identification of children
- */
-
-/**
- * @typedef SwipeableOptions
- * @property {boolean} horizontal - Swipe horizontally
- * @property {boolean} vertical   - Swipe vertically
- * @property {boolean} enabled    - Enable swiping
- * @property {number}  threshold  - Threshold for swipe
- * @property {number}  minSpeed   - Minimum speed for swipe
- */
-
-/**
- * @typedef TraversableOptions
- * @property {boolean} horizontal - Traverse horizontally
- * @property {boolean} nested     - Traverse nested items
- * @property {boolean} enabled    - Enable traversal
- * @property {string}  value      - Value to be used for traversal
- * @property {Array<*>} items     - An array containing the data set to traverse
- * @property {Array<integer} [indices] - Indices of the items to be traversed
- */
-
-/**
- * @typedef PositionTracker
- * @property {integer} index
- * @property {integer} previousIndex
- */
-
-/**
- * @typedef EventHandlers
- * @property {function} [keydown]
- * @property {function} [keyup]
- * @property {function} [click]
- * @property {function} [touchstart]
- * @property {function} [touchmove]
- * @property {function} [touchend]
- * @property {function} [touchcancel]
- * @property {function} [mousedown]
- * @property {function} [mouseup]
- * @property {function} [mousemove]
- */
-
-/**
- * @typedef {Object} ActionHandlers
- * @property {Function} [next]
- * @property {Function} [previous]
- * @property {Function} [select]
- * @property {Function} [escape]
- * @property {Function} [collapse]
- * @property {Function} [expand]
- */
-
-/**
- * @typedef {Object} NavigationOptions
- * @property {Boolean} [horizontal]
- * @property {Boolean} [nested]
- * @property {Boolean} [enabled]
- */
-
-/**
- * @typedef {Object} KeyboardActions
- * @property {Function} [ArrowDown]
- * @property {Function} [ArrowUp]
- * @property {Function} [ArrowRight]
- * @property {Function} [ArrowLeft]
- * @property {Function} [Enter]
- * @property {Function} [Escape]
- * @property {Function} [" "]
- */
-
-/**
- * @typedef {Object} TouchTracker
- * @property {number} startX - The start X position of the touch.
- * @property {number} startY - The start Y position of the touch.
- * @property {number} startTime - The start time of the touch.
- */
-
-/**
- * @typedef {Object} PushDownOptions
- * @property {string} selector - The CSS selector for the child element to which keyboard events will be forwarded.
- * @property {Array<string>} [events=['keydown', 'keyup', 'keypress']] - The keyboard events to forward.
- */
-
-/**
- * @typedef {Object} Bounds
- * @property {number} lower
- * @property {number} upper
- */
-
-export default {}

package/src/utils.js

@@ -1,24 +1,28 @@
-export function handleAction(actions, event) {
-	if (event.key in actions) {
-		event.preventDefault()
-		event.stopPropagation()
-		actions[event.key]()
-	}
+/**
+ * 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)
 }
 
-export function getKeyboardActions(node, options, handlers) {
-	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
-	}
+import * as R from 'ramda'
+
+/**
+ * Get the event name for a given key.
+ * @param {import('./types.js').KeyboardConfig} keyMapping
+ * @param {string} key - The key to match.
+ * @returns {string|null} - The event name or null if no match is found.
+ */
+export const getEventForKey = (keyMapping, key) => {
+	const matchEvent = ([eventName, keys]) =>
+		(Array.isArray(keys) && keys.includes(key)) || (keys instanceof RegExp && keys.test(key))
+
+	const event = R.find(matchEvent, R.toPairs(keyMapping))
+	return event ? event[0] : null
 }

package/src/delegate.js

@@ -1,34 +0,0 @@
-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.
- * The action returns an object with a destroy method.
- * The destroy method removes all event listeners from the parent.
- *
- * @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))
-	}
-
-	if (child) {
-		events.forEach((event) => (handlers[event] = forwardEvent))
-		manager.update(handlers)
-	}
-
-	return {
-		destroy: () => manager.reset()
-	}
-}

package/src/dismissable.js

@@ -1,33 +0,0 @@
-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
- * @returns {import('./types').SvelteActionReturn}
- */
-export function dismissable(node) {
-	const handleClick = (event) => {
-		if (node && !node.contains(event.target) && !event.defaultPrevented) {
-			node.dispatchEvent(new CustomEvent('dismiss', node))
-		}
-	}
-	const keyup = (event) => {
-		if (event.keyCode === KEYCODE_ESC || event.key === 'Escape') {
-			event.stopPropagation()
-
-			node.dispatchEvent(new CustomEvent('dismiss', node))
-		}
-	}
-
-	document.addEventListener('click', handleClick, true)
-	document.addEventListener('keyup', keyup, true)
-
-	return {
-		destroy() {
-			document.removeEventListener('click', handleClick, true)
-			document.removeEventListener('keyup', keyup, true)
-		}
-	}
-}

package/src/fillable.js

@@ -1,106 +0,0 @@
-/**
- * Action for filling a <del>?</del> element in html block.
- *
- * @param {HTMLElement} node
- * @param {import('./types').FillOptions} options
- * @returns
- */
-export function fillable(node, { options, current, check }) {
-	const data = { options, current, check }
-	const blanks = node.getElementsByTagName('del')
-
-	function click(event) {
-		if (event.target.innerHTML !== '?') {
-			clear(event, node)
-		}
-	}
-
-	initialize(blanks, click)
-
-	return {
-		update(input) {
-			data.options = input.options
-			data.current = input.current
-			data.check = check
-
-			fill(blanks, data.options, data.current)
-			if (data.check) validate(blanks, data)
-		},
-		destroy() {
-			Object.keys(blanks).forEach((ref) => {
-				blanks[ref].removeEventListener('click', click)
-			})
-		}
-	}
-}
-
-/**
- * Initialize empty fillable element style and add listener for click
- *
- * @param {HTMLCollection} blanks
- * @param {EventListener} click
- */
-function initialize(blanks, click) {
-	Object.keys(blanks).forEach((ref) => {
-		blanks[ref].addEventListener('click', click)
-		blanks[ref].classList.add('empty')
-		blanks[ref].name = `fill-${ref}`
-		blanks[ref]['data-index'] = ref
-	})
-}
-
-/**
- * Fill current blank with provided option
- *
- * @param {HTMLCollection} blanks
- * @param {Array<import('./types.js').FillableData>} options
- * @param {*} current
- */
-function fill(blanks, options, current) {
-	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')
-		}
-	}
-}
-
-/**
- * Clear all fillable elements
- *
- * @param {EventListener} event
- * @param {HTMLElement} node
- */
-function clear(event, node) {
-	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.name.split('-')[1],
-				value: event.target['data-index']
-			}
-		})
-	)
-}
-
-/**
- * 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'
-			)
-	})
-}