rails_onboarding 0.6.1

data/lib/rails_onboarding/requirements_validator.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Validates that the host application meets all requirements for RailsOnboarding
+  # Usage: RailsOnboarding::RequirementsValidator.validate!
+  class RequirementsValidator
+    class ValidationError < StandardError; end
+
+    class << self
+      # Run all validations and raise if any fail
+      def validate!
+        results = run_validations
+
+        if results[:errors].any?
+          raise ValidationError, format_error_message(results)
+        end
+
+        log_results(results)
+        true
+      end
+
+      # Run all validations and return results without raising
+      def check
+        run_validations
+      end
+
+      private
+
+      def run_validations
+        results = {
+          errors: [],
+          warnings: [],
+          info: []
+        }
+
+        validate_rails_version(results)
+        validate_ruby_version(results)
+        validate_user_class(results)
+        validate_user_model(results)
+        validate_application_controller(results)
+        validate_current_user_method(results)
+        validate_database_columns(results)
+        validate_routes(results)
+        validate_optional_dependencies(results)
+        validate_configuration(results)
+
+        results
+      end
+
+      def validate_rails_version(results)
+        required_version = Gem::Version.new("7.0.0")
+        current_version = Gem::Version.new(Rails.version)
+
+        if current_version < required_version
+          results[:errors] << "Rails version #{required_version} or higher required (current: #{current_version})"
+        else
+          results[:info] << "Rails version: #{current_version} ✓"
+        end
+      rescue => e
+        results[:errors] << "Could not determine Rails version: #{e.message}"
+      end
+
+      def validate_ruby_version(results)
+        required_version = Gem::Version.new("3.0.0")
+        current_version = Gem::Version.new(RUBY_VERSION)
+
+        if current_version < required_version
+          results[:errors] << "Ruby version #{required_version} or higher required (current: #{current_version})"
+        else
+          results[:info] << "Ruby version: #{current_version} ✓"
+        end
+      rescue => e
+        results[:errors] << "Could not determine Ruby version: #{e.message}"
+      end
+
+      def validate_user_class(results)
+        begin
+          user_class_name = RailsOnboarding.configuration.user_class_name
+          user_class = user_class_name.constantize
+
+          results[:info] << "User class '#{user_class_name}' found ✓"
+
+          # Check if Onboardable concern is included
+          unless user_class.included_modules.include?(RailsOnboarding::Onboardable)
+            results[:errors] << "User class '#{user_class_name}' must include RailsOnboarding::Onboardable concern"
+          else
+            results[:info] << "Onboardable concern included ✓"
+          end
+        rescue NameError
+          results[:errors] << "User class '#{RailsOnboarding.configuration.user_class_name}' not found"
+        rescue => e
+          results[:errors] << "Error validating user class: #{e.message}"
+        end
+      end
+
+      def validate_user_model(results)
+        begin
+          user_class_name = RailsOnboarding.configuration.user_class_name
+          user_class = user_class_name.constantize
+
+          # Check for required behavioral methods (provided by the Onboardable concern).
+          # onboarding_completed? and onboarding_current_step are column-backed attribute
+          # methods instead - Rails generates those lazily on first instantiation, so
+          # instance_methods.include? can't reliably see them here; their underlying
+          # columns are already checked in validate_database_columns.
+          required_methods = [
+            :needs_onboarding?,
+            :complete_onboarding!,
+            :onboarding_progress_percentage
+          ]
+
+          required_methods.each do |method|
+            unless user_class.instance_methods.include?(method)
+              results[:errors] << "User model missing required method: #{method}"
+            end
+          end
+        rescue NameError
+          # Already reported in validate_user_class
+        rescue => e
+          results[:warnings] << "Could not validate user model methods: #{e.message}"
+        end
+      end
+
+      def validate_application_controller(results)
+        if defined?(ApplicationController)
+          results[:info] << "ApplicationController found ✓"
+
+          # Check if ControllerHelpers are included
+          if ApplicationController.included_modules.include?(RailsOnboarding::ControllerHelpers)
+            results[:info] << "ControllerHelpers included ✓"
+          else
+            results[:warnings] << "RailsOnboarding::ControllerHelpers not included in ApplicationController (this is automatic in engine mode)"
+          end
+        else
+          results[:warnings] << "ApplicationController not found (unusual but may be intentional)"
+        end
+      rescue => e
+        results[:warnings] << "Error checking ApplicationController: #{e.message}"
+      end
+
+      def validate_current_user_method(results)
+        if defined?(ApplicationController)
+          if ApplicationController.instance_methods.include?(:current_user)
+            results[:info] << "current_user method available ✓"
+          else
+            results[:errors] << "ApplicationController must have a current_user method (typically provided by authentication system)"
+          end
+        end
+      rescue => e
+        results[:warnings] << "Could not validate current_user method: #{e.message}"
+      end
+
+      def validate_database_columns(results)
+        begin
+          user_class = RailsOnboarding.configuration.user_class_name.constantize
+
+          return unless user_class.respond_to?(:column_names)
+
+          required_columns = {
+            "onboarding_completed" => :boolean,
+            "onboarding_current_step" => :string,
+            "onboarding_skipped" => :boolean
+          }
+
+          optional_columns = {
+            "onboarding_completed_at" => :datetime,
+            "feature_tooltips_shown" => [ :jsonb, :text ],
+            "milestones_achieved" => [ :text, :jsonb ],
+            "milestone_points" => :integer,
+            "last_milestone_at" => :datetime
+          }
+
+          # Check required columns
+          required_columns.each do |column_name, expected_type|
+            if user_class.column_names.include?(column_name)
+              actual_type = user_class.columns_hash[column_name]&.type
+              if actual_type.to_s != expected_type.to_s
+                results[:warnings] << "Column '#{column_name}' has type #{actual_type}, expected #{expected_type}"
+              else
+                results[:info] << "Required column '#{column_name}' (#{expected_type}) ✓"
+              end
+            else
+              results[:errors] << "Required database column missing: #{column_name} (#{expected_type})"
+            end
+          end
+
+          # Check optional columns
+          optional_columns.each do |column_name, expected_types|
+            expected_types = Array(expected_types)
+            if user_class.column_names.include?(column_name)
+              actual_type = user_class.columns_hash[column_name]&.type
+              if expected_types.map(&:to_s).include?(actual_type.to_s)
+                results[:info] << "Optional column '#{column_name}' (#{actual_type}) ✓"
+              else
+                results[:warnings] << "Column '#{column_name}' has type #{actual_type}, expected one of #{expected_types.join(', ')}"
+              end
+            else
+              results[:info] << "Optional column '#{column_name}' not present (some features may be unavailable)"
+            end
+          end
+        rescue NameError
+          # Already reported in validate_user_class
+        rescue => e
+          results[:warnings] << "Could not validate database columns: #{e.message}"
+        end
+      end
+
+      def validate_routes(results)
+        if defined?(Rails.application)
+          routes = Rails.application.routes.routes.map(&:name).compact
+
+          if routes.include?("rails_onboarding")
+            results[:info] << "Engine mounted in routes ✓"
+          else
+            results[:errors] << "RailsOnboarding engine not mounted in routes. Add: mount RailsOnboarding::Engine => '/onboarding'"
+          end
+        end
+      rescue => e
+        results[:warnings] << "Could not validate routes: #{e.message}"
+      end
+
+      def validate_optional_dependencies(results)
+        # Check for optional gems
+        optional_gems = {
+          "ActiveJob" => -> { defined?(::ActiveJob::Base) },
+          "ActionMailer" => -> { defined?(::ActionMailer::Base) },
+          "Devise" => -> { defined?(Devise) },
+          "Turbo" => -> { defined?(Turbo) },
+          "Stimulus" => -> { defined?(Stimulus) },
+          "Noticed" => -> { defined?(Noticed) },
+          "ActiveModel::Serializers" => -> { defined?(ActiveModel::Serializer) }
+        }
+
+        optional_gems.each do |gem_name, check|
+          if check.call
+            results[:info] << "Optional: #{gem_name} available ✓"
+          else
+            results[:info] << "Optional: #{gem_name} not available (some features may be limited)"
+          end
+        end
+      rescue => e
+        results[:warnings] << "Error checking optional dependencies: #{e.message}"
+      end
+
+      def validate_configuration(results)
+        config = RailsOnboarding.configuration
+
+        # Check critical configuration
+        unless config.steps.any?
+          results[:errors] << "No onboarding steps configured. Add steps in config/initializers/rails_onboarding.rb"
+        else
+          results[:info] << "#{config.steps.size} onboarding step(s) configured ✓"
+        end
+
+        # Check step names are unique
+        step_names = config.steps.map { |s| s[:name] }
+        duplicates = step_names.select { |name| step_names.count(name) > 1 }.uniq
+        if duplicates.any?
+          results[:errors] << "Duplicate step names found: #{duplicates.join(', ')}"
+        end
+
+        # Check redirect paths
+        if config.redirect_after_completion.nil?
+          results[:warnings] << "No redirect_after_completion configured (users will stay on onboarding page)"
+        end
+
+        # Validate mailer configuration if emails are enabled
+        if RailsOnboarding::BackgroundJobs.background_job_options[:enable_emails] && !RailsOnboarding.action_mailer_configured?
+          results[:warnings] << "Emails enabled but ActionMailer not properly configured"
+        end
+      rescue => e
+        results[:warnings] << "Error validating configuration: #{e.message}"
+      end
+
+      def format_error_message(results)
+        message = "\n" + "=" * 80 + "\n"
+        message += "RailsOnboarding Requirements Validation Failed\n"
+        message += "=" * 80 + "\n\n"
+
+        if results[:errors].any?
+          message += "ERRORS (must be fixed):\n"
+          results[:errors].each { |error| message += "  ✗ #{error}\n" }
+          message += "\n"
+        end
+
+        if results[:warnings].any?
+          message += "WARNINGS (should be addressed):\n"
+          results[:warnings].each { |warning| message += "  ⚠ #{warning}\n" }
+          message += "\n"
+        end
+
+        message += "Please fix the errors above before using RailsOnboarding.\n"
+        message += "See documentation: https://github.com/bunnahabhain/rails_onboarding\n"
+        message += "=" * 80 + "\n"
+
+        message
+      end
+
+      def log_results(results)
+        return unless defined?(Rails.logger)
+
+        Rails.logger.info "RailsOnboarding requirements validation passed ✓"
+
+        if results[:warnings].any?
+          Rails.logger.warn "RailsOnboarding has #{results[:warnings].size} warning(s):"
+          results[:warnings].each { |warning| Rails.logger.warn "  ⚠ #{warning}" }
+        end
+
+        if results[:info].any? && Rails.env.development?
+          results[:info].each { |info| Rails.logger.debug "  #{info}" }
+        end
+      end
+    end
+  end
+end

