rails_onboarding 0.6.1

data/lib/rails_onboarding/cdn_support.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module RailsOnboarding
+  # CDN Support module for serving assets from a CDN
+  #
+  # This module provides helpers and configuration for serving
+  # onboarding assets (JavaScript, CSS, images) from a CDN
+  # to improve performance through better caching and geographic distribution
+  module CdnSupport
+    extend ActiveSupport::Concern
+
+    # Get the CDN host URL
+    #
+    # @return [String, nil] CDN host URL or nil if not configured
+    def self.cdn_host
+      @cdn_host ||= begin
+        # Check Rails configuration first
+        if defined?(Rails.application) && Rails.application.config.action_controller.asset_host
+          Rails.application.config.action_controller.asset_host
+        else
+          ENV["RAILS_ONBOARDING_CDN_HOST"]
+        end
+      end
+    end
+
+    # Set the CDN host URL
+    #
+    # @param host [String] CDN host URL
+    def self.cdn_host=(host)
+      @cdn_host = host
+    end
+
+    # Check if CDN is enabled
+    #
+    # @return [Boolean]
+    def self.cdn_enabled?
+      cdn_host.present? && !Rails.env.development?
+    end
+
+    # Get asset URL with CDN support
+    #
+    # @param asset_path [String] The asset path (e.g., 'rails_onboarding/application.css')
+    # @param asset_type [Symbol] Asset type (:stylesheet, :javascript, :image)
+    # @return [String] Full URL to the asset
+    def self.cdn_asset_url(asset_path, asset_type: :stylesheet)
+      if cdn_enabled?
+        case asset_type
+        when :stylesheet
+          "#{cdn_host}/assets/#{asset_path}"
+        when :javascript
+          "#{cdn_host}/assets/#{asset_path}"
+        when :image
+          "#{cdn_host}/assets/#{asset_path}"
+        else
+          "#{cdn_host}/assets/#{asset_path}"
+        end
+      else
+        # Fall back to local asset path
+        "/assets/#{asset_path}"
+      end
+    end
+
+    # Preload critical onboarding assets
+    #
+    # @return [Array<Hash>] Array of asset preload hints
+    def self.preload_assets
+      [
+        {
+          href: cdn_asset_url("rails_onboarding/application.css", asset_type: :stylesheet),
+          as: "style",
+          type: "text/css"
+        },
+        {
+          href: cdn_asset_url("rails_onboarding/application.js", asset_type: :javascript),
+          as: "script",
+          type: "text/javascript"
+        }
+      ]
+    end
+
+    # Generate cache-busting URL with versioning
+    #
+    # @param asset_path [String] The asset path
+    # @param version [String] Asset version (defaults to gem version)
+    # @param asset_type [Symbol] Asset type (:stylesheet, :javascript, :image)
+    # @return [String] URL with version parameter
+    def self.versioned_asset_url(asset_path, version: nil, asset_type: :stylesheet)
+      version ||= RailsOnboarding::VERSION
+      url = cdn_asset_url(asset_path, asset_type: asset_type)
+      "#{url}?v=#{version}"
+    end
+
+    # Make these methods available as class methods when included
+    class_methods do
+      delegate :cdn_host, :cdn_host=, :cdn_enabled?, :cdn_asset_url,
+               :preload_assets, :versioned_asset_url, to: CdnSupport
+    end
+
+    module_function
+
+    # Helper method for view templates
+    # Generates link tags with CDN support and preload hints
+    #
+    # @param asset_path [String] Asset path
+    # @param options [Hash] Additional options
+    # @return [String] HTML link tag
+    def stylesheet_link_tag_with_cdn(asset_path, **options)
+      url = CdnSupport.versioned_asset_url(asset_path, asset_type: :stylesheet)
+
+      preload = options.delete(:preload)
+      crossorigin = options.delete(:crossorigin)
+
+      tag_options = {
+        rel: "stylesheet",
+        href: url
+      }.merge(options)
+
+      tag_options[:crossorigin] = crossorigin if crossorigin
+
+      tags = [ "<link #{cdn_tag_attributes(tag_options)} />" ]
+
+      if preload
+        tags.unshift("<link #{cdn_tag_attributes(rel: 'preload', href: url, as: 'style')} />")
+      end
+
+      tags.join("\n").html_safe
+    end
+
+    # Helper method for JavaScript tags with CDN support
+    #
+    # @param asset_path [String] Asset path
+    # @param options [Hash] Additional options
+    # @return [String] HTML script tag
+    def javascript_include_tag_with_cdn(asset_path, **options)
+      url = CdnSupport.versioned_asset_url(asset_path, asset_type: :javascript)
+
+      preload = options.delete(:preload)
+      defer = options.delete(:defer) { true } # Default to defer
+      async = options.delete(:async)
+
+      tag_options = {
+        src: url,
+        type: "text/javascript"
+      }.merge(options)
+
+      tag_options[:defer] = "defer" if defer && !async
+      tag_options[:async] = "async" if async
+
+      tags = [ "<script #{cdn_tag_attributes(tag_options)}></script>" ]
+
+      if preload
+        tags.unshift("<link #{cdn_tag_attributes(rel: 'preload', href: url, as: 'script')} />")
+      end
+
+      tags.join("\n").html_safe
+    end
+
+    # Generate resource hints for DNS prefetch and preconnect
+    #
+    # @return [String] HTML meta tags for resource hints
+    def cdn_resource_hints
+      return "" unless CdnSupport.cdn_enabled?
+
+      cdn_host = ERB::Util.html_escape(CdnSupport.cdn_host)
+      <<~HTML.html_safe
+        <!-- DNS Prefetch and Preconnect for CDN -->
+        <link rel="dns-prefetch" href="#{cdn_host}" />
+        <link rel="preconnect" href="#{cdn_host}" crossorigin />
+      HTML
+    end
+
+    # Render tag attributes with every value HTML-escaped, so a CDN host or
+    # asset path containing a quote or angle bracket can't break out of the
+    # attribute it's placed in. Used in place of ActionView's tag helpers
+    # because these methods are also called as CdnSupport module functions,
+    # outside any view context where `tag`/`content_tag` would be available.
+    def cdn_tag_attributes(attributes)
+      attributes.map { |key, value| "#{key}=\"#{ERB::Util.html_escape(value)}\"" }.join(" ")
+    end
+
+    # Configure CDN headers for optimal caching
+    #
+    # @param max_age [Integer] Cache max age in seconds (default: 1 year)
+    # @return [Hash] Headers for CDN caching
+    def cdn_cache_headers(max_age: 31_536_000)
+      {
+        "Cache-Control" => "public, max-age=#{max_age}, immutable",
+        "Expires" => max_age.seconds.from_now.httpdate,
+        "Vary" => "Accept-Encoding"
+      }
+    end
+  end
+end
+
+# Extend ActionView helpers if in Rails context
+if defined?(ActionView::Base)
+  ActionView::Base.class_eval do
+    include RailsOnboarding::CdnSupport
+  end
+end

