tweakit 0.5.2 → 0.7.0

package/src/tweaks/controls/shadow.ts

@@ -0,0 +1,156 @@
+// ── Shadow — a box-shadow editor with the kit's own picker mounted inline (popover() is single-open). The value carries
+// the CSS as `css`, built only from the numbers and a color the picker accepted as one color token (isColor) — a host
+// string reaching a `style` sink could splice in a url(). Lazy. ──
+import { el, txt, popover, createSegmented, registerControl, btn, icon, isObj, words } from "../shared.js";
+import { numField, triggerRow } from "../heavy.js";
+import { createPickerBody, isColor } from "./color.js";
+import type { OnChange, NumField } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control, ShadowValue, ShadowInput } from "../types.js";
+
+const DEF = { x: 0, y: 8, blur: 24, spread: 0, color: "rgb(0 0 0 / 0.18)" };
+const num = (v: unknown, d: number) => (v != null && v !== "" && Number.isFinite(+v) ? +v : d);
+const fmt = (n: number) => String(+n.toFixed(1));
+// One color function, no nesting, so a stray `)` can't extend the match.
+const COLOR_RE = /#[0-9a-f]{3,8}\b|(?:oklch|oklab|rgba?|hsla?|hwb|lab|lch|color)\([^()]*\)/i;
+const LEN_RE = /^(-?\d*\.?\d+)(px)?$/;
+// Strict: optional `inset`, two to four px lengths, one color, one layer; anything else is null.
+const parseShadow = (s: string): ShadowInput | null => {
+  const m = COLOR_RE.exec(s);
+  if (!m || !isColor(m[0])) return null;
+  const rest = (s.slice(0, m.index) + " " + s.slice(m.index + m[0].length)).trim().split(/\s+/).filter(Boolean);
+  const inset = rest.includes("inset"),
+    lens = rest.filter((t) => t !== "inset");
+  if (lens.length < 2 || lens.length > 4 || !lens.every((t) => LEN_RE.test(t))) return null;
+  const n = lens.map((t) => +t.replace(/px$/, ""));
+  return { inset, x: n[0], y: n[1], blur: n[2] ?? 0, spread: n[3] ?? 0, color: m[0] };
+};
+
+// the kit's chevron; importing icons.ts splits a 4th chunk
+const CHEVRON = icon('<path d="M18 9s-4.4 6-6 6-6-6-6-6"/>', "twk-shadow-chevron", 2.5);
+function createShadow(meta: Meta, onChange: OnChange): Control {
+  const tr = words();
+  const read = (v: unknown): ShadowInput | null => (typeof v === "string" ? parseShadow(v) : isObj(v) ? v : null);
+  const init = read(meta.value ?? meta) || {}; // the fields may sit on the meta itself (verbose form)
+  let inset = !!init.inset;
+
+  // ── Row — label, chip, summary. ──
+  // ??: an explicit "" label renders none
+  const { root, trigger, right } = triggerRow("twk-shadow", meta.label ?? tr("shadow", "Shadow"));
+  const chip = el("span", "twk-trigger-chip twk-shadow-chip"),
+    chipTile = el("span", "twk-shadow-chip-tile");
+  chip.append(chipTile);
+  const valueEl = el("span", "twk-trigger-value");
+  right.append(chip, valueEl);
+
+  // ── Popover — a preview card, the position switch, the four lengths, the picker. ──
+  const pop = el("div", "twk-color-pop twk-shadow-pop");
+  const stage = el("div", "twk-shadow-stage"),
+    card = el("div", "twk-shadow-card");
+  stage.append(card);
+  const insetSeg = createSegmented(
+    [
+      { value: "outer", label: tr("outer", "Outer") },
+      { value: "inner", label: tr("inner", "Inner") },
+    ],
+    inset ? "inner" : "outer",
+    (m: unknown) => {
+      if ((m === "inner") !== inset) {
+        inset = m === "inner";
+        update();
+        emit();
+      }
+    },
+    tr("shadowPosition", "Shadow position"),
+  );
+  const insetRow = el("div", "twk-row");
+  insetRow.append(txt("span", "twk-row-label", tr("position", "Position")), insetSeg.el);
+  const fields = el("div", "twk-fields twk-shadow-fields");
+  // The four lengths live in their fields, read as the fields fit them: an authored 2.5 shows "3" and emits 3px, and
+  // the blur's min clamps a negative one to 0.
+  const field = (label: string, value: number, min?: number): NumField => {
+    const f = numField({ label, value, step: 1, min, unit: "px" }, () => {
+      update();
+      emit();
+    });
+    fields.append(f.el);
+    return f;
+  };
+  const fx = field("X", num(init.x, DEF.x)),
+    fy = field("Y", num(init.y, DEF.y)),
+    fb = field(tr("blur", "Blur"), num(init.blur, DEF.blur), 0),
+    fs = field(tr("spread", "Spread"), num(init.spread, DEF.spread));
+  const lengths = () => [fx, fy, fb, fs].map((f) => f.get());
+  // The color row discloses the picker, so the pop opens compact.
+  const colorRow = btn("twk-trigger twk-shadow-color");
+  colorRow.setAttribute("aria-expanded", "false");
+  const cSwatch = el("span", "twk-trigger-chip twk-color-swatch"),
+    cText = el("span", "twk-trigger-value"),
+    cRight = el("span", "twk-trigger-right");
+  cRight.append(cSwatch, cText);
+  cRight.insertAdjacentHTML("beforeend", CHEVRON);
+  colorRow.append(txt("span", "twk-trigger-label", tr("color", "Color")), cRight);
+  const body = createPickerBody(
+    { value: typeof init.color === "string" && isColor(init.color) ? init.color : DEF.color, onMode: () => update() },
+    () => {
+      update();
+      emit();
+    },
+  );
+  body.el.hidden = true;
+  // re-place for the new height; the picker lays out now
+  colorRow.addEventListener("click", () => {
+    const show = body.el.hidden;
+    body.el.hidden = !show;
+    colorRow.setAttribute("aria-expanded", String(show));
+    pop_.reflow();
+  });
+  pop.append(stage, insetRow, fields, colorRow, body.el);
+  root.append(pop);
+
+  const cssAt = (k: number) =>
+    `${inset ? "inset " : ""}${lengths()
+      .map((n) => `${fmt(n * k)}px`)
+      .join(" ")} ${body.get()}`;
+  const value = (): ShadowValue => {
+    const [x, y, blur, spread] = lengths().map((n) => +fmt(n));
+    return { inset, x, y, blur, spread, color: body.get(), css: cssAt(1) };
+  };
+  const emit = () => onChange(value());
+  const update = () => {
+    card.style.boxShadow = cssAt(1);
+    chipTile.style.boxShadow = cssAt(0.3);
+    const [x, y, blur, spread] = lengths();
+    valueEl.textContent = `${inset ? tr("inset", "in") + " " : ""}${fmt(x)} ${fmt(y)} ${fmt(blur)}${spread ? " " + fmt(spread) : ""}`;
+    cSwatch.style.background = body.swatchCss();
+    cText.textContent = body.valueText();
+  };
+  const pop_ = popover(root, trigger, pop, { fallbackH: 300, onOpen: body.reflow, onReflow: body.reflow });
+  update();
+
+  // Set/restore: the object form or a strict box-shadow string; `css` is ignored, and the color goes through the
+  // picker.
+  const set = (v: unknown) => {
+    const inp = read(v);
+    if (!inp) return;
+    if (inp.inset != null) {
+      inset = !!inp.inset;
+      insetSeg.set(inset ? "inner" : "outer");
+    }
+    (
+      [
+        ["x", fx],
+        ["y", fy],
+        ["blur", fb],
+        ["spread", fs],
+      ] as const
+    ).forEach(([k, f]) => {
+      if (inp[k] != null) f.set(num(inp[k], f.get()));
+    });
+    if (typeof inp.color === "string" && isColor(inp.color)) body.set(inp.color);
+    update();
+  };
+  return { el: root, set, get: value };
+}
+
+registerControl("shadow", createShadow);

