@astryxdesign/core 0.7.6 → 0.7.7-canary.0eb44a2

package/src/TabList/Tab.tsx

@@ -42,6 +42,7 @@ import {useDevWarning} from '../hooks/useDevWarning';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {isRenderable} from '../utils/isRenderable';
 
 export interface TabProps extends BaseProps<HTMLButtonElement> {
   /**
@@ -304,7 +305,8 @@ export function Tab({
   const isTabsPattern = tabListCtx.pattern === 'tabs';
   const isLink = href != null && !isTabsPattern;
   const isTabRole = isTabsPattern && !isLink;
-  const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
+  const displayIcon =
+    isSelected && isRenderable(selectedIcon) ? selectedIcon : icon;
   const hasVisibleLabel = !isLabelHidden && label !== '';
 
   const isDisabled =
@@ -353,7 +355,7 @@ export function Tab({
     !isTabsPattern && panelId != null,
   );
 
-  const iconElement = displayIcon ? (
+  const iconElement = isRenderable(displayIcon) ? (
     <span {...stylex.props(styles.icon, iconSizeStyles[size])}>
       {displayIcon}
     </span>
@@ -439,7 +441,7 @@ export function Tab({
     </span>
   ) : null;
 
-  const endContentElement = endContent ? (
+  const endContentElement = isRenderable(endContent) ? (
     <span {...stylex.props(styles.endContentWrapper)}>{endContent}</span>
   ) : null;
 

package/src/Tokenizer/Tokenizer.tsx

@@ -55,6 +55,7 @@ import {
 import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {TokenizerClearAllMessageContext} from './TokenizerClearAllMessageContext';
+import {TokenizerItemRemovableContext} from './TokenizerItemRemovableContext';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useAdaptivePresentation} from '../hooks/useAdaptivePresentation';
 import {useIsHydrating} from '../hooks/useIsHydrating';
@@ -103,6 +104,7 @@ import {
   useComponentTranslator,
 } from '../i18n/useComponentTranslator';
 import english from '../i18n/generated-english/Tokenizer/Tokenizer.generated';
+import {isRenderable} from '../utils/isRenderable';
 
 registerEnglishFallback(english);
 
@@ -1007,6 +1009,14 @@ export function Tokenizer<T extends SearchableItem>({
   // `endContent`, a clear button, or all three — so its width is measured
   // rather than assumed, and the input reserves it.
   const [laneRef, laneReserve] = useEndLaneReserve(END_LANE_INSET);
+  // A composing component can lock tokens (PowerSearch's read-only field).
+  // Backspace and the token remove controls skip a locked token. Clear all
+  // does not check it.
+  const isItemRemovable = use(TokenizerItemRemovableContext);
+  const canRemoveItem = useCallback(
+    (item: T) => isItemRemovable?.(item) ?? true,
+    [isItemRemovable],
+  );
   // The half of the lane's contents this component knows about. The busy half
   // is the leaf's own business — folding it in here would mean reading the
   // busy state during this render, which is exactly the re-render the store
@@ -1263,7 +1273,7 @@ export function Tokenizer<T extends SearchableItem>({
   // announcement covers both.
   const handleRemove = useCallback(
     (item: T, options?: {silent?: boolean}): boolean => {
-      if (isDisabled) {
+      if (isDisabled || !canRemoveItem(item)) {
         return false;
       }
       const newItems = value.filter(v => v.id !== item.id);
@@ -1274,7 +1284,7 @@ export function Tokenizer<T extends SearchableItem>({
       inputRef.current?.focus();
       return true;
     },
-    [value, onChange, isDisabled, announce, t],
+    [value, onChange, isDisabled, canRemoveItem, announce, t],
   );
 
   // Handle clearing all items
@@ -1414,7 +1424,7 @@ export function Tokenizer<T extends SearchableItem>({
         controlClassName,
         controlStyle,
       )}>
-      {startIcon && (
+      {isRenderable(startIcon as ReactNode) && (
         <span {...stylex.props(value.length > 0 && styles.startIconWithTokens)}>
           {renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
         </span>
@@ -1647,7 +1657,7 @@ export function Tokenizer<T extends SearchableItem>({
             controlClassName,
             controlStyle,
           )}>
-          {startIcon && (
+          {isRenderable(startIcon as ReactNode) && (
             <span
               {...stylex.props(value.length > 0 && styles.startIconWithTokens)}>
               {renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
@@ -1751,7 +1761,7 @@ export function Tokenizer<T extends SearchableItem>({
           )}>
           {isTruncated && (
             <>
-              {startIcon &&
+              {isRenderable(startIcon as ReactNode) &&
                 renderIconSlot(startIcon, {
                   size: 'sm',
                   color: 'secondary',

package/src/Tokenizer/TokenizerItemRemovableContext.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TokenizerItemRemovableContext.ts
+ * @input None
+ * @output A context carrying a predicate that tells which tokens the user can
+ *   remove
+ * @position Internal to Core: not exported from the Tokenizer barrel. A
+ *   component that composes Tokenizer and locks some tokens (PowerSearch: every
+ *   filter of a read-only field) provides it. Backspace then removes nothing
+ *   while the last token is locked. Without it, every token is removable.
+ */
+
+import {createContext} from 'react';
+import type {SearchableItem} from '../Typeahead/types';
+
+export const TokenizerItemRemovableContext = createContext<
+  ((item: SearchableItem) => boolean) | null
+>(null);
+TokenizerItemRemovableContext.displayName = 'TokenizerItemRemovableContext';

package/src/Tooltip/Tooltip.doc.mjs

@@ -84,9 +84,16 @@ 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. 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): 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',
@@ -130,7 +137,7 @@ export const docs = {
     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: 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.'},
     ],
