phlex-reactive 0.15.3 → 0.15.5

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

@@ -37,6 +37,7 @@ import * as hintsFeature from "phlex/reactive/features/hints"
 import * as deferFeature from "phlex/reactive/features/defer"
 import * as sortableFeature from "phlex/reactive/features/sortable"
 import * as presenceFeature from "phlex/reactive/features/presence"
+import * as countdownFeature from "phlex/reactive/features/countdown"
 
 // phlex/reactive/runtime — the reactive controller WITHOUT its feature
 // modules (issue #275): the code both client entries share. It is not an
@@ -436,6 +437,26 @@ const IMAGE_STATE = "data-reactive-image-state"
 const IMAGE_HIDDEN = "data-reactive-image-hidden"
 let imageFallbackListeners = null
 
+// --- A wrapper an op hides (issues #391, #392) -------------------------------
+// preview_file's wrap: and reactive_image_fallback's wrap: hide the box around
+// an img. The mark says the runtime set that `hidden`, so a show removes only
+// a hide of its own, never one the author wrote. On the element, for the
+// IMAGE_HIDDEN reason. Visibility only: a wrapper usually holds the img, so
+// nothing here writes its text.
+const WRAP_HIDDEN = "data-reactive-wrap-hidden"
+
+function hideWrap(el) {
+  if (el.hasAttribute("hidden")) return
+  el.setAttribute("hidden", "")
+  el.setAttribute(WRAP_HIDDEN, "")
+}
+
+function showWrap(el) {
+  if (!el.hasAttribute(WRAP_HIDDEN)) return
+  el.removeAttribute("hidden")
+  el.removeAttribute(WRAP_HIDDEN)
+}
+
 function imageFallback(img) {
   if (img?.localName !== "img") return null
   const raw = img.getAttribute(IMAGE_FALLBACK)
@@ -451,23 +472,33 @@ const hasImageSrc = (img) => img.getAttribute("src") || img.getAttribute("srcset
 
 // The node that shows the alt text: a selector resolved inside the img's own
 // root only (a document listener has no op scope).
-function imageAltNode(img, wire) {
-  if (typeof wire.alt !== "string" || !wire.alt) return null
+function imageRootNode(img, selector) {
+  if (typeof selector !== "string" || !selector) return null
   try {
-    const node = img.closest('[data-controller~="reactive"]')?.querySelector(wire.alt)
-    // Never a node that holds the img: its textContent would wipe the img.
-    return node && !node.contains(img) ? node : null
+    return img.closest('[data-controller~="reactive"]')?.querySelector(selector) ?? null
   } catch {
     return null
   }
 }
 
+function imageAltNode(img, wire) {
+  const node = imageRootNode(img, wire.alt)
+  // Never a node that holds the img: its textContent would wipe the img.
+  return node && !node.contains(img) ? node : null
+}
+
 function setImageState(img, wire, value) {
   if (value === "error") {
     if (wire.hide && !img.hasAttribute("hidden")) {
       img.setAttribute("hidden", "")
       img.setAttribute(IMAGE_HIDDEN, "")
     }
+    // wrap: (issue #392) may hold the img: only its visibility changes.
+    if (wire.wrap) {
+      const wrap = imageRootNode(img, wire.wrap)
+      if (wrap) hideWrap(wrap)
+      else console.warn(`[phlex-reactive] reactive_image_fallback wrap: ${JSON.stringify(wire.wrap)} is not in the root — skipped`)
+    }
     const node = imageAltNode(img, wire)
     if (node) {
       node.textContent = img.getAttribute("alt") ?? ""
@@ -483,6 +514,8 @@ function resetImage(img, wire = imageFallback(img)) {
   if (!wire || img.getAttribute(IMAGE_STATE) == null) return
   if (img.getAttribute(IMAGE_STATE) === "error") {
     if (img.hasAttribute(IMAGE_HIDDEN)) img.removeAttribute("hidden")
+    const wrap = imageRootNode(img, wire.wrap)
+    if (wrap) showWrap(wrap)
     const node = imageAltNode(img, wire)
     if (node) node.hidden = true
   }
@@ -1247,6 +1280,13 @@ const CLIENT_OPS = Object.freeze({
   // its first focusable descendant (opened-menu → first menuitem).
   focus: (el) => el.focus?.(),
   focus_first: (el) => firstFocusable(el)?.focus?.(),
+  // Issue #399: blur the focused element when it is the target or inside it
+  // (Escape ends a menu's :focus-within); focus elsewhere is left alone.
+  // ACTOR-ONLY like focus (BROADCAST_REFUSED_OPS server-side).
+  blur: (el) => {
+    const active = el.ownerDocument?.activeElement ?? globalThis.document?.activeElement
+    if (active && (active === el || el.contains?.(active))) active.blur?.()
+  },
 
   // Modal dialog ops (issue #365): HTMLDialogElement#showModal / #close.
   // ACTOR-ONLY like focus (BROADCAST_REFUSED_OPS server-side).
@@ -1429,8 +1469,18 @@ function previewFile(input, args, resolveTargets) {
   // valid: true (issue #382): an input the app marked invalid (setCustomValidity,
   // required) previews as empty. validity.valid, not checkValidity(): no
   // `invalid` event fired into the app's own listeners.
-  const files = args.valid === true && input.validity?.valid === false ? [] : (input.files ?? [])
-  const file = [...files].find((f) => typeof f?.type === "string" && f.type.startsWith("image/"))
+  const files = [...(args.valid === true && input.validity?.valid === false ? [] : (input.files ?? []))]
+  const accepts = previewAccepts(input, args.accept)
+  const listed = files.filter((f) => typeof f?.type === "string" && accepts(f))
+  // Only an image is painted: a listed PDF clears the preview, unrefused.
+  let file = listed.find((f) => f.type.startsWith("image/"))
+  // A refused file (issue #391) clears like an empty pick and says why. The
+  // input keeps its files and its validity: the page owns the reset. Size is
+  // read BEFORE an object URL exists, so an over-size file never gets one.
+  let reason = files.length > 0 && listed.length === 0 ? "type" : null
+  if (file && Number.isInteger(args.max_bytes) && file.size > args.max_bytes) reason = "size"
+  const refused = reason === "size" ? file : files[0]
+  if (reason) file = null
   forgetPreview(img)
   if (file) {
     const url = URL.createObjectURL(file)
@@ -1439,8 +1489,40 @@ function previewFile(input, args, resolveTargets) {
     watchPreviews()
   } else img.removeAttribute("src")
   resetImage(img)
-  if (args.name == null) return
-  for (const node of resolveTargets({ ...args, to: args.name })) node.textContent = file ? file.name : ""
+  if (args.wrap != null) {
+    const wraps = resolveTargets({ ...args, to: args.wrap })
+    if (wraps.length === 0) warnPreview(`wrap: ${JSON.stringify(args.wrap)} is not on the page`)
+    for (const wrap of wraps) file ? showWrap(wrap) : hideWrap(wrap)
+  }
+  if (args.name != null) {
+    for (const node of resolveTargets({ ...args, to: args.name })) node.textContent = file ? file.name : ""
+  }
+  if (reason) {
+    input.dispatchEvent(new CustomEvent("reactive:file-rejected", { bubbles: true, detail: { reason, file: refused } }))
+  }
+}
+
+// Which files the page takes: an image by default. accept: true reads the
+// input's own accept attribute; a string is that list for this op. A token is
+// an extension (".png"), a MIME type or a type/* wildcard, the browser's own
+// accept grammar. An absent or empty list keeps the image rule.
+function previewAccepts(input, accept) {
+  const tokens = String((accept === true ? input.getAttribute("accept") : typeof accept === "string" && accept) || "")
+    .toLowerCase()
+    .split(",")
+    .map((token) => token.trim())
+    .filter(Boolean)
+  if (tokens.length === 0) return (f) => f.type.startsWith("image/")
+  return (f) => {
+    const type = f.type.toLowerCase()
+    return tokens.some((token) =>
+      token[0] === "."
+        ? String(f.name).toLowerCase().endsWith(token)
+        : token.endsWith("/*")
+          ? type.startsWith(token.slice(0, -1))
+          : type === token,
+    )
+  }
 }
 
 function warnPreview(why) {
@@ -1939,6 +2021,30 @@ function deferNeeded(root) {
   )
 }
 
+// Issue #410: a tokenless CLIENT-ONLY root (a ClientBindings component: filter,
+// show, on_client) has no action of its own. It is transparent to server round
+// trips: a server trigger inside it dispatches on the nearest token-bearing root
+// above, and that root's #collectFields looks through it. A lazy or deferred
+// shell is tokenless by design and is NOT client-only.
+const AWAKE_ROOT = '[data-controller~="reactive"]'
+const ANY_ROOT = '[data-controller~="reactive"],[data-reactive-dormant~="reactive"]'
+
+const clientOnlyRoot = (root) => root.getAttribute?.("data-reactive-token-value") == null && !deferNeeded(root)
+
+// The first `selector` root at or above `from` that is not client-only, or
+// `stop` when the walk reaches it first, or null.
+function serverRoot(from, selector, stop) {
+  let root = from?.closest?.(selector)
+  while (root && root !== stop && clientOnlyRoot(root)) root = root.parentElement?.closest?.(selector)
+  return root ?? null
+}
+
+// Connected controllers by root element, so a client-only root can hand a
+// dispatch to the server root above it. A dispatch for a root that has not
+// connected yet (a dormant root being woken) waits here until it does.
+const rootControllers = new WeakMap()
+const heldForwards = new WeakMap()
+
 // Dirty tracking with its navigate-away guard, and the paste-trigger gate:
 // the root or anything inside it carries one of the two markers. (A nested
 // root's marker loads the module for its parent too; the module then checks
@@ -1988,6 +2094,11 @@ function presenceNeeded(root) {
   return root.getAttribute?.("data-reactive-presence") != null
 }
 
+// Countdowns (issue #400): the root is, or holds, a reactive_countdown.
+function countdownNeeded(root) {
+  return Boolean(root.matches?.("[data-reactive-countdown]") || root.querySelector?.("[data-reactive-countdown]"))
+}
+
 const PRODUCTION_FEATURES = [
   // (Its `waiting` hook is the opt-in entry's: core.js.) The draft restore
   // writes what a request reads, so it gates.
@@ -2003,6 +2114,8 @@ const PRODUCTION_FEATURES = [
   // Its announce is a request of its own; nothing it does at connect is read
   // by another request: it never gates.
   ["presence", [presenceNeeded, null]],
+  // A countdown writes only its own text and visibility: it never gates.
+  ["countdown", [countdownNeeded, null]],
   [
     // Stream effects and dismissing flashes are document-level: the module
     // has no connect. A root that DECLARES an effect only gets it fetched
@@ -2166,7 +2279,7 @@ function featureTimeoutMs() {
 export function reactiveFeatureNames() {
   return __SPLIT__
     ? [...FEATURES.keys()]
-    : ["persist", "defer", "form", "bindings", "compute", "sortable", "presence", "effects", "hints", "devtools"]
+    : ["persist", "defer", "form", "bindings", "compute", "sortable", "presence", "countdown", "effects", "hints", "devtools"]
 }
 
 export function __setReactiveFeatureForTest(name, needs, load, waiting, gates) {
@@ -2190,6 +2303,7 @@ export function __loadReactiveFeatureForTest(name) {
     compute: computeFeature,
     sortable: sortableFeature,
     presence: presenceFeature,
+    countdown: countdownFeature,
     effects: effectsFeature,
     hints: hintsFeature,
     devtools: devtoolsFeature,
@@ -2244,6 +2358,7 @@ const BINDINGS = 8
 const COMPUTE = 16
 const SORTABLE = 32
 const PRESENCE = 64
+const COUNTDOWN = 128
 
 // The default entry's features are part of this file: install them now, as
 // the opt-in entry does when one arrives.
@@ -2269,6 +2384,10 @@ const WINDOW_EARLY_TTL_MS = 1500
 // which a replay built from its trigger element's document carries).
 const isWindow = (target) => target != null && (target === globalThis.window || target.window === target)
 
+// Issue #393: the key on()'s dispatch debounce uses in #debounceTimers. An
+// on_client record keys on its JSON, which starts with "{", so never this.
+const DISPATCH_WAIT_KEY = "dispatch"
+
 function earlyState() {
   globalThis[EARLY_KEY] ??= { queue: [], connected: new WeakSet() }
   return globalThis[EARLY_KEY]
@@ -2425,8 +2544,8 @@ export default class extends Controller {
   }
 
   #tokenCache // freshest token, threaded synchronously across queued requests
-  #debounceTimers = new Map() // trigger element -> { timer, flush } pending dispatch
-  #throttleTimers = new Map() // trigger element -> Map(action -> suppression timer)
+  #debounceTimers = new Map() // trigger element -> Map(key -> { timer, flush }) pending run
+  #throttleTimers = new Map() // trigger element -> Map(action or record key -> suppression timer)
   #actionPathCache // page-stable action path, resolved once per controller
   #timeoutMsCache // page-stable request timeout (ms), resolved once per controller (issue #101)
   #tokenRegexCache // { id, token, self } — #extractToken's two per-id RegExps, rebuilt on id change (issue #118)
@@ -2465,7 +2584,7 @@ export default class extends Controller {
   #featureTurns = new Map() // name -> settles once that feature has had its turn to connect
   #featureEpoch = 0
   #featureHandle // the `core` handle features receive, built on first use
-  // The default entry (issue #305): one bit per feature, PERSIST … PRESENCE —
+  // The default entry (issue #305): one bit per feature, PERSIST … COUNTDOWN —
   // asked for (its marker read true) and connected on this connection.
   #featuresAsked = 0
   #featuresOn = 0
@@ -2479,6 +2598,7 @@ export default class extends Controller {
     // queueing them NOW — a connect-time seed below (a compute output write)
     // dispatches real input events. The queue itself drains at the very end.
     earlyState().connected.add(this.element)
+    rootControllers.set(this.element, this)
 
     // Root-id guard (issue #48). The token round trip assumes the reactive root
     // element's id == component.id: the server targets component.id and the client
@@ -2568,6 +2688,7 @@ export default class extends Controller {
       this.#connectFeatureNow(COMPUTE, "compute", computeNeeded, (core) => computeFeature.connect(this, core, morphed))
       this.#connectFeatureNow(SORTABLE, "sortable", sortableNeeded, (core) => sortableFeature.connect(this, core))
       this.#connectFeatureNow(PRESENCE, "presence", presenceNeeded, (core) => presenceFeature.connect(this, core))
+      this.#connectFeatureNow(COUNTDOWN, "countdown", countdownNeeded, (core) => countdownFeature.connect(this, core))
     }
   }
 
@@ -2606,6 +2727,7 @@ export default class extends Controller {
       if (on & COMPUTE) this.#disconnectFeatureNow("compute", () => computeFeature.disconnect(this, core))
       if (on & SORTABLE) this.#disconnectFeatureNow("sortable", () => sortableFeature.disconnect(this, core))
       if (on & PRESENCE) this.#disconnectFeatureNow("presence", () => presenceFeature.disconnect(this, core))
+      if (on & COUNTDOWN) this.#disconnectFeatureNow("countdown", () => countdownFeature.disconnect(this, core))
     }
   }
 
@@ -2801,6 +2923,8 @@ export default class extends Controller {
       served: serverText,
       // Copy one <img> onto another (issue #373): the reactive_media binding.
       copyMedia,
+      // set_value's write (issue #374): reactive_show clear: (issue #394).
+      setValue: setFieldValue,
       // The confirm gate, as dispatch() runs it: the resolver inside the chain
       // (a synchronous throw is a cancel), never a rejection out.
       confirm: (message, context) =>
@@ -2900,6 +3024,14 @@ export default class extends Controller {
       )
     }
     this.#drainEarly()
+    // Issue #410: dispatches a client-only root inside handed over before this
+    // root connected (a dormant root woken by that very trigger).
+    // currentTarget is null once propagation ended: pin the trigger back on.
+    for (const [event, target] of heldForwards.get(this.element) ?? []) {
+      if (event.currentTarget !== target) Object.defineProperty(event, "currentTarget", { value: target, configurable: true })
+      this.dispatch(event)
+    }
+    heldForwards.delete(this.element)
   }
 
   // The trigger elements whose :once descriptor THIS connection replayed —
@@ -3000,6 +3132,7 @@ export default class extends Controller {
     }
     // Early triggers (issue #273): a disconnected root records again.
     earlyState().connected.delete(this.element)
+    if (rootControllers.get(this.element) === this) rootControllers.delete(this.element)
     this.element.removeAttribute?.("data-reactive-connected")
     // A spent :once replay is remembered per element so a morph REPLY (root
     // still connected) cannot re-arm it. A disconnect drops Stimulus's own
@@ -3017,6 +3150,12 @@ export default class extends Controller {
   // a per-controller promise makes each dispatch wait for the previous one, so
   // it always uses the freshest token.
   dispatch(event) {
+    // Issue #410: a client-only root has no action of its own — a server
+    // trigger inside it belongs to the token-bearing root above. FIRST, so that
+    // root runs every check below with its own element.
+    if (event.params?.action && event.params.action !== LAZY_MATERIALIZE_ACTION && this.#clientOnly()) {
+      return this.#forwardToServerRoot(event)
+    }
     // A shortcut (issue #357) that is the other platform's twin, or pressed
     // in a field the user is typing in, is a complete no-op: the native
     // default (text undo) proceeds and nothing is announced. Checked FIRST: a
@@ -3181,6 +3320,37 @@ export default class extends Controller {
   }
 
 
+  // A tokenless client-only root (issue #410). tokenValue is the Stimulus view
+  // of data-reactive-token-value; the attribute check also rules out a shell.
+  #clientOnly() {
+    return !this.tokenValue && clientOnlyRoot(this.element)
+  }
+
+  // Hand a server trigger to the nearest token-bearing root above (issue #410).
+  // A dormant one is woken (as early.js wakes a root on its own trigger) and
+  // runs the dispatch when it connects. With no such root nothing is sent.
+  #forwardToServerRoot(event) {
+    const root = serverRoot(this.element.parentElement, ANY_ROOT)
+    if (!root) {
+      if (this.element.closest?.('[data-reactive-verbose="true"], [data-reactive-debug="true"]'))
+        console.warn(`[phlex-reactive] "${event.params.action}": no token on this root or above, nothing sent`)
+      return
+    }
+    const controller = rootControllers.get(root)
+    if (controller) return controller.dispatch(event)
+    // Held past this event's dispatch: cancel its native default NOW, by
+    // dispatch()'s own rule, or a submit/link would act before the request.
+    const { shortcut, window: windowBound, optimistic } = event.params
+    const target = event.currentTarget ?? event.target
+    if ((shortcut != null || !windowBound) && !this.#keepsNativeToggle(optimistic, target)) event.preventDefault()
+    heldForwards.set(root, [...(heldForwards.get(root) ?? []), [event, target]])
+    const data = root.dataset
+    if (data.reactiveDormant) {
+      data.controller = `${data.controller ?? ""} ${data.reactiveDormant}`.trim()
+      delete data.reactiveDormant
+    }
+  }
+
   // CLIENT-ONLY trigger entry point (issue #95) — the zero-round-trip sibling
   // of dispatch(). Wired by on_client: applies the declared op chain
   // (data-reactive-ops-param, built by Phlex::Reactive::JS) locally. NO token,
@@ -3233,13 +3403,21 @@ export default class extends Controller {
       if (record.shortcut != null && !shortcutApplies(record.shortcut, event, this.application?.schema?.keyMappings))
         continue
       if (onceBindingSpent(this, event, record)) continue
-      this.#runBinding(record.legacy ? { ...params, ops: record.ops } : record, event, trigger)
+      // A legacy attr reads its flags element-wide — but never a mix-ed on()'s
+      // debounce/throttle params (issue #393): those belong to the dispatch.
+      this.#runBinding(
+        record.legacy ? { ...params, ops: record.ops, debounce: undefined, throttle: undefined } : record,
+        event,
+        trigger,
+        records.indexOf(record),
+      )
     }
   }
 
   // One on_client binding (issue #95): its outside guard, preventDefault rule,
   // confirm gate, then its ops — every flag read from the binding itself.
-  #runBinding({ ops, confirm, confirmWhen, outside, window: windowBound, shortcut }, event, trigger) {
+  #runBinding(record, event, trigger, ordinal) {
+    const { ops, confirm, confirmWhen, outside, window: windowBound, shortcut } = record
     // Outside guard FIRST — identical semantics to dispatch() (issue #80): an
     // outside: trigger is a COMPLETE no-op for events inside this root, before
     // preventDefault and before any op runs.
@@ -3262,7 +3440,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.#applyOps(this.#parseOps(ops))
+    const apply = this.#waitedOps(record, ordinal, trigger, () => this.#applyOps(this.#parseOps(ops)))
     if (!message) return apply()
     if (message instanceof Promise) {
       return message.then((resolved) => (resolved ? this.#confirmThen(resolved, trigger, apply) : apply()))
@@ -3270,6 +3448,20 @@ export default class extends Controller {
     this.#confirmThen(message, trigger, apply)
   }
 
+  // Issue #393: an on_client record's debounce:/throttle: — on()'s timers
+  // (#debounce trailing, #throttle leading), keyed on the trigger + the
+  // record's ordinal + JSON (two identical mix-ed records keep their own
+  // timers), so disconnect clears them with the dispatch ones. The wait sits
+  // after the outside guard, preventDefault and confirm, as on()'s does.
+  #waitedOps(record, ordinal, trigger, run) {
+    const debounce = Number(record.debounce) || 0
+    const throttle = Number(record.throttle) || 0
+    if (debounce <= 0 && throttle <= 0) return run
+    const key = JSON.stringify([ordinal, record])
+    if (debounce > 0) return () => this.#debounce(trigger, key, debounce, run)
+    return () => this.#throttle(trigger, key, throttle, run)
+  }
+
   // Client-side compute (issue #104) is the compute feature's (issue #275,
   // features/compute.js). This is the method its descriptor names
   // (input->reactive#recompute), so it stays. While the module is on its way
@@ -3554,30 +3746,45 @@ export default class extends Controller {
   // Also flush immediately on blur so leaving the field never drops the last
   // edit (a long debounce shouldn't swallow a value the user tabbed away from).
   #debounceDispatch(target, ms, action, params, optimistic, busy) {
-    this.#clearDebounce(target)
+    this.#debounce(target, DISPATCH_WAIT_KEY, ms, () => this.#enqueue(action, params, optimistic, target, busy))
+  }
+
+  // The one trailing-edge timer on() and on_client (issue #393) share. Timers
+  // are keyed on target + key: on()'s dispatch uses DISPATCH_WAIT_KEY, an
+  // on_client record its ordinal + JSON (it starts with "["), so an on() debounce and an
+  // on_client debounce on one input never cancel each other. A window-bound
+  // trigger gets no blur flush: a window blur is a tab switch, not an edit.
+  #debounce(target, key, ms, run) {
+    this.#clearDebounce(target, key)
 
     const flush = () => {
-      this.#clearDebounce(target)
-      this.#enqueue(action, params, optimistic, target, busy)
+      this.#clearDebounce(target, key)
+      run()
     }
     const timer = setTimeout(flush, ms)
-    target?.addEventListener?.("blur", flush, { once: true })
-    this.#debounceTimers.set(target, { timer, flush })
+    if (!isWindow(target)) target?.addEventListener?.("blur", flush, { once: true })
+    let pending = this.#debounceTimers.get(target)
+    if (!pending) this.#debounceTimers.set(target, (pending = new Map()))
+    pending.set(key, { timer, flush })
   }
 
-  #clearDebounce(target) {
-    const pending = this.#debounceTimers.get(target)
+  #clearDebounce(target, key) {
+    const byKey = this.#debounceTimers.get(target)
+    const pending = byKey?.get(key)
     if (!pending) return
     clearTimeout(pending.timer)
     target?.removeEventListener?.("blur", pending.flush)
-    this.#debounceTimers.delete(target)
+    byKey.delete(key)
+    if (byKey.size === 0) this.#debounceTimers.delete(target)
   }
 
   // Clear every pending debounce timer (used on disconnect). Reuses
   // #clearDebounce so all timer/listener teardown stays in one place. Snapshot
-  // the keys first — #clearDebounce mutates the map as it goes.
+  // the entries first — #clearDebounce mutates the maps as it goes.
   #clearAllDebounces() {
-    for (const target of [...this.#debounceTimers.keys()]) this.#clearDebounce(target)
+    for (const [target, byKey] of [...this.#debounceTimers]) {
+      for (const key of [...byKey.keys()]) this.#clearDebounce(target, key)
+    }
   }
 
   // Leading-edge throttle (issue #80), mirroring #debounceDispatch: the FIRST
@@ -3587,16 +3794,22 @@ export default class extends Controller {
   // events all share event.target === document, so two window-bound triggers
   // on one component would otherwise collide on one timer.
   #throttleDispatch(target, ms, action, params, optimistic, busy) {
+    return this.#throttle(target, action, ms, () => this.#enqueue(action, params, optimistic, target, busy))
+  }
+
+  // The leading-edge window on() and on_client (issue #393) share; an
+  // on_client record keys on its ordinal + JSON, which no action name can equal.
+  #throttle(target, key, ms, run) {
     const timers = this.#throttleTimers.get(target) ?? new Map()
-    if (timers.has(action)) return // inside the window — suppress
+    if (timers.has(key)) return // inside the window — suppress
 
     const timer = setTimeout(() => {
-      timers.delete(action)
+      timers.delete(key)
       if (timers.size === 0) this.#throttleTimers.delete(target)
     }, ms)
-    timers.set(action, timer)
+    timers.set(key, timer)
     this.#throttleTimers.set(target, timers)
-    return this.#enqueue(action, params, optimistic, target, busy) // leading edge: fire NOW
+    return run() // leading edge: fire NOW
   }
 
   // Clear every throttle suppression timer (used on disconnect, alongside
@@ -4076,6 +4289,17 @@ export default class extends Controller {
     return (el) => this.#ownsField(el)
   }
 
+  // #ownershipFilter for SERVER params (issue #410): nested client-only roots
+  // are transparent, so a control under one is this root's when the first
+  // token-bearing root above it is this.element. A nested token-bearing root
+  // keeps its own fields (issue #15). Bindings, computes and listnav keep the
+  // strict nearest-root #ownershipFilter.
+  #serverFieldFilter() {
+    const nested = this.element.querySelectorAll(AWAKE_ROOT)
+    if (nested.length === 0 || [...nested].every(clientOnlyRoot)) return () => true
+    return (el) => serverRoot(el, AWAKE_ROOT, this.element) === this.element
+  }
+
   // 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
@@ -4087,7 +4311,7 @@ export default class extends Controller {
   #collectFields() {
     const fields = {}
     const files = []
-    const owns = this.#ownershipFilter() // compute ONCE per dispatch (issue #117)
+    const owns = this.#serverFieldFilter() // compute ONCE per dispatch (issue #117)
     const controls = []
     this.element.querySelectorAll("input[name], select[name], textarea[name]").forEach((field) => {
       if (!owns(field)) return

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Phlex
+  module Reactive
+    module Component
+      # A server deadline counted down on the client (issue #400).
+      #
+      #   span(**reactive_countdown(until: deadline.iso8601, waiting: "#wait", done: "#done")) { "2:00" }
+      #   div(id: "wait") { "Waiting" }
+      #   div(id: "done", hidden: true) { "Finished" }
+      #
+      # The client paints the time left from until: and Date.now at connect and
+      # once a second ("1:30": unpadded minutes, a colon, padded seconds — the
+      # only format, :ms), as textContent only. A tab that wakes late jumps to
+      # the real time left. At zero, or with until: already past on connect, the
+      # text is "0:00", data-reactive-countdown-state is "done", waiting: hides,
+      # done: shows (CSS selectors inside the root) and the element dispatches
+      # reactive:countdown-done once; the timer stops. A morph that keeps until:
+      # does not dispatch again; one that changes it counts down again. No
+      # request and no frame reload: the event is the hook.
+      #
+      # The countdown's content is its text, so waiting: and done: name nodes
+      # beside it, never inside it: a reactive root that is itself the
+      # countdown has nowhere to put them.
+      #
+      # The server renders the initial text and visibility, so the page reads
+      # with JavaScript off. until: is an ISO8601 date-time WITH a zone (Z or an
+      # offset), or a Time, which is written as one: a zoneless string would
+      # read as the browser's local time.
+      module CountdownBinding
+        ISO8601_WITH_ZONE = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+
+        # `until` is a keyword: the value is read off the binding.
+        def reactive_countdown(until:, format: :ms, waiting: nil, done: nil, **attrs)
+          wire = { "until" => countdown_until!(binding.local_variable_get(:until)), "format" => countdown_format!(format) }
+          wire["waiting"] = countdown_selector!(:waiting, waiting) unless waiting.nil?
+          wire["done"] = countdown_selector!(:done, done) unless done.nil?
+          mix({ data: { reactive_countdown: wire.to_json } }, attrs)
+        end
+
+        private
+
+        def countdown_until!(value)
+          value = value.utc.iso8601(value.subsec.zero? ? 0 : 3) if value.is_a?(Time) || value.respond_to?(:time_zone)
+          return value if countdown_iso8601?(value)
+
+          raise ArgumentError, "reactive_countdown until: must be an ISO8601 date-time with a zone " \
+                               "(e.g. \"2026-10-14T12:02:00Z\") or a Time, got #{value.inspect}"
+        end
+
+        # The shape (a zone is required), then a real date (no month 13).
+        def countdown_iso8601?(value)
+          value.is_a?(String) && value.match?(ISO8601_WITH_ZONE) && Time.iso8601(value) && true
+        rescue ::ArgumentError
+          false
+        end
+
+        def countdown_format!(format)
+          return "ms" if format == :ms
+
+          raise ArgumentError, "reactive_countdown format: must be :ms (the only format), got #{format.inspect}"
+        end
+
+        # A selector the client passes to querySelector inside the root.
+        def countdown_selector!(name, selector)
+          if selector == JS::ROOT_SENTINEL
+            raise ArgumentError,
+              "reactive_countdown #{name}: #{selector} names the whole root — pass the selector of a node inside it"
+          end
+          return selector if selector.is_a?(String) && !selector.strip.empty?
+
+          raise ArgumentError,
+            "reactive_countdown #{name}: must be a CSS selector (e.g. \"##{name}\"), got #{selector.inspect}"
+        end
+      end
+    end
+  end
+end