phlex-reactive 0.11.7 → 0.12.1

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

@@ -490,6 +490,284 @@ export function __resetReactiveDismissForTest() {
   dismissRegistered = false
 }
 
+// Reactive effects (issue #215): animate ENTER (append/prepend), EXIT (remove)
+// and UPDATE (replace/update, plain or morph) when a <turbo-stream> renders.
+// Document-level and render-wrapping like the dismiss hook above, so ONE
+// interceptor covers both delivery paths (a reply and a broadcast). Strictly
+// data-driven and default-deny: the per-call data-reactive-effect on the
+// stream element wins ("off" suppresses), else the carrier element's
+// data-reactive-effect-<hook> — the DOM target for exit/update, the INCOMING
+// template root for enter. No attribute → no work; unknown names and
+// malformed legs warn + skip (a newer or forged attr must never break the
+// page). prefers-reduced-motion disables everything (the shipped CSS is also
+// media-wrapped — defense in depth).
+//
+// Timing:
+//   * exit — the animation runs BEFORE Turbo's render (the removal), awaited
+//     via animationend/transitionend with a timeout fallback; a ZERO computed
+//     duration (no effects CSS loaded, reduced-motion CSS gate) skips the wait
+//     entirely, so a missing stylesheet can never freeze a removal.
+//   * enter/update — Turbo renders first, then the effect class is applied to
+//     the inserted/updated element(s) and removed on settle (fire-and-forget).
+//     Re-applying an update effect restarts it (class off → reflow → on).
+//
+// A named effect maps to the shipped CSS class reactive-fx--<name>-<hook>
+// (app/assets/stylesheets/phlex/reactive/effects.css); "random" picks a
+// built-in per application; a "["-prefixed value is a custom
+// [during, from, to] class-legs triple (the #96/#186 vocabulary), run with
+// runTransition's add → frame → swap → settle choreography.
+const EFFECT_HOOKS = Object.freeze({
+  append: "enter",
+  prepend: "enter",
+  replace: "update",
+  update: "update",
+  remove: "exit",
+})
+const EFFECT_BUILT_INS = Object.freeze(["fade", "slide", "scale", "highlight", "shake"])
+// Marks an incoming template root so the post-render scan finds the inserted
+// CLONE (Turbo clones template content on render — attrs ride the clone).
+const EFFECT_PENDING_ATTR = "data-reactive-fx-pending"
+// The hard ceiling on any effect wait — an exit's removal is delayed at most
+// this long even if animationend/transitionend never fire.
+const EFFECT_SETTLE_FALLBACK_MS = 1000
+
+let effectsRegistered = false
+export function registerReactiveEffects() {
+  if (effectsRegistered) return
+  if (typeof document === "undefined" || typeof document.addEventListener !== "function") return
+  effectsRegistered = true
+  document.addEventListener("turbo:before-stream-render", wrapStreamRenderForEffects)
+}
+
+export function __resetReactiveEffectsForTest() {
+  effectsRegistered = false
+}
+
+// Wrap event.detail.render (the dismiss-hook pattern) when this stream both
+// maps to a hook AND resolves to an effect. Resolution happens HERE, before
+// the render, because exit must read the target while it is still in the DOM
+// and enter must read (and mark) the template content before Turbo clones it.
+function wrapStreamRenderForEffects(event) {
+  const detail = event.detail
+  const original = detail?.render
+  if (typeof original !== "function" || original.__reactiveEffectsWrapped) return
+  const streamEl = detail?.newStream ?? event.target
+  const hook = EFFECT_HOOKS[streamEl?.getAttribute?.("action")]
+  if (!hook || effectsReducedMotion()) return
+  const effect = resolveStreamEffect(streamEl, hook)
+  if (!effect) return
+
+  const wrapped =
+    hook === "exit"
+      ? async (el) => {
+          await runExitEffect(effectTarget(streamEl), effect)
+          await original(el)
+        }
+      : async (el) => {
+          const container = hook === "enter" ? markIncomingRoots(streamEl) : null
+          await original(el)
+          if (hook === "enter") animateMarkedRoots(container, effect)
+          else runEnterOrUpdateEffect(effectTarget(streamEl), effect)
+        }
+  wrapped.__reactiveEffectsWrapped = true
+  detail.render = wrapped
+}
+
+// The effect for this stream: per-call data-reactive-effect first ("off" →
+// none), else the carrier's declared data-reactive-effect-<hook>.
+function resolveStreamEffect(streamEl, hook) {
+  const perCall = streamEl.getAttribute?.("data-reactive-effect")
+  if (perCall === "off") return null
+  if (perCall) return parseEffect(perCall, hook)
+  const carrier = hook === "enter" ? incomingEffectRoot(streamEl) : effectTarget(streamEl)
+  const declared = carrier?.getAttribute?.(`data-reactive-effect-${hook}`)
+  return declared ? parseEffect(declared, hook) : null
+}
+
+// The stream's CURRENT DOM target (re-queried at use, so a post-replace call
+// sees the freshly-swapped element). Our builders always emit `target` —
+// multi-`targets` streams are not ours and pass through unanimated.
+function effectTarget(streamEl) {
+  const target = streamEl.getAttribute?.("target")
+  return target ? (document.getElementById?.(target) ?? null) : null
+}
+
+// The incoming content's root element (an append/prepend's arriving
+// component) — the carrier of a declared enter effect.
+function incomingEffectRoot(streamEl) {
+  return streamEl.querySelector?.("template")?.content?.firstElementChild ?? null
+}
+
+// A wire value → an executable effect: { className } for a shipped built-in
+// ("random" picks one per application), { legs } for a custom triple. null +
+// console.warn for anything else (default-deny).
+function parseEffect(value, hook) {
+  if (value.startsWith("[")) {
+    let legs = null
+    try {
+      const parsed = JSON.parse(value)
+      if (Array.isArray(parsed) && parsed.length === 3) legs = parsed.map(String)
+    } catch {
+      // malformed JSON → the shared warn below
+    }
+    if (legs) return { legs }
+    console.warn(`[phlex-reactive] malformed effect legs ${JSON.stringify(value)} — skipped`)
+    return null
+  }
+  const name =
+    value === "random" ? EFFECT_BUILT_INS[Math.floor(Math.random() * EFFECT_BUILT_INS.length)] : value
+  if (!EFFECT_BUILT_INS.includes(name)) {
+    console.warn(`[phlex-reactive] unknown effect ${JSON.stringify(value)} — skipped`)
+    return null
+  }
+  return { className: `reactive-fx--${name}-${hook}` }
+}
+
+function effectsReducedMotion() {
+  try {
+    return typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches
+  } catch {
+    return false
+  }
+}
+
+// Stamp each incoming template root with the pending marker (Turbo's render
+// clones the content, so the marker rides the inserted clone) and return the
+// container the post-render scan searches. Pre-render on purpose.
+function markIncomingRoots(streamEl) {
+  const content = streamEl.querySelector?.("template")?.content
+  if (!content) return null
+  for (const child of Array.from(content.children ?? [])) child.setAttribute?.(EFFECT_PENDING_ATTR, "")
+  return effectTarget(streamEl)
+}
+
+// Post-render: find the just-inserted clones by their marker, unmark, animate.
+function animateMarkedRoots(container, effect) {
+  if (typeof container?.querySelectorAll !== "function") return
+  for (const el of Array.from(container.querySelectorAll(`[${EFFECT_PENDING_ATTR}]`))) {
+    el.removeAttribute(EFFECT_PENDING_ATTR)
+    runEnterOrUpdateEffect(el, effect)
+  }
+}
+
+// EXIT: animate on the still-present element, resolve when settled, and only
+// then does the wrapper run Turbo's removal. Zero computed duration (no
+// effects CSS) resolves immediately — never a dead 1s freeze.
+async function runExitEffect(el, effect) {
+  if (!el?.classList) return
+  if (effect.legs) {
+    await runLegsEffect(el, effect.legs)
+    return
+  }
+  el.classList.add(effect.className)
+  const duration = effectDurationMs(el)
+  if (duration <= 0) {
+    el.classList.remove(effect.className)
+    return
+  }
+  await effectSettled(el, duration)
+  el.classList.remove(effect.className)
+}
+
+// ENTER/UPDATE: fire-and-forget after the render. A re-applied class is
+// removed + reflowed first so rapid successive updates restart the flash; the
+// per-element token keeps an older settle from clearing a newer application.
+function runEnterOrUpdateEffect(el, effect) {
+  if (!el?.classList) return
+  if (effect.legs) {
+    runLegsEffect(el, effect.legs)
+    return
+  }
+  if (el.classList.contains(effect.className)) {
+    el.classList.remove(effect.className)
+    void el.offsetWidth // force a reflow so re-adding restarts the animation
+  }
+  el.classList.add(effect.className)
+  const duration = effectDurationMs(el)
+  if (duration <= 0) {
+    el.classList.remove(effect.className)
+    return
+  }
+  const token = (el.__reactiveFxToken = (el.__reactiveFxToken ?? 0) + 1)
+  effectSettled(el, duration).then(() => {
+    if (el.__reactiveFxToken === token) el.classList.remove(effect.className)
+  })
+}
+
+// Custom class legs — runTransition's choreography (add during+from, swap
+// from→to on the next frame, settle, clean up), promise-shaped so an exit can
+// await it. Class lists are space-separated (the #96/#186 wire).
+//
+// Rapid re-application on the same element RESTARTS, mirroring the named
+// path's token guard: each run takes the per-element token, clears any
+// earlier run's leg classes, and a superseded run stops touching the element
+// the moment a newer run owns it — so a stale settle can never strip classes
+// mid-animation or double-swap the legs. A superseded EXIT run resolves
+// early, which only lets Turbo's removal proceed sooner (never later).
+async function runLegsEffect(el, legs) {
+  const [during, from, to] = legs.map(splitEffectClasses)
+  const token = (el.__reactiveFxToken = (el.__reactiveFxToken ?? 0) + 1)
+  el.classList.remove(...during, ...from, ...to)
+  el.classList.add(...during, ...from)
+  await effectNextFrame()
+  if (el.__reactiveFxToken !== token) return
+  el.classList.remove(...from)
+  el.classList.add(...to)
+  const duration = effectDurationMs(el)
+  if (duration > 0) await effectSettled(el, duration)
+  if (el.__reactiveFxToken !== token) return
+  el.classList.remove(...during, ...to)
+}
+
+function splitEffectClasses(list) {
+  return String(list ?? "")
+    .split(/\s+/)
+    .filter(Boolean)
+}
+
+// The longest computed animation/transition (duration + delay, comma lists
+// included) in ms, capped at the hard fallback. 0 when getComputedStyle is
+// unavailable or nothing animates — callers skip the wait entirely.
+function effectDurationMs(el) {
+  if (typeof getComputedStyle !== "function") return 0
+  try {
+    const style = getComputedStyle(el)
+    const longest = (value) =>
+      String(value ?? "")
+        .split(",")
+        .reduce((max, part) => Math.max(max, parseFloat(part) || 0), 0)
+    const animation = longest(style.animationDuration) + longest(style.animationDelay)
+    const transition = longest(style.transitionDuration) + longest(style.transitionDelay)
+    return Math.min(Math.max(animation, transition) * 1000, EFFECT_SETTLE_FALLBACK_MS)
+  } catch {
+    return 0
+  }
+}
+
+// Resolve on animationend/transitionend — whichever fires first — with a
+// timeout slightly past the computed duration, so a canceled animation (a
+// display:none ancestor, an interrupted transition) can't hang an exit.
+function effectSettled(el, durationMs) {
+  return new Promise((resolve) => {
+    let done = false
+    const settle = () => {
+      if (done) return
+      done = true
+      resolve()
+    }
+    el.addEventListener?.("animationend", settle, { once: true })
+    el.addEventListener?.("transitionend", settle, { once: true })
+    setTimeout(settle, Math.min(durationMs + 50, EFFECT_SETTLE_FALLBACK_MS))
+  })
+}
+
+function effectNextFrame() {
+  return new Promise((resolve) => {
+    if (typeof requestAnimationFrame === "function") requestAnimationFrame(() => resolve())
+    else setTimeout(resolve, 16)
+  })
+}
+
 // Offline CSS hook (issue #101). Mirror data-reactive-offline on
 // document.documentElement from navigator.onLine, kept in sync by the window
 // online/offline events — so an app can dim a save button or show a banner with
