@ixfx/components 0.3.2 → 0.4.1

package/docs-user/crumbs.md

@@ -0,0 +1,66 @@
+# `ixfx-crumb-navigation`
+
+Breadcrumb navigation with lazy-loading child support. Uses the same `TreeNode` / `TreeItem` data model as `ixfx-tree-list`, allowing easy swapping between the two components.
+
+```html
+<ixfx-crumb-navigation></ixfx-crumb-navigation>
+```
+
+```js
+const nav = document.querySelector('ixfx-crumb-navigation');
+nav.model = {
+  root: {
+    item: { key: 'root', label: 'Home' },
+    children: [
+      { item: { key: 'docs', label: 'Documentation' }, children: [...] },
+      { item: { key: 'api', label: 'API' } }
+    ]
+  },
+  selectedNode: { item: { key: 'docs', label: 'Documentation' } }
+};
+```
+
+### Properties / attributes
+
+| Attribute / Property   | Type                            | Default     | Description                                      |
+|-----------------------|---------------------------------|-------------|--------------------------------------------------|
+| `root`                | `TreeNode \| undefined`         | `undefined` | Root node of the tree                            |
+| `model`               | `TreeDataModel \| undefined`    | `undefined` | Optional reactive tree data model                 |
+| `selectedNode`        | `TreeNode \| undefined`        | `undefined` | Currently selected node                           |
+| `loadChildren`        | `LoadChildrenCallback \| undefined` | `undefined` | Callback for lazy-loading children            |
+| `filterPredicate`     | `TreeFilterPredicate \| undefined` | `undefined` | Filter function for nodes                  |
+| `exclusivity`         | `TreeExclusivity`              | `'none'`    | Selection exclusivity mode                       |
+| `selectionFilter`     | `TreeSelectionFilter`          | `'leaf'`    | Which nodes can be selected                      |
+
+### Events
+
+| Event         | Detail                                              | Description                          |
+|---------------|-----------------------------------------------------|--------------------------------------|
+| `select`       | `{ selected: Set<TreeNode>, previous: Set<TreeNode> \| undefined }` | Fired when selection changes |
+| `item-click`   | `{ node: TreeNode, depth: number }`                | Fired when a breadcrumb label is clicked |
+| `expand`       | `{ node: TreeNode, depth: number }`                | Fired when a caret is clicked for a node with unloaded children |
+| `tickle`       | `{ node: TreeNode, depth: number }`                 | Fired when mouse enters a crumb      |
+| `activate`     | `TreeActivateEvent`                                 | Fired when a node is activated       |
+
+### Methods
+
+| Method                  | Returns | Description                                     |
+|-------------------------|---------|------------------------------------------------|
+| `navigateTo(keys)`      | `boolean` | Navigate to a node by key path. Returns false if not found. |
+| `navigateToNode(predicate)` | `boolean` | Navigate to the first node matching a predicate. |
+
+### CSS custom properties
+
+| Property         | Default                  | Description                  |
+|------------------|-------------------------|------------------------------|
+| `--text-highlight` | `var(--accent)`        | Highlight color on hover     |
+| `--separator`     | `var(--surface-muted-text)` | Separator character color |
+| `--padding-s`     | `var(--space-xs)`      | Padding between items        |
+
+### CSS parts
+
+| Part      | Description              |
+|-----------|--------------------------|
+| `crumb-segment` | Individual crumb segment |
+| `caret`   | The dropdown caret button |
+| `label`   | Clickable label text     |

package/docs-user/data-display.md

