hyperclayjs 1.14.1 → 1.15.0

package/README.md

@@ -60,7 +60,7 @@ 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.5KB | 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 | 9.6KB | CMD+S, [trigger-save] button, savestatus attribute |
@@ -137,12 +137,12 @@ 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 (~60.1KB)
+### 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 (~182.3KB)
+### 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.1",
+  "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}}`;
@@ -146,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/hyperclay.js

@@ -1,5 +1,5 @@
 /**
- * HyperclayJS v1.14.1 - 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.