data/lib/rails_onboarding/configuration/ab_testing.rb

@@ -0,0 +1,24 @@
+module RailsOnboarding
+  class Configuration
+    # A/B testing configuration.
+    module AbTesting
+      attr_accessor :enable_ab_testing, :ab_tests
+
+      # Get a specific A/B test configuration
+      #
+      # @param test_name [Symbol, String] The name of the test
+      # @return [Hash, nil] The test configuration or nil
+      def ab_test(test_name)
+        return nil unless enable_ab_testing
+        ab_tests[test_name.to_sym]
+      end
+
+      private
+
+      def initialize_ab_testing
+        @enable_ab_testing = false
+        @ab_tests = {}
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration/analytics.rb

@@ -0,0 +1,29 @@
+module RailsOnboarding
+  class Configuration
+    # Analytics tracking configuration.
+    module Analytics
+      attr_accessor :enable_analytics, :analytics_session_timeout_minutes
+      attr_reader :analytics_data_retention_days, :analytics_retention_days
+
+      # Keep analytics_retention_days in sync with analytics_data_retention_days
+      def analytics_retention_days=(value)
+        @analytics_retention_days = value
+        @analytics_data_retention_days = value
+      end
+
+      def analytics_data_retention_days=(value)
+        @analytics_data_retention_days = value
+        @analytics_retention_days = value
+      end
+
+      private
+
+      def initialize_analytics
+        @enable_analytics = true
+        @analytics_data_retention_days = 365 # Keep analytics data for 1 year
+        @analytics_retention_days = 365 # Alias for analytics_data_retention_days
+        @analytics_session_timeout_minutes = 30 # Consider session ended after 30 minutes of inactivity
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration/integrations.rb

