rails_onboarding 0.6.1

data/lib/rails_onboarding/session_manager.rb

@@ -0,0 +1,187 @@
+module RailsOnboarding
+  # Session Manager
+  # Handles browser refresh/navigation during onboarding
+  # Persists onboarding state to allow seamless resume
+  class SessionManager
+    SESSION_KEY = "rails_onboarding_session"
+    SESSION_TIMEOUT = 2.hours
+
+    class << self
+      # Initialize or restore onboarding session
+      #
+      # @param user [User] The current user
+      # @param session [ActionDispatch::Session] Rails session
+      # @return [Hash] Session data
+      def initialize_session(user, session)
+        session_data = restore_session(user, session)
+
+        # If no existing session or expired, create new one
+        if session_data.nil? || session_expired?(session_data)
+          session_data = create_session(user)
+        end
+
+        # Update last activity
+        session_data[:last_activity_at] = Time.current.iso8601
+        persist_session(user, session, session_data)
+
+        session_data
+      end
+
+      # Create a new onboarding session
+      def create_session(user)
+        {
+          user_id: user.id,
+          started_at: Time.current.iso8601,
+          last_activity_at: Time.current.iso8601,
+          current_step: user.onboarding_current_step,
+          step_history: [],
+          form_data: {},
+          progress: user.onboarding_progress,
+          session_id: SecureRandom.uuid
+        }
+      end
+
+      # Restore session from storage
+      def restore_session(user, session)
+        # Try session storage first
+        session_data = session[SESSION_KEY]
+        return parse_session_data(session_data) if session_data
+
+        # Try database storage if available
+        if user.respond_to?(:onboarding_session_data)
+          parse_session_data(user.onboarding_session_data)
+        end
+      end
+
+      # Persist session to storage
+      def persist_session(user, session, session_data)
+        # Store in Rails session
+        session[SESSION_KEY] = session_data.to_json
+
+        # Also persist to database if available
+        if user.respond_to?(:onboarding_session_data=)
+          user.onboarding_session_data = session_data.to_json
+          user.save(validate: false) rescue nil
+        end
+      end
+
+      # Update current step in session
+      def update_step(user, session, step_name)
+        session_data = initialize_session(user, session)
+
+        # Add previous step to history
+        if session_data[:current_step] && session_data[:current_step] != step_name
+          session_data[:step_history] ||= []
+          session_data[:step_history] << {
+            step: session_data[:current_step],
+            completed_at: Time.current.iso8601
+          }
+        end
+
+        session_data[:current_step] = step_name.to_s
+        session_data[:progress] = user.onboarding_progress
+        session_data[:last_activity_at] = Time.current.iso8601
+
+        persist_session(user, session, session_data)
+        session_data
+      end
+
+      # Save form data for a step
+      def save_step_data(user, session, step_name, data)
+        session_data = initialize_session(user, session)
+        session_data[:form_data] ||= {}
+        session_data[:form_data][step_name.to_sym] = {
+          data: data,
+          saved_at: Time.current.iso8601
+        }
+        persist_session(user, session, session_data)
+      end
+
+      # Get saved form data for a step
+      def get_step_data(user, session, step_name)
+        session_data = restore_session(user, session)
+        return nil unless session_data
+
+        step_data = session_data.dig(:form_data, step_name.to_sym)
+        step_data ? step_data[:data] : nil
+      end
+
+      # Clear step data
+      def clear_step_data(user, session, step_name)
+        session_data = initialize_session(user, session)
+        session_data[:form_data]&.delete(step_name.to_sym)
+        persist_session(user, session, session_data)
+      end
+
+      # Get step history
+      def step_history(user, session)
+        session_data = restore_session(user, session)
+        return [] unless session_data
+        session_data[:step_history] || []
+      end
+
+      # Get previous step from history
+      def previous_step(user, session)
+        history = step_history(user, session)
+        return nil if history.empty?
+        history.last[:step]
+      end
+
+      # Check if session is expired
+      def session_expired?(session_data)
+        return true unless session_data&.dig(:last_activity_at)
+
+        last_activity = Time.parse(session_data[:last_activity_at])
+        Time.current - last_activity > SESSION_TIMEOUT
+      rescue StandardError
+        true
+      end
+
+      # Clear session data
+      def clear_session(user, session)
+        session.delete(SESSION_KEY)
+
+        if user.respond_to?(:onboarding_session_data=)
+          user.onboarding_session_data = nil
+          user.save(validate: false) rescue nil
+        end
+      end
+
+      # Resume from saved session
+      def resume_session(user, session)
+        session_data = restore_session(user, session)
+
+        return nil if session_data.nil? || session_expired?(session_data)
+
+        # Sync user state with session
+        if user.onboarding_current_step != session_data[:current_step]
+          user.update(onboarding_current_step: session_data[:current_step]) rescue nil
+        end
+
+        session_data
+      end
+
+      # Get session ID for analytics tracking
+      def session_id(user, session)
+        session_data = restore_session(user, session)
+        session_data&.dig(:session_id) || SecureRandom.uuid
+      end
+
+      private
+
+      def parse_session_data(data)
+        return nil unless data
+
+        parsed = if data.is_a?(String)
+                   JSON.parse(data)
+        else
+                   data
+        end
+
+        parsed.deep_symbolize_keys
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/rails_onboarding/skip_logic.rb

