@ixfx/components 0.3.1 → 0.4.0

package/docs-user/incr-search.md

@@ -0,0 +1,94 @@
+# Incremental Search
+
+Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.
+You can use the low-level `createIncrSearch` for data, `createElementIncrSearch` for
+DOM elements, or `IncrSearchTreeController` for tree and Miller list components.
+
+## Plain UL list
+
+Matches the approach in `demo/incr-search.ts` using `createElementIncrSearch`.
+
+```typescript
+import { createElementIncrSearch } from '../src/incr-search/index.js';
+
+const ITEMS = [
+  'Afghanistan', 'Albania', 'Algeria', 'Andorra', 'Angola',
+  'Argentina', 'Armenia', 'Australia', 'Austria', 'Azerbaijan',
+];
+
+const listEl = document.querySelector<HTMLUListElement>('#list')!;
+const searchEl = document.querySelector<HTMLInputElement>('#search')!;
+
+for (const name of ITEMS) {
+  const li = document.createElement('li');
+  li.textContent = name;
+  listEl.append(li);
+}
+
+const search = createElementIncrSearch({
+  container: listEl,
+  itemSelector: 'li',
+  highlightKey: 'demo-incr-highlight',
+  onChange: state => {
+    const count = state.query.trim() ? state.results.length : ITEMS.length;
+    console.log('query', `"${state.query}" → ${count} items`);
+  },
+});
+
+searchEl.addEventListener('input', () => {
+  void search.setQuery(searchEl.value);
+});
+
+searchEl.addEventListener('keydown', (e: KeyboardEvent) => {
+  if (e.key === 'Escape') {
+    searchEl.value = '';
+    void search.clearQuery();
+  }
+});
+```
+
+## Tree list component
+
+Use `IncrSearchTreeController` with `ixfx-tree-list` (or any `TreeSearchHost`).
+
+```typescript
+import { IncrSearchTreeController } from '../src/incr-search/index.js';
+import type { TreeListElement } from '../src/tree/tree-list.ts';
+
+const treeEl = document.querySelector<TreeListElement>('ixfx-tree-list')!;
+const searchEl = document.querySelector<HTMLInputElement>('[data-search]')!;
+
+const searchCtrl = new IncrSearchTreeController(treeEl, {
+  selector: ({ node }) => node.item.label,
+  input: searchEl,
+});
+
+searchCtrl.connect();
+```
+
+## Miller tree component
+
+`IncrSearchMillerController` is a compatibility export. Prefer `IncrSearchTreeController`
+and pass the Miller label selector.
+
+```typescript
+import { IncrSearchTreeController } from '../src/incr-search/index.js';
+import type { MillerListElement } from '../src/miller/miller-list.ts';
+
+const millerEl = document.querySelector<MillerListElement>('ixfx-miller-list')!;
+const searchEl = document.querySelector<HTMLInputElement>('[data-search]')!;
+
+const searchCtrl = new IncrSearchTreeController(millerEl, {
+  selector: ({ node }) => node.item.label,
+  labelSelector: '.label',
+  input: searchEl,
+});
+
+searchCtrl.connect();
+```
+
+## Notes
+
+- `createElementIncrSearch` observes child mutations and refreshes automatically.
+- `IncrSearchTreeController` sets `filterPredicate` and highlights matching labels.
+- Call `disconnect()` when tearing down controllers to clear highlights and handlers.

package/docs-user/labelled-radial-input.md

