rails_onboarding 0.6.1

data/lib/rails_onboarding/configuration/tooltips.rb

@@ -0,0 +1,32 @@
+module RailsOnboarding
+  class Configuration
+    # Feature tooltip configuration.
+    module Tooltips
+      def enable_tooltips
+        tenant_override(:enable_tooltips, @enable_tooltips)
+      end
+
+      attr_writer :enable_tooltips
+
+      def feature_tooltips
+        tenant_override(:feature_tooltips, @feature_tooltips)
+      end
+
+      attr_writer :feature_tooltips
+
+      private
+
+      def initialize_tooltips
+        @enable_tooltips = true
+
+        @feature_tooltips = {
+          "getting_started" => {
+            text: "Click here to get started!",
+            delay: 1000,
+            position: "bottom"
+          }
+        }
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration.rb

@@ -0,0 +1,133 @@
+require_relative "configuration_validator"
+require_relative "configuration/steps"
+require_relative "configuration/milestones"
+require_relative "configuration/tooltips"
+require_relative "configuration/analytics"
+require_relative "configuration/ab_testing"
+require_relative "configuration/personalization"
+require_relative "configuration/progressive_disclosure"
+require_relative "configuration/integrations"
+require_relative "configuration/rate_limiting"
+require_relative "configuration/templates"
+
+module RailsOnboarding
+  # Every reader/writer here is part of this gem's public configuration DSL
+  # (host apps set these in a RailsOnboarding.configure block), so none of
+  # them can change shape without breaking every existing installation. The
+  # ~40 settings are grouped by feature into the modules under
+  # configuration/ - each one owns its own defaults and any logic specific
+  # to it, so a change to (say) A/B testing only touches
+  # configuration/ab_testing.rb instead of this whole file. What's left
+  # here is identity/branding settings with no logic of their own, plus the
+  # infrastructure the feature modules share (tenant overrides, the derived-
+  # lookup cache, and the validator).
+  class Configuration
+    include Steps
+    include Milestones
+    include Tooltips
+    include Analytics
+    include AbTesting
+    include Personalization
+    include ProgressiveDisclosure
+    include Integrations
+    include RateLimiting
+    include Templates
+
+    attr_accessor :user_class_name,
+                  :include_host_styles,
+                  :redirect_after_completion,
+                  :redirect_after_skip,
+                  :custom_css_path,
+                  :custom_js_path,
+                  :welcome_heading,
+                  :welcome_subheading,
+                  :welcome_features,
+                  :admin_user_search
+
+    def initialize
+      @user_class_name = "User"
+      @include_host_styles = true  # Default to including host app css
+      @redirect_after_completion = :root_path
+      @redirect_after_skip = :root_path
+      @welcome_heading = "We're excited to have you here!"
+      @welcome_subheading = "Now, let's take a few moments to get you set up and familiar with a few things you need to know to get started."
+      @welcome_features = [
+        { icon: "👤", text: "Set up your profile" },
+        { icon: "📝", text: "Create your first item" },
+        { icon: "🔍", text: "Explore key features" }
+      ]
+
+      # Optional override for the admin User Management search box. The
+      # built-in search is plain SQL, which can't see through an encrypted
+      # email column - a host app that encrypts email and still wants partial
+      # matching has to supply the strategy itself. Receives the already
+      # status/step-filtered scope and the raw term, and must return a
+      # relation (not an array) so sorting and pagination still apply.
+      @admin_user_search = nil
+
+      initialize_steps
+      initialize_milestones
+      initialize_tooltips
+      initialize_analytics
+      initialize_ab_testing
+      initialize_personalization
+      initialize_progressive_disclosure
+      initialize_integrations
+      initialize_rate_limiting
+      initialize_templates
+    end
+
+    # Validate the current configuration
+    # @raise [ConfigurationError] if any validation fails
+    def validate!
+      validator.validate!
+    end
+
+    # Check if the configuration is valid without raising
+    # @return [Boolean] true if valid, false otherwise
+    def valid?
+      validator.valid?
+    end
+
+    # Get the validator instance for this configuration
+    # @return [ConfigurationValidator]
+    def validator
+      @validator ||= ConfigurationValidator.new(self)
+    end
+
+    # Get validation errors without raising
+    # @return [Array<StandardError>] array of validation errors
+    def validation_errors
+      validator.errors
+    end
+
+    def user_class
+      @user_class ||= @user_class_name.constantize
+    end
+
+    # Clear all cached lookups - call this when configuration changes
+    def clear_cache!
+      @user_class = nil
+      @total_steps = nil
+      @step_by_name_cache = nil
+      @step_index_cache = nil
+      @milestone_by_key_cache = nil
+      @milestones_for_trigger_cache = nil
+      @validator = nil
+    end
+
+    private
+
+    # Reads a per-request tenant override for +key+, set by
+    # MultiTenant.with_tenant_configuration via RailsOnboarding::Current.
+    # Falls back to +default+ (the process-wide value) when no override is
+    # active for +key+, distinguishing an explicit `false` override from "no
+    # override at all".
+    def tenant_override(key, default)
+      overrides = RailsOnboarding::Current.tenant_overrides
+      return default unless overrides&.key?(key)
+
+      overrides[key]
+    end
+  end
+end

data/lib/rails_onboarding/configuration_errors.rb

@@ -0,0 +1,19 @@
+module RailsOnboarding
+  # Base error class for all configuration errors
+  class ConfigurationError < StandardError; end
+
+  # Raised when step configuration is invalid
+  class InvalidStepError < ConfigurationError; end
+
+  # Raised when milestone configuration is invalid
+  class InvalidMilestoneError < ConfigurationError; end
+
+  # Raised when redirect path configuration is invalid
+  class InvalidRedirectPathError < ConfigurationError; end
+
+  # Raised when a configuration value has the wrong type
+  class InvalidTypeError < ConfigurationError; end
+
+  # Raised when a required configuration option is missing
+  class MissingRequiredOptionError < ConfigurationError; end
+end

data/lib/rails_onboarding/configuration_validator.rb

@@ -0,0 +1,477 @@
+require_relative "configuration_errors"
+
+module RailsOnboarding
+  # Validates RailsOnboarding configuration to ensure all settings are valid
+  class ConfigurationValidator
+    VALID_TRIGGERS = [ :onboarding_step_completed, :onboarding_completed, :tooltip_shown,
+                      :tooltip_clicked, :custom ].freeze
+    VALID_REDIRECT_TYPES = [ Symbol, String, Proc ].freeze
+    VALID_ONBOARDING_REQUIREMENTS = [ :new_users, :all_users, Proc ].freeze
+    VALID_API_AUTH_METHODS = [ :token, :session, :custom ].freeze
+    VALID_REVEAL_CONDITIONS = [ :time_based, :action_based, :step_based, :milestone_based, :engagement_based ].freeze
+    NAME_FORMAT = /\A[a-z_][a-z0-9_]*\z/i
+
+    attr_reader :config, :errors
+
+    def initialize(config)
+      @config = config
+      @errors = []
+    end
+
+    # Validate all configuration options
+    # @raise [ConfigurationError] if any validation fails
+    def validate!
+      validate_required_options
+      validate_types
+      validate_steps
+      validate_milestones
+      validate_redirect_paths
+      validate_feature_tooltips
+      validate_ab_tests
+      validate_personalized_flows
+      validate_progressive_features
+      validate_mailer_config
+
+      raise ConfigurationError, error_message unless errors.empty?
+    end
+
+    # Validate without raising exceptions
+    # @return [Boolean] true if valid, false otherwise
+    def valid?
+      validate!
+      true
+    rescue ConfigurationError
+      false
+    end
+
+    private
+
+    def validate_required_options
+      validate_present(:user_class_name, "User class name is required")
+      validate_present(:steps, "At least one step must be defined")
+    end
+
+    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(: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")
+      validate_type(:steps, [ Array ], "steps must be an Array")
+      validate_type(:milestones, [ Array ], "milestones must be an Array")
+      validate_type(:feature_tooltips, [ Hash ], "feature_tooltips must be a Hash")
+
+      # Numeric validations
+      if config.analytics_data_retention_days
+        validate_type(:analytics_data_retention_days, [ Integer ], "analytics_data_retention_days must be an Integer")
+        validate_positive(:analytics_data_retention_days, "analytics_data_retention_days must be positive")
+      end
+
+      if config.analytics_session_timeout_minutes
+        validate_type(:analytics_session_timeout_minutes, [ Integer ], "analytics_session_timeout_minutes must be an Integer")
+        validate_positive(:analytics_session_timeout_minutes, "analytics_session_timeout_minutes must be positive")
+      end
+
+      # Validate onboarding_required_for
+      unless VALID_ONBOARDING_REQUIREMENTS.include?(config.onboarding_required_for) ||
+             config.onboarding_required_for.is_a?(Proc)
+        errors << InvalidTypeError.new(
+          "onboarding_required_for must be :new_users, :all_users, or a Proc"
+        )
+      end
+
+      # API mode validations
+      if config.api_mode_enabled
+        validate_type(:api_mode_enabled, [ TrueClass, FalseClass ], "api_mode_enabled must be a Boolean")
+        unless VALID_API_AUTH_METHODS.include?(config.api_authentication_method)
+          errors << InvalidTypeError.new(
+            "api_authentication_method must be one of: #{VALID_API_AUTH_METHODS.join(', ')}"
+          )
+        end
+      end
+    end
+
+    def validate_steps
+      return unless config.steps.is_a?(Array)
+
+      if config.steps.empty?
+        errors << InvalidStepError.new("At least one step must be defined")
+        return
+      end
+
+      validate_named_collection(
+        config.steps,
+        error_class: InvalidStepError,
+        label: "Step",
+        identifier_field: :name,
+        identifier_type: [ Symbol, String ],
+        duplicate_label: "step name",
+        format_description: "Use alphanumeric characters and underscores only, starting with a letter or underscore",
+        fields: [
+          { name: :title, type: String },
+          { name: :icon, type: String },
+          { name: :skippable, type: [ TrueClass, FalseClass ] },
+          { name: :path, type: [ Symbol, String, Proc ] },
+          { name: :complete_if, type: Proc }
+        ]
+      ) do |step, name|
+        # A :path step with no :complete_if and no skippable: true can only
+        # advance via an explicit advance_onboarding! call in the host
+        # controller - which this validator can't see. Warn rather than error,
+        # but make the trap visible: if that call is missing, the user gets
+        # redirected to the step's page forever.
+        if step.is_a?(Hash) && step[:path] && !step[:complete_if] && step[:skippable] != true
+          Rails.logger.warn(
+            "RailsOnboarding: step '#{name}' has a :path but no :complete_if and is not skippable. " \
+            "Make sure the host controller calls advance_onboarding!(:#{name}), " \
+            "or users cannot progress past this step."
+          )
+        end
+      end
+    end
+
+    def validate_milestones
+      return unless config.enable_milestones
+      return unless config.milestones.is_a?(Array)
+      return if config.milestones.empty? # Empty milestones array is valid
+
+      validate_named_collection(
+        config.milestones,
+        error_class: InvalidMilestoneError,
+        label: "Milestone",
+        identifier_field: :key,
+        duplicate_label: "milestone key",
+        format_description: "Use alphanumeric characters and underscores only",
+        fields: [
+          { name: :trigger, required: true },
+          { name: :points, type: Integer },
+          { name: :title, type: String },
+          { name: :description, type: String },
+          { name: :conditions, type: Hash }
+        ]
+      ) do |milestone, key|
+        # Cross-field and value-range checks that a generic field schema
+        # can't express - kept bespoke per collection.
+        if milestone[:trigger] && !VALID_TRIGGERS.include?(milestone[:trigger].to_sym)
+          errors << InvalidMilestoneError.new(
+            "Milestone '#{key}' has invalid trigger '#{milestone[:trigger]}'. " \
+            "Valid triggers: #{VALID_TRIGGERS.join(', ')}"
+          )
+        end
+
+        if milestone[:points].is_a?(Integer) && milestone[:points].negative?
+          errors << InvalidMilestoneError.new(
+            "Milestone '#{key}' has negative points. Points must be non-negative"
+          )
+        end
+
+        if milestone[:conditions].is_a?(Hash) && milestone[:conditions][:step]
+          step_name = milestone[:conditions][:step]
+          unless config.step_by_name(step_name)
+            errors << InvalidMilestoneError.new(
+              "Milestone '#{key}' references undefined step '#{step_name}' in conditions"
+            )
+          end
+        end
+      end
+    end
+
+    def validate_redirect_paths
+      validate_redirect_path(:redirect_after_completion, config.redirect_after_completion)
+      validate_redirect_path(:redirect_after_skip, config.redirect_after_skip)
+    end
+
+    def validate_redirect_path(field_name, value)
+      return if value.nil?
+
+      unless VALID_REDIRECT_TYPES.any? { |type| value.is_a?(type) }
+        errors << InvalidRedirectPathError.new(
+          "#{field_name} must be a Symbol, String, or Proc, got #{value.class}"
+        )
+        return
+      end
+
+      # If it's a symbol, validate it looks like a valid path helper
+      if value.is_a?(Symbol) && !value.to_s.end_with?("_path", "_url")
+        errors << InvalidRedirectPathError.new(
+          "#{field_name} symbol '#{value}' should end with '_path' or '_url' (e.g., :root_path, :dashboard_path)"
+        )
+      end
+
+      # If it's a string, validate it starts with /
+      if value.is_a?(String) && !value.start_with?("/")
+        errors << InvalidRedirectPathError.new(
+          "#{field_name} string '#{value}' should be an absolute path starting with '/'"
+        )
+      end
+    end
+
+    def validate_feature_tooltips
+      return unless config.enable_tooltips
+      return unless config.feature_tooltips.is_a?(Hash)
+
+      config.feature_tooltips.each do |key, tooltip|
+        unless tooltip.is_a?(Hash)
+          errors << InvalidTypeError.new(
+            "Tooltip '#{key}' must be a Hash, got #{tooltip.class}"
+          )
+          next
+        end
+
+        # :text has a combined required+type message ("must have a :text
+        # field of type String"), unlike every other field here, so it's
+        # kept as its own check rather than going through validate_item_fields.
+        unless tooltip[:text].is_a?(String)
+          errors << InvalidTypeError.new(
+            "Tooltip '#{key}' must have a :text field of type String"
+          )
+        end
+
+        validate_item_fields(tooltip, "Tooltip '#{key}'", InvalidTypeError, [
+          { name: :delay, type: Integer }
+        ])
+
+        if tooltip[:position]
+          valid_positions = %w[top bottom left right]
+          unless valid_positions.include?(tooltip[:position].to_s)
+            errors << InvalidTypeError.new(
+              "Tooltip '#{key}' has invalid :position '#{tooltip[:position]}'. " \
+              "Valid positions: #{valid_positions.join(', ')}"
+            )
+          end
+        end
+      end
+    end
+
+    def validate_ab_tests
+      return unless config.enable_ab_testing
+      return unless config.ab_tests.is_a?(Hash)
+
+      config.ab_tests.each do |test_name, test_config|
+        unless test_config.is_a?(Hash)
+          errors << InvalidTypeError.new(
+            "A/B test '#{test_name}' must be a Hash, got #{test_config.class}"
+          )
+          next
+        end
+
+        # Validate variants exist
+        unless test_config[:variants].is_a?(Array)
+          errors << InvalidTypeError.new(
+            "A/B test '#{test_name}' must have a :variants array"
+          )
+          next
+        end
+
+        if test_config[:variants].empty?
+          errors << InvalidTypeError.new(
+            "A/B test '#{test_name}' must have at least one variant"
+          )
+        end
+      end
+    end
+
+    def validate_personalized_flows
+      return unless config.personalization_enabled
+      return unless config.personalized_flows.is_a?(Hash)
+
+      config.personalized_flows.each do |user_type, steps|
+        unless steps.is_a?(Array)
+          errors << InvalidTypeError.new(
+            "Personalized flow for '#{user_type}' must be an Array, got #{steps.class}"
+          )
+          next
+        end
+
+        # Validate each step follows the same rules as regular steps
+        steps.each_with_index do |step, index|
+          unless step.is_a?(Hash)
+            errors << InvalidStepError.new(
+              "Personalized flow '#{user_type}' step at index #{index} must be a Hash"
+            )
+          end
+        end
+      end
+    end
+
+    def validate_progressive_features
+      return unless config.progressive_disclosure_enabled
+      return unless config.progressive_features.is_a?(Array)
+
+      validate_named_collection(
+        config.progressive_features,
+        error_class: InvalidTypeError,
+        label: "Progressive feature",
+        identifier_field: :key
+      ) do |feature, key|
+        next unless feature[:reveal_condition]
+
+        unless VALID_REVEAL_CONDITIONS.include?(feature[:reveal_condition])
+          errors << InvalidTypeError.new(
+            "Progressive feature '#{key}' has invalid :reveal_condition. " \
+            "Valid conditions: #{VALID_REVEAL_CONDITIONS.join(', ')}"
+          )
+        end
+
+        # Validate time_based features have delay
+        if feature[:reveal_condition] == :time_based && !feature[:delay].is_a?(Integer)
+          errors << InvalidTypeError.new(
+            "Progressive feature '#{key}' with :time_based condition must have :delay (Integer in seconds)"
+          )
+        end
+
+        # Validate step_based features reference valid steps
+        if feature[:reveal_condition] == :step_based && feature[:after_step]
+          unless config.step_by_name(feature[:after_step])
+            errors << InvalidTypeError.new(
+              "Progressive feature '#{key}' references undefined step '#{feature[:after_step]}'"
+            )
+          end
+        end
+      end
+    end
+
+    def validate_mailer_config
+      return unless config.background_jobs_enabled
+
+      if config.mailer_from && !config.mailer_from.is_a?(String)
+        errors << InvalidTypeError.new(
+          "mailer_from must be a String, got #{config.mailer_from.class}"
+        )
+      end
+
+      # Validate email format
+      if config.mailer_from.is_a?(String) && !valid_email_format?(config.mailer_from)
+        errors << InvalidTypeError.new(
+          "mailer_from '#{config.mailer_from}' is not a valid email address"
+        )
+      end
+    end
+
+    # Helper methods
+
+    def validate_present(field, message)
+      value = config.send(field)
+      if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        errors << MissingRequiredOptionError.new(message)
+      end
+    end
+
+    def validate_type(field, valid_types, message)
+      value = config.send(field)
+      return if value.nil? # nil is valid unless validate_present says otherwise
+
+      unless valid_types.any? { |type| value.is_a?(type) }
+        errors << InvalidTypeError.new(message)
+      end
+    end
+
+    def validate_positive(field, message)
+      value = config.send(field)
+      if value && value.is_a?(Integer) && value <= 0
+        errors << InvalidTypeError.new(message)
+      end
+    end
+
+    # Shared engine behind validate_steps/validate_milestones/
+    # validate_progressive_features: they all iterate an Array of Hashes,
+    # each identified by one field (:name/:key), and each with its own mix
+    # of required/optional fields - only the identifier's uniqueness/format
+    # rules and the field list differ, plus whatever bespoke cross-field
+    # checks the caller needs (yielded per item).
+    #
+    # @param items [Array] the configured collection (steps, milestones, ...)
+    # @param error_class [Class] error class to raise for problems found
+    # @param label [String] human label used in messages, e.g. "Step"
+    # @param identifier_field [Symbol] the field that identifies each item
+    # @param identifier_type [Array<Class>, nil] allowed types for the
+    #   identifier's value, if it should be type-checked
+    # @param duplicate_label [String, nil] enables a uniqueness check on the
+    #   identifier, e.g. "step name"
+    # @param format_description [String, nil] enables a name-format check on
+    #   the identifier (alphanumeric/underscore), described in the message
+    # @param fields [Array<Hash>] field schema: {name:, type:, required:}
+    # @yield [item, identifier] for bespoke, collection-specific checks once
+    #   the item has passed the structural checks above
+    def validate_named_collection(items, error_class:, label:, identifier_field:, identifier_type: nil,
+                                   duplicate_label: nil, format_description: nil, fields: [])
+      return unless items.is_a?(Array)
+
+      seen_identifiers = []
+
+      items.each_with_index do |item, index|
+        unless item.is_a?(Hash)
+          errors << error_class.new("#{label} at index #{index} must be a Hash")
+          next
+        end
+
+        identifier = item[identifier_field]
+        unless identifier
+          errors << error_class.new("#{label} at index #{index} is missing required :#{identifier_field} field")
+          next
+        end
+
+        if identifier_type && !identifier_type.any? { |type| identifier.is_a?(type) }
+          errors << error_class.new(
+            "#{label} at index #{index} has invalid #{identifier_field} type. " \
+            "Must be #{identifier_type.map(&:name).join(' or ')}, got #{identifier.class}"
+          )
+          next
+        end
+
+        item_label = "#{label} '#{identifier}'"
+
+        if duplicate_label
+          if seen_identifiers.include?(identifier.to_sym)
+            errors << error_class.new("Duplicate #{duplicate_label} found: '#{identifier}'")
+          end
+          seen_identifiers << identifier.to_sym
+        end
+
+        if format_description && !identifier.to_s.match?(NAME_FORMAT)
+          errors << error_class.new("#{item_label} has invalid format. #{format_description}")
+        end
+
+        validate_item_fields(item, item_label, error_class, fields)
+
+        yield item, identifier if block_given?
+      end
+    end
+
+    # Checks a schema of {name:, type:, required:} field rules against a
+    # single Hash item, reporting a missing-required-field or wrong-type
+    # error per field as appropriate.
+    def validate_item_fields(item, item_label, error_class, fields)
+      fields.each do |field|
+        value = item[field[:name]]
+
+        if field[:required] && value.nil?
+          errors << error_class.new("#{item_label} is missing required :#{field[:name]} field")
+          next
+        end
+
+        next if value.nil?
+
+        expected_types = Array(field[:type])
+        next if expected_types.empty?
+
+        unless expected_types.any? { |type| value.is_a?(type) }
+          errors << error_class.new(
+            "#{item_label} has invalid :#{field[:name]} type. " \
+            "Expected #{expected_types.map(&:name).join(' or ')}, got #{value.class}"
+          )
+        end
+      end
+    end
+
+    def valid_email_format?(email)
+      email.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+    end
+
+    def error_message
+      header = "Configuration validation failed with #{errors.size} error(s):"
+      error_list = errors.map.with_index { |error, i| "  #{i + 1}. #{error.message}" }.join("\n")
+      "#{header}\n#{error_list}"
+    end
+  end
+end