balala-revogrid 1.0.0

package/dist/types/types/plugin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Interface for plugin components
+ */
+export interface PluginBaseComponent {
+    /**
+     * Cleans up plugin's resources
+     */
+    destroy?(): void;
+}

package/dist/types/types/plugin.types.d.ts

@@ -0,0 +1,48 @@
+import { PluginBaseComponent } from "./index";
+import ColumnDataProvider from '../services/column.data.provider';
+import { DataProvider } from '../services/data.provider';
+import DimensionProvider from '../services/dimension.provider';
+import type { SelectionStoreConnector } from '../services/selection.store.connector';
+import ViewportProvider from '../services/viewport.provider';
+export interface PluginServiceBase {
+    get(): PluginBaseComponent[];
+    add(plugin: PluginBaseComponent): void;
+    remove(plugin: PluginBaseComponent): void;
+    getByClass<T extends PluginBaseComponent>(pluginClass: new (...args: any[]) => T): T | undefined;
+}
+/**
+ * Services that are provided by the various plugins for use by the grid. Each plugin
+ * is responsible for providing a specific service, and the `PluginProviders` type collects all the services provided
+ * by the plugins.
+ */
+export type PluginProviders = {
+    /**
+     * The data service provides access to the grid data.
+     */
+    data: DataProvider;
+    /**
+     * The dimension service provides access to the grid's dimensions and settings.
+     */
+    dimension: DimensionProvider;
+    /**
+     * The selection service provides access to the grid's selection state.
+     */
+    selection: SelectionStoreConnector;
+    /**
+     * The column service provides access to the grid's column data.
+     */
+    column: ColumnDataProvider;
+    /**
+     * The viewport service provides access to the grid's viewport state.
+     */
+    viewport: ViewportProvider;
+    /**
+     * Plugin services
+     */
+    plugins: PluginServiceBase;
+};
+declare global {
+    type CombinedHTMLRevoGridElementEventMap = Record<string, any> & HTMLRevogrClipboardElementEventMap & HTMLRevogrFocusElementEventMap & HTMLRevogrDataElementEventMap & HTMLRevogrEditElementEventMap & HTMLRevogrFilterPanelElementEventMap & HTMLRevogrHeaderElementEventMap & HTMLRevogrOrderEditorElementEventMap & HTMLRevogrOverlaySelectionElementEventMap & HTMLRevogrRowHeadersElementEventMap & HTMLRevogrScrollVirtualElementEventMap & HTMLRevogrViewportScrollElementEventMap & HTMLVnodeHtmlElementEventMap;
+    interface HTMLRevoGridElementEventMap extends CombinedHTMLRevoGridElementEventMap {
+    }
+}

package/dist/types/types/selection.d.ts

