tweakit 0.5.2 → 0.7.0

package/src/tweaks/controls/interval.ts

@@ -0,0 +1,189 @@
+// ── Interval / range slider — dual-handle [lo,hi]. Lazy.
+import {
+  el,
+  txt,
+  clamp,
+  words,
+  roundToStep,
+  stepPrecision,
+  gridEnds,
+  normalizeRange,
+  rangeStep,
+  overlapsText,
+  wireHoverClass,
+  onReady,
+  onLive,
+  registerControl,
+  rubberBand,
+  rubberRelease,
+} from "../shared.js";
+import { dragGesture } from "../heavy.js";
+import type { OnChange } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control } from "../types.js";
+
+function createInterval(meta: Meta, onChange: OnChange): Control {
+  const label = meta.label;
+  const t0 = +(meta.value && meta.value[0]),
+    t1 = +(meta.value && meta.value[1]);
+  const lo0 = Number.isFinite(t0) ? t0 : 0,
+    hi0 = Number.isFinite(t1) ? t1 : 1;
+  // normalizeRange, the slider's guard: an absent or non-finite bound (data-min="abc") derives from the values, each
+  // end widening it, for the shorthand and the verbose form alike: [20, 80] spans 0–240, not 20–80 (which pinned both
+  // handles).
+  let { min, max, step } = normalizeRange(meta.min, meta.max, meta.step, [lo0, hi0], label);
+  [min, max] = gridEnds(min, max, step); // the slider's rule: no value past an off-grid bound
+  const decimals = stepPrecision(step);
+  const q = (v: number) => roundToStep(v, min, step);
+  let lo = 0,
+    hi = 0;
+  // ordered, on the grid, in bounds
+  const put = (a: number, b: number) => {
+    lo = clamp(q(Math.min(a, b)), min, max);
+    hi = clamp(q(Math.max(a, b)), min, max);
+  };
+  // Missing tuple entries fall back to the bounds: value:[5] gives [5, max], not [5, NaN].
+  put(Number.isFinite(t0) ? t0 : min, Number.isFinite(t1) ? t1 : max);
+
+  const wrap = el("div", "twk-slider-wrap");
+  const track = el("div", "twk-slider twk-interval");
+  const fill = el("div", "twk-slider-fill");
+  const hLo = el("div", "twk-slider-handle"),
+    hHi = el("div", "twk-slider-handle");
+  const labelEl = txt("span", "twk-slider-label", label);
+  const valueEl = el("span", "twk-slider-value");
+  track.append(fill, hLo, hHi, labelEl, valueEl);
+  wrap.append(track);
+
+  const tr = words();
+  (
+    [
+      ["intervalMin", "{label} minimum", hLo],
+      ["intervalMax", "{label} maximum", hHi],
+    ] as const
+  ).forEach(([k, d, h]) => {
+    h.tabIndex = 0;
+    h.setAttribute("role", "slider");
+    h.setAttribute("aria-label", tr(k, d, { label }));
+    h.setAttribute("aria-valuemin", String(min));
+    h.setAttribute("aria-valuemax", String(max));
+  });
+
+  const pctOf = (v: number) => ((v - min) / (max - min || 1)) * 100;
+  // stay inset at the extremes, like the slider handle
+  const handleLeft = (pct: number) => `clamp(5px, calc(${pct}% - 1.5px), calc(100% - 9px))`;
+  const render = () => {
+    const a = pctOf(lo),
+      b = pctOf(hi);
+    fill.style.left = a + "%";
+    fill.style.width = Math.max(0, b - a) + "%";
+    hLo.style.left = handleLeft(a);
+    hHi.style.left = handleLeft(b);
+    valueEl.textContent = `${lo.toFixed(decimals)} – ${hi.toFixed(decimals)}`;
+    hLo.setAttribute("aria-valuenow", String(lo));
+    hHi.setAttribute("aria-valuenow", String(hi));
+    // Value-dodge (overlapsText), per handle: one sliding under the label or the readout yields so the text stays
+    // legible.
+    const trackW = wrap.offsetWidth;
+    if (trackW) {
+      // The label's room is what the dual readout leaves, measured: 12px label inset + 8px gap + the readout's right
+      // inset.
+      labelEl.style.maxWidth = Math.max(0, trackW - valueEl.offsetWidth - 12 - 8 - 10) + "px";
+      const dodges = (pct: number) => overlapsText(labelEl, valueEl, (pct / 100) * trackW - 1.5, 3);
+      hLo.classList.toggle("is-dodge", dodges(pctOf(lo)));
+      hHi.classList.toggle("is-dodge", dodges(pctOf(hi)));
+    }
+  };
+  render();
+
+  const emit = () => onChange([lo, hi]);
+  const setLo = (v: number) => {
+    lo = clamp(Math.min(q(v), hi), min, max);
+    render();
+  };
+  const setHi = (v: number) => {
+    hi = clamp(Math.max(q(v), lo), min, max);
+    render();
+  };
+
+  let rect: DOMRect | null = null,
+    scale = 1,
+    active: "lo" | "hi" | null = null;
+  // Divide out any ancestor CSS transform (rect is visual px, offsetWidth layout px), as the single slider does.
+  const valFromX = (x: number) => {
+    const native = wrap.offsetWidth || rect.width;
+    const p = clamp((x - rect.left) / scale / native, 0, 1);
+    return clamp(min + p * (max - min), min, max);
+  };
+  const grab = (x: number) => {
+    const v = valFromX(x);
+    if (!active) active = v < lo ? "lo" : v > hi ? "hi" : Math.abs(v - lo) <= Math.abs(v - hi) ? "lo" : "hi";
+    active === "lo" ? setLo(v) : setHi(v);
+    emit();
+  };
+  dragGesture(track, {
+    onDown: (e) => {
+      e.preventDefault();
+      rect = wrap.getBoundingClientRect();
+      scale = rect.width / (wrap.offsetWidth || rect.width);
+      track.style.transition = ""; // a re-press mid spring-home stretches 1:1
+      track.classList.add("is-active", "is-dragging");
+      active = null;
+      grab(e.clientX);
+      // preventDefault killed click-to-focus; focus without a ring
+      (active === "lo" ? hLo : hHi).focus({ focusVisible: false });
+    },
+    onMove: (e) => {
+      grab(e.clientX);
+      rubberBand(track, rect, e.clientX);
+    },
+    onEnd: () => {
+      rubberRelease(track);
+      rect = null;
+      active = null;
+      track.classList.remove("is-active", "is-dragging");
+    },
+  });
+  wireHoverClass(track, render); // re-run the dodge with the real track width on hover
+  // Recompute once layout and fonts settle (a web-font swap shifts the widths the dodge measures) and on track-width
+  // change.
+  onReady(render);
+  // twk-reflow: a tab page revealing this re-measures it
+  onLive(
+    track,
+    [
+      [window, "resize"],
+      [window, "twk-reflow"],
+    ],
+    render,
+  );
+
+  // Home/End snap a handle to its neighbor-or-limit, so the two can't cross.
+  const page = (max - min) / 10 || step * 10; // PageUp/Down: a tenth of the range, as the slider jumps
+  const onKey = (which: "lo" | "hi") => (e: KeyboardEvent) => {
+    const nv = which === "lo" ? rangeStep(e, lo, step, min, hi, page) : rangeStep(e, hi, step, lo, max, page);
+    if (nv == null) return;
+    e.preventDefault();
+    which === "lo" ? setLo(nv) : setHi(nv);
+    emit();
+  };
+  hLo.addEventListener("keydown", onKey("lo"));
+  hHi.addEventListener("keydown", onKey("hi"));
+
+  return {
+    el: wrap,
+    set: (v: unknown) => {
+      if (Array.isArray(v)) {
+        const a = +v[0],
+          b = +v[1];
+        if (!Number.isFinite(a) || !Number.isFinite(b)) return;
+        put(a, b);
+        render();
+      }
+    },
+    get: () => [lo, hi],
+    range: [min, max],
+  };
+}
+
+registerControl("interval", createInterval);

