@astryxdesign/core 0.7.7-canary.550ff21 → 0.7.7-canary.58c5b8a

package/src/Tooltip/Tooltip.doc.mjs

@@ -24,16 +24,29 @@ export const docs = {
   playground: {
     defaults: {
       content: 'Helpful tooltip text',
-      children: {__element: 'Button', props: {label: 'Hover me', variant: 'secondary'}},
+      children: {
+        __element: 'Button',
+        props: {label: 'Hover me', variant: 'secondary'},
+      },
     },
   },
-  keywords: ["tooltip","hint","infotip","title","hover","flyout","balloon","helpertext"],
+  keywords: [
+    'tooltip',
+    'hint',
+    'infotip',
+    'title',
+    'hover',
+    'flyout',
+    'balloon',
+    'helpertext',
+  ],
   components: [
     {
       name: 'Tooltip',
       displayName: 'Tooltip',
       description:
-        'Component wrapper for tooltip display triggered on hover or focus.',      props: [
+        'Component wrapper for tooltip display triggered on hover or focus.',
+      props: [
         {
           name: 'children',
           type: 'ReactNode',
@@ -48,18 +61,26 @@ export const docs = {
           name: 'content',
           type: 'ReactNode',
           description: 'Tooltip content, typically short text.',
-          slotElements: [{__element: 'Text', props: {type: 'body'}, children: 'Content text'}],
+          slotElements: [
+            {
+              __element: 'Text',
+              props: {type: 'body'},
+              children: 'Content text',
+            },
+          ],
         },
         {
           name: 'placement',
           type: "'above' | 'below' | 'start' | 'end'",
-          description: "Position relative to the anchor element. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+          description:
+            "Position relative to the anchor element. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
           default: "'above'",
         },
         {
           name: 'alignment',
           type: "'start' | 'center' | 'end'",
-          description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+          description:
+            "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
           default: "'center'",
         },
         {
@@ -84,7 +105,7 @@ export const docs = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.',
+            'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens, for a button whose only job is to reveal the tooltip; for an info icon, use InfoTip. none never opens on touch.',
           default: "'auto'",
         },
         {
@@ -108,7 +129,8 @@ export const docs = {
         {
           name: 'isDefaultOpen',
           type: 'boolean',
-          description: 'Whether the tooltip should be shown on mount. Still dismissible.',
+          description:
+            'Whether the tooltip should be shown on mount. Still dismissible.',
         },
         {
           name: 'isOpen',
@@ -119,20 +141,38 @@ export const docs = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-tooltip'},
-    ],
+    targets: [{className: 'astryx-tooltip'}],
   },
   usage: {
     anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [
-      {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
-      {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
-      {guidance: true, description: 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip, such as an info icon: touch has no hover, and auto keeps the tap for triggers that perform an action.'},
-      {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
-      {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
+      {
+        guidance: true,
+        description:
+          'Keep tooltip content concise: aim for under 140 characters of plain text.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a tooltip to icon-only buttons and controls that lack a visible label.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip: touch has no hover, and auto keeps the tap for triggers that perform an action. For an info icon, use InfoTip, which also pins its help on a press.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use tooltips for essential information that users must see to complete a task.',
+      },
     ],
   },
 };
@@ -145,8 +185,7 @@ export const docsZh = {
     {
       name: 'Tooltip',
       displayName: 'Tooltip',
-      description:
-        '工具提示显示的组件包装器，通过悬停或聚焦触发。',
+      description: '工具提示显示的组件包装器，通过悬停或聚焦触发。',
       props: [
         {
           name: 'children',
@@ -166,13 +205,15 @@ export const docsZh = {
         {
           name: 'placement',
           type: "'above' | 'below' | 'start' | 'end'",
-          description: '相对于锚点元素的位置。逻辑值：start/end 根据弹出层自身继承的方向解析（RTL 镜像）。',
+          description:
+            '相对于锚点元素的位置。逻辑值：start/end 根据弹出层自身继承的方向解析（RTL 镜像）。',
           default: "'above'",
         },
         {
           name: 'alignment',
           type: "'start' | 'center' | 'end'",
-          description: '沿放置轴的对齐方式。逻辑值：start/end 根据弹出层自身继承的方向解析（RTL 镜像）。',
+          description:
+            '沿放置轴的对齐方式。逻辑值：start/end 根据弹出层自身继承的方向解析（RTL 镜像）。',
           default: "'center'",
         },
         {
@@ -197,7 +238,7 @@ export const docsZh = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none：触摸永不打开。',
+            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开，适用于唯一作用是显示工具提示的按钮；信息图标请使用 InfoTip。none：触摸永不打开。',
           default: "'auto'",
         },
         {
@@ -227,37 +268,76 @@ export const docsZh = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-tooltip'},
-    ],
+    targets: [{className: 'astryx-tooltip'}],
   },
   usage: {
     anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [
-      {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
-      {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
-      {guidance: true, description: 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip, such as an info icon: touch has no hover, and auto keeps the tap for triggers that perform an action.'},
-      {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
-      {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
+      {
+        guidance: true,
+        description:
+          'Keep tooltip content concise: aim for under 140 characters of plain text.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a tooltip to icon-only buttons and controls that lack a visible label.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip: touch has no hover, and auto keeps the tap for triggers that perform an action. For an info icon, use InfoTip, which also pins its help on a press.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use tooltips for essential information that users must see to complete a task.',
+      },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Hover/focus triggered tooltip for displaying short, non-interactive text anchored to trigger element.',
+  description:
+    'Hover/focus triggered tooltip for displaying short, non-interactive text anchored to trigger element.',
   usage: {
     anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [
-      {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
-      {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
-      {guidance: true, description: 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip, such as an info icon: touch has no hover, and auto keeps the tap for triggers that perform an action.'},
-      {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
-      {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
+      {
+        guidance: true,
+        description:
+          'Keep tooltip content concise: aim for under 140 characters of plain text.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a tooltip to icon-only buttons and controls that lack a visible label.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip: touch has no hover, and auto keeps the tap for triggers that perform an action. For an info icon, use InfoTip, which also pins its help on a press.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use tooltips for essential information that users must see to complete a task.',
+      },
     ],
   },
   components: [
@@ -269,14 +349,18 @@ export const docsDense = {
         children: 'Trigger element(s) that activate tooltip.',
         anchorRef: 'External anchor ref for sibling mode.',
         content: 'Tooltip content, typically short text.',
-        placement: 'Position relative to anchor. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
-        alignment: 'Alignment along placement axis. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+        placement:
+          "Position relative to anchor. Logical: start/end follow the popover's inherited direction (RTL mirrors).",
+        alignment:
+          "Alignment along placement axis. Logical: start/end follow the popover's inherited direction (RTL mirrors).",
         delay: 'Show delay in ms.',
         hideDelay: 'Hide delay in ms.',
         focusTrigger: 'Controls when focus events trigger tooltip.',
-        touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens (info icon rendered as a button); none = never on touch.',
+        touchTrigger:
+          'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens (a button whose only job is the tooltip; for an info icon use InfoTip); none = never on touch.',
         isEnabled: 'Enables/disables tooltip triggers.',
-        onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',
+        onOpenChange:
+          'Callback when visibility changes; true=shown, false=hidden.',
         hasHoverIndication: 'Dashed underline on trigger element.',
         isDefaultOpen: 'Show tooltip on mount. Still dismissible.',
       },

package/src/Tooltip/Tooltip.tsx

@@ -5,7 +5,8 @@
 /**
  * @file Tooltip.tsx
  * @input Uses React, useTooltip hook
- * @output Exports Tooltip component for hover/focus triggered tooltips
+ * @output Exports Tooltip component for hover/focus triggered tooltips, and the
+ *   module-only TooltipWithTriggerBehavior that InfoTip's press-to-pin uses
  * @position Layer component; uses display:contents wrapper to avoid cloneElement
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -23,10 +24,14 @@ import React, {
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {
-  useTooltip,
+  useTooltipWithTriggerBehavior,
   type TooltipFocusTrigger,
   type TooltipTouchTrigger,
 } from './useTooltip';
+import {
+  stopPressPinClick,
+  type LayerTriggerBehavior,
+} from '../Layer/usePressPin';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {colorVars} from '../theme/tokens.stylex';
 
@@ -109,9 +114,7 @@ export interface TooltipProps {
    * - `auto`: tap opens the tooltip, unless the trigger performs an action of
    *   its own (a button, a link, a form control) — that tap belongs to the
    *   control, and a hint about a control the user just operated is noise
-   * - `tap`: tap always opens the tooltip. This is what an info icon rendered
-   *   as a button wants: it looks like an action to the DOM, but revealing the
-   *   tooltip is the only thing it does
+   * - `tap`: tap always opens the tooltip, even on a trigger that acts
    * - `none`: touch never opens the tooltip
    *
    * @default 'auto'
@@ -191,7 +194,32 @@ function mergeIds(...ids: (string | undefined | null)[]): string | undefined {
  * </Tooltip>
  * ```
  */
-export function Tooltip({
+export function Tooltip(props: TooltipProps): ReactElement {
+  // The option is fixed to `adaptive`, so a spread object that carries it at
+  // runtime cannot reach the press-to-pin path.
+  return <TooltipWithTriggerBehavior {...props} triggerBehavior="adaptive" />;
+}
+
+/**
+ * Module-only props for `TooltipWithTriggerBehavior`. Not exported from the
+ * package.
+ */
+export interface TooltipWithTriggerBehaviorProps extends TooltipProps {
+  /**
+   * How the trigger opens the tooltip. `toggle` pins it on a click, a tap,
+   * Enter, or Space on a button trigger, and stops that press at the trigger
+   * (see `useTooltipWithTriggerBehavior`). InfoTip uses it.
+   *
+   * @default 'adaptive'
+   */
+  triggerBehavior?: LayerTriggerBehavior;
+}
+
+/**
+ * `Tooltip` with a trigger behavior. Module-only: InfoTip's press-to-pin goes
+ * through it, and the package does not export it.
+ */
+export function TooltipWithTriggerBehavior({
   children,
   anchorRef,
   content,
@@ -201,12 +229,13 @@ export function Tooltip({
   hideDelay = 0,
   focusTrigger = 'auto',
   touchTrigger = 'auto',
+  triggerBehavior = 'adaptive',
   isEnabled = true,
   onOpenChange,
   hasHoverIndication = 'auto',
   isOpen,
   isDefaultOpen,
-}: TooltipProps): ReactElement {
+}: TooltipWithTriggerBehaviorProps): ReactElement {
   const wrapperRef = useRef<HTMLDivElement>(null);
   const textOnly = children != null ? isTextOnly(children) : false;
 
@@ -223,13 +252,14 @@ export function Tooltip({
   }, [onOpenChange]);
 
   // Use the hook for all tooltip behavior
-  const tooltip = useTooltip({
+  const tooltip = useTooltipWithTriggerBehavior({
     placement,
     alignment,
     delay,
     hideDelay,
     focusTrigger,
     touchTrigger,
+    triggerBehavior,
     isEnabled,
     isOpen,
     isDefaultOpen,
@@ -343,6 +373,7 @@ export function Tooltip({
           ref={tooltip.ref}
           tabIndex={0}
           aria-describedby={tooltip.describedBy}
+          onClick={stopPressPinClick}
           {...stylex.props(
             styles.wrapperInline,
             showHoverIndication && styles.hoverIndication,
@@ -357,7 +388,10 @@ export function Tooltip({
   // For element children: use display:contents, ref on first child
   return (
     <>
-      <div ref={wrapperRef} {...stylex.props(styles.wrapperContents)}>
+      <div
+        ref={wrapperRef}
+        onClick={stopPressPinClick}
+        {...stylex.props(styles.wrapperContents)}>
         {children}
       </div>
       {tooltip.renderTooltip(content)}

package/src/Tooltip/useTooltip.doc.mjs

@@ -7,32 +7,146 @@ export const docs = {
   group: 'Tooltip',
   keywords: ['tooltip', 'hint', 'label', 'hover', 'info', 'title', 'floating'],
   params: [
-    {name: 'placement', type: "'above' | 'below' | 'start' | 'end'", description: "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'above'"},
-    {name: 'alignment', type: "'start' | 'center' | 'end'", description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'center'"},
-    {name: 'delay', type: 'number', description: 'Delay before showing on hover, in milliseconds.', default: '200'},
-    {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '0'},
-    {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the tooltip. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.', default: "'auto'"},
-    {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens (an info icon rendered as a button); none never opens on touch.', default: "'auto'"},
-    {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
-    {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
-    {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the tooltip should be shown on mount.', default: 'false'},
-    {name: 'onShow', type: '() => void', description: 'Callback fired when the tooltip becomes visible.'},
-    {name: 'onHide', type: '() => void', description: 'Callback fired when the tooltip is hidden.'},
+    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description:
+        "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+      default: "'above'",
+    },
+    {
+      name: 'alignment',
+      type: "'start' | 'center' | 'end'",
+      description:
+        "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+      default: "'center'",
+    },
+    {
+      name: 'delay',
+      type: 'number',
+      description: 'Delay before showing on hover, in milliseconds.',
+      default: '200',
+    },
+    {
+      name: 'hideDelay',
+      type: 'number',
+      description:
+        'Delay before hiding after mouse or focus leaves, in milliseconds.',
+      default: '0',
+    },
+    {
+      name: 'focusTrigger',
+      type: "'auto' | 'always' | 'never'",
+      description:
+        'When focus should open the tooltip. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.',
+      default: "'auto'",
+    },
+    {
+      name: 'touchTrigger',
+      type: "'auto' | 'tap' | 'none'",
+      description:
+        'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens (a button whose only job is revealing the tooltip); none never opens on touch.',
+      default: "'auto'",
+    },
+    {
+      name: 'isEnabled',
+      type: 'boolean',
+      description: 'Whether hover and focus triggers are enabled.',
+      default: 'true',
+    },
+    {
+      name: 'isOpen',
+      type: 'boolean',
+      description:
+        'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.',
+    },
+    {
+      name: 'isDefaultOpen',
+      type: 'boolean',
+      description: 'Whether the tooltip should be shown on mount.',
+      default: 'false',
+    },
+    {
+      name: 'onShow',
+      type: '() => void',
+      description: 'Callback fired when the tooltip becomes visible.',
+    },
+    {
+      name: 'onHide',
+      type: '() => void',
+      description: 'Callback fired when the tooltip is hidden.',
+    },
   ],
   returns: [
-    {name: 'ref', type: 'RefCallback<HTMLElement>', description: 'Combined ref that sets both position and interaction on the same trigger element.'},
-    {name: 'positionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the positioning anchor element.'},
-    {name: 'interactionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the hover/focus interaction element.'},
-    {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
-    {name: 'describedBy', type: 'string', description: 'ID to compose into aria-describedby on the trigger.'},
-    {name: 'renderTooltip', type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode", description: 'Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment.'},
+    {
+      name: 'ref',
+      type: 'RefCallback<HTMLElement>',
+      description:
+        'Combined ref that sets both position and interaction on the same trigger element.',
+    },
+    {
+      name: 'positionRef',
+      type: 'RefCallback<HTMLElement>',
+      description: 'Ref for the positioning anchor element.',
+    },
+    {
+      name: 'interactionRef',
+      type: 'RefCallback<HTMLElement>',
+      description: 'Ref for the hover/focus interaction element.',
+    },
+    {
+      name: 'anchorId',
+      type: 'string',
+      description: 'CSS anchor name for advanced positioning cases.',
+    },
+    {
+      name: 'describedBy',
+      type: 'string',
+      description: 'ID to compose into aria-describedby on the trigger.',
+    },
+    {
+      name: 'renderTooltip',
+      type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
+      description:
+        'Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment.',
+    },
+    {
+      name: 'show',
+      type: '() => void',
+      description:
+        'Opens the tooltip now and keeps it open until hide(), Escape, a press outside, or focus leaving its trigger. Its text is announced once, and onShow fires. Under a controlled isOpen it only calls onShow. Does nothing while isEnabled is false.',
+    },
+    {
+      name: 'hide',
+      type: '() => void',
+      description:
+        'Closes the tooltip now, and onHide fires. Under a controlled isOpen it only calls onHide.',
+    },
   ],
   usage: {
-    description: 'Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.',
+    description:
+      'Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.',
     bestPractices: [
-      {guidance: true, description: 'Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.'},
-      {guidance: true, description: 'Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.'},
-      {guidance: false, description: 'Put interactive content inside tooltips: use Popover or HoverCard instead.'},
+      {
+        guidance: true,
+        description:
+          'Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.',
+      },
+      {
+        guidance: true,
+        description:
+          'For a toggle-style trigger, have your own button call show() and hide() on each press. Give it aria-describedby and aria-controls set to describedBy, and aria-expanded (true while show() holds the tooltip, false after hide() or onHide), and keep its own accessible name. For an info icon, use InfoTip instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put interactive content inside tooltips: use Popover or HoverCard instead.',
+      },
     ],
   },
   relatedComponents: ['Tooltip', 'HoverCard', 'Popover'],
@@ -43,16 +157,22 @@ export const docs = {
 
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
-  description: 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
+  description:
+    'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
   paramDescriptions: {
-    placement: 'position relative to trigger. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
-    alignment: 'alignment along placement axis. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+    placement:
+      "position relative to trigger. logical: start/end follow the popover's inherited direction (RTL mirrors).",
+    alignment:
+      "alignment along placement axis. logical: start/end follow the popover's inherited direction (RTL mirrors).",
     delay: 'show delay in ms.',
     hideDelay: 'hide delay after mouse/focus leave in ms.',
-    focusTrigger: 'when focus opens tooltip; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
-    touchTrigger: 'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
+    focusTrigger:
+      'when focus opens tooltip; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
+    touchTrigger:
+      'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
     isEnabled: 'whether hover/focus triggers are enabled.',
-    isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
+    isOpen:
+      'controlled open state: true force-show, false force-hide, undefined unmanaged.',
     isDefaultOpen: 'show on mount.',
     onShow: 'fires when tooltip becomes visible.',
     onHide: 'fires when tooltip hides.',
@@ -64,13 +184,33 @@ export const docsDense = {
     anchorId: 'CSS anchor name.',
     describedBy: 'ID for aria-describedby.',
     renderTooltip: 'renders anchor-positioned tooltip content.',
+    show: 'opens + holds until hide()/Escape/outside press/focus leave; announces once; onShow. Controlled: onShow only. No-op when disabled.',
+    hide: 'closes; onHide. Controlled: onHide only.',
   },
   usage: {
-    description: 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
+    description:
+      'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
     bestPractices: [
-      {guidance: true, description: 'Use for brief text labels describing icon buttons, truncated text, abbreviations, compact controls.'},
-      {guidance: true, description: 'Prefer Tooltip for standard wrapping; use hook when trigger is not simple child.'},
-      {guidance: false, description: 'Put interactive content in tooltips: use Popover / HoverCard instead.'},
+      {
+        guidance: true,
+        description:
+          'Use for brief text labels describing icon buttons, truncated text, abbreviations, compact controls.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer Tooltip for standard wrapping; use hook when trigger is not simple child.',
+      },
+      {
+        guidance: true,
+        description:
+          'Toggle-style trigger: own button calls show()/hide() per press, sets aria-describedby + aria-controls={describedBy}, aria-expanded (true while held), keeps its own name. Info icon: use InfoTip.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put interactive content in tooltips: use Popover / HoverCard instead.',
+      },
     ],
   },
 };