@ixfx/components 0.3.1 → 0.4.0

package/docs-user/user-catalog.md

@@ -0,0 +1,165 @@
+# Component Catalog
+
+This guide provides an overview of the ixfx component library, organized by common use cases to help you find the right building blocks for your application.
+
+## Buttons and Controls
+
+### ixfx-button
+A styled button component with support for icons, loading states, and flexible layout. Use it as a direct replacement for standard HTML buttons when you need consistent theming and enhanced visual feedback.
+
+### ixfx-split-button
+A button that combines a primary action with a dropdown menu. Ideal for actions that have a default behavior plus additional variants (like "Save" with a menu for "Save As", "Save All", etc.).
+
+### ixfx-radio-group
+A group of mutually exclusive options that can render as traditional radio buttons or as a toggle switch when used without explicit options. Great for settings panels or form selections where only one choice is allowed.
+
+### ixfx-checkbox
+A brutalist-style checkbox with diagonal check mark indicator and indeterminate state support. Perfect for terms acceptance, feature toggles, or any binary selection.
+
+### ixfx-toggle-switch
+A compact on/off switch that provides a clear visual indication of state. Use for settings that have two distinct values like enabled/disabled or show/hide.
+
+## Input Components
+
+### ixfx-labelled-range-input
+Combines a range slider with a label and optional input field for precise value entry. Use when users need to select from a continuous range of values with both coarse and fine control.
+
+### ixfx-labelled-radial-input
+A circular input control for selecting values in a rotational manner. Ideal for color pickers, angle selectors, or any cyclical value selection.
+
+### ixfx-ac-text
+An autocomplete text input that suggests options as the user type. Perfect for search boxes, tag entry, or any field where you want to assist users with predefined options.
+
+### ixfx-narrowed-text
+A specialized text input that constrains input length and provides visual feedback about remaining capacity. Use for fields with strict character limits like tweet composition or SMS messages.
+
+### ixfx-editable-label
+A label that becomes an inline editor when clicked or focused. Useful for in-place editing of list items, card titles, or any display text that users might need to modify.
+
+### ixfx-color-picker
+A comprehensive color selection tool with multiple modes (hue/saturation/lightness, red/green/blue, etc.) and support for saving custom colors. Use whenever users need to select or adjust colors.
+
+## Display Components
+
+### ixfx-panel
+A container component with consistent theming, elevation, and padding. Use as a building block for cards, dialogs, sidebar sections, or any content grouping that needs visual separation.
+
+### ixfx-panel-group
+A collection of panels that can be expanded or collapsed, similar to an accordion. Perfect for settings pages, FAQ sections, or any content that benefits from progressive disclosure.
+
+### ixfx-tabs
+A tabbed interface for organizing content into separate views. Use when you have related content that users need to switch between frequently.
+
+### ixfx-tab-panel
+Individual panels that work with the ixfx-tabs component to create tabbed interfaces.
+
+### ixfx-data-display
+A flexible component for presenting various types of data with consistent formatting. Use for showing metrics, status information, or any structured data that benefits from standardized presentation.
+
+## Navigation Components
+
+### ixfx-menu
+A contextual popup menu that can be attached to buttons or other elements. Use for context menus, action menus, or any list of commands that should appear on demand.
+
+### ixfx-menu-bar
+A horizontal menu bar typically placed at the top of an application or window. Ideal for main application navigation with dropdown menus.
+
+### ixfx-menu-item
+Individual items that populate menus, supporting icons, shortcuts, and various states (disabled, checked, etc.).
+
+### ixfx-breadcrumb-navigation
+A component that shows the hierarchical path to the current location. Use in file browsers, documentation sites, or any application with nested content structures.
+
+### ixfx-tree
+A hierarchical tree view component for displaying nested data structures. Perfect for file explorers, organizational charts, or any data with parent-child relationships.
+
+### ixfx-crumb-navigation
+Similar to breadcrumb navigation but with a more compact representation focused on the immediate path context.
+
+## Layout Components
+
+### ixfx-split-layout
+A resizable split pane that allows users to adjust the proportion between two adjacent sections. Use for editor layouts, file explorers with previews, or any interface where users need to control space allocation.
+
+### ixfx-snap-container
+A container that snaps child elements to specific positions or alignments. Useful for creating custom layouts, dashboards, or any interface where precise element positioning is needed.
+
+### ixfx-polar-pad
+A circular input device for selecting points in polar coordinates (angle and radius). Ideal for color pickers, directional controls, or any circular input scenario.
+
+## Visualization Components
+
+### ixfx-xy-pad
+A two-dimensional pad for selecting X and Y coordinate values simultaneously. Commonly used for color selection (saturation/brightness), audio filtering, or any 2D parameter space.
+
+### ixfx-single-axis
+A component for displaying data along a single axis with appropriate scaling and labeling. Use for simple charts, waveform displays, or any linear data visualization.
+
+### ixfx-xy-axis
+A pair of orthogonal axes that work together to create a coordinate system for plotting data. Essential building block for custom charts and graphs.
+
+### ixfx-colour-map
+A visualization component that displays data as a color gradient or heatmap. Use for showing intensity distributions, correlation matrices, or any 2D data where color represents value.
+
+### ixfx-timeline
+A horizontal timeline for displaying events or data points over time. Perfect for audio/video editing, historical data presentation, or any chronological data visualization.
+
+### ixfx-range
+A component for representing and manipulating numerical ranges with visual handles. Use for date/time ranges, value selectors, or any scenario where users need to define a minimum and maximum.
+
+### ixfx-range-multi
+An extension of the range component that allows multiple non-overlapping ranges to be selected simultaneously. Ideal for selecting multiple time segments or value ranges.
+
+## Utility Components
+
+### ixfx-icon
+A flexible icon component that supports both built-in icons and custom SVG content. Use for visual enhancement of buttons, menu items, or any interface element that benefits from symbolic representation.
+
+### ixfx-tooltip
+A small popup that appears on hover or focus to provide additional information about an element. Use for explaining icon buttons, providing context for form fields, or any situation where brief supplemental help is needed.
+
+### ixfx-led
+A simple indicator light component that can show on/off states or various colors. Use for status indicators, power lights, or any binary state visualization.
+
+### ixfx-horizontal-selector
+A compact horizontal control for selecting from a set of options. Use when you need a more space-efficient alternative to radio groups or dropdowns.
+
+## Component Selection Guidelines
+
+When choosing components for your application, consider these patterns:
+
+### For Forms and Settings
+- Use `ixfx-checkbox` for binary options
+- Use `ixfx-radio-group` for mutually exclusive choices
+- Use `ixfx-labelled-range-input` for numerical parameters
+- Use `ixfx-toggle-switch` for settings with clear on/off states
+- Use `ixfx-panel` or `ixfx-panel-group` to organize related settings
+
+### For Data Display
+- Use `ixfx-data-display` for consistent metric presentation
+- Use `ixfx-panel` as containers for grouped information
+- Use `ixfx-tabs` to separate different views of related data
+- Use visualization components (`ixfx-xy-pad`, `ixfx-single-axis`, etc.) for graphical data representation
+
+### For Navigation and Selection
+- Use `ixfx-menu` for contextual actions
+- Use `ixfx-menu-bar` for primary application navigation
+- Use `ixfx-tree` for hierarchical data exploration
+- Use `ixfx-breadcrumb-navigation` to show location in hierarchies
+- Use `ixfx-ac-text` for assisted text entry with predefined options
+
+### For Layout and Structure
+- Use `ixfx-split-layout` for adjustable panes
+- Use `ixfx-panel` as basic building blocks
+- Use `ixfx-snap-container` for custom positioning needs
+- Use `ixfx-tabs` to organize content into separate views
+
+### For Interactive Controls
+- Use `ixfx-xy-pad` for 2D parameter control
+- Use `ixfx-labelled-radial-input` for circular parameters
+- Use `ixfx-range` or `ixfx-range-multi` for value ranges
+- Use `ixfx-color-picker` for comprehensive color selection
+
+This catalog represents the core components available in the ixfx library. Each component is designed to work together through a shared theming system and consistent interaction patterns, allowing you to build cohesive interfaces with minimal effort.
+
+For detailed usage instructions on any specific component, refer to the individual component documentation in the src/ directory or the corresponding user guide documents in @docs-user/.

package/docs-user/user-theming.md

@@ -0,0 +1,379 @@
+# User Theming Guide
+
+This document explains how users of the ixfx components can customize the appearance of components through CSS variables and theme overrides.
+
+## Overview
+
+The ixfx component library uses a CSS variable-based theming system that allows easy customization of colors, spacing, typography, and other visual properties. Rather than hardcoding values, components reference semantic CSS variables that can be overridden to create custom themes.
+
+## How Theming Works
+
+Components use CSS variables for all visual properties. For example:
+
+```css
+/* Instead of hardcoded values */
+background: #fff;
+color: #000;
+
+/* Components use variables */
+background: var(--surface-3);
+color: var(--surface-3-text);
+```
+
+These variables are defined in the base theme (`src/style.css`) and can be overridden at different scopes:
+- Globally (affects all components)
+- On specific components or containers
+- Per-instance using inline styles
+
+## Available Variables
+
+The theming system includes variables for:
+
+### Surfaces
+UI elevation levels (`--surface-0` through `--surface-6`) with paired text colors (`--surface-*-text`).
+
+### Content
+Background and text colors for user content areas (`--content`, `--content-text`).
+
+### Accent
+Primary action colors (`--accent`, `--accent-text`) and surface-based accent variants.
+
+### Feedback/Status
+State indicator colors (`--error`, `--error-text`).
+
+### Typography
+Font families, weights, and sizes (`--font-family`, `--font-mono`, `--text-xs`, etc.).
+
+### Spacing
+Consistent spacing values (`--space-xs`, `--space-s`, `--space-m`, etc.).
+
+### Borders & Radius
+Border styles and corner rounding (`--border`, `--border-subtle`, `--radius-s`, etc.).
+
+### Shadows
+Elevation effects (`--shadow-m`, `--shadow-l`).
+
+### Theme Fallbacks
+All components include a centralized fallback module (`themeFallbacks` in `src/styles/fallbacks.ts`) that registers `@property` rules for every theme variable. This ensures components render correctly even when the base theme CSS isn't loaded — the fallback values mirror the dark theme defaults.
+
+### Interaction
+Disabled states and transitions (`--disabled-opacity`, `--transition`).
+
+### Item States
+Styling for list/item components (`--item-border`, `--item-bg-selected`, etc.).
+
+### Prominence Styles
+Interaction feedback for visual components (`--prominence-idle-opacity`, etc.).
+
+## Customizing Themes
+
+### Global Overrides
+
+To customize themes globally, override variables on the `:root` selector:
+
+```css
+:root {
+  /* Change accent color */
+  --accent: oklch(60% 0.15 200); /* Blue-ish accent */
+  
+  /* Modify surface colors */
+  --surface-3: oklch(90% 0.01 240); /* Lighter panel background */
+  
+  /* Adjust spacing */
+  --space-m: 10px; /* Larger default spacing */
+}
+```
+
+### Component-Specific Overrides
+
+Apply theme overrides to specific components or containers:
+
+```html
+<!-- All components inside this container use custom theme -->
+<div class="my-custom-theme">
+  <ixfx-button>Click me</ixfx-button>
+  <ixfx-panel>Content</ixfx-panel>
+</div>
+```
+
+```css
+.my-custom-theme {
+  --accent: oklch(50% 0.2 300); /* Purple accent */
+  --font-family: 'Georgia', serif; /* Different font */
+}
+```
+
+### Per-Instance Overrides
+
+Customize individual components using inline styles:
+
+```html
+<ixfx-button style="
+  --accent: oklch(70% 0.15 50); /* Orange for this button */
+  --space-m: 16px; /* Larger spacing just for this button */
+">
+  Custom Button
+</ixfx-button>
+```
+
+## Complete Base Theme Reference
+
+Below is the full set of CSS variables used by the library. Copy this into your own stylesheet as a starting point and override the values you want to change.
+
+```css
+/* ========================================
+   ixfx Components — Base Theme Reference
+   ========================================
+   All colours use OKLCH for perceptual uniformity.
+   Dark theme is the default. Light theme overrides
+   are nested under @media (prefers-color-scheme: light).
+   ======================================== */
+
+:root {
+  /* ── Surfaces (depth: higher = more elevated) ── */
+  --surface-0: oklch(5% 0.02 240);
+  --surface-1: oklch(8% 0.02 240);
+  --surface-2: oklch(12% 0.02 240);
+  --surface-3: oklch(15% 0.02 240);   /* default UI plane */
+  --surface-4: oklch(22% 0.02 240);   /* buttons, inputs */
+  --surface-5: oklch(28% 0.02 240);   /* menus, popovers */
+  --surface-6: oklch(35% 0.02 240);   /* active/pressed, hover in popups */
+
+  /* ── Text on Surfaces ── */
+  --surface-2-text: #fff;
+  --surface-3-text: oklch(75% 0.02 240);
+  --surface-4-text: #fff;
+  --surface-5-text: #fff;
+  --surface-6-text: #fff;
+  --surface-muted-text: oklch(55% 0.02 240);
+
+  /* ── Content (user content areas — canvas, editors) ── */
+  --content: oklch(10% 0.01 240);
+  --content-text: #fff;
+
+  /* ── Accent ── */
+  --accent: oklch(60% 0.15 140);
+  --accent-text: #fff;
+
+  /* ── Feedback / Status ── */
+  --error: oklch(60% 0.15 20);
+  --error-text: #fff;
+
+  /* ── Typography ── */
+  --font-family: system-ui, sans-serif;
+  --font-mono: ui-monospace, monospace;
+  --font-weight: 400;
+  --font-weight-bold: 600;
+  --text-xs: 10px;
+  --text-s: 11px;
+  --text-m: 12px;
+  --text-l: 13px;
+  --text-xl: 16px;
+  --text-2xl: 20px;
+
+  /* ── Spacing ── */
+  --space-xs: 3px;
+  --space-s: 4px;
+  --space-m: 8px;
+  --space-l: 12px;
+  --space-xl: 16px;
+  --space-2xl: 20px;
+
+  /* ── Borders ── */
+  --border: 1px solid oklch(25% 0.02 240);
+  --border-subtle: 1px solid oklch(18% 0.02 240);
+  --radius-s: 3px;
+  --radius-m: 4px;
+  --radius-l: 6px;
+  --radius-xl: 8px;
+
+  /* ── Shadows ── */
+  --shadow-m: 0 4px 12px rgba(0, 0, 0, 0.3);
+  --shadow-l: 0 4px 24px rgba(0, 0, 0, 0.5);
+
+  /* ── Interaction ── */
+  --disabled-opacity: 0.5;
+  --transition: 0.15s ease-out;
+
+  /* ── Item States ── */
+  --item-bg: transparent;
+  --item-bg-tickled: var(--surface-5);
+  --item-bg-selected: var(--accent);
+  --item-bg-selected-tickled: color-mix(in oklch, var(--accent) 80%, oklch(0% 0 0));
+  --item-text-tickled: var(--surface-5-text);
+  --item-text-selected: var(--accent-text);
+  --item-border: 1px solid var(--surface-5);
+  --item-border-tickled: 1px solid color-mix(in oklch, var(--accent) 40%, transparent);
+  --item-border-selected: 1px dashed var(--accent);
+  --item-border-active: 2px solid var(--accent);
+  --item-border-dragged: 2px dotted color-mix(in oklch, var(--accent) 80%, transparent);
+  --item-border-disabled: 1px solid var(--surface-4);
+  --item-padding: var(--space-s) var(--space-m);
+  --item-border-radius: var(--radius-m);
+  --item-icon-spacing: var(--space-s);
+
+  /* ── Item Label Styling ── */
+  --item-label-font-style-default: normal;
+  --item-label-font-style-selected: italic;
+  --item-label-font-style-tickled: normal;
+  --item-label-text-decoration-default: none;
+  --item-label-text-decoration-selected: none;
+  --item-label-text-decoration-tickled: underline;
+  --item-label-text-underline-offset-default: auto;
+  --item-label-text-underline-offset-tickled: 3px;
+
+  /* ── Prominence (filter-based idle/tickled/active) ── */
+  --prominence-idle-opacity: 0.6;
+  --prominence-idle-saturate: 0.4;
+  --prominence-tickled-opacity: 0.85;
+  --prominence-tickled-saturate: 0.8;
+  --prominence-disabled-opacity: 0.3;
+  --prominence-disabled-saturate: 0.1;
+
+  /* ── Miscellaneous ── */
+  --transparent-bg: oklch(30% 0.02 240);
+  --plot-color: var(--accent);
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    --surface-0: oklch(70% 0 0);
+    --surface-1: oklch(80% 0.01 240);
+    --surface-2: oklch(85% 0.01 240);
+    --surface-3: oklch(90% 0.01 240);
+    --surface-4: oklch(94% 0.01 240);
+    --surface-5: oklch(96% 0.01 240);
+    --surface-6: oklch(99% 0.01 240);
+
+    --surface-2-text: oklch(15% 0.02 240);
+    --surface-3-text: oklch(25% 0.02 240);
+    --surface-4-text: oklch(15% 0.02 240);
+    --surface-5-text: oklch(10% 0.02 240);
+    --surface-6-text: oklch(10% 0.02 240);
+    --surface-muted-text: oklch(45% 0.02 240);
+
+    --content: oklch(100% 0 0);
+    --content-text: oklch(10% 0.02 240);
+
+    --accent: oklch(45% 0.15 140);
+    --accent-text: #fff;
+
+    --error: oklch(55% 0.15 20);
+    --error-text: #fff;
+
+    --border: 1px solid oklch(80% 0.01 240);
+    --border-subtle: 1px solid oklch(88% 0.01 240);
+
+    --shadow-m: 0 2px 8px rgba(0, 0, 0, 0.1);
+    --shadow-l: 0 4px 16px rgba(0, 0, 0, 0.15);
+
+    --prominence-idle-opacity: 0.55;
+    --prominence-idle-saturate: 0.35;
+    --prominence-tickled-opacity: 0.8;
+    --prominence-tickled-saturate: 0.75;
+    --prominence-disabled-opacity: 0.25;
+    --prominence-disabled-saturate: 0.1;
+
+    --transparent-bg: oklch(85% 0.01 240);
+
+    --item-border: 1px solid var(--surface-4);
+    --item-border-tickled: 1px solid color-mix(in oklch, var(--accent) 50%, transparent);
+    --item-border-selected: 1px dashed var(--accent);
+    --item-border-active: 2px solid var(--accent);
+    --item-border-dragged: 2px dotted var(--accent);
+    --item-border-disabled: 1px solid var(--surface-3);
+    --item-bg-tickled: var(--surface-4);
+    --item-bg-selected-tickled: color-mix(in oklch, var(--accent) 80%, oklch(0% 0 0));
+    --item-text-tickled: var(--surface-4-text);
+    --item-bg-selected: var(--accent);
+    --item-text-selected: var(--accent-text);
+
+    --item-label-font-style-default: normal;
+    --item-label-font-style-selected: italic;
+    --item-label-font-style-tickled: normal;
+    --item-label-text-decoration-default: none;
+    --item-label-text-decoration-selected: none;
+    --item-label-text-decoration-tickled: underline;
+    --item-label-text-underline-offset-default: auto;
+    --item-label-text-underline-offset-tickled: 3px;
+  }
+}
+```
+
+## Using Demo Themes as Examples
+
+The library includes several demo themes that showcase different customization approaches:
+
+### Cyberpunk Theme
+- Monospace typography
+- Sharp corners (0px radius)
+- Custom accent hue (cyan/blue)
+- Modified surface colors
+
+### Retro Theme
+- Serif typography
+- Larger border radii
+- Warm accent colors (orange/brown)
+- Dashed borders for selected items
+
+### Flat Theme
+- Minimal styling
+- High contrast colors
+- No deboss effects
+
+You can inspect the demo themes in:
+- `demo/shared/base-themes.css` - Base dark/light theme definitions
+- `demo/shared/demo-themes.css` - Theme-specific overrides
+
+## Best Practices
+
+1. **Use Semantic Variables**: Always prefer `--surface-3` over hardcoded colors for better theme compatibility
+2. **Maintain Contrast**: Ensure text remains readable against background colors
+3. **Test Both Themes**: Verify customizations work in both dark and light modes
+4. **Leverage Inheritance**: Set variables on parent elements to affect child components
+5. **Use Theme Fallbacks in Shadow DOM**: When building custom elements that use these variables in their shadow DOM, import and include the `themeFallbacks` module in your `static styles`:
+
+   ```ts
+   import { themeFallbacks } from '@ixfx/components/styles/fallbacks.js';
+
+   class MyWidget extends LitElement {
+     static styles = [themeFallbacks, css`
+       :host {
+         background: var(--surface-3);
+         color: var(--surface-3-text);
+       }
+     `];
+   }
+   ```
+
+   This registers `@property` rules so the variables resolve correctly in shadow DOM even when no `:root` theme is loaded. Do not use per-usage CSS fallbacks (`var(--surface-3, #ccc)`) — the `@property` approach is centralized and automatically stays in sync with the theme.
+
+## Theme Activation
+
+The system automatically detects theme preference via `prefers-color-scheme` media query. To force a specific theme:
+
+```html
+<!-- Force dark theme -->
+<html class="theme-dark">
+  <!-- components -->
+</html>
+
+<!-- Force light theme -->
+<html class="theme-light">
+  <!-- components -->
+</html>
+```
+
+## Migration Notes
+
+If you're upgrading from previous versions:
+- All color values now use OKLCH for perceptual uniformity
+- Variable names remain stable but values may have been adjusted
+- Custom themes may need adjustment for the new color system
+
+## Further Reading
+
+For implementation details, see:
+- [`docs/infra-theming.md`](infra-theming.md) - Internal theming specification
+- [`src/style.css`] - Base theme definitions
+- [`demo/shared/`] - Example theme implementations

