@rokkit/actions 1.1.1 → 1.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,24 +12,31 @@ bun add @rokkit/actions
12
12
 
13
13
  ## Overview
14
14
 
15
- `@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.
15
+ `@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 any IWrapper-shaped object) 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.
16
16
 
17
17
  ## Usage
18
18
 
19
- ### navigator — keyboard and click navigation
19
+ ### Navigator — keyboard and click navigation
20
20
 
21
- 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.
21
+ The `Navigator` class wires a container element's DOM events to a Wrapper. It handles `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight`, `Home`, `End`, `Enter`, `Space`, typeahead, click-to-select, ctrl/cmd-click toggle, shift-click range, and contained `scrollIntoView`.
22
22
 
23
23
  ```svelte
24
24
  <script>
25
- import { navigator } from '@rokkit/actions'
25
+ import { Navigator } from '@rokkit/actions'
26
26
  import { ProxyTree, Wrapper } from '@rokkit/states'
27
27
 
28
28
  const tree = new ProxyTree(items)
29
29
  const wrapper = new Wrapper(tree, { onselect })
30
+
31
+ let rootRef = $state(null)
32
+ $effect(() => {
33
+ if (!rootRef) return
34
+ const nav = new Navigator(rootRef, wrapper, { orientation: 'vertical' })
35
+ return () => nav.destroy()
36
+ })
30
37
  </script>
31
38
 
32
- <ul use:navigator={{ controller: wrapper, orientation: 'vertical' }}>
39
+ <ul bind:this={rootRef}>
33
40
  {#each wrapper.flatView as node (node.key)}
34
41
  <li data-path={node.key}>{node.proxy.label}</li>
35
42
  {/each}
@@ -38,18 +45,15 @@ The `navigator` action connects a container element's DOM events to a Wrapper co
38
45
 
39
46
  The `data-path` attribute on each item is required — Navigator uses it to resolve which item was clicked or focused.
40
47
 
41
- ### Navigator class (imperative usage)
48
+ Options:
42
49
 
43
50
  ```js