@@ -0,0 +1,178 @@
+import { type VNode } from '../stencil-public-runtime';
+import type { DimensionRows, DimensionCols } from './dimension';
+import type { ColumnProp, DataType, DataLookup, HyperFunc, ColumnDataSchemaModel, PositionItem } from './interfaces';
+export type RowIndex = number;
+export type ColIndex = number;
+/**
+ * Represents the state of the selection store.
+ * It contains information about the selection range, temporary range,
+ * focused cell, editing cell, last focused cell, and next cell to focus.
+ */
+export type SelectionStoreState = {
+    range: RangeArea | null;
+    /**
+     * Temporary range selection area
+     */
+    tempRange: RangeArea | null;
+    /**
+     * Type of the temporary range selection
+     */
+    tempRangeType: string | null;
+    /**
+     * Focused cell coordinate
+     */
+    focus: Cell | null;
+    /**
+     * Editing cell store
+     */
+    edit: EditCellStore | null;
+    /**
+     * Last cell which was focused
+     * The last real coordinate + 1
+     */
+    lastCell: Cell | null;
+    /**
+     * Next cell to focus
+     */
+    nextFocus: Cell | null;
+};
+export type RangeArea = {
+    x: ColIndex;
+    y: RowIndex;
+    x1: ColIndex;
+    y1: RowIndex;
+};
+export type TempRange = {
+    type: string;
+    area: RangeArea;
+};
+export type OldNewRangeMapping = {
+    [newRowIndex: number]: {
+        [T in ColumnProp]: {
+            rowIndex: number;
+            colIndex: number;
+            colProp: ColumnProp;
+        };
+    };
+};
+export type ChangedRange = {
+    type: DimensionRows;
+    colType: DimensionCols;
+    newRange: RangeArea;
+    oldRange: RangeArea;
+    mapping: OldNewRangeMapping;
+    newData: {
+        [newRowIndex: number]: DataType;
+    };
+};
+/**
+ * Cell coordinates
+ */
+export interface Cell {
+    x: ColIndex;
+    y: RowIndex;
+}
+export type FocusedCells = {
+    focus: Cell;
+    end: Cell;
+};
+export type RangeAreaCss = {
+    left: string;
+    top: string;
+    width: string;
+    height: string;
+};
+export type SaveDataDetails = {
+    rgRow: RowIndex;
+    rgCol: ColIndex;
+    type: DimensionRows;
+    prop: ColumnProp;
+    val: any;
+    preventFocus?: boolean;
+};
+export type BeforeEdit = BeforeSaveDataDetails;
+export type RowDragStartDetails = {
+    cell: Cell;
+    text: string;
+    pos: PositionItem;
+    event: MouseEvent;
+    rowType: DimensionRows;
+    model: any;
+};
+export interface BeforeSaveDataDetails extends ColumnDataSchemaModel {
+    /**
+     * Value from editor to save, not part of the model value yet
+     */
+    val?: any;
+}
+export interface CellClickDetails extends BeforeSaveDataDetails {
+    /**
+     * Original mouse or touch event
+     */
+    originalEvent?: MouseEvent | TouchEvent;
+}
+export type BeforeRangeSaveDataDetails = {
+    data: DataLookup;
+    models: Partial<DataLookup>;
+    type: DimensionRows;
+    newRange: RangeArea | null;
+    oldRange: RangeArea | null;
+};
+export type AfterEditEvent = BeforeRangeSaveDataDetails | BeforeSaveDataDetails;
+/**
+ * Edit cell info for store
+ */
+export interface EditCellStore extends Cell {
+    val?: any;
+}
+/**
+ * Edit cell info for editor
+ */
+export type EditCell = EditCellStore & BeforeSaveDataDetails;
+/**
+ * Available editors in grid
+ */
+export type Editors = {
+    [name: string]: EditorCtr;
+};
+/**
+ * Editor component
+ */
+export type EditorCtr = EditorCtrCallable | EditorCtrConstructible;
+/**
+ * Editor component callable function
+ */
+export type EditorCtrCallable = {
+    (column: ColumnDataSchemaModel, save: (value?: any, preventFocus?: boolean) => void, close: (focusNext?: boolean) => void): EditorBase;
+};
+/**
+ * Editor component constructible class
+ */
+export interface EditorCtrConstructible {
+    new (column: ColumnDataSchemaModel, save: (value: any, preventFocus?: boolean) => void, close: (focusNext?: boolean) => void): EditorBase;
+}
+/**
+ * Editor interface
+ */
+export interface EditorBase {
+    element?: Element | null;
+    editCell?: EditCell;
+    /**
+     * Autosave usage when you want to return value for models.
+     */
+    getValue?(): any;
+    /**
+     * For Editor plugin internal usage.
+     * Prevents Editor save. Manual save usage required.
+     */
+    beforeAutoSave?(val?: any): boolean;
+    beforeUpdate?(): void;
+    /**
+     * Before editor got disconnected.
+     * Can be triggered multiple times before actual disconnect.
+     */
+    beforeDisconnect?(): void;
+    componentDidRender?(): void;
+    disconnectedCallback?(): void;
+    render(createElement: HyperFunc<VNode>, additionalData?: any): VNode | VNode[] | string | void;
+}

package/dist/types/types/theme.d.ts

@@ -0,0 +1,7 @@
+export interface ThemePackage {
+    defaultRowSize: number;
+}
+export type ThemeConfig = {
+    rowSize: number;
+};
+export type Theme = 'default' | 'material' | 'compact' | 'darkMaterial' | 'darkCompact' | string;

package/dist/types/types/viewport.interfaces.d.ts

