@zumer/orbit-kit 0.1.0 → 2.1.0

package/src/o-color-wheel.js

@@ -0,0 +1,322 @@
+/**
+ * <o-color-wheel>: a circular color picker. A hue ring around a
+ * saturation / brightness square, with an optional ring of swatches.
+ *
+ *   .orbit-0  > .satellite.at-center > .ok-cw-ring     the hue ring (a conic gradient)
+ *   .orbit-12 > .satellite                             hue handle, at the hue's angle
+ *   .orbit-11 > .satellite > button × n                swatches, spread by Orbit
+ *   .orbit-0  > .satellite.at-center > .ok-cw-area     saturation (x) and brightness (y)
+ *
+ * The hue handle is one satellite on a ring whose --o-from is the hue, so
+ * Orbit places it. It is a form control (FormControl): `name`, `disabled`,
+ * form reset/restore; it submits the color as hex, rgb() or hsl() (`format`).
+ * Emits `input` while changing and `change` when a gesture commits.
+ */
+import { OrbitKitElement, FormControl, define, injectStyleOnce, universe, hub, fixed, escapeHTML as e, FORM_ATTRS, withShared } from './base.js';
+import { parseColor, rgbToHex, hsvToRgb, rgbToHsv, colorName, formatColor } from './color.js';
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const FORMATS = ['hex', 'rgb', 'hsl'];
+
+const CW_CSS = `
+o-color-wheel { -webkit-tap-highlight-color: transparent; }
+o-color-wheel :where(.satellite) { border: none; background: transparent; }
+o-color-wheel > .bigbang > .gravity-spot { font-size: var(--ok-font-size, 8cqmin); color: var(--ok-text, inherit); }
+o-color-wheel .ok-cw-ring {
+  width: 100%; aspect-ratio: 1; border-radius: 50%;
+  background: conic-gradient(#f00, #ff0, #0f0, #0ff, #00f, #f0f, #f00);
+  -webkit-mask: radial-gradient(closest-side, #0000 calc(var(--ok-cw-hole) - .5px), #000 var(--ok-cw-hole), #000 calc(100% - .75px), #0000 100%);
+  mask: radial-gradient(closest-side, #0000 calc(var(--ok-cw-hole) - .5px), #000 var(--ok-cw-hole), #000 calc(100% - .75px), #0000 100%);
+}
+o-color-wheel .ok-cw-area {
+  position: relative; width: 100%; aspect-ratio: 1; border-radius: var(--ok-cw-radius, .3em); touch-action: none;
+  background: linear-gradient(to top, #000, #0000), linear-gradient(to right, #fff, hsl(var(--ok-cw-hue, 0) 100% 50%));
+  box-shadow: inset 0 0 0 1px rgba(255,255,255,.08);
+}
+o-color-wheel .ok-cw-thumb {
+  box-sizing: border-box; display: block; border-radius: 50%; background: var(--ok-cw-color, #fff);
+  border: .1em solid var(--ok-cw-thumb-border, #fff); box-shadow: 0 0 0 1px rgba(0,0,0,.35), 0 .05em .25em rgba(0,0,0,.45);
+  outline: none; cursor: grab; touch-action: none;
+}
+o-color-wheel .ok-cw-hue-thumb { width: 100%; aspect-ratio: 1; }
+o-color-wheel .ok-cw-area-thumb { position: absolute; width: .82em; aspect-ratio: 1; translate: -50% -50%; }
+o-color-wheel .ok-cw-thumb:focus-visible,
+o-color-wheel .ok-cw-swatch:focus-visible { outline: 2px solid var(--ok-focus, #3da9fc); outline-offset: 2px; }
+o-color-wheel .ok-cw-swatch {
+  font: inherit; display: block; width: 100%; aspect-ratio: 1; padding: 0; margin: 0; border-radius: 50%; cursor: pointer;
+  background: var(--ok-cw-swatch); border: .07em solid var(--ok-cw-swatch-border, rgba(255,255,255,.14));
+  transition: scale .15s;
+}
+o-color-wheel .ok-cw-swatch:hover { scale: 1.12; background: var(--ok-cw-swatch); }
+o-color-wheel .ok-cw-swatch[aria-pressed="true"] { border-color: var(--ok-cw-thumb-border, #fff); box-shadow: 0 0 0 .07em rgba(0,0,0,.4); }
+o-color-wheel[data-disabled] > .bigbang { opacity: .5; }
+o-color-wheel[data-disabled] :is(.ok-cw-thumb, .ok-cw-swatch) { cursor: default; }
+@media (prefers-reduced-motion: reduce) { o-color-wheel .ok-cw-swatch { transition: none; } }
+`;
+
+/** "#1e90ff" for any parsable color, else null. */
+export const toHex = (value) => { const rgb = parseColor(value); return rgb ? rgbToHex(rgb) : null; };
+
+export class OrbitColorWheel extends FormControl(OrbitKitElement) {
+  static get observedAttributes() {
+    return withShared(['value', 'size', 'format', 'swatches', 'label', 'thickness'], FORM_ATTRS);
+  }
+
+  constructor() {
+    super();
+    for (const name of ['_onDown', '_onMove', '_onUp', '_onKey']) this[name] = this[name].bind(this);
+  }
+
+  readConfig() {
+    const swatches = (Array.isArray(this._json('swatches', [])) ? this._json('swatches', []) : []).slice(0, 36).map((s) => {
+      const item = typeof s === 'string' ? { color: s } : (s && typeof s === 'object' ? s : {});
+      const hex = toHex(item.color);
+      return hex ? { hex, label: item.label == null ? null : String(item.label) } : null;
+    }).filter(Boolean);
+    const format = this._str('format', 'hex');
+    const band = clamp(this._num('thickness', swatches.length ? 1.7 : 1.9), .8, 3);
+    const outer = swatches.length ? 9.6 : 11.6;
+    return {
+      size: this._size('size', '240px'), swatches, format: FORMATS.includes(format) ? format : 'hex',
+      label: this._str('label', 'Color picker'), disabled: this._isDisabled(),
+      outer, band, center: outer - band / 2,
+      // The square fits inside the hole with a little air.
+      half: (outer - band - .6) / Math.SQRT2,
+      value: toHex(this.getAttribute('value')) || '#4fd1c5'
+    };
+  }
+
+  structuralSignature({ value, label, disabled, format, ...rest }) { return JSON.stringify(rest); }
+
+  build(cfg) {
+    injectStyleOnce('orbit-kit-color-wheel', CW_CSS);
+    const hole = fixed((cfg.outer - cfg.band) / cfg.outer * 100, 2);
+    const sw = cfg.swatches.length ? Math.min(1.7, 2 * Math.PI * 11 / cfg.swatches.length * .62) : 0;
+    const swatches = cfg.swatches.length ? `<div class="orbit-11 ok-cw-swatches" role="group" aria-label="Swatches" style="--o-size-ratio:${fixed(sw)}">${cfg.swatches.map((s, i) => {
+      const name = s.label ?? colorName(s.hex);
+      return `<div class="satellite"><div class="capsule"><button type="button" class="ok-cw-swatch" data-index="${i}" data-hex="${s.hex}" tabindex="-1" aria-pressed="false" aria-label="${e(`${name}, ${s.hex}`)}" title="${e(name)}" style="--ok-cw-swatch:${s.hex}"></button></div></div>`;
+    }).join('')}</div>` : '';
+    this.innerHTML = universe(cfg.size, `
+      ${hub(2 * cfg.outer, `<div class="ok-cw-ring" aria-hidden="true" style="--ok-cw-hole:${hole}%"></div>`, 'ok-cw-ring-cap')}
+      <div class="orbit-12 ok-cw-hue-ring"><div class="satellite" style="--o-size-ratio:${fixed(cfg.band + .45)};--o-alignment:calc(var(--o-radius) / 12 * ${fixed(12 - cfg.center)})"><div class="capsule"><span class="ok-cw-thumb ok-cw-hue-thumb" role="slider" aria-label="Hue" aria-valuemin="0" aria-valuemax="359" data-part="hue"></span></div></div></div>
+      ${hub(2 * cfg.half, '<div class="ok-cw-area"><span class="ok-cw-thumb ok-cw-area-thumb" role="slider" aria-label="Saturation and brightness" aria-roledescription="2D slider" aria-valuemin="0" aria-valuemax="100" data-part="area"></span></div>', 'ok-cw-area-cap')}
+      ${swatches}`);
+    this._box = this.querySelector('.bigbang');
+    this._hueRing = this.querySelector('.ok-cw-hue-ring');
+    this._hueThumb = this.querySelector('.ok-cw-hue-thumb');
+    this._area = this.querySelector('.ok-cw-area');
+    this._areaThumb = this.querySelector('.ok-cw-area-thumb');
+    this._swatches = [...this.querySelectorAll('.ok-cw-swatch')];
+    this._painted = null;
+  }
+
+  sync(cfg) {
+    this._cfg = cfg;
+    // A new value attribute moves the picker; the hue survives grays and black.
+    if (!this._hsv || cfg.value !== rgbToHex(hsvToRgb(this._hsv))) this._hsv = this._adopt(cfg.value);
+    this._describe(cfg.label, 'group');
+    for (const thumb of [this._hueThumb, this._areaThumb]) if (thumb) thumb.tabIndex = cfg.disabled ? -1 : 0;
+    this._roving(this._swatches.find((s) => s.tabIndex === 0) || this._swatches[0], cfg.disabled);
+    this.style.touchAction = cfg.disabled ? 'auto' : 'none';
+    if (cfg.disabled) this._stopDrag();
+    this._paint();
+  }
+
+  /** HSV for a hex, keeping the current hue (and saturation) where the hex has none. */
+  _adopt(hex) {
+    const next = rgbToHsv(parseColor(hex) || { r: 0, g: 0, b: 0 });
+    const prev = this._hsv;
+    if (prev && (next.s === 0 || next.v === 0)) next.h = prev.h;
+    if (prev && next.v === 0) next.s = prev.s;
+    return next;
+  }
+
+  _paint() {
+    const { h, s, v } = this._hsv;
+    const rgb = hsvToRgb(this._hsv);
+    const hex = rgbToHex(rgb);
+    const key = `${fixed(h, 2)}|${fixed(s, 4)}|${fixed(v, 4)}`;
+    if (key === this._painted) return;
+    this._painted = key;
+    const name = colorName(rgb);
+    if (this._hueRing) this._hueRing.style.setProperty('--o-from', `${fixed(h, 2)}deg`);
+    if (this._hueThumb) {
+      this._hueThumb.style.setProperty('--ok-cw-color', `hsl(${fixed(h, 2)} 100% 50%)`);
+      this._hueThumb.setAttribute('aria-valuenow', String(Math.round(h) % 360));
+      this._hueThumb.setAttribute('aria-valuetext', `${Math.round(h) % 360} degrees, ${colorName(hsvToRgb({ h, s: 1, v: 1 }))}`);
+    }
+    if (this._area) this._area.style.setProperty('--ok-cw-hue', fixed(h, 2));
+    if (this._areaThumb) {
+      this._areaThumb.style.left = `${fixed(s * 100, 2)}%`;
+      this._areaThumb.style.top = `${fixed((1 - v) * 100, 2)}%`;
+      this._areaThumb.style.setProperty('--ok-cw-color', hex);
+      this._areaThumb.setAttribute('aria-valuenow', String(Math.round(s * 100)));
+      this._areaThumb.setAttribute('aria-valuetext', `Saturation ${Math.round(s * 100)}%, brightness ${Math.round(v * 100)}%, ${name}, ${hex}`);
+    }
+    for (const sw of this._swatches) sw.setAttribute('aria-pressed', String(sw.dataset.hex === hex));
+  }
+
+  get value() { return this._hsv ? rgbToHex(hsvToRgb(this._hsv)) : this.readConfig().value; }
+  /** Any CSS color; it is stored as hex. Setting it fires no event. */
+  set value(color) {
+    const hex = toHex(color);
+    if (!hex) return;
+    if (!this.isConnected) { this.setAttribute('value', hex); return; }
+    this._hsv = this._adopt(hex);
+    this._reflectValue(hex);
+    this._paint();
+    this._updateForm();
+  }
+  get rgb() { return formatColor(parseColor(this.value), 'rgb'); }
+  get hsl() { return formatColor(parseColor(this.value), 'hsl'); }
+  /** A plain-English name of the color, like "dark blue". */
+  get colorName() { return colorName(this.value); }
+
+  _formValue() {
+    const format = this.getAttribute('format');
+    return formatColor(parseColor(this.value), FORMATS.includes(format) ? format : 'hex');
+  }
+
+  _formAnchor() { return this._areaThumb || undefined; }
+
+  onConnected() {
+    this.addEventListener('pointerdown', this._onDown);
+    this.addEventListener('lostpointercapture', this._onUp);
+    this.addEventListener('keydown', this._onKey);
+    this.addEventListener('click', this._onSwatch);
+  }
+
+  onDisconnected() {
+    this.removeEventListener('pointerdown', this._onDown);
+    this.removeEventListener('lostpointercapture', this._onUp);
+    this.removeEventListener('keydown', this._onKey);
+    this.removeEventListener('click', this._onSwatch);
+    this._stopDrag();
+  }
+
+  /** Set the color from a gesture: `input` on each change, `change` with { change: true }. */
+  _commit(hsv, { change = false } = {}) {
+    const before = this.value;
+    this._hsv = { h: ((hsv.h % 360) + 360) % 360, s: clamp(hsv.s, 0, 1), v: clamp(hsv.v, 0, 1) };
+    const hex = this.value;
+    this._reflectValue(hex);
+    this._paint();
+    this._updateForm();
+    if (hex !== before) {
+      this._emit('input');
+      if (change) this._emit('change');
+    }
+  }
+
+  _emit(type) {
+    const rgb = parseColor(this.value);
+    this._emitValue(type, this.value, { rgb: formatColor(rgb, 'rgb'), hsl: formatColor(rgb, 'hsl'), name: colorName(rgb) });
+  }
+
+  /** Where a pointer is, in lanes from the center (a lane is a twelfth of the radius). */
+  _lanes(event) {
+    const r = this._box?.getBoundingClientRect?.();
+    if (!r?.width) return null;
+    const lane = Math.min(r.width, r.height) / 24;
+    return { x: (event.clientX - (r.left + r.width / 2)) / lane, y: (event.clientY - (r.top + r.height / 2)) / lane };
+  }
+
+  _onDown(event) {
+    if (this._isDisabled() || event.button !== 0 || this._pointerId != null || event.target?.closest?.('.ok-cw-swatch')) return;
+    const p = this._lanes(event);
+    const cfg = this._cfg;
+    if (!p || !cfg) return;
+    const d = Math.hypot(p.x, p.y);
+    if (d >= cfg.outer - cfg.band - .5 && d <= cfg.outer + .5) this._mode = 'hue';
+    else if (Math.abs(p.x) <= cfg.half + .5 && Math.abs(p.y) <= cfg.half + .5) this._mode = 'area';
+    else return;
+    event.preventDefault();
+    (this._mode === 'hue' ? this._hueThumb : this._areaThumb)?.focus({ preventScroll: true });
+    this._pointerId = event.pointerId;
+    this._startValue = this.value;
+    this.setPointerCapture?.(event.pointerId);
+    window.addEventListener('pointermove', this._onMove);
+    window.addEventListener('pointerup', this._onUp);
+    window.addEventListener('pointercancel', this._onUp);
+    this._move(p);
+  }
+
+  _onMove(event) {
+    if (event.pointerId !== this._pointerId || this._isDisabled()) return;
+    const p = this._lanes(event);
+    if (p) this._move(p);
+  }
+
+  _move(p) {
+    const { half } = this._cfg;
+    if (this._mode === 'hue') this._commit({ ...this._hsv, h: Math.atan2(p.x, -p.y) * 180 / Math.PI });
+    else this._commit({ ...this._hsv, s: (p.x + half) / (2 * half), v: (half - p.y) / (2 * half) });
+  }
+
+  _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);
+    window.removeEventListener('pointercancel', this._onUp);
+  }
+
+  _onUp(event) {
+    if (event.pointerId !== this._pointerId) return;
+    const changed = this.value !== this._startValue;
+    this._stopDrag();
+    if (changed && !this._isDisabled()) this._emit('change');
+  }
+
+  _onSwatch = (event) => {
+    const sw = event.target?.closest?.('.ok-cw-swatch');
+    if (!sw || this._isDisabled()) return;
+    this._roving(sw);
+    this._commit(rgbToHsv(parseColor(sw.dataset.hex)), { change: true });
+  };
+
+  _roving(active, disabled = this._isDisabled()) {
+    for (const sw of this._swatches || []) sw.tabIndex = !disabled && sw === active ? 0 : -1;
+  }
+
+  _onKey(event) {
+    if (this._isDisabled()) return;
+    const part = event.target?.dataset?.part;
+    const big = event.shiftKey ? 10 : 1;
+    const { h, s, v } = this._hsv;
+    let next = null;
+    if (event.target?.classList?.contains('ok-cw-swatch')) {
+      const i = this._swatches.indexOf(event.target), n = this._swatches.length;
+      const to = { ArrowRight: i + 1, ArrowDown: i + 1, ArrowLeft: i - 1, ArrowUp: i - 1, Home: 0, End: n - 1 }[event.key];
+      if (to == null) return;
+      event.preventDefault();
+      const sw = this._swatches[(to + n) % n];
+      this._roving(sw);
+      sw.focus();
+      return;
+    }
+    if (part === 'hue') {
+      const moves = { ArrowRight: 1, ArrowUp: 1, ArrowLeft: -1, ArrowDown: -1, PageUp: 10, PageDown: -10 };
+      if (Object.hasOwn(moves, event.key)) next = { h: (Math.round(h) + moves[event.key] * (event.key.startsWith('Page') ? 1 : big) + 360) % 360, s, v };
+      else if (event.key === 'Home') next = { h: 0, s, v };
+      else if (event.key === 'End') next = { h: 359, s, v };
+    } else if (part === 'area') {
+      const step = big / 100;
+      const r = (n) => Math.round(n * 100) / 100;
+      if (event.key === 'ArrowRight') next = { h, s: r(s) + step, v };
+      else if (event.key === 'ArrowLeft') next = { h, s: r(s) - step, v };
+      else if (event.key === 'ArrowUp') next = { h, s, v: r(v) + step };
+      else if (event.key === 'ArrowDown') next = { h, s, v: r(v) - step };
+      else if (event.key === 'PageUp') next = { h, s, v: r(v) + .1 };
+      else if (event.key === 'PageDown') next = { h, s, v: r(v) - .1 };
+      else if (event.key === 'Home') next = { h, s: 0, v };
+      else if (event.key === 'End') next = { h, s: 1, v };
+    }
+    if (!next) return;
+    event.preventDefault();
+    this._commit(next, { change: true });
+  }
+}
+
+define('o-color-wheel', OrbitColorWheel);

