@mui/x-virtualizer 0.1.0

package/esm/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./useVirtualizer.js";
+export * from "./features/index.js";

package/esm/index.js

@@ -0,0 +1,9 @@
+/**
+ * @mui/x-virtualizer v0.1.0
+ *
+ * @license MIT
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export * from "./useVirtualizer.js";
+export * from "./features/index.js";

package/esm/models/colspan.d.ts

@@ -0,0 +1,13 @@
+import { float, integer } from '@mui/x-internals/types';
+export type ColumnIndex = number;
+export type CellColSpanInfo = {
+  spannedByColSpan: true;
+  rightVisibleCellIndex: ColumnIndex;
+  leftVisibleCellIndex: ColumnIndex;
+} | {
+  spannedByColSpan: false;
+  cellProps: {
+    colSpan: integer;
+    width: float;
+  };
+};

package/esm/models/colspan.js

@@ -0,0 +1 @@
+export {};

package/esm/models/core.d.ts

@@ -0,0 +1,72 @@
+export type Size = {
+  width: number;
+  height: number;
+};
+export declare namespace Size {
+  const EMPTY: {
+    width: number;
+    height: number;
+  };
+  function equals(a: Size, b: Size): boolean;
+}
+export type Row = {
+  [key: string | symbol]: any;
+};
+export type Column = {
+  [key: string | symbol]: any;
+};
+export type ColumnWithWidth = {
+  computedWidth: number;
+} & Column;
+export type RowId = any;
+export type RowEntry = {
+  id: any;
+  model: Row;
+};
+export type PinnedRows = {
+  top: RowEntry[];
+  bottom: RowEntry[];
+};
+export type PinnedColumns = {
+  left: Column[];
+  right: Column[];
+};
+export type FocusedCell = {
+  rowIndex: number;
+  columnIndex: number;
+  id?: any;
+  field?: string;
+};
+export interface ColumnsRenderContext {
+  firstColumnIndex: number;
+  lastColumnIndex: number;
+}
+export interface RenderContext extends ColumnsRenderContext {
+  firstRowIndex: number;
+  lastRowIndex: number;
+}
+export interface GridScrollParams {
+  left: number;
+  top: number;
+  renderContext?: RenderContext;
+}
+export type GridScrollFn = (v: GridScrollParams) => void;
+export type PinnedRowPosition = keyof PinnedRows;
+export type ScrollPosition = {
+  top: number;
+  left: number;
+};
+export declare enum ScrollDirection {
+  NONE = 0,
+  UP = 1,
+  DOWN = 2,
+  LEFT = 3,
+  RIGHT = 4,
+}
+export declare namespace ScrollDirection {
+  function forDelta(dx: number, dy: number): ScrollDirection;
+}
+export type RowRange = {
+  firstRowIndex: number;
+  lastRowIndex: number;
+};

package/esm/models/core.js

@@ -0,0 +1,43 @@
+/* eslint-disable @typescript-eslint/no-redeclare */
+export let Size;
+(function (_Size) {
+  const EMPTY = _Size.EMPTY = {
+    width: 0,
+    height: 0
+  };
+  function equals(a, b) {
+    return a.width === b.width && a.height === b.height;
+  }
+  _Size.equals = equals;
+})(Size || (Size = {})); // TODO
+export let ScrollDirection = /*#__PURE__*/function (ScrollDirection) {
+  ScrollDirection[ScrollDirection["NONE"] = 0] = "NONE";
+  ScrollDirection[ScrollDirection["UP"] = 1] = "UP";
+  ScrollDirection[ScrollDirection["DOWN"] = 2] = "DOWN";
+  ScrollDirection[ScrollDirection["LEFT"] = 3] = "LEFT";
+  ScrollDirection[ScrollDirection["RIGHT"] = 4] = "RIGHT";
+  return ScrollDirection;
+}({});
+(function (_ScrollDirection) {
+  function forDelta(dx, dy) {
+    if (dx === 0 && dy === 0) {
+      return ScrollDirection.NONE;
+    }
+    /* eslint-disable */
+    if (Math.abs(dy) >= Math.abs(dx)) {
+      if (dy > 0) {
+        return ScrollDirection.DOWN;
+      } else {
+        return ScrollDirection.UP;
+      }
+    } else {
+      if (dx > 0) {
+        return ScrollDirection.RIGHT;
+      } else {
+        return ScrollDirection.LEFT;
+      }
+    }
+    /* eslint-enable */
+  }
+  _ScrollDirection.forDelta = forDelta;
+})(ScrollDirection || (ScrollDirection = {}));

