@gemboss/gem-framework 0.5.2 → 0.9.0

package/dist/runtime-core.d.ts

@@ -0,0 +1,51 @@
+// Types for @gemboss/gem-framework/runtime-core (runtime-core.js, copied as is into dist/). Hand-written next to the
+// file it describes; the package build test type-checks a consumer against it (package-build.test.ts).
+
+/** A gem:* event callback. The detail's shape depends on the event, so it is left to the caller. */
+export type GemEventCallback = (detail: any) => void;
+
+/** The shape of window.GemTheme: on() returns an unsubscribe, emit() fires a document CustomEvent and the callbacks. */
+export interface GemApi {
+  listeners: Record<string, GemEventCallback[]>;
+  on(event: string, callback: GemEventCallback): () => void;
+  emit(event: string, detail?: Record<string, unknown>): void;
+}
+
+export interface MountOptions {
+  /** The event hub (pass window.GemTheme to share one with gem-runtime.js). Default: one hub shared by the modules. */
+  api?: GemApi;
+  /** The window used for timers, storage and scroll. Default: root.ownerDocument.defaultView. */
+  window?: Window | typeof globalThis;
+  [option: string]: unknown;
+}
+
+/** Removes what one mount() added. Calling it twice does nothing the second time. */
+export type Unmount = () => void;
+
+/** An expando a plugin sets on its elements instead of a data-gem-bound-<key> mark (offer-engine: __gemOffer). */
+export interface PluginGuard {
+  selector: string;
+  prop: string;
+}
+
+/** The names a plugin body is given, scoped to one root. */
+export interface PluginInstallScope {
+  document: Document;
+  window: Window;
+  target: Window;
+  mark(element: Element | null | undefined, key: string): boolean;
+  canListen(element: unknown): boolean;
+  listen(element: EventTarget, type: string, callback: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  registerPlugin(key: string, setup: (context: { api: GemApi; config: unknown; reason: string }) => void): void;
+  registerNoopPlugin(key: string, readyEvent?: string): void;
+}
+
+export declare function createGemApi(doc?: Document): GemApi;
+export declare function gemApi(): GemApi;
+export declare function mountPlugin(
+  key: string,
+  install: (scope: PluginInstallScope) => void,
+  root?: ParentNode | null,
+  options?: MountOptions,
+  guard?: PluginGuard,
+): Unmount;

package/dist/runtime-core.js

@@ -0,0 +1,176 @@
+// @gemboss/gem-framework/runtime-core: what every dist/plugins/<key>.js shares (gem-framework 0.8.0).
+//
+// A plugin module carries the SAME plugin body gem-runtime.js carries (runtime.ts, one table), and this file gives
+// that body the names it expects (`document`, `window`, `target`, `mark`, `canListen`, `registerPlugin`) scoped to
+// one root, and keeps a ledger of what the body did so unmount() can undo it:
+//   - listeners (the module wraps every `x.addEventListener(` of the body as `__gemListen(x, `), timers,
+//     animation frames and IntersectionObservers made through `window` / `target`;
+//   - the `data-gem-bound-<key>` marks it set, so the same root can be mounted again after an unmount.
+// Importing this file does nothing: no global is read or written until mount() is called.
+
+const mounted = new WeakMap(); // root -> Map(key -> { count, teardown })
+let sharedApi = null;
+
+/** An event hub with the shape of window.GemTheme: on(), emit() (a document CustomEvent + the callbacks), listeners. */
+export function createGemApi(doc) {
+  const listeners = {};
+  return {
+    listeners,
+    on(event, callback) {
+      (listeners[event] ||= []).push(callback);
+      return () => { listeners[event] = (listeners[event] || []).filter((item) => item !== callback); };
+    },
+    emit(event, detail = {}) {
+      const d = doc || globalThis.document;
+      const Event = (d && d.defaultView && d.defaultView.CustomEvent) || globalThis.CustomEvent;
+      if (d && typeof d.dispatchEvent === "function" && Event) d.dispatchEvent(new Event(event, { detail }));
+      for (const callback of listeners[event] || []) callback(detail);
+    },
+  };
+}
+
+/** The hub every plugin module uses unless mount() is given `options.api` (pass window.GemTheme to share one). */
+export function gemApi() {
+  return (sharedApi ||= createGemApi());
+}
+
+const bindMethod = (owner, value, prop) => (typeof value === "function" && !/^[A-Z]/.test(String(prop)) ? value.bind(owner) : value);
+
+// `document` for a plugin mounted on an element: queries see only that element and what is inside it (the element
+// itself included, as gemsite's behaviors match their own root); everything else is the real document.
+function scopedDocument(root, doc) {
+  const matches = (selector) => typeof root.matches === "function" && root.matches(selector);
+  const own = {
+    querySelectorAll: (selector) => {
+      const found = Array.from(root.querySelectorAll(selector));
+      return matches(selector) ? [root, ...found] : found;
+    },
+    querySelector: (selector) => (matches(selector) ? root : root.querySelector(selector)),
+  };
+  return new Proxy(doc, {
+    get: (real, prop) => (Object.prototype.hasOwnProperty.call(own, prop) ? own[prop] : bindMethod(real, Reflect.get(real, prop), prop)),
+  });
+}
+
+// `window` / `target` for a plugin: the real window, except that timers, frames and observers made through it are
+// remembered so unmount() can stop them.
+function trackedWindow(win, ledger) {
+  const own = {
+    setTimeout: (fn, ms, ...args) => {
+      const id = win.setTimeout(() => { ledger.timeouts.delete(id); fn(...args); }, ms);
+      ledger.timeouts.add(id);
+      return id;
+    },
+    clearTimeout: (id) => { ledger.timeouts.delete(id); win.clearTimeout(id); },
+    setInterval: (fn, ms, ...args) => {
+      const id = win.setInterval(fn, ms, ...args);
+      ledger.intervals.add(id);
+      return id;
+    },
+    clearInterval: (id) => { ledger.intervals.delete(id); win.clearInterval(id); },
+    requestAnimationFrame: typeof win.requestAnimationFrame === "function"
+      ? (fn) => {
+          const id = win.requestAnimationFrame((time) => { ledger.frames.delete(id); fn(time); });
+          ledger.frames.add(id);
+          return id;
+        }
+      : undefined,
+    IntersectionObserver: typeof win.IntersectionObserver === "function"
+      ? class extends win.IntersectionObserver {
+          constructor(callback, init) {
+            super(callback, init);
+            ledger.observers.add(this);
+          }
+          disconnect() {
+            ledger.observers.delete(this);
+            super.disconnect();
+          }
+        }
+      : undefined,
+  };
+  return new Proxy(win, {
+    get: (real, prop) => (Object.prototype.hasOwnProperty.call(own, prop) ? own[prop] : bindMethod(real, Reflect.get(real, prop), prop)),
+    set: (real, prop, value) => Reflect.set(real, prop, value),
+    has: (real, prop) => (Object.prototype.hasOwnProperty.call(own, prop) ? own[prop] !== undefined : prop in real),
+  });
+}
+
+/**
+ * Run one plugin's install() against `root` (default: the whole document) and return unmount().
+ * Mounting a key on a root it is already mounted on binds nothing more: it returns another handle on the same
+ * mount, and the plugin is torn down when the last handle is released.
+ * `guard` names an expando the plugin body sets on its elements instead of a data-gem-bound mark (offer-engine:
+ * `__gemOffer`); unmount clears it on the elements this mount bound so a later mount binds them again.
+ */
+export function mountPlugin(key, install, root, options = {}, guard) {
+  const scope = root || globalThis.document;
+  if (!scope || typeof scope.querySelectorAll !== "function") return () => {};
+  let byKey = mounted.get(scope);
+  if (!byKey) mounted.set(scope, (byKey = new Map()));
+  const existing = byKey.get(key);
+  if (existing) {
+    existing.count += 1;
+    return release(byKey, key, existing);
+  }
+
+  const doc = scope.nodeType === 9 ? scope : scope.ownerDocument || globalThis.document;
+  const win = options.window || (doc && doc.defaultView) || globalThis;
+  const api = options.api || (doc === globalThis.document ? gemApi() : createGemApi(doc));
+  const ledger = { listeners: [], marks: [], timeouts: new Set(), intervals: new Set(), frames: new Set(), observers: new Set() };
+  const window = trackedWindow(win, ledger);
+  const document = scope === doc ? doc : scopedDocument(scope, doc);
+  // `data-gem-bound-<key>` with ANY value means bound, including one the markup carries to claim an element for its own
+  // behavior (promo-popup.email-capture.v1). Teardown removes only the marks in this ledger, never a claim.
+  const mark = (element, markKey) => {
+    const attr = "data-gem-bound-" + markKey;
+    if (!element || element.hasAttribute(attr)) return false;
+    element.setAttribute(attr, "true");
+    ledger.marks.push([element, attr]);
+    return true;
+  };
+  const canListen = (element) => Boolean(element && typeof element.addEventListener === "function");
+  const listen = (element, type, callback, listenOptions) => {
+    element.addEventListener(type, callback, listenOptions);
+    ledger.listeners.push(() => element.removeEventListener && element.removeEventListener(type, callback, listenOptions));
+  };
+  let setup = null;
+  const registerPlugin = (registeredKey, fn) => { if (registeredKey === key) setup = fn; };
+  const registerNoopPlugin = (registeredKey, readyEvent) => {
+    registerPlugin(registeredKey, ({ api: hub }) => { if (readyEvent) hub.emit(readyEvent, { source: "gem-runtime" }); });
+  };
+  const unguarded = guard ? Array.from(document.querySelectorAll(guard.selector)).filter((element) => !element[guard.prop]) : [];
+
+  const teardown = () => {
+    ledger.timeouts.forEach((id) => win.clearTimeout(id));
+    ledger.intervals.forEach((id) => win.clearInterval(id));
+    ledger.frames.forEach((id) => win.cancelAnimationFrame && win.cancelAnimationFrame(id));
+    ledger.observers.forEach((observer) => observer.disconnect());
+    ledger.listeners.splice(0).reverse().forEach((off) => off());
+    ledger.marks.splice(0).forEach(([element, attr]) => element.removeAttribute(attr));
+    if (guard) unguarded.forEach((element) => { delete element[guard.prop]; });
+  };
+  try {
+    install({ document, window, target: window, mark, canListen, listen, registerPlugin, registerNoopPlugin });
+    if (typeof setup === "function") {
+      setup({ api, config: { planId: "gem-plugin-module", plugins: [{ key, loadStrategy: "mount", dependsOn: [] }] }, reason: "mount" });
+    }
+  } catch (error) {
+    teardown(); // a plugin that throws half way leaves nothing bound behind it
+    throw error;
+  }
+  const record = { count: 1, teardown };
+  byKey.set(key, record);
+  return release(byKey, key, record);
+}
+
+function release(byKey, key, record) {
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    record.count -= 1;
+    if (record.count > 0) return;
+    if (byKey.get(key) === record) byKey.delete(key);
+    record.teardown();
+  };
+}