@hortonstudio/main 1.9.10 → 1.9.11

package/autoInit/accessibility/functions/pagination/README.md

@@ -14,12 +14,11 @@ Complete pagination system for paginated lists with controls, counters, dot navi
 - **Responsive Layouts**: Different items per page for desktop/mobile
 - **Page Controls**: Next/Previous buttons with infinite looping
 - **Page Counter**: Live-updating "X / Y" page indicator
-- **Dot Navigation**: Visual page indicators with click/keyboard support
+- **Dot Navigation**: Visual page indicators with click/keyboard support (semantic buttons)
 - **Auto-height Management**: Smooth height transitions between pages
 - **Focus Management**: Uses `inert` attribute for inactive pages
 - **ARIA Live Announcements**: Screen reader announcements for page changes
 - **Mobile Auto-scroll**: Scrolls controls into view on mobile after navigation
-- **Infinite Mode**: Disable all pagination for continuous scrolling
 
 ---
 
@@ -45,21 +44,35 @@ Complete pagination system for paginated lists with controls, counters, dot navi
 
 ### **Next Button** *(required)*
 
-**Attribute:** `data-hs-pagination="next"`
+**Attribute:** `data-hs-pagination="next"` on wrapper element
 
 **What it does:** Navigate to next page. Loops to first page after last page.
 
-**Accessibility:** Automatically receives `aria-label="Go to next page"`
+**Structure:** Uses `data-site-clickable="element"` pattern:
+```html
+<div data-hs-pagination="next" data-site-clickable="element">
+  <button type="button">Next</button>
+</div>
+```
+
+**Accessibility:** Automatically receives `aria-label="Go to next page"` on the button element
 
 ---
 
 ### **Previous Button** *(required)*
 
-**Attribute:** `data-hs-pagination="previous"`
+**Attribute:** `data-hs-pagination="previous"` on wrapper element
 
 **What it does:** Navigate to previous page. Loops to last page from first page.
 
-**Accessibility:** Automatically receives `aria-label="Go to previous page"`
+**Structure:** Uses `data-site-clickable="element"` pattern:
+```html
+<div data-hs-pagination="previous" data-site-clickable="element">
+  <button type="button">Previous</button>
+</div>
+```
+
+**Accessibility:** Automatically receives `aria-label="Go to previous page"` on the button element
 
 ---
 
@@ -67,40 +80,33 @@ Complete pagination system for paginated lists with controls, counters, dot navi
 
 **Attribute:** `data-hs-pagination="controls"`
 
-**What it does:** Container for pagination controls AND configuration via `data-hs-config`.
-
-**Configuration Syntax:**
-```
-data-hs-config="[option], [option], ..."
-```
+**What it does:** Container for pagination controls AND configuration.
 
-**Configuration Options:**
+**Configuration Attributes:**
 
-**Show Items (Desktop):**
+**`data-hs-pagination-show`** - Desktop items per page (default: 6)
 ```html
-data-hs-config="show-6"
+data-hs-pagination-show="4"
 ```
-Shows 6 items per page on desktop (default: 6)
 
-**Show Items (Mobile):**
+**`data-hs-pagination-show-mobile`** - Mobile items per page (optional, defaults to desktop value)
 ```html
-data-hs-config="show-3-mobile"
+data-hs-pagination-show-mobile="2"
 ```
-Shows 3 items per page on mobile (default: desktop value)
 
-**Infinite Mode:**
+**Example:**
 ```html
-data-hs-config="infinite"
-```
-Disables pagination completely (hides controls and dots, shows all items)
-
-**Combined Example:**
-```html
-<div data-hs-pagination="controls" data-hs-config="show-4, show-2-mobile">
+<div data-hs-pagination="controls"
+     data-hs-pagination-show="4"
+     data-hs-pagination-show-mobile="2">
   <!-- Buttons, counter, etc. -->
 </div>
 ```
 
+**No Pagination (Infinite Mode):**
+
+To disable pagination and show all items, simply don't render the controls element at all. Without controls, the pagination system won't initialize and the list displays naturally.
+
 ---
 
 ### **Counter** *(optional)*
@@ -125,10 +131,11 @@ Disables pagination completely (hides controls and dots, shows all items)
 - At least one child element (used as template)
 - Use `.is-active` class to designate active template
 - If only one template, same used for active/inactive states
+- **Dots are semantic `<button>` elements with `type="button"`**
 
 **Accessibility:** System automatically adds:
 - Individual dots via separate pagination dots system
-- `role="button"`, `tabindex="0"`, `aria-label` on each dot
+- `role="button"`, `tabindex="0"`, `aria-label` on each dot button
 - `aria-current="page"` on active dot
 
 ---
@@ -154,23 +161,34 @@ Disables pagination completely (hides controls and dots, shows all items)
   </div>
 
   <!-- Controls -->
