@ixfx/components 0.3.1 → 0.4.0

package/docs-user/range-input.md

@@ -0,0 +1,264 @@
+# `<ixfx-range-input>`
+
+A label-free, fully styled range slider wrapping `<input type="range">`. Supports horizontal and vertical orientations, CSS variable theming, gradient fills, custom thumb shapes, and an optional value tooltip.
+
+---
+
+## Basic usage
+
+```html
+<ixfx-range-input value="0.5"></ixfx-range-input>
+```
+
+```js
+const slider = document.querySelector('ixfx-range-input');
+slider.addEventListener('input', e => console.log(e.detail.value));
+```
+
+---
+
+## Attributes / properties
+
+| Attribute / Property  | Type                        | Default        | Description                                      |
+|-----------------------|-----------------------------|----------------|--------------------------------------------------|
+| `value`               | `number`                    | `0`            | Current value within `min`..`max`                |
+| `min`                 | `number`                    | `0`            | Minimum value                                    |
+| `max`                 | `number`                    | `1`            | Maximum value                                    |
+| `step`                | `number`                    | `0.01`         | Step increment                                   |
+| `orientation`         | `"horizontal" \| "vertical"` | `"horizontal"` | Slider axis                                     |
+| `tooltip`             | `boolean`                   | `false`        | Show value tooltip on hover/focus                |
+| `tooltip-orientation` | `"top" \| "right"`          | `"top"`        | Tooltip position relative to thumb               |
+| `labelFormatter`      | `(raw, scaled) => string`   | —              | JS property (not an attribute) — custom tooltip formatter. `raw` is the value within `min`..`max`; `scaled` is the normalised 0..1 position. |
+
+---
+
+## Events
+
+Both events are `CustomEvent` instances with `{ bubbles: true, composed: true }`.
+
+| Event    | `detail` type          | Description                                        |
+|----------|------------------------|----------------------------------------------------|
+| `input`  | `{ value: number }`    | Fires continuously while dragging                  |
+| `change` | `{ value: number }`    | Fires once on release (same semantics as native)   |
+
+`value` in both events is the raw value within `min`..`max` (not normalised).
+
+---
+
+## Sizing
+
+The component fills whatever dimensions you give it via `--width` / `--height`, or explicit CSS sizing.
+
+| CSS variable | Default (horizontal) | Default (vertical) | Description              |
+|---|---|---|---|
+| `--width`    | `200px`              | `2em`              | Component width          |
+| `--height`   | `2em`                | `200px`            | Component height         |
+
+```html
+<!-- Full-width, default height -->
+<ixfx-range-input style="--width:100%"></ixfx-range-input>
+
+<!-- Tall horizontal slider -->
+<ixfx-range-input style="--width:100%; --height:4em"></ixfx-range-input>
+
+<!-- Vertical, filling a flex container -->
+<div style="height:160px; display:flex; align-items:stretch">
+  <ixfx-range-input orientation="vertical" style="--width:2em; --height:100%"></ixfx-range-input>
+</div>
+```
+
+---
+
+## Track CSS variables
+
+| Variable                                    | Default                       | Description                              |
+|---------------------------------------------|-------------------------------|------------------------------------------|
+| `--track-thickness`                         | `100%`                        | Track cross-axis size (% of component height in horizontal mode) |
+| `--background-track`                        | `var(--surface-ll)`           | Unfilled track background                |
+| `--background-track-hover`                  | `--background-track`          | Unfilled track on hover                  |
+| `--background-track-value`                  | `var(--surface-hh)`           | Filled track color (supports gradients)  |
+| `--background-track-value-hover`            | `var(--accent)`               | Filled track on hover                    |
+| `--background-track-value-active`           | `var(--accent)`               | Filled track while dragging              |
+
+### Vertical-only overrides
+
+When `orientation="vertical"` these take precedence over the horizontal vars (falling back to them when unset):
+
+| Variable                                         | Falls back to                        |
+|--------------------------------------------------|--------------------------------------|
+| `--background-track-vertical`                    | `--background-track`                 |
+| `--background-track-value-vertical`              | `--background-track-value`           |
+| `--background-track-value-hover-vertical`        | `--background-track-value-hover`     |
+| `--background-track-value-active-vertical`       | `--background-track-value-active`    |
+
+---
+
+## Thumb CSS variables
+
+| Variable              | Default                   | Description                                     |
+|-----------------------|---------------------------|-------------------------------------------------|
+| `--thumb-thickness`   | `2em`                     | Thumb size along the track axis                 |
+| `--thumb-size`        | `--track-thickness`       | Thumb size across the track axis                |
+| `--thumb-color`       | `var(--surface-text)`     | Thumb fill at rest                              |
+| `--thumb-color-active`| `var(--accent)`           | Thumb fill on hover / active                    |
+| `--thumb-radius`      | `0`                       | `border-radius` of the thumb                    |
+| `--thumb-border`      | `none`                    | `border` shorthand for the thumb                |
+| `--thumb-shadow`      | `none`                    | `box-shadow` for the thumb                      |
+
+### Using container query units for thumb sizing
+
+Because the component uses `container-type: size` internally, you can use `cqh` (1% of component height) and `cqw` (1% of component width) for reliable, dimension-agnostic sizing:
+
+```css
+/* Thumb is always a square equal to the component height */
+ixfx-range-input {
+  --thumb-thickness: 100cqh;
+  --thumb-size: 100cqh;
+}
+
+/* Thumb is 80% of component height */
+ixfx-range-input {
+  --thumb-thickness: 80cqh;
+  --thumb-size: 80cqh;
+}
+```
+
+For vertical sliders, use `cqw` (component width) to size the thumb relative to the narrow dimension:
+
+```css
+ixfx-range-input[orientation="vertical"] {
+  --thumb-thickness: 100cqw;
+  --thumb-size: 100cqw;
+}
+```
+
+---
+
+## Tooltip
+
+Add the `tooltip` attribute to show the current value above the thumb on hover/focus.
+
+```html
+<!-- Default: shows value rounded to 2 decimal places -->
+<ixfx-range-input tooltip value="0.5"></ixfx-range-input>
+
+<!-- Integer range: step=1 → no decimal places shown -->
+<ixfx-range-input tooltip min="0" max="100" step="1" value="42"></ixfx-range-input>
+
+<!-- Vertical slider: show tooltip to the right of the thumb -->
+<ixfx-range-input orientation="vertical" tooltip tooltip-orientation="right" value="0.6"></ixfx-range-input>
+```
+
+### Custom tooltip formatter
+
+Assign a function to the `labelFormatter` JS property:
+
+```js
+const slider = document.querySelector('ixfx-range-input');
+slider.labelFormatter = (rawValue, scaledValue) =>
+  `${Math.round(scaledValue * 100)}%`;
+```
+
+- `rawValue` — the value within `min`..`max`
+- `scaledValue` — normalised 0..1 position
+
+---
+
+## Examples
+
+### Accent colour override
+
+```css
+.my-slider {
+  --background-track-value: hsl(280 60% 35%);
+  --background-track-value-hover: hsl(280 80% 55%);
+  --background-track-value-active: hsl(280 80% 55%);
+  --thumb-color-active: hsl(280 80% 65%);
+}
+```
+
+```html
+<ixfx-range-input class="my-slider" value="0.5" style="--width:100%"></ixfx-range-input>
+```
+
+### Gradient fill
+
+The filled-track area uses a CSS mask, so any gradient set on `--background-track-value` shows through only up to the current value position.
+
+```css
+.gradient-fire {
+  --background-track-value: linear-gradient(to right, hsl(50 100% 45%), hsl(15 90% 50%));
+  --background-track-value-hover: linear-gradient(to right, hsl(55 100% 55%), hsl(15 100% 60%));
+  --background-track-value-active: linear-gradient(to right, hsl(55 100% 55%), hsl(15 100% 60%));
+}
+```
+
+### Pill thumb
+
+```css
+.pill {
+  --thumb-radius: 999px;
+  --thumb-thickness: 20px;
+  --thumb-size: 200cqh;
+}
+```
+
+### Circle dot thumb
+
+```css
+.dot {
+  --thumb-thickness: 100cqh;
+  --thumb-size: 100cqh;
+  --thumb-radius: 50%;
+}
+```
+
+### Ghost (outlined) thumb
+
+```css
+.ghost {
+  --thumb-color: transparent;
+  --thumb-color-active: transparent;
+  --thumb-border: 2px solid var(--accent);
+  --thumb-radius: 3px;
+  --thumb-shadow: 0 0 6px var(--accent);
+}
+```
+
+### Orientation-specific colours
+
+Both orientations can share one CSS class, with the vertical variant overriding only what it needs:
+
+```css
+.dual-color {
+  --background-track-value: hsl(210 70% 40%);              /* horizontal → blue */
+  --background-track-value-vertical: hsl(30 70% 45%);      /* vertical → orange */
+}
+```
+
+```html
+<ixfx-range-input class="dual-color" value="0.6" style="--width:100%"></ixfx-range-input>
+<ixfx-range-input class="dual-color" orientation="vertical" value="0.6"></ixfx-range-input>
+```
+
+### Listening to events
+
+```js
+const slider = document.querySelector('ixfx-range-input');
+
+// Fires on every move
+slider.addEventListener('input', ({ detail }) => {
+  console.log('moving:', detail.value);
+});
+
+// Fires once on release
+slider.addEventListener('change', ({ detail }) => {
+  console.log('settled:', detail.value);
+});
+```
+
+### Setting value programmatically
+
+```js
+slider.value = 0.75;
+```

