hyperclayjs 1.14.0 → 1.15.0

package/README.md

@@ -60,10 +60,10 @@ import 'hyperclayjs/presets/standard.js';
 | autosave | 0.9KB | Auto-save on DOM changes |
 | edit-mode | 1.8KB | Toggle edit mode on hyperclay on/off |
 | edit-mode-helpers | 7.5KB | Admin-only functionality: [edit-mode-input], [edit-mode-resource], [edit-mode-onclick] |
-| option-visibility | 5.3KB | Dynamic show/hide based on ancestor state with option:attribute="value" |
+| option-visibility | 7.8KB | Dynamic show/hide based on ancestor state with option:attribute="value" |
 | persist | 2.4KB | Persist input/select/textarea values to the DOM with [persist] attribute |
 | save-core | 6.8KB | Basic save function only - hyperclay.savePage() |
-| save-system | 7.1KB | CMD+S, [trigger-save] button, savestatus attribute |
+| save-system | 9.6KB | CMD+S, [trigger-save] button, savestatus attribute |
 | save-toast | 0.9KB | Toast notifications for save events |
 | snapshot | 7.5KB | Source of truth for page state - captures DOM snapshots for save and sync |
 | tailwind-inject | 0.4KB | Injects tailwind CSS link with cache-bust on save |
@@ -106,7 +106,7 @@ import 'hyperclayjs/presets/standard.js';
 | 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 | 2.4KB | Dynamic stylesheet injection |
+| style-injection | 4KB | Dynamic stylesheet injection |
 
 ### String Utilities (String manipulation helpers)
 
@@ -132,17 +132,17 @@ import 'hyperclayjs/presets/standard.js';
 
 ## Presets
 
-### Minimal (~38.1KB)
+### Minimal (~40.6KB)
 Essential features for basic editing
 
 **Modules:** `save-core`, `snapshot`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`, `view-mode-excludes-edit-modules`
 
-### Standard (~57.4KB)
+### Standard (~62.4KB)
 Standard feature set for most use cases
 
 **Modules:** `save-core`, `snapshot`, `save-system`, `unsaved-warning`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`, `save-toast`, `export-to-window`, `view-mode-excludes-edit-modules`
 
-### Everything (~178KB)
+### Everything (~184.6KB)
 All available features
 
 Includes all available modules across all categories.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperclayjs",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Modular JavaScript library for building interactive HTML applications with Hyperclay",
   "type": "module",
   "main": "src/hyperclay.js",

package/src/core/optionVisibility.js

@@ -1,18 +1,26 @@
 /**
  * Option Visibility (CSS Layers Implementation)
  *
- * Shows/hides elements based on `option:` attributes and ancestor matches.
+ * Shows/hides elements based on `option:` and `option-not:` attributes.
  *
- * Usage:
+ * SYNTAX:
+ *   option:name="value"       - Show when ancestor has name="value"
+ *   option:name="a|b|c"       - Show when ancestor has name="a" OR "b" OR "c"
+ *   option:name=""            - Show when ancestor has name="" (empty value)
+ *   option:name="|saved"      - Show when ancestor has name="" OR name="saved"
+ *   option-not:name="value"   - Show when ancestor has name attr but ≠ "value"
+ *   option-not:name="a|b"     - Show when ancestor has name attr but ≠ "a" AND ≠ "b"
+ *
+ * EXAMPLES:
  *   <div editmode="true">
- *     <button option:editmode="true">Visible</button>
+ *     <button option:editmode="true">Visible in edit mode</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"`.
- *
- * ---
+ *   <div savestatus="error">
+ *     <span option:savestatus="saved|error">Visible (matches error)</span>
+ *     <span option-not:savestatus="saving">Visible (error ≠ saving)</span>
+ *   </div>
  *
  * HOW IT WORKS:
  * 1. Uses `display: none !important` to forcefully hide elements
@@ -21,13 +29,14 @@
  * 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+).
+ * Requires `@layer`, `revert-layer`, and `:not()` selector lists (~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)
+ * - Con: Pipe character `|` cannot be used as a literal value (reserved as OR delimiter)
  */
 
 import Mutation from "../utilities/mutation.js";
@@ -35,6 +44,34 @@ import insertStyles from "../dom-utilities/insertStyleTag.js";
 
 const STYLE_NAME = 'option-visibility';
 
+/**
+ * Parse an option:/option-not: attribute into a pattern object.
+ * Pure function for easy testing.
+ *
+ * @param {string} attrName - Attribute name (e.g., 'option:editmode', 'option-not:status')
+ * @param {string} attrValue - Attribute value (e.g., 'true', 'a|b|c')
+ * @returns {Object|null} Pattern object or null if not a valid option attribute
+ */
+export function parseOptionAttribute(attrName, attrValue) {
+  let negated = false;
+  let name;
+
+  if (attrName.startsWith('option-not:')) {
+    negated = true;
+    name = attrName.slice(11);
+  } else if (attrName.startsWith('option:')) {
+    name = attrName.slice(7);
+  } else {
+    return null;
+  }
+
+  const rawValue = attrValue;
+  // Split by pipe, keep empty strings (they match empty attribute values)
+  const values = rawValue.split('|');
+
+  return { name, rawValue, values, negated };
+}
+
 const optionVisibility = {
   debug: false,
   _started: false,
@@ -54,14 +91,15 @@ const optionVisibility = {
   },
 
   /**
-   * Find all unique option:name="value" patterns using XPath (faster than regex on HTML)
+   * Find all unique option:/option-not: patterns using XPath
+   * Returns array of { name, rawValue, values, negated }
    */
   findOptionAttributes() {
     const patterns = new Map();
 
     try {
       const snapshot = document.evaluate(
-        '//*[@*[starts-with(name(), "option:")]]',
+        '//*[@*[starts-with(name(), "option:") or starts-with(name(), "option-not:")]]',
         document.documentElement,
         null,
         XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE,
@@ -71,13 +109,12 @@ const optionVisibility = {
       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 });
-            }
+          const pattern = parseOptionAttribute(attr.name, attr.value);
+          if (!pattern) continue;
+
+          const key = `${pattern.negated ? '!' : ''}${pattern.name}=${pattern.rawValue}`;
+          if (!patterns.has(key)) {
+            patterns.set(key, pattern);
           }
         }
       }
