@rokkit/actions 1.0.0-next.99 → 1.0.1

package/README.md

@@ -1 +1,189 @@
-# Core Components
+# @rokkit/actions
+
+Svelte actions and DOM utilities for Rokkit components.
+
+## Installation
+
+```bash
+npm install @rokkit/actions
+# or
+bun add @rokkit/actions
+```
+
+## Overview
+
+`@rokkit/actions` provides the DOM event layer that `@rokkit/ui` components build on. The main export is `Navigator` — a class that wires keyboard, click, and focus events on a container element to a `Wrapper` or `ListController` instance. The package also includes standalone Svelte `use:` actions for effects like ripple, magnetic snap, reveal animations, dismissal on click-outside, and declarative keyboard shortcuts.
+
+## Usage
+
+### navigator — keyboard and click navigation
+
+The `navigator` action connects a container element's DOM events to a Wrapper controller. It handles `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight`, `Home`, `End`, `Enter`, `Space`, typeahead, and click-to-select.
+
+```svelte
+<script>
+  import { navigator } from '@rokkit/actions'
+  import { ProxyTree, Wrapper } from '@rokkit/states'
+
+  const tree = new ProxyTree(items)
+  const wrapper = new Wrapper(tree, { onselect })
+</script>
+
+<ul use:navigator={{ controller: wrapper, orientation: 'vertical' }}>
+  {#each wrapper.flatView as node (node.key)}
+    <li data-path={node.key}>{node.proxy.label}</li>
+  {/each}
+</ul>
+```
+
+The `data-path` attribute on each item is required — Navigator uses it to resolve which item was clicked or focused.
+
+### Navigator class (imperative usage)
+
+```js
+import { Navigator } from '@rokkit/actions'
+
+const nav = new Navigator(containerEl, wrapper, {
+  orientation: 'vertical', // 'vertical' | 'horizontal'
+  collapsible: true // enable expand/collapse key handling
+})
+
+// Clean up when done
+nav.destroy()
+```
+
+### keyboard — declarative shortcut binding
+
+```svelte
+<script>
+  import { keyboard } from '@rokkit/actions'
+</script>
+
+<div
+  use:keyboard={{ submit: 'enter', cancel: 'escape' }}
+  onsubmit={() => save()}
+  oncancel={() => close()}
+>
+  ...
+</div>
+```
+
+Default mappings: alphabet keys dispatch `add`, Enter dispatches `submit`, Escape dispatches `cancel`, Backspace/Delete dispatch `delete`.
+
+### ripple — click ripple effect
+
+```svelte
+<script>
+  import { ripple } from '@rokkit/actions'
+</script>
+
+<button use:ripple>Click me</button>
+
+<!-- With options -->
+<button use:ripple={{ color: 'white', opacity: 0.2, duration: 400 }}>Click me</button>
+```
+
+### hoverLift — elevation shadow on hover
+
+```svelte
+<script>
+  import { hoverLift } from '@rokkit/actions'
+</script>
+
+<div use:hoverLift>Card content</div>
+```
+
+### magnetic — snap-to-cursor effect
+
+```svelte
+<script>
+  import { magnetic } from '@rokkit/actions'
+</script>
+
+<button use:magnetic>Hover me</button>
+```
+
+### reveal — intersection observer reveal animation
+
+```svelte
+<script>
+  import { reveal } from '@rokkit/actions'
+</script>
+
+<section use:reveal>Fades in when scrolled into view</section>
+```
+
+### dismissable — click-outside dismissal
+
+```svelte
+<script>
+  import { dismissable } from '@rokkit/actions'
+
+  let open = $state(false)
+</script>
+
+<div use:dismissable={{ enabled: open, ondismiss: () => (open = false) }}>Dropdown content</div>
+```
+
+### swipeable — touch swipe detection
+
+```svelte
+<script>
+  import { swipeable } from '@rokkit/actions'
+</script>
+
+<div use:swipeable onswipeleft={() => next()} onswiperight={() => prev()}>Swipeable content</div>
+```
+
+### themable — apply theme CSS variables
+
+```svelte
+<script>
+  import { themable } from '@rokkit/actions'
+</script>
+
+<div use:themable={{ theme: 'ocean' }}>Themed content</div>
+```
+
+## API Reference
+
+### Navigator options
+
+| Option        | Type                         | Default      | Description                           |
+| ------------- | ---------------------------- | ------------ | ------------------------------------- |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Arrow key axis for prev/next movement |
+| `collapsible` | `boolean`                    | `false`      | Enable expand/collapse via arrow keys |
+
+### buildKeymap / resolveAction
+
+Low-level utilities for constructing custom keymaps:
+
+```js
+import { buildKeymap, resolveAction, ACTIONS } from '@rokkit/actions'
+
+const keymap = buildKeymap({ orientation: 'vertical', collapsible: true })
+const action = resolveAction(keymap, event) // returns action string or null
+```
+
+## Exports
+
+| Export          | Type          | Description                                    |
+| --------------- | ------------- | ---------------------------------------------- |
+| `Navigator`     | Class         | DOM event wiring for Wrapper/ListController    |
+| `navigator`     | Svelte action | `use:navigator` wrapper around Navigator class |
+| `keyboard`      | Svelte action | Declarative keyboard shortcut binding          |
+| `ripple`        | Svelte action | Material Design ink ripple on click            |
+| `hoverLift`     | Svelte action | Elevation shadow on hover                      |
+| `magnetic`      | Svelte action | Snap-to-cursor magnetic effect                 |
+| `reveal`        | Svelte action | Intersection-observer reveal animation         |
+| `dismissable`   | Svelte action | Click-outside dismissal                        |
+| `pannable`      | Svelte action | Pan / drag detection                           |
+| `swipeable`     | Svelte action | Touch swipe detection                          |
+| `themable`      | Svelte action | Apply theme CSS vars to element                |
+| `buildKeymap`   | Function      | Build a keymap for given orientation/options   |
+| `resolveAction` | Function      | Resolve a keyboard event to an action string   |
+| `ACTIONS`       | Object        | Named action constants                         |
+
+---
+
+Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.