@@ -197,9 +204,16 @@ export const docsZh = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none：触摸永不打开。',
+            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开。none：触摸永不打开。仅在 triggerBehavior 为 adaptive（默认）时生效。',
           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',
@@ -238,7 +252,7 @@ export const docsZh = {
     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: 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.'},
     ],
@@ -255,7 +269,7 @@ export const docsDense = {
     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: 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.'},
     ],
@@ -274,7 +288,8 @@ export const docsDense = {
         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, 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.',
         isEnabled: 'Enables/disables tooltip triggers.',
         onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',
         hasHoverIndication: 'Dashed underline on trigger element.',

package/src/Tooltip/Tooltip.tsx

@@ -25,12 +25,18 @@ import * as stylex from '@stylexjs/stylex';
 import {
   useTooltip,
   type TooltipFocusTrigger,
+  type TooltipTriggerBehavior,
   type TooltipTouchTrigger,
 } from './useTooltip';
+import {stopPressPinClick} from '../Layer/usePressPin';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {colorVars} from '../theme/tokens.stylex';
 
-export type {TooltipFocusTrigger, TooltipTouchTrigger} from './useTooltip';
+export type {
+  TooltipFocusTrigger,
+  TooltipTriggerBehavior,
+  TooltipTouchTrigger,
+} from './useTooltip';
 
 const styles = stylex.create({
   wrapperContents: {
@@ -109,15 +115,40 @@ 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
    *
+   * 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.
@@ -201,6 +232,7 @@ export function Tooltip({
   hideDelay = 0,
   focusTrigger = 'auto',
   touchTrigger = 'auto',
+  triggerBehavior = 'adaptive',
   isEnabled = true,
   onOpenChange,
   hasHoverIndication = 'auto',
@@ -230,6 +262,7 @@ export function Tooltip({
     hideDelay,
     focusTrigger,
     touchTrigger,
+    triggerBehavior,
     isEnabled,
     isOpen,
     isDefaultOpen,
@@ -343,6 +376,7 @@ export function Tooltip({
           ref={tooltip.ref}
           tabIndex={0}
           aria-describedby={tooltip.describedBy}
+          onClick={stopPressPinClick}
           {...stylex.props(
             styles.wrapperInline,
             showHoverIndication && styles.hoverIndication,
@@ -357,7 +391,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/index.ts

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

package/src/Tooltip/useTooltip.doc.mjs

@@ -12,7 +12,8 @@ export const docs = {
     {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: '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'},
@@ -50,7 +51,8 @@ export const docsDense = {
     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.',
+    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.',
     isEnabled: 'whether hover/focus triggers are enabled.',
     isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
     isDefaultOpen: 'show on mount.',

package/src/Tooltip/useTooltip.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file useTooltip.tsx
- * @input Uses useLayer, useTouchTrigger, React hooks
+ * @input Uses useLayer, usePressPin, React hooks
  * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
  * @position Layer hook; builds on useLayer for tooltip behavior
  *
@@ -26,12 +26,12 @@ import {
   type LayerAlignment,
   type LayerPlacement,
 } from '../Layer/useLayer';
-import {
-  useTouchTrigger,
-  type LayerTouchTrigger,
-} from '../Layer/useTouchTrigger';
+import type {LayerTouchTrigger} from '../Layer/useTouchTrigger';
+import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {registerLayerSurface} from '../Layer/layerSurfacePress';
+import {usePressPin} from '../Layer/usePressPin';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {themeProps} from '../utils/themeProps';
 import {
@@ -83,6 +83,14 @@ export type TooltipFocusTrigger = 'auto' | 'always' | 'never';
  */
 export type TooltipTouchTrigger = LayerTouchTrigger;
 
+/**
+ * How the trigger opens the tooltip. `adaptive`, the default, previews it on
+ * hover and focus, and a tap opens it unless the trigger acts. `hover`
+ * previews it on hover and focus, and no touch or pen tap opens it. `toggle`
+ * pins it on a click, tap, Enter, or Space on a button trigger.
+ */
+export type TooltipTriggerBehavior = 'adaptive' | 'hover' | 'toggle';
+
 export interface TooltipOptions {
   /**
    * Position placement relative to anchor
@@ -124,15 +132,35 @@ export interface TooltipOptions {
    * - `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
    *
+   * 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. Astryx clickable rows and cards
+   *   ignore the pinning press, except an Item row on a trigger that is not
+   *   a native button. The `Tooltip` component also stops it at a child
+   *   trigger. A hook caller stops a plain `onClick` ancestor itself. The
+   *   trigger reports `aria-expanded` and `aria-controls`, and the tooltip's
+   *   text is announced once when it pins. `touchTrigger` is ignored.
+   *
+   * @default 'adaptive'
+   */
+  triggerBehavior?: TooltipTriggerBehavior;
+
   /**
    * Whether the tooltip is enabled.
    * When false, hover/focus triggers are disabled.
@@ -275,6 +303,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     hideDelay = 0,
     focusTrigger = 'auto',
     touchTrigger = 'auto',
+    triggerBehavior = 'adaptive',
     isEnabled = true,
     isOpen,
     isDefaultOpen = false,
@@ -332,23 +361,44 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     hideLayer();
   }, [clearTimeouts, hideLayer]);
 
+  // A press pins the tooltip under `triggerBehavior="toggle"`. The pin also
+  // owns the tooltip's touch trigger, so this one call wires both.
   const {
-    isTouchPointerRef,
-    isTouchInteraction,
-    handlePointerEnter,
-    handlePointerDown: handleTouchPointerDown,
-    clearTapOpen,
-  } = useTouchTrigger({
+    isToggleTrigger,
+    isHeldOpen: isPressHeldOpen,
+    attach: attachPressPin,
+    unpin: unpinPress,
+    isPinShown,
+    touch: {
+      isTouchPointerRef,
+      isTouchInteraction,
+      handlePointerEnter,
+      handlePointerDown: handleTouchPointerDown,
+      clearTapOpen,
+    },
+  } = usePressPin({
+    triggerBehavior,
     touchTrigger,
     isEnabled,
-    isControlled: isOpen !== undefined,
-    isOpen: isLayerOpen,
-    layerId: layerId,
+    isOpen,
+    isLayerOpen,
+    layerId,
     triggerRef,
+    component: 'Tooltip',
     show: showNow,
     hide: hideNow,
+    report: next => (next ? onShow?.() : onHide?.()),
   });
 
+  // Only a pin announces the text: a preview is already the trigger's
+  // description.
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  useAnnounceRenderedText(contentRef, isPinShown, 'pinned');
+  const contentRefs = useMergedRefs<HTMLDivElement>(
+    contentRef,
+    registerLayerSurface,
+  );
+
   // Schedule show with delay (suppressed when isOpen is false)
   const scheduleShow = useCallback(() => {
     if (!isEnabled || isOpen === false) {
@@ -376,7 +426,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // trigger onto the tooltip surface without the tooltip vanishing — required
   // for WCAG 1.4.13 (Content on Hover or Focus: hoverable).
   const scheduleHide = useCallback(() => {
-    if (isOpen === true) {
+    if (isOpen === true || isPressHeldOpen()) {
       return;
     }
     clearTimeouts();
@@ -384,7 +434,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     hideTimeoutRef.current = setTimeout(() => {
       hideLayer();
     }, effectiveHideDelay);
-  }, [isOpen, clearTimeouts, hideLayer, hideDelay]);
+  }, [isOpen, isPressHeldOpen, clearTimeouts, hideLayer, hideDelay]);
 
   // Cancel a pending hide (e.g. the pointer entered the tooltip surface).
   const cancelHide = useCallback(() => {
@@ -482,6 +532,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     ],
   );
 
+  // A pinned tooltip's focus-leave close is the pin's own: it listens on the
+  // trigger whatever `focusTrigger` is. This schedules the unpinned hide,
+  // which a held tooltip skips.
   const handleFocusOut = useCallback(
     (e: Event) => {
       if (!focusCountedRef.current && !isFocusForTrigger(e)) {
@@ -502,6 +555,11 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // tooltip at all), so the touch path answers it first.
   const handlePointerDown = useCallback(
     (event: PointerEvent) => {
+      // A press on a toggle trigger pins or closes through its click. It
+      // neither hides the preview here nor waits for a tap verdict.
+      if (isToggleTrigger(triggerRef.current)) {
+        return;
+      }
       if (handleTouchPointerDown(event)) {
         return;
       }
@@ -511,7 +569,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       clearTimeouts();
       hideLayer();
     },
-    [handleTouchPointerDown, isOpen, clearTimeouts, hideLayer],
+    [isToggleTrigger, handleTouchPointerDown, isOpen, clearTimeouts, hideLayer],
   );
 
   // Interaction ref that handles event listeners only
@@ -552,8 +610,10 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       }
 
       triggerRef.current = el;
+      attachPressPin(el);
     },
     [
+      attachPressPin,
       focusTrigger,
       handleMouseEnter,
       handleMouseLeave,
@@ -641,6 +701,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     onDismiss: () => {
       clearTimeouts();
       clearTapOpen();
+      unpinPress();
       if (isOpen !== undefined) {
         onHide?.();
         return;
@@ -677,7 +738,8 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         // something else in the shared interactive-ancestor walk, so a
         // clickable container around the trigger leaves the press alone while
         // document listeners still see it.
-        <div ref={registerLayerSurface} {...stylex.props(styles.content)}>
+        // The pin's announcement reads this element's text.
+        <div ref={contentRefs} {...stylex.props(styles.content)}>
           {children}
         </div>,
         renderProps,
@@ -690,6 +752,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       popoverXstyle,
       cancelHide,
       scheduleHide,
+      contentRefs,
     ],
   );
 

package/src/Typeahead/BaseTypeahead.tsx

@@ -79,6 +79,7 @@ import {
   useComponentTranslator,
 } from '../i18n/useComponentTranslator';
 import english from '../i18n/generated-english/Typeahead/BaseTypeahead.generated';
+import {textEntryTraitAttributes} from '../Field/textEntryTraits';
 
 registerEnglishFallback(english);
 // =============================================================================
@@ -607,8 +608,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   );
   // Committed values (Tokenizer's tokens) leave the shown rows in the same
   // render that commits them, before any reload answers, so a list never
-  // offers a token (component:Tokenizer FR13). The highlight stays on its item
-  // when that item remains. The previous key is remembered in state, like
+  // offers a token (component:Tokenizer FR13). Until the reload answers, the
+  // highlight stays on its item when that item remains; the reloaded list
+  // highlights its first row. The previous key is remembered in state, like
   // `sourceOfState` below.
   const committedChoices = useCommittedChoices();
   const committedChoicesKey = committedChoices?.key;
@@ -1119,11 +1121,16 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       resultsGenRef.current = gen;
       const shown = bootstrapResults.slice(0, maxMenuItems);
       const nextHighlightedIndex = shown.length > 0 ? 0 : -1;
+      // A focus load that yields no choice, or fails (it arrives here empty),
+      // closes the list rather than leaving it open and empty. A typed
+      // query's empty search is not a focus load and keeps its empty-search
+      // message.
       if (
         results.length === 0 &&
         shown.length === 0 &&
         highlightedIndex === -1
       ) {
+        popover.hide();
         return;
       }
       setHeldHeight(null);
@@ -1131,11 +1138,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       setHighlightedIndex(nextHighlightedIndex);
       if (bootstrapResults.length > 0) {
         showLayer();
-      } else if (committedChoices != null) {
-        // A Tokenizer list left with no eligible choice (its focus entries
-        // all committed, or the request failed) closes rather than staying
-        // open and empty (component:Tokenizer FR15). A plain Typeahead
-        // provides no committed choices and keeps its current behavior.
+      } else {
         popover.hide();
       }
     },
@@ -1146,7 +1149,6 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       showLayer,
       replaceResults,
       popover,
-      committedChoices,
     ],
   );
 
@@ -1722,6 +1724,12 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         autoComplete="off"
+        // Autocorrect would rewrite names and identifiers. The key is only a
+        // label: Enter still commits the highlighted option.
+        {...textEntryTraitAttributes({
+          enterKeyHint: 'search',
+          hasAutoCorrect: false,
+        })}
         {...mergeProps(
           stylex.props(
             styles.input,