phlex-reactive 0.16.8 → 0.16.9

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

@@ -1972,13 +1972,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 +1988,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 +2041,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 +3567,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 +3581,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 +3634,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 +4821,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 +4853,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)

data/lib/phlex/reactive/js.rb

@@ -23,8 +23,16 @@ module Phlex
     #
     # Targets: a CSS selector string is resolved WITHIN the component's root by
     # default (nested reactive roots excluded, issue #15 semantics); `:root`
-    # targets the root element itself; `global: true` opts a single op out of
-    # root scoping (document escape hatch, e.g. a page-level overlay).
+    # targets the root element itself; `:trigger` (issue #442) targets the
+    # element whose on_client binding fired (with on_client's within:, the
+    # matching element under it); `global: true` opts a single op out of root
+    # scoping (document escape hatch, e.g. a page-level overlay).
+    #
+    # Reads (issue #442): set_value, text and set_attr take `from:` + `attr:`
+    # in place of a literal value — the value is read in the browser off the
+    # `from` element (a data-* attribute or its text), so one chain bound once
+    # serves every row of a list:
+    #   js.set_value("#item-value", from: :trigger, attr: "data-value")
     #
     # The op vocabulary is a fixed whitelist mirrored by the client interpreter
     # — an op name the client doesn't know is warn-and-skipped there
@@ -35,6 +43,38 @@ module Phlex
       # Serialized stand-in for "the component's own root element".
       ROOT_SENTINEL = "@root"
 
+      # Serialized stand-in for "the element whose on_client binding fired"
+      # (issue #442). Only an on_client binding has one: a server-pushed op
+      # (reply.js, broadcast_to(js:)) or a reactive_on_complete run refuses it.
+      TRIGGER_SENTINEL = "@trigger"
+
+      # attr: :text's wire value — read the element's textContent.
+      TEXT_READ = "@text"
+
+      # What a from: read may take off an element (issue #442): a data-*
+      # attribute — state the server declared on the element — or its text.
+      # Two-sided like the write allowlist below: the client refuses anything
+      # else in a hand-built record. Narrow on purpose (widening later breaks
+      # nothing; narrowing would).
+      READABLE_ATTR = /\Adata-[a-z][a-z0-9-]*\z/i
+
+      # The ops whose value from: + attr: can read, and the arg keys that name
+      # an element (where a server-pushed op has no @trigger to put).
+      READ_OPS = %w[set_value text set_attr].freeze
+      TARGET_KEYS = %w[to from expanded submitter].freeze
+
+      # The field-writing ops write a field the author names: never the root
+      # (a container) nor the trigger (the element clicked).
+      FIELD_REFUSED = {
+        :root => "the component root", ROOT_SENTINEL => "the component root",
+        :trigger => "the trigger", TRIGGER_SENTINEL => "the trigger"
+      }.freeze
+
+      # The positional value set_value/text/set_attr default to, so nil keeps
+      # meaning "clear" and only from: may replace it.
+      NO_VALUE = Object.new.freeze
+      private_constant :NO_VALUE
+
       # The attribute-name allowlist (issue #96) — the security-critical part of
       # the attr ops, enforced HERE at build time AND again in the client
       # interpreter (two-sided default-deny: a hand-built ops attr must not
@@ -75,15 +115,73 @@ module Phlex
           "target must be :root or a CSS selector string, got #{to.inspect}"
       end
 
+      # The op builder's target: normalize_target plus :trigger (issue #442).
+      # Separate so a pending hint or a css-vars binding given :trigger keeps
+      # raising — neither has a trigger element.
+      def self.normalize_client_target(to)
+        return TRIGGER_SENTINEL if to == :trigger
+        return ROOT_SENTINEL if to == :root
+        return to if to.is_a?(String)
+
+        raise ArgumentError,
+          "target must be :trigger, :root or a CSS selector string, got #{to.inspect}"
+      end
+
+      # Also refuses @trigger (a raw list is server-pushed or a
+      # reactive_on_complete run: no trigger) and a read attr outside the
+      # data-*/text rule (issue #442).
       def self.assert_ops_allowed!(list)
+        refuse_trigger!(list)
         Array(list).each do |op, args|