package/package.json

@@ -1,33 +1,29 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.99",
+  "version": "1.0.1",
   "description": "Contains generic actions that can be used in various components.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jerrythomas/rokkit.git"
+  },
   "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.99",
-    "validators": "1.0.0-next.99"
+  "scripts": {
+    "prepublishOnly": "cp ../../LICENSE . && tsc --project tsconfig.build.json",
+    "postpublish": "rm -f LICENSE",
+    "clean": "rm -rf dist",
+    "build": "bun clean && bun prepublishOnly"
   },
   "files": [
     "src/**/*.js",
-    "src/**/*.svelte"
+    "dist/**/*.d.ts",
+    "README.md",
+    "package.json",
+    "LICENSE"
   ],
   "exports": {
     "./src": "./src",
@@ -39,18 +35,11 @@
     }
   },
   "dependencies": {
-    "ramda": "^0.30.1",
-    "@rokkit/core": "1.0.0-next.99",
-    "@rokkit/stores": "1.0.0-next.99"
+    "ramda": "^0.32.0",
+    "@rokkit/core": "latest"
   },
-  "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"
+  "devDependencies": {
+    "@rokkit/helpers": "latest",
+    "@rokkit/states": "latest"
   }
-}
+}

package/src/{delegate.js → delegate.svelte.js}

@@ -1,11 +1,10 @@
 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.
@@ -23,12 +22,13 @@ export function delegateKeyboardEvents(
 		child.dispatchEvent(new KeyboardEvent(event.type, event))
 	}
 
-	if (child) {
-		events.forEach((event) => (handlers[event] = forwardEvent))
-		manager.update(handlers)
-	}
-
-	return {
-		destroy: () => manager.reset()
-	}
+	$effect(() => {
+		if (child) {
+			events.forEach((event) => {
+				handlers[event] = forwardEvent
+			})
+			manager.update(handlers)
+		}
+		return () => manager.reset()
+	})
 }

package/src/{dismissable.js → dismissable.svelte.js}

@@ -1,3 +1,4 @@
+import { on } from 'svelte/events'
 const KEYCODE_ESC = 27
 
 /**
@@ -5,29 +6,28 @@ const KEYCODE_ESC = 27
  * 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))
+			node.dispatchEvent(new CustomEvent('dismiss'))
 		}
 	}
+
 	const keyup = (event) => {
 		if (event.keyCode === KEYCODE_ESC || event.key === 'Escape') {
 			event.stopPropagation()
-
-			node.dispatchEvent(new CustomEvent('dismiss', node))
+			node.dispatchEvent(new CustomEvent('dismiss', { detail: node }))
 		}
 	}
 
-	document.addEventListener('click', handleClick, true)
-	document.addEventListener('keyup', keyup, true)
+	$effect(() => {
+		const cleanupClickEvent = on(document, 'click', handleClick)
+		const cleanupKeyupEvent = on(document, 'keyup', keyup)
 
-	return {
-		destroy() {
-			document.removeEventListener('click', handleClick, true)
-			document.removeEventListener('keyup', keyup, true)
+		return () => {
+			cleanupClickEvent()
+			cleanupKeyupEvent()
 		}
-	}
+	})
 }

package/src/{fillable.js → fillable.svelte.js}

@@ -1,39 +1,4 @@
-/**
- * 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)
-			})
-		}
-	}
-}
-
+import { on } from 'svelte/events'
 /**
  * Initialize empty fillable element style and add listener for click
  *
@@ -41,12 +6,16 @@ export function fillable(node, { options, current, check }) {
  * @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
+	const registry = []
+	Array.from(blanks).forEach((blank, ref) => {
+		blank.innerHTML = '?'
+		blank.classList.add('empty')
+		blank.name = `fill-${ref}`
+		blank['data-index'] = ref
+		const cleanup = on(blank, 'click', click)
+		registry.push(cleanup)
 	})
+	return registry
 }
 
 /**
@@ -56,13 +25,21 @@ function initialize(blanks, click) {
  * @param {Array<import('./types.js').FillableData>} options
  * @param {*} current
  */
