tweakit 0.5.2 → 0.7.0

package/src/tweaks/controls/tabs.ts

@@ -0,0 +1,68 @@
+// ── 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 = `twk-tabs-${++tabsSeq}`;
+  const root = el("div", "twk-tabs");
+  const bar = el("div", "twk-tabs-bar");
+  bar.setAttribute("role", "tablist");
+  const pill = el("div", "twk-tabs-pill");
+  bar.append(pill);
+  const pagesWrap = el("div", "twk-tabs-pages");
+  const bodies: HTMLDivElement[] = [];
+  const tabs = meta.pages.map((page, i) => {
+    const tab = txt("button", "twk-tabs-tab", page.title);
+    tab.setAttribute("role", "tab");
+    tab.id = `${uid}-tab-${i}`;
+    tab.setAttribute("aria-controls", `${uid}-page-${i}`);
+    const body = el("div", "twk-tabs-page twk-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-twk] 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,118 @@
+/* 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)}%`;
+  // one stop isn't a stop list; doubled, it's a solid fill
+  if (stops.length < 2) return `${stops[0].color}, ${stops[0].color}`;
+  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,35 @@
+/* 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";
+import type { EnhanceOptions } from "./types.js";
+
+declare const TW_SPLIT: boolean;
+const kit: MarkupKit = {
+  metaFor,
+  ensureForMetas,
+  LAZY_IMPORT,
+  createFolder,
+  createControl,
+  makeCopyBtn,
+  makeResetBtn,
+  addHintMarker,
+};
+
+/** Bind every unbound [data-twk] host under `root` (the document by default). */
+export function enhance(root: Document | Element = document, opts: EnhanceOptions = {}): Promise<void> {
+  const run = getMarkup<MarkupKit>();
+  // the single-file build registered it on load: synchronous, as ever
+  if (run || !TW_SPLIT) return run ? run(root, kit, opts.strings) : Promise.resolve();
+  // 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, opts.strings),
+    (e) => console.error("[tweaks] markup chunk failed to load:", e),
+  );
+}

package/src/tweaks/feedback.ts

@@ -0,0 +1,218 @@
+/* Panel feedback chrome — the toolbar button factories (copy / reset and their one-shot
+ * animations), the hint tooltip and the clipboard helper. The screen-reader announcer they
+ * speak through lives in shared.ts, where the lazy controls reach it too. */
+import { el, btn, carrySkin, placeBelow, announce, portalTo, words } from "./shared.js";
+import type { Tr } from "./shared.js";
+import { ICON_COPY, ICON_CHECK, ICON_RESET, ICON_INFO } from "./icons.js";
+
+/** A toolbar button with its one-shot animation state: timer, spin settle hook, last click time. */
+interface ToolbarBtn extends HTMLButtonElement {
+  _t?: number;
+  _spinSettle?: () => void;
+  _spinT?: number;
+}
+
+/** An icon toolbar button with matching title and aria-label. */
+const toolbarBtn = (cls: string, icon: string, label: string): ToolbarBtn => {
+  const b = btn("twk-toolbar-btn" + (cls ? " " + cls : ""), icon);
+  b.title = label;
+  b.setAttribute("aria-label", label);
+  return b;
+};
+/** Copy: puts `text(changedOnly)` on the clipboard and confirms with the check swap, and to a screen reader in words.
+ *  `text` returns the payload and a count (-1 for the full snapshot; 0 copies nothing).
+ *  Both handlers bail while `disabled`: a synthetic dispatchEvent(click) reaches a disabled button. */
+const makeCopyBtn = (text: (changedOnly: boolean) => [string, number], tr: Tr = words()) => {
+  const b = toolbarBtn(
+    "twk-toolbar-btn--swap",
+    `<span class="twk-toolbar-btn__icons">${ICON_COPY}${ICON_CHECK}</span>`,
+    tr("copy", "Copy values (⇧: changed only)"),
+  );
+  b.addEventListener("click", async (e) => {
+    if (b.disabled) return;
+    const [t, n] = text(e.shiftKey);
+    if (!n) return announce(tr("nothingChanged", "Nothing has changed"));
+    if (!(await copyText(t))) return announce(tr("copyFailed", "Copy failed"));
+    flashCopied(b);
+    announce(
+      n > 0
+        ? tr("copiedChanged", (v) => `${v.n} changed value${v.n === 1 ? "" : "s"} copied`, { n })
+        : tr("copied", "Values copied"),
+    );
+  });
+  return b;
+};
+/** Reset: runs `onReset` behind the icon's one-shot spin. */
+const makeResetBtn = (onReset: () => void, tr: Tr = words()) => {
+  const b = toolbarBtn("twk-toolbar-btn--reset", ICON_RESET, tr("reset", "Reset"));
+  b.addEventListener("click", () => {
+    if (b.disabled) return;
+    spinReset(b);
+    onReset();
+  });
+  return b;
+};
+const flashCopied = (btn: ToolbarBtn) => {
+  btn.classList.add("is-copied");
+  clearTimeout(btn._t);
+  btn._t = setTimeout(() => btn.classList.remove("is-copied"), 1400);
+};
+/** Reset spin — an accumulated rotation on --twk-spin driven by the transform transition, so a
+ *  second click mid-spin retargets smoothly instead of snapping back. Once settled the counter
+ *  renormalizes to 0 with the transition suppressed (−n·360° is the same angle). "Settled" is the
+ *  transform's own transitionend, not a timer: the hover wind-up shares the transform and restarts
+ *  the clock. An end <250ms after the click is a stale wind settle; the timeout is only a fallback
+ *  for when no transition runs at all (reduced motion, hidden panel). */
+const spinReset = (btn: ToolbarBtn) => {
+  const svg = btn.querySelector("svg");
+  if (!btn._spinSettle) {
+    btn._spinSettle = () => {
+      clearTimeout(btn._t);
+      btn.classList.remove("is-spinning");
+      svg.style.transition = "none";
+      svg.style.setProperty("--twk-spin", "0deg");
+      // getBoundingClientRect, not offsetWidth: on an SVG element offsetWidth is undefined, so the
+      // reflow idiom flushed nothing and the −n·360° → 0 change animated as a visible unwind.
+      void svg.getBoundingClientRect();
+      svg.style.transition = "";
+    };
+    svg.addEventListener("transitionend", (e) => {
+      if (
+        e.propertyName === "transform" &&
+        btn.classList.contains("is-spinning") &&
+        performance.now() - btn._spinT > 250
+      )
+        btn._spinSettle();
+    });
+  }
+  btn._spinT = performance.now();
+  svg.style.setProperty("--twk-spin", `${(parseFloat(svg.style.getPropertyValue("--twk-spin")) || 0) - 360}deg`);
+  btn.classList.add("is-spinning");
+  clearTimeout(btn._t);
+  const fallback = () => {
+    if (svg.getAnimations && svg.getAnimations().length) btn._t = setTimeout(fallback, 250);
+    else btn._spinSettle();
+  };
+  btn._t = setTimeout(fallback, 600);
+};
+
+// Hint tooltip — one shared bubble, portaled where its panel's portals go (<body>, or a shadow panel's portal root) so
+// it clears the panel's overflow clip.
+let hintTip: HTMLDivElement | null = null,
+  hintTimer = 0,
+  hintAnchor: Element | null = null;
+// bound only while open; WCAG 1.4.13 (dismissable)
+const onHintKey = (e: KeyboardEvent) => {
+  if (e.key === "Escape") {
+    e.stopPropagation();
+    hideHintNow();
+  }
+};
+/** Hide the tip now; with `owner` (panel.destroy()), only a tip anchored inside it — the node is shared. */
+const hideHintNow = (owner?: Element) => {
+  if (owner && hintAnchor && !owner.contains(hintAnchor)) return;
+  clearTimeout(hintTimer);
+  document.removeEventListener("keydown", onHintKey);
+  if (hintTip) hintTip.classList.remove("is-open");
+};
+function showHint(anchor: Element, text: string) {
+  if (!hintTip) {
+    hintTip = el("div", "twk-tip twk-portal");
+    hintTip.setAttribute("role", "tooltip");
+  }
+  // each show: the last hint may have been another root's, or a host replaced <body>'s content
+  portalTo(hintTip, anchor);
+  clearTimeout(hintTimer);
+  hintTip.textContent = text;
+  carrySkin(hintTip, anchor); // resolved at show time: setTheme may have run since build
+  const wasOpen = hintTip.classList.contains("is-open");
+  hintTip.style.visibility = "hidden";
+  hintTip.classList.add("is-open");
+  placeBelow(anchor, hintTip, { align: "center", prefer: "above", gap: 8 });
+  hintTip.style.visibility = "";
+  document.addEventListener("keydown", onHintKey);
+  hintAnchor = anchor;
+  // Unmount watchdog: a host removing the panel mid-hover would strand the open tip. One rAF per frame while open.
+  if (!wasOpen)
+    requestAnimationFrame(function watch() {
+      if (!hintTip.classList.contains("is-open")) return;
+      if (!hintAnchor.isConnected) return hideHintNow();
+      requestAnimationFrame(watch);
+    });
+}
+// a short grace, so crossing marker → tip doesn't flicker
+function hideHint() {
+  if (hintTip) {
+    clearTimeout(hintTimer);
+    hintTimer = setTimeout(hideHintNow, 80);
+  }
+}
+/** Every control's label element — the one list behind the hint marker's home and the per-control
+ *  reset target (panel.ts wireReset), so the two can't drift. */
+const LABEL_SEL =
+  ".twk-slider-label, .twk-row-label, .twk-select-label, .twk-trigger-label, .twk-radiogrid-label, .twk-field-label, .twk-folder-title, .twk-fps-label, .twk-plot-label, .twk-spring-label, .twk-bezier-label";
+/** A control's `hint` becomes a ⓘ marker beside its label that reveals the tooltip on hover/focus. */
+function addHintMarker(node: Element, hint: string) {
+  const label = node.querySelector(LABEL_SEL) || node;
+  if (label === node && node.classList.contains("twk-separator")) return; // a divider has no label to carry a marker
+  // Inside a <button> (select trigger, folder header), which can't contain interactive content, the
+  // ⓘ is a decorative span and the hint rides the host button's aria-description for screen readers.
+  const hostBtn = label.closest("button");
+  const mark = hostBtn ? el("span", "twk-hint", ICON_INFO) : btn("twk-hint", ICON_INFO);
+  const show = () => showHint(mark, hint);
+  if (hostBtn) {
+    mark.setAttribute("aria-hidden", "true");
+    const prior = hostBtn.getAttribute("aria-description");
+    hostBtn.setAttribute("aria-description", prior ? `${prior}. ${hint}` : hint);
+  } else {
+    mark.setAttribute("aria-label", hint);
+    mark.addEventListener("focus", show);
+    mark.addEventListener("blur", hideHint);
+    // keyboard activation stays on the marker
+    mark.addEventListener("keydown", (e) => {
+      if (e.key === "Enter" || e.key === " ") e.stopPropagation();
+    });
+  }
+  mark.addEventListener("pointerenter", show);
+  mark.addEventListener("pointerleave", hideHint);
+  mark.addEventListener("pointerdown", (e) => e.stopPropagation()); // mustn't start a slider scrub or panel drag
+  // and (inside a control button) mustn't toggle the parent
+  mark.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+  });
+  label.appendChild(mark);
+}
+async function copyText(text: string) {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {}
+  // Fallback when the clipboard API is blocked (no user activation): textarea + execCommand.
+  const ta = document.createElement("textarea");
+  ta.value = text;
+  ta.style.position = "fixed";
+  ta.style.top = "-9999px";
+  document.body.appendChild(ta);
+  ta.focus();
+  ta.select();
+  let ok = false;
+  try {
+    ok = document.execCommand("copy");
+  } catch {}
+  document.body.removeChild(ta);
+  return ok;
+}
+
+export {
+  toolbarBtn,
+  makeCopyBtn,
+  makeResetBtn,
+  flashCopied,
+  copyText,
+  spinReset,
+  announce,
+  hideHintNow,
+  addHintMarker,
+  LABEL_SEL,
+};

