@ixfx/components 0.4.4 → 0.5.0

package/docs-user/slider-input.md

@@ -0,0 +1,673 @@
+# ixfx-slider-input
+
+A linear SVG-based slider. Supports horizontal and vertical orientations, three value modes (single/dual/triple), three single-mode styles (range/bipolar/unipolar), triangle/needle/dot markers, and `value-drag` length-drag gestures for multi-handle modes.
+
+---
+
+## Basic Usage
+
+```html
+<ixfx-slider-input min="0" max="100" value-a="50"></ixfx-slider-input>
+```
+
+The component defaults to `200px` wide and `24px` tall (the horizontal cross axis). Set width and height via CSS:
+
+```html
+<ixfx-slider-input min="0" max="100" value-a="50" style="width: 320px;"></ixfx-slider-input>
+```
+
+Vertical orientation swaps the dimensions and rotates interaction to up/down:
+
+```html
+<ixfx-slider-input
+  orientation="vertical"
+  min="0" max="100" value-a="30"
+  style="width: 24px; height: 200px;"
+></ixfx-slider-input>
+```
+
+To fill a container, set both `width: 100%` and `height: 100%`:
+
+```html
+<div style="width: 100%; height: 24px;">
+  <ixfx-slider-input min="0" max="100" value-a="50" style="width: 100%; height: 100%;"></ixfx-slider-input>
+</div>
+```
+
+---
+
+## Attributes & Properties
+
+| Attribute / Property | Type | Default | Description |
+|---|---|---|---|
+| `value-a` | `number` | `50` | Primary handle value (single mode), or lower pole (dual/triple) |
+| `value-b` | `number` | `0` | Upper pole (dual/triple modes only) |
+| `value-c` | `number` | midpoint of A/B | Middle handle (triple mode only) |
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `undefined` | Keyboard/wheel/pointer step size. If unset, defaults to 10% of range |
+| `stops` | `number` | `undefined` | Quantise to N discrete positions. Also sets step size |
+| `value-mode` | `"single"` \| `"dual"` \| `"triple"` | `"single"` | Number of handles |
+| `single-style` | `"range"` \| `"bipolar"` \| `"unipolar"` | `"range"` | How the value bar is drawn (single mode only) |
+| `orientation` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Track orientation |
+| `marker-style` | `"needle"` \| `"dot"` \| `"triangle"` \| `"none"` | `"needle"` | Marker shape (applies to all handles) |
+| `marker-style-c` | as `marker-style` | `undefined` | Optional per-handle marker override for the C handle in triple mode |
+| `crossover` | `"none"` \| `"allow"` | `"allow"` | Whether handles can pass through each other (dual/triple) |
+| `value-drag` | `"none"` \| `"stop"` \| `"flex"` | `"none"` | Whether the segment between A and B is draggable (dual/triple) |
+| `value-min` | `number` | `1` | Minimum gap between A and B in value units (dual/triple) |
+| `value-c-follow` | `"none"` \| `"proportional"` | `"none"` | How C follows when A/B move the band (triple mode) |
+| `disabled` | `boolean` | `false` | Disables all interaction. Reflected as attribute |
+
+### Sizing
+
+Size via CSS `width`/`height`. The horizontal default is 200×24, vertical 24×200. Both can be overridden freely.
+
+```html
+<!-- Thin (16px tall) -->
+<ixfx-slider-input style="height: 16px;" min="0" max="100" value-a="60"></ixfx-slider-input>
+
+<!-- Large (32px tall) -->
+<ixfx-slider-input style="height: 32px;" min="0" max="100" value-a="60"></ixfx-slider-input>
+```
+
+### Disabled state
+
+```html
+<ixfx-slider-input disabled min="0" max="100" value-a="70"></ixfx-slider-input>
+```
+
+---
+
+## Interaction
+
+**Mouse / touch:** click or drag on the track. Clicking sets the value to that position; dragging continuously updates it. In dual/triple modes, clicking a handle drags it; clicking the segment between handles (when `value-drag` is enabled) drags the whole band. Full min-to-max range spans `2×` the component's rendered long-axis size.
+
+**Cursor feedback:**
+- `grab` over a marker handle (a/b/c)
+- `move` over a draggable segment (between A and B when `value-drag` is on)
+- `pointer` over empty track where clicking sets a value (single mode; or the dead zones outside A/B in multi mode)
+- `grabbing` while actively dragging
+- `default` over a no-op segment (dual mode with `value-drag="none"`, or between A-C/C-B in triple with `value-drag="none"`)
+- `not-allowed` on a `disabled` slider
+
+**Shift + drag:** fine control — sensitivity reduced to 1/10th (`KEY_STEP_DIVISOR = 10`).
+
+**Keyboard** (when focused):
+
+| Key | Action |
+|---|---|
+| `ArrowRight` / `ArrowUp` | Increase by step (single mode), or move last-interacted handle |
+| `ArrowLeft` / `ArrowDown` | Decrease by step (single mode), or move last-interacted handle |
+| `Home` | Set to `min` (or move handle to low in multi mode) |
+| `End` | Set to `max` (or move handle to high in multi mode) |
+| `Shift` + arrows | Fine step (÷10) |
+
+**Wheel** (when focused or `lighttouch` is on):
+
+Wheel forward increases the value, wheel backward decreases it (sign is platform-agnostic — both `deltaY` and `deltaX` are considered so Mac shift-scrolls are handled correctly). Shift narrows the step to 1/10th.
+
+Step size priority: `stops` > explicit `step` > 10% of range.
+
+---
+
+## Value Modes
+
+### `single` (default)
+
+One handle. The `value-a` property holds the current value.
+
+```html
+<ixfx-slider-input value-mode="single" min="0" max="100" value-a="60"></ixfx-slider-input>
+```
+
+### `dual`
+
+Two handles. The `value-a` / `value-b` properties hold the low/high poles, and the value bar is drawn between them. They are swapped automatically so that `valueMin = min(valueA, valueB)` and `valueMax = max(valueA, valueB)`.
+
+```html
+<ixfx-slider-input
+  value-mode="dual"
+  min="0" max="100"
+  value-a="20" value-b="80"
+></ixfx-slider-input>
+```
+
+The `crossover` attribute controls whether the handles can pass through each other:
+- `"allow"` (default) — handles can cross; the bar will flip and the high/low swap.
+- `"none"` — handles are pinned to their side and can't cross. `value-min` enforces a minimum gap.
+
+The `value-drag` attribute controls whether the segment between A and B is itself draggable:
+- `"none"` (default) — clicking the segment does nothing.
+- `"stop"` — dragging the segment translates it, but length stays fixed at the bounds.
+- `"flex"` — dragging the segment translates it, length shortens at the bounds.
+
+### `triple`
+
+Three handles. `value-a` / `value-b` are the outer poles, `value-c` is the middle handle. The `value-c-follow` attribute controls how C behaves when the A/B band changes:
+- `"none"` (default) — C keeps its value unless pushed outside the new band.
+- `"proportional"` — C is re-anchored at the same fractional position it had within the old band, so it moves with A/B.
+
+```html
+<ixfx-slider-input
+  value-mode="triple"
+  min="0" max="100"
+  value-a="20" value-b="80"
+></ixfx-slider-input>
+```
+
+A/B/C can be styled independently via `--marker-a-color`, `--marker-b-color`, `--marker-c-color`, and the C handle can take a different marker shape via `marker-style-c="dot"`.
+
+---
+
+## Single Styles
+
+The `single-style` attribute (single mode only) controls how the value bar is drawn.
+
+### `range` (default)
+
+The value bar grows from the start of the track to the value. Classic slider behaviour.
+
+```html
+<ixfx-slider-input single-style="range" min="0" max="100" value-a="60"></ixfx-slider-input>
+```
+
+### `bipolar`
+
+The value bar is centred on the midpoint of `min`…`max`. Values below the midpoint grow leftward, values above grow rightward. A small tick is drawn at the centre. Suited for pan, balance, or any centred parameter.
+
+```html
+<ixfx-slider-input single-style="bipolar" min="-1" max="1" value-a="0.5"></ixfx-slider-input>
+```
+
+### `unipolar`
+
+The value bar is symmetric around the centre, growing in both directions as the value increases. A marker is shown at *both* ends of the bar (low and high). A small tick is drawn at the centre. Click-to-set follows a V-shape: 0 at the centre, 1 at either end (clicking 25% in from the left or right sets value 0.5).
+
+```html
+<ixfx-slider-input single-style="unipolar" min="0" max="1" value-a="0.6"></ixfx-slider-input>
+```
+
+---
+
+## Stepping & Quantisation
+
+`step` controls keyboard, wheel, and pointer step size:
+
+```html
+<ixfx-slider-input min="0" max="1" value-a="0.5" step="0.2"></ixfx-slider-input>
+```
+
+`stops` quantises the value to N equally-spaced positions. Drag, click, keyboard, and wheel input all snap:
+
+```html
+<!-- 5 discrete stops: 0, 0.2, 0.4, 0.6, 0.8, 1.0 -->
+<ixfx-slider-input min="0" max="1" value-a="0.5" stops="5"></ixfx-slider-input>
+
+<!-- 10 stops across 0-100: snaps to 0, 10, 20 … 100 -->
+<ixfx-slider-input min="0" max="100" value-a="50" stops="10"></ixfx-slider-input>
+```
+
+When `stops` is set it also governs the keyboard and wheel step (one stop per keypress).
+
+---
+
+## Events
+
+Both events bubble and are `composed` (cross shadow-DOM boundaries).
+
+### `input`
+
+Fired continuously during user interaction (every pointer/key event that changes the value). Use for live updates.
+
+```ts
+import type { SliderInputInputEvent } from 'ixfx-slider-input/types';
+
+slider.addEventListener('input', (e: SliderInputInputEvent) => {
+  const d = e.detail;
+  // d.value: number in min..max (single mode), or = valueMax in multi modes
+  // d.valueRelative: number 0..1
+  // d.valueMin, d.valueMax, d.valueMinRelative, d.valueMaxRelative: dual/triple
+  // d.valueC, d.valueCRelative: triple only
+  // d.changed: 'min' | 'max' | 'c' | 'both' (which pole(s) moved)
+});
+```
+
+### `change`
+
+Fired after the user finishes interacting (debounced 150 ms). Equivalent to the native `<input type="range">` change semantics. Also fires immediately for programmatic value changes.
+
+```ts
+import type { SliderInputChangeEvent } from 'ixfx-slider-input/types';
+
+slider.addEventListener('change', (e: SliderInputChangeEvent) => {
+  const d = e.detail;
+  // Same shape as `input` plus previousValue / previousValueMin / etc.
+});
+```
+
+**Note:** `input` fires only for user-initiated changes. Programmatic `slider.valueA = x` triggers only `change`.
+
+---
+
+## CSS Custom Properties
+
+### Track
+
+| Variable | Default | Description |
+|---|---|---|
+| `--track-color` | `var(--surface-4)` | Stroke colour of the central track rect |
+| `--track-width` | `2` | Stroke width of the track (SVG units) |
+| `--track-fill` | `transparent` | Fill colour of the track rect |
+
+```html
+<ixfx-slider-input
+  min="0" max="100" value-a="60"
+  style="--track-width: 6; --track-color: hsl(280, 30%, 30%);"
+></ixfx-slider-input>
+```
+
+### Lanes
+
+Lanes are line segments drawn over the track. The built-in lanes are `track` (the grey background) and `value` (the accent-coloured progress bar). Custom lanes can be added at runtime (see [Data Lanes](#data-lanes-programmatic-api)).
+
+| Variable | Default | Description |
+|---|---|---|
+| `--lane-track-color` | `var(--surface-4)` | Colour of the `track` lane |
+| `--lane-value-color` | `var(--accent)` | Colour of the `value` lane |
+| `--lane-color` | `var(--accent)` | Fallback colour for custom lanes |
+| `--lane-<key>-color` | — | Per-lane colour override (e.g. `--lane-sweep-color`) |
+| `--lane-<key>-width` | — | Per-lane width override (e.g. `--lane-sweep-width`) |
+| `--lane-dasharray` | `none` | SVG `stroke-dasharray` applied to all lanes |
+| `--lane-dashoffset` | `0` | SVG `stroke-dashoffset` — animate for marching-ants effect |
+
+Dashed lanes:
+
+```html
+<!-- 8px dashes, 4px gaps -->
+<ixfx-slider-input style="--lane-dasharray: 8 4;" min="0" max="100" value-a="60"></ixfx-slider-input>
+
+<!-- Dotted -->
+<ixfx-slider-input style="--lane-dasharray: 2 4;" min="0" max="100" value-a="60"></ixfx-slider-input>
+```
+
+### Track + lanes styled together (independent of host dimensions)
+
+```html
+<ixfx-slider-input
+  min="0" max="100" value-a="60"
+  style="--track-width: 6; --lane-track-width: 0.4; --lane-value-width: 0.4;"
+></ixfx-slider-input>
+```
+
+### Marker (value indicator)
+
+| Variable | Default | Description |
+|---|---|---|
+| `--marker-color` | `var(--accent)` | Colour of the needle line, dot fill, or triangle fill |
+| `--marker-thickness` | `0.12` | Relative thickness (fraction of cross axis) |
+| `--marker-length` | `0.8` | Needle length as fraction of cross axis (needle) |
+| `--marker-offset` | `0` | Perpendicular offset from track centreline (needle/dot/triangle) |
+| `--marker-border-width` | `0` | Border halo thickness around marker |
+| `--marker-border-color` | `transparent` | Border halo colour |
+| `--marker-dasharray` | `none` | Dashed needle pattern |
+| `--marker-dashoffset` | `0` | Dashed needle offset |
+
+Per-handle overrides in dual/triple modes follow the same convention: `--marker-a-color`, `--marker-b-color`, `--marker-c-color`.
+
+### Midpoint marker (bipolar / unipolar modes only)
+
+| Variable | Default | Description |
+|---|---|---|
+| `--midpoint-color` | `var(--surface-muted-text)` | Colour of the centre tick / dot |
+| `--midpoint-thickness` | `1px` (needle) / `0.08` (dot) | Tick line width or dot radius fraction |
+| `--midpoint-length` | `0.15` | Tick length as fraction of cross axis (needle) |
+| `--midpoint-border-color` | `transparent` | Dot border colour (dot only) |
+| `--midpoint-border-width` | `0` | Dot border width (dot only) |
+
+### Dynamic value variables
+
+The component sets `--value-relative` (a number 0…1) on the host as the value changes. In dual/triple modes it also sets `--value-min-relative`, `--value-max-relative`, and `--value-c-relative`. Use them inside `calc()` to create value-reactive styles entirely in CSS:
+
+```html
+<!-- Value bar hue shifts from purple to pink as value increases -->
+<ixfx-slider-input
+  min="0" max="100" value-a="60"
+  style="--lane-value-color: hsl(calc(var(--value-relative) * 280), 80%, 55%);"
+></ixfx-slider-input>
+
+<!-- Marker hue follows value -->
+<ixfx-slider-input
+  min="0" max="100" value-a="60"
+  style="--marker-color: hsl(calc(var(--value-relative) * 280), 80%, 55%);"
+></ixfx-slider-input>
+
+<!-- Marker thickness scales with value -->
+<ixfx-slider-input
+  min="0" max="100" value-a="60"
+  style="--marker-thickness: calc(0.08 + var(--value-relative) * 0.25);"
+></ixfx-slider-input>
+```
+
+### Focus outline
+
+| Variable | Default | Description |
+|---|---|---|
+| `--slider-input-svg-focus-outline` | `2px solid var(--accent)` | Outline colour and style applied to the SVG when focused via keyboard |
+| `--slider-input-svg-focus-outline-offset` | `2px` | Outline offset |
+
+---
+
+## Marker Styles
+
+### `needle` (default)
+
+A line drawn perpendicular to the track. Spans `--marker-offset` (offset from centreline) to `--marker-length` (length, both as fractions of cross axis).
+
+```html
+<ixfx-slider-input marker-style="needle" min="0" max="100" value-a="60"></ixfx-slider-input>
+```
+
+Thin minimalist look:
+
+```html
+<ixfx-slider-input
+  marker-style="needle" min="0" max="100" value-a="60"
+  style="--marker-thickness: 0.05; --marker-color: var(--surface-muted-text); --marker-length: 0.9; --marker-offset: 0.5;"
+></ixfx-slider-input>
+```
+
+With a border halo (useful for contrast against coloured lanes):
+
+```html
+<ixfx-slider-input
+  marker-style="needle" min="0" max="100" value-a="60"
+  style="--marker-thickness: 0.1; --marker-border-width: 0.02; --marker-border-color: white;"
+></ixfx-slider-input>
+```
+
+### `dot`
+
+A filled circle placed at the value's track position. `--marker-offset` shifts it perpendicular to the track (0 = on the centreline, positive = away from the centreline in the track's perpendicular direction).
+
+```html
+<!-- Dot on the track -->
+<ixfx-slider-input marker-style="dot" min="0" max="100" value-a="60"></ixfx-slider-input>
+
+<!-- Dot offset above the track -->
+<ixfx-slider-input
+  marker-style="dot" min="0" max="100" value-a="60"
+  style="--marker-offset: 0.5; --marker-thickness: 0.15;"
+></ixfx-slider-input>
+```
+
+### `triangle`
+
+A downward-pointing triangle. The apex sits on the value-track centreline at the value's track position; the base is offset *outward* by `--marker-length` (away from the centreline), so the shape hangs outside the value bar with its point facing in. Useful as a "data is here" indicator on a stacked-lane layout.
+
+```html
+<ixfx-slider-input
+  marker-style="triangle" min="0" max="100" value-a="60"
+  style="--marker-offset: 0.7; --marker-thickness: 0.3;"
+></ixfx-slider-input>
+```
+
+### `none`
+
+No marker rendered. Use when the value bar or lanes carry the visual.
+
+```html
+<ixfx-slider-input marker-style="none" min="0" max="100" value-a="60"></ixfx-slider-input>
+```
+
+---
+
+## Data Lanes (programmatic API)
+
+Lanes are additional line segments drawn over (or offset from) the track. The two built-in lanes are `track` (grey background) and `value` (accent progress bar). You can add custom lanes at runtime.
+
+### Lane types
+
+| Type | Behaviour |
+|---|---|
+| `value` | Draws from `lane.valueMin` to `lane.valueMax` along the track. Update with `setLaneRange()` for ranges or `setLaneValue()` for a single position (single mode) |
+| `fixed` | Always shows the full track — useful for static reference lines |
+| `anchored` | Centred on the current value, with `lane.value` controlling its half-width (0..1 of total track) |
+
+### API
+
+```ts
+import type { SliderInputElement } from 'ixfx-slider-input';
+
+const slider = document.querySelector('ixfx-slider-input') as SliderInputElement;
+
+await customElements.whenDefined('ixfx-slider-input');
+await slider.updateComplete;
+
+// Add a fixed reference line above the track
+slider.addLane('target', {
+  type: 'fixed',
+  offset: 0.2,   // 20% above the track centreline
+  width: 0.05,   // thin line
+});
+
+// Add a value-type lane (will default to current value span)
+slider.addLane('average', {
+  type: 'value',
+  value: 0.4,    // initial 0..1 position
+});
+
+// Add an anchored tolerance band centred on the current value
+slider.addLane('tolerance', {
+  type: 'anchored',
+  value: 0.15,   // band spans ±15% of total track
+});
+
+// Update a value-type lane
+slider.setLaneValue('average', 0.6);
+
+// Update a value-type lane's range (dual/triple band)
+slider.setLaneRange('average', 0.2, 0.8);
+
+// Remove a lane
+slider.removeLane('target');
+
+// Read lane state
+const lane = slider.getLane('average');
+const allLanes = slider.getLanes(); // ReadonlyMap<string, LaneData>
+```
+
+Style lanes via CSS variables using the lane key:
+
+```css
+ixfx-slider-input {
+  --lane-average-color: hsl(120, 70%, 50%);
+  --lane-tolerance-color: hsl(180, 80%, 50%);
+  --lane-sweep-width: 0.06;
+}
+```
+
+### Live lane animation example
+
+From the demo — a sweep lane that oscillates between 0 and the current slider value:
+
+```ts
+let direction = 1;
+setInterval(() => {
+  const sweep = slider.getLane('sweep');
+  if (!sweep) return;
+  const lo = sweep.valueMin ?? 0;
+  let nextLo = lo + direction * 0.02;
+  if (nextLo >= 0.7 || nextLo <= 0.05) {
+    direction *= -1;
+    nextLo = Math.max(0.05, Math.min(0.7, nextLo));
+  }
+  slider.setLaneRange('sweep', nextLo, nextLo + 0.3);
+}, 100);
+```
+
+The lane's `offset` value (in `addLane({ offset })`) positions it perpendicular to the track. Positive values push the lane *away* from the centreline (above for horizontal, right of for vertical).
+
+---
+
+## Tooltip Integration
+
+Set `data-tooltip` and `data-tooltip-live` to wire up a live tooltip that updates as the user drags:
+
+```html
+<ixfx-slider-input
+  min="0" max="100" value-a="50"
+  data-tooltip="50%"
+  data-tooltip-anchor="top"
+  data-tooltip-live="input"
+></ixfx-slider-input>
+```
+
+When `data-tooltip-live` is present the component automatically updates `data-tooltip` to the current percentage (e.g. `"63%"`) on every `input` event. In dual/triple modes the tooltip reflects the value at the max pole (parity with native `<input type="range">`).
+
+---
+
+## CSS Parts
+
+Lane paths and marker groups are exposed as CSS shadow parts for styling from outside the shadow DOM:
+
+```css
+ixfx-slider-input::part(lane) { … }                 /* all lanes */
+ixfx-slider-input::part(lane-track) { … }           /* track lane */
+ixfx-slider-input::part(lane-value) { … }           /* value lane */
+ixfx-slider-input::part(lane-sweep) { … }           /* a custom lane */
+ixfx-slider-input::part(value-marker) { … }         /* all handles' marker group */
+ixfx-slider-input::part(value-marker-a) { … }       /* dual/triple: A handle */
+ixfx-slider-input::part(value-marker-b) { … }       /* dual/triple: B handle */
+ixfx-slider-input::part(value-marker-c) { … }       /* triple: C handle */
+ixfx-slider-input::part(midpoint-marker) { … }      /* bipolar/unipolar centre tick */
+```
+
+---
+
+## Vertical Orientation
+
+Set `orientation="vertical"`. The component swaps width and height (24×200 default) and inverts the click-to-set / drag direction so the **top of the track = high value** and the **bottom = low value**. The host's CSS dimensions need to match the new layout (typically swap width ↔ height and tweak one to match the visual thickness you want):
+
+```html
+<ixfx-slider-input
+  orientation="vertical" min="0" max="100" value-a="50"
+  style="width: 24px; height: 200px;"
+></ixfx-slider-input>
+```
+
+The track, value bar, and markers all use the same `CROSS` axis for their perpendicular dimension, so all CSS variables (e.g. `--marker-thickness`, `--lane-track-width`) work identically in both orientations.
+
+---
+
+## Styling Recipes
+
+### Purple theme
+
+```css
+#my-slider {
+  --lane-value-color: hsl(280, 100%, 60%);
+  --lane-track-color: hsl(280, 30%, 30%);
+  --marker-color: hsl(280, 100%, 70%);
+  --marker-thickness: 0.3;
+}
+```
+
+### Animated marching-ants track
+
+```css
+@keyframes march {
+  to { --lane-dashoffset: -30; }
+}
+#my-slider {
+  --lane-dasharray: 20 10;
+  animation: march 1s linear infinite;
+}
+```
+
+### Value-reactive hue (single mode)
+
+```html
+<ixfx-slider-input
+  min="0" max="100" value-a="60"
+  style="--marker-color: hsl(calc((1 - var(--value-relative)) * 280), 80%, 55%);"
+></ixfx-slider-input>
+```
+
+### SVG gradient on the value bar
+
+Define gradients in a hidden `<svg>` at the top of the page using `gradientUnits="userSpaceOnUse"` anchored to the slider's viewBox, then reference them via `--lane-value-color`:
+
+```html
+<svg width="0" height="0" style="position:absolute" aria-hidden="true">
+  <defs>
+    <linearGradient id="slider-grad-h" gradientUnits="userSpaceOnUse" x1="5" y1="0" x2="95" y2="0">
+      <stop offset="0%" stop-color="oklch(70% 0.22 25)" />
+      <stop offset="100%" stop-color="oklch(75% 0.22 145)" />
+    </linearGradient>
+  </defs>
+</svg>
+<ixfx-slider-input
+  min="0" max="100" value-a="60"
+  style="--lane-value-color: url(#slider-grad-h);"
+></ixfx-slider-input>
+```
+
+---
+
+## Implementation Notes
+
+These are lessons learned from building the component — useful context when building a similar thing from scratch.
+
+### SVG in a fixed `100×24` viewBox
+
+All geometry is computed in a fixed `100×24` viewBox coordinate space for horizontal, or `24×100` for vertical, with the track running along the long axis. The `CROSS = 24` constant sets the perpendicular dimension, and `LONG = 100` sets the long axis. The SVG `viewBox` attribute handles scaling to actual DOM pixels, so every calculation stays coordinate-system-agnostic. The path is always `(viewBox-relative) × (host size / viewBox size)` regardless of the host's rendered size.
+
+### Lane offset needs a CSS unit
+
+`transform: translateY(${offset})` (unitless) is **invalid** CSS — a `<length>` is required, otherwise the whole `transform` declaration is dropped and the lane renders on the centreline. The code uses `translateY(${offset * CROSS / 2}px)` so the offset is expressed in viewBox units (with `px` suffix for CSS), making the offset stable across host sizes.
+
+### Marker rendering uses `part` + per-handle CSS variable patterns
+
+Each marker group has `part="value-marker"` (or `value-marker-<handle>` in multi modes) and reads its colour from a `var(--marker-<handle>-color, var(--marker-color, var(--accent)))` chain. The two-tier fallback means `--marker-color` styles all markers globally, while `--marker-a-color` / `--marker-b-color` / `--marker-c-color` can override per handle. The same pattern is used for the marker-style override (`--marker-style-c`) and for lane widths (`--lane-<key>-width`).
+
+The `<defs>` + `<use>` pattern with `markerBorderWidth > 0` produces a halo: the shape is pushed into a single root `<defs>` (so it's not rendered twice) and referenced twice via `<use>` — once as `class="marker-border"` (slightly thicker stroke) and once as `class="marker-fill"` (the actual colour). The same approach handles both needle (`<path>`) and dot/triangle (`<circle>` / `<polygon>`) shapes.
+
+### `#quantise` runs at the set-value boundary
+
+`#quantise(value)` is the single internal entry point for snapping: it applies `stops` first (priority), then `step` (if `stops` not set), and returns the raw value otherwise. Because every value-setting path (`#setSingleValueFromRelative`, `#setDualOrTripleValueFromRelative`, `#stepHandleByRelativeDelta`, `#applyLengthDragFromRelative`) funnels through it, snapping is universal — drag, click, keyboard, wheel, and length-drag all quantise identically.
+
+### WillUpdate initialises the value lane before the first render
+
+In multi-handle modes, the internal `#poleA` / `#poleB` / `#poleC` must be in sync before the first paint. This is done in `willUpdate()` (not the constructor) because `@property` values set from HTML attributes are not yet parsed at construction time. The triple-mode `valueC` defaults to the midpoint of A and B, matching `radial-input`'s deferred lane-correction pattern.
+
+### `value-c-follow="proportional"` keeps C anchored to the band
+
+When A or B moves, the C handle's fractional position within the *old* band is recomputed against the *new* band, so C tracks the band automatically across continuous drags. Because `#resolvePoleChange` and `#applyLengthDragFromRelative` both use the same `oldLo/oldHi → newLo/newHi` formula, the behaviour is consistent across pointer-drag, keyboard nudges, wheel, and length-drag.
+
+### Length-drag preserves the grab offset
+
+The bar between A and B in dual/triple modes is draggable when `value-drag !== "none"`. `#applyLengthDragFromRelative` computes the delta against `#lengthDragStartRelative` (the host-relative position at `pointerdown`), not against the low edge. Without this, the low edge would jump under the cursor on grab. The same `#lengthDragStartRelative` is captured in `#onPointerDown` when `chosenHandle === 'length'`.
+
+### Dead-zone clicks are no-ops when `value-drag` is enabled
+
+In `#onPointerDown`'s multi-handle hit-testing, the "click outside the band jumps the nearest handle" branches are gated on `valueDrag === "none"`. When `value-drag` is on, the only interactions that change values are grabbing a handle directly or grabbing the bar itself. This makes the click target clear: outside the band does nothing.
+
+### Midpoint marker only renders in bipolar / unipolar single mode
+
+`#renderMidpointMarker()` is a no-op unless `valueMode === "single"` and `singleStyle` is `"bipolar"` or `"unipolar"`. In those modes a small tick is drawn at the track centre to anchor the symmetric value bar.
+
+### Unipolar shows two markers (low + high end)
+
+For unipolar single mode, `#renderValueMarker` computes a `lowCenter` reflection of the high end across `bounds.centre` and emits a second marker shape at that position. The low-end marker uses the same `--marker-color` / `--marker-thickness` / `--marker-length` as the high end, so the existing CSS customisation patterns work unchanged.
+
+### Unipolar click-to-set uses a V-shape mapping
+
+`#onPointerDown` and `#onPointerMove` remap the host-relative click position to the value via `Math.abs(2 * relativeValue - 1)` when in unipolar single mode: 0 at the centre, 1 at either end. So clicking 25% in from the left or right sets value 0.5, and clicking at the centre sets value 0. The mapping is *not* applied to cursor hit-testing (the cursor logic uses the raw host-relative position so it can find the low/high markers at `0.5 ± value/2`).
+
+### `disconnectedCallback` cleans up timers and global listeners
+
+The debounce timer and the `pointermove` / `pointerup` / `pointercancel` window listeners are both cleaned up in `disconnectedCallback`. The pointer cleanup is achieved by calling `#onPointerUp()` directly, which resets `#dragging`, releases pointer capture, and removes the window listeners. Forgetting this causes a memory leak and a stuck-dragging bug if an element is removed mid-drag.
+
+### Wheel handling is platform-agnostic
+
+The `WheelNudgeMixin` consults `event.deltaY` first, falling back to `event.deltaX` when `deltaY` is 0. This matters on Mac, where shift+scroll is interpreted as horizontal scrolling and the browser sends `deltaX` with `deltaY=0`; without the fallback, shift+wheel on Mac would always read direction as `-1` (because `0 < 0` is false). The slider's `_applyWheelDelta` then inverts the sign so that "wheel forward = value up" works on both Windows and Mac.