tweakit 0.5.2 → 0.7.0

package/src/tweaks/image-store.ts

@@ -0,0 +1,189 @@
+// ── Persisted images. An upload's data URL can outgrow localStorage (~5 MB an origin), so a panel with `persist`
+// keeps each one in IndexedDB and saves a short ref in its place: `tw-image:<hash>`. Records are keyed
+// [storage key, hash], so one panel's images read as a range. Loaded only by a panel that persists
+// an image control. Every call settles, never rejects: IndexedDB off or refused reads as null. ──
+
+const REF = "tw-image:";
+type Store = IDBObjectStore;
+let db: Promise<IDBDatabase | null> | null = null;
+// An open that never settles (another tab's pending delete or upgrade) reads as unavailable after 3s rather than
+// holding panel.ready forever. The connection closes for another tab's upgrade or delete, and one the browser drops is
+// reopened.
+const open = () =>
+  (db ||= new Promise<IDBDatabase | null>((done) => {
+    let late = false;
+    const t = setTimeout(() => {
+      late = true;
+      db = null;
+      done(null);
+    }, 3000);
+    // no indexedDB at all
+    try {
+      const r = indexedDB.open("tweakit", 1);
+      r.onupgradeneeded = () => r.result.createObjectStore("images");
+      r.onsuccess = () => {
+        const d = r.result;
+        clearTimeout(t);
+        if (late) {
+          d.close();
+          return;
+        }
+        d.onversionchange = () => {
+          d.close();
+          db = null;
+        };
+        d.onclose = () => {
+          db = null;
+        };
+        done(d);
+      };
+      r.onerror = () => {
+        clearTimeout(t);
+        db = null;
+        done(null);
+      };
+    } catch {
+      clearTimeout(t);
+      done(null);
+    }
+  }));
+// One transaction; resolves with what `fn` returns once it commits, null if it fails.
+const run = <T>(mode: IDBTransactionMode, fn: (s: Store) => T) =>
+  open().then(
+    (d) =>
+      d &&
+      new Promise<T | null>((done) => {
+        try {
+          const t = d.transaction("images", mode),
+            out = fn(t.objectStore("images"));
+          t.oncomplete = () => done(out);
+          t.onerror = t.onabort = () => done(null);
+        } catch {
+          done(null);
+        }
+      }),
+  );
+// an array sorts after every string, so [key, []] caps the range
+const range = (key: string) => IDBKeyRange.bound([key], [key, []]);
+
+// cyrb53: a 53-bit string hash, plenty to tell one panel's few images apart.
+const hash = (s: string) => {
+  let h1 = 0xdeadbeef,
+    h2 = 0x41c6ce57;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 2654435761);
+    h2 = Math.imul(h2 ^ c, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36) + s.length.toString(36);
+};
+
+const refFor = (dataUrl: string) => REF + hash(dataUrl);
+
+/** Every image stored under `key`, ref → data URL; null when IndexedDB can't be used. */
+const load = (key: string) =>
+  run("readonly", (s) => {
+    const out = new Map<string, string>();
+    s.openCursor(range(key)).onsuccess = function () {
+      const c = this.result;
+      if (!c) return;
+      if (typeof c.value === "string") out.set(REF + (c.key as string[])[1], c.value);
+      c.continue();
+    };
+    return out;
+  });
+/** One image by its ref (a preset another tab saved after this panel loaded); null when it isn't there. */
+const get = (key: string, ref: string) =>
+  run("readonly", (s) => {
+    const r = s.get([key, ref.slice(REF.length)]);
+    return r;
+  }).then((r) => (r && typeof r.result === "string" ? r.result : null));
+const put = (key: string, ref: string, dataUrl: string) =>
+  run("readwrite", (s) => {
+    s.put(dataUrl, [key, ref.slice(REF.length)]);
+    return true;
+  });
+/** Delete the images under `key` that `refs` name. */
+const prune = (key: string, refs: string[]) =>
+  run("readwrite", (s) => {
+    for (const r of refs) s.delete([key, r.slice(REF.length)]);
+    return true;
+  });
+
+/** Each ref a stored snapshot or preset names, read from its JSON whatever the schema: a renamed field's preset still
+ * counts. */
+const refsIn = (v: unknown) => new Set<string>(JSON.stringify(v ?? null).match(/tw-image:[0-9a-z]+/g) || []);
+/** Delete the records under `key` this panel knows (`known`) that nothing in `named` names any more. */
+const pruneUnnamed = (key: string, known: Map<string, string>, named: unknown[]) => {
+  const keep = refsIn(named),
+    gone = [...known.keys()].filter((r) => !keep.has(r));
+  for (const r of gone) known.delete(r);
+  if (gone.length) prune(key, gone);
+};
+/** `presets` with `ref` swapped for `with` everywhere it appears, or null when nothing names it. */
+const swapRef = (presets: unknown, ref: string, withText: string) => {
+  const text = JSON.stringify(presets);
+  return text.includes(ref) ? JSON.parse(text.split(ref).join(JSON.stringify(withText).slice(1, -1))) : null;
+};
+
+/** The store bound to one panel: `known` holds the records it has loaded or written (ref → data URL), `refused` runs
+ * when
+ *  a write fails with its ref (the panel saves again, that image inline), and the presets pair reads and writes its
+ *  presets. */
+const bind = (
+  key: string,
+  known: Map<string, string>,
+  refused: (ref: string) => void,
+  readPresets: () => unknown,
+  writePresets: (v: unknown) => boolean,
+) => {
+  const failed = new Set<string>(),
+    hashed = new WeakMap<object, [string, string]>();
+  // Each row's last data URL and its ref, so a save that didn't touch the image doesn't hash megabytes again.
+  const refOf = (row: object, v: string) => {
+    const c = hashed.get(row);
+    if (c?.[0] === v) return c[1];
+    const r = refFor(v);
+    hashed.set(row, [v, r]);
+    return r;
+  };
+  // A record the store refused: a preset that names it takes the data URL inline, or an empty image if storage can't
+  // fit it.
+  const inlinePresets = (ref: string, v: string) => {
+    const inlined = swapRef(readPresets(), ref, v);
+    if (!inlined || writePresets(inlined)) return;
+    writePresets(swapRef(readPresets(), ref, ""));
+    console.warn("[tweaks] persist: an image a preset holds didn't fit in storage — the preset keeps the rest");
+  };
+  return {
+    /** The ref `row`'s image saves as, or null to save it inline (the store refused it). Written once, and again
+     * whenever
+     *  `stored` (what storage holds now) no longer names it: a tab that replaced it may have pruned the record. */
+    save(row: object, v: string, stored: unknown) {
+      const ref = refOf(row, v);
+      if (failed.has(ref)) return null;
+      if (!known.has(ref) || !refsIn(stored).has(ref)) {
+        known.set(ref, v);
+        put(key, ref, v).then((ok) => {
+          if (ok) return;
+          known.delete(ref);
+          failed.add(ref);
+          refused(ref);
+          inlinePresets(ref, v);
+        });
+      }
+      return ref;
+    },
+    prune: (named: unknown[]) => pruneUnnamed(key, known, named),
+    /** A ref this panel hasn't seen (a preset another tab saved), read from the store. */
+    fetch: (ref: string) =>
+      get(key, ref).then((url) => {
+        if (url) known.set(ref, url);
+        return url;
+      }),
+  };
+};
+
+export { refFor, load, bind };

