rails_onboarding 0.6.1

data/app/views/rails_onboarding/templates/index.html.erb

@@ -0,0 +1,255 @@
+<div class="templates-index">
+  <div class="header">
+    <h1>Onboarding Templates</h1>
+    <p class="subtitle">Choose a pre-built onboarding flow to get started quickly</p>
+  </div>
+
+  <div class="templates-grid">
+    <% @templates.each do |template_key, template| %>
+      <div class="template-card" data-template-key="<%= template_key %>">
+        <div class="template-header">
+          <h2><%= template[:name] %></h2>
+          <span class="template-steps-count"><%= template[:steps]&.size || 0 %> steps</span>
+        </div>
+
+        <div class="template-description">
+          <p><%= template[:description] || "A #{template_key.to_s.titleize} onboarding flow" %></p>
+        </div>
+
+        <div class="template-steps-preview">
+          <h3>Steps included:</h3>
+          <ul>
+            <% (template[:steps] || []).each do |step| %>
+              <li>
+                <span class="step-icon"><%= step[:icon] %></span>
+                <span class="step-title"><%= step[:title] %></span>
+                <% if step[:skippable] %>
+                  <span class="step-badge optional">Optional</span>
+                <% else %>
+                  <span class="step-badge required">Required</span>
+                <% end %>
+              </li>
+            <% end %>
+          </ul>
+        </div>
+
+        <div class="template-actions">
+          <%= link_to 'Preview', template_path(template_key), class: 'btn btn-secondary' %>
+          <%= button_to 'Use This Template', apply_template_path(template_key), method: :post, class: 'btn btn-primary' %>
+        </div>
+      </div>
+    <% end %>
+  </div>
+
+  <div class="custom-template-section">
+    <h2>Create Custom Template</h2>
+    <p>Already have an onboarding flow configured? Save it as a custom template for future use.</p>
+    <%= button_to 'Save Current Flow as Template', '#', class: 'btn btn-outline', onclick: 'return false;' %>
+  </div>
+</div>
+
+<style>
+  .templates-index {
+    max-width: 1400px;
+    margin: 0 auto;
+    padding: 2rem;
+  }
+
+  .header {
+    margin-bottom: 3rem;
+    text-align: center;
+  }
+
+  .header h1 {
+    font-size: 2.5rem;
+    font-weight: bold;
+    margin-bottom: 0.5rem;
+  }
+
+  .subtitle {
+    color: #666;
+    font-size: 1.125rem;
+  }
+
+  .templates-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(400px, 1fr));
+    gap: 2rem;
+    margin-bottom: 3rem;
+  }
+
+  .template-card {
+    background: white;
+    border: 2px solid #e0e0e0;
+    border-radius: 12px;
+    padding: 2rem;
+    transition: all 0.3s;
+  }
+
+  .template-card:hover {
+    border-color: #007bff;
+    box-shadow: 0 4px 12px rgba(0, 123, 255, 0.1);
+    transform: translateY(-2px);
+  }
+
+  .template-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 1rem;
+    padding-bottom: 1rem;
+    border-bottom: 2px solid #f0f0f0;
+  }
+
+  .template-header h2 {
+    font-size: 1.5rem;
+    font-weight: 600;
+    margin: 0;
+  }
+
+  .template-steps-count {
+    background: #e9ecef;
+    padding: 0.25rem 0.75rem;
+    border-radius: 12px;
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: #495057;
+  }
+
+  .template-description {
+    margin-bottom: 1.5rem;
+  }
+
+  .template-description p {
+    color: #666;
+    line-height: 1.6;
+  }
+
+  .template-steps-preview h3 {
+    font-size: 1rem;
+    font-weight: 600;
+    margin-bottom: 0.75rem;
+    color: #333;
+  }
+
+  .template-steps-preview ul {
+    list-style: none;
+    padding: 0;
+    margin: 0 0 1.5rem 0;
+    max-height: 300px;
+    overflow-y: auto;
+  }
+
+  .template-steps-preview li {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.75rem;
+    background: #f8f9fa;
+    border-radius: 6px;
+    margin-bottom: 0.5rem;
+  }
+
+  .step-icon {
+    font-size: 1.25rem;
+  }
+
+  .step-title {
+    flex: 1;
+    font-weight: 500;
+  }
+
+  .step-badge {
+    padding: 0.125rem 0.5rem;
+    border-radius: 8px;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+  }
+
+  .step-badge.required {
+    background: #ffeaa7;
+    color: #856404;
+  }
+
+  .step-badge.optional {
+    background: #d1ecf1;
+    color: #0c5460;
+  }
+
+  .template-actions {
+    display: flex;
+    gap: 0.75rem;
+  }
+
+  .btn {
+    flex: 1;
+    padding: 0.75rem 1.5rem;
+    border-radius: 6px;
+    text-decoration: none;
+    text-align: center;
+    border: none;
+    cursor: pointer;
+    font-size: 0.875rem;
+    font-weight: 600;
+    transition: all 0.2s;
+  }
+
+  .btn-primary {
+    background: #007bff;
+    color: white;
+  }
+
+  .btn-primary:hover {
+    background: #0056b3;
+  }
+
+  .btn-secondary {
+    background: #6c757d;
+    color: white;
+  }
+
+  .btn-secondary:hover {
+    background: #545b62;
+  }
+
+  .btn-outline {
+    background: transparent;
+    color: #007bff;
+    border: 2px solid #007bff;
+  }
+
+  .btn-outline:hover {
+    background: #007bff;
+    color: white;
+  }
+
+  .custom-template-section {
+    background: #f8f9fa;
+    border-radius: 12px;
+    padding: 2rem;
+    text-align: center;
+  }
+
+  .custom-template-section h2 {
+    font-size: 1.5rem;
+    font-weight: 600;
+    margin-bottom: 0.5rem;
+  }
+
+  .custom-template-section p {
+    color: #666;
+    margin-bottom: 1.5rem;
+  }
+
+  /* Mobile responsiveness */
+  @media (max-width: 768px) {
+    .templates-grid {
+      grid-template-columns: 1fr;
+    }
+
+    .template-actions {
+      flex-direction: column;
+    }
+  }
+</style>

