rails_onboarding 0.8.7 → 0.8.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 735f78958744dc1965b60dbbe1fd195bcf252c179b7ef5b582462410ec1af3ea
-  data.tar.gz: 302e224c0b4c63800c7f7eec5f49a63063dd4cbf8bd47b5d739a897d021f5d07
+  metadata.gz: 5de350daba589470bba3cfa3afe9daa037307873d47a888f81899b2e542172fa
+  data.tar.gz: 6871219f6639948ec9e66747c2e89be3b58d2260d6ef8bc2750a84900db14b1d
 SHA512:
-  metadata.gz: dddebe786b830ba2ae4fe7cfaa0897e2eeec2b0a35b697ca9ffdf8a62df56702c4d4b86580396e40c19a9c15fa49b3fdf0ff94e5afde9c94008755a62de47123
-  data.tar.gz: d8c1a9c239d9567f9474563d196163c3108d65cdd260a4278e41065469db5136b9faa8d72cf328a969bcea472c81856bb31ab9d9514774f63c89c28fc34a9b6b
+  metadata.gz: 2b6e4ccc57e00c7d41e4b21604be312330888ac2cc96e6b8ef0bc39206c529416ddc35f5d4bdc998632a6488fca0ce2a1c53e900c50115a17b08c17c2f9193f3
+  data.tar.gz: a4714eaed7cca529878cc9cc99ed06e0e48fa117a1cfa7f327eed5e9de97abf98cf5c35cc4ef7b51e2c8449cca5e78bf64953f9d2a8b2114487b60a9a0dc27d5

data/app/assets/javascripts/rails_onboarding/tour_controller.js