package/src/o-compass.js

@@ -1,41 +1,42 @@
 /**
  * <o-compass> — heading indicator.
  *
- * A fixed dial with a red lubber index at the top; the compass card (36 ticks
- * + cardinal letters) rotates so the current `heading` sits under the index —
- * the way an aircraft heading indicator reads. Cardinal letters stay upright
- * (`spin-lock`). Rotating the card is done through Orbit's own `--o-from`, so
- * changing `heading` only re-rotates (no rebuild).
+ * A fixed dial with a lubber index at the top; the compass card (36 ticks and
+ * the cardinal letters) turns so the current `heading` sits under the index,
+ * the way an aircraft heading indicator reads. Turning the card is Orbit's own
+ * `--o-from` on its rings, so changing `heading` only re-rotates. Capsules
+ * stay upright on their own.
  *
  *   .bigbang > .gravity-spot
- *     ├── .orbit-6 (filled)              — dial face + bezel
- *     ├── .orbit-6 (rotates) > .vector × 36   — tick scale
- *     ├── .orbit-5 (rotates) > .satellite × cardinals (spin-lock)
- *     ├── .orbit-6 > .satellite.angle-0 > lubber index (fixed)
- *     └── .orbit-0 > heading readout
+ *     ├── .orbit-12 (filled)                     dial face + bezel
+ *     ├── .orbit-12 (turns) > .vector × 36       tick scale
+ *     ├── .orbit-10 (turns) > .satellite × n     cardinals
+ *     ├── .orbit-12 > .satellite.angle-0         lubber index (fixed)
+ *     └── .orbit-0  > heading readout
  *
  *   <o-compass heading="45"></o-compass>
  *   <o-compass heading="120" labels="N,NE,E,SE,S,SW,W,NW"></o-compass>
  */
