phlex-reactive 0.16.8 → 0.16.10

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

@@ -449,7 +449,9 @@ export function __resetReactiveKeepForTest() {
 // a morph that changes the src lets the browser try again. A morph that keeps
 // the src puts the state back. An error with no src is not an error (a
 // removed or emptied src). One document listener, capture phase (neither
-// event bubbles); nothing per root at connect.
+// event bubbles); nothing per root at connect. An img that finished before it
+// was in the document (before registration, or while Turbo held it imported
+// but not yet inserted, issue #452) is read off the element instead.
 const IMAGE_FALLBACK = "data-reactive-image-fallback"
 const IMAGE_STATE = "data-reactive-image-state"
 // Marks the `hidden` the fallback set, so a reset removes only that one. On
@@ -580,13 +582,36 @@ export function registerReactiveImageFallback() {
         if (wire) setImageState(img, wire, value)
       })
     },
+    // Content Turbo inserts was imported into the document first, a few awaits
+    // earlier (issue #452): an img loads from then on, so one whose request
+    // ended in between fired its event detached, unheard. Read it off the
+    // element once the content is in: the frame, the page, a stream's render.
+    "turbo:frame-render": (event) => scanImageFallbacks(event.target),
+    "turbo:render": () => scanImageFallbacks(document),
+    "turbo:before-stream-render": (event) => {
+      const detail = event.detail
+      const render = detail?.render
+      const stream = detail?.newStream ?? event.target
+      if (typeof render !== "function" || !stream?.querySelector?.("template")?.content?.querySelector?.(`img[${IMAGE_FALLBACK}]`)) return
+      // The whole document: a replace's target is gone by then.
+      detail.render = async (el) => {
+        await render(el)
+        scanImageFallbacks(document)
+      }
+    },
   }
   for (const [name, fn] of Object.entries(imageFallbackListeners)) document.addEventListener(name, fn, true)
