hyperclayjs 1.3.1 → 1.5.0

package/LICENSE

@@ -19,3 +19,24 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+## Third-Party Licenses
+
+This project includes the following third-party libraries:
+
+### Idiomorph
+- Copyright (c) Big Sky Software
+- License: 0BSD (Zero-Clause BSD)
+- https://github.com/bigskysoftware/idiomorph
+
+### Tailwind CSS
+- Copyright (c) Tailwind Labs, Inc.
+- License: MIT
+- https://github.com/tailwindlabs/tailwindcss
+
+### Sortable.js
+- Copyright (c) All contributors to Sortable
+- License: MIT
+- https://github.com/SortableJS/Sortable

package/README.md

@@ -15,22 +15,27 @@ A modular JavaScript library for building interactive HTML applications with Hyp
 
 ### Using CDN (Self-detecting Loader)
 
-The self-detecting loader reads URL parameters and automatically loads the requested features with all dependencies:
+The self-detecting loader reads URL parameters and automatically loads the requested features with all dependencies.
 
-```html
-<!-- Minimal setup -->
-<script src="https://hyperclay.com/js/hyperclay.js?preset=minimal" type="module"></script>
+Destructure directly from the import:
 
-<!-- Standard setup -->
-<script src="https://hyperclay.com/js/hyperclay.js?preset=standard" type="module"></script>
+```html
+<script type="module">
+  const { toast, savePage } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/hyperclay.js?preset=standard');
+  toast('Hello!');
+</script>
+```
 
-<!-- Custom features -->
-<script src="https://hyperclay.com/js/hyperclay.js?features=save,admin,toast,ajax" type="module"></script>
+Or with custom features:
 
-<!-- Everything -->
-<script src="https://hyperclay.com/js/hyperclay.js?preset=everything" type="module"></script>
+```html
+<script type="module">
+  const { toast, ask } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/hyperclay.js?features=toast,dialogs');
+</script>
 ```
 
+**Note:** Presets include `export-to-window` by default, which also exports to `window.hyperclay`. Omit it from custom features if you only want ES module exports.
+
 ### Using NPM
 
 ```bash
@@ -52,91 +57,112 @@ import 'hyperclayjs/presets/standard.js';
 
 | Module | Size | Description |
 |--------|------|-------------|
-| admin | 5.4KB | Hides admin inputs, scripts, contenteditable, onclick for regular viewers |
-| autosave | 2.4KB | Auto-save on DOM changes, unsaved changes warning |
-| edit-mode | 1.7KB | Toggle edit mode on/off |
+| 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.4KB | Persist form values to the DOM with [persist] attribute |
-| save-core | 5.8KB | Basic save function only - hyperclay.savePage() |
-| save-system | 4.1KB | Manual save: keyboard shortcut (CMD+S), save button, change tracking |
+| 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-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)
 
 | Module | Size | Description |
 |--------|------|-------------|
 | ajax-elements | 2.8KB | [ajax-form], [ajax-button] for async form submissions |
-| dom-helpers | 5.6KB | el.nearest, el.val, el.text, el.exec, el.cycle |
+| 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 |
-| sortable | 118.1KB | Drag-drop sorting with [sortable] - includes Sortable.js vendor library |
+| 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)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| dialogs | 11.2KB | ask(), consent(), tell(), info(), snippet() functions |
-| modal | 18.5KB | Full modal window creation system - window.theModal |
-| tailwind-play | 362.3KB | Live Tailwind CSS editing - no need for a build system |
-| toast | 7.3KB | Success/error message notifications - toast(msg, msgType) |
+| dialogs | 8.4KB | ask(), consent(), tell(), snippet() dialog functions |
+| tailwind-play | 0.7KB | Live Tailwind CSS editing, lazy-loads ~370KB script in edit mode only |
+| the-modal | 19.8KB | Full modal window creation system - window.theModal |
+| toast | 7.7KB | Success/error message notifications, toast(msg, msgType) |
 
 ### Utilities (Core utilities (often auto-included))
 
 | Module | Size | Description |
 |--------|------|-------------|
-| cookie | 1.3KB | Cookie management (often auto-included) |
+| cookie | 1.4KB | Cookie management (often auto-included) |
 | debounce | 0.4KB | Function debouncing |
-| mutation | 12.9KB | DOM mutation observation (often auto-included) |
-| nearest | 3.3KB | Find nearest elements (often auto-included) |
-| throttle | 0.7KB | Function throttling |
+| mutation | 13KB | DOM mutation observation (often auto-included) |
+| nearest | 3.4KB | Find nearest elements (often auto-included) |
+| throttle | 0.8KB | Function throttling |
 
 ### DOM Utilities (DOM manipulation helpers)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| all-js | 13.9KB | Full DOM manipulation library |
-| dom-ready | 0.3KB | DOM ready callback |
-| form-data | 1.9KB | Extract form data as an object |
-| style-injection | 1KB | Dynamic stylesheet injection |
+| all-js | 14KB | 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 |
 
 ### String Utilities (String manipulation helpers)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| clipboard | 0.8KB | Clipboard utility |
-| emmet | 1.5KB | Emmet-like HTML generation |
-| query-params | 0.2KB | Parse URL search params |
-| slugify | 0.6KB | URL-friendly slug generator |
+| copy-to-clipboard | 0.9KB | Clipboard utility |
+| query-params | 0.3KB | Parse URL search params |
+| slugify | 0.7KB | URL-friendly slug generator |
 
 ### Communication & Files (File handling and messaging)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| file-upload | 10.6KB | File upload with progress |
-| send-message | 1.3KB | Message sending utility |
+| file-upload | 10.7KB | File upload with progress |
+| send-message | 1.4KB | Message sending utility |
 
 ### Vendor Libraries (Third-party libraries)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| idiomorph | 8.1KB | Efficient DOM morphing library |
+| idiomorph | 8.2KB | Efficient DOM morphing library |
 
 ## Presets
 
-### Minimal (~22.6KB)
+### Minimal (~27.7KB)
 Essential features for basic editing
 
-**Modules:** `save-core`, `save-system`, `admin`, `toast`
+**Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Standard (~38.9KB)
+### Standard (~44.2KB)
 Standard feature set for most use cases
 
-**Modules:** `save-core`, `save-system`, `admin`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`
+**Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Everything (~629.5KB)
+### Everything (~149.6KB)
 All available features
 
 Includes all available modules across all categories.
 
+## Lazy-Loaded Modules
+
+Some modules with large vendor dependencies are **lazy-loaded** to optimize page performance:
+
+| Module | Wrapper Size | Vendor Size | Loaded When |
+|--------|-------------|-------------|-------------|
+| `sortable` | ~3KB | ~118KB | Edit mode only |
+| `tailwind-play` | ~1KB | ~370KB | Edit mode only |
+
+**How it works:**
+- The wrapper module checks if the page is in edit mode (`isEditMode`)
+- If true, it injects a `<script save-ignore>` tag that loads the vendor script
+- If false, nothing is loaded - viewers don't download the heavy scripts
+- The `save-ignore` attribute strips the script tag when the page is saved
+
+This means:
+- **Editors** get full functionality when needed
+- **Viewers** never download ~500KB of vendor scripts
+- **Saved pages** stay clean with no leftover script tags
+
 ## Visual Configurator
 
 Explore features and build your custom bundle with our interactive configurator:
@@ -217,7 +243,7 @@ The configurator dynamically loads this file to always show accurate information
 - Safari 15.4+
 - Edge 89+
 
-The loader uses top-level await, which means any `<script type="module">` placed after it will automatically wait for HyperclayJS to finish loading. No ready events or promises needed.
+The loader uses ES modules with top-level await. Use `await import()` to ensure modules finish loading before your code runs.
 
 ## API Examples
 
@@ -278,7 +304,7 @@ tell("Welcome to Hyperclay!");
   Click outside this div
 </div>
 
-<!-- Persist form values -->
+<!-- Persist input/select/textarea values -->
 <input type="text" name="username" persist>
 ```
 
@@ -320,7 +346,7 @@ myFeature();
 <script src="/js/hyperclay.js?preset=standard" type="module"></script>
 
 <!-- Or specific features -->
-<script src="/js/hyperclay.js?features=save,admin,toast" type="module"></script>
+<script src="/js/hyperclay.js?features=save,edit-mode-helpers,toast" type="module"></script>
 ```
 
 ## Contributing
@@ -338,6 +364,14 @@ myFeature();
 
 MIT © Hyperclay
 
+### Third-Party Credits
+
+This project includes the following open-source libraries:
+
+- **[Idiomorph](https://github.com/bigskysoftware/idiomorph)** - DOM morphing library by Big Sky Software (0BSD)
+- **[Tailwind CSS](https://github.com/tailwindlabs/tailwindcss)** - Utility-first CSS framework by Tailwind Labs (MIT)
+- **[Sortable.js](https://github.com/SortableJS/Sortable)** - Drag-and-drop library (MIT)
+
 ## Links
 
 - [Documentation](https://hyperclay.com/docs)

package/communication/behaviorCollector.js

@@ -222,9 +222,12 @@ const behaviorCollector = (() => {
   };
 })();
 
-// Self-export to hyperclay only
-window.hyperclay = window.hyperclay || {};
-window.hyperclay.behaviorCollector = behaviorCollector;
+// Auto-export to window unless suppressed by loader
+if (!window.__hyperclayNoAutoExport) {
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.behaviorCollector = behaviorCollector;
+  window.h = window.hyperclay;
+}
 
 export default behaviorCollector;
 
@@ -234,4 +237,4 @@ export function init() {
 }
 
 // Auto-init when module is imported
-init();
+init();

package/communication/sendMessage.js

@@ -47,8 +47,11 @@ function sendMessage(eventOrObj, successMessage = "Successfully sent", callback)
     });
 }
 
-// Self-export to hyperclay only
-window.hyperclay = window.hyperclay || {};
-window.hyperclay.sendMessage = sendMessage;
+// Auto-export to window unless suppressed by loader
+if (!window.__hyperclayNoAutoExport) {
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.sendMessage = sendMessage;
+  window.h = window.hyperclay;
+}
 
-export default sendMessage;
+export default sendMessage;

package/communication/uploadFile.js

@@ -347,8 +347,11 @@ function detectContentType(content) {
   return { type: "txt", mime: "text/plain", extension: ".txt" };
 }
 
-// Self-export to hyperclay only
-window.hyperclay = window.hyperclay || {};
-window.hyperclay.uploadFile = uploadFile;
-window.hyperclay.createFile = createFile;
-window.hyperclay.uploadFileBasic = uploadFileBasic;
+// Auto-export to window unless suppressed by loader
+if (!window.__hyperclayNoAutoExport) {
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.uploadFile = uploadFile;
+  window.hyperclay.createFile = createFile;
+  window.hyperclay.uploadFileBasic = uploadFileBasic;
+  window.h = window.hyperclay;
+}

package/core/autosave.js

@@ -4,67 +4,27 @@
  * Automatically saves page on DOM changes with throttling.
  * Warns before leaving page with unsaved changes.
  *
- * Requires the 'save' module to be loaded first.
+ * 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 throttle from "../utilities/throttle.js";
 import Mutation from "../utilities/mutation.js";
 import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
-import { getPageContents } from "./savePageCore.js";
 import {
-  savePage,
-  getUnsavedChanges,
-  setUnsavedChanges,
-  getLastSavedContents
+  savePageThrottled,
+  getUnsavedChanges
 } from "./savePage.js";
 
-let baselineContents = '';
-
-// Capture baseline after setup mutations settle
-document.addEventListener('DOMContentLoaded', () => {
-  if (isEditMode) {
-    setTimeout(() => {
-      baselineContents = getPageContents();
-    }, 1500);
-  }
-});
-
-/**
- * Throttled version of savePage for auto-save
- */
-const throttledSave = throttle(savePage, 1200);
-
-/**
- * Save the page with throttling, for use with auto-save
- * Checks both baseline and last saved content to prevent saves from initial setup
- *
- * @param {Function} callback - Optional callback
- */
-export function savePageThrottled(callback = () => {}) {
-  if (!isEditMode) return;
-
-  const currentContents = getPageContents();
-  // For autosave: check both that content changed from baseline AND from last save
-  // This prevents saves from initial setup mutations
-  if (currentContents !== baselineContents && currentContents !== getLastSavedContents()) {
-    setUnsavedChanges(true);
-    throttledSave(callback);
-  }
-}
-
 /**
  * Initialize auto-save on DOM changes
  * Uses debounced mutation observer
  */
-export function initSavePageOnChange() {
+function initSavePageOnChange() {
   Mutation.onAnyChange({
     debounce: 3333,
     omitChangeDetails: true
   }, () => {
-    savePageThrottled(({msg, msgType} = {}) => {
-      if (msg) toast(msg, msgType);
-    });
+    savePageThrottled();
   });
 }
 
@@ -83,13 +43,9 @@ function init() {
   initSavePageOnChange();
 }
 
-// Self-export to hyperclay
-window.hyperclay = window.hyperclay || {};
-window.hyperclay.savePageThrottled = savePageThrottled;
-window.hyperclay.initSavePageOnChange = initSavePageOnChange;
+// No window exports - savePageThrottled is exported from save-system
 
 // Auto-init when module is imported
 init();
 
-export { init, savePageThrottled, initSavePageOnChange };
 export default init;

package/core/editmodeSystem.js

@@ -7,11 +7,14 @@ function init() {
   initPageType();
 }
 
-// Self-export to hyperclay only
-window.hyperclay = window.hyperclay || {};
-window.hyperclay.toggleEditMode = toggleEditMode;
-window.hyperclay.isEditMode = isEditMode;
-window.hyperclay.isOwner = isOwner;
+// Auto-export to window unless suppressed by loader
+if (!window.__hyperclayNoAutoExport) {
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.toggleEditMode = toggleEditMode;
+  window.hyperclay.isEditMode = isEditMode;
+  window.hyperclay.isOwner = isOwner;
+  window.h = window.hyperclay;
+}
 
 // Auto-init when module is imported
 init();

package/core/enablePersistentFormInputValues.js

@@ -61,9 +61,12 @@ export function init() {
   enablePersistentFormInputValues("[persist]");
 }
 
-// Self-export to hyperclay only
-window.hyperclay = window.hyperclay || {};
-window.hyperclay.enablePersistentFormInputValues = enablePersistentFormInputValues;
+// Auto-export to window unless suppressed by loader
+if (!window.__hyperclayNoAutoExport) {
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.enablePersistentFormInputValues = enablePersistentFormInputValues;
+  window.h = window.hyperclay;
+}
 
 // Auto-init when module is imported
-init();
+init();

package/core/exportToWindow.js

@@ -0,0 +1,14 @@
+/**
+ * Export to Window Module
+ *
+ * When loaded FIRST by the loader, this flips the __hyperclayNoAutoExport flag
+ * to false, allowing subsequent modules to self-export to window.hyperclay.
+ *
+ * This module is included in all presets by default.
+ * Exclude it if you prefer ES module-only imports (no window pollution).
+ */
+
+// Flip the flag so modules will auto-export
+window.__hyperclayNoAutoExport = false;
+
+export default true;

package/core/optionVisibilityRuleGenerator.js

@@ -152,10 +152,13 @@ const optionVisibilityRuleGenerator = {
   },
 };
 
-// Self-export to window and hyperclay
-window.optionVisibilityRuleGenerator = optionVisibilityRuleGenerator;
-window.hyperclay = window.hyperclay || {};
-window.hyperclay.optionVisibilityRuleGenerator = optionVisibilityRuleGenerator;
+// Auto-export to window unless suppressed by loader
+if (!window.__hyperclayNoAutoExport) {
+  window.optionVisibilityRuleGenerator = optionVisibilityRuleGenerator;
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.optionVisibilityRuleGenerator = optionVisibilityRuleGenerator;
+  window.h = window.hyperclay;
+}
 
 export default optionVisibilityRuleGenerator;
 
@@ -165,4 +168,4 @@ export function init() {
 }
 
 // Auto-init when module is imported
-init();
+init();