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

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

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

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

@@ -0,0 +1,7 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {useTableRowStatus} from './useTableRowStatus';
+export type {
+  UseTableRowStatusConfig,
+  TableRowStatus,
+} from './useTableRowStatus';

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

@@ -0,0 +1,138 @@
+// 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 {useTableRowStatus, type TableRowStatus} from './useTableRowStatus';
+
+interface Row extends Record<string, unknown> {
+  id: string;
+  name: string;
+  state: 'error' | 'warning' | 'ok' | 'done';
+}
+
+const data: Row[] = [
+  {id: 'a', name: 'Alice', state: 'error'},
+  {id: 'b', name: 'Bob', state: 'ok'},
+  {id: 'c', name: 'Carol', state: 'warning'},
+];
+
+const columns: TableColumn<Row>[] = [{key: 'name', header: 'Name'}];
+
+function getStatus(item: Row): TableRowStatus | null {
+  if (item.state === 'error') {
+    return {color: 'red', label: 'Error'};
+  }
+  if (item.state === 'warning') {
+    return {color: 'orange', label: 'Warning'};
+  }
+  return null;
+}
+
+function Harness({
+  rows = data,
+  statusFn = getStatus,
+}: {
+  rows?: Row[];
+  statusFn?: (item: Row) => TableRowStatus | null;
+}) {
+  const rowStatus = useTableRowStatus<Row>({getStatus: statusFn});
+  return (
+    <Table data={rows} columns={columns} idKey="id" plugins={{rowStatus}} />
+  );
+}
+
+describe('useTableRowStatus', () => {
+  it('prepends a narrow status column with an empty header', () => {
+    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('');
+  });
+
+  it('renders a labeled dot for rows with a status', () => {
+    render(<Harness />);
+    expect(screen.getByRole('img', {name: 'Error'})).toBeInTheDocument();
+    expect(screen.getByRole('img', {name: 'Warning'})).toBeInTheDocument();
+  });
+
+  it('renders a dot (not an icon) by default', () => {
+    render(<Harness />);
+    // Default (no icon) renders a plain colored dot: no svg in the indicator.
+    const dot = screen.getByRole('img', {name: 'Error'});
+    expect(dot.querySelector('svg')).toBeNull();
+  });
+
+  it('renders no indicator for rows returning null', () => {
+    render(<Harness />);
+    const rows = screen.getAllByRole('row');
+    // rows[2] is Bob (state ok): no status indicator in his status cell.
+    const bob = rows[2];
+    expect(within(bob).getByText('Bob')).toBeInTheDocument();
+    expect(within(bob).queryByRole('img')).not.toBeInTheDocument();
+  });
+
+  it('maps a semantic color name to its icon color token', () => {
+    render(<Harness />);
+    const errorDot = screen.getByRole('img', {name: 'Error'});
+    // 'red' resolves to var(--color-icon-red); StyleX emits it on the inline
+    // style of the inner dot element.
+    const dot = errorDot.querySelector('span');
+    expect(dot?.getAttribute('style')).toContain('--color-icon-red');
+  });
+
+  it('passes through a raw CSS color as an escape hatch', () => {
+    render(
+      <Harness
+        statusFn={item =>
+          item.state === 'error' ? {color: 'rgb(1, 2, 3)', label: 'Raw'} : null
+        }
+      />,
+    );
+    const indicator = screen.getByRole('img', {name: 'Raw'});
+    const dot = indicator.querySelector('span');
+    expect(dot?.getAttribute('style')).toContain('rgb(1, 2, 3)');
+  });
+
+  it('renders an icon as the status signifier when icon is provided', () => {
+    render(
+      <Harness
+        statusFn={item =>
+          item.state === 'error'
+            ? {color: 'red', icon: 'error', label: 'Error'}
+            : null
+        }
+      />,
+    );
+    // Icon-mode still exposes the accessible label via role=img.
+    const indicator = screen.getByRole('img', {name: 'Error'});
+    expect(indicator).toBeInTheDocument();
+    // An SVG icon is rendered inside the indicator (dot mode has no svg).
+    expect(indicator.querySelector('svg')).not.toBeNull();
+  });
+
+  it('exposes the required label as the accessible name in dot mode', () => {
+    render(
+      <Harness
+        statusFn={item =>
+          item.state === 'error' ? {color: 'red', label: 'Error'} : null
+        }
+      />,
+    );
+    // Label is required, so every dot is announced via role=img with its name.
+    const indicator = screen.getByRole('img', {name: 'Error'});
+    expect(indicator).toBeInTheDocument();
+    // Dot mode renders no svg (that is icon mode).
+    expect(indicator.querySelector('svg')).toBeNull();
+    expect(screen.getByText('Alice')).toBeInTheDocument();
+  });
+
+  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');
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,189 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableRowStatus.tsx
+ * @input React, StyleX, Icon, Table types
+ * @output Exports useTableRowStatus hook + config type
+ * @position Row-status 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} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Icon, type IconColor, type IconName} from '../../../Icon';
+import {Tooltip} from '../../../Tooltip';
+import type {TableColumn, TablePlugin} from '../../types';
+
+/**
+ * Semantic status colors, resolved to the design system's icon color tokens.
+ * Prefer these over raw CSS so status colors stay consistent with the theme.
+ */
+export type TableRowStatusColor =
+  | 'accent'
+  | 'success'
+  | 'error'
+  | 'warning'
+  | 'red'
+  | 'orange'
+  | 'green'
+  | 'yellow'
+  | 'blue'
+  | 'gray';
+
+const SEMANTIC_COLORS: Record<TableRowStatusColor, string> = {
+  accent: 'var(--color-icon-accent)',
+  success: 'var(--color-icon-green)',
+  error: 'var(--color-icon-red)',
+  warning: 'var(--color-icon-orange)',
+  red: 'var(--color-icon-red)',
+  orange: 'var(--color-icon-orange)',
+  green: 'var(--color-icon-green)',
+  yellow: 'var(--color-icon-yellow)',
+  blue: 'var(--color-icon-blue)',
+  gray: 'var(--color-icon-gray)',
+};
+
+/** Icon colors that map cleanly from a semantic status color. */
+const ICON_COLOR_BY_STATUS: Record<TableRowStatusColor, IconColor> = {
+  accent: 'accent',
+  success: 'success',
+  error: 'error',
+  warning: 'warning',
+  red: 'red',
+  orange: 'warning',
+  green: 'green',
+  yellow: 'warning',
+  blue: 'blue',
+  gray: 'gray',
+};
+
+/**
+ * A row's status indicator. `color` accepts a semantic status color
+ * (mapped to a theme token) or any raw CSS color string as an escape hatch.
+ * By default the plugin renders a colored status dot. Provide `icon` to signal
+ * status by shape as well as color, which is more accessible when several
+ * statuses coexist. `label` is required so the status is never conveyed by
+ * color alone — it names the indicator for assistive technology and shows on
+ * hover. Return `null` for rows with no status.
+ */
+export interface TableRowStatus {
+  /** Semantic status color (preferred) or a raw CSS color string. */
+  color: TableRowStatusColor | (string & {});
+  /** Optional icon rendered as the signifier instead of the dot (shape as an a11y differentiator). */
+  icon?: IconName;
+  /**
+   * Accessible name for the status, announced to assistive technology and
+   * shown in a tooltip on hover. Required: a status must never be conveyed by
+   * color alone.
+   */
+  label: string;
+}
+
+/** Configuration for {@link useTableRowStatus}. */
+export interface UseTableRowStatusConfig<T extends Record<string, unknown>> {
+  /**
+   * Derive the status indicator for a row. Return `null` for no indicator.
+   * Memoize with `useCallback` for a stable plugin identity across renders.
+   *
+   * @example
+   * ```
+   * getStatus: row =>
+   *   row.hasError ? {color: 'error', icon: 'error', label: 'Error'} : null
+   * ```
+   */
+  getStatus: (item: T) => TableRowStatus | null;
+}
+
+// The status column holds a small centered dot (or an icon when provided).
+// A fixed narrow width keeps every row's indicator aligned in one gutter.
+const STATUS_COLUMN_WIDTH = {type: 'pixel' as const, value: 28};
+
+/** Resolve a semantic color name to a token, or pass a raw CSS color through. */
+function resolveColor(color: string): string {
+  return (SEMANTIC_COLORS as Record<string, string>)[color] ?? color;
+}
+
+const styles = stylex.create({
+  // Centers the dot or icon within the narrow status column.
+  wrap: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  dot: (color: string) => ({
+    width: '8px',
+    height: '8px',
+    borderRadius: '50%',
+    backgroundColor: color,
+    flexShrink: 0,
+  }),
+});
+
+/**
+ * Returns a {@link TablePlugin} that prepends a narrow column signaling per-row
+ * status: a colored status dot by default, or an icon when `icon` is provided
+ * (shape + color is more accessible than color alone).
+ *
+ * @example
+ * ```
+ * const rowStatus = useTableRowStatus<Row>({
+ *   getStatus: row =>
+ *     row.state === 'error'
+ *       ? {color: 'error', icon: 'error', label: 'Error'}
+ *       : null,
+ * });
+ * <Table data={data} columns={columns} idKey="id" plugins={{rowStatus}} />;
+ * ```
+ */
+export function useTableRowStatus<T extends Record<string, unknown>>(
+  config: UseTableRowStatusConfig<T>,
+): TablePlugin<T> {
+  const {getStatus} = config;
+
+  return useMemo(
+    (): TablePlugin<T> => ({
+      transformColumns(columns) {
+        const statusColumn: TableColumn<T> = {
+          key: '__rowStatus',
+          header: '',
+          width: STATUS_COLUMN_WIDTH,
+          resizable: false,
+          renderCell: (item: T) => {
+            const status = getStatus(item);
+            if (!status) {
+              return null;
+            }
+            const signifier = status.icon ? (
+              <Icon
+                icon={status.icon}
+                size="xsm"
+                color={
+                  ICON_COLOR_BY_STATUS[status.color as TableRowStatusColor] ??
+                  'primary'
+                }
+              />
+            ) : (
+              <span {...stylex.props(styles.dot(resolveColor(status.color)))} />
+            );
+            return (
+              <Tooltip content={status.label}>
+                <span
+                  {...stylex.props(styles.wrap)}
+                  role="img"
+                  aria-label={status.label}>
+                  {signifier}
+                </span>
+              </Tooltip>
+            );
+          },
+        };
+        return [statusColumn, ...columns];
+      },
+    }),
+    [getStatus],
+  );
+}

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

