phlex-reactive 0.12.3 → 0.12.5

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,
+    )
   }
 }
 
@@ -1047,9 +1059,11 @@ function runTransition(el, transition, flip) {
 // Phlex::Reactive::JS's vocabulary; an op name not in this map is
 // warn-and-skipped by #applyOps (client-side default-deny — a stale or newer
 // ops attr must never break the page). Each op is a pure, local DOM mutation:
-// nothing is read back, nothing is sent anywhere. Frozen so nothing can be
-// registered into it at runtime — extending the vocabulary is a gem change,
-// not an app hook.
+// nothing is sent anywhere, and nothing is read back — with ONE deliberate
+// exception, paste_into (issue #228), which reads the clipboard behind the
+// browser's own gesture + permission gates and still only writes locally.
+// Frozen so nothing can be registered into it at runtime — extending the
+// vocabulary is a gem change, not an app hook.
 const CLIENT_OPS = Object.freeze({
   show: (el, args) => setHidden(el, false, args),
   hide: (el, args) => setHidden(el, true, args),
@@ -1099,6 +1113,24 @@ const CLIENT_OPS = Object.freeze({
   // exactly like a user submit. No form → no-op. ACTOR-ONLY like focus: the
   // broadcast builder refuses it server-side (BROADCAST_REFUSED_OPS).
   submit: (el) => submitFormFor(el)?.requestSubmit?.(),
+
+  // Clipboard-source paste (issue #228): on a user gesture, read
+  // navigator.clipboard.readText() and feed the text into the target field
+  // through the normal input pipeline — exactly what a native Cmd/Ctrl+V does.
+  // The ONE op that reads a browser API and is async: fire-and-forget, so
+  // applyOps stays sync and chain siblings never wait (the runTransition
+  // posture). A rejected/dismissed read, empty text, or a missing API is a
+  // SILENT no-op — page state must not change. ACTOR-ONLY like focus/submit:
+  // the broadcast builder refuses it server-side (BROADCAST_REFUSED_OPS) —
+  // and that server gate is the REAL one. The browser only partially backs it
+  // up: Safari gates every read on a fresh gesture and Firefox shows its
+  // paste picker per read, but Chromium's clipboard-read is a PERSISTENT
+  // per-origin permission — once granted (the legit paste button itself
+  // induces that), readText() succeeds with no gesture. No client-side
+  // refusal is possible here: the reactive:js interpreter cannot distinguish
+  // an actor reply's stream from a broadcast's, and reply.js legitimately
+  // carries this op.
+  paste_into: (el) => pasteClipboardInto(el),
 })
 
 // The form a submit op commits (issue #226), in order: the target itself when
@@ -1111,6 +1143,32 @@ function submitFormFor(el) {
   return el?.form ?? el?.closest?.("form") ?? null
 }
 
+// Read the clipboard into a field (issue #228) — the body of the paste_into
+// op. The write mirrors a native paste: set .value, dispatch a bubbling
+// `input` event (the set-value + dispatch contract, issue #183 — compute
+// reducers, show bindings, and on_complete all run exactly as if the user
+// had typed), then focus (the caret lands where the user continues typing on
+// a partial paste). Availability-guarded: insecure contexts and some
+// webviews have no navigator.clipboard — the connect()-time gate hides
+// marked triggers there, so this guard is belt-and-braces. Empty text is a
+// no-op: "paste nothing" must not clear a half-typed field.
+function pasteClipboardInto(field) {
+  const clipboard = globalThis.navigator?.clipboard
+  if (typeof clipboard?.readText !== "function") return
+  clipboard
+    .readText()
+    .then((text) => {
+      if (!text) return
+      field.value = text
+      if (typeof field.dispatchEvent === "function") field.dispatchEvent(new Event("input", { bubbles: true }))
+      field.focus?.()
+    })
+    .catch(() => {
+      // Permission denied or the prompt dismissed — the browser's own UX said
+      // no. The issue-#228 contract: a silent no-op, never an error.
+    })
+}
+
 // Apply a hidden-flag change, optionally animated by a [during, from, to]
 // transition (issue #96). Split out so show/hide/toggle share it.
 function setHidden(el, hidden, args) {
@@ -1445,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
@@ -1453,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).
@@ -1554,6 +1672,9 @@ export default class extends Controller {
   // Lazy initial mount (issue #165): the bound re-probe attached to
   // turbo:morph-element so a Turbo page-refresh morph re-fires the defer fetch.
   #boundProbeLazyDefer
+  // Clipboard-trigger availability gate (issue #228): the bound morph re-sync,
+  // held for teardown.
+  #boundSyncClipboard
 
   // Mark that a reactive controller actually connected, so the registration
   // guard above knows the controller was registered (issue #26 part 2).
@@ -1735,6 +1856,24 @@ export default class extends Controller {
       this.element.addEventListener?.("turbo:morph-element", this.#boundSeedCompute)
       this.recompute()
     }
+
+    // Clipboard-trigger availability gate (issue #228) — ONLY when this root
+    // owns a paste trigger (on_client marks one with data-reactive-clipboard),
+    // so every other component pays a single probe (the show/filter/tags gate
+    // precedent). The Async Clipboard API is absent in insecure contexts and
+    // some webviews; a paste button that can never work must not show. The
+    // gate OWNS a marked trigger's `hidden` flag: author the trigger `hidden`
+    // and this pass reveals it where the API exists (a dead button never
+    // paints); turbo:morph-element re-syncs because a morph rewrites the
+    // trigger back to its authored hidden state. Like every sibling gate the
+    // decision is made ONCE at connect — render the paste trigger
+    // unconditionally: a trigger first INTRODUCED by a later morph stays
+    // ungated (hidden) until a full replace re-connects the controller.
+    if (this.#clipboardGateEnabled()) {
+      this.#boundSyncClipboard = () => this.#syncClipboardTriggers()
+      this.element.addEventListener?.("turbo:morph-element", this.#boundSyncClipboard)
+      this.#syncClipboardTriggers()
+    }
   }
 
   // Whether this root opts into dirty tracking (issue #103): track_dirty: puts the
@@ -1765,6 +1904,7 @@ export default class extends Controller {
     this.#teardownTagsSync()
     this.#teardownNestedJsonSync()
     this.#teardownComputeSeed()
+    this.#teardownClipboardGate()
     if (this.#boundProbeLazyDefer) {
       this.element.removeEventListener?.("turbo:morph-element", this.#boundProbeLazyDefer)
     }
@@ -2136,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
@@ -3551,6 +3695,40 @@ export default class extends Controller {
     return !!this.element.getAttribute?.("data-reactive-on-complete")
   }
 
+  // Whether this root owns a clipboard-marked paste trigger (issue #228) —
+  // the connect() gate. The ROOT itself counts (a button-only component that
+  // mixes on_client(paste_into) onto reactive_root — the #dirtyTrackingEnabled
+  // root-then-descendants precedent), then one scoped query; a NESTED root's
+  // triggers are its own controller's to gate (issue #15 ownership).
+  #clipboardGateEnabled() {
+    if (this.element.getAttribute?.("data-reactive-clipboard")) return true
+    const nodes = this.element.querySelectorAll?.("[data-reactive-clipboard]") ?? []
+    for (const el of nodes) if (this.#ownsField(el)) return true
+    return false
+  }
+
+  // Set every owned paste trigger's `hidden` from clipboard availability
+  // (issue #228): available → revealed (the authored `hidden` was only the
+  // no-dead-button first paint), missing → hidden (insecure context /
+  // webview). The gate owns the flag on MARKED elements only — nothing else
+  // is ever touched. A marked ROOT is gated too: when the component IS the
+  // paste button, hiding the root is exactly "the dead button never shows".
+  #syncClipboardTriggers() {
+    const available = typeof globalThis.navigator?.clipboard?.readText === "function"
+    if (this.element.getAttribute?.("data-reactive-clipboard")) this.element.hidden = !available
+    for (const el of this.element.querySelectorAll?.("[data-reactive-clipboard]") ?? []) {
+      if (this.#ownsField(el)) el.hidden = !available
+    }
+  }
+
+  // Remove the clipboard gate's morph listener on disconnect, so a stray
+  // morph event after a Turbo navigation never re-syncs a detached root.
+  #teardownClipboardGate() {
+    if (!this.#boundSyncClipboard) return
+    this.element.removeEventListener?.("turbo:morph-element", this.#boundSyncClipboard)
+    this.#boundSyncClipboard = undefined
+  }
+
   // Parse-and-memoize the completion bindings, keyed on the RAW attr string:
   // a morph that rewrote the payload re-parses and RESETS the latches (the
   // morph listener's own arm pass then re-arms without firing). A removed
@@ -3589,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),
+        )
+      }
     })
   }
 
@@ -4131,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 —
@@ -4207,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
@@ -4360,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