@@ -0,0 +1,204 @@
+# `<ixfx-labelled-radial-input>`
+
+A composite radial input that pairs an editable label (`ixfx-editable-number`) with a rotary dial (`ixfx-radial-input`). The two controls are always in sync — turning the dial updates the number, and editing the number moves the dial.
+
+## Basic usage
+
+```html
+<ixfx-labelled-radial-input label="Volume" value="50" min="0" max="100">
+</ixfx-labelled-radial-input>
+```
+
+## Layout
+
+Layout is driven by a container query on the component's aspect ratio (width / height).
+
+| Aspect Ratio (width/height) | Layout                         |
+|----------------------------|--------------------------------|
+| >= 1.5 (wide)              | **Horizontal** — label to the left of dial |
+| < 1.5 (tall/square)       | **Vertical** — label above dial |
+
+### Force a layout with `--flow`
+
+Override the container query entirely:
+
+```html
+<ixfx-labelled-radial-input style="--flow: row" ...>    <!-- always horizontal (label left) -->
+<ixfx-labelled-radial-input style="--flow: column" ...> <!-- always vertical (label above) -->
+```
+
+## Mini mode
+
+When the component is very small the label is hidden and only the dial is shown, with the tooltip forced on.
+
+Mini mode activates when **both** of the following are true:
+- `width < mini-width-threshold` (default 120px)
+- `height < mini-height-threshold` (default 45px)
+
+Override with a CSS variable:
+
+```html
+<ixfx-labelled-radial-input style="--mini: 1" ...> <!-- always mini  -->
+<ixfx-labelled-radial-input style="--mini: 0" ...> <!-- never mini   -->
+```
+
+## Formatter
+
+Apply a function to format the displayed value. Set it as a JS property — it cannot be set as an HTML attribute.
+
+```js
+const el = document.querySelector('ixfx-labelled-radial-input');
+el.formatter = (v) => `${Math.round(Number(v))}%`;
+```
+
+The formatter receives the raw string value and returns the string to display.
+
+## Properties / attributes
+
+| Attribute                | Type                                           | Default      | Description                                         |
+|--------------------------|------------------------------------------------|--------------|-----------------------------------------------------|
+| `label`                  | `string`                                       | `""`         | Label text shown in the editable-number             |
+| `value`                  | `number`                                      | `0`          | Current value                                       |
+| `min`                    | `number`                                      | `0`          | Minimum value                                       |
+| `max`                    | `number`                                      | `100`        | Maximum value                                       |
+| `step`                   | `number`                                      | `1`          | Step increment                                      |
+| `drag-sensitivity`       | `number`                                      | `1`          | Steps per pixel when dragging the number label      |
+| `precision`              | `number`                                      | `0`          | Decimal places shown                                |
+| `radius`                 | `number` (10-50)                              | `45`         | Dial size                                           |
+| `flatten`                | `number` (0-1)                                | `0.3`        | How much circle to hide                             |
+| `marker-style`           | `"needle" \| "dot" \| "none"`                 | `"needle"`   | Marker type                                         |
+| `wedge`                  | `boolean`                                     | `false`      | Show filled wedge sector                            |
+| `value-mode`             | `"range" \| "bipolar" \| "unipolar"`           | `"range"`    | Value display mode                                 |
+| `tooltip`                | `boolean`                                     | `false`      | Show dial tooltip                                   |
+| `aspect-ratio-threshold` | `number`                                      | `1.5`        | Width/height ratio to trigger horizontal layout     |
+| `mini-width-threshold`   | `number`                                      | `120`        | Width (px) below which mini mode can activate       |
+| `mini-height-threshold`  | `number`                                      | `45`         | Height (px) below which mini mode can activate      |
+| `display-text-logic`     | `"hidden" \| "show" \| "override" \| "transient"` | `"transient"` | Controls when label text vs value is shown    |
+| `formatter`              | `(value: string) => string`                   | —            | JS property only — formats value for display        |
+
+### `display-text-logic` values
+
+| Value       | Behaviour                                              |
+|-------------|--------------------------------------------------------|
+| `transient` | Shows the label when idle, value on hover/interaction  |
+| `show`      | Always shows the value                                 |
+| `hidden`    | Always shows the label text, never the value           |
+| `override`  | Label text replaces value at all times                 |
+
+## Events
+
+| Event    | Detail                    | Description                                              |
+|----------|---------------------------|----------------------------------------------------------|
+| `change` | `{ value: string }`       | Fired when the value is committed (dial release or number edit) |
+| `input`  | `{ value: number }`       | Fired on every dial interaction                          |
+
+Both events bubble and are composed (cross shadow boundary).
+
+## CSS variables
+
+### Layout
+
+| Variable    | Default      | Description                                               |
+|-------------|--------------|-----------------------------------------------------------|
+| `--height`  | `auto`       | Component height                                          |
+| `--width`   | `auto`       | Component width                                           |
+| `--min-height` | `60px`    | Minimum height                                            |
+| `--min-width`  | `60px`    | Minimum width                                             |
+| `--flow`    | *(container query)* | `row` or `column` — overrides the automatic layout |
+| `--mini`    | *(auto)*     | `1` to force mini mode, `0` to disable it                 |
+
+### Label (passed to `ixfx-editable-number`)
+
+| Variable              | Default                    | Description              |
+|-----------------------|----------------------------|--------------------------|
+| `--label-font-size`   | `var(--text-m)`            | Font size                |
+| `--label-font-family` | `var(--font-family)`       | Font family              |
+| `--label-color`       | `var(--surface-text)`      | Text colour              |
+| `--label-muted-color` | `var(--surface-muted-text)`| Muted text colour        |
+| `--label-padding`     | `var(--space-xs) var(--space-s)` | Padding             |
+| `--label-radius`      | `var(--radius-s)`          | Border radius            |
+| `--label-align`       | `center`                   | Text alignment           |
+
+### Dial (passed to `ixfx-radial-input`)
+
+| Variable                    | Default      | Description                        |
+|-----------------------------|--------------|------------------------------------|
+| `--dial-border-width`        | —            | Dial border width                  |
+| `--dial-border-color`        | —            | Dial border colour                 |
+| `--dial-fill`                | —            | Dial fill colour                   |
+| `--radius`                  | `45`         | Dial radius                        |
+| `--marker-color`             | —            | Marker colour                      |
+| `--marker-thickness`         | —            | Marker thickness                   |
+| `--marker-length`            | —            | Marker length                      |
+| `--marker-offset`            | —            | Marker offset from dial edge       |
+| `--marker-border-width`       | —            | Marker border width                |
+| `--marker-border-color`       | —            | Marker border colour               |
+| `--midpoint-color`            | —            | Midpoint colour (bipolar mode)     |
+| `--midpoint-thickness`        | —            | Midpoint thickness                 |
+| `--midpoint-length`           | —            | Midpoint length                    |
+| `--midpoint-offset`           | —            | Midpoint offset                    |
+| `--lane-width`                | —            | Lane width                         |
+| `--lane-color`                | —            | Lane colour                        |
+| `--lane-border-width`          | —            | Lane border width                  |
+| `--lane-offset`               | —            | Lane offset                        |
+| `--lane-dasharray`            | —            | Lane dash array                    |
+| `--wedge-fill`                | —            | Wedge fill colour                  |
+| `--wedge-fill-opacity`        | —            | Wedge fill opacity                 |
+| `--wedge-border-width`        | —            | Wedge border width                 |
+| `--wedge-border-color`        | —            | Wedge border colour                |
+
+## Examples
+
+### Horizontal layout (wide container)
+
+```html
+<ixfx-labelled-radial-input
+  id="my-dial"
+  label="Mix"
+  value="75"
+  style="width: 200px; height: 80px;"
+></ixfx-labelled-radial-input>
+```
+
+### Custom dial colours
+
+```html
+<ixfx-labelled-radial-input
+  label="Intensity"
+  value="70"
+  style="
+    --dial-fill: hsl(200 80% 40%);
+    --marker-color: white;
+  "
+></ixfx-labelled-radial-input>
+```
+
+### Wedge mode
+
+```html
+<ixfx-labelled-radial-input
+  label="Mix"
+  value="50"
+  wedge
+  style="--wedge-fill: hsl(260 80% 50%);"
+></ixfx-labelled-radial-input>
+```
+
+### Force mini mode
+
+```html
+<ixfx-labelled-radial-input label="Vol" value="50" style="--mini: 1">
+</ixfx-labelled-radial-input>
+```
+
+### Listen for changes
+
+```js
+const el = document.querySelector('ixfx-labelled-radial-input');
+
+// Committed value (dial release or number edit)
+el.addEventListener('change', (e) => console.log(e.detail.value));
+
+// Every dial interaction
+el.addEventListener('input', (e) => console.log(e.detail.value));
+```

