@panphora/clayjs 1.13.1 → 1.15.0

package/src/lib/derived.js

@@ -0,0 +1,116 @@
+import { ownsAttr, paintsOf, stripPaints, eachPainted } from "../vendor/sap-ownership.vendor.js";
+import { bootPhase } from "../core/boot-phase.js";
+
+// Values a derive engine (sapjs) paints from the page's records: attr:, class:,
+// css:, text and show output inside a [sap] root. They are saved like any other
+// content, but they are never an edit: comparisons, the dirty gate, undo and
+// merges leave them out, and the engine repaints them after every merge, before
+// anything records a baseline. Which parts of an element are painted is read
+// from its own attributes, so the same answer holds for the live page, a
+// snapshot clone and a parsed frame. No expression is evaluated here.
+
+export const isDerivedAttr = (el, name) => ownsAttr(el, name);
+
+export const ownsDerivedText = (el) => !!el && el.nodeType === 1 && !!paintsOf(el)?.text;
+
+/** Remove every painted value from a detached tree, in place. Never the live page. */
+export const stripDerived = (root) => stripPaints(root);
+
+/** Every painted value under root, in document order, as one string. */
+export function paintSignature(root) {
+  const parts = [];
+  eachPainted(root, (el, p) => {
+    parts.push(el.localName);
+    for (const n of p.attrs) if (n !== "sap-error") parts.push(n + "=" + (el.getAttribute(n) ?? "\u0000"));
+    for (const t of p.classes) parts.push("." + t + "=" + el.classList.contains(t));
+    for (const v of p.vars) parts.push(v + "=" + el.style.getPropertyValue(v));
+    if (p.text) parts.push("#" + el.textContent);
+  });
+  return parts.join("\u0001");
+}
+
+/** paintSignature of a document's bytes, such as the file on disk. */
+export function paintSignatureOfHtml(html) {
+  return paintSignature(new DOMParser().parseFromString(html, "text/html"));
+}
+
+function withoutTokens(value, owned, split, join, nameOf) {
+  return split(value || "").map((t) => t.trim()).filter((t) => t && !owned.includes(nameOf(t))).sort().join(join);
+}
+
+// A class or style change that only touched painted tokens.
+function onlyPaintedTokens(el, name, before, after) {
+  const p = paintsOf(el);
+  if (!p) return false;
+  if (name === "class") {
+    if (!p.classes.length) return false;
+    const rest = (v) => withoutTokens(v, p.classes, (s) => s.split(/\s+/), " ", (t) => t);
+    return rest(before) === rest(after);
+  }
+  if (!p.vars.length) return false;
+  const rest = (v) => withoutTokens(v, p.vars, (s) => s.split(";"), ";", (t) => t.split(":")[0].trim());
+  return rest(before) === rest(after);
+}
+
+/** True when a mutation-hub change only rewrote painted output. */
+export function isDerivedChange(change) {
+  if (change.__derived !== undefined) return change.__derived;
+  const el = change.element;
+  let derived = false;
+  if (el && el.nodeType === 1) {
+    if (change.type === "attribute") {
+      const name = change.attribute;
+      derived = isDerivedAttr(el, name) ||
+        ((name === "class" || name === "style") && onlyPaintedTokens(el, name, change.oldValue, change.newValue));
+    } else if (change.type === "characterData") {
+      derived = ownsDerivedText(el);
+    }
+  }
+  change.__derived = derived;
+  return derived;
+}
+
+const engines = new Set();
+let mountedOnce = false;
+
+/** True while a derive engine is registered, or the loader holds boot for one. */
+export function derivedActive() {
+  return engines.size > 0 || bootPhase.holdSettle;
+}
+
+const mountWaiters = [];
+
+/** Run every registered engine's repaint, synchronously. Live sync calls it right after a merge applies. */
+export function repaintDerived() {
+  for (const repaint of [...engines]) {
+    try {
+      repaint();
+    } catch (err) {
+      console.error("clayjs: a derived repaint failed:", err);
+    }
+  }
+}
+
+/** Calls fn once an engine has finished its first pass, or after timeoutMs without one. */
+export function afterDerivedMount(fn, timeoutMs) {
+  if (mountedOnce || typeof document === "undefined" || !document.querySelector("[sap]")) return fn();
+  let done = false;
+  const once = () => {
+    if (done) return;
+    done = true;
+    fn();
+  };
+  mountWaiters.push(once);
+  setTimeout(once, timeoutMs);
+}
+
+export const derived = {
+  register(repaint) {
+    engines.add(repaint);
+    return () => engines.delete(repaint);
+  },
+  mounted() {
+    mountedOnce = true;
+    for (const fn of mountWaiters.splice(0)) fn();
+  },
+};