44
- import { Navigator } from '@rokkit/actions'
45
-
46
- const nav = new Navigator(containerEl, wrapper, {
51
+ new Navigator(containerEl, wrapper, {
47
52
  orientation: 'vertical', // 'vertical' | 'horizontal'
48
- collapsible: true // enable expand/collapse key handling
53
+ dir: 'ltr', // 'ltr' | 'rtl' — arrow-key direction
54
+ collapsible: false, // enable expand/collapse key handling
55
+ containScroll: false // stop wheel events from bubbling to parents
49
56
  })
50
-
51
- // Clean up when done
52
- nav.destroy()
53
57
  ```
54
58
 
55
59
  ### keyboard — declarative shortcut binding
@@ -169,8 +173,7 @@ const action = resolveAction(keymap, event) // returns action string or null
169
173
 
170
174
  | Export | Type | Description |
171
175
  | --------------- | ------------- | ---------------------------------------------- |
172
- | `Navigator` | Class | DOM event wiring for Wrapper/ListController |
173
- | `navigator` | Svelte action | `use:navigator` wrapper around Navigator class |
176
+ | `Navigator` | Class | DOM event wiring for Wrapper |
174
177
  | `keyboard` | Svelte action | Declarative keyboard shortcut binding |
175
178
  | `ripple` | Svelte action | Material Design ink ripple on click |
176
179
  | `hoverLift` | Svelte action | Elevation shadow on hover |
package/dist/index.d.ts CHANGED
@@ -4,7 +4,6 @@ export { Trigger } from "./trigger.js";
4
4
  export { keyboard } from "./keyboard.svelte.js";
5
5
  export { pannable } from "./pannable.svelte.js";
6
6
  export { swipeable } from "./swipeable.svelte.js";
7
- export { navigator } from "./navigator.svelte.js";
8
7
  export { themable } from "./themable.svelte.js";
9
8
  export { skinnable } from "./skinnable.svelte.js";
10
9
  export { dismissable } from "./dismissable.svelte.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rokkit/actions",
3
- "version": "1.1.1",
3
+ "version": "1.1.4",
4
4
  "description": "Contains generic actions that can be used in various components.",
5
5
  "repository": {
6
6
  "type": "git",
package/src/index.js CHANGED
@@ -6,7 +6,6 @@ export { buildKeymap, resolveAction, ACTIONS } from './keymap.js'
6
6
  export { keyboard } from './keyboard.svelte.js'
7
7
  export { pannable } from './pannable.svelte.js'
8
8
  export { swipeable } from './swipeable.svelte.js'
9
- export { navigator } from './navigator.svelte.js'
10
9
  export { themable } from './themable.svelte.js'
11
10
  export { skinnable } from './skinnable.svelte.js'
12
11
  export { dismissable } from './dismissable.svelte.js'
@@ -1,20 +0,0 @@
1
- /**
2
- * The last only indicates that if there is an array only the last event is fired.
3
- * This is crucial because a click event needs to fire both move and select,
4
- * however the keyboard should only fire the select event because we are already
5
- * on the current item
6
- *
7
- * @param {HTMLElement} root
8
- * @param {*} controller
9
- * @param {*} name
10
- */
11
- export function emitAction(root: HTMLElement, controller: any, name: any, lastOnly?: boolean): void;
12
- export function handleAction(event: any, handler: any, path: any): any;
13
- /**
14
- * A svelte action function that captures keyboard evvents and emits event for corresponding movements.
15
- *
16
- * @param {HTMLElement} node
17
- * @param {import('./types').NavigableOptions} options
18
- * @returns {import('./types').SvelteActionReturn}
19
- */
20
- export function navigator(node: HTMLElement, options: import("./types").NavigableOptions): import("./types").SvelteActionReturn;
@@ -1,235 +0,0 @@
1
- import { on } from 'svelte/events'
2
- import { omit } from 'ramda'
3
- import { getKeyboardAction, defaultNavigationOptions } from './kbd'
4
- import { getClickAction, getPathFromEvent } from './utils'
5
-
6
- /**
7
- * Scrolls the focused element into view if it exists
8
- * @param {HTMLElement} container - The container element with the navigator action
9
- * @param {*} wrapper - The controller/wrapper with focusedKey
10
- */
11
- function scrollFocusedIntoView(container, wrapper) {
12
- let focusedElement = null
13
-
14
- // Use focusedKey if available (most reliable)
15
- if (wrapper.focusedKey) {
16
- focusedElement = container.querySelector(`[data-path="${wrapper.focusedKey}"]`)
17
- }
18
-
19
- // Fallback: find by aria-current
20
- if (!focusedElement) {
21
- focusedElement = container.querySelector('[aria-current="true"]')
22
- }
23
-
24
- // Scroll into view if element found and method exists (may not exist in test env)
25
- if (focusedElement?.scrollIntoView) {
26
- focusedElement.scrollIntoView({
27
- behavior: 'smooth',
28
- block: 'nearest',
29
- inline: 'nearest'
30
- })
31
- }
32
- }
33
-
34
- const EVENT_MAP = {
35
- first: ['move'],
36
- last: ['move'],
37
- previous: ['move'],
38
- next: ['move'],
39
- select: ['move', 'select'],
40
- extend: ['move', 'select'],
41
- range: ['move', 'select'],
42
- collapse: ['toggle'],
43
- expand: ['toggle'],
44
- toggle: ['toggle']
45
- }
46
-
47
- /**
48
- * The last only indicates that if there is an array only the last event is fired.
49
- * This is crucial because a click event needs to fire both move and select,
50
- * however the keyboard should only fire the select event because we are already
51
- * on the current item
52
- *
53
- * @param {HTMLElement} root
54
- * @param {*} controller
55
- * @param {*} name
56
- */
57
- export function emitAction(root, controller, name, lastOnly = false) {
58
- const events = lastOnly ? EVENT_MAP[name].slice(-1) : EVENT_MAP[name]
59
-
60
- events.forEach((event) => {
61
- root.dispatchEvent(
62
- new CustomEvent('action', {
63
- detail: {
64
- name: event,
65
- data: { value: controller.focused, selected: controller.selected }
66
- }
67
- })
68
- )
69
- })
70
- }
71
-
72
- /*
73
- * Generic action handler for keyboard events.
74
- *
75
- * @param {Record<string, () => void>} actions
76
- * @param {KeyboardEvent} event
77
- */
78
- export function handleAction(event, handler, path) {
79
- if (handler) {
80
- event.preventDefault()
81
- event.stopPropagation()
82
-
83
- return handler(path)
84
- }
85
- return false
86
- }
87
-
88
- function getHandlers(wrapper) {
89
- return {
90
- first: () => wrapper.moveFirst(),
91
- last: () => wrapper.moveLast(),
92
- previous: () => wrapper.movePrev(),
93
- next: () => wrapper.moveNext(),
94
- collapse: () => wrapper.collapse(),
95
- expand: () => wrapper.expand(),
96
- select: (path) => wrapper.select(path),
97
- extend: (path) => wrapper.extendSelection(path),
98
- range: (path) => wrapper.selectRange(path),
99
- toggle: (path) => wrapper.toggleExpansion(path)
100
- }
101
- }
102
-
103
- function isTypeaheadEvent(event) {
104
- if (event.ctrlKey) return false
105
- if (event.metaKey) return false
106
- if (event.altKey) return false
107
- if (event.key.length !== 1) return false
108
- return event.key !== ' '
109
- }
110
-
111
- function dispatchFocusMoveEvent(node, wrapper) {
112
- node.dispatchEvent(
113
- new CustomEvent('action', {
114
- detail: {
115
- name: 'move',
116
- data: { value: wrapper.focused, selected: wrapper.selected }
117
- }
118
- })
119
- )
120
- }
121
-
122
- const SCROLL_ACTIONS = new Set(['first', 'last', 'previous', 'next', 'expand', 'collapse'])
123
-
124
- function isNativeLink(action, target) {
125
- return action === 'select' && Boolean(target.closest('a[href]'))
126
- }
127
-
128
- function notifyFocusMove(node, wrapper, action, prevKey) {
129
- if (action !== 'expand' && action !== 'collapse') return false
130
- if (wrapper.focusedKey === prevKey) return false
131
- dispatchFocusMoveEvent(node, wrapper)
132
- return true
133
- }
134
-
135
- function runTypeahead(config, wrapper, ta, event) {
136
- if (!config.typeahead) return
137
- if (!wrapper.findByText) return
138
- ta.handle(event)
139
- }
140
-
141
- function makeKeydownHandler(ctx, config, handlers, ta) {
142
- const { node, wrapper } = ctx
143
- return (event) => {
144
- const action = getKeyboardAction(event, config)
145
- if (isNativeLink(action, event.target)) return
146
-
147
- const prevKey = wrapper.focusedKey
148
- const handled = handleAction(event, handlers[action])
149
- if (!handled) {
150
- runTypeahead(config, wrapper, ta, event)
151
- return
152
- }
153
-
154
- ta.reset()
155
- emitAction(node, wrapper, action, true)
156
- notifyFocusMove(node, wrapper, action, prevKey)
157
- if (SCROLL_ACTIONS.has(action)) setTimeout(() => scrollFocusedIntoView(node, wrapper), 0)
158
- }
159
- }
160
-
161
- function getTypeaheadStart(buffer, wrapper) {
162
- if (buffer.length === 0) return wrapper.focusedKey
163
- return null
164
- }
165
-
166
- function makeTypeahead(node, wrapper) {
167
- let buffer = ''
168
- let timer = null
169
-
170
- function reset() {
171
- buffer = ''
172
- if (timer) {
173
- clearTimeout(timer)
174
- timer = null
175
- }
176
- }
177
-
178
- function handle(event) {
179
- if (!isTypeaheadEvent(event)) return false
180
-
181
- const startAfter = getTypeaheadStart(buffer, wrapper)
182
- buffer += event.key
183
- if (timer) clearTimeout(timer)
184
- timer = setTimeout(reset, 500)
185
-
186
- const matchKey = wrapper.findByText(buffer, startAfter)
187
- if (matchKey === null) return false
188
- if (!wrapper.moveTo(matchKey)) return false
189
-
190
- event.preventDefault()
191
- event.stopPropagation()
192
- emitAction(node, wrapper, 'first', true)
193
- setTimeout(() => scrollFocusedIntoView(node, wrapper), 0)
194
- return true
195
- }
196
-
197
- return { reset, handle }
198
- }
199
-
200
- /**
201
- * A svelte action function that captures keyboard evvents and emits event for corresponding movements.
202
- *
203
- * @param {HTMLElement} node
204
- * @param {import('./types').NavigableOptions} options
205
- * @returns {import('./types').SvelteActionReturn}
206
- */
207
- export function navigator(node, options) {
208
- const { wrapper } = options
209
- const config = { ...defaultNavigationOptions, ...omit(['wrapper'], options) }
210
- const handlers = getHandlers(wrapper)
211
- const ta = makeTypeahead(node, wrapper)
212
- const handleKeydown = makeKeydownHandler({ node, wrapper }, config, handlers, ta)
213
-
214
- const handleClick = (event) => {
215
- const action = getClickAction(event)
216
- const path = getPathFromEvent(event)
217
-
218
- if (event.target.closest('a[href]')) {
219
- const handler = handlers[action]
220
- if (handler?.(path)) emitAction(node, options.wrapper, action)
221
- return
222
- }
223
-
224
- const handled = handleAction(event, handlers[action], path)
225
- if (handled) emitAction(node, options.wrapper, action)
226
- }
227
-
228
- $effect(() => {
229
- const cleanup = [on(node, 'keydown', handleKeydown), on(node, 'click', handleClick)]
230
- return () => {
231
- ta.reset()
232
- cleanup.forEach((fn) => fn())
233
- }
234
- })
235
- }