Let a tooltip linger, and tell the screen reader what it says

A plain tooltip vanished the instant the pointer left, where M3 keeps one for
1.5s and shows only one at a time — these are popover="manual", so nothing was
closing the last one. A rich tooltip's bubble was never associated with its
trigger at all, so the explanation it exists to give was never announced; the
script now writes aria-describedby (and aria-haspopup/aria-expanded when it is
persistent) onto the focusable control in the trigger slot, and again after a
morph. Plan step 18, actions.md ACT-22, ACT-25.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9

resources/boost/skills/livewire-material-development/SKILL.md

@@ -242,7 +242,7 @@ Label button, icon button, toggle and responsive FAB in one component.
 
 ### `<x-tooltip>`
 
-M3's plain tooltip, standalone around any trigger: `<x-tooltip text="Copy link" side="bottom"><button>…</button></x-tooltip>`. `side`: `top` (default), `bottom`, `left`, `right`. Shows on hover (fine pointers) and keyboard focus; `aria-hidden`, so the trigger still needs its own accessible name. Buttons and FABs take a `tooltip` prop instead.
+M3's plain tooltip, standalone around any trigger: `<x-tooltip text="Copy link" side="bottom"><button>…</button></x-tooltip>`. `side`: `top` (default), `bottom`, `left`, `right`. Shows on hover (fine pointers) and keyboard focus, and goes 1.5s after the pointer or the focus leaves it (M3's transient tooltip); only one is on screen at a time. It is `aria-hidden`, so the trigger has to carry the same words itself — as an icon button's `aria-label` does. Where the tip says something the trigger does not, use `<x-rich-tooltip>`, which points the trigger at its text. Buttons and FABs take a `tooltip` prop instead.
 
 ### `<x-menu>`, `<x-menu-item>`, `<x-menu-group>`, `<x-menu-separator>`
 