package/docs-user/util.md

@@ -0,0 +1,122 @@
+# `ixfx-tooltip`
+
+A tooltip component that renders a value with optional icon and formatted number display. Uses native render root (no shadow DOM).
+
+```html
+<ixfx-tooltip value="42" orientation="top"></ixfx-tooltip>
+<ixfx-tooltip value="3.14159" icon="pi"></ixfx-tooltip>
+<ixfx-tooltip value="error" icon="<svg>...</svg>" orientation="bottom"></ixfx-tooltip>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type                           | Default                   | Description                   |
+|----------------------|--------------------------------|---------------------------|-------------------------------|
+| `value`              | `unknown`                      | `undefined`               | Value to display              |
+| `orientation`        | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Popover orientation |
+| `anchor`             | `string`                       | `'--tooltip'`             | CSS anchor name               |
+| `icon`               | `string \| undefined`          | `undefined`               | Icon name or raw SVG string   |
+
+### Value formatting
+
+Numbers are formatted using `valueFormatTooltip`:
+- Integers display as-is
+- Floats display with 2 decimal places
+- Strings display as-is
+- Other values are JSON-stringified
+
+### Static properties
+
+| Property              | Type                    | Description                    |
+|-----------------------|-------------------------|--------------------------------|
+| `numberFormatter`     | `(v: number) => string` | Formats number for display     |
+| `defaultFormatter`    | `FormatValueForHuman`   | Default value formatter        |
+
+### Instance properties
+
+| Property              | Type                    | Description                    |
+|-----------------------|-------------------------|--------------------------------|
+| `valueFormatTooltip`  | `FormatValueForHuman`   | Instance formatter, adjustable |
+
+### CSS custom properties
+
+| Property   | Default | Description       |
+|------------|---------|-------------------|
+| `--anchor-id` | set dynamically | CSS anchor for positioning |
+
+### CSS classes
+
+The component applies these classes to the output element:
+- `tooltip`
+- `tooltip-orientation-{top|right|bottom|left}`
+- `tooltip-type-text` or `tooltip-type-number`
+- `tooltip-style-bubble`
+
+### Usage notes
+
+- `renderRenderRoot` returns `this` (light DOM), allowing CSS from parent to style the tooltip
+- For native CSS anchor positioning, set `anchor` to a unique CSS custom property name
+- Can be used as an overlay element positioned via CSS Anchor Positioning API
+
+---
+
+# `ixfx-value-drag`
+
+A vertical drag handle for adjusting numeric values. Drag up/down to change value; click the slot to activate an editor.
+
+```html
+<ixfx-value-drag min="0" max="100" value="50"></ixfx-value-drag>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type                   | Default    | Description                                  |
+|---------------------|------------------------|------------|----------------------------------------------|
+| `min`              | `number`               | `0`        | Minimum value                                |
+| `max`              | `number`               | `1`        | Maximum value                                |
+| `value`            | `number`               | `0.5`      | Current value                                |
+| `sensitivity`      | `number`               | `0.3`      | Screen percentage needed to reach min/max     |
+| `disabled`         | `boolean`              | `false`    | Disables interaction                         |
+| `numberConverter`  | `(v: number) => number`| `Math.floor` | Converts the raw value                      |
+
+### Events
+
+| Event    | Detail                    | Description                            |
+|----------|---------------------------|----------------------------------------|
+| `input`  | `{ value: number }`      | Fired continuously during drag         |
+| `change` | `{ value: number }`      | Fired when drag ends                   |
+
+### Usage
+
+```js
+const drag = document.querySelector('ixfx-value-drag');
+drag.min = 0;
+drag.max = 255;
+drag.value = 128;
+
+// Listen for changes
+drag.addEventListener('change', e => {
+  console.log('final value:', e.detail.value);
+});
+
+// Listen during drag
+drag.addEventListener('input', e => {
+  console.log('current value:', e.detail.value);
+});
+```
+
+### Custom value conversion
+
+By default, values are floored to integers. Provide a custom converter:
+
+```js
+drag.numberConverter = v => Math.round(v);  // Round instead of floor
+drag.numberConverter = v => v.toFixed(2); // Keep 2 decimal places (returns string!)
+```
+
+### CSS custom properties
+
+| Property   | Default | Description       |
+|------------|---------|-------------------|
+| --surface-3 | `#ccc` | Background color |
+| --surface-text | `#000` | Text color |