@@ -7,13 +7,13 @@
  * @position Test file; validates selection behavior (checkboxes, aria, select-all)
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {useState} from 'react';
-import {render, screen, within} from '@testing-library/react';
+import {act, render, renderHook, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Table} from '../../Table';
 import {useTableSelection} from './useTableSelection';
-import type {TableColumn} from '../../types';
+import type {BodyRowRenderProps, TableColumn} from '../../types';
 
 // =============================================================================
 // Test Data
@@ -40,9 +40,11 @@ const selectableColumns: TableColumn<SelectableUser>[] = [
 function SelectionTable({
   getIsItemSelectable,
   getIsItemEnabled,
+  getRowLabel,
 }: {
   getIsItemSelectable?: (item: SelectableUser) => boolean;
   getIsItemEnabled?: (item: SelectableUser) => boolean;
+  getRowLabel?: (item: SelectableUser) => string;
 }) {
   const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());
 
@@ -75,6 +77,7 @@ function SelectionTable({
     },
     getIsItemSelectable,
     getIsItemEnabled,
+    getRowLabel,
   });
 
   return (
@@ -109,6 +112,19 @@ describe('useTableSelection', () => {
     expect(rowCheckboxes).toHaveLength(3);
   });
 
+  it('derives per-row accessible names from getRowLabel', () => {
+    render(<SelectionTable getRowLabel={item => item.name} />);
+    expect(screen.getByLabelText('Select Alice')).toBeInTheDocument();
+    expect(screen.getByLabelText('Select Bob')).toBeInTheDocument();
+    expect(screen.getByLabelText('Select Charlie')).toBeInTheDocument();
+    expect(screen.queryByLabelText('Select row')).not.toBeInTheDocument();
+  });
+
+  it('keeps the "Select all rows" header label when getRowLabel is provided', () => {
+    render(<SelectionTable getRowLabel={item => item.name} />);
+    expect(screen.getByLabelText('Select all rows')).toBeInTheDocument();
+  });
+
   it('toggles individual row selection on click', async () => {
     const user = userEvent.setup();
     render(<SelectionTable />);
@@ -194,4 +210,62 @@ describe('useTableSelection', () => {
     const headers = within(headerRow).getAllByRole('columnheader');
     expect(headers).toHaveLength(3);
   });
+
+  it('unsubscribes detached row refs instead of accumulating listeners', () => {
+    const getIsItemSelected = vi.fn(() => false);
+    const {result, rerender} = renderHook(() =>
+      useTableSelection<SelectableUser>({
+        getIsItemSelected,
+        onSelectItem: vi.fn(),
+        onSelectAll: vi.fn(),
+        getIsAllSelected: () => false,
+      }),
+    );
+
+    const initialProps: BodyRowRenderProps = {
+      htmlProps: {},
+      styles: [],
+      children: null,
+    };
+    const row = document.createElement('tr');
+    document.body.append(row);
+
+    let detach: (() => void) | undefined;
+
+    // Simulate React replacing the callback ref as this row re-renders.
+    // Each detach must unsubscribe the previous ref before the next attaches.
+    for (let i = 0; i < 3; i++) {
+      act(() => {
+        detach?.();
+      });
+
+      const transformed = result.current.transformBodyRow?.(
+        initialProps,
+        selectableUsers[0],
+        0,
+      );
+      expect(transformed?.ref).toBeTypeOf('function');
+
+      act(() => {
+        const cleanup = (
+          transformed?.ref as React.RefCallback<HTMLTableRowElement>
+        )(row);
+        expect(cleanup).toBeTypeOf('function');
+        detach = cleanup as () => void;
+      });
+    }
+
+    getIsItemSelected.mockClear();
+    rerender();
+    expect(getIsItemSelected).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      detach?.();
+    });
+    getIsItemSelected.mockClear();
+    rerender();
+    expect(getIsItemSelected).not.toHaveBeenCalled();
+
+    row.remove();
+  });
 });

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

