@wcomp/elementum 0.0.0-stage → 0.2.0

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.
Files changed (102) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +282 -2
  3. package/custom-elements.json +3613 -0
  4. package/mcp/server.js +593 -0
  5. package/package.json +77 -4
  6. package/skills/elementum-break-ui/CATALOG.md +11 -0
  7. package/skills/elementum-break-ui/SKILL.md +16 -0
  8. package/skills/elementum-mobile/SKILL.md +18 -0
  9. package/skills/elementum-motion/SKILL.md +18 -0
  10. package/skills/elementum-motion/STANDARDS.md +15 -0
  11. package/skills/elementum-penpot/SKILL.md +45 -0
  12. package/skills/elementum-ui/CATALOG.md +14 -0
  13. package/skills/elementum-ui/SKILL.md +21 -0
  14. package/src/ag-ui.js +474 -0
  15. package/src/behaviors/index.js +760 -0
  16. package/src/components/el-accordion.js +201 -0
  17. package/src/components/el-alert-dialog.js +186 -0
  18. package/src/components/el-alert.js +254 -0
  19. package/src/components/el-aspect-ratio.js +73 -0
  20. package/src/components/el-autocomplete.js +775 -0
  21. package/src/components/el-avatar.js +271 -0
  22. package/src/components/el-badge.js +131 -0
  23. package/src/components/el-border-beam.js +135 -0
  24. package/src/components/el-breadcrumb.js +203 -0
  25. package/src/components/el-button.js +231 -0
  26. package/src/components/el-calendar.js +436 -0
  27. package/src/components/el-callout.js +158 -0
  28. package/src/components/el-card.js +298 -0
  29. package/src/components/el-carousel.js +308 -0
  30. package/src/components/el-chart.js +632 -0
  31. package/src/components/el-checkbox-card.js +221 -0
  32. package/src/components/el-checkbox.js +208 -0
  33. package/src/components/el-chip.js +276 -0
  34. package/src/components/el-code-block.js +230 -0
  35. package/src/components/el-collapsible.js +124 -0
  36. package/src/components/el-command.js +556 -0
  37. package/src/components/el-context-menu.js +328 -0
  38. package/src/components/el-data-list.js +210 -0
  39. package/src/components/el-datepicker.js +192 -0
  40. package/src/components/el-dialog.js +272 -0
  41. package/src/components/el-diff-viewer.js +441 -0
  42. package/src/components/el-drawer.js +782 -0
  43. package/src/components/el-dropdown.js +182 -0
  44. package/src/components/el-dropzone.js +242 -0
  45. package/src/components/el-empty-state.js +130 -0
  46. package/src/components/el-field.js +394 -0
  47. package/src/components/el-form.js +185 -0
  48. package/src/components/el-input.js +229 -0
  49. package/src/components/el-inset.js +90 -0
  50. package/src/components/el-insight-card.js +263 -0
  51. package/src/components/el-kbd.js +151 -0
  52. package/src/components/el-menubar.js +254 -0
  53. package/src/components/el-meter.js +183 -0
  54. package/src/components/el-navbar.js +294 -0
  55. package/src/components/el-navigation-menu.js +327 -0
  56. package/src/components/el-number-field.js +510 -0
  57. package/src/components/el-number-flow.js +164 -0
  58. package/src/components/el-otp-input.js +266 -0
  59. package/src/components/el-pagination.js +231 -0
  60. package/src/components/el-popover.js +288 -0
  61. package/src/components/el-preview-card.js +202 -0
  62. package/src/components/el-progress.js +179 -0
  63. package/src/components/el-prompt-input.js +383 -0
  64. package/src/components/el-radio-card.js +360 -0
  65. package/src/components/el-radio.js +257 -0
  66. package/src/components/el-rating.js +165 -0
  67. package/src/components/el-reasoning-card.js +293 -0
  68. package/src/components/el-resizable.js +324 -0
  69. package/src/components/el-router.js +305 -0
  70. package/src/components/el-scroll-area.js +150 -0
  71. package/src/components/el-segmented-control.js +282 -0
  72. package/src/components/el-select.js +220 -0
  73. package/src/components/el-separator.js +85 -0
  74. package/src/components/el-sidebar.js +386 -0
  75. package/src/components/el-skeleton.js +156 -0
  76. package/src/components/el-slider.js +351 -0
  77. package/src/components/el-sources.js +288 -0
  78. package/src/components/el-spinner.js +159 -0
  79. package/src/components/el-streaming-text.js +199 -0
  80. package/src/components/el-switch.js +221 -0
  81. package/src/components/el-table.js +397 -0
  82. package/src/components/el-tabs.js +235 -0
  83. package/src/components/el-task-list.js +230 -0
  84. package/src/components/el-textarea.js +175 -0
  85. package/src/components/el-theme-switch.js +120 -0
  86. package/src/components/el-timeline.js +254 -0
  87. package/src/components/el-toast.js +778 -0
  88. package/src/components/el-toggle.js +311 -0
  89. package/src/components/el-tool-call.js +386 -0
  90. package/src/components/el-toolbar.js +183 -0
  91. package/src/components/el-tooltip.js +172 -0
  92. package/src/components/el-tree-view.js +261 -0
  93. package/src/components/el-visually-hidden.js +32 -0
  94. package/src/elementum.js +504 -0
  95. package/src/index.d.ts +1093 -0
  96. package/src/index.js +112 -0
  97. package/src/signal.js +215 -0
  98. package/src/ssr.js +136 -0
  99. package/src/template.js +321 -0
  100. package/src/tokens.css +416 -0
  101. package/tokens/figma-tokens.json +69 -0
  102. package/tokens/penpot-tokens.json +98 -0
