phlex-reactive 0.11.7 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce274b76a614b8510a9fc365e717d0b5391b815743a9cd0e9f3ffa716428c0ec
-  data.tar.gz: 9be84dd96ad24ef556935b8b68a60ecdbf48fabe902e1541584d6af6f22e17cf
+  metadata.gz: 27841384eb24e3e9d66f404b495705b2db4c30fec683ad21ae0f2b2c258c6a00
+  data.tar.gz: 14990c96dd4dfafefd56794531cc116f8a17a9bc6aa76d8caf50679fb95abc1b
 SHA512:
-  metadata.gz: 5e87ae21d988550c315b9ac27a721d5e65b7fdf354ddbaa487cd0e2db7e062ad854198f0a6893ab8e9d0531b6ff698829f7421bd1d8a4fbd3c533992a4485a51
-  data.tar.gz: 107d841025bc3d6d2fecb4b30027e417607773edd12c45503a5615ecee40d9cd5994d42c5ddd40a3ec53c354fa49ef482953844b2ee2ee01311e27c0bbf987c2
+  metadata.gz: c36de342a6909b7cbd04f58a9d6da9b77497acfe5f6777c200932a54af5251872ec91b2a5d624f14f1cb5b3faed8fe60e5a169e4363cb6d32bf7d24418fd88ac
+  data.tar.gz: 45c811958371300f558d57f41e8ead04e607cc07cd43a9915aa2534fa15b650d1c284ca92b871734b755791b730fdb325f7e28e7f8372616aff383887873f340

data/CHANGELOG.md

@@ -8,6 +8,61 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Project board — the kanban flagship demo (#216).** A live three-lane board
+  on the docs site (`/docs/example-project-board`, `/demos/project-board`)
+  composing the toolkit end to end: each card is its own nested reactive root
+  (record + signed style state) whose move is ONE reply — the row's remove
+  (its exit effect animates before the element leaves), a fresh-token append
+  into the new lane (wearing its enter effect), and a `reactive:js` text-op
+  stream repainting all three count badges — with the same delta broadcast to
+  peers, actor echo excluded. Inline rename morphs in place, archive is
+  confirm-gated + optimistic, per-lane composers flash on a blank title, and
+  the effect-style picker (including `random`) rides signed state to drive
+  per-call `effect:` overrides. Peer count badges stay live everywhere via
+  `broadcast_to(js:)` — closing the stale-badge gap the team-inbox flagship
+  documents — and empty lanes are pure CSS `:empty`, so the 0↔1 boundary
+  needs no bookkeeping on either delivery path. Docs-app only; no gem code
+  changes.
+
+- **Reactive effects — animate enter/exit/update on every stream render (#215).**
+  Opt-in at three levels, most specific wins: `Phlex::Reactive.effects = true`
+  (or a `{ enter:/exit:/update: }` hash) is the global switch AND the app-wide
+  default set; `reactive_effects enter: :slide, update: false` refines per
+  component (`false` opts out entirely; declaring on a component also works
+  standalone with no global switch); `effect:` on every stream builder, reply
+  verb, and `broadcast_to` overrides one stream (`effect: false` suppresses a
+  declared effect for that call). Five built-ins ship as an engine stylesheet —
+  `stylesheet_link_tag "phlex/reactive/effects"` — fade/slide/scale/highlight/
+  shake, all inside `prefers-reduced-motion: no-preference` and tunable via
+  `--reactive-fx-*` custom properties; `:random` picks a built-in per
+  application; custom effects take the `{ during:, from:, to: }` class-legs
+  vocabulary (issue #186), Tailwind-friendly and stylesheet-free. On the wire
+  the resolved hooks ride the component root as `data-reactive-effect-<hook>`
+  attributes (omitted entirely when off — byte-identical to previous releases)
+  and per-call overrides ride the `<turbo-stream>` element itself; ONE
+  document-level `turbo:before-stream-render` interceptor animates replies AND
+  broadcasts identically on Action Cable and pgbus. `remove` is special: the
+  exit animation runs BEFORE the element leaves the DOM, awaited via
+  `animationend`/`transitionend` with a computed-duration fallback hard-capped
+  at 1s — and a zero computed duration (no effects CSS loaded) skips the wait
+  entirely, so a missing stylesheet can never freeze a removal. Unknown names
+  raise at class load server-side and warn-and-skip client-side (two-sided
+  default-deny). Zero additional allocations per render with effects on (the
+  resolved fragment is a per-class memo keyed on the config + registry
+  generations); the render/token hot paths hold flat with effects off.
+
+- **Confirm on the draft-row remove — `reactive_nested_remove(confirm:)` (#218).**
+  `reactive_nested_remove` now accepts the SAME `confirm:` the other triggers
+  (`on`/`on_client`) do — a static message String, or the conditional Hash form
+  (`{ when: …, message: }` / `{ predicate: …, message: }`, #179) — routed through
+  the shared `apply_confirm!` and gated client-side behind the same overridable
+  `confirmResolver` (the styled-modal seam, #52/#55/#178). On accept it does the
+  existing remove (a draft row leaves the DOM; a persisted row is `_destroy`-marked
+  + hidden) and the existing JSON/attributes re-sync; on cancel, nothing. Per-row
+  messages come for free — the confirm is a per-render string. Works in BOTH wire
+  modes (`:attributes` and `as: :json`). No confirm: → the immediate-remove fast
+  path, unchanged.
+
 - **Fill-then-add for draft nested rows — `reactive_nested_add(:assoc, from:, clear:)` (#208).**
   The draft-rows primitive's add is *inline-edit* — it clones the template and
   focuses the new row's first field, so you type INTO the row. A common

data/README.md

@@ -332,11 +332,13 @@ The [inline edit example](https://phlex-reactive.zoolutions.llc/docs/example-inl
 | [Client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops) | `on_client` tabs / outside-close menu / accessible drawer — zero fetches, zero custom JS |
 | [Failure surface](https://phlex-reactive.zoolutions.llc/docs/example-failure) | `error_flash` + `data-reactive-error` + `dismiss_after:` — what you get for free when an action fails |
 | [Team inbox (flagship)](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox) | The whole toolkit in one UI: collection rows, optimistic archive that **reverts on failure**, cross-tab broadcast, an `on_client` kebab, error flashes |
+| [Project board (flagship)](https://phlex-reactive.zoolutions.llc/docs/example-project-board) | The kanban: cards move across lanes with **enter/exit effects** (per-visitor style picker incl. `random`), live count badges in every tab via `broadcast_to(js:)`, nested reactive rows with inline rename, confirm-gated archive |
 
 Every page renders its **real** reactive component inline (source read straight
 off the file), so the demo and the code can never drift. The
-[Team inbox](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox) is the
-flagship — every feature composed into one believable UI.
+[Team inbox](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox) and the
+[Project board](https://phlex-reactive.zoolutions.llc/docs/example-project-board) are the
+flagships — every feature composed into believable UIs.
 
 ---
 
@@ -397,7 +399,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_dirty` / `reactive_dirty warn_unsaved: true` / `reactive_dirty only: %i[...]` | **Dirty tracking**, declared once at the class level, against the DOM's own `defaultValue`/`defaultChecked`/`defaultSelected` — no client state. Marks changed fields + the root `data-reactive-dirty`; `warn_unsaved:` arms a `beforeunload`/`turbo:before-visit` guard; `only:` scopes tracking to named fields. Style with `[data-reactive-dirty]`. See [Dirty-field tracking](#dirty-field-tracking-reactive_dirty). |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
 | `reactive_nested_list(:assoc, as: :attributes \| :json)` / `reactive_nested_template(:assoc)` / `reactive_nested_row` | **Draft nested-attribute rows** (the "new parent + child rows" form): the container rows land in, the `<template>` holding ONE row's markup, and the row wrapper marker — all **client-only** form state, keyed by association (several collections per root). `as: :json` (default `:attributes`) serializes the rows into ONE hidden JSON field instead of posting `accepts_nested_attributes_for` names — for an app whose controller `JSON.parse`s a serialized param. See [Draft rows for a new parent](#draft-rows-for-a-new-parent-reactive_nested_). |
-| `reactive_nested_add(:assoc, from:, clear:)` / `reactive_nested_remove` | The row triggers, client-only (zero round trips): add clones the template and renumbers its placeholder index; remove deletes a draft row from the DOM, or `_destroy`-marks + hides a persisted row (a hidden `[_destroy]` input present). **Fill-then-add**: `from: { row_field => "#source-selector" }` seeds the new row from add controls that live OUTSIDE it (a preset select, a typeahead), and `clear: true` resets them — composes with `as: :attributes` AND `as: :json`. See [Draft rows for a new parent](#draft-rows-for-a-new-parent-reactive_nested_). |
+| `reactive_nested_add(:assoc, from:, clear:)` / `reactive_nested_remove(confirm:)` | The row triggers, client-only (zero round trips): add clones the template and renumbers its placeholder index; remove deletes a draft row from the DOM, or `_destroy`-marks + hides a persisted row (a hidden `[_destroy]` input present). **Fill-then-add**: `from: { row_field => "#source-selector" }` seeds the new row from add controls that live OUTSIDE it (a preset select, a typeahead), and `clear: true` resets them — composes with `as: :attributes` AND `as: :json`. **Confirm on remove**: `reactive_nested_remove(confirm: "Really delete this row?")` gates the remove behind the same overridable `confirmResolver` as `on`/`on_client` (a per-row string, or the conditional `{ when:, message: }` Hash). See [Draft rows for a new parent](#draft-rows-for-a-new-parent-reactive_nested_). |
 | `nested_field_name(:assoc, :field, index: nil)` | The Rails `accepts_nested_attributes_for` wire name for one row field — `order[line_items_attributes][NEW_ROW][quantity]` (the template placeholder) by default, a real index when given. Scope-aware under `reactive_scope`. |
 | `reactive_collection :name, item:, container:, count:, empty:, size:` | Declare an add/remove-row list once; actions call `reply.append`/`prepend`/`remove`. See [Reactive collections](#reactive-collections-addremove-rows--count--empty-state). |
 | `reply.replace` / `.morph` / `.update` / `.remove` / `.redirect(url)` / `.with(*)` / `.js(ops)` | Return from an action to control the reply (flash, remove, redirect, multi-stream, server-pushed client ops). See [Controlling the action's reply](#reply--controlling-the-actions-reply). |
@@ -2133,6 +2135,66 @@ end
   `reactive_collection` is the per-actor add/remove + count + empty-state wrapper,
   not a replacement for the broadcast.
 
+### Effects — animate enter/exit/update (opt-in)
+
+Reactive updates land instantly and invisibly: a removed row pops out of
+existence, an appended row pops in, a cross-tab change gives no cue. Effects
+make the reactivity *visible* — rows fade/slide in and out, updates flash —
+with zero app JS. Strictly **opt-in at three levels**, most specific wins:
+
+```ruby
+# 1. GLOBAL — setting it is the opt-in AND the app-wide default set:
+Phlex::Reactive.effects = true   # { enter: :fade, exit: :fade, update: :highlight }
+Phlex::Reactive.effects = { enter: :slide, exit: :fade, update: :highlight }
+
+# 2. PER COMPONENT — refine or opt out (works standalone too; declaring on a
+#    component opts it in even without the global switch):
+class Notifications::Row < ApplicationComponent
+  reactive_effects enter: :slide, exit: :fade   # built-ins (shipped CSS)
+  # reactive_effects update: false              # disable one hook
+  # reactive_effects false                      # opt this component out entirely
+  # reactive_effects enter: :random             # a random built-in per application
+end
+
+# 3. PER CALL — the escape hatch for one stream:
+reply.remove(effect: :shake)                    # a dramatic one-off exit
+reply.append(item, to: :items, effect: :scale)  # this row only
+Item.replace(@todo, effect: false)              # suppress a declared effect once
+Row.broadcast_to(@list, :todos, append: todo, target: "rows", effect: :slide)
+```
+
+The hooks map to stream actions: **enter** (`append`/`prepend`) animates the
+arriving element, **exit** (`remove`) runs *before* the element leaves the DOM
+(the removal waits for the animation, capped at 1s so a missing stylesheet can
+never wedge it), **update** (`replace`/`update`, plain or morph) flashes the
+fresh render. Effects fire for the actor's own reply AND for broadcasts alike
+— if a debounced-save grid flashes too much, declare `reactive_effects
+update: false` on that component.
+
+Link the shipped stylesheet once (five built-ins — `:fade`, `:slide`,
+`:scale`, `:highlight`, `:shake` — wrapped in `prefers-reduced-motion:
+no-preference`, tunable via `--reactive-fx-*` CSS custom properties):
+
+```erb
+<%= stylesheet_link_tag "phlex/reactive/effects" %>
+```
+
+Custom effects skip the stylesheet entirely: pass named class legs (the same
+`{ during:, from:, to: }` vocabulary `js.toggle(transition:)` uses), perfect
+for Tailwind utilities:
+
+```ruby
+reactive_effects enter: { during: %w[transition-all duration-300],
+                          from: %w[opacity-0 translate-y-2],
+                          to: %w[opacity-100 translate-y-0] }
+```
+
+Unknown effect names raise at class load (server) and warn-and-skip on the
+client (default-deny, two-sided). With effects off (the default) the wire is
+byte-identical to previous releases; with them on, the resolved hooks ride the
+component root as `data-reactive-effect-*` attributes — identity, never state,
+and identical on Action Cable and pgbus.
+
 ### Configuration (`config/initializers/phlex_reactive.rb`)
 
 ```ruby
@@ -2180,6 +2242,10 @@ Phlex::Reactive.error_flash = ->(kind) do
   end
 end
 
+# Effects (issue #215): opt in globally + set the app-wide default hooks; see
+# "Effects" above. Off (nil) by default — byte-identical wire when off.
+Phlex::Reactive.effects = { enter: :fade, exit: :fade, update: :highlight }
+
 # Turnkey APM integration. Names each action Component#action in AppSignal/Sentry/
 # Datadog and reports action-body crashes with component/action tags. SDK is
 # runtime-detected (no gem dependency); a custom object responding to

data/app/assets/stylesheets/phlex/reactive/effects.css

@@ -0,0 +1,106 @@
+/* phlex-reactive effects (issue #215) — the shipped built-in animations.
+ *
+ * Opt in from your layout:
+ *
+ *   <%= stylesheet_link_tag "phlex/reactive/effects" %>
+ *
+ * The client applies these classes transiently around stream renders:
+ * reactive-fx--<name>-<hook>, where <name> is fade/slide/scale/highlight/
+ * shake and <hook> is enter (append/prepend), exit (remove), or update
+ * (replace/update). Every class is removed again on animationend, so nothing
+ * here leaks into steady-state styling.
+ *
+ * Everything is wrapped in prefers-reduced-motion: no-preference — the client
+ * ALSO skips effects entirely under reduced motion (defense in depth; a zero
+ * computed duration short-circuits the exit wait, so removals never stall).
+ *
+ * Tune globally (or per component root) by overriding the custom properties:
+ *
+ *   :root { --reactive-fx-duration: 200ms; --reactive-fx-highlight-color: #bae6fd80; }
+ *
+ * Keep durations comfortably under 1s — the client hard-caps any effect wait
+ * at 1000ms (an exit past the cap is removed mid-animation).
+ */
+@media (prefers-reduced-motion: no-preference) {
+  :root {
+    --reactive-fx-duration: 300ms;
+    --reactive-fx-highlight-duration: 700ms;
+    --reactive-fx-highlight-color: rgba(250, 204, 21, 0.5);
+  }
+
+  /* fade — opacity in/out. The update variant re-fades the fresh render in. */
+  @keyframes reactive-fx-fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+  @keyframes reactive-fx-fade-out {
+    from { opacity: 1; }
+    to { opacity: 0; }
+  }
+  .reactive-fx--fade-enter,
+  .reactive-fx--fade-update {
+    animation: reactive-fx-fade-in var(--reactive-fx-duration) ease-out both;
+  }
+  .reactive-fx--fade-exit {
+    animation: reactive-fx-fade-out var(--reactive-fx-duration) ease-in both;
+  }
+
+  /* slide — a short vertical travel + fade. */
+  @keyframes reactive-fx-slide-in {
+    from { opacity: 0; transform: translateY(0.5rem); }
+    to { opacity: 1; transform: none; }
+  }
+  @keyframes reactive-fx-slide-out {
+    from { opacity: 1; transform: none; }
+    to { opacity: 0; transform: translateY(0.5rem); }
+  }
+  .reactive-fx--slide-enter,
+  .reactive-fx--slide-update {
+    animation: reactive-fx-slide-in var(--reactive-fx-duration) ease-out both;
+  }
+  .reactive-fx--slide-exit {
+    animation: reactive-fx-slide-out var(--reactive-fx-duration) ease-in both;
+  }
+
+  /* scale — grow in / shrink out around the element's center. */
+  @keyframes reactive-fx-scale-in {
+    from { opacity: 0; transform: scale(0.92); }
+    to { opacity: 1; transform: none; }
+  }
+  @keyframes reactive-fx-scale-out {
+    from { opacity: 1; transform: none; }
+    to { opacity: 0; transform: scale(0.92); }
+  }
+  .reactive-fx--scale-enter,
+  .reactive-fx--scale-update {
+    animation: reactive-fx-scale-in var(--reactive-fx-duration) ease-out both;
+  }
+  .reactive-fx--scale-exit {
+    animation: reactive-fx-scale-out var(--reactive-fx-duration) ease-in both;
+  }
+
+  /* highlight — the classic background flash that fades to the element's own
+   * background. One animation for every hook: flash on arrival, on change,
+   * and as a last flare before a removal. */
+  @keyframes reactive-fx-highlight {
+    from { background-color: var(--reactive-fx-highlight-color); }
+  }
+  .reactive-fx--highlight-enter,
+  .reactive-fx--highlight-update,
+  .reactive-fx--highlight-exit {
+    animation: reactive-fx-highlight var(--reactive-fx-highlight-duration) ease-out both;
+  }
+
+  /* shake — a quick horizontal oscillation (attention / destructive cue). */
+  @keyframes reactive-fx-shake {
+    10%, 90% { transform: translateX(-1px); }
+    20%, 80% { transform: translateX(2px); }
+    30%, 50%, 70% { transform: translateX(-3px); }
+    40%, 60% { transform: translateX(3px); }
+  }
+  .reactive-fx--shake-enter,
+  .reactive-fx--shake-update,
+  .reactive-fx--shake-exit {
+    animation: reactive-fx-shake 400ms cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
+  }
+}

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()
 }
@@ -1967,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"
@@ -1978,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()
   }