@astryxdesign/core 0.1.1 → 0.1.2-canary.2581eb4

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;
@@ -313,8 +319,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 +359,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 +370,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>.
@@ -465,6 +477,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
             <TableHeader>
               <RowComponent
                 {...headerRowRenderProps.htmlProps}
+                isHeaderRow
                 xstyle={headerRowRenderProps.styles}>
                 {headerRowRenderProps.children}
               </RowComponent>
@@ -497,9 +510,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 +524,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 +559,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 +585,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>>',

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'});
@@ -746,11 +753,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 +770,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,37 @@ 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}
+      {...restHtmlProps}
       {...mergeProps(
         themeProps('table-scroll-wrapper'),
         stylex.props(
           scrollWrapperStyles.base,
           scrollWrapperStyles.containerBleed,
+          ...(pluginStyles ?? []),
         ),
       )}>
+      {beforeTable}
       {children}
+      {afterTable}
     </div>
   );
 }

package/src/Table/TableRow.tsx

@@ -34,6 +34,11 @@ export interface TableRowProps extends BaseProps<HTMLTableRowElement> {
    * Must be a `stylex.create()` value — not an inline style object.
    */
   xstyle?: StyleXStyles[];
+  /**
+   * Whether this row is the header row. Header rows skip the striped/hover
+   * row styling (which is only meant for body rows).
+   */
+  isHeaderRow?: boolean;
 }
 
 const stripedRowStyles = stylex.create({
@@ -42,6 +47,13 @@ const stripedRowStyles = stylex.create({
       default: null,
       ':nth-child(even)': colorVars['--color-background-muted'],
     },
+    // Publish the row's current overlay color as an inheritable variable so
+    // pinned/sticky cells (which paint an opaque background over the otherwise
+    // transparent row) can replay the exact same striping. Unset on odd rows.
+    '--table-row-overlay': {
+      default: null,
+      ':nth-child(even)': colorVars['--color-background-muted'],
+    },
   },
 });
 