@@ -0,0 +1,760 @@
1
+ /**
2
+ * Elementum Behavior Controllers (@wcomp/elementum/behaviors)
3
+ * Zero-dependency, React-Aria-inspired interaction, accessibility, i18n/RTL,
4
+ * selection, reorder/DnD, and state-reflection primitives built on standard DOM APIs and AbortSignal.
5
+ */
6
+
7
+ import { signal as createSignal } from '../signal.js';
8
+
9
+ let lastInteractionModality = 'pointer';
10
+ let modalityListenersAttached = false;
11
+
12
+ function ensureModalityTracking() {
13
+ if (modalityListenersAttached || typeof window === 'undefined') return;
14
+ modalityListenersAttached = true;
15
+
16
+ window.addEventListener(
17
+ 'keydown',
18
+ (e) => {
19
+ if (e.metaKey || e.ctrlKey || e.altKey) return;
20
+ lastInteractionModality = 'keyboard';
21
+ },
22
+ true
23
+ );
24
+
25
+ const setPointer = () => {
26
+ lastInteractionModality = 'pointer';
27
+ };
28
+ window.addEventListener('pointerdown', setPointer, true);
29
+ window.addEventListener('mousedown', setPointer, true);
30
+ window.addEventListener('touchstart', setPointer, { capture: true, passive: true });
31
+ }
32
+
33
+ /**
34
+ * Reflect a standardized interaction/component state onto a host element
35
+ * using BOTH `data-<name>` attributes (for universal CSS / Tailwind selectors)
36
+ * and native `ElementInternals.states` (`:state(<name>)`) when available.
37
+ */
38
+ export function setHostState(host, name, active) {
39
+ if (!host || !name) return;
40
+ const attr = `data-${name}`;
41
+ if (active) {
42
+ if (!host.hasAttribute?.(attr)) {
43
+ host.setAttribute?.(attr, '');
44
+ }
45
+ try {
46
+ host.internals?.states?.add(name);
47
+ } catch {
48
+ // Ignore environments without CustomStateSet support
49
+ }
50
+ } else {
51
+ if (host.hasAttribute?.(attr)) {
52
+ host.removeAttribute?.(attr);
53
+ }
54
+ try {
55
+ host.internals?.states?.delete(name);
56
+ } catch {
57
+ // Ignore environments without CustomStateSet support
58
+ }
59
+ }
60
+ }
61
+
62
+ /**
63
+ * Detect whether an element (or document) is in a Right-to-Left (RTL) writing direction.
64
+ */
65
+ export function isRTL(el) {
66
+ if (el && typeof el.closest === 'function') {
67
+ const dirAncestor = el.closest('[dir]');
68
+ if (dirAncestor) {
69
+ const dir = (dirAncestor.getAttribute('dir') || '').toLowerCase();
70
+ if (dir === 'rtl') return true;
71
+ if (dir === 'ltr') return false;
72
+ }
73
+ }
74
+ if (typeof document !== 'undefined') {
75
+ const docDir = (document.documentElement?.getAttribute?.('dir') || document.dir || '').toLowerCase();
76
+ if (docDir === 'rtl') return true;
77
+ }
78
+ return false;
79
+ }
80
+
81
+ /**
82
+ * Locale-aware number formatting using native Intl.NumberFormat (0 runtime deps).
83
+ */
84
+ export function formatLocaleNumber(value, locale = 'en-US', options = {}) {
85
+ const num = Number(value);
86
+ if (Number.isNaN(num)) return String(value ?? '');
87
+ try {
88
+ return new Intl.NumberFormat(locale || 'en-US', options).format(num);
89
+ } catch {
90
+ return String(num);
91
+ }
92
+ }
93
+
94
+ /**
95
+ * Locale-aware date formatting using native Intl.DateTimeFormat (0 runtime deps).
96
+ */
97
+ export function formatLocaleDate(date, locale = 'en-US', options = {}) {
98
+ const d = date instanceof Date ? date : new Date(date);
99
+ if (Number.isNaN(d.getTime())) return String(date ?? '');
100
+ try {
101
+ return new Intl.DateTimeFormat(locale || 'en-US', options).format(d);
102
+ } catch {
103
+ return d.toISOString().slice(0, 10);
104
+ }
105
+ }
106
+
107
+ // ==========================================
108
+ // 1. LiveAnnouncer (Screen-Reader Live Region)
109
+ // ==========================================
110
+
111
+ const ANNOUNCER_STYLE =
112
+ 'position:fixed;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;pointer-events:none;';
113
+
114
+ function getLiveRegion(politeness) {
115
+ if (typeof document === 'undefined' || !document.body) return null;
116
+ const mode = politeness === 'assertive' ? 'assertive' : 'polite';
117
+ const id = `el-live-announcer-${mode}`;
118
+ let region = document.getElementById(id);
119
+ if (!region) {
120
+ region = document.createElement('div');
121
+ region.id = id;
122
+ region.setAttribute('role', mode === 'assertive' ? 'alert' : 'status');
123
+ region.setAttribute('aria-live', mode);
124
+ region.setAttribute('aria-atomic', 'true');
125
+ region.setAttribute('style', ANNOUNCER_STYLE);
126
+ document.body.appendChild(region);
127
+ }
128
+ return region;
129
+ }
130
+
131
+ /**
132
+ * Announce a dynamic status update to assistive technologies (VoiceOver, NVDA, JAWS, TalkBack).
133
+ */
134
+ export function announce(message, politeness = 'polite') {
135
+ if (!message) return;
136
+ const region = getLiveRegion(politeness);
137
+ if (!region) return;
138
+ const text = String(message);
139
+ // Clear first so identical consecutive announcements still trigger AT output
140
+ if (region.textContent === text) {
141
+ region.textContent = '';
142
+ }
143
+ region.textContent = text;
144
+ }
145
+
146
+ /**
147
+ * Clear active live-region announcements.
148
+ */
149
+ export function clearAnnouncer() {
150
+ if (typeof document === 'undefined') return;
151
+ for (const mode of ['polite', 'assertive']) {
152
+ const region = document.getElementById(`el-live-announcer-${mode}`);
153
+ if (region) region.textContent = '';
154
+ }
155
+ }
156
+
157
+ // ==========================================
158
+ // 2. Press, Hover & Focus-Visible Behavior
159
+ // ==========================================
160
+
161
+ /**
162
+ * Normalizes mouse, touch, and keyboard interactions on an element:
163
+ * - Reflects `data-pressed`, `data-hovered`, `data-focused`, `data-focus-visible` (and `:state(...)`)
164
+ * - Ignores synthetic hover on touch pointers (`pointerType === 'touch'`) to prevent sticky hover on mobile
165
+ * - Handles Enter / Space keyboard press consistently
166
+ */
167
+ export function createPressBehavior(
168
+ host,
169
+ target = host,
170
+ { isDisabled = () => false, onPress = null, signal = host?.signal } = {}
171
+ ) {
172
+ if (!host || !target) return () => {};
173
+ ensureModalityTracking();
174
+
175
+ const controller = new AbortController();
176
+ const abortSignal = controller.signal;
177
+ if (signal) {
178
+ if (signal.aborted) return () => {};
179
+ signal.addEventListener('abort', () => controller.abort(), { once: true });
180
+ }
181
+
182
+ let pressed = false;
183
+ const setPressed = (val) => {
184
+ pressed = Boolean(val);
185
+ setHostState(host, 'pressed', pressed);
186
+ };
187
+
188
+ target.addEventListener(
189
+ 'pointerenter',
190
+ (e) => {
191
+ if (isDisabled() || e.pointerType === 'touch') return;
192
+ setHostState(host, 'hovered', true);
193
+ },
194
+ { signal: abortSignal }
195
+ );
196
+
197
+ target.addEventListener(
198
+ 'pointerleave',
199
+ () => {
200
+ setHostState(host, 'hovered', false);
201
+ if (pressed) setPressed(false);
202
+ },
203
+ { signal: abortSignal }
204
+ );
205
+
206
+ target.addEventListener(
207
+ 'pointerdown',
208
+ (e) => {
209
+ if (isDisabled() || (e.button !== undefined && e.button !== 0)) return;
210
+ lastInteractionModality = 'pointer';
211
+ setPressed(true);
212
+ },
213
+ { signal: abortSignal }
214
+ );
215
+
216
+ target.addEventListener(
217
+ 'pointerup',
218
+ (e) => {
219
+ if (!pressed) return;
220
+ setPressed(false);
221
+ if (!isDisabled() && typeof onPress === 'function') {
222
+ onPress(e);
223
+ }
224
+ },
225
+ { signal: abortSignal }
226
+ );
227
+
228
+ target.addEventListener(
229
+ 'pointercancel',
230
+ () => {
231
+ if (pressed) setPressed(false);
232
+ },
233
+ { signal: abortSignal }
234
+ );
235
+
236
+ target.addEventListener(
237
+ 'keydown',
238
+ (e) => {
239
+ if (isDisabled()) return;
240
+ if (e.key === 'Enter' || e.key === ' ') {
241
+ setPressed(true);
242
+ }
243
+ },
244
+ { signal: abortSignal }
245
+ );
246
+
247
+ target.addEventListener(
248
+ 'keyup',
249
+ (e) => {
250
+ if (!pressed) return;
251
+ if (e.key === 'Enter' || e.key === ' ') {
252
+ setPressed(false);
253
+ if (!isDisabled() && typeof onPress === 'function') {
254
+ onPress(e);
255
+ }
256
+ }
257
+ },
258
+ { signal: abortSignal }
259
+ );
260
+
261
+ target.addEventListener(
262
+ 'focus',
263
+ () => {
264
+ if (isDisabled()) return;
265
+ setHostState(host, 'focused', true);
266
+ const isKeyboard = lastInteractionModality === 'keyboard' || Boolean(target.matches?.(':focus-visible'));
267
+ setHostState(host, 'focus-visible', isKeyboard);
268
+ },
269
+ { signal: abortSignal }
270
+ );
271
+
272
+ target.addEventListener(
273
+ 'blur',
274
+ () => {
275
+ setHostState(host, 'focused', false);
276
+ setHostState(host, 'focus-visible', false);
277
+ if (pressed) setPressed(false);
278
+ },
279
+ { signal: abortSignal }
280
+ );
281
+
282
+ return () => {
283
+ controller.abort();
284
+ setHostState(host, 'pressed', false);
285
+ setHostState(host, 'hovered', false);
286
+ setHostState(host, 'focused', false);
287
+ setHostState(host, 'focus-visible', false);
288
+ };
289
+ }
290
+
291
+ // ==========================================
292
+ // 3. Roving Focus + Typeahead + RTL Behavior
293
+ // ==========================================
294
+
295
+ /**
296
+ * Manages roving tabindex keyboard navigation across composite widgets
297
+ * (tabs, toolbars, menus, radio groups, listboxes, tree views) with
298
+ * automatic RTL (`dir="rtl"`) reversal and 500ms typeahead character search.
299
+ */
300
+ export function createRovingFocus(
301
+ host,
302
+ {
303
+ getItems,
304
+ orientation = 'horizontal',
305
+ loop = true,
306
+ typeahead = true,
307
+ onFocusItem = null,
308
+ signal = host?.signal,
309
+ } = {}
310
+ ) {
311
+ if (!host || typeof getItems !== 'function') return () => {};
312
+
313
+ const controller = new AbortController();
314
+ const abortSignal = controller.signal;
315
+ if (signal) {
316
+ if (signal.aborted) return () => {};
317
+ signal.addEventListener('abort', () => controller.abort(), { once: true });
318
+ }
319
+
320
+ let typeBuffer = '';
321
+ let typeTimer = null;
322
+
323
+ function focusIndex(items, idx) {
324
+ if (!items.length) return;
325
+ const bounded = loop
326
+ ? (idx + items.length) % items.length
327
+ : Math.max(0, Math.min(items.length - 1, idx));
328
+
329
+ items.forEach((item, i) => {
330
+ item.setAttribute('tabindex', i === bounded ? '0' : '-1');
331
+ });
332
+ const target = items[bounded];
333
+ target?.focus?.();
334
+ if (typeof onFocusItem === 'function') {
335
+ onFocusItem(target, bounded);
336
+ }
337
+ }
338
+
339
+ host.addEventListener(
340
+ 'keydown',
341
+ (e) => {
342
+ const items = (getItems() || []).filter(
343
+ (el) => el && !el.disabled && !el.hasAttribute?.('disabled') && el.getAttribute?.('aria-disabled') !== 'true'
344
+ );
345
+ if (!items.length) return;
346
+
347
+ const activeEl = host.shadowRoot?.activeElement || document.activeElement;
348
+ const currentIdx = items.findIndex((item) => item === activeEl || item === e.target || item.contains?.(e.target));
349
+ const orient = typeof orientation === 'function' ? orientation() : orientation;
350
+ const rtl = isRTL(host);
351
+
352
+ const nextKey = orient === 'vertical' ? 'ArrowDown' : (rtl ? 'ArrowLeft' : 'ArrowRight');
353
+ const prevKey = orient === 'vertical' ? 'ArrowUp' : (rtl ? 'ArrowRight' : 'ArrowLeft');
354
+
355
+ if (e.key === nextKey || (orient === 'both' && (e.key === 'ArrowRight' || e.key === 'ArrowDown'))) {
356
+ e.preventDefault();
357
+ focusIndex(items, currentIdx === -1 ? 0 : currentIdx + 1);
358
+ return;
359
+ }
360
+
361
+ if (e.key === prevKey || (orient === 'both' && (e.key === 'ArrowLeft' || e.key === 'ArrowUp'))) {
362
+ e.preventDefault();
363
+ focusIndex(items, currentIdx === -1 ? items.length - 1 : currentIdx - 1);
364
+ return;
365
+ }
366
+
367
+ if (e.key === 'Home') {
368
+ e.preventDefault();
369
+ focusIndex(items, 0);
370
+ return;
371
+ }
372
+
373
+ if (e.key === 'End') {
374
+ e.preventDefault();
375
+ focusIndex(items, items.length - 1);
376
+ return;
377
+ }
378
+
379
+ if (typeahead && e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
380
+ typeBuffer += e.key.toLowerCase();
381
+ if (typeTimer) clearTimeout(typeTimer);
382
+ typeTimer = setTimeout(() => {
383
+ typeBuffer = '';
384
+ }, 500);
385
+
386
+ const start = currentIdx === -1 ? 0 : (currentIdx + 1) % items.length;
387
+ for (let offset = 0; offset < items.length; offset++) {
388
+ const i = (start + offset) % items.length;
389
+ const label = (items[i].getAttribute?.('aria-label') || items[i].textContent || '').trim().toLowerCase();
390
+ if (label.startsWith(typeBuffer)) {
391
+ e.preventDefault();
392
+ focusIndex(items, i);
393
+ break;
394
+ }
395
+ }
396
+ }
397
+ },
398
+ { signal: abortSignal }
399
+ );
400
+
401
+ return () => {
402
+ if (typeTimer) clearTimeout(typeTimer);
403
+ controller.abort();
404
+ };
405
+ }
406
+
407
+ // ==========================================
408
+ // 4. Dismissable Layer Stack (Overlays)
409
+ // ==========================================
410
+
411
+ const dismissableStack = [];
412
+
413
+ /**
414
+ * Registers an overlay (dialog, drawer, popover, dropdown, context menu) in a
415
+ * top-most-first stack so Escape and outside clicks dismiss only the topmost open layer.
416
+ */
417
+ export function createDismissableLayer(
418
+ host,
419
+ {
420
+ isOpen = () => true,
421
+ onDismiss,
422
+ closeOnEscape = true,
423
+ closeOnOutsideClick = true,
424
+ signal = host?.signal,
425
+ } = {}
426
+ ) {
427
+ if (!host || typeof onDismiss !== 'function' || typeof document === 'undefined') {
428
+ return () => {};
429
+ }
430
+
431
+ const layer = { host, isOpen, onDismiss, closeOnEscape, closeOnOutsideClick };
432
+ dismissableStack.push(layer);
433
+
434
+ const isTopMostOpen = () => {
435
+ for (let i = dismissableStack.length - 1; i >= 0; i--) {
436
+ if (dismissableStack[i].isOpen()) {
437
+ return dismissableStack[i] === layer;
438
+ }
439
+ }
440
+ return false;
441
+ };
442
+
443
+ const controller = new AbortController();
444
+ const abortSignal = controller.signal;
445
+ if (signal) {
446
+ if (signal.aborted) {
447
+ const idx = dismissableStack.indexOf(layer);
448
+ if (idx !== -1) dismissableStack.splice(idx, 1);
449
+ return () => {};
450
+ }
451
+ signal.addEventListener('abort', () => cleanup(), { once: true });
452
+ }
453
+
454
+ document.addEventListener(
455
+ 'keydown',
456
+ (e) => {
457
+ if (!closeOnEscape || e.key !== 'Escape') return;
458
+ if (!isTopMostOpen()) return;
459
+ e.preventDefault();
460
+ onDismiss('escape', e);
461
+ },
462
+ { signal: abortSignal }
463
+ );
464
+
465
+ document.addEventListener(
466
+ 'pointerdown',
467
+ (e) => {
468
+ if (!closeOnOutsideClick || !isTopMostOpen()) return;
469
+ const path = typeof e.composedPath === 'function' ? e.composedPath() : [];
470
+ if (path.includes(host) || host.contains(e.target)) return;
471
+ onDismiss('outside-click', e);
472
+ },
473
+ { signal: abortSignal }
474
+ );
475
+
476
+ function cleanup() {
477
+ controller.abort();
478
+ const idx = dismissableStack.indexOf(layer);
479
+ if (idx !== -1) dismissableStack.splice(idx, 1);
480
+ }
481
+
482
+ return cleanup;
483
+ }
484
+
485
+ // ==========================================
486
+ // 5. Unified Selection Behavior (Single / Multiple / Range)
487
+ // ==========================================
488
+
489
+ /**
490
+ * Signal-backed selection controller supporting single, multiple, and Shift-range
491
+ * selection plus Ctrl/Cmd+A select-all and disabledKeys filtering.
492
+ */
493
+ export function createSelectionBehavior({
494
+ mode = 'single',
495
+ getKeys = () => [],
496
+ initialKeys = [],
497
+ disabledKeys = [],
498
+ onSelectionChange = null,
499
+ } = {}) {
500
+ const disabledSet = new Set(disabledKeys);
501
+ const selectedKeys = createSignal(new Set(initialKeys));
502
+ let anchorKey = initialKeys.length > 0 ? initialKeys[initialKeys.length - 1] : null;
503
+
504
+ function commit(nextSet) {
505
+ selectedKeys.value = nextSet;
506
+ if (typeof onSelectionChange === 'function') {
507
+ onSelectionChange(nextSet);
508
+ }
509
+ }
510
+
511
+ function isDisabled(key) {
512
+ return disabledSet.has(key);
513
+ }
514
+
515
+ function isSelected(key) {
516
+ return selectedKeys.value.has(key);
517
+ }
518
+
519
+ function selectRange(fromKey, toKey) {
520
+ if (mode !== 'multiple') return;
521
+ const keys = getKeys();
522
+ const startIdx = keys.indexOf(fromKey);
523
+ const endIdx = keys.indexOf(toKey);
524
+ if (startIdx === -1 || endIdx === -1) return;
525
+ const [lo, hi] = startIdx <= endIdx ? [startIdx, endIdx] : [endIdx, startIdx];
526
+ const next = new Set(selectedKeys.peek());
527
+ for (let i = lo; i <= hi; i++) {
528
+ if (!isDisabled(keys[i])) {
529
+ next.add(keys[i]);
530
+ }
531
+ }
532
+ commit(next);
533
+ }
534
+
535
+ function select(key, { shiftKey = false, ctrlKey = false, metaKey = false, toggle = false } = {}) {
536
+ if (mode === 'none' || isDisabled(key)) return;
537
+
538
+ if (mode === 'single') {
539
+ const current = selectedKeys.peek();
540
+ if (toggle && current.has(key)) {
541
+ anchorKey = null;
542
+ commit(new Set());
543
+ } else {
544
+ anchorKey = key;
545
+ commit(new Set([key]));
546
+ }
547
+ return;
548
+ }
549
+
550
+ // Multiple mode
551
+ if (shiftKey && anchorKey !== null) {
552
+ selectRange(anchorKey, key);
553
+ return;
554
+ }
555
+
556
+ const next = new Set(ctrlKey || metaKey || toggle ? selectedKeys.peek() : []);
557
+ if (next.has(key) && (ctrlKey || metaKey || toggle)) {
558
+ next.delete(key);
559
+ } else {
560
+ next.add(key);
561
+ }
562
+ anchorKey = key;
563
+ commit(next);
564
+ }
565
+
566
+ function toggleKey(key) {
567
+ select(key, { toggle: true });
568
+ }
569
+
570
+ function selectAll() {
571
+ if (mode !== 'multiple') return;
572
+ const next = new Set(getKeys().filter((k) => !isDisabled(k)));
573
+ commit(next);
574
+ }
575
+
576
+ function clear() {
577
+ anchorKey = null;
578
+ commit(new Set());
579
+ }
580
+
581
+ return {
582
+ selectedKeys,
583
+ isSelected,
584
+ select,
585
+ toggle: toggleKey,
586
+ selectRange,
587
+ selectAll,
588
+ clear,
589
+ };
590
+ }
591
+
592
+ // ==========================================
593
+ // 6. Accessible Reorder / Drag & Drop Behavior (Pointer + Keyboard)
594
+ // ==========================================
595
+
596
+ /**
597
+ * Enables accessible pointer (HTML5 DnD) AND keyboard reordering on a list/collection:
598
+ * - Keyboard: Space/Enter grabs item -> Arrow keys move -> Space/Enter drops, Escape cancels.
599
+ * - Pointer: dragstart / dragover / drop with `data-dragging` and `data-drop-target` states.
600
+ * - Announces grab, move, drop, and cancel updates to screen readers via `announce()`.
601
+ */
602
+ export function createReorderBehavior(
603
+ host,
604
+ {
605
+ getItems,
606
+ orientation = 'vertical',
607
+ onReorder,
608
+ signal = host?.signal,
609
+ } = {}
610
+ ) {
611
+ if (!host || typeof getItems !== 'function' || typeof onReorder !== 'function') {
612
+ return () => {};
613
+ }
614
+
615
+ const controller = new AbortController();
616
+ const abortSignal = controller.signal;
617
+ if (signal) {
618
+ if (signal.aborted) return () => {};
619
+ signal.addEventListener('abort', () => controller.abort(), { once: true });
620
+ }
621
+
622
+ let grabbedIndex = -1;
623
+ let currentIndex = -1;
624
+ let dragSourceIndex = -1;
625
+
626
+ function clearStates(items) {
627
+ for (const el of items) {
628
+ setHostState(el, 'dragging', false);
629
+ setHostState(el, 'drop-target', false);
630
+ }
631
+ }
632
+
633
+ // Keyboard accessible reorder
634
+ host.addEventListener(
635
+ 'keydown',
636
+ (e) => {
637
+ const items = getItems() || [];
638
+ if (!items.length) return;
639
+
640
+ const idx = items.findIndex((el) => el === e.target || el.contains?.(e.target));
641
+ if (idx === -1) return;
642
+
643
+ if (e.key === ' ' || e.key === 'Enter') {
644
+ e.preventDefault();
645
+ if (grabbedIndex === -1) {
646
+ grabbedIndex = idx;
647
+ currentIndex = idx;
648
+ setHostState(items[idx], 'dragging', true);
649
+ announce(`Grabbed item ${idx + 1} of ${items.length}. Use arrow keys to move, Space to drop, Escape to cancel.`);
650
+ } else {
651
+ const from = grabbedIndex;
652
+ const to = currentIndex;
653
+ const item = items[from];
654
+ clearStates(items);
655
+ grabbedIndex = -1;
656
+ currentIndex = -1;
657
+ if (from !== to) {
658
+ onReorder({ fromIndex: from, toIndex: to, item });
659
+ }
660
+ announce(`Dropped item at position ${to + 1} of ${items.length}.`);
661
+ }
662
+ return;
663
+ }
664
+
665
+ if (grabbedIndex === -1) return;
666
+
667
+ if (e.key === 'Escape') {
668
+ e.preventDefault();
669
+ clearStates(items);
670
+ grabbedIndex = -1;
671
+ currentIndex = -1;
672
+ announce('Reorder cancelled.');
673
+ return;
674
+ }
675
+
676
+ const rtl = isRTL(host);
677
+ const nextKey = orientation === 'horizontal' ? (rtl ? 'ArrowLeft' : 'ArrowRight') : 'ArrowDown';
678
+ const prevKey = orientation === 'horizontal' ? (rtl ? 'ArrowRight' : 'ArrowLeft') : 'ArrowUp';
679
+
680
+ if (e.key === nextKey && currentIndex < items.length - 1) {
681
+ e.preventDefault();
682
+ setHostState(items[currentIndex], 'drop-target', false);
683
+ currentIndex++;
684
+ setHostState(items[currentIndex], 'drop-target', true);
685
+ announce(`Position ${currentIndex + 1} of ${items.length}.`);
686
+ } else if (e.key === prevKey && currentIndex > 0) {
687
+ e.preventDefault();
688
+ setHostState(items[currentIndex], 'drop-target', false);
689
+ currentIndex--;
690
+ setHostState(items[currentIndex], 'drop-target', true);
691
+ announce(`Position ${currentIndex + 1} of ${items.length}.`);
692
+ }
693
+ },
694
+ { signal: abortSignal }
695
+ );
696
+
697
+ // Pointer HTML5 Drag & Drop
698
+ host.addEventListener(
699
+ 'dragstart',
700
+ (e) => {
701
+ const items = getItems() || [];
702
+ const idx = items.findIndex((el) => el === e.target || el.contains?.(e.target));
703
+ if (idx === -1) return;
704
+ dragSourceIndex = idx;
705
+ setHostState(items[idx], 'dragging', true);
706
+ if (e.dataTransfer) {
707
+ e.dataTransfer.effectAllowed = 'move';
708
+ e.dataTransfer.setData?.('text/plain', String(idx));
709
+ }
710
+ },
711
+ { signal: abortSignal }
712
+ );
713
+
714
+ host.addEventListener(
715
+ 'dragover',
716
+ (e) => {
717
+ if (dragSourceIndex === -1) return;
718
+ const items = getItems() || [];
719
+ const idx = items.findIndex((el) => el === e.target || el.contains?.(e.target));
720
+ if (idx === -1) return;
721
+ e.preventDefault();
722
+ items.forEach((el, i) => setHostState(el, 'drop-target', i === idx && i !== dragSourceIndex));
723
+ },
724
+ { signal: abortSignal }
725
+ );
726
+
727
+ host.addEventListener(
728
+ 'drop',
729
+ (e) => {
730
+ if (dragSourceIndex === -1) return;
731
+ e.preventDefault();
732
+ const items = getItems() || [];
733
+ const toIndex = items.findIndex((el) => el === e.target || el.contains?.(e.target));
734
+ const fromIndex = dragSourceIndex;
735
+ const item = items[fromIndex];
736
+ clearStates(items);
737
+ dragSourceIndex = -1;
738
+ if (toIndex !== -1 && fromIndex !== toIndex) {
739
+ onReorder({ fromIndex, toIndex, item });
740
+ announce(`Moved item to position ${toIndex + 1} of ${items.length}.`);
741
+ }
742
+ },
743
+ { signal: abortSignal }
744
+ );
745
+
746
+ host.addEventListener(
747
+ 'dragend',
748
+ () => {
749
+ const items = getItems() || [];
750
+ clearStates(items);
751
+ dragSourceIndex = -1;
752
+ },
753
+ { signal: abortSignal }
754
+ );
755
+
756
+ return () => {
757
+ controller.abort();
758
+ clearStates(getItems() || []);
759
+ };
760
+ }