@@ -400,7 +400,7 @@ A few lines of context around a trigger, with an optional `title` and `actions`
 </x-rich-tooltip>
 ```
 
-Shows on hover and keyboard focus; `persistent` opens it on press and keeps it until a press elsewhere or Escape (use it when there are actions). An open bubble stays open while the Livewire component around it renders, its actions' `wire:click` included. `side`: `bottom` (default), `top`, `left`, `right`.
+Shows on hover and keyboard focus; `persistent` opens it on press and keeps it until a press elsewhere or Escape (use it when there are actions). The trigger is pointed at the bubble with `aria-describedby`, so its words are read out with the control. An open bubble stays open while the Livewire component around it renders, its actions' `wire:click` included. `side`: `bottom` (default), `top`, `left`, `right`.
 
 ### `<x-stat>`
 

resources/js/rich-tooltip.js

@@ -4,6 +4,13 @@
  * Transient (the default): like a plain tooltip — after a short hover on a pointer that can hover,
  * at once on keyboard focus, and it stays while the pointer moves onto the bubble to reach its
  * actions. Persistent: a press on the trigger opens it as a light-dismiss popover.
+ *
+ * The trigger is pointed at the bubble with `aria-describedby`, so the explanation — the whole
+ * point of a rich tooltip — is read out with the control rather than never at all; a persistent
+ * one also says `aria-haspopup="dialog"` and whether it is open. The server cannot write any of
+ * it: the trigger comes from a slot, and only script knows which element in it takes the focus.
+ * A Livewire morph strips attributes the server did not render and gives the bubble a new id, so
+ * they are written again whenever the trigger is reached.
  */
 const HOVER_DELAY_MS = 500
 const LEAVE_GRACE_MS = 200
@@ -17,6 +24,28 @@ document.addEventListener('alpine:init', () => {
             const wrapper = this.$el
             const open = () => bubble.matches(':popover-open')
 
+            const control = () => [...wrapper.querySelectorAll('button, a[href], [tabindex]')].find((element) => !bubble.contains(element))
+
+            const describe = () => {
+                const trigger = control()
+
+                if (!trigger) {
+                    return
+                }
+
+                trigger.setAttribute('aria-describedby', bubble.id)
+
+                if (persistent) {
+                    trigger.setAttribute('aria-haspopup', 'dialog')
+                    trigger.setAttribute('aria-expanded', String(open()))
+                }
+            }
+
+            describe()
+            bubble.addEventListener('toggle', describe)
+            wrapper.addEventListener('focusin', describe)
+            wrapper.addEventListener('pointerenter', describe)
+
             if (persistent) {
                 wrapper.addEventListener('click', (event) => {
                     if (bubble.contains(event.target)) {

resources/js/tooltip.js

@@ -3,10 +3,15 @@
  *
  * The trigger is the popover's parent element (the button, or the standalone wrapper). Hover
  * counts only for a pointer that can hover, after a short delay so a pointer passing over a
- * toolbar does not flash every label; keyboard focus shows it at once. A press, leaving, blur
+ * toolbar does not flash every label; keyboard focus shows it at once. A press and Escape hide it
- * and Escape hide it.
+ * at once; leaving and blur let it stand for M3's 1.5s, so the words can still be read while the
+ * pointer moves on. Only one tooltip is up at a time: showing one takes the last one down, which
+ * the browser will not do for us because these are `popover="manual"`.
  */
 const HOVER_DELAY_MS = 500
+const LEAVE_DELAY_MS = 1500
+
+let visible = null
 
 document.addEventListener('alpine:init', () => {
     window.Alpine.data('materialTooltip', () => ({
@@ -22,25 +27,37 @@ document.addEventListener('alpine:init', () => {
             const show = (delay) => {
                 clearTimeout(this.timer)
                 this.timer = setTimeout(() => {
-                    if (tip.isConnected && !open()) {
+                    if (!tip.isConnected || open()) {
+                        return
+                    }
+
+                    if (visible && visible !== tip && visible.matches(':popover-open')) {
+                        visible.hidePopover()
+                    }
+
+                    visible = tip
                     tip.showPopover()
+                }, delay)
+            }
+
+            const hide = (delay = 0) => {
+                clearTimeout(this.timer)
+                this.timer = setTimeout(() => {
+                    if (open()) {
+                        tip.hidePopover()
+                    }
+
+                    if (visible === tip) {
+                        visible = null
                     }
                 }, delay)
             }
 
-            const hide = () => {
-                clearTimeout(this.timer)
-
-                if (open()) {
-                    tip.hidePopover()
-                }
-            }
-
             this.listen(trigger, 'pointerenter', (event) => event.pointerType === 'mouse' && show(HOVER_DELAY_MS))
-            this.listen(trigger, 'pointerleave', hide)
+            this.listen(trigger, 'pointerleave', () => hide(LEAVE_DELAY_MS))
-            this.listen(trigger, 'pointerdown', hide)
+            this.listen(trigger, 'pointerdown', () => hide())
             this.listen(trigger, 'focusin', () => trigger.matches(':focus-within:has(:focus-visible), :focus-visible') && show(0))
-            this.listen(trigger, 'focusout', hide)
+            this.listen(trigger, 'focusout', () => hide(LEAVE_DELAY_MS))
             this.listen(document, 'keydown', (event) => event.key === 'Escape' && hide())
         },
 
@@ -51,6 +68,11 @@ document.addEventListener('alpine:init', () => {
 
         destroy() {
             clearTimeout(this.timer)
+
+            if (visible === this.$el) {
+                visible = null
+            }
+
             this.listeners.forEach((remove) => remove())
         },
     }))

resources/views/components/rich-tooltip.blade.php

@@ -15,6 +15,12 @@
      action's `wire:click` too — and resources/js/rich-tooltip.js keeps showing and hiding the
      element on the page rather than one the morph took away.
 
+     resources/js/rich-tooltip.js points the trigger at the bubble with `aria-describedby`, and a
+     `persistent` one also carries `aria-haspopup="dialog"` and `aria-expanded`: the explanation is
+     the whole point of a rich tooltip, and without the association a screen reader reads only the
+     trigger's own label. The trigger arrives in a slot, so only script can find the element in it
+     that takes the focus.
+
      RichTooltipTokens (androidx Compose Material 3, Apache-2.0): title-small subhead and body-medium
      text in on-surface-variant, label-large actions in primary. --}}
 

resources/views/components/tooltip.blade.php

@@ -5,8 +5,9 @@
 
          <x-tooltip text="Copy link"><button …>…</button></x-tooltip>
 
-     It shows after a short hover on a pointer that can hover, at once on keyboard focus, and
+     It shows after a short hover on a pointer that can hover, at once on keyboard focus, and hides
-     hides on leave, blur, press and Escape. A phone has no hover, so a control there carries its
+     at once on a press or Escape; leaving or blurring lets it stand for M3's 1.5s. Only one
+     tooltip is on screen at a time, as M3 asks. A phone has no hover, so a control there carries its
      words. The bubble is a `popover="manual"` in the top layer — never clipped by an
      `overflow-hidden` parent, never widening a scroll container — placed by CSS anchor
      positioning on `side` (`top`, `bottom`, `left`, `right`), flipping when there is no room.