@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/TabList/index.ts

@@ -12,7 +12,7 @@
  */
 
 export {TabList} from './TabList';
-export type {TabListProps} from './TabList';
+export type {TabListProps, TabListOverflow} from './TabList';
 
 export {Tab} from './Tab';
 export type {TabProps} from './Tab';
@@ -21,4 +21,8 @@ export {TabMenu} from './TabMenu';
 export type {TabMenuProps, TabMenuOption} from './TabMenu';
 
 export {useTabListContext} from './TabListContext';
-export type {TabListSize, TabListLayout} from './TabListContext';
+export type {
+  TabListSize,
+  TabListLayout,
+  TabListPattern,
+} from './TabListContext';

package/src/Table/BaseTable.tsx

@@ -183,9 +183,12 @@ function TableRowInner<T extends Record<string, unknown>>({
     );
 
     const isDefaultRenderer = !col.renderCell;
-    const rawContent = isDefaultRenderer
-      ? defaultCellRenderer(item, col.key)
-      : (col.renderCell?.(item) ?? null);
+    let rawContent: ReactNode = null;
+    if (!cellRenderProps.isContentSuppressed) {
+      rawContent = isDefaultRenderer
+        ? defaultCellRenderer(item, col.key)
+        : (col.renderCell?.(item) ?? null);
+    }
 
     // In truncate mode, wrap default-rendered string content in
     // <Text maxLines={1}> for smart tooltips that only appear
@@ -525,7 +528,12 @@ function BaseTableInner<T extends Record<string, unknown>>({
       {...(ariaRowCount != null ? {'aria-rowcount': ariaRowCount} : null)}
       {...tableRenderProps.htmlProps}
       {...mergeProps(
-        themeProps('base-table'),
+        themeProps('table', undefined, {
+          // `base-table` was a second root on the same <table> element that
+          // `table` names; themes styling it keep working until the next
+          // major.
+          legacyNames: ['base-table'],
+        }),
         stylex.props(...tableRenderProps.xstyle, xstyle),
         [tableRenderProps.htmlProps.className, className]
           .filter(Boolean)

package/src/Table/Table.doc.mjs

@@ -24,7 +24,6 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-base-table'},
       {className: 'astryx-table'},
       {className: 'astryx-table-scroll-wrapper'},
       {className: 'astryx-table-header'},
@@ -33,6 +32,9 @@ export const docs = {
       {className: 'astryx-table-row'},
       {className: 'astryx-table-cell', visualProps: ['density']},
       {className: 'astryx-table-header-cell', visualProps: ['density']},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-base-table', deprecatedFor: 'table'},
     ],
   },
   description: 'Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support. T must extend Record<string, unknown>.',
@@ -107,7 +109,7 @@ export const docs = {
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'Children mode: render TableRow/TableCell directly instead of using data-driven rendering.',
+      description: 'Children mode: compose the table yourself from TableHeader / TableBody / TableFooter, each holding TableRow and TableCell, instead of using data-driven rendering. The children are passed straight to the <table>, so the section is yours to supply. A TableRow placed directly in Table emits <table><tr>, which is invalid HTML and mismatches on hydration (the parser inserts an implied <tbody> for server-rendered markup; React does not on the client). Data-driven mode renders the sections for you.',
     },
     {
       name: 'xstyle',
@@ -116,6 +118,9 @@ export const docs = {
     },
   ],
   components: [
+    {name: 'TableHeader'},
+    {name: 'TableBody'},
+    {name: 'TableFooter'},
     {name: 'TableRow'},
     {name: 'TableCell'},
     {name: 'TableHeaderCell'},
@@ -135,6 +140,7 @@ export const docs = {
     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 Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'In children mode, put every row inside TableHeader, TableBody, or TableFooter. <table> cannot contain a <tr> directly: the HTML parser inserts an implied <tbody> for server-rendered markup and React does not on the client, so unwrapped rows mismatch on hydration.' },
       { 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.' },
@@ -183,6 +189,7 @@ export const docsDense = {
     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 Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'Children mode: wrap rows in TableHeader/TableBody/TableFooter. <table> cannot hold a <tr> directly; the parser adds an implied <tbody> for SSR markup, React does not on the client, so unwrapped rows mismatch on hydration.' },
       { 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.' },

package/src/Table/Table.test.tsx

@@ -369,9 +369,11 @@ describe('BaseTable', () => {
   it('renders children mode instead of data', () => {
     render(
       <BaseTable>
-        <tr>
-          <td>Manual cell</td>
-        </tr>
+        <tbody>
+          <tr>
+            <td>Manual cell</td>
+          </tr>
+        </tbody>
       </BaseTable>,
     );
     expect(screen.getByText('Manual cell')).toBeInTheDocument();
@@ -380,9 +382,11 @@ describe('BaseTable', () => {
   it('does not render thead in children mode without columns', () => {
     const {container} = render(
       <BaseTable>
-        <tr>
-          <td>Content</td>
-        </tr>
+        <tbody>
+          <tr>
+            <td>Content</td>
+          </tr>
+        </tbody>
       </BaseTable>,
     );
     expect(container.querySelector('thead')).toBeNull();
@@ -602,6 +606,41 @@ describe('BaseTable', () => {
       expect(calls[0]).toEqual({col: 'name', name: 'Alice'});
     });
 
+    it('isContentSuppressed renders an empty cell and never calls the column renderer', () => {
+      const rendered: string[] = [];
+      const withRenderer: TableColumn<User>[] = [
+        {
+          key: 'name',
+          header: 'Name',
+          renderCell: item => {
+            rendered.push(item.name);
+            return <b>{item.name}</b>;
+          },
+        },
+      ];
+      const plugin: TablePlugin<User> = {
+        transformBodyCell: (props, _column, item) =>
+          item.name === 'Bob' ? {...props, isContentSuppressed: true} : props,
+      };
+      render(
+        <BaseTable data={users} columns={withRenderer} plugins={[plugin]} />,
+      );
+      expect(rendered).toEqual(['Alice', 'Charlie']);
+      const cells = screen.getAllByRole('cell');
+      expect(cells[1]).toBeEmptyDOMElement();
+      expect(cells[0]).toHaveTextContent('Alice');
+    });
+
+    it('isContentSuppressed also suppresses the default renderer', () => {
+      const plugin: TablePlugin<User> = {
+        transformBodyCell: props => ({...props, isContentSuppressed: true}),
+      };
+      render(<BaseTable data={users} columns={columns} plugins={[plugin]} />);
+      for (const cell of screen.getAllByRole('cell')) {
+        expect(cell).toBeEmptyDOMElement();
+      }
+    });
+
     it('composes multiple plugins sequentially', () => {
       const plugin1: TablePlugin<User> = {
         transformTable: props => ({
@@ -988,14 +1027,16 @@ describe('Table', () => {
   it('renders children mode with TableRow and TableCell', () => {
     render(
       <Table density="balanced" dividers="rows">
-        <TableRow>
-          <TableCell>Streamed A</TableCell>
-          <TableCell>Streamed B</TableCell>
-        </TableRow>
-        <TableRow>
-          <TableCell>Streamed C</TableCell>
-          <TableCell>Streamed D</TableCell>
-        </TableRow>
+        <TableBody>
+          <TableRow>
+            <TableCell>Streamed A</TableCell>
+            <TableCell>Streamed B</TableCell>
+          </TableRow>
+          <TableRow>
+            <TableCell>Streamed C</TableCell>
+            <TableCell>Streamed D</TableCell>
+          </TableRow>
+        </TableBody>
       </Table>,
     );
     expect(screen.getByText('Streamed A')).toBeInTheDocument();
@@ -1004,6 +1045,83 @@ describe('Table', () => {
     expect(screen.getAllByRole('cell')).toHaveLength(4);
   });
 
+  // Children mode hands the children straight to <table> — it does not wrap
+  // them the way the data-driven path does. That is deliberate (it is what
+  // makes the section components composable), but it was never written down,
+  // and a caller who skipped the section shipped `<table><tr>` (#5277).
+  it("children mode renders no tbody of its own — the section is the caller's", () => {
+    const {container} = render(
+      <Table density="balanced">
+        {/* The unwrapped shape is the subject of this test, not a mistake. */}
+        {/* eslint-disable-next-line @astryx/require-table-section */}
+        <TableRow>
+          <TableCell>Unwrapped</TableCell>
+        </TableRow>
+      </Table>,
+    );
+    const table = container.querySelector('table');
+    expect(table?.querySelector('tbody')).toBeNull();
+    expect(Array.from(table?.children ?? []).map(el => el.tagName)).toContain(
+      'TR',
+    );
+  });
+
+  // Columns do not bring a thead with them in children mode — BaseTable's
+  // `children ? children : <>...</>` short-circuits the whole data-driven
+  // branch, header included. The header is TableHeader's job here.
+  it('children mode renders no thead even when columns are supplied', () => {
+    const {container} = render(
+      <Table columns={columns}>
+        <TableBody>
+          <TableRow>
+            <TableCell>Only body</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    expect(container.querySelector('thead')).toBeNull();
+    expect(container.querySelector('tbody > tr')).not.toBeNull();
+  });
+
+  it('children mode renders the thead TableHeader supplies', () => {
+    const {container} = render(
+      <Table columns={columns}>
+        <TableHeader>
+          <TableRow isHeaderRow>
+            <TableCell>H</TableCell>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          <TableRow>
+            <TableCell>B</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const table = container.querySelector('table');
+    expect(Array.from(table?.children ?? []).map(el => el.tagName)).toEqual([
+      'THEAD',
+      'TBODY',
+    ]);
+  });
+
+  it('children mode puts the rows in the tbody TableBody renders', () => {
+    const {container} = render(
+      <Table density="balanced">
+        <TableBody>
+          <TableRow>
+            <TableCell>Wrapped</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const table = container.querySelector('table');
+    expect(
+      Array.from(table?.children ?? []).map(el => el.tagName),
+    ).not.toContain('TR');
+    expect(table?.querySelector('tbody > tr')).not.toBeNull();
+  });
+
   it('passes through idKey string to base table', () => {
     render(<Table data={users} columns={columns} idKey="email" />);
     expect(screen.getAllByRole('row')).toHaveLength(4);

package/src/Table/Table.tsx

@@ -186,16 +186,11 @@ function buildTableStylePlugin<
 >(): TablePlugin<T> {
   return {
     transformTable(props: TableRenderProps): TableRenderProps {
-      const existingClass = props.htmlProps.className ?? '';
-      const tableClass = themeProps('table').className;
+      // The `astryx-table` class itself comes from BaseTable, which renders
+      // the <table> element and now names it `table` (with `base-table` as its
+      // legacy name). Adding it here too would put the token on twice.
       return {
         ...props,
-        htmlProps: {
-          ...props.htmlProps,
-          className: existingClass
-            ? `${existingClass} ${tableClass}`
-            : tableClass,
-        },
         xstyle: [...props.xstyle, tableStyles.base],
       };
     },

package/src/Table/TableBody.doc.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'TableBody',
+  subComponentOf: 'Table',
+  displayName: 'Table Body',
+  isHiddenFromOverview: true,
+  description:
+    '<tbody> wrapper for children mode. Holds the data rows. A row must sit inside a section: <table> cannot contain a <tr> directly, because the HTML parser inserts an implied <tbody> when it parses server-rendered markup and React does not when it renders on the client, so rows written straight into Table mismatch on hydration. The data-driven data={...} mode renders this element itself; in children mode it is yours to supply.',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'The <tbody> rows.',
+      required: true,
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for layout customization. Must be a stylex.create() value: not an inline style object like style={{}}.',
+    },
+  ],
+  theming: {
+    targets: [{className: 'astryx-table-body'}],
+  },
+};
+
+export const docsDense = {
+  name: 'TableBody',
+  isHiddenFromOverview: true,
+  displayName: 'Table Body',
+  description: '<tbody> wrapper for children mode; holds the data rows; children mode does not add one for you',
+  propDescriptions: {
+    children: 'The <tbody> rows.',
+    xstyle: 'StyleX styles for layout customization',
+  },
+};

package/src/Table/TableFooter.doc.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'TableFooter',
+  subComponentOf: 'Table',
+  displayName: 'Table Footer',
+  isHiddenFromOverview: true,
+  description:
+    '<tfoot> wrapper for children mode. Holds summary or total rows beneath the body. A row must sit inside a section: <table> cannot contain a <tr> directly, because the HTML parser inserts an implied <tbody> when it parses server-rendered markup and React does not when it renders on the client, so the two trees mismatch on hydration. Children mode only: the data-driven data={...} path renders a header and a body, never a footer.',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'The <tfoot> rows.',
+      required: true,
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for layout customization. Must be a stylex.create() value: not an inline style object like style={{}}.',
+    },
+  ],
+  theming: {
+    targets: [{className: 'astryx-table-footer'}],
+  },
+};
+
+export const docsDense = {
+  name: 'TableFooter',
+  isHiddenFromOverview: true,
+  displayName: 'Table Footer',
+  description: '<tfoot> wrapper for children mode; holds summary rows',
+  propDescriptions: {
+    children: 'The <tfoot> rows.',
+    xstyle: 'StyleX styles for layout customization',
+  },
+};

package/src/Table/TableHeader.doc.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'TableHeader',
+  subComponentOf: 'Table',
+  displayName: 'Table Header',
+  isHiddenFromOverview: true,
+  description:
+    '<thead> wrapper for children mode. Holds the header row, whose cells are TableHeaderCell. A row must sit inside a section: <table> cannot contain a <tr> directly, because the HTML parser inserts an implied <tbody> when it parses server-rendered markup and React does not when it renders on the client, so the two trees mismatch on hydration. The data-driven data={...} mode renders this element itself whenever columns are supplied; in children mode it is yours to supply.',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'The <thead> rows.',
+      required: true,
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for layout customization. Must be a stylex.create() value: not an inline style object like style={{}}.',
+    },
+  ],
+  theming: {
+    targets: [{className: 'astryx-table-header'}],
+  },
+};
+
+export const docsDense = {
+  name: 'TableHeader',
+  isHiddenFromOverview: true,
+  displayName: 'Table Header',
+  description: '<thead> wrapper for children mode; holds the header row',
+  propDescriptions: {
+    children: 'The <thead> rows.',
+    xstyle: 'StyleX styles for layout customization',
+  },
+};

package/src/Table/TableRow.tsx

@@ -6,7 +6,8 @@
  * @file TableRow.tsx
  * @input React, StyleX, TableContext, theme tokens
  * @output Exports TableRow component, TableRowProps
- * @position Sub-component; used inside Table children mode
+ * @position Sub-component; used inside a Table section (TableHeader /
+ *   TableBody / TableFooter) in children mode
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Table/Table.doc.mjs
@@ -105,13 +106,23 @@ const stripedHoverRowStyles = stylex.create({
  * When used inside `<Table>`, inherits styling from the table context
  * (striped, hover, divider overrides). When used standalone, renders a plain `<tr>`.
  *
+ * Rows go inside a section — `<TableBody>`, `<TableHeader>`, or
+ * `<TableFooter>`. `<table>` cannot contain a `<tr>` directly: the HTML parser
+ * inserts an implied `<tbody>` when it parses server-rendered markup and React
+ * does not when it renders on the client, so the two trees mismatch on
+ * hydration. Children mode passes children straight through, so the section is
+ * the caller's to supply — the data-driven `data={...}` mode renders it for
+ * you.
+ *
  * @example
  * ```
  * <Table>
- *   <TableRow>
- *     <TableCell>Alice</TableCell>
- *     <TableCell>30</TableCell>
- *   </TableRow>
+ *   <TableBody>
+ *     <TableRow>
+ *       <TableCell>Alice</TableCell>
+ *       <TableCell>30</TableCell>
+ *     </TableRow>
+ *   </TableBody>
  * </Table>
  * ```
  */

package/src/Table/plugins/filtering/useTableFiltering.test.tsx

@@ -142,12 +142,15 @@ function FilterTable({
   });
 
   return (
-    <Table
-      data={testData}
-      columns={columns}
-      idKey="id"
-      plugins={{filter: filterPlugin}}
-    />
+    <>
+      <Table
+        data={testData}
+        columns={columns}
+        idKey="id"
+        plugins={{filter: filterPlugin}}
+      />
+      <output data-testid="filters">{JSON.stringify(filters)}</output>
+    </>
   );
 }
 
@@ -210,6 +213,41 @@ describe('useTableFiltering', () => {
       await user.type(textInputs[0], 'Alice');
       expect(textInputs[0]).toHaveValue('Alice');
     });
+
+    it('updates a number filter while typing', async () => {
+      const user = userEvent.setup();
+      render(<FilterTable variant="inline" />);
+      const input = screen.getByRole('spinbutton', {name: 'Filter Age'});
+
+      await user.type(input, '30');
+
+      expect(screen.getByTestId('filters')).toHaveTextContent('{"age":30}');
+    });
+
+    it('restores the pre-edit number filter when an invalid draft blurs', async () => {
+      const user = userEvent.setup();
+      render(<FilterTable variant="inline" />);
+      const input = screen.getByRole('spinbutton', {name: 'Filter Age'});
+
+      await user.type(input, '3·');
+      expect(screen.getByTestId('filters')).toHaveTextContent('{"age":3}');
+      await user.tab();
+
+      expect(screen.getByTestId('filters')).toHaveTextContent('{}');
+    });
+
+    it('restores the pre-edit number filter when Enter rejects a draft', async () => {
+      const user = userEvent.setup();
+      render(<FilterTable variant="inline" />);
+      const input = screen.getByRole('spinbutton', {name: 'Filter Age'});
+
+      await user.type(input, '3·');
+      await user.keyboard('{Enter}');
+
+      expect(input).toHaveValue('3·');
+      expect(input).toHaveAttribute('aria-invalid', 'true');
+      expect(screen.getByTestId('filters')).toHaveTextContent('{}');
+    });
   });
 
   describe('field reference forms', () => {