phlex-reactive 0.4.4 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68b6f765fc61e5be0b5c338effc94c2c4b283aa64d54f916e44767b4aecf62b9
-  data.tar.gz: e8c2e1c676b6d40d2d89e6acada741c2712746fd9e1bd5b9f54770c730a679b9
+  metadata.gz: 57f49d14a96bb92d0e65f8b6dc8331390538331630858145ed6a42ad80cc4ba5
+  data.tar.gz: 5709021682d0741191df8000fd1b90c10927d1e9bb0f59a8e459728e39a39bc6
 SHA512:
-  metadata.gz: 23c24dcacc6defa4d9479c82aa4cd01778e7a7e02cbe2893ef18539becab491de69195d7da50a5876001633e8f3bfe73a582298a7b4161f2d3f4d5c882caef76
-  data.tar.gz: a2373220f92ad0a9b84ef2ab555b0d6453e889792a334cb89a46d221acd4d6bce64864aa0b7b32e493461613d7fce076f46eb1fe3565a6eb91a7b19b47f01b36
+  metadata.gz: d69d38d3f339502c69caad92d5730c43f2b995d6e12202823ac62da69e02967e14eaa46dfb57536f74c11f5bd8181c1ef8bc9b4cc12067d2f7eb072b4d996cc2
+  data.tar.gz: 30e84a8827a9cfdd515d7a2f9daec8c70b76ea5faffd6bf302f406b6aafc00daddfbf2ba0f4a1e070421e44e34ad3525fe09ecd692b5a009bcd4b0473f1eb087

data/CHANGELOG.md

