@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx

@@ -44,12 +44,18 @@ function Harness({
 }
 
 describe('useTableRowStatus', () => {
-  it('prepends a narrow status column with an empty header', () => {
+  it('names the status column header for assistive technology', () => {
     render(<Harness />);
-    const headers = screen.getAllByRole('columnheader');
-    // Status column is first; its header is empty.
-    expect(headers[0]).toHaveAttribute('data-column-key', '__rowStatus');
-    expect(headers[0].textContent).toBe('');
+    // The gutter looks blank but its th carries a visually hidden name.
+    const header = screen.getByRole('columnheader', {name: 'Row status'});
+    expect(header).toHaveAttribute('data-column-key', '__rowStatus');
+    // Status column is first.
+    expect(screen.getAllByRole('columnheader')[0]).toBe(header);
+    // The name must come from the clipped VisuallyHidden span — bare th text
+    // would be a visible header on what should stay a blank gutter.
+    const hiddenText = within(header).getByText('Row status');
+    expect(hiddenText.tagName).toBe('SPAN');
+    expect(hiddenText.className).not.toBe('');
   });
 
   it('renders a labeled dot for rows with a status', () => {
@@ -131,8 +137,8 @@ describe('useTableRowStatus', () => {
 
   it('renders the status header with empty data and no indicators', () => {
     render(<Harness rows={[]} />);
-    const headers = screen.getAllByRole('columnheader');
-    expect(headers[0]).toHaveAttribute('data-column-key', '__rowStatus');
+    const header = screen.getByRole('columnheader', {name: 'Row status'});
+    expect(header).toHaveAttribute('data-column-key', '__rowStatus');
     expect(screen.queryByRole('img')).not.toBeInTheDocument();
   });
 });

package/src/Table/plugins/rowStatus/useTableRowStatus.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file useTableRowStatus.tsx
- * @input React, StyleX, Icon, Table types
+ * @input React, StyleX, Icon, i18n, VisuallyHidden, Table types
  * @output Exports useTableRowStatus hook + config type
  * @position Row-status plugin; consumed by Table via plugins prop
  *
@@ -16,6 +16,8 @@ import {useMemo} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon, type IconColor, type IconName} from '../../../Icon';
 import {Tooltip} from '../../../Tooltip';
+import {useTranslator} from '../../../i18n';
+import {VisuallyHidden} from '../../../VisuallyHidden';
 import type {TableColumn, TablePlugin} from '../../types';
 
 /**
@@ -142,6 +144,7 @@ const styles = stylex.create({
 export function useTableRowStatus<T extends Record<string, unknown>>(
   config: UseTableRowStatusConfig<T>,
 ): TablePlugin<T> {
+  const t = useTranslator();
   const {getStatus} = config;
 
   return useMemo(
@@ -149,7 +152,13 @@ export function useTableRowStatus<T extends Record<string, unknown>>(
       transformColumns(columns) {
         const statusColumn: TableColumn<T> = {
           key: '__rowStatus',
-          header: '',
+          // The gutter stays visually blank, but the th needs a discernible
+          // name for assistive technology (axe: empty-table-header).
+          header: (
+            <VisuallyHidden>
+              {t('@astryx.table.rowStatus.columnHeader')}
+            </VisuallyHidden>
+          ),
           width: STATUS_COLUMN_WIDTH,
           resizable: false,
           renderCell: (item: T) => {
@@ -184,6 +193,6 @@ export function useTableRowStatus<T extends Record<string, unknown>>(
         return [statusColumn, ...columns];
       },
     }),
-    [getStatus],
+    [getStatus, t],
   );
 }

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

@@ -13,6 +13,7 @@ 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 {colorVars} from '../../../theme/tokens.stylex';
 import type {BodyRowRenderProps, TableColumn} from '../../types';
 
 // =============================================================================
@@ -41,10 +42,12 @@ function SelectionTable({
   getIsItemSelectable,
   getIsItemEnabled,
   getRowLabel,
+  hasRowHighlight,
 }: {
   getIsItemSelectable?: (item: SelectableUser) => boolean;
   getIsItemEnabled?: (item: SelectableUser) => boolean;
   getRowLabel?: (item: SelectableUser) => string;
+  hasRowHighlight?: boolean;
 }) {
   const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());
 
@@ -78,6 +81,7 @@ function SelectionTable({
     getIsItemSelectable,
     getIsItemEnabled,
     getRowLabel,
+    hasRowHighlight,
   });
 
   return (
@@ -211,6 +215,140 @@ describe('useTableSelection', () => {
     expect(headers).toHaveLength(3);
   });
 
+  describe('hasRowHighlight', () => {
+    const selectedBgColor = colorVars['--color-accent-muted'];
+
+    it('paints a checked row with the accent wash by default', async () => {
+      const user = userEvent.setup();
+      render(<SelectionTable />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+
+      const row = screen.getAllByRole('row')[1];
+      expect(row.style.backgroundColor).toBe(selectedBgColor);
+      expect(row).toHaveAttribute('aria-selected', 'true');
+    });
+
+    it('leaves the row background alone when hasRowHighlight is false', async () => {
+      const user = userEvent.setup();
+      render(<SelectionTable hasRowHighlight={false} />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+
+      const row = screen.getAllByRole('row')[1];
+      expect(row.style.backgroundColor).toBe('');
+      // The wash is opt-out; the semantics are not.
+      expect(row).toHaveAttribute('aria-selected', 'true');
+    });
+
+    it('clears an already-painted row when the flag flips to false', async () => {
+      const user = userEvent.setup();
+      const {rerender} = render(<SelectionTable />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+      expect(screen.getAllByRole('row')[1].style.backgroundColor).toBe(
+        selectedBgColor,
+      );
+
+      rerender(<SelectionTable hasRowHighlight={false} />);
+
+      const row = screen.getAllByRole('row')[1];
+      expect(row.style.backgroundColor).toBe('');
+      expect(row).toHaveAttribute('aria-selected', 'true');
+    });
+
+    it('repaints an already-checked row when the flag flips back to true', async () => {
+      const user = userEvent.setup();
+      const {rerender} = render(<SelectionTable hasRowHighlight={false} />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+      rerender(<SelectionTable hasRowHighlight />);
+
+      expect(screen.getAllByRole('row')[1].style.backgroundColor).toBe(
+        selectedBgColor,
+      );
+    });
+
+    it('never paints unchecked rows in either mode', async () => {
+      const user = userEvent.setup();
+      const {rerender} = render(<SelectionTable />);
+
+      await user.click(screen.getAllByLabelText('Select row')[0]);
+      expect(screen.getAllByRole('row')[2].style.backgroundColor).toBe('');
+      expect(screen.getAllByRole('row')[2]).not.toHaveAttribute(
+        'aria-selected',
+      );
+
+      rerender(<SelectionTable hasRowHighlight={false} />);
+      expect(screen.getAllByRole('row')[2].style.backgroundColor).toBe('');
+      expect(screen.getAllByRole('row')[2]).not.toHaveAttribute(
+        'aria-selected',
+      );
+    });
+
+    // A pinned cell paints over the row, then replays whatever the row
+    // published as --table-row-overlay. Without the variable the wash simply
+    // stops at the freeze line, so it has to track the background exactly.
+    describe('--table-row-overlay', () => {
+      const readOverlay = (row: HTMLElement) =>
+        row.style.getPropertyValue('--table-row-overlay');
+
+      it('publishes the wash so pinned cells can replay it', async () => {
+        const user = userEvent.setup();
+        render(<SelectionTable />);
+
+        await user.click(screen.getAllByLabelText('Select row')[0]);
+
+        expect(readOverlay(screen.getAllByRole('row')[1])).toBe(
+          selectedBgColor,
+        );
+      });
+
+      it('publishes nothing when the row is not painted', async () => {
+        const user = userEvent.setup();
+        render(<SelectionTable hasRowHighlight={false} />);
+
+        await user.click(screen.getAllByLabelText('Select row')[0]);
+
+        expect(readOverlay(screen.getAllByRole('row')[1])).toBe('');
+      });
+
+      it('withdraws the variable when a row is unchecked', async () => {
+        const user = userEvent.setup();
+        render(<SelectionTable />);
+
+        const checkbox = screen.getAllByLabelText('Select row')[0];
+        await user.click(checkbox);
+        await user.click(checkbox);
+
+        expect(readOverlay(screen.getAllByRole('row')[1])).toBe('');
+      });
+
+      it('tracks the background when the flag flips', async () => {
+        const user = userEvent.setup();
+        const {rerender} = render(<SelectionTable />);
+
+        await user.click(screen.getAllByLabelText('Select row')[0]);
+        rerender(<SelectionTable hasRowHighlight={false} />);
+        expect(readOverlay(screen.getAllByRole('row')[1])).toBe('');
+
+        rerender(<SelectionTable hasRowHighlight />);
+        expect(readOverlay(screen.getAllByRole('row')[1])).toBe(
+          selectedBgColor,
+        );
+      });
+
+      it('leaves unchecked rows without the variable', async () => {
+        const user = userEvent.setup();
+        render(<SelectionTable />);
+
+        await user.click(screen.getAllByLabelText('Select row')[0]);
+
+        expect(readOverlay(screen.getAllByRole('row')[2])).toBe('');
+      });
+    });
+  });
+
   it('unsubscribes detached row refs instead of accumulating listeners', () => {
     const getIsItemSelected = vi.fn(() => false);
     const {result, rerender} = renderHook(() =>

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

@@ -26,7 +26,13 @@
  * DOM elements and no central element tracking. Each subscription
  * self-cleans when the row disconnects.
  *
+ * Because the background is an inline style, it outranks anything
+ * userland can layer on with StyleX. `hasRowHighlight: false` is the
+ * supported way to reclaim the row background; `aria-selected` is
+ * unaffected by it.
+ *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/useTableSelection.doc.mjs (config prop table)
  * - /packages/core/src/Table/Table.doc.mjs (selection documentation)
  * - /packages/core/src/Table/index.ts (exports)
  */
@@ -81,6 +87,22 @@ export interface UseTableSelectionConfig<T extends Record<string, unknown>> {
    * ```
    */
   getRowLabel?: (item: T) => string;
+  /**
+   * Paint checked rows with the accent wash. Set false when the surrounding
+   * UI already uses row background to mean something else — a row that is
+   * open in a detail panel, for instance. The wash is an inline style, so
+   * it cannot be overridden from userland; this flag is the way off it.
+   *
+   * Only the background is dropped. `aria-selected` is still set on checked
+   * rows either way, so the selection stays legible to screen readers.
+   *
+   * @default true
+   * @example
+   * ```
+   * useTableSelection({...config, hasRowHighlight: false})
+   * ```
+   */
+  hasRowHighlight?: boolean;
 }
 
 // =============================================================================
@@ -121,17 +143,39 @@ function createSelectionStore<T extends Record<string, unknown>>(
 
 /**
  * Apply or remove selection styling on a <tr> element.
+ *
+ * `aria-selected` tracks selection on its own: it is the semantic half of
+ * the state and stays correct whether or not the row is painted.
  */
 function applyRowSelectionStyle(
   el: HTMLTableRowElement,
   isSelected: boolean,
+  hasRowHighlight: boolean,
 ): void {
   if (isSelected) {
     el.setAttribute('aria-selected', 'true');
-    el.style.backgroundColor = selectedBgColor;
   } else {
     el.removeAttribute('aria-selected');
-    el.style.backgroundColor = '';
+  }
+  // Written on every pass, not just when painting: the flag can flip while a
+  // row is already selected, and the wash has to come back off.
+  const wash = isSelected && hasRowHighlight ? selectedBgColor : '';
+  if (el.style.backgroundColor !== wash) {
+    el.style.backgroundColor = wash;
+  }
+  // A pinned column paints its own opaque background over the row, so the
+  // wash alone stops at the freeze line. Publishing it as the row overlay is
+  // what lets useTableStickyColumns replay it on those cells — the same
+  // contract TableRow honours for striping and hover.
+  const currentOverlay = el.style.getPropertyValue(ROW_OVERLAY_VAR);
+  if (wash === '') {
+    if (currentOverlay !== '') {
+      el.style.removeProperty(ROW_OVERLAY_VAR);
+    }
+  } else {
+    if (currentOverlay !== wash) {
+      el.style.setProperty(ROW_OVERLAY_VAR, wash);
+    }
   }
 }
 
@@ -278,6 +322,13 @@ function SelectionCellContentInner<T extends Record<string, unknown>>({
 
 const selectedBgColor = colorVars['--color-accent-muted'];
 
+/**
+ * The row's current fill, republished for pinned cells to read. Declared as a
+ * literal rather than imported because StyleX needs the same name as a static
+ * key on the reading side, so there is no one constant both ends can share.
+ */
+const ROW_OVERLAY_VAR = '--table-row-overlay';
+
 const selectionColumnStyles = stylex.create({
   center: {
     display: 'flex',
@@ -358,18 +409,23 @@ export function useTableSelection<T extends Record<string, unknown>>(
           if (!el) {
             return;
           }
+          const applyStyle = () => {
+            const config = store.getConfig();
+            applyRowSelectionStyle(
+              el,
+              config.getIsItemSelected(item),
+              config.hasRowHighlight ?? true,
+            );
+          };
           // Apply initial style
-          applyRowSelectionStyle(el, store.getConfig().getIsItemSelected(item));
+          applyStyle();
           // Subscribe for future changes
           const unsub = store.subscribe(() => {
             if (!el.isConnected) {
               unsub();
               return;
             }
-            applyRowSelectionStyle(
-              el,
-              store.getConfig().getIsItemSelected(item),
-            );
+            applyStyle();
           });
           return () => {
             unsub();

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

@@ -210,8 +210,7 @@ const stickyStyles = stylex.create({
 // ::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.
 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 SHADOW_TINT = colorVars['--color-shadow'];
 const shadowStyles = stylex.create({
   // start-pinned: shadow falls toward inline-end (over scrolled content).
   // insetInlineEnd anchors the strip to the column's inline-end edge; the strip

package/src/Table/types.ts

@@ -322,6 +322,19 @@ export interface BodyCellRenderProps {
    * sticky offsets. Optional for backward compatibility.
    */
   columns?: ReadonlyArray<TableColumn<Record<string, unknown>>>;
+  /**
+   * When true, the cell renders empty: BaseTable calls neither the column's
+   * `renderCell` nor the default renderer. Set it for a row whose cells a
+   * plugin is going to replace wholesale in `transformBodyRow` (a grouped-rows
+   * section header, a summary row) — the row is not one the consumer supplied,
+   * so their renderer can only misread it or throw, and its output is
+   * discarded moments later anyway.
+   *
+   * Applies to this cell only, and is decided per render against the final
+   * column list, so it covers columns other plugins contributed regardless of
+   * where in the pipeline this plugin sits.
+   */
+  isContentSuppressed?: boolean;
 }
 
 /**
@@ -414,13 +427,18 @@ export type TableContextActions =
  *
  * 1. `transformColumns` — filter, reorder, or inject columns before rendering
  * 2. `transformTable` — transform the root `<table>` element props
- * 3. `transformHeaderRow` — transform the header `<tr>` props
- * 4. `transformHeaderCell` — transform each `<th>` props
- * 5. `transformBodyRow` — transform each body `<tr>` props
- * 6. `transformBodyCell` — transform each body `<td>` props
+ * 3. `transformHeaderCell` — transform each `<th>` props
+ * 4. `transformHeaderRow` — transform the header `<tr>` props
+ * 5. `transformBodyCell` — transform each body `<td>` props
+ * 6. `transformBodyRow` — transform each body `<tr>` props
  * 7. `transformScrollWrapper` — transform the scroll-container wrapper around the table
  * 8. `transformTableContext` — wrap the table output in context providers
  *
+ * A row's cells are built before its row transform runs, and reach it as
+ * `children`: the cell hook is the earliest per-cell interception point, and a
+ * row transform can discard cells but cannot stop them being built (see
+ * `isContentSuppressed` on `BodyCellRenderProps` for that).
+ *
  * Plugins may also contribute right-click menu actions by appending to
  * `contextMenuActions` in `transformHeaderCell` / `transformBodyCell`
  * (aggregated into one menu per header cell / row).

package/src/Table/useBaseTablePlugins.ts

@@ -46,6 +46,11 @@ import {devWarn} from '../utils/devWarning';
  * Canonical ordering for first-party plugin names.
  * Plugins are sorted by their position in this array.
  * Unknown names are appended after the known set.
+ *
+ * This decides LAYOUT — which column lands left of which, who wraps whom. It
+ * must never decide whether the table works: a plugin that renders in one
+ * order and crashes in the other is broken, and adding it here buys a lucky
+ * order rather than a fix.
  */
 const PLUGIN_ORDER: ReadonlyArray<string> = [
   'columnSettings',

package/src/Table/useTableGroupedRows.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableGroupedRows',
   description:
-    'Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group\'s data rows while keeping the header visible. Mirrors useTableTreeState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey}: pass all three to Table (data, plugins, and idKey respectively).',
+    "Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group's data rows while keeping the header visible. Mirrors useTableTreeState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey}: pass them to Table as data, plugins, and idKey respectively. Grouping runs on the rows you hand it, so with pagination the order is filter, sort, slice, then group \u2014 sort by the group key first and the user's keys second, so a section's rows stay contiguous and each page appends to the bottom of the table instead of splicing rows in above the reader. A page that ends on a row count still cuts mid-section, and the heading then counts what has loaded rather than what exists \u2014 \"6\" quietly becoming \"10\". Where the full result set is in hand, carry the cut forward to the end of the section it lands in: every rendered section is then whole and its count is a total.",
   props: [
     {
       name: 'data',
@@ -58,13 +58,14 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey}: pass to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
+    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey}: pass them to Table data / plugins / idKey. Consumer owns the collapsedGroups set. Under pagination the order is filter, sort, slice, group \u2014 sort by the group key first so sections stay contiguous and pages append at the bottom. A row-count cut lands mid-section and the heading counts the page, not the section; where the whole result set is in hand, carry the cut to the end of the section it lands in so every rendered section is complete.',
   propDescriptions: {
     data: 'The flat data to group.',
-    groupBy: 'Derive a row\'s group key. Same key = same section.',
+    groupBy: "Derive a row's group key. Same key = same section.",
     collapsedGroups: 'Set of currently-collapsed group keys.',
     onToggleGroup: 'Called with the group key when a header is toggled.',
-    renderGroupHeader: "Custom header content (right of chevron). Default '<key> (<count>)'.",
+    renderGroupHeader:
+      "Custom header content (right of chevron). Default '<key> (<count>)'. Args: (key, count, collapsed).",
     getRowKey: 'Stable key for a real row; positional fallback when omitted.',
     groupOrder: 'Pin these group keys first; others keep first-seen order.',
   },

package/src/Table/useTablePagination.doc.mjs

@@ -72,6 +72,12 @@ export const docs = {
       description: 'Horizontal alignment of the pagination controls.',
       default: "'center'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description: "Accessible name for the pagination nav landmark. With position='both' the two navs get distinct names (the label suffixed as '(top)' and '(bottom)') so same-type landmarks stay unique (axe landmark-unique).",
+      default: "'Table pagination'",
+    },
   ],
 };
 
@@ -129,5 +135,6 @@ export const docsDense = {
     pageSize: 'Items per page. Default 10.',
     variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",
     position: "Render position: 'below'|'above'|'both'|'none'.",
+    label: "Accessible name for the nav landmark; position='both' emits '<label> (top)' / '<label> (bottom)'.",
   },
 };

package/src/Table/useTableRowStatus.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableRowStatus',
   description:
-    'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status: a colored status dot by default, or an icon when provided (shape + color is more accessible than color alone). getStatus maps a row to a semantic color (mapped to a theme token) or raw CSS color, an optional icon, and a required accessible label (shown in a tooltip on hover and announced to assistive technology, so status is never color-only); return null for no indicator. Memoize getStatus with useCallback for a stable plugin identity.',
+    'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status: a colored status dot by default, or an icon when provided (shape + color is more accessible than color alone). getStatus maps a row to a semantic color (mapped to a theme token) or raw CSS color, an optional icon, and a required accessible label (shown in a tooltip on hover and announced to assistive technology, so status is never color-only); return null for no indicator. The column header is visually blank but carries a screen-reader-only localized name ("Row status", i18n key @astryx.table.rowStatus.columnHeader). Memoize getStatus with useCallback for a stable plugin identity.',
   props: [
     {
       name: 'getStatus',

package/src/Table/useTableSelection.doc.mjs

@@ -61,6 +61,13 @@ export const docs = {
       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.',
     },
+    {
+      name: 'hasRowHighlight',
+      type: 'boolean',
+      description:
+        'Paints checked rows with the accent wash. Set false when the surrounding UI already uses row background to mean something else (a row open in a detail panel, say). The wash is an inline style, so it cannot be overridden from userland. Only the background is dropped: aria-selected is still set on checked rows either way.',
+      default: 'true',
+    },
   ],
   examples: [
     {
@@ -82,6 +89,21 @@ const selectionPlugin = useTableSelection({
   idKey="id"
   plugins={{selection: selectionPlugin}}
 />;
+`,
+    },
+    {
+      label: 'Opt out of the checked-row wash',
+      code: `
+// This table already uses row background to mean "open in the detail
+// panel". Turning the selection wash off keeps that meaning unambiguous;
+// the checkbox and aria-selected still carry the selection.
+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,
+  hasRowHighlight: false,
+});
 `,
     },
   ],
@@ -142,6 +164,13 @@ export const docsZh = {
       description:
         '为行派生人类可读的标识；行复选框的隐藏标签变为 `Select ${getRowLabel(item)}`，让屏幕阅读器播报每个复选框选择的是哪一行。省略时回退为 "Select row"。',
     },
+    {
+      name: 'hasRowHighlight',
+      type: 'boolean',
+      description:
+        '为选中的行绘制强调色背景。当周围的界面已用行背景表达其他含义（例如该行已在详情面板中打开）时设为 false —— 该背景是内联样式，无法从业务代码覆盖。仅去掉背景：无论如何选中的行仍会设置 aria-selected。',
+      default: 'true',
+    },
   ],
 };
 
@@ -164,5 +193,7 @@ export const docsDense = {
       '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.',
+    hasRowHighlight:
+      'false => skip the accent wash on checked rows (inline style, not overridable from userland). aria-selected is unaffected. Defaults to true.',
   },
 };

package/src/Text/Text.test.tsx

@@ -6,7 +6,7 @@
  */
 
 import {render, screen} from '@testing-library/react';
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {Text} from './Text';
 import type {TextType} from './Text';
 import type {TextColor} from '../theme/types';
@@ -23,6 +23,28 @@ describe('Text', () => {
       expect(screen.getByText('Hello World')).toBeInTheDocument();
     });
 
+    it('keeps a forwarded ref attached across rerenders', () => {
+      const ref = vi.fn();
+      const {rerender} = render(
+        <Text ref={ref} type="body">
+          Before
+        </Text>,
+      );
+
+      const element = screen.getByText('Before');
+      expect(ref).toHaveBeenLastCalledWith(element);
+      ref.mockClear();
+
+      rerender(
+        <Text ref={ref} type="body">
+          After
+        </Text>,
+      );
+
+      expect(ref).not.toHaveBeenCalled();
+      expect(screen.getByText('After')).toBe(element);
+    });
+
     it('renders as span by default', () => {
       render(<Text type="body">Text</Text>);
       const element = screen.getByText('Text');
@@ -275,3 +297,47 @@ describe('Text custom colors', () => {
     expect(screen.getByText('Accent').className).toContain('accent');
   });
 });
+
+// A truncated Text rendered its own Tooltip AND set `title` with the same
+// string, so the browser drew a second, unstyled tooltip on top of ours.
+describe('truncated text shows one tooltip, not two', () => {
+  function withOverflow() {
+    const proto = window.HTMLElement.prototype;
+    const original = {
+      scrollWidth: Object.getOwnPropertyDescriptor(proto, 'scrollWidth'),
+      offsetWidth: Object.getOwnPropertyDescriptor(proto, 'offsetWidth'),
+    };
+    Object.defineProperty(proto, 'scrollWidth', {
+      configurable: true,
+      get: () => 400,
+    });
+    Object.defineProperty(proto, 'offsetWidth', {
+      configurable: true,
+      get: () => 100,
+    });
+    return () => {
+      if (original.scrollWidth) {
+        Object.defineProperty(proto, 'scrollWidth', original.scrollWidth);
+      }
+      if (original.offsetWidth) {
+        Object.defineProperty(proto, 'offsetWidth', original.offsetWidth);
+      }
+    };
+  }
+
+  it('leaves the native title to the tooltip it already renders', () => {
+    const restore = withOverflow();
+    try {
+      render(
+        <Text type="body" maxLines={1}>
+          A label far wider than the space it has been given
+        </Text>,
+      );
+      expect(
+        screen.getByText('A label far wider than the space it has been given'),
+      ).not.toHaveAttribute('title');
+    } finally {
+      restore();
+    }
+  });
+});