package/src/lib/effect.js

@@ -0,0 +1,130 @@
+// clay.effect(fn): run fn soon and again after anything that can change what it
+// reads. Local edits arrive through the mutation hub; a live-sync merge runs with
+// the hub paused, so clay:sync-applied covers it; undo and redo write through the
+// hub as well, and their events are a backstop. fn runs with the hub paused, so
+// its own writes (derived counts, totals) never re-trigger it, never start an
+// autosave and never enter undo history. The first run is on a microtask too:
+// pausing the hub mid-way through an undo.commit would split the command. fn must
+// be synchronous: writes after an await land outside the pause and would loop.
+//
+// In edit mode each effect warns once about the misuses it can see: a write to
+// saved, dirty-tracked content (saved with the file, but never marks it unsaved),
+// an effect created inside an effect, undo.commit inside an effect (checked by the
+// undo plugin through effect.running), and an effect that keeps re-running.
+import { isTabLocalAttr } from "./root-attrs.js";
+
+const LOOP_RUNS = 50;
+const LOOP_WINDOW_MS = 1000;
+const NO_SNAPSHOT = '[clay~="no-snapshot"], [no-snapshot], [snapshot-remove]';
+
+let running = 0;
+
+const describe = (node) => {
+  const el = node.nodeType === 1 ? node : node.parentElement;
+  if (!el) return "a detached node";
+  let s = el.localName;
+  if (el.id) s += "#" + el.id;
+  else if (el.classList.length) s += "." + [...el.classList].slice(0, 2).join(".");
+  return "<" + s + ">";
+};
+
+function savedWrite(records) {
+  const policy = window.clay?.region?.resolveRegionPolicy;
+  if (!policy) return null;
+  const tracked = (el) => !!el && !el.closest(NO_SNAPSHOT) && policy(el).dirtyTracked;
+  for (const r of records) {
+    if (r.type === "attributes" && isTabLocalAttr(r.attributeName, r.target)) continue;
+    const el = r.target.nodeType === 1 ? r.target : r.target.parentElement;
+    if (!tracked(el)) continue;
+    // A child added or removed counts only when it is saved itself: chrome
+    // inserted into a saved parent (clay="editor-ui") is stripped on save.
+    if (r.type === "childList" && ![...r.addedNodes, ...r.removedNodes].some((n) => n.nodeType !== 1 || tracked(n))) continue;
+    return r.target;
+  }
+  return null;
+}
+
+export function effect(fn) {
+  const clay = window.clay;
+  const Mutation = clay.Mutation;
+  const warned = new Set();
+  const warn = (key, message) => {
+    if (warned.has(key)) return;
+    warned.add(key);
+    console.warn("clay.effect: " + message);
+  };
+  let queued = false;
+  let stopped = false;
+  let windowStart = 0;
+  let runs = 0;
+
+  if (running && clay.isEditMode) {
+    console.warn("clay.effect: an effect was created inside another effect, so a new one starts on every run. Create effects once, in clay.start.");
+  }
+
+  const watchLoop = () => {
+    const now = Date.now();
+    if (now - windowStart > LOOP_WINDOW_MS) { windowStart = now; runs = 0; }
+    if (++runs > LOOP_RUNS) {
+      warn("loop", `this effect ran more than ${LOOP_RUNS} times in a second. Something keeps changing the document, often a timer or async callback the effect started.`);
+    }
+  };
+
+  const run = () => {
+    queued = false;
+    if (stopped) return;
+    let observer = null;
+    Mutation.pause();
+    running++;
+    try {
+      if (clay.isEditMode === true) {
+        watchLoop();
+        if (!warned.has("saved")) {
+          observer = new MutationObserver(() => {});
+          observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
+        }
+      }
+      const result = fn();
+      if (result && typeof result.then === "function") {
+        stop();
+        console.error("clay.effect: fn returned a promise. It must be synchronous, so this effect was stopped.");
+      }
+    } catch (err) {
+      console.error("clay.effect:", err);
+    } finally {
+      running--;
+      Mutation.resume();
+      const records = observer ? observer.takeRecords() : [];
+      observer?.disconnect();
+      if (records.length) {
+        const target = savedWrite(records);
+        if (target) {
+          warn("saved", `this effect changed ${describe(target)}, which is saved with the file. Effect writes never mark the page unsaved, so a merge can leave it dirty with no save scheduled. Draw derived values inside clay="no-dirty" or clay="editor-ui".`);
+        }
+      }
+    }
+  };
+  const schedule = () => {
+    if (queued || stopped) return;
+    queued = true;
+    queueMicrotask(run);
+  };
+
+  const offMutation = Mutation.onAnyChange({ debounce: 0, require: "observed" }, schedule);
+  document.addEventListener("clay:sync-applied", schedule);
+  clay.undo?.on?.("undo", schedule);
+  clay.undo?.on?.("redo", schedule);
+
+  const stop = () => {
+    stopped = true;
+    offMutation();
+    document.removeEventListener("clay:sync-applied", schedule);
+    clay.undo?.off?.("undo", schedule);
+    clay.undo?.off?.("redo", schedule);
+  };
+
+  schedule();
+  return stop;
+}
+
+Object.defineProperty(effect, "running", { get: () => running > 0 });

