@customviews-js/customviews 1.1.11 → 1.2.0

package/dist/custom-views.esm.js

@@ -1,5 +1,5 @@
 /*!
- * @customviews-js/customviews v1.1.11
+ * @customviews-js/customviews v1.2.0
  * (c) 2025 Chan Ger Teck
  * Released under the MIT License.
  */
@@ -414,7 +414,7 @@ function getPinIcon(isPinned = false) {
 }
 
 // Constants for selectors
-const TABGROUP_SELECTOR = 'cv-tabgroup';
+const TABGROUP_SELECTOR$1 = 'cv-tabgroup';
 const TAB_SELECTOR = 'cv-tab';
 const NAV_AUTO_SELECTOR = 'cv-tabgroup[nav="auto"], cv-tabgroup:not([nav])';
 const NAV_CONTAINER_CLASS = 'cv-tabs-nav';
@@ -430,11 +430,9 @@ class TabManager {
         return trimmedIds;
     }
     /**
-     * Apply tab selections to all tab groups in the DOM
+     * Apply tab selections to a given list of tab group elements
      */
-    static applyTabSelections(rootEl, tabs, cfgGroups) {
-        // Find all cv-tabgroup elements
-        const tabGroups = rootEl.querySelectorAll(TABGROUP_SELECTOR);
+    static applyTabSelections(tabGroups, tabs, cfgGroups) {
         tabGroups.forEach((groupEl) => {
             const groupId = groupEl.getAttribute('id');
             // Determine the active tab for this group
@@ -539,10 +537,18 @@ class TabManager {
     /**
      * Build navigation for tab groups (one-time setup)
      */
-    static buildNavs(rootEl, cfgGroups, onTabClick, onTabDoubleClick) {
-        // Find all cv-tabgroup elements with nav="auto" or no nav attribute
-        const tabGroups = rootEl.querySelectorAll(NAV_AUTO_SELECTOR);
+    static buildNavs(tabGroups, cfgGroups, onTabClick, onTabDoubleClick) {
+        const rootEl = document.body; // Needed for NAV_HIDE_ROOT_CLASS check
         tabGroups.forEach((groupEl) => {
+            // Prevent re-initialization
+            if (groupEl.hasAttribute('data-cv-initialized')) {
+                return;
+            }
+            groupEl.setAttribute('data-cv-initialized', 'true');
+            // Filter to only build for groups with nav="auto" or no nav attribute
+            if (!groupEl.matches(NAV_AUTO_SELECTOR)) {
+                return;
+            }
             const groupId = groupEl.getAttribute('id') || null;
             // Note: groupId can be null for standalone tabgroups
             // These won't sync with other groups or persist state
@@ -746,8 +752,7 @@ class TabManager {
     /**
      * Update active states for all tab groups based on current state
      */
-    static updateAllNavActiveStates(rootEl, tabs, cfgGroups) {
-        const tabGroups = rootEl.querySelectorAll(TABGROUP_SELECTOR);
+    static updateAllNavActiveStates(tabGroups, tabs, cfgGroups) {
         tabGroups.forEach((groupEl) => {
             const groupId = groupEl.getAttribute('id');
             if (!groupId)
@@ -810,7 +815,7 @@ class TabManager {
      */
     static getTabgroupsWithId(rootEl, sourceGroupId, tabId) {
         const syncedGroupEls = [];
-        const allGroupEls = Array.from(rootEl.querySelectorAll(`${TABGROUP_SELECTOR}[id="${sourceGroupId}"]`));
+        const allGroupEls = Array.from(rootEl.querySelectorAll(`${TABGROUP_SELECTOR$1}[id="${sourceGroupId}"]`));
         allGroupEls.forEach((targetGroupEl) => {
             // Only sync if target group actually contains this tab
             if (this.groupHasTab(targetGroupEl, tabId)) {
@@ -822,9 +827,8 @@ class TabManager {
     /**
      * Update pin icon visibility for all tab groups based on current state.
      * Shows pin icon for tabs that are in the persisted state (i.e., have been double-clicked).
-     */
-    static updatePinIcons(rootEl, tabs) {
-        const tabGroups = rootEl.querySelectorAll(TABGROUP_SELECTOR);
+      */
+    static updatePinIcons(tabGroups, tabs) {
         tabGroups.forEach((groupEl) => {
             const groupId = groupEl.getAttribute('id');
             if (!groupId)
@@ -974,33 +978,31 @@ function renderAssetInto(el, assetId, assetsManager) {
     }
 }
 
-// Constants for selectors
-const TOGGLE_DATA_SELECTOR = "[data-cv-toggle], [data-customviews-toggle]";
-const TOGGLE_ELEMENT_SELECTOR = "cv-toggle";
-const TOGGLE_SELECTOR = `${TOGGLE_DATA_SELECTOR}, ${TOGGLE_ELEMENT_SELECTOR}`;
 /**
  * ToggleManager handles discovery, visibility, and asset rendering for toggle elements
  */
 class ToggleManager {
     /**
-     * Apply toggle visibility to all toggle elements in the DOM
+     * Apply toggle visibility to a given list of toggle elements
      */
-    static applyToggles(rootEl, activeToggles) {
-        rootEl.querySelectorAll(TOGGLE_SELECTOR).forEach(el => {
+    static applyToggles(elements, activeToggles) {
+        elements.forEach(el => {
             const categories = this.getToggleCategories(el);
             const shouldShow = categories.some(cat => activeToggles.includes(cat));
             this.applyToggleVisibility(el, shouldShow);
         });
     }
     /**
-     * Render assets into toggle elements that are currently visible
+     * Render assets into a given list of toggle elements that are currently visible
      */
-    static renderAssets(rootEl, activeToggles, assetsManager) {
-        rootEl.querySelectorAll(TOGGLE_SELECTOR).forEach(el => {
+    static renderAssets(elements, activeToggles, assetsManager) {
+        elements.forEach(el => {
             const categories = this.getToggleCategories(el);
             const toggleId = this.getToggleId(el);
-            if (toggleId && categories.some(cat => activeToggles.includes(cat))) {
+            const isRendered = el.dataset.cvRendered === 'true';
+            if (toggleId && !isRendered && categories.some(cat => activeToggles.includes(cat))) {
                 renderAssetInto(el, toggleId, assetsManager);
+                el.dataset.cvRendered = 'true';
             }
         });
     }
@@ -1036,6 +1038,21 @@ class ToggleManager {
             el.classList.remove('cv-visible');
         }
     }
+    /**
+     * Scans a given DOM subtree for toggle elements and initializes them.
+     * This includes applying visibility and rendering assets.
+     */
+    static initializeToggles(root, activeToggles, assetsManager) {
+        const elements = [];
+        if (root.matches('[data-cv-toggle], [data-customviews-toggle], cv-toggle')) {
+            elements.push(root);
+        }
+        root.querySelectorAll('[data-cv-toggle], [data-customviews-toggle], cv-toggle').forEach(el => elements.push(el));
+        if (elements.length === 0)
+            return;
+        this.applyToggles(elements, activeToggles);
+        this.renderAssets(elements, activeToggles, assetsManager);
+    }
 }
 
 // src/utils/scroll-manager.ts
@@ -1359,11 +1376,18 @@ function injectCoreStyles() {
     document.head.appendChild(style);
 }
 
+const TOGGLE_SELECTOR = "[data-cv-toggle], [data-customviews-toggle], cv-toggle";
+const TABGROUP_SELECTOR = 'cv-tabgroup';
 class CustomViewsCore {
     rootEl;
     assetsManager;
     persistenceManager;
     visibilityManager;
+    observer = null;
+    componentRegistry = {
+        toggles: new Set(),
+        tabGroups: new Set(),
+    };
     config;
     stateChangeListeners = [];
     showUrlEnabled;
@@ -1377,6 +1401,57 @@ class CustomViewsCore {
         this.showUrlEnabled = opt.showUrl ?? false;
         this.lastAppliedState = this.cloneState(this.getComputedDefaultState());
     }
+    /**
+     * Scan the given element for toggles and tab groups, register them
+     * Returns true if new components were found
+     */
+    scan(element) {
+        let newComponentsFound = false;
+        // Scan for toggles
+        const toggles = Array.from(element.querySelectorAll(TOGGLE_SELECTOR));
+        if (element.matches(TOGGLE_SELECTOR)) {
+            toggles.unshift(element);
+        }
+        toggles.forEach((toggle) => {
+            if (!this.componentRegistry.toggles.has(toggle)) {
+                this.componentRegistry.toggles.add(toggle);
+                newComponentsFound = true;
+            }
+        });
+        // Scan for tab groups
+        const tabGroups = Array.from(element.querySelectorAll(TABGROUP_SELECTOR));
+        if (element.matches(TABGROUP_SELECTOR)) {
+            tabGroups.unshift(element);
+        }
+        tabGroups.forEach((tabGroup) => {
+            if (!this.componentRegistry.tabGroups.has(tabGroup)) {
+                this.componentRegistry.tabGroups.add(tabGroup);
+                newComponentsFound = true;
+            }
+        });
+        return newComponentsFound;
+    }
+    /**
+     * Unscan the given element for toggles and tab groups, de-register them
+     */
+    unscan(element) {
+        // Unscan for toggles
+        const toggles = Array.from(element.querySelectorAll(TOGGLE_SELECTOR));
+        if (element.matches(TOGGLE_SELECTOR)) {
+            toggles.unshift(element);
+        }
+        toggles.forEach((toggle) => {
+            this.componentRegistry.toggles.delete(toggle);
+        });
+        // Unscan for tab groups
+        const tabGroups = Array.from(element.querySelectorAll(TABGROUP_SELECTOR));
+        if (element.matches(TABGROUP_SELECTOR)) {
+            tabGroups.unshift(element);
+        }
+        tabGroups.forEach((tabGroup) => {
+            this.componentRegistry.tabGroups.delete(tabGroup);
+        });
+    }
     getConfig() {
         return this.config;
     }
@@ -1411,7 +1486,7 @@ class CustomViewsCore {
             });
         }
         const computedState = {
-            toggles: [...(this.config.allToggles || [])],
+            toggles: this.config.toggles?.map(t => t.id) || [],
             tabs
         };
         return computedState;
@@ -1450,8 +1525,25 @@ class CustomViewsCore {
     // Inject styles, setup listeners and call rendering logic
     async init() {
         injectCoreStyles();
-        // Build navigation once (with click and double-click handlers)
-        TabManager.buildNavs(this.rootEl, this.config.tabGroups, 
+        this.scan(this.rootEl);
+        // Initialize all components found on initial scan
+        this.initializeNewComponents();
+        // Apply stored nav visibility preference on page load
+        const navPref = this.persistenceManager.getPersistedTabNavVisibility();
+        if (navPref !== null) {
+            TabManager.setNavsVisibility(this.rootEl, navPref);
+        }
+        // For session history, clicks on back/forward button
+        window.addEventListener("popstate", () => {
+            this.loadAndCallApplyState();
+        });
+        this.loadAndCallApplyState();
+        this.initObserver();
+    }
+    initializeNewComponents() {
+        // Build navigation for any newly added tab groups.
+        // The `data-cv-initialized` attribute in `buildNavs` prevents re-initialization.
+        TabManager.buildNavs(Array.from(this.componentRegistry.tabGroups), this.config.tabGroups, 
         // Single click: update clicked group only (local, no persistence)
         (groupId, tabId, groupEl) => {
             this.setActiveTab(groupId, tabId, groupEl);
@@ -1474,16 +1566,46 @@ class CustomViewsCore {
                 scrollAnchor: { element: anchorElement, top: initialTop }
             });
         });
-        // Apply stored nav visibility preference on page load
-        const navPref = this.persistenceManager.getPersistedTabNavVisibility();
-        if (navPref !== null) {
-            TabManager.setNavsVisibility(this.rootEl, navPref);
-        }
-        // For session history, clicks on back/forward button
-        window.addEventListener("popstate", () => {
-            this.loadAndCallApplyState();
+        // Future components (e.g., toggles, widgets) can be initialized here
+    }
+    initObserver() {
+        this.observer = new MutationObserver((mutations) => {
+            let newComponentsFound = false;
+            for (const mutation of mutations) {
+                if (mutation.type === 'childList') {
+                    mutation.addedNodes.forEach((node) => {
+                        if (node instanceof Element) {
+                            // Scan the new node for components and add them to the registry
+                            if (this.scan(node)) {
+                                newComponentsFound = true;
+                            }
+                        }
+                    });
+                    mutation.removedNodes.forEach((node) => {
+                        if (node instanceof Element) {
+                            // Unscan the removed node to cleanup the registry
+                            this.unscan(node);
+                        }
+                    });
+                }
+            }
+            if (newComponentsFound) {
+                // Initialize navs for new components.
+                this.initializeNewComponents();
+                // Re-apply the last known state. renderState will handle disconnecting
+                // the observer to prevent infinite loops.
+                if (this.lastAppliedState) {
+                    this.renderState(this.lastAppliedState);
+                }
+            }
         });
-        this.loadAndCallApplyState();
+        // Observe only the root element to avoid performance issues on large pages.
+        if (this.rootEl) {
+            this.observer.observe(this.rootEl, {
+                childList: true,
+                subtree: true,
+            });
+        }
     }
     // Priority: URL state > persisted state > config default > computed default
     // Also filters using the visibility manager to persist selection
@@ -1537,23 +1659,34 @@ class CustomViewsCore {
             ScrollManager.handleScrollAnchor(options.scrollAnchor);
         }
     }
-    /** Render all toggles for the current state */
+    /**
+     * Renders state on components in ComponentRegistry
+     * Applies the given state.
+     * Disconnects the mutation observer during rendering to prevent loops
+     **/
     renderState(state) {
+        this.observer?.disconnect();
         this.lastAppliedState = this.cloneState(state);
         const toggles = state?.toggles || [];
         const finalToggles = this.visibilityManager.filterVisibleToggles(toggles);
+        const toggleElements = Array.from(this.componentRegistry.toggles);
+        const tabGroupElements = Array.from(this.componentRegistry.tabGroups);
         // Apply toggle visibility
-        ToggleManager.applyToggles(this.rootEl, finalToggles);
+        ToggleManager.applyToggles(toggleElements, finalToggles);
         // Render assets into toggles
-        ToggleManager.renderAssets(this.rootEl, finalToggles, this.assetsManager);
+        ToggleManager.renderAssets(toggleElements, finalToggles, this.assetsManager);
         // Apply tab selections
-        TabManager.applyTabSelections(this.rootEl, state.tabs || {}, this.config.tabGroups);
+        TabManager.applyTabSelections(tabGroupElements, state.tabs || {}, this.config.tabGroups);
         // Update nav active states (without rebuilding)
-        TabManager.updateAllNavActiveStates(this.rootEl, state.tabs || {}, this.config.tabGroups);
+        TabManager.updateAllNavActiveStates(tabGroupElements, state.tabs || {}, this.config.tabGroups);
         // Update pin icons to show which tabs are persisted
-        TabManager.updatePinIcons(this.rootEl, state.tabs || {});
+        TabManager.updatePinIcons(tabGroupElements, state.tabs || {});
         // Notify state change listeners (like widgets)
         this.notifyStateChangeListeners();
+        this.observer?.observe(document.body, {
+            childList: true,
+            subtree: true,
+        });
     }
     /**
      * Reset to default state
@@ -1805,7 +1938,7 @@ class CustomViews {
         else {
             console.error("No config provided, using minimal default config");
             // Create a minimal default config
-            config = { allToggles: [], defaultState: {} };
+            config = { toggles: [], defaultState: {} };
         }
         const coreOptions = {
             assetsManager,
@@ -2062,6 +2195,10 @@ const WIDGET_STYLES = `
   animation: fadeIn 0.2s ease;
 }
 
+.cv-widget-modal-overlay.cv-hidden {
+  display: none;
+}
+
 @keyframes fadeIn {
   from { opacity: 0; }
   to { opacity: 1; }
@@ -2918,8 +3055,11 @@ class CustomViewsWidget {
     container;
     widgetIcon = null;
     options;
+    _hasVisibleConfig = false;
+    pageToggleIds = new Set();
+    pageTabIds = new Set();
     // Modal state
-    modal = null;
+    stateModal = null;
     constructor(options) {
         this.core = options.core;
         this.container = options.container || document.body;
@@ -2937,12 +3077,41 @@ class CustomViewsWidget {
             welcomeMessage: options.welcomeMessage || 'This site is powered by Custom Views. Use the widget on the side (⚙) to customize your experience. Your preferences will be saved and can be shared via URL.<br><br>Learn more at <a href="https://github.com/customviews-js/customviews" target="_blank">customviews GitHub</a>.',
             showTabGroups: options.showTabGroups ?? true
         };
-        // No external state manager to initialize
+        // Determine if there are any configurations to show
+        const config = this.core.getConfig();
+        const allToggles = config?.toggles || [];
+        const visibleToggles = allToggles.filter(toggle => {
+            if (toggle.isLocal) {
+                return !!document.querySelector(`[data-cv-toggle="${toggle.id}"], [data-cv-toggle-group-id="${toggle.id}"]`);
+            }
+            return true;
+        });
+        const allTabGroups = this.core.getTabGroups() || [];
+        const visibleTabGroups = allTabGroups.filter(group => {
+            if (group.isLocal) {
+                return !!document.querySelector(`cv-tabgroup[id="${group.id}"]`);
+            }
+            return true;
+        });
+        if (visibleToggles.length > 0 || (this.options.showTabGroups && visibleTabGroups.length > 0)) {
+            this._hasVisibleConfig = true;
+        }
+        // Scan for page-declared local components and cache them
+        // Do this on initialization to avoid querying DOM repeatedly
+        const pageTogglesAttr = document.querySelector('[data-cv-page-local-toggles]')?.getAttribute('data-cv-page-local-toggles') || '';
+        this.pageToggleIds = new Set(pageTogglesAttr.split(',').map(id => id.trim()).filter(id => id));
+        const pageTabsAttr = document.querySelector('[data-cv-page-local-tabs]')?.getAttribute('data-cv-page-local-tabs') || '';
+        this.pageTabIds = new Set(pageTabsAttr.split(',').map(id => id.trim()).filter(id => id));
     }
     /**
-     * Render the widget
+     * Render the widget modal icon
+     *
+     * Does not render if there are no visible toggles or tab groups.
      */
-    render() {
+    renderModalIcon() {
+        if (!this._hasVisibleConfig) {
+            return;
+        }
         this.widgetIcon = this.createWidgetIcon();
         this.attachEventListeners();
         // Always append to body since it's a floating icon
@@ -2975,9 +3144,9 @@ class CustomViewsWidget {
             this.widgetIcon = null;
         }
         // Clean up modal
-        if (this.modal) {
-            this.modal.remove();
-            this.modal = null;
+        if (this.stateModal) {
+            this.stateModal.remove();
+            this.stateModal = null;
         }
     }
     attachEventListeners() {
@@ -2990,49 +3159,71 @@ class CustomViewsWidget {
      * Close the modal
      */
     closeModal() {
-        if (this.modal) {
-            this.modal.remove();
-            this.modal = null;
+        if (this.stateModal) {
+            this.stateModal.classList.add('cv-hidden');
         }
     }
     /**
      * Open the custom state creator
      */
     openStateModal() {
-        // Get toggles from current configuration and open the modal regardless of count
-        const config = this.core.getConfig();
-        const toggles = config?.allToggles || [];
-        this.createCustomStateModal(toggles);
+        if (!this.stateModal) {
+            this._createStateModal();
+        }
+        this._updateStateModalContent();
+        this.stateModal.classList.remove('cv-hidden');
     }
     /**
-     * Create the custom state creator modal
+     * Create the custom state creator modal shell and attach listeners
      */
-    createCustomStateModal(toggles) {
-        // Close existing modal
-        this.closeModal();
-        this.modal = document.createElement('div');
-        this.modal.className = 'cv-widget-modal-overlay';
+    _createStateModal() {
+        this.stateModal = document.createElement('div');
+        this.stateModal.className = 'cv-widget-modal-overlay cv-hidden';
         this.applyThemeToModal();
-        const toggleControlsHtml = toggles.map(toggle => `
+        document.body.appendChild(this.stateModal);
+        this._attachStateModalFrameEventListeners();
+    }
+    /**
+     * Update the content of the state modal
+     */
+    _updateStateModalContent() {
+        if (!this.stateModal)
+            return;
+        const pageToggleIds = this.pageToggleIds;
+        const pageTabIds = this.pageTabIds;
+        // Get toggles from current configuration
+        const config = this.core.getConfig();
+        const allToggles = config?.toggles || [];
+        // Filter toggles to only include global and visible/declared local toggles
+        const visibleToggles = allToggles.filter(toggle => {
+            if (toggle.isLocal) {
+                return pageToggleIds.has(toggle.id) || !!document.querySelector(`[data-cv-toggle="${toggle.id}"], [data-cv-toggle-group-id="${toggle.id}"]`);
+            }
+            return true; // Keep global toggles
+        });
+        const toggleControlsHtml = visibleToggles.map(toggle => `
       <div class="cv-toggle-card">
         <div class="cv-toggle-content">
           <div>
-            <p class="cv-toggle-title">${this.formatToggleName(toggle)}</p>
+            <p class="cv-toggle-title">${toggle.label || toggle.id}</p>
           </div>
           <label class="cv-toggle-label">
-            <input class="cv-toggle-input" type="checkbox" data-toggle="${toggle}"/>
+            <input class="cv-toggle-input" type="checkbox" data-toggle="${toggle.id}"/>
             <span class="cv-toggle-slider"></span>
           </label>
         </div>
       </div>
     `).join('');
-        // Todo: Re-add description if needed (Line 168, add label field to toggles if needed change structure)
-        // <p class="cv-toggle-description">Show or hide the ${this.formatToggleName(toggle).toLowerCase()} area </p>
         // Get tab groups
-        const tabGroups = this.core.getTabGroups();
+        const allTabGroups = this.core.getTabGroups() || [];
+        const tabGroups = allTabGroups.filter(group => {
+            if (group.isLocal) {
+                return pageTabIds.has(group.id) || !!document.querySelector(`cv-tabgroup[id="${group.id}"]`);
+            }
+            return true; // Keep global tab groups
+        });
         let tabGroupControlsHTML = '';
         if (this.options.showTabGroups && tabGroups && tabGroups.length > 0) {
-            // Determine initial nav visibility state
             const initialNavsVisible = TabManager.areNavsVisible(document.body);
             tabGroupControlsHTML = `
         <div class="cv-tabgroup-card cv-tabgroup-header">
@@ -3067,7 +3258,7 @@ class CustomViewsWidget {
         </div>
       `;
         }
-        this.modal.innerHTML = `
+        this.stateModal.innerHTML = `
       <div class="cv-widget-modal cv-custom-state-modal">
         <header class="cv-modal-header">
           <div class="cv-modal-header-content">
@@ -3083,7 +3274,7 @@ class CustomViewsWidget {
         <main class="cv-modal-main">
           ${this.options.description ? `<p class="cv-modal-description">${this.options.description}</p>` : ''}
           
-          ${toggles.length ? `
+          ${visibleToggles.length ? `
           <div class="cv-content-section">
             <div class="cv-section-heading">Toggles</div>
             <div class="cv-toggles-container">
@@ -3116,62 +3307,76 @@ class CustomViewsWidget {
         </footer>
       </div>
     `;
-        document.body.appendChild(this.modal);
-        this.attachStateModalEventListeners();
-        // Load current state into form if we're already in a custom state
+        this._attachStateModalContentEventListeners();
         this.loadCurrentStateIntoForm();
     }
     /**
-     * Attach event listeners for custom state creator
+     * Attach event listeners for the modal frame (delegated events)
      */
-    attachStateModalEventListeners() {
-        if (!this.modal)
+    _attachStateModalFrameEventListeners() {
+        if (!this.stateModal)
             return;
-        // Close button
-        const closeBtn = this.modal.querySelector('.cv-modal-close');
-        if (closeBtn) {
-            closeBtn.addEventListener('click', () => {
+        // Delegated click events
+        this.stateModal.addEventListener('click', (e) => {
+            const target = e.target;
+            // Close button
+            if (target.closest('.cv-modal-close')) {
                 this.closeModal();
-            });
-        }
-        // Copy URL button
-        const copyUrlBtn = this.modal.querySelector('.cv-share-btn');
-        if (copyUrlBtn) {
-            copyUrlBtn.addEventListener('click', () => {
+                return;
+            }
+            // Copy URL button
+            if (target.closest('.cv-share-btn')) {
                 this.copyShareableURL();
-                // Visual feedback: change icon to tick for 3 seconds
-                const iconContainer = copyUrlBtn.querySelector('.cv-share-btn-icon');
+                const copyUrlBtn = target.closest('.cv-share-btn');
+                const iconContainer = copyUrlBtn?.querySelector('.cv-share-btn-icon');
                 if (iconContainer) {
                     const originalIcon = iconContainer.innerHTML;
                     iconContainer.innerHTML = getTickIcon();
-                    // Revert after 3 seconds
                     setTimeout(() => {
                         iconContainer.innerHTML = originalIcon;
                     }, 3000);
                 }
-            });
-        }
-        // Reset to default button
-        const resetBtn = this.modal.querySelector('.cv-reset-btn');
-        if (resetBtn) {
-            resetBtn.addEventListener('click', () => {
-                // Add spinning animation to icon
-                const resetIcon = resetBtn.querySelector('.cv-reset-btn-icon');
+                return;
+            }
+            // Reset to default button
+            if (target.closest('.cv-reset-btn')) {
+                const resetBtn = target.closest('.cv-reset-btn');
+                const resetIcon = resetBtn?.querySelector('.cv-reset-btn-icon');
                 if (resetIcon) {
                     resetIcon.classList.add('cv-spinning');
                 }
                 this.core.resetToDefault();
                 this.loadCurrentStateIntoForm();
-                // Remove spinning animation after it completes
                 setTimeout(() => {
                     if (resetIcon) {
                         resetIcon.classList.remove('cv-spinning');
                     }
-                }, 600); // 600ms matches the animation duration
-            });
-        }
+                }, 600);
+                return;
+            }
+            // Overlay click to close
+            if (e.target === this.stateModal) {
+                this.closeModal();
+            }
+        });
+        // Escape key to close
+        const handleEscape = (e) => {
+            if (e.key === 'Escape') {
+                this.closeModal();
+            }
+        };
+        // We can't remove this listener easily if it's anonymous, so we attach it to the document
+        // and it will stay for the lifetime of the widget. This is acceptable.
+        document.addEventListener('keydown', handleEscape);
+    }
+    /**
+     * Attach event listeners for custom state creator's dynamic content
+     */
+    _attachStateModalContentEventListeners() {
+        if (!this.stateModal)
+            return;
         // Listen to toggle switches
-        const toggleInputs = this.modal.querySelectorAll('.cv-toggle-input');
+        const toggleInputs = this.stateModal.querySelectorAll('.cv-toggle-input');
         toggleInputs.forEach(toggleInput => {
             toggleInput.addEventListener('change', () => {
                 const state = this.getCurrentCustomStateFromModal();
@@ -3179,17 +3384,14 @@ class CustomViewsWidget {
             });
         });
         // Listen to tab group selects
-        const tabGroupSelects = this.modal.querySelectorAll('.cv-tabgroup-select');
+        const tabGroupSelects = this.stateModal.querySelectorAll('.cv-tabgroup-select');
         tabGroupSelects.forEach(select => {
             select.addEventListener('change', () => {
                 const groupId = select.dataset.groupId;
                 const tabId = select.value;
                 if (groupId && tabId) {
-                    // Get current state and update the tab for this group, then apply globally
-                    // This triggers sync behavior and persistence
                     const currentTabs = this.core.getCurrentActiveTabs();
                     currentTabs[groupId] = tabId;
-                    // Apply state globally for persistence and sync
                     const currentToggles = this.core.getCurrentActiveToggles();
                     const newState = {
                         toggles: currentToggles,
@@ -3200,84 +3402,56 @@ class CustomViewsWidget {
             });
         });
         // Listener for show/hide tab navs
-        const tabNavToggle = this.modal.querySelector('.cv-nav-pref-input');
-        const navIcon = this.modal?.querySelector('#cv-nav-icon');
-        const navHeaderCard = this.modal?.querySelector('.cv-tabgroup-card.cv-tabgroup-header');
+        const tabNavToggle = this.stateModal.querySelector('.cv-nav-pref-input');
+        const navIcon = this.stateModal?.querySelector('#cv-nav-icon');
+        const navHeaderCard = this.stateModal?.querySelector('.cv-tabgroup-card.cv-tabgroup-header');
         if (tabNavToggle && navIcon && navHeaderCard) {
-            // Helper to update icon based on state
             const updateIcon = (isVisible, isHovering = false) => {
                 if (isHovering) {
-                    // On hover, show the transition icon
                     navIcon.innerHTML = getNavDashed();
                 }
                 else {
-                    // Normal state, show the status icon (on if visible, off if hidden)
                     navIcon.innerHTML = isVisible ? getNavHeadingOnIcon() : getNavHeadingOffIcon();
                 }
             };
-            // Add hover listeners to entire header card
-            navHeaderCard.addEventListener('mouseenter', () => {
-                updateIcon(tabNavToggle.checked, true);
-            });
-            navHeaderCard.addEventListener('mouseleave', () => {
-                updateIcon(tabNavToggle.checked, false);
-            });
-            // Add change listener
+            navHeaderCard.addEventListener('mouseenter', () => updateIcon(tabNavToggle.checked, true));
+            navHeaderCard.addEventListener('mouseleave', () => updateIcon(tabNavToggle.checked, false));
             tabNavToggle.addEventListener('change', () => {
                 const visible = tabNavToggle.checked;
-                // Update the icon based on new state (not hovering)
                 updateIcon(visible, false);
-                // Persist preference via core
                 this.core.persistTabNavVisibility(visible);
-                // Apply to DOM using TabManager via core
                 try {
-                    const rootEl = document.body;
-                    TabManager.setNavsVisibility(rootEl, visible);
+                    TabManager.setNavsVisibility(document.body, visible);
                 }
                 catch (e) {
-                    // ignore errors
                     console.error('Failed to set tab nav visibility:', e);
                 }
             });
         }
-        // Overlay click to close
-        this.modal.addEventListener('click', (e) => {
-            if (e.target === this.modal) {
-                this.closeModal();
-            }
-        });
-        // Escape key to close
-        const handleEscape = (e) => {
-            if (e.key === 'Escape') {
-                this.closeModal();
-                document.removeEventListener('keydown', handleEscape);
-            }
-        };
-        document.addEventListener('keydown', handleEscape);
     }
     /**
      * Apply theme class to the modal overlay based on options
      */
     applyThemeToModal() {
-        if (!this.modal)
+        if (!this.stateModal)
             return;
         if (this.options.theme === 'dark') {
-            this.modal.classList.add('cv-widget-theme-dark');
+            this.stateModal.classList.add('cv-widget-theme-dark');
         }
         else {
-            this.modal.classList.remove('cv-widget-theme-dark');
+            this.stateModal.classList.remove('cv-widget-theme-dark');
         }
     }
     /**
      * Get current state from form values
      */
     getCurrentCustomStateFromModal() {
-        if (!this.modal) {
+        if (!this.stateModal) {
             return {};
         }
         // Collect toggle values
         const toggles = [];
-        const toggleInputs = this.modal.querySelectorAll('.cv-toggle-input');
+        const toggleInputs = this.stateModal.querySelectorAll('.cv-toggle-input');
         toggleInputs.forEach(toggleInput => {
             const toggle = toggleInput.dataset.toggle;
             if (toggle && toggleInput.checked) {
@@ -3285,7 +3459,7 @@ class CustomViewsWidget {
             }
         });
         // Collect tab selections
-        const tabGroupSelects = this.modal.querySelectorAll('.cv-tabgroup-select');
+        const tabGroupSelects = this.stateModal.querySelectorAll('.cv-tabgroup-select');
         const tabs = {};
         tabGroupSelects.forEach(select => {
             const groupId = select.dataset.groupId;
@@ -3313,25 +3487,25 @@ class CustomViewsWidget {
      * Load current state into form based on currently active toggles
      */
     loadCurrentStateIntoForm() {
-        if (!this.modal)
+        if (!this.stateModal)
             return;
         // Get currently active toggles (from custom state or default configuration)
         const activeToggles = this.core.getCurrentActiveToggles();
         // First, uncheck all toggle inputs
-        const allToggleInputs = this.modal.querySelectorAll('.cv-toggle-input');
+        const allToggleInputs = this.stateModal.querySelectorAll('.cv-toggle-input');
         allToggleInputs.forEach(toggleInput => {
             toggleInput.checked = false;
         });
         // Then check the ones that should be active
         activeToggles.forEach(toggle => {
-            const toggleInput = this.modal?.querySelector(`[data-toggle="${toggle}"]`);
+            const toggleInput = this.stateModal?.querySelector(`[data-toggle="${toggle}"]`);
             if (toggleInput) {
                 toggleInput.checked = true;
             }
         });
         // Load tab group selections
         const activeTabs = this.core.getCurrentActiveTabs();
-        const tabGroupSelects = this.modal.querySelectorAll('.cv-tabgroup-select');
+        const tabGroupSelects = this.stateModal.querySelectorAll('.cv-tabgroup-select');
         tabGroupSelects.forEach(select => {
             const groupId = select.dataset.groupId;
             if (groupId && activeTabs[groupId]) {
@@ -3346,8 +3520,8 @@ class CustomViewsWidget {
             }
             return TabManager.areNavsVisible(document.body);
         })();
-        const tabNavToggle = this.modal.querySelector('.cv-nav-pref-input');
-        const navIcon = this.modal?.querySelector('#cv-nav-icon');
+        const tabNavToggle = this.stateModal.querySelector('.cv-nav-pref-input');
+        const navIcon = this.stateModal?.querySelector('#cv-nav-icon');
         if (tabNavToggle) {
             tabNavToggle.checked = navPref;
             // Ensure UI matches actual visibility
@@ -3358,33 +3532,22 @@ class CustomViewsWidget {
             }
         }
     }
-    /**
-     * Format toggle name for display
-     */
-    formatToggleName(toggle) {
-        return toggle.charAt(0).toUpperCase() + toggle.slice(1);
-    }
     /**
      * Check if this is the first visit and show welcome modal
      */
     showWelcomeModalIfFirstVisit() {
+        if (!this._hasVisibleConfig)
+            return;
         const STORAGE_KEY = 'cv-welcome-shown';
         // Check if welcome has been shown before
         const hasSeenWelcome = localStorage.getItem(STORAGE_KEY);
         if (!hasSeenWelcome) {
-            // Check if this page has any custom views elements
-            const hasCustomViewElements = document.querySelector('cv-tabgroup') !== null ||
-                document.querySelector('cv-tab') !== null ||
-                document.querySelector('cv-toggle') !== null ||
-                document.querySelector('[data-cv-toggle]') !== null;
-            if (hasCustomViewElements) {
-                // Show welcome modal after a short delay to let the page settle
-                setTimeout(() => {
-                    this.createWelcomeModal();
-                }, 500);
-                // Mark as shown
-                localStorage.setItem(STORAGE_KEY, 'true');
-            }
+            // Show welcome modal after a short delay to let the page settle
+            setTimeout(() => {
+                this.createWelcomeModal();
+            }, 500);
+            // Mark as shown
+            localStorage.setItem(STORAGE_KEY, 'true');
         }
     }
     /**
@@ -3392,12 +3555,14 @@ class CustomViewsWidget {
      */
     createWelcomeModal() {
         // Don't show if there's already a modal open
-        if (this.modal)
+        if (this.stateModal && !this.stateModal.classList.contains('cv-hidden'))
             return;
-        this.modal = document.createElement('div');
-        this.modal.className = 'cv-widget-modal-overlay cv-welcome-modal-overlay';
-        this.applyThemeToModal();
-        this.modal.innerHTML = `
+        const welcomeModal = document.createElement('div');
+        welcomeModal.className = 'cv-widget-modal-overlay cv-welcome-modal-overlay';
+        if (this.options.theme === 'dark') {
+            welcomeModal.classList.add('cv-widget-theme-dark');
+        }
+        welcomeModal.innerHTML = `
       <div class="cv-widget-modal cv-welcome-modal">
         <header class="cv-modal-header">
           <div class="cv-modal-header-content">
@@ -3421,33 +3586,32 @@ class CustomViewsWidget {
         </div>
       </div>
     `;
-        document.body.appendChild(this.modal);
-        this.attachWelcomeModalEventListeners();
+        document.body.appendChild(welcomeModal);
+        this.attachWelcomeModalEventListeners(welcomeModal);
     }
     /**
      * Attach event listeners for welcome modal
      */
-    attachWelcomeModalEventListeners() {
-        if (!this.modal)
-            return;
+    attachWelcomeModalEventListeners(welcomeModal) {
+        const closeModal = () => {
+            welcomeModal.remove();
+            document.removeEventListener('keydown', handleEscape);
+        };
         // Got it button
-        const gotItBtn = this.modal.querySelector('.cv-welcome-got-it');
+        const gotItBtn = welcomeModal.querySelector('.cv-welcome-got-it');
         if (gotItBtn) {
-            gotItBtn.addEventListener('click', () => {
-                this.closeModal();
-            });
+            gotItBtn.addEventListener('click', closeModal);
         }
         // Overlay click to close
-        this.modal.addEventListener('click', (e) => {
-            if (e.target === this.modal) {
-                this.closeModal();
+        welcomeModal.addEventListener('click', (e) => {
+            if (e.target === welcomeModal) {
+                closeModal();
             }
         });
         // Escape key to close
         const handleEscape = (e) => {
             if (e.key === 'Escape') {
-                this.closeModal();
-                document.removeEventListener('keydown', handleEscape);
+                closeModal();
             }
         };
         document.addEventListener('keydown', handleEscape);
@@ -3517,7 +3681,7 @@ function initializeFromScript() {
                     console.warn(`[CustomViews] Config file not found at ${fullConfigPath}. Using defaults.`);
                     // Provide minimal default config structure
                     configFile = {
-                        config: { allToggles: [], defaultState: {} },
+                        config: { toggles: [], defaultState: {} },
                         widget: { enabled: true }
                     };
                 }
@@ -3555,7 +3719,7 @@ function initializeFromScript() {
                     core,
                     ...configFile.widget
                 });
-                widget.render();
+                widget.renderModalIcon();
                 // Store widget instance
                 window.customViewsInstance.widget = widget;
                 console.log('[CustomViews] Widget initialized and rendered');