@rokkit/actions 1.1.1 → 1.1.5
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 +18 -15
- package/dist/index.d.ts +0 -1
- package/package.json +1 -1
- package/src/index.js +0 -1
- package/dist/navigator.svelte.d.ts +0 -20
- package/src/navigator.svelte.js +0 -235
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
|
|
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
|
-
###
|
|
19
|
+
### Navigator — keyboard and click navigation
|
|
20
20
|
|
|
21
|
-
The `
|
|
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 {
|
|
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
|
|
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
|
-
|
|
48
|
+
Options:
|
|
42
49
|
|
|
43
50
|
```js
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
const nav = new Navigator(containerEl, wrapper, {
|
|
51
|
+
new Navigator(containerEl, wrapper, {
|
|
47
52
|
orientation: 'vertical', // 'vertical' | 'horizontal'
|
|
48
|
-
|
|
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
|
|
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
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;
|
package/src/navigator.svelte.js
DELETED
|
@@ -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
|
-
}
|