-  <div data-hs-pagination="controls" data-hs-config="show-4, show-2-mobile">
-    <button data-hs-pagination="previous">Previous</button>
+  <div data-hs-pagination="controls"
+       data-hs-pagination-show="4"
+       data-hs-pagination-show-mobile="2">
+
+    <div data-hs-pagination="previous" data-site-clickable="element">
+      <button type="button">Previous</button>
+    </div>
+
     <div data-hs-pagination="counter">1 / 2</div>
-    <button data-hs-pagination="next">Next</button>
+
+    <div data-hs-pagination="next" data-site-clickable="element">
+      <button type="button">Next</button>
+    </div>
   </div>
 
   <!-- Dots -->
   <div data-hs-pagination="dots">
-    <div class="dot is-active"></div> <!-- Active template -->
-    <div class="dot"></div> <!-- Inactive template -->
+    <button type="button" class="dot is-active"></button> <!-- Active template -->
+    <button type="button" class="dot"></button> <!-- Inactive template -->
   </div>
 </div>
 ```
 
 ---
 
-### **Infinite Mode (No Pagination)**
+### **No Pagination (Infinite Mode)**
+
+To disable pagination and show all items without pagination controls, simply don't render the controls element:
 
 ```html
 <div data-hs-pagination="wrapper">
@@ -180,14 +198,12 @@ Disables pagination completely (hides controls and dots, shows all items)
       <div>Item 1</div>
       <div>Item 2</div>
       <div>Item 3</div>
+      <div>Item 4</div>
+      <div>Item 5</div>
     </div>
   </div>
 
-  <div data-hs-pagination="controls" data-hs-config="infinite">
-    <!-- Controls hidden automatically -->
-    <button data-hs-pagination="previous">Previous</button>
-    <button data-hs-pagination="next">Next</button>
-  </div>
+  <!-- No controls = no pagination initialization -->
 </div>
 ```
 
@@ -223,9 +239,11 @@ Uses CSS custom property `--data-hs-break` to detect layout:
 | ----- | ----- | ----- | ----- |
 | `data-hs-pagination="wrapper"` | Main container | **Required** | Wrapper div |
 | `data-hs-pagination="list"` | Items to paginate | **Required** | List container |
-| `data-hs-pagination="next"` | Next button | **Required** | `<button>` |
-| `data-hs-pagination="previous"` | Previous button | **Required** | `<button>` |
+| `data-hs-pagination="next"` | Next button wrapper | **Required** | Wrapper div with `data-site-clickable="element"` |
+| `data-hs-pagination="previous"` | Previous button wrapper | **Required** | Wrapper div with `data-site-clickable="element"` |
 | `data-hs-pagination="controls"` | Controls + config | Required for config | Wrapper div |
+| `data-hs-pagination-show` | Desktop items per page | Required on controls | Attribute (number) |
+| `data-hs-pagination-show-mobile` | Mobile items per page | Optional on controls | Attribute (number) |
 | `data-hs-pagination="counter"` | Page counter | Optional | Any element |
 | `data-hs-pagination="dots"` | Dots container | Optional | Wrapper div |
 
@@ -259,7 +277,7 @@ Uses CSS custom property `--data-hs-break` to detect layout:
 
 ### **Initialization:**
 1. Finds all `[data-hs-pagination="wrapper"]` containers
-2. Reads configuration from `data-hs-config`
+2. Reads configuration from `data-hs-pagination-show` attributes
 3. Calculates total pages based on items and config
 4. Splits items into page lists
 5. Clones pages for infinite loop (adds before/after)
@@ -280,10 +298,10 @@ Uses CSS custom property `--data-hs-break` to detect layout:
 3. Re-initializes pagination if breakpoint changes
 4. Maintains current page position when possible
 
-### **Infinite Mode:**
-1. Hides all pagination controls and dots
-2. Shows all items without splitting
-3. No page transitions or animations
+### **No Pagination (Infinite Mode):**
+1. Don't render controls element in HTML
+2. Pagination system won't initialize
+3. All items display naturally in list
 
 ---
 
@@ -329,22 +347,27 @@ The pagination system integrates with the separate pagination dots system:
 
 ### **Desktop: 6 items, Mobile: 3 items**
 ```html
-<div data-hs-config="show-6, show-3-mobile">
+<div data-hs-pagination="controls"
+     data-hs-pagination-show="6"
+     data-hs-pagination-show-mobile="3">
 ```
 
 ### **Desktop: 4 items, Mobile: 2 items**
 ```html
-<div data-hs-config="show-4, show-2-mobile">
+<div data-hs-pagination="controls"
+     data-hs-pagination-show="4"
+     data-hs-pagination-show-mobile="2">
 ```
 
 ### **Same on all devices (8 items)**
 ```html
-<div data-hs-config="show-8">
+<div data-hs-pagination="controls"
+     data-hs-pagination-show="8">
 ```
 
-### **Disable pagination (infinite mode)**
+### **No pagination (infinite mode)**
 ```html
