daisyui 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d82c1b4f52e8a5b62fb723e83557c1def70805b24c855aced7381c8c2f80dc0e
-  data.tar.gz: 831d1acb486a33fb1b779643d273a58925a921a456d20be7374cf4a5ed6c3cf4
+  metadata.gz: d6868c0a6fbec134472fd51d293059527c056b84c3606fdc460a3335e9ce09f9
+  data.tar.gz: 4eab735dbc402b5967a7d9225fc64cd6fea6a312135762aeca77e0cd46d58f72
 SHA512:
-  metadata.gz: 061d1ff9eb34a488db5ab1aff21491e9c4f8b39912c7749637e3941d9738edd5cbef993b5d52bd6e55620f4b6f4207f9ad7285df0f672507c3552f16be775d1a
-  data.tar.gz: 598db62e9eefc346e30b1d42d449bc49c54c6a80c5d917c21360fb1511ea0ed17380a2c9b2be8b4f1edd647d4281b5b134e18995be66ff1d884de17428a9d127
+  metadata.gz: be45f9a0eb9668b3eec64079656919bce38eac29ad02b6d20f1dfd7a596f7db9398f47c1633995b1091855515273f75e3e848dd244228177d1f138b98d3ae7ce
+  data.tar.gz: ca6520ba004e142524092b29c4e76622b2c05f1002d11c529659fb8874ef34344f0be5160f84f0b966d997d5913f3e6852abd673f1ae18dc4ae22cf53d285598

data/CHANGELOG.md

@@ -19,6 +19,12 @@
   positioning fallback (Safari < 26, Firefox < 147) and optional roving
   keyboard navigation. The default `:popover` dropdown remains zero-JS, and the
   gem stays a plain Phlex library when Rails is absent.
+- `Tooltip` `:popover` modifier for collision-aware tooltips. It renders real
+  tooltip content in the browser top layer, opens on hover or focus, flips and
+  shifts within the visual viewport, follows scroll/resize while open, and
+  exposes `role="tooltip"`/`aria-describedby` semantics. The bundled
+  `daisy-tooltip` Stimulus controller is auto-pinned for importmap-rails apps
+  and supports a custom controller identifier via `stimulus:`.
 
 ### Changed
 

data/README.md

@@ -248,6 +248,58 @@ JS-bundler (esbuild/vite/webpack) consumers: import the controller from the
 gem's `app/javascript/daisy_ui/controllers/daisy_dropdown_controller.js` and
 register it manually.
 
+## Collision-aware `Tooltip(:popover)`
+
+The `:popover` Tooltip modifier renders real tooltip content in the browser top
+layer instead of a `data-tip` pseudo-element. It therefore escapes clipping
+ancestors, and the bundled `daisy-tooltip` controller flips and shifts the
+tooltip to remain inside the visual viewport. Geometry listeners are attached
+only while the tooltip is open.
+
+```ruby
+Tooltip(:popover, tip: "Helpful details") do
+  Button(:circle) { "?" }
+end
+```
+
+Directional and color modifiers compose normally:
+
+```ruby
+Tooltip(:popover, :bottom, :info, tip: "Saved automatically") do
+  Button(:ghost) { "Status" }
+end
+```
+
+Rich content uses the existing `content` sub-component:
+
+```ruby
+Tooltip(:popover) do |tooltip|
+  tooltip.content(class: "max-w-64") do
+    strong { "Keyboard shortcut" }
+    kbd { "⌘ K" }
+  end
+  Button { "Commands" }
+end
+```
+
+Register the gem controllers once with
+`lazyLoadControllersFrom("daisy_ui/controllers", application)`, as shown in the
+dropdown controller section above. Importmap-rails applications receive the
+controller pin from the gem automatically. Bundler applications can import
+`app/javascript/daisy_ui/controllers/daisy_tooltip_controller.js` and register
+it as `daisy-tooltip`.
+
+Popover tooltips:
+
+- open on pointer hover or keyboard focus and close on leave, blur, or Escape;
+- use `role="tooltip"` and merge their id into the first interactive trigger's
+  `aria-describedby`;
+- preserve caller-supplied Stimulus controllers;
+- accept `popover_id:` for a stable tooltip id and `stimulus: "your-id"` to
+  override the controller identifier.
+
+Classic `Tooltip(tip: ...)` rendering remains unchanged.
+
 # MCP Server (Claude Code Integration)
 
 This gem includes an MCP (Model Context Protocol) server that provides component information to AI assistants like Claude Code.

