@astryxdesign/core 0.1.1 → 0.1.2-canary.03536f1

package/dist/Table/plugins/sortable/useTableSortable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTableSortable.d.ts","sourceRoot":"","sources":["../../../../src/Table/plugins/sortable/useTableSortable.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,WAAW,EAGZ,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IAC9D,2EAA2E;IAC3E,OAAO,EAAE,QAAQ,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,IACzD,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;AAM7B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IACtE,iEAAiE;IACjE,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE/B;;;OAGG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAEvD;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAmND;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,SAAS,MAAM,GAAG,MAAM,EAChC,MAAM,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAuC1D"}
+{"version":3,"file":"useTableSortable.d.ts","sourceRoot":"","sources":["../../../../src/Table/plugins/sortable/useTableSortable.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IAC9D,2EAA2E;IAC3E,OAAO,EAAE,QAAQ,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,IACzD,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;AAM7B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IACtE,iEAAiE;IACjE,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE/B;;;OAGG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAEvD;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAmND;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,SAAS,MAAM,GAAG,MAAM,EAChC,MAAM,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAyF1D"}

package/dist/Table/plugins/sortable/useTableSortable.js

@@ -17,6 +17,7 @@ import * as stylex from '@stylexjs/stylex';
 import "../../../theme/tokens.stylex.js";
 import { colorVars, spacingVars, radiusVars } from "../../../theme/tokens.stylex.js";
 import { Icon } from "../../../Icon/index.js";
+import { resolveContextActions } from "../../tableContextMenu.js";
 
 // =============================================================================
 // Sort Types
@@ -243,10 +244,64 @@ export function useTableSortable(config) {
       if (sortKey == null) {
         return props;
       }
-
-      // Find sort entry for this column
       const cfg = configRef.current;
       const entry = cfg.sort.find(e => e.sortKey === sortKey);
+
+      // Context-menu actions are built lazily (only when the menu opens) via
+      // a getter, reading the current sort state at call time — so we don't
+      // build an action array for every header on every render, and the
+      // checked/clear state always reflects the latest sort.
+      const getSortActions = () => {
+        const c = configRef.current;
+        const dir = c.sort.find(e => e.sortKey === sortKey)?.direction ?? null;
+        const actions = [{
+          id: 'sort-asc',
+          group: 'sort',
+          label: 'Sort ascending',
+          icon: /*#__PURE__*/_jsx(Icon, {
+            icon: "arrowUp",
+            size: "xsm",
+            "aria-hidden": true
+          }),
+          checked: dir === 'ascending',
+          onSelect: () => c.onSortChange([{
+            sortKey: sortKey,
+            direction: 'ascending'
+          }])
+        }, {
+          id: 'sort-desc',
+          group: 'sort',
+          label: 'Sort descending',
+          icon: /*#__PURE__*/_jsx(Icon, {
+            icon: "arrowDown",
+            size: "xsm",
+            "aria-hidden": true
+          }),
+          checked: dir === 'descending',
+          onSelect: () => c.onSortChange([{
+            sortKey: sortKey,
+            direction: 'descending'
+          }])
+        }];
+        if (dir != null) {
+          actions.push({
+            id: 'sort-clear',
+            group: 'sort-clear',
+            label: 'Clear sort',
+            icon: /*#__PURE__*/_jsx(Icon, {
+              icon: "close",
+              size: "xsm",
+              "aria-hidden": true
+            }),
+            onSelect: () => c.onSortChange(c.sort.filter(e => e.sortKey !== sortKey))
+          });
+        }
+        return actions;
+      };
+
+      // Merge with any actions a prior plugin contributed (array or getter),
+      // resolving both lazily at open time.
+      const priorActions = props.contextMenuActions;
       return {
         ...props,
         htmlProps: {
@@ -259,7 +314,8 @@ export function useTableSortable(config) {
           column: column,
           configRef: configRef,
           children: props.content
-        })
+        }),
+        contextMenuActions: () => [...resolveContextActions(priorActions), ...getSortActions()]
       };
     }
   }), []);

package/dist/Table/plugins/stickyColumns/index.d.ts

@@ -0,0 +1,3 @@
+export { useTableStickyColumns } from './useTableStickyColumns';
+export type { UseTableStickyColumnsConfig } from './useTableStickyColumns';
+//# sourceMappingURL=index.d.ts.map