@@ -0,0 +1,159 @@
+module RailsOnboarding
+  # Skip Logic Service
+  # Allows conditional step skipping based on user data and custom conditions
+  class SkipLogic
+    class << self
+      # Check if a step should be skipped for a user
+      #
+      # @param user [User] The current user
+      # @param step [Hash] The step configuration
+      # @return [Boolean] True if step should be skipped
+      def should_skip_step?(user, step)
+        return false unless step.is_a?(Hash)
+
+        # Check if step has skip conditions
+        skip_conditions = step[:skip_if]
+        return false unless skip_conditions
+
+        evaluate_conditions(user, skip_conditions)
+      end
+
+      # Evaluate skip conditions
+      #
+      # @param user [User] The user object
+      # @param conditions [Hash, Proc, Symbol] The conditions to evaluate
+      # @return [Boolean] True if conditions are met
+      def evaluate_conditions(user, conditions)
+        case conditions
+        when Proc
+          # Call proc with user
+          conditions.call(user)
+        when Symbol
+          # Call method on user
+          user.respond_to?(conditions) && user.send(conditions)
+        when Hash
+          # Evaluate hash conditions
+          evaluate_hash_conditions(user, conditions)
+        else
+          false
+        end
+      rescue StandardError => e
+        Rails.logger.error("Error evaluating skip conditions: #{e.message}")
+        false
+      end
+
+      # Get next unskipped step
+      #
+      # @param user [User] The current user
+      # @param current_step_name [Symbol] Current step name
+      # @return [Hash, nil] Next unskipped step
+      def next_unskipped_step(user, current_step_name)
+        current_index = RailsOnboarding.configuration.step_index(current_step_name)
+        return nil unless current_index
+
+        steps = RailsOnboarding.configuration.steps
+        remaining_steps = steps[(current_index + 1)..-1]
+
+        return nil unless remaining_steps
+
+        remaining_steps.find { |step| !should_skip_step?(user, step) }
+      end
+
+      # Get all steps that should be skipped for a user
+      #
+      # @param user [User] The current user
+      # @return [Array<Hash>] Array of steps to skip
+      def skippable_steps(user)
+        RailsOnboarding.configuration.steps.select do |step|
+          should_skip_step?(user, step)
+        end
+      end
+
+      # Get all steps that are required for a user
+      #
+      # @param user [User] The current user
+      # @return [Array<Hash>] Array of required steps
+      def required_steps(user)
+        RailsOnboarding.configuration.steps.reject do |step|
+          should_skip_step?(user, step)
+        end
+      end
+
+      # Calculate actual progress excluding skipped steps
+      #
+      # @param user [User] The current user
+      # @return [Integer] Progress percentage
+      def progress_excluding_skipped(user)
+        required = required_steps(user)
+        return 100 if required.empty?
+
+        current_index = required.find_index { |s| s[:name] == user.onboarding_current_step&.to_sym }
+        return 0 unless current_index
+
+        ((current_index + 1).to_f / required.size * 100).round
+      end
+
+      # Check if user should auto-skip to next step
+      #
+      # @param user [User] The current user
+      # @param step_name [Symbol] The step to check
+      # @return [Hash, nil] Next step if should auto-skip, nil otherwise
+      def auto_skip_step(user, step_name)
+        step = RailsOnboarding.configuration.step_by_name(step_name)
+        return nil unless step
+
+        if should_skip_step?(user, step) && step[:auto_skip]
+          next_unskipped_step(user, step_name)
+        end
+      end
+
+      private
+
+      # Evaluate hash-based conditions
+      def evaluate_hash_conditions(user, conditions)
+        operator = conditions[:operator] || :all
+
+        predicates = conditions.except(:operator).map do |key, value|
+          evaluate_predicate(user, key, value)
+        end
+
+        case operator
+        when :all
+          predicates.all?
+        when :any
+          predicates.any?
+        when :none
+          predicates.none?
+        else
+          predicates.all?
+        end
+      end
+
+      # Evaluate a single predicate
+      def evaluate_predicate(user, key, value)
+        case key
+        when :has_attribute
+          user.respond_to?(value) && user.send(value).present?
+        when :missing_attribute
+          !user.respond_to?(value) || user.send(value).blank?
+        when :attribute_equals
+          attribute, expected = value.is_a?(Hash) ? value.first : [ value, true ]
+          user.respond_to?(attribute) && user.send(attribute) == expected
+        when :attribute_not_equals
+          attribute, expected = value.is_a?(Hash) ? value.first : [ value, true ]
+          !user.respond_to?(attribute) || user.send(attribute) != expected
+        when :has_role
+          user.respond_to?(:has_role?) && user.has_role?(value)
+        when :custom
+          value.is_a?(Proc) ? value.call(user) : false
+        else
+          # Try to call as method on user
+          user.respond_to?(key) && user.send(key) == value
+        end
+      rescue StandardError => e
+        Rails.logger.error("Error evaluating predicate #{key}: #{e.message}")
+        false
+      end
+    end
+  end
+end

