@astryxdesign/core 0.1.5 → 0.1.6-canary.02f2602

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

@@ -0,0 +1,351 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableGroupedRows.tsx
+ * @input React, StyleX, Icon, Table types + the flat data array
+ * @output Exports useTableGroupedRows hook + config/result types
+ * @position Grouped-rows plugin; consumed by Table via plugins prop
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/index.ts (exports)
+ */
+
+import {useCallback, useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+  spacingVars,
+  colorVars,
+  fontWeightVars,
+} from '../../../theme/tokens.stylex';
+import {Icon} from '../../../Icon';
+import type {TablePlugin} from '../../types';
+import {useTranslator} from '../../../i18n';
+
+// A synthetic group-header row injected into the flattened data. Real rows
+// never carry this marker.
+const GROUP_HEADER = Symbol('tableGroupHeader');
+
+interface GroupHeader {
+  [GROUP_HEADER]: true;
+  groupKey: string;
+  count: number;
+}
+
+function isGroupHeader(item: unknown): item is GroupHeader {
+  return (
+    typeof item === 'object' &&
+    item !== null &&
+    (item as Record<symbol, unknown>)[GROUP_HEADER] === true
+  );
+}
+
+// Proxy handler: any field access beyond the marker fields resolves to `''`
+// so user cell renderers (`item.name.toUpperCase()`) never throw on a header.
+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 {
+    if (prop === GROUP_HEADER || prop === 'groupKey' || prop === 'count') {
+      return t[prop];
+    }
+    return prop in t ? t[prop] : '';
+  },
+};
+
+/**
+ * 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.
+ */
+function makeHeader<T extends Record<string, unknown>>(
+  groupKey: string,
+  count: number,
+): T {
+  const target: Record<string | symbol, unknown> = {
+    [GROUP_HEADER]: true,
+    groupKey,
+    count,
+  };
+  return new Proxy(target, HEADER_PROXY_HANDLER) as unknown as T;
+}
+
+/** Configuration for {@link useTableGroupedRows}. */
+export interface UseTableGroupedRowsConfig<T extends Record<string, unknown>> {
+  /** The flat data to group. */
+  data: T[];
+  /** Derive the group key for a row. Rows with the same key share a section. */
+  groupBy: (item: T) => string;
+  /** Set of currently-collapsed group keys. */
+  collapsedGroups: Set<string>;
+  /** Called with a group key when its header is toggled. */
+  onToggleGroup: (groupKey: string) => void;
+  /**
+   * Custom renderer for a group header's content (right of the chevron).
+   * Defaults to `<groupKey> (<count>)`.
+   */
+  renderGroupHeader?: (
+    groupKey: string,
+    count: number,
+    collapsed: boolean,
+  ) => ReactNode;
+  /** Stable key for a real row. Falls back to a positional key when omitted. */
+  getRowKey?: (item: T) => string;
+  /** Explicit group ordering; groups not listed keep first-seen order after these. */
+  groupOrder?: string[];
+}
+
+export interface UseTableGroupedRowsResult<T extends Record<string, unknown>> {
+  /** Ready-to-use plugin for `<Table plugins>`. */
+  plugin: TablePlugin<T>;
+  /** Flattened rows: `[header, ...visibleRows, header, ...visibleRows]`. */
+  data: T[];
+  /**
+   * Row-key resolver (also keys synthetic headers as `__group_<key>`). Pass to
+   * `<Table idKey>` — named for parallelism with the Table prop:
+   * `<Table idKey={grouped.idKey} />`.
+   */
+  idKey: (item: T) => string;
+}
+
+const styles = stylex.create({
+  headerRow: {
+    cursor: 'pointer',
+    userSelect: 'none',
+    backgroundColor: colorVars['--color-background-muted'],
+    // Divider beneath each group header row (Ernest review #2).
+    borderBottomWidth: '1px',
+    borderBottomStyle: 'solid',
+    borderBottomColor: colorVars['--color-border'],
+  },
+  headerCell: {
+    paddingBlock: spacingVars['--spacing-2'],
+    // No inline start padding so the chevron aligns with the table's leading
+    // edge (Ernest review #1).
+    paddingInlineStart: spacingVars['--spacing-1'],
+    paddingInlineEnd: spacingVars['--spacing-3'],
+  },
+  headerInner: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+  },
+  // Standalone chevron button with no heavy chrome (transparent, borderless,
+  // zero padding) so the icon sits flush with the start of the table
+  // (Ernest review #1) while staying keyboard-operable.
+  chevron: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: '0',
+    padding: 0,
+    margin: 0,
+    background: 'transparent',
+    border: 'none',
+    cursor: 'pointer',
+    color: {
+      default: colorVars['--color-icon-secondary'],
+      ':hover': colorVars['--color-icon-primary'],
+    },
+  },
+  chevronIcon: {
+    display: 'inline-flex',
+    transitionProperty: 'transform',
+    transitionDuration: '150ms',
+  },
+  chevronExpanded: {
+    transform: 'rotate(90deg)',
+  },
+  // Emphasized body text — same size as body, heavier weight (Ernest #3).
+  label: {
+    fontWeight: fontWeightVars['--font-weight-semibold'],
+    color: colorVars['--color-text-primary'],
+  },
+  count: {
+    fontWeight: fontWeightVars['--font-weight-normal'],
+    color: colorVars['--color-text-secondary'],
+  },
+});
+
+/**
+ * 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 {@link useTableRowExpansionState}: the consumer owns the
+ * `collapsedGroups` set and this hook returns `{data, plugin, idKey}` —
+ * pass all three to `<Table>`.
+ *
+ * @example
+ * ```
+ * const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
+ * const grouped = useTableGroupedRows({
+ *   data: rows,
+ *   groupBy: r => r.team,
+ *   collapsedGroups: collapsed,
+ *   onToggleGroup: key =>
+ *     setCollapsed(prev => {
+ *       const next = new Set(prev);
+ *       next.has(key) ? next.delete(key) : next.add(key);
+ *       return next;
+ *     }),
+ *   getRowKey: r => r.id,
+ * });
+ * <Table
+ *   data={grouped.data}
+ *   columns={columns}
+ *   idKey={grouped.idKey}
+ *   plugins={{grouped: grouped.plugin}}
+ * />;
+ * ```
+ */
+export function useTableGroupedRows<T extends Record<string, unknown>>(
+  config: UseTableGroupedRowsConfig<T>,
+): UseTableGroupedRowsResult<T> {
+  const t = useTranslator();
+  const {
+    data,
+    groupBy,
+    collapsedGroups,
+    onToggleGroup,
+    renderGroupHeader,
+    getRowKey: getRowKeyProp,
+    groupOrder,
+  } = config;
+
+  const flattened = useMemo((): T[] => {
+    if (data.length === 0) {
+      return [];
+    }
+
+    // Group preserving first-seen order.
+    const groups = new Map<string, T[]>();
+    for (const item of data) {
+      const key = groupBy(item);
+      const bucket = groups.get(key);
+      if (bucket) {
+        bucket.push(item);
+      } else {
+        groups.set(key, [item]);
+      }
+    }
+
+    // Determine iteration order.
+    let keys = [...groups.keys()];
+    if (groupOrder && groupOrder.length > 0) {
+      const ordered = groupOrder.filter(k => groups.has(k));
+      const rest = keys.filter(k => !groupOrder.includes(k));
+      keys = [...ordered, ...rest];
+    }
+
+    const out: T[] = [];
+    for (const key of keys) {
+      const rows = groups.get(key) ?? [];
+      out.push(makeHeader<T>(key, rows.length));
+      if (!collapsedGroups.has(key)) {
+        out.push(...rows);
+      }
+    }
+    return out;
+  }, [data, groupBy, collapsedGroups, groupOrder]);
+
+  // Positional fallback index, built once per flattened array so key lookup
+  // stays O(1) instead of O(n) per row (which would make table keying O(n²)).
+  const positionByItem = useMemo(() => {
+    if (getRowKeyProp) {
+      return null;
+    }
+    const map = new Map<T, number>();
+    for (let i = 0; i < flattened.length; i++) {
+      map.set(flattened[i], i);
+    }
+    return map;
+  }, [flattened, getRowKeyProp]);
+
+  const idKey = useCallback(
+    (item: T): string => {
+      if (isGroupHeader(item)) {
+        return `__group_${item.groupKey}`;
+      }
+      if (getRowKeyProp) {
+        return getRowKeyProp(item);
+      }
+      return String(positionByItem?.get(item) ?? -1);
+    },
+    [getRowKeyProp, positionByItem],
+  );
+
+  const plugin = useMemo(
+    (): TablePlugin<T> => ({
+      // Replace a header row's pre-rendered cells with one full-width cell.
+      transformBodyRow(props, item) {
+        if (!isGroupHeader(item)) {
+          return props;
+        }
+        const header = item as unknown as GroupHeader;
+        const collapsed = collapsedGroups.has(header.groupKey);
+        const toggle = () => onToggleGroup(header.groupKey);
+        const content: ReactNode = renderGroupHeader ? (
+          renderGroupHeader(header.groupKey, header.count, collapsed)
+        ) : (
+          <span {...stylex.props(styles.label)}>
+            {header.groupKey}{' '}
+            <span {...stylex.props(styles.count)}>({header.count})</span>
+          </span>
+        );
+        return {
+          ...props,
+          htmlProps: {
+            ...props.htmlProps,
+            // Convenience: clicking anywhere on the row toggles it. The chevron
+            // button below is the accessible, keyboard-operable control, so the
+            // row keeps its implicit `row` role (no role override here).
+            onClick: toggle,
+            'aria-expanded': !collapsed,
+          },
+          styles: [...props.styles, styles.headerRow],
+          children: (
+            // colSpan larger than the column count is clamped by the browser
+            // to the actual number of columns, so the header always spans the
+            // full width without the plugin knowing the column count.
+            <td colSpan={999} {...stylex.props(styles.headerCell)}>
+              <span {...stylex.props(styles.headerInner)}>
+                {/* Standalone chevron button, flush with the table's start
+                    edge (no heavy button chrome) — the keyboard control. */}
+                <button
+                  type="button"
+                  {...stylex.props(styles.chevron)}
+                  onClick={e => {
+                    e.stopPropagation();
+                    toggle();
+                  }}
+                  aria-label={
+                    collapsed
+                      ? t('@astryx.tableGroupedRows.expandGroup', {groupKey: header.groupKey})
+                      : t('@astryx.tableGroupedRows.collapseGroup', {groupKey: header.groupKey})
+                  }
+                  aria-expanded={!collapsed}>
+                  <span
+                    {...stylex.props(
+                      styles.chevronIcon,
+                      !collapsed && styles.chevronExpanded,
+                    )}>
+                    <Icon icon="chevronRight" size="xsm" />
+                  </span>
+                </button>
+                {content}
+              </span>
+            </td>
+          ),
+        };
+      },
+    }),
+    [collapsedGroups, onToggleGroup, renderGroupHeader, t],
+  );
+
+  return {plugin, data: flattened, idKey};
+}

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

