turbo_form 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 766426d5a82a0111940995bccf95c62656da129bef99756e5175691745d223c8
-  data.tar.gz: d9fb56cc66201aa99f78aac9fdeb5aeb5f148a13315d800197d7ed02116d3f5f
+  metadata.gz: 01bb2ce15b4fc755a0f4b689fa4e11d1a34627a206d95d5b2d008ad3d9e66aa3
+  data.tar.gz: 52860d7614b4aa8cd960721ee677854704324d34f0abdcdd938f879546daf7d2
 SHA512:
-  metadata.gz: d4ac30341bedfbeb31a2dc295c81bbf54b2b42cdc847edb8e34efbf822d364f86346468445eb7ad64db4fcd7abcc7b72a390f0e0bb34cc33f3af2995927ad609
-  data.tar.gz: 8158bb3dc3a3462ab3f79676d2e6f5e8a5930deec48a57ddb9cb0235c568ad094aa56ca8a236aab148ce915326197eaf499ae1a2c380241ca0e67775d68f8ae2
+  metadata.gz: cfee3dbcfb3d319e0e1265735a9dfe88d86a0479f3cfb01b53ad9879ef9f1d7b92eaf8679a9486613ffaba54a57f3f1e2965a66531aa6065557927a629ce39d1
+  data.tar.gz: 82b3308ced5f38ace3d7e4f170b1beb77d0559f24a67cbfb91174e39de67ef9e66831a8d1a6a9fa03a2def2772459a821833aa684b45bd6f8a6141443ab36113

data/README.md

@@ -37,10 +37,15 @@ 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
 
@@ -72,6 +77,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:
 
@@ -97,7 +126,8 @@ 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,
 3. assigns it to `@resource`,
-4. renders the turbo_stream template.
+4. calls `TurboForm.before_render` with the controller and 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,
@@ -112,15 +142,55 @@ may come from the browser unverified.
 ```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 = ->(controller, 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 the controller and that resource.
+
+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 }
+
+# Action Policy's verify_authorized
+TurboForm.before_render = ->(controller, resource) { controller.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 = ->(controller, resource) { controller.authorize(resource, :edit?) }
+
+# Action Policy
+TurboForm.before_render = ->(controller, resource) { controller.authorize!(resource, to: :edit?) }
+
+# CanCanCan -- this also satisfies `check_authorization`, which has no runtime skip
+TurboForm.before_render = ->(controller, resource) { controller.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.
+
 ## JavaScript
 
 **importmap-rails** — nothing to do. The engine pins its controller as
@@ -135,31 +205,43 @@ 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 turbo_form
-```
 ```js
-import TurboFormController from "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
 
-The controller counts completed round trips, so a system test can wait on one
-instead of sleeping:
+A re-render is a round trip, so the line after a trigger is racing it. Wrap the
+trigger and the wait comes with it:
 
 ```ruby
-def expect_dynamic_form_request
-  form = find("[data-controller~='turbo-form']")
-  before = form["data-turbo-form-requests-value"].to_i
-  yield
-  assert_selector "[data-turbo-form-requests-value='#{before + 1}']"
-end
+expect_dynamic_form_request { select "Bourbon", from: "Category" }
+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 the controller's
+count of completed round trips rather than on the fields that came back, so it
+doesn't care what the response changed. Scope it with Capybara's `within` when
+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

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

@@ -10,13 +10,18 @@ module TurboForm
       head :bad_request
     end
 
-    def update
-      @resource = signature.model.new(form_params)
+    before_action :build_resource
+    before_action { TurboForm.before_render&.call(self, @resource) }
 
+    def update
       render template: signature.template_for(@resource), formats: :turbo_stream
     end
 
     private
+      def build_resource
+        @resource = signature.model.new(form_params)
+      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/engine.rb

@@ -30,6 +30,29 @@ module TurboForm
       app.config.assets.precompile << "turbo_form.js"
     end
 
+    # Minitest's system tests descend from ActionDispatch::SystemTestCase, so
+    # the load hook reaches them. RSpec's don't -- RSpec::Rails::SystemExampleGroup
+    # 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
+      ActiveSupport.on_load(:action_dispatch_system_test_case) do
+        require "turbo_form/system_test_helper"
+
+        include TurboForm::SystemTestHelper
+      end
+    end
+
+    config.after_initialize do
+      next unless defined?(RSpec.configure)
+
+      require "turbo_form/system_test_helper"
+
+      RSpec.configure do |config|
+        config.include TurboForm::SystemTestHelper, type: :system
+      end
+    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

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/system_test_helper.rb

@@ -0,0 +1,23 @@
+module TurboForm::SystemTestHelper
+  # Waits for a dynamic form to finish re-rendering itself.
+  #
+  # A trigger sends the form to the server and swaps part of it out when the
+  # response lands, so anything a test does on the next line is racing that
+  # response -- and loses often enough to be flaky rather than broken. The
+  # Stimulus controller counts completed round trips; waiting on that count is
+  # both cheaper and steadier than waiting on whichever field came back.
+  #
+  #   expect_dynamic_form_request { select "Bourbon", from: "Category" }
+  #   select "Barrel Aged", from: "Flavor"
+  #
+  # Scope it with Capybara's own `within` when a page carries more than one
+  # dynamic form.
+  def expect_dynamic_form_request
+    form = page.find("[data-controller~='turbo-form']")
+    completed = form["data-turbo-form-requests-value"].to_i + 1
+
+    yield
+
+    page.assert_selector "[data-turbo-form-requests-value='#{completed}']"
+  end
+end

data/lib/turbo_form/version.rb

@@ -1,3 +1,3 @@
 module TurboForm
-  VERSION = '0.1.0'
+  VERSION = '0.3.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 }
+
+  # 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.
+  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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andy Cohen
@@ -79,12 +79,15 @@ 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
 - lib/turbo_form/form_builder.rb
 - lib/turbo_form/form_helper.rb
 - lib/turbo_form/signature.rb
+- lib/turbo_form/system_test_helper.rb
 - lib/turbo_form/version.rb
 homepage: https://github.com/outlawandy/turbo_form
 licenses: