@astryxdesign/core 0.7.2 → 0.7.3-canary.02f5fe4

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -304,7 +304,7 @@ export const docs = {
           name: 'disabledMessage',
           type: 'string',
           description:
-            'Explains why the selector is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled MultiSelector in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+            'Explains why the selector is disabled. With isDisabled, shows the reason as a tooltip on hover and keyboard focus of the trigger, which stays focusable (aria-disabled) like every disabled selector; activation stays blocked. Use this instead of wrapping a disabled MultiSelector in Tooltip.',
         },
         {
           name: 'isLabelHidden',
@@ -511,7 +511,7 @@ export const docs = {
       {
         guidance: false,
         description:
-          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled. Use the disabledMessage prop, which attaches the reason to the trigger itself.',
       },
     ],
   },
@@ -552,7 +552,7 @@ export const docsZh = {
         htmlName:
           '用于表单提交的 HTML name 属性。为每个已选值渲染一个隐藏输入，类似原生多选。',
         disabledMessage:
-          '解释选择器被禁用的原因。与 isDisabled 一起使用时，悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持触发器可聚焦（仍无法激活）。请使用此属性，而不是用 Tooltip 包裹被禁用的选择器。',
+          '解释选择器被禁用的原因。与 isDisabled 一起使用时，悬停/键盘聚焦时显示工具提示，触发器与所有被禁用的选择器一样通过 aria-disabled 保持可聚焦（仍无法激活）。请使用此属性，而不是用 Tooltip 包裹被禁用的选择器。',
         isLabelHidden: '视觉上隐藏标签同时保持其可访问性。',
         description: '标签下方显示的辅助文本。',
         isOptional: '将字段标记为可选。',
@@ -619,7 +619,7 @@ export const docsZh = {
       {
         guidance: false,
         description:
-          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled. Use the disabledMessage prop, which attaches the reason to the trigger itself.',
       },
     ],
   },
@@ -674,7 +674,7 @@ export const docsDense = {
       {
         guidance: false,
         description:
-          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+          'Wrap a disabled MultiSelector in Tooltip to explain why it is disabled. Use the disabledMessage prop, which attaches the reason to the trigger itself.',
       },
     ],
   },

package/src/MultiSelector/MultiSelector.focusableDisabled.test.tsx

@@ -0,0 +1,121 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MultiSelector.focusableDisabled.test.tsx
+ * @input Uses vitest, @testing-library/react, StyleX, MultiSelector
+ * @output Conformance tests for spec:AST-085 FR1–FR3 and FR6 on MultiSelector;
+ *   FR4 needs a real engine (MultiSelector.disabledFocus.a11y.chromium.spec.ts)
+ * @position Testing; validates the disabled trigger of MultiSelector.tsx
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {MultiSelector} from './MultiSelector';
+
+type Handler = () => void;
+function Harness(props: {
+  isDisabled: boolean;
+  variant?: 'input' | 'secondary' | 'ghost';
+  onClick?: Handler;
+  onKeyDown?: Handler;
+  onMouseDown?: Handler;
+  onDoubleClick?: Handler;
+}) {
+  return (
+    <form aria-label="Form">
+      <button type="button">Before</button>
+      <MultiSelector
+        label="Fruit"
+        htmlName="fruit"
+        options={['Apple', 'Banana']}
+        value={['Banana']}
+        onChange={() => {}}
+        {...props}
+      />
+      <button type="button">After</button>
+    </form>
+  );
+}
+
+const trigger = () => screen.getByRole('combobox', {name: 'Fruit'});
+
+describe('MultiSelector disabled (spec:AST-085)', () => {
+  it('FR1: renders no native disabled and keeps its tab stop', async () => {
+    const user = userEvent.setup();
+    const {container} = render(<Harness isDisabled />);
+    expect(container.querySelector('[disabled]')).toBeNull();
+    expect(trigger()).toHaveAttribute('aria-disabled', 'true');
+    await user.click(screen.getByRole('button', {name: 'Before'}));
+    await user.tab();
+    expect(trigger()).toHaveFocus();
+    await user.tab();
+    expect(screen.getByRole('button', {name: 'After'})).toHaveFocus();
+  });
+
+  it('FR2: no press or key opens it or reaches a caller or ancestor handler', async () => {
+    const user = userEvent.setup();
+    const handlers = {
+      onClick: vi.fn(),
+      onKeyDown: vi.fn(),
+      onMouseDown: vi.fn(),
+      onDoubleClick: vi.fn(),
+    };
+    const onAncestorClick = vi.fn();
+    render(
+      <div onClick={onAncestorClick}>
+        <Harness isDisabled {...handlers} />
+      </div>,
+    );
+    await user.dblClick(trigger());
+    trigger().focus();
+    for (const key of ['{Enter}', ' ', '{ArrowDown}', 'b']) {
+      await user.keyboard(key);
+    }
+    expect(trigger()).toHaveAttribute('aria-expanded', 'false');
+    expect(screen.queryByRole('listbox')).toBeNull();
+    for (const handler of [...Object.values(handlers), onAncestorClick]) {
+      expect(handler).not.toHaveBeenCalled();
+    }
+  });
+
+  it('FR3: submits no value while disabled', () => {
+    const {rerender} = render(<Harness isDisabled={false} />);
+    const form = () =>
+      screen.getByRole<HTMLFormElement>('form', {name: 'Form'});
+    expect(new FormData(form()).getAll('fruit')).toEqual(['Banana']);
+    rerender(<Harness isDisabled />);
+    expect(new FormData(form()).getAll('fruit')).toEqual([]);
+  });
+
+  // jsdom cannot match `:focus-visible`: compare the ring's StyleX class hash.
+  const RING = stylex
+    .props(
+      stylex.create({
+        ring: {
+          boxShadow: {
+            default: null,
+            ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+          },
+        },
+      }).ring,
+    )
+    .className!.split(' ')
+    .pop()!;
+
+  it.each([
+    ['input', true],
+    ['secondary', false],
+    ['ghost', false],
+  ] as const)(
+    'FR6: a disabled %s trigger carries its own ring: %s',
+    (variant, ring) => {
+      render(<Harness isDisabled variant={variant} />);
+      const wrapper = trigger().parentElement!;
+      expect(wrapper.classList.contains(RING)).toBe(ring);
+      expect(getComputedStyle(wrapper).cursor).toBe('default');
+    },
+  );
+});

