@ixfx/components 0.3.1 → 0.4.0

package/docs-user/polar-pad.md

@@ -0,0 +1,228 @@
+# `<ixfx-polar-pad>`
+
+A circular pad for setting polar coordinates (angle + radius). The user clicks or drags within a circle to position a marker. The marker's position encodes an angle (degrees, 0 = right, clockwise) and a radius (0–1).
+
+---
+
+## Basic usage
+
+```html
+<ixfx-polar-pad angle="0" radius="0.5"></ixfx-polar-pad>
+```
+
+```js
+const pad = document.querySelector('ixfx-polar-pad');
+pad.addEventListener('input', e => {
+  console.log('angle:', e.detail.angle, 'radius:', e.detail.radius);
+});
+```
+
+---
+
+## Attributes / properties
+
+| Attribute / Property | Type      | Default | Description                                                  |
+|---------------------|-----------|---------|--------------------------------------------------------------|
+| `angle`             | `number`  | `0`     | Current angle in degrees (0 = right, clockwise)            |
+| `radius`            | `number`  | `0.5`   | Current radius 0–1 (0 = centre, 1 = edge)                   |
+| `rings`             | `number`  | `0`     | Number of concentric rings to draw (0 = none)              |
+| `rays`              | `number`  | `0`     | Number of radial spokes to draw (0 = none)                 |
+| `show-ray`          | `boolean` | `false` | Draw a line from origin to the marker                       |
+| `show-origin`       | `boolean` | `false` | Show a dot at the origin (centre)                          |
+
+---
+
+## Events
+
+Both events are `CustomEvent` instances with `{ bubbles: true, composed: true }`.
+
+| Event   | `detail` type                              | Description                              |
+|---------|--------------------------------------------|------------------------------------------|
+| `input` | `{ angle: number, radius: number }`      | Fires continuously while dragging        |
+
+- `angle` — degrees, 0 = right, clockwise
+- `radius` — 0–1
+
+---
+
+## Sizing
+
+The component defaults to 200×200px and scales to fill its container:
+
+```css
+/* Custom size */
+ixfx-polar-pad {
+  width: 300px;
+  height: 300px;
+}
+
+/* Full-width */
+ixfx-polar-pad {
+  width: 100%;
+  aspect-ratio: 1;
+}
+```
+
+---
+
+## CSS variables
+
+### Pad
+
+| Variable              | Default                              | Description                                  |
+|----------------------|--------------------------------------|----------------------------------------------|
+| `--pad-background`   | `var(--surface-ll, oklch(22% 0.02 240))` | Background (any CSS background value)       |
+| `--pad-border-color` | `var(--surface-hh, oklch(35% 0.02 240))` | Stroke of the outer circle                   |
+| `--pad-border-width` | `1px`                                | Thickness of outer border                   |
+
+### Marker
+
+| Variable               | Default                              | Description                      |
+|-----------------------|--------------------------------------|----------------------------------|
+| `--marker-size`       | `10cqb`                              | Diameter of the draggable marker |
+| `--marker-color`     | `var(--accent, oklch(60% 0.15 140))` | Fill colour of the marker       |
+| `--marker-opacity`   | `1`                                  | Opacity of the marker            |
+| `--marker-stroke`    | `none`                               | Stroke colour of the marker     |
+| `--marker-stroke-width` | `0`                               | Stroke thickness of the marker  |
+
+### Origin dot (`show-origin`)
+
+| Variable          | Default                              | Description                |
+|------------------|--------------------------------------|----------------------------|
+| `--origin-size`  | `6cqb`                               | Diameter of the origin dot |
+| `--origin-color` | `var(--accent, oklch(60% 0.15 140))` | Fill colour               |
+| `--origin-opacity` | `1`                                | Opacity                   |
+
+### Ray line (`show-ray`)
+
+| Variable        | Default                              | Description                    |
+|----------------|--------------------------------------|--------------------------------|
+| `--ray-color`  | `var(--surface-hh, oklch(35% 0.02 240))` | Stroke colour                |
+| `--ray-width` | `2px`                                | Thickness                      |
+| `--ray-opacity` | `1`                                | Opacity                        |
+| `--ray-dash`  | `none`                               | `stroke-dasharray` (e.g. `"4 2"`) |
+
+### Rings (`rings > 0`)
+
+| Variable        | Default                              | Description                    |
+|----------------|--------------------------------------|--------------------------------|
+| `--ring-color` | `var(--surface-hh, oklch(35% 0.02 240))` | Stroke colour                |
+| `--ring-width` | `1px`                               | Thickness                      |
+| `--ring-opacity` | `1`                                | Opacity                        |
+| `--ring-dash` | `none`                               | `stroke-dasharray`             |
+
+### Spokes (`rays > 0`)
+
+| Variable          | Default                              | Description                    |
+|------------------|--------------------------------------|--------------------------------|
+| `--spoke-color`  | `var(--surface-hh, oklch(35% 0.02 240))` | Stroke colour                |
+| `--spoke-width` | `1px`                                | Thickness                      |
+| `--spoke-opacity` | `1`                                | Opacity                        |
+| `--spoke-dash`  | `none`                               | `stroke-dasharray`             |
+
+### Dynamic CSS variables (set by component)
+
+The component sets these on its host element for external use:
+
+| Variable       | Description                              |
+|----------------|------------------------------------------|
+| `--angle-deg`  | Current angle as unitless degrees        |
+| `--angle-rad`  | Current angle as unitless radians       |
+| `--radius-pct` | Current radius as unitless 0–100        |
+
+---
+
+## Examples
+
+### Basic pad with marker
+
+```html
+<ixfx-polar-pad></ixfx-polar-pad>
+```
+
+### Show rings and spokes
+
+```html
+<ixfx-polar-pad rings="4" rays="8"></ixfx-polar-pad>
+```
+
+### Show origin and ray
+
+```html
+<ixfx-polar-pad show-origin show-ray></ixfx-polar-pad>
+```
+
+### Custom background gradient
+
+The `--pad-background` accepts any CSS background. Dynamic variables like `--angle-deg` and `--radius-pct` can be used:
+
+```css
+.gradient-pad {
+  --pad-background: conic-gradient(
+    from 0deg,
+    hsl(0 80% 60%),
+    hsl(60 80% 60%),
+    hsl(120 80% 60%),
+    hsl(180 80% 60%),
+    hsl(240 80% 60%),
+    hsl(300 80% 60%),
+    hsl(360 80% 60%)
+  );
+}
+```
+
+```html
+<ixfx-polar-pad class="gradient-pad" show-ray></ixfx-polar-pad>
+```
+
+### Custom marker styling
+
+```css
+.large-marker {
+  --marker-size: 20cqb;
+  --marker-color: hsl(280 70% 50%);
+  --marker-stroke: white;
+  --marker-stroke-width: 2px;
+}
+```
+
+### Custom ring/spoke styling
+
+```css
+.dashed-lines {
+  --ring-dash: "4 2";
+  --spoke-dash: "4 2";
+  --ring-color: hsl(200 50% 60%);
+  --spoke-color: hsl(200 50% 60%);
+}
+```
+
+### Listening to input events
+
+```js
+const pad = document.querySelector('ixfx-polar-pad');
+
+pad.addEventListener('input', ({ detail }) => {
+  const { angle, radius } = detail;
+  console.log(`Position: ${Math.round(angle)}° at ${Math.round(radius * 100)}%`);
+});
+```
+
+### Setting value programmatically
+
+```js
+pad.angle = 45;
+pad.radius = 0.75;
+```
+
+### Converting to Cartesian coordinates
+
+```js
+pad.addEventListener('input', ({ detail }) => {
+  const { angle, radius } = detail;
+  const angleRad = angle * (Math.PI / 180);
+  const x = radius * Math.cos(angleRad);
+  const y = radius * Math.sin(angleRad);
+  console.log(`x: ${x.toFixed(2)}, y: ${y.toFixed(2)}`);
+});
+```