phlex-reactive 0.15.2 → 0.15.4

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
@@ -419,6 +420,167 @@ export function __resetReactiveKeepForTest() {
   keepRegistered = false
 }
 
+// --- An image fallback that recovers (issue #383) ---------------------------
+// data-reactive-image-fallback='{"hide":true,"alt":"#name"}' on an <img>. On
+// `error` it gets data-reactive-image-state="error" (plus `hidden` with hide,
+// and its alt shown in the `alt` node of its own reactive root); on `load`,
+// "loaded". A later src clears the error: copy_media and preview_file reset
+// it as they write (resetImage), any src that loads clears it on `load`, and
+// a morph that changes the src lets the browser try again. A morph that keeps
+// the src puts the state back. An error with no src is not an error (a
+// removed or emptied src). One document listener, capture phase (neither
+// event bubbles); nothing per root at connect.
+const IMAGE_FALLBACK = "data-reactive-image-fallback"
+const IMAGE_STATE = "data-reactive-image-state"
+// Marks the `hidden` the fallback set, so a reset removes only that one. On
+// the element, not in a WeakSet: a Turbo snapshot restores a NEW node.
+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)
+  if (raw == null) return null
+  try {
+    return JSON.parse(raw) || {}
+  } catch {
+    return {}
+  }
+}
+
+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 imageRootNode(img, selector) {
+  if (typeof selector !== "string" || !selector) return null
+  try {
+    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") ?? ""
+      node.hidden = false
+    }
+  } else resetImage(img, wire)
+  img.setAttribute(IMAGE_STATE, value)
+}
+
+// Undo what an error did — only what it did: `hidden` stays when the author
+// set it. Called by copy_media and preview_file when they change the src.
+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
+  }
+  img.removeAttribute(IMAGE_STATE)
+  img.removeAttribute(IMAGE_HIDDEN)
+}
+
+function onImageEvent(event) {
+  const img = event.target
+  const wire = imageFallback(img)
+  if (!wire) return
+  if (event.type === "load") setImageState(img, wire, "loaded")
+  else if (hasImageSrc(img)) setImageState(img, wire, "error")
+  else resetImage(img, wire)
+}
+
+export function registerReactiveImageFallback() {
+  if (imageFallbackListeners) return
+  if (typeof document === "undefined" || typeof document.addEventListener !== "function") return
+  // A morph that keeps the src keeps the state: the render carries none, and
+  // the browser loads nothing new to tell us again. Put it back once the
+  // whole morph is done, so a later-morphed alt node is shown again too.
+  const kept = new WeakMap()
+  imageFallbackListeners = {
+    error: onImageEvent,
+    load: onImageEvent,
+    "turbo:before-morph-element": (event) => {
+      const img = event.target
+      const next = event.detail?.newElement
+      const value = img?.getAttribute?.(IMAGE_STATE)
+      if (value == null || !next || !imageFallback(img)) return
+      const same = (name) => img.getAttribute(name) === next.getAttribute?.(name)
+      if (same("src") && same("srcset")) kept.set(img, value)
+    },
+    "turbo:morph-element": (event) => {
+      const img = event.target
+      const value = kept.get(img)
+      if (value === undefined) return
+      kept.delete(img)
+      queueMicrotask(() => {
+        const wire = imageFallback(img)
+        if (wire) setImageState(img, wire, value)
+      })
+    },
+  }
+  for (const [name, fn] of Object.entries(imageFallbackListeners)) document.addEventListener(name, fn, true)
+  // An image that finished before this ran (a cached 404) fired its event
+  // unheard: read it off the element once. naturalWidth 0 is also a loaded
+  // SVG with only a viewBox, so decode() decides (it rejects a broken image).
+  for (const img of document.querySelectorAll?.(`img[${IMAGE_FALLBACK}]`) ?? []) {
+    if (!img.complete || !hasImageSrc(img)) continue
+    // A decode() that settles after the src changed decoded the OLD one: ignore it.
+    const was = `${img.getAttribute("src")} ${img.getAttribute("srcset")}`
+    const mark = (value) => `${img.getAttribute("src")} ${img.getAttribute("srcset")}` === was && setImageState(img, imageFallback(img) ?? {}, value)
+    if (img.naturalWidth > 0) mark("loaded")
+    else if (typeof img.decode === "function") img.decode().then(() => mark("loaded"), () => mark("error"))
+    else mark("error")
+  }
+}
+
+export function __resetReactiveImageFallbackForTest() {
+  for (const [name, fn] of Object.entries(imageFallbackListeners ?? {})) document.removeEventListener(name, fn, true)
+  imageFallbackListeners = null
+}
+
 // For the opt-in entry: what to do with a stream before its render — hold it
 // for a module the incoming content needs. `handle(event, effects)` gets the
 // loaded effects module (or undefined) and wraps the stream with it itself.
@@ -860,6 +1022,7 @@ export function registerReactiveActions() {
   registerReactiveMorphFocus()
   registerReactiveModals()
   registerReactiveKeep()
+  registerReactiveImageFallback()
   registerReactivePlaintext()
   registerReactiveOffline()
   registerReactiveDev()
@@ -1117,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).
@@ -1296,7 +1466,21 @@ function previewFile(input, args, resolveTargets) {
   if (img?.tagName !== "IMG") {
     return warnPreview(`paints an <img>, and ${JSON.stringify(args.into)} is ${img ? `a <${img.localName}>` : "not on the page"}`)
   }
-  const file = [...(input.files ?? [])].find((f) => typeof f?.type === "string" && f.type.startsWith("image/"))
+  // 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 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)
@@ -1304,8 +1488,41 @@ function previewFile(input, args, resolveTargets) {
     img.setAttribute("src", url)
     watchPreviews()
   } else img.removeAttribute("src")
-  if (args.name == null) return
-  for (const node of resolveTargets({ ...args, to: args.name })) node.textContent = file ? file.name : ""
+  resetImage(img)
+  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) {
@@ -1404,7 +1621,9 @@ function guardAttr(name) {
 // copy_media op and the reactive_media binding (the bindings feature reaches it
 // through the core handle). Only an <img> target is written, so an iframe,
 // script, object, embed or frame never receives a src from here. A source that
-// is missing, not an <img> or has no src clears the target. Each attribute is
+// is missing or not an <img> clears the target. An <img> source without src is
+// a hit with no image (issue #381): the target loses src and srcset but takes
+// the alt, so a known entry without a logo keeps its name. Each attribute is
 // written only when it changes, so the same URL twice does not reload. Returns
 // the alt copied, false when it cleared, or null when the target was skipped.
 function copyMedia(target, source) {
@@ -1412,17 +1631,19 @@ function copyMedia(target, source) {
     console.warn(`[phlex-reactive] copy_media targets an <img>, not <${target?.localName}> — skipped`)
     return null
   }
-  const src = source?.localName === "img" ? source.getAttribute("src") : null
-  const pick = (name) => (src ? source.getAttribute(name) : null)
+  const img = source?.localName === "img" ? source : null
+  const src = img?.getAttribute("src")
+  let changed = false
   for (const name of ["srcset", "src"]) {
-    const value = pick(name)
+    const value = src ? img.getAttribute(name) : null
     if (value == null) {
-      if (target.hasAttribute(name)) target.removeAttribute(name)
-    } else if (target.getAttribute(name) !== value) target.setAttribute(name, value)
+      if (target.hasAttribute(name)) changed = target.removeAttribute(name) ?? true
+    } else if (target.getAttribute(name) !== value) changed = target.setAttribute(name, value) ?? true
   }
-  const alt = pick("alt") ?? ""
+  if (changed) resetImage(target)
+  const alt = img?.getAttribute("alt") ?? ""
   if (target.getAttribute("alt") !== alt) target.setAttribute("alt", alt)
-  return src ? alt : false
+  return img ? alt : false
 }
 
 // The first focusable descendant of `el`, in document order — the natural
@@ -1849,6 +2070,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.
@@ -1864,6 +2090,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
@@ -2027,7 +2255,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) {
@@ -2051,6 +2279,7 @@ export function __loadReactiveFeatureForTest(name) {
     compute: computeFeature,
     sortable: sortableFeature,
     presence: presenceFeature,
+    countdown: countdownFeature,
     effects: effectsFeature,
     hints: hintsFeature,
     devtools: devtoolsFeature,
@@ -2105,6 +2334,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.
@@ -2130,6 +2360,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]
@@ -2286,8 +2520,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)
@@ -2326,7 +2560,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
@@ -2429,6 +2663,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))
     }
   }
 
@@ -2467,6 +2702,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))
     }
   }
 
@@ -2662,6 +2898,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) =>
@@ -3094,13 +3332,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.
@@ -3123,7 +3369,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()))
@@ -3131,6 +3377,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
@@ -3415,30 +3675,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
@@ -3448,16 +3723,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

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