@zumer/orbit-kit 0.1.0 → 2.0.0

package/src/o-gauge.js

@@ -1,135 +1,69 @@
+import { OrbitKitElement, define, injectStyleOnce, universe, hub, fixed, escapeHTML as e, withShared, RANGE_ATTRS, FORMAT_ATTRS } from './base.js';
+
 /**
- * <o-gauge> — high-level gauge component for Orbit.
- *
- * Collapses the canonical Orbit gauge recipe:
- *
- *   .bigbang > .gravity-spot
- *     ├── .orbit-N (range/from) > <o-progress>
- *     └── .orbit-0 > .satellite.at-center > .capsule   (center label)
- *
- * ...into a single declarative tag:
- *
- *   <o-gauge value="72" unit="%"></o-gauge>
+ * <o-gauge>: one value on an arc, with a readout in the middle.
  *
- * Design note — LIGHT DOM on purpose:
- * Orbit positions elements through global CSS (cos()/sin()/:has()) and reads
- * inherited --o-* custom properties. A layout-composing component must therefore
- * render into the light DOM so the global orbit.css applies and the inner
- * <o-progress> participates in the cascade normally. This also keeps "view
- * source" honest: the output is exactly the documented Orbit structure.
+ *   .bigbang (width = size)
+ *   └── .gravity-spot
+ *       ├── .orbit-12 > o-arc.inner-orbit     track (thickness lanes, flush with the edge)
+ *       ├── .orbit-12 > o-arc.inner-orbit     value
+ *       └── .orbit-0  > .satellite.at-center  readout
  *
- * Requires @zumer/orbit (CSS + JS) to be loaded on the page so that
- * <o-progress> is registered. orbit-kit declares it as a peer dependency.
+ * Value and label updates patch the existing arc; nothing is rebuilt.
  */
-// Side-effect import: injects the kit baseline (strips the default satellite
-// outline) so a standalone <o-gauge> looks right without the rest of the kit.
-import './base.js';
-
-export class OrbitGauge extends HTMLElement {
+export class OrbitGauge extends OrbitKitElement {
   static get observedAttributes() {
-    return [
-      'value', 'max', 'range', 'from', 'orbit', 'size',
-      'label', 'unit', 'fill', 'track', 'stroke-width', 'shape', 'glow'
-    ];
-  }
-
-  connectedCallback() {
-    this.render();
+    return withShared(['value', 'range', 'from', 'orbit', 'thickness', 'size', 'label', 'fill', 'track', 'stroke-width', 'shape', 'glow'], RANGE_ATTRS, FORMAT_ATTRS);
   }
 
-  attributeChangedCallback() {
-    if (this.isConnected) this.render();
-  }
-
-  /** Parse a numeric attribute with a fallback. */
-  _num(name, fallback) {
-    const raw = this.getAttribute(name);
-    if (raw === null || raw === '') return fallback;
-    const n = parseFloat(raw);
-    return Number.isFinite(n) ? n : fallback;
-  }
-
-  _readConfig() {
-    const range = this._num('range', 270);
+  readConfig() {
+    const range = Math.max(0, Math.min(360, this._num('range', 270)));
+    const { value, min, max, step, fraction } = this._range({ min: 0, max: 100, step: 0 });
     return {
-      value: this._num('value', 0),
-      max: this._num('max', 100),
-      range,
-      // Default `from` centers the arc's gap at the bottom (6 o'clock),
-      // matching the classic 3/4 gauge: range-270 -> from-225.
-      from: this.hasAttribute('from')
-        ? this._num('from', 0)
-        : ((360 - range / 2) % 360 + 360) % 360,
-      orbit: Math.round(this._num('orbit', 4)),
-      size: this.getAttribute('size') || '200px',
-      fill: this.getAttribute('fill') || '#6366f1',
-      track: this.getAttribute('track') || '#262d38',
-      strokeWidth: this._num('stroke-width', 8),
-      shape: this.getAttribute('shape') || 'rounded',
-      unit: this.getAttribute('unit') || '',
-      label: this.hasAttribute('label') ? this.getAttribute('label') : null
+      value, min, max, step, fraction, range,
+      from: this.hasAttribute('from') ? this._num('from', 0) : this._autoFrom(range),
+      thickness: this._thickness(2.4), size: this._size('size', '200px'),
+      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(), label: this.getAttribute('label'), glow: this.hasAttribute('glow') ? this._glowPx() : null
     };
   }
 
-  render() {
-    const cfg = this._readConfig();
-    // Only structural attributes require rebuilding the subtree; value/label
-    // changes (e.g. during animation) just patch the existing nodes, so the
-    // inner <o-progress> isn't torn down and recreated on every frame.
-    const sig = [
-      cfg.range, cfg.from, cfg.orbit, cfg.size,
-      cfg.fill, cfg.track, cfg.strokeWidth, cfg.shape,
-      this.getAttribute('glow')
-    ].join('|');
-
-    if (!this._built || this._sig !== sig) {
-      this._build(cfg);
-      this._sig = sig;
-      this._built = true;
-    }
-    this._sync(cfg);
-  }
-
-  _build(cfg) {
-    const glow = this.hasAttribute('glow')
-      ? `filter:drop-shadow(0 0 ${this._num('glow', 6) || 6}px ${cfg.fill});`
-      : '';
-    // Track + value as two stacked <o-arc>s (each in its own orbit so they
-    // don't chain): o-arc FILLS solid, unlike o-progress's back which only
-    // strokes a hollow outline (the ugly border + center seam).
-    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 fillStyle = `--o-fill:${cfg.fill};--o-stroke:${cfg.fill};--o-stroke-width:${cfg.strokeWidth};${glow}`;
-
-    this.innerHTML = `
-      <div class="bigbang" style="width:${cfg.size};aspect-ratio:1;">
-        <div class="gravity-spot">
-          <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-gauge-fill" value="0" shape="${cfg.shape}" style="${fillStyle}"></o-arc></div>
-          <div class="orbit-0">
-            <div class="satellite at-center">
-              <div class="capsule ok-hub"></div>
-            </div>
-          </div>
-        </div>
-      </div>`;
+  structuralSignature({ value, fraction, min, max, step, label, unit, fill, track, ...structure }) { return JSON.stringify(structure); }
+  // The 0.x helper names keep working.
+  _readConfig() { return this.readConfig(); }
+  render() { this._render(); }
 
+  build(cfg) {
+    const ring = `--o-range:${cfg.range}deg;--o-from:${cfg.from}deg;--o-size-ratio:${fixed(cfg.thickness)};--o-gap:0`;
+    // stroke-width (0.x): an outline in the band's own color, in px.
+    const stroke = cfg.strokeWidth ? `--o-stroke-width:${cfg.strokeWidth};` : '';
+    const glow = cfg.glow == null ? '' : `filter:drop-shadow(0 0 ${cfg.glow}px var(--ok-fill, #6366f1));`;
+    this.innerHTML = universe(cfg.size, `
+      <div class="orbit-12" style="${ring}"><o-arc class="inner-orbit ok-track" value="100" shape="${e(cfg.shape)}"${stroke ? ` style="${stroke}"` : ''}></o-arc></div>
+      <div class="orbit-12" style="${ring}"><o-arc class="inner-orbit ok-value o-gauge-fill" value="0" shape="${e(cfg.shape)}" ${stroke || glow ? ` style="${stroke}${glow}"` : ''}></o-arc></div>
+      ${hub(2 * (12 - cfg.thickness) - 1)}`);
     this._fill = this.querySelector('.o-gauge-fill');
-    this._center = this.querySelector('.capsule');
+    this._center = this.querySelector('.ok-hub');
   }
 
-  _sync(cfg) {
-    if (this._fill) {
-      const pct = Math.max(0, Math.min(100, (cfg.value / cfg.max) * 100));
-      this._fill.setAttribute('value', pct.toFixed(2));
-    }
-    if (this._center) {
-      this._center.textContent =
-        cfg.label !== null ? cfg.label : `${cfg.value}${cfg.unit}`;
-    }
+  sync(cfg) {
+    this._applyTheme({ '--ok-fill': cfg.fill, '--ok-track': cfg.track });
+    const range = { min: cfg.min, max: cfg.max };
+    const reading = this._formatText(cfg.value, range);
+    const text = cfg.label ?? reading;
+    this._fill?.setAttribute('value', (cfg.fraction * 100).toFixed(2));
+    if (this._center) this._center.textContent = text;
+    this._describe(`${text}; ${this._format(cfg.value, range)} of ${this._formatText(cfg.max, range)}`, 'meter');
+    this._ariaRange(cfg);
   }
+  _build(cfg) { this.build(cfg); }
+  _sync(cfg) { this.sync(cfg); }
 }
 
-if (typeof customElements !== 'undefined' && !customElements.get('o-gauge')) {
-  customElements.define('o-gauge', OrbitGauge);
-}
+const GAUGE_CSS = `
+o-gauge .ok-track { --o-fill: var(--ok-track, #262d38); --o-stroke: var(--o-fill); }
+o-gauge .ok-value { --o-fill: var(--ok-fill, #6366f1); --o-stroke: var(--o-fill); transition: filter .2s; }
+`;
+injectStyleOnce('orbit-kit-gauge', GAUGE_CSS);
+define('o-gauge', OrbitGauge);

package/src/o-instrument.js

@@ -3,16 +3,16 @@
  * preset-driven needle gauge for automotive, aviation and computer readouts.
  *
  * Anatomy (all in the light DOM, aligned in one --o-from/--o-range frame so
- * ticks, labels, color zones and the needle agree):
+ * ticks, labels, color zones and the needle agree). The dial is the universe:
  *
  *   case > .bigbang > .gravity-spot
- *     ├── full sweep:  .orbit-11 (filled)            — round dial face + bezel
- *     │   partial(≤180): .orbit-9 > <o-arc>          — track band (no round case)
- *     ├── .orbit-10 fit-range > .vector × minor ticks
- *     ├── .orbit-10 fit-range > .vector × major ticks
- *     ├── .orbit-9  (per zone, own --o-from) > <o-arc>— color/redline zones
- *     ├── .orbit-8  fit-range > .satellite × labels   — numeric scale
- *     ├── .orbit-0  > .vector needle (full length, rotates to value)
+ *     ├── full sweep:  .orbit-12 (filled)             dial face + bezel
+ *     │   partial(≤180): .orbit-11 > <o-arc>          track band (no round case)
+ *     ├── .orbit-11 fit-range > .vector × minor ticks
+ *     ├── .orbit-11 fit-range > .vector × major ticks
+ *     ├── .orbit-11 (per zone, own --o-from) > <o-arc> color/redline zones
+ *     ├── .orbit-9  fit-range > .satellite × labels   numeric scale
+ *     ├── .orbit-0  > .vector needle (rotates to value)
  *     └── .orbit-4  > readout (value + unit + caption)
  *
  *   <o-instrument preset="tachometer" value="6.2"></o-instrument>
@@ -25,80 +25,84 @@
  * visible, even at zero) — pointed by `--o-angle-composite`. Only `value` is
  * cheap to change; the dial rebuilds when the scale, zones, case or theme change.
  */
-import { OrbitKitElement, define, injectStyleOnce } from './base.js';
+import { OrbitKitElement, define, injectStyleOnce, finiteNumber, arrayData, cssValue, fixed, escapeHTML as e, withShared, RANGE_ATTRS, FORMAT_ATTRS } from './base.js';
 
-const RED = '#ef4444', YEL = '#eab308', GRN = '#22c55e', AMB = '#f59e0b', WHT = '#e5e7eb';
+// WHT follows the theme's strong color (--ok-hand), so a white needle stays visible on a light face.
+const RED = '#ef4444', YEL = '#eab308', GRN = '#22c55e', AMB = '#f59e0b', WHT = 'var(--ok-hand, #e5e7eb)';
 
 // Real instruments as preset bundles; any explicit attribute overrides them.
 const PRESETS = {
   tachometer:  { min: 0, max: 8, range: 270, ticks: 9, minor: 5, unit: '', label: 'RPM x1000',
                  zones: [{ from: 6.5, to: 8, color: RED }], value: 0.8, accent: RED },
-  speedometer: { min: 0, max: 240, range: 270, ticks: 9, minor: 2, unit: 'km/h', label: 'SPEED', value: 0, accent: WHT },
-  fuel:        { min: 0, max: 1, range: 90, from: 270, ticks: 3, minor: 4, unit: '', label: 'FUEL', digital: false,
+  speedometer: { min: 0, max: 240, range: 270, ticks: 9, minor: 2, unit: 'km/h', label: 'Speed', value: 0, accent: WHT },
+  fuel:        { min: 0, max: 1, range: 90, from: 270, ticks: 3, minor: 4, unit: '', label: 'Fuel', digital: false,
                  tickLabels: ['E', '½', 'F'], zones: [{ from: 0, to: 0.12, color: RED }], value: 0.66, accent: AMB },
-  temp:        { min: 0, max: 1, range: 90, from: 270, ticks: 3, minor: 4, unit: '', label: 'TEMP', digital: false,
+  temp:        { min: 0, max: 1, range: 90, from: 270, ticks: 3, minor: 4, unit: '', label: 'Temp', digital: false,
                  tickLabels: ['C', '', 'H'], zones: [{ from: 0.82, to: 1, color: RED }], value: 0.45, accent: RED },
-  boost:       { min: -1, max: 2, range: 240, ticks: 7, minor: 5, unit: 'bar', label: 'BOOST',
+  boost:       { min: -1, max: 2, range: 240, ticks: 7, minor: 5, unit: 'bar', label: 'Boost',
                  zones: [{ from: 1.2, to: 2, color: RED }], value: 0, accent: '#06b6d4' },
-  voltmeter:   { min: 8, max: 16, range: 180, ticks: 5, minor: 5, unit: 'V', label: 'VOLTS',
+  voltmeter:   { min: 8, max: 16, range: 180, ticks: 5, minor: 5, unit: 'V', label: 'Volts',
                  zones: [{ from: 8, to: 11, color: RED }, { from: 11, to: 12, color: YEL }], value: 13.8, accent: GRN },
-  airspeed:    { min: 0, max: 200, range: 300, ticks: 11, minor: 5, unit: 'kt', label: 'AIRSPEED',
+  airspeed:    { min: 0, max: 200, range: 300, ticks: 11, minor: 5, unit: 'kt', label: 'Airspeed',
                  zones: [{ from: 40, to: 140, color: GRN }, { from: 140, to: 170, color: YEL }, { from: 170, to: 200, color: RED }],
                  value: 0, accent: WHT },
-  altimeter:   { min: 0, max: 10, range: 360, ticks: 10, minor: 5, unit: 'x1000 ft', label: 'ALT', value: 0, accent: WHT },
+  altimeter:   { min: 0, max: 10, range: 360, ticks: 10, minor: 5, unit: 'x1000 ft', label: 'Altitude', value: 0, accent: WHT },
   cpu:         { min: 0, max: 100, range: 270, ticks: 6, minor: 5, unit: '%', label: 'CPU',
                  zones: [{ from: 85, to: 100, color: RED }], value: 0, accent: GRN },
   gpu:         { min: 0, max: 100, range: 270, ticks: 6, minor: 5, unit: '%', label: 'GPU',
                  zones: [{ from: 85, to: 100, color: RED }], value: 0, accent: '#a855f7' },
-  vu:          { min: -20, max: 3, range: 120, ticks: 6, minor: 5, unit: 'dB', label: 'VU',
+  vu:          { min: -21, max: 3, range: 120, ticks: 5, minor: 5, unit: 'dB', label: 'VU',
                  zones: [{ from: 0, to: 3, color: RED }], value: -8, accent: YEL }
 };
 const CASES = ['round', 'square', 'rounded', 'bare'];
 
 const INST_CSS = `
+o-instrument { --ok-font-size: 7.2cqmin; }
 o-instrument .ok-inst-case { box-sizing: border-box; display: flex; align-items: center; justify-content: center; }
+o-instrument .ok-inst-case--square, o-instrument .ok-inst-case--rounded { padding: 7%; }
 o-instrument .ok-inst-case--round   { border-radius: 50%; }
 o-instrument .ok-inst-case--square  { border-radius: 9%; }
 o-instrument .ok-inst-case--rounded { border-radius: 22%; }
 o-instrument .ok-inst-case--bare    { background: transparent; }
 o-instrument .ok-inst-case--square,
 o-instrument .ok-inst-case--rounded {
-  background: var(--ok-inst-case-bg, linear-gradient(160deg, #232a34, #11151b));
+  background: var(--ok-inst-case-bg, var(--ok-case, linear-gradient(160deg, #232a34, #11151b)));
   box-shadow: 0 10px 30px rgba(0,0,0,.45), inset 0 1px 0 rgba(255,255,255,.06);
 }
-o-instrument .ok-inst-face { color: var(--ok-inst-label, #cbd5e1); }
+o-instrument .ok-inst-face { color: var(--ok-inst-label, var(--ok-text, #cbd5e1)); }
 o-instrument .ok-inst-dial {
-  background: var(--ok-inst-face, radial-gradient(circle at 50% 35%, #1b212b, #0a0d12));
-  box-shadow: inset 0 0 0 4px var(--ok-inst-bezel, #2a3340), inset 0 4px 18px rgba(0,0,0,.65);
+  background: var(--ok-inst-face, var(--ok-face, radial-gradient(circle at 50% 35%, #1b212b, #0a0d12)));
+  box-shadow: inset 0 0 0 4px var(--ok-inst-bezel, var(--ok-bezel, #2a3340)), inset 0 4px 18px rgba(0,0,0,.65);
 }
-o-instrument .ok-inst-tick   { background: var(--ok-inst-tick, rgba(203,213,225,.45)); height: 1px; }
-o-instrument .ok-inst-tick-M { background: var(--ok-inst-tick-M, #e6edf3); height: 2px; border-radius: 1px; }
-o-instrument .ok-inst-num    { font-weight: 700; font-variant-numeric: tabular-nums; font-size: .8em; }
-o-instrument .ok-inst-needle { background: var(--ok-inst-accent, #ef4444); height: 3px; border-radius: 0 3px 3px 0; }
+o-instrument .ok-inst-track  { --o-fill: var(--ok-inst-track, var(--ok-track, #171c24)); --o-stroke: var(--o-fill); }
+o-instrument .ok-inst-tick   { background: var(--ok-inst-tick, var(--ok-tick, rgba(203,213,225,.45))); height: 1px; }
+o-instrument .ok-inst-tick-M { background: var(--ok-inst-tick-M, var(--ok-hand, #e6edf3)); height: 2px; border-radius: 1px; }
+o-instrument .ok-inst-num    { font-weight: 700; font-variant-numeric: tabular-nums; font-size: .8em; white-space: nowrap; }
+o-instrument .ok-inst-needle { background: var(--ok-inst-accent, var(--ok-accent, #ef4444)); height: max(2px, 1.2cqmin); border-radius: 0 3px 3px 0; transition: transform .25s cubic-bezier(.3,.7,.4,1); }
+@media (prefers-reduced-motion: reduce) { o-instrument .ok-inst-needle { transition: none; } }
 o-instrument .ok-inst-readout {
   display: flex; flex-direction: column; align-items: center; line-height: 1.05;
 }
-o-instrument .ok-inst-value  { font-weight: 800; font-variant-numeric: tabular-nums; font-size: 1.5em; color: var(--ok-inst-readout-color, #f8fafc); }
-o-instrument .ok-inst-unit   { font-size: .62em; opacity: .7; letter-spacing: .05em; }
-o-instrument .ok-inst-cap-label { font-size: .58em; font-weight: 700; letter-spacing: .14em; text-transform: uppercase; opacity: .65; margin-top: .15em; }
-o-instrument .ok-inst-cap    { background: var(--ok-inst-accent, #e6edf3); box-shadow: 0 0 0 3px var(--ok-inst-hub, #0a0d12); }
-o-instrument.ok-glow .ok-inst-needle { filter: drop-shadow(0 0 5px var(--ok-inst-accent, #ef4444)); }
+o-instrument .ok-inst-value  { font-weight: 800; font-variant-numeric: tabular-nums; font-size: 1.5em; white-space: nowrap; color: var(--ok-inst-readout-color, var(--ok-hand, #f8fafc)); }
+o-instrument .ok-inst-unit   { font-size: .62em; opacity: .7; white-space: nowrap; }
+o-instrument .ok-inst-cap-label { font-size: .6em; font-weight: 700; opacity: .65; margin-top: .15em; white-space: nowrap; }
+o-instrument .ok-inst-cap    { background: var(--ok-inst-accent, var(--ok-accent, #ef4444)); box-shadow: 0 0 0 3px var(--ok-inst-hub, var(--ok-surface, #0a0d12)); }
+o-instrument.ok-glow .ok-inst-needle { filter: drop-shadow(0 0 var(--ok-inst-glow, 5px) var(--ok-inst-accent, #ef4444)); }
 `;
 
 export class OrbitInstrument extends OrbitKitElement {
   static get observedAttributes() {
-    return ['value', 'min', 'max', 'range', 'from', 'ticks', 'minor', 'zones',
-            'tick-labels', 'unit', 'label', 'redline', 'preset', 'case', 'size',
-            'digital', 'face', 'bezel', 'accent', 'needle-color', 'tick-color', 'glow'];
+    return withShared(['value', 'range', 'from', 'ticks', 'minor', 'zones',
+            'tick-labels', 'label', 'redline', 'preset', 'case', 'size',
+            'digital', 'face', 'bezel', 'accent', 'needle-color', 'tick-color', 'glow'], RANGE_ATTRS, FORMAT_ATTRS);
   }
 
   _preset() { return PRESETS[this.getAttribute('preset')] || {}; }
 
   _pNum(name, key, dflt) {
     const v = this.getAttribute(name);
-    if (v != null && v !== '') return parseFloat(v);
     const p = this._preset();
-    return p[key] != null ? p[key] : dflt;
+    return finiteNumber(v, p[key] != null ? p[key] : dflt);
   }
   _pStr(name, key, dflt) {
     const v = this.getAttribute(name);
@@ -108,22 +112,24 @@ export class OrbitInstrument extends OrbitKitElement {
   }
   _pArr(name, key, dflt) {
     const v = this.getAttribute(name);
-    if (v != null && v.trim() !== '') { try { return JSON.parse(v); } catch { /* fall through */ } }
+    if (v != null && v.trim() !== '') { try { const parsed = JSON.parse(v); if (Array.isArray(parsed)) return parsed; } catch { /* fall through */ } }
     const p = this._preset();
     return p[key] != null ? p[key] : dflt;
   }
 
   readConfig() {
-    const range = this._pNum('range', 'range', 270);
-    const min = this._pNum('min', 'min', 0);
-    const max = this._pNum('max', 'max', 100);
-    const span = (max - min) || 1;
-    const zones = (this._pArr('zones', 'zones', []) || []).map((z) => ({
-      from: Number(z.from), to: Number(z.to), color: z.color || RED
-    }));
+    const range = Math.max(0, Math.min(360, this._pNum('range', 'range', 270)));
+    const p = this._preset();
+    const r = this._range({ min: p.min ?? 0, max: p.max ?? 100, step: 0, value: p.value });
+    const { min, max } = r;
+    const span = r.span || 1;
+    const zones = arrayData(this._pArr('zones', 'zones', [])).map((z) => ({
+      from: Math.max(min, finiteNumber(z.from, min)), to: Math.min(max, finiteNumber(z.to, min)), color: cssValue(z.color, RED)
+    })).filter((z) => z.to > z.from);
     // `redline=` is sugar for a red zone from that value to max.
     const redline = this.getAttribute('redline');
-    if (redline != null) zones.push({ from: parseFloat(redline), to: max, color: RED });
+    const redlineValue = finiteNumber(redline, max);
+    if (redline != null && redlineValue < max) zones.push({ from: Math.max(min, redlineValue), to: max, color: RED });
 
     // Partial-sweep gauges (fuel/temp/…) read as an arc band, not a round watch,
     // so they default to a "bare" case (no round bezel) unless told otherwise.
@@ -133,54 +139,50 @@ export class OrbitInstrument extends OrbitKitElement {
     if (!CASES.includes(caseShape)) caseShape = partial ? 'bare' : 'round';
 
     return {
-      value: this._pNum('value', 'value', min),
+      value: r.value, fraction: r.fraction, step: r.step,
       min, max, span, range, zones, caseShape, partial,
-      from: this.hasAttribute('from') ? this._pNum('from', null, 0) : (this._preset().from ?? this._autoFrom(range)),
-      ticks: Math.max(2, Math.round(this._pNum('ticks', 'ticks', 7))),
-      minor: Math.max(0, Math.round(this._pNum('minor', 'minor', 5))),
+      from: this.hasAttribute('from') ? this._pNum('from', null, 0) : (this._preset().from ?? (range === 360 ? 0 : this._autoFrom(range))),
+      ticks: Math.max(2, Math.min(360, Math.round(this._pNum('ticks', 'ticks', 7)))),
+      minor: Math.max(0, Math.min(60, Math.round(this._pNum('minor', 'minor', 5)))),
       tickLabels: this._pArr('tick-labels', 'tickLabels', null),
-      unit: this._pStr('unit', 'unit', ''),
+      unit: this.getAttribute('format') === 'unit' ? '' : this._pStr('unit', 'unit', ''),
       label: this._pStr('label', 'label', ''),
       digital: this.hasAttribute('digital')
         ? this.getAttribute('digital') !== 'false'
         : (this._preset().digital !== false),
-      size: this._str('size', '240px'),
-      glow: this.hasAttribute('glow'),
-      accent: this._pStr('accent', 'accent', '#ef4444'),
-      theme: ['face', 'bezel', 'needle-color', 'tick-color'].map((a) => this.getAttribute(a)).join('|')
+      size: this._size('size', '240px'),
+      glow: this.getAttribute('glow'),
+      accent: cssValue(this._pStr('accent', 'accent', null), null),
+      theme: ['face', 'bezel', 'needle-color', 'tick-color'].map((a) => this.getAttribute(a)).join('|'),
+      // Tick labels are part of the dial, so the number format rebuilds it.
+      format: [...['format', 'locale', 'decimals', 'currency'].map((a) => this.getAttribute(a)), this._formatter ? 'fn' : '', this.getAttribute('format') === 'unit' ? this.getAttribute('unit') : ''].join('|')
     };
   }
 
   structuralSignature(cfg) {
-    const { value, ...rest } = cfg;
+    const { value, fraction, step, unit, label, ...rest } = cfg;
     return JSON.stringify(rest);
   }
 
   build(cfg) {
     injectStyleOnce('orbit-kit-instrument', INST_CSS);
-    this.classList.toggle('ok-glow', cfg.glow);
+    this.classList.toggle('ok-glow', cfg.glow != null);
 
-    this.style.setProperty('--ok-inst-accent', cfg.accent);
-    const map = { face: '--ok-inst-face', bezel: '--ok-inst-bezel',
-                  'needle-color': '--ok-inst-accent', 'tick-color': '--ok-inst-tick' };
-    for (const [attr, prop] of Object.entries(map)) {
-      const v = this.getAttribute(attr);
-      if (v != null) this.style.setProperty(prop, v);
-    }
+    this._applyTheme({
+      '--ok-inst-accent': this.getAttribute('needle-color') ?? cfg.accent,
+      '--ok-inst-face': this.getAttribute('face'), '--ok-inst-bezel': this.getAttribute('bezel'),
+      '--ok-inst-tick': this.getAttribute('tick-color'),
+      '--ok-inst-glow': cfg.glow == null ? null : `${Math.max(0, this._num('glow', 5))}px`
+    });
 
-    const dialPx = parseFloat(cfg.size) || 240;
-    const force = (dialPx * 12 / 11).toFixed(1);
-    const frame = (cfg.caseShape === 'round' || cfg.caseShape === 'bare') ? 0 : Math.round(dialPx * 0.07);
-    const box = dialPx + frame * 2;
-    const baseFont = (dialPx * 0.072).toFixed(1);
     const fromVar = `--o-range:${cfg.range}deg;--o-from:${cfg.from}deg;`;
 
     // Partial gauges (a 90° fuel arc) otherwise sit crammed in one quadrant.
-    // Center the content by translating the gravity-spot so the arc's bounding
-    // box (plus the center pivot) is centered in the square box.
+    // Center the content by moving the gravity-spot so the arc's bounding box
+    // (plus the center pivot) is centered in the square box.
     let centering = '';
-    if (cfg.partial) {
-      const R = dialPx * 5 / 11; // ≈ outer tick-ring radius
+    if (cfg.partial && cfg.caseShape === 'bare') {
+      const R = 50 * 11 / 12; // the tick ring, in cqmin of the universe
       let minX = 0, maxX = 0, minY = 0, maxY = 0; // seed with the center pivot
       for (let k = 0; k <= 24; k++) {
         const p = (cfg.from + (cfg.range * k) / 24) * Math.PI / 180;
@@ -188,64 +190,63 @@ export class OrbitInstrument extends OrbitKitElement {
         minX = Math.min(minX, x); maxX = Math.max(maxX, x);
         minY = Math.min(minY, y); maxY = Math.max(maxY, y);
       }
-      const dx = (-(minX + maxX) / 2 * R).toFixed(1);
-      const dy = (-(minY + maxY) / 2 * R).toFixed(1);
-      centering = `transform:translate(${dx}px,${dy}px);`;
+      centering = `translate:${fixed(-(minX + maxX) / 2 * R, 1)}cqmin ${fixed(-(minY + maxY) / 2 * R, 1)}cqmin;`;
     }
 
     // Face: a round dial for full sweeps, or a neutral track band for partial
     // gauges (so a quarter-arc fuel gauge isn't trapped in a round bezel).
-    const face = cfg.partial
-      ? `<div class="orbit-9" style="${fromVar}"><o-arc value="100" style="--o-fill:var(--ok-inst-track,#171c24);--o-stroke:var(--ok-inst-track,#171c24);--o-stroke-width:8"></o-arc></div>`
-      : '<div class="orbit-11 ok-inst-dial"></div>';
+    const band = `--o-size-ratio:.55;--o-gap:0;`;
+    const face = cfg.caseShape === 'bare'
+      ? `<div class="orbit-11" style="${fromVar}${band}"><o-arc class="inner-orbit ok-inst-track" value="100"></o-arc></div>`
+      : '<div class="orbit-12 ok-inst-dial ok-surface"></div>';
 
     // --- ticks: major (count) + minor (between) over the range ---
     const majorN = cfg.ticks;
-    const minorN = cfg.minor > 0 ? (majorN - 1) * cfg.minor + 1 : 0;
+    const closed = cfg.range === 360;
+    const fit = closed ? '' : 'fit-range';
+    const minorN = cfg.minor > 0 ? (closed ? majorN * (cfg.minor + 1) : (majorN - 1) * (cfg.minor + 1) + 1) : 0;
     const minorTicks = minorN
-      ? `<div class="orbit-10 fit-range" style="${fromVar}">${Array.from({ length: minorN }, () =>
-          '<div class="vector inner-orbit shrink-80 ok-inst-tick"></div>').join('')}</div>`
+      ? `<div class="orbit-11 ${fit}" style="${fromVar}--o-size-ratio:.3">${Array.from({ length: minorN }, () =>
+          '<div class="vector inner-orbit ok-inst-tick"></div>').join('')}</div>`
       : '';
-    const majorTicks = `<div class="orbit-10 fit-range" style="${fromVar}">${Array.from({ length: majorN }, () =>
-      '<div class="vector inner-orbit shrink-55 ok-inst-tick-M"></div>').join('')}</div>`;
+    const majorTicks = `<div class="orbit-11 ${fit}" style="${fromVar}--o-size-ratio:.6">${Array.from({ length: majorN }, () =>
+      '<div class="vector inner-orbit ok-inst-tick-M"></div>').join('')}</div>`;
 
     // --- numeric / custom scale labels ---
     const labels = Array.from({ length: majorN }, (_, i) => {
       const txt = cfg.tickLabels ? (cfg.tickLabels[i] ?? '')
-        : this._fmtTick(cfg.min + (i * cfg.span) / (majorN - 1));
-      return `<div class="satellite"><div class="capsule ok-inst-num">${txt}</div></div>`;
+        : this._format(cfg.min + (i * cfg.span) / (closed ? majorN : majorN - 1), { kind: 'tick', min: cfg.min, max: cfg.max, fallback: (v) => this._fmtTick(v) });
+      return `<div class="satellite"><div class="capsule ok-inst-num">${e(txt)}</div></div>`;
     }).join('');
-    const labelRing = `<div class="orbit-8 fit-range" style="${fromVar}">${labels}</div>`;
+    const labelRing = `<div class="orbit-9 ${fit}" style="${fromVar}">${labels}</div>`;
 
-    // --- color zones: each in its own orbit so non-contiguous zones land right ---
+    // --- color zones: each on its own ring so non-contiguous zones land right ---
     const zones = cfg.zones.map((z) => {
       const startA = cfg.from + ((z.from - cfg.min) / cfg.span) * cfg.range;
       const pct = ((z.to - z.from) / cfg.span) * 100;
-      const style = `--o-range:${cfg.range}deg;--o-from:${startA}deg`;
-      const arc = `--o-fill:${z.color};--o-stroke:${z.color};--o-stroke-width:5${cfg.glow ? `;filter:drop-shadow(0 0 4px ${z.color})` : ''}`;
-      return `<div class="orbit-9" style="${style}"><o-arc value="${pct.toFixed(3)}" style="${arc}"></o-arc></div>`;
+      const style = `--o-range:${cfg.range}deg;--o-from:${fixed(startA)}deg;${band}`;
+      const arc = `--o-fill:${z.color};--o-stroke:${z.color}${cfg.glow != null ? `;filter:drop-shadow(0 0 ${Math.max(0, this._num('glow', 4))}px ${z.color})` : ''}`;
+      return `<div class="orbit-11" style="${style}"><o-arc class="inner-orbit ok-inst-zone" value="${pct.toFixed(3)}" style="${e(arc)}"></o-arc></div>`;
     }).join('');
 
-    const readout = cfg.digital || cfg.label
-      ? `<div class="orbit-4"><div class="satellite angle-180"><div class="capsule ok-inst-readout">
-           ${cfg.digital ? `<span class="ok-inst-value"></span>` : ''}
-           ${cfg.unit ? `<span class="ok-inst-unit">${cfg.unit}</span>` : ''}
-           ${cfg.label ? `<span class="ok-inst-cap-label">${cfg.label}</span>` : ''}
-         </div></div></div>`
-      : '';
+    const readout = `<div class="orbit-4"><div class="satellite angle-180"><div class="capsule ok-inst-readout">
+      ${cfg.digital ? '<span class="ok-inst-value"></span>' : ''}
+      <span class="ok-inst-unit">${e(cfg.unit)}</span>
+      <span class="ok-inst-cap-label">${e(cfg.label)}</span>
+    </div></div></div>`;
 
     this.innerHTML = `
-      <div class="ok-inst-case ok-inst-case--${cfg.caseShape}" style="width:${box}px;height:${box}px;font-size:${baseFont}px;">
-        <div class="bigbang" style="width:100%;height:100%;">
-          <div class="gravity-spot ok-inst-face" style="--o-force:${force}px;${centering}">
+      <div class="ok-inst-case ok-inst-case--${cfg.caseShape}${cfg.caseShape === 'square' || cfg.caseShape === 'rounded' ? ' ok-surface' : ''}" style="width:${e(cfg.size)};aspect-ratio:1">
+        <div class="bigbang" style="width:100%">
+          <div class="gravity-spot ok-inst-face"${centering ? ` style="${centering}"` : ''}>
             ${face}
             ${minorTicks}${majorTicks}
             ${zones}
             ${labelRing}
             ${readout}
             <div class="orbit-0">
-              <div class="vector outer-orbit grow-4x ok-inst-needle"></div>
-              <div class="satellite at-center shrink-75 ok-inst-cap"></div>
+              <div class="vector outer-orbit ok-inst-needle" style="--o-size-ratio:9.6"></div>
+              <div class="satellite at-center ok-inst-cap" style="--o-size-ratio:.8"></div>
             </div>
           </div>
         </div>
@@ -253,16 +254,26 @@ export class OrbitInstrument extends OrbitKitElement {
 
     this._needle = this.querySelector('.ok-inst-needle');
     this._value = this.querySelector('.ok-inst-value');
+    this._unit = this.querySelector('.ok-inst-unit');
+    this._caption = this.querySelector('.ok-inst-cap-label');
+    this._readout = this.querySelector('.ok-inst-readout');
   }
 
   sync(cfg) {
-    const v = Math.min(cfg.max, Math.max(cfg.min, cfg.value));
-    const frac = (v - cfg.min) / cfg.span;
+    const frac = cfg.fraction;
     // The arc start (value 0) sits at screen angle `from + 270`; the needle is
     // a full-length vector rotated to the value's screen angle (always visible).
     const deg = (((cfg.from + 270 + frac * cfg.range) % 360) + 360) % 360;
     if (this._needle) this._needle.style.setProperty('--o-angle-composite', `${deg.toFixed(2)}deg`);
-    if (this._value) this._value.textContent = this._fmtValue(cfg.value, cfg.span);
+    const range = { min: cfg.min, max: cfg.max };
+    const reading = this._format(cfg.value, { ...range, fallback: (v) => this._fmtValue(v, cfg.span) });
+    if (this._value) this._value.textContent = reading;
+    if (this._unit) { this._unit.textContent = cfg.unit; this._unit.hidden = !cfg.unit; }
+    if (this._caption) { this._caption.textContent = cfg.label; this._caption.hidden = !cfg.label; }
+    if (this._readout) this._readout.hidden = !cfg.digital && !cfg.label && !cfg.unit;
+    const tick = (v) => this._format(v, { ...range, kind: 'tick', fallback: String });
+    this._describe(`${cfg.label ? cfg.label + ': ' : ''}${reading}${cfg.unit}; range ${tick(cfg.min)} to ${tick(cfg.max)}`, 'meter');
+    this._ariaRange(cfg, cfg.value, this._formatText(cfg.value, { ...range, kind: 'aria', fallback: (v) => this._fmtValue(v, cfg.span) }, cfg.unit));
   }
 
   /** Tick-scale label: integers bare, otherwise one decimal. */