sinatra-inertia 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e51ad95f421e2dc7d2eadc72b2c17b06377e2a72748a591e09d48106500786e
-  data.tar.gz: 3f110beacd7e7eb6778440a800e6f31768d0cb44ff75546607a94ee22c50e066
+  metadata.gz: bf6ac9b17727011296d39f42de745b6c9cd6e27b6cd6ed73ced25c0795dd0c34
+  data.tar.gz: a9c6f651bf9017f99e3baf93f849f68c22844c8dce63ae6645a570de65d77a42
 SHA512:
-  metadata.gz: 3ab6eda91b4f83b63d90d3cd56281edb83222e99692396748544497dd5c4637aedaf8f557bf7777b3f03c743ab15c1ec483d50f8b88e415d15aef071aade9a47
-  data.tar.gz: 4d1b984e23f72254fad4e1a6da82498cb35ca8f26f5270c5ab1ddaa4149118926a1c9a00ce5c7c061318e9d9da7693d412b50c4952432ba9d909a82394376914
+  metadata.gz: 9178b8948981c792d0d40fe9c3bfc35649e3ca4f561c7c26dda9bbc63bb28fb6f7af82806ba035aa7e0c9dbe79d2d8427086325c0bbe485fea9ce9344bd12729
+  data.tar.gz: 913198985434b0955bfb790967406400491ec356f732df35bd1a793de4f28131a0a6b97672cb8f35f6f73e588a3f905f35550f1839a89c1cd071abb879dbf865

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.4 — 2026-05-03
+
+- Add the recommended Sinatra-native page API: `render 'Component', props`,
+  `share_props`, `set :page_version`, `set :page_layout`, and route helpers
+  `defer`, `always`, `optional`, `lazy`, `merge`, `page_errors`,
+  `clear_history!`, and `encrypt_history!`.
+- Keep existing `inertia_*` helpers/settings and `Inertia.*` prop wrappers
+  working for compatibility.
+
 ## 0.1.3 — 2026-04-29
 
 - `lib/sinatra/inertia/async_sources.rb` registers under

data/README.md

@@ -2,8 +2,8 @@
 
 A Sinatra extension that implements the full **Inertia.js v2** wire protocol —
 page-object responses, version-mismatch detection, partial reloads,
