@vanduo-oss/framework 1.2.6 → 1.2.8

package/js/components/spotlight.js

@@ -0,0 +1,295 @@
+/**
+ * Vanduo Framework - Spotlight (Feature Discovery) Component
+ * Guided tour with overlay highlight and step-through tooltip
+ */
+
+(function () {
+  'use strict';
+
+  const Spotlight = {
+    _active: false,
+    _steps: [],
+    _currentStep: 0,
+    _elements: {},
+    _cleanup: [],
+    _boundTriggers: new WeakMap(),
+    _triggerElement: null,
+
+    init: function () {
+      const triggers = document.querySelectorAll('[data-vd-spotlight]');
+
+      triggers.forEach(trigger => {
+        if (this._boundTriggers.has(trigger)) return;
+
+        const clickHandler = (event) => {
+          event.preventDefault();
+
+          const steps = this._parseSteps(trigger.getAttribute('data-vd-spotlight'));
+          if (steps.length === 0) return;
+
+          this.start(steps, { trigger });
+        };
+
+        trigger.addEventListener('click', clickHandler);
+        this._boundTriggers.set(trigger, clickHandler);
+      });
+    },
+
+    _parseSteps: function (raw) {
+      if (typeof raw !== 'string' || raw.trim() === '') return [];
+
+      try {
+        const parsed = JSON.parse(raw);
+        return this._normalizeSteps(parsed);
+      } catch (error) {
+        console.error('VanduoSpotlight: invalid data-vd-spotlight payload.', error);
+        return [];
+      }
+    },
+
+    _normalizeStep: function (step) {
+      if (!step || typeof step !== 'object') return null;
+
+      const target = step.target;
+      const hasSelectorTarget = typeof target === 'string' && target.trim() !== '';
+      const hasElementTarget = typeof Element !== 'undefined' && target instanceof Element;
+
+      if (!hasSelectorTarget && !hasElementTarget) return null;
+
+      const title = typeof step.title === 'string' ? step.title : '';
+      const description = typeof step.description === 'string'
+        ? step.description
+        : (typeof step.content === 'string' ? step.content : '');
+
+      return {
+        target,
+        title,
+        description
+      };
+    },
+
+    _normalizeSteps: function (steps) {
+      if (!Array.isArray(steps)) return [];
+
+      return steps
+        .map(step => this._normalizeStep(step))
+        .filter(Boolean);
+    },
+
+    start: function (steps, options) {
+      if (this._active) this.stop();
+
+      const normalizedSteps = this._normalizeSteps(steps);
+      if (normalizedSteps.length === 0) return;
+
+      const startOptions = options || {};
+
+      this._steps = normalizedSteps;
+      this._currentStep = 0;
+      this._active = true;
+      this._triggerElement = startOptions.trigger || (document.activeElement instanceof HTMLElement ? document.activeElement : null);
+
+      // Create overlay
+      const overlay = document.createElement('div');
+      overlay.className = 'vd-spotlight-overlay';
+      overlay.setAttribute('aria-hidden', 'true');
+      document.body.appendChild(overlay);
+
+      // Create tooltip
+      const tooltip = document.createElement('div');
+      tooltip.className = 'vd-spotlight-tooltip';
+      tooltip.setAttribute('role', 'dialog');
+      tooltip.setAttribute('aria-modal', 'true');
+      tooltip.tabIndex = -1;
+      document.body.appendChild(tooltip);
+
+      this._elements = { overlay, tooltip };
+
+      // ESC to close
+      const escHandler = (e) => { if (e.key === 'Escape') this.stop(); };
+      document.addEventListener('keydown', escHandler);
+      this._cleanup.push(() => document.removeEventListener('keydown', escHandler));
+
+      // Overlay click to close
+      overlay.addEventListener('click', () => this.stop());
+
+      this._showStep(this._currentStep);
+    },
+
+    _showStep: function (index) {
+      const step = this._steps[index];
+      if (!step) return;
+
+      const target = typeof step.target === 'string' ? document.querySelector(step.target) : step.target;
+      const { tooltip } = this._elements;
+
+      // Remove previous highlight
+      document.querySelectorAll('.vd-spotlight-target').forEach(el => {
+        el.classList.remove('vd-spotlight-target');
+      });
+
+      // Highlight target
+      if (target) {
+        target.classList.add('vd-spotlight-target');
+        target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      }
+
+      // Build tooltip content
+      const total = this._steps.length;
+      tooltip.innerHTML = '';
+      tooltip.removeAttribute('aria-labelledby');
+      tooltip.removeAttribute('aria-describedby');
+
+      if (step.title) {
+        const title = document.createElement('h4');
+        title.className = 'vd-spotlight-title';
+        title.id = 'vd-spotlight-title-' + index + '-' + Date.now();
+        title.textContent = step.title;
+        tooltip.appendChild(title);
+        tooltip.setAttribute('aria-labelledby', title.id);
+      }
+
+      if (step.description) {
+        const desc = document.createElement('p');
+        desc.className = 'vd-spotlight-description';
+        desc.id = 'vd-spotlight-description-' + index + '-' + Date.now();
+        desc.textContent = step.description;
+        tooltip.appendChild(desc);
+        tooltip.setAttribute('aria-describedby', desc.id);
+      }
+
+      // Footer
+      const footer = document.createElement('div');
+      footer.className = 'vd-spotlight-footer';
+      footer.setAttribute('aria-label', 'Step ' + (index + 1) + ' of ' + total);
+
+      const counter = document.createElement('span');
+      counter.className = 'vd-spotlight-counter';
+      counter.textContent = (index + 1) + ' / ' + total;
+
+      const actions = document.createElement('div');
+      actions.className = 'vd-spotlight-actions';
+
+      if (index > 0) {
+        const prevBtn = document.createElement('button');
+        prevBtn.type = 'button';
+        prevBtn.className = 'vd-spotlight-btn';
+        prevBtn.textContent = 'Back';
+        prevBtn.addEventListener('click', () => this.prev());
+        actions.appendChild(prevBtn);
+      }
+
+      const skipBtn = document.createElement('button');
+      skipBtn.type = 'button';
+      skipBtn.className = 'vd-spotlight-btn';
+      skipBtn.textContent = 'Skip';
+      skipBtn.addEventListener('click', () => this.stop());
+      actions.appendChild(skipBtn);
+
+      if (index < total - 1) {
+        const nextBtn = document.createElement('button');
+        nextBtn.type = 'button';
+        nextBtn.className = 'vd-spotlight-btn vd-spotlight-btn-primary';
+        nextBtn.textContent = 'Next';
+        nextBtn.addEventListener('click', () => this.next());
+        actions.appendChild(nextBtn);
+      } else {
+        const doneBtn = document.createElement('button');
+        doneBtn.type = 'button';
+        doneBtn.className = 'vd-spotlight-btn vd-spotlight-btn-primary';
+        doneBtn.textContent = 'Done';
+        doneBtn.addEventListener('click', () => this.stop());
+        actions.appendChild(doneBtn);
+      }
+
+      footer.appendChild(counter);
+      footer.appendChild(actions);
+      tooltip.appendChild(footer);
+
+      // Position tooltip near target
+      if (target) {
+        requestAnimationFrame(() => {
+          const rect = target.getBoundingClientRect();
+          const tRect = tooltip.getBoundingClientRect();
+          let top = rect.bottom + 12 + window.scrollY;
+          let left = rect.left + (rect.width - tRect.width) / 2 + window.scrollX;
+
+          // Keep in viewport
+          left = Math.max(8, Math.min(left, window.innerWidth - tRect.width - 8));
+          if (top + tRect.height > window.innerHeight + window.scrollY) {
+            top = rect.top - tRect.height - 12 + window.scrollY;
+          }
+
+          tooltip.style.top = top + 'px';
+          tooltip.style.left = left + 'px';
+        });
+      }
+
+      document.dispatchEvent(new CustomEvent('spotlight:step', {
+        detail: { index, step: index, total, data: step }
+      }));
+    },
+
+    next: function () {
+      if (this._currentStep < this._steps.length - 1) {
+        this._currentStep++;
+        this._showStep(this._currentStep);
+      }
+    },
+
+    prev: function () {
+      if (this._currentStep > 0) {
+        this._currentStep--;
+        this._showStep(this._currentStep);
+      }
+    },
+
+    stop: function () {
+      if (!this._active) return;
+
+      const total = this._steps.length;
+      const detail = {
+        completedSteps: total === 0 ? 0 : Math.min(this._currentStep + 1, total),
+        total,
+        completed: total > 0 && this._currentStep >= total - 1
+      };
+
+      this._active = false;
+
+      document.querySelectorAll('.vd-spotlight-target').forEach(el => {
+        el.classList.remove('vd-spotlight-target');
+      });
+
+      if (this._elements.overlay && this._elements.overlay.parentNode) {
+        this._elements.overlay.parentNode.removeChild(this._elements.overlay);
+      }
+      if (this._elements.tooltip && this._elements.tooltip.parentNode) {
+        this._elements.tooltip.parentNode.removeChild(this._elements.tooltip);
+      }
+
+      this._cleanup.forEach(fn => fn());
+      this._cleanup = [];
+      this._elements = {};
+      this._steps = [];
+      this._currentStep = 0;
+
+      if (this._triggerElement && this._triggerElement.isConnected && typeof this._triggerElement.focus === 'function') {
+        this._triggerElement.focus();
+      }
+      this._triggerElement = null;
+
+      document.dispatchEvent(new CustomEvent('spotlight:end', { detail }));
+    },
+
+    destroyAll: function () {
+      this.stop();
+    }
+  };
+
+  if (typeof window.Vanduo !== 'undefined') {
+    window.Vanduo.register('spotlight', Spotlight);
+  }
+
+  window.VanduoSpotlight = Spotlight;
+
+})();

