turbo_form 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c69a1768a1d65dd2bdfa4d77ea5e58ea239923d54280820b5197bec043376b91
-  data.tar.gz: 5958181f35cc5c6cfbdbd50c9a4da9eea692c5670867dfa86d55459355a07c08
+  metadata.gz: 1ea880fbc0453b32344bf09706c5bc68c095de36fdbea018f00fdf4adc7acc03
+  data.tar.gz: 49bf3d131c1a1179d8ce8b64772e23681f1c54332797bca9cd46589c4d0c90d3
 SHA512:
-  metadata.gz: 76dbea8632fa0087c403cbaa95682fae7b16ed8c3370586007e873e4c7ad3277a06f73a436782834ffb8d2b81fa8302a4d7c3e61130e48adbf6dd28ebd53d6a4
-  data.tar.gz: c89bdf36b175d24708012a869ec06692217a38d8b0d3d889c1692dca95237a7ce0039d020cab93463d34491b452b0a8ce309b2cb969396d0a1662534e358861d
+  metadata.gz: 300aabd3ad77727c57ddf99980ce56036e4f5fdbf6c001a31908dcef1f0f53408b4100cf21fa1b88abfd663f2adab10dd14003d90e1915136231e62576b1e2d6
+  data.tar.gz: 24ec9eabed896e9de6f14c71b70e3f6aa8bc299244fcf3858146b55bf5d78c76549e4e08acdaaa6c0f77b13b6713183fabc2c469347c3a59df7e7dd477ed6ff9

data/README.md

@@ -14,14 +14,15 @@ instead:
 <% end %>
 ```
 
-Pick a category and the page reloads with the form as it currently stands. The
-form assigns what was typed to `@widget` before its fields render, so
-`@widget.flavors` answers for the category just picked. Turbo morphs the page in
-place, so focus, scroll and everything else typed survive the reload.
+Pick a category and the form is sent to the page it is on. That page's own
+action builds `@widget`, the form's values are assigned to it, and the page's
+own template renders it — so `@widget.flavors` answers for the category just
+picked. Turbo morphs the page in place, so focus, scroll and everything else
+typed survive.
 
-That's the whole feature. No route, no controller action, no template, no
-JavaScript. The page is rendered by its own controller, so its authentication,
-authorization and partials are the ones it always had.
+No new action, no template, no JavaScript to write. The page is rendered by its
+own controller, so its authentication, authorization and partials are the ones
+it always had.
 
 ## Installation
 
@@ -29,23 +30,47 @@ authorization and partials are the ones it always had.
 gem "turbo_form"
 ```
 
-On a stock Rails app — Propshaft, importmap-rails, stimulus-rails — the Stimulus
-controller registers itself and there is nothing to generate. If your app
-bundles with esbuild, Vite, Bun or webpack:
+Then run the installer:
 
 ```bash
 rails generate turbo_form:install
 ```
 
