npm - hyperclayjs - Versions diffs - 1.7.0 → 1.9.0 - Mend

hyperclayjs 1.7.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (67) hide show

package/src/core/snapshot.js ADDED Viewed

@@ -0,0 +1,203 @@
+/**
+ * snapshot.js — The source of truth for page state
+ *
+ * THE SAVE/SYNC PIPELINE:
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  1. CLONE         document.documentElement.cloneNode()  │
+ *   └─────────────────────────────────────────────────────────┘
+ *                              │
+ *                              ▼
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  2. SNAPSHOT HOOKS       onSnapshot callbacks           │
+ *   │                          (form value sync)              │
+ *   │                                                         │
+ *   │     ✓ Used by: SAVE and LIVE-SYNC                       │
+ *   └─────────────────────────────────────────────────────────┘
+ *                              │
+ *              ┌───────────────┴───────────────┐
+ *              ▼                               ▼
+ *   ┌─────────────────────────┐     ┌─────────────────────────┐
+ *   │  3a. PREPARE HOOKS      │     │  3b. DONE               │
+ *   │  onPrepareForSave       │     │  (live-sync stops here) │
+ *   │  [onbeforesave]         │     │                         │
+ *   │  [save-ignore]          │     │  → emits snapshot-ready │
+ *   │                         │     └─────────────────────────┘
+ *   │  ✓ Used by: SAVE only   │
+ *   └─────────────────────────┘
+ *              │
+ *              ▼
+ *   ┌─────────────────────────┐
+ *   │  4. SERIALIZE           │
+ *   │  "<!DOCTYPE html>"      │
+ *   │  + outerHTML            │
+ *   │                         │
+ *   │  → sent to server       │
+ *   └─────────────────────────┘
+ */
+// =============================================================================
+// HOOK REGISTRIES
+// =============================================================================
+const snapshotHooks = [];       // Phase 2: Always run (form sync)
+const prepareForSaveHooks = []; // Phase 3a: Save only (strip admin)
+/**
+ * Register a hook that runs on EVERY snapshot (save AND sync).
+ * Use for: syncing form values to the clone.
+ *
+ * @param {Function} callback - Receives the cloned document element
+ */
+export function onSnapshot(callback) {
+  snapshotHooks.push(callback);
+}
+/**
+ * Register a hook that runs ONLY when preparing for save.
+ * Use for: stripping admin elements, cleanup.
+ *
+ * @param {Function} callback - Receives the cloned document element
+ */
+export function onPrepareForSave(callback) {
+  prepareForSaveHooks.push(callback);
+}
+// Backwards compat alias
+export const beforeSave = onPrepareForSave;
+// =============================================================================
+// CAPTURE FUNCTIONS
+// =============================================================================
+/**
+ * PHASE 1-2: Clone the DOM and run snapshot hooks.
+ *
+ * This is the "canonical" state — form values synced, nothing stripped.
+ * Used as the base for both saving and syncing.
+ *
+ * @returns {HTMLElement} Cloned document element with snapshot hooks applied
+ */
+export function captureSnapshot() {
+  const clone = document.documentElement.cloneNode(true);
+  for (const hook of snapshotHooks) {
+    hook(clone);
+  }
+  return clone;
+}
+/**
+ * Prepare an already-captured snapshot for saving.
+ * Mutates the clone — only call once per snapshot.
+ *
+ * @param {HTMLElement} clone - A snapshot from captureSnapshot()
+ * @returns {string} Full HTML string ready for server
+ */
+function prepareCloneForSave(clone) {
+  // Run inline [onbeforesave] handlers
+  for (const el of clone.querySelectorAll('[onbeforesave]')) {
+    new Function(el.getAttribute('onbeforesave')).call(el);
+  }
+  // Remove elements that shouldn't be saved
+  for (const el of clone.querySelectorAll('[save-ignore]')) {
+    el.remove();
+  }
+  // Run registered prepare hooks
+  for (const hook of prepareForSaveHooks) {
+    hook(clone);
+  }
+  return "<!DOCTYPE html>" + clone.outerHTML;
+}
+/**
+ * PHASE 1-4: Full pipeline for saving to server.
+ *
+ * Captures snapshot, emits for live-sync, then prepares for save.
+ * This is the main entry point for the save process.
+ *
+ * @param {Object} options
+ * @param {boolean} options.emitForSync - Whether to emit snapshot-ready event (default: true)
+ * @returns {string} Full HTML string ready for server
+ */
+export function captureForSave({ emitForSync = true } = {}) {
+  const clone = captureSnapshot();
+  // Emit for live-sync before stripping admin elements
+  if (emitForSync) {
+    const bodyForSync = clone.querySelector('body').innerHTML;
+    document.dispatchEvent(new CustomEvent('hyperclay:snapshot-ready', {
+      detail: { body: bodyForSync }
+    }));
+  }
+  return prepareCloneForSave(clone);
+}
+/**
+ * PHASE 1-2 (body only): For live-sync between admin users.
+ *
+ * Includes admin elements — no stripping.
+ * Note: Prefer listening to 'hyperclay:snapshot-ready' event instead,
+ * which reuses the save's clone.
+ *
+ * @returns {string} Body innerHTML with form values synced
+ */
+export function captureBodyForSync() {
+  const clone = captureSnapshot();
+  return clone.querySelector('body').innerHTML;
+}
+/**
+ * Get page contents for change detection.
+ * Does NOT emit snapshot-ready event (safe for comparison).
+ *
+ * For CodeMirror pages, returns editor content directly.
+ * For normal pages, returns full HTML via snapshot pipeline.
+ */
+export function getPageContents() {
+  if (isCodeMirrorPage()) {
+    return getCodeMirrorContents();
+  }
+  return captureForSave({ emitForSync: false });
+}
+// =============================================================================
+// CODEMIRROR SUPPORT
+// =============================================================================
+/**
+ * Check if this is a CodeMirror editor page.
+ * CodeMirror pages bypass the normal snapshot pipeline.
+ */
+export function isCodeMirrorPage() {
+  return !!document.querySelector('.CodeMirror')?.CodeMirror;
+}
+/**
+ * Get CodeMirror editor contents.
+ * @returns {string} Editor contents
+ */
+export function getCodeMirrorContents() {
+  return document.querySelector('.CodeMirror').CodeMirror.getValue();
+}
+// =============================================================================
+// WINDOW EXPORTS
+// =============================================================================
+if (!window.__hyperclayNoAutoExport) {
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.captureSnapshot = captureSnapshot;
+  window.hyperclay.captureForSave = captureForSave;
+  window.hyperclay.captureBodyForSync = captureBodyForSync;
+  window.hyperclay.onSnapshot = onSnapshot;
+  window.hyperclay.onPrepareForSave = onPrepareForSave;
+  window.hyperclay.beforeSave = beforeSave;
+  window.hyperclay.getPageContents = getPageContents;
+  window.h = window.hyperclay;
+}