package/esm/models/dimensions.d.ts

@@ -0,0 +1,132 @@
+import { Size } from "./core.js";
+export interface DimensionsState {
+  /**
+   * Indicates that the dimensions have been initialized.
+   */
+  isReady: boolean;
+  /**
+   * The root container size.
+   */
+  root: Size;
+  /**
+   * The viewport size including scrollbars.
+   */
+  viewportOuterSize: Size;
+  /**
+   * The viewport size not including scrollbars.
+   */
+  viewportInnerSize: Size;
+  /**
+   * The size of the main content (unpinned rows & columns).
+   */
+  contentSize: Size;
+  /**
+   * The minimum size to display the grid, including all pinned sections and headers.
+   */
+  minimumSize: Size;
+  /**
+   * Indicates if a scroll is currently needed to go from the beginning of the first column to the end of the last column.
+   */
+  hasScrollX: boolean;
+  /**
+   * Indicates if a scroll is currently needed to go from the beginning of the first row to the end of the last row.
+   */
+  hasScrollY: boolean;
+  /**
+   * Size of the scrollbar used to scroll the rows in pixel.
+   * It is defined even when the scrollbar is currently not needed.
+   */
+  scrollbarSize: number;
+  /**
+   * Width of a row.
+   */
+  rowWidth: number;
+  /**
+   * Height of a row.
+   */
+  rowHeight: number;
+  /**
+   * Size of all the visible columns.
+   */
+  columnsTotalWidth: number;
+  /**
+   * Size of left pinned columns.
+   */
+  leftPinnedWidth: number;
+  /**
+   * Size of right pinned columns.
+   */
+  rightPinnedWidth: number;
+  /**
+   * Height of one column header.
+   */
+  headerHeight: number;
+  /**
+   * Height of one column group header.
+   */
+  groupHeaderHeight: number;
+  /**
+   * Height of header filters.
+   */
+  headerFilterHeight: number;
+  /**
+   * Height of all the column headers.
+   */
+  headersTotalHeight: number;
+  /**
+   * Size of the top container.
+   */
+  topContainerHeight: number;
+  /**
+   * Size of the bottom container.
+   */
+  bottomContainerHeight: number;
+}
+/**
+ * The rows total height and positions.
+ */
+export interface RowsMetaState {
+  /**
+   * The grid rows positions.
+   */
+  positions: number[];
+  /**
+   * The sum of all visible grid rows in the current rows.
+   */
+  currentPageTotalHeight: number;
+  /**
+   * The total height of the pinned top rows.
+   */
+  pinnedTopRowsTotalHeight: number;
+  /**
+   * The total height of the pinned bottom rows.
+   */
+  pinnedBottomRowsTotalHeight: number;
+}
+export interface RowVisibilityParams {
+  /**
+   * Whether this row is the first visible or not.
+   */
+  isFirstVisible: boolean;
+  /**
+   * Whether this row is the last visible or not.
+   */
+  isLastVisible: boolean;
+  /**
+   * Index of the row in the current page.
+   * If the pagination is disabled, it will be the index relative to all filtered rows.
+   */
+  indexRelativeToCurrentPage: number;
+}
+export interface RowSpacing {
+  top?: number;
+  bottom?: number;
+}
+export type HeightEntry = {
+  content: number;
+  spacingTop: number;
+  spacingBottom: number;
+  detail: number;
+  autoHeight: boolean;
+  needsFirstMeasurement: boolean;
+};

package/esm/models/dimensions.js

@@ -0,0 +1 @@
+export {};

package/esm/models/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./core.js";
+export * from "./colspan.js";
+export * from "./dimensions.js";
+export * from "./rowspan.js";

package/esm/models/index.js

@@ -0,0 +1,4 @@
+export * from "./core.js";
+export * from "./colspan.js";
+export * from "./dimensions.js";
+export * from "./rowspan.js";

package/esm/models/rowspan.d.ts

@@ -0,0 +1,17 @@
+import { RowId, RowRange } from "./core.js";
+type ColumnIndex = number;
+export interface RowSpanningCaches {
+  spannedCells: Record<RowId, Record<ColumnIndex, number>>;
+  hiddenCells: Record<RowId, Record<ColumnIndex, boolean>>;
+  /**
+   * For each hidden cell, it contains the row index corresponding to the cell that is
+   * the origin of the hidden cell. i.e. the cell which is spanned.
+   * Used by the virtualization to properly keep the spanned cells in view.
+   */
+  hiddenCellOriginMap: Record<number, Record<ColumnIndex, number>>;
+}
+export interface RowSpanningState {
+  caches: RowSpanningCaches;
+  processedRange: RowRange;
+}
+export {};

package/esm/models/rowspan.js

@@ -0,0 +1 @@
+export {};

package/esm/package.json

@@ -0,0 +1 @@
+{"type":"module","sideEffects":false}

package/esm/useVirtualizer.d.ts