package/docs-user/labelled-range-input.md

@@ -0,0 +1,194 @@
+# `<ixfx-labelled-range-input>`
+
+A composite range input that pairs an editable label (`ixfx-editable-number`) with a slider (`ixfx-range-input`). The two controls are always in sync — dragging the slider updates the number, and editing the number moves the slider.
+
+## Basic usage
+
+```html
+<ixfx-labelled-range-input label="Volume" value="0.5" min="0" max="1" step="0.01">
+</ixfx-labelled-range-input>
+```
+
+## Layout
+
+Layout is driven by a container query on the component's own height.
+
+| Height          | Layout                          |
+|-----------------|---------------------------------|
+| >= 80px (default) | **Vertical** — label above slider |
+| < 80px          | **Horizontal** — label beside slider |
+
+The component defaults to `height: 100px`, so unconstrained usage shows the vertical layout. Constrain the height in your CSS to switch to horizontal.
+
+### Force a layout with `--flow`
+
+Override the container query entirely:
+
+```html
+<ixfx-labelled-range-input style="--flow: row" ...>   <!-- always horizontal -->
+<ixfx-labelled-range-input style="--flow: column" ...> <!-- always vertical   -->
+```
+
+### Control label width (horizontal layout)
+
+```html
+<ixfx-labelled-range-input style="--label-width: 8em" ...>
+```
+
+## Mini mode
+
+When the component is very small the label is hidden and only the slider is shown, with the tooltip forced on.
+
+Mini mode activates when **both** of the following are true:
+- `width < mini-width-threshold` (default 120px)
+- `height < mini-height-threshold` (default 40px)
+
+Override with a CSS variable:
+
+```html
+<ixfx-labelled-range-input style="--mini: 1" ...> <!-- always mini  -->
+<ixfx-labelled-range-input style="--mini: 0" ...> <!-- never mini   -->
+```
+
+## Formatter
+
+Apply a function to format the displayed value and tooltip. Set it as a JS property — it cannot be set as an HTML attribute.
+
+```js
+const el = document.querySelector('ixfx-labelled-range-input');
+el.formatter = (v) => `${Math.round(Number(v))}%`;
+```
+
+The formatter receives the raw string value and returns the string to display. When set, it applies to both the editable-number label and the slider tooltip.
+
+## Properties / attributes
+
+| Attribute              | Type                                          | Default      | Description                                         |
+|------------------------|-----------------------------------------------|--------------|-----------------------------------------------------|
+| `label`                | `string`                                      | `""`         | Label text shown in the editable-number             |
+| `value`                | `number`                                      | `0`          | Current value                                       |
+| `min`                  | `number`                                      | `0`          | Minimum value                                       |
+| `max`                  | `number`                                      | `1`          | Maximum value                                       |
+| `step`                 | `number`                                      | `0.01`       | Step increment                                      |
+| `drag-sensitivity`     | `number`                                      | `1`          | Steps per pixel when dragging the number label      |
+| `precision`            | `number`                                      | `0`          | Decimal places shown                                |
+| `orientation`          | `"horizontal" \| "vertical"`                  | `"horizontal"` | Slider track orientation                          |
+| `tooltip`              | `boolean`                                     | `false`      | Show slider tooltip                                 |
+| `tooltip-orientation`  | `"top" \| "right"`                            | `"top"`      | Tooltip position relative to the slider thumb       |
+| `switch-height`        | `number`                                      | `80`         | Height (px) at which layout switches vertical↔horizontal |
+| `mini-width-threshold` | `number`                                      | `120`        | Width (px) below which mini mode can activate       |
+| `mini-height-threshold`| `number`                                      | `40`         | Height (px) below which mini mode can activate      |
+| `display-text-logic`   | `"hidden" \| "show" \| "override" \| "transient"` | `"transient"` | Controls when label text vs value is shown    |
+| `formatter`            | `(value: string) => string`                   | —            | JS property only — formats value for display and tooltip |
+
+### `display-text-logic` values
+
+| Value       | Behaviour                                              |
+|-------------|--------------------------------------------------------|
+| `transient` | Shows the label when idle, value on hover/interaction  |
+| `show`      | Always shows the value                                 |
+| `hidden`    | Always shows the label text, never the value           |
+| `override`  | Label text replaces value at all times                 |
+
+## Events
+
+| Event    | Detail                    | Description                                              |
+|----------|---------------------------|----------------------------------------------------------|
+| `change` | `{ value: string }`       | Fired when the value is committed (slider release or number edit) |
+| `input`  | `{ value: number }`       | Fired on every slider move                               |
+
+Both events bubble and are composed (cross shadow boundary).
+
+## CSS variables
+
+### Layout
+
+| Variable                 | Default      | Description                                               |
+|--------------------------|--------------|-----------------------------------------------------------|
+| `--height`               | `100px`      | Component height. Set to `100%` to fill a constrained parent |
+| `--width`                | `auto`       | Component width                                           |
+| `--min-height`           | `20px`       | Minimum height                                            |
+| `--min-width`            | `50px`       | Minimum width                                             |
+| `--flow`                 | *(container query)* | `row` or `column` — overrides the automatic layout |
+| `--label-width`          | `5ch`        | Width of the editable-number in horizontal layout         |
+| `--mini`                 | *(auto)*     | `1` to force mini mode, `0` to disable it                 |
+
+### Label (passed to `ixfx-editable-number`)
+
+| Variable              | Default                    | Description              |
+|-----------------------|----------------------------|--------------------------|
+| `--label-font-size`   | `var(--text-m)`            | Font size                |
+| `--label-font-family` | `var(--font-family)`       | Font family              |
+| `--label-color`       | `var(--surface-text)`      | Text colour              |
+| `--label-muted-color` | `var(--surface-muted-text)`| Muted text colour        |
+| `--label-padding`     | `var(--space-xs) var(--space-s)` | Padding             |
+| `--label-radius`      | `var(--radius-s)`          | Border radius            |
+| `--label-align`       | `center`                   | Text alignment           |
+
+### Slider track (passed to `ixfx-range-input`)
+
+| Variable                          | Default                  | Description                              |
+|-----------------------------------|--------------------------|------------------------------------------|
+| `--track-thickness`               | `1.5em`                  | Track cross-axis size                    |
+| `--thumb-color`                   | `var(--surface-text)`    | Thumb colour                             |
+| `--thumb-color-active`            | `var(--accent)`          | Thumb colour while active                |
+| `--thumb-size`                    | `var(--track-thickness)` | Thumb size along the track axis          |
+| `--thumb-thickness`               | `2em`                    | Thumb size on the cross axis             |
+| `--thumb-radius`                  | `0`                      | Thumb border radius                      |
+| `--thumb-border`                  | `none`                   | Thumb border                             |
+| `--thumb-shadow`                  | `none`                   | Thumb box shadow                         |
+| `--background-track`              | `var(--surface-ll)`      | Track background                         |
+| `--background-track-hover`        | `--background-track`     | Track background on hover                |
+| `--background-track-value`        | `var(--surface-hh)`      | Filled (value) portion of the track      |
+| `--background-track-value-hover`  | `var(--accent)`          | Filled portion on hover                  |
+| `--background-track-value-active` | `var(--accent)`          | Filled portion while dragging            |
+
+## Examples
+
+### Horizontal layout with percentage formatter
+
+```html
+<ixfx-labelled-range-input
+  id="my-slider"
+  label="Mix"
+  value="0.75"
+  style="height: 50px"
+></ixfx-labelled-range-input>
+
+<script type="module">
+  document.querySelector('#my-slider').formatter = (v) =>
+    `${Math.round(Number(v) * 100)}%`;
+</script>
+```
+
+### Custom slider colours
+
+```html
+<ixfx-labelled-range-input
+  label="Intensity"
+  value="0.7"
+  style="
+    --background-track-value: linear-gradient(to right, hsl(200 80% 40%), hsl(260 80% 50%));
+    --thumb-radius: 999px;
+  "
+></ixfx-labelled-range-input>
+```
+
+### Force mini mode
+
+```html
+<ixfx-labelled-range-input label="Vol" value="0.5" style="--mini: 1">
+</ixfx-labelled-range-input>
+```
+
+### Listen for changes
+
+```js
+const el = document.querySelector('ixfx-labelled-range-input');
+
+// Committed value (slider release or number edit)
+el.addEventListener('change', (e) => console.log(e.detail.value));
+
+// Every slider move
+el.addEventListener('input', (e) => console.log(e.detail.value));
+```

