Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
13.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file Table.tsx
 * @input React, StyleX, BaseTable, the coordinated Table viewport, theme tokens and types
 * @output Exports Table component, TableProps, TableDensity, TableDividers types
 * @position Styled wrapper; the primary table API for consumers
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Table/Table.doc.mjs (props table, features, usage examples)
 * - /packages/core/src/Table/Table.test.tsx (tests for new/changed behavior)
 * - /packages/core/src/Table/__tests__/TableScroll.a11y.chromium.spec.ts (browser scroll behavior)
 * - /packages/core/src/Table/index.ts (exports if types change)
 * - /apps/storybook/stories/Table.stories.tsx (storybook stories)
 * - /packages/cli/assets/templates/blocks/components/Table/ (showcase blocks)
 */

import {use, useMemo, type ReactElement, type Ref} from 'react';
import {TableRuntimeContext, registerTableScrollWrapper} from './tableRuntime';
import {mergeRefs} from '../utils/mergeRefs';
import * as stylex from '@stylexjs/stylex';
import {borderVars, colorVars, focusVars} from '../theme/tokens.stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {BaseTable} from './BaseTable';
import {TableContext} from './TableContext';
import {useBaseTablePlugins} from './useBaseTablePlugins';
import {useScrollableArea} from '../hooks/useScrollableArea';
import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
import type {
  BaseTableProps,
  TableVerticalAlign,
  TablePlugin,
  TableRenderProps,
} from './types';
import type {StyleXStyles} from '../theme/types';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Table/Table.generated';
import {createSharedContext} from '../utils/sharedContext';

registerEnglishFallback(english);

// =============================================================================
// Table Types
// =============================================================================

/** Row density controlling padding and font size */

export type TableDensity = 'compact' | 'balanced' | 'spacious';

/** Divider style between cells */

export type TableDividers = 'rows' | 'columns' | 'grid' | 'none';

/** How body cell text behaves when it exceeds column width */

export type TableTextOverflow = 'wrap' | 'truncate';

interface TableAppearanceProps<T extends Record<string, unknown>> extends Omit<
  BaseTableProps<T>,
  'plugins' | 'components' | 'virtualization'
> {
  /** Row density. @default 'balanced' */
  density?: TableDensity;
  /** Divider style. @default 'rows' */
  dividers?: TableDividers;
  /** Striped even rows. @default false */
  isStriped?: boolean;
  /** Hover highlight on rows. @default false */
  hasHover?: boolean;
  /**
   * Vertical alignment for body row cells.
   * Controls `vertical-align` on `<td>` elements.
   *
   * @default 'middle'
   *
   * @example
   * ```
   * <Table data={items} columns={columns} verticalAlign="top" />
   * ```
   */
  verticalAlign?: TableVerticalAlign;
  /**
   * How body cell text behaves when it exceeds the column width.
   *
   * - `'wrap'` — text wraps and the row grows taller. No content is hidden.
   * - `'truncate'` — text is clipped with an ellipsis. Default-rendered cells
   *   show a tooltip on hover when truncated.
   *
   * Header cells always truncate regardless of this setting.
   *
   * @default 'wrap'
   *
   * @example
   * ```
   * <Table data={logs} columns={columns} textOverflow="wrap" />
   * ```
   */
  textOverflow?: 'wrap' | 'truncate';
  /** Named plugins to extend table behavior */
  plugins?: Record<string, TablePlugin<T>>;
}

/**
 * Props for the styled Table component.
 * Supports both data-driven mode and children mode with TableRow/Cell.
 *
 * @template T - The row data type
 */
export interface TableProps<
  T extends Record<string, unknown>,
> extends TableAppearanceProps<T> {
  /** Fixed-height opt-in. Requires data and explicit idKey; invalid combinations fall back with diagnostics. */
  virtualization?: BaseTableProps<T>['virtualization'];
}

// =============================================================================
// StyleX Styles (table-level only; cell/row/header styles owned by components)
// =============================================================================

const tableStyles = stylex.create({
  base: {
    fontFamily: 'inherit',
    color: colorVars['--color-text-primary'],
  },
});

const scrollWrapperStyles = stylex.create({
  viewport: (height: number) => ({height, maxHeight: height}),
  base: {
    overflowX: 'auto',
    WebkitOverflowScrolling: 'touch',
  },
  containerBleed: {
    marginInlineStart: 'calc(-1 * var(--container-padding-inline-start, 0px))',
    marginInlineEnd: 'calc(-1 * var(--container-padding-inline-end, 0px))',
    width:
      'calc(100% + var(--container-padding-inline-start, 0px) + var(--container-padding-inline-end, 0px))',
    marginTop: {
      default: null,
      ':first-child': 'calc(-1 * var(--container-padding-block-start, 0px))',
    },
    marginBottom: {
      default: null,
      ':last-child': 'calc(-1 * var(--container-padding-block-end, 0px))',
    },
    // As its container's first or last child, the region reaches that block
    // edge. There it takes the published corner, so its ring and fills follow
    // the curve. Every other corner is square.
    borderStartStartRadius: {
      default: '0px',
      ':first-child': 'var(--container-corner-start-start, 0px)',
    },
    borderStartEndRadius: {
      default: '0px',
      ':first-child': 'var(--container-corner-start-end, 0px)',
    },
    borderEndStartRadius: {
      default: '0px',
      ':last-child': 'var(--container-corner-end-start, 0px)',
    },
    borderEndEndRadius: {
      default: '0px',
      ':last-child': 'var(--container-corner-end-end, 0px)',
    },
  },
  // The wrapper bleeds to its container's edges, under a Card's border, and
  // the Card clips there, so its keyboard ring sits inside its own box, clear
  // of that border too.
  focusRingInset: {
    outlineOffset: {
      default: null,
      ':focus-visible': `calc(-1 * (${focusVars['--focus-outline-width']} + ${borderVars['--border-width']}))`,
    },
  },
});

/**
 * The Table's own name, for the scroll region that names itself after it.
 * Internal to Table: the scroll wrapper is not given it as a prop, so it adds
 * nothing to the public table types.
 */
const TableNameContext = createSharedContext<{
  label?: string;
  labelledBy?: string;
} | null>('TableNameContext', 1, null);
TableNameContext.displayName = 'TableNameContext';

function TableScrollWrapper({
  children,
  htmlProps,
  xstyle: pluginStyles,
  beforeTable,
  afterTable,
}: {
  children: React.ReactNode;
  htmlProps?: React.HTMLAttributes<HTMLDivElement> & {
    ref?: React.Ref<HTMLDivElement>;
  };
  xstyle?: StyleXStyles[];
  beforeTable?: React.ReactNode;
  afterTable?: React.ReactNode;
}) {
  const t = useComponentTranslator();
  const tableName = use(TableNameContext);
  // The focusable scroll region takes the table's own name (spec:AST-025
  // FR12), so two tables are not two groups both named "Table". It is named
  // the way the table is: `aria-labelledby` wins over `aria-label`, as it does
  // in accessible-name computation; the generic name is the fallback for an
  // unnamed table.
  const labelledBy = tableName?.labelledBy;
  const label =
    labelledBy != null
      ? undefined
      : (tableName?.label ?? t('@astryx.table.label'));
  const runtime = use(TableRuntimeContext);
  const viewportHeight = runtime?.viewportHeight;
  const hasBlockViewport = viewportHeight != null;
  const {getViewportProps, getContentProps, state} = useScrollableArea({
    axis: hasBlockViewport ? 'both' : 'inline',
    keyboardAccess: {owner: 'content'},
    overscroll: 'contain',
  });
  // The spread below replaces className and style. Merge the plugin's instead.
  const {
    ref,
    className: pluginClassName,
    style: pluginStyle,
    ...restHtmlProps
  } = htmlProps ?? {};
  const wrapperRef = useMemo(
    () => mergeRefs(ref, runtime?.setViewport),
    [ref, runtime?.setViewport],
  );
  const viewportProps = getViewportProps<HTMLDivElement>({
    role: 'group',
    'aria-label': label,
    // A plugin's explicit name stays authoritative (Table FR1).
    'aria-labelledby':
      restHtmlProps['aria-label'] == null ? labelledBy : undefined,
    ...(state.inline.isScrollable || state.block.isScrollable
      ? {tabIndex: 0}
      : {}),
    // Reads the corner its container publishes (scrollWrapperStyles).
    'data-container-corner': '',
    ...restHtmlProps,
    ref: wrapperRef,
    ...mergeProps(
      themeProps('table-scroll-wrapper'),
      stylex.props(
        scrollWrapperStyles.base,
        scrollWrapperStyles.containerBleed,
        // A tab stop once the table scrolls inline: the shared ring, which a
        // theme restyles through the focus-outline tokens.
        focusOutlineStyles.focusVisible,
        scrollWrapperStyles.focusRingInset,
        hasBlockViewport && scrollWrapperStyles.viewport(viewportHeight),
        ...(pluginStyles ?? []),
      ),
      pluginClassName,
      pluginStyle,
    ),
  });

  if (hasBlockViewport) {
    viewportProps.style = {...viewportProps.style, overscrollBehaviorY: 'auto'};
  }
  return (
    <div {...viewportProps}>
      <div {...getContentProps<HTMLDivElement>()}>
        {beforeTable}
        {children}
        {afterTable}
      </div>
    </div>
  );
}

// =============================================================================
// Table-level styling plugin (only transforms the <table> element)
// =============================================================================

function buildTableStylePlugin<
  T extends Record<string, unknown>,
>(): TablePlugin<T> {
  return {
    transformTable(props: TableRenderProps): TableRenderProps {
      // The `astryx-table` class itself comes from BaseTable, which renders
      // the <table> element and names it with the canonical `table` target.
      // Adding it here too would put the token on twice.
      return {
        ...props,
        xstyle: [...props.xstyle, tableStyles.base],
      };
    },
  };
}

// =============================================================================
// Table Component
// =============================================================================

registerTableScrollWrapper(TableScrollWrapper);

function TableInner<T extends Record<string, unknown>>({
  density = 'balanced',
  dividers = 'rows',
  isStriped = false,
  hasHover = false,
  verticalAlign = 'middle',
  textOverflow: textOverflowProp,
  virtualization,
  plugins: userPlugins,
  columns,
  data,
  ref,
  ...rest
}: TableProps<T> & {ref?: Ref<HTMLTableElement>}): ReactElement {
  const textOverflow =
    textOverflowProp ?? (virtualization == null ? 'wrap' : 'truncate');
  // Table-level styling plugin (just adds font/color to <table>)
  const tablePlugin = useMemo(() => buildTableStylePlugin<T>(), []);
  const basePlugins = useMemo(() => [tablePlugin], [tablePlugin]);

  // Convert named plugin record to stable memoized array
  const mergedPlugins = useBaseTablePlugins<T>(basePlugins, userPlugins);

  const contextValue = useMemo(
    () => ({
      density,
      dividers,
      isStriped,
      hasHover,
      verticalAlign,
      textOverflow,
    }),
    [density, dividers, isStriped, hasHover, verticalAlign, textOverflow],
  );
  const tableLabel = rest['aria-label'];
  const tableLabelledBy = rest['aria-labelledby'];
  const tableName = useMemo(
    () => ({label: tableLabel, labelledBy: tableLabelledBy}),
    [tableLabel, tableLabelledBy],
  );

  return (
    <TableContext value={contextValue}>
      <TableNameContext value={tableName}>
        <BaseTable<T>
          ref={ref}
          data={data}
          columns={columns}
          plugins={mergedPlugins}
          textOverflow={textOverflowProp}
          virtualization={virtualization}
          scrollWrapper={TableScrollWrapper}
          {...rest}
        />
      </TableNameContext>
    </TableContext>
  );
}

/**
 * Table — a styled, data-driven table component.
 *
 * Wraps BaseTable with styled components (TableRow, TableCell,
 * TableHeaderCell) that read appearance configuration from TableContext.
 * Density, dividers, striped rows, and hover effects are applied via
 * design tokens in the component styles.
 *
 * @compositionHint Use renderCell on columns to compose rich cell content.
 * Combine with Badge (status labels), StatusDot (colored indicators),
 * Text (formatted values), Avatar (user cells), and HStack/VStack
 * (multi-element cell layouts). Without renderCell, cells render as plain text.
 * Columns without width remain equally flexible with a compact 60px readability
 * floor. Set one column's floor with proportional(1, { minWidth }), weight
 * columns with proportional(n), and fix widths with pixel().
 *
 * @example
 * ```
 * <Table
 *   data={users}
 *   columns={[
 *     { key: 'name', header: 'Name', width: proportional(1), renderCell: (u) => (
 *       <HStack gap={2} align="center">
 *         <Avatar name={u.name} size="md" />
 *         <Text weight="semibold">{u.name}</Text>
 *       </HStack>
 *     )},
 *     { key: 'status', header: 'Status', width: proportional(1), renderCell: (u) => (
 *       <Badge variant={u.active ? 'success' : 'error'} label={u.active ? 'Active' : 'Inactive'} />
 *     )},
 *   ]}
 *   density="compact"
 *   dividers="grid"
 *   hasHover
 * />
 * ```
 */
export const Table = TableInner as <T extends Record<string, unknown>>(
  props: TableProps<T> & {ref?: Ref<HTMLTableElement>},
) => ReactElement;

// eslint-disable-next-line @typescript-eslint/no-explicit-any
(Table as any).displayName = 'Table';