virtua 0.51.3 → 0.52.0

package/lib/react/VGrid.d.ts

@@ -1,14 +1,6 @@
-import { default as React, JSX, CSSProperties, ReactNode, Ref } from 'react';
+import { ReactElement, ReactNode, Ref } from 'react';
+import { VGridAxis, VGridCell, VGridSize, VGridSpan, VGridScrollToIndexOpts } from '../core/index.js';
 import { ViewportComponentAttributes } from './types.js';
-/**
- * Props of customized cell component for {@link VGrid}.
- */
-export interface CustomCellComponentProps {
-    style: CSSProperties;
-    children: ReactNode;
-}
-export type CustomCellComponent = React.ForwardRefExoticComponent<React.PropsWithoutRef<CustomCellComponentProps> & React.RefAttributes<any>>;
-export type VGridItemResize = readonly [index: number, size: number];
 /**
  * Methods of {@link VGrid}.
  */
@@ -16,11 +8,11 @@ export interface VGridHandle {
     /**
      * Get current scrollTop.
      */
-    readonly scrollTop: number;
+    readonly verticalScrollOffset: number;
     /**
      * Get current scrollLeft. Always positive even in RTL.
      */
-    readonly scrollLeft: number;
+    readonly horizontalScrollOffset: number;
     /**
      * Get current scrollHeight.
      */
@@ -39,128 +31,161 @@ export interface VGridHandle {
     readonly viewportWidth: number;
     /**
      * Find nearest row index from offset.
-     * @param offset offset in pixels from the start of the scroll container
+     * @param offset offset in pixels from the top of the scroll container
      */
-    findRowIndex: (offset: number) => number;
+    findRowIndex(offset: number): number;
     /**
-     * Find nearest col index from offset.
+     * Find nearest column index from offset.
      * @param offset offset in pixels from the start of the scroll container
      */
-    findColIndex: (offset: number) => number;
+    findColIndex(offset: number): number;
     /**
-     * Get row offset from start.
+     * Get offset of the row from the top.
      * @param index index of row
      */
     getRowOffset(index: number): number;
     /**
-     * Get col offset from start.
-     * @param index index of col
+     * Get offset of the column from the start.
+     * @param index index of column
      */
     getColOffset(index: number): number;
     /**
-     * Get row size.
+     * Get size of the row.
      * @param index index of row
      */
     getRowSize(index: number): number;
     /**
-     * Get col size.
-     * @param index index of col
+     * Get size of the column.
+     * @param index index of column
      */
     getColSize(index: number): number;
     /**
-     * Resize individual columns.
-     * @param cols array of `[index, size]` to update column sizes
-     */
-    resizeCols(cols: VGridItemResize[]): void;
-    /**
-     * Resize individual rows.
-     * @param rows array of `[index, size]` to update row sizes
+     * Scroll to the cell specified by the indexes. The cell is not hidden behind the rows and the columns sticking over it.
+     * @param opts the indexes of the cell and the options. See {@link VGridScrollToIndexOpts}.
      */
-    resizeRows(rows: VGridItemResize[]): void;
+    scrollToIndex(opts: VGridScrollToIndexOpts): void;
     /**
-     * Scroll to the item specified by index.
-     * @param indexX horizontal index of item
-     * @param indexY vertical index of item
+     * Scroll to the given offsets from the top/start of the scroll container.
+     * @param offset the offsets. The axis whose offset is omitted is not scrolled.
      */
-    scrollToIndex(indexX?: number, indexY?: number): void;
+    scrollTo(offset: {
+        vertical?: number;
+        horizontal?: number;
+    }): void;
     /**
-     * Scroll to the given offset.
-     * @param offsetX offset from left
-     * @param offsetY offset from top
+     * Scroll by the given offsets from the current position.
+     * @param offset the offsets. The axis whose offset is omitted is not scrolled.
      */
-    scrollTo(offsetX?: number, offsetY?: number): void;
-    /**
-     * Scroll by the given offset.
-     * @param offsetX horizontal offset from current position
-     * @param offsetY vertical offset from current position
-     */
-    scrollBy(offsetX?: number, offsetY?: number): void;
+    scrollBy(offset: {
+        vertical?: number;
+        horizontal?: number;
+    }): void;
 }
 /**
  * Props of {@link VGrid}.
  */
-export interface VGridProps extends ViewportComponentAttributes {
+export interface VGridProps<R = number, C = number> extends Omit<ViewportComponentAttributes, "role"> {
+    /**
+     * A function to create cell elements rendered by this component.
+     * @param row the item of {@link VGridProps.rows} at the row of the cell, or the row index if {@link VGridProps.rows} is a number
+     * @param col the item of {@link VGridProps.cols} at the column of the cell, or the column index if {@link VGridProps.cols} is a number
+     * @param cell the row index and the column index of the cell
+     */
+    children: (row: R, col: C, cell: Readonly<VGridCell>) => ReactNode;
+    /**
+     * The rows of the grid. See {@link VGridAxis} for the accepted values.
+     */
+    rows: VGridAxis<R>;
+    /**
+     * The columns of the grid. See {@link VGridAxis} for the accepted values.
+     */
+    cols: VGridAxis<C>;
+    /**
+     * The heights of the rows. See {@link VGridSize} for the accepted values.
+     */
+    rowHeight: NoInfer<VGridSize<R>>;
+    /**
+     * The widths of the columns. See {@link VGridSize} for the accepted values.
+     */
+    colWidth: NoInfer<VGridSize<C>>;
+    /**
+     * The number of the leading rows pinned to the start, which are the column headers (`role="columnheader"`).
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    headerRows?: number;
+    /**
+     * Indexes of the rows which start sections. A section lasts until the next section row or the footer rows, and its first row sticks below the header rows while the section is scrolled through.
+     *
+     * **The section rows are rendered over the other cells while they stick, so give them an opaque background.**
+     */
+    sectionRows?: readonly number[];
     /**
-     * A function to create elements rendered by this component.
+     * The number of the trailing rows pinned to the end.
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
      */
-    children: (arg: {
-        /**
-         * row index of cell
-         */
-        rowIndex: number;
-        /**
-         * column index of cell
-         */
-        colIndex: number;
-    }) => ReactNode;
+    footerRows?: number;
     /**
-     * Total row length of grid.
+     * The number of the leading columns pinned to the start, the last of which is the row header (`role="rowheader"`).
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
      */
-    row: number;
+    headerCols?: number;
     /**
-     * Total column length of grid.
+     * The number of the trailing columns pinned to the end.
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
      */
-    col: number;
+    footerCols?: number;
     /**
-     * Cell height hint for unmeasured items. It's recommended to specify this prop if item sizes are fixed and known, or much larger than the defaultValue. It will help to reduce scroll jump when items are measured.
-     * @defaultValue 40
+     * Cells merged over multiple rows and/or columns. See {@link VGridSpan} for the accepted values.
+     *
+     * The cell at the origin is stretched over the merged area, and the other cells in it are not rendered. Spans must not overlap each other or cross the boundaries of the pinned rows/columns or the sections. A spanning cell is not measured for `"auto"` sizes on the axes it spans, and doesn't enlarge those tracks.
      */
-    cellHeight?: number;
+    spans?: readonly VGridSpan[];
     /**
-     * Cell width hint for unmeasured items. It's recommended to specify this prop if item sizes are fixed and known, or much larger than the defaultValue. It will help to reduce scroll jump when items are measured.
-     * @defaultValue 100
+     * List of cells that should be always mounted, even when off screen.
      */
-    cellWidth?: number;
+    keepMounted?: readonly VGridCell[];
     /**
-     * Extra item space in pixels to render before/after the viewport. The minimum value is 0. Lower value will give better performance but you can increase to avoid showing blank items in fast scrolling.
+     * Extra space in pixels to render before/after the viewport. The minimum value is 0. Lower value will give better performance but you can increase to avoid showing blank cells in fast scrolling.
      * @defaultValue 200
      */
     bufferSize?: number;
     /**
-     * A prop for SSR. If set, the specified amount of rows will be mounted in the initial rendering regardless of the container size until hydrated.
+     * The gap between the rows and the columns in pixels, which is not included in the sizes. Must not be changed after mount.
+     * @defaultValue 0
      */
-    ssrRowCount?: number;
+    gap?: number;
     /**
-     * A prop for SSR. If set, the specified amount of cols will be mounted in the initial rendering regardless of the container size until hydrated.
+     * The header cell of the sorted column or row, and the sort order (`aria-sort`).
      */
-    ssrColCount?: number;
+    ariaSort?: VGridCell & {
+        order: "ascending" | "descending" | "other";
+    };
     /**
-     * Component or element type for cell element. This component will get {@link CustomCellComponentProps} as props.
-     * @defaultValue "div"
+     * Callback invoked whenever the vertical scroll offset changes.
+     * @param offset Current scrollTop.
      */
-    item?: keyof JSX.IntrinsicElements | CustomCellComponent;
-    /** Reference to the rendered DOM element (the one that scrolls). */
-    domRef?: Ref<HTMLDivElement>;
+    onVerticalScroll?: (offset: number) => void;
     /**
-     * Callback invoked whenever scroll offset changes.
+     * Callback invoked whenever the horizontal scroll offset changes.
+     * @param offset Current scrollLeft. Always positive even in RTL.
      */
-    onScroll?: (offset: number) => void;
+    onHorizontalScroll?: (offset: number) => void;
     /**
      * Callback invoked when scrolling stops.
      */
     onScrollEnd?: () => void;
 }
 /**
- * Virtualized grid component. See {@link VGridProps} and {@link VGridHandle}.
+ * Virtualized grid component for tabular data. See {@link VGridProps} and {@link VGridHandle}.
  */
-export declare const VGrid: React.ForwardRefExoticComponent<VGridProps & React.RefAttributes<VGridHandle>>;
+export declare const VGrid: <R = number, C = number>(props: VGridProps<R, C> & {
+    ref?: Ref<VGridHandle>;
+}) => ReactElement;

package/lib/react/index.d.ts

@@ -4,6 +4,7 @@ export { Virtualizer } from './Virtualizer.js';
 export type { VirtualizerProps, VirtualizerHandle } from './Virtualizer.js';
 export { WindowVirtualizer } from './WindowVirtualizer.js';
 export type { WindowVirtualizerProps, WindowVirtualizerHandle, } from './WindowVirtualizer.js';
-export { VGrid as experimental_VGrid } from './VGrid.js';
-export type { VGridItemResize, VGridProps, VGridHandle, CustomCellComponent, CustomCellComponentProps, } from './VGrid.js';
+export { VGrid } from './VGrid.js';
+export type { VGridProps, VGridHandle } from './VGrid.js';
+export type { VGridSize, VGridSpan } from '../core/index.js';
 export type * from './types.js';

package/lib/solid/VGrid.d.ts

@@ -0,0 +1,193 @@
+import { JSX } from 'solid-js';
+import { VGridScrollToIndexOpts, VGridAxis, VGridCell, VGridSize, VGridSpan } from '../core/index.js';
+import { ViewportComponentAttributes } from './types.js';
+/**
+ * Methods of {@link VGrid}.
+ */
+export interface VGridHandle {
+    /**
+     * Get current scrollTop.
+     */
+    readonly verticalScrollOffset: number;
+    /**
+     * Get current scrollLeft. Always positive even in RTL.
+     */
+    readonly horizontalScrollOffset: number;
+    /**
+     * Get current scrollHeight.
+     */
+    readonly scrollHeight: number;
+    /**
+     * Get current scrollWidth.
+     */
+    readonly scrollWidth: number;
+    /**
+     * Get current clientHeight.
+     */
+    readonly viewportHeight: number;
+    /**
+     * Get current clientWidth.
+     */
+    readonly viewportWidth: number;
+    /**
+     * Find nearest row index from offset.
+     * @param offset offset in pixels from the top of the scroll container
+     */
+    findRowIndex(offset: number): number;
+    /**
+     * Find nearest column index from offset.
+     * @param offset offset in pixels from the start of the scroll container
+     */
+    findColIndex(offset: number): number;
+    /**
+     * Get offset of the row from the top.
+     * @param index index of row
+     */
+    getRowOffset(index: number): number;
+    /**
+     * Get offset of the column from the start.
+     * @param index index of column
+     */
+    getColOffset(index: number): number;
+    /**
+     * Get size of the row.
+     * @param index index of row
+     */
+    getRowSize(index: number): number;
+    /**
+     * Get size of the column.
+     * @param index index of column
+     */
+    getColSize(index: number): number;
+    /**
+     * Scroll to the cell specified by the indexes. The cell is not hidden behind the rows and the columns sticking over it.
+     * @param opts the indexes of the cell and the options. See {@link VGridScrollToIndexOpts}.
+     */
+    scrollToIndex(opts: VGridScrollToIndexOpts): void;
+    /**
+     * Scroll to the given offsets from the top/start of the scroll container.
+     * @param offset the offsets. The axis whose offset is omitted is not scrolled.
+     */
+    scrollTo(offset: {
+        vertical?: number;
+        horizontal?: number;
+    }): void;
+    /**
+     * Scroll by the given offsets from the current position.
+     * @param offset the offsets. The axis whose offset is omitted is not scrolled.
+     */
+    scrollBy(offset: {
+        vertical?: number;
+        horizontal?: number;
+    }): void;
+}
+/**
+ * Props of {@link VGrid}.
+ */
+export interface VGridProps<R = number, C = number> extends Omit<ViewportComponentAttributes, "role"> {
+    /**
+     * Get reference to {@link VGridHandle}.
+     */
+    ref?: VGridHandle | ((handle?: VGridHandle) => void);
+    /**
+     * A function to create cell elements rendered by this component.
+     * @param row the item of {@link VGridProps.rows} at the row of the cell, or the row index if {@link VGridProps.rows} is a number
+     * @param col the item of {@link VGridProps.cols} at the column of the cell, or the column index if {@link VGridProps.cols} is a number
+     * @param cell the row index and the column index of the cell
+     */
+    children: (row: R, col: C, cell: Readonly<VGridCell>) => JSX.Element;
+    /**
+     * The rows of the grid. See {@link VGridAxis} for the accepted values.
+     */
+    rows: VGridAxis<R>;
+    /**
+     * The columns of the grid. See {@link VGridAxis} for the accepted values.
+     */
+    cols: VGridAxis<C>;
+    /**
+     * The heights of the rows. See {@link VGridSize} for the accepted values.
+     */
+    rowHeight: NoInfer<VGridSize<R>>;
+    /**
+     * The widths of the columns. See {@link VGridSize} for the accepted values.
+     */
+    colWidth: NoInfer<VGridSize<C>>;
+    /**
+     * The number of the leading rows pinned to the start, which are the column headers (`role="columnheader"`).
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    headerRows?: number;
+    /**
+     * Indexes of the rows which start sections. A section lasts until the next section row or the footer rows, and its first row sticks below the header rows while the section is scrolled through.
+     *
+     * **The section rows are rendered over the other cells while they stick, so give them an opaque background.**
+     */
+    sectionRows?: readonly number[];
+    /**
+     * The number of the trailing rows pinned to the end.
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    footerRows?: number;
+    /**
+     * The number of the leading columns pinned to the start, the last of which is the row header (`role="rowheader"`).
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    headerCols?: number;
+    /**
+     * The number of the trailing columns pinned to the end.
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    footerCols?: number;
+    /**
+     * Cells merged over multiple rows and/or columns. See {@link VGridSpan} for the accepted values.
+     *
+     * The cell at the origin is stretched over the merged area, and the other cells in it are not rendered. Spans must not overlap each other or cross the boundaries of the pinned rows/columns or the sections. A spanning cell is not measured for `"auto"` sizes on the axes it spans, and doesn't enlarge those tracks.
+     */
+    spans?: readonly VGridSpan[];
+    /**
+     * List of cells that should be always mounted, even when off screen.
+     */
+    keepMounted?: readonly VGridCell[];
+    /**
+     * Extra space in pixels to render before/after the viewport. The minimum value is 0. Lower value will give better performance but you can increase to avoid showing blank cells in fast scrolling.
+     * @defaultValue 200
+     */
+    bufferSize?: number;
+    /**
+     * The gap between the rows and the columns in pixels, which is not included in the sizes. Must not be changed after mount.
+     * @defaultValue 0
+     */
+    gap?: number;
+    /**
+     * The header cell of the sorted column or row, and the sort order (`aria-sort`).
+     */
+    ariaSort?: VGridCell & {
+        order: "ascending" | "descending" | "other";
+    };
+    /**
+     * Callback invoked whenever the vertical scroll offset changes.
+     * @param offset Current scrollTop.
+     */
+    onVerticalScroll?: (offset: number) => void;
+    /**
+     * Callback invoked whenever the horizontal scroll offset changes.
+     * @param offset Current scrollLeft. Always positive even in RTL.
+     */
+    onHorizontalScroll?: (offset: number) => void;
+    /**
+     * Callback invoked when scrolling stops.
+     */
+    onScrollEnd?: () => void;
+}
+/**
+ * Virtualized grid component for tabular data. See {@link VGridProps} and {@link VGridHandle}.
+ */
+export declare const VGrid: <R = number, C = number>(props: VGridProps<R, C>) => JSX.Element;