@panphora/clayjs 1.15.2 → 1.17.0

package/src/plugins/bind-text.js

@@ -0,0 +1,218 @@
+/**
+ * clay.bindText — an editor textarea that lives outside the saved records.
+ *
+ * The textarea sits in a `clay="freeze"` region and edits one record's text
+ * element (for example `<pre><code class="entry-body">`). Every input is
+ * written into the record at once, so a save captures it as the record's text
+ * and a peer's merge of another paragraph keeps both edits. A change to the
+ * record from elsewhere (a peer's merge, a restored draft, a JSON API write) is
+ * shown in the textarea with the caret kept. During an IME composition nothing
+ * is written or shown, and when it ends both edits apply unless they touch the
+ * same stretch of text. Nothing here is Journal-specific: OverType, the
+ * timestamps and the note arrive as callbacks.
+ *
+ * The binding answers for its own lifecycle too: `flush()` reports whether the
+ * record now holds the text and refuses while a composition is running, `open()`
+ * and `close()` honor that refusal, and `dispose()` only detaches once the exit
+ * barrier has landed.
+ */
+
+// Applies two edits to one text when each is one stretch of it (an IME composition always is) and the
+// stretches do not overlap (two inserts at one point keep both); null when they do.
+export function spliceMerge(base, local, remote) {
+  const span = (text) => {
+    let pre = 0;
+    const max = Math.min(base.length, text.length);
+    while (pre < max && base[pre] === text[pre]) pre++;
+    let suf = 0;
+    while (suf < max - pre && base[base.length - 1 - suf] === text[text.length - 1 - suf]) suf++;
+    return { start: pre, end: base.length - suf, text: text.slice(pre, text.length - suf) };
+  };
+  const l = span(local);
+  const r = span(remote);
+  if (l.end <= r.start) return base.slice(0, l.start) + l.text + base.slice(l.end, r.start) + r.text + base.slice(r.end);
+  if (r.end <= l.start) return base.slice(0, r.start) + r.text + base.slice(r.end, l.start) + l.text + base.slice(l.end);
+  return null;
+}
+
+// Where an offset in `before` lands in `after`, when the two differ in one stretch.
+export function mapCaret(before, after, offset) {
+  let pre = 0;
+  const max = Math.min(before.length, after.length);
+  while (pre < max && before[pre] === after[pre]) pre++;
+  if (offset <= pre) return offset;
+  let suf = 0;
+  while (suf < max - pre && before[before.length - 1 - suf] === after[after.length - 1 - suf]) suf++;
+  return offset >= before.length - suf ? after.length - (before.length - offset) : after.length - suf;
+}
+
+export function bindText(textarea, { onWrite, onShow, onConflict, onGone } = {}) {
+  const OBSERVE = { characterData: true, childList: true, subtree: true };
+  let field = textarea;
+  const ta = () => field;
+  let s = null; // { key, code, seen, composing, resolve }
+  let disposed = false;
+  const observer = new MutationObserver(() => {
+    observer.takeRecords();
+    if (s && !s.composing && s.code.textContent !== s.seen) reconcile(s.code.textContent);
+  });
+
+  // New durable input is the lifecycle's to admit, not the binding's: while a transition
+  // runs, a keystroke is not new input and is refused. A standalone page has no lifecycle
+  // and always admits.
+  const admitted = () => window.clay?.modeLifecycle?.canWrite?.() !== false;
+
+  // The record holds what the textarea holds. That is the only proof a flush landed: a
+  // callback that staged a conflict or a gone record has not made the text represented.
+  const represented = () => !!(s && s.code.isConnected && s.code.textContent === ta().value);
+
+  function write(value) {
+    const t = s.code.firstChild;
+    if (t && t.nodeType === 3 && !t.nextSibling) t.data = value;
+    else s.code.textContent = value;
+    observer.takeRecords();
+    s.seen = value;
+    onWrite?.(s.code);
+  }
+  function show(value) {
+    const el = ta();
+    const before = el.value;
+    const [a, b] = [mapCaret(before, value, el.selectionStart), mapCaret(before, value, el.selectionEnd)];
+    el.value = value;
+    if (document.activeElement === el) el.setSelectionRange(a, b);
+    s.seen = value;
+    onShow?.();
+  }
+  // The record changed while the textarea held text the record had not taken yet.
+  // `base` is the text both sides were editing, read before show() moves `seen`: a
+  // caller staging the losing side needs what the clash was measured against, not
+  // what the textarea holds afterwards. The second argument is additive, so a
+  // caller that only wants the typed string ignores it.
+  function reconcile(now) {
+    const typed = ta().value;
+    const base = s.seen;
+    const merged = typed === base ? now : spliceMerge(base, typed, now);
+    if (merged == null) {
+      onConflict?.(typed, { key: s.key, base, remote: now });
+      show(now);
+      return { ok: false, code: "conflict" };
+    }
+    if (merged !== now) write(merged);
+    show(merged);
+    return { ok: true };
+  }
+  // A record that cannot be resolved hands its text to `onGone` and is released: there is
+  // nothing left here that a later write could land in, and holding the detached element
+  // would refuse every record switch after it.
+  function rebind() {
+    const code = s.resolve ? s.resolve() : null;
+    if (!code) {
+      onGone?.(ta().value, { key: s.key, base: s.seen });
+      observer.disconnect();
+      s = null;
+      return false;
+    }
+    s.code = code;
+    observer.disconnect();
+    observer.observe(s.code, OBSERVE);
+    return true;
+  }
+  // `captured` is the composition this binding already holds: it finishes through its own
+  // operation, so a closed admission does not throw away what the person was typing.
+  function input(captured = false) {
+    if (!s) return { ok: true };
+    if (s.composing) return { ok: false, code: "composition" };
+    if (!captured && !admitted()) return { ok: false, code: "busy" };
+    if (!s.code.isConnected && !rebind()) return { ok: false, code: "gone" };
+    const now = s.code.textContent;
+    if (now !== s.seen) return reconcile(now);
+    const value = ta().value;
+    if (value !== s.seen) write(value);
+    return { ok: true };
+  }
+  // A composition in progress is not something a flush may end on the person's behalf: it
+  // is refused, and `s.composing` stays exactly as it was. Everything else runs the input
+  // path above, and its answer says whether the record now holds the text.
+  function flush() {
+    if (!s) return { ok: true };
+    if (s.composing) return { ok: false, code: "composition" };
+    const result = input();
+    if (!result.ok) return result;
+    return represented() ? { ok: true } : { ok: false, code: "conflict" };
+  }
+  function open(textEl, options = {}) {
+    if (disposed) return { ok: false, code: "disposed" };
+    const key = options.key;
+    if (s && s.key === key) {
+      s.resolve = options.resolve;
+      if (s.code !== textEl || !s.code.isConnected) {
+        if (!rebind()) return { ok: false, code: "gone" };
+        return input();
+      }
+      return { ok: true };
+    }
+    // A refused flush keeps the open record and its observer: nothing was written, so
+    // switching records here would drop the text the refusal was protecting. A record that
+    // was gone has already handed its text over and released itself, so there is nothing
+    // left to protect and the switch goes ahead.
+    const flushed = flush();
+    if (!flushed.ok && s) return flushed;
+    observer.disconnect();
+    s = { key, code: textEl, seen: textEl.textContent, composing: false, resolve: options.resolve };
+    observer.observe(textEl, OBSERVE);
+    const el = ta();
+    el.value = s.seen;
+    el.setSelectionRange(0, 0);
+    onShow?.();
+    return { ok: true };
+  }
+  function close() {
+    const flushed = flush();
+    if (!flushed.ok && s) return flushed;
+    observer.disconnect();
+    s = null;
+    return { ok: true };
+  }
+  // Detaching only. The barrier has already succeeded when a lease disposes the binding, so
+  // this never flushes: a composition still in progress or text the record never took keeps
+  // the listeners where they are, and the caller is told why.
+  function dispose() {
+    if (disposed) return { ok: true };
+    if (s?.composing) return { ok: false, code: "composition" };
+    if (s && !represented()) return { ok: false, code: "pending-input" };
+    disposed = true;
+    observer.disconnect();
+    detach();
+    s = null;
+    return { ok: true };
+  }
+  function attach(next) {
+    if (disposed || !next || next === field) return;
+    detach();
+    field = next;
+    listen();
+  }
+
+  function onInput() { input(); }
+  function onCompositionStart() { if (s) s.composing = true; }
+  function onCompositionEnd() { if (s) { s.composing = false; input(true); } }
+  function listen() {
+    field.addEventListener("input", onInput);
+    field.addEventListener("compositionstart", onCompositionStart);
+    field.addEventListener("compositionend", onCompositionEnd);
+  }
+  function detach() {
+    field.removeEventListener("input", onInput);
+    field.removeEventListener("compositionstart", onCompositionStart);
+    field.removeEventListener("compositionend", onCompositionEnd);
+  }
+
+  listen();
+
+  return {
+    open, close, flush, dispose,
+    current: () => s && s.code,
+    attach,
+    composing: () => !!(s && s.composing),
+  };
+}