package/src/MultiSelector/MultiSelector.test.tsx

@@ -35,7 +35,7 @@ import {generateThemeCSS} from '../theme/generateThemeRules';
 import {selectorPresentationStyles} from '../Selector/selectorPresentation.stylex';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {InputGroup, InputGroupText} from '../InputGroup';
-import {focusVars} from '../theme/tokens.stylex';
+import {colorVars, focusVars} from '../theme/tokens.stylex';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
@@ -210,6 +210,45 @@ describe('MultiSelector', () => {
     );
   });
 
+  it('shows no disabled focus ring after a pointer pick (spec:AST-085 FR6)', async () => {
+    const field = (isDisabled: boolean) => (
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={[]}
+        onChange={() => {}}
+        presentation="bottom-sheet"
+        isDisabled={isDisabled}
+      />
+    );
+    const {rerender} = render(field(false));
+    const trigger = screen.getByRole('combobox');
+    fireEvent.pointerDown(trigger, {pointerType: 'touch'});
+    fireEvent.click(trigger, {detail: 1});
+    const dialog = await screen.findByRole('dialog', {name: 'Fruit'});
+    fireEvent.pointerDown(dialog, {pointerType: 'touch'});
+    fireEvent.click(dialog, {detail: 1});
+    rerender(field(true));
+    const ring = stylex
+      .props(
+        stylex.create({
+          ring: {
+            boxShadow: {
+              default: null,
+              ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+            },
+          },
+        }).ring,
+      )
+      .className!.split(' ')
+      .pop()!;
+    const wrapper = screen.getByRole('combobox').parentElement!;
+    expect(wrapper).toHaveClass(
+      stylex.props(selectorPresentationStyles.pointerRestoredFocus).className!,
+    );
+    expect(wrapper).not.toHaveClass(ring);
+  });
+
   it('renders with label', () => {
     render(
       <MultiSelector
@@ -515,7 +554,9 @@ describe('MultiSelector', () => {
         isDisabled
       />,
     );
-    expect(screen.getByRole('combobox')).toBeDisabled();
+    const trigger = screen.getByRole('combobox');
+    expect(trigger).not.toHaveAttribute('disabled');
+    expect(trigger).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('has correct ARIA attributes', () => {
@@ -1602,7 +1643,7 @@ describe('MultiSelector', () => {
       expect(screen.getByRole('combobox')).toHaveFocus();
     });
 
-    it('trigger is not focusable when disabled', () => {
+    it('trigger keeps its tab stop when disabled (spec:AST-085 FR1)', () => {
       render(
         <MultiSelector
           label="Fruit"
@@ -1612,7 +1653,7 @@ describe('MultiSelector', () => {
           isDisabled
         />,
       );
-      expect(screen.getByRole('combobox')).toHaveAttribute('tabIndex', '-1');
+      expect(screen.getByRole('combobox')).toHaveAttribute('tabIndex', '0');
     });
 
     it('opens the listbox with ArrowDown from a focused trigger', async () => {
@@ -2076,7 +2117,7 @@ describe('MultiSelector', () => {
       expect(onChange).not.toHaveBeenCalled();
     });
 
-    it('remains non-focusable when disabled without a reason', () => {
+    it('stays focusable when disabled without a reason (spec:AST-085 FR1)', () => {
       render(
         <MultiSelector
           label="Fruit"
@@ -2087,8 +2128,9 @@ describe('MultiSelector', () => {
         />,
       );
       const trigger = screen.getByRole('combobox');
-      expect(trigger).toBeDisabled();
-      expect(trigger).toHaveAttribute('tabIndex', '-1');
+      expect(trigger).not.toHaveAttribute('disabled');
+      expect(trigger).toHaveAttribute('aria-disabled', 'true');
+      expect(trigger).toHaveAttribute('tabIndex', '0');
     });
   });
   describe('isReadOnly', () => {

package/src/MultiSelector/MultiSelector.tsx

@@ -271,6 +271,21 @@ const styles = stylex.create({
       '[data-astryx-press="on"]': 'scale(0.98)',
     },
   },
+  // A disabled input-variant trigger keeps its tab stop (`spec:AST-085` FR1),
+  // and the shared disabled wrapper style drops the field focus ring, so the
+  // trigger shows keyboard focus here instead (FR6). It keys on the trigger
+  // itself, a direct child, so a focused status button keeps its own outline.
+  triggerDisabledFocus: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(> [aria-disabled="true"]:focus-visible)':
+        colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   triggerGhostDisabled: {
     backgroundImage: 'none',
     transform: {
@@ -688,8 +703,8 @@ export interface MultiSelectorProps<
    * The selected values stay visible, focusable, and included in form
    * submission, and retain their combobox identity with `aria-readonly`. The
    * selection surface and editing affordances are removed.
-   * Unlike `isDisabled`, a read-only selector is not dimmed and stays in the
-   * tab order. `isDisabled` takes precedence when both are set.
+   * Unlike `isDisabled`, a read-only selector is not dimmed and keeps its
+   * value in form submission. `isDisabled` takes precedence when both are set.
    * @default false
    */
   isReadOnly?: boolean;
@@ -701,8 +716,8 @@ export interface MultiSelectorProps<
    * so the reason is discoverable by keyboard and assistive technology.
    * Activation stays blocked.
    *
-   * Use this instead of wrapping a disabled selector in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled selector in `Tooltip`, so the
+   * reason is attached to the trigger itself.
    *
    * @example
    * ```
@@ -2409,8 +2424,18 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     });
   }
 
+  // A disabled trigger stays focusable but, like a natively disabled button,
+  // runs no caller event handler other than focus and blur, and a press on it
+  // reaches no handler at all (`spec:AST-085` FR2).
+  const callerProps = isDisabled
+    ? Object.fromEntries(
+        Object.entries(rest).filter(
+          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
+        ),
+      )
+    : rest;
   const triggerSharedProps: React.HTMLAttributes<HTMLElement> = {
-    ...rest,
+    ...callerProps,
     id: triggerId,
     // A caller's description is kept alongside the field's own.
     'aria-describedby':
@@ -2423,13 +2448,20 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     // Newly forwarded handlers compose component first: the built-in toggle
     // and keyboard model always run. `onFocus` keeps its existing caller-first
     // order.
-    onKeyDown: composeEventHandlers(onKeyDown, onKeyDownProp),
+    onKeyDown: isDisabled
+      ? onKeyDown
+      : composeEventHandlers(onKeyDown, onKeyDownProp),
     onFocus: event => {
       onFocus?.(event);
       surface.onTriggerFocus(event);
     },
-    onClick: composeEventHandlers(handleTriggerButtonClick, onClick),
-    tabIndex: isDisabled && !showsDisabledMessage ? -1 : 0,
+    onClick: isDisabled
+      ? event => {
+          event.preventDefault();
+          event.stopPropagation();
+        }
+      : composeEventHandlers(handleTriggerButtonClick, onClick),
+    tabIndex: 0,
     ...stylex.props(
       styles.trigger,
       isEffectivelyReadOnly && styles.triggerReadOnly,
@@ -2496,14 +2528,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       <>
         {renderTrigger(triggerProps)}
         {htmlName != null &&
+          !isDisabled &&
           value.map(v => (
-            <input
-              key={v}
-              type="hidden"
-              name={htmlName}
-              value={v}
-              disabled={isDisabled}
-            />
+            <input key={v} type="hidden" name={htmlName} value={v} />
           ))}
         {selectionSurface}
       </>
@@ -2541,6 +2568,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             surface.isTriggerFocusRingSuppressed &&
               selectorPresentationStyles.pointerRestoredFocus,
             isDisabled && inputWrapperStyles.disabled,
+            variant === 'input' &&
+              isDisabled &&
+              !surface.isTriggerFocusRingSuppressed &&
+              styles.triggerDisabledFocus,
             isEffectivelyReadOnly && styles.triggerReadOnly,
             variant !== 'input' && isDisabled && styles.triggerGhostDisabled,
             variant !== 'input' &&
@@ -2598,26 +2629,19 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
               ? activeDescendantId
               : undefined
           }
-          // With a disabledMessage the trigger keeps focusability via
-          // aria-disabled so the reason is focus-discoverable; activation is
-          // still blocked by the isDisabled guards in useMultiCombobox.
-          disabled={isDisabled && !showsDisabledMessage}
-          aria-disabled={showsDisabledMessage ? 'true' : undefined}>
+          // A disabled trigger keeps its tab stop and says so through
+          // aria-disabled (`spec:AST-085` FR1); the isDisabled guards in
+          // useMultiCombobox block every way of opening it.
+          aria-disabled={isDisabled ? 'true' : undefined}>
           <span {...stylex.props(styles.triggerContent)}>
             {renderTriggerContent()}
           </span>
         </button>
+        {/* A disabled selector submits no value (`spec:AST-085` FR3). */}
         {htmlName != null &&
+          !isDisabled &&
           value.map(v => (
-            <input
-              key={v}
-              type="hidden"
-              name={htmlName}
-              value={v}
-              // Disabled native controls are excluded from form submission;
-              // mirror that for the hidden carriers.
-              disabled={isDisabled}
-            />
+            <input key={v} type="hidden" name={htmlName} value={v} />
           ))}
         {isBusy && <Spinner size="sm" />}
         {hasClear &&

package/src/Pagination/Pagination.test.tsx

@@ -763,9 +763,13 @@ describe('Pagination', () => {
         />,
       );
       const dot = screen.getByRole('button', {name: 'Go to page 2'});
-      expect(dot).toBeDisabled();
+      // spec:AST-085 FR1: the active dot keeps its tab stop, exposed as disabled.
+      expect(dot).not.toHaveAttribute('disabled');
+      expect(dot).toHaveAttribute('aria-disabled', 'true');
       dot.focus();
+      expect(dot).toHaveFocus();
       await user.keyboard('{ArrowRight}');
+      await user.keyboard('{Enter} ');
       expect(onChange).not.toHaveBeenCalled();
     });
   });

package/src/Pagination/Pagination.tsx

@@ -706,7 +706,9 @@ export function Pagination({
                   // needs to focus the dot, which some browsers (Safari) skip for
                   // buttons, so focus it explicitly.
                   onClick={e => e.currentTarget.focus()}
-                  disabled={isDisabled}
+                  // Disabled dots stay focusable (spec:AST-085 FR1); the page
+                  // only follows focus while enabled (handleDotsFocus).
+                  aria-disabled={isDisabled || undefined}
                   {...mergeProps(
                     themeProps('pagination-dot', {
                       active: isActive ? 'active' : null,

package/src/Popover/Popover.test.tsx

@@ -124,6 +124,21 @@ describe('Popover', () => {
     expect(screen.getByRole('button', {name: 'Open'})).toBeInTheDocument();
   });
 
+  it('does not open from an aria-disabled trigger', () => {
+    render(
+      <Popover content={<span>Content</span>} label="Test">
+        <button type="button" aria-disabled="true">
+          Trigger
+        </button>
+      </Popover>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    // A click dispatched straight on the trigger, as element.click() or an
+    // assistive-technology activate command does (spec:AST-085 FR2).
+    act(() => trigger.click());
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
   it('sets aria-haspopup on trigger', () => {
     render(
       <Popover content={<span>Content</span>} label="Test">

package/src/Popover/Popover.tsx

@@ -481,12 +481,22 @@ export function Popover({
   }, [content, popover.isOpen, scheduleOverflowMeasurement]);
 
   // Shared handler for click events on the trigger button.
-  const handleTriggerClick = useCallback(() => {
-    if (!isEnabled) {
-      return;
-    }
-    popover.toggle();
-  }, [isEnabled, popover]);
+  const handleTriggerClick = useCallback(
+    (event?: {currentTarget: EventTarget | null}) => {
+      // An aria-disabled trigger stays focusable but opens nothing
+      // (spec:AST-085 FR2), even for a click dispatched straight on it.
+      const trigger = event?.currentTarget;
+      if (
+        !isEnabled ||
+        (trigger instanceof Element &&
+          trigger.getAttribute('aria-disabled') === 'true')
+      ) {
+        return;
+      }
+      popover.toggle();
+    },
+    [isEnabled, popover],
+  );
 
   // Shared handler for keydown events on role="button" elements.
   // Native <button> synthesizes click on Enter/Space, but role="button"
@@ -495,7 +505,7 @@ export function Popover({
     (e: KeyboardEvent) => {
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
-        handleTriggerClick();
+        handleTriggerClick(e);
       }
     },
     [handleTriggerClick],
@@ -662,7 +672,8 @@ export function Popover({
   if (isRenderProp) {
     const triggerProps: PopoverTriggerRenderProps = {
       ref: popover.triggerRef,
-      onClick: handleTriggerClick,
+      // The caller renders and owns this trigger element.
+      onClick: () => handleTriggerClick(),
       'aria-haspopup': 'dialog',
       'aria-expanded': popover.isOpen,
       'aria-controls': popover.id,

package/src/PowerSearch/PowerSearchFilterEditor.test.tsx

@@ -370,7 +370,8 @@ describe('PowerSearchFilterEditor', () => {
 
     expect(screen.queryByRole('button', {name: 'Delete'})).toBeNull();
     const [fieldTrigger, operatorTrigger] = selectorTriggers();
-    expect(fieldTrigger).toBeDisabled();
-    expect(operatorTrigger).toBeDisabled();
+    // Disabled triggers stay focusable (spec:AST-085 FR1).
+    expect(fieldTrigger).toHaveAttribute('aria-disabled', 'true');
+    expect(operatorTrigger).toHaveAttribute('aria-disabled', 'true');
   });
 });

package/src/PowerSearch/PowerSearchToken.test.tsx

@@ -218,11 +218,13 @@ describe('PowerSearchToken', () => {
     expect(onRemove).toHaveBeenCalledTimes(1);
   });
 
-  it('disables both the activation and remove buttons when isDisabled is set', () => {
+  it('marks both the activation and remove buttons disabled when isDisabled is set', () => {
     renderToken({onClick: vi.fn(), onRemove: vi.fn(), isDisabled: true});
-    expect(screen.getByRole('button', {name: 'Status: is'})).toBeDisabled();
-    expect(
-      screen.getByRole('button', {name: 'Remove Status: is'}),
-    ).toBeDisabled();
+    // spec:AST-085 FR1: focusable, exposed through aria-disabled.
+    for (const name of ['Status: is', 'Remove Status: is']) {
+      const button = screen.getByRole('button', {name});
+      expect(button).not.toHaveAttribute('disabled');
+      expect(button).toHaveAttribute('aria-disabled', 'true');
+    }
   });
 });

package/src/Selector/Selector.doc.mjs

@@ -273,7 +273,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the selector is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Selector in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the selector is disabled. With isDisabled, shows the reason as a tooltip on hover and keyboard focus of the trigger, which stays focusable (aria-disabled) like every disabled selector; activation stays blocked. Use this instead of wrapping a disabled Selector in Tooltip.',
     },
     {
       name: 'isLabelHidden',
@@ -475,7 +475,7 @@ export const docs = {
       {
         guidance: false,
         description:
-          'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+          'Wrap a disabled Selector in Tooltip to explain why it is disabled. Use the disabledMessage prop, which attaches the reason to the trigger itself.',
       },
     ],
     anatomy,
@@ -536,7 +536,7 @@ export const docsZh = {
       {
         guidance: false,
         description:
-          'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+          'Wrap a disabled Selector in Tooltip to explain why it is disabled. Use the disabledMessage prop, which attaches the reason to the trigger itself.',
       },
     ],
     anatomy,
@@ -607,7 +607,7 @@ export const docsDense = {
       {
         guidance: false,
         description:
-          'Wrap a disabled Selector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+          'Wrap a disabled Selector in Tooltip to explain why it is disabled. Use the disabledMessage prop, which attaches the reason to the trigger itself.',
       },
     ],
     anatomy,