@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Table/useTableSelection.doc.mjs

@@ -6,7 +6,8 @@ export const docs = {
   name: 'useTableSelection',
   subComponentOf: 'Table',
   displayName: 'useTableSelection',
-  description: 'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
+  description:
+    'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
   props: [
     {
       name: 'getIsItemSelected',
@@ -17,7 +18,8 @@ export const docs = {
     {
       name: 'onSelectItem',
       type: '(event: {item: T; isSelected: boolean}) => void',
-      description: 'Called when a row checkbox is toggled. isSelected is the new desired state.',
+      description:
+        'Called when a row checkbox is toggled. isSelected is the new desired state.',
       required: true,
     },
     {
@@ -29,33 +31,67 @@ export const docs = {
     {
       name: 'getIsAllSelected',
       type: '() => boolean',
-      description: 'Returns whether all selectable items are currently selected.',
+      description:
+        'Returns whether all selectable items are currently selected.',
       required: true,
     },
     {
       name: 'getIsIndeterminate',
       type: '() => boolean',
-      description: 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
+      description:
+        'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
     },
     {
       name: 'getIsItemSelectable',
       type: '(item: T) => boolean',
-      description: 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
+      description:
+        'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
       default: '() => true',
     },
     {
       name: 'getIsItemEnabled',
       type: '(item: T) => boolean',
-      description: 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
+      description:
+        'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
       default: '() => true',
     },
+    {
+      name: 'getRowLabel',
+      type: '(item: T) => string',
+      description:
+        'Derives a human-readable identity for a row; the row checkbox\'s hidden label becomes `Select ${getRowLabel(item)}` so screen readers announce which row each checkbox selects. Falls back to "Select row" when omitted.',
+    },
+  ],
+  examples: [
+    {
+      label: 'Accessible per-row checkbox names',
+      code: `
+const selectionPlugin = useTableSelection({
+  getIsItemSelected: item => selectedIds.has(item.id),
+  onSelectItem: ({item, isSelected}) => toggle(item.id, isSelected),
+  onSelectAll: ({isAllSelected}) => selectAll(isAllSelected),
+  getIsAllSelected: () => selectedIds.size === users.length,
+  // Screen readers announce "Select Alice", "Select Bob", ...
+  // instead of an undifferentiated "Select row" for every checkbox.
+  getRowLabel: item => item.name,
+});
+
+<Table
+  data={users}
+  columns={columns}
+  idKey="id"
+  plugins={{selection: selectionPlugin}}
+/>;
+`,
+    },
   ],
 };
 
 export const docsZh = {
   name: 'useTableSelection',
   displayName: 'useTableSelection',
-  description: '返回 TablePlugin 的 Hook，实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
+  description:
+    '返回 TablePlugin 的 Hook，实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
   props: [
     {
       name: 'getIsItemSelected',
@@ -84,12 +120,14 @@ export const docsZh = {
     {
       name: 'getIsIndeterminate',
       type: '() => boolean',
-      description: '返回选择是否为部分选中（部分但非全部）。将全选复选框渲染为不确定状态。',
+      description:
+        '返回选择是否为部分选中（部分但非全部）。将全选复选框渲染为不确定状态。',
     },
     {
       name: 'getIsItemSelectable',
       type: '(item: T) => boolean',
-      description: '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
+      description:
+        '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
       default: '() => true',
     },
     {
@@ -98,20 +136,33 @@ export const docsZh = {
       description: '返回行复选框是否可交互。禁用的行显示禁用状态的复选框。',
       default: '() => true',
     },
+    {
+      name: 'getRowLabel',
+      type: '(item: T) => string',
+      description:
+        '为行派生人类可读的标识；行复选框的隐藏标签变为 `Select ${getRowLabel(item)}`，让屏幕阅读器播报每个复选框选择的是哪一行。省略时回退为 "Select row"。',
+    },
   ],
 };
 
 export const docsDense = {
   name: 'useTableSelection',
   displayName: 'useTableSelection',
-  description: 'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
+  description:
+    'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
   propDescriptions: {
     getIsItemSelected: 'Returns whether item is selected.',
-    onSelectItem: 'Called on row checkbox toggle; isSelected = new desired state.',
+    onSelectItem:
+      'Called on row checkbox toggle; isSelected = new desired state.',
     onSelectAll: 'Called on select-all header checkbox toggle.',
     getIsAllSelected: 'Returns whether all selectable items are selected.',
-    getIsIndeterminate: 'Returns partial selection state; renders indeterminate checkbox.',
-    getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows render nothing.',
-    getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
+    getIsIndeterminate:
+      'Returns partial selection state; renders indeterminate checkbox.',
+    getIsItemSelectable:
+      'Returns whether row shows checkbox; non-selectable rows render nothing.',
+    getIsItemEnabled:
+      'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
+    getRowLabel:
+      'Derives row identity for the checkbox\'s hidden label: `Select ${getRowLabel(item)}`. Falls back to "Select row" when omitted.',
   },
 };

package/src/Table/useTableTreeData.doc.mjs

@@ -29,6 +29,29 @@ export const docs = {
         'Whether any row in the dataset is expandable. When false the plugin is a no-op: no expanders, no indent, no tree ARIA.',
       required: true,
     },
+    {
+      name: 'hasExpandAllControl',
+      type: 'boolean',
+      description:
+        'Show an expand-all/collapse-all toggle in the tree column header. Requires isAllExpanded plus onExpandAll/onCollapseAll (all supplied by useTableTreeState).',
+      default: 'false',
+    },
+    {
+      name: 'isAllExpanded',
+      type: "boolean | 'indeterminate'",
+      description:
+        'Aggregate expansion state across every expandable row, driving the header expand-all toggle. true when all are expanded, false when none are, indeterminate when some are.',
+    },
+    {
+      name: 'onExpandAll',
+      type: '() => void',
+      description: 'Expand every expandable row. Wired to the header control.',
+    },
+    {
+      name: 'onCollapseAll',
+      type: '() => void',
+      description: 'Collapse every row. Wired to the header control.',
+    },
     {
       name: 'indent',
       type: "'sm' | 'md' | 'lg'",
@@ -71,5 +94,11 @@ export const docsDense = {
     indent:
       "indent step per level: 'sm' | 'md' | 'lg' (spacing-3/4/6). Defaults to 'md'.",
     treeColumnKey: 'column carrying indent + expander. Defaults to first column.',
+    hasExpandAllControl:
+      'show expand-all/collapse-all toggle in tree column header. Needs isAllExpanded + onExpandAll/onCollapseAll (from useTableTreeState). Defaults to false.',
+    isAllExpanded:
+      "aggregate state driving the header toggle: true (all) | false (none) | 'indeterminate' (some).",
+    onExpandAll: 'expand every expandable row (header control)',
+    onCollapseAll: 'collapse every row (header control)',
   },
 };

package/src/Table/useTableTreeState.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableTreeState',
   description:
-    'State management companion for useTableTreeData. Owns the expanded set (controlled or uncontrolled) and flattens nested data into the visible row array; collapsed subtrees are unmounted, not hidden, so the table body contains exactly the visible rows. Returns expandAll/collapseAll helpers and a ready-to-use config for the tree plugin. Note: because collapsed rows unmount, cell-local React state inside collapsed subtrees is lost on collapse; lift state that must survive.',
+    'State management companion for useTableTreeData. Owns the expanded set (controlled or uncontrolled) and flattens nested data into the visible row array; collapsed subtrees are unmounted, not hidden, so the table body contains exactly the visible rows. Returns expandAll/collapseAll helpers, the aggregate isAllExpanded state (true/false/indeterminate) for a header expand-all control, and a ready-to-use config for the tree plugin. Note: because collapsed rows unmount, cell-local React state inside collapsed subtrees is lost on collapse; lift state that must survive.',
   props: [
     {
       name: 'data',
@@ -79,7 +79,7 @@ export const docsDense = {
   name: 'useTableTreeState',
   displayName: 'useTableTreeState',
   description:
-    'State companion for useTableTreeData. Owns expanded set (controlled or uncontrolled), flattens nested data to visible rows (collapsed subtrees unmounted, not hidden). Returns {visibleData, treeConfig, expandedIds, expandAll, collapseAll}. Cell-local state in collapsed subtrees is lost on collapse; lift state that must survive.',
+    'State companion for useTableTreeData. Owns expanded set (controlled or uncontrolled), flattens nested data to visible rows (collapsed subtrees unmounted, not hidden). Returns {visibleData, treeConfig, expandedIds, isAllExpanded, expandAll, collapseAll} (isAllExpanded = true/false/indeterminate for a header expand-all control). Cell-local state in collapsed subtrees is lost on collapse; lift state that must survive.',
   propDescriptions: {
     data: 'nested data; rows carry child rows under childrenKey. Flat data => plugin is a no-op.',
     idKey: 'row ID accessor: property name or fn returning unique id',

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

@@ -10,11 +10,19 @@
  */
 
 import {useState} from 'react';
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
 import {TextArea} from './TextArea';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+// FieldStatus announces status messages through the persistent useAnnounce
+// singletons; remove them between tests so role/aria-live queries in this
+// file never match a leftover region.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
 // disabledMessage tooltip.
@@ -728,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',
+    );
+  });
+});

package/src/TextArea/TextArea.tsx

@@ -27,7 +27,6 @@ import {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
 import {
   colorVars,
   spacingVars,
@@ -40,14 +39,16 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
-import {Icon, renderIconSlot, type IconType} from '../Icon';
+import {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 {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -217,6 +218,14 @@ export interface TextAreaProps extends Omit<
    * If message is provided, displays a floating message box below the textarea.
    */
   status?: TextAreaStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
    * (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
@@ -298,6 +307,7 @@ export function TextArea({
   isDisabled = false,
   disabledMessage,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   startIcon,
   hasSpellCheck = true,
@@ -341,25 +351,19 @@ export function TextArea({
     isEnabled: showsDisabledMessage,
   });
 
-  const statusIconMap: Record<TextAreaStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
-
-  const statusIconColorMap: Record<
-    TextAreaStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+    });
 
   const ariaDescribedBy =
     [
       description ? descriptionID : null,
-      status?.message ? statusMessageID : null,
+      statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+      // The tooltip variant renders no message box; describe the input by the
+      // tooltip's content instead so the status is still announced.
+      statusTooltipDescribedBy,
       maxLength != null ? counterID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
@@ -412,6 +416,7 @@ export function TextArea({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       <div
@@ -432,7 +437,9 @@ export function TextArea({
             textareaSizeStyles[size],
             effectivelyDisabled && inputWrapperStyles.disabled,
             status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
+            status &&
+              !effectivelyDisabled &&
+              inputStatusHoverShadowStyles[status.type],
             status && inputStatusFocusWithinStyles[status.type],
             xstyle,
           ),
@@ -478,14 +485,8 @@ export function TextArea({
           )}
         />
         {isBusy && <Spinner size="sm" />}
-        {status && (
-          <span {...stylex.props(styles.statusIcon)}>
-            <Icon
-              icon={statusIconMap[status.type]}
-              size="md"
-              color={statusIconColorMap[status.type]}
-            />
-          </span>
+        {statusIcon && (
+          <span {...stylex.props(styles.statusIcon)}>{statusIcon}</span>
         )}
       </div>
       {maxLength != null && (

package/src/TextInput/TextInput.doc.mjs

@@ -114,6 +114,13 @@ export const docs = {
       description:
         'Validation status: applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
     },
+    {
+      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: 'hasClear',
       type: 'boolean',
@@ -133,6 +140,12 @@ export const docs = {
       description:
         'The HTML name attribute for the input, 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.',
+    },
   ],
   theming: {
     targets: [
@@ -274,6 +287,13 @@ export const docsZh = {
       description:
         '验证状态：应用彩色边框和状态图标。如果提供了 message，在输入框下方显示浮动消息。错误类型还会设置 aria-invalid。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。',
+      default: "'attached'",
+    },
     {
       name: 'hasClear',
       type: 'boolean',
@@ -368,6 +388,7 @@ export const docsDense = {
     labelTooltip: 'Tooltip in info icon at label end.',
     startIcon: 'SVG icon at input start (e.g. heroicons or lucide).',
     status: 'Validation status; colored border+icon. Message floats below. Error sets aria-invalid.',
+    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.',
     hasClear: 'Shows clear button when input has value. Clears value on click.',
     hasAutoFocus: 'Auto-focus input on mount.',
     htmlName: 'HTML name attr for form submissions.',

package/src/TextInput/TextInput.test.tsx

@@ -13,6 +13,7 @@ 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 {TestIcon} from '../__tests__/TestIcon';
+import {InputGroup} from '../InputGroup';
 import {TextInput} from './TextInput';
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
@@ -229,6 +230,26 @@ describe('TextInput', () => {
       expect(screen.getByText('Invalid email address')).toBeInTheDocument();
     });
 
+    it('has no dangling aria-describedby ids inside InputGroup (WCAG 1.3.1)', () => {
+      // Inside an InputGroup no Field renders, so the status message element
+      // does not exist; aria-describedby must not reference its id.
+      render(
+        <InputGroup label="Contact">
+          <TextInput
+            label="Email"
+            value=""
+            onChange={() => {}}
+            status={{type: 'error', message: 'Invalid email address'}}
+          />
+        </InputGroup>,
+      );
+      const input = screen.getByRole('textbox');
+      const describedBy = input.getAttribute('aria-describedby') ?? '';
+      for (const idToken of describedBy.split(/\s+/).filter(Boolean)) {
+        expect(document.getElementById(idToken)).not.toBeNull();
+      }
+    });
+
     it('does not render status message when not provided', () => {
       render(
         <TextInput
@@ -659,3 +680,132 @@ describe('TextInput', () => {
     });
   });
 });
+
+describe('TextInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+      />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="detached"
+      />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+
+  it('renders no message box for statusVariant="tooltip"', () => {
+    const {container} = render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    expect(
+      container.querySelector('.astryx-field-status'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('surfaces the status message in a tooltip for statusVariant="tooltip"', () => {
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const tooltip = screen.getByRole('tooltip', h);
+    expect(tooltip).toHaveTextContent('Invalid email');
+  });
+
+  it('describes the input by the status tooltip for statusVariant="tooltip"', () => {
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const input = screen.getByRole('textbox');
+    const tooltip = screen.getByRole('tooltip', h);
+    expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+  });
+
+  it('renders the tooltip status affordance as a focusable button (WCAG 2.1.1)', () => {
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    // The status affordance is a real button with an accessible name naming
+    // the status type (WCAG 4.1.2), so keyboard-only users (no AT) can reach it.
+    const statusButton = screen.getByRole('button', {name: /error details/i});
+    expect(statusButton).toBeInTheDocument();
+    expect(statusButton).toHaveAttribute('type', 'button');
+  });
+
+  it('opens the status tooltip on keyboard focus for statusVariant="tooltip"', async () => {
+    const user = userEvent.setup();
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const tooltip = screen.getByRole('tooltip', h);
+    // Tab from the input to the status button; keyboard focus reveals the tip.
+    await user.tab();
+    await user.tab();
+    await waitFor(() => {
+      expect(tooltip).toHaveAttribute('popover-open');
+    });
+  });
+
+  it('describes the status button by the tooltip content for statusVariant="tooltip"', () => {
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const statusButton = screen.getByRole('button', {name: /error details/i});
+    const tooltip = screen.getByRole('tooltip', h);
+    expect(statusButton.getAttribute('aria-describedby')).toContain(tooltip.id);
+  });
+});