turbo_form 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cb1af8f341d1112a85f86bc4fe28470e83f867994be6029a32fbd996da03677
-  data.tar.gz: 97afa78d913454ea096c0f988ecb85d99f7ebe7027f02f2e19cc40af534b624e
+  metadata.gz: 69e93adb63b8efad18d18aa5009294ecf46dff732a835677016787a498a359fe
+  data.tar.gz: 8058b55a07707691cd9bb2770339f2685ca4c13f104cd97db01aeeef184326bd
 SHA512:
-  metadata.gz: 221fbbcd5e31c6191a208cefb92089f70094ef5709547cdb63984a4bb419342d7109dfe4001135853ee7380537b63d82a8cb2fef64af550d40a1a713dfa93f20
-  data.tar.gz: 2e7cd4ecec1194cc7605035e9a51c9dcd1542f3c45410c6497a74221e8ae6a037991650a6d928bdf230097af4cfbc0e7aaf73751326a912f291649b9e22221b4
+  metadata.gz: 641956f04889ecb24a6744d65f9a397e75dfa97ac5fcf57847dab4c41c06bf641268b0e620f4b9e8e1cdf865e23eaf97606a286b7db8eabc1d27d31a02707381
+  data.tar.gz: 36036dda2b7c129b9a4d704695d849049bcafbe4f5fec2b3690b2709e2e98dcaaaf2ffab4ce8c438712df1b6ea78bec0d29b08d25a9024c56ccd9d98c299d18e

data/README.md

@@ -64,7 +64,7 @@ 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
+## The options
 
 ### `dynamic:` on the form
 
@@ -80,19 +80,35 @@ page of its model — `edit` once the record is saved — which is where
 ```
 
 `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
+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:
+Works on every Rails field helper and on `f.submit` and `f.button`, including
+the select and date families where Rails keeps HTML attributes in a separate hash:
 
 ```erb
 <%= f.collection_select :category_id, Category.all, :id, :name, dynamic_trigger: true %>
 ```
 
+### `dynamic_action:` on a field
+
+```erb
+<%= f.select :flavor, @widget.flavors, {}, dynamic_action: summary_widgets_path %>
+<%= f.text_field :zip, dynamic_action: lookup_path(form: "widget"), dynamic_trigger: :blur %>
+<%= f.button "Swap", type: "button", dynamic_action: [:swap, @estimate] %>
+```
+
+For when the page's own render isn't the answer: the trigger PATCHes the whole
+form to that URL instead, asks for a Turbo Stream, and renders the stream it
+gets back, whatever its status, so a `422` of errors renders too. The URL is
+anything `url_for` takes. The action and its `.turbo_stream` template are yours. Nothing is assigned or
+rolled back for you, and the form doesn't need `dynamic: true`. It triggers on
+the field's default event unless `dynamic_trigger:` names one, and counts toward
+`expect_dynamic_form_request`.
+
 ### With SimpleForm
 
 turbo_form builds on `ActionView::Helpers::FormBuilder`, which SimpleForm
@@ -145,6 +161,16 @@ 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.
 
+### Telling a trigger from a visit
+
+`turbo_form_render?` is true while a trigger's request is rendering, in the
+controller and in views, so a layout can leave alone what an ordinary visit
+would set up — a modal that animates open on arrival, say:
+
+```erb
+<div data-open-on-connect="<%= !turbo_form_render? %>">
+```
+
 ### Inside a Turbo Frame
 
 A form inside a `<turbo-frame>`, or one naming a frame with
@@ -207,6 +233,8 @@ It handles the common case well and gets out of the way otherwise.
   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.
+  `dynamic_action:` is the way out, at the cost of writing the action and its
+  stream.
 - **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,

data/app/assets/javascripts/turbo_form.js

@@ -10,17 +10,22 @@ import { Turbo } from "@hotwired/turbo-rails"
 // 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()
