turbo_form 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1637d6cbac8d370efc21308cc1ace27f278e2153fde411829fa4031d5980a54
-  data.tar.gz: 0247d756f8f6217149c1bd24e30acca602b0fa9a7af69acc7d07d0228a1a727c
+  metadata.gz: 959442a013960f1f2a4cbe72191b4fc965f15cc416be00b4d8ba2f2349dca3f9
+  data.tar.gz: 7fa3a58b24e6c22bf27bcfc994dad3aa3f121795ccf6f18211839f18cfb99045
 SHA512:
-  metadata.gz: b53a713122f8443e248f787953724cc0204aca67ae53b994122838fabaf7c9bf3300c720557f8a7818dba2154495d5f1ec98c289458f5456245c7f8550120349
-  data.tar.gz: fab34492c6b7b1b7f01efea76aa25a157d96c7ccaaed682c9e15f424e3e4512cc37543119caa9dcc381c52208cb891c73ee727d6a1c54c1c435610a0b8e9c8b4
+  metadata.gz: a62fcaf048717ca8261bac7e79a4c831bce7d02e9b0c0e6f689c3fe01d7966eeff9a4ed771977c703984b45e45b9ba1282f397ed2ba3b2a29a1f29ddb05dd7d2
+  data.tar.gz: 3a5c4756db5d7c1685733877e424198d6a338065bd51c79f2f2cb4d67c0875bb005bd9918835ab4125b65920ab50860a64e04488b14671b7d7eae41adb4e01c6

data/README.md

@@ -1,7 +1,16 @@
 # turbo_form
 
+<div>
+  <img src="https://github.com/OutlawAndy/turbo_form/actions/workflows/ci.yml/badge.svg" alt="CI">
+  <img src="https://img.shields.io/gem/v/turbo_form?label=rubygems" alt="RubyGems">
+  <img src="https://img.shields.io/npm/v/@rolemodel/turbo-form?label=npm" alt="npm">
+</div>
+<br/>
+
 Dynamic forms for Rails, by convention.
 
+![title image](title_image.png)
+
 A form that needs to change as it is filled in — a dependent dropdown, a section
 that appears once you pick a type — usually costs you a route, a controller
 action, a Stimulus controller and some wiring. This gem asks for two words
@@ -68,9 +77,9 @@ the route concern listens.
 ```
 
 `true` picks the element's natural event: `change` for a select, `click` for a
-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
+button, `input` for everything else. An `input` event fires on every keystroke,
+so it waits for a 300ms pause before sending the form. Name an event when you
+want something else, like `:blur`. 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.
 
@@ -81,6 +90,20 @@ the select and date families where Rails keeps HTML attributes in a separate has
 <%= f.collection_select :category_id, Category.all, :id, :name, dynamic_trigger: true %>
 ```
 