package/docs-user/led.md

@@ -0,0 +1,40 @@
+# `ixfx-led`
+
+An LED indicator component with color mixing and optional blinking animation.
+
+```html
+<ixfx-led></ixfx-led>
+<ixfx-led lit color="oklch(60% 0.2 120)"></ixfx-led>
+<ixfx-led blinking rate="300"></ixfx-led>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type     | Default                  | Description                            |
+|----------------------|----------|--------------------------|----------------------------------------|
+| `lit`                | `boolean`| `false`                  | Whether the LED is illuminated         |
+| `value`              | `number` | `0`                      | Value 0-1 used for brightness calculation |
+| `color`              | `string` | `'oklch(50% 0.15 25)'`   | LED color (oklch recommended)          |
+| `blinking`           | `boolean`| `false`                  | Enable blinking animation              |
+| `rate`               | `number` | `500`                    | Blinking interval in milliseconds      |
+
+### CSS custom properties
+
+| Property | Default | Description       |
+|----------|---------|-------------------|
+| `--size` | `1ex`   | LED diameter      |
+| `--colour` | `oklch(50% 0.15 25)` | LED colour (overrides `color` attribute) |
+
+### Usage notes
+
+The LED brightness is calculated as `color-mix(color, white, (1 - value) * 50%)`. Set `value` to 0 for off and 1 for fully lit.
+
+For blinking, setting `rate` below 300ms adjusts the transition duration automatically for smoother animation.
+
+### TypeScript types
+
+```ts
+// LED color is a CSS color string
+led.color = 'oklch(70% 0.15 200)';
+led.value = 0.75; // 75% lit
+```