phlex-reactive 0.12.4 → 0.12.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 735a21537bb98a3b89ba46f21fe40630ee413191e5509db2fe7895172e6b92b7
-  data.tar.gz: 2110972a68b3ff0c336255afe15674167d9012201ebe80479a5c84fff922e682
+  metadata.gz: ec14089cc43f0bf439305f48b9fca3ee8b0fe2ba83b44b341e22370ad11fc22d
+  data.tar.gz: 101ae52fce38a343185a2699082c79709dadf609d9401f199b9b9c5f181dda9c
 SHA512:
-  metadata.gz: 7f6c98822ac5eabbcfdd39b6bdbbbd50176e6d4d5735b5eb0189321ac26e0b559ccc7f8ec60c9394492e23e53eb7e77b79c89c0298f1c962b2115961f8cbfc48
-  data.tar.gz: 4b7dc6d779d5f250592387b3cb9615b4d9d37a5994c0b03e3b83ad1e740251e9875b06735b79a02e304ba0fe53b659220950c47906d0805d0128e81b84231966
+  metadata.gz: '083b640658e403acc1bfeb311d0c22051cd3a2b275a4f44084dfb9c52755fab481eb63c7458e593eb43741d6b3726b8c8e7dadeb2059bcd9b9818cae64768937'
+  data.tar.gz: 3984b48e58eb838ed9bfb009d50444babd518831eb5d2fc7c0f77dc577060b146729f428e7bf1acead2281dd86547fc86130c43ba245b6a4956acf0d5e39d04f

data/CHANGELOG.md