@@ -666,6 +944,7 @@ export function registerReactiveActions() {
   registerReactiveJs()
   registerReactiveDefer()
   registerReactiveDismiss()
+  registerReactiveEffects()
   registerReactiveOffline()
   attachLatencyHandle()
 }
@@ -1463,8 +1742,10 @@ export default class extends Controller {
     // so a dismissed/erroring dialog never surfaces as an unhandled rejection AND a
     // genuine bug inside #proceed is NOT silently swallowed. Enqueue ONLY on a
     // truthy resolution — nothing is enqueued, no timer scheduled, otherwise.
+    // The resolver's optional 2nd arg (issue #222) carries the trigger element,
+    // so an override has the same ctx shape here as on nestedRemove ({ el, … }).
     Promise.resolve()
-      .then(() => confirmResolver(message))
+      .then(() => confirmResolver(message, { el: target }))
       .catch(() => false)
       .then((ok) => {
         if (ok) this.#proceed(target, action, params, debounce, throttle, optimistic, busy)
@@ -1479,6 +1760,9 @@ export default class extends Controller {
   // owns state that must survive re-renders).
   runOps(event) {
     const { ops, confirm, confirmWhen, outside, window: windowBound } = event.params
+    // The trigger element on_client was spread onto (issue #222 ctx: { el }),
+    // captured now — currentTarget resets before the confirm resolver's microtask.
+    const trigger = event.currentTarget ?? event.target
 
     // Outside guard FIRST — identical semantics to dispatch() (issue #80): an
     // outside: trigger is a COMPLETE no-op for events inside this root, before
@@ -1510,7 +1794,7 @@ export default class extends Controller {
     // here (the user gesture), NOT in #applyOps: that applier is shared with the
     // server-pushed reactive:js stream action, which must NEVER prompt.
     Promise.resolve()
-      .then(() => confirmResolver(message))
+      .then(() => confirmResolver(message, { el: trigger }))
       .catch(() => false)
       .then((ok) => {
         if (ok) this.#applyOps(this.#parseOps(ops))
@@ -1967,6 +2251,61 @@ export default class extends Controller {
     // inside ANOTHER collection's row (the issue #15 closest-form posture).
     if (row.closest?.('[data-controller~="reactive"]') !== this.element) return
 
+    // Confirm gate (issue #218): reactive_nested_remove(confirm:) emits the SAME
+    // data-reactive-confirm[-when]-param the other triggers do (nestedRemove reads
+    // params via getAttribute, not event.params, so pull them off the trigger),
+    // routed through the SAME #effectiveConfirmMessage + confirmResolver seam. A
+    // static string always shows; a conditional Hash fires only when it matches,
+    // else null. No confirm attr → null → the immediate-remove fast path.
+    const confirm = trigger?.getAttribute?.("data-reactive-confirm-param")
+    const confirmWhen = trigger?.getAttribute?.("data-reactive-confirm-when-param")
+    const rawMessage = this.#effectiveConfirmMessage(confirm, confirmWhen)
+    if (!rawMessage) return this.#removeNestedRow(row)
+
+    // Per-row confirm interpolation (issue #222). A row added client-side is a
+    // cloneNode of the <template>, and the clone carries the TEMPLATE's confirm
+    // string verbatim — the renumber/seed steps never rewrite the confirm attr.
+    // So resolve %{field} placeholders here, from THIS row's live field values
+    // (read now, not at clone time, so a later edit is reflected). An unresolved
+    // key is left as its literal %{key} (debuggable, never throws). Server-
+    // rendered rows already interpolate server-side, so their finished strings
+    // carry no %{}; this is a no-op for them.
+    const fields = this.#nestedRowObject(row)
+    const message = this.#interpolateConfirm(rawMessage, fields)
+
+    // Gate through the overridable confirmResolver (issues #52/#55/#178) — a
+    // themed dialog set with setConfirmResolver covers this trigger too. Pass the
+    // row context (issue #222, superset of proposal 3) as an optional 2nd arg so
+    // a power-user override can build the string itself; the message is already
+    // interpolated for the default window.confirm path. Call the resolver INSIDE
+    // the chain so even a SYNCHRONOUS override throw is a cancel (like a dismissed
+    // dialog), and remove ONLY on a truthy resolution.
+    return Promise.resolve()
+      .then(() => confirmResolver(message, { el: trigger, row, fields }))
+      .catch(() => false)
+      .then((ok) => {
+        if (ok) this.#removeNestedRow(row)
+      })
+  }
+
+  // Resolve %{field} placeholders in a confirm message from a row's field map
+  // (issue #222). Ruby-style %{name} tokens; an unresolved key is left verbatim
+  // (a visible, debuggable placeholder — never an empty hole or a throw). A
+  // message with no placeholders returns unchanged, so this is inert for every
+  // server-rendered (already-interpolated) confirm string.
+  #interpolateConfirm(message, fields) {
+    if (!message.includes("%{")) return message
+    return message.replace(/%\{(\w+)\}/g, (whole, key) =>
+      Object.prototype.hasOwnProperty.call(fields, key) ? fields[key] : whole,
+    )
+  }
+
+  // The remove itself, shared by the confirmed and no-confirm paths. Draft rows
+  // leave the DOM; a persisted row (a hidden [_destroy] input present) is marked
+  // "1" + hidden instead (set-value + dispatch contract, #183), so Rails destroys
+  // it on save. Then re-sync every owned JSON-mode list (#208) — an absent row
+  // IS the removal; a form without a JSON list iterates an empty set and exits.
+  #removeNestedRow(row) {
     const destroy = [...(row.querySelectorAll?.('input[name$="[_destroy]"]') ?? [])][0]
     if (destroy) {
       destroy.value = "1"
@@ -1978,9 +2317,6 @@ export default class extends Controller {
       row.parentNode?.removeChild?.(row)
     }
 
-    // JSON mode (issue #208): the removed (or _destroy-hidden) row must leave
-    // the serialized array too — an absent row IS the removal. Re-sync every
-    // owned JSON-mode list; a form without one iterates an empty set and exits.
     this.#syncAllNestedJson()
   }