@mui/x-virtualizer 0.1.0

package/index.d.ts

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

package/index.js

@@ -0,0 +1,34 @@
+/**
+ * @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.
+ */
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _useVirtualizer = require("./useVirtualizer");
+Object.keys(_useVirtualizer).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _useVirtualizer[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _useVirtualizer[key];
+    }
+  });
+});
+var _features = require("./features");
+Object.keys(_features).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _features[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _features[key];
+    }
+  });
+});

package/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/models/colspan.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/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/models/core.js

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Size = exports.ScrollDirection = void 0;
+/* eslint-disable @typescript-eslint/no-redeclare */
+let Size = exports.Size = void 0;
+(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 || (exports.Size = Size = {})); // TODO
+let ScrollDirection = exports.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 || (exports.ScrollDirection = ScrollDirection = {}));

package/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/models/dimensions.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/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/models/index.js

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _core = require("./core");
+Object.keys(_core).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _core[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _core[key];
+    }
+  });
+});
+var _colspan = require("./colspan");
+Object.keys(_colspan).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _colspan[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _colspan[key];
+    }
+  });
+});
+var _dimensions = require("./dimensions");
+Object.keys(_dimensions).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _dimensions[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _dimensions[key];
+    }
+  });
+});
+var _rowspan = require("./rowspan");
+Object.keys(_rowspan).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _rowspan[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _rowspan[key];
+    }
+  });
+});

package/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/models/rowspan.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@mui/x-virtualizer",
+  "version": "0.1.0",
+  "author": "MUI Team",
+  "description": "MUI virtualization library",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mui/mui-x/issues"
+  },
+  "homepage": "https://mui.com",
+  "sideEffects": false,
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/mui-org"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "react-component",
+    "virtualization"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mui/mui-x.git",
+    "directory": "packages/x-virtualizer"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.27.4",
+    "@mui/x-internals": "8.9.2"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "private": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "import": {
+        "types": "./esm/index.d.ts",
+        "default": "./esm/index.js"
+      }
+    },
+    "./*": {
+      "require": {
+        "types": "./*/index.d.ts",
+        "default": "./*/index.js"
+      },
+      "import": {
+        "types": "./esm/*/index.d.ts",
+        "default": "./esm/*/index.js"
+      }
+    },
+    "./esm": null,
+    "./modern": null
+  },
+  "types": "./index.d.ts"
+}

package/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/useVirtualizer.js

@@ -0,0 +1,33 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useVirtualizer = void 0;
+var _useLazyRef = _interopRequireDefault(require("@mui/utils/useLazyRef"));
+var _store = require("@mui/x-internals/store");
+var _colspan = require("./features/colspan");
+var _dimensions = require("./features/dimensions");
+var _keyboard = require("./features/keyboard");
+var _rowspan = require("./features/rowspan");
+var _virtualization = require("./features/virtualization");
+/* eslint-disable jsdoc/require-param-type */
+/* eslint-disable jsdoc/require-param-description */
+/* eslint-disable jsdoc/require-returns-type */
+
+const FEATURES = [_dimensions.Dimensions, _virtualization.Virtualization, _colspan.Colspan, _rowspan.Rowspan, _keyboard.Keyboard];
+const useVirtualizer = params => {
+  const store = (0, _useLazyRef.default)(() => {
+    return new _store.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
+  };
+};
+exports.useVirtualizer = useVirtualizer;