-          next unless ATTR_NAME_OPS.include?(op.to_s) && args.is_a?(::Hash)
+          next unless args.is_a?(::Hash)
+
+          name = arg(args, "name")
+          assert_allowed_attr(name.to_s) if name && ATTR_NAME_OPS.include?(op.to_s)
+          # A read: the client takes args.attr only on a read op with a from.
+          read_attr(arg(args, "attr"), op) if READ_OPS.include?(op.to_s) && arg(args, "from")
+        end
+      end
+
+      # Raise when an op in `list` (a JS chain or a raw [[op, args]] list)
+      # names @trigger (a target, from:, or dispatch's detail_from:, which
+      # reads off it). Called for every op the server pushes
+      # (Response.js_ops_json: reply.js and broadcast_to(js:)) and for a
+      # reactive_on_complete run.
+      def self.refuse_trigger!(list, where = "a server-pushed op (reply.js, broadcast_to(js:)) " \
+                                             "or a reactive_on_complete run")
+        op = trigger_op(list.is_a?(JS) ? list.ops : list)
+        return if op.nil?
+
+        raise ArgumentError,
+          "#{self}: #{op} names @trigger, the element whose on_client binding fired (a :trigger " \
+          "target, from: :trigger or detail_from:) — #{where} has no trigger. Name the element " \
+          "with a CSS selector."
+      end
 
-          name = args["name"] || args[:name]
-          assert_allowed_attr(name.to_s) if name
+      # The name of the first op that names @trigger, or nil. A raw list, or a
+      # hand-built JS.new([...]), may carry Symbol keys or no args Hash.
+      def self.trigger_op(list)
+        Array(list).each do |op, args|
+          next unless args.is_a?(::Hash)
+          return op.to_s if arg(args, "detail_from") || TARGET_KEYS.any? { arg(args, it) == TRIGGER_SENTINEL }
         end
+        nil
       end
 
+      # What attr: may read (issue #442): :text (or its "@text" wire form) or a
+      # data-* attribute name. Returns the wire value; raises otherwise.
+      def self.read_attr(attr, verb = "a read")
+        return TEXT_READ if [:text, TEXT_READ].include?(attr)
+        return attr if attr.is_a?(String) && attr.match?(READABLE_ATTR)
+
+        raise ArgumentError,
+          "#{self}: #{verb} attr: reads a data-* attribute or :text (textContent), got #{attr.inspect}"
+      end
+
+      # A raw list's args may carry String or Symbol keys.
+      def self.arg(args, key) = args.key?(key) ? args[key] : args[key.to_sym]
+      private_class_method :arg
+
       # The attribute-name allowlist (issue #96), case-insensitive. Refuses
       # event-handler (on*), URL-bearing, and style attributes. Enforced at build
       # time by the instance builder AND on the raw-list escape hatch — two-sided
@@ -172,9 +270,15 @@ module Phlex
       # instead of toggling presence — current == on ? off : on, so an absent
       # attribute becomes `on`. For aria-expanded/aria-pressed/data-state:
       #   js.toggle_attr("#trigger", "aria-expanded", "true", "false")
+      #
+      # set_attr(to, name, from:, attr:) (issue #442) reads the value off an
+      # element instead (see #set_value); the name allowlist above still
+      # decides what may be WRITTEN:
+      #   js.set_attr(:trigger, "aria-selected", "true")
+      #   js.set_attr("#preview", "data-state", from: :trigger, attr: "data-state")
 
-      def set_attr(to, name, value, global: false, keep: false)
-        append("set_attr", attr_args(to, name, global:, keep:, value:))
+      def set_attr(to, name, value = NO_VALUE, from: nil, attr: nil, global: false, keep: false)
+        append("set_attr", attr_args(to, name, global:, keep:) { value_args(it, "set_attr", value, from:, attr:) })
       end
 
       def remove_attr(to, name, global: false, keep: false)
@@ -251,12 +355,13 @@ module Phlex
         args = target_args(to, global:)
         return append("submit", args) if submitter.nil?
 
-        unless submitter.is_a?(String) && !submitter.empty?
+        unless submitter == :trigger || (submitter.is_a?(String) && !submitter.empty?)
           raise ArgumentError,
-            "js.submit submitter: must be a CSS selector string naming a submit control, got #{submitter.inspect}"
+            "js.submit submitter: must be a CSS selector string naming a submit control " \
+            "(or :trigger), got #{submitter.inspect}"
         end
 
-        append("submit", args.merge("submitter" => submitter).freeze)
+        append("submit", args.merge("submitter" => normalize_target(submitter)).freeze)
       end
 
       # --- Clipboard-source paste (issue #228) ---
@@ -279,12 +384,8 @@ module Phlex
       # element (the two passes would fight over the same attribute).
 
       def paste_into(to, global: false)
-        if [:root, ROOT_SENTINEL].include?(to)
-          raise ArgumentError,
-            "#{self.class}: paste_into targets a field, not the component root — " \
-            "pass the input's CSS selector (e.g. js.paste_into(\"[name=code]\"))"
-        end
-
+        refuse_field_target!(to, "paste_into targets a field, not %s — " \
+                                 "pass the input's CSS selector (e.g. js.paste_into(\"[name=code]\"))")
         append("paste_into", target_args(to, global:))
       end
 
