modal_stack 0.2.0 → 0.4.1

data/lib/generators/modal_stack/views/templates/_panel.html.erb

@@ -0,0 +1,18 @@
+<%# modal_stack panel template — override this file to customise the HTML
+    structure that wraps every modal/drawer/bottom-sheet/confirmation panel.
+    Available locals:
+      content       — SafeBuffer, the yielded view content
+      back_button   — SafeBuffer | nil, pre-rendered back button (nil when back: false)
+      wrapper_attrs — Hash { class:, data:, ...extras } — must stay on the root element
+                      so the JS runtime can read its data attributes
+      size          — Symbol  :sm | :md | :lg | :xl
+      variant       — Symbol  :modal | :drawer | :bottom_sheet | :confirmation
+      dismissible   — Boolean
+      side          — Symbol | nil  :left | :right | :top | :bottom
+      width         — String | nil  CSS value (e.g. "42rem")
+      height        — String | nil  CSS value
+      transition    — Symbol | nil  :slide | :fade | :none %>
+<%= content_tag(:div, wrapper_attrs) do %>
+  <%= back_button %>
+  <%= content %>
+<% end %>

data/lib/generators/modal_stack/views/views_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module ModalStack
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :panel, type: :boolean, default: false,
+                           desc: "Copy only the panel partial"
+      class_option :dialog, type: :boolean, default: false,
+                            desc: "Copy only the dialog partial"
+
+      def copy_views
+        if options[:panel]
+          copy_panel
+        elsif options[:dialog]
+          copy_dialog
+        else
+          copy_panel
+          copy_dialog
+        end
+      end
+
+      def show_readme
+        say <<~TXT, :green
+
+          modal_stack views ejected to app/views/modal_stack/.
+
+          Edit the copied partials to override the default HTML structure.
+          The `wrapper_attrs` / `dialog_attrs` locals carry the required
+          data attributes — keep them on the root element so the JS runtime
+          continues to work.
+        TXT
+      end
+
+      private
+
+      def copy_panel
+        copy_file "_panel.html.erb", "app/views/modal_stack/_panel.html.erb"
+      end
+
+      def copy_dialog
+        copy_file "_dialog.html.erb", "app/views/modal_stack/_dialog.html.erb"
+      end
+    end
+  end
+end

data/lib/modal_stack/capybara.rb

@@ -14,6 +14,7 @@ module ModalStack
   module Capybara
     DIALOG_SELECTOR = "#modal-stack-root"
     LAYER_SELECTOR = '[data-modal-stack-target="layer"]:not([data-leaving])'
+    FRAME_SELECTOR = "[data-modal-stack-frame]:not([data-leaving])"
 
     # Scope Capybara matchers to a specific layer of the stack.
     #
@@ -81,5 +82,25 @@ module ModalStack
     def modal_stack_depth
       ::Capybara.current_session.all(:css, LAYER_SELECTOR, wait: 0).size
     end
+
+    # Capybara matcher: assert the top layer's path frame depth.
+    #
+    #   expect(page).to have_modal_frames(2)
+    #
+    # Layers without a path read as a single frame.
+    def have_modal_frames(count, **)
+      have_css("#{LAYER_SELECTOR}[data-frame-depth=\"#{count}\"]", **)
+    end
+
+    # Scope Capybara to the *current* frame inside the top (or specified)
+    # layer — i.e. the frame that's not animating out.
+    def within_modal_frame(depth: nil, **, &)
+      layers = ::Capybara.current_session.all(:css, LAYER_SELECTOR, minimum: 1, **)
+      layer = depth ? layers[depth - 1] : layers.last
+      raise ::Capybara::ElementNotFound, "no modal_stack layer at depth #{depth}" unless layer
+
+      frame = layer.first(:css, FRAME_SELECTOR, minimum: 1, **)
+      ::Capybara.current_session.within(frame, &)
+    end
   end
 end

data/lib/modal_stack/configuration.rb

@@ -11,11 +11,16 @@ module ModalStack
   #   end
   #
   class Configuration
