rails_onboarding 0.8.9 → 0.8.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5de350daba589470bba3cfa3afe9daa037307873d47a888f81899b2e542172fa
-  data.tar.gz: 6871219f6639948ec9e66747c2e89be3b58d2260d6ef8bc2750a84900db14b1d
+  metadata.gz: 8e42f9771d8f9d357ebbf763900651576721b726c548e6f837853d6590ff2da5
+  data.tar.gz: 5892846e24f4c86ab43217016e5713c8a80958e72aa861cdeed555d659e83179
 SHA512:
-  metadata.gz: 2b6e4ccc57e00c7d41e4b21604be312330888ac2cc96e6b8ef0bc39206c529416ddc35f5d4bdc998632a6488fca0ce2a1c53e900c50115a17b08c17c2f9193f3
-  data.tar.gz: a4714eaed7cca529878cc9cc99ed06e0e48fa117a1cfa7f327eed5e9de97abf98cf5c35cc4ef7b51e2c8449cca5e78bf64953f9d2a8b2114487b60a9a0dc27d5
+  metadata.gz: ed6b1a9c9a64766bca536370562c962e04dfafb0478283834e335e7a80e0e1e11e5bd7619e468597af0c2fe24d1fa84a2c2bfd2eaf52b57a546a209053bca307
+  data.tar.gz: 7dd60ecfec9f08115c6b25a40ed91c7c54790ca79e539085929891cb900895767bc4e17e2b64cfa50117132464dd655c709ae7bdc83fd05f1319142ca826acc7

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

@@ -28,6 +28,12 @@ export default class extends Controller {
         scrollBehavior: { type: String, default: "smooth" }, // smooth, auto, none
         scrollOffset: { type: Number, default: 80 }, // px offset from top when scrolling
         persistProgress: { type: Boolean, default: true },
+        // Whether the highlighted element stays clickable. It is lifted above the
+        // overlay so that a tour can say "click here to continue", and that is the
+        // default. An informational tour wants the opposite: a link inside the
+        // spotlight is a trap, because following it navigates away and the tour is
+        // either lost or restarted from step one. Overridable per step.
+        allowInteraction: { type: Boolean, default: true },
         tourId: String
     }
 
@@ -43,10 +49,33 @@ export default class extends Controller {
 
         // Auto-start if configured and not completed
         if (this.autoStartValue && !this.isTourCompleted()) {
-            setTimeout(() => this.start(), 1000)
+            this.autoStartTimer = setTimeout(() => this.autoStart(), 1000)
         }
     }
 
+    /**
+     * Begin an auto-started tour, if the page it was configured on is still the
+     * one on screen.
+     *
+     * Turbo renders a cached snapshot as a preview while the fresh response is
+     * still in flight, and every controller on the page connects to that preview
+     * as well as to the render that replaces it a few milliseconds later.
+     * Starting on the preview builds the whole tour, tears it down again when the
+     * preview is discarded, and rebuilds it - which a member sees as the popup
+     * appearing, vanishing and appearing again. The real render starts it
+     * properly, so the preview should simply stand aside.
+     *
+     * The element check covers the same ground from the other side: a controller
+     * whose element has left the document must not build an overlay and a popup,
+     * because it no longer has the handlers that would take them down again.
+     */
+    autoStart() {
+        if (!this.element.isConnected) return
+        if (document.documentElement.hasAttribute('data-turbo-preview')) return
+
+        this.start()
+    }
+
     /**
      * Parse and validate tour steps from configuration
      */
@@ -80,6 +109,7 @@ export default class extends Controller {
             beforeHide: step.beforeHide,
             onComplete: step.onComplete,
             width: step.width || 400, // Popup width in px
+            allowInteraction: step.allowInteraction ?? this.allowInteractionValue,
             ...step
         }))
     }
@@ -259,13 +289,25 @@ export default class extends Controller {
         }
     }
 
+    /**
+     * Elements the controller injects into document.body. Turbo caches the whole body
+     * when you navigate away, so without this a Back lands you on a snapshot with a
+     * frozen overlay and popup baked in - which then sit underneath the live tour the
+     * launcher starts, as duplicated and inert DOM. The attribute is ignored by hosts
+     * that do not use Turbo.
+     */
+    excludeFromSnapshot(element) {
+        element.setAttribute('data-turbo-cache', 'false')
+        return element
+    }
+
     /**
      * Create modal overlay
      */
     createOverlay() {
         if (this.overlay) return
 
-        this.overlay = document.createElement('div')
+        this.overlay = this.excludeFromSnapshot(document.createElement('div'))
         this.overlay.className = 'tour-overlay'
         this.overlay.style.cssText = `
             position: fixed;
@@ -322,7 +364,7 @@ export default class extends Controller {
 
         if (style === 'none') return
 
-        this.spotlight = document.createElement('div')
+        this.spotlight = this.excludeFromSnapshot(document.createElement('div'))
         this.spotlight.className = `tour-spotlight tour-spotlight-${style}`
 
         const baseStyles = `
@@ -381,8 +423,16 @@ export default class extends Controller {
         this.highlightedElement = element
         this.previousElementPosition = element.style.position
         this.previousElementZIndex = element.style.zIndex
+        this.previousElementPointerEvents = element.style.pointerEvents
         element.style.position = 'relative'
         element.style.zIndex = '10000'
+
+        // With interaction off, clicks fall through the highlighted element to the
+        // overlay beneath, which swallows them like the rest of the page. The element
+        // is still lifted above the overlay so it stays fully lit.
+        if (step.allowInteraction === false) {
+            element.style.pointerEvents = 'none'
+        }
     }
 
     /**
@@ -426,6 +476,7 @@ export default class extends Controller {
         if (this.highlightedElement) {
             this.highlightedElement.style.position = this.previousElementPosition || ''
             this.highlightedElement.style.zIndex = this.previousElementZIndex || ''
+            this.highlightedElement.style.pointerEvents = this.previousElementPointerEvents || ''
             this.highlightedElement = null
         }
     }
@@ -436,7 +487,7 @@ export default class extends Controller {
     createPopup(step, targetElement) {
         this.removePopup()
 
-        this.popup = document.createElement('div')
+        this.popup = this.excludeFromSnapshot(document.createElement('div'))
         this.popup.className = 'tour-popup'
 
         // Build popup HTML
@@ -843,6 +894,8 @@ export default class extends Controller {
     disconnect() {
         this.stop()
 
+        if (this.autoStartTimer) clearTimeout(this.autoStartTimer)
+
         if (this.keyboardHandler) {
             document.removeEventListener('keydown', this.keyboardHandler)
         }

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

@@ -71,6 +71,13 @@
   --onboarding-border: #e5e7eb;
   --onboarding-border-focus: var(--onboarding-primary);
 
+  /* The edge of a tour spotlight's cutout. Transparent here because a light page
+     needs none: the scrim darkens the surround and the cutout keeps the page's
+     own white, which is a step anyone can see. The dark block at the foot of
+     this file turns them on, where that step does not exist. */
+  --onboarding-tour-spotlight-ring: transparent;
+  --onboarding-tour-spotlight-glow: transparent;
+
   /* Spacing */
   --onboarding-space-xs: 0.25rem;
   --onboarding-space-sm: 0.5rem;
@@ -1143,6 +1150,15 @@
     --onboarding-text-muted: #d1d5db;
     --onboarding-text-light: #9ca3af;
     --onboarding-border: #374151;
+
+    /* Draw the spotlight's edge instead of relying on one. A black scrim over a
+       page that is already near-black moves the surround by a few points of
+       luminance, so the cutout has no visible boundary and the highlight reads
+       as nothing in particular - the tour points at the page and the page looks
+       the same. The brand colour is the foreground role here, hence
+       --onboarding-primary rather than the fill. */
+    --onboarding-tour-spotlight-ring: var(--onboarding-primary);
+    --onboarding-tour-spotlight-glow: color-mix(in srgb, var(--onboarding-primary) 35%, transparent);
   }
 
   .step-debug {

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

@@ -28,9 +28,21 @@
    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. */
+   property overrides the inline style, which is what made overlayOpacity a dead knob.
+
+   The ring and glow are listed first because a box-shadow list paints in reverse: the
+   first shadow lands on top, so both sit over the scrim rather than under it. Both
+   default to transparent, which is a light page's answer - there the scrim alone
+   separates the cutout, since the surround visibly darkens while the cutout keeps the
+   page's own white. A dark page has no such headroom - a black scrim over a near-black
+   background lands on a slightly nearer black, a difference nobody can see - so the
+   cutout has to be given an edge rather than a luminance step to be seen by.
+   application.css turns these on in its dark block. */
 .tour-spotlight-spotlight {
-  box-shadow: 0 0 0 9999px rgba(0, 0, 0, var(--onboarding-tour-scrim, 0.7));
+  box-shadow:
+    0 0 0 3px var(--onboarding-tour-spotlight-ring, transparent),
+    0 0 24px 8px var(--onboarding-tour-spotlight-glow, transparent),
+    0 0 0 9999px rgba(0, 0, 0, var(--onboarding-tour-scrim, 0.7));
 }
 
 /* Border highlight style */

data/lib/rails_onboarding/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_onboarding
 version: !ruby/object:Gem::Version
-  version: 0.8.9
+  version: 0.8.11
 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.9
+  source_code_uri: https://github.com/bunnahabhain/rails_onboarding/tree/v0.8.11
   changelog_uri: https://github.com/bunnahabhain/rails_onboarding/blob/master/docs/CHANGELOG.md
 rdoc_options: []
 require_paths: