rails_onboarding 0.6.1

data/lib/generators/rails_onboarding/templates/README

@@ -0,0 +1,120 @@
+===============================================================================
+
+Rails Onboarding has been installed!
+
+Next steps:
+
+1. Run the migrations:
+   bin/rails db:migrate
+
+2. Add the Onboardable concern to your User model:
+
+   # app/models/user.rb
+   class User < ApplicationRecord
+     include RailsOnboarding::Onboardable
+
+     # your existing code...
+   end
+
+3. Review config/initializers/rails_onboarding.rb - in particular, make sure
+   redirect_after_completion / redirect_after_skip point at routes that
+   actually exist in your app (they default to :root_path).
+
+4. Load the CSS and JS in your layout.
+
+   On Sprockets, rails_onboarding/application.css bundles all of the gem's
+   stylesheets itself, so one tag is enough:
+
+   # app/views/layouts/application.html.erb
+   <%= stylesheet_link_tag "rails_onboarding/application" %>
+   <%= javascript_include_tag "rails_onboarding/application", defer: true %>
+
+   On Propshaft (Rails 8's default, including with cssbundling-rails),
+   there's no bundling step, so application.css only contains its own base
+   styles - you need one tag per gem stylesheet or tooltips/tours/
+   milestones/mobile responsiveness/etc. will silently never load:
+
+   # app/views/layouts/application.html.erb
+   <%= stylesheet_link_tag "rails_onboarding/application" %>
+   <%= stylesheet_link_tag "rails_onboarding/tooltips" %>
+   <%= stylesheet_link_tag "rails_onboarding/utilities" %>
+   <%= stylesheet_link_tag "rails_onboarding/accessibility" %>
+   <%= stylesheet_link_tag "rails_onboarding/milestones" %>
+   <%= stylesheet_link_tag "rails_onboarding/tour" %>
+   <%= stylesheet_link_tag "rails_onboarding/flash_messages" %>
+   <%= stylesheet_link_tag "rails_onboarding/progressive_disclosure" %>
+   <%= stylesheet_link_tag "rails_onboarding/admin" %>
+   <%= stylesheet_link_tag "rails_onboarding/mobile" %>
+   <%= javascript_include_tag "rails_onboarding/application", defer: true %>
+
+   (Keep application first and mobile last; skip admin if you don't use the
+   admin dashboard.)
+
+   If you're on Importmap, the tags above are enough to load the tooltip/tour helpers
+   (RailsOnboarding.showTooltip, etc.), but the Stimulus controllers still
+   need to be registered explicitly - add to app/javascript/controllers/index.js:
+
+     import OnboardingController from "rails_onboarding/onboarding_controller"
+     import ProgressController from "rails_onboarding/progress_controller"
+     import NavigationController from "rails_onboarding/navigation_controller"
+     import TooltipController from "rails_onboarding/tooltip_controller"
+
+     application.register("onboarding", OnboardingController)
+     application.register("progress", ProgressController)
+     application.register("navigation", NavigationController)
+     application.register("tooltip", TooltipController)
+
+   (These four cover the core onboarding flow. See the README's Asset
+   Loading section for the full controller list, including milestones,
+   tours, and the admin dashboard.)
+
+   If you're on ESBuild/Webpack/Vite instead, see docs/ESBUILD_SETUP.md
+   in the gem's repository (github.com/bunnahabhain/rails_onboarding) for
+   how to copy and register the controllers manually.
+
+5. Create a view for each step in config.steps (config/initializers/
+   rails_onboarding.rb). The default config ships with four steps -
+   welcome, profile, first_action, explore - and the gem only provides a
+   real view for "welcome"; any step without one falls back to a generic
+   "this step is not yet fully configured" placeholder, which is fine for
+   development but not something to ship.
+
+   # app/views/rails_onboarding/onboarding/profile.html.erb
+   <div class="onboarding-step">
+     <h1>Setup Your Profile</h1>
+
+     <%= link_to "Continue", next_onboarding_path,
+         method: :post,
+         class: "btn btn-primary" %>
+   </div>
+
+   Repeat for each step name. See the README's "Customize Step Views"
+   section for a full example, including the welcome.html.erb the gem
+   ships as a reference.
+
+6. Require a `current_user` method in your controllers (from Devise or your
+   own auth) - RailsOnboarding reads it to know who's onboarding. Then wire
+   up the redirect yourself; the gem gives you the predicate, not the
+   before_action:
+
+   # app/controllers/application_controller.rb
+   class ApplicationController < ActionController::Base
+     before_action :redirect_to_onboarding_if_needed
+
+     private
+
+     def redirect_to_onboarding_if_needed
+       redirect_to onboarding_path if needs_onboarding?
+     end
+   end
+
+   Skip specific actions/controllers with:
+
+     skip_onboarding_check only: [:edit, :update]   # or except: [...]
+
+7. Visit /onboarding to test your setup!
+
+For more details, see the README at
+https://github.com/bunnahabhain/rails_onboarding
+
+===============================================================================

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

@@ -0,0 +1,33 @@
+class AddAnalyticsToRailsOnboarding < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    create_table :rails_onboarding_analytics_events do |t|
+      t.references :user, polymorphic: true, null: true
+      t.string :event_type, null: false
+      t.text :properties
+      t.string :session_id
+      t.datetime :occurred_at, null: false
+
+      t.timestamps
+
+      # Indexes for common queries and performance optimization
+      t.index :event_type
+      t.index :occurred_at
+      t.index :session_id
+
+      # Polymorphic association indexes (optimized for queries on specific user types)
+      t.index [:user_type, :user_id], name: 'index_analytics_events_on_user'
+      t.index [:user_type, :user_id, :event_type], name: 'index_analytics_events_on_user_and_type'
+      t.index [:user_type, :user_id, :occurred_at], name: 'index_analytics_events_on_user_and_date'
+
+      # Composite indexes for common analytics queries
+      t.index [:event_type, :occurred_at], name: 'index_analytics_events_on_type_and_date'
+      t.index [:user_id, :session_id], name: 'index_analytics_events_on_user_and_session'
+      t.index [:session_id, :occurred_at], name: 'index_analytics_events_on_session_and_date'
+      t.index [:event_type, :session_id], name: 'index_analytics_events_on_type_and_session'
+    end
+  end
+
+  def down
+    drop_table :rails_onboarding_analytics_events if table_exists?(:rails_onboarding_analytics_events)
+  end
+end

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

@@ -0,0 +1,38 @@
+class AddMilestoneTrackingToUsers < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  disable_ddl_transaction!
+
+  def up
+    # No DB-level default: MySQL/MariaDB reject a literal DEFAULT on
+    # TEXT/BLOB/JSON columns. Onboardable already treats a nil
+    # milestones_achieved as an empty array in Ruby (see onboardable.rb),
+    # so there's nothing to work around adapter-by-adapter here.
+    add_column :users, :milestones_achieved, :text
+    add_column :users, :milestone_points, :integer, default: 0
+    add_column :users, :last_milestone_at, :datetime
+
+    # On PostgreSQL, build concurrently so these don't hold a write lock on a
+    # large, live users table; other adapters don't support that algorithm,
+    # so fall back to a plain index there.
+    add_index :users, :milestone_points, **concurrent_index_options
+    add_index :users, :last_milestone_at, **concurrent_index_options
+  end
+
+  def down
+    remove_index :users, :last_milestone_at if index_exists?(:users, :last_milestone_at)
+    remove_index :users, :milestone_points if index_exists?(:users, :milestone_points)
+
+    remove_column :users, :last_milestone_at if column_exists?(:users, :last_milestone_at)
+    remove_column :users, :milestone_points if column_exists?(:users, :milestone_points)
+    remove_column :users, :milestones_achieved if column_exists?(:users, :milestones_achieved)
+  end
+
+  private
+
+  def concurrent_index_options
+    postgresql? ? { algorithm: :concurrently } : {}
+  end
+
+  def postgresql?
+    %w[postgresql postgis].include?(ActiveRecord::Base.connection.adapter_name.downcase)
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+class AddOnboardingIndexes < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  disable_ddl_transaction!
+
+  def up
+    # Add indexes for frequently queried columns.
+    # Skip if index already exists. On PostgreSQL, build concurrently so these
+    # don't hold a write lock on a large, live users table; other adapters
+    # don't support that algorithm, so fall back to a plain index there.
+    unless index_exists?(:users, :onboarding_completed)
+      add_index :users, :onboarding_completed, **concurrent_index_options
+    end
+
+    unless index_exists?(:users, :onboarding_current_step)
+      add_index :users, :onboarding_current_step, **concurrent_index_options
+    end
+
+    unless index_exists?(:users, :onboarding_skipped)
+      add_index :users, :onboarding_skipped, **concurrent_index_options
+    end
+
+    unless index_exists?(:users, [:onboarding_completed, :created_at])
+      # Composite index for finding users who need onboarding
+      add_index :users, [:onboarding_completed, :created_at],
+                name: 'index_users_on_onboarding_status_and_created', **concurrent_index_options
+    end
+
+    unless index_exists?(:users, :onboarding_completed_at)
+      # Index for analytics queries on completion time
+      add_index :users, :onboarding_completed_at, **concurrent_index_options
+    end
+
+    unless index_exists?(:users, :last_milestone_at)
+      # Index for milestone queries
+      add_index :users, :last_milestone_at, **concurrent_index_options
+    end
+
+    # Add indexes to analytics_events table if it exists
+    if table_exists?(:rails_onboarding_analytics_events)
+      # Named distinctly from the analytics migration's own same-columns-prefixed
+      # indexes (index_analytics_events_on_user_and_type is [:user_type, :user_id,
+      # :event_type]; index_analytics_events_on_type_and_date is [:event_type,
+      # :occurred_at]) - reusing those names here for different column sets would
+      # raise a duplicate-index-name error on every fresh install.
+      unless index_exists?(:rails_onboarding_analytics_events, [:user_id, :event_type])
+        add_index :rails_onboarding_analytics_events, [:user_id, :event_type],
+                  name: 'index_analytics_events_on_user_id_and_event_type', **concurrent_index_options
+      end
+
+      unless index_exists?(:rails_onboarding_analytics_events, [:event_type, :created_at])
+        add_index :rails_onboarding_analytics_events, [:event_type, :created_at],
+                  name: 'index_analytics_events_on_type_and_created_at', **concurrent_index_options
+      end
+
+      unless index_exists?(:rails_onboarding_analytics_events, :session_id)
+        add_index :rails_onboarding_analytics_events, :session_id, **concurrent_index_options
+      end
+
+      unless index_exists?(:rails_onboarding_analytics_events, [:user_id, :session_id])
+        add_index :rails_onboarding_analytics_events, [:user_id, :session_id],
+                  name: 'index_analytics_events_on_user_and_session', **concurrent_index_options
+      end
+    end
+  end
+
+  def down
+    # Remove indexes in reverse order
+    if table_exists?(:rails_onboarding_analytics_events)
+      remove_index :rails_onboarding_analytics_events, name: 'index_analytics_events_on_user_and_session' if index_exists?(:rails_onboarding_analytics_events, [:user_id, :session_id], name: 'index_analytics_events_on_user_and_session')
+      remove_index :rails_onboarding_analytics_events, :session_id if index_exists?(:rails_onboarding_analytics_events, :session_id)
+      remove_index :rails_onboarding_analytics_events, name: 'index_analytics_events_on_type_and_created_at' if index_exists?(:rails_onboarding_analytics_events, [:event_type, :created_at], name: 'index_analytics_events_on_type_and_created_at')
+      remove_index :rails_onboarding_analytics_events, name: 'index_analytics_events_on_user_id_and_event_type' if index_exists?(:rails_onboarding_analytics_events, [:user_id, :event_type], name: 'index_analytics_events_on_user_id_and_event_type')
+    end
+
+    remove_index :users, :last_milestone_at if index_exists?(:users, :last_milestone_at)
+    remove_index :users, :onboarding_completed_at if index_exists?(:users, :onboarding_completed_at)
+    remove_index :users, name: 'index_users_on_onboarding_status_and_created' if index_exists?(:users, [:onboarding_completed, :created_at], name: 'index_users_on_onboarding_status_and_created')
+    remove_index :users, :onboarding_skipped if index_exists?(:users, :onboarding_skipped)
+    remove_index :users, :onboarding_current_step if index_exists?(:users, :onboarding_current_step)
+    remove_index :users, :onboarding_completed if index_exists?(:users, :onboarding_completed)
+  end
+
+  private
+
+  def concurrent_index_options
+    postgresql? ? { algorithm: :concurrently } : {}
+  end
+
+  def postgresql?
+    %w[postgresql postgis].include?(ActiveRecord::Base.connection.adapter_name.downcase)
+  end
+end

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

@@ -0,0 +1,51 @@
+class AddOnboardingToUsers < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  disable_ddl_transaction!
+
+  def up
+    add_column :users, :onboarding_completed, :boolean, default: false, null: false
+    add_column :users, :onboarding_completed_at, :datetime
+    add_column :users, :onboarding_current_step, :string
+    add_column :users, :onboarding_skipped, :boolean, default: false
+
+    # Use jsonb for PostgreSQL, json for MySQL/MariaDB, text for others
+    adapter_name = ActiveRecord::Base.connection.adapter_name.downcase
+    case adapter_name
+    when "postgresql", "postgis"
+      add_column :users, :feature_tooltips_shown, :jsonb, default: {}
+    when "mysql2", "trilogy", "mysql"
+      add_column :users, :feature_tooltips_shown, :json
+    else
+      # SQLite and other databases - use text with serialization
+      add_column :users, :feature_tooltips_shown, :text, default: "{}"
+    end
+
+    # Performance indexes. On PostgreSQL, build them concurrently so they
+    # don't hold a write lock on a large, live users table; other adapters
+    # don't support that algorithm, so fall back to a plain index there.
+    add_index :users, :onboarding_completed, **concurrent_index_options
+    add_index :users, :onboarding_current_step, **concurrent_index_options
+    add_index :users, [:onboarding_completed, :created_at], name: 'index_users_on_onboarding_status_and_created', **concurrent_index_options
+  end
+
+  def down
+    remove_index :users, name: 'index_users_on_onboarding_status_and_created' if index_exists?(:users, [:onboarding_completed, :created_at], name: 'index_users_on_onboarding_status_and_created')
+    remove_index :users, :onboarding_current_step if index_exists?(:users, :onboarding_current_step)
+    remove_index :users, :onboarding_completed if index_exists?(:users, :onboarding_completed)
+
+    remove_column :users, :feature_tooltips_shown if column_exists?(:users, :feature_tooltips_shown)
+    remove_column :users, :onboarding_skipped if column_exists?(:users, :onboarding_skipped)
+    remove_column :users, :onboarding_current_step if column_exists?(:users, :onboarding_current_step)
+    remove_column :users, :onboarding_completed_at if column_exists?(:users, :onboarding_completed_at)
+    remove_column :users, :onboarding_completed if column_exists?(:users, :onboarding_completed)
+  end
+
+  private
+
+  def concurrent_index_options
+    postgresql? ? { algorithm: :concurrently } : {}
+  end
+
+  def postgresql?
+    %w[postgresql postgis].include?(ActiveRecord::Base.connection.adapter_name.downcase)
+  end
+end

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

@@ -0,0 +1,20 @@
+class AddRobustnessFieldsToUsers < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    add_column :users, :onboarding_errors, :text unless column_exists?(:users, :onboarding_errors)
+    add_column :users, :onboarding_failed_actions, :text unless column_exists?(:users, :onboarding_failed_actions)
+    add_column :users, :onboarding_session_data, :text unless column_exists?(:users, :onboarding_session_data)
+
+    # Add indexes for performance
+    add_index :users, :onboarding_completed unless index_exists?(:users, :onboarding_completed)
+    add_index :users, :onboarding_current_step unless index_exists?(:users, :onboarding_current_step)
+  end
+
+  def down
+    remove_index :users, :onboarding_current_step if index_exists?(:users, :onboarding_current_step)
+    remove_index :users, :onboarding_completed if index_exists?(:users, :onboarding_completed)
+
+    remove_column :users, :onboarding_session_data if column_exists?(:users, :onboarding_session_data)
+    remove_column :users, :onboarding_failed_actions if column_exists?(:users, :onboarding_failed_actions)
+    remove_column :users, :onboarding_errors if column_exists?(:users, :onboarding_errors)
+  end
+end

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

@@ -0,0 +1,18 @@
+class CreateRailsOnboardingFlows < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    create_table :rails_onboarding_flows do |t|
+      t.string :name, null: false
+      t.text :description
+      t.text :steps, null: false
+      t.boolean :active, null: false, default: false
+
+      t.timestamps
+    end
+
+    add_index :rails_onboarding_flows, :active
+  end
+
+  def down
+    drop_table :rails_onboarding_flows if table_exists?(:rails_onboarding_flows)
+  end
+end

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

@@ -0,0 +1,18 @@
+/* Custom onboarding styles for your application */
+/*
+ * This file is for customizing the onboarding appearance
+ * to match your application's design system.
+ */
+
+/* Example customizations: */
+.onboarding-container {
+  /* Override default styles here */
+}
+
+.onboarding-progress {
+  /* Customize progress bar appearance */
+}
+
+.onboarding-step {
+  /* Customize step appearance */
+}

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

@@ -0,0 +1,75 @@
+# RailsOnboarding configuration
+#
+# See https://github.com/bunnahabhain/rails_onboarding for the full option
+# reference, and docs/MILESTONES_GUIDE.md / docs/ANALYTICS_GUIDE.md for the
+# features configured below.
+RailsOnboarding.configure do |config|
+  # The class name of your application's user model. Change this if your
+  # app uses a different name (e.g. "Account", "Member").
+  config.user_class_name = "User"
+
+  # Where to send users after they finish or skip onboarding. Accepts a
+  # route helper name (as a symbol) or a Proc that receives the user and
+  # returns a path.
+  config.redirect_after_completion = :root_path
+  config.redirect_after_skip = :root_path
+
+  # Feature toggles
+  config.enable_tooltips = true
+  config.enable_milestones = true
+  config.enable_analytics = true
+
+  # Analytics event retention/session settings. Only relevant when
+  # enable_analytics is true. See docs/ANALYTICS_GUIDE.md.
+  config.analytics_data_retention_days = 365 # how long to keep analytics events
+  config.analytics_session_timeout_minutes = 30 # inactivity gap that starts a new session
+
+  # Who should be sent through onboarding?
+  # :new_users - only users created after the gem was installed (default)
+  # :all_users - every user, regardless of when their account was created
+  # a Proc     - receives the user and returns true/false, e.g.:
+  #              config.onboarding_required_for = ->(user) { !user.admin? }
+  config.onboarding_required_for = :new_users
+
+  # The steps a user walks through, in order. Each step needs a unique
+  # `name` (used internally for progress tracking) and a `title` shown in
+  # the UI. Set `skippable: true` to let users jump past a step.
+  #
+  # Customize this list to match your app's onboarding flow - add, remove,
+  # or reorder steps as needed. If you add a step, you'll also need a
+  # matching view under app/views/rails_onboarding/onboarding/<name>.html.erb
+  # (see the generated views for examples).
+  config.steps = [
+    {
+      name: :welcome,
+      title: "Welcome",
+      icon: "🎉",
+      skippable: true
+    },
+    {
+      name: :profile,
+      title: "Setup Profile",
+      icon: "👤",
+      skippable: false
+    },
+    {
+      name: :explore,
+      title: "Explore Features",
+      icon: "🔍",
+      skippable: true
+    }
+  ]
+
+  # Contextual tooltips shown to highlight specific UI elements. The key
+  # is the tooltip's identifier (referenced from your views/helpers), and
+  # each entry configures the text, delay (ms) before it appears, and
+  # position relative to its target element ("top", "bottom", "left",
+  # "right"). Only relevant when enable_tooltips is true.
+  config.feature_tooltips = {
+    "getting_started" => {
+      text: "Click here to get started!",
+      delay: 1000,
+      position: "bottom"
+    }
+  }
+end

data/lib/generators/rails_onboarding/update_generator.rb

@@ -0,0 +1,73 @@
+require "rails/generators/base"
+require "rails_onboarding/version"
+
+module RailsOnboarding
+  module Generators
+    # Re-copies the gem's Stimulus controllers into a bundler-based host app so
+    # that a gem upgrade actually reaches the app. esbuild/webpack/vite apps
+    # bundle their own copy of these controllers (see docs/ESBUILD_SETUP.md) rather
+    # than importing them from the engine the way importmap apps do, so the copy
+    # goes stale on every gem bump unless it is re-synced. This generator is that
+    # re-sync step - run it after updating the gem:
+    #
+    #   bin/rails generate rails_onboarding:update
+    #   bin/rails generate rails_onboarding:update --path some/other/dir
+    #
+    # It copies the controllers flat into app/javascript/controllers (so Stimulus
+    # derives the flat identifiers the gem's views use - onboarding, tooltip,
+    # progress, ... - not prefixed rails-onboarding--* ones; see docs/ESBUILD_SETUP.md).
+    # The gem's application.js is intentionally NOT copied: it would clobber the
+    # host's own controllers/application.js entrypoint, and nothing imports it.
+    #
+    # It overwrites the vendored controllers unconditionally (that is the point -
+    # they are meant to mirror the gem, so there is nothing to preserve), but is
+    # deliberately scoped to those files ONLY: it never touches your initializer,
+    # migrations, rails_onboarding_custom.css, or your onboarding step views.
+    # Importmap apps don't need it (they import the controllers from the gem).
+    class UpdateGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../app/assets/javascripts/rails_onboarding", __dir__)
+
+      # Written into the destination so the engine's boot-time staleness check
+      # (see Engine.warn_if_controllers_stale) can tell which gem version the
+      # copied controllers came from. Keep in sync with that constant.
+      VERSION_MARKER = ".rails_onboarding_version".freeze
+
+      class_option :path, type: :string,
+                          default: "app/javascript/controllers",
+                          desc: "Destination directory for the copied Stimulus controllers"
+
+      def copy_controllers
+        controller_paths.each do |rel|
+          copy_file rel, File.join(dest_dir, rel), force: true
+        end
+      end
+
+      def stamp_version
+        create_file File.join(dest_dir, VERSION_MARKER),
+                    "#{RailsOnboarding::VERSION}\n", force: true
+      end
+
+      def print_next_steps
+        say ""
+        say "rails_onboarding: synced #{controller_paths.size} controller(s) to " \
+            "#{dest_dir} (v#{RailsOnboarding::VERSION}).", :green
+        say "Next, re-register the controllers and rebuild your JS bundle:", :yellow
+        say "  bin/rails stimulus:manifest:update   # if you use stimulus-rails", :yellow
+        say "  yarn build                           # or your bundler's build command", :yellow
+      end
+
+      private
+
+      def dest_dir
+        options[:path]
+      end
+
+      # Every *_controller.js the gem ships (top-level + the admin/ subfolder,
+      # which yields admin--* identifiers), as paths relative to source_root.
+      # Globbing *_controller.js deliberately excludes application.js.
+      def controller_paths
+        @controller_paths ||= Dir.glob("**/*_controller.js", base: self.class.source_root).sort
+      end
+    end
+  end
+end