From c27447e2a0b2bb4fa11b7f1a6c98d5a7299dbbaa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean=20Mendon=C3=A7a?= <pierrybm@gmail.com>
Date: Tue, 12 May 2026 11:30:46 -0300
Subject: [PATCH 1/2] [Improvement] Add exit animation, remove delay,
 lazy-mount Tooltip content
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Aligns the Tooltip with shadcn/ui's defaults and behavior:

- Switch from `data-show="true"` (binary) to `data-state="open"|"closed"`,
  enabling clean enter/exit animations driven by paired
  `data-[state=open]:*` / `data-[state=closed]:*` Tailwind classes.
- Add `data-[state=closed]:fill-mode-forwards` so the exit animation
  persists at its final keyframe (opacity 0) — without it, `tw-animate-css`
  defaults to `fill-mode: none` and the content snaps back to opacity 1
  after the animation completes.
- Remove the 500ms delay — shadcn overrides Radix's 700ms default with
  `delayDuration: 0`, so the tooltip now opens instantly on hover/focus.
- Lazy-mount the content via `<template>`: the content lives inert in a
  `DocumentFragment` until first hover; the controller clones it into
  `document.body` on `show`, unmounts on the close animation's
  `animationend`. Avoids paying parse + CSS + Stimulus target scan cost
  for tooltips the user never interacts with.
- Add `turbo:before-cache` listener so the tooltip is removed from `body`
  before Turbo snapshots the page, keeping the cache clean.
- Wire the trigger through Stimulus actions (`mouseenter` / `mouseleave`
  / `focus` / `blur`) on a single `data-action`, instead of relying on
  CSS sibling selectors (`peer-hover` / `peer-focus`).
- Drop `class: "peer"` from the trigger — the sibling pattern is no
  longer used.
---
 .../controllers/ruby_ui/tooltip_controller.js | 80 ++++++++++++++-----
 gem/lib/ruby_ui/tooltip/tooltip_content.rb    |  9 +--
 gem/lib/ruby_ui/tooltip/tooltip_controller.js | 80 ++++++++++++++-----
 gem/lib/ruby_ui/tooltip/tooltip_trigger.rb    |  8 +-
 4 files changed, 125 insertions(+), 52 deletions(-)

