rails_onboarding 0.6.3 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54c87e18cdea35b440ea3d1f9dcd93984da008e6690bbf0dba255e8b1b803266
-  data.tar.gz: 6675e0f3bf44029a6ee5d2b6c6d051edf877dd388e087b44925a716f51070a1b
+  metadata.gz: 1ac648ef8f4bb783aa4c15e67e84fbeb68748f67f1565b9c6aaae498b21be94c
+  data.tar.gz: 827307fd65da0a3caf06805f2bd0024ad667e0730de7bdd22812b832ce86c9c4
 SHA512:
-  metadata.gz: fd7a88c2058c5ea08bc5636990af96fd58775bfa98bf8f5a93849793564afe09bb51dcdf4983641dab499cd850213e6b24c2c867c44137b4ae30b7cc469697b0
-  data.tar.gz: 75827eaa49ba15a510ae5212be0ba4f6ea67739b32e1da632c9e9fd36eaa452a721d635f839e01f77922755ed15742e9d31f91618dcca0485f4c012b4e6088d3
+  metadata.gz: 95e7d0b6d87d82b2cabdc1bed8ef7dbc33985bb35746f56b980e641ee6067fdc18082ce206f65e9506c614094bf4f374ed0ef999383025ee217d45356e206e36
+  data.tar.gz: cad8d3c274a9ec9db074edc1df5c60d0da753398af937c0f5fb50d3fd89ab9241e6e590dc86aa761c22597892ae585be7f6a2624f2a504c8a31df57447ab1e99

data/README.md

@@ -537,7 +537,11 @@ current_user.complete_onboarding!
 # Skip onboarding
 current_user.skip_onboarding!
 
