action_version_preview 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6d263561ee95f415d87df090bb1e0008500048a1a896c96ae2df8ba7690e6b7
+  data.tar.gz: fc72870345f275e9e40fe4d75a5bba496467239e577fb524ecfd2e4b9b740fb2
+SHA512:
+  metadata.gz: f8353f9edc0f76a49425d6a5147b814fc6ca82304c465c186f33a94a8c42f61cea4d8120c0f8c5332636f277705e43e3755f1d38b10706137902d356d5c98011
+  data.tar.gz: 87099d11c6a79710263dc7c5b8f58a0e91a066279f60a9f4ad8b2c2a011096f1e33b79db414719b61a237e4f755b0c3950dedc77dd48272135b5138a03e7af80

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,118 @@
+# ActionVersionPreview
+
+Preview multiple versions of your UI simultaneously using Rails' built-in view variants. No feature flags, no complex setup. Just create variant templates and visit them via URL.
+
+## Why?
+
+Feature flag gems like Flipper are designed for toggling features on/off for users, not for showing multiple versions at once. For design iterations and feedback collection, you want to open three browser tabs side by side, each showing a different version, all logged in as the same user.
+
+ActionVersionPreview makes this trivial using Rails' native view variants.
+
+<img width="2146" height="2014" alt="image" src="https://github.com/user-attachments/assets/c39b1305-ad14-4958-be39-d714d53d1990" />
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "action_version_preview"
+```
+
+Run `bundle install`. That's it. The concern is automatically included in all controllers.
+
+## Usage
+
+### 1. Create Variant Templates
+
+Rails looks for variant templates using this naming convention:
+
+```
+app/views/dashboard/show.html.erb           # default
+app/views/dashboard/show.html+v2.erb        # variant :v2
+app/views/dashboard/show.html+redesign.erb  # variant :redesign
+```
+
+This works for layouts, partials, mailers, and ViewComponent templates too.
+
+### 2. Visit the Variant URL
+
+```
+/dashboard           # renders show.html.erb
+/dashboard?vv=v2     # renders show.html+v2.erb
+/dashboard?vv=true   # renders default, but activates the switcher
+```
+
+### 3. Add the Variant Switcher (Optional)
+
+Drop the built-in switcher widget in your layout:
+
+```erb
+<%= variant_switcher %>
+```
+
+The switcher automatically detects available variants by scanning the view directory for `+variant` template files. It only appears when:
+- The `vv` param is present in the URL (e.g., `?vv=true` or `?vv=v2`)
+- The current action has variant templates available
+- The user can preview variants (dev/test by default)
+
+Standard Rails variants (`mobile`, `tablet`, `phone`, `desktop`) are excluded from detection.
+
+## Configuration
+
+Zero config is the default. But if you need to customize:
+
+```ruby
+# config/initializers/action_version_preview.rb
+ActionVersionPreview.configure do |config|
+  # Change the URL parameter (default: :vv)
+  config.param_name = :v
+
+  # Control who can preview variants (default: dev/test only)
+  # In production, you might want admins only:
+  config.access_check = ->(controller) {
+    Rails.env.development? ||
+    Rails.env.test? ||
+    controller.current_user&.admin?
+  }
+end
+```
+
+## Helper Methods
+
+These are available in controllers and views:
+
+| Method | Description |
+|--------|-------------|
+| `current_variant` | Returns the active variant symbol (e.g., `:v2`) or `nil` |
+| `detected_variants` | Returns array of variant names found for current action |
+| `variant_preview_active?` | Returns true if variant preview mode is active |
+| `can_preview_variants?` | Returns true if current user can access variants |
+| `variant_switcher` | Renders the switcher widget |
+
+## How It Works
+
+Under the hood, ActionVersionPreview sets `request.variant` based on the URL parameter. Rails' template resolver then automatically looks for matching variant templates.
+
+When you visit `/dashboard?vv=v2`:
+1. The `before_action` extracts `vv=v2` from params
+2. It sets `request.variant = :v2`
+3. Rails renders `show.html+v2.erb` instead of `show.html.erb`
+4. The switcher detects all `show.html+*.erb` variants in the view directory
+
+## Comparison: Feature Flags vs View Variants
+
+| Feature Flags (Flipper) | View Variants (This Gem) |
+|------------------------|--------------------------|
+| Toggle features on/off for users | Access all versions simultaneously |
+| One version "live" at a time | Side-by-side comparison in multiple tabs |
+| Percentage rollouts, A/B testing | Design iteration, feedback collection |
+| Requires database/Redis | Zero dependencies |
+
+## Requirements
+
+- Rails 7.0+ or 8.x
+- Ruby 3.1+
+
+## License
+
+MIT License. See [MIT-LICENSE](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/helpers/action_version_preview/switcher_helper.rb

@@ -0,0 +1,7 @@
+module ActionVersionPreview
+  module SwitcherHelper
+    def variant_switcher
+      render partial: "action_version_preview/variant_switcher"
+    end
+  end
+end

data/app/views/action_version_preview/_variant_switcher.html.erb

@@ -0,0 +1,13 @@
+<% if variant_preview_active? && detected_variants.any? %>
+  <div style="position: fixed; bottom: 1rem; right: 1rem; background: #18181b; color: white; padding: 0.75rem; border-radius: 0.5rem; box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1); z-index: 9999; font-size: 0.875rem; font-family: system-ui, -apple-system, sans-serif;">
+    <span style="color: #a1a1aa; margin-right: 0.5rem;">View:</span>
+    <%= link_to "Default",
+        url_for(request.params.except(ActionVersionPreview.param_name.to_s, ActionVersionPreview.param_name.to_sym)),
+        style: "padding: 0.25rem 0.5rem; border-radius: 0.25rem; text-decoration: none; color: white; #{current_variant.nil? ? 'background: #2563eb;' : ''}" %>
+    <% detected_variants.each do |variant| %>
+      <%= link_to variant.upcase,
+          url_for(request.params.merge(ActionVersionPreview.param_name => variant)),
+          style: "padding: 0.25rem 0.5rem; border-radius: 0.25rem; text-decoration: none; color: white; #{current_variant.to_s == variant ? 'background: #2563eb;' : ''}" %>
+    <% end %>
+  </div>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/action_version_preview/controller_methods.rb

@@ -0,0 +1,51 @@
+module ActionVersionPreview
+  module ControllerMethods
+    extend ActiveSupport::Concern
+
+    # Standard Rails variants that should be excluded from detection
+    STANDARD_VARIANTS = %w[mobile tablet phone desktop].freeze
+
+    included do
+      before_action :set_view_variant
+      helper_method :current_variant, :detected_variants, :can_preview_variants?, :variant_preview_active?
+    end
+
+    private
+
+    def set_view_variant
+      variant = params[ActionVersionPreview.param_name]
+      return unless variant.present?
+      return unless can_preview_variants?
+
+      # Set the variant if it's not just a truthy trigger value
+      request.variant = variant.to_sym unless variant.to_s == "true"
+    end
+
+    def current_variant
+      request.variant&.first
+    end
+
+    # Returns true if the variant preview mode is active (param is present)
+    def variant_preview_active?
+      params[ActionVersionPreview.param_name].present? && can_preview_variants?
+    end
+
+    # Auto-detect variant files for the current controller action
+    def detected_variants
+      @detected_variants ||= begin
+        view_path = Rails.root.join("app", "views", controller_path)
+        pattern = "#{action_name}.html+*.erb"
+
+        Dir.glob(view_path.join(pattern)).filter_map do |file|
+          match = File.basename(file).match(/\.html\+(\w+)\.erb$/)
+          variant = match[1] if match
+          variant unless STANDARD_VARIANTS.include?(variant)
+        end.sort
+      end
+    end
+
+    def can_preview_variants?
+      ActionVersionPreview.access_check.call(self)
+    end
+  end
+end

data/lib/action_version_preview/engine.rb

@@ -0,0 +1,14 @@
+require "action_version_preview/controller_methods"
+
+module ActionVersionPreview
+  class Engine < ::Rails::Engine
+    isolate_namespace ActionVersionPreview
+
+    initializer "action_version_preview.controller_methods" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include ActionVersionPreview::ControllerMethods
+        helper ActionVersionPreview::Engine.helpers
+      end
+    end
+  end
+end

data/lib/action_version_preview/version.rb

@@ -0,0 +1,3 @@
+module ActionVersionPreview
+  VERSION = "0.1.0"
+end

data/lib/action_version_preview.rb

@@ -0,0 +1,25 @@
+require "action_version_preview/version"
+require "action_version_preview/engine"
+
+module ActionVersionPreview
+  class << self
+    # The URL parameter name used to specify the variant (default: :vv)
+    # Example: /dashboard?vv=v2
+    attr_accessor :param_name
+
+    # Proc that determines if the current user can preview variants
+    # Default: always true in development/test, always false in production
+    # Example: ->(controller) { controller.current_user&.admin? }
+    attr_accessor :access_check
+  end
+
+  # Set sensible defaults
+  self.param_name = :vv
+  self.access_check = ->(controller) {
+    Rails.env.development? || Rails.env.test?
+  }
+
+  def self.configure
+    yield self
+  end
+end

data/lib/tasks/action_version_preview_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :action_version_preview do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: action_version_preview
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Avi Flombaum
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: A zero-config Rails engine that leverages Rails' view variants to let
+  you preview different versions of your UI simultaneously. Perfect for A/B design
+  comparisons, UI iterations, and collecting feedback on redesigns.
+email:
+- im@avi.nyc
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/helpers/action_version_preview/switcher_helper.rb
+- app/views/action_version_preview/_variant_switcher.html.erb
+- config/routes.rb
+- lib/action_version_preview.rb
+- lib/action_version_preview/controller_methods.rb
+- lib/action_version_preview/engine.rb
+- lib/action_version_preview/version.rb
+- lib/tasks/action_version_preview_tasks.rake
+homepage: https://github.com/aviflombaum/action_version_preview
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aviflombaum/action_version_preview
+  source_code_uri: https://github.com/aviflombaum/action_version_preview
+  changelog_uri: https://github.com/aviflombaum/action_version_preview/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Preview multiple view variants side-by-side using Rails' built-in view variants.
+test_files: []