-    CSS_PROVIDERS = %i[tailwind bootstrap vanilla none].freeze
+    CSS_PROVIDERS = %i[tailwind_v3 tailwind_v4 bootstrap vanilla none].freeze
+    # Aliases accepted on input, normalized to a canonical CSS_PROVIDERS value.
+    # `:tailwind` predates the v3/v4 split — keep it working, map to v3 (no change
+    # in rendered CSS for existing apps).
+    CSS_PROVIDER_ALIASES = { tailwind: :tailwind_v3 }.freeze
     ASSETS_MODES = %i[importmap jsbundling sprockets auto].freeze
     VARIANTS = %i[modal drawer bottom_sheet confirmation].freeze
     SIZES = %i[sm md lg xl].freeze
     MAX_DEPTH_STRATEGIES = %i[raise warn silent].freeze
+    PATH_TRANSITIONS = %i[slide fade none].freeze
 
     attr_accessor :default_classes,
                   :request_header,
@@ -33,29 +38,18 @@ module ModalStack
                 :default_size,
                 :default_dismissible,
                 :max_depth,
-                :max_depth_strategy
+                :max_depth_strategy,
+                :default_path_transition
 
     def initialize
-      @css_provider = :tailwind
-      @assets_mode = :auto
-      @default_variant = :modal
-      @default_size = :md
-      @default_dismissible = true
-      @max_depth = 5
-      @max_depth_strategy = :warn
-      @request_header = "X-Modal-Stack-Request"
-      @dialog_id = "modal-stack-root"
-      @stack_root_data_attribute = "modal-stack"
-      @respect_reduced_motion = true
-      @replace_turbo_confirm = false
-      @i18n_scope = "modal_stack"
-      @initializer_version = nil
-      @silence_initializer_warning = false
+      apply_behavior_defaults
+      apply_naming_defaults
       @default_classes = default_classes_hash
     end
 
     def css_provider=(value)
       value = value.to_sym
+      value = CSS_PROVIDER_ALIASES.fetch(value, value)
       raise ArgumentError, "css_provider must be one of #{CSS_PROVIDERS.inspect}, got #{value.inspect}" unless CSS_PROVIDERS.include?(value)
 
       @css_provider = value
@@ -110,8 +104,40 @@ module ModalStack
       @max_depth_strategy = value
     end
 
+    def default_path_transition=(value)
+      value = value.to_sym
+      unless PATH_TRANSITIONS.include?(value)
+        raise ArgumentError,
+              "default_path_transition must be one of #{PATH_TRANSITIONS.inspect}, got #{value.inspect}"
+      end
+
+      @default_path_transition = value
+    end
+
     private
 