-import { OrbitKitElement, define, injectStyleOnce } from './base.js';
+import { OrbitKitElement, define, injectStyleOnce, universe, escapeHTML as e, withShared, FORMAT_ATTRS } from './base.js';
 
 const CMP_CSS = `
+o-compass { --ok-font-size: 7cqmin; }
 o-compass .ok-cmp-dial {
-  background: var(--ok-cmp-face, radial-gradient(circle at 50% 35%, #1b212b, #0a0d12));
-  box-shadow: inset 0 0 0 4px var(--ok-cmp-bezel, #2a3340), inset 0 4px 18px rgba(0,0,0,.65);
+  background: var(--ok-cmp-face, var(--ok-face, radial-gradient(circle at 50% 35%, #1b212b, #0a0d12)));
+  box-shadow: inset 0 0 0 4px var(--ok-cmp-bezel, var(--ok-bezel, #2a3340)), inset 0 4px 18px rgba(0,0,0,.65);
 }
-o-compass .ok-cmp-rotor { transition: transform .3s ease; }
-o-compass .ok-cmp-tick   { background: var(--ok-cmp-tick, rgba(203,213,225,.4)); height: 1px; }
-o-compass .ok-cmp-tick-M { background: #e6edf3; height: 2px; border-radius: 1px; }
-o-compass .ok-cmp-card   { font-weight: 800; color: #e6edf3; }
-o-compass .ok-cmp-card.north { color: var(--ok-cmp-accent, #ef4444); }
+o-compass .ok-cmp-tick   { background: var(--ok-cmp-tick, var(--ok-tick, rgba(203,213,225,.4))); height: 1px; }
+o-compass .ok-cmp-tick-M { background: var(--ok-cmp-tick-M, var(--ok-hand, #e6edf3)); height: max(2px, .9cqmin); border-radius: 1px; }
+o-compass .ok-cmp-card   { font-weight: 800; color: var(--ok-cmp-text, var(--ok-text, #e6edf3)); }
+o-compass .ok-cmp-card.north { color: var(--ok-cmp-accent, var(--ok-accent, #ef4444)); }
 o-compass .ok-cmp-lubber {
-  width: 0; height: 0; border-left: 7px solid transparent; border-right: 7px solid transparent;
-  border-top: 12px solid var(--ok-cmp-accent, #ef4444);
+  filter: drop-shadow(0 0 var(--ok-cmp-glow, 0px) var(--ok-cmp-accent, var(--ok-accent, #ef4444)));
+  width: 0; height: 0; border-left: .45em solid transparent; border-right: .45em solid transparent;
+  border-top: .8em solid var(--ok-cmp-accent, var(--ok-accent, #ef4444)); translate: 0 40%;
 }
 o-compass .ok-cmp-readout { display: flex; flex-direction: column; align-items: center; line-height: 1.05; }
-o-compass .ok-cmp-deg { font-weight: 800; font-size: 1.5em; font-variant-numeric: tabular-nums; color: #f8fafc; }
-o-compass .ok-cmp-sub { font-size: .6em; letter-spacing: .15em; opacity: .6; }
+o-compass .ok-cmp-deg { font-weight: 800; font-size: 1.5em; font-variant-numeric: tabular-nums; color: var(--ok-cmp-text, var(--ok-text, #f8fafc)); }
+o-compass .ok-cmp-sub { font-size: .65em; opacity: .6; }
 `;
 
 // Compass point abbreviations for the heading readout.
@@ -43,7 +44,7 @@ const POINTS = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'];
 
 export class OrbitCompass extends OrbitKitElement {
   static get observedAttributes() {
-    return ['heading', 'size', 'labels', 'fill', 'unit', 'glow'];
+    return withShared(['heading', 'size', 'labels', 'fill', 'accent', 'glow'], FORMAT_ATTRS);
   }
 
   readConfig() {
@@ -51,50 +52,41 @@ export class OrbitCompass extends OrbitKitElement {
     return {
       heading: ((this._num('heading', 0) % 360) + 360) % 360,
       labels,
-      size: this._str('size', '220px'),
-      fill: this._str('fill', '#ef4444'),
-      unit: this._str('unit', '°'),
-      glow: this.hasAttribute('glow')
+      size: this._size('size', '220px'),
+      fill: this._color('accent', this._color('fill', null)),
+      unit: this._unitText('°'),
+      glow: this.getAttribute('glow')
     };
   }
 
   structuralSignature(cfg) {
-    const { heading, ...rest } = cfg;
+    const { heading, unit, fill, ...rest } = cfg;
     return JSON.stringify(rest);
   }
 
   build(cfg) {
     injectStyleOnce('orbit-kit-compass', CMP_CSS);
-    this.style.setProperty('--ok-cmp-accent', cfg.fill);
-
-    // orbit-6 is the outermost ring; scale --o-force so it fills `size`.
-    const dialPx = parseFloat(cfg.size) || 220;
-    const force = (dialPx * 12 / 6).toFixed(1);
-    const baseFont = (dialPx * 0.07).toFixed(1);
+    this._applyTheme({ '--ok-cmp-glow': cfg.glow == null ? null : `${Math.max(0, this._num('glow', 6))}px` });
 
     // 36 ticks every 10°; every 9th (90°) is a long cardinal tick.
     const ticks = Array.from({ length: 36 }, (_, i) =>
-      `<div class="vector inner-orbit ${i % 9 === 0 ? 'shrink-30 ok-cmp-tick-M' : 'shrink-60 ok-cmp-tick'}"></div>`).join('');
+      `<div class="vector inner-orbit ${i % 9 === 0 ? 'ok-cmp-tick-M" style="--o-size-ratio:1.5' : 'ok-cmp-tick" style="--o-size-ratio:.8'}"></div>`).join('');
 
     // Cardinals distributed by count (NO fit-range — that overlaps on a 360 loop).
     // Plain satellites (NOT spin-lock): the capsule stays upright by default
     // while the ring's --o-from rotates only their POSITION. spin-lock would
     // over-rotate the letters once we drive --o-from for the heading.
     const cards = cfg.labels.map((l, i) =>
-      `<div class="satellite"><div class="capsule ok-cmp-card${i === 0 ? ' north' : ''}">${l}</div></div>`).join('');
+      `<div class="satellite"><div class="capsule ok-cmp-card${i === 0 ? ' north' : ''}">${e(l)}</div></div>`).join('');
 
-    this.innerHTML = `
-      <div class="bigbang" style="width:${cfg.size};aspect-ratio:1;font-size:${baseFont}px;">
-        <div class="gravity-spot" style="--o-force:${force}px;">
-          <div class="orbit-6 ok-cmp-dial"></div>
-          <div class="orbit-6 ok-cmp-rotor o-cmp-ticks" style="--o-from:0deg;">${ticks}</div>
-          <div class="orbit-5 ok-cmp-rotor o-cmp-cards" style="--o-from:0deg;">${cards}</div>
-          <div class="orbit-6"><div class="satellite angle-0"><div class="capsule ok-cmp-lubber"></div></div></div>
-          <div class="orbit-0"><div class="satellite at-center"><div class="capsule ok-cmp-readout">
-            <span class="ok-cmp-deg"></span><span class="ok-cmp-sub"></span>
-          </div></div></div>
-        </div>
-      </div>`;
+    this.innerHTML = universe(cfg.size, `
+      <div class="orbit-12 ok-cmp-dial ok-surface"></div>
+      <div class="orbit-12 ok-cmp-rotor o-cmp-ticks" style="--o-from:0deg">${ticks}</div>
+      <div class="orbit-10 ok-cmp-rotor o-cmp-cards" style="--o-from:0deg">${cards}</div>
+      <div class="orbit-12"><div class="satellite angle-0"><div class="capsule ok-cmp-lubber"></div></div></div>
+      <div class="orbit-0"><div class="satellite at-center"><div class="capsule ok-cmp-readout">
+        <span class="ok-cmp-deg"></span><span class="ok-cmp-sub"></span>
+      </div></div></div>`);
 
     this._ticks = this.querySelector('.o-cmp-ticks');
     this._cards = this.querySelector('.o-cmp-cards');
@@ -107,8 +99,12 @@ export class OrbitCompass extends OrbitKitElement {
     const rot = `${-cfg.heading}deg`;
     if (this._ticks) this._ticks.style.setProperty('--o-from', rot);
     if (this._cards) this._cards.style.setProperty('--o-from', rot);
-    if (this._deg) this._deg.textContent = `${String(Math.round(cfg.heading)).padStart(3, '0')}${cfg.unit}`;
+    const range = { min: 0, max: 360 };
+    const degrees = (h) => String(Math.round(h) % 360).padStart(3, '0');
+    if (this._deg) this._deg.textContent = this._formatText(cfg.heading, { ...range, fallback: degrees }, cfg.unit);
     if (this._sub) this._sub.textContent = POINTS[Math.round(cfg.heading / 45) % 8];
+    this._describe(`Heading ${this._formatText(cfg.heading, { ...range, kind: 'aria', fallback: (h) => String(Math.round(h) % 360) }, cfg.unit)}, ${POINTS[Math.round(cfg.heading / 45) % 8]}`);
+    this._applyTheme({ '--ok-cmp-accent': cfg.fill });
   }
 }
 

package/src/o-donut.js

@@ -1,100 +1,88 @@
+import { OrbitKitElement, define, injectStyleOnce, universe, hub, fixed, finiteNumber, cssValue, escapeHTML as e, withShared, FORMAT_ATTRS } from './base.js';
+
+const PALETTE = ['#6366f1', '#22c55e', '#eab308', '#f97316', '#ef4444', '#06b6d4', '#a855f7', '#ec4899'];
+
 /**
- * <o-donut> — data-driven donut / pie chart.
- *
- * Collapses the Orbit recipe:
- *
- *   .bigbang > .gravity-spot
- *     ├── .orbit-N > <o-arc> × segments   (each arc stacks onto the previous)
- *     └── .orbit-0 > .satellite.at-center > .capsule   (center label)
+ * <o-donut>: a donut chart from a JSON array. Segments are sibling <o-arc>s
+ * with a `value`, so Orbit stacks them one after another around one ring.
  *
- * ...into one tag fed by a JSON array:
- *
- *   <o-donut data='[{"value":52,"color":"#f97316","label":"Rent"},
- *                   {"value":28,"color":"#eab308"},
- *                   {"value":20,"color":"#22c55e"}]'
- *            label="$2.4k" unit=""></o-donut>
- *
- * Segments are normalized to the sum of their values (so they fill the ring),
- * unless `total` is given — then values are taken as a fraction of `total`,
- * leaving an empty remainder (partial donut).
+ *   .orbit-12 > o-arc                    track
+ *   .orbit-12 > o-arc[value] × n         segments (stacked by Orbit)
+ *   .orbit-0  > .satellite.at-center     label
  */
-import { OrbitKitElement, define } from './base.js';
-
 export class OrbitDonut extends OrbitKitElement {
   static get observedAttributes() {
-    return ['data', 'size', 'orbit', 'stroke-width', 'gap', 'track',
-            'range', 'from', 'label', 'unit', 'total', 'glow'];
+    return withShared(['data', 'size', 'orbit', 'thickness', 'stroke-width', 'gap', 'track', 'range', 'from', 'label', 'total', 'shape', 'glow'], FORMAT_ATTRS);
   }
 
   readConfig() {
-    const range = this._num('range', 360);
-    const data = (this._json('data', []) || []).map((d) => ({
-      value: Number(d.value) || 0,
-      color: d.color || null,
-      label: d.label != null ? String(d.label) : null
+    const data = this._array('data').map((d, i) => ({
+      value: Math.max(0, finiteNumber(d.value)), color: cssValue(d.color, PALETTE[i % PALETTE.length]),
+      label: d.label == null ? null : String(d.label)
     }));
-    const sum = data.reduce((a, d) => a + d.value, 0) || 1;
-    const total = this._num('total', sum);
+    // Normalize through a scaled sum to avoid overflow on large finite values.
+    const largest = data.reduce((n, d) => Math.max(n, d.value), 1);
+    const sum = data.reduce((n, d) => n + d.value / largest, 0) * largest;
+    const requestedTotal = this._num('total', sum);
+    const total = requestedTotal > 0 ? requestedTotal : (sum || 1);
+    let remaining = 100;
+    const weightSum = data.reduce((n, d) => n + d.value / largest, 0) || 1;
+    for (const d of data) {
+      const pct = Number.isFinite(total) ? d.value / total * 100 : (d.value / largest) / weightSum * 100;
+      d.pct = Math.max(0, Math.min(remaining, pct));
+      remaining = Math.max(0, remaining - d.pct);
+    }
     return {
-      data,
-      total,
-      range,
-      from: this.hasAttribute('from') ? this._num('from', 0) : 0,
-      orbit: Math.round(this._num('orbit', 3)),
-      size: this._str('size', '200px'),
-      strokeWidth: this._num('stroke-width', 14),
-      gap: this._num('gap', 2),
-      shape: this._str('shape', 'none'),
-      track: this._str('track', 'rgba(255,255,255,.05)'),
-      unit: this._str('unit', ''),
-      glow: this.getAttribute('glow'),
-      label: this.hasAttribute('label') ? this.getAttribute('label') : null
+      data, total, range: Math.max(0, Math.min(360, this._num('range', 360))), from: this._num('from', 0),
+      thickness: this._thickness(3), size: this._size('size', '200px'),
+      strokeWidth: Math.max(0, this._num('stroke-width', 0)), gap: this._gap(1.5),
+      shape: this._str('shape', 'none'), track: this._color('track', null),
+      unit: this._unitText(), glow: this.hasAttribute('glow') ? this._glowPx() : null, label: this.getAttribute('label')
     };
   }
 
-  structuralSignature(cfg) {
-    // Re-render the whole subtree whenever the data or geometry changes;
-    // segment count and arc values are all structural here.
-    return JSON.stringify(cfg);
+  /** A segment value as text; "percent" is its share of the total. */
+  _segmentText(cfg, d, i) {
+    return `${d.label ?? `Segment ${i + 1}`}: ${this._formatText(d.value, { min: 0, max: cfg.total })}`;
   }
 
-  build(cfg) {
-    const palette = ['#6366f1', '#22c55e', '#eab308', '#f97316', '#ef4444',
-                     '#06b6d4', '#a855f7', '#ec4899'];
-
-    const segments = cfg.data.map((d, i) => {
-      const pct = (d.value / cfg.total) * 100;
-      const color = d.color || palette[i % palette.length];
-      const style = [
-        `--o-fill:${color}`,
-        `--o-stroke:${color}`,
-        `--o-stroke-width:${cfg.strokeWidth}`,
-        `--o-gap:${cfg.gap}`,
-        this._glow(color)
-      ].join(';');
-      const title = d.label ? ` title="${d.label}: ${d.value}"` : '';
-      return `<o-arc value="${pct.toFixed(4)}" shape="${cfg.shape}" style="${style}"${title}></o-arc>`;
-    }).join('');
-
-    // Faint full-circle track underneath the segments (rounded to match).
-    const track = cfg.track && cfg.track !== 'transparent'
-      ? `<o-arc value="100" style="--o-fill:${cfg.track};--o-stroke:${cfg.track};--o-stroke-width:${cfg.strokeWidth}"></o-arc>`
-      : '';
+  structuralSignature({ data, total, label, unit, track, ...structure }) {
+    return JSON.stringify({ ...structure, count: data.length });
+  }
 
-    const center = cfg.label !== null
-      ? `<div class="orbit-0"><div class="satellite at-center"><div class="capsule ok-hub">${cfg.label}${cfg.unit}</div></div></div>`
-      : '';
+  build(cfg) {
+    const ring = `--o-range:${cfg.range}deg;--o-from:${cfg.from}deg;--o-size-ratio:${fixed(cfg.thickness)};`;
+    const stroke = cfg.strokeWidth ? `--o-stroke-width:${cfg.strokeWidth};` : '';
+    const segments = cfg.data.map((d, i) =>
+      `<o-arc class="inner-orbit ok-donut-segment" value="${d.pct.toFixed(4)}" shape="${e(cfg.shape)}" style="${e(`--o-fill:${d.color};${stroke}${cfg.glow == null ? '' : `filter:drop-shadow(0 0 ${cfg.glow}px ${d.color});`}`)}" title="${e(this._segmentText(cfg, d, i))}"></o-arc>`).join('');
+    this.innerHTML = universe(cfg.size, `
+      <div class="orbit-12" style="${ring}--o-gap:0"><o-arc class="inner-orbit ok-track" value="100"></o-arc></div>
+      <div class="orbit-12" style="${ring}--o-gap:${fixed(cfg.gap * 6)}">${segments}</div>
+      ${hub(2 * (12 - cfg.thickness) - 1, `${e(cfg.label ?? '')}${cfg.label == null ? '' : e(cfg.unit)}`)}`);
+    this._segments = [...this.querySelectorAll('.ok-donut-segment')];
+    this._center = this.querySelector('.ok-hub');
+  }
 
-    this.innerHTML = `
-      <div class="bigbang" style="width:${cfg.size};aspect-ratio:1;">
-        <div class="gravity-spot">
-          <div class="orbit-${cfg.orbit}" style="--o-range:${cfg.range}deg;--o-from:${cfg.from}deg;">
-            ${track}${segments}
-          </div>
-          ${center}
-        </div>
-      </div>`;
+  sync(cfg) {
+    this._applyTheme({ '--ok-track': cfg.track });
+    this._segments?.forEach((arc, i) => {
+      const d = cfg.data[i];
+      arc.setAttribute('value', d.pct.toFixed(4));
+      arc.setAttribute('title', this._segmentText(cfg, d, i));
+      arc.style.setProperty('--o-fill', d.color);
+      if (cfg.glow != null) arc.style.setProperty('filter', `drop-shadow(0 0 ${cfg.glow}px ${d.color})`);
+      else arc.style.removeProperty?.('filter');
+    });
+    if (this._center) {
+      this._center.textContent = cfg.label == null ? '' : `${cfg.label}${cfg.unit}`;
+      this._center.hidden = cfg.label == null;
+    }
+    this._describe([cfg.label == null ? null : `${cfg.label}${cfg.unit}`, ...cfg.data.map((d, i) => this._segmentText(cfg, d, i))].filter(Boolean).join('; ') || 'Empty donut chart');
   }
 }
 
+injectStyleOnce('orbit-kit-donut', `
+o-donut .ok-track { --o-fill: var(--ok-track, rgba(127,127,127,.12)); --o-stroke: var(--o-fill); }
+o-donut .ok-donut-segment { --o-stroke: var(--o-fill); }
+`);
 define('o-donut', OrbitDonut);