package/dist/Table/plugins/stickyColumns/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/Table/plugins/stickyColumns/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,YAAY,EAAC,2BAA2B,EAAC,MAAM,yBAAyB,CAAC"}

package/dist/Table/plugins/stickyColumns/index.js

@@ -0,0 +1,3 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export { useTableStickyColumns } from "./useTableStickyColumns.js";

package/dist/Table/plugins/stickyColumns/useTableStickyColumns.d.ts

@@ -0,0 +1,25 @@
+import type { TablePlugin } from '../../types';
+/**
+ * Config for {@link useTableStickyColumns}. Provide at least one of
+ * `startKeys` / `endKeys` to pin columns.
+ *
+ * @remarks Every field is optional by design, so `useTableStickyColumns({})`
+ * compiles and is an intentional no-op that pins nothing — the hook returns a
+ * plugin that passes every cell through untouched. This lets callers compute
+ * the config conditionally (e.g. `endKeys: enabled ? ['notes'] : undefined`)
+ * without branching on whether to install the plugin at all.
+ */
+export interface UseTableStickyColumnsConfig {
+    /**
+     * Column keys pinned to the START (inline-start / left in LTR) edge — the
+     * contiguous run from the first column through the last listed key.
+     */
+    startKeys?: string[];
+    /**
+     * Column keys pinned to the END (inline-end / right in LTR) edge — the
+     * contiguous run from the first listed key through the last column.
+     */
+    endKeys?: string[];
+}
+export declare function useTableStickyColumns<T extends Record<string, unknown>>(config: UseTableStickyColumnsConfig): TablePlugin<T>;
+//# sourceMappingURL=useTableStickyColumns.d.ts.map

package/dist/Table/plugins/stickyColumns/useTableStickyColumns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTableStickyColumns.d.ts","sourceRoot":"","sources":["../../../../src/Table/plugins/stickyColumns/useTableStickyColumns.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAEV,WAAW,EAIZ,MAAM,aAAa,CAAC;AAOrB;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AA6MD,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,MAAM,EAAE,2BAA2B,GAClC,WAAW,CAAC,CAAC,CAAC,CAmJhB"}

package/dist/Table/plugins/stickyColumns/useTableStickyColumns.js

