Skip to content

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

TypeScript

docs(core): soft-deprecate useTableRowExpansion for the tree plugin (#4142) (#4587)

Humberto Virtudes4ffab6f6f18c
diff --git a/.changeset/deprecate-row-expansion.md b/.changeset/deprecate-row-expansion.md
new file mode 100644
index 0000000000..d252d01879
--- /dev/null
+++ b/.changeset/deprecate-row-expansion.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Soft-deprecate useTableRowExpansion and useTableRowExpansionState in favor of the tree plugin (useTableTreeData + useTableTreeState). The hooks still work; JSDoc @deprecated tags and the docs point to the migration guide. Removal will come in a later release.
+
+@humbertovirtudes
diff --git a/packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx b/packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx
index 2a24f50c73..fb745fac53 100644
--- a/packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx
+++ b/packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx
@@ -7,6 +7,9 @@
* @input React, StyleX, Icon, Table types
* @output Exports useTableRowExpansion hook + config/state types
* @position Row-expansion plugin; consumed by Table via plugins prop
+ * @deprecated Superseded by the tree plugin (useTableTreeData +
+ * useTableTreeState). Kept for back-compat; new tree tables should use the
+ * tree plugin. See the migration guide on useTableRowExpansion.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Table/index.ts (exports)
@@ -106,9 +109,14 @@ export interface UseTableRowExpansionStateResult<
/**
* Manages row-expansion state and derives the config for
- * {@link useTableRowExpansion}. This is the recommended entry point — it
- * removes the boilerplate of flattening the tree, tracking depth, and
- * computing the expand-all state.
+ * {@link useTableRowExpansion}.
+ *
+ * @deprecated Use `useTableTreeState` (with `useTableTreeData`) instead. The
+ * tree plugin covers the same affordances (expand-all header control,
+ * whole-row click) with a cycle guard and per-row fine-grained re-render. See
+ * the migration guide on `useTableRowExpansion` (`astryx component
+ * useTableRowExpansion --detail full`) for the before/after and config
+ * mapping.
*
* @example
* ```
@@ -379,6 +387,16 @@ function ExpansionChevron({
// Hook
// =============================================================================
+/**
+ * Returns a TablePlugin implementing expandable rows with inherited columns.
+ *
+ * @deprecated Use `useTableTreeData` (with `useTableTreeState`) instead. The
+ * tree plugin covers the same affordances (expand-all header control,
+ * whole-row click) with a cycle guard and per-row fine-grained re-render. See
+ * the migration guide on this hook's docs (`astryx component
+ * useTableRowExpansion --detail full`) for the before/after and config
+ * mapping.
+ */
export function useTableRowExpansion<T extends Record<string, unknown>>(
config: UseTableRowExpansionConfig<T>,
): TablePlugin<T> {
diff --git a/packages/core/src/Table/useTableRowExpansion.doc.mjs b/packages/core/src/Table/useTableRowExpansion.doc.mjs
index 7a1bcbe5b6..218b1c513e 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. 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.',
+ 'Deprecated: use useTableTreeData + useTableTreeState instead. 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',
@@ -118,7 +118,7 @@ const tree = useTableTreeData({
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description:
- 'Returns a TablePlugin for expandable rows w/ inherited columns. Child rows reuse parent columns, indented by depth. Chevron click (or right-click menu) toggles expansion. Pair w/ useTableRowExpansionState, which flattens the tree + derives this config from one expandedKeys set.',
+ 'Deprecated: use useTableTreeData + useTableTreeState instead. Returns a TablePlugin for expandable rows w/ inherited columns. Child rows reuse parent columns, indented by depth. Chevron click (or right-click menu) toggles expansion. Pair w/ useTableRowExpansionState, which flattens the tree + derives this config from one expandedKeys set.',
propDescriptions: {
expandedKeys: 'Set of currently-expanded row keys.',
onToggle: 'Called when a row expansion is toggled.',