rails_onboarding 0.6.1

data/app/controllers/rails_onboarding/test_sessions_controller.rb

@@ -0,0 +1,16 @@
+# Test-only controller for setting session in integration tests
+module RailsOnboarding
+  class TestSessionsController < ApplicationController
+    skip_before_action :verify_authenticity_token, only: :create
+
+    def create
+      # Only allow in test environment
+      if Rails.env.test?
+        session[:user_id] = params[:user_id]
+        head :ok
+      else
+        head :forbidden
+      end
+    end
+  end
+end

data/app/controllers/rails_onboarding/tooltips_controller.rb

@@ -0,0 +1,92 @@
+module RailsOnboarding
+  class TooltipsController < ApplicationController
+    include RailsOnboarding::RateLimitable
+
+    before_action :authenticate_user!
+
+    # POST /tooltips/dismiss
+    def dismiss
+      tooltip_id = params[:tooltip_id]
+
+      if tooltip_id.blank?
+        render json: { success: false, message: "tooltip_id is required" }, status: :bad_request
+        return
+      end
+
+      # For dismiss, we mark as shown and track as dismissed
+      if current_user.respond_to?(:dismiss_tooltip)
+        current_user.dismiss_tooltip(tooltip_id)
+        render json: { success: true }
+      elsif current_user.respond_to?(:mark_tooltip_shown!)
+        # Fallback: manually mark and track
+        tooltips = current_user.feature_tooltips_shown || {}
+        tooltips[tooltip_id.to_s] = Time.current.iso8601
+        current_user.update!(feature_tooltips_shown: tooltips)
+
+        # Track dismissal event
+        if current_user.respond_to?(:track_tooltip_interaction!)
+          current_user.track_tooltip_interaction!(tooltip_id, "dismissed")
+        end
+        render json: { success: true }
+      else
+        render json: { success: false, message: "User does not support tooltips" }, status: :unprocessable_entity
+      end
+    end
+
+    # POST /tooltips/show
+    def show
+      tooltip_id = params[:tooltip_id]
+
+      if tooltip_id.present? && current_user.respond_to?(:mark_tooltip_shown!)
+        current_user.mark_tooltip_shown!(tooltip_id)
+        render json: { success: true }
+      else
+        render json: { success: false, message: "Invalid tooltip_id or user" }, status: :unprocessable_entity
+      end
+    end
+
+    # POST /tooltips/reset
+    def reset
+      if current_user.respond_to?(:reset_tooltips!)
+        current_user.reset_tooltips!
+        render json: { success: true }
+      else
+        render json: { success: false, message: "User does not support tooltips" }, status: :unprocessable_entity
+      end
+    end
+
+    # GET /tooltips/status
+    def status
+      tooltip_id = params[:tooltip_id]
+
+      if tooltip_id.present? && current_user.respond_to?(:show_feature_tooltip?)
+        shown = !current_user.show_feature_tooltip?(tooltip_id)
+        render json: { shown: shown, tooltip_id: tooltip_id }
+      else
+        render json: { shown: false, message: "Invalid tooltip_id or user" }, status: :unprocessable_entity
+      end
+    end
+
+    # Legacy action - kept for backward compatibility
+    def mark_shown
+      feature = params[:feature]
+
+      if feature.present? && current_user.respond_to?(:mark_tooltip_shown!)
+        current_user.mark_tooltip_shown!(feature)
+        render json: { status: "success", feature: feature }
+      else
+        render json: { status: "error", message: "Invalid feature or user" }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def authenticate_user!
+      # This should be overridden by the host app
+      # or use the host app's authentication
+      unless defined?(current_user) && current_user
+        render json: { status: "error", message: "Authentication required" }, status: :unauthorized
+      end
+    end
+  end
+end

data/app/helpers/rails_onboarding/application_helper.rb

@@ -0,0 +1,4 @@
+module RailsOnboarding
+  module ApplicationHelper
+  end
+end

data/app/helpers/rails_onboarding/i18n_helper.rb

@@ -0,0 +1,137 @@
+module RailsOnboarding
+  # I18n Helper Module
+  # Provides convenient methods for internationalization
+  module I18nHelper
+    # Translate a key with the rails_onboarding scope
+    #
+    # @param key [String, Symbol] Translation key
+    # @param options [Hash] Translation options
+    # @return [String] Translated string
+    def t_onboarding(key, **options)
+      I18n.t("rails_onboarding.#{key}", **options)
+    end
+
+    # Translate navigation text
+    def t_nav(key, **options)
+      t_onboarding("navigation.#{key}", **options)
+    end
+
+    # Translate action text
+    def t_action(key, **options)
+      t_onboarding("actions.#{key}", **options)
+    end
+
+    # Translate message text
+    def t_message(key, **options)
+      t_onboarding("messages.#{key}", **options)
+    end
+
+    # Translate error text
+    def t_error(key, **options)
+      t_onboarding("errors.#{key}", **options)
+    end
+
+    # Translate common text
+    def t_common(key, **options)
+      t_onboarding("common.#{key}", **options)
+    end
+
+    # Translate progress text
+    def t_progress(key, **options)
+      t_onboarding("progress.#{key}", **options)
+    end
+
+    # Translate milestone text
+    def t_milestone(key, **options)
+      t_onboarding("milestones.#{key}", **options)
+    end
+
+    # Get localized step title
+    #
+    # @param step [Hash] Step configuration
+    # @return [String] Localized step title
+    def localized_step_title(step)
+      return step[:title] unless step[:title_key]
+
+      I18n.t(step[:title_key], default: step[:title])
+    end
+
+    # Get localized step description
+    #
+    # @param step [Hash] Step configuration
+    # @return [String] Localized step description
+    def localized_step_description(step)
+      return step[:description] unless step[:description_key]
+
+      I18n.t(step[:description_key], default: step[:description] || "")
+    end
+
+    # Get localized milestone title
+    #
+    # @param milestone [Hash] Milestone configuration
+    # @return [String] Localized milestone title
+    def localized_milestone_title(milestone)
+      return milestone[:title] unless milestone[:title_key]
+
+      I18n.t(milestone[:title_key], default: milestone[:title])
+    end
+
+    # Get localized milestone description
+    #
+    # @param milestone [Hash] Milestone configuration
+    # @return [String] Localized milestone description
+    def localized_milestone_description(milestone)
+      return milestone[:description] unless milestone[:description_key]
+
+      I18n.t(milestone[:description_key], default: milestone[:description] || "")
+    end
+
+    # Get available locales for onboarding
+    #
+    # @return [Array<Symbol>] Available locale codes
+    def onboarding_locales
+      I18n.available_locales.select do |locale|
+        I18n.exists?("rails_onboarding", locale: locale)
+      end
+    end
+
+    # Check if a locale is available
+    #
+    # @param locale [Symbol, String] Locale code
+    # @return [Boolean] True if locale is available
+    def locale_available?(locale)
+      I18n.available_locales.include?(locale.to_sym) &&
+        I18n.exists?("rails_onboarding", locale: locale)
+    end
+
+    # Get user's preferred locale
+    #
+    # @param user [User] User object
+    # @return [Symbol] Locale code
+    def user_locale(user)
+      return I18n.default_locale unless user
+
+      # Try to get locale from user
+      user_locale = if user.respond_to?(:locale)
+                      user.locale
+      elsif user.respond_to?(:language)
+                      user.language
+      elsif user.respond_to?(:preferred_language)
+                      user.preferred_language
+      end
+
+      return I18n.default_locale unless user_locale
+
+      locale_sym = user_locale.to_sym
+      locale_available?(locale_sym) ? locale_sym : I18n.default_locale
+    end
+
+    # Execute block with user's locale
+    #
+    # @param user [User] User object
+    # @yield Block to execute with user's locale
+    def with_user_locale(user, &block)
+      I18n.with_locale(user_locale(user), &block)
+    end
+  end
+end

