@rokkit/actions 1.0.0-next.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# Core Components

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@rokkit/actions",
+  "version": "1.0.0-next.100",
+  "description": "Contains generic actions that can be used in various components.",
+  "author": "Jerry Thomas <me@jerrythomas.name>",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "src/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "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"
+  ],
+  "exports": {
+    "./src": "./src",
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./src/index.js",
+      "svelte": "./src/index.js"
+    }
+  },
+  "dependencies": {
+    "ramda": "^0.30.1",
+    "@rokkit/core": "1.0.0-next.100",
+    "@rokkit/stores": "1.0.0-next.100"
+  },
+  "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"
+  }
+}

package/src/delegate.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.
+ * 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

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1,106 @@
+/**
+ * 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'
+			)
+	})
+}

package/src/hierarchy.js

@@ -0,0 +1,156 @@
+import { isExpanded } from '@rokkit/core'
+
+/**
+ * Navigate to last visible child in the hirarchy starting with the provided path
+ *
+ * @param {Array<import('./types').PathFragment>} path - path to a node in the hierarchy
+ * @returns
+ */
+export function navigateToLastVisibleChild(path) {
+	let current = path[path.length - 1]
+
+	while (isExpanded(current.items[current.index], current.fields)) {
+		const items = current.items[current.index][current.fields.children]
+		const level = {
+			items,
+			index: items.length - 1,
+			fields: current.fields.fields ?? current.fields
+		}
+		path.push(level)
+		current = level
+	}
+
+	return path
+}
+
+/**
+ * Navigate to the next item
+ *
+ * @param {Array<import('./types').PathFragment>}                 path  - path to a node in the hierarchy
+ * @param {Array<*>}                            items - array of items
+ * @param {import('@rokkit/core').FieldMapping} fields - field mapping
+ * @returns
+ */
+export function moveNext(path, items, fields) {
+	if (path.length === 0) {
+		return [{ index: 0, items, fields }]
+	}
+
+	const current = path[path.length - 1]
+	if (isExpanded(current.items[current.index], current.fields)) {
+		path.push({
+			items: current.items[current.index][current.fields.children],
+			index: 0,
+			fields: current.fields.fields || current.fields
+		})
+	} else if (current.index < current.items.length - 1) {
+		current.index++
+	} else {
+		path = navigateToNextLevel(path)
+	}
+	return path
+}
+
+/**
+ * Navigate to the next level
+ * @param {Array<import('./types').PathFragment>} path
+ * @returns {Array<import('./types').PathFragment>}
+ */
+function navigateToNextLevel(path) {
+	let level = path.length - 2
+	while (level >= 0) {
+		const parent = path[level]
+		if (parent.index < parent.items.length - 1) {
+			parent.index++
+			path = path.slice(0, level + 1)
+			break
+		}
+		level--
+	}
+	return path
+}
+/**
+ * Navigate to the previous item
+ *
+ * @param {Array<import('./types').PathFragment>} path  - path to a node in the hierarchy
+ * @returns
+ */
+export function movePrevious(path) {
+	if (path.length === 0) return []
+
+	const current = path[path.length - 1]
+
+	if (current.index === 0) {
+		if (path.length > 1) path.pop()
+		return path
+	}
+
+	current.index--
+	if (isExpanded(current.items[current.index], current.fields)) {
+		return navigateToLastVisibleChild(path)
+	}
+	return path
+}
+
+/**
+ *
+ * @param {Array<integer>} indices
+ * @param {Array<*>} items
+ * @param {import('@rokkit/core').FieldMapping} fields
+ * @returns
+ */
+export function pathFromIndices(indices, items, fields) {
+	const path = []
+	let fragment = {}
+	indices.forEach((index, level) => {
+		if (level === 0) {
+			fragment = { index, items, fields }
+		} else {
+			fragment = {
+				index,
+				items: fragment.items[fragment.index][fragment.fields.children],
+				fields: fragment.fields.fields ?? fragment.fields
+			}
+		}
+		path.push(fragment)
+	})
+	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
+	for (let level = 1; level < indices.length; level++) {
+		item = item[levelFields.children][indices[level]]
+		levelFields = levelFields.fields ?? levelFields
+	}
+	return item
+}

package/src/index.js

@@ -0,0 +1,13 @@
+// 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'

package/src/lib/constants.js

@@ -0,0 +1,35 @@
+export const dimensionAttributes = {
+	vertical: {
+		scroll: 'scrollTop',
+		offset: 'offsetHeight',
+		paddingStart: 'paddingTop',
+		paddingEnd: 'paddingBottom',
+		size: 'height'
+	},
+	horizontal: {
+		scroll: 'scrollLeft',
+		offset: 'offsetWidth',
+		paddingStart: 'paddingLeft',
+		paddingEnd: 'paddingRight',
+		size: 'width'
+	}
+}
+
+export const defaultResizerOptions = {
+	horizontal: false,
+	minSize: 40,
+	minVisible: 1,
+	maxVisible: null,
+	availableSize: 200,
+	start: 0
+}
+
+export const defaultVirtualListOptions = {
+	itemSelector: 'virtual-list-item',
+	contentSelector: 'virtual-list-content',
+	enabled: true,
+	horizontal: false,
+	start: 0,
+	limit: null,
+	index: null
+}

package/src/lib/event-manager.js

@@ -0,0 +1,50 @@
+/**
+ * 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 = {}) {
+	let listening = false
+
+	/**
+	 * Activate the event listeners.
+	 */
+	function activate() {
+		if (!listening) {
+			Object.entries(handlers).forEach(([event, handler]) =>
+				element.addEventListener(event, handler)
+			)
+			listening = true
+		}
+	}
+
+	/**
+	 * Reset the event listeners.
+	 */
+	function reset() {
+		if (listening) {
+			Object.entries(handlers).forEach(([event, handler]) =>
+				element.removeEventListener(event, handler)
+			)
+			listening = false
+		}
+	}
+
+	/**
+	 * 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) {
+		if (listening !== enabled || handlers !== newHandlers) {
+			reset()
+			handlers = newHandlers
+			if (enabled) activate()
+		}
+	}
+
+	return { activate, reset, update }
+}

package/src/lib/index.js

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,185 @@
+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.
+ *
+ * @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)
+		})
+	}
+}
+
+/**
+ * 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 }
+}