-<div data-hs-config="infinite">
+<!-- Don't render controls element at all -->
 ```
 
 ---
@@ -360,10 +383,10 @@ The pagination system integrates with the separate pagination dots system:
 - Dots hidden similarly
 - All items displayed on single page
 
-### **Infinite Mode:**
-- Controls completely hidden
-- Dots completely hidden
-- List displayed as-is
+### **No Pagination (Infinite Mode):**
+- Don't render controls element
+- Pagination system won't initialize
+- List displays all items naturally
 - No pagination logic runs
 
 ### **Layout Changes:**
@@ -388,12 +411,13 @@ The pagination system integrates with the separate pagination dots system:
 
 **Pagination not working:**
 1. Ensure wrapper, list, next, and previous elements exist
-2. Check `data-hs-config` has valid configuration
+2. Check `data-hs-pagination-show` attribute has valid number
 3. Verify list has children elements
-4. Check console for warnings
+4. Ensure button structure uses `data-site-clickable="element"` pattern
+5. Check console for warnings
 
 **Items not splitting into pages:**
-1. Ensure `data-hs-config` specifies `show-X`
+1. Ensure `data-hs-pagination-show` specifies a number
 2. Check that total items > items per page
 3. Verify CSS custom property `--data-hs-break` is set
 
@@ -409,9 +433,9 @@ The pagination system integrates with the separate pagination dots system:
 3. Check ResizeObserver is not being blocked
 
 **Controls always hidden:**
-1. Check `data-hs-config` doesn't include "infinite"
-2. Ensure total items > items per page
-3. Verify controls container exists
+1. Ensure total items > items per page
+2. Verify controls container exists in DOM
+3. Check that `data-hs-pagination-show` is set properly
 
 ---
 

package/autoInit/accessibility/functions/pagination/pagination.js

@@ -12,26 +12,48 @@ export function init() {
   };
 
   // Initialize all pagination containers
-  document.querySelectorAll('[data-hs-pagination="wrapper"]')
-    .forEach(container => {
-      const instance = initPaginationInstance(container, cleanup);
-      if (!instance) {
-        console.warn('[hs-pagination] Failed to initialize container', container);
-      }
-    });
+  try {
+    document.querySelectorAll('[data-hs-pagination="wrapper"]')
+      .forEach(container => {
+        try {
+          const instance = initPaginationInstance(container, cleanup);
+          if (!instance) {
+            console.warn('[hs-pagination] Failed to initialize container', container);
+          }
+        } catch (error) {
+          console.error('[hs-pagination] Error initializing container:', error, container);
+        }
+      });
+  } catch (error) {
+    console.error('[hs-pagination] Critical error during initialization:', error);
+  }
 
   return {
     result: "pagination initialized",
     destroy: () => {
-      // Disconnect all observers
-      cleanup.observers.forEach(obs => obs.disconnect());
-      cleanup.observers.length = 0;
-
-      // Remove all event listeners
-      cleanup.handlers.forEach(({ element, event, handler }) => {
-        element.removeEventListener(event, handler);
-      });
-      cleanup.handlers.length = 0;
+      try {
+        // Disconnect all observers
+        cleanup.observers.forEach(obs => {
+          try {
+            obs.disconnect();
+          } catch (error) {
+            console.error('[hs-pagination] Error disconnecting observer:', error);
+          }
+        });
+        cleanup.observers.length = 0;
+
+        // Remove all event listeners
+        cleanup.handlers.forEach(({ element, event, handler }) => {
+          try {
+            element.removeEventListener(event, handler);
+          } catch (error) {
+            console.error('[hs-pagination] Error removing event listener:', error);
+          }
+        });
+        cleanup.handlers.length = 0;
+      } catch (error) {
+        console.error('[hs-pagination] Critical error during cleanup:', error);
+      }
     }
   };
 }
@@ -47,18 +69,30 @@ function initPaginationInstance(container, cleanup) {
   if (!wrapper) return null;
 
   const elements = {
-    nextBtn: container.querySelector('[data-hs-pagination="next"]'),
-    prevBtn: container.querySelector('[data-hs-pagination="previous"]'),
-    counter: container.querySelector('[data-hs-pagination="counter"]'),
     controls: container.querySelector('[data-hs-pagination="controls"]'),
+    counter: container.querySelector('[data-hs-pagination="counter"]'),
     dotsWrap: container.querySelector('[data-hs-pagination="dots"]')
   };
 
-  if (!elements.nextBtn || !elements.prevBtn) {
+  // Early exit for infinite mode - no controls means no pagination
+  if (!elements.controls) {
+    return { initialized: false };
+  }
+
+  // Find next/previous buttons using data-site-clickable pattern
+  const nextClickable = container.querySelector('[data-hs-pagination="next"]');
+  const prevClickable = container.querySelector('[data-hs-pagination="previous"]');
+  const nextBtn = nextClickable?.children[0];
+  const prevBtn = prevClickable?.children[0];
+
+  if (!nextBtn || !prevBtn) {
     console.warn('[hs-pagination] Missing required navigation buttons');
     return null;
   }
 
+  elements.nextBtn = nextBtn;
+  elements.prevBtn = prevBtn;
+
   // Add ARIA attributes to buttons
   elements.nextBtn.setAttribute('aria-label', 'Go to next page');
   elements.prevBtn.setAttribute('aria-label', 'Go to previous page');
@@ -67,26 +101,9 @@ function initPaginationInstance(container, cleanup) {
     elements.counter.setAttribute('aria-label', 'Current page');
   }
 
-  // Parse configuration
-  const config = elements.controls?.getAttribute('data-hs-config') || '';
-  const configOptions = config.split(', ').map(opt => opt.trim());
-  const isInfiniteMode = configOptions.includes('infinite');
-
-  const desktopItems = !isInfiniteMode ? (parseInt(config.match(/show-(\d+)(?!-mobile)/)?.[1]) || 6) : 0;
-  const mobileItems = !isInfiniteMode ? (parseInt(config.match(/show-(\d+)-mobile/)?.[1]) || desktopItems) : 0;
-
-  // Early exit for infinite mode - disable pagination completely
-  if (isInfiniteMode) {
-    if (elements.controls) {
-      elements.controls.style.display = 'none';
-      elements.controls.setAttribute('aria-hidden', 'true');
-    }
-    if (elements.dotsWrap) {
-      elements.dotsWrap.style.display = 'none';
-      elements.dotsWrap.setAttribute('aria-hidden', 'true');
-    }
-    return { initialized: false };
-  }
+  // Parse configuration from new attributes
+  const desktopItems = parseInt(elements.controls?.getAttribute('data-hs-pagination-show')) || 6;
+  const mobileItems = parseInt(elements.controls?.getAttribute('data-hs-pagination-show-mobile')) || desktopItems;
 
   const isMobileLayout = () => {
     const breakpoint = getComputedStyle(list).getPropertyValue('--data-hs-break').trim().replace(/"/g, '');
@@ -102,7 +119,8 @@ function initPaginationInstance(container, cleanup) {
     currentIndex: 1,
     currentPage: 1,
     isAnimating: false,
-    itemsPerPage: desktopItems
+    itemsPerPage: desktopItems,
+    dotTemplates: { active: null, inactive: null }
   };
   let wrapperChildren = [];
 
@@ -133,38 +151,84 @@ function initPaginationInstance(container, cleanup) {
 
   const updateHeight = () => {
     const targetPage = wrapperChildren[state.currentIndex];
-    if (targetPage) wrapper.style.height = targetPage.offsetHeight + 'px';
+    if (targetPage && targetPage.offsetHeight !== undefined) {
+      wrapper.style.height = targetPage.offsetHeight + 'px';
+    }
   };
 
   const initializeDots = () => {
     if (!elements.dotsWrap) return;
 
-    // Set pagination attributes for dot system
-    elements.dotsWrap.setAttribute('data-hs-pagination', '');
-    elements.dotsWrap.setAttribute('data-hs-pagination-total', state.totalPages);
-    elements.dotsWrap.setAttribute('data-hs-pagination-current', state.currentPage);
-
-    // Wait for pagination system to initialize dots
-    setTimeout(() => {
-      // Listen for dot clicks
-      const paginationChangeHandler = (e) => {
-        if (e.detail && e.detail.page) {
-          navigateToPage(e.detail.page);
+    // Find existing dots as templates
+    const existingDots = Array.from(elements.dotsWrap.children);
+    if (!existingDots.length) return;
+
+    // Identify active and inactive templates
+    const activeDot = existingDots.find(dot => dot.classList.contains('is-active'));
+    const inactiveDot = existingDots.find(dot => !dot.classList.contains('is-active'));
+
+    // Store templates (use same template for both if only one exists)
+    state.dotTemplates.active = activeDot ? activeDot.cloneNode(true) : existingDots[0].cloneNode(true);
+    state.dotTemplates.inactive = inactiveDot ? inactiveDot.cloneNode(true) : existingDots[0].cloneNode(true);
+
+    // Clear existing dots
+    elements.dotsWrap.innerHTML = '';
+
+    // Add pagination accessibility attributes
+    elements.dotsWrap.setAttribute('role', 'group');
+    elements.dotsWrap.setAttribute('aria-label', 'Page navigation');
+
+    // Create dots for each page
+    for (let i = 1; i <= state.totalPages; i++) {
+      const dot = (i === 1 ? state.dotTemplates.active : state.dotTemplates.inactive).cloneNode(true);
+
+      // Add accessibility attributes
+      dot.setAttribute('role', 'button');
+      dot.setAttribute('tabindex', '0');
+      dot.setAttribute('aria-label', `Go to page ${i}`);
+      dot.setAttribute('aria-current', i === 1 ? 'page' : 'false');
+      dot.setAttribute('data-page', i);
+
+      // Set initial active state
+      if (i === 1) {
+        dot.classList.add('is-active');
+      } else {
+        dot.classList.remove('is-active');
+      }
+
+      // Click handler
+      const clickHandler = () => navigateToPage(i);
+      dot.addEventListener('click', clickHandler);
+      cleanup.handlers.push({ element: dot, event: 'click', handler: clickHandler });
+
+      // Keyboard handler
+      const keyHandler = (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          navigateToPage(i);
         }
       };
-      elements.dotsWrap.addEventListener('hs-pagination-change', paginationChangeHandler);
-      cleanup.handlers.push({
-        element: elements.dotsWrap,
-        event: 'hs-pagination-change',
-        handler: paginationChangeHandler
-      });
-    }, 50);
+      dot.addEventListener('keydown', keyHandler);
+      cleanup.handlers.push({ element: dot, event: 'keydown', handler: keyHandler });
+
+      elements.dotsWrap.appendChild(dot);
+    }
   };
 
-  const updateDots = () => {
-    if (!elements.dotsWrap || !elements.dotsWrap.hsPaginationUpdate) return;
-    elements.dotsWrap.setAttribute('data-hs-pagination-current', state.currentPage);
-    elements.dotsWrap.hsPaginationUpdate(state.currentPage);
+  const updateActiveDot = () => {
+    if (!elements.dotsWrap) return;
+
+    const dots = Array.from(elements.dotsWrap.children);
+    dots.forEach((dot, index) => {
+      const dotPage = index + 1;
+      if (dotPage === state.currentPage) {
+        dot.classList.add('is-active');
+        dot.setAttribute('aria-current', 'page');
+      } else {
+        dot.classList.remove('is-active');
+        dot.setAttribute('aria-current', 'false');
+      }
+    });
   };
 
   const initializePagination = (forceItemsPerPage = null) => {
@@ -172,6 +236,13 @@ function initPaginationInstance(container, cleanup) {
     state.itemsPerPage = forceItemsPerPage || (currentIsMobile ? mobileItems : desktopItems);
     state.totalPages = Math.ceil(totalItems / state.itemsPerPage);
 
+    // Remove old dot event handlers to prevent memory leaks
+    if (elements.dotsWrap) {
+      cleanup.handlers = cleanup.handlers.filter(({ element }) => {
+        return !elements.dotsWrap.contains(element);
+      });
+    }
+
     // Clean up previous page lists
     Array.from(wrapper.children).forEach(child => {
       if (child !== list) wrapper.removeChild(child);
@@ -238,6 +309,9 @@ function initPaginationInstance(container, cleanup) {
   let currentLayoutIsMobile = isMobileLayout();
 
   const checkLayoutChange = () => {
+    // Prevent resize during animation
+    if (state.isAnimating) return;
+
     const newIsMobile = isMobileLayout();
     if (newIsMobile !== currentLayoutIsMobile) {
       currentLayoutIsMobile = newIsMobile;
@@ -263,7 +337,7 @@ function initPaginationInstance(container, cleanup) {
     updateCounter();
     announcePageChange();
     updateHeight();
-    updateDots();
+    updateActiveDot();
 
     if (isMobileLayout() && elements.controls) {
       setTimeout(() => {
@@ -277,7 +351,10 @@ function initPaginationInstance(container, cleanup) {
     wrapper.style.transition = 'transform 0.5s cubic-bezier(0.25, 0.46, 0.45, 0.94)';
     wrapper.style.transform = `translateX(${-state.currentIndex * 100}%)`;
 
+    let transitionTimeout = null;
+
     const handleTransitionEnd = () => {
+      clearTimeout(transitionTimeout);
       wrapper.removeEventListener('transitionend', handleTransitionEnd);
       wrapper.style.transition = '';
 
@@ -285,10 +362,13 @@ function initPaginationInstance(container, cleanup) {
       announcePageChange();
       updateHeight();
       manageFocus();
-      updateDots();
+      updateActiveDot();
       state.isAnimating = false;
     };
 
+    // Safety timeout in case transitionend never fires
+    transitionTimeout = setTimeout(handleTransitionEnd, 1000);
+
     wrapper.addEventListener('transitionend', handleTransitionEnd);
   };
 
@@ -303,7 +383,7 @@ function initPaginationInstance(container, cleanup) {
     updateCounter();
     announcePageChange();
     updateHeight();
-    updateDots();
+    updateActiveDot();
 
     if (isMobileLayout() && elements.controls) {
       setTimeout(() => {
@@ -317,7 +397,10 @@ function initPaginationInstance(container, cleanup) {
     wrapper.style.transition = 'transform 0.5s cubic-bezier(0.25, 0.46, 0.45, 0.94)';
     wrapper.style.transform = `translateX(${-state.currentIndex * 100}%)`;
 
+    let transitionTimeout = null;
+
     const handleTransitionEnd = () => {
+      clearTimeout(transitionTimeout);
       wrapper.removeEventListener('transitionend', handleTransitionEnd);
       wrapper.style.transition = '';
 
@@ -335,10 +418,13 @@ function initPaginationInstance(container, cleanup) {
       announcePageChange();
       updateHeight();
       manageFocus();
-      updateDots();
+      updateActiveDot();
       state.isAnimating = false;
     };
 
+    // Safety timeout in case transitionend never fires
+    transitionTimeout = setTimeout(handleTransitionEnd, 1000);
+
     wrapper.addEventListener('transitionend', handleTransitionEnd);
   };
 

package/autoInit/site-settings/README.md

@@ -2,7 +2,7 @@
 
 ## **Overview**
 
-The site settings system collects dynamic values from designated elements and replaces placeholder text (`{{name}}`) throughout the entire page. This allows for centralized content management where values can be defined once and used multiple times across text and links.
+The site settings system collects dynamic values from designated elements and replaces placeholder text (`{{name}}`) throughout the entire page. Supports both text and href values, allowing for proper handling of links like `tel:`, `mailto:`, and URLs without Webflow's default prefixes breaking them.
 
 ---
 
@@ -22,7 +22,8 @@ The site settings system collects dynamic values from designated elements and re
 
 * data-site-settings="name"
   * The attribute value is the placeholder name (e.g., "company", "email", "phone")
-  * The element's text content is the value to replace
+  * The element's text content is used for text replacements
+  * The element's href attribute (if present) is used for link replacements
 
 **Typical element layout:**
 
@@ -30,17 +31,29 @@ The site settings system collects dynamic values from designated elements and re
    1. Settings List (data-site-settings-element="list")
       1. Setting Element (data-site-settings="company")
          1. Text: "Compass Facilities"
-      2. Setting Element (data-site-settings="email")
+      2. Link Setting (data-site-settings="email", href="mailto:info@compass.com")
          1. Text: "info@compass.com"
-      3. Setting Element (data-site-settings="phone")
-         1. Text: "555-1234"
+      3. Link Setting (data-site-settings="phone", href="tel:+15551234567")
+         1. Text: "(555) 123-4567"
 
 ### **What It Does**
 
-1. **Collects settings** - Finds all elements with `[data-site-settings]` and stores their text values
-2. **Ignores empty elements** - Elements without text (like images) are skipped
-3. **Replaces text placeholders** - Finds all `{{name}}` in page text and replaces with values
-4. **Replaces link placeholders** - Finds all `{{name}}` in link hrefs and replaces with values
+1. **Collects settings** - Finds all elements with `[data-site-settings]` and stores both text and href values
+2. **Separates text and href** - Distinguishes between display text and link URLs
+3. **Replaces text placeholders** - Finds all `{{name}}` in page text and replaces with text value (or href as fallback)
+4. **Replaces link hrefs** - Finds all `{{name}}` in link hrefs:
+   - **With dedicated href:** Completely replaces entire href attribute (prevents Webflow's "https://" prefix)
+   - **Without dedicated href:** Does normal placeholder replacement using text value
+
+### **Text vs Href Behavior**
+
+**Text replacement** (in page content):
+- **First choice:** Use text value
+- **Fallback:** Use href value if no text
+
+**Href replacement** (in link attributes):
+- **With dedicated href:** Completely replace entire href (fixes Webflow prefix issue)
+- **Without dedicated href:** Normal placeholder replacement with text value
 
 ### **When It Runs**
 
@@ -88,7 +101,7 @@ For dynamic content where certain parts should be hidden based on CMS conditions
 2. Finds all descendants with `[data-site-settings-hide]`
 3. Checks if element has any matching classes
 4. Removes matching elements from clone
-5. Extracts text from cleaned clone
+5. Extracts text and href from cleaned clone
 
 ---
 
@@ -96,19 +109,38 @@ For dynamic content where certain parts should be hidden based on CMS conditions
 
 ### **Define Settings**
 
+#### **Basic Text Settings**
+
 ```html
 <div data-site-settings-element="wrapper" style="display: none;">
   <div data-site-settings-element="list">
     <div data-site-settings="company">Compass Facilities</div>
