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

package/dist/Table/plugins/tree/useTableTreeData.js

@@ -0,0 +1,358 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableTreeData.tsx
+ * @input React, StyleX, Icon, Table types, theme tokens, i18n (useTranslator)
+ * @output Exports useTableTreeData hook + config/meta types
+ * @position Tree plugin; consumed by Table via plugins prop.
+ *   Pairs with useTableTreeState (owns expansion state + flattening).
+ *
+ * ## Architecture (mirrors useTableSelection)
+ *
+ * The tree affordance decorates the tree column's cells in place — no
+ * synthetic column. `transformColumns` wraps the tree column's renderCell
+ * with a flex wrapper carrying per-level indentation and an expander
+ * button (or a fixed-width spacer on leaves). Other columns get zero
+ * extra DOM.
+ *
+ * Expansion state flows through an external store (TreeStore) so each
+ * row's expander subscribes independently — a toggle re-renders only the
+ * affected cells, not the whole body. Row ARIA (aria-level,
+ * aria-expanded) is applied imperatively via a ref callback on each
+ * <tr>, exactly like selection's row styling; each subscription
+ * self-cleans when the row disconnects.
+ *
+ * When `hasExpandableRows` is false (flat data), every transform is a
+ * pass-through: adopting the plugin ahead of hierarchical data is a
+ * no-op.
+ */
+import { createContext, use, useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../../../theme/tokens.stylex.js";
+import { colorVars, radiusVars, spacingVars } from "../../../theme/tokens.stylex.js";
+import { Icon } from "../../../Icon/index.js";
+import { mergeRefs } from "../../../utils/index.js";
+import { useTranslator } from "../../../i18n/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Structural position of one visible row within the tree. */
+
+/**
+ * Configuration for useTableTreeData. `useTableTreeState` returns a
+ * ready-made value (`treeConfig`); consumers with server-driven or
+ * pre-flattened trees can construct one directly.
+ */
+
+// =============================================================================
+// Tree Store (external store for fine-grained row subscriptions)
+// =============================================================================
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+function createTreeStore(configRef) {
+  const listeners = new Set();
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    notify() {
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    getConfig() {
+      return configRef.current;
+    }
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const TreeStoreContext = /*#__PURE__*/createContext(null);
+TreeStoreContext.displayName = 'TreeStoreContext';
+
+/** Indent token -> index, for the numeric row snapshot. */
+const INDENT_INDEX = {
+  sm: 0,
+  md: 1,
+  lg: 2
+};
+
+/**
+ * Encode a row's tree meta as a primitive for useSyncExternalStore —
+ * object snapshots would tear. The indent token participates so a
+ * runtime `indent` change re-renders the affected cells.
+ * Encoding: level * 16 + indentIndex * 4 + hasChildren * 2 + isExpanded;
+ * -1 = no meta.
+ */
+function encodeRowMeta(config, item) {
+  const meta = config.getRowMeta(item);
+  if (!meta) {
+    return -1;
+  }
+  return meta.level * 16 + INDENT_INDEX[config.indent ?? 'md'] * 4 + (meta.hasChildren ? 2 : 0) + (meta.isExpanded ? 1 : 0);
+}
+function useRowMetaSnapshot(store, item) {
+  const getSnapshot = useCallback(() => encodeRowMeta(store.getConfig(), item), [store, item]);
+  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+
+// =============================================================================
+// Row ARIA (imperative, mirrors selection's row styling)
+// =============================================================================
+
+function applyRowTreeAria(el, meta) {
+  if (!meta) {
+    el.removeAttribute('aria-level');
+    el.removeAttribute('aria-expanded');
+    return;
+  }
+  el.setAttribute('aria-level', String(meta.level + 1));
+  if (meta.hasChildren) {
+    el.setAttribute('aria-expanded', String(meta.isExpanded));
+  } else {
+    el.removeAttribute('aria-expanded');
+  }
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+/** Indent step per level, by the `indent` config token. */
+const INDENT_STEP = {
+  sm: spacingVars['--spacing-3'],
+  md: spacingVars['--spacing-4'],
+  lg: spacingVars['--spacing-6']
+};
+const treeStyles = {
+  cell: {
+    k1xSpc: "x78zum5",
+    kGNEyG: "x6s0dn4",
+    kOIVth: "xzye2dw",
+    $$css: true
+  },
+  indent: paddingInlineStart => [{
+    kZCmMZ: paddingInlineStart != null ? "xnvo3vl" : paddingInlineStart,
+    $$css: true
+  }, {
+    "--x-paddingInlineStart": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(paddingInlineStart)
+  }]
+};
+
+// =============================================================================
+// Cell content
+// =============================================================================
+
+function TreeExpander({
+  isExpanded,
+  onToggle
+}) {
+  const t = useTranslator();
+  return /*#__PURE__*/_jsx("button", {
+    type: "button",
+    ...{
+      className: "x3nfvp2 x6s0dn4 xl56j7k xvy4d1p xxk0z11 xx3sua9 x1ypdohk xv9yike x1gbuem2 xx6bhzk x1717udv x2lah0s x1ilzqfv x1cqbx0l"
+    },
+    onClick: e => {
+      e.stopPropagation();
+      onToggle();
+    },
+    "aria-label": isExpanded ? t('@astryx.tableTree.collapseRow') : t('@astryx.tableTree.expandRow'),
+    "aria-expanded": isExpanded,
+    children: /*#__PURE__*/_jsx("span", {
+      ...{
+        0: {
+          className: "x3nfvp2 x11xpdln xx6bhzk x7p49u4"
+        },
+        1: {
+          className: "x3nfvp2 x11xpdln xx6bhzk x1iffjtl"
+        }
+      }[!!isExpanded << 0],
+      children: /*#__PURE__*/_jsx(Icon, {
+        icon: "chevronRight",
+        size: "xsm"
+      })
+    })
+  });
+}
+function TreeCellContent({
+  item,
+  children
+}) {
+  const store = use(TreeStoreContext);
+  if (!store) {
+    return /*#__PURE__*/_jsx(_Fragment, {
+      children: children
+    });
+  }
+  return /*#__PURE__*/_jsx(TreeCellContentInner, {
+    store: store,
+    item: item,
+    children: children
+  });
+}
+function TreeCellContentInner({
+  store,
+  item,
+  children
+}) {
+  // Subscribe to this row's structural meta so a toggle re-renders only
+  // the affected cells.
+  useRowMetaSnapshot(store, item);
+  const config = store.getConfig();
+  const meta = config.getRowMeta(item);
+  if (!meta) {
+    return /*#__PURE__*/_jsx(_Fragment, {
+      children: children
+    });
+  }
+  const step = INDENT_STEP[config.indent ?? 'md'];
+  const indent = `calc(${meta.level} * ${step})`;
+  return /*#__PURE__*/_jsxs("div", {
+    ...stylex.props(treeStyles.cell, meta.level > 0 && treeStyles.indent(indent)),
+    children: [meta.hasChildren ? /*#__PURE__*/_jsx(TreeExpander, {
+      isExpanded: meta.isExpanded,
+      onToggle: () => store.getConfig().onToggleItem(item)
+    }) : /*#__PURE__*/_jsx("span", {
+      ...{
+        className: "x1rg5ohu xvy4d1p xxk0z11 x2lah0s"
+      }
+    }), children]
+  });
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useTableTreeData(config) {
+  const configRef = useRef(config);
+  configRef.current = config;
+  const storeRef = useRef(null);
+  if (storeRef.current == null) {
+    storeRef.current = createTreeStore(configRef);
+  }
+  const store = storeRef.current;
+
+  // Notify subscribers on every render — useSyncExternalStore only
+  // re-renders cells whose snapshot actually changed. Row ref subscribers
+  // apply imperative ARIA independently.
+  useEffect(() => {
+    store.notify();
+  });
+
+  // transformColumns runs on every table render; wrapped column objects
+  // must keep their identity across renders or the per-row memo breaks
+  // and a toggle re-renders the whole body. Earlier plugins may rebuild
+  // structurally-identical arrays each render, so the cache compares
+  // input columns by shallow equality, not array identity. Held in a ref
+  // (like rowExpansion's column tracking) — transforms run during
+  // BaseTable's render, where a closure variable reassignment trips the
+  // react-compiler lint.
+  const columnsCacheRef = useRef(null);
+
+  // The plugin object is created once per store and never changes shape:
+  // every transform reads the live config through the store, and
+  // internally no-ops when hasExpandableRows is false. Swapping between
+  // an empty and a context-wrapping plugin would change the element tree
+  // and remount the whole table when flat data turns nested.
+  return useMemo(() => {
+    const getCachedColumns = (columns, treeKey, wrapped) => {
+      const cache = columnsCacheRef.current;
+      if (!cache || cache.treeKey !== treeKey || cache.wrapped !== wrapped) {
+        return null;
+      }
+      const prev = cache.input;
+      if (prev !== columns) {
+        if (prev.length !== columns.length) {
+          return null;
+        }
+        for (let i = 0; i < prev.length; i++) {
+          if (prev[i] !== columns[i]) {
+            return null;
+          }
+        }
+      }
+      return cache.output;
+    };
+    return {
+      transformTableContext(children) {
+        return /*#__PURE__*/_jsx(TreeStoreContext, {
+          value: store,
+          children: children
+        });
+      },
+      transformColumns(columns) {
+        const {
+          hasExpandableRows,
+          treeColumnKey
+        } = store.getConfig();
+
+        // Resolve the tree column: the configured key when present, else
+        // the first non-synthetic column (a configured column may have
+        // been hidden by columnSettings — the expander must not vanish).
+        const configuredExists = treeColumnKey != null && columns.some(c => c.key === treeColumnKey);
+        const treeKey = configuredExists ? treeColumnKey : columns.find(c => !c.key.startsWith('__'))?.key ?? columns[0]?.key;
+
+        // Migration guarantee: flat data renders identically to a Table
+        // without the plugin.
+        const wrapped = hasExpandableRows;
+        const cached = getCachedColumns(columns, treeKey, wrapped);
+        if (cached) {
+          return cached;
+        }
+        const output = !wrapped ? columns : columns.map(col => {
+          if (col.key !== treeKey) {
+            return col;
+          }
+          const originalRenderCell = col.renderCell;
+          return {
+            ...col,
+            renderCell: item => /*#__PURE__*/_jsx(TreeCellContent, {
+              item: item,
+              children: originalRenderCell ? originalRenderCell(item) : String(item[col.key] ?? '')
+            })
+          };
+        });
+        columnsCacheRef.current = {
+          input: columns,
+          treeKey,
+          wrapped,
+          output
+        };
+        return output;
+      },
+      transformBodyRow(props, item) {
+        // Attach a ref that subscribes to the store for imperative row
+        // ARIA. The ref returns a cleanup so React unsubscribes on
+        // detach — without it, every row re-render would leak one
+        // subscription (toggles shift rowIndex and re-render rows, so
+        // the listener set would grow on every toggle). The ref is
+        // attached even when no row is expandable so tree ARIA is
+        // removed if the data turns flat.
+        const treeRef = el => {
+          if (!el) {
+            return;
+          }
+          const apply = () => {
+            const cfg = store.getConfig();
+            applyRowTreeAria(el, cfg.hasExpandableRows ? cfg.getRowMeta(item) : undefined);
+          };
+          apply();
+          const unsub = store.subscribe(apply);
+          return () => {
+            unsub();
+          };
+        };
+        return {
+          ...props,
+          ref: props.ref ? mergeRefs(props.ref, treeRef) : treeRef
+        };
+      }
+    };
+  }, [store]);
+}

package/dist/Table/plugins/tree/useTableTreeState.d.ts

@@ -0,0 +1,51 @@
+import type { UseTableTreeDataConfig } from './useTableTreeData';
+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;
+}
+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;
+}
+export declare function useTableTreeState<T extends Record<string, unknown>>(config: UseTableTreeStateConfig<T>): UseTableTreeStateResult<T>;
+//# sourceMappingURL=useTableTreeState.d.ts.map

package/dist/Table/plugins/tree/useTableTreeState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTableTreeState.d.ts","sourceRoot":"","sources":["../../../../src/Table/plugins/tree/useTableTreeState.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAM5B,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxE,kEAAkE;IAClE,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,2EAA2E;IAC3E,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,CAAC,CAAC;IAC3D;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,kBAAkB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtC;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IACzD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IACxC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;IACtC,4DAA4D;IAC5D,MAAM,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC5B,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxE,qEAAqE;IACrE,WAAW,EAAE,CAAC,EAAE,CAAC;IACjB,gDAAgD;IAChD,UAAU,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IACtC,oCAAoC;IACpC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,+CAA+C;IAC/C,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAMD,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACjC,uBAAuB,CAAC,CAAC,CAAC,CAoK5B"}

package/dist/Table/plugins/tree/useTableTreeState.js

@@ -0,0 +1,175 @@
+// 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';
+
+// =============================================================================
+// Config
+// =============================================================================
+
+// =============================================================================
+// Result
+// =============================================================================
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useTableTreeState(config) {
+  const {
+    data,
+    idKey,
+    childrenKey = 'children',
+    defaultExpandedIds,
+    expandedIds: controlledExpandedIds,
+    onExpandedIdsChange,
+    isItemExpandable,
+    sortSiblings,
+    indent,
+    treeColumnKey
+  } = config;
+  const getId = useCallback(item => typeof idKey === 'function' ? String(idKey(item)) : String(item[idKey]), [idKey]);
+  const getChildren = useCallback(item => {
+    const children = item[childrenKey];
+    return Array.isArray(children) ? children : [];
+  }, [childrenKey]);
+  const getIsExpandable = useCallback(item => isItemExpandable ? isItemExpandable(item) : getChildren(item).length > 0, [isItemExpandable, getChildren]);
+
+  // Internal state (used in uncontrolled mode)
+  const [internalExpandedIds, setInternalExpandedIds] = useState(() => 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 => {
+    // 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 = [];
+    const meta = new Map();
+    const path = new Set();
+    const walk = (items, level) => {
+      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 = [];
+    const path = new Set();
+    const walk = items => {
+      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 => {
+    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 => metaMap.get(getId(item)), [metaMap, getId]);
+  const treeConfig = useMemo(() => ({
+    getRowMeta,
+    onToggleItem,
+    hasExpandableRows,
+    indent,
+    treeColumnKey
+  }), [getRowMeta, onToggleItem, hasExpandableRows, indent, treeColumnKey]);
+  return {
+    visibleData,
+    treeConfig,
+    expandedIds,
+    expandAll,
+    collapseAll
+  };
+}

package/dist/Table/types.d.ts

@@ -181,12 +181,12 @@ 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;
 }
 /**
@@ -206,7 +206,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. */
@@ -241,7 +241,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>;
@@ -249,7 +249,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
@@ -294,7 +294,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. */
@@ -449,7 +449,14 @@ export interface BaseTableProps<T extends Record<string, unknown>> extends BaseP
     plugins?: TablePlugin<T>[];
     /** 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
@@ -457,9 +464,9 @@ export interface BaseTableProps<T extends Record<string, unknown>> extends BaseP
      * 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<{
@@ -467,7 +474,7 @@ export interface BaseTableProps<T extends Record<string, unknown>> extends BaseP
         htmlProps?: HTMLAttributes<HTMLDivElement> & {
             ref?: Ref<HTMLDivElement>;
         };
-        styles?: StyleXStyles[];
+        xstyle?: StyleXStyles[];
         beforeTable?: ReactNode;
         afterTable?: ReactNode;
     }>;