@astryxdesign/core 0.7.3-canary.f94e962 → 0.7.3

package/src/FieldStatus/FieldStatus.spec.md

@@ -130,9 +130,9 @@ intentional decision.
   region, including on first mount and when message or type changes, without
   moving focus. Inside a mounted live container, `spec:AST-086` FR4 applies.
 - **AR5 — Assistive-technology output.** Claims about whether, when, or how the
-  message is spoken or presented in braille MUST be verified through the real-AT
-  evidence process in `spec:AST-009`; DOM and accessibility-tree checks prove
-  only programmatic exposure and routing.
+  message is spoken or presented in braille are recommended real-AT follow-up
+  under `spec:AST-009`, not a merge or release requirement; DOM and
+  accessibility-tree checks prove programmatic exposure and routing.
 - **AR2 — Visible description.** The rendered message box MUST remain available
   to assistive technology for `aria-describedby` association and MUST NOT become
   its own newly mounted live region.
@@ -182,7 +182,7 @@ change either presentation.
 | FR5, FR6            | `FieldStatus.test.tsx` forwarding and update suites                     | Initial render and rerender                                   | Breaking the released root or update behavior fails compatibility assertions.                                                         | `audit:FieldStatus/behavior`      |
 | AR1                 | `StatusMessage.a11y.test.tsx` and `StatusMessage.a11y.chromium.spec.ts` | Error, warning, and success; post-mount message replacement   | Removing the persistent channel, changing its role/urgency, or dropping a post-mount update fails the shared status-message contract. | `audit:FieldStatus/accessibility` |
 | AR1                 | `FieldStatus.test.tsx` channel-routing suite                            | First non-empty mount; same-instance message and type changes | Breaking FieldStatus's first-use hook call or severity rerouting fails component-specific assertions.                                 | `audit:FieldStatus/accessibility` |
-| AR5                 | Pending/unverified real-AT evidence governed by `spec:AST-009`          | First mount; message replacement; type/urgency change         | Spoken and braille output remain unverified until a durable named AT/browser receipt exists.                                          | `audit:FieldStatus/accessibility` |
+| AR5                 | Recommended real-AT follow-up under `spec:AST-009`                      | First mount; message replacement; type/urgency change         | Spoken and braille output stay unverified until a real-AT receipt exists; this does not block merge or release.                       | `audit:FieldStatus/accessibility` |
 | AR2                 | `FieldStatus.test.tsx`                                                  | Attached/detached visible message and empty message           | The visible description becomes a second live region or is hidden from assistive technology.                                          | `audit:FieldStatus/accessibility` |
 | Theming anatomy map | `scripts/check-knowledge.mjs`                                           | Consumer anatomy and current targets                          | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                   | `audit:FieldStatus/theming`       |
 

package/src/FieldStatus/__tests__/StatusMessage.a11y.renders.tsx

@@ -10,7 +10,6 @@
  */
 
 import {useEffect, useState, type ReactElement, type ReactNode} from 'react';
-import {ChatSystemMessage} from '../../Chat/ChatSystemMessage';
 import {ProgressBar} from '../../ProgressBar/ProgressBar';
 import {Spinner} from '../../Spinner/Spinner';
 import {Toast} from '../../Toast/Toast';
@@ -198,22 +197,6 @@ function SpinnerHarness({visibleLabel}: {visibleLabel: boolean}) {
   );
 }
 
-function ChatSystemMessageHarness() {
-  const initial = 'Conversation started';
-  const [message, setMessage] = useState(initial);
-  return (
-    <Frame>
-      <TransitionButton name="show" onClick={() => setMessage(initial)} />
-      <TransitionButton
-        name="replace"
-        onClick={() => setMessage('A file was shared')}
-      />
-      <TransitionButton name="clear" onClick={() => setMessage('')} />
-      <ChatSystemMessage>{message}</ChatSystemMessage>
-    </Frame>
-  );
-}
-
 function ProgressHarness({
   initial,
   progressValue = 40,
@@ -289,7 +272,6 @@ export const CORE_STATUS_MESSAGE_STATE_RENDERS: Record<
     <SpinnerHarness visibleLabel={false} />
   ),
   'spinner-visible-label-mounted': () => <SpinnerHarness visibleLabel />,
-  'chat-system-status-mounted': () => <ChatSystemMessageHarness />,
   'progress-loading-to-complete': () => <ProgressHarness />,
   'progress-custom-range': () => (
     <ProgressHarness

package/src/FieldStatus/__tests__/StatusMessage.a11y.states.ts

@@ -14,7 +14,6 @@ export type CoreStatusMessageBinding =
   | 'Toast card'
   | 'FieldStatus announcement channel'
   | 'Spinner'
-  | 'ChatSystemMessage'
   | 'ProgressBar';
 
 export interface CoreStatusMessageBindingDefinition {
@@ -188,20 +187,6 @@ export const CORE_STATUS_MESSAGE_BINDING_STATES = [
     }),
     storyId: 'a11y-status-message-pattern--spinner-visible-label-mounted',
   },
-  {
-    id: 'chat-system-status-mounted',
-    binding: 'ChatSystemMessage',
-    summary: 'a chat status notice is mounted with its live-region content',
-    facts: liveFacts({
-      role: 'status',
-      politeness: 'polite',
-      initialMessage: 'Conversation started',
-      message: 'Conversation started',
-      replacement: 'A file was shared',
-      semanticTransitions: ['replace', 'clear'],
-    }),
-    storyId: 'a11y-status-message-pattern--chat-system-status-mounted',
-  },
   {
     id: 'progress-loading-to-complete',
     binding: 'ProgressBar',
@@ -279,10 +264,10 @@ export const CORE_STATUS_MESSAGE_EXCLUSIONS = [
       'A composing control that marks Spinner aria-hidden owns the surrounding busy semantics; the decorative ring is not another status message.',
   },
   {
-    owner: 'ChatSystemMessage divider',
-    part: 'date or section separator',
+    owner: 'ChatSystemMessage',
+    part: 'chat notice or date separator',
     reason:
-      'A divider does not report success, results, waiting, progress, or an error. Its current forced status role is tracked as a separate ownership mismatch rather than adopted here.',
+      'spec:AST-086 FR4: a notice added to a chat log is delivered by the log, so neither the notice row nor the divider carries its own live role; a date or section separator is ordinary transcript content.',
   },
   {
     owner: 'ChatMessageList and streaming logs',

package/src/FieldStatus/__tests__/StatusMessage.a11y.test.tsx

@@ -128,7 +128,6 @@ describe('Core status-message binding inventory', () => {
         ),
       ].sort(),
     ).toEqual([
-      'ChatSystemMessage',
       'FieldStatus announcement channel',
       'ProgressBar',
       'Spinner',
@@ -141,7 +140,7 @@ describe('Core status-message binding inventory', () => {
     expect(CORE_STATUS_MESSAGE_EXCLUSIONS.map(entry => entry.part)).toEqual([
       'visible validation text',
       'aria-hidden decorative spinner',
-      'date or section separator',
+      'chat notice or date separator',
       'role=log transcript updates',
       'composer errors and tool-run states',
       'busy announcement',

package/src/Markdown/Markdown.helpers.perf.test.ts

@@ -357,17 +357,17 @@ describe('Markdown helper performance', () => {
         }),
       ];
 
-      // Timed on the transform stage alone and compared at the FASTEST
-      // sample of each side: this is a few hundred microseconds against a
-      // parse of milliseconds, so measuring the whole parse buries it, and
-      // a minimum is the least-disturbed sample each side achieved.
+      // Timed on the transform stage alone: this is a few hundred
+      // microseconds against a parse of milliseconds, so measuring the whole
+      // parse buries it. Each side is compared at its FASTEST sample, the
+      // least-disturbed run it achieved, and the two sides alternate sample by
+      // sample so a slow stretch of the machine reaches both instead of one.
       const root = parseMarkdownAst(source);
-      const fastestTransform = (
+      const transformOnly = (
         plugins: ReadonlyArray<ReturnType<typeof createMarkdownPlugin>>,
-      ): number => {
+      ) => {
         const prepared = prepareMarkdownPlugins(plugins);
-        let fastest = Number.POSITIVE_INFINITY;
-        for (let sample = 0; sample < 60; sample++) {
+        return () => {
           const start = performance.now();
           benchmarkSink ^= applyMarkdownTransforms(
             root,
@@ -376,18 +376,24 @@ describe('Markdown helper performance', () => {
             true,
             'block',
           ).children.length;
-          fastest = Math.min(fastest, performance.now() - start);
-        }
-        void benchmarkSink;
-        return fastest;
+          return performance.now() - start;
+        };
       };
-
-      const single = plugin('scale-single', gaps);
-      const double = plugin('scale-double', doubled);
-      // Warm both before either is recorded.
-      fastestTransform(single);
-      fastestTransform(double);
-      const ratio = fastestTransform(double) / fastestTransform(single);
+      const single = transformOnly(plugin('scale-single', gaps));
+      const double = transformOnly(plugin('scale-double', doubled));
+      let fastestSingle = Number.POSITIVE_INFINITY;
+      let fastestDouble = Number.POSITIVE_INFINITY;
+      for (let sample = 0; sample < 80; sample++) {
+        // The first rounds only warm both sides.
+        const singleTime = single();
+        const doubleTime = double();
+        if (sample >= 20) {
+          fastestSingle = Math.min(fastestSingle, singleTime);
+          fastestDouble = Math.min(fastestDouble, doubleTime);
+        }
+      }
+      void benchmarkSink;
+      const ratio = fastestDouble / fastestSingle;
       console.log(
         `  ${sections} sections, ${doubled.length} ranges over ${gaps.length}: ${ratio.toFixed(3)}`,
       );

package/src/Markdown/Markdown.rerender.test.tsx

@@ -0,0 +1,143 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Markdown.rerender.test.tsx
+ * @input Uses vitest, @testing-library/react, Markdown, a synthetic long document
+ * @output Tests that an unrelated caller re-render reuses the rendered document
+ * @position Performance regression evidence for long documents. Counting
+ *   renders of a caller-supplied block renderer is deterministic, unlike a
+ *   timing budget, and fails when Markdown rebuilds every block element on a
+ *   re-render that changed nothing it reads.
+ */
+
+import {useState} from 'react';
+import {act, cleanup, fireEvent, render} from '@testing-library/react';
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {Markdown} from './Markdown';
+import type {MarkdownComponents} from './Markdown';
+
+afterEach(() => {
+  cleanup();
+});
+
+/** A long, review-style document: headings, prose, lists, a table, code. */
+function longDocument(sections: number): string {
+  return Array.from({length: sections}, (_, i) =>
+    [
+      `## Section ${i}`,
+      '',
+      `Paragraph ${i} with **bold**, *emphasis*, \`code\` and a [link](/docs/${i}).`,
+      '',
+      `- Point ${i}`,
+      `  - Nested point ${i}`,
+      `- [x] Done ${i}`,
+      '',
+      '| Name | Count |',
+      '| --- | ---: |',
+      `| row ${i} | ${i * 3} |`,
+      '',
+      '```ts',
+      `const value${i} = ${i};`,
+      '```',
+    ].join('\n'),
+  ).join('\n\n');
+}
+
+const SECTIONS = 40;
+
+function createCountingComponents(): {
+  components: Partial<MarkdownComponents>;
+  renders: () => number;
+} {
+  let count = 0;
+  function CountingCode({code}: {code: string; language?: string}) {
+    count++;
+    return <pre data-testid="code">{code}</pre>;
+  }
+  return {components: {code: CountingCode}, renders: () => count};
+}
+
+describe('Markdown re-render reuse', () => {
+  it('does not re-render any block when a caller re-render changes nothing Markdown reads', () => {
+    const {components, renders} = createCountingComponents();
+    const source = longDocument(SECTIONS);
+    let bump: () => void = () => {};
+    function Page() {
+      const [tick, setTick] = useState(0);
+      bump = () => setTick(t => t + 1);
+      return (
+        <section data-tick={tick}>
+          {/* A new link handler each render, as inline callers write it. */}
+          <Markdown components={components} onLinkClick={() => {}}>
+            {source}
+          </Markdown>
+        </section>
+      );
+    }
+    const {container} = render(<Page />);
+    const document = container.querySelector('[role="document"]');
+    const html = document?.innerHTML;
+    expect(renders()).toBe(SECTIONS);
+
+    act(() => bump());
+    act(() => bump());
+
+    expect(renders()).toBe(SECTIONS);
+    expect(container.querySelector('[role="document"]')).toBe(document);
+    expect(document?.innerHTML).toBe(html);
+  });
+
+  it('re-renders when the text changes', () => {
+    const {components, renders} = createCountingComponents();
+    const {rerender, getAllByTestId} = render(
+      <Markdown components={components}>{longDocument(2)}</Markdown>,
+    );
+    expect(renders()).toBe(2);
+    rerender(
+      <Markdown components={components}>
+        {`${longDocument(2)}\n\n\`\`\`ts\nconst added = true;\n\`\`\``}
+      </Markdown>,
+    );
+    expect(getAllByTestId('code')).toHaveLength(3);
+    expect(getAllByTestId('code')[2].textContent).toBe('const added = true;');
+  });
+
+  it('re-renders when a rendering prop changes', () => {
+    const {container, rerender} = render(
+      <Markdown headingLevelStart={1}>{'# Title'}</Markdown>,
+    );
+    expect(container.querySelector('h1')).not.toBeNull();
+    rerender(<Markdown headingLevelStart={3}>{'# Title'}</Markdown>);
+    expect(container.querySelector('h1')).toBeNull();
+    expect(container.querySelector('h3')?.textContent).toBe('Title');
+  });
+
+  it('calls the latest link handler after a re-render that reused the document', () => {
+    const first = vi.fn();
+    const latest = vi.fn(() => false as const);
+    const {container, rerender} = render(
+      <Markdown onLinkClick={first}>{'[go](/next)'}</Markdown>,
+    );
+    rerender(<Markdown onLinkClick={latest}>{'[go](/next)'}</Markdown>);
+    const link = container.querySelector('a');
+    expect(link).not.toBeNull();
+    const event = new MouseEvent('click', {bubbles: true, cancelable: true});
+    act(() => {
+      link?.dispatchEvent(event);
+    });
+    expect(first).not.toHaveBeenCalled();
+    expect(latest).toHaveBeenCalledWith('/next', expect.anything());
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it('starts and stops handling link clicks when the handler is added or removed', () => {
+    const handler = vi.fn();
+    const {container, rerender} = render(<Markdown>{'[go](/next)'}</Markdown>);
+    rerender(<Markdown onLinkClick={handler}>{'[go](/next)'}</Markdown>);
+    fireEvent.click(container.querySelector('a') as HTMLAnchorElement);
+    expect(handler).toHaveBeenCalledTimes(1);
+    rerender(<Markdown>{'[go](/next)'}</Markdown>);
+    fireEvent.click(container.querySelector('a') as HTMLAnchorElement);
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});

package/src/Markdown/Markdown.tsx

@@ -41,6 +41,7 @@ import {TableHeaderCell} from '../Table/TableHeaderCell';
 import {TableHeader} from '../Table/TableHeader';
 import {TableBody} from '../Table/TableBody';
 import {mergeProps} from '../utils';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {useStreamingText} from '../hooks/useStreamingText';
 import {computeBoundaries, computeSegments} from './streaming';
 import type {BaseProps} from '../BaseProps';
@@ -2122,6 +2123,21 @@ export function Markdown<
 }: MarkdownProps<Plugins>): React.ReactElement {
   const t = useTranslator();
   const LinkComponent = useLinkComponent();
+  // Links read the caller's handler when clicked, so a handler recreated on
+  // every caller render does not invalidate the memoized document below.
+  // Only whether a handler exists changes the rendered links.
+  const onLinkClickRef = useRef(onLinkClick);
+  useIsomorphicLayoutEffect(() => {
+    onLinkClickRef.current = onLinkClick;
+  });
+  const hasLinkClick = onLinkClick != null;
+  const stableOnLinkClick = useMemo<MarkdownProps['onLinkClick']>(
+    () =>
+      hasLinkClick
+        ? (href, event) => onLinkClickRef.current?.(href, event)
+        : undefined,
+    [hasLinkClick],
+  );
   // Derive the set of source IDs for the parser (stable across renders when sources don't change)
   const sourceIds = useMemo(
     () => (sources ? new Set(Object.keys(sources)) : undefined),
@@ -2327,19 +2343,80 @@ export function Markdown<
     return next;
   }, [display, smoothedLen, maxSpans]);
 
-  const cursor: StreamingCursor = {
-    offset: 0,
-    boundaries,
-    active: isStreaming,
-  };
-
-  // Build citation context — numbers are assigned in encounter order during rendering.
-  // This is recreated each render so numbering stays consistent with the AST.
-  const citationCtx: CitationContext | null = sources
-    ? {sources, numberMap: new Map(), nextNumber: 1, style: citationStyle}
+  const contentWidthValue = contentWidth
+    ? typeof contentWidth === 'number'
+      ? `${contentWidth}px`
+      : contentWidth
     : null;
 
+  // The block document is the expensive part of a long Markdown render. It
+  // depends only on these inputs, so a caller re-render that changes none of
+  // them returns the same elements and React skips the whole subtree. The
+  // cursor and citation numbering are rebuilt inside, from the start of the
+  // document, exactly as a full render builds them.
+  const renderedBlocks = useMemo(() => {
+    if (display === 'inline') {
+      return null;
+    }
+    const blockCursor: StreamingCursor = {
+      offset: 0,
+      boundaries,
+      active: isStreaming,
+    };
+    // Numbers are assigned in encounter order during rendering.
+    const blockCitationCtx: CitationContext | null = sources
+      ? {sources, numberMap: new Map(), nextNumber: 1, style: citationStyle}
+      : null;
+    return blocks.map((block, i) =>
+      renderBlock(
+        block,
+        i,
+        blocks.length,
+        density,
+        headingLevelStart,
+        stableOnLinkClick,
+        blockCursor,
+        blockCitationCtx,
+        contentWidthValue,
+        contentAlign,
+        LinkComponent,
+        inlinePlugins,
+        components,
+        preparedPlugins,
+        t,
+        headingProjection,
+      ),
+    );
+  }, [
+    display,
+    blocks,
+    boundaries,
+    isStreaming,
+    sources,
+    citationStyle,
+    density,
+    headingLevelStart,
+    stableOnLinkClick,
+    contentWidthValue,
+    contentAlign,
+    LinkComponent,
+    inlinePlugins,
+    components,
+    preparedPlugins,
+    t,
+    headingProjection,
+  ]);
+
   if (display === 'inline') {
+    const cursor: StreamingCursor = {
+      offset: 0,
+      boundaries,
+      active: isStreaming,
+    };
+    // Numbers are assigned in encounter order during rendering.
+    const citationCtx: CitationContext | null = sources
+      ? {sources, numberMap: new Map(), nextNumber: 1, style: citationStyle}
+      : null;
     const renderedInline = (
       <span
         ref={ref}
@@ -2357,7 +2434,7 @@ export function Markdown<
           renderInline(
             node,
             i,
-            onLinkClick,
+            stableOnLinkClick,
             cursor,
             citationCtx,
             LinkComponent,
@@ -2391,30 +2468,7 @@ export function Markdown<
         className,
         style,
       )}>
-      {blocks.map((block, i) =>
-        renderBlock(
-          block,
-          i,
-          blocks.length,
-          density,
-          headingLevelStart,
-          onLinkClick,
-          cursor,
-          citationCtx,
-          contentWidth
-            ? typeof contentWidth === 'number'
-              ? `${contentWidth}px`
-              : contentWidth
-            : null,
-          contentAlign,
-          LinkComponent,
-          inlinePlugins,
-          components,
-          preparedPlugins,
-          t,
-          headingProjection,
-        ),
-      )}
+      {renderedBlocks}
     </div>
   );
 

package/src/MultiSelector/MultiSelector.disabledFocus.a11y.chromium.spec.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MultiSelector.disabledFocus.a11y.chromium.spec.ts
+ * @input The `Core/MultiSelector` Default story in a built Storybook.
+ * @output Real-engine proof of `spec:AST-085` FR4: a trigger disabled while it
+ *   holds keyboard focus keeps focus and reports itself disabled.
+ * @position Run with `pnpm test:a11y-contract`; a DOM emulator does not move
+ *   focus off an element that becomes disabled, so it cannot show the loss.
+ */
+
+import {expect, test} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+test('a focused trigger keeps focus when it becomes disabled', async ({
+  page,
+}) => {
+  const storyId = 'core-multiselector--default';
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`,
+  );
+  const trigger = page.getByRole('combobox', {name: 'Columns'});
+  await trigger.focus();
+  await expect(trigger).toBeFocused();
+
+  await page.evaluate(id => {
+    const channel = (
+      window as unknown as {
+        __STORYBOOK_ADDONS_CHANNEL__?: {
+          emit: (event: string, payload: unknown) => void;
+        };
+      }
+    ).__STORYBOOK_ADDONS_CHANNEL__;
+    if (channel == null) {
+      throw new Error('Storybook channel is unavailable');
+    }
+    channel.emit('updateStoryArgs', {
+      storyId: id,
+      updatedArgs: {isDisabled: true},
+    });
+  }, storyId);
+
+  // Wait for the disabled re-render in either form, so focus is checked
+  // after it lands.
+  await expect
+    .poll(async () =>
+      trigger.evaluate(
+        el =>
+          el.hasAttribute('disabled') ||
+          el.getAttribute('aria-disabled') === 'true',
+      ),
+    )
+    .toBe(true);
+  await expect(trigger).toBeFocused();
+});

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.',
       },
     ],
   },