turbo_form 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 887edabc903374a74393c5a9f2b04e70c78d421a17e893355f9b2f985404a7da
-  data.tar.gz: 11cbdfb726a72675d6980e373001ca40de5a9258f2329b2391992779a5eebfa7
+  metadata.gz: e9cee9bf341b5d0a6bf59ac5334065a7c71f66c0cfe99636471af207054c6484
+  data.tar.gz: 6d60f46ff0e7e74e43ba80a6db207a7fc5d30cf79afb0a7baf5ca8fa3a08fad5
 SHA512:
-  metadata.gz: 0431310fcc0bb70e96b71336275a63889b7746b79d4ba4ca64fb36358beff818d56d5b7b05f50663875371771a8e33c85fdb6b1a68e60228a7fcfeaf8a0760e9
-  data.tar.gz: 56831a247fe03fd5bc540a2a44c6fde0a8a4dc2ac64a4f8b8a9dca712ba5134fd8ac79cced5b8e12e78e93e7daa7f427bad683fa56e1729bd59fbe212eb55197
+  metadata.gz: 87318b7b8397c9e71d1754cea8b527f7d813865b6ad8d4101183494f8788815b1f77ea3a22053b0cfe7ec2418a9f644b21380bde114839ba98adf6b38d155241
+  data.tar.gz: b62767b018f4c05fce71f7af5060d68526d0c4bfb3f47d6b872405f89c879489f4d4320b93a09d2e55f452b3c158b3ac0af4520d8567788e6d32ee3548d5dbdd

data/README.md

@@ -37,29 +37,37 @@ That's the whole feature. No route, no controller, no JavaScript.
 gem "turbo_form"
 ```
 
-There is nothing to mount and nothing to generate. On a stock Rails app —
-Propshaft, importmap-rails, stimulus-rails — the Stimulus controller registers
-itself. See [JavaScript](#javascript) if your app bundles with esbuild, Vite,
-Bun or webpack.
+There is nothing to mount. On a stock Rails app — Propshaft, importmap-rails,
+stimulus-rails — the Stimulus controller registers itself and there is nothing
+to generate either. If your app bundles with esbuild, Vite, Bun or webpack:
+
+```bash
+rails generate turbo_form:install
+```
+
+See [JavaScript](#javascript) for what that does and how to do it by hand.
 
 ## The two options
 
 ### `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:
+
+- 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.
 
-Pass a string to render something else instead:
+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
@@ -72,6 +80,30 @@ checkbox, `input` for a text field, `click` for a button. Name an event when you
 want something else — `:blur` on text fields is usually what you want, since the
 default fires on every keystroke.
 
+#### Sending the form somewhere else
+
+A trigger can answer to a different endpoint than its own form, and can add to
+what the form sends:
+
+```erb
+<%= f.button "Run", type: "button", dynamic_trigger: {
+      event: :click,
+      url: formula_preview_widgets_path,
+      params: { attribute: :rafter_count }
+    } %>
+```
+
+`url:` replaces the form's own endpoint for that one trigger; everything else on
+the form keeps using the form's. `params:` are appended to the submitted form
+data, so one endpoint can tell which of several triggers asked. Both are
+optional, and either can be given without the other.
+
+That endpoint is yours, not the gem's — it's an ordinary action rendering an
+ordinary turbo_stream template, so the whole form arrives as `params` under its
+usual scope. Use it when one form feeds several actions: a dozen fields that
+each preview themselves, or a select that belongs to a nested form with its own
+controller.
+
 Works on every Rails field helper, including the select and date families where
 Rails keeps HTML attributes in a separate hash:
 
