@astryxdesign/core 0.7.7-canary.f9ac85f → 0.7.7

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,16 +105,9 @@ 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. none never opens on touch. It decides only under triggerBehavior="adaptive", the default.',
+            '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'",
         },
-        {
-          name: 'triggerBehavior',
-          type: "'adaptive' | 'hover' | 'toggle'",
-          description:
-            'How the trigger opens the tooltip. adaptive (the default): hover and focus preview it, and a tap opens it unless the trigger performs an action of its own, as touchTrigger decides while it remains. hover: hover and focus preview it, and no touch or pen tap opens it. toggle, on a button trigger: a click, a tap, Enter, or Space pins the tooltip and the same press closes it, while hover and keyboard focus still preview it. A pinned tooltip stays until Escape, a second press, a press outside, or focus leaving, and the press stops at the trigger, so a clickable row or card around it does not activate (with anchorRef, the anchored trigger still runs its own onClick, Astryx clickable rows and cards ignore the press except an Item row when the anchor is not a native button, and a plain onClick element around the anchor receives it unless that onClick stops it). The trigger reports aria-expanded and aria-controls, and the text is announced once when it pins. Use it for an info icon or any button whose only job is revealing the tooltip.',
-          default: "'adaptive'",
-        },
         {
           name: 'isEnabled',
           type: 'boolean',
@@ -115,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',
@@ -126,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 triggerBehavior to toggle when the trigger is a button whose only job is revealing the tooltip, such as an info icon: a click, a tap, Enter, or Space pins it, and the press stops at the trigger.'},
-      {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.',
+      },
     ],
   },
 };
@@ -152,8 +185,7 @@ export const docsZh = {
     {
       name: 'Tooltip',
       displayName: 'Tooltip',
-      description:
-        '工具提示显示的组件包装器，通过悬停或聚焦触发。',
+      description: '工具提示显示的组件包装器，通过悬停或聚焦触发。',
       props: [
         {
           name: 'children',
@@ -173,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'",
         },
         {
@@ -204,16 +238,9 @@ export const docsZh = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开。none：触摸永不打开。仅在 triggerBehavior 为 adaptive（默认）时生效。',
+            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开，适用于唯一作用是显示工具提示的按钮；信息图标请使用 InfoTip。none：触摸永不打开。',
           default: "'auto'",
         },
-        {
-          name: 'triggerBehavior',
-          type: "'adaptive' | 'hover' | 'toggle'",
-          description:
-            '触发元素如何打开工具提示。adaptive（默认）：悬停和聚焦会预览；轻点即打开，除非触发元素本身会执行操作（在 touchTrigger 仍存在期间由它决定）。hover：悬停和聚焦会预览，触摸或触控笔轻点都不会打开。toggle（仅限按钮触发元素）：单击、轻点、Enter 或空格键固定打开，再按一次关闭；悬停和键盘聚焦仍会预览。固定后，直到按 Escape、再次按下、在外部按下或焦点移出才关闭；这次按下止于触发元素，外层可点击的行或卡片不会被激活（使用 anchorRef 时，锚定元素自身的 onClick 仍会运行，Astryx 的可点击行和卡片会忽略这次按下，但锚定元素不是原生按钮时，Item 行仍会响应，锚定元素外层普通的 onClick 元素仍会收到，除非锚定元素的 onClick 阻止它）。触发元素会报告 aria-expanded 和 aria-controls，固定时朗读一次文本。适用于信息图标等唯一作用就是显示工具提示的按钮。',
-          default: "'adaptive'",
-        },
         {
           name: 'isEnabled',
           type: 'boolean',
@@ -241,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 triggerBehavior to toggle when the trigger is a button whose only job is revealing the tooltip, such as an info icon: a click, a tap, Enter, or Space pins it, and the press stops at the trigger.'},
-      {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 triggerBehavior to toggle when the trigger is a button whose only job is revealing the tooltip, such as an info icon: a click, a tap, Enter, or Space pins it, and the press stops at the trigger.'},
-      {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: [
@@ -283,15 +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, under triggerBehavior="adaptive" only. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens; none = never on touch.',
-        triggerBehavior: 'adaptive (default) = hover/focus preview, a tap opens unless the trigger acts; hover = hover/focus preview, no touch/pen tap opens; toggle = a click/tap/Enter/Space on a button trigger pins the tooltip (aria-expanded, announced once), the same press closes it, and the press stops at the trigger.',
+        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,20 +24,18 @@ import React, {
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {
-  useTooltip,
+  useTooltipWithTriggerBehavior,
   type TooltipFocusTrigger,
-  type TooltipTriggerBehavior,
   type TooltipTouchTrigger,
 } from './useTooltip';
-import {stopPressPinClick} from '../Layer/usePressPin';
+import {
+  stopPressPinClick,
+  type LayerTriggerBehavior,
+} from '../Layer/usePressPin';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {colorVars} from '../theme/tokens.stylex';
 
-export type {
-  TooltipFocusTrigger,
-  TooltipTriggerBehavior,
-  TooltipTouchTrigger,
-} from './useTooltip';
+export type {TooltipFocusTrigger, TooltipTouchTrigger} from './useTooltip';
 
 const styles = stylex.create({
   wrapperContents: {
@@ -118,37 +117,10 @@ export interface TooltipProps {
    * - `tap`: tap always opens the tooltip, even on a trigger that acts
    * - `none`: touch never opens the tooltip
    *
-   * It decides only under `triggerBehavior="adaptive"`, the default.
-   *
    * @default 'auto'
    */
   touchTrigger?: TooltipTouchTrigger;
 
-  /**
-   * How the trigger opens the tooltip:
-   * - `adaptive` (the default): hover and focus preview it. A tap opens it
-   *   unless the trigger performs an action of its own. While `touchTrigger`
-   *   remains, it decides those taps.
-   * - `hover`: hover and focus preview it; no touch or pen tap opens it.
-   * - `toggle`: on a button trigger, a click, a tap, Enter, or Space pins the
-   *   tooltip open, and the same press closes it. Hover and keyboard focus
-   *   still preview it. A pinned tooltip stays until Escape, a second press,
-   *   a press outside, or focus leaving. The press stops at the trigger. Its
-   *   default action is prevented, and the trigger's own handlers still run.
-   *   No clickable row or card around the trigger activates. With
-   *   `anchorRef`, the anchor's own `onClick` runs, and a plain `onClick`
-   *   element around it receives the press unless that `onClick` stops it.
-   *   Astryx clickable rows, cards, and containers ignore it, except an Item
-   *   row when the anchor is not a native button. The trigger reports
-   *   `aria-expanded` and `aria-controls`, and the tooltip's text is
-   *   announced once when it pins. Use it for a trigger whose information
-   *   lives only in the tooltip, such as an info icon. `touchTrigger` is
-   *   ignored.
-   *
-   * @default 'adaptive'
-   */
-  triggerBehavior?: TooltipTriggerBehavior;
-
   /**
    * Whether the tooltip is enabled.
    * When false, hover/focus triggers are disabled.
@@ -222,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,
@@ -238,7 +235,7 @@ export function Tooltip({
   hasHoverIndication = 'auto',
   isOpen,
   isDefaultOpen,
-}: TooltipProps): ReactElement {
+}: TooltipWithTriggerBehaviorProps): ReactElement {
   const wrapperRef = useRef<HTMLDivElement>(null);
   const textOnly = children != null ? isTextOnly(children) : false;
 
@@ -255,7 +252,7 @@ export function Tooltip({
   }, [onOpenChange]);
 
   // Use the hook for all tooltip behavior
-  const tooltip = useTooltip({
+  const tooltip = useTooltipWithTriggerBehavior({
     placement,
     alignment,
     delay,

package/src/Tooltip/index.ts

@@ -15,7 +15,6 @@
 export {useTooltip} from './useTooltip';
 export type {
   TooltipFocusTrigger,
-  TooltipTriggerBehavior,
   TooltipTouchTrigger,
   TooltipOptions,
   TooltipReturn,

package/src/Tooltip/useTooltip.doc.mjs

@@ -7,33 +7,129 @@ 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; none never opens on touch. It decides only under triggerBehavior="adaptive", the default.', default: "'auto'"},
-    {name: 'triggerBehavior', type: "'adaptive' | 'hover' | 'toggle'", description: 'How the trigger opens the tooltip. adaptive (the default) previews on hover and focus and opens on a tap unless the trigger acts (touchTrigger decides while it remains); hover previews on hover and focus, and no touch or pen tap opens it; toggle, on a button trigger, pins on a click, a tap, Enter, or Space and closes on the same press, Escape, a press outside, or focus leaving. The trigger carries aria-expanded and aria-controls, the tooltip is announced once when it pins. Astryx clickable rows and cards ignore the pinning press, except an Item row on a trigger that is not a native button; a plain onClick ancestor still receives it from the hook (the Tooltip component stops it at a child trigger).', default: "'adaptive'"},
-    {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.',
+    },
   ],
   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: false,
+        description:
+          'Put interactive content inside tooltips: use Popover or HoverCard instead.',
+      },
     ],
   },
   relatedComponents: ['Tooltip', 'HoverCard', 'Popover'],
@@ -44,17 +140,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, under triggerBehavior adaptive only; auto = tap unless trigger acts, tap = always, none = never.',
-    triggerBehavior: 'adaptive (default) = hover/focus preview, tap opens unless the trigger acts; hover = no touch/pen tap opens; toggle = a press on a button trigger pins and closes; clickable rows and cards ignore it (an Item row only on a native-button trigger), and the Tooltip component also stops it at a child trigger.',
+    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.',
@@ -68,11 +169,24 @@ export const docsDense = {
     renderTooltip: 'renders anchor-positioned tooltip content.',
   },
   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: false,
+        description:
+          'Put interactive content in tooltips: use Popover / HoverCard instead.',
+      },
     ],
   },
 };