package/src/tweaks/controls/monitor.ts

@@ -0,0 +1,211 @@
+// ── Monitor + FPS graph — live sparkline / readout. Lazy; registers both types.
+import { el, txt, clamp, blade, json, registerControl, words } from "../shared.js";
+import { fitCanvas, accentColor } from "../heavy.js";
+import type { Meta } from "../schema.js";
+
+// NaN means no sample yet: the pen lifts rather than drawing a false zero.
+const strokeSeries = (
+  ctx: CanvasRenderingContext2D,
+  node: Element,
+  w: number,
+  h: number,
+  samples: number[],
+  start: number,
+  frac: (s: number) => number,
+) => {
+  const N = samples.length;
+  ctx.clearRect(0, 0, w, h);
+  ctx.strokeStyle = accentColor(node);
+  ctx.lineWidth = 1.5;
+  ctx.lineJoin = "round";
+  ctx.beginPath();
+  let pen = false;
+  for (let k = 0; k < N; k++) {
+    const s = samples[(start + k) % N];
+    if (Number.isNaN(s)) continue;
+    const x = (k / (N - 1)) * w,
+      y = h - clamp(frac(s), 0, 1) * h;
+    pen ? ctx.lineTo(x, y) : (ctx.moveTo(x, y), (pen = true));
+  }
+  ctx.stroke();
+};
+
+// Manual, not onLive: these blades idle through the built-but-not-mounted window, which onLive would read as gone.
+const watchReflow = (fn: () => void) => {
+  for (const t of ["resize", "twk-reflow"]) window.addEventListener(t, fn);
+  return () => {
+    for (const t of ["resize", "twk-reflow"]) window.removeEventListener(t, fn);
+  };
+};
+
+// ── Monitor — a number as a sparkline or a readout, a string as a buffer of the last few values; read on an interval
+// or, `perFrame` (the FPS graph), once per animation frame. ──
+function createMonitor(meta: Meta, perFrame = false) {
+  const get: (now?: number) => unknown = typeof meta.get === "function" ? meta.get : () => meta.value;
+  // NaN would make setInterval a 0 ms busy-poll
+  const interval = Math.max(30, Number.isFinite(+meta.interval) ? +meta.interval : 200);
+  let probe: unknown;
+  try {
+    probe = get();
+  } catch {}
+  const isNum = typeof probe === "number";
+  const graph = meta.view === "graph" || (isNum && meta.graph !== false && meta.view !== "text" && meta.rows == null);
+
+  const wrap = el("div", "twk-fps twk-monitor");
+  const val = txt("span", "twk-fps-val", "—");
+  wrap.append(txt("span", "twk-fps-label", meta.label ?? words()("monitor", "Monitor")), val);
+
+  let timer = 0,
+    raf = 0,
+    unwatch = () => {},
+    wasConnected = false;
+  // toFixed throws past 100; a missing value reads as a dash.
+  const decimals = Number.isFinite(+meta.decimals) ? Math.min(20, Math.max(0, Math.floor(+meta.decimals))) : 2;
+  const fmt = (v: unknown) =>
+    v == null
+      ? "—"
+      : typeof v === "number"
+        ? Number.isInteger(v) || !Number.isFinite(v)
+          ? String(v)
+          : v.toFixed(decimals)
+        : typeof v === "object"
+          ? json(v)
+          : String(v);
+  // Also the blade's `destroy`: a panel torn down before it ever connected can never self-stop below.
+  const stop = () => {
+    if (timer) clearInterval(timer);
+    timer = 0;
+    if (raf) cancelAnimationFrame(raf);
+    raf = 0;
+    unwatch();
+  };
+  // Never-mounted-yet idles the tick; only a mount-then-remove, or destroy(), stops it. The next frame is booked before
+  // the read, so a stop() inside the tick cancels it.
+  const poll = (fn: (v: unknown) => void) => {
+    const tick = (now?: number) => {
+      if (perFrame) raf = requestAnimationFrame(tick);
+      if (!wrap.isConnected) {
+        if (wasConnected) stop();
+        return;
+      }
+      wasConnected = true;
+      let v: unknown;
+      try {
+        v = get(now);
+      } catch {
+        return;
+      }
+      fn(v);
+    };
+    if (perFrame) raf = requestAnimationFrame(tick);
+    else timer = setInterval(tick, interval);
+  };
+
+  if (!graph && meta.rows) {
+    val.remove();
+    // A negative or NaN rows spun the trim loop forever.
+    const rows = Math.max(1, Math.floor(+meta.rows) || 1);
+    const buf = el("pre", "twk-monitor-buffer");
+    buf.style.setProperty("--twk-monitor-rows", rows);
+    wrap.append(buf);
+    const lines: string[] = [];
+    poll((v) => {
+      lines.push(fmt(v));
+      while (lines.length > rows) lines.shift();
+      buf.textContent = lines.join("\n");
+    });
+    return blade(wrap, stop);
+  }
+  const readout = (v: unknown) => {
+    val.textContent = fmt(v);
+  };
+  if (!graph) {
+    poll(readout);
+    return blade(wrap, stop);
+  }
+
+  const canvas = document.createElement("canvas");
+  canvas.className = "twk-fps-canvas";
+  wrap.append(canvas);
+  const ctx = canvas.getContext("2d");
+  // No 2D context (a headless DOM, a blocked canvas) degrades to the text readout.
+  if (!ctx) {
+    poll(readout);
+    return blade(wrap, stop);
+  }
+  const N = 80,
+    samples: number[] = new Array(N).fill(NaN);
+  let idx = 0,
+    w = 0,
+    h = 0;
+  const onResize = () => {
+    [w, h] = fitCanvas(canvas, ctx, 2);
+  };
+  unwatch = watchReflow(onResize);
+  const draw = () => {
+    if (!w) onResize(); // measured 0 while detached: fit on the first live draw
+    if (!w) return;
+    let lo = meta.min,
+      hi = meta.max;
+    if (lo == null || hi == null) {
+      let mn = Infinity,
+        mx = -Infinity;
+      // an Infinity sample would blank the auto-range
+      for (const s of samples)
+        if (Number.isFinite(s)) {
+          if (s < mn) mn = s;
+          if (s > mx) mx = s;
+        }
+      if (mn === Infinity) {
+        mn = 0;
+        mx = 1;
+      } else if (mn === mx) {
+        mn -= 0.5;
+        mx += 0.5;
+      }
+      const pad = (mx - mn) * 0.1;
+      if (lo == null) lo = mn - pad;
+      if (hi == null) hi = mx + pad;
+    }
+    const span = hi - lo || 1;
+    strokeSeries(ctx, wrap, w, h, samples, idx, (s) => (s - lo) / span);
+  };
+  // a non-finite sample shows in the readout, not the graph
+  poll((v) => {
+    readout(v);
+    if (typeof v === "number" && Number.isFinite(v)) {
+      samples[idx] = v;
+      idx = (idx + 1) % N;
+      draw();
+    }
+  });
+  return blade(wrap, stop);
+}
+
+// ── FPS graph — each frame's timestamp becomes the rate since the last (none on the first or for the probe), 0–120. ──
+const frameRate = () => {
+  let last = 0;
+  return (now?: number) => {
+    if (!(now! > 0)) return undefined;
+    const fps = last ? 1000 / (now! - last) : undefined;
+    last = now!;
+    return fps;
+  };
+};
+// ??: an explicit "" label renders none
+const createFps = (meta: Meta) =>
+  createMonitor(
+    {
+      ...meta,
+      label: meta.label ?? words()("fps", "FPS"),
+      get: frameRate(),
+      view: "graph",
+      min: 0,
+      max: 120,
+      decimals: 0,
+    },
+    true,
+  );
+
+registerControl("fpsgraph", createFps);
+registerControl("monitor", (meta: Meta) => createMonitor(meta)); // the registry passes (meta, onChange), not perFrame