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

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

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file index.ts
  * @input Imports from Table component files
@@ -27,6 +25,8 @@ 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 {resolveContextActions} from './tableContextMenu';
 export {
   useTableFiltering,
   useTableFilterState,
@@ -48,11 +48,14 @@ export type {
   ProportionalWidth,
   PixelWidth,
   TablePlugin,
+  TableContextAction,
+  TableContextActions,
   TableRenderProps,
   HeaderRowRenderProps,
   HeaderCellRenderProps,
   BodyRowRenderProps,
   BodyCellRenderProps,
+  ScrollWrapperRenderProps,
   BaseTableProps,
 } from './types';
 export type {
@@ -93,6 +96,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/pagination/paginateData.ts

@@ -15,7 +15,8 @@
  *
  * @param data - Full data array
  * @param page - Current page number (1-based)
- * @param pageSize - Number of items per page
+ * @param pageSize - Number of items per page; coerced to a positive integer,
+ *   non-finite values fall back to 10
  * @returns Slice of data for the current page
  *
  * @example
@@ -31,6 +32,12 @@ export function paginateData<T>(
   page: number,
   pageSize: number,
 ): T[] {
-  const start = (page - 1) * pageSize;
-  return data.slice(start, start + pageSize);
+  // Same coercion as Pagination and useTablePagination: a 0/NaN/negative
+  // pageSize would slice every page empty while the pagination chrome still
+  // renders page buttons.
+  const size = Number.isFinite(pageSize)
+    ? Math.max(1, Math.floor(pageSize))
+    : 10;
+  const start = (page - 1) * size;
+  return data.slice(start, start + size);
 }

package/src/Table/plugins/pagination/useTablePagination.test.tsx

@@ -184,6 +184,22 @@ describe('useTablePagination', () => {
       ).toBeTruthy();
     });
 
+    it('guards pageSize 0 against Infinity page counts', () => {
+      render(<PaginatedTable data={generateItems(5)} pageSize={0} />);
+      expect(
+        screen.getByRole('navigation', {name: 'Table pagination'}),
+      ).toBeInTheDocument();
+      // pageSize is coerced to 1, so 5 items produce 5 pages, not Infinity,
+      // and page 1 shows the first item instead of an empty slice
+      expect(
+        screen.queryByRole('button', {name: 'Go to page Infinity'}),
+      ).toBeNull();
+      expect(
+        screen.getByRole('button', {name: 'Go to page 5'}),
+      ).toBeInTheDocument();
+      expect(screen.getByText('Item 1')).toBeInTheDocument();
+    });
+
     it('transformTableContext renders Pagination above table', () => {
       render(
         <PaginatedTable

package/src/Table/plugins/pagination/useTablePagination.tsx

@@ -199,7 +199,7 @@ export function useTablePagination<T extends Record<string, unknown>>(
     totalItems,
     totalPages: totalPagesProp,
     hasMore,
-    pageSize = 10,
+    pageSize: pageSizeConfig = 10,
     onPageSizeChange,
     pageSizeOptions,
     variant = 'pages',
@@ -209,6 +209,13 @@ export function useTablePagination<T extends Record<string, unknown>>(
     label = 'Table pagination',
   } = config;
 
+  // Same guard as Pagination itself: 0/NaN/negative pageSize would produce an
+  // Infinity/NaN totalPages here, which bypasses Pagination's own coercion
+  // because it is passed down as the explicit totalPages prop.
+  const pageSize = Number.isFinite(pageSizeConfig)
+    ? Math.max(1, Math.floor(pageSizeConfig))
+    : 10;
+
   const computedTotalPages =
     totalPagesProp ??
     (totalItems != null ? Math.ceil(totalItems / pageSize) : undefined);

package/src/Table/plugins/sortable/useTableSortable.test.tsx

@@ -7,8 +7,8 @@
  * @position Testing; validates sortable plugin implementation
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {useState} from 'react';
 import {Table} from '../../Table';
@@ -620,3 +620,92 @@ describe('useTableSortable', () => {
     });
   });
 });
+
+// =============================================================================
+// Context-menu actions (colocated with the sortable plugin)
+// =============================================================================
+
+describe('useTableSortable — context menu actions', () => {
+  // jsdom doesn't implement the Popover API; mock it so the menu can "open"
+  // and its items become queryable (as hidden).
+  beforeEach(() => {
+    HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+      this.setAttribute('popover-open', '');
+      const event = new Event('toggle', {bubbles: false});
+      Object.defineProperty(event, 'newState', {value: 'open'});
+      this.dispatchEvent(event);
+    });
+    HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+      this.removeAttribute('popover-open');
+      const event = new Event('toggle', {bubbles: false});
+      Object.defineProperty(event, 'newState', {value: 'closed'});
+      this.dispatchEvent(event);
+    });
+    const originalMatches = HTMLElement.prototype.matches;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (HTMLElement.prototype as any).matches = function (
+      selector: string,
+    ): boolean {
+      if (selector === ':popover-open') {
+        return this.hasAttribute('popover-open');
+      }
+      return originalMatches.call(this, selector);
+    };
+  });
+
+  it('offers Sort ascending/descending on a sortable header, and Clear sort once sorted', () => {
+    render(<SortableTable allowUnsortedState />);
+
+    // Unsorted: asc + desc, no "Clear sort".
+    fireEvent.contextMenu(screen.getByText('Name'));
+    expect(
+      screen.getAllByRole('menuitem', {name: 'Sort ascending', hidden: true})
+        .length,
+    ).toBeGreaterThan(0);
+    expect(
+      screen.getAllByRole('menuitem', {name: 'Sort descending', hidden: true})
+        .length,
+    ).toBeGreaterThan(0);
+    expect(
+      screen.queryByRole('menuitem', {name: 'Clear sort', hidden: true}),
+    ).not.toBeInTheDocument();
+
+    // Apply ascending → "Clear sort" now appears.
+    fireEvent.click(
+      screen.getAllByRole('menuitem', {name: 'Sort ascending', hidden: true})[0],
+    );
+    fireEvent.contextMenu(screen.getByText('Name'));
+    expect(
+      screen.getAllByRole('menuitem', {name: 'Clear sort', hidden: true}).length,
+    ).toBeGreaterThan(0);
+  });
+
+  it('resolves fresh actions on each open as sort state changes (lazy getter)', () => {
+    const onSortChange = vi.fn();
+    render(<SortableTable allowUnsortedState onSortChange={onSortChange} />);
+
+    // Open (unsorted) and pick descending.
+    fireEvent.contextMenu(screen.getByText('Name'));
+    fireEvent.click(
+      screen.getAllByRole('menuitem', {
+        name: 'Sort descending',
+        hidden: true,
+      })[0],
+    );
+    expect(onSortChange).toHaveBeenLastCalledWith([
+      {sortKey: 'name', direction: 'descending'},
+    ]);
+
+    // Re-open: the getter recomputes against the now-descending state, so
+    // "Clear sort" is present and clicking it clears — proving the actions are
+    // freshly derived on each open, not memoized from the first render.
+    fireEvent.contextMenu(screen.getByText('Name'));
+    const clear = screen.getAllByRole('menuitem', {
+      name: 'Clear sort',
+      hidden: true,
+    });
+    expect(clear.length).toBeGreaterThan(0);
+    fireEvent.click(clear[0]);
+    expect(onSortChange).toHaveBeenLastCalledWith([]);
+  });
+});

