@customviews-js/customviews 1.0.2 → 1.1.0

package/dist/{custom-views.umd.js → custom-views.js}

@@ -1,5 +1,5 @@
 /*!
- * @customviews-js/customviews v1.0.2
+ * @customviews-js/customviews v1.1.0
  * (c) 2025 Chan Ger Teck
  * Released under the MIT License.
  */
@@ -86,18 +86,6 @@
         }
     }
 
-    /**
-     * Configuration for the site, has default state and list of toggles
-     */
-    class Config {
-        defaultState;
-        allToggles;
-        constructor(defaultState, allToggles) {
-            this.defaultState = defaultState;
-            this.allToggles = allToggles;
-        }
-    }
-
     /**
      * Manages persistence of custom views state using browser localStorage
      */
@@ -227,6 +215,10 @@
                 const compact = {
                     t: state.toggles
                 };
+                // Add tab groups if present
+                if (state.tabs && Object.keys(state.tabs).length > 0) {
+                    compact.g = Object.entries(state.tabs);
+                }
                 // Convert to JSON and encode
                 const json = JSON.stringify(compact);
                 let encoded;
@@ -273,9 +265,19 @@
                 if (!compact || typeof compact !== 'object') {
                     throw new Error('Invalid compact state structure');
                 }
-                return {
+                const state = {
                     toggles: Array.isArray(compact.t) ? compact.t : []
                 };
+                // Reconstruct tabs from compact format
+                if (Array.isArray(compact.g)) {
+                    state.tabs = {};
+                    for (const [groupId, tabId] of compact.g) {
+                        if (typeof groupId === 'string' && typeof tabId === 'string') {
+                            state.tabs[groupId] = tabId;
+                        }
+                    }
+                }
+                return state;
             }
             catch (error) {
                 console.warn('Failed to decode view state:', error);
@@ -330,7 +332,7 @@
         }
         /**
          * Apply simple class-based visibility to a toggle element.
-         * The element is assumed to have data-customviews-toggle.
+         * The element is assumed to have data-cv-toggle or data-customviews-toggle.
          */
         applyElementVisibility(el, visible) {
             if (visible) {
@@ -344,8 +346,211 @@
         }
     }
 
