turbo_form 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1637d6cbac8d370efc21308cc1ace27f278e2153fde411829fa4031d5980a54
-  data.tar.gz: 0247d756f8f6217149c1bd24e30acca602b0fa9a7af69acc7d07d0228a1a727c
+  metadata.gz: dbeda5baf3151daeee78f081393fcb7ad320a927c7c928b1a1af4940afe02580
+  data.tar.gz: 62f16acb9a560d7b7abb946c02d72c6a021a7e790ae1d8abf984a5627e44a0f0
 SHA512:
-  metadata.gz: b53a713122f8443e248f787953724cc0204aca67ae53b994122838fabaf7c9bf3300c720557f8a7818dba2154495d5f1ec98c289458f5456245c7f8550120349
-  data.tar.gz: fab34492c6b7b1b7f01efea76aa25a157d96c7ccaaed682c9e15f424e3e4512cc37543119caa9dcc381c52208cb891c73ee727d6a1c54c1c435610a0b8e9c8b4
+  metadata.gz: fa3df3560e87aa90ad79e86664c14cfc1a4d44cd28474e43b3bfbc66032fe676531c444d3d3716421628a3590f7b7c32e6eb3f04d77ca324f4bd223630a1b225
+  data.tar.gz: 4de2fedf514e70e5f37f5fa49e74bec3389dfed6626eb848180d90b2fa216963db372ab55bad53f0b6cedddaac9b93d3c29ed80045960ac356226311ae121996

data/README.md

@@ -2,6 +2,8 @@
 
 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 +70,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 +83,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
@@ -217,8 +233,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/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.10.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.10.0
 platform: ruby
 authors:
 - Andy Cohen