@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/src/Table/tableContextMenu.test.tsx

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file tableContextMenu.test.tsx
+ * @output Tests for the Table context-menu system
+ * @position Validates contextMenuActions aggregation + header context menus
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {Table} from './Table';
+import type {TablePlugin, TableColumn} from './types';
+import {resolveContextActions} from './tableContextMenu';
+
+// jsdom doesn't implement the Popover API; mirror the ContextMenu test's mock
+// so the menu can "open" and its items become queryable (as hidden).
+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);
+  };
+});
+
+interface Row extends Record<string, unknown> {
+  id: string;
+  name: string;
+}
+
+const data: Row[] = [
+  {id: '1', name: 'Alice'},
+  {id: '2', name: 'Bob'},
+];
+
+const columns: TableColumn<Row>[] = [
+  {key: 'name', header: 'Name'},
+  {key: 'id', header: 'ID'},
+];
+
+// =============================================================================
+// contextMenuActions via transformHeaderCell
+// =============================================================================
+
+describe('Table header context menu', () => {
+  it('renders a menu from a plugin that sets contextMenuActions', () => {
+    const onSelect = vi.fn();
+    const plugin: TablePlugin<Row> = {
+      transformHeaderCell: props => ({
+        ...props,
+        contextMenuActions: [{id: 'pin', label: 'Pin column', onSelect}],
+      }),
+    };
+    render(
+      <Table data={data} columns={columns} idKey="id" plugins={{plugin}} />,
+    );
+    fireEvent.contextMenu(screen.getByText('Name'));
+    const items = screen.getAllByRole('menuitem', {
+      name: 'Pin column',
+      hidden: true,
+    });
+    expect(items.length).toBeGreaterThan(0);
+    fireEvent.click(items[0]);
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+
+  it('concatenates actions from multiple plugins (never overridden)', () => {
+    const a: TablePlugin<Row> = {
+      transformHeaderCell: props => ({
+        ...props,
+        contextMenuActions: [
+          ...resolveContextActions(props.contextMenuActions),
+          {id: 'a', label: 'Action A', onSelect: () => {}},
+        ],
+      }),
+    };
+    const b: TablePlugin<Row> = {
+      transformHeaderCell: props => ({
+        ...props,
+        contextMenuActions: [
+          ...resolveContextActions(props.contextMenuActions),
+          {id: 'b', label: 'Action B', onSelect: () => {}},
+        ],
+      }),
+    };
+    render(
+      <Table data={data} columns={columns} idKey="id" plugins={{a, b}} />,
+    );
+    fireEvent.contextMenu(screen.getByText('Name'));
+    expect(
+      screen.getAllByRole('menuitem', {name: 'Action A', hidden: true}).length,
+    ).toBeGreaterThan(0);
+    expect(
+      screen.getAllByRole('menuitem', {name: 'Action B', hidden: true}).length,
+    ).toBeGreaterThan(0);
+  });
+
+  it('does not render a menu when no plugin contributes actions', () => {
+    render(<Table data={data} columns={columns} idKey="id" />);
+    fireEvent.contextMenu(screen.getByText('Name'));
+    expect(
+      screen.queryByRole('menuitem', {hidden: true}),
+    ).not.toBeInTheDocument();
+  });
+});
+
+// =============================================================================
+// Body / row context menu
+// =============================================================================
+
+describe('Table body context menu', () => {
+  it('renders row actions from a plugin that sets contextMenuActions in transformBodyCell', () => {
+    const onSelect = vi.fn();
+    const plugin: TablePlugin<Row> = {
+      transformBodyCell: (props, _column, item) => ({
+        ...props,
+        contextMenuActions: [
+          {
+            id: `delete-${item.id}`,
+            label: 'Delete row',
+            onSelect: () => {
+              onSelect(item.id);
+            },
+          },
+        ],
+      }),
+    };
+    render(
+      <Table data={data} columns={columns} idKey="id" plugins={{plugin}} />,
+    );
+    // Right-click the first body cell (Alice).
+    fireEvent.contextMenu(screen.getByText('Alice'));
+    const items = screen.getAllByRole('menuitem', {
+      name: 'Delete row',
+      hidden: true,
+    });
+    expect(items.length).toBeGreaterThan(0);
+    fireEvent.click(items[0]);
+    expect(onSelect).toHaveBeenCalledWith('1');
+  });
+});

package/src/Table/tableContextMenu.tsx

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file tableContextMenu.tsx
+ * @input React, ContextMenu, Icon, types
+ * @output wrapInTableContextMenu helper
+ * @position Renders the aggregated `contextMenuActions` for a header cell / row
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/BaseTable.tsx (call sites)
+ * - /packages/core/src/Table/types.ts (TableContextAction)
+ */
+
+import {useState, type ReactNode} from 'react';
+import {ContextMenu, type ContextMenuOption} from '../ContextMenu';
+import {Icon} from '../Icon';
+import type {TableContextAction, TableContextActions} from './types';
+
+/**
+ * Resolve a `contextMenuActions` value (array or getter) to a plain array.
+ * Use this when composing actions from a prior plugin's render props so you
+ * don't have to branch on the array-vs-getter form:
+ *
+ * ```
+ * contextMenuActions: () => [
+ *   ...resolveContextActions(props.contextMenuActions),
+ *   ...myActions,
+ * ]
+ * ```
+ */
+export function resolveContextActions(
+  actions: TableContextActions | undefined,
+): TableContextAction[] {
+  if (typeof actions === 'function') {
+    return actions();
+  }
+  return actions ?? [];
+}
+
+/**
+ * Convert the flat action list into ContextMenu options, inserting a divider
+ * between groups (first-seen group order). Ungrouped actions form a trailing
+ * group. A `checked` action shows a trailing check icon.
+ */
+function toContextMenuOptions(
+  actions: TableContextAction[],
+): ContextMenuOption[] {
+  const order: string[] = [];
+  const buckets = new Map<string, TableContextAction[]>();
+  for (const action of actions) {
+    const key = action.group ?? '__ungrouped__';
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = [];
+      buckets.set(key, bucket);
+      order.push(key);
+    }
+    bucket.push(action);
+  }
+
+  const options: ContextMenuOption[] = [];
+  order.forEach((key, groupIndex) => {
+    if (groupIndex > 0) {
+      options.push({type: 'divider'});
+    }
+    for (const action of buckets.get(key) ?? []) {
+      options.push({
+        label: typeof action.label === 'string' ? action.label : action.id,
+        // A checked action (e.g. the active sort direction) shows a checkmark;
+        // otherwise the action's own icon. ContextMenu's data form takes a
+        // single leading icon, so checked state replaces the icon.
+        icon: action.checked ? (
+          <Icon icon="check" size="xsm" aria-hidden />
+        ) : (
+          action.icon
+        ),
+        isDisabled: action.disabled,
+        onClick: action.onSelect,
+      });
+    }
+  });
+  return options;
+}
+
+/**
+ * Wrap a table element (a header cell's content or a row) in a right-click
+ * context menu rendering the aggregated `actions`. When no plugin contributes
+ * actions the element is returned untouched so the native browser menu passes
+ * through.
+ */
+/**
+ * A context menu whose actions are resolved lazily — only when the user opens
+ * the menu (right-click). Deferring the work means plugins that pass a getter
+ * don't build an action array (with its closures) for every cell on every
+ * render; it's computed on demand and memoized until the menu closes.
+ */
+function LazyTableContextMenu({
+  element,
+  getActions,
+}: {
+  element: ReactNode;
+  getActions: () => TableContextAction[];
+}): ReactNode {
+  const [options, setOptions] = useState<ContextMenuOption[] | null>(null);
+  return (
+    <ContextMenu
+      items={options ?? []}
+      onOpenChange={open => {
+        // Resolve actions when opening; clear on close so state derived later
+        // (e.g. current sort direction) is always fresh next open.
+        setOptions(open ? toContextMenuOptions(getActions()) : null);
+      }}>
+      {element}
+    </ContextMenu>
+  );
+}
+
+/**
+ * Wrap a table element (a header cell's content or a body cell) in a right-click
+ * context menu rendering the aggregated `actions`. Accepts a static array or a
+ * getter (resolved lazily on open). When there are no actions the element is
+ * returned untouched so the native browser menu passes through.
+ */
+export function wrapInTableContextMenu(
+  element: ReactNode,
+  actions: TableContextActions | undefined,
+): ReactNode {
+  // Getter form → resolve lazily on open.
+  if (typeof actions === 'function') {
+    return <LazyTableContextMenu element={element} getActions={actions} />;
+  }
+  if (!actions || actions.length === 0) {
+    return element;
+  }
+  // item (it looked like "ascending" was always selected). Focus moves only
+  // when the user arrow-keys into the menu.
+  return (
+    <ContextMenu items={toContextMenuOptions(actions)}>{element}</ContextMenu>
+  );
+}

package/src/Table/types.ts

@@ -261,6 +261,12 @@ export interface HeaderCellRenderProps {
   overlay?: ReactNode;
   /** Content rendered below the header label row (e.g. inline filter controls). */
   below?: ReactNode;
+  /**
+   * Right-click context-menu actions for this header cell. Plugins append
+   * their actions in `transformHeaderCell`; BaseTable concatenates the arrays
+   * across plugins (never overridden) and renders one menu per header cell.
+   */
+  contextMenuActions?: TableContextActions;
   /**
    * Index of this column within the final, ordered list of rendered columns
    * (after column injection/reordering by other plugins). Populated by
@@ -290,6 +296,13 @@ export interface BodyRowRenderProps {
 export interface BodyCellRenderProps {
   htmlProps: TdHTMLAttributes<HTMLTableCellElement>;
   styles: StyleXStyles[];
+  /**
+   * Right-click context-menu actions for this body cell. Plugins append their
+   * actions in `transformBodyCell`; BaseTable concatenates the arrays across
+   * plugins and across the row's cells (never overridden) and renders one menu
+   * per row.
+   */
+  contextMenuActions?: TableContextActions;
   /**
    * Index of this cell's column within the final ordered column list.
    * Mirrors the `columnIndex` passed to `transformHeaderCell`. Populated by
@@ -335,6 +348,50 @@ export interface ScrollWrapperRenderProps {
   afterTable?: ReactNode;
 }
 
+// =============================================================================
+// Context-menu actions
+// =============================================================================
+
+/**
+ * A single right-click context-menu action contributed by a plugin.
+ *
+ * Plugins contribute actions via the `contextMenuActions` field on
+ * `HeaderCellRenderProps` / `BodyCellRenderProps` (set in
+ * `transformHeaderCell` / `transformBodyCell`); the table aggregates actions
+ * from every enabled plugin into a single menu per header cell / row.
+ */
+export interface TableContextAction {
+  /** Stable identifier, unique within a single menu. */
+  id: string;
+  /** Visible label for the menu item. */
+  label: ReactNode;
+  /** Optional leading icon. */
+  icon?: ReactNode;
+  /** Invoked when the item is selected. */
+  onSelect: () => void;
+  /** When true, the item is rendered but not selectable. */
+  disabled?: boolean;
+  /**
+   * Group key used to cluster related actions and insert a divider between
+   * groups (e.g. 'sort', 'selection'). Actions without a group form a trailing
+   * group. Group order follows first-seen order across the aggregated list.
+   */
+  group?: string;
+  /** When true, the item renders as checked (e.g. the active sort direction). */
+  checked?: boolean;
+}
+
+/**
+ * Context-menu actions for a cell — either a static array, or a getter that
+ * returns the actions lazily. Prefer the getter for actions derived from state
+ * (e.g. the active sort direction): it's only invoked when the menu is opened,
+ * so the plugin doesn't build an action array (with closures) for every cell on
+ * every render.
+ */
+export type TableContextActions =
+  | TableContextAction[]
+  | (() => TableContextAction[]);
+
 // =============================================================================
 // Plugin Interface
 // =============================================================================
@@ -353,6 +410,10 @@ export interface ScrollWrapperRenderProps {
  * 6. `transformBodyCell` — transform each body `<td>` props
  * 7. `transformScrollWrapper` — transform the scroll-container wrapper around the table
  * 8. `transformTableContext` — wrap the table output in context providers
+ *
+ * Plugins may also contribute right-click menu actions by appending to
+ * `contextMenuActions` in `transformHeaderCell` / `transformBodyCell`
+ * (aggregated into one menu per header cell / row).
  */
 export interface TablePlugin<
   T extends Record<string, unknown> = Record<string, unknown>,
@@ -432,12 +493,25 @@ export interface TableRowComponentProps extends HTMLAttributes<HTMLTableRowEleme
 export interface TableCellComponentProps extends TdHTMLAttributes<HTMLTableCellElement> {
   children?: ReactNode;
   xstyle?: StyleXStyles | StyleXStyles[];
+  /**
+   * Right-click actions to render as a context menu around the cell content.
+   * The cell owns the menu wrapper so it can control how it interacts with
+   * padding / content sizing. Empty/undefined renders no menu (native passes
+   * through).
+   */
+  contextMenuActions?: TableContextActions;
 }
 
 /** Props for header cell components used in the components prop */
 export interface TableHeaderCellComponentProps extends ThHTMLAttributes<HTMLTableCellElement> {
   children?: ReactNode;
   xstyle?: StyleXStyles | StyleXStyles[];
+  /**
+   * Right-click actions to render as a context menu around the header content.
+   * The cell owns the menu wrapper so it can control how it interacts with
+   * padding / content sizing. Empty/undefined renders no menu.
+   */
+  contextMenuActions?: TableContextActions;
 }
 
 // =============================================================================

package/src/Table/useTableColumnResize.doc.mjs

@@ -19,7 +19,7 @@ export const docs = {
       name: 'onColumnResizeEnd',
       type: '(updates: Record<string, number>) => void',
       description:
-        'Called when a resize completes (pointerup / Enter). Receives a map of every column key whose width changed — merge it into your columnWidths state.',
+        'Called when a resize completes (pointerup / Enter). Receives a map of every column key whose width changed; merge it into your columnWidths state.',
     },
     {
       name: 'minWidth',
@@ -37,7 +37,7 @@ export const docs = {
       name: 'columns',
       type: 'TableColumn<T>[]',
       description:
-        'Column definitions — needed to derive per-column min widths and detect proportional vs pixel columns for neighbor/last-column resize behavior.',
+        'Column definitions, needed to derive per-column min widths and detect proportional vs pixel columns for neighbor/last-column resize behavior.',
     },
   ],
 };
@@ -91,6 +91,6 @@ export const docsDense = {
     minWidth: 'Global min column width (px) during resize.',
     maxWidth: 'Global max column width (px) during resize. Default Infinity.',
     columns:
-      'Column defs — derive per-column mins + proportional/pixel detection for neighbor/last-column behavior.',
+      'Column defs: derive per-column mins + proportional/pixel detection for neighbor/last-column behavior.',
   },
 };

package/src/Table/useTableStickyColumns.doc.mjs

@@ -13,13 +13,13 @@ export const docs = {
       name: 'startKeys',
       type: 'string[]',
       description:
-        'Column keys pinned to the start (inline-start / left in LTR) edge — the contiguous run from the first column through the last listed key.',
+        'Column keys pinned to the start (inline-start / left in LTR) edge: the contiguous run from the first column through the last listed key.',
     },
     {
       name: 'endKeys',
       type: 'string[]',
       description:
-        'Column keys pinned to the end (inline-end / right in LTR) edge — the contiguous run from the first listed key through the last column.',
+        'Column keys pinned to the end (inline-end / right in LTR) edge: the contiguous run from the first listed key through the last column.',
     },
   ],
 };

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