@are-visual/virtual-table 0.0.1

package/index.d.ts

@@ -0,0 +1,311 @@
+import { DetailedHTMLProps, HTMLAttributes, Key, ReactNode, TdHTMLAttributes, RefObject, ReactElement, FC, CSSProperties, Ref, RefAttributes } from 'react';
+
+type ScrollElement = HTMLElement | Window;
+
+type FixedType = 'left' | 'right';
+declare function isValidFixedLeft(fixed: unknown): fixed is "left";
+declare function isValidFixedRight(fixed: unknown): fixed is "right";
+declare function isValidFixed(fixed: unknown): fixed is "left" | "right";
+
+type AnyObject = Record<string, any>;
+type OnRowType<T = any> = (record: T, index: number) => Omit<DetailedHTMLProps<HTMLAttributes<HTMLTableRowElement>, HTMLTableRowElement>, 'children' | 'ref'>;
+
+type AlignType = 'left' | 'right' | 'center';
+interface ColumnExtra {
+}
+interface ColumnTypeCommon<T> extends ColumnExtra {
+    className?: string;
+    /** 表头列合并，设置为 0 时，不渲染 */
+    colSpan?: number;
+    title?: ReactNode;
+    align?: AlignType;
+    minWidth?: number;
+    width?: string | number;
+    fixed?: FixedType;
+    render?: (value: any, record: T, index: number) => ReactNode;
+    onHeaderCell?: (column: ColumnType<any>, index: number) => HTMLAttributes<any> & TdHTMLAttributes<any>;
+    onCell?: (data: T, index: number) => HTMLAttributes<any> & TdHTMLAttributes<any>;
+}
+type ColumnTypeWithKey<T> = ColumnTypeCommon<T> & {
+    key: Key;
+    [key: string]: unknown;
+};
+type ColumnTypeWithDataIndex<T> = ColumnTypeCommon<T> & {
+    dataIndex: keyof T | (string & {});
+    [key: string]: unknown;
+};
+type ColumnType<T> = ColumnTypeWithKey<T> | ColumnTypeWithDataIndex<T>;
+type ColumnDescriptor<T = any> = {
+    key: Key;
+    type: 'blank';
+    width: number;
+} | {
+    key: Key;
+    type: 'normal';
+    column: ColumnType<T>;
+};
+interface InnerColumnDescriptor<T> {
+    descriptor: ColumnDescriptor<T>[];
+    columns: ColumnType<T>[];
+}
+
+interface NecessaryProps<T> {
+    dataSource: T[];
+    columns: ColumnType<T>[];
+    rowKey: keyof T | (string & {});
+}
+
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+interface MiddlewareContext<T> extends Readonly<NecessaryProps<T>> {
+    readonly estimatedRowHeight: number;
+    readonly rootRef: RefObject<HTMLDivElement>;
+    readonly headerWrapperRef: RefObject<HTMLDivElement>;
+    readonly bodyWrapperRef: RefObject<HTMLDivElement>;
+    readonly bodyRootRef: RefObject<HTMLTableElement>;
+    readonly bodyRef: RefObject<HTMLTableSectionElement>;
+    readonly getScroller: () => ScrollElement | undefined;
+    readonly getOffsetTop: () => number;
+}
+interface MiddlewareResult<T> extends MiddlewareContext<T>, MiddlewareRenders {
+    rowClassName?: (record: T, index: number) => string;
+    onRow?: OnRowType<T>;
+}
+type Middleware<T> = (context: MiddlewareContext<T>) => MiddlewareResult<T>;
+interface RenderOptions<T = any> {
+    column: ColumnType<T>;
+    columnWidths: Map<Key, number>;
+    rowIndex: number;
+    columns: ColumnType<T>[];
+    rowData: T;
+    columnDescriptor: ColumnDescriptor<T>[];
+}
+type PipelineRenderOptions = Partial<RenderOptions>;
+type PipelineRender = (children: ReactNode, options: PipelineRenderOptions) => ReactNode;
+type MiddlewareRender<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderRoot<T = any> = (children: ReactNode, options: Prettify<Omit<RenderOptions<T>, keyof RenderOptions<T>>>) => ReactNode;
+type MiddlewareRenderContent<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderHeaderWrapper<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderHeaderRoot<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderHeader<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderHeaderRow<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderHeaderCell<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor' | 'column' | 'columnWidths'>>) => ReactNode;
+type MiddlewareRenderBodyWrapper<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderBodyRoot<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderBody<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor'>>) => ReactNode;
+type MiddlewareRenderRow<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'columns' | 'columnDescriptor' | 'rowIndex' | 'rowData'>>) => ReactNode;
+type MiddlewareRenderCell<T = any> = (children: ReactNode, options: Prettify<Pick<RenderOptions<T>, 'column'>>) => ReactNode;
+type MergedMiddlewareRender<T = any> = MiddlewareRender<T> | MiddlewareRenderRoot<T> | MiddlewareRenderContent<T> | MiddlewareRenderHeaderWrapper<T> | MiddlewareRenderHeaderRoot<T> | MiddlewareRenderHeader<T> | MiddlewareRenderHeaderRow<T> | MiddlewareRenderHeaderCell<T> | MiddlewareRenderBodyWrapper<T> | MiddlewareRenderBodyRoot<T> | MiddlewareRenderBody<T> | MiddlewareRenderRow<T> | MiddlewareRenderCell<T>;
+interface MiddlewareRenders {
+    /**
+     * 自定义最外层渲染，children 为 整个 VirtualTable。
+     */
+    render?: MiddlewareRender;
+    /**
+     * 自定义 TableRoot(div.virtual-table) 的渲染。
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderRoot?: MiddlewareRenderRoot;
+    /**
+     * 自定义渲染，children 为（TableHeader、TableBody）。
+     */
+    renderContent?: MiddlewareRenderContent;
+    /**
+     * 自定义渲染 TableHeader。children 为 div.virtual-table-header
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderHeaderWrapper?: MiddlewareRenderHeaderWrapper;
+    /**
+     * children 为 table
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderHeaderRoot?: MiddlewareRenderHeaderRoot;
+    /**
+     * children 为 thead
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderHeader?: MiddlewareRenderHeader;
+    /**
+     * children 为 tr
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderHeaderRow?: MiddlewareRenderHeaderRow;
+    /**
+     * children 为 th
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderHeaderCell?: MiddlewareRenderHeaderCell;
+    /**
+     * 自定义渲染 TableBody。children 为 div.virtual-table-body-wrapper
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderBodyWrapper?: MiddlewareRenderBodyWrapper;
+    /**
+     * children 为 table.virtual-table-body
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderBodyRoot?: MiddlewareRenderBodyRoot;
+    /**
+     * children 为 tbody
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderBody?: MiddlewareRenderBody;
+    /**
+     * children 为 tr
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderRow?: MiddlewareRenderRow;
+    /**
+     * children 为 td
+     * @note 注意：出于性能考虑，**需要自行对函数 memo**
+     */
+    renderCell?: MiddlewareRenderCell;
+}
+
+type NativeProps$1 = DetailedHTMLProps<HTMLAttributes<HTMLTableCellElement>, HTMLTableCellElement>;
+interface CellProps<T> extends Omit<NativeProps$1, 'children'> {
+    column: ColumnType<T>;
+    rowIndex: number;
+    rowData: T;
+    renderCell?: MiddlewareRenderCell;
+}
+declare const _default$2: <T>(props: CellProps<T>) => ReactElement;
+
+interface ColgroupProps {
+    columns: ColumnDescriptor[];
+    colRef?: (instance: HTMLTableColElement | null, column: ColumnType<any>, index: number) => void;
+}
+declare const Colgroup: FC<ColgroupProps>;
+
+interface TableColumnsContextType {
+    widthList: Map<Key, number>;
+    setWidthList: (value: Map<Key, number>) => void;
+}
+declare function useColumnSizes(): TableColumnsContextType;
+
+interface ContainerSizeState {
+    scrollContainerWidth: number;
+    scrollContainerHeight: number;
+    tableWidth: number;
+    tableHeight: number;
+}
+declare function useContainerSize(): ContainerSizeState;
+
+type Listener = (scrollLeft: number, node: HTMLElement) => void;
+interface HorizontalScrollContextState {
+    listen: (key: string, listener: Listener) => () => void;
+    notify: (key: string, scrollLeft: number, node: HTMLElement) => void;
+}
+declare function useHorizontalScrollContext(): HorizontalScrollContextState;
+
+interface TableRowManagerContextType {
+    getRowHeightList: () => number[];
+    updateRowHeight: (index: number, height: number) => void;
+}
+declare function useTableRowManager(): TableRowManagerContextType;
+
+interface StickyContextState {
+    size: Map<Key, number>;
+    /** 每一列设置的 fixed 值 */
+    fixed: {
+        key: Key;
+        fixed: FixedType | undefined;
+    }[];
+}
+declare function useTableSticky(): StickyContextState;
+
+/**
+ * 缓存数据（浅比较，如果是数组则对第一层进行浅比较）
+ */
+declare function useShallowMemo<T>(pickData: () => T): T;
+
+declare function useStableFn<T extends Function>(callback: T): T;
+
+/**
+ * 创建中间件，内部会浅比较 options，只有 options 改变才会返回新的函数。
+ */
+declare function createMiddleware<T, Args extends any[]>(hook: (ctx: MiddlewareContext<T>, ...args: Args) => MiddlewareResult<T>): (...args: Args) => Middleware<T>;
+
+interface Hook<T> {
+    priority: number;
+    hook: Middleware<T>;
+}
+declare class TablePipeline<T> {
+    constructor();
+    hooks: Hook<T>[];
+    setHooks(value: Hook<T>[]): void;
+    use(options: MiddlewareContext<T>): MiddlewareResult<T>;
+    static defaultPipeline: TablePipeline<unknown>;
+}
+
+interface UseTablePipelineOptions<T = any> {
+    pipeline?: TablePipeline<T>;
+    use?: (Middleware<T> | Hook<T>)[];
+}
+
+declare function useTablePipeline<T = any>(options: UseTablePipelineOptions<T>): TablePipeline<T>;
+
+type NativeProps = DetailedHTMLProps<HTMLAttributes<HTMLTableRowElement>, HTMLTableRowElement>;
+interface RowProps<T> extends Omit<NativeProps, 'children'> {
+    rowIndex: number;
+    rowData: T;
+    columns: InnerColumnDescriptor<T>;
+    onRow?: OnRowType<T>;
+    renderRow?: MiddlewareRenderRow;
+    renderCell?: MiddlewareRenderCell;
+}
+declare const _default$1: <T>(props: RowProps<T>) => ReactElement;
+
+interface TableBodyProps<T> extends Omit<NecessaryProps<T>, 'columns'>, Pick<RowProps<T>, 'onRow' | 'renderRow' | 'renderCell'> {
+    className?: string;
+    style?: CSSProperties;
+    startIndex: number;
+    columns: InnerColumnDescriptor<T>;
+    bodyWrapperRef?: Ref<HTMLDivElement>;
+    bodyRootRef?: Ref<HTMLTableElement>;
+    bodyRef?: Ref<HTMLTableSectionElement>;
+    rowClassName?: (record: T, index: number) => string;
+    renderBodyWrapper?: MiddlewareRenderBodyWrapper;
+    renderBodyRoot?: MiddlewareRenderBodyRoot;
+    renderBody?: MiddlewareRenderBody;
+}
+
+interface VirtualTableCoreProps<T> extends NecessaryProps<T>, Pick<TableBodyProps<T>, 'rowClassName' | 'onRow'> {
+    bodyRootRef?: Ref<HTMLTableElement>;
+    className?: string;
+    style?: CSSProperties;
+    tableBodyClassName?: string;
+    tableBodyStyle?: CSSProperties;
+    /** 开启表头 sticky，设置为 true 则默认 top 为 0，为 number 则是偏移量 */
+    stickyHeader?: number | boolean;
+    /** 预计每列宽度，需要横向虚拟化时，设置它 */
+    estimatedColumnWidth?: number;
+    /** 预计每行高度 @default 46 */
+    estimatedRowHeight?: number;
+    /** 在头和尾额外渲染多少行 @default 5 */
+    overscanRows?: number;
+    /** 横向虚拟化时，在头和尾额外渲染多少列 @default 3 */
+    overscanColumns?: number;
+    /** 开启表头虚拟滚动 @default false */
+    virtualHeader?: boolean;
+    pipeline?: TablePipeline<T>;
+    getOffsetTop?: () => number;
+}
+declare const _default: <T>(props: VirtualTableCoreProps<T> & RefAttributes<HTMLDivElement>) => ReactElement;
+
+declare function getKey<T>(column: ColumnType<T>): Key;
+
+interface ResizeRect {
+    width: number;
+    height: number;
+}
+declare function onResize(target: Window | HTMLElement, callback: (rect: ResizeRect) => void): () => void;
+
+declare function findLastIndex<T>(arr: T[], predicate: (value: T, index: number) => boolean): number;
+
+type PossibleRef<T> = Ref<T> | undefined;
+declare function mergeRefs<T>(...refs: PossibleRef<T>[]): (node: T | null) => void;
+declare function useMergedRef<T>(...refs: PossibleRef<T>[]): (node: T | null) => void;
+
+export { type AlignType, type AnyObject, Colgroup, type ColumnDescriptor, type ColumnExtra, type ColumnType, type ContainerSizeState, type FixedType, type HorizontalScrollContextState, type MergedMiddlewareRender, type Middleware, type MiddlewareContext, type MiddlewareRender, type MiddlewareRenderBody, type MiddlewareRenderBodyRoot, type MiddlewareRenderBodyWrapper, type MiddlewareRenderCell, type MiddlewareRenderContent, type MiddlewareRenderHeader, type MiddlewareRenderHeaderCell, type MiddlewareRenderHeaderRoot, type MiddlewareRenderHeaderRow, type MiddlewareRenderHeaderWrapper, type MiddlewareRenderRoot, type MiddlewareRenderRow, type MiddlewareRenders, type MiddlewareResult, type OnRowType, type PipelineRender, type PipelineRenderOptions, type StickyContextState, type TableColumnsContextType, TablePipeline, type TableRowManagerContextType, type UseTablePipelineOptions, _default as VirtualTable, _default$2 as VirtualTableCell, type CellProps as VirtualTableCellProps, type VirtualTableCoreProps as VirtualTableProps, _default$1 as VirtualTableRow, type RowProps as VirtualTableRowProps, createMiddleware, findLastIndex, getKey, isValidFixed, isValidFixedLeft, isValidFixedRight, mergeRefs, onResize, useColumnSizes, useContainerSize, useHorizontalScrollContext, useMergedRef, useShallowMemo, useStableFn, useTablePipeline, useTableRowManager, useTableSticky };