@@ -91,16 +128,34 @@ const optionVisibility = {
   /**
    * Generate CSS rules wrapped in @layer
    */
-  generateCSS(attributes) {
-    if (!attributes.length) return '';
+  generateCSS(patterns) {
+    if (!patterns.length) return '';
 
-    const rules = attributes.map(({ name, value }) => {
+    const rules = patterns.map(({ name, rawValue, values, negated }) => {
       const safeName = CSS.escape(name);
-      const safeValue = CSS.escape(value);
+      const safeRawValue = CSS.escape(rawValue);
+      const prefix = negated ? 'option-not' : 'option';
+      const attrSelector = `[${prefix}\\:${safeName}="${safeRawValue}"]`;
+
+      // Hide rule (same for both types)
+      const hideRule = `${attrSelector}{display:none!important}`;
+
+      // Show rule depends on type
+      let showRule;
+      if (negated) {
+        // option-not: show when ancestor has attr but NOT any of the values
+        // Uses :not(sel1, sel2) selector list syntax
+        const notList = values.map(v => `[${safeName}="${CSS.escape(v)}"]`).join(',');
+        showRule = `[${safeName}]:not(${notList}) ${attrSelector}{display:revert-layer!important}`;
+      } else {
+        // option: show when ancestor has ANY of the values
+        const showSelectors = values.map(v =>
+          `[${safeName}="${CSS.escape(v)}"] ${attrSelector}`
+        ).join(',');
+        showRule = `${showSelectors}{display:revert-layer!important}`;
+      }
 
-      // 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}`;
+      return hideRule + showRule;
     }).join('');
 
     return `@layer ${STYLE_NAME}{${rules}}`;
@@ -118,7 +173,11 @@ const optionVisibility = {
     try {
       const attributes = this.findOptionAttributes();
       const css = this.generateCSS(attributes);
-      insertStyles(STYLE_NAME, css);
+      // mutations-ignore: This style tag is regenerated on load. Without this,
+      // the mutation observer would detect it as a change, delaying the settled signal.
+      insertStyles(STYLE_NAME, css, (style) => {
+        style.setAttribute('mutations-ignore', '');
+      });
       this.log(`Generated ${attributes.length} rules`);
     } catch (error) {
       console.error('[OptionVisibility:Layer] Error generating rules:', error);
@@ -142,12 +201,14 @@ const optionVisibility = {
 
     this.update();
 
-    // selectorFilter only triggers on option:* attribute changes (new patterns).
+    // selectorFilter only triggers on option:/option-not: 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:')),
+      selectorFilter: el => [...el.attributes].some(attr =>
+        attr.name.startsWith('option:') || attr.name.startsWith('option-not:')
+      ),
       omitChangeDetails: true
     }, () => this.update());
 

package/src/core/savePage.js

@@ -11,6 +11,7 @@
  */
 
 import throttle from "../utilities/throttle.js";
+import Mutation from "../utilities/mutation.js";
 import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
 import {
   savePage as savePageCore,
@@ -19,6 +20,11 @@ import {
   beforeSave
 } from "./savePageCore.js";
 
+// Reset savestatus to 'saved' in snapshots (each module cleans up its own attrs)
+beforeSave(clone => {
+  clone.setAttribute('savestatus', 'saved');
+});
+
 // ============================================
 // SAVE STATE MANAGEMENT
 // ============================================
@@ -94,17 +100,6 @@ export function setUnsavedChanges(val) { unsavedChanges = val; }
 export function getLastSavedContents() { return lastSavedContents; }
 export function setLastSavedContents(val) { lastSavedContents = val; }
 
-// Initialize lastSavedContents on page load to match what's on disk
-// This prevents unnecessary save attempts when content hasn't changed
-document.addEventListener('DOMContentLoaded', () => {
-  if (isEditMode) {
-    // Capture initial state immediately for comparison
-    lastSavedContents = getPageContents();
-    // Set initial save status to 'saved'
-    document.documentElement.setAttribute('savestatus', 'saved');
-  }
-});
-
 /**
  * Save the current page with change detection and state management
  *
@@ -185,14 +180,87 @@ const throttledSave = throttle(savePage, 1200);
 // Baseline for autosave comparison
 let baselineContents = '';
 
-// Capture baseline after setup mutations settle
-document.addEventListener('DOMContentLoaded', () => {
-  if (isEditMode) {
-    setTimeout(() => {
-      baselineContents = getPageContents();
-    }, 1500);
-  }
-});
+// ============================================
+// BASELINE CAPTURE (Settled Signal)
+// ============================================
+//
+// WHY SETTLED SIGNAL:
+// Modules run on load and mutate the DOM (add styles, modify attributes).
+// A fixed delay (e.g., 1500ms) is arbitrary and either too short (misses slow
+// mutations) or too long (delays baseline). Instead, we wait for mutations to
+// stop, meaning all modules have finished their setup work.
+//
+// WHY IMMEDIATE + CONDITIONAL UPDATE:
+// We set baseline immediately as a safety net. If the user edits or saves
+// before settle completes, we don't overwrite their work. The settled snapshot
+// only replaces baseline if nothing changed (lastSavedContents === immediateContents).
+
+const SETTLE_MS = 500;        // Wait for no mutations for this long
+const MAX_SETTLE_MS = 3000;   // Max time to wait before forcing capture
+
+function initBaselineCapture() {
+  if (!isEditMode) return;
+
+  let userEdited = false;
+  let settled = false;
+  let unsubscribeMutation = null;
+
+  // Take immediate snapshot and set as baseline right away
+  // This ensures saves during settle window work correctly
+  const immediateContents = getPageContents();
+  lastSavedContents = immediateContents;
+  baselineContents = immediateContents;
+
+  // Track user edits to avoid overwriting real changes
+  const userEditEvents = ['input', 'change', 'paste'];
+  const markUserEdited = (e) => {
+    const target = e.target;
+    const isEditable = target.isContentEditable ||
+                       target.tagName === 'INPUT' ||
+                       target.tagName === 'TEXTAREA' ||
+                       target.tagName === 'SELECT';
+    if (isEditable) userEdited = true;
+  };
+  userEditEvents.forEach(evt => document.addEventListener(evt, markUserEdited, true));
+
+  // Called when mutations settle OR max timeout reached
+  const captureBaseline = () => {
+    if (settled) return;
+    settled = true;
+
+    // Cleanup listeners
+    if (unsubscribeMutation) unsubscribeMutation();
+    userEditEvents.forEach(evt => document.removeEventListener(evt, markUserEdited, true));
+
+    // Only update if no user edits AND no saves occurred during settle
+    // (if a save happened, lastSavedContents would differ from immediateContents)
+    if (!userEdited && lastSavedContents === immediateContents) {
+      const contents = getPageContents();
+      lastSavedContents = contents;
+      baselineContents = contents;
+    }
+
+    document.documentElement.setAttribute('savestatus', 'saved');
+  };
+
+  // Start settle observer - fires when no mutations for SETTLE_MS
+  unsubscribeMutation = Mutation.onAnyChange(
+    { debounce: SETTLE_MS, omitChangeDetails: true },
+    captureBaseline
+  );
+
+  // Max timeout fallback
+  setTimeout(() => {
+    if (!settled) captureBaseline();
+  }, MAX_SETTLE_MS);
+}
+
+// Run when DOM is ready
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initBaselineCapture);
+} else {
+  initBaselineCapture();
+}
 
 /**
  * Save the page with throttling, for use with auto-save

package/src/dom-utilities/insertStyleTag.js

@@ -2,10 +2,20 @@
  * 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
+ * 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 (hyperclay), 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
@@ -18,15 +28,33 @@ function insertStyles(nameOrHref, cssOrCallback, callback) {
     // Inline style: insertStyles('my-styles', '.foo { ... }', optionalCallback)
     const name = nameOrHref;
     const css = cssOrCallback;
-    const oldStyles = document.querySelectorAll(`style[data-name="${name}"]`);
+    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;
+    }
 
-    const style = document.createElement('style');
-    style.dataset.name = name;
-    style.textContent = css;
-    if (callback) callback(style);
-    document.head.appendChild(style);
+    // 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);
+    }
 
-    oldStyles.forEach(el => el.remove());
     return style;
   }
 
@@ -34,25 +62,35 @@ function insertStyles(nameOrHref, cssOrCallback, callback) {
   const href = nameOrHref;
   const cb = typeof cssOrCallback === 'function' ? cssOrCallback : undefined;
 
-  let identifier;
-  try {
-    const url = new URL(href, window.location.href);
-    identifier = url.pathname.split('/').pop();
-  } catch (e) {
-    identifier = href;
-  }
+  // Normalize href to full URL for comparison
+  const normalizedHref = new URL(href, window.location.href).href;
+
+  // Find all links with matching normalized path
+  const existingLinks = [...document.querySelectorAll('link[rel="stylesheet"]')]
+    .filter(el => {
+      try {
+        return new URL(el.getAttribute('href'), window.location.href).href === normalizedHref;
+      } catch {
+        return false;
+      }
+    });
 
-  const oldLinks = document.querySelectorAll(
-    `link[href="${href}"], link[href*="${identifier}"]`
-  );
+  // 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);
 
-  oldLinks.forEach(el => el.remove());
   return link;
 }
 

package/src/hyperclay.js

@@ -1,5 +1,5 @@
 /**
- * HyperclayJS v1.14.0 - Minimal Browser-Native Loader
+ * HyperclayJS v1.15.0 - Minimal Browser-Native Loader
  *
  * Modules auto-init when imported (no separate init call needed).
  * Include `export-to-window` feature to export to window.hyperclay.