@ixfx/components 0.3.1 → 0.4.0

package/docs-user/button.md

@@ -0,0 +1,355 @@
+# Button components
+
+Three related button components:
+
+- **`ixfx-button`** — a styled, icon-capable replacement for `<button>`
+- **`ixfx-split-button`** — a button paired with a dropdown caret; supports a static popup menu, a switcher mode, and programmatic item control
+- **`ixfx-radio-group`** — a group of radio-style selectable items; also supports single toggle mode
+
+---
+
+## `ixfx-button`
+
+```html
+<ixfx-button>Save</ixfx-button>
+<ixfx-button icon="check">Commit</ixfx-button>
+<ixfx-button icon="check" hide-label>Commit</ixfx-button>
+<ixfx-button disabled>Unavailable</ixfx-button>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type    | Default | Description                                        |
+|---------------------|---------|---------|----------------------------------------------------|
+| `disabled`          | boolean | `false` | Disables the button                                |
+| `icon`              | string  | —       | Registered icon name **or** raw `<svg>` string     |
+| `hide-icon`         | boolean | `false` | Hides the icon even when `icon` is set             |
+| `hide-label`        | boolean | `false` | Hides the text label (useful for icon-only buttons)|
+
+### Slots
+
+| Slot    | Description              |
+|---------|--------------------------|
+| default | Button label text / HTML |
+
+### Events
+
+`ixfx-button` does not fire custom events. Listen for the standard `click` on the element.
+
+```js
+document.querySelector('ixfx-button').addEventListener('click', () => { ... });
+```
+
+### Icons
+
+Icon names resolve against the icon registry. Built-in names: `check`, `chevron-down`, `chevron-right`, `close`, `caret-right`. Register custom icons with `registerIcon(name, svgString)` from `src/icons/registry.ts`.
+
+You can also pass a raw SVG string directly to `icon`:
+
+```js
+btn.icon = '<svg viewBox="0 0 24 24" fill="currentColor"><path d="..."/></svg>';
+```
+
+### CSS custom properties
+
+| Property            | Default  | Description             |
+|---------------------|----------|-------------------------|
+| `--surface-3`       | `#ccc`   | Button background       |
+| `--surface-3-text`  | `#000`   | Button text / icon fill |
+| `--accent`          | `#666`   | Hover border colour     |
+| `--border`          | `1px solid #999` | Border         |
+| `--radius-xl`       | `8px`    | Border radius           |
+| `--space-m`         | `8px`    | Vertical padding        |
+| `--space-l`         | `12px`   | Horizontal padding      |
+| `--text-m`          | `14px`   | Font size               |
+| `--transition`      | `0.2s`   | Hover/active transition |
+| `--disabled-opacity`| `0.5`    | Opacity when disabled   |
+
+---
+
+## `ixfx-radio-group`
+
+A group of radio-style selectable items, useful for selecting one option from a list. Also supports a **single toggle mode** when no `<option>` children are provided.
+
+```html
+<ixfx-radio-group name="waveform" value="sine">
+  <option value="sine">Sine</option>
+  <option value="square">Square</option>
+  <option value="sawtooth">Saw</option>
+  <option value="triangle">Tri</option>
+</ixfx-radio-group>
+```
+
+### Single toggle mode
+
+When no `<option>` elements are provided and text content is present, the component renders as a toggle button:
+
+```html
+<ixfx-radio-group name="toggle" checked>Enable Feature</ixfx-radio-group>
+<ixfx-radio-group name="state" value="active" value-off="inactive" checked>Active/Inactive</ixfx-radio-group>
+<ixfx-radio-group name="confirm" icon-name="check" icon-name-off="close" checked>On/Off</ixfx-radio-group>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type                              | Default      | Description                                                    |
+|---------------------|-----------------------------------|--------------|----------------------------------------------------------------|
+| `value`             | string                            | `''`         | Currently selected value                                        |
+| `checked`           | boolean                           | `false`      | For toggle mode: whether it is checked                         |
+| `orientation`       | `'horizontal'` \| `'vertical'`    | `'horizontal'` | Layout direction                                             |
+| `mode`              | `'compact'` \| `'max'`            | `'compact'`  | `compact`: items size to fit content. `max`: items stretch to fill container |
+| `name`              | string                            | `''`         | Radio group name (used for native radio behavior)               |
+| `value-off`         | string                            | `''`         | Value when toggle is in off state                              |
+| `icon-name`         | string                            | `''`         | Icon name (from registry) shown when toggle is on / item selected |
+| `icon-name-off`     | string                            | `''`         | Icon name shown when toggle is off                             |
+| `hide-labels`       | boolean                           | `false`      | Hides item labels                                             |
+| `items`             | `RadioItem[]`                     | `[]`         | Programmatically set items (alternative to `<option>` children) |
+
+### Slots
+
+| Slot      | Description                                      |
+|-----------|--------------------------------------------------|
+| default   | Text content for toggle mode                     |
+| (children)| `<option>` elements defining radio items         |
+
+### Events
+
+| Event    | Detail                                      | Description                         |
+|----------|---------------------------------------------|-------------------------------------|
+| `change` | `{ checked: boolean, value: string \| undefined }` | Fired when selection changes |
+
+```js
+document.querySelector('ixfx-radio-group').addEventListener('change', e => {
+  console.log(e.detail.value);   // e.g. 'sine'
+  console.log(e.detail.checked);  // true
+});
+```
+
+### Programmatic control
+
+```js
+const group = document.querySelector('ixfx-radio-group');
+
+// Get/set selected value
+group.value = 'square';
+
+// For toggle mode
+group.checked = true;
+
+// Update items programmatically
+group.items = [
+  { value: 'alpha', label: 'Alpha' },
+  { value: 'beta', label: 'Beta', disabled: true },
+  { value: 'gamma', label: 'Gamma', iconName: 'check' },
+];
+```
+
+### CSS custom properties
+
+| Property               | Default                        | Description                              |
+|------------------------|--------------------------------|------------------------------------------|
+| `--surface-3`          | `transparent`                  | Background                               |
+| `--border`             | `none`                         | Border                                   |
+| `--radius-m`           | `4px`                          | Border radius                            |
+| `--item-spacing`       | `0`                            | Gap between items                        |
+| `--icon-label-spacing`  | `0.5rem`                       | Gap between icon and label               |
+| `--icon-size`          | `1.2rem`                       | Icon dimensions                          |
+| `--compact-padding`    | `0.5rem`                       | Padding in compact mode                  |
+| `--space-m`            | `0.5rem`                       | Vertical item padding                    |
+| `--space-l`            | `1rem`                         | Horizontal item padding                  |
+
+### TypeScript types
+
+```ts
+import type { RadioGroupChangeDetail, RadioItem, RadioGroupMode } from 'ixfxfun-components';
+```
+
+---
+
+## `ixfx-split-button`
+
+A button split into a **primary action area** (left) and a **caret** (right) that opens a popup menu. Extends `ixfx-button` so all button properties and CSS variables apply.
+
+```html
+<ixfx-split-button>
+  Save
+  <ixfx-menu-container slot="menu">
+    <ixfx-menu-item command="save-draft" label="Save as Draft"></ixfx-menu-item>
+    <ixfx-menu-item command="save-copy"  label="Save a Copy"></ixfx-menu-item>
+    <ixfx-menu-separator></ixfx-menu-separator>
+    <ixfx-menu-item command="export"     label="Export…"></ixfx-menu-item>
+  </ixfx-menu-container>
+</ixfx-split-button>
+```
+
+### Properties / attributes
+
+Inherits all `ixfx-button` properties, plus:
+
+| Attribute / Property | Type            | Default     | Description                                                     |
+|---------------------|-----------------|-------------|-----------------------------------------------------------------|
+| `mode`              | `'default'` \| `'switcher'` | `'default'` | See [Modes](#modes)                        |
+| `default-value`     | string          | `''`        | Command to pre-select in switcher mode                          |
+| `items`             | `PopupItem[]`   | —           | Directly set popup items (ignored when `itemsProvider` is set)  |
+| `itemsProvider`     | `() => PopupItem[] \| Promise<PopupItem[]>` | — | Called on each caret click; return value replaces all other item sources |
+| `registry`          | `CommandRegistry` | —         | Optional command registry forwarded to `ixfx-menu-trigger`      |
+| `keyboardManager`   | `KeyboardManager` | —         | Optional keyboard manager forwarded to `ixfx-menu-trigger`      |
+
+### Slots
+
+| Slot      | Description                                                                   |
+|-----------|-------------------------------------------------------------------------------|
+| default   | Primary button label                                                          |
+| `menu`    | `<ixfx-menu-container>` + items for the popup (default mode); or `<ixfx-menu-item>` elements as the data source in switcher mode |
+
+### Events
+
+| Event          | Detail                       | Description                                                                 |
+|----------------|------------------------------|-----------------------------------------------------------------------------|
+| `menu-command` | `{ command: string }`        | Fired when a menu item is selected, or when the primary button is clicked in switcher mode |
+
+```js
+element.addEventListener('menu-command', e => {
+  console.log(e.detail.command); // e.g. 'save-draft'
+});
+```
+
+The primary area does **not** fire `click` with a command — handle `menu-command` for both modes.
+
+---
+
+### Modes
+
+#### `default` mode (the default)
+
+Left side fires a plain `click`. Right caret opens the popup.
+
+```html
+<ixfx-split-button icon="check">
+  Commit
+  <ixfx-menu-container slot="menu">
+    <ixfx-menu-item command="commit-push"  label="Commit & Push"></ixfx-menu-item>
+    <ixfx-menu-item command="commit-only"  label="Commit Only"></ixfx-menu-item>
+    <ixfx-menu-item command="amend"        label="Amend Last Commit"></ixfx-menu-item>
+  </ixfx-menu-container>
+</ixfx-split-button>
+```
+
+#### `switcher` mode
+
+Selecting from the popup **replaces** the primary action and fires `menu-command` immediately. The replaced item returns to the popup. The caret shows a right-facing chevron to signal "this changes what the button does".
+
+```html
+<ixfx-split-button mode="switcher" default-value="save">
+  <ixfx-menu-item slot="menu" command="save"       label="Save"></ixfx-menu-item>
+  <ixfx-menu-item slot="menu" command="save-draft" label="Save as Draft"></ixfx-menu-item>
+  <ixfx-menu-item slot="menu" command="export"     label="Export…"></ixfx-menu-item>
+</ixfx-split-button>
+```
+
+Icons on switcher items flow through to the primary button:
+
+```html
+<ixfx-split-button mode="switcher" default-value="commit-push">
+  <ixfx-menu-item slot="menu" command="commit-push" label="Commit & Push" icon-name="check"></ixfx-menu-item>
+  <ixfx-menu-item slot="menu" command="commit-only" label="Commit Only"   icon-name="check"></ixfx-menu-item>
+  <ixfx-menu-item slot="menu" command="amend"       label="Amend"                          ></ixfx-menu-item>
+</ixfx-split-button>
+```
+
+---
+
+### Programmatic control
+
+All properties are writable at runtime. Changes trigger re-render automatically.
+
+#### Set popup items directly
+
+```js
+import type { PopupItem } from 'ixfxfun-components';
+
+const btn = document.querySelector('ixfx-split-button');
+
+btn.items = [
+  { command: 'staging', label: 'Deploy to Staging', icon: 'check' },
+  { command: 'prod',    label: 'Deploy to Production' },
+  { command: 'preview', label: 'Preview build' },
+];
+```
+
+`items` works in both `default` and `switcher` modes. In switcher mode the first item (or `default-value` if matched) becomes the active selection.
+
+#### Dynamic / async items via callback
+
+```js
+btn.itemsProvider = async () => {
+  const data = await fetch('/api/deploy-targets').then(r => r.json());
+  return data.map(t => ({ command: t.id, label: t.name }));
+};
+```
+
+The popup shows a "Loading…" placeholder while the promise resolves. `itemsProvider` takes priority over `items` and declarative slot content.
+
+#### Change mode at runtime
+
+```js
+btn.mode = 'switcher'; // or 'default'
+```
+
+When switching to `switcher` and `items` is set, items are re-applied for the new mode automatically.
+
+#### Select a command in switcher mode
+
+```js
+const found = btn.selectCommand('staging'); // returns false if command not in items
+```
+
+This changes the primary button label/icon immediately without opening the popup and without firing `menu-command`.
+
+#### Change label and icon
+
+```js
+btn.textContent = 'Publish';  // updates the default slot
+btn.icon = 'check';
+btn.hideLabel = true;
+btn.disabled = true;
+```
+
+---
+
+### Responsive behaviour
+
+When the primary area is too narrow to show its label, the component automatically collapses to icon + caret only. It restores the label as soon as space allows. No configuration needed — driven by a `ResizeObserver` comparing `scrollWidth` vs `offsetWidth`.
+
+To force icon-only at all times, set `hide-label`:
+
+```html
+<ixfx-split-button icon="check" hide-label>Commit</ixfx-split-button>
+```
+
+---
+
+### CSS parts
+
+| Part      | Element                   |
+|-----------|---------------------------|
+| `primary` | The left primary `<button>` |
+| `caret`   | The right caret `<button>`  |
+
+```css
+ixfx-split-button::part(primary) { font-weight: bold; }
+ixfx-split-button::part(caret)   { background: hotpink; }
+```
+
+---
+
+### TypeScript types
+
+```ts
+import type {
+  PopupItem,           // { command, label, icon?, disabled? }
+  SwitcherItem,        // { command, label, icon }
+  ItemsProvider,       // () => PopupItem[] | Promise<PopupItem[]>
+  SplitButtonMode,     // 'default' | 'switcher'
+} from 'ixfxfun-components';
+```

package/docs-user/checkbox.md

@@ -0,0 +1,62 @@
+# `ixfx-checkbox`
+
+A custom checkbox with a diagonal line indicator and indeterminate state support. Uses shadow DOM with CSS variables for full appearance customization.
+
+```html
+<ixfx-checkbox label="Accept terms"></ixfx-checkbox>
+<ixfx-checkbox checked label="Enabled"></ixfx-checkbox>
+<ixfx-checkbox disabled label="Disabled"></ixfx-checkbox>
+<ixfx-checkbox indeterminate label="Pending"></ixfx-checkbox>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type      | Default | Description                          |
+|----------------------|-----------|---------|--------------------------------------|
+| `checked`            | `boolean` | `false` | Checked state (diagonal line)        |
+| `indeterminate`      | `boolean` | `false` | Indeterminate state (horizontal bar) |
+| `disabled`           | `boolean` | `false` | Disabled state                       |
+| `label`              | `string`  | `''`    | Text label beside the box            |
+| `name`               | `string`  | `''`    | Form field name                      |
+| `value`              | `string`  | `''`    | Form field value                     |
+
+### Events
+
+| Event    | Detail                    | Description                  |
+|----------|---------------------------|------------------------------|
+| `change` | `{ checked: boolean }`    | Fired when checked state changes |
+
+```js
+document.querySelector('ixfx-checkbox').addEventListener('change', e => {
+  console.log(e.detail.checked);
+});
+```
+
+### CSS custom properties
+
+| Property                  | Default                           | Description                     |
+|---------------------------|-----------------------------------|---------------------------------|
+| `--box-size`              | `18px`                            | Box width/height                |
+| `--box-border-width`      | `2px`                             | Box border thickness            |
+| `--box-border-color`      | `var(--surface-4)`                | Box border color                |
+| `--box-bg-unchecked`      | `color-mix(...surface-3, surface-2)` | Background when unchecked     |
+| `--box-bg-checked`        | `color-mix(...surface-3, surface-2)` | Background when checked       |
+| `--check-line-color`      | `var(--accent)`                   | Diagonal / horizontal line color |
+| `--check-line-width`      | `6px`                             | Line thickness                  |
+| `--box-opacity-unchecked` | `0.5`                             | Opacity when unchecked          |
+| `--box-opacity-checked`   | `1`                               | Opacity when checked            |
+| `--box-opacity-hover`     | `var(--prominence-tickled-opacity)` | Opacity on hover             |
+| `--box-opacity-disabled`  | `var(--prominence-disabled-opacity)` | Opacity when disabled        |
+| `--label-gap`             | `var(--space-m)`                  | Gap between box and label       |
+| `--label-fg`              | `var(--surface-3-text)`           | Label text color                |
+| `--label-active`          | `var(--surface-2-text)`           | Label color when box clicked    |
+| `--label-hover`           | `var(--surface-2-text)`           | Label color on hover            |
+| `--label-opacity`         | `1`                               | Label opacity                   |
+| `--label-opacity-unchecked` | `1`                             | Label opacity when unchecked    |
+| `--transition-duration`   | `var(--transition)`               | Animation duration              |
+
+### TypeScript types
+
+```ts
+import type { CheckboxChangeDetail } from 'ixfxfun-components';
+```

