hyperclayjs 1.6.0 → 1.8.0

package/README.md

@@ -21,7 +21,7 @@ Destructure directly from the import:
 
 ```html
 <script type="module">
-  const { toast, savePage } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/hyperclay.js?preset=standard');
+  const { toast, savePage } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/src/hyperclay.js?preset=standard');
   toast('Hello!');
 </script>
 ```
@@ -30,7 +30,7 @@ Or with custom features:
 
 ```html
 <script type="module">
-  const { toast, ask } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/hyperclay.js?features=toast,dialogs');
+  const { toast, ask } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/src/hyperclay.js?features=toast,dialogs');
 </script>
 ```
 
@@ -59,10 +59,10 @@ import 'hyperclayjs/presets/standard.js';
 |--------|------|-------------|
 | autosave | 1.1KB | Auto-save on DOM changes, unsaved changes warning |
 | edit-mode | 1.8KB | Toggle edit mode on hyperclay on/off |
-| edit-mode-helpers | 5.4KB | Admin-only functionality: [edit-mode-input], [edit-mode-resource], [edit-mode-onclick] |
-| option-visibility | 4.7KB | Dynamic show/hide based on ancestor state with option:attribute="value" |
+| edit-mode-helpers | 7.5KB | Admin-only functionality: [edit-mode-input], [edit-mode-resource], [edit-mode-onclick] |
+| option-visibility | 5.9KB | Dynamic show/hide based on ancestor state with option:attribute="value" |
 | persist | 2.5KB | Persist input/select/textarea values to the DOM with [persist] attribute |
-| save-core | 6.3KB | Basic save function only - hyperclay.savePage() |
+| save-core | 6.5KB | Basic save function only - hyperclay.savePage() |
 | save-system | 7.1KB | Manual save: keyboard shortcut (CMD+S), save button, change tracking |
 | save-toast | 0.9KB | Toast notifications for save events |
 
@@ -71,18 +71,18 @@ import 'hyperclayjs/presets/standard.js';
 | Module | Size | Description |
 |--------|------|-------------|
 | ajax-elements | 2.8KB | [ajax-form], [ajax-button] for async form submissions |
-| dom-helpers | 5.7KB | el.nearest, el.val, el.text, el.exec, el.cycle |
-| event-attrs | 3.6KB | [onclickaway], [onclone], [onpagemutation], [onrender] |
+| dom-helpers | 6.2KB | el.nearest, el.val, el.text, el.exec, el.cycle |
+| event-attrs | 4.1KB | [onclickaway], [onclone], [onpagemutation], [onrender] |
 | input-helpers | 1.2KB | [prevent-enter], [autosize] for textareas |
 | onaftersave | 1.2KB | [onaftersave] attribute - run JS when save status changes |
-| sortable | 2.8KB | Drag-drop sorting with [sortable], lazy-loads ~118KB Sortable.js in edit mode |
+| sortable | 3.4KB | Drag-drop sorting with [sortable], lazy-loads ~118KB Sortable.js in edit mode |
 
 ### UI Components (User interface elements)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| dialogs | 8.4KB | ask(), consent(), tell(), snippet() dialog functions |
-| the-modal | 19.8KB | Full modal window creation system - window.theModal |
+| dialogs | 7.7KB | ask(), consent(), tell(), snippet() dialog functions |
+| the-modal | 21.8KB | Full modal window creation system - window.theModal |
 | toast | 7.7KB | Success/error message notifications, toast(msg, msgType) |
 
 ### Utilities (Core utilities (often auto-included))
@@ -99,7 +99,7 @@ import 'hyperclayjs/presets/standard.js';
 
 | Module | Size | Description |
 |--------|------|-------------|
-| all-js | 14KB | Full DOM manipulation library |
+| all-js | 14.4KB | Full DOM manipulation library |
 | dom-ready | 0.4KB | DOM ready callback |
 | form-data | 2KB | Extract form data as an object |
 | style-injection | 1.1KB | Dynamic stylesheet injection |
@@ -127,17 +127,17 @@ import 'hyperclayjs/presets/standard.js';
 
 ## Presets
 
-### Minimal (~27.8KB)
+### Minimal (~30.1KB)
 Essential features for basic editing
 
 **Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Standard (~44.3KB)
+### Standard (~48.8KB)
 Standard feature set for most use cases
 
 **Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Everything (~149KB)