@@ -0,0 +1,98 @@
+# `ixfx-data-display`
+
+A debug data display component that renders key-value pairs from a plain object. Supports 7 inline render modes (`led`, `plot`, `plot-xy`, `plot-heat`, `plot-histogram`, `time-elapsed`, `hide`) via `configure()`, automatic mode assignment via `automap`, and recursive nested objects.
+
+```html
+<ixfx-data-display></ixfx-data-display>
+```
+
+```js
+const display = document.querySelector('ixfx-data-display');
+display.updateData({
+  temperature: 23.45,
+  humidity: 0.62,
+  status: 'active',
+});
+```
+
+### Usage modes
+
+**Text-only** (default, no config): renders all values as text. Nested objects create child `<ixfx-data-display>` elements.
+
+**`automap` attribute**: boolean values → LED, numbers → plot, objects → recursive child display, everything else → text.
+
+**`configure(config)`**: explicit render style per dot-path. Replaces any previous config and re-renders.
+
+```js
+display.configure([
+  ['flag', 'led'],
+  ['position', 'plot-xy'],
+  ['timestamp', 'time-elapsed'],
+  ['sensor.gyro', 'plot'],
+  ['sensor.accel', 'hide'],
+]);
+```
+
+### Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `updateData(value)` | `Record<string, unknown> \| unknown[]` | Store full data and update all renderers; plot values accumulate only on change |
+| `displayData(o)` | `Record<string, unknown> \| unknown[]` | Update data without change tracking |
+| `formatValue(v, options?)` | `unknown, FormattingOptions?` | Format a single value to string |
+| `configure(config)` | `[path: string, style: RendererStyle, options?: Record<string, unknown>][]` | Set render styles per path |
+
+### Properties / attributes
+
+| Attribute / Property | Type | Default | Description |
+|----------------------|------|---------|-------------|
+| `automap` | `boolean` | `false` | Auto-assign render styles: boolean→led, number→plot |
+| `configure()` | method | — | Explicit render style config |
+
+### Render styles
+
+| Style | Tag | Value types | Behaviour |
+|-------|-----|-------------|-----------|
+| `led` | `ixfx-led` | `boolean`, `number` | Toggle or proportional brightness (number mapped 0..1) |
+| `plot` | `ixfx-plot-single-axis` / `ixfx-plot-multi-axis` | `number`, `number[]`, `Record<string, number>` | Accumulated time-series |
+| `plot-xy` | `ixfx-plot-xy-axis` | `[x, y]`, `{ x, y }`, object with 2 numeric properties | XY scatter |
+| `plot-heat` | `ixfx-plot-histogram` | `number` | Heatmap (full-height bars, density via opacity) |
+| `plot-histogram` | `ixfx-plot-histogram` | `number` | Histogram (variable bar lengths) |
+| `time-elapsed` | `span` | `Date`, `number` (ms/ISO) | Relative time from value to now |
+| `hide` | — | any | Row not rendered |
+
+### Options (third element of configure tuple)
+
+| Option | Type | Applies to | Description |
+|--------|------|------------|-------------|
+| `capacity` | `number` | all plots | Max data points (default: varies by plot) |
+| `resolution` | `number` | `plot-heat`, `plot-histogram` | Bucket size (default: `0.1`) |
+| `drawStyle` | `string` | `plot` (single-axis), `plot-xy` | Render style (`line-sharp`, `line-round`, `dots`, `circles`, etc.) |
+| `orientation` | `string` | `plot-heat`, `plot-histogram` | `horizontal` or `vertical` |
+| `layout` | `string` | `plot` (multi-axis) | `overlap`, `horizontal`, `vertical`, `grid` |
+
+### Formatting options
+
+Passed to `formatValue()`:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `precision` | `number` | Fixed decimal places |
+| `roundNumbers` | `number` | Round to N significant figures |
+
+### CSS custom properties
+
+Renders rows in a CSS grid (`auto auto` columns). Uses standard surface variables:
+
+- `--surface-3` — component background
+- `--surface-2-text` — label text colour
+- `--border` — row separator
+- `--space-m`, `--space-s` — spacing
+- `--font-mono` — monospace font for values
+- `--size` — LED size (via ixfx-led default of `1ex`)
+
+### TypeScript types
+
+```ts
+import type { RendererStyle, FormattingOptions } from 'ixfxfun-components';
+```

package/docs-user/editable-label.md

