@hortonstudio/main 1.9.10 → 1.9.20

package/src/modules/default/functions/transition/transition.ts

@@ -0,0 +1,290 @@
+/**
+ * Page Transition Module
+ * Enhanced with namespace support and SPA/MPA compatibility
+ *
+ * Features:
+ * - Backward compatible with old single-trigger system
+ * - Namespace-specific transitions (data-hs-transition-namespace)
+ * - Separate exit/enter triggers with custom timing (optional)
+ * - MPA: Auto link interception (default)
+ * - SPA: Event-based integration (set data-hs-spa="true" on script tag)
+ *
+ * @version 2.0.0
+ */
+import fullConfig from '@config';
+import { querySelector, querySelectorAll, globalConfig } from '@utils';
+
+const API_NAME = globalConfig.apiName;
+
+export async function init(transitionConfig) {
+  const config = transitionConfig || fullConfig.default?.transition;
+
+  // Check if transition element exists - skip if not found
+  const transitionElement = querySelector(config, 'element');
+  if (!transitionElement) {
+    console.log('[transition] No transition element found, skipping initialization');
+    return {
+      result: 'transition skipped - no element found',
+      destroy: () => {},
+    };
+  }
+
+  // Get current namespace (if any)
+  const namespaceAttr = config.attributes.elements.namespace.primary;
+  const currentNamespace = transitionElement.getAttribute(namespaceAttr) || null;
+
+  // Check if running in SPA mode
+  const isSPA = window[API_NAME]?.settings?.isSPA || false;
+
+  // Store event handlers and timeouts for cleanup
+  const eventHandlers = new Map();
+  let delayTimeout = null;
+  let navTimeout = null;
+
+  const cleanup = () => {
+    // Clear any pending timeouts
+    if (delayTimeout) clearTimeout(delayTimeout);
+    if (navTimeout) clearTimeout(navTimeout);
+
+    // Remove all event listeners
+    eventHandlers.forEach((handler, event) => {
+      if (event === 'click' || event === 'pageshow' || event === 'resize') {
+        const target = event === 'click' ? document : window;
+        target.removeEventListener(event, handler);
+      } else {
+        window.removeEventListener(event, handler);
+      }
+    });
+    eventHandlers.clear();
+  };
+
+  /**
+   * Find trigger element for specific namespace and type (exit or enter)
+   * Falls back to default trigger (no namespace) if namespace-specific not found
+   * Also supports legacy single-trigger system for backward compatibility
+   */
+  const findTrigger = (type: 'exit' | 'enter', namespace: string | null) => {
+    // Try new system: separate exit/enter triggers
+    const allTriggers = querySelectorAll(config, type === 'exit' ? 'exitTrigger' : 'enterTrigger');
+
+    if (allTriggers.length > 0) {
+      // If namespace specified, try to find namespace-specific trigger first
+      if (namespace) {
+        const namespaceTrigger = Array.from(allTriggers).find(
+          (trigger) => trigger.getAttribute(namespaceAttr) === namespace
+        );
+        if (namespaceTrigger) return namespaceTrigger;
+      }
+
+      // Fall back to default trigger (no namespace attribute)
+      const defaultTrigger = Array.from(allTriggers).find(
+        (trigger) => !trigger.hasAttribute(namespaceAttr)
+      );
+
+      if (defaultTrigger) return defaultTrigger;
+      return allTriggers[0];
+    }
+
+    // Legacy fallback: look for old single trigger system
+    // This maintains backward compatibility with existing sites
+    const legacyTriggers = document.querySelectorAll('[data-hs-transition="trigger"]');
+    if (legacyTriggers.length > 0) {
+      // If namespace specified, try to find namespace-specific trigger
+      if (namespace) {
+        const namespaceTrigger = Array.from(legacyTriggers).find(
+          (trigger) => trigger.getAttribute(namespaceAttr) === namespace
+        );
+        if (namespaceTrigger) return namespaceTrigger;
+      }
+
+      // Fall back to first legacy trigger
+      return legacyTriggers[0];
+    }
+
+    return null;
+  };
+
+  /**
+   * Get timing value from trigger element or transition element (legacy)
+   */
+  const getTiming = (
+    trigger: Element | null,
+    type: 'time' | 'delay',
+    direction: 'exit' | 'enter'
+  ): number => {
+    if (!trigger) return 0;
+
+    // Try new system: timing attributes on trigger element
+    const attrName =
+      direction === 'exit'
+        ? type === 'time'
+          ? config.attributes.elements.exitTime.primary
+          : config.attributes.elements.exitDelay.primary
+        : type === 'time'
+          ? config.attributes.elements.enterTime.primary
+          : config.attributes.elements.enterDelay.primary;
+
+    let value = trigger.getAttribute(attrName);
+    if (value) return parseFloat(value) * 1000;
+
+    // Legacy fallback: timing on transition element
+    if (direction === 'exit' && type === 'time') {
+      value = transitionElement.getAttribute('data-hs-exit-time');
+      if (value) return parseFloat(value) * 1000;
+    }
+
+    if (direction === 'enter' && type === 'delay') {
+      value = transitionElement.getAttribute('data-hs-delay');
+      if (value) return parseFloat(value) * 1000;
+    }
+
+    return 0;
+  };
+
+  /**
+   * Play exit animation (when leaving page)
+   */
+  const playExitAnimation = (namespace: string | null = currentNamespace): Promise<void> => {
+    return new Promise((resolve) => {
+      const exitTrigger = findTrigger('exit', namespace);
+      if (!exitTrigger) {
+        resolve();
+        return;
+      }
+
+      const exitTime = getTiming(exitTrigger, 'time', 'exit');
+      const exitDelay = getTiming(exitTrigger, 'delay', 'exit');
+
+      const triggerAnimation = () => {
+        if (typeof Webflow !== 'undefined') {
+          Webflow.push(() => {
+            (exitTrigger as HTMLElement).click();
+          });
+        } else {
+          (exitTrigger as HTMLElement).click();
+        }
+
+        // Resolve after animation completes
+        setTimeout(resolve, exitTime);
+      };
+
+      if (exitDelay > 0) {
+        setTimeout(triggerAnimation, exitDelay);
+      } else {
+        triggerAnimation();
+      }
+    });
+  };
+
+  /**
+   * Play enter animation (when arriving on page)
+   */
+  const playEnterAnimation = (namespace: string | null = currentNamespace): Promise<void> => {
+    return new Promise((resolve) => {
+      const enterTrigger = findTrigger('enter', namespace);
+      if (!enterTrigger) {
+        resolve();
+        return;
+      }
+
+      const enterTime = getTiming(enterTrigger, 'time', 'enter');
+      const enterDelay = getTiming(enterTrigger, 'delay', 'enter');
+
+      // Check if first load (legacy behavior)
+      const isFirstLoad = !sessionStorage.getItem('transition-loaded');
+
+      const triggerAnimation = () => {
+        if (typeof Webflow !== 'undefined') {
+          Webflow.push(() => {
+            (enterTrigger as HTMLElement).click();
+          });
+        } else {
+          (enterTrigger as HTMLElement).click();
+        }
+
+        // Mark as loaded for session
+        if (isFirstLoad) {
+          sessionStorage.setItem('transition-loaded', 'true');
+        }
+
+        // Resolve after animation completes
+        setTimeout(resolve, enterTime);
+      };
+
+      // Only apply delay on first load (legacy behavior)
+      if (isFirstLoad && enterDelay > 0) {
+        delayTimeout = setTimeout(triggerAnimation, enterDelay);
+      } else {
+        triggerAnimation();
+      }
+    });
+  };
+
+  // Always listen for custom events (works for both MPA and SPA)
+  const handleExitEvent = () => playExitAnimation();
+  const handleEnterEvent = () => playEnterAnimation();
+
+  eventHandlers.set('hsmain:transition-exit', handleExitEvent);
+  eventHandlers.set('hsmain:transition-enter', handleEnterEvent);
+  window.addEventListener('hsmain:transition-exit', handleExitEvent);
+  window.addEventListener('hsmain:transition-enter', handleEnterEvent);
+
+  // MPA Mode: Intercept link clicks
+  if (!isSPA) {
+    const linkClickHandler = (e: MouseEvent) => {
+      const link = (e.target as Element).closest('a[href]') as HTMLAnchorElement;
+
+      if (
+        link &&
+        link.hostname === window.location.hostname &&
+        link.getAttribute('href') &&
+        link.getAttribute('href')!.indexOf('#') === -1 &&
+        link.getAttribute('target') !== '_blank'
+      ) {
+        e.preventDefault();
+        const href = link.href;
+
+        // Play exit animation, then navigate
+        playExitAnimation().then(() => {
+          window.location.href = href;
+        });
+      }
+    };
+
+    eventHandlers.set('click', linkClickHandler);
+    document.addEventListener('click', linkClickHandler);
+
+    // Handle back button navigation
+    const pageShowHandler = (event: PageTransitionEvent) => {
+      if (event.persisted) {
+        window.location.reload();
+      }
+    };
+
+    eventHandlers.set('pageshow', pageShowHandler);
+    window.addEventListener('pageshow', pageShowHandler);
+  }
+
+  // Hide transition on window resize (prevents visual glitches)
+  const resizeHandler = () => {
+    if (transitionElement) {
+      (transitionElement as HTMLElement).style.display = 'none';
+    }
+  };
+
+  eventHandlers.set('resize', resizeHandler);
+  window.addEventListener('resize', resizeHandler);
+
+  // On DOM ready, play enter animation
+  const domReadyHandler = () => {
+    playEnterAnimation();
+  };
+
+  eventHandlers.set(`${API_NAME}:dom-ready`, domReadyHandler);
+  window.addEventListener(`${API_NAME}:dom-ready`, domReadyHandler, { once: true });
+
+  return {
+    result: 'transition initialized',
+    destroy: cleanup,
+  };
+}