package/src/tweaks/fold.ts

@@ -0,0 +1,33 @@
+/* The fold a row behind a render condition hides and shows with. A panel with conditionals
+ * imports it once its first pass is done, so a basic panel never fetches it.
+ * The rows below close up over the row's height and gap as it's clipped from the bottom and
+ * fades; its own height is held so nothing inside squashes, and flipped mid-fold it turns
+ * around from where it's drawn. */
+import { REDUCE_MOTION } from "./shared.js";
+
+/** Fold `node` shut or open; reduced motion, no Animations API or a row with nothing drawn just toggle the class. */
+export const fold = (node: HTMLElement & { _fold?: Animation }, hide: boolean) => {
+  const cs = getComputedStyle(node),
+    at = node._fold?.playState == "running" && {
+      marginBottom: cs.marginBottom,
+      clipPath: cs.clipPath,
+      opacity: cs.opacity,
+    };
+  node._fold?.cancel();
+  node.classList.remove("twk-cond-hidden");
+  const h = !REDUCE_MOTION.matches && node.animate && node.offsetHeight;
+  node.classList.toggle("twk-cond-hidden", hide);
+  if (h)
+    try {
+      // d is the room the row takes: its height, the 6px stack gap (tweaks.css) and its own top margin.
+      const d = h + 6 + parseFloat(cs.marginTop),
+        H = h + "px",
+        shut = { height: H, marginBottom: -d + "px", clipPath: `inset(0 0 ${d}px)`, opacity: 0 },
+        open = { height: H, clipPath: "inset(0)" };
+      (node._fold = node.animate([at || (hide ? open : shut), hide ? shut : open], {
+        duration: 350,
+        easing: cs.getPropertyValue("--twk-ease-fold").trim(),
+      })).onfinish = () => node.classList.toggle("twk-cond-hidden", hide);
+      node.classList.remove("twk-cond-hidden"); // after animate(): a refused easing leaves the toggle done
+    } catch {}
+};