package/src/tweaks/controls/sides.ts

@@ -0,0 +1,196 @@
+// ── Sides — one row for a four-sided length (padding, margin, border width, or with `corners` a radius): one field
+// linked; unlinked, the row opens in place and four fields sit in a line under it, in CSS order, each under its glyph.
+// The value is the four numbers in CSS order plus the shorthand `css`, built only from the numbers and the unit —
+// never a host string. Lazy. ──
+import { el, txt, btn, icon, registerControl, stepPrecision, words } from "../shared.js";
+import { numField, decimalStep } from "../heavy.js";
+import type { OnChange, NumField } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control, SidesValue } from "../types.js";
+
+// original: the four corner arcs of a rounded box, apart
+const ICON_SPLIT = icon(
+  '<path d="M3 9V7a4 4 0 0 1 4-4h2M15 3h2a4 4 0 0 1 4 4v2M21 15v2a4 4 0 0 1-4 4h-2M9 21H7a4 4 0 0 1-4-4v-2"/>',
+);
+// original: the top-left quarter of a rounded box, turned per corner in CSS
+const ICON_CORNER = icon('<path d="M3 13V8a5 5 0 0 1 5-5h5"/>', "", 1.5, 16);
+// original: the top of that box, two of its corners joined, turned per side
+const ICON_EDGE = icon('<path d="M3 10V8a5 5 0 0 1 5-5a5 5 0 0 1 5 5v2"/>', "", 1.5, 16);
+const LEN_RE = /^(-?\d*\.?\d+)([a-z%]*)$/i;
+const num = (v: unknown) => (v != null && v !== "" && Number.isFinite(+v) ? +v : null);
+const expand = (n: number[]) =>
+  n.length === 1
+    ? [n[0], n[0], n[0], n[0]]
+    : n.length === 2
+      ? [n[0], n[1], n[0], n[1]]
+      : n.length === 3
+        ? [n[0], n[1], n[2], n[1]]
+        : n.slice(0, 4);
+// A shorthand string as one to four [number, unit] pairs, or null for anything else: calc(), var(), five lengths, junk.
+const lengths = (s: string) => {
+  const m = s
+    .trim()
+    .split(/\s+/)
+    .map((t) => LEN_RE.exec(t));
+  return m.length <= 4 && m.every(Boolean)
+    ? (m as RegExpExecArray[]).map((x) => [+x[1], x[2].toLowerCase()] as const)
+    : null;
+};
+// Any form to four numbers, or null; an object fills in from `cur`, so `{ top: 4 }` moves one side.
+const read = (v: unknown, cur: number[]): number[] | null => {
+  if (typeof v === "number") return Number.isFinite(v) ? [v, v, v, v] : null;
+  if (typeof v === "string") {
+    const n = lengths(v);
+    return n ? expand(n.map((x) => x[0])) : null;
+  }
+  if (Array.isArray(v)) {
+    const n = v.map(num);
+    return n.length >= 1 && n.length <= 4 && n.every((x) => x !== null) ? expand(n as number[]) : null;
+  }
+  if (v && typeof v === "object") {
+    const o = v as Record<string, unknown>,
+      out = cur.slice();
+    let any = false;
+    (["top", "right", "bottom", "left"] as const).forEach((k, i) => {
+      const x = num(o[k]);
+      if (x !== null) {
+        out[i] = x;
+        any = true;
+      }
+    });
+    return any ? out : null;
+  }
+  return null;
+};
+
+// The unit a shorthand string says, when its sides agree: "1rem 2rem" is rem, and so is "0 1rem 2". A zero doesn't
+// vote, as 0 is 0 in any unit. Mixed units can't be kept, since the control edits four numbers in one unit, so they
+// warn and read as px, as every string did before; "" when the string names no unit.
+const saidUnit = (v: unknown, name: string, sides: string[]) => {
+  const n = typeof v === "string" && lengths(v);
+  if (!n) return "";
+  const said = expand(n.map((_, i) => i))
+    .map((i, s) => [sides[s].toLowerCase(), n[i][0] ? n[i][1] : ""])
+    .filter(([, u]) => u);
+  if (new Set(said.map(([, u]) => u)).size < 2) return said.length ? said[0][1] : "";
+  console.warn(
+    `[tweaks] sides "${name}": "${v}" mixes units (${said.map((s) => s.join(" ")).join(", ")}) and the control edits one, so all four read as px; write one unit, or set unit`,
+  );
+  return "";
+};
+
+function createSides(meta: Meta, onChange: OnChange): Control {
+  const corners = !!meta.corners,
+    names = corners ? ["Top-left", "Top-right", "Bottom-right", "Bottom-left"] : ["Top", "Right", "Bottom", "Left"];
+  // topLeft …; `names` stays the glyph's data-at
+  const tr = words(),
+    shown = names.map((n) =>
+      tr(
+        n.toLowerCase().replace(/-(\w)/, (_, c) => c.toUpperCase()),
+        n,
+      ),
+    );
+  const name = meta.label || meta.key,
+    init = meta.value ?? meta;
+  // an explicit unit wins over the string's
+  const unit = (typeof meta.unit === "string" && meta.unit.trim()) || saidUnit(init, name, names) || "px";
+  let v = read(init, [0, 0, 0, 0]);
+  // No step: 1, or finer when a side has decimals, so "0.5rem 1.25rem" keeps its quarter rem (decimalStep, as the
+  // number's).
+  // a radius can't go negative; a margin can
+  const spec = {
+    step: meta.step ?? Math.min(1, ...(v || []).map(decimalStep)),
+    min: meta.min ?? (corners ? 0 : undefined),
+    max: meta.max,
+    unit,
+  };
+  // the readout and css at the step's decimals, so 0.125rem isn't 0.13rem
+  const fmt = (n: number) => String(+n.toFixed(Math.max(2, stepPrecision(+spec.step))));
+  // A default it can't read still starts at 0, but says so: a padding that quietly lost its value looks like the page's
+  // bug.
+  // An object naming no side stays quiet, as markup hands its whole dataset over when there's no data-value.
+  if (!v && meta.value != null && (typeof meta.value !== "object" || Array.isArray(meta.value)))
+    console.warn(
+      `[tweaks] sides "${name}": can't read ${JSON.stringify(meta.value)?.slice(0, 60)}, so it starts at 0; it takes one to four numbers or plain lengths, like "8px 16px"`,
+    );
+  v = v || [0, 0, 0, 0];
+  let linked = v.every((x) => x === v[0]);
+  const root = el("div", "twk-sides");
+  const all = numField({ label: meta.label, value: v[0], row: true, ...spec }, (n) => {
+    v = [n, n, n, n];
+    update();
+    emit();
+  });
+  // One toggle, moved to whichever block is showing; last in both, so it sits on the same pixels either way. It says
+  // what a click opens — each corner or side on its own — and is pressed while they are.
+  const split = corners ? tr("splitCorners", "Independent corners") : tr("splitSides", "Independent sides");
+  const link = btn("twk-sides-link", ICON_SPLIT);
+  link.setAttribute("aria-label", split);
+  link.title = split;
+  link.addEventListener("click", () => toggle());
+  // The head has the row's geometry, so opening moves nothing: the readout takes the field's place, with the unit once.
+  const multi = el("div", "twk-sides-multi"),
+    head = el("div", "twk-sides-head"),
+    sum = el("span", "twk-sides-sum"),
+    nums = document.createTextNode("");
+  sum.append(nums, txt("span", "twk-sides-unit", unit));
+  head.append(txt("span", "twk-row-label", meta.label), sum);
+  const fields = el("div", "twk-fields");
+  const flds: NumField[] = shown.map((n, i) =>
+    numField({ label: n, value: v[i], ...spec }, (x) => {
+      v[i] = x;
+      update();
+      emit();
+    }),
+  );
+  // The input and the tooltip carry the full name; on screen each field wears its glyph, one drawing turned per place.
+  flds.forEach((f, i) => {
+    const lab = f.el.querySelector<HTMLElement>(".twk-field-label")!;
+    lab.title = shown[i];
+    lab.classList.add("twk-sides-glyph");
+    lab.dataset.at = names[i].toLowerCase();
+    lab.innerHTML = corners ? ICON_CORNER : ICON_EDGE;
+    fields.append(f.el);
+  });
+  multi.append(head, fields);
+  root.append(all.el, multi);
+  // As the fields fitted them.
+  v = flds.map((f) => f.get());
+
+  const css = () => {
+    const [t, r, b, l] = v.map(fmt),
+      u = (s: string) => (s === "0" ? "0" : s + unit);
+    return (t === b && r === l ? (t === r ? [t] : [t, r]) : r === l ? [t, r, b] : [t, r, b, l]).map(u).join(" ");
+  };
+  const value = (): SidesValue => ({ top: v[0], right: v[1], bottom: v[2], left: v[3], css: css() });
+  const emit = () => onChange(value());
+  const update = () => {
+    root.classList.toggle("is-linked", linked);
+    link.setAttribute("aria-pressed", String(!linked));
+    (linked ? all.el : head).append(link);
+    all.set(v[0]);
+    flds.forEach((f, i) => f.set(v[i]));
+    nums.data = v.map(fmt).join(" ");
+  };
+  const toggle = () => {
+    linked = !linked;
+    if (linked) v = [v[0], v[0], v[0], v[0]];
+    update();
+    emit();
+    link.focus();
+  };
+  update();
+
+  // Set/restore: equal sides re-link, unequal ones unlink, so a restored "8 16 8 16" opens the fields it needs.
+  const set = (x: unknown) => {
+    const n = read(x, v);
+    if (!n) return;
+    flds.forEach((f, i) => f.set(n[i]));
+    v = flds.map((f) => f.get());
+    linked = v.every((s) => s === v[0]);
+    update();
+  };
+  return { el: root, set, get: value, range: all.range };
+}
+
+registerControl("sides", createSides);