@@ -22,6 +22,7 @@ import {spacingVars} from '../../../theme/tokens.stylex';
 import {Pagination} from '../../../Pagination';
 import type {PaginationProps} from '../../../Pagination';
 import type {TablePlugin} from '../../types';
+import {useTranslator} from '../../../i18n';
 
 // =============================================================================
 // Styles
@@ -193,6 +194,7 @@ export interface UseTablePaginationConfig {
 export function useTablePagination<T extends Record<string, unknown>>(
   config: UseTablePaginationConfig,
 ): TablePlugin<T> {
+  const t = useTranslator();
   const {
     page,
     onPageChange,
@@ -206,8 +208,9 @@ export function useTablePagination<T extends Record<string, unknown>>(
     size = 'md',
     position = 'below',
     align = 'center',
-    label = 'Table pagination',
+    label: labelFromProps,
   } = config;
+  const label = labelFromProps ?? t('@astryx.table.pagination.label');
 
   // Same guard as Pagination itself: 0/NaN/negative pageSize would produce an
   // Infinity/NaN totalPages here, which bypasses Pagination's own coercion

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

@@ -17,6 +17,7 @@ import * as stylex from '@stylexjs/stylex';
 import {spacingVars, colorVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
+import {useTranslator} from '../../../i18n';
 import type {
   TablePlugin,
   TableColumn,
@@ -109,7 +110,7 @@ export interface UseTableRowExpansionStateResult<
  * computing the expand-all state.
  *
  * @example
- * ```tsx
+ * ```
  * const [expandedKeys, setExpandedKeys] = useState<Set<string>>(new Set());
  * const {data, expansionConfig} = useTableRowExpansionState({
  *   baseData: tree,
@@ -356,6 +357,7 @@ function ExpansionChevron({
 export function useTableRowExpansion<T extends Record<string, unknown>>(
   config: UseTableRowExpansionConfig<T>,
 ): TablePlugin<T> {
+  const t = useTranslator();
   const {
     expandedKeys,
     onToggle,
@@ -397,7 +399,7 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
           <ExpansionChevron
             isExpanded={isExpanded}
             onToggle={() => onToggle(key)}
-            ariaLabel={isExpanded ? 'Collapse row' : 'Expand row'}
+            ariaLabel={isExpanded ? t('@astryx.tableRowExpansion.collapseRow') : t('@astryx.tableRowExpansion.expandRow')}
           />
         );
       },
@@ -409,6 +411,7 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
       getChildren,
       getIsItemExpandable,
       getDepth,
+      t,
     ],
   );
 
@@ -457,7 +460,7 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                 <ExpansionChevron
                   isExpanded={isExpanded}
                   onToggle={() => onToggle(key)}
-                  ariaLabel={isExpanded ? 'Collapse row' : 'Expand row'}
+                  ariaLabel={isExpanded ? t('@astryx.tableRowExpansion.collapseRow') : t('@astryx.tableRowExpansion.expandRow')}
                 />
               ) : (
                 <span {...stylex.props(expansionStyles.placeholder)} />
@@ -499,7 +502,7 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                 {...stylex.props(expansionStyles.chevronButton)}
                 onClick={() => onToggleExpandAll(!allExpanded)}
                 aria-label={
-                  allExpanded ? 'Collapse all rows' : 'Expand all rows'
+                  allExpanded ? t('@astryx.tableRowExpansion.collapseAllRows') : t('@astryx.tableRowExpansion.expandAllRows')
                 }>
                 <span
                   {...stylex.props(
@@ -585,6 +588,7 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
       isAllExpanded,
       onToggleExpandAll,
       expansionColumn,
+      t,
     ],
   );
 }

package/src/Table/plugins/rowIndex/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {useTableRowIndex} from './useTableRowIndex';
+export type {UseTableRowIndexConfig} from './useTableRowIndex';

package/src/Table/plugins/rowIndex/useTableRowIndex.test.tsx

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, within} from '@testing-library/react';
+import {Table} from '../../Table';
+import type {TableColumn} from '../../types';
+import {useTableRowIndex} from './useTableRowIndex';
+
+interface Row extends Record<string, unknown> {
+  id: string;
+  name: string;
+}
+
+const data: Row[] = [
+  {id: 'a', name: 'Alice'},
+  {id: 'b', name: 'Bob'},
+  {id: 'c', name: 'Carol'},
+];
+
+const columns: TableColumn<Row>[] = [{key: 'name', header: 'Name'}];
+
+function Harness({
+  rows = data,
+  label,
+  startFrom,
+  useKey = false,
+}: {
+  rows?: Row[];
+  label?: string;
+  startFrom?: number;
+  useKey?: boolean;
+}) {
+  const rowIndex = useTableRowIndex<Row>({
+    data: rows,
+    label,
+    startFrom,
+    getRowKey: useKey ? item => item.id : undefined,
+  });
+  return (
+    <Table data={rows} columns={columns} idKey="id" plugins={{rowIndex}} />
+  );
+}
+
+describe('useTableRowIndex', () => {
+  it('prepends a header cell with the default label', () => {
+    render(<Harness />);
+    const headers = screen.getAllByRole('columnheader');
+    // First column is the index column.
+    expect(within(headers[0]).getByText('#')).toBeInTheDocument();
+  });
+
+  it('numbers rows 1..n by default', () => {
+    render(<Harness />);
+    expect(screen.getByText('1')).toBeInTheDocument();
+    expect(screen.getByText('2')).toBeInTheDocument();
+    expect(screen.getByText('3')).toBeInTheDocument();
+  });
+
+  it('respects startFrom', () => {
+    render(<Harness startFrom={0} />);
+    expect(screen.getByText('0')).toBeInTheDocument();
+    expect(screen.getByText('2')).toBeInTheDocument();
+    expect(screen.queryByText('3')).not.toBeInTheDocument();
+  });
+
+  it('supports a custom label', () => {
+    render(<Harness label="Row" />);
+    const headers = screen.getAllByRole('columnheader');
+    expect(within(headers[0]).getByText('Row')).toBeInTheDocument();
+  });
+
+  it('numbers a single row', () => {
+    render(<Harness rows={[{id: 'a', name: 'Alice'}]} />);
+    const rows = screen.getAllByRole('row');
+    expect(within(rows[1]).getByText('1')).toBeInTheDocument();
+    expect(within(rows[1]).getByText('Alice')).toBeInTheDocument();
+  });
+
+  it('renders the index header with empty data and no row numbers', () => {
+    render(<Harness rows={[]} />);
+    const headers = screen.getAllByRole('columnheader');
+    expect(within(headers[0]).getByText('#')).toBeInTheDocument();
+    // No body rows → no ordinals.
+    expect(screen.queryByText('1')).not.toBeInTheDocument();
+  });
+
+  it('renumbers when the data order changes (reference path)', () => {
+    const {rerender} = render(<Harness rows={data} />);
+    let rows = screen.getAllByRole('row');
+    // rows[0] is the header row.
+    expect(within(rows[1]).getByText('Alice')).toBeInTheDocument();
+    expect(within(rows[1]).getByText('1')).toBeInTheDocument();
+
+    // Reorder: Carol, Alice, Bob (same object identities, new order).
+    rerender(<Harness rows={[data[2], data[0], data[1]]} />);
+    rows = screen.getAllByRole('row');
+    expect(within(rows[1]).getByText('Carol')).toBeInTheDocument();
+    expect(within(rows[1]).getByText('1')).toBeInTheDocument();
+    expect(within(rows[2]).getByText('Alice')).toBeInTheDocument();
+    expect(within(rows[2]).getByText('2')).toBeInTheDocument();
+  });
+
+  it('renumbers when the data order changes (keyed path)', () => {
+    // With getRowKey provided, the keyed lookup must still produce ordinals in
+    // the new order. If the keyed branch were broken it would return undefined
+    // and render no numbers — so this fails for the right reason.
+    const {rerender} = render(<Harness rows={data} useKey />);
+    let rows = screen.getAllByRole('row');
+    expect(within(rows[1]).getByText('Alice')).toBeInTheDocument();
+    expect(within(rows[1]).getByText('1')).toBeInTheDocument();
+
+    rerender(<Harness rows={[data[1], data[2], data[0]]} useKey />);
+    rows = screen.getAllByRole('row');
+    expect(within(rows[1]).getByText('Bob')).toBeInTheDocument();
+    expect(within(rows[1]).getByText('1')).toBeInTheDocument();
+    expect(within(rows[3]).getByText('Alice')).toBeInTheDocument();
+    expect(within(rows[3]).getByText('3')).toBeInTheDocument();
+  });
+
+  it('keyed path resolves ordinals across fresh object identities', () => {
+    // Simulates a re-fetch: brand-new objects with the same ids. Keyed lookup
+    // must map them correctly.
+    const fresh: Row[] = [
+      {id: 'a', name: 'Alice'},
+      {id: 'b', name: 'Bob'},
+    ];
+    render(<Harness rows={fresh} useKey />);
+    const rows = screen.getAllByRole('row');
+    expect(within(rows[1]).getByText('1')).toBeInTheDocument();
+    expect(within(rows[2]).getByText('2')).toBeInTheDocument();
+  });
+});

package/src/Table/plugins/rowIndex/useTableRowIndex.tsx

@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableRowIndex.tsx
+ * @input React, StyleX, Table types + the rendered data array
+ * @output Exports useTableRowIndex hook + config type
+ * @position Row-index plugin; consumed by Table via plugins prop
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/index.ts (exports)
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars, typeScaleVars} from '../../../theme/tokens.stylex';
+
+import type {TableColumn, TablePlugin} from '../../types';
+
+/**
+ * Configuration for {@link useTableRowIndex}.
+ *
+ * Astryx's `renderCell` receives only the row item (not its position), so the
+ * plugin needs the rendered `data` array — the same array passed to
+ * `<Table data>` — to derive each row's 1-based ordinal. Pass `getRowKey` when
+ * items don't have a stable identity by reference (e.g. new objects each
+ * render); it must return a **unique** string per row (duplicate keys collapse
+ * to a single ordinal).
+ */
+export interface UseTableRowIndexConfig<T extends Record<string, unknown>> {
+  /** The data array currently rendered by the table (post sort/filter/page). */
+  data: T[];
+  /**
+   * Optional key extractor returning a **unique** string per row. When
+   * provided, index lookup is keyed by the returned string (stable across new
+   * object identities); otherwise items are matched by reference identity.
+   * For a stable plugin identity across renders, memoize this with
+   * `useCallback`.
+   */
+  getRowKey?: (item: T) => string;
+  /** Header label for the index column. @default '#' */
+  label?: ReactNode;
+  /** First index value. @default 1 */
+  startFrom?: number;
+}
+
+const INDEX_COLUMN_WIDTH = {type: 'pixel' as const, value: 48};
+
+const styles = stylex.create({
+  index: {
+    fontFamily: 'var(--font-family-code)',
+    fontSize: typeScaleVars['--text-supporting-size'],
+    fontVariantNumeric: 'tabular-nums',
+    color: colorVars['--color-text-secondary'],
+  },
+});
+
+/**
+ * Returns a {@link TablePlugin} that prepends a right-aligned, monospaced
+ * row-number column. Numbering follows the order of the rendered `data` array,
+ * so it reflects the current sort / filter / pagination view.
+ *
+ * @example
+ * ```
+ * const rowIndex = useTableRowIndex({data});
+ * <Table data={data} columns={columns} idKey="id" plugins={{rowIndex}} />;
+ * ```
+ */
+export function useTableRowIndex<T extends Record<string, unknown>>(
+  config: UseTableRowIndexConfig<T>,
+): TablePlugin<T> {
+  const {data, getRowKey, label = '#', startFrom = 1} = config;
+
+  // Single item → ordinal lookup, built in one pass and rebuilt only when the
+  // data array or key extractor changes. Keyed by getRowKey when provided
+  // (stable across new object identities), otherwise by object reference.
+  const lookup = useMemo(() => {
+    const map = new Map<unknown, number>();
+    for (let i = 0; i < data.length; i++) {
+      const item = data[i];
+      map.set(getRowKey ? getRowKey(item) : item, i);
+    }
+    return (item: T): number | undefined =>
+      map.get(getRowKey ? getRowKey(item) : item);
+  }, [data, getRowKey]);
+
+  // The plugin object depends only on the stable lookup and the presentational
+  // props — not on data directly — so it stays as stable as its inputs allow.
+  return useMemo(
+    (): TablePlugin<T> => ({
+      transformColumns(columns) {
+        const indexColumn: TableColumn<T> = {
+          key: '__rowIndex',
+          header: label,
+          width: INDEX_COLUMN_WIDTH,
+          align: 'end',
+          resizable: false,
+          renderCell: (item: T) => {
+            const idx = lookup(item);
+            if (idx == null) {
+              return null;
+            }
+            return (
+              <span {...stylex.props(styles.index)}>{idx + startFrom}</span>
+            );
+          },
+        };
+        return [indexColumn, ...columns];
+      },
+    }),
+    [label, startFrom, lookup],
+  );
+}