data/lib/rails_onboarding/turbo_compatibility.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Comprehensive Turbo and Stimulus compatibility for Rails 7+
+  # Provides seamless integration with Hotwire stack
+  module TurboCompatibility
+    extend ActiveSupport::Concern
+
+    included do
+      # Enable Turbo Stream responses
+      before_action :set_turbo_frame_headers, if: :turbo_frame_request?
+      after_action :turbo_stream_response_cleanup, if: :turbo_stream_request?
+    end
+
+    module ClassMethods
+      # Check if Turbo is available
+      def turbo_available?
+        defined?(Turbo)
+      end
+
+      # Check if Stimulus is available
+      def stimulus_available?
+        defined?(Stimulus)
+      end
+
+      # Configure Turbo integration options
+      def configure_turbo_integration(options = {})
+        @turbo_integration_options = {
+          enable_streams: true,
+          enable_native_navigation: true,
+          enable_morphing: options.fetch(:enable_morphing, false),
+          broadcast_updates: options.fetch(:broadcast_updates, true)
+        }.merge(options)
+      end
+
+      def turbo_integration_options
+        @turbo_integration_options || {}
+      end
+    end
+
+    # Turbo Frame helpers
+    def turbo_frame_request?
+      request.headers["Turbo-Frame"].present?
+    end
+
+    def turbo_frame_request_id
+      request.headers["Turbo-Frame"]
+    end
+
+    def turbo_stream_request?
+      request.format == :turbo_stream ||
+      request.headers["Accept"]&.include?("text/vnd.turbo-stream.html")
+    end
+
+    def turbo_native_app?
+      request.user_agent.to_s.match?(/Turbo Native/)
+    end
+
+    # Respond with appropriate format for Turbo
+    def respond_with_turbo(options = {}, &block)
+      respond_to do |format|
+        format.html do
+          if turbo_frame_request?
+            render options.merge(layout: false)
+          else
+            render options
+          end
+        end
+
+        format.turbo_stream do
+          if block_given?
+            yield
+          else
+            render turbo_stream: turbo_stream_actions(options)
+          end
+        end
+      end
+    end
+
+    # Generate Turbo Stream actions
+    def turbo_stream_actions(options = {})
+      actions = []
+
+      if options[:replace]
+        actions << turbo_stream.replace(options[:replace], partial: options[:partial])
+      end
+
+      if options[:update]
+        actions << turbo_stream.update(options[:update], partial: options[:partial])
+      end
+
+      if options[:append]
+        actions << turbo_stream.append(options[:append], partial: options[:partial])
+      end
+
+      if options[:prepend]
+        actions << turbo_stream.prepend(options[:prepend], partial: options[:partial])
+      end
+
+      if options[:remove]
+        actions << turbo_stream.remove(options[:remove])
+      end
+
+      actions
+    end
+
+    # Broadcast onboarding updates via Turbo Streams
+    def broadcast_onboarding_update(user, action, data = {})
+      return unless self.class.turbo_integration_options[:broadcast_updates]
+      return unless defined?(Turbo::StreamsChannel)
+
+      Turbo::StreamsChannel.broadcast_update_to(
+        "onboarding_#{user.id}",
+        target: "onboarding-container",
+        partial: "rails_onboarding/onboarding/#{action}",
+        locals: { user: user, data: data }
+      )
+    end
+
+    # Helper to safely navigate with Turbo
+    def turbo_navigate_to(path, options = {})
+      if turbo_stream_request?
+        turbo_stream.action(:redirect, path)
+      else
+        redirect_to path, options
+      end
+    end
+
+    # Turbo Morphing support (for Turbo 8+)
+    def enable_turbo_morphing
+      response.headers["X-Turbo-Morph"] = "true" if turbo_morph_supported?
+    end
+
+    def turbo_morph_supported?
+      return false unless defined?(Turbo)
+      # Check if Turbo version supports morphing (8.0+)
+      Turbo::VERSION.to_f >= 8.0 rescue false
+    end
+
+    # Stimulus controller data attributes
+    def stimulus_controller_data(controller_name, values = {})
+      data = { controller: "rails-onboarding--#{controller_name}" }
+
+      values.each do |key, value|
+        data[:"rails-onboarding--#{controller_name}-#{key}-value"] = value
+      end
+
+      data
+    end
+
+    # Generate Stimulus action attributes
+    def stimulus_action(event, controller, method, params = {})
+      action_string = "#{event}->rails-onboarding--#{controller}##{method}"
+
+      unless params.empty?
+        param_string = params.map { |k, v| "#{k}:#{v}" }.join(" ")
+        action_string += "(#{param_string})"
+      end
+
+      { action: action_string }
+    end
+
+    # Turbo Frame tag helper
+    def turbo_frame_tag_for_onboarding(id, **options, &block)
+      if defined?(turbo_frame_tag)
+        turbo_frame_tag(id, **options, &block)
+      else
+        content_tag(:turbo-frame, id: id, **options, &block)
+      end
+    end
+
+    # Turbo Stream tag helper
+    def turbo_stream_tag_for_onboarding(action, target, **options, &block)
+      if defined?(turbo_stream)
+        turbo_stream.send(action, target, **options, &block)
+      else
+        # Fallback for older versions
+        content_tag("turbo-stream", action: action, target: target, **options, &block)
+      end
+    end
+
+    # Handle Turbo Confirm dialogs
+    def turbo_confirm(message)
+      { 'data-turbo-confirm': message }
+    end
+
+    # Handle Turbo Method overrides
+    def turbo_method(method)
+      { 'data-turbo-method': method }
+    end
+
+    # Disable Turbo for specific links/forms
+    def disable_turbo
+      { 'data-turbo': "false" }
+    end
+
+    # Enable Turbo permanent elements
+    def turbo_permanent
+      { 'data-turbo-permanent': "true" }
+    end
+
+    private
+
+    def set_turbo_frame_headers
+      response.headers["Turbo-Frame"] = turbo_frame_request_id if turbo_frame_request_id
+    end
+
+    def turbo_stream_response_cleanup
+      # Ensure proper content type for Turbo Stream responses
+      response.content_type = "text/vnd.turbo-stream.html" if turbo_stream_request?
+    end
+  end
+
+  # Railtie for Turbo/Stimulus integration
+  class TurboRailtie < Rails::Railtie
+    initializer "rails_onboarding.turbo_compatibility", after: :load_config_initializers do
+      ActiveSupport.on_load(:action_controller) do
+        if defined?(Turbo) || defined?(Stimulus)
+          Rails.logger.info "RailsOnboarding: Turbo/Stimulus compatibility enabled"
+
+          # Add Turbo Stream MIME type if not already registered
+          unless Mime::Type.lookup_by_extension(:turbo_stream)
+            Mime::Type.register "text/vnd.turbo-stream.html", :turbo_stream
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_onboarding/version.rb

