@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.
- package/bundle/index.d.ts +727 -256
- package/bundle/index.d.ts.map +1 -1
- package/bundle/index.js +2046 -35
- package/bundle/index.js.map +1 -1
- package/dist/ac-text.d.ts +1 -1
- package/dist/ac-text.js +1 -1
- package/dist/{ac-token-TCLAZeVg.d.ts → ac-token--_vCHXWw.d.ts} +2 -2
- package/dist/{ac-token-TCLAZeVg.d.ts.map → ac-token--_vCHXWw.d.ts.map} +1 -1
- package/dist/ac-token.d.ts +1 -1
- package/dist/ac-token.js +1 -1
- package/dist/button.d.ts +1 -1
- package/dist/button.d.ts.map +1 -1
- package/dist/colour-picker.d.ts +1 -1
- package/dist/crumbs.d.ts +1 -1
- package/dist/crumbs.js +3 -3
- package/dist/{data-grid-Db4QpnII.d.ts → data-grid-BddUjAti.d.ts} +34 -2
- package/dist/data-grid-BddUjAti.d.ts.map +1 -0
- package/dist/data-grid.d.ts +1 -1
- package/dist/data-grid.js +180 -7
- package/dist/data-grid.js.map +1 -1
- package/dist/detail-list-Br0WAnry.d.ts +167 -0
- package/dist/detail-list-Br0WAnry.d.ts.map +1 -0
- package/dist/detail-list.d.ts +3 -0
- package/dist/detail-list.js +1115 -0
- package/dist/detail-list.js.map +1 -0
- package/dist/grid-list-B_orPsot.d.ts +304 -0
- package/dist/grid-list-B_orPsot.d.ts.map +1 -0
- package/dist/grid-list.d.ts +3 -0
- package/dist/grid-list.js +933 -0
- package/dist/grid-list.js.map +1 -0
- package/dist/{grouped-item-lister-BWlC9S4e.d.ts → grouped-item-lister-fdZHVxFM.d.ts} +3 -3
- package/dist/{grouped-item-lister-BWlC9S4e.d.ts.map → grouped-item-lister-fdZHVxFM.d.ts.map} +1 -1
- package/dist/grouped-item-lister.d.ts +1 -1
- package/dist/{icon-DR_3rSyZ.d.ts → icon-CDGprSdE.d.ts} +2 -2
- package/dist/icon-CDGprSdE.d.ts.map +1 -0
- package/dist/icons.d.ts +2 -2
- package/dist/{index-C59-JEPl.d.ts → index-9AhaHIT2.d.ts} +3 -3
- package/dist/{index-C59-JEPl.d.ts.map → index-9AhaHIT2.d.ts.map} +1 -1
- package/dist/{index-DsjpDksO.d.ts → index-CS9yM8L-.d.ts} +2 -2
- package/dist/{index-DsjpDksO.d.ts.map → index-CS9yM8L-.d.ts.map} +1 -1
- package/dist/{index-BUB5SICW.d.ts → index-CoqtMSd9.d.ts} +2 -2
- package/dist/{index-BUB5SICW.d.ts.map → index-CoqtMSd9.d.ts.map} +1 -1
- package/dist/{index-CJ5fshD3.d.ts → index-UvnoZUAo.d.ts} +2 -2
- package/dist/{index-CJ5fshD3.d.ts.map → index-UvnoZUAo.d.ts.map} +1 -1
- package/dist/{index-BOUaDIW-.d.ts → index-tq6f8007.d.ts} +2 -2
- package/dist/{index-BOUaDIW-.d.ts.map → index-tq6f8007.d.ts.map} +1 -1
- package/dist/index.d.ts +185 -240
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +375 -1002
- package/dist/index.js.map +1 -1
- package/dist/interaction-Cr13azbM.js +3 -0
- package/dist/{labelled-input-base-Dp_9KP0G.d.ts → labelled-input-base-DiTme1JO.d.ts} +2 -2
- package/dist/{labelled-input-base-Dp_9KP0G.d.ts.map → labelled-input-base-DiTme1JO.d.ts.map} +1 -1
- package/dist/labelled-radial-input.d.ts +2 -2
- package/dist/labelled-radial-input.d.ts.map +1 -1
- package/dist/labelled-range-input.d.ts +1 -1
- package/dist/labelled-slider-input.d.ts +1 -1
- package/dist/list-item-animation-DuiwgN3l.js +112 -0
- package/dist/list-item-animation-DuiwgN3l.js.map +1 -0
- package/dist/list-selection-controller-CUo-Hhcm.js +338 -0
- package/dist/list-selection-controller-CUo-Hhcm.js.map +1 -0
- package/dist/{list-selection-types-DSuRNWpx.d.ts → list-selection-types-B5ioL-dG.d.ts} +6 -1
- package/dist/list-selection-types-B5ioL-dG.d.ts.map +1 -0
- package/dist/{menu-DMzjkVnK.js → menu-Bg90Qr0B.js} +3 -3
- package/dist/{menu-DMzjkVnK.js.map → menu-Bg90Qr0B.js.map} +1 -1
- package/dist/{menu-item-D2S4i8u1.js → menu-item-Bx-Fs7jq.js} +3 -3
- package/dist/{menu-item-D2S4i8u1.js.map → menu-item-Bx-Fs7jq.js.map} +1 -1
- package/dist/{menu-item-ZmkXNjek.d.ts → menu-item-CZi9vy5O.d.ts} +2 -2
- package/dist/{menu-item-ZmkXNjek.d.ts.map → menu-item-CZi9vy5O.d.ts.map} +1 -1
- package/dist/menu.d.ts +2 -2
- package/dist/menu.js +2 -2
- package/dist/miller.d.ts +1 -1
- package/dist/miller.js +2 -2
- package/dist/narrowed-text.js +2 -2
- package/dist/panel.d.ts +1 -1
- package/dist/plots.js +1 -1
- package/dist/select-horiz.js +2 -2
- package/dist/{split-layout-C5SYbDrq.d.ts → split-layout-JK3xWVX2.d.ts} +2 -2
- package/dist/{split-layout-C5SYbDrq.d.ts.map → split-layout-JK3xWVX2.d.ts.map} +1 -1
- package/dist/split-layout.d.ts +1 -1
- package/dist/{tab-list-DbMIL520.d.ts → tab-list-CGyPt07Z.d.ts} +2 -2
- package/dist/{tab-list-DbMIL520.d.ts.map → tab-list-CGyPt07Z.d.ts.map} +1 -1
- package/dist/tabs.d.ts +1 -1
- package/dist/{tickled-controller-Ds1DMyG7.d.ts → tickled-controller-Bn3YdQsM.d.ts} +12 -1
- package/dist/{tickled-controller-Ds1DMyG7.d.ts.map → tickled-controller-Bn3YdQsM.d.ts.map} +1 -1
- package/dist/{tickled-controller-h9GmJ_bU.js → tickled-controller-C66DgJHl.js} +16 -1
- package/dist/tickled-controller-C66DgJHl.js.map +1 -0
- package/dist/{titlebar-B23MrIbI.d.ts → titlebar-Bj5pfdw_.d.ts} +2 -2
- package/dist/{titlebar-B23MrIbI.d.ts.map → titlebar-Bj5pfdw_.d.ts.map} +1 -1
- package/dist/titlebar.d.ts +1 -1
- package/dist/{tree-Ch4W8qXQ.js → tree-B74zdI60.js} +116 -17
- package/dist/tree-B74zdI60.js.map +1 -0
- package/dist/tree.d.ts +6 -3
- package/dist/tree.d.ts.map +1 -1
- package/dist/tree.js +1 -1
- package/dist/vertical-list-CQSEVeOT.d.ts +140 -0
- package/dist/vertical-list-CQSEVeOT.d.ts.map +1 -0
- package/dist/vertical-list.d.ts +3 -121
- package/dist/vertical-list.js +710 -1
- package/dist/vertical-list.js.map +1 -0
- package/dist/{xy-axis-DWizs0bt.js → xy-axis-VrX8dmvS.js} +2 -2
- package/dist/{xy-axis-DWizs0bt.js.map → xy-axis-VrX8dmvS.js.map} +1 -1
- package/docs-user/README.md +1 -0
- package/docs-user/data-grid.md +51 -2
- package/docs-user/detail-list.md +38 -0
- package/docs-user/grid-list.md +274 -0
- package/docs-user/index.json +7 -2
- package/docs-user/llms.txt +1 -0
- package/docs-user/tree.md +13 -0
- package/docs-user/vertical-list.md +51 -1
- package/llms.txt +1 -0
- package/package.json +17 -2
- package/dist/data-grid-Db4QpnII.d.ts.map +0 -1
- package/dist/icon-DR_3rSyZ.d.ts.map +0 -1
- package/dist/interaction-D5XdKzbR.js +0 -2
- package/dist/list-selection-types-DSuRNWpx.d.ts.map +0 -1
- package/dist/tickled-controller-h9GmJ_bU.js.map +0 -1
- package/dist/tree-Ch4W8qXQ.js.map +0 -1
- package/dist/vertical-list-B4w_ksJk.js +0 -814
- package/dist/vertical-list-B4w_ksJk.js.map +0 -1
- package/dist/vertical-list.d.ts.map +0 -1
package/docs-user/data-grid.md
CHANGED
|
@@ -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
|
|
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
|
|
package/docs-user/detail-list.md
CHANGED
|
@@ -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`.
|
package/docs-user/index.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ixfx/components",
|
|
3
|
-
"version": "0.7.
|
|
4
|
-
"generated": "2026-09-
|
|
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",
|
package/docs-user/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/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.
|
|
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 +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":"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"}
|