data/app/helpers/rails_onboarding/personalization_helper.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Helper methods for personalization features in views
+  module PersonalizationHelper
+    # Render content only for specific user types
+    #
+    # @param user_types [Array<Symbol>, Symbol] User type(s) to show content for
+    # @param user [Object] User object (defaults to current_user)
+    # @yield Block to render if user type matches
+    #
+    # @example
+    #   <%= for_user_types(:business, :enterprise) do %>
+    #     <p>This is only shown to business and enterprise users</p>
+    #   <% end %>
+    def for_user_types(*user_types, user: nil)
+      user ||= current_user if respond_to?(:current_user)
+      return unless user
+
+      return unless user.respond_to?(:personalization_type)
+
+      user_type = user.personalization_type
+      return unless user_types.map(&:to_sym).include?(user_type.to_sym)
+
+      yield if block_given?
+    end
+
+    # Render different content based on user type
+    #
+    # @param user [Object] User object (defaults to current_user)
+    # @yield [user_type] Block that receives the user type
+    #
+    # @example
+    #   <%= personalized_content do |type| %>
+    #     <% if type == :business %>
+    #       <p>Welcome, business user!</p>
+    #     <% else %>
+    #       <p>Welcome!</p>
+    #     <% end %>
+    #   <% end %>
+    def personalized_content(user: nil, &block)
+      user ||= current_user if respond_to?(:current_user)
+      return unless user
+
+      return unless user.respond_to?(:personalization_type)
+
+      user_type = user.personalization_type
+      yield(user_type) if block_given?
+    end
+
+    # Get a personalized message based on user type
+    #
+    # @param messages [Hash] Hash of user_type => message
+    # @param default [String] Default message if user type not found
+    # @param user [Object] User object (defaults to current_user)
+    # @return [String] The personalized message
+    #
+    # @example
+    #   <%= personalized_message(
+    #     { business: "Welcome to your business dashboard",
+    #       individual: "Welcome to your personal dashboard" },
+    #     default: "Welcome"
+    #   ) %>
+    def personalized_message(messages, default: "Welcome", user: nil)
+      user ||= current_user if respond_to?(:current_user)
+      return default unless user
+
+      return default unless user.respond_to?(:personalization_type)
+
+      user_type = user.personalization_type
+      messages[user_type.to_sym] || default
+    end
+
+    # Get personalized steps for the current user
+    #
+    # @param user [Object] User object (defaults to current_user)
+    # @return [Array<Hash>] Array of step configurations
+    def personalized_steps(user: nil)
+      user ||= current_user if respond_to?(:current_user)
+      return RailsOnboarding.configuration.steps unless user
+
+      return RailsOnboarding.configuration.steps unless user.respond_to?(:personalized_steps)
+
+      user.personalized_steps
+    end
+
+    # Render a personalized progress indicator
+    #
+    # @param user [Object] User object (defaults to current_user)
+    # @return [String] HTML for progress indicator
+    def personalized_progress_indicator(user: nil)
+      user ||= current_user if respond_to?(:current_user)
+      return "" unless user
+
+      return "" unless user.respond_to?(:personalized_progress_percentage)
+
+      percentage = user.personalized_progress_percentage
+      total_steps = user.respond_to?(:personalized_total_steps) ? user.personalized_total_steps : 0
+
+      content_tag :div, class: "personalized-progress" do
+        concat(content_tag(:div, class: "progress-bar") do
+          content_tag(:div, "", class: "progress-fill", style: "width: #{percentage}%")
+        end)
+        concat(content_tag(:div, "#{percentage}% complete (Step #{user.personalized_step_index(user.onboarding_current_step) + 1} of #{total_steps})", class: "progress-text"))
+      end
+    end
+
+    # Check if a feature should be shown based on personalization
+    #
+    # @param feature_name [Symbol, String] Feature name
+    # @param user [Object] User object (defaults to current_user)
+    # @return [Boolean] True if feature should be shown
+    def show_personalized_feature?(feature_name, user: nil)
+      user ||= current_user if respond_to?(:current_user)
+      return true unless user
+
+      return true unless user.respond_to?(:show_personalized_feature?)
+
+      user.show_personalized_feature?(feature_name)
+    end
+
+    # Get personalized CTA (Call To Action) text
+    #
+    # @param action [Symbol, String] Action type (:next, :complete, :skip, etc.)
+    # @param user [Object] User object (defaults to current_user)
+    # @return [String] Personalized CTA text
+    def personalized_cta(action, user: nil)
+      user ||= current_user if respond_to?(:current_user)
+
+      user_type = user&.respond_to?(:personalization_type) ? user.personalization_type : nil
+
+      cta_map = {
+        next: {
+          business: "Continue to Business Setup",
+          enterprise: "Proceed to Enterprise Configuration",
+          individual: "Next Step",
+          default: "Continue"
+        },
+        complete: {
+          business: "Launch Your Business Account",
+          enterprise: "Activate Enterprise Features",
+          individual: "Get Started",
+          default: "Complete Setup"
+        },
+        skip: {
+          business: "Skip for Now (You can complete this later in Settings)",
+          enterprise: "Configure Later",
+          individual: "Skip This Step",
+          default: "Skip"
+        }
+      }
+
+      action_map = cta_map[action.to_sym] || {}
+      action_map[user_type&.to_sym] || action_map[:default] || action.to_s.titleize
+    end
+
+    # Render personalized recommendations
+    #
+    # @param user [Object] User object (defaults to current_user)
+    # @return [String] HTML for recommendations
+    def personalized_recommendations(user: nil)
+      user ||= current_user if respond_to?(:current_user)
+      return "" unless user
+
+      return "" unless user.respond_to?(:personalized_recommendations)
+
+      recommendations = user.personalized_recommendations
+      return "" if recommendations.empty?
+
+      content_tag :div, class: "personalized-recommendations" do
+        concat(content_tag(:h3, "Recommended for You"))
+        concat(content_tag(:div, class: "recommendations-list") do
+          recommendations.each do |rec|
+            concat(content_tag(:div, class: "recommendation-card") do
+              concat(content_tag(:h4, rec[:title]))
+              concat(content_tag(:p, rec[:description]))
+              concat(link_to(rec[:cta] || "Get Started", rec[:url], class: "btn btn-primary")) if rec[:url]
+            end)
+          end
+        end)
+      end
+    end
+  end
+end