data/lib/rails_onboarding/responsive_helper.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Responsive layout helper module
+  # Provides helper methods for implementing responsive design features in the host application
+  module ResponsiveHelper
+    # Returns the viewport meta tag for responsive design
+    # This should be included in the host application's layout
+    #
+    # @param options [Hash] Optional configuration
+    # @option options [String] :width The viewport width (default: 'device-width')
+    # @option options [Float] :initial_scale The initial zoom level (default: 1.0)
+    # @option options [Float] :maximum_scale The maximum zoom level (default: 5.0)
+    # @option options [Float] :minimum_scale The minimum zoom level (default: 1.0)
+    # @option options [Boolean] :user_scalable Whether user can zoom (default: true)
+    # @option options [String] :viewport_fit How to handle notches/safe areas (default: 'cover')
+    #
+    # @return [String] The viewport meta tag HTML
+    #
+    # @example Basic usage in a layout
+    #   <%= rails_onboarding_viewport_meta %>
+    #
+    # @example Custom configuration
+    #   <%= rails_onboarding_viewport_meta(maximum_scale: 3.0, viewport_fit: 'contain') %>
+    def rails_onboarding_viewport_meta(options = {})
+      width = options[:width] || "device-width"
+      initial_scale = options[:initial_scale] || 1.0
+      maximum_scale = options[:maximum_scale] || 5.0
+      minimum_scale = options[:minimum_scale] || 1.0
+      user_scalable = options.fetch(:user_scalable, true) ? "yes" : "no"
+      viewport_fit = options[:viewport_fit] || "cover"
+
+      content = [
+        "width=#{width}",
+        "initial-scale=#{initial_scale}",
+        "maximum-scale=#{maximum_scale}",
+        "minimum-scale=#{minimum_scale}",
+        "user-scalable=#{user_scalable}",
+        "viewport-fit=#{viewport_fit}"
+      ].join(", ")
+
+      tag(:meta, name: "viewport", content: content)
+    end
+
+    # Returns theme color meta tag for mobile browsers
+    #
+    # @param color [String] The theme color (default: primary color from config)
+    # @return [String] The theme-color meta tag HTML
+    #
+    # @example
+    #   <%= rails_onboarding_theme_color %>
+    #   <%= rails_onboarding_theme_color('#6366f1') %>
+    def rails_onboarding_theme_color(color = nil)
+      color ||= "#6366f1" # Default primary color
+      tag(:meta, name: "theme-color", content: color)
+    end
+
+    # Checks if the current device is mobile based on user agent
+    #
+    # @return [Boolean] True if mobile device
+    def mobile_device?
+      return false unless request.present?
+
+      user_agent = request.user_agent.to_s.downcase
+      mobile_patterns = [
+        /mobile/,
+        /android/,
+        /iphone/,
+        /ipad/,
+        /ipod/,
+        /blackberry/,
+        /windows phone/,
+        /opera mini/,
+        /kindle/,
+        /silk/
+      ]
+
+      mobile_patterns.any? { |pattern| user_agent.match?(pattern) }
+    end
+
+    # Checks if the current device is a tablet
+    #
+    # @return [Boolean] True if tablet device
+    def tablet_device?
+      return false unless request.present?
+
+      user_agent = request.user_agent.to_s.downcase
+      tablet_patterns = [ /ipad/, /tablet/, /kindle/, /silk/, /playbook/ ]
+
+      tablet_patterns.any? { |pattern| user_agent.match?(pattern) }
+    end
+
+    # Checks if the current device is a phone
+    #
+    # @return [Boolean] True if phone device
+    def phone_device?
+      mobile_device? && !tablet_device?
+    end
+
+    # Returns CSS classes for responsive context
+    #
+    # @return [String] Space-separated CSS classes
+    #
+    # @example In a view
+    #   <div class="<%= responsive_device_classes %>">
+    def responsive_device_classes
+      classes = []
+      classes << "is-mobile" if mobile_device?
+      classes << "is-tablet" if tablet_device?
+      classes << "is-phone" if phone_device?
+      classes << "is-desktop" unless mobile_device?
+      classes.join(" ")
+    end
+
+    # Returns data attributes for JavaScript device detection
+    #
+    # @return [Hash] Data attributes for HTML tags
+    #
+    # @example In a view
+    #   <div <%= responsive_device_data %>>
+    def responsive_device_data
+      {
+        "data-mobile" => mobile_device?,
+        "data-tablet" => tablet_device?,
+        "data-phone" => phone_device?
+      }
+    end
+
+    # Apple-specific meta tags for iOS devices
+    #
+    # @return [String] Combined meta tags for iOS
+    #
+    # @example In a layout
+    #   <%= rails_onboarding_ios_meta %>
+    def rails_onboarding_ios_meta
+      tags = []
+
+      # Enable web app capable mode
+      tags << tag(:meta, name: "apple-mobile-web-app-capable", content: "yes")
+
+      # Status bar style
+      tags << tag(:meta, name: "apple-mobile-web-app-status-bar-style", content: "default")
+
+      # Disable phone number detection
+      tags << tag(:meta, name: "format-detection", content: "telephone=no")
+
+      safe_join(tags, "\n")
+    end
+
+    # Returns manifest link for PWA support
+    #
+    # @param manifest_path [String] Path to manifest.json
+    # @return [String] Link tag for manifest
+    #
+    # @example
+    #   <%= rails_onboarding_manifest_link %>
+    def rails_onboarding_manifest_link(manifest_path = "/manifest.json")
+      tag(:link, rel: "manifest", href: manifest_path)
+    end
+
+    # Helper to render responsive images
+    #
+    # @param src [String] Base image source
+    # @param options [Hash] Image options
+    # @option options [String] :alt Alt text
+    # @option options [Hash] :srcset Responsive image sources
+    # @option options [String] :sizes Media query sizes
+    #
+    # @example
+    #   <%= responsive_image('welcome.jpg',
+    #         alt: 'Welcome',
+    #         srcset: { '1x' => 'welcome.jpg', '2x' => 'welcome@2x.jpg' },
+    #         sizes: '(max-width: 768px) 100vw, 50vw') %>
+    def responsive_image(src, options = {})
+      alt = options[:alt] || ""
+      srcset = options[:srcset]
+      sizes = options[:sizes]
+      css_class = options[:class] || ""
+
+      img_options = { src: src, alt: alt, class: css_class }
+
+      if srcset.present?
+        srcset_value = srcset.map { |density, path| "#{path} #{density}" }.join(", ")
+        img_options[:srcset] = srcset_value
+      end
+
+      img_options[:sizes] = sizes if sizes.present?
+
+      tag(:img, img_options)
+    end
+
+    # Returns appropriate loading attribute for images
+    #
+    # @param eager [Boolean] Whether to load eagerly
+    # @return [String] Loading attribute value
+    def image_loading_strategy(eager: false)
+      eager ? "eager" : "lazy"
+    end
+
+    # Checks if the viewport supports hover (desktop/laptop)
+    #
+    # @return [Boolean] True if hover is supported
+    # Note: This is a server-side estimation; client-side detection is more accurate
+    def supports_hover?
+      !mobile_device?
+    end
+
+    # Returns touch-friendly attributes for interactive elements
+    #
+    # @return [Hash] Data attributes for touch optimization
+    def touch_friendly_attrs
+      {
+        "data-touch-enabled" => mobile_device?,
+        "style" => mobile_device? ? "touch-action: manipulation;" : nil
+      }.compact
+    end
+  end
+end