Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): grouped-table template rendered rows outside a tbody (#5278)

AKb6c0501302f9
diff --git a/.changeset/table-grouped-template-table-body.md b/.changeset/table-grouped-template-table-body.md
new file mode 100644
index 0000000000..412baf5094
--- /dev/null
+++ b/.changeset/table-grouped-template-table-body.md
@@ -0,0 +1,19 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Table - Grouped page template: wrap the rows in `TableBody`
+
+The template rendered `<TableRow>` straight into `<Table>`, so the emitted DOM
+was `<table><tr>`. `<table>` cannot contain a row 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 anyone who copied the template into
+an app as a server-rendered page inherited a hydration mismatch in their own
+app. Client-only the DOM is still invalid — nothing reparents the rows, so the
+table ends up with `<tr>` children and no `<tbody>` at all, and any CSS or
+query aimed at `tbody` silently misses.
+
+The rows now sit in `<TableBody>`, the same element the data-driven `data={...}`
+path renders, so styling, dividers, and column widths are unchanged.
+
+@AKnassa @rubyycheung
diff --git a/.changeset/table-section-component-docs.md b/.changeset/table-section-component-docs.md
new file mode 100644
index 0000000000..1c1eea1bf8
--- /dev/null
+++ b/.changeset/table-section-component-docs.md
@@ -0,0 +1,20 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Table: document the section components children mode requires
+
+Children mode stopped wrapping children in a `<tbody>` in #2098, but the docs
+still described the contract from before it. The `children` prop read "render
+TableRow/TableCell directly"; `TableRow`'s own `@example` showed a row sitting
+in `<Table>` with no section around it; and `TableHeader`, `TableBody`, and
+`TableFooter` — public exports since that change — had no docs at all and were
+missing from `Table`'s component list. A reader following the component's own
+documentation wrote `<table><tr>`, which is invalid HTML and mismatches on
+hydration.
+
+The three section components are now documented, listed on `Table`, and named
+in the `children` prop description, in a best practice, and in `TableRow`'s
+example.
+
+@AKnassa @rubyycheung
diff --git a/eslint.config.js b/eslint.config.js
index 24481eeea7..2824ddf1be 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -202,6 +202,23 @@ export default defineConfig(
'@astryx/copyright-header': 'error',
},
},
+ // Table rows must sit inside a table section. `<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 (#5277). Repo-wide, not
+ // core-only — the shape reached a shipped CLI page template, which consumers
+ // copy into their own apps, and the @eslint-react DOM rules below are scoped
+ // to packages/core/src.
+ {
+ files: ["**/*.{ts,tsx}"],
+ ignores: ["**/*.d.ts", "**/dist/**"],
+ plugins: {
+ '@astryx': astryxEslintPlugin,
+ },
+ rules: {
+ '@astryx/require-table-section': 'error',
+ },
+ },
// Locale-sensitive formatting in shipped packages must go through the
// provider-aware locale utilities, never raw Intl — see the rule's own doc
// comment and internal/eslint-plugin-astryx/README.md for the approved
diff --git a/internal/eslint-plugin-astryx/README.md b/internal/eslint-plugin-astryx/README.md
index 01b7bac388..a57e14e470 100644
--- a/internal/eslint-plugin-astryx/README.md
+++ b/internal/eslint-plugin-astryx/README.md
@@ -647,3 +647,103 @@ imported handler is treated as unknown and not flagged. A `role`/`type`/
`contentEditable` spread via `{...props}` is not seen.
See: https://github.com/facebook/astryx/issues/4892
+
+### `@astryx/require-table-section`
+
+Flags a `TableRow` (or a raw `tr`) written as a **direct child of a table** —
+`Table`, `BaseTable`, or a raw `table` — instead of inside a section:
+`TableHeader` / `TableBody` / `TableFooter`, or a raw `thead` / `tbody` /
+`tfoot`.
+
+`<table>`'s content model does not admit `<tr>`. The HTML parser applies
+implied-`<tbody>` insertion, so when a server-rendered page is parsed the
+browser silently wraps the rows in a `<tbody>` the author never wrote. React's
+client render does not — `appendChild` puts the `<tr>` exactly where the tree
+says. The two trees then disagree and the render hydration-mismatches. React
+says so up front:
+
+```
+In HTML, <tr> cannot be a child of <table>. Add a <tbody>, <thead> or <tfoot>
+to your code to match the DOM tree generated by the browser.
+```
+
+Client-only it is still wrong: nothing reparents the rows, so the table ends up
+with `<tr>` children and no `<tbody>` at all, and any CSS or query aimed at
+`tbody` silently misses.
+
+`Table`'s data-driven mode (`data={...}`) renders its own `TableBody` and is
+unaffected. Children mode passes children straight to the `<table>`, which is
+the right API — it is what makes the section components composable — but it
+makes the section the caller's job, and nothing said so: the `children` prop
+doc described the pre-`#2098` contract, and `TableRow`'s own `@example` showed
+a row directly inside `<Table>`. A shipped page template was written from that
+documentation.
+
+**Bad:**
+
+```tsx
+<Table columns={columns}>
+ <colgroup>…</colgroup>
+ {rows.map(r => (
+ <TableRow key={r.id}>…</TableRow>
+ ))}
+</Table>
+```
+
+**Good:**
+
+```tsx
+<Table columns={columns}>
+ <colgroup>…</colgroup>
+ <TableBody>
+ {rows.map(r => (
+ <TableRow key={r.id}>…</TableRow>
+ ))}
+ </TableBody>
+</Table>
+```
+
+`<colgroup>`, `<col>`, and `<caption>` are legal direct children of a table and
+are not touched.
+
+**Scope:** repo-wide (`**/*.{ts,tsx}`), not core-only. The shape reached a
+shipped CLI page template, which consumers copy into their own apps as a page,
+and the `@eslint-react` DOM rules are scoped to `packages/core/src`. This is the
+`<table>` counterpart of `no-raw-paragraph`: both guard an HTML content model
+that browsers repair on parse and React does not.
+
+Ships as an **error in both tiers**: the repo is clean after the fixes in the
+commit below this one, and this keeps it that way.
+
+**How the walk decides.** The check is lexical. It walks up from the row through
+the wrappers that are transparent in the DOM — fragments, expression containers,
+`&&`/ternary guards, `if`/`switch`/`try` inside a callback, array literals and
+JSX spread children — and reports only when the first real element it reaches is
+the table.
+
+Calls are the subtle part, and the transparency there is **position-aware**, not
+a node-type lookup. The walk steps out of a callback only for `.map()` and
+`.flatMap()`, whose result is spliced into the JSX position the call occupies,
+and it follows a chain chained off that result (`rows.map(...).filter(Boolean)`).
+It does **not** step out of a call whose argument is the row itself: a row handed
+to a function is data, not placement, and the callee routinely puts it somewhere
+valid. `wrapInBody(<TableRow/>)` and
+`React.createElement('tbody', null, <TableRow/>)` are silent for that reason —
+flagging them told authors to wrap code that was already correct.
+
+Element names resolve on their last segment, so `Astryx.TableRow` is a row and
+`Rx.Fragment` is a fragment. There is no import resolution, deliberately: the
+rule already trusts a bare `Table`, and resolving the segment applies that same
+trade consistently.
+
+**Known limitations (intentional false-negatives):** a row that has left its
+lexical position — assigned to a variable, returned from a named helper, passed
+as a prop, or handed to a function as an argument — could land anywhere, so the
+rule stays silent rather than guessing. The same goes for an aliased import
+(`<DataTable>`), a sequence expression, and an awaited wrapper such as
+`await Promise.all(rows.map(...))`. Each of those is pinned as a valid fixture in
+the tests, so a change in that behaviour has to be deliberate. A deliberate
+unwrapped row (the contract test in `Table.test.tsx`) opts out with an
+`eslint-disable-next-line` and a reason.
+
+See: https://github.com/facebook/astryx/issues/5277
diff --git a/internal/eslint-plugin-astryx/index.js b/internal/eslint-plugin-astryx/index.js
index 3443c094f1..1791069e75 100644
--- a/internal/eslint-plugin-astryx/index.js
+++ b/internal/eslint-plugin-astryx/index.js
@@ -15,6 +15,7 @@
* - no-unguarded-ime-keydown: Flags an onKeyDown on an editable surface that branches on command keys without an IME composition guard (isImeKeyEvent/isComposing)
* - no-classname-clobber: Flags two className sources on one JSX element — a literal className/style beside {...stylex.props()}, or two spreads that each carry a className (the later one silently wins)
* - no-hover-on-disabled: Flags a :hover condition that can still match a disabled element (browsers suppress a disabled control's events, not its hover styling)
+ * - require-table-section: Requires TableRow/tr to sit inside TableHeader/TableBody/TableFooter (a row directly inside a table emits <table><tr>, which browsers repair on parse and React does not)
* - disabled-cursor: Flags a cursor that promises an interaction without giving way to not-allowed on a disabled element
*
* Philosophy: Strict for agents (CI), lenient for humans (local dev)
@@ -48,6 +49,7 @@ import requireBasePropsRule from './require-base-props.js';
import requireRefPropRule from './require-ref-prop.js';
import noHardcodedI18nStringRule from './no-hardcoded-i18n-string.js';
import i18nKeyFormatRule from './i18n-key-format.js';
+import requireTableSectionRule from './require-table-section.js';
// =============================================================================
// Rule: no-hardcoded-styles
@@ -274,6 +276,7 @@ const plugin = {
'no-raw-console-cli': noRawConsoleCliRule,
'no-hardcoded-i18n-string': noHardcodedI18nStringRule,
'i18n-key-format': i18nKeyFormatRule,
+ 'require-table-section': requireTableSectionRule,
},
configs: {},
};
@@ -340,6 +343,9 @@ plugin.configs.strict = {
'@astryx/copyright-header': 'error',
'@astryx/no-hardcoded-i18n-string': 'error',
'@astryx/i18n-key-format': 'error',
+ // A row directly inside a table is invalid DOM and hydration-unsafe, and
+ // the repo is clean — error in both tiers so it stays that way (#5277).
+ '@astryx/require-table-section': 'error',
},
};
@@ -394,6 +400,9 @@ plugin.configs.recommended = {
'@astryx/copyright-header': 'error',
'@astryx/no-hardcoded-i18n-string': 'warn',
'@astryx/i18n-key-format': 'warn',
+ // A row directly inside a table is invalid DOM and hydration-unsafe, and
+ // the repo is clean — error in both tiers so it stays that way (#5277).
+ '@astryx/require-table-section': 'error',
},
};
diff --git a/internal/eslint-plugin-astryx/require-table-section.js b/internal/eslint-plugin-astryx/require-table-section.js
new file mode 100644
index 0000000000..68e4151055
--- /dev/null
+++ b/internal/eslint-plugin-astryx/require-table-section.js
@@ -0,0 +1,236 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file require-table-section.js
+ * @description Require table rows to sit inside a table section
+ * (`TableHeader` / `TableBody` / `TableFooter`, or a raw
+ * `thead` / `tbody` / `tfoot`) rather than directly inside the table.
+ *
+ * `<table>`'s content model does not admit `<tr>`. When a row is written as a
+ * direct child of a table, the HTML parser applies implied-`<tbody>`
+ * insertion: it silently wraps the rows in a `<tbody>` the author never
+ * wrote. React's client render does not — `appendChild` places the `<tr>`
+ * exactly where the tree says. So the server's parsed markup and the client's
+ * tree disagree, and the render hydration-mismatches. React flags it up front:
+ *
+ * In HTML, <tr> cannot be a child of <table>. Add a <tbody>, <thead> or
+ * <tfoot> to your code to match the DOM tree generated by the browser.
+ *
+ * Client-only, it is still wrong: the rows are never reparented, so the table
+ * ends up with `<tr>` children and no `<tbody>` at all, and any CSS or query
+ * targeting `tbody` silently misses.
+ *
+ * `Table`'s data-driven mode (`data={...}`) renders its own `TableBody`, so it
+ * is unaffected. Children mode hands the children straight to `<table>`
+ * (BaseTable renders `{children ? children : <>…</>}`), which is the right API
+ * — it is what makes `TableHeader`/`TableBody`/`TableFooter` composable — but
+ * it means the section is the caller's job, and nothing said so.
+ *
+ * This is the `<table>` counterpart of no-raw-paragraph: both guard an HTML
+ * content model that browsers repair on parse and React does not.
+ *
+ * Bad:
+ * <Table columns={columns}>
+ * <colgroup>…</colgroup>
+ * {rows.map(r => <TableRow key={r.id}>…</TableRow>)}
+ * </Table>
+ *
+ * Good:
+ * <Table columns={columns}>
+ * <colgroup>…</colgroup>
+ * <TableBody>
+ * {rows.map(r => <TableRow key={r.id}>…</TableRow>)}
+ * </TableBody>
+ * </Table>
+ *
+ * The rule walks up from each row through the wrappers that are transparent in
+ * the DOM — fragments, expression containers, `&&`/ternary guards, and the
+ * arrow bodies of an inline `.map()` — and reports only when the first real
+ * element it reaches is the table itself. If the row's lexical parent is
+ * anything else (another component, a variable, a named helper), where it
+ * lands is not knowable from this file and the rule stays silent.
+ */
+
+const ROW_ELEMENTS = new Set(['TableRow', 'tr']);
+
+const SECTION_ELEMENTS = new Set([
+ 'TableHeader',
+ 'TableBody',
+ 'TableFooter',
+ 'thead',
+ 'tbody',
+ 'tfoot',
+]);
+
+const TABLE_ELEMENTS = new Set(['Table', 'BaseTable', 'table']);
+
+// JSX elements that render nothing of their own, so a row inside one is still
+// a direct child of whatever encloses it.
+const FRAGMENT_ELEMENTS = new Set(['Fragment']);
+
+// Expression and statement nodes a row can sit inside while remaining, in the
+// emitted DOM, a direct child of the enclosing element.
+const TRANSPARENT_NODES = new Set([
+ 'JSXFragment',
+ 'JSXExpressionContainer',
+ 'JSXSpreadChild',
+ 'ConditionalExpression',
+ 'LogicalExpression',
+ 'ArrayExpression',
+ 'ReturnStatement',
+ 'BlockStatement',
+ 'IfStatement',
+ 'SwitchStatement',
+ 'SwitchCase',
+ 'TryStatement',
+ 'CatchClause',
+ 'ArrowFunctionExpression',
+ 'FunctionExpression',
+ 'ChainExpression',
+ 'TSAsExpression',
+ 'TSSatisfiesExpression',
+ 'TSNonNullExpression',
+]);
+
+// Array methods whose result is spliced straight into the JSX position the call
+// occupies. Stepping out of one of these callbacks keeps the row where it looks
+// like it is; stepping out of any other call does not.
+const SPLICING_METHODS = new Set(['map', 'flatMap']);
+
+/** Flatten a JSX element name to a string: `Table`, `React.Fragment`, `svg:a`. */
+function nameOf(name) {
+ if (!name) {
+ return null;
+ }
+ if (name.type === 'JSXIdentifier') {
+ return name.name;
+ }
+ if (name.type === 'JSXMemberExpression') {
+ const object = nameOf(name.object);
+ const property = nameOf(name.property);
+ return object && property ? `${object}.${property}` : null;
+ }
+ if (name.type === 'JSXNamespacedName') {
+ return `${name.namespace.name}:${name.name.name}`;
+ }
+ return null;
+}
+
+function elementName(node) {
+ return node?.type === 'JSXElement' ? nameOf(node.openingElement?.name) : null;
+}
+
+/**
+ * The part of an element name that identifies the component. Names arrive
+ * flattened (`React.Fragment`, `Astryx.TableRow`), and the namespace is just
+ * how the module was imported — `Rx.Fragment` is still a fragment. The rule
+ * already trusts a bare `Table` without resolving imports, so resolving the
+ * last segment is the same trade, applied consistently.
+ */
+function lastSegment(name) {
+ return name == null ? null : name.slice(name.lastIndexOf('.') + 1);
+}
+
+/**
+ * Can the walk step from `child` up through `parent` and still be describing
+ * the same position in the DOM?
+ *
+ * A call needs more than its node type. `CallExpression` is in the walk so that
+ * `{rows.map(r => <TableRow/>)}` works — the callback's return value lands
+ * exactly where the call sits. But a row handed to a function as an ARGUMENT is
+ * data, not placement: `wrapInBody(<TableRow/>)` and
+ * `React.createElement('tbody', null, <TableRow/>)` put it somewhere the callee
+ * chooses, and blaming the enclosing table for those flags correct code.
+ */
+function isTransparent(parent, child) {
+ if (parent.type === 'CallExpression') {
+ // Chained off the result: `rows.map(...).filter(Boolean)`.
+ if (parent.callee === child) {
+ return true;
+ }
+ // Stepping out of a callback, but only for the methods that splice their
+ // result into this position. A callback given to some other helper is that
+ // helper's to place.
+ const isCallbackArg =
+ parent.arguments.includes(child) &&
+ (child.type === 'ArrowFunctionExpression' ||
+ child.type === 'FunctionExpression');
+ return (
+ isCallbackArg &&
+ parent.callee?.type === 'MemberExpression' &&
+ SPLICING_METHODS.has(lastSegment(nameOf(parent.callee.property) ?? parent.callee.property?.name))
+ );
+ }
+ // `rows.map(...)` inside `rows.map(...).filter(...)` — we came up the object
+ // side of the chain, not out of a computed key.
+ if (parent.type === 'MemberExpression') {
+ return parent.object === child;
+ }
+ return TRANSPARENT_NODES.has(parent.type);
+}
+
+const rule = {
+ meta: {
+ type: 'problem',
+ docs: {
+ description:
+ 'Require TableRow/tr to sit inside TableHeader/TableBody/TableFooter — a row directly inside a table emits <table><tr>, which browsers repair on parse and React does not, producing invalid DOM and a hydration mismatch',
+ category: 'Possible Errors',
+ recommended: true,
+ },
+ messages: {
+ rowOutsideSection:
+ '<{{row}}> is a direct child of <{{table}}>. `<table>` cannot contain a ' +
+ 'row directly: the HTML parser inserts an implied <tbody> when it parses ' +
+ 'server-rendered markup, React does not when it renders on the client, and ' +
+ 'the two trees then mismatch on hydration. Wrap the rows in <TableBody> ' +
+ '(or <TableHeader>/<TableFooter>), the same element the data-driven ' +
+ '`data={...}` mode renders for you.',
+ },
+ schema: [],
+ },
+ create(context) {
+ return {
+ JSXElement(node) {
+ const row = lastSegment(elementName(node));
+ if (!ROW_ELEMENTS.has(row)) {
+ return;
+ }
+
+ let child = node;
+ for (let current = node.parent; current; current = current.parent) {
+ if (current.type === 'JSXElement') {
+ const parent = lastSegment(elementName(current));
+ if (FRAGMENT_ELEMENTS.has(parent)) {
+ child = current;
+ continue;
+ }
+ if (SECTION_ELEMENTS.has(parent)) {
+ return;
+ }
+ if (TABLE_ELEMENTS.has(parent)) {
+ context.report({
+ node,
+ messageId: 'rowOutsideSection',
+ data: {row, table: parent},
+ });
+ return;
+ }
+ // Some other component. What it renders is not knowable here.
+ return;
+ }
+
+ if (!isTransparent(current, child)) {
+ // The row has escaped its JSX position (assigned to a variable,
+ // returned from a named helper, handed to a function as an
+ // argument, passed as a prop). Stay silent.
+ return;
+ }
+ child = current;
+ }
+ },
+ };
+ },
+};
+
+export default rule;
diff --git a/internal/eslint-plugin-astryx/require-table-section.test.mjs b/internal/eslint-plugin-astryx/require-table-section.test.mjs
new file mode 100644
index 0000000000..70489587ab
--- /dev/null
+++ b/internal/eslint-plugin-astryx/require-table-section.test.mjs
@@ -0,0 +1,216 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file require-table-section.test.mjs
+ * @description Tests for the require-table-section ESLint rule, plus the
+ * #5277 regression it was written for (the `table-grouped` page template
+ * emitted `<table><tr>` because its rows had no `<TableBody>` around them).
+ */
+
+import {RuleTester} from 'eslint';
+import tseslint from 'typescript-eslint';
+import requireTableSectionRule from './require-table-section.js';
+
+const ruleTester = new RuleTester({
+ languageOptions: {
+ parser: tseslint.parser,
+ parserOptions: {
+ ecmaFeatures: {jsx: true},
+ },
+ },
+});
+
+// RuleTester registers its own describe/it blocks internally, so it
+// must run at the top level. Vitest 4 forbids calling suite functions
+// (describe/it) from inside another it() callback.
+ruleTester.run('require-table-section', requireTableSectionRule, {
+ valid: [
+ // The house pattern: rows live in a section component.
+ {code: '<Table><TableBody><TableRow/></TableBody></Table>'},
+ {code: '<Table><TableHeader><TableRow/></TableHeader></Table>'},
+ {code: '<Table><TableFooter><TableRow/></TableFooter></Table>'},
+ // Raw section elements are the same DOM node and equally valid.
+ {code: '<Table><tbody><TableRow/></tbody></Table>'},
+ {code: '<table><tbody><tr/></tbody></table>'},
+ {code: '<table><thead><tr/></thead></table>'},
+ // colgroup/caption are legal direct children of a table — untouched.
+ {code: '<Table><colgroup><col/></colgroup><TableBody><TableRow/></TableBody></Table>'},
+ {code: '<table><caption>Cap</caption><tbody><tr/></tbody></table>'},
+ // Mapped rows inside a section: the .map()/fragment chain is transparent.
+ {
+ code: '<Table><TableBody>{rows.map(r => <TableRow key={r.id}/>)}</TableBody></Table>',
+ },
+ {
+ code: '<Table><TableBody>{keys.map(k => (<React.Fragment key={k}><TableRow/></React.Fragment>))}</TableBody></Table>',
+ },
+ // Data-driven mode: Table supplies its own tbody, no children at all.
+ {code: '<Table data={data} columns={columns}/>'},
+ // A row whose enclosing element is some other component: we cannot know
+ // what that renders, so the rule stays silent rather than guessing.
+ {code: '<Wrapper><TableRow/></Wrapper>'},
+ // A row hoisted out of the JSX: its lexical parent is a declarator, so
+ // the rule cannot see where it lands. Silent, not a false positive.
+ {code: 'const row = <TableRow/>; const t = <Table><TableBody>{row}</TableBody></Table>;'},
+ // A row returned from a named helper — same reasoning.
+ {code: 'function renderRow() { return <TableRow/>; }'},
+ // A standalone row with no table around it at all (unit-test fixtures).
+ {code: '<TableRow><TableCell>x</TableCell></TableRow>'},
+
+ // A component we know nothing about, INSIDE a table: it may well render the
+ // tbody itself, so guessing here would flag correct code.
+ {code: '<Table><Wrapper><TableRow/></Wrapper></Table>'},
+ // A row handed to Table as a prop — the prop's renderer decides where it lands.
+ {code: '<Table rowSlot={<TableRow/>}><TableBody/></Table>'},
+ {code: '<Table children={<TableRow/>}/>'},
+ // BaseTable renders the same <table>; a section is still a section under it.
+ {code: '<BaseTable><tbody><tr/></tbody></BaseTable>'},
+ // Fragment shorthand inside a section stays valid.
+ {
+ code: '<Table><TableBody><>{list.map(r => <TableRow key={r}/>)}</></TableBody></Table>',
+ },
+ // Nested tables, both composed correctly.
+ {
+ code: '<Table><TableBody><TableRow><TableCell><Table><TableBody><TableRow/></TableBody></Table></TableCell></TableRow></TableBody></Table>',
+ },
+
+ // A row passed to a function as an ARGUMENT is data, not placement: the
+ // callee decides where it ends up, and it is routinely somewhere valid.
+ // Flagging these told authors to wrap code that was already correct.
+ {code: '<Table>{wrapInBody(<TableRow/>)}</Table>'},
+ {code: "<Table>{React.createElement('tbody', null, <TableRow/>)}</Table>"},
+ {code: '<table>{createPortal(<tr/>, node)}</table>'},
+ // Same for a callback handed to a helper: only an inline .map()/.flatMap()
+ // splices its result straight into this JSX position.
+ {code: '<Table>{withBody(() => <TableRow/>)}</Table>'},
+ {
+ code: '<Table columns={c}>{buildGroupedBodies(groups, g => <TableRow key={g.id}/>)}</Table>',
+ },
+
+ // Name matching is lexical — no import resolution, by design. An aliased
+ // table or row is invisible, the same way a bare `Table` from any package
+ // is treated as ours.
+ {code: '<DataTable><TableRow/></DataTable>'},
+ // Accepted limitations, pinned so a change of behaviour is deliberate:
+ // a sequence expression and an awaited wrapper both break the walk.
+ {code: '<Table>{(0, <TableRow/>)}</Table>'},
+ {
+ code: '<Table>{await Promise.all(rows.map(async r => <TableRow key={r.id}/>))}</Table>',
+ },
+ // Only the method form splices: a helper that happens to be named `map`
+ // still places the row itself.
+ {code: '<Table>{map(rows, r => <TableRow key={r.id}/>)}</Table>'},
+ // The chain is followed up the object side, not out of a computed key.
+ {code: '<Table>{arr[<TableRow/>]}</Table>'},
+ ],
+ invalid: [
+ // The straightforward case.
+ {
+ code: '<Table><TableRow/></Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // The #5277 shape: a colgroup, then rows mapped straight into the table.
+ {
+ code: '<Table columns={columns}><colgroup><col/></colgroup>{rows.map(r => <TableRow key={r.id}/>)}</Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // The #5277 shape in full: fragment + conditional + nested map, two rows.
+ {
+ code: `
+ <Table columns={columns}>
+ <colgroup><col/></colgroup>
+ {groupKeys.map(key => {
+ return (
+ <React.Fragment key={key}>
+ {groupBy !== 'none' && <TableRow role="button"/>}
+ {isExpanded && tasks.map(task => (<TableRow key={task.id}/>))}
+ </React.Fragment>
+ );
+ })}
+ </Table>
+ `,
+ errors: [
+ {messageId: 'rowOutsideSection'},
+ {messageId: 'rowOutsideSection'},
+ ],
+ },
+ // Raw <tr> under the Astryx <Table> is the same invalid DOM.
+ {
+ code: '<Table><tr><td>x</td></tr></Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // ...and under a raw <table> too.
+ {
+ code: '<table><tr><td>x</td></tr></table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // A ternary branch is transparent: both arms are still direct children.
+ {
+ code: '<Table>{isEmpty ? <TableRow/> : <TableRow/>}</Table>',
+ errors: [
+ {messageId: 'rowOutsideSection'},
+ {messageId: 'rowOutsideSection'},
+ ],
+ },
+ // BaseTable renders the <table>; core's own tests compose it directly.
+ {
+ code: '<BaseTable><tr><td>x</td></tr></BaseTable>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // Fragment shorthand, single and nested.
+ {
+ code: '<Table><>{list.map(r => <TableRow key={r}/>)}</></Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ {
+ code: '<Table><><><TableRow/></></></Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // An array literal spliced into the table.
+ {
+ code: '<Table>{[<TableRow key="a"/>]}</Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // ...and the same rows spread in. Flagging the literal row but not the
+ // spread beside it would be a green lint over the same broken DOM.
+ {
+ code: '<Table>{...rows.map(r => <TableRow key={r.id}/>)}</Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // Nested tables: only the inner, section-less one is reported.
+ {
+ code: '<Table><TableBody><TableRow><TableCell><Table><TableRow/></Table></TableCell></TableRow></TableBody></Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // A method chained after the map is the most idiomatic row-list shape there
+ // is, and it must not hide the rows.
+ {
+ code: '<Table>{rows.map(r => <TableRow key={r.id}/>).filter(Boolean)}</Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // A return one statement deeper inside the map callback.
+ {
+ code: '<Table>{rows.map(r => { if (r.ok) { return <TableRow key={r.id}/>; } return null; })}</Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // Member-expression element names resolve on their last segment, so a
+ // namespaced import is not a blind spot.
+ {
+ code: '<Astryx.Table><Astryx.TableRow/></Astryx.Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // ...and an aliased React import still reads as a fragment.
+ {
+ code: '<Table><Rx.Fragment><TableRow/></Rx.Fragment></Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ // Optional chaining and flatMap are the same splice.
+ {
+ code: '<Table>{rows?.map(r => <TableRow key={r.id}/>)}</Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ {
+ code: '<Table>{groups.flatMap(g => g.rows.map(r => <TableRow key={r.id}/>))}</Table>',
+ errors: [{messageId: 'rowOutsideSection'}],
+ },
+ ],
+});
diff --git a/packages/cli/assets/templates/pages/table-grouped/page.tsx b/packages/cli/assets/templates/pages/table-grouped/page.tsx
index e2346be803..be9742881a 100644
--- a/packages/cli/assets/templates/pages/table-grouped/page.tsx
+++ b/packages/cli/assets/templates/pages/table-grouped/page.tsx
@@ -37,6 +37,7 @@ import {Divider} from '@astryxdesign/core/Divider';
import {MetadataList, MetadataListItem} from '@astryxdesign/core/MetadataList';
import {
Table,
+ TableBody,
TableRow,
TableCell,
proportional,
@@ -963,161 +964,167 @@ export default function DataTableTemplate() {
/>
))}
</colgroup>
- {groupKeys.map(key => {
- const tasks = grouped.get(key);
- if (!tasks || tasks.length === 0) {
- return null;
- }
- const isExpanded = expandedGroups.has(key);
+ <TableBody>
+ {groupKeys.map(key => {
+ const tasks = grouped.get(key);
+ if (!tasks || tasks.length === 0) {
+ return null;
+ }
+ const isExpanded = expandedGroups.has(key);
- return (
- <React.Fragment key={key}>
- {groupBy !== 'none' && (
- <TableRow
- role="button"
- tabIndex={0}
- onClick={() => toggleGroup(key)}
- onKeyDown={e => {
- if (e.key === 'Enter' || e.key === ' ') {
- e.preventDefault();
- toggleGroup(key);
- }
- }}>
- <TableCell colSpan={COL_COUNT} style={groupHeaderCell}>
- <HStack gap={2} vAlign="center">
- <Icon
- icon={
- isExpanded ? ChevronDownIcon : ChevronRightIcon
- }
- size="sm"
- color="secondary"
- />
- <Text type="body" weight="bold">
- {getGroupLabel(groupBy, key)}
- </Text>
- <Badge
- variant="neutral"
- label={String(tasks.length)}
- />
- </HStack>
- </TableCell>
- </TableRow>
- )}
- {(groupBy === 'none' || isExpanded) &&
- tasks.map(task => (
+ return (
+ <React.Fragment key={key}>
+ {groupBy !== 'none' && (
<TableRow
- key={task.id}
- onClick={() => setSelectedTask(task)}>
- <TableCell>
- <Center axis="horizontal">
- <StatusDot
- variant={STATUS_DOT_VARIANT[task.status]}
- label={STATUS_LABEL[task.status]}
- />
- </Center>
- </TableCell>
- <TableCell>
- <HStack gap={3} vAlign="center">
+ role="button"
+ tabIndex={0}
+ onClick={() => toggleGroup(key)}
+ onKeyDown={e => {
+ if (e.key === 'Enter' || e.key === ' ') {
+ e.preventDefault();
+ toggleGroup(key);
+ }
+ }}>
+ <TableCell
+ colSpan={COL_COUNT}
+ style={groupHeaderCell}>
+ <HStack gap={2} vAlign="center">
<Icon
- icon={ChartBarIcon}
+ icon={
+ isExpanded
+ ? ChevronDownIcon
+ : ChevronRightIcon
+ }
size="sm"
- color={PRIORITY_COLOR[task.priority]}
+ color="secondary"
/>
- <Text type="supporting" color="secondary">
- {task.taskId}
+ <Text type="body" weight="bold">
+ {getGroupLabel(groupBy, key)}
</Text>
- <Text type="body" maxLines={1}>
- {task.title}
- </Text>
- {task.subtitle && (
- <Text
- type="body"
- color="secondary"
- maxLines={1}>
- › {task.subtitle}
- </Text>
- )}
+ <Badge
+ variant="neutral"
+ label={String(tasks.length)}
+ />
</HStack>
</TableCell>
- <TableCell>
- {task.project ? (
- <Text type="body" maxLines={1}>
- {task.project}
+ </TableRow>
+ )}
+ {(groupBy === 'none' || isExpanded) &&
+ tasks.map(task => (
+ <TableRow
+ key={task.id}
+ onClick={() => setSelectedTask(task)}>
+ <TableCell>
+ <Center axis="horizontal">
+ <StatusDot
+ variant={STATUS_DOT_VARIANT[task.status]}
+ label={STATUS_LABEL[task.status]}
+ />
+ </Center>
+ </TableCell>
+ <TableCell>
+ <HStack gap={3} vAlign="center">
+ <Icon
+ icon={ChartBarIcon}
+ size="sm"
+ color={PRIORITY_COLOR[task.priority]}
+ />
+ <Text type="supporting" color="secondary">
+ {task.taskId}
+ </Text>
+ <Text type="body" maxLines={1}>
+ {task.title}
+ </Text>
+ {task.subtitle && (
+ <Text
+ type="body"
+ color="secondary"
+ maxLines={1}>
+ › {task.subtitle}
+ </Text>
+ )}
+ </HStack>
+ </TableCell>
+ <TableCell>
+ {task.project ? (
+ <Text type="body" maxLines={1}>
+ {task.project}
+ </Text>
+ ) : (
+ <Text type="supporting" color="secondary">
+ —
+ </Text>
+ )}
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {task.created}
</Text>
- ) : (
+ </TableCell>
+ <TableCell>
<Text type="supporting" color="secondary">
- —
+ {task.updated}
</Text>
- )}
- </TableCell>
- <TableCell>
- <Text type="supporting" color="secondary">
- {task.created}
- </Text>
- </TableCell>
- <TableCell>
- <Text type="supporting" color="secondary">
- {task.updated}
- </Text>
- </TableCell>
- <TableCell>
- <Avatar name={task.assignee} size="sm" />
- </TableCell>
- <TableCell>
- <DropdownMenu
- button={{
- label: 'Actions',
- variant: 'ghost',
- size: 'sm',
- icon: (
- <Icon
- icon={EllipsisHorizontalIcon}
- size="sm"
- />
- ),
- isIconOnly: true,
- }}
- hasChevron={false}
- items={[
- {
- label: 'Edit issue',
- icon: PencilIcon,
- onClick: () => {},
- },
- {
- label: 'Assign to...',
- icon: UserIcon,
- onClick: () => {},
- },
- {
- label: 'Add label',
- icon: TagIcon,
- onClick: () => {},
- },
- {
- label: 'Duplicate',
- icon: DocumentDuplicateIcon,
- onClick: () => {},
- },
- {
- label: 'Move to project',
- icon: ArrowRightIcon,
- onClick: () => {},
- },
- {type: 'divider' as const},
- {
- label: 'Delete issue',
- icon: TrashIcon,
- onClick: () => {},
- },
- ]}
- />
- </TableCell>
- </TableRow>
- ))}
- </React.Fragment>
- );
- })}
+ </TableCell>
+ <TableCell>
+ <Avatar name={task.assignee} size="sm" />
+ </TableCell>
+ <TableCell>
+ <DropdownMenu
+ button={{
+ label: 'Actions',
+ variant: 'ghost',
+ size: 'sm',
+ icon: (
+ <Icon
+ icon={EllipsisHorizontalIcon}
+ size="sm"
+ />
+ ),
+ isIconOnly: true,
+ }}
+ hasChevron={false}
+ items={[
+ {
+ label: 'Edit issue',
+ icon: PencilIcon,
+ onClick: () => {},
+ },
+ {
+ label: 'Assign to...',
+ icon: UserIcon,
+ onClick: () => {},
+ },
+ {
+ label: 'Add label',
+ icon: TagIcon,
+ onClick: () => {},
+ },
+ {
+ label: 'Duplicate',
+ icon: DocumentDuplicateIcon,
+ onClick: () => {},
+ },
+ {
+ label: 'Move to project',
+ icon: ArrowRightIcon,
+ onClick: () => {},
+ },
+ {type: 'divider' as const},
+ {
+ label: 'Delete issue',
+ icon: TrashIcon,
+ onClick: () => {},
+ },
+ ]}
+ />
+ </TableCell>
+ </TableRow>
+ ))}
+ </React.Fragment>
+ );
+ })}
+ </TableBody>
</Table>
</LayoutContent>
}
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 5f6d0c3ef9..544a3638a9 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -107,7 +107,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 +116,9 @@ export const docs = {
},
],
components: [
+ {name: 'TableHeader'},
+ {name: 'TableBody'},
+ {name: 'TableFooter'},
{name: 'TableRow'},
{name: 'TableCell'},
{name: 'TableHeaderCell'},
@@ -135,6 +138,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 +187,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 — 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.' },
diff --git a/packages/core/src/Table/Table.test.tsx b/packages/core/src/Table/Table.test.tsx
index ae83dd1112..d44328689c 100644
--- a/packages/core/src/Table/Table.test.tsx
+++ b/packages/core/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();
@@ -1023,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();
@@ -1039,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);
diff --git a/packages/core/src/Table/TableBody.doc.mjs b/packages/core/src/Table/TableBody.doc.mjs
new file mode 100644
index 0000000000..6005b45921
--- /dev/null
+++ b/packages/core/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',
+ },
+};
diff --git a/packages/core/src/Table/TableFooter.doc.mjs b/packages/core/src/Table/TableFooter.doc.mjs
new file mode 100644
index 0000000000..b33953fb8f
--- /dev/null
+++ b/packages/core/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',
+ },
+};
diff --git a/packages/core/src/Table/TableHeader.doc.mjs b/packages/core/src/Table/TableHeader.doc.mjs
new file mode 100644
index 0000000000..fccd810aa6
--- /dev/null
+++ b/packages/core/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',
+ },
+};
diff --git a/packages/core/src/Table/TableRow.tsx b/packages/core/src/Table/TableRow.tsx
index e61a309efe..4dfb0bae31 100644
--- a/packages/core/src/Table/TableRow.tsx
+++ b/packages/core/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>
* ```
*/