package/src/plugins/cms.js

@@ -4,9 +4,102 @@
 import { installSkin } from "../ui/vendor-skin.js";
 import { CSS } from "../ui/skins/cms.js";
 import { CSS as TOGGLE_CSS, ROOTS as TOGGLE_ROOTS } from "../ui/skins/cms-toggle.js";
+import { cms as hypercms } from "../vendor/hypercms.vendor.js";
 
 export { cms, default } from "../vendor/hypercms.vendor.js";
 
 installSkin("cms", CSS);
 // The toggle takes the page's scheme, so Bevel's face and ink resolve the way the page reads.
 installSkin("cms-toggle", TOGGLE_CSS, { roots: TOGGLE_ROOTS });
+
+const fault = (message, code) => Object.assign(new Error(`clay:cms: ${message}`), { code });
+
+const isStale = (context) => {
+  if (!context) return false;
+  if (context.signal?.aborted) return true;
+  return typeof context.isCurrent === "function" && !context.isCurrent();
+};
+
+// One edit session over the page the CMS edits, as a ClayJS lease. The source owns the
+// session itself, so every method here is the source's own lifecycle call: `enable`
+// opens and mounts, `resume` is the refused exit over the same session, and `dispose`
+// goes through the CMS's teardown after the barrier.
+//
+// `quiesce` is the one call the lease shapes. The source answers for the work it still
+// holds, an upload in flight or a painted preview, with `{ok:false}` rather than by
+// tearing that work down: an exit refused there keeps the session, its buffers and the
+// upload, and the controller resumes the same lease once the person finishes or
+// discards it. The lease contract carries a refusal as the `code` a controller reports,
+// so the non-ok answer is thrown as `pending-input`.
+function cmsLease(source) {
+  let disposed = false;
+  return {
+    ready: source.ready,
+    enable() {
+      if (disposed) return;
+      source.enable();
+    },
+    quiesce() {
+      if (disposed) return;
+      const result = source.quiesce();
+      if (result && result.ok === false) {
+        throw Object.assign(fault("the CMS still has work to finish", result.code || "pending-input"), {
+          pending: result.pending,
+        });
+      }
+      return result;
+    },
+    resume() {
+      if (disposed) return;
+      source.resume();
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      source.dispose();
+    },
+  };
+}
+
+// The boot this tab made, adopted instead of prepared. A page that opened the CMS itself
+// (`?cms=true`) holds a session the source hands no lease out for, so it cannot be
+// quiesced or torn down through the adapter and the caller keeps its reload instead;
+// a boot that opened nothing has nothing to hand back, and this lease starts nothing.
+function adopt() {
+  if (hypercms.isOpen) throw fault("the CMS this boot opened cannot be taken back", "unsupported-plugin");
+  const lease = cmsLease(hypercms.prepareModeLease({}));
+  return {
+    enable() {},
+    quiesce: () => lease.quiesce(),
+    resume: () => lease.resume(),
+    dispose: () => lease.dispose(),
+  };
+}
+
+/**
+ * The CMS as a mode participant: the session the commit that enters edit opens, and the
+ * one the exit destroys.
+ *
+ * `prepare` is inert by construction, because the source's lease mounts nothing until
+ * `enable`; a vendor build without that lifecycle is refused here rather than opened
+ * beside the controller, where an exit would have no session to quiesce and no teardown
+ * to run. `order` is the source's: the CMS edits the page's own attributes and content,
+ * so it enters after the modules that prepare that page for editing, and it leaves
+ * first, while its session can still refuse an exit over an upload or a preview.
+ */
+export function cmsParticipant(options = {}) {
+  return {
+    id: "clay:cms",
+    order: 1000,
+    async prepare(context = {}) {
+      if (typeof hypercms.prepareModeLease !== "function") {
+        throw fault("this vendor build has no quiescable session", "unsupported-plugin");
+      }
+      if (isStale(context)) throw fault("prepared for a stale generation", "stale-document");
+      if (context.initial === true) return adopt();
+      return cmsLease(hypercms.prepareModeLease(options));
+    },
+  };
+}
+
+export { cmsParticipant as modeParticipant };

package/src/plugins/indicator.js

@@ -1,4 +1,4 @@
-import { isEditMode } from "../core/is-edit-mode.js";
+import { startsAtImport } from "../core/is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
 import { set, style } from "../lib/hostile-css.js";
 import { bevelSurface, pageScheme } from "../ui/bevel-controls.js";
@@ -79,13 +79,65 @@ function show(state) {
   if (!STICKY.has(state)) hideTimer = setTimeout(() => { set(node, "opacity", "0"); }, 2200);
 }
 
-function init() {
-  if (!isEditMode) return;
+let listeners = null;
+
+// Arming is idempotent: the plugin's own boot and a mode lease both ask for the same
+// listeners, and one exit must be able to take all of them back.
+function arm() {
   saveFeedback.chip = true;
+  if (listeners) return;
+  listeners = new AbortController();
+  const { signal } = listeners;
   for (const state of Object.keys(LABELS)) {
-    document.addEventListener("clay:save-" + state, () => show(state));
+    document.addEventListener("clay:save-" + state, () => show(state), { signal });
   }
-  document.addEventListener("clay:page-save-state", (event) => show(event.detail?.state));
+  document.addEventListener("clay:page-save-state", (event) => show(event.detail?.state), { signal });
+}
+
+function disarm() {
+  listeners?.abort();
+  listeners = null;
+  clearTimeout(hideTimer);
+  hideTimer = null;
+  el?.remove();
+  el = null;
 }
 
+function init() {
+  if (!startsAtImport()) return;
+  arm();
+}
+
+/**
+ * The save chip as a mode lease.
+ *
+ * The chip owns no input: it reports a save somebody else is making, so an exit never
+ * waits on it. `quiesce` leaves the chip and its fade timer exactly as they were, which
+ * is what a refusal has to keep showing; `resume` has nothing to reopen. `initial: true`
+ * adopts the chip the boot already armed and arms nothing again. `dispose` (after the
+ * barrier) takes the chip, its listeners and its timer down, so a save event in view
+ * draws nothing.
+ */
+export function indicatorParticipant() {
+  return {
+    id: "clay:indicator",
+    order: 700,
+    prepare(context = {}) {
+      return {
+        enable() {
+          if (context.initial === true) return;
+          arm();
+        },
+        quiesce() {},
+        resume() {},
+        dispose() {
+          disarm();
+        },
+      };
+    },
+  };
+}
+
+export { indicatorParticipant as modeParticipant };
+
 onDomReady(init);