phlex-reactive 0.16.12 → 0.16.13

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

@@ -854,8 +854,18 @@ function refusedHeader(response) {
 // (streamOwnReply wraps its render, innermost); a reply none of whose streams
 // rendered releases now. An error reply (keep true) never marks either, but
 // releases nothing: the server refused those values rather than answering them.
-function renderOwnReply(root, html, keep = null) {
-  const own = { root, streams: 0, keep }
+//
+// Returns a promise that settles once the reply is drawn (issue #464), so the
+// dispatch lane leaves the activity counter after the morph, not a repaint
+// before it. Every listener has had its say by the time renderStreamMessage
+// returns (dispatch is synchronous), so a stream whose event was not cancelled
+// is one Turbo will render: the promise waits for each such render to finish
+// (the innermost wrapper below — after an exit effect, after the opt-in
+// client's hold). With none left to wait for — no stream, or every render
+// prevented — it settles after one repaint. Never later than `cap` ms: a render
+// chain that never finishes must not wedge the request queue.
+function renderOwnReply(root, html, keep = null, cap = 30000) {
+  const own = { root, streams: 0, keep, events: [] }
   const previous = replyRoot
   replyRoot = own
   try {
@@ -864,6 +874,21 @@ function renderOwnReply(root, html, keep = null) {
     replyRoot = previous
   }
   if (own.streams === 0) releaseHeld(root, keep)
+  const renders = own.events.filter((entry) => !entry.event.defaultPrevented).map((entry) => entry.done)
+  // Resolves with the first render's error, if one threw (Turbo logs it).
+  const drawn = renders.length > 0 ? Promise.all(renders).then((errors) => errors.find(Boolean)) : nextRepaint()
+  let timer
+  const bound = new Promise((resolve) => (timer = setTimeout(resolve, cap)))
+  return Promise.race([drawn, bound]).finally(() => clearTimeout(timer))
+}
+
+// Turbo's own nextRepaint: a frame, or a task in a hidden tab (where frames
+// stop) and wherever there is no requestAnimationFrame.
+function nextRepaint() {
+  return new Promise((resolve) => {
+    if (document.visibilityState === "hidden" || typeof requestAnimationFrame !== "function") setTimeout(resolve, 0)
+    else requestAnimationFrame(() => resolve())
+  })
 }
 
 function streamOwnReply(event) {
@@ -872,15 +897,22 @@ function streamOwnReply(event) {
   const render = detail?.render
   if (!own || typeof render !== "function") return
   own.streams++
+  let finished
+  own.events.push({ event, done: new Promise((resolve) => (finished = resolve)) })
   detail.render = async (el) => {
     replying.set(own.root, (replying.get(own.root) || 0) + 1)
+    let failure
     try {
       return await render(el)
+    } catch (error) {
+      failure = error
+      throw error
     } finally {
       const left = replying.get(own.root) - 1
       if (left) replying.set(own.root, left)
       else replying.delete(own.root)
       releaseHeld(own.root, own.keep)
+      finished(failure)
     }
   }
 }
@@ -988,9 +1020,20 @@ export function registerReactiveDev() {
 // is fully applied by the time the call returns — there is no async window to await
 // (the "value settles a beat after a morph/seed" case the issue describes is
 // covered by the System test helpers' re-resolve-by-id polling, not this counter).
+//
+// Each busy window (busy edge to idle edge) also collects the failures raised
+// inside it (issue #464): a dispatch that failed (every reactive:error kind,
+// apply included), a feature that could not load, a deferred render that
+// failed. reactive:idle's detail carries them as `errors`, and <html> carries
+// data-reactive-errors (the same list, as JSON) from that idle edge until the
+// next busy edge — so a system test can tell a failed round trip from one that
+// rendered. A failure raised while nothing is in flight belongs to no window
+// and is not kept.
 export const ACTIVE_ATTR = "data-reactive-active"
+export const ERRORS_ATTR = "data-reactive-errors"
 
 let activityCount = 0
+let activityErrors = []
 
 // Increment the global in-flight count; on the 0 -> 1 edge, mark <html> and fire
 // reactive:busy. Fully defensive — a non-browser/test document with no
@@ -998,7 +1041,17 @@ let activityCount = 0
 // side effects (a global signal must never throw during bootstrap or a round trip).
 export function enterReactiveActivity() {
   activityCount++
-  if (activityCount === 1) syncReactiveActivity("reactive:busy")
+  if (activityCount === 1) {
+    activityErrors = []
+    syncReactiveActivity("reactive:busy")
+  }
+}
+
+// Note a failure in the open busy window: { action, kind, status, root }, each
+// null when it does not apply. Called BEFORE the failing operation exits.
+export function recordReactiveError({ action = null, kind, status = null, root = null }) {
+  if (activityCount === 0) return
+  activityErrors.push({ action: action ?? null, kind, status: status ?? null, root: root || null })
 }
 
 // Decrement the global in-flight count, clamped at 0 so an unbalanced exit can
@@ -1020,8 +1073,10 @@ export function reactiveActivityCount() {
 // since the module is imported once per bun run.
 export function resetReactiveActivity() {
   activityCount = 0
+  activityErrors = []
   const root = typeof document !== "undefined" ? document.documentElement : null
   root?.removeAttribute?.(ACTIVE_ATTR)
+  root?.removeAttribute?.(ERRORS_ATTR)
 }
 
 // Write the <html> marker from the current count and fire the edge event on
@@ -1031,11 +1086,15 @@ export function resetReactiveActivity() {
 function syncReactiveActivity(eventName) {
   if (typeof document === "undefined") return
   const root = document.documentElement
+  const idle = eventName === "reactive:idle"
   if (typeof root?.toggleAttribute === "function") {
     root.toggleAttribute(ACTIVE_ATTR, activityCount > 0)
+    if (idle && activityErrors.length > 0) root.setAttribute(ERRORS_ATTR, JSON.stringify(activityErrors))
+    else root.removeAttribute(ERRORS_ATTR)
   }
   if (typeof document.dispatchEvent === "function" && typeof CustomEvent === "function") {
-    document.dispatchEvent(new CustomEvent(eventName, { detail: { count: activityCount } }))
+    const detail = idle ? { count: activityCount, errors: activityErrors.slice() } : { count: activityCount }
+    document.dispatchEvent(new CustomEvent(eventName, { detail }))
   }
 }
 
@@ -2568,8 +2627,14 @@ export function __loadReactiveFeatureForTest(name) {
 // modules the default bundle handed over still loaded — or, `cold`, with none
 // loaded at all: the state of a page that imported phlex/reactive/core.
 export function __resetReactiveFeaturesForTest(cold) {
-  // (The default entry has no table to reset: its features are static.)
-  if (!__SPLIT__) return
+  // The default entry has no table to reset: its features are static. A second
+  // copy of the runtime installs its own counters into them, though, so put
+  // this instance's back.
+  if (!__SPLIT__) {
+    persistFeature.install(FEATURE_SHARED)
+    deferFeature.install(FEATURE_SHARED)
+    return
+  }
   FEATURES.clear()
   for (const [name, entry] of PRODUCTION_FEATURES) FEATURES.set(name, entry)
   // (Only the opt-in entry registers any; with the default entry alone the
@@ -2596,6 +2661,7 @@ function forgetWaiting(root, name, pending) {
 const FEATURE_SHARED = {
   enter: enterReactiveActivity,
   exit: exitReactiveActivity,
+  fail: recordReactiveError,
   count: countReactiveRequest,
   // The editable collector and server text (issue #351), for the draft.
   text: editableValue,
@@ -3219,6 +3285,7 @@ export default class extends Controller {
   #featureFailed(name, phase, error) {
     logFeatureFailure(name, phase, error)
     this.#markError("feature")
+    recordReactiveError({ kind: "feature", root: this.element.id })
     // A lazy shell whose module will never come (a failed import stays failed
     // until the page is reloaded) must not go on shimmering as if it loaded.
     if (phase === "load" && this.element.getAttribute?.("data-reactive-defer-pending")) {
@@ -4145,6 +4212,7 @@ export default class extends Controller {
       }
       return this.#enqueue(action, rawParams)
     }
+    recordReactiveError({ action, kind: extra.kind, status: extra.status, root: this.element.id })
     this.#emit("reactive:error", { action, params: sentParams, ...extra, retry })
   }
 
@@ -4390,7 +4458,9 @@ export default class extends Controller {
             if (__SPLIT__) this.#devtools((devtools) => devtools.recordBody(debug, errorBody, fresh))
             else devtoolsFeature.recordBody(debug, errorBody, fresh)
           }
-          renderOwnReply(this.element, errorBody, true)
+          const drawn = renderOwnReply(this.element, errorBody, true, this.#timeoutMs())
+          settle?.handoff?.()
+          await drawn
         }
         this.#markError("http")
         this.#emitError(action, params, allParams, { kind: "http", status: response.status, body: errorBody })
@@ -4424,7 +4494,7 @@ export default class extends Controller {
       // focused input + caret on unchanged nodes — see issue #28. As the root's
       // own reply, it clears what the root held (issue #370), but what it
       // refused (issue #413).
-      renderOwnReply(this.element, html, refusedHeader(response))
+      const drawn = renderOwnReply(this.element, html, refusedHeader(response), this.#timeoutMs())
       // Debug-only (issue #181): the morph may apply a microtask later, so check
       // the resurrected-hide case AFTER it lands. Off the debug path, resurrect is
       // null — zero cost.
@@ -4437,8 +4507,24 @@ export default class extends Controller {
       // complete a tick later. Apps needing post-morph timing listen to Turbo's
       // own events; this one is for "the action round trip succeeded".
       this.#emit("reactive:applied", { action, params: allParams, html })
+      // The round trip ends once the reply is drawn (issue #464): the finally's
+      // settle (and with it the activity counter's idle edge) runs after the
+      // morph, and the next queued action starts after it too. The busy state
+      // reverts first, still a repaint before the streams render.
+      settle?.handoff?.()
+      // A stream that threw while Turbo rendered it is a client-side apply
+      // failure. Recorded here, not in the catch below: the rest of the reply
+      // is already drawn, so nothing reverts (the optimistic inverse would undo
+      // over the server's state) and the reply still counts as applied.
+      const failure = await drawn
+      if (failure) {
+        this.#markError("apply")
+        recordReactiveError({ action, kind: "apply", root: this.element.id })
+        this.#emit("reactive:error", { action, params: allParams, kind: "apply" })
+      }
       // What core.proceed resolves with: a feature can tell a reply that
-      // applied from a failure (every other exit returns nothing).
+      // applied from a failure (every other exit returns nothing). A reply
+      // with a stream that threw still applied the rest.
       return html
     } catch (error) {
       // The server already processed this action successfully (we're past the
@@ -4449,6 +4535,8 @@ export default class extends Controller {
       // action the server already completed.
       console.error("[phlex-reactive] action error", error)
       this.#revertOptimistic(pending.inverse)
+      this.#markError("apply")
+      recordReactiveError({ action, kind: "apply", root: this.element.id })
       this.#emit("reactive:error", { action, params: allParams, kind: "apply" })
     } finally {
       // Settle the loading state (issue #99): decrement the pending counter,
@@ -5019,15 +5107,28 @@ export default class extends Controller {
     // #perform runs in its finally on EVERY exit path (success or any failure).
     enterReactiveActivity()
 
+    // Two steps (issue #464). `handoff` reverts this enqueue's busy state when
+    // the reply is handed to Turbo, a repaint before it renders, so an in-place
+    // morph's server state (a trigger it renders disabled) wins over the undo.
+    // The settle itself leaves the activity count only once the reply is drawn,
+    // running the hand-off first if no reply got that far.
+    let unbusied = false
     let settled = false
-    return () => {
+    const handoff = () => {
+      if (unbusied) return
+      unbusied = true
+      this.#unmarkBusy(action, trigger)
+      // Busy reverts regardless of outcome, guarded per element.
+      for (const op of pending.undo) op()
+    }
+    const settle = () => {
       if (settled) return // one settle per enqueue, even if called twice
       settled = true
-      this.#unmarkBusy(action, trigger)
+      handoff()
       exitReactiveActivity()
-      // Busy reverts on SETTLE regardless of outcome, guarded per element.
-      for (const op of pending.undo) op()
     }
+    settle.handoff = handoff
+    return settle
   }
 
   // Layer 1 — the always-on busy markers. Trigger + root carry the action token;

data/lib/phlex/reactive/component/helpers.rb

@@ -1139,20 +1139,40 @@ module Phlex
         # `from:` values are RAW CSS selectors (the escape-hatch posture of
         # reactive_filter/reactive_tags) — the sources are author-owned markup,
         # not reactive_field bindings — resolved root-scoped (#15 ownership).
+        #
+        # `clear: :reset` (issue #466) puts each source back to its RENDERED
+        # default instead of emptying it, the way a form reset would: a
+        # default-on checkbox stays ticked for the next entry, a text input
+        # returns to its `value`, a select to its `selected` option.
         def reactive_nested_add(association, from: nil, clear: false)
           data = {
             action: "click->reactive#nestedAdd",
             reactive_association_param: nested_identifier!(:reactive_nested_add, :association, association)
           }
+          clear_param = nested_clear_param!(clear)
           unless from.nil?
             data[:reactive_nested_from_param] = nested_from_param!(from)
-            # STRING "true", not boolean: a valueless boolean attr reads "" (falsy)
-            # client-side — the on()/tags precedent.
-            data[:reactive_nested_clear_param] = "true" if clear
+            data[:reactive_nested_clear_param] = clear_param if clear_param
           end
           { type: "button", data: }
         end
 
+        # The clear: wire value: "true" (empty the sources), "reset" (back to
+        # their rendered defaults, issue #466), or nil (leave them). STRINGS,
+        # not booleans: a valueless boolean attr reads "" (falsy) client-side —
+        # the on()/tags precedent. Anything else is a typo: fail at render.
+        def nested_clear_param!(clear)
+          case clear
+          when false, nil then nil
+          when true then "true"
+          when :reset then "reset"
+          else
+            raise ArgumentError,
+              "reactive_nested_add(clear:) takes true (empty the sources), :reset (put them back to " \
+              "their rendered defaults) or false, got #{clear.inspect}"
+          end
+        end
+
         # Validate + compile a fill-then-add `from:` map into its JSON wire
         # (issue #208). Each key is a ROW FIELD name (plain identifier, like the
         # association); each value is a SOURCE CONTROL selector (non-blank). An

data/lib/phlex/reactive/test_helpers/system/reactive_reply_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module TestHelpers
+      module System
+        # Raised by wait_for_reactive when the busy window it waited on ended with
+        # failures (issue #464): the client's <html data-reactive-errors> list.
+        #
+        #   reactive action "increment" failed (http 500) on #flaky-counter
+        #
+        # #errors is that list, each entry { action:, kind:, status:, root: }.
+        class ReactiveReplyError < StandardError
+          attr_reader :errors
+
+          def initialize(errors)
+            @errors = errors
+            super(errors.map { describe(it) }.join("; "))
+          end
+
+          private
+
+          def describe(error)
+            subject = error[:action] ? %(action "#{error[:action]}") : error[:kind].to_s
+            reason = [error[:kind], error[:status]].compact.join(" ")
+            "reactive #{subject} failed (#{reason})#{" on ##{error[:root]}" if error[:root]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/test_helpers/system.rb

@@ -42,6 +42,22 @@ module Phlex
         # gate (dev/test by default).
         REQUESTS_ATTR = "data-reactive-requests"
 
+        # The <html> attribute the client writes when a busy window ends with
+        # failures (issue #464): a JSON list of { action, kind, status, root },
+        # present from that idle edge until the next busy edge. Lockstep with
+        # runtime.js ERRORS_ATTR.
+        ERRORS_ATTR = "data-reactive-errors"
+
+        # The list in the attribute, each entry a Hash with Symbol keys. Anything
+        # but a JSON list (absent, garbled, Playwright's {} for a JS null) reads
+        # as no errors, and so does an entry that is not an object.
+        def self.parse_reactive_errors(raw)
+          parsed = raw.is_a?(::String) ? ::JSON.parse(raw, symbolize_names: true) : []
+          parsed.is_a?(::Array) ? parsed.grep(::Hash) : []
+        rescue ::JSON::ParserError
+          []
+        end
+
         # Parse the attribute value into { action:, defer: } Integers — zeros for
         # an absent or garbled value. Shared by the helpers and
         # ReactiveRequestsMatcher.
@@ -74,7 +90,13 @@ module Phlex
         # (a deferred render behind a real job). Returns nil; call it as a barrier
         # BEFORE asserting a settled value if you are not already using one of the
         # waiting matchers below.
-        def wait_for_reactive(timeout: nil)
+        #
+        # The idle edge comes after the replies are drawn, and it records what
+        # failed in the window that just ended (issue #464). If anything did, this
+        # raises ReactiveReplyError naming each failed action, kind and status, so
+        # a 500 or a timeout fails here rather than one assertion later.
+        # `allow_error: true` only waits, for a test that expects the failure.
+        def wait_for_reactive(timeout: nil, allow_error: false)
           # Scope the check to <html> via the :xpath "/html" so the marker is read
           # on the document element the client writes it to — not a descendant.
           # assert_no_selector WAITS (retries) until the marker clears or the wait
@@ -83,6 +105,13 @@ module Phlex
           # session) so it works regardless of whether the example group mixed in
           # Capybara::DSL.
           page.assert_no_selector(:xpath, "/html[@#{ACTIVE_MARKER}]", **wait_option(timeout))
+          return if allow_error
+
+          errors = System.parse_reactive_errors(
+            page.evaluate_script("document.documentElement.getAttribute(#{ERRORS_ATTR.to_json})")
+          )
+          raise ReactiveReplyError, errors if errors.any?
+
           nil
         end
 
@@ -252,3 +281,4 @@ module Phlex
 end
 
 require "phlex/reactive/test_helpers/system/reactive_requests_matcher"
+require "phlex/reactive/test_helpers/system/reactive_reply_error"

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.16.12"
+    VERSION = "0.16.13"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.16.12
+  version: 0.16.13
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -262,6 +262,7 @@ files:
 - lib/phlex/reactive/test_helpers.rb
 - lib/phlex/reactive/test_helpers/matchers.rb
 - lib/phlex/reactive/test_helpers/system.rb
+- lib/phlex/reactive/test_helpers/system/reactive_reply_error.rb
 - lib/phlex/reactive/test_helpers/system/reactive_requests_matcher.rb
 - lib/phlex/reactive/version.rb
 - lib/tasks/phlex_reactive.rake