@ixfx/components 0.3.1 → 0.4.0

package/docs-user/panel.md

@@ -0,0 +1,250 @@
+# Panel
+
+An collapsible panel component with support for titles, icons, toolbars, and multiple visual variants.
+
+```html
+<ixfx-panel title="Settings">
+  <p>Panel content goes here.</p>
+</ixfx-panel>
+```
+
+---
+
+## `ixfx-panel`
+
+### Properties / attributes
+
+| Attribute / Property      | Type                                              | Default       | Description                                      |
+|--------------------------|---------------------------------------------------|---------------|--------------------------------------------------|
+| `collapsed`              | boolean                                           | `false`       | Whether the panel is collapsed (content hidden)  |
+| `orientation`            | `'horizontal'` \| `'vertical'`                    | `'horizontal'`| Layout direction of title bar                   |
+| `title`                  | string                                            | `''`          | Panel title text                                |
+| `icon-name`              | string                                            | `''`          | Icon name from the registry                      |
+| `closable`              | boolean                                           | `false`       | Shows a close button that removes the panel     |
+| `toggle-interaction`     | `'implicit'` \| `'explicit'` \| `'disabled'`       | `'implicit'`   | How users can toggle the panel (see below)      |
+| `variant`                | `'titlebar'` \| `'midline'`                       | `'titlebar'`  | Visual style of the panel                       |
+
+### Toggle interaction modes
+
+| Mode       | Behavior                                                                 |
+|------------|--------------------------------------------------------------------------|
+| `implicit` | Clicking the caret button or anywhere in the title bar toggles the panel |
+| `explicit` | Only clicking the caret button toggles the panel                         |
+| `disabled` | Caret is hidden; no user toggle possible (programmatic only)          |
+
+### Slots
+
+| Slot        | Description                                      |
+|-------------|--------------------------------------------------|
+| default     | Panel content (shown when expanded)              |
+| `toolbar`   | Buttons or other elements in the title bar toolbar |
+
+### Events
+
+| Event    | Detail                             | Description                           |
+|----------|------------------------------------|---------------------------------------|
+| `toggle` | `{ collapsed: boolean }`           | Fired when panel expand/collapse state changes |
+| `close`  | —                                 | Fired when close button is clicked; panel is removed from DOM |
+
+```js
+const panel = document.querySelector('ixfx-panel');
+
+panel.addEventListener('toggle', e => {
+  console.log('Panel collapsed:', e.detail.collapsed);
+});
+
+panel.addEventListener('close', () => {
+  console.log('Panel closed and removed');
+});
+```
+
+### Icons
+
+Icon names resolve against the icon registry. Register custom icons with `registerIcon(name, svgString)` from `src/icons/registry.ts`.
+
+Built-in icon names: `check`, `chevron-down`, `chevron-right`, `close`.
+
+---
+
+## Visual variants
+
+### `titlebar` variant (default)
+
+The standard panel style with a visible header bar above the content area:
+
+```html
+<ixfx-panel title="Settings" icon-name="settings">
+  <p>Content here</p>
+</ixfx-panel>
+```
+
+- Header uses `--surface-4` background
+- Content area has inset shadow for depth
+- Rounded corners (`--radius-m`)
+
+### `midline` variant
+
+A lightweight, minimal style with a horizontal line running through the title text:
+
+```html
+<ixfx-panel title="Settings" variant="midline" icon-name="settings">
+  <p>Content here</p>
+</ixfx-panel>
+```
+
+- No background or border on the host element
+- Title bar is transparent with the title text overlaid
+- A debossed line runs horizontally (or vertically for `orientation="vertical"`) behind the title text
+- The line is visible between the title text and toolbar buttons
+- Useful for section headers or metadata display
+
+---
+
+## Vertical orientation
+
+Panels can display vertically with the title bar on the left side:
+
+```html
+<ixfx-panel title="Device" orientation="vertical" icon-name="server">
+  <p>Content here</p>
+</ixfx-panel>
+```
+
+For `variant="midline"` with `orientation="vertical"`, the debossed line runs vertically alongside the rotated title text.
+
+---
+
+## With toolbar
+
+Add buttons or other controls to the title bar using the `toolbar` slot:
+
+```html
+<ixfx-panel title="Document">
+  <div slot="toolbar">
+    <button type="button" data-tooltip="Print">
+      <ixfx-icon name="printer"></ixfx-icon>
+    </button>
+  </div>
+  <p>Document content</p>
+</ixfx-panel>
+```
+
+Clicking toolbar buttons does not toggle the panel when `toggle-interaction="implicit"`.
+
+---
+
+## Collapsed by default
+
+Use the `collapsed` attribute to start the panel in collapsed state:
+
+```html
+<ixfx-panel title="Advanced" collapsed>
+  <p>This content is hidden initially</p>
+</ixfx-panel>
+```
+
+---
+
+## CSS custom properties
+
+| Property                | Default                   | Description                                      |
+|-------------------------|--------------------------|--------------------------------------------------|
+| `--surface-3`           | theme-dependent          | Panel background                                |
+| `--surface-3-text`     | theme-dependent          | Title text color                                |
+| `--surface-4`           | theme-dependent          | Title bar background (titlebar variant)          |
+| `--border-subtle`       | theme-dependent          | Border color (titlebar variant)                  |
+| `--radius-m`            | `4px`                    | Border radius (titlebar variant)                 |
+| `--space-s`             | `4px`                    | Small spacing                                   |
+| `--space-m`             | `8px`                    | Medium spacing                                  |
+| `--transition`           | `0.15s ease-out`        | Animation transition duration                    |
+| `--panel-width`         | `auto`                   | Width for vertical panels                       |
+| `--panel-height`        | `auto`                   | Height for horizontal panels                    |
+| `--prominence-idle-opacity` | `0.6`             | Opacity of caret when idle                     |
+| `--prominence-tickled-opacity` | `1.0`         | Opacity of caret on hover                      |
+
+### Midline-specific line appearance
+
+| Property     | Description                                    |
+|--------------|------------------------------------------------|
+| `--surface-1` | Shadow color for debossed line (darker)       |
+| `--surface-2` | Line background color                         |
+| `--surface-5` | Highlight color for debossed line (lighter)   |
+
+---
+
+## `ixfx-panel-group`
+
+A container component that manages multiple panels with exclusive open behavior (accordion style).
+
+### Properties / attributes
+
+| Attribute / Property   | Type                                              | Default        | Description                                                   |
+|------------------------|---------------------------------------------------|----------------|---------------------------------------------------------------|
+| `orientation`          | `'horizontal'` \| `'vertical'`                   | `'horizontal'` | Layout direction of the group                                 |
+| `variant`              | `'titlebar'` \| `'midline'`                       | `'titlebar'`   | Visual style applied to all child panels                     |
+| `toggle-interaction`   | `'implicit'` \| `'explicit'` \| `'disabled'`     | `'implicit'`   | Toggle behavior applied to all child panels                   |
+| `allow-multiple`       | boolean                                           | `false`        | Allow multiple panels to be open simultaneously              |
+| `gap`                  | string                                            | `'var(--space-m)'` | CSS gap between panels                                     |
+
+### Group orientation vs child panel orientation
+
+The group's `orientation` controls:
+1. How the group lays out its child panels (flex row vs flex column)
+2. What `orientation` is automatically applied to child panels
+
+| Group `orientation` | Group layout direction | Child panels get `orientation` |
+|---------------------|------------------------|-------------------------------|
+| `horizontal`        | Flex row (horizontal)  | `vertical`                    |
+| `vertical`          | Flex column (vertical)  | `horizontal`                  |
+
+Explicit attributes on child panels take precedence over group-propagated values.
+
+### Example
+
+```html
+<ixfx-panel-group orientation="horizontal">
+  <ixfx-panel title="Panel 1">
+    <p>Content 1</p>
+  </ixfx-panel>
+  <ixfx-panel title="Panel 2">
+    <p>Content 2</p>
+  </ixfx-panel>
+  <ixfx-panel title="Panel 3">
+    <p>Content 3</p>
+  </ixfx-panel>
+</ixfx-panel-group>
+```
+
+By default, only one panel can be open at a time. Set `allow-multiple` to allow multiple panels to be open:
+
+```html
+<ixfx-panel-group orientation="horizontal" allow-multiple>
+  <!-- panels -->
+</ixfx-panel-group>
+```
+
+### Group-propagated properties
+
+When you set `variant` or `toggle-interaction` on the group, those values are automatically applied to all child panels that don't have an explicit value set. This simplifies declaration when all panels in a group share the same styling:
+
+```html
+<ixfx-panel-group variant="midline" toggle-interaction="explicit">
+  <ixfx-panel title="Settings">...</ixfx-panel>
+  <ixfx-panel title="Account">...</ixfx-panel>
+  <ixfx-panel title="Help">...</ixfx-panel>
+</ixfx-panel-group>
+```
+
+---
+
+## TypeScript types
+
+```ts
+import type { PanelOrientation, PanelVariant, PanelToggleInteraction, PanelToggleDetail, PanelGroupOrientation } from 'ixfxfun-components';
+```
+
+---
+
+## See also
+
+- [`ixfx-icon`](../icons/README.md) — Icon component used by panel