@@ -0,0 +1,31 @@
+module RailsOnboarding
+  class Configuration
+    # Integration & compatibility options (Devise, Turbo, API mode,
+    # background jobs, mailer).
+    module Integrations
+      attr_accessor :devise_integration_enabled,
+                    :redirect_unconfirmed_to_onboarding,
+                    :turbo_streams_enabled,
+                    :turbo_morphing_enabled,
+                    :api_mode_enabled,
+                    :api_authentication_method,
+                    :background_jobs_enabled,
+                    :background_jobs_queue,
+                    :mailer_from
+
+      private
+
+      def initialize_integrations
+        @devise_integration_enabled = true
+        @redirect_unconfirmed_to_onboarding = false
+        @turbo_streams_enabled = true
+        @turbo_morphing_enabled = false
+        @api_mode_enabled = false
+        @api_authentication_method = :token
+        @background_jobs_enabled = false
+        @background_jobs_queue = :default
+        @mailer_from = "noreply@example.com"
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration/milestones.rb

@@ -0,0 +1,92 @@
+module RailsOnboarding
+  class Configuration
+    # Milestone configuration, lookups, and trigger matching.
+    module Milestones
+      def enable_milestones
+        tenant_override(:enable_milestones, @enable_milestones)
+      end
+
+      attr_writer :enable_milestones
+
+      def milestones
+        tenant_override(:milestones, @milestones)
+      end
+
+      # Override setter to clear cache when configuration changes
+      def milestones=(value)
+        clear_cache!
+        @milestones = value
+      end
+
+      def milestone_by_key(key)
+        return nil if key.nil?
+
+        @milestone_by_key_cache ||= {}
+        @milestone_by_key_cache[key.to_sym] ||= milestones.find { |m| m[:key].to_sym == key.to_sym }
+      end
+
+      def milestones_for_trigger(trigger, conditions = {})
+        cache_key = [ trigger, conditions ].hash
+        @milestones_for_trigger_cache ||= {}
+        @milestones_for_trigger_cache[cache_key] ||= milestones.select do |milestone|
+          # Match on trigger
+          next false unless milestone[:trigger] == trigger.to_sym
+
+          # If no conditions are provided, match all milestones with this trigger
+          next true if conditions.empty?
+
+          # If milestone has no conditions, but we're providing conditions, don't match
+          next false if milestone[:conditions].nil?
+
+          # Both have conditions, check if they match
+          conditions_match?(milestone[:conditions], conditions)
+        end
+      end
+
+      private
+
+      def conditions_match?(milestone_conditions, trigger_conditions)
+        return true if milestone_conditions.nil?
+
+        milestone_conditions.all? do |key, value|
+          trigger_conditions[key] == value || trigger_conditions[key.to_s] == value ||
+          trigger_conditions[key.to_sym] == value
+        end
+      end
+
+      def initialize_milestones
+        @enable_milestones = false
+
+        # Default milestones - can be customized
+        @milestones = [
+          {
+            key: :welcome_completed,
+            title: "Welcome Aboard!",
+            description: "You completed the welcome step",
+            icon: "🎉",
+            points: 10,
+            trigger: :onboarding_step_completed,
+            conditions: { step: :welcome }
+          },
+          {
+            key: :onboarding_completed,
+            title: "Onboarding Champion",
+            description: "You completed the entire onboarding flow",
+            icon: "🏆",
+            points: 50,
+            trigger: :onboarding_completed
+          },
+          {
+            key: :early_adopter,
+            title: "Early Adopter",
+            description: "You joined within the first hour",
+            icon: "⚡",
+            points: 100,
+            trigger: :custom,
+            conditions: { early_adopter: true }
+          }
+        ]
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration/personalization.rb

@@ -0,0 +1,25 @@
+module RailsOnboarding
+  class Configuration
+    # Per-user-type personalized onboarding flows.
+    module Personalization
+      attr_accessor :personalization_enabled, :user_type_method, :personalized_flows
+
+      # Get a personalized flow for a user type
+      #
+      # @param user_type [Symbol, String] The user type
+      # @return [Array, nil] The personalized steps or nil
+      def personalized_flow(user_type)
+        return nil unless personalization_enabled
+        personalized_flows[user_type.to_sym]
+      end
+
+      private
+
+      def initialize_personalization
+        @personalization_enabled = false
+        @user_type_method = :user_type # Method to call on user to determine their type
+        @personalized_flows = {}
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration/progressive_disclosure.rb