@@ -0,0 +1,193 @@
+import * as React from 'react';
+import { integer, RefObject } from '@mui/x-internals/types';
+import { Store } from '@mui/x-internals/store';
+import { Colspan } from "./features/colspan.js";
+import { Dimensions } from "./features/dimensions.js";
+import { Rowspan } from "./features/rowspan.js";
+import { Virtualization } from "./features/virtualization.js";
+import type { RowId } from "./models/core.js";
+import type { HeightEntry, RowSpacing, RowVisibilityParams } from "./models/dimensions.js";
+import { ColumnWithWidth, FocusedCell, Size, PinnedRows, PinnedColumns, RenderContext, Row, RowEntry } from "./models/index.js";
+export type Virtualizer = ReturnType<typeof useVirtualizer>;
+export type VirtualScrollerCompat = Virtualization.State['getters'];
+export type BaseState = Virtualization.State & Dimensions.State;
+export type VirtualizerParams = {
+  scrollbarSize?: number;
+  dimensions: {
+    rowHeight: number;
+    headerHeight: number;
+    groupHeaderHeight: number;
+    headerFilterHeight: number;
+    columnsTotalWidth: number;
+    headersTotalHeight: number;
+    leftPinnedWidth: number;
+    rightPinnedWidth: number;
+  };
+  initialState?: {
+    scroll?: {
+      top: number;
+      left: number;
+    };
+    dimensions?: Partial<Dimensions.State['dimensions']>;
+    rowSpanning?: Rowspan.State['rowSpanning'];
+    virtualization?: Partial<Virtualization.State['virtualization']>;
+  };
+  isRtl: boolean;
+  /** current page rows */
+  rows: RowEntry[];
+  /** current page range */
+  range: {
+    firstRowIndex: integer;
+    lastRowIndex: integer;
+  } | null;
+  rowIdToIndexMap: Map<RowId, number>;
+  rowCount: integer;
+  columns: ColumnWithWidth[];
+  pinnedRows: PinnedRows;
+  pinnedColumns: PinnedColumns;
+  refs: {
+    container: RefObject<HTMLDivElement | null>;
+    scroller: RefObject<HTMLDivElement | null>;
+    scrollbarVertical: RefObject<HTMLDivElement | null>;
+    scrollbarHorizontal: RefObject<HTMLDivElement | null>;
+  };
+  hasColSpan: boolean;
+  contentHeight: number;
+  minimalContentHeight: number | string;
+  autoHeight: boolean;
+  getRowHeight?: (row: RowEntry) => number | null | undefined | 'auto';
+  /**
+   * Function that returns the estimated height for a row.
+   * Only works if dynamic row height is used.
+   * Once the row height is measured this value is discarded.
+   * @param rowEntry
+   * @returns The estimated row height value. If `null` or `undefined` then the default row height, based on the density, is applied.
+   */
+  getEstimatedRowHeight?: (rowEntry: RowEntry) => number | null;
+  /**
+   * Function that allows to specify the spacing between rows.
+   * @param rowEntry
+   * @param visibility With all properties from [[RowVisibilityParams]].
+   * @returns The row spacing values.
+   */
+  getRowSpacing?: (rowEntry: RowEntry, visibility: RowVisibilityParams) => RowSpacing;
+  /** Update the row height values before they're used.
+   * Used to add detail panel heights.
+   * @param entry
+   * @param rowEntry
+   */
+  applyRowHeight?: (entry: HeightEntry, rowEntry: RowEntry) => void;
+  virtualizeColumnsWithAutoRowHeight?: boolean;
+  resizeThrottleMs: number;
+  onResize?: (lastSize: Size) => void;
+  onWheel?: (event: React.WheelEvent) => void;
+  onTouchMove?: (event: React.TouchEvent) => void;
+  onRenderContextChange?: (c: RenderContext) => void;
+  onScrollChange?: (scrollPosition: {
+    top: number;
+    left: number;
+  }, nextRenderContext: RenderContext) => void;
+  focusedVirtualCell: () => FocusedCell | null;
+  rowBufferPx: number;
+  columnBufferPx: number;
+  scrollReset?: any;
+  getColspan: (rowId: RowId, column: ColumnWithWidth, columnIndex: integer) => number;
+  renderRow: (params: {
+    id: any;
+    model: Row;
+    rowIndex: number;
+    offsetLeft: number;
+    columnsTotalWidth: number;
+    baseRowHeight: number | 'auto';
+    columns: ColumnWithWidth[];
+    firstColumnIndex: number;
+    lastColumnIndex: number;
+    focusedColumnIndex: number | undefined;
+    isFirstVisible: boolean;
+    isLastVisible: boolean;
+    isVirtualFocusRow: boolean;
+    showBottomBorder: boolean;
+  }) => React.ReactElement;
+  renderInfiniteLoadingTrigger: (id: any) => React.ReactElement;
+};
+export declare const useVirtualizer: (params: VirtualizerParams) => {
+  store: Store<Dimensions.State & Virtualization.State & Colspan.State & Rowspan.State>;
+  api: {
+    updateDimensions: () => void;
+    debouncedUpdateDimensions: ((() => void) & import("@mui/x-internals/throttle/throttle").Cancelable) | undefined;
+    rowsMeta: {
+      getRowHeight: (rowId: RowId) => any;
+      setLastMeasuredRowIndex: (index: number) => void;
+      storeRowHeightMeasurement: (id: RowId, height: number) => void;
+      hydrateRowsMeta: () => void;
+      observeRowHeight: (element: Element, rowId: RowId) => () => void | undefined;
+      rowHasAutoHeight: (id: RowId) => any;
+      getRowHeightEntry: (rowId: RowId) => any;
+      getLastMeasuredRowIndex: () => number;
+      resetRowHeights: () => void;
+    };
+  } & {
+    getters: {
+      setPanels: React.Dispatch<React.SetStateAction<Readonly<Map<any, React.ReactNode>>>>;
+      getRows: (rowParams: {
+        rows?: RowEntry[];
+        position?: import("./models/index.js").PinnedRowPosition;
+        renderContext?: RenderContext;
+      } | undefined, unstable_rowTree: Record<RowId, any>) => React.ReactNode[];
+      getContainerProps: () => {
+        ref: React.RefObject<HTMLDivElement | null>;
+      };
+      getScrollerProps: () => {
+        ref: React.RefObject<HTMLDivElement | null>;
+        onScroll: () => void;
+        onWheel: ((event: React.WheelEvent) => void) | undefined;
+        onTouchMove: ((event: React.TouchEvent) => void) | undefined;
+        style: React.CSSProperties;
+        role: string;
+        tabIndex: number | undefined;
+      };
+      getContentProps: () => {
+        style: React.CSSProperties;
+        role: string;
+        ref: (node: HTMLDivElement | null) => void;
+      };
+      getRenderZoneProps: () => {
+        role: string;
+      };
+      getScrollbarVerticalProps: () => {
+        ref: React.RefObject<HTMLDivElement | null>;
+        scrollPosition: React.RefObject<{
+          top: number;
+          left: number;
+        }>;
+      };
+      getScrollbarHorizontalProps: () => {
+        ref: React.RefObject<HTMLDivElement | null>;
+        scrollPosition: React.RefObject<{
+          top: number;
+          left: number;
+        }>;
+      };
+      getScrollAreaProps: () => {
+        scrollPosition: React.RefObject<{
+          top: number;
+          left: number;
+        }>;
+      };
+    };
+    useVirtualization: () => BaseState;
+    setPanels: React.Dispatch<React.SetStateAction<Readonly<Map<any, React.ReactNode>>>>;
+    forceUpdateRenderContext: () => void;
+    getCellColSpanInfo: (rowId: RowId, columnIndex: integer) => import("./models/index.js").CellColSpanInfo;
+    calculateColSpan: (rowId: RowId, minFirstColumn: integer, maxLastColumn: integer, columns: ColumnWithWidth[]) => void;
+    getHiddenCellsOrigin: () => Record<RowId, Record<number, number>>;
+  } & {
+    resetColSpan: () => void;
+    getCellColSpanInfo: (rowId: RowId, columnIndex: integer) => import("./models/index.js").CellColSpanInfo | undefined;
+    calculateColSpan: (rowId: RowId, minFirstColumn: integer, maxLastColumn: integer, columns: ColumnWithWidth[]) => void;
+  } & {
+    getHiddenCellsOrigin: () => Record<number, Record<number, number>>;
+  } & {
+    getViewportPageSize: () => number;
+  };
+};