@@ -0,0 +1,3 @@
+module RailsOnboarding
+  VERSION = "0.6.1"
+end

data/lib/rails_onboarding.rb

@@ -0,0 +1,44 @@
+require "pagy"
+
+require "rails_onboarding/version"
+require "rails_onboarding/engine"
+require "rails_onboarding/deprecation"
+require "rails_onboarding/current"
+require "rails_onboarding/configuration_errors"
+require "rails_onboarding/configuration_validator"
+require "rails_onboarding/configuration"
+require "rails_onboarding/requirements_validator"
+require "rails_onboarding/controller_helpers"
+require "rails_onboarding/responsive_helper"
+require "rails_onboarding/error_recovery"
+require "rails_onboarding/session_manager"
+require "rails_onboarding/skip_logic"
+require "rails_onboarding/multi_tenant"
+require "rails_onboarding/devise_integration"
+require "rails_onboarding/turbo_compatibility"
+require "rails_onboarding/api_mode"
+require "rails_onboarding/background_jobs"
+require "rails_onboarding/caching"
+require "rails_onboarding/lazy_loading"
+require "rails_onboarding/cdn_support"
+require "rails_onboarding/backfill"
+
+module RailsOnboarding
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  def self.reset_configuration!
+    self.configuration = Configuration.new
+  end
+
+  # Default configuration
+  self.configuration = Configuration.new
+end