RubyGems - inertia_jb - Versions diffs - 0.1.0 → 0.2.0 - Mend

inertia_jb 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

checksums.yaml +4 -4
data/README.md +34 -0
data/lib/inertia_jb/controller.rb +16 -30
data/lib/inertia_jb/handler.rb +7 -10
data/lib/inertia_jb/railtie.rb +1 -0
data/lib/inertia_jb/renderer.rb +26 -33
data/lib/inertia_jb/version.rb +1 -1
data/test/layout_suppression_test.rb +90 -0
data/test/layout_test.rb +136 -0
metadata +6 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5318dc498cde30ce2dfada1a46e68138c4a85dfef6a7cf275b411f861e059d67
-  data.tar.gz: abb2907bdaba0907f38376557c750e99d918988dc28e2b36e02bd209bbcedd37
+  metadata.gz: 73afc6da5300453502fb918b78a802c92401b8dbe91fa6307ed4523a664c9716
+  data.tar.gz: 0fb62ff6422c754317d18f6ddcf49cb46982822a931f72db2773999117ea9652
 SHA512:
-  metadata.gz: 8039dfc4f8d98b88c328c622a007f9baf110bed9024b828443bac26ef12cc05853c5c59087b472f454de9dace0693c34cd864914822541f4be1879db76e7f500
-  data.tar.gz: 535c7d2247b8da621a0f55ab3973006b27a2dab97a0af71cfd2294bebd65b9a2406a5ab8ba6956c3097a5bbff85472e3c9b7db8a1f32b678ad1b8495d8a90168
+  metadata.gz: cf13cab4f4de7bf9973354d12b590e58473c873a0eb07a84ea14b28a87d32e1ef6c57310c7255f4b7c92e828b66463e12d5d67c25f55c9cb12d558ac8e1d6970
+  data.tar.gz: '08e77238e1754dcdd0e2e74df5e984d38bab7c922ea9fa755495e09b50c056ef674eff9df8ea26dd0db3d91eca09ab1973b4744129da93064f691fccae40c4e9'

data/README.md CHANGED Viewed

@@ -87,6 +87,40 @@ end
 You do **not** need to call `use_inertia_instance_props`.
+## Layout
+On an **initial (non-XHR) page load** the `data-page` root element is wrapped in
+a layout; Inertia (XHR) visits always return a bare JSON body with no layout.
+The layout is chosen from inertia-rails' `config.layout`, matching
+`InertiaRails::Renderer`'s own semantics:
+```ruby
+# config/initializers/inertia_rails.rb
+InertiaRails.configure do |config|
+  config.default_render = false
+  # config.layout = true      # (default) use the controller's normal layout
+  # config.layout = "inertia" # use app/views/layouts/inertia.html.erb
+  # config.layout = false     # no layout — render just the <div id="app"> root
+end
+```
+- `true` / `nil` — the controller's default layout, resolved the normal Rails
+  way (`app/views/layouts/application.html.erb`, or any `layout "..."`
+  declaration in the controller).
+- A **String** — that named layout (`app/views/layouts/<name>.html.erb`).
+- `false` — no layout at all; the response is only the `<div id="app"
+  data-page="…">` root, so you provide `<html>`/`<head>`/asset tags elsewhere.
+Because `config.layout` is scoped per controller in inertia-rails, you can also
+set it on a single controller with `inertia_config layout: "..."`. Plain
+(non-Inertia) `.html.erb` actions in the same app keep their layout regardless
+of this setting.
+> **Note:** this gem does not perform server-side rendering (SSR), so
+> `inertia_ssr_head` in your layout will always be empty.
 ## Templates and partials
 - **Page templates** live at `app/views/<controller>/<action>.html.inertia` and

data/lib/inertia_jb/controller.rb CHANGED Viewed

@@ -1,42 +1,28 @@
 # frozen_string_literal: true
 module InertiaJb
-  # Controller concern that makes `.html.inertia` templates behave like proper
-  # Inertia responses.
+  # Controller concern that renders `.html.inertia` templates as Inertia
+  # responses.
   #
-  # Our {Renderer} only computes the page hash (it does not go through
-  # +InertiaRails::Renderer#render+), so we set the Inertia response headers and
-  # skip the layout for Inertia (XHR) requests here — mirroring inertia-builder.
+  # A `.html.inertia` page template is reached through Rails' normal implicit
+  # render. Its body (compiled by {Handler}) throws the props Hash back here,
+  # which aborts the implicit render — layout and all — before we re-render the
+  # page through inertia-rails' native renderer via `render inertia:`. Component
+  # resolution, shared data, `PropsResolver`/partial reloads, `config.layout`,
+  # SSR and the X-Inertia/Vary headers are therefore all handled by
+  # inertia-rails, identically to a plain inertia-rails app.
   #
