tweakit 0.5.2 → 0.6.0

package/src/tweaks/controls/point.ts

@@ -0,0 +1,119 @@
+// ── Point — 2D/3D/4D vector. Lazy.
+import { el, clamp, stepPrecision, defaultRange, popover, registerControl } from "../shared.js";
+import { numField, svgEl, grabSurface, boxFrac, arrowStep, sayWhenKeysStop, triggerRow, decimalStep } from "../heavy.js";
+import type { OnChange, Built } from "../shared.js";
+import type { Meta, PointComponent } from "../schema.js";
+import type { Control } from "../types.js";
+
+// A trigger row opens the 2D pad over the component fields in a popover. The fields hold the values; readout, thumb
+// and emitted map read off them. `pad: false` opts out.
+function createPoint(meta: Meta, onChange: OnChange): Control {
+  const comps = meta.components; // [{ key, label, value, step, min, max }]
+
+  // ── Trigger row — label + value + a mini pad preview. ──
+  const { root, trigger, right } = triggerRow("tw-point", meta.label ?? "Point"); // ??: an explicit "" label renders none
+  const valueEl = el("span", "tw-trigger-value");
+  const preview = el("div", "tw-trigger-chip tw-point-preview");
+  const previewDot = el("div", "tw-point-preview-dot");
+  preview.append(previewDot);
+  right.append(preview, valueEl); // chip first, as every chip row
+
+  // ── Popover — the 2D pad over the component fields. ──
+  const pop = el("div", "tw-color-pop tw-point-pop");
+  const body = el("div", "tw-point-body");
+  pop.append(body);
+
+  const hasPad = meta.pad !== false && comps.length >= 2;
+  // An absent bound is the unit range widened to hold the value, mirrored about the origin (5 spans ±15); an absent
+  // step is the decade at or below range/200, so the pad is continuous, and finer when the default or min sits between
+  // its steps (337 over ±1011 stepped by 10 to 340), as the slider's step fits its default.
+  const rangeOf = (c: PointComponent) => {
+    const half = defaultRange(Math.abs(Number.isFinite(+c.value) ? +c.value : 0))[1];
+    let lo = c.min ?? -half, hi = c.max ?? half;
+    // A lone bound at or past the other end spans from itself instead, as the slider's does (min 5 over 0 spans 5–35, not 5–1, swapped).
+    if ((c.min == null) !== (c.max == null) && !(hi > lo)) { const w = 2 * defaultRange(Math.abs(+(c.min ?? c.max)!))[1]; if (c.min == null) lo = hi - w; else hi = lo + w; }
+    const fine = 10 ** Math.floor(Math.log10((hi - lo) / 200)), nudge = c.step ?? (fine > 0 && Number.isFinite(fine) ? fine : 1); // a degenerate range (hi ≤ lo, NaN) keeps a step of 1
+    return { lo, hi, nudge, step: c.step ?? Math.min(nudge, decimalStep(c.value), decimalStep(c.min)) }; // the pad's arrows keep the decade: 3.14159's 0.00001 would crawl
+  };
+  const ranges = comps.map(rangeOf);
+  const rx = ranges[0], ry = ranges[1];
+  const minX = rx?.lo ?? -1, maxX = rx?.hi ?? 1, minY = ry?.lo ?? -1, maxY = ry?.hi ?? 1;
+  const frac = (v: number, lo: number, hi: number) => (hi > lo ? clamp((v - lo) / (hi - lo), 0, 1) : 0.5);
+
+  let padHost: HTMLDivElement | null = null, padThumb: HTMLDivElement | null = null, padLine: Built<SVGLineElement> | null = null;
+  if (hasPad) {
+    padHost = el("div", "tw-pad");
+    padThumb = el("div", "tw-pad-thumb");
+    // A tether from the origin to the thumb, so the point reads as a vector; the pad is square so the angle is true.
+    const padSvg = svgEl("svg", "tw-pad-line"); padSvg.setAttribute("viewBox", "0 0 100 100"); padSvg.setAttribute("preserveAspectRatio", "none");
+    padLine = svgEl("line"); padSvg.append(padLine);
+    // The origin is fixed for the control's life: set x1/y1 once.
+    const oy0 = frac(0, minY, maxY); padLine.setAttribute("x1", frac(0, minX, maxX) * 100); padLine.setAttribute("y1", (meta.invertY ? oy0 : 1 - oy0) * 100);
+    padHost.append(el("div", "tw-pad-axis tw-pad-axis-x"), el("div", "tw-pad-axis tw-pad-axis-y"), padSvg, padThumb);
+    body.append(padHost);
+  }
+
+  const fields = el("div", "tw-fields");
+  body.append(fields);
+  const sync = () => { positionPad(); paintValue(); };
+  const emit = () => onChange(read());
+  const flds = comps.map((c, k) => {
+    const fld = numField({ label: c.label, value: c.value ?? 0, step: ranges[k].step, min: c.min, max: c.max }, () => { sync(); emit(); });
+    fields.append(fld.el); return fld;
+  });
+  const read = () => Object.fromEntries(comps.map((c, k) => [c.key, flds[k].get()])); // the emitted map, straight off the fields
+
+  // Readout: the components at each step's precision, so a value reads "−1.00, −0.46" (steady columns), not "−1, −0.46".
+  const fmt = (v: number, step: number) => (+v).toFixed(stepPrecision(step));
+  const paintValue = () => { valueEl.textContent = flds.map((f, k) => fmt(f.get(), ranges[k].step)).join(", "); };
+  let positionPad = () => { previewDot.style.left = "50%"; previewDot.style.top = "50%"; };
+
+  if (hasPad) {
+    // The mini preview is clipped, so inset the 5px dot: its center travels from +2.5px at 0 to −2.5px at 1.
+    const DOT = 5;
+    const inset = (f: number) => `calc(${(f * 100).toFixed(2)}% + ${((0.5 - f) * DOT).toFixed(2)}px)`;
+    positionPad = () => {
+      const fx = frac(flds[0].get(), minX, maxX), fyv = frac(flds[1].get(), minY, maxY);
+      const tyFrac = meta.invertY ? fyv : 1 - fyv;
+      const tx = fx * 100, ty = tyFrac * 100;
+      padThumb.style.left = tx + "%"; padThumb.style.top = ty + "%";
+      previewDot.style.left = inset(fx); previewDot.style.top = inset(tyFrac); // mini pad: dot stays in bounds
+      padLine.setAttribute("x2", tx); padLine.setAttribute("y2", ty);
+      padHost.setAttribute("aria-description", `${comps[0].label ?? comps[0].key} ${fmt(flds[0].get(), rx.step)}, ${comps[1].label ?? comps[1].key} ${fmt(flds[1].get(), ry.step)}`); // the pad's live readout for assistive tech
+    };
+    const padSet = (e: PointerEvent) => {
+      const [fx, fy] = boxFrac(e, padHost); const yFrac = meta.invertY ? fy : 1 - fy;
+      flds[0].set(minX + fx * (maxX - minX)); flds[1].set(minY + yFrac * (maxY - minY));
+      sync(); emit();
+    };
+    grabSurface(padHost, padSet);
+    // Keyboard: a focusable group (no ARIA role fits a 2D point; the readout rides on aria-description). Arrows move a
+    // pad step (⇧ = ten), ↑ always up on screen; Home restores the default. Escape is the popover's — a blur here would close it first.
+    padHost.tabIndex = 0; padHost.setAttribute("role", "group");
+    padHost.setAttribute("aria-label", `${meta.label ?? "Point"} pad: ${comps[0].label ?? comps[0].key} and ${comps[1].label ?? comps[1].key}`);
+    const say = sayWhenKeysStop(padHost);
+    padHost.addEventListener("keydown", (e) => {
+      if (e.key === "Home") { e.preventDefault(); comps.forEach((c, k) => flds[k].set(c.value ?? 0)); sync(); emit(); say(); return; }
+      const [dx, dy] = arrowStep(e);
+      if (!dx && !dy) return;
+      e.preventDefault();
+      const k = e.shiftKey ? 10 : 1;
+      if (dx) flds[0].set(clamp(flds[0].get() + dx * rx.nudge * k, minX, maxX));
+      if (dy) flds[1].set(clamp(flds[1].get() + (meta.invertY ? -dy : dy) * ry.nudge * k, minY, maxY));
+      sync(); emit(); say();
+    });
+  }
+
+  root.append(pop);
+  popover(root, trigger, pop, { fallbackH: 240, onOpen: sync });
+  sync();
+
+  return {
+    el: root,
+    set: (v: Record<string, number | string>) => { if (v) comps.forEach((c, k) => { if (v[c.key] != null) flds[k].set(v[c.key]); }); sync(); },
+    get: read,
+    range: Object.fromEntries(comps.map((c, k) => [c.key, flds[k].range])),
+  };
+}
+
+registerControl("point", createPoint);

package/src/tweaks/controls/shadow.ts

@@ -0,0 +1,83 @@
+// ── 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 } 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] };
+};
+
+const CHEVRON = icon('<path d="M18 9s-4.4 6-6 6-6-6-6-6"/>', "tw-shadow-chevron", 2.5); // the kit's chevron; importing icons.ts splits a 4th chunk
+function createShadow(meta: Meta, onChange: OnChange): Control {
+  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. ──
+  const { root, trigger, right } = triggerRow("tw-shadow", meta.label ?? "Shadow"); // ??: an explicit "" label renders none
+  const chip = el("span", "tw-trigger-chip tw-shadow-chip"), chipTile = el("span", "tw-shadow-chip-tile"); chip.append(chipTile);
+  const valueEl = el("span", "tw-trigger-value");
+  right.append(chip, valueEl);
+
+  // ── Popover — a preview card, the position switch, the four lengths, the picker. ──
+  const pop = el("div", "tw-color-pop tw-shadow-pop");
+  const stage = el("div", "tw-shadow-stage"), card = el("div", "tw-shadow-card"); stage.append(card);
+  const insetSeg = createSegmented([{ value: "outer", label: "Outer" }, { value: "inner", label: "Inner" }], inset ? "inner" : "outer", (m: unknown) => { if ((m === "inner") !== inset) { inset = m === "inner"; update(); emit(); } }, "Shadow position");
+  const insetRow = el("div", "tw-row"); insetRow.append(txt("span", "tw-row-label", "Position"), insetSeg.el);
+  const fields = el("div", "tw-fields tw-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("Blur", num(init.blur, DEF.blur), 0), fs = field("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("tw-trigger tw-shadow-color"); colorRow.setAttribute("aria-expanded", "false");
+  const cSwatch = el("span", "tw-trigger-chip tw-color-swatch"), cText = el("span", "tw-trigger-value"), cRight = el("span", "tw-trigger-right");
+  cRight.append(cSwatch, cText); cRight.insertAdjacentHTML("beforeend", CHEVRON); colorRow.append(txt("span", "tw-trigger-label", "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;
+  colorRow.addEventListener("click", () => { const show = body.el.hidden; body.el.hidden = !show; colorRow.setAttribute("aria-expanded", String(show)); pop_.reflow(); }); // re-place for the new height; the picker lays out now
+  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 ? "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,86 @@
+// ── 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 } 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";
+
+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 four corner arcs of a rounded box, apart
+const ICON_CORNER = icon('<path d="M3 13V8a5 5 0 0 1 5-5h5"/>', "", 1.5, 16); // original: the top-left quarter of a rounded box, turned per corner in CSS
+const ICON_EDGE = icon('<path d="M3 10V8a5 5 0 0 1 5-5a5 5 0 0 1 5 5v2"/>', "", 1.5, 16); // original: the top of that box, two of its corners joined, turned per side
+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"];
+  const name = meta.label || meta.key, init = meta.value ?? meta;
+  const unit = (typeof meta.unit === "string" && meta.unit.trim()) || saidUnit(init, name, names) || "px"; // an explicit unit wins over the string's
+  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).
+  const spec = { step: meta.step ?? Math.min(1, ...(v || []).map(decimalStep)), min: meta.min ?? (corners ? 0 : undefined), max: meta.max, unit }; // a radius can't go negative; a margin can
+  const fmt = (n: number) => String(+n.toFixed(Math.max(2, stepPrecision(+spec.step)))); // the readout and css at the step's decimals, so 0.125rem isn't 0.13rem
+  // 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", "tw-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 ? "Independent corners" : "Independent sides";
+  const link = btn("tw-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", "tw-sides-multi"), head = el("div", "tw-sides-head"), sum = el("span", "tw-sides-sum"), nums = document.createTextNode("");
+  sum.append(nums, txt("span", "tw-sides-unit", unit)); head.append(txt("span", "tw-row-label", meta.label), sum);
+  const fields = el("div", "tw-fields");
+  const flds: NumField[] = names.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>(".tw-field-label")!; lab.title = names[i]; lab.classList.add("tw-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,148 @@
+// ── 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 } 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 {
+  // 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", "tw-spring");
+  const viz = el("div", "tw-spring-viz");
+  const canvas = document.createElement("canvas"); canvas.className = "tw-spring-canvas"; viz.append(canvas);
+  const physFields = el("div", "tw-fields");
+  const timeFields = el("div", "tw-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, "--tw-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: 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: "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(); });
+  const bounceFld = numField({ label: "Bounce", value: time.bounce * 100, step: 5, min: -100, max: 100, unit: "%" }, (v) => { time.bounce = clampBounce(v / 100); draw(); emit(); }); // shown as a percentage; the value stays Motion's −1–1
+  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: "Time" }, { value: "physics", label: "Physics" }], mode, switchMode, "Spring mode");
+  const modeRow = el("div", "tw-row");
+  modeRow.append(txt("span", "tw-row-label", "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", "tw-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.
+  const ST_MIN = 1, ST_MAX = 500, DA_MIN = 1, DA_MAX = 40, DRAG_DUR_MIN = 0.1, DRAG_DUR_MAX = 1; // the feel-tuning span; the fields reach further
+  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;
+      bounceFld.set((1 - 2 * py) * 100); time.bounce = bounceFld.get() / 100; // top = bounce 100%, the middle 0, the bottom −100% (overdamped)
+    } 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 (tw-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, "tw-reflow"], [matchMedia("(prefers-color-scheme: dark)"), "change"], [window, "tw-retheme"]], draw);
+  // A host flipping [data-tw-scheme] re-themes through CSS alone; the canvas needs a redraw. Let go once mounted and removed.
+  let schemeObs: MutationObserver | null = null, wasMounted = false;
+  if (typeof MutationObserver === "function") {
+    schemeObs = new MutationObserver(() => {
+      if (canvas.isConnected) { wasMounted = true; draw(); }
+      else if (wasMounted) { schemeObs.disconnect(); schemeObs = null; }
+    });
+    schemeObs.observe(document.documentElement, { subtree: true, attributes: true, attributeFilter: ["data-tw-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);

package/src/tweaks/controls/tabs.ts

@@ -0,0 +1,47 @@
+// ── Tabs — group controls into pages; build() fills the page bodies. Lazy.
+import { el, txt, onReady, measurePill, navIndex, requestReflow, registerControl } from "../shared.js";
+import type { Meta } from "../schema.js";
+
+/** The tabs handle: a page body per tab for build() to fill, and the active tab for the panel's UI state. */
+export interface TabsControl { el: HTMLDivElement; bodies: HTMLDivElement[]; activate(i: number): void; active(): number }
+
+let tabsSeq = 0; // unique ids for the tab ↔ tabpanel aria pairing
+function createTabs(meta: Meta): TabsControl {
+  const uid = `tw-tabs-${++tabsSeq}`;
+  const root = el("div", "tw-tabs");
+  const bar = el("div", "tw-tabs-bar"); bar.setAttribute("role", "tablist");
+  const pill = el("div", "tw-tabs-pill"); bar.append(pill);
+  const pagesWrap = el("div", "tw-tabs-pages");
+  const bodies: HTMLDivElement[] = [];
+  const tabs = meta.pages.map((page, i) => {
+    const tab = txt("button", "tw-tabs-tab", page.title); tab.setAttribute("role", "tab");
+    tab.id = `${uid}-tab-${i}`; tab.setAttribute("aria-controls", `${uid}-page-${i}`);
+    const body = el("div", "tw-tabs-page tw-controls");
+    body.setAttribute("role", "tabpanel"); body.id = `${uid}-page-${i}`; body.setAttribute("aria-labelledby", tab.id);
+    bodies.push(body); pagesWrap.append(body);
+    tab.addEventListener("click", () => activate(i));
+    bar.append(tab); return tab;
+  });
+  root.append(bar, pagesWrap);
+  const measure = (animate?: boolean) => measurePill(bar, pill, animate); // slide the pill to the active tab
+  // The active tab and page; the roving tabindex is set from the build, not only after a switch.
+  const mark = (i: number) => {
+    tabs.forEach((b, k) => { b.dataset.active = String(k === i); b.setAttribute("aria-selected", String(k === i)); b.tabIndex = k === i ? 0 : -1; });
+    bodies.forEach((b, k) => (b.dataset.active = String(k === i)));
+  };
+  mark(0);
+  function activate(i: number) {
+    mark(i); measure(true);
+    requestReflow(); // controls built on a display:none page measured 0; let them re-measure
+  }
+  bar.addEventListener("keydown", (e) => {
+    const i = tabs.findIndex((b) => b.dataset.active === "true"); if (i < 0) return;
+    const j = navIndex(e.key, i, tabs.length, -1); if (j < 0) return; // cols −1: ↑/↓ stay the page's scroll keys
+    e.preventDefault(); activate(j); tabs[j].focus();
+  });
+  onReady(measure);
+  return { el: root, bodies, activate, active: () => tabs.findIndex((t) => t.dataset.active === "true") };
+}
+
+registerControl("tabs", createTabs);
+

package/src/tweaks/core.ts

@@ -0,0 +1,9 @@
+/* Tweaks — a dependency-free real-time parameter panel. The public entry: tweaks() builds a
+ * live panel from a plain schema object, enhance() turns [data-tw] markup into live controls,
+ * and mountControl() / createColorPicker() / gradientCss() are the controls without the panel. */
+export { tweaks } from "./panel.js";
+export { enhance } from "./enhance.js";
+export { mountControl, createColorPicker } from "./standalone.js";
+export { gradientCss, gradientStops } from "./easing.js";
+// The public types, so `import type { Schema } from "tweakit"` works from either entry.
+export type * from "./types.js";

package/src/tweaks/easing.ts

@@ -0,0 +1,93 @@
+/* Gradient easing + gradient → CSS: the one place a gradient value becomes a stop list, so
+ * the editor draws what a host's CSS draws. Pure string + number work, no DOM.
+ * The eye reads a straight blend's ends as an edge and native easing hasn't shipped
+ * (csswg-drafts#1332), so Larsen's "easing gradients" are generated here: the curve sampled
+ * PARAMETRICALLY at 16 even t (x the position, y the blend), so any cubic-bezier works with
+ * no x→t solve; each sample is a color-mix in the value's own blend space. */
+import type { GradientEasing, GradientStop, GradientValue } from "./types.js";
+
+/** cubic-bezier control points [x1, y1, x2, y2]. */
+export type Bez = [number, number, number, number];
+
+// The CSS easing keywords as cubic-beziers. Null-prototype, so "constructor" can't read a function off Object.prototype.
+export const KEYWORDS: Record<string, Bez> = Object.assign(Object.create(null), {
+  ease: [0.25, 0.1, 0.25, 1], "ease-in": [0.42, 0, 1, 1], "ease-out": [0, 0, 0.58, 1], "ease-in-out": [0.42, 0, 0.58, 1],
+});
+const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
+const SAMPLES = 15; // 16 per segment, Larsen's count; the joins vanish
+
+/** Bezier control points, or null for linear and anything unrecognized (bad input degrades to a
+ *  straight blend). x1/x2 clamp into [0,1] as CSS requires; y may overshoot. */
+export function parseEasing(e: unknown): Bez | null {
+  if (typeof e !== "string") return null;
+  const s = e.trim().toLowerCase();
+  if (KEYWORDS[s]) return KEYWORDS[s];
+  const m = /^cubic-bezier\(([^()]*)\)$/.exec(s); if (!m) return null;
+  const n = m[1].split(",").map((x) => (x.trim() ? Number(x) : NaN)); // an empty field is NaN, not Number("") → 0
+  if (n.length !== 4 || !n.every(Number.isFinite)) return null;
+  return [clamp01(n[0]), n[1], clamp01(n[2]), n[3]];
+}
+
+/** The curve at 16 even t: [x, y] pairs, y clamped to [0,1] since it becomes a color-mix percentage. */
+export function easingSamples(b: Bez): Array<[number, number]> {
+  const out: Array<[number, number]> = [];
+  for (let k = 0; k <= SAMPLES; k++) {
+    const t = k / SAMPLES, u = 1 - t, p1 = 3 * u * u * t, p2 = 3 * u * t * t, p3 = t * t * t;
+    out.push([p1 * b[0] + p2 * b[2] + p3, clamp01(p1 * b[1] + p2 * b[3] + p3)]);
+  }
+  return out;
+}
+
+const pct = (n: number) => +(n * 100).toFixed(2);
+
+// A stop's color is written into the gradient as it is, so it must be one color token: a comma or a stray ")" splices in
+// another layer (a url() the browser fetches), and var() can stand for anything. DOM-free, so by shape: a hex, a keyword,
+// or one function with no nested parens; the editor's picker checks the grammar itself.
+const STOP_COLOR = /^(?:#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})|(?!(?:url|var)\()[a-z][a-z-]*(?:\([\w\s.,%+\-\/]*\))?)$/i;
+// The blend spaces CSS takes, and a hue method on the polar ones; anything else (`in junk`, `in 5`) falls to
+// oklch, the default.
+const INTERP = /^(?:(?:hsl|hwb|lch|oklch)(?: (?:shorter|longer|increasing|decreasing) hue)?|srgb(?:-linear)?|oklab|lab|display-p3|rec2020|a98-rgb|prophoto-rgb|xyz(?:-d50|-d65)?)$/i;
+const blend = (v: GradientValue) => (typeof v.interpolation === "string" && INTERP.test(v.interpolation) ? v.interpolation : "oklch");
+
+/** The stops a value can draw, sorted. A hand-built value can hold no stops, or stops without a
+ *  color or a numeric pos, and any of those builds CSS the browser drops whole, silently;
+ *  so they're set aside with a warning (heavy.ts badGradient, one per distinct fault). */
+function drawable(value: unknown, fn: string): GradientStop[] {
+  const all: unknown = value && typeof value === "object" ? (value as GradientValue).stops : null;
+  const ok = Array.isArray(all) ? all.filter((s) => s && typeof s.color === "string" && STOP_COLOR.test(s.color.trim()) && Number.isFinite(s.pos)) : [];
+  if (!ok.length || ok.length < (all as unknown[]).length) import("./heavy.js").then((m) => m.badGradient(fn, value, all, ok.length), () => {});
+  return ok.sort((a, b) => a.pos - b.pos);
+}
+
+/** A gradient value's `<color-stop-list>` with the easing expanded; for a conic / radial gradient.
+ *  One stop comes back doubled and none as `transparent, transparent`, so the list stays valid. */
+export function gradientStops(value: GradientValue): string {
+  const stops = drawable(value, "gradientStops");
+  return stops.length ? stopList(value, stops) : "transparent, transparent";
+}
+
+function stopList(value: GradientValue, stops: GradientStop[]): string {
+  const plain = (s: GradientStop) => `${s.color} ${pct(s.pos)}%`;
+  if (stops.length < 2) return `${stops[0].color}, ${stops[0].color}`; // one stop isn't a stop list; doubled, it's a solid fill
+  const bez = parseEasing(value.easing);
+  if (!bez) return stops.map(plain).join(", ");
+  const samples = easingSamples(bez), space = blend(value);
+  const out = [plain(stops[0])];
+  for (let i = 1; i < stops.length; i++) {
+    const a = stops[i - 1], b = stops[i], span = b.pos - a.pos;
+    // Two stops at one position are a hard edge: no samples between.
+    if (span > 1e-6) for (let k = 1; k < SAMPLES; k++) {
+      const [x, y] = samples[k];
+      out.push(`color-mix(in ${space}, ${a.color}, ${b.color} ${pct(y)}%) ${pct(a.pos + span * x)}%`);
+    }
+    out.push(plain(b));
+  }
+  return out.join(", ");
+}
+
+/** The `linear-gradient(…)` for a gradient value; `direction` is degrees or any CSS direction.
+ *  One stop draws a solid fill and no stops is `none`, both still valid for background-image. */
+export function gradientCss(value: GradientValue, direction: number | string = "to right"): string {
+  const stops = drawable(value, "gradientCss");
+  return stops.length ? `linear-gradient(in ${blend(value)} ${typeof direction === "number" ? `${direction}deg` : direction}, ${stopList(value, stops)})` : "none";
+}

package/src/tweaks/enhance.ts

@@ -0,0 +1,20 @@
+/* Markup-driven enhancement, core's side: enhance(). The work lives in markup.ts, a lazy chunk of the code-split build that
+ * only a page with markup fetches; core lends it what it shares with the panel, as a kit. Importing core binds nothing:
+ * the page scan on load is opt-in, in auto.ts (tweakit/auto), so the package can declare core free of side effects. */
+import { getMarkup } from "./shared.js";
+import { metaFor } from "./schema.js";
+import { ensureForMetas, LAZY_IMPORT } from "./lazy.js";
+import { createFolder, createControl } from "./controls/basic.js";
+import { makeCopyBtn, makeResetBtn, addHintMarker } from "./feedback.js";
+import type { MarkupKit } from "./markup.js";
+
+declare const TW_SPLIT: boolean;
+const kit: MarkupKit = { metaFor, ensureForMetas, LAZY_IMPORT, createFolder, createControl, makeCopyBtn, makeResetBtn, addHintMarker };
+
+/** Bind every unbound [data-tw] host under `root` (the document by default). */
+export function enhance(root: Document | Element = document): Promise<void> {
+  const run = getMarkup<MarkupKit>();
+  if (run || !TW_SPLIT) return run ? run(root, kit) : Promise.resolve(); // the single-file build registered it on load: synchronous, as ever
+  // A chunk that fails to load skips the markup, as a failed control chunk skips its control, instead of rejecting.
+  return import("./markup.js").then(() => getMarkup<MarkupKit>()!(root, kit), (e) => console.error("[tweaks] markup chunk failed to load:", e));
+}