@@ -68,6 +68,19 @@ export interface UseTableSelectionConfig<T extends Record<string, unknown>> {
   getIsItemSelectable?: (item: T) => boolean;
   /** Is this row's checkbox interactive? Disabled rows show disabled checkbox. @default () => true */
   getIsItemEnabled?: (item: T) => boolean;
+  /**
+   * Derive a human-readable identity for a row, used in the row checkbox's
+   * hidden label as `Select ${getRowLabel(item)}`. Without it, every row
+   * checkbox announces an undifferentiated "Select row" to screen readers.
+   * With `getRowLabel: item => item.name`, checkbox accessible names become
+   * "Select Alice", "Select Bob", and so on.
+   *
+   * @example
+   * ```
+   * getRowLabel: item => item.name
+   * ```
+   */
+  getRowLabel?: (item: T) => string;
 }
 
 // =============================================================================
@@ -235,6 +248,7 @@ function SelectionCellContentInner<T extends Record<string, unknown>>({
   const isSelected = useIsItemSelected(store, item);
   const selectable = config.getIsItemSelectable?.(item) ?? true;
   const enabled = config.getIsItemEnabled?.(item) ?? true;
+  const rowLabel = config.getRowLabel?.(item);
 
   if (!selectable) {
     return null;
@@ -242,7 +256,11 @@ function SelectionCellContentInner<T extends Record<string, unknown>>({
 
   return (
     <CheckboxInput
-      label={t('@astryx.table.selection.selectRow')}
+      label={
+        rowLabel != null
+          ? t('@astryx.table.selection.selectRowNamed', {label: rowLabel})
+          : t('@astryx.table.selection.selectRow')
+      }
       isLabelHidden
       value={isSelected}
       onChange={() =>
@@ -353,6 +371,9 @@ export function useTableSelection<T extends Record<string, unknown>>(
               store.getConfig().getIsItemSelected(item),
             );
           });
+          return () => {
+            unsub();
+          };
         };
 
         return {

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

@@ -205,7 +205,7 @@ const stickyStyles = stylex.create({
   },
 });
 
-// Soft drop shadow over the scrolling region (matches the EPS sticky treatment).
+// Soft drop shadow over the scrolling region (a standard sticky-column shadow treatment).
 // border-collapse tables don't paint box-shadow on cells in Chromium, so it's a
 // ::after gradient strip just past the pinned edge (visible thanks to the cell's
 // overflow: visible). Opacity is gated by the scroll-state variable above.