@hortonstudio/main 1.9.20 → 1.9.22

package/src/modules/default/functions/smooth-scroll/README.md

@@ -1,417 +0,0 @@
-# **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
-
----
-
-## **v2.0.0 Improvements**
-
-### **JSON Config System**
-
-- Added config.js with module metadata
-- Future-proof: Ready for configuration options if needed
-- Note: This module auto-detects anchor links and requires no data attributes
-
-### **Barba.js / SPA Compatibility**
-
-The smooth-scroll system is fully compatible with Barba.js and other SPA frameworks:
-
-- Proper cleanup on destroy (removes event listeners, restores CSS scroll behavior)
-- Fresh initialization on reinitialize
-- Works on all anchor links on new pages
-- Works like fresh page load on new DOM
-
----
-
-## **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/src/modules/default/functions/smooth-scroll/smooth-scroll.ts

@@ -1,115 +0,0 @@
-import { getGsap, prefersReducedMotion } from '@utils';
-
-export async function init() {
-  // Store event handlers for cleanup
-  let clickHandler = null;
-  let keydownHandler = null;
-
-  // Disable Webflow's native scroll behavior (jQuery-based)
-  // This runs immediately since default module already waits for IX3
-  if (typeof $ !== 'undefined') {
-    $(document).off('click.wf-scroll');
-  }
-
-  // Disable CSS smooth scrolling
-  document.documentElement.style.scrollBehavior = 'auto';
-  document.body.style.scrollBehavior = 'auto';
-
-  function getScrollOffset() {
-    const offsetValue = getComputedStyle(document.documentElement)
-      .getPropertyValue('--misc--scroll-offset')
-      .trim();
-    return parseInt(offsetValue) || 0;
-  }
-
-  // Smooth scroll to element with offset
-  function scrollToElement(target, offset = 0) {
-    if (!target) return;
-
-    const gsapLib = getGsap('smooth-scroll', false);
-
-    // Skip animation if user prefers reduced motion or GSAP not available
-    if (prefersReducedMotion() || !gsapLib) {
-      const targetPosition = target.getBoundingClientRect().top + window.scrollY - offset;
-      window.scrollTo(0, targetPosition);
-      target.setAttribute('tabindex', '-1');
-      target.focus({ preventScroll: true });
-      return;
-    }
-
-    gsapLib.gsap.to(window, {
-      duration: 1,
-      scrollTo: {
-        y: target,
-        offsetY: offset,
-      },
-      ease: 'power2.out',
-      onComplete: function () {
-        target.setAttribute('tabindex', '-1');
-        target.focus({ preventScroll: true });
-      },
-    });
-  }
-
-  function handleAnchorActivation(e) {
-    const link = e.target.closest('a[href^="#"]');
-    if (!link) return;
-
-    const href = link.getAttribute('href');
-    if (!href || href === '#') return;
-
-    const targetId = href.substring(1);
-    const targetElement = document.getElementById(targetId);
-
-    if (targetElement) {
-      e.preventDefault();
-      if (history.replaceState) {
-        history.replaceState(null, null, `#${targetElement.id}`);
-      }
-      const offset = getScrollOffset();
-      scrollToElement(targetElement, offset);
-    }
-  }
-
-  // Handle anchor link clicks and keyboard activation
-  function handleAnchorClicks() {
-    clickHandler = handleAnchorActivation;
-    keydownHandler = function (e) {
-      if (e.key === 'Enter' || e.key === ' ') {
-        handleAnchorActivation(e);
-      }
-    };
-
-    document.addEventListener('click', clickHandler);
-    document.addEventListener('keydown', keydownHandler);
-  }
-
-  // Initialize anchor link handling
-  handleAnchorClicks();
-
-  // Mock scroll to trigger scroll-based animations
-  const gsapLib = getGsap('smooth-scroll', false);
-  if (gsapLib && document.body.scrollHeight > window.innerHeight) {
-    gsapLib.gsap.set(window, { scrollTo: 1 });
-    gsapLib.gsap.set(window, { scrollTo: 0 });
-  }
-
-  return {
-    result: 'autoInit-smooth-scroll initialized',
-    destroy: () => {
-      // Remove event listeners
-      if (clickHandler) {
-        document.removeEventListener('click', clickHandler);
-        clickHandler = null;
-      }
-      if (keydownHandler) {
-        document.removeEventListener('keydown', keydownHandler);
-        keydownHandler = null;
-      }
-
-      // Re-enable CSS smooth scrolling
-      document.documentElement.style.scrollBehavior = '';
-      document.body.style.scrollBehavior = '';
-    },
-  };
-}