@ixfx/components 0.3.2 → 0.4.1

package/docs-user/vertical-list.md

@@ -0,0 +1,351 @@
+# `ixfx-vertical-list`
+
+A scrollable vertical list of items with selection, keyboard navigation, and incremental search. Items can be plain `<li>` elements declared in HTML or rich custom elements added programmatically.
+
+---
+
+## Contents
+
+1. [Quick start](#quick-start)
+2. [Item types](#item-types)
+3. [Properties](#properties)
+4. [Selection](#selection)
+5. [Events](#events)
+6. [Keyboard navigation](#keyboard-navigation)
+7. [Incremental search](#incremental-search)
+8. [CSS variables](#css-variables)
+9. [CSS parts](#css-parts)
+
+---
+
+## Quick start
+
+### Declarative HTML items
+
+```html
+<ixfx-vertical-list id="my-list" selection-mode="single">
+  <li>Apple</li>
+  <li>Banana</li>
+  <li>Cherry</li>
+</ixfx-vertical-list>
+
+<script type="module">
+  import '@ixfx/components/vertical-list';
+
+  const list = document.querySelector('#my-list');
+  list.addEventListener('list-select', ({ detail }) => {
+    const [item] = detail.selected;
+    console.log('selected:', item?.textContent);
+  });
+</script>
+```
+
+### Programmatic items
+
+```typescript
+import type { VerticalListElement } from '@ixfx/components';
+
+const list = document.querySelector<VerticalListElement>('ixfx-vertical-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. Styled directly via `::slotted(li)` CSS from the component's shadow DOM.
+
+```html
+<ixfx-vertical-list>
+  <li>Item one</li>
+  <li>Item two</li>
+</ixfx-vertical-list>
+```
+
+Searchable text is the element's `textContent`. Override with `data-search-label` for custom search terms:
+
+```html
+<li data-search-label="document a alpha">Document A</li>
+```
+
+### Custom shadow-DOM components
+
+Any element with a `data-list-item` attribute is recognised as a list item. This enables rich card-style rows built with Lit or any other framework:
+
+```html
+<ixfx-vertical-list>
+  <my-track-card data-list-item track-title="Bohemian Rhapsody" artist="Queen"></my-track-card>
+</ixfx-vertical-list>
+```
+
+Because the component cannot reach inside a custom element's shadow root, you must expose searchable text via a `data-search-label` attribute on the host element. The recommended pattern is to set this in the custom element's `willUpdate` lifecycle:
+
+```typescript
+override willUpdate(changed: PropertyValues) {
+  super.willUpdate(changed);
+  if (changed.has('trackTitle') || changed.has('artist')) {
+    this.setAttribute('data-search-label', `${this.trackTitle} ${this.artist}`);
+  }
+}
+```
+
+To reflect selection state inside the custom element's shadow DOM, target the `:host([data-selected])` CSS selector:
+
+```css
+:host([data-selected]) .title {
+  color: var(--item-text-selected, #fff);
+}
+```
+
+---
+
+## Properties
+
+| Property / Attribute | Type | Default | Description |
+|---|---|---|---|
+| `selectionMode` / `selection-mode` | `'none' \| 'single' \| 'multiple'` | `'single'` | Which items can be selected simultaneously |
+| `interactionMode` / `interaction-mode` | `ListInteractionMode` | `'standard'` | How gestures map to selection changes (see table below) |
+| `filterPredicate` | `((el: Element) => boolean) \| undefined` | `undefined` | External filter; only items returning `true` are shown |
+
+Switching `interactionMode` always clears the current selection.
+
+### `interactionMode`
+
+| Value | Behaviour |
+|---|---|
+| `'implicit'` | Click always replaces selection. No modifier support. |
+| `'standard'` | Plain click replaces selection; Ctrl/Cmd+click toggles; Shift+click range-selects (multiple mode only); Cmd+A selects all |
+| `'vscode'` | Like `standard` for clicks; Shift+Arrow extends the range from the keyboard anchor |
+| `'checked'` | Checkboxes on every `<li>` row; checkbox click (or Space) toggles; body clicks do nothing. Custom elements show a left-border indicator instead of a checkbox |
+| `'manual'` | No automatic selection; drive state entirely via `select()` / `deselect()` / `clearSelection()` |
+
+---
+
+## Selection
+
+### Programmatic API
+
+```typescript
+// Replace selection with a single item
+list.select(element);
+
+// Replace selection with multiple items — requires selectionMode="multiple", throws otherwise
+list.selectMany([elementA, elementB, elementC]);
+
+// Remove one item from the selection
+list.deselect(element);
+
+// Clear entire selection
+list.clearSelection();
+
+// Select all visible items (only works when multiple selection is effective)
+list.selectAll();
+```
+
+### Adding and removing items
+
+```typescript
+// Append a string (wrapped in <li>) or an Element
+list.addItem('New item');
+list.addItem(myElement);
+
+// Remove a specific element
+list.removeItem(element);
+
+// Remove all items and clear selection
+list.clearItems();
+```
+
+### Reading the selection
+
+```typescript
+// Most recently selected item (primary selection)
+const item = list.selectedItem;
+if (item) console.log(item.textContent?.trim());
+
+// Full selection set
+for (const el of list.selectedItems) {
+  console.log(el.textContent?.trim());
+}
+
+// Via event
+list.addEventListener('list-select', ({ detail }) => {
+  const { selected, previous } = detail;
+  for (const el of selected) {
+    console.log(el.textContent?.trim());
+  }
+});
+```
+
+### Attribute hooks on items
+
+The component reflects state onto list items as data attributes. Use these in CSS or to read state from JavaScript:
+
+| Attribute | Set when |
+|---|---|
+| `data-tickled` | The keyboard/pointer cursor is on this item |
+| `data-selected` | The item is in the current selection |
+| `data-checked` | Set in `checked` mode; mirrors `data-selected` |
+
+---
+
+## Events
+
+All events **bubble** and are **composed** (they cross shadow-DOM boundaries).
+
+| Event | Detail type | When fired |
+|---|---|---|
+| `list-select` | `ListSelectDetail` | Selection changes by any means |
+| `list-tickle` | `ListTickleDetail` | An item enters cursor focus (hover or keyboard navigation) |
+| `list-activate` | `ListActivateDetail` | User explicitly activates an item: Enter key or double-click |
+| `list-item-click` | `ListItemClickDetail` | Raw click or Enter on any item |
+
+### Detail types
+
+```typescript
+type ListSelectDetail = {
+  readonly selected: ReadonlySet<Element>;  // Current full selection
+  readonly previous: ReadonlySet<Element>;  // Selection before this change
+};
+
+type ListTickleDetail   = { readonly item: Element };
+type ListActivateDetail = { readonly item: Element };
+type ListItemClickDetail = { readonly item: Element };
+```
+
+### Usage example
+
+```typescript
+list.addEventListener('list-select', ({ detail }) => {
+  const labels = [...detail.selected]
+    .map(el => el.getAttribute('data-search-label') ?? el.textContent?.trim())
+    .join(', ');
+  console.log('selection:', labels);
+});
+
+list.addEventListener('list-tickle', ({ detail }) => {
+  previewPane.show(detail.item);
+});
+
+list.addEventListener('list-activate', ({ detail }) => {
+  router.navigate(detail.item.dataset.key);
+});
+
+list.addEventListener('list-item-click', ({ detail }) => {
+  analytics.track('list-click', detail.item.dataset.key);
+});
+```
+
+---
+
+## Keyboard navigation
+
+The element must be focused (click it or tab to it) before keyboard navigation works. A visible focus ring appears on focus.
+
+| Key | Action |
+|---|---|
+| `Arrow Down` | Move cursor to next visible item |
+| `Arrow Up` | Move cursor to previous visible item |
+| `Enter` | Activate the cursor item — fires `list-item-click` then `list-activate`; selects the item (except in `manual` mode) |
+| `Space` | Toggle selection on the cursor item |
+| `Shift+Arrow Down/Up` | Extend range from anchor (`vscode` mode only) |
+| `Ctrl/Cmd+A` | Select all visible items (when effective multiple selection is on) |
+| `Ctrl/Cmd+F` | Open the incremental search overlay |
+| `Escape` | Clear the current selection (or close the search overlay if open) |
+
+### While the search overlay is open
+
+| Key | Action |
+|---|---|
+| `Arrow Down / Up` | Move cursor through the filtered list |
+| `Enter` | Activate the cursor item (or first visible item) and close search |
+| `Escape` | Close search overlay |
+
+---
+
+## Incremental search
+
+Press **Ctrl+F** (or **Cmd+F**) to open the search overlay. Typing filters items in real time using fuzzy matching. Matched text in plain `<li>` items is highlighted via the [CSS Highlight API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API).
+
+### Adding the page-level highlight rule
+
+The CSS Highlight API requires a `::highlight()` rule in the page stylesheet to make matches visible. Add this to your page:
+
+```css
+::highlight(vertical-list-search) {
+  background: var(--accent);
+  color: var(--accent-text, #fff);
+}
+```
+
+Without this rule the filtering still works (non-matching items are hidden) but matched text inside `<li>` items will not be highlighted.
+
+### Searchable text
+
+| Item type | Default search text | Override |
+|---|---|---|
+| `<li>` | `textContent` | `data-search-label` attribute |
+| `[data-list-item]` custom element | `data-search-label` attribute | — |
+
+Custom elements must always set `data-search-label` since the component cannot read their shadow DOM content.
+
+### External `filterPredicate`
+
+Supply a custom filter function to hide items independently of the search overlay:
+
+```typescript
+// Show only items tagged as 'document'
+list.filterPredicate = (el) => el.dataset.type === 'document';
+
+// Remove the filter
+list.filterPredicate = undefined;
+```
+
+---
+
+## CSS variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `--list-bg` | `var(--surface-3)` | List background |
+| `--list-text` | `var(--surface-3-text)` | Default text colour |
+| `--list-border` | `var(--border)` | Border colour |
+| `--list-radius` | `var(--radius-s)` | Border radius |
+| `--list-item-height` | `28px` | Minimum row height for `<li>` items |
+| `--list-item-padding` | `4px var(--space-m, 8px)` | Padding for `<li>` items |
+| `--item-bg-tickled` | `rgba(0,0,0,0.06)` | Row background when cursor is on it |
+| `--item-bg-selected` | `rgba(25,118,210,1)` | Selected row background |
+| `--item-text-selected` | `#fff` | Selected row text colour |
+| `--item-bg-selected-tickled` | `rgba(21,101,192,1)` | Selected + cursor row background |
+| `--accent` | — | Accent colour (focus ring, search highlight, checkbox) |
+| `--transition` | `0.1s ease-out` | Transition timing for hover/selection changes |
+
+---
+
+## CSS parts
+
+| Part | Element |
+|---|---|
+| `list` | The `<ul>` scroll container |
+| `search-overlay` | The floating search input overlay |
+
+Use `::part()` to style these from outside the component's shadow DOM:
+
+```css
+ixfx-vertical-list::part(list) {
+  padding: 4px 0;
+}
+
+ixfx-vertical-list::part(search-overlay) {
+  border-radius: 8px;
+}
+```

package/docs-user/xy-pad.md

@@ -0,0 +1,94 @@
+# `ixfx-xy-pad`
+
+A 2D touch-friendly XY pad for controlling two parameters simultaneously. Each axis supports independent linear/logarithmic scaling.
+
+```html
+<ixfx-xy-pad></ixfx-xy-pad>
+<ixfx-xy-pad x-min="0" x-max="1" y-min="0" y-max="1" x-label="Volume" y-label="Pan"></ixfx-xy-pad>
+```
+
+```js
+const pad = document.querySelector('ixfx-xy-pad');
+pad.xMin = 0;
+pad.xMax = 100;
+pad.yMin = 0;
+pad.yMax = 100;
+pad.xScale = 'linear';
+pad.yScale = 'log'; // logarithmic scaling for y axis
+
+pad.addEventListener('input', e => {
+  console.log(`x: ${e.detail.x.toFixed(2)}, y: ${e.detail.y.toFixed(2)}`);
+});
+
+pad.addEventListener('change', e => {
+  console.log('drag ended:', e.detail);
+});
+```
+
+### Properties / attributes
+
+| Attribute / Property  | Type                   | Default    | Description                                  |
+|-----------------------|------------------------|------------|----------------------------------------------|
+| `xMin`                | `number`               | `1`        | Minimum X value                              |
+| `xMax`                | `number`               | `100`      | Maximum X value                              |
+| `x`                   | `number`               | `50`       | Current X value                              |
+| `yMin`                | `number`               | `1`        | Minimum Y value                              |
+| `yMax`                | `number`               | `100`      | Maximum Y value                              |
+| `y`                   | `number`               | `50`       | Current Y value                              |
+| `xScale`              | `'linear' \| 'log'`    | `'linear'` | X axis scaling                               |
+| `yScale`              | `'linear' \| 'log'`    | `'linear'` | Y axis scaling                               |
+| `xSnapStep`           | `number \| undefined`  | `undefined`| X axis snap granularity (`x-snap-step`)     |
+| `ySnapStep`           | `number \| undefined`  | `undefined`| Y axis snap granularity (`y-snap-step`)     |
+| `xLabel`              | `string`               | `'X'`      | X axis label text                            |
+| `yLabel`              | `string`               | `'Y'`      | Y axis label text                            |
+| `showCrosshairs`      | `boolean`              | `false`    | Show crosshair lines                         |
+| `showGrid`            | `boolean`              | `false`    | Show background grid                         |
+| `hideCursor`           | `boolean`              | `false`    | Hide cursor during drag                     |
+| `disabled`            | `boolean`              | `false`    | Disable all interaction                     |
+| `stops`               | `number \| undefined`  | `undefined`| Quantized stops for both axes               |
+| `stopsX`              | `number \| undefined`  | `undefined`| Quantized stops for X axis only             |
+| `stopsY`              | `number \| undefined`  | `undefined`| Quantized stops for Y axis only             |
+
+### Events
+
+| Event    | Detail                    | Description                            |
+|----------|---------------------------|----------------------------------------|
+| `input`  | `{ x: number, y: number }` | Continuously during drag               |
+| `change` | `{ x: number, y: number }` | When drag ends (pointer release)       |
+
+### Methods
+
+| Method           | Returns                      | Description                                      |
+|------------------|------------------------------|--------------------------------------------------|
+| `getRelativeX()` | `number` (0–1)              | X position as fraction                           |
+| `getRelativeY()` | `number` (0–1)              | Y position as fraction                           |
+| `getPolar()`     | `{ radius: number, angle: number }` | Polar coordinates (radius 0–1, angle 0–2π radians, 0 = right, clockwise) |
+
+### Keyboard navigation
+
+Arrow keys move the position. Hold Shift for finer control (step divisor).
+
+### CSS custom properties
+
+| Property              | Default              | Description                           |
+|-----------------------|----------------------|---------------------------------------|
+| `--marker-size`       | `10cqb`             | Position marker diameter              |
+| `--crosshair-color`   | `var(--surface-6)`  | Crosshair line color                  |
+| `--crosshair-width`   | `2px`               | Crosshair line thickness              |
+| `--crosshair-x-color` | `var(--crosshair-color)` | Vertical crosshair color        |
+| `--crosshair-x-width` | `var(--crosshair-width)` | Vertical crosshair thickness   |
+| `--crosshair-y-color` | `var(--crosshair-color)` | Horizontal crosshair color      |
+| `--crosshair-y-width` | `var(--crosshair-width)` | Horizontal crosshair thickness |
+| `--grid-color`        | `var(--surface-6)`  | Grid line color                       |
+| `--grid-width`        | `1px`               | Grid line thickness                   |
+| `--xy-pad-bg`         | `var(--surface-3)`  | Pad background colour                 |
+
+### CSS properties set on host (for external use)
+
+The component sets these custom properties on its host element during drag:
+
+| Property   | Description                                  |
+|------------|----------------------------------------------|
+| `--x-pct`  | X position as 0–100 percentage              |
+| `--y-pct`  | Y position as 0–100 percentage              |
+| `--radius-pct` | Distance from centre as 0–100 percentage |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "",
   "author": "",
   "license": "ISC",
@@ -19,7 +19,7 @@
       "types": "./dist/incr-search.d.ts",
       "import": "./dist/incr-search.js"
     },
-    "./*": {
+    "./*.js": {
       "types": "./dist/*.d.ts",
       "import": "./dist/*.js"
     }
@@ -27,7 +27,8 @@
   "main": "dist/index.js",
   "files": [
     "bundle",
-    "dist"
+    "dist",
+    "docs-user"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -48,23 +49,23 @@
   "devDependencies": {
     "@antfu/eslint-config": "^9.0.0",
     "@clinth/vcanvas": "0.0.3",
-    "@ixfx/arrays": "0.56.12",
-    "@ixfx/collections": "0.56.12",
-    "@ixfx/core": "0.56.12",
-    "@ixfx/dom": "0.56.12",
-    "@ixfx/flow": "0.56.12",
-    "@ixfx/geometry": "0.56.12",
-    "@ixfx/modulation": "0.56.12",
-    "@ixfx/numbers": "0.56.12",
-    "@ixfx/visual": "0.56.12",
-    "@tsdown/css": "0.22.0",
-    "eslint": "10.4.0",
+    "@ixfx/arrays": "0.56.13",
+    "@ixfx/collections": "0.56.13",
+    "@ixfx/core": "0.56.13",
+    "@ixfx/dom": "0.56.13",
+    "@ixfx/flow": "0.56.13",
+    "@ixfx/geometry": "0.56.13",
+    "@ixfx/modulation": "0.56.13",
+    "@ixfx/numbers": "0.56.13",
+    "@ixfx/visual": "0.56.13",
+    "@tsdown/css": "0.22.1",
+    "eslint": "10.4.1",
     "eslint-plugin-format": "2.0.1",
     "globals": "17.6.0",
-    "knip": "6.14.1",
-    "tsdown": "0.22.0",
+    "knip": "6.14.2",
+    "tsdown": "0.22.1",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.59.3",
-    "vite": "8.0.13"
+    "typescript-eslint": "8.60.0",
+    "vite": "8.0.14"
   }
 }