@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/Table/Table.doc.mjs

@@ -93,6 +93,17 @@ export const docs = {
       type: 'Record<string, TablePlugin<T>>',
       description: 'Named plugins that extend table behavior via the transform pipeline. Converted to an ordered array internally.',
     },
+    {
+      name: 'rowIndexStart',
+      type: 'number',
+      description: 'ARIA row index (1-based) for the first rendered body row. The row ordinal is an accessibility concern independent of any visible index column, so setting this (or rowCount) makes the table emit aria-rowindex on body rows and aria-rowcount on the table. For a paginated/windowed view, pass the offset of the first visible row (e.g. (page - 1) * pageSize + 1) so aria-rowindex reflects position in the full dataset. Data-driven mode only.',
+      default: '1',
+    },
+    {
+      name: 'rowCount',
+      type: 'number',
+      description: 'Total number of body rows across all pages/windows, used for aria-rowcount so assistive tech can announce "row X of Y" against the full dataset. When omitted but rowIndexStart is set (windowed view with an unknown total), aria-rowcount is set to -1 per the ARIA unknown-count convention. Data-driven mode only.',
+    },
     {
       name: 'children',
       type: 'ReactNode',

package/src/Table/Table.test.tsx

@@ -1451,3 +1451,88 @@ describe('emptyState', () => {
     });
   });
 });
+
+describe('ARIA row indexing (#3939)', () => {
+  const bodyRows = (container: HTMLElement): HTMLTableRowElement[] =>
+    Array.from(container.querySelectorAll('tbody tr'));
+
+  it('emits no aria-rowindex/aria-rowcount by default', () => {
+    const {container} = render(<Table data={users} columns={columns} />);
+    expect(screen.getByRole('table')).not.toHaveAttribute('aria-rowcount');
+    for (const row of bodyRows(container)) {
+      expect(row).not.toHaveAttribute('aria-rowindex');
+    }
+  });
+
+  it('numbers rows from 1 when rowCount is provided', () => {
+    const {container} = render(
+      <Table data={users} columns={columns} rowCount={users.length} />,
+    );
+    expect(screen.getByRole('table')).toHaveAttribute(
+      'aria-rowcount',
+      String(users.length),
+    );
+    const indices = bodyRows(container).map(r =>
+      r.getAttribute('aria-rowindex'),
+    );
+    expect(indices).toEqual(['1', '2', '3']);
+  });
+
+  it('offsets aria-rowindex by rowIndexStart for a paginated view', () => {
+    // Page 3 of a 10-per-page dataset: first visible row is dataset row 21.
+    const {container} = render(
+      <Table
+        data={users}
+        columns={columns}
+        rowIndexStart={21}
+        rowCount={100}
+      />,
+    );
+    expect(screen.getByRole('table')).toHaveAttribute('aria-rowcount', '100');
+    const indices = bodyRows(container).map(r =>
+      r.getAttribute('aria-rowindex'),
+    );
+    expect(indices).toEqual(['21', '22', '23']);
+  });
+
+  it('sets aria-rowcount to -1 (unknown) when only rowIndexStart is given', () => {
+    // Windowed/cursor pagination: offset known, total unknown.
+    const {container} = render(
+      <Table data={users} columns={columns} rowIndexStart={5} />,
+    );
+    expect(screen.getByRole('table')).toHaveAttribute('aria-rowcount', '-1');
+    const indices = bodyRows(container).map(r =>
+      r.getAttribute('aria-rowindex'),
+    );
+    expect(indices).toEqual(['5', '6', '7']);
+  });
+
+  it('does not assign an ARIA row index to the header row', () => {
+    render(<Table data={users} columns={columns} rowCount={users.length} />);
+    const header = screen.getAllByRole('row')[0];
+    expect(header).not.toHaveAttribute('aria-rowindex');
+  });
+
+  it('lets a plugin override the seeded aria-rowindex', () => {
+    const plugin: TablePlugin<User> = {
+      transformBodyRow(props, _item, index) {
+        return {
+          ...props,
+          htmlProps: {...props.htmlProps, 'aria-rowindex': 100 + index},
+        };
+      },
+    };
+    const {container} = render(
+      <Table
+        data={users}
+        columns={columns}
+        rowCount={users.length}
+        plugins={{custom: plugin}}
+      />,
+    );
+    const indices = bodyRows(container).map(r =>
+      r.getAttribute('aria-rowindex'),
+    );
+    expect(indices).toEqual(['100', '101', '102']);
+  });
+});

package/src/Table/TableCell.tsx