package/docs-user/plots.md

@@ -0,0 +1,361 @@
+# Plot Components
+
+SVG-based plotting components for visualising data streams.
+
+```bash
+npm install @ixfx/plots
+```
+
+---
+
+## Overview
+
+All plot components share a common rendering approach (SVG, intrinsic sizing via ResizeObserver, theme-aware CSS variables) but differ in what they visualise:
+
+| Component | Data shape | Axis meaning | Draw styles | Age/colour | Key use case |
+|-----------|-----------|--------------|-------------|------------|-------------|
+| `<ixfx-plot-single-axis>` | 1D values (ordered sequence) | X = index/order, Y = value | 9 styles (line, marker, bar, hist) | Age + colour | Time series, sensor readings |
+| `<ixfx-plot-xy-axis>` | 2D (x, y) pairs | X = value, Y = value | 2 styles (circle, square) | Age + colour | Scatter plots, Lissajous |
+| `<ixfx-plot-multi-axis>` | Named 1D series | Same as single-axis per series | Defined per series via `styleSeries()` | Per-series colour | Multiple simultaneous signals |
+| `<ixfx-plot-histogram>` | 1D values (unordered distribution) | X/Y = value bins, bar length = density | Single bar style | Opacity via `--value` | Value distribution, heat map |
+
+---
+
+## Common Features
+
+### Adding Data
+
+```typescript
+// single-axis / histogram
+plot.add(42);
+plot.set([1, 2, 3, 4, 5]);
+plot.clear();
+
+// xy-axis — requires x and y
+plot.add(0.5, 0.8);
+plot.setXY([1,2,3], [4,5,6]);
+plot.clear();
+
+// multi-axis — named values
+plot.addData({ temperature: 22, humidity: 60 });
+plot.clear();
+```
+
+### Common Properties
+
+| Property | Type | Default | Applies to | Description |
+|----------|------|---------|-------------|-------------|
+| `title` | `string` | `""` | all | Title displayed on the plot |
+| `capacity` | `number` | `100` | single-axis, xy-axis, histogram | Max data points to store |
+| `paused` | `boolean` | `false` | all but multi-axis | Pause rendering updates |
+
+### Inline (Declarative) Data
+
+Provide initial data directly in the HTML for **single-axis** and **histogram**:
+
+```html
+<ixfx-plot-single-axis>1, 2, 0.5, 0.3, -1</ixfx-plot-single-axis>
+<ixfx-plot-histogram>0.1 0.4 0.7 0.3 0.9</ixfx-plot-histogram>
+```
+
+Numbers can be separated by commas, spaces, or semicolons. Programmatic `set()` / `add()` calls take precedence.
+
+### CSS Variables (shared)
+
+| Variable | Default | Applies to | Description |
+|----------|---------|-------------|-------------|
+| `--plot-color` | `var(--accent)` | single-axis, xy-axis | Base colour for data points |
+| `--plot-text` | `var(--surface-2-text, #fff)` | all | Text colour for title |
+
+### Sizing
+
+All components use `display: inline-block` with `width: 100%; height: 100%` by default. They observe their container via `ResizeObserver`, so sizing is controlled entirely by the parent:
+
+```css
+.plot-container {
+  width: 100%;
+  height: 200px;
+}
+.plot-container > ixfx-plot-* {
+  width: 100%;
+  height: 100%;
+}
+```
+
+---
+
+## `<ixfx-plot-single-axis>`
+
+Renders a 1D data series as a time-series / ordered-sequence plot.
+
+**Tag:** `<ixfx-plot-single-axis>`
+
+### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `drawStyle` | `SingleAxisDrawStyle` | `line-sharp` | Rendering style |
+| `ageStyle` | `SingleAxisAgeStyle` | `none` | Ageing effect |
+| `tooltips` | `boolean` | `true` | Show tooltip on hover |
+| `precise` | `boolean` | `false` | Show latest value in corner |
+| `persistentScale` | `boolean` | `true` | Keep same scale; if `false`, scale adjusts to visible data |
+| `clickPauses` | `boolean` | `false` | Toggle pause on click |
+| `shaded` | `boolean` | `false` | Shaded area under line |
+| `areaColor` | `string` | `""` | Custom shade colour |
+| `colorMode` | `ColourMode` | `fixed` | Colour mapping |
+| `colorEasing` | `string` | `""` | Easing for colour mapping |
+| `colorScale` | `string` | `""` | Colour palette for `scale` mode |
+
+### Draw Styles
+
+| Style | Description |
+|-------|-------------|
+| `line-sharp` | Sharp line segments (default) |
+| `line-round` | Rounded line segments |
+| `circles` | Circle markers |
+| `squares` | Square markers |
+| `vbar` | Vertical bars from baseline |
+| `hbar` | Horizontal bars |
+| `hist-bottom` | Histogram bars from bottom |
+| `hist-top` | Histogram bars from top |
+| `hist-middle` | Histogram bars from middle |
+
+### Age Styles
+
+| Style | Description |
+|-------|-------------|
+| `none` | No effect (default) |
+| `opacity` | Older points fade out |
+| `desaturation` | Older points grayscale |
+| `size` | Older points shrink |
+
+Applies to discrete draw styles only (`circles`, `squares`, `vbar`, `hbar`, `hist-*`).
+
+### Colour Mapping
+
+| Mode | Description |
+|------|-------------|
+| `fixed` | Single colour (default) |
+| `opacity` | Varying opacity |
+| `hue` | Map value to hue |
+| `saturation` | Map value to saturation |
+| `lightness` | Map value to lightness |
+| `scale` | Interpolate through a colour palette |
+
+Use `color-easing` for easing functions or `color-scale` for custom palettes:
+
+```html
+<ixfx-plot-single-axis color-mode="scale" color-scale="green,yellow,red">
+```
+
+### Events
+
+- **`plot-datapoint-click`** — `{ value: number, index: number }`
+
+### Example
+
+```html
+<ixfx-plot-single-axis draw-style="line-round" title="Temperature" capacity="50"></ixfx-plot-single-axis>
+<script type="module">
+  import '@ixfx/plots';
+  const plot = document.querySelector('ixfx-plot-single-axis');
+  setInterval(() => plot.add(Math.random() * 100), 100);
+</script>
+```
+
+---
+
+## `<ixfx-plot-xy-axis>`
+
+Renders a 2D X/Y scatter or line plot.
+
+**Tag:** `<ixfx-plot-xy-axis>`
+
+### Properties
+
+Same colour/age properties as single-axis. Add via `plot.add(x, y)` or `plot.setXY(xArray, yArray)`.
+
+### Draw Styles
+
+| Style | Description |
+|-------|-------------|
+| `circles` | Circle markers (default) |
+| `squares` | Square markers |
+
+### Events
+
+- **`plot-datapoint-click`** — `{ x: number, y: number, index: number }`
+
+### Custom Formatting
+
+Override `valueFormat`:
+
+```typescript
+plot.valueFormat = (x, y) => `(${x.toFixed(2)}, ${y.toFixed(2)})`;
+```
+
+### Example
+
+```html
+<ixfx-plot-xy-axis draw-style="circles" age-style="opacity" title="Position"></ixfx-plot-xy-axis>
+<script type="module">
+  import '@ixfx/plots';
+  const plot = document.querySelector('ixfx-plot-xy-axis');
+  let t = 0;
+  setInterval(() => { plot.add(Math.sin(t), Math.cos(t)); t += 0.1; }, 50);
+</script>
+```
+
+---
+
+## `<ixfx-plot-multi-axis>`
+
+Displays multiple named 1D series simultaneously with configurable layout.
+
+**Tag:** `<ixfx-plot-multi-axis>`
+
+Unlike the other plot components, multi-axis manages multiple independent data streams. Each series has its own colour, and the layout can arrange them as overlapped, horizontal, vertical, or in a grid.
+
+### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `layout` | `"overlap"` \| `"horizontal"` \| `"vertical"` \| `"grid"` | `overlap` | How to arrange the series |
+| `gridMinWidth` | `number` | `180` | Min column width in `grid` layout (px) |
+| `capacity` | `number` | `100` | Max data points per series |
+
+### Methods
+
+```typescript
+plot.addData({ temperature: 22, humidity: 60, pressure: 1013 });
+plot.styleSeries('temperature', { 'plot-color': '#ff6b6b' });
+plot.clear();
+```
+
+### Layouts
+
+| Layout | Description |
+|--------|-------------|
+| `overlap` | All series drawn on the same axes (default) |
+| `horizontal` | Each series in its own row |
+| `vertical` | Each series in its own column |
+| `grid` | Auto-fill grid, each cell holds one series |
+
+### Per-Series Styling
+
+```typescript
+plot.styleSeries('temperature', {
+  'plot-color': '#ff6b6b',
+  'draw-style': 'line-round',
+});
+plot.styleSeries('humidity', {
+  'plot-color': '#4ecdc4',
+  'draw-style': 'hist-bottom',
+});
+```
+
+### Events
+
+- **`plot-datapoint-click`** — `{ series: string, value: number, index: number }`
+- **`plot-series-add`**, **`plot-series-remove`** — Series lifecycle
+
+### Example
+
+```html
+<ixfx-plot-multi-axis layout="horizontal" class="plot-lg"></ixfx-plot-multi-axis>
+<script type="module">
+  import '@ixfx/plots';
+  const plot = document.querySelector('ixfx-plot-multi-axis');
+  let t = 0;
+  setInterval(() => {
+    plot.addData({ x: Math.sin(t), y: Math.cos(t), z: Math.sin(t * 0.5) });
+    t += 0.1;
+  }, 80);
+</script>
+```
+
+---
+
+## `<ixfx-plot-histogram>`
+
+Renders a histogram of value distributions. Unlike `ixfx-plot-single-axis` (where the X-axis represents ordering), this component shows a pure distribution — all values in the current buffer are binned into buckets spanning the data range. There is no time or sequence axis.
+
+**Tag:** `<ixfx-plot-histogram>`
+
+### Orientation
+
+| Value | Description |
+|-------|-------------|
+| `horizontal` (default) | X-axis = value range → vertical bars rising from bottom |
+| `vertical` | Y-axis = value range → horizontal bars extending from left (bottom-to-top = min-to-max) |
+
+### Resolution
+
+Controls bucket granularity. Value is a fraction of the available space. Default `0.10` = 10 buckets.
+
+```html
+<ixfx-plot-histogram resolution="0.05"></ixfx-plot-histogram>  <!-- 20 buckets -->
+<ixfx-plot-histogram resolution="0.20"></ixfx-plot-histogram>  <!-- 5 buckets -->
+```
+
+### Fixed Range
+
+Set `min` / `max` attributes to fix the value range and disable automatic RangeStream scaling:
+
+```html
+<ixfx-plot-histogram min="0" max="1" resolution="0.05"></ixfx-plot-histogram>
+```
+
+### Bar Length
+
+By default, each bar's length (height in horizontal, width in vertical) is proportional to the fraction of values in that bucket — a classic histogram. Override via `--plot-histogram-bar-length` to produce a **heat-map** appearance where all bars are full-length and only colour varies:
+
+```css
+ixfx-plot-histogram {
+  --plot-histogram-bar-length: 1;
+  --plot-histogram-fill: oklch(65% 0.2 30);
+  --plot-histogram-gap: 0px;
+}
+```
+
+### CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--plot-histogram-fill` | `currentColor` | Fill colour of each bucket bar |
+| `--plot-histogram-gap` | `1px` | Gap between adjacent buckets |
+| `--plot-histogram-border-radius` | `0` | Corner radius of each bucket |
+| `--plot-histogram-bar-length` | `auto` | Fixed bar length fraction (0–1); `auto` = proportional to density |
+
+Opacity is derived from `--value` (set inline on each bucket bar):
+```css
+rect.bar {
+  opacity: calc(0.15 + var(--value) * 0.85);
+}
+```
+
+### Events
+
+- **`plot-bucket-click`** — `{ bucketIndex: number, valueMin: number, valueMax: number, relativeValue: number }`
+
+### Example
+
+```html
+<ixfx-plot-histogram title="distribution" capacity="500"></ixfx-plot-histogram>
+<script type="module">
+  import '@ixfx/plots';
+  const plot = document.querySelector('ixfx-plot-histogram');
+  setInterval(() => plot.add(Math.random()), 50);
+</script>
+```
+
+---
+
+## TypeScript
+
+```typescript
+import type { SingleAxisDrawStyle, SingleAxisAgeStyle } from '@ixfx/plots';
+import type { XyDrawStyle, XyAgeStyle } from '@ixfx/plots';
+import type { PlotHistogramOrientation, PlotHistogramBucketClickDetail } from '@ixfx/plots';
+import type { MultiAxisLayout, PlotMultiAxis } from '@ixfx/plots';
+```