@customviews-js/customviews 1.4.0 → 1.4.1-beta.1

package/dist/custom-views.esm.js

@@ -1,5 +1,5 @@
 /*!
- * @customviews-js/customviews v1.4.0
+ * @customviews-js/customviews v1.4.1-beta.1
  * (c) 2025 Chan Ger Teck
  * Released under the MIT License.
  */
@@ -163,8 +163,12 @@ class URLStateManager {
             // Create a compact representation
             const compact = {};
             // Add toggles if present and non-empty
-            if (state.toggles && state.toggles.length > 0) {
-                compact.t = state.toggles;
+            if (state.shownToggles && state.shownToggles.length > 0) {
+                compact.t = state.shownToggles;
+            }
+            // Add peek toggles if present and non-empty
+            if (state.peekToggles && state.peekToggles.length > 0) {
+                compact.p = state.peekToggles;
             }
             // Add tab groups if present
             if (state.tabs && Object.keys(state.tabs).length > 0) {
@@ -225,7 +229,8 @@ class URLStateManager {
             // Reconstruct State from compact format
             // Reconstruct Toggles
             const state = {
-                toggles: Array.isArray(compact.t) ? compact.t : []
+                shownToggles: Array.isArray(compact.t) ? compact.t : [],
+                peekToggles: Array.isArray(compact.p) ? compact.p : []
             };
             // Reconstruct Tabs
             if (Array.isArray(compact.g)) {
@@ -438,6 +443,12 @@ function getGitHubIcon() {
             <path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z"/>
           </svg>`;
 }
+function getChevronDownIcon() {
+    return `<svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"></polyline></svg>`;
+}
+function getChevronUpIcon() {
+    return `<svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="18 15 12 9 6 15"></polyline></svg>`;
+}
 
 // Constants for selectors
 const TABGROUP_SELECTOR$1 = 'cv-tabgroup';
@@ -693,7 +704,7 @@ class TabManager {
                     });
                 }
                 // Add tooltip for UX feedback (use native title attribute)
-                navLink.setAttribute('title', 'Double click to change switch tabs across all groups');
+                navLink.setAttribute('title', "Double-click a tab to 'pin' it in all similar tab groups.");
                 listItem.appendChild(navLink);
                 navContainer.appendChild(listItem);
             });
@@ -1008,20 +1019,33 @@ function renderAssetInto(el, assetId, assetsManager) {
  * ToggleManager handles discovery, visibility, and asset rendering for toggle elements
  */
 class ToggleManager {
+    /**
+     * Track locally expanded elements (that were in peek mode but user expanded them)
+     */
+    static expandedPeekElements = new WeakSet();
     /**
      * Apply toggle visibility to a given list of toggle elements
      */
-    static applyToggles(elements, activeToggles) {
-        elements.forEach(el => {
+    static applyTogglesVisibility(allToggleElements, activeToggles, peekToggles = []) {
+        allToggleElements.forEach(el => {
             const categories = this.getToggleCategories(el);
             const shouldShow = categories.some(cat => activeToggles.includes(cat));
-            this.applyToggleVisibility(el, shouldShow);
+            const shouldPeek = !shouldShow && categories.some(cat => peekToggles.includes(cat));
+            if (!shouldPeek) {
+                this.expandedPeekElements.delete(el);
+            }
+            // If locally expanded, treat as shown (override peek)
+            // Note: If neither show nor peek is active (i.e. hidden), local expansion is ignored/cleared effectively
+            this.applyToggleVisibility(el, shouldShow || (shouldPeek && this.expandedPeekElements.has(el)), shouldPeek && !this.expandedPeekElements.has(el));
         });
     }
     /**
      * Render assets into a given list of toggle elements that are currently visible
+     * Toggles that have a toggleId and are currently visible will have their assets rendered (if any)
      */
-    static renderAssets(elements, activeToggles, assetsManager) {
+    static renderToggleAssets(elements, activeToggles, assetsManager) {
+        // TO DO: (gerteck) Enable for peek toggles as well
+        // Also, rework the rendering logic again to make it more user friendly.
         elements.forEach(el => {
             const categories = this.getToggleCategories(el);
             const toggleId = this.getToggleId(el);
@@ -1034,6 +1058,7 @@ class ToggleManager {
     }
     /**
      * Get toggle categories from an element (supports both data attributes and cv-toggle elements)
+     * Note: a toggle can have multiple categories.
      */
     static getToggleCategories(el) {
         if (el.tagName.toLowerCase() === 'cv-toggle') {
@@ -1054,14 +1079,101 @@ class ToggleManager {
     /**
      * Apply simple class-based visibility to a toggle element
      */
-    static applyToggleVisibility(el, visible) {
+    static applyToggleVisibility(toggleElement, visible, peek = false) {
+        const isLocallyExpanded = this.expandedPeekElements.has(toggleElement);
         if (visible) {
-            el.classList.remove('cv-hidden');
-            el.classList.add('cv-visible');
+            toggleElement.classList.remove('cv-hidden', 'cv-peek');
+            toggleElement.classList.add('cv-visible');
+            // Show collapse button ONLY if locally expanded (meaning we are actually in peek mode but expanded).
+            // If globally visible (because of 'Show' state), isLocallyExpanded should have been cleared by applyTogglesVisibility,
+            // so this will be false, and button will be removed.
+            this.manageExpandButton(toggleElement, false, isLocallyExpanded);
+        }
+        else if (peek) {
+            toggleElement.classList.remove('cv-hidden', 'cv-visible');
+            toggleElement.classList.add('cv-peek');
+            // Show/create expand button if peeked
+            this.manageExpandButton(toggleElement, true, false);
         }
         else {
-            el.classList.add('cv-hidden');
-            el.classList.remove('cv-visible');
+            toggleElement.classList.add('cv-hidden');
+            toggleElement.classList.remove('cv-visible', 'cv-peek');
+            // Ensure button is gone/hidden
+            this.manageExpandButton(toggleElement, false, false);
+        }
+    }
+    /**
+     * Manage the presence of the inline Expand/Collapse button using a wrapper approach
+     */
+    static manageExpandButton(toggleElement, showExpand, showCollapse = false) {
+        // 1. Ensure wrapper exists
+        let wrapper = toggleElement.parentElement;
+        if (!wrapper || !wrapper.classList.contains('cv-wrapper')) {
+            wrapper = document.createElement('div');
+            wrapper.className = 'cv-wrapper';
+            toggleElement.parentNode?.insertBefore(wrapper, toggleElement);
+            wrapper.appendChild(toggleElement);
+        }
+        const btn = wrapper.querySelector('.cv-expand-btn');
+        // 2. Handle "No Button" case (neither expand nor collapse)
+        if (!showExpand && !showCollapse) {
+            if (btn)
+                btn.style.display = 'none';
+            // If content is visible globally (not hidden), ensure wrapper has 'cv-expanded' 
+            // to hide the peek fade effect (since fade is for peek state only).
+            if (!toggleElement.classList.contains('cv-hidden')) {
+                wrapper.classList.add('cv-expanded');
+            }
+            else {
+                wrapper.classList.remove('cv-expanded');
+            }
+            return;
+        }
+        // 3. Handle Button Needed (Expand or Collapse)
+        const action = showExpand ? 'expand' : 'collapse';
+        // Update Wrapper Class Logic
+        // If showExpand (Peek state) -> remove cv-expanded (show fade)
+        // If showCollapse (Expanded peek) -> add cv-expanded (hide fade)
+        if (showExpand) {
+            wrapper.classList.remove('cv-expanded');
+        }
+        else {
+            if (!wrapper.classList.contains('cv-expanded'))
+                wrapper.classList.add('cv-expanded');
+        }
+        // Check if existing button matches desired state
+        const currentAction = btn?.getAttribute('data-action');
+        if (btn && currentAction === action) {
+            btn.style.display = 'flex';
+            return;
+        }
+        // 4. Create New Button (if missing or state changed)
+        const iconSvg = showExpand ? getChevronDownIcon() : getChevronUpIcon();
+        const newBtn = document.createElement('button');
+        newBtn.className = 'cv-expand-btn';
+        newBtn.innerHTML = iconSvg;
+        newBtn.setAttribute('aria-label', showExpand ? 'Expand content' : 'Collapse content');
+        newBtn.setAttribute('data-action', action); // Track state
+        newBtn.style.display = 'flex';
+        newBtn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            // Logic: Toggle expansion state
+            if (showExpand) {
+                wrapper.classList.add('cv-expanded');
+                this.expandedPeekElements.add(toggleElement);
+                this.applyToggleVisibility(toggleElement, true, false);
+            }
+            else {
+                wrapper.classList.remove('cv-expanded');
+                this.expandedPeekElements.delete(toggleElement);
+                this.applyToggleVisibility(toggleElement, false, true);
+            }
+        });
+        if (btn) {
+            btn.replaceWith(newBtn);
+        }
+        else {
+            wrapper.appendChild(newBtn);
         }
     }
     /**
@@ -1069,15 +1181,15 @@ class ToggleManager {
      * This includes applying visibility and rendering assets.
      */
     static initializeToggles(root, activeToggles, assetsManager) {
-        const elements = [];
+        const allToggleElements = [];
         if (root.matches('[data-cv-toggle], [data-customviews-toggle], cv-toggle')) {
-            elements.push(root);
+            allToggleElements.push(root);
         }
-        root.querySelectorAll('[data-cv-toggle], [data-customviews-toggle], cv-toggle').forEach(el => elements.push(el));
-        if (elements.length === 0)
+        root.querySelectorAll('[data-cv-toggle], [data-customviews-toggle], cv-toggle').forEach(el => allToggleElements.push(el));
+        if (allToggleElements.length === 0)
             return;
-        this.applyToggles(elements, activeToggles);
-        this.renderAssets(elements, activeToggles, assetsManager);
+        this.applyTogglesVisibility(allToggleElements, activeToggles);
+        this.renderToggleAssets(allToggleElements, activeToggles, assetsManager);
     }
 }
 
@@ -1185,17 +1297,16 @@ class ScrollManager {
 const TOGGLE_STYLES = `
 /* Core toggle visibility transitions */
 [data-cv-toggle], [data-customviews-toggle], cv-toggle {
-  transition: opacity 150ms ease,
-              transform 150ms ease,
-              max-height 200ms ease,
-              margin 150ms ease;
-  will-change: opacity, transform, max-height, margin;
+  display: block;
+  overflow: hidden;
+  /* Removed transitions for instant toggling */
 }
 
+/* Open State */
 .cv-visible {
   opacity: 1 !important;
   transform: translateY(0) !important;
-  max-height: var(--cv-max-height, 9999px) !important;
+  max-height: none !important;
 }
 
 .cv-hidden {
@@ -1211,6 +1322,61 @@ const TOGGLE_STYLES = `
   margin-bottom: 0 !important;
   overflow: hidden !important;
 }
+
+/* Close/Peek State */
+.cv-peek {
+  display: block !important;
+  max-height: 70px !important;
+  overflow: hidden !important;
+  opacity: 1 !important;
+  transform: translateY(0) !important;
+  mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
+  -webkit-mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
+}
+
+.cv-wrapper {
+  position: relative;
+  width: 100%;
+  display: block;
+  margin-bottom: 24px; /* Space for the button */
+}
+
+.cv-expand-btn {
+  position: absolute;
+  bottom: -28px; /* Mostly outside, slight overlap */
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  background: transparent;
+  border: none;
+  border-radius: 50%;
+  padding: 4px;
+  width: 32px;
+  height: 32px;
+  cursor: pointer;
+  z-index: 100;
+  align-items: center;
+  justify-content: center;
+  color: #888;
+  transition: all 0.2s ease;
+  box-shadow: none;
+}
+
+.cv-expand-btn:hover {
+  background: rgba(0, 0, 0, 0.05);
+  color: #000;
+  transform: translateX(-50%) scale(1.1);
+}
+
+.cv-expand-btn svg {
+  display: block;
+  opacity: 0.6;
+}
+
+.cv-expand-btn:hover svg {
+  opacity: 1;
+}
+
 `;
 
 /**
@@ -2566,6 +2732,12 @@ class CustomViewsCore {
             this.componentRegistry.tabGroups.delete(tabGroup);
         });
     }
+    /**
+     * Check if there are any active components in the registry
+     */
+    hasActiveComponents() {
+        return this.componentRegistry.toggles.size > 0 || this.componentRegistry.tabGroups.size > 0;
+    }
     getConfig() {
         return this.config;
     }
@@ -2600,7 +2772,7 @@ class CustomViewsCore {
             });
         }
         const computedState = {
-            toggles: this.config.toggles?.map(t => t.id) || [],
+            shownToggles: this.config.toggles?.map(t => t.id) || [],
             tabs
         };
         return computedState;
@@ -2672,9 +2844,9 @@ class CustomViewsCore {
             const initialTop = anchorElement.getBoundingClientRect().top;
             const currentTabs = this.getCurrentActiveTabs();
             currentTabs[groupId] = tabId;
-            const currentToggles = this.getCurrentActiveToggles();
+            const currentState = this.getCurrentState();
             const newState = {
-                toggles: currentToggles,
+                ...currentState,
                 tabs: currentTabs,
             };
             // 2. Apply state with scroll anchor information
@@ -2730,7 +2902,8 @@ class CustomViewsCore {
         // 1. URL State
         const urlState = URLStateManager.parseURL();
         if (urlState) {
-            this.applyState(urlState);
+            // Apply URL state temporarily (do not persist until interaction)
+            this.applyState(urlState, { persist: false });
             return;
         }
         // 2. Persisted State
@@ -2744,9 +2917,10 @@ class CustomViewsCore {
     }
     /**
     * Apply a custom state, saves to localStorage and updates the URL
-    * Add 'source' in options to indicate the origin of the state change
+    * 'source' in options indicates the origin of the state change
     * (e.g., 'widget' to trigger scroll behavior)
-    * Add scrollAnchor in options to maintain scroll position of a specific element
+    * 'scrollAnchor' in options indicates the element to maintain scroll position of
+    * 'persist' (default true) to control whether to save to localStorage
     */
     applyState(state, options) {
         // console.log(`[Core] applyState called with source: ${options?.source}`, state);
@@ -2756,7 +2930,10 @@ class CustomViewsCore {
         }
         const snapshot = this.cloneState(state);
         this.renderState(snapshot);
-        this.persistenceManager.persistState(snapshot);
+        // Only persist if explicitly requested (default true)
+        if (options?.persist !== false) {
+            this.persistenceManager.persistState(snapshot);
+        }
         if (this.showUrlEnabled) {
             URLStateManager.updateURL(snapshot);
         }
@@ -2783,14 +2960,13 @@ class CustomViewsCore {
     renderState(state) {
         this.observer?.disconnect();
         this.lastAppliedState = this.cloneState(state);
-        const toggles = state?.toggles || [];
+        const toggles = state?.shownToggles || [];
         const finalToggles = this.visibilityManager.filterVisibleToggles(toggles);
-        const toggleElements = Array.from(this.componentRegistry.toggles);
+        const allToggleElements = Array.from(this.componentRegistry.toggles);
         const tabGroupElements = Array.from(this.componentRegistry.tabGroups);
-        // Apply toggle visibility
-        ToggleManager.applyToggles(toggleElements, finalToggles);
+        ToggleManager.applyTogglesVisibility(allToggleElements, finalToggles, state.peekToggles);
         // Render assets into toggles
-        ToggleManager.renderAssets(toggleElements, finalToggles, this.assetsManager);
+        ToggleManager.renderToggleAssets(allToggleElements, finalToggles, this.assetsManager);
         // Apply tab selections
         TabManager.applyTabSelections(tabGroupElements, state.tabs || {}, this.config.tabGroups);
         // Update nav active states (without rebuilding)
@@ -2821,16 +2997,16 @@ class CustomViewsCore {
         URLStateManager.clearURL();
     }
     /**
-     * Get the currently active toggles regardless of whether they come from custom state or default configuration
+     * Get the full current state including active toggles, peek toggles, and tabs
      */
-    getCurrentActiveToggles() {
+    getCurrentState() {
         if (this.lastAppliedState) {
-            return this.lastAppliedState.toggles || [];
+            return this.cloneState(this.lastAppliedState);
         }
         if (this.config) {
-            return this.getComputedDefaultState().toggles || [];
+            return this.cloneState(this.getComputedDefaultState());
         }
-        return [];
+        return {};
     }
     /**
      * Clear all persistence and reset to default
@@ -3526,10 +3702,6 @@ const WIDGET_STYLES = `
   color: rgba(255, 255, 255, 0.6);
 }
 
-.cv-widget-theme-dark .cv-toggle-slider {
-  background: rgba(255, 255, 255, 0.2);
-}
-
 .cv-widget-theme-dark .cv-tab-group-description {
   color: rgba(255, 255, 255, 0.8);
 }
@@ -3650,40 +3822,32 @@ const WIDGET_STYLES = `
 }
 
 .cv-toggle-input {
+  /* Only hide if it is part of a custom slider toggle */
+}
+.cv-toggle-label .cv-toggle-input {
   opacity: 0;
   width: 0;
   height: 0;
 }
 
-.cv-toggle-slider {
-  position: absolute;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background: rgba(0, 0, 0, 0.2);
-  border-radius: 9999px;
-  transition: background-color 0.2s ease;
-}
-
-.cv-toggle-slider:before {
-  position: absolute;
-  content: "";
-  height: 1rem;
-  width: 1rem;
-  left: 0.25rem;
-  bottom: 0.25rem;
-  background: white;
-  border-radius: 50%;
-  transition: transform 0.2s ease;
+.cv-toggle-radios {
+  display: flex;
+  gap: 8px;
 }
 
-.cv-toggle-input:checked + .cv-toggle-slider {
-  background: #3e84f4;
+.cv-radio-label {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 0.85rem;
+  cursor: pointer;
 }
 
-.cv-toggle-input:checked + .cv-toggle-slider:before {
-  transform: translateX(1.25rem);
+.cv-radio-label input {
+  margin: 0;
+  opacity: 1;
+  width: auto;
+  height: auto;
 }
 
 /* Dark theme toggle switch styles */
@@ -4032,97 +4196,7 @@ const WIDGET_STYLES = `
 }
 
 /* Dark theme custom state styles */
-/* Welcome modal styles */
-.cv-welcome-modal {
-  max-width: 32rem;
-  width: 90vw;
-  background: white;
-  border-radius: 0.75rem;
-  box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
-  animation: slideIn 0.2s ease;
-  display: flex;
-  flex-direction: column;
-}
-
-.cv-modal-main {
-  padding: 1rem;
-  flex: 1;
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-  overflow-y: auto;
-  max-height: calc(80vh - 8rem);
-}
-
-.cv-welcome-message {
-  font-size: 0.875rem;
-  color: rgba(0, 0, 0, 0.8);
-  margin: 0;
-  line-height: 1.4;
-  text-align: center;
-}
-
-.cv-welcome-message a {
-  color: #3e84f4;
-  text-align: justify;
-  text-decoration: none;
-}
-
-.cv-welcome-message a:hover {
-  text-decoration: underline;
-}
-
-.cv-welcome-widget-preview {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 1rem;
-  padding: 1rem;
-  background: #f8f9fa;
-  border-radius: 0.5rem;
-  margin: 1rem 0;
-}
-
-.cv-welcome-widget-icon {
-  width: 2rem;
-  height: 2rem;
-  background: rgba(62, 132, 244, 0.1);
-  border-radius: 9999px;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  animation: cv-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
-  color: #3e84f4;
-}
-
-.cv-welcome-widget-label {
-  font-size: 0.875rem;
-  font-weight: 500;
-  color: rgba(0, 0, 0, 0.8);
-  margin: 0;
-}
-
-.cv-welcome-got-it {
-  width: 100%;
-  background: #3e84f4;
-  color: white;
-  font-weight: 600;
-  padding: 0.75rem 1rem;
-  border-radius: 0.5rem;
-  border: none;
-  cursor: pointer;
-  font-size: 0.875rem;
-  transition: background-color 0.2s ease;
-  outline: none;
-}
 
-.cv-welcome-got-it:hover {
-  background: rgba(62, 132, 244, 0.9);
-}
-
-.cv-welcome-got-it:focus {
-  box-shadow: 0 0 0 2px rgba(62, 132, 244, 0.5);
-}
 
 /* Animations */
 @keyframes cv-pulse {
@@ -4134,26 +4208,7 @@ const WIDGET_STYLES = `
   }
 }
 
-/* Dark theme welcome modal styles */
-.cv-widget-theme-dark .cv-welcome-modal {
-  background: #101722;
-}
 
-.cv-widget-theme-dark .cv-welcome-message {
-  color: rgba(255, 255, 255, 0.8);
-}
-
-.cv-widget-theme-dark .cv-welcome-message a {
-  color: #60a5fa;
-}
-
-.cv-widget-theme-dark .cv-welcome-widget-preview {
-  background: rgba(255, 255, 255, 0.1);
-}
-
-.cv-widget-theme-dark .cv-welcome-widget-label {
-  color: #e2e8f0;
-}
 
 /* Dark theme logo box */
 .cv-widget-theme-dark .cv-tabgroup-logo-box {
@@ -4328,6 +4383,176 @@ const WIDGET_STYLES = `
 .cv-widget-theme-dark .cv-share-action-btn.primary:hover {
   background: #2b74e6;
 }
+
+/* Intro Callout styles */
+.cv-widget-callout {
+  position: fixed;
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
+  padding: 12px 16px;
+  width: 260px;
+  z-index: 9999;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  animation: cvFadeIn 0.3s ease-out;
+  pointer-events: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.cv-widget-callout-text {
+  font-size: 0.9rem;
+  color: #333;
+  margin: 0;
+  line-height: 1.4;
+}
+
+.cv-widget-callout-close {
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  width: 18px;
+  height: 18px;
+  border: none;
+  background: rgba(0,0,0,0.05);
+  color: #666;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  font-size: 14px;
+  line-height: 1;
+  padding: 0;
+  transition: all 0.2s ease;
+}
+
+.cv-widget-callout-close:hover {
+  background: #f0f0f0;
+  color: #333;
+}
+
+/* Callout positioning and arrow */
+.cv-widget-callout::after {
+  content: '';
+  position: absolute;
+  width: 10px;
+  height: 10px;
+  background: white;
+  transform: rotate(45deg);
+  box-shadow: 1px 1px 1px rgba(0,0,0,0.05); /* subtle shadow for arrow */
+}
+
+/* Top-Right Widget -> Callout to the left */
+.cv-widget-callout.cv-pos-top-right {
+  top: 20px;
+  right: 64px;
+}
+.cv-widget-callout.cv-pos-top-right::after {
+  top: 13px;
+  right: -5px;
+  box-shadow: 1px -1px 1px rgba(0,0,0,0.05);
+  transform: rotate(45deg);
+}
+
+/* Bottom-Right Widget -> Callout to the left */
+.cv-widget-callout.cv-pos-bottom-right {
+  bottom: 20px;
+  right: 64px;
+}
+.cv-widget-callout.cv-pos-bottom-right::after {
+  bottom: 13px;
+  right: -5px;
+}
+
+/* Top-Left Widget -> Callout to the right */
+.cv-widget-callout.cv-pos-top-left {
+  top: 20px;
+  left: 64px;
+}
+.cv-widget-callout.cv-pos-top-left::after {
+  top: 13px;
+  left: -5px;
+}
+
+/* Bottom-Left Widget -> Callout to the right */
+.cv-widget-callout.cv-pos-bottom-left {
+  bottom: 20px;
+  left: 64px;
+}
+.cv-widget-callout.cv-pos-bottom-left::after {
+  bottom: 13px;
+  left: -5px;
+}
+
+/* Middle-Right Widget -> Callout to the left */
+.cv-widget-callout.cv-pos-middle-right {
+  top: 50%;
+  right: 64px;
+  transform: translateY(-50%);
+}
+.cv-widget-callout.cv-pos-middle-right::after {
+  top: 50%;
+  right: -5px;
+  transform: translateY(-50%) rotate(45deg);
+}
+
+/* Middle-Left Widget -> Callout to the right */
+.cv-widget-callout.cv-pos-middle-left {
+  top: 50%;
+  left: 64px;
+  transform: translateY(-50%);
+}
+.cv-widget-callout.cv-pos-middle-left::after {
+  top: 50%;
+  left: -5px;
+  transform: translateY(-50%) rotate(45deg);
+}
+
+/* Pulse animation utility */
+.cv-widget-icon.cv-pulse {
+  animation: cv-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  box-shadow: 0 0 0 0 rgba(62, 132, 244, 0.7);
+}
+
+@keyframes cv-pulse {
+  0% {
+    transform: scale(1);
+    box-shadow: 0 0 0 0 rgba(62, 132, 244, 0.7);
+  }
+  70% {
+    transform: scale(1.05);
+    box-shadow: 0 0 0 10px rgba(62, 132, 244, 0);
+  }
+  100% {
+    transform: scale(1);
+    box-shadow: 0 0 0 0 rgba(62, 132, 244, 0);
+  }
+}
+
+/* Dark Theme */
+.cv-widget-theme-dark .cv-widget-callout {
+    background: #1f2937; /* Tailwind gray-800 mostly */
+    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.5);
+    border: 1px solid rgba(255,255,255,0.1);
+}
+.cv-widget-theme-dark .cv-widget-callout::after {
+    background: #1f2937;
+    border-top: 1px solid rgba(255,255,255,0.1);
+    border-right: 1px solid rgba(255,255,255,0.1);
+}
+.cv-widget-theme-dark .cv-widget-callout-text {
+    color: #e5e7eb;
+}
+.cv-widget-theme-dark .cv-widget-callout-close {
+    background: rgba(255,255,255,0.1);
+    color: #9ca3af;
+}
+.cv-widget-theme-dark .cv-widget-callout-close:hover {
+    background: rgba(255,255,255,0.2);
+    color: #fff;
+}
 `;
 /**
  * Inject widget styles into the document head
@@ -4346,6 +4571,7 @@ class CustomViewsWidget {
     core;
     container;
     widgetIcon = null;
+    introCallout = null;
     options;
     _hasVisibleConfig = false;
     pageToggleIds = new Set();
@@ -4366,8 +4592,7 @@ class CustomViewsWidget {
             title: options.title || 'Customize View',
             description: options.description || '',
             showWelcome: options.showWelcome ?? false,
-            welcomeTitle: options.welcomeTitle || 'Site Customization',
-            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>.',
+            welcomeMessage: options.welcomeMessage || 'Customize your reading experience (theme, toggles, tabs) here.',
             showTabGroups: options.showTabGroups ?? true
         };
         // Determine if there are any configurations to show
@@ -4409,9 +4634,9 @@ class CustomViewsWidget {
         this.attachEventListeners();
         // Always append to body since it's a floating icon
         document.body.appendChild(this.widgetIcon);
-        // Show welcome modal on first visit if enabled
+        // Show intro callout on first visit if enabled
         if (this.options.showWelcome) {
-            this.showWelcomeModalIfFirstVisit();
+            this.showIntroCalloutIfFirstVisit();
         }
         return this.widgetIcon;
     }
@@ -4441,6 +4666,11 @@ class CustomViewsWidget {
             this.stateModal.remove();
             this.stateModal = null;
         }
+        // Clean up callout
+        if (this.introCallout) {
+            this.introCallout.remove();
+            this.introCallout = null;
+        }
     }
     attachEventListeners() {
         if (!this.widgetIcon)
@@ -4456,10 +4686,48 @@ class CustomViewsWidget {
             this.stateModal.classList.add('cv-hidden');
         }
     }
+    /**
+     * Dismiss the intro callout
+     */
+    dismissIntroCallout() {
+        if (!this.introCallout)
+            return;
+        const callout = this.introCallout;
+        // Clear reference immediately from class to prevent re-use
+        this.introCallout = null;
+        callout.remove();
+        // Stop pulsing the widget icon
+        if (this.widgetIcon) {
+            this.widgetIcon.classList.remove('cv-pulse');
+        }
+        // Mark as shown in localStorage
+        try {
+            localStorage.setItem('cv-intro-shown', 'true');
+        }
+        catch (e) {
+            // Ignore localStorage errors
+        }
+    }
     /**
      * Open the custom state creator
      */
     openStateModal() {
+        // Dismiss intro callout if valid
+        if (this.introCallout) {
+            this.dismissIntroCallout();
+        }
+        else {
+            // Even if no callout is shown (e.g. page had no content), opening the widget
+            // should count as "seen", preventing future callouts.
+            try {
+                if (!localStorage.getItem('cv-intro-shown')) {
+                    localStorage.setItem('cv-intro-shown', 'true');
+                }
+            }
+            catch (e) {
+                // Ignore localStorage errors
+            }
+        }
         if (!this.stateModal) {
             this._createStateModal();
         }
@@ -4500,10 +4768,20 @@ class CustomViewsWidget {
           <div>
             <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.id}"/>
-            <span class="cv-toggle-slider"></span>
-          </label>
+          <div class="cv-toggle-radios">
+             <label class="cv-radio-label" title="Hide">
+               <input class="cv-toggle-input" type="radio" name="cv-toggle-${toggle.id}" value="hide" data-toggle="${toggle.id}"/>
+               <span>Hide</span>
+             </label>
+             <label class="cv-radio-label" title="Peek">
+               <input class="cv-toggle-input" type="radio" name="cv-toggle-${toggle.id}" value="peek" data-toggle="${toggle.id}"/>
+               <span>Peek</span>
+             </label>
+             <label class="cv-radio-label" title="Show">
+               <input class="cv-toggle-input" type="radio" name="cv-toggle-${toggle.id}" value="show" data-toggle="${toggle.id}"/>
+               <span>Show</span>
+             </label>
+          </div>
         </div>
       </div>
     `).join('');
@@ -4704,10 +4982,11 @@ class CustomViewsWidget {
                 if (groupId && tabId) {
                     const currentTabs = this.core.getCurrentActiveTabs();
                     currentTabs[groupId] = tabId;
-                    const currentToggles = this.core.getCurrentActiveToggles();
+                    const currentState = this.core.getCurrentState();
                     const newState = {
-                        toggles: currentToggles,
-                        tabs: currentTabs
+                        shownToggles: currentState.shownToggles || [],
+                        peekToggles: currentState.peekToggles || [], // Preserve peek state, fallback to empty array
+                        tabs: currentTabs,
                     };
                     this.core.applyState(newState, { source: 'widget' });
                 }
@@ -4805,25 +5084,33 @@ class CustomViewsWidget {
         }
         // Collect toggle values
         const toggles = [];
-        const toggleInputs = this.stateModal.querySelectorAll('.cv-toggle-input');
-        toggleInputs.forEach(toggleInput => {
-            const toggle = toggleInput.dataset.toggle;
-            if (toggle && toggleInput.checked) {
-                toggles.push(toggle);
-            }
-        });
-        // Collect tab selections
-        const tabGroupSelects = this.stateModal.querySelectorAll('.cv-tabgroup-select');
-        const tabs = {};
-        tabGroupSelects.forEach(select => {
-            const groupId = select.dataset.groupId;
-            if (groupId) {
-                tabs[groupId] = select.value;
+        const peekToggles = [];
+        // Get all radio inputs
+        const radios = this.stateModal.querySelectorAll('input[type="radio"]:checked');
+        radios.forEach(radio => {
+            const input = radio;
+            const toggleId = input.getAttribute('data-toggle');
+            if (toggleId) {
+                if (input.value === 'show') {
+                    toggles.push(toggleId);
+                }
+                else if (input.value === 'peek') {
+                    peekToggles.push(toggleId);
+                }
             }
         });
-        const result = { toggles };
-        if (Object.keys(tabs).length > 0) {
-            result.tabs = tabs;
+        const result = { shownToggles: toggles, peekToggles };
+        // Get active tabs from selects
+        const selects = this.stateModal.querySelectorAll('select[data-group-id]');
+        if (selects.length > 0) {
+            result.tabs = {};
+            selects.forEach(select => {
+                const el = select;
+                const groupId = el.getAttribute('data-group-id');
+                if (groupId) {
+                    result.tabs[groupId] = el.value;
+                }
+            });
         }
         return result;
     }
@@ -4843,18 +5130,29 @@ class CustomViewsWidget {
     loadCurrentStateIntoForm() {
         if (!this.stateModal)
             return;
-        // Get currently active toggles (from custom state or default configuration)
-        const activeToggles = this.core.getCurrentActiveToggles();
-        // First, uncheck all toggle inputs
+        // We need complete state for both shown and peek toggles
+        const currentState = this.core.getCurrentState();
+        const currentToggles = currentState.shownToggles || [];
+        const currentPeekToggles = currentState.peekToggles || [];
+        // Reset all inputs first (optional, but good for clarity)
         const allToggleInputs = this.stateModal.querySelectorAll('.cv-toggle-input');
-        allToggleInputs.forEach(toggleInput => {
-            toggleInput.checked = false;
+        // Identify unique toggles present in the modal
+        const uniqueToggles = new Set();
+        allToggleInputs.forEach(input => {
+            if (input.dataset.toggle)
+                uniqueToggles.add(input.dataset.toggle);
         });
-        // Then check the ones that should be active
-        activeToggles.forEach(toggle => {
-            const toggleInput = this.stateModal?.querySelector(`[data-toggle="${toggle}"]`);
-            if (toggleInput) {
-                toggleInput.checked = true;
+        uniqueToggles.forEach(toggleId => {
+            let valueToSelect = 'hide';
+            if (currentToggles.includes(toggleId)) {
+                valueToSelect = 'show';
+            }
+            else if (currentPeekToggles.includes(toggleId)) {
+                valueToSelect = 'peek';
+            }
+            const input = this.stateModal.querySelector(`input[name="cv-toggle-${toggleId}"][value="${valueToSelect}"]`);
+            if (input) {
+                input.checked = true;
             }
         });
         // Load tab group selections
@@ -4887,88 +5185,70 @@ class CustomViewsWidget {
         }
     }
     /**
-     * Check if this is the first visit and show welcome modal
+     * Check if this is the first visit and show intro callout
      */
-    showWelcomeModalIfFirstVisit() {
+    showIntroCalloutIfFirstVisit() {
         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) {
-            // Show welcome modal after a short delay to let the page settle
+        // Strict check: Only show callout if there is actual content on the page to customize.
+        // We check the core registry for any active toggles or tab groups.
+        if (!this.core.hasActiveComponents()) {
+            return;
+        }
+        const STORAGE_KEY = 'cv-intro-shown';
+        // Check if intro has been shown before
+        let hasSeenIntro = null;
+        try {
+            hasSeenIntro = localStorage.getItem(STORAGE_KEY);
+        }
+        catch (e) {
+            // Ignore localStorage errors (e.g. private mode)
+        }
+        if (!hasSeenIntro) {
+            // Show callout after a short delay
             setTimeout(() => {
-                this.createWelcomeModal();
-            }, 500);
-            // Mark as shown
-            localStorage.setItem(STORAGE_KEY, 'true');
+                this.createCallout();
+            }, 1000);
         }
     }
     /**
-     * Create and show the welcome modal
+     * Create and show the intro callout
      */
-    createWelcomeModal() {
-        // Don't show if there's already a modal open
-        if (this.stateModal && !this.stateModal.classList.contains('cv-hidden'))
+    createCallout() {
+        // Avoid duplicates
+        if (this.introCallout || document.querySelector('.cv-widget-callout'))
             return;
-        const welcomeModal = document.createElement('div');
-        welcomeModal.className = 'cv-widget-modal-overlay cv-welcome-modal-overlay';
+        this.introCallout = document.createElement('div');
+        const callout = this.introCallout;
+        callout.className = `cv-widget-callout cv-pos-${this.options.position}`;
         if (this.options.theme === 'dark') {
-            welcomeModal.classList.add('cv-widget-theme-dark');
+            callout.classList.add('cv-widget-theme-dark');
+        }
+        // Close button
+        const closeBtn = document.createElement('button');
+        closeBtn.className = 'cv-widget-callout-close';
+        closeBtn.innerHTML = '×';
+        closeBtn.setAttribute('aria-label', 'Dismiss intro');
+        closeBtn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            this.dismissIntroCallout();
+        });
+        // Message
+        const msg = document.createElement('p');
+        msg.className = 'cv-widget-callout-text';
+        msg.textContent = this.options.welcomeMessage;
+        callout.appendChild(closeBtn);
+        callout.appendChild(msg);
+        document.body.appendChild(callout);
+        // Add pulse to widget icon to draw attention
+        if (this.widgetIcon) {
+            this.widgetIcon.classList.add('cv-pulse');
         }
-        welcomeModal.innerHTML = `
-      <div class="cv-widget-modal cv-welcome-modal">
-        <header class="cv-modal-header">
-          <div class="cv-modal-header-content">
-            <div class="cv-modal-icon">
-              ${getGearIcon()}
-            </div>
-            <h1 class="cv-modal-title">${this.options.welcomeTitle}</h1>
-          </div>
-        </header>
-        <div class="cv-modal-main">
-          <p class="cv-welcome-message">${this.options.welcomeMessage}</p>
-          
-          <div class="cv-welcome-widget-preview">
-            <div class="cv-welcome-widget-icon">
-              ${getGearIcon()}
-            </div>
-            <p class="cv-welcome-widget-label">Look for this widget</p>
-          </div>
-          
-          <button class="cv-welcome-got-it">Got it!</button>
-        </div>
-      </div>
-    `;
-        document.body.appendChild(welcomeModal);
-        this.attachWelcomeModalEventListeners(welcomeModal);
-    }
-    /**
-     * Attach event listeners for welcome modal
-     */
-    attachWelcomeModalEventListeners(welcomeModal) {
-        const closeModal = () => {
-            welcomeModal.remove();
-            document.removeEventListener('keydown', handleEscape);
-        };
-        // Got it button
-        const gotItBtn = welcomeModal.querySelector('.cv-welcome-got-it');
-        if (gotItBtn) {
-            gotItBtn.addEventListener('click', closeModal);
-        }
-        // Overlay click to close
-        welcomeModal.addEventListener('click', (e) => {
-            if (e.target === welcomeModal) {
-                closeModal();
-            }
+        // Auto-dismiss and open widget on click anywhere on callout
+        callout.addEventListener('click', () => {
+            this.dismissIntroCallout();
+            this.openStateModal();
         });
-        // Escape key to close
-        const handleEscape = (e) => {
-            if (e.key === 'Escape') {
-                closeModal();
-            }
-        };
-        document.addEventListener('keydown', handleEscape);
     }
 }