-  # +InertiaRails::Controller+ (which provides +inertia_share+, shared data and
-  # +default_render+) is already mixed into +ActionController::Base+ by
+  # Plain (non-Inertia) `.html.erb` actions never throw, so `catch` falls
+  # through to `super` and they render exactly as in vanilla Rails.
+  #
+  # +InertiaRails::Controller+ is already mixed into +ActionController::Base+ by
   # inertia-rails' engine, so we don't include it again.
   module Controller
     extend ActiveSupport::Concern
-    included do
-      before_action :format_inertia_jb_response, if: -> { inertia_json_request? }
-    end
-    private
-    def format_inertia_jb_response
-      response.headers["Vary"] = if response.headers["Vary"].blank?
-                                   "X-Inertia"
-                                 else
-                                   "#{response.headers['Vary']}, X-Inertia"
-                                 end
-      response.set_header("X-Inertia", "true")
-    end
-    # Inertia (XHR) requests return a bare JSON body — no application layout.
-    # Initial page loads keep the layout so the `data-page` root is wrapped.
-    def action_has_layout?
-      !inertia_json_request? && super
-    end
-    def inertia_json_request?
-      request.headers["X-Inertia"] == "true"
+    def default_render(*)
+      props = catch(:__inertia_jb) { return super }
+      render(inertia: props)
     end
   end
 end

data/lib/inertia_jb/handler.rb CHANGED Viewed

@@ -4,21 +4,18 @@ module InertiaJb
   # ActionView template handler for `*.html.inertia` templates.
   #
   # An `.html.inertia` template is jb-style Ruby: its last expression is a Hash
-  # of Inertia props. We evaluate it, then hand the resulting Hash to
-  # {Renderer}, whose return value becomes the rendered body.
-  #
-  # Unlike props_template, there is no shared builder state to guard: jb
-  # partials each return their own Hash independently, so no `@__json`-style
-  # finalize dance is needed here.
+  # of Inertia props. The handler evaluates that Hash and immediately `throw`s
+  # it back to {Controller#default_render}, which hands it to inertia-rails'
+  # native renderer. The `throw` also aborts this implicit render (and the
+  # layout it was about to apply), so the handler emits no body of its own.
   class Handler
     def self.call(template, source = nil)
       source ||= template.source
       # `begin;#{source}` keeps the template's own line numbers aligned in
-      # backtraces. The begin/end block evaluates to the template's last
-      # expression (the props Hash).
-      "__inertia_props = begin;#{source}\nend\n" \
-        "::InertiaJb::Renderer.new(self, __inertia_props, true).render"
+      # backtraces. The block evaluates to the template's last expression (the
+      # props Hash), which we throw up to the controller to render.
+      "throw(:__inertia_jb, begin;#{source}\nend)"
     end
   end
 end

data/lib/inertia_jb/railtie.rb CHANGED Viewed

@@ -12,6 +12,7 @@ module InertiaJb
       ActiveSupport.on_load(:action_view) do
         ActionView::Template.register_template_handler :inertia, InertiaJb::Handler
         ActionView::Base.include InertiaJb::Helper
+        ActionView::TemplateRenderer.prepend InertiaJb::Renderer
       end
     end
   end

data/lib/inertia_jb/renderer.rb CHANGED Viewed

@@ -1,41 +1,34 @@
 # frozen_string_literal: true
 module InertiaJb
-  # Bridges a props Hash (built by a `.html.inertia` template) to the Inertia
-  # protocol via +InertiaRails::Renderer+.
+  # Prepended onto +ActionView::TemplateRenderer+ to guarantee that a
+  # `.html.inertia` template is never wrapped in a layout.
   #
-  # Because the props are already a plain Ruby Hash, +InertiaRails::Renderer+
-  # can walk them natively: shared data is merged in, Procs and prop objects
-  # (optional/always/defer/scroll) are resolved, and partial reloads are
-  # filtered at any nesting depth.
-  class Renderer
-    def initialize(view_context, props, component)
-      @view_context = view_context
-      @inertia_renderer = ::InertiaRails::Renderer.new(
-        component,
-        view_context.controller,
-        view_context.request,
-        view_context.response,
-        view_context.controller.method(:render),
-        props: props
-      )
-    end
-    def render
-      # `page` computes the full Inertia page hash (running PropsResolver)
-      # without triggering a controller render, so we can return the body
-      # ourselves from inside the template rendering pipeline.
-      page = @inertia_renderer.send(:page)
+  # An `.inertia` template's body (see {Handler}) throws its props Hash back to
+  # the controller before it produces any output, so a surrounding layout is
+  # always discarded. Left alone, Rails would still resolve and compile the
+  # controller's layout and emit phantom `render_layout.action_view` /
+  # `render_template.action_view` events for it — their `ensure` blocks fire as
+  # the `throw` unwinds the stack — whose timing absorbs the prop-building work,
+  # polluting request logs and APM traces with a layout render that never
+  # actually happened.
+  #
+  # +render_template+ is the one point where Rails has already resolved the
+  # template (so we can see its handler) but has not yet looked up the layout
+  # (`find_layout` runs one call deeper, in +render_with_layout+). Nulling the
+  # layout here for our handler skips the lookup entirely — cleanly, without the
+  # controller having to guess in advance which template an action will render.
+  #
+  # This only affects our own templates. The real Inertia shell is applied later
+  # by inertia-rails when it renders the `inertia` root template (an ERB
+  # template) with `config.layout`, and plain `.erb`/`.jb` templates keep their
+  # layouts exactly as in vanilla Rails.
+  module Renderer
+    private
-      if @view_context.request.headers["X-Inertia"]
-        page.to_json
-      else
-        @view_context.controller.render_to_string(
-          template: "inertia",
-          layout: false,
-          locals: { page: page }
-        )
-      end
+    def render_template(view, template, layout_name, locals)
+      layout_name = nil if template.handler == InertiaJb::Handler
+      super
     end
   end
 end

