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

inertia_jb 0.2.0 → 0.3.1

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 (7) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73afc6da5300453502fb918b78a802c92401b8dbe91fa6307ed4523a664c9716
-  data.tar.gz: 0fb62ff6422c754317d18f6ddcf49cb46982822a931f72db2773999117ea9652
+  metadata.gz: 37e2ba2d8b4c896a4a4f7f006aa32cbee162cc7b798a77e78daab8a305512c65
+  data.tar.gz: 7d1f22f9ba1596965f7d8fc52c7ccc3f7f7aae78d3a1093464b77791ed858a27
 SHA512:
-  metadata.gz: cf13cab4f4de7bf9973354d12b590e58473c873a0eb07a84ea14b28a87d32e1ef6c57310c7255f4b7c92e828b66463e12d5d67c25f55c9cb12d558ac8e1d6970
-  data.tar.gz: '08e77238e1754dcdd0e2e74df5e984d38bab7c922ea9fa755495e09b50c056ef674eff9df8ea26dd0db3d91eca09ab1973b4744129da93064f691fccae40c4e9'
+  metadata.gz: 69f29e30c55a3efe39d54695948fec6de98ef96cf1a788dcb7806fb05186bc6e04f3f92cdb4ae5d175457489b042a1a3d5c8e692df2fdb07d7559d22f13edea3
+  data.tar.gz: c666ba929d8d67a7daaed36b39985ac9642b546d182dbccf30abc0281b5c115daef7f395157bbee6a0e35943c29cdb5b2ce84d07a528993d6ee528db0e269eea

data/README.md CHANGED Viewed

@@ -63,9 +63,6 @@ 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
@@ -93,33 +90,8 @@ 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:
+`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
@@ -145,11 +117,75 @@ of this setting.
 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.
+## Sharing a partial with a plain JSON API
+An Inertia page and a plain JSON endpoint are both, in the end, just **a Hash**,
+so a single jb partial can back both. Name the partial **without a format**
+(`_message.jb`, not `_message.html.jb`) so it resolves for the `html` format
+Inertia uses *and* the `json` format a normal API request uses:
+```ruby
+# app/views/messages/_message.jb
+{
+  id:      message.id,
+  content: message.content,
+  author:  render(partial: "authors/author", object: message.author)
+}
+```
+```ruby
+# app/views/messages/show.html.inertia   — the Inertia page
+{ **render(partial: "messages/message", object: @message) }
+```
+```ruby
+# app/views/messages/index.html.inertia   — nested under a key
+{ messages: render(partial: "messages/message", collection: @messages, as: :message) }
+```
+```ruby
+# app/views/messages/show.json.jb        — a plain JSON endpoint
+render(partial: "messages/message", object: @message)
+```
+Note the asymmetry: the JSON endpoint can return that Array at the top level,
+but the Inertia page **must** nest it under a key (`{ posts: … }`) — Inertia
+props must be an object, never a top-level Array.
+> **Gotcha — wrap the page template in a Hash literal.** A `.html.inertia` page
+> must **not** be a bare top-level `render(partial: …)`:
+>
+> ```ruby
+> # ❌ props get misread as the component name
+> render(partial: "messages/message", object: @message)
+>
+> # ✅ spread into a real Hash literal
+> { **render(partial: "messages/message", object: @message) }
+> ```
+>
+> jb's `render(partial:)` returns a `Jb::TemplateResult` (a delegator), not a
+> true `Hash`. inertia-rails decides *"is this props or a component name?"* with
+> `component.is_a?(Hash)`, so a bare partial result is taken for a component name
+> and your props end up in the `component` field. Wrapping it in a literal
+> `{ **… }` — or nesting it under a key, e.g. `{ message: render(…) }` — makes
+> the top-level value a genuine `Hash`, which inertia-rails reads as props. A
+> `.json.jb` endpoint never hits this, because jb serializes its top-level result
+> with `to_json` directly.
+If you'd rather keep a format-specific partial (`_message.json.jb`), borrow the
+`:json` variant from the Inertia side with `formats:`:
+```ruby
+# app/views/messages/show.html.inertia
+{ **render(partial: "messages/message", object: @message, formats: [:json]) }
+```
 ## 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
+(`optional`, `always`, `defer`, `scroll`, `merge`, `deep_merge`, `once`, `cache`) or the full
 `InertiaRails.*` methods.
 ```ruby
