rails_onboarding 0.6.1

data/lib/rails_onboarding/controller_helpers.rb

@@ -0,0 +1,153 @@
+# lib/rails_onboarding/controller_helpers.rb
+module RailsOnboarding
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :needs_onboarding?, :onboarding_path
+    end
+
+    # Configuration at the controller level
+    class_methods do
+      def skip_onboarding_check(options = {})
+        @skip_onboarding_options = options
+      end
+
+      def skip_onboarding_for_action?(action)
+        return false unless @skip_onboarding_options
+
+        if @skip_onboarding_options[:only]
+          Array(@skip_onboarding_options[:only]).include?(action.to_sym)
+        elsif @skip_onboarding_options[:except]
+          !Array(@skip_onboarding_options[:except]).include?(action.to_sym)
+        else
+          true
+        end
+      end
+    end
+
+    def needs_onboarding?
+      return false unless user_signed_in?
+      return false if on_onboarding_page?
+      return false if skip_onboarding_request?
+      return false if self.class.skip_onboarding_for_action?(action_name)
+
+      current_user.needs_onboarding?
+    end
+
+    def on_onboarding_page?
+      # Deliberately reads the engine proxy, not the onboarding_path method -
+      # in engine controllers the engine's own url_helper shadows ours, so
+      # relying on method resolution here would be ambiguous. Chomping makes
+      # the match segment-aware: the engine root (with or without its
+      # trailing slash) and anything under it count, but sibling host paths
+      # that merely share the prefix (/onboarding_help when mounted at
+      # /onboarding) do not.
+      root = rails_onboarding.onboarding_path.chomp("/")
+      return true if request.path == root || request.path.start_with?("#{root}/")
+
+      on_current_step_page?
+    end
+
+    def skip_onboarding_request?
+      request.xhr? ||
+        request.format.json? ||
+        request.path.start_with?("/api")
+    end
+
+    # The onboarding flow lives at the engine's mount root, so the raw engine
+    # helper returns it with a trailing slash ("/onboarding/") like any
+    # mounted engine root. Serve host apps the canonical slash-less form for
+    # links and redirects.
+    def onboarding_path
+      path = rails_onboarding.onboarding_path.chomp("/")
+      path.empty? ? "/" : path
+    end
+
+    # Complete the current onboarding step from a host-app controller.
+    #
+    # Call this from the action that performs the step's real work (e.g.
+    # ProfilesController#create after a successful save), then redirect to
+    # onboarding_path to advance the user:
+    #
+    #   if advance_onboarding!(:profile)
+    #     redirect_to onboarding_path
+    #   else
+    #     redirect_to @profile
+    #   end
+    #
+    # Deliberately a no-op unless the named step is the user's *current*
+    # step - so when the same action runs outside onboarding (the user edits
+    # their profile again next week), the controller behaves normally.
+    #
+    # @param step_name [Symbol, String] the step this action fulfills
+    # @return [Boolean] true if the step was completed and the user advanced
+    def advance_onboarding!(step_name)
+      return false unless user_signed_in?
+      return false unless current_user.respond_to?(:needs_onboarding?)
+      return false unless current_user.needs_onboarding?
+
+      step = current_user.current_onboarding_step
+      return false unless step && step[:name].to_sym == step_name.to_sym
+
+      current_user.complete_onboarding_step!(step[:name])
+      true
+    end
+
+    # Resolve a step's :path option against the host application's routes.
+    # Symbols/Strings are sent to the main_app route proxy; Procs are
+    # instance_exec'd in the controller context, so a zero-arg lambda can use
+    # main_app, current_user, params, etc.:
+    #
+    #   path: :new_profile_path
+    #   path: -> { main_app.new_post_path(from: "onboarding") }
+    def resolve_onboarding_step_path(path)
+      path.is_a?(Proc) ? instance_exec(&path) : main_app.public_send(path)
+    end
+
+    private
+
+    # True when the current request is for the page a :path-based step points
+    # at, or for another action on that same controller. Folded into
+    # on_onboarding_page? (and therefore needs_onboarding?) so a host app's
+    # `redirect_to onboarding_path if needs_onboarding?` guard doesn't bounce
+    # the user off the very flow the current step sent them to.
+    #
+    # Two things need covering, not just one:
+    #   - without the exact-path check, /onboarding redirects to the step
+    #     page and the step page's own guard redirects straight back, forever.
+    #   - without the same-controller check, the action that actually
+    #     performs the step's work (e.g. PATCH /profile for a step whose
+    #     :path is edit_profile_path) never runs at all: the guard fires as a
+    #     before_action on *every* controller action, so it intercepts the
+    #     update/create request and redirects to /onboarding before
+    #     advance_onboarding! ever gets a chance to complete the step. That
+    #     action decides independently whether the step completes, so the
+    #     guard only needs to get out of its way.
+    def on_current_step_page?
+      return false unless user_signed_in?
+      return false unless current_user.respond_to?(:current_onboarding_step)
+
+      step = current_user.current_onboarding_step
+      return false unless step.is_a?(Hash) && step[:path]
+
+      resolved = resolve_onboarding_step_path(step[:path])
+      # Compare paths only - the resolved route may carry a query string
+      # (path: -> { main_app.new_post_path(from: "onboarding") }) or be a
+      # full URL, while request.path never includes either.
+      resolved_path = URI.parse(resolved.to_s).path
+      return true if request.path == resolved_path
+
+      recognized = Rails.application.routes.recognize_path(resolved_path, method: "GET")
+      recognized[:controller] == params[:controller]
+    rescue StandardError => e
+      Rails.logger.warn("RailsOnboarding: could not resolve step path for loop guard: #{e.class} - #{e.message}")
+      false
+    end
+
+    def user_signed_in?
+      # Override this or use the host app's method
+      defined?(current_user) && current_user.present?
+    end
+  end
+end

