turbo_form 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01bb2ce15b4fc755a0f4b689fa4e11d1a34627a206d95d5b2d008ad3d9e66aa3
-  data.tar.gz: 52860d7614b4aa8cd960721ee677854704324d34f0abdcdd938f879546daf7d2
+  metadata.gz: e9cee9bf341b5d0a6bf59ac5334065a7c71f66c0cfe99636471af207054c6484
+  data.tar.gz: 6d60f46ff0e7e74e43ba80a6db207a7fc5d30cf79afb0a7baf5ca8fa3a08fad5
 SHA512:
-  metadata.gz: cfee3dbcfb3d319e0e1265735a9dfe88d86a0479f3cfb01b53ad9879ef9f1d7b92eaf8679a9486613ffaba54a57f3f1e2965a66531aa6065557927a629ce39d1
-  data.tar.gz: 82b3308ced5f38ace3d7e4f170b1beb77d0559f24a67cbfb91174e39de67ef9e66831a8d1a6a9fa03a2def2772459a821833aa684b45bd6f8a6141443ab36113
+  metadata.gz: 87318b7b8397c9e71d1754cea8b527f7d813865b6ad8d4101183494f8788815b1f77ea3a22053b0cfe7ec2418a9f644b21380bde114839ba98adf6b38d155241
+  data.tar.gz: b62767b018f4c05fce71f7af5060d68526d0c4bfb3f47d6b872405f89c879489f4d4320b93a09d2e55f452b3c158b3ac0af4520d8567788e6d32ee3548d5dbdd

data/README.md

@@ -51,20 +51,23 @@ See [JavaScript](#javascript) for what that does and how to do it by hand.
 
 ### `dynamic:` on the form
 
-`dynamic: true` wires the form up and points it at
-`app/views/<resource dir>/dynamic_form.turbo_stream.*` — alongside the
-resource's own partial, so `widgets/_widget` gets `widgets/dynamic_form`.
+`dynamic: true` makes the form dynamic. When a trigger fires, the gem renders a
+template named `dynamic_form`, looked up just as the controller that rendered
+the form would look up one of its own views:
 
-Pass a string to render something else instead:
+- A form rendered by `WidgetsController` gets
+  `widgets/dynamic_form.turbo_stream.erb`.
+- If that doesn't exist, lookup follows controller inheritance, ending at
+  `application/dynamic_form.turbo_stream.erb`.
+- Partials resolve the same way, so `render "fields"` inside the template finds
+  `widgets/_fields`, just as it would in the form itself.
+
+To render a different template, pass its name instead of `true`:
 
 ```erb
 <%= form_for @widget, dynamic: "shared/refresh_widget" %>
 ```
 
-Works on `form_for` and `form_with` alike. Any template engine works — the
-template is resolved the way every other Rails template is, so `.slim` and
-`.haml` are fine.
-
 ### `dynamic_trigger:` on a field
 
 ```erb
@@ -124,18 +127,24 @@ A `dynamic: true` form carries a signed description of itself to a single
 endpoint the gem draws into your routes. Given a valid signature it:
 
 1. permits the submitted parameters wholesale,
-2. builds a **new, unsaved** instance of the form's class from them,
+2. rebuilds the form's object and assigns them to it — an edit form's record is
+   found again by id, and a new form's object is rebuilt from the attributes it
+   was built with (a parent's foreign key from `@order.line_items.new`, say) before
+   the submitted ones are applied,
 3. assigns it to `@resource`,
-4. calls `TurboForm.before_render` with the controller and the resource, if one is set,
+4. runs `TurboForm.before_render` inside the controller with the resource, if one is set,
 5. renders the turbo_stream template.
 
-Nothing is persisted, and the resource is always freshly instantiated — even for
-an edit form. `@resource` exists to be asked what the form should now look like,
-not to be saved.
+Nothing is persisted. `@resource` exists to be asked what the form should now
+look like, not to be saved — and since Active Record saves some assignments on
+the spot (`has_many` writers, `*_ids=`), an Active Record resource is rebuilt
+inside a transaction that is always rolled back.
 
-The signature covers the class name, the parameter scope and the template. It is
-signed because the endpoint constantizes and renders what it names; none of that
-may come from the browser unverified.
+The signature covers the class name, the parameter scope, the template, the view
+paths the form was rendered under, and the record's id or starting attributes. It is signed because the endpoint
+constantizes, loads and renders what it names; none of that may come from the
+browser unverified. It is not encrypted, so those starting attributes are
+readable in the page, as the form itself is.
 
 ## Configuration
 
@@ -151,7 +160,7 @@ TurboForm.parent_controller = "ApplicationController"
 TurboForm.draw_routes = false
 
 # Run something before the render. See below.
-TurboForm.before_render = ->(controller, resource) { }
+TurboForm.before_render = ->(resource) { }
 ```
 
 ### `before_render`
@@ -159,17 +168,18 @@ TurboForm.before_render = ->(controller, resource) { }
 The endpoint is a controller you never wrote, inheriting filters written for
 controllers that save things. `before_render` is where you get to treat it like
 one of your own: it runs in a `before_action`, after the signature is verified
-and the resource is built, and is handed the controller and that resource.
+and the resource is built, and is handed that resource. It runs *inside* the
+controller, so its protected helpers — Pundit's among them — are in reach.
 
 Satisfy a filter the endpoint can't — the most common need, since nothing here
 is authorized because nothing here is saved:
 
 ```ruby
 # Pundit's after_action :verify_authorized
-TurboForm.before_render = ->(controller, resource) { controller.skip_authorization }
+TurboForm.before_render = ->(resource) { skip_authorization }
 
 # Action Policy's verify_authorized
-TurboForm.before_render = ->(controller, resource) { controller.skip_verify_authorized! }
+TurboForm.before_render = ->(resource) { skip_verify_authorized! }
 ```
 
 Or authorize it for real, if re-rendering a form is something you'd rather gate.
@@ -178,18 +188,18 @@ permission you mean.
 
 ```ruby
 # Pundit
-TurboForm.before_render = ->(controller, resource) { controller.authorize(resource, :edit?) }
+TurboForm.before_render = ->(resource) { authorize resource, :edit? }
 
 # Action Policy
-TurboForm.before_render = ->(controller, resource) { controller.authorize!(resource, to: :edit?) }
+TurboForm.before_render = ->(resource) { authorize! resource, to: :edit? }
 
 # CanCanCan -- this also satisfies `check_authorization`, which has no runtime skip
-TurboForm.before_render = ->(controller, resource) { controller.authorize!(:edit, resource) }
+TurboForm.before_render = ->(resource) { authorize! :edit, resource }
 ```
 
 Raising works the way it does in any `before_action`: your
 `rescue_from`s catch it, since the endpoint inherits them too. Rendering or
-redirecting from the controller halts the chain as usual.
+redirecting halts the chain as usual.
 
 ## JavaScript
 
@@ -245,9 +255,7 @@ a page carries more than one dynamic form.
 ## What this deliberately doesn't do
 
 It handles the common case well and gets out of the way otherwise. There is no
-debouncing, no request cancellation, no loading state, no per-element URL
-override, and no hook for loading an existing record instead of building a new
-one. When you need those, write the action by hand — that path is still open,
+debouncing, no request cancellation and no loading state. When you need those, write the action by hand — that path is still open,
 and this gem doesn't stand in front of it.
 
 ## License

data/app/controllers/turbo_form/dynamic_forms_controller.rb

@@ -1,25 +1,48 @@
 module TurboForm
   # Renders a form again from the state the browser currently has it in.
   #
-  # Nothing here is saved. The resource is rebuilt only so the template can ask
-  # it what the form should now look like, which is why the parameters are taken
-  # whole: narrowing them would only make the re-rendered form disagree with what
-  # the user actually typed.
+  # Nothing here is saved. The form's object is rebuilt only so the template can
+  # ask it what the form should now look like, which is why the parameters are
+  # taken whole: narrowing them would only make the re-rendered form disagree
+  # with what the user actually typed.
   class DynamicFormsController < TurboForm.parent_controller.constantize
     rescue_from TurboForm::Signature::Invalid do
       head :bad_request
     end
 
+    around_action :discard_writes
     before_action :build_resource
-    before_action { TurboForm.before_render&.call(self, @resource) }
+    before_action { instance_exec(@resource, &TurboForm.before_render) if TurboForm.before_render }
 
     def update
-      render template: signature.template_for(@resource), formats: :turbo_stream
+      render signature.template || "dynamic_form", formats: :turbo_stream
     end
 
     private
       def build_resource
-        @resource = signature.model.new(form_params)
+        @resource = signature.rebuild(form_params)
+      end
+
+      # Assigning to a saved record is not always inert: Active Record saves
+      # `has_many` writers and `*_ids=` on the spot.
+      def discard_writes
+        return yield unless defined?(ActiveRecord::Base) && signature.model < ActiveRecord::Base
+
+        signature.model.transaction do
+          yield
+          raise ActiveRecord::Rollback
+        end
+      end
+
+      # Renders as if it were the controller that rendered the form, so the
+      # template's relative partials resolve the way the form's own did.
+      #
+      # Read while the lookup context is built, before `rescue_from` is in play,
+      # so a bad signature falls through here and is answered by the action.
+      def _prefixes
+        signature.prefixes
+      rescue TurboForm::Signature::Invalid
+        super
       end
 
       def signature

data/lib/turbo_form/form_helper.rb

@@ -14,9 +14,11 @@ module TurboForm
 
       scope ||= model_name_from_record_or_class(object).param_key
       signature = TurboForm::Signature.new(
-        model_name: object.class.name,
+        model_name: (object.class.try(:base_class) || object.class).name,
         scope: scope.to_s,
-        template: (dynamic unless dynamic == true)
+        template: (dynamic unless dynamic == true),
+        prefixes: lookup_context.prefixes,
+        **origin_of(object)
       )
 
       wire_dynamic_form(options, signature)
@@ -24,6 +26,16 @@ module TurboForm
     end
 
     private
+      # A saved record is found again by id. An unsaved one is rebuilt from what
+      # it had already been given -- a parent's foreign key, say -- since the
+      # form may not submit that back. A plain form object with no dirty
+      # tracking has nothing to carry.
+      def origin_of(object)
+        return { id: object.id } if object.try(:persisted?)
+
+        { seed: object.try(:changes).to_h.transform_values(&:last) }
+      end
+
       # `form_for` funnels HTML attributes through options[:html] while `form_with`
       # takes them at the top level. Write wherever the caller already is, and sit
       # alongside any Stimulus controller they asked for rather than replacing it.

data/lib/turbo_form/signature.rb

@@ -6,9 +6,13 @@ module TurboForm
   # constantized and instantiated, `template` gets rendered. Neither may come
   # from the client unverified.
   #
-  # Note that this identifies a *class*, not a record. Dynamic forms are usually
-  # editing something unsaved, which is also why GlobalID -- which requires a
-  # persisted record -- can't express it.
+  # `prefixes` are the view paths the form was rendered under, so the endpoint
+  # can find its template and partials the way the form's own controller would.
+  #
+  # It also says where the form's object came from, so the endpoint can rebuild
+  # that object rather than a blank one: the `id` of a saved record, or the
+  # `seed` of attributes an unsaved one already had -- the `tank_id` of
+  # `@tank.rings.new` -- which the form itself may never submit.
   class Signature
     class Invalid < StandardError; end
 
@@ -19,25 +23,42 @@ module TurboForm
       new(**payload.symbolize_keys)
     end
 
-    attr_reader :model_name, :scope, :template
+    attr_reader :model_name, :scope, :template, :prefixes, :id, :seed
 
-    def initialize(model_name:, scope:, template: nil)
+    def initialize(model_name:, scope:, template: nil, prefixes: [], id: nil, seed: {})
       @model_name = model_name
       @scope = scope
       @template = template
+      @prefixes = prefixes
+      @id = id
+      @seed = seed
     end
 
     def model = model_name.constantize
 
-    # By convention the template sits alongside the resource's own partial:
-    # `widgets/_widget` gets `widgets/dynamic_form`.
-    def template_for(resource)
-      template || File.join(File.dirname(resource.to_partial_path), "dynamic_form")
+    # The form's object as the user now has it. A new one is built in a single
+    # step so the submitted `type` picks its STI subclass.
+    def rebuild(params)
+      return model.new(seed.merge(params.to_h)) unless id
+
+      retype(model.find(id), params).tap { |resource| resource.assign_attributes(params) }
     end
 
     def to_s
-      TurboForm.verifier.generate({ model_name:, scope:, template: })
+      TurboForm.verifier.generate({ model_name:, scope:, template:, prefixes:, id:, seed: })
     end
     alias to_param to_s
+
+    private
+      # `find` answers with the subclass that was saved, not the one just picked.
+      # Let `new` choose by Active Record's own STI rules, and switch before
+      # assigning so nested records land on the object that is kept.
+      def retype(record, params)
+        type = params.to_h.slice(model.try(:inheritance_column).to_s)
+        return record if type.empty?
+
+        subclass = model.new(type).class
+        record.instance_of?(subclass) ? record : record.becomes(subclass)
+      end
   end
 end

data/lib/turbo_form/version.rb

@@ -1,3 +1,3 @@
 module TurboForm
-  VERSION = '0.3.0'
+  VERSION = "0.4.0"
 end

data/lib/turbo_form.rb

@@ -13,12 +13,12 @@ module TurboForm
   # route yourself.
   mattr_accessor :draw_routes, default: true
 
-  # Called from a `before_action` with the controller and the resource the form
-  # was rebuilt into. The endpoint is an inherited controller the host never
-  # wrote, so this is where it gets to treat it like one of its own: authorize
-  # the render, skip a filter the endpoint can't satisfy
-  # (`controller.skip_authorization`), set something the template needs. Left
-  # alone, only the host's own inherited filters apply.
+  # Run as the body of a `before_action`, inside the endpoint, and handed the
+  # resource the form was rebuilt into. The endpoint is an inherited controller
+  # the host never wrote, so this is where it gets to treat it like one of its
+  # own: authorize the render, skip a filter the endpoint can't satisfy
+  # (`skip_authorization`), set something the template needs. Left alone, only
+  # the host's own inherited filters apply.
   mattr_accessor :before_render
 
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_form
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Andy Cohen