+    def apply_behavior_defaults
+      @css_provider = :tailwind_v3
+      @assets_mode = :auto
+      @default_variant = :modal
+      @default_size = :md
+      @default_dismissible = true
+      @max_depth = 5
+      @max_depth_strategy = :warn
+      @default_path_transition = :slide
+      @respect_reduced_motion = true
+      @replace_turbo_confirm = false
+    end
+
+    def apply_naming_defaults
+      @request_header = "X-Modal-Stack-Request"
+      @dialog_id = "modal-stack-root"
+      @stack_root_data_attribute = "modal-stack"
+      @i18n_scope = "modal_stack"
+      @initializer_version = nil
+      @silence_initializer_warning = false
+    end
+
     def default_classes_hash
       {
         modal_panel: nil,

data/lib/modal_stack/controller_extensions.rb

@@ -5,7 +5,7 @@ module ModalStack
     extend ActiveSupport::Concern
 
     included do
-      helper_method :modal_stack_request?
+      helper_method :modal_stack_request?, :modal_stack_config
     end
 
     class_methods do
@@ -39,6 +39,13 @@ module ModalStack
       end
     end
 
+    # Request-scoped accessor for `ModalStack.configuration`. Memoized so
+    # helpers that read several config values per render hit the global
+    # singleton once instead of N times.
+    def modal_stack_config
+      @modal_stack_config ||= ModalStack.configuration
+    end
+
     # True when the current request was issued by the modal_stack JS runtime
     # (signaled by the X-Modal-Stack-Request header on the fetch).
     def modal_stack_request?

data/lib/modal_stack/engine.rb

@@ -9,9 +9,11 @@ module ModalStack
         require "modal_stack/helpers/modal_link_helper"
         require "modal_stack/helpers/modal_stack_container_helper"
         require "modal_stack/helpers/modal_stack_assets_helper"
+        require "modal_stack/helpers/modal_back_link_helper"
         include ModalStack::Helpers::ModalLinkHelper
         include ModalStack::Helpers::ModalStackContainerHelper
         include ModalStack::Helpers::ModalStackAssetsHelper
+        include ModalStack::Helpers::ModalBackLinkHelper
       end
     end
 

data/lib/modal_stack/helpers/modal_back_link_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ModalStack
+  module Helpers
+    # Renders a button (or link) that steps back through the top layer's
+    # path. Wired to the `modal-stack-back-link` Stimulus controller, which
+    # delegates to `orchestrator.pathBack`.
+    #
+    #   <%= modal_back_link "Back" %>
+    #   <%= modal_back_link "Back to step 1", steps: 2 %>
+    #   <%= modal_back_link class: "btn btn-link" do %>
+    #     <span aria-hidden="true">←</span> Back
+    #   <% end %>
+    module ModalBackLinkHelper
+      LINK_CONTROLLER = "modal-stack-back-link"
+      LINK_CLICK_ACTION = "click->modal-stack-back-link#trigger"
+
+      def modal_back_link(name = nil, options = {}, &block) # rubocop:disable Metrics/CyclomaticComplexity
+        if block
+          options = name.is_a?(Hash) ? name : {}
+          name = capture(&block)
+        end
+        options = options.dup
+        steps = Integer(options.delete(:steps) || 1)
+        raise ArgumentError, "steps must be a positive integer, got #{steps.inspect}" if steps < 1
+
+        options[:data] = back_link_data(options.delete(:data) || {}, steps)
+        options[:type] ||= "button"
+
+        button_tag(name || I18n.t("modal_stack.back", default: "Back"), **options)
+      end
+
+      private
+
+      def back_link_data(existing, steps)
+        existing.merge(
+          controller: merged_token(existing[:controller], LINK_CONTROLLER),
+          action: merged_token(existing[:action], LINK_CLICK_ACTION),
+          modal_stack_back_link_steps_value: steps
+        )
+      end
+
+      def merged_token(existing, addition)
+        [existing, addition].compact.join(" ").strip
+      end
+    end
+  end
+end

data/lib/modal_stack/helpers/modal_stack_assets_helper.rb

@@ -11,7 +11,7 @@ module ModalStack
       # Returns an empty SafeBuffer when `config.css_provider = :none`,
       # so apps can call this unconditionally.
       def modal_stack_stylesheet_link_tag(**)
-        provider = ModalStack.configuration.css_provider
+        provider = _modal_stack_config.css_provider
         return ActiveSupport::SafeBuffer.new if provider == :none
 
         stylesheet_link_tag("modal_stack/#{provider}", **)
@@ -23,12 +23,12 @@ module ModalStack
       #   <%= modal_stack_dialog_tag %>
       #
       def modal_stack_dialog_tag(**html_options)
-        config = ModalStack.configuration
+        config = _modal_stack_config
         attrs = html_options.dup
         attrs[:id] ||= config.dialog_id
         attrs[:data] = build_dialog_data(attrs[:data], config)
 
-        content_tag(:dialog, "".html_safe, attrs)
+        render partial: "modal_stack/dialog", locals: { dialog_attrs: attrs }
       end
 
       # Merges caller-provided data attrs with the gem-managed ones (controller,
@@ -48,6 +48,18 @@ module ModalStack
       def modal_stack_javascript_tag(**)
         ActiveSupport::SafeBuffer.new
       end
+
+      private
+
+      # Prefers the request-scoped accessor injected by ControllerExtensions
+      # so we hit `ModalStack.configuration` once per request, not per call.
+      # Falls back to the global singleton for non-controller render contexts
+      # (mailers, ActionCable, isolated view tests).
+      def _modal_stack_config
+        return modal_stack_config if respond_to?(:modal_stack_config, true)
+
+        ModalStack.configuration
+      end
     end
   end
 end

data/lib/modal_stack/helpers/modal_stack_container_helper.rb

@@ -12,24 +12,51 @@ module ModalStack
     module ModalStackContainerHelper
       DEFAULT_SIZE = :md
 
-      def modal_stack_container(size: DEFAULT_SIZE, dismissible: true, variant: :modal, side: nil, width: nil, height: nil, html: {},
-                                &)
+      def modal_stack_container(size: DEFAULT_SIZE, dismissible: true, variant: :modal, side: nil, width: nil, height: nil,
+                                back: false, transition: nil, html: {}, &)
+        attrs = build_panel_attrs(size: size, variant: variant, side: side,
+                                  dismissible: dismissible, width: width,
+                                  height: height, transition: transition, html: html)
+        body = capture(&)
+        back_html = back ? modal_stack_container_back_button : nil
+
+        render partial: "modal_stack/panel", locals: {
+          content: body, back_button: back_html, wrapper_attrs: attrs,
+          size: size, variant: variant, dismissible: dismissible,
+          side: side, width: width, height: height, transition: transition
+        }
+      end
+
+      private
+
+      def build_panel_attrs(size:, variant:, side:, dismissible:, width:, height:, transition:, html:)
         classes = ["modal-stack__panel", "modal-stack__panel--#{variant}", "modal-stack__panel--size-#{size}"]
         classes << "modal-stack__panel--side-#{side}" if side
 
-        attrs = {
-          class: [classes, html[:class]].compact.join(" "),
-          data: {
-            modal_stack_size: size,
-            modal_stack_variant: variant,
-            modal_stack_dismissible: dismissible.to_s,
-            modal_stack_side: side,
-            modal_stack_width: width,
-            modal_stack_height: height
-          }.merge(html.fetch(:data, {})).compact
-        }.merge(html.except(:class, :data))
-
-        content_tag(:div, capture(&), **attrs)
+        data = {
+          modal_stack_size: size, modal_stack_variant: variant,
+          modal_stack_dismissible: dismissible.to_s, modal_stack_side: side,
+          modal_stack_width: width, modal_stack_height: height,
+          modal_stack_transition: transition
+        }.merge(html.fetch(:data, {})).compact
+
+        { class: [classes, html[:class]].compact.join(" "), data: data }
+          .merge(html.except(:class, :data))
+      end
+
+      # The back button stays in the DOM at all depths and is hidden by CSS
+      # when the layer is on its first frame (`[data-frame-depth="1"]`).
+      # That keeps the wizard structure stable across path_to/path_back —
+      # no Stimulus state needed.
+      def modal_stack_container_back_button
+        label = (defined?(I18n) ? I18n.t("modal_stack.back", default: "Back") : "Back")
+        button_tag(
+          label,
+          type: "button",
+          class: "modal-stack__panel-back",
+          data: { action: "click->modal-stack#pathBack" },
+          aria: { label: label }
+        )
       end
     end
   end

data/lib/modal_stack/turbo_streams_extension.rb

@@ -6,6 +6,7 @@ module ModalStack
   # so the standard `turbo_stream.foo(...)` form keeps working alongside.
   module TurboStreamsExtension
     HISTORY_MODES = %i[push replace].freeze
+    PATH_TRANSITIONS = %i[slide fade none].freeze
 
     # Push a new layer on top of the stack. The content is rendered using
     # the same options as Turbo's standard stream actions
@@ -64,10 +65,65 @@ module ModalStack
       turbo_stream_action_tag(:modal_close_all, target: ModalStack::TARGET_ID)
     end
 
+    # Navigate forward inside the top layer's path. The current frame is
+    # cached in memory so a subsequent `modal_path_back` (or browser back)
+    # restores it without a network round-trip. Pass `stale: true` (or set
+    # `X-Modal-Stack-Stale: true` on the response) to force a refetch on
+    # back.
+    def modal_path_to(content = nil, url: nil, transition: nil, stale: false, layer_id: nil, **rendering, &)
+      template = render_template(ModalStack::TARGET_ID, content, **rendering, &)
+      turbo_stream_action_tag(
+        :modal_path_to,
+        target: ModalStack::TARGET_ID,
+        template: template,
+        data: modal_data(
+          url: url,
+          transition: validate_path_transition(resolved_path_transition(transition)),
+          stale: stale ? "true" : nil,
+          layer_id: layer_id
+        )
+      )
+    end
+
+    # Step back through the top layer's path. Defaults to one frame; pass
+    # `steps: N` to collapse multiple frames at once. Clamps at the first
+    # frame — does not close the layer.
+    def modal_path_back(steps: 1, transition: nil)
+      n = Integer(steps)
+      raise ArgumentError, "steps must be a positive integer, got #{steps.inspect}" if n < 1
+
+      turbo_stream_action_tag(
+        :modal_path_back,
+        target: ModalStack::TARGET_ID,
+        data: modal_data(
+          steps: n,
+          transition: validate_path_transition(resolved_path_transition(transition))
+        )
+      )
+    end
+
     private
 
     def modal_data(**attrs)
       attrs.compact
     end
+
+    def validate_path_transition(value)
+      return nil if value.nil?
+
+      sym = value.to_sym
+      unless PATH_TRANSITIONS.include?(sym)
+        raise ArgumentError, "transition must be one of #{PATH_TRANSITIONS.inspect}, got #{value.inspect}"
+      end
+
+      sym
+    end
+
+    # Falls back to the configured default when a call site doesn't
+    # specify a transition. Pass `transition: :none` to disable
+    # explicitly.
+    def resolved_path_transition(value)
+      value || ModalStack.configuration.default_path_transition
+    end
   end
 end

data/lib/modal_stack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ModalStack
-  VERSION = "0.2.0"
+  VERSION = "0.4.1"
 end

data/lib/modal_stack.rb

@@ -10,11 +10,15 @@ module ModalStack
   # at the application level (config.dialog_id =, config.request_header =).
   TARGET_ID = "modal-stack-root"
   REQUEST_HEADER = "X-Modal-Stack-Request"
+  # Response header set by `path_to` controllers to mark the just-rendered
+  # frame as stale — the JS runtime refetches instead of restoring from its
+  # in-memory cache when the user steps back to it.
+  STALE_HEADER = "X-Modal-Stack-Stale"
 
   # Bumped when config/initializers/modal_stack.rb gains/loses an option,
   # so apps that haven't regenerated their initializer get a one-line
   # boot warning.  Independent from the gem's VERSION.
-  INITIALIZER_VERSION = "0.2.0"
+  INITIALIZER_VERSION = "0.4.0"
 
   class << self
     def configuration

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: modal_stack
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Florian Gagnaire
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-03 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -70,8 +70,10 @@ files:
 - Rakefile
 - app/assets/javascripts/modal_stack.js
 - app/assets/stylesheets/modal_stack/bootstrap.css
-- app/assets/stylesheets/modal_stack/tailwind.css
+- app/assets/stylesheets/modal_stack/tailwind_v3.css
+- app/assets/stylesheets/modal_stack/tailwind_v4.css
 - app/assets/stylesheets/modal_stack/vanilla.css
+- app/javascript/modal_stack/controllers/modal_stack_back_link_controller.js
 - app/javascript/modal_stack/controllers/modal_stack_controller.js
 - app/javascript/modal_stack/controllers/modal_stack_link_controller.js
 - app/javascript/modal_stack/index.js
@@ -83,8 +85,13 @@ files:
 - app/javascript/modal_stack/state.js
 - app/javascript/modal_stack/state.test.js
 - app/views/layouts/modal.html.erb
+- app/views/modal_stack/_dialog.html.erb
+- app/views/modal_stack/_panel.html.erb
 - lib/generators/modal_stack/install/install_generator.rb
 - lib/generators/modal_stack/install/templates/initializer.rb
+- lib/generators/modal_stack/views/templates/_dialog.html.erb
+- lib/generators/modal_stack/views/templates/_panel.html.erb
+- lib/generators/modal_stack/views/views_generator.rb
 - lib/modal_stack.rb
 - lib/modal_stack/capybara.rb
 - lib/modal_stack/capybara/minitest.rb
@@ -92,6 +99,7 @@ files:
 - lib/modal_stack/configuration.rb
 - lib/modal_stack/controller_extensions.rb
 - lib/modal_stack/engine.rb
+- lib/modal_stack/helpers/modal_back_link_helper.rb
 - lib/modal_stack/helpers/modal_link_helper.rb
 - lib/modal_stack/helpers/modal_stack_assets_helper.rb
 - lib/modal_stack/helpers/modal_stack_container_helper.rb