@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/src/Table/BaseTable.tsx

@@ -205,6 +205,7 @@ function TableRowInner<T extends Record<string, unknown>>({
       <CellComponent
         key={col.key}
         {...cellRenderProps.htmlProps}
+        contextMenuActions={cellRenderProps.contextMenuActions}
         xstyle={cellRenderProps.styles}>
         {content}
       </CellComponent>
@@ -409,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>
     );
   });

package/src/Table/Table.doc.mjs

@@ -118,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.' },
@@ -165,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

@@ -633,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', 'group');
+    expect(wrapper!).toHaveAttribute('aria-label', 'Table');
+  });
+
   it('uses table-layout: auto in children mode', () => {
     const {container} = render(
       <Table dividers="rows">

package/src/Table/Table.tsx

@@ -151,6 +151,14 @@ function TableScrollWrapper({
   return (
     <div
       ref={ref}
+      // Keyboard-focusable so keyboard users can scroll a horizontally
+      // overflowing table. Uses role="group" (not "region") so multiple
+      // tables on a page don't create duplicate same-named landmarks
+      // (axe: landmark-unique). Callers may override role/aria-label via
+      // htmlProps.
+      tabIndex={0}
+      role="group"
+      aria-label="Table"
       {...restHtmlProps}
       {...mergeProps(
         themeProps('table-scroll-wrapper'),

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>
   );
 }

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
@@ -28,6 +26,7 @@ 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,
@@ -49,6 +48,8 @@ export type {
   ProportionalWidth,
   PixelWidth,
   TablePlugin,
+  TableContextAction,
+  TableContextActions,
   TableRenderProps,
   HeaderRowRenderProps,
   HeaderCellRenderProps,

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