data/config/importmap.rb

@@ -0,0 +1,33 @@
+# Pin Rails Onboarding JavaScript modules for Importmap
+# These pins allow the engine's JavaScript to be loaded via importmap in the host application
+
+# Main application bundle
+pin "rails_onboarding/application", to: "rails_onboarding/application.js"
+
+# Core onboarding controllers
+pin "rails_onboarding/onboarding_controller", to: "rails_onboarding/onboarding_controller.js"
+pin "rails_onboarding/progress_controller", to: "rails_onboarding/progress_controller.js"
+pin "rails_onboarding/navigation_controller", to: "rails_onboarding/navigation_controller.js"
+
+# Tooltip system controllers
+pin "rails_onboarding/tooltip_controller", to: "rails_onboarding/tooltip_controller.js"
+pin "rails_onboarding/tooltip_scheduler_controller", to: "rails_onboarding/tooltip_scheduler_controller.js"
+
+# Tour and progressive disclosure
+pin "rails_onboarding/tour_controller", to: "rails_onboarding/tour_controller.js"
+pin "rails_onboarding/progressive_disclosure_controller", to: "rails_onboarding/progressive_disclosure_controller.js"
+
+# Milestone system controllers
+pin "rails_onboarding/milestone_celebration_controller", to: "rails_onboarding/milestone_celebration_controller.js"
+pin "rails_onboarding/milestone_dashboard_controller", to: "rails_onboarding/milestone_dashboard_controller.js"
+pin "rails_onboarding/milestone_detail_controller", to: "rails_onboarding/milestone_detail_controller.js"
+
+# Admin controllers
+pin "rails_onboarding/admin/chart_controller", to: "rails_onboarding/admin/chart_controller.js"
+pin "rails_onboarding/admin/filter_controller", to: "rails_onboarding/admin/filter_controller.js"
+pin "rails_onboarding/admin/flash_controller", to: "rails_onboarding/admin/flash_controller.js"
+pin "rails_onboarding/admin/flow_editor_controller", to: "rails_onboarding/admin/flow_editor_controller.js"
+
+# External dependencies (if using Stimulus from importmap)
+# Uncomment if your host app doesn't already pin these
+# pin "@hotwired/stimulus", to: "https://ga.jspm.io/npm:@hotwired/stimulus@3.2.2/dist/stimulus.js"

