inertia_jb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5318dc498cde30ce2dfada1a46e68138c4a85dfef6a7cf275b411f861e059d67
+  data.tar.gz: abb2907bdaba0907f38376557c750e99d918988dc28e2b36e02bd209bbcedd37
+SHA512:
+  metadata.gz: 8039dfc4f8d98b88c328c622a007f9baf110bed9024b828443bac26ef12cc05853c5c59087b472f454de9dace0693c34cd864914822541f4be1879db76e7f500
+  data.tar.gz: 535c7d2247b8da621a0f55ab3973006b27a2dab97a0af71cfd2294bebd65b9a2406a5ab8ba6956c3097a5bbff85472e3c9b7db8a1f32b678ad1b8495d8a90168

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 kikyous
+
+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,190 @@
+# InertiaJb
+
+InertiaJb lets you declare [Inertia.js](https://inertiajs.com/) props
+for your Rails frontend components inside **view templates**, using plain Ruby
+Hashes powered by [jb](https://github.com/amatsuda/jb).
+
+It is built on top of the [inertia-rails](https://github.com/inertiajs/inertia-rails) gem.
+
+A `*.html.inertia` template is just Ruby code whose last expression is a Hash.
+That Hash is handed straight to `InertiaRails::Renderer`, so **every Inertia
+protocol feature works out of the box** — partial reloads (at any nesting
+depth), optional / always / deferred / scroll props, prop merging, shared data,
+and global key transforms.
+
+```ruby
+# app/controllers/messages_controller.rb
+class MessagesController < ApplicationController
+  # Shared props are merged in automatically.
+  inertia_share user: -> { Current.user }
+
+  def show
+    @message = Message.find(params[:id])
+  end
+end
+```
+
+```ruby
+# app/views/messages/show.html.inertia
+{
+  message: {
+    content: @message.content,
+    author: {
+      name: @message.author.name,
+      email: @message.author.email,
+      url: url_for(@message.author, format: :json)
+    },
+    comments: render(partial: "comments/comment", collection: @message.comments)
+  }
+}
+```
+
+```jsx
+// app/javascript/pages/messages/show.jsx
+export default function Message({ user, message }) {
+  return (
+    <div>
+      <p>Hi, {user.name}</p>
+      <p>{message.content}</p>
+      <a href={message.author.url}>
+        {message.author.name} &lt;{message.author.email}&gt;
+      </a>
+      {message.comments.map((c) => <Comment key={c.id} comment={c} />)}
+    </div>
+  );
+}
+```
+
+## Why jb?
+
+Inertia's server side is fundamentally about producing **a Hash of props** that
+`inertia-rails` then resolves and serializes. jb templates *are* plain Ruby
+Hashes, so there is zero impedance mismatch: no DSL to learn, no intermediate
+representation, and the full power of Ruby for building collections and
+conditionals.
+
+> Coming from `props_template`? That gem streams JSON strings, which don't map
+> cleanly onto Inertia's Hash-based resolver. jb's plain-Hash output is the
+> natural fit, which is why this gem is built on it.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "inertia_jb"
+```
+
+Then, in your inertia-rails initializer, **disable `default_render`** so that a
+normal implicit render falls through to your `.html.inertia` template:
+
+```ruby
+# config/initializers/inertia_rails.rb
+InertiaRails.configure do |config|
+  config.default_render = false
+end
+```
+
+You do **not** need to call `use_inertia_instance_props`.
+
+## Templates and partials
+
+- **Page templates** live at `app/views/<controller>/<action>.html.inertia` and
+  must return a Hash (your Inertia props).
+- **Partials** are ordinary [jb](https://github.com/amatsuda/jb) partials named
+  `_name.html.jb`. They return a Hash, and compose naturally:
+
+```ruby
+# app/views/messages/show.html.inertia
+{
+  author:   render(partial: "authors/author", object: @message.author),
+  comments: render(partial: "comments/comment", collection: @message.comments)
+}
+```
+
+```ruby
+# app/views/authors/_author.html.jb
+{ id: author.id, name: author.name }
+```
+
+`render(partial:, collection:)` returns an **array of Hashes** (thanks to jb),
+which you embed directly. Don't name partials `.html.inertia` — that extension
+triggers the Inertia response wrapper and is only for top-level page templates.
+
+## Inertia prop types
+
+Because props are just a Hash, Inertia's special prop types are plain values you
+drop in. Inside a `.html.inertia` template you can use the short helpers
+(`optional`, `always`, `defer`, `scroll`, `merge`, `deep_merge`) or the full
+`InertiaRails.*` methods.
+
+```ruby
+{
+  id:    @post.id,
+  title: @post.title,
+
+  # Only fetched when explicitly requested in a partial reload.
+  stats: optional { @post.expensive_stats },
+
+  # Always fetched, even if not requested in a partial reload.
+  settings: always { current_settings },
+
+  # Excluded from the initial load; fetched in a follow-up request.
+  comments: defer(group: :comments) {
+    render(partial: "comments/comment", collection: @post.comments)
+  },
+
+  # Infinite scrolling (accepts a paginator or explicit metadata).
+  feed: scroll(@pagy) {
+    render(partial: "feed/item", collection: @items)
+  }
+}
+```
+
+See the inertia-rails docs for [partial reloads](https://inertiajs.com/partial-reloads),
+[deferred props](https://inertiajs.com/deferred-props), and
+[infinite scroll](https://inertia-rails.dev/guide/infinite-scroll).
+
+## Caching
+
+Use plain Rails caching — you're caching Ruby Hashes:
+
+```ruby
+@posts.map do |post|
+  Rails.cache.fetch(post) { render(partial: "posts/post", object: post) }
+end
+```
+
+## camelCase keys
+
+If you configure inertia-rails' `prop_transformer` to camelize keys, it applies
+at **every nesting depth** — because your props reach inertia-rails as a real
+Hash:
+
+```ruby
+# config/initializers/inertia_rails.rb
+InertiaRails.configure do |config|
+  config.default_render = false
+  config.prop_transformer = ->(props:) { props.deep_transform_keys { |k| k.to_s.camelize(:lower) } }
+end
+```
+
+Alternatively, just write camelCase keys directly in your templates.
+
+## Notes
+
+- Inertia props must be an **object**, so page templates should return a Hash
+  (not a top-level Array).
+- Don't install this alongside `inertia-builder`; both register an `:inertia`
+  template handler.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

data/lib/inertia_jb/controller.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module InertiaJb
+  # Controller concern that makes `.html.inertia` templates behave like proper
+  # 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.
+  #
+  # +InertiaRails::Controller+ (which provides +inertia_share+, shared data and
+  # +default_render+) 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"
+    end
+  end
+end

data/lib/inertia_jb/handler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+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.
+  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"
+    end
+  end
+end

data/lib/inertia_jb/helper.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module InertiaJb
+  # Optional syntax sugar available inside `.html.inertia` templates, so you can
+  # write `optional { ... }` instead of `InertiaRails.optional { ... }`.
+  #
+  # These simply delegate to the +InertiaRails+ factory methods; the returned
+  # prop objects are resolved by +InertiaRails::PropsResolver+ when the page is
+  # built (respecting partial reloads, grouping, etc.).
+  module Helper
+    # Only fetched when explicitly requested in a partial reload.
+    def optional(&block)
+      ::InertiaRails.optional(&block)
+    end
+
+    # Always fetched, even when not requested in a partial reload.
+    def always(&block)
+      ::InertiaRails.always(&block)
+    end
+
+    # Excluded from the initial load; fetched in a follow-up request.
+    def defer(...)
+      ::InertiaRails.defer(...)
+    end
+
+    # Infinite-scroll prop (accepts a paginator or explicit metadata).
+    def scroll(...)
+      ::InertiaRails.scroll(...)
+    end
+
+    # Merged with existing client-side data instead of replacing it.
+    def merge(...)
+      ::InertiaRails.merge(...)
+    end
+
+    # Deep-merged with existing client-side data.
+    def deep_merge(...)
+      ::InertiaRails.deep_merge(...)
+    end
+  end
+end

data/lib/inertia_jb/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module InertiaJb
+  class Railtie < ::Rails::Railtie
+    initializer :inertia_jb do
+      ActiveSupport.on_load(:action_controller) do
+        include InertiaJb::Controller
+      end
+
+      ActiveSupport.on_load(:action_view) do
+        ActionView::Template.register_template_handler :inertia, InertiaJb::Handler
+        ActionView::Base.include InertiaJb::Helper
+      end
+    end
+  end
+end

data/lib/inertia_jb/renderer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module InertiaJb
+  # Bridges a props Hash (built by a `.html.inertia` template) to the Inertia
+  # protocol via +InertiaRails::Renderer+.
+  #
+  # 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)
+
+      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
+    end
+  end
+end

data/lib/inertia_jb/version.rb

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

data/lib/inertia_jb.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "jb"
+require "inertia_rails"
+
+require "inertia_jb/version"
+require "inertia_jb/handler"
+require "inertia_jb/renderer"
+require "inertia_jb/controller"
+require "inertia_jb/helper"
+require "inertia_jb/railtie" if defined?(Rails::Railtie)
+
+# InertiaJb lets you declare Inertia.js props for your Rails
+# frontend components inside view templates, using plain Ruby Hashes powered by
+# the {https://github.com/amatsuda/jb jb} renderer.
+#
+# A `*.html.inertia` template is Ruby code whose last expression is a Hash of
+# props. That Hash is handed straight to +InertiaRails::Renderer+, so every
+# Inertia protocol feature (partial reloads, optional/always/deferred props,
+# merging, shared data, key transforms) works out of the box.
+module InertiaJb
+end

data/test/controller_test.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "action_view/testing/resolvers"
+require "json"
+
+class TestController < ActionController::Base
+  include InertiaJb::Controller
+
+  layout "application"
+
+  # Shared props are merged in automatically by inertia-rails.
+  inertia_share user: -> { { name: "Alice" } }
+
+  def index; end
+
+  def nested; end
+
+  def collection
+    @products = [{ id: 10, name: "Keyboard" }, { id: 11, name: "Monitor" }]
+  end
+
+  def with_partial
+    @author = { id: 42, name: "John" }
+    @comments = [{ body: "first" }, { body: "second" }]
+  end
+
+  # optional (only on partial reload) + deferred (excluded on first load).
+  def special
+    @id = 1
+  end
+end
+
+class ControllerTest < ActionController::TestCase
+  tests TestController
+
+  TEMPLATES = {
+    "layouts/application.html.erb" => "<html><body><%= yield %></body></html>",
+    "test/index.html.inertia"      => "{ content: 'content' }",
+    "test/nested.html.inertia"     => "{ product: { id: 10, name: 'Keyboard', price: 29.99 } }",
+    "test/collection.html.inertia" => "{ products: @products.map { |p| { id: p[:id], name: p[:name] } } }",
+    "test/with_partial.html.inertia" =>
+      "{ author: render(partial: 'authors/author', object: @author), " \
+      "comments: render(partial: 'comments/comment', collection: @comments) }",
+    "authors/_author.html.jb"  => "{ id: author[:id], name: author[:name] }",
+    "comments/_comment.html.jb" => "{ body: comment[:body] }",
+    "test/special.html.inertia" =>
+      "{ id: @id, stats: optional { { visits: 42 } }, feed: defer(group: :feed) { [1, 2, 3] } }"
+  }.freeze
+
+  def setup
+    super
+
+    @routes = ActionDispatch::Routing::RouteSet.new
+    @routes.draw do
+      %i[index nested collection with_partial special].each do |action|
+        get action.to_s => "test##{action}"
+      end
+    end
+
+    resolver = ActionView::FixtureResolver.new(TEMPLATES)
+    @controller.prepend_view_path(resolver)
+  end
+
+  def teardown
+    super
+    @routes.clear!
+  end
+
+  # ---- basic rendering -----------------------------------------------------
+
+  def test_non_inertia_request_renders_html_with_data_page
+    get :index
+
+    assert_response :success
+    assert_equal "text/html; charset=utf-8", response.content_type
+    assert_nil response.headers["X-Inertia"]
+
+    assert_includes response.body, "<html><body>"
+    assert_includes response.body, 'id="app"'
+    assert_includes response.body, "data-page"
+    # component + a prop value survive into the escaped data-page payload.
+    assert_includes response.body, "test/index"
+    assert_includes response.body, "content"
+  end
+
+  def test_inertia_request_returns_json
+    inertia_get :index
+
+    assert_response :success
+    assert_equal "true", response.headers["X-Inertia"]
+    assert_includes response.headers["Vary"].to_s, "X-Inertia"
+
+    page = JSON.parse(response.body)
+    assert_equal "test/index", page["component"]
+    assert_equal "content", page.dig("props", "content")
+    assert_equal({}, page.dig("props", "errors"))
+    assert_equal false, page["encryptHistory"]
+  end
+
+  def test_shared_props_are_merged
+    inertia_get :index
+    page = JSON.parse(response.body)
+    assert_equal({ "name" => "Alice" }, page.dig("props", "user"))
+  end
+
+  def test_nested_props
+    inertia_get :nested
+    page = JSON.parse(response.body)
+    assert_equal({ "id" => 10, "name" => "Keyboard", "price" => 29.99 }, page.dig("props", "product"))
+  end
+
+  def test_collection_props
+    inertia_get :collection
+    page = JSON.parse(response.body)
+    assert_equal(
+      [{ "id" => 10, "name" => "Keyboard" }, { "id" => 11, "name" => "Monitor" }],
+      page.dig("props", "products")
+    )
+  end
+
+  # ---- jb partials ---------------------------------------------------------
+
+  def test_object_and_collection_partials
+    inertia_get :with_partial
+    page = JSON.parse(response.body)
+
+    assert_equal({ "id" => 42, "name" => "John" }, page.dig("props", "author"))
+    assert_equal([{ "body" => "first" }, { "body" => "second" }], page.dig("props", "comments"))
+  end
+
+  # ---- optional / deferred props ------------------------------------------
+
+  def test_optional_prop_excluded_on_full_visit
+    inertia_get :special
+    page = JSON.parse(response.body)
+
+    assert_equal 1, page.dig("props", "id")
+    refute page["props"].key?("stats"), "optional prop should be absent on a full visit"
+  end
+
+  def test_optional_prop_included_on_partial_reload
+    inertia_get :special,
+                headers: {
+                  "X-Inertia-Partial-Component" => "test/special",
+                  "X-Inertia-Partial-Data" => "stats"
+                }
+    page = JSON.parse(response.body)
+
+    assert_equal({ "visits" => 42 }, page.dig("props", "stats"))
+  end
+
+  def test_deferred_prop_is_listed_and_excluded_on_full_visit
+    inertia_get :special
+    page = JSON.parse(response.body)
+
+    refute page["props"].key?("feed"), "deferred prop should be absent on the initial load"
+    assert_equal({ "feed" => ["feed"] }, page["deferredProps"])
+  end
+
+  private
+
+  def inertia_get(action, headers: {})
+    headers.each { |k, v| @request.headers[k] = v }
+    @request.headers["X-Inertia"] = "true"
+    get action
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails"
+require "action_controller/railtie"
+
+require "inertia_rails"
+require "inertia_jb"
+require "active_support/testing/autorun"
+
+ActiveSupport.test_order = :random
+
+# Instantiate an Application in order to trigger the initializers (inertia-rails
+# engine, jb railtie, and our own railtie that registers the :inertia handler).
+Class.new(Rails::Application) do
+  config.secret_key_base = "secret"
+  config.eager_load = false
+end.initialize!
+
+InertiaRails.configure do |c|
+  c.always_include_errors_hash = true # comply with the Inertia protocol + silence deprecation
+end
+
+# Touch AV::Base so the :action_view on_load hooks (handler + helper) run before tests.
+ActionView::Base.inspect

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: inertia_jb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kikyous
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: inertia_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: jb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: InertiaJb lets you declare Inertia.js props for your Rails frontend components
+  inside `.html.inertia` view templates using plain Ruby Hashes, powered by the jb
+  renderer. Built on top of inertia_rails.
+email:
+- kikyous@163.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/inertia_jb.rb
+- lib/inertia_jb/controller.rb
+- lib/inertia_jb/handler.rb
+- lib/inertia_jb/helper.rb
+- lib/inertia_jb/railtie.rb
+- lib/inertia_jb/renderer.rb
+- lib/inertia_jb/version.rb
+- test/controller_test.rb
+- test/test_helper.rb
+homepage: https://github.com/kikyous/inertia_jb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/kikyous/inertia_jb/issues
+  source_code_uri: https://github.com/kikyous/inertia_jb
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Declare Inertia.js props in Rails view templates with plain Ruby Hashes (powered
+  by jb)
+test_files:
+- test/controller_test.rb
+- test/test_helper.rb