@bigcapitalhq/blueprintjs-react-table 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +245 -7
  2. package/dist/blueprintjs-react-table.cjs +6 -0
  3. package/dist/blueprintjs-react-table.cjs.map +1 -0
  4. package/dist/blueprintjs-react-table.js +2533 -0
  5. package/dist/blueprintjs-react-table.js.map +1 -0
  6. package/dist/styles.css +1 -0
  7. package/dist/types/components/BP_Table.d.ts +119 -6
  8. package/dist/types/components/body/TableBody.d.ts +18 -1
  9. package/dist/types/components/body/TableBodyCell.d.ts +6 -3
  10. package/dist/types/components/body/TableGhostCells.d.ts +18 -4
  11. package/dist/types/components/body/TableRowHeaderCell.d.ts +9 -3
  12. package/dist/types/components/body/TableRowHeaders.d.ts +16 -1
  13. package/dist/types/components/body/TableRowSelectionCell.d.ts +18 -0
  14. package/dist/types/components/common/cell-selection.d.ts +57 -0
  15. package/dist/types/components/common/cellCoordinates.d.ts +25 -4
  16. package/dist/types/components/common/classes.d.ts +8 -0
  17. package/dist/types/components/common/dimensions.d.ts +5 -0
  18. package/dist/types/components/common/menu-context.d.ts +81 -0
  19. package/dist/types/components/common/pinning.d.ts +44 -0
  20. package/dist/types/components/common/region.d.ts +26 -0
  21. package/dist/types/components/common/table-selection-context.d.ts +3 -3
  22. package/dist/types/components/container/TableContainer.d.ts +8 -2
  23. package/dist/types/components/head/TableColumnHeaders.d.ts +4 -1
  24. package/dist/types/components/head/TableHead.d.ts +3 -1
  25. package/dist/types/components/head/TableRowSelectionHeaderCell.d.ts +13 -0
  26. package/dist/types/components/layers/TableRegionLayer.d.ts +10 -2
  27. package/dist/types/components/layers/TableReorderGuides.d.ts +10 -1
  28. package/dist/types/components/layers/TableResizeGuides.d.ts +18 -5
  29. package/dist/types/components/pagination/TablePaginationBar.d.ts +30 -0
  30. package/dist/types/components/pagination/constants.d.ts +4 -0
  31. package/dist/types/components/pagination/withPagination.d.ts +51 -0
  32. package/dist/types/components/quadrant/TableQuadrant.d.ts +41 -10
  33. package/dist/types/components/quadrant/TableQuadrantStack.d.ts +38 -0
  34. package/dist/types/components/quadrant/quadrant-type.d.ts +10 -0
  35. package/dist/types/hooks/use-bp-table-instance.d.ts +31 -0
  36. package/dist/types/hooks/use-cell-selection.d.ts +62 -0
  37. package/dist/types/hooks/use-column-header-height.d.ts +24 -0
  38. package/dist/types/hooks/use-column-reorder.d.ts +7 -3
  39. package/dist/types/hooks/use-freeze-pinning.d.ts +25 -0
  40. package/dist/types/hooks/use-row-virtualizer.d.ts +13 -2
  41. package/dist/types/hooks/use-uncontrolled.d.ts +19 -0
  42. package/dist/types/index.d.ts +8 -0
  43. package/dist/types/types.d.ts +12 -1
  44. package/package.json +2 -2
  45. package/dist/types/components/body/TableStaticBody.d.ts +0 -10
  46. package/dist/types/components/body/VirtualBody.d.ts +0 -12
  47. package/dist/types/components/quadrant/TableBottomContainer.d.ts +0 -14
  48. package/dist/types/components/quadrant/TableTopContainer.d.ts +0 -11
  49. package/dist/types/hooks/use-cell-focus-selection.d.ts +0 -34
@@ -50,7 +50,33 @@ export declare class Regions {
50
50
  static getCellRegionFromRegion(region: Region, numRows: number, numCols: number): NonNullRegion;
51
51
  static getFocusCellCoordinatesFromRegion(region: Region): CellCoordinates;
52
52
  static regionsEqual(regionA: Region, regionB: Region): boolean;
53
+ /**
54
+ * Returns the index of the region that wholly contains the supplied
55
+ * region. Returns -1 if no such region is found.
56
+ */
57
+ static findContainingRegion(regions: Region[] | null | undefined, region: Region): number;
58
+ /**
59
+ * Returns true if the regions fully contain the query region.
60
+ */
61
+ static containsRegion(regions: Region[], query: Region): boolean;
62
+ /**
63
+ * Returns true if the regions at least partially overlap the query region.
64
+ * When `allowPartialOverlap` is false (the default), every interval of the
65
+ * query region must be fully contained in the corresponding interval of a
66
+ * region.
67
+ */
68
+ static overlapsRegion(regions: Region[], query: Region, allowPartialOverlap?: boolean): boolean;
69
+ /**
70
+ * Using the supplied array of potentially non-contiguous `Region`s, returns
71
+ * an ordered array of every unique cell that exists in those regions. The
72
+ * cell coordinates are sorted by row and then column.
73
+ */
74
+ static enumerateUniqueCells(regions: Region[] | null | undefined, numRows: number, numCols: number): CellCoordinates[];
53
75
  static joinStyledRegionGroups(selectedRegions: Region[] | undefined, focusedRegion: FocusedRegion | undefined): StyledRegionGroup[];
76
+ private static regionContains;
77
+ private static intervalContains;
78
+ private static intervalOverlaps;
79
+ private static eachCellInRegion;
54
80
  private static clamp;
55
81
  private static intervalsEqual;
56
82
  private static normalizeInterval;
@@ -1,3 +1,3 @@
1
- import type { CellFocusSelectionApi } from '../../hooks/use-cell-focus-selection.js';
2
- export declare const TableSelectionContext: import("react").Context<CellFocusSelectionApi | null>;
3
- export declare function useTableSelection(): CellFocusSelectionApi | null;
1
+ import type { CellSelectionApi } from '../../hooks/use-cell-selection.js';
2
+ export declare const TableSelectionContext: import("react").Context<CellSelectionApi | null>;
3
+ export declare function useTableSelection(): CellSelectionApi | null;
@@ -1,14 +1,18 @@
1
1
  import { RegionCardinality, type FocusedCellCoordinates, type FocusedRegion, type Region } from '../common/region.js';
2
2
  import type { RowVirtualizerOptions } from '../../hooks/use-row-virtualizer.js';
3
+ import type { BP_BodyContextMenuRenderer } from '../common/menu-context.js';
3
4
  import type { BP_RowData, BP_TableInstance, HTMLPropsRef, TableLoading } from '../../types.js';
4
5
  import type { TableLayout } from '../common/dimensions.js';
5
6
  export type TableContainerProps<TData extends BP_RowData> = HTMLPropsRef<HTMLDivElement> & TableLayout & TableLoading & Pick<RowVirtualizerOptions<TData>, 'enableRowVirtualization' | 'overscanRowCount'> & {
6
7
  table: BP_TableInstance<TData>;
8
+ /** Whether to render the row headers (the row-number column) and corner menu. */
9
+ enableRowHeader?: boolean;
7
10
  enableColumnReordering?: boolean;
8
11
  enableSorting?: boolean;
9
12
  enableFocusedCell?: boolean;
10
13
  enableGhostCells?: boolean;
11
- focusedCell?: FocusedCellCoordinates;
14
+ bodyContextMenuRenderer?: BP_BodyContextMenuRenderer<TData>;
15
+ enableBodyContextMenu?: boolean;
12
16
  onFocusedCell?: (cell: FocusedCellCoordinates) => void;
13
17
  onFocusedRegion?: (region: FocusedRegion) => void;
14
18
  selectedRegions?: Region[];
@@ -20,5 +24,7 @@ export type TableContainerProps<TData extends BP_RowData> = HTMLPropsRef<HTMLDiv
20
24
  onRowHeightChanged?: (index: number, height: number) => void;
21
25
  minRowHeight?: number;
22
26
  maxRowHeight?: number;
27
+ /** Width of the row-selection checkboxes column; `0` hides the column. */
28
+ selectionColumnWidth?: number;
23
29
  };
24
- export declare function TableContainer<TData extends BP_RowData>({ table, rowHeight, rowHeaderWidth, columnHeaderHeight, enableColumnReordering, enableSorting, areCellsLoading, areColumnHeadersLoading, areRowHeadersLoading, enableFocusedCell, enableGhostCells, focusedCell, onFocusedCell, onFocusedRegion, selectedRegions, onSelection, selectionModes, enableRowVirtualization, overscanRowCount, enableRowResizing, rowHeights, defaultRowHeights, onRowHeightChanged, minRowHeight, maxRowHeight, className, ...restProps }: TableContainerProps<TData>): import("react").JSX.Element;
30
+ export declare function TableContainer<TData extends BP_RowData>({ table, rowHeight, rowHeaderWidth, enableRowHeader, columnHeaderHeight, enableColumnReordering, enableSorting, areCellsLoading, areColumnHeadersLoading, areRowHeadersLoading, enableFocusedCell, enableGhostCells, bodyContextMenuRenderer, enableBodyContextMenu, onFocusedCell, onFocusedRegion, selectedRegions, onSelection, selectionModes, enableRowVirtualization, overscanRowCount, enableRowResizing, rowHeights, defaultRowHeights, onRowHeightChanged, minRowHeight, maxRowHeight, selectionColumnWidth, className, ...restProps }: TableContainerProps<TData>): import("react").JSX.Element;
@@ -1,9 +1,12 @@
1
+ import { type ColumnRegion } from '../common/pinning.js';
1
2
  import { type BP_GhostCells } from '../../hooks/use-ghost-cells.js';
2
3
  import type { BP_RowData, BP_TableInstance, HTMLPropsRef } from '../../types.js';
3
4
  export type TableColumnHeadersProps<TData extends BP_RowData> = HTMLPropsRef<HTMLDivElement> & {
4
5
  table: BP_TableInstance<TData>;
6
+ /** Which column region this header renders: frozen ("start") or scrollable ("center"). */
7
+ columnRegion: ColumnRegion;
5
8
  enableSorting?: boolean;
6
9
  areColumnHeadersLoading: boolean;
7
10
  ghosts?: BP_GhostCells;
8
11
  };
9
- export declare function TableColumnHeaders<TData extends BP_RowData>({ table, enableSorting, areColumnHeadersLoading, ghosts, className, ...restProps }: TableColumnHeadersProps<TData>): import("react").JSX.Element;
12
+ export declare function TableColumnHeaders<TData extends BP_RowData>({ table, columnRegion, enableSorting, areColumnHeadersLoading, ghosts, className, ...restProps }: TableColumnHeadersProps<TData>): import("react").JSX.Element;
@@ -1,11 +1,13 @@
1
1
  import { type HeaderGroup } from '@tanstack/react-table';
2
+ import { type ColumnRegion } from '../common/pinning.js';
2
3
  import { type BP_GhostCells } from '../../hooks/use-ghost-cells.js';
3
4
  import type { BP_RowData, BP_TableFeatures, BP_TableInstance } from '../../types.js';
4
5
  export type TableHeadProps<TData extends BP_RowData> = {
5
6
  table: BP_TableInstance<TData>;
6
7
  headerGroup: HeaderGroup<BP_TableFeatures, TData>;
8
+ columnRegion: ColumnRegion;
7
9
  enableSorting?: boolean;
8
10
  areColumnHeadersLoading: boolean;
9
11
  ghosts?: BP_GhostCells;
10
12
  };
11
- export declare function TableHead<TData extends BP_RowData>({ table, headerGroup, enableSorting, areColumnHeadersLoading, ghosts, }: TableHeadProps<TData>): import("react").JSX.Element;
13
+ export declare function TableHead<TData extends BP_RowData>({ table, headerGroup, columnRegion, enableSorting, areColumnHeadersLoading, ghosts, }: TableHeadProps<TData>): import("react").JSX.Element;
@@ -0,0 +1,13 @@
1
+ import type { BP_RowData, BP_TableInstance } from '../../types.js';
2
+ export type TableRowSelectionHeaderCellProps<TData extends BP_RowData> = {
3
+ table: BP_TableInstance<TData>;
4
+ width: number;
5
+ height: number;
6
+ /** Whether the row headers are currently showing loading placeholders. */
7
+ loading?: boolean;
8
+ };
9
+ /**
10
+ * The header of the row-selection checkboxes column: a select-all checkbox
11
+ * with an indeterminate state, sitting to the right of the corner menu.
12
+ */
13
+ export declare function TableRowSelectionHeaderCell<TData extends BP_RowData>({ table, width, height, loading, }: TableRowSelectionHeaderCellProps<TData>): import("react").JSX.Element;
@@ -1,10 +1,18 @@
1
1
  import { type StyledRegionGroup } from '../common/region.js';
2
+ import { type ColumnRegion, type RowRegion } from '../common/pinning.js';
2
3
  import type { BP_RowData, BP_TableInstance } from '../../types.js';
3
4
  export type TableRegionLayerProps<TData extends BP_RowData> = {
4
5
  table: BP_TableInstance<TData>;
5
6
  regionGroups: StyledRegionGroup[];
7
+ columnRegion: ColumnRegion;
8
+ rowRegion: RowRegion;
6
9
  getRowTop: (index: number) => number;
7
10
  getRowHeight: (index: number) => number;
8
- totalHeight: number;
9
11
  };
10
- export declare function TableRegionLayer<TData extends BP_RowData>({ table, regionGroups, getRowTop, getRowHeight, totalHeight, }: TableRegionLayerProps<TData>): import("react").JSX.Element;
12
+ /**
13
+ * Renders the selection and focus regions clipped to a single quadrant's
14
+ * region. Regions that span the frozen and scrollable areas are drawn as
15
+ * abutting rectangles in each quadrant, so the selection overlay stays pinned
16
+ * to the frozen rows/columns as the scrollable area scrolls under them.
17
+ */
18
+ export declare function TableRegionLayer<TData extends BP_RowData>({ table, regionGroups, columnRegion, rowRegion, getRowTop, getRowHeight, }: TableRegionLayerProps<TData>): import("react").JSX.Element;
@@ -4,5 +4,14 @@ export type TableReorderGuidesProps<TData extends BP_RowData> = {
4
4
  reorderingColumnId: string | null;
5
5
  guideIndex: number | null;
6
6
  rowHeaderWidth: number;
7
+ /** Current horizontal scroll offset of the main quadrant. */
8
+ scrollLeft: number;
7
9
  };
8
- export declare function TableReorderGuides<TData extends BP_RowData>({ table, reorderingColumnId, guideIndex, rowHeaderWidth, }: TableReorderGuidesProps<TData>): import("react").JSX.Element | null;
10
+ /**
11
+ * Preview guide shown while a column is being dragged. `guideIndex` is a
12
+ * boundary in the natural column order (0..numColumns); the guide is drawn at
13
+ * the display offset of that boundary. Boundaries inside the frozen region are
14
+ * fixed, while boundaries in the scrollable region follow the main quadrant's
15
+ * horizontal scroll offset — mirroring Blueprint's quadrant-aware guide.
16
+ */
17
+ export declare function TableReorderGuides<TData extends BP_RowData>({ table, reorderingColumnId, guideIndex, rowHeaderWidth, scrollLeft, }: TableReorderGuidesProps<TData>): import("react").JSX.Element | null;
@@ -1,11 +1,24 @@
1
1
  import type { BP_RowData, BP_TableInstance } from '../../types.js';
2
2
  export type TableResizeGuidesProps<TData extends BP_RowData> = {
3
3
  table: BP_TableInstance<TData>;
4
+ rowHeaderWidth: number;
5
+ /** Effective height of the column-header area; offsets the horizontal guide into the body's coordinate space. */
6
+ columnHeaderHeight: number;
7
+ /** Current horizontal scroll offset of the main quadrant. */
8
+ scrollLeft: number;
9
+ /** Current vertical scroll offset of the main quadrant. */
10
+ scrollTop: number;
11
+ /** Number of frozen rows; rows before it never scroll vertically. */
12
+ frozenRowCount: number;
4
13
  /** Absolute top of the horizontal guide while resizing a row, or `null`. */
5
14
  resizingGuideTop?: number | null;
6
- /** Height of the column-header area; offsets the horizontal guide into the body's coordinate space. */
7
- columnHeaderHeight?: number;
8
- /** Width of the row-header/menu area; offsets the vertical guide into the body's coordinate space. */
9
- rowHeaderWidth?: number;
15
+ /** Absolute index of the row being resized, or `null`. */
16
+ resizingRowIndex?: number | null;
10
17
  };
11
- export declare function TableResizeGuides<TData extends BP_RowData>({ table, resizingGuideTop, columnHeaderHeight, rowHeaderWidth, }: TableResizeGuidesProps<TData>): import("react").JSX.Element | null;
18
+ /**
19
+ * Resize guides for the whole table. The layers live at the quadrant-stack
20
+ * level so a guide can span across the frozen and scrollable regions; the
21
+ * display offsets of the columns/rows they track are derived from the main
22
+ * quadrant's scroll offsets.
23
+ */
24
+ export declare function TableResizeGuides<TData extends BP_RowData>({ table, rowHeaderWidth, columnHeaderHeight, scrollLeft, scrollTop, frozenRowCount, resizingGuideTop, resizingRowIndex, }: TableResizeGuidesProps<TData>): import("react").JSX.Element | null;
@@ -0,0 +1,30 @@
1
+ export type TablePaginationBarProps = {
2
+ /** Zero-based index of the current page. */
3
+ pageIndex: number;
4
+ /** Number of rows shown per page. */
5
+ pageSize: number;
6
+ /**
7
+ * Total number of pages. `undefined` means the count is unknown — typical for
8
+ * manual/server-side pagination without a `rowCount` — in which case "last"
9
+ * navigation is disabled and "next" stays enabled.
10
+ */
11
+ pageCount?: number;
12
+ /**
13
+ * Total number of rows across all pages, used for the "1–10 of 240" summary.
14
+ * When `undefined`, the summary is omitted.
15
+ */
16
+ rowCount?: number;
17
+ /** Page sizes offered by the rows-per-page select. */
18
+ pageSizeOptions?: readonly number[];
19
+ /** Invoked with the requested page index when a navigation control is used. */
20
+ onPageIndexChange: (pageIndex: number) => void;
21
+ /** Invoked with the requested page size when the rows-per-page select changes. */
22
+ onPageSizeChange: (pageSize: number) => void;
23
+ className?: string;
24
+ };
25
+ /**
26
+ * Blueprint-styled pagination bar rendered below the table by the
27
+ * `withPagination` HOC. It is presentational: page state and navigation are
28
+ * owned by the caller.
29
+ */
30
+ export declare function TablePaginationBar({ pageIndex, pageSize, pageCount, rowCount, pageSizeOptions, onPageIndexChange, onPageSizeChange, className, }: TablePaginationBarProps): import("react").JSX.Element;
@@ -0,0 +1,4 @@
1
+ /** Default number of rows per page for uncontrolled pagination. */
2
+ export declare const DEFAULT_PAGE_SIZE = 10;
3
+ /** Page sizes offered by the pagination bar when none are supplied. */
4
+ export declare const DEFAULT_PAGE_SIZE_OPTIONS: number[];
@@ -0,0 +1,51 @@
1
+ import { type ComponentType } from 'react';
2
+ import type { BP_RowData } from '../../types.js';
3
+ import type { BP_TableProps } from '../BP_Table.js';
4
+ export type BP_PaginationOptions = {
5
+ /**
6
+ * Initial page size for uncontrolled pagination. Ignored when
7
+ * `state.pagination` or `initialState.pagination` is provided.
8
+ *
9
+ * @default 10
10
+ */
11
+ initialPageSize?: number;
12
+ /**
13
+ * Initial zero-based page index for uncontrolled pagination. Ignored when
14
+ * `state.pagination` or `initialState.pagination` is provided.
15
+ *
16
+ * @default 0
17
+ */
18
+ initialPageIndex?: number;
19
+ /** Page sizes offered by the pagination bar's rows-per-page select. */
20
+ pageSizeOptions?: readonly number[];
21
+ /**
22
+ * Whether to render the pagination bar below the table. When `false`, the
23
+ * table is still paginated; only the controls are hidden.
24
+ *
25
+ * @default true
26
+ */
27
+ showPaginationBar?: boolean;
28
+ /** Additional class name(s) for the pagination bar. */
29
+ paginationBarClassName?: string;
30
+ };
31
+ export type BP_PaginatedTableProps<TData extends BP_RowData> = BP_TableProps<TData> & BP_PaginationOptions;
32
+ /**
33
+ * Wraps a table component (usually `BP_Table`) with row pagination and a
34
+ * Blueprint-styled pagination bar, keeping the whole pagination concern — the
35
+ * TanStack feature registration, the page state, and the controls — outside the
36
+ * wrapped component.
37
+ *
38
+ * Pagination is uncontrolled by default (`initialPageIndex` /
39
+ * `initialPageSize`, or `initialState.pagination`). It becomes controlled when
40
+ * `state.pagination` is provided: the HOC defers to it and forwards
41
+ * `onPaginationChange`.
42
+ *
43
+ * Client-side pagination slices `data` automatically. For server-side
44
+ * pagination, pass `manualPagination` plus `pageCount` (or `rowCount`) and
45
+ * provide the current page's rows as `data`.
46
+ *
47
+ * @example
48
+ * const PaginatedTable = withPagination(BP_Table);
49
+ * <PaginatedTable data={rows} columns={columns} initialPageSize={20} />
50
+ */
51
+ export declare function withPagination<TData extends BP_RowData>(TableComponent: ComponentType<BP_TableProps<TData>>): ComponentType<BP_PaginatedTableProps<TData>>;
@@ -1,17 +1,48 @@
1
- import type { MutableRefObject } from 'react';
2
- import type { CellFocusSelectionApi } from '../../hooks/use-cell-focus-selection.js';
3
- import { type RowVirtualizerOptions } from '../../hooks/use-row-virtualizer.js';
4
- import type { RowResizingApi } from '../../hooks/use-row-resizing.js';
1
+ import type { CSSProperties, MutableRefObject, UIEventHandler, WheelEventHandler } from 'react';
5
2
  import type { BP_GhostCells } from '../../hooks/use-ghost-cells.js';
6
- import type { BP_RowData, BP_TableInstance, HTMLPropsRef, TableLoading } from '../../types.js';
7
- import type { TableLayout } from '../common/dimensions.js';
8
- export type TableQuadrantProps<TData extends BP_RowData> = HTMLPropsRef<HTMLDivElement> & Pick<TableLayout, 'rowHeaderWidth' | 'columnHeaderHeight'> & TableLoading & Pick<RowVirtualizerOptions<TData>, 'enableRowVirtualization' | 'overscanRowCount'> & {
3
+ import type { BP_RowVirtualizer } from '../../hooks/use-row-virtualizer.js';
4
+ import type { RowResizingApi } from '../../hooks/use-row-resizing.js';
5
+ import type { BP_RowData, BP_TableInstance } from '../../types.js';
6
+ import { QuadrantType } from './quadrant-type.js';
7
+ export type TableQuadrantProps<TData extends BP_RowData> = {
8
+ quadrantType: QuadrantType;
9
9
  table: BP_TableInstance<TData>;
10
- enableColumnReordering?: boolean;
10
+ rowHeaderWidth: number;
11
+ /** Whether to render the row headers (the row-number column) and corner menu. */
12
+ enableRowHeader?: boolean;
13
+ /** Effective (measured) height of the column-header area. */
14
+ columnHeaderHeight: number;
15
+ /** Ref used to measure the rendered column-header height (TOP quadrant only). */
16
+ columnHeaderMeasureRef?: MutableRefObject<HTMLDivElement | null>;
11
17
  enableSorting?: boolean;
12
- selection: CellFocusSelectionApi;
18
+ areCellsLoading: boolean;
19
+ areColumnHeadersLoading: boolean;
20
+ areRowHeadersLoading: boolean;
13
21
  rowResizing: RowResizingApi;
22
+ rowVirtualizer?: BP_RowVirtualizer;
14
23
  ghosts?: BP_GhostCells;
15
24
  scrollContainerRef: MutableRefObject<HTMLDivElement | null>;
25
+ /** Only provided for the main quadrant, whose scrollbar is visible. */
26
+ onScroll?: UIEventHandler<HTMLDivElement>;
27
+ /** Provided for every non-main quadrant; forwards wheel gestures to the main quadrant. */
28
+ onWheel?: WheelEventHandler<HTMLDivElement>;
29
+ style?: CSSProperties;
30
+ /** Width of the row-selection checkboxes column; `0` hides the column. */
31
+ selectionColumnWidth?: number;
16
32
  };
17
- export declare function TableQuadrant<TData extends BP_RowData>({ table, rowHeaderWidth, columnHeaderHeight, enableColumnReordering, enableSorting, areCellsLoading, areColumnHeadersLoading, areRowHeadersLoading, selection, scrollContainerRef, enableRowVirtualization, overscanRowCount, rowResizing, ghosts, className, ...restProps }: TableQuadrantProps<TData>): import("react").JSX.Element;
33
+ /**
34
+ * One quadrant of the table. The quadrant type determines which regions it
35
+ * renders:
36
+ *
37
+ * - `MAIN` renders the scrollable ("center") columns and rows. It is the only
38
+ * quadrant with visible scrollbars and the only one that handles keyboard
39
+ * focus; the other quadrants sync their scroll offsets from it.
40
+ * - `TOP` renders the column headers and the frozen ("top") rows.
41
+ * - `LEFT` renders the row headers and the frozen ("start") columns.
42
+ * - `TOP_LEFT` renders the corner menu, the frozen column headers, the frozen
43
+ * row headers, and the cells frozen in both directions.
44
+ *
45
+ * Each quadrant's content is padded with spacers so the quadrants that scroll
46
+ * share the main quadrant's scroll ranges.
47
+ */
48
+ export declare function TableQuadrant<TData extends BP_RowData>({ quadrantType, table, rowHeaderWidth, enableRowHeader, columnHeaderHeight, columnHeaderMeasureRef, enableSorting, areCellsLoading, areColumnHeadersLoading, areRowHeadersLoading, rowResizing, rowVirtualizer, ghosts, scrollContainerRef, onScroll, onWheel, style, selectionColumnWidth, }: TableQuadrantProps<TData>): import("react").JSX.Element;
@@ -0,0 +1,38 @@
1
+ import type { MutableRefObject } from 'react';
2
+ import type { CellSelectionApi } from '../../hooks/use-cell-selection.js';
3
+ import type { RowResizingApi } from '../../hooks/use-row-resizing.js';
4
+ import type { BP_GhostCells } from '../../hooks/use-ghost-cells.js';
5
+ import type { BP_RowData, BP_TableInstance } from '../../types.js';
6
+ export type TableQuadrantStackProps<TData extends BP_RowData> = {
7
+ table: BP_TableInstance<TData>;
8
+ rowHeaderWidth: number;
9
+ /** Whether to render the row headers (the row-number column) and corner menu. */
10
+ enableRowHeader?: boolean;
11
+ /** Effective (measured) height of the column-header area. */
12
+ columnHeaderHeight: number;
13
+ /** Ref to attach to the rendered TOP quadrant's column-header area. */
14
+ columnHeaderMeasureRef: MutableRefObject<HTMLDivElement | null>;
15
+ enableColumnReordering?: boolean;
16
+ enableSorting?: boolean;
17
+ areCellsLoading: boolean;
18
+ areColumnHeadersLoading: boolean;
19
+ areRowHeadersLoading: boolean;
20
+ selection: CellSelectionApi;
21
+ rowResizing: RowResizingApi;
22
+ ghosts?: BP_GhostCells;
23
+ enableRowVirtualization?: boolean;
24
+ overscanRowCount?: number;
25
+ /** Ref to the main quadrant's scroll container (the interactive one). */
26
+ scrollContainerRef: MutableRefObject<HTMLDivElement | null>;
27
+ /** Width of the row-selection checkboxes column; `0` hides the column. */
28
+ selectionColumnWidth?: number;
29
+ };
30
+ /**
31
+ * The table's quadrant stack: four clipped quadrants (main, top, left,
32
+ * top-left) overlaid on top of each other. Frozen columns and rows, the column
33
+ * headers, and the row headers are rendered by the frozen quadrants and stay in
34
+ * place, while the main quadrant scrolls. The frozen quadrants' offsets follow
35
+ * the main quadrant's scroll position, and wheel gestures over them are
36
+ * forwarded to the main quadrant.
37
+ */
38
+ export declare function TableQuadrantStack<TData extends BP_RowData>({ table, rowHeaderWidth, enableRowHeader, columnHeaderHeight, columnHeaderMeasureRef, enableColumnReordering, enableSorting, areCellsLoading, areColumnHeadersLoading, areRowHeadersLoading, selection, rowResizing, ghosts, enableRowVirtualization, overscanRowCount, scrollContainerRef, selectionColumnWidth, }: TableQuadrantStackProps<TData>): import("react").JSX.Element;
@@ -0,0 +1,10 @@
1
+ export declare enum QuadrantType {
2
+ /** The main quadrant beneath any frozen rows or columns. */
3
+ MAIN = "main",
4
+ /** The top quadrant, containing column headers and frozen rows. */
5
+ TOP = "top",
6
+ /** The left quadrant, containing row headers and frozen columns. */
7
+ LEFT = "left",
8
+ /** The top-left quadrant, containing the headers and cells common to both the frozen columns and frozen rows. */
9
+ TOP_LEFT = "top-left"
10
+ }
@@ -1,2 +1,33 @@
1
1
  import { BP_RowData, BP_TableFeatures, BP_TableInstance, BP_TableOptions } from '../types.js';
2
+ /**
3
+ * The feature registry `BP_Table` uses by default: column sizing/resizing,
4
+ * ordering, visibility, pinning, row pinning, row selection, cell selection,
5
+ * and sorting. It is exported so layers built on top of `BP_Table` (such as
6
+ * the `withPagination` HOC) can compose additional features without having to
7
+ * replace the defaults.
8
+ *
9
+ * Compose it with `tableFeatures()`:
10
+ *
11
+ * tableFeatures({ ...DEFAULT_BP_TABLE_FEATURES, rowPaginationFeature, paginatedRowModel: createPaginatedRowModel() })
12
+ */
13
+ export declare const DEFAULT_BP_TABLE_FEATURES: {
14
+ columnSizingFeature: import("@tanstack/table-core").TableFeature;
15
+ columnResizingFeature: import("@tanstack/table-core").TableFeature;
16
+ columnOrderingFeature: import("@tanstack/table-core").TableFeature;
17
+ columnVisibilityFeature: import("@tanstack/table-core").TableFeature;
18
+ columnPinningFeature: import("@tanstack/table-core").TableFeature;
19
+ rowPinningFeature: import("@tanstack/table-core").TableFeature;
20
+ rowSelectionFeature: import("@tanstack/table-core").TableFeature;
21
+ cellSelectionFeature: import("@tanstack/table-core").TableFeature;
22
+ rowSortingFeature: import("@tanstack/table-core").TableFeature;
23
+ sortedRowModel: (table: import("@tanstack/table-core").Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
24
+ sortFns: {
25
+ alphanumeric: import("@tanstack/table-core").CreatedSortFn<any, any>;
26
+ alphanumericCaseSensitive: import("@tanstack/table-core").CreatedSortFn<any, any>;
27
+ basic: import("@tanstack/table-core").CreatedSortFn<any, any>;
28
+ datetime: import("@tanstack/table-core").CreatedSortFn<any, any>;
29
+ text: import("@tanstack/table-core").CreatedSortFn<any, any>;
30
+ textCaseSensitive: import("@tanstack/table-core").CreatedSortFn<any, any>;
31
+ };
32
+ };
2
33
  export declare const useBPTableInstance: <TData extends BP_RowData>(definedTableOptions: BP_TableOptions<BP_TableFeatures, TData>) => BP_TableInstance<TData>;
@@ -0,0 +1,62 @@
1
+ import { type KeyboardEvent as ReactKeyboardEvent, type MouseEvent as ReactMouseEvent, type MutableRefObject, type PointerEvent as ReactPointerEvent, type ReactElement } from 'react';
2
+ import type { BP_RowData, BP_TableInstance } from '../types.js';
3
+ import { type BP_BodyContextMenuRenderer } from '../components/common/menu-context.js';
4
+ import { RegionCardinality, type FocusedCellCoordinates, type FocusedRegion, type Region, type StyledRegionGroup } from '../components/common/region.js';
5
+ export type CellSelectionOptions<TData extends BP_RowData> = {
6
+ table: BP_TableInstance<TData>;
7
+ /** Resolved absolute top offset of the row at the given index. */
8
+ getRowTop: (index: number) => number;
9
+ /** Resolved height of the row at the given index. */
10
+ getRowHeight: (index: number) => number;
11
+ scrollContainerRef: MutableRefObject<HTMLDivElement | null>;
12
+ /** Width of the frozen row-header column. */
13
+ rowHeaderWidth: number;
14
+ /** Effective height of the column-header area. */
15
+ columnHeaderHeight: number;
16
+ bodyContextMenuRenderer?: BP_BodyContextMenuRenderer<TData>;
17
+ enableBodyContextMenu?: boolean;
18
+ enableFocusedCell?: boolean;
19
+ onFocusedCell?: (cell: FocusedCellCoordinates) => void;
20
+ onFocusedRegion?: (region: FocusedRegion) => void;
21
+ selectedRegions?: Region[] | undefined;
22
+ onSelection?: (regions: Region[]) => void;
23
+ selectionModes?: RegionCardinality[];
24
+ };
25
+ export type CellSelectionApi = {
26
+ /**
27
+ * Styled region groups for the selection overlays: the selected regions
28
+ * (resolved from the cell selection plugin's bounds) and, when
29
+ * `enableFocusedCell` is on, the focused cell.
30
+ */
31
+ regionGroups: StyledRegionGroup[];
32
+ isSelectionModeEnabled: (cardinality: RegionCardinality) => boolean;
33
+ handleKeyDown: (event: ReactKeyboardEvent<HTMLDivElement>) => void;
34
+ /** Focuses the scroll container so keyboard navigation keeps working. */
35
+ handleBodyPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
36
+ handleColumnHeaderMouseDown: (index: number, event: ReactMouseEvent) => void;
37
+ handleRowHeaderMouseDown: (index: number, event: ReactMouseEvent) => void;
38
+ handleMenuMouseDown: (event: ReactMouseEvent) => void;
39
+ /** Whether a body context menu renderer is configured and enabled. */
40
+ isBodyContextMenuEnabled: boolean;
41
+ /**
42
+ * Applies Blueprint's right-click semantics before a body context menu
43
+ * opens: when the right-clicked cell is not part of the current selection,
44
+ * the selection (and the active cell) move to that cell.
45
+ */
46
+ handleBodyContextMenu: (event: ReactMouseEvent<HTMLElement>) => void;
47
+ /**
48
+ * Builds the menu context for the right-click event and invokes the
49
+ * configured body context menu renderer.
50
+ */
51
+ renderBodyContextMenu: (event: ReactMouseEvent<HTMLElement>) => ReactElement | undefined;
52
+ };
53
+ /**
54
+ * Cell-range selection and focused-cell navigation built on TanStack Table's
55
+ * `cellSelectionFeature`. The plugin owns the selection state (drag, shift
56
+ * extend, Ctrl/Cmd multi-range); this hook adds the Blueprint layer on top:
57
+ * full-row/column/table selection from the headers and corner menu, keyboard
58
+ * navigation, scroll-into-view, right-click context menu semantics, and the
59
+ * controlled `selectedRegions` / `onSelection` props translated to and from
60
+ * the plugin's state.
61
+ */
62
+ export declare function useCellSelection<TData extends BP_RowData>({ table, getRowTop, getRowHeight, scrollContainerRef, rowHeaderWidth, columnHeaderHeight, bodyContextMenuRenderer, enableBodyContextMenu, enableFocusedCell, onFocusedCell, onFocusedRegion, selectedRegions: controlledSelectedRegions, onSelection, selectionModes, }: CellSelectionOptions<TData>): CellSelectionApi;
@@ -0,0 +1,24 @@
1
+ import type { MutableRefObject } from 'react';
2
+ export type ColumnHeaderHeightOptions = {
3
+ /** Minimum height for the column-header area (the `columnHeaderHeight` prop). */
4
+ minHeight: number;
5
+ /** Number of header rows, used for the pre-measurement estimate. */
6
+ headerRowCount: number;
7
+ };
8
+ export type ColumnHeaderHeightResult = {
9
+ /** Attach to the rendered column-header area to measure its height. */
10
+ ref: MutableRefObject<HTMLDivElement | null>;
11
+ /** Effective height of the column-header area. */
12
+ height: number;
13
+ };
14
+ /**
15
+ * Resolves the effective height of the column-header area.
16
+ *
17
+ * Column headers can be taller than a single row (grouped columns render
18
+ * additional header rows, and custom header content can grow a row), so the
19
+ * rendered height is measured with a `ResizeObserver` and used as the source of
20
+ * truth for layout. Until the first measurement, an estimate of
21
+ * `headerRowCount * DEFAULT_COLUMN_HEADER_HEIGHT` keeps the layout stable, and
22
+ * the `minHeight` prop continues to act as a floor.
23
+ */
24
+ export declare function useColumnHeaderHeight({ minHeight, headerRowCount, }: ColumnHeaderHeightOptions): ColumnHeaderHeightResult;
@@ -4,12 +4,16 @@ import type { BP_RowData, BP_TableFeatures, BP_TableInstance } from '../types.js
4
4
  export type ColumnReorderStartHandler = <TData extends BP_RowData>(column: Column<BP_TableFeatures, TData>, event: ReactPointerEvent<Element>) => void;
5
5
  export type ColumnReorderContextValue = {
6
6
  enableColumnReordering: boolean;
7
- columnsRef: MutableRefObject<HTMLDivElement | null>;
8
7
  reorderingColumnId: string | null;
9
8
  startReorder: ColumnReorderStartHandler;
10
9
  };
11
- export declare function useColumnReorder<TData extends BP_RowData>(table: BP_TableInstance<TData>, enableColumnReordering: boolean): {
12
- columnsRef: MutableRefObject<HTMLDivElement | null>;
10
+ export declare function useColumnReorder<TData extends BP_RowData>(table: BP_TableInstance<TData>, enableColumnReordering: boolean,
11
+ /** Ref to the quadrant stack element; its left edge is the grid's x-origin. */
12
+ gridRef: MutableRefObject<HTMLDivElement | null>,
13
+ /** Ref to the main quadrant's scroll container (source of scroll offsets). */
14
+ scrollContainerRef: MutableRefObject<HTMLDivElement | null>,
15
+ /** Width of the frozen row-header column. */
16
+ rowHeaderWidth: number): {
13
17
  contextValue: ColumnReorderContextValue;
14
18
  guideIndex: number | null;
15
19
  reorderingColumnId: string | null;
@@ -0,0 +1,25 @@
1
+ import type { BP_RowData, BP_TableInstance } from '../types.js';
2
+ export type FreezePinningOptions<TData extends BP_RowData> = {
3
+ table: BP_TableInstance<TData>;
4
+ /**
5
+ * Number of leftmost columns that should be frozen. The pinned column ids are
6
+ * derived from the table's current visible leaf columns (in natural order),
7
+ * so freezing stays correct across column reordering and column visibility.
8
+ */
9
+ numFrozenColumns: number;
10
+ /**
11
+ * Number of topmost rows that should be frozen. The pinned row ids are
12
+ * derived from the table's current row model, so freezing follows sorting.
13
+ */
14
+ numFrozenRows: number;
15
+ };
16
+ /**
17
+ * Derives TanStack's column/row pinning state from the `numFrozenColumns` /
18
+ * `numFrozenRows` props, mirroring Blueprint's frozen columns and rows.
19
+ *
20
+ * The pinning state is the source of truth for the frozen regions (see
21
+ * `pinning.ts`), so power users can also drive it directly through TanStack's
22
+ * `columnPinning` / `rowPinning` state and `column.pin()` / `row.pin()` APIs.
23
+ * The hook is a no-op when both counts match the current state.
24
+ */
25
+ export declare function useFreezePinning<TData extends BP_RowData>({ table, numFrozenColumns, numFrozenRows, }: FreezePinningOptions<TData>): void;
@@ -5,11 +5,22 @@ export declare const DEFAULT_OVERSCAN_ROW_COUNT = 5;
5
5
  export type BP_RowVirtualizer = Virtualizer<HTMLDivElement, HTMLDivElement>;
6
6
  export type RowVirtualizerOptions<TData extends BP_RowData> = {
7
7
  table: BP_TableInstance<TData>;
8
+ /** Effective height of the column-header area above the scrollable body. */
8
9
  columnHeaderHeight: number;
9
- /** Resolved height of the row at the given index (used to estimate item sizes). */
10
+ /** Number of frozen rows rendered above the scrollable body. */
11
+ frozenRowCount: number;
12
+ /** Resolved height of the frozen rows rendered above the scrollable body. */
13
+ frozenRowsHeight: number;
14
+ /** Resolved height of the row at the given absolute index (used to estimate item sizes). */
10
15
  getRowHeight: (index: number) => number;
11
16
  scrollContainerRef: MutableRefObject<HTMLDivElement | null>;
12
17
  enableRowVirtualization: boolean;
13
18
  overscanRowCount: number;
14
19
  };
15
- export declare function useRowVirtualizer<TData extends BP_RowData>({ table, columnHeaderHeight, getRowHeight, scrollContainerRef, enableRowVirtualization, overscanRowCount, }: RowVirtualizerOptions<TData>): BP_RowVirtualizer | undefined;
20
+ /**
21
+ * Virtualizes the scrollable ("center") rows only. Frozen rows are always
22
+ * rendered (they are expected to be few) and are excluded from the virtualizer,
23
+ * so virtual item indices are offsets into the center rows; callers map them to
24
+ * absolute row indices with `getFrozenRowCount`.
25
+ */
26
+ export declare function useRowVirtualizer<TData extends BP_RowData>({ table, columnHeaderHeight, frozenRowCount, frozenRowsHeight, getRowHeight, scrollContainerRef, enableRowVirtualization, overscanRowCount, }: RowVirtualizerOptions<TData>): BP_RowVirtualizer | undefined;
@@ -0,0 +1,19 @@
1
+ export type UseUncontrolledInput<T> = {
2
+ /** Value for controlled state. */
3
+ value?: T;
4
+ /** Initial value for uncontrolled state. */
5
+ initialValue?: T;
6
+ /** Final value for uncontrolled state when value and initialValue are not provided. */
7
+ finalValue?: T;
8
+ /** Controlled state onChange handler. */
9
+ onChange?: (value: T) => void;
10
+ };
11
+ /**
12
+ * Owns a piece of state that can be driven either by the caller (controlled) or
13
+ * by the component itself (uncontrolled), mirroring the common React
14
+ * controlled/uncontrolled convention.
15
+ *
16
+ * Returns the resolved value, a setter that notifies `onChange` in both modes,
17
+ * and whether the state is currently controlled (`value` was provided).
18
+ */
19
+ export declare function useUncontrolled<T>({ value, initialValue, finalValue, onChange, }: UseUncontrolledInput<T>): [T, (value: T) => void, boolean];
@@ -2,6 +2,7 @@
2
2
  * Public entry point for the `blueprintjs-react-table` package.
3
3
  *
4
4
  * Exports the `BP_Table` component and all public types used in its props,
5
+ * the `withPagination` HOC that layers row pagination on top of `BP_Table`,
5
6
  * as well as the region / focus / selection types used by the focus and
6
7
  * selection APIs.
7
8
  *
@@ -13,5 +14,12 @@
13
14
 
14
15
  export { BP_Table } from './components/BP_Table.js';
15
16
  export type { BP_TableProps } from './components/BP_Table.js';
17
+ export { withPagination } from './components/pagination/withPagination.js';
18
+ export type { BP_PaginatedTableProps, BP_PaginationOptions, } from './components/pagination/withPagination.js';
19
+ export { TablePaginationBar } from './components/pagination/TablePaginationBar.js';
20
+ export type { TablePaginationBarProps } from './components/pagination/TablePaginationBar.js';
21
+ export { DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZE_OPTIONS, } from './components/pagination/constants.js';
22
+ export { DEFAULT_BP_TABLE_FEATURES } from './hooks/use-bp-table-instance.js';
23
+ export type { BP_BodyContextMenuRenderer, BP_MenuContext, } from './components/common/menu-context.js';
16
24
  export * from './types.js';
17
25
  export * from './components/common/region.js';