-    <div data-site-settings="email">info@compass.com</div>
-    <div data-site-settings="phone">555-1234</div>
     <div data-site-settings="address">123 Main St, Dallas, TX 75001</div>
   </div>
 </div>
 ```
 
+#### **Link Settings with Href**
+
+```html
+<div data-site-settings-element="wrapper" style="display: none;">
+  <div data-site-settings-element="list">
+    <!-- Email with both display text and mailto: link -->
+    <a data-site-settings="email" href="mailto:info@compass.com">info@compass.com</a>
+
+    <!-- Phone with formatted display and tel: link -->
+    <a data-site-settings="phone" href="tel:+15551234567">(555) 123-4567</a>
+
+    <!-- Social link -->
+    <a data-site-settings="facebook" href="https://facebook.com/compassfacilities">Facebook</a>
+  </div>
+</div>
+```
+
 **Note:** The wrapper is typically hidden with `display: none` since it's only for data storage.
 
+---
+
 ### **Use Settings in Text**
 
 ```html
@@ -120,23 +152,52 @@ For dynamic content where certain parts should be hidden based on CMS conditions
 **Result:**
 ```html
 <h1>Welcome to Compass Facilities</h1>
-<p>Contact us at info@compass.com or call 555-1234</p>
+<p>Contact us at info@compass.com or call (555) 123-4567</p>
 <p>Visit us at 123 Main St, Dallas, TX 75001</p>
 ```
 
-### **Use Settings in Links**
+---
+
+### **Use Settings in Links (With Dedicated Href)**
+
+**IMPORTANT:** When setting has a dedicated href, the ENTIRE href attribute is replaced (not just the placeholder). This prevents Webflow's default "https://" prefix from breaking tel:, mailto:, and other special link types.
 
 ```html
-<a href="mailto:{{email}}">Email Us</a>
-<a href="tel:{{phone}}">Call Us</a>
-<a href="https://maps.google.com/?q={{address}}">Get Directions</a>
+<!-- In Webflow, these links might have href="https://{{email}}" -->
+<a href="{{email}}">Email Us</a>
+<a href="{{phone}}">Call Us</a>
+<a href="{{facebook}}">Follow Us</a>
 ```
 
 **Result:**
 ```html
+<!-- Entire href replaced with dedicated href value -->
 <a href="mailto:info@compass.com">Email Us</a>
-<a href="tel:555-1234">Call Us</a>
-<a href="https://maps.google.com/?q=123 Main St, Dallas, TX 75001">Get Directions</a>
+<a href="tel:+15551234567">Call Us</a>
+<a href="https://facebook.com/compassfacilities">Follow Us</a>
+```
+
+**Why this matters:** Webflow often adds `https://` prefix by default. Without complete href replacement:
+- `https://tel:+15551234567` ❌ (broken)
+- `tel:+15551234567` ✅ (works)
+
+---
+
+### **Use Settings in Links (Without Dedicated Href)**
+
+When setting has only text (no href), normal placeholder replacement occurs:
+
+```html
+<!-- Setting with only text -->
+<div data-site-settings="company-url">compassfacilities.com</div>
+
+<!-- Link in page -->
+<a href="https://{{company-url}}">Visit Site</a>
+```
+
+**Result:**
+```html
+<a href="https://compassfacilities.com">Visit Site</a>
 ```
 
 ---
