@ixfx/components 0.7.3 → 0.7.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.
Files changed (121) hide show
  1. package/bundle/index.d.ts +727 -256
  2. package/bundle/index.d.ts.map +1 -1
  3. package/bundle/index.js +2046 -35
  4. package/bundle/index.js.map +1 -1
  5. package/dist/ac-text.d.ts +1 -1
  6. package/dist/ac-text.js +1 -1
  7. package/dist/{ac-token-TCLAZeVg.d.ts → ac-token--_vCHXWw.d.ts} +2 -2
  8. package/dist/{ac-token-TCLAZeVg.d.ts.map → ac-token--_vCHXWw.d.ts.map} +1 -1
  9. package/dist/ac-token.d.ts +1 -1
  10. package/dist/ac-token.js +1 -1
  11. package/dist/button.d.ts +1 -1
  12. package/dist/button.d.ts.map +1 -1
  13. package/dist/colour-picker.d.ts +1 -1
  14. package/dist/crumbs.d.ts +1 -1
  15. package/dist/crumbs.js +3 -3
  16. package/dist/{data-grid-Db4QpnII.d.ts → data-grid-BddUjAti.d.ts} +34 -2
  17. package/dist/data-grid-BddUjAti.d.ts.map +1 -0
  18. package/dist/data-grid.d.ts +1 -1
  19. package/dist/data-grid.js +180 -7
  20. package/dist/data-grid.js.map +1 -1
  21. package/dist/detail-list-Br0WAnry.d.ts +167 -0
  22. package/dist/detail-list-Br0WAnry.d.ts.map +1 -0
  23. package/dist/detail-list.d.ts +3 -0
  24. package/dist/detail-list.js +1115 -0
  25. package/dist/detail-list.js.map +1 -0
  26. package/dist/grid-list-B_orPsot.d.ts +304 -0
  27. package/dist/grid-list-B_orPsot.d.ts.map +1 -0
  28. package/dist/grid-list.d.ts +3 -0
  29. package/dist/grid-list.js +933 -0
  30. package/dist/grid-list.js.map +1 -0
  31. package/dist/{grouped-item-lister-BWlC9S4e.d.ts → grouped-item-lister-fdZHVxFM.d.ts} +3 -3
  32. package/dist/{grouped-item-lister-BWlC9S4e.d.ts.map → grouped-item-lister-fdZHVxFM.d.ts.map} +1 -1
  33. package/dist/grouped-item-lister.d.ts +1 -1
  34. package/dist/{icon-DR_3rSyZ.d.ts → icon-CDGprSdE.d.ts} +2 -2
  35. package/dist/icon-CDGprSdE.d.ts.map +1 -0
  36. package/dist/icons.d.ts +2 -2
  37. package/dist/{index-C59-JEPl.d.ts → index-9AhaHIT2.d.ts} +3 -3
  38. package/dist/{index-C59-JEPl.d.ts.map → index-9AhaHIT2.d.ts.map} +1 -1
  39. package/dist/{index-DsjpDksO.d.ts → index-CS9yM8L-.d.ts} +2 -2
  40. package/dist/{index-DsjpDksO.d.ts.map → index-CS9yM8L-.d.ts.map} +1 -1
  41. package/dist/{index-BUB5SICW.d.ts → index-CoqtMSd9.d.ts} +2 -2
  42. package/dist/{index-BUB5SICW.d.ts.map → index-CoqtMSd9.d.ts.map} +1 -1
  43. package/dist/{index-CJ5fshD3.d.ts → index-UvnoZUAo.d.ts} +2 -2
  44. package/dist/{index-CJ5fshD3.d.ts.map → index-UvnoZUAo.d.ts.map} +1 -1
  45. package/dist/{index-BOUaDIW-.d.ts → index-tq6f8007.d.ts} +2 -2
  46. package/dist/{index-BOUaDIW-.d.ts.map → index-tq6f8007.d.ts.map} +1 -1
  47. package/dist/index.d.ts +185 -240
  48. package/dist/index.d.ts.map +1 -1
  49. package/dist/index.js +375 -1002
  50. package/dist/index.js.map +1 -1
  51. package/dist/interaction-Cr13azbM.js +3 -0
  52. package/dist/{labelled-input-base-Dp_9KP0G.d.ts → labelled-input-base-DiTme1JO.d.ts} +2 -2
  53. package/dist/{labelled-input-base-Dp_9KP0G.d.ts.map → labelled-input-base-DiTme1JO.d.ts.map} +1 -1
  54. package/dist/labelled-radial-input.d.ts +2 -2
  55. package/dist/labelled-radial-input.d.ts.map +1 -1
  56. package/dist/labelled-range-input.d.ts +1 -1
  57. package/dist/labelled-slider-input.d.ts +1 -1
  58. package/dist/list-item-animation-DuiwgN3l.js +112 -0
  59. package/dist/list-item-animation-DuiwgN3l.js.map +1 -0
  60. package/dist/list-selection-controller-CUo-Hhcm.js +338 -0
  61. package/dist/list-selection-controller-CUo-Hhcm.js.map +1 -0
  62. package/dist/{list-selection-types-DSuRNWpx.d.ts → list-selection-types-B5ioL-dG.d.ts} +6 -1
  63. package/dist/list-selection-types-B5ioL-dG.d.ts.map +1 -0
  64. package/dist/{menu-DMzjkVnK.js → menu-Bg90Qr0B.js} +3 -3
  65. package/dist/{menu-DMzjkVnK.js.map → menu-Bg90Qr0B.js.map} +1 -1
  66. package/dist/{menu-item-D2S4i8u1.js → menu-item-Bx-Fs7jq.js} +3 -3
  67. package/dist/{menu-item-D2S4i8u1.js.map → menu-item-Bx-Fs7jq.js.map} +1 -1
  68. package/dist/{menu-item-ZmkXNjek.d.ts → menu-item-CZi9vy5O.d.ts} +2 -2
  69. package/dist/{menu-item-ZmkXNjek.d.ts.map → menu-item-CZi9vy5O.d.ts.map} +1 -1
  70. package/dist/menu.d.ts +2 -2
  71. package/dist/menu.js +2 -2
  72. package/dist/miller.d.ts +1 -1
  73. package/dist/miller.js +2 -2
  74. package/dist/narrowed-text.js +2 -2
  75. package/dist/panel.d.ts +1 -1
  76. package/dist/plots.js +1 -1
  77. package/dist/select-horiz.js +2 -2
  78. package/dist/{split-layout-C5SYbDrq.d.ts → split-layout-JK3xWVX2.d.ts} +2 -2
  79. package/dist/{split-layout-C5SYbDrq.d.ts.map → split-layout-JK3xWVX2.d.ts.map} +1 -1
  80. package/dist/split-layout.d.ts +1 -1
  81. package/dist/{tab-list-DbMIL520.d.ts → tab-list-CGyPt07Z.d.ts} +2 -2
  82. package/dist/{tab-list-DbMIL520.d.ts.map → tab-list-CGyPt07Z.d.ts.map} +1 -1
  83. package/dist/tabs.d.ts +1 -1
  84. package/dist/{tickled-controller-Ds1DMyG7.d.ts → tickled-controller-Bn3YdQsM.d.ts} +12 -1
  85. package/dist/{tickled-controller-Ds1DMyG7.d.ts.map → tickled-controller-Bn3YdQsM.d.ts.map} +1 -1
  86. package/dist/{tickled-controller-h9GmJ_bU.js → tickled-controller-C66DgJHl.js} +16 -1
  87. package/dist/tickled-controller-C66DgJHl.js.map +1 -0
  88. package/dist/{titlebar-B23MrIbI.d.ts → titlebar-Bj5pfdw_.d.ts} +2 -2
  89. package/dist/{titlebar-B23MrIbI.d.ts.map → titlebar-Bj5pfdw_.d.ts.map} +1 -1
  90. package/dist/titlebar.d.ts +1 -1
  91. package/dist/{tree-Ch4W8qXQ.js → tree-B74zdI60.js} +116 -17
  92. package/dist/tree-B74zdI60.js.map +1 -0
  93. package/dist/tree.d.ts +6 -3
  94. package/dist/tree.d.ts.map +1 -1
  95. package/dist/tree.js +1 -1
  96. package/dist/vertical-list-CQSEVeOT.d.ts +140 -0
  97. package/dist/vertical-list-CQSEVeOT.d.ts.map +1 -0
  98. package/dist/vertical-list.d.ts +3 -121
  99. package/dist/vertical-list.js +710 -1
  100. package/dist/vertical-list.js.map +1 -0
  101. package/dist/{xy-axis-DWizs0bt.js → xy-axis-VrX8dmvS.js} +2 -2
  102. package/dist/{xy-axis-DWizs0bt.js.map → xy-axis-VrX8dmvS.js.map} +1 -1
  103. package/docs-user/README.md +1 -0
  104. package/docs-user/data-grid.md +51 -2
  105. package/docs-user/detail-list.md +38 -0
  106. package/docs-user/grid-list.md +274 -0
  107. package/docs-user/index.json +7 -2
  108. package/docs-user/llms.txt +1 -0
  109. package/docs-user/tree.md +13 -0
  110. package/docs-user/vertical-list.md +51 -1
  111. package/llms.txt +1 -0
  112. package/package.json +17 -2
  113. package/dist/data-grid-Db4QpnII.d.ts.map +0 -1
  114. package/dist/icon-DR_3rSyZ.d.ts.map +0 -1
  115. package/dist/interaction-D5XdKzbR.js +0 -2
  116. package/dist/list-selection-types-DSuRNWpx.d.ts.map +0 -1
  117. package/dist/tickled-controller-h9GmJ_bU.js.map +0 -1
  118. package/dist/tree-Ch4W8qXQ.js.map +0 -1
  119. package/dist/vertical-list-B4w_ksJk.js +0 -814
  120. package/dist/vertical-list-B4w_ksJk.js.map +0 -1
  121. package/dist/vertical-list.d.ts.map +0 -1