package/src/tweaks/lazy.ts

@@ -0,0 +1,63 @@
+/* Lazy-control loading — the dynamic-import map behind the code-split build, plus the schema
+ * scan that preloads what a panel needs before it assembles. */
+import { getControl } from "./shared.js";
+import type { Meta } from "./schema.js";
+
+/** What the preload scan reads off a meta. */
+type MetaNode = Pick<Meta, "type" | "children" | "pages">;
+
+// ── Lazy controls — each import registers its constructor(s) into the shared registry ──
+// TW_SPLIT is an esbuild `define`: `false` for the single-file bundle, where single.ts imports
+// every control statically, so this map is empty and esbuild drops the import()s.
+declare const TW_SPLIT: boolean;
+// null-prototype: "constructor" isn't a chunk
+const LAZY_IMPORT: Record<string, () => Promise<unknown>> = Object.assign(
+  Object.create(null),
+  TW_SPLIT
+    ? {
+        number: () => import("./heavy.js"), // heavy.js registers the Number control itself
+        interval: () => import("./controls/interval.js"),
+        color: () => import("./controls/color.js"),
+        gradient: () => import("./controls/gradient.js"),
+        shadow: () => import("./controls/shadow.js"),
+        sides: () => import("./controls/sides.js"),
+        tabs: () => import("./controls/tabs.js"),
+        image: () => import("./controls/image.js"),
+        fpsgraph: () => import("./controls/monitor.js"),
+        monitor: () => import("./controls/monitor.js"),
+        spring: () => import("./controls/spring.js"),
+        cubicbezier: () => import("./controls/bezier.js"),
+        // motion registers last, so a failed editor chunk leaves it unregistered for the next panel to retry.
+        motion: () =>
+          Promise.all([import("./controls/bezier.js"), import("./controls/spring.js")]).then(
+            () => import("./controls/motion.js"),
+          ),
+        point: () => import("./controls/point.js"),
+        plot: () => import("./controls/plot.js"),
+      }
+    : {},
+);
+const loading: Record<string, Promise<unknown>> = {};
+// a rejection isn't cached, so a later panel retries
+const ensure = (type: string) =>
+  getControl(type) || !LAZY_IMPORT[type]
+    ? null
+    : (loading[type] ||= LAZY_IMPORT[type]().catch((e) => {
+        delete loading[type];
+        console.error(`[tweaks] control chunk "${type}" failed to load:`, e);
+        throw e;
+      }));
+const scanTypes = (metas: MetaNode[], set = new Set<string>()) => {
+  for (const m of metas) {
+    set.add(m.type);
+    if (m.children) scanTypes(m.children, set);
+    if (m.pages) for (const pg of m.pages) scanTypes(pg.children, set);
+  }
+  return set;
+};
+const ensureForMetas = (metas: MetaNode[]) => {
+  const pend = [...scanTypes(metas)].map(ensure).filter(Boolean);
+  return pend.length ? Promise.all(pend) : null;
+};
+
+export { ensureForMetas, scanTypes, LAZY_IMPORT }; // LAZY_IMPORT is exported for the registry sync test only

package/src/tweaks/markup.ts

@@ -0,0 +1,317 @@
+/* Markup-driven enhancement — the work behind enhance(): it turns [data-twk] hosts into live controls, sharing the
+ * panel's meta derivation through the kit. A lazy chunk in the code-split build, fetched by the first enhance() on a
+ * page with markup (single.ts imports it statically). It imports shared.ts alone: a panel module imported here as well
+ * as by core would become a shared chunk every basic panel fetches, so core lends what it needs (enhance.ts builds the
+ * kit). */
+import {
+  el,
+  btn,
+  foldBody,
+  getControl,
+  titleCase,
+  setMarkup,
+  controlTypes,
+  hasOwn,
+  valueChanged,
+  restoreDefault,
+  SPRING_KEYS,
+  using,
+  words,
+} from "./shared.js";
+import type { Words } from "./shared.js";
+import type { metaFor } from "./schema.js";
+import type { ensureForMetas, LAZY_IMPORT } from "./lazy.js";
+import type { createFolder, createControl } from "./controls/basic.js";
+import type { makeCopyBtn, makeResetBtn, addHintMarker } from "./feedback.js";
+import type { Control, SchemaObject } from "./types.js";
+
+/** What core lends the markup chunk. */
+export interface MarkupKit {
+  metaFor: typeof metaFor;
+  ensureForMetas: typeof ensureForMetas;
+  LAZY_IMPORT: typeof LAZY_IMPORT;
+  createFolder: typeof createFolder;
+  createControl: typeof createControl;
+  makeCopyBtn: typeof makeCopyBtn;
+  makeResetBtn: typeof makeResetBtn;
+  addHintMarker: typeof addHintMarker;
+}
+
+// ── The markup forms — each [data-twk] type parses its dataset into the same verbose
+// schema value TYPED_META consumes, then rides metaFor: ONE derivation, so markup defaults can't drift. ──
+// the motion control reads the same markup
+const springData = (d: DOMStringMap) => ({
+  ...Object.fromEntries(SPRING_KEYS.map((k) => [k, num(d[k])])),
+  mode: d.mode,
+});
+// the radio grid, by either name
+const choices = (d: DOMStringMap) => ({ options: splitList(d.options), value: d.value, cols: num(d.cols) });
+const DATA_VALUE: Partial<Record<SchemaObject["type"], (d: DOMStringMap, host: HTMLElement, label: string) => object>> =
+  {
+    // absent bounds derive from the value, like the schema
+    slider: (d) => ({
+      value: num(d.value),
+      min: num(d.min),
+      max: num(d.max),
+      step: num(d.step),
+      soft: flag(d.soft),
+      unit: d.unit,
+    }),
+    checkbox: (d) => (d.options ? { type: "radiogrid", ...choices(d) } : { value: d.checked === "true" }),
+    radiogrid: choices,
+    segmented: choices,
+    list: (d) => ({ options: splitList(d.options), value: d.value }),
+    // data-options is a comma list, so it takes URLs, not data URLs (they carry a comma).
+    image: (d) => ({
+      value: d.value,
+      options: d.options ? splitList(d.options) : undefined,
+      cols: num(d.cols),
+      maxSize: num(d.maxSize),
+      fit: d.fit === "false" ? false : num(d.fit),
+      quality: num(d.quality),
+      upload: d.upload === "false" ? false : undefined,
+      clear: d.clear === "false" ? false : undefined,
+    }),
+    buttongroup: (d) => ({ buttons: splitList(d.buttons).map((lab) => ({ label: lab })) }),
+    separator: () => ({}),
+    number: (d) => ({ value: num(d.value), min: num(d.min), max: num(d.max), step: num(d.step), unit: d.unit }),
+    text: (d) => ({ value: d.value ?? "", placeholder: d.placeholder, rows: num(d.rows) }),
+    fpsgraph: (d) => ({ label: d.label ?? "FPS" }),
+    interval: (d) => ({
+      value: d.value ? d.value.split(",").map(Number) : undefined,
+      min: num(d.min),
+      max: num(d.max),
+      step: num(d.step),
+    }),
+    // "8px 16px", or data-top / -right / -bottom / -left
+    sides: (d) => ({
+      value: d.value ?? d,
+      corners: flag(d.corners),
+      unit: d.unit,
+      step: num(d.step),
+      min: num(d.min),
+      max: num(d.max),
+    }),
+    // a box-shadow string, or data-x / -y / -blur / -color
+    shadow: (d) => ({ value: d.value ?? { ...d, inset: flag(d.inset) } }),
+    spring: springData,
+    // plus data-curve and data-duration
+    motion: (d) => ({
+      ...springData(d),
+      curve: d.curve && d.curve.includes(",") ? d.curve.split(",").map(Number) : d.curve,
+      duration: num(d.duration),
+    }),
+    cubicbezier: (d) => ({ value: d.value ? d.value.split(",").map(Number) : undefined }),
+    point: (d) => {
+      const vals = (d.value || "").split(",").map((s) => parseFloat(s));
+      return {
+        // no step: the control derives a continuous one
+        components: splitList(d.components || "X,Y").map((lab, i) => ({
+          key: lab.toLowerCase(),
+          label: lab,
+          value: isNaN(vals[i]) ? 0 : vals[i],
+          step: num(d.step),
+          min: num(d.min),
+          max: num(d.max),
+        })),
+        pad: flag(d.pad),
+        invertY: d.invertY === "true",
+      };
+    },
+    plot: (d) => ({
+      expr: d.expr,
+      xMin: num(d.xmin),
+      xMax: num(d.xmax),
+      yMin: num(d.ymin),
+      yMax: num(d.ymax),
+      samples: num(d.samples),
+      editable: d.editable !== "false",
+    }),
+  };
+// non-numeric → undefined, so the default applies
+const num = (s: string | undefined) => {
+  if (s == null || s === "") return undefined;
+  const n = +s;
+  return Number.isFinite(n) ? n : undefined;
+};
+const flag = (s: string | undefined) => s === "true" || s === ""; // boolean attributes: data-x / data-x="true"
+const splitList = (s: string | undefined) =>
+  (s || "")
+    .split(",")
+    .map((t) => t.trim())
+    .filter(Boolean);
+const dataMeta = (kit: MarkupKit, host: HTMLElement) => {
+  const d = host.dataset,
+    type = d.twk;
+  // Tabs are panel-only, so a tabs host is left untouched, as the markup page says; built, it fell through to a folder
+  // whose missing get() threw out of enhance() and left every later host claimed but empty.
+  if (type === "tabs") return null;
+  const label = d.label ?? titleCase(d.key || type); // data-label="" means no label, like `label: ""`
+  // A lazy type with no parser takes the dataset as its fields.
+  const v = hasOwn(DATA_VALUE, type)
+    ? DATA_VALUE[type]!(d, host, label)
+    : kit.LAZY_IMPORT[type] || getControl(type)
+      ? { ...d }
+      : null;
+  // A typo (`data-twk="slidr"`) rendered nothing and said nothing. The list names what markup builds, so not tabs.
+  if (!v) {
+    import("./heavy.js").then(
+      (m) =>
+        m.unknownType(
+          `data-twk="${type}"`,
+          String(type),
+          [...Object.keys(DATA_VALUE), ...Object.keys(kit.LAZY_IMPORT), ...controlTypes()].filter((t) => t !== "tabs"),
+          "markup",
+        ),
+      () => {},
+    );
+    return null;
+  }
+  // The label rides the verbose value; v spreads after, so a parser's own type or label wins. A form that comes back a
+  // folder (a lazy type's verbose form missing the field it hinges on) is no control either.
+  const m = kit.metaFor("v", { type, label, ...v });
+  return m && m.type !== "folder" ? m : null;
+};
+
+/** The handle enhance() hangs on a bound [data-twk] host: its control, the reset pair and its key. */
+interface HostHandle {
+  ctrl: Control;
+  raw: unknown;
+  def: unknown;
+  key: string;
+  host: HTMLElement;
+  reset: () => void;
+}
+interface HostEl extends HTMLElement {
+  _tw?: HostHandle;
+}
+
+// Echo a control's value onto its host's data-value, in the comma form schema.ts parses. A plain
+// object (a point, a spring) would stringify as "[object Object]", so take its values in order.
+const writeDataValue = (host: HTMLElement, v: unknown) => {
+  host.dataset.value =
+    v == null ? "" : Array.isArray(v) ? v.join(",") : typeof v === "object" ? Object.values(v).join(",") : String(v);
+};
+// One change path for a markup host: echo onto data-value, then a bubbling twk:change with { key, value }.
+const announce = (host: HTMLElement, key: string, v: unknown) => {
+  writeDataValue(host, v);
+  host.dispatchEvent(new CustomEvent("twk:change", { bubbles: true, detail: { key, value: v } }));
+};
+// querySelectorAll sees descendants only — a root that is itself a host counts too (a Document has no matches()).
+const select = <T extends Element = HTMLElement>(root: Document | Element, sel: string): T[] => [
+  ...(typeof (root as Element).matches === "function" && (root as Element).matches(sel) ? [root as T] : []),
+  ...root.querySelectorAll<T>(sel),
+];
+/** Bind every unbound [data-twk] host under `root`, in `strings` (enhance()'s option) over the English defaults. */
+async function enhance(root: Document | Element, kit: MarkupKit, strings?: Words): Promise<void> {
+  const { createFolder, createControl, makeCopyBtn, makeResetBtn, addHintMarker, ensureForMetas } = kit,
+    tr = words(strings);
+  // Static showcase panels collapse like the real one: wrap the controls in a .twk-body, make the title the toggle.
+  select(root, '.twk-panel[data-mode="inline"]:not([data-twk-panel-bound])').forEach((panel) => {
+    const header = panel.querySelector(":scope > .twk-header");
+    const controls = panel.querySelector(":scope > .twk-controls");
+    if (!header || !controls) return;
+    panel.setAttribute("data-twk-panel-bound", "");
+    const body = el("div", "twk-body");
+    panel.insertBefore(body, controls);
+    body.append(controls);
+    let toggle = header.querySelector<HTMLButtonElement>(".twk-header-toggle");
+    const title = header.querySelector(".twk-title");
+    if (!toggle && title) {
+      toggle = btn("twk-header-toggle");
+      title.replaceWith(toggle);
+      toggle.append(title);
+    }
+    if (!toggle) return;
+    toggle.setAttribute("aria-expanded", "true");
+    toggle.addEventListener("click", () => foldBody(panel, toggle, body, !panel.classList.contains("is-collapsed")));
+    // The same toolbar tweaks() builds, over this panel's own [data-twk] controls (gathered at click time).
+    if (!header.querySelector(".twk-toolbar")) {
+      const live = () =>
+        [...panel.querySelectorAll<HostEl>("[data-twk]")]
+          .map((h) => h._tw)
+          .filter((t) => t && t.ctrl.get() !== undefined);
+      // Two hosts can share a key (a repeated data-key, or the same label): suffix the duplicates.
+      const values = () => {
+        // null-proto: a "__proto__" data-key is an ordinary key
+        const vals: Record<string, unknown> = Object.create(null);
+        for (const t of live()) {
+          let k = t.key,
+            n = 2;
+          while (hasOwn(vals, k)) k = `${t.key}-${n++}`;
+          vals[k] = t.ctrl.get();
+        }
+        return JSON.stringify(vals, null, 2);
+      };
+      const reset = () => {
+        for (const t of live()) t.reset();
+      };
+      const toolbar = el("div", "twk-toolbar");
+      // no defaults to diff against: the copy is every value
+      toolbar.append(
+        makeCopyBtn(() => [values(), -1], tr),
+        makeResetBtn(reset, tr),
+      );
+      header.append(toolbar);
+    }
+  });
+  // Folders first: move child hosts into the collapsible chrome.
+  select(root, '[data-twk="folder"]:not([data-twk-bound])').forEach((host) => {
+    host.setAttribute("data-twk-bound", "");
+    const f = createFolder({ label: host.dataset.label || tr("folder", "Folder") });
+    [...host.children].forEach((c) => f.body.append(c));
+    host.append(f.el);
+  });
+  // Claim each host synchronously, so a re-entrant enhance can't double-bind; then load and build.
+  const hosts = select<HostEl>(root, "[data-twk]:not([data-twk-bound])")
+    .map((h) => ({ host: h, meta: dataMeta(kit, h) }))
+    .filter((x) => x.meta);
+  hosts.forEach(({ host }) => host.setAttribute("data-twk-bound", ""));
+  const pend = ensureForMetas(hosts.map((x) => x.meta));
+  if (pend) await pend.catch(() => {}); // a failed chunk skips its controls instead of rejecting
+  // One host that fails to build costs only itself: the rest still bind.
+  for (const { host, meta } of hosts)
+    try {
+      const key = host.dataset.key || meta.label;
+      // Gated the way the panel gates notify(): a same-value emit announces nothing.
+      let last: unknown;
+      const emit = (v: unknown) => {
+        if (!valueChanged(last, v)) return;
+        last = v;
+        announce(host, key, v);
+      };
+      const ctrl = using(strings, () => createControl(meta, emit));
+      if (!ctrl) continue;
+      if (!host.closest(".twk-panel, .twk-portal")) host.classList.add("twk-portal"); // a bare host gets the token scope
+      host.append(ctrl.el);
+      if (host.dataset.hint) addHintMarker(ctrl.el, host.dataset.hint);
+      // raw = the markup's value, def = the form the control opened on: the panel's reset pair.
+      const def = ctrl.get();
+      last = def;
+      // The handle's set() runs the change path too, where the bare control's set() is silent.
+      const handle = {
+        ...ctrl,
+        set: (v: unknown) => {
+          ctrl.set(v);
+          emit(ctrl.get());
+        },
+      };
+      host._tw = {
+        ctrl: handle,
+        raw: meta.value,
+        def,
+        key,
+        host,
+        reset: () => {
+          restoreDefault(ctrl, meta.value, def);
+          emit(ctrl.get());
+        },
+      };
+    } catch (err) {
+      console.error(`[tweaks] data-twk="${host.dataset.twk}" could not be built — skipped:`, err);
+    }
+}
+
+setMarkup(enhance);
+
+export { DATA_VALUE }; // for the registry sync test