package/src/modules/normalize/README.md

@@ -0,0 +1,172 @@
+# **Normalize System Documentation**
+
+## **Overview**
+
+The normalize module provides functions that modify DOM structure before any visual changes occur. These are critical functions that run in Phase 1 (normalize) of the phased initialization system.
+
+**Purpose**: Ensure DOM structure is normalized and consistent before visual-dom modules run, preventing layout shifts and ensuring reliable selectors.
+
+**Phase**: Normalize (Phase 1) - runs first, before all other modules
+
+---
+
+## **Functions**
+
+### **1. Clickable**
+
+Normalizes clickable wrappers by keeping either `<button>` or `<a>` element based on href validity.
+
+**Use case:** Designer includes both button and link in wrapper. Script automatically keeps the semantically correct one based on whether there's a valid link destination.
+
+**Sub-functions:**
+
+- **normalize**: Removes duplicate button/link elements, keeps the correct one
+
+**Performance:** ~30-50ms for 100 wrappers (with 1s timeout safety)
+
+---
+
+## **Documentation**
+
+Each function has detailed documentation in its respective folder:
+
+- `functions/clickable/README.md`
+  - `functions/clickable/functions/normalize/README.md`
+
+---
+
+## **How It Works**
+
+The normalize system uses a dynamic loader pattern:
+
+1. Main `normalize.js` imports all function modules
+2. Each function is loaded in parallel via `Promise.allSettled()`
+3. All destroy functions are collected for cleanup
+4. On destroy, all functions are cleaned up properly
+
+**Initialization Flow**:
+
+```
+Page Load
+  ↓
+Phase 1: Normalize (normalize module) ← WE ARE HERE
+  ↓
+Phase 2: Visual-DOM (structure + form)
+  ↓
+Phase 3: Transition reveals page
+  ↓
+Phase 4: Default modules (accessibility, navbar, etc.)
+```
+
+---
+
+## **Phased Initialization**
+
+### **Why Phase 1?**
+
+These functions modify the DOM structure in fundamental ways:
+
+- Clickable removes elements from DOM
+- Other normalize functions might add/remove/restructure elements
+- Must happen BEFORE visual modules select elements
+
+**Without phasing**: Visual modules might select wrong elements or fail to find elements
+
+**With phasing**: DOM structure is normalized → visual modules always find correct elements
+
+### **Phase Characteristics**
+
+- **Timing**: Runs first, before all other modules
+- **Parallelization**: All functions load/execute in parallel within Phase 1
+- **Resilience**: Uses `Promise.allSettled` - individual failures don't block phase
+- **Timeout**: 1s timeout per module (safety net for stuck DOM operations)
+
+---
+
+## **Barba.js / SPA Compatibility**
+
+The normalize system is fully compatible with Barba.js and other SPA frameworks:
+
+### **v2.0.0 Improvements:**
+
+- **Resilient loading with Promise.allSettled** - Individual function failures won't break other functions
+- **Graceful error handling** - Failed functions are logged but don't prevent successful ones from working
+- **Complete cleanup on destroy** - All functions properly cleaned up for page transitions
+- **Phased initialization** - Same clean flow on page load and SPA transitions
+
+### **Resilient Loading:**
+
+- If one function fails (missing element, error, etc.), others continue working
+- Logs helpful warnings showing which functions succeeded/failed
+- System remains functional even with partial failures
+
+### **On Destroy:**
+
+1. Calls destroy() on all successfully loaded functions
+2. Errors during cleanup are caught and logged
+3. Cleanup tracking arrays are reset
+4. Safe for Barba.js page transitions
+
+### **On Reinitialize:**
+
+1. Attempts to load all functions again
+2. Works like fresh page load on new DOM
+3. Independent function loading ensures maximum resilience
+4. Runs in same Phase 1 timing for consistent UX
+
+---
+
+## **Performance**
+
+**Expected load time**: ~20-50ms total
+
+Individual timing varies by function:
+
+- Clickable normalization: ~30-50ms (DOM manipulation for 100 elements)
+
+**Total Phase 1 timing**: All normalize functions in parallel, typically completes in 30-50ms
+
+**1s timeout**: Safety net for stuck operations, ensures Phase 2 starts even if normalize hangs
+
+---
+
+## **Adding New Normalize Functions**
+
+To add a new normalize function:
+
+1. **Create function folder:**
+
+   ```
+   autoInit/normalize/functions/my-function/
+     my-function.js
+     config.js
+     README.md
+   ```
+
+2. **Update normalize.js functionMap:**
+
+   ```javascript
+   const functionMap = {
+     clickable: () => import('./functions/clickable/clickable.js'),
+     'my-function': () => import('./functions/my-function/my-function.js'),
+   };
+   ```
+
+3. **Follow the pattern:**
+   - Export `init()` function that returns `{ result, destroy }`
+   - Export `version` constant
+   - Use Promise.allSettled for resilient loading
+   - Clean up properly in destroy()
+
+---
+
+## **Notes**
+
+- All functions auto-initialize on page load
+- Each function operates independently
+- Barba.js compatible with proper cleanup
+- No configuration required at normalize level - each function uses its own config
+- Runs in Phase 1 (normalize) of initialization system
+- Uses Promise.allSettled for maximum reliability
+- Part of v2.0.0 phased initialization architecture
+- 1s timeout per module ensures Phase 2 starts even if normalize hangs