-# Restart onboarding
+# Reset onboarding state (clears milestones too; pass clear_milestones: false to keep them)
+current_user.reset_onboarding!
+
+# Restart onboarding - resets and walks the user through the steps again, even
+# if their data already satisfies every :complete_if
 current_user.restart_onboarding!
 ```
 
@@ -1016,7 +1020,9 @@ RailsOnboarding::Templates.apply('saas')
 - `go_back!` - Move to previous step
 - `complete_onboarding!` - Mark onboarding as complete
 - `skip_onboarding!` - Skip onboarding
-- `restart_onboarding!` - Restart from beginning
+- `reset_onboarding!(clear_milestones: true)` - Clear onboarding state
+- `restart_onboarding!` - Reset and re-walk the flow (replay mode)
+- `replaying_onboarding?` - Is the user re-walking the flow?
 
 #### Progress Methods
 - `onboarding_progress` - Returns completion percentage (0-100)

data/app/controllers/rails_onboarding/admin/users_controller.rb

@@ -61,7 +61,19 @@ module RailsOnboarding
         @user = user_class.find(params[:id])
 
         @user.restart_onboarding!
-        flash[:notice] = "Onboarding restarted for user #{@user.id}"
+
+        # Without the replay columns a restart can't stop :complete_if from
+        # auto-advancing an established user straight back to "completed",
+        # which looks like the button did nothing. Say so rather than claiming
+        # a restart that won't survive their next page load.
+        flash[:notice] = if !user_class.respond_to?(:onboarding_replay_supported?) ||
+                            user_class.onboarding_replay_supported?
+          "Onboarding restarted for user #{@user.id}"
+        else
+          "Onboarding restarted for user #{@user.id}. Steps whose completion criteria " \
+            "are already met will be skipped - run the add_onboarding_replay_to_users " \
+            "migration to walk this user through them again."
+        end
         redirect_to admin_user_path(@user)
       rescue StandardError => e
         flash[:alert] = "Error restarting onboarding: #{e.message}"

data/app/controllers/rails_onboarding/onboarding_controller.rb

@@ -55,6 +55,12 @@ module RailsOnboarding
         )
       end
 
+      # Record that the user has now been shown this step. That's what lets
+      # :complete_if advance them past it when they come back, and it is what
+      # makes a restart re-walk a flow the user's data already satisfies.
+      # No-op outside a replay.
+      mark_step_replayed(@current_step)
+
       # Steps that own a real page in the host app: route there instead of
       # rendering a gem template, so the existing controller/view do the work.
       if @current_step[:path]
@@ -232,6 +238,10 @@ module RailsOnboarding
       awarded_milestones = []
       RailsOnboarding.configuration.total_steps.times do
         break unless @current_step && onboarding_step_criteria_met?(@current_step)
+        # During a replay, a satisfied :complete_if is not enough on its own -
+        # the user has to have been shown the step again first, or a restart
+        # would auto-advance them straight back to "completed".
+        break unless step_replayed?(@current_step)
 
         if defined?(RailsOnboarding::MilestoneService)
           milestones = RailsOnboarding::MilestoneService.check_onboarding_step_milestones(
@@ -258,6 +268,21 @@ module RailsOnboarding
       set_step
     end
 
+    # Replay bookkeeping. Both tolerate a host User that predates replay
+    # support (or isn't Onboardable at all), falling back to the ordinary
+    # auto-advance behaviour.
+    def step_replayed?(step)
+      return true unless current_user.respond_to?(:onboarding_step_replayed?)
+
+      current_user.onboarding_step_replayed?(step[:name])
+    end
+
+    def mark_step_replayed(step)
+      return unless current_user.respond_to?(:mark_onboarding_step_replayed!)
+
+      current_user.mark_onboarding_step_replayed!(step[:name])
+    end
+
     # Redirect to the host-app page that owns the current step. Returns false
     # (without redirecting) when the configured path can't be resolved, so
     # show can fall back to rendering a gem template instead of stranding the

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

@@ -18,6 +18,8 @@ module RailsOnboarding
       # - milestones_achieved: text (serialized JSON array)
       # - milestone_points: integer
       # - last_milestone_at: datetime
+      # - 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
@@ -28,6 +30,10 @@ module RailsOnboarding
         serialize :milestones_achieved, coder: JSON
       end
 
+      if columns_hash["onboarding_replay_steps"]&.type == :text
+        serialize :onboarding_replay_steps, coder: JSON
+      end
+
       # Association with analytics events (only if ActiveRecord is available)
       if respond_to?(:has_many)
         has_many :analytics_events,
@@ -43,6 +49,19 @@ module RailsOnboarding
       end
     end
 
+    class_methods do
+      # Replay mode needs two columns that predate no host app: installs from
+      # before it existed simply don't have them. Everything replay-related
+      # degrades to the old auto-advance behaviour when they're missing rather
+      # than raising on a column that isn't there.
+      def onboarding_replay_supported?
+        return false unless respond_to?(:column_names)
+
+        column_names.include?("onboarding_replay_started_at") &&
+          column_names.include?("onboarding_replay_steps")
+      end
+    end
+
     # Determines if the user needs to go through onboarding
     #
     # This method checks the configuration setting and user state to determine
@@ -163,9 +182,11 @@ module RailsOnboarding
 
     def complete_onboarding!(session_id: nil, completion_time: nil)
       persist_and_track!(
-        onboarding_completed: true,
-        onboarding_completed_at: Time.current,
-        onboarding_current_step: nil
+        {
+          onboarding_completed: true,
+          onboarding_completed_at: Time.current,
+          onboarding_current_step: nil
+        }.merge(replay_reset_attributes)
       ) do
         AnalyticsEvent.track_onboarding_completed(
           user: self,
@@ -179,10 +200,12 @@ module RailsOnboarding
 
     def skip_onboarding!(session_id: nil)
       persist_and_track!(
-        onboarding_completed: true,
-        onboarding_completed_at: Time.current,
-        onboarding_skipped: true,
-        onboarding_current_step: nil
+        {
+          onboarding_completed: true,
+          onboarding_completed_at: Time.current,
+          onboarding_skipped: true,
+          onboarding_current_step: nil
+        }.merge(replay_reset_attributes)
       ) do
         AnalyticsEvent.track_onboarding_completed(
           user: self,
@@ -193,14 +216,35 @@ module RailsOnboarding
       end
     end
 
-    def reset_onboarding!
-      update!(
+    # Clear onboarding state so the user starts over.
+    #
+    # Milestones are cleared by default. achieve_milestone! is idempotent
+    # (it returns false for anything already in milestones_achieved), so
+    # leaving them behind means a user sent back through the flow can never
+    # re-earn them and finishes with no milestone notice at all. Pass
+    # clear_milestones: false to keep them - worth doing where a host app's
+    # milestones record real achievements rather than onboarding progress.
+    #
+    # Any in-flight replay is cancelled: a bare reset drops the user back to
+    # the default behaviour, where a step whose :complete_if already passes is
+    # advanced past automatically. Use restart_onboarding! to reset *and*
+    # replay.
+    #
+    # @param clear_milestones [Boolean] also wipe milestones, points and
+    #   last_milestone_at (default: true)
+    # @return [Boolean] true
+    def reset_onboarding!(clear_milestones: true)
+      attributes = {
         onboarding_completed: false,
         onboarding_completed_at: nil,
         onboarding_skipped: false,
         onboarding_current_step: nil,
         feature_tooltips_shown: {}
-      )
+      }
+      attributes.merge!(milestone_reset_attributes) if clear_milestones
+      attributes.merge!(replay_reset_attributes)
+
+      update!(attributes)
     end
 
     # Feature tooltips
@@ -432,11 +476,18 @@ module RailsOnboarding
       true
     end
 
-    def restart_onboarding!(session_id: nil)
+    # Reset and immediately re-enter the flow at step one.
+    #
+    # Unlike a bare reset this turns replay mode on, so a user whose host-app
+    # data already satisfies every :complete_if walks the steps again instead
+    # of being auto-advanced straight back to "completed" on their next visit
+    # to /onboarding. See replaying_onboarding?.
+    def restart_onboarding!(session_id: nil, clear_milestones: true)
       previous_step = onboarding_current_step
       was_completed = onboarding_completed
 
-      reset_onboarding!
+      reset_onboarding!(clear_milestones: clear_milestones)
+      start_onboarding_replay!
       start_onboarding!(session_id: session_id)
 
       AnalyticsEvent.track_custom_event(
@@ -447,6 +498,63 @@ module RailsOnboarding
       )
     end
 
+    # Replay mode
+    #
+    # A reset clears onboarding's own bookkeeping, but it cannot clear the
+    # host-app data a step's :complete_if reads. For an established user every
+    # predicate is still satisfied, so /onboarding advances through the whole
+    # flow in a single redirect and the reset looks like it did nothing.
+    #
+    # While a replay is active, :complete_if is no longer enough on its own -
+    # the user also has to have been shown the step again. That makes a
+    # restart walk the real pages a second time without touching the data
+    # those predicates read.
+
+    # Is this user currently re-walking the flow?
+    #
+    # False once they finish, so a completed user is never stuck in replay.
+    def replaying_onboarding?
+      return false unless self.class.onboarding_replay_supported?
+      return false if onboarding_completed?
+
+      onboarding_replay_started_at.present?
+    end
+
+    # @return [Boolean] false when the host app hasn't run the replay migration
+    def start_onboarding_replay!
+      return false unless self.class.onboarding_replay_supported?
+
+      update!(onboarding_replay_started_at: Time.current, onboarding_replay_steps: [])
+      true
+    end
+
+    def end_onboarding_replay!
+      return false unless self.class.onboarding_replay_supported?
+
+      update!(replay_reset_attributes)
+      true
+    end
+
+    # Has the user been shown this step since the current replay began?
+    #
+    # True whenever no replay is active, so callers can gate auto-advance on
+    # it unconditionally and get the ordinary behaviour outside a replay.
+    def onboarding_step_replayed?(step_name)
+      return true unless replaying_onboarding?
+
+      (onboarding_replay_steps || []).map(&:to_s).include?(step_name.to_s)
+    end
+
+    # Record that the user has now seen this step. No-op outside a replay.
+    def mark_onboarding_step_replayed!(step_name)
+      return false unless replaying_onboarding?
+      return false if onboarding_step_replayed?(step_name)
+
+      self.onboarding_replay_steps = (onboarding_replay_steps || []) + [ step_name.to_s ]
+      save!
+      true
+    end
+
     # API-friendly aliases and helper methods
     alias_method :complete_step, :complete_onboarding_step!
     alias_method :skip_step, :skip_onboarding_step!
@@ -552,6 +660,26 @@ module RailsOnboarding
     # triggers) must never fire for a state change that didn't actually get
     # persisted - update!/save! raise on failure, so if that happens, this
     # method never reaches the block.
+    # Milestone columns arrive in a separate migration, so a host app can be
+    # running without them. Only reset what actually exists.
+    def milestone_reset_attributes
+      attributes = {}
+      attributes[:milestones_achieved] = [] if onboarding_column?("milestones_achieved")
+      attributes[:milestone_points] = 0 if onboarding_column?("milestone_points")
+      attributes[:last_milestone_at] = nil if onboarding_column?("last_milestone_at")
+      attributes
+    end
+
+    def replay_reset_attributes
+      return {} unless self.class.onboarding_replay_supported?
+
+      { onboarding_replay_started_at: nil, onboarding_replay_steps: [] }
+    end
+
+    def onboarding_column?(name)
+      self.class.respond_to?(:column_names) && self.class.column_names.include?(name)
+    end
+
     def persist_and_track!(attributes = nil)
       if attributes
         update!(attributes)

data/app/views/layouts/rails_onboarding/application.html.erb

@@ -31,6 +31,22 @@
     <%= stylesheet_link_tag "application", "data-turbo-track": "reload", media: "screen" %>
   <% end %>
 
+  <%# Host-supplied overrides, loaded last - after both the engine's own
+      stylesheets and the host's application bundle - so retheming doesn't
+      turn into a specificity fight. The install generator writes a starter
+      file to app/assets/stylesheets/rails_onboarding_custom.css, but nothing
+      loads it until custom_css_path names it (nil by default). Prefer
+      redefining the --onboarding-* design tokens there over overriding
+      individual rules: the tokens are read by every rule in the engine, so
+      one declaration recolours the whole flow.
+
+      Steps declared with `path:` render inside the *host's* layout, not this
+      one, so a host using those has to add the same tag to those layouts for
+      the theme to carry across the whole flow. %>
+  <% if RailsOnboarding.configuration.custom_css_path.present? %>
+    <%= stylesheet_link_tag RailsOnboarding.configuration.custom_css_path, media: "screen" %>
+  <% end %>
+
   <%= javascript_include_tag "rails_onboarding/application", "data-turbo-track": "reload", defer: true %>
 </head>
 <body>

data/lib/generators/rails_onboarding/install_generator.rb

@@ -60,6 +60,11 @@ module RailsOnboarding
                            "db/migrate/add_robustness_fields_to_users.rb"
       end
 
+      def copy_onboarding_replay_migration
+        migration_template "add_onboarding_replay_to_users.rb",
+                           "db/migrate/add_onboarding_replay_to_users.rb"
+      end
+
       def copy_initializer
         template "rails_onboarding.rb", "config/initializers/rails_onboarding.rb"
       end
@@ -87,6 +92,7 @@ module RailsOnboarding
           "add_milestone_tracking_to_users.rb",
           "add_onboarding_indexes.rb",
           "add_robustness_fields_to_users.rb.tt",
+          "add_onboarding_replay_to_users.rb",
           "rails_onboarding.rb",
           "onboarding.css",
           "README"

data/lib/generators/rails_onboarding/templates/add_onboarding_replay_to_users.rb

@@ -0,0 +1,22 @@
+class AddOnboardingReplayToUsers < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    # Replay mode: when set, the user is walking the flow again after a
+    # restart, and a step's :complete_if is not allowed to advance them past a
+    # step they have not been shown yet. See Onboardable#replaying_onboarding?.
+    #
+    # No DB-level default on the text column: MySQL/MariaDB reject a literal
+    # DEFAULT on TEXT, and Onboardable already treats nil as an empty array.
+    unless column_exists?(:users, :onboarding_replay_started_at)
+      add_column :users, :onboarding_replay_started_at, :datetime
+    end
+
+    unless column_exists?(:users, :onboarding_replay_steps)
+      add_column :users, :onboarding_replay_steps, :text
+    end
+  end
+
+  def down
+    remove_column :users, :onboarding_replay_steps if column_exists?(:users, :onboarding_replay_steps)
+    remove_column :users, :onboarding_replay_started_at if column_exists?(:users, :onboarding_replay_started_at)
+  end
+end

data/lib/generators/rails_onboarding/templates/onboarding.css

@@ -1,18 +1,34 @@
-/* Custom onboarding styles for your application */
 /*
- * This file is for customizing the onboarding appearance
- * to match your application's design system.
+ * Custom onboarding styles for your application.
+ *
+ * This file does nothing until you point the initializer at it:
+ *
+ *   config.custom_css_path = "rails_onboarding_custom"
+ *
+ * It is then loaded last on onboarding pages - after the engine's own
+ * stylesheets and after your application bundle - so these rules win without
+ * needing extra specificity.
+ *
+ * Prefer redefining the design tokens below over overriding individual rules.
+ * Every rule in the engine reads them, so one declaration recolours the whole
+ * flow and keeps working across gem upgrades. The full list is at the top of
+ * app/assets/stylesheets/rails_onboarding/application.css.
  */
 
-/* Example customizations: */
-.onboarding-container {
-  /* Override default styles here */
-}
+:root {
+  /* Brand */
+  /* --onboarding-primary:       #6366f1; */
+  /* --onboarding-primary-hover: #4f46e5; */
 
-.onboarding-progress {
-  /* Customize progress bar appearance */
-}
+  /* Surfaces */
+  /* --onboarding-background:       #ffffff; */
+  /* --onboarding-surface:          #f8fafc; */
+  /* --onboarding-surface-elevated: #ffffff; */
+
+  /* Text */
+  /* --onboarding-text:       #1f2937; */
+  /* --onboarding-text-muted: #6b7280; */
 
-.onboarding-step {
-  /* Customize step appearance */
+  /* Borders */
+  /* --onboarding-border: #e5e7eb; */
 }

data/lib/generators/rails_onboarding/templates/rails_onboarding.rb

@@ -14,6 +14,13 @@ RailsOnboarding.configure do |config|
   config.redirect_after_completion = :root_path
   config.redirect_after_skip = :root_path
 
+  # Asset name of a stylesheet loaded last on onboarding pages, for matching
+  # the flow to your own design. This generator wrote a starter file to
+  # app/assets/stylesheets/rails_onboarding_custom.css - nothing loads it
+  # until you uncomment the line below. Retheme by redefining the
+  # --onboarding-* tokens in that file rather than overriding rules.
+  # config.custom_css_path = "rails_onboarding_custom"
+
   # Feature toggles
   config.enable_tooltips = true
   config.enable_milestones = true

data/lib/rails_onboarding/configuration.rb

@@ -47,6 +47,12 @@ module RailsOnboarding
     def initialize
       @user_class_name = "User"
       @include_host_styles = true  # Default to including host app css
+
+      # Asset name of a host stylesheet to load after everything else on
+      # onboarding pages, for retheming the flow. The install generator writes
+      # app/assets/stylesheets/rails_onboarding_custom.css; set this to
+      # "rails_onboarding_custom" to actually load it. nil = load nothing.
+      @custom_css_path = nil
       @redirect_after_completion = :root_path
       @redirect_after_skip = :root_path
       @welcome_heading = "We're excited to have you here!"

data/lib/rails_onboarding/configuration_validator.rb

@@ -54,6 +54,7 @@ module RailsOnboarding
     def validate_types
       validate_type(:user_class_name, [ String ], "user_class_name must be a String")
       validate_type(:include_host_styles, [ TrueClass, FalseClass ], "include_host_styles must be a Boolean")
+      validate_type(:custom_css_path, [ String ], "custom_css_path must be a String")
       validate_type(:enable_tooltips, [ TrueClass, FalseClass ], "enable_tooltips must be a Boolean")
       validate_type(:enable_milestones, [ TrueClass, FalseClass ], "enable_milestones must be a Boolean")
       validate_type(:enable_analytics, [ TrueClass, FalseClass ], "enable_analytics must be a Boolean")

data/lib/rails_onboarding/requirements_validator.rb

@@ -167,7 +167,9 @@ module RailsOnboarding
             "feature_tooltips_shown" => [ :jsonb, :text ],
             "milestones_achieved" => [ :text, :jsonb ],
             "milestone_points" => :integer,
-            "last_milestone_at" => :datetime
+            "last_milestone_at" => :datetime,
+            "onboarding_replay_started_at" => :datetime,
+            "onboarding_replay_steps" => [ :text, :jsonb ]
           }
 
           # Check required columns

data/lib/rails_onboarding/version.rb

@@ -1,3 +1,3 @@
 module RailsOnboarding
-  VERSION = "0.6.3"
+  VERSION = "0.7.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_onboarding
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.1
 platform: ruby
 authors:
 - David Lewis
@@ -234,6 +234,7 @@ files:
 - lib/generators/rails_onboarding/templates/add_analytics_to_rails_onboarding.rb
 - lib/generators/rails_onboarding/templates/add_milestone_tracking_to_users.rb
 - lib/generators/rails_onboarding/templates/add_onboarding_indexes.rb
+- lib/generators/rails_onboarding/templates/add_onboarding_replay_to_users.rb
 - lib/generators/rails_onboarding/templates/add_onboarding_to_users.rb
 - lib/generators/rails_onboarding/templates/add_robustness_fields_to_users.rb.tt
 - lib/generators/rails_onboarding/templates/create_rails_onboarding_flows.rb
@@ -281,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.6.3
+  source_code_uri: https://github.com/bunnahabhain/rails_onboarding/tree/v0.7.1
   changelog_uri: https://github.com/bunnahabhain/rails_onboarding/blob/master/docs/CHANGELOG.md
 rdoc_options: []
 require_paths:
@@ -297,7 +298,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Flexible onboarding engine for Rails applications
 test_files: []