@@ -95,32 +127,80 @@ 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. renders the turbo_stream template.
+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
 
 ```ruby
 # config/initializers/turbo_form.rb
 
-# The endpoint inherits from this, so your authentication applies to it. If your
-# ApplicationController enforces something the endpoint can't satisfy -- Pundit's
-# `verify_authorized`, say -- point this at a controller that doesn't.
+# The endpoint inherits from this, so your authentication applies to it. Point
+# it at a narrower controller when that inheritance brings something the
+# endpoint shouldn't have.
 TurboForm.parent_controller = "ApplicationController"
 
 # Draw the route yourself instead.
 TurboForm.draw_routes = false
+
+# Run something before the render. See below.
+TurboForm.before_render = ->(resource) { }
+```
+
+### `before_render`
+
+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 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 = ->(resource) { skip_authorization }
+
+# Action Policy's 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.
+Name the query explicitly: the endpoint's action is `update`, which is not the
+permission you mean.
+
+```ruby
+# Pundit
+TurboForm.before_render = ->(resource) { authorize resource, :edit? }
+
+# Action Policy
+TurboForm.before_render = ->(resource) { authorize! resource, to: :edit? }
+
+# CanCanCan -- this also satisfies `check_authorization`, which has no runtime skip
+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 halts the chain as usual.
+
 ## JavaScript
 
 **importmap-rails** — nothing to do. The engine pins its controller as
@@ -135,17 +215,27 @@ import TurboFormController from "controllers/turbo_form_controller"
 application.register("turbo-form", TurboFormController)
 ```
 
-**esbuild, Vite, Bun, webpack** — install the npm package alongside the gem, at
-the same version, and register it:
+**esbuild, Vite, Bun, webpack** — there is no sweep to pick the controller up,
+so the package has to be installed alongside the gem, at the same version, and
+registered. `rails generate turbo_form:install` does both: it adds the package
+with whichever manager your lockfile names, and writes
 
-```bash
-yarn add @rolemodel/turbo_form
-```
 ```js
-import TurboFormController from "@rolemodel/turbo_form"
-application.register("turbo-form", TurboFormController)
+// app/javascript/controllers/turbo_form_controller.js
+import TurboFormController from "@rolemodel/turbo-form"
+
+export default TurboFormController
 ```
 
+Registering by *filename* rather than by appending to
+`app/javascript/controllers/index.js` is deliberate. That file is regenerated
+from the contents of the directory every time `rails generate stimulus` runs, so
+a registration appended to it lasts until the next controller you generate. A
+file named `turbo_form_controller.js` is picked up by that same regeneration and
+registered as `turbo-form`, every time.
+
+To do it by hand, write that file yourself and run `rails stimulus:manifest:update`.
+
 ### Testing against it
 
 A re-render is a round trip, so the line after a trigger is racing it. Wrap the
@@ -165,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/assets/javascripts/turbo_form.js