-function fill(blanks, options, current) {
+function fill(blanks, { options, current }, node) {
 	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')
+			node.dispatchEvent(
+				new CustomEvent('fill', {
+					detail: {
+						index: current,
+						value: options[index].value
+					}
+				})
+			)
 		}
 	}
 }
@@ -73,17 +50,19 @@ function fill(blanks, options, current) {
  * @param {EventListener} event
  * @param {HTMLElement} node
  */
-function clear(event, node) {
+function clear(event, node, options) {
+	const item = options.find(({ value }) => value === event.target.innerHTML)
 	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']
+				index: event.target['data-index'],
+				value: item.value
 			}
 		})
 	)
@@ -104,3 +83,33 @@ function validate(blanks, data) {
 			)
 	})
 }
+
+/**
+ * Action for filling a <del>?</del> element in html block.
+ *
+ * @param {HTMLElement} node
+ * @param {import('./types').FillOptions} options
+ * @returns
+ */
+export function fillable(node, data) {
+	const blanks = node.getElementsByTagName('del')
+
+	function click(event) {
+		if (event.target.innerHTML !== '?') {
+			clear(event, node, data.options)
+		} else {
+			data.current = event.target['data-index']
+			fill(blanks, data, node)
+		}
+	}
+
+	$effect(() => {
+		const registry = initialize(blanks, click)
+
+		if (data.check) validate(blanks, data)
+
+		return () => {
+			registry.forEach((cleanup) => cleanup())
+		}
+	})
+}

package/src/hover-lift.svelte.js

@@ -0,0 +1,64 @@
+/**
+ * Hover lift action — adds translateY + elevated shadow on hover.
+ * Sets transition on mount, applies transform + box-shadow on mouseenter, resets on mouseleave.
+ *
+ * @param {HTMLElement} node
+ * @param {HoverLiftOptions} [options]
+ *
+ * @typedef {Object} HoverLiftOptions
+ * @property {string} [distance='-0.25rem'] Translate distance on hover (negative = up)
+ * @property {string} [shadow='0 10px 25px -5px rgba(0,0,0,0.1)'] Box shadow on hover
+ * @property {number} [duration=200] Transition duration (ms)
+ */
+
+function resolveHoverLiftOpts(options) {
+	return {
+		distance: '-0.25rem',
+		shadow: '0 10px 25px -5px rgba(0,0,0,0.1)',
+		duration: 200,
+		...options
+	}
+}
+
+function isReducedMotion() {
+	return (
+		typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+	)
+}
+
+function applyHoverLift(node, opts) {
+	const originalTransform = node.style.transform
+	const originalBoxShadow = node.style.boxShadow
+	const originalTransition = node.style.transition
+
+	node.style.transition = `transform ${opts.duration}ms ease, box-shadow ${opts.duration}ms ease`
+
+	function onEnter() {
+		node.style.transform = `translateY(${opts.distance})`
+		node.style.boxShadow = opts.shadow
+	}
+
+	function onLeave() {
+		node.style.transform = originalTransform
+		node.style.boxShadow = originalBoxShadow
+	}
+
+	node.addEventListener('mouseenter', onEnter)
+	node.addEventListener('mouseleave', onLeave)
+
+	return () => {
+		node.removeEventListener('mouseenter', onEnter)
+		node.removeEventListener('mouseleave', onLeave)
+		node.style.transform = originalTransform
+		node.style.boxShadow = originalBoxShadow
+		node.style.transition = originalTransition
+	}
+}
+
+export function hoverLift(node, options = {}) {
+	$effect(() => {
+		const opts = resolveHoverLiftOpts(options)
+		if (isReducedMotion()) return
+		return applyHoverLift(node, opts)
+	})
+}

package/src/index.js

@@ -1,13 +1,20 @@
 // 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 { Navigator } from './navigator.js'
+export { Trigger } from './trigger.js'
+export { buildKeymap, resolveAction, ACTIONS } from './keymap.js'
+export { keyboard } from './keyboard.svelte.js'
+export { pannable } from './pannable.svelte.js'
+export { swipeable } from './swipeable.svelte.js'
+export { navigator } from './navigator.svelte.js'
+export { themable } from './themable.svelte.js'
+export { skinnable } from './skinnable.svelte.js'
+export { dismissable } from './dismissable.svelte.js'
+export { navigable } from './navigable.svelte.js'
+export { fillable } from './fillable.svelte.js'
+export { delegateKeyboardEvents } from './delegate.svelte.js'
+export { reveal } from './reveal.svelte.js'
+export { hoverLift } from './hover-lift.svelte.js'
+export { magnetic } from './magnetic.svelte.js'
+export { ripple } from './ripple.svelte.js'
+export { tooltip } from './tooltip.svelte.js'