@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/Table/plugins/tree/useTableTreeState.tsx

@@ -0,0 +1,253 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableTreeState.tsx
+ * @input React
+ * @output Exports useTableTreeState hook and config/result types
+ * @position Tree state helper; owns the expanded set + flattens nested data.
+ *   Pairs with useTableTreeData (the headless tree plugin).
+ *
+ * Modeled after useTableSortableState — a convenience layer that owns state
+ * (controlled or uncontrolled) and produces both the visible flattened rows
+ * and a ready-to-use config for the headless plugin. Data shaping stays
+ * outside the render pipeline: Table always receives exactly the rows it
+ * renders, so collapsed subtrees are unmounted, not hidden.
+ */
+
+import {useCallback, useMemo, useRef, useState} from 'react';
+import type {
+  TableTreeRowMeta,
+  UseTableTreeDataConfig,
+} from './useTableTreeData';
+
+// =============================================================================
+// Config
+// =============================================================================
+
+export interface UseTableTreeStateConfig<T extends Record<string, unknown>> {
+  /** Nested data: rows may carry child rows under `childrenKey`. */
+  data: T[];
+  /** Row ID accessor: property name, or a function returning a unique id. */
+  idKey: (keyof T & string) | ((item: T) => string | number);
+  /**
+   * Property holding each row's children array.
+   * @default 'children'
+   */
+  childrenKey?: string;
+  /** Initial expanded row ids for uncontrolled mode. Ignored when `expandedIds` is provided. */
+  defaultExpandedIds?: Iterable<string>;
+  /**
+   * Controlled set of expanded row ids. When provided, the hook uses this
+   * instead of internal state. Pair with `onExpandedIdsChange`.
+   */
+  expandedIds?: ReadonlySet<string>;
+  /** Called with the next expanded set whenever expansion changes. */
+  onExpandedIdsChange?: (ids: ReadonlySet<string>) => void;
+  /**
+   * Should this row show an expander? Overrides the default
+   * "has a non-empty children array" check — use for lazy loading, where a
+   * row is expandable before its children have been fetched.
+   */
+  isItemExpandable?: (item: T) => boolean;
+  /**
+   * Sort each sibling group independently during flattening. Children always
+   * stay directly under their parent — sorting never crosses levels. Pass
+   * `applySort` from `useTableSortableState` to compose with column sorting.
+   */
+  sortSiblings?: (siblings: T[]) => T[];
+  /** Indent step per level, forwarded to useTableTreeData. */
+  indent?: 'sm' | 'md' | 'lg';
+  /** Column that carries the tree affordance, forwarded to useTableTreeData. */
+  treeColumnKey?: string;
+}
+
+// =============================================================================
+// Result
+// =============================================================================
+
+export interface UseTableTreeStateResult<T extends Record<string, unknown>> {
+  /** The flattened, currently-visible rows. Pass to `<Table data>`. */
+  visibleData: T[];
+  /** Ready-to-use config for useTableTreeData. */
+  treeConfig: UseTableTreeDataConfig<T>;
+  /** The current expanded row ids. */
+  expandedIds: ReadonlySet<string>;
+  /** Expand every expandable row in the tree. */
+  expandAll: () => void;
+  /** Collapse every row. */
+  collapseAll: () => void;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useTableTreeState<T extends Record<string, unknown>>(
+  config: UseTableTreeStateConfig<T>,
+): UseTableTreeStateResult<T> {
+  const {
+    data,
+    idKey,
+    childrenKey = 'children',
+    defaultExpandedIds,
+    expandedIds: controlledExpandedIds,
+    onExpandedIdsChange,
+    isItemExpandable,
+    sortSiblings,
+    indent,
+    treeColumnKey,
+  } = config;
+
+  const getId = useCallback(
+    (item: T): string =>
+      typeof idKey === 'function' ? String(idKey(item)) : String(item[idKey]),
+    [idKey],
+  );
+
+  const getChildren = useCallback(
+    (item: T): T[] => {
+      const children = item[childrenKey];
+      return Array.isArray(children) ? (children as T[]) : [];
+    },
+    [childrenKey],
+  );
+
+  const getIsExpandable = useCallback(
+    (item: T): boolean =>
+      isItemExpandable ? isItemExpandable(item) : getChildren(item).length > 0,
+    [isItemExpandable, getChildren],
+  );
+
+  // Internal state (used in uncontrolled mode)
+  const [internalExpandedIds, setInternalExpandedIds] = useState<
+    ReadonlySet<string>
+  >(() => new Set(defaultExpandedIds));
+
+  // Resolve controlled vs uncontrolled
+  const isControlled = controlledExpandedIds !== undefined;
+  const expandedIds = isControlled
+    ? controlledExpandedIds
+    : internalExpandedIds;
+
+  // Stable refs so callbacks don't churn on inline-prop identity changes
+  const expandedIdsRef = useRef(expandedIds);
+  expandedIdsRef.current = expandedIds;
+  const onExpandedIdsChangeRef = useRef(onExpandedIdsChange);
+  onExpandedIdsChangeRef.current = onExpandedIdsChange;
+
+  const commitExpandedIds = useCallback(
+    (next: ReadonlySet<string>) => {
+      // Advance the ref immediately so a second commit in the same React
+      // batch (e.g. two onToggleItem calls in one event handler) builds
+      // on this one instead of the pre-batch set. The ref re-syncs from
+      // the resolved state on the next render either way.
+      expandedIdsRef.current = next;
+      if (!isControlled) {
+        setInternalExpandedIds(next);
+      }
+      onExpandedIdsChangeRef.current?.(next);
+    },
+    [isControlled],
+  );
+
+  // Flatten: depth-first walk emitting only visible rows, collecting per-row
+  // meta ({level, hasChildren, isExpanded}) in the same pass. Children mount
+  // only when their parent is expanded, so collapsed subtrees stay unmounted.
+  // `path` holds the ids on the current ancestor chain: an edge pointing back
+  // at an ancestor is skipped instead of recursing forever. Sibling arrays
+  // are copied before sortSiblings so an in-place sorter can't reorder the
+  // consumer's data.
+  const {visibleData, metaMap} = useMemo(() => {
+    const rows: T[] = [];
+    const meta = new Map<string, TableTreeRowMeta>();
+    const path = new Set<string>();
+    const walk = (items: T[], level: number) => {
+      const siblings = sortSiblings ? sortSiblings([...items]) : items;
+      for (const item of siblings) {
+        const id = getId(item);
+        if (path.has(id)) {
+          continue; // cyclic edge — this row is its own ancestor
+        }
+        const hasChildren = getIsExpandable(item);
+        const isExpanded = hasChildren && expandedIds.has(id);
+        rows.push(item);
+        meta.set(id, {id, level, hasChildren, isExpanded});
+        if (isExpanded) {
+          path.add(id);
+          walk(getChildren(item), level + 1);
+          path.delete(id);
+        }
+      }
+    };
+    walk(data, 0);
+    return {visibleData: rows, metaMap: meta};
+  }, [data, expandedIds, getId, getChildren, getIsExpandable, sortSiblings]);
+
+  // Every expandable row id across the whole tree, including collapsed
+  // subtrees (drives expandAll and the migration no-op flag). Same
+  // ancestor-chain guard as the flatten walk.
+  const allExpandableIds = useMemo(() => {
+    const idsAcc: string[] = [];
+    const path = new Set<string>();
+    const walk = (items: T[]) => {
+      for (const item of items) {
+        const id = getId(item);
+        if (path.has(id)) {
+          continue;
+        }
+        if (getIsExpandable(item)) {
+          idsAcc.push(id);
+        }
+        path.add(id);
+        walk(getChildren(item));
+        path.delete(id);
+      }
+    };
+    walk(data);
+    return idsAcc;
+  }, [data, getId, getChildren, getIsExpandable]);
+
+  const hasExpandableRows = allExpandableIds.length > 0;
+
+  const onToggleItem = useCallback(
+    (item: T) => {
+      const id = getId(item);
+      const next = new Set(expandedIdsRef.current);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      commitExpandedIds(next);
+    },
+    [getId, commitExpandedIds],
+  );
+
+  const expandAll = useCallback(() => {
+    commitExpandedIds(new Set(allExpandableIds));
+  }, [commitExpandedIds, allExpandableIds]);
+
+  const collapseAll = useCallback(() => {
+    commitExpandedIds(new Set());
+  }, [commitExpandedIds]);
+
+  const getRowMeta = useCallback(
+    (item: T): TableTreeRowMeta | undefined => metaMap.get(getId(item)),
+    [metaMap, getId],
+  );
+
+  const treeConfig = useMemo(
+    (): UseTableTreeDataConfig<T> => ({
+      getRowMeta,
+      onToggleItem,
+      hasExpandableRows,
+      indent,
+      treeColumnKey,
+    }),
+    [getRowMeta, onToggleItem, hasExpandableRows, indent, treeColumnKey],
+  );
+
+  return {visibleData, treeConfig, expandedIds, expandAll, collapseAll};
+}

package/src/Table/types.ts

@@ -223,13 +223,13 @@ export interface TableColumn<T extends Record<string, unknown>> {
 /** Props passed through the plugin pipeline for the `<table>` element */
 export interface TableRenderProps {
   htmlProps: HTMLAttributes<HTMLTableElement>;
-  styles: StyleXStyles[];
+  xstyle: StyleXStyles[];
 }
 
 /** Props passed through the plugin pipeline for the header `<tr>` */
 export interface HeaderRowRenderProps {
   htmlProps: HTMLAttributes<HTMLTableRowElement>;
-  styles: StyleXStyles[];
+  xstyle: StyleXStyles[];
   children: ReactNode;
 }
 
@@ -250,7 +250,7 @@ export interface HeaderRowRenderProps {
  */
 export interface HeaderCellRenderProps {
   htmlProps: ThHTMLAttributes<HTMLTableCellElement>;
-  styles: StyleXStyles[];
+  xstyle: StyleXStyles[];
   /** Content rendered before the header label. */
   before?: ReactNode;
   /** The header label content. Initialized from `column.header ?? column.key`. Plugins may wrap or replace. */
@@ -286,7 +286,7 @@ export interface HeaderCellRenderProps {
 /** Props passed through the plugin pipeline for each body `<tr>` */
 export interface BodyRowRenderProps {
   htmlProps: HTMLAttributes<HTMLTableRowElement>;
-  styles: StyleXStyles[];
+  xstyle: StyleXStyles[];
   children: ReactNode;
   /** Ref for the `<tr>` element. Plugins can set this to access the row DOM node. */
   ref?: Ref<HTMLTableRowElement>;
@@ -295,7 +295,7 @@ export interface BodyRowRenderProps {
 /** Props passed through the plugin pipeline for each body `<td>` */
 export interface BodyCellRenderProps {
   htmlProps: TdHTMLAttributes<HTMLTableCellElement>;
-  styles: StyleXStyles[];
+  xstyle: StyleXStyles[];
   /**
    * Right-click context-menu actions for this body cell. Plugins append their
    * actions in `transformBodyCell`; BaseTable concatenates the arrays across
@@ -341,7 +341,7 @@ export interface ScrollWrapperRenderProps {
   htmlProps: HTMLAttributes<HTMLDivElement> & {
     ref?: Ref<HTMLDivElement>;
   };
-  styles: StyleXStyles[];
+  xstyle: StyleXStyles[];
   /** Content rendered before the `<table>`, inside the scroll container. */
   beforeTable?: ReactNode;
   /** Content rendered after the `<table>`, inside the scroll container. */
@@ -389,8 +389,7 @@ export interface TableContextAction {
  * every render.
  */
 export type TableContextActions =
-  | TableContextAction[]
-  | (() => TableContextAction[]);
+  TableContextAction[] | (() => TableContextAction[]);
 
 // =============================================================================
 // Plugin Interface
@@ -543,7 +542,14 @@ export interface BaseTableProps<
 
   /** Children mode — render `<tr>`/`<td>` directly instead of data-driven */
   children?: ReactNode;
-  /** Additional HTML attributes for the `<table>` element */
+  /**
+   * Additional HTML attributes for the `<table>` element.
+   *
+   * @deprecated Pass `className`, `style`, `xstyle`, and other HTML
+   * attributes directly on the component instead — they now reach the root
+   * `<table>` and win over `tableProps` on conflicts. Migrate with
+   * `npx astryx upgrade --codemod migrate-table-tableprops-to-direct-props`.
+   */
   tableProps?: HTMLAttributes<HTMLTableElement>;
   /**
    * Optional wrapper rendered around the `<table>` element, inside the
@@ -551,15 +557,15 @@ export interface BaseTableProps<
    * horizontal scroll container so plugin chrome (pagination, toolbars)
    * stays outside the scrollable area.
    *
-   * Receives `htmlProps` (including an optional `ref`) and `styles` produced
+   * Receives `htmlProps` (including an optional `ref`) and `xstyle` produced
    * by the plugin `transformScrollWrapper` pipeline, plus `beforeTable`/`afterTable`
-   * chrome. The wrapper must spread `htmlProps` (and apply `styles`) onto its
+   * chrome. The wrapper must spread `htmlProps` (and apply `xstyle`) onto its
    * scroll-container element so plugins can attach refs / scroll listeners.
    */
   scrollWrapper?: ComponentType<{
     children: ReactNode;
     htmlProps?: HTMLAttributes<HTMLDivElement> & {ref?: Ref<HTMLDivElement>};
-    styles?: StyleXStyles[];
+    xstyle?: StyleXStyles[];
     beforeTable?: ReactNode;
     afterTable?: ReactNode;
   }>;

package/src/Table/useBaseTablePlugins.ts

@@ -18,12 +18,15 @@
  * Canonical order:
  *   1. columnSettings — column filtering (future: transformColumns)
  *   2. sort           — header cell sort controls
- *   3. selection      — checkbox column + row selection
- *   4. pagination     — pagination controls around the table
+ *   3. tree           — indent + expander on the tree column
+ *   4. selection      — checkbox column + row selection
+ *   5. pagination     — pagination controls around the table
  *
  * Rationale:
  * - columnSettings filters columns before sort/selection see them
  * - sort adds header cell UI before selection adds its header column
+ * - tree wraps the first *user* column before selection prepends its
+ *   checkbox column, so the expander never lands in the checkbox column
  * - selection adds its column after sort so the checkbox header
  *   doesn't get a sort button
  * - pagination wraps the table in context last (outermost provider)
@@ -46,6 +49,7 @@ import type {TablePlugin} from './types';
 const PLUGIN_ORDER: ReadonlyArray<string> = [
   'columnSettings',
   'sort',
+  'tree',
   'selection',
   'pagination',
 ];

package/src/Table/useTableFiltering.doc.mjs

@@ -23,7 +23,7 @@ export const docs = {
     },
     {
       name: 'variant',
-      type: "'popover' | 'inline'",
+      type: "'popover' | 'inline' | 'inline-compact'",
       description: 'Display variant for filter controls.',
       default: "'popover'",
     },
@@ -50,7 +50,7 @@ export const docsZh = {
     },
     {
       name: 'variant',
-      type: "'popover' | 'inline'",
+      type: "'popover' | 'inline' | 'inline-compact'",
       description: '筛选控件的显示变体。',
       default: "'popover'",
     },

package/src/Table/useTableGroupedRows.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableGroupedRows',
   description:
-    'Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group\u2019s data rows while keeping the header visible. Mirrors useTableRowExpansionState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey} \u2014 pass all three to Table (data, plugins, and idKey respectively).',
+    'Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group\'s data rows while keeping the header visible. Mirrors useTableRowExpansionState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey}: pass all three to Table (data, plugins, and idKey respectively).',
   props: [
     {
       name: 'data',
@@ -58,10 +58,10 @@ export const docs = {
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
   description:
-    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey} \u2014 pass to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
+    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey}: pass to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
   propDescriptions: {
     data: 'The flat data to group.',
-    groupBy: 'Derive a row\u2019s group key. Same key = same section.',
+    groupBy: 'Derive a row\'s group key. Same key = same section.',
     collapsedGroups: 'Set of currently-collapsed group keys.',
     onToggleGroup: 'Called with the group key when a header is toggled.',
     renderGroupHeader: "Custom header content (right of chevron). Default '<key> (<count>)'.",

package/src/Table/useTableSortable.doc.mjs

@@ -13,20 +13,20 @@ export const docs = {
   props: [
     {
       name: 'sort',
-      type: 'TableSortState<TSortKey>',
-      description: 'Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.',
+      type: "Array<{sortKey: TSortKey, direction: 'ascending' | 'descending'}>",
+      description: "Current sort state (TableSortState<TSortKey>). Ordered array of entries; the first is the primary sort, the rest are tiebreakers. An empty array means unsorted. Direction is the full word: 'ascending' / 'descending', not 'asc' / 'desc'.",
       required: true,
     },
     {
       name: 'onSortChange',
-      type: '(sort: TableSortState<TSortKey>) => void',
-      description: 'Called when the user clicks a header cell to change sort.',
+      type: "(sort: Array<{sortKey: TSortKey, direction: 'ascending' | 'descending'}>) => void",
+      description: 'Called when the user clicks a header cell to change sort. Receives the next sort state.',
       required: true,
     },
     {
       name: 'allowUnsortedState',
       type: 'boolean',
-      description: 'Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.',
+      description: "Allow cycling back to unsorted. When true: 'ascending', 'descending', unsorted. When false: 'ascending', 'descending', 'ascending'.",
       default: 'false',
     },
     {
@@ -45,20 +45,20 @@ export const docsZh = {
   props: [
     {
       name: 'sort',
-      type: 'TableSortState<TSortKey>',
-      description: '当前排序状态。{sortKey, direction} 条目的有序数组。第一个条目是主排序。',
+      type: "Array<{sortKey: TSortKey, direction: 'ascending' | 'descending'}>",
+      description: "当前排序状态。{sortKey, direction} 条目的有序数组。第一个条目是主排序。方向值为完整单词 'ascending' / 'descending'，不是 'asc' / 'desc'。",
       required: true,
     },
     {
       name: 'onSortChange',
-      type: '(sort: TableSortState<TSortKey>) => void',
+      type: "(sort: Array<{sortKey: TSortKey, direction: 'ascending' | 'descending'}>) => void",
       description: '用户点击表头单元格更改排序时调用。',
       required: true,
     },
     {
       name: 'allowUnsortedState',
       type: 'boolean',
-      description: '允许循环回到未排序状态。为 true 时：升序、降序、未排序。为 false 时：升序、降序、升序。',
+      description: "允许循环回到未排序状态。为 true 时：'ascending'、'descending'、未排序。为 false 时：'ascending'、'descending'、'ascending'。",
       default: 'false',
     },
     {
@@ -75,9 +75,9 @@ export const docsDense = {
   displayName: 'useTableSortable',
   description: 'Headless multi-sort plugin. Consumer owns sort state + callback. Shift+click for secondary sort. Sort indicators auto-render in header cells.',
   propDescriptions: {
-    sort: 'Current sort state; ordered array of {sortKey, direction} entries.',
+    sort: "Current sort state; ordered array of {sortKey, direction: 'ascending'|'descending'} entries. Not 'asc'/'desc'.",
     onSortChange: 'Called on header click to change sort.',
-    allowUnsortedState: 'Allow cycling to unsorted. true: asc>desc>unsorted. false: asc>desc>asc.',
+    allowUnsortedState: "Allow cycling to unsorted. true: ascending>descending>unsorted. false: ascending>descending>ascending.",
     isMultiSortEnabled: 'Enable multi-sort via Shift+click. Regular click replaces sort state.',
   },
 };

package/src/Table/useTableTreeData.doc.mjs

@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableTreeData',
+  subComponentOf: 'Table',
+  displayName: 'useTableTreeData',
+  description:
+    'Headless tree plugin for Table: renders nested rows with per-level indentation and expand/collapse chevrons in the tree column (the first column by default), and reflects hierarchy on body rows via aria-level and aria-expanded. Composable with the other Table plugins: the canonical plugin order places tree before selection, so the checkbox column lands left of the indented tree column. Feed it the treeConfig from useTableTreeState, or construct the config directly for server-driven or pre-flattened trees. When no row is expandable (flat data), every transform is a pass-through and the table renders identically to one without the plugin. Known limitation: the tree column wraps its cell content, so textOverflow="truncate" tooltips do not apply within the tree column.',
+  props: [
+    {
+      name: 'getRowMeta',
+      type: '(item: T) => TableTreeRowMeta | undefined',
+      description:
+        'Structural meta for a visible row: {id, level (0-based), hasChildren, isExpanded}.',
+      required: true,
+    },
+    {
+      name: 'onToggleItem',
+      type: '(item: T) => void',
+      description: 'Toggle a row’s expansion.',
+      required: true,
+    },
+    {
+      name: 'hasExpandableRows',
+      type: 'boolean',
+      description:
+        'Whether any row in the dataset is expandable. When false the plugin is a no-op: no expanders, no indent, no tree ARIA.',
+      required: true,
+    },
+    {
+      name: 'indent',
+      type: "'sm' | 'md' | 'lg'",
+      description:
+        'Indent step per level, mapped to the spacing-3 / spacing-4 / spacing-6 tokens.',
+      default: "'md'",
+    },
+    {
+      name: 'treeColumnKey',
+      type: 'string',
+      description:
+        'Column that carries the indent + expander. Defaults to the first column.',
+    },
+  ],
+  examples: [
+    {
+      label: 'File tree with expandable folders',
+      code: `const {visibleData, treeConfig} = useTableTreeState({
+  data: files,          // rows may nest under 'children'
+  idKey: 'id',
+  defaultExpandedIds: ['src'],
+});
+const tree = useTableTreeData(treeConfig);
+
+<Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />;`,
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableTreeData',
+  displayName: 'useTableTreeData',
+  description:
+    'Headless tree plugin: indent + expander chevron on the tree column (first column by default), aria-level/aria-expanded on body rows. Canonical plugin order puts tree before selection (checkbox column lands left of tree column). Consume treeConfig from useTableTreeState, or construct directly for server-driven trees. hasExpandableRows=false => full no-op (flat-data migration).',
+  propDescriptions: {
+    getRowMeta:
+      'structural meta per visible row: {id, level (0-based), hasChildren, isExpanded}',
+    onToggleItem: 'toggle row expansion',
+    hasExpandableRows: 'false => plugin is a no-op (no expanders/indent/ARIA)',
+    indent:
+      "indent step per level: 'sm' | 'md' | 'lg' (spacing-3/4/6). Defaults to 'md'.",
+    treeColumnKey: 'column carrying indent + expander. Defaults to first column.',
+  },
+};

package/src/Table/useTableTreeState.doc.mjs

@@ -0,0 +1,98 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableTreeState',
+  subComponentOf: 'Table',
+  displayName: 'useTableTreeState',
+  description:
+    'State management companion for useTableTreeData. Owns the expanded set (controlled or uncontrolled) and flattens nested data into the visible row array — collapsed subtrees are unmounted, not hidden, so the table body contains exactly the visible rows. Returns expandAll/collapseAll helpers and a ready-to-use config for the tree plugin. Note: because collapsed rows unmount, cell-local React state inside collapsed subtrees is lost on collapse; lift state that must survive.',
+  props: [
+    {
+      name: 'data',
+      type: 'T[]',
+      description:
+        'Nested data: rows may carry child rows under childrenKey. Flat data (no children anywhere) makes the plugin a no-op, so it can be adopted before the data becomes hierarchical.',
+      required: true,
+    },
+    {
+      name: 'idKey',
+      type: '(keyof T & string) | ((item: T) => string | number)',
+      description:
+        'Row ID accessor: property name or function returning a unique id.',
+      required: true,
+    },
+    {
+      name: 'childrenKey',
+      type: 'string',
+      description: 'Property holding each row’s children array.',
+      default: "'children'",
+    },
+    {
+      name: 'defaultExpandedIds',
+      type: 'Iterable<string>',
+      description:
+        'Initial expanded row ids for uncontrolled mode. Ignored when expandedIds is provided.',
+    },
+    {
+      name: 'expandedIds',
+      type: 'ReadonlySet<string>',
+      description:
+        'Controlled set of expanded row ids. Pair with onExpandedIdsChange.',
+    },
+    {
+      name: 'onExpandedIdsChange',
+      type: '(ids: ReadonlySet<string>) => void',
+      description:
+        'Called with the next expanded set whenever expansion changes (both modes). In lazy-loading setups, trigger the children fetch here.',
+    },
+    {
+      name: 'isItemExpandable',
+      type: '(item: T) => boolean',
+      description:
+        'Should this row show an expander? Overrides the default non-empty-children check — use for lazy loading, where a row is expandable before its children have been fetched.',
+    },
+    {
+      name: 'sortSiblings',
+      type: '(siblings: T[]) => T[]',
+      description:
+        'Sort each sibling group independently during flattening; children always stay directly under their parent. Pass applySort from useTableSortableState to compose with column sorting.',
+    },
+    {
+      name: 'indent',
+      type: "'sm' | 'md' | 'lg'",
+      description:
+        'Indent step per level (spacing-3 / spacing-4 / spacing-6), forwarded to useTableTreeData.',
+      default: "'md'",
+    },
+    {
+      name: 'treeColumnKey',
+      type: 'string',
+      description:
+        'Column that carries the indent + expander, forwarded to useTableTreeData. Defaults to the first column.',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableTreeState',
+  displayName: 'useTableTreeState',
+  description:
+    'State companion for useTableTreeData. Owns expanded set (controlled or uncontrolled), flattens nested data to visible rows (collapsed subtrees unmounted, not hidden). Returns {visibleData, treeConfig, expandedIds, expandAll, collapseAll}. Cell-local state in collapsed subtrees is lost on collapse; lift state that must survive.',
+  propDescriptions: {
+    data: 'nested data; rows carry child rows under childrenKey. Flat data => plugin is a no-op.',
+    idKey: 'row ID accessor: property name or fn returning unique id',
+    childrenKey: "property holding children array. Defaults to 'children'.",
+    defaultExpandedIds: 'initial expanded ids (uncontrolled)',
+    expandedIds: 'controlled expanded set; pair with onExpandedIdsChange',
+    onExpandedIdsChange:
+      'called with next expanded set on change (both modes); trigger lazy children fetch here',
+    isItemExpandable:
+      'overrides non-empty-children expandability check (lazy loading)',
+    sortSiblings:
+      'sorts each sibling group during flattening; pass applySort from useTableSortableState',
+    indent: "indent step per level: 'sm' | 'md' | 'lg'. Defaults to 'md'.",
+    treeColumnKey: 'column carrying indent + expander. Defaults to first column.',
+  },
+};

package/src/Text/Text.doc.mjs

@@ -23,8 +23,8 @@ export const docs = {
   props: [
     {
       name: 'type',
-      type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3'",
-      description: 'Semantic text type. Determines size, weight, and line-height from the theme. Note: this prop is called `type`, not `variant`.',
+      type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3' | 'inherit'",
+      description: "Semantic text type. Determines size, weight, and line-height from the theme. 'inherit' takes all three from the surrounding text instead. Themes may add custom types. Note: this prop is called `type`, not `variant`.",
       default: "'body'",
     },
     {