inertia_rails 3.17.0 → 3.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daa51c630e98a180cf58db897801bccf070932b66f5959d3e1a14663b6cda4a1
-  data.tar.gz: c4610fb28fd87ab63182715358000e417b24d436c8228d77e7cab5e023009c8f
+  metadata.gz: 9e041109440a74fee87c6aa2ec7a338db68e01e1c5160dee3e9e00364a55f504
+  data.tar.gz: e4e8fc4f115e2f7d84f8f39bfe90099ca5b17a2490cd97aa6c21282b112ef15c
 SHA512:
-  metadata.gz: b174cdfe7024669af7a7b560effdfa5ad8931e1487d4cf77f72f33c616008c915931bd1e7f687018ddcb64aeea00bb3c534662c3567d98c42ceef2561a21868c
-  data.tar.gz: e143611be5a920f9caa5bc6895fd6977ab638ea02cf81a30a522b53d1d2e638bc2c582eb4968315a64666e9db851a8b0ba398d6f0a85db25a98167963cf0e13a
+  metadata.gz: f399be828b7f2e01c5cb9dedb86d67d3a0fe278370846f2c70a37576246e96d8ea00395239152bd908aad238b9389e06c5349f6bbb51b68b1b131367fe51b317
+  data.tar.gz: 833c82fff42dce56d47e20dbfb32e9103a76dd889b921902f73f9f020369409bfcd81f8ddfecabe122b95983034d0c3eb2e24cf5a0e46e018a78b2aeb94f7b1e

data/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.18.0] - 2026-03-11
+
+* New (super awesome) landing page design (seriously, go look at the animated graphic) (@skryukov)
+* Convert `_inertia_meta` to Hash in props for testing (@greendrop)
+* Make InertaRails.scroll props deferable (@skyrukov)
+* Add `withAllErrors` as default (@skyrukov)
+* Improved testing with `evaluate_optional_props` (@skyrukov)
+* Add Railsified Precognition support (@skyrukov)
+
 ## [3.17.0] - 2026-02-04
 
 * Add support for use_data_inertia_head_attribute configuration option (@greendrop)

data/lib/generators/inertia/install/templates/react/inertia.jsx

@@ -42,6 +42,7 @@ createInertiaApp({
   defaults: {
     form: {
       forceIndicesArrayFormatInFormData: false,
+      withAllErrors: true,
     },
     future: {
       useScriptElementForInitialPage: true,

data/lib/generators/inertia/install/templates/react/inertia.tsx

@@ -42,6 +42,7 @@ void createInertiaApp({
   defaults: {
     form: {
       forceIndicesArrayFormatInFormData: false,
+      withAllErrors: true,
     },
     future: {
       useScriptElementForInitialPage: true,

data/lib/generators/inertia/install/templates/svelte/inertia.ts

@@ -40,6 +40,7 @@ createInertiaApp({
   defaults: {
     form: {
       forceIndicesArrayFormatInFormData: false,
+      withAllErrors: true,
     },
     future: {
       useScriptElementForInitialPage: true,

data/lib/generators/inertia/install/templates/vue/inertia.ts

@@ -39,6 +39,7 @@ createInertiaApp({
   defaults: {
     form: {
       forceIndicesArrayFormatInFormData: false,
+      withAllErrors: true,
     },
     future: {
       useScriptElementForInitialPage: true,

data/lib/inertia_rails/configuration.rb

@@ -47,6 +47,11 @@ module InertiaRails
       # Flash keys from Rails flash to expose to frontend.
       # Set to nil to disable Rails flash integration (use only flash.inertia).
       flash_keys: %i[notice alert].freeze,
+
+      # Whether to prevent database writes during precognition requests.
+      # When enabled, any ActiveRecord write during a precognition request
+      # will raise ActiveRecord::ReadOnlyError.
+      precognition_prevent_writes: false,
     }.freeze
 
     OPTION_NAMES = DEFAULTS.keys.freeze

data/lib/inertia_rails/controller.rb

@@ -5,6 +5,7 @@ require_relative 'flash_extension'
 require_relative 'helper'
 require_relative 'action_filter'
 require_relative 'meta_tag_builder'
+require_relative 'precognition'
 
 module InertiaRails
   module Controller
@@ -13,9 +14,17 @@ module InertiaRails
     included do
       helper ::InertiaRails::Helper
 
+      before_action do
+        InertiaRails::Current.request = request
+      end
+
       after_action do
         cookies['XSRF-TOKEN'] = form_authenticity_token if protect_against_forgery?
       end
+
+      rescue_from InertiaRails::PrecognitionResponse do |e|
+        render_precognition(e.errors)
+      end
     end
 
     module ClassMethods
@@ -139,6 +148,29 @@ module InertiaRails
 
     private
 
+    def precognition!(model_or_errors)
+      InertiaRails.precognition!(model_or_errors)
+    end
+
+    def precognition(model_or_errors)
+      errors = InertiaRails::Precognition.validate(model_or_errors)
+      return if errors.nil?
+
+      render_precognition(errors)
+      true
+    end
+
+    def render_precognition(errors)
+      response.headers['Precognition'] = 'true'
+
+      if errors.empty?
+        response.headers['Precognition-Success'] = 'true'
+        head :no_content
+      else
+        render json: { errors: errors }, status: :unprocessable_entity
+      end
+    end
+
     def inertia_view_assigns
       return {} unless @_inertia_instance_props
 

data/lib/inertia_rails/current.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :request, :precognition_called
+  end
+end

data/lib/inertia_rails/defer_prop.rb

@@ -14,5 +14,9 @@ module InertiaRails
 
       @group = props[:group] || DEFAULT_GROUP
     end
+
+    def deferred?
+      true
+    end
   end
 end

data/lib/inertia_rails/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  class Error < StandardError; end
+
+  class DoublePrecognitionError < StandardError
+    def initialize
+      super('You can only call precognition once per action, use a form object to validate multiple models.')
+    end
+  end
+end

data/lib/inertia_rails/middleware.rb

@@ -18,7 +18,11 @@ module InertiaRails
 
       def response
         copy_xsrf_to_csrf!
-        status, headers, body = @app.call(@env)
+        status, headers, body = if prevent_precognition_writes?
+                                  ActiveRecord::Base.while_preventing_writes { @app.call(@env) }
+                                else
+                                  @app.call(@env)
+                                end
         request = ActionDispatch::Request.new(@env)
 
         # Inertia session data is added via redirect_to
@@ -96,7 +100,19 @@ module InertiaRails
       end
 
       def copy_xsrf_to_csrf!
-        @env['HTTP_X_CSRF_TOKEN'] = @env['HTTP_X_XSRF_TOKEN'] if @env['HTTP_X_XSRF_TOKEN'] && inertia_request?
+        return unless @env['HTTP_X_XSRF_TOKEN'] && (inertia_request? || precognition_request?)
+
+        @env['HTTP_X_CSRF_TOKEN'] = @env['HTTP_X_XSRF_TOKEN']
+      end
+
+      def precognition_request?
+        @env['HTTP_PRECOGNITION'] == 'true'
+      end
+
+      def prevent_precognition_writes?
+        precognition_request? &&
+          InertiaRails.configuration.precognition_prevent_writes &&
+          defined?(ActiveRecord::Base)
       end
     end
   end

data/lib/inertia_rails/precognition.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'current'
+require_relative 'errors'
+
+module InertiaRails
+  class PrecognitionResponse < StandardError
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super('Precognition response')
+    end
+  end
+
+  module Precognition
+    class << self
+      # Returns filtered errors hash if precognition request, nil otherwise
+      def validate(model_or_errors)
+        # Check before the precognitive? guard to catch errors early
+        # without waiting for precognition requests.
+        ensure_single_precognition_call!
+        request = Current.request
+        return unless request&.inertia_precognitive?
+
+        errors = normalize_errors(model_or_errors)
+        filter_errors(errors, request)
+      end
+
+      private
+
+      def normalize_errors(errors)
+        return errors if errors.is_a?(Hash)
+
+        if errors.respond_to?(:valid?) && errors.respond_to?(:errors)
+          errors.valid?
+          return errors.errors.to_hash
+        end
+
+        return errors.to_hash if errors.respond_to?(:to_hash)
+        return errors.to_h if errors.respond_to?(:to_h)
+
+        raise ArgumentError,
+              "Expected a Hash or an object responding to :valid? and :errors, :to_hash, or :to_h, got #{errors.class}"
+      end
+
+      def filter_errors(errors, request)
+        only_keys = request.inertia_precognitive_validate_only
+        return errors unless only_keys&.any?
+
+        errors.slice(*only_keys, *only_keys.map(&:to_sym))
+      end
+
+      def ensure_single_precognition_call!
+        raise DoublePrecognitionError if Current.precognition_called
+
+        Current.precognition_called = true
+      end
+    end
+  end
+
+  def self.precognition!(model_or_errors)
+    errors = Precognition.validate(model_or_errors)
+    return false if errors.nil?
+
+    raise PrecognitionResponse, errors, []
+  end
+end

data/lib/inertia_rails/renderer.rb

@@ -98,17 +98,17 @@ module InertiaRails
       # rubocop:disable Style/MultilineBlockChain
       @props
         .tap do |merged_props|
-          # Always keep errors in the props
-          if merged_props.key?(:errors) && !merged_props[:errors].is_a?(BaseProp)
-            errors = merged_props[:errors]
-            merged_props[:errors] = InertiaRails.always { errors }
-          end
+        # Always keep errors in the props
+        if merged_props.key?(:errors) && !merged_props[:errors].is_a?(BaseProp)
+          errors = merged_props[:errors]
+          merged_props[:errors] = InertiaRails.always { errors }
+        end
       end
         .then { |props| deep_transform_props(props) } # Internal hydration/filtering
         .then { |props| @configuration.prop_transformer(props: props) } # Apply user-defined prop transformer
         .tap do |props|
-          # Add meta tags last (never transformed)
-          props[:_inertia_meta] = meta_tags if meta_tags.present?
+        # Add meta tags last (never transformed)
+        props[:_inertia_meta] = meta_tags if meta_tags.present?
       end
       # rubocop:enable Style/MultilineBlockChain
     end
@@ -164,7 +164,7 @@ module InertiaRails
       return if rendering_partial_component?
 
       @props.each_with_object({}) do |(key, prop), result|
-        (result[prop.group] ||= []) << key if prop.is_a?(DeferProp)
+        (result[prop.group] ||= []) << key if prop.try(:deferred?)
       end
     end
 
@@ -248,6 +248,7 @@ module InertiaRails
       @scroll_props = {}
       requested_merge_props.each do |key, prop|
         next unless prop.is_a?(ScrollProp)
+        next if prop.deferred? && !rendering_partial_component?
 
         @scroll_props[key] = prop.metadata.merge!(reset: reset_keys.include?(key))
       end
@@ -292,7 +293,7 @@ module InertiaRails
       return false if excluded_by_partial_request?(path)
 
       # Precedence: Evaluate IgnoreOnFirstLoadProp only after partial keys have been checked
-      return false if prop.is_a?(IgnoreOnFirstLoadProp) && !rendering_partial_component?
+      return false if (prop.is_a?(IgnoreOnFirstLoadProp) || prop.try(:deferred?)) && !rendering_partial_component?
 
       true
     end

data/lib/inertia_rails/scroll_prop.rb

@@ -6,16 +6,24 @@ module InertiaRails
   class ScrollProp < BaseProp
     prepend PropMergeable
 
+    attr_reader :group
+
     def initialize(**options, &block)
       super(&block)
 
       @merge = true
+      @deferred = options.delete(:defer) || false
+      @group = options.delete(:group) || DeferProp::DEFAULT_GROUP
       @metadata = options.delete(:metadata)
       @wrapper = options.delete(:wrapper)
 
       @options = options
     end
 
+    def deferred?
+      @deferred
+    end
+
     def call(controller)
       @value = super
       configure_merge_intent(controller.request.headers['X-Inertia-Infinite-Scroll-Merge-Intent'])

data/lib/inertia_rails/testing.rb

@@ -3,6 +3,7 @@
 module InertiaRails
   module Testing
     thread_mattr_accessor :current_response
+    mattr_accessor :evaluate_optional_props, default: false
 
     module RendererTestingPatch
       def new(component, controller, request, response, render, **options)
@@ -12,10 +13,23 @@ module InertiaRails
       end
     end
 
+    module RendererOptionalInTests
+      private
+
+      def keep_prop?(prop, path)
+        return true if InertiaRails::Testing.evaluate_optional_props &&
+                       (prop.is_a?(IgnoreOnFirstLoadProp) || prop.try(:deferred?)) &&
+                       !rendering_partial_component?
+
+        super
+      end
+    end
+
     def self.install!
       return if @installed
 
       InertiaRails::Renderer.singleton_class.prepend(RendererTestingPatch)
+      InertiaRails::Renderer.prepend(RendererOptionalInTests)
       @installed = true
     end
 
@@ -37,7 +51,7 @@ module InertiaRails
       def assign_locals(params)
         if params[:locals].present?
           @view_data = params[:locals].except(:page).with_indifferent_access
-          page = params[:locals][:page] || {}
+          page = JSON.parse((params[:locals][:page] || {}).to_json)
         else
           # Sequential Inertia request
           @view_data = {}
@@ -189,7 +203,7 @@ module InertiaRails
       def inertia_reload_only(*props)
         partial_headers = {
           'X-Inertia' => 'true',
-          'X-Inertia-Partial-Data' => props.map(&:to_s).join(','),
+          'X-Inertia-Partial-Data' => props.join(','),
           'X-Inertia-Partial-Component' => inertia.component,
         }
         get request.fullpath, headers: partial_headers
@@ -198,7 +212,7 @@ module InertiaRails
       def inertia_reload_except(*props)
         partial_headers = {
           'X-Inertia' => 'true',
-          'X-Inertia-Partial-Except' => props.map(&:to_s).join(','),
+          'X-Inertia-Partial-Except' => props.join(','),
           'X-Inertia-Partial-Component' => inertia.component,
         }
         get request.fullpath, headers: partial_headers

data/lib/inertia_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InertiaRails
-  VERSION = '3.17.0'
+  VERSION = '3.18.0'
 end

data/lib/patches/request.rb

@@ -9,6 +9,14 @@ module InertiaRails
     def inertia_partial?
       key?('HTTP_X_INERTIA_PARTIAL_COMPONENT')
     end
+
+    def inertia_precognitive?
+      headers['Precognition'] == 'true'
+    end
+
+    def inertia_precognitive_validate_only
+      headers['Precognition-Validate-Only']&.split(',')&.map(&:strip)
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inertia_rails
 version: !ruby/object:Gem::Version
-  version: 3.17.0
+  version: 3.18.0
 platform: ruby
 authors:
 - Brian Knoles
@@ -9,7 +9,7 @@ authors:
 - Eugene Granovsky
 bindir: bin
 cert_chain: []
-date: 2026-02-05 00:00:00.000000000 Z
+date: 2026-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -187,8 +187,10 @@ files:
 - lib/inertia_rails/base_prop.rb
 - lib/inertia_rails/configuration.rb
 - lib/inertia_rails/controller.rb
+- lib/inertia_rails/current.rb
 - lib/inertia_rails/defer_prop.rb
 - lib/inertia_rails/engine.rb
+- lib/inertia_rails/errors.rb
 - lib/inertia_rails/flash_extension.rb
 - lib/inertia_rails/generators/controller_template_base.rb
 - lib/inertia_rails/generators/helper.rb
@@ -204,6 +206,7 @@ files:
 - lib/inertia_rails/minitest.rb
 - lib/inertia_rails/once_prop.rb
 - lib/inertia_rails/optional_prop.rb
+- lib/inertia_rails/precognition.rb
 - lib/inertia_rails/prop_mergeable.rb
 - lib/inertia_rails/prop_onceable.rb
 - lib/inertia_rails/renderer.rb