hotwire_club-toolbox 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bedf92af7ff8eee2fae5cc33bafda59fc79c68c8c8cb8052a77bc77b43f674b
-  data.tar.gz: b7ca7fe46f611501e4383398e79d8d73845a64e2a7e647c239be685d137c01a6
+  metadata.gz: 3ef4fb1e166b6dfb0c498a89f9dbdec29c95af1228d45d126a080ee4328ca44f
+  data.tar.gz: 67c0d7880e2e4a9749632ebd5a59c84575046cf88589ca79e8ef0919062ce661
 SHA512:
-  metadata.gz: 2e072995e35f86644f3f6521aa144375a3291989c0e96ab67e6e93543bf29ddea3c60bae060fc707d668e2c303a7e3b553660c0584d324e36214bb4e7b92c52c
-  data.tar.gz: cbed3456a119ea18e391b68f62633402f182ac8c7ba4bd8944b409ca24f0ed58460259274477de31af8d38bf54fc3e9f6bb3d6f18557be328dcbaa8127957d84
+  metadata.gz: 9ace48512f23f6dd4fff86676542564f50354baa4e41520157bbca198ffedf01647798041ac1f6ed9cdd0b2b42933ae6a3cb20fd774a1153c3add0bd5cb00cfb
+  data.tar.gz: 63c0130410564e5bee90f918521ab146caca70aeb266c5ba0e781a4e4e01290c149d1dc16f0e1ba5ef6029ec30a201ada01dff066418b73b7627f44956bc87bc

data/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project are documented here.
 
+## [0.2.0]
+
+### Changed
+- **Optimistic Form**: reconciliation moved from the form to the document. The
+  controller follows each submission it saw on `turbo:submit-start` and
+  refreshes on its `turbo:submit-end` when it failed, wherever that event is
+  dispatched. `optimistic_form_with` / `optimistic_form_for` now wire only
+  `turbo:submit-start->optimistic-form#apply`; the
+  `turbo:submit-end->optimistic-form#refresh` action is gone. A form that
+  still carries it (hand-wired, or rendered by a cached fragment) keeps
+  working: `refresh` runs once per submission.
+- **Upgrading**: apps that copied `optimistic_form_controller.js` (jsbundling,
+  vite) must copy the new one before rendering with the 0.2.0 helpers, since
+  the old controller only reconciled through the removed action.
+
+### Fixed
+- **Optimistic Form**: a failed submission is reconciled when the optimistic
+  paint removed the form itself, as a predicted row removal does. Turbo
+  dispatches `turbo:submit-end` on `<html>` once the form has left the page,
+  so the form-bound action never ran and the removed row stayed gone.
+
 ## [0.1.1]
 
 ### Added

data/app/helpers/hotwire_club/toolbox/optimistic_form_helper.rb

@@ -71,7 +71,7 @@ module HotwireClub
         options[:html][:data][:controller] =
           [ options[:html][:data][:controller], "optimistic-form" ].compact.join(" ")
         options[:html][:data][:action] =
-          [ options[:html][:data][:action], "turbo:submit-start->optimistic-form#apply turbo:submit-end->optimistic-form#refresh" ].compact.join(" ")
+          [ options[:html][:data][:action], "turbo:submit-start->optimistic-form#apply" ].compact.join(" ")
       end
     end
   end

data/app/javascript/hotwire_club/toolbox/optimistic_form_controller.js

@@ -2,18 +2,25 @@ import { Controller } from "@hotwired/stimulus";
 import { throttle } from "hotwire_club/toolbox/helpers/timing_helpers";
 
 // Applies optimistic UI on form submit by cloning the form's <template>(s)