data/config/locales/en.yml

@@ -0,0 +1,62 @@
+en:
+  rails_onboarding:
+    # Navigation
+    navigation:
+      next: "Next"
+      back: "Back"
+      skip: "Skip"
+      skip_all: "Skip All"
+      finish: "Finish"
+      restart: "Restart"
+
+    # Actions
+    actions:
+      complete: "Complete"
+      continue: "Continue"
+      get_started: "Get Started"
+
+    # Messages
+    messages:
+      welcome: "Welcome!"
+      completed: "Congratulations! You've completed the onboarding."
+      skipped: "You can explore features at your own pace."
+      restarted: "Onboarding has been restarted."
+      cannot_go_back: "Cannot go back from the first step."
+      cannot_skip: "This step cannot be skipped."
+      error: "An error occurred. Please try again."
+      validation_error: "Unable to save changes: %{errors}"
+
+    # Progress
+    progress:
+      step_of: "Step %{current} of %{total}"
+      percent_complete: "%{percent}% complete"
+
+    # Tooltips
+    tooltips:
+      dismiss: "Got it"
+      next_tip: "Next tip"
+      close: "Close"
+
+    # Milestones
+    milestones:
+      achievement_unlocked: "Achievement Unlocked!"
+      points_earned: "%{points} points earned"
+      view_all: "View all achievements"
+
+    # Errors
+    errors:
+      failed_to_save: "Failed to save your progress"
+      step_not_found: "Step not found"
+      invalid_action: "Invalid action"
+      session_expired: "Your session has expired. Please refresh the page."
+      network_error: "Network error. Please check your connection."
+
+    # Common
+    common:
+      loading: "Loading..."
+      saving: "Saving..."
+      please_wait: "Please wait..."
+      cancel: "Cancel"
+      confirm: "Confirm"
+      yes: "Yes"
+      no: "No"

data/config/locales/es.yml

@@ -0,0 +1,62 @@
+es:
+  rails_onboarding:
+    # Navigation
+    navigation:
+      next: "Siguiente"
+      back: "Atrás"
+      skip: "Omitir"
+      skip_all: "Omitir Todo"
+      finish: "Finalizar"
+      restart: "Reiniciar"
+
+    # Actions
+    actions:
+      complete: "Completar"
+      continue: "Continuar"
+      get_started: "Comenzar"
+
+    # Messages
+    messages:
+      welcome: "¡Bienvenido!"
+      completed: "¡Felicitaciones! Has completado la integración."
+      skipped: "Puedes explorar las funciones a tu propio ritmo."
+      restarted: "La integración ha sido reiniciada."
+      cannot_go_back: "No se puede retroceder desde el primer paso."
+      cannot_skip: "Este paso no se puede omitir."
+      error: "Ocurrió un error. Por favor, inténtalo de nuevo."
+      validation_error: "No se pudieron guardar los cambios: %{errors}"
+
+    # Progress
+    progress:
+      step_of: "Paso %{current} de %{total}"
+      percent_complete: "%{percent}% completado"
+
+    # Tooltips
+    tooltips:
+      dismiss: "Entendido"
+      next_tip: "Siguiente consejo"
+      close: "Cerrar"
+
+    # Milestones
+    milestones:
+      achievement_unlocked: "¡Logro Desbloqueado!"
+      points_earned: "%{points} puntos ganados"
+      view_all: "Ver todos los logros"
+
+    # Errors
+    errors:
+      failed_to_save: "No se pudo guardar tu progreso"
+      step_not_found: "Paso no encontrado"
+      invalid_action: "Acción inválida"
+      session_expired: "Tu sesión ha expirado. Por favor, actualiza la página."
+      network_error: "Error de red. Por favor, verifica tu conexión."
+
+    # Common
+    common:
+      loading: "Cargando..."
+      saving: "Guardando..."
+      please_wait: "Por favor, espera..."
+      cancel: "Cancelar"
+      confirm: "Confirmar"
+      yes: "Sí"
+      no: "No"

