@astryxdesign/core 0.1.0 → 0.1.1-canary.080d887

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>>',
@@ -104,7 +116,7 @@ export const docs = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { 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 XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { 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: 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.' },
@@ -128,7 +140,7 @@ export const docsZh = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { 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 XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { 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.' },
     ],
@@ -151,7 +163,7 @@ export const docsDense = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { 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 XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { 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: 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.' },

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