modal_stack 0.1.1

data/lib/modal_stack/helpers/modal_stack_assets_helper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ModalStack
+  module Helpers
+    # Layout-level helpers for wiring modal_stack into the host app.
+    module ModalStackAssetsHelper
+      # Renders a <link> for the configured CSS provider:
+      #
+      #   <%= modal_stack_stylesheet_link_tag %>
+      #
+      # 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
+        return ActiveSupport::SafeBuffer.new if provider == :none
+
+        stylesheet_link_tag("modal_stack/#{provider}", **)
+      end
+
+      # Renders the singleton <dialog> root that the modal-stack Stimulus
+      # controller binds to. Drop into your application layout:
+      #
+      #   <%= modal_stack_dialog_tag %>
+      #
+      def modal_stack_dialog_tag(**html_options)
+        config = ModalStack.configuration
+        attrs = html_options.dup
+        attrs[:id] ||= config.dialog_id
+
+        existing_data = attrs[:data] || {}
+        controllers = [existing_data[:controller], config.stack_root_data_attribute].compact.join(" ").strip
+        attrs[:data] = existing_data.merge(controller: controllers)
+
+        content_tag(:dialog, "".html_safe, attrs)
+      end
+
+      # Emits a no-op SafeBuffer for now — kept as a stable hook for apps
+      # that prefer a single line in their layout. The actual JS loading
+      # is handled by the host app's bundler / importmap.
+      def modal_stack_javascript_tag(**)
+        ActiveSupport::SafeBuffer.new
+      end
+    end
+  end
+end

data/lib/modal_stack/helpers/modal_stack_container_helper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ModalStack
+  module Helpers
+    # Wraps the layout content in the panel structure expected by the
+    # JS runtime.  The layout `modal.html.erb` typically reads:
+    #
+    #   <%= modal_stack_container size: :md, dismissible: true do %>
+    #     <%= yield %>
+    #   <% end %>
+    #
+    module ModalStackContainerHelper
+      DEFAULT_SIZE = :md
+
+      def modal_stack_container(size: DEFAULT_SIZE, dismissible: true, variant: :modal, side: nil, width: nil, height: nil, 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)
+      end
+    end
+  end
+end

data/lib/modal_stack/initializer_version_check.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ModalStack
+  module InitializerVersionCheck
+    module_function
+
+    def perform
+      return if ModalStack.configuration.silence_initializer_warning
+
+      stamped = ModalStack.configuration.initializer_version
+      shipped = ModalStack::INITIALIZER_VERSION
+
+      if stamped.nil?
+        warn(
+          "[modal_stack] config/initializers/modal_stack.rb has no " \
+          "config.initializer_version. The initializer template shipped " \
+          "with #{shipped} introduces options the older template did " \
+          "not have — regenerate with `bin/rails g modal_stack:install " \
+          "--skip-layout --force`. Set " \
+          "`config.silence_initializer_warning = true` to silence."
+        )
+      elsif stamped != shipped
+        warn(
+          "[modal_stack] config/initializers/modal_stack.rb is stamped " \
+          "for v#{stamped} but the gem ships v#{shipped}. The template " \
+          "may have new options — review the diff or regenerate with " \
+          "`bin/rails g modal_stack:install --skip-layout --force`. Set " \
+          "`config.silence_initializer_warning = true` to silence."
+        )
+      end
+    end
+  end
+end