@@ -146,11 +207,11 @@ For dynamic content where certain parts should be hidden based on CMS conditions
 You can have multiple lists inside the wrapper for organization:
 
 ```html
-<div data-site-settings-element="wrapper">
+<div data-site-settings-element="wrapper" style="display: none;">
   <!-- Contact info -->
   <div data-site-settings-element="list">
-    <div data-site-settings="email">info@compass.com</div>
-    <div data-site-settings="phone">555-1234</div>
+    <a data-site-settings="email" href="mailto:info@compass.com">info@compass.com</a>
+    <a data-site-settings="phone" href="tel:+15551234567">(555) 123-4567</a>
   </div>
 
   <!-- Company info -->
@@ -158,6 +219,12 @@ You can have multiple lists inside the wrapper for organization:
     <div data-site-settings="company">Compass Facilities</div>
     <div data-site-settings="established">2020</div>
   </div>
+
+  <!-- Social links -->
+  <div data-site-settings-element="list">
+    <a data-site-settings="facebook" href="https://facebook.com/compass">Facebook</a>
+    <a data-site-settings="twitter" href="https://twitter.com/compass">Twitter</a>
+  </div>
 </div>
 ```
 
@@ -172,6 +239,7 @@ All settings are collected regardless of which list they're in.
 | `data-site-settings-element="wrapper"` | Settings container | Wrapper div |
 | `data-site-settings-element="list"` | Settings list | List div (at least one) |
 | `data-site-settings="name"` | Setting with name | Individual setting elements |