-    const CORE_STYLES = `
-[data-customviews-toggle] {
+    // Constants for selectors
+    const TABGROUP_SELECTOR = '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';
+    /**
+     * TabManager handles discovery, visibility, and navigation for tab groups and tabs
+     */
+    class TabManager {
+        /**
+         * Apply tab selections to all tab groups in the DOM
+         */
+        static applySelections(rootEl, tabs, cfgGroups) {
+            // Find all cv-tabgroup elements
+            const tabGroups = rootEl.querySelectorAll(TABGROUP_SELECTOR);
+            tabGroups.forEach((groupEl) => {
+                const groupId = groupEl.getAttribute('id');
+                if (!groupId)
+                    return;
+                // Determine the active tab for this group
+                const activeTabId = this.resolveActiveTab(groupId, tabs, cfgGroups, groupEl);
+                // Apply visibility to child cv-tab elements
+                const tabElements = groupEl.querySelectorAll(TAB_SELECTOR);
+                tabElements.forEach((tabEl) => {
+                    const tabId = tabEl.getAttribute('id');
+                    if (!tabId)
+                        return;
+                    const isActive = tabId === activeTabId;
+                    this.applyTabVisibility(tabEl, isActive);
+                });
+            });
+        }
+        /**
+         * Resolve the active tab for a group based on state, config, and DOM
+         */
+        static resolveActiveTab(groupId, tabs, cfgGroups, groupEl) {
+            // 1. Check state
+            if (tabs[groupId]) {
+                return tabs[groupId];
+            }
+            // 2. Check config default
+            if (cfgGroups) {
+                const groupCfg = cfgGroups.find(g => g.id === groupId);
+                if (groupCfg) {
+                    if (groupCfg.default) {
+                        return groupCfg.default;
+                    }
+                    // Fallback to first tab in config
+                    const firstConfigTab = groupCfg.tabs[0];
+                    if (firstConfigTab) {
+                        return firstConfigTab.id;
+                    }
+                }
+            }
+            // 3. Fallback to first cv-tab child in DOM
+            const firstTab = groupEl.querySelector(TAB_SELECTOR);
+            if (firstTab) {
+                return firstTab.getAttribute('id');
+            }
+            return null;
+        }
+        /**
+         * Apply visibility classes to a tab element
+         */
+        static applyTabVisibility(tabEl, isActive) {
+            if (isActive) {
+                tabEl.classList.remove('cv-hidden');
+                tabEl.classList.add('cv-visible');
+            }
+            else {
+                tabEl.classList.add('cv-hidden');
+                tabEl.classList.remove('cv-visible');
+            }
+        }
+        /**
+         * Build navigation for tab groups with nav="auto" (one-time setup)
+         */
+        static buildNavs(rootEl, cfgGroups, onTabClick) {
+            // Find all cv-tabgroup elements with nav="auto" or no nav attribute
+            const tabGroups = rootEl.querySelectorAll(NAV_AUTO_SELECTOR);
+            tabGroups.forEach((groupEl) => {
+                const groupId = groupEl.getAttribute('id');
+                if (!groupId)
+                    return;
+                // Check if nav already exists - if so, skip building
+                let navContainer = groupEl.querySelector(`.${NAV_CONTAINER_CLASS}`);
+                if (navContainer)
+                    return; // Already built
+                // Get all child tabs
+                const tabElements = Array.from(groupEl.querySelectorAll(TAB_SELECTOR));
+                if (tabElements.length === 0)
+                    return;
+                // Create nav container
+                navContainer = document.createElement('ul');
+                navContainer.className = `${NAV_CONTAINER_CLASS} nav-tabs`;
+                navContainer.setAttribute('role', 'tablist');
+                groupEl.insertBefore(navContainer, groupEl.firstChild);
+                // Build nav items
+                tabElements.forEach((tabEl) => {
+                    const tabId = tabEl.getAttribute('id');
+                    if (!tabId)
+                        return;
+                    const header = tabEl.getAttribute('header') || this.getTabLabel(tabId, groupId, cfgGroups) || tabId;
+                    const listItem = document.createElement('li');
+                    listItem.className = 'nav-item';
+                    const navLink = document.createElement('a');
+                    navLink.className = 'nav-link';
+                    navLink.textContent = header;
+                    navLink.href = '#';
+                    navLink.setAttribute('data-tab-id', tabId);
+                    navLink.setAttribute('data-group-id', groupId);
+                    navLink.setAttribute('role', 'tab');
+                    // Check if this tab is currently active
+                    const isActive = tabEl.classList.contains('cv-visible');
+                    if (isActive) {
+                        navLink.classList.add('active');
+                        navLink.setAttribute('aria-selected', 'true');
+                    }
+                    else {
+                        navLink.setAttribute('aria-selected', 'false');
+                    }
+                    // Add click handler
+                    if (onTabClick) {
+                        navLink.addEventListener('click', (e) => {
+                            e.preventDefault();
+                            onTabClick(groupId, tabId);
+                        });
+                    }
+                    listItem.appendChild(navLink);
+                    navContainer.appendChild(listItem);
+                });
+                // Add bottom border line at the end of the tab group
+                const bottomBorder = document.createElement('div');
+                bottomBorder.className = 'cv-tabgroup-bottom-border';
+                groupEl.appendChild(bottomBorder);
+            });
+        }
+        /**
+         * Get tab label from config
+         */
+        static getTabLabel(tabId, groupId, cfgGroups) {
+            if (!cfgGroups)
+                return null;
+            const groupCfg = cfgGroups.find(g => g.id === groupId);
+            if (!groupCfg)
+                return null;
+            const tabCfg = groupCfg.tabs.find(t => t.id === tabId);
+            return tabCfg?.label || null;
+        }
+        /**
+         * Update active state in navs after selection change (single group)
+         */
+        static updateNavActiveState(rootEl, groupId, activeTabId) {
+            const tabGroups = rootEl.querySelectorAll(`${TABGROUP_SELECTOR}[id="${groupId}"]`);
+            tabGroups.forEach((groupEl) => {
+                const navLinks = groupEl.querySelectorAll('.nav-link');
+                navLinks.forEach((link) => {
+                    const tabId = link.getAttribute('data-tab-id');
+                    if (tabId === activeTabId) {
+                        link.classList.add('active');
+                        link.setAttribute('aria-selected', 'true');
+                    }
+                    else {
+                        link.classList.remove('active');
+                        link.setAttribute('aria-selected', 'false');
+                    }
+                });
+            });
+        }
+        /**
+         * Update active states for all tab groups based on current state
+         */
+        static updateAllNavActiveStates(rootEl, tabs, cfgGroups) {
+            const tabGroups = rootEl.querySelectorAll(TABGROUP_SELECTOR);
+            tabGroups.forEach((groupEl) => {
+                const groupId = groupEl.getAttribute('id');
+                if (!groupId)
+                    return;
+                // Determine the active tab for this group
+                const activeTabId = this.resolveActiveTab(groupId, tabs, cfgGroups, groupEl);
+                if (!activeTabId)
+                    return;
+                // Update nav links for this group
+                const navLinks = groupEl.querySelectorAll('.nav-link');
+                navLinks.forEach((link) => {
+                    const tabId = link.getAttribute('data-tab-id');
+                    if (tabId === activeTabId) {
+                        link.classList.add('active');
+                        link.setAttribute('aria-selected', 'true');
+                    }
+                    else {
+                        link.classList.remove('active');
+                        link.setAttribute('aria-selected', 'false');
+                    }
+                });
+            });
+        }
+    }
+
+    /**
+     * Styles for toggle visibility and animations
+     */
+    const TOGGLE_STYLES = `
+/* Core toggle visibility transitions */
+[data-cv-toggle], [data-customviews-toggle] {
   transition: opacity 150ms ease,
               transform 150ms ease,
               max-height 200ms ease,
@@ -372,6 +577,125 @@
   margin-bottom: 0 !important;
   overflow: hidden !important;
 }
+`;
+
+    /**
+     * Styles for tab groups and tab navigation
+     */
+    const TAB_STYLES = `
+/* Tab navigation styles - Bootstrap-style tabs matching MarkBind */
+.cv-tabs-nav {
+  display: flex;
+  flex-wrap: wrap;
+  padding-left: 0;
+  margin-top: 0.5rem;
+  margin-bottom: 1rem;
+  list-style: none;
+  border-bottom: 1px solid #dee2e6;
+}
+
+.cv-tabs-nav .nav-item {
+  margin-bottom: -1px;
+  list-style: none;
+  display: inline-block;
+}
+
+.cv-tabs-nav .nav-link {
+  display: block;
+  padding: 0.5rem 1rem;
+  color: #495057;
+  text-decoration: none;
+  background-color: transparent;
+  border: 1px solid transparent;
+  border-top-left-radius: 0.25rem;
+  border-top-right-radius: 0.25rem;
+  transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out;
+  cursor: pointer;
+}
+
+.cv-tabs-nav .nav-link:hover,
+.cv-tabs-nav .nav-link:focus {
+  border-color: #e9ecef #e9ecef #dee2e6;
+  isolation: isolate;
+}
+
+.cv-tabs-nav .nav-link.active {
+  color: #495057;
+  background-color: #fff;
+  border-color: #dee2e6 #dee2e6 #fff;
+}
+
+.cv-tabs-nav .nav-link:focus {
+  outline: 0;
+  box-shadow: 0 0 0 0.25rem rgba(13, 110, 253, 0.25);
+}
+
+/* Legacy button-based nav (deprecated, kept for compatibility) */
+.cv-tabs-nav-item {
+  background: none;
+  border: none;
+  border-bottom: 2px solid transparent;
+  padding: 0.5rem 1rem;
+  cursor: pointer;
+  font-size: 1rem;
+  color: #6c757d;
+  transition: color 150ms ease, border-color 150ms ease;
+}
+
+.cv-tabs-nav-item:hover {
+  color: #495057;
+  border-bottom-color: #dee2e6;
+}
+
+.cv-tabs-nav-item.active {
+  color: #007bff;
+  border-bottom-color: #007bff;
+  font-weight: 500;
+}
+
+.cv-tabs-nav-item:focus {
+  outline: 2px solid #007bff;
+  outline-offset: 2px;
+}
+
+/* Tab panel base styles */
+cv-tab {
+  display: block;
+}
+
+/* Override visibility for tab panels - use display instead of collapse animation */
+cv-tab.cv-hidden {
+  display: none !important;
+}
+
+cv-tab.cv-visible {
+  display: block !important;
+}
+
+cv-tabgroup {
+  display: block;
+  margin-bottom: 1.5rem;
+}
+
+/* Bottom border line for tab groups */
+.cv-tabgroup-bottom-border {
+  border-bottom: 1px solid #dee2e6;
+  margin-top: 1rem;
+}
+
+/* Tab content wrapper */
+.cv-tab-content {
+  padding: 1rem 0;
+}
+`;
+
+    /**
+     * Combined core styles for toggles and tabs
+     */
+    const CORE_STYLES = `
+${TOGGLE_STYLES}
+
+${TAB_STYLES}
 `;
     /**
      * Add styles for hiding and showing toggles animations and transitions to the document head
@@ -392,36 +716,85 @@
         assetsManager;
         persistenceManager;
         visibilityManager;
-        stateFromUrl = null;
-        localConfig;
+        config;
         stateChangeListeners = [];
+        showUrlEnabled;
+        lastAppliedState = null;
         constructor(opt) {
             this.assetsManager = opt.assetsManager;
-            this.localConfig = opt.config;
+            this.config = opt.config;
             this.rootEl = opt.rootEl || document.body;
             this.persistenceManager = new PersistenceManager();
             this.visibilityManager = new VisibilityManager();
+            this.showUrlEnabled = opt.showUrl ?? true;
+            this.lastAppliedState = this.cloneState(this.config?.defaultState);
+        }
+        getConfig() {
+            return this.config;
+        }
+        /**
+         * Get tab groups from config
+         */
+        getTabGroups() {
+            return this.config.tabGroups;
+        }
+        /**
+         * Get currently active tabs (from URL > persisted (localStorage) > defaults)
+         */
+        getCurrentActiveTabs() {
+            if (this.lastAppliedState?.tabs) {
+                return { ...this.lastAppliedState.tabs };
+            }
+            const persistedState = this.persistenceManager.getPersistedState();
+            if (persistedState?.tabs) {
+                return { ...persistedState.tabs };
+            }
+            return this.config?.defaultState?.tabs ? { ...this.config.defaultState.tabs } : {};
         }
-        getLocalConfig() {
-            return this.localConfig;
+        /**
+         * Set active tab for a group and apply state
+         */
+        setActiveTab(groupId, tabId) {
+            // Get current state
+            const currentToggles = this.getCurrentActiveToggles();
+            const currentTabs = this.getCurrentActiveTabs();
+            // Merge new tab selection
+            const newTabs = { ...currentTabs, [groupId]: tabId };
+            // Create new state
+            const newState = {
+                toggles: currentToggles,
+                tabs: newTabs
+            };
+            // Apply the state
+            this.applyState(newState);
+            // Emit custom event
+            const event = new CustomEvent('customviews:tab-change', {
+                detail: { groupId, tabId },
+                bubbles: true
+            });
+            document.dispatchEvent(event);
         }
         // Inject styles, setup listeners and call rendering logic
         async init() {
             injectCoreStyles();
+            // Build navigation once (with click handlers)
+            TabManager.buildNavs(this.rootEl, this.config.tabGroups, (groupId, tabId) => {
+                this.setActiveTab(groupId, tabId);
+            });
             // For session history, clicks on back/forward button
             window.addEventListener("popstate", () => {
-                this.loadAndRenderState();
+                this.loadAndCallApplyState();
             });
-            this.loadAndRenderState();
+            this.loadAndCallApplyState();
         }
         // Priority: URL state > persisted state > default
         // Also filters using the visibility manager to persist selection
         // across back/forward button clicks
-        async loadAndRenderState() {
+        async loadAndCallApplyState() {
             // 1. URL State
-            this.stateFromUrl = URLStateManager.parseURL();
-            if (this.stateFromUrl) {
-                this.applyState(this.stateFromUrl);
+            const urlState = URLStateManager.parseURL();
+            if (urlState) {
+                this.applyState(urlState);
                 return;
             }
             // 2. Persisted State
@@ -431,38 +804,48 @@
                 return;
             }
             // 3. Local Config Fallback
-            this.renderState(this.localConfig.defaultState);
+            this.renderState(this.config.defaultState);
         }
         /**
-       * Apply a custom state, saves to localStorage and updates the URL
-       */
+        * Apply a custom state, saves to localStorage and updates the URL
+        */
         applyState(state) {
-            this.renderState(state);
-            this.persistenceManager.persistState(state);
-            this.stateFromUrl = state;
-            URLStateManager.updateURL(state);
+            const snapshot = this.cloneState(state);
+            this.renderState(snapshot);
+            this.persistenceManager.persistState(snapshot);
+            if (this.showUrlEnabled) {
+                URLStateManager.updateURL(snapshot);
+            }
+            else {
+                URLStateManager.clearURL();
+            }
         }
         /** Render all toggles for the current state */
         renderState(state) {
+            this.lastAppliedState = this.cloneState(state);
             const toggles = state.toggles || [];
             const finalToggles = this.visibilityManager.filterVisibleToggles(toggles);
             // Toggles hide or show relevant toggles
-            this.rootEl.querySelectorAll("[data-customviews-toggle]").forEach(el => {
-                const category = el.dataset.customviewsToggle;
+            this.rootEl.querySelectorAll("[data-cv-toggle], [data-customviews-toggle]").forEach(el => {
+                const category = el.dataset.cvToggle || el.dataset.customviewsToggle;
                 const shouldShow = !!category && finalToggles.includes(category);
                 this.visibilityManager.applyElementVisibility(el, shouldShow);
             });
             // Render toggles
             for (const category of finalToggles) {
-                this.rootEl.querySelectorAll(`[data-customviews-toggle="${category}"]`).forEach(el => {
-                    // if it has an id, then we render the asset into it
-                    // if it has no id, then we assume it's a container
-                    const toggleId = el.dataset.customviewsId;
+                this.rootEl.querySelectorAll(`[data-cv-toggle="${category}"], [data-customviews-toggle="${category}"]`).forEach(el => {
+                    // if it has an id, then we should render the asset into it
+                    // Support both (data-cv-id) and (data-customviews-id) attributes
+                    const toggleId = el.dataset.cvId || el.dataset.customviewsId;
                     if (toggleId) {
                         renderAssetInto(el, toggleId, this.assetsManager);
                     }
                 });
             }
+            // Apply tab selections
+            TabManager.applySelections(this.rootEl, state.tabs || {}, this.config.tabGroups);
+            // Update nav active states (without rebuilding)
+            TabManager.updateAllNavActiveStates(this.rootEl, state.tabs || {}, this.config.tabGroups);
             // Notify state change listeners (like widgets)
             this.notifyStateChangeListeners();
         }
@@ -470,10 +853,9 @@
          * Reset to default state
          */
         resetToDefault() {
-            this.stateFromUrl = null;
             this.persistenceManager.clearAll();
-            if (this.localConfig) {
-                this.renderState(this.localConfig.defaultState);
+            if (this.config) {
+                this.renderState(this.config.defaultState);
             }
             else {
                 console.warn("No configuration loaded, cannot reset to default state");
@@ -485,15 +867,12 @@
          * Get the currently active toggles regardless of whether they come from custom state or default configuration
          */
         getCurrentActiveToggles() {
-            // If we have a custom state, return its toggles
-            if (this.stateFromUrl) {
-                return this.stateFromUrl.toggles || [];
+            if (this.lastAppliedState) {
+                return this.lastAppliedState.toggles || [];
             }
-            // Otherwise, if we have local config, return its default state toggles
-            if (this.localConfig) {
-                return this.localConfig.defaultState.toggles || [];
+            if (this.config) {
+                return this.config.defaultState.toggles || [];
             }
-            // No configuration or state
             return [];
         }
         /**
@@ -501,15 +880,35 @@
          */
         clearPersistence() {
             this.persistenceManager.clearAll();
-            this.stateFromUrl = null;
-            if (this.localConfig) {
-                this.renderState(this.localConfig.defaultState);
+            if (this.config) {
+                this.renderState(this.config.defaultState);
             }
             else {
                 console.warn("No configuration loaded, cannot reset to default state");
             }
             URLStateManager.clearURL();
         }
+        setOption(flag, value) {
+            switch (flag) {
+                case 'showUrl': {
+                    const nextValue = Boolean(value);
+                    if (this.showUrlEnabled === nextValue) {
+                        return;
+                    }
+                    this.showUrlEnabled = nextValue;
+                    if (nextValue) {
+                        const stateForUrl = this.getTrackedStateSnapshot();
+                        URLStateManager.updateURL(stateForUrl);
+                    }
+                    else {
+                        URLStateManager.clearURL();
+                    }
+                    break;
+                }
+                default:
+                    console.warn(`[CustomViews] Unknown option '${flag}' passed to setOption`);
+            }
+        }
         // === STATE CHANGE LISTENER METHODS ===
         /**
          * Add a listener that will be called whenever the state changes
@@ -539,6 +938,20 @@
                 }
             });
         }
+        cloneState(state) {
+            const toggles = state?.toggles ? [...state.toggles] : [];
+            const tabs = state?.tabs ? { ...state.tabs } : undefined;
+            return tabs ? { toggles, tabs } : { toggles };
+        }
+        getTrackedStateSnapshot() {
+            if (this.lastAppliedState) {
+                return this.cloneState(this.lastAppliedState);
+            }
+            if (this.config) {
+                return this.cloneState(this.config.defaultState);
+            }
+            return { toggles: [] };
+        }
     }
 
     class AssetsManager {
@@ -587,6 +1000,70 @@
         }
     }
 
+    /**
+     * Helper function to prepend baseUrl to a path
+     * @param path The path to prepend the baseUrl to
+     * @param baseUrl The base URL to prepend
+     * @returns The full URL with baseUrl prepended if applicable
+     */
+    function prependBaseUrl(path, baseUrl) {
+        if (!baseUrl)
+            return path;
+        // Don't prepend if the path is already absolute (starts with http:// or https://)
+        if (path.startsWith('http://') || path.startsWith('https://')) {
+            return path;
+        }
+        // Ensure baseUrl doesn't end with / and path starts with /
+        const cleanbaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        const cleanPath = path.startsWith('/') ? path : '/' + path;
+        return cleanbaseUrl + cleanPath;
+    }
+
+    /**
+     * Main CustomViews class for initializing and managing custom views
+     */
+    class CustomViews {
+        /**
+         * Entry Point to use CustomViews
+         * @param opts Initialization options including config object and assets path
+         * @returns Promise resolving to the CustomViewsCore instance or null if initialization fails
+         */
+        static async init(opts) {
+            // Load assets JSON if provided
+            let assetsManager;
+            const baseURL = opts.baseURL || '';
+            if (opts.assetsJsonPath) {
+                const assetsPath = prependBaseUrl(opts.assetsJsonPath, baseURL);
+                const assetsJson = await (await fetch(assetsPath)).json();
+                assetsManager = new AssetsManager(assetsJson, baseURL);
+            }
+            else {
+                assetsManager = new AssetsManager({}, baseURL);
+            }
+            // Use provided config or create a minimal default one
+            let config;
+            if (opts.config) {
+                config = opts.config;
+            }
+            else {
+                console.error("No config provided, using minimal default config");
+                // Create a minimal default config
+                config = { allToggles: [], defaultState: { toggles: [] } };
+            }
+            const coreOptions = {
+                assetsManager,
+                config: config,
+                rootEl: opts.rootEl,
+            };
+            if (opts.showUrl !== undefined) {
+                coreOptions.showUrl = opts.showUrl;
+            }
+            const core = new CustomViewsCore(coreOptions);
+            core.init();
+            return core;
+        }
+    }
+
     /**
      * Widget styles for CustomViews
      * Extracted from widget.ts for better maintainability
@@ -598,8 +1075,10 @@
 /* Rounded rectangle widget icon styles */
 .cv-widget-icon {
   position: fixed;
-  background: white;
-  color: black;
+  /* Slightly transparent by default so the widget is subtle at the page edge */
+  background: rgba(255, 255, 255, 0.92);
+  color: rgba(0, 0, 0, 0.9);
+  opacity: 0.6;
   display: flex;
   align-items: center;
   justify-content: center;
@@ -613,8 +1092,10 @@
 }
 
 .cv-widget-icon:hover {
-  background: white;
-  color: black;
+  /* Become fully opaque on hover to improve readability */
+  background: rgba(255, 255, 255, 1);
+  color: rgba(0, 0, 0, 1);
+  opacity: 1;
 }
 
 /* Top-right: rounded end on left, sticks out leftward on hover */
@@ -1021,6 +1502,43 @@
   width: auto;
 }
 
+.cv-tab-groups {
+  margin-top: 20px;
+}
+
+.cv-tab-group-control {
+  margin-bottom: 15px;
+}
+
+.cv-tab-group-control label {
+  display: block;
+  margin-bottom: 5px;
+  font-weight: 500;
+  font-size: 14px;
+}
+
+.cv-tab-group-select {
+  width: 100%;
+  padding: 8px 12px;
+  border: 1px solid #ced4da;
+  border-radius: 4px;
+  font-size: 14px;
+  background-color: white;
+  cursor: pointer;
+}
+
+.cv-tab-group-select:focus {
+  outline: none;
+  border-color: #007bff;
+  box-shadow: 0 0 0 0.2rem rgba(0, 123, 255, 0.25);
+}
+
+.cv-widget-theme-dark .cv-tab-group-select {
+  background-color: #2d3748;
+  border-color: #4a5568;
+  color: #e2e8f0;
+}
+
 .cv-custom-state-actions {
   display: flex;
   gap: 10px;
@@ -1209,7 +1727,8 @@
                 description: options.description || 'Toggle different content sections to customize your view. Changes are applied instantly and the URL will be updated for sharing.',
                 showWelcome: options.showWelcome ?? false,
                 welcomeTitle: options.welcomeTitle || 'Welcome to Custom Views!',
-                welcomeMessage: options.welcomeMessage || 'This website uses Custom Views to let you personalize your experience. Use the widget on the side (⚙) to show or hide different content sections based on your preferences. Your selections will be saved and can be shared via URL.'
+                welcomeMessage: options.welcomeMessage || 'This website uses Custom Views to let you personalize your experience. Use the widget on the side (⚙) to show or hide different content sections based on your preferences. Your selections will be saved and can be shared via URL.',
+                showTabGroups: options.showTabGroups ?? true
             };
             // No external state manager to initialize
         }
@@ -1274,8 +1793,8 @@
          */
         openStateModal() {
             // Get toggles from current configuration and open the modal regardless of count
-            const localConfig = this.core.getLocalConfig();
-            const toggles = localConfig?.allToggles || [];
+            const config = this.core.getConfig();
+            const toggles = config?.allToggles || [];
             this.createCustomStateModal(toggles);
         }
         /**
@@ -1297,6 +1816,28 @@
         </div>
       `).join('')
                 : `<p class="cv-no-toggles">No configurable sections available.</p>`;
+            // Get tab groups
+            const tabGroups = this.core.getTabGroups();
+            let tabGroupsHTML = '';
+            if (this.options.showTabGroups && tabGroups && tabGroups.length > 0) {
+                const tabGroupControls = tabGroups.map(group => {
+                    const options = group.tabs.map(tab => `<option value="${tab.id}">${tab.label || tab.id}</option>`).join('');
+                    return `
+          <div class="cv-tab-group-control">
+            <label for="tab-group-${group.id}">${group.label || group.id}</label>
+            <select id="tab-group-${group.id}" class="cv-tab-group-select" data-group-id="${group.id}">
+              ${options}
+            </select>
+          </div>
+        `;
+                }).join('');
+                tabGroupsHTML = `
+        <h4>Tab Groups</h4>
+        <div class="cv-tab-groups">
+          ${tabGroupControls}
+        </div>
+      `;
+            }
             this.modal.innerHTML = `
       <div class="cv-widget-modal cv-custom-state-modal">
         <div class="cv-widget-modal-header">
@@ -1312,6 +1853,8 @@
               ${toggleControls}
             </div>
             
+            ${tabGroupsHTML}
+            
             <div class="cv-custom-state-actions">
               ${this.options.showReset ? `<button class="cv-custom-state-reset">Reset to Default</button>` : ''}
               <button class="cv-custom-state-copy-url">Copy Shareable URL</button>
@@ -1361,6 +1904,17 @@
                     this.core.applyState(state);
                 });
             });
+            // Listen to tab group selects
+            const tabGroupSelects = this.modal.querySelectorAll('.cv-tab-group-select');
+            tabGroupSelects.forEach(select => {
+                select.addEventListener('change', () => {
+                    const groupId = select.dataset.groupId;
+                    const tabId = select.value;
+                    if (groupId && tabId) {
+                        this.core.setActiveTab(groupId, tabId);
+                    }
+                });
+            });
             // Overlay click to close
             this.modal.addEventListener('click', (e) => {
                 if (e.target === this.modal) {
@@ -1405,7 +1959,16 @@
                     toggles.push(toggle);
                 }
             });
-            return { toggles };
+            // Collect tab selections
+            const tabGroupSelects = this.modal.querySelectorAll('.cv-tab-group-select');
+            const tabs = {};
+            tabGroupSelects.forEach(select => {
+                const groupId = select.dataset.groupId;
+                if (groupId) {
+                    tabs[groupId] = select.value;
+                }
+            });
+            return Object.keys(tabs).length > 0 ? { toggles, tabs } : { toggles };
         }
         /**
          * Copy shareable URL to clipboard
@@ -1441,6 +2004,15 @@
                     }
                 }
             });
+            // Load tab group selections
+            const activeTabs = this.core.getCurrentActiveTabs();
+            const tabGroupSelects = this.modal.querySelectorAll('.cv-tab-group-select');
+            tabGroupSelects.forEach(select => {
+                const groupId = select.dataset.groupId;
+                if (groupId && activeTabs[groupId]) {
+                    select.value = activeTabs[groupId];
+                }
+            });
         }
         /**
          * Format toggle name for display
@@ -1534,61 +2106,204 @@
         }
     }
 
-    class CustomViews {
-        // Entry Point to use CustomViews
-        static async initFromJson(opts) {
-            // Load assets JSON if provided
-            let assetsManager;
-            const baseURL = opts.baseURL || '';
-            if (opts.assetsJsonPath) {
-                const assetsJson = await (await fetch(opts.assetsJsonPath)).json();
-                assetsManager = new AssetsManager(assetsJson, baseURL);
-            }
-            else {
-                assetsManager = new AssetsManager({}, baseURL);
-            }
-            // Load config JSON if provided, else just log error and don't load the custom views
-            let localConfig;
-            if (opts.config) {
-                localConfig = opts.config;
+    /**
+     * Custom Elements for Tab Groups and Tabs
+     */
+    /**
+     * <cv-tab> element - represents a single tab panel
+     */
+    class CVTab extends HTMLElement {
+        connectedCallback() {
+            // Element is managed by TabManager
+        }
+    }
+    /**
+     * <cv-tabgroup> element - represents a group of tabs
+     */
+    class CVTabgroup extends HTMLElement {
+        connectedCallback() {
+            // Element is managed by TabManager
+            // Emit ready event after a brief delay to ensure children are parsed
+            setTimeout(() => {
+                const event = new CustomEvent('cv:tabgroup-ready', {
+                    bubbles: true,
+                    detail: { groupId: this.getAttribute('id') }
+                });
+                this.dispatchEvent(event);
+            }, 0);
+        }
+    }
+    /**
+     * Register custom elements
+     */
+    function registerCustomElements() {
+        // Only register if not already defined
+        if (!customElements.get('cv-tab')) {
+            customElements.define('cv-tab', CVTab);
+        }
+        if (!customElements.get('cv-tabgroup')) {
+            customElements.define('cv-tabgroup', CVTabgroup);
+        }
+    }
+
+    /**
+     * Initialize CustomViews from script tag attributes and config file
+     * This function handles the automatic initialization of CustomViews when included via script tag
+     *
+     * Data attributes supported:
+     * - data-base-url: Base URL for the site (e.g., "/customviews" for subdirectory deployments)
+     * - data-config-path: Path to config file (default: "/customviews.config.json")
+     *
+     * The function fetches the config file and uses it directly to initialize CustomViews.
+     * Widget visibility is controlled via the config file (widget.enabled property).
+     */
+    function initializeFromScript() {
+        // Only run in browser environment
+        if (typeof window === 'undefined')
+            return;
+        // Use the typed global `window` (see src/types/global.d.ts)
+        // Idempotency guard: if already initialized, skip setting up listener again.
+        if (window.__customViewsInitialized) {
+            // Informational for developers; harmless in production.
+            console.info('[CustomViews] Auto-init skipped: already initialized.');
+            return;
+        }
+        document.addEventListener('DOMContentLoaded', async function () {
+            // Prevent concurrent initialization runs (race conditions when script is loaded twice)
+            if (window.__customViewsInitInProgress || window.__customViewsInitialized) {
+                return;
             }
-            else {
-                if (!opts.configPath) {
-                    console.error("No config path provided, skipping custom views");
-                    return null;
+            window.__customViewsInitInProgress = true;
+            // Register custom elements early
+            registerCustomElements();
+            try {
+                // Find the script tag
+                let scriptTag = document.currentScript;
+                // Fallback if currentScript is not available (executed after page load)
+                if (!scriptTag) {
+                    // Try to find the script tag by looking for our script
+                    const scripts = document.querySelectorAll('script[src*="custom-views"]');
+                    if (scripts.length > 0) {
+                        // Find the most specific match (to avoid matching other custom-views scripts)
+                        for (let i = 0; i < scripts.length; i++) {
+                            const script = scripts[i];
+                            const src = script.getAttribute('src') || '';
+                            // Look for .min.js or .js at the end
+                            if (src.match(/custom-views(\.min)?\.js($|\?)/)) {
+                                scriptTag = script;
+                                break;
+                            }
+                        }
+                        // If no specific match found, use the first one
+                        if (!scriptTag) {
+                            scriptTag = scripts[0];
+                        }
+                    }
+                }
+                // Read data attributes from script tag
+                let baseURL = '';
+                let configPath = '/customviews.config.json';
+                if (scriptTag) {
+                    baseURL = scriptTag.getAttribute('data-base-url') || '';
+                    configPath = scriptTag.getAttribute('data-config-path') || configPath;
                 }
+                // Fetch config file
+                let configFile;
                 try {
-                    localConfig = await (await fetch(opts.configPath)).json();
+                    const fullConfigPath = prependBaseUrl(configPath, baseURL);
+                    console.log(`[CustomViews] Loading config from: ${fullConfigPath}`);
+                    const response = await fetch(fullConfigPath);
+                    if (!response.ok) {
+                        console.warn(`[CustomViews] Config file not found at ${fullConfigPath}. Using defaults.`);
+                        // Provide minimal default config structure
+                        configFile = {
+                            config: {
+                                allToggles: [],
+                                defaultState: { toggles: [] }
+                            },
+                            widget: {
+                                enabled: true
+                            }
+                        };
+                    }
+                    else {
+                        configFile = await response.json();
+                        console.log('[CustomViews] Config loaded successfully');
+                    }
                 }
                 catch (error) {
-                    console.error("Error loading config:", error);
-                    return null;
+                    console.error('[CustomViews] Error loading config file:', error);
+                    return; // Abort initialization
+                }
+                // Determine effective baseURL (data attribute takes precedence over config)
+                const effectiveBaseURL = baseURL || configFile.baseURL || '';
+                const options = {
+                    config: configFile.config,
+                    assetsJsonPath: configFile.assetsJsonPath,
+                    baseURL: effectiveBaseURL,
+                };
+                if (configFile.showUrl !== undefined) {
+                    options.showUrl = configFile.showUrl;
                 }
+                // Initialize CustomViews core
+                const core = await CustomViews.init(options);
+                if (!core) {
+                    console.error('[CustomViews] Failed to initialize core.');
+                    return; // Abort widget creation
+                }
+                // Store instance
+                window.customViewsInstance = { core };
+                // Initialize widget if enabled in config
+                let widget;
+                if (configFile.widget?.enabled !== false) {
+                    widget = new CustomViewsWidget({
+                        core,
+                        ...configFile.widget
+                    });
+                    widget.render();
+                    // Store widget instance
+                    window.customViewsInstance.widget = widget;
+                    console.log('[CustomViews] Widget initialized and rendered');
+                }
+                else {
+                    console.log('[CustomViews] Widget disabled in config - skipping initialization');
+                }
+                // Dispatch ready event
+                const readyEvent = new CustomEvent('customviews:ready', {
+                    detail: {
+                        core,
+                        widget
+                    }
+                });
+                document.dispatchEvent(readyEvent);
+                // Mark initialized and clear in-progress flag
+                window.__customViewsInitialized = true;
+                window.__customViewsInitInProgress = false;
             }
-            const coreOptions = {
-                assetsManager,
-                config: localConfig,
-                rootEl: opts.rootEl,
-            };
-            const core = new CustomViewsCore(coreOptions);
-            core.init();
-            return core;
-        }
+            catch (error) {
+                // Clear in-progress flag so a future attempt can retry
+                window.__customViewsInitInProgress = false;
+                console.error('[CustomViews] Auto-initialization error:', error);
+            }
+        });
     }
+
+    // Import from new modules
+    // Set up globals and auto-initialization
     if (typeof window !== "undefined") {
-        // @ts-ignore
+        // Expose to window to enable usage (e.g. const app = new window.CustomViews(...))
         window.CustomViews = CustomViews;
-        // @ts-ignore
         window.CustomViewsWidget = CustomViewsWidget;
+        // Run auto-initialization
+        initializeFromScript();
     }
 
     exports.AssetsManager = AssetsManager;
     exports.CustomViews = CustomViews;
     exports.CustomViewsCore = CustomViewsCore;
     exports.CustomViewsWidget = CustomViewsWidget;
-    exports.LocalConfig = Config;
     exports.PersistenceManager = PersistenceManager;
     exports.URLStateManager = URLStateManager;
 
 }));
-//# sourceMappingURL=custom-views.umd.js.map
+//# sourceMappingURL=custom-views.js.map