@astryxdesign/core 0.4.7 → 0.5.0-canary.54bb922

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

@@ -41,8 +41,11 @@ function isGroupHeader(item: unknown): item is GroupHeader {
   );
 }
 
-// Proxy handler: any field access beyond the marker fields resolves to `''`
-// so user cell renderers (`item.name.toUpperCase()`) never throw on a header.
+// Proxy handler: any field access beyond the marker fields resolves to `''`,
+// which keeps anything that reads a header's data — the sortable and filtering
+// plugins, a consumer's own row handler — off `undefined`. Cell renderers are
+// handled at render time instead (see `transformBodyCell` below); the Proxy
+// never protected them, because `''` fails a lookup exactly as `undefined` does.
 const HEADER_PROXY_HANDLER: ProxyHandler<Record<string | symbol, unknown>> = {
   // eslint-disable-next-line @typescript-eslint/promise-function-async -- Proxy get trap, not a promise-returning fn
   get(t: Record<string | symbol, unknown>, prop: string | symbol): unknown {
@@ -54,12 +57,9 @@ const HEADER_PROXY_HANDLER: ProxyHandler<Record<string | symbol, unknown>> = {
 };
 
 /**
- * Build a synthetic header row wrapped in a Proxy so arbitrary field access
- * from user cell renderers (e.g. `item.name.toUpperCase()`) resolves to `''`
- * instead of throwing — BaseTable evaluates `col.renderCell(item)` on every
- * row (including synthetic headers) before `transformBodyRow` can replace the
- * row's cells. `transformBodyRow` then discards those cells and renders a
- * single full-width header cell.
+ * Build a synthetic header row wrapped in a Proxy so field access resolves to
+ * `''` instead of `undefined`. `transformBodyRow` then discards the row's
+ * cells and renders a single full-width header cell.
  */
 function makeHeader<T extends Record<string, unknown>>(
   groupKey: string,
@@ -301,6 +301,15 @@ export function useTableGroupedRows<T extends Record<string, unknown>>(
 
   const plugin = useMemo(
     (): TablePlugin<T> => ({
+      // A header row is not one of the caller's rows, so running a cell
+      // renderer against it can only misread it or throw — and the cells are
+      // discarded by `transformBodyRow` below regardless.
+      transformBodyCell(props, _column, item) {
+        if (!isGroupHeader(item)) {
+          return props;
+        }
+        return {...props, isContentSuppressed: true};
+      },
       // Replace a header row's pre-rendered cells with one full-width cell.
       transformBodyRow(props, item) {
         if (!isGroupHeader(item)) {

package/src/Table/plugins/pagination/useTablePagination.test.tsx

@@ -229,7 +229,7 @@ describe('useTablePagination', () => {
       ).toBeTruthy();
     });
 
-    it('transformTableContext renders Pagination above and below', () => {
+    it('transformTableContext renders distinctly named Pagination above and below', () => {
       render(
         <PaginatedTable
           data={generateItems(30)}
@@ -237,10 +237,40 @@ describe('useTablePagination', () => {
           position="both"
         />,
       );
-      const navs = screen.getAllByRole('navigation', {
-        name: 'Table pagination',
+      const table = screen.getByRole('table');
+      // Each nav landmark gets a unique accessible name (axe landmark-unique)
+      const topNav = screen.getByRole('navigation', {
+        name: 'Table pagination (top)',
+      });
+      const bottomNav = screen.getByRole('navigation', {
+        name: 'Table pagination (bottom)',
       });
-      expect(navs).toHaveLength(2);
+      // Top nav comes before the table, bottom nav after it in DOM order
+      expect(
+        table.compareDocumentPosition(topNav) &
+          Node.DOCUMENT_POSITION_PRECEDING,
+      ).toBeTruthy();
+      expect(
+        table.compareDocumentPosition(bottomNav) &
+          Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+    });
+
+    it('position="both" interpolates a consumer label into distinct nav names', () => {
+      render(
+        <PaginatedTable
+          data={generateItems(30)}
+          pageSize={10}
+          position="both"
+          label="Users table"
+        />,
+      );
+      expect(
+        screen.getByRole('navigation', {name: 'Users table (top)'}),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('navigation', {name: 'Users table (bottom)'}),
+      ).toBeInTheDocument();
     });
 
     it('transformTableContext does not render Pagination when position is none', () => {

package/src/Table/plugins/pagination/useTablePagination.tsx

@@ -164,6 +164,9 @@ export interface UseTablePaginationConfig {
 
   /**
    * Accessible label for the pagination nav landmark.
+   * When `position` is 'both', the two navs get distinct names by suffixing
+   * this label — "{label} (top)" above and "{label} (bottom)" below — so
+   * same-type landmarks stay distinguishable to assistive technology.
    * @default 'Table pagination'
    */
   label?: string;
@@ -211,6 +214,10 @@ export function useTablePagination<T extends Record<string, unknown>>(
     label: labelFromProps,
   } = config;
   const label = labelFromProps ?? t('@astryx.table.pagination.label');
+  // position='both' renders two nav landmarks; suffix the base label so each
+  // gets a unique accessible name (axe landmark-unique).
+  const labelAbove = t('@astryx.table.pagination.labelAbove', {label});
+  const labelBelow = t('@astryx.table.pagination.labelBelow', {label});
 
   // Same guard as Pagination itself: 0/NaN/negative pageSize would produce an
   // Infinity/NaN totalPages here, which bypasses Pagination's own coercion
@@ -240,8 +247,20 @@ export function useTablePagination<T extends Record<string, unknown>>(
 
   // Keep current config in a ref so the plugin can read the latest values
   // without needing to recreate the plugin object on every change.
-  const configRef = useRef({paginationProps, position, align});
-  configRef.current = {paginationProps, position, align};
+  const configRef = useRef({
+    paginationProps,
+    position,
+    align,
+    labelAbove,
+    labelBelow,
+  });
+  configRef.current = {
+    paginationProps,
+    position,
+    align,
+    labelAbove,
+    labelBelow,
+  };
 
   // Stable plugin object \u2014 created once, reads config via ref.
   return useMemo(
@@ -251,6 +270,8 @@ export function useTablePagination<T extends Record<string, unknown>>(
           position: pos,
           paginationProps: props,
           align: a,
+          labelAbove: above,
+          labelBelow: below,
         } = configRef.current;
         if (pos === 'none') {
           return children;
@@ -277,7 +298,18 @@ export function useTablePagination<T extends Record<string, unknown>>(
               a === 'end' && styles.alignEnd,
               a === 'start' && styles.alignStart,
             )}>
-            <Pagination {...props} />
+            <Pagination
+              {...props}
+              // Two navs with the same name are indistinguishable landmarks;
+              // give each side a unique name when both render.
+              label={
+                pos === 'both'
+                  ? side === 'above'
+                    ? above
+                    : below
+                  : props.label
+              }
+            />
           </div>
         );
 

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

@@ -21,6 +21,7 @@ import {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 {VisuallyHidden} from '../../../VisuallyHidden';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator} from '../../../i18n';
 import {rtlStyles} from '../../../utils';
@@ -207,7 +208,13 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
   const expansionColumn = useMemo(
     (): TableColumn<T> => ({
       key: '__expansion',
-      header: '',
+      // A `<th>` with no discernible text is announced as an unlabelled
+      // column; the label is hidden because the column shows only chevrons.
+      header: (
+        <VisuallyHidden>
+          {t('@astryx.tableRowExpansion.columnHeader')}
+        </VisuallyHidden>
+      ),
       width: EXPANSION_COLUMN_WIDTH,
       resizable: false,
       renderCell: (item: T) => {
@@ -226,7 +233,7 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
         );
       },
     }),
-    [expandedKeys, onToggle, getRowKey, getIsItemExpandable],
+    [expandedKeys, onToggle, getRowKey, getIsItemExpandable, t],
   );
 
   return useMemo(

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,78 @@ 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',
+      );
+    });
+  });
+
   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,18 +143,24 @@ 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.
+  el.style.backgroundColor =
+    isSelected && hasRowHighlight ? selectedBgColor : '';
 }
 
 // =============================================================================
@@ -358,18 +386,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/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.",
   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.',
   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>)'.",
     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.',
   },
 };