data/app/javascript/daisy_ui/controllers/daisy_tooltip_controller.js

@@ -0,0 +1,231 @@
+import { Controller } from "@hotwired/stimulus"
+
+const VIEWPORT_PADDING = 8
+const GAP = 8
+const ARROW_WIDTH = 10
+const ARROW_HEIGHT = 4
+const FOCUSABLE_SELECTOR = 'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+const OPPOSITE = { top: "bottom", bottom: "top", left: "right", right: "left" }
+
+// daisy-tooltip — positions a :popover Tooltip in the browser top layer.
+//
+// The Popover API escapes clipping ancestors. This controller supplies the
+// hover/focus lifecycle expected of a tooltip, then flips and shifts the real
+// tooltip element only while it is open so it remains inside the visual
+// viewport. No global listeners remain attached while the tooltip is closed.
+export default class extends Controller {
+  static targets = ["content", "arrow"]
+  static values = { placement: { type: String, default: "top" } }
+
+  connect() {
+    if (!this.hasContentTarget) return
+
+    this.originalMaxWidth = this.contentTarget.style.maxWidth
+    this.onPointerEnter = () => this.show()
+    this.onPointerLeave = () => this.#hideUnlessFocused()
+    this.onFocusIn = () => this.show()
+    this.onFocusOut = (event) => this.#handleFocusOut(event)
+    this.onKeydown = (event) => this.#handleKeydown(event)
+    this.onGeometryChange = () => this.#schedulePosition()
+
+    this.element.addEventListener("pointerenter", this.onPointerEnter)
+    this.element.addEventListener("pointerleave", this.onPointerLeave)
+    this.element.addEventListener("focusin", this.onFocusIn)
+    this.element.addEventListener("focusout", this.onFocusOut)
+    this.#describeTrigger()
+
+    if (this.element.classList.contains("tooltip-open")) this.show()
+  }
+
+  disconnect() {
+    this.element.removeEventListener("pointerenter", this.onPointerEnter)
+    this.element.removeEventListener("pointerleave", this.onPointerLeave)
+    this.element.removeEventListener("focusin", this.onFocusIn)
+    this.element.removeEventListener("focusout", this.onFocusOut)
+    this.#teardownOpen()
+    this.#restoreDescription()
+    if (this.hasContentTarget) this.contentTarget.style.maxWidth = this.originalMaxWidth
+  }
+
+  show() {
+    if (!this.hasContentTarget || this.#isOpen()) return
+
+    this.contentTarget.style.visibility = "hidden"
+    this.contentTarget.showPopover()
+    this.#setupOpen()
+    this.#schedulePosition()
+  }
+
+  hide() {
+    if (this.#isOpen()) this.contentTarget.hidePopover()
+    this.contentTarget.style.visibility = "hidden"
+    this.#teardownOpen()
+  }
+
+  #setupOpen() {
+    window.addEventListener("resize", this.onGeometryChange)
+    window.addEventListener("scroll", this.onGeometryChange, true)
+    window.addEventListener("keydown", this.onKeydown)
+    window.visualViewport?.addEventListener("resize", this.onGeometryChange)
+    window.visualViewport?.addEventListener("scroll", this.onGeometryChange)
+  }
+
+  #teardownOpen() {
+    cancelAnimationFrame(this.frame)
+    window.removeEventListener("resize", this.onGeometryChange)
+    window.removeEventListener("scroll", this.onGeometryChange, true)
+    window.removeEventListener("keydown", this.onKeydown)
+    window.visualViewport?.removeEventListener("resize", this.onGeometryChange)
+    window.visualViewport?.removeEventListener("scroll", this.onGeometryChange)
+  }
+
+  #schedulePosition() {
+    cancelAnimationFrame(this.frame)
+    this.frame = requestAnimationFrame(() => this.#position())
+  }
+
+  #position() {
+    if (!this.#isOpen()) return
+
+    const viewport = this.#viewport()
+    const availableWidth = Math.max(0, viewport.width - VIEWPORT_PADDING * 2)
+    this.contentTarget.style.maxWidth = this.originalMaxWidth
+    const computedMaxWidth = Number.parseFloat(getComputedStyle(this.contentTarget).maxWidth)
+    const maxWidth = Number.isFinite(computedMaxWidth) ? Math.min(computedMaxWidth, availableWidth) : availableWidth
+    this.contentTarget.style.maxWidth = `${maxWidth}px`
+
+    const trigger = this.element.getBoundingClientRect()
+    const tooltip = this.contentTarget.getBoundingClientRect()
+    const preferred = this.#coordinates(this.placementValue, trigger, tooltip)
+    const oppositePlacement = OPPOSITE[this.placementValue] || "bottom"
+    const opposite = this.#coordinates(oppositePlacement, trigger, tooltip)
+    const useOpposite = this.#overflow(opposite, tooltip, viewport) < this.#overflow(preferred, tooltip, viewport)
+    const placement = useOpposite ? oppositePlacement : this.placementValue
+    const coordinates = useOpposite ? opposite : preferred
+    const { x, y } = this.#shift(coordinates, tooltip, viewport)
+
+    Object.assign(this.contentTarget.style, { left: `${x}px`, top: `${y}px`, visibility: "visible" })
+    this.#positionArrow(placement, trigger, tooltip, x, y)
+  }
+
+  #coordinates(placement, trigger, tooltip) {
+    const centerX = trigger.left + trigger.width / 2
+    const centerY = trigger.top + trigger.height / 2
+
+    switch (placement) {
+      case "bottom":
+        return { x: centerX - tooltip.width / 2, y: trigger.bottom + GAP }
+      case "left":
+        return { x: trigger.left - tooltip.width - GAP, y: centerY - tooltip.height / 2 }
+      case "right":
+        return { x: trigger.right + GAP, y: centerY - tooltip.height / 2 }
+      default:
+        return { x: centerX - tooltip.width / 2, y: trigger.top - tooltip.height - GAP }
+    }
+  }
+
+  #overflow({ x, y }, tooltip, viewport) {
+    const left = viewport.left + VIEWPORT_PADDING
+    const right = viewport.left + viewport.width - VIEWPORT_PADDING
+    const top = viewport.top + VIEWPORT_PADDING
+    const bottom = viewport.top + viewport.height - VIEWPORT_PADDING
+
+    return (
+      Math.max(0, left - x) +
+      Math.max(0, x + tooltip.width - right) +
+      Math.max(0, top - y) +
+      Math.max(0, y + tooltip.height - bottom)
+    )
+  }
+
+  #shift({ x, y }, tooltip, viewport) {
+    const left = viewport.left + VIEWPORT_PADDING
+    const right = viewport.left + viewport.width - VIEWPORT_PADDING
+    const top = viewport.top + VIEWPORT_PADDING
+    const bottom = viewport.top + viewport.height - VIEWPORT_PADDING
+
+    return {
+      x: tooltip.width > right - left ? left : Math.min(Math.max(x, left), right - tooltip.width),
+      y: tooltip.height > bottom - top ? top : Math.min(Math.max(y, top), bottom - tooltip.height),
+    }
+  }
+
+  #positionArrow(placement, trigger, tooltip, x, y) {
+    if (!this.hasArrowTarget) return
+
+    const centerX = trigger.left + trigger.width / 2 - x
+    const centerY = trigger.top + trigger.height / 2 - y
+    const arrow = this.arrowTarget.style
+    Object.assign(arrow, { inset: "auto", transform: "none" })
+
+    if (placement === "top" || placement === "bottom") {
+      arrow.left = `${this.#clamp(centerX - ARROW_WIDTH / 2, 4, tooltip.width - ARROW_WIDTH - 4)}px`
+      if (placement === "top") arrow.bottom = `${-ARROW_HEIGHT}px`
+      else {
+        arrow.top = `${-ARROW_HEIGHT}px`
+        arrow.transform = "rotate(180deg)"
+      }
+      return
+    }
+
+    arrow.top = `${this.#clamp(centerY - ARROW_HEIGHT / 2, 4, tooltip.height - ARROW_HEIGHT - 4)}px`
+    if (placement === "left") {
+      arrow.right = "-7px"
+      arrow.transform = "rotate(-90deg)"
+    } else {
+      arrow.left = "-7px"
+      arrow.transform = "rotate(90deg)"
+    }
+  }
+
+  #viewport() {
+    const visualViewport = window.visualViewport
+    return {
+      left: visualViewport?.offsetLeft ?? 0,
+      top: visualViewport?.offsetTop ?? 0,
+      width: visualViewport?.width ?? window.innerWidth,
+      height: visualViewport?.height ?? window.innerHeight,
+    }
+  }
+
+  #handleFocusOut(event) {
+    if (!this.element.contains(event.relatedTarget)) this.hide()
+  }
+
+  #hideUnlessFocused() {
+    if (!this.element.matches(":focus-within")) this.hide()
+  }
+
+  #handleKeydown(event) {
+    if (event.key !== "Escape") return
+
+    this.hide()
+  }
+
+  #describeTrigger() {
+    const trigger = this.element.matches(FOCUSABLE_SELECTOR)
+      ? this.element
+      : this.element.querySelector(FOCUSABLE_SELECTOR)
+    if (!trigger || !this.contentTarget.id) return
+
+    this.describedTrigger = trigger
+    this.previousDescription = trigger.getAttribute("aria-describedby")
+    const descriptions = this.previousDescription?.split(/\s+/).filter(Boolean) || []
+    trigger.setAttribute("aria-describedby", [...new Set([...descriptions, this.contentTarget.id])].join(" "))
+  }
+
+  #restoreDescription() {
+    if (!this.describedTrigger) return
+
+    if (this.previousDescription === null) this.describedTrigger.removeAttribute("aria-describedby")
+    else this.describedTrigger.setAttribute("aria-describedby", this.previousDescription)
+  }
+
+  #isOpen() {
+    return this.hasContentTarget && this.contentTarget.matches(":popover-open")
+  }
+
+  #clamp(value, minimum, maximum) {
+    return Math.min(Math.max(value, minimum), Math.max(minimum, maximum))
+  }
+}