data/lib/modal_stack/turbo_streams_extension.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ModalStack
+  # Custom Turbo Stream actions for stack manipulation. Mixed into
+  # Turbo::Streams::TagBuilder via the :turbo_streams_tag_builder load hook
+  # so the standard `turbo_stream.foo(...)` form keeps working alongside.
+  module TurboStreamsExtension
+    HISTORY_MODES = %i[push replace].freeze
+
+    # Push a new layer on top of the stack. The content is rendered using
+    # the same options as Turbo's standard stream actions
+    # (partial:/locals:/template:/...).
+    #
+    # variant:     :modal (default) | :drawer | :bottom_sheet | :confirmation
+    # dismissible: true (default) | false
+    # url:         override the URL associated with this layer (defaults to the request path)
+    # side:        only meaningful for :drawer — :left | :right | :top | :bottom
+    # size:        :sm | :md | :lg | :xl | string
+    # width/height: CSS length values (e.g. "42rem", "70vh", "min(90vw, 56rem)")
+    def modal_push(content = nil, variant: :modal, dismissible: true, url: nil, side: nil, size: nil, width: nil, height: nil, **rendering,
+                   &)
+      template = render_template(ModalStack::TARGET_ID, content, **rendering, &)
+      turbo_stream_action_tag(
+        :modal_push,
+        target: ModalStack::TARGET_ID,
+        template: template,
+        data: modal_data(variant: variant, dismissible: dismissible, url: url, side: side, size: size, width: width, height: height)
+      )
+    end
+
+    # Pop the top layer.
+    def modal_pop
+      turbo_stream_action_tag(:modal_pop, target: ModalStack::TARGET_ID)
+    end
+
+    # Replace the top layer's content. Defaults to history.replaceState
+    # (no new history entry). Pass history: :push for a wizard-step semantic
+    # where browser-back returns to the previous step.
+    def modal_replace(content = nil, variant: nil, dismissible: nil, url: nil, history: :replace, layer_id: nil, side: nil, size: nil,
+                      width: nil, height: nil, **rendering, &)
+      raise ArgumentError, "history: must be #{HISTORY_MODES.inspect}, got #{history.inspect}" unless HISTORY_MODES.include?(history)
+
+      template = render_template(ModalStack::TARGET_ID, content, **rendering, &)
+      turbo_stream_action_tag(
+        :modal_replace,
+        target: ModalStack::TARGET_ID,
+        template: template,
+        data: modal_data(
+          variant: variant,
+          dismissible: dismissible,
+          url: url,
+          side: side,
+          size: size,
+          width: width,
+          height: height,
+          history_mode: history,
+          layer_id: layer_id
+        )
+      )
+    end
+
+    # Tear down the entire stack.
+    def modal_close_all
+      turbo_stream_action_tag(:modal_close_all, target: ModalStack::TARGET_ID)
+    end
+
+    private
+
+    def modal_data(**attrs)
+      attrs.compact
+    end
+  end
+end

data/lib/modal_stack/version.rb

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

data/lib/modal_stack.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "modal_stack/version"
+
+module ModalStack
+  class Error < StandardError; end
+
+  # Default IDs / headers — exposed for code that needs the values
+  # without instantiating Configuration.  Configuration overrides them
+  # at the application level (config.dialog_id =, config.request_header =).
+  TARGET_ID = "modal-stack-root"
+  REQUEST_HEADER = "X-Modal-Stack-Request"
+
+  # 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.1.0"
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require_relative "modal_stack/configuration"
+require_relative "modal_stack/initializer_version_check"
+require "modal_stack/engine" if defined?(Rails::Engine)

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: modal_stack
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Florian Gagnaire
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: |
+  modal_stack adds a navigation stack on top of Hotwire: push N modals/drawers/bottom
+  sheets, deep-link the top of the stack via native Rails URLs, get full browser
+  history (back/forward) support, and drive everything from imperative Turbo Stream
+  actions (modal_push, modal_pop, modal_replace).
+email:
+- gagnaire.flo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- 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/vanilla.css
+- 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
+- app/javascript/modal_stack/install.js
+- app/javascript/modal_stack/orchestrator.js
+- app/javascript/modal_stack/orchestrator.test.js
+- app/javascript/modal_stack/runtime.js
+- app/javascript/modal_stack/runtime.test.js
+- app/javascript/modal_stack/state.js
+- app/javascript/modal_stack/state.test.js
+- app/views/layouts/modal.html.erb
+- lib/generators/modal_stack/install/install_generator.rb
+- lib/generators/modal_stack/install/templates/initializer.rb
+- lib/modal_stack.rb
+- lib/modal_stack/capybara.rb
+- lib/modal_stack/capybara/minitest.rb
+- lib/modal_stack/capybara/rspec.rb
+- lib/modal_stack/configuration.rb
+- lib/modal_stack/controller_extensions.rb
+- lib/modal_stack/engine.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
+- lib/modal_stack/initializer_version_check.rb
+- lib/modal_stack/turbo_streams_extension.rb
+- lib/modal_stack/version.rb
+homepage: https://github.com/Metalzoid/modal_stack
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Metalzoid/modal_stack
+  source_code_uri: https://github.com/Metalzoid/modal_stack
+  changelog_uri: https://github.com/Metalzoid/modal_stack/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Metalzoid/modal_stack/issues
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Stackable modals, drawers and bottom sheets for Hotwire-powered Rails apps.
+test_files: []