-See [JavaScript](#javascript) for what that does and how to do it by hand.
+It includes `TurboForm::Controller` in your ApplicationController and declares
+the route concern:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include TurboForm::Controller
+end
+```
+
+```ruby
+concern :turbo_form, TurboForm::Routes
+```
+
+Draw the concern on each resource with a dynamic form — the installer leaves
+which ones to you:
+
+```ruby
+resources :widgets, concerns: :turbo_form
+```
+
+It draws a PATCH beside whichever of `new` and `edit` the resource has, so
+`resources :widgets, only: %i[new create], concerns: :turbo_form` gets only the
+one for `new`.
+
+It also imports the script into `app/javascript/application.js`, adding the npm
+package first if your app bundles with esbuild, Vite, Bun or webpack; see
+[JavaScript](#javascript) for doing that by hand.
 
 ## The two options
 
 ### `dynamic:` on the form
 
-`dynamic: true` makes the form dynamic: on a reload, it assigns the submitted
-values under its scope to its object, via `assign_attributes`, before any field
-renders.
+`dynamic: true` makes the form dynamic: a trigger sends it to the `new` or `edit`
+page of its model — `edit` once the record is saved — which is where
+`TurboForm::Routes` listens.
 
 ### `dynamic_trigger:` on a field
 
@@ -54,10 +79,12 @@ renders.
 <%= f.text_field :name, dynamic_trigger: :blur %>      <%# on a named event %>
 ```
 
-`true` lets Stimulus pick the element's natural event: `change` for a select or
-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.
+`true` picks the element's natural event: `change` for a select, `click` for a
+submit button, `input` for everything else. Name an event when you want
+something else — `:blur` on text fields is usually what you want, since the
+default fires on every keystroke. Any event name works, including custom ones
+dispatched by other Stimulus controllers — `dynamic_trigger: "autocomplete:selected"`
+— as long as the event is dispatched on the field or bubbles up from inside it.
 
 Works on every Rails field helper, including the select and date families where
 Rails keeps HTML attributes in a separate hash:
@@ -76,100 +103,90 @@ inherits from, so it works without SimpleForm being involved at all:
   = f.input :category, input_html: { dynamic_trigger: true }
 ```
 
-## What a reload does
+## What a trigger does
 
-A trigger visits the page's own URL with the form's fields in the query string,
-leaving out the authenticity token and `_method`, and marks the request with an
-`X-Turbo-Form` header. On the server:
+A trigger PATCHes the whole form to its own page — `/widgets/new` or
+`/widgets/:id/edit` — which the route concern sends to that page's own action.
+The request:
 
-1. the page's controller runs as it would for any visit, building `@widget` the
-   way it always does — found by id, built from a parent, whatever it does,
-2. the form assigns the submitted values to that object as it starts to render,
-3. the whole request runs inside a database transaction that is always rolled
-   back.
+1. runs `new` or `edit` as an ordinary visit would, callbacks and all, building
+   `@widget` the way it always does — found by id, built from a parent,
+   whatever it does,
+2. assigns `widget_params` to it,
+3. renders the page's own template,
 
-Only a request carrying the header is assigned anything. A plain link can't set
-a header, and another origin can't without a CORS preflight, so a hand-crafted
-URL with form values in it renders the page as if they weren't there.
+all inside a database transaction that is always rolled back.
 
-The rollback is there because Active Record saves some assignments on the spot
-(`has_many` writers, `*_ids=`). A reload exists to render, so nothing it does is
-kept — including anything else the action writes.
+Because the values are assigned in the controller, before anything renders, the
+whole page sees what was typed — the layout, the template above the form, and
+the form itself.
 
-### Needing the values before the form
+The rollback is there because Active Record saves some assignments on the spot
+(`has_many` writers, `*_ids=`). A trigger exists to render, so nothing it does is
+kept — including anything else the action or its callbacks write.
 
-The form assigns as it starts to render, so everything from the form down — and
-the layout, which Rails renders after the template — sees what was typed. The
-controller, and anything in the template above the form, sees the object as it
-was built. When those need it too, assign in the action:
+### The conventions it leans on
 
-```ruby
-def new
-  @widget = turbo_form_assign(Widget.new)
-end
-```
+turbo_form knows nothing about your resource beyond its controller's name.
+For a `WidgetsController`:
 
-`turbo_form_assign` returns the object, assigns only on a reload, and takes
-`scope:` when the form's scope isn't the object's param key. The form assigns
-the same values again when it renders, which changes nothing.
+- `new` and `edit` set `@widget`,
+- `widget_params` permits the form's fields — the same method `create` and
+  `update` already use, so a trigger assigns nothing a save wouldn't,
+- `new` and `edit` leave rendering to Rails. The values are assigned just before
+  Rails' implicit render, so an action that calls `render` itself renders its
+  object as it built it, and one that redirects still redirects.
 
 ### Switching an STI subclass
 
-When the submitted values include the inheritance column, the form switches its
-object to the subclass it names, with `becomes`, before assigning — so a `type`
-select can turn a `Gizmo` into a `Doohickey` and the rest of the form answers
-as one. Give the form its base class's scope (`scope: :gadget`) so the switched
-object reads and posts under the same name.
+When the submitted values include the inheritance column, the object is switched
+to the subclass it names, with `becomes`, before assigning — so a `type` select
+can turn a `Gizmo` into a `Doohickey` and the rest of the page answers as one.
+Give the form its base class's scope (`scope: :gadget`) so the switched object
+reads and posts under the same name, and permit `type` in the params method.
 
-The switched object shares its attributes with the original, so everything
-outside the form sees the same values. To have it be the new subclass too, keep
-what `turbo_form_assign` returns — it switches the same way.
+### Inside a Turbo Frame
+
+A form inside a `<turbo-frame>`, or one naming a frame with
+`data-turbo-frame`, asks for that frame alone: the request carries the
+`Turbo-Frame` header, turbo-rails renders without the layout, and only the frame
+is morphed. A frame's own `target` is followed, and `_top` means the whole page,
+as they do for Turbo. While the request is out, the form and its frame are `aria-busy`, and the
+frame `busy`, the way Turbo marks a submission.
 
 ### After a failed save
 
-Rendering `:new` or `:edit` with `422` after a failed save leaves the browser on
-the form's own URL, since Turbo renders it without touching history — so a
-trigger reloads the right page. The reload builds a fresh object that has not
-been validated, so the error messages go away.
+A trigger sends the form to its model's `new` or `edit` page, not to whatever
+URL the browser is on, so a trigger after rendering `:new` from a failed
+`create` still reaches the right action. The object it builds is fresh and has
+not been validated, so the error messages go away.
 
 ## JavaScript
 
-**importmap-rails** — nothing to do. The engine pins its controller as
-`controllers/turbo_form_controller`, which the `eagerLoadControllersFrom` /
-`lazyLoadControllersFrom` in a stock `app/javascript/controllers/index.js`
-registers as `turbo-form` on its own.
-
-If you hand-wrote that file, register it yourself:
+There is no Stimulus controller to register. The script listens on the document
+for triggers, so it only has to be imported once:
 
 ```js
-import TurboFormController from "controllers/turbo_form_controller"
-application.register("turbo-form", TurboFormController)
+// app/javascript/application.js
+import "turbo_form"             // importmap-rails: the engine pins it
+import "@rolemodel/turbo-form"  // esbuild, Vite, Bun, webpack
 ```
 
-**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
+Bundled apps install the npm package alongside the gem, at the same version.
+`rails generate turbo_form:install` does that with whichever package manager
+your lockfile names, and adds the import.
+
+To send a form from your own code, import `refresh`:
 
 ```js
-// app/javascript/controllers/turbo_form_controller.js
-import TurboFormController from "@rolemodel/turbo-form"
+import { refresh } from "turbo_form"
 
-export default TurboFormController
+refresh(document.querySelector("form[data-turbo-form-url]"))
 ```
 
-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 reload is a round trip, so the line after a trigger is racing it. Wrap the
+A trigger is a round trip, so the line after it is racing it. Wrap the
 trigger and the wait comes with it:
 
 ```ruby
@@ -179,22 +196,25 @@ select "Barrel Aged", from: "Flavor"
 
 `expect_dynamic_form_request` is available in system tests with nothing to
 require or include — Minitest and RSpec both. It waits on a count of
-completed reloads kept on `<html>` rather than on the fields that came back, so
-it doesn't care what the reload changed.
+completed triggers kept on `<html>` rather than on the fields that came back, so
+it doesn't care what the trigger changed.
 
 ## What this deliberately doesn't do
 
 It handles the common case well and gets out of the way otherwise.
 
-- **No debouncing, request cancellation or loading state.** Write the action by
-  hand when you need those — that path is still open.
-- **The form rides in the URL.** Very large forms can hit URL length limits,
-  file inputs are left out, and what was typed lands in browser history and any
-  access log outside Rails' own parameter filtering.
+- **No debouncing, request cancellation or loading state** beyond `aria-busy`.
+  Write the action by hand when you need those — that path is still open.
+- **Resourceful pages only.** The form's URL comes from its model, so a page
+  whose `new` or `edit` isn't the model's own route has nowhere to send it.
+- **Not a Turbo form submission.** Turbo renders a form's response only when it
+  redirects or fails, so the trigger fetches the form itself and hands the
+  response to a Turbo visit. Turbo renders the page — its morph, render events,
+  error page and progress bar — but there are no `turbo:submit-start`,
+  `turbo:submit-end` or `turbo:before-fetch-request` events. A frame is morphed
+  directly, without Turbo's frame render events.
 - **Only the primary database is rolled back**, and only writes: jobs enqueued
-  or mail sent during a reload still happen. A streamed response renders after
-  the transaction has closed.
-- **A form with Turbo turned off** reloads whatever URL a failed save left it on.
+  or mail sent during a trigger still happen.
 
 ## License
 

data/app/assets/javascripts/turbo_form.js

@@ -1,38 +1,147 @@
-import { Controller } from "@hotwired/stimulus"
 import { Turbo } from "@hotwired/turbo-rails"
 
-// Never worth putting in a URL: the token is a secret, and the page's own
-// verb is GET whatever the form says.
-const UNSENT = new Set(["authenticity_token", "_method"])
-
-// Reloads the page with the form's current state in the query string. The
-// page's own action renders it again, and the form assigns that state to its
-// object on the way, so the whole page answers as the user now has it. The
-// header is what tells the server this is that reload and not an ordinary
-// visit to the same URL.
+// PATCHes the form, as it stands, to the page it is on. The server runs that
+// page's own action, assigns the form to its object and renders its own
+// template, which is morphed in so focus, scroll and everything typed survive.
+// Inside a frame, only the frame is asked for and morphed, as Turbo would.
 //
-// A morphing refresh keeps focus and scroll, so it reads as the form updating
-// in place rather than as a navigation.
-export default class extends Controller {
-  perform() {
-    const url = new URL(location.href)
-    const data = new FormData(this.element)
-
-    for (const name of new Set(data.keys())) url.searchParams.delete(name)
-    for (const [name, value] of data) {
-      if (typeof value === "string" && !UNSENT.has(name)) url.searchParams.append(name, value)
-    }
+// Fetched rather than submitted through Turbo, which renders a form response
+// only if it redirects or fails. The page is still rendered by Turbo: a visit
+// handed the response, so its events, error page and progress bar all apply. A
+// frame is morphed directly, since Turbo's frame loading wants its own
+// unexported response object.
+export function refresh(form) {
+  return new FormRefresh(form).start()
+}
 
-    const markReload = ({ detail: { url: requested, fetchOptions } }) => {
-      if (requested.href !== url.href) return
+// Shaped like Turbo's FormSubmission, which is what its navigator expects to be
+// told about.
+class FormRefresh {
+  constructor(formElement) {
+    this.formElement = formElement
+    this.location = new URL(formElement.dataset.turboFormUrl, location.href)
+    this.target = targetFor(formElement)
+  }
+
+  async start() {
+    this.requestStarted()
+    try {
+      const response = await Turbo.fetch(this.location, { method: "PATCH", body: new FormData(this.formElement), headers: this.target.headers })
 
-      fetchOptions.headers["X-Turbo-Form"] = "reload"
-      document.removeEventListener("turbo:before-fetch-request", markReload)
+      this.target.render(response.status, await response.text())
+    } finally {
+      this.requestFinished()
     }
+  }
+
+  requestStarted() {
+    markAsBusy(this.formElement, ...this.target.elements)
+    Turbo.navigator.formSubmissionStarted(this)
+  }
+
+  requestFinished() {
+    clearBusyState(this.formElement, ...this.target.elements)
+    Turbo.navigator.formSubmissionFinished(this)
+  }
+}
+
+class PageTarget {
+  elements = []
+  headers = { Accept: "text/html" }
 
-    document.addEventListener("turbo:before-fetch-request", markReload)
+  render(statusCode, responseHTML) {
     document.addEventListener("turbo:load", countVisit, { once: true })
-    Turbo.visit(url, { action: "replace", shouldCacheSnapshot: false, refresh: { method: "morph", scroll: "preserve" } })
+    Turbo.visit(location.href, {
+      action: "replace",
+      shouldCacheSnapshot: false,
+      refresh: { method: "morph", scroll: "preserve" },
+      response: { statusCode, responseHTML }
+    })
+  }
+}
+
+class FrameTarget {
+  constructor(element) {
+    this.element = element
+    this.elements = [ element ]
+  }
+
+  get headers() {
+    return { Accept: "text/html", "Turbo-Frame": this.element.id }
+  }
+
+  render(_statusCode, responseHTML) {
+    const frame = new DOMParser().parseFromString(responseHTML, "text/html").getElementById(this.element.id)
+
+    Turbo.morphTurboFrameElements(this.element, frame)
+    countVisit()
+  }
+}
+
+// Turbo's own targeting: the form's data-turbo-frame, then the target of the
+// frame it sits in, then that frame itself. "_top" means the page.
+function targetFor(form) {
+  const enclosing = form.closest("turbo-frame")
+  const id = form.dataset.turboFrame || enclosing?.getAttribute("target")
+  const frame = id === "_top" ? null : id ? document.getElementById(id) : enclosing
+
+  return frame ? new FrameTarget(frame) : new PageTarget()
+}
+
+const triggerSelector = "[data-turbo-form-trigger]"
+
+// Shaped like Turbo's observers. One listener per event the page's triggers
+// name, on the event target and in the capture phase, so fields rendered later
+// are covered and events that don't bubble, like blur, still arrive. New names
+// are picked up as triggers appear; the browser ignores a listener it already has.
+class TriggerObserver {
+  constructor(delegate, eventTarget) {
+    this.delegate = delegate
+    this.eventTarget = eventTarget
+    this.mutationObserver = new MutationObserver(this.listen)
+  }
+
+  start() {
+    this.listen()
+    this.mutationObserver.observe(this.eventTarget, { subtree: true, childList: true, attributeFilter: [ "data-turbo-form-trigger" ] })
+  }
+
+  listen = () => {
+    for (const trigger of this.eventTarget.querySelectorAll(triggerSelector)) {
+      this.eventTarget.addEventListener(eventFor(trigger), this.triggerCaptured, true)
+    }
+  }
+
+  triggerCaptured = ({ type, target }) => {
+    const trigger = target.closest?.(triggerSelector)
+    const form = trigger?.form
+
+    if (form?.dataset.turboFormUrl && eventFor(trigger) == type) this.delegate.triggerFired(form)
+  }
+}
+
+// A trigger with no event named fires on its element's natural one.
+function eventFor(trigger) {
+  const named = trigger.dataset.turboFormTrigger
+  if (named) return named
+  if (trigger.localName == "select") return "change"
+  if (trigger.type == "submit") return "click"
+
+  return "input"
+}
+
+// Turbo's own busy state, which it doesn't export.
+function markAsBusy(...elements) {
+  for (const element of elements) {
+    if (element.localName == "turbo-frame") element.setAttribute("busy", "")
+    element.setAttribute("aria-busy", "true")
+  }
+}
+
+function clearBusyState(...elements) {
+  for (const element of elements) {
+    if (element.localName == "turbo-frame") element.removeAttribute("busy")
+    element.removeAttribute("aria-busy")
   }
 }
 
@@ -43,3 +152,5 @@ function countVisit() {
   const root = document.documentElement.dataset
   root.turboFormVisits = Number(root.turboFormVisits || 0) + 1
 }
+
+new TriggerObserver({ triggerFired: refresh }, document).start()

data/config/turbo_form_importmap.rb

@@ -1,5 +1,3 @@
-# Keyed as `controllers/..._controller` so the stock
-# `eagerLoadControllersFrom("controllers", application)` in a Rails app finds it
-# and registers it as `turbo-form`, with nothing asked of the host. The asset
-# name is distinct so the host's own app/javascript/controllers can't shadow it.
-pin "controllers/turbo_form_controller", to: "turbo_form.js"
+# Imported once by the host's application.js, which starts its listeners. The
+# asset name is distinct so nothing in the host's app/javascript can shadow it.
+pin 'turbo_form', to: 'turbo_form.js'

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

@@ -1,62 +1,56 @@
-require "rails/generators"
+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.
+    # Every app gets TurboForm::Controller, the route concern its resources opt
+    # into and an import of the script. On importmap-rails the engine pins the
+    # script itself; bundled apps get the npm package to import instead.
     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"
+        'yarn.lock' => 'yarn add', 'pnpm-lock.yaml' => 'pnpm add',
+        'bun.lock' => 'bun add', 'bun.lockb' => 'bun add'
       }.freeze
 
+      ENTRYPOINT = 'app/javascript/application.js'
+
       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
+        include_controller
+        declare_route_concern
+        install_package unless importmap?
+        import_script
       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
+      def include_controller
+        inject_into_class 'app/controllers/application_controller.rb', 'ApplicationController', "  include TurboForm::Controller\n"
+      end
+
+      # Declared once, drawn on no resource: which forms are dynamic is the
+      # app's call, one `concerns: :turbo_form` at a time.
+      def declare_route_concern
+        route 'concern :turbo_form, TurboForm::Routes'
+      end
+
+      def importmap? = Rails.root.join('config/importmap.rb').exist?
+
+      def install_package
+        run "#{package_manager} #{package}"
+      end
+
+      def import_script
+        import = %(import "#{importmap? ? "turbo_form" : "@rolemodel/turbo-form"}"\n)
+        return say("Add #{import.strip} to your JavaScript entrypoint.") unless Rails.root.join(ENTRYPOINT).exist?
+
+        append_to_file ENTRYPOINT, import
+      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/turbo_form/controller.rb

@@ -0,0 +1,60 @@
+module TurboForm
+  # Included into the host's ApplicationController. A request that
+  # TurboForm::Routes marks runs `new` or `edit` as usual, callbacks and all,
+  # then assigns the form to what the action built just before the implicit
+  # render.
+  #
+  # Leans on the scaffold's conventions: the action builds `@<resource>`,
+  # `<resource>_params` permits the form, and the action leaves rendering to Rails.
+  module Controller
+    private
+    def process_action(...)
+      dynamic_form? ? discarding_writes { super } : super
+    end
+
+    def default_render
+      dynamic_form_assignment if dynamic_form?
+      super
+    end
+
+    def dynamic_form_assignment
+      resource = turbo_form_resource.extend(TurboForm::Resource).dynamic_assign(turbo_form_resource_params)
+      instance_variable_set(:"@#{turbo_form_resource_name}", resource)
+    end
+
+    def dynamic_form? = request.path_parameters[:dynamic_form]
+    def turbo_form_resource = instance_variable_get(:"@#{turbo_form_resource_name}")
+    def turbo_form_resource_params = send(:"#{turbo_form_resource_name}_params")
+    def turbo_form_resource_name = controller_name.singularize
+
+    # Active Record saves `has_many` writers and `*_ids=` on assignment, and
+    # this request exists only to render.
+    def discarding_writes
+      return yield unless defined?(ActiveRecord::Base)
+
+      ActiveRecord::Base.transaction do
+        yield
+        raise ActiveRecord::Rollback
+      end
+    end
+  end
+
+  # Switches to the STI subclass the submitted `type` names before assigning, so
+  # nested records land on the object that is kept -- which is returned.
+  module Resource
+    def dynamic_assign(params)
+      retype(params).tap { it.assign_attributes(params) }
+    end
+
+    private
+    def retype(params)
+      type = inheritance_column && params[inheritance_column]
+      return self if type.blank?
+
+      subclass = self.class.sti_class_for(type)
+      instance_of?(subclass) ? self : becomes!(subclass)
+    end
+
+    def inheritance_column = self.class.try(:inheritance_column)
+  end
+end

data/lib/turbo_form/engine.rb

@@ -1,7 +1,8 @@
-require "turbo-rails"
-require "turbo_form/form_helper"
-require "turbo_form/form_builder"
-require "turbo_form/reload"
+require 'turbo-rails'
+require 'turbo_form/form_helper'
+require 'turbo_form/form_builder'
+require 'turbo_form/routes'
+require 'turbo_form/controller'
 
 module TurboForm
   class Engine < ::Rails::Engine
@@ -10,20 +11,20 @@ module TurboForm
     # here both registers ours and leaves the host able to override them.
     # The guard keeps esbuild/vite/bun hosts booting; a `before:` naming an
     # initializer that doesn't exist is itself harmless.
-    initializer "turbo_form.importmap", before: "importmap" do |app|
+    initializer 'turbo_form.importmap', before: 'importmap' do |app|
       next unless app.config.respond_to?(:importmap)
 
-      app.config.importmap.paths << root.join("config/turbo_form_importmap.rb")
-      app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+      app.config.importmap.paths << root.join('config/turbo_form_importmap.rb')
+      app.config.importmap.cache_sweepers << root.join('app/assets/javascripts')
     end
 
     # Propshaft puts every engine's app/assets/* on the load path by itself.
     # Sprockets additionally wants the asset named, or the pin above silently
     # resolves to nothing.
-    initializer "turbo_form.assets" do |app|
+    initializer 'turbo_form.assets' do |app|
       next unless app.config.respond_to?(:assets)
 
-      app.config.assets.precompile << "turbo_form.js"
+      app.config.assets.precompile << 'turbo_form.js'
     end
 
     # Minitest's system tests descend from ActionDispatch::SystemTestCase, so
@@ -31,9 +32,9 @@ module TurboForm
     # assembles itself from Action Dispatch's parts instead of inheriting the
     # case -- so they need telling separately, once RSpec is loaded but before
     # any example group has been defined.
-    initializer "turbo_form.system_test_helper" do
+    initializer 'turbo_form.system_test_helper' do
       ActiveSupport.on_load(:action_dispatch_system_test_case) do
-        require "turbo_form/system_test_helper"
+        require 'turbo_form/system_test_helper'
 
         include TurboForm::SystemTestHelper
       end
@@ -42,24 +43,19 @@ module TurboForm
     config.after_initialize do
       next unless defined?(RSpec.configure)
 
-      require "turbo_form/system_test_helper"
+      require 'turbo_form/system_test_helper'
 
       RSpec.configure do |config|
         config.include TurboForm::SystemTestHelper, type: :system
       end
     end
 
-    initializer "turbo_form.reload" do |app|
-      app.middleware.use TurboForm::Reload::Middleware
-      ActiveSupport.on_load(:action_controller_base) { include TurboForm::Reload::Controller }
-    end
-
     # Deliberately eager rather than `ActiveSupport.on_load(:action_view)`: that
     # hook doesn't fire until Action View is first loaded, which in an app that
     # isn't eager loading is partway through rendering the first view -- late
     # enough that the first form on the first request can miss the patch.
-    initializer "turbo_form.form_helpers" do
-      require "action_view"
+    initializer 'turbo_form.form_helpers' do
+      require 'action_view'
 
       ActionView::Helpers::FormHelper.prepend(TurboForm::FormHelper)
       ActionView::Helpers::FormBuilder.prepend(TurboForm::FormBuilder)

data/lib/turbo_form/form_builder.rb

@@ -4,20 +4,11 @@ module TurboForm
   #   f.text_field :name, dynamic_trigger: true      # re-render on the default event
   #   f.select :category, categories, {}, dynamic_trigger: :blur
   #
-  # `dynamic_trigger:` always has to end up as a `data-action`, but where it
+  # `dynamic_trigger:` always has to end up as a data attribute, but where it
   # *arrives* depends on the helper. Most treat their `options` hash as the tag's
   # HTML attributes; the select and date families keep those in a trailing
   # `html_options` instead, which is where these overrides earn their keep.
   module FormBuilder
-    # A dynamic form's trigger reloads the page with the form's current state in
-    # the query string. Assigning it here, before the form's block runs, lets
-    # every field -- and every question the form asks of its object -- answer
-    # as the user now has it.
-    def initialize(object_name, object, template, options)
-      super
-      @object = TurboForm::Reload.assign(object, @template.params[object_name]) if options[:dynamic] && TurboForm::Reload.requested?(@template.try(:request))
-    end
-
     def select(method, choices = nil, options = {}, html_options = {}, &block)
       super(method, choices, *hoist_trigger(options, html_options), &block)
     end
@@ -59,41 +50,37 @@ module TurboForm
     end
 
     private
-      # Every other field helper -- generated and hand-written alike -- passes its
-      # attributes through here on the way to the tag.
-      def objectify_options(options)
-        super(absorb_trigger(options))
-      end
-
-      # A trailing `dynamic_trigger:` binds to `options` because Ruby folds bare
-      # keywords into the first optional positional hash -- but for these helpers
-      # that hash is the *select's* options, not the tag's. Carry it across.
-      # SimpleForm arrives on the other side, via `input_html:`, so take it from
-      # either.
-      def hoist_trigger(options, html_options)
-        return [ options, absorb_trigger(html_options) ] unless options.key?(:dynamic_trigger)
-
-        trigger = options[:dynamic_trigger]
-        [ options.except(:dynamic_trigger), absorb_trigger(html_options.merge(dynamic_trigger: trigger)) ]
-      end
-
-      def absorb_trigger(attributes)
-        return attributes unless attributes.key?(:dynamic_trigger)
-
-        trigger = attributes[:dynamic_trigger]
-        attributes = attributes.except(:dynamic_trigger)
-        return attributes unless trigger
-
-        data = (attributes[:data] || {}).dup
-        data[:action] = [ data[:action], stimulus_action_for(trigger) ].compact.join(" ")
-        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(event)
-        event.nil? || event == true ? "turbo-form#perform" : "#{event}->turbo-form#perform"
-      end
+    # Every other field helper -- generated and hand-written alike -- passes its
+    # attributes through here on the way to the tag.
+    def objectify_options(options)
+      super(absorb_trigger(options))
+    end
+
+    # A trailing `dynamic_trigger:` binds to `options` because Ruby folds bare
+    # keywords into the first optional positional hash -- but for these helpers
+    # that hash is the *select's* options, not the tag's. Carry it across.
+    # SimpleForm arrives on the other side, via `input_html:`, so take it from
+    # either.
+    def hoist_trigger(options, html_options)
+      return [ options, absorb_trigger(html_options) ] unless options.key?(:dynamic_trigger)
+
+      trigger = options[:dynamic_trigger]
+      [ options.except(:dynamic_trigger), absorb_trigger(html_options.merge(dynamic_trigger: trigger)) ]
+    end
+
+    def absorb_trigger(attributes)
+      return attributes unless attributes.key?(:dynamic_trigger)
+
+      trigger = attributes[:dynamic_trigger]
+      attributes = attributes.except(:dynamic_trigger)
+      return attributes unless trigger
+
+      attributes.merge(data: { **attributes[:data].to_h, turbo_form_trigger: trigger_event(trigger) })
+    end
+
+    # Left blank for `true`, which the script reads as the element's own
+    # default: `change` for a select, `input` for a text field, `click` for a
+    # button.
+    def trigger_event(trigger) = trigger == true ? '' : trigger.to_s
   end
 end

data/lib/turbo_form/form_helper.rb

@@ -7,19 +7,21 @@ module TurboForm
     # stays in the options so the builder sees it; Rails slices the form tag's
     # attributes out by name, so it never reaches the HTML.
     def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block)
-      wire_dynamic_form(options) if options[:dynamic]
+      wire_dynamic_form(options, model) if options[:dynamic]
       super
     end
 
     private
-      # `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.
-      def wire_dynamic_form(options)
-        attributes = options.key?(:html) ? (options[:html] ||= {}) : options
-        data = attributes[:data] ||= {}
+    # `form_for` funnels HTML attributes through options[:html] while `form_with`
+    # takes them at the top level. Write wherever the caller already is.
+    def wire_dynamic_form(options, model)
+      attributes = options.key?(:html) ? (options[:html] ||= {}) : options
+      (attributes[:data] ||= {})[:turbo_form_url] = namesake_path(model)
+    end
 
-        data[:controller] = [ data[:controller], "turbo-form" ].compact.join(" ")
-      end
+    # The page the form is on, which TurboForm::Routes answers PATCH on too.
+    def namesake_path(model)
+      polymorphic_path(model, action: Array(model).last.persisted? ? :edit : :new)
+    end
   end
 end

data/lib/turbo_form/routes.rb

@@ -0,0 +1,16 @@
+module TurboForm
+  # A callable route concern. Draws a PATCH beside whichever of a resource's `new`
+  # and `edit` it has, at the same paths and onto the same actions, marked so the
+  # controller renders them from what the form currently holds.
+  #
+  #   concern :turbo_form, TurboForm::Routes
+  #   resources :widgets, concerns: :turbo_form
+  module Routes
+    def self.call(mapper, _options = {})
+      actions = mapper.send(:parent_resource).actions
+
+      mapper.new { mapper.patch :new, as: nil, defaults: { dynamic_form: true } } if actions.include?(:new)
+      mapper.patch :edit, on: :member, as: nil, defaults: { dynamic_form: true } if actions.include?(:edit)
+    end
+  end
+end

data/lib/turbo_form/system_test_helper.rb

@@ -4,7 +4,7 @@ module TurboForm::SystemTestHelper
   #   expect_dynamic_form_request { select "Bourbon", from: "Category" }
   #   select "Barrel Aged", from: "Flavor"
   def expect_dynamic_form_request
-    completed = page.find("html")["data-turbo-form-visits"].to_i + 1
+    completed = page.find('html')['data-turbo-form-visits'].to_i + 1
 
     yield
 

data/lib/turbo_form/version.rb

@@ -1,3 +1,3 @@
 module TurboForm
-  VERSION = "0.5.0"
+  VERSION = '0.6.0'
 end

data/lib/turbo_form.rb

@@ -1,2 +1,2 @@
-require "turbo_form/version"
-require "turbo_form/engine"
+require 'turbo_form/version'
+require 'turbo_form/engine'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_form
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Andy Cohen
@@ -78,13 +78,13 @@ files:
 - app/assets/javascripts/turbo_form.js
 - 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/controller.rb
 - lib/turbo_form/engine.rb
 - lib/turbo_form/form_builder.rb
 - lib/turbo_form/form_helper.rb
-- lib/turbo_form/reload.rb
+- lib/turbo_form/routes.rb
 - lib/turbo_form/system_test_helper.rb
 - lib/turbo_form/version.rb
 homepage: https://github.com/outlawandy/turbo_form

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

@@ -1,4 +0,0 @@
-// 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/reload.rb

@@ -1,68 +0,0 @@
-module TurboForm
-  # A dynamic trigger reloads its page with this header set. Only a request
-  # carrying it has its form's state assigned, and only such a request has its
-  # writes discarded -- one predicate for both, so the one can't happen without
-  # the other. A plain link can't set a header, and a cross-origin page can't
-  # without a CORS preflight, so a crafted URL assigns nothing.
-  module Reload
-    HEADER = "X-Turbo-Form"
-
-    def self.requested?(request) = request&.headers&.key?(HEADER)
-
-    # Answers with the object the form should now render, which is a different
-    # one when the submitted `type` picks another STI subclass.
-    def self.assign(object, submitted)
-      return object unless submitted.is_a?(ActionController::Parameters)
-
-      retype(object, submitted).tap { |record| record.assign_attributes(submitted.permit!) }
-    end
-
-    # Let `new` pick the subclass by Active Record's own STI rules, and switch
-    # before assigning so nested records land on the object that is kept.
-    # `becomes` shares its attributes with the original, so whoever still holds
-    # that one sees the same values, if not the subclass's behaviour.
-    def self.retype(object, submitted)
-      column = object.class.try(:inheritance_column)
-      return object unless column && submitted.key?(column)
-
-      subclass = object.class.base_class.new(column => submitted[column]).class
-      object.instance_of?(subclass) ? object : object.becomes(subclass)
-    end
-
-    # Included into ActionController::Base, for an action that needs the form's
-    # state before the form itself is rendered:
-    #
-    #   @widget = turbo_form_assign(Widget.new)
-    #
-    # The form assigns the same state again when it renders, which changes
-    # nothing. Keep what it returns: that is the switched object when the form
-    # picked another STI subclass.
-    module Controller
-      private
-        def turbo_form_assign(object, scope: object.model_name.param_key)
-          return object unless TurboForm::Reload.requested?(request)
-
-          TurboForm::Reload.assign(object, params[scope])
-        end
-    end
-
-    # Assigning to a saved record is not always inert -- Active Record saves
-    # `has_many` writers and `*_ids=` on the spot -- and a reload exists only to
-    # render, so nothing it does is kept.
-    class Middleware
-      def initialize(app) = @app = app
-
-      def call(env)
-        return @app.call(env) unless defined?(ActiveRecord::Base) && Reload.requested?(ActionDispatch::Request.new(env))
-
-        response = nil
-        ActiveRecord::Base.transaction do
-          # ponytail: a streamed body renders after this returns, outside the transaction
-          response = @app.call(env)
-          raise ActiveRecord::Rollback
-        end
-        response
-      end
-    end
-  end
-end