data/lib/rails_onboarding/current.rb

@@ -0,0 +1,13 @@
+module RailsOnboarding
+  # Per-request/per-job isolated state.
+  #
+  # MultiTenant.with_tenant_configuration uses this to apply tenant-specific
+  # configuration overrides for the duration of a block without mutating the
+  # shared RailsOnboarding.configuration singleton - CurrentAttributes is
+  # isolated per thread/fiber and is automatically reset by Rails around each
+  # request and job, so concurrent requests on a threaded server can never
+  # observe (or clobber) each other's tenant configuration.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :tenant_overrides
+  end
+end

data/lib/rails_onboarding/deprecation.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Deprecation warnings utility module
+  # Provides consistent deprecation warnings across the gem
+  module Deprecation
+    class << self
+      # Issue a deprecation warning
+      # @param message [String] The deprecation message
+      # @param version [String] The version when the feature will be removed
+      def warn(message, version: nil)
+        full_message = "[DEPRECATION] #{message}"
+        full_message += " It will be removed in version #{version}." if version
+
+        if defined?(ActiveSupport::Deprecation)
+          # Use the default deprecator instance
+          deprecator = ActiveSupport::Deprecation._instance || ActiveSupport::Deprecation.new
+          deprecator.warn(full_message)
+        else
+          Rails.logger.warn(full_message) if defined?(Rails)
+        end
+      end
+
+      # Deprecate a method call
+      # @param old_method [String] The deprecated method name
+      # @param new_method [String] The replacement method name
+      # @param version [String] The version when it will be removed
+      def deprecate_method(old_method, new_method: nil, version: nil)
+        message = "#{old_method} is deprecated"
+        message += " and will be removed in version #{version}" if version
+        message += ". Use #{new_method} instead" if new_method
+        message += "."
+
+        warn(message, version: version)
+      end
+
+      # Deprecate a configuration option
+      # @param option [String] The deprecated configuration option
+      # @param replacement [String] The replacement option
+      # @param version [String] The version when it will be removed
+      def deprecate_config(option, replacement: nil, version: nil)
+        message = "Configuration option '#{option}' is deprecated"
+        message += " and will be removed in version #{version}" if version
+        message += ". Use '#{replacement}' instead" if replacement
+        message += "."
+
+        warn(message, version: version)
+      end
+
+      # Deprecate a data format
+      # @param format [String] The deprecated format description
+      # @param new_format [String] The new format description
+      # @param version [String] The version when support will be removed
+      def deprecate_format(format, new_format: nil, version: nil)
+        message = "#{format} is deprecated"
+        message += " and support will be removed in version #{version}" if version
+        message += ". Please migrate to: #{new_format}" if new_format
+        message += "."
+
+        warn(message, version: version)
+      end
+    end
+  end
+end

