hotwire_club-toolbox 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0950bbb3f4ecf3bcf29bffd1b773e3292226a24710d4022412c33d7d5a31ade3'
-  data.tar.gz: 17433199837db374317a62fccf830caade02cf4e8a7a6c94a2d5288952a21433
+  metadata.gz: 3ef4fb1e166b6dfb0c498a89f9dbdec29c95af1228d45d126a080ee4328ca44f
+  data.tar.gz: 67c0d7880e2e4a9749632ebd5a59c84575046cf88589ca79e8ef0919062ce661
 SHA512:
-  metadata.gz: ec93a18015f5ef402f5b163f71bb49d772b84a141bf97d5f1f1d7de95dc945d4ada812b16b46959070709b5bba3308a7b811afab8a66b2f53d8558a8a50a54a7
-  data.tar.gz: a1f4e48daeb95574133cef520d10ff346ac560fddb225fc7a2646a7f08bc280881cd3942208fd699fd04ac341b0c0b93b5351e3f87d8c1b39ab9f85fcdf1db1b
+  metadata.gz: 9ace48512f23f6dd4fff86676542564f50354baa4e41520157bbca198ffedf01647798041ac1f6ed9cdd0b2b42933ae6a3cb20fd774a1153c3add0bd5cb00cfb
+  data.tar.gz: 63c0130410564e5bee90f918521ab146caca70aeb266c5ba0e781a4e4e01290c149d1dc16f0e1ba5ef6029ec30a201ada01dff066418b73b7627f44956bc87bc

data/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 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
+- **Optimistic Form**: the builder methods (`optimistic_template`,
+  `optimistic_hidden_field`) now live in the `OptimisticFormBuilding` mixin, so
+  an app can include them in its own form builder. `optimistic_form_with` /
+  `optimistic_form_for` keep a `builder:` that includes the mixin and raise
+  `ArgumentError` for one that does not, instead of silently replacing it.
+  `OptimisticFormBuilder` is unchanged in behaviour (a plain `FormBuilder` with
+  the mixin). Documented under "Using your own form builder".
+
 ## [0.1.0]
 
 ### Added

data/README.md

@@ -1,34 +1,52 @@
 # HotwireClub::Toolbox