diff --git a/docs/app/javascript/controllers/ruby_ui/tooltip_controller.js b/docs/app/javascript/controllers/ruby_ui/tooltip_controller.js
index 20ba35ce9..504242a5b 100644
--- a/docs/app/javascript/controllers/ruby_ui/tooltip_controller.js
+++ b/docs/app/javascript/controllers/ruby_ui/tooltip_controller.js
@@ -3,36 +3,72 @@ import { computePosition, autoUpdate, offset, shift } from "@floating-ui/dom";
 
 export default class extends Controller {
   static targets = ["trigger", "content"];
-  static values = { placement: String }
 
-  constructor(...args) {
-    super(...args);
-    this.cleanup;
+  static values = { placement: "top" };
+
+  mount() {
+    if (this.mounted) return;
+
+    const element = this.cloneTemplate();
+    element.setAttribute("data-placement", this.placementValue);
+    document.body.appendChild(element);
+
+    this.triggerTarget.setAttribute("aria-describedby", element.id);
+    element.addEventListener("animationend", (event) => this.animationEnd(event));
+
+    const onBeforeCache = () => this.unmount();
+    document.addEventListener("turbo:before-cache", onBeforeCache);
+
+    this.mounted = { element, onBeforeCache };
+    this.mounted.stopAutoUpdate = autoUpdate(this.triggerTarget, element, () => this.reposition());
   }
 
-  connect() {
-    this.setFloatingElement();
+  unmount() {
+    if (!this.mounted) return;
 
-    const tooltipId = this.contentTarget.getAttribute("id");
-    this.triggerTarget.setAttribute("aria-describedby", tooltipId);
+    document.removeEventListener("turbo:before-cache", this.mounted.onBeforeCache);
 
+    this.mounted.stopAutoUpdate?.();
+    this.mounted.element.remove();
+    this.triggerTarget.removeAttribute("aria-describedby");
+
+    this.mounted = null;
   }
 
   disconnect() {
-    this.cleanup();
-  }
-
-  setFloatingElement() {
-    this.cleanup = autoUpdate(this.triggerTarget, this.contentTarget, () => {
-      computePosition(this.triggerTarget, this.contentTarget, {
-        placement: this.placementValue,
-        middleware: [offset(4), shift()]
-      }).then(({ x, y }) => {
-        Object.assign(this.contentTarget.style, {
-          left: `${x}px`,
-          top: `${y}px`,
-        });
-      });
+    this.unmount();
+  }
+
+  show() {
+    if (!this.hasContentTarget) return;
+
+    this.mount();
+    this.mounted.element.setAttribute("data-state", "open");
+  }
+
+  hide() {
+    this.mounted?.element.setAttribute("data-state", "closed");
+  }
+
+  animationEnd(event) {
+    if (event.animationName !== "exit") return;
+    if (this.mounted?.element.getAttribute("data-state") !== "closed") return;
+
+    this.unmount();
+  }
+
+  cloneTemplate() {
+    return this.contentTarget.content.firstElementChild.cloneNode(true);
+  }
+
+  reposition() {
+    if (!this.mounted) return;
+
+    const position = { placement: this.placementValue, middleware: [offset(4), shift()] };
+
+    computePosition(this.triggerTarget, this.mounted.element, position).then(({ x, y }) => {
+      this.mounted?.element.style.setProperty("left", `${x}px`);
+      this.mounted?.element.style.setProperty("top", `${y}px`);
     });
   }
 }
diff --git a/gem/lib/ruby_ui/tooltip/tooltip_content.rb b/gem/lib/ruby_ui/tooltip/tooltip_content.rb
index ec0e31390..386944fd6 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_content.rb
+++ b/gem/lib/ruby_ui/tooltip/tooltip_content.rb
@@ -8,7 +8,9 @@ def initialize(**attrs)
     end
 
     def view_template(&)
-      div(**attrs, &)
+      template(data: {ruby_ui__tooltip_target: "content"}) do
+        div(**attrs, &)
+      end
     end
 
     private
@@ -16,10 +18,7 @@ def view_template(&)
     def default_attrs
       {
         id: @id,
-        data: {
-          ruby_ui__tooltip_target: "content"
-        },
-        class: "invisible peer-hover:visible peer-focus:visible w-fit max-w-[calc(100vw-2rem)] text-balance break-words absolute top-0 left-0 z-50 overflow-hidden rounded-md border bg-popover px-3 py-1.5 text-sm text-popover-foreground shadow-md peer-focus:zoom-in-95 animate-out fade-out-0 zoom-out-95 peer-hover:animate-in peer-focus:animate-in peer-hover:fade-in-0 peer-focus:fade-in-0 peer-hover:zoom-in-95 group-data-[ruby-ui--tooltip-placement-value=bottom]:slide-in-from-top-2 group-data-[ruby-ui--tooltip-placement-value=left]:slide-in-from-right-2 group-data-[ruby-ui--tooltip-placement-value=right]:slide-in-from-left-2 group-data-[ruby-ui--tooltip-placement-value=top]:slide-in-from-bottom-2 delay-500"
+        class: "invisible pointer-events-none w-fit max-w-[calc(100vw-2rem)] text-balance break-words absolute top-0 left-0 z-50 overflow-hidden rounded-md border bg-popover px-3 py-1.5 text-sm text-popover-foreground shadow-md data-[state=open]:visible data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:visible data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=closed]:fill-mode-forwards data-[placement=bottom]:slide-in-from-top-2 data-[placement=left]:slide-in-from-right-2 data-[placement=right]:slide-in-from-left-2 data-[placement=top]:slide-in-from-bottom-2"
       }
     end
   end
diff --git a/gem/lib/ruby_ui/tooltip/tooltip_controller.js b/gem/lib/ruby_ui/tooltip/tooltip_controller.js
index 20ba35ce9..504242a5b 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_controller.js
+++ b/gem/lib/ruby_ui/tooltip/tooltip_controller.js
@@ -3,36 +3,72 @@ import { computePosition, autoUpdate, offset, shift } from "@floating-ui/dom";
 
 export default class extends Controller {
   static targets = ["trigger", "content"];
-  static values = { placement: String }
 
-  constructor(...args) {
-    super(...args);
-    this.cleanup;
+  static values = { placement: "top" };
+
+  mount() {
+    if (this.mounted) return;
+
+    const element = this.cloneTemplate();
+    element.setAttribute("data-placement", this.placementValue);
+    document.body.appendChild(element);
+
+    this.triggerTarget.setAttribute("aria-describedby", element.id);
+    element.addEventListener("animationend", (event) => this.animationEnd(event));
+
+    const onBeforeCache = () => this.unmount();
+    document.addEventListener("turbo:before-cache", onBeforeCache);
+
+    this.mounted = { element, onBeforeCache };
+    this.mounted.stopAutoUpdate = autoUpdate(this.triggerTarget, element, () => this.reposition());
   }
 
-  connect() {
-    this.setFloatingElement();
+  unmount() {
+    if (!this.mounted) return;
 
-    const tooltipId = this.contentTarget.getAttribute("id");
-    this.triggerTarget.setAttribute("aria-describedby", tooltipId);
+    document.removeEventListener("turbo:before-cache", this.mounted.onBeforeCache);
 
+    this.mounted.stopAutoUpdate?.();
+    this.mounted.element.remove();
+    this.triggerTarget.removeAttribute("aria-describedby");
+
+    this.mounted = null;
   }
 
   disconnect() {
-    this.cleanup();
-  }
-
-  setFloatingElement() {
-    this.cleanup = autoUpdate(this.triggerTarget, this.contentTarget, () => {
-      computePosition(this.triggerTarget, this.contentTarget, {
-        placement: this.placementValue,
-        middleware: [offset(4), shift()]
-      }).then(({ x, y }) => {
-        Object.assign(this.contentTarget.style, {
-          left: `${x}px`,
-          top: `${y}px`,
-        });
-      });
+    this.unmount();
+  }
+
+  show() {
+    if (!this.hasContentTarget) return;
+
+    this.mount();
+    this.mounted.element.setAttribute("data-state", "open");
+  }
+
+  hide() {
+    this.mounted?.element.setAttribute("data-state", "closed");
+  }
+
+  animationEnd(event) {
+    if (event.animationName !== "exit") return;
+    if (this.mounted?.element.getAttribute("data-state") !== "closed") return;
+
+    this.unmount();
+  }
+
+  cloneTemplate() {
+    return this.contentTarget.content.firstElementChild.cloneNode(true);
+  }
+
+  reposition() {
+    if (!this.mounted) return;
+
+    const position = { placement: this.placementValue, middleware: [offset(4), shift()] };
+
+    computePosition(this.triggerTarget, this.mounted.element, position).then(({ x, y }) => {
+      this.mounted?.element.style.setProperty("left", `${x}px`);
+      this.mounted?.element.style.setProperty("top", `${y}px`);
     });
   }
 }
diff --git a/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb b/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
index a535e9422..0232ae994 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
+++ b/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
@@ -10,9 +10,11 @@ def view_template(&)
 
     def default_attrs
       {
-        data: {ruby_ui__tooltip_target: "trigger"},
-        variant: :outline,
-        class: "peer"
+        data: {
+          ruby_ui__tooltip_target: "trigger",
+          action: "mouseenter->ruby-ui--tooltip#show mouseleave->ruby-ui--tooltip#hide focus->ruby-ui--tooltip#show blur->ruby-ui--tooltip#hide"
+        },
+        variant: :outline
       }
     end
   end

From 0553c87a782fe4d07ee368e1a7527f0fa401d0b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean=20Mendon=C3=A7a?= <pierrybm@gmail.com>
Date: Tue, 12 May 2026 11:35:24 -0300
Subject: [PATCH 2/2] [Refactor] Break Tooltip class and data-action strings
 into arrays

Improves readability by grouping related Tailwind variants
(placement, state) and separating each Stimulus action descriptor
on its own line.
---
 gem/lib/ruby_ui/tooltip/tooltip_content.rb | 10 +++++++++-
 gem/lib/ruby_ui/tooltip/tooltip_trigger.rb |  7 ++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/gem/lib/ruby_ui/tooltip/tooltip_content.rb b/gem/lib/ruby_ui/tooltip/tooltip_content.rb
index 386944fd6..e09a23178 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_content.rb
+++ b/gem/lib/ruby_ui/tooltip/tooltip_content.rb
@@ -18,7 +18,15 @@ def view_template(&)
     def default_attrs
       {
         id: @id,
-        class: "invisible pointer-events-none w-fit max-w-[calc(100vw-2rem)] text-balance break-words absolute top-0 left-0 z-50 overflow-hidden rounded-md border bg-popover px-3 py-1.5 text-sm text-popover-foreground shadow-md data-[state=open]:visible data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:visible data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=closed]:fill-mode-forwards data-[placement=bottom]:slide-in-from-top-2 data-[placement=left]:slide-in-from-right-2 data-[placement=right]:slide-in-from-left-2 data-[placement=top]:slide-in-from-bottom-2"
+        class: [
+          "invisible pointer-events-none w-fit max-w-[calc(100vw-2rem)] text-balance break-words absolute top-0 left-0 z-50 overflow-hidden rounded-md border bg-popover px-3 py-1.5 text-sm text-popover-foreground shadow-md",
+          "data-[placement=bottom]:slide-in-from-top-2",
+          "data-[placement=left]:slide-in-from-right-2",
+          "data-[placement=right]:slide-in-from-left-2",
+          "data-[placement=top]:slide-in-from-bottom-2",
+          "data-[state=open]:visible data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
+          "data-[state=closed]:visible data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=closed]:fill-mode-forwards"
+        ]
       }
     end
   end
diff --git a/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb b/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
index 0232ae994..473ba027a 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
+++ b/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
@@ -12,7 +12,12 @@ def default_attrs
       {
         data: {
           ruby_ui__tooltip_target: "trigger",
-          action: "mouseenter->ruby-ui--tooltip#show mouseleave->ruby-ui--tooltip#hide focus->ruby-ui--tooltip#show blur->ruby-ui--tooltip#hide"
+          action: [
+            "mouseenter->ruby-ui--tooltip#show",
+            "mouseleave->ruby-ui--tooltip#hide",
+            "focus->ruby-ui--tooltip#show",
+            "blur->ruby-ui--tooltip#hide"
+          ]
         },
         variant: :outline
       }