@hortonstudio/main 1.9.6 → 1.9.7

package/autoInit/button/README.md

@@ -0,0 +1,122 @@
+# **Button Icon System Documentation**
+
+## **Overview**
+
+The button icon system automatically clones icons from a "main" slot to a "placeholder" slot within button wrappers. This allows for consistent icon duplication for animation or styling purposes.
+
+**Note:** This functionality is **already set up** in the Global / Button components. This documentation is for custom button implementations that require this icon cloning behavior.
+
+---
+
+## **Button Icon Cloning**
+
+### **Required Elements**
+
+**Button Wrapper** *(main wrapper of the button)*
+
+* data-site-button="wrapper"
+
+**Icon Wrapper** *(wraps both main and placeholder icons)*
+
+* data-site-button-icon="wrapper"
+
+**Main Icon** *(the source icon to be cloned)*
+
+* data-site-button-icon="main"
+  * Contains: `[data-site-icon="slot"]` (the actual icon element)
+
+**Placeholder Icon** *(the destination for the cloned icon)*
+
+* data-site-button-icon="placeholder"
+  * Contains: `[data-site-icon="slot"]` (will be replaced with cloned icon)
+
+**Typical element layout:**
+
+1. Button Wrapper (data-site-button="wrapper")
+   1. Button Content
+      1. Icon Wrapper (data-site-button-icon="wrapper")
+         1. Main Icon (data-site-button-icon="main")
+            1. Icon Slot (data-site-icon="slot")
+               1. SVG or Icon Element
+         2. Placeholder Icon (data-site-button-icon="placeholder")
+            1. Icon Slot (data-site-icon="slot")
+               1. Empty (will be replaced)
+
+### **What It Does**
+
+1. **Finds all button wrappers** with `[data-site-button="wrapper"]`
+2. **Checks for icon wrapper** - If no `[data-site-button-icon="wrapper"]`, skips button
+3. **Clones main icon** - Gets first `[data-site-icon="slot"]` inside main icon
+4. **Replaces placeholder** - Swaps placeholder slot with cloned main slot
+
+### **When It Runs**
+
+* Runs once on page load
+* Runs again on Barba.js page transitions (via `reinitialize()`)
+* No ongoing monitoring or event listeners
+
+### **Notes**
+
+1. **Global / Button components** already include this setup by default
+   * Use this documentation only for custom button implementations
+2. If any required element is missing, that button is skipped (no errors)
+3. The system works independently for each button on the page
+4. No cleanup needed - purely DOM manipulation
+
+---
+
+## **Example Structure**
+
+```html
+<div data-site-button="wrapper">
+  <div data-site-button-icon="wrapper">
+    <!-- Main icon (source) -->
+    <div data-site-button-icon="main">
+      <div data-site-icon="slot">
+        <svg><!-- Your icon --></svg>
+      </div>
+    </div>
+
+    <!-- Placeholder icon (destination) -->
+    <div data-site-button-icon="placeholder">
+      <div data-site-icon="slot">
+        <!-- This entire element gets replaced with cloned main slot -->
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+**Result:** The placeholder slot is replaced with an exact clone of the main slot (including the SVG).
+
+---
+
+## **Key Attributes Summary**
+
+| Attribute | Purpose | Required On |
+| ----- | ----- | ----- |
+| `data-site-button="wrapper"` | Button container | Wrapper div |
+| `data-site-button-icon="wrapper"` | Icon container | Icon wrapper div |
+| `data-site-button-icon="main"` | Source icon | Main icon div |
+| `data-site-button-icon="placeholder"` | Clone destination | Placeholder icon div |
+| `data-site-icon="slot"` | Icon slot element | Both main and placeholder |
+
+---
+
+## **Common Issues**
+
+**Icons not cloning:**
+
+1. Verify all required attributes are present
+2. Check that `[data-site-icon="slot"]` is the **first child** of both main and placeholder
+3. Ensure button wrapper has `[data-site-button="wrapper"]`
+
+**Icons not updating after Barba transition:**
+
+1. Ensure `window.hsmain.reinitialize()` is called after transition
+2. Check that new page content has proper button structure
+
+**Multiple buttons on page:**
+
+1. Each button works independently - if one fails, others continue
+2. Check console for warnings about missing elements

package/autoInit/counter/README.md

@@ -0,0 +1,274 @@
+# **Counter System Documentation**
+
+## **Overview**
+
+The counter system provides animated number counting that triggers when the counter scrolls into view. It supports prefixes, suffixes, decimals, and automatically handles accessibility by combining all text content into an aria-label.
+
+---
+
+## **Counter Setup**
+
+### **Required Elements**
+
+**Counter Wrapper** *(main wrapper of the counter)*
+
+* data-hs-counter="wrapper"
+
+**Counter Number** *(the number element to animate)*
+
+* data-hs-anim="counter"
+  * Contains the target number with optional prefix/suffix (e.g., "20+", "$1,500", "99.9%")
+
+**Typical element layout:**
+
+1. Counter Wrapper (data-hs-counter="wrapper")
+   1. Counter Number (data-hs-anim="counter")
+      1. Text: "20+"
+   2. Description Text (optional)
+      1. Text: "Years of Experience"
+
+### **What It Does**
+
+1. **Parses numbers** - Extracts prefix, number, and suffix from counter text
+2. **Scroll trigger** - Uses IntersectionObserver to detect when counter enters viewport
+3. **Animates count** - Counts from 0 to target number with easeOutQuart easing
+4. **Accessibility** - Combines ALL text within wrapper into aria-label (e.g., "20+ Years of Experience")
+5. **Respects motion preferences** - Skips animation if user has `prefers-reduced-motion` enabled
+
+### **When It Runs**
+
+* Runs once on page load to set up observers
+* Triggers animation when counter scrolls into view (threshold: 0)
+* Each counter only animates once (tracks with `data-animated="true"`)
+* Runs again on Barba.js page transitions (via `reinitialize()`)
+
+---
+
+## **Number Formats**
+
+### **Supported Formats**
+
+The counter automatically detects and preserves:
+
+**Prefix:**
+```
+$1000    � Counts from $0 to $1000
++500     � Counts from +0 to +500
+```
+
+**Suffix:**
+```
+100%     � Counts from 0% to 100%
+50+      � Counts from 0+ to 50+
+1000K    � Counts from 0K to 1000K
+```
+
+**Decimals:**
+```
+99.9     � Counts from 0.0 to 99.9 (preserves 1 decimal)
+3.14159  � Counts from 0.00000 to 3.14159 (preserves 5 decimals)
+```
+
+**Combined:**
+```
+$99.99   � Counts from $0.00 to $99.99
+50.5%    � Counts from 0.0% to 50.5%
+```
+
+---
+
+## **Accessibility**
+
+### **Automatic ARIA Setup**
+
+For each counter wrapper, the system:
+
+1. **Combines all text** - Uses TreeWalker to find all text nodes within wrapper
+2. **Creates aria-label** - Joins text with spaces (e.g., "20+ Years of Experience")
+3. **Sets role** - Adds `role="img"` to wrapper
+4. **Hides children** - Sets `aria-hidden="true"` on all descendant elements
+
+### **Example**
+
+```html
+<!-- Before JS runs -->
+<div data-hs-counter="wrapper">
+  <div data-hs-anim="counter">20+</div>
+  <div>Years of Experience</div>
+</div>
+
+<!-- After JS runs -->
+<div data-hs-counter="wrapper" aria-label="20+ Years of Experience" role="img">
+  <div data-hs-anim="counter" aria-hidden="true">20+</div>
+  <div aria-hidden="true">Years of Experience</div>
+</div>
+```
+
+Screen readers announce: "20+ Years of Experience"
+
+---
+
+## **Usage Examples**
+
+### **Basic Counter**
+
+```html
+<div data-hs-counter="wrapper">
+  <div data-hs-anim="counter">1000</div>
+</div>
+```
+
+**Result:** Counts from 0 to 1000 when scrolled into view
+**aria-label:** "1000"
+
+### **Counter with Description**
+
+```html
+<div data-hs-counter="wrapper">
+  <div data-hs-anim="counter">50+</div>
+  <p>Projects Completed</p>
+</div>
+```
+
+**Result:** Counts from 0+ to 50+
+**aria-label:** "50+ Projects Completed"
+
+### **Currency Counter**
+
+```html
+<div data-hs-counter="wrapper">
+  <div data-hs-anim="counter">$99.99</div>
+  <p>Starting Price</p>
+</div>
+```
+
+**Result:** Counts from $0.00 to $99.99
+**aria-label:** "$99.99 Starting Price"
+
+### **Percentage Counter**
+
+```html
+<div data-hs-counter="wrapper">
+  <div data-hs-anim="counter">99.9%</div>
+  <p>Uptime Guarantee</p>
+</div>
+```
+
+**Result:** Counts from 0.0% to 99.9%
+**aria-label:** "99.9% Uptime Guarantee"
+
+---
+
+## **Configuration**
+
+### **Default Settings**
+
+```javascript
+{
+  duration: 3000  // Animation duration in milliseconds
+}
+```
+
+### **Updating Config**
+
+```javascript
+window.hsmain.counter.updateConfig({
+  duration: 2000  // Faster animation
+});
+```
+
+**Note:** Config changes only affect counters that haven't animated yet.
+
+---
+
+## **API Methods**
+
+### **Trigger Animation Manually**
+
+```javascript
+window.hsmain.counter.triggerAnimation('[data-hs-counter="wrapper"]');
+```
+
+Manually triggers animation for a specific counter (bypasses scroll detection).
+
+### **Reset All Counters**
+
+```javascript
+window.hsmain.counter.reset();
+```
+
+Resets all counters to original state and re-enables scroll triggers.
+
+### **Access Counter Elements**
+
+```javascript
+window.hsmain.counter.counters
+```
+
+Returns array of all counter wrapper elements.
+
+---
+
+## **Animation Behavior**
+
+### **Easing Function**
+
+Uses **easeOutQuart** for smooth deceleration:
+- Starts fast
+- Slows down as it approaches target
+- Creates natural counting effect
+
+### **Reduced Motion**
+
+If user has `prefers-reduced-motion: reduce` enabled:
+- Skips animation entirely
+- Shows final number immediately
+- Respects user accessibility preferences
+
+---
+
+## **Key Attributes Summary**
+
+| Attribute | Purpose | Required On |
+| ----- | ----- | ----- |
+| `data-hs-counter="wrapper"` | Counter container | Wrapper div |
+| `data-hs-anim="counter"` | Number to animate | Number element |
+
+---
+
+## **Notes**
+
+1. **One-time animation** - Each counter animates only once when first scrolled into view
+2. **IntersectionObserver** - Uses `threshold: 0` (triggers as soon as any part is visible)
+3. **Original text preserved** - Stores original value in `data-hs-original` attribute
+4. **Barba.js compatible** - Automatically reinitializes on page transitions
+5. **No visual component** - Works with any styling, just handles number animation and a11y
+
+---
+
+## **Common Issues**
+
+**Counter not animating:**
+
+1. Verify `data-hs-counter="wrapper"` is on container element
+2. Check that `data-hs-anim="counter"` is on number element
+3. Ensure number element contains parseable number
+4. Check if `prefers-reduced-motion` is enabled (animation skips)
+
+**Wrong number format:**
+
+1. Counter auto-detects prefix/suffix - ensure format is: `[prefix][number][suffix]`
+2. Decimals are auto-detected from original number
+3. Use dot (.) for decimal separator, not comma
+
+**Aria-label missing text:**
+
+1. Ensure all text is within `[data-hs-counter="wrapper"]`
+2. Check that text nodes have actual content (not just whitespace)
+3. Verify elements aren't hidden with `display: none` when script runs
+
+**Counter animates multiple times:**
+
+1. This shouldn't happen - check if `reset()` is being called unintentionally
+2. Verify `data-animated` attribute is being set correctly
+3. Check for multiple script instances running

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

@@ -84,12 +84,27 @@ export function init() {
     const statsElements = document.querySelectorAll('[data-hs-counter="wrapper"]');
 
     statsElements.forEach((element) => {
-      const numberElement = element.querySelector('[data-hs-anim="counter"]');
-      const originalText = numberElement.getAttribute("data-hs-original");
-      
-      element.setAttribute("aria-label", originalText);
+      // Collect all text nodes and join with spaces
+      const walker = document.createTreeWalker(
+        element,
+        NodeFilter.SHOW_TEXT,
+        null
+      );
+
+      const textParts = [];
+      let node;
+      while (node = walker.nextNode()) {
+        const text = node.textContent.trim();
+        if (text) {
+          textParts.push(text);
+        }
+      }
+
+      const allText = textParts.join(' ');
+
+      element.setAttribute("aria-label", allText);
       element.setAttribute("role", "img");
-      
+
       const allChildren = element.querySelectorAll("*");
       allChildren.forEach((child) => {
         child.setAttribute("aria-hidden", "true");