@astryxdesign/core 0.1.8 → 0.1.9

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

@@ -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 />);

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={() =>

package/src/Table/plugins/tree/useTableTreeData.test.tsx

@@ -55,14 +55,18 @@ const columns: TableColumn<FileRow>[] = [
 ];
 
 function TreeTable(
-  props: Partial<UseTableTreeStateConfig<FileRow>> & {data?: FileRow[]},
+  props: Partial<UseTableTreeStateConfig<FileRow>> & {
+    data?: FileRow[];
+    hasExpandAllControl?: boolean;
+  },
 ) {
+  const {hasExpandAllControl, ...stateProps} = props;
   const {visibleData, treeConfig} = useTableTreeState<FileRow>({
     data: props.data ?? fileTree,
     idKey: 'id',
-    ...props,
+    ...stateProps,
   });
-  const tree = useTableTreeData(treeConfig);
+  const tree = useTableTreeData({...treeConfig, hasExpandAllControl});
 
   return (
     <Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />
@@ -592,3 +596,131 @@ describe('useTableTreeData — composition with sorting', () => {
     expect(names).toEqual(['src', 'utils.ts', 'components', 'README.md']);
   });
 });
+
+// =============================================================================
+// header expand-all control
+// =============================================================================
+
+describe('useTableTreeData: expand-all header control', () => {
+  /** The header row is the first row; return its expand-all toggle if present. */
+  function queryExpandAllButton(): HTMLElement | null {
+    const headerRow = screen.getAllByRole('row')[0];
+    return (
+      within(headerRow).queryByRole('button', {name: /expand all/i}) ??
+      within(headerRow).queryByRole('button', {name: /collapse all/i})
+    );
+  }
+
+  it('renders no expand-all control by default', () => {
+    render(<TreeTable defaultExpandedIds={['src']} />);
+    expect(queryExpandAllButton()).toBeNull();
+  });
+
+  it('renders an "Expand all" toggle in the tree column header when enabled and collapsed', () => {
+    render(<TreeTable hasExpandAllControl />);
+    const headerRow = screen.getAllByRole('row')[0];
+    expect(
+      within(headerRow).getByRole('button', {name: /expand all/i}),
+    ).toBeInTheDocument();
+  });
+
+  it('expands every row when the collapsed toggle is clicked', async () => {
+    const user = userEvent.setup();
+    render(<TreeTable hasExpandAllControl />);
+
+    // Collapsed: only roots are visible.
+    expect(getBodyRows()).toHaveLength(2);
+
+    await user.click(
+      within(screen.getAllByRole('row')[0]).getByRole('button', {
+        name: /expand all/i,
+      }),
+    );
+
+    // Every level is now visible.
+    expect(
+      getBodyRows().map(r => within(r).getByText(/.+/, {selector: 'td *'})),
+    ).not.toHaveLength(2);
+    expect(screen.getByText('Button.tsx')).toBeInTheDocument();
+  });
+
+  it('relabels the toggle "Collapse all" once everything is expanded', () => {
+    render(
+      <TreeTable
+        hasExpandAllControl
+        defaultExpandedIds={['src', 'components']}
+      />,
+    );
+    const headerRow = screen.getAllByRole('row')[0];
+    expect(
+      within(headerRow).getByRole('button', {name: /collapse all/i}),
+    ).toBeInTheDocument();
+  });
+
+  it('collapses back to roots when the expanded toggle is clicked', async () => {
+    const user = userEvent.setup();
+    render(
+      <TreeTable
+        hasExpandAllControl
+        defaultExpandedIds={['src', 'components']}
+      />,
+    );
+    expect(screen.getByText('Button.tsx')).toBeInTheDocument();
+
+    await user.click(
+      within(screen.getAllByRole('row')[0]).getByRole('button', {
+        name: /collapse all/i,
+      }),
+    );
+
+    expect(getBodyRows()).toHaveLength(2);
+    expect(screen.queryByText('Button.tsx')).not.toBeInTheDocument();
+  });
+
+  it('marks the toggle aria-expanded=false in the indeterminate (partial) state', () => {
+    // 'src' expanded but 'components' not: partially expanded.
+    render(<TreeTable hasExpandAllControl defaultExpandedIds={['src']} />);
+    const headerRow = screen.getAllByRole('row')[0];
+    const toggle = within(headerRow).getByRole('button', {
+      name: /expand all/i,
+    });
+    expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('does not render the control for flat data even when enabled', () => {
+    const flat: FileRow[] = [
+      {id: 'a', name: 'A', size: 1},
+      {id: 'b', name: 'B', size: 2},
+    ];
+    render(<TreeTable data={flat} hasExpandAllControl />);
+    expect(queryExpandAllButton()).toBeNull();
+  });
+
+  it('renders the toggle inline with the header label, not stacked above it', () => {
+    render(<TreeTable hasExpandAllControl />);
+    const headerRow = screen.getAllByRole('row')[0];
+    const toggle = within(headerRow).getByRole('button', {
+      name: /expand all/i,
+    });
+    // The tree column's <th> holds the label text ('Name'). The bug was that
+    // the toggle went into the `before` slot, which BaseTable renders as a
+    // block sibling of the label, stacking the chevron ABOVE the title. The
+    // fix wraps the label + toggle in one inline-flex container, so they must
+    // share the same immediate parent (the toggle is a sibling of the label,
+    // not in a separate stacked slot).
+    const th = toggle.closest('th');
+    expect(th).not.toBeNull();
+    const label = within(th as HTMLElement).getByText('Name');
+    const wrapper = label.parentElement as HTMLElement;
+    expect(wrapper).toContainElement(toggle);
+    // The toggle precedes the label within that shared wrapper (chevron sits
+    // to the LEFT of the title). StyleX compiles the inline-flex layout to a
+    // class on this wrapper; assert the class is present (real CSS is not
+    // applied in jsdom, so we check the class hook, not computed display).
+    expect(wrapper.className).not.toBe('');
+    const kids = Array.from(wrapper.childNodes);
+    expect(kids.indexOf(toggle)).toBeLessThan(
+      kids.findIndex(n => n.textContent === 'Name' || n.contains(label)),
+    );
+  });
+});

package/src/Table/plugins/tree/useTableTreeData.tsx

@@ -43,7 +43,12 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, radiusVars, spacingVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {mergeRefs} from '../../../utils';
-import type {TablePlugin, TableColumn, BodyRowRenderProps} from '../../types';
+import type {
+  TablePlugin,
+  TableColumn,
+  BodyRowRenderProps,
+  HeaderCellRenderProps,
+} from '../../types';
 import {useTranslator} from '../../../i18n';
 
 // =============================================================================
@@ -78,6 +83,22 @@ export interface UseTableTreeDataConfig<T extends Record<string, unknown>> {
    * identically to a Table without the plugin.
    */
   hasExpandableRows: boolean;
+  /**
+   * Aggregate expansion state across every expandable row. When provided
+   * together with `onExpandAll`/`onCollapseAll`, the tree column header shows
+   * an expand-all toggle. `useTableTreeState` supplies all three.
+   */
+  isAllExpanded?: boolean | 'indeterminate';
+  /** Expand every expandable row. Wired to the header expand-all control. */
+  onExpandAll?: () => void;
+  /** Collapse every row. Wired to the header expand-all control. */
+  onCollapseAll?: () => void;
+  /**
+   * Show the expand-all/collapse-all toggle in the tree column header. Needs
+   * `isAllExpanded` and `onExpandAll`/`onCollapseAll` to be present.
+   * @default false
+   */
+  hasExpandAllControl?: boolean;
   /**
    * Indent step per level, as spacing tokens.
    * @default 'md'
@@ -243,6 +264,13 @@ const treeStyles = stylex.create({
     height: '24px',
     flexShrink: '0',
   },
+  /** Header expand-all toggle: same affordance as a row expander. */
+  headerCell: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    minWidth: 0,
+  },
 });
 
 // =============================================================================
@@ -282,6 +310,53 @@ function TreeExpander({
   );
 }
 
+/**
+ * Header expand-all/collapse-all toggle. Rendered in the tree column header
+ * when `hasExpandAllControl` is set and the state hook supplies the aggregate
+ * `isAllExpanded` plus `onExpandAll`/`onCollapseAll`. Shares the chevron
+ * affordance with the per-row expander; the chevron points down (expanded)
+ * only when every expandable row is expanded, matching the row expander.
+ */
+function TreeExpandAllToggle({
+  isAllExpanded,
+  onExpandAll,
+  onCollapseAll,
+}: {
+  isAllExpanded: boolean | 'indeterminate';
+  onExpandAll: () => void;
+  onCollapseAll: () => void;
+}) {
+  const t = useTranslator();
+  const allExpanded = isAllExpanded === true;
+  return (
+    <button
+      type="button"
+      {...stylex.props(treeStyles.expanderButton)}
+      onClick={e => {
+        e.stopPropagation();
+        if (allExpanded) {
+          onCollapseAll();
+        } else {
+          onExpandAll();
+        }
+      }}
+      aria-label={
+        allExpanded
+          ? t('@astryx.tableTree.collapseAllRows')
+          : t('@astryx.tableTree.expandAllRows')
+      }
+      aria-expanded={allExpanded}>
+      <span
+        {...stylex.props(
+          treeStyles.chevron,
+          allExpanded && treeStyles.chevronExpanded,
+        )}>
+        <Icon icon="chevronRight" size="xsm" />
+      </span>
+    </button>
+  );
+}
+
 function TreeCellContent<T extends Record<string, unknown>>({
   item,
   children,
@@ -380,6 +455,11 @@ export function useTableTreeData<T extends Record<string, unknown>>(
     output: TableColumn<T>[];
   } | null>(null);
 
+  // The resolved tree column key, written by transformColumns (pipeline step 1)
+  // and read by transformHeaderCell (step 4) to place the expand-all toggle on
+  // the same column that carries the row expanders.
+  const treeKeyRef = useRef<string | undefined>(undefined);
+
   // The plugin object is created once per store and never changes shape:
   // every transform reads the live config through the store, and
   // internally no-ops when hasExpandableRows is false. Swapping between
@@ -426,6 +506,7 @@ export function useTableTreeData<T extends Record<string, unknown>>(
           ? treeColumnKey
           : (columns.find(c => !c.key.startsWith('__'))?.key ??
             columns[0]?.key);
+        treeKeyRef.current = treeKey;
 
         // Migration guarantee: flat data renders identically to a Table
         // without the plugin.
@@ -459,6 +540,52 @@ export function useTableTreeData<T extends Record<string, unknown>>(
         return output;
       },
 
+      transformHeaderCell(
+        props: HeaderCellRenderProps,
+        column: TableColumn<T>,
+      ): HeaderCellRenderProps {
+        const {
+          hasExpandableRows,
+          hasExpandAllControl,
+          isAllExpanded,
+          onExpandAll,
+          onCollapseAll,
+        } = store.getConfig();
+
+        // Only the tree column carries the toggle, and only when the control
+        // is enabled, the data is actually hierarchical, and the state hook
+        // supplied the aggregate state plus both handlers. Otherwise this is a
+        // pass-through (flat data stays a no-op).
+        if (
+          !hasExpandAllControl ||
+          !hasExpandableRows ||
+          column.key !== treeKeyRef.current ||
+          isAllExpanded === undefined ||
+          !onExpandAll ||
+          !onCollapseAll
+        ) {
+          return props;
+        }
+
+        // Wrap the header label + the toggle in one inline-flex row so the
+        // chevron sits to the LEFT of the title on the same line. BaseTable
+        // only applies its own flex row for the `after` slot, so a bare
+        // `before` would stack above the label in the block-level <th>.
+        return {
+          ...props,
+          content: (
+            <span {...stylex.props(treeStyles.headerCell)}>
+              <TreeExpandAllToggle
+                isAllExpanded={isAllExpanded}
+                onExpandAll={onExpandAll}
+                onCollapseAll={onCollapseAll}
+              />
+              {props.content}
+            </span>
+          ),
+        };
+      },
+
       transformBodyRow(props: BodyRowRenderProps, item: T) {
         // Attach a ref that subscribes to the store for imperative row
         // ARIA. The ref returns a cleanup so React unsubscribes on