@ixfx/components 0.6.2 → 0.7.1

package/docs-user/detail-list.md

@@ -0,0 +1,398 @@
+# `ixfx-detail-list`
+
+A list that scales horizontally, not vertically. Items are laid out in equal-width columns; they flow top→bottom down a column, then wrap to the top of the next column to the right. The component has a fixed vertical extent and scrolls horizontally.
+
+Selection semantics match `ixfx-vertical-list` — same modes, same `list-*` events, same keyboard gestures — but navigation is a 2-D grid (Up/Down move within a column, Left/Right jump columns).
+
+---
+
+## Contents
+
+1. [Quick start](#quick-start)
+2. [Item types](#item-types)
+3. [Properties](#properties)
+4. [Selection](#selection)
+5. [Interaction modes](#interaction-modes)
+6. [Custom checkbox](#custom-checkbox)
+7. [Events](#events)
+8. [Keyboard navigation](#keyboard-navigation)
+9. [Incremental search](#incremental-search)
+10. [Filter predicate](#filter-predicate)
+11. [Sorting](#sorting)
+12. [Asynchronous data](#asynchronous-data)
+13. [CSS variables](#css-variables)
+14. [CSS parts](#css-parts)
+
+---
+
+## Quick start
+
+### Declarative HTML items
+
+```html
+<ixfx-detail-list id="my-list" selection-mode="single">
+  <li>Alpha</li>
+  <li>Bravo</li>
+  <li>Charlie</li>
+</ixfx-detail-list>
+
+<script type="module">
+  import '@ixfx/components';
+
+  const list = document.querySelector('#my-list');
+  list.addEventListener('list-select', ({ detail }) => {
+    const [item] = detail.selected;
+    console.log('selected:', item?.textContent);
+  });
+</script>
+```
+
+Items flow down columns (vertically) then wrap to the next column:
+
+```
+Alpha    Golf     November  Uniform
+Bravo    Hotel    Oscar    Victor
+Charlie  India    Papa     Whiskey
+Delta    Juliett  Quebec   X-ray
+Echo     Kilo     Romeo    Yankee
+Foxtrot  Lima     Sierra   Zulu
+```
+
+### Programmatic items
+
+```typescript
+import type { DetailListElement } from '@ixfx/components';
+
+const list = document.querySelector<DetailListElement>('ixfx-detail-list')!;
+
+list.addItem('Document A');
+list.addItem('Image 01.png');
+
+// Or pass an element directly
+const li = document.createElement('li');
+li.textContent = 'Custom item';
+list.addItem(li);
+```
+
+---
+
+## Item types
+
+### Plain `<li>` elements
+
+The simplest item type. Items are positioned by CSS flexbox into columns.
+
+```html
+<ixfx-detail-list>
+  <li>Item one</li>
+  <li>Item two</li>
+</ixfx-detail-list>
+```
+
+**Attributes supported on `<li>`:**
+
+| Attribute | Description |
+|---|---|
+| `data-search-label` | Override searchable text (defaults to `textContent`) |
+| `data-key` | Stable identity for selection persistence across sort/rebuild |
+| `data-value` | Alternative to `data-key` |
+| `data-icon` | Icon name to display (injects `<ixfx-icon>`) |
+| `not-checked` | In `checked` mode, renders without a checkbox and cannot be checked |
+| `hidden` | Hides the item from view and navigation |
+
+### Object items
+
+Pass an array of objects and configure how to display them:
+
+```typescript
+const files = [
+  { name: 'Report Q1.pdf', size: 220, kind: 'doc' },
+  { name: 'Photo 01.png', size: 1400, kind: 'img' },
+  { name: 'Notes.txt', size: 3, kind: 'doc' },
+];
+
+list.items = files;
+list.displayProperty = 'name';
+list.keyProperty = 'name'; // Preserves selection across rebuilds
+```
+
+**Object-related properties:**
+
+| Property | Type | Description |
+|---|---|---|
+| `items` | `readonly unknown[]` | Array of objects to render |
+| `displayProperty` | `string` | Property name to use as label |
+| `keyProperty` | `string` | Property name for stable identity |
+| `iconProperty` | `string` | Property name for icon name |
+| `formatter` | `(item: unknown, index: number) => string \| Node` | Custom renderer |
+
+```typescript
+list.formatter = (item, index) => {
+  const file = item as { name: string; size: number };
+  return `${file.name} (${file.size} KB)`;
+};
+```
+
+Retrieve the original data for an element:
+
+```typescript
+const data = list.getItemData(liElement);
+```
+
+---
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|---|---|---|---|---|
+| `selectionMode` | `selection-mode` | `'single' \| 'multiple' \| 'none'` | `'single'` | How selection works |
+| `interactionMode` | `interaction-mode` | `'implicit' \| 'standard' \| 'manual' \| 'checked' \| 'sticky' \| 'vscode'` | `'standard'` | Click/keyboard behavior |
+| `sort` | `sort` | `'none' \| 'ascending' \| 'descending'` | `'none'` | Sort direction |
+| `sortBy` | `sort-by` | `string` | — | Object property to sort by |
+| `sortComparator` | — | `(a, b) => number` | — | Custom sort function |
+| `filterPredicate` | — | `(el: Element) => boolean` | — | Filter visible items |
+| `itemWrap` | `item-wrap` | `'stop' \| 'wrap'` | `'stop'` | Keyboard wrap behavior |
+| `provider` | — | `IDataProvider` | — | Async data source |
+| `checkboxRenderer` | — | `function \| object` | — | Custom checkbox |
+
+---
+
+## Selection
+
+### Getters
+
+```typescript
+const selected = list.selectedItem;       // First selected element or undefined
+const allSelected = list.selectedItems;   // Array of all selected elements
+```
+
+### Methods
+
+```typescript
+list.select(item);          // Select an item
+list.deselect(item);       // Deselect an item
+list.selectMany([item1, item2]); // Select multiple
+list.clearSelection();     // Clear all selections
+list.selectAll();          // Select all visible items (if permitted)
+```
+
+---
+
+## Interaction modes
+
+| Mode | Description |
+|---|---|
+| `standard` | Click replaces selection. Ctrl+click toggles. Shift+click creates range. Cmd+A selects all. |
+| `implicit` | Click always replaces selection (no modifier support). |
+| `checked` | Checkbox column toggles selection; rows marked `not-checked` have no checkbox. |
+| `sticky` | Every click toggles. Cmd+A selects all. |
+| `vscode` | Like `standard`, but Shift+Arrow extends selection range. |
+| `manual` | No auto-selection; drive state via `select()` / `deselect()` programmatically. |
+
+---
+
+## Custom checkbox
+
+In `checked` mode, provide a custom checkbox renderer:
+
+```typescript
+list.checkboxRenderer = (checked) => checked
+  ? html`<span>✓</span>`
+  : html``;
+```
+
+Or use the shorthand object form:
+
+```typescript
+list.checkboxRenderer = { checked: '✓', unchecked: '' };
+```
+
+---
+
+## Events
+
+| Event | Detail | Description |
+|---|---|---|
+| `list-select` | `{ selected: Element[] }` | Selection changed |
+| `list-tickle` | `{ item: Element }` | Hover/focus cursor moved |
+| `list-activate` | `{ item: Element }` | Item activated (Enter/double-click) |
+| `list-item-click` | `{ item: Element }` | Item clicked |
+
+```typescript
+list.addEventListener('list-select', (e) => {
+  console.log('Selected:', [...e.detail.selected].map(el => el.textContent));
+});
+```
+
+---
+
+## Keyboard navigation
+
+The list must have focus for keyboard navigation. Click an item to focus, or set `tabindex="0"` on the element.
+
+| Key | Action |
+|---|---|
+| ↑ / ↓ | Move up/down within the current column |
+| ← / → | Jump to previous/next column (same row) |
+| Home | Jump to first item |
+| End | Jump to last item |
+| Enter | Activate item (fires `list-activate`) |
+| Space | Toggle selection (in modes that support it) |
+| Escape | Clear selection / close search |
+| Ctrl+F | Open incremental search |
+| Ctrl+A | Select all (in modes that support it) |
+
+### Wrapping
+
+Set `item-wrap="wrap"` to enable wraparound navigation:
+
+```html
+<ixfx-detail-list item-wrap="wrap">...</ixfx-detail-list>
+```
+
+With wrapping:
+- Down from last row → first row of next column (or first column if at end)
+- Up from first row → last row of previous column (or last column if at start)
+- Right from last column → first column
+- Left from first column → last column
+
+---
+
+## Incremental search
+
+Press Ctrl+F (or Cmd+F on Mac) to open the search overlay. Type to filter items in real-time using fuzzy matching.
+
+Search matches against `data-search-label` (or `textContent` as fallback). Use `data-search-label` to match against a different string than what's displayed:
+
+```html
+<li data-search-label="document a alpha">Document A</li>
+```
+
+### Highlight styling
+
+Matched characters are highlighted with the `detail-list-search` highlight key. Style matches with:
+
+```css
+::highlight(detail-list-search) {
+  background: yellow;
+  color: black;
+}
+```
+
+---
+
+## Filter predicate
+
+Use `filterPredicate` to programmatically hide items:
+
+```typescript
+// Show only .doc files
+list.filterPredicate = (el) => el.getAttribute('data-kind') === 'doc';
+
+// Clear filter
+list.filterPredicate = undefined;
+```
+
+Filtered items are hidden from view, keyboard navigation, and selection.
+
+---
+
+## Sorting
+
+### Simple sort
+
+```typescript
+list.sort = 'ascending';  // or 'descending'
+```
+
+### Sort by property
+
+```typescript
+list.sortBy = 'size';  // Sort by 'size' property
+list.sort = 'ascending';
+```
+
+### Custom comparator
+
+```typescript
+list.sortComparator = (a, b) => {
+  // Sort by kind first, then by label
+  const kindCompare = a.data.kind.localeCompare(b.data.kind);
+  if (kindCompare !== 0) return kindCompare;
+  return a.label.localeCompare(b.label);
+};
+```
+
+The comparator receives `{ element, data, label }` where:
+- `element` — the `<li>` DOM element
+- `data` — the original object from `items` array
+- `label` — the display string
+
+---
+
+## Asynchronous data
+
+Use a `provider` for async data loading:
+
+### Promise provider
+
+```typescript
+list.provider = async () => {
+  const response = await fetch('/api/items');
+  return response.json();
+};
+```
+
+### Streaming provider
+
+```typescript
+list.provider = async function*() {
+  for (let i = 0; i < 100; i++) {
+    yield [{ id: i, name: `Item ${i}` }];
+    await delay(100);
+  }
+}();
+```
+
+The provider function can return:
+- A promise that resolves to an array
+- An async iterable that yields arrays (streaming)
+
+Streaming providers extend columns to the right as batches arrive.
+
+---
+
+## CSS variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `--detail-list-bg` | `surface-3` | Background color |
+| `--detail-list-text` | `surface-3-text` | Text color |
+| `--detail-list-border` | `border` | Border color |
+| `--detail-list-radius` | `radius-s` | Border radius |
+| `--detail-list-column-width` | `220px` | Width of each column |
+| `--detail-list-column-gap` | `8px` | Gap between columns |
+| `--detail-list-item-height` | `28px` | Height of each item |
+| `--detail-list-item-padding` | `0 var(--space-m)` | Item padding |
+| `--detail-list-scrollbar-width` | `auto` | Scrollbar width |
+| `--detail-list-scrollbar-gutter` | `auto` | Scrollbar gutter |
+| `--detail-list-scrollbar-color` | `auto` | Scrollbar color |
+
+Plus all `--item-bg-*`, `--item-text-*` variables from the theme for selection/tickle states.
+
+---
+
+## CSS parts
+
+| Part | Description |
+|---|---|
+| `list` | The `<ul>` container |
+| `search-overlay` | The Ctrl+F search overlay |
+| `checkbox` | The checkbox element (in `checked` mode) |
+| `loading` | The loading indicator |
+
+```css
+ixfx-detail-list::part(search-overlay) {
+  background: rgba(0, 0, 0, 0.8);
+}
+```