npm - turbo-refresh-animations - Versions diffs - 0.0.1 - Mend

turbo-refresh-animations 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE +21 -0
package/README.md +439 -0
package/index.js +2 -0
package/package.json +38 -0
package/turbo-refresh-animations.js +539 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 FIRSTDRAFT LLC
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,439 @@
+# Turbo Refresh Animations
+Animates elements that enter, exit, or change during [Turbo Page Refreshes](https://turbo.hotwired.dev/handbook/page_refreshes).
+**Features:**
+- Opt-in animations via `data-turbo-refresh-animate` attribute.
+- Animates entries, exits, and changes.
+- Protect elements (especially forms) during same-page refresh morphs; the initiator still morphs.
+- Customize animations via CSS classes.
+- Works with importmaps, esbuild, webpack, or any bundler.
+## Table of Contents
+- [Installation](#installation)
+  - [With importmaps (Rails 7+)](#with-importmaps-rails-7)
+  - [With npm/yarn](#with-npmyarn)
+- [Quick Start](#quick-start)
+  - [1. Import the library](#1-import-the-library)
+  - [2. Add the CSS](#2-add-the-css)
+  - [3. Enable morphing in your layout](#3-enable-morphing-in-your-layout)
+  - [4. Opt in elements for animations](#4-opt-in-elements-for-animations)
+- [Data Attributes Reference](#data-attributes-reference)
+- [How It Works](#how-it-works)
+  - [Change Detection](#change-detection)
+- [Protecting Elements During Same-Page Refreshes](#protecting-elements-during-same-page-refreshes)
+  - [`data-turbo-refresh-stream-permanent`](#data-turbo-refresh-stream-permanent)
+  - [Form-specific conveniences](#form-specific-conveniences)
+  - [Flash protected elements on update](#flash-protected-elements-on-update)
+- [Customization](#customization)
+  - [Custom animation classes per element](#custom-animation-classes-per-element)
+  - [Enable specific animations](#enable-specific-animations)
+  - [Define your own animations](#define-your-own-animations)
+  - [Example animations](#example-animations)
+- [Refresh Deduping Notes](#refresh-deduping-notes)
+- [Disabling the Turbo Progress Bar](#disabling-the-turbo-progress-bar)
+- [TODOs](#todos)
+- [License](#license)
+## Installation
+### With importmaps (Rails 7+)
+```bash
+bin/importmap pin turbo-refresh-animations
+```
+### With npm/yarn
+```bash
+npm install turbo-refresh-animations
+# or
+yarn add turbo-refresh-animations
+```
+Peer dependency: `@hotwired/turbo` >= 8. If you're using Rails with `turbo-rails`, it's already included; otherwise install `@hotwired/turbo` alongside this package.
+## Quick Start
+### 1. Import the library
+```javascript
+// app/javascript/application.js
+import "@hotwired/turbo-rails"
+import "turbo-refresh-animations"
+```
+### 2. Add the CSS
+Add CSS for the animation classes in your app's stylesheet. This package does not ship CSS. You can copy the example styles from the [Example animations](#example-animations) section or write your own.
+### 3. Enable morphing in your layout
+```erb
+<%# app/views/layouts/application.html.erb %>
+<head>
+  <%= turbo_refreshes_with method: :morph, scroll: :preserve %>
+</head>
+```
+### 4. Opt in elements for animations
+Add `data-turbo-refresh-animate` and an `id` to elements you want to animate:
+```erb
+<%# app/views/items/_item.html.erb %>
+<div id="<%= dom_id(item) %>" data-turbo-refresh-animate>
+  <%= item.title %>
+</div>
+```
+Elements will animate when created, changed, or deleted during Turbo morphs.
+## Data Attributes Reference
+| Attribute | Purpose |
+|-----------|---------|
+| `id` | Element identifier (required for enter/change/exit animations) |
+| `data-turbo-refresh-animate` | Opt-in for animations (`=""`/present enables all, `="enter,exit"` enables subset, `="none"` disables) |
+| `data-turbo-refresh-enter="class"` | Custom enter animation class (single class token; no spaces) |
+| `data-turbo-refresh-change="class"` | Custom change animation class (single class token; no spaces) |
+| `data-turbo-refresh-exit="class"` | Custom exit animation class (single class token; no spaces) |
+| `data-turbo-refresh-stream-permanent` | Protect element during same-page refresh morphs (except initiator) |
+| `data-turbo-refresh-version` | Override change detection (used instead of `textContent`, e.g. `item.cache_key_with_version`) |
+## How It Works
+The library compares each element's "meaningful signature" before and after Turbo renders a page refresh morph. Elements with both an `id` and the `data-turbo-refresh-animate` attribute will be animated:
+| Animation | Trigger | Default CSS class |
+|-----------|---------|-------------------|
+| Enter | New element added to DOM | `turbo-refresh-enter` |
+| Change | Element text changes (or version changes) | `turbo-refresh-change` |
+| Exit | Element removed from DOM | `turbo-refresh-exit` |
+### Change Detection
+By default, change animations run only when an element's normalized `textContent` differs between the old and new page. This naturally ignores most "noise" that isn't user-visible (CSRF tokens, framework attributes, etc.).
+Normalization collapses all whitespace to single spaces and trims leading/trailing whitespace.
+For precise control (and to count non-text changes as meaningful), use `data-turbo-refresh-version`:
+```erb
+<div id="<%= dom_id(item) %>"
+     data-turbo-refresh-animate
+     data-turbo-refresh-version="<%= item.cache_key_with_version %>">
+  <%= item.title %>
+  <%= button_to "Delete", item, method: :delete %>
+</div>
+```
+When `data-turbo-refresh-version` is present, it's used instead of `textContent` to decide whether a change is meaningful. This is useful when:
+- If you want to respect invisible changes like hidden inputs (e.g. CSRF tokens) or attributes.
+- Elements include dynamic attributes from JavaScript frameworks.
+- You want explicit control over what constitutes a "change".
+## Protecting Elements During Same-Page Refreshes
+### `data-turbo-refresh-stream-permanent`
+When using `broadcasts_refreshes_to` (or any same-page refresh morph), any element with this attribute will be protected from morphing when the refresh comes from elsewhere (e.g., another user's refresh stream). This is useful for any element whose current DOM state you want to preserve during external refreshes.
+Unlike Turbo's `data-turbo-permanent`, this protection is conditional: the element is allowed to morph when it contains the form submit or same-page link that initiated the refresh, so user-initiated updates still apply.
+```erb
+<div data-turbo-refresh-stream-permanent>
+  <!-- This element won't be morphed during refresh streams -->
+</div>
+```
+This protection does not require an `id` (unless you also want the element to participate in enter/change/exit animations).
+**The most common use case is forms.** Without protection, a user typing in a form would lose their input whenever another user's action triggers a refresh stream:
+```erb
+<div id="new_item_form" data-turbo-refresh-stream-permanent>
+  <%= form_with model: item do |f| %>
+    <%= f.text_field :title %>
+    <%= f.submit "Add" %>
+  <% end %>
+</div>
+```
+### Form-specific conveniences
+Since forms are the most common use case, the library includes special handling:
+1. **Submitter's form still clears**: When a user submits a form inside a protected element, that specific element is allowed to morph normally (so the form clears after submission via the redirect response). Other protected elements remain protected.
+2. **Same-page refreshes preserve state**: Even during refresh morphs that stay on the same URL (e.g., `redirect_to` back to the current page), elements with `data-turbo-refresh-stream-permanent` stay protected. This preserves user-created UI state like open edit forms. If a user clicks a same‑page link inside a protected element (e.g., "Cancel"), the library sets `data-turbo-action="replace"` on that link so Turbo uses a refresh morph; the initiating element updates while other protected elements remain open.
+   - For this behavior, “same page” means the same `origin + pathname + search` (hash ignored).
+   - Note: links to an anchor in the current document (e.g. `/lists/1#comments`) are treated as in-page navigation and are not forced into a refresh morph.
+### Flash protected elements on update
+To show a visual indicator when a protected element's underlying data changes (e.g., another user edits the same item), add `data-turbo-refresh-version`:
+```erb
+<div id="<%= dom_id(item) %>"
+     data-turbo-refresh-stream-permanent
+     data-turbo-refresh-animate
+     data-turbo-refresh-version="<%= item.cache_key_with_version %>">
+  <%= form_with model: [item.list, item] do |f| %>
+    <%= f.text_field :title %>
+    <%= f.submit "Save" %>
+  <% end %>
+</div>
+```
+When the version changes during an external refresh, the element flashes with the change animation while keeping its current content protected.
+Note: protected elements can temporarily be in a different "view state" than the server-rendered HTML (e.g., an open edit form vs a read-only item view). To avoid false positives, the library only flashes protected elements based on `data-turbo-refresh-version` from the incoming HTML. In practice, add `data-turbo-refresh-version` to all render variants of a given `id` if you want flashing to work reliably.
+## Customization
+### Custom animation classes per element
+Use a different animation class for specific elements:
+```erb
+<div id="<%= dom_id(item) %>"
+     data-turbo-refresh-animate
+     data-turbo-refresh-enter="my-custom-enter"
+     data-turbo-refresh-exit="my-custom-exit">
+  <!-- Uses my-custom-enter and my-custom-exit instead of the default class names -->
+</div>
+```
+### Enable specific animations
+By default, `data-turbo-refresh-animate` enables all three animation types. Specify a comma-separated list to enable only certain types:
+```erb
+<%# Only animate exits (no enter or change) %>
+<div id="<%= dom_id(item) %>" data-turbo-refresh-animate="exit">
+<%# Animate enter and exit (no change) %>
+<div id="<%= dom_id(item) %>" data-turbo-refresh-animate="enter,exit">
+<%# All animations (default) %>
+<div id="<%= dom_id(item) %>" data-turbo-refresh-animate>
+```
+Options: `enter`, `exit`, `change`
+To explicitly disable animations on an element, use `data-turbo-refresh-animate="none"` (or `"false"`). This can be useful when a helper emits the attribute automatically.
+### Define your own animations
+You can override the default class names or use custom class names per element.
+If you already have an existing class you want the library to use by default, CSS doesn't provide true
+"class aliasing", but you can get the same effect:
+```css
+/* Apply the same rules to both selectors */
+.turbo-refresh-enter,
+.my-enter {
+  animation: myEnter 180ms ease-out;
+}
+```
+If you use Sass/SCSS, you can also do:
+```scss
+/* Make .turbo-refresh-enter reuse .my-enter rules */
+.turbo-refresh-enter { @extend .my-enter; }
+```
+Alternatively, set `data-turbo-refresh-enter="my-enter"` (or `...-change` / `...-exit`) on specific elements.
+Exit animations can be implemented with CSS transitions (not just keyframes). The exit class should
+change a property with a non-zero transition duration (for example, opacity or transform). The
+element is removed after the transition ends (with a timeout fallback).
+For predictable timing, use explicit transition properties (e.g., `opacity, transform`) instead of
+`transition-property: all`.
+#### Example: Background color flash
+```css
+/* Enter - green background fade */
+@keyframes bg-flash-enter {
+  from { background-color: #D1E7DD; }
+  to   { background-color: inherit; }
+}
+.bg-flash-enter {
+  animation: bg-flash-enter 1.2s ease-out;
+}
+/* Change - yellow background fade */
+@keyframes bg-flash-change {
+  from { background-color: #FFF3CD; }
+  to   { background-color: inherit; }
+}
+.bg-flash-change {
+  animation: bg-flash-change 1.2s ease-out;
+}
+/* Exit - red background fade + opacity */
+@keyframes bg-flash-exit {
+  from { background-color: #F8D7DA; opacity: 1; }
+  to   { background-color: inherit; opacity: 0; }
+}
+.bg-flash-exit {
+  animation: bg-flash-exit 0.6s ease-out forwards;
+}
+```
+#### Example: Slide in/out
+```css
+@keyframes slideInDown {
+  from {
+    transform: translate3d(0, -100%, 0);
+    visibility: visible;
+  }
+  to {
+    transform: translate3d(0, 0, 0);
+  }
+}
+.slideInDown {
+  animation: slideInDown 0.5s ease-out;
+}
+@keyframes slideOutUp {
+  from {
+    transform: translate3d(0, 0, 0);
+  }
+  to {
+    visibility: hidden;
+    transform: translate3d(0, -100%, 0);
+  }
+}
+.slideOutUp {
+  animation: slideOutUp 0.5s ease-out forwards;
+}
+```
+##### Masking slide animations
+Transform-based slide animations can "ghost" over adjacent rows because they paint outside their own box.
+To keep the motion contained, apply `overflow: hidden` on the animated element and animate a child:
+```erb
+<li data-turbo-refresh-animate
+    data-turbo-refresh-enter="slide-mask-enter"
+    data-turbo-refresh-exit="slide-mask-exit">
+  <div class="slide-mask-content">
+    <%= item.title %>
+  </div>
+</li>
+```
+```css
+.slide-mask-enter,
+.slide-mask-exit {
+  overflow: hidden;
+}
+.slide-mask-enter > .slide-mask-content {
+  animation: slideInDown 0.5s ease-out;
+}
+.slide-mask-exit > .slide-mask-content {
+  animation: slideOutUp 0.5s ease-out forwards;
+}
+```
+Use custom classes per element:
+```erb
+<div id="<%= dom_id(item) %>"
+     data-turbo-refresh-animate
+     data-turbo-refresh-enter="slideInDown"
+     data-turbo-refresh-exit="slideOutUp">
+  <%= item.title %>
+</div>
+```
+### Example animations
+Copy/paste this example into your app's stylesheet:
+```css
+/* Enter - fade in */
+.turbo-refresh-enter {
+  animation: turbo-refresh-enter 300ms ease-out;
+}
+@keyframes turbo-refresh-enter {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+/* Exit - fade out */
+.turbo-refresh-exit {
+  animation: turbo-refresh-exit 300ms ease-out forwards;
+}
+@keyframes turbo-refresh-exit {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+/* Change - yellow background flash */
+.turbo-refresh-change {
+  animation: turbo-refresh-change 800ms ease-out;
+}
+@keyframes turbo-refresh-change {
+  from { background-color: #FFF3CD; }
+  to { background-color: inherit; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .turbo-refresh-enter,
+  .turbo-refresh-change,
+  .turbo-refresh-exit {
+    animation-duration: 1ms;
+    animation-iteration-count: 1;
+  }
+}
+```
+## Refresh Deduping Notes
+You might be worried about the performance of using Turbo Refreshes so heavily, especially when paired with `broadcasts` from models. It's not as bad as you might think, because Turbo does two kinds of refresh deduping:
+- Backend (Turbo Rails): `broadcasts_refreshes_to` uses `broadcast_refresh_later_to`, which is debounced per stream name + `request_id` on the current thread. Multiple refreshes in quick succession coalesce into the last one. This does not apply to `broadcast_refresh_to`, and it is not a process-wide/global dedupe.
+- Frontend (Turbo Source): refresh stream actions are debounced in the session (default 150ms via `pageRefreshDebouncePeriod`), and refreshes with a `request-id` that matches a recent client request are ignored. The `request-id` is set automatically when you use `Turbo.fetch` (it adds `X-Turbo-Request-Id`).
+## Disabling the Turbo Progress Bar
+This library disables the Turbo progress bar during morph operations (but keeps it for regular navigation):
+```javascript
+document.addEventListener("turbo:morph", () => {
+  Turbo.navigator.delegate.adapter.progressBar.hide()
+})
+```
+See [hotwired/turbo#1221](https://github.com/hotwired/turbo/issues/1221) for discussion on making this configurable in Turbo itself.
+## TODOs
+- Expose a hook to set animation parameters before animations run (e.g., to measure `scrollHeight`
+  for jQuery UI-style "push siblings" slide animations).
+## License
+MIT

package/index.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import "./turbo-refresh-animations.js"
2	+

package/package.json ADDED Viewed

@@ -0,0 +1,38 @@
+{
+  "name": "turbo-refresh-animations",
+  "version": "0.0.1",
+  "description": "CSS class-based animations for Turbo page refresh morphs with form protection",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./turbo-refresh-animations.js": "./turbo-refresh-animations.js"
+  },
+  "files": [
+    "index.js",
+    "turbo-refresh-animations.js"
+  ],
+  "keywords": [
+    "turbo",
+    "hotwire",
+    "rails",
+    "morph",
+    "animations",
+    "turbo-stream",
+    "turbo-refresh",
+    "broadcasts_refreshes_to"
+  ],
+  "author": "Raghu Betina",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firstdraft/turbo-refresh-animations.git"
+  },
+  "bugs": {
+    "url": "https://github.com/firstdraft/turbo-refresh-animations/issues"
+  },
+  "homepage": "https://github.com/firstdraft/turbo-refresh-animations",
+  "peerDependencies": {
+    "@hotwired/turbo": ">=8.0.0"
+  }
+}

package/turbo-refresh-animations.js ADDED Viewed

@@ -0,0 +1,539 @@
+// ========== TURBO REFRESH ANIMATIONS ==========
+// Animates elements during Turbo page refresh morphs using Turbo events + before/after signatures
+const canInstall = typeof window !== "undefined" && typeof document !== "undefined"
+if (canInstall && !window.TurboRefreshAnimationsInstalled) {
+  window.TurboRefreshAnimationsInstalled = true
+let lastRenderedPathname = window.location.pathname
+let pendingVisitPathname = null
+let pendingVisitIsReplace = false
+let shouldAnimateAfterRender = false
+let signaturesBefore = new Map()
+const animationClassCleanupTimers = new WeakMap()
+// ========== FORM PROTECTION ==========
+// Protect elements with data-turbo-refresh-stream-permanent during same-page refresh
+// morphs ("page refreshes"). Allow the initiating element
+// (form submit / link click inside it) to morph so user-intended updates apply.
+let submittingPermanentEl = null
+let pendingVisitingPermanentEl = null
+let pendingVisitingPermanentUrl = null
+let pendingVisitingPermanentAtMs = 0
+let pendingVisitingPermanentClearTimer = null
+let visitingPermanentEl = null
+function clearPendingVisitingPermanent() {
+  pendingVisitingPermanentEl = null
+  pendingVisitingPermanentUrl = null
+  pendingVisitingPermanentAtMs = 0
+  if (pendingVisitingPermanentClearTimer) {
+    window.clearTimeout(pendingVisitingPermanentClearTimer)
+    pendingVisitingPermanentClearTimer = null
+  }
+}
+function hideTurboProgressBar() {
+  const progressBar = window.Turbo?.navigator?.delegate?.adapter?.progressBar
+  progressBar?.hide?.()
+}
+document.addEventListener("turbo:morph", hideTurboProgressBar)
+document.addEventListener("turbo:submit-start", (event) => {
+  const wrapper = event.target.closest("[data-turbo-refresh-stream-permanent]")
+  submittingPermanentEl = wrapper || null
+})
+document.addEventListener("turbo:submit-end", (event) => {
+  const contentType = event.detail?.fetchResponse?.contentType || ""
+  if (contentType.startsWith("text/vnd.turbo-stream.html")) {
+    submittingPermanentEl = null
+  }
+})
+document.addEventListener("turbo:click", (event) => {
+  const wrapper = event.target.closest("[data-turbo-refresh-stream-permanent]")
+  const link = event.target.closest("a[href]")
+  const clickUrl = event.detail?.url || link?.href || null
+  if (!wrapper || !link || !clickUrl) return
+  const samePage = visitKeyForUrl(clickUrl) === visitKeyForUrl(window.location.href)
+  const turboDisabled = link.getAttribute("data-turbo") === "false"
+  const hasTurboAction = link.hasAttribute("data-turbo-action")
+  const hasTurboMethod = link.hasAttribute("data-turbo-method")
+  const hasTurboStream = link.hasAttribute("data-turbo-stream")
+  const target = link.getAttribute("target")
+  // When a link points to the current document but includes an anchor (e.g. /path#section),
+  // don't force it into a "replace" refresh visit. That breaks expected anchor scrolling,
+  // especially with turbo-refresh-scroll=preserve. Let the browser handle it.
+  let clickHasAnchor = false
+  if (samePage) {
+    try {
+      clickHasAnchor = new URL(clickUrl, document.baseURI).hash !== ""
+    } catch {
+      clickHasAnchor = false
+    }
+  }
+  if (samePage && clickHasAnchor && !turboDisabled && !hasTurboAction && !hasTurboMethod && !hasTurboStream && target !== "_blank") {
+    event.preventDefault()
+    return
+  }
+  pendingVisitingPermanentEl = wrapper
+  pendingVisitingPermanentUrl = clickUrl
+  pendingVisitingPermanentAtMs = Date.now()
+  if (pendingVisitingPermanentClearTimer) {
+    window.clearTimeout(pendingVisitingPermanentClearTimer)
+  }
+  pendingVisitingPermanentClearTimer = window.setTimeout(clearPendingVisitingPermanent, 2000)
+  if (samePage && !turboDisabled && !hasTurboAction && !hasTurboMethod && !hasTurboStream && target !== "_blank") {
+    link.dataset.turboAction = "replace"
+  }
+})
+document.addEventListener("turbo:visit", (event) => {
+  pendingVisitPathname = pathnameForUrl(event.detail.url)
+  pendingVisitIsReplace = event.detail.action === "replace"
+  const ageMs = Date.now() - pendingVisitingPermanentAtMs
+  const pendingKey = visitKeyForUrl(pendingVisitingPermanentUrl)
+  const visitKey = visitKeyForUrl(event.detail.url)
+  const urlsMatch = pendingKey && visitKey && pendingKey === visitKey
+  visitingPermanentEl = ageMs >= 0 && ageMs < 2000 && urlsMatch ? pendingVisitingPermanentEl : null
+  clearPendingVisitingPermanent()
+})
+function clearPendingVisit() {
+  pendingVisitPathname = null
+  pendingVisitIsReplace = false
+}
+document.addEventListener("turbo:before-cache", () => {
+  document.querySelectorAll("[data-turbo-refresh-animate]").forEach(el => {
+    const timers = animationClassCleanupTimers.get(el)
+    if (timers) {
+      for (const timer of timers.values()) {
+        window.clearTimeout(timer)
+      }
+      timers.clear()
+    }
+    const animationClasses = new Set([
+      "turbo-refresh-enter",
+      "turbo-refresh-change",
+      "turbo-refresh-exit",
+      el.getAttribute("data-turbo-refresh-enter"),
+      el.getAttribute("data-turbo-refresh-change"),
+      el.getAttribute("data-turbo-refresh-exit")
+    ])
+    for (const className of animationClasses) {
+      if (className) el.classList.remove(className)
+    }
+  })
+})
+function getAnimationClass(el, animType, defaultClass) {
+  const animateValue = el.getAttribute("data-turbo-refresh-animate")
+  // data-turbo-refresh-animate semantics:
+  // - Absent => disabled
+  // - "none"/"false" => disabled
+  // - "" (present but empty) => all enabled
+  // - Comma list containing any of enter/exit/change => only the recognized subset enabled
+  // - Any other value (including common Rails helper "true") => all enabled
+  if (animateValue === null) return null
+  const normalized = animateValue.trim().toLowerCase()
+  if (normalized === "none" || normalized === "false") return null
+  if (normalized !== "") {
+    const enabledTypes = animateValue
+      .split(",")
+      .map(s => s.trim().toLowerCase())
+      .filter(type => type === "enter" || type === "exit" || type === "change")
+    if (enabledTypes.length > 0 && !enabledTypes.includes(animType)) return null
+  }
+  // Check for custom class via data-turbo-refresh-{type}="my-class"
+  const customClass = el.getAttribute(`data-turbo-refresh-${animType}`)
+  return customClass || defaultClass
+}
+function applyAnimation(el, defaultClass) {
+  // Extract animation type from class name (e.g., "turbo-refresh-enter" -> "enter")
+  const animType = defaultClass.replace("turbo-refresh-", "")
+  const animClass = getAnimationClass(el, animType, defaultClass)
+  if (!animClass) return
+  if (el.classList.contains(animClass)) {
+    el.classList.remove(animClass)
+    // Force a reflow so the same animation class can retrigger.
+    void el.offsetWidth
+  }
+  el.classList.add(animClass)
+  let timers = animationClassCleanupTimers.get(el)
+  if (!timers) {
+    timers = new Map()
+    animationClassCleanupTimers.set(el, timers)
+  }
+  const existingTimer = timers.get(animClass)
+  if (existingTimer) window.clearTimeout(existingTimer)
+  const waitMs = maxWaitMsForAnimationOrTransition(el)
+  if (waitMs === 0) {
+    el.classList.remove(animClass)
+    timers.delete(animClass)
+    return
+  }
+  const timer = window.setTimeout(() => {
+    el.classList.remove(animClass)
+    const currentTimers = animationClassCleanupTimers.get(el)
+    currentTimers?.delete(animClass)
+  }, waitMs)
+  timers.set(animClass, timer)
+}
+function normalizedTextContent(el) {
+  return (el.textContent || "").replace(/\s+/g, " ").trim()
+}
+function meaningfulUpdateSignature(el) {
+  const version = el.getAttribute("data-turbo-refresh-version")
+  if (version !== null) return `v:${version}`
+  return `t:${normalizedTextContent(el)}`
+}
+function visitKeyForUrl(url) {
+  try {
+    const parsed = new URL(url, document.baseURI)
+    return `${parsed.origin}${parsed.pathname}${parsed.search}`
+  } catch {
+    return null
+  }
+}
+function pathnameForUrl(url) {
+  try {
+    return new URL(url, document.baseURI).pathname
+  } catch {
+    return null
+  }
+}
+function isPageRefreshVisit() {
+  if (!pendingVisitIsReplace) return false
+  if (!pendingVisitPathname || !lastRenderedPathname) return false
+  return pendingVisitPathname === lastRenderedPathname
+}
+function parseCssTimeMs(value) {
+  const trimmed = value.trim()
+  if (trimmed === "") return 0
+  if (trimmed.endsWith("ms")) return Number.parseFloat(trimmed)
+  if (trimmed.endsWith("s")) return Number.parseFloat(trimmed) * 1000
+  const fallback = Number.parseFloat(trimmed)
+  return Number.isFinite(fallback) ? fallback * 1000 : 0
+}
+function parseCssTimeListMs(value) {
+  return value
+    .split(",")
+    .map(part => parseCssTimeMs(part))
+    .filter(Number.isFinite)
+}
+function parseCssNumberList(value) {
+  return value
+    .split(",")
+    .map(part => {
+      const trimmed = part.trim()
+      if (trimmed === "infinite") return 1
+      const num = Number.parseFloat(trimmed)
+      return Number.isFinite(num) ? num : 1
+    })
+}
+function maxTimingMs(durationsMs, delaysMs, iterations) {
+  const count = Math.max(durationsMs.length, delaysMs.length, iterations.length)
+  if (count === 0) return 0
+  let maxMs = 0
+  for (let i = 0; i < count; i++) {
+    const duration = durationsMs[i % durationsMs.length] || 0
+    const delay = delaysMs[i % delaysMs.length] || 0
+    const iteration = iterations[i % iterations.length] || 1
+    maxMs = Math.max(maxMs, delay + duration * iteration)
+  }
+  return maxMs
+}
+function expectedAnimationEndCount(el) {
+  const style = window.getComputedStyle(el)
+  if (!style.animationName || style.animationName === "none") return 0
+  const names = style.animationName.split(",").map(name => name.trim())
+  const durationsMs = parseCssTimeListMs(style.animationDuration)
+  const iterations = parseCssNumberList(style.animationIterationCount)
+  let count = 0
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i]
+    if (!name || name === "none") continue
+    const duration = durationsMs[i % durationsMs.length] || 0
+    const iteration = iterations[i % iterations.length] || 1
+    if (duration > 0 && iteration > 0) count += 1
+  }
+  return count
+}
+function expectedTransitionEndCount(el) {
+  const style = window.getComputedStyle(el)
+  if (!style.transitionProperty || style.transitionProperty === "none") return 0
+  const properties = style.transitionProperty.split(",").map(prop => prop.trim())
+  // "all" means we can't know which properties will change, so we can't reliably
+  // predict how many transitionend events will fire. Fall back to the timeout.
+  if (properties.some(prop => prop.toLowerCase() === "all")) return 0
+  const durationsMs = parseCssTimeListMs(style.transitionDuration)
+  let count = 0
+  for (let i = 0; i < properties.length; i++) {
+    const name = properties[i]
+    if (!name || name === "none") continue
+    const duration = durationsMs[i % durationsMs.length] || 0
+    if (duration > 0) count += 1
+  }
+  return count
+}
+function maxWaitMsForAnimationOrTransition(el) {
+  const style = window.getComputedStyle(el)
+  let maxMs = 0
+  if (style.animationName && style.animationName !== "none") {
+    maxMs = Math.max(
+      maxMs,
+      maxTimingMs(
+        parseCssTimeListMs(style.animationDuration),
+        parseCssTimeListMs(style.animationDelay),
+        parseCssNumberList(style.animationIterationCount)
+      )
+    )
+  }
+  if (style.transitionProperty && style.transitionProperty !== "none") {
+    maxMs = Math.max(
+      maxMs,
+      maxTimingMs(
+        parseCssTimeListMs(style.transitionDuration),
+        parseCssTimeListMs(style.transitionDelay),
+        [1]
+      )
+    )
+  }
+  return maxMs > 0 ? maxMs + 50 : 0
+}
+function animateAndRemove(el, animClass) {
+  return new Promise(resolve => {
+    let finished = false
+    let timer = null
+    let endedCount = 0
+    let expectedEnds = 0
+    const finish = () => {
+      if (finished) return
+      finished = true
+      if (timer) clearTimeout(timer)
+      el.removeEventListener("animationend", onEnd)
+      el.removeEventListener("animationcancel", onCancel)
+      el.removeEventListener("transitionend", onTransitionEnd)
+      el.removeEventListener("transitioncancel", onCancel)
+      el.remove()
+      resolve()
+    }
+    const onEnd = (event) => {
+      if (event.target !== el) return
+      endedCount += 1
+      if (expectedEnds > 0 && endedCount >= expectedEnds) {
+        finish()
+      }
+    }
+    const onCancel = (event) => {
+      if (event.target !== el) return
+      finish()
+    }
+    const onTransitionEnd = (event) => {
+      if (event.target !== el) return
+      endedCount += 1
+      if (expectedEnds > 0 && endedCount >= expectedEnds) {
+        finish()
+      }
+    }
+    el.addEventListener("animationend", onEnd)
+    el.addEventListener("animationcancel", onCancel)
+    el.addEventListener("transitionend", onTransitionEnd)
+    el.addEventListener("transitioncancel", onCancel)
+    el.classList.add(animClass)
+    expectedEnds = expectedAnimationEndCount(el) + expectedTransitionEndCount(el)
+    const waitMs = maxWaitMsForAnimationOrTransition(el)
+    if (expectedEnds === 0 && waitMs === 0) {
+      finish()
+      return
+    }
+    timer = setTimeout(finish, waitMs > 0 ? waitMs : 2000)
+  })
+}
+// Handle morphing: protect permanent elements, animate deletes
+document.addEventListener("turbo:before-morph-element", (event) => {
+  const currentEl = event.target
+  const newEl = event.detail.newElement
+  // Protect permanent elements:
+  // - During same-page refresh morphs (preserve user state like open forms)
+  // - EXCEPT the element initiating the refresh (form submit or link click within it)
+  if (currentEl.hasAttribute("data-turbo-refresh-stream-permanent")) {
+    // If the element is being removed, allow Turbo to remove it normally.
+    if (newEl === undefined) return
+    const isSubmitting = currentEl === submittingPermanentEl
+    const isVisiting = currentEl === visitingPermanentEl
+    const isInitiator = isSubmitting || isVisiting
+    const shouldProtect = !isInitiator && shouldAnimateAfterRender
+    if (shouldProtect) {
+      event.preventDefault()
+      // Flash protected elements on meaningful updates, based on data-turbo-refresh-version.
+      // This avoids false positives from view-state differences (e.g., open form vs read-only).
+      if (currentEl.hasAttribute("data-turbo-refresh-animate") && currentEl.hasAttribute("data-turbo-refresh-version")) {
+        const oldVersion = currentEl.getAttribute("data-turbo-refresh-version")
+        const newVersion = newEl.getAttribute("data-turbo-refresh-version")
+        if (newVersion !== null && oldVersion !== newVersion) {
+          currentEl.setAttribute("data-turbo-refresh-version", newVersion)
+          if (currentEl.id) {
+            signaturesBefore.set(currentEl.id, meaningfulUpdateSignature(currentEl))
+          }
+          applyAnimation(currentEl, "turbo-refresh-change")
+        }
+      }
+      return
+    }
+  }
+})
+// Before render: detect deletions and animate BEFORE morph
+document.addEventListener("turbo:before-render", async (event) => {
+  if (!event.detail.newBody) {
+    clearPendingVisit()
+    return
+  }
+  signaturesBefore = new Map()
+  shouldAnimateAfterRender = isPageRefreshVisit()
+  clearPendingVisit()
+  if (!shouldAnimateAfterRender) {
+    return
+  }
+  const animatedElements = Array.from(document.querySelectorAll("[data-turbo-refresh-animate][id]"))
+  animatedElements.forEach(el => {
+    signaturesBefore.set(el.id, meaningfulUpdateSignature(el))
+  })
+  let shouldResume = false
+  // Detect elements that will be deleted
+  const deletions = animatedElements.filter(el => {
+    return !event.detail.newBody.querySelector(`#${CSS.escape(el.id)}`)
+  })
+  // If there are deletions, animate them BEFORE the morph
+  if (deletions.length > 0) {
+    // Filter to only elements that want exit animation and get their classes
+    const candidateDeletions = deletions
+      .map(el => ({ el, exitClass: getAnimationClass(el, "exit", "turbo-refresh-exit") }))
+      .filter(({ exitClass }) => exitClass)
+    if (candidateDeletions.length > 0) {
+      event.preventDefault()
+      shouldResume = true
+      const candidateSet = new Set(candidateDeletions.map(({ el }) => el))
+      const topLevelDeletions = candidateDeletions.filter(({ el }) => {
+        let parent = el.parentElement
+        while (parent) {
+          if (candidateSet.has(parent)) return false
+          parent = parent.parentElement
+        }
+        return true
+      })
+      await Promise.all(topLevelDeletions.map(({ el, exitClass }) => animateAndRemove(el, exitClass)))
+    }
+  }
+  if (shouldResume) {
+    event.detail.resume()
+  }
+})
+document.addEventListener("turbo:render", () => {
+  lastRenderedPathname = window.location.pathname
+  submittingPermanentEl = null
+  visitingPermanentEl = null
+  clearPendingVisit()
+  if (shouldAnimateAfterRender) {
+    document.querySelectorAll("[data-turbo-refresh-animate][id]").forEach(el => {
+      const beforeSignature = signaturesBefore.get(el.id)
+      if (beforeSignature === undefined) {
+        applyAnimation(el, "turbo-refresh-enter")
+        return
+      }
+      const afterSignature = meaningfulUpdateSignature(el)
+      if (beforeSignature !== afterSignature) {
+        applyAnimation(el, "turbo-refresh-change")
+      }
+    })
+  }
+  shouldAnimateAfterRender = false
+  signaturesBefore = new Map()
+})
+}