@ixfx/components 0.3.1 → 0.4.0

package/docs-user/swipe.md

@@ -0,0 +1,44 @@
+# `ixfx-swipe`
+
+A touch-friendly swipe/nudge component. User taps and drags to generate a value in range [-1, 1]. Value is emitted only on pointer release.
+
+```html
+<ixfx-swipe></ixfx-swipe>
+```
+
+```js
+const swipe = document.querySelector('ixfx-swipe');
+swipe.addEventListener('input', e => {
+  console.log(e.detail.value); // -1 to 1
+});
+```
+
+### Properties / attributes
+
+| Attribute / Property   | Type     | Default | Description                                |
+|-----------------------|----------|---------|--------------------------------------------|
+| `barSpacing`          | `number` | `20`    | Center-to-center pixel distance between bars |
+| `barWidth`            | `number` | `14`    | Pixel width of each bar                    |
+| `debounceMs`          | `number` | `200`   | Pause after release before retraction begins |
+| `retractDurationMs`   | `number` | `400`   | Spring-back animation duration in ms        |
+
+### Events
+
+| Event   | Detail               | Description                                 |
+|---------|----------------------|---------------------------------------------|
+| `input` | `{ value: number }`  | Fired on pointer release with drag value (-1 to 1) |
+
+### CSS custom properties
+
+| Property            | Default              | Description                      |
+|---------------------|----------------------|----------------------------------|
+| `--swipe-color-a`   | `var(--surface-4)`   | Fill color for even-indexed bars |
+| `--swipe-color-b`   | `var(--surface-5)`   | Fill color for odd-indexed bars  |
+| `--swipe-border-color` | `var(--border)`    | Border color                     |
+
+### Usage notes
+
+- A full drag across the component width equals ±1
+- Value is emitted as `input` only on `pointerup` (not during drag)
+- Spring-back animation uses cubic ease-out: `1 - (1 - t)³`
+- Touch-action is set to `none` for reliable touch handling

package/docs-user/tabs.md

@@ -0,0 +1,217 @@
+# Tab layout components
+
+A complete tabbed interface system using several coordinated components:
+
+- **`ixfx-tab-layout`** — Layout wrapper (minimal)
+- **`ixfx-tab-layout-item`** — Individual tab item within layout
+- **`ixfx-tab-list`** — Tab header bar with tab buttons
+- **`ixfx-tab-list-item`** — Individual tab button
+- **`ixfx-tab-panel`** — Content panel for a single tab
+- **`ixfx-tab-panels`** — Container managing multiple panels
+
+## Basic usage
+
+```html
+<ixfx-tab-layout>
+  <ixfx-tab-list>
+    <ixfx-tab-list-item id="tab-home" for="panel-home">Home</ixfx-tab-list-item>
+    <ixfx-tab-list-item id="tab-profile" for="panel-profile">Profile</ixfx-tab-list-item>
+  </ixfx-tab-list>
+  
+  <ixfx-tab-panels>
+    <ixfx-tab-panel id="panel-home">Home content</ixfx-tab-panel>
+    <ixfx-tab-panel id="panel-profile">Profile content</ixfx-tab-panel>
+  </ixfx-tab-panels>
+</ixfx-tab-layout>
+```
+
+Wire them together:
+
+```js
+const tabList = document.querySelector('ixfx-tab-list');
+const tabPanels = document.querySelector('ixfx-tab-panels');
+tabList.addEventListener('change', e => {
+  tabPanels.selectPanel(e.detail.selected);
+});
+```
+
+---
+
+## `ixfx-tab-list`
+
+Manages tab selection and keyboard navigation.
+
+### Properties / attributes
+
+| Attribute / Property | Type                              | Default        | Description                      |
+|---------------------|-----------------------------------|----------------|----------------------------------|
+| `orientation`       | `'horizontal' \| 'vertical-stack' \| 'vertical-side'` | `'horizontal'` | Layout direction |
+| `flip`              | `boolean`                          | `false`        | Flip indicator to opposite side   |
+| `scrollable`        | `boolean`                          | `false`        | Enable scroll overflow           |
+
+### Events
+
+| Event    | Detail                                               | Description               |
+|----------|------------------------------------------------------|---------------------------|
+| `change` | `{ previous, selected, for }`                       | Tab selection changed     |
+
+### Methods
+
+| Method             | Argument | Returns | Description            |
+|--------------------|----------|---------|------------------------|
+| `getSelectedElement()` | — | `TabListItemElement \| undefined` | Get currently selected tab |
+| `selectElement(el)` | `HTMLElement` | `void` | Programmatically select a tab |
+
+### CSS custom properties
+
+| Property           | Default          | Description               |
+|--------------------|------------------|---------------------------|
+| `--activated-colour` | `var(--accent)` | Active tab color          |
+| `--colour`          | `var(--surface-4)` | Inactive tab background |
+| `--scroll-max-height` | `200px`      | Max height when scrollable |
+
+---
+
+## `ixfx-tab-list-item`
+
+Individual tab button within the tab list.
+
+### Properties / attributes
+
+| Attribute / Property  | Type     | Default | Description                    |
+|-----------------------|----------|---------|--------------------------------|
+| `closeable`           | `boolean`| `false` | Show close button               |
+| `iconName`            | `string \| undefined` | `undefined` | Icon to display      |
+| `description`         | `string \| undefined` | `undefined` | Tooltip description |
+| `commandActive`       | `string \| undefined` | `undefined` | Command ID that triggers click |
+| `registry`            | `CommandRegistry \| undefined` | `undefined` | Command registry for `commandActive` |
+
+### Slots
+
+| Slot        | Description                                                                 |
+|-------------|-----------------------------------------------------------------------------|
+| *(default)* | Tab label text                                                              |
+| `toolbar`   | Buttons or controls shown right-aligned when the tab is **selected**, before the close button. Multiple elements may use `slot="toolbar"`. |
+
+Toolbar buttons should use a plain icon-button style so they blend with the tab chrome. Clicks on toolbar content do not stop propagation — because the toolbar is only visible when the tab is already selected, this has no side-effect on tab switching.
+
+```html
+<!-- Single icon button in toolbar -->
+<ixfx-tab-list-item selected for="panel-home" closeable>
+  Home
+  <button slot="toolbar" type="button" class="tab-toolbar-btn" aria-label="Refresh">
+    <ixfx-icon name="refresh"></ixfx-icon>
+  </button>
+</ixfx-tab-list-item>
+```
+
+Multiple elements can occupy the toolbar slot:
+
+```html
+<ixfx-tab-list-item for="panel-sources" closeable>
+  Sources
+  <button slot="toolbar" type="button" class="tab-toolbar-btn" aria-label="Refresh">
+    <ixfx-icon name="refresh"></ixfx-icon>
+  </button>
+  <button slot="toolbar" type="button" class="tab-toolbar-btn" aria-label="Filter">
+    <ixfx-icon name="filter"></ixfx-icon>
+  </button>
+  <button slot="toolbar" type="button" class="tab-toolbar-btn" aria-label="Settings">
+    <ixfx-icon name="settings"></ixfx-icon>
+  </button>
+</ixfx-tab-list-item>
+```
+
+Use `ixfx-menu-trigger` with `slot="trigger"` to add a popup menu to the toolbar:
+
+```html
+<ixfx-tab-list-item for="panel-console" closeable>
+  Console
+  <ixfx-menu-trigger slot="toolbar" placement="bottom-start">
+    <button slot="trigger" type="button" class="tab-toolbar-btn" aria-label="Console options">
+      <ixfx-icon name="filter"></ixfx-icon>
+    </button>
+    <ixfx-menu-container slot="menu">
+      <ixfx-menu-item command="console-clear" label="Clear console"></ixfx-menu-item>
+      <ixfx-menu-separator></ixfx-menu-separator>
+      <ixfx-menu-item command="console-filter-errors" label="Errors only"></ixfx-menu-item>
+      <ixfx-menu-item command="console-filter-all" label="Show all"></ixfx-menu-item>
+    </ixfx-menu-container>
+  </ixfx-menu-trigger>
+</ixfx-tab-list-item>
+```
+
+A recommended `.tab-toolbar-btn` style for the page stylesheet:
+
+```css
+.tab-toolbar-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: var(--space-xs);
+  color: inherit;
+  border-radius: var(--radius-s);
+  opacity: var(--prominence-idle-opacity);
+  transition: opacity var(--transition, 0.15s), background var(--transition, 0.15s);
+}
+.tab-toolbar-btn:hover {
+  background: var(--surface-5);
+  opacity: var(--prominence-tickled-opacity);
+}
+```
+
+### Events
+
+| Event    | Detail | Description                |
+|----------|--------|----------------------------|
+| `close`  | —      | Fired when close button clicked; item removes itself from DOM |
+
+### CSS custom properties
+
+| Property                | Default          | Description                  |
+|-------------------------|------------------|------------------------------|
+| `--selected-colour`     | `var(--accent)`  | Text color when selected     |
+| `--selected-border-width` | `1px`         | Border width when selected   |
+| `--padding`             | `var(--space-m)` | Tab padding                  |
+
+### CSS parts
+
+| Part       | Description              |
+|------------|--------------------------|
+| `item`     | The tab item container   |
+| `label`    | Label text span          |
+
+---
+
+## `ixfx-tab-panel`
+
+Single content panel. Hidden unless it has the `selected` attribute.
+
+### CSS
+
+When `selected`, displays as `display: block` with `background: var(--surface-3)`. Otherwise uses `display: none`.
+
+---
+
+## `ixfx-tab-panels`
+
+Manages multiple `ixfx-tab-panel` children, selecting one at a time.
+
+### Properties / attributes
+
+| Property              | Type                        | Description                        |
+|-----------------------|-----------------------------|------------------------------------|
+| `onUnselectedPanel`   | `(id, el) => void`          | Callback when panel is de-selected |
+| `onSelectingPanel`    | `(id, el) => void`          | Callback before panel is selected  |
+| `onSelectedPanel`     | `(id, el) => void`          | Callback after panel is selected   |
+
+### Methods
+
+| Method              | Argument | Returns | Description                      |
+|---------------------|----------|---------|----------------------------------|
+| `getSelectedElement()` | —      | `TabPanelElement \| undefined` | Get currently selected panel |
+| `selectPanel(id)`  | `string` | `boolean` | Select panel by ID; returns true if found |
+| `syncWithList(el)`  | `TabListElement` | `void` | Sync panel selection to tab list |

package/docs-user/timeline.md

@@ -0,0 +1,116 @@
+# `ixfx-timeline`
+
+A canvas-based timeline component with tracks, events, zoom/pan, and vertical track resizing. Suitable for visualizing time-series data, event logs, or scheduling.
+
+```html
+<ixfx-timeline id="timeline"></ixfx-timeline>
+```
+
+```js
+const tl = document.querySelector('#timeline');
+
+tl.tracks = [
+  { key: 'track-1', label: 'Schedule A', height: 60 },
+  { key: 'track-2', label: 'Schedule B', height: 48 },
+];
+
+tl.events = [
+  { id: 'e1', trackKey: 'track-1', start: 100, end: 200 },
+  { id: 'e2', trackKey: 'track-2', start: 150, end: 250 },
+  { id: 'e3', trackKey: 'track-1', start: 300, end: 400 },
+];
+
+tl.min = 0;
+tl.max = 1000;
+
+tl.formatLabel = (v) => `${v}ms`;
+```
+
+### Properties / attributes
+
+| Attribute / Property       | Type                   | Default        | Description                                  |
+|---------------------------|------------------------|----------------|----------------------------------------------|
+| `tracks`                  | `TimelineTrack[]`      | `[]`           | Array of track definitions                   |
+| `events`                  | `TimelineEvent[]`      | `[]`           | Array of event definitions                   |
+| `min`                     | `number`               | `0`            | Minimum time value                           |
+| `max`                     | `number`               | `1000`         | Maximum time value                           |
+| `trackHeight`             | `TrackHeightMode`      | `'fixed'`      | `'fixed'`, `'free'`, or `'none'`             |
+| `userScale`               | `UserScale`            | `'normal'`     | Grid scaling mode: `'normal'` or `'time'`    |
+| `reorderable`             | `boolean`              | `false`        | Allow drag-to-reorder tracks (future)        |
+| `meta`                    | `boolean`              | `false`        | Show metadata/resizer area                   |
+| `altMajorBg`              | `boolean`              | `false`        | Alternate major grid row backgrounds         |
+| `defaultTrackHeight`      | `number`               | `48`           | Default track height in pixels               |
+| `gridMode`                | `GridMode`             | `'adaptive'`   | Grid resolution mode                         |
+| `minorStep`               | `number`               | `10`           | Minor grid step size                         |
+| `onDragging`              | `DragSnappingFn \| null` | `null`       | Callback during event drag                  |
+
+### Events
+
+| Event              | Detail                                              | Description                      |
+|--------------------|-----------------------------------------------------|----------------------------------|
+| `selection-change` | `{ selectedIds: string[] }`                         | Selection set changed            |
+| `tickle-change`    | `{ event: TimelineEvent \| null }`                 | Hovered (tickled) event changed |
+| `track-select`     | `{ trackKey: string, shiftKey: boolean }`          | Track tab was clicked            |
+| `track-resize`     | `{ trackKey: string, height: number }`            | Track height was changed         |
+| `dragging`         | `{ eventId, start, end, trackKey, rawLogicalX, rawY, originTrackKey }` | Ongoing drag update |
+
+### Methods
+
+| Method                  | Returns | Description                                    |
+|-------------------------|---------|------------------------------------------------|
+| `setPpu(ppu)`          | `void`  | Set pixels-per-unit zoom level                 |
+| `setViewRange(range)`  | `void`  | Set horizontal view range `{ min, max }`       |
+| `setZoomPan(viewMin, ppu)` | `void` | Set zoom and pan atomically                  |
+| `setVerticalZoomPan(vMin, vMax)` | `void` | Set vertical zoom/pan               |
+| `selectAll()`          | `void`  | Select all events                              |
+| `deselectAll()`        | `void`  | Clear selection                                |
+| `getTrackEvents(trackKey)` | `TimelineEvent[]` | Get events for a track      |
+| `resetTrackHeights()`  | `void`  | Reset all track heights to default              |
+| `getVCanvas()`         | `VCanvasElement \| null` | Get underlying virtual canvas element |
+| `get tickledEvent`     | `TimelineEvent \| null` | Currently hovered event (getter)     |
+| `get selectedIds()`    | `readonly string[]` | Currently selected event IDs (getter/setter) |
+
+### Static helpers
+
+| Method                 | Description                           |
+|------------------------|---------------------------------------|
+| `defaultDragSnapping`  | No-op snapping (passthrough)           |
+| `gridSnapping`         | Snap to nearest minor gridline         |
+
+### CSS custom properties
+
+| Property                    | Default | Description                        |
+|-----------------------------|---------|------------------------------------|
+| `--timeline-tab-width`      | `120`   | Track tab column width              |
+| `--timeline-tab-bg`         | `#2a2a2a` | Default tab background          |
+| `--timeline-tab-text`       | `#ccc`  | Default tab text color             |
+| `--timeline-tab-selected-bg`| `#3498db` | Selected tab background         |
+| `--timeline-grid-major-color`| `rgba(255,255,255,0.12)` | Major grid line color |
+
+### TypeScript types
+
+Import from `src/timeline/types.js`:
+- `TimelineTrack`, `TimelineEvent`, `TimelineTrackResizeDetail`, `GridMode`, `GridResolution`, `ViewRange`, `TrackHeightMode`, `UserScale`
+
+---
+
+## `ixfx-timeline-track-tab`
+
+Individual track tab in the timeline's left margin. Handles display, selection, and resize.
+
+### Properties / attributes
+
+| Attribute / Property  | Type      | Default | Description                        |
+|------------------------|-----------|---------|------------------------------------|
+| `label`                | `string`  | `''`    | Track label text                   |
+| `trackKey`             | `string`  | `''`    | Associated track key                |
+| `selected`             | `boolean` | `false` | Whether track is selected           |
+| `reorderable`          | `boolean` | `false` | Show drag handle                   |
+| `resizable`            | `boolean` | `false` | Enable bottom-edge resize           |
+
+### Events
+
+| Event             | Detail                              | Description                    |
+|-------------------|-------------------------------------|--------------------------------|
+| `track-resize-move` | `{ trackKey, height }`             | Live preview during resize drag |
+| `track-resize`    | `{ trackKey, height }`              | Final height on pointer release |

package/docs-user/transitory-label.md

@@ -0,0 +1,120 @@
+# ixfx-transitory-label
+
+An inline text label that animates between values instead of changing instantly. Displays as `inline-block` and inherits text styling from its parent.
+
+```html
+<ixfx-transitory-label text="Ready" effect="fade"></ixfx-transitory-label>
+```
+
+---
+
+## Properties
+
+| Property   | Type     | Default  | Description |
+|------------|----------|----------|-------------|
+| `text`     | `string` | `""`     | The displayed text. Changing this triggers the default `effect`. |
+| `effect`   | `Effect` | `"fade"` | Transition effect used when `text` changes directly. |
+| `duration` | `number` | `300`    | Animation duration in milliseconds. |
+| `easing`   | `string` | `"ease"` | Any valid CSS `<easing-function>` value. |
+
+### `setText(msg, effect)`
+
+Set text with a specific effect for this change only, ignoring the component's default `effect` property.
+
+```ts
+label.setText('Error!', 'slide-up');
+```
+
+If a transition is already running, the new text is queued and plays immediately after.
+
+---
+
+## Effects
+
+| Value            | Description |
+|------------------|-------------|
+| `fade`           | Old text fades out as new text fades in simultaneously. |
+| `slide-right`    | Old text exits right, new text enters from the left. |
+| `slide-left`     | Old text exits left, new text enters from the right. |
+| `slide-up`       | Old text exits upward, new text enters from below. |
+| `slide-down`     | Old text exits downward, new text enters from above. |
+| `character-swap` | Characters swap one by one left-to-right with a staggered scale/fade. |
+
+```html
+<ixfx-transitory-label text="OK" effect="slide-up"></ixfx-transitory-label>
+```
+
+---
+
+## Easing
+
+The `easing` property accepts any CSS timing function. The same value applies to both the outgoing and incoming animations.
+
+| Value | Result |
+|-------|--------|
+| `ease` | Default — gradual start and end |
+| `ease-in` | Slow start, fast end |
+| `ease-out` | Fast start, slow end |
+| `ease-in-out` | Slow at both ends |
+| `linear` | Constant speed |
+| `cubic-bezier(0.34, 1.56, 0.64, 1)` | Spring — overshoots slightly before settling |
+| `cubic-bezier(0.7, 0, 0.3, 1)` | Sharp — fast in the middle, crisp stop |
+
+```html
+<ixfx-transitory-label
+  text="Ready"
+  effect="slide-right"
+  duration="400"
+  easing="cubic-bezier(0.34, 1.56, 0.64, 1)"
+></ixfx-transitory-label>
+```
+
+Easing can also be set via the CSS variable `--transitory-label-easing` without using the property:
+
+```css
+ixfx-transitory-label {
+  --transitory-label-easing: ease-out;
+}
+```
+
+---
+
+## Styling
+
+Text font, size, weight, and colour are fully inherited from the parent — no scoped styles are applied to the text content. Size the label by styling its parent or the element directly:
+
+```css
+ixfx-transitory-label {
+  font-size: 1.4em;
+  font-weight: bold;
+}
+```
+
+---
+
+## Usage examples
+
+### Auto-cycling status label
+
+```ts
+const label = document.querySelector('ixfx-transitory-label');
+const states = ['Idle', 'Loading', 'Done'];
+let i = 0;
+
+setInterval(() => {
+  label.text = states[++i % states.length];
+}, 2000);
+```
+
+### Per-update effect
+
+```ts
+label.setText('Connected', 'slide-up');
+label.setText('Disconnected', 'fade');
+```
+
+### Attribute-only usage
+
+```html
+<p>Status: <ixfx-transitory-label text="Waiting" effect="fade" duration="500"></ixfx-transitory-label></p>
+```