@@ -344,12 +445,8 @@ module Phlex
 
       def preview_file(to, into:, name: nil, global: false, valid: false, wrap: nil, max_bytes: nil, accept: nil,
                        per_file: false)
-        if [:root, ROOT_SENTINEL].include?(to)
-          raise ArgumentError,
-            "#{self.class}: preview_file reads a file input, not the component root — " \
-            "pass the input's CSS selector (e.g. js.preview_file(\"#photo-file\", into: \"#photo\"))"
-        end
-
+        refuse_field_target!(to, "preview_file reads a file input, not %s — pass the input's CSS selector " \
+                                 "(e.g. js.preview_file(\"#photo-file\", into: \"#photo\"))")
         args = { "to" => normalize_target(to), "into" => preview_selector(:into, into) }
         args["name"] = preview_selector(:name, name) unless name.nil?
         args["global"] = true if global
@@ -368,9 +465,14 @@ module Phlex
       # less powerful than set_attr. Pair with `global: true` to paint a value
       # into a node OUTSIDE the component's root (the cross-root text escape,
       # e.g. a read-only recap in another tab pane).
+      #
+      # text(to, from:, attr:) (issue #442) reads the text off an element
+      # instead (see #set_value) — the label of the row that was clicked:
+      #   js.text("#item-label", from: :trigger, attr: "data-label")
 
-      def text(to, value, global: false)
-        args = { "to" => normalize_target(to), "value" => value.to_s }
+      def text(to, value = NO_VALUE, from: nil, attr: nil, global: false)
+        args = { "to" => normalize_target(to) }
+        value_args(args, "text", value, from:, attr:)
         args["global"] = true if global
         append("text", args.freeze)
       end
@@ -413,15 +515,21 @@ module Phlex
       # ACTOR-ONLY like paste_into: a broadcast that overwrote every
       # subscriber's field would be hostile (BROADCAST_REFUSED_OPS).
       #   button(**on_client(:click, js.set_value("#notes", "Thanks"))) { "Thanks" }
-
-      def set_value(to, value, global: false)
-        if [:root, ROOT_SENTINEL].include?(to)
-          raise ArgumentError,
-            "#{self.class}: set_value targets a field, not the component root — " \
-            "pass the field's CSS selector (e.g. js.set_value(\"#notes\", \"Thanks\"))"
-        end
-
-        args = { "to" => normalize_target(to), "value" => value.to_s }
+      #
+      # Reads (issue #442): `from:` + `attr:` in place of the value read it in
+      # the browser off an element — `from:` is :trigger, :root or a selector,
+      # resolved with the op's own scoping (global: included), first match;
+      # `attr:` is a data-* attribute or :text (textContent). A missing
+      # attribute reads "", so it clears; a `from:` matching nothing skips the
+      # op. Exactly one of the value or `from:`. The same on text and set_attr:
+      #   ul(**on_client(:click, js.set_value("#item-value", from: :trigger, attr: "data-value"),
+      #                  within: "[role=option]"))
+
+      def set_value(to, value = NO_VALUE, from: nil, attr: nil, global: false)
+        refuse_field_target!(to, "set_value targets a field, not %s — " \
+                                 "pass the field's CSS selector (e.g. js.set_value(\"#notes\", \"Thanks\"))")
+        args = { "to" => normalize_target(to) }
+        value_args(args, "set_value", value, from:, attr:)
         args["global"] = true if global
         append("set_value", args.freeze)
       end
@@ -465,8 +573,15 @@ module Phlex
       # uniformly); `detail:` is the event's `detail` payload. The client uses raw
       # element.dispatchEvent — the shared controller SHADOWS Stimulus's
       # this.dispatch helper, so the interpreter must not use it.
-      def dispatch(name, to: nil, detail: {}, global: false)
+      #
+      # detail_from: (issue #442) maps detail keys to what to read off the
+      # TRIGGER (a data-* attribute or :text), merged over `detail:` in the
+      # browser — every value a String. Only an on_client binding has a
+      # trigger: a server-pushed dispatch refuses it.
+      #   js.dispatch("app:item-picked", detail_from: { id: "data-id", text: :text })
+      def dispatch(name, to: nil, detail: {}, detail_from: {}, global: false)
         args = { "name" => name.to_s, "to" => normalize_target(to.nil? ? :root : to), "detail" => detail }
+        args["detail_from"] = detail_reads(detail, detail_from) unless detail_from.nil? || detail_from == {}
         args["global"] = true if global
         append("dispatch", args.freeze)
       end
@@ -609,17 +724,72 @@ module Phlex
         [on, off].freeze
       end
 