-// into the DOM (Turbo then processes the contained turbo-stream). On submit-end
-// it reconciles against the server only when the submission failed.
+// into the DOM (Turbo then processes the contained turbo-stream). Each
+// submission is followed from the document until its submit-end, and the page
+// is refreshed to reconcile against the server only when the submission failed.
 export default class extends Controller {
   static targets = ["template"];
 
   initialize() {
     // Throttle so the paint fires immediately, but a burst of rapid submits on
     // the same form can't stack duplicate clones.
-    this.apply = throttle(this.apply.bind(this), 200);
+    this.paint = throttle(this.paint.bind(this), 200);
+    this.reconciled = new WeakSet();
   }
 
-  apply() {
+  apply(event) {
+    this.follow(event?.detail?.formSubmission);
+    this.paint();
+  }
+
+  paint() {
     if (!this.hasTemplateTarget) return;
 
     this.templateTargets.forEach((template) => {
@@ -21,11 +28,37 @@ export default class extends Controller {
     });
   }
 
+  // Listened for on the document, not the form: a prediction may remove the
+  // form itself (a deleted row), and Turbo then dispatches turbo:submit-end on
+  // <html>, where a listener on the form never hears it.
+  follow(formSubmission) {
+    if (!formSubmission) return;
+
+    // Not `once`: with several submissions in flight, another form's
+    // submit-end may come first, and that one must not consume the listener.
+    const onSubmitEnd = (event) => {
+      if (event.detail.formSubmission !== formSubmission) return;
+
+      document.removeEventListener("turbo:submit-end", onSubmitEnd);
+      this.refresh(event);
+    };
+
+    document.addEventListener("turbo:submit-end", onSubmitEnd);
+  }
+
   refresh(event) {
     // On success the optimistic paint already reflects the new state; only
     // refresh to reconcile when the server rejected the submission.
     if (event.detail?.success) return;
 
+    // Once per submission, so a form that still carries the pre-0.2 submit-end
+    // action does not refresh a second time.
+    const { formSubmission } = event.detail ?? {};
+    if (formSubmission) {
+      if (this.reconciled.has(formSubmission)) return;
+      this.reconciled.add(formSubmission);
+    }
+
     document.body.insertAdjacentHTML(
       "beforeend",
       '<turbo-stream action="refresh"></turbo-stream>',

data/docs/optimistic-form.md

@@ -53,11 +53,30 @@ An add-to-cart button that bumps a counter elsewhere on the page:
 
 ## The reconciliation model
 
-- **On submit-start**, the controller clones the form's `<template>`(s) into the document. Turbo processes the contained stream and paints the optimistic state.
+- **On submit-start**, the controller clones the form's `<template>`(s) into the document. Turbo processes the contained stream and paints the optimistic state. The controller also starts following that submission from the document.
 - **On submit-end**, the controller reconciles **only if the submission failed** (`event.detail.success === false`). On success the optimistic paint already reflects the new state, so nothing happens.
 
+The helpers wire a single action onto the form, `turbo:submit-start->optimistic-form#apply`. Submit-end is not an action on the form: the controller listens for it on the document, matched to the submission it painted, so it is heard even when the form has left the page by then (see below).
+
 This keeps the happy path free of extra requests. A full page refresh only ever runs when the server rejects the change, which is exactly when you want authoritative truth.
 
+### Predictions that remove the form
+
+A prediction may take its own form out of the page: a delete button whose template removes the row it sits in, or one that replaces a card around it.
+
+```erb
+<%= optimistic_form_with url: photo_path(photo), method: :delete do |form| %>
+  <%= form.optimistic_template { turbo_stream.remove(dom_id(photo)) } %>
+  <%= form.button "Remove" %>
+<% end %>
+```
+
+Turbo dispatches `turbo:submit-end` on `<html>` once the form is no longer connected, so a listener on the form would never hear it. Because the controller follows the submission from the document, a rejected removal refreshes the page and brings the row back like any other failure.
+
+### Upgrading from 0.1
+
+Before 0.2.0 the helpers also wired `turbo:submit-end->optimistic-form#refresh` onto the form, which is why a removed form was never reconciled. If your app copied `optimistic_form_controller.js` (jsbundling, vite), copy the 0.2.0 one before upgrading the gem: the old controller only reconciles through that action, which the 0.2.0 helpers no longer render. A form that still carries the action is harmless with the new controller, which refreshes once per submission.
+
 ## Server contract
 
 Because success trusts the optimistic paint and failure triggers a client refresh, your controller must respond accordingly:

data/lib/hotwire_club/toolbox/version.rb

@@ -1,5 +1,5 @@
 module HotwireClub
   module Toolbox
-    VERSION = "0.1.1"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hotwire_club-toolbox
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Julian Rubisch
 bindir: bin
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails