@zumer/orbit-kit 0.1.0 → 2.1.0

package/src/o-knob.js

@@ -1,191 +1,199 @@
 /**
- * <o-knob> — interactive rotary control.
+ * <o-knob>: a rotary slider. Grab the band and turn it, drag anywhere else
+ * vertically, use the wheel while focused, or press arrows / Page Up·Down /
+ * Home·End. Emits `input` while changing and `change` when a gesture commits,
+ * like <input type="range">; setting `value` from code fires neither.
+ * It is a form control (FormControl): `name`, `disabled`, form reset/restore.
  *
- * Collapses the Orbit recipe:
- *
- *   .bigbang > .gravity-spot
- *     ├── .orbit-N > <o-arc shape="circle-a">   (the dial)
- *     └── .orbit-0 > .satellite.at-center > .capsule   (value readout)
- *
- * ...into one tag that behaves like a form control:
- *
- *   <o-knob value="65" min="0" max="100" unit="%" fill="#a1a1aa"></o-knob>
- *
- * Interaction: drag vertically (or use the mouse wheel / arrow keys when
- * focused) to change the value. Emits a bubbling `input` event on every change
- * and `change` when the gesture ends. `el.value` reads/writes the number.
+ * The track is an `interactive` <o-arc> with a `hit-width`, so the whole band
+ * takes the pointer even where it is transparent.
  */
-import { OrbitKitElement, define } from './base.js';
+import { OrbitKitElement, FormControl, define, injectStyleOnce, universe, hub, fixed, escapeHTML, finiteNumber, snapValue, pointerAngle, valueAtAngle, withShared, RANGE_ATTRS, FORMAT_ATTRS, FORM_ATTRS } from './base.js';
 
-export class OrbitKnob extends OrbitKitElement {
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+export class OrbitKnob extends FormControl(OrbitKitElement) {
   static get observedAttributes() {
-    return ['value', 'min', 'max', 'step', 'size', 'orbit', 'fill', 'track',
-            'stroke-width', 'shape', 'unit', 'label', 'disabled', 'range', 'from', 'glow'];
+    return withShared(['value', 'size', 'orbit', 'thickness', 'fill', 'track',
+      'stroke-width', 'shape', 'label', 'range', 'from', 'glow'], RANGE_ATTRS, FORMAT_ATTRS, FORM_ATTRS);
+  }
+
+  constructor() {
+    super();
+    for (const name of ['_onDown', '_onMove', '_onUp', '_onWheel', '_onKey']) {
+      this[name] = this[name].bind(this);
+    }
   }
 
   readConfig() {
-    const range = this._num('range', 270);
-    const min = this._num('min', 0);
-    const max = this._num('max', 100);
+    const range = clamp(this._num('range', 270), 0, 360);
+    const r = this._range({ min: 0, max: 100, step: 1 });
     return {
-      value: this._num('value', min),
-      min, max,
-      span: (max - min) || 1,
-      step: this._num('step', 1),
+      min: r.min, max: r.max, span: r.span || 1, step: r.step, value: r.value, fraction: r.fraction,
       range,
       from: this.hasAttribute('from') ? this._num('from', 0) : this._autoFrom(range),
-      orbit: Math.round(this._num('orbit', 4)),
-      size: this._str('size', '160px'),
-      fill: this._str('fill', '#a1a1aa'),
-      track: this._str('track', '#27272a'),
-      strokeWidth: this._num('stroke-width', 14),
-      shape: this._str('shape', 'rounded'),
-      unit: this._str('unit', ''),
-      disabled: this.hasAttribute('disabled'),
-      glow: this.getAttribute('glow'),
+      thickness: this._thickness(2.4),
+      size: this._size('size', '160px'),
+      fill: this._color('fill', null), track: this._color('track', null),
+      strokeWidth: Math.max(0, this._num('stroke-width', 0)),
+      shape: this._str('shape', 'rounded'), unit: this._unitText(),
+      disabled: this._isDisabled(), glow: this.getAttribute('glow'),
       label: this.hasAttribute('label') ? this.getAttribute('label') : null
     };
   }
 
+  /** Clamp and snap like the attribute (kept for 1.0 callers). */
+  _normalize(raw, cfg) { return snapValue(finiteNumber(raw, cfg.min), cfg); }
+
   structuralSignature(cfg) {
-    const { value, label, disabled, ...rest } = cfg;
+    const { value, fraction, min, max, span, step, label, disabled, fill, track, unit, ...rest } = cfg;
     return JSON.stringify(rest);
   }
 
   build(cfg) {
-    // Scale --o-force so the dial (orbit-N) fits the box with a margin.
-    const dialPx = parseFloat(cfg.size) || 160;
-    const force = (dialPx * 12 / (cfg.orbit + 1)).toFixed(1);
-    const ring = `--o-range:${cfg.range}deg;--o-from:${cfg.from}deg;`;
-    const trackStyle = `--o-fill:${cfg.track};--o-stroke:${cfg.track};--o-stroke-width:${cfg.strokeWidth}`;
-    const valStyle = `--o-fill:${cfg.fill};--o-stroke:${cfg.fill};--o-stroke-width:${cfg.strokeWidth};${this._glow(cfg.fill)}`;
-
-    this.innerHTML = `
-      <div class="bigbang" style="width:${cfg.size};aspect-ratio:1;${cfg.disabled ? 'opacity:.5;' : ''}">
-        <div class="gravity-spot" style="--o-force:${force}px;">
-          <div class="orbit-${cfg.orbit}" style="${ring}"><o-arc value="100" shape="${cfg.shape}" style="${trackStyle}"></o-arc></div>
-          <div class="orbit-${cfg.orbit}" style="${ring}"><o-arc class="o-knob-dial" value="0" shape="${cfg.shape}" style="${valStyle}"></o-arc></div>
-          <div class="orbit-0">
-            <div class="satellite at-center">
-              <div class="capsule ok-hub o-knob-readout"></div>
-            </div>
-          </div>
-        </div>
-      </div>`;
-
+    const e = escapeHTML;
+    const ring = `--o-range:${cfg.range}deg;--o-from:${cfg.from}deg;--o-size-ratio:${fixed(cfg.thickness)};--o-gap:0`;
+    const stroke = cfg.strokeWidth ? `--o-stroke-width:${cfg.strokeWidth};` : '';
+    const glow = cfg.glow == null ? '' : `filter:drop-shadow(0 0 ${Math.max(0, this._num('glow', 6))}px var(--ok-fill, #a1a1aa));`;
+    this.innerHTML = universe(cfg.size, `
+      <div class="orbit-12" style="${ring}"><o-arc aria-hidden="true" class="inner-orbit ok-track o-knob-track" interactive hit-width="6" value="100" shape="${e(cfg.shape)}"${stroke ? ` style="${stroke}"` : ''}></o-arc></div>
+      <div class="orbit-12" style="${ring}"><o-arc aria-hidden="true" class="inner-orbit ok-value o-knob-dial" value="0" shape="${e(cfg.shape)}" ${stroke || glow ? ` style="${stroke}${glow}"` : ''}></o-arc></div>
+      ${hub(2 * (12 - cfg.thickness) - 1, '', 'ok-hub o-knob-readout', ' aria-hidden="true"')}`);
+    this._box = this.querySelector('.bigbang');
     this._dial = this.querySelector('.o-knob-dial');
     this._readout = this.querySelector('.o-knob-readout');
-
-    // Accessibility: act as a slider.
     this.setAttribute('role', 'slider');
-    this.tabIndex = cfg.disabled ? -1 : 0;
-    this.style.touchAction = 'none';
-    this.style.cursor = cfg.disabled ? 'default' : 'ns-resize';
   }
 
   sync(cfg) {
-    const v = Math.min(cfg.max, Math.max(cfg.min, cfg.value));
-    const pct = ((v - cfg.min) / cfg.span) * 100;
-    if (this._dial) this._dial.setAttribute('value', pct.toFixed(2));
-    if (this._readout) {
-      this._readout.textContent = cfg.label !== null ? cfg.label : `${Math.round(v)}${cfg.unit}`;
+    this._applyTheme({ '--ok-fill': cfg.fill, '--ok-track': cfg.track });
+    if (this._dial) this._dial.setAttribute('value', (cfg.fraction * 100).toFixed(2));
+    const text = this._formatText(cfg.value, { min: cfg.min, max: cfg.max });
+    if (this._readout) this._readout.textContent = cfg.label ?? text;
+    this._ariaRange(cfg, cfg.value, this._formatText(cfg.value, { min: cfg.min, max: cfg.max, kind: 'aria' }));
+    if (!this.hasAttribute('aria-labelledby') && (!this.hasAttribute('aria-label') || this.getAttribute('aria-label') === this._autoLabel)) {
+      this._autoLabel = cfg.label || 'Rotary control';
+      this.setAttribute('aria-label', this._autoLabel);
     }
-    this.setAttribute('aria-valuenow', String(v));
-    this.setAttribute('aria-valuemin', String(cfg.min));
-    this.setAttribute('aria-valuemax', String(cfg.max));
+    this.tabIndex = cfg.disabled ? -1 : 0;
+    this.style.touchAction = cfg.disabled ? 'auto' : 'none';
+    this.style.cursor = cfg.disabled ? 'default' : 'ns-resize';
+    this.toggleAttribute?.('data-disabled', cfg.disabled);
+    if (this._box) this._box.style.opacity = cfg.disabled ? '.5' : '';
+    if (cfg.disabled) this._stopDrag();
   }
 
-  /** Numeric value as a property (framework-friendly). */
-  get value() { return this._num('value', this._num('min', 0)); }
-  set value(v) { this._commit(v); }
+  get value() { return this.readConfig().value; }
+  /** Setting the value snaps and clamps it and fires no event, like a native input. */
+  set value(value) { this._commit(finiteNumber(value, this.value), { silent: true }); }
+  get valueAsNumber() { return this.value; }
+  get min() { return this.readConfig().min; }
+  set min(value) { this.setAttribute('min', String(value)); }
+  get max() { return this.readConfig().max; }
+  set max(value) { this.setAttribute('max', String(value)); }
+  get step() { return this.readConfig().step; }
+  set step(value) { this.setAttribute('step', String(value)); }
+  stepUp(n = 1) { const cfg = this.readConfig(); this._commit(cfg.value + n * (cfg.step || cfg.span / 100), { silent: true }); }
+  stepDown(n = 1) { this.stepUp(-n); }
 
   onConnected() {
-    this._onDown = this._onDown.bind(this);
-    this._onMove = this._onMove.bind(this);
-    this._onUp = this._onUp.bind(this);
-    this._onWheel = this._onWheel.bind(this);
-    this._onKey = this._onKey.bind(this);
     this.addEventListener('pointerdown', this._onDown);
+    this.addEventListener('lostpointercapture', this._onUp);
     this.addEventListener('wheel', this._onWheel, { passive: false });
     this.addEventListener('keydown', this._onKey);
   }
 
   onDisconnected() {
     this.removeEventListener('pointerdown', this._onDown);
+    this.removeEventListener('lostpointercapture', this._onUp);
     this.removeEventListener('wheel', this._onWheel);
     this.removeEventListener('keydown', this._onKey);
-    window.removeEventListener('pointermove', this._onMove);
-    window.removeEventListener('pointerup', this._onUp);
+    this._stopDrag();
   }
 
-  _cfg() { return this.readConfig(); }
-
-  _commit(raw, emitChange = false) {
-    const cfg = this._cfg();
-    if (cfg.disabled) return;
-    let v = Math.min(cfg.max, Math.max(cfg.min, raw));
-    if (cfg.step > 0) v = Math.round(v / cfg.step) * cfg.step;
-    v = Number(v.toFixed(6));
-    const prev = this._num('value', cfg.min);
-    if (v !== prev) {
-      this.setAttribute('value', String(v)); // triggers re-render via attributeChangedCallback
-      this.dispatchEvent(new CustomEvent('input', { detail: { value: v }, bubbles: true }));
-    }
-    if (emitChange) {
-      this.dispatchEvent(new CustomEvent('change', { detail: { value: v }, bubbles: true }));
+  _emit(type, value) { this._emitValue(type, value); }
+
+  /** Set a value; user gestures fire `input` (and `change` when they commit). */
+  _commit(raw, { change = false, silent = false } = {}) {
+    const cfg = this.readConfig();
+    const value = this._normalize(raw, cfg);
+    const changed = value !== cfg.value;
+    // The attribute shows the current value; the default (for form reset) stays.
+    this._reflectValue(String(value));
+    if (changed && !silent) {
+      this._emit('input', value);
+      if (change) this._emit('change', value);
     }
   }
 
-  _onDown(e) {
-    const cfg = this._cfg();
-    if (cfg.disabled) return;
-    e.preventDefault();
+  _onDown(event) {
+    if (this._isDisabled() || event.button !== 0 || this._pointerId != null) return;
+    event.preventDefault();
     this.focus();
-    this._dragStartY = e.clientY;
-    this._dragStartVal = this._num('value', cfg.min);
+    this._pointerId = event.pointerId;
+    this._dragStartY = event.clientY;
+    this._dragStartVal = this.value;
+    // On the band the knob follows the pointer around; elsewhere it is a vertical drag.
+    this._rotary = !!event.target?.closest?.('.o-knob-track');
+    if (this._rotary) this._commit(this._valueAt(event));
+    this.setPointerCapture?.(event.pointerId);
     window.addEventListener('pointermove', this._onMove);
     window.addEventListener('pointerup', this._onUp);
+    window.addEventListener('pointercancel', this._onUp);
   }
 
-  _onMove(e) {
-    const cfg = this._cfg();
-    // Full sweep ~= 200px of vertical travel; up increases.
-    const dy = this._dragStartY - e.clientY;
-    const delta = (dy / 200) * cfg.span;
-    this._commit(this._dragStartVal + delta);
+  _onMove(event) {
+    if (event.pointerId !== this._pointerId || this._isDisabled()) return;
+    if (this._rotary) this._commit(this._valueAt(event));
+    else this._commit(this._dragStartVal + (this._dragStartY - event.clientY) / 200 * this.readConfig().span);
   }
 
-  _onUp() {
+  /** The value under the pointer, from its angle around the center. */
+  _valueAt(event) {
+    const cfg = this.readConfig();
+    if (!this._box?.getBoundingClientRect || !cfg.range) return cfg.value;
+    return valueAtAngle(pointerAngle(event, this._box), cfg);
+  }
+
+  _stopDrag() {
+    if (typeof window === 'undefined') return;
+    if (this._pointerId != null && this.hasPointerCapture?.(this._pointerId)) this.releasePointerCapture(this._pointerId);
+    this._pointerId = null;
     window.removeEventListener('pointermove', this._onMove);
     window.removeEventListener('pointerup', this._onUp);
-    this._commit(this._num('value', this._cfg().min), true);
+    window.removeEventListener('pointercancel', this._onUp);
   }
 
-  _onWheel(e) {
-    const cfg = this._cfg();
-    if (cfg.disabled) return;
-    e.preventDefault();
-    const dir = e.deltaY < 0 ? 1 : -1;
-    this._commit(this._num('value', cfg.min) + dir * (cfg.step || 1), true);
+  _onUp(event) {
+    if (event.pointerId !== this._pointerId) return;
+    const changed = this.value !== this._dragStartVal;
+    this._stopDrag();
+    if (changed && !this._isDisabled()) this._emit('change', this.value);
   }
 
-  _onKey(e) {
-    const cfg = this._cfg();
-    if (cfg.disabled) return;
-    const step = cfg.step || 1;
-    const map = {
-      ArrowUp: step, ArrowRight: step, ArrowDown: -step, ArrowLeft: -step,
-      PageUp: step * 10, PageDown: -step * 10
-    };
-    if (e.key in map) {
-      e.preventDefault();
-      this._commit(this._num('value', cfg.min) + map[e.key], true);
-    } else if (e.key === 'Home') {
-      e.preventDefault(); this._commit(cfg.min, true);
-    } else if (e.key === 'End') {
-      e.preventDefault(); this._commit(cfg.max, true);
-    }
+  _onWheel(event) {
+    if (this._isDisabled() || this.ownerDocument?.activeElement !== this || !event.deltaY) return;
+    event.preventDefault();
+    const cfg = this.readConfig();
+    this._commit(cfg.value + (event.deltaY < 0 ? 1 : -1) * (cfg.step || cfg.span / 100), { change: true });
+  }
+
+  _onKey(event) {
+    if (this._isDisabled()) return;
+    const cfg = this.readConfig();
+    const next = this._keyValue(event, cfg);
+    if (next == null) return;
+    event.preventDefault();
+    this._commit(next, { change: true });
   }
 }
 
+injectStyleOnce('orbit-kit-knob', `
+o-knob { -webkit-tap-highlight-color: transparent; }
+o-knob .ok-track { --o-fill: var(--ok-track, #27272a); --o-stroke: var(--o-fill); }
+o-knob .ok-value { --o-fill: var(--ok-fill, #a1a1aa); --o-stroke: var(--o-fill); }
+o-knob .o-knob-track { cursor: grab; }
+o-knob[data-disabled] .o-knob-track { cursor: default; }
+o-knob[data-disabled] > .bigbang { opacity: .5; }
+`);
 define('o-knob', OrbitKnob);