@panphora/clayjs 1.15.2 → 1.17.0

package/src/plugins/people.js

@@ -19,12 +19,9 @@
  */
 
 import { hostMeta, hostMetaOutcome } from "../core/host-meta.js";
-import { isEditMode } from "../core/is-edit-mode.js";
+import { isEditMode, modeState } from "../core/is-edit-mode.js";
 
 const editing = () => (window.clay && "isEditMode" in window.clay ? !!window.clay.isEditMode : isEditMode);
-import { bevelDialog, dismissOf, keepFocusIn } from "../ui/bevel-dialog.js";
-import { bevelBox, bevelButton, bevelInput, bevelText } from "../ui/bevel-controls.js";
-import { resolveTheme } from "../ui/theme.js";
 import { colorIndexOf, initialsOf } from "../lib/person-face.js";
 
 const ID = /^[A-Za-z0-9_-]{8,64}$/;
@@ -41,6 +38,7 @@ let asking = null;
 let askingRoot = null;
 let cancelAsking = null;
 let lastRegistry = "";
+let dialogLoad = null;
 
 function clean(person) {
   if (!person || typeof person !== "object") return null;
@@ -140,6 +138,7 @@ async function refresh(fresh) {
 }
 
 function get(id) {
+  observe();
   const key = String(id ?? "");
   const live = (host.me?.id === key && host.me) || host.members?.find((person) => person.id === key);
   if (live) return record(live);
@@ -149,6 +148,7 @@ function get(id) {
 }
 
 function list() {
+  observe();
   return [...saved().keys()].map(get);
 }
 
@@ -208,6 +208,16 @@ function rename(name) {
   return record(next);
 }
 
+// Same session and still editing: the two facts an await can invalidate.
+const stale = (generation) => generation !== modeState().generation || !editing();
+
+function refuseIfStale(generation) {
+  if (!stale(generation)) return;
+  throw Object.assign(new Error("clay.author: the page left edit mode before your name was recorded"), {
+    code: "stale-document",
+  });
+}
+
 function unavailable() {
   return Object.assign(new Error("Can't reach the host to check who you are. Try again in a moment."), { code: "people-unavailable" });
 }
@@ -220,11 +230,16 @@ function unavailable() {
 export async function author(el, attr = "data-by") {
   if (!window.clay?.isEditMode) throw new Error("clay.author: this page is not in edit mode");
   if (!(el instanceof Element)) throw new TypeError("clay.author: needs an element");
+  // Attribution belongs to the session that asked for it. Asking the host who I am and
+  // asking a person their name both take long enough for the page to leave edit, and a
+  // stamp recorded afterwards would credit a session that has already ended.
+  const generation = modeState().generation;
   // A host that names people can change who you are while the page is open (a sign-out,
   // a rename in the app), so a stamp asks it again first. If it cannot answer now, nothing
   // is stamped: the last answer might name someone who is no longer here.
   if (host.supports) {
     const meta = await hostMeta({ fresh: true });
+    refuseIfStale(generation);
     const fresh = hostMetaOutcome(meta);
     if (fresh === "none") throw Object.assign(new Error("This page lost its connection to the host. Reload it to keep editing."), { code: "people-unavailable" });
     if (fresh !== "ok") throw unavailable();
@@ -232,11 +247,13 @@ export async function author(el, attr = "data-by") {
     if (host.unavailable) throw Object.assign(new Error("The app hosting this file can't name you right now. Check its Profile settings, then try again."), { code: "people-unavailable" });
   } else if (outcome !== "ok" && outcome !== "none") {
     await refresh(outcome === "failed");
+    refuseIfStale(generation);
   }
   if (outcome === "failed") throw unavailable();
   let me = currentMe();
   if (!me) {
     const chosen = await askName();
+    refuseIfStale(generation);
     if (!chosen) return null;
     writeLocal(chosen);
     me = record(chosen);
@@ -247,12 +264,38 @@ export async function author(el, attr = "data-by") {
   return me;
 }
 
+// The dialog and the theme it paints with are this page's first-use download: a
+// reader is nobody and is asked nothing, so it never fetches them.
+function loadDialogUI() {
+  dialogLoad ??= Promise.all([
+    import("../ui/bevel-dialog.js"),
+    import("../ui/bevel-controls.js"),
+    import("../ui/theme.js"),
+  ]).then(([dialog, controls, theme]) => ({ ...dialog, ...controls, resolveTheme: theme.resolveTheme }))
+    .catch((error) => {
+      dialogLoad = null;
+      throw error;
+    });
+  return dialogLoad;
+}
+
 function askName() {
-  if (asking && askingRoot?.isConnected) return asking;
+  if (asking && (askingRoot ? askingRoot.isConnected : true)) return asking;
   if (asking) cancelAsking();
-  asking = new Promise((resolve) => {
-    const theme = resolveTheme();
-    const { root, overlay, panel, heading, body, footer, close } = bevelDialog({
+  asking = promptForName().catch((error) => {
+    asking = null;
+    askingRoot = null;
+    cancelAsking = null;
+    throw error;
+  });
+  return asking;
+}
+
+async function promptForName() {
+  const ui = await loadDialogUI();
+  return new Promise((resolve) => {
+    const theme = ui.resolveTheme();
+    const { root, overlay, panel, heading, body, footer, close } = ui.bevelDialog({
       zIndex: "2147483001", width: "420px", closable: true, titled: true, theme, surface: "people",
     });
     askingRoot = root;
@@ -260,27 +303,27 @@ function askName() {
     heading.textContent = "What name should appear on your changes?";
     panel.setAttribute("aria-label", "Your name");
 
-    const input = bevelInput("input", { rules: ["display:block", "width:100%", "margin:0"], theme, parts: ["dialog.input", "people.input"] });
+    const input = ui.bevelInput("input", { rules: ["display:block", "width:100%", "margin:0"], theme, parts: ["dialog.input", "people.input"] });
     input.setAttribute("aria-label", "Your name");
     input.maxLength = MAX_NAME;
     input.autocomplete = "name";
-    const hint = bevelText("p", ["display:block", "margin:10px 0 0", "font-size:13px", "opacity:.8"],
+    const hint = ui.bevelText("p", ["display:block", "margin:10px 0 0", "font-size:13px", "opacity:.8"],
       "Saved in this browser. Everyone who can read this page will see it.", { theme, parts: ["dialog.hint", "people.hint"], role: "mutedText" });
     const hintText = hint.textContent;
     body.append(input, hint);
 
     const known = list().slice(0, 8);
     if (known.length) {
-      const label = bevelText("p", ["display:block", "margin:18px 0 8px", "font-size:13px"], "Or continue as someone already in this page:", { theme, parts: ["people.choiceLabel"], role: "mutedText" });
-      const row = bevelBox("div", ["display:flex", "flex-wrap:wrap", "gap:8px"], { theme, parts: ["people.choices"] });
+      const label = ui.bevelText("p", ["display:block", "margin:18px 0 8px", "font-size:13px"], "Or continue as someone already in this page:", { theme, parts: ["people.choiceLabel"], role: "mutedText" });
+      const row = ui.bevelBox("div", ["display:flex", "flex-wrap:wrap", "gap:8px"], { theme, parts: ["people.choices"] });
       for (const person of known) {
-        row.append(bevelButton(person.name, { small: true, onClick: () => finish({ id: person.id, name: person.name }), theme, parts: ["dialog.button", "people.button", "people.choice"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] }));
+        row.append(ui.bevelButton(person.name, { small: true, onClick: () => finish({ id: person.id, name: person.name }), theme, parts: ["dialog.button", "people.button", "people.choice"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] }));
       }
       body.append(label, row);
     }
 
-    const cancel = bevelButton("Cancel", { onClick: () => finish(null), theme, parts: ["dialog.button", "people.button"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] });
-    const ok = bevelButton("Continue", { variant: "primary", onClick: () => submit(), theme, parts: ["dialog.button", "people.button"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] });
+    const cancel = ui.bevelButton("Cancel", { onClick: () => finish(null), theme, parts: ["dialog.button", "people.button"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] });
+    const ok = ui.bevelButton("Continue", { variant: "primary", onClick: () => submit(), theme, parts: ["dialog.button", "people.button"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] });
     footer.append(cancel, ok);
 
     const submit = () => {
@@ -314,7 +357,7 @@ function askName() {
     const onKey = (event) => {
       if (event.key === "Tab") {
         event.stopPropagation();
-        keepFocusIn(panel, event);
+        ui.keepFocusIn(panel, event);
         return;
       }
       if (event.key === "Escape") {
@@ -343,13 +386,12 @@ function askName() {
       cancelAsking = null;
       resolve(person);
     }
-    dismissOf.set(root, () => finish(null));
+    ui.dismissOf.set(root, () => finish(null));
 
     root.setAttribute("aria-hidden", "false");
     modalHost().append(root);
     input.focus();
   });
-  return asking;
 }
 
 // A page's own modal <dialog> makes everything outside it inert, so the prompt goes inside
@@ -367,9 +409,20 @@ function registrySignature() {
   return JSON.stringify([...saved().values()].map(({ id, name }) => [id, name]));
 }
 
+// The observer belongs to the page rather than to one edit session — a reader repaint
+// has to keep the names in it current — so any read starts it and a session that stops
+// takes it down. It is created with the document it watches held once: a test
+// environment can tear that document down while a mutation is still queued, and a
+// callback that reached for the global afterwards would read a page that is gone.
+let watcher = null;
+
 function observe() {
+  const doc = document;
+  if (watcher?.doc === doc) return;
+  watcher?.observer.disconnect();
   lastRegistry = registrySignature();
-  new MutationObserver((records) => {
+  const observer = new MutationObserver((records) => {
+    if (typeof document === "undefined" || document !== doc) return;
     for (const rec of records) {
       const target = rec.target.nodeType === 1 ? rec.target : rec.target.parentElement;
       // A removed clay-people attribute no longer matches the selector, so it is caught by name.
@@ -387,25 +440,99 @@ function observe() {
         return;
       }
     }
-  }).observe(document.body, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ["value", "clay-people"] });
+  });
+  observer.observe(doc.body, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ["value", "clay-people"] });
+  watcher = { doc, observer };
+}
+
+function unobserve() {
+  watcher?.observer.disconnect();
+  watcher = null;
+}
+
+// The editing half: the host answer that names me and the two listeners that keep it
+// current, added once for the boot and a lease alike. Each checks the mode when it fires,
+// so a session that has ended asks the host nothing.
+let session = null;
+
+function startEditing() {
+  if (!editing()) return Promise.resolve(null);
+  if (!session) {
+    const listeners = new AbortController();
+    const { signal } = listeners;
+    window.addEventListener("storage", (event) => {
+      if (event.key !== STORE || !editing()) return;
+      local = undefined;
+      emit();
+    }, { signal });
+    document.addEventListener("visibilitychange", () => {
+      if (!editing()) return;
+      if (document.visibilityState === "visible" && outcome !== "none") refresh(true);
+    }, { signal });
+    session = { listeners, first: refresh(false) };
+  }
+  return Promise.race([session.first, new Promise((resolve) => setTimeout(resolve, BOOT_WAIT_MS))]);
+}
+
+function stopEditing() {
+  session?.listeners.abort();
+  session = null;
 }
 
 async function init() {
   observe();
   // A reader is nobody and picks nobody, so a read-only page never asks the host.
-  if (!editing()) return;
-  window.addEventListener("storage", (event) => {
-    if (event.key !== STORE) return;
-    local = undefined;
-    emit();
-  });
-  document.addEventListener("visibilitychange", () => {
-    if (document.visibilityState === "visible" && outcome !== "none") refresh(true);
-  });
-  const first = refresh(false);
-  await Promise.race([first, new Promise((resolve) => setTimeout(resolve, BOOT_WAIT_MS))]);
+  await startEditing();
+}
+
+function peopleLease() {
+  return {
+    enable() {
+      observe();
+      startEditing();
+    },
+    quiesce() {
+      if (!asking) return;
+      throw Object.assign(new Error("clay:people: a name is still being chosen"), {
+        code: "pending-input",
+        pending: ["name"],
+      });
+    },
+    resume() {},
+    dispose() {
+      cancelAsking?.();
+      unobserve();
+      stopEditing();
+    },
+  };
 }
 
+/**
+ * Attribution as a mode lease.
+ *
+ * Reading names is not editing, so every read keeps the registry observer running and
+ * costs a session nothing. What a session adds is a name that is still being chosen: a
+ * half-answered prompt is input nobody has committed, so `quiesce` refuses the exit
+ * rather than closing it, and `resume` leaves that same prompt on screen. `dispose`
+ * (after the barrier) takes back both the prompt and the observer, and the next read
+ * starts watching again.
+ */
+export function peopleParticipant() {
+  return {
+    id: "clay:people",
+    order: 330,
+    prepare(context = {}) {
+      const lease = peopleLease();
+      // An adoption is the session this module's own import already started: the exit
+      // takes it back, and the commit starts nothing a second time.
+      if (context.initial !== true) return lease;
+      return { ...lease, enable() {} };
+    },
+  };
+}
+
+export { peopleParticipant as modeParticipant };
+
 export const people = Object.freeze({ get, list, available, add, remove, canRename, rename });
 
 export const ready = init();

package/src/plugins/richclay.js

@@ -4,18 +4,128 @@
 import { installSkin } from "../ui/vendor-skin.js";
 import { CSS, ROOTS } from "../ui/skins/richclay.js";
 import { RichClay } from "../vendor/richclay.vendor.js";
-import { isEditMode } from "../core/is-edit-mode.js";
+import { startsAtImport } from "../core/is-edit-mode.js";
 
 installSkin("richclay", CSS, { roots: ROOTS });
 
-// A frame's snapshot carries none of RichClay's runtime state, and the merge removes
-// live attributes the merged page lacks, so an applied frame leaves editors that can
-// no longer be typed into. RichClay's reattach() restores them. View mode mounts none.
-if (isEditMode) {
-  document.addEventListener("clay:sync-applied", () => {
-    for (const editor of RichClay.init()) editor.reattach();
-  });
+let session = null;
+
+const fault = (message, code) => Object.assign(new Error(`clay:richclay: ${message}`), { code });
+
+const isStale = (context) => {
+  if (!context) return false;
+  if (context.signal?.aborted) return true;
+  return typeof context.isCurrent === "function" && !context.isCurrent();
+};
+
+const ownership = (root) => ({
+  root,
+  win: root.ownerDocument?.defaultView || window,
+  admitted: false,
+  stopWatch: null,
+  subscriber: null,
+});
+
+const elements = (record) => [...record.root.querySelectorAll(RichClay.selector)];
+
+// Mounts the regions the page has, and repairs the ones an applied frame stripped: a frame's
+// snapshot carries none of RichClay's runtime state, and the merge removes live attributes
+// the merged page lacks, so an applied frame leaves editors that can no longer be typed
+// into. RichClay's reattach() restores them.
+function mount(record) {
+  for (const editor of RichClay.init(elements(record))) editor.reattach();
+}
+
+// One edit session over the live DOM. `enable` mounts the page's regions and starts the one
+// watcher for regions that arrive later; `quiesce` closes admission, so a region that
+// arrives while the exit runs is given no editor; `resume` is the refused exit, over the
+// same session; `dispose` destroys every instance and removes exactly the subscription it
+// added, so the view it leaves behind holds no editor and the next entry begins from
+// nothing.
+function richclayLease(record) {
+  const onFrame = () => mount(record);
+  return {
+    enable() {
+      if (record.admitted) return;
+      record.admitted = true;
+      mount(record);
+      record.stopWatch = RichClay.watch(record.win);
+      const target = record.root.ownerDocument || document;
+      record.subscriber = { target, type: "clay:sync-applied", handler: onFrame };
+      target.addEventListener(record.subscriber.type, onFrame);
+    },
+    quiesce() {
+      record.admitted = false;
+      if (record.stopWatch) {
+        record.stopWatch();
+        record.stopWatch = null;
+      }
+    },
+    resume() {
+      if (record.admitted) return;
+      record.admitted = true;
+      record.stopWatch = RichClay.watch(record.win);
+    },
+    dispose() {
+      record.admitted = false;
+      if (record.stopWatch) {
+        record.stopWatch();
+        record.stopWatch = null;
+      }
+      const subscriber = record.subscriber;
+      record.subscriber = null;
+      if (subscriber) subscriber.target.removeEventListener(subscriber.type, subscriber.handler);
+      for (const el of elements(record)) RichClay.stripElement(el);
+      if (session === record) session = null;
+    },
+  };
 }
 
-export { RichClay };
+/**
+ * RichClay as a mode participant: the editors the commit that enters edit mounts, and the
+ * ones the exit takes back.
+ *
+ * `prepare` takes the vendor's auto-watch out of the page first, so every instance is this
+ * session's to quiesce and destroy and an entry never meets an editor it did not mount; a
+ * vendor build without that lifecycle support is refused here rather than left half
+ * mounted in a view. `enable` mounts the regions and starts the session's own watcher.
+ * `quiesce` stops admitting regions. `dispose` destroys the instances and hands back the
+ * frame subscription, leaving no editor behind for the reader's page.
+ */
+export function richclayParticipant(root = document) {
+  return {
+    id: "clay:richclay",
+    order: 310,
+    async prepare(context = {}) {
+      if (context.initial === true) return adopt();
+      if (typeof RichClay.watch !== "function" || typeof RichClay.stripElement !== "function") {
+        throw fault("this vendor build has no watchable lifecycle", "unsupported-plugin");
+      }
+      if (isStale(context)) throw fault("prepared for a stale generation", "stale-document");
+      const stopAutoWatch = RichClay.autoInit?.();
+      if (typeof stopAutoWatch === "function") stopAutoWatch();
+      return richclayLease(session || (session = ownership(root)));
+    },
+  };
+}
+
+// The boot this tab already made, adopted instead of prepared: it is the session `init`
+// below enabled, or, on a boot that started none, nothing to hand back.
+async function adopt() {
+  const lease = await ready;
+  return { enable() {}, quiesce: () => lease?.quiesce(), resume: () => lease?.resume(), dispose: () => lease?.dispose() };
+}
+
+// Auto-init when the module is imported; the loader awaits `ready` before resolving clay.ready
+async function init() {
+  if (!startsAtImport()) return null;
+  const lease = await richclayParticipant().prepare();
+  lease.enable();
+  return lease;
+}
+
+const ready = init();
+
+export { RichClay, init, ready };
+export { richclayParticipant as modeParticipant };
 export default RichClay;