-  // An image that finished before this ran (a cached 404) fired its event
-  // unheard: read it off the element once. naturalWidth 0 is also a loaded
-  // SVG with only a viewBox, so decode() decides (it rejects a broken image).
-  for (const img of document.querySelectorAll?.(`img[${IMAGE_FALLBACK}]`) ?? []) {
-    if (!img.complete || !hasImageSrc(img)) continue
+  // An image that finished before this ran (a cached 404) fired its event unheard.
+  scanImageFallbacks(document)
+}
+
+// Read the result of every marked img in `root` that has no state yet and has
+// finished; one still loading fires its own event, connected. naturalWidth 0
+// is also a loaded SVG with only a viewBox, so decode() decides (it rejects a
+// broken image, and fetches nothing).
+function scanImageFallbacks(root) {
+  for (const img of root?.querySelectorAll?.(`img[${IMAGE_FALLBACK}]`) ?? []) {
+    if (img.getAttribute(IMAGE_STATE) != null || !img.complete || !hasImageSrc(img)) continue
     // A decode() that settles after the src changed decoded the OLD one: ignore it.
     const was = `${img.getAttribute("src")} ${img.getAttribute("srcset")}`
     const mark = (value) => `${img.getAttribute("src")} ${img.getAttribute("srcset")}` === was && setImageState(img, imageFallback(img) ?? {}, value)
@@ -1972,13 +1997,15 @@ function bindingsAlreadyRan(event, controller) {
 function applyOps(list, resolveTargets, onZeroTargets) {
   for (const entry of list) {
     if (!Array.isArray(entry)) continue
-    const [name, args = {}] = entry
+    let [name, args = {}] = entry
     if (!Object.hasOwn(CLIENT_OPS, name)) {
       console.warn(`[phlex-reactive] unknown client op ${JSON.stringify(name)} — skipped`)
       continue
     }
     const targets = resolveTargets(args)
     if (targets.length === 0 && onZeroTargets) onZeroTargets(name, args)
+    if (targets.length > 0) args = readArgs(name, args, resolveTargets, onZeroTargets)
+    if (!args) continue
     for (const el of targets) {
       CLIENT_OPS[name](el, args, resolveTargets)
       if (args?.keep === true) keepResult(el, name, args, resolveTargets)
@@ -1986,6 +2013,48 @@ function applyOps(list, resolveTargets, onZeroTargets) {
   }
 }
 
+// --- Reads (issue #442) ----------------------------------------------------
+// set_value, text and set_attr with `from` + `attr` take their value off an
+// element instead of a literal; dispatch's detail_from builds the detail off
+// the trigger. The read runs ONCE per op, before any target is written, with
+// the op's own scoping ("@trigger", "@root", a selector, global:), first
+// match. Returns the args with the value (or detail) in place, or null to skip
+// the op: a source that resolves to nothing (the zero-target diagnostic) or a
+// read attr off the data-*/text rule (warned). copy_media's `from` is an
+// element it copies, not a read, so it never comes here.
+const READ_OPS = new Set(["set_value", "text", "set_attr"])
+
+function readArgs(name, args, resolveTargets, onZeroTargets) {
+  const detail = name === "dispatch"
+  const reads = detail ? args.detail_from : READ_OPS.has(name) && args.from != null && { value: args.attr }
+  if (!reads) return args
+  const from = detail ? "@trigger" : args.from
+  let source
+  // A from that does not parse is a miss like one that matches nothing (the
+  // copy_media precedent): the op is skipped, its siblings still run.
+  try {
+    source = resolveTargets({ ...args, to: from })[0]
+  } catch {}
+  if (!source) return onZeroTargets?.(name, { ...args, to: from }), null
+  const values = detail ? { ...args.detail } : {}
+  for (const [key, attr] of Object.entries(reads)) {
+    const value = readValue(source, attr)
+    if (value == null) return null
+    values[key] = value
+  }
+  return detail ? { ...args, detail: values } : { ...args, ...values }
+}
+
+// What a read may take off an element: a data-* attribute (absent reads "",
+// so it clears) or "@text", its textContent. Anything else warns and is null
+// — the interpret-time side of JS::READABLE_ATTR (two-sided default-deny).
+function readValue(el, attr) {
+  if (attr === "@text") return el.textContent ?? ""
+  if (typeof attr === "string" && /^data-[a-z][a-z0-9-]*$/i.test(attr)) return el.getAttribute(attr) ?? ""
+  console.warn(`[phlex-reactive] refused client read of ${JSON.stringify(attr)} — skipped`)
+  return null
+}
+
 // Resolve a reactive:js op's targets against its `target` root (issue #97).
 // "@root" is the root element itself; a selector resolves WITHIN it; a bare
 // selector with no root (no `target` attr on the stream) resolves document-wide
@@ -1997,6 +2066,9 @@ function applyOps(list, resolveTargets, onZeroTargets) {
 // documents for the controller path).
 function streamOpTargets(args, root) {
   const to = args.to
+  // A server-pushed op has no trigger (issue #442): the server refuses
+  // "@trigger", and a hand-built one resolves to nothing.
+  if (to === "@trigger") return []
   if (root) {
     if (to === "@root") return [root]
     if (typeof to !== "string" || to === "") return []
@@ -3520,6 +3592,9 @@ export default class extends Controller {
       // A detail miss (issue #346) is a complete no-op — checked before the
       // once record is spent, preventDefault and the confirm gate.
       if (!detailMatches(record, event)) continue
+      // So is a within: miss (issue #442); a hit's row is the ops' @trigger.
+      const row = record.within == null ? trigger : this.#delegatedTrigger(record.within, event)
+      if (record.within != null && !row) continue
       // So is a shortcut that is not this platform's twin or fired in an
       // editable target (issue #357).
       if (record.shortcut != null && !shortcutApplies(record.shortcut, event, this.application?.schema?.keyMappings))
@@ -3531,15 +3606,35 @@ export default class extends Controller {
       this.#runBinding(
         record.legacy ? { ...params, ops: record.ops, debounce: undefined, throttle: undefined, prevent: undefined } : record,
         event,
-        trigger,
+        row,
         records.indexOf(record),
+        trigger,
       )
     }
   }
 
+  // Issue #442: a within: record runs for an event from inside an element
+  // matching the selector, strictly under the bound element and owned by this
+  // root (issue #15: a nested root's row is that root's). That element is
+  // returned as the ops' @trigger; anything else is a miss (null). So is a
+  // selector that does not parse (Ruby cannot check CSS), warned under
+  // verbose_errors so the dead binding is never silent in development.
+  #delegatedTrigger(within, event) {
+    const bound = event.currentTarget
+    let row = null
+    try {
+      row = event.target?.closest?.(within)
+    } catch {
+      if (this.#verboseEnabled()) console.warn(`[phlex-reactive] on_client within: ${JSON.stringify(within)} is not a selector — nothing ran`)
+    }
+    return row && row !== bound && bound?.contains?.(row) && this.#ownsField(row) ? row : null
+  }
+
   // One on_client binding (issue #95): its outside guard, preventDefault rule,
   // confirm gate, then its ops — every flag read from the binding itself.
-  #runBinding(record, event, trigger, ordinal) {
+  // `trigger` is the ops' @trigger and the confirm ctx.el (with within:, the
+  // row); `bound`, the element the binding is on, keys its wait (issue #442).
+  #runBinding(record, event, trigger, ordinal, bound = trigger) {
     const { ops, confirm, confirmWhen, outside, window: windowBound, shortcut, prevent } = record
     // Outside guard FIRST — identical semantics to dispatch() (issue #80): an
     // outside: trigger is a COMPLETE no-op for events inside this root, before
@@ -3564,7 +3659,7 @@ export default class extends Controller {
     // which must NEVER prompt. The same confirmResolver gate on(:action,
     // confirm:) uses (issues #52/#55/#178), so a themed dialog covers both.
     const message = this.#effectiveConfirmMessage(confirm, confirmWhen)
-    const apply = this.#waitedOps(record, ordinal, trigger, () => this.#applyOps(this.#parseOps(ops)))
+    const apply = this.#waitedOps(record, ordinal, bound, () => this.#applyOps(this.#parseOps(ops), trigger))
     if (!message) return apply()
     if (message instanceof Promise) {
       return message.then((resolved) => (resolved ? this.#confirmThen(resolved, trigger, apply) : apply()))
@@ -4751,10 +4846,10 @@ export default class extends Controller {
   // nested-reactive-root ownership filter, issue #15). The whitelist + skip
   // 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, trigger) {
     applyOps(
       list,
-      (args) => this.#opTargets(args),
+      (args) => this.#opTargets(args, trigger),
       (name, args) => this.#diagnoseZeroTargets(`client op "${name}"`, args),
     )
   }
@@ -4783,13 +4878,17 @@ export default class extends Controller {
     if (__SPLIT__) withFeature("devtools", use)
   }
 
-  // Resolve an op's targets: "@root" is this element; a selector resolves
-  // WITHIN this root and excludes nested reactive roots' subtrees (issue #15
-  // semantics — the same nearest-root ownership check the field walk uses);
-  // global: true opts a single op out to document-wide.
-  #opTargets(args) {
+  // Resolve an op's targets: "@root" is this element; "@trigger" (issue #442)
+  // the element whose on_client binding fired, when there is one and it is an
+  // element (a window-bound binding's is the window; a reducer's $ops, a
+  // feature's ops and a stream have none); a selector resolves WITHIN this
+  // root and excludes nested reactive roots' subtrees (issue #15 semantics —
+  // the same nearest-root ownership check the field walk uses); global: true
+  // opts a single op out to document-wide.
+  #opTargets(args, trigger) {
     const to = args.to
     if (to === "@root") return [this.element]
+    if (to === "@trigger") return trigger?.nodeType === 1 ? [trigger] : []
     if (typeof to !== "string" || to === "") return []
     if (args.global) return [...document.querySelectorAll(to)]
     return [...this.element.querySelectorAll(to)].filter((el) => this.#ownsField(el))

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

@@ -657,6 +657,8 @@ module Phlex
             end
             raise ArgumentError, "reactive_on_complete #{name.inspect} got no ops — a dead binding" if pairs.empty?
 
+            # Issue #442: a completion has no element whose binding fired.
+            Phlex::Reactive::JS.refuse_trigger!(pairs, "a reactive_on_complete run")
             Phlex::Reactive::JS.assert_ops_allowed!(pairs) unless run.is_a?(Phlex::Reactive::JS)
             pairs
           end

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

@@ -504,6 +504,23 @@ module Phlex
         # on a window-bound binding, an ArgumentError with shortcut:.
         #   div(**on_client(:drop, js.remove_class("#zone", "is-over"), prevent: false))
         #
+        # Issue #442: `within:` makes ONE binding serve a whole subtree — a list
+        # of N rows binds once instead of N times. The record runs only for an
+        # event from inside an element matching the selector under the bound
+        # element (owned by this root: a row of a nested reactive root is that
+        # root's), and that element is the ops' `:trigger`; read each row's
+        # value off it with from:/attr: (see Phlex::Reactive::JS#set_value):
+        #   ul(**on_client(:click, js.set_value("#item-value", from: :trigger, attr: "data-value")
+        #                            .set_attr(:trigger, "aria-selected", "true"),
+        #                  within: "[role=option]"))
+        # Anywhere else (the list's padding) is a complete no-op: no
+        # preventDefault, no confirm, no ops. The bound element is a container,
+        # so a click binding is not forced to type="button". window:, outside:
+        # and shortcut: raise (a delegated binding is element-bound), and so
+        # does once: (Stimulus would drop the listener on the first click, a
+        # miss included). A window-bound binding has no trigger element: its
+        # `:trigger` ops resolve to nothing (warned under verbose_errors).
+        #
         # Ops are EPHEMERAL UI: any server re-render of the component (an action
         # reply, a broadcast, a morph) rebuilds from server state and resets
         # whatever they toggled — by design (the LiveView JS-commands caveat). Use
@@ -513,7 +530,7 @@ module Phlex
         # accepted — a dead trigger should fail at render, not no-op in the
         # browser.
         def on_client(event, ops, window: false, once: false, outside: false, confirm: nil, detail: nil,
-                      shortcut: nil, debounce: nil, throttle: nil, prevent: true)
+                      shortcut: nil, debounce: nil, throttle: nil, prevent: true, within: nil)
           unless ops.is_a?(Phlex::Reactive::JS)
             raise ArgumentError,
               "on_client expects a Phlex::Reactive::JS chain (e.g. js.toggle(\"#menu\")), " \
@@ -533,8 +550,10 @@ module Phlex
           shortcut = client_shortcut!(event, shortcut, window:, outside:)
           keeps_default!("on_client(#{event.inspect})", prevent, shortcut) unless prevent == true
           window_bound = window || outside || !shortcut.nil?
+          client_within!(event, within, window:, outside:, shortcut:, once:) unless within.nil?
           keep_default = !prevent && !window_bound
-          record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:, keep_default:)
+          record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:, keep_default:,
+            within:)
           client_binding_wait!(record, event, debounce, throttle) unless debounce.nil? && throttle.nil?
           # The record's `on` stays the bare keydown: the client reads a key
           # filter from `on`, and `mod` is not a key.
@@ -553,7 +572,7 @@ module Phlex
           # hidden = !navigator.clipboard.readText. Render the trigger `hidden`
           # for reveal-when-available (a dead paste button never shows).
           attrs[:data][:reactive_clipboard] = "true" if ops.ops.any? { |name, _| name == "paste_into" }
-          attrs[:type] = "button" if event == "click" && !window_bound
+          attrs[:type] = "button" if event == "click" && !window_bound && within.nil?
           attrs
         end
 
@@ -1596,7 +1615,8 @@ module Phlex
         # overridable confirmResolver on(:action, confirm:) uses (#52/#55); the
         # client prompts BEFORE applying the ops. Issue #179: a Hash confirm: is
         # CONDITIONAL, compiled by the shared compile_conditional_confirm.
-        def client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:, keep_default:)
+        def client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:, keep_default:,
+                                  within: nil)
           record = { "on" => event }
           # Issue #433: RIGHT AFTER "on" — phlex/reactive/early reads the pair
           # `"on":"<event>","prevent":false` off the raw attribute before connect.
@@ -1607,6 +1627,9 @@ module Phlex
           # this binding's :once listener — the client skips a spent once record.
           record["once"] = true if once
           record["detail"] = client_binding_detail(detail, once:) unless detail.nil?
+          # Issue #442: written only when given, so a record without it is
+          # byte-identical to before.
+          record["within"] = within unless within.nil?
           case confirm
           when nil, false then nil
           when String then record["confirm"] = confirm
@@ -1617,6 +1640,29 @@ module Phlex
           record
         end
 
+        # Issue #442: validate on_client's within: — a non-empty CSS selector,
+        # on an element-bound binding that can survive a miss.
+        def client_within!(event, within, window:, outside:, shortcut:, once:)
+          label = "on_client(#{event.inspect})"
+          unless within.is_a?(String) && !within.strip.empty?
+            raise ArgumentError,
+              "#{label} within: takes a non-empty CSS selector String naming the elements to delegate " \
+              "from (e.g. within: \"[role=option]\"), got #{within.inspect}"
+          end
+          { "window:" => window, "outside:" => outside, "shortcut:" => shortcut }.each do |name, value|
+            next unless value
+
+            raise ArgumentError,
+              "#{label} within: delegates from the bound element's own subtree — it cannot be " \
+              "window-bound; drop #{name}"
+          end
+          return unless once
+
+          raise ArgumentError,
+            "#{label} within: cannot combine with once: — Stimulus removes a :once listener on its " \
+            "first event, so a first event outside every match would leave the binding dead"
+        end
+
         # Issue #393: the one message on() and on_client() raise when given both
         # waits. Built only on that error path (on() is a hot path).
         def both_waits_message(label)