rails_onboarding 0.8.6 → 0.8.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eb640c48091d5cc3028c5563bbdd22d3b5a2b2a32e3ce6079f20afb99b14cec
-  data.tar.gz: b85af1963ce35f84da739613dc6168179ea0e548bc90d11a91e7a01be2c5c484
+  metadata.gz: 408fd1e294065de10f66f097028bca6ea0ef929c2da585fb5fe20034a14e0202
+  data.tar.gz: 2e015226988b1bda4bf5594d43c00341f4a9fb2c21c020b0607446be87dfe671
 SHA512:
-  metadata.gz: 1f76a6f1b8d8ec877f5efe98026c2f75039d6a6102bc3eda76cbdbabb36d9926b9b2fe3f88044e0a515fcb76053eb087d7929b7fa62799acdd5ab2abafacb476
-  data.tar.gz: b58edc5a568ad4691982422fe8a21c557d074fed14c91990fbda23ef2e8cdd9584eee8b54241ac5996f97578eeffdbdcd6250c5812d8880e2753ed644893fab8
+  metadata.gz: 6f924adbe61c18fc3b8070653655b04d74bd01a97562ed5eaa274d43276c07a331a11ef233ceab5484f545b20779485cbe55417921516bc9c2cd0557da694884
+  data.tar.gz: 678c83c71d204f027f92d65555af8cff1b3aecd53992cda79e5d234f5deffaf3a465e4b786295bc5ca2319b97a74946750e3a98083a45b8f1ad5ea4a37f3d4c1

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,8 @@ export default class extends Controller {
         // Find target element
         const targetElement = step.selector ? document.querySelector(step.selector) : null
 
+        this.currentTargetElement = targetElement
+
         if (targetElement) {
             this.scrollToElement(targetElement, step)
             this.createHighlight(targetElement, step)
@@ -277,8 +280,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 +297,14 @@ 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'
+        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)
     }
 
@@ -372,7 +375,11 @@ 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'
     }
@@ -388,10 +395,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 +436,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 +463,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 +597,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 +653,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 +821,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/milestones.css

@@ -19,12 +19,46 @@
   font-size: 2.5rem;
   font-weight: 700;
   color: #2c3e50;
-  margin: 0;
+  margin: 0 1rem;
+}
+
+.milestone-header-actions {
+  display: flex;
+  align-items: center;
+  gap: 1.5rem;
 }
 
 .milestone-stats {
   display: flex;
-  gap: 2rem;
+  gap: 1rem;
+}
+
+.milestone-home-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem 1.25rem;
+  border: 2px solid #e5e7eb;
+  border-radius: 12px;
+  background: white;
+  color: #2c3e50;
+  font-size: 0.9375rem;
+  font-weight: 600;
+  text-decoration: none;
+  white-space: nowrap;
+  transition: border-color 0.2s ease, color 0.2s ease, transform 0.2s ease;
+}
+
+.milestone-home-link:hover,
+.milestone-home-link:focus-visible {
+  border-color: #667eea;
+  color: #667eea;
+  transform: translateY(-1px);
+}
+
+.milestone-home-icon {
+  font-size: 1.125rem;
+  line-height: 1;
 }
 
 .total-points,
@@ -490,6 +524,11 @@
     text-align: center;
   }
   
+  .milestone-header-actions {
+    flex-direction: column;
+    gap: 1rem;
+  }
+
   .milestone-stats {
     justify-content: center;
   }

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

@@ -39,43 +39,43 @@
 
 /* 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 +83,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 +112,7 @@
   margin: 0 0 1rem;
   font-size: 1.25rem;
   font-weight: 600;
-  color: #111827;
+  color: var(--onboarding-text);
   line-height: 1.4;
 }
 
@@ -119,7 +121,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 +144,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 +159,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 +174,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 +182,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 +219,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 +228,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 */
@@ -330,11 +332,11 @@
   }
 
   .tour-btn-next {
-    background: #1d4ed8;
+    background: var(--onboarding-primary-fill-hover);
   }
 
   .tour-btn-prev {
-    border: 2px solid #374151;
+    border: 2px solid var(--onboarding-border);
   }
 }
 
@@ -362,63 +364,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 +379,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/app/views/rails_onboarding/milestones/index.html.erb

@@ -6,15 +6,27 @@
      data-milestone-dashboard-milestones-path-value="<%= milestones_path %>">
   <div class="milestone-header">
     <h1 class="milestone-title">🏆 Your Achievements</h1>
-    <div class="milestone-stats">
-      <div class="total-points">
-        <span class="points-value" data-milestone-dashboard-target="pointsValue"><%= @total_points %></span>
-        <span class="points-label">Total Points</span>
-      </div>
-      <div class="achievement-count">
-        <span class="count-value" data-milestone-dashboard-target="countValue"><%= @achieved_milestones.length %></span>
-        <span class="count-label">Milestones</span>
+    <div class="milestone-header-actions">
+      <div class="milestone-stats">
+        <div class="total-points">
+          <span class="points-value" data-milestone-dashboard-target="pointsValue"><%= @total_points %></span>
+          <span class="points-label">Total Points</span>
+        </div>
+        <div class="achievement-count">
+          <span class="count-value" data-milestone-dashboard-target="countValue"><%= @achieved_milestones.length %></span>
+          <span class="count-label">Milestones</span>
+        </div>
       </div>
+
+      <%# Leaves the engine for the host app's root. Guarded because a host app
+          is not required to define a root route, and a missing one here would
+          break the whole page - same reasoning as the admin layout's Home link. %>
+      <% if main_app.respond_to?(:root_path) %>
+        <%= link_to main_app.root_path, class: "milestone-home-link" do %>
+          <span class="milestone-home-icon" aria-hidden="true">🏠</span>
+          Home
+        <% end %>
+      <% end %>
     </div>
   </div>
 

data/lib/rails_onboarding/version.rb

@@ -1,3 +1,3 @@
 module RailsOnboarding
-  VERSION = "0.8.6"
+  VERSION = "0.8.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_onboarding
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.8.8
 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.6
+  source_code_uri: https://github.com/bunnahabhain/rails_onboarding/tree/v0.8.8
   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: []