@@ -0,0 +1,45 @@
+import type { JSXBase } from '../stencil-public-runtime';
+import type { DimensionCols, ColumnRegular, ViewPortScrollEvent, ViewportState, Cell, SelectionStoreState } from "./index";
+import type { DimensionStoreCollection, ViewportStoreCollection, DSourceState } from "../store/index";
+import type { Observable } from '../utils';
+import type { RowDataSources } from '../services/data.provider';
+import type { JSX } from '..';
+export type SlotType = 'content' | 'header' | 'footer';
+export interface ElementScroll {
+    changeScroll?(e: ViewPortScrollEvent, silent?: boolean): Promise<ViewPortScrollEvent | undefined>;
+    setScroll?(e: ViewPortScrollEvent): Promise<void>;
+}
+export type ElementsScroll = {
+    [key: string]: ElementScroll[];
+};
+export type HeaderProperties = JSX.RevogrHeader;
+export type ViewportProperties = JSX.RevogrViewportScroll & JSXBase.HTMLAttributes<HTMLRevogrViewportScrollElement>;
+export type ViewportColumn = {
+    colType: DimensionCols;
+    position: Cell;
+    fixWidth?: boolean;
+    viewports: ViewportStoreCollection;
+    dimensions: DimensionStoreCollection;
+    rowStores: RowDataSources;
+    colStore: Observable<DSourceState<ColumnRegular, DimensionCols>>;
+} & Partial<JSX.RevogrViewportScroll> & Partial<JSX.RevogrHeader>;
+export type ViewportData = {
+    /** Slot to put data */
+    slot: SlotType;
+    style?: {
+        [key: string]: string;
+    };
+} & JSX.RevogrOverlaySelection & (Pick<JSXBase.HTMLAttributes<HTMLRevogrOverlaySelectionElement>, 'ref'> & Pick<JSXBase.HTMLAttributes<HTMLRevogrDataElement>, 'ref'>) & JSX.RevogrData;
+export type ViewportProps = {
+    prop: JSX.RevogrViewportScroll & JSXBase.HTMLAttributes<HTMLRevogrViewportScrollElement>;
+    position: Cell;
+    type: DimensionCols;
+    /** Cols dataset */
+    viewportCol: Observable<ViewportState>;
+    /** header container props */
+    headerProp: HeaderProperties;
+    /** parent selector link */
+    /** viewport rows */
+    dataPorts: ViewportData[];
+    columnSelectionStore: Observable<SelectionStoreState>;
+};

package/dist/types/utils/batchGroupCollapse.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 批量折叠分组工具
+ * 一次性折叠多个指定分组，无动画闪烁，性能最优
+ */
+/**
+ * 批量折叠指定的分组（一次性完成，无视觉闪烁）
+ *
+ * 核心原理：
+ * 1. 收集所有分组的当前展开状态
+ * 2. 将要折叠的分组状态设为 false
+ * 3. 保留子分组的展开状态（这样重新展开父分组时，子分组会保持原状态）
+ * 4. 通过更新 grouping.prevExpanded 并触发重新分组来应用更改
+ *
+ * @param grid - RevoGrid 实例
+ * @param groupKeysToCollapse - 要折叠的分组 key 数组，例如：['V1.0', 'V2.0,需求']
+ * @returns Promise<void>
+ *
+ * @example
+ * ```typescript
+ * // 折叠多个指定分组
+ * await batchCollapseGroups(grid.value, [
+ *   '技术部',
+ *   '技术部,电商平台',
+ *   '产品部,用户增长,P0'
+ * ]);
+ * ```
+ */
+export declare function batchCollapseGroups(grid: HTMLRevoGridElement, groupKeysToCollapse: string[]): Promise<void>;
+/**
+ * 批量展开指定的分组
+ *
+ * @param grid - RevoGrid 实例
+ * @param groupKeysToExpand - 要展开的分组 key 数组
+ * @returns Promise<void>
+ */
+export declare function batchExpandGroups(grid: HTMLRevoGridElement, groupKeysToExpand: string[]): Promise<void>;
+/**
+ * 切换指定分组的展开/折叠状态
+ *
+ * @param grid - RevoGrid 实例
+ * @param groupKeysToToggle - 要切换的分组 key 数组
+ * @returns Promise<void>
+ */
+export declare function batchToggleGroups(grid: HTMLRevoGridElement, groupKeysToToggle: string[]): Promise<void>;
+/**
+ * 根据条件批量折叠分组
+ *
+ * @param grid - RevoGrid 实例
+ * @param predicate - 判断函数，返回 true 的分组会被折叠
+ * @returns Promise<void>
+ *
+ * @example
+ * ```typescript
+ * // 折叠所有包含 "技术部" 的分组
+ * await batchCollapseGroupsByCondition(grid.value, (key) => key.includes('技术部'));
+ *
+ * // 折叠所有二级分组（包含一个逗号）
+ * await batchCollapseGroupsByCondition(grid.value, (key) => key.split(',').length === 2);
+ * ```
+ */
+export declare function batchCollapseGroupsByCondition(grid: HTMLRevoGridElement, predicate: (key: string) => boolean): Promise<void>;
+/**
+ * 获取所有分组的 key 列表
+ *
+ * @param grid - RevoGrid 实例
+ * @param level - 可选，指定层级（0=一级，1=二级，2=三级...）
+ * @returns Promise<string[]>
+ */
+export declare function getAllGroupKeys(grid: HTMLRevoGridElement, level?: number): Promise<string[]>;
+/**
+ * 获取所有展开/折叠的分组 key
+ *
+ * @param grid - RevoGrid 实例
+ * @param expanded - true=获取展开的，false=获取折叠的
+ * @returns Promise<string[]>
+ */
+export declare function getGroupKeysByState(grid: HTMLRevoGridElement, expanded: boolean): Promise<string[]>;