package/js/components/stepper.js

@@ -0,0 +1,97 @@
+/**
+ * Vanduo Framework - Stepper Component
+ * Multi-step progress indicator with state management
+ */
+
+(function () {
+  'use strict';
+
+  const Stepper = {
+    instances: new Map(),
+
+    init: function () {
+      const steppers = document.querySelectorAll('.vd-stepper');
+      steppers.forEach(el => {
+        if (this.instances.has(el)) return;
+        this.initInstance(el);
+      });
+    },
+
+    initInstance: function (el) {
+      const cleanup = [];
+      const items = Array.from(el.querySelectorAll('.vd-stepper-item'));
+      const isClickable = el.classList.contains('vd-stepper-clickable');
+      let currentIndex = items.findIndex(i => i.classList.contains('is-active'));
+      if (currentIndex === -1) currentIndex = 0;
+
+      const setStep = (index) => {
+        if (index < 0 || index >= items.length) return;
+        const prev = currentIndex;
+        currentIndex = index;
+
+        items.forEach((item, i) => {
+          item.classList.remove('is-active', 'is-completed');
+          if (i < index) item.classList.add('is-completed');
+          else if (i === index) item.classList.add('is-active');
+        });
+
+        el.dispatchEvent(new CustomEvent('stepper:change', {
+          detail: { current: index, previous: prev, total: items.length },
+          bubbles: true
+        }));
+      };
+
+      if (isClickable) {
+        items.forEach((item, i) => {
+          const handler = () => setStep(i);
+          item.addEventListener('click', handler);
+          cleanup.push(() => item.removeEventListener('click', handler));
+        });
+      }
+
+      // Initialize current state
+      setStep(currentIndex);
+
+      this.instances.set(el, {
+        cleanup,
+        setStep,
+        next: () => setStep(currentIndex + 1),
+        prev: () => setStep(currentIndex - 1),
+        getCurrent: () => currentIndex
+      });
+    },
+
+    setStep: function (el, index) {
+      const inst = this.instances.get(el);
+      if (inst) inst.setStep(index);
+    },
+
+    next: function (el) {
+      const inst = this.instances.get(el);
+      if (inst) inst.next();
+    },
+
+    prev: function (el) {
+      const inst = this.instances.get(el);
+      if (inst) inst.prev();
+    },
+
+    destroy: function (el) {
+      const inst = this.instances.get(el);
+      if (!inst) return;
+      inst.cleanup.forEach(fn => fn());
+      this.instances.delete(el);
+    },
+
+    destroyAll: function () {
+      this.instances.forEach((_, el) => this.destroy(el));
+    }
+  };
+
+  if (typeof window.Vanduo !== 'undefined') {
+    window.Vanduo.register('stepper', Stepper);
+  }
+
+  window.VanduoStepper = Stepper;
+
+})();

package/js/components/suggest.js

@@ -0,0 +1,219 @@
+/**
+ * Vanduo Framework - Suggest (Autocomplete) Component
+ * Dropdown suggestion list with keyboard navigation, static/async data sources
+ */
+
+(function () {
+  'use strict';
+
+  const Suggest = {
+    instances: new Map(),
+
+    init: function () {
+      const inputs = document.querySelectorAll('[data-vd-suggest], [data-vd-autocomplete]');
+      inputs.forEach(el => {
+        if (this.instances.has(el)) return;
+        this.initInstance(el);
+      });
+    },
+
+    initInstance: function (input) {
+      const cleanup = [];
+      const minChars = parseInt(input.getAttribute('data-vd-suggest-min-chars') || '1', 10);
+      const url = input.getAttribute('data-vd-suggest-url') || '';
+      const staticData = input.getAttribute('data-vd-suggest') || input.getAttribute('data-vd-autocomplete') || '';
+      let items = [];
+
+      try { items = JSON.parse(staticData); } catch (_e) {
+        items = staticData.split(',').map(s => s.trim()).filter(Boolean);
+      }
+
+      // Wrap input if not already wrapped
+      let wrapper = input.closest('.vd-suggest-wrapper, .vd-autocomplete-wrapper');
+      if (!wrapper) {
+        wrapper = document.createElement('div');
+        wrapper.className = 'vd-suggest-wrapper';
+        input.parentNode.insertBefore(wrapper, input);
+        wrapper.appendChild(input);
+      }
+
+      // Create dropdown list
+      const list = document.createElement('ul');
+      list.className = 'vd-suggest-list';
+      list.setAttribute('role', 'listbox');
+      const listId = 'vd-suggest-' + Math.random().toString(36).slice(2, 9);
+      list.id = listId;
+      wrapper.appendChild(list);
+
+      // ARIA
+      input.setAttribute('role', 'combobox');
+      input.setAttribute('aria-autocomplete', 'list');
+      input.setAttribute('aria-expanded', 'false');
+      input.setAttribute('aria-controls', listId);
+      input.setAttribute('autocomplete', 'off');
+
+      let highlighted = -1;
+      let currentItems = [];
+      let debounceTimer = null;
+
+      const renderItems = (filtered, query) => {
+        list.innerHTML = '';
+        currentItems = filtered;
+        highlighted = -1;
+
+        if (filtered.length === 0) {
+          const empty = document.createElement('li');
+          empty.className = 'vd-suggest-empty';
+          empty.textContent = 'No results';
+          list.appendChild(empty);
+          return;
+        }
+
+        filtered.forEach((item, i) => {
+          const li = document.createElement('li');
+          li.className = 'vd-suggest-item';
+          li.setAttribute('role', 'option');
+          li.id = listId + '-item-' + i;
+
+          const text = typeof item === 'object' ? (item.label || item.text || String(item)) : String(item);
+          if (query) {
+            const re = new RegExp('(' + query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ')', 'gi');
+            li.innerHTML = text.replace(re, '<span class="vd-suggest-match">$1</span>');
+          } else {
+            li.textContent = text;
+          }
+
+          li.addEventListener('click', () => selectItem(i));
+          list.appendChild(li);
+        });
+      };
+
+      const open = () => {
+        list.classList.add('is-open');
+        input.setAttribute('aria-expanded', 'true');
+      };
+
+      const close = () => {
+        list.classList.remove('is-open');
+        input.setAttribute('aria-expanded', 'false');
+        highlighted = -1;
+        input.removeAttribute('aria-activedescendant');
+      };
+
+      const selectItem = (index) => {
+        const item = currentItems[index];
+        const value = typeof item === 'object' ? (item.value || item.label || String(item)) : String(item);
+        input.value = value;
+        close();
+        input.dispatchEvent(new CustomEvent('suggest:select', {
+          detail: { value, item, index },
+          bubbles: true
+        }));
+      };
+
+      const highlight = (index) => {
+        const listItems = list.querySelectorAll('.vd-suggest-item');
+        listItems.forEach(li => li.classList.remove('is-highlighted'));
+        if (index >= 0 && index < listItems.length) {
+          highlighted = index;
+          listItems[index].classList.add('is-highlighted');
+          input.setAttribute('aria-activedescendant', listItems[index].id);
+          listItems[index].scrollIntoView({ block: 'nearest' });
+        }
+      };
+
+      const doSearch = async (query) => {
+        if (query.length < minChars) { close(); return; }
+
+        let filtered;
+        if (url) {
+          try {
+            const separator = url.includes('?') ? '&' : '?';
+            const res = await window.fetch(url + separator + 'q=' + encodeURIComponent(query));
+            filtered = await res.json();
+          } catch (_e) {
+            filtered = [];
+          }
+        } else {
+          const lower = query.toLowerCase();
+          filtered = items.filter(item => {
+            const text = typeof item === 'object' ? (item.label || item.text || String(item)) : String(item);
+            return text.toLowerCase().includes(lower);
+          });
+        }
+
+        renderItems(filtered, query);
+        if (filtered.length > 0) open();
+        else open(); // show "no results"
+      };
+
+      const inputHandler = () => {
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => doSearch(input.value), 200);
+      };
+
+      const keyHandler = (e) => {
+        if (!list.classList.contains('is-open')) {
+          if (e.key === 'ArrowDown') { doSearch(input.value); e.preventDefault(); }
+          return;
+        }
+
+        const total = currentItems.length;
+        switch (e.key) {
+          case 'ArrowDown':
+            e.preventDefault();
+            highlight(highlighted < total - 1 ? highlighted + 1 : 0);
+            break;
+          case 'ArrowUp':
+            e.preventDefault();
+            highlight(highlighted > 0 ? highlighted - 1 : total - 1);
+            break;
+          case 'Enter':
+            e.preventDefault();
+            if (highlighted >= 0) selectItem(highlighted);
+            break;
+          case 'Escape':
+            close();
+            break;
+        }
+      };
+
+      const blurHandler = () => {
+        setTimeout(close, 200);
+      };
+
+      input.addEventListener('input', inputHandler);
+      input.addEventListener('keydown', keyHandler);
+      input.addEventListener('blur', blurHandler);
+      input.addEventListener('focus', () => { if (input.value.length >= minChars) doSearch(input.value); });
+
+      cleanup.push(
+        () => input.removeEventListener('input', inputHandler),
+        () => input.removeEventListener('keydown', keyHandler),
+        () => input.removeEventListener('blur', blurHandler),
+        () => clearTimeout(debounceTimer),
+        () => { if (list.parentNode) list.parentNode.removeChild(list); }
+      );
+
+      this.instances.set(input, { cleanup, list, close });
+    },
+
+    destroy: function (el) {
+      const instance = this.instances.get(el);
+      if (!instance) return;
+      instance.cleanup.forEach(fn => fn());
+      this.instances.delete(el);
+    },
+
+    destroyAll: function () {
+      this.instances.forEach((_, el) => this.destroy(el));
+    }
+  };
+
+  if (typeof window.Vanduo !== 'undefined') {
+    window.Vanduo.register('suggest', Suggest);
+  }
+
+  window.VanduoSuggest = Suggest;
+
+})();

package/js/components/theme-customizer.js

@@ -251,8 +251,14 @@
         mode = this.DEFAULTS.THEME;
       }
 
+      // Prevent circular updates
+      this._isApplying = true;
+
       // Check if we should switch primary color (if using default)
-      const oldDefault = this.getDefaultPrimary(this.state.theme);
+      // Use the incoming mode for both old and new default checks since
+      // ThemeSwitcher calls this with the new mode before updating its own state
+      const currentMode = this.state.theme;
+      const oldDefault = this.getDefaultPrimary(currentMode);
       if (this.state.primary === oldDefault) {
         const newDefault = this.getDefaultPrimary(mode);
         if (newDefault !== this.state.primary) {
@@ -271,13 +277,16 @@
       this.savePreference(this.STORAGE_KEYS.THEME, mode);
 
       // Also update the existing ThemeSwitcher if available
+      // Only update state, don't call setPreference to avoid circular calls
       if (window.Vanduo && window.Vanduo.components.themeSwitcher) {
         const themeSwitcher = window.Vanduo.components.themeSwitcher;
-        if (themeSwitcher.state) {
+        if (themeSwitcher.state && themeSwitcher.state.preference !== mode) {
           themeSwitcher.state.preference = mode;
+          themeSwitcher.savePreference(themeSwitcher.STORAGE_KEY, mode);
         }
       }
 
+      this._isApplying = false;
       this.dispatchEvent('mode-change', { mode: mode });
     },
 

package/js/components/theme-switcher.js

@@ -41,6 +41,13 @@
       this.state.preference = pref;
       this.setStorageValue(this.STORAGE_KEY, pref);
       this.applyTheme();
+      
+      // Coordinate with ThemeCustomizer for primary color swap if available
+      // Check _isApplying flag to prevent circular updates
+      if (window.ThemeCustomizer && window.ThemeCustomizer.applyTheme && !window.ThemeCustomizer._isApplying) {
+        window.ThemeCustomizer.applyTheme(pref);
+      }
+      
       this.updateUI();
     },