package/src/lib/mutation.js

@@ -71,6 +71,7 @@ import { resolveRegionPolicy, isInert, strictestPolicy, skipForPolicy } from './
 import { isPolicyAttribute } from './region-capabilities.js';
 import { ROOT_LIBRARY_ATTRS, ROUTE_ROOT_PREFIX, ROUTE_ACTIVE_ATTR } from './root-attrs.js';
 import { isEphemeralAttr } from './ephemeral.js';
+import { isDerivedChange } from './derived.js';
 
 import { isUserDrivenNow, markUserDriven } from './user-gesture.js';
 
@@ -215,6 +216,7 @@ const localMutation = {
       // and their legacy equivalents), resolved against the callback's `require`.
       let filteredChanges = changes.filter(
         change => {
+          if (require !== 'observed' && isDerivedChange(change)) return false;
           const currentSkipped = skipForPolicy(this._policyForChange(change), require, skip);
           if (!change.policyTransition) return !currentSkipped;
           const previousSkipped = skipForPolicy(change.previousPolicy, require, skip);
@@ -647,7 +649,7 @@ const localMutation = {
       // Runs synchronously in the MO callback; skipped during paused-morph drains.
       if (!onlyNonPausable && isUserDrivenNow()) {
         for (const change of changes) {
-          if (!skipForPolicy(this._policyForChange(change), 'dirty')) {
+          if (!isDerivedChange(change) && !skipForPolicy(this._policyForChange(change), 'dirty')) {
             markUserDriven();
             break;
           }

package/src/lib/style-adoption.js

@@ -0,0 +1,9 @@
+let adopter = () => {};
+
+export function registerStyleAdoption(fn) {
+  adopter = fn;
+}
+
+export function adoptStyleComparisons(identity) {
+  adopter(identity);
+}

package/src/lib/style.js

@@ -0,0 +1,47 @@
+import { insertStyles, getStyleBaseUrl } from "../dom/insert-style-tag.js";
+import Mutation from "./mutation.js";
+import { adoptStyleComparisons } from "./style-adoption.js";
+
+// A style a script owns. The tag saves with the page, so the next load paints
+// styled before any script runs. Each call writes the current CSS into the saved
+// tag in place (or points the saved <link> at the current href), so a page saved
+// by an older script picks up newer styles. The tag is no-dirty: an update is
+// carried by the next real save and never counts as an edit, starts an autosave
+// or raises the close warning. A caller can add region tokens (editor-ui keeps a
+// style a plugin re-injects on every boot out of the saved file).
+const marker = (extra = []) => (el) => {
+  const tokens = (el.getAttribute("clay") ?? "").split(/\s+/).filter(Boolean);
+  const missing = ["no-dirty", ...extra].filter((token) => !tokens.includes(token));
+  if (missing.length) el.setAttribute("clay", [...tokens, ...missing].join(" "));
+};
+const markNoDirty = marker();
+
+export function style(nameOrHref, css) {
+  return writeStyle(nameOrHref, css);
+}
+
+export function styleWithLegacyId(name, css, legacyId, tokens = []) {
+  return writeStyle(name, css, legacyId, tokens);
+}
+
+function writeStyle(nameOrHref, css, legacyId, tokens = []) {
+  const inline = typeof css === "string";
+  const identity = inline ? { name: nameOrHref, legacyId } : { href: getStyleBaseUrl(nameOrHref) };
+  const legacy = legacyId === undefined ? [] : document.querySelectorAll(`style[id="${legacyId}"]:not([data-name])`);
+  Mutation.pause();
+  try {
+    adoptStyleComparisons(identity);
+    for (const el of legacy) el.dataset.name = nameOrHref;
+    if (inline) {
+      const el = insertStyles(nameOrHref, css, marker(tokens));
+      if (legacyId !== undefined) el.id = legacyId;
+      return el;
+    }
+    return insertStyles(nameOrHref, (link) => {
+      markNoDirty(link);
+      if (link.getAttribute("href") !== nameOrHref) link.setAttribute("href", nameOrHref);
+    });
+  } finally {
+    Mutation.resume();
+  }
+}