entasis 0.11.0 → 0.12.0

package/dist/components/Tooltip/tooltip.attachment.svelte.js

@@ -1,41 +1,152 @@
+import { untrack } from 'svelte';
+import { on } from 'svelte/events';
 import { useTheme } from '../Theme/theme.state.svelte.js';
+import { getDeepActiveElement } from '../../utils/focus.js';
 import { useHoverAction } from '../../utils/useHoverAction.svelte.js';
-import { on } from 'svelte/events';
+import { isRestoringFocus } from '../../utils/useFocusScope.svelte.js';
+import { requestTooltipChange, watchTooltipContentHover } from './tooltip.surface.js';
 const FOCUSABLE = 'a[href], button, input, select, textarea, summary, [tabindex], [contenteditable]:not([contenteditable="false"])';
+/**
+ * Least time, in milliseconds, a tooltip with hoverable content stays open after the pointer
+ * leaves its trigger, so the pointer can cross the gap to the content.
+ */
+export const TOOLTIP_CONTENT_GRACE = 100;
+/** Whether the focus that just arrived shows a focus ring (keyboard focus, not a click or a tap). */
+const showsFocusRing = (target) => {
+    if (!(target instanceof Element))
+        return true;
+    try {
+        return target.matches(':focus-visible');
+    }
+    catch {
+        // An engine without `:focus-visible` gets the tooltip on any focus, as it always did.
+        return true;
+    }
+};
 export const tooltip = (props) => {
     const theme = useTheme();
     let refElement = null;
-    const hoverAction = useHoverAction({
-        isActive: () => true,
-        onMouseEnter: () => {
-            if (refElement) {
-                theme.tooltip = { ...props, ref: refElement };
+    // A press closes the tooltip and keeps it closed until the pointer leaves or focus moves on.
+    let pressed = false;
+    // Focus that comes back with the window is not the user moving focus onto the trigger.
+    let windowReturning = false;
+    let overContent = false;
+    let hideTimer = null;
+    const clearHideTimer = () => {
+        if (hideTimer !== null)
+            clearTimeout(hideTimer);
+        hideTimer = null;
+    };
+    // A tooltip opened by hover closes when the pointer leaves, but `mouseleave` is not guaranteed:
+    // a trigger re-rendered, moved or removed under the pointer (a navigation that updates the
+    // active item of a rail, say) may never send one. While such a tooltip shows, every pointer move
+    // that lands on neither the trigger nor the tooltip's content closes it after the usual grace.
+    let offStrayPointer = null;
+    let strayTimer = null;
+    const clearStrayTimer = () => {
+        if (strayTimer !== null)
+            clearTimeout(strayTimer);
+        strayTimer = null;
+    };
+    const stopWatchingPointer = () => {
+        offStrayPointer?.();
+        offStrayPointer = null;
+        clearStrayTimer();
+    };
+    const isOnTooltip = (ref, target) => {
+        if (!(target instanceof Node))
+            return false;
+        if (ref.isConnected && ref.contains(target))
+            return true;
+        const surface = theme.tooltipId ? ref.ownerDocument.getElementById(theme.tooltipId) : null;
+        return props.hoverable !== false && !!surface?.contains(target);
+    };
+    const watchPointer = (ref) => {
+        if (offStrayPointer)
+            return;
+        offStrayPointer = on(ref.ownerDocument, 'pointermove', (event) => {
+            if (event.pointerType === 'touch')
+                return;
+            if (theme.tooltip?.ref !== ref) {
+                stopWatchingPointer();
+                return;
             }
-        },
-        onMouseLeave: () => {
-            if (theme.tooltip?.ref !== refElement)
+            const target = event.composedPath?.()[0] ?? event.target;
+            if (isOnTooltip(ref, target)) {
+                clearStrayTimer();
                 return;
-            theme.tooltip = null;
-            theme.lastTooltipClosed = Date.now();
-        },
-        get delay() {
-            const lastTooltipClosed = theme.lastTooltipClosed;
-            const now = Date.now();
-            if (lastTooltipClosed && now - lastTooltipClosed < (props.delay ?? 400)) {
-                return 0;
             }
-            return props.delay ?? 400;
+            if (strayTimer !== null)
+                return;
+            const closeDelay = Math.max(0, props.closeDelay ?? 0);
+            const delay = props.hoverable === false ? closeDelay : Math.max(closeDelay, TOOLTIP_CONTENT_GRACE);
+            strayTimer = setTimeout(() => {
+                strayTimer = null;
+                // The hover the trigger still believes in is stale; drop it so a later enter starts fresh.
+                hoverAction.cancel();
+                hide({ reason: 'trigger-hover', event, interaction: 'mouse' });
+            }, delay);
+        }, { capture: true, passive: true });
+    };
+    const show = (init) => {
+        const ref = refElement;
+        clearHideTimer();
+        if (!ref || props.disabled || pressed)
+            return;
+        if (requestTooltipChange(theme, { ...props, ref }, init) && init.interaction === 'mouse') {
+            watchPointer(ref);
         }
-    });
-    const show = (ref) => {
-        theme.tooltip = { ...props, ref };
     };
-    const hide = (ref) => {
-        if (theme.tooltip?.ref !== ref)
+    const hide = (init) => {
+        clearHideTimer();
+        stopWatchingPointer();
+        // The content goes away with the tooltip, without telling the trigger the pointer left it.
+        overContent = false;
+        const ref = refElement;
+        if (!ref || theme.tooltip?.ref !== ref)
             return;
-        theme.tooltip = null;
-        theme.lastTooltipClosed = Date.now();
+        requestTooltipChange(theme, null, init);
     };
+    // The pointer left the trigger or its content. Content that can be hovered keeps the tooltip
+    // open for a moment so the pointer can reach it; a re-entry or the next tooltip cancels or
+    // replaces the close, and the warm-up window for the next hover starts right now.
+    const scheduleHide = (init) => {
+        clearHideTimer();
+        const ref = refElement;
+        if (!ref || theme.tooltip?.ref !== ref)
+            return;
+        theme.hoverIntent.markClosed();
+        const closeDelay = Math.max(0, props.closeDelay ?? 0);
+        const delay = props.hoverable === false ? closeDelay : Math.max(closeDelay, TOOLTIP_CONTENT_GRACE);
+        if (delay === 0) {
+            hide(init);
+            return;
+        }
+        hideTimer = setTimeout(() => {
+            hideTimer = null;
+            if (overContent || hoverAction.isHovered)
+                return;
+            hide(init);
+        }, delay);
+    };
+    const hoverAction = useHoverAction({
+        isActive: () => !props.disabled,
+        onMouseEnter: (event) => {
+            show({ reason: 'trigger-hover', event, interaction: 'mouse' });
+        },
+        onMouseLeave: (event) => {
+            pressed = false;
+            scheduleHide({ reason: 'trigger-hover', event, interaction: 'mouse' });
+        },
+        get delay() {
+            return props.delay ?? 400;
+        },
+        // Right after another tooltip, hover card or hover popover, the next tooltip shows at once.
+        // TooltipHost reports the shared surface's closes to the group.
+        group: () => theme.hoverIntent,
+        // A tooltip often explains why its trigger is disabled.
+        skipDisabled: false
+    });
     return (ref) => {
         refElement = ref;
         // Keyboard users reach the tooltip by focusing its trigger, so an element the browser
@@ -43,9 +154,79 @@ export const tooltip = (props) => {
         if (!ref.matches(FOCUSABLE))
             ref.tabIndex = 0;
         const off = hoverAction.reference?.(ref);
-        // Keyboard users get the tooltip on focus; screen readers get it via aria-describedby.
-        const offFocus = on(ref, 'focusin', () => show(ref));
-        const offBlur = on(ref, 'focusout', () => hide(ref));
+        const press = (event) => {
+            if (props.closeOnClick === false)
+                return;
+            pressed = true;
+            hoverAction.cancel();
+            hide({ reason: 'trigger-press', event });
+        };
+        const win = ref.ownerDocument.defaultView;
+        let windowFocusTimer = null;
+        const offs = [
+            // A new hover on the trigger ends the wait to close and the press that closed it.
+            on(ref, 'mouseenter', () => {
+                clearHideTimer();
+            }),
+            on(ref, 'pointerenter', (event) => {
+                if (event.pointerType !== 'touch')
+                    pressed = false;
+            }),
+            on(ref, 'pointerdown', (event) => {
+                // A touch never opens a tooltip, so there is nothing to close, and the press that
+                // follows is not a pointer leaving.
+                if (event.pointerType === 'touch' || event.button !== 0)
+                    return;
+                press(event);
+            }),
+            // Enter or Space on a focused trigger: a click with no pointer behind it.
+            // A click from code, or from Enter in a form field, reaches a trigger nobody focused.
+            on(ref, 'click', (event) => {
+                if (event.detail === 0 && getDeepActiveElement(ref.ownerDocument) === ref)
+                    press(event);
+            }),
+            // Keyboard users get the tooltip on focus when the focus ring shows; a click, a tap, focus
+            // the page gave back (a closing dialog) or the window returning do not open it. Screen
+            // readers get the text through aria-describedby.
+            on(ref, 'focusin', (event) => {
+                if (windowReturning || isRestoringFocus() || !showsFocusRing(event.target))
+                    return;
+                show({ reason: 'trigger-focus', event, interaction: 'keyboard' });
+            }),
+            on(ref, 'focusout', (event) => {
+                pressed = false;
+                hide({ reason: 'trigger-focus', event, interaction: 'keyboard' });
+            }),
+            watchTooltipContentHover(ref, (inside, event) => {
+                overContent = inside;
+                if (inside)
+                    clearHideTimer();
+                else if (!hoverAction.isHovered)
+                    scheduleHide({ reason: 'trigger-hover', event, interaction: 'mouse' });
+            })
+        ];
+        if (win) {
+            offs.push(on(win, 'blur', () => {
+                if (getDeepActiveElement(ref.ownerDocument) === ref)
+                    windowReturning = true;
+            }), on(win, 'focus', () => {
+                // The trigger's own `focusin` for the return arrives around this event.
+                if (windowFocusTimer !== null)
+                    clearTimeout(windowFocusTimer);
+                windowFocusTimer = setTimeout(() => {
+                    windowFocusTimer = null;
+                    windowReturning = false;
+                });
+            }));
+        }
+        $effect(() => {
+            if (!props.disabled)
+                return;
+            untrack(() => {
+                pressed = false;
+                hide({ reason: 'imperative-action' });
+            });
+        });
         $effect(() => {
             const active = theme.tooltip?.ref === ref && theme.tooltipId;
             if (!active)
@@ -61,13 +242,14 @@ export const tooltip = (props) => {
         });
         return () => {
             off?.();
-            offFocus();
-            offBlur();
+            offs.forEach((stop) => stop());
+            clearHideTimer();
+            stopWatchingPointer();
+            if (windowFocusTimer !== null)
+                clearTimeout(windowFocusTimer);
             hoverAction.destroy();
-            if (theme.tooltip?.ref === ref) {
+            if (theme.tooltip?.ref === ref)
                 theme.tooltip = null;
-                theme.lastTooltipClosed = Date.now();
-            }
             if (refElement === ref)
                 refElement = null;
         };

package/dist/components/Tooltip/tooltip.attributes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The styling hooks a tooltip exposes. Attributes are presence attributes (`''` while the state
+ * holds, omitted otherwise) unless the description says they carry a value. The surface is the
+ * `role="tooltip"` element a tooltip's `class` and theme style.
+ */
+export declare const tooltipDataAttributes: {
+    readonly 'data-open': "On the surface: present while the tooltip shows.";
+    readonly 'data-closed': "On the surface: present while its exit transition plays.";
+    readonly 'data-entering': "On the surface: present while the enter transition plays.";
+    readonly 'data-exiting': "On the surface: present while the exit transition plays.";
+    readonly 'data-side': "On the surface: the side of the trigger it sits on after flipping, `top`, `right`, `bottom` or `left`.";
+    readonly 'data-align': "On the surface: `start`, `center` or `end`, how it lines up with the trigger.";
+    readonly 'data-anchor-hidden': "On the surface: present while the trigger is scrolled out of view.";
+    readonly 'data-instant': "On the surface: present while it moved straight from one trigger to another, which plays no transition.";
+    readonly 'data-color': "On the surface: the resolved `color`.";
+    readonly 'data-size': "On the surface: the resolved `size`.";
+    readonly 'data-variant': "On the surface: the resolved `variant`.";
+    readonly 'data-popup-open': "On the trigger: present while its tooltip shows.";
+    readonly 'data-popup-side': "On the trigger: the surface's `data-side` while it is placed.";
+};
+/** The name of a tooltip data attribute. */
+export type TooltipDataAttribute = keyof typeof tooltipDataAttributes;
+/** Written by the placement on the positioned wrapper and inherited by the surface. */
+export declare const tooltipCssVariables: {
+    readonly '--available-width': "The width in px the surface can take before it reaches the viewport edges, minus 20px.";
+    readonly '--available-height': "The room in px between the trigger and the viewport edge on the surface's side, minus 20px.";
+    readonly '--anchor-width': "The trigger's width in px, snapped to the device pixel grid.";
+    readonly '--anchor-height': "The trigger's height in px, snapped to the device pixel grid.";
+    readonly '--transform-origin': "The surface corner facing the trigger, the point it scales from.";
+};
+/** The name of a tooltip CSS variable. */
+export type TooltipCssVariable = keyof typeof tooltipCssVariables;

package/dist/components/Tooltip/tooltip.attributes.js

@@ -0,0 +1,28 @@
+/**
+ * The styling hooks a tooltip exposes. Attributes are presence attributes (`''` while the state
+ * holds, omitted otherwise) unless the description says they carry a value. The surface is the
+ * `role="tooltip"` element a tooltip's `class` and theme style.
+ */
+export const tooltipDataAttributes = {
+    'data-open': 'On the surface: present while the tooltip shows.',
+    'data-closed': 'On the surface: present while its exit transition plays.',
+    'data-entering': 'On the surface: present while the enter transition plays.',
+    'data-exiting': 'On the surface: present while the exit transition plays.',
+    'data-side': 'On the surface: the side of the trigger it sits on after flipping, `top`, `right`, `bottom` or `left`.',
+    'data-align': 'On the surface: `start`, `center` or `end`, how it lines up with the trigger.',
+    'data-anchor-hidden': 'On the surface: present while the trigger is scrolled out of view.',
+    'data-instant': 'On the surface: present while it moved straight from one trigger to another, which plays no transition.',
+    'data-color': 'On the surface: the resolved `color`.',
+    'data-size': 'On the surface: the resolved `size`.',
+    'data-variant': 'On the surface: the resolved `variant`.',
+    'data-popup-open': 'On the trigger: present while its tooltip shows.',
+    'data-popup-side': "On the trigger: the surface's `data-side` while it is placed."
+};
+/** Written by the placement on the positioned wrapper and inherited by the surface. */
+export const tooltipCssVariables = {
+    '--available-width': 'The width in px the surface can take before it reaches the viewport edges, minus 20px.',
+    '--available-height': "The room in px between the trigger and the viewport edge on the surface's side, minus 20px.",
+    '--anchor-width': "The trigger's width in px, snapped to the device pixel grid.",
+    '--anchor-height': "The trigger's height in px, snapped to the device pixel grid.",
+    '--transform-origin': 'The surface corner facing the trigger, the point it scales from.'
+};

package/dist/components/Tooltip/tooltip.mcp.d.ts

@@ -1 +1 @@
-export declare const tooltipDescription = "\n# Tooltip\n\nContextual information shown on hover or keyboard focus. Two forms share one surface:\n\n- `<Tooltip>` \u2014 a component with a `trigger` prop, like every other overlay.\n- `tooltip()` \u2014 the underlying attachment, for elements you already render yourself.\n\nBoth are rendered by the single tooltip surface that `<Theme>` mounts (`TooltipHost`).\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Click to submit\" trigger={{ content: 'Submit', variant: 'outline' }} />\n```\n\n## Props\n\n- **content**: string | Snippet (required) - Tooltip body\n- **trigger**: Snippet<[Attachment<HTMLElement>]> | ButtonProps & { content?: string } (required) -\n  A snippet receives the tooltip attachment and spreads it on its own element; an element the\n  browser cannot focus (a span, an icon) gets `tabindex=\"0\"` so keyboard focus shows the tooltip.\n  Button props render a Button carrying it; `children` (a string or a snippet) replaces\n  `content` for a richer body\n- **open**: boolean (default: false) - Shows the tooltip without hover or focus; bindable\n- **defaultOpen**: boolean (default: false) - Initial open state when `open` is not provided\n- **onOpenChange**: (open: boolean) => void - Called whenever the tooltip becomes visible or hidden,\n  hover and focus included\n- **position**: Placement (default: 'top') - Tooltip position relative to the trigger\n  - Options: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end'\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Visual size\n- **color**: Colors (default: 'neutral') - Color theme\n- **variant**: 'solid' | 'outline' | 'soft' (default: 'solid') - Visual style matching Chip\n- **delay**: number (default: 400) - Delay in ms before showing tooltip; zero shows immediately\n- **offset**: number - Distance from the trigger in pixels\n- **class**: string - Additional CSS classes\n- **transition**: FSOProps - Custom transition configuration\n- **theme**: TooltipThemeProps - Per-instance theme overrides\n- **onAfterOpen**: () => void - Callback after the opening transition completes\n- **onAfterClose**: () => void - Callback after the closing transition completes\n\nEvery prop except `trigger`, `open`, `defaultOpen` and `onOpenChange` is also an option of the\n`tooltip()` attachment.\n\n## Examples\n\n### Button Trigger\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip\n\tcontent=\"This is helpful information\"\n\ttrigger={{ content: 'Hover me', variant: 'outline', color: 'neutral' }}\n/>\n```\n\n### Snippet Trigger\n```svelte\n<script lang=\"ts\">\n\timport type { Attachment } from 'svelte/attachments';\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n{#snippet helpTrigger(attach: Attachment<HTMLElement>)}\n\t<span class=\"underline\" {@attach attach}>What is this?</span>\n{/snippet}\n\n<Tooltip content=\"Anchored to any element you like\" trigger={helpTrigger} />\n```\n\n### Forced Open\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<!-- Useful for docs, screenshots and visual tests -->\n<Tooltip open content=\"Always visible\" trigger={{ content: 'Anchor', variant: 'outline' }} />\n```\n\n### Different Positions\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Top tooltip\" position=\"top\" trigger={{ content: 'Top' }} />\n<Tooltip content=\"Bottom tooltip\" position=\"bottom\" trigger={{ content: 'Bottom' }} />\n<Tooltip content=\"Left tooltip\" position=\"left\" trigger={{ content: 'Left' }} />\n<Tooltip content=\"Right tooltip\" position=\"right\" trigger={{ content: 'Right' }} />\n```\n\n### Different Colors\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Success!\" color=\"success\" trigger={{ content: 'Success' }} />\n<Tooltip content=\"Warning!\" color=\"warning\" trigger={{ content: 'Warning' }} />\n<Tooltip content=\"Error!\" color=\"danger\" trigger={{ content: 'Error' }} />\n```\n\n### Custom Delay\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Quick tooltip\" delay={100} trigger={{ content: 'Quick (100ms)' }} />\n<Tooltip content=\"Slow tooltip\" delay={1000} trigger={{ content: 'Slow (1000ms)' }} />\n```\n\n### Different Sizes and Variants\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Small tooltip\" size=\"small\" trigger={{ content: 'Small' }} />\n<Tooltip content=\"Large tooltip\" size=\"large\" trigger={{ content: 'Large' }} />\n<Tooltip content=\"Outlined tooltip\" variant=\"outline\" trigger={{ content: 'Outline' }} />\n<Tooltip content=\"Soft tooltip\" variant=\"soft\" trigger={{ content: 'Soft' }} />\n```\n\n### With Snippet Content\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n{#snippet richContent()}\n\t<div class=\"p-2\">\n\t\t<strong>Pro Tip</strong>\n\t\t<p class=\"text-sm\">Use Ctrl+S to save</p>\n\t</div>\n{/snippet}\n\n<Tooltip content={richContent} trigger={{ content: 'Keyboard Shortcuts' }} />\n```\n\n### With Callbacks\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip\n\tcontent=\"Tracked tooltip\"\n\tonAfterOpen={() => console.log('Tooltip opened')}\n\tonAfterClose={() => console.log('Tooltip closed')}\n\ttrigger={{ content: 'Track me' }}\n/>\n```\n\n## The tooltip() attachment\n\nUse the attachment when the element already exists in your markup \u2014 icons, table cells, list rows,\ndisabled wrappers \u2014 or inside another component's internals.\n\n```svelte\n<script lang=\"ts\">\n\timport { tooltip } from 'entasis/tooltip';\n</script>\n\n<button {@attach tooltip({ content: 'Click to submit' })}> Submit </button>\n\n<!-- On icons or any non-interactive element -->\n<span {@attach tooltip({ content: 'More information', position: 'right' })}> \u24D8 </span>\n\n<!-- Disabled elements do not fire events, so wrap them -->\n<span {@attach tooltip({ content: 'Feature coming soon' })}>\n\t<button disabled>Disabled Button</button>\n</span>\n```\n\nThe `<Tooltip>` component hands this same attachment to a snippet trigger, so the two forms are\ninterchangeable.\n\n## Accessibility\n\n- Shows on pointer hover and on keyboard focus (`focusin` / `focusout` on the trigger element), so\n  attach it to focusable elements for keyboard users\n- Dismissed on mouse leave or blur\n- Non-interactive (cannot be clicked)\n- Renders with `role=\"tooltip\"` and sets `aria-describedby` on the trigger while visible (any previous value is restored on hide)\n- Does not block content behind it\n\n## Notes\n\n- Only one tooltip shows at a time; an `open` tooltip hands the surface over when another tooltip is\n  hovered and reports that through `onOpenChange`\n- Automatically positions to stay in viewport using Floating UI\n- Uses smart delay: subsequent tooltips show instantly if within 400ms of previous\n- Brief content only (use Popover for interactive content)\n- The surface is a singleton (`TooltipHost`) rendered by `<Theme>`\n- Does not lock scroll or trap focus\n\n## Theme Customization\n\nThe Tooltip uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main tooltip container styles\n\n### Theme Type Definition\n\n```typescript\nimport type { TooltipThemeProps } from 'entasis/tooltip';\n\n// Example theme customization\nconst customTheme: TooltipThemeProps = {\n  root: {\n    base: 'inline-flex w-fit items-center rounded-full border font-medium',\n    size: {\n      small: 'h-5 px-2 text-xs',\n      normal: 'h-6 px-2.5 text-xs',\n      large: 'h-7 px-3 text-sm'\n    },\n\tcolor: {\n\t  neutral: 'bg-neutral text-neutral-contrast',\n      primary: 'bg-primary text-primary-contrast',\n      danger: 'bg-danger text-danger-contrast',\n      success: 'bg-success text-success-contrast',\n      warning: 'bg-warning text-warning-contrast',\n\t  info: 'bg-info text-info-contrast'\n\t},\n\tvariant: {\n\t  solid: 'bg-color text-color-contrast',\n\t  outline: 'border-color bg-transparent text-color-readable',\n\t  soft: 'bg-color-muted text-color-muted-readable'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**root**:\n- base: Base classes applied to all tooltips\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Controls text size and padding\n  - color: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' - Color scheme\n  - variant: 'solid' | 'outline' | 'soft' - Matches Chip's visual variants\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip\n\tcontent=\"Custom tooltip\"\n\ttheme={{ root: { base: 'rounded-lg lift-4 border-2', size: { normal: 'px-3 py-2 text-sm' } } }}\n\ttrigger={{ content: 'Hover me' }}\n/>\n```\n\n**Color Customization**:\n```svelte\n<script lang=\"ts\">\n\timport { tooltip } from 'entasis/tooltip';\n</script>\n\n<button\n\t{@attach tooltip({\n\t\tcontent: 'Success!',\n\t\tcolor: 'success',\n\t\ttheme: { root: { color: { success: 'bg-green-500 text-white lift-3' } } }\n\t})}\n>\n\tSuccess Tooltip\n</button>\n```\n\n**Global Theme Setting**:\n```svelte\n<script lang=\"ts\">\n\timport { setTooltipTheme } from 'entasis/tooltip';\n\n\tsetTooltipTheme({\n\t\troot: {\n\t\t\tbase: 'rounded-md lift-4 backdrop-blur-sm',\n\t\t\tsize: { normal: 'px-3 py-1.5 text-sm' },\n\t\t\tcolor: { neutral: 'bg-gray-900 text-white', primary: 'bg-blue-500 text-white' }\n\t\t}\n\t});\n</script>\n```\n\n## Motion\n\n- **motion** theme slot: one preset (no variants) \u2014 a short fade-and-rise, `duration: 'fast'`.\n- Resolved by the tooltip surface and handed to the underlying Popover, so it replaces the\n  popover preset.\n- Ladder: `<Theme components={{ tooltip: { motion } }}>` \u2192 `setTooltipTheme({ motion })` \u2192\n  `theme.motion` \u2192 the tooltip's `transition` option. Reduced motion collapses it to 0.\n- The tooltip surface is a singleton rendered by `<Theme>`, so a `setTooltipTheme` call\n  made *below* `<Theme>` never reaches it. Call it at or above the `<Theme>` boundary, or\n  use the `<Theme components={{ tooltip }}>` registry, which always applies.\n";
+export declare const tooltipDescription = "\n# Tooltip\n\nContextual information shown on hover or on keyboard focus (when the focus ring shows). Two forms share one surface:\n\n- `<Tooltip>` \u2014 a component with a `trigger` prop, like every other overlay.\n- `tooltip()` \u2014 the underlying attachment, for elements you already render yourself.\n\nBoth are rendered by the single tooltip surface that `<Theme>` mounts (`TooltipHost`).\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Click to submit\" trigger={{ content: 'Submit', variant: 'outline' }} />\n```\n\n## Props\n\n- **content**: string | Snippet (required) - Tooltip body\n- **trigger**: Snippet<[Attachment<HTMLElement>]> | ButtonProps & { content?: string } (required) -\n  A snippet receives the tooltip attachment and spreads it on its own element; an element the\n  browser cannot focus (a span, an icon) gets `tabindex=\"0\"` so keyboard focus shows the tooltip.\n  Button props render a Button carrying it; `children` (a string or a snippet) replaces\n  `content` for a richer body\n- **open**: boolean (default: false) - Shows the tooltip without hover or focus; bindable\n- **defaultOpen**: boolean (default: false) - Initial open state when `open` is not provided\n- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void - Called before the tooltip\n  shows or hides, whatever causes it (hover, focus, a press on the trigger, Escape, an outside press).\n  `details.reason` is `'trigger-hover'`, `'trigger-focus'`, `'trigger-press'`, `'outside-press'`,\n  `'escape-key'` or `'imperative-action'`; `details.event` and `details.trigger` say what caused it, and\n  `details.cancel()` keeps the tooltip as it was. When another tooltip takes the shared surface, the\n  one it leaves is told with a close that cannot be cancelled. A change to the `open` prop is silent\n- **position**: Placement (default: 'top') - Tooltip position relative to the trigger\n  - Options: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end'\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Visual size\n- **color**: Colors (default: 'neutral') - Color theme\n- **variant**: 'solid' | 'outline' | 'soft' (default: 'solid') - Visual style matching Chip\n- **delay**: number (default: 400) - Delay in ms before showing tooltip; zero shows immediately\n- **closeDelay**: number (default: 0) - Delay in ms between the pointer leaving the trigger (or the\n  content) and the tooltip closing; moving to another tooltip's trigger within it hands the surface\n  over without closing it. With `hoverable` content the pointer always gets at least 100 ms to reach it\n- **hoverable**: boolean (default: true) - The tooltip stays open while the pointer is over its content\n  (WCAG 1.4.13), so its text can be read or selected and its links used. `false` makes the content\n  ignore the pointer and closes the tooltip as soon as the pointer leaves the trigger\n- **closeOnClick**: boolean (default: true) - A press on the trigger (pointer, or Enter / Space) closes\n  the tooltip, and it stays closed until the pointer leaves the trigger or focus moves away. `false`\n  leaves it open\n- **disabled**: boolean (default: false) - Turns the tooltip off: hover and focus do not open it, an\n  open one closes, and the trigger loses `aria-describedby`. Read live\n- **offset**: number - Distance from the trigger in pixels\n- **class**: string - Additional CSS classes\n- **transition**: FSOProps - Custom transition configuration\n- **theme**: TooltipThemeProps - Per-instance theme overrides\n- **onAfterOpen**: () => void - Callback after the opening transition completes\n- **onAfterClose**: () => void - Callback after the closing transition completes\n\nEvery prop except `trigger`, `open` and `defaultOpen` is also an option of the `tooltip()`\nattachment, `onOpenChange` included.\n\n## Examples\n\n### Button Trigger\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip\n\tcontent=\"This is helpful information\"\n\ttrigger={{ content: 'Hover me', variant: 'outline', color: 'neutral' }}\n/>\n```\n\n### Snippet Trigger\n```svelte\n<script lang=\"ts\">\n\timport type { Attachment } from 'svelte/attachments';\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n{#snippet helpTrigger(attach: Attachment<HTMLElement>)}\n\t<span class=\"underline\" {@attach attach}>What is this?</span>\n{/snippet}\n\n<Tooltip content=\"Anchored to any element you like\" trigger={helpTrigger} />\n```\n\n### Forced Open\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<!-- Useful for docs, screenshots and visual tests -->\n<Tooltip open content=\"Always visible\" trigger={{ content: 'Anchor', variant: 'outline' }} />\n```\n\n### Different Positions\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Top tooltip\" position=\"top\" trigger={{ content: 'Top' }} />\n<Tooltip content=\"Bottom tooltip\" position=\"bottom\" trigger={{ content: 'Bottom' }} />\n<Tooltip content=\"Left tooltip\" position=\"left\" trigger={{ content: 'Left' }} />\n<Tooltip content=\"Right tooltip\" position=\"right\" trigger={{ content: 'Right' }} />\n```\n\n### Different Colors\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Success!\" color=\"success\" trigger={{ content: 'Success' }} />\n<Tooltip content=\"Warning!\" color=\"warning\" trigger={{ content: 'Warning' }} />\n<Tooltip content=\"Error!\" color=\"danger\" trigger={{ content: 'Error' }} />\n```\n\n### Custom Delay\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Quick tooltip\" delay={100} trigger={{ content: 'Quick (100ms)' }} />\n<Tooltip content=\"Slow tooltip\" delay={1000} trigger={{ content: 'Slow (1000ms)' }} />\n```\n\n### Different Sizes and Variants\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip content=\"Small tooltip\" size=\"small\" trigger={{ content: 'Small' }} />\n<Tooltip content=\"Large tooltip\" size=\"large\" trigger={{ content: 'Large' }} />\n<Tooltip content=\"Outlined tooltip\" variant=\"outline\" trigger={{ content: 'Outline' }} />\n<Tooltip content=\"Soft tooltip\" variant=\"soft\" trigger={{ content: 'Soft' }} />\n```\n\n### With Snippet Content\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n{#snippet richContent()}\n\t<div class=\"p-2\">\n\t\t<strong>Pro Tip</strong>\n\t\t<p class=\"text-sm\">Use Ctrl+S to save</p>\n\t</div>\n{/snippet}\n\n<Tooltip content={richContent} trigger={{ content: 'Keyboard Shortcuts' }} />\n```\n\n### Hoverable Content\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n{#snippet help()}\n\tRead the <a href=\"/docs/shortcuts\">shortcut list</a>.\n{/snippet}\n\n<!-- The pointer can move onto the tooltip and use the link -->\n<Tooltip content={help} trigger={{ content: 'Shortcuts' }} />\n\n<!-- The pointer passes through, and the tooltip closes on leaving the trigger -->\n<Tooltip hoverable={false} content=\"Not interactive\" trigger={{ content: 'Hint' }} />\n```\n\n### Press and Disabled\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n\n\tlet busy = $state(false);\n</script>\n\n<!-- Closes when the trigger is pressed, and stays closed until the pointer leaves -->\n<Tooltip content=\"Save changes\" trigger={{ content: 'Save' }} />\n\n<!-- Stays open after a press -->\n<Tooltip closeOnClick={false} content=\"Save changes\" trigger={{ content: 'Save' }} />\n\n<!-- No tooltip while busy -->\n<Tooltip disabled={busy} content=\"Save changes\" trigger={{ content: 'Save' }} />\n```\n\n### With Callbacks\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip\n\tcontent=\"Tracked tooltip\"\n\tonOpenChange={(open, details) => console.log(open, details.reason)}\n\tonAfterOpen={() => console.log('Tooltip opened')}\n\tonAfterClose={() => console.log('Tooltip closed')}\n\ttrigger={{ content: 'Track me' }}\n/>\n```\n\n## The tooltip() attachment\n\nUse the attachment when the element already exists in your markup \u2014 icons, table cells, list rows,\ndisabled wrappers \u2014 or inside another component's internals.\n\n```svelte\n<script lang=\"ts\">\n\timport { tooltip } from 'entasis/tooltip';\n</script>\n\n<button {@attach tooltip({ content: 'Click to submit' })}> Submit </button>\n\n<!-- On icons or any non-interactive element -->\n<span {@attach tooltip({ content: 'More information', position: 'right' })}> \u24D8 </span>\n\n<!-- Disabled elements do not fire events, so wrap them -->\n<span {@attach tooltip({ content: 'Feature coming soon' })}>\n\t<button disabled>Disabled Button</button>\n</span>\n```\n\nThe `<Tooltip>` component hands this same attachment to a snippet trigger, so the two forms are\ninterchangeable.\n\n## Styling hooks\n\nThe surface (the `role=\"tooltip\"` element that `class` and the theme style) and the trigger carry state attributes.\n\nAttributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.\n\n**Data attributes**\n- `data-open`: On the surface: present while the tooltip shows.\n- `data-closed`: On the surface: present while its exit transition plays.\n- `data-entering`: On the surface: present while the enter transition plays.\n- `data-exiting`: On the surface: present while the exit transition plays.\n- `data-side`: On the surface: the side of the trigger it sits on after flipping, `top`, `right`, `bottom` or `left`.\n- `data-align`: On the surface: `start`, `center` or `end`, how it lines up with the trigger.\n- `data-anchor-hidden`: On the surface: present while the trigger is scrolled out of view.\n- `data-instant`: On the surface: present while it moved straight from one trigger to another, which plays no transition.\n- `data-color`: On the surface: the resolved `color`.\n- `data-size`: On the surface: the resolved `size`.\n- `data-variant`: On the surface: the resolved `variant`.\n- `data-popup-open`: On the trigger: present while its tooltip shows.\n- `data-popup-side`: On the trigger: the surface's `data-side` while it is placed.\n\n**CSS variables**\n- `--available-width`: The width in px the surface can take before it reaches the viewport edges, minus 20px.\n- `--available-height`: The room in px between the trigger and the viewport edge on the surface's side, minus 20px.\n- `--anchor-width`: The trigger's width in px, snapped to the device pixel grid.\n- `--anchor-height`: The trigger's height in px, snapped to the device pixel grid.\n- `--transform-origin`: The surface corner facing the trigger, the point it scales from.\n\nThe typed maps `tooltipDataAttributes` and `tooltipCssVariables` (from `entasis/tooltip`) list each name with its meaning.\n\n```svelte\n<script>\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<!-- Nudge the surface away from the side it sits on while it enters -->\n<Tooltip content=\"Saved\" class=\"data-[side=top]:data-entering:-translate-y-0.5\" trigger={{ content: 'Save' }} />\n```\n\n## Accessibility\n\n- Shows on pointer hover and on keyboard focus (`focusin` / `focusout` on the trigger element), so\n  attach it to focusable elements for keyboard users\n- Focus opens it only when the browser shows a focus ring: focus from a mouse press or a tap, focus a\n  closing dialog or popover hands back, and focus that returns with the window do not\n- A touch tap is not a hover: the compatibility mouse events a tap fires never show the tooltip\n- The content can be hovered (WCAG 1.4.13: hoverable, dismissible, persistent): the pointer may move\n  onto the tooltip, and Escape dismisses it\n- A trigger that appears under a resting pointer (a dialog closing over it, a list scrolled by the\n  wheel) shows its tooltip once the pointer moves, not on arrival\n- Dismissed on mouse leave or blur\n- Brief, read-only content; use `hoverable={false}` for content that should never take the pointer\n- Renders with `role=\"tooltip\"` and sets `aria-describedby` on the trigger while visible (any previous value is restored on hide)\n- Does not block content behind it when `hoverable={false}`; the default hoverable content captures the pointer so it can be read\n\n## Notes\n\n- Only one tooltip shows at a time; an `open` tooltip hands the surface over when another tooltip is\n  hovered and reports that through `onOpenChange`. Moving between triggers keeps the surface: it\n  stays in place, resizes to the new content and carries `data-instant`; the tooltip it leaves gets\n  `onAfterClose` and the new one `onAfterOpen`\n- Automatically positions to stay in viewport using Floating UI\n- Uses smart delay: right after a tooltip, a hover card or a hover-opened popover was open\n  (within 400ms of it closing, or while a hover card or popover is still open), the next tooltip\n  shows instantly. A tooltip inside an open hover card keeps its delay.\n- Brief content only: text and a link are fine, but use Popover for controls and forms\n- The surface is a singleton (`TooltipHost`) rendered by `<Theme>`\n- Does not lock scroll or trap focus\n\n## Theme Customization\n\nThe Tooltip uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main tooltip container styles\n\n### Theme Type Definition\n\n```typescript\nimport type { TooltipThemeProps } from 'entasis/tooltip';\n\n// Example theme customization\nconst customTheme: TooltipThemeProps = {\n  root: {\n    base: 'inline-flex w-fit items-center rounded-full border font-medium',\n    size: {\n      small: 'h-5 px-2 text-xs',\n      normal: 'h-6 px-2.5 text-xs',\n      large: 'h-7 px-3 text-sm'\n    },\n\tcolor: {\n\t  neutral: 'bg-neutral text-neutral-contrast',\n      primary: 'bg-primary text-primary-contrast',\n      danger: 'bg-danger text-danger-contrast',\n      success: 'bg-success text-success-contrast',\n      warning: 'bg-warning text-warning-contrast',\n\t  info: 'bg-info text-info-contrast'\n\t},\n\tvariant: {\n\t  solid: 'bg-color text-color-contrast',\n\t  outline: 'border-color bg-transparent text-color-readable',\n\t  soft: 'bg-color-muted text-color-muted-readable'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**root**:\n- base: Base classes applied to all tooltips\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Controls text size and padding\n  - color: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' - Color scheme\n  - variant: 'solid' | 'outline' | 'soft' - Matches Chip's visual variants\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<script lang=\"ts\">\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<Tooltip\n\tcontent=\"Custom tooltip\"\n\ttheme={{ root: { base: 'rounded-lg lift-4 border-2', size: { normal: 'px-3 py-2 text-sm' } } }}\n\ttrigger={{ content: 'Hover me' }}\n/>\n```\n\n**Color Customization**:\n```svelte\n<script lang=\"ts\">\n\timport { tooltip } from 'entasis/tooltip';\n</script>\n\n<button\n\t{@attach tooltip({\n\t\tcontent: 'Success!',\n\t\tcolor: 'success',\n\t\ttheme: { root: { color: { success: 'bg-green-500 text-white lift-3' } } }\n\t})}\n>\n\tSuccess Tooltip\n</button>\n```\n\n**Global Theme Setting**:\n```svelte\n<script lang=\"ts\">\n\timport { setTooltipTheme } from 'entasis/tooltip';\n\n\tsetTooltipTheme({\n\t\troot: {\n\t\t\tbase: 'rounded-md lift-4 backdrop-blur-sm',\n\t\t\tsize: { normal: 'px-3 py-1.5 text-sm' },\n\t\t\tcolor: { neutral: 'bg-gray-900 text-white', primary: 'bg-blue-500 text-white' }\n\t\t}\n\t});\n</script>\n```\n\n## Motion\n\n- **motion** theme slot: one preset (no variants) \u2014 a short fade-and-rise, `duration: 'fast'`.\n- Resolved by the tooltip surface and handed to the underlying Popover, so it replaces the\n  popover preset.\n- Ladder: `<Theme components={{ tooltip: { motion } }}>` \u2192 `setTooltipTheme({ motion })` \u2192\n  `theme.motion` \u2192 the tooltip's `transition` option. Reduced motion collapses it to 0.\n- The tooltip surface is a singleton rendered by `<Theme>`, so a `setTooltipTheme` call\n  made *below* `<Theme>` never reaches it. Call it at or above the `<Theme>` boundary, or\n  use the `<Theme components={{ tooltip }}>` registry, which always applies.\n";

package/dist/components/Tooltip/tooltip.mcp.js

@@ -1,7 +1,7 @@
 export const tooltipDescription = `
 # Tooltip
 
-Contextual information shown on hover or keyboard focus. Two forms share one surface:
+Contextual information shown on hover or on keyboard focus (when the focus ring shows). Two forms share one surface:
 
 - \`<Tooltip>\` — a component with a \`trigger\` prop, like every other overlay.
 - \`tooltip()\` — the underlying attachment, for elements you already render yourself.
@@ -28,14 +28,29 @@ Both are rendered by the single tooltip surface that \`<Theme>\` mounts (\`Toolt
   \`content\` for a richer body
 - **open**: boolean (default: false) - Shows the tooltip without hover or focus; bindable
 - **defaultOpen**: boolean (default: false) - Initial open state when \`open\` is not provided
-- **onOpenChange**: (open: boolean) => void - Called whenever the tooltip becomes visible or hidden,
-  hover and focus included
+- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void - Called before the tooltip
+  shows or hides, whatever causes it (hover, focus, a press on the trigger, Escape, an outside press).
+  \`details.reason\` is \`'trigger-hover'\`, \`'trigger-focus'\`, \`'trigger-press'\`, \`'outside-press'\`,
+  \`'escape-key'\` or \`'imperative-action'\`; \`details.event\` and \`details.trigger\` say what caused it, and
+  \`details.cancel()\` keeps the tooltip as it was. When another tooltip takes the shared surface, the
+  one it leaves is told with a close that cannot be cancelled. A change to the \`open\` prop is silent
 - **position**: Placement (default: 'top') - Tooltip position relative to the trigger
   - Options: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end'
 - **size**: 'small' | 'normal' | 'large' (default: 'normal') - Visual size
 - **color**: Colors (default: 'neutral') - Color theme
 - **variant**: 'solid' | 'outline' | 'soft' (default: 'solid') - Visual style matching Chip
 - **delay**: number (default: 400) - Delay in ms before showing tooltip; zero shows immediately
+- **closeDelay**: number (default: 0) - Delay in ms between the pointer leaving the trigger (or the
+  content) and the tooltip closing; moving to another tooltip's trigger within it hands the surface
+  over without closing it. With \`hoverable\` content the pointer always gets at least 100 ms to reach it
+- **hoverable**: boolean (default: true) - The tooltip stays open while the pointer is over its content
+  (WCAG 1.4.13), so its text can be read or selected and its links used. \`false\` makes the content
+  ignore the pointer and closes the tooltip as soon as the pointer leaves the trigger
+- **closeOnClick**: boolean (default: true) - A press on the trigger (pointer, or Enter / Space) closes
+  the tooltip, and it stays closed until the pointer leaves the trigger or focus moves away. \`false\`
+  leaves it open
+- **disabled**: boolean (default: false) - Turns the tooltip off: hover and focus do not open it, an
+  open one closes, and the trigger loses \`aria-describedby\`. Read live
 - **offset**: number - Distance from the trigger in pixels
 - **class**: string - Additional CSS classes
 - **transition**: FSOProps - Custom transition configuration
@@ -43,8 +58,8 @@ Both are rendered by the single tooltip surface that \`<Theme>\` mounts (\`Toolt
 - **onAfterOpen**: () => void - Callback after the opening transition completes
 - **onAfterClose**: () => void - Callback after the closing transition completes
 
-Every prop except \`trigger\`, \`open\`, \`defaultOpen\` and \`onOpenChange\` is also an option of the
-\`tooltip()\` attachment.
+Every prop except \`trigger\`, \`open\` and \`defaultOpen\` is also an option of the \`tooltip()\`
+attachment, \`onOpenChange\` included.
 
 ## Examples
 
@@ -145,6 +160,41 @@ Every prop except \`trigger\`, \`open\`, \`defaultOpen\` and \`onOpenChange\` is
 <Tooltip content={richContent} trigger={{ content: 'Keyboard Shortcuts' }} />
 \`\`\`
 
+### Hoverable Content
+\`\`\`svelte
+<script lang="ts">
+	import { Tooltip } from './index.ts';
+</script>
+
+{#snippet help()}
+	Read the <a href="/docs/shortcuts">shortcut list</a>.
+{/snippet}
+
+<!-- The pointer can move onto the tooltip and use the link -->
+<Tooltip content={help} trigger={{ content: 'Shortcuts' }} />
+
+<!-- The pointer passes through, and the tooltip closes on leaving the trigger -->
+<Tooltip hoverable={false} content="Not interactive" trigger={{ content: 'Hint' }} />
+\`\`\`
+
+### Press and Disabled
+\`\`\`svelte
+<script lang="ts">
+	import { Tooltip } from './index.ts';
+
+	let busy = $state(false);
+</script>
+
+<!-- Closes when the trigger is pressed, and stays closed until the pointer leaves -->
+<Tooltip content="Save changes" trigger={{ content: 'Save' }} />
+
+<!-- Stays open after a press -->
+<Tooltip closeOnClick={false} content="Save changes" trigger={{ content: 'Save' }} />
+
+<!-- No tooltip while busy -->
+<Tooltip disabled={busy} content="Save changes" trigger={{ content: 'Save' }} />
+\`\`\`
+
 ### With Callbacks
 \`\`\`svelte
 <script lang="ts">
@@ -153,6 +203,7 @@ Every prop except \`trigger\`, \`open\`, \`defaultOpen\` and \`onOpenChange\` is
 
 <Tooltip
 	content="Tracked tooltip"
+	onOpenChange={(open, details) => console.log(open, details.reason)}
 	onAfterOpen={() => console.log('Tooltip opened')}
 	onAfterClose={() => console.log('Tooltip closed')}
 	trigger={{ content: 'Track me' }}
@@ -183,22 +234,72 @@ disabled wrappers — or inside another component's internals.
 The \`<Tooltip>\` component hands this same attachment to a snippet trigger, so the two forms are
 interchangeable.
 
+## Styling hooks
+
+The surface (the \`role="tooltip"\` element that \`class\` and the theme style) and the trigger carry state attributes.
+
+Attributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.
+
+**Data attributes**
+- \`data-open\`: On the surface: present while the tooltip shows.
+- \`data-closed\`: On the surface: present while its exit transition plays.
+- \`data-entering\`: On the surface: present while the enter transition plays.
+- \`data-exiting\`: On the surface: present while the exit transition plays.
+- \`data-side\`: On the surface: the side of the trigger it sits on after flipping, \`top\`, \`right\`, \`bottom\` or \`left\`.
+- \`data-align\`: On the surface: \`start\`, \`center\` or \`end\`, how it lines up with the trigger.
+- \`data-anchor-hidden\`: On the surface: present while the trigger is scrolled out of view.
+- \`data-instant\`: On the surface: present while it moved straight from one trigger to another, which plays no transition.
+- \`data-color\`: On the surface: the resolved \`color\`.
+- \`data-size\`: On the surface: the resolved \`size\`.
+- \`data-variant\`: On the surface: the resolved \`variant\`.
+- \`data-popup-open\`: On the trigger: present while its tooltip shows.
+- \`data-popup-side\`: On the trigger: the surface's \`data-side\` while it is placed.
+
+**CSS variables**
+- \`--available-width\`: The width in px the surface can take before it reaches the viewport edges, minus 20px.
+- \`--available-height\`: The room in px between the trigger and the viewport edge on the surface's side, minus 20px.
+- \`--anchor-width\`: The trigger's width in px, snapped to the device pixel grid.
+- \`--anchor-height\`: The trigger's height in px, snapped to the device pixel grid.
+- \`--transform-origin\`: The surface corner facing the trigger, the point it scales from.
+
+The typed maps \`tooltipDataAttributes\` and \`tooltipCssVariables\` (from \`entasis/tooltip\`) list each name with its meaning.
+
+\`\`\`svelte
+<script>
+	import { Tooltip } from './index.ts';
+</script>
+
+<!-- Nudge the surface away from the side it sits on while it enters -->
+<Tooltip content="Saved" class="data-[side=top]:data-entering:-translate-y-0.5" trigger={{ content: 'Save' }} />
+\`\`\`
+
 ## Accessibility
 
 - Shows on pointer hover and on keyboard focus (\`focusin\` / \`focusout\` on the trigger element), so
   attach it to focusable elements for keyboard users
+- Focus opens it only when the browser shows a focus ring: focus from a mouse press or a tap, focus a
+  closing dialog or popover hands back, and focus that returns with the window do not
+- A touch tap is not a hover: the compatibility mouse events a tap fires never show the tooltip
+- The content can be hovered (WCAG 1.4.13: hoverable, dismissible, persistent): the pointer may move
+  onto the tooltip, and Escape dismisses it
+- A trigger that appears under a resting pointer (a dialog closing over it, a list scrolled by the
+  wheel) shows its tooltip once the pointer moves, not on arrival
 - Dismissed on mouse leave or blur
-- Non-interactive (cannot be clicked)
+- Brief, read-only content; use \`hoverable={false}\` for content that should never take the pointer
 - Renders with \`role="tooltip"\` and sets \`aria-describedby\` on the trigger while visible (any previous value is restored on hide)
-- Does not block content behind it
+- Does not block content behind it when \`hoverable={false}\`; the default hoverable content captures the pointer so it can be read
 
 ## Notes
 
 - Only one tooltip shows at a time; an \`open\` tooltip hands the surface over when another tooltip is
-  hovered and reports that through \`onOpenChange\`
+  hovered and reports that through \`onOpenChange\`. Moving between triggers keeps the surface: it
+  stays in place, resizes to the new content and carries \`data-instant\`; the tooltip it leaves gets
+  \`onAfterClose\` and the new one \`onAfterOpen\`
 - Automatically positions to stay in viewport using Floating UI
-- Uses smart delay: subsequent tooltips show instantly if within 400ms of previous
-- Brief content only (use Popover for interactive content)
+- Uses smart delay: right after a tooltip, a hover card or a hover-opened popover was open
+  (within 400ms of it closing, or while a hover card or popover is still open), the next tooltip
+  shows instantly. A tooltip inside an open hover card keeps its delay.
+- Brief content only: text and a link are fine, but use Popover for controls and forms
 - The surface is a singleton (\`TooltipHost\`) rendered by \`<Theme>\`
 - Does not lock scroll or trap focus