@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Table/BaseTable.tsx

@@ -26,6 +26,7 @@ import type {
   HeaderCellRenderProps,
   BodyRowRenderProps,
   BodyCellRenderProps,
+  ScrollWrapperRenderProps,
   TableRowComponentProps,
   TableCellComponentProps,
   TableHeaderCellComponentProps,
@@ -152,22 +153,27 @@ function TableRowInner<T extends Record<string, unknown>>({
   CellComponent,
 }: TableRowProps<T>): ReactElement {
   // Build cells first
-  const cells = columns.map(col => {
+  const cells = columns.map((col, columnIndex) => {
     // Apply column alignment to body cells
     const initialCellHtmlProps: Record<string, unknown> = {};
     if (col.align) {
       initialCellHtmlProps.style = {textAlign: col.align};
     }
 
+    const initialBodyCellRenderProps: BodyCellRenderProps = {
+      htmlProps: initialCellHtmlProps,
+      styles: [],
+      columnIndex,
+      columns: columns as ReadonlyArray<TableColumn<Record<string, unknown>>>,
+    };
     const cellRenderProps = applyPlugins(
       plugins,
       p => p.transformBodyCell,
-      {
-        htmlProps: initialCellHtmlProps,
-        styles: [],
-      } satisfies BodyCellRenderProps,
+      initialBodyCellRenderProps,
       col,
       item,
+      columnIndex,
+      columns,
     );
 
     const isDefaultRenderer = !col.renderCell;
@@ -199,6 +205,7 @@ function TableRowInner<T extends Record<string, unknown>>({
       <CellComponent
         key={col.key}
         {...cellRenderProps.htmlProps}
+        contextMenuActions={cellRenderProps.contextMenuActions}
         xstyle={cellRenderProps.styles}>
         {content}
       </CellComponent>
@@ -313,8 +320,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
   // Use stable empty array when no plugins provided
   const plugins = pluginsProp ?? (EMPTY_PLUGINS as TablePlugin<T>[]);
 
-  const RowComponent =
-    TableRow as React.ComponentType<TableRowComponentProps>;
+  const RowComponent = TableRow as React.ComponentType<TableRowComponentProps>;
   const CellComponent =
     TableCell as React.ComponentType<TableCellComponentProps>;
   const HeaderCellComponent =
@@ -354,7 +360,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
   } satisfies TableRenderProps);
 
   // --- Plugin pipeline: header cells ---
-  const headerCells = resolvedColumns.map(col => {
+  const headerCells = resolvedColumns.map((col, columnIndex) => {
     const headerContent = col.header ?? col.key;
 
     // Build initial htmlProps with column alignment if specified
@@ -365,15 +371,22 @@ function BaseTableInner<T extends Record<string, unknown>>({
       initialHeaderHtmlProps.style = {textAlign: col.align};
     }
 
+    const initialHeaderRenderProps: HeaderCellRenderProps = {
+      htmlProps: initialHeaderHtmlProps,
+      styles: [],
+      content: headerContent,
+      columnIndex,
+      columns: resolvedColumns as ReadonlyArray<
+        TableColumn<Record<string, unknown>>
+      >,
+    };
     const cellRenderProps = applyPlugins(
       plugins,
       p => p.transformHeaderCell,
-      {
-        htmlProps: initialHeaderHtmlProps,
-        styles: [],
-        content: headerContent,
-      } satisfies HeaderCellRenderProps,
+      initialHeaderRenderProps,
       col,
+      columnIndex,
+      resolvedColumns,
     );
 
     // Apply pre-computed column width styles on the <th>.
@@ -397,29 +410,32 @@ function BaseTableInner<T extends Record<string, unknown>>({
     const hasSlots =
       before != null || after != null || overlay != null || below != null;
 
+    const headerInner = hasSlots ? (
+      <>
+        {before}
+        {after != null ? (
+          <div {...stylex.props(styles.headerLabelRow)}>
+            {resolvedContent}
+            {after}
+          </div>
+        ) : (
+          resolvedContent
+        )}
+        {overlay}
+        {below}
+      </>
+    ) : (
+      resolvedContent
+    );
+
     return (
       <HeaderCellComponent
         key={col.key}
         {...mergedHtmlProps}
         {...headerTitleProp}
+        contextMenuActions={cellRenderProps.contextMenuActions}
         xstyle={cellRenderProps.styles}>
-        {hasSlots ? (
-          <>
-            {before}
-            {after != null ? (
-              <div {...stylex.props(styles.headerLabelRow)}>
-                {resolvedContent}
-                {after}
-              </div>
-            ) : (
-              resolvedContent
-            )}
-            {overlay}
-            {below}
-          </>
-        ) : (
-          resolvedContent
-        )}
+        {headerInner}
       </HeaderCellComponent>
     );
   });
@@ -465,6 +481,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
             <TableHeader>
               <RowComponent
                 {...headerRowRenderProps.htmlProps}
+                isHeaderRow
                 xstyle={headerRowRenderProps.styles}>
                 {headerRowRenderProps.children}
               </RowComponent>
@@ -497,9 +514,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
                 emptyState !== false && (
                   <tr>
                     <td colSpan={resolvedColumns.length}>
-                      {emptyState ?? (
-                        <EmptyState title="No data" isCompact />
-                      )}
+                      {emptyState ?? <EmptyState title="No data" isCompact />}
                     </td>
                   </tr>
                 )}
@@ -513,8 +528,29 @@ function BaseTableInner<T extends Record<string, unknown>>({
   // when columns exceed the container width. This wrapper sits between
   // the <table> and transformTableContext, so plugin chrome (pagination,
   // toolbars) renders outside the scroll area.
+  //
+  // Before rendering the wrapper, run the plugin `transformScrollWrapper`
+  // pipeline so plugins can attach a ref to the scroll container (scroll-aware
+  // sticky shadows, virtualization) and inject before/after chrome.
   if (ScrollWrapper) {
-    tableElement = <ScrollWrapper>{tableElement}</ScrollWrapper>;
+    const scrollWrapperRenderProps = applyPlugins(
+      plugins,
+      p => p.transformScrollWrapper,
+      {
+        htmlProps: {},
+        styles: [],
+      } satisfies ScrollWrapperRenderProps,
+    );
+
+    tableElement = (
+      <ScrollWrapper
+        htmlProps={scrollWrapperRenderProps.htmlProps}
+        styles={scrollWrapperRenderProps.styles}
+        beforeTable={scrollWrapperRenderProps.beforeTable}
+        afterTable={scrollWrapperRenderProps.afterTable}>
+        {tableElement}
+      </ScrollWrapper>
+    );
   }
 
   // Apply transformTableContext from each plugin.
@@ -527,10 +563,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
       try {
         tableElement = plugin.transformTableContext(tableElement);
       } catch (error) {
-        console.error(
-          '[Table] Plugin threw in transformTableContext:',
-          error,
-        );
+        console.error('[Table] Plugin threw in transformTableContext:', error);
       }
     }
   }
@@ -556,9 +589,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
  * />
  * ```
  */
-export const BaseTable = BaseTableInner as <
-  T extends Record<string, unknown>,
->(
+export const BaseTable = BaseTableInner as <T extends Record<string, unknown>>(
   props: BaseTableProps<T> & {ref?: Ref<HTMLTableElement>},
 ) => ReactElement;
 

package/src/Table/Table.doc.mjs

@@ -71,6 +71,18 @@ export const docs = {
       description: 'Applies a hover highlight background to rows on pointer devices.',
       default: 'false',
     },
+    {
+      name: 'verticalAlign',
+      type: "'middle' | 'top' | 'bottom'",
+      description: 'Vertical alignment for body row cells. Controls `vertical-align` on the `<td>` elements.',
+      default: "'middle'",
+    },
+    {
+      name: 'textOverflow',
+      type: "'wrap' | 'truncate'",
+      description: "How body cell text behaves when it exceeds the column width. 'wrap' lets text wrap and the row grow taller; 'truncate' clips with an ellipsis (default-rendered cells show a tooltip on hover when truncated). Header cells always truncate.",
+      default: "'wrap'",
+    },
     {
       name: 'plugins',
       type: 'Record<string, TablePlugin<T>>',
@@ -106,6 +118,7 @@ export const docs = {
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
       { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { guidance: true, description: 'Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum.' },
+      { guidance: true, description: 'Use the data-driven API from React Server Components: proportional(), pixel(), and column definitions without function props are server-safe. Columns using renderCell (or any function prop) need the table wrapped in a "use client" component, since functions cannot cross the server-client boundary.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
       { guidance: false, description: 'Omit width on text-heavy columns; without an explicit proportional() width they have no minimum and can squish to near-zero on mobile.' },
@@ -153,6 +166,7 @@ export const docsDense = {
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
       { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { guidance: true, description: 'Set explicit width on every column via proportional() or pixel(). proportional(1) = equal flex w/ 120px min preventing collapse on narrow viewports. Omitting width skips the minimum.' },
+      { guidance: true, description: 'Data-driven API is RSC-safe: proportional(), pixel(), column defs w/o function props work in Server Components. renderCell (any function prop) requires a "use client" wrapper.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
       { guidance: false, description: 'Omit width on text-heavy columns; w/o explicit proportional() width they have no minimum and can squish to near-zero on mobile.' },

package/src/Table/Table.test.tsx

@@ -245,6 +245,27 @@ describe('BaseTable', () => {
     expect(screen.getAllByRole('row')).toHaveLength(4);
   });
 
+  it('does not apply hover styling to the header row when hasHover is set', () => {
+    // Use the public Table (provides TableContext); BaseTable alone has no
+    // context, so rows wouldn't pick up hover styling at all.
+    const {container} = render(
+      <Table data={users} columns={columns} hasHover />,
+    );
+    const headerRow = container.querySelector('thead tr');
+    const bodyRow = container.querySelector('tbody tr');
+    expect(headerRow).not.toBeNull();
+    expect(bodyRow).not.toBeNull();
+
+    const headerClasses = new Set(
+      (headerRow?.className ?? '').split(/\s+/).filter(Boolean),
+    );
+    // The body row carries hover-styling class(es) that the header row does not.
+    const bodyOnlyClasses = (bodyRow?.className ?? '')
+      .split(/\s+/)
+      .filter(c => c && !headerClasses.has(c));
+    expect(bodyOnlyClasses.length).toBeGreaterThan(0);
+  });
+
   it('auto-generates columns from data keys when columns omitted', () => {
     render(<BaseTable data={users} />);
     const headers = screen.getAllByRole('columnheader');
@@ -276,11 +297,7 @@ describe('BaseTable', () => {
 
   it('uses idKey function to key rows', () => {
     render(
-      <BaseTable
-        data={users}
-        columns={columns}
-        idKey={item => item.email}
-      />,
+      <BaseTable data={users} columns={columns} idKey={item => item.email} />,
     );
     expect(screen.getAllByRole('row')).toHaveLength(4);
   });
@@ -374,9 +391,7 @@ describe('BaseTable', () => {
           htmlProps: {...props.htmlProps, 'data-testid': 'plugin-table'},
         }),
       };
-      render(
-        <BaseTable data={users} columns={columns} plugins={[plugin]} />,
-      );
+      render(<BaseTable data={users} columns={columns} plugins={[plugin]} />);
       expect(screen.getByTestId('plugin-table')).toBeInTheDocument();
     });
 
@@ -387,9 +402,7 @@ describe('BaseTable', () => {
           htmlProps: {...props.htmlProps, 'data-testid': 'plugin-header-row'},
         }),
       };
-      render(
-        <BaseTable data={users} columns={columns} plugins={[plugin]} />,
-      );
+      render(<BaseTable data={users} columns={columns} plugins={[plugin]} />);
       expect(screen.getByTestId('plugin-header-row')).toBeInTheDocument();
     });
 
@@ -404,9 +417,7 @@ describe('BaseTable', () => {
           };
         },
       };
-      render(
-        <BaseTable data={users} columns={columns} plugins={[plugin]} />,
-      );
+      render(<BaseTable data={users} columns={columns} plugins={[plugin]} />);
       expect(receivedKeys).toEqual(['name', 'age', 'email']);
       const headers = screen.getAllByRole('columnheader');
       expect(headers[0]).toHaveAttribute('data-column', 'name');
@@ -423,9 +434,7 @@ describe('BaseTable', () => {
           };
         },
       };
-      render(
-        <BaseTable data={users} columns={columns} plugins={[plugin]} />,
-      );
+      render(<BaseTable data={users} columns={columns} plugins={[plugin]} />);
       expect(receivedItems).toEqual(['Alice', 'Bob', 'Charlie']);
     });
 
@@ -437,9 +446,7 @@ describe('BaseTable', () => {
           return props;
         },
       };
-      render(
-        <BaseTable data={users} columns={columns} plugins={[plugin]} />,
-      );
+      render(<BaseTable data={users} columns={columns} plugins={[plugin]} />);
       // 3 rows * 3 columns = 9 calls
       expect(calls).toHaveLength(9);
       expect(calls[0]).toEqual({col: 'name', name: 'Alice'});
@@ -626,6 +633,16 @@ describe('Table', () => {
     expect(wrapper!.className).toContain('astryx-table-scroll-wrapper');
   });
 
+  it('makes the scroll container keyboard-focusable', () => {
+    render(<Table data={users} columns={columns} />);
+    const table = screen.getByRole('table');
+    const wrapper = table.parentElement;
+    expect(wrapper).toBeTruthy();
+    expect(wrapper!).toHaveAttribute('tabindex', '0');
+    expect(wrapper!).toHaveAttribute('role', 'region');
+    expect(wrapper!).toHaveAttribute('aria-label', 'Table');
+  });
+
   it('uses table-layout: auto in children mode', () => {
     const {container} = render(
       <Table dividers="rows">
@@ -746,11 +763,7 @@ describe('Table', () => {
       }),
     };
     render(
-      <Table
-        data={users}
-        columns={columns}
-        plugins={{custom: userPlugin}}
-      />,
+      <Table data={users} columns={columns} plugins={{custom: userPlugin}} />,
     );
     expect(screen.getByTestId('custom-plugin')).toBeInTheDocument();
   });
@@ -767,11 +780,7 @@ describe('Table', () => {
       },
     };
     render(
-      <Table
-        data={users}
-        columns={columns}
-        plugins={{custom: userPlugin}}
-      />,
+      <Table data={users} columns={columns} plugins={{custom: userPlugin}} />,
     );
     expect(screen.getByTestId('after-xds')).toBeInTheDocument();
   });

package/src/Table/Table.tsx

@@ -30,6 +30,7 @@ import type {
   TablePlugin,
   TableRenderProps,
 } from './types';
+import type {StyleXStyles} from '../theme/types';
 
 // =============================================================================
 // Table Types
@@ -131,17 +132,42 @@ const scrollWrapperStyles = stylex.create({
   },
 });
 
-function TableScrollWrapper({children}: {children: React.ReactNode}) {
+function TableScrollWrapper({
+  children,
+  htmlProps,
+  styles: pluginStyles,
+  beforeTable,
+  afterTable,
+}: {
+  children: React.ReactNode;
+  htmlProps?: React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
+  };
+  styles?: StyleXStyles[];
+  beforeTable?: React.ReactNode;
+  afterTable?: React.ReactNode;
+}) {
+  const {ref, ...restHtmlProps} = htmlProps ?? {};
   return (
     <div
+      ref={ref}
+      // Keyboard-focusable so keyboard users can scroll a horizontally
+      // overflowing table. Callers may override role/aria-label via htmlProps.
+      tabIndex={0}
+      role="region"
+      aria-label="Table"
+      {...restHtmlProps}
       {...mergeProps(
         themeProps('table-scroll-wrapper'),
         stylex.props(
           scrollWrapperStyles.base,
           scrollWrapperStyles.containerBleed,
+          ...(pluginStyles ?? []),
         ),
       )}>
+      {beforeTable}
       {children}
+      {afterTable}
     </div>
   );
 }

package/src/Table/TableCell.tsx

@@ -24,6 +24,8 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {StyleXStyles} from '../theme/types';
+import type {TableContextActions} from './types';
+import {wrapInTableContextMenu} from './tableContextMenu';
 import {
   overflowStyles,
   wrapStyles,
@@ -56,6 +58,12 @@ export interface TableCellProps extends BaseProps<HTMLTableCellElement> {
    * Must be a `stylex.create()` value — not an inline style object.
    */
   xstyle?: StyleXStyles | StyleXStyles[];
+  /**
+   * Right-click actions rendered as a context menu around the cell content.
+   * The cell owns the wrapper so it controls how the menu interacts with its
+   * padding / content. Empty or undefined renders no menu.
+   */
+  contextMenuActions?: TableContextActions;
 }
 
 const densityStyles = stylex.create({
@@ -138,33 +146,27 @@ export function TableCell({
   ref,
   className: incomingClassName,
   style: incomingStyle,
+  contextMenuActions,
   ...props
 }: TableCellProps) {
   const ctx = useTableContext();
 
-  if (!ctx) {
-    return (
-      <td
-        ref={ref}
-        {...props}
-        {...mergeProps(
-          themeProps('table-cell'),
-          stylex.props(xstyle),
-          incomingClassName,
-          incomingStyle,
-        )}>
-        {children}
-      </td>
-    );
-  }
+  // Standalone (no table context) renders plain, with no density/divider styles.
+  const cellStyles: StyleXStyles[] = ctx
+    ? [
+        densityStyles[ctx.density],
+        ctx.textOverflow === 'truncate'
+          ? overflowStyles.cell
+          : wrapStyles.cell,
+        containerEdgeStyles[ctx.density],
+        verticalAlignStyles[ctx.verticalAlign],
+        ...buildDividerStyles(ctx, dividerRowStyles.cell, dividerColumnStyles.cell),
+      ]
+    : [];
 
-  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),
-  ];
+  // The cell owns the context-menu wrapper so it controls how the menu
+  // interacts with its padding / content. No-op when no actions.
+  const content = wrapInTableContextMenu(children, contextMenuActions);
 
   return (
     <td
@@ -176,7 +178,7 @@ export function TableCell({
         incomingClassName,
         incomingStyle,
       )}>
-      {children}
+      {content}
     </td>
   );
 }

package/src/Table/TableHeaderCell.tsx

@@ -25,8 +25,10 @@ import {
   borderVars,
 } from '../theme/tokens.stylex';
 import type {StyleXStyles} from '../theme/types';
+import type {TableContextActions} from './types';
 import {overflowStyles, containerEdgeStyles} from './table.stylex';
 import {useTableContext, mergeXStyle} from './useTableCellStyles';
+import {wrapInTableContextMenu} from './tableContextMenu';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
@@ -42,6 +44,12 @@ export interface TableHeaderCellProps extends BaseProps<HTMLTableCellElement> {
    * Must be a `stylex.create()` value — not an inline style object.
    */
   xstyle?: StyleXStyles | StyleXStyles[];
+  /**
+   * Right-click actions rendered as a context menu around the cell content.
+   * The cell owns the wrapper so it controls how the menu interacts with its
+   * padding / content. Empty or undefined renders no menu.
+   */
+  contextMenuActions?: TableContextActions;
 }
 
 const densityStyles = stylex.create({
@@ -117,41 +125,32 @@ export function TableHeaderCell({
   ref,
   className: incomingClassName,
   style: incomingStyle,
+  contextMenuActions,
   ...props
 }: TableHeaderCellProps) {
   const ctx = useTableContext();
 
-  if (!ctx) {
-    return (
-      <th
-        ref={ref}
-        {...props}
-        {...mergeProps(
-          themeProps('table-header-cell'),
-          stylex.props(xstyle),
-          incomingClassName,
-          incomingStyle,
-        )}>
-        {children}
-      </th>
+  // Header cells always get the bottom divider (separates header from body).
+  // When used standalone (no table context) the cell renders plain, with no
+  // density/divider styles.
+  const cellStyles: StyleXStyles[] = [];
+  if (ctx) {
+    cellStyles.push(
+      headerStyles.cell,
+      densityStyles[ctx.density],
+      headerDividerStyles.cell,
+      overflowStyles.cell,
+      containerEdgeStyles[ctx.density],
     );
+    // Column dividers come from the shared builder (column axis only).
+    if (ctx.dividers === 'columns' || ctx.dividers === 'grid') {
+      cellStyles.push(dividerColumnStyles.cell);
+    }
   }
 
-  // Header cells always get the bottom divider (separates header from body).
-  // Column dividers use the shared buildDividerStyles — but only for
-  // the column axis, since the row divider is the headerDividerStyles.
-  const cellStyles: StyleXStyles[] = [
-    headerStyles.cell,
-    densityStyles[ctx.density],
-    headerDividerStyles.cell,
-    overflowStyles.cell,
-    containerEdgeStyles[ctx.density],
-  ];
-
-  // Only add column dividers from the shared builder
-  if (ctx.dividers === 'columns' || ctx.dividers === 'grid') {
-    cellStyles.push(dividerColumnStyles.cell);
-  }
+  // The cell owns the context-menu wrapper so it controls how the menu
+  // interacts with its padding / content. No-op when no actions.
+  const content = wrapInTableContextMenu(children, contextMenuActions);
 
   return (
     <th
@@ -163,7 +162,7 @@ export function TableHeaderCell({
         incomingClassName,
         incomingStyle,
       )}>
-      {children}
+      {content}
     </th>
   );
 }