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

package/dist/custom-views.js

@@ -1,5 +1,5 @@
 /*!
- * @customviews-js/customviews v1.4.1-beta.0
+ * @customviews-js/customviews v1.4.1-beta.1
  * (c) 2025 Chan Ger Teck
  * Released under the MIT License.
  */
@@ -710,7 +710,7 @@
                         });
                     }
                     // 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);
                 });
@@ -2738,6 +2738,12 @@ ${TAB_STYLES}
                 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;
         }
@@ -4196,97 +4202,7 @@ ${TAB_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 {
@@ -4298,26 +4214,7 @@ ${TAB_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 {
@@ -4492,6 +4389,176 @@ ${TAB_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
@@ -4510,6 +4577,7 @@ ${TAB_STYLES}
         core;
         container;
         widgetIcon = null;
+        introCallout = null;
         options;
         _hasVisibleConfig = false;
         pageToggleIds = new Set();
@@ -4530,8 +4598,7 @@ ${TAB_STYLES}
                 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
@@ -4573,9 +4640,9 @@ ${TAB_STYLES}
             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;
         }
@@ -4605,6 +4672,11 @@ ${TAB_STYLES}
                 this.stateModal.remove();
                 this.stateModal = null;
             }
+            // Clean up callout
+            if (this.introCallout) {
+                this.introCallout.remove();
+                this.introCallout = null;
+            }
         }
         attachEventListeners() {
             if (!this.widgetIcon)
@@ -4620,10 +4692,48 @@ ${TAB_STYLES}
                 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();
             }
@@ -5081,88 +5191,70 @@ ${TAB_STYLES}
             }
         }
         /**
-         * 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);
         }
     }