@@ -171,23 +207,24 @@ drop in. Inside a `.html.inertia` template you can use the short helpers
   # Infinite scrolling (accepts a paginator or explicit metadata).
   feed: scroll(@pagy) {
     render(partial: "feed/item", collection: @items)
+  },
+  # Sent once and cached client-side; skipped on later visits until reset.
+  flash: once { session.delete(:flash) },
+  # Server-side cached via Rails.cache; the block's JSON output is reused
+  # across requests until the cache entry expires.
+  report: cache("posts/#{@post.id}/report", expires_in: 5.minutes) {
+    render(partial: "reports/report", object: @post.report)
   }
 }
 ```
 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
-```
+[deferred props](https://inertiajs.com/deferred-props),
+[infinite scroll](https://inertia-rails.dev/guide/infinite-scroll),
+[once props](https://inertia-rails.dev/guide/once-props), and
+[prop caching](https://inertia-rails.dev/guide/prop-caching).
 ## camelCase keys

data/lib/inertia_jb/helper.rb CHANGED Viewed

@@ -4,38 +4,78 @@ 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.).
+  # These 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.).
+  #
+  # Every block is bound to the current view with {InertiaJb.bind_to_view} so
+  # that a lazy prop's block runs in the *same* context an eager prop would —
+  # see that method for why this matters.
   module Helper
     # Only fetched when explicitly requested in a partial reload.
     def optional(&block)
-      ::InertiaRails.optional(&block)
+      ::InertiaRails.optional(&InertiaJb.bind_to_view(self, block))
     end
     # Always fetched, even when not requested in a partial reload.
     def always(&block)
-      ::InertiaRails.always(&block)
+      ::InertiaRails.always(&InertiaJb.bind_to_view(self, block))
     end
     # Excluded from the initial load; fetched in a follow-up request.
-    def defer(...)
-      ::InertiaRails.defer(...)
+    def defer(*args, **kwargs, &block)
+      ::InertiaRails.defer(*args, **kwargs, &InertiaJb.bind_to_view(self, block))
     end
     # Infinite-scroll prop (accepts a paginator or explicit metadata).
-    def scroll(...)
-      ::InertiaRails.scroll(...)
+    def scroll(*args, **kwargs, &block)
+      ::InertiaRails.scroll(*args, **kwargs, &InertiaJb.bind_to_view(self, block))
     end
     # Merged with existing client-side data instead of replacing it.
-    def merge(...)
-      ::InertiaRails.merge(...)
+    def merge(*args, **kwargs, &block)
+      ::InertiaRails.merge(*args, **kwargs, &InertiaJb.bind_to_view(self, block))
     end
     # Deep-merged with existing client-side data.
-    def deep_merge(...)
-      ::InertiaRails.deep_merge(...)
+    def deep_merge(*args, **kwargs, &block)
+      ::InertiaRails.deep_merge(*args, **kwargs, &InertiaJb.bind_to_view(self, block))
+    end
+    # Sent once and cached client-side; skipped on later visits unless reset or expired.
+    def once(*args, **kwargs, &block)
+      ::InertiaRails.once(*args, **kwargs, &InertiaJb.bind_to_view(self, block))
+    end
+    # Server-side cached via Rails.cache; the block's result is stored as JSON
+    # and reused on subsequent requests until the cache expires.
+    def cache(*args, **kwargs, &block)
+      ::InertiaRails.cache(*args, **kwargs, &InertiaJb.bind_to_view(self, block))
     end
   end
+  # Binds a lazy-prop block to the view that declared it, so the block evaluates
+  # in the same view context as an eager prop.
+  #
+  # Eager props are evaluated while the +.inertia+ template renders, so their
+  # +render(partial: ...)+ is the *view* helper — it returns jb data and never
+  # touches +response_body+. Lazy props (+defer+/+optional+/+always+/...) are
+  # different: inertia-rails resolves them later via
+  # +controller.instance_exec(&block)+, i.e. in *controller* context, where the
+  # same +render(partial: ...)+ binds to +ActionController+'s +render+ and
+  # assigns +response_body+. inertia-rails then performs its own
+  # +render(json:)+, and the already-set +response_body+ raises
+  # +AbstractController::DoubleRenderError+.
+  #
+  # Wrapping the block in +view.instance_exec+ keeps every block — eager or
+  # lazy — running against the view, so +render+ behaves identically everywhere.
+  # Controller-exposed helpers still work in the view (e.g. +policy_scope+,
+  # +current_user+ via Pundit/Devise +helper_method+s); the only controller-only
+  # call that does not carry over is +render_to_string+ — use +render(partial:,
+  # formats: [:html])+ instead, which returns the same String in a view.
+  def self.bind_to_view(view, block)
+    return block if block.nil?
+    proc { view.instance_exec(&block) }
+  end
 end

data/lib/inertia_jb/version.rb CHANGED Viewed

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

data/test/controller_test.rb CHANGED Viewed

@@ -29,11 +29,24 @@ class TestController < ActionController::Base
   def special
     @id = 1
   end
+  # once (client-cached) + cache (server-cached).
+  def cached
+    @call_count = 0
+  end
+  # lazy props (defer/optional) whose block renders a jb partial.
+  def lazy_partial
+    @author = { id: 42, name: "John" }
+    @comments = [{ body: "first" }, { body: "second" }]
+  end
 end
 class ControllerTest < ActionController::TestCase
   tests TestController
+  include ActiveSupport::Testing::TimeHelpers
   TEMPLATES = {
     "layouts/application.html.erb" => "<html><body><%= yield %></body></html>",
     "test/index.html.inertia"      => "{ content: 'content' }",
@@ -45,7 +58,16 @@ class ControllerTest < ActionController::TestCase
     "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] } }"
+      "{ id: @id, stats: optional { { visits: 42 } }, feed: defer(group: :feed) { [1, 2, 3] } }",
+    "test/cached.html.inertia" =>
+      "{ flash: once { 'hello' }, " \
+      "report: cache('report', expires_in: 1.minute) { Time.current.to_f } }",
+    # A deferred/optional prop whose block renders a jb partial. The block is
+    # resolved by inertia-rails in controller context, so a bare `render` there
+    # would set response_body and collide with inertia's own render(json:).
+    "test/lazy_partial.html.inertia" =>
+      "{ deferredAuthor: defer { render(partial: 'authors/author', object: @author) }, " \
+      "optionalComments: optional { render(partial: 'comments/comment', collection: @comments) } }"
   }.freeze
   def setup
@@ -53,7 +75,7 @@ class ControllerTest < ActionController::TestCase
     @routes = ActionDispatch::Routing::RouteSet.new
     @routes.draw do
-      %i[index nested collection with_partial special].each do |action|
+      %i[index nested collection with_partial special cached lazy_partial].each do |action|
         get action.to_s => "test##{action}"
       end
     end
@@ -65,6 +87,7 @@ class ControllerTest < ActionController::TestCase
   def teardown
     super
     @routes.clear!
+    Rails.cache.clear
   end
   # ---- basic rendering -----------------------------------------------------
@@ -158,6 +181,79 @@ class ControllerTest < ActionController::TestCase
     assert_equal({ "feed" => ["feed"] }, page["deferredProps"])
   end
+  # ---- once props (client-cached) -----------------------------------------
+  def test_once_prop_included_on_first_visit
+    inertia_get :cached
+    page = JSON.parse(response.body)
+    assert_equal "hello", page.dig("props", "flash")
+    assert_equal({ "flash" => { "prop" => "flash" } }, page["onceProps"])
+  end
+  def test_once_prop_excluded_when_client_reports_it_cached
+    inertia_get :cached,
+                headers: {
+                  "X-Inertia-Partial-Component" => "test/cached",
+                  "X-Inertia-Except-Once-Props" => "flash"
+                }
+    page = JSON.parse(response.body)
+    refute page["props"].key?("flash"), "once prop should be absent when client reports it cached"
+  end
+  # ---- lazy props that render jb partials ---------------------------------
+  def test_deferred_prop_rendering_jb_partial_does_not_double_render
+    inertia_get :lazy_partial,
+                headers: {
+                  "X-Inertia-Partial-Component" => "test/lazy_partial",
+                  "X-Inertia-Partial-Data" => "deferredAuthor"
+                }
+    assert_response :success
+    page = JSON.parse(response.body)
+    assert_equal({ "id" => 42, "name" => "John" }, page.dig("props", "deferredAuthor"))
+  end
+  def test_optional_prop_rendering_jb_partial_does_not_double_render
+    inertia_get :lazy_partial,
+                headers: {
+                  "X-Inertia-Partial-Component" => "test/lazy_partial",
+                  "X-Inertia-Partial-Data" => "optionalComments"
+                }
+    assert_response :success
+    page = JSON.parse(response.body)
+    assert_equal(
+      [{ "body" => "first" }, { "body" => "second" }],
+      page.dig("props", "optionalComments")
+    )
+  end
+  # ---- cached props (server-cached) ---------------------------------------
+  def test_cached_prop_serves_same_value_across_requests
+    inertia_get :cached
+    first = JSON.parse(response.body).dig("props", "report")
+    inertia_get :cached
+    second = JSON.parse(response.body).dig("props", "report")
+    assert_equal first, second, "cached prop should return the same value across requests"
+  end
+  def test_cached_prop_recomputes_after_expiry
+    inertia_get :cached
+    first = JSON.parse(response.body).dig("props", "report")
+    travel_to 2.minutes.from_now do
+      inertia_get :cached
+      second = JSON.parse(response.body).dig("props", "report")
+      refute_equal first, second, "cached prop should recompute after expiry"
+    end
+  end
   private
   def inertia_get(action, headers: {})

data/test/test_helper.rb CHANGED Viewed

@@ -6,6 +6,7 @@ require "action_controller/railtie"
 require "inertia_rails"
 require "inertia_jb"
 require "active_support/testing/autorun"
+require "active_support/testing/time_helpers"
 ActiveSupport.test_order = :random
@@ -14,6 +15,7 @@ ActiveSupport.test_order = :random
 Class.new(Rails::Application) do
   config.secret_key_base = "secret"
   config.eager_load = false
+  config.cache_store = :memory_store
 end.initialize!
 InertiaRails.configure do |c|

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inertia_jb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - kikyous
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inertia_rails