package/src/modules/normalize/functions/clickable/README.md

@@ -0,0 +1,84 @@
+# **Clickable System Documentation**
+
+## **Overview**
+
+The clickable system provides modular functions to manage clickable elements and their behaviors. Each function operates independently and can be customized through data attributes.
+
+**Note:** This module auto-initializes and loads all functions on page load.
+
+---
+
+## **Functions**
+
+### **1. Normalize**
+
+Normalizes clickable wrappers by keeping either `<button>` or `<a>` element based on href validity.
+
+**Use case:** Designer includes both button and link in wrapper. Script automatically keeps the semantically correct one based on whether there's a valid link destination.
+
+**How it works:**
+
+- If `<a>` has valid href (not empty, not "#") → keep link, remove button
+- Otherwise → keep button, remove link
+- Kept element gets `data-site-clickable="button"` for reliable selection by other modules
+
+**Performance:** ~30-50ms for 100 wrappers
+
+---
+
+## **Documentation**
+
+Each function has detailed documentation in its respective folder:
+
+- `functions/normalize/README.md`
+
+---
+
+## **How It Works**
+
+The clickable system uses a dynamic loader pattern:
+
+1. Main `clickable.js` imports all function modules
+2. Each function is loaded in parallel via `Promise.allSettled()`
+3. All destroy functions are collected for cleanup
+4. On destroy, all functions are cleaned up properly
+
+---
+
+## **Barba.js / SPA Compatibility**
+
+The clickable system is fully compatible with Barba.js and other SPA frameworks:
+
+### **v2.0.0 Improvements:**
+
+- **Resilient loading with Promise.allSettled** - Individual function failures won't break other functions
+- **Graceful error handling** - Failed functions are logged but don't prevent successful ones from working
+- **Complete cleanup on destroy** - All functions properly cleaned up for page transitions
+
+### **Resilient Loading:**
+
+- If one clickable function fails (missing element, error, etc.), others continue working
+- Logs helpful warnings showing which functions succeeded/failed
+- System remains functional even with partial failures
+
+### **On Destroy:**
+
+1. Calls destroy() on all successfully loaded functions
+2. Errors during cleanup are caught and logged
+3. Cleanup tracking arrays are reset
+4. Safe for Barba.js page transitions
+
+### **On Reinitialize:**
+
+1. Attempts to load all functions again
+2. Works like fresh page load on new DOM
+3. Independent function loading ensures maximum resilience
+
+---
+
+## **Notes**
+
+- All functions auto-initialize on page load
+- Each function operates independently
+- Barba.js compatible with proper cleanup
+- No configuration required - works with data attributes

package/src/modules/normalize/functions/clickable/clickable.ts

@@ -0,0 +1,43 @@
+/**
+ * Clickable Orchestrator
+ * Manages clickable wrapper normalization
+ *
+ * Uses static imports and passes config down to functions
+ * @version 2.0.0
+ */
+import { init as normalizeInit } from './functions/normalize/normalize.ts';
+
+export async function init(clickableConfig) {
+  const cleanup = { destroyFunctions: [] };
+
+  try {
+    // Load normalize function
+    const normalizeResult = await normalizeInit(clickableConfig.normalize);
+    if (normalizeResult?.destroy) cleanup.destroyFunctions.push(normalizeResult.destroy);
+
+    return {
+      result: 'clickable initialized',
+      destroy: () => {
+        cleanup.destroyFunctions.forEach((destroyFn) => {
+          try {
+            destroyFn();
+          } catch (error) {
+            console.error('[clickable] Error during cleanup:', error);
+          }
+        });
+        cleanup.destroyFunctions.length = 0;
+      },
+    };
+  } catch (error) {
+    console.error('[clickable] Initialization failed:', error);
+    // Cleanup any partial initialization
+    cleanup.destroyFunctions.forEach((fn) => {
+      try {
+        fn();
+      } catch (cleanupError) {
+        console.error('[clickable] Error during error cleanup:', cleanupError);
+      }
+    });
+    throw error;
+  }
+}