package/src/Table/plugins/sortable/useTableSortable.tsx

@@ -17,10 +17,12 @@ import {useRef, useMemo, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
+import {resolveContextActions} from '../../tableContextMenu';
 import type {
   TablePlugin,
   HeaderCellRenderProps,
   TableColumn,
+  TableContextAction,
 } from '../../types';
 
 // =============================================================================
@@ -356,10 +358,56 @@ export function useTableSortable<
           return props;
         }
 
-        // Find sort entry for this column
         const cfg = configRef.current;
         const entry = cfg.sort.find(e => e.sortKey === sortKey);
 
+        // Context-menu actions are built lazily (only when the menu opens) via
+        // a getter, reading the current sort state at call time — so we don't
+        // build an action array for every header on every render, and the
+        // checked/clear state always reflects the latest sort.
+        const getSortActions = (): TableContextAction[] => {
+          const c = configRef.current;
+          const dir = c.sort.find(e => e.sortKey === sortKey)?.direction ?? null;
+          const actions: TableContextAction[] = [
+            {
+              id: 'sort-asc',
+              group: 'sort',
+              label: 'Sort ascending',
+              icon: <Icon icon="arrowUp" size="xsm" aria-hidden />,
+              checked: dir === 'ascending',
+              onSelect: () =>
+                c.onSortChange([
+                  {sortKey: sortKey as TSortKey, direction: 'ascending'},
+                ]),
+            },
+            {
+              id: 'sort-desc',
+              group: 'sort',
+              label: 'Sort descending',
+              icon: <Icon icon="arrowDown" size="xsm" aria-hidden />,
+              checked: dir === 'descending',
+              onSelect: () =>
+                c.onSortChange([
+                  {sortKey: sortKey as TSortKey, direction: 'descending'},
+                ]),
+            },
+          ];
+          if (dir != null) {
+            actions.push({
+              id: 'sort-clear',
+              group: 'sort-clear',
+              label: 'Clear sort',
+              icon: <Icon icon="close" size="xsm" aria-hidden />,
+              onSelect: () =>
+                c.onSortChange(c.sort.filter(e => e.sortKey !== sortKey)),
+            });
+          }
+          return actions;
+        };
+
+        // Merge with any actions a prior plugin contributed (array or getter),
+        // resolving both lazily at open time.
+        const priorActions = props.contextMenuActions;
         return {
           ...props,
           htmlProps: {
@@ -375,6 +423,10 @@ export function useTableSortable<
               {props.content}
             </SortHeaderButton>
           ),
+          contextMenuActions: () => [
+            ...resolveContextActions(priorActions),
+            ...getSortActions(),
+          ],
         };
       },
     }),

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('');
+  });
+});