@@ -0,0 +1,41 @@
+module RailsOnboarding
+  class Configuration
+    # Progressive feature disclosure configuration.
+    module ProgressiveDisclosure
+      attr_accessor :progressive_disclosure_enabled, :progressive_features
+
+      # Check if a feature should be shown based on progressive disclosure
+      #
+      # @param feature_key [Symbol, String] The feature key
+      # @param user [Object] The user object
+      # @return [Boolean] True if feature should be shown
+      def show_progressive_feature?(feature_key, user)
+        return true unless progressive_disclosure_enabled
+
+        feature = progressive_features.find { |f| f[:key] == feature_key.to_sym }
+        return true unless feature
+
+        # Check if feature meets its reveal conditions
+        case feature[:reveal_condition]
+        when :time_based
+          user.created_at + feature[:delay].seconds <= Time.current
+        when :action_based
+          user.send(feature[:check_method]) if user.respond_to?(feature[:check_method])
+        when :step_based
+          step_index(user.onboarding_current_step) >= step_index(feature[:after_step])
+        else
+          true
+        end
+      rescue StandardError
+        true # Default to showing feature if check fails
+      end
+
+      private
+
+      def initialize_progressive_disclosure
+        @progressive_disclosure_enabled = false
+        @progressive_features = []
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration/rate_limiting.rb

@@ -0,0 +1,18 @@
+module RailsOnboarding
+  class Configuration
+    # Rate limiting configuration (RailsOnboarding::RateLimitable) - opt-in.
+    module RateLimiting
+      attr_accessor :rate_limiting_enabled, :rate_limit_per_period, :rate_limit_period
+
+      private
+
+      def initialize_rate_limiting
+        # Defaulting this on would start enforcing a request limit on every
+        # host app that upgrades without them ever having asked for it.
+        @rate_limiting_enabled = false
+        @rate_limit_per_period = 60  # Number of requests allowed per period
+        @rate_limit_period = 60      # Period in seconds (60 seconds = 1 minute)
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration/steps.rb

@@ -0,0 +1,121 @@
+module RailsOnboarding
+  class Configuration
+    # Onboarding step configuration and lookups.
+    module Steps
+      attr_accessor :onboarding_required_for
+
+      # Reads the active RailsOnboarding::Flow from the admin Flow Editor when one
+      # exists, falling back to the statically-configured steps otherwise. This
+      # keeps "activate a flow" a real, shared, durable change instead of a
+      # per-process global mutation - every process re-checks the database
+      # instead of caching a value that could go stale the moment another
+      # process (or another admin) activates a different flow.
+      def steps
+        flow_steps = active_flow_steps
+        return hydrate_code_options(flow_steps) if flow_steps
+
+        tenant_override(:steps, @steps)
+      end
+
+      # Override setter to clear cache when configuration changes
+      def steps=(value)
+        clear_cache!
+        @steps = value
+      end
+
+      def total_steps
+        @total_steps ||= steps.size
+      end
+
+      def step_by_name(name)
+        return nil if name.nil?
+
+        @step_by_name_cache ||= {}
+        @step_by_name_cache[name.to_sym] ||= steps.find do |s|
+          next false unless s.is_a?(Hash) && s[:name]
+          s[:name].to_sym == name.to_sym
+        end
+      end
+
+      def step_index(name)
+        return nil if name.nil?
+
+        @step_index_cache ||= {}
+        @step_index_cache[name.to_sym] ||= steps.find_index do |s|
+          next false unless s.is_a?(Hash) && s[:name]
+          s[:name].to_sym == name.to_sym
+        end
+      end
+
+      private
+
+      def active_flow_steps
+        return nil unless defined?(RailsOnboarding::Flow)
+        return nil unless RailsOnboarding::Flow.table_exists?
+
+        RailsOnboarding::Flow.active.first&.steps
+      rescue StandardError
+        nil
+      end
+
+      # A flow persisted by the admin Flow Editor is stored as JSON, so any
+      # Proc-valued step option (:path, :complete_if, or a custom callable) was
+      # silently dropped on write - JSON can't serialize a Proc. Merge those
+      # code-only options back in from the statically-configured step of the
+      # same name, so activating a flow never disables a path-based step or its
+      # completion criteria. Presentation and ordering still come entirely from
+      # the flow; only behavior that can only live in code is re-hydrated.
+      def hydrate_code_options(flow_steps)
+        config_by_name = Array(@steps).each_with_object({}) do |step, index|
+          index[step[:name].to_sym] = step if step.is_a?(Hash) && step[:name]
+        end
+        return Array(flow_steps) if config_by_name.empty?
+
+        Array(flow_steps).map do |flow_step|
+          name = flow_step[:name] if flow_step.respond_to?(:[])
+          config_step = name && config_by_name[name.to_sym]
+          next flow_step unless config_step
+
+          code_options = config_step.select { |_key, value| value.is_a?(Proc) }
+          next flow_step if code_options.empty?
+
+          hydrated = flow_step.dup
+          code_options.each { |key, value| hydrated[key] = value }
+          hydrated
+        end
+      end
+
+      def initialize_steps
+        @onboarding_required_for = :new_users # :new_users, :all_users, or a Proc
+
+        # Default steps - can be customized
+        @steps = [
+          {
+            name: :welcome,
+            title: "Welcome",
+            icon: "🎉",
+            skippable: true
+          },
+          {
+            name: :profile,
+            title: "Setup Profile",
+            icon: "👤",
+            skippable: false
+          },
+          {
+            name: :first_action,
+            title: "First Action",
+            icon: "🚀",
+            skippable: false
+          },
+          {
+            name: :explore,
+            title: "Explore Features",
+            icon: "🔍",
+            skippable: true
+          }
+        ]
+      end
+    end
+  end
+end