package/src/tweaks/controls/spring.ts

@@ -0,0 +1,308 @@
+// ── Spring config — physics (stiffness/damping/mass) or a perceptual time (duration/bounce) mode, over one settle-curve preview. Lazy. ──
+import { el, txt, onReady, onLive, clamp, createSegmented, registerControl, words } from "../shared.js";
+import {
+  dragGesture,
+  numField,
+  cssVar,
+  accentColor,
+  springCurve,
+  springFromTime,
+  boxFrac,
+  notice,
+  SPRING_DUR,
+} from "../heavy.js";
+import type { OnChange, NumField } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control } from "../types.js";
+
+type SpringMode = "time" | "physics";
+/** The physics triple every emitted value carries. */
+interface Phys {
+  stiffness: number;
+  damping: number;
+  mass: number;
+}
+type PhysKey = keyof Phys;
+/** The perceptual pair the time mode edits. */
+interface SpringTime {
+  visualDuration: number;
+  bounce: number;
+}
+/** What set() accepts: any subset of the physics, the time pair and an explicit mode. */
+type SpringValue = Partial<Phys & SpringTime & { mode: SpringMode }>;
+
+function createSpring(meta: Meta, onChange: OnChange): Control {
+  const tr = words();
+  // The fields' floors, non-finite to the defaults: a stiffness or mass of 0 would divide the settle curve to NaN.
+  const cl = (v: unknown, lo: number, def: number) => (Number.isFinite(+v) ? Math.max(lo, +v) : def);
+  const clampS = (o: { stiffness?: unknown; damping?: unknown; mass?: unknown }): Phys => ({
+    stiffness: cl(o.stiffness, 1, 300),
+    damping: cl(o.damping, 0.5, 26),
+    mass: cl(o.mass, 0.1, 1),
+  });
+  const has = (x: unknown) => Number.isFinite(+x);
+
+  // Time mode edits visualDuration + bounce (Motion's spring shorthand), mapped onto the physics the preview and emit
+  // share exactly as Motion resolves them (springFromTime): stiffness = (2π / (visualDuration × 1.2))², ζ from bounce
+  // floored at
+  // 0.05, a negative bounce overdamped. Not through the physics pad's clamps, which would cut a short spring's
+  // stiffness.
+  // An authored duration past the editor's range is clamped, and the console says so once.
+  const [DUR_MIN, DUR_MAX] = SPRING_DUR;
+  let said = false;
+  const clampDur = (v: unknown) => {
+    const n = has(v) ? +v : 0.5,
+      c = clamp(n, DUR_MIN, DUR_MAX);
+    if (c !== n && !said) {
+      said = true;
+      notice("springDur", [meta.key, n, c]);
+    }
+    return c;
+  };
+  const clampBounce = (v: unknown) => clamp(has(v) ? +v : 0.2, -1, 1); // Motion takes a negative bounce: overdamped
+  // Ten significant figures: the trig round trip otherwise hands back 300.00000000000006 for a stiffness of 300.
+  const sig = (x: number) => +x.toPrecision(10);
+  const timeToPhysics = (t: SpringTime): Phys => {
+    const p = springFromTime(t.visualDuration, t.bounce);
+    return { stiffness: sig(p.stiffness), damping: sig(p.damping), mass: p.mass };
+  };
+
+  // Top-level props (the inline shorthand) or the `value:{…}` form, value winning; the mode is explicit or inferred,
+  // time winning.
+  const explicit = (m: unknown): SpringMode | null => (m === "time" || m === "physics" ? m : null);
+  const init = {
+    stiffness: meta.stiffness,
+    damping: meta.damping,
+    mass: meta.mass,
+    visualDuration: meta.visualDuration,
+    bounce: meta.bounce,
+    ...(meta.value || {}),
+  };
+  let mode: SpringMode =
+    explicit(init.mode) ?? explicit(meta.mode) ?? (has(init.visualDuration) || has(init.bounce) ? "time" : "physics");
+  const time: SpringTime = { visualDuration: clampDur(init.visualDuration), bounce: clampBounce(init.bounce) };
+  let phys = clampS({ stiffness: init.stiffness, damping: init.damping, mass: init.mass });
+
+  const root = el("div", "twk-spring");
+  const viz = el("div", "twk-spring-viz");
+  const canvas = document.createElement("canvas");
+  canvas.className = "twk-spring-canvas";
+  viz.append(canvas);
+  const physFields = el("div", "twk-fields");
+  const timeFields = el("div", "twk-fields");
+  const ctx = canvas.getContext("2d");
+
+  // The preview and the emitted value both read this, so they can never disagree.
+  const resolved = () => (mode === "time" ? timeToPhysics(time) : clampS(phys));
+  const draw = () => {
+    // Layout size: getBoundingClientRect includes the pop's entrance scale.
+    const w = Math.max(1, viz.clientWidth),
+      h = Math.max(1, viz.clientHeight);
+    if (w < 2) return;
+    const dpr = window.devicePixelRatio || 1;
+    canvas.width = w * dpr;
+    canvas.height = h * dpr;
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, w, h);
+    const s = resolved();
+    // Sample ~one point per device pixel so fast oscillations stay smooth, not angular.
+    const pts = springCurve(s.stiffness, s.damping, s.mass, Math.max(160, Math.round(w * dpr)));
+    const peak = Math.max(1.05, ...pts),
+      pad = 8; // the bezier editor's PAD, so the two previews inset alike
+    const X = (i: number) => pad + (i / (pts.length - 1)) * (w - 2 * pad);
+    const Y = (v: number) => h - pad - (v / peak) * (h - 2 * pad);
+    ctx.strokeStyle = cssVar(root, "--twk-surface-active") || "rgba(255,255,255,0.1)";
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.moveTo(pad, Y(1));
+    ctx.lineTo(w - pad, Y(1));
+    ctx.stroke(); // target (=1)
+    ctx.strokeStyle = accentColor(root);
+    ctx.lineWidth = 1.5;
+    ctx.lineJoin = ctx.lineCap = "round";
+    ctx.beginPath();
+    pts.forEach((v, i) => (i ? ctx.lineTo(X(i), Y(v)) : ctx.moveTo(X(i), Y(v))));
+    ctx.stroke();
+  };
+  // The resolved {k,d,m} plus, in time mode, visualDuration/bounce, from which set() infers the mode back from
+  // persistence.
+  const resolvedValue = (): Phys & Partial<SpringTime> =>
+    mode === "time" ? { ...resolved(), visualDuration: time.visualDuration, bounce: time.bounce } : resolved();
+  const emit = () => onChange(resolvedValue());
+
+  const flds: Partial<Record<PhysKey, NumField>> = {};
+  (
+    [
+      ["stiffness", "Stiffness", 1],
+      ["damping", "Damping", 0.5],
+      ["mass", "Mass", 0.1],
+    ] as const
+  ).forEach(([key, lab, step]) => {
+    flds[key] = numField({ label: tr(key, lab), value: phys[key], step, min: step }, (v) => {
+      phys[key] = v;
+      draw();
+      emit();
+    });
+    physFields.append(flds[key].el);
+  });
+  // The field shows ms; the value stays Motion's visualDuration in seconds.
+  const durFld = numField(
+    {
+      label: tr("duration", "Duration"),
+      value: time.visualDuration * 1000,
+      step: 10,
+      min: DUR_MIN * 1000,
+      max: DUR_MAX * 1000,
+      unit: "ms",
+    },
+    (v) => {
+      time.visualDuration = clampDur(v / 1000);
+      draw();
+      emit();
+    },
+  );
+  // shown as a percentage; the value stays Motion's −1–1
+  const bounceFld = numField(
+    { label: tr("bounce", "Bounce"), value: time.bounce * 100, step: 5, min: -100, max: 100, unit: "%" },
+    (v) => {
+      time.bounce = clampBounce(v / 100);
+      draw();
+      emit();
+    },
+  );
+  timeFields.append(durFld.el, bounceFld.el);
+
+  const showMode = () => {
+    timeFields.style.display = mode === "time" ? "" : "none";
+    physFields.style.display = mode === "physics" ? "" : "none";
+  };
+  const switchMode = (m: unknown) => {
+    if ((m !== "time" && m !== "physics") || m === mode) return;
+    mode = m;
+    showMode();
+    draw();
+    emit();
+  };
+  const modeToggle = createSegmented(
+    [
+      { value: "time", label: tr("time", "Time") },
+      { value: "physics", label: tr("physics", "Physics") },
+    ],
+    mode,
+    switchMode,
+    tr("springMode", "Spring mode"),
+  );
+  const modeRow = el("div", "twk-row");
+  modeRow.append(txt("span", "twk-row-label", tr("mode", "Mode")), modeToggle.el);
+  // A caption, so two springs in one panel can be told apart and the filter matches shown text.
+  if (meta.label) root.append(txt("div", "twk-spring-label", meta.label));
+  root.append(viz, modeRow, physFields, timeFields);
+
+  // Drag the preview to tune by feel: horizontal sets stiffness or duration, vertical sets damping or bounce.
+  // the feel-tuning span; the fields reach further
+  const ST_MIN = 1,
+    ST_MAX = 500,
+    DA_MIN = 1,
+    DA_MAX = 40,
+    DRAG_DUR_MIN = 0.1,
+    DRAG_DUR_MAX = 1;
+  const fromPointer = (e: PointerEvent) => {
+    const [px, py] = boxFrac(e, viz);
+    // Set the field (it snaps and clamps), then read back, so readout, value and preview agree.
+    if (mode === "time") {
+      durFld.set((DRAG_DUR_MIN + px * (DRAG_DUR_MAX - DRAG_DUR_MIN)) * 1000);
+      time.visualDuration = durFld.get() / 1000;
+      // top = bounce 100%, the middle 0, the bottom −100% (overdamped)
+      bounceFld.set((1 - 2 * py) * 100);
+      time.bounce = bounceFld.get() / 100;
+    } else {
+      flds.stiffness.set(ST_MIN + px * (ST_MAX - ST_MIN));
+      phys.stiffness = flds.stiffness.get();
+      flds.damping.set(DA_MIN + py * (DA_MAX - DA_MIN));
+      phys.damping = flds.damping.get(); // top = low damping
+    }
+    draw();
+    emit();
+  };
+  dragGesture(viz, {
+    onDown: (e) => {
+      e.preventDefault();
+      viz.classList.add("is-dragging");
+      fromPointer(e);
+    },
+    onMove: fromPointer,
+    onEnd: () => viz.classList.remove("is-dragging"),
+  });
+  showMode();
+  onReady(draw);
+  // The canvas reads theme tokens at draw time: redraw on resize, on a tab page revealing it (twk-reflow; it built at
+  // 0×0 while hidden), on an OS scheme flip and on a host re-theme — CSS re-themes the SVG controls, a canvas keeps a
+  // stale color.
+  onLive(
+    canvas,
+    [
+      [window, "resize"],
+      [window, "twk-reflow"],
+      [matchMedia("(prefers-color-scheme: dark)"), "change"],
+      [window, "twk-retheme"],
+    ],
+    draw,
+  );
+  // A host flipping [data-twk-scheme] re-themes through CSS alone; the canvas needs a redraw. Let go once mounted and
+  // removed.
+  // The redraw waits a frame, for a shadow panel's own observer to mirror the pin first.
+  let schemeObs: MutationObserver | null = null,
+    wasMounted = false;
+  if (typeof MutationObserver === "function") {
+    schemeObs = new MutationObserver(() => {
+      if (canvas.isConnected) {
+        wasMounted = true;
+        requestAnimationFrame(draw);
+      } else if (wasMounted) {
+        schemeObs.disconnect();
+        schemeObs = null;
+      }
+    });
+    schemeObs.observe(document.documentElement, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["data-twk-scheme"],
+    });
+  }
+  return {
+    el: root,
+    destroy: () => {
+      if (schemeObs) {
+        schemeObs.disconnect();
+        schemeObs = null;
+      }
+    },
+    // Silent set/restore: infer the mode from the keys, update caches and fields, redraw without emitting.
+    set: (v: SpringValue) => {
+      if (!v || typeof v !== "object") return;
+      const ex = explicit(v.mode),
+        hasTime = has(v.visualDuration) || has(v.bounce),
+        hasPhys = has(v.stiffness) || has(v.damping) || has(v.mass);
+      if (!hasTime && !hasPhys && !ex) return;
+      mode = ex ?? (hasTime ? "time" : "physics"); // an explicit mode wins; else time, the authoring mode
+      if (hasTime) {
+        if (has(v.visualDuration)) time.visualDuration = clampDur(v.visualDuration);
+        if (has(v.bounce)) time.bounce = clampBounce(v.bounce);
+      }
+      // Restore the physics cache even alongside time keys (reset's default carries both), so a later toggle to Physics
+      // shows the intended spring.
+      if (hasPhys) phys = clampS({ ...phys, ...v });
+      modeToggle.set(mode);
+      durFld.set(time.visualDuration * 1000);
+      bounceFld.set(time.bounce * 100);
+      flds.stiffness.set(phys.stiffness);
+      flds.damping.set(phys.damping);
+      flds.mass.set(phys.mass);
+      showMode();
+      draw();
+    },
+    get: () => resolvedValue(),
+  };
+}
+
+registerControl("spring", createSpring);