data/lib/rails_onboarding/devise_integration.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Integration module for seamless Devise compatibility
+  # Automatically detects Devise and provides integration helpers
+  module DeviseIntegration
+    extend ActiveSupport::Concern
+
+    included do
+      # Detect if Devise is available
+      if defined?(Devise)
+        # Hook into Devise's after_sign_in callback
+        after_action :redirect_to_onboarding_if_needed, only: [ :create ], if: -> { devise_controller? }
+      end
+    end
+
+    module ClassMethods
+      # Check if Devise is present in the application
+      def devise_available?
+        defined?(Devise)
+      end
+
+      # Configure Devise integration
+      def configure_devise_integration(options = {})
+        @devise_integration_options = {
+          redirect_after_sign_in: true,
+          redirect_after_sign_up: true,
+          skip_for_admin: options.fetch(:skip_for_admin, true),
+          admin_check: options.fetch(:admin_check, ->(user) { user.respond_to?(:admin?) && user.admin? })
+        }.merge(options)
+      end
+
+      def devise_integration_options
+        @devise_integration_options || {}
+      end
+    end
+
+    # Instance methods for Devise integration
+    def redirect_to_onboarding_if_needed
+      return unless self.class.devise_available?
+      return unless current_user
+      return if devise_integration_skip_onboarding?
+
+      if current_user.should_see_onboarding?
+        store_location_for(current_user, rails_onboarding.onboarding_path) if defined?(store_location_for)
+        redirect_to rails_onboarding.onboarding_path and return
+      end
+    end
+
+    private
+
+    def devise_integration_skip_onboarding?
+      options = self.class.devise_integration_options
+
+      # Skip for admins if configured
+      if options[:skip_for_admin] && options[:admin_check]
+        return true if options[:admin_check].call(current_user)
+      end
+
+      false
+    end
+
+    def devise_controller?
+      is_a?(Devise::SessionsController) ||
+      is_a?(Devise::RegistrationsController) ||
+      is_a?(Devise::PasswordsController)
+    rescue NameError
+      false
+    end
+  end
+
+  # Helper module to extend Devise controllers
+  module DeviseControllerExtension
+    extend ActiveSupport::Concern
+
+    included do
+      # Override Devise's after_sign_in_path_for to redirect to onboarding
+      def after_sign_in_path_for(resource)
+        if resource.respond_to?(:should_see_onboarding?) && resource.should_see_onboarding?
+          rails_onboarding.onboarding_path
+        else
+          stored_location_for(resource) || super
+        end
+      end
+
+      # Override Devise's after_sign_up_path_for to redirect to onboarding
+      def after_sign_up_path_for(resource)
+        if resource.respond_to?(:should_see_onboarding?) && resource.should_see_onboarding?
+          rails_onboarding.onboarding_path
+        else
+          stored_location_for(resource) || super
+        end
+      end
+
+      # Override after_inactive_sign_up_path_for (for unconfirmed users)
+      def after_inactive_sign_up_path_for(resource)
+        if RailsOnboarding.configuration.redirect_unconfirmed_to_onboarding
+          # Store that they should see onboarding after confirmation
+          session[:pending_onboarding] = true
+          super
+        else
+          super
+        end
+      end
+    end
+  end
+
+  # Railtie to auto-integrate with Devise when available
+  class DeviseRailtie < Rails::Railtie
+    initializer "rails_onboarding.devise_integration", after: :load_config_initializers do
+      ActiveSupport.on_load(:action_controller) do
+        if defined?(Devise)
+          # Auto-include DeviseControllerExtension in Devise controllers
+          Devise::SessionsController.include(RailsOnboarding::DeviseControllerExtension) rescue nil
+          Devise::RegistrationsController.include(RailsOnboarding::DeviseControllerExtension) rescue nil
+
+          Rails.logger.info "RailsOnboarding: Devise integration enabled"
+        end
+      end
+    end
+  end
+end

data/lib/rails_onboarding/engine.rb

