@cube-dev/ui-kit 0.156.0 → 0.157.1

package/dist/components/data/TableBase/types.d.ts

@@ -0,0 +1,160 @@
+
+import "../../content/Item/index.js";
+import { CubeItemProps } from "../../content/Item/Item.js";
+import { Styles } from "@tenphi/tasty";
+import { ReactNode } from "react";
+import { Key as Key$1 } from "@react-types/shared";
+
+//#region src/components/data/TableBase/types.d.ts
+type CubeTableSortDirection = 'asc' | 'desc';
+type CubeTableAlign = 'start' | 'center' | 'end';
+type CubeTableRowSection = 'body' | 'pinnedTop' | 'pinnedBottom';
+interface CubeTableCellRange {
+  fromRowKey: Key$1;
+  toRowKey: Key$1;
+  fromColumnKey: string;
+  toColumnKey: string;
+}
+interface CubeTableSort {
+  /** `key` of the sorted column. */
+  columnKey: string;
+  direction: CubeTableSortDirection;
+}
+interface CubeTableCellContext<T = any> {
+  row: T;
+  rowKey: Key$1;
+  rowIndex: number;
+  columnKey: string;
+  columnIndex: number;
+  section: CubeTableRowSection;
+  /** Whether the ROW is selected, matching `isRowFocused` below. */
+  isSelected: boolean;
+  /**
+   * Not yet wired — always absent.
+   *
+   * Optional rather than `boolean`, because there is nowhere honest to compute
+   * them from where this context is built. Focus lives in the DOM, and drop
+   * state comes out of `useDropIndicator`, a hook that can only run inside the
+   * row component — so populating either means moving the `render` / `cellStyles`
+   * call sites into `TableRow`. Declaring them required and passing `false`
+   * would just be a documented lie.
+   */
+  isRowFocused?: boolean;
+  isDropTarget?: boolean;
+}
+interface CubeTableRowContext<T = any> {
+  row: T;
+  rowKey: Key$1;
+  rowIndex: number;
+  section: CubeTableRowSection;
+  isSelected: boolean;
+  /** Not yet wired — always absent. See `CubeTableCellContext` for why. */
+  isFocused?: boolean;
+  isDropTarget?: boolean;
+}
+interface CubeTableHeaderContext {
+  columnKey: string;
+  columnIndex: number;
+  sort: CubeTableSortDirection | null;
+  isSortable: boolean;
+  isResizing: boolean;
+  width: number | null;
+}
+/**
+ * Rich header content. Every slot maps 1:1 onto the `Item` rendered inside the
+ * header `<th>`, so a header gets icon / description / tooltip / suffix /
+ * actions for free.
+ */
+interface CubeTableColumnHeader {
+  icon?: CubeItemProps['icon'];
+  rightIcon?: CubeItemProps['rightIcon'];
+  prefix?: ReactNode;
+  suffix?: ReactNode;
+  description?: ReactNode;
+  descriptionPlacement?: CubeItemProps['descriptionPlacement'];
+  /** `true` = auto tooltip when the label is truncated. */
+  tooltip?: CubeItemProps['tooltip'];
+  actions?: ReactNode;
+  /** Hide `actions` until hover/focus. @default true */
+  autoHideActions?: boolean;
+  theme?: CubeItemProps['theme'];
+  /** Full takeover of the header cell's content. Overrides `title` and every slot. */
+  render?: (ctx: CubeTableHeaderContext) => ReactNode;
+  /** Overrides `column.align` for the header only. */
+  align?: CubeTableAlign;
+  styles?: Styles;
+}
+interface CubeTableColumn<T = any> {
+  /**
+   * Column id. Also the default data path — dot notation is supported
+   * (`'owner.name'`). Anything beyond a path needs `getValue`.
+   */
+  key: string;
+  /** Header label. Shorthand for `header` with no extra slots. */
+  title?: ReactNode;
+  header?: CubeTableColumnHeader;
+  /**
+   * Renders `<th scope="row">` instead of `<td>`, names the row for screen
+   * readers, and hosts the `rowLink` anchor. Defaults to the first
+   * non-structural column when a row link is present.
+   */
+  isRowHeader?: boolean;
+  /** Fixed width in px. Mutually exclusive with `flex`. */
+  width?: number;
+  /** Weight for the leftover space. @default 1 when `width` is unset */
+  flex?: number;
+  /** @default 150 */
+  minWidth?: number;
+  maxWidth?: number;
+  /** Inherits the table's `isResizable`. */
+  isResizable?: boolean;
+  /** Stick to the start/end edge during horizontal scroll. */
+  pin?: 'start' | 'end';
+  /** Hide without losing width or order state. */
+  isHidden?: boolean;
+  /** @default (row) => get(row, key) */
+  getValue?: (row: T, rowIndex: number) => unknown;
+  /** Raw value → display text. Feeds client sort, client search and TSV copy. */
+  format?: (value: any, row: T, rowIndex: number) => string;
+  /** Client-side comparator over raw `getValue` results. */
+  compare?: (a: any, b: any, rowA: T, rowB: T) => number;
+  /** A returned string is wrapped in a truncating `TextItem`. */
+  render?: (value: any, row: T, rowIndex: number, ctx: CubeTableCellContext<T>) => ReactNode;
+  cellStyles?: Styles | ((ctx: CubeTableCellContext<T>) => Styles | undefined);
+  cellProps?: (ctx: CubeTableCellContext<T>) => Record<string, any> | undefined;
+  align?: CubeTableAlign;
+  /** @default true unless the table's `sortMode` is `'off'` */
+  isSortable?: boolean;
+  /** Two-state cycling (asc ↔ desc), never back to unsorted. @default false */
+  disallowSortRemoval?: boolean;
+  /** Include in the built-in client search. @default true */
+  isSearchable?: boolean;
+  /** Include in TSV copy. @default true */
+  isCopyable?: boolean;
+  /** Wrap text and let the row grow to fit. */
+  autoHeight?: boolean;
+  /** Consumer-owned bag. Never reaches the DOM. */
+  meta?: Record<string, unknown>;
+}
+/**
+ * How a refresh over an existing result is presented.
+ *
+ * - `overlay` — keep the previous rows visible, dimmed, behind a spinner. A
+ *   server page or a re-sort never blanks the table.
+ * - `skeleton` — discard the previous rows and show placeholders.
+ * - `none` — no visuals beyond `aria-busy`; the page owns the indicator.
+ */
+type CubeTableLoadingIndicator = 'overlay' | 'skeleton' | 'none';
+type CubeTableSelectionMode = 'none' | 'single' | 'multiple';
+/**
+ * What the header checkbox acts on.
+ *
+ * - `page` — the rows on the current page.
+ * - `filtered` — every row passing the current search/filter, across pages.
+ * - `all` — emits the `'all'` sentinel, meaning "everything, including rows the
+ *   client has not loaded". The consumer decides what that means for its query.
+ */
+type CubeTableSelectAllMode = 'page' | 'filtered' | 'all';
+//#endregion
+export { CubeTableAlign, CubeTableCellContext, CubeTableCellRange, CubeTableColumn, CubeTableColumnHeader, CubeTableHeaderContext, CubeTableLoadingIndicator, CubeTableRowContext, CubeTableRowSection, CubeTableSelectAllMode, CubeTableSelectionMode, CubeTableSort, CubeTableSortDirection };
+//# sourceMappingURL=types.d.ts.map

package/dist/components/data/TableBase/types.js

@@ -0,0 +1,31 @@
+/** @license MIT | @cube-dev/ui-kit v0.157.1 | Cube Dev Team */
+//#region src/components/data/TableBase/types.ts
+/**
+* `asc | desc` rather than React Aria's `ascending | descending`: we do not use
+* `useTableState`, so there is no `SortDescriptor` interop to preserve, and
+* every consumer and server query parameter already speaks `asc|desc`.
+* `aria-sort` is a one-line map in the header cell.
+*/
+/**
+* A rectangular block of cells, stored as two opposite corners.
+*
+* Corners rather than a set of keys so the selection survives a re-sort or a
+* page change the way a keyed row selection does: "the block between these two
+* cells" is re-resolved against the current order every render.
+*/
+/**
+* The key a cell range identifies a row by.
+*
+* Not the consumer's row key: a pinned total is commonly the SAME record at the
+* top and the bottom (`id: 'total'`), and one flat key space collapsed the two
+* into whichever `indexOf` found first — so a range aimed at the footer total
+* resolved against the header one. The section is part of the identity here,
+* and only here; `ctx.rowKey` stays the consumer's own.
+*/
+function selectionRowKey(section, rowKey) {
+	return section === "body" ? rowKey : `${section}:${rowKey}`;
+}
+
+//#endregion
+export { selectionRowKey };
+//# sourceMappingURL=types.js.map

package/dist/components/data/TableBase/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../../../src/components/data/TableBase/types.ts"],"sourcesContent":["import type { Key } from '@react-types/shared';\nimport type { Styles } from '@tenphi/tasty';\nimport type { ReactNode } from 'react';\nimport type { CubeItemProps } from '../../content/Item';\n\nexport type CubeTableSortDirection = 'asc' | 'desc';\nexport type CubeTableAlign = 'start' | 'center' | 'end';\nexport type CubeTableRowSection = 'body' | 'pinnedTop' | 'pinnedBottom';\n\n/**\n * `asc | desc` rather than React Aria's `ascending | descending`: we do not use\n * `useTableState`, so there is no `SortDescriptor` interop to preserve, and\n * every consumer and server query parameter already speaks `asc|desc`.\n * `aria-sort` is a one-line map in the header cell.\n */\n/**\n * A rectangular block of cells, stored as two opposite corners.\n *\n * Corners rather than a set of keys so the selection survives a re-sort or a\n * page change the way a keyed row selection does: \"the block between these two\n * cells\" is re-resolved against the current order every render.\n */\n/**\n * The key a cell range identifies a row by.\n *\n * Not the consumer's row key: a pinned total is commonly the SAME record at the\n * top and the bottom (`id: 'total'`), and one flat key space collapsed the two\n * into whichever `indexOf` found first — so a range aimed at the footer total\n * resolved against the header one. The section is part of the identity here,\n * and only here; `ctx.rowKey` stays the consumer's own.\n */\nexport function selectionRowKey(\n  section: CubeTableRowSection,\n  rowKey: Key,\n): Key {\n  return section === 'body' ? rowKey : `${section}:${rowKey}`;\n}\n\nexport interface CubeTableCellRange {\n  fromRowKey: Key;\n  toRowKey: Key;\n  fromColumnKey: string;\n  toColumnKey: string;\n}\n\nexport interface CubeTableSort {\n  /** `key` of the sorted column. */\n  columnKey: string;\n  direction: CubeTableSortDirection;\n}\n\n/* ── render contexts ─────────────────────────────────────────────────────── */\n\nexport interface CubeTableCellContext<T = any> {\n  row: T;\n  rowKey: Key;\n  rowIndex: number;\n  columnKey: string;\n  columnIndex: number;\n  section: CubeTableRowSection;\n  /** Whether the ROW is selected, matching `isRowFocused` below. */\n  isSelected: boolean;\n  /**\n   * Not yet wired — always absent.\n   *\n   * Optional rather than `boolean`, because there is nowhere honest to compute\n   * them from where this context is built. Focus lives in the DOM, and drop\n   * state comes out of `useDropIndicator`, a hook that can only run inside the\n   * row component — so populating either means moving the `render` / `cellStyles`\n   * call sites into `TableRow`. Declaring them required and passing `false`\n   * would just be a documented lie.\n   */\n  isRowFocused?: boolean;\n  isDropTarget?: boolean;\n}\n\nexport interface CubeTableRowContext<T = any> {\n  row: T;\n  rowKey: Key;\n  rowIndex: number;\n  section: CubeTableRowSection;\n  isSelected: boolean;\n  /** Not yet wired — always absent. See `CubeTableCellContext` for why. */\n  isFocused?: boolean;\n  isDropTarget?: boolean;\n}\n\nexport interface CubeTableHeaderContext {\n  columnKey: string;\n  columnIndex: number;\n  sort: CubeTableSortDirection | null;\n  isSortable: boolean;\n  isResizing: boolean;\n  width: number | null;\n}\n\n/* ── column ──────────────────────────────────────────────────────────────── */\n\n/**\n * Rich header content. Every slot maps 1:1 onto the `Item` rendered inside the\n * header `<th>`, so a header gets icon / description / tooltip / suffix /\n * actions for free.\n */\nexport interface CubeTableColumnHeader {\n  icon?: CubeItemProps['icon'];\n  rightIcon?: CubeItemProps['rightIcon'];\n  prefix?: ReactNode;\n  suffix?: ReactNode;\n  description?: ReactNode;\n  descriptionPlacement?: CubeItemProps['descriptionPlacement'];\n  /** `true` = auto tooltip when the label is truncated. */\n  tooltip?: CubeItemProps['tooltip'];\n  actions?: ReactNode;\n  /** Hide `actions` until hover/focus. @default true */\n  autoHideActions?: boolean;\n  theme?: CubeItemProps['theme'];\n  /** Full takeover of the header cell's content. Overrides `title` and every slot. */\n  render?: (ctx: CubeTableHeaderContext) => ReactNode;\n  /** Overrides `column.align` for the header only. */\n  align?: CubeTableAlign;\n  styles?: Styles;\n}\n\nexport interface CubeTableColumn<T = any> {\n  /**\n   * Column id. Also the default data path — dot notation is supported\n   * (`'owner.name'`). Anything beyond a path needs `getValue`.\n   */\n  key: string;\n  /** Header label. Shorthand for `header` with no extra slots. */\n  title?: ReactNode;\n  header?: CubeTableColumnHeader;\n  /**\n   * Renders `<th scope=\"row\">` instead of `<td>`, names the row for screen\n   * readers, and hosts the `rowLink` anchor. Defaults to the first\n   * non-structural column when a row link is present.\n   */\n  isRowHeader?: boolean;\n\n  /* sizing */\n  /** Fixed width in px. Mutually exclusive with `flex`. */\n  width?: number;\n  /** Weight for the leftover space. @default 1 when `width` is unset */\n  flex?: number;\n  /** @default 150 */\n  minWidth?: number;\n  maxWidth?: number;\n  /** Inherits the table's `isResizable`. */\n  isResizable?: boolean;\n  /** Stick to the start/end edge during horizontal scroll. */\n  pin?: 'start' | 'end';\n  /** Hide without losing width or order state. */\n  isHidden?: boolean;\n\n  /* value pipeline */\n  /** @default (row) => get(row, key) */\n  getValue?: (row: T, rowIndex: number) => unknown;\n  /** Raw value → display text. Feeds client sort, client search and TSV copy. */\n  format?: (value: any, row: T, rowIndex: number) => string;\n  /** Client-side comparator over raw `getValue` results. */\n  compare?: (a: any, b: any, rowA: T, rowB: T) => number;\n\n  /* rendering */\n  /** A returned string is wrapped in a truncating `TextItem`. */\n  render?: (\n    value: any,\n    row: T,\n    rowIndex: number,\n    ctx: CubeTableCellContext<T>,\n  ) => ReactNode;\n  cellStyles?: Styles | ((ctx: CubeTableCellContext<T>) => Styles | undefined);\n  cellProps?: (ctx: CubeTableCellContext<T>) => Record<string, any> | undefined;\n\n  /* behaviour */\n  align?: CubeTableAlign;\n  /** @default true unless the table's `sortMode` is `'off'` */\n  isSortable?: boolean;\n  /** Two-state cycling (asc ↔ desc), never back to unsorted. @default false */\n  disallowSortRemoval?: boolean;\n  /** Include in the built-in client search. @default true */\n  isSearchable?: boolean;\n  /** Include in TSV copy. @default true */\n  isCopyable?: boolean;\n  /** Wrap text and let the row grow to fit. */\n  autoHeight?: boolean;\n\n  /** Consumer-owned bag. Never reaches the DOM. */\n  meta?: Record<string, unknown>;\n}\n\n/* ── resolved layout (internal, but exported for adapters) ───────────────── */\n\nexport interface CubeResolvedColumn<T = any>\n  // `width`, `minWidth`, `maxWidth`, `flex` and `align` are all resolved here,\n  // so they narrow from optional to definite and must be replaced, not extended.\n  extends Omit<\n    CubeTableColumn<T>,\n    'width' | 'minWidth' | 'maxWidth' | 'flex' | 'align'\n  > {\n  /** Position among the visible leaf columns, 0-based. */\n  index: number;\n  /** `aria-colindex`, 1-based and document-absolute. */\n  ariaColIndex: number;\n  /** Resolved pixel width, or `null` while the container is unmeasured. */\n  width: number | null;\n  minWidth: number;\n  maxWidth: number | null;\n  flex: number | null;\n  align: CubeTableAlign;\n  /** Cumulative sticky offset in px for a pinned column. */\n  pinOffset: number | null;\n  /** `true` for the last pinned-start / first pinned-end column. */\n  isPinEdge: boolean;\n  /** Structural columns (selection, drag handle, row menu) never enter sorting,\n   *  search, copy, or the value pipeline. */\n  isStructural: boolean;\n}\n\nexport interface CubeTableColumnLayout<T = any> {\n  columns: CubeResolvedColumn<T>[];\n  pinnedStartWidth: number;\n  pinnedEndWidth: number;\n  /** Sum of resolved widths, or `null` while unmeasured. */\n  totalWidth: number | null;\n  /** `true` when the columns cannot fit and the table scrolls horizontally. */\n  isOverflowing: boolean;\n}\n\n/**\n * How a refresh over an existing result is presented.\n *\n * - `overlay` — keep the previous rows visible, dimmed, behind a spinner. A\n *   server page or a re-sort never blanks the table.\n * - `skeleton` — discard the previous rows and show placeholders.\n * - `none` — no visuals beyond `aria-busy`; the page owns the indicator.\n */\nexport type CubeTableLoadingIndicator = 'overlay' | 'skeleton' | 'none';\n\nexport type CubeTableSelectionMode = 'none' | 'single' | 'multiple';\n\n/**\n * What the header checkbox acts on.\n *\n * - `page` — the rows on the current page.\n * - `filtered` — every row passing the current search/filter, across pages.\n * - `all` — emits the `'all'` sentinel, meaning \"everything, including rows the\n *   client has not loaded\". The consumer decides what that means for its query.\n */\nexport type CubeTableSelectAllMode = 'page' | 'filtered' | 'all';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,gBACd,SACA,QACK;AACL,QAAO,YAAY,SAAS,SAAS,GAAG,QAAQ,GAAG"}

package/dist/components/data/TableBase/use-cell-selection.d.ts

@@ -0,0 +1,3 @@
+
+import "./types.js";
+import { Key as Key$1 } from "@react-types/shared";

package/dist/components/data/TableBase/use-cell-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cell-selection.js","names":[],"sources":["../../../../src/components/data/TableBase/use-cell-selection.ts"],"sourcesContent":["import { useControlledState } from '@react-stately/utils';\nimport { useCallback, useMemo, useRef } from 'react';\n\nimport { useEvent } from '../../../_internal/hooks';\n\nimport type { Key } from '@react-types/shared';\nimport type { CubeResolvedColumn, CubeTableCellRange } from './types';\n\nexport type CubeTableCellSelectionMode = 'none' | 'cell' | 'range';\n\nexport interface UseCellSelectionOptions<T> {\n  /** @default 'range' */\n  mode?: CubeTableCellSelectionMode;\n  columns: CubeResolvedColumn<T>[];\n  /**\n   * Every row a range can reach, in the order they appear on screen — pinned\n   * rows included. ag-grid excludes them (`!rowNode.rowPinned`), and we do not:\n   * a total is a figure like any other, and selecting a column of revenue only\n   * to have to copy its sum separately is the wrong trade.\n   *\n   * A pinned row is still not reachable by dragging THROUGH it — see\n   * `TableView`'s pointer handlers for why.\n   */\n  rows: readonly T[];\n  /**\n   * Parallel to `rows`. Supplied rather than derived, so it cannot disagree with\n   * the keys the renderer stamps on the cells — when the two drifted, every\n   * range silently resolved to nothing.\n   */\n  rowKeys: readonly Key[];\n  /**\n   * Vetoes individual cells. A pinned total's label cell is the motivating\n   * case: \"Total\" is a caption for the row, not a figure, and there is nothing\n   * useful to do with it selected.\n   *\n   * A vetoed cell cannot anchor or receive a range, never highlights, and copies\n   * as an empty field so a block spanning it keeps its shape.\n   */\n  isCellSelectable?: (row: T, rowKey: Key, columnKey: string) => boolean;\n  range?: CubeTableCellRange | null;\n  defaultRange?: CubeTableCellRange | null;\n  onRangeChange?: (range: CubeTableCellRange | null) => void;\n}\n\nconst cellKey = (rowKey: Key, columnKey: string) => `${rowKey}\u0000${columnKey}`;\n\n/**\n * Rectangular cell selection.\n *\n * A result grid is read by cell, not by row: the thing a user wants out of it is\n * a figure, or a block of figures to paste somewhere else. So a click selects a\n * cell, shift-click and drag grow a rectangle, and ⌘/Ctrl+C writes the rectangle\n * out as TSV.\n *\n * The range is stored as two corners rather than a set of keys, so it survives\n * sorting and paging the way a keyed row selection does — and normalizing it\n * against the CURRENT row and column order is what makes \"the block between\n * these two cells\" keep meaning that after a re-sort.\n *\n * Structural columns (the row number, the checkbox, the row-menu button) can\n * never enter a range: they are chrome, and copying them would put the grid's\n * own furniture into the user's spreadsheet.\n */\nexport function useCellSelection<T>({\n  mode = 'range',\n  columns,\n  rows,\n  rowKeys,\n  isCellSelectable,\n  range: rangeProp,\n  defaultRange,\n  onRangeChange,\n}: UseCellSelectionOptions<T>) {\n  const [range, setRange] = useControlledState<CubeTableCellRange | null>(\n    rangeProp as CubeTableCellRange | null,\n    defaultRange ?? null,\n    onRangeChange as (value: CubeTableCellRange | null) => void,\n  );\n\n  // The press that started a drag. A ref rather than state: it is written and\n  // read inside one pointer gesture, and re-rendering on every `pointerenter`\n  // would drop frames across a wide grid.\n  const anchorRef = useRef<CubeTableCellRange | null>(null);\n  const isDraggingRef = useRef(false);\n\n  const selectableColumns = useMemo(\n    () => columns.filter((column) => !column.isStructural),\n    [columns],\n  );\n\n  const isEnabled = mode !== 'none';\n\n  /**\n   * The range's corners resolved against the current order, as index bounds.\n   * `null` when either corner has scrolled out of the data — a range whose\n   * anchor no longer exists is not a range.\n   */\n  const bounds = useMemo(() => {\n    if (!isEnabled || !range) return null;\n\n    const rowFrom = rowKeys.indexOf(range.fromRowKey);\n    const rowTo = rowKeys.indexOf(range.toRowKey);\n    const colFrom = selectableColumns.findIndex(\n      (column) => column.key === range.fromColumnKey,\n    );\n    const colTo = selectableColumns.findIndex(\n      (column) => column.key === range.toColumnKey,\n    );\n\n    if (rowFrom === -1 || rowTo === -1 || colFrom === -1 || colTo === -1) {\n      return null;\n    }\n\n    return {\n      rowStart: Math.min(rowFrom, rowTo),\n      rowEnd: Math.max(rowFrom, rowTo),\n      colStart: Math.min(colFrom, colTo),\n      colEnd: Math.max(colFrom, colTo),\n    };\n  }, [isEnabled, range, rowKeys, selectableColumns]);\n\n  /**\n   * Every selected cell, precomputed. A range spanning a full page is tens of\n   * thousands of cells and every one of them asks whether it is selected on\n   * every render, so this has to be a lookup rather than four comparisons.\n   */\n  const selectedKeys = useMemo(() => {\n    const keys = new Set<string>();\n\n    if (!bounds) return keys;\n\n    for (let r = bounds.rowStart; r <= bounds.rowEnd; r++) {\n      for (let c = bounds.colStart; c <= bounds.colEnd; c++) {\n        const columnKey = selectableColumns[c].key;\n\n        if (isCellSelectable?.(rows[r], rowKeys[r], columnKey) === false) {\n          continue;\n        }\n\n        keys.add(cellKey(rowKeys[r], columnKey));\n      }\n    }\n\n    return keys;\n  }, [bounds, rows, rowKeys, selectableColumns, isCellSelectable]);\n\n  // `useCallback`, not `useEvent`: the renderer asks this DURING render, once\n  // per cell. `useEvent` keeps its closure current through a layout effect, so a\n  // render-time reader sees the PREVIOUS render's answer — the highlight then\n  // trails the selection by one commit and a cleared range stays painted.\n  const isSelected = useCallback(\n    (rowKey: Key, columnKey: string) =>\n      selectedKeys.has(cellKey(rowKey, columnKey)),\n    [selectedKeys],\n  );\n\n  const isSelectableColumn = useEvent((columnKey: string) =>\n    selectableColumns.some((column) => column.key === columnKey),\n  );\n\n  /**\n   * Whether a cell can take part at all — asked by the renderer before it wires\n   * up any pointer handler, so a vetoed cell is inert rather than merely\n   * unpainted.\n   */\n  const canSelectCell = useEvent((rowKey: Key, columnKey: string) => {\n    if (!isEnabled || !isSelectableColumn(columnKey)) return false;\n    if (!isCellSelectable) return true;\n\n    const index = rowKeys.indexOf(rowKey);\n\n    return index === -1 || isCellSelectable(rows[index], rowKey, columnKey);\n  });\n\n  const select = useEvent((rowKey: Key, columnKey: string) => {\n    if (!canSelectCell(rowKey, columnKey)) return;\n\n    const next: CubeTableCellRange = {\n      fromRowKey: rowKey,\n      toRowKey: rowKey,\n      fromColumnKey: columnKey,\n      toColumnKey: columnKey,\n    };\n\n    anchorRef.current = next;\n    setRange(next);\n  });\n\n  /** Grow the range from the standing anchor. Shift-click and drag both land here. */\n  const extendTo = useEvent((rowKey: Key, columnKey: string) => {\n    if (mode !== 'range' || !canSelectCell(rowKey, columnKey)) return;\n\n    // Shift-clicking with nothing selected yet behaves as a plain click, which\n    // is what every grid and every file manager does.\n    const anchor = anchorRef.current ?? range;\n\n    if (!anchor) {\n      select(rowKey, columnKey);\n\n      return;\n    }\n\n    setRange({\n      fromRowKey: anchor.fromRowKey,\n      toRowKey: rowKey,\n      fromColumnKey: anchor.fromColumnKey,\n      toColumnKey: columnKey,\n    });\n  });\n\n  const clear = useEvent(() => {\n    anchorRef.current = null;\n    if (range) setRange(null);\n  });\n\n  /**\n   * The selection as a grid of display strings, unescaped.\n   *\n   * A matrix rather than a formatted blob, because the clipboard needs the same\n   * block in two formats and re-parsing one to build the other does not\n   * survive contact with the data: a value carrying a tab is RFC-4180 quoted\n   * for the TSV, and splitting that back apart on tabs tore the cell in half.\n   * Both formats are built from this instead.\n   *\n   * Values come from the same display-text pipeline client sort and search use,\n   * so what lands on the clipboard is what was on screen: a formatted currency\n   * stays formatted, and a value with no text representation copies as empty\n   * rather than as `[object Object]`.\n   */\n  const getSelectionMatrix = useEvent(\n    (\n      getText: (\n        column: CubeResolvedColumn<T>,\n        row: T,\n        rowIndex: number,\n      ) => string,\n      getHeader?: (column: CubeResolvedColumn<T>) => string,\n    ) => {\n      if (!bounds) return [];\n\n      const cols = selectableColumns.slice(bounds.colStart, bounds.colEnd + 1);\n      const matrix: string[][] = [];\n\n      if (getHeader) matrix.push(cols.map((column) => getHeader(column)));\n\n      for (let r = bounds.rowStart; r <= bounds.rowEnd; r++) {\n        matrix.push(\n          cols.map((column) =>\n            selectedKeys.has(cellKey(rowKeys[r], column.key))\n              ? getText(column, rows[r], r)\n              : '',\n          ),\n        );\n      }\n\n      return matrix;\n    },\n  );\n\n  return {\n    mode,\n    isEnabled,\n    range: bounds ? range : null,\n    /** Cells in the range, for `aria-selected` and the highlight. */\n    isSelected,\n    /** `true` once the range covers more than one cell. */\n    hasRange: selectedKeys.size > 1,\n    cellCount: selectedKeys.size,\n    canSelectCell,\n    select,\n    extendTo,\n    clear,\n    getSelectionMatrix,\n    anchorRef,\n    isDraggingRef,\n  };\n}\n\n/**\n * The matrix as tab-separated values — the format Excel and Sheets both paste\n * as a grid rather than as one run of text.\n *\n * RFC-4180 quoting: a value carrying a tab or a newline would otherwise break\n * the grid apart on paste, one cell becoming two or one row becoming two.\n */\nexport function toTsv(matrix: string[][]) {\n  return matrix.map((row) => row.map(quote).join('\\t')).join('\\n');\n}\n\nfunction quote(value: string) {\n  if (!/[\\t\\n\\r\"]/.test(value)) return value;\n\n  return `\"${value.replace(/\"/g, '\"\"')}\"`;\n}\n"],"mappings":"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"}

package/dist/components/data/TableBase/use-container-width.js

@@ -0,0 +1,35 @@
+/** @license MIT | @cube-dev/ui-kit v0.157.1 | Cube Dev Team */
+import { useLayoutEffect, useState } from "react";
+
+//#region src/components/data/TableBase/use-container-width.ts
+/**
+* Content-box width of the scroller, measured before paint and kept current
+* with a `ResizeObserver`.
+*
+* Takes the **element**, not a ref: in the virtualized path the scroller is
+* created by Virtuoso and handed over through a callback after mount, so a hook
+* that peeked at `ref.current` once would see `null` and never measure
+* anything — leaving every column unsized.
+*
+* `useLayoutEffect` rather than `useEffect` on purpose: column widths are
+* derived from this value, so measuring after paint would show one frame of
+* min-width columns before they snap to their real size.
+*/
+function useContainerWidth(element) {
+	const [width, setWidth] = useState(null);
+	useLayoutEffect(() => {
+		if (!element || !(element instanceof Element)) return;
+		const measure = () => {
+			setWidth((current) => current === element.clientWidth ? current : element.clientWidth);
+		};
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(element);
+		return () => observer.disconnect();
+	}, [element]);
+	return width;
+}
+
+//#endregion
+export { useContainerWidth };
+//# sourceMappingURL=use-container-width.js.map

package/dist/components/data/TableBase/use-container-width.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-container-width.js","names":[],"sources":["../../../../src/components/data/TableBase/use-container-width.ts"],"sourcesContent":["import { useLayoutEffect, useState } from 'react';\n\n/**\n * Content-box width of the scroller, measured before paint and kept current\n * with a `ResizeObserver`.\n *\n * Takes the **element**, not a ref: in the virtualized path the scroller is\n * created by Virtuoso and handed over through a callback after mount, so a hook\n * that peeked at `ref.current` once would see `null` and never measure\n * anything — leaving every column unsized.\n *\n * `useLayoutEffect` rather than `useEffect` on purpose: column widths are\n * derived from this value, so measuring after paint would show one frame of\n * min-width columns before they snap to their real size.\n */\nexport function useContainerWidth(element: HTMLElement | null): number | null {\n  const [width, setWidth] = useState<number | null>(null);\n\n  useLayoutEffect(() => {\n    // Virtuoso's `scrollerRef` reports `HTMLElement | Window | null`, and\n    // `ResizeObserver.observe` throws on anything that is not an Element.\n    if (!element || !(element instanceof Element)) return;\n\n    const measure = () => {\n      // `clientWidth` excludes the vertical scrollbar, which is what we want:\n      // the columns must fit the content box, not the border box, or a\n      // scrollbar appearing would push the last column out and bring a\n      // horizontal scrollbar with it.\n      setWidth((current) =>\n        current === element.clientWidth ? current : element.clientWidth,\n      );\n    };\n\n    measure();\n\n    const observer = new ResizeObserver(measure);\n\n    observer.observe(element);\n\n    return () => observer.disconnect();\n  }, [element]);\n\n  return width;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAeA,SAAgB,kBAAkB,SAA4C;CAC5E,MAAM,CAAC,OAAO,YAAY,SAAwB,KAAK;AAEvD,uBAAsB;AAGpB,MAAI,CAAC,WAAW,EAAE,mBAAmB,SAAU;EAE/C,MAAM,gBAAgB;AAKpB,aAAU,YACR,YAAY,QAAQ,cAAc,UAAU,QAAQ,YACrD;;AAGH,WAAS;EAET,MAAM,WAAW,IAAI,eAAe,QAAQ;AAE5C,WAAS,QAAQ,QAAQ;AAEzB,eAAa,SAAS,YAAY;IACjC,CAAC,QAAQ,CAAC;AAEb,QAAO"}

package/dist/components/data/TableBase/use-row-move-animation.js

@@ -0,0 +1,90 @@
+/** @license MIT | @cube-dev/ui-kit v0.157.1 | Cube Dev Team */
+import { useLayoutEffect, useRef } from "react";
+
+//#region src/components/data/TableBase/use-row-move-animation.ts
+/** Matches ag-grid's row animation closely enough to feel familiar. */
+const ROW_MOVE_DURATION = 120;
+/** Matches `DisplayTransition`'s check, which is the kit's existing precedent. */
+function prefersReducedMotion() {
+	return typeof window !== "undefined" && Boolean(window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches);
+}
+/**
+* Slides rows to their new positions when the order changes.
+*
+* FLIP: the previous commit's positions are the First, this commit's are the
+* Last, and each row is Inverted with a `translateY` back to where it was and
+* then Played to zero. The DOM is already correct the whole time — only the
+* paint is behind — so a test or a screen reader sees the new order
+* immediately, and nothing has to be delayed or double-rendered.
+*
+* Sorting a table otherwise teleports every row at once, and the eye has no way
+* to follow a particular one to where it went. The whole value is in tracking
+* one row, which is why this animates positions rather than cross-fading.
+*
+* **Only a reorder**, and only rows that were already on screen. If the rows
+* common to both commits are in the same relative order, nothing animates,
+* however much their positions moved — that is a relayout, not a reorder, and
+* it covers the initial mount (widths resolving, the virtualizer measuring, a
+* scrollbar appearing), a container resize, and a filter that only removes
+* rows.
+*
+* Scrolling is not movement either, and that falls out of measuring `offsetTop`
+* rather than viewport coordinates: it is relative to the scroller's content,
+* so it does not change as the content scrolls past.
+*/
+function useRowMoveAnimation({ isEnabled, bodyRef, duration = ROW_MOVE_DURATION }) {
+	const previousRef = useRef(null);
+	const previousOrderRef = useRef([]);
+	useLayoutEffect(() => {
+		const body = bodyRef.current;
+		if (!body) return;
+		const rows = Array.from(body.querySelectorAll("tr[data-element=\"Row\"][data-key]:not([data-pinned])"));
+		const next = /* @__PURE__ */ new Map();
+		for (const row of rows) next.set(row.dataset.key, row.offsetTop);
+		const previous = previousRef.current;
+		const previousOrder = previousOrderRef.current;
+		const nextOrder = rows.map((row) => row.dataset.key);
+		previousRef.current = next;
+		previousOrderRef.current = nextOrder;
+		if (!isEnabled || prefersReducedMotion() || !previous) return;
+		const stillHere = new Set(nextOrder);
+		const before = previousOrder.filter((key) => stillHere.has(key));
+		const after = nextOrder.filter((key) => previous.has(key));
+		if (!(before.length !== after.length || before.some((key, index) => key !== after[index]))) return;
+		const moved = [];
+		for (const row of rows) {
+			const from = previous.get(row.dataset.key);
+			if (from === void 0) continue;
+			const delta = from - next.get(row.dataset.key);
+			if (delta !== 0) moved.push({
+				row,
+				delta
+			});
+		}
+		if (!moved.length) return;
+		for (const { row, delta } of moved) {
+			row.style.transition = "none";
+			row.style.transform = `translateY(${delta}px)`;
+		}
+		body.offsetHeight;
+		for (const { row } of moved) {
+			row.style.transition = `transform ${duration}ms ease-out`;
+			row.style.transform = "";
+		}
+		const clear = () => {
+			for (const { row } of moved) {
+				row.style.transition = "";
+				row.style.transform = "";
+			}
+		};
+		const timer = setTimeout(clear, duration);
+		return () => {
+			clearTimeout(timer);
+			clear();
+		};
+	});
+}
+
+//#endregion
+export { useRowMoveAnimation };
+//# sourceMappingURL=use-row-move-animation.js.map

package/dist/components/data/TableBase/use-row-move-animation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-row-move-animation.js","names":[],"sources":["../../../../src/components/data/TableBase/use-row-move-animation.ts"],"sourcesContent":["import { useLayoutEffect, useRef } from 'react';\n\nimport type { RefObject } from 'react';\n\n/** Matches ag-grid's row animation closely enough to feel familiar. */\nexport const ROW_MOVE_DURATION = 120;\n\nexport interface UseRowMoveAnimationOptions {\n  isEnabled: boolean;\n  /** The `<tbody>` the rows live in. */\n  bodyRef: RefObject<HTMLTableSectionElement | null>;\n  /** @default 120 */\n  duration?: number;\n}\n\n/** Matches `DisplayTransition`'s check, which is the kit's existing precedent. */\nfunction prefersReducedMotion() {\n  return (\n    typeof window !== 'undefined' &&\n    Boolean(window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches)\n  );\n}\n\n/**\n * Slides rows to their new positions when the order changes.\n *\n * FLIP: the previous commit's positions are the First, this commit's are the\n * Last, and each row is Inverted with a `translateY` back to where it was and\n * then Played to zero. The DOM is already correct the whole time — only the\n * paint is behind — so a test or a screen reader sees the new order\n * immediately, and nothing has to be delayed or double-rendered.\n *\n * Sorting a table otherwise teleports every row at once, and the eye has no way\n * to follow a particular one to where it went. The whole value is in tracking\n * one row, which is why this animates positions rather than cross-fading.\n *\n * **Only a reorder**, and only rows that were already on screen. If the rows\n * common to both commits are in the same relative order, nothing animates,\n * however much their positions moved — that is a relayout, not a reorder, and\n * it covers the initial mount (widths resolving, the virtualizer measuring, a\n * scrollbar appearing), a container resize, and a filter that only removes\n * rows.\n *\n * Scrolling is not movement either, and that falls out of measuring `offsetTop`\n * rather than viewport coordinates: it is relative to the scroller's content,\n * so it does not change as the content scrolls past.\n */\nexport function useRowMoveAnimation({\n  isEnabled,\n  bodyRef,\n  duration = ROW_MOVE_DURATION,\n}: UseRowMoveAnimationOptions) {\n  const previousRef = useRef<Map<string, number> | null>(null);\n  const previousOrderRef = useRef<string[]>([]);\n\n  // No dependency array: the previous positions have to be captured after every\n  // commit, because any of them may turn out to be the one a reorder starts\n  // from.\n  useLayoutEffect(() => {\n    const body = bodyRef.current;\n\n    if (!body) return;\n\n    const rows = Array.from(\n      body.querySelectorAll<HTMLTableRowElement>(\n        // Pinned rows are excluded by the selector rather than filtered later:\n        // they do not take part in the order, so they never move.\n        'tr[data-element=\"Row\"][data-key]:not([data-pinned])',\n      ),\n    );\n\n    // `offsetTop`, not `getBoundingClientRect()`: it is relative to the\n    // scroller, so scrolling does not read as movement. Otherwise every scroll\n    // tick would look like a reorder of the whole page.\n    const next = new Map<string, number>();\n\n    for (const row of rows) next.set(row.dataset.key!, row.offsetTop);\n\n    const previous = previousRef.current;\n    const previousOrder = previousOrderRef.current;\n    const nextOrder = rows.map((row) => row.dataset.key!);\n\n    previousRef.current = next;\n    previousOrderRef.current = nextOrder;\n\n    // Checked per commit rather than once: the setting can change mid-session,\n    // and the position bookkeeping above must keep running either way so the\n    // animation is correct the moment it is turned back on.\n    if (!isEnabled || prefersReducedMotion() || !previous) return;\n\n    // Animate a REORDER, never a relayout.\n    //\n    // Positions shift for all sorts of reasons that are not a row moving: the\n    // column widths resolving after the first measure, the virtualizer taking\n    // its measurements, a scrollbar appearing, a font landing, the container\n    // being resized. Every one of those happens on the second commit of a\n    // normal mount — so keying off \"an offset changed\" animated the table into\n    // existence on load, which is exactly what a load should not do.\n    //\n    // Comparing the order of the rows common to both commits answers the real\n    // question. A relayout leaves it identical; a sort does not.\n    const stillHere = new Set(nextOrder);\n    const before = previousOrder.filter((key) => stillHere.has(key));\n    const after = nextOrder.filter((key) => previous.has(key));\n    const isReorder =\n      before.length !== after.length ||\n      before.some((key, index) => key !== after[index]);\n\n    if (!isReorder) return;\n\n    const moved: { row: HTMLTableRowElement; delta: number }[] = [];\n\n    for (const row of rows) {\n      const from = previous.get(row.dataset.key!);\n\n      // A row that was not here before has nowhere to come from. Skipped rather\n      // than bailing on the whole batch: a virtualized window swaps some of its\n      // rows on every re-sort, and refusing to animate unless ALL of them are\n      // familiar means a virtualized grid — most result grids — never animates\n      // at all.\n      if (from === undefined) continue;\n\n      const delta = from - next.get(row.dataset.key!)!;\n\n      if (delta !== 0) moved.push({ row, delta });\n    }\n\n    if (!moved.length) return;\n\n    // Invert: put every moved row back where it was, with transitions off so\n    // this jump is not itself animated.\n    for (const { row, delta } of moved) {\n      row.style.transition = 'none';\n      row.style.transform = `translateY(${delta}px)`;\n    }\n\n    // Flush the inverted state into layout, so the browser has something to\n    // animate FROM. A forced reflow rather than `requestAnimationFrame`,\n    // deliberately: rAF does not fire in a hidden tab, and a sort that lands\n    // while the tab is in the background would leave every row frozen at its\n    // old position until the next reorder. One reflow, once per animation.\n    void body.offsetHeight;\n\n    // Play.\n    for (const { row } of moved) {\n      row.style.transition = `transform ${duration}ms ease-out`;\n      row.style.transform = '';\n    }\n\n    // Clear on arrival. A `transition` left inline would go on to animate\n    // transforms this hook never set — a dragged row, for one.\n    //\n    // A timer rather than `transitionend`, for the same reason the invert does\n    // not use `requestAnimationFrame`: in a hidden tab the transition never\n    // runs, so the event never fires and every animated row keeps its inline\n    // `transition` for the rest of the session. The duration is known exactly,\n    // so there is nothing to wait to be told.\n    const clear = () => {\n      for (const { row } of moved) {\n        row.style.transition = '';\n        row.style.transform = '';\n      }\n    };\n    const timer = setTimeout(clear, duration);\n\n    return () => {\n      // A reorder landing mid-animation starts over from wherever the rows are,\n      // so nothing may be left behind.\n      clearTimeout(timer);\n      clear();\n    };\n  });\n}\n"],"mappings":";;;;;AAKA,MAAa,oBAAoB;;AAWjC,SAAS,uBAAuB;AAC9B,QACE,OAAO,WAAW,eAClB,QAAQ,OAAO,aAAa,mCAAmC,EAAE,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;AA4B7E,SAAgB,oBAAoB,EAClC,WACA,SACA,WAAW,qBACkB;CAC7B,MAAM,cAAc,OAAmC,KAAK;CAC5D,MAAM,mBAAmB,OAAiB,EAAE,CAAC;AAK7C,uBAAsB;EACpB,MAAM,OAAO,QAAQ;AAErB,MAAI,CAAC,KAAM;EAEX,MAAM,OAAO,MAAM,KACjB,KAAK,iBAGH,wDACD,CACF;EAKD,MAAM,uBAAO,IAAI,KAAqB;AAEtC,OAAK,MAAM,OAAO,KAAM,MAAK,IAAI,IAAI,QAAQ,KAAM,IAAI,UAAU;EAEjE,MAAM,WAAW,YAAY;EAC7B,MAAM,gBAAgB,iBAAiB;EACvC,MAAM,YAAY,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAK;AAErD,cAAY,UAAU;AACtB,mBAAiB,UAAU;AAK3B,MAAI,CAAC,aAAa,sBAAsB,IAAI,CAAC,SAAU;EAavD,MAAM,YAAY,IAAI,IAAI,UAAU;EACpC,MAAM,SAAS,cAAc,QAAQ,QAAQ,UAAU,IAAI,IAAI,CAAC;EAChE,MAAM,QAAQ,UAAU,QAAQ,QAAQ,SAAS,IAAI,IAAI,CAAC;AAK1D,MAAI,EAHF,OAAO,WAAW,MAAM,UACxB,OAAO,MAAM,KAAK,UAAU,QAAQ,MAAM,OAAO,EAEnC;EAEhB,MAAM,QAAuD,EAAE;AAE/D,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,OAAO,SAAS,IAAI,IAAI,QAAQ,IAAK;AAO3C,OAAI,SAAS,OAAW;GAExB,MAAM,QAAQ,OAAO,KAAK,IAAI,IAAI,QAAQ,IAAK;AAE/C,OAAI,UAAU,EAAG,OAAM,KAAK;IAAE;IAAK;IAAO,CAAC;;AAG7C,MAAI,CAAC,MAAM,OAAQ;AAInB,OAAK,MAAM,EAAE,KAAK,WAAW,OAAO;AAClC,OAAI,MAAM,aAAa;AACvB,OAAI,MAAM,YAAY,cAAc,MAAM;;AAQ5C,EAAK,KAAK;AAGV,OAAK,MAAM,EAAE,SAAS,OAAO;AAC3B,OAAI,MAAM,aAAa,aAAa,SAAS;AAC7C,OAAI,MAAM,YAAY;;EAWxB,MAAM,cAAc;AAClB,QAAK,MAAM,EAAE,SAAS,OAAO;AAC3B,QAAI,MAAM,aAAa;AACvB,QAAI,MAAM,YAAY;;;EAG1B,MAAM,QAAQ,WAAW,OAAO,SAAS;AAEzC,eAAa;AAGX,gBAAa,MAAM;AACnB,UAAO;;GAET"}

package/dist/components/data/TableBase/use-scrollability.js

@@ -0,0 +1,49 @@
+/** @license MIT | @cube-dev/ui-kit v0.157.1 | Cube Dev Team */
+import { useLayoutEffect, useState } from "react";
+
+//#region src/components/data/TableBase/use-scrollability.ts
+const NONE = {
+	x: false,
+	y: false
+};
+/**
+* Whether the scroller can actually scroll, per axis.
+*
+* This exists for `overscroll-behavior`. `contain` is what stops a horizontal
+* swipe at the scroll edge from triggering browser back-navigation, but Chrome
+* applies it to any element with `overflow: auto` — including one whose content
+* fits. The wheel event is then swallowed by a scroller with nothing to scroll,
+* and the page behind it will not move. So the containment has to be scoped to
+* the axis that is genuinely scrollable, which means measuring.
+*
+* Both the scroller and its content are observed: the scroller's own box does
+* not change when rows are added, so observing it alone would miss a table that
+* grew past its container.
+*/
+function useScrollability(element) {
+	const [state, setState] = useState(NONE);
+	useLayoutEffect(() => {
+		if (!element || !(element instanceof Element)) {
+			setState(NONE);
+			return;
+		}
+		const measure = () => {
+			const next = {
+				x: element.scrollWidth - element.clientWidth > 1,
+				y: element.scrollHeight - element.clientHeight > 1
+			};
+			setState((current) => current.x === next.x && current.y === next.y ? current : next);
+		};
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(element);
+		const content = element.firstElementChild;
+		if (content) observer.observe(content);
+		return () => observer.disconnect();
+	}, [element]);
+	return state;
+}
+
+//#endregion
+export { useScrollability };
+//# sourceMappingURL=use-scrollability.js.map

package/dist/components/data/TableBase/use-scrollability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-scrollability.js","names":[],"sources":["../../../../src/components/data/TableBase/use-scrollability.ts"],"sourcesContent":["import { useLayoutEffect, useState } from 'react';\n\nexport interface CubeScrollability {\n  x: boolean;\n  y: boolean;\n}\n\nconst NONE: CubeScrollability = { x: false, y: false };\n\n/**\n * Whether the scroller can actually scroll, per axis.\n *\n * This exists for `overscroll-behavior`. `contain` is what stops a horizontal\n * swipe at the scroll edge from triggering browser back-navigation, but Chrome\n * applies it to any element with `overflow: auto` — including one whose content\n * fits. The wheel event is then swallowed by a scroller with nothing to scroll,\n * and the page behind it will not move. So the containment has to be scoped to\n * the axis that is genuinely scrollable, which means measuring.\n *\n * Both the scroller and its content are observed: the scroller's own box does\n * not change when rows are added, so observing it alone would miss a table that\n * grew past its container.\n */\nexport function useScrollability(\n  element: HTMLElement | null,\n): CubeScrollability {\n  const [state, setState] = useState<CubeScrollability>(NONE);\n\n  useLayoutEffect(() => {\n    // Matches `useContainerWidth`: a scroller handed over by a callback ref can\n    // be null, and `observe` throws on anything that is not an Element.\n    if (!element || !(element instanceof Element)) {\n      setState(NONE);\n\n      return;\n    }\n\n    const measure = () => {\n      // A 1px tolerance: sub-pixel layout regularly leaves `scrollHeight` a\n      // fraction above `clientHeight` on a table that visibly does not scroll,\n      // and trapping the wheel over that fraction is the exact bug this avoids.\n      const next = {\n        x: element.scrollWidth - element.clientWidth > 1,\n        y: element.scrollHeight - element.clientHeight > 1,\n      };\n\n      setState((current) =>\n        current.x === next.x && current.y === next.y ? current : next,\n      );\n    };\n\n    measure();\n\n    const observer = new ResizeObserver(measure);\n\n    observer.observe(element);\n\n    const content = element.firstElementChild;\n\n    if (content) observer.observe(content);\n\n    return () => observer.disconnect();\n  }, [element]);\n\n  return state;\n}\n"],"mappings":";;;;AAOA,MAAM,OAA0B;CAAE,GAAG;CAAO,GAAG;CAAO;;;;;;;;;;;;;;;AAgBtD,SAAgB,iBACd,SACmB;CACnB,MAAM,CAAC,OAAO,YAAY,SAA4B,KAAK;AAE3D,uBAAsB;AAGpB,MAAI,CAAC,WAAW,EAAE,mBAAmB,UAAU;AAC7C,YAAS,KAAK;AAEd;;EAGF,MAAM,gBAAgB;GAIpB,MAAM,OAAO;IACX,GAAG,QAAQ,cAAc,QAAQ,cAAc;IAC/C,GAAG,QAAQ,eAAe,QAAQ,eAAe;IAClD;AAED,aAAU,YACR,QAAQ,MAAM,KAAK,KAAK,QAAQ,MAAM,KAAK,IAAI,UAAU,KAC1D;;AAGH,WAAS;EAET,MAAM,WAAW,IAAI,eAAe,QAAQ;AAE5C,WAAS,QAAQ,QAAQ;EAEzB,MAAM,UAAU,QAAQ;AAExB,MAAI,QAAS,UAAS,QAAQ,QAAQ;AAEtC,eAAa,SAAS,YAAY;IACjC,CAAC,QAAQ,CAAC;AAEb,QAAO"}

package/dist/components/data/TableBase/use-table-columns.d.ts

@@ -0,0 +1,2 @@
+
+import "./types.js";

package/dist/components/data/TableBase/use-table-columns.js

@@ -0,0 +1,166 @@
+/** @license MIT | @cube-dev/ui-kit v0.157.1 | Cube Dev Team */
+import { useMemo } from "react";
+
+//#region src/components/data/TableBase/use-table-columns.ts
+/** @default when a column declares neither `width` nor `minWidth`. */
+const DEFAULT_MIN_WIDTH = 150;
+/**
+* Reads `key` as a data path. A plain key is a single property lookup; dots
+* walk nested objects (`'owner.name'`). Anything richer belongs in `getValue`.
+*/
+function readPath(row, path) {
+	if (row == null) return void 0;
+	if (!path.includes(".")) return row[path];
+	let current = row;
+	for (const part of path.split(".")) {
+		if (current == null) return void 0;
+		current = current[part];
+	}
+	return current;
+}
+function getColumnValue(column, row, rowIndex) {
+	return column.getValue ? column.getValue(row, rowIndex) : readPath(row, column.key);
+}
+/**
+* Display text for a cell — what client sort, client search and TSV copy all
+* operate on. Deliberately NOT the rendered output: `render` may return
+* arbitrary React, and stringifying that is how cloud's filter ended up
+* matching `"[object Object]"` against the query `"object"`.
+*
+* Returns `null` when the column cannot produce text, so callers can skip it
+* rather than coerce a non-primitive.
+*/
+function getColumnText(column, row, rowIndex) {
+	const value = getColumnValue(column, row, rowIndex);
+	if (column.format) return column.format(value, row, rowIndex);
+	if (value == null) return "";
+	const type = typeof value;
+	if (type === "string") return value;
+	if (type === "number" || type === "boolean" || type === "bigint") return String(value);
+	if (value instanceof Date) return value.toISOString();
+	return null;
+}
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max ?? Number.POSITIVE_INFINITY);
+}
+/**
+* Normalizes the public column list into resolved leaves: visual order, ARIA
+* indices, pixel widths, and sticky offsets for pinned columns.
+*
+* Width resolution mirrors ag-grid's `fitGridWidth`: fixed columns take their
+* width, the remainder is split across flex columns by weight, and each result
+* is clamped to `[minWidth, maxWidth]`. Clamping perturbs the sum, so the
+* residual is redistributed across the still-unclamped columns until it
+* settles. When even the minimums do not fit, every column takes its minimum
+* and the table scrolls horizontally.
+*/
+function useTableColumns({ columns, containerWidth, columnWidths, leadingColumns, trailingColumns }) {
+	return useMemo(() => {
+		const visible = [
+			...leadingColumns ?? [],
+			...columns,
+			...trailingColumns ?? []
+		].filter((column) => !column.isHidden);
+		const ordered = [
+			...visible.filter((c) => c.pin === "start"),
+			...visible.filter((c) => !c.pin),
+			...visible.filter((c) => c.pin === "end")
+		];
+		const structuralKeys = new Set([...leadingColumns ?? [], ...trailingColumns ?? []].map((c) => c.key));
+		const specs = ordered.map((column) => {
+			const isStructural = structuralKeys.has(column.key);
+			const explicit = columnWidths?.[column.key] ?? column.width;
+			const minWidth = column.minWidth ?? (explicit != null ? explicit : isStructural ? 0 : DEFAULT_MIN_WIDTH);
+			return {
+				column,
+				isStructural,
+				fixed: explicit ?? null,
+				minWidth,
+				maxWidth: column.maxWidth ?? null,
+				flex: explicit != null ? null : column.flex ?? 1
+			};
+		});
+		const resolved = /* @__PURE__ */ new Map();
+		let isOverflowing = false;
+		if (containerWidth != null && containerWidth > 0) {
+			const fixedTotal = specs.reduce((sum, s) => sum + (s.fixed ?? 0), 0);
+			const flexSpecs = specs.filter((s) => s.fixed == null);
+			if (specs.reduce((sum, s) => sum + (s.fixed ?? s.minWidth), 0) > containerWidth) {
+				isOverflowing = true;
+				for (const spec of specs) resolved.set(spec.column.key, spec.fixed ?? spec.minWidth);
+			} else {
+				let remaining = containerWidth - fixedTotal;
+				let pool = flexSpecs;
+				while (pool.length > 0) {
+					const totalFlex = pool.reduce((sum, s) => sum + (s.flex ?? 1), 0);
+					const nextPool = [];
+					let consumed = 0;
+					for (const spec of pool) {
+						const ideal = remaining * (spec.flex ?? 1) / (totalFlex || 1);
+						const clamped = clamp(ideal, spec.minWidth, spec.maxWidth);
+						if (clamped !== ideal) {
+							resolved.set(spec.column.key, clamped);
+							consumed += clamped;
+						} else nextPool.push(spec);
+					}
+					if (nextPool.length === pool.length) {
+						const totalLeft = nextPool.reduce((sum, s) => sum + (s.flex ?? 1), 0);
+						for (const spec of nextPool) resolved.set(spec.column.key, remaining * (spec.flex ?? 1) / (totalLeft || 1));
+						break;
+					}
+					remaining -= consumed;
+					pool = nextPool;
+				}
+				for (const spec of specs) if (spec.fixed != null) resolved.set(spec.column.key, spec.fixed);
+			}
+		}
+		let pinnedStartWidth = 0;
+		let pinnedEndWidth = 0;
+		const out = specs.map((spec, index) => ({
+			...spec.column,
+			index,
+			ariaColIndex: index + 1,
+			width: resolved.get(spec.column.key) ?? null,
+			minWidth: spec.minWidth,
+			maxWidth: spec.maxWidth,
+			flex: spec.flex,
+			align: spec.column.align ?? "start",
+			pinOffset: null,
+			isPinEdge: false,
+			isStructural: spec.isStructural
+		}));
+		for (const column of out) {
+			if (column.pin !== "start") continue;
+			column.pinOffset = pinnedStartWidth;
+			pinnedStartWidth += column.width ?? column.minWidth;
+		}
+		for (let i = out.length - 1; i >= 0; i--) {
+			const column = out[i];
+			if (column.pin !== "end") continue;
+			column.pinOffset = pinnedEndWidth;
+			pinnedEndWidth += column.width ?? column.minWidth;
+		}
+		const lastPinnedStart = out.filter((c) => c.pin === "start").at(-1);
+		const firstPinnedEnd = out.find((c) => c.pin === "end");
+		if (lastPinnedStart) lastPinnedStart.isPinEdge = true;
+		if (firstPinnedEnd) firstPinnedEnd.isPinEdge = true;
+		const totalWidth = out.every((c) => c.width != null) ? out.reduce((sum, c) => sum + (c.width ?? 0), 0) : null;
+		return {
+			columns: out,
+			pinnedStartWidth,
+			pinnedEndWidth,
+			totalWidth,
+			isOverflowing
+		};
+	}, [
+		columns,
+		containerWidth,
+		columnWidths,
+		leadingColumns,
+		trailingColumns
+	]);
+}
+
+//#endregion
+export { getColumnText, getColumnValue, useTableColumns };
+//# sourceMappingURL=use-table-columns.js.map