-deferred / lazy / always / optional / merge / once props, encrypted history,
-303 redirect promotion, and error/flash session sweeps.
+deferred / lazy / always / optional / merge props, encrypted history, 303
+redirect promotion, and error/flash session sweeps.
 
 Pure Sinatra-compatible: depends only on `sinatra` and `rack`. Runs on
 MRI Ruby and on the [homura](https://github.com/kazuph/homura) Cloudflare
@@ -13,11 +13,12 @@ Workers + Opal stack.
 
 Two principles drove the API:
 
-1. **Sinatra慣習に乗る.** Rendering a page is `inertia 'Component', props: {...}` —
-   the same shape as Sinatra's `erb :index`. A `render inertia: 'Component'`
-   alias is also provided for Rails refugees.
-2. **Class-level config uses `set` and `inertia_share do ... end`,**
-   matching Sinatra's existing DSL surface (`set :views`, `helpers do … end`).
+1. **Routes render pages.** Application code should read like ordinary
+   Sinatra: `render 'Pages/Show', record: record`. The Inertia protocol stays
+   in the extension.
+2. **Class-level config uses Sinatra nouns.** Use `set :page_version`,
+   `set :page_layout`, and `share_props do ... end`. The older `inertia_*`
+   names still work for existing apps.
 
 ## Installation
 
@@ -33,10 +34,12 @@ gem 'sinatra-inertia'
 require 'sinatra'
 require 'sinatra/inertia'
 
-set :inertia_version, -> { ENV.fetch('ASSETS_VERSION', '1') }
+register Sinatra::Inertia
+
+set :page_version, -> { ENV.fetch('ASSETS_VERSION', '1') }
 
 get '/' do
-  inertia 'Pages/Hello', props: { name: 'world' }
+  render 'Pages/Hello', name: 'world'
 end
 ```
 
@@ -61,42 +64,49 @@ end
 
 | helper | purpose |
 |---|---|
-| `inertia(component, props:, layout:)` | Render an Inertia response (HTML on first hit, JSON on Inertia visit). |
-| `render(inertia: 'Comp', props: {...})` | Rails-style alias for the above. |
-| `inertia_request?` | True when `X-Inertia: true` header is present. |
-| `inertia_errors(payload = nil)` | Read or write validation errors that survive one redirect. |
-| `inertia_clear_history!` | Mark the next response's history as cleared. |
-| `inertia_encrypt_history!` | Mark the next response's history as encrypted. |
+| `render 'Comp', props_hash` | Render an Inertia response (HTML on first hit, JSON on Inertia visit). |
+| `render 'Comp', key: value` | Keyword-prop form of the same page render. |
+| `page_request?` | True when `X-Inertia: true` header is present. |
+| `page_errors(payload = nil)` | Read or write validation errors that survive one redirect. |
+| `clear_history!` | Mark the next response's history as cleared. |
+| `encrypt_history!` | Mark the next response's history as encrypted. |
+| `always`, `defer`, `optional`, `lazy`, `merge` | Prop wrappers for Inertia v2 transport modes. |
+
+Compatibility aliases remain available: `inertia`, `render(inertia: ...)`,
+`inertia_request?`, `inertia_errors`, `inertia_clear_history!`,
+`inertia_encrypt_history!`, and `Inertia.defer` / `Inertia.merge` / etc.
 
 ### Class-level DSL
 
 | DSL | purpose |
 |---|---|
-| `set :inertia_version, -> { ... }` | Asset version. Mismatch on Inertia GET → 409 + `X-Inertia-Location`. |
-| `set :inertia_layout, :layout` | ERB layout used for full-page rendering (default `:layout`). |
+| `set :page_version, -> { ... }` | Asset version. Mismatch on Inertia GET → 409 + `X-Inertia-Location`. |
+| `set :page_layout, :layout` | ERB layout used for full-page rendering (default `:layout`). |
 | `set :inertia_encrypt_history, true` | Default `encryptHistory: true` on every page. |
-| `inertia_share do … end` | Block whose return Hash is merged into every page's props. |
+| `share_props do … end` | Block whose return Hash is merged into every page's props. |
+
+Compatibility aliases remain available: `set :inertia_version`,
+`set :inertia_layout`, and `inertia_share do ... end`.
 
 ### Prop wrappers (Inertia v2 transport modes)
 
 ```ruby
-inertia 'Page', props: {
+render 'Page',
   todos:  -> { Todo.all },                        # plain lazy
-  csrf:   Inertia.always { csrf_token },          # always sent
-  stats:  Inertia.defer(group: 'meta') { stats }, # excluded from initial response
-  filter: Inertia.optional { params[:f] },        # only on partial-reload request
-  feed:   Inertia.merge(page_items)               # client-side array merge
-}
+  csrf:   always { csrf_token },                  # always sent
+  stats:  defer(group: 'meta') { stats },         # excluded from initial response
+  filter: optional { params[:f] },                # only on partial-reload request
+  feed:   merge(page_items)                       # client-side array merge
 ```
 
 | wrapper | semantics |
 |---|---|
 | bare `Proc`/`->` | resolved every request when included; partial-reload aware. |
-| `Inertia.always { … }` | always included, even on partials that omit it. |
-| `Inertia.defer(group:) { … }` | excluded on initial visit; client refetches in second roundtrip. |
-| `Inertia.optional { … }` | only resolved when explicitly requested via `X-Inertia-Partial-Data`. |
-| `Inertia.lazy { … }` | alias of `optional` (Inertia v1 name). |
-| `Inertia.merge(value)` | sent as a merge prop (`mergeProps` array on page object). Honours `X-Inertia-Reset: prop1,prop2` (Inertia 2.0) — reset props are emitted as plain values and dropped from `mergeProps`. |
+| `always { … }` | always included, even on partials that omit it. |
+| `defer(group:) { … }` | excluded on initial visit; client refetches in second roundtrip. |
+| `optional { … }` | only resolved when explicitly requested via `X-Inertia-Partial-Data`. |
+| `lazy { … }` | alias of `optional` (Inertia v1 name). |
+| `merge(value)` | sent as a merge prop (`mergeProps` array on page object). Honours `X-Inertia-Reset: prop1,prop2` (Inertia 2.0) — reset props are emitted as plain values and dropped from `mergeProps`. |
 
 ## Protocol features
 
@@ -110,9 +120,9 @@ inertia 'Page', props: {
   303 so the browser follows with GET.
 * **Partial reloads** — `X-Inertia-Partial-Component` + `X-Inertia-Partial-Data`
   / `X-Inertia-Partial-Except` headers narrow which props are resolved.
-* **Encrypted history / clear history** — set per-app via setting or
-  per-route via `inertia_encrypt_history!` / `inertia_clear_history!`.
-* **Errors session** — `inertia_errors(field: 'msg')` survives one redirect
+* **Encrypted history / clear history** — set per-app via setting or per-route
+  via `encrypt_history!` / `clear_history!`.
+* **Errors session** — `page_errors(field: 'msg')` survives one redirect
   and is automatically swept on render.
 
 ## Validation pattern (no 422, no client state)
@@ -120,7 +130,7 @@ inertia 'Page', props: {
 ```ruby
 post '/todos' do
   if params[:title].to_s.strip.empty?
-    inertia_errors title: "can't be blank"
+    page_errors title: "can't be blank"
     redirect back  # 303 by middleware; Inertia client follows
   else
     Todo.create(params)
@@ -129,10 +139,9 @@ post '/todos' do
 end
 
 get '/' do
-  inertia 'Todos/Index', props: {
+  render 'Todos/Index',
     todos: Todo.all,
     values: { title: params[:title] }
-  }
 end
 ```
 

data/lib/sinatra/inertia/deferred.rb

@@ -13,8 +13,7 @@ module Sinatra
     #     stats:  Inertia.defer { compute_stats } # excluded from initial response, fetched in 2nd request
     #     csrf:   Inertia.always { csrf_token }   # included even on partial reloads that omit it
     #     filter: Inertia.optional { params[:f] } # only included when explicitly requested via partial
-    #     feed:   Inertia.merge(page_items)       # array merged with existing client-side feed
-    #     once:   Inertia.once { current_time }   # delivered exactly once; subsequent visits suppress
+    #     feed:   merge(page_items)               # array merged with existing client-side feed
     #   }
     class Prop
       attr_reader :block, :value, :group
@@ -45,8 +44,6 @@ module Sinatra
       # existing array (Inertia 2 merge semantics)?
       def merge? = false
 
-      # Once-only delivery (cleared from session/state after first emission).
-      def once? = false
     end
 
     class AlwaysProp < Prop

data/lib/sinatra/inertia/helpers.rb

@@ -10,7 +10,7 @@ module Sinatra
     module Helpers
       # Render an Inertia response.
       #
-      #   inertia 'Todos/Index', props: { todos: -> { Todo.all } }
+      #   render 'Todos/Index', todos: -> { Todo.all }
       #
       # Layout selection: the configured layout (default `:layout`) is
       # rendered for full HTML responses. The view receives `@page_json`
@@ -18,7 +18,7 @@ module Sinatra
       # attribute) and `@page` (the underlying Hash, useful for SSR or
       # custom rendering).
       def inertia(component, props: {}, layout: nil)
-        layout = settings.respond_to?(:inertia_layout) ? settings.inertia_layout : :layout if layout.nil?
+        layout = current_page_layout if layout.nil?
 
         version = current_inertia_version
         shared = current_inertia_shared
@@ -72,7 +72,9 @@ module Sinatra
         erb layout, layout: false
       end
 
-      # Rails-flavored alias: `render inertia: 'Component', props: {...}`
+      # Natural page-rendering API: `render 'Component', props_hash`.
+      # `render inertia: 'Component', props: {...}` remains available for
+      # existing apps, while non-page render calls still delegate to Sinatra.
       # We must preserve Sinatra's `render(engine, data = nil, options = {}, locals = {}, &block)`
       # signature for the non-inertia path, so we forward *args/**kwargs.
       def render(*args, **kwargs, &block)
@@ -81,6 +83,14 @@ module Sinatra
           inertia(first[:inertia], props: first[:props] || {}, layout: first[:layout])
         elsif kwargs.key?(:inertia) && args.empty?
           inertia(kwargs[:inertia], props: kwargs[:props] || {}, layout: kwargs[:layout])
+        elsif first.is_a?(String) && args.length <= 2 && (args.length == 1 || args[1].is_a?(Hash))
+          layout = kwargs.delete(:layout)
+          props = {}
+          props.merge!(args[1]) if args[1].is_a?(Hash)
+          explicit_props = kwargs.delete(:props)
+          props.merge!(explicit_props) if explicit_props.is_a?(Hash)
+          props.merge!(kwargs)
+          inertia(first, props: props, layout: layout)
         else
           super(*args, **kwargs, &block)
         end
@@ -90,6 +100,10 @@ module Sinatra
         request.env['HTTP_X_INERTIA'] == 'true'
       end
 
+      def page_request?
+        inertia_request?
+      end
+
       # CSRF token for the current request. Mounted by CSRFMiddleware
       # (`set :inertia_csrf_protection, true` by default). Pair this with
       # `inertia_share { { csrfToken: csrf_token } }` so the React/Vue
@@ -101,6 +115,26 @@ module Sinatra
         request.env['sinatra.inertia.csrf_token']
       end
 
+      def always(value = nil, &block)
+        Sinatra::Inertia.always(value, &block)
+      end
+
+      def defer(group: 'default', &block)
+        Sinatra::Inertia.defer(group: group, &block)
+      end
+
+      def optional(&block)
+        Sinatra::Inertia.optional(&block)
+      end
+
+      def lazy(&block)
+        Sinatra::Inertia.lazy(&block)
+      end
+
+      def merge(value = nil, &block)
+        Sinatra::Inertia.merge(value, &block)
+      end
+
       # ------------------------------------------------------------------
       # Shared props — runtime accessors (the `inertia_share` class DSL is
       # in extension.rb, this is the per-request resolver).
@@ -119,7 +153,11 @@ module Sinatra
       # ------------------------------------------------------------------
       # Asset version
       def current_inertia_version
-        v = settings.respond_to?(:inertia_version) ? settings.inertia_version : nil
+        v = if settings.respond_to?(:page_version)
+              settings.page_version
+            elsif settings.respond_to?(:inertia_version)
+              settings.inertia_version
+            end
         v.respond_to?(:call) ? v.call.to_s : v.to_s
       end
 
@@ -137,14 +175,26 @@ module Sinatra
         end
       end
 
+      def page_errors(payload = nil)
+        inertia_errors(payload)
+      end
+
       def inertia_clear_history!
         @inertia_clear_history = true
       end
 
+      def clear_history!
+        inertia_clear_history!
+      end
+
       def inertia_encrypt_history!(flag = true)
         @inertia_encrypt_history_override = flag
       end
 
+      def encrypt_history!(flag = true)
+        inertia_encrypt_history!(flag)
+      end
+
       def inertia_errors_payload
         errors = session[:_inertia_errors]
         return nil if errors.nil?
@@ -167,6 +217,16 @@ module Sinatra
 
       private
 
+      def current_page_layout
+        if settings.respond_to?(:page_layout)
+          settings.page_layout
+        elsif settings.respond_to?(:inertia_layout)
+          settings.inertia_layout
+        else
+          :layout
+        end
+      end
+
       def deep_merge(a, b)
         a.merge(b) do |_k, av, bv|
           (av.is_a?(Hash) && bv.is_a?(Hash)) ? deep_merge(av, bv) : bv

data/lib/sinatra/inertia/version.rb

@@ -2,6 +2,6 @@
 
 module Sinatra
   module Inertia
-    VERSION = '0.1.3'
+    VERSION = '0.1.4'
   end
 end

data/lib/sinatra/inertia.rb

@@ -16,22 +16,23 @@ module Sinatra
   #   class App < Sinatra::Base
   #     register Sinatra::Inertia
   #
-  #     set :inertia_version, -> { ASSETS_VERSION }
-  #     set :inertia_layout,  :layout
+  #     set :page_version, -> { ASSETS_VERSION }
+  #     set :page_layout,  :layout
   #
-  #     inertia_share do
+  #     share_props do
   #       { auth: { user: current_user }, flash: flash_payload }
   #     end
   #
   #     get '/' do
-  #       inertia 'Todos/Index', props: { todos: -> { Todo.all } }
+  #       render 'Todos/Index', todos: -> { Todo.all }
   #     end
   #   end
   #
   # See README.md for the full feature matrix.
   module Inertia
     def self.registered(app)
-      # Default settings — consumers override with `set :inertia_*` in app.
+      # Default settings. `page_*` is the recommended application-facing API;
+      # `inertia_*` remains supported for existing apps and lower-level tuning.
       app.set :inertia_version, '1' unless app.respond_to?(:inertia_version)
       app.set :inertia_layout,  :layout unless app.respond_to?(:inertia_layout)
       app.set :inertia_encrypt_history, false unless app.respond_to?(:inertia_encrypt_history)
@@ -47,15 +48,26 @@ module Sinatra
       end
 
       # Mount protocol middleware (version mismatch + 303 redirect promotion).
-      app.use Sinatra::Inertia::Middleware, version: -> { app.settings.inertia_version }
+      app.use Sinatra::Inertia::Middleware, version: lambda {
+        version = if app.settings.respond_to?(:page_version)
+                    app.settings.page_version
+                  else
+                    app.settings.inertia_version
+                  end
+        version.respond_to?(:call) ? version.call.to_s : version.to_s
+      }
 
-      # Class-level DSL: `inertia_share { ... }` registers a block whose
-      # return value is merged into every page's `props.shared` payload.
+      # Class-level DSL: `share_props { ... }` registers a block whose return
+      # value is merged into every page's props.
       app.define_singleton_method(:inertia_share) do |&block|
         raise ArgumentError, 'inertia_share requires a block' unless block
         settings.inertia_share_blocks = settings.inertia_share_blocks + [block]
       end
 
+      app.define_singleton_method(:share_props) do |&block|
+        inertia_share(&block)
+      end
+
       app.helpers Sinatra::Inertia::Helpers
     end
 
@@ -72,4 +84,3 @@ end
 # overwrite an existing `::Inertia` constant — if your app has one, use
 # `Sinatra::Inertia.defer` instead.
 ::Inertia = Sinatra::Inertia unless defined?(::Inertia)
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-inertia
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Kazuhiro Homma