@hortonstudio/main 1.9.4 → 1.9.7

package/autoInit/smooth-scroll/README.md

@@ -0,0 +1,386 @@
+# **Smooth Scroll System Documentation**
+
+## **Overview**
+
+The smooth scroll system provides GSAP-powered smooth scrolling for anchor links, replacing Webflow's default behavior with a more customizable solution. It supports scroll offsets, reduced motion preferences, and automatically triggers scroll-based animations on page load.
+
+**Note:** This module auto-initializes on every page load.
+
+---
+
+## **Smooth Scroll**
+
+### **Required Dependencies**
+
+**GSAP Core**
+* Must be loaded before this script
+
+**GSAP ScrollToPlugin**
+* Required for smooth scrolling functionality
+
+**Typical setup:**
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollToPlugin.min.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@hortonstudio/main@latest"></script>
+```
+
+### **What It Does**
+
+1. **Disables native smooth scroll** - Removes Webflow's jQuery-based anchor link handler
+2. **Disables CSS smooth scrolling** - Sets `scroll-behavior: auto` on html and body
+3. **GSAP smooth scrolling** - Uses GSAP ScrollToPlugin for animated scrolling
+4. **Respects reduced motion** - Instant scroll if user has `prefers-reduced-motion` enabled
+5. **Custom offset support** - Reads `--misc--scroll-offset` CSS variable for scroll offset
+6. **Focus management** - Sets focus on target element after scroll
+7. **URL hash updates** - Updates browser URL with hash when scrolling to anchor
+8. **Mock scroll trigger** - Triggers scroll-based animations on page load with quick scroll
+9. **Keyboard support** - Handles Enter/Space key activation on anchor links
+
+### **When It Runs**
+
+* Auto-initializes on page load
+* Runs on every page in a multi-page site
+* Listed in `autoInitModules` in index.js
+
+---
+
+## **Scroll Offset**
+
+### **CSS Variable**
+
+Define a scroll offset using a CSS custom property:
+
+```css
+:root {
+  --misc--scroll-offset: 100px;
+}
+```
+
+**What it does:** When scrolling to an anchor, the page scrolls to the target element minus this offset. Useful for fixed headers.
+
+**Default:** `0` (no offset)
+
+**Units:** Pixels only (parsed as integer)
+
+### **Example with Fixed Header**
+
+```css
+:root {
+  --misc--scroll-offset: 80px; /* Height of fixed navbar */
+}
+```
+
+**Result:** When clicking an anchor link, the page scrolls so the target element is 80px from the top of the viewport.
+
+---
+
+## **Anchor Links**
+
+### **Supported Anchor Links**
+
+Any link with `href` starting with `#`:
+
+```html
+<a href="#section-1">Go to Section 1</a>
+<a href="#about">About Us</a>
+<a href="#contact">Contact</a>
+```
+
+**Requirements:**
+- Must have `href` attribute starting with `#`
+- Target element must have matching `id` attribute
+- Cannot be just `#` (empty hash)
+
+### **Target Elements**
+
+```html
+<section id="section-1">
+  <h2>Section 1</h2>
+</section>
+
+<div id="about">
+  <h2>About Us</h2>
+</div>
+```
+
+**Requirements:**
+- Must have `id` attribute matching the anchor's `href` (without `#`)
+
+---
+
+## **Animation Settings**
+
+### **GSAP Configuration**
+
+The scroll animation uses these GSAP settings:
+
+**Duration:** `1` second
+**Easing:** `power2.out` (fast start, slow end)
+**Plugin:** ScrollToPlugin with `offsetY` support
+
+### **Example of smooth scroll behavior:**
+
+```javascript
+gsap.to(window, {
+  duration: 1,
+  scrollTo: {
+    y: target,
+    offsetY: offset,
+  },
+  ease: "power2.out"
+});
+```
+
+**Result:** Smooth 1-second scroll with deceleration easing.
+
+---
+
+## **Reduced Motion Support**
+
+### **What It Does**
+
+If user has `prefers-reduced-motion: reduce` enabled:
+- Skips GSAP animation entirely
+- Uses instant scroll with `window.scrollTo()`
+- Still respects scroll offset
+- Still sets focus on target element
+
+### **Detection**
+
+```javascript
+window.matchMedia("(prefers-reduced-motion: reduce)").matches
+```
+
+**Result:** Users with motion sensitivity get instant, non-animated scrolling while maintaining all functionality.
+
+---
+
+## **Focus Management**
+
+### **Automatic Focus**
+
+After scrolling to target element:
+1. Sets `tabindex="-1"` on target (makes it focusable without adding to tab order)
+2. Calls `focus({ preventScroll: true })` on target
+3. Announces target to screen readers
+
+**Why:** Improves accessibility by moving keyboard focus to the section you scrolled to, similar to native anchor link behavior.
+
+---
+
+## **Mock Scroll (Animation Trigger)**
+
+### **What It Does**
+
+On page load, performs a quick scroll:
+1. Scrolls to `1px`
+2. Immediately scrolls back to `0px`
+
+**Why:** Triggers scroll-based animations (IntersectionObserver, scroll triggers) that only fire when the page scrolls.
+
+**Condition:** Only runs if page is scrollable (`document.body.scrollHeight > window.innerHeight`)
+
+**Result:** Scroll-based animations initialize properly on page load without user interaction.
+
+---
+
+## **URL Hash Updates**
+
+When clicking an anchor link:
+1. Prevents default browser behavior
+2. Updates URL hash using `history.replaceState()`
+3. Scrolls to target
+
+**Example:**
+- Click `<a href="#about">`
+- URL changes from `example.com` to `example.com#about`
+- Page smoothly scrolls to `#about` element
+
+**Note:** Uses `replaceState` (not `pushState`), so it doesn't create a new browser history entry.
+
+---
+
+## **Keyboard Support**
+
+### **Supported Keys**
+
+When an anchor link is focused:
+- **Enter** � Triggers smooth scroll to target
+- **Space** � Triggers smooth scroll to target
+
+**Implementation:** Keyboard events are handled the same as clicks, providing consistent behavior.
+
+---
+
+## **Usage Examples**
+
+### **Basic Anchor Link**
+
+```html
+<nav>
+  <a href="#section-1">Section 1</a>
+  <a href="#section-2">Section 2</a>
+</nav>
+
+<section id="section-1">
+  <h2>Section 1</h2>
+  <p>Content here...</p>
+</section>
+
+<section id="section-2">
+  <h2>Section 2</h2>
+  <p>More content...</p>
+</section>
+```
+
+**Result:** Clicking links smoothly scrolls to corresponding sections with 1-second animation.
+
+### **With Scroll Offset**
+
+```css
+:root {
+  --misc--scroll-offset: 100px;
+}
+```
+
+```html
+<header style="position: fixed; height: 100px;">
+  <nav>
+    <a href="#content">Skip to content</a>
+  </nav>
+</header>
+
+<main id="content" style="margin-top: 100px;">
+  <h1>Main Content</h1>
+</main>
+```
+
+**Result:** Clicking "Skip to content" scrolls so the main content appears 100px from top (below the fixed header).
+
+### **Table of Contents**
+
+```html
+<nav class="toc">
+  <a href="#introduction">Introduction</a>
+  <a href="#features">Features</a>
+  <a href="#installation">Installation</a>
+  <a href="#usage">Usage</a>
+</nav>
+
+<article>
+  <section id="introduction">
+    <h2>Introduction</h2>
+  </section>
+
+  <section id="features">
+    <h2>Features</h2>
+  </section>
+
+  <section id="installation">
+    <h2>Installation</h2>
+  </section>
+
+  <section id="usage">
+    <h2>Usage</h2>
+  </section>
+</article>
+```
+
+**Result:** Fully functional table of contents with smooth scrolling and focus management.
+
+---
+
+## **Webflow Integration**
+
+### **Disables Webflow's Default Behavior**
+
+This script automatically disables:
+1. **jQuery scroll handler** - Removes `click.wf-scroll` event listener
+2. **CSS smooth scrolling** - Sets `scroll-behavior: auto`
+
+**When:** On Webflow ready (`afterWebflowReady()` callback)
+
+**Why:** Prevents conflicts between Webflow's scroll and GSAP scroll.
+
+---
+
+## **Key Attributes Summary**
+
+This module doesn't require any data attributes - it works automatically with standard HTML anchor links.
+
+| Element | Requirement |
+| ----- | ----- |
+| Anchor link | `href="#target-id"` |
+| Target element | `id="target-id"` |
+
+---
+
+## **API**
+
+This module has no public API methods. It runs automatically and handles all anchor links on the page.
+
+---
+
+## **Notes**
+
+1. **GSAP required** - Must load GSAP and ScrollToPlugin before this script
+2. **Auto-initializes** - Runs on every page load
+3. **Disables Webflow scroll** - Replaces Webflow's default anchor link behavior
+4. **Accessibility first** - Respects reduced motion, manages focus
+5. **No configuration** - Works out of the box with standard HTML
+6. **CSS variable for offset** - Use `--misc--scroll-offset` for custom offset
+7. **Mock scroll triggers animations** - Ensures scroll-based animations initialize
+8. **Clean destroy** - Removes listeners and re-enables CSS smooth scrolling on cleanup
+
+---
+
+## **Common Issues**
+
+**Smooth scroll not working:**
+
+1. Verify GSAP and ScrollToPlugin are loaded before main script
+2. Check browser console for GSAP errors
+3. Ensure anchor `href` starts with `#` and matches target `id`
+4. Verify target element exists in DOM
+
+**Scroll offset not working:**
+
+1. Check CSS variable is defined: `--misc--scroll-offset: 100px`
+2. Verify it's on `:root` or `html` element (computed style)
+3. Ensure value is in pixels (no other units supported)
+4. Check computed styles in browser DevTools
+
+**Focus not working after scroll:**
+
+1. This is expected behavior for accessibility
+2. Target element gets `tabindex="-1"` and focus
+3. Use CSS to style `:focus` state if needed
+4. Don't prevent this - it's important for screen reader users
+
+**Scroll animations not triggering on load:**
+
+1. Mock scroll only runs if page is scrollable
+2. Check that `document.body.scrollHeight > window.innerHeight`
+3. If page isn't tall enough, animations may not trigger
+4. Add more content or adjust animation triggers
+
+**Reduced motion not instant:**
+
+1. Check browser/OS motion settings
+2. Test with DevTools: Rendering � Emulate CSS media `prefers-reduced-motion: reduce`
+3. Verify scroll is instant (no animation)
+
+**URL hash not updating:**
+
+1. Check `history.replaceState` is supported (all modern browsers)
+2. Verify no errors in console
+3. Ensure target element has `id` attribute
+4. Check that link click isn't being prevented elsewhere
+
+**Conflicts with other scroll libraries:**
+
+1. This module disables Webflow's scroll on init
+2. If using Lenis or other smooth scroll libraries, may conflict
+3. Choose one smooth scroll solution per site
+4. Remove this module if using another smooth scroll library

package/autoInit/transition/README.md

@@ -0,0 +1,301 @@
+# **Page Transition System Documentation**
+
+## **Overview**
+
+The page transition system provides smooth animated transitions between pages in your Webflow site. It automatically triggers entrance animations on page load and exit animations when clicking internal links, creating a seamless single-page-application feel.
+
+**Note:** This module auto-initializes by default unless the `no-transition` attribute is added to the script tag.
+
+---
+
+## **Page Transitions**
+
+### **Required Elements**
+
+**Transition Trigger** *(invisible element that triggers Webflow IX animation)*
+
+* data-hs-transition="trigger"
+* Webflow IX interaction attached (entrance and exit animations)
+
+**Transition Element** *(visual overlay that covers the page during transition)*
+
+* data-hs-transition="element"
+* Should cover entire viewport
+* Contains visual transition effect (fade, slide, etc.)
+
+**Exit Time** *(optional attribute on transition element)*
+
+* data-hs-exit-time="0.5"
+* Time in seconds to wait before navigating to new page
+* Should match your Webflow exit animation duration
+
+**Entrance Delay** *(optional attribute on transition element)*
+
+* data-hs-delay="0.3"
+* Delay in seconds before triggering entrance animation on FIRST page load only
+* Subsequent page loads trigger instantly (no delay)
+* Default: 0 (instant trigger)
+
+**Typical element layout:**
+
+1. Transition Wrapper
+   1. Transition Trigger (data-hs-transition="trigger")
+      1. Hidden element (0px × 0px, invisible)
+   2. Transition Element (data-hs-transition="element")
+      1. Full-screen overlay with animation
+      2. Attribute: data-hs-exit-time="0.5"
+      3. Attribute: data-hs-delay="0.3"
+
+### **What It Does**
+
+1. **Page load animation** - Clicks trigger on load to play entrance animation
+2. **Link interception** - Captures clicks on internal links
+3. **Exit animation** - Clicks trigger before navigation
+4. **Timed navigation** - Waits for exit animation to complete, then navigates
+5. **Back button handling** - Reloads page when using browser back button
+6. **Resize handling** - Hides transition element on window resize to prevent visual bugs
+7. **Session awareness** - Tracks first page load via sessionStorage
+
+### **When It Runs**
+
+* Auto-initializes on page load (unless `no-transition` attribute is present)
+* Waits for Webflow to be ready (`afterWebflowReady()`)
+* Adds 50ms delay after Webflow ready to ensure IX is fully loaded
+* Runs on every page in a multi-page site
+
+---
+
+## **Disabling Transitions**
+
+### **no-transition Attribute**
+
+Add `no-transition` attribute to the script tag to disable page transitions:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@hortonstudio/main@latest" no-transition></script>
+```
+
+**When to use:**
+- During development/testing
+- On sites where transitions cause issues
+- For specific pages where you don't want transitions
+
+**Result:** The transition module will not load, and pages will navigate normally without animations.
+
+---
+
+## **Interaction Requirements (IX3)**
+
+**CRITICAL:** Webflow interactions MUST be set up on the trigger element.
+
+**Triggers:**
+
+1. **Click trigger** on `[data-hs-transition="trigger"]`
+   1. First click: Play entrance animation
+   2. Second click: Play exit animation (or reverse)
+
+**Timeline (Entrance):**
+
+1. 0s: Transition element visible (covering page)
+2. 0s-0.5s: Fade out or slide out animation
+3. 0.5s: Transition element hidden
+
+**Timeline (Exit):**
+
+1. 0s: Transition element hidden
+2. 0s-0.5s: Fade in or slide in animation
+3. 0.5s: Transition element visible (covering page)
+
+**Important:** The `data-hs-exit-time` should match the exit animation duration.
+
+---
+
+## **Link Behavior**
+
+### **Links that trigger transitions:**
+
+- Internal links (same hostname)
+- Links without `target="_blank"`
+- Links without `#` hash in href
+- Links with valid `href` attribute
+
+### **Links that DON'T trigger transitions:**
+
+- External links (different domain)
+- Links with `target="_blank"`
+- Anchor links (`href="#section"`)
+- Links without `href` attribute
+- `mailto:` and `tel:` links
+
+---
+
+## **Fallback Script (Recommended)**
+
+Add this script to your site's `<head>` BEFORE the main script to prevent transition elements from blocking the page if the codebase fails to load:
+
+```html
+<script>
+// Prevent transition if codebase hasn't loaded
+new MutationObserver((m,o)=>{if(document.documentElement.classList.contains('w-mod-ix3')){if(!document.documentElement.classList.contains('hs-main'))document.querySelectorAll('[data-hs-transition="element"]').forEach(el=>el.remove());o.disconnect()}}).observe(document.documentElement,{attributes:true,attributeFilter:['class']})
+</script>
+```
+
+**What it does:**
+1. Waits for Webflow IX to load (`w-mod-ix3` class)
+2. Checks if main codebase loaded (`hs-main` class)
+3. If main codebase didn't load, removes all transition elements
+4. Prevents transition overlay from blocking page content
+
+**Why it's needed:** If the CDN fails or the script errors, the transition element could cover the entire page permanently, making the site unusable.
+
+---
+
+## **Usage Example**
+
+### **Basic Setup**
+
+```html
+<!-- Fallback script in <head> -->
+<script>
+new MutationObserver((m,o)=>{if(document.documentElement.classList.contains('w-mod-ix3')){if(!document.documentElement.classList.contains('hs-main'))document.querySelectorAll('[data-hs-transition="element"]').forEach(el=>el.remove());o.disconnect()}}).observe(document.documentElement,{attributes:true,attributeFilter:['class']})
+</script>
+
+<!-- Main script -->
+<script type="module" src="https://cdn.jsdelivr.net/npm/@hortonstudio/main@latest"></script>
+
+<!-- Transition wrapper in <body> -->
+<div class="page-transition">
+  <!-- Invisible trigger -->
+  <div data-hs-transition="trigger" style="width: 0; height: 0; opacity: 0;"></div>
+
+  <!-- Visual overlay with 0.5s exit time -->
+  <div data-hs-transition="element" data-hs-exit-time="0.5" style="position: fixed; top: 0; left: 0; width: 100vw; height: 100vh; background: black; z-index: 9999;">
+    <!-- Optional loading animation or logo -->
+  </div>
+</div>
+```
+
+### **With Custom Exit Time**
+
+```html
+<div data-hs-transition="element" data-hs-exit-time="1.2">
+  <!-- Longer transition: 1.2 seconds -->
+</div>
+```
+
+**Result:** JavaScript waits 1200ms after clicking the trigger before navigating to the new page.
+
+### **With Entrance Delay**
+
+```html
+<div data-hs-transition="element" data-hs-exit-time="0.5" data-hs-delay="0.3">
+  <!-- First page load: waits 300ms before entrance animation -->
+  <!-- Subsequent loads: instant entrance animation -->
+</div>
+```
+
+**Result:**
+- First visit to site: Waits 300ms, then triggers entrance animation
+- Navigating to other pages: Triggers entrance animation immediately
+
+---
+
+## **Session Storage**
+
+The system uses `sessionStorage` to track the first page load:
+
+**Key:** `transition-loaded`
+**Value:** `'true'`
+
+**Purpose:** Differentiates between initial site visit and subsequent page navigations. Used to determine whether to apply the entrance delay (`data-hs-delay`):
+- **First load:** Delay is applied before entrance animation
+- **Subsequent loads:** No delay, entrance animation triggers immediately
+
+---
+
+## **Resize Handling**
+
+When the browser window is resized:
+- The transition element is hidden (`display: none`)
+- Prevents visual bugs with fixed positioning during resize
+- Transition will work again on next navigation
+
+---
+
+## **Back Button Behavior**
+
+When using the browser back button:
+- Page is fully reloaded (not cached)
+- Ensures transition animations play correctly
+- Uses `window.onpageshow` event with `persisted` check
+
+---
+
+## **Key Attributes Summary**
+
+| Attribute | Purpose | Required On |
+| ----- | ----- | ----- |
+| `data-hs-transition="trigger"` | Animation trigger | Hidden trigger element |
+| `data-hs-transition="element"` | Visual transition overlay | Transition element |
+| `data-hs-exit-time="0.5"` | Exit duration in seconds | Transition element (optional) |
+| `data-hs-delay="0.3"` | First load entrance delay in seconds | Transition element (optional) |
+| `no-transition` | Disable transitions | Script tag (optional) |
+
+---
+
+## **Notes**
+
+1. **Auto-initializes** - Runs by default unless `no-transition` attribute is present
+2. **Webflow IX required** - Must have click interaction on trigger element
+3. **Exit time critical** - Should match your Webflow animation duration
+4. **Fallback script recommended** - Prevents site from being blocked if script fails
+5. **Session tracking** - Uses sessionStorage to track first load
+6. **Back button reloads** - Forces full page reload on back navigation
+7. **Resize hides transition** - Prevents visual bugs during window resize
+
+---
+
+## **Common Issues**
+
+**Transition element blocks entire page:**
+
+1. Ensure main script is loading correctly (check for `hs-main` class on `<html>`)
+2. Add the fallback script to `<head>` to auto-remove transition on failure
+3. Check browser console for script errors
+
+**Page navigates without exit animation:**
+
+1. Verify `data-hs-exit-time` attribute is set on transition element
+2. Check that Webflow IX click interaction is on trigger element
+3. Ensure exit animation is playing when trigger is clicked second time
+
+**Exit animation is cut short:**
+
+1. Increase `data-hs-exit-time` to match animation duration
+2. Test animation by manually clicking trigger element
+3. Verify Webflow IX timeline duration matches exit time
+
+**Entrance animation not playing:**
+
+1. Check that Webflow IX is loaded (`w-mod-ix3` class on `<html>`)
+2. Verify 50ms delay is sufficient (can be timing issue)
+3. Ensure trigger element exists before script runs
+
+**Links not triggering transitions:**
+
+1. Check link is internal (same hostname)
+2. Verify link doesn't have `target="_blank"`
+3. Ensure href doesn't contain `#` hash
+4. Check that click event listener is attached (inspect in debugger)
+
+**Transition shows on window resize:**
+
+1. This is expected - resize handler hides it with `display: none`
+2. Will work again on next navigation
+3. Check that resize handler is attached correctly
+
+**Back button doesn't work:**
+
+1. Page should reload when using back button
+2. Check that `onpageshow` handler is attached
+3. Verify `event.persisted` is true when using back button

package/autoInit/{transition.js → transition/transition.js}

@@ -33,6 +33,10 @@ export async function init() {
     const exitTimeAttr = transitionElement.getAttribute('data-hs-exit-time');
     const exitTime = exitTimeAttr ? parseFloat(exitTimeAttr) * 1000 : 0;
 
+    // Get delay time for first load from data attribute (in seconds)
+    const delayAttr = transitionElement.getAttribute('data-hs-delay');
+    const delayTime = delayAttr ? parseFloat(delayAttr) * 1000 : 0;
+
     // Page Load - Trigger entrance animation
     // Check if this is the first page load of the session
     const isFirstLoad = !sessionStorage.getItem('transition-loaded');
@@ -43,9 +47,16 @@ export async function init() {
       });
     };
 
-    triggerAnimation();
-    if (isFirstLoad) {
+    // If first load and delay is set, wait before triggering
+    if (isFirstLoad && delayTime > 0) {
+      setTimeout(triggerAnimation, delayTime);
       sessionStorage.setItem('transition-loaded', 'true');
+    } else {
+      // Subsequent loads or no delay: trigger immediately
+      triggerAnimation();
+      if (isFirstLoad) {
+        sessionStorage.setItem('transition-loaded', 'true');
+      }
     }
 
     // On Link Click