phlex-reactive 0.11.6 → 0.12.0

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()
 }
@@ -1869,15 +2148,89 @@ export default class extends Controller {
     const row = proto.cloneNode(true)
     this.#renumberNestedRow(row, this.#nextNestedIndex())
     list.appendChild(row)
-    const first = [...(row.querySelectorAll?.("input, select, textarea") ?? [])][0]
-    first?.focus?.()
 
-    // JSON mode (issue #208): a freshly-added empty row must land in the hidden
-    // field immediately, so the serialized array reflects the DOM even before
-    // the first keystroke. A no-op when this list isn't `as: :json`.
+    // Fill-then-add (issue #208 Scenario A): seed the cloned row from named
+    // source controls OUTSIDE the row, then (optionally) clear the sources.
+    // Runs AFTER renumber+append so a seeded field's name already carries its
+    // final `[<index>][field]` form — the key match agrees with what JSON mode
+    // reads. `seeded` is the FIRST source we cleared/read, so fill-then-add can
+    // return focus to the sources instead of stealing it into the new row.
+    const fromJson = trigger?.getAttribute?.("data-reactive-nested-from-param")
+    const clear = trigger?.getAttribute?.("data-reactive-nested-clear-param") === "true"
+    const firstSource = this.#seedNestedRow(row, fromJson, clear)
+
+    // Focus: inline-edit (no from:) focuses the new row's first field so you
+    // type INTO it; fill-then-add keeps focus on the sources (the first one) so
+    // you keep entering the next item — stealing focus would break that loop.
+    if (fromJson) firstSource?.focus?.()
+    else [...(row.querySelectorAll?.("input, select, textarea") ?? [])][0]?.focus?.()
+
+    // JSON mode (issue #208): a freshly-added row must land in the hidden field
+    // immediately (seeded values included), so the serialized array reflects the
+    // DOM even before the first keystroke. A no-op when not `as: :json`.
     if (list.getAttribute?.("data-reactive-nested-json") === assoc) this.#syncNestedJson(assoc)
   }
 
+  // Fill-then-add (issue #208): copy each source control's value into the
+  // matching cloned-row field, keyed by the trailing bracket segment of the
+  // field's name (#nestedJsonKey — the SAME inference JSON mode uses, so the
+  // two features can't drift). Sources resolve root-scoped and owned (#15); an
+  // unresolved source or an unmatched key is silently skipped (the row still
+  // adds — a half-mapped binding must never throw on click). Returns the FIRST
+  // source control read (for focus), or null. With `clear`, resets every source
+  // it read via the set-value + dispatch contract (#183) so dirty/show/compute
+  // observe the reset.
+  #seedNestedRow(row, fromJson, clear) {
+    if (!fromJson) return null
+    let map
+    try {
+      map = JSON.parse(fromJson)
+    } catch {
+      return null
+    }
+    if (!map || typeof map !== "object") return null
+
+    const owns = this.#ownershipFilter()
+    const rowFields = [...(row.querySelectorAll?.("input, select, textarea") ?? [])]
+    const sources = []
+    for (const [key, selector] of Object.entries(map)) {
+      const source = [...(this.element.querySelectorAll?.(selector) ?? [])].find(owns)
+      if (!source) continue
+      const target = rowFields.find((field) => this.#nestedJsonKey(field.getAttribute?.("name")) === key)
+      if (!target) continue
+      this.#seedNestedField(target, source)
+      sources.push(source)
+    }
+    if (clear) for (const source of sources) this.#clearNestedSource(source)
+    return sources[0] ?? null
+  }
+
+  // Copy a source control's value into a cloned-row field, then dispatch a
+  // bubbling `input` (the set-value + dispatch contract, #183). Checkbox ↔
+  // checkbox copies the checked state; every other target takes the source's
+  // submit-shaped value (#nestedFieldValue), so a checkbox source feeding a
+  // text field lands "on"/"" exactly as a submit would.
+  #seedNestedField(target, source) {
+    if (target.type === "checkbox") {
+      target.checked = source.type === "checkbox" ? !!source.checked : this.#nestedFieldValue(source) !== ""
+    } else {
+      target.value = this.#nestedFieldValue(source)
+    }
+    if (typeof target.dispatchEvent === "function") {
+      target.dispatchEvent(new Event("input", { bubbles: true }))
+    }
+  }
+
+  // Reset a source control after a fill-then-add (issue #208), dispatching a
+  // bubbling `input` so dirty tracking / reactive_show / compute see the reset.
+  #clearNestedSource(source) {
+    if (source.type === "checkbox") source.checked = false
+    else source.value = ""
+    if (typeof source.dispatchEvent === "function") {
+      source.dispatchEvent(new Event("input", { bubbles: true }))
+    }
+  }
+
   // Remove the trigger's closest row wrapper. A DRAFT row (no [_destroy]
   // input) leaves the DOM — it was never persisted, so removing its fields IS
   // the removal. A PERSISTED row (an edit form rendered a hidden [_destroy]
@@ -1893,6 +2246,35 @@ 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 message = this.#effectiveConfirmMessage(confirm, confirmWhen)
+    if (!message) return this.#removeNestedRow(row)
+
+    // Gate through the overridable confirmResolver (issues #52/#55/#178) — a
+    // themed dialog set with setConfirmResolver covers this trigger too. 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))
+      .catch(() => false)
+      .then((ok) => {
+        if (ok) this.#removeNestedRow(row)
+      })
+  }
+
+  // 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"
@@ -1904,9 +2286,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()
   }