data/lib/rails_onboarding/configuration/templates.rb

@@ -0,0 +1,85 @@
+module RailsOnboarding
+  class Configuration
+    # Pre-built onboarding step templates for common app types.
+    module Templates
+      attr_accessor :onboarding_templates
+
+      # Get an onboarding template by key
+      #
+      # @param template_key [Symbol, String] The template key
+      # @return [Hash, nil] The template configuration or nil
+      def template(template_key)
+        onboarding_templates[template_key.to_sym]
+      end
+
+      # Apply a template to the current configuration
+      #
+      # @param template_key [Symbol, String] The template key to apply
+      # @return [Boolean] True if template was applied successfully
+      def apply_template(template_key)
+        template = onboarding_templates[template_key.to_sym]
+        return false unless template
+
+        @steps = template[:steps]
+        true
+      end
+
+      private
+
+      def initialize_templates
+        @onboarding_templates = {
+          saas: {
+            name: "SaaS Application",
+            steps: [
+              { name: :welcome, title: "Welcome", icon: "🎉", skippable: true },
+              { name: :account_setup, title: "Account Setup", icon: "👤", skippable: false },
+              { name: :team_invite, title: "Invite Team", icon: "👥", skippable: true },
+              { name: :first_project, title: "Create Project", icon: "📁", skippable: false },
+              { name: :integration, title: "Connect Tools", icon: "🔌", skippable: true }
+            ]
+          },
+          ecommerce: {
+            name: "E-commerce Platform",
+            steps: [
+              { name: :welcome, title: "Welcome", icon: "🎉", skippable: true },
+              { name: :store_setup, title: "Setup Store", icon: "🏪", skippable: false },
+              { name: :first_product, title: "Add Product", icon: "📦", skippable: false },
+              { name: :payment_setup, title: "Payment Setup", icon: "💳", skippable: false },
+              { name: :launch, title: "Launch Store", icon: "🚀", skippable: false }
+            ]
+          },
+          marketplace: {
+            name: "Marketplace",
+            steps: [
+              { name: :welcome, title: "Welcome", icon: "🎉", skippable: true },
+              { name: :profile_setup, title: "Create Profile", icon: "👤", skippable: false },
+              { name: :verification, title: "Verify Account", icon: "✅", skippable: false },
+              { name: :first_listing, title: "Create Listing", icon: "📝", skippable: false },
+              { name: :explore, title: "Explore", icon: "🔍", skippable: true }
+            ]
+          },
+          community: {
+            name: "Community Platform",
+            steps: [
+              { name: :welcome, title: "Welcome", icon: "🎉", skippable: true },
+              { name: :profile, title: "Setup Profile", icon: "👤", skippable: false },
+              { name: :interests, title: "Choose Interests", icon: "❤️", skippable: true },
+              { name: :first_post, title: "Create Post", icon: "✍️", skippable: false },
+              { name: :connect, title: "Connect", icon: "🤝", skippable: true }
+            ]
+          },
+          education: {
+            name: "Educational Platform",
+            steps: [
+              { name: :welcome, title: "Welcome", icon: "🎉", skippable: true },
+              { name: :student_setup, title: "Student Info", icon: "🎓", skippable: false },
+              { name: :course_selection, title: "Choose Courses", icon: "📚", skippable: false },
+              { name: :first_lesson, title: "First Lesson", icon: "📖", skippable: false },
+              { name: :study_plan, title: "Study Plan", icon: "📅", skippable: true }
+            ]
+          }
+        }
+      end
+    end
+  end
+end