@astryxdesign/core 0.1.2 → 0.1.3-canary.1e94ba0

package/src/Text/Text.doc.mjs

@@ -124,15 +124,15 @@ export const docs = {
     description:
       'Text renders styled body text and headings from the theme. Use Text with a semantic type for body copy, labels, and captions, and Heading for section titles that output the correct h1\u2013h6 element.',
     bestPractices: [
-      { guidance: true, description: 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight \u2014 the theme handles the details.' },
+      { guidance: true, description: 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.' },
       { guidance: true, description: 'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.' },
-      { guidance: true, description: 'Use maxLines with a number to truncate long content \u2014 a tooltip appears automatically on hover so no text is lost.' },
+      { guidance: true, description: 'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.' },
       { guidance: true, description: 'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.' },
-      { guidance: false, description: 'Override size and weight when a semantic type already matches \u2014 extra overrides fight the theme and break when themes change.' },
-      { guidance: false, description: 'Skip heading levels in the document outline \u2014 go h1 then h2 then h3, never h1 then h3.' },
-      { guidance: false, description: 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text \u2014 Text and Heading apply the correct theme tokens automatically.' },
-      { guidance: false, description: 'Pass a `variant` prop \u2014 Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.' },
-      { guidance: false, description: 'Use Text for headings \u2014 use Heading with a `level` prop (1\u20136) for section titles and headings.' },
+      { guidance: false, description: 'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.' },
+      { guidance: false, description: 'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.' },
+      { guidance: false, description: 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.' },
+      { guidance: false, description: 'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.' },
+      { guidance: false, description: 'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.' },
     ],
   },
 };
@@ -143,15 +143,15 @@ export const docsZh = {
     description:
       'Text renders styled body text and headings from the theme. Use Text with a semantic type for body copy, labels, and captions, and Heading for section titles that output the correct h1\u2013h6 element.',
     bestPractices: [
-      { guidance: true, description: 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight \u2014 the theme handles the details.' },
+      { guidance: true, description: 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.' },
       { guidance: true, description: 'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.' },
-      { guidance: true, description: 'Use maxLines with a number to truncate long content \u2014 a tooltip appears automatically on hover so no text is lost.' },
+      { guidance: true, description: 'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.' },
       { guidance: true, description: 'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.' },
-      { guidance: false, description: 'Override size and weight when a semantic type already matches \u2014 extra overrides fight the theme and break when themes change.' },
-      { guidance: false, description: 'Skip heading levels in the document outline \u2014 go h1 then h2 then h3, never h1 then h3.' },
-      { guidance: false, description: 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text \u2014 Text and Heading apply the correct theme tokens automatically.' },
-      { guidance: false, description: 'Pass a `variant` prop \u2014 Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.' },
-      { guidance: false, description: 'Use Text for headings \u2014 use Heading with a `level` prop (1\u20136) for section titles and headings.' },
+      { guidance: false, description: 'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.' },
+      { guidance: false, description: 'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.' },
+      { guidance: false, description: 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.' },
+      { guidance: false, description: 'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.' },
+      { guidance: false, description: 'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.' },
     ],
   },
 };
@@ -165,12 +165,12 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Semantic type (body, label, supporting, large, code) instead of manual size/weight.' },
       { guidance: true, description: 'accessibilityLevel on Heading when visual level differs from document outline.' },
-      { guidance: true, description: 'maxLines for truncation \u2014 tooltip shows full text on hover.' },
+      { guidance: true, description: 'maxLines for truncation; tooltip shows full text on hover.' },
       { guidance: true, description: 'hasTabularNumbers for aligned numeric columns.' },
       { guidance: false, description: 'Override size/weight when a semantic type already matches.' },
-      { guidance: false, description: 'Skip heading levels \u2014 sequential h1 \u2192 h2 \u2192 h3.' },
-      { guidance: false, description: 'Raw <p>/<h1>/<span> \u2014 use Text/Heading for theme tokens.' },
-      { guidance: false, description: '`variant` prop \u2014 does not exist. Use `type` for text styling or Heading for headings.' },
+      { guidance: false, description: 'Skip heading levels; sequential h1 \u2192 h2 \u2192 h3.' },
+      { guidance: false, description: 'Raw <p>/<h1>/<span>; use Text/Heading for theme tokens.' },
+      { guidance: false, description: '`variant` prop, which does not exist. Use `type` for text styling or Heading for headings.' },
       { guidance: false, description: 'Text for headings: use Heading with level (1\u20136).' },
     ],
   },

package/src/TextArea/TextArea.doc.mjs

@@ -70,6 +70,12 @@ export const docs = {
       description: 'Disables the textarea, preventing interaction.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -174,6 +180,7 @@ export const docs = {
       { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.' },
       { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.' },
       { guidance: false, description: 'Don\'t show a status message without also setting the status type; the colored border and icon are what draw the user\'s attention to the message.' },
+      { guidance: false, description: 'Don\'t wrap a disabled TextArea in Tooltip to explain why it\'s disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -239,6 +246,12 @@ export const docsZh = {
       description: '禁用文本域，阻止交互。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明文本域被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持文本域可聚焦（字段变为只读）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TextArea。',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -336,6 +349,7 @@ export const docsZh = {
       { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.' },
       { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.' },
       { guidance: false, description: 'Don\'t show a status message without also setting the status type; the colored border and icon are what draw the user\'s attention to the message.' },
+      { guidance: false, description: 'Don\'t wrap a disabled TextArea in Tooltip to explain why it\'s disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -354,6 +368,7 @@ export const docsDense = {
       { guidance: false, description: 'Avoid TextArea for single-line values; use TextInput.' },
       { guidance: false, description: 'Don\'t use placeholder as only label; disappears on focus, not accessible.' },
       { guidance: false, description: 'Don\'t show status message without status type; border and icon draw attention.' },
+      { guidance: false, description: 'Don\'t wrap a disabled TextArea in Tooltip to explain the disabled state; use the disabledMessage prop instead.' },
     ],
   },
   propDescriptions: {
@@ -367,6 +382,8 @@ export const docsDense = {
     isOptional: 'Shows "Optional" indicator. Mutually exclusive w/ isRequired.',
     isRequired: 'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',
     isDisabled: 'Disables textarea, prevents interaction.',
+    disabledMessage:
+      'Explains why textarea is disabled. With isDisabled, shows tooltip on hover/focus + keeps textarea focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled TextArea in Tooltip.',
     isLoading: 'Loading state w/ spinner inside input.',
     placeholder: 'Placeholder when textarea empty.',
     rows: 'Visible text rows.',

package/src/TextArea/TextArea.test.tsx

@@ -10,12 +10,43 @@
  */
 
 import {useState} from 'react';
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
 import {TextArea} from './TextArea';
 
+// Mock showPopover/hidePopover since jsdom does not implement them. Used by the
+// disabledMessage tooltip.
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
+// jsdom popover content is in the DOM but may not be "visible" in the
+// accessibility tree. Use hidden: true to find it.
+const h = {hidden: true} as const;
+
 describe('TextArea', () => {
   it('renders with label', () => {
     render(<TextArea label="Description" value="" onChange={() => {}} />);
@@ -39,9 +70,7 @@ describe('TextArea', () => {
   it('calls onChange with value and event when typing', async () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
-    render(
-      <TextArea label="Description" value="" onChange={handleChange} />,
-    );
+    render(<TextArea label="Description" value="" onChange={handleChange} />);
 
     const textarea = screen.getByRole('textbox');
     await user.type(textarea, 'Hi');
@@ -73,24 +102,14 @@ describe('TextArea', () => {
   it('forwards ref correctly', () => {
     const ref = vi.fn();
     render(
-      <TextArea
-        ref={ref}
-        label="Description"
-        value=""
-        onChange={() => {}}
-      />,
+      <TextArea ref={ref} label="Description" value="" onChange={() => {}} />,
     );
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLTextAreaElement));
   });
 
   it('visually hides label when isLabelHidden is true', () => {
     render(
-      <TextArea
-        label="Comments"
-        isLabelHidden
-        value=""
-        onChange={() => {}}
-      />,
+      <TextArea label="Comments" isLabelHidden value="" onChange={() => {}} />,
     );
     const label = screen.getByText('Comments');
     expect(label).toBeInTheDocument();
@@ -133,12 +152,7 @@ describe('TextArea', () => {
 
   it('is disabled when isDisabled is true', () => {
     render(
-      <TextArea
-        label="Description"
-        isDisabled
-        value=""
-        onChange={() => {}}
-      />,
+      <TextArea label="Description" isDisabled value="" onChange={() => {}} />,
     );
     expect(screen.getByRole('textbox')).toBeDisabled();
   });
@@ -150,12 +164,7 @@ describe('TextArea', () => {
 
   it('shows aria-busy when isLoading is true', () => {
     render(
-      <TextArea
-        label="Description"
-        isLoading
-        value=""
-        onChange={() => {}}
-      />,
+      <TextArea label="Description" isLoading value="" onChange={() => {}} />,
     );
     expect(screen.getByRole('textbox')).toHaveAttribute('aria-busy', 'true');
     expect(screen.getByRole('textbox')).not.toBeDisabled();
@@ -340,12 +349,7 @@ describe('TextArea', () => {
 
   it('renders with size="lg"', () => {
     render(
-      <TextArea
-        label="Description"
-        value=""
-        onChange={() => {}}
-        size="lg"
-      />,
+      <TextArea label="Description" value="" onChange={() => {}} size="lg" />,
     );
     expect(screen.getByLabelText('Description')).toBeInTheDocument();
   });
@@ -595,4 +599,132 @@ describe('TextArea', () => {
       expect(textarea).toHaveFocus();
     });
   });
+
+  describe('disabledMessage', () => {
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <TextArea
+          label="Notes"
+          value=""
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const textarea = screen.getByRole('textbox');
+      const container = textarea.parentElement as HTMLElement;
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('You need the Editor role');
+
+      fireEvent.mouseEnter(container);
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+
+      fireEvent.mouseLeave(container);
+      await waitFor(() => {
+        expect(tooltip).not.toHaveAttribute('popover-open');
+      });
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <TextArea
+          label="Notes"
+          value=""
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('textbox')).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <TextArea
+          label="Notes"
+          value=""
+          onChange={() => {}}
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <TextArea label="Notes" value="" onChange={() => {}} isDisabled />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the textarea focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <TextArea
+          label="Notes"
+          value=""
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const textarea = screen.getByRole('textbox');
+      expect(textarea).not.toBeDisabled();
+      expect(textarea).toHaveAttribute('aria-disabled', 'true');
+      expect(textarea).toHaveAttribute('readonly');
+    });
+
+    it('links the reason tooltip from the textarea via aria-describedby', () => {
+      render(
+        <TextArea
+          label="Notes"
+          value=""
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const textarea = screen.getByRole('textbox');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(textarea.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks value changes while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <TextArea
+          label="Notes"
+          value=""
+          onChange={onChange}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const textarea = screen.getByRole('textbox');
+      await user.click(textarea);
+      await user.keyboard('hello');
+      expect(onChange).not.toHaveBeenCalled();
+      expect(textarea).toHaveValue('');
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(
+        <TextArea label="Notes" value="" onChange={() => {}} isDisabled />,
+      );
+      const textarea = screen.getByRole('textbox');
+      expect(textarea).toBeDisabled();
+      expect(textarea).not.toHaveAttribute('aria-disabled');
+    });
+  });
 });

package/src/TextArea/TextArea.tsx

@@ -43,12 +43,14 @@ import {
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
+import {useTooltip} from '../Tooltip';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 const COUNTER_WARNING_THRESHOLD = 0.8;
 
@@ -93,17 +95,6 @@ const styles = stylex.create({
   counterError: {
     color: colorVars['--color-error'],
   },
-  srOnly: {
-    position: 'absolute',
-    width: '1px',
-    height: '1px',
-    padding: 0,
-    margin: '-1px',
-    overflow: 'hidden',
-    clip: 'rect(0,0,0,0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
   statusIcon: {
     position: 'absolute',
     top: spacingVars['--spacing-2'],
@@ -199,6 +190,27 @@ export interface TextAreaProps extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the textarea is disabled. When set together with
+   * `isDisabled`, the textarea shows a tooltip with this text on hover and
+   * keyboard focus, and stays focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. The field cannot be
+   * edited (it becomes read-only) while disabled.
+   *
+   * Use this instead of wrapping a disabled textarea in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <TextArea
+   *   label="Notes"
+   *   value={notes}
+   *   isDisabled
+   *   disabledMessage="Notes are locked after submission"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
   /**
    * Status indicator for the textarea.
    * When set, displays a colored border and status icon.
@@ -284,6 +296,7 @@ export function TextArea({
   placeholder,
   rows = 3,
   isDisabled = false,
+  disabledMessage,
   status,
   labelTooltip,
   startIcon,
@@ -314,6 +327,20 @@ export function TextArea({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the textarea container (which already exists)
+  // and the textarea stays perceivable via aria-disabled instead of the native
+  // disabled attribute. The field is made read-only so it can't be typed into,
+  // and value mutation is blocked by the isDisabled guard in handleChange.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the textarea, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   const statusIconMap: Record<TextAreaStatusType, IconName> = {
     warning: 'warning',
     error: 'error',
@@ -334,11 +361,18 @@ export function TextArea({
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
       maxLength != null ? counterID : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
 
   const handleChange = (e: ChangeEvent<HTMLTextAreaElement>) => {
+    // Value can't change while showing a disabled message (the field is
+    // read-only and non-native-disabled), but guard the handler too so the
+    // optimistic value and callbacks never fire.
+    if (isDisabled) {
+      return;
+    }
     const newValue = e.target.value;
     onChange?.(newValue, e);
     if (changeAction && !e.defaultPrevented) {
@@ -381,7 +415,13 @@ export function TextArea({
       labelTooltip={labelTooltip}
       width={width}>
       <div
-        ref={containerRef}
+        ref={el => {
+          containerRef.current = el;
+          // Anchor + hover/focus listeners for the disabled-message tooltip.
+          // Handlers are gated internally by isEnabled, and anchor names
+          // compose, so attaching unconditionally is safe.
+          disabledMessageTooltip.ref(el);
+        }}
         onClick={handleWrapperClick}
         onMouseUp={handleWrapperMouseUp}
         {...mergeProps(
@@ -413,7 +453,12 @@ export function TextArea({
           onBlur={onBlur}
           placeholder={placeholder}
           rows={rows}
-          disabled={isDisabled}
+          // With a disabledMessage the textarea keeps focusability via
+          // aria-disabled so the reason is focus-discoverable; readOnly + the
+          // handleChange guard keep the value from changing.
+          disabled={isDisabled && !showsDisabledMessage}
+          aria-disabled={showsDisabledMessage ? 'true' : undefined}
+          readOnly={showsDisabledMessage || undefined}
           spellCheck={hasSpellCheck}
           autoFocus={hasAutoFocus}
           data-autofocus={hasAutoFocus || undefined}
@@ -451,15 +496,17 @@ export function TextArea({
             optimisticValue.length > maxLength && styles.counterError,
           )}>
           {optimisticValue.length}/{maxLength}
-          <span aria-live="polite" {...stylex.props(styles.srOnly)}>
+          <VisuallyHidden aria-live="polite">
             {optimisticValue.length >= maxLength * COUNTER_WARNING_THRESHOLD
               ? optimisticValue.length > maxLength
                 ? `${optimisticValue.length - maxLength} characters over limit`
                 : `${maxLength - optimisticValue.length} characters remaining`
               : ''}
-          </span>
+          </VisuallyHidden>
         </div>
       )}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/TextInput/TextInput.doc.mjs

@@ -78,6 +78,12 @@ export const docs = {
         'Disables the input, preventing interaction and dimming the element.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -144,6 +150,7 @@ export const docs = {
       {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
       {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
       {guidance: false, description: "Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors."},
+      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -231,6 +238,12 @@ export const docsZh = {
         '禁用输入框，阻止交互并使元素变暗。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明输入框被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持输入框可聚焦（字段变为只读）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TextInput——已禁用的控件会吞掉外部 Tooltip 所需的悬停事件。',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -296,6 +309,7 @@ export const docsZh = {
       {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
       {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
       {guidance: false, description: "Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors."},
+      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -323,6 +337,7 @@ export const docsDense = {
       {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
       {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
       {guidance: false, description: "Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors."},
+      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -346,6 +361,8 @@ export const docsDense = {
     isOptional: 'Shows "Optional" indicator. Mutually exclusive w/ isRequired.',
     isRequired: 'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',
     isDisabled: 'Disables input, prevents interaction, dims element.',
+    disabledMessage:
+      'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps input focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled TextInput in Tooltip.',
     isLoading: 'Loading state w/ spinner+aria-busy.',
     placeholder: 'Placeholder when input empty.',
     labelTooltip: 'Tooltip in info icon at label end.',