@panphora/clayjs 0.1.0 → 0.2.1

package/src/dom/form-data.js

@@ -0,0 +1,62 @@
+// easily convert a form into a JS object
+function getDataFromForm(container) {
+  const formData = {};
+
+  // Helper function to process a single element
+  const processElement = (elem) => {
+    const name = elem.getAttribute('name');
+    const value = elem.value || elem.getAttribute('value');
+
+    // Skip elements without a name or with a disabled attribute
+    if (!name || elem.disabled) return;
+
+    // Handle different element types
+    switch (elem.type) {
+      case 'checkbox':
+        if (!formData[name]) {
+          formData[name] = [];
+        }
+        if (elem.checked) {
+          formData[name].push(value);
+        }
+        break;
+      case 'radio':
+        if (elem.checked) {
+          formData[name] = value;
+        }
+        break;
+      case 'select-multiple':
+        formData[name] = Array.from(elem.selectedOptions, option => option.value);
+        break;
+      case 'button':
+      case 'submit':
+      case 'reset':
+        // Only include buttons if they have both name and value attributes
+        if (name && value) {
+          formData[name] = value;
+        }
+        break;
+      default:
+        formData[name] = value;
+    }
+  };
+
+  // If container is a form, use elements property
+  if (container instanceof HTMLFormElement) {
+    Array.from(container.elements).forEach(processElement);
+  }
+  // Otherwise, process container itself and then query for elements with name attribute
+  else {
+    // Process container element if it has a name attribute
+    if (container.hasAttribute('name')) {
+      processElement(container);
+    }
+    // Process all child elements with name attributes
+    const elements = container.querySelectorAll('[name]');
+    elements.forEach(processElement);
+  }
+
+  return formData;
+}
+
+export default getDataFromForm;

package/src/dom/insert-style-tag.js

@@ -0,0 +1,109 @@
+/**
+ * Insert styles into the document (inline CSS or external stylesheet).
+ *
+ * With a persistent DOM (i.e. clayjs), we need a way to update styles.
+ * This function reuses existing elements when possible:
+ *   - Inline styles: matches by data-name, reuses if content matches
+ *   - External stylesheets: matches by normalized full URL path
+ *
+ * This ensures:
+ *   - No DOM churn: existing elements are reused when content/path matches
+ *   - No duplicates: removes any duplicate style/link elements
+ *   - Callback always runs: attributes can be updated on existing elements
+ *
+ * WHY REUSE IN-PLACE:
+ * In a persistent DOM (clayjs), removing and re-adding elements changes their
+ * position and surrounding whitespace. This causes snapshot diffs even when content
+ * is identical, triggering false "unsaved changes" warnings. Reusing existing
+ * elements preserves DOM structure for stable snapshots.
+ *
+ * Usage:
+ *   insertStyles('/path/to/file.css')                    // External stylesheet
+ *   insertStyles('/path/to/file.css', (link) => { ... }) // With callback
+ *   insertStyles('my-styles', '.foo { ... }')            // Inline CSS
+ *   insertStyles('my-styles', '.foo { ... }', (style) => { ... }) // With callback
+ */
+function insertStyles(nameOrHref, cssOrCallback, callback) {
+  if (typeof cssOrCallback === 'string') {
+    // Inline style: insertStyles('my-styles', '.foo { ... }', optionalCallback)
+    const name = nameOrHref;
+    const css = cssOrCallback;
+    const existingStyles = [...document.querySelectorAll(`style[data-name="${name}"]`)];
+
+    // If exact match exists, just update attributes via callback and return it
+    const exactMatch = existingStyles.find(el => el.textContent === css);
+    if (exactMatch) {
+      if (callback) callback(exactMatch);
+      // Remove any duplicates
+      existingStyles.filter(el => el !== exactMatch).forEach(el => el.remove());
+      return exactMatch;
+    }
+
+    // Update first existing style in-place, or create new one
+    let style;
+    if (existingStyles.length > 0) {
+      style = existingStyles[0];
+      style.textContent = css;
+      if (callback) callback(style);
+      // Remove duplicates
+      existingStyles.slice(1).forEach(el => el.remove());
+    } else {
+      style = document.createElement('style');
+      style.dataset.name = name;
+      style.textContent = css;
+      if (callback) callback(style);
+      document.head.appendChild(style);
+    }
+
+    return style;
+  }
+
+  // External stylesheet: insertStyles('/path/to/file.css', optionalCallback)
+  const href = nameOrHref;
+  const cb = typeof cssOrCallback === 'function' ? cssOrCallback : undefined;
+
+  // Helper to get base URL without query params (for comparison)
+  const getBaseUrl = (url) => {
+    try {
+      const parsed = new URL(url, window.location.href);
+      return parsed.origin + parsed.pathname;
+    } catch {
+      return url;
+    }
+  };
+
+  // Normalize href to full URL path (without query params) for comparison
+  const normalizedHref = getBaseUrl(href);
+
+  // Find all links with matching normalized path (ignoring query params like ?v=)
+  const existingLinks = [...document.querySelectorAll('link[rel="stylesheet"]')]
+    .filter(el => {
+      try {
+        return getBaseUrl(el.getAttribute('href')) === normalizedHref;
+      } catch {
+        return false;
+      }
+    });
+
+  // If match exists, just update attributes via callback and return it
+  if (existingLinks.length > 0) {
+    const link = existingLinks[0];
+    if (cb) cb(link);
+    // Remove any duplicates
+    existingLinks.slice(1).forEach(el => el.remove());
+    return link;
+  }
+
+  // Create new link element
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = href;
+  if (cb) cb(link);
+  document.head.appendChild(link);
+
+  return link;
+}
+
+export { insertStyles };
+export { insertStyles as insertStyleTag };  // backwards-compat alias
+export default insertStyles;