+### Everything (~155.8KB)
 All available features
 
 Includes all available modules across all categories.

package/package.json

@@ -1,39 +1,31 @@
 {
   "name": "hyperclayjs",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Modular JavaScript library for building interactive HTML applications with Hyperclay",
   "type": "module",
-  "main": "hyperclay.js",
-  "module": "hyperclay.js",
+  "main": "src/hyperclay.js",
+  "module": "src/hyperclay.js",
   "exports": {
     ".": {
-      "import": "./hyperclay.js",
-      "default": "./hyperclay.js"
+      "import": "./src/hyperclay.js",
+      "default": "./src/hyperclay.js"
     },
-    "./core/*": "./core/*.js",
-    "./custom-attributes/*": "./custom-attributes/*.js",
-    "./ui/*": "./ui/*.js",
-    "./utilities/*": "./utilities/*.js",
-    "./dom-utilities/*": "./dom-utilities/*.js",
-    "./string-utilities/*": "./string-utilities/*.js",
-    "./communication/*": "./communication/*.js",
-    "./vendor/*": "./vendor/*.js"
+    "./core/*": "./src/core/*.js",
+    "./custom-attributes/*": "./src/custom-attributes/*.js",
+    "./ui/*": "./src/ui/*.js",
+    "./utilities/*": "./src/utilities/*.js",
+    "./dom-utilities/*": "./src/dom-utilities/*.js",
+    "./string-utilities/*": "./src/string-utilities/*.js",
+    "./communication/*": "./src/communication/*.js",
+    "./vendor/*": "./src/vendor/*.js"
   },
   "files": [
-    "core",
-    "custom-attributes",
-    "ui",
-    "utilities",
-    "dom-utilities",
-    "string-utilities",
-    "communication",
-    "vendor",
-    "hyperclay.js",
-    "module-dependency-graph.json"
+    "src"
   ],
   "scripts": {
-    "dev": "npm run build && http-server -p 3535 -c-1 -o /index.html",
+    "dev": "npm run build && npm run build:website && http-server website -p 3535 -c-1 -o /index.html",
     "build": "npm run generate:deps && npm run build:loader && npm run build:readme && npm run build:load-jsdelivr && npm run build:index-url",
+    "build:website": "node scripts/build-website.js",
     "generate:deps": "node build/generate-dependency-graph.js",
     "build:loader": "node build/build-loader.js",
     "build:readme": "node build/generate-readme.js",
@@ -44,7 +36,7 @@
     "format": "prettier --write .",
     "release": "./scripts/release.sh",
     "prepublishOnly": "npm run build && npm test",
-    "postpublish": "test -n \"$SKIP_POSTPUBLISH\" || open http://127.0.0.1:3535/build/load-jsdelivr.html"
+    "postpublish": "test -n \"$SKIP_POSTPUBLISH\" || open http://127.0.0.1:3535/load-jsdelivr.html"
   },
   "repository": {
     "type": "git",

package/src/core/adminContenteditable.js

@@ -0,0 +1,51 @@
+import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
+import onDomReady from "../dom-utilities/onDomReady.js";
+import {beforeSave} from "./savePage.js";
+
+export function disableContentEditableBeforeSave () {
+  beforeSave(docElem => {
+    docElem.querySelectorAll('[edit-mode-contenteditable]').forEach(resource => {
+      const originalValue = resource.getAttribute("contenteditable");
+      resource.setAttribute("inert-contenteditable", originalValue);
+      resource.removeAttribute("contenteditable");
+    });
+  });
+}
+
+export function enableContentEditableForAdminOnPageLoad () {
+  if (!isEditMode) return;
+
+  onDomReady(() => {
+    enableContentEditable();
+  });
+}
+
+// Runtime toggle functions
+export function enableContentEditable() {
+  document.querySelectorAll('[edit-mode-contenteditable]').forEach(el => {
+    let val = el.getAttribute("inert-contenteditable");
+    if (!["false", "plaintext-only"].includes(val)) val = "true";
+    el.setAttribute("contenteditable", val);
+    el.removeAttribute("inert-contenteditable");
+  });
+}
+
+export function disableContentEditable() {
+  document.querySelectorAll('[edit-mode-contenteditable]').forEach(el => {
+    const val = el.getAttribute("contenteditable") || "true";
+    el.setAttribute("inert-contenteditable", val);
+    el.removeAttribute("contenteditable");
+  });
+}
+
+// Auto-initialize
+export function init() {
+  disableContentEditableBeforeSave();
+  enableContentEditableForAdminOnPageLoad();
+}
+
+// Export to window
+window.hyperclay = window.hyperclay || {};
+window.hyperclay.enableContentEditable = enableContentEditable;
+window.hyperclay.disableContentEditable = disableContentEditable;
+window.h = window.hyperclay;

package/{core → src/core}/adminInputs.js

@@ -18,13 +18,28 @@ export function enableAdminInputsOnPageLoad() {
   if (!isEditMode) return;
 
   onDomReady(() => {
-    document.querySelectorAll('[edit-mode-input]').forEach(input => {
-      if (supportsReadonly(input)) {
-        input.removeAttribute('readonly');
-      } else {
-        input.removeAttribute('disabled');
-      }
-    });
+    enableAdminInputs();
+  });
+}
+
+// Runtime toggle functions
+export function enableAdminInputs() {
+  document.querySelectorAll('[edit-mode-input]').forEach(input => {
+    if (supportsReadonly(input)) {
+      input.removeAttribute('readonly');
+    } else {
+      input.removeAttribute('disabled');
+    }
+  });
+}
+
+export function disableAdminInputs() {
+  document.querySelectorAll('[edit-mode-input]').forEach(input => {
+    if (supportsReadonly(input)) {
+      input.setAttribute('readonly', '');
+    } else {
+      input.setAttribute('disabled', '');
+    }
   });
 }
 
@@ -55,4 +70,10 @@ function supportsReadonly(element) {
 export function init() {
   disableAdminInputsBeforeSave();
   enableAdminInputsOnPageLoad();
-}
+}
+
+// Export to window
+window.hyperclay = window.hyperclay || {};
+window.hyperclay.enableAdminInputs = enableAdminInputs;
+window.hyperclay.disableAdminInputs = disableAdminInputs;
+window.h = window.hyperclay;

package/src/core/adminOnClick.js

@@ -0,0 +1,54 @@
+import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
+import onDomReady from "../dom-utilities/onDomReady.js";
+import {beforeSave} from "./savePage.js";
+
+export function disableOnClickBeforeSave () {
+  beforeSave(docElem => {
+    docElem.querySelectorAll('[edit-mode-onclick]').forEach(resource => {
+      const originalValue = resource.getAttribute("onclick");
+      resource.setAttribute("inert-onclick", originalValue);
+      resource.removeAttribute("onclick");
+    });
+  });
+}
+
+export function enableOnClickForAdminOnPageLoad () {
+  if (!isEditMode) return;
+
+  onDomReady(() => {
+    enableOnClick();
+  });
+}
+
+// Runtime toggle functions
+export function enableOnClick() {
+  document.querySelectorAll('[edit-mode-onclick]').forEach(el => {
+    const val = el.getAttribute("inert-onclick");
+    if (val) {
+      el.setAttribute("onclick", val);
+      el.removeAttribute("inert-onclick");
+    }
+  });
+}
+
+export function disableOnClick() {
+  document.querySelectorAll('[edit-mode-onclick]').forEach(el => {
+    const val = el.getAttribute("onclick");
+    if (val) {
+      el.setAttribute("inert-onclick", val);
+      el.removeAttribute("onclick");
+    }
+  });
+}
+
+// Auto-initialize
+export function init() {
+  disableOnClickBeforeSave();
+  enableOnClickForAdminOnPageLoad();
+}
+
+// Export to window
+window.hyperclay = window.hyperclay || {};
+window.hyperclay.enableOnClick = enableOnClick;
+window.hyperclay.disableOnClick = disableOnClick;
+window.h = window.hyperclay;

package/{core → src/core}/adminResources.js

@@ -18,11 +18,25 @@ export function enableAdminResourcesOnPageLoad () {
   if (!isEditMode) return;
 
   onDomReady(() => {
-    document.querySelectorAll('[edit-mode-resource]:is(style, link, script)[type^="inert/"]').forEach(resource => {
-      // works for js and css
-      resource.type = resource.type.replace(/inert\//g, '');
+    enableAdminResources();
+  });
+}
+
+// Runtime toggle functions
+export function enableAdminResources() {
+  document.querySelectorAll('[edit-mode-resource]:is(style, link, script)[type^="inert/"]').forEach(resource => {
+    resource.type = resource.type.replace(/inert\//g, '');
+    resource.replaceWith(resource.cloneNode(true));
+  });
+}
+
+export function disableAdminResources() {
+  document.querySelectorAll('[edit-mode-resource]:is(style, link, script)').forEach(resource => {
+    const currentType = resource.getAttribute('type') || 'text/javascript';
+    if (!currentType.startsWith('inert/')) {
+      resource.setAttribute('type', `inert/${currentType}`);
       resource.replaceWith(resource.cloneNode(true));
-    });
+    }
   });
 }
 
@@ -30,4 +44,10 @@ export function enableAdminResourcesOnPageLoad () {
 export function init() {
   disableAdminResourcesBeforeSave();
   enableAdminResourcesOnPageLoad();
-}
+}
+
+// Export to window
+window.hyperclay = window.hyperclay || {};
+window.hyperclay.enableAdminResources = enableAdminResources;
+window.hyperclay.disableAdminResources = disableAdminResources;
+window.h = window.hyperclay;

package/src/core/optionVisibility.js

@@ -0,0 +1,216 @@
+/**
+ * Option Visibility (CSS Layers Implementation)
+ *
+ * Shows/hides elements based on `option:` attributes and ancestor matches.
+ *
+ * Usage:
+ *   <div editmode="true">
+ *     <button option:editmode="true">Visible</button>
+ *     <button option:editmode="false">Hidden</button>
+ *   </div>
+ *
+ * An element with `option:name="value"` is hidden by default.
+ * It becomes visible when ANY ancestor has `name="value"`.
+ *
+ * ---
+ *
+ * HOW IT WORKS:
+ * 1. Uses `display: none !important` to forcefully hide elements
+ * 2. Uses `display: revert-layer !important` to un-hide when ancestor matches
+ *    `revert-layer` tells the browser: "Ignore rules in this layer, fall back to author styles"
+ * 3. This preserves the user's original `display` (flex, grid, block) without us knowing what it is
+ *
+ * BROWSER SUPPORT:
+ * Requires `@layer` and `revert-layer` support (~92% of browsers, 2022+).
+ * Falls back gracefully - elements remain visible if unsupported.
+ *
+ * TRADEOFFS:
+ * - Pro: Pure CSS after generation, zero JS overhead for toggling
+ * - Pro: Simple code, similar to original approach
+ * - Con: Loses to user `!important` rules (layered !important < unlayered !important)
+ */
+
+import Mutation from "../utilities/mutation.js";
+
+const optionVisibility = {
+  debug: false,
+  _started: false,
+  _styleElement: null,
+  _unsubscribe: null,
+
+  LAYER_NAME: 'option-visibility',
+  STYLE_CLASS: 'option-visibility-layer-styles',
+
+  log(...args) {
+    if (this.debug) console.log('[OptionVisibility:Layer]', ...args);
+  },
+
+  /**
+   * Check if browser supports the layer approach
+   */
+  isSupported() {
+    return typeof CSS !== 'undefined'
+      && typeof CSS.supports === 'function'
+      && CSS.supports('display', 'revert-layer');
+  },
+
+  /**
+   * Find all unique option:name="value" patterns using XPath (faster than regex on HTML)
+   */
+  findOptionAttributes() {
+    const patterns = new Map();
+
+    try {
+      const snapshot = document.evaluate(
+        '//*[@*[starts-with(name(), "option:")]]',
+        document.documentElement,
+        null,
+        XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE,
+        null
+      );
+
+      for (let i = 0; i < snapshot.snapshotLength; i++) {
+        const el = snapshot.snapshotItem(i);
+        for (const attr of el.attributes) {
+          if (attr.name.startsWith('option:')) {
+            const name = attr.name.slice(7);
+            const value = attr.value;
+            const key = `${name}=${value}`;
+            if (!patterns.has(key)) {
+              patterns.set(key, { name, value });
+            }
+          }
+        }
+      }
+    } catch (error) {
+      this.log('XPath error, falling back to empty', error);
+    }
+
+    return [...patterns.values()];
+  },
+
+  /**
+   * Generate CSS rules wrapped in @layer
+   */
+  generateCSS(attributes) {
+    if (!attributes.length) return '';
+
+    const rules = attributes.map(({ name, value }) => {
+      const safeName = CSS.escape(name);
+      const safeValue = CSS.escape(value);
+
+      // Hidden by default, visible when ancestor matches
+      // Both rules need !important for consistency within the layer
+      return `[option\\:${safeName}="${safeValue}"]{display:none!important}[${safeName}="${safeValue}"] [option\\:${safeName}="${safeValue}"]{display:revert-layer!important}`;
+    }).join('');
+
+    return `@layer ${this.LAYER_NAME}{${rules}}`;
+  },
+
+  /**
+   * Update the style element with current rules
+   */
+  update() {
+    if (!this.isSupported()) {
+      this.log('Browser lacks revert-layer support, skipping');
+      return;
+    }
+
+    try {
+      const attributes = this.findOptionAttributes();
+      const css = this.generateCSS(attributes);
+
+      // Remove style element if no attributes
+      if (!css) {
+        if (this._styleElement) {
+          this._styleElement.remove();
+          this._styleElement = null;
+          this.log('Removed empty style element');
+        }
+        return;
+      }
+
+      // Skip if unchanged
+      if (this._styleElement?.textContent === css) {
+        this.log('Styles unchanged');
+        return;
+      }
+
+      // Create or update
+      if (!this._styleElement) {
+        this._styleElement = document.createElement('style');
+        this._styleElement.className = this.STYLE_CLASS;
+        document.head.appendChild(this._styleElement);
+      }
+
+      this._styleElement.textContent = css;
+      this.log(`Generated ${attributes.length} rules`);
+
+    } catch (error) {
+      console.error('[OptionVisibility:Layer] Error generating rules:', error);
+    }
+  },
+
+  start() {
+    if (this._started) return;
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', () => this.start(), { once: true });
+      return;
+    }
+
+    this._started = true;
+
+    if (!this.isSupported()) {
+      console.warn('[OptionVisibility:Layer] Browser lacks revert-layer support. Elements will remain visible.');
+      return;
+    }
+
+    this.update();
+
+    // selectorFilter only triggers on option:* attribute changes (new patterns).
+    // Ancestor attribute changes (e.g., editmode="true" -> "false") are handled
+    // automatically by the browser - CSS rules re-evaluate when attributes change.
+    this._unsubscribe = Mutation.onAnyChange({
+      debounce: 200,
+      selectorFilter: el => [...el.attributes].some(attr => attr.name.startsWith('option:')),
+      omitChangeDetails: true
+    }, () => this.update());
+
+    this.log('Started');
+  },
+
+  stop() {
+    if (!this._started) return;
+
+    this._started = false;
+
+    if (this._unsubscribe) {
+      this._unsubscribe();
+      this._unsubscribe = null;
+    }
+
+    if (this._styleElement) {
+      this._styleElement.remove();
+      this._styleElement = null;
+    }
+
+    this.log('Stopped');
+  }
+};
+
+// Auto-export
+if (!window.__hyperclayNoAutoExport) {
+  window.optionVisibility = optionVisibility;
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.optionVisibility = optionVisibility;
+  window.h = window.hyperclay;
+}
+
+export default optionVisibility;
+
+export function init() {
+  optionVisibility.start();
+}
+
+init();

package/{core → src/core}/savePage.js

@@ -111,7 +111,7 @@ document.addEventListener('DOMContentLoaded', () => {
  * @param {Function} callback - Optional callback for custom handling
  */
 export function savePage(callback = () => {}) {
-  if (!isEditMode) {
+  if (!isEditMode && !window.hyperclay?.testMode) {
     return;
   }
 

package/{core → src/core}/savePageCore.js

@@ -73,11 +73,21 @@ export function getPageContents() {
  * });
  */
 export function savePage(callback = () => {}) {
-  if (!isEditMode || saveInProgress) {
+  if (saveInProgress) {
+    return;
+  }
+  if (!isEditMode && !window.hyperclay?.testMode) {
     return;
   }
 
-  const currentContents = getPageContents();
+  let currentContents;
+  try {
+    currentContents = getPageContents();
+  } catch (err) {
+    console.error('savePage: getPageContents failed', err);
+    callback({msg: err.message, msgType: "error"});
+    return;
+  }
   saveInProgress = true;
 
   // Test mode: skip network request, return mock success
@@ -121,7 +131,7 @@ export function savePage(callback = () => {}) {
 
     const msg = err.name === 'AbortError'
       ? 'Server not responding'
-      : (err.message || 'Failed to save');
+      : 'Save failed';
 
     if (typeof callback === 'function') {
       callback({msg, msgType: "error"});

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

@@ -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

@@ -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();
 }