@@ -8,6 +8,22 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Overridable / async confirm resolver — reuse your themed dialog (#55).**
+  Follow-up to #52. The `confirm:` gate was hardcoded to the synchronous,
+  browser-native `window.confirm`, so a reactive trigger was the one interaction
+  a Hotwire app couldn't theme — every confirmable reactive action showed the
+  unstyled native chrome instead of the app's `Turbo.config.forms.confirm`
+  dialog. The client now resolves the confirmation through an overridable hook
+  (`confirmResolver`, set via `setConfirmResolver` from `phlex/reactive/confirm`),
+  defaulting to `window.confirm`. An app reuses its styled dialog in one line:
+  `setConfirmResolver((m) => window.Turbo.config.forms.confirm(m))`. The resolver
+  may be **async** — `dispatch` `preventDefault`s up front (preserving the #11
+  submit-trigger guarantee), then `await`s the resolver and enqueues only on a
+  truthy result; a falsy resolve or a rejection cancels the action and never
+  leaks an unhandled rejection. Unset, behavior is byte-for-byte identical to
+  0.4.5 (sync native confirm, no dependency); the `confirm:` markup/`on(...)` API
+  is unchanged. README documents the one-line opt-in.
+
 - **`reactive_root` helper — the whole reactive root in one spread (#48).**
   `reactive_attrs` doesn't emit `id:`, so an app could put `id:` on a *child*
   element and leave the controller root's `id` empty — which silently re-opened

data/README.md

@@ -311,6 +311,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_attrs` | Marks an element reactive + carries the signed token (no `id`). Spread alongside `id:` on the **same** element: `div(id:, **reactive_attrs)`. Prefer `reactive_root`, which can't split them. |
 | `on(:action, event: "click", **params)` | Spread onto a trigger element. Adds `type=button` for clicks. |
 | `on(:action, event: "input", debounce: 300)` | Coalesce rapid events into one round trip after a quiet period (live-as-you-type). |
+| `on(:action, confirm: "Sure?")` | Gate a destructive trigger behind a confirmation. Defaults to `window.confirm`; override the dialog with [`setConfirmResolver`](#custom-confirmation-dialogs-setconfirmresolver). |
 | `reactive_input(:param, **attrs)` / `reactive_select(:param, **attrs)` | Render a control already bound to an action param (no magic `name:`). |
 | `reactive_field(:param, **attrs)` | The attribute hash behind the above — spread onto any control. |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
@@ -478,6 +479,37 @@ end
 `nested_attributes(:address, address)` returns the id-merged hash without
 updating, if you need to combine it with other attributes.
 
+### Custom confirmation dialogs (`setConfirmResolver`)
+
+`on(:action, confirm: "Really delete this?")` gates a destructive trigger behind
+a confirmation. Because the reactive controller preempts the event (its own
+`preventDefault` + POST), Hotwire's `data-turbo-confirm` — which routes through
+`Turbo.config.forms.confirm` — never runs for a reactive trigger. So by default
+the gate uses the browser-native `window.confirm` (synchronous, no dependency,
+screen-reader friendly).
+
+If your app already themes confirmations (the common Hotwire setup —
+`Turbo.config.forms.confirm = (message) => Promise<boolean>`, backed by a styled
+modal), reuse that exact dialog for reactive triggers with one line at boot:
+
+```js
+import { setConfirmResolver } from "phlex/reactive/confirm"
+
+// Reuse the same themed dialog the rest of the app already uses.
+setConfirmResolver((message) => window.Turbo.config.forms.confirm(message))
+```
+
+The resolver receives the `confirm:` message and returns `true`/`false` (or a
+`Promise` of one). It may be **async** — the controller `await`s it, then runs
+the action only on a truthy result; a falsy result (or a rejected promise — e.g.
+the user dismissed the dialog) cancels the action, exactly like declining the
+native prompt. The native default is always prevented up front, so a `submit`
+trigger never navigates while the dialog is open.
+
+Unset, behavior is identical to the native `window.confirm` — the `confirm:`
+markup and `on(...)` API are unchanged; only the client's resolution strategy
+gains a seam.
+
 ### `reply` — controlling the action's reply
 
 By default an action re-renders its component in place. To do more, **return**

data/app/javascript/phlex/reactive/confirm.js

@@ -0,0 +1,34 @@
+// The overridable confirmation resolver behind `on(:action, confirm: "…")`
+// (issue #55, follow-up to #52).
+//
+// The reactive controller preempts the click event (its own preventDefault +
+// POST), so Hotwire's `data-turbo-confirm` — which routes through
+// `Turbo.config.forms.confirm` — never runs for a reactive trigger. That made
+// the reactive path the ONE interaction a Hotwire app couldn't theme: every
+// confirmable reactive action showed the unstyled native window.confirm chrome.
+//
+// This module is the seam. `dispatch` resolves the confirm message through
+// `confirmResolver`, which defaults to a Promise-wrapped window.confirm (so the
+// 0.4.5 behavior is byte-for-byte unchanged when nothing is configured: sync,
+// no dependency, screen-reader friendly). An app reuses its themed dialog with
+// one line at boot:
+//
+//   import { setConfirmResolver } from "phlex/reactive/confirm"
+//   setConfirmResolver((message) => window.Turbo.config.forms.confirm(message))
+//
+// The resolver may be sync or async — the controller awaits it via
+// Promise.resolve, so a bare boolean and a Promise<boolean> both work. It must
+// resolve truthy to proceed; a falsy resolve (or a rejection) cancels the
+// action — exactly like declining the native prompt.
+
+// The default: wrap the synchronous native confirm in a Promise so the call
+// site can always `await` it. Read window lazily (per call), not at module load
+// — under SSR / test the global may not exist yet when this module is imported.
+export let confirmResolver = (message) =>
+  Promise.resolve(typeof window !== "undefined" ? window.confirm(message) : true)
+
+// Override the resolver. Pass a function `(message) => boolean | Promise<boolean>`.
+// Truthy resolves the action through; falsy (or a rejected Promise) cancels it.
+export function setConfirmResolver(fn) {
+  confirmResolver = fn
+}

data/app/javascript/phlex/reactive/reactive_controller.js

@@ -1,4 +1,5 @@
 import { Controller } from "@hotwired/stimulus"
+import { confirmResolver } from "./confirm.js"
 
 // The ONE generic controller behind every reactive Phlex component. It
 // replaces the per-feature Stimulus controllers you'd otherwise hand-write
@@ -168,27 +169,56 @@ export default class extends Controller {
   // a per-controller promise makes each dispatch wait for the previous one, so
   // it always uses the freshest token.
   dispatch(event) {
-    const { action, params, debounce } = event.params
+    const { action, params, debounce, confirm } = event.params
     if (!action) return
 
     // Stop native behavior (button submit / FORM NAVIGATION) HERE, synchronously
-    // within the event dispatch. preventDefault() only works while the event is
-    // still being handled — deferring it into the request-queue microtask (below)
-    // is too late: a `submit` trigger would natively POST the form and navigate
-    // before the reactive round trip runs (issue #11). For a `click` trigger
-    // there's no default to miss, so this was previously invisible. This holds
+    // within the event dispatch — BEFORE the (possibly async) confirm gate below.
+    // preventDefault() only works while the event is still being handled; once we
+    // await the confirm resolver it's too late, and a `submit` trigger would
+    // natively POST the form and navigate before the reactive round trip runs
+    // (issue #11). For a `click` trigger there's no default to miss. This holds
     // for debounced triggers too — the round trip is deferred, but the native
-    // default must still be prevented now.
+    // default must still be prevented now. (Moved ahead of the confirm branch in
+    // issue #55: an async resolver means we can't preventDefault after awaiting.)
     event.preventDefault()
 
+    // Capture the trigger element now; #proceed runs in a later microtask (after
+    // the confirm resolver settles), by which point event.target may be reset.
+    const target = event.target
+
+    // No confirm message → proceed straight away (unchanged fast path).
+    if (!confirm) return this.#proceed(target, action, params, debounce)
+
+    // Confirmation gate (issue #52, made overridable + async in #55). A reactive
+    // trigger can't use Hotwire's data-turbo-confirm — this controller preempts
+    // the event — so a `confirm:` message routes through confirmResolver (default
+    // window.confirm; an app can override it to reuse Turbo.config.forms.confirm).
+    // The resolver may be sync or async; call it INSIDE the chain (via the leading
+    // .then) so even a SYNCHRONOUS override throw rejects this promise instead of
+    // escaping dispatch — a throwing dialog is treated as a cancel, like the user
+    // dismissing it. The .catch is scoped to the resolver step (→ false = cancel),
+    // so a dismissed/erroring dialog never surfaces as an unhandled rejection AND a
+    // genuine bug inside #proceed is NOT silently swallowed. Enqueue ONLY on a
+    // truthy resolution — nothing is enqueued, no timer scheduled, otherwise.
+    Promise.resolve()
+      .then(() => confirmResolver(confirm))
+      .catch(() => false)
+      .then((ok) => {
+        if (ok) this.#proceed(target, action, params, debounce)
+      })
+  }
+
+  // Enqueue the action — debounced if a debounce window is set, else immediately.
+  // Split out of dispatch so both the no-confirm fast path and the post-confirm
+  // microtask share one place (issue #55). `target` is captured up front because
+  // this can run in a later microtask, after event.target has been reset.
+  #proceed(target, action, params, debounce) {
     // Debounced trigger (e.g. on(:update, event: "input", debounce: 300)):
     // coalesce rapid events into ONE round trip after a quiet period, instead of
     // one POST per keystroke (issue #17). A blur flushes a pending dispatch.
     const ms = Number(debounce) || 0
-    if (ms > 0) return this.#debounceDispatch(event.target, ms, action, params)
-
-    // Capture action/params now; the queued work runs in a later microtask, by
-    // which point the event object may have been reset by the browser.
+    if (ms > 0) return this.#debounceDispatch(target, ms, action, params)
     return this.#enqueue(action, params)
   }
 

data/lib/phlex/reactive/component.rb

@@ -304,13 +304,22 @@ module Phlex
       # live-update-as-you-type doesn't POST per keystroke. A blur flushes a
       # pending dispatch so the last edit is never dropped. Omit it for the
       # immediate-dispatch default.
+      #
+      # `confirm:` (a message string) gates the action behind a confirmation
+      # prompt (issue #52). Destructive reactive triggers can't use Hotwire's
+      # `data-turbo-confirm` — the reactive controller calls preventDefault and
+      # enqueues the POST itself, so Turbo's confirm handling never runs. The
+      # client shows window.confirm(message) FIRST and bails before any
+      # enqueue/debounce if the user declines (and prevents the native default so
+      # a `submit` trigger can't navigate on cancel). Omit it for no prompt.
+      #   button(**on(:destroy, confirm: "Really delete this item?")) { "Delete" }
       # The verbatim JSON for an empty explicit-params payload. The common
       # trigger (on(:increment), no params) hits this on EVERY render — skipping
       # params.to_json (which re-serializes {} to the same "{}" each time) avoids
       # a per-render allocation while keeping the wire format byte-identical.
       EMPTY_PARAMS_JSON = "{}"
 
-      def on(action_name, event: "click", debounce: nil, **params)
+      def on(action_name, event: "click", debounce: nil, confirm: nil, **params)
         attrs = {
           data: {
             action: "#{event}->reactive#dispatch",
@@ -319,6 +328,7 @@ module Phlex
           }
         }
         attrs[:data][:reactive_debounce_param] = debounce if debounce
+        attrs[:data][:reactive_confirm_param] = confirm if confirm
         attrs[:type] = "button" if event == "click"
         attrs
       end

data/lib/phlex/reactive/engine.rb

@@ -24,7 +24,10 @@ module Phlex
       initializer "phlex_reactive.assets" do
         if it.config.respond_to?(:assets)
           it.config.assets.paths << root.join("app/javascript").to_s
-          it.config.assets.precompile += %w[phlex/reactive/reactive_controller.js]
+          it.config.assets.precompile += %w[
+            phlex/reactive/reactive_controller.js
+            phlex/reactive/confirm.js
+          ]
         end
       end
 
@@ -38,6 +41,14 @@ module Phlex
             to: "phlex/reactive/reactive_controller.js",
             preload: true
           )
+          # The overridable confirm resolver (issue #55). reactive_controller.js
+          # imports it relatively (./confirm.js), and an app reuses its themed
+          # dialog via `import { setConfirmResolver } from "phlex/reactive/confirm"`.
+          it.importmap.pin(
+            "phlex/reactive/confirm",
+            to: "phlex/reactive/confirm.js",
+            preload: true
+          )
         end
       end
 

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.4.4"
+    VERSION = "0.4.6"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.6
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -117,6 +117,7 @@ files:
 - LICENSE.txt
 - README.md
 - app/controllers/phlex/reactive/actions_controller.rb
+- app/javascript/phlex/reactive/confirm.js
 - app/javascript/phlex/reactive/reactive_controller.js
 - lib/generators/phlex/reactive/component/USAGE
 - lib/generators/phlex/reactive/component/component_generator.rb