@hortonstudio/main 1.9.10 → 1.9.20

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

@@ -0,0 +1,213 @@
+# **Normalize Function Documentation**
+
+## **Overview**
+
+The normalize function ensures clickable wrappers have a consistent DOM structure by keeping either a `<button>` or `<a>` element based on href validity.
+
+**Problem**: Designers include both `<button>` and `<a>` elements in wrappers, but only one should exist based on whether there's a valid link destination.
+
+**Solution**: Automatically remove the unnecessary element, keeping the semantically correct one.
+
+---
+
+## **How It Works**
+
+### **Detection**
+
+1. Finds all elements with `data-hs-clickable="wrapper"`
+2. Checks for direct children: `<button>` and `<a>`
+3. Only processes wrappers that have BOTH elements
+
+### **Logic**
+
+```
+IF <a> has valid href (not empty, not "#")
+  → Keep <a>, remove <button>
+ELSE
+  → Keep <button>, remove <a>
+```
+
+### **Normalization**
+
+- Kept element gets `data-hs-clickable="button"` attribute (if it doesn't already have it)
+- Other element is removed from DOM
+- Other modules can reliably find `[data-hs-clickable="button"]`
+- Won't break if kept element already has the attribute
+
+---
+
+## **HTML Structure**
+
+### **Before Normalize**
+
+```html
+<div data-hs-clickable="wrapper">
+  <button class="card">
+    <span>Read More</span>
+  </button>
+  <a href="/blog/post-1" class="card">
+    <span>Read More</span>
+  </a>
+</div>
+```
+
+### **After Normalize** (valid href)
+
+```html
+<div data-hs-clickable="wrapper">
+  <a href="/blog/post-1" class="card" data-hs-clickable="button">
+    <span>Read More</span>
+  </a>
+</div>
+```
+
+### **After Normalize** (no valid href)
+
+```html
+<div data-hs-clickable="wrapper">
+  <button class="card" data-hs-clickable="button">
+    <span>Read More</span>
+  </button>
+</div>
+```
+
+---
+
+## **CMS Integration**
+
+Perfect for Webflow CMS where link availability varies:
+
+```html
+<!-- Blog post with link -->
+<div data-hs-clickable="wrapper">
+  <button>Read More</button>
+  <a href="{{wf-link}}">Read More</a>
+  <!-- Valid CMS link -->
+</div>
+
+<!-- Blog post without link (draft, disabled, etc.) -->
+<div data-hs-clickable="wrapper">
+  <button>Read More</button>
+  <a href="">Read More</a>
+  <!-- Empty CMS link → button kept -->
+</div>
+```
+
+---
+
+## **Performance**
+
+- **Speed**: ~0.3-0.5ms per wrapper (tested with 100 elements: ~30-50ms total)
+- **DOM Operations**: Single `remove()` call per wrapper
+- **Selector**: Uses `:scope >` for direct children only (fast)
+- **Phase**: Runs in Phase 1 (normalize) before visual changes
+
+---
+
+## **Barba.js / SPA Compatibility**
+
+### **On Page Transition**
+
+1. `destroy()` called - removes `data-hs-clickable="button"` attributes
+2. New page DOM loads with both button and link again
+3. `init()` runs - normalizes new DOM
+4. Other modules find normalized structure
+
+### **Cleanup Behavior**
+
+- Cannot restore deleted elements (would require cloning before removal)
+- Only removes the attribute if it was added during normalization (won't remove if element already had it)
+- Safe for page transitions - new DOM has original structure
+
+---
+
+## **Edge Cases**
+
+### **Missing Elements**
+
+```html
+<!-- Only button → skipped (no normalization needed) -->
+<div data-hs-clickable="wrapper">
+  <button>Click Me</button>
+</div>
+
+<!-- Only link → skipped -->
+<div data-hs-clickable="wrapper">
+  <a href="/page">Click Me</a>
+</div>
+```
+
+### **Invalid Hrefs**
+
+All treated as invalid, button kept:
+
+- `href=""`
+- `href="#"`
+- `href` attribute missing
+
+### **Valid Hrefs**
+
+All treated as valid, link kept:
+
+- `href="/page"`
+- `href="https://example.com"`
+- `href="#section"` (anchor links are valid)
+- `href="javascript:void(0)"` (technically valid, link kept)
+
+---
+
+## **Module Integration**
+
+Other modules can rely on normalized structure:
+
+```javascript
+// Always finds the kept element (button or link)
+const clickables = document.querySelectorAll('[data-hs-clickable="button"]');
+
+clickables.forEach((element) => {
+  // Could be <button> or <a>, both work the same
+  element.addEventListener('click', handleClick);
+});
+```
+
+---
+
+## **Technical Details**
+
+### **Selectors Used**
+
+- Wrapper: `[data-hs-clickable='wrapper']`
+- Direct children: `:scope > button`, `:scope > a`
+- Added attribute: `data-hs-clickable="button"`
+
+### **Cleanup Tracking**
+
+```javascript
+cleanup.processedWrappers = [
+  {
+    wrapper: HTMLElement, // The wrapper div
+    keptElement: HTMLElement, // Button or link that was kept
+    wasLink: Boolean, // True if link was kept
+    addedAttribute: Boolean, // True if we added the attribute (vs already existed)
+  },
+];
+```
+
+### **Return Value**
+
+```javascript
+{
+  result: "normalize processed 42 wrappers",
+  destroy: Function
+}
+```
+
+---
+
+## **Notes**
+
+- Runs in Phase 1 (normalize) with 1s timeout
+- Uses global config for selector consistency
+- Non-destructive: skips wrappers that don't need normalization
+- Fast: querySelector with `:scope` limits search depth
+- Reliable: Works even if other modules fail

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

@@ -0,0 +1,68 @@
+import { globalConfig, querySelectorAll } from '@utils';
+
+export async function init(config) {
+  const cleanup = {
+    processedWrappers: [],
+  };
+
+  // Find all clickable wrappers using global clickable config
+  const wrappers = querySelectorAll(globalConfig.clickable, 'wrapper');
+
+  wrappers.forEach((wrapper) => {
+    // Find direct button and link children
+    const button = wrapper.querySelector(':scope > button');
+    const link = wrapper.querySelector(':scope > a');
+
+    // Only process if both exist
+    if (!button || !link) return;
+
+    // Check if link has valid href
+    const href = link.getAttribute('href');
+    const hasValidHref = href && href !== '' && href !== '#';
+
+    let keptElement, removedElement;
+
+    if (hasValidHref) {
+      // Keep link, remove button
+      keptElement = link;
+      removedElement = button;
+    } else {
+      // Keep button, remove link
+      keptElement = button;
+      removedElement = link;
+    }
+
+    // Check if kept element already has data-hs-clickable="button"
+    const hadAttribute = keptElement.getAttribute('data-hs-clickable') === 'button';
+
+    // Ensure kept element has data-hs-clickable="button"
+    if (!hadAttribute) {
+      keptElement.setAttribute('data-hs-clickable', 'button');
+    }
+
+    // Remove the other element
+    removedElement.remove();
+
+    // Track for cleanup
+    cleanup.processedWrappers.push({
+      wrapper,
+      keptElement,
+      wasLink: keptElement === link,
+      addedAttribute: !hadAttribute,
+    });
+  });
+
+  return {
+    result: `normalize processed ${cleanup.processedWrappers.length} wrappers`,
+    destroy: () => {
+      // On destroy, we can't restore deleted elements
+      // Only remove the attribute if we added it
+      cleanup.processedWrappers.forEach(({ keptElement, addedAttribute }) => {
+        if (addedAttribute) {
+          keptElement.removeAttribute('data-hs-clickable');
+        }
+      });
+      cleanup.processedWrappers.length = 0;
+    },
+  };
+}

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

@@ -0,0 +1,405 @@
+# **Dupe Function Documentation**
+
+## **Overview**
+
+The dupe function automatically duplicates DOM elements or their children, useful for patterns, decorations, and marquee effects.
+
+**Problem**: Designers need multiple copies of elements for visual effects (marquees, patterns, decorative elements).
+
+**Solution**: Automatically clone elements based on simple attributes, runs after clickable normalization.
+
+---
+
+## **Modes**
+
+### **1. Child Mode** (`data-hs-dupe="child"`)
+
+Duplicates the first direct child element as siblings.
+
+```html
+<!-- Before -->
+<div data-hs-dupe="child">
+  <svg class="icon">...</svg>
+</div>
+
+<!-- After -->
+<div data-hs-dupe="child">
+  <svg class="icon">...</svg>
+  <svg class="icon">...</svg>
+  <!-- cloned -->
+</div>
+```
+
+**Use cases:**
+
+- Icon duplication for visual effects
+- Pattern backgrounds
+- Decorative elements
+
+### **2. Self Mode** (`data-hs-dupe="self"`)
+
+Duplicates the element itself as next siblings.
+
+```html
+<!-- Before -->
+<div class="container">
+  <div data-hs-dupe="self" class="item">Content</div>
+</div>
+
+<!-- After -->
+<div class="container">
+  <div data-hs-dupe="self" class="item">Content</div>
+  <div class="item">Content</div>
+  <!-- cloned, attributes removed -->
+</div>
+```
+
+**Use cases:**
+
+- Marquee items (duplicate cards/logos)
+- Loading skeletons
+- Grid patterns
+
+---
+
+## **Count Attribute**
+
+Control how many duplicates are created with `data-hs-dupe-count`.
+
+**Default:** 1 duplicate (2 total elements)
+
+### **Examples**
+
+```html
+<!-- Create 5 duplicates (6 total) -->
+<div data-hs-dupe="child" data-hs-dupe-count="5">
+  <img src="logo.svg" />
+</div>
+<!-- Result: 1 original + 5 clones = 6 images -->
+
+<!-- Marquee with 10 items -->
+<div class="marquee">
+  <div data-hs-dupe="self" data-hs-dupe-count="10">
+    <span>Scrolling Text</span>
+  </div>
+</div>
+<!-- Result: 11 total items for seamless loop -->
+```
+
+### **Maximum Limit: 20**
+
+Count is capped at 20 to prevent performance issues.
+
+```html
+<div data-hs-dupe="child" data-hs-dupe-count="50">
+  <div>Item</div>
+</div>
+<!-- Console: "[dupe] Count of 50 exceeds maximum of 20. Capping at 20." -->
+<!-- Result: 1 original + 20 clones = 21 elements -->
+```
+
+---
+
+## **Modifiers**
+
+Customize cloned elements with optional modifier attributes.
+
+### **1. Hidden Modifier** (`data-hs-dupe-hidden`)
+
+Adds `aria-hidden="true"` to clones for accessibility.
+
+**Use case:** Duplicate text for visual animation effects while keeping screen readers focused on the original.
+
+```html
+<button data-hs-dupe="child" data-hs-dupe-hidden>
+  <span>Next</span>
+</button>
+<!-- Result: Clone gets aria-hidden="true" -->
+<button data-hs-dupe="child" data-hs-dupe-hidden>
+  <span>Next</span>
+  <span aria-hidden="true">Next</span>
+  <!-- Cloned, hidden from screen readers -->
+</button>
+```
+
+### **2. No-Select Modifier** (`data-hs-dupe-no-select`)
+
+Adds `user-select: none` to clones to prevent text selection and copying.
+
+**Use case:** Animated text effects where duplicate text shouldn't be selectable/copyable.
+
+```html
+<div data-hs-dupe="child" data-hs-dupe-no-select>
+  <span>Animated Text</span>
+</div>
+<!-- Result: Clone has inline style user-select: none -->
+<div data-hs-dupe="child" data-hs-dupe-no-select>
+  <span>Animated Text</span>
+  <span style="user-select: none; -webkit-user-select: none; -ms-user-select: none;"
+    >Animated Text</span
+  >
+</div>
+```
+
+### **3. Combining Modifiers**
+
+Use both modifiers together for complete isolation of clones.
+
+```html
+<button data-hs-dupe="child" data-hs-dupe-count="3" data-hs-dupe-hidden data-hs-dupe-no-select>
+  <span class="text">Click Me</span>
+</button>
+<!-- Result: 3 clones, all with aria-hidden and user-select: none -->
+```
+
+**Perfect for:**
+
+- Text animation effects
+- Decorative duplicate elements
+- Loading animations
+- Visual-only duplicates
+
+---
+
+## **Execution Order**
+
+Dupe runs **after clickable** in the normalize phase:
+
+1. **Clickable** normalizes button/link structure
+2. **Dupe** duplicates the normalized elements
+
+### **Example: Clickable + Dupe**
+
+```html
+<!-- Before normalize phase -->
+<div data-hs-clickable="wrapper">
+  <button>Click</button>
+  <a href="/page">Click</a>
+</div>
+
+<!-- After clickable (keeps link, removes button) -->
+<div data-hs-clickable="wrapper">
+  <a href="/page" data-hs-clickable="button">Click</a>
+</div>
+
+<!-- Then wrap for duplication -->
+<div data-hs-dupe="child" data-hs-dupe-count="3">
+  <div data-hs-clickable="wrapper">
+    <a href="/page" data-hs-clickable="button">Click</a>
+  </div>
+</div>
+
+<!-- After dupe -->
+<div data-hs-dupe="child" data-hs-dupe-count="3">
+  <div data-hs-clickable="wrapper">
+    <a href="/page" data-hs-clickable="button">Click</a>
+  </div>
+  <div data-hs-clickable="wrapper">
+    <a href="/page" data-hs-clickable="button">Click</a>
+  </div>
+  <div data-hs-clickable="wrapper">
+    <a href="/page" data-hs-clickable="button">Click</a>
+  </div>
+  <div data-hs-clickable="wrapper">
+    <a href="/page" data-hs-clickable="button">Click</a>
+  </div>
+</div>
+<!-- Result: 4 normalized, clickable links ready for marquee -->
+```
+
+---
+
+## **Performance**
+
+- **Speed**: ~0.1-0.2ms per element duplication
+- **Count of 20**: ~2-4ms total
+- **DOM Operations**: `cloneNode(true)` + `appendChild()` per duplicate
+- **Phase**: Runs in Phase 1 (normalize) after clickable
+
+**Benchmark** (100 elements with count=5):
+
+- Total time: ~50-100ms
+- No noticeable performance impact
+
+---
+
+## **Barba.js / SPA Compatibility**
+
+### **On Page Transition**
+
+1. `destroy()` called - removes all cloned elements
+2. New page DOM loads with original structure
+3. `init()` runs - duplicates elements again on new DOM
+
+### **Cleanup Behavior**
+
+- Removes all cloned elements from DOM
+- Original elements remain untouched
+- Attributes stay on original elements
+- Safe for page transitions
+
+### **Self Mode Cleanup**
+
+- Cloned elements have `data-hs-dupe` attributes removed
+- Only original element retains the attribute
+- Clones are fully removed on destroy
+
+---
+
+## **Edge Cases**
+
+### **No Child Found (child mode)**
+
+```html
+<div data-hs-dupe="child">
+  <!-- Empty, no children -->
+</div>
+<!-- Console: "[dupe] No child element found to duplicate" -->
+<!-- No duplication occurs -->
+```
+
+### **No Parent (self mode)**
+
+```html
+<!-- Orphan element, not in DOM -->
+<div data-hs-dupe="self">Content</div>
+<!-- Console: "[dupe] Element has no parent, cannot duplicate self" -->
+<!-- No duplication occurs -->
+```
+
+### **Invalid Mode**
+
+```html
+<div data-hs-dupe="invalid">
+  <div>Item</div>
+</div>
+<!-- Console: "[dupe] Invalid mode. Use 'child' or 'self'" -->
+<!-- No duplication occurs -->
+```
+
+### **Invalid Count**
+
+```html
+<!-- Non-numeric -->
+<div data-hs-dupe="child" data-hs-dupe-count="abc">
+  <div>Item</div>
+</div>
+<!-- Console: "[dupe] Invalid count, using default of 1" -->
+<!-- Creates 1 duplicate -->
+
+<!-- Negative or zero -->
+<div data-hs-dupe="child" data-hs-dupe-count="-5">
+  <div>Item</div>
+</div>
+<!-- Console: "[dupe] Invalid count, using default of 1" -->
+<!-- Creates 1 duplicate -->
+```
+
+---
+
+## **Use Cases**
+
+### **1. Marquee with CMS Items**
+
+```html
+<div class="marquee-wrapper">
+  <div data-hs-dupe="self" data-hs-dupe-count="5" class="marquee-item">
+    <!-- CMS-generated card -->
+  </div>
+</div>
+<!-- Creates 6 items for seamless infinite scroll -->
+```
+
+### **2. Icon Pattern Background**
+
+```html
+<div class="pattern" data-hs-dupe="child" data-hs-dupe-count="12">
+  <svg class="dot">...</svg>
+</div>
+<!-- Creates 13 dots in a pattern -->
+```
+
+### **3. Loading Skeleton**
+
+```html
+<div class="skeleton-list">
+  <div data-hs-dupe="self" data-hs-dupe-count="4" class="skeleton-item">
+    <div class="skeleton-line"></div>
+  </div>
+</div>
+<!-- Creates 5 skeleton items while loading -->
+```
+
+### **4. Button Icon Duplication**
+
+```html
+<button data-hs-dupe="child">
+  <svg class="arrow">→</svg>
+  <span>Next</span>
+</button>
+<!-- Duplicates arrow for visual effect -->
+<button data-hs-dupe="child">
+  <svg class="arrow">→</svg>
+  <svg class="arrow">→</svg>
+  <!-- cloned -->
+  <span>Next</span>
+</button>
+```
+
+---
+
+## **Technical Details**
+
+### **Attributes Used**
+
+- Element: `data-hs-dupe` (value: "child" or "self")
+- Count: `data-hs-dupe-count` (integer, default: 1, max: 20)
+
+### **Cleanup Tracking**
+
+```javascript
+cleanup.processedElements = [
+  {
+    element: HTMLElement, // Original element with data-hs-dupe
+    mode: String, // "child" or "self"
+    clones: [HTMLElement], // Array of cloned elements
+  },
+];
+```
+
+### **Return Value**
+
+```javascript
+{
+  result: "dupe processed 42 elements",
+  destroy: Function
+}
+```
+
+---
+
+## **Integration with Other Modules**
+
+### **Works After Clickable**
+
+- Clickable normalizes DOM structure first
+- Dupe then duplicates the normalized result
+- Ensures duplicates have consistent structure
+
+### **Works Before Visual-DOM**
+
+- Structure module (marquee, etc.) finds duplicated elements
+- All duplicates are present before visual animations start
+- No flash of incomplete content
+
+---
+
+## **Notes**
+
+- Runs in Phase 1 (normalize) after clickable
+- Maximum 20 duplicates per element (performance protection)
+- Deep clone with `cloneNode(true)` - includes all children
+- Self mode removes dupe attributes from clones
+- Child mode leaves original structure intact
+- Compatible with Barba.js page transitions
+- Fast: <0.2ms per duplication operation