diff --git a/audit/component_map/tooltip.yml b/audit/component_map/tooltip.yml
new file mode 100644
index 000000000..d359fd86c
--- /dev/null
+++ b/audit/component_map/tooltip.yml
@@ -0,0 +1,32 @@
+shadcn: tooltip
+shadcn_sha: 8a3536678a528cc012b9e62484290e79d0be410f
+kind: popover
+docs_view: tooltip
+# The fixture follows shadcn's "Basic" example: an outline Button as the
+# trigger and a <p> in the content. Both sides open at once (delay 0) and stay
+# open on click (closeOnClick false / close_on_click: false) so collect's
+# click, which hovers the trigger first, reaches the open state.
+parts:
+  Tooltip: tooltip
+  TooltipTrigger: tooltip-trigger
+  TooltipContent: tooltip-content
+# TooltipTrigger is an inline-flex <div> wrapper in RubyUI; the Button inside
+# it is what shadcn renders as the trigger (render={<Button />}), so that is
+# compared. Base UI's Tooltip.Root renders no element.
+selectors:
+  Tooltip: null
+  TooltipTrigger: '[data-slot="tooltip-trigger"] > button'
+  TooltipContent: '[data-slot="tooltip-content"]'
+# side/sideOffset/align/alignOffset from the .tsx (TooltipContent);
+# delay/closeDelay/closeOnClick from the Base UI Tooltip.Trigger;
+# open/defaultOpen/onOpenChange/disabled from Tooltip.Root (RubyUI's open: is
+# the initial state; the open value attribute and the change event cover the
+# controlled use).
+props:
+  Tooltip: {open: null, defaultOpen: open, onOpenChange: null, disabled: disabled}
+  TooltipTrigger: {delay: delay, closeDelay: close_delay, closeOnClick: close_on_click}
+  TooltipContent: {side: side, sideOffset: side_offset, align: align, alignOffset: align_offset}
+# placement: is the older API (TooltipContent side: wins over it).
+rubyui_only:
+  Tooltip: [placement]
+fixture_shadcn: [button]
diff --git a/audit/fixtures/tooltip/content.yml b/audit/fixtures/tooltip/content.yml
new file mode 100644
index 000000000..466a3a75e
--- /dev/null
+++ b/audit/fixtures/tooltip/content.yml
@@ -0,0 +1,3 @@
+# Same strings on both sides. Follows shadcn's tooltip "Basic" example.
+trigger: Show Tooltip
+body: Add to library
diff --git a/audit/fixtures/tooltip/rubyui.rb b/audit/fixtures/tooltip/rubyui.rb
new file mode 100644
index 000000000..8fde3d84c
--- /dev/null
+++ b/audit/fixtures/tooltip/rubyui.rb
@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ShadcnAuditFixtures
+  # RubyUI side of audit/fixtures/tooltip (strings in content.yml).
+  # close_on_click: false matches the shadcn side, so collect's click leaves it open.
+  class Tooltip < Phlex::HTML
+    include RubyUI
+
+    def view_template
+      Tooltip do
+        TooltipTrigger(close_on_click: false) do
+          Button(variant: :outline, class: "w-fit", data: {audit_trigger: true}) { "Show Tooltip" }
+        end
+        TooltipContent do
+          p { "Add to library" }
+        end
+      end
+    end
+  end
+end
diff --git a/audit/fixtures/tooltip/shadcn.tsx b/audit/fixtures/tooltip/shadcn.tsx
new file mode 100644
index 000000000..0db95d516
--- /dev/null
+++ b/audit/fixtures/tooltip/shadcn.tsx
@@ -0,0 +1,28 @@
+import { Button } from "@/components/ui/button"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+
+// shadcn's "Basic" example inside its TooltipProvider (delay 0). closeOnClick
+// is off so collect's click (a hover, then a press) leaves it open.
+export default function TooltipFixture() {
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger
+          closeOnClick={false}
+          data-audit-trigger=""
+          render={<Button variant="outline" className="w-fit" />}
+        >
+          Show Tooltip
+        </TooltipTrigger>
+        <TooltipContent>
+          <p>Add to library</p>
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}
diff --git a/docs/app/views/docs/tooltip.rb b/docs/app/views/docs/tooltip.rb
index 9a4ec1195..feb02c098 100644
--- a/docs/app/views/docs/tooltip.rb
+++ b/docs/app/views/docs/tooltip.rb
@@ -9,29 +9,113 @@ def view_template
 
       Heading(level: 2) { "Usage" }
 
-      render Docs::VisualCodeExample.new(title: "Example", context: self) do
+      render Docs::VisualCodeExample.new(title: "Example", description: "The tooltip opens while the pointer rests on the trigger or when the trigger gets keyboard focus. The pointer can move onto the tooltip; it closes when the pointer leaves both, on blur (unless the pointer is still over it), on Escape, or when the trigger is pressed. The trigger's button is described by the tooltip (aria-describedby).", context: self) do
         <<~RUBY
           Tooltip do
             TooltipTrigger do
-              Button(variant: :outline, icon: true) do
+              Button(variant: :outline) { "Show Tooltip" }
+            end
+            TooltipContent do
+              p { "Add to library" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Sides", description: "side: places the tooltip around the trigger: :top (the default), :right, :bottom, :left, or the logical :inline_start and :inline_end, which follow the writing direction. side_offset: is the gap in pixels (4 by default); align: (:start, :center, :end) and align_offset: line it up along that edge. It flips to the other side when there is no room.", context: self) do
+        <<~RUBY
+          div(class: "flex flex-wrap gap-2") do
+            [:inline_start, :left, :top, :bottom, :right, :inline_end].each do |side|
+              Tooltip do
+                TooltipTrigger do
+                  Button(variant: :outline, class: "capitalize") { side.to_s.tr("_", " ") }
+                end
+                TooltipContent(side: side) do
+                  p { "Add to library" }
+                end
+              end
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "With icon", description: "An icon-only trigger still needs an accessible name: the tooltip describes the button, it doesn't name it.", context: self) do
+        <<~RUBY
+          Tooltip do
+            TooltipTrigger do
+              Button(variant: :ghost, icon: true) do
                 bookmark_icon
+                span(class: "sr-only") { "Bookmark" }
               end
             end
             TooltipContent do
-              Text { "Add to library" }
+              p { "Add to library" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Long content", description: "Long text wraps at 20rem.", context: self) do
+        <<~RUBY
+          Tooltip do
+            TooltipTrigger do
+              Button(variant: :outline) { "Show Tooltip" }
+            end
+            TooltipContent do
+              plain "To learn more about how this works, check out the docs. If you have any questions, please reach out to us."
             end
           end
         RUBY
       end
 
-      render Docs::VisualCodeExample.new(title: "Long content", context: self) do
+      render Docs::VisualCodeExample.new(title: "Disabled button", description: "A disabled button gets no pointer events, so the wrapper still opens the tooltip on hover.", context: self) do
         <<~RUBY
           Tooltip do
             TooltipTrigger do
-              Button(variant: :outline) { "Hover me" }
+              Button(variant: :outline, disabled: true) { "Disabled" }
+            end
+            TooltipContent do
+              p { "This feature is currently unavailable" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "With keyboard shortcut", context: self) do
+        <<~RUBY
+          Tooltip do
+            TooltipTrigger do
+              Button(variant: :outline, size: :sm) { "Save" }
+            end
+            TooltipContent do
+              plain "Save Changes"
+              ShortcutKey { "S" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Delay and click", description: "delay: waits that many milliseconds of pointer rest before opening (0 by default), close_delay: waits before closing (0 by default, plus a 100 ms grace to cross onto the tooltip). close_on_click: false keeps it open when the trigger is pressed.", context: self) do
+        <<~RUBY
+          Tooltip do
+            TooltipTrigger(delay: 500, close_on_click: false) do
+              Button(variant: :outline) { "Hover and wait" }
+            end
+            TooltipContent do
+              p { "Opened after 500 ms" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Disabled tooltip", description: "disabled: true keeps the tooltip from opening. open: true renders it open on load. Changing the data-ruby-ui--tooltip-open-value or -disabled-value attribute later opens, closes or disables it, and each open or close dispatches ruby-ui--tooltip:change with detail.open.", context: self) do
+        <<~RUBY
+          Tooltip(disabled: true) do
+            TooltipTrigger do
+              Button(variant: :outline) { "No tooltip" }
             end
             TooltipContent do
-              Text { "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." }
+              p { "You won't see this" }
             end
           end
         RUBY
diff --git a/gem/lib/ruby_ui/sidebar/sidebar_menu_button.rb b/gem/lib/ruby_ui/sidebar/sidebar_menu_button.rb
index 95cdd1f7e..2cd8693cd 100644
--- a/gem/lib/ruby_ui/sidebar/sidebar_menu_button.rb
+++ b/gem/lib/ruby_ui/sidebar/sidebar_menu_button.rb
@@ -16,10 +16,12 @@ class SidebarMenuButton < Base
       lg: "h-12 text-sm group-data-[collapsible=icon]:!p-0"
     }.freeze
 
-    # The tooltip is cloned into <body>, outside the sidebar, so it hides itself
-    # with a body-level selector: only shown while a desktop sidebar is
-    # collapsed (shadcn: hidden={state !== "collapsed" || isMobile}).
-    TOOLTIP_CLASSES = "[body:has([data-slot=sidebar][data-state=expanded])_&]:hidden max-md:hidden"
+    # The tooltip controller places the content right after this button, inside
+    # its own sidebar, so it hides from that sidebar's state alone: shown only
+    # while the desktop sidebar around it is collapsed (shadcn:
+    # hidden={state !== "collapsed" || isMobile}). A second, expanded sidebar
+    # on the page no longer hides it.
+    TOOLTIP_CLASSES = "[[data-slot=sidebar]:not([data-state=collapsed])_&]:hidden max-md:hidden"
 
     # tooltip: label shown on the right when the sidebar is collapsed to icons.
     def initialize(as: :button, variant: :default, size: :default, active: false, tooltip: nil, **attrs)
@@ -39,7 +41,7 @@ def view_template(&block)
 
       tag(@as, **mix(attrs, tooltip_attrs)) do
         # First child, so [&>span:last-child]:truncate still finds the label.
-        TooltipContent(class: TOOLTIP_CLASSES) { @tooltip }
+        TooltipContent(side: :right, class: TOOLTIP_CLASSES) { @tooltip }
         yield if block
       end
     end
@@ -50,14 +52,7 @@ def tooltip_attrs
       {
         data: {
           controller: "ruby-ui--tooltip",
-          ruby_ui__tooltip_placement_value: "right",
-          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"
-          ]
+          ruby_ui__tooltip_target: "trigger"
         }
       }
     end
diff --git a/gem/lib/ruby_ui/tooltip/tooltip.rb b/gem/lib/ruby_ui/tooltip/tooltip.rb
index 70b40dc30..99f05bfad 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip.rb
+++ b/gem/lib/ruby_ui/tooltip/tooltip.rb
@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
 module RubyUI
+  # Root of the tooltip: scopes the trigger and the content for the Stimulus
+  # controller. open: renders it open on load (Base UI's defaultOpen) and
+  # disabled: keeps it from opening (Base UI's Root disabled). Setting the
+  # data-ruby-ui--tooltip-open-value or -disabled-value attribute later
+  # opens, closes or disables it; each open or close dispatches
+  # ruby-ui--tooltip:change with detail {open:}.
+  #
+  # placement: is the older API: TooltipContent's side: wins over it.
   class Tooltip < Base
-    def initialize(placement: "top", **attrs)
+    def initialize(placement: nil, open: false, disabled: false, **attrs)
       @placement = placement
+      @open = open
+      @disabled = disabled
       super(**attrs)
     end
 
@@ -16,8 +26,11 @@ def view_template(&)
     def default_attrs
       {
         data: {
+          slot: "tooltip",
           controller: "ruby-ui--tooltip",
-          ruby_ui__tooltip_placement_value: @placement
+          ruby_ui__tooltip_placement_value: @placement&.to_s,
+          ruby_ui__tooltip_open_value: (!!@open).to_s,
+          ruby_ui__tooltip_disabled_value: (!!@disabled).to_s
         },
         class: "group"
       }
diff --git a/gem/lib/ruby_ui/tooltip/tooltip_content.rb b/gem/lib/ruby_ui/tooltip/tooltip_content.rb
index e09a23178..e652fb0bf 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_content.rb
+++ b/gem/lib/ruby_ui/tooltip/tooltip_content.rb
@@ -1,31 +1,82 @@
 # frozen_string_literal: true
 
 module RubyUI
+  # The popup, kept in a <template> until the controller connects. The
+  # controller places the copy right after the trigger, so it stays inside
+  # the same container (a Sidebar hides its own tooltips from its state), and
+  # opens it as a native popover="manual" in the top layer, where no ancestor
+  # with overflow: hidden clips it. role="tooltip"; the trigger's focusable
+  # element points at it with aria-describedby.
+  #
+  # side:/align: pick the placement (side also takes the logical
+  # :inline_start / :inline_end), side_offset:/align_offset: the gap, with the
+  # defaults of shadcn's TooltipContent. Without side:, Tooltip's placement:
+  # applies, then top. It flips to the other side when there is no room.
   class TooltipContent < Base
-    def initialize(**attrs)
-      @id = "tooltip#{SecureRandom.hex(4)}"
-      super
+    SIDES = %i[top right bottom left inline_start inline_end].freeze
+    ALIGNS = %i[start center end].freeze
+
+    def initialize(side: nil, side_offset: 4, align: nil, align_offset: 0, **attrs)
+      @id = "tooltip-#{SecureRandom.hex(4)}"
+      @side = SIDES.include?(side&.to_sym) ? side.to_s.tr("_", "-") : nil
+      @align = ALIGNS.include?(align&.to_sym) ? align.to_s : nil
+      @side_offset = side_offset
+      @align_offset = align_offset
+      super(**attrs)
     end
 
-    def view_template(&)
+    def view_template(&block)
       template(data: {ruby_ui__tooltip_target: "content"}) do
-        div(**attrs, &)
+        div(**attrs) do
+          yield if block
+          span(**arrow_attrs)
+        end
       end
     end
 
     private
 
+    def arrow_attrs
+      {
+        aria: {hidden: "true"},
+        data: {slot: "tooltip-arrow"},
+        class: [
+          "absolute z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground",
+          "data-[side=bottom]:top-1 data-[side=top]:-bottom-2.5",
+          "data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2",
+          # The controller writes the physical side, so logical sides point right in RTL too.
+          "data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2"
+        ]
+      }
+    end
+
     def default_attrs
       {
         id: @id,
+        popover: "manual",
+        role: "tooltip",
+        data: {
+          slot: "tooltip-content",
+          # Kept in sync with data-open/data-closed for CSS that targets data-[state=...].
+          state: "closed",
+          closed: "",
+          preferred_side: @side,
+          preferred_align: @align,
+          side_offset: @side_offset,
+          align_offset: @align_offset
+        },
         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"
+          # Resets the UA popover box (overflow too, or it clips the arrow);
+          # inline-flex must not beat the UA's hidden closed popover.
+          "fixed inset-auto m-0 border-0 overflow-visible [&:not(:popover-open)]:hidden",
+          "z-50 w-fit max-w-xs origin-(--transform-origin) bg-foreground text-background",
+          "inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs",
+          "has-data-[slot=kbd]:pr-1.5 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm",
+          "data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95",
+          "data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 data-closed:fill-mode-forwards",
+          "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2",
+          "data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+          "data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2"
         ]
       }
     end