-Short description and motivation.
+
+A Rails engine that bundles loosely-connected, production-ready Hotwire and Rails patterns distilled from [The Hotwire Club](https://hotwire.club) challenge series. It's a growing collection, and each tool is independent: pull in the whole engine, use only the pieces you need. There's no shared runtime coupling between them beyond living in the same gem.
 
 ## Tools
 
-A collection of loosely connected Hotwire/Rails tools and techniques. Each has its own usage guide under [`docs/`](docs/).
+Each tool has its own usage guide under [`docs/`](docs/).
 
 - **[Optimistic Form](docs/optimistic-form.md)** - optimistic UI for Turbo forms: paint the predicted result instantly on submit, reconcile with the server only on failure.
 
-## Usage
-How to use my plugin.
-
 ## Installation
-Add this line to your application's Gemfile:
+
+Add the gem to your application's Gemfile:
 
 ```ruby
 gem "hotwire_club-toolbox"
 ```
 
-And then execute:
+Then run `bundle`.
+
+Each tool ships with its own generator, so you install only what you use. For Optimistic Form:
+
 ```bash
-$ bundle
+bin/rails generate hotwire_club:toolbox:optimistic_form:install
 ```
 
-Or install it yourself as:
-```bash
-$ gem install hotwire_club-toolbox
+## Requirements
+
+- Ruby >= 3.2.0
+- Rails >= 8.1.3
+- turbo-rails ~> 2.0
+
+## Optimistic Form at a glance
+
+You author the optimistic update as a Turbo Stream inside a `<template>`. On submit, a Stimulus controller clones it into the DOM so Turbo paints it instantly, then reconciles against the server only if the request fails. Here's a favorite toggle: the `optimistic_template` predicts the toggled state, and the button shows the current one.
+
+```erb
+<%= optimistic_form_for photo, attribute_name: :favorite, value: !photo.favorite do |form| %>
+  <%= form.optimistic_template dom_id(photo, "favorite-button-icon"), favorite_button_icon(!photo.favorite) %>
+  <%= form.button do %><%= favorite_button_icon(photo.favorite) %><% end %>
+<% end %>
 ```
 
+Full guide → [docs/optimistic-form.md](docs/optimistic-form.md).
+
 ## Contributing
-Contribution directions go here.
+
+Issues and pull requests are welcome. See the [CHANGELOG](CHANGELOG.md) for what's shipped.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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

@@ -1,48 +1,10 @@
 module HotwireClub
   module Toolbox
-    # Form builder that renders the optimistic-UI scaffolding: a hidden
-    # <template> holding the turbo-stream(s) the Stimulus controller paints on
-    # submit, and (optionally) a hidden field carrying the value being toggled.
+    # The default builder for `optimistic_form_with` / `optimistic_form_for`:
+    # Rails' FormBuilder plus the optimistic-UI methods. Apps with a builder of
+    # their own include `OptimisticFormBuilding` in it instead.
     class OptimisticFormBuilder < ActionView::Helpers::FormBuilder
-      # Sentinel used by OptimisticFormHelper's form defaults to distinguish
-      # "no value given" from a real nil/false value.
-      UNSET = Object.new
-
-      # Wraps the optimistic markup in a <template> the Stimulus controller
-      # clones into the DOM on `turbo:submit-start`.
-      #
-      #   form.optimistic_template "cart-count", @count + 1
-      #   form.optimistic_template { turbo_stream.update("cart-count") { ... } }
-      #
-      # Positional form builds a `turbo_stream.update` for you; block form lets
-      # you author the stream(s) yourself and ignores +target+/+template+.
-      def optimistic_template(target = nil, template = nil, &block)
-        content = if block
-          @template.capture(&block)
-        else
-          @template.turbo_stream.turbo_stream_action_tag(:update, target: target, template: template)
-        end
-
-        @template.content_tag("template", data: { optimistic_form_target: "template" }) do
-          content
-        end
-      end
-
-      # Explicit hidden field for the value being submitted. Calling this marks
-      # the field as rendered so the helper skips its automatic injection.
-      #
-      #   form.optimistic_hidden_field :favorite, value: !photo.favorite
-      #
-      # +value:+ is required (a value-less field would be meaningless); pass
-      # +false+ freely, only +nil+ renders an empty value.
-      def optimistic_hidden_field(attribute_name, value:)
-        @optimistic_hidden_field_rendered = true
-        hidden_field(attribute_name, value: value)
-      end
-
-      def optimistic_hidden_field_rendered?
-        !!@optimistic_hidden_field_rendered
-      end
+      include OptimisticFormBuilding
     end
   end
 end

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

@@ -0,0 +1,58 @@
+module HotwireClub
+  module Toolbox
+    # The optimistic-UI builder methods, as a mixin so an app can keep its own
+    # form builder (Web Awesome, Tailwind, a design-system builder) and still
+    # author optimistic templates:
+    #
+    #   class MyFormBuilder < ActionView::Helpers::FormBuilder
+    #     include HotwireClub::Toolbox::OptimisticFormBuilding
+    #   end
+    #
+    #   optimistic_form_with url: cart_path, builder: MyFormBuilder do |form|
+    #     form.optimistic_template "cart-count", @count + 1
+    #   end
+    #
+    # `OptimisticFormBuilder` is this module on a plain `FormBuilder`.
+    module OptimisticFormBuilding
+      # Sentinel used by OptimisticFormHelper's form defaults to distinguish
+      # "no value given" from a real nil/false value.
+      UNSET = Object.new
+
+      # Wraps the optimistic markup in a <template> the Stimulus controller
+      # clones into the DOM on `turbo:submit-start`.
+      #
+      #   form.optimistic_template "cart-count", @count + 1
+      #   form.optimistic_template { turbo_stream.update("cart-count") { ... } }
+      #
+      # Positional form builds a `turbo_stream.update` for you; block form lets
+      # you author the stream(s) yourself and ignores +target+/+template+.
+      def optimistic_template(target = nil, template = nil, &block)
+        content = if block
+          @template.capture(&block)
+        else
+          @template.turbo_stream.turbo_stream_action_tag(:update, target: target, template: template)
+        end
+
+        @template.content_tag("template", data: { optimistic_form_target: "template" }) do
+          content
+        end
+      end
+
+      # Explicit hidden field for the value being submitted. Calling this marks
+      # the field as rendered so the helper skips its automatic injection.
+      #
+      #   form.optimistic_hidden_field :favorite, value: !photo.favorite
+      #
+      # +value:+ is required (a value-less field would be meaningless); pass
+      # +false+ freely, only +nil+ renders an empty value.
+      def optimistic_hidden_field(attribute_name, value:)
+        @optimistic_hidden_field_rendered = true
+        hidden_field(attribute_name, value: value)
+      end
+
+      def optimistic_hidden_field_rendered?
+        !!@optimistic_hidden_field_rendered
+      end
+    end
+  end
+end

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

@@ -10,9 +10,12 @@ module HotwireClub
     #
     # Pass +attribute_name:+/+value:+ to have a hidden field injected
     # automatically, or call +form.optimistic_hidden_field+ yourself to place it.
+    #
+    # A +builder:+ option is honoured when that builder includes
+    # `OptimisticFormBuilding`; without one, `OptimisticFormBuilder` is used.
     module OptimisticFormHelper
-      def optimistic_form_with(attribute_name: nil, value: OptimisticFormBuilder::UNSET, **options, &block)
-        options[:builder] = OptimisticFormBuilder
+      def optimistic_form_with(attribute_name: nil, value: OptimisticFormBuilding::UNSET, **options, &block)
+        options[:builder] = optimistic_form_builder(options[:builder])
         enrich_form_with_optimistic_options(options)
 
         form_with(**options) do |form|
@@ -20,8 +23,8 @@ module HotwireClub
         end
       end
 
-      def optimistic_form_for(record, attribute_name: nil, value: OptimisticFormBuilder::UNSET, **options, &block)
-        options[:builder] = OptimisticFormBuilder
+      def optimistic_form_for(record, attribute_name: nil, value: OptimisticFormBuilding::UNSET, **options, &block)
+        options[:builder] = optimistic_form_builder(options[:builder])
         enrich_form_with_optimistic_options(options)
 
         form_for(record, **options) do |form|
@@ -31,6 +34,16 @@ module HotwireClub
 
       private
 
+      # The app's own builder is kept when it carries the optimistic methods.
+      # One without them fails loudly rather than being swapped out: the caller
+      # asked for that builder and would otherwise silently lose its methods.
+      def optimistic_form_builder(builder)
+        return OptimisticFormBuilder if builder.nil?
+        return builder if builder <= OptimisticFormBuilding
+
+        raise ArgumentError, "#{builder} must include HotwireClub::Toolbox::OptimisticFormBuilding to build an optimistic form"
+      end
+
       # Capture the block first so an explicit `form.optimistic_hidden_field`
       # call inside it wins; only auto-inject when the caller supplied
       # attribute_name/value and didn't render the field themselves.
@@ -47,7 +60,7 @@ module HotwireClub
       def auto_inject_hidden_field?(form, attribute_name, value)
         attribute_name.present? &&
           !value.nil? &&
-          !OptimisticFormBuilder::UNSET.equal?(value) &&
+          !OptimisticFormBuilding::UNSET.equal?(value) &&
           !form.optimistic_hidden_field_rendered?
       end
 
@@ -58,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:
@@ -135,6 +154,26 @@ Instead of the positional `target, template`, pass a block to author the stream(
 <% end %>
 ```
 
+## Using your own form builder
+
+Apps often have a builder of their own (a design-system builder, a Tailwind builder). The optimistic methods are a mixin, so such a builder can carry them instead of being replaced:
+
+```ruby
+class WebAwesomeFormBuilder < ActionView::Helpers::FormBuilder
+  include HotwireClub::Toolbox::OptimisticFormBuilding
+  # ...
+end
+```
+
+```erb
+<%= optimistic_form_with url: cart_path, builder: WebAwesomeFormBuilder do |form| %>
+  <%= form.optimistic_template "cart-items-count", @cart_items_count + 1 %>
+  <%= form.submit_button "Add to cart" %>  <%# a method of your builder %>
+<% end %>
+```
+
+`OptimisticFormBuilder` itself is just `ActionView::Helpers::FormBuilder` with the module included. A `builder:` that lacks the module raises `ArgumentError` at render time, so a missing `include` shows up immediately rather than as a `NoMethodError` on `optimistic_template`.
+
 ## Notes
 
 - **Escaping.** Template content is treated as trusted developer markup, the same as any `turbo_stream.update` body (this is what lets you inject SVG icons). Do not pass unescaped user input; sanitize at the call site if you must.
@@ -147,7 +186,7 @@ Helpers (available in all views):
 - `optimistic_form_with(attribute_name: nil, value: nil, **options, &block)`
 - `optimistic_form_for(record, attribute_name: nil, value: nil, **options, &block)`
 
-Both set `options[:builder]` to `OptimisticFormBuilder`; a `builder:` you pass is overridden (the tool's builder methods depend on it).
+Both default `options[:builder]` to `OptimisticFormBuilder`. A `builder:` you pass is kept when it includes `HotwireClub::Toolbox::OptimisticFormBuilding` (see [Using your own form builder](#using-your-own-form-builder)); one without it raises `ArgumentError` rather than being silently replaced.
 
 Builder methods (yielded `form`):
 

data/lib/hotwire_club/toolbox/version.rb

@@ -1,5 +1,5 @@
 module HotwireClub
   module Toolbox
-    VERSION = "0.1.0"
+    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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Julian Rubisch
 bindir: bin
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -51,6 +51,7 @@ files:
 - README.md
 - Rakefile
 - app/helpers/hotwire_club/toolbox/optimistic_form_builder.rb
+- app/helpers/hotwire_club/toolbox/optimistic_form_building.rb
 - app/helpers/hotwire_club/toolbox/optimistic_form_helper.rb
 - app/javascript/hotwire_club/toolbox/helpers/timing_helpers.js
 - app/javascript/hotwire_club/toolbox/optimistic_form_controller.js