package/src/dom/nearest.js

@@ -0,0 +1,97 @@
+/**
+ * Searches for elements matching a CSS selector by exploring the DOM tree outward from a starting point,
+ * checking nearby elements first before moving to more distant parts of the document.
+ *
+ * Unlike `element.closest()` which only searches ancestors, this explores the DOM tree in a
+ * unique pattern designed to find nearby elements in the visual layout:
+ *
+ * TRAVERSAL ORDER (for each level):
+ * 1. Current element
+ * 2. All children of current element (deeply)
+ * 3. All previous siblings (right-to-left), exploring each fully with descendants
+ * 4. All next siblings (left-to-right), exploring each fully with descendants
+ * 5. Move to parent and repeat from step 1
+ *
+ * KEY FEATURES:
+ * - Global visited cache prevents revisiting nodes (big performance boost)
+ * - Searches "outward" from start position, checking nearby elements first
+ * - Explores each sibling's entire subtree before moving to next sibling
+ * - Continues up the ancestor chain until document.body
+ *
+ * USE CASES:
+ * - Finding related UI elements that might be siblings or cousins
+ * - Locating the "next" instance of something in reading order
+ * - Finding nearby form fields, buttons, or other interactive elements
+ *
+ * @param {Element} startElem - Starting element for the search
+ * @param {string} selector - CSS selector to match
+ * @param {Function} elementFoundReturnValue - Transform function for the found element
+ * @returns {*} Transformed element if found, null otherwise
+ */
+export default function nearest (startElem, selector, elementFoundReturnValue = x => x) {
+  const visited = new Set();
+
+  // Check node and its descendants using BFS
+  function checkDeep(root) {
+    if (!root || visited.has(root)) return null;
+
+    const queue = [root];
+    const localVisited = new Set(); // Prevent cycles within this BFS
+
+    while (queue.length > 0) {
+      const node = queue.shift();
+      if (!node || localVisited.has(node) || visited.has(node)) continue;
+
+      visited.add(node);
+      localVisited.add(node);
+
+      if (node.matches(selector)) {
+        return elementFoundReturnValue(node);
+      }
+
+      queue.push(...node.children);
+    }
+    return null;
+  }
+
+  // Check siblings in a direction
+  function checkSiblings(start, direction) {
+    let sibling = start[direction];
+    while (sibling) {
+      const result = checkDeep(sibling);
+      if (result) return result;
+      sibling = sibling[direction];
+    }
+    return null;
+  }
+
+  // Main traversal
+  // check current → children → siblings → move up
+  let current = startElem;
+
+  while (current) {
+    // Check current node (shallow)
+    if (!visited.has(current)) {
+      visited.add(current);
+      if (current.matches(selector)) {
+        return elementFoundReturnValue(current);
+      }
+    }
+
+    // Check children deeply
+    for (const child of current.children) {
+      const result = checkDeep(child);
+      if (result) return result;
+    }
+
+    // Check siblings deeply
+    let result = checkSiblings(current, 'previousElementSibling') ||
+                 checkSiblings(current, 'nextElementSibling');
+    if (result) return result;
+
+    // Move up to parent
+    current = current.parentElement;
+  }
+
+  return null;
+}

package/src/dom/pipe.js

@@ -0,0 +1 @@
+export default (...fns) => x => fns.reduce((v, f) => f(v), x);

package/src/events/index.js

@@ -0,0 +1,22 @@
+// Events module - combines all event attribute handlers
+import { init as initOnclickaway } from './onclickaway.js';
+import { init as initOnclickchildren } from './onclickchildren.js';
+import { init as initOnclone } from './onclone.js';
+import { init as initOnmutation } from './onmutation.js';
+import { init as initOnpagemutation } from './onpagemutation.js';
+import { init as initOnrender } from './onrender.js';
+
+function init() {
+  initOnclickaway();
+  initOnclickchildren();
+  initOnclone();
+  initOnmutation();
+  initOnpagemutation();
+  initOnrender();
+}
+
+// Auto-init when module is imported
+init();
+
+export { init };
+export default init;

package/src/events/onclickaway.js

@@ -0,0 +1,27 @@
+function init () {
+
+  // the code inside `onclickaway` attributes will be executed whenever that element is NOT clicked
+  document.addEventListener('click', function(event) {
+    const elementsWithOnClickAway = document.querySelectorAll('[onclickaway]');
+
+    elementsWithOnClickAway.forEach(element => {
+      let targetElement = event.target; // clicked element
+
+      do {
+        if (targetElement === element) {
+          // Click inside, do nothing
+          return;
+        }
+        // Go up the DOM
+        targetElement = targetElement.parentNode;
+      } while (targetElement);
+
+      // Click outside the element, execute onclickaway
+      new Function(element.getAttribute('onclickaway')).call(element);
+    });
+  });
+
+}
+
+export { init };
+export default init;

package/src/events/onclickchildren.js

@@ -0,0 +1,12 @@
+function init() {
+  document.addEventListener('click', function(event) {
+    const parent = event.target.closest('[onclickchildren]');
+    if (parent && event.target !== parent) {
+      const directChild = event.composedPath().find(el => el.parentNode === parent);
+      new Function(parent.getAttribute('onclickchildren')).call(directChild);
+    }
+  });
+}
+
+export { init };
+export default init;

package/src/events/onclone.js

@@ -0,0 +1,54 @@
+function init() {
+  // Bail if already patched (idempotence)
+  if (Node.prototype.__hyperclayOnclone) {
+    return;
+  }
+
+  const originalCloneNode = Node.prototype.cloneNode;
+
+  // Store original for idempotence check
+  Node.prototype.__hyperclayOnclone = originalCloneNode;
+
+  Node.prototype.cloneNode = function(deep) {
+    const clonedNode = originalCloneNode.call(this, deep);
+
+    if (clonedNode.nodeType === Node.ELEMENT_NODE) {
+      if (!window.__preventOnclone) {
+        processOnclone(clonedNode);
+        clonedNode.querySelectorAll('[onclone]').forEach(processOnclone);
+      }
+
+      // Patch textareas: the persist module writes live values to data-value
+      // on every keystroke (because writing textContent on a focused textarea
+      // destroys cursor/scroll). Shift data-value into textContent on the
+      // clone so consumers get the current value without special handling.
+      if (deep) {
+        const textareas = clonedNode.tagName === 'TEXTAREA'
+          ? [clonedNode]
+          : clonedNode.querySelectorAll('textarea[data-value]');
+        textareas.forEach(ta => {
+          const val = ta.getAttribute('data-value');
+          if (val !== null) {
+            ta.textContent = val;
+            ta.removeAttribute('data-value');
+          }
+        });
+      }
+    }
+
+    return clonedNode;
+  };
+
+  function processOnclone(element) {
+    const oncloneCode = element.getAttribute('onclone');
+    if (oncloneCode) {
+      try {
+        new Function(oncloneCode).call(element);
+      } catch (error) {
+        console.error('Error executing onclone:', error);
+      }
+    }
+  }
+}
+export { init };
+export default init;

package/src/events/onmutation.js

@@ -0,0 +1,54 @@
+/*
+   [onmutation] - Trigger code when this element or its children change
+
+   Usage:
+   <div onmutation="console.log('My content changed')">
+     <span contenteditable>Edit me</span>
+   </div>
+
+   Unlike [onglobalmutation]/[onpagemutation] which fires on ANY DOM change,
+   [onmutation] only fires when the element itself or its descendants mutate.
+*/
+import Mutation from "../lib/mutation.js";
+
+async function executeMutation(element) {
+  try {
+    const code = element.getAttribute('onmutation');
+    if (!code) return;
+    const asyncFn = new Function(`return (async function() { ${code} })`)();
+    await asyncFn.call(element);
+  } catch (error) {
+    console.error('Error in onmutation execution:', error);
+  }
+}
+
+function init() {
+  // Source from the single shared observer instead of one MutationObserver per
+  // [onmutation] element. For each change, fire every [onmutation] element whose
+  // subtree it belongs to: walk up from the element whose subtree actually
+  // changed — the still-attached parent for add/remove (the removed node is
+  // detached), otherwise the changed element itself — and run any [onmutation]
+  // ancestor, exactly as a per-element subtree observer would. An element's own
+  // insertion is its parent's childList change, so (correctly) doesn't fire it.
+  //
+  // require:'observed' makes it region-aware (skips no-watch / extension noise),
+  // which the old per-element observers were not. It stays PAUSABLE (the
+  // default): a live-sync morph must NOT fire the hook, or the hook's own DOM
+  // writes would autosave → broadcast → morph the other tab → fire the same hook
+  // → broadcast back, looping forever. Skipping morphs is safe because the other
+  // tab already ran this identical hook, so the morph carries the result.
+  Mutation.onAnyChange({ require: 'observed' }, (changes) => {
+    const toFire = new Set();
+    for (const change of changes) {
+      let el = (change.type === 'add' || change.type === 'remove') ? change.parent : change.element;
+      while (el && el.nodeType === 1) {
+        if (el.hasAttribute('onmutation')) toFire.add(el);
+        el = el.parentElement;
+      }
+    }
+    toFire.forEach(executeMutation);
+  });
+}
+
+export { init };
+export default init;

package/src/events/onpagemutation.js

@@ -0,0 +1,37 @@
+/*
+   [onpagemutation] / [onglobalmutation] - Trigger code when ANY element on the page changes
+
+   Usage:
+   <span onglobalmutation="this.textContent = All('li').length">0</span>
+   <span onpagemutation="this.textContent = All('li').length">0</span>
+
+   Both attributes are equivalent - onglobalmutation is the preferred name for clarity.
+*/
+import Mutation from "../lib/mutation.js";
+
+function init() {
+  const executeGlobalMutation = async element => {
+    try {
+      // Support both onglobalmutation and onpagemutation (legacy)
+      const code = element.getAttribute('onglobalmutation') || element.getAttribute('onpagemutation');
+      const asyncFn = new Function(`return (async function() { ${code} })`)();
+      await asyncFn.call(element);
+    } catch (error) {
+      console.error('Error in onglobalmutation/onpagemutation execution:', error);
+    }
+  };
+
+  // Pausable (the default): a live-sync morph must NOT trigger these hooks, or
+  // their DOM writes would autosave → broadcast → morph the other tab → fire the
+  // same hook → broadcast back, looping forever. Safe to skip morphs because the
+  // other tab already ran the identical hook and the morph carries the result.
+  Mutation.onAnyChange({
+    debounce: 200,
+    omitChangeDetails: true,
+    require: 'observed'
+  }, () => {
+    document.querySelectorAll('[onglobalmutation], [onpagemutation]').forEach(executeGlobalMutation);
+  });
+}
+export { init };
+export default init;

package/src/events/onrender.js