@@ -161,12 +161,12 @@ const dividerRowStyles = stylex.create({
 
 const dividerColumnStyles = stylex.create({
   cell: {
-    borderRightWidth: {
+    borderInlineEndWidth: {
       default: borderVars['--border-width'],
       ':last-child': '0',
     },
-    borderRightStyle: 'solid',
-    borderRightColor: colorVars['--color-border'],
+    borderInlineEndStyle: 'solid',
+    borderInlineEndColor: colorVars['--color-border'],
   },
 });
 

package/src/Table/TableHeaderCell.tsx

@@ -91,12 +91,12 @@ const headerDividerStyles = stylex.create({
 
 const dividerColumnStyles = stylex.create({
   cell: {
-    borderRightWidth: {
+    borderInlineEndWidth: {
       default: borderVars['--border-width'],
       ':last-child': '0',
     },
-    borderRightStyle: 'solid',
-    borderRightColor: colorVars['--color-border'],
+    borderInlineEndStyle: 'solid',
+    borderInlineEndColor: colorVars['--color-border'],
   },
 });
 

package/src/Table/plugins/groupedRows/useTableGroupedRows.tsx

@@ -20,6 +20,7 @@ import {
   fontWeightVars,
 } from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
+import {rtlStyles} from '../../../utils';
 import type {TablePlugin} from '../../types';
 import {useTranslator} from '../../../i18n';
 
@@ -333,12 +334,14 @@ export function useTableGroupedRows<T extends Record<string, unknown>>(
                         })
                   }
                   aria-expanded={!collapsed}>
-                  <span
-                    {...stylex.props(
-                      styles.chevronIcon,
-                      !collapsed && styles.chevronExpanded,
-                    )}>
-                    <Icon icon="chevronRight" size="xsm" />
+                  <span {...stylex.props(rtlStyles.mirror)}>
+                    <span
+                      {...stylex.props(
+                        styles.chevronIcon,
+                        !collapsed && styles.chevronExpanded,
+                      )}>
+                      <Icon icon="chevronRight" size="xsm" />
+                    </span>
                   </span>
                 </button>
                 {content}

package/src/Table/plugins/rowExpansion/useTableRowExpansion.test.tsx

@@ -9,6 +9,7 @@ import {
   useTableRowExpansion,
   useTableRowExpansionState,
 } from './useTableRowExpansion';
+import {InternationalizationProvider} from '../../../i18n';
 
 // popover mock for context-menu tests
 beforeEach(() => {
@@ -118,6 +119,24 @@ describe('useTableRowExpansion', () => {
     expect(items.length).toBeGreaterThan(0);
   });
 
+  it('localizes the context-menu action label through the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {'@astryx.tableRowExpansion.expandRow': 'Développer la ligne'},
+        }}>
+        <Harness />
+      </InternationalizationProvider>,
+    );
+    fireEvent.contextMenu(screen.getByText('Folder A'));
+    const items = screen.getAllByRole('menuitem', {
+      name: /Développer la ligne/,
+      hidden: true,
+    });
+    expect(items.length).toBeGreaterThan(0);
+  });
+
   it('does not show chevron for leaf nodes', () => {
     render(<Harness />);
     // Leaf C has no children

package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx

@@ -16,6 +16,7 @@ import {useCallback, useMemo, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, colorVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
+import {rtlStyles} from '../../../utils';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator} from '../../../i18n';
 import type {
@@ -361,12 +362,14 @@ function ExpansionChevron({
       }}
       aria-label={ariaLabel}
       aria-expanded={isExpanded}>
-      <span
-        {...stylex.props(
-          expansionStyles.chevronIcon,
-          isExpanded && expansionStyles.chevronExpanded,
-        )}>
-        <Icon icon="chevronRight" size="xsm" />
+      <span {...stylex.props(rtlStyles.mirror)}>
+        <span
+          {...stylex.props(
+            expansionStyles.chevronIcon,
+            isExpanded && expansionStyles.chevronExpanded,
+          )}>
+          <Icon icon="chevronRight" size="xsm" />
+        </span>
       </span>
     </button>
   );
@@ -533,12 +536,14 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                     ? t('@astryx.tableRowExpansion.collapseAllRows')
                     : t('@astryx.tableRowExpansion.expandAllRows')
                 }>
-                <span
-                  {...stylex.props(
-                    expansionStyles.chevronIcon,
-                    allExpanded && expansionStyles.chevronExpanded,
-                  )}>
-                  <Icon icon="chevronRight" size="xsm" />
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <span
+                    {...stylex.props(
+                      expansionStyles.chevronIcon,
+                      allExpanded && expansionStyles.chevronExpanded,
+                    )}>
+                    <Icon icon="chevronRight" size="xsm" />
+                  </span>
                 </span>
               </button>
             ),
@@ -571,13 +576,17 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
             {
               id: 'row-expansion-toggle',
               group: 'row-expansion',
-              label: isExpanded ? 'Collapse row' : 'Expand row',
+              label: isExpanded
+                ? t('@astryx.tableRowExpansion.collapseRow')
+                : t('@astryx.tableRowExpansion.expandRow'),
               icon: (
-                <Icon
-                  icon={isExpanded ? 'chevronDown' : 'chevronRight'}
-                  size="xsm"
-                  aria-hidden
-                />
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <Icon
+                    icon={isExpanded ? 'chevronDown' : 'chevronRight'}
+                    size="xsm"
+                    aria-hidden
+                  />
+                </span>
               ),
               onSelect: () => onToggle(key),
             },

package/src/Table/plugins/selection/useTableSelection.test.tsx

@@ -7,13 +7,13 @@
  * @position Test file; validates selection behavior (checkboxes, aria, select-all)
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {useState} from 'react';
-import {render, screen, within} from '@testing-library/react';
+import {act, render, renderHook, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Table} from '../../Table';
 import {useTableSelection} from './useTableSelection';
-import type {TableColumn} from '../../types';
+import type {BodyRowRenderProps, TableColumn} from '../../types';
 
 // =============================================================================
 // Test Data
@@ -210,4 +210,62 @@ describe('useTableSelection', () => {
     const headers = within(headerRow).getAllByRole('columnheader');
     expect(headers).toHaveLength(3);
   });
+
+  it('unsubscribes detached row refs instead of accumulating listeners', () => {
+    const getIsItemSelected = vi.fn(() => false);
+    const {result, rerender} = renderHook(() =>
+      useTableSelection<SelectableUser>({
+        getIsItemSelected,
+        onSelectItem: vi.fn(),
+        onSelectAll: vi.fn(),
+        getIsAllSelected: () => false,
+      }),
+    );
+
+    const initialProps: BodyRowRenderProps = {
+      htmlProps: {},
+      xstyle: [],
+      children: null,
+    };
+    const row = document.createElement('tr');
+    document.body.append(row);
+
+    let detach: (() => void) | undefined;
+
+    // Simulate React replacing the callback ref as this row re-renders.
+    // Each detach must unsubscribe the previous ref before the next attaches.
+    for (let i = 0; i < 3; i++) {
+      act(() => {
+        detach?.();
+      });
+
+      const transformed = result.current.transformBodyRow?.(
+        initialProps,
+        selectableUsers[0],
+        0,
+      );
+      expect(transformed?.ref).toBeTypeOf('function');
+
+      act(() => {
+        const cleanup = (
+          transformed?.ref as React.RefCallback<HTMLTableRowElement>
+        )(row);
+        expect(cleanup).toBeTypeOf('function');
+        detach = cleanup as () => void;
+      });
+    }
+
+    getIsItemSelected.mockClear();
+    rerender();
+    expect(getIsItemSelected).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      detach?.();
+    });
+    getIsItemSelected.mockClear();
+    rerender();
+    expect(getIsItemSelected).not.toHaveBeenCalled();
+
+    row.remove();
+  });
 });

package/src/Table/plugins/selection/useTableSelection.tsx

@@ -371,6 +371,9 @@ export function useTableSelection<T extends Record<string, unknown>>(
               store.getConfig().getIsItemSelected(item),
             );
           });
+          return () => {
+            unsub();
+          };
         };
 
         return {

package/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx

@@ -205,7 +205,7 @@ const stickyStyles = stylex.create({
   },
 });
 
-// Soft drop shadow over the scrolling region (matches the EPS sticky treatment).
+// Soft drop shadow over the scrolling region (a standard sticky-column shadow treatment).
 // border-collapse tables don't paint box-shadow on cells in Chromium, so it's a
 // ::after gradient strip just past the pinned edge (visible thanks to the cell's
 // overflow: visible). Opacity is gated by the scroll-state variable above.
@@ -213,7 +213,12 @@ const SHADOW_WIDTH = '6px';
 // --color-shadow is only ~10% alpha (too faint here); use a slightly stronger soft tint.
 const SHADOW_TINT = 'light-dark(rgba(0, 0, 0, 0.12), rgba(0, 0, 0, 0.32))';
 const shadowStyles = stylex.create({
-  // start-pinned: shadow falls to the right (inline-end), over scrolled content
+  // start-pinned: shadow falls toward inline-end (over scrolled content).
+  // insetInlineEnd anchors the strip to the column's inline-end edge; the strip
+  // must then be nudged one full width OUTWARD (past that edge) into the
+  // scrolled region. Outward is +X under LTR (inline-end = right) but −X under
+  // RTL (inline-end = left), and the fade must run from the pinned edge toward
+  // content in each direction — hence both transform and gradient flip on dir.
   start: {
     '::after': {
       content: '""',
@@ -222,14 +227,24 @@ const shadowStyles = stylex.create({
       bottom: 0,
       insetInlineEnd: 0,
       width: SHADOW_WIDTH,
-      transform: 'translateX(100%)',
+      transform: {
+        default: 'translateX(100%)',
+        ':is([dir="rtl"] *)': 'translateX(-100%)',
+      },
       pointerEvents: 'none',
       transition: 'opacity 150ms ease',
       opacity: `var(${SHADOW_VAR_START}, 0)`,
-      backgroundImage: `linear-gradient(to right, ${SHADOW_TINT}, transparent)`,
+      backgroundImage: {
+        default: `linear-gradient(to right, ${SHADOW_TINT}, transparent)`,
+        ':is([dir="rtl"] *)': `linear-gradient(to left, ${SHADOW_TINT}, transparent)`,
+      },
     },
   },
-  // end-pinned: shadow falls to the left (inline-start), over scrolled content
+  // end-pinned: shadow falls toward inline-start (over scrolled content).
+  // insetInlineStart anchors the strip to the column's inline-start edge; the
+  // strip is nudged one full width OUTWARD into content — −X under LTR
+  // (inline-start = left) but +X under RTL (inline-start = right) — with the
+  // gradient fading from the pinned edge toward content in each direction.
   end: {
     '::after': {
       content: '""',
@@ -238,11 +253,17 @@ const shadowStyles = stylex.create({
       bottom: 0,
       insetInlineStart: 0,
       width: SHADOW_WIDTH,
-      transform: 'translateX(-100%)',
+      transform: {
+        default: 'translateX(-100%)',
+        ':is([dir="rtl"] *)': 'translateX(100%)',
+      },
       pointerEvents: 'none',
       transition: 'opacity 150ms ease',
       opacity: `var(${SHADOW_VAR_END}, 0)`,
-      backgroundImage: `linear-gradient(to left, ${SHADOW_TINT}, transparent)`,
+      backgroundImage: {
+        default: `linear-gradient(to left, ${SHADOW_TINT}, transparent)`,
+        ':is([dir="rtl"] *)': `linear-gradient(to right, ${SHADOW_TINT}, transparent)`,
+      },
     },
   },
 });
@@ -289,16 +310,24 @@ export function useTableStickyColumns<T extends Record<string, unknown>>(
       const {hasStart: hs, hasEnd: he} = stateRef.current;
       const maxScroll = el.scrollWidth - el.clientWidth;
       const hasOverflow = maxScroll > 1;
+      // RTL-safe scroll position. Spec-compliant browsers report a NEGATIVE
+      // scrollLeft under RTL (0 at the inline-start edge, decreasing toward the
+      // inline-end edge), so a raw `scrollLeft > 1` start test would never fire
+      // and the end test would be wrong-signed. Math.abs collapses both
+      // conventions to a distance-from-inline-start, matching the repo's own
+      // useScrollOverflow (overflowStart/overflowEnd use Math.abs, tolerance 1).
+      // No-op under LTR where scrollLeft is already >= 0.
+      const pos = Math.abs(el.scrollLeft);
       if (hs) {
         el.style.setProperty(
           SHADOW_VAR_START,
-          hasOverflow && el.scrollLeft > 1 ? '1' : '0',
+          hasOverflow && pos > 1 ? '1' : '0',
         );
       }
       if (he) {
         el.style.setProperty(
           SHADOW_VAR_END,
-          hasOverflow && el.scrollLeft < maxScroll - 1 ? '1' : '0',
+          hasOverflow && pos < maxScroll - 1 ? '1' : '0',
         );
       }
     };

package/src/Table/plugins/tree/useTableTreeData.tsx

@@ -42,7 +42,7 @@ import {
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, radiusVars, spacingVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
-import {mergeRefs} from '../../../utils';
+import {mergeRefs, rtlStyles} from '../../../utils';
 import type {
   TablePlugin,
   TableColumn,
@@ -299,12 +299,14 @@ function TreeExpander({
           : t('@astryx.tableTree.expandRow')
       }
       aria-expanded={isExpanded}>
-      <span
-        {...stylex.props(
-          treeStyles.chevron,
-          isExpanded && treeStyles.chevronExpanded,
-        )}>
-        <Icon icon="chevronRight" size="xsm" />
+      <span {...stylex.props(rtlStyles.mirror)}>
+        <span
+          {...stylex.props(
+            treeStyles.chevron,
+            isExpanded && treeStyles.chevronExpanded,
+          )}>
+          <Icon icon="chevronRight" size="xsm" />
+        </span>
       </span>
     </button>
   );
@@ -346,12 +348,14 @@ function TreeExpandAllToggle({
           : t('@astryx.tableTree.expandAllRows')
       }
       aria-expanded={allExpanded}>
-      <span
-        {...stylex.props(
-          treeStyles.chevron,
-          allExpanded && treeStyles.chevronExpanded,
-        )}>
-        <Icon icon="chevronRight" size="xsm" />
+      <span {...stylex.props(rtlStyles.mirror)}>
+        <span
+          {...stylex.props(
+            treeStyles.chevron,
+            allExpanded && treeStyles.chevronExpanded,
+          )}>
+          <Icon icon="chevronRight" size="xsm" />
+        </span>
       </span>
     </button>
   );

package/src/Table/types.ts

@@ -540,6 +540,39 @@ export interface BaseTableProps<
   /** Plugins to transform render props at each level */
   plugins?: TablePlugin<T>[];
 
+  /**
+   * ARIA row index (1-based) assigned to the **first** rendered body row.
+   *
+   * The row ordinal is an accessibility concern independent of any visible
+   * index column: `aria-rowindex` on each `<tr>` should reflect the row's
+   * position in the **full** dataset, not just the current page. For a
+   * paginated / windowed view, pass the offset of the first visible row,
+   * e.g. `(page - 1) * pageSize + 1`.
+   *
+   * Setting this (or {@link rowCount}) opts the table into emitting
+   * `aria-rowindex` on body rows and `aria-rowcount` on the `<table>`. Data
+   * rows are numbered from this value; the header row keeps native table
+   * semantics and is not assigned an ARIA row index (so the visible
+   * `useTableRowIndex` numbering and `aria-rowindex` stay in agreement).
+   *
+   * Applies to data-driven mode only (ignored in children mode).
+   *
+   * @default 1
+   */
+  rowIndexStart?: number;
+  /**
+   * Total number of body rows across **all** pages/windows, used for
+   * `aria-rowcount` on the `<table>`. Provide this for paginated data so
+   * assistive tech can announce "row X of Y" against the full dataset.
+   *
+   * When omitted but {@link rowIndexStart} is set (a windowed view with an
+   * unknown total, e.g. cursor pagination), `aria-rowcount` is set to `-1`
+   * per the ARIA convention for an unknown row count.
+   *
+   * Applies to data-driven mode only (ignored in children mode).
+   */
+  rowCount?: number;
+
   /** Children mode — render `<tr>`/`<td>` directly instead of data-driven */
   children?: ReactNode;
   /**

package/src/Table/useTableRowStatus.doc.mjs

@@ -13,7 +13,7 @@ export const docs = {
       name: 'getStatus',
       type: "(item: T) => { color: 'accent' | 'success' | 'error' | 'warning' | 'red' | 'orange' | 'green' | 'yellow' | 'blue' | 'gray' | string; icon?: IconName; label: string } | null",
       description:
-        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray — mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
+        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray, each mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
       required: true,
     },
   ],

package/src/TextArea/TextArea.doc.mjs

@@ -106,6 +106,13 @@ export const docs = {
       description:
         'Status indicator that applies a colored border and icon. An optional message is displayed in a floating box below the textarea.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -147,6 +154,12 @@ export const docs = {
       description:
         'HTML name attribute for the textarea element, useful for form submissions.',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
     {
       name: 'onFocus',
       type: '(e: FocusEvent<HTMLTextAreaElement>) => void',
@@ -279,6 +292,13 @@ export const docsZh = {
       type: "{ type: 'warning' | 'error' | 'success'; message?: string }",
       description: '应用彩色边框和图标的状态指示器。可选消息显示在文本域下方的浮动框中。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -389,6 +409,7 @@ export const docsDense = {
     rows: 'Visible text rows.',
     maxLength: 'Max chars allowed. Shows counter (current/max) below textarea. No native enforcement.',
     status: 'Colored border+icon status. Optional floating message below textarea.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     labelTooltip: 'Tooltip in info icon at label end.',
     startIcon: 'Icon inside leading edge of textarea wrapper.',
     hasSpellCheck: 'Enables/disables browser spell checking.',

package/src/TextArea/TextArea.test.tsx

@@ -736,3 +736,26 @@ describe('TextArea', () => {
     });
   });
 });
+
+
+describe('TextArea statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <TextArea label="Bio" value="" onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <TextArea label="Bio" value="" onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});