data/config/importmap.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Auto-pins the gem's bundled Stimulus controllers for importmap-rails consumers.
-# Exposes `daisy_ui/controllers/daisy_dropdown_controller`. Register it in the
-# host app (lazily recommended):
+# Exposes the bundled `daisy-dropdown` and `daisy-tooltip` controllers. Register
+# them in the host app (lazily recommended):
 #
 #   // app/javascript/controllers/index.js
 #   import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"

data/lib/daisy_ui/tooltip.rb

@@ -1,28 +1,117 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module DaisyUI
   class Tooltip < Base
     self.component_class = :tooltip
 
-    def initialize(*, tip: nil, as: :div, **)
-      super(*, as:, **)
+    PLACEMENTS = %i[top bottom left right].freeze
+    DEFAULT_STIMULUS_IDENTIFIER = "daisy-tooltip"
+    POPOVER_STYLE = "position:fixed;inset:auto;margin:0;border:0;opacity:1;transform:none;pointer-events:none;visibility:hidden"
+    ARROW_STYLE = "position:absolute;width:.625rem;height:.25rem;background:var(--tt-bg);" \
+                  "clip-path:polygon(0 0,100% 0,50% 100%);pointer-events:none"
+
+    def initialize(*modifiers, tip: nil, as: :div, popover_id: nil, stimulus: true, **options)
+      @popover = modifiers.include?(:popover)
+      @popover_id = popover_id if @popover
+      @stimulus = stimulus
       @tip = tip