@@ -0,0 +1,32 @@
+import Mutation from "../lib/mutation.js";
+import onLoad from "../lib/on-load.js";
+
+function init() {
+  const executeRender = async (element) => {
+    try {
+      const code = element.getAttribute('onrender');
+      const asyncFn = new Function(`return (async function() { ${code} })`)();
+      await asyncFn.call(element);
+    } catch (error) {
+      console.error('Error in onrender execution:', error);
+    }
+  };
+
+  // Execute onrender on page load
+  onLoad(() => {
+    document.querySelectorAll('[onrender]').forEach(executeRender);
+  });
+
+  // Execute onrender when new elements are added
+  Mutation.onAddElement({
+    selectorFilter: "[onrender]",
+    debounce: 200,
+    require: 'observed',
+    pausable: false
+  }, (changes) => {
+    changes.forEach(({ element }) => executeRender(element));
+  });
+}
+
+export { init };
+export default init;

package/src/lib/mutation.js

@@ -72,7 +72,7 @@ import { isUserDrivenNow, markUserDriven } from './user-gesture.js';
 
 const dummyElem = document.createElement("div");
 
-const Mutation = {
+const localMutation = {
   _callbacks: {
     anyChange: [],
     addOrRemove: [],
@@ -707,13 +707,30 @@ const Mutation = {
   }
 };
 
-// Signal consumers (e.g. hypercms ?cms=true auto-open) that Mutation is ready,
-// so they can react instead of polling. Wrapped so a dispatch failure can never
-// break the install.
-try {
-  document.dispatchEvent(new CustomEvent('clay:mutation-ready', { detail: { Mutation } }));
-  // vendor-compat: hypercms's readiness fast path listens for the legacy name
-  document.dispatchEvent(new CustomEvent('hyperclay:mutation-ready', { detail: { Mutation } }));
-} catch {}
+// Realm-global singleton, keyed by identity not module URL. A satellite bootstrap
+// that imports this module from a different origin (apex vs www, clayjs.com vs
+// jsdelivr, version-pinned URLs) evaluates a second module instance; without this,
+// each would create its own MutationObserver and silently double-observe. The
+// first instance to evaluate publishes its hub on window.__clayMutation; every
+// later instance adopts it and never creates a second observer.
+const existingHub = typeof window !== 'undefined' && window.__clayMutation;
+const Mutation = existingHub || localMutation;
+
+if (typeof window !== 'undefined' && !existingHub) {
+  window.__clayMutation = Mutation;
+  // Publish the vendor-compat mirror BEFORE the readiness dispatch: sap's mutation
+  // bridge reads window.hyperclay.Mutation when hyperclay:mutation-ready fires, so
+  // the hub must already be in place or sap keeps its own native observer.
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.Mutation = Mutation;
+  // Signal consumers (e.g. hypercms ?cms=true auto-open, sap's late-hub listener)
+  // that Mutation is ready, so they can react instead of polling. Wrapped so a
+  // dispatch failure can never break the install.
+  try {
+    document.dispatchEvent(new CustomEvent('clay:mutation-ready', { detail: { Mutation } }));
+    // vendor-compat: hypercms's readiness fast path listens for the legacy name
+    document.dispatchEvent(new CustomEvent('hyperclay:mutation-ready', { detail: { Mutation } }));
+  } catch {}
+}
 
 export default Mutation;

package/src/lib/on-load.js

@@ -0,0 +1,9 @@
+function onLoad (callback) {
+  if (document.readyState === "complete") {
+    callback();
+  } else {
+    window.addEventListener("load", callback);
+  }
+}
+
+export default onLoad;

package/src/loader-logic.js

@@ -21,9 +21,10 @@ export const PLUGIN_PATHS = {
   sortable:  { path: "plugins/sortable.js",        editOnly: true,  default: false },
   undo:      { path: "plugins/undo.js",            editOnly: true,  default: false },
   cms:       { path: "vendor/hypercms.vendor.js",  editOnly: false, default: false },
+  demo:      { path: "plugins/demo.js",            editOnly: false, default: false },
 };
 
-const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync"];
+const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync", "demo"];
 
 function parseCsv(params, key, enabled, apply) {
   const raw = params.get(key);

package/src/loader.js

@@ -108,6 +108,8 @@ function attachPluginMember(path, mod) {
   } else if (path === "vendor/hypercms.vendor.js") {
     clay.cms = mod.cms || mod.default;
     window.hyperclay.hypercms = clay.cms;
+  } else if (path === "plugins/demo.js") {
+    clay.demo = mod.demo;
   } else if (path === "vendor/richclay.vendor.js") {
     window.hyperclay.RichClay = mod.RichClay || mod.default;
   }