@@ -0,0 +1,244 @@
+# `ixfx-editable-label` & `ixfx-editable-number`
+
+Inline editable text components. `ixfx-editable-number` extends `ixfx-editable-label` with drag-to-adjust and fill-bar visualization.
+
+---
+
+## `ixfx-editable-label`
+
+An inline text label that can be edited in place.
+
+### Modes
+
+| `mode` attribute | Behaviour |
+|---|---|
+| `label` (default) | Renders as plain text; click to enter edit mode |
+| `editor` | Always renders as a box; click or focus activates editing |
+
+### Attributes
+
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `label \| editor` | `label` | Display mode |
+| `entry-mode` | `free \| text \| number \| percent` | `free` | Character filter during input |
+| `value` | string | `""` | Current value |
+| `disabled` | boolean | — | Disables interaction |
+| `placeholder` | string | `""` | Shown when value is empty |
+
+**Entry modes:**
+- `free` — no restrictions
+- `text` — letters and spaces only
+- `number` — digits, `.`, `-`
+- `percent` — digits, `.`, `%` (strips `%` on commit; appends `%` on display)
+
+### JavaScript Properties
+
+These are set on the element object, not as HTML attributes.
+
+```js
+const el = document.querySelector('ixfx-editable-label');
+
+// Custom commit validator — return false to reject and revert
+el.validator = (value) => value.trim().length >= 3;
+
+// Transform committed value for display only (stored value unchanged)
+el.formatter = (value) => value.toUpperCase();
+
+// Override displayed text entirely (editing shows raw value)
+el.displayText = '★ Hidden ★';
+el.displayText = undefined; // clear override
+```
+
+### Events
+
+| Event | Detail | When |
+|---|---|---|
+| `change` | `{ value: string }` | On commit (Enter or blur); not fired if value unchanged |
+
+```js
+el.addEventListener('change', (e) => {
+  console.log(e.detail.value);
+});
+```
+
+The event bubbles and is composed (crosses shadow DOM boundaries).
+
+### CSS Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `--label-font-size` | `var(--text-m, 12px)` | Font size |
+| `--label-font-family` | `var(--font-family, system-ui)` | Font family |
+| `--label-color` | `var(--surface-text)` | Text colour |
+| `--label-muted-color` | `var(--surface-muted-text)` | Placeholder colour |
+| `--label-padding` | `var(--space-xs, 3px) var(--space-s, 4px)` | Inner padding |
+| `--label-radius` | `var(--radius-s, 3px)` | Border radius |
+| `--label-align` | `center` | Text alignment: `left`, `center`, or `right` |
+
+### Keyboard
+
+| Key | Action |
+|---|---|
+| `Enter` | Commit value |
+| `Escape` | Cancel and revert |
+
+### Usage Examples
+
+**Basic label (click to edit):**
+```html
+<ixfx-editable-label value="Hello"></ixfx-editable-label>
+```
+
+**Always-visible editor box:**
+```html
+<ixfx-editable-label mode="editor" value="Edit me"></ixfx-editable-label>
+```
+
+**Numbers only with placeholder:**
+```html
+<ixfx-editable-label
+  mode="editor"
+  entry-mode="number"
+  placeholder="0"
+  value="42"
+></ixfx-editable-label>
+```
+
+**Custom validator and formatter:**
+```html
+<ixfx-editable-label id="name" value="Ada"></ixfx-editable-label>
+<script>
+  const el = document.querySelector('#name');
+  el.validator = (v) => v.trim().length > 0;
+  el.formatter = (v) => v.trim();
+</script>
+```
+
+**Currency display:**
+```html
+<ixfx-editable-label id="price" entry-mode="number" value="9.99"></ixfx-editable-label>
+<script>
+  document.querySelector('#price').formatter =
+    (v) => isNaN(parseFloat(v)) ? v : `$${parseFloat(v).toFixed(2)}`;
+</script>
+```
+
+---
+
+## `ixfx-editable-number`
+
+Extends `ixfx-editable-label` with Ableton-style drag interaction and an optional fill-bar visualization. See above for all shared attributes, events, CSS variables, and JavaScript properties — only the differences are documented here.
+
+### Interaction Model
+
+| Action | Effect |
+|---|---|
+| Click | Focuses the control |
+| Drag up | Increases value |
+| Drag down | Decreases value |
+| Printable key while focused | Enters text-edit mode |
+| Enter / blur | Commits typed value |
+| Escape | Cancels typed edit and restores previous value |
+
+### Additional Attributes
+
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `min` | number | — | Minimum value (no clamping if unset) |
+| `max` | number | — | Maximum value (no clamping if unset) |
+| `step` | number | — | Snap increment; also informs decimal-place display |
+| `drag-sensitivity` | number | `1` | Steps changed per pixel of drag |
+| `precision` | number | `0` | Decimal places used when rounding drag-produced values |
+| `fill-style` | `linear` \| `circular` | — | Fill-bar style; omit to disable fill bar |
+| `linear-style` | `range` \| `bipolar` \| `unipolar` | `range` | How value maps to fill (linear mode only) |
+| `circular-style` | `grow` \| `offset` \| `dot` | `grow` | How value maps to fill (circular mode only) |
+| `no-drag` | boolean | — | Disables drag interaction; text editing still works |
+
+**`drag-sensitivity`** scales relative to `step`. With `step=0.01` and `drag-sensitivity=1`, each pixel of drag moves the value by 0.01 — sweeping `min=0` to `max=1` takes 100 px. Increase for faster/coarser control, decrease for finer.
+
+**`precision`** only affects drag-produced values. Typed values are never precision-rounded — the user can always enter more decimal places than `precision` allows.
+
+### CSS Variables (fill bar)
+
+| Variable | Default | Description |
+|---|---|---|
+| `--fill-color` | `var(--accent)` | Fill bar colour |
+| `--fill-opacity` | `0.25` | Fill bar opacity (0–1) |
+| `--fill-image` | — | Override the entire `background-image`; use `var(--value)` for position |
+
+The `--value` custom property (0–1) is set dynamically on the host element and is available in CSS expressions.
+
+### Usage Examples
+
+**Integer 0–100 with fill bar:**
+```html
+<ixfx-editable-number
+  min="0" max="100" step="1"
+  value="50"
+  fill-style="linear"
+></ixfx-editable-number>
+```
+
+**Fine-grained float (step=0.01, full range ~100px of drag):**
+```html
+<ixfx-editable-number
+  min="0" max="1" step="0.01"
+  value="0.5"
+  fill-style="linear"
+></ixfx-editable-number>
+```
+
+**No step — drag rounds to 1 decimal place, typed values unrestricted:**
+```html
+<ixfx-editable-number
+  min="0" max="10"
+  precision="1"
+  value="3.5"
+></ixfx-editable-number>
+```
+
+**Custom accent colour:**
+```html
+<ixfx-editable-number
+  min="0" max="100" value="60"
+  fill-style="linear"
+  style="--fill-color: oklch(60% 0.2 30); --fill-opacity: 0.35;"
+></ixfx-editable-number>
+```
+
+**Green–yellow–red gradient that reveals with value:**
+```html
+<ixfx-editable-number
+  min="0" max="100" value="50"
+  fill-style="linear"
+  style="
+    --fill-image: linear-gradient(
+      to right,
+      oklch(55% 0.18 140),
+      oklch(78% 0.2 100),
+      oklch(60% 0.22 25)  calc(var(--value) * 100%),
+      var(--surface-ll, oklch(22% 0.02 240)) calc(var(--value) * 100%)
+    );
+  "
+></ixfx-editable-number>
+```
+
+**Saturation tied to value:**
+```html
+<ixfx-editable-number
+  min="0" max="100" value="50"
+  fill-style="linear"
+  style="
+    --fill-color: oklch(65% calc(var(--value) * 0.3) 250);
+    --fill-opacity: 1;
+  "
+></ixfx-editable-number>
+```
+
+**Formatter (display as percentage):**
+```html
+<ixfx-editable-number id="vol" min="0" max="1" step="0.01" value="0.75"></ixfx-editable-number>
+<script>
+  document.querySelector('#vol').formatter = (v) => `${Math.round(parseFloat(v) * 100)}%`;
+</script>
+```