data/config/locales/fr.yml

@@ -0,0 +1,62 @@
+fr:
+  rails_onboarding:
+    # Navigation
+    navigation:
+      next: "Suivant"
+      back: "Retour"
+      skip: "Passer"
+      skip_all: "Tout Passer"
+      finish: "Terminer"
+      restart: "Recommencer"
+
+    # Actions
+    actions:
+      complete: "Compléter"
+      continue: "Continuer"
+      get_started: "Commencer"
+
+    # Messages
+    messages:
+      welcome: "Bienvenue!"
+      completed: "Félicitations! Vous avez terminé l'intégration."
+      skipped: "Vous pouvez explorer les fonctionnalités à votre rythme."
+      restarted: "L'intégration a été redémarrée."
+      cannot_go_back: "Impossible de revenir en arrière depuis la première étape."
+      cannot_skip: "Cette étape ne peut pas être ignorée."
+      error: "Une erreur s'est produite. Veuillez réessayer."
+      validation_error: "Impossible d'enregistrer les modifications: %{errors}"
+
+    # Progress
+    progress:
+      step_of: "Étape %{current} sur %{total}"
+      percent_complete: "%{percent}% terminé"
+
+    # Tooltips
+    tooltips:
+      dismiss: "Compris"
+      next_tip: "Conseil suivant"
+      close: "Fermer"
+
+    # Milestones
+    milestones:
+      achievement_unlocked: "Succès Débloqué!"
+      points_earned: "%{points} points gagnés"
+      view_all: "Voir tous les succès"
+
+    # Errors
+    errors:
+      failed_to_save: "Échec de l'enregistrement de votre progression"
+      step_not_found: "Étape non trouvée"
+      invalid_action: "Action invalide"
+      session_expired: "Votre session a expiré. Veuillez actualiser la page."
+      network_error: "Erreur réseau. Veuillez vérifier votre connexion."
+
+    # Common
+    common:
+      loading: "Chargement..."
+      saving: "Enregistrement..."
+      please_wait: "Veuillez patienter..."
+      cancel: "Annuler"
+      confirm: "Confirmer"
+      yes: "Oui"
+      no: "Non"

data/config/routes.rb

@@ -0,0 +1,79 @@
+RailsOnboarding::Engine.routes.draw do
+  # Test-only route for setting session in integration tests (no URL helpers needed)
+  post "test_session", to: "test_sessions#create", as: nil if Rails.env.test?
+
+  # Regular web routes. path: "" anchors the onboarding flow at the engine's
+  # mount point, so the host app's mount path alone controls the URL -
+  # `mount ... => "/onboarding"` yields /onboarding, not /onboarding/onboarding.
+  resource :onboarding, only: [ :show ], controller: "onboarding", path: "" do
+    post :next
+    post :complete
+    post :skip
+    post :back
+    post :restart
+  end
+
+  # Tooltip routes
+  post "tooltips/dismiss", to: "tooltips#dismiss", as: :dismiss_tooltip
+  post "tooltips/show", to: "tooltips#show", as: :show_tooltip
+  post "tooltips/reset", to: "tooltips#reset", as: :reset_tooltips
+  get "tooltips/status", to: "tooltips#status", as: :tooltip_status
+
+  resources :tooltips, only: [] do
+    member do
+      post :mark_shown
+    end
+  end
+
+  resources :milestones, only: [ :index, :show ] do
+    collection do
+      get :recent
+      post :achieve
+      get :progress
+      post :trigger
+      get :available
+    end
+    member do
+      get :check
+    end
+  end
+
+  # Admin interface
+  namespace :admin do
+    # Dashboard
+    get "/", to: "dashboard#index", as: :dashboard
+
+    # User management
+    resources :users, only: [ :index, :show ] do
+      member do
+        post :reset_onboarding
+        post :complete_onboarding
+        post :restart_onboarding
+      end
+      collection do
+        post :bulk_action
+        get :export
+      end
+    end
+
+    # Flow editor
+    resources :flows do
+      member do
+        post :duplicate
+        post :activate
+        get :preview
+      end
+    end
+
+    # A/B test management - tests are defined in the host app's initializer
+    # (RailsOnboarding.configuration.ab_tests), so only viewing and toggling
+    # them on/off is supported here, not creating or deleting them.
+    resources :ab_tests, only: [ :index, :show ] do
+      member do
+        post :start
+        post :stop
+        get :export
+      end
+    end
+  end
+end