+      if popover?
+        validate_stimulus!
+        boolean_placements = PLACEMENTS.select { |candidate| options[candidate] == true }
+        wire_controller(options, modifiers + boolean_placements)
+      end
+      super(*modifiers, as:, **options)
     end
 
     def view_template(&)
-      opts = { class: classes, **attributes }
-      opts[:data_tip] = tip if tip
-      public_send(as, **opts, &)
+      if popover?
+        public_send(as, class: merge_classes(classes, "after:hidden"), **attributes) do
+          yield self if block_given?
+          content { plain tip } if tip && !@content_rendered
+        end
+      else
+        opts = { class: classes, **attributes }
+        opts[:data_tip] = tip if tip
+        public_send(as, **opts, &)
+      end
     end
 
     def content(**options, &)
-      div(class: component_classes("tooltip-content", options:), **options, &)
+      if popover?
+        @content_rendered = true
+        options[:id] ||= popover_id
+        options[:popover] = "manual"
+        options[:role] ||= "tooltip"
+        options[:style] = merge_style(options[:style], POPOVER_STYLE)
+        merge_stimulus_target(options, "content")
+
+        div(class: component_classes("tooltip-content", options:), **options) do
+          span(
+            aria_hidden: "true",
+            data: { stimulus_target_key => "arrow" },
+            style: ARROW_STYLE
+          )
+          yield if block_given?
+        end
+      else
+        div(class: component_classes("tooltip-content", options:), **options, &)
+      end
     end
 
     private
 
     attr_reader :tip
 
