modal_stack 0.3.0 → 0.4.1

data/lib/modal_stack/configuration.rb

@@ -20,6 +20,7 @@ module ModalStack
     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,
@@ -37,24 +38,12 @@ module ModalStack
                 :default_size,
                 :default_dismissible,
                 :max_depth,
-                :max_depth_strategy
+                :max_depth_strategy,
+                :default_path_transition
 
     def initialize
-      @css_provider = :tailwind_v3
-      @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
 
@@ -115,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/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

@@ -28,7 +28,7 @@ module ModalStack
         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,

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.3.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.3.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.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Florian Gagnaire
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-08 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -73,6 +73,7 @@ files:
 - 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
@@ -84,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
@@ -93,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