@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

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/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/useTableRowStatus.doc.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableRowStatus',
+  subComponentOf: 'Table',
+  displayName: 'useTableRowStatus',
+  description:
+    'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status: a colored status dot by default, or an icon when provided (shape + color is more accessible than color alone). getStatus maps a row to a semantic color (mapped to a theme token) or raw CSS color, an optional icon, and a required accessible label (shown in a tooltip on hover and announced to assistive technology, so status is never color-only); return null for no indicator. Memoize getStatus with useCallback for a stable plugin identity.',
+  props: [
+    {
+      name: 'getStatus',
+      type: "(item: T) => { color: 'accent' | 'success' | 'error' | 'warning' | 'red' | 'orange' | 'green' | 'yellow' | 'blue' | 'gray' | string; icon?: IconName; label: string } | null",
+      description:
+        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray — mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
+      required: true,
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Returns a TablePlugin that prepends a narrow per-row status column: a colored dot, or an icon when provided (shape + color beats color alone for a11y). getStatus maps a row to {color, icon?, label} or null. color is a semantic name (success/error/warning/etc.) mapped to a theme token, or a raw CSS color. label is required (tooltip + accessible name). Memoize getStatus with useCallback.',
+  propDescriptions: {
+    getStatus:
+      'Map a row to {color, icon?, label} or null. color = semantic status name (mapped to a token) or raw CSS; icon = shape signifier (a11y); label = required accessible name (tooltip + role="img"). Memoize with useCallback.',
+  },
+};

package/src/Table/useTableSelection.doc.mjs

@@ -6,7 +6,8 @@ export const docs = {
   name: 'useTableSelection',
   subComponentOf: 'Table',
   displayName: 'useTableSelection',
-  description: 'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
+  description:
+    'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
   props: [
     {
       name: 'getIsItemSelected',
@@ -17,7 +18,8 @@ export const docs = {
     {
       name: 'onSelectItem',
       type: '(event: {item: T; isSelected: boolean}) => void',
-      description: 'Called when a row checkbox is toggled. isSelected is the new desired state.',
+      description:
+        'Called when a row checkbox is toggled. isSelected is the new desired state.',
       required: true,
     },
     {
@@ -29,33 +31,67 @@ export const docs = {
     {
       name: 'getIsAllSelected',
       type: '() => boolean',
-      description: 'Returns whether all selectable items are currently selected.',
+      description:
+        'Returns whether all selectable items are currently selected.',
       required: true,
     },
     {
       name: 'getIsIndeterminate',
       type: '() => boolean',
-      description: 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
+      description:
+        'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
     },
     {
       name: 'getIsItemSelectable',
       type: '(item: T) => boolean',
-      description: 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
+      description:
+        'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
       default: '() => true',
     },
     {
       name: 'getIsItemEnabled',
       type: '(item: T) => boolean',
-      description: 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
+      description:
+        'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
       default: '() => true',
     },
+    {
+      name: 'getRowLabel',
+      type: '(item: T) => string',
+      description:
+        'Derives a human-readable identity for a row; the row checkbox\'s hidden label becomes `Select ${getRowLabel(item)}` so screen readers announce which row each checkbox selects. Falls back to "Select row" when omitted.',
+    },
+  ],
+  examples: [
+    {
+      label: 'Accessible per-row checkbox names',
+      code: `
+const selectionPlugin = useTableSelection({
+  getIsItemSelected: item => selectedIds.has(item.id),
+  onSelectItem: ({item, isSelected}) => toggle(item.id, isSelected),
+  onSelectAll: ({isAllSelected}) => selectAll(isAllSelected),
+  getIsAllSelected: () => selectedIds.size === users.length,
+  // Screen readers announce "Select Alice", "Select Bob", ...
+  // instead of an undifferentiated "Select row" for every checkbox.
+  getRowLabel: item => item.name,
+});
+
+<Table
+  data={users}
+  columns={columns}
+  idKey="id"
+  plugins={{selection: selectionPlugin}}
+/>;
+`,
+    },
   ],
 };
 
 export const docsZh = {
   name: 'useTableSelection',
   displayName: 'useTableSelection',
-  description: '返回 TablePlugin 的 Hook，实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
+  description:
+    '返回 TablePlugin 的 Hook，实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
   props: [
     {
       name: 'getIsItemSelected',
@@ -84,12 +120,14 @@ export const docsZh = {
     {
       name: 'getIsIndeterminate',
       type: '() => boolean',
-      description: '返回选择是否为部分选中（部分但非全部）。将全选复选框渲染为不确定状态。',
+      description:
+        '返回选择是否为部分选中（部分但非全部）。将全选复选框渲染为不确定状态。',
     },
     {
       name: 'getIsItemSelectable',
       type: '(item: T) => boolean',
-      description: '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
+      description:
+        '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
       default: '() => true',
     },
     {
@@ -98,20 +136,33 @@ export const docsZh = {
       description: '返回行复选框是否可交互。禁用的行显示禁用状态的复选框。',
       default: '() => true',
     },
+    {
+      name: 'getRowLabel',
+      type: '(item: T) => string',
+      description:
+        '为行派生人类可读的标识；行复选框的隐藏标签变为 `Select ${getRowLabel(item)}`，让屏幕阅读器播报每个复选框选择的是哪一行。省略时回退为 "Select row"。',
+    },
   ],
 };
 
 export const docsDense = {
   name: 'useTableSelection',
   displayName: 'useTableSelection',
-  description: 'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
+  description:
+    'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
   propDescriptions: {
     getIsItemSelected: 'Returns whether item is selected.',
-    onSelectItem: 'Called on row checkbox toggle; isSelected = new desired state.',
+    onSelectItem:
+      'Called on row checkbox toggle; isSelected = new desired state.',
     onSelectAll: 'Called on select-all header checkbox toggle.',
     getIsAllSelected: 'Returns whether all selectable items are selected.',
-    getIsIndeterminate: 'Returns partial selection state; renders indeterminate checkbox.',
-    getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows render nothing.',
-    getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
+    getIsIndeterminate:
+      'Returns partial selection state; renders indeterminate checkbox.',
+    getIsItemSelectable:
+      'Returns whether row shows checkbox; non-selectable rows render nothing.',
+    getIsItemEnabled:
+      'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
+    getRowLabel:
+      'Derives row identity for the checkbox\'s hidden label: `Select ${getRowLabel(item)}`. Falls back to "Select row" when omitted.',
   },
 };

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/TextArea/TextArea.doc.mjs

@@ -116,7 +116,7 @@ export const docs = {
       name: 'startIcon',
       type: 'IconType',
       description:
-        'Icon component rendered inside the leading edge of the textarea wrapper. See `npx astryx docs icons` for valid semantic names.',
+        'Icon component rendered inside the leading edge of the textarea wrapper. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'hasSpellCheck',

package/src/TextArea/TextArea.test.tsx

@@ -10,11 +10,19 @@
  */
 
 import {useState} from 'react';
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
 import {TextArea} from './TextArea';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+// FieldStatus announces status messages through the persistent useAnnounce
+// singletons; remove them between tests so role/aria-live queries in this
+// file never match a leftover region.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
 // disabledMessage tooltip.

package/src/TextInput/TextInput.doc.mjs

@@ -106,7 +106,7 @@ export const docs = {
       name: 'startIcon',
       type: 'IconType',
       description:
-        'SVG icon component displayed at the start of the input. See `npx astryx docs icons` for valid semantic names.',
+        'SVG icon component displayed at the start of the input. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'status',