data/app/helpers/rails_onboarding/templates_helper.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Helper methods for working with onboarding templates
+  module TemplatesHelper
+    # Get all available templates
+    #
+    # @return [Hash] Hash of template_key => template_config
+    def available_templates
+      RailsOnboarding.configuration.onboarding_templates || {}
+    end
+
+    # Get a specific template
+    #
+    # @param template_key [Symbol, String] Template identifier
+    # @return [Hash, nil] Template configuration or nil
+    def get_template(template_key)
+      RailsOnboarding.configuration.template(template_key)
+    end
+
+    # Apply a template to configuration
+    #
+    # @param template_key [Symbol, String] Template identifier
+    # @return [Boolean] Success status
+    def apply_template(template_key)
+      RailsOnboarding.configuration.apply_template(template_key)
+    end
+
+    # Get recommended template based on context
+    #
+    # @param context [Hash] Context information (industry, user_count, etc.)
+    # @return [Symbol, nil] Recommended template key or nil
+    #
+    # @example
+    #   recommended_template(industry: :ecommerce, user_count: 1)
+    #   # => :ecommerce
+    def recommended_template(context = {})
+      templates = available_templates
+
+      # Recommend based on industry if provided
+      if context[:industry]
+        return context[:industry].to_sym if templates[context[:industry].to_sym]
+      end
+
+      # Recommend based on user type
+      if context[:user_type]
+        case context[:user_type].to_sym
+        when :student, :learner
+          return :education if templates[:education]
+        when :seller, :merchant
+          return :marketplace if templates[:marketplace]
+        when :business, :company
+          return :saas if templates[:saas]
+        end
+      end
+
+      # Recommend based on team size
+      if context[:team_size]
+        if context[:team_size] > 10
+          return :saas if templates[:saas]
+        elsif context[:team_size] == 1
+          return :community if templates[:community]
+        end
+      end
+
+      # Default to first available template
+      templates.keys.first
+    end
+
+    # Render template selection UI
+    #
+    # @param options [Hash] Display options
+    # @return [String] HTML for template selector
+    def template_selector(options = {})
+      templates = available_templates
+      current_template = options[:current] || detect_current_template
+
+      content_tag :div, class: "template-selector" do
+        concat(content_tag(:h3, options[:title] || "Choose a Template"))
+
+        concat(content_tag(:div, class: "template-options") do
+          templates.each do |key, template|
+            concat(template_option(key, template, key == current_template))
+          end
+        end)
+      end
+    end
+
+    # Render a single template option
+    #
+    # @param key [Symbol] Template key
+    # @param template [Hash] Template configuration
+    # @param selected [Boolean] Whether this template is selected
+    # @return [String] HTML for template option
+    def template_option(key, template, selected = false)
+      content_tag :div, class: "template-option #{selected ? 'selected' : ''}", data: { template: key } do
+        concat(content_tag(:div, class: "template-icon") do
+          template[:icon] || "📋"
+        end)
+        concat(content_tag(:div, class: "template-info") do
+          concat(content_tag(:h4, template[:name]))
+          concat(content_tag(:p, template[:description] || "#{key.to_s.titleize} onboarding"))
+          concat(content_tag(:span, "#{template[:steps]&.size || 0} steps", class: "step-count"))
+        end)
+      end
+    end
+
+    # Detect which template matches current configuration
+    #
+    # @return [Symbol, nil] Matched template key or nil
+    def detect_current_template
+      current_steps = RailsOnboarding.configuration.steps
+      return nil if current_steps.empty?
+
+      available_templates.find do |key, template|
+        template[:steps] == current_steps
+      end&.first
+    end
+
+    # Compare templates
+    #
+    # @param template_keys [Array<Symbol>] Template keys to compare
+    # @return [Hash] Comparison data
+    def compare_templates(*template_keys)
+      comparison = {}
+
+      template_keys.each do |key|
+        template = get_template(key)
+        next unless template
+
+        comparison[key] = {
+          name: template[:name],
+          total_steps: template[:steps]&.size || 0,
+          required_steps: template[:steps]&.count { |s| !s[:skippable] } || 0,
+          optional_steps: template[:steps]&.count { |s| s[:skippable] } || 0,
+          steps: template[:steps]
+        }
+      end
+
+      comparison
+    end
+
+    # Render template comparison table
+    #
+    # @param template_keys [Array<Symbol>] Templates to compare
+    # @return [String] HTML table comparing templates
+    def render_template_comparison(*template_keys)
+      comparison = compare_templates(*template_keys)
+      return "" if comparison.empty?
+
+      content_tag :table, class: "template-comparison" do
+        concat(content_tag(:thead) do
+          content_tag(:tr) do
+            concat(content_tag(:th, "Feature"))
+            comparison.each_key do |key|
+              concat(content_tag(:th, comparison[key][:name]))
+            end
+          end
+        end)
+
+        concat(content_tag(:tbody) do
+          # Total steps row
+          concat(content_tag(:tr) do
+            concat(content_tag(:td, "Total Steps"))
+            comparison.each_value do |data|
+              concat(content_tag(:td, data[:total_steps]))
+            end
+          end)
+
+          # Required steps row
+          concat(content_tag(:tr) do
+            concat(content_tag(:td, "Required Steps"))
+            comparison.each_value do |data|
+              concat(content_tag(:td, data[:required_steps]))
+            end
+          end)
+
+          # Optional steps row
+          concat(content_tag(:tr) do
+            concat(content_tag(:td, "Optional Steps"))
+            comparison.each_value do |data|
+              concat(content_tag(:td, data[:optional_steps]))
+            end
+          end)
+        end)
+      end
+    end
+
+    # Get template metadata
+    #
+    # @param template_key [Symbol, String] Template identifier
+    # @return [Hash] Metadata about the template
+    def template_metadata(template_key)
+      template = get_template(template_key)
+      return {} unless template
+
+      {
+        name: template[:name],
+        total_steps: template[:steps]&.size || 0,
+        estimated_time: estimate_template_time(template),
+        difficulty: template_difficulty(template),
+        categories: template_categories(template)
+      }
+    end
+
+    # Estimate completion time for a template
+    #
+    # @param template [Hash] Template configuration
+    # @return [String] Estimated time (e.g., "5-10 minutes")
+    def estimate_template_time(template)
+      steps_count = template[:steps]&.size || 0
+      min_time = steps_count * 1 # 1 minute per step minimum
+      max_time = steps_count * 3 # 3 minutes per step maximum
+
+      "#{min_time}-#{max_time} minutes"
+    end
+
+    # Determine template difficulty
+    #
+    # @param template [Hash] Template configuration
+    # @return [Symbol] :easy, :medium, or :hard
+    def template_difficulty(template)
+      total_steps = template[:steps]&.size || 0
+      required_steps = template[:steps]&.count { |s| !s[:skippable] } || 0
+
+      if total_steps <= 3 && required_steps <= 2
+        :easy
+      elsif total_steps <= 5 && required_steps <= 3
+        :medium
+      else
+        :hard
+      end
+    end
+
+    # Get categories/tags for a template
+    #
+    # @param template [Hash] Template configuration
+    # @return [Array<Symbol>] Categories
+    def template_categories(template)
+      categories = []
+
+      step_names = template[:steps]&.map { |s| s[:name].to_s } || []
+
+      categories << :profile if step_names.any? { |n| n.include?("profile") }
+      categories << :team if step_names.any? { |n| n.include?("team") || n.include?("invite") }
+      categories << :payment if step_names.any? { |n| n.include?("payment") || n.include?("billing") }
+      categories << :content if step_names.any? { |n| n.include?("post") || n.include?("product") }
+      categories << :social if step_names.any? { |n| n.include?("connect") || n.include?("friends") }
+
+      categories
+    end
+  end
+end

data/app/jobs/rails_onboarding/application_job.rb

@@ -0,0 +1,4 @@
+module RailsOnboarding
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/rails_onboarding/application_mailer.rb

@@ -0,0 +1,6 @@
+module RailsOnboarding
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end