+| `href` attribute | Link URL for href replacement | Optional (on link settings) |
 | `data-site-settings-hide="class"` | Conditional hide | Optional (inside setting elements) |
 
 ---
@@ -187,13 +255,74 @@ All settings are collected regardless of which list they're in.
 
 ---
 
+## **Replacement Logic**
+
+### **For Text Content (`{{name}}` in page text):**
+1. If setting has text value → use text
+2. If no text but has href value → use href
+3. If neither → skip replacement
+
+### **For Link Hrefs (`{{name}}` in href attribute):**
+1. If setting has href value → **completely replace entire href**
+2. If no href but has text value → normal placeholder replacement
+3. If neither → skip replacement
+
+---
+
+## **Common Use Cases**
+
+### **Phone Number**
+```html
+<!-- Setting with both formatted display and tel: link -->
+<a data-site-settings="phone" href="tel:+15551234567">(555) 123-4567</a>
+
+<!-- Text usage -->
+<p>Call us at {{phone}}</p>
+<!-- Result: Call us at (555) 123-4567 -->
+
+<!-- Link usage -->
+<a href="{{phone}}">Call Now</a>
+<!-- Result: <a href="tel:+15551234567">Call Now</a> -->
+```
+
+### **Email Address**
+```html
+<!-- Setting -->
+<a data-site-settings="email" href="mailto:contact@example.com">contact@example.com</a>
+
+<!-- Text usage -->
+<p>Email: {{email}}</p>
+<!-- Result: Email: contact@example.com -->
+
+<!-- Link usage -->
+<a href="{{email}}">Email Us</a>
+<!-- Result: <a href="mailto:contact@example.com">Email Us</a> -->
+```
+
+### **Social Media**
+```html
+<!-- Setting -->
+<a data-site-settings="facebook" href="https://facebook.com/mypage">@mypage</a>
+
+<!-- Text usage -->
+<p>Follow us: {{facebook}}</p>
+<!-- Result: Follow us: @mypage -->
+
+<!-- Link usage -->
+<a href="{{facebook}}">Facebook</a>
+<!-- Result: <a href="https://facebook.com/mypage">Facebook</a> -->
+```
+
+---
+
 ## **Notes**
 
-1. **Empty elements ignored** - Elements without text (images, empty divs) are skipped
+1. **Empty elements ignored** - Elements without text or href are skipped
 2. **No visual component** - Settings wrapper should be hidden with CSS
 3. **Page-wide replacement** - Placeholders are replaced throughout entire page
 4. **Multiple replacements** - Same placeholder can be used unlimited times
 5. **Barba.js compatible** - Automatically reinitializes on page transitions
+6. **Webflow-friendly** - Complete href replacement prevents default "https://" prefix issues
 
 ---
 
@@ -202,17 +331,35 @@ All settings are collected regardless of which list they're in.
 **Placeholder not replacing:**
 
 1. Verify `data-site-settings` attribute matches placeholder name exactly
-2. Check that setting element has text content
+2. Check that setting element has text content or href attribute
 3. Ensure double curly braces: `{{name}}` not `{name}` or `{{ name }}`
 
 **Wrong value appearing:**
 
 1. Check for duplicate setting names (last one wins)
 2. Verify conditional hide elements are working correctly
-3. Inspect the settings wrapper to confirm expected text
+3. Inspect the settings wrapper to confirm expected text and href
+
+**Links not working (tel:, mailto:, etc.):**
+
+1. Ensure setting element has `href` attribute with proper protocol
+2. Use `<a>` element for settings that need href replacement
+3. Verify placeholder is directly in href: `href="{{phone}}"` not `href="tel:{{phone}}"`
+4. The system will completely replace the href when setting has dedicated href value
+
+**Webflow adding "https://" prefix:**
+
+1. This is expected Webflow behavior
+2. System automatically fixes this when setting has dedicated href
+3. Entire href is replaced, removing Webflow's prefix
+4. Example: `https://{{phone}}` → `tel:+15551234567` ✓
+
+---
 
-**Links not working:**
+## **Best Practices**
 
-1. Ensure placeholder syntax is correct in href attribute
-2. Check that value is URL-safe (encode special characters if needed)
-3. For tel: links, ensure phone number has no spaces or dashes in setting value
+1. **Use links for contact info** - Phone, email, social media should be `<a>` elements with href
+2. **Format display text** - Use human-readable text, proper href for functionality
+3. **Hide the wrapper** - Always use `display: none` or similar to hide settings container
+4. **Organize with lists** - Group related settings in separate lists for clarity
+5. **Test replacements** - Check both text and link replacements work as expected

package/autoInit/site-settings/site-settings.js

@@ -47,11 +47,15 @@ export function init() {
         });
 
         const settingName = element.getAttribute('data-site-settings');
-        const settingValue = clonedElement.textContent.trim();
-
-        // Only store if both name and value exist (ignore empty elements like images)
-        if (settingName && settingValue) {
-          siteSettings[settingName] = settingValue;
+        const settingText = clonedElement.textContent.trim();
+        const settingHref = element.getAttribute('href');
+
+        // Store if name exists and either text or href exists
+        if (settingName && (settingText || settingHref)) {
+          siteSettings[settingName] = {
+            text: settingText || null,
+            href: settingHref || null
+          };
         }
       });
     });
@@ -93,8 +97,13 @@ export function init() {
       for (const name in siteSettings) {
         const placeholder = `{{${name}}}`;
         if (newText.includes(placeholder)) {
-          newText = newText.replace(new RegExp(placeholder, 'g'), siteSettings[name]);
-          hasChanges = true;
+          const setting = siteSettings[name];
+          // Use text value if available, otherwise use href value, otherwise skip
+          const replacementValue = setting.text || setting.href;
+          if (replacementValue) {
+            newText = newText.replace(new RegExp(placeholder, 'g'), replacementValue);
+            hasChanges = true;
+          }
         }
       }
 
@@ -112,8 +121,19 @@ export function init() {
       for (const name in siteSettings) {
         const placeholder = `{{${name}}}`;
         if (href.includes(placeholder)) {
-          href = href.replace(new RegExp(placeholder, 'g'), siteSettings[name]);
-          hasChanges = true;
+          const setting = siteSettings[name];
+
+          // If setting has a dedicated href, completely replace the entire href
+          // (prevents Webflow's default "https://" from breaking tel:, mailto:, etc.)
+          if (setting.href) {
+            href = setting.href;
+            hasChanges = true;
+          }
+          // Otherwise, do normal placeholder replacement with text value
+          else if (setting.text) {
+            href = href.replace(new RegExp(placeholder, 'g'), setting.text);
+            hasChanges = true;
+          }
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hortonstudio/main",
-  "version": "1.9.10",
+  "version": "1.9.11",
   "description": "Animation and utility library for client websites",
   "main": "index.js",
   "type": "module",