@rokkit/actions 1.0.0-next.36 → 1.0.0-next.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.36",
+  "version": "1.0.0-next.37",
   "description": "Contains generic actions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -13,17 +13,17 @@
     "access": "public"
   },
   "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^2.4.2",
+    "@sveltejs/vite-plugin-svelte": "^2.4.3",
     "@testing-library/svelte": "^4.0.3",
     "@vitest/coverage-v8": "^0.33.0",
     "@vitest/ui": "~0.33.0",
     "jsdom": "^22.1.0",
-    "svelte": "^4.0.5",
+    "svelte": "^4.1.1",
     "typescript": "^5.1.6",
     "validators": "latest",
-    "vite": "^4.4.4",
+    "vite": "^4.4.7",
     "vitest": "~0.33.0",
-    "shared-config": "1.0.0-next.36"
+    "shared-config": "1.0.0-next.37"
   },
   "files": [
     "src/**/*.js",

package/src/dismissable.js

@@ -1,5 +1,12 @@
 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) {
@@ -7,7 +14,9 @@ export function dismissable(node) {
 		}
 	}
 	const keyup = (event) => {
-		if (event.keyCode === KEYCODE_ESC) {
+		if (event.keyCode === KEYCODE_ESC || event.key === 'Escape') {
+			event.stopPropagation()
+
 			node.dispatchEvent(new CustomEvent('dismiss', node))
 		}
 	}

package/src/fillable.js

@@ -1,14 +1,8 @@
-/**
- * @typedef FillOptions
- * @property {Array<string>} options available options to fill
- * @property {integer} current       index of option to be filled
- * @property {boolean} check         validate filled values
- */
 /**
  * Action for filling a <del>?</del> element in html block.
  *
- * @param {*} node
- * @param {FillOptions} options
+ * @param {HTMLElement} node
+ * @param {import('./types').FillOptions} options
  * @returns
  */
 export function fillable(node, { options, current, check }) {
@@ -43,8 +37,8 @@ export function fillable(node, { options, current, check }) {
 /**
  * Initialize empty fillable element style and add listener for click
  *
- * @param {*} blanks
- * @param {*} click
+ * @param {HTMLCollection} blanks
+ * @param {EventListener} click
  */
 function initialize(blanks, click) {
 	Object.keys(blanks).map((ref) => {
@@ -58,8 +52,8 @@ function initialize(blanks, click) {
 /**
  * Fill current blank with provided option
  *
- * @param {*} blanks
- * @param {*} options
+ * @param {HTMLCollection} blanks
+ * @param {Array<import('./types.js').FillableData>} options
  * @param {*} current
  */
 function fill(blanks, options, current) {
@@ -76,8 +70,8 @@ function fill(blanks, options, current) {
 /**
  * Clear all fillable elements
  *
- * @param {*} event
- * @param {*} node
+ * @param {EventListener} event
+ * @param {HTMLElement} node
  */
 function clear(event, node) {
 	event.target.innerHTML = '?'
@@ -98,8 +92,8 @@ function clear(event, node) {
 /**
  * Validate the filled values
  *
- * @param {*} blanks
- * @param {*} data
+ * @param {HTMLCollection} blanks
+ * @param {import('./types').FillOptions} data
  */
 function validate(blanks, data) {
 	Object.keys(blanks).map((ref) => {

package/src/hierarchy.js

@@ -1,17 +1,8 @@
-/**
- * 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('../constants').FieldMapping} fields - Field mapping for the data
- */
-
 /**
  * Check if the current item is a parent
  *
  * @param {*} item
- * @param {import('../constants').FieldMapping} fields
+ * @param {import('@rokkit/core').FieldMapping} fields
  * @returns {boolean}
  */
 export function hasChildren(item, fields) {
@@ -26,7 +17,7 @@ export function hasChildren(item, fields) {
  * Check if the current item is a parent and is expanded
  *
  * @param {*} item
- * @param {import('../constants').FieldMapping} fields
+ * @param {import('@rokkit/core').FieldMapping} fields
  * @returns {boolean}
  */
 export function isExpanded(item, fields) {
@@ -42,7 +33,7 @@ export function isExpanded(item, fields) {
  * Verify if at least one item has children
  *
  * @param {Array<*>} items
- * @param {import('../constants').FieldMapping} fields
+ * @param {import('@rokkit/core').FieldMapping} fields
  * @returns {boolean}
  */
 export function isNested(items, fields) {
@@ -55,7 +46,7 @@ export function isNested(items, fields) {
 /**
  * Navigate to last visible child in the hirarchy starting with the provided path
  *
- * @param {Array<PathFragment>} path - path to a node in the hierarchy
+ * @param {Array<import('./types').PathFragment>} path - path to a node in the hierarchy
  * @returns
  */
 export function navigateToLastVisibleChild(path) {
@@ -78,9 +69,9 @@ export function navigateToLastVisibleChild(path) {
 /**
  * Navigate to the next item
  *
- * @param {Array<PathFragment>}                 path  - path to a node in the hierarchy
+ * @param {Array<import('./types').PathFragment>}                 path  - path to a node in the hierarchy
  * @param {Array<*>}                            items - array of items
- * @param {import('../constants').FieldMapping} fields - field mapping
+ * @param {import('@rokkit/core').FieldMapping} fields - field mapping
  * @returns
  */
 export function moveNext(path, items, fields) {
@@ -115,7 +106,7 @@ export function moveNext(path, items, fields) {
 /**
  * Navigate to the previous item
  *
- * @param {Array<PathFragment>} path  - path to a node in the hierarchy
+ * @param {Array<import('./types').PathFragment>} path  - path to a node in the hierarchy
  * @returns
  */
 export function movePrevious(path) {
@@ -139,7 +130,7 @@ export function movePrevious(path) {
  *
  * @param {Array<integer>} indices
  * @param {Array<*>} items
- * @param {import('../constants').FieldMapping} fields
+ * @param {import('@rokkit/core').FieldMapping} fields
  * @returns
  */
 export function pathFromIndices(indices, items, fields) {
@@ -160,15 +151,34 @@ export function pathFromIndices(indices, items, fields) {
 	return path
 }
 
+/**
+ * Get the indices from the path
+ * @param {Array<import('./types').PathFragment>} path
+ * @returns {Array<integer>}
+ */
 export function indicesFromPath(path) {
 	return path.map(({ index }) => index)
 }
+
+/**
+ * Get the current node from the path
+ * @param {Array<import('./types').PathFragment>} path
+ * @returns {*}
+ */
 export function getCurrentNode(path) {
 	if (path.length === 0) return null
 	const lastIndex = path.length - 1
 	return path[lastIndex].items[path[lastIndex].index]
 }
 
+/**
+ * Find the item in the hierarchy using the indices
+ *
+ * @param {Array<*>} items
+ * @param {Array<integer>} indices
+ * @param {import('@rokkit/core').FieldMapping} fields
+ * @returns {*}
+ */
 export function findItem(items, indices, fields) {
 	let item = items[indices[0]]
 	let levelFields = fields

package/src/index.js

@@ -1,3 +1,4 @@
+import './types'
 export { fillable } from './fillable'
 export { pannable } from './pannable'
 export { navigable } from './navigable'

package/src/navigable.js

@@ -1,3 +1,10 @@
+/**
+ * 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,
 	{ horizontal = true, nested = false, enabled = true } = {}

package/src/navigator.js

@@ -1,4 +1,4 @@
-import { getId } from '@rokkit/core'
+// import { tick } from 'svelte'
 import {
 	moveNext,
 	movePrevious,
@@ -6,82 +6,67 @@ import {
 	hasChildren,
 	pathFromIndices,
 	indicesFromPath,
-	getCurrentNode
+	getCurrentNode,
+	isExpanded
 } from './hierarchy'
 
-/**
- * @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
- */
-
 /**
  * Keyboard navigation for Lists and NestedLists. The data is either nested or not and is not
  * expected to switch from nested to simple list or vice-versa.
  *
- * @param {HTMLElement}      node    - The node on which the action is to be used on
- * @param {NavigatorOptions} options - Configuration options for the action
+ * @param {HTMLElement}                        element - Root element for the actionn
+ * @param {import('./types').NavigatorOptions} options - Configuration options for the action
  * @returns
  */
-export function navigator(node, options) {
+export function navigator(element, options) {
 	const { fields, enabled = true, vertical = true, idPrefix = 'id-' } = options
 	let items, path, currentNode
 
 	if (!enabled) return { destroy: () => {} }
 
+	// todo: Update should handle selection value change
+	// should we wait a tick before updating?
 	const update = (options) => {
+		const previousNode = currentNode
 		items = options.items
 		path = pathFromIndices(options.indices ?? [], items, fields)
 		currentNode = getCurrentNode(path)
+
+		if (previousNode !== currentNode && currentNode) {
+			const indices = indicesFromPath(path)
+			let current = element.querySelector('#' + idPrefix + indices.join('-'))
+			if (current) {
+				current.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
+			}
+		}
 	}
 
 	const next = () => {
 		const previousNode = currentNode
 		path = moveNext(path, items, fields)
 		currentNode = getCurrentNode(path)
-
 		if (previousNode !== currentNode)
-			moveTo(node, path, currentNode, idPrefix, fields)
+			moveTo(element, path, currentNode, idPrefix)
 	}
+
 	const previous = () => {
 		const previousNode = currentNode
 		path = movePrevious(path)
 		if (path.length > 0) {
 			currentNode = getCurrentNode(path)
 			if (previousNode !== currentNode)
-				moveTo(node, path, currentNode, idPrefix, fields)
+				moveTo(element, path, currentNode, idPrefix)
 		}
 	}
 	const select = () => {
-		if (currentNode)
-			node.dispatchEvent(
-				new CustomEvent('select', {
-					detail: {
-						path: indicesFromPath(path),
-						node: currentNode,
-						id: getId(currentNode, fields)
-					}
-				})
-			)
+		if (currentNode) emit('select', element, indicesFromPath(path), currentNode)
 	}
 	const collapse = () => {
 		if (currentNode) {
-			const collapse =
-				hasChildren(currentNode, path[path.length - 1].fields) &&
-				currentNode[path[path.length - 1].fields.isOpen]
+			const collapse = isExpanded(currentNode, path[path.length - 1].fields)
 			if (collapse) {
 				currentNode[path[path.length - 1].fields.isOpen] = false
-				node.dispatchEvent(
-					new CustomEvent('collapse', {
-						detail: {
-							path: indicesFromPath(path),
-							node: currentNode,
-							id: getId(currentNode, fields)
-						}
-					})
-				)
+				emit('collapse', element, indicesFromPath(path), currentNode)
 			} else if (path.length > 0) {
 				path = path.slice(0, -1)
 				currentNode = getCurrentNode(path)
@@ -92,15 +77,7 @@ export function navigator(node, options) {
 	const expand = () => {
 		if (currentNode && hasChildren(currentNode, path[path.length - 1].fields)) {
 			currentNode[path[path.length - 1].fields.isOpen] = true
-			node.dispatchEvent(
-				new CustomEvent('expand', {
-					detail: {
-						path: indicesFromPath(path),
-						node: currentNode,
-						id: getId(currentNode, fields)
-					}
-				})
-			)
+			emit('expand', element, indicesFromPath(path), currentNode)
 		}
 	}
 
@@ -126,7 +103,7 @@ export function navigator(node, options) {
 	}
 
 	const handleClick = (event) => {
-		let target = findParentWithDataPath(event.target)
+		let target = findParentWithDataPath(event.target, element)
 		let indices = !target
 			? []
 			: target.dataset.path
@@ -143,65 +120,72 @@ export function navigator(node, options) {
 				const event = currentNode[path[path.length - 1].fields.isOpen]
 					? 'expand'
 					: 'collapse'
-				node.dispatchEvent(
-					new CustomEvent(event, {
-						detail: {
-							path: indices,
-							node: currentNode,
-							id: getId(currentNode, fields)
-						}
-					})
-				)
-			}
-			node.dispatchEvent(
-				new CustomEvent('select', {
-					detail: {
-						path: indices,
-						node: currentNode,
-						id: getId(currentNode, fields)
-					}
-				})
-			)
+				emit(event, element, indices, currentNode)
+			} else if (currentNode) emit('select', element, indices, currentNode)
 		}
 	}
 
-	node.addEventListener('keydown', handleKeyDown)
-	node.addEventListener('click', handleClick)
+	element.addEventListener('keydown', handleKeyDown)
+	element.addEventListener('click', handleClick)
 
 	return {
 		update,
 		destroy() {
-			node.removeEventListener('keydown', handleKeyDown)
-			node.removeEventListener('click', handleClick)
+			element.removeEventListener('keydown', handleKeyDown)
+			element.removeEventListener('click', handleClick)
 		}
 	}
 }
 
-export function moveTo(node, path, currentNode, idPrefix, fields) {
+/**
+ * Move to the element with the given path
+ *
+ * @param {HTMLElement} element
+ * @param {*} path
+ * @param {*} currentNode
+ * @param {*} idPrefix
+ */
+export function moveTo(element, path, currentNode, idPrefix) {
 	const indices = indicesFromPath(path)
-
-	let current = node.querySelector('#' + idPrefix + indices.join('-'))
+	let current = element.querySelector('#' + idPrefix + indices.join('-'))
 	if (current) current.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
 
-	const id = getId(currentNode, fields)
-	node.dispatchEvent(
-		new CustomEvent('move', {
-			detail: {
-				path: indices,
-				node: currentNode,
-				id
-			}
-		})
-	)
+	emit('move', element, indices, currentNode)
 }
 
-export function findParentWithDataPath(element) {
+/**
+ * Find the parent element with data-path attribute
+ *
+ * @param {HTMLElement} element
+ * @param {HTMLElement} root
+ * @returns {HTMLElement}
+ */
+export function findParentWithDataPath(element, root) {
 	if (element.hasAttribute('data-path')) return element
 	let parent = element.parentNode
 
-	while (parent && !parent.hasAttribute('data-path')) {
+	while (parent && parent !== root && !parent.hasAttribute('data-path')) {
 		parent = parent.parentNode
 	}
 
-	return parent
+	return parent !== root ? parent : null
+}
+
+/**
+ * Emit a custom event on the element with the path and node as detail
+ *
+ * @param {string} event
+ * @param {HTMLElement} element
+ * @param {Array<integer>} indices
+ * @param {*} node
+ */
+function emit(event, element, indices, node) {
+	element.dispatchEvent(
+		new CustomEvent(event, {
+			detail: {
+				path: indices,
+				node: node
+			}
+		})
+	)
 }

package/src/pannable.js

@@ -1,9 +1,8 @@
-// pannable.js
 /**
  * Handle drag and move events
  *
- * @param {*} node
- * @returns
+ * @param {HTMLElement} node
+ * @returns {import('./types').SvelteActionReturn}
  */
 export function pannable(node) {
 	let x

package/src/swipeable.js

@@ -1,3 +1,11 @@
+/**
+ * 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,
 	{

package/src/themeable.js

@@ -1,7 +1,7 @@
 import { theme } from '@rokkit/stores'
 
 /**
- * Sets theme level classes based on the theme store
+ * A svelte action function that adds theme classes to the element
  *
  * @param {HTMLElement} node
  */
@@ -16,6 +16,14 @@ export function themable(node) {
 	})
 }
 
+/**
+ * Switch the class on the node
+ *
+ * @param {HTMLElement} node
+ * @param {string} current
+ * @param {string} previous
+ * @returns
+ */
 function switchClass(node, current, previous) {
 	if (current && current !== previous) {
 		node.classList.remove(previous)

package/src/types.js

@@ -0,0 +1,53 @@
+/**
+ * @typedef SvelteActionReturn
+ * @property {() => void} destroy
+ * @property {() => void} [update]
+ */
+
+/**
+ * @typedef FillableData
+ * @property {string} value
+ * @property {integer} actualIndex
+ * @property {integer} expectedIndex
+ */
+
+/**
+ * @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
+ */