rails_onboarding 0.8.11 → 0.8.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e42f9771d8f9d357ebbf763900651576721b726c548e6f837853d6590ff2da5
-  data.tar.gz: 5892846e24f4c86ab43217016e5713c8a80958e72aa861cdeed555d659e83179
+  metadata.gz: 593e5e47988a8b3f81d6ea034f186669a099d98b09707723ed723128bcdad01d
+  data.tar.gz: 790f85934b3f9573cc6421488b882fcf3ac80340e27a0b6b587cc2de93bcdcab
 SHA512:
-  metadata.gz: ed6b1a9c9a64766bca536370562c962e04dfafb0478283834e335e7a80e0e1e11e5bd7619e468597af0c2fe24d1fa84a2c2bfd2eaf52b57a546a209053bca307
-  data.tar.gz: 7dd60ecfec9f08115c6b25a40ed91c7c54790ca79e539085929891cb900895767bc4e17e2b64cfa50117132464dd655c709ae7bdc83fd05f1319142ca826acc7
+  metadata.gz: f9bc4b4bd26ace6d84e153b906a0b687035e6d0ccb1b81d13ed15f6219bcc1e7be6c02ae30aa85658fc3c79933c5a7c374243bdffc9bf0197b923172ce1c2a36
+  data.tar.gz: 1d1bed61cc8462db8e23fe1e92a114d7df9be93cc7254e6f0cecfe8d56a8fcae765ffe072769c768044f5315795510c0c9533339f9835ac57fc48213a6f83e77

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

@@ -216,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)
@@ -244,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
      */
@@ -592,26 +622,26 @@ export default class extends Controller {
 
         const popupRect = this.popup.getBoundingClientRect()
         const margin = 20
-        let top, left
-
-        if (targetElement) {
-            const targetRect = targetElement.getBoundingClientRect()
-            const position = this.calculateBestPosition(step, targetRect, popupRect, margin)
+        const targetRect = targetElement ? targetElement.getBoundingClientRect() : null
 
-            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))
     }
 
     /**
@@ -641,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 }
     }
 
     /**

data/app/models/concerns/rails_onboarding/onboardable.rb

@@ -7,6 +7,45 @@ module RailsOnboarding
     MAX_MILESTONES_ACHIEVED = 500
     MAX_JSON_SIZE_BYTES = 65_535 # ~64KB for TEXT columns
 
+    # Whether the host model's table can be inspected right now.
+    #
+    # `columns_hash` and `column_names` both query the database, and the
+    # `included do` block below runs the moment the host model is loaded --
+    # which can be long before that table exists. A host that references its
+    # user model from an initializer hits this immediately: the common OmniAuth
+    # `:identity` setup passes `model: User`, so the model loads during boot,
+    # the include queries `columns_hash`, and against an empty database the
+    # whole process dies with "Table 'users' doesn't exist".
+    #
+    # That is circular and unrecoverable: loading the schema requires booting
+    # the app, and booting the app requires the schema. It stops `db:prepare`
+    # bootstrapping a genuinely new database, a restore into an empty schema,
+    # and CI against a fresh database service.
+    #
+    # A missing table, a missing database and an absent connection all mean the
+    # same thing here -- the column types cannot be known yet -- so degrade
+    # instead of raising. Nothing is lost: a process that boots against an empty
+    # database is bootstrapping it, not serving from it, and the next process
+    # configures everything normally once the schema is in place.
+    #
+    # Only ever answers false when the table is positively known to be absent.
+    # This concern is deliberately includable into plain classes that are not
+    # ActiveRecord models -- hence the `respond_to?(:has_many)` and
+    # `respond_to?(:validate)` guards below -- and such a class has no
+    # `table_exists?` while still answering `columns_hash`. Saying "not
+    # available" for those would silently stop configuring them, so anything
+    # that cannot be asked is treated as queryable and left to the callers'
+    # own guards, exactly as before this check existed.
+    def self.columns_queryable?(model)
+      return true unless model.respond_to?(:table_exists?)
+
+      model.table_exists?
+    rescue ActiveRecord::NoDatabaseError,
+           ActiveRecord::ConnectionNotEstablished,
+           ActiveRecord::StatementInvalid
+      false
+    end
+
     included do
       # Add fields via migration or expect them in the host model
       # The host app should have these columns:
@@ -21,17 +60,21 @@ module RailsOnboarding
       # - onboarding_replay_started_at: datetime
       # - onboarding_replay_steps: text (serialized JSON array)
 
-      # Fix for Rails 8: Use the new serialize syntax
-      if columns_hash["feature_tooltips_shown"]&.type == :text
-        serialize :feature_tooltips_shown, coder: JSON
-      end
+      # Fix for Rails 8: Use the new serialize syntax.
+      # Guarded because columns_hash queries the database -- see
+      # Onboardable.columns_queryable? above.
+      if RailsOnboarding::Onboardable.columns_queryable?(self)
+        if columns_hash["feature_tooltips_shown"]&.type == :text
+          serialize :feature_tooltips_shown, coder: JSON
+        end
 
-      if columns_hash["milestones_achieved"]&.type == :text
-        serialize :milestones_achieved, coder: JSON
-      end
+        if columns_hash["milestones_achieved"]&.type == :text
+          serialize :milestones_achieved, coder: JSON
+        end
 
-      if columns_hash["onboarding_replay_steps"]&.type == :text
-        serialize :onboarding_replay_steps, coder: JSON
+        if columns_hash["onboarding_replay_steps"]&.type == :text
+          serialize :onboarding_replay_steps, coder: JSON
+        end
       end
 
       # Association with analytics events (only if ActiveRecord is available)
@@ -56,6 +99,7 @@ module RailsOnboarding
       # than raising on a column that isn't there.
       def onboarding_replay_supported?
         return false unless respond_to?(:column_names)
+        return false unless RailsOnboarding::Onboardable.columns_queryable?(self)
 
         column_names.include?("onboarding_replay_started_at") &&
           column_names.include?("onboarding_replay_steps")

data/lib/rails_onboarding/version.rb

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

metadata

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