package/src/core/unsavedWarning.js ADDED Viewed

@@ -0,0 +1,26 @@
+/**
+ * Unsaved Warning Module
+ *
+ * Warns users before leaving the page if there are unsaved changes.
+ * Self-contained: compares current page content to last saved content on beforeunload.
+ *
+ * Works independently of autosave - no mutation observer needed during editing,
+ * just a single comparison when the user tries to leave.
+ *
+ * Requires the 'save-system' module (automatically included as dependency).
+ */
+import { isOwner, isEditMode } from "./isAdminOfCurrentResource.js";
+import { getPageContents, getLastSavedContents } from "./savePage.js";
+window.addEventListener('beforeunload', (event) => {
+  if (!isOwner || !isEditMode) return;
+  const currentContents = getPageContents();
+  const lastSaved = getLastSavedContents();
+  if (currentContents !== lastSaved) {
+    event.preventDefault();
+    event.returnValue = '';
+  }
+});

package/{custom-attributes → src/custom-attributes}/ajaxElements.js RENAMED Viewed

@@ -38,16 +38,9 @@ function submitAjax(elem) {
     }
     method = (method || 'POST').toUpperCase();
-    // Get data - for buttons, only use form data if button is inside a form
-    let data = {};
-    if (isButton && parentForm) {
-      // Button inside form: use form data
-      data = getDataFromForm(parentForm);
-    } else if (!isButton) {
-      // It's a form element itself
-      data = getDataFromForm(elem);
-    }
-    // For standalone buttons with no form, data remains empty object
+    // Get data - from parent form if button is inside one, otherwise from element itself
+    const dataSource = (isButton && parentForm) ? parentForm : elem;
+    const data = getDataFromForm(dataSource);
     fetch(url, {
       method: method,

package/{custom-attributes → src/custom-attributes}/domHelpers.js RENAMED Viewed

@@ -24,22 +24,35 @@ function init () {
     }
   });
-  // elem.val.project returns the value of the nearest "project" attribute
-  // elem.val.project = "hello world" sets the value of the nearest "project" attribute
+  // elem.val.project returns the value of the nearest element with "project" attribute
+  // elem.val.project = "hello world" sets the value of the nearest element with "project" attribute
+  // For form elements (input/select/textarea), uses the value property; otherwise uses the attribute
   Object.defineProperty(HTMLElement.prototype, 'val', {
     configurable: true,
     get: function() {
       let element = this;
+      const isFormElement = (elem) =>
+        elem.tagName === 'INPUT' || elem.tagName === 'SELECT' || elem.tagName === 'TEXTAREA';
       const handler = {
         get(target, prop) {
-          return nearest(element, `[${prop}], .${prop}`, elem => elem.getAttribute(prop));
+          return nearest(element, `[${prop}], .${prop}`, elem => {
+            if (isFormElement(elem)) {
+              return elem.value;
+            }
+            return elem.getAttribute(prop);
+          });
         },
         set(target, prop, value) {
           const foundElem = nearest(element, `[${prop}], .${prop}`);
           if (foundElem) {
-            foundElem.setAttribute(prop, value);
+            if (isFormElement(foundElem)) {
+              foundElem.value = value;
+            } else {
+              foundElem.setAttribute(prop, value);
+            }
           }
           return true;

package/{custom-attributes → src/custom-attributes}/events.js RENAMED Viewed

@@ -1,12 +1,14 @@
 // Events module - combines all event attribute handlers
 import { init as initOnclickaway } from './onclickaway.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();
   initOnclone();
+  initOnmutation();
   initOnpagemutation();
   initOnrender();
 }

package/{custom-attributes → src/custom-attributes}/onaftersave.js RENAMED Viewed

@@ -1,16 +1,16 @@
 /**
  * [onaftersave] Custom Attribute
  *
- * Runs inline JavaScript when save status changes.
- * Pairs with the existing [onbeforesave] attribute.
+ * Runs inline JavaScript after a successful save.
+ * Only fires on 'hyperclay:save-saved' events (not on error/offline).
  *
  * Usage:
  *   <span onaftersave="this.innerText = event.detail.msg"></span>
- *   <div onaftersave="console.log('Status:', event.detail.status)"></div>
+ *   <link href="styles.css" onaftersave="cacheBust(this)">
  *
  * The event.detail object contains:
- *   - status: 'saving' | 'saved' | 'offline' | 'error'
- *   - msg: string (e.g., 'Saved' or error message)
+ *   - status: 'saved'
+ *   - msg: string (e.g., 'Saved')
  *   - timestamp: number (Date.now())
  */
@@ -30,10 +30,7 @@ function broadcast(e) {
 }
 function init() {
-  document.addEventListener('hyperclay:save-saving', broadcast);
   document.addEventListener('hyperclay:save-saved', broadcast);
-  document.addEventListener('hyperclay:save-offline', broadcast);
-  document.addEventListener('hyperclay:save-error', broadcast);
 }
 init();

package/src/custom-attributes/onmutation.js ADDED Viewed

@@ -0,0 +1,90 @@
+/*
+   [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 "../utilities/mutation.js";
+const observers = new WeakMap();
+function setupMutationObserver(element) {
+  if (observers.has(element)) return;
+  const executeMutation = async () => {
+    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);
+    }
+  };
+  const observer = new MutationObserver(() => {
+    executeMutation();
+  });
+  observer.observe(element, {
+    childList: true,
+    subtree: true,
+    characterData: true,
+    attributes: true
+  });
+  observers.set(element, observer);
+}
+function teardownMutationObserver(element) {
+  const observer = observers.get(element);
+  if (observer) {
+    observer.disconnect();
+    observers.delete(element);
+  }
+}
+function init() {
+  // Set up existing elements
+  document.querySelectorAll('[onmutation]').forEach(setupMutationObserver);
+  // Watch for dynamically added elements with onmutation
+  Mutation.onAddElement({
+    selectorFilter: '[onmutation]',
+    debounce: 200
+  }, (changes) => {
+    changes.forEach(({ element }) => {
+      setupMutationObserver(element);
+    });
+  });
+  // Clean up when elements are removed
+  Mutation.onRemoveElement({
+    selectorFilter: '[onmutation]',
+    debounce: 200
+  }, (changes) => {
+    changes.forEach(({ element }) => {
+      teardownMutationObserver(element);
+    });
+  });
+  // Watch for attribute removal
+  Mutation.onAttribute({
+    selectorFilter: '[onmutation]',
+    debounce: 200
+  }, (changes) => {
+    changes.forEach(({ element, attribute, newValue }) => {
+      if (attribute === 'onmutation' && newValue === null) {
+        teardownMutationObserver(element);
+      }
+    });
+  });
+}
+export { init };
+export default init;

package/src/custom-attributes/onpagemutation.js ADDED Viewed

@@ -0,0 +1,32 @@
+/*
+   [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 "../utilities/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);
+    }
+  };
+  Mutation.onAnyChange({
+    debounce: 200,
+    omitChangeDetails: true
+  }, () => {
+    document.querySelectorAll('[onglobalmutation], [onpagemutation]').forEach(executeGlobalMutation);
+  });
+}
+export { init };
+export default init;

package/{custom-attributes → src/custom-attributes}/sortable.js RENAMED Viewed

@@ -5,6 +5,8 @@
    How to use:
    - add `sortable` attribute to an element to make children sortable
    - e.g. <div sortable></div>
+   - add `onsorting` attribute to execute code during drag
+   - e.g. <ul sortable onsorting="console.log('Dragging!')"></ul>
    - add `onsorted` attribute to execute code when items are sorted
    - e.g. <ul sortable onsorted="console.log('Items reordered!')"></ul>
@@ -39,7 +41,20 @@ function makeSortable(sortableElem, Sortable) {
     options.handle = '[sortable-handle]';
   }
-  // Add onsorted callback if attribute exists
+  // Add onsorting callback if attribute exists (fires during drag)
+  const onsortingCode = sortableElem.getAttribute('onsorting');
+  if (onsortingCode) {
+    options.onMove = function(evt) {
+      try {
+        const asyncFn = new Function(`return (async function(evt) { ${onsortingCode} })`)();
+        asyncFn.call(sortableElem, evt);
+      } catch (error) {
+        console.error('Error in onsorting execution:', error);
+      }
+    };
+  }
+  // Add onsorted callback if attribute exists (fires after drop)
   const onsortedCode = sortableElem.getAttribute('onsorted');
   if (onsortedCode) {
     options.onEnd = function(evt) {

package/{dom-utilities → src/dom-utilities}/All.js RENAMED Viewed

@@ -336,6 +336,28 @@ const defaultPlugins = {
       });
       return this;
+    },
+    pluck(attr) {
+      return this.map(el => el.getAttribute(attr));
+    },
+    unique() {
+      return [...new Set(this)];
+    },
+    sortBy(fn) {
+      if (typeof fn === 'string') {
+        const attr = fn;
+        fn = el => el.getAttribute(attr);
+      }
+      return [...this].sort((a, b) => {
+        const aVal = fn(a);
+        const bVal = fn(b);
+        if (aVal < bVal) return -1;
+        if (aVal > bVal) return 1;
+        return 0;
+      });
     }
   }
 };

package/src/dom-utilities/insertStyleTag.js ADDED Viewed

@@ -0,0 +1,61 @@
+/**
+ * Insert styles into the document (inline CSS or external stylesheet).
+ *
+ * With a persistent DOM (i.e. hyperclay), we need a way to update styles.
+ * This function always inserts the new styles first, then removes any
+ * duplicates. This ensures:
+ *   - No flickering: new styles are applied before old ones are removed
+ *   - Always upgrades: we default to the new styles/approach
+ */
+function insertStyles(nameOrHref, css) {
+  if (css !== undefined) {
+    // Inline style: insertStyles('my-styles', '.foo { ... }')
+    const name = nameOrHref;
+    const oldStyles = document.querySelectorAll(`style[data-name="${name}"]`);
+    const style = document.createElement('style');
+    style.dataset.name = name;
+    style.textContent = css;
+    document.head.appendChild(style);
+    oldStyles.forEach(el => el.remove());
+    return style;
+  }
+  // External stylesheet: insertStyles('/path/to/file.css')
+  const href = nameOrHref;
+  let identifier;
+  try {
+    const url = new URL(href, window.location.href);
+    identifier = url.pathname.split('/').pop();
+  } catch (e) {
+    identifier = href;
+  }
+  const oldLinks = document.querySelectorAll(
+    `link[href="${href}"], link[href*="${identifier}"]`
+  );
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = href;
+  document.head.appendChild(link);
+  oldLinks.forEach(el => el.remove());
+  return link;
+}
+// Auto-export to window unless suppressed by loader
+if (!window.__hyperclayNoAutoExport) {
+  window.insertStyles = insertStyles;
+  window.insertStyleTag = insertStyles; // backwards-compat alias
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.insertStyles = insertStyles;
+  window.hyperclay.insertStyleTag = insertStyles; // backwards-compat alias
+  window.h = window.hyperclay;
+}
+export { insertStyles };
+export { insertStyles as insertStyleTag };  // backwards-compat alias
+export default insertStyles;