hyperclayjs 1.4.0 → 1.5.0

package/README.md

@@ -57,13 +57,14 @@ import 'hyperclayjs/presets/standard.js';
 
 | Module | Size | Description |
 |--------|------|-------------|
-| autosave | 1.2KB | Auto-save on DOM changes, unsaved changes warning |
+| 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" |
 | persist | 2.5KB | Persist input/select/textarea values to the DOM with [persist] attribute |
-| save-core | 5.9KB | Basic save function only - hyperclay.savePage() |
-| save-system | 4.9KB | Manual save: keyboard shortcut (CMD+S), save button, change tracking |
+| save-core | 6.3KB | Basic save function only - hyperclay.savePage() |
+| save-system | 7KB | Manual save: keyboard shortcut (CMD+S), save button, change tracking |
+| save-toast | 0.9KB | Toast notifications for save events (opt-in) |
 
 ### Custom Attributes (HTML enhancements)
 
@@ -73,6 +74,7 @@ import 'hyperclayjs/presets/standard.js';
 | dom-helpers | 5.7KB | el.nearest, el.val, el.text, el.exec, el.cycle |
 | event-attrs | 3.6KB | [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 |
 
 ### UI Components (User interface elements)
@@ -126,17 +128,17 @@ import 'hyperclayjs/presets/standard.js';
 
 ## Presets
 
-### Minimal (~24.3KB)
+### Minimal (~27.7KB)
 Essential features for basic editing
 
-**Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `toast`, `export-to-window`
+**Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Standard (~40.8KB)
+### Standard (~44.2KB)
 Standard feature set for most use cases
 
-**Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`, `export-to-window`
+**Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Everything (~145.1KB)
+### Everything (~149.6KB)
 All available features
 
 Includes all available modules across all categories.

package/core/autosave.js

@@ -5,9 +5,9 @@
  * Warns before leaving page with unsaved changes.
  *
  * Requires the 'save-system' module to be loaded first.
+ * For toast notifications, also load the 'save-toast' module.
  */
 
-import toast from "../ui/toast.js";
 import Mutation from "../utilities/mutation.js";
 import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
 import {
@@ -24,9 +24,7 @@ function initSavePageOnChange() {
     debounce: 3333,
     omitChangeDetails: true
   }, () => {
-    savePageThrottled(({msg, msgType} = {}) => {
-      if (msg) toast(msg, msgType);
-    });
+    savePageThrottled();
   });
 }
 

package/core/savePage.js

@@ -1,15 +1,15 @@
 /**
  * Save system for Hyperclay
  *
- * Manual save with change detection, toast notifications,
+ * Manual save with change detection, state management,
  * keyboard shortcuts, and save button support.
  *
  * For auto-save on DOM changes, also load the 'autosave' module.
+ * For toast notifications, also load the 'save-toast' module.
  *
  * Built on top of savePageCore.js
  */
 
-import toast from "../ui/toast.js";
 import throttle from "../utilities/throttle.js";
 import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
 import {
@@ -19,6 +19,69 @@ import {
   beforeSave
 } from "./savePageCore.js";
 
+// ============================================
+// SAVE STATE MANAGEMENT
+// ============================================
+
+let savingTimeout = null;
+
+/**
+ * Sets the save status on <html> and dispatches an event.
+ *
+ * @param {string} state - One of: 'saving', 'saved', 'offline', 'error'
+ * @param {string} msg - Optional message (e.g., error details)
+ */
+function setSaveState(state, msg = '') {
+  if (savingTimeout) {
+    clearTimeout(savingTimeout);
+    savingTimeout = null;
+  }
+
+  document.documentElement.setAttribute('savestatus', state);
+
+  const event = new CustomEvent(`hyperclay:save-${state}`, {
+    detail: { msg, timestamp: Date.now() }
+  });
+  document.dispatchEvent(event);
+}
+
+/**
+ * Sets DOM state to 'offline' immediately, but does NOT fire an event.
+ * Used for instant UI feedback before we know the final state.
+ */
+function setOfflineStateQuiet() {
+  if (savingTimeout) {
+    clearTimeout(savingTimeout);
+    savingTimeout = null;
+  }
+  document.documentElement.setAttribute('savestatus', 'offline');
+}
+
+/**
+ * Starts a debounced 'saving' state.
+ * Only shows 'saving' if the save takes longer than 500ms.
+ * This prevents UI flicker on fast saves.
+ */
+function setSavingState() {
+  savingTimeout = setTimeout(() => {
+    setSaveState('saving');
+  }, 500);
+}
+
+// ============================================
+// OFFLINE DETECTION
+// ============================================
+
+window.addEventListener('offline', () => {
+  setOfflineStateQuiet();
+});
+
+window.addEventListener('online', () => {
+  if (document.documentElement.getAttribute('savestatus') === 'offline') {
+    savePage();
+  }
+});
+
 // Re-export from core for backward compatibility
 export { beforeSave, getPageContents };
 
@@ -41,7 +104,7 @@ document.addEventListener('DOMContentLoaded', () => {
 });
 
 /**
- * Save the current page with change detection and toast notifications
+ * Save the current page with change detection and state management
  *
  * @param {Function} callback - Optional callback for custom handling
  */
@@ -50,6 +113,13 @@ export function savePage(callback = () => {}) {
     return;
   }
 
+  // Check if offline - set DOM state immediately for UI feedback
+  // but still try the fetch (navigator.onLine can be wrong)
+  const wasOffline = !navigator.onLine;
+  if (wasOffline) {
+    setOfflineStateQuiet();
+  }
+
   const currentContents = getPageContents();
 
   // Track whether there are unsaved changes
@@ -60,11 +130,22 @@ export function savePage(callback = () => {}) {
     return;
   }
 
+  // Start debounced 'saving' state (only shows if save takes >500ms)
+  setSavingState();
+
   savePageCore(({msg, msgType}) => {
-    // Update tracking on success
     if (msgType !== 'error') {
+      // SUCCESS
       lastSavedContents = currentContents;
       unsavedChanges = false;
+      setSaveState('saved', msg);
+    } else {
+      // FAILED - determine if it's offline or server error
+      if (!navigator.onLine) {
+        setSaveState('offline', msg);
+      } else {
+        setSaveState('error', msg);
+      }
     }
 
     // Call user callback if provided
@@ -76,7 +157,7 @@ export function savePage(callback = () => {}) {
 
 /**
  * Fetch HTML from a URL and save it, then reload
- * Shows toast notifications
+ * Emits error event if save fails
  *
  * @param {string} url - URL to fetch from
  */
@@ -87,8 +168,8 @@ export function replacePageWith(url) {
 
   replacePageWithCore(url, (err, data) => {
     if (err) {
-      // Show error toast if save failed
-      toast(err.message || "Failed to save template", "error");
+      // Emit error event (save-toast will show toast if loaded)
+      setSaveState('error', err.message || "Failed to save template");
     } else {
       // Only reload if save was successful
       window.location.reload();
@@ -138,9 +219,7 @@ export function initSaveKeyboardShortcut() {
     let metaKeyPressed = isMac ? event.metaKey : event.ctrlKey;
     if (metaKeyPressed && event.keyCode == 83) {
       event.preventDefault();
-      savePage(({msg, msgType} = {}) => {
-        if (msg) toast(msg, msgType);
-      });
+      savePage();
     }
   });
 }
@@ -152,9 +231,7 @@ export function initSaveKeyboardShortcut() {
 export function initHyperclaySaveButton() {
   document.addEventListener("click", event => {
     if (event.target.closest("[trigger-save]")) {
-      savePage(({msg, msgType} = {}) => {
-        if (msg) toast(msg, msgType);
-      });
+      savePage();
     }
   });
 }

package/core/savePageCore.js

@@ -91,12 +91,18 @@ export function savePage(callback = () => {}) {
     return;
   }
 
+  // Add timeout - abort if server doesn't respond within 5 seconds
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 5000);
+
   fetch(saveEndpoint, {
     method: 'POST',
     credentials: 'include',
-    body: currentContents
+    body: currentContents,
+    signal: controller.signal
   })
   .then(res => {
+    clearTimeout(timeoutId);
     return res.json().then(data => {
       if (!res.ok) {
         throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
@@ -110,12 +116,19 @@ export function savePage(callback = () => {}) {
     }
   })
   .catch(err => {
+    clearTimeout(timeoutId);
     console.error('Failed to save page:', err);
+
+    const msg = err.name === 'AbortError'
+      ? 'Server not responding'
+      : (err.message || 'Failed to save');
+
     if (typeof callback === 'function') {
-      callback({msg: err.message || "Failed to save", msgType: "error"});
+      callback({msg, msgType: "error"});
     }
   })
   .finally(() => {
+    clearTimeout(timeoutId);
     saveInProgress = false;
   });
 }

package/core/saveToast.js

@@ -0,0 +1,37 @@
+/**
+ * Save Toast Module
+ *
+ * Listens for save lifecycle events and shows toast notifications.
+ * This is opt-in - only included if you want toast notifications.
+ *
+ * Events handled:
+ * - hyperclay:save-saved   → success toast
+ * - hyperclay:save-error   → error toast
+ * - hyperclay:save-offline → error toast (treated as error for notifications)
+ */
+
+import toast from "../ui/toast.js";
+import { isEditMode } from "./isAdminOfCurrentResource.js";
+
+function init() {
+  if (!isEditMode) return;
+
+  document.addEventListener('hyperclay:save-saved', (e) => {
+    const msg = e.detail?.msg || 'Saved';
+    toast(msg, 'success');
+  });
+
+  document.addEventListener('hyperclay:save-error', (e) => {
+    const msg = e.detail?.msg || 'Failed to save';
+    toast(msg, 'error');
+  });
+
+  document.addEventListener('hyperclay:save-offline', (e) => {
+    const msg = e.detail?.msg || 'No internet connection';
+    toast(msg, 'error');
+  });
+}
+
+init();
+
+export default init;

package/custom-attributes/onaftersave.js

@@ -0,0 +1,41 @@
+/**
+ * [onaftersave] Custom Attribute
+ *
+ * Runs inline JavaScript when save status changes.
+ * Pairs with the existing [onbeforesave] attribute.
+ *
+ * Usage:
+ *   <span onaftersave="this.innerText = event.detail.msg"></span>
+ *   <div onaftersave="console.log('Status:', event.detail.status)"></div>
+ *
+ * The event.detail object contains:
+ *   - status: 'saving' | 'saved' | 'offline' | 'error'
+ *   - msg: string (e.g., 'Saved' or error message)
+ *   - timestamp: number (Date.now())
+ */
+
+function broadcast(e) {
+  const status = e.type.replace('hyperclay:save-', '');
+  const detail = { ...e.detail, status };
+
+  document.querySelectorAll('[onaftersave]').forEach(el => {
+    try {
+      const event = new CustomEvent('aftersave', { detail });
+      const handler = new Function('event', el.getAttribute('onaftersave'));
+      handler.call(el, event);
+    } catch (err) {
+      console.error('[onaftersave] Error in handler:', err);
+    }
+  });
+}
+
+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();
+
+export default init;

package/hyperclay.js

@@ -1,5 +1,5 @@
 /**
- * HyperclayJS v1.4.0 - Minimal Browser-Native Loader
+ * HyperclayJS v1.5.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.
@@ -28,6 +28,7 @@ const MODULE_PATHS = {
   "save-core": "./core/savePageCore.js",
   "save-system": "./core/savePage.js",
   "autosave": "./core/autosave.js",
+  "save-toast": "./core/saveToast.js",
   "edit-mode-helpers": "./core/adminSystem.js",
   "persist": "./core/enablePersistentFormInputValues.js",
   "option-visibility": "./core/optionVisibilityRuleGenerator.js",
@@ -37,6 +38,7 @@ const MODULE_PATHS = {
   "sortable": "./custom-attributes/sortable.js",
   "dom-helpers": "./custom-attributes/domHelpers.js",
   "input-helpers": "./custom-attributes/inputHelpers.js",
+  "onaftersave": "./custom-attributes/onaftersave.js",
   "dialogs": "./ui/prompts.js",
   "toast": "./ui/toast.js",
   "toast-hyperclay": "./ui/toast-hyperclay.js",
@@ -70,6 +72,7 @@ const PRESETS = {
       "save-system",
       "edit-mode-helpers",
       "toast",
+      "save-toast",
       "export-to-window"
     ]
   },
@@ -85,6 +88,7 @@ const PRESETS = {
       "event-attrs",
       "dom-helpers",
       "toast",
+      "save-toast",
       "export-to-window"
     ]
   },
@@ -95,6 +99,7 @@ const PRESETS = {
       "save-core",
       "save-system",
       "autosave",
+      "save-toast",
       "edit-mode-helpers",
       "persist",
       "option-visibility",
@@ -104,6 +109,7 @@ const PRESETS = {
       "sortable",
       "dom-helpers",
       "input-helpers",
+      "onaftersave",
       "dialogs",
       "toast",
       "toast-hyperclay",

package/module-dependency-graph.json

@@ -50,7 +50,6 @@
     "core/autosave.js": [
       "core/isAdminOfCurrentResource.js",
       "core/savePage.js",
-      "ui/toast.js",
       "utilities/mutation.js"
     ],
     "core/editmode.js": [
@@ -75,13 +74,16 @@
     "core/savePage.js": [
       "core/isAdminOfCurrentResource.js",
       "core/savePageCore.js",
-      "ui/toast.js",
       "utilities/throttle.js"
     ],
     "core/savePageCore.js": [
       "core/isAdminOfCurrentResource.js",
       "utilities/cookie.js"
     ],
+    "core/saveToast.js": [
+      "core/isAdminOfCurrentResource.js",
+      "ui/toast.js"
+    ],
     "core/setPageTypeOnDocumentElement.js": [
       "core/isAdminOfCurrentResource.js",
       "core/savePage.js",
@@ -108,6 +110,7 @@
       "custom-attributes/autosize.js",
       "custom-attributes/preventEnter.js"
     ],
+    "custom-attributes/onaftersave.js": [],
     "custom-attributes/onclickaway.js": [],
     "custom-attributes/onclone.js": [],
     "custom-attributes/onpagemutation.js": [
@@ -165,7 +168,7 @@
     "save-core": {
       "name": "save-core",
       "category": "core",
-      "size": 5.9,
+      "size": 6.3,
       "files": [
         "core/savePageCore.js"
       ],
@@ -179,7 +182,7 @@
     "save-system": {
       "name": "save-system",
       "category": "core",
-      "size": 4.9,
+      "size": 7,
       "files": [
         "core/savePage.js"
       ],
@@ -202,13 +205,23 @@
     "autosave": {
       "name": "autosave",
       "category": "core",
-      "size": 1.2,
+      "size": 1.1,
       "files": [
         "core/autosave.js"
       ],
       "description": "Auto-save on DOM changes, unsaved changes warning",
       "exports": {}
     },
+    "save-toast": {
+      "name": "save-toast",
+      "category": "core",
+      "size": 0.9,
+      "files": [
+        "core/saveToast.js"
+      ],
+      "description": "Toast notifications for save events (opt-in)",
+      "exports": {}
+    },
     "edit-mode-helpers": {
       "name": "edit-mode-helpers",
       "category": "core",
@@ -321,6 +334,16 @@
       "description": "[prevent-enter], [autosize] for textareas",
       "exports": {}
     },
+    "onaftersave": {
+      "name": "onaftersave",
+      "category": "custom-attributes",
+      "size": 1.2,
+      "files": [
+        "custom-attributes/onaftersave.js"
+      ],
+      "description": "[onaftersave] attribute - run JS when save status changes",
+      "exports": {}
+    },
     "dialogs": {
       "name": "dialogs",
       "category": "ui",
@@ -669,6 +692,7 @@
     "save-core": "./core/savePageCore.js",
     "save-system": "./core/savePage.js",
     "autosave": "./core/autosave.js",
+    "save-toast": "./core/saveToast.js",
     "edit-mode-helpers": "./core/adminSystem.js",
     "persist": "./core/enablePersistentFormInputValues.js",
     "option-visibility": "./core/optionVisibilityRuleGenerator.js",
@@ -678,6 +702,7 @@
     "sortable": "./custom-attributes/sortable.js",
     "dom-helpers": "./custom-attributes/domHelpers.js",
     "input-helpers": "./custom-attributes/inputHelpers.js",
+    "onaftersave": "./custom-attributes/onaftersave.js",
     "dialogs": "./ui/prompts.js",
     "toast": "./ui/toast.js",
     "toast-hyperclay": "./ui/toast-hyperclay.js",
@@ -710,6 +735,7 @@
         "save-core",
         "save-system",
         "autosave",
+        "save-toast",
         "edit-mode-helpers",
         "persist",
         "option-visibility",
@@ -724,7 +750,8 @@
         "ajax-elements",
         "sortable",
         "dom-helpers",
-        "input-helpers"
+        "input-helpers",
+        "onaftersave"
       ]
     },
     "ui": {
@@ -792,6 +819,7 @@
         "save-system",
         "edit-mode-helpers",
         "toast",
+        "save-toast",
         "export-to-window"
       ]
     },
@@ -807,6 +835,7 @@
         "event-attrs",
         "dom-helpers",
         "toast",
+        "save-toast",
         "export-to-window"
       ]
     },
@@ -817,6 +846,7 @@
         "save-core",
         "save-system",
         "autosave",
+        "save-toast",
         "edit-mode-helpers",
         "persist",
         "option-visibility",
@@ -826,6 +856,7 @@
         "sortable",
         "dom-helpers",
         "input-helpers",
+        "onaftersave",
         "dialogs",
         "toast",
         "toast-hyperclay",

package/package.json

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