@rokkit/actions 1.0.0-next.133 → 1.0.0-next.134

package/README.md

@@ -1,57 +1,189 @@
-# Actions
+# @rokkit/actions
 
-This package provides a set of actions that can be used to perform various tasks.
+Svelte actions and DOM utilities for Rokkit components.
 
-## Keyboard
+## Installation
 
-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:
+```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>
+```
 
-The default behavior is to listen to keyup events.
+### hoverLift — elevation shadow on hover
 
-- [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
+```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>
 
-Default configuration
+<button use:magnetic>Hover me</button>
+```
 
-- _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
+### reveal — intersection observer reveal animation
 
-### Basic Usage
+```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 { keyboard } from '@fumbl/actions'
+  import { dismissable } from '@rokkit/actions'
 
-  function handleKey(event) {
-    console.log(`${event.detail} pressed`)
-  }
+  let open = $state(false)
 </script>
 
-<div use:keyboard onadd={handleKey}></div>
+<div use:dismissable={{ enabled: open, ondismiss: () => (open = false) }}>Dropdown content</div>
 ```
 
-### Custom Events
+### swipeable — touch swipe detection
 
 ```svelte
 <script>
-  import { keyboard } from '@fumbl/actions'
-  function handleKey(event) {
-    console.log(`${event.detail} pressed`)
-  }
+  import { swipeable } from '@rokkit/actions'
+</script>
 
-  const config = {
-    add: ['a', 'b', 'c'],
-    submit: 'enter',
-    cancel: 'escape',
-    delete: ['backspace', 'delete']
-  }
+<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:keyboard={config} onadd={handleKey}></div>
+<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,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.133",
+  "version": "1.0.0-next.134",
   "description": "Contains generic actions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -10,6 +10,7 @@
   },
   "scripts": {
     "prepublishOnly": "cp ../../LICENSE . && tsc --project tsconfig.build.json",
+    "postpublish": "rm -f LICENSE",
     "clean": "rm -rf dist",
     "build": "bun clean && bun prepublishOnly"
   },

package/src/hover-lift.svelte.js

@@ -20,8 +20,7 @@ export function hoverLift(node, options = {}) {
 		}
 
 		const reducedMotion =
-			typeof window !== 'undefined' &&
-			window.matchMedia('(prefers-reduced-motion: reduce)').matches
+			typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
 
 		if (reducedMotion) return
 

package/src/magnetic.svelte.js

@@ -18,8 +18,7 @@ export function magnetic(node, options = {}) {
 		}
 
 		const reducedMotion =
-			typeof window !== 'undefined' &&
-			window.matchMedia('(prefers-reduced-motion: reduce)').matches
+			typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
 
 		if (reducedMotion) return
 

package/src/navigator.js

@@ -153,9 +153,7 @@ export class Navigator {
 		// Focused the container itself (user tabbed in, no roving tabindex item yet)
 		// Redirect focus to the currently focused item, or first item if none
 		const targetKey = this.#wrapper.focusedKey
-		const selector = targetKey
-			? `[data-path="${targetKey}"]`
-			: '[data-path]:not([disabled])'
+		const selector = targetKey ? `[data-path="${targetKey}"]` : '[data-path]:not([disabled])'
 		const el = /** @type {HTMLElement|null} */ (this.#root.querySelector(selector))
 		if (el) {
 			el.focus()

package/src/navigator.svelte.js

@@ -162,8 +162,7 @@ export function navigator(node, options) {
 			resetTypeahead()
 			emitAction(node, wrapper, action, true)
 			// If expand/collapse moved focus, also emit move so components update DOM focus
-			const focusMoved =
-				['expand', 'collapse'].includes(action) && wrapper.focusedKey !== prevKey
+			const focusMoved = ['expand', 'collapse'].includes(action) && wrapper.focusedKey !== prevKey
 			if (focusMoved) {
 				node.dispatchEvent(
 					new CustomEvent('action', {

package/src/reveal.svelte.js

@@ -31,8 +31,7 @@ export function reveal(node, options = {}) {
 		}
 
 		const reducedMotion =
-			typeof window !== 'undefined' &&
-			window.matchMedia('(prefers-reduced-motion: reduce)').matches
+			typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
 
 		const isStagger = opts.stagger > 0
 

package/src/ripple.svelte.js

@@ -20,8 +20,7 @@ export function ripple(node, options = {}) {
 		}
 
 		const reducedMotion =
-			typeof window !== 'undefined' &&
-			window.matchMedia('(prefers-reduced-motion: reduce)').matches
+			typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
 
 		if (reducedMotion) return
 

package/src/trigger.js

@@ -49,7 +49,9 @@ export class Trigger {
 		document.addEventListener('keydown', this.#handleDocKeydown)
 	}
 
-	get isOpen() { return this.#isOpenFn() }
+	get isOpen() {
+		return this.#isOpenFn()
+	}
 
 	open() {
 		if (this.isOpen) return

package/src/utils.js

@@ -26,7 +26,6 @@ export function getClosestAncestorWithAttribute(element, attribute) {
  * @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))