+### `dynamic_debounce:` on a field
+
+```erb
+<%= f.text_field :name, dynamic_trigger: true, dynamic_debounce: 500 %>   <%# wait longer %>
+<%= f.range_field :size, dynamic_trigger: true, dynamic_debounce: false %> <%# don't wait %>
+```
+
+How many milliseconds a trigger waits for its events to pause before sending
+the form, as it stands by then. `input` events wait 300ms unless told
+otherwise; every other event sends at once unless it names a wait.
+
+Text typed into a field while its request is out is kept when the response
+arrives, and a response overtaken by a later one to the same URL isn't rendered.
+
 ### `dynamic_action:` on a field
 
 ```erb
@@ -141,6 +164,16 @@ For a `WidgetsController`:
   themselves — `render layout: 'panel'` is fine. The values are assigned just
   before it renders; an action that redirects still redirects.
 
+When `new` and `edit` build the form's object under another name — a bulk form
+object in `@form`, say, where `@widget` already means one of the records it
+wraps — name it, and `widget_params` still permits it:
+
+```ruby
+class WidgetsController < ApplicationController
+  self.turbo_form_resource_name = :form
+end
+```
+
 ### Switching an STI subclass
 
 When the submitted values include the inheritance column, the object is switched
@@ -217,8 +250,9 @@ it doesn't care what the trigger changed.
 
 It handles the common case well and gets out of the way otherwise.
 
-- **No debouncing, request cancellation or loading state** beyond `aria-busy`.
-  Write the action by hand when you need those — that path is still open.
+- **No request cancellation or loading state** beyond `aria-busy`. An overtaken
+  request still runs on the server; its response is just not rendered. Write
+  the action by hand when you need more — 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

data/app/assets/javascripts/turbo_form.js

@@ -33,21 +33,34 @@ 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() } })
 
-      await this.target.render(response)
+      if (!this.superseded) await this.target.render(response)
     } finally {
       this.requestFinished()
     }
   }
 
   requestStarted() {
+    latestRefreshes(this.formElement).set(this.location.href, this)
     markAsBusy(this.formElement, ...this.target.elements)
     Turbo.navigator.formSubmissionStarted(this)
   }
 
   requestFinished() {
-    clearBusyState(this.formElement, ...this.target.elements)
+    if (!this.superseded) clearBusyState(this.formElement, ...this.target.elements)
     Turbo.navigator.formSubmissionFinished(this)
   }
+
+  // Responses can arrive out of order. Only the last one sent to a URL is
+  // rendered, so the page ends up answering the form as it was last sent.
+  get superseded() {
+    return latestRefreshes(this.formElement).get(this.location.href) != this
+  }
+}
+
+const refreshes = new WeakMap()
+
+function latestRefreshes(form) {
+  return refreshes.get(form) ?? refreshes.set(form, new Map).get(form)
 }
 
 class PageTarget {
@@ -146,10 +159,24 @@ class TriggerObserver {
     const trigger = target.closest?.(triggerSelector)
     const form = trigger?.form
 
-    if (form && (trigger.dataset.turboFormAction || form.dataset.turboFormUrl) && eventFor(trigger) == type) this.delegate.triggerFired(form, trigger)
+    if (form && (trigger.dataset.turboFormAction || form.dataset.turboFormUrl) && eventFor(trigger) == type) debounce(trigger, type, () => this.delegate.triggerFired(form, trigger))
   }
 }
 
+const timers = new WeakMap()
+
+// An input event, fired on every keystroke, waits for a 300ms pause before
+// sending the form as it stands by then. data-turbo-form-debounce names a wait
+// of its own for any event, or 0 for none. A trigger gone from the page by then,
+// as when the user has moved on, sends nothing.
+function debounce(trigger, type, fire) {
+  const wait = Number(trigger.dataset.turboFormDebounce ?? (type == "input" ? 300 : 0))
+  if (!wait) return fire()
+
+  clearTimeout(timers.get(trigger))
+  timers.set(trigger, setTimeout(() => trigger.isConnected && fire(), wait))
+}
+
 // A trigger with no event named fires on its element's natural one.
 function eventFor(trigger) {
   const named = trigger.dataset.turboFormTrigger
@@ -183,4 +210,13 @@ function countVisit() {
   root.turboFormVisits = Number(root.turboFormVisits || 0) + 1
 }
 
+// A response answers the form as it was sent, which may be a keystroke or more
+// behind the field being typed into. That field keeps what it has.
+function keepFocusedValue(event) {
+  const { target, detail } = event
+
+  if (target == document.activeElement && target.form?.querySelector(triggerSelector) && detail.attributeName == "value") event.preventDefault()
+}
+
 new TriggerObserver({ triggerFired: refresh }, document).start()
+addEventListener("turbo:before-morph-attribute", keepFocusedValue)

data/lib/turbo_form/controller.rb

@@ -5,12 +5,17 @@ module TurboForm
   # implicitly, or with its own `render layout: 'panel'`.
   #
   # Leans on the scaffold's conventions: the action builds `@<resource>` and
-  # `<resource>_params` permits the form.
+  # `<resource>_params` permits the form. A controller whose form object goes by
+  # another name sets `self.turbo_form_resource_name = :form`.
   module Controller
     extend ActiveSupport::Concern
 
     included do
       helper_method :turbo_form_render?
+
+      # The instance variable `new` and `edit` build the form's object in, when
+      # it isn't the controller's namesake.
+      class_attribute :turbo_form_resource_name, instance_accessor: false
     end
 
     # Public, as Rails' own is. ActionController::Base's public methods are never
@@ -31,12 +36,12 @@ module TurboForm
 
     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)
+      instance_variable_set(turbo_form_ivar, resource)
     end
 
-    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
+    def turbo_form_resource = instance_variable_get(turbo_form_ivar)
+    def turbo_form_resource_params = send(:"#{controller_name.singularize}_params")
+    def turbo_form_ivar = :"@#{self.class.turbo_form_resource_name || controller_name.singularize}"
 
     # Active Record saves `has_many` writers and `*_ids=` on assignment, and
     # this request exists only to render.

data/lib/turbo_form/form_builder.rb

@@ -4,13 +4,14 @@ 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
+  #   f.text_field :name, dynamic_trigger: true, dynamic_debounce: 500   # once typing pauses for 500ms
   #
   # `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
+    DYNAMIC_OPTIONS = %i[dynamic_trigger dynamic_action dynamic_debounce].freeze
 
     def select(method, choices = nil, options = {}, html_options = {}, &block)
       super(method, choices, *hoist_trigger(options, html_options), &block)
@@ -85,17 +86,20 @@ module TurboForm
     def self.absorb_trigger(attributes, template)
       return attributes unless attributes.keys.intersect?(DYNAMIC_OPTIONS)
 
-      trigger, action = attributes.values_at(*DYNAMIC_OPTIONS)
+      trigger, action, debounce = 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), turbo_form_action: (template.url_for(action) if action) })
+      attributes.merge(data: { **attributes[:data].to_h, turbo_form_trigger: trigger_event(trigger), turbo_form_action: (template.url_for(action) if action), turbo_form_debounce: debounce_wait(debounce) })
     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 self.trigger_event(trigger) = trigger == true ? '' : trigger.to_s
+
+    # The script debounces input events on its own; `false` turns that off.
+    def self.debounce_wait(debounce) = debounce == false ? 0 : debounce
   end
 end

data/lib/turbo_form/version.rb

@@ -1,3 +1,3 @@
 module TurboForm
-  VERSION = '0.9.1'
+  VERSION = '0.11.0'
 end

metadata

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