@astryxdesign/core 0.0.0-bootstrap.0 → 0.0.15

package/src/Table/Table.tsx

@@ -0,0 +1,266 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Table.tsx
+ * @input React, StyleX, BaseTable, theme tokens, types, components
+ * @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/index.ts (exports if types change)
+ * - /apps/storybook/stories/Table.stories.tsx (storybook stories)
+ * - /packages/cli/templates/blocks/components/Table/ (showcase blocks)
+ */
+
+import {useMemo, type ReactElement, type Ref} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {BaseTable} from './BaseTable';
+import {TableContext} from './TableContext';
+import {useBaseTablePlugins} from './useBaseTablePlugins';
+import {mergeProps} from '../utils';
+import {xdsThemeProps} from '../utils/xdsThemeProps';
+import type {
+  BaseTableProps,
+  TableVerticalAlign,
+  TablePlugin,
+  TableRenderProps,
+} from './types';
+
+// =============================================================================
+// 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';
+
+/**
+ * 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 Omit<
+  BaseTableProps<T>,
+  'plugins' | 'components'
+> {
+  /** 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>>;
+}
+
+// =============================================================================
+// 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({
+  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))',
+    },
+  },
+});
+
+function TableScrollWrapper({children}: {children: React.ReactNode}) {
+  return (
+    <div
+      {...mergeProps(
+        xdsThemeProps('table-scroll-wrapper'),
+        stylex.props(
+          scrollWrapperStyles.base,
+          scrollWrapperStyles.containerBleed,
+        ),
+      )}>
+      {children}
+    </div>
+  );
+}
+
+// =============================================================================
+// Table-level styling plugin (only transforms the <table> element)
+// =============================================================================
+
+function buildTableStylePlugin<
+  T extends Record<string, unknown>,
+>(): TablePlugin<T> {
+  return {
+    transformTable(props: TableRenderProps): TableRenderProps {
+      const existingClass = props.htmlProps.className ?? '';
+      const tableClass = xdsThemeProps('table').className;
+      return {
+        ...props,
+        htmlProps: {
+          ...props.htmlProps,
+          className: existingClass
+            ? `${existingClass} ${tableClass}`
+            : tableClass,
+        },
+        styles: [...props.styles, tableStyles.base],
+      };
+    },
+  };
+}
+
+// =============================================================================
+// Table Component
+// =============================================================================
+
+function TableInner<T extends Record<string, unknown>>({
+  density = 'balanced',
+  dividers = 'rows',
+  isStriped = false,
+  hasHover = false,
+  verticalAlign = 'middle',
+  textOverflow = 'wrap',
+  plugins: userPlugins,
+  columns,
+  data,
+  ref,
+  ...rest
+}: TableProps<T> & {ref?: Ref<HTMLTableElement>}): ReactElement {
+  // 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],
+  );
+
+  return (
+    <TableContext value={contextValue}>
+      <BaseTable<T>
+        ref={ref}
+        data={data}
+        columns={columns}
+        plugins={mergedPlugins}
+        textOverflow={textOverflow}
+        scrollWrapper={TableScrollWrapper}
+        {...rest}
+      />
+    </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.
+ * Always set explicit width on columns using proportional() or pixel() — omitting
+ * width skips the minimum width floor, which can cause columns to collapse on mobile.
+ *
+ * @example
+ * ```
+ * <Table
+ *   data={users}
+ *   columns={[
+ *     { key: 'name', header: 'Name', width: proportional(1), renderCell: (u) => (
+ *       <HStack gap={2} align="center">
+ *         <Avatar name={u.name} size="small" />
+ *         <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';

package/src/Table/TableBody.tsx

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+import type React from 'react';
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps} from '../utils';
+import {xdsThemeProps} from '../utils/xdsThemeProps';
+
+export interface TableBodyProps extends BaseProps<HTMLTableSectionElement> {
+  ref?: React.Ref<HTMLTableSectionElement>;
+  children: ReactNode;
+}
+
+export function TableBody({ref, children, xstyle}: TableBodyProps) {
+  return (
+    <tbody
+      ref={ref}
+      {...mergeProps(xdsThemeProps('table-body'), stylex.props(xstyle))}>
+      {children}
+    </tbody>
+  );
+}
+TableBody.displayName = 'TableBody';

package/src/Table/TableCell.doc.mjs

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'TableCell',
+  subComponentOf: 'Table',
+  displayName: 'Table Cell',
+  isHiddenFromOverview: true,
+  description: '<td> wrapper that reads TableContext to apply density padding, font size, and divider borders when used inside Table.',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Cell content.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'TableCell',
+  isHiddenFromOverview: true,
+  displayName: 'Table Cell',
+  description: '<td> 包装器，读取 TableContext 以在 Table 内部使用时应用密度内边距、字体大小和分隔线边框。',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: '单元格内容。',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'TableCell',
+  isHiddenFromOverview: true,
+  displayName: 'Table Cell',
+  description: '<td> wrapper; reads TableContext for density padding, font size, divider borders.',
+  propDescriptions: {
+    children: 'Cell content.',
+  },
+};

package/src/Table/TableCell.tsx

@@ -0,0 +1,184 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TableCell.tsx
+ * @input React, StyleX, TableContext, theme tokens, useTableCellStyles
+ * @output Exports TableCell component, TableCellProps
+ * @position Sub-component; used inside Table children mode
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Table/Table.doc.mjs
+ * - /packages/core/src/Table/index.ts
+ * - /packages/cli/templates/blocks/components/Table/ (showcase blocks)
+ */
+
+import type {ReactNode} from 'react';
+import type {BaseProps} from '../BaseProps';
+import * as stylex from '@stylexjs/stylex';
+import {
+  borderVars,
+  colorVars,
+  spacingVars,
+  typeScaleVars,
+} from '../theme/tokens.stylex';
+import type {StyleXStyles} from '../theme/types';
+import {
+  overflowStyles,
+  wrapStyles,
+  containerEdgeStyles,
+  tableRowMarker,
+} from './table.stylex';
+import {
+  useTableContext,
+  buildDividerStyles,
+  mergeXStyle,
+} from './useTableCellStyles';
+import {mergeProps} from '../utils';
+import {xdsThemeProps} from '../utils/xdsThemeProps';
+
+/** Props for TableCell — thin `<td>` wrapper */
+export interface TableCellProps extends BaseProps<HTMLTableCellElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLTableCellElement>;
+  /** Specifies which cells this cell relates to (used on `<td>` acting as a row header). */
+  scope?: 'col' | 'row' | 'colgroup' | 'rowgroup';
+  /** Space-separated list of header cell IDs this cell is described by. */
+  headers?: string;
+  /** Number of columns this cell spans. Standard HTML `<td>` attribute. */
+  colSpan?: number;
+  /** Number of rows this cell spans. Standard HTML `<td>` attribute. */
+  rowSpan?: number;
+  children?: ReactNode;
+  /**
+   * StyleX styles for layout customization (margins, positioning, sizing).
+   * Must be a `stylex.create()` value — not an inline style object.
+   */
+  xstyle?: StyleXStyles | StyleXStyles[];
+}
+
+const densityStyles = stylex.create({
+  compact: {
+    paddingBlock: spacingVars['--spacing-1'],
+    paddingInline: spacingVars['--spacing-2'],
+    fontSize: typeScaleVars['--text-body-size'],
+    boxSizing: 'border-box',
+  },
+  balanced: {
+    paddingBlock: spacingVars['--spacing-2'],
+    paddingInline: spacingVars['--spacing-3'],
+    fontSize: typeScaleVars['--text-body-size'],
+    boxSizing: 'border-box',
+  },
+  spacious: {
+    paddingBlock: spacingVars['--spacing-3'],
+    paddingInline: spacingVars['--spacing-4'],
+    fontSize: typeScaleVars['--text-body-size'],
+    boxSizing: 'border-box',
+  },
+});
+
+const dividerRowStyles = stylex.create({
+  cell: {
+    borderBottomWidth: {
+      default: borderVars['--border-width'],
+      // Skip border on cells in the last body row to avoid a
+      // redundant line at the bottom of the table.
+      // Scoped to tableRowMarker so only the parent <tr> is checked —
+      // without the scope, <tbody> (also a :last-child) would match
+      // and suppress borders on every row.
+      [stylex.when.ancestor(':last-child', tableRowMarker)]: '0',
+    },
+    borderBottomStyle: 'solid',
+    borderBottomColor: colorVars['--color-border'],
+  },
+});
+
+const dividerColumnStyles = stylex.create({
+  cell: {
+    borderRightWidth: {
+      default: borderVars['--border-width'],
+      ':last-child': '0',
+    },
+    borderRightStyle: 'solid',
+    borderRightColor: colorVars['--color-border'],
+  },
+});
+
+const verticalAlignStyles = stylex.create({
+  middle: {
+    verticalAlign: 'middle',
+  },
+  top: {
+    verticalAlign: 'top',
+  },
+  bottom: {
+    verticalAlign: 'bottom',
+  },
+});
+
+/**
+ * TableCell — a `<td>` wrapper for children/streaming mode.
+ *
+ * When used inside `<Table>`, inherits styling from the table context
+ * (density padding, divider borders). When used standalone, renders a plain `<td>`.
+ *
+ * @example
+ * ```
+ * <TableRow>
+ *   <TableCell>Alice</TableCell>
+ *   <TableCell>30</TableCell>
+ * </TableRow>
+ * ```
+ */
+export function TableCell({
+  children,
+  xstyle,
+  ref,
+  className: incomingClassName,
+  style: incomingStyle,
+  ...props
+}: TableCellProps) {
+  const ctx = useTableContext();
+
+  if (!ctx) {
+    return (
+      <td
+        ref={ref}
+        {...props}
+        {...mergeProps(
+          xdsThemeProps('table-cell'),
+          stylex.props(xstyle),
+          incomingClassName,
+          incomingStyle,
+        )}>
+        {children}
+      </td>
+    );
+  }
+
+  const cellStyles: StyleXStyles[] = [
+    densityStyles[ctx.density],
+    ctx.textOverflow === 'truncate' ? overflowStyles.cell : wrapStyles.cell,
+    containerEdgeStyles[ctx.density],
+    verticalAlignStyles[ctx.verticalAlign],
+    ...buildDividerStyles(ctx, dividerRowStyles.cell, dividerColumnStyles.cell),
+  ];
+
+  return (
+    <td
+      ref={ref}
+      {...props}
+      {...mergeProps(
+        xdsThemeProps('table-cell'),
+        stylex.props(...mergeXStyle(cellStyles, xstyle)),
+        incomingClassName,
+        incomingStyle,
+      )}>
+      {children}
+    </td>
+  );
+}
+
+TableCell.displayName = 'TableCell';

package/src/Table/TableContext.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TableContext.ts
+ * @input React
+ * @output Exports TableContext and TableContextValue
+ * @position Context layer; connects Table styling to sub-components (TableRow, TableCell)
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/Table.tsx (provider)
+ * - /packages/core/src/Table/TableRow.tsx (consumer)
+ * - /packages/core/src/Table/TableCell.tsx (consumer)
+ * - /packages/core/src/Table/index.ts (exports if types change)
+ */
+
+import {createContext} from 'react';
+import type {TableVerticalAlign} from './types';
+
+export interface TableContextValue {
+  density: 'compact' | 'balanced' | 'spacious';
+  dividers: 'rows' | 'columns' | 'grid' | 'none';
+  isStriped: boolean;
+  hasHover: boolean;
+  verticalAlign: TableVerticalAlign;
+  textOverflow: 'wrap' | 'truncate';
+}
+
+export const TableContext = createContext<TableContextValue | null>(null);
+TableContext.displayName = 'TableContext';

package/src/Table/TableFooter.tsx

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+import type React from 'react';
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps} from '../utils';
+import {xdsThemeProps} from '../utils/xdsThemeProps';
+
+export interface TableFooterProps extends BaseProps<HTMLTableSectionElement> {
+  ref?: React.Ref<HTMLTableSectionElement>;
+  children: ReactNode;
+}
+
+export function TableFooter({ref, children, xstyle}: TableFooterProps) {
+  return (
+    <tfoot
+      ref={ref}
+      {...mergeProps(xdsThemeProps('table-footer'), stylex.props(xstyle))}>
+      {children}
+    </tfoot>
+  );
+}
+TableFooter.displayName = 'TableFooter';