@@ -8,6 +8,23 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Dev-mode warning when a client op resolves zero targets (#237).** A client
+  op that matches nothing is indistinguishable from a working no-op, and the
+  three documented scoping traps — the nested-root ownership filter, a selector
+  that matches the component's own root (root-scoped resolution never includes
+  the root itself), and the op stream's default target scope — all present
+  exactly that way. Now `verbose_errors` (on by default in dev/test) reaches
+  the client as `data-reactive-verbose="true"` on reactive roots and on
+  server-emitted `reactive:js` streams, and under that gate (or full
+  `debug` mode) the interpreter `console.warn`s once per unique
+  (op, selector, scope) naming the op, the selector, and the scoping root —
+  plus the documented escape (`to: :root` / `global: true`) as a hint when the
+  element exists in the DOM but sits outside the op's scope. Covers `on_client`
+  ops, reducer `$ops`, `reply…js(...)` / `broadcast_js_to` streams (including a
+  stream whose `target` root id has left the DOM), and busy/optimistic hint
+  targets. Production (flag off) renders no attribute and stays byte-identical
+  and silent; resolution behavior itself is unchanged everywhere.
+
 - **`js.paste_into(selector)` — the clipboard-source trigger (#228).** A field
   whose real `<input>` is visually hidden (an OTP cell UI painted by a
   `reactive_compute` reducer) has no mouse-reachable paste path: right-click →
@@ -315,6 +332,53 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`Component::Action` renamed `ActionDefinition` — it shadowed a host kit
+  component named `Action` under dev autoloading (#233).** The mixin sits in
+  every reactive component's ancestry, so its bare `Action` constant satisfied
+  Phlex::Kit's LazyLoader `const_get` check with the wrong class: the kit's
+  real `Action` component never autoloaded and the call fell through to
+  `NoMethodError` — intermittently (any unrelated load of the kit class masks
+  it until the next reload) and only under lazy autoloading, so an
+  eager-loaded test suite stays green. The rename matches its siblings
+  (`ComputeDefinition`, `OnCompleteDefinition`, `CollectionDefinition`) and
+  removes the constant entirely — **deliberately no alias**, since any
+  `Action` constant in the ancestry re-creates the shadowing. Breaking only
+  for code referencing the internal
+  `Phlex::Reactive::Component::Action` Data class directly; the `action :name`
+  DSL and `reactive_actions` registry are unchanged. A regression spec guards
+  the whole component ancestry against `:Action` coming back.
+
+- **Multipart path corrupted/dropped fields with Rails-bracketed names (#231).**
+  `#buildFormData` wrapped every collected field/file name verbatim as
+  `params[<name>]`, so `blog_post[summary]` went out as the Rack-unparseable
+  `params[blog_post[summary]]` — the scalar arrived as `{"]" => value}` (and a
+  writer stringified that hash into the record, with a 200), and a `:file` under
+  a bracketed name (`blog_post[image]`) never reached its schema key (silent
+  drop). It only fired when a file input was populated — the JSON path expands
+  the same names server-side — which is why flat-named forms never caught it.
+  The client now bracket-expands the field **name** into wire segments
+  (`params[blog_post][summary]`, `params[blog_post][image]`, and
+  `params[photos][]` for a `multiple` picker named `photos[]`), mirroring the
+  server's `bracket_path` exactly, so a multipart body and a JSON body coerce
+  identically for the same fields. Flat names are byte-identical to before.
+
+- **Reply-rendered components now generate absolute URLs with the REQUESTING
+  host, not the process default (#232).** Actor replies (`reply.replace`,
+  `reply.streams(...)`, the implicit replace) render through the memoized
+  off-request view context, whose `url_options` were process defaults — so any
+  absolute URL helper (`image_tag` on an Active Storage attachment being the
+  everyday case) rendered the wrong host on a multi-host app: a broken image
+  after every save, healed by the next full page load. The action endpoint now
+  threads the request's protocol/host/port into the reply render (the
+  `ActiveStorage::SetCurrent` move) via a thread-local the memoized context
+  merges per call — the context is never rebuilt, so the render memoization
+  win is untouched (allocations byte-identical, throughput flat within noise).
+  The defer **pull** endpoint gets the same treatment (it is an actor request).
+  **Broadcasts are unchanged by design** — there is no request and subscribers
+  can be on different hosts, so a broadcast fired *inside* an action explicitly
+  clears the actor's url_options around its render; "URLs in broadcast-rendered
+  components must be host-relative" is now documented in the Broadcasting guide.
+
 - **`rake bench` ran the removed `broadcast_replace_to` API and exited 1.**
   `benchmark/micro/broadcast.rb` migrated to the #185 spellings
   (`broadcast_to(*key, replace:)` / `broadcast_to(each:, replace:)`); the

data/README.md

@@ -458,7 +458,10 @@ a populated `<input type="file">`, the client sends the action as multipart
 `FormData` (instead of JSON) — `token` + `act` as fields, scalar params as fields,
 any nested/array params bracket-expanded into `params[key][sub]` /
 `params[key][index]` fields (the same Rails-form shape, so a JSON body and a
-multipart body coerce identically — #39), and the file(s) appended; the endpoint
+multipart body coerce identically — #39), and the file(s) appended. A
+Rails-bracketed field **name** (`blog_post[summary]`, `blog_post[image]`)
+expands the same way — `params[blog_post][summary]`, never the unparseable
+`params[blog_post[summary]]` (#231). The endpoint
 coerces `:file` to the `ActionDispatch::Http::UploadedFile`, passed through
 untouched. A non-file value sent to a `:file` param is dropped (the keyword
 default applies — never a fabricated file). Token threading and the
@@ -822,6 +825,14 @@ field collection); `:root` targets the root element itself; `global: true` on
 an op escapes to the whole document. An op name the client doesn't recognize
 logs a warning and is skipped — the rest of the chain still applies.
 
+In development and test (`verbose_errors`), an op whose selector resolves to
+**zero elements** also warns once per unique (op, selector, scope) — with a
+targeted hint when the element exists but sits outside the op's scope: "use
+`to: :root`" when the selector matches the component's own root (root-scoped
+resolution never includes the root itself), or "use `global: true`" when it
+matches only inside a nested reactive root or elsewhere in the document.
+Production stays silent — a zero-match no-op is legitimate there.
+
 **Attributes, focus, dispatch, and transitions.** Beyond visibility and classes,
 the same chain covers the rest of the client-only vocabulary:
 
@@ -2600,6 +2611,19 @@ helper — a child row rendering a trigger for its container's action) is skippe
 `on_client` triggers are never checked (they aren't declared actions). The
 server's default-deny stays the security boundary — this is a dev-time courtesy.
 
+The flag reaches the **client** too: reactive roots (and server-emitted
+`reactive:js` streams) carry `data-reactive-verbose="true"` when it is on, and
+the client op interpreter uses that gate to `console.warn` when a client op —
+`on_client`, a reducer's `$ops`, `reply…js(...)`, `broadcast_js_to`, or a
+busy/optimistic hint — resolves **zero targets**. The warning names the op, the
+selector, and the scoping root, dedupes per unique case per page, and hints the
+documented escape (`to: :root` / `global: true`) when the element exists but
+was filtered out by root scoping or the nested-root ownership rule — the trap
+where the element is right there in the DOM, just outside the op's scope. A
+`reactive:js` stream whose `target` root id has left the DOM warns the same
+way instead of silently dropping its ops. Production (flag off) renders no
+attribute and stays byte-identical and silent.
+
 See [docs/security.md](https://phlex-reactive.zoolutions.llc/docs/security) for the threat model and a checklist.
 
 ---

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -39,9 +39,17 @@ module Phlex
         # #165 security), so the defer endpoint accepts them ONLY back from this
         # same actor. The defer token is built in response_streams (inside this
         # block via the Defer builder), so the binding must be established here.
-        Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
-          Phlex::Reactive.instrument("action", event) do
-            create_action(event)
+        # Thread the ACTOR's url_options (protocol/host/port) into the reply
+        # render (issue #232): the reply renders through the memoized
+        # off-request view context, whose process-default url_options emit the
+        # wrong host for absolute URL helpers on a multi-host app. Broadcasts
+        # fired inside the action are exempted at their render (see
+        # Streamable.broadcast_component) — subscribers can be on other hosts.
+        Phlex::Reactive.with_url_options(Phlex::Reactive.url_options_for(request)) do
+          Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
+            Phlex::Reactive.instrument("action", event) do
+              create_action(event)
+            end
           end
         end
       end
@@ -62,9 +70,14 @@ module Phlex
         # so a leaked token can't be exchanged here for this actor's render (and
         # its embedded fresh identity token). Unbound requests (no session) are
         # unchanged.
-        Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
-          Phlex::Reactive.instrument("defer", event) do
-            deferred_action(event)
+        # The defer PULL is an actor request too (issue #232) — its render gets
+        # the same request-derived url_options as the action reply. The PUSH
+        # lane (job → SSE) has no request and stays on process defaults.
+        Phlex::Reactive.with_url_options(Phlex::Reactive.url_options_for(request)) do
+          Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
+            Phlex::Reactive.instrument("defer", event) do
+              deferred_action(event)
+            end
           end
         end
       end

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

@@ -103,10 +103,22 @@ export function registerReactiveJs() {
     const list = parseOps(this.getAttribute("data-reactive-ops"))
     if (!list.length) return
     const targetId = this.getAttribute("target")
+    // Issue #237: the server stamps the verbose gate on the stream element
+    // itself (verbose_errors), so document-scoped ops are diagnosable too.
+    const verbose = this.getAttribute("data-reactive-verbose") === "true"
     // With a target: scope to that element (missing → no-op). Without: document.
     const root = targetId ? document.getElementById(targetId) : null
-    if (targetId && !root) return
-    applyOps(list, (args) => streamOpTargets(args, root))
+    if (targetId && !root) {
+      if (verbose && !zeroTargetAlreadyWarned(`missing-root|#${targetId}`)) {
+        console.warn(`[phlex-reactive] reactive:js stream target root #${targetId} is not in the DOM — its ops were dropped`)
+      }
+      return
+    }
+    applyOps(
+      list,
+      (args) => streamOpTargets(args, root),
+      verbose ? (name, args) => diagnoseStreamZeroTargets(name, args, root) : undefined,
+    )
   }
 }
 
@@ -1491,7 +1503,7 @@ function computeOpsList(raw) {
 // chain still applies — client-side default-deny, one bad op never takes down
 // its siblings. Object.hasOwn (not a bare read) so inherited Object members
 // ("constructor") can't masquerade as ops.
-function applyOps(list, resolveTargets) {
+function applyOps(list, resolveTargets, onZeroTargets) {
   for (const entry of list) {
     if (!Array.isArray(entry)) continue
     const [name, args = {}] = entry
@@ -1499,8 +1511,68 @@ function applyOps(list, resolveTargets) {
       console.warn(`[phlex-reactive] unknown client op ${JSON.stringify(name)} — skipped`)
       continue
     }
-    for (const el of resolveTargets(args)) CLIENT_OPS[name](el, args)
+    const targets = resolveTargets(args)
+    if (targets.length === 0 && onZeroTargets) onZeroTargets(name, args)
+    for (const el of targets) CLIENT_OPS[name](el, args)
+  }
+}
+
+// --- zero-target diagnostics (issue #237) -----------------------------------
+// An op resolving ZERO targets is indistinguishable from a working no-op, and
+// the documented scoping traps (nested-root ownership filter, root-self
+// selector, stream default scope) all present exactly that way. Under the
+// verbose gate (data-reactive-verbose, stamped when Phlex::Reactive
+// .verbose_errors is on — dev/test by default — or the debug attr) warn ONCE
+// per unique (label, selector, scope) with a targeted hint when the element
+// EXISTS but sits outside the op's scope. Everything below runs only after a
+// zero-match with the gate on; production (no attr) pays one boolean per empty
+// resolution and never probes the DOM.
+//
+// Dedupe is keyed per document (page lifetime): a WeakMap entry per document
+// means a fresh page — or a fresh unit-harness stub — starts clean, and the
+// per-keystroke reducer ($ops) path can never flood the console.
+const zeroTargetWarnSets = new WeakMap()
+
+function zeroTargetAlreadyWarned(key) {
+  const doc = globalThis.document
+  if (!doc) return true
+  let seen = zeroTargetWarnSets.get(doc)
+  if (!seen) {
+    seen = new Set()
+    zeroTargetWarnSets.set(doc, seen)
+  }
+  if (seen.has(key)) return true
+  seen.add(key)
+  return false
+}
+
+// Guarded probes: unit harnesses stub partial documents/roots, and an exotic
+// selector could throw — a diagnostic must never break the op pipeline.
+function countMatches(node, selector) {
+  try {
+    return node?.querySelectorAll?.(selector)?.length ?? 0
+  } catch {
+    return 0
+  }
+}
+
+function emitZeroTargetWarn(label, to, scope, hint) {
+  if (zeroTargetAlreadyWarned(`${label}|${to}|${scope}`)) return
+  console.warn(`[phlex-reactive] ${label} matched zero targets for selector "${to}" (${scope})${hint}`)
+}
+
+// The stream-path diagnoser (reactive:js). No ownership filter exists here, so
+// the only trap is the target-root scope: the selector matches document-wide
+// but the op was scoped to the stream's target root.
+function diagnoseStreamZeroTargets(name, args, root) {
+  const to = args.to
+  if (typeof to !== "string" || to === "" || to === "@root") return
+  let hint = ""
+  if (root && !args.global) {
+    const n = countMatches(globalThis.document, to)
+    if (n > 0) hint = ` — it matches ${n} element(s) outside the stream's target root; use global: true`
   }
+  emitZeroTargetWarn(`client op "${name}"`, to, root ? `scoped to #${root.id || "?"}` : "document-scoped", hint)
 }
 
 // Resolve a reactive:js op's targets against its `target` root (issue #97).
@@ -2204,7 +2276,11 @@ export default class extends Controller {
     const fire = signature !== null && signature !== this.#computeOpsSignature && eventDriven
     this.#computeOpsSignature = signature
     if (!fire) return
-    applyOps(list, (args) => this.#opTargets(args.to == null ? { ...args, to: "@root" } : args))
+    applyOps(
+      list,
+      (args) => this.#opTargets(args.to == null ? { ...args, to: "@root" } : args),
+      (name, args) => this.#diagnoseZeroTargets(`client op "${name}"`, args),
+    )
   }
 
   // Client-side list navigation (combobox keyboard nav, issue #72). Wired by
@@ -3691,7 +3767,13 @@ export default class extends Controller {
       if (matches === null) return
       const fire = matches && !this.#onCompleteStates[i] && Boolean(event)
       this.#onCompleteStates[i] = matches
-      if (fire) applyOps(binding.ops, (args) => this.#opTargets(args.to == null ? { ...args, to: "@root" } : args))
+      if (fire) {
+        applyOps(
+          binding.ops,
+          (args) => this.#opTargets(args.to == null ? { ...args, to: "@root" } : args),
+          (name, args) => this.#diagnoseZeroTargets(`client op "${name}"`, args),
+        )
+      }
     })
   }
 
@@ -4233,19 +4315,39 @@ export default class extends Controller {
     fd.append("token", token)
     fd.append("act", action)
     for (const [key, value] of Object.entries(params)) {
-      this.#appendField(fd, `params[${key}]`, value)
+      this.#appendField(fd, this.#wireKey(key), value)
     }
     const multiNames = this.#multiFileNames(files)
     for (const { name, file, multiple } of files) {
       // params[name][] when the input is `multiple` (array shape even for one
       // file) OR the name repeats across inputs; otherwise a lone scalar file.
       const asArray = multiple || multiNames.has(name)
-      const key = asArray ? `params[${name}][]` : `params[${name}]`
+      const key = asArray ? `${this.#wireKey(name)}[]` : this.#wireKey(name)
       fd.append(key, file, file.name)
     }
     return fd
   }
 
+  // The multipart wire key for a collected field/file name: params[...] with
+  // the name's OWN brackets expanded into nesting segments (issue #231). The
+  // old verbatim wrap of a Rails-bracketed name — params[blog_post[summary]] —
+  // is unparseable by Rack: a scalar arrived as {"blog_post[summary" => {"]" =>
+  // value}} (data corruption written through `update!` with a 200) and a file
+  // never reached its schema key (silent drop). Expanding blog_post[summary]
+  // into params[blog_post][summary] mirrors the server's bracket_path exactly —
+  // split at the first "[", then each non-empty bracket segment; an empty
+  // trailing segment (tags[]) drops, matching how the JSON path's
+  // expand_bracket_keys coerces the same name — so a multipart body and a JSON
+  // body coerce identically for the same fields (the documented contract).
+  // A flat name stays a single params[name] wrap, byte-identical to before.
+  #wireKey(name) {
+    const raw = String(name)
+    const head = raw.indexOf("[")
+    if (head === -1) return `params[${raw}]`
+    const segments = [raw.slice(0, head), ...(raw.slice(head).match(/[^\[\]]+/g) ?? [])]
+    return `params${segments.map((segment) => `[${segment}]`).join("")}`
+  }
+
   // Append a param leaf to FormData under its bracketed key. FormData carries
   // only strings, so a NON-scalar param (a nested object or an array) is
   // bracket-EXPANDED into params[key][sub] / params[key][index][...] fields —
@@ -4309,7 +4411,41 @@ export default class extends Controller {
   // logic lives in the shared applyOps so runOps and the reactive:js stream
   // action interpret the SAME vocabulary the SAME way (client-side default-deny).
   #applyOps(list) {
-    applyOps(list, (args) => this.#opTargets(args))
+    applyOps(
+      list,
+      (args) => this.#opTargets(args),
+      (name, args) => this.#diagnoseZeroTargets(`client op "${name}"`, args),
+    )
+  }
+
+  // Issue #237: the verbose gate for zero-target diagnostics — the
+  // verbose_errors stamp (ON by default in dev/test) or full debug mode (a
+  // debug user must never see less). Read live off the root like #debugEnabled.
+  #verboseEnabled() {
+    return this.element?.getAttribute?.("data-reactive-verbose") === "true" || this.#debugEnabled()
+  }
+
+  // Issue #237: called when a selector-form target resolved to ZERO elements on
+  // this root. Gated + deduped (module helpers); builds the trap-specific hint:
+  // the root-self selector (root-scoped resolution never includes the root),
+  // the nested-reactive-root ownership filter, or plain out-of-scope. All DOM
+  // probes run only here — after a zero-match with the gate on.
+  #diagnoseZeroTargets(label, args) {
+    if (!this.#verboseEnabled()) return
+    const to = args.to
+    if (typeof to !== "string" || to === "" || to === "@root") return
+    let hint = ""
+    if (!args.global) {
+      if (this.element?.matches?.(to)) {
+        hint = " — the selector matches this component's own root, which root-scoped resolution never includes; use to: :root"
+      } else if (countMatches(this.element, to) > 0) {
+        hint = " — it matches only inside a nested reactive root (excluded by ownership scoping); use global: true"
+      } else {
+        const n = countMatches(globalThis.document, to)
+        if (n > 0) hint = ` — it matches ${n} element(s) outside this scope; use global: true`
+      }
+    }
+    emitZeroTargetWarn(label, to, `scoped to #${this.element?.id || "?"}`, hint)
   }
 
   // Resolve an op's targets: "@root" is this element; a selector resolves
@@ -4462,7 +4598,10 @@ export default class extends Controller {
   // this root's owned matches) or, with no `to:`, the trigger itself.
   #hintTargets(hint, trigger) {
     if (hint.to == null) return trigger ? [trigger] : []
-    return this.#opTargets({ to: hint.to })
+    const targets = this.#opTargets({ to: hint.to })
+    // Issue #237: a hint aimed at nothing is the same silent trap as an op.
+    if (targets.length === 0) this.#diagnoseZeroTargets("busy/optimistic hint", { to: hint.to })
+    return targets
   }
 
   // Swap the trigger's disabled/innerHTML for a pending hint, snapshotting the