@@ -39,6 +39,7 @@ export default class extends Controller {
 
         this.parseSteps()
         this.setupKeyboardHandlers()
+        this.setupViewportHandlers()
 
         // Auto-start if configured and not completed
         if (this.autoStartValue && !this.isTourCompleted()) {
@@ -188,6 +189,9 @@ export default class extends Controller {
         // Find target element
         const targetElement = step.selector ? document.querySelector(step.selector) : null
 
+        this.currentTargetElement = targetElement
+        this.applyScrim(step, targetElement)
+
         if (targetElement) {
             this.scrollToElement(targetElement, step)
             this.createHighlight(targetElement, step)
@@ -269,7 +273,7 @@ export default class extends Controller {
             left: 0;
             width: 100%;
             height: 100%;
-            background: rgba(0, 0, 0, ${this.overlayOpacityValue});
+            background: transparent;
             z-index: 9998;
             opacity: 0;
             transition: opacity 0.3s ease;
@@ -277,8 +281,12 @@ export default class extends Controller {
 
         document.body.appendChild(this.overlay)
 
-        // Prevent body scroll
-        document.body.style.overflow = 'hidden'
+        // Deliberately no `document.body.style.overflow = 'hidden'` here. The overlay is
+        // position:fixed and already covers the viewport, and locking the body made
+        // scrollToElement()'s window.scrollTo a no-op - so a target below the fold was
+        // spotlit off-screen, since the spotlight and popup are placed from
+        // getBoundingClientRect(). Scrolling stays live and repositionCurrentStep()
+        // keeps the highlight glued to its element instead.
 
         // Trigger fade in
         requestAnimationFrame(() => {
@@ -290,18 +298,15 @@ export default class extends Controller {
      * Remove modal overlay
      */
     removeOverlay() {
-        if (!this.overlay) return
+        const overlay = this.overlay
+        if (!overlay) return
 
-        this.overlay.style.opacity = '0'
+        document.documentElement.style.removeProperty('--onboarding-tour-scrim')
+        this.overlay = null
+        overlay.style.opacity = '0'
 
         setTimeout(() => {
-            if (this.overlay && this.overlay.parentNode) {
-                this.overlay.parentNode.removeChild(this.overlay)
-            }
-            this.overlay = null
-
-            // Restore body scroll
-            document.body.style.overflow = ''
+            if (overlay.parentNode) overlay.parentNode.removeChild(overlay)
         }, 300)
     }
 
@@ -336,7 +341,6 @@ export default class extends Controller {
                     left: ${rect.left - padding}px;
                     width: ${rect.width + (padding * 2)}px;
                     height: ${rect.height + (padding * 2)}px;
-                    box-shadow: 0 0 0 9999px rgba(0, 0, 0, ${this.overlayOpacityValue});
                     border-radius: 8px;
                 `
                 break
@@ -372,11 +376,39 @@ export default class extends Controller {
 
         document.body.appendChild(this.spotlight)
 
-        // Make highlighted element interactive
+        // Make highlighted element interactive, remembering what we overwrote so
+        // removeHighlight() can put it back without searching the document.
+        this.highlightedElement = element
+        this.previousElementPosition = element.style.position
+        this.previousElementZIndex = element.style.zIndex
         element.style.position = 'relative'
         element.style.zIndex = '10000'
     }
 
+    /**
+     * Decide which layer paints the scrim for this step, and at what strength.
+     *
+     * A 'spotlight' highlight is already a full-viewport scrim - its box-shadow has a
+     * 9999px spread and covers everything but the cutout - so painting the overlay on
+     * top of it darkens every pixel twice. At the default 0.7 that composites to ~0.92,
+     * which buries the surrounding page and leaves someone unfamiliar with the layout
+     * with no idea what the highlight is being singled out *from*. Every other style
+     * (border, glow, none) draws no scrim of its own, and nor does a step with no target
+     * element, so those still need the overlay.
+     */
+    applyScrim(step, targetElement) {
+        document.documentElement.style.setProperty(
+            '--onboarding-tour-scrim', this.overlayOpacityValue
+        )
+
+        if (!this.overlay) return
+
+        const spotlit = Boolean(targetElement) && step.highlightStyle === 'spotlight'
+        this.overlay.style.background = spotlit
+            ? 'transparent'
+            : `rgba(0, 0, 0, ${this.overlayOpacityValue})`
+    }
+
     /**
      * Remove highlight/spotlight
      */
@@ -388,10 +420,14 @@ export default class extends Controller {
             this.spotlight = null
         }
 
-        // Reset z-index of previously highlighted elements
-        document.querySelectorAll('[style*="z-index: 10000"]').forEach(el => {
-            el.style.zIndex = ''
-        })
+        // Restore only the element we actually touched. This used to sweep the whole
+        // document for [style*="z-index: 10000"], which clears the inline z-index of
+        // unrelated host-app elements that happen to carry that value.
+        if (this.highlightedElement) {
+            this.highlightedElement.style.position = this.previousElementPosition || ''
+            this.highlightedElement.style.zIndex = this.previousElementZIndex || ''
+            this.highlightedElement = null
+        }
     }
 
     /**
@@ -425,20 +461,20 @@ export default class extends Controller {
 
                 <div class="tour-popup-actions">
                     ${step.showSkip ? `
-                        <button type="button" class="tour-btn tour-btn-skip" data-action="click->tour#skip">
+                        <button type="button" class="tour-btn tour-btn-skip">
                             ${step.skipLabel}
                         </button>
                     ` : '<div></div>'}
 
                     <div class="tour-popup-nav">
                         ${step.showPrev && !isFirstStep ? `
-                            <button type="button" class="tour-btn tour-btn-prev" data-action="click->tour#previous">
+                            <button type="button" class="tour-btn tour-btn-prev">
                                 ← ${step.prevLabel}
                             </button>
                         ` : ''}
 
                         ${step.showNext ? `
-                            <button type="button" class="tour-btn tour-btn-next" data-action="click->tour#next">
+                            <button type="button" class="tour-btn tour-btn-next">
                                 ${isLastStep ? step.completeLabel : step.nextLabel} →
                             </button>
                         ` : ''}
@@ -452,32 +488,49 @@ export default class extends Controller {
 
         document.body.appendChild(this.popup)
 
+        // The popup lives on document.body, so that host overflow and stacking
+        // contexts cannot clip it - which also puts it outside every controller
+        // scope, where Stimulus will not bind a data-action. These buttons are
+        // wired directly for that reason; a data-action on them would be silently
+        // inert, which is what left the tour unable to advance at all.
+        this.bindPopupActions()
+
         // Position popup relative to target
         this.positionPopup(step, targetElement)
 
         // Animate in
         requestAnimationFrame(() => {
-            this.popup.style.opacity = '1'
-            this.popup.style.transform = 'scale(1)'
+            if (this.popup) this.popup.classList.add('onboarding-show')
         })
     }
 
+    /**
+     * Wire the popup's own controls. See the note in createPopup().
+     */
+    bindPopupActions() {
+        const actions = {
+            '.tour-btn-next': () => this.next(),
+            '.tour-btn-prev': () => this.previous(),
+            '.tour-btn-skip': () => this.skip()
+        }
+
+        for (const [selector, handler] of Object.entries(actions)) {
+            this.popup.querySelector(selector)?.addEventListener('click', (event) => {
+                event.preventDefault()
+                handler()
+            })
+        }
+    }
+
     /**
      * Style the popup element
      */
     stylePopup(step) {
-        this.popup.style.cssText = `
-            position: fixed;
-            z-index: 10001;
-            background: white;
-            border-radius: 12px;
-            box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
-            max-width: ${step.width}px;
-            width: calc(100% - 2rem);
-            opacity: 0;
-            transform: scale(0.95);
-            transition: all 0.3s ease;
-        `
+        // Only the per-step width is set inline. Everything else - including the
+        // background - belongs to `.tour-popup` in tour.css, so that a host app
+        // redefining the --onboarding-* tokens (and the dark-mode block that flips
+        // them) actually reaches the popup. An inline background would win over both.
+        this.popup.style.maxWidth = `${step.width}px`
     }
 
     /**
@@ -569,17 +622,19 @@ export default class extends Controller {
      * Remove popup
      */
     removePopup() {
-        if (this.popup) {
-            this.popup.style.opacity = '0'
-            this.popup.style.transform = 'scale(0.95)'
+        const popup = this.popup
+        if (!popup) return
 
-            setTimeout(() => {
-                if (this.popup && this.popup.parentNode) {
-                    this.popup.parentNode.removeChild(this.popup)
-                }
-                this.popup = null
-            }, 300)
-        }
+        // Detach from the instance up front and let the timeout close over the local.
+        // createPopup() calls removePopup() and then assigns a new this.popup straight
+        // away, so a timeout reading the instance property would remove the popup that
+        // replaced this one - every Next and Previous would blank the tour after 300ms.
+        this.popup = null
+        popup.classList.remove('onboarding-show')
+
+        setTimeout(() => {
+            if (popup.parentNode) popup.parentNode.removeChild(popup)
+        }, 300)
     }
 
     /**
@@ -623,6 +678,38 @@ export default class extends Controller {
         }
     }
 
+    /**
+     * Re-place the highlight and popup for the current step. The spotlight and popup
+     * are position:fixed and derived from getBoundingClientRect(), so they have to be
+     * recomputed whenever the viewport moves under them.
+     */
+    repositionCurrentStep() {
+        if (!this.isActive) return
+
+        const step = this.tourSteps[this.currentStepIndex]
+        if (!step) return
+
+        const element = this.currentTargetElement
+        if (element && element.isConnected) {
+            this.createHighlight(element, step)
+        }
+        this.positionPopup(step, element)
+    }
+
+    /**
+     * Setup viewport handlers that keep the current step aligned
+     */
+    setupViewportHandlers() {
+        this.viewportHandler = () => {
+            if (!this.isActive) return
+            if (this.viewportFrame) cancelAnimationFrame(this.viewportFrame)
+            this.viewportFrame = requestAnimationFrame(() => this.repositionCurrentStep())
+        }
+
+        window.addEventListener('scroll', this.viewportHandler, { passive: true })
+        window.addEventListener('resize', this.viewportHandler)
+    }
+
     /**
      * Setup keyboard event handlers
      */
@@ -759,5 +846,12 @@ export default class extends Controller {
         if (this.keyboardHandler) {
             document.removeEventListener('keydown', this.keyboardHandler)
         }
+
+        if (this.viewportHandler) {
+            window.removeEventListener('scroll', this.viewportHandler)
+            window.removeEventListener('resize', this.viewportHandler)
+        }
+
+        if (this.viewportFrame) cancelAnimationFrame(this.viewportFrame)
     }
 }

data/app/assets/stylesheets/rails_onboarding/tour.css

@@ -22,60 +22,56 @@
   border-radius: 8px;
 }
 
-/* Spotlight style - Creates cutout effect */
+/* Spotlight style - Creates cutout effect.
+   The 9999px spread makes this box-shadow a full-viewport scrim in its own right, so
+   tour_controller stops painting .tour-overlay whenever a spotlight is drawn - the two
+   together composited to ~0.92 and buried the surrounding page.
+   The alpha comes from --onboarding-tour-scrim, which the controller sets on :root from
+   its overlayOpacity value. It is deliberately not animated: an animation on this
+   property overrides the inline style, which is what made overlayOpacity a dead knob. */
 .tour-spotlight-spotlight {
-  box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.7);
-  animation: onboarding-spotlightPulse 2s ease-in-out infinite;
-}
-
-@keyframes onboarding-spotlightPulse {
-  0%, 100% {
-    box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.7);
-  }
-  50% {
-    box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.75);
-  }
+  box-shadow: 0 0 0 9999px rgba(0, 0, 0, var(--onboarding-tour-scrim, 0.7));
 }
 
 /* Border highlight style */
 .tour-spotlight-border {
-  border: 3px solid #3b82f6;
-  box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.2);
+  border: 3px solid var(--onboarding-primary);
+  box-shadow: 0 0 0 4px color-mix(in srgb, var(--onboarding-primary) 20%, transparent);
   animation: onboarding-borderPulse 2s ease-in-out infinite;
 }
 
 @keyframes onboarding-borderPulse {
   0%, 100% {
-    border-color: #3b82f6;
-    box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.2);
+    border-color: var(--onboarding-primary);
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--onboarding-primary) 20%, transparent);
   }
   50% {
-    border-color: #2563eb;
-    box-shadow: 0 0 0 6px rgba(37, 99, 235, 0.3);
+    border-color: var(--onboarding-primary-hover);
+    box-shadow: 0 0 0 6px color-mix(in srgb, var(--onboarding-primary-hover) 30%, transparent);
   }
 }
 
 /* Glow highlight style */
 .tour-spotlight-glow {
   box-shadow:
-    0 0 0 4px rgba(59, 130, 246, 0.3),
-    0 0 20px 8px rgba(59, 130, 246, 0.4),
-    inset 0 0 20px rgba(59, 130, 246, 0.2);
+    0 0 0 4px color-mix(in srgb, var(--onboarding-primary) 30%, transparent),
+    0 0 20px 8px color-mix(in srgb, var(--onboarding-primary) 40%, transparent),
+    inset 0 0 20px color-mix(in srgb, var(--onboarding-primary) 20%, transparent);
   animation: onboarding-glowPulse 2s ease-in-out infinite;
 }
 
 @keyframes onboarding-glowPulse {
   0%, 100% {
     box-shadow:
-      0 0 0 4px rgba(59, 130, 246, 0.3),
-      0 0 20px 8px rgba(59, 130, 246, 0.4),
-      inset 0 0 20px rgba(59, 130, 246, 0.2);
+      0 0 0 4px color-mix(in srgb, var(--onboarding-primary) 30%, transparent),
+      0 0 20px 8px color-mix(in srgb, var(--onboarding-primary) 40%, transparent),
+      inset 0 0 20px color-mix(in srgb, var(--onboarding-primary) 20%, transparent);
   }
   50% {
     box-shadow:
-      0 0 0 6px rgba(59, 130, 246, 0.4),
-      0 0 30px 12px rgba(59, 130, 246, 0.5),
-      inset 0 0 30px rgba(59, 130, 246, 0.3);
+      0 0 0 6px color-mix(in srgb, var(--onboarding-primary) 40%, transparent),
+      0 0 30px 12px color-mix(in srgb, var(--onboarding-primary) 50%, transparent),
+      inset 0 0 30px color-mix(in srgb, var(--onboarding-primary) 30%, transparent);
   }
 }
 
@@ -83,7 +79,9 @@
 .tour-popup {
   position: fixed;
   z-index: 10001;
-  background: white;
+  background: var(--onboarding-surface-elevated);
+  color: var(--onboarding-text);
+  border: 1px solid var(--onboarding-border);
   border-radius: 12px;
   box-shadow:
     0 20px 25px -5px rgba(0, 0, 0, 0.1),
@@ -110,7 +108,7 @@
   margin: 0 0 1rem;
   font-size: 1.25rem;
   font-weight: 600;
-  color: #111827;
+  color: var(--onboarding-text);
   line-height: 1.4;
 }
 
@@ -119,7 +117,7 @@
   margin: 0 0 1.5rem;
   font-size: 0.9375rem;
   line-height: 1.6;
-  color: #4b5563;
+  color: var(--onboarding-text-muted);
 }
 
 .tour-popup-body p {
@@ -142,12 +140,12 @@
 
 .tour-popup-body strong {
   font-weight: 600;
-  color: #111827;
+  color: var(--onboarding-text);
 }
 
 .tour-popup-body code {
   padding: 0.125rem 0.375rem;
-  background: #f3f4f6;
+  background: var(--onboarding-surface);
   border-radius: 0.25rem;
   font-family: 'Monaco', 'Menlo', 'Courier New', monospace;
   font-size: 0.875em;
@@ -157,14 +155,14 @@
 .tour-popup-progress {
   margin: 1.5rem 0 1rem;
   padding-top: 1rem;
-  border-top: 1px solid #e5e7eb;
+  border-top: 1px solid var(--onboarding-border);
 }
 
 /* Progress Bar */
 .tour-progress-bar {
   width: 100%;
   height: 6px;
-  background: #e5e7eb;
+  background: var(--onboarding-border);
   border-radius: 3px;
   overflow: hidden;
   margin-bottom: 0.5rem;
@@ -172,7 +170,7 @@
 
 .tour-progress-fill {
   height: 100%;
-  background: linear-gradient(90deg, #3b82f6, #2563eb);
+  background: linear-gradient(90deg, var(--onboarding-primary-fill), var(--onboarding-primary-fill-hover));
   border-radius: 3px;
   transition: width 0.3s ease;
 }
@@ -180,7 +178,7 @@
 /* Progress Text */
 .tour-progress-text {
   font-size: 0.8125rem;
-  color: #6b7280;
+  color: var(--onboarding-text-muted);
   text-align: center;
   font-weight: 500;
 }
@@ -217,7 +215,7 @@
 
 .tour-btn:focus {
   outline: none;
-  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.3);
+  box-shadow: var(--onboarding-focus-ring);
 }
 
 .tour-btn:active {
@@ -226,47 +224,47 @@
 
 /* Next Button - Primary */
 .tour-btn-next {
-  background: #3b82f6;
-  color: white;
+  background: var(--onboarding-primary-fill);
+  color: var(--onboarding-on-primary);
   padding: 0.625rem 1.25rem;
 }
 
 .tour-btn-next:hover {
-  background: #2563eb;
+  background: var(--onboarding-primary-fill-hover);
 }
 
 .tour-btn-next:active {
-  background: #1d4ed8;
+  background: var(--onboarding-primary-fill-hover);
 }
 
 /* Previous Button - Secondary */
 .tour-btn-prev {
-  background: #f3f4f6;
-  color: #374151;
+  background: var(--onboarding-surface);
+  color: var(--onboarding-text);
 }
 
 .tour-btn-prev:hover {
-  background: #e5e7eb;
+  background: var(--onboarding-border);
 }
 
 .tour-btn-prev:active {
-  background: #d1d5db;
+  background: var(--onboarding-border);
 }
 
 /* Skip Button - Ghost */
 .tour-btn-skip {
   background: transparent;
-  color: #6b7280;
+  color: var(--onboarding-text-muted);
   padding: 0.5rem 0.75rem;
 }
 
 .tour-btn-skip:hover {
-  color: #374151;
-  background: #f9fafb;
+  color: var(--onboarding-text);
+  background: var(--onboarding-surface);
 }
 
 .tour-btn-skip:active {
-  background: #f3f4f6;
+  background: var(--onboarding-border);
 }
 
 /* Mobile Responsive */
@@ -325,16 +323,20 @@
     background: rgba(0, 0, 0, 0.85);
   }
 
+  .tour-spotlight-spotlight {
+    --onboarding-tour-scrim: 0.85;
+  }
+
   .tour-spotlight-border {
     border-width: 4px;
   }
 
   .tour-btn-next {
-    background: #1d4ed8;
+    background: var(--onboarding-primary-fill-hover);
   }
 
   .tour-btn-prev {
-    border: 2px solid #374151;
+    border: 2px solid var(--onboarding-border);
   }
 }
 
@@ -349,10 +351,6 @@
     animation: none;
   }
 
-  .tour-spotlight-spotlight {
-    animation: none;
-  }
-
   .tour-spotlight-border {
     animation: none;
   }
@@ -362,63 +360,6 @@
   }
 }
 
-/* Dark Mode Support */
-@media (prefers-color-scheme: dark) {
-  .tour-popup {
-    background: #1f2937;
-    box-shadow:
-      0 20px 25px -5px rgba(0, 0, 0, 0.3),
-      0 10px 10px -5px rgba(0, 0, 0, 0.2);
-  }
-
-  .tour-popup-title {
-    color: #f9fafb;
-  }
-
-  .tour-popup-body {
-    color: #d1d5db;
-  }
-
-  .tour-popup-body strong {
-    color: #f3f4f6;
-  }
-
-  .tour-popup-body code {
-    background: #374151;
-    color: #e5e7eb;
-  }
-
-  .tour-popup-progress {
-    border-top-color: #374151;
-  }
-
-  .tour-progress-bar {
-    background: #374151;
-  }
-
-  .tour-progress-text {
-    color: #9ca3af;
-  }
-
-  .tour-btn-prev {
-    background: #374151;
-    color: #e5e7eb;
-  }
-
-  .tour-btn-prev:hover {
-    background: #4b5563;
-  }
-
-  .tour-btn-skip {
-    color: #9ca3af;
-  }
-
-  .tour-btn-skip:hover {
-    color: #d1d5db;
-    background: #374151;
-  }
-}
-
 /* Print Styles - Hide tour elements when printing */
 @media print {
   .tour-overlay,
@@ -434,13 +375,13 @@
 }
 
 .tour-btn:focus-visible {
-  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.3);
+  box-shadow: var(--onboarding-focus-ring);
 }
 
 /* Utility classes for custom tour content */
 .tour-highlight {
-  background: #dbeafe;
-  color: #1e40af;
+  background: color-mix(in srgb, var(--onboarding-primary-fill) 18%, transparent);
+  color: var(--onboarding-text);
   padding: 0.125rem 0.375rem;
   border-radius: 0.25rem;
   font-weight: 500;

data/lib/rails_onboarding/version.rb

@@ -1,3 +1,3 @@
 module RailsOnboarding
-  VERSION = "0.8.7"
+  VERSION = "0.8.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_onboarding
 version: !ruby/object:Gem::Version
-  version: 0.8.7
+  version: 0.8.9
 platform: ruby
 authors:
 - David Lewis
@@ -282,7 +282,7 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/bunnahabhain/rails_onboarding
-  source_code_uri: https://github.com/bunnahabhain/rails_onboarding/tree/v0.8.7
+  source_code_uri: https://github.com/bunnahabhain/rails_onboarding/tree/v0.8.9
   changelog_uri: https://github.com/bunnahabhain/rails_onboarding/blob/master/docs/CHANGELOG.md
 rdoc_options: []
 require_paths:
@@ -298,7 +298,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 4.0.19
 specification_version: 4
 summary: Flexible onboarding engine for Rails applications
 test_files: []