package/docs-user/colour-picker.md

@@ -0,0 +1,237 @@
+# Colour Picker Components
+
+Two components for picking OKLCH colours. Use `ixfx-colour-picker` when you need a full inline picker; use `ixfx-colour-picker-popup` when you need a compact swatch that opens a picker in a popover.
+
+Both work in OKLCH colour space, which gives perceptually uniform gradients across all three channels.
+
+---
+
+## `<ixfx-colour-picker>`
+
+A full inline picker with gradient-rendered sliders for Hue, Lightness, and Chroma (and optionally Opacity). Includes a colour preview swatch. Layout adapts automatically — portrait (stacked), landscape (preview beside sliders), and a compact narrow-height mode.
+
+### Basic usage
+
+```html
+<ixfx-colour-picker></ixfx-colour-picker>
+
+<script>
+  const picker = document.querySelector('ixfx-colour-picker');
+  picker.addEventListener('input', e => {
+    console.log(e.detail); // { l, c, h, a }
+    console.log(picker.value); // "oklch(0.7 0.15 180)"
+  });
+</script>
+```
+
+### Attributes
+
+| Attribute        | Type    | Default | Description |
+|------------------|---------|---------|-------------|
+| `l`              | number  | `0.7`   | Lightness (0–1) |
+| `c`              | number  | `0.15`  | Chroma (0–0.4) |
+| `h`              | number  | `180`   | Hue (0–360) |
+| `a`              | number  | `1`     | Opacity (0–1). Only relevant when `show-a` is set. |
+| `value`          | string  | —       | Set initial colour from any CSS colour string (e.g. `"#ff0"`, `"hsl(120 50% 50%)"`) |
+| `hide-preview`   | boolean | `false` | Hide the colour preview swatch |
+| `hide-h`         | boolean | `false` | Hide the Hue slider |
+| `hide-l`         | boolean | `false` | Hide the Lightness slider |
+| `hide-c`         | boolean | `false` | Hide the Chroma slider |
+| `show-a`         | boolean | `false` | Show the Opacity slider |
+| `horizontal`     | boolean | `false` | Force horizontal layout (preview left, sliders right) |
+| `sliders-vertical` | boolean | `false` | Render sliders as side-by-side vertical bars |
+| `hide-tooltips`  | boolean | `false` | Suppress hover tooltips on slider labels |
+| `range-l`        | string  | `"0-1"` | Restrict Lightness slider range, e.g. `"0.2-0.9"` |
+| `range-c`        | string  | `"0-0.4"` | Restrict Chroma slider range |
+| `range-h`        | string  | `"0-360"` | Restrict Hue slider range |
+| `range-a`        | string  | `"0-1"` | Restrict Opacity slider range |
+
+### Properties
+
+All attributes above are also settable as JS properties (camelCase where applicable: `hidePreview`, `hideH`, `hideL`, `hideC`, `showA`, `horizontal`, `slidersVertical`, `hideTooltips`).
+
+Range setters accept a `[min, max]` tuple and can also be set via the attributes above:
+
+```js
+picker.rangeH = [0, 180];   // restrict hue to cool colours
+picker.rangeL = [0.2, 0.8]; // exclude near-black and near-white
+```
+
+### Getters
+
+| Getter  | Returns | Description |
+|---------|---------|-------------|
+| `value` | `string` | Current colour as a CSS `oklch()` string, e.g. `"oklch(0.7 0.15 180)"` |
+| `rangeL` | `[number, number]` | Active lightness range |
+| `rangeC` | `[number, number]` | Active chroma range |
+| `rangeH` | `[number, number]` | Active hue range |
+| `rangeA` | `[number, number]` | Active opacity range |
+
+### Methods
+
+#### `setColour(colour)`
+
+Set the colour programmatically from any ixfx-compatible colour format. Also updates the double-click reset target for all sliders.
+
+```js
+picker.setColour('hsl(200, 80%, 50%)');
+picker.setColour('#e74c3c');
+picker.setColour({ l: 0.6, c: 0.2, h: 260 }); // OKLCH object
+```
+
+Accepts any format that ixfx's `Colour.convert()` understands.
+
+### Events
+
+Both events carry `CustomEvent<{ l: number, c: number, h: number, a: number }>` and bubble + compose.
+
+| Event    | When |
+|----------|------|
+| `input`  | Every slider move (continuous, high frequency) |
+| `change` | When slider interaction ends (committed value) |
+
+```js
+picker.addEventListener('input', e => {
+  document.body.style.background = picker.value;
+});
+
+picker.addEventListener('change', e => {
+  saveColour(e.detail); // { l, c, h, a }
+});
+```
+
+### CSS custom properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--picker-alt-width` | `240px` | Component width |
+| `--picker-alt-height` | `240px` | Component height |
+| `--picker-alt-min-slider-height` | `2.5em` | Minimum height per slider |
+
+Standard theme variables (`--surface`, `--surface-ll`, `--radius-m`, `--space-s`, `--accent`) are used where available.
+
+### Layout behaviour
+
+The component uses CSS container queries on its own size, so you can size it freely:
+
+```css
+ixfx-colour-picker {
+  width: 100%;
+  height: 300px;
+}
+```
+
+- **Portrait / square**: preview swatch on top, sliders below (stacked column)
+- **Landscape** (aspect ratio > 1): preview swatch on left, sliders on right
+- **Short** (height < 150px): switches to landscape regardless of width
+- **`sliders-vertical`**: sliders become narrow side-by-side vertical bars (good for wide, short layouts)
+
+---
+
+## `<ixfx-colour-picker-popup>`
+
+A compact inline swatch button. Clicking it opens a full `ixfx-colour-picker` in a native popover anchored to the swatch. The picker is lazy — it is not added to the DOM until the swatch is clicked for the first time.
+
+### Basic usage
+
+```html
+<label>
+  Background colour
+  <ixfx-colour-picker-popup></ixfx-colour-picker-popup>
+</label>
+
+<script>
+  const popup = document.querySelector('ixfx-colour-picker-popup');
+  popup.addEventListener('change', e => {
+    document.body.style.background = popup.value;
+  });
+</script>
+```
+
+### Modes
+
+#### Fluid mode (default)
+
+Every slider move updates `l/c/h/a` on the popup and fires `input`. The swatch updates live. `change` fires when the slider interaction ends.
+
+#### Confirm mode
+
+Slider changes are held in a pending state. Nothing is committed until the user clicks the confirm (✓) button, which fires `change` and closes the popover. Dismissing the popover without confirming (light-dismiss / clicking outside) reverts the picker to the last committed values.
+
+```html
+<ixfx-colour-picker-popup mode="confirm"></ixfx-colour-picker-popup>
+```
+
+### Attributes
+
+| Attribute      | Type    | Default    | Description |
+|----------------|---------|------------|-------------|
+| `mode`         | string  | `"fluid"`  | `"fluid"` or `"confirm"` |
+| `l`            | number  | `0.7`      | Committed lightness (0–1) |
+| `c`            | number  | `0.15`     | Committed chroma (0–0.4) |
+| `h`            | number  | `180`      | Committed hue (0–360) |
+| `a`            | number  | `1`        | Committed opacity (0–1) |
+| `size`         | string  | `"medium"` | Popover picker size: `"small"` \| `"medium"` \| `"large"` \| `"huge"` |
+| `show-preview` | boolean | `false`    | Show the colour preview inside the picker (fluid mode hides it by default since the swatch already shows the live colour) |
+| `hide-h`       | boolean | `false`    | Hide the Hue slider inside the picker |
+| `hide-l`       | boolean | `false`    | Hide the Lightness slider inside the picker |
+| `hide-c`       | boolean | `false`    | Hide the Chroma slider inside the picker |
+| `show-a`       | boolean | `false`    | Show the Opacity slider inside the picker |
+| `horizontal`   | boolean | `false`    | Force horizontal layout inside the picker |
+
+Picker sizes (width × height):
+
+| `size`    | Dimensions |
+|-----------|------------|
+| `small`   | 130 × 100 px |
+| `medium`  | 100 × 155 px (default) |
+| `large`   | 200 × 180 px |
+| `huge`    | 290 × 240 px |
+
+### Getters
+
+| Getter  | Returns  | Description |
+|---------|----------|-------------|
+| `value` | `string` | Committed colour as a CSS `oklch()` string |
+
+### Methods
+
+#### `setColour(colour)`
+
+Set the committed colour from any ixfx-compatible format. The swatch updates immediately. The inner picker reflects the new colour the next time the popover opens.
+
+```js
+popup.setColour('#3498db');
+popup.setColour({ l: 0.5, c: 0.25, h: 30 });
+```
+
+### Events
+
+| Event    | Mode    | When |
+|----------|---------|------|
+| `input`  | fluid   | Every slider move |
+| `change` | fluid   | Slider interaction ends |
+| `change` | confirm | Confirm button clicked |
+
+Both carry `CustomEvent<{ l: number, c: number, h: number, a: number }>`, bubble, and compose.
+
+### CSS custom properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--cp-popup-swatch-size` | `1.5em` | Width and height of the swatch button |
+
+The popover panel uses standard theme variables for background, border, radius, and shadow (`--surface`, `--border`, `--radius-l`, `--shadow-l`, `--space-s`).
+
+---
+
+## Shared event detail type
+
+```ts
+type ColourPickerEventDetail = {
+  l: number; // Lightness 0–1
+  c: number; // Chroma 0–0.4
+  h: number; // Hue 0–360
+  a?: number; // Opacity 0–1 (defaults to 1)
+};
+```