@@ -9,12 +9,18 @@ import { Turbo } from "@hotwired/turbo-rails"
 export default class extends Controller {
   static values = { url: String, requests: Number }
 
-  async perform() {
-    this.trigger
-    const response = await fetch(this.urlValue, {
+  // A trigger can send the form somewhere other than the form's own endpoint,
+  // and can add to what it sends. Both ride in as Stimulus action params, so
+  // one form can feed several actions without needing several forms.
+  async perform({ params: { url, query } }) {
+    const body = new FormData(this.element)
+
+    if (query) Object.entries(query).forEach(([name, value]) => body.append(name, value))
+
+    const response = await fetch(url || this.urlValue, {
       method: "PATCH",
       headers: this.#headers,
-      body: new FormData(this.element)
+      body
     })
 
     if (!response.ok) return

data/app/controllers/turbo_form/dynamic_forms_controller.rb

@@ -1,22 +1,50 @@
 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
 
-    def update
-      @resource = signature.model.new(form_params)
+    around_action :discard_writes
+    before_action :build_resource
+    before_action { instance_exec(@resource, &TurboForm.before_render) if TurboForm.before_render }
 
-      render template: signature.template_for(@resource), formats: :turbo_stream
+    def update
+      render signature.template || "dynamic_form", formats: :turbo_stream
     end
 
     private
+      def build_resource
+        @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
         @signature ||= TurboForm::Signature.verify(params[:signature])
       end

data/lib/generators/turbo_form/install/install_generator.rb

@@ -0,0 +1,62 @@
+require "rails/generators"
+
+module TurboForm
+  module Generators
+    # There is nothing to install on importmap-rails: the engine pins its own
+    # Stimulus controller and a stock `app/javascript/controllers/index.js`
+    # registers it. Bundled apps get no such sweep, so this hands them the two
+    # things they'd otherwise write by hand -- the package and the registration.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      LOCKFILES = {
+        "yarn.lock" => "yarn add", "pnpm-lock.yaml" => "pnpm add",
+        "bun.lock" => "bun add", "bun.lockb" => "bun add"
+      }.freeze
+
+      def install
+        if importmap?
+          say "turbo_form registers its own Stimulus controller on importmap-rails. Nothing to install."
+          return
+        end
+
+        install_package
+        register_controller
+        update_stimulus_manifest
+      end
+
+      private
+        def importmap? = Rails.root.join("config/importmap.rb").exist?
+
+        def install_package
+          run "#{package_manager} #{package}"
+        end
+
+        # Named for the controller it is, rather than imported into `index.js`:
+        # that file is rewritten wholesale every time `rails generate stimulus`
+        # runs, and would take a registration appended to it down with it. The
+        # manifest is generated from this directory instead, so a file named
+        # this way is picked back up every time and registered as `turbo-form`.
+        def register_controller
+          copy_file "turbo_form_controller.js", "app/javascript/controllers/turbo_form_controller.js"
+        end
+
+        # Left to Stimulus' own task rather than written here, the way the
+        # `stimulus` generator does it: the task is what the app already trusts
+        # to regenerate this file, and its internals have moved between releases.
+        def update_stimulus_manifest
+          return unless Rails.root.join("app/javascript/controllers/index.js").exist?
+
+          rails_command "stimulus:manifest:update"
+        end
+
+        def package = "@rolemodel/turbo-form@#{TurboForm::VERSION}"
+
+        # Matched to the lockfile that is already there, so the generator doesn't
+        # introduce a second package manager to an app that settled on one.
+        def package_manager
+          LOCKFILES.find { |lockfile, _| Rails.root.join(lockfile).exist? }&.last || "npm install"
+        end
+    end
+  end
+end

data/lib/generators/turbo_form/install/templates/turbo_form_controller.js

@@ -0,0 +1,4 @@
+// Registered as `turbo-form` by the Stimulus manifest, which reads this filename.
+import TurboFormController from "@rolemodel/turbo-form"
+
+export default TurboFormController

data/lib/turbo_form/form_builder.rb

@@ -75,16 +75,30 @@ module TurboForm
         attributes = attributes.except(:dynamic_trigger)
         return attributes unless trigger
 
+        event, url, query = destructure_trigger(trigger)
+
         data = (attributes[:data] || {}).dup
-        data[:action] = [ data[:action], stimulus_action_for(trigger) ].compact.join(" ")
+        data[:action] = [ data[:action], stimulus_action_for(event) ].compact.join(" ")
+        data[:turbo_form_url_param] = url if url
+        data[:turbo_form_query_param] = query if query
         attributes.merge(data: data)
       end
 
-      # `true` leaves the event off the descriptor so Stimulus binds the element's
-      # own default: `change` for a select, `input` for a text field, `click` for
-      # a button. Anything else is taken as the event name.
-      def stimulus_action_for(trigger)
-        trigger == true ? "turbo-form#perform" : "#{trigger}->turbo-form#perform"
+      # The short forms say when to fire and nothing else. The hash form also
+      # says where to send the form and what to send with it, which is what a
+      # field needs when it answers to a different action than its own form does.
+      def destructure_trigger(trigger)
+        return trigger.values_at(:event, :url, :params) if trigger.is_a?(Hash)
+
+        [ trigger, nil, nil ]
+      end
+
+      # `true` -- or a hash that names no event -- leaves the event off the
+      # descriptor so Stimulus binds the element's own default: `change` for a
+      # select, `input` for a text field, `click` for a button. Anything else is
+      # taken as the event name.
+      def stimulus_action_for(event)
+        event.nil? || event == true ? "turbo-form#perform" : "#{event}->turbo-form#perform"
       end
   end
 end

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.2.0"
+  VERSION = "0.4.0"
 end

data/lib/turbo_form.rb

@@ -12,7 +12,14 @@ module TurboForm
   # Set to false to keep the engine out of the host's route set and draw its
   # route yourself.
   mattr_accessor :draw_routes, default: true
-  # mattr_accessor :authorize, default: ->(controller) { true }
+
+  # 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
     attr_writer :verifier

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_form
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Andy Cohen
@@ -79,6 +79,8 @@ files:
 - app/controllers/turbo_form/dynamic_forms_controller.rb
 - config/routes.rb
 - config/turbo_form_importmap.rb
+- lib/generators/turbo_form/install/install_generator.rb
+- lib/generators/turbo_form/install/templates/turbo_form_controller.js
 - lib/tasks/turbo_form_tasks.rake
 - lib/turbo_form.rb
 - lib/turbo_form/engine.rb