@@ -65,6 +65,30 @@ grid.getRowKey = (row, i) => row.key ?? row.id ?? String(i);
65
65
 
66
66
  Reassign `rows` to update. Sorting is derived from `sortState`.
67
67
 
68
+ When the row set changes without a wholesale replace — rows spliced in, rows
69
+ filtered out — the new rows fade in and, for ~0.3s afterwards, every row slides
70
+ to its new position instead of snapping (so an inserted row's neighbours make
71
+ room and a removed row's gap closes). Skipped under `prefers-reduced-motion:
72
+ reduce`; timing is `--data-grid-row-move-duration` (default `200ms`).
73
+
74
+ ### Streaming appends — `appendRows()`
75
+
76
+ Reassigning `rows` re-runs `_applySort([...rows])` + `_rebuildFlat()` every
77
+ time — O(n log n) per batch, quadratic over a full load. When feeding the grid
78
+ from a stream (paged fetch, incremental scan), use `appendRows()` instead:
79
+
80
+ ```ts
81
+ for await (const batch of stream) {
82
+ grid.appendRows(batch);
83
+ }
84
+ ```
85
+
86
+ It still sets `rows` to a new array reference (reactivity preserved) but
87
+ **bypasses the `rows` setter's full rebuild** — the derived arrays are extended
88
+ over the appended slice only. When a sort is active the new rows show unsorted
89
+ for one frame, then a single coalesced re-sort runs. Scroll position, selection
90
+ and cursor are preserved across the append.
91
+
68
92
  ---
69
93
 
70
94
  ## Selection & interaction
@@ -76,7 +100,19 @@ Reassign `rows` to update. Sorting is derived from `sortState`.
76
100
 
77
101
  See `ixfx-vertical-list` README for mode table. Data-grid adds checkbox column in `checked` mode.
78
102
 
79
- Programmatic: selection is `Set<string>` of row keys (`_selectedKeys` private, read via events).
103
+ ### Programmatic selection & cursor
104
+
105
+ ```ts
106
+ grid.selectedKeys; // ReadonlySet<string> of selected row keys
107
+ grid.selectedKeys = ['r3', 'r7']; // replace (clamped to known rows, single-mode keeps the last)
108
+ grid.selectKeys(['r3', 'r7']); // alias of the setter
109
+
110
+ grid.tickleRow('r7'); // move the row cursor + scroll it into view
111
+ grid.tickledKey; // row key under the cursor, or undefined
112
+ ```
113
+
114
+ The setter fires `datagrid-select` `{ selectedKeys, previous }` only when the
115
+ selection actually changes.
80
116
 
81
117
  ---
82
118
 
@@ -194,6 +230,10 @@ Demo: `Score` is random float `0–100` with 0–3 decimals, `align:'right'`, `f
194
230
 
195
231
  Gear menu (`ixfx-menu-trigger` placement `bottom-end`, `inset-area: block-end span-inline-end`) lists `Columns` (check-items) and `Group by` (radio). Toggle visibility via `col.visible=false` or menu. Event: `datagrid-column-visibility` `{key, visible}`.
196
232
 
233
+ `column-menu` attribute: `auto` (default) renders the gear menu; `none`
234
+ suppresses it entirely. `col.visible` + `datagrid-column-visibility` still give
235
+ full external control, so `none` lets a host own the column-visibility UI.
236
+
197
237
  Other events: `datagrid-column-reorder` `{from,to,columns}`, `datagrid-column-resize` `{key,width}`, `datagrid-cell-click` `{rowKey,colKey,rowIndex,colIndex}`, `datagrid-cell-edit` `{rowKey,colKey,oldValue,newValue}`.
198
238
 
199
239
  ---
@@ -218,6 +258,7 @@ Grid is focusable (`tabindex=0`). When not editing:
218
258
  | Variable | Default | Description |
219
259
  |---|---|---|
220
260
  | `--data-grid-row-height` | `28px` | Row height |
261
+ | `--data-grid-row-move-duration` | `200ms` | Insertion / removal animation duration |
221
262
  | `--data-grid-header-height` | `32px` | Header height |
222
263
  | `--data-grid-bg` | `var(--surface-3)` | Grid background |
223
264
  | `--data-grid-header-bg` | `var(--surface-2)` | Header background |
@@ -239,10 +280,18 @@ No `::part` exports yet (header/row/cell are shadow-internal).
239
280
  | `startRowEdit` | `(rowKey)` | Open row editors |
240
281
  | `stopEdit` | `()` | Cancel editors |
241
282
  | `getVisibleRange` | `()=>{startRow,endRow,startCol,endCol}` | Virtual window |
283
+ | `appendRows` | `(rows)` | Add rows without a full re-sort/rebuild — for streaming |
284
+ | `selectKeys` / `set selectedKeys` | `(keys)` | Replace the selection by row key |
285
+ | `tickleRow` | `(key)` | Move the row cursor and scroll it into view |
286
+
287
+ | Getter | Type | |
288
+ |---|---|---|
289
+ | `selectedKeys` | `ReadonlySet<string>` | Selected row keys |
290
+ | `tickledKey` | `string \| undefined` | Row key under the cursor |
242
291
 
243
292
  ---
244
293
 
245
294
  ## Demo
246
295
 
247
- `demo/data-grid.html` + `demo/data-grid.ts`: 200 rows, `Department` random, `Score` float, `Name`/`Department` editable (`user` mode, slow double-click; `Tab`/`Up`/`Down` navigation; `Enter` from tickled row). Controls: Selection/Interaction/Group by/Editability + `Edit first row` (manual).
296
+ `demo/data-grid.html` + `demo/data-grid.ts`: 200 rows, `Department` random, `Score` float, `Name`/`Department` editable (`user` mode, slow double-click; `Tab`/`Up`/`Down` navigation; `Enter` from tickled row). Controls: Selection/Interaction/Group by/Editability/`column-menu` + `Edit first row` (manual), a `Stream +5,000 rows` button (`appendRows`), and `selectKeys` / `tickleRow` buttons.
248
297
 
@@ -87,8 +87,17 @@ list.addItem('Image 01.png');
87
87
  const li = document.createElement('li');
88
88
  li.textContent = 'Custom item';
89
89
  list.addItem(li);
90
+
91
+ // removeItem / removeItems return a Promise that resolves once the row is gone
92
+ list.removeItems(list.selectedItems);
90
93
  ```
91
94
 
95
+ Rows added mid-list collapse + fade in; `removeItem` / `removeItems` collapse +
96
+ fade them out before detaching, so the rows around them slide to make or close
97
+ the gap. A bulk populate isn't animated, and it's all skipped under
98
+ `prefers-reduced-motion: reduce` (`--ixfx-list-item-move-duration`, default
99
+ `200ms`).
100
+
92
101
  ---
93
102
 
94
103
  ## Item types
@@ -191,6 +200,35 @@ list.clearSelection(); // Clear all selections
191
200
  list.selectAll(); // Select all visible items (if permitted)
192
201
  ```
193
202
 
203
+ ### Key-based selection
204
+
205
+ `Element` references die when the item set is rebuilt (re-fetch, re-sort,
206
+ filter). Drive selection by a stable **`data-key`** (or `data-value`) instead —
207
+ the Element API is unchanged, the key API is additive. Object items built from
208
+ `items` / a provider get their key stamped automatically from `keyProperty`.
209
+
210
+ ```typescript
211
+ list.selectKeys(['row-3', 'row-7']); // replace selection; unknown keys ignored
212
+ list.addSelectedKeys(['row-9']); // multi-select modes only
213
+ list.removeSelectedKeys(['row-3']);
214
+ list.selectedKeys; // ReadonlySet<string>
215
+
216
+ list.focusKey('row-7'); // move cursor to an item + scroll into view
217
+ list.tickledKey; // key under the cursor, or undefined
218
+
219
+ list.addEventListener('list-select', ({ detail }) => {
220
+ console.log([...detail.selectedKeys]); // carried alongside detail.selected
221
+ });
222
+ ```
223
+
224
+ Restore a selection across a data reload:
225
+
226
+ ```typescript
227
+ const keep = [...list.selectedKeys];
228
+ list.items = await fetchRows(); // Element refs are stale...
229
+ list.selectKeys(keep); // ...keys still resolve
230
+ ```
231
+
194
232
  ---
195
233
 
196
234
  ## Interaction modes
@@ -0,0 +1,274 @@
1
+ # `ixfx-grid-list`
2
+
3
+ A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —
4
+ with selection, keyboard navigation, and captions. Windowed rendering keeps the
5
+ DOM small regardless of item count; the same component does a wrapping grid, a
6
+ single vertical column, or a horizontally-scrolling strip.
7
+
8
+ ---
9
+
10
+ ## Contents
11
+
12
+ 1. [Quick start](#quick-start)
13
+ 2. [Items & keys](#items--keys)
14
+ 3. [Sizing & layout](#sizing--layout)
15
+ 4. [Captions](#captions)
16
+ 5. [Orientation](#orientation)
17
+ 6. [Selection](#selection)
18
+ 7. [Cursor](#cursor)
19
+ 8. [Events](#events)
20
+ 9. [Keyboard](#keyboard)
21
+ 10. [Virtualisation](#virtualisation)
22
+ 11. [CSS parts](#css-parts)
23
+ 12. [Choosing a list component](#choosing-a-list-component)
24
+
25
+ ---
26
+
27
+ ## Quick start
28
+
29
+ ```html
30
+ <ixfx-grid-list id="grid" selection-mode="single" item-size="120" gap="8">
31
+ <div class="tile" data-key="a" data-label="Apple">🍎</div>
32
+ <div class="tile" data-key="b" data-label="Banana">🍌</div>
33
+ <div class="tile" data-key="c" data-label="Cherry">🍒</div>
34
+ </ixfx-grid-list>
35
+
36
+ <script type="module">
37
+ import '@ixfx/components/grid-list';
38
+
39
+ const grid = document.querySelector('#grid');
40
+ grid.addEventListener('list-select', ({ detail }) => {
41
+ console.log([...detail.selectedKeys]);
42
+ });
43
+ </script>
44
+ ```
45
+
46
+ Items are **light-DOM children**. Each is projected into its own virtualised
47
+ cell via a named `<slot>`. Add or remove children at any time — a
48
+ `MutationObserver` picks the change up and re-renders.
49
+
50
+ ```typescript
51
+ import type { GridListElement } from '@ixfx/components/grid-list';
52
+
53
+ const grid = document.querySelector<GridListElement>('#grid')!;
54
+ for (const item of data) {
55
+ const el = document.createElement('div');
56
+ el.className = 'tile';
57
+ el.dataset.key = item.id;
58
+ el.dataset.label = item.name;
59
+ el.textContent = item.glyph;
60
+ grid.appendChild(el);
61
+ }
62
+ ```
63
+
64
+ ---
65
+
66
+ ## Items & keys
67
+
68
+ | Item attribute | Purpose |
69
+ |---|---|
70
+ | `data-key` (or `data-value`) | Stable identity — for key-based selection, `focusKey`, and `visibleKeys()`. Recommended on every item. |
71
+ | `data-label` | Caption text (see [Captions](#captions)). Alternatively put the text in a `[data-grid-list-caption]` descendant. |
72
+ | `not-checked` | Item can't be tickled / checked (skipped by the cursor). |
73
+ | `hidden` | Item is excluded from layout and navigation. |
74
+
75
+ ---
76
+
77
+ ## Sizing & layout
78
+
79
+ | Property / attribute | Default | Description |
80
+ |---|---|---|
81
+ | `itemSize` / `item-size` | `160` | Cell width in px. Also the square's height for `separate` / `under` / `overlaid` / `hidden`. |
82
+ | `gap` | `8` | Gap between cells, px. |
83
+ | `captionHeight` / `caption-height` | `24` | Height reserved for the caption band in `separate` / `under`. |
84
+
85
+ Values are clamped and rounded. Changing `item-size` / `gap` re-anchors the
86
+ scroll on the item nearest the viewport centre (zoom stays put rather than
87
+ jumping to the top-left corner).
88
+
89
+ ---
90
+
91
+ ## Captions
92
+
93
+ `caption-style` — how the caption relates to the content:
94
+
95
+ | value | layout |
96
+ |---|---|
97
+ | `hidden` | No caption. Cell height = `item-size`. |
98
+ | `separate` | Content in a square; caption a **detached** label below it. Square and caption highlight independently (macOS Finder icon view). |
99
+ | `under` (default) | One box: content on top, caption strip **inside** it below. One selection outline. |
100
+ | `overlaid` | Caption floats over the content. |
101
+
102
+ `caption-align` — `left` \| `middle` (default) \| `right`. Text alignment; also
103
+ positions the pill in `separate`.
104
+
105
+ `overlaid` only:
106
+
107
+ - `caption-position` — `top` \| `middle` \| `bottom` (default).
108
+ - `caption-backdrop` — `scrim` (default, flat translucent panel) \| `gradient`
109
+ (fades away from the caption edge) \| `blur` (frosted) \| `none` (text +
110
+ shadow, no panel).
111
+
112
+ ```html
113
+ <ixfx-grid-list caption-style="separate" caption-align="left"></ixfx-grid-list>
114
+ <ixfx-grid-list caption-style="overlaid" caption-position="top" caption-backdrop="gradient"></ixfx-grid-list>
115
+ ```
116
+
117
+ ---
118
+
119
+ ## Orientation
120
+
121
+ `orientation`:
122
+
123
+ | value | layout | scrolls |
124
+ |---|---|---|
125
+ | `grid` (default) | wraps across as many columns as fit | vertically |
126
+ | `row` | a single row of items | **horizontally** |
127
+ | `column` | a single column of items | vertically |
128
+
129
+ `row` is the virtualised horizontal strip; `column` is the recommended
130
+ large-list replacement for `ixfx-vertical-list`.
131
+
132
+ ---
133
+
134
+ ## Selection
135
+
136
+ `selection-mode` (`none` \| `single` \| `multiple`) and `interaction-mode`
137
+ (`standard` \| `implicit` \| `manual` \| `checked` \| `sticky` \| `vscode`) match
138
+ the other list components — see the `ixfx-vertical-list` README for the mode
139
+ table.
140
+
141
+ ### Element API
142
+
143
+ ```typescript
144
+ grid.select(el); // replace with one item
145
+ grid.selectMany([a, b]); // selection-mode="multiple" only
146
+ grid.deselect(el);
147
+ grid.clearSelection();
148
+ grid.selectAll();
149
+ grid.selectedItems; // ReadonlySet<Element>
150
+ ```
151
+
152
+ ### Key-based selection
153
+
154
+ `Element` references die when the item set is rebuilt. With a `data-key` on each
155
+ item, drive selection by key instead — additive, the Element API is unchanged.
156
+
157
+ ```typescript
158
+ grid.selectKeys(['a', 'c']); // replace; unknown keys ignored
159
+ grid.addSelectedKeys(['b']); // multi-select modes only
160
+ grid.removeSelectedKeys(['a']);
161
+ grid.selectedKeys; // ReadonlySet<string>
162
+
163
+ grid.addEventListener('list-select', ({ detail }) => {
164
+ console.log([...detail.selectedKeys]); // alongside detail.selected
165
+ });
166
+ ```
167
+
168
+ Restore across a reload:
169
+
170
+ ```typescript
171
+ const keep = [...grid.selectedKeys];
172
+ grid.replaceChildren(...(await fetchTiles()));
173
+ grid.selectKeys(keep);
174
+ ```
175
+
176
+ ---
177
+
178
+ ## Cursor
179
+
180
+ The "tickled" cursor follows hover (mouse) or arrow keys (keyboard).
181
+
182
+ ```typescript
183
+ grid.focusKey('b'); // move the cursor to an item and scroll it into view
184
+ grid.tickledKey; // key under the cursor, or undefined
185
+ ```
186
+
187
+ ---
188
+
189
+ ## Events
190
+
191
+ All bubble and are `composed`.
192
+
193
+ | Event | Detail | When |
194
+ |---|---|---|
195
+ | `list-select` | `{ selected, previous, selectedKeys }` | Selection changes by any means |
196
+ | `list-activate` | `{ item }` | Double-click or `Enter` on an item |
197
+ | `list-item-click` | `{ item }` | Single click / `Enter` |
198
+ | `list-tickle` | `{ item }` | Cursor moves onto an item |
199
+ | `grid-list-viewport-change` | `{ visibleKeys }` | Scroll, resize, or content change — the rendered window moved |
200
+
201
+ ---
202
+
203
+ ## Keyboard
204
+
205
+ | Key | `grid` | `row` / `column` |
206
+ |---|---|---|
207
+ | `ArrowLeft` / `ArrowRight` | ∓1 item | ∓1 item |
208
+ | `ArrowUp` / `ArrowDown` | ∓/± one row | ∓1 item |
209
+ | `Home` / `End` | first / last | first / last |
210
+ | `PageUp` / `PageDown` | ± one screen of rows | ± one screen of items |
211
+ | `Enter` | activate | activate |
212
+ | `Space` | toggle selection | toggle selection |
213
+ | `Escape` | clear selection | clear selection |
214
+ | `Ctrl` / `Cmd` + `A` | select all (multi modes) | select all (multi modes) |
215
+
216
+ ---
217
+
218
+ ## Virtualisation
219
+
220
+ Only the cells in (or near) the viewport are in the DOM.
221
+
222
+ ```typescript
223
+ grid.count; // total items
224
+ grid.renderedCount; // cells currently in the shadow DOM
225
+ grid.visibleKeys(); // data-key of items in the current window
226
+ ```
227
+
228
+ `grid-list` handles tens of thousands of children in every orientation.
229
+
230
+ ---
231
+
232
+ ## Scroll fade & insertion animation
233
+
234
+ The scrollable edge is fade-masked whenever there's more content that way — a
235
+ zero-JS `scroll-timeline` mask (`scroll-fade-y` for `grid` / `column`,
236
+ `scroll-fade-x` for `row`). See `docs/infra-theming.md` → *Scroll Fade*; tune the
237
+ reach with `--scroll-fade-width` (default `30px`).
238
+
239
+ When the child list changes **mid-list** (not a first populate or a wholesale
240
+ `replaceChildren`), the cells slide to their new position rather than snapping —
241
+ so an inserted item's neighbours make room and a removed item's gap closes — and
242
+ a freshly inserted cell also fades in. The transition is confined to a short
243
+ window after the mutation, so it never fires during scroll virtualisation, and
244
+ it's suppressed under `prefers-reduced-motion: reduce`. Duration:
245
+ `--grid-list-item-move-duration` (default `200ms`).
246
+
247
+ ---
248
+
249
+ ## CSS parts
250
+
251
+ | Part | Element |
252
+ |---|---|
253
+ | `viewport` | The scroll container |
254
+ | `item` | A cell |
255
+ | `thumb` | The square holding the slotted content |
256
+ | `caption` | The caption element (absent for `caption-style="hidden"`) |
257
+
258
+ Host CSS custom properties: `--grid-list-item-bg`, `--grid-list-radius`,
259
+ `--grid-list-gap`, `--grid-list-item-move-duration` (insertion animation,
260
+ default `200ms`), `--scroll-fade-width` (edge fade reach, default `30px`), plus
261
+ the shared `--item-bg-*` / `--accent` theme tokens.
262
+
263
+ ---
264
+
265
+ ## Choosing a list component
266
+
267
+ - **Large lists** — prefer `ixfx-grid-list` with `orientation="column"` over
268
+ `ixfx-vertical-list`. `vertical-list` renders every child; `grid-list` is
269
+ windowed.
270
+ - **Small, declarative, richly-slotted lists** — `ixfx-vertical-list` stays the
271
+ simpler choice.
272
+ - **Horizontal virtualised strip** — `ixfx-grid-list` with `orientation="row"`.
273
+ - **Tabular data with columns / sort / grouping / inline edit** —
274
+ `ixfx-data-grid`.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@ixfx/components",
3
- "version": "0.7.3",
4
- "generated": "2026-09-06T18:27:10.873Z",
3
+ "version": "0.7.4",
4
+ "generated": "2026-09-08T16:59:30.569Z",
5
5
  "components": [
6
6
  {
7
7
  "name": "ac-text",
@@ -63,6 +63,11 @@
63
63
  "summary": "Primitives for typical form layout with responsive label positioning and data binding.",
64
64
  "path": "docs-user/form.md"
65
65
  },
66
+ {
67
+ "name": "grid-list",
68
+ "summary": "A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —",
69
+ "path": "docs-user/grid-list.md"
70
+ },
66
71
  {
67
72
  "name": "grouped-item-lister",
68
73
  "summary": "A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own",
@@ -23,6 +23,7 @@ import '@ixfx/components/data-grid';
23
23
  - [dock](docs-user/dock.md): Dockable, movable panels like VS Code / Photoshop. Drag a panel by its
24
24
  - [editable-label](docs-user/editable-label.md): Inline editable text components. `ixfx-editable-number` extends `ixfx-editable-label` with drag-to-adjust and fill-bar visualization.
25
25
  - [form](docs-user/form.md): Primitives for typical form layout with responsive label positioning and data binding.
26
+ - [grid-list](docs-user/grid-list.md): A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —
26
27
  - [grouped-item-lister](docs-user/grouped-item-lister.md): A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own
27
28
  - [icons](docs-user/icons.md): A centralized SVG icon system for `@ixfx/components`. Icons are stored by name, can be overridden globally, and all components that use a given icon re-render automatically when it changes.
28
29
  - [incr-search](docs-user/incr-search.md): Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.
package/docs-user/tree.md CHANGED
@@ -463,6 +463,18 @@ Each column is a separate `role="listbox"` with `aria-label` showing the parent
463
463
 
464
464
  ---
465
465
 
466
+ ## Row animation
467
+
468
+ Rows that appear — a branch expanded, a node added to `root` / the model —
469
+ collapse + fade in, and the rows below slide down to make room. Rows that
470
+ disappear — a branch collapsed, a node removed — are kept as fading "ghost" rows
471
+ until they've collapsed out, so the gap closes smoothly. Above ~50 rows changing
472
+ at once the animation is skipped, as it is entirely under
473
+ `prefers-reduced-motion: reduce`. Duration: `--ixfx-list-item-move-duration`
474
+ (default `200ms`).
475
+
476
+ ---
477
+
466
478
  ## CSS variables
467
479
 
468
480
  ### Shared / themed
@@ -493,6 +505,7 @@ These are set by the global theme and inherited by all tree components.
493
505
  | `--tree-indent` | `20px` | Indentation per depth level |
494
506
  | `--tree-item-height` | `28px` | Height of each row |
495
507
  | `--tree-caret-size` | `10px` | Expand/collapse caret size |
508
+ | `--ixfx-list-item-move-duration` | `200ms` | Row enter / leave animation duration |
496
509
 
497
510
  ### `ixfx-miller-list` specific
498
511
 
@@ -313,13 +313,21 @@ list.addItem(myElement);
313
313
  // In checked mode, add a row that shows no checkbox and can't be checked
314
314
  list.addItem('Header', { notChecked: true });
315
315
 
316
- // Remove a specific element
316
+ // Remove a specific element (returns a Promise that resolves once it's gone)
317
317
  list.removeItem(element);
318
+ list.removeItems(list.selectedItems);
318
319
 
319
320
  // Remove all items and clear selection
320
321
  list.clearItems();
321
322
  ```
322
323
 
324
+ Items added mid-list — via `addItem`, a direct `appendChild`, or a framework
325
+ binding — collapse + fade in, and the rows below slide down to make room.
326
+ `removeItem` / `removeItems` play the reverse (collapse + fade out) and then
327
+ detach, so the gap closes smoothly. A bulk populate isn't animated, and
328
+ everything is skipped under `prefers-reduced-motion: reduce`. Tune the timing
329
+ with the `--ixfx-list-item-move-duration` custom property (default `200ms`).
330
+
323
331
  ### Reading the selection
324
332
 
325
333
  ```typescript
@@ -341,6 +349,48 @@ list.addEventListener('list-select', ({ detail }) => {
341
349
  });
342
350
  ```
343
351
 
352
+ ### Key-based selection
353
+
354
+ `Element` references die the moment you rebuild the item set (re-fetch, external
355
+ re-sort, filter). Give each item a **`data-key`** (or `data-value`) and drive
356
+ selection by that stable string instead. The Element API keeps working
357
+ unchanged — the key API is additive.
358
+
359
+ ```html
360
+ <ixfx-vertical-list selection-mode="multiple">
361
+ <li data-key="a">Apple</li>
362
+ <li data-key="b">Banana</li>
363
+ <li data-key="c">Cherry</li>
364
+ </ixfx-vertical-list>
365
+ ```
366
+
367
+ ```typescript
368
+ list.selectKeys(['a', 'c']); // replace selection; unknown keys ignored
369
+ list.addSelectedKeys(['b']); // multi-select modes only
370
+ list.removeSelectedKeys(['a']);
371
+ list.selectedKeys; // ReadonlySet<string>, e.g. Set { 'b', 'c' }
372
+
373
+ list.focusKey('b'); // move the cursor to an item + scroll it into view
374
+ list.tickledKey; // key under the cursor, or undefined
375
+
376
+ // list-select carries keys too
377
+ list.addEventListener('list-select', ({ detail }) => {
378
+ console.log([...detail.selectedKeys]);
379
+ });
380
+ ```
381
+
382
+ Restore a selection across a data reload:
383
+
384
+ ```typescript
385
+ const keep = [...list.selectedKeys];
386
+ list.setItems(await fetchRows()); // Element refs are now stale
387
+ list.selectKeys(keep); // ...but the keys still resolve
388
+ ```
389
+
390
+ The `data-key` requirement is documented, not enforced: items without a key
391
+ simply never appear in `selectedKeys` and can't be targeted by `selectKeys` /
392
+ `focusKey`.
393
+
344
394
  ### Filtering by state
345
395
 
346
396
  Use `selectedFilter()` to iterate over items based on their selection or checked state. Pass `'selected'`, `'checked'`, or `'either'` to filter accordingly:
package/llms.txt CHANGED
@@ -23,6 +23,7 @@ import '@ixfx/components/data-grid';
23
23
  - [dock](docs-user/dock.md): Dockable, movable panels like VS Code / Photoshop. Drag a panel by its
24
24
  - [editable-label](docs-user/editable-label.md): Inline editable text components. `ixfx-editable-number` extends `ixfx-editable-label` with drag-to-adjust and fill-bar visualization.
25
25
  - [form](docs-user/form.md): Primitives for typical form layout with responsive label positioning and data binding.
26
+ - [grid-list](docs-user/grid-list.md): A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —
26
27
  - [grouped-item-lister](docs-user/grouped-item-lister.md): A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own
27
28
  - [icons](docs-user/icons.md): A centralized SVG icon system for `@ixfx/components`. Icons are stored by name, can be overridden globally, and all components that use a given icon re-render automatically when it changes.
28
29
  - [incr-search](docs-user/incr-search.md): Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@ixfx/components",
3
3
  "type": "module",
4
- "version": "0.7.3",
4
+ "version": "0.7.4",
5
5
  "packageManager": "pnpm@10.0.0",
6
6
  "description": "Web components for ixfx — Lit-based UI toolkit",
7
7
  "author": "Clint Heyer",
@@ -20,6 +20,18 @@
20
20
  "types": "./dist/incr-search.d.ts",
21
21
  "import": "./dist/incr-search.js"
22
22
  },
23
+ "./grid-list": {
24
+ "types": "./dist/grid-list.d.ts",
25
+ "import": "./dist/grid-list.js"
26
+ },
27
+ "./detail-list": {
28
+ "types": "./dist/detail-list.d.ts",
29
+ "import": "./dist/detail-list.js"
30
+ },
31
+ "./vertical-list": {
32
+ "types": "./dist/vertical-list.d.ts",
33
+ "import": "./dist/vertical-list.js"
34
+ },
23
35
  "./*.js": {
24
36
  "types": "./dist/*.d.ts",
25
37
  "import": "./dist/*.js"
@@ -35,6 +47,7 @@
35
47
  "engines": { "node": ">=20" },
36
48
  "scripts": {
37
49
  "typecheck": "tsc --noEmit",
50
+ "test": "vitest run",
38
51
  "start": "vite serve",
39
52
  "dev": "vite serve",
40
53
  "lint": "eslint",
@@ -76,11 +89,13 @@
76
89
  "eslint": "10.8.1",
77
90
  "eslint-plugin-format": "2.0.1",
78
91
  "globals": "17.9.0",
92
+ "happy-dom": "^20.14.0",
79
93
  "knip": "6.32.0",
80
94
  "lit": "3.3.3",
81
95
  "tsdown": "0.22.14",
82
96
  "typescript": "npm:@typescript/typescript6@6.0.2",
83
97
  "typescript-eslint": "8.66.0",
84
- "vite": "8.2.1"
98
+ "vite": "8.2.1",
99
+ "vitest": "^5.0.0"
85
100
  }
86
101
  }
@@ -1 +0,0 @@
1
- {"version":3,"file":"data-grid-Db4QpnII.d.ts","names":[],"sources":["../src/data-grid/types.ts","../src/data-grid/data-grid.ts"],"mappings":";;;KAAY;KACA;KACA;KACA;WAA+B;WAAsB,WAAW;;KAChE;KAEA,sBAAsB;WACvB,KAAK;WACL,QAAQ,eAAe;WACvB;WACA;WACA;EACT,SAAS;EACT;;KAEU,sBAAsB,gBAAgB,KAAK,sBAAsB;KAEjE,eAAe;EACzB;EACA;EACA;EACA;EACA;EACA;EACA;EACA,UAAU,GAAG,GAAG,GAAG;EACnB;EACA;EACA;EACA,YAAY,KAAK,GAAG,KAAK,eAAe,IAAI;EAC5C;EACA;EACA;EACA,SAAS,qBAAqB,sBAAsB;EACpD,gBAAgB;IAAyB;IAAe;;EACxD,aAAa,gBAAgB,KAAK,GAAG,KAAK,eAAe;;KAG/C,mBAAmB,gBAAgB,oBAAoB;KAEvD;KAEA;KACA;EAA4B;;KAE5B,kBAAkB,MAAM,KAAK,GAAG;KAChC,gBAAgB,gBAAgB,KAAK;KACrC,sBAAsB,kBAAkB;;;KClCxC;WAAgC,MAAM;WAA4B,UAAU;;KAC5E,oBAAoB,YAAY;KAChC;WAAkC,cAAc;WAA8B,UAAU;;KACxF,sBAAsB,YAAY;KAClC;WAAyC;WAAuB;WAAqB,kBAAkB;;KACvG,6BAA6B,YAAY;KACzC;WAAwC;WAAsB;;KAC9D,4BAA4B,YAAY;KACxC;WAA4C;WAAsB;;KAClE,gCAAgC,YAAY;KAC5C;WAAqC;WAAyB;WAAyB;WAA2B;;KAClH,yBAAyB,YAAY;KACrC;WAAoC;WAAyB;WAAyB;WAA4B;;KAClH,wBAAwB,YAAY;KAEpC;WAAuC,SAAS;;KAChD,2BAA2B,YAAY;UAClC;EACf,iBAAiB;EACjB,mBAAmB;EACnB,2BAA2B;EAC3B,0BAA0B;EAC1B,8BAA8B;EAC9B,uBAAuB;EACvB,sBAAsB;EACtB,yBAAyB;;cAId,wBAAwB;SACnB,sBAAM;EAoFK,SAAS;EACT;EAC8B,eAAe;EACb,iBAAiB;EAC5C,WAAW;EACU;EACrB,WAAW;EACX,oBAAoB;EACpB,sBAAsB,cAAc,KAAK;EAC9B,aAAa;EAExB,SAAS;EACiB;EAC1B,YAAY;;EAEZ;EACgD;EAChD,kBAAkB;UAC1C;UAES;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UAEW;UACK;UAEzB;UAKA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;EAEC;EAQA;UAOD;YAgBW;YAaA,QAAQ,SAAS;YAmBjB,WAAW,SAAS;UAmB/B;UAQA;UAiCA;UAOA;UAoBA;UAYA;UAcA;UA0BA;UAKA;UAMA;UAsFA;UAYA;UAEA;UAcA;UAKA;UAiBA;UAsBA;UAmCA;UAsKA;UAUA;UAKA;UAQA;;EAeR,UAAU,gBAAgB;;EAK1B,aAAa;EAWb;EAIA,mBAAmB,mBAAmB,aAAa,8BAA8B,6BAA6B,UAAU;UAkBhH;UAWA;UAYA;UAyBA;UACA;UA2BA;UAYA;UAkCA;EAoBR;IAAqB;IAAkB;IAAgB;IAAkB;;UASjE;UAaA;YAQW,wBAAM;;QAsMnB;YACI;IAAwB,kBAAkB;;;UAErC;EACf,oBAAoB,gBAAgB,yBAAyB,MAAM,GAAG,WAAW,MAAM,iBAAiB,OAAO,wBAAwB,aAAa,oBAAoB,sCAAsC,cAAc,UAAU,oCAAoC,oBAAoB;EAC9R,uBAAuB,gBAAgB,yBAAyB,MAAM,GAAG,WAAW,MAAM,iBAAiB,OAAO,wBAAwB,aAAa,oBAAoB,mCAAmC,cAAc,UAAU,oCAAoC,oBAAoB"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"icon-DR_3rSyZ.d.ts","names":[],"sources":["../src/icons/icon.ts"],"mappings":";;cAUa,wBAAwB;;EACvB;EACgB;EAChB;EAC0C;EACU;EAevD;EAMA;YAMU,wBAAM,2BAAA;YA4BN,QAAQ,SAAS;SAWpB,sBAAM;;QAiDhB;YACI;IACR,aAAa"}
@@ -1,2 +0,0 @@
1
- import "./tickled-controller-h9GmJ_bU.js";
2
- import "./tickled-styles-BrAHEj1q.js";
@@ -1 +0,0 @@
1
- {"version":3,"file":"list-selection-types-DSuRNWpx.d.ts","names":[],"sources":["../src/interaction/list-selection-types.ts"],"mappings":";;;;;;;;;KASY;;;;;;;;;;;;;KAcA;KAEA;WACD,UAAU,YAAY;WACtB,UAAU,YAAY;;KAGrB;WACD,MAAM;;KAGL;WACD,MAAM;;KAGL;WACD,MAAM;;KAGL,kBAAkB,YAAY;KAC9B,kBAAkB,YAAY;KAC9B,oBAAoB,YAAY;KAChC,qBAAqB,YAAY;UAE5B;EACf,eAAe;EACf,eAAe;EACf,iBAAiB;EACjB,mBAAmB"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"tickled-controller-h9GmJ_bU.js","names":[],"sources":["../src/interaction/tickled-controller.ts"],"sourcesContent":["import type { ReactiveController, ReactiveControllerHost } from 'lit';\n\n/**\n * Represents an item that can be tickled (highlighted via hover or keyboard navigation)\n */\nexport type TickledItem<T = unknown> = {\n /**\n * Unique identifier for the item (e.g., index, id, path)\n */\n readonly id: T;\n\n /**\n * Whether the item is currently enabled/interactive\n */\n readonly enabled?: boolean;\n};\n\n/**\n * Input mode determines which mechanism controls the tickled state\n */\nexport type InputMode = `keyboard` | `mouse`;\n\n/**\n * Configuration for TickledController\n */\nexport type TickledControllerConfig<T> = {\n /**\n * Function to retrieve all items that can be tickled\n */\n getItems: () => ReadonlyArray<TickledItem<T>>;\n\n /**\n * Optional callback when an item becomes tickled\n * Use this for side effects like opening submenus\n * @param id - The id of the newly tickled item, or undefined if nothing is tickled\n */\n onTickle?: (id: T | undefined) => void;\n\n /**\n * Optional callback fired after any state change (tickled id or input mode)\n * Use this to sync DOM attributes for slotted content that can't use reactive rendering\n *\n * For components that render items directly, this is usually not needed as\n * Lit's reactive rendering will handle updates automatically via requestUpdate()\n *\n * @example\n * ```ts\n * onStateChange: () => {\n * // Sync data-tickled attributes for slotted items\n * const items = this.getItems();\n * items.forEach((item, i) => {\n * if (this.tickled.isTickled(i)) {\n * item.setAttribute('data-tickled', '');\n * } else {\n * item.removeAttribute('data-tickled');\n * }\n * });\n * }\n * ```\n */\n onStateChange?: () => void;\n\n /**\n * Optional initial input mode (defaults to 'mouse')\n */\n initialInputMode?: InputMode;\n\n /**\n * Whether keyboard navigation wraps from last to first and vice versa.\n * - 'stop' (default): navigation stops at the boundary\n * - 'wrap': navigation wraps around\n */\n itemWrap?: `stop` | `wrap`;\n};\n\n/**\n * ReactiveController that manages \"tickled\" state for interactive lists.\n *\n * A \"tickled\" item is one that is under active attention via hover (mouse mode)\n * or keyboard focus (keyboard mode). Only one item can be tickled at a time.\n *\n * The input mode determines which mechanism controls tickled state:\n * - Mouse mode: hover controls tickled, keyboard navigation ignored\n * - Keyboard mode: keyboard navigation controls tickled, hover ignored\n *\n * Last interaction wins - any mouse hover switches to mouse mode, any keyboard\n * navigation switches to keyboard mode.\n *\n * ## Global Mouse Tracking\n *\n * This controller uses a single, ref-counted global `pointermove` listener (shared\n * across all instances) to track actual mouse movement. This prevents `pointerenter`\n * events caused by content scrolling from incorrectly switching to mouse mode when\n * the user is actually using keyboard navigation. The listener is attached when the\n * first host connects and removed once the last host disconnects.\n *\n * @example\n * ```ts\n * class MyList extends LitElement {\n * private tickled = new TickledController(this, {\n * getItems: () => this.items.map((item, i) => ({ id: i, enabled: !item.disabled })),\n * onTickle: (id) => {\n * // Optional: perform side effect when item is tickled\n * console.log('Tickled item:', id);\n * }\n * });\n *\n * render() {\n * return html`\n * <ul @pointerleave=${(e) => this.tickled.handlePointerLeave(e)}>\n * ${this.items.map((item, i) => html`\n * <li\n * class=\"item ${this.tickled.isTickled(i) ? 'tickled' : ''}\"\n * @pointerenter=${() => this.tickled.handlePointerEnter(i)}\n * >${item.label}</li>\n * `)}\n * </ul>\n * `;\n * }\n *\n * private handleKeyDown(e: KeyboardEvent) {\n * if (e.key === 'ArrowDown') {\n * this.tickled.handleKeyboardNavigation('next');\n * } else if (e.key === 'ArrowUp') {\n * this.tickled.handleKeyboardNavigation('previous');\n * }\n * }\n * }\n * ```\n */\nexport class TickledController<T = number> implements ReactiveController {\n private host: ReactiveControllerHost;\n private config: TickledControllerConfig<T>;\n private _tickledId: T | undefined = undefined;\n private _inputMode: InputMode;\n\n private static _lastMouseClientX: number = Number.NaN;\n private static _lastMouseClientY: number = Number.NaN;\n private static _mouseMovedSinceKeyboard: boolean = true;\n private static _listenerRefCount: number = 0;\n\n private static readonly _onGlobalPointerMove = (e: PointerEvent): void => {\n TickledController.handleGlobalPointerMove(e.clientX, e.clientY);\n };\n\n constructor(host: ReactiveControllerHost, config: TickledControllerConfig<T>) {\n this.host = host;\n this.config = config;\n this._inputMode = config.initialInputMode ?? `mouse`;\n host.addController(this);\n }\n\n hostConnected(): void {\n if (TickledController._listenerRefCount === 0) {\n document.addEventListener(`pointermove`, TickledController._onGlobalPointerMove, { passive: true });\n }\n TickledController._listenerRefCount++;\n }\n\n hostDisconnected(): void {\n TickledController._listenerRefCount--;\n if (TickledController._listenerRefCount === 0) {\n document.removeEventListener(`pointermove`, TickledController._onGlobalPointerMove);\n }\n }\n\n /**\n * Get the current input mode\n */\n get inputMode(): InputMode {\n return this._inputMode;\n }\n\n /**\n * Get the currently tickled item id\n */\n get tickledId(): T | undefined {\n return this._tickledId;\n }\n\n /**\n * Check if a specific item is tickled\n */\n isTickled(id: T): boolean {\n return this._tickledId === id;\n }\n\n /**\n * Handle global pointer move event.\n * Called automatically by the global listener.\n * Tracks mouse movement to distinguish real hover from content scrolling.\n */\n private static handleGlobalPointerMove(clientX: number, clientY: number): void {\n if (!Number.isNaN(TickledController._lastMouseClientX)) {\n if (\n clientX !== TickledController._lastMouseClientX\n || clientY !== TickledController._lastMouseClientY\n ) {\n TickledController._mouseMovedSinceKeyboard = true;\n }\n }\n TickledController._lastMouseClientX = clientX;\n TickledController._lastMouseClientY = clientY;\n }\n\n /**\n * Check if actual mouse movement has occurred since last keyboard interaction.\n * Used to distinguish real hover/leave from content-scrolling-induced events.\n */\n static get hasMouseMovedSinceKeyboard(): boolean {\n return TickledController._mouseMovedSinceKeyboard;\n }\n\n /**\n * Handle pointer enter event on an item (mouse hover).\n * Only processes if actual mouse movement is detected (not content scrolling).\n * Switches to mouse mode and tickles the item.\n */\n handlePointerEnter(id: T): void {\n if (!TickledController._mouseMovedSinceKeyboard) {\n return;\n }\n\n const items = this.config.getItems();\n const item = items.find(item => item.id === id);\n if (item && item.enabled === false) {\n return;\n }\n\n const modeChanged = this._inputMode !== `mouse`;\n this._inputMode = `mouse`;\n\n const previousId = this._tickledId;\n this._tickledId = id;\n\n this.host.requestUpdate();\n\n if (previousId !== id && this.config.onTickle) {\n this.config.onTickle(id);\n }\n\n if ((previousId !== id || modeChanged) && this.config.onStateChange) {\n this.config.onStateChange();\n }\n }\n\n /**\n * Handle pointer leave event on an item.\n * Only clears tickled state if actual mouse movement is detected.\n * @param _e The pointer event (not used, but kept for API compatibility)\n */\n handlePointerLeave(_e: PointerEvent): void {\n if (TickledController._mouseMovedSinceKeyboard) {\n this.clearTickled();\n }\n }\n\n /**\n * Handle keyboard navigation.\n * Switches to keyboard mode and moves tickled state.\n *\n * @param direction - 'next', 'previous', 'first', 'last', or specific id\n */\n handleKeyboardNavigation(direction: `next` | `previous` | `first` | `last` | T): void {\n const modeChanged = this._inputMode !== `keyboard`;\n this._inputMode = `keyboard`;\n\n const items = this.config.getItems();\n const enabledItems = items.filter(item => item.enabled !== false);\n\n if (enabledItems.length === 0) {\n return;\n }\n\n let newId: T | undefined;\n\n if (direction === `first`) {\n newId = enabledItems[0].id;\n } else if (direction === `last`) {\n newId = enabledItems.at(-1)?.id;\n } else if (direction === `next` || direction === `previous`) {\n const currentIndex = enabledItems.findIndex(item => item.id === this._tickledId);\n const wrap = this.config.itemWrap === `wrap`;\n\n if (currentIndex === -1) {\n newId = direction === `next` ? enabledItems[0].id : enabledItems.at(-1)?.id;\n } else {\n const delta = direction === `next` ? 1 : -1;\n let newIndex = currentIndex + delta;\n\n if (newIndex >= 0 && newIndex < enabledItems.length) {\n newId = enabledItems[newIndex].id;\n } else if (wrap) {\n // Wrap around\n if (newIndex < 0) {\n newIndex = enabledItems.length - 1;\n } else {\n newIndex = 0;\n }\n newId = enabledItems[newIndex].id;\n }\n // If newIndex is out of bounds and wrap is disabled, keep current tickled item\n }\n } else {\n const item = enabledItems.find(item => item.id === direction);\n if (item) {\n newId = item.id;\n }\n }\n\n if (newId !== undefined) {\n const previousId = this._tickledId;\n this._tickledId = newId;\n this.host.requestUpdate();\n\n if (previousId !== newId && this.config.onTickle) {\n this.config.onTickle(newId);\n }\n\n if ((previousId !== newId || modeChanged) && this.config.onStateChange) {\n this.config.onStateChange();\n }\n }\n }\n\n /**\n * Manually set the tickled item (useful for programmatic control).\n * Does NOT change input mode.\n */\n setTickled(id: T | undefined): void {\n const previousId = this._tickledId;\n this._tickledId = id;\n this.host.requestUpdate();\n\n if (previousId !== id && this.config.onTickle) {\n this.config.onTickle(id);\n }\n\n if (previousId !== id && this.config.onStateChange) {\n this.config.onStateChange();\n }\n }\n\n /**\n * Clear the tickled state (e.g., on pointer leave).\n * Note: For pointer leave events, prefer using handlePointerLeave() which\n * checks for actual mouse movement.\n */\n clearTickled(): void {\n if (this._tickledId !== undefined) {\n this._tickledId = undefined;\n this.host.requestUpdate();\n\n if (this.config.onTickle) {\n this.config.onTickle(undefined);\n }\n\n if (this.config.onStateChange) {\n this.config.onStateChange();\n }\n }\n }\n\n /**\n * Manually set the input mode.\n * When switching to keyboard mode, resets the mouse movement tracking.\n */\n setInputMode(mode: InputMode): void {\n if (this._inputMode !== mode) {\n this._inputMode = mode;\n this.host.requestUpdate();\n\n if (mode === `keyboard`) {\n TickledController._mouseMovedSinceKeyboard = false;\n }\n\n if (this.config.onStateChange) {\n this.config.onStateChange();\n }\n }\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkIA,IAAa,oBAAb,MAAa,kBAA4D;;EAM5B,KAAA,oBAAA;;;EACA,KAAA,oBAAA;;;EACQ,KAAA,2BAAA;;;EACR,KAAA,oBAAA;;;EAEK,KAAA,wBAAA,MAA0B;GACxE,kBAAkB,wBAAwB,EAAE,SAAS,EAAE,OAAO;EAChE;;CAEA,YAAY,MAA8B,QAAoC;EAZ1C,KAAA,aAAA,KAAA;EAalC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,aAAa,OAAO,oBAAoB;EAC7C,KAAK,cAAc,IAAI;CACzB;CAEA,gBAAsB;EACpB,IAAI,kBAAkB,sBAAsB,GAC1C,SAAS,iBAAiB,eAAe,kBAAkB,sBAAsB,EAAE,SAAS,KAAK,CAAC;EAEpG,kBAAkB;CACpB;CAEA,mBAAyB;EACvB,kBAAkB;EAClB,IAAI,kBAAkB,sBAAsB,GAC1C,SAAS,oBAAoB,eAAe,kBAAkB,oBAAoB;CAEtF;;;;CAKA,IAAI,YAAuB;EACzB,OAAO,KAAK;CACd;;;;CAKA,IAAI,YAA2B;EAC7B,OAAO,KAAK;CACd;;;;CAKA,UAAU,IAAgB;EACxB,OAAO,KAAK,eAAe;CAC7B;;;;;;CAOA,OAAe,wBAAwB,SAAiB,SAAuB;EAC7E,IAAI,CAAC,OAAO,MAAM,kBAAkB,iBAAiB,GAEjD;OAAA,YAAY,kBAAkB,qBAC3B,YAAY,kBAAkB,mBAEjC,kBAAkB,2BAA2B;EAAA;EAGjD,kBAAkB,oBAAoB;EACtC,kBAAkB,oBAAoB;CACxC;;;;;CAMA,WAAW,6BAAsC;EAC/C,OAAO,kBAAkB;CAC3B;;;;;;CAOA,mBAAmB,IAAa;EAC9B,IAAI,CAAC,kBAAkB,0BACrB;EAIF,MAAM,OADQ,KAAK,OAAO,SACT,CAAC,CAAC,MAAK,SAAQ,KAAK,OAAO,EAAE;EAC9C,IAAI,QAAQ,KAAK,YAAY,OAC3B;EAGF,MAAM,cAAc,KAAK,eAAe;EACxC,KAAK,aAAa;EAElB,MAAM,aAAa,KAAK;EACxB,KAAK,aAAa;EAElB,KAAK,KAAK,cAAc;EAExB,IAAI,eAAe,MAAM,KAAK,OAAO,UACnC,KAAK,OAAO,SAAS,EAAE;EAGzB,KAAK,eAAe,MAAM,gBAAgB,KAAK,OAAO,eACpD,KAAK,OAAO,cAAc;CAE9B;;;;;;CAOA,mBAAmB,IAAwB;EACzC,IAAI,kBAAkB,0BACpB,KAAK,aAAa;CAEtB;;;;;;;CAQA,yBAAyB,WAA6D;EACpF,MAAM,cAAc,KAAK,eAAe;EACxC,KAAK,aAAa;EAGlB,MAAM,eADQ,KAAK,OAAO,SACD,CAAC,CAAC,QAAO,SAAQ,KAAK,YAAY,KAAK;EAEhE,IAAI,aAAa,WAAW,GAC1B;EAGF,IAAI;EAEJ,IAAI,cAAc,SAChB,QAAQ,aAAa,EAAE,CAAC;OACnB,IAAI,cAAc,QACvB,QAAQ,aAAa,GAAG,EAAE,CAAC,EAAE;OACxB,IAAI,cAAc,UAAU,cAAc,YAAY;GAC3D,MAAM,eAAe,aAAa,WAAU,SAAQ,KAAK,OAAO,KAAK,UAAU;GAC/E,MAAM,OAAO,KAAK,OAAO,aAAa;GAEtC,IAAI,iBAAiB,IACnB,QAAQ,cAAc,SAAS,aAAa,EAAE,CAAC,KAAK,aAAa,GAAG,EAAE,CAAC,EAAE;QACpE;IAEL,IAAI,WAAW,gBADD,cAAc,SAAS,IAAI;IAGzC,IAAI,YAAY,KAAK,WAAW,aAAa,QAC3C,QAAQ,aAAa,SAAS,CAAC;SAC1B,IAAI,MAAM;KAEf,IAAI,WAAW,GACb,WAAW,aAAa,SAAS;UAEjC,WAAW;KAEb,QAAQ,aAAa,SAAS,CAAC;IACjC;GAEF;EACF,OAAO;GACL,MAAM,OAAO,aAAa,MAAK,SAAQ,KAAK,OAAO,SAAS;GAC5D,IAAI,MACF,QAAQ,KAAK;EAEjB;EAEA,IAAI,UAAU,KAAA,GAAW;GACvB,MAAM,aAAa,KAAK;GACxB,KAAK,aAAa;GAClB,KAAK,KAAK,cAAc;GAExB,IAAI,eAAe,SAAS,KAAK,OAAO,UACtC,KAAK,OAAO,SAAS,KAAK;GAG5B,KAAK,eAAe,SAAS,gBAAgB,KAAK,OAAO,eACvD,KAAK,OAAO,cAAc;EAE9B;CACF;;;;;CAMA,WAAW,IAAyB;EAClC,MAAM,aAAa,KAAK;EACxB,KAAK,aAAa;EAClB,KAAK,KAAK,cAAc;EAExB,IAAI,eAAe,MAAM,KAAK,OAAO,UACnC,KAAK,OAAO,SAAS,EAAE;EAGzB,IAAI,eAAe,MAAM,KAAK,OAAO,eACnC,KAAK,OAAO,cAAc;CAE9B;;;;;;CAOA,eAAqB;EACnB,IAAI,KAAK,eAAe,KAAA,GAAW;GACjC,KAAK,aAAa,KAAA;GAClB,KAAK,KAAK,cAAc;GAExB,IAAI,KAAK,OAAO,UACd,KAAK,OAAO,SAAS,KAAA,CAAS;GAGhC,IAAI,KAAK,OAAO,eACd,KAAK,OAAO,cAAc;EAE9B;CACF;;;;;CAMA,aAAa,MAAuB;EAClC,IAAI,KAAK,eAAe,MAAM;GAC5B,KAAK,aAAa;GAClB,KAAK,KAAK,cAAc;GAExB,IAAI,SAAS,YACX,kBAAkB,2BAA2B;GAG/C,IAAI,KAAK,OAAO,eACd,KAAK,OAAO,cAAc;EAE9B;CACF;AACF"}