@@ -0,0 +1,369 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableStickyColumns.tsx
+ * @input React, StyleX, theme tokens, Table types
+ * @output Exports useTableStickyColumns hook and UseTableStickyColumnsConfig type
+ * @position Sticky-columns plugin; consumed by Table via plugins prop
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/Table.doc.mjs (sticky-columns documentation)
+ * - /packages/core/src/Table/index.ts (exports)
+ */
+import { useCallback, useMemo, useRef } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../../../theme/tokens.stylex.js";
+import { colorVars, durationVars, easeVars } from "../../../theme/tokens.stylex.js";
+import { DEFAULT_MIN_COLUMN_WIDTH } from "../../columnUtils.js";
+
+// =============================================================================
+// Config
+// =============================================================================
+
+/**
+ * Config for {@link useTableStickyColumns}. Provide at least one of
+ * `startKeys` / `endKeys` to pin columns.
+ *
+ * @remarks Every field is optional by design, so `useTableStickyColumns({})`
+ * compiles and is an intentional no-op that pins nothing — the hook returns a
+ * plugin that passes every cell through untouched. This lets callers compute
+ * the config conditionally (e.g. `endKeys: enabled ? ['notes'] : undefined`)
+ * without branching on whether to install the plugin at all.
+ */
+
+// =============================================================================
+// Width helpers
+// =============================================================================
+
+/**
+ * Resolve a column's pixel width for cumulative offset math. Mirrors the
+ * resize plugin's fallback so offsets line up with rendered widths:
+ * pixel columns use their value; proportional columns use their declared
+ * minWidth (or the default); unknown widths use the default.
+ */
+function getColumnWidth(col) {
+  const w = col.width;
+  if (!w) {
+    return DEFAULT_MIN_COLUMN_WIDTH;
+  }
+  if (w.type === 'pixel') {
+    return w.value;
+  }
+  // proportional
+  return w.minWidth ?? DEFAULT_MIN_COLUMN_WIDTH;
+}
+
+/**
+ * Columns pinned to the START edge → cumulative inline offset (px). The pinned
+ * block is the contiguous run from column 0 through the last key in `startKeys`
+ * (inclusive of any synthetic columns before it). `null` if none / no context.
+ */
+function computeStartOffsets(columns, startKeys) {
+  if (!columns || columns.length === 0 || startKeys.length === 0) {
+    return null;
+  }
+  let lastStickyIndex = -1;
+  for (let i = 0; i < columns.length; i++) {
+    if (startKeys.includes(columns[i].key)) {
+      lastStickyIndex = i;
+    }
+  }
+  if (lastStickyIndex === -1) {
+    return null;
+  }
+  const offsets = new Map();
+  let cumulative = 0;
+  for (let i = 0; i <= lastStickyIndex; i++) {
+    offsets.set(columns[i].key, cumulative);
+    cumulative += getColumnWidth(columns[i]);
+  }
+  return offsets;
+}
+
+/**
+ * Mirror of {@link computeStartOffsets} for the END edge — contiguous run from
+ * the first key in `endKeys` through the last column, offsets accumulating from
+ * the end (last column = 0). `null` if none.
+ */
+function computeEndOffsets(columns, endKeys) {
+  if (!columns || columns.length === 0 || endKeys.length === 0) {
+    return null;
+  }
+  let firstStickyIndex = -1;
+  for (let i = 0; i < columns.length; i++) {
+    if (endKeys.includes(columns[i].key)) {
+      firstStickyIndex = i;
+      break;
+    }
+  }
+  if (firstStickyIndex === -1) {
+    return null;
+  }
+  const offsets = new Map();
+  let cumulative = 0;
+  for (let i = columns.length - 1; i >= firstStickyIndex; i--) {
+    offsets.set(columns[i].key, cumulative);
+    cumulative += getColumnWidth(columns[i]);
+  }
+  return offsets;
+}
+/**
+ * Resolve how a single column should be pinned given the start/end configs and
+ * the full column list. A key (mis)configured on both edges resolves to start.
+ * Returns `null` for columns that should not be pinned.
+ */
+function resolveStickySide(columns, columnKey, startKeys, endKeys) {
+  const startOffsets = computeStartOffsets(columns, startKeys);
+  if (startOffsets?.has(columnKey)) {
+    return {
+      edge: 'start',
+      offset: startOffsets.get(columnKey) ?? 0
+    };
+  }
+  const endOffsets = computeEndOffsets(columns, endKeys);
+  if (endOffsets?.has(columnKey)) {
+    return {
+      edge: 'end',
+      offset: endOffsets.get(columnKey) ?? 0
+    };
+  }
+  return null;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+// Scroll-state CSS variables set on the scroll container by the layout ref;
+// the cell ::after shadows read them so each edge's shadow only shows when
+// content is hidden behind it. (A variable, not stylex.when.ancestor, because
+// StyleX ancestor selectors are pseudo-class only — not scroll state.)
+const SHADOW_VAR_START = '--table-sticky-shadow-start';
+const SHADOW_VAR_END = '--table-sticky-shadow-end';
+const stickyStyles = {
+  cell: {
+    kVAEAm: "x7wzq59",
+    kWkggS: "x1fd97le",
+    kgeoSG: "x1cpjm7i",
+    kEoFBp: "x1hmns74",
+    kFcpXp: "xxx281p",
+    kxmVGU: "xy5mcqj",
+    km8f2m: "xkk1bqk",
+    kLkRvE: "x1uvfo0n",
+    k7KCAZ: "xxcwgru",
+    kKXxxB: "x1y1nw7a",
+    kqUdNP: "xa5v58t",
+    kHypHr: "xx83zyx",
+    kVQacm: "x1rea2x4",
+    $$css: true
+  },
+  headerCell: {
+    kY2c9j: "xzkaem6",
+    $$css: true
+  },
+  bodyCell: {
+    kY2c9j: "x1vjfegm",
+    $$css: true
+  }
+};
+
+// Soft drop shadow over the scrolling region (matches the EPS sticky treatment).
+// border-collapse tables don't paint box-shadow on cells in Chromium, so it's a
+// ::after gradient strip just past the pinned edge (visible thanks to the cell's
+// overflow: visible). Opacity is gated by the scroll-state variable above.
+const SHADOW_WIDTH = '6px';
+// --color-shadow is only ~10% alpha (too faint here); use a slightly stronger soft tint.
+const SHADOW_TINT = 'light-dark(rgba(0, 0, 0, 0.12), rgba(0, 0, 0, 0.32))';
+const shadowStyles = {
+  start: {
+    k5JduY: "x1s928wv",
+    kwXMNM: "x1j6awrg",
+    k3foIR: "x1m1drc7",
+    k8Iv0R: "x1xrz1ek",
+    kH8aOt: "x1unh1gc",
+    kkgrvl: "xzkji8o",
+    kLigFv: "x1qyefdi",
+    kloYau: "x2q1x1w",
+    kFJxch: "x17s1k9h",
+    kypkao: "x1sggmfs",
+    kNctxI: "x156sm4c",
+    $$css: true
+  },
+  end: {
+    k5JduY: "x1s928wv",
+    kwXMNM: "x1j6awrg",
+    k3foIR: "x1m1drc7",
+    k8Iv0R: "x1xrz1ek",
+    kc1e00: "x1iygr5g",
+    kkgrvl: "xzkji8o",
+    kLigFv: "xvs0bi2",
+    kloYau: "x2q1x1w",
+    kFJxch: "x17s1k9h",
+    kypkao: "x1c2idit",
+    kNctxI: "x14ofgck",
+    $$css: true
+  }
+};
+
+// Stable empty default so an unset start/end doesn't allocate a fresh array
+// (and bust the memo) on every render.
+const EMPTY = [];
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useTableStickyColumns(config) {
+  const {
+    startKeys,
+    endKeys
+  } = config;
+  const start = startKeys ?? EMPTY;
+  const end = endKeys ?? EMPTY;
+  const hasStart = start.length > 0;
+  const hasEnd = end.length > 0;
+
+  // Live snapshot of the resolved config, read inside the (memoized) transforms
+  // and the scroll-shadow callback. Keeping these in a ref lets the plugin memo
+  // be computed once (deps: only the stable scroll-shadow callback) while never
+  // reading stale config — consumers typically pass fresh array literals each
+  // render, so we never want array identity in the deps.
+  const stateRef = useRef({
+    start,
+    end,
+    hasStart,
+    hasEnd
+  });
+  stateRef.current = {
+    start,
+    end,
+    hasStart,
+    hasEnd
+  };
+
+  // Scroll-aware shadows: toggle CSS variables on the scroll container so each
+  // edge's shadow only paints when there is hidden, horizontally-scrolled
+  // content behind that edge. Implemented with a callback ref + scroll/resize
+  // listeners (synchronizing with the DOM) rather than React state, so
+  // scrolling never triggers re-renders.
+  const detachRef = useRef(null);
+  const attachScrollShadow = useCallback(el => {
+    detachRef.current?.();
+    detachRef.current = null;
+    if (!el) {
+      return;
+    }
+    const update = () => {
+      const {
+        hasStart: hs,
+        hasEnd: he
+      } = stateRef.current;
+      const maxScroll = el.scrollWidth - el.clientWidth;
+      const hasOverflow = maxScroll > 1;
+      if (hs) {
+        el.style.setProperty(SHADOW_VAR_START, hasOverflow && el.scrollLeft > 1 ? '1' : '0');
+      }
+      if (he) {
+        el.style.setProperty(SHADOW_VAR_END, hasOverflow && el.scrollLeft < maxScroll - 1 ? '1' : '0');
+      }
+    };
+    el.addEventListener('scroll', update, {
+      passive: true
+    });
+    const resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(update) : null;
+    resizeObserver?.observe(el);
+    update();
+    detachRef.current = () => {
+      el.removeEventListener('scroll', update);
+      resizeObserver?.disconnect();
+    };
+  }, []);
+  return useMemo(() => ({
+    transformHeaderCell(props, column) {
+      const {
+        start: s,
+        end: e
+      } = stateRef.current;
+      const side = resolveStickySide(props.columns, column.key, s, e);
+      if (!side) {
+        return props;
+      }
+      // position/inline-offset are runtime values → set via inline style so
+      // they are authoritative regardless of plugin composition order (the
+      // resize plugin also writes inline style on header cells).
+      const offsetStyle = side.edge === 'start' ? {
+        insetInlineStart: `${side.offset}px`
+      } : {
+        insetInlineEnd: `${side.offset}px`
+      };
+      return {
+        ...props,
+        htmlProps: {
+          ...props.htmlProps,
+          style: {
+            ...props.htmlProps.style,
+            ...offsetStyle
+          }
+        },
+        styles: [...props.styles, stickyStyles.cell, stickyStyles.headerCell, side.edge === 'start' ? shadowStyles.start : shadowStyles.end]
+      };
+    },
+    transformBodyCell(props, column) {
+      const {
+        start: s,
+        end: e
+      } = stateRef.current;
+      const side = resolveStickySide(props.columns, column.key, s, e);
+      if (!side) {
+        return props;
+      }
+      const offsetStyle = side.edge === 'start' ? {
+        insetInlineStart: `${side.offset}px`
+      } : {
+        insetInlineEnd: `${side.offset}px`
+      };
+      return {
+        ...props,
+        htmlProps: {
+          ...props.htmlProps,
+          style: {
+            ...props.htmlProps.style,
+            ...offsetStyle
+          }
+        },
+        styles: [...props.styles, stickyStyles.cell, stickyStyles.bodyCell, side.edge === 'start' ? shadowStyles.start : shadowStyles.end]
+      };
+    },
+    transformScrollWrapper(props) {
+      // No pinned edges → nothing to gate; leave the wrapper untouched.
+      if (!stateRef.current.hasStart && !stateRef.current.hasEnd) {
+        return props;
+      }
+      // Compose with any ref a prior plugin (e.g. virtualization) set on the
+      // scroll container.
+      const existingRef = props.htmlProps.ref;
+      const mergedRef = node => {
+        attachScrollShadow(node);
+        if (typeof existingRef === 'function') {
+          existingRef(node);
+        } else if (existingRef != null) {
+          // RefObject — assign through its writable `.current`.
+          existingRef.current = node;
+        }
+      };
+      return {
+        ...props,
+        htmlProps: {
+          ...props.htmlProps,
+          ref: mergedRef
+        }
+      };
+    }
+  }),
+  // The returned plugin's transforms read live config from `stateRef` and
+  // `attachScrollShadow` is stable (empty deps), so the plugin object can be
+  // computed once and reused across renders.
+  [attachScrollShadow]);
+}

package/dist/Table/tableContextMenu.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file tableContextMenu.tsx
+ * @input React, ContextMenu, Icon, types
+ * @output wrapInTableContextMenu helper
+ * @position Renders the aggregated `contextMenuActions` for a header cell / row
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/BaseTable.tsx (call sites)
+ * - /packages/core/src/Table/types.ts (TableContextAction)
+ */
+import { type ReactNode } from 'react';
+import type { TableContextAction, TableContextActions } from './types';
+/**
+ * Resolve a `contextMenuActions` value (array or getter) to a plain array.
+ * Use this when composing actions from a prior plugin's render props so you
+ * don't have to branch on the array-vs-getter form:
+ *
+ * ```
+ * contextMenuActions: () => [
+ *   ...resolveContextActions(props.contextMenuActions),
+ *   ...myActions,
+ * ]
+ * ```
+ */
+export declare function resolveContextActions(actions: TableContextActions | undefined): TableContextAction[];
+/**
+ * Wrap a table element (a header cell's content or a body cell) in a right-click
+ * context menu rendering the aggregated `actions`. Accepts a static array or a
+ * getter (resolved lazily on open). When there are no actions the element is
+ * returned untouched so the native browser menu passes through.
+ */
+export declare function wrapInTableContextMenu(element: ReactNode, actions: TableContextActions | undefined): ReactNode;
+//# sourceMappingURL=tableContextMenu.d.ts.map

package/dist/Table/tableContextMenu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableContextMenu.d.ts","sourceRoot":"","sources":["../../src/Table/tableContextMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,EAAW,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG/C,OAAO,KAAK,EAAC,kBAAkB,EAAE,mBAAmB,EAAC,MAAM,SAAS,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GACvC,kBAAkB,EAAE,CAKtB;AAiFD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,mBAAmB,GAAG,SAAS,GACvC,SAAS,CAgBX"}

package/dist/Table/tableContextMenu.js

@@ -0,0 +1,136 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file tableContextMenu.tsx
+ * @input React, ContextMenu, Icon, types
+ * @output wrapInTableContextMenu helper
+ * @position Renders the aggregated `contextMenuActions` for a header cell / row
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/BaseTable.tsx (call sites)
+ * - /packages/core/src/Table/types.ts (TableContextAction)
+ */
+import { useState } from 'react';
+import { ContextMenu } from "../ContextMenu/index.js";
+import { Icon } from "../Icon/index.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Resolve a `contextMenuActions` value (array or getter) to a plain array.
+ * Use this when composing actions from a prior plugin's render props so you
+ * don't have to branch on the array-vs-getter form:
+ *
+ * ```
+ * contextMenuActions: () => [
+ *   ...resolveContextActions(props.contextMenuActions),
+ *   ...myActions,
+ * ]
+ * ```
+ */
+export function resolveContextActions(actions) {
+  if (typeof actions === 'function') {
+    return actions();
+  }
+  return actions ?? [];
+}
+
+/**
+ * Convert the flat action list into ContextMenu options, inserting a divider
+ * between groups (first-seen group order). Ungrouped actions form a trailing
+ * group. A `checked` action shows a trailing check icon.
+ */
+function toContextMenuOptions(actions) {
+  const order = [];
+  const buckets = new Map();
+  for (const action of actions) {
+    const key = action.group ?? '__ungrouped__';
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = [];
+      buckets.set(key, bucket);
+      order.push(key);
+    }
+    bucket.push(action);
+  }
+  const options = [];
+  order.forEach((key, groupIndex) => {
+    if (groupIndex > 0) {
+      options.push({
+        type: 'divider'
+      });
+    }
+    for (const action of buckets.get(key) ?? []) {
+      options.push({
+        label: typeof action.label === 'string' ? action.label : action.id,
+        // A checked action (e.g. the active sort direction) shows a checkmark;
+        // otherwise the action's own icon. ContextMenu's data form takes a
+        // single leading icon, so checked state replaces the icon.
+        icon: action.checked ? /*#__PURE__*/_jsx(Icon, {
+          icon: "check",
+          size: "xsm",
+          "aria-hidden": true
+        }) : action.icon,
+        isDisabled: action.disabled,
+        onClick: action.onSelect
+      });
+    }
+  });
+  return options;
+}
+
+/**
+ * Wrap a table element (a header cell's content or a row) in a right-click
+ * context menu rendering the aggregated `actions`. When no plugin contributes
+ * actions the element is returned untouched so the native browser menu passes
+ * through.
+ */
+/**
+ * A context menu whose actions are resolved lazily — only when the user opens
+ * the menu (right-click). Deferring the work means plugins that pass a getter
+ * don't build an action array (with its closures) for every cell on every
+ * render; it's computed on demand and memoized until the menu closes.
+ */
+function LazyTableContextMenu({
+  element,
+  getActions
+}) {
+  const [options, setOptions] = useState(null);
+  return /*#__PURE__*/_jsx(ContextMenu, {
+    items: options ?? [],
+    hasAutoFocus: false,
+    onOpenChange: open => {
+      // Resolve actions when opening; clear on close so state derived later
+      // (e.g. current sort direction) is always fresh next open.
+      setOptions(open ? toContextMenuOptions(getActions()) : null);
+    },
+    children: element
+  });
+}
+
+/**
+ * Wrap a table element (a header cell's content or a body cell) in a right-click
+ * context menu rendering the aggregated `actions`. Accepts a static array or a
+ * getter (resolved lazily on open). When there are no actions the element is
+ * returned untouched so the native browser menu passes through.
+ */
+export function wrapInTableContextMenu(element, actions) {
+  // Getter form → resolve lazily on open.
+  if (typeof actions === 'function') {
+    return /*#__PURE__*/_jsx(LazyTableContextMenu, {
+      element: element,
+      getActions: actions
+    });
+  }
+  if (!actions || actions.length === 0) {
+    return element;
+  }
+  // hasAutoFocus={false}: a right-click menu shouldn't pre-highlight the first
+  // item (it looked like "ascending" was always selected). Focus moves only
+  // when the user arrow-keys into the menu.
+  return /*#__PURE__*/_jsx(ContextMenu, {
+    items: toContextMenuOptions(actions),
+    hasAutoFocus: false,
+    children: element
+  });
+}