@@ -0,0 +1,245 @@
+module RailsOnboarding
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsOnboarding
+
+    # Make engine's helpers available to the main app
+    config.to_prepare do
+      ApplicationController.helper(RailsOnboarding::Engine.helpers)
+      ApplicationController.helper(RailsOnboarding::ResponsiveHelper)
+    end
+
+    # Load migrations
+    initializer :append_migrations do |app|
+      unless app.root.to_s.match?(root.to_s)
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+
+    # Load JavaScript and CSS assets
+    initializer "rails_onboarding.assets" do |app|
+      # Detect which asset pipeline is in use
+      asset_pipeline = Engine.detect_asset_pipeline(app)
+
+      # Configure assets based on the pipeline
+      case asset_pipeline
+      when :sprockets
+        Engine.configure_sprockets_assets(app)
+      when :propshaft
+        Engine.configure_propshaft_assets(app)
+      when :importmap
+        Engine.configure_importmap_assets(app)
+      else
+        # Fallback configuration for modern bundlers (ESBuild, Webpack, etc.)
+        Engine.configure_modern_bundler_assets(app)
+      end
+
+      Rails.logger.info "RailsOnboarding: Detected asset pipeline: #{asset_pipeline}"
+    end
+
+    # Add engine's controller methods to ApplicationController
+    initializer "rails_onboarding.controller_helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include RailsOnboarding::ControllerHelpers
+      end
+    end
+
+    # Add view paths for the engine
+    initializer "rails_onboarding.view_paths" do |app|
+      ActiveSupport.on_load(:action_controller_base) do
+        # Add engine views to the view path
+        view_path = RailsOnboarding::Engine.root.join("app", "views")
+
+        # Ensure the view path exists before adding it
+        if File.directory?(view_path)
+          append_view_path view_path
+          Rails.logger.debug "RailsOnboarding: Added view path: #{view_path}"
+        else
+          Rails.logger.warn "RailsOnboarding: View path not found: #{view_path}"
+        end
+      end
+
+      # Also add to ActionMailer if available
+      ActiveSupport.on_load(:action_mailer) do
+        view_path = RailsOnboarding::Engine.root.join("app", "views")
+        if File.directory?(view_path)
+          append_view_path view_path
+          Rails.logger.debug "RailsOnboarding: Added mailer view path: #{view_path}"
+        end
+      end
+    end
+
+    # Optional: Setup Stimulus integration if available
+    config.after_initialize do |app|
+      Engine.setup_stimulus_integration(app) if Engine.stimulus_available?(app)
+      Engine.setup_importmap_integration(app) if Engine.importmap_available?(app)
+
+      # Bundler apps (esbuild/webpack/vite) vendor a *copy* of the gem's Stimulus
+      # controllers, so unlike the engine-served CSS/views they don't auto-update
+      # on a gem bump. Nudge the developer when that copy has drifted. Dev only.
+      Engine.warn_if_controllers_stale(app) if Rails.env.development?
+    end
+
+    # NOTE: everything below is internal to the engine, not part of its public API.
+    # It can't actually be marked `private` (bare `private` has no effect on `def self.x`
+    # methods, and `private_class_method` would break the initializers above: those run
+    # via `instance_exec` with the Rails::Railtie *instance* as `self`, not this class, so
+    # they must call these as `Engine.method_name(...)` with an explicit receiver).
+
+    # Detect which asset pipeline is being used
+    def self.detect_asset_pipeline(app)
+      if defined?(Propshaft)
+        :propshaft
+      elsif defined?(Sprockets) && app.config.respond_to?(:assets)
+        :sprockets
+      elsif importmap_available?(app)
+        :importmap
+      else
+        :modern_bundler
+      end
+    end
+
+    # Configure Sprockets-based asset pipeline
+    def self.configure_sprockets_assets(app)
+      app.config.assets.paths << root.join("app", "assets", "stylesheets")
+      app.config.assets.paths << root.join("app", "assets", "javascripts")
+
+      # Precompile all CSS and JavaScript assets
+      app.config.assets.precompile += %w[
+        rails_onboarding/application.css
+        rails_onboarding/tooltips.css
+        rails_onboarding/utilities.css
+        rails_onboarding/accessibility.css
+        rails_onboarding/tour.css
+        rails_onboarding/mobile.css
+        rails_onboarding/milestones.css
+        rails_onboarding/progressive_disclosure.css
+        rails_onboarding/flash_messages.css
+        rails_onboarding/admin.css
+        rails_onboarding/application.js
+        rails_onboarding/*.js
+      ]
+
+      Rails.logger.info "RailsOnboarding: Configured Sprockets asset pipeline"
+    end
+
+    # Configure Propshaft-based asset pipeline
+    def self.configure_propshaft_assets(app)
+      # Propshaft automatically includes all assets from engine paths
+      app.config.assets.paths << root.join("app", "assets", "stylesheets")
+      app.config.assets.paths << root.join("app", "assets", "javascripts")
+
+      Rails.logger.info "RailsOnboarding: Configured Propshaft asset pipeline"
+    end
+
+    # Configure Importmap-based asset loading
+    def self.configure_importmap_assets(app)
+      # Importmap handles JavaScript, but we still need stylesheets
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app", "assets", "stylesheets")
+      end
+
+      Rails.logger.info "RailsOnboarding: Configured Importmap asset loading"
+    end
+
+    # Configure for modern bundlers (ESBuild, Webpack, etc.)
+    def self.configure_modern_bundler_assets(app)
+      # Add asset paths if assets config is available
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app", "assets", "stylesheets")
+        app.config.assets.paths << root.join("app", "assets", "javascripts")
+      end
+
+      Rails.logger.info "RailsOnboarding: Configured for modern bundler (ESBuild/Webpack/etc.)"
+    end
+
+    def self.stimulus_available?(app)
+      defined?(StimulusRails) &&
+        app.config.respond_to?(:stimulus) &&
+        app.config.stimulus.respond_to?(:paths)
+    end
+
+    def self.setup_stimulus_integration(app)
+      begin
+        app.config.stimulus.paths << root.join("app", "assets", "javascripts", "rails_onboarding")
+        Rails.logger.info "RailsOnboarding: Stimulus integration enabled"
+      rescue => e
+        Rails.logger.warn "RailsOnboarding: Could not setup Stimulus integration: #{e.message}"
+      end
+    end
+
+    def self.importmap_available?(app)
+      defined?(Importmap) &&
+        defined?(Importmap::Map) &&
+        app.config.respond_to?(:importmap)
+    end
+
+    def self.setup_importmap_integration(app)
+      begin
+        importmap_path = root.join("config", "importmap.rb")
+        if File.exist?(importmap_path)
+          # importmap-rails draws app.config.importmap.paths into app.importmap
+          # during its own "importmap" initializer, which has already run by the
+          # time this after_initialize hook fires - appending to that array here
+          # would be a no-op. Draw directly into the live map instead so the
+          # engine's pins actually get registered.
+          app.importmap.draw(importmap_path)
+          Rails.logger.info "RailsOnboarding: Importmap integration enabled"
+        end
+      rescue => e
+        Rails.logger.warn "RailsOnboarding: Could not setup importmap integration: #{e.message}"
+      end
+    end
+
+    # Warn (dev only) when a bundler app's vendored copy of the Stimulus
+    # controllers has drifted from the installed gem version. `rails g
+    # rails_onboarding:update` stamps the copy with a version marker; we compare
+    # that marker to RailsOnboarding::VERSION. Checks the flat layout (controllers
+    # copied straight into controllers/, the current recommendation) as well as
+    # the legacy controllers/rails_onboarding/ subfolder so an un-migrated app
+    # still gets nudged. Never raises - a warning must not take down boot.
+    def self.warn_if_controllers_stale(app)
+      controllers = app.root.join("app", "javascript", "controllers")
+      return unless Dir.exist?(controllers)
+
+      legacy = controllers.join("rails_onboarding")
+      marker =
+        if File.exist?(controllers.join(".rails_onboarding_version"))
+          controllers.join(".rails_onboarding_version")
+        elsif File.exist?(legacy.join(".rails_onboarding_version"))
+          legacy.join(".rails_onboarding_version")
+        end
+
+      # Is a copy vendored here at all? A marker, the legacy subfolder, or a
+      # signature controller (onboarding_controller.js is distinctively ours,
+      # so it won't be confused with a host controller in the flat layout).
+      vendored = marker ||
+                 Dir.exist?(legacy) ||
+                 File.exist?(controllers.join("onboarding_controller.js"))
+      return unless vendored
+
+      current = RailsOnboarding::VERSION
+      cmd     = "bin/rails generate rails_onboarding:update"
+
+      unless marker
+        Rails.logger.warn(
+          "[rails_onboarding] Vendored Stimulus controllers have no version marker, so " \
+          "they may be stale relative to gem v#{current}. Run `#{cmd}` to re-sync and " \
+          "stamp them, then rebuild your JS bundle."
+        )
+        return
+      end
+
+      stamped = File.read(marker).strip
+      if stamped != current
+        Rails.logger.warn(
+          "[rails_onboarding] Vendored Stimulus controllers were generated for v#{stamped} " \
+          "but the gem is v#{current}. Run `#{cmd}` to re-sync, then rebuild your JS bundle."
+        )
+      end
+    rescue => e
+      Rails.logger.debug "RailsOnboarding: controller staleness check skipped: #{e.message}"
+    end
+  end
+end