phlex-reactive 0.16.7 → 0.16.9

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

@@ -136,6 +136,20 @@ export function registerReactiveToken() {
 // is emitted AFTER all render streams in the reply (the endpoint appends it
 // last), so focus("[name=next]") sees the freshly morphed DOM — Turbo applies
 // streams in document order.
+//
+// Focus ops wait one frame (issue #446). Turbo renders a stream message inside
+// its focus preservation: it reads document.activeElement, appends the
+// streams, waits one animation frame, reads it again and, when the element
+// focused before has an id and focus moved, focuses that element again. This
+// action runs behind a frame each stream queued before that compare, so a
+// focus, focus_first or blur applied here would be undone, and the old
+// field's focus binding would run again. The ops before the first focus op
+// still run now; that op and the rest of its chain (order kept) run in a frame
+// queued from here, the one after the compare, which then saw nothing move and
+// restored nothing. Plain requestAnimationFrame, never a timeout: in a hidden
+// tab Turbo's compare waits for the first frame too.
+const FOCUS_OPS = ["focus", "focus_first", "blur"]
+
 export function registerReactiveJs() {
   const actions = window.Turbo?.StreamActions
   if (!actions || actions["reactive:js"]) return
@@ -155,16 +169,21 @@ export function registerReactiveJs() {
       }
       return
     }
-    applyOps(
-      list,
-      (args) => streamOpTargets(args, root),
-      verbose
-        ? (name, args) =>
-            __SPLIT__
-              ? withFeature("devtools", (devtools) => devtools.diagnoseStream(name, args, root))
-              : devtoolsFeature.diagnoseStream(name, args, root)
-        : undefined,
-    )
+    const run = (ops) =>
+      applyOps(
+        ops,
+        (args) => streamOpTargets(args, root),
+        verbose
+          ? (name, args) =>
+              __SPLIT__
+                ? withFeature("devtools", (devtools) => devtools.diagnoseStream(name, args, root))
+                : devtoolsFeature.diagnoseStream(name, args, root)
+          : undefined,
+      )
+    const at = list.findIndex((entry) => FOCUS_OPS.includes(entry?.[0]))
+    if (at < 0 || typeof requestAnimationFrame !== "function") return run(list)
+    run(list.slice(0, at))
+    requestAnimationFrame(() => run(list.slice(at)))
   }
 }
 
@@ -1953,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)
@@ -1967,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
@@ -1978,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 []
@@ -2046,6 +2112,10 @@ function streamOpTargets(args, root) {
 //   core.owns(el)                         is this control this root's own, not
 //                                         a nested reactive root's (issue #15)
 //   core.ownership()                      the hoisted per-pass form of owns
+//   core.bindingOwns(el)                  may this root's bindings READ this
+//                                         control: owns, or a shared field
+//                                         just below (issue #440)
+//   core.bindingOwnership()               the hoisted per-pass form of it
 //   core.opTargets(args)                  the elements an op's `to:` names
 //   core.applyOps(list, defaultTo)        run an op list root-scoped
 //   core.diagnose(label, args)            the zero-target warning
@@ -2991,6 +3061,8 @@ export default class extends Controller {
       },
       owns: (el) => this.#ownsField(el),
       ownership: () => this.#ownershipFilter(),
+      bindingOwns: (el) => this.#bindingOwns(el),
+      bindingOwnership: () => this.#bindingOwnership(),
       opTargets: (args) => this.#opTargets(args),
       diagnose: (label, args) => this.#diagnoseZeroTargets(label, args),
       // Apply an op list root-scoped, with the zero-target diagnostics; a
@@ -3495,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))
@@ -3506,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
@@ -3539,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()))
@@ -4397,7 +4492,8 @@ export default class extends Controller {
   // the control's own server root sits directly below this one. One level: a
   // grand-host never sees it. Whatever reads #collectFields sees it too: the
   // request, and the conditional confirm (it judges the fields the action is
-  // about to post). Bindings, computes, listnav, dirty tracking and persist
+  // about to post). The client bindings read such a control too
+  // (#bindingOwnership); listnav, ops, busy_on, dirty tracking and persist
   // keep the strict nearest-root #ownershipFilter / #ownsField.
   #serverFieldFilter() {
     const nested = this.element.querySelectorAll(AWAKE_ROOT)
@@ -4410,6 +4506,30 @@ export default class extends Controller {
     }
   }
 
+  // What this root's client BINDINGS read (issue #440): its own controls, as
+  // #ownsField, plus a control marked data-reactive-shared-field whose own
+  // server root is this one (under client-only roots, issue #410) or sits
+  // directly below it: one level, the #serverFieldFilter rule. Field reads
+  // only: show (every term, after:, clear:, disable: true), enable, show and
+  // group targets, checked_* counts, on_complete, media, css vars, compute
+  // inputs and outputs. Which binding ELEMENTS a root evaluates, and every op, listnav,
+  // busy_on, dirty and persist read, stay on the strict #ownsField. An
+  // unmarked control in a nested root costs one attribute read more.
+  #bindingOwns(el) {
+    if (this.#ownsField(el)) return true
+    if (el.getAttribute?.("data-reactive-shared-field") == null) return false
+    const own = serverRoot(el, AWAKE_ROOT, this.element)
+    return own === this.element || serverRoot(own?.parentElement, AWAKE_ROOT, this.element) === this.element
+  }
+
+  // The hoisted per-pass form of #bindingOwns, with #ownershipFilter's fast
+  // path: no nested root, every control is this root's. Never cached on the
+  // instance (a morph replaces nodes).
+  #bindingOwnership() {
+    if (this.element.querySelectorAll(AWAKE_ROOT).length === 0) return () => true
+    return (el) => this.#bindingOwns(el)
+  }
+
   // One walk over THIS root's named controls (not a nested reactive root's),
   // returning both the scalar `fields` and any chosen `files`. The ownership
   // predicate is hoisted ONCE (issue #117) via #ownershipFilter — in the common
@@ -4701,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),
     )
   }
@@ -4733,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)