package/src/Table/TableHeader.tsx

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+import type React from 'react';
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps} from '../utils';
+import {xdsThemeProps} from '../utils/xdsThemeProps';
+
+export interface TableHeaderProps extends BaseProps<HTMLTableSectionElement> {
+  ref?: React.Ref<HTMLTableSectionElement>;
+  children: ReactNode;
+}
+
+export function TableHeader({ref, children, xstyle}: TableHeaderProps) {
+  return (
+    <thead
+      ref={ref}
+      {...mergeProps(xdsThemeProps('table-header'), stylex.props(xstyle))}>
+      {children}
+    </thead>
+  );
+}
+TableHeader.displayName = 'TableHeader';

package/src/Table/TableHeaderCell.doc.mjs

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'TableHeaderCell',
+  subComponentOf: 'Table',
+  displayName: 'Table Header Cell',
+  isHiddenFromOverview: true,
+  description: '<th> wrapper that reads TableContext to apply density padding, semibold weight, secondary text color, and divider borders when used inside Table.',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Header cell content.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'TableHeaderCell',
+  isHiddenFromOverview: true,
+  displayName: 'Table Header Cell',
+  description: '<th> 包装器，读取 TableContext 以在 Table 内部使用时应用密度内边距、半粗字重、次要文本颜色和分隔线边框。',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: '表头单元格内容。',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'TableHeaderCell',
+  isHiddenFromOverview: true,
+  displayName: 'Table Header Cell',
+  description: '<th> wrapper; reads TableContext for density padding, semibold weight, secondary color, dividers.',
+  propDescriptions: {
+    children: 'Header cell content.',
+  },
+};