diff --git a/gem/lib/ruby_ui/tooltip/tooltip_controller.js b/gem/lib/ruby_ui/tooltip/tooltip_controller.js
index 6eae0edab..eb1a30ee2 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_controller.js
+++ b/gem/lib/ruby_ui/tooltip/tooltip_controller.js
@@ -1,77 +1,456 @@
 import { Controller } from "@hotwired/stimulus";
-import { computePosition, autoUpdate, offset, shift } from "@floating-ui/dom";
+import { computePosition, autoUpdate, offset, flip, shift, arrow } from "@floating-ui/dom";
+
+// Connects to data-controller="ruby-ui--tooltip"
+//
+// Behaves like Base UI's Tooltip: it opens while the pointer rests on the
+// trigger (after delay) or when the trigger gets keyboard focus, and closes
+// when the pointer leaves both the trigger and the content, on blur, on
+// Escape, or when the trigger is pressed (close_on_click). The pointer can
+// move onto the content without closing it (WCAG 1.4.13).
+//
+// TooltipContent ships in a <template>. On connect the controller places a
+// copy right after the trigger, so it stays inside the same container (a
+// Sidebar hides its tooltips from its own data-state), and opens it as a
+// native popover="manual" in the top layer; Floating UI places it next to
+// the trigger. The content has role="tooltip" and the trigger's focusable
+// element points at it with aria-describedby, as the APG tooltip pattern
+// asks (Base UI leaves both out).
+const SIDES = ["top", "right", "bottom", "left", "inline-start", "inline-end"];
+const ALIGNS = ["start", "center", "end"];
+const FOCUSABLE = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+// The pointer needs a moment to cross the gap between trigger and content.
+const HOVER_GRACE = 100;
 
 export default class extends Controller {
   static targets = ["trigger", "content"];
+  static values = {
+    placement: { type: String, default: "top" },
+    open: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+  };
 
-  static values = { placement: "top" };
+  // The copy of the content template that lives in the page.
+  popup = null;
+  isOpen = false;
 
-  mount() {
-    if (this.mounted) return;
+  connect() {
+    document.addEventListener("turbo:before-cache", this.handleBeforeCache);
+    this.mount();
+    if (this.openValue && !this.disabledValue) this.open();
+    this.ready = true;
+  }
+
+  disconnect() {
+    this.ready = false;
+    document.removeEventListener("turbo:before-cache", this.handleBeforeCache);
+    this.unmount();
+    // Stimulus reuses this instance if the element comes back.
+    this.pointerInside = false;
+    this.pressedClosed = false;
+  }
+
+  // Target callbacks run before connect() and again whenever Turbo or other
+  // code swaps the trigger or the content inside a connected tooltip.
+  triggerTargetConnected(trigger) {
+    trigger.addEventListener("mouseenter", this.handleEnter);
+    trigger.addEventListener("mouseleave", this.handleLeave);
+    trigger.addEventListener("focusin", this.handleFocusIn);
+    trigger.addEventListener("focusout", this.handleFocusOut);
+    trigger.addEventListener("click", this.handleClick);
+    if (this.ready) this.remount();
+  }
+
+  triggerTargetDisconnected(trigger) {
+    trigger.removeEventListener("mouseenter", this.handleEnter);
+    trigger.removeEventListener("mouseleave", this.handleLeave);
+    trigger.removeEventListener("focusin", this.handleFocusIn);
+    trigger.removeEventListener("focusout", this.handleFocusOut);
+    trigger.removeEventListener("click", this.handleClick);
+    // The copy sits next to (and is placed against) this trigger.
+    if (this.popup && this.mountedTrigger === trigger) this.unmount();
+  }
+
+  contentTargetConnected() {
+    if (this.ready) this.remount();
+  }
+
+  contentTargetDisconnected(template) {
+    if (this.popup && this.mountedTemplate === template) this.unmount();
+  }
+
+  openValueChanged(open) {
+    if (!this.ready) return;
+    open ? this.open() : this.close();
+  }
+
+  disabledValueChanged(disabled) {
+    if (!this.ready) return;
+    // An open value set while disabled takes effect once enabled again.
+    if (disabled) {
+      this.close();
+    } else if (this.openValue) {
+      this.open();
+    }
+  }
+
+  // Kept for markup that still wires data-action to show/hide.
+  show() {
+    this.open();
+  }
 
-    const element = this.cloneTemplate();
-    element.setAttribute("data-placement", this.placementValue);
-    document.body.appendChild(element);
+  hide() {
+    this.close();
+  }
 
-    this.triggerTarget.setAttribute("aria-describedby", element.id);
-    // animationcancel covers an exit run cut short (backgrounded tab, interrupting
-    // style change) — without it the cloned node is never removed from <body>.
-    element.addEventListener("animationend", this.handleExitAnimationEnd);
-    element.addEventListener("animationcancel", this.handleExitAnimationEnd);
+  // --- Mounting -----------------------------------------------------------------
 
-    const onBeforeCache = () => this.unmount();
-    document.addEventListener("turbo:before-cache", onBeforeCache);
+  mount() {
+    if (this.popup || !this.hasContentTarget || !this.hasTriggerTarget) return;
+    const template = this.contentTarget;
+    const trigger = this.triggerTarget;
+    const popup = template.content?.firstElementChild?.cloneNode(true);
+    if (!popup) return;
 
-    this.mounted = { element, onBeforeCache };
-    this.mounted.stopAutoUpdate = autoUpdate(this.triggerTarget, element, () => this.reposition());
+    popup.addEventListener("mouseenter", this.handleEnter);
+    popup.addEventListener("mouseleave", this.handleLeave);
+    trigger.after(popup);
+    this.popup = popup;
+    this.mountedTrigger = trigger;
+    this.mountedTemplate = template;
+    this.describe(trigger, popup);
   }
 
   unmount() {
-    if (!this.mounted) return;
+    const popup = this.popup;
+    if (!popup) return;
+    this.close({ animate: false });
+    popup.removeEventListener("mouseenter", this.handleEnter);
+    popup.removeEventListener("mouseleave", this.handleLeave);
+    this.undescribe();
+    popup.remove();
+    this.popup = null;
+    this.mountedTrigger = null;
+    this.mountedTemplate = null;
+  }
 
-    document.removeEventListener("turbo:before-cache", this.mounted.onBeforeCache);
+  // A swapped trigger or content while open stays open, without telling
+  // listeners about a close and reopen that never happened.
+  remount() {
+    const wasOpen = this.isOpen;
+    this.remounting = wasOpen;
+    try {
+      this.unmount();
+      this.mount();
+      if (wasOpen) this.open();
+    } finally {
+      this.remounting = false;
+    }
+  }
 
-    this.mounted.stopAutoUpdate?.();
-    this.mounted.element.remove();
-    this.triggerTarget.removeAttribute("aria-describedby");
+  // --- aria-describedby ---------------------------------------------------------
 
-    this.mounted = null;
+  // The element inside the trigger that receives focus (the Button), else the wrapper.
+  controlFor(trigger) {
+    return trigger.matches(FOCUSABLE) ? trigger : trigger.querySelector(FOCUSABLE) || trigger;
   }
 
-  disconnect() {
-    this.unmount();
+  // Adds the content's id to the control's aria-describedby, keeping a
+  // caller's own ids. Skipped when the tooltip only repeats the control's
+  // text (SidebarMenuButton's label): the description would say it twice.
+  describe(trigger, popup) {
+    const control = this.controlFor(trigger);
+    const text = (element) => element.textContent.replace(/\s+/g, " ").trim().toLowerCase();
+    if (text(popup) !== "" && text(popup) === text(control)) return;
+
+    const ids = (control.getAttribute("aria-describedby") || "").split(/\s+/).filter(Boolean);
+    if (!ids.includes(popup.id)) control.setAttribute("aria-describedby", [...ids, popup.id].join(" "));
+    this.describedControl = control;
   }
 
-  show() {
-    if (!this.hasContentTarget) return;
+  undescribe() {
+    const control = this.describedControl;
+    this.describedControl = null;
+    if (!control || !this.popup) return;
+    const ids = (control.getAttribute("aria-describedby") || "").split(/\s+/).filter((id) => id && id !== this.popup.id);
+    ids.length ? control.setAttribute("aria-describedby", ids.join(" ")) : control.removeAttribute("aria-describedby");
+  }
 
-    this.mount();
-    this.mounted.element.setAttribute("data-state", "open");
+  // --- Pointer, focus, click, Escape --------------------------------------------
+
+  triggerSetting(key, fallback) {
+    const own = this.mountedTrigger?.dataset[key];
+    return own !== undefined && own !== "" ? own : fallback;
   }
 
-  hide() {
-    this.mounted?.element.setAttribute("data-state", "closed");
+  get openDelay() {
+    return Number(this.triggerSetting("delay", 0)) || 0;
   }
 
-  handleExitAnimationEnd = (event) => {
-    if (event.animationName !== "exit") return;
-    if (this.mounted?.element.getAttribute("data-state") !== "closed") return;
+  get closeDelay() {
+    return Number(this.triggerSetting("closeDelay", 0)) || 0;
+  }
+
+  get closeOnClick() {
+    return this.triggerSetting("closeOnClick", "true") !== "false";
+  }
+
+  handleEnter = (event) => {
+    this.pointerInside = true;
+    this.clearTimers();
+    // After close_on_click, the pointer has to leave the trigger before it opens again.
+    if (this.isOpen || this.pressedClosed || this.disabledValue) return;
+    if (event.currentTarget === this.popup) return;
+    const delay = this.openDelay;
+    if (delay > 0) {
+      this.openTimeout = setTimeout(() => this.open(), delay);
+    } else {
+      this.open();
+    }
+  };
+
+  handleLeave = (event) => {
+    this.pointerInside = false;
+    if (event.currentTarget === this.mountedTrigger) this.pressedClosed = false;
+    this.clearTimers();
+    if (!this.isOpen || this.keyboardFocusInside()) return;
+    this.closeTimeout = setTimeout(() => this.close(), this.closeDelay + HOVER_GRACE);
+  };
+
+  // Opens on keyboard focus only, as Base UI does: a click focuses the button too.
+  handleFocusIn = (event) => {
+    if (this.disabledValue || this.isOpen || !this.isFocusVisible(event.target)) return;
+    this.clearTimers();
+    this.open();
+  };
+
+  handleFocusOut = (event) => {
+    if (this.mountedTrigger?.contains(event.relatedTarget)) return;
+    if (this.pointerInside) return;
+    this.close();
+  };
+
+  // Enter and Space on the trigger's button arrive here as a click too. A
+  // press during the open delay cancels the pending open as well.
+  handleClick = () => {
+    if (!this.closeOnClick) return;
+    this.clearTimers();
+    this.pressedClosed = this.pointerInside;
+    this.close();
+  };
+
+  handleKeydown = (event) => {
+    if (event.key !== "Escape" || !this.isOpen) return;
+    // A tooltip hidden by CSS (an expanded or mobile sidebar) closes without
+    // taking the key, so an enclosing Sheet or dialog still gets it.
+    // A visible one keeps an enclosing <dialog> from closing on the same key.
+    if (this.isRendered(this.popup)) event.preventDefault();
+    this.close();
+  };
 
+  handleBeforeCache = () => {
+    // The snapshot keeps the <template>; connect() places a fresh copy on restore.
     this.unmount();
   };
 
-  cloneTemplate() {
-    return this.contentTarget.content.firstElementChild.cloneNode(true);
+  isRendered(element) {
+    return Boolean(element?.isConnected && element.getClientRects().length > 0);
+  }
+
+  keyboardFocusInside() {
+    const active = document.activeElement;
+    return Boolean(active && this.mountedTrigger?.contains(active) && this.isFocusVisible(active));
+  }
+
+  isFocusVisible(element) {
+    try {
+      return element.matches(":focus-visible");
+    } catch {
+      return true;
+    }
+  }
+
+  clearTimers() {
+    clearTimeout(this.openTimeout);
+    clearTimeout(this.closeTimeout);
+  }
+
+  // --- Opening and closing ------------------------------------------------------
+
+  open() {
+    if (this.isOpen || this.disabledValue) return;
+    this.mount();
+    const popup = this.popup;
+    if (!popup || !popup.isConnected) return;
+    this.clearTimers();
+    this.isOpen = true;
+
+    // Side and origin before the enter animation starts; position() refines both.
+    const { side, align } = this.preferredPlacement(popup);
+    popup.dataset.side = side;
+    popup.dataset.align = align;
+    popup.removeAttribute("data-closed");
+    popup.setAttribute("data-open", "");
+    popup.dataset.state = "open";
+    if (!popup.matches(":popover-open")) popup.showPopover();
+
+    document.addEventListener("keydown", this.handleKeydown);
+    this.startPositioning();
+    this.setOpenValue(true);
+  }
+
+  close({ animate = true } = {}) {
+    this.clearTimers();
+    if (!this.isOpen) return;
+    const popup = this.popup;
+    this.isOpen = false;
+    document.removeEventListener("keydown", this.handleKeydown);
+    this.stopPositioning();
+
+    popup.removeAttribute("data-open");
+    popup.setAttribute("data-closed", "");
+    popup.dataset.state = "closed";
+    animate ? this.hideAfterExitAnimation(popup) : this.settleExit(popup);
+    this.setOpenValue(false);
+  }
+
+  // Mirrors the state on the open value (so openValueChanged sees no change)
+  // and tells listeners, as Base UI's onOpenChange does.
+  setOpenValue(open) {
+    if (this.remounting) return;
+    if (this.openValue !== open) this.openValue = open;
+    this.dispatch("change", { detail: { open } });
+  }
+
+  // --- Positioning --------------------------------------------------------------
+
+  // TooltipContent side:/align:, else Tooltip placement:, else top/center.
+  preferredPlacement(popup) {
+    // Logical sides keep their hyphen: "inline-start" is a side, not side-align.
+    const placement = String(this.placementValue || "");
+    const [placementSide, placementAlign] = placement.startsWith("inline-") ? [placement] : placement.split("-");
+    const side = [popup.dataset.preferredSide, placementSide].find((value) => SIDES.includes(value)) || "top";
+    const align = popup.dataset.preferredSide
+      ? popup.dataset.preferredAlign || "center"
+      : [popup.dataset.preferredAlign, placementAlign].find((value) => ALIGNS.includes(value)) || "center";
+    return { side, align };
+  }
+
+  // inline-start / inline-end follow the trigger's writing direction.
+  physicalSide(side, trigger) {
+    if (!side.startsWith("inline-")) return side;
+    const rtl = getComputedStyle(trigger).direction === "rtl";
+    return (side === "inline-start") !== rtl ? "left" : "right";
   }
 
-  reposition() {
-    if (!this.mounted) return;
+  startPositioning() {
+    this.stopPositioning();
+    const trigger = this.mountedTrigger;
+    const popup = this.popup;
+    const anchor = this.controlFor(trigger);
+    this.cleanup = autoUpdate(anchor, popup, () => this.position(anchor, popup));
+  }
+
+  stopPositioning() {
+    if (this.cleanup) this.cleanup();
+    this.cleanup = null;
+  }
 
-    const position = { placement: this.placementValue, middleware: [offset(4), shift()] };
+  position(anchor, popup) {
+    const { side, align } = this.preferredPlacement(popup);
+    const physical = this.physicalSide(side, anchor);
+    const placement = align === "center" ? physical : `${physical}-${align}`;
+    const sideOffset = Number(popup.dataset.sideOffset ?? 4);
+    const alignOffset = Number(popup.dataset.alignOffset ?? 0);
+    const arrowElement = popup.querySelector('[data-slot="tooltip-arrow"]');
+
+    const middleware = [
+      // crossAxis shifts a centered tooltip; alignmentAxis takes over for
+      // :start / :end and flips the offset for :end, as Base UI does.
+      offset({ mainAxis: sideOffset, crossAxis: alignOffset, alignmentAxis: alignOffset }),
+      flip(),
+      shift({ padding: 5 }),
+    ];
+    if (arrowElement) middleware.push(arrow({ element: arrowElement, padding: 5 }));
+
+    computePosition(anchor, popup, { strategy: "fixed", placement, middleware }).then(
+      ({ x, y, placement: resolved, middlewareData }) => {
+        if (!popup.isConnected || popup !== this.popup || !this.isOpen) return;
+        const [resolvedSide, resolvedAlign = "center"] = resolved.split("-");
+        Object.assign(popup.style, { left: `${x}px`, top: `${y}px` });
+        // A logical side keeps its logical name, flipped to the other one if Floating UI flipped.
+        const finalSide = side.startsWith("inline-")
+          ? resolvedSide === physical ? side : side === "inline-start" ? "inline-end" : "inline-start"
+          : resolvedSide;
+        popup.dataset.side = finalSide;
+        popup.dataset.align = resolvedAlign;
+        if (arrowElement) this.placeArrow(arrowElement, resolvedSide, resolvedAlign, middlewareData.arrow);
+        popup.style.setProperty("--transform-origin", this.transformOrigin(anchor, popup, resolvedSide, x, y, sideOffset));
+      },
+    );
+  }
+
+  // Along the trigger for top/bottom; the classes center it for left/right.
+  // The arrow takes the physical side, so a logical side points the right
+  // way in RTL too.
+  placeArrow(arrowElement, physical, align, data = {}) {
+    arrowElement.dataset.side = physical;
+    arrowElement.dataset.align = align;
+    const vertical = physical === "top" || physical === "bottom";
+    arrowElement.style.left = vertical && data.x != null ? `${data.x}px` : "";
+    arrowElement.style.top = !vertical && data.y != null ? `${data.y}px` : "";
+  }
+
+  // The content grows out of the trigger: the origin sits on the trigger's
+  // center line, at the gap between the two (Base UI's --transform-origin).
+  transformOrigin(anchor, popup, side, x, y, sideOffset) {
+    const rect = anchor.getBoundingClientRect();
+    const { width, height } = popup.getBoundingClientRect();
+    const centerX = rect.left + rect.width / 2 - x;
+    const centerY = rect.top + rect.height / 2 - y;
+    switch (side) {
+      case "top":
+        return `${centerX}px ${height + sideOffset}px`;
+      case "left":
+        return `${width + sideOffset}px ${centerY}px`;
+      case "right":
+        return `${-sideOffset}px ${centerY}px`;
+      default:
+        return `${centerX}px ${-sideOffset}px`;
+    }
+  }
+
+  // --- Exit animation (same block as the other overlay controllers) ------------
+
+  exitAnimationNames = new WeakMap();
+
+  hideAfterExitAnimation(animated) {
+    const exitAnimations = animated.getAnimations().filter((animation) => animation instanceof CSSAnimation);
+    // No exit animation, or no box to run it in (hidden by CSS): animationend would never fire.
+    if (exitAnimations.length === 0) {
+      this.settleExit(animated);
+      return;
+    }
+    this.exitAnimationNames.set(animated, exitAnimations.map((animation) => animation.animationName));
+    animated.addEventListener("animationend", this.handleExitAnimationEnd);
+    animated.addEventListener("animationcancel", this.handleExitAnimationEnd);
+  }
+
+  handleExitAnimationEnd = (event) => {
+    // animationend bubbles — an animated child must not hide its container.
+    if (event.target !== event.currentTarget) return;
+    // Closing mid-open cancels the enter animation; only the exit run settles this.
+    if (!this.exitAnimationNames.get(event.currentTarget)?.includes(event.animationName)) return;
+    this.settleExit(event.currentTarget);
+  };
 
-    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`);
-    });
+  settleExit(animated) {
+    animated.removeEventListener("animationend", this.handleExitAnimationEnd);
+    animated.removeEventListener("animationcancel", this.handleExitAnimationEnd);
+    // Reopened mid-exit: it is on its way back in, leave it showing.
+    if (animated.hasAttribute("data-open")) return;
+    animated.setAttribute("data-closed", "");
+    animated.dataset.state = "closed";
+    if (animated.matches(":popover-open")) animated.hidePopover();
   }
 }
diff --git a/gem/lib/ruby_ui/tooltip/tooltip_docs.rb b/gem/lib/ruby_ui/tooltip/tooltip_docs.rb
index 9a4ec1195..feb02c098 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_docs.rb
+++ b/gem/lib/ruby_ui/tooltip/tooltip_docs.rb
@@ -9,29 +9,113 @@ def view_template
 
       Heading(level: 2) { "Usage" }
 
-      render Docs::VisualCodeExample.new(title: "Example", context: self) do
+      render Docs::VisualCodeExample.new(title: "Example", description: "The tooltip opens while the pointer rests on the trigger or when the trigger gets keyboard focus. The pointer can move onto the tooltip; it closes when the pointer leaves both, on blur (unless the pointer is still over it), on Escape, or when the trigger is pressed. The trigger's button is described by the tooltip (aria-describedby).", context: self) do
         <<~RUBY
           Tooltip do
             TooltipTrigger do
-              Button(variant: :outline, icon: true) do
+              Button(variant: :outline) { "Show Tooltip" }
+            end
+            TooltipContent do
+              p { "Add to library" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Sides", description: "side: places the tooltip around the trigger: :top (the default), :right, :bottom, :left, or the logical :inline_start and :inline_end, which follow the writing direction. side_offset: is the gap in pixels (4 by default); align: (:start, :center, :end) and align_offset: line it up along that edge. It flips to the other side when there is no room.", context: self) do
+        <<~RUBY
+          div(class: "flex flex-wrap gap-2") do
+            [:inline_start, :left, :top, :bottom, :right, :inline_end].each do |side|
+              Tooltip do
+                TooltipTrigger do
+                  Button(variant: :outline, class: "capitalize") { side.to_s.tr("_", " ") }
+                end
+                TooltipContent(side: side) do
+                  p { "Add to library" }
+                end
+              end
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "With icon", description: "An icon-only trigger still needs an accessible name: the tooltip describes the button, it doesn't name it.", context: self) do
+        <<~RUBY
+          Tooltip do
+            TooltipTrigger do
+              Button(variant: :ghost, icon: true) do
                 bookmark_icon
+                span(class: "sr-only") { "Bookmark" }
               end
             end
             TooltipContent do
-              Text { "Add to library" }
+              p { "Add to library" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Long content", description: "Long text wraps at 20rem.", context: self) do
+        <<~RUBY
+          Tooltip do
+            TooltipTrigger do
+              Button(variant: :outline) { "Show Tooltip" }
+            end
+            TooltipContent do
+              plain "To learn more about how this works, check out the docs. If you have any questions, please reach out to us."
             end
           end
         RUBY
       end
 
-      render Docs::VisualCodeExample.new(title: "Long content", context: self) do
+      render Docs::VisualCodeExample.new(title: "Disabled button", description: "A disabled button gets no pointer events, so the wrapper still opens the tooltip on hover.", context: self) do
         <<~RUBY
           Tooltip do
             TooltipTrigger do
-              Button(variant: :outline) { "Hover me" }
+              Button(variant: :outline, disabled: true) { "Disabled" }
+            end
+            TooltipContent do
+              p { "This feature is currently unavailable" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "With keyboard shortcut", context: self) do
+        <<~RUBY
+          Tooltip do
+            TooltipTrigger do
+              Button(variant: :outline, size: :sm) { "Save" }
+            end
+            TooltipContent do
+              plain "Save Changes"
+              ShortcutKey { "S" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Delay and click", description: "delay: waits that many milliseconds of pointer rest before opening (0 by default), close_delay: waits before closing (0 by default, plus a 100 ms grace to cross onto the tooltip). close_on_click: false keeps it open when the trigger is pressed.", context: self) do
+        <<~RUBY
+          Tooltip do
+            TooltipTrigger(delay: 500, close_on_click: false) do
+              Button(variant: :outline) { "Hover and wait" }
+            end
+            TooltipContent do
+              p { "Opened after 500 ms" }
+            end
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Disabled tooltip", description: "disabled: true keeps the tooltip from opening. open: true renders it open on load. Changing the data-ruby-ui--tooltip-open-value or -disabled-value attribute later opens, closes or disables it, and each open or close dispatches ruby-ui--tooltip:change with detail.open.", context: self) do
+        <<~RUBY
+          Tooltip(disabled: true) do
+            TooltipTrigger do
+              Button(variant: :outline) { "No tooltip" }
             end
             TooltipContent do
-              Text { "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." }
+              p { "You won't see this" }
             end
           end
         RUBY
diff --git a/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb b/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
index 473ba027a..4820a0d16 100644
--- a/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
+++ b/gem/lib/ruby_ui/tooltip/tooltip_trigger.rb
@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 
 module RubyUI
+  # Wraps the element that shows the tooltip (usually a Button). The tooltip
+  # opens while the pointer rests on it for delay: ms, or when it gets
+  # keyboard focus, and closes close_delay: ms after the pointer leaves both
+  # the trigger and the content (plus a short grace to cross the gap), on
+  # blur (unless the pointer is still over it) or on Escape. close_on_click: closes it when the trigger is pressed.
+  # Defaults follow shadcn's TooltipProvider (delay 0) and Base UI's Trigger.
   class TooltipTrigger < Base
+    def initialize(delay: 0, close_delay: 0, close_on_click: true, **attrs)
+      @delay = delay
+      @close_delay = close_delay
+      @close_on_click = close_on_click
+      super(**attrs)
+    end
+
     def view_template(&)
       div(**attrs, &)
     end
@@ -11,15 +24,14 @@ def view_template(&)
     def default_attrs
       {
         data: {
+          slot: "tooltip-trigger",
           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"
-          ]
+          delay: @delay,
+          close_delay: @close_delay,
+          close_on_click: @close_on_click.to_s
         },
-        variant: :outline
+        # Shrinks to the button, so the hit area and the anchor are the button.
+        class: "inline-flex w-fit"
       }
     end
   end
diff --git a/gem/test/ruby_ui/sidebar_test.rb b/gem/test/ruby_ui/sidebar_test.rb
index a34dee769..a9e737da2 100644
--- a/gem/test/ruby_ui/sidebar_test.rb
+++ b/gem/test/ruby_ui/sidebar_test.rb
@@ -259,9 +259,21 @@ def test_menu_button_tooltip
     output = phlex { RubyUI.SidebarMenuButton(tooltip: "Home") { "Home" } }
 
     assert_match(/data-controller="ruby-ui--tooltip"/, output)
-    assert_match(/data-ruby-ui--tooltip-placement-value="right"/, output)
-    assert_match(/data-ruby-ui--tooltip-target="trigger"/, output)
-    assert_match(%r{blur->ruby-ui--tooltip#hide"><template data-ruby-ui--tooltip-target="content">}, output)
+    assert_match(/data-ruby-ui--tooltip-target="trigger"><template data-ruby-ui--tooltip-target="content">/, output)
+    assert_match(/data-preferred-side="right"/, output)
+    refute_match(/data-action/, output)
+  end
+
+  # Pins the classes that scope the hiding to the sidebar around the button
+  # (the content sits inside it), instead of a body-level selector that any
+  # expanded sidebar on the page matched. The two-sidebar behavior itself is
+  # checked in the browser (see the PR).
+  def test_menu_button_tooltip_hides_from_its_own_sidebar
+    output = phlex { RubyUI.SidebarMenuButton(tooltip: "Home") { "Home" } }
+
+    assert_includes output, "[[data-slot=sidebar]:not([data-state=collapsed])_&]:hidden"
+    assert_includes output, "max-md:hidden"
+    refute_match(/body:has/, output)
   end
 
   def test_menu_button_without_tooltip
diff --git a/gem/test/ruby_ui/tooltip_test.rb b/gem/test/ruby_ui/tooltip_test.rb
index c815bed0d..32adbb1d8 100644
--- a/gem/test/ruby_ui/tooltip_test.rb
+++ b/gem/test/ruby_ui/tooltip_test.rb
@@ -18,13 +18,121 @@ def test_render_with_all_items
     assert_match(/Add to library/, output)
   end
 
-  def test_tooltip_content_wraps_long_text_within_viewport
+  def test_data_slots
     output = phlex do
-      RubyUI.TooltipContent { "Long tooltip content" }
+      RubyUI.Tooltip do
+        RubyUI.TooltipTrigger { "Trigger" }
+        RubyUI.TooltipContent { "Tip" }
+      end
     end
 
-    assert_match(/w-fit/, output)
-    assert_match(/max-w-\[calc\(100vw-2rem\)\]/, output)
-    assert_match(/break-words/, output)
+    assert_match(/data-slot="tooltip"/, output)
+    assert_match(/data-slot="tooltip-trigger"/, output)
+    assert_match(/data-slot="tooltip-content"/, output)
+    assert_match(/data-slot="tooltip-arrow"/, output)
+  end
+
+  def test_root_values
+    output = phlex { RubyUI.Tooltip(open: true, disabled: true, placement: "bottom") { "x" } }
+
+    assert_match(/data-controller="ruby-ui--tooltip"/, output)
+    assert_match(/data-ruby-ui--tooltip-open-value="true"/, output)
+    assert_match(/data-ruby-ui--tooltip-disabled-value="true"/, output)
+    assert_match(/data-ruby-ui--tooltip-placement-value="bottom"/, output)
+  end
+
+  # An empty value would read as true in Stimulus.
+  def test_root_coerces_nil_to_false
+    output = phlex { RubyUI.Tooltip(open: nil, disabled: nil) { "x" } }
+
+    assert_match(/data-ruby-ui--tooltip-open-value="false"/, output)
+    assert_match(/data-ruby-ui--tooltip-disabled-value="false"/, output)
+  end
+
+  def test_root_defaults_leave_placement_to_the_content
+    output = phlex { RubyUI.Tooltip { "x" } }
+
+    assert_match(/data-ruby-ui--tooltip-open-value="false"/, output)
+    assert_match(/data-ruby-ui--tooltip-disabled-value="false"/, output)
+    refute_match(/placement-value/, output)
+  end
+
+  # The wrapper shrinks to the button (hit area and anchor) and carries no
+  # stray attributes.
+  def test_trigger_is_an_inline_wrapper
+    output = phlex { RubyUI.TooltipTrigger { "Trigger" } }
+
+    assert_match(/class="inline-flex w-fit"/, output)
+    assert_match(/data-ruby-ui--tooltip-target="trigger"/, output)
+    refute_match(/variant=/, output)
+    refute_match(/data-action/, output)
+  end
+
+  def test_trigger_defaults
+    output = phlex { RubyUI.TooltipTrigger { "Trigger" } }
+
+    assert_match(/data-delay="0"/, output)
+    assert_match(/data-close-delay="0"/, output)
+    assert_match(/data-close-on-click="true"/, output)
+  end
+
+  def test_trigger_options
+    output = phlex { RubyUI.TooltipTrigger(delay: 300, close_delay: 100, close_on_click: false) { "Trigger" } }
+
+    assert_match(/data-delay="300"/, output)
+    assert_match(/data-close-delay="100"/, output)
+    assert_match(/data-close-on-click="false"/, output)
+  end
+
+  def test_content_is_a_manual_popover_tooltip_in_a_template
+    output = phlex { RubyUI.TooltipContent { "Tip" } }
+
+    assert_match(/<template data-ruby-ui--tooltip-target="content"><div/, output)
+    assert_match(/popover="manual"/, output)
+    assert_match(/role="tooltip"/, output)
+    assert_match(/id="tooltip-[0-9a-f]{8}"/, output)
+    assert_match(/data-state="closed"/, output)
+  end
+
+  def test_content_uses_vega_classes
+    output = phlex { RubyUI.TooltipContent { "Tip" } }
+
+    %w[bg-foreground text-background inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs w-fit max-w-xs
+      origin-(--transform-origin) overflow-visible].each do |token|
+      assert_includes output.scan(/class="([^"]*)"/).first.first.split, token
+    end
+    refute_match(/bg-popover|shadow-md|pointer-events-none|text-sm/, output)
+  end
+
+  def test_content_placement_defaults
+    output = phlex { RubyUI.TooltipContent { "Tip" } }
+
+    assert_match(/data-side-offset="4"/, output)
+    assert_match(/data-align-offset="0"/, output)
+    refute_match(/data-preferred-side/, output)
+    refute_match(/data-preferred-align/, output)
+  end
+
+  def test_content_placement_options
+    output = phlex { RubyUI.TooltipContent(side: :inline_end, align: :start, side_offset: 8, align_offset: 2) { "Tip" } }
+
+    assert_match(/data-preferred-side="inline-end"/, output)
+    assert_match(/data-preferred-align="start"/, output)
+    assert_match(/data-side-offset="8"/, output)
+    assert_match(/data-align-offset="2"/, output)
+  end
+
+  def test_content_ignores_unknown_side_and_align
+    output = phlex { RubyUI.TooltipContent(side: :middle, align: :around) { "Tip" } }
+
+    refute_match(/data-preferred-side/, output)
+    refute_match(/data-preferred-align/, output)
+  end
+
+  def test_arrow_is_hidden_from_assistive_tech
+    output = phlex { RubyUI.TooltipContent { "Tip" } }
+
+    assert_match(/<span aria-hidden="true" data-slot="tooltip-arrow"/, output)
+    assert_match(/rotate-45/, output)
   end
 end
diff --git a/mcp/data/registry/components/sidebar.json b/mcp/data/registry/components/sidebar.json
index 1f00e211a..974564134 100644
--- a/mcp/data/registry/components/sidebar.json
+++ b/mcp/data/registry/components/sidebar.json
@@ -72,7 +72,7 @@
     },
     {
       "path": "sidebar_menu_button.rb",
-      "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  class SidebarMenuButton < Base\n    VARIANT_CLASSES = {\n      default: \"hover:bg-sidebar-accent hover:text-sidebar-accent-foreground\",\n      outline: [\n        \"bg-background shadow-[0_0_0_1px_var(--sidebar-border)]\",\n        \"hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_var(--sidebar-accent)]\"\n      ].join(\" \")\n    }.freeze\n\n    SIZE_CLASSES = {\n      default: \"h-8 text-sm\",\n      sm: \"h-7 text-xs\",\n      lg: \"h-12 text-sm group-data-[collapsible=icon]:!p-0\"\n    }.freeze\n\n    # The tooltip is cloned into <body>, outside the sidebar, so it hides itself\n    # with a body-level selector: only shown while a desktop sidebar is\n    # collapsed (shadcn: hidden={state !== \"collapsed\" || isMobile}).\n    TOOLTIP_CLASSES = \"[body:has([data-slot=sidebar][data-state=expanded])_&]:hidden max-md:hidden\"\n\n    # tooltip: label shown on the right when the sidebar is collapsed to icons.\n    def initialize(as: :button, variant: :default, size: :default, active: false, tooltip: nil, **attrs)\n      raise ArgumentError, \"Invalid variant: #{variant}\" unless VARIANT_CLASSES.key?(variant)\n      raise ArgumentError, \"Invalid size: #{size}\" unless SIZE_CLASSES.key?(size)\n\n      @as = as\n      @variant = variant\n      @size = size\n      @active = active\n      @tooltip = tooltip\n      super(**attrs)\n    end\n\n    def view_template(&block)\n      return tag(@as, **attrs, &block) unless @tooltip\n\n      tag(@as, **mix(attrs, tooltip_attrs)) do\n        # First child, so [&>span:last-child]:truncate still finds the label.\n        TooltipContent(class: TOOLTIP_CLASSES) { @tooltip }\n        yield if block\n      end\n    end\n\n    private\n\n    def tooltip_attrs\n      {\n        data: {\n          controller: \"ruby-ui--tooltip\",\n          ruby_ui__tooltip_placement_value: \"right\",\n          ruby_ui__tooltip_target: \"trigger\",\n          action: [\n            \"mouseenter->ruby-ui--tooltip#show\",\n            \"mouseleave->ruby-ui--tooltip#hide\",\n            \"focus->ruby-ui--tooltip#show\",\n            \"blur->ruby-ui--tooltip#hide\"\n          ]\n        }\n      }\n    end\n\n    def default_attrs\n      {\n        class: [\n          \"peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden\",\n          \"rounded-md p-2 text-left text-sm outline-none ring-sidebar-ring\",\n          \"transition-[width,height,padding] focus-visible:ring-2\",\n          \"active:bg-sidebar-accent active:text-sidebar-accent-foreground\",\n          \"disabled:pointer-events-none disabled:opacity-50\",\n          \"group-has-[[data-sidebar=menu-action]]/menu-item:pr-8\",\n          \"aria-disabled:pointer-events-none aria-disabled:opacity-50\",\n          \"data-[active=true]:bg-sidebar-accent data-[active=true]:font-medium\",\n          \"data-[active=true]:text-sidebar-accent-foreground\",\n          \"data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground\",\n          \"aria-expanded:hover:bg-sidebar-accent aria-expanded:hover:text-sidebar-accent-foreground\",\n          \"group-data-[collapsible=icon]:!size-8\",\n          \"group-data-[collapsible=icon]:!p-2 [&>span:last-child]:truncate\",\n          \"[&_svg]:size-4 [&_svg]:shrink-0\",\n          VARIANT_CLASSES[@variant],\n          SIZE_CLASSES[@size]\n        ],\n        data: {\n          slot: \"sidebar-menu-button\",\n          sidebar: \"menu-button\",\n          size: @size,\n          active: @active.to_s\n        }\n      }\n    end\n  end\nend\n"
+      "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  class SidebarMenuButton < Base\n    VARIANT_CLASSES = {\n      default: \"hover:bg-sidebar-accent hover:text-sidebar-accent-foreground\",\n      outline: [\n        \"bg-background shadow-[0_0_0_1px_var(--sidebar-border)]\",\n        \"hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_var(--sidebar-accent)]\"\n      ].join(\" \")\n    }.freeze\n\n    SIZE_CLASSES = {\n      default: \"h-8 text-sm\",\n      sm: \"h-7 text-xs\",\n      lg: \"h-12 text-sm group-data-[collapsible=icon]:!p-0\"\n    }.freeze\n\n    # The tooltip controller places the content right after this button, inside\n    # its own sidebar, so it hides from that sidebar's state alone: shown only\n    # while the desktop sidebar around it is collapsed (shadcn:\n    # hidden={state !== \"collapsed\" || isMobile}). A second, expanded sidebar\n    # on the page no longer hides it.\n    TOOLTIP_CLASSES = \"[[data-slot=sidebar]:not([data-state=collapsed])_&]:hidden max-md:hidden\"\n\n    # tooltip: label shown on the right when the sidebar is collapsed to icons.\n    def initialize(as: :button, variant: :default, size: :default, active: false, tooltip: nil, **attrs)\n      raise ArgumentError, \"Invalid variant: #{variant}\" unless VARIANT_CLASSES.key?(variant)\n      raise ArgumentError, \"Invalid size: #{size}\" unless SIZE_CLASSES.key?(size)\n\n      @as = as\n      @variant = variant\n      @size = size\n      @active = active\n      @tooltip = tooltip\n      super(**attrs)\n    end\n\n    def view_template(&block)\n      return tag(@as, **attrs, &block) unless @tooltip\n\n      tag(@as, **mix(attrs, tooltip_attrs)) do\n        # First child, so [&>span:last-child]:truncate still finds the label.\n        TooltipContent(side: :right, class: TOOLTIP_CLASSES) { @tooltip }\n        yield if block\n      end\n    end\n\n    private\n\n    def tooltip_attrs\n      {\n        data: {\n          controller: \"ruby-ui--tooltip\",\n          ruby_ui__tooltip_target: \"trigger\"\n        }\n      }\n    end\n\n    def default_attrs\n      {\n        class: [\n          \"peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden\",\n          \"rounded-md p-2 text-left text-sm outline-none ring-sidebar-ring\",\n          \"transition-[width,height,padding] focus-visible:ring-2\",\n          \"active:bg-sidebar-accent active:text-sidebar-accent-foreground\",\n          \"disabled:pointer-events-none disabled:opacity-50\",\n          \"group-has-[[data-sidebar=menu-action]]/menu-item:pr-8\",\n          \"aria-disabled:pointer-events-none aria-disabled:opacity-50\",\n          \"data-[active=true]:bg-sidebar-accent data-[active=true]:font-medium\",\n          \"data-[active=true]:text-sidebar-accent-foreground\",\n          \"data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground\",\n          \"aria-expanded:hover:bg-sidebar-accent aria-expanded:hover:text-sidebar-accent-foreground\",\n          \"group-data-[collapsible=icon]:!size-8\",\n          \"group-data-[collapsible=icon]:!p-2 [&>span:last-child]:truncate\",\n          \"[&_svg]:size-4 [&_svg]:shrink-0\",\n          VARIANT_CLASSES[@variant],\n          SIZE_CLASSES[@size]\n        ],\n        data: {\n          slot: \"sidebar-menu-button\",\n          sidebar: \"menu-button\",\n          size: @size,\n          active: @active.to_s\n        }\n      }\n    end\n  end\nend\n"
     },
     {
       "path": "sidebar_menu_item.rb",
diff --git a/mcp/data/registry/components/tooltip.json b/mcp/data/registry/components/tooltip.json
index 84422dc56..5afcca4f5 100644
--- a/mcp/data/registry/components/tooltip.json
+++ b/mcp/data/registry/components/tooltip.json
@@ -4,19 +4,19 @@
   "files": [
     {
       "path": "tooltip.rb",
-      "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  class Tooltip < Base\n    def initialize(placement: \"top\", **attrs)\n      @placement = placement\n      super(**attrs)\n    end\n\n    def view_template(&)\n      div(**attrs, &)\n    end\n\n    private\n\n    def default_attrs\n      {\n        data: {\n          controller: \"ruby-ui--tooltip\",\n          ruby_ui__tooltip_placement_value: @placement\n        },\n        class: \"group\"\n      }\n    end\n  end\nend\n"
+      "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  # Root of the tooltip: scopes the trigger and the content for the Stimulus\n  # controller. open: renders it open on load (Base UI's defaultOpen) and\n  # disabled: keeps it from opening (Base UI's Root disabled). Setting the\n  # data-ruby-ui--tooltip-open-value or -disabled-value attribute later\n  # opens, closes or disables it; each open or close dispatches\n  # ruby-ui--tooltip:change with detail {open:}.\n  #\n  # placement: is the older API: TooltipContent's side: wins over it.\n  class Tooltip < Base\n    def initialize(placement: nil, open: false, disabled: false, **attrs)\n      @placement = placement\n      @open = open\n      @disabled = disabled\n      super(**attrs)\n    end\n\n    def view_template(&)\n      div(**attrs, &)\n    end\n\n    private\n\n    def default_attrs\n      {\n        data: {\n          slot: \"tooltip\",\n          controller: \"ruby-ui--tooltip\",\n          ruby_ui__tooltip_placement_value: @placement&.to_s,\n          ruby_ui__tooltip_open_value: (!!@open).to_s,\n          ruby_ui__tooltip_disabled_value: (!!@disabled).to_s\n        },\n        class: \"group\"\n      }\n    end\n  end\nend\n"
     },
     {
       "path": "tooltip_content.rb",
-      "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  class TooltipContent < Base\n    def initialize(**attrs)\n      @id = \"tooltip#{SecureRandom.hex(4)}\"\n      super\n    end\n\n    def view_template(&)\n      template(data: {ruby_ui__tooltip_target: \"content\"}) do\n        div(**attrs, &)\n      end\n    end\n\n    private\n\n    def default_attrs\n      {\n        id: @id,\n        class: [\n          \"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\",\n          \"data-[placement=bottom]:slide-in-from-top-2\",\n          \"data-[placement=left]:slide-in-from-right-2\",\n          \"data-[placement=right]:slide-in-from-left-2\",\n          \"data-[placement=top]:slide-in-from-bottom-2\",\n          \"data-[state=open]:visible data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95\",\n          \"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\"\n        ]\n      }\n    end\n  end\nend\n"
+      "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  # The popup, kept in a <template> until the controller connects. The\n  # controller places the copy right after the trigger, so it stays inside\n  # the same container (a Sidebar hides its own tooltips from its state), and\n  # opens it as a native popover=\"manual\" in the top layer, where no ancestor\n  # with overflow: hidden clips it. role=\"tooltip\"; the trigger's focusable\n  # element points at it with aria-describedby.\n  #\n  # side:/align: pick the placement (side also takes the logical\n  # :inline_start / :inline_end), side_offset:/align_offset: the gap, with the\n  # defaults of shadcn's TooltipContent. Without side:, Tooltip's placement:\n  # applies, then top. It flips to the other side when there is no room.\n  class TooltipContent < Base\n    SIDES = %i[top right bottom left inline_start inline_end].freeze\n    ALIGNS = %i[start center end].freeze\n\n    def initialize(side: nil, side_offset: 4, align: nil, align_offset: 0, **attrs)\n      @id = \"tooltip-#{SecureRandom.hex(4)}\"\n      @side = SIDES.include?(side&.to_sym) ? side.to_s.tr(\"_\", \"-\") : nil\n      @align = ALIGNS.include?(align&.to_sym) ? align.to_s : nil\n      @side_offset = side_offset\n      @align_offset = align_offset\n      super(**attrs)\n    end\n\n    def view_template(&block)\n      template(data: {ruby_ui__tooltip_target: \"content\"}) do\n        div(**attrs) do\n          yield if block\n          span(**arrow_attrs)\n        end\n      end\n    end\n\n    private\n\n    def arrow_attrs\n      {\n        aria: {hidden: \"true\"},\n        data: {slot: \"tooltip-arrow\"},\n        class: [\n          \"absolute z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground\",\n          \"data-[side=bottom]:top-1 data-[side=top]:-bottom-2.5\",\n          \"data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2\",\n          # The controller writes the physical side, so logical sides point right in RTL too.\n          \"data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2\"\n        ]\n      }\n    end\n\n    def default_attrs\n      {\n        id: @id,\n        popover: \"manual\",\n        role: \"tooltip\",\n        data: {\n          slot: \"tooltip-content\",\n          # Kept in sync with data-open/data-closed for CSS that targets data-[state=...].\n          state: \"closed\",\n          closed: \"\",\n          preferred_side: @side,\n          preferred_align: @align,\n          side_offset: @side_offset,\n          align_offset: @align_offset\n        },\n        class: [\n          # Resets the UA popover box (overflow too, or it clips the arrow);\n          # inline-flex must not beat the UA's hidden closed popover.\n          \"fixed inset-auto m-0 border-0 overflow-visible [&:not(:popover-open)]:hidden\",\n          \"z-50 w-fit max-w-xs origin-(--transform-origin) bg-foreground text-background\",\n          \"inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs\",\n          \"has-data-[slot=kbd]:pr-1.5 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm\",\n          \"data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95\",\n          \"data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 data-closed:fill-mode-forwards\",\n          \"data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2\",\n          \"data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2\",\n          \"data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2\"\n        ]\n      }\n    end\n  end\nend\n"
     },
     {
       "path": "tooltip_controller.js",
-      "content": "import { Controller } from \"@hotwired/stimulus\";\nimport { computePosition, autoUpdate, offset, shift } from \"@floating-ui/dom\";\n\nexport default class extends Controller {\n  static targets = [\"trigger\", \"content\"];\n\n  static values = { placement: \"top\" };\n\n  mount() {\n    if (this.mounted) return;\n\n    const element = this.cloneTemplate();\n    element.setAttribute(\"data-placement\", this.placementValue);\n    document.body.appendChild(element);\n\n    this.triggerTarget.setAttribute(\"aria-describedby\", element.id);\n    // animationcancel covers an exit run cut short (backgrounded tab, interrupting\n    // style change) — without it the cloned node is never removed from <body>.\n    element.addEventListener(\"animationend\", this.handleExitAnimationEnd);\n    element.addEventListener(\"animationcancel\", this.handleExitAnimationEnd);\n\n    const onBeforeCache = () => this.unmount();\n    document.addEventListener(\"turbo:before-cache\", onBeforeCache);\n\n    this.mounted = { element, onBeforeCache };\n    this.mounted.stopAutoUpdate = autoUpdate(this.triggerTarget, element, () => this.reposition());\n  }\n\n  unmount() {\n    if (!this.mounted) return;\n\n    document.removeEventListener(\"turbo:before-cache\", this.mounted.onBeforeCache);\n\n    this.mounted.stopAutoUpdate?.();\n    this.mounted.element.remove();\n    this.triggerTarget.removeAttribute(\"aria-describedby\");\n\n    this.mounted = null;\n  }\n\n  disconnect() {\n    this.unmount();\n  }\n\n  show() {\n    if (!this.hasContentTarget) return;\n\n    this.mount();\n    this.mounted.element.setAttribute(\"data-state\", \"open\");\n  }\n\n  hide() {\n    this.mounted?.element.setAttribute(\"data-state\", \"closed\");\n  }\n\n  handleExitAnimationEnd = (event) => {\n    if (event.animationName !== \"exit\") return;\n    if (this.mounted?.element.getAttribute(\"data-state\") !== \"closed\") return;\n\n    this.unmount();\n  };\n\n  cloneTemplate() {\n    return this.contentTarget.content.firstElementChild.cloneNode(true);\n  }\n\n  reposition() {\n    if (!this.mounted) return;\n\n    const position = { placement: this.placementValue, middleware: [offset(4), shift()] };\n\n    computePosition(this.triggerTarget, this.mounted.element, position).then(({ x, y }) => {\n      this.mounted?.element.style.setProperty(\"left\", `${x}px`);\n      this.mounted?.element.style.setProperty(\"top\", `${y}px`);\n    });\n  }\n}\n"
+      "content": "import { Controller } from \"@hotwired/stimulus\";\nimport { computePosition, autoUpdate, offset, flip, shift, arrow } from \"@floating-ui/dom\";\n\n// Connects to data-controller=\"ruby-ui--tooltip\"\n//\n// Behaves like Base UI's Tooltip: it opens while the pointer rests on the\n// trigger (after delay) or when the trigger gets keyboard focus, and closes\n// when the pointer leaves both the trigger and the content, on blur, on\n// Escape, or when the trigger is pressed (close_on_click). The pointer can\n// move onto the content without closing it (WCAG 1.4.13).\n//\n// TooltipContent ships in a <template>. On connect the controller places a\n// copy right after the trigger, so it stays inside the same container (a\n// Sidebar hides its tooltips from its own data-state), and opens it as a\n// native popover=\"manual\" in the top layer; Floating UI places it next to\n// the trigger. The content has role=\"tooltip\" and the trigger's focusable\n// element points at it with aria-describedby, as the APG tooltip pattern\n// asks (Base UI leaves both out).\nconst SIDES = [\"top\", \"right\", \"bottom\", \"left\", \"inline-start\", \"inline-end\"];\nconst ALIGNS = [\"start\", \"center\", \"end\"];\nconst FOCUSABLE = 'button, [href], input, select, textarea, [tabindex]:not([tabindex=\"-1\"])';\n// The pointer needs a moment to cross the gap between trigger and content.\nconst HOVER_GRACE = 100;\n\nexport default class extends Controller {\n  static targets = [\"trigger\", \"content\"];\n  static values = {\n    placement: { type: String, default: \"top\" },\n    open: { type: Boolean, default: false },\n    disabled: { type: Boolean, default: false },\n  };\n\n  // The copy of the content template that lives in the page.\n  popup = null;\n  isOpen = false;\n\n  connect() {\n    document.addEventListener(\"turbo:before-cache\", this.handleBeforeCache);\n    this.mount();\n    if (this.openValue && !this.disabledValue) this.open();\n    this.ready = true;\n  }\n\n  disconnect() {\n    this.ready = false;\n    document.removeEventListener(\"turbo:before-cache\", this.handleBeforeCache);\n    this.unmount();\n    // Stimulus reuses this instance if the element comes back.\n    this.pointerInside = false;\n    this.pressedClosed = false;\n  }\n\n  // Target callbacks run before connect() and again whenever Turbo or other\n  // code swaps the trigger or the content inside a connected tooltip.\n  triggerTargetConnected(trigger) {\n    trigger.addEventListener(\"mouseenter\", this.handleEnter);\n    trigger.addEventListener(\"mouseleave\", this.handleLeave);\n    trigger.addEventListener(\"focusin\", this.handleFocusIn);\n    trigger.addEventListener(\"focusout\", this.handleFocusOut);\n    trigger.addEventListener(\"click\", this.handleClick);\n    if (this.ready) this.remount();\n  }\n\n  triggerTargetDisconnected(trigger) {\n    trigger.removeEventListener(\"mouseenter\", this.handleEnter);\n    trigger.removeEventListener(\"mouseleave\", this.handleLeave);\n    trigger.removeEventListener(\"focusin\", this.handleFocusIn);\n    trigger.removeEventListener(\"focusout\", this.handleFocusOut);\n    trigger.removeEventListener(\"click\", this.handleClick);\n    // The copy sits next to (and is placed against) this trigger.\n    if (this.popup && this.mountedTrigger === trigger) this.unmount();\n  }\n\n  contentTargetConnected() {\n    if (this.ready) this.remount();\n  }\n\n  contentTargetDisconnected(template) {\n    if (this.popup && this.mountedTemplate === template) this.unmount();\n  }\n\n  openValueChanged(open) {\n    if (!this.ready) return;\n    open ? this.open() : this.close();\n  }\n\n  disabledValueChanged(disabled) {\n    if (!this.ready) return;\n    // An open value set while disabled takes effect once enabled again.\n    if (disabled) {\n      this.close();\n    } else if (this.openValue) {\n      this.open();\n    }\n  }\n\n  // Kept for markup that still wires data-action to show/hide.\n  show() {\n    this.open();\n  }\n\n  hide() {\n    this.close();\n  }\n\n  // --- Mounting -----------------------------------------------------------------\n\n  mount() {\n    if (this.popup || !this.hasContentTarget || !this.hasTriggerTarget) return;\n    const template = this.contentTarget;\n    const trigger = this.triggerTarget;\n    const popup = template.content?.firstElementChild?.cloneNode(true);\n    if (!popup) return;\n\n    popup.addEventListener(\"mouseenter\", this.handleEnter);\n    popup.addEventListener(\"mouseleave\", this.handleLeave);\n    trigger.after(popup);\n    this.popup = popup;\n    this.mountedTrigger = trigger;\n    this.mountedTemplate = template;\n    this.describe(trigger, popup);\n  }\n\n  unmount() {\n    const popup = this.popup;\n    if (!popup) return;\n    this.close({ animate: false });\n    popup.removeEventListener(\"mouseenter\", this.handleEnter);\n    popup.removeEventListener(\"mouseleave\", this.handleLeave);\n    this.undescribe();\n    popup.remove();\n    this.popup = null;\n    this.mountedTrigger = null;\n    this.mountedTemplate = null;\n  }\n\n  // A swapped trigger or content while open stays open, without telling\n  // listeners about a close and reopen that never happened.\n  remount() {\n    const wasOpen = this.isOpen;\n    this.remounting = wasOpen;\n    try {\n      this.unmount();\n      this.mount();\n      if (wasOpen) this.open();\n    } finally {\n      this.remounting = false;\n    }\n  }\n\n  // --- aria-describedby ---------------------------------------------------------\n\n  // The element inside the trigger that receives focus (the Button), else the wrapper.\n  controlFor(trigger) {\n    return trigger.matches(FOCUSABLE) ? trigger : trigger.querySelector(FOCUSABLE) || trigger;\n  }\n\n  // Adds the content's id to the control's aria-describedby, keeping a\n  // caller's own ids. Skipped when the tooltip only repeats the control's\n  // text (SidebarMenuButton's label): the description would say it twice.\n  describe(trigger, popup) {\n    const control = this.controlFor(trigger);\n    const text = (element) => element.textContent.replace(/\\s+/g, \" \").trim().toLowerCase();\n    if (text(popup) !== \"\" && text(popup) === text(control)) return;\n\n    const ids = (control.getAttribute(\"aria-describedby\") || \"\").split(/\\s+/).filter(Boolean);\n    if (!ids.includes(popup.id)) control.setAttribute(\"aria-describedby\", [...ids, popup.id].join(\" \"));\n    this.describedControl = control;\n  }\n\n  undescribe() {\n    const control = this.describedControl;\n    this.describedControl = null;\n    if (!control || !this.popup) return;\n    const ids = (control.getAttribute(\"aria-describedby\") || \"\").split(/\\s+/).filter((id) => id && id !== this.popup.id);\n    ids.length ? control.setAttribute(\"aria-describedby\", ids.join(\" \")) : control.removeAttribute(\"aria-describedby\");\n  }\n\n  // --- Pointer, focus, click, Escape --------------------------------------------\n\n  triggerSetting(key, fallback) {\n    const own = this.mountedTrigger?.dataset[key];\n    return own !== undefined && own !== \"\" ? own : fallback;\n  }\n\n  get openDelay() {\n    return Number(this.triggerSetting(\"delay\", 0)) || 0;\n  }\n\n  get closeDelay() {\n    return Number(this.triggerSetting(\"closeDelay\", 0)) || 0;\n  }\n\n  get closeOnClick() {\n    return this.triggerSetting(\"closeOnClick\", \"true\") !== \"false\";\n  }\n\n  handleEnter = (event) => {\n    this.pointerInside = true;\n    this.clearTimers();\n    // After close_on_click, the pointer has to leave the trigger before it opens again.\n    if (this.isOpen || this.pressedClosed || this.disabledValue) return;\n    if (event.currentTarget === this.popup) return;\n    const delay = this.openDelay;\n    if (delay > 0) {\n      this.openTimeout = setTimeout(() => this.open(), delay);\n    } else {\n      this.open();\n    }\n  };\n\n  handleLeave = (event) => {\n    this.pointerInside = false;\n    if (event.currentTarget === this.mountedTrigger) this.pressedClosed = false;\n    this.clearTimers();\n    if (!this.isOpen || this.keyboardFocusInside()) return;\n    this.closeTimeout = setTimeout(() => this.close(), this.closeDelay + HOVER_GRACE);\n  };\n\n  // Opens on keyboard focus only, as Base UI does: a click focuses the button too.\n  handleFocusIn = (event) => {\n    if (this.disabledValue || this.isOpen || !this.isFocusVisible(event.target)) return;\n    this.clearTimers();\n    this.open();\n  };\n\n  handleFocusOut = (event) => {\n    if (this.mountedTrigger?.contains(event.relatedTarget)) return;\n    if (this.pointerInside) return;\n    this.close();\n  };\n\n  // Enter and Space on the trigger's button arrive here as a click too. A\n  // press during the open delay cancels the pending open as well.\n  handleClick = () => {\n    if (!this.closeOnClick) return;\n    this.clearTimers();\n    this.pressedClosed = this.pointerInside;\n    this.close();\n  };\n\n  handleKeydown = (event) => {\n    if (event.key !== \"Escape\" || !this.isOpen) return;\n    // A tooltip hidden by CSS (an expanded or mobile sidebar) closes without\n    // taking the key, so an enclosing Sheet or dialog still gets it.\n    // A visible one keeps an enclosing <dialog> from closing on the same key.\n    if (this.isRendered(this.popup)) event.preventDefault();\n    this.close();\n  };\n\n  handleBeforeCache = () => {\n    // The snapshot keeps the <template>; connect() places a fresh copy on restore.\n    this.unmount();\n  };\n\n  isRendered(element) {\n    return Boolean(element?.isConnected && element.getClientRects().length > 0);\n  }\n\n  keyboardFocusInside() {\n    const active = document.activeElement;\n    return Boolean(active && this.mountedTrigger?.contains(active) && this.isFocusVisible(active));\n  }\n\n  isFocusVisible(element) {\n    try {\n      return element.matches(\":focus-visible\");\n    } catch {\n      return true;\n    }\n  }\n\n  clearTimers() {\n    clearTimeout(this.openTimeout);\n    clearTimeout(this.closeTimeout);\n  }\n\n  // --- Opening and closing ------------------------------------------------------\n\n  open() {\n    if (this.isOpen || this.disabledValue) return;\n    this.mount();\n    const popup = this.popup;\n    if (!popup || !popup.isConnected) return;\n    this.clearTimers();\n    this.isOpen = true;\n\n    // Side and origin before the enter animation starts; position() refines both.\n    const { side, align } = this.preferredPlacement(popup);\n    popup.dataset.side = side;\n    popup.dataset.align = align;\n    popup.removeAttribute(\"data-closed\");\n    popup.setAttribute(\"data-open\", \"\");\n    popup.dataset.state = \"open\";\n    if (!popup.matches(\":popover-open\")) popup.showPopover();\n\n    document.addEventListener(\"keydown\", this.handleKeydown);\n    this.startPositioning();\n    this.setOpenValue(true);\n  }\n\n  close({ animate = true } = {}) {\n    this.clearTimers();\n    if (!this.isOpen) return;\n    const popup = this.popup;\n    this.isOpen = false;\n    document.removeEventListener(\"keydown\", this.handleKeydown);\n    this.stopPositioning();\n\n    popup.removeAttribute(\"data-open\");\n    popup.setAttribute(\"data-closed\", \"\");\n    popup.dataset.state = \"closed\";\n    animate ? this.hideAfterExitAnimation(popup) : this.settleExit(popup);\n    this.setOpenValue(false);\n  }\n\n  // Mirrors the state on the open value (so openValueChanged sees no change)\n  // and tells listeners, as Base UI's onOpenChange does.\n  setOpenValue(open) {\n    if (this.remounting) return;\n    if (this.openValue !== open) this.openValue = open;\n    this.dispatch(\"change\", { detail: { open } });\n  }\n\n  // --- Positioning --------------------------------------------------------------\n\n  // TooltipContent side:/align:, else Tooltip placement:, else top/center.\n  preferredPlacement(popup) {\n    // Logical sides keep their hyphen: \"inline-start\" is a side, not side-align.\n    const placement = String(this.placementValue || \"\");\n    const [placementSide, placementAlign] = placement.startsWith(\"inline-\") ? [placement] : placement.split(\"-\");\n    const side = [popup.dataset.preferredSide, placementSide].find((value) => SIDES.includes(value)) || \"top\";\n    const align = popup.dataset.preferredSide\n      ? popup.dataset.preferredAlign || \"center\"\n      : [popup.dataset.preferredAlign, placementAlign].find((value) => ALIGNS.includes(value)) || \"center\";\n    return { side, align };\n  }\n\n  // inline-start / inline-end follow the trigger's writing direction.\n  physicalSide(side, trigger) {\n    if (!side.startsWith(\"inline-\")) return side;\n    const rtl = getComputedStyle(trigger).direction === \"rtl\";\n    return (side === \"inline-start\") !== rtl ? \"left\" : \"right\";\n  }\n\n  startPositioning() {\n    this.stopPositioning();\n    const trigger = this.mountedTrigger;\n    const popup = this.popup;\n    const anchor = this.controlFor(trigger);\n    this.cleanup = autoUpdate(anchor, popup, () => this.position(anchor, popup));\n  }\n\n  stopPositioning() {\n    if (this.cleanup) this.cleanup();\n    this.cleanup = null;\n  }\n\n  position(anchor, popup) {\n    const { side, align } = this.preferredPlacement(popup);\n    const physical = this.physicalSide(side, anchor);\n    const placement = align === \"center\" ? physical : `${physical}-${align}`;\n    const sideOffset = Number(popup.dataset.sideOffset ?? 4);\n    const alignOffset = Number(popup.dataset.alignOffset ?? 0);\n    const arrowElement = popup.querySelector('[data-slot=\"tooltip-arrow\"]');\n\n    const middleware = [\n      // crossAxis shifts a centered tooltip; alignmentAxis takes over for\n      // :start / :end and flips the offset for :end, as Base UI does.\n      offset({ mainAxis: sideOffset, crossAxis: alignOffset, alignmentAxis: alignOffset }),\n      flip(),\n      shift({ padding: 5 }),\n    ];\n    if (arrowElement) middleware.push(arrow({ element: arrowElement, padding: 5 }));\n\n    computePosition(anchor, popup, { strategy: \"fixed\", placement, middleware }).then(\n      ({ x, y, placement: resolved, middlewareData }) => {\n        if (!popup.isConnected || popup !== this.popup || !this.isOpen) return;\n        const [resolvedSide, resolvedAlign = \"center\"] = resolved.split(\"-\");\n        Object.assign(popup.style, { left: `${x}px`, top: `${y}px` });\n        // A logical side keeps its logical name, flipped to the other one if Floating UI flipped.\n        const finalSide = side.startsWith(\"inline-\")\n          ? resolvedSide === physical ? side : side === \"inline-start\" ? \"inline-end\" : \"inline-start\"\n          : resolvedSide;\n        popup.dataset.side = finalSide;\n        popup.dataset.align = resolvedAlign;\n        if (arrowElement) this.placeArrow(arrowElement, resolvedSide, resolvedAlign, middlewareData.arrow);\n        popup.style.setProperty(\"--transform-origin\", this.transformOrigin(anchor, popup, resolvedSide, x, y, sideOffset));\n      },\n    );\n  }\n\n  // Along the trigger for top/bottom; the classes center it for left/right.\n  // The arrow takes the physical side, so a logical side points the right\n  // way in RTL too.\n  placeArrow(arrowElement, physical, align, data = {}) {\n    arrowElement.dataset.side = physical;\n    arrowElement.dataset.align = align;\n    const vertical = physical === \"top\" || physical === \"bottom\";\n    arrowElement.style.left = vertical && data.x != null ? `${data.x}px` : \"\";\n    arrowElement.style.top = !vertical && data.y != null ? `${data.y}px` : \"\";\n  }\n\n  // The content grows out of the trigger: the origin sits on the trigger's\n  // center line, at the gap between the two (Base UI's --transform-origin).\n  transformOrigin(anchor, popup, side, x, y, sideOffset) {\n    const rect = anchor.getBoundingClientRect();\n    const { width, height } = popup.getBoundingClientRect();\n    const centerX = rect.left + rect.width / 2 - x;\n    const centerY = rect.top + rect.height / 2 - y;\n    switch (side) {\n      case \"top\":\n        return `${centerX}px ${height + sideOffset}px`;\n      case \"left\":\n        return `${width + sideOffset}px ${centerY}px`;\n      case \"right\":\n        return `${-sideOffset}px ${centerY}px`;\n      default:\n        return `${centerX}px ${-sideOffset}px`;\n    }\n  }\n\n  // --- Exit animation (same block as the other overlay controllers) ------------\n\n  exitAnimationNames = new WeakMap();\n\n  hideAfterExitAnimation(animated) {\n    const exitAnimations = animated.getAnimations().filter((animation) => animation instanceof CSSAnimation);\n    // No exit animation, or no box to run it in (hidden by CSS): animationend would never fire.\n    if (exitAnimations.length === 0) {\n      this.settleExit(animated);\n      return;\n    }\n    this.exitAnimationNames.set(animated, exitAnimations.map((animation) => animation.animationName));\n    animated.addEventListener(\"animationend\", this.handleExitAnimationEnd);\n    animated.addEventListener(\"animationcancel\", this.handleExitAnimationEnd);\n  }\n\n  handleExitAnimationEnd = (event) => {\n    // animationend bubbles — an animated child must not hide its container.\n    if (event.target !== event.currentTarget) return;\n    // Closing mid-open cancels the enter animation; only the exit run settles this.\n    if (!this.exitAnimationNames.get(event.currentTarget)?.includes(event.animationName)) return;\n    this.settleExit(event.currentTarget);\n  };\n\n  settleExit(animated) {\n    animated.removeEventListener(\"animationend\", this.handleExitAnimationEnd);\n    animated.removeEventListener(\"animationcancel\", this.handleExitAnimationEnd);\n    // Reopened mid-exit: it is on its way back in, leave it showing.\n    if (animated.hasAttribute(\"data-open\")) return;\n    animated.setAttribute(\"data-closed\", \"\");\n    animated.dataset.state = \"closed\";\n    if (animated.matches(\":popover-open\")) animated.hidePopover();\n  }\n}\n"
     },
     {
       "path": "tooltip_trigger.rb",
-      "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  class TooltipTrigger < Base\n    def view_template(&)\n      div(**attrs, &)\n    end\n\n    private\n\n    def default_attrs\n      {\n        data: {\n          ruby_ui__tooltip_target: \"trigger\",\n          action: [\n            \"mouseenter->ruby-ui--tooltip#show\",\n            \"mouseleave->ruby-ui--tooltip#hide\",\n            \"focus->ruby-ui--tooltip#show\",\n            \"blur->ruby-ui--tooltip#hide\"\n          ]\n        },\n        variant: :outline\n      }\n    end\n  end\nend\n"
+      "content": "# frozen_string_literal: true\n\nmodule RubyUI\n  # Wraps the element that shows the tooltip (usually a Button). The tooltip\n  # opens while the pointer rests on it for delay: ms, or when it gets\n  # keyboard focus, and closes close_delay: ms after the pointer leaves both\n  # the trigger and the content (plus a short grace to cross the gap), on\n  # blur (unless the pointer is still over it) or on Escape. close_on_click: closes it when the trigger is pressed.\n  # Defaults follow shadcn's TooltipProvider (delay 0) and Base UI's Trigger.\n  class TooltipTrigger < Base\n    def initialize(delay: 0, close_delay: 0, close_on_click: true, **attrs)\n      @delay = delay\n      @close_delay = close_delay\n      @close_on_click = close_on_click\n      super(**attrs)\n    end\n\n    def view_template(&)\n      div(**attrs, &)\n    end\n\n    private\n\n    def default_attrs\n      {\n        data: {\n          slot: \"tooltip-trigger\",\n          ruby_ui__tooltip_target: \"trigger\",\n          delay: @delay,\n          close_delay: @close_delay,\n          close_on_click: @close_on_click.to_s\n        },\n        # Shrinks to the button, so the hit area and the anchor are the button.\n        class: \"inline-flex w-fit\"\n      }\n    end\n  end\nend\n"
     }
   ],
   "dependencies": {
@@ -29,16 +29,46 @@
     "gems": []
   },
   "install_command": "rails g ruby_ui:component Tooltip",
-  "docs_markdown": "# Tooltip\n\nA popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.\n\n## Usage\n\n### Example\n\n```ruby\nTooltip do\n  TooltipTrigger do\n    Button(variant: :outline, icon: true) do\n      bookmark_icon\n    end\n  end\n  TooltipContent do\n    Text { \"Add to library\" }\n  end\nend\n```\n\n### Long content\n\n```ruby\nTooltip do\n  TooltipTrigger do\n    Button(variant: :outline) { \"Hover me\" }\n  end\n  TooltipContent do\n    Text { \"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\" }\n  end\nend\n```",
+  "docs_markdown": "# Tooltip\n\nA popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.\n\n## Usage\n\n### Example\n\n```ruby\nTooltip do\n  TooltipTrigger do\n    Button(variant: :outline) { \"Show Tooltip\" }\n  end\n  TooltipContent do\n    p { \"Add to library\" }\n  end\nend\n```\n\n### Sides\n\n```ruby\ndiv(class: \"flex flex-wrap gap-2\") do\n  [:inline_start, :left, :top, :bottom, :right, :inline_end].each do |side|\n    Tooltip do\n      TooltipTrigger do\n        Button(variant: :outline, class: \"capitalize\") { side.to_s.tr(\"_\", \" \") }\n      end\n      TooltipContent(side: side) do\n        p { \"Add to library\" }\n      end\n    end\n  end\nend\n```\n\n### With icon\n\n```ruby\nTooltip do\n  TooltipTrigger do\n    Button(variant: :ghost, icon: true) do\n      bookmark_icon\n      span(class: \"sr-only\") { \"Bookmark\" }\n    end\n  end\n  TooltipContent do\n    p { \"Add to library\" }\n  end\nend\n```\n\n### Long content\n\n```ruby\nTooltip do\n  TooltipTrigger do\n    Button(variant: :outline) { \"Show Tooltip\" }\n  end\n  TooltipContent do\n    plain \"To learn more about how this works, check out the docs. If you have any questions, please reach out to us.\"\n  end\nend\n```\n\n### Disabled button\n\n```ruby\nTooltip do\n  TooltipTrigger do\n    Button(variant: :outline, disabled: true) { \"Disabled\" }\n  end\n  TooltipContent do\n    p { \"This feature is currently unavailable\" }\n  end\nend\n```\n\n### With keyboard shortcut\n\n```ruby\nTooltip do\n  TooltipTrigger do\n    Button(variant: :outline, size: :sm) { \"Save\" }\n  end\n  TooltipContent do\n    plain \"Save Changes\"\n    ShortcutKey { \"S\" }\n  end\nend\n```\n\n### Delay and click\n\n```ruby\nTooltip do\n  TooltipTrigger(delay: 500, close_on_click: false) do\n    Button(variant: :outline) { \"Hover and wait\" }\n  end\n  TooltipContent do\n    p { \"Opened after 500 ms\" }\n  end\nend\n```\n\n### Disabled tooltip\n\n```ruby\nTooltip(disabled: true) do\n  TooltipTrigger do\n    Button(variant: :outline) { \"No tooltip\" }\n  end\n  TooltipContent do\n    p { \"You won't see this\" }\n  end\nend\n```",
   "examples": [
     {
       "title": "Example",
-      "code": "Tooltip do\n  TooltipTrigger do\n    Button(variant: :outline, icon: true) do\n      bookmark_icon\n    end\n  end\n  TooltipContent do\n    Text { \"Add to library\" }\n  end\nend\n",
+      "code": "Tooltip do\n  TooltipTrigger do\n    Button(variant: :outline) { \"Show Tooltip\" }\n  end\n  TooltipContent do\n    p { \"Add to library\" }\n  end\nend\n",
+      "language": "ruby"
+    },
+    {
+      "title": "Sides",
+      "code": "div(class: \"flex flex-wrap gap-2\") do\n  [:inline_start, :left, :top, :bottom, :right, :inline_end].each do |side|\n    Tooltip do\n      TooltipTrigger do\n        Button(variant: :outline, class: \"capitalize\") { side.to_s.tr(\"_\", \" \") }\n      end\n      TooltipContent(side: side) do\n        p { \"Add to library\" }\n      end\n    end\n  end\nend\n",
+      "language": "ruby"
+    },
+    {
+      "title": "With icon",
+      "code": "Tooltip do\n  TooltipTrigger do\n    Button(variant: :ghost, icon: true) do\n      bookmark_icon\n      span(class: \"sr-only\") { \"Bookmark\" }\n    end\n  end\n  TooltipContent do\n    p { \"Add to library\" }\n  end\nend\n",
       "language": "ruby"
     },
     {
       "title": "Long content",
-      "code": "Tooltip do\n  TooltipTrigger do\n    Button(variant: :outline) { \"Hover me\" }\n  end\n  TooltipContent do\n    Text { \"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\" }\n  end\nend\n",
+      "code": "Tooltip do\n  TooltipTrigger do\n    Button(variant: :outline) { \"Show Tooltip\" }\n  end\n  TooltipContent do\n    plain \"To learn more about how this works, check out the docs. If you have any questions, please reach out to us.\"\n  end\nend\n",
+      "language": "ruby"
+    },
+    {
+      "title": "Disabled button",
+      "code": "Tooltip do\n  TooltipTrigger do\n    Button(variant: :outline, disabled: true) { \"Disabled\" }\n  end\n  TooltipContent do\n    p { \"This feature is currently unavailable\" }\n  end\nend\n",
+      "language": "ruby"
+    },
+    {
+      "title": "With keyboard shortcut",
+      "code": "Tooltip do\n  TooltipTrigger do\n    Button(variant: :outline, size: :sm) { \"Save\" }\n  end\n  TooltipContent do\n    plain \"Save Changes\"\n    ShortcutKey { \"S\" }\n  end\nend\n",
+      "language": "ruby"
+    },
+    {
+      "title": "Delay and click",
+      "code": "Tooltip do\n  TooltipTrigger(delay: 500, close_on_click: false) do\n    Button(variant: :outline) { \"Hover and wait\" }\n  end\n  TooltipContent do\n    p { \"Opened after 500 ms\" }\n  end\nend\n",
+      "language": "ruby"
+    },
+    {
+      "title": "Disabled tooltip",
+      "code": "Tooltip(disabled: true) do\n  TooltipTrigger do\n    Button(variant: :outline) { \"No tooltip\" }\n  end\n  TooltipContent do\n    p { \"You won't see this\" }\n  end\nend\n",
       "language": "ruby"
     }
   ]