@@ -53,6 +65,12 @@ const hoverRowStyles = stylex.create({
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
     },
+    '--table-row-overlay': {
+      default: null,
+      ':hover': {
+        '@media (hover: hover)': colorVars['--color-overlay-hover'],
+      },
+    },
     transitionProperty: 'background-color',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -68,6 +86,13 @@ const stripedHoverRowStyles = stylex.create({
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
     },
+    '--table-row-overlay': {
+      default: null,
+      ':nth-child(even)': colorVars['--color-background-muted'],
+      ':hover': {
+        '@media (hover: hover)': colorVars['--color-overlay-hover'],
+      },
+    },
     transitionProperty: 'background-color',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -94,6 +119,7 @@ export function TableRow({
   children,
   xstyle,
   ref,
+  isHeaderRow = false,
   ...props
 }: TableRowProps) {
   const ctx = use(TableContext);
@@ -114,13 +140,17 @@ export function TableRow({
 
   const rowStyles: StyleXStyles[] = [];
 
-  // Handle striped + hover combination to avoid backgroundColor conflicts
-  if (ctx.isStriped && ctx.hasHover) {
-    rowStyles.push(stripedHoverRowStyles.row);
-  } else if (ctx.isStriped) {
-    rowStyles.push(stripedRowStyles.row);
-  } else if (ctx.hasHover) {
-    rowStyles.push(hoverRowStyles.row);
+  // Striped + hover styling is for body rows only — the header row must not
+  // pick up the hover highlight (or striping) even when hasHover/isStriped.
+  if (!isHeaderRow) {
+    // Handle striped + hover combination to avoid backgroundColor conflicts
+    if (ctx.isStriped && ctx.hasHover) {
+      rowStyles.push(stripedHoverRowStyles.row);
+    } else if (ctx.isStriped) {
+      rowStyles.push(stripedRowStyles.row);
+    } else if (ctx.hasHover) {
+      rowStyles.push(hoverRowStyles.row);
+    }
   }
 
   if (ctx.dividers === 'rows' || ctx.dividers === 'grid') {

package/src/Table/index.ts

@@ -27,6 +27,7 @@ export {useTablePagination, paginateData} from './plugins/pagination';
 export {useTableColumnSettings} from './plugins/columnSettings';
 export {useTableColumnSettingsState} from './plugins/columnSettings';
 export {useTableColumnResize} from './plugins/columnResize';
+export {useTableStickyColumns} from './plugins/stickyColumns';
 export {
   useTableFiltering,
   useTableFilterState,
@@ -53,6 +54,7 @@ export type {
   HeaderCellRenderProps,
   BodyRowRenderProps,
   BodyCellRenderProps,
+  ScrollWrapperRenderProps,
   BaseTableProps,
 } from './types';
 export type {
@@ -93,6 +95,7 @@ export type {
   UseTableColumnSettingsStateReturn,
 } from './plugins/columnSettings';
 export type {UseTableColumnResizeConfig} from './plugins/columnResize';
+export type {UseTableStickyColumnsConfig} from './plugins/stickyColumns';
 export type {
   UseTableFilteringConfig,
   TableFilterState,

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

@@ -0,0 +1,4 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {useTableStickyColumns} from './useTableStickyColumns';
+export type {UseTableStickyColumnsConfig} from './useTableStickyColumns';

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

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useTableStickyColumns.test.tsx
+ * @input useTableStickyColumns, Table, React testing utilities
+ * @output Functional tests for the sticky-columns plugin
+ * @position Test file; validates pinning, cumulative offsets, edges, no-op
+ *
+ * Note: `position: sticky` and the z-index/background are applied via StyleX
+ * (compiled to classNames), which jsdom does not resolve to `element.style`.
+ * The plugin sets the per-column *offset* (`insetInlineStart`/`insetInlineEnd`)
+ * as an inline style, so these tests assert on those inline offsets — the
+ * jsdom-visible, plugin-owned signal that a column is pinned and at what offset.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Table} from '../../Table';
+import {useTableStickyColumns} from './useTableStickyColumns';
+import {pixel} from '../../columnUtils';
+import type {TableColumn} from '../../types';
+
+// =============================================================================
+// Test Data
+// =============================================================================
+
+interface Row extends Record<string, unknown> {
+  id: string;
+  name: string;
+  email: string;
+  team: string;
+  status: string;
+}
+
+const data: Row[] = [
+  {id: '1', name: 'Alice', email: 'a@x.com', team: 'DS', status: 'Active'},
+  {id: '2', name: 'Bob', email: 'b@x.com', team: 'Plat', status: 'Away'},
+];
+
+const columns: TableColumn<Row>[] = [
+  {key: 'name', header: 'Name', width: pixel(180)},
+  {key: 'email', header: 'Email', width: pixel(220)},
+  {key: 'team', header: 'Team', width: pixel(160)},
+  {key: 'status', header: 'Status', width: pixel(140)},
+];
+
+function getHeader(name: string): HTMLElement {
+  return screen.getByRole('columnheader', {name});
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('useTableStickyColumns', () => {
+  it('pins a start column at inset-inline-start: 0', () => {
+    function Harness() {
+      const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
+      return (
+        <Table
+          data={data}
+          columns={columns}
+          idKey="id"
+          plugins={{stickyColumns: sticky}}
+        />
+      );
+    }
+    render(<Harness />);
+    expect(getHeader('Name').style.insetInlineStart).toBe('0px');
+  });
+
+  it('computes cumulative start offsets for contiguous pinned columns', () => {
+    function Harness() {
+      const sticky = useTableStickyColumns<Row>({
+        startKeys: ['name', 'email'],
+      });
+      return (
+        <Table
+          data={data}
+          columns={columns}
+          idKey="id"
+          plugins={{stickyColumns: sticky}}
+        />
+      );
+    }
+    render(<Harness />);
+    // name is first → offset 0; email follows → offset = name width (180px)
+    expect(getHeader('Name').style.insetInlineStart).toBe('0px');
+    expect(getHeader('Email').style.insetInlineStart).toBe('180px');
+  });
+
+  it('pins an end column at inset-inline-end: 0', () => {
+    function Harness() {
+      const sticky = useTableStickyColumns<Row>({endKeys: ['status']});
+      return (
+        <Table
+          data={data}
+          columns={columns}
+          idKey="id"
+          plugins={{stickyColumns: sticky}}
+        />
+      );
+    }
+    render(<Harness />);
+    expect(getHeader('Status').style.insetInlineEnd).toBe('0px');
+  });
+
+  it('pins body cells, not just headers', () => {
+    function Harness() {
+      const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
+      return (
+        <Table
+          data={data}
+          columns={columns}
+          idKey="id"
+          plugins={{stickyColumns: sticky}}
+        />
+      );
+    }
+    render(<Harness />);
+    const firstBodyCell = screen.getByText('Alice').closest('td');
+    expect(firstBodyCell).not.toBeNull();
+    expect(firstBodyCell!.style.insetInlineStart).toBe('0px');
+  });
+
+  it('is a no-op with an empty config — no cell gets an offset', () => {
+    function Harness() {
+      const sticky = useTableStickyColumns<Row>({});
+      return (
+        <Table
+          data={data}
+          columns={columns}
+          idKey="id"
+          plugins={{stickyColumns: sticky}}
+        />
+      );
+    }
+    render(<Harness />);
+    for (const header of ['Name', 'Email', 'Team', 'Status']) {
+      const th = getHeader(header);
+      expect(th.style.insetInlineStart).toBe('');
+      expect(th.style.insetInlineEnd).toBe('');
+    }
+  });
+
+  it('only pins configured columns, leaving others unset', () => {
+    function Harness() {
+      const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
+      return (
+        <Table
+          data={data}
+          columns={columns}
+          idKey="id"
+          plugins={{stickyColumns: sticky}}
+        />
+      );
+    }
+    render(<Harness />);
+    expect(getHeader('Name').style.insetInlineStart).toBe('0px');
+    expect(getHeader('Team').style.insetInlineStart).toBe('');
+    expect(getHeader('Team').style.insetInlineEnd).toBe('');
+  });
+});