Skip to content

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

TypeScript

docs(core): add useTableRowExpansion to tree-plugin migration guide (#4142) (#4584)

Humberto Virtudes0f688f8badf2
diff --git a/.changeset/table-tree-migration-guide.md b/.changeset/table-tree-migration-guide.md
new file mode 100644
index 0000000000..7d5ab05ced
--- /dev/null
+++ b/.changeset/table-tree-migration-guide.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Add a migration guide from useTableRowExpansion to useTableTreeData + useTableTreeState (before/after example plus a config mapping), since the two tree plugins are converging.
+
+@humbertovirtudes
diff --git a/packages/core/src/Table/useTableRowExpansion.doc.mjs b/packages/core/src/Table/useTableRowExpansion.doc.mjs
index 2055434a98..7a1bcbe5b6 100644
--- a/packages/core/src/Table/useTableRowExpansion.doc.mjs
+++ b/packages/core/src/Table/useTableRowExpansion.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
subComponentOf: 'Table',
displayName: 'useTableRowExpansion',
description:
- 'Hook that returns a TablePlugin implementing expandable rows with inherited columns. Child rows use the same columns as their parents, indented by depth. Clicking the chevron (or right-click context menu) toggles expansion. Pair with useTableRowExpansionState, which flattens the tree and derives this config (expand/collapse handlers + expand-all state) from a single expandedKeys set.',
+ 'Hook that returns a TablePlugin implementing expandable rows with inherited columns. Child rows use the same columns as their parents, indented by depth. Clicking the chevron (or right-click context menu) toggles expansion. Pair with useTableRowExpansionState, which flattens the tree and derives this config (expand/collapse handlers + expand-all state) from a single expandedKeys set. Converging with useTableTreeData: new tree tables should prefer useTableTreeData + useTableTreeState, which cover the same affordances with a cycle guard and fine-grained re-render. See the migration example below.',
props: [
{
name: 'expandedKeys',
@@ -60,6 +60,59 @@ export const docs = {
description: 'Callback when the expand-all header toggle is clicked.',
},
],
+ examples: [
+ {
+ label: 'Migrating to useTableTreeData + useTableTreeState',
+ code: `// useTableRowExpansion and useTableTreeData are converging onto one tree
+// plugin. useTableTreeData is the destination: it adds a cycle guard,
+// per-row fine-grained re-render, and imperative row ARIA, and now covers
+// the same affordances (expand-all header control, whole-row click).
+
+// BEFORE: useTableRowExpansion + useTableRowExpansionState
+const [expandedKeys, setExpandedKeys] = useState(new Set(['root']));
+const {data, expansionConfig} = useTableRowExpansionState({
+ baseData: tree,
+ getChildren: item => item.children ?? [],
+ getRowKey: item => item.id,
+ expandedKeys,
+ setExpandedKeys,
+});
+const expansion = useTableRowExpansion(expansionConfig);
+<Table data={data} columns={columns} idKey="id" plugins={{expansion}} />;
+
+// AFTER: useTableTreeState + useTableTreeData
+const {visibleData, treeConfig} = useTableTreeState({
+ data: tree, // nested data, not a flat array
+ idKey: 'id', // or a function: idKey={item => item.id}
+ childrenKey: 'children', // replaces getChildren (default 'children')
+ defaultExpandedIds: ['root'], // uncontrolled; or expandedIds + onExpandedIdsChange
+});
+const tree = useTableTreeData({
+ ...treeConfig,
+ hasExpandAllControl: true, // was isAllExpanded + onToggleExpandAll
+ hasRowClickExpansion: true, // same prop name
+});
+<Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />;`,
+ },
+ {
+ label: 'Config mapping',
+ code: `// useTableRowExpansion(State) -> useTableTreeState / useTableTreeData
+
+// baseData: T[] (nested) -> data: T[] (useTableTreeState)
+// getChildren: item => item.children -> childrenKey: 'children' (property name)
+// getRowKey: item => item.id -> idKey: 'id' | (item => item.id)
+// getIsItemExpandable -> isItemExpandable (same shape)
+// expandedKeys + setExpandedKeys -> defaultExpandedIds (uncontrolled), or
+// expandedIds + onExpandedIdsChange (controlled)
+// getDepth -> removed; depth derives from nesting
+// isAllExpanded + onToggleExpandAll -> hasExpandAllControl (state is computed)
+// hasRowClickExpansion -> hasRowClickExpansion (unchanged)
+
+// Rendering: useTableRowExpansion prepends a dedicated expander column;
+// useTableTreeData decorates the tree column in place (configurable via
+// treeColumnKey). Keyboard and AT users toggle via the chevron in both.`,
+ },
+ ],
};
/** @type {import('../docs-types').TranslationDoc} */