data/lib/generators/rails_onboarding/install_generator.rb

@@ -0,0 +1,124 @@
+require "rails/generators/base"
+require "rails/generators/migration"
+
+module RailsOnboarding
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(path)
+        @prev_migration_nr = if @prev_migration_nr
+          @prev_migration_nr + 1
+        else
+          Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        end
+        @prev_migration_nr.to_s
+      end
+
+      def validate_environment
+        # Validate that we're in a Rails app
+        unless defined?(Rails)
+          raise "This generator must be run within a Rails application"
+        end
+
+        # Validate template paths exist
+        validate_template_paths!
+
+        # Validate User model exists
+        validate_user_model!
+      end
+
+      def copy_migration
+        migration_template "add_onboarding_to_users.rb",
+                           "db/migrate/add_onboarding_to_users.rb"
+      end
+
+      def copy_analytics_migration
+        migration_template "add_analytics_to_rails_onboarding.rb",
+                           "db/migrate/add_analytics_to_rails_onboarding.rb"
+      end
+
+      def copy_flows_migration
+        migration_template "create_rails_onboarding_flows.rb",
+                           "db/migrate/create_rails_onboarding_flows.rb"
+      end
+
+      def copy_milestone_tracking_migration
+        migration_template "add_milestone_tracking_to_users.rb",
+                           "db/migrate/add_milestone_tracking_to_users.rb"
+      end
+
+      def copy_onboarding_indexes_migration
+        migration_template "add_onboarding_indexes.rb",
+                           "db/migrate/add_onboarding_indexes.rb"
+      end
+
+      def copy_robustness_fields_migration
+        migration_template "add_robustness_fields_to_users.rb.tt",
+                           "db/migrate/add_robustness_fields_to_users.rb"
+      end
+
+      def copy_initializer
+        template "rails_onboarding.rb", "config/initializers/rails_onboarding.rb"
+      end
+
+      def add_route
+        route 'mount RailsOnboarding::Engine => "/onboarding"'
+      end
+
+      def copy_stylesheets
+        copy_file "onboarding.css",
+                  "app/assets/stylesheets/rails_onboarding_custom.css"
+      end
+
+      def display_readme
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def validate_template_paths!
+        required_templates = [
+          "add_onboarding_to_users.rb",
+          "add_analytics_to_rails_onboarding.rb",
+          "create_rails_onboarding_flows.rb",
+          "add_milestone_tracking_to_users.rb",
+          "add_onboarding_indexes.rb",
+          "add_robustness_fields_to_users.rb.tt",
+          "rails_onboarding.rb",
+          "onboarding.css",
+          "README"
+        ]
+
+        missing_templates = required_templates.reject do |template|
+          File.exist?(File.join(self.class.source_root, template))
+        end
+
+        if missing_templates.any?
+          raise "Missing required template files: #{missing_templates.join(', ')}"
+        end
+      end
+
+      def validate_user_model!
+        # Use destination_root in test environment, Rails.root otherwise
+        root_path = respond_to?(:destination_root) ? destination_root : Rails.root
+        user_model_path = File.join(root_path, "app/models/user.rb")
+
+        unless File.exist?(user_model_path)
+          say_status :error, "User model not found at app/models/user.rb", :red
+          say ""
+          say "RailsOnboarding requires a User model to exist.", :yellow
+          say "Please create a User model before running this generator:", :yellow
+          say ""
+          say "  rails generate model User email:string", :green
+          say ""
+          raise "User model does not exist. Please create it first."
+        end
+
+        say_status :check, "User model found", :green
+      end
+    end
+  end
+end