-      # An attr op's args: the target, the allowlisted name, an optional
-      # (stringified) value. The name is validated LOUDLY at build time.
-      def attr_args(to, name, global:, keep: false, value: :__none)
+      # An attr op's args: the target, the allowlisted name, then whatever the
+      # block adds (set_attr's value or read). The name is validated LOUDLY at
+      # build time.
+      def attr_args(to, name, global:, keep: false)
         name = name.to_s
         assert_allowed_attr(name)
         args = { "to" => normalize_target(to), "name" => name }
-        args["value"] = value.to_s unless value == :__none
+        yield args if block_given?
         args["global"] = true if global
         with_keep(args, keep)
       end
 
+      # The value of set_value/text/set_attr (issue #442): the literal
+      # (stringified; nil clears) as "value", or a read as "from" + "attr".
+      # Exactly one — loud at render.
+      def value_args(args, verb, value, from:, attr:)
+        literal = !value.equal?(NO_VALUE)
+        raise ArgumentError, "#{self.class}: #{verb} takes a value or from:, not both" if literal && !from.nil?
+        if from.nil? && !attr.nil?
+          raise ArgumentError,
+            "#{self.class}: #{verb} attr: needs from: (the element to read it off)"
+        end
+        return args["value"] = value.to_s if literal
+        raise ArgumentError, "#{self.class}: #{verb} needs a value or from: + attr:" if from.nil?
+        raise ArgumentError, "#{self.class}: #{verb} from: needs attr: (a data-* attribute or :text)" if attr.nil?
+
+        source = normalize_target(from)
+        raise ArgumentError, "#{self.class}: #{verb} from: needs a CSS selector, got an empty string" if source.empty?
+
+        args["from"] = source
+        args["attr"] = self.class.read_attr(attr, verb)
+      end
+
+      # dispatch's detail_from: — detail key → read attr, the keys Strings.
+      # A key also in detail: would silently override it, so it raises.
+      def detail_reads(detail, reads)
+        unless reads.is_a?(Hash)
+          raise ArgumentError,
+            "#{self.class}: dispatch detail_from: takes a Hash of detail keys to data-* attributes " \
+            "(or :text), got #{reads.inspect}"
+        end
+
+        literal = detail.is_a?(Hash) ? detail.keys.map(&:to_s) : []
+        normalized = reads.to_h do |key, attr|
+          key = key.to_s
+          if literal.include?(key)
+            raise ArgumentError,
+              "#{self.class}: dispatch detail_from: key #{key.inspect} is also in detail: — one would override the other"
+          end
+
+          [key, self.class.read_attr(attr, "dispatch detail_from: #{key.inspect}")]
+        end
+        if normalized.size < reads.size
+          raise ArgumentError, "#{self.class}: dispatch detail_from: keys must be unique as strings"
+        end
+
+        normalized.freeze
+      end
+
+      # set_value/paste_into/preview_file write a field the author names:
+      # `message` has a %s for what was named instead (the root, the trigger).
+      def refuse_field_target!(to, message)
+        where = FIELD_REFUSED[to]
+        raise ArgumentError, "#{self.class}: #{format(message, where)}" if where
+      end
+
       # Build-time attr-name allowlist for the instance builder — delegates to the
       # shared class-method check (also used by the raw-list escape hatch).
       def assert_allowed_attr(name)
@@ -655,9 +825,9 @@ module Phlex
         with_keep(args, keep)
       end
 
-      # Instance-side alias for the class method (used by the op builder). See
-      # JS.normalize_target — the shared :root/selector translation.
-      def normalize_target(to) = self.class.normalize_target(to)
+      # The op builder's target translation: :trigger, :root or a selector
+      # (JS.normalize_client_target; issue #442).
+      def normalize_target(to) = self.class.normalize_client_target(to)
     end
   end
 end

data/lib/phlex/reactive/response.rb

@@ -302,10 +302,14 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
         # Normalize `ops` to its JSON wire form, rejecting an empty chain — a
         # reactive:js stream with no ops is a dead stream (a mistake at the call
         # site), so fail loudly rather than emit an inert tag.
+        # Every op the server pushes (reply.js, broadcast_to(js:)) passes here,
+        # so this is where @trigger is refused for a chain too (issue #442): a
+        # pushed op has no element whose binding fired.
         def js_ops_json(ops)
           if ops.is_a?(Phlex::Reactive::JS)
             raise ArgumentError, "js(...) got no ops — a dead reactive:js stream" if ops.empty?
 
+            Phlex::Reactive::JS.refuse_trigger!(ops)
             ops.to_json
           else
             list = Array(ops)

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.16.8"
+    VERSION = "0.16.9"
   end
 end