rails_onboarding 0.8.10 → 0.8.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c05ac141e36d0ce4babc403026980c036569d9ae47a6dfe7fd945b9023bdce8b
-  data.tar.gz: a4a1482feee59b542485b5368e9cadbbe99dc16d3bcb9da6da399b7ca22c02c6
+  metadata.gz: 532f89d681d2a2bf5cdf575a99b26742497707b65c1109525f51307d09bc50c6
+  data.tar.gz: 6f5e6c0c374b350ac09ac25c36846ad93eee2c2e10d31a531629f65cb19062f7
 SHA512:
-  metadata.gz: abcfa7de7380a5a5591fbcad733a093c0eb11dfacf89e82fb20d25d7570c67e2f4d26040a7c871d1990d9de5283bfe45b42584241676a55173078f29b5ff8393
-  data.tar.gz: 95ed36308b6f64e56bb4b2cac753efec1f6359dde989b8ccd516f57f2a0e9106c4621e2e4ca0e59ec72b9eb0f6dfdc092da1dcd3a5e3b803dbc45a6f40821809
+  metadata.gz: 68277199c94e5109304653b498934f8971779b6fe58696133b992b365753527545b06982f013e75faa2fd34e4cb7f71f4730937c2c599da30efdbd0a218d7f7e
+  data.tar.gz: f2b95e0a399d1981f5f01783231179ea62d7398e8145f0aed809e0621f158c8949e1152c8305f9c5f05daf328350eddf4a293885f954dfa99400c5bf8dac491f

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

@@ -49,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
      */
@@ -193,8 +216,7 @@ export default class extends Controller {
             this.executeCallback(step.beforeShow, step)
         }
 
-        // Find target element
-        const targetElement = step.selector ? document.querySelector(step.selector) : null
+        const targetElement = this.resolveTarget(step)
 
         this.currentTargetElement = targetElement
         this.applyScrim(step, targetElement)
@@ -221,6 +243,37 @@ export default class extends Controller {
         this.dispatch('step-shown', { detail: { step, index } })
     }
 
+    /**
+     * Find the element a step should point at.
+     *
+     * `selector` may be a list, which is how a step survives a responsive layout:
+     * the same idea is often two elements, one of them display:none at the current
+     * breakpoint - a row of tabs on a wide screen and a select on a narrow one. The
+     * first candidate that is actually rendered wins.
+     *
+     * An element with no layout box is treated as absent rather than used anyway.
+     * getBoundingClientRect() on a display:none element is all zeroes, so the
+     * spotlight became a small square in the top-left corner and the popup was
+     * placed against the origin - pointing confidently at nothing, on top of
+     * whatever happened to be there.
+     */
+    resolveTarget(step) {
+        const selectors = Array.isArray(step.selector) ? step.selector : [step.selector]
+
+        for (const selector of selectors) {
+            if (!selector) continue
+
+            const element = document.querySelector(selector)
+            if (element && this.hasLayoutBox(element)) return element
+        }
+
+        return null
+    }
+
+    hasLayoutBox(element) {
+        return element.getClientRects().length > 0
+    }
+
     /**
      * Hide current step
      */
@@ -569,26 +622,26 @@ export default class extends Controller {
 
         const popupRect = this.popup.getBoundingClientRect()
         const margin = 20
-        let top, left
+        const targetRect = targetElement ? targetElement.getBoundingClientRect() : null
 
-        if (targetElement) {
-            const targetRect = targetElement.getBoundingClientRect()
-            const position = this.calculateBestPosition(step, targetRect, popupRect, margin)
-
-            top = position.top
-            left = position.left
-        } else {
-            // Center on screen if no target
-            top = (window.innerHeight - popupRect.height) / 2
-            left = (window.innerWidth - popupRect.width) / 2
-        }
+        const coords = targetRect
+            ? this.calculateBestPosition(step, targetRect, popupRect, margin)
+            : {
+                top: (window.innerHeight - popupRect.height) / 2,
+                left: (window.innerWidth - popupRect.width) / 2
+            }
 
-        // Ensure popup stays in viewport
-        top = Math.max(margin, Math.min(top, window.innerHeight - popupRect.height - margin))
-        left = Math.max(margin, Math.min(left, window.innerWidth - popupRect.width - margin))
+        // The clamp keeps the popup reachable, which matters more than anything else -
+        // its own buttons are the only way forward. calculateBestPosition is what keeps
+        // it off the highlight; this is the last word on staying on screen.
+        this.popup.style.top =
+            `${this.clamp(coords.top, margin, window.innerHeight - popupRect.height - margin)}px`
+        this.popup.style.left =
+            `${this.clamp(coords.left, margin, window.innerWidth - popupRect.width - margin)}px`
+    }
 
-        this.popup.style.top = `${top}px`
-        this.popup.style.left = `${left}px`
+    clamp(value, min, max) {
+        return Math.max(min, Math.min(value, max))
     }
 
     /**
@@ -618,22 +671,40 @@ export default class extends Controller {
             }
         }
 
-        // If position is auto, find best fit
-        if (step.position === 'auto') {
-            const preferences = ['bottom', 'top', 'right', 'left']
+        // 'center' is a host saying "do not point at anything", so it is taken at its
+        // word. Every other position is a *preference*: it used to be handed back
+        // without being checked, and positionPopup then clamped it into the viewport -
+        // which on a phone slides the popup straight over the element it is describing.
+        // A tour that hides what it is explaining is worse than one placed on the wrong
+        // side, so the asked-for side is tried first and the others are tried after it.
+        if (step.position === 'center') return positions.center
 
-            for (const pos of preferences) {
-                const coords = positions[pos]
-                if (this.isPositionValid(coords, popupRect, margin)) {
-                    return coords
-                }
-            }
+        const fallbacks = ['bottom', 'top', 'right', 'left']
+        const order = positions[step.position] && step.position !== 'auto'
+            ? [step.position, ...fallbacks.filter((pos) => pos !== step.position)]
+            : fallbacks
 
-            // Fallback to center
-            return positions.center
+        for (const pos of order) {
+            if (this.isPositionValid(positions[pos], popupRect, margin)) return positions[pos]
         }
 
-        return positions[step.position] || positions.bottom
+        return this.positionBesideTarget(targetRect, popupRect, margin)
+    }
+
+    /**
+     * Nothing fits cleanly on any side, which on a small viewport is the ordinary
+     * case rather than the exceptional one. Put the popup in whichever band - above
+     * the target or below it - has more room. Centring instead, which is what this
+     * used to do, lands on the target more often than not.
+     */
+    positionBesideTarget(targetRect, popupRect, margin) {
+        const roomAbove = targetRect.top - margin
+        const roomBelow = window.innerHeight - targetRect.bottom - margin
+        const left = targetRect.left + (targetRect.width - popupRect.width) / 2
+
+        return roomBelow >= roomAbove
+            ? { top: targetRect.bottom + margin, left }
+            : { top: targetRect.top - popupRect.height - margin, left }
     }
 
     /**
@@ -871,6 +942,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.10"
+  VERSION = "0.8.12"
 end

metadata

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