package/esm/useVirtualizer.js

@@ -0,0 +1,26 @@
+import useLazyRef from '@mui/utils/useLazyRef';
+import { Store } from '@mui/x-internals/store';
+import { Colspan } from "./features/colspan.js";
+import { Dimensions } from "./features/dimensions.js";
+import { Keyboard } from "./features/keyboard.js";
+import { Rowspan } from "./features/rowspan.js";
+import { Virtualization } from "./features/virtualization.js";
+
+/* eslint-disable jsdoc/require-param-type */
+/* eslint-disable jsdoc/require-param-description */
+/* eslint-disable jsdoc/require-returns-type */
+
+const FEATURES = [Dimensions, Virtualization, Colspan, Rowspan, Keyboard];
+export const useVirtualizer = params => {
+  const store = useLazyRef(() => {
+    return new Store(FEATURES.map(f => f.initialize(params)).reduce((state, partial) => Object.assign(state, partial), {}));
+  }).current;
+  const api = {};
+  for (const feature of FEATURES) {
+    Object.assign(api, feature.use(store, params, api));
+  }
+  return {
+    store,
+    api
+  };
+};

package/features/colspan.d.ts

@@ -0,0 +1,28 @@
+import { Store } from '@mui/x-internals/store';
+import type { integer } from '@mui/x-internals/types';
+import type { BaseState, VirtualizerParams } from "../useVirtualizer.js";
+import type { ColumnWithWidth, RowId } from "../models/index.js";
+import type { CellColSpanInfo } from "../models/colspan.js";
+import { Virtualization } from "./virtualization.js";
+type ColumnIndex = number;
+type ColspanMap = Map<RowId, Record<ColumnIndex, CellColSpanInfo>>;
+export declare const Colspan: {
+  initialize: typeof initializeState;
+  use: typeof useColspan;
+  selectors: {};
+};
+export declare namespace Colspan {
+  type State = {
+    colspanMap: ColspanMap;
+  };
+  type API = ReturnType<typeof useColspan>;
+}
+declare function initializeState(_params: VirtualizerParams): {
+  colspanMap: Map<any, any>;
+};
+declare function useColspan(store: Store<BaseState & Colspan.State>, params: VirtualizerParams, api: Virtualization.API): {
+  resetColSpan: () => void;
+  getCellColSpanInfo: (rowId: RowId, columnIndex: integer) => CellColSpanInfo | undefined;
+  calculateColSpan: (rowId: RowId, minFirstColumn: integer, maxLastColumn: integer, columns: ColumnWithWidth[]) => void;
+};
+export {};

package/features/colspan.js

@@ -0,0 +1,94 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Colspan = void 0;
+var _useEventCallback = _interopRequireDefault(require("@mui/utils/useEventCallback"));
+/* eslint-disable import/export, @typescript-eslint/no-redeclare */
+
+const selectors = {};
+const Colspan = exports.Colspan = {
+  initialize: initializeState,
+  use: useColspan,
+  selectors
+};
+function initializeState(_params) {
+  return {
+    colspanMap: new Map()
+  };
+}
+function useColspan(store, params, api) {
+  const resetColSpan = () => {
+    store.state.colspanMap = new Map();
+  };
+  const getCellColSpanInfo = (rowId, columnIndex) => {
+    return store.state.colspanMap.get(rowId)?.[columnIndex];
+  };
+
+  // Calculate `colSpan` for each cell in the row
+  const calculateColSpan = (0, _useEventCallback.default)((rowId, minFirstColumn, maxLastColumn, columns) => {
+    for (let i = minFirstColumn; i < maxLastColumn; i += 1) {
+      const cellProps = calculateCellColSpan(store.state.colspanMap, i, rowId, minFirstColumn, maxLastColumn, columns, params.getColspan);
+      if (cellProps.colSpan > 1) {
+        i += cellProps.colSpan - 1;
+      }
+    }
+  });
+  api.calculateColSpan = calculateColSpan;
+  return {
+    resetColSpan,
+    getCellColSpanInfo,
+    calculateColSpan
+  };
+}
+function calculateCellColSpan(lookup, columnIndex, rowId, minFirstColumnIndex, maxLastColumnIndex, columns, getColspan) {
+  const columnsLength = columns.length;
+  const column = columns[columnIndex];
+  const colSpan = getColspan(rowId, column, columnIndex);
+  if (!colSpan || colSpan === 1) {
+    setCellColSpanInfo(lookup, rowId, columnIndex, {
+      spannedByColSpan: false,
+      cellProps: {
+        colSpan: 1,
+        width: column.computedWidth
+      }
+    });
+    return {
+      colSpan: 1
+    };
+  }
+  let width = column.computedWidth;
+  for (let j = 1; j < colSpan; j += 1) {
+    const nextColumnIndex = columnIndex + j;
+    // Cells should be spanned only within their column section (left-pinned, right-pinned and unpinned).
+    if (nextColumnIndex >= minFirstColumnIndex && nextColumnIndex < maxLastColumnIndex) {
+      const nextColumn = columns[nextColumnIndex];
+      width += nextColumn.computedWidth;
+      setCellColSpanInfo(lookup, rowId, columnIndex + j, {
+        spannedByColSpan: true,
+        rightVisibleCellIndex: Math.min(columnIndex + colSpan, columnsLength - 1),
+        leftVisibleCellIndex: columnIndex
+      });
+    }
+    setCellColSpanInfo(lookup, rowId, columnIndex, {
+      spannedByColSpan: false,
+      cellProps: {
+        colSpan,
+        width
+      }
+    });
+  }
+  return {
+    colSpan
+  };
+}
+function setCellColSpanInfo(colspanMap, rowId, columnIndex, cellColSpanInfo) {
+  let columnInfo = colspanMap.get(rowId);
+  if (!columnInfo) {
+    columnInfo = {};
+    colspanMap.set(rowId, columnInfo);
+  }
+  columnInfo[columnIndex] = cellColSpanInfo;
+}