+//
+// A trigger naming a URL of its own, with data-turbo-form-action, PATCHes the
+// form there instead and renders the Turbo Stream that comes back.
+export function refresh(form, trigger) {
+  return new FormRefresh(form, trigger).start()
 }
 
 // Shaped like Turbo's FormSubmission, which is what its navigator expects to be
 // told about.
 class FormRefresh {
-  constructor(formElement) {
+  constructor(formElement, trigger) {
+    const action = trigger?.dataset.turboFormAction
+
     this.formElement = formElement
-    this.location = new URL(formElement.dataset.turboFormUrl, location.href)
-    this.target = targetFor(formElement)
+    this.location = new URL(action || formElement.dataset.turboFormUrl, location.href)
+    this.target = action ? new StreamTarget() : targetFor(formElement)
   }
 
   async start() {
@@ -28,7 +33,7 @@ class FormRefresh {
     try {
       const response = await Turbo.fetch(this.location, { method: "PATCH", body: new FormData(this.formElement), headers: { ...this.target.headers, "X-CSRF-Token": csrfToken() } })
 
-      this.target.render(response.status, await response.text())
+      await this.target.render(response)
     } finally {
       this.requestFinished()
     }
@@ -49,13 +54,15 @@ class PageTarget {
   elements = []
   headers = { Accept: "text/html" }
 
-  render(statusCode, responseHTML) {
+  async render(response) {
+    const responseHTML = await response.text()
+
     document.addEventListener("turbo:load", countVisit, { once: true })
     Turbo.visit(location.href, {
       action: "replace",
       shouldCacheSnapshot: false,
       refresh: { method: "morph", scroll: "preserve" },
-      response: { statusCode, responseHTML }
+      response: { statusCode: response.status, responseHTML }
     })
   }
 }
@@ -70,14 +77,30 @@ class FrameTarget {
     return { Accept: "text/html", "Turbo-Frame": this.element.id }
   }
 
-  render(_statusCode, responseHTML) {
-    const frame = new DOMParser().parseFromString(responseHTML, "text/html").getElementById(this.element.id)
+  async render(response) {
+    const frame = new DOMParser().parseFromString(await response.text(), "text/html").getElementById(this.element.id)
 
     Turbo.morphTurboFrameElements(this.element, frame)
     countVisit()
   }
 }
 
+const streamType = "text/vnd.turbo-stream.html"
+
+// Whatever the status, as Turbo does for a form: a 422 stream of errors is
+// rendered too. Anything else, like an HTML error page, isn't a stream to render.
+class StreamTarget {
+  elements = []
+  headers = { Accept: streamType }
+
+  async render(response) {
+    if (!response.headers.get("Content-Type")?.startsWith(streamType)) return
+
+    Turbo.renderStreamMessage(await response.text())
+    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) {
@@ -123,7 +146,7 @@ class TriggerObserver {
     const trigger = target.closest?.(triggerSelector)
     const form = trigger?.form
 
-    if (form?.dataset.turboFormUrl && eventFor(trigger) == type) this.delegate.triggerFired(form)
+    if (form && (trigger.dataset.turboFormAction || form.dataset.turboFormUrl) && eventFor(trigger) == type) this.delegate.triggerFired(form, trigger)
   }
 }
 
@@ -132,7 +155,7 @@ function eventFor(trigger) {
   const named = trigger.dataset.turboFormTrigger
   if (named) return named
   if (trigger.localName == "select") return "change"
-  if (trigger.type == "submit") return "click"
+  if (trigger.type == "submit" || trigger.type == "button") return "click"
 
   return "input"
 }

data/lib/turbo_form/controller.rb

@@ -7,16 +7,26 @@ module TurboForm
   # Leans on the scaffold's conventions: the action builds `@<resource>` and
   # `<resource>_params` permits the form.
   module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :turbo_form_render?
+    end
+
     # Public, as Rails' own is. ActionController::Base's public methods are never
     # actions, so this one isn't either.
     def render(...)
-      dynamic_form_assignment if dynamic_form?
+      dynamic_form_assignment if turbo_form_render?
       super
     end
 
     private
+    # Whether this request is a trigger's re-render rather than a visit, for a
+    # layout or template that should answer differently to one.
+    def turbo_form_render? = request.path_parameters.key?(:dynamic_form)
+
     def process_action(...)
-      dynamic_form? ? discarding_writes { super } : super
+      turbo_form_render? ? discarding_writes { super } : super
     end
 
     def dynamic_form_assignment
@@ -24,7 +34,6 @@ module TurboForm
       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

data/lib/turbo_form/form_builder.rb

@@ -3,12 +3,15 @@ module TurboForm
   #
   #   f.text_field :name, dynamic_trigger: true      # re-render on the default event
   #   f.select :category, categories, {}, dynamic_trigger: :blur
+  #   f.select :flavor, flavors, {}, dynamic_action: summary_widgets_path  # stream from a URL of its own
   #
   # `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
+    DYNAMIC_OPTIONS = %i[dynamic_trigger dynamic_action].freeze
+
     def select(method, choices = nil, options = {}, html_options = {}, &block)
       super(method, choices, *hoist_trigger(options, html_options), &block)
     end
@@ -49,6 +52,16 @@ module TurboForm
       super(method, *hoist_trigger(options, html_options))
     end
 
+    # These two hand their options straight to the tag helper, skipping
+    # `objectify_options`, and take them first when no value is given.
+    def submit(value = nil, options = {})
+      value.is_a?(Hash) ? super(absorb_trigger(value)) : super(value, absorb_trigger(options))
+    end
+
+    def button(value = nil, options = {}, &block)
+      value.is_a?(Hash) ? super(absorb_trigger(value), &block) : super(value, absorb_trigger(options), &block)
+    end
+
     private
     # Every other field helper -- generated and hand-written alike -- passes its
     # attributes through here on the way to the tag.
@@ -62,20 +75,20 @@ module TurboForm
     # 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)) ]
+      [ options.except(*DYNAMIC_OPTIONS), absorb_trigger(html_options.merge(options.slice(*DYNAMIC_OPTIONS))) ]
     end
 
+    # `dynamic_action:` makes a trigger of its own, on the default event unless
+    # `dynamic_trigger:` names one. It takes whatever `url_for` does.
     def absorb_trigger(attributes)
-      return attributes unless attributes.key?(:dynamic_trigger)
+      return attributes unless attributes.keys.intersect?(DYNAMIC_OPTIONS)
 
-      trigger = attributes[:dynamic_trigger]
-      attributes = attributes.except(:dynamic_trigger)
+      trigger, action = attributes.values_at(*DYNAMIC_OPTIONS)
+      attributes = attributes.except(*DYNAMIC_OPTIONS)
+      trigger ||= action.present?
       return attributes unless trigger
 
-      attributes.merge(data: { **attributes[:data].to_h, turbo_form_trigger: trigger_event(trigger) })
+      attributes.merge(data: { **attributes[:data].to_h, turbo_form_trigger: trigger_event(trigger), turbo_form_action: (@template.url_for(action) if action) })
     end
 
     # Left blank for `true`, which the script reads as the element's own

data/lib/turbo_form/version.rb

@@ -1,3 +1,3 @@
 module TurboForm
-  VERSION = '0.7.1'
+  VERSION = '0.8.0'
 end

metadata

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