data/lib/inertia_jb/version.rb CHANGED Viewed

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

data/test/layout_suppression_test.rb ADDED Viewed

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+require "test_helper"
+require "action_view/testing/resolvers"
+# Regression test for the "phantom layout render" bug.
+#
+# An `.inertia` page throws its props before producing output, so the
+# controller's layout is always discarded. Rails must therefore never resolve,
+# compile, or *instrument* that layout while rendering the props template —
+# otherwise request logs and APM traces show a `crm/application` layout render
+# that never happened, with its timing absorbing the prop-building work.
+#
+# The controller here uses `layout "application"` but points Inertia at a
+# *different* shell (`config.layout = "inertia"`), so the two are easy to tell
+# apart in the instrumentation stream:
+#   * the `.inertia` props template must be rendered with NO layout, and
+#   * `layouts/application` must never be rendered at all.
+class SuppressLayoutController < ActionController::Base
+  include InertiaJb::Controller
+  layout "application"
+  inertia_config layout: "inertia"
+  def index; end
+end
+class LayoutSuppressionTest < ActionController::TestCase
+  tests SuppressLayoutController
+  TEMPLATES = {
+    "layouts/application.html.erb" => "<html><body><%= yield %></body></html>",
+    "layouts/inertia.html.erb"     => "<main data-inertia-shell=\"1\"><%= yield %></main>",
+    "suppress_layout/index.html.inertia" => "{ ok: true }"
+  }.freeze
+  def setup
+    super
+    @routes = ActionDispatch::Routing::RouteSet.new
+    @routes.draw { get "index" => "suppress_layout#index" }
+    @controller.prepend_view_path(ActionView::FixtureResolver.new(TEMPLATES))
+  end
+  def teardown
+    super
+    @routes.clear!
+  end
+  def test_inertia_template_is_rendered_without_a_layout
+    templates = capture("render_template.action_view") { get :index }
+    page = templates.find { |e| e.payload[:identifier].end_with?("index.html.inertia") }
+    assert page, "the .inertia props template should have been rendered"
+    assert_nil page.payload[:layout],
+               "the .inertia props template must be rendered without a layout, " \
+               "got #{page.payload[:layout].inspect}"
+  end
+  def test_controller_layout_is_never_rendered_for_an_inertia_page
+    layouts = capture("render_layout.action_view") { get :index }
+    identifiers = layouts.map { |e| e.payload[:identifier] }
+    assert identifiers.none? { |id| id.include?("layouts/application") },
+           "the controller layout must not be rendered for an Inertia page, saw #{identifiers.inspect}"
+    # Sanity check: the real Inertia shell (config.layout) still wraps the root.
+    assert identifiers.any? { |id| id.include?("layouts/inertia") },
+           "the Inertia shell layout should still wrap the data-page root, saw #{identifiers.inspect}"
+  end
+  def test_rendered_output_is_wrapped_only_by_the_inertia_shell
+    get :index
+    assert_response :success
+    assert_includes response.body, "data-inertia-shell"
+    assert_includes response.body, "data-page"
+    refute_includes response.body, "<html><body>"
+  end
+  private
+  # Collects the instrumentation events for `name` emitted while the block runs.
+  def capture(name)
+    events = []
+    subscriber = ActiveSupport::Notifications.subscribe(name) do |*args|
+      events << ActiveSupport::Notifications::Event.new(*args)
+    end
+    yield
+    events
+  ensure
+    ActiveSupport::Notifications.unsubscribe(subscriber)
+  end
+end

data/test/layout_test.rb ADDED Viewed

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+require "test_helper"
+require "action_view/testing/resolvers"
+require "json"
+# Controllers exercising inertia-rails' `config.layout` for initial page loads.
+# `config.layout` is scoped per controller class via `inertia_config`, so each
+# case gets its own controller and no global state is mutated.
+class LayoutDefaultController < ActionController::Base
+  include InertiaJb::Controller
+  layout "application"
+  # No `inertia_config` — `config.layout` defaults to `true`.
+  def index; end
+end
+class LayoutFalseController < ActionController::Base
+  include InertiaJb::Controller
+  layout "application"
+  inertia_config layout: false
+  def index; end
+end
+class LayoutNamedController < ActionController::Base
+  include InertiaJb::Controller
+  layout "application"
+  inertia_config layout: "inertia"
+  def index; end
+end
+# A plain (non-Inertia) HTML action living in an app that configured
+# `config.layout = false`. Its layout must behave like vanilla Rails.
+class PlainController < ActionController::Base
+  include InertiaJb::Controller
+  layout "application"
+  inertia_config layout: false
+  def index; end
+end
+module LayoutTestHelpers
+  TEMPLATES = {
+    "layouts/application.html.erb" => "<html><body><%= yield %></body></html>",
+    "layouts/inertia.html.erb"     => "<main data-inertia-layout=\"1\"><%= yield %></main>",
+    "layout_default/index.html.inertia" => "{ ok: true }",
+    "layout_false/index.html.inertia"   => "{ ok: true }",
+    "layout_named/index.html.inertia"   => "{ ok: true }",
+    "plain/index.html.erb"              => "plain-body-<%= 1 + 1 %>"
+  }.freeze
+  def setup
+    super
+    controller_path = @controller.class.controller_path
+    @routes = ActionDispatch::Routing::RouteSet.new
+    @routes.draw { get "index" => "#{controller_path}#index" }
+    @controller.prepend_view_path(ActionView::FixtureResolver.new(TEMPLATES))
+  end
+  def teardown
+    super
+    @routes.clear!
+  end
+end
+# config.layout = true (default): the controller's default layout wraps the root.
+class LayoutDefaultTest < ActionController::TestCase
+  include LayoutTestHelpers
+  tests LayoutDefaultController
+  def test_default_layout_wraps_the_data_page_root
+    get :index
+    assert_response :success
+    assert_includes response.body, "<html><body>"
+    assert_includes response.body, 'id="app"'
+    assert_includes response.body, "data-page"
+  end
+end
+# config.layout = false: no layout at all — just the bare `data-page` root.
+class LayoutFalseTest < ActionController::TestCase
+  include LayoutTestHelpers
+  tests LayoutFalseController
+  def test_disabled_layout_renders_bare_root
+    get :index
+    assert_response :success
+    assert_includes response.body, 'id="app"'
+    assert_includes response.body, "data-page"
+    refute_includes response.body, "<html><body>"
+    refute_includes response.body, "data-inertia-layout"
+  end
+  def test_xhr_still_returns_json_when_layout_disabled
+    @request.headers["X-Inertia"] = "true"
+    get :index
+    assert_equal "true", response.headers["X-Inertia"]
+    page = JSON.parse(response.body)
+    assert_equal true, page.dig("props", "ok")
+    refute_includes response.body, "data-page"
+  end
+end
+# config.layout = "inertia": the named layout wraps the root, not the
+# controller's own `layout "application"`.
+class LayoutNamedTest < ActionController::TestCase
+  include LayoutTestHelpers
+  tests LayoutNamedController
+  def test_named_layout_wraps_the_root
+    get :index
+    assert_response :success
+    assert_includes response.body, "data-inertia-layout"
+    assert_includes response.body, 'id="app"'
+    refute_includes response.body, "<html><body>"
+  end
+end
+# A non-Inertia `.html.erb` action must keep its layout even when the app set
+# `config.layout = false` for Inertia responses.
+class PlainHtmlLayoutTest < ActionController::TestCase
+  include LayoutTestHelpers
+  tests PlainController
+  def test_plain_html_action_is_unaffected_by_inertia_config_layout
+    get :index
+    assert_response :success
+    assert_includes response.body, "<html><body>"
+    assert_includes response.body, "plain-body-2"
+    refute_includes response.body, "data-page"
+  end
+end

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inertia_jb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - kikyous
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inertia_rails
@@ -85,6 +85,8 @@ files:
 - lib/inertia_jb/renderer.rb
 - lib/inertia_jb/version.rb
 - test/controller_test.rb
+- test/layout_suppression_test.rb
+- test/layout_test.rb
 - test/test_helper.rb
 homepage: https://github.com/kikyous/inertia_jb
 licenses:
@@ -115,4 +117,6 @@ summary: Declare Inertia.js props in Rails view templates with plain Ruby Hashes
   by jb)
 test_files:
 - test/controller_test.rb
+- test/layout_suppression_test.rb
+- test/layout_test.rb
 - test/test_helper.rb