package/dist/types/utils/browser.d.ts

@@ -0,0 +1 @@
+export declare function isSafariDesktop(): boolean;

package/dist/types/utils/cell-template-helper.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 高性能单元格模板辅助工具
+ *
+ * 当使用 Vue/React 等框架组件作为单元格渲染器时，滚动性能可能会下降。
+ * 这是因为框架组件的创建/挂载开销较大。
+ *
+ * 本工具提供原生的高性能渲染方案，适用于对滚动性能要求较高的场景。
+ */
+import type { HyperFunc, ColumnDataSchemaModel } from '../types';
+import type { VNode } from '../stencil-public-runtime';
+/**
+ * 单元格渲染函数类型
+ */
+export type CellRenderFn = (h: HyperFunc<VNode>, props: ColumnDataSchemaModel, additionalData?: any) => VNode | VNode[] | string;
+/**
+ * 创建高性能单元格模板
+ *
+ * @example
+ * ```ts
+ * const priorityTemplate = createCellTemplate((h, { value }) => {
+ *   const colors = { P0: '#f5222d', P1: '#fa541c', P2: '#faad14' };
+ *   return h('span', {
+ *     style: { color: colors[value] || '#999' }
+ *   }, value);
+ * });
+ *
+ * const columns = [
+ *   { prop: 'priority', cellTemplate: priorityTemplate }
+ * ];
+ * ```
+ */
+export declare function createCellTemplate(renderFn: CellRenderFn): CellRenderFn;
+/**
+ * 带缓存的单元格模板
+ * 当单元格值没有变化时，返回缓存的结果
+ *
+ * @param renderFn 渲染函数
+ * @param getCacheKey 获取缓存键的函数，默认使用 rowIndex-prop-value
+ */
+export declare function createCachedCellTemplate(renderFn: CellRenderFn, getCacheKey?: (props: ColumnDataSchemaModel) => string): (h: HyperFunc<VNode>, props: ColumnDataSchemaModel, additionalData?: any) => string | VNode | VNode[];
+/**
+ * 常用的单元格渲染器
+ */
+export declare const CellRenderers: {
+    /**
+     * 带颜色标签的渲染器
+     */
+    colorTag: (colorMap: Record<string, string>) => CellRenderFn;
+    /**
+     * 进度条渲染器
+     */
+    progressBar: (options?: {
+        height?: number;
+        colors?: {
+            low: string;
+            mid: string;
+            high: string;
+        };
+    }) => CellRenderFn;
+    /**
+     * 头像渲染器
+     */
+    avatar: (options?: {
+        size?: number;
+        colors?: string[];
+    }) => CellRenderFn;
+    /**
+     * 状态指示器渲染器
+     */
+    status: (statusConfig: Record<string, {
+        color: string;
+        icon?: string;
+    }>) => CellRenderFn;
+};

package/dist/types/utils/column.utils.d.ts

@@ -0,0 +1,110 @@
+import type { ColumnData, ColumnGrouping, ColumnProp, ColumnRegular, ColumnTypes, DataType, DimensionCols, ViewSettingSizeProp } from "../types/index";
+import { type Group as StoreGroup } from "../store/index";
+export type ColumnItems = Record<DimensionCols, ColumnRegular[]>;
+export interface ColumnGroup extends StoreGroup {
+    level: number;
+}
+export type ColumnGroupingCollection = Record<DimensionCols, ColumnGroup[]>;
+export declare function getCellData(val?: any): any;
+export declare function getCellRaw(model?: DataType, column?: ColumnRegular): any;
+export declare function getCellDataParsed(model: DataType, column: ColumnRegular): any;
+/**
+ * Column collection definition.
+ * Used to access indexed data for columns.
+ * Can be accessed via different events.
+ */
+export type ColumnCollection = {
+    /**
+     * Columns as they are in stores
+     */
+    columns: Record<DimensionCols, ColumnRegular[]>;
+    /**
+     * Columns indexed by prop for quick access, it's possible to have multiple columns with same prop but not recommended
+     */
+    columnByProp: Record<ColumnProp, ColumnRegular[]>;
+    /**
+     * Grouped columns
+     */
+    columnGrouping: ColumnGroupingCollection;
+    /**
+     * Max level of grouping
+     */
+    maxLevel: number;
+    /**
+     * Sorting
+     */
+    sort: Record<ColumnProp, ColumnRegular>;
+};
+/**
+ * Get column type from column data
+ */
+export declare function getColumnType(rgCol: ColumnRegular): DimensionCols;
+export declare function getColumnSizes(cols: ColumnRegular[]): ViewSettingSizeProp;
+/**
+ * Check if column is grouping column
+ */
+export declare function isColGrouping(colData: ColumnGrouping | ColumnRegular): colData is ColumnGrouping;
+/**
+ * This function is used to create a collection of columns.
+ */
+export declare function getColumns(columns: ColumnData, level?: number, types?: ColumnTypes, resFromRoot?: Partial<ColumnCollection>): ColumnCollection;
+export declare function gatherGroup<T extends ColumnCollection>(res: T, colData: ColumnGrouping, collection: T, existingColumnsByType?: ColumnCollection['columns'], level?: number): T;
+export declare function getColumnByProp(columns: ColumnData, prop: ColumnProp): ColumnRegular | undefined;
+/**
+ * 获取自动宽度列的配置选项
+ * 用于 convertCollectionToColumns 的第二个参数
+ *
+ * @param providers - PluginProviders 对象
+ * @param stretchPlugin - ColumnStretchPlugin 实例
+ * @returns 自动宽度列配置选项
+ *
+ * @example
+ * ```typescript
+ * const stretchPlugin = providers.plugins.getByClass(ColumnStretchPlugin);
+ * const options = getStretchColumnOptions(providers, stretchPlugin);
+ * const columns = convertCollectionToColumns(providers, options);
+ * ```
+ */
+export declare function getStretchColumnOptions(providers: any, stretchPlugin?: any): {
+    stretchColumnProps: Set<string>;
+    manuallyResizedProps: Set<string>;
+} | undefined;
+/**
+ * 将 ColumnCollection 转换为 revogrid.columns 格式
+ * 按照冻结顺序合并：左冻结列 -> 普通列 -> 右冻结列
+ * 并根据 columnGrouping 信息重建分组结构
+ *
+ * @param providers - PluginProviders 对象
+ * @param options - 可选配置
+ * @param options.stretchColumnProps - 自动宽度列的 prop 集合
+ * @param options.manuallyResizedProps - 被手动调整过的列的 prop 集合
+ * @returns 适用于 revogrid.columns 的列数组（包含分组）
+ *
+ * @example
+ * ```typescript
+ * const columns = convertCollectionToColumns(this.providers, {
+ *   stretchColumnProps: new Set(['displayName']),
+ *   manuallyResizedProps: new Set(['priority'])
+ * });
+ * this.revogrid.columns = columns;
+ * ```
+ */
+export declare function convertCollectionToColumns(providers: any, options?: {
+    stretchColumnProps?: Set<string>;
+    manuallyResizedProps?: Set<string>;
+}): (ColumnRegular | ColumnGrouping)[];
+/**
+ * 合并相邻的同名编组
+ * @param columns 列数组
+ * @returns 是否发生了合并
+ *
+ * @example
+ * ```typescript
+ * const columns = [...];
+ * const hasMerged = mergeAdjacentGroups(columns);
+ * if (hasMerged) {
+ *   // 列结构已更新
+ * }
+ * ```
+ */
+export declare function mergeAdjacentGroups(columns: (ColumnRegular | ColumnGrouping)[]): boolean;

package/dist/types/utils/consts.d.ts

@@ -0,0 +1,22 @@
+export declare const MIN_COL_SIZE = 30;
+export declare const RESIZE_INTERVAL = 40;
+export declare const DATA_COL = "data-rgCol";
+export declare const DATA_ROW = "data-rgRow";
+export declare const DISABLED_CLASS = "disabled";
+export declare const CELL_CLASS = "rgCell";
+export declare const ROW_HEADER_TYPE = "rowHeaders";
+export declare const HEADER_CLASS = "rgHeaderCell";
+export declare const HEADER_SORTABLE_CLASS = "sortable";
+export declare const HEADER_ROW_CLASS = "header-rgRow";
+export declare const HEADER_ACTUAL_ROW_CLASS = "actual-rgRow";
+export declare const DRAG_ICON_CLASS = "revo-drag-icon";
+export declare const DRAGGABLE_CLASS = "revo-draggable";
+export declare const FOCUS_CLASS = "focused-cell";
+export declare const SELECTION_BORDER_CLASS = "selection-border-range";
+export declare const MOBILE_CLASS = "mobile-handler";
+export declare const TMP_SELECTION_BG_CLASS = "temp-bg-range";
+export declare const CELL_HANDLER_CLASS = "autofill-handle";
+export declare const EDIT_INPUT_WR = "edit-input-wrapper";
+export declare const DRAGG_TEXT = "Draggable item";
+export declare const GRID_INTERNALS = "__rvgr";
+export declare const ROW_FOCUSED_CLASS = "focused-rgRow";

package/dist/types/utils/events.d.ts

@@ -0,0 +1,5 @@
+export declare function verifyTouchTarget(touchEvent?: Touch, focusClass?: string): boolean;
+/**
+ * Function to get the value of a specific property from a MouseEvent or TouchEvent object.
+ */
+export declare function getPropertyFromEvent(e: MouseEvent | TouchEvent, prop: keyof Pick<Touch, 'clientX' | 'clientY' | 'screenX' | 'screenY'>, focusClass?: string): number | null;

package/dist/types/utils/header.utils.d.ts

@@ -0,0 +1,2 @@
+export declare function generateHeader(index: number): string;
+export declare function generateHeaderByCount(colsNumber: number): string[];

package/dist/types/utils/index.d.ts

@@ -0,0 +1,32 @@
+export * from './store.utils';
+export * from './store.types';
+export * from './column.utils';
+export * from './consts';
+export * from './key.utils';
+export * from './key.codes';
+export * from './row-header-utils';
+export * from './cell-template-helper';
+export * from './batchGroupCollapse';
+export declare function range(size: number, startAt?: number): number[];
+export declare function findPositionInArray<T>(this: T[], el: T, compareFn: (el: T, el2: T) => number): number;
+/**
+ * Sorted push
+ */
+export declare function pushSorted<T>(arr: T[], el: T, fn: (el: T, el2: T) => number): T[];
+/**
+ * Merge sorted array helper function
+ */
+export declare function mergeSortedArray<T>(arr1: T[], arr2: T[], compareFn?: (el: T, el2: T) => boolean): T[];
+/**
+ * Calculate system scrollbar size
+ */
+export declare function getScrollbarSize(document: Document): number;
+export declare function scaleValue(value: number, from: [number, number], to: [number, number]): number;
+/**
+ * Async timeout
+ */
+export declare function timeout(delay?: number): Promise<void>;
+/**
+ * Type script mixins
+ */
+export declare function applyMixins(derivedCtor: any, constructors: any[]): void;