+    def popover?
+      @popover
+    end
+
+    def popover_id
+      @popover_id ||= "tooltip_#{SecureRandom.hex(8)}"
+    end
+
+    def stimulus_identifier
+      return DEFAULT_STIMULUS_IDENTIFIER if @stimulus == true
+
+      @stimulus.to_s
+    end
+
+    def validate_stimulus!
+      valid_identifier = (@stimulus.is_a?(String) || @stimulus.is_a?(Symbol)) && @stimulus.to_s.match?(/\A\S+\z/)
+      return if @stimulus == true || valid_identifier
+
+      raise ArgumentError, "stimulus must be true or a non-empty controller identifier in popover mode"
+    end
+
+    def stimulus_target_key
+      :"#{stimulus_identifier}_target"
+    end
+
+    def placement(source_modifiers = modifiers)
+      PLACEMENTS.find { |candidate| source_modifiers.include?(candidate) } || :top
+    end
+
+    def wire_controller(options, source_modifiers)
+      data = (options[:data] || {}).dup
+      controllers = data[:controller].to_s.split
+      data[:controller] = (controllers + [stimulus_identifier]).uniq.join(" ")
+      data[:"#{stimulus_identifier}_placement_value"] = placement(source_modifiers)
+      options[:data] = data
+    end
+
+    def merge_stimulus_target(options, target)
+      data = (options[:data] || {}).dup
+      targets = data[stimulus_target_key].to_s.split
+      data[stimulus_target_key] = (targets + [target]).uniq.join(" ")
+      options[:data] = data
+    end
+
+    def merge_style(existing, added)
+      [existing&.chomp(";"), added].compact.join(";")
+    end
+
     register_modifiers(
       # "sm:tooltip-open"
       # "@sm:tooltip-open"

data/lib/daisy_ui/updated_at.rb

@@ -3,5 +3,5 @@
 module DaisyUI
   # This timestamp is automatically updated when releasing a new version
   # Format: YYYY-MM-DD HH:MM:SS UTC
-  UPDATED_AT = "2026-06-26 15:27:35 UTC"
+  UPDATED_AT = "2026-08-30 12:32:05 UTC"
 end

data/lib/daisy_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DaisyUI
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: daisyui
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -56,6 +56,7 @@ files:
 - LICENSE.txt
 - README.md
 - app/javascript/daisy_ui/controllers/daisy_dropdown_controller.js
+- app/javascript/daisy_ui/controllers/daisy_tooltip_controller.js
 - config/importmap.rb
 - exe/daisyui-mcp
 - lib/daisy_ui.rb