package/docs-user/range.md

@@ -0,0 +1,12 @@
+# Range elements
+
+## Styling
+
+Range: Coloured bar that suggests values
+--range-background: (AccentColor)
+--range-thickness: (1em)
+--thumb-background: (ButtonFace)
+Tooltip
+
+--tooltip-background: (ButtonFace)
+--tooltip-color: (ButtonText)

package/docs-user/selecthorizontal.md

@@ -0,0 +1,32 @@
+# `ixfx-selecthorizontal-element`
+
+A horizontally scrolling container with snap points for child elements. Useful for scrollable lists of items that should snap into alignment.
+
+```html
+<ixfx-selecthorizontal-element>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</ixfx-selecthorizontal-element>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type     | Default | Description                |
+|----------------------|----------|---------|----------------------------|
+| `editMode`           | `boolean`| `false` | (Reserved for future use)  |
+
+### CSS custom properties
+
+Inherits border styling from global `--border` and `--accent` variables applied to slotted children.
+
+### CSS parts
+
+The component styles slotted elements with scroll snapping behavior.
+
+### Usage notes
+
+- Children should have `data-value` attribute for identification
+- Component handles `slotchange` events to update available items
+- Uses `scroll-snap-type: x mandatory` for snap alignment
+- Hidden scrollbar via `scrollbar-width: none`

package/docs-user/snap-container.md

@@ -0,0 +1,132 @@
+# `ixfx-snap-container`
+
+A container that positions its child element at configurable snap positions along an axis. The child can be dragged, clicked to snap, or controlled via keyboard.
+
+```html
+<ixfx-snap-container snap-positions="3" orientation="horizontal">
+  <button>Drag me</button>
+</ixfx-snap-container>
+```
+
+---
+
+## Properties / attributes
+
+| Attribute / Property    | Type                          | Default     | Description                                                        |
+|------------------------|-------------------------------|-------------|--------------------------------------------------------------------|
+| `orientation`          | `'horizontal'` \| `'vertical'` | `'horizontal'` | Axis along which snapping occurs. Horizontal uses x-axis; vertical uses y-axis |
+| `snap-positions`       | number                        | `3`         | Number of snap positions                                           |
+| `snap-logic`           | `'centre'` \| `'balanced'`    | `'balanced'` | How snap positions are distributed (see [Snap logic](#snap-logic)) |
+| `click-snap`           | `'closest'` \| `'step'`       | `'closest'` | How clicking in empty space snaps (see [Click snap modes](#click-snap-modes)) |
+| `snap`                 | number                        | `0`         | Current snap index (0-based)                                       |
+
+---
+
+## Snap logic
+
+### `balanced` (default)
+
+First snap position aligns with container's left/top edge. Last snap position aligns with container's right/bottom edge. Middle positions are evenly distributed.
+
+```
+Position 0 ─┬── Position 1 ─┬── Position 2 ─┬── Position 3 ─┬── Position 4
+            │                │                │                │
+────────────┼────────────────┼────────────────┼────────────────┼────────────
+Left edge   │    evenly      │    evenly      │    evenly      │ Right edge
+            │    spaced      │    spaced      │    spaced      │
+```
+
+### `centre`
+
+All snap positions are evenly distributed, ignoring edge alignment.
+
+```
+Position 0 ─┬── Position 1 ─┬── Position 2 ─┬── Position 3 ─┬── Position 4
+            │                │                │                │
+────────────┼────────────────┼────────────────┼────────────────┼────────────
+            │                │    centred      │                │
+            │                │                │                │
+```
+
+---
+
+## Click snap modes
+
+### `closest` (default)
+
+Clicking anywhere in the container (not on the child) moves the child to the nearest snap position to the click point.
+
+### `step`
+
+Clicking to the **right** of the child's center moves it one position right. Clicking to the **left** moves it one position left. Similarly for vertical orientation (up/down).
+
+This is useful for incremental navigation without dragging.
+
+---
+
+## Events
+
+| Event         | Detail                              | Description                              |
+|---------------|-------------------------------------|------------------------------------------|
+| `snap-change` | `{ previousSnap, newSnap }`         | Fired when snap index changes            |
+| `snap-input`  | `{ index }`                         | Fired continuously during drag operation |
+
+Both events bubble and are composed.
+
+```js
+container.addEventListener('snap-change', (e) => {
+  console.log(`Moved from ${e.detail.previousSnap} to ${e.detail.newSnap}`);
+});
+```
+
+---
+
+## CSS custom properties
+
+| Property               | Default    | Description                                      |
+|------------------------|------------|--------------------------------------------------|
+| `--transition-duration`| `200ms`   | Duration of snap transitions                     |
+
+The child element also receives a `--snap-index` custom property reflecting its current position:
+
+```css
+child {
+  background: hsl(calc(var(--snap-index) * 60), 70%, 50%);
+}
+```
+
+---
+
+## Keyboard navigation
+
+When the container or its child has focus:
+
+| Orientation   | Key       | Action                        |
+|---------------|-----------|-------------------------------|
+| horizontal    | LEFT      | Move to previous snap position|
+| horizontal    | RIGHT     | Move to next snap position    |
+| vertical      | UP        | Move to previous snap position|
+| vertical      | DOWN      | Move to next snap position    |
+
+---
+
+## Programmatic control
+
+All properties are writable at runtime:
+
+```js
+const container = document.querySelector('ixfx-snap-container');
+
+container.snap = 2;              // Jump to position 2
+container.snapPositions = 5;     // Change to 5 positions
+container.orientation = 'vertical'; // Switch to vertical
+```
+
+---
+
+## Usage notes
+
+- The child element should have a fixed or intrinsic size
+- The container has `overflow: hidden` and positions the child absolutely
+- Drag requires moving at least 10px before snapping engages
+- In `step` mode, clicking when already at the boundary (0 or max) does nothing

package/docs-user/split-layout.md

@@ -0,0 +1,232 @@
+# Split Layout
+
+A Lit web component that lays out two elements within a container with a resize handle to adjust their proportions.
+
+---
+
+## `ixfx-split-layout`
+
+### Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `layout` | `vertical` \| `horizontal` | `vertical` | Split orientation. `vertical` creates left/right panels, `horizontal` creates top/bottom panels. |
+| `sizeA` | `String` | `""` | CSS size for panel A (slot `a`). Can use relative (`50%`) or absolute (`100px`) values. Empty string defaults to `auto`. |
+| `sizeB` | `String` | `""` | CSS size for panel B (slot `b`). Same format as `sizeA`. |
+| `fixedA` | `Boolean` | `false` | If `true`, `sizeA` is calculated in pixels rather than percentage of whole. |
+| `fixedB` | `Boolean` | `false` | If `true`, `sizeB` is calculated in pixels rather than percentage of whole. |
+| `collapsible` | `Boolean` | `false` | If `true`, panels can be collapsed by dragging the handle to the edge. The other panel expands to fill the space. |
+| `minSizeA` | `String` | `""` | Minimum size for panel A (e.g., `"100px"` or `"20%"`). Empty means no minimum. |
+| `maxSizeA` | `String` | `""` | Maximum size for panel A. Empty means no maximum. |
+| `minSizeB` | `String` | `""` | Minimum size for panel B. |
+| `maxSizeB` | `String` | `""` | Maximum size for panel B. |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `collapsedA` | `Boolean` (reflects attribute) | `true` if panel A is currently collapsed. |
+| `collapsedB` | `Boolean` (reflects attribute) | `true` if panel B is currently collapsed. |
+
+### CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--handle-size` | `2px` | Width/height of the resize handle |
+| `--handle-colour` | `var(--surface-5)` | Colour of the resize handle |
+| `--handle-hover-colour` | `var(--surface-6)` | Colour of handle when hovering |
+| `--handle-active-colour` | `var(--accent)` | Colour of handle when being dragged |
+
+### Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `ixfx-split-collapsed` | `{ panel: 'A' \| 'B', collapsed: boolean }` | Fired when a panel is collapsed or uncollapsed via drag. |
+
+---
+
+## Basic Usage
+
+### Vertical Split (Left/Right)
+
+```html
+<ixfx-split-layout layout="vertical" style="width: 100%; height: 400px;">
+  <div slot="a" style="background: var(--surface-3);">Left Panel</div>
+  <div slot="b" style="background: var(--surface-5);">Right Panel</div>
+</ixfx-split-layout>
+```
+
+### Horizontal Split (Top/Bottom)
+
+```html
+<ixfx-split-layout layout="horizontal" style="width: 100%; height: 400px;">
+  <div slot="a" style="background: var(--surface-3);">Top Panel</div>
+  <div slot="b" style="background: var(--surface-5);">Bottom Panel</div>
+</ixfx-split-layout>
+```
+
+### With Fixed Panel
+
+```html
+<!-- Left panel fixed at 200px, right panel takes remaining space -->
+<ixfx-split-layout fixedA layout="vertical" style="width: 100%; height: 400px;">
+  <div slot="a" style="background: var(--surface-3);">Left Panel (200px)</div>
+  <div slot="b" style="background: var(--surface-5);">Right Panel (flexible)</div>
+</ixfx-split-layout>
+```
+
+---
+
+## Collapsible Panels
+
+When `collapsible` is set, dragging a resize handle to the edge collapses that panel. The other panel expands to fill the space. Dragging away from the edge uncollapses the panel.
+
+```html
+<ixfx-split-layout collapsible layout="horizontal" style="width: 100%; height: 400px;">
+  <div slot="a" style="background: var(--surface-3);">Top Panel</div>
+  <div slot="b" style="background: var(--surface-5);">Bottom Panel</div>
+</ixfx-split-layout>
+```
+
+### Collapse Events
+
+```javascript
+const split = document.querySelector('ixfx-split-layout[collapsible]');
+
+split.addEventListener('ixfx-split-collapsed', ({ detail }) => {
+  console.log(`Panel ${detail.panel} is now ${detail.collapsed ? 'collapsed' : 'uncollapsed'}`);
+});
+```
+
+---
+
+## Min/Max Size Constraints
+
+Use `minSizeA`, `maxSizeA`, `minSizeB`, and `maxSizeB` to constrain panel sizes:
+
+```html
+<ixfx-split-layout 
+  minSizeA="100px" 
+  maxSizeA="70%" 
+  minSizeB="50px"
+  layout="horizontal" 
+  style="width: 100%; height: 400px;">
+  <div slot="a" style="background: var(--surface-3);">Top Panel</div>
+  <div slot="b" style="background: var(--surface-5);">Bottom Panel</div>
+</ixfx-split-layout>
+```
+
+**Constraint rules:**
+- **Min constraints take precedence**: If both panels' minimums exceed 100% combined, they're scaled proportionally
+- **Max constraints are secondary**: If a max constraint conflicts with a min constraint, the max is ignored to satisfy the min
+- **The constrained panel gets clamped**: The other panel receives the remaining space
+
+---
+
+## Nested Splits with Two-Way Corner Resize
+
+When a `ixfx-split-layout` is nested inside slot A of an outer split, a corner zone appears at the intersection of the two resize handles. This enables simultaneous resize of both splits.
+
+```
+┌─────────────────┬────────────┐
+│                 │            │
+│   ┌─────────────┤            │
+│   │   Editor    │            │
+│   │             │            │
+│   ├─────────────┤  Sidebar   │
+│   │  Terminal   │            │
+│   │             │            │
+│   └─────────────┘            │
+└─────────────────┴────────────┘
+         ↑
+    Corner Zone
+    (drag here for two-way resize)
+```
+
+### Structure
+
+```html
+<ixfx-split-layout layout="vertical" style="width: 100%; height: 400px;">
+  <!-- Nested split is a direct child of slot A -->
+  <ixfx-split-layout slot="a" layout="horizontal" style="width: 100%; height: 100%;">
+    <div slot="a" style="background: var(--surface);">Editor</div>
+    <div slot="b" style="background: var(--surface-3);">Terminal</div>
+  </ixfx-split-layout>
+  <div slot="b" style="background: var(--surface-5);">Sidebar</div>
+</ixfx-split-layout>
+```
+
+**Note**: For the corner zone to appear, the nested split must be a direct child of slot A (no wrapper elements between the split and slot A).
+
+### Corner Zone Behavior
+
+- **Visual indicator**: A small magenta circle (12px) appears at the intersection point
+- **Cursor change**: Shows `nwse-resize` cursor when hovering over the corner zone (for vertical-outer/horizontal-inner splits)
+- **Two-way resize**: Dragging the corner zone adjusts both the outer vertical split and the inner horizontal split simultaneously
+- **Position tracking**: The corner zone follows the resize handles as they move, staying at their intersection
+
+---
+
+## CSS Customisation
+
+### Handle Styling
+
+```css
+ixfx-split-layout {
+  --handle-size: 4px;
+  --handle-colour: var(--surface-4);
+  --handle-hover-colour: var(--surface-6);
+  --handle-active-colour: var(--accent);
+}
+```
+
+### Hide Collapsed Panels Completely
+
+```css
+ixfx-split-layout[data-collapsed-a] slot[name="a"] {
+  display: none;
+}
+```
+
+---
+
+## Programmatic Control
+
+### Setting Sizes
+
+```javascript
+const split = document.querySelector('ixfx-split-layout');
+
+// Set to 30% / 70%
+split.sizeA = '30%';
+split.sizeB = '70%';
+
+// Set to fixed pixel widths
+split.fixedA = true;
+split.sizeA = '200px'; // Panel A is 200px
+// Panel B automatically gets remaining space
+
+// Collapse a panel programmatically
+split.collapsedA = true;
+split.collapsedB = false;
+```
+
+### Reading State
+
+```javascript
+console.log('Panel A size:', split.sizeA);
+console.log('Panel B size:', split.sizeB);
+console.log('Is A collapsed?', split.collapsedA);
+console.log('Is B collapsed?', split.collapsedB);
+```
+
+---
+
+## Implementation Notes
+
+- Uses Shadow DOM for style encapsulation
+- Slots use `display: block` and `overflow: hidden` by default
+- When no size is specified for a panel, it defaults to `auto` (fill remaining space)
+- When both sizes are empty, both default to `50%`
+- The resize handle is `flex-shrink: 0` to prevent it from collapsing
+- Nested splits detect their parent through slot assignment and automatically enable corner resize