arthub-table 0.0.3

package/dist/types/core/EdgeScroller.d.ts

@@ -0,0 +1,75 @@
+import type DataGrid from "./DataGrid";
+/**
+ * EdgeScroller — manages continuous auto-scrolling when dragging near viewport edges.
+ *
+ * Usage:
+ *   1. Call `start(onScroll)` when a drag operation begins
+ *   2. Call `update(mouseX, mouseY)` on every mousemove during drag
+ *   3. Call `stop()` when the drag operation ends
+ *
+ * The scroller uses requestAnimationFrame for smooth, continuous scrolling.
+ * Speed increases as the mouse gets closer to the edge.
+ */
+/** Axis constraint for edge scrolling */
+type ScrollAxis = 'both' | 'horizontal' | 'vertical';
+declare class EdgeScroller {
+    private grid;
+    private animationId;
+    private dirX;
+    private dirY;
+    private speedX;
+    private speedY;
+    private isActive;
+    private onScrollCallback;
+    private _lastMouseX;
+    private _lastMouseY;
+    private scrollAxis;
+    /** Last known mouse X position during drag (read-only) */
+    get lastMouseX(): number;
+    /** Last known mouse Y position during drag (read-only) */
+    get lastMouseY(): number;
+    constructor(grid: DataGrid);
+    /**
+     * Start edge scrolling for a drag operation.
+     * @param onScroll Callback invoked after each scroll tick (e.g., to update drag indicators)
+     * @param initialX Optional initial mouse X (avoids stale lastMouseX before first update)
+     * @param initialY Optional initial mouse Y (avoids stale lastMouseY before first update)
+     * @param axis Scroll axis constraint: 'horizontal' for col drag, 'vertical' for row drag, 'both' for selection
+     */
+    start(onScroll?: () => void, initialX?: number, initialY?: number, axis?: ScrollAxis): void;
+    /**
+     * Update mouse position. Call on every mousemove during drag.
+     * Detects edge proximity and starts/stops/adjusts the scroll animation.
+     */
+    update(mouseX: number, mouseY: number): void;
+    /**
+     * Stop edge scrolling. Call when the drag operation ends.
+     */
+    stop(): void;
+    /**
+     * Destroy the edge scroller, releasing all references.
+     * Call when the parent DataGrid is destroyed.
+     */
+    destroy(): void;
+    /**
+     * Compute the scrollable viewport bounds, accounting for fixed columns, header, and scrollbars.
+     */
+    private getViewport;
+    /**
+     * Detect if the mouse is in an edge zone and compute scroll direction + speed.
+     */
+    private detectEdge;
+    /**
+     * Start the RAF animation loop (idempotent — won't start if already running).
+     */
+    private startAnimation;
+    /**
+     * Stop the RAF animation loop.
+     */
+    private stopAnimation;
+    /**
+     * Apply one frame of scrolling, clamped to valid bounds.
+     */
+    private applyScroll;
+}
+export default EdgeScroller;

package/dist/types/core/Editor.d.ts

@@ -0,0 +1,33 @@
+import type DataGrid from "./DataGrid";
+interface Cell {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    editable?: boolean;
+    [key: string]: any;
+}
+declare class Editor {
+    grid: DataGrid;
+    areaEl: any;
+    textEl: any;
+    el: any;
+    type: string;
+    fixed: boolean;
+    selectOptions: any[];
+    editorXIndex: number;
+    editorYIndex: number;
+    xIndex: number;
+    yIndex: number;
+    show: boolean;
+    value: string;
+    cell: Cell | null;
+    suggest?: any;
+    validator?: any;
+    constructor(grid: DataGrid);
+    fire(cell: Cell): void;
+    hide(): void;
+    setData(val: string): void;
+    setoffset(): void;
+}
+export default Editor;

package/dist/types/core/Events.d.ts

@@ -0,0 +1,25 @@
+import type DataGrid from "./DataGrid";
+interface EventTasks {
+    clickoutside: (e: Event) => void;
+    mousedown: (e: MouseEvent) => void;
+    mousemove: (e: MouseEvent) => void;
+    mouseup: (e: MouseEvent) => void;
+    click: (e: MouseEvent) => void;
+    dblclick: (e: MouseEvent) => void;
+    contextmenu: (e: MouseEvent) => void;
+    mousewheel: (e: WheelEvent) => void;
+    keydown: (e: KeyboardEvent) => void;
+    resize: (() => void) & {
+        cancel?: () => void;
+    };
+}
+declare class Events {
+    grid: DataGrid;
+    el: HTMLCanvasElement;
+    isFirefox: boolean;
+    eventTasks: EventTasks;
+    constructor(grid: DataGrid, el: HTMLCanvasElement);
+    init(): void;
+    destroy(): void;
+}
+export default Events;

package/dist/types/core/Footer.d.ts

@@ -0,0 +1,37 @@
+import type DataGrid from './DataGrid';
+import type { FooterData, FooterCellData } from './types';
+declare class Footer {
+    grid: DataGrid;
+    footerData: FooterData;
+    hoverColIndex: number;
+    constructor(grid: DataGrid);
+    /** Footer 行高度 */
+    get height(): number;
+    /** Footer Y 坐标（固定在可视区域底部，水平滚动条上方） */
+    get y(): number;
+    /** 一次性设置所有列的统计数据 */
+    setFooterData(data: FooterData): void;
+    /** 设置单列的统计数据 */
+    setFooterCellData(columnKey: string, data: FooterCellData): void;
+    /** 当列结构变化时，清理已不存在列的 footer 数据 */
+    cleanupFooterData(existingKeys: Set<string>): void;
+    /** 判断鼠标是否在 footer 区域内 */
+    isInFooterArea(x: number, y: number): boolean;
+    /** 获取鼠标悬停所在的列索引（考虑固定列和滚动偏移） */
+    getHoverColumnIndex(mouseX: number): number;
+    /** 获取列在屏幕上的实际 X 坐标 */
+    private getColumnScreenX;
+    /** 处理鼠标单击事件 */
+    onClick(mouseX: number, mouseY: number, clientX: number, clientY: number): void;
+    /** 从列配置中查找指定索引的列 */
+    private findColumnConfig;
+    /** 绘制 footer */
+    draw(): void;
+    /** 绘制单个 footer 单元格 */
+    private drawFooterCell;
+    /** 绘制 "数据统计" 提示文字 */
+    private drawHintText;
+    /** 绘制下拉箭头图标 */
+    private drawArrowIcon;
+}
+export default Footer;

package/dist/types/core/GifAnimationManager.d.ts

@@ -0,0 +1,69 @@
+/**
+ * GIF 动画管理器
+ * 使用 gifuct-js 解析 GIF 并逐帧绘制
+ */
+export default class GifAnimationManager {
+    private static instance;
+    private gifs;
+    private animationFrameId;
+    private isAnimating;
+    private enabled;
+    private constructor();
+    static getInstance(): GifAnimationManager;
+    /**
+     * 加载并解析 GIF
+     */
+    loadGif(url: string): Promise<void>;
+    /**
+     * 渲染指定帧
+     */
+    private renderFrame;
+    /**
+     * 启动动画循环
+     */
+    private startAnimation;
+    /**
+     * 动画循环
+     */
+    private animate;
+    /**
+     * 停止动画循环
+     */
+    stopAnimation(): void;
+    /**
+     * 获取 GIF 的当前帧 Canvas
+     */
+    getGifCanvas(url: string): HTMLCanvasElement | null;
+    /**
+     * 检查 GIF 是否已加载
+     */
+    isGifLoaded(url: string): boolean;
+    /**
+     * 卸载 GIF
+     */
+    unloadGif(url: string): void;
+    /**
+     * 清空所有 GIF
+     */
+    clear(): void;
+    /**
+     * 获取已加载的 GIF 数量
+     */
+    getLoadedGifCount(): number;
+    /**
+     * 暂停所有 GIF 动画
+     */
+    pause(): void;
+    /**
+     * 恢复所有 GIF 动画
+     */
+    resume(): void;
+    /**
+     * 切换 GIF 动画播放状态
+     */
+    toggle(): boolean;
+    /**
+     * 获取当前播放状态
+     */
+    isEnabled(): boolean;
+}

package/dist/types/core/GifOverlay.d.ts

@@ -0,0 +1,33 @@
+import type DataGrid from "./DataGrid";
+interface GifElement {
+    url: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export default class GifOverlay {
+    private grid;
+    private container;
+    private gifElements;
+    private imageManager;
+    constructor(grid: DataGrid);
+    /**
+     * 获取容器元素
+     */
+    get el(): HTMLDivElement;
+    /**
+     * 更新GIF显示
+     * @param gifs GIF元素数组
+     */
+    update(gifs: GifElement[]): void;
+    /**
+     * 清空所有GIF
+     */
+    clear(): void;
+    /**
+     * 销�?
+     */
+    destroy(): void;
+}
+export {};

package/dist/types/core/GroupRow.d.ts

@@ -0,0 +1,80 @@
+/**
+ * GroupRow - Special row type for grouped table rendering
+ * Handles rendering of group header rows and separator rows
+ */
+import Context from './Context';
+import type DataGrid from './DataGrid';
+import { type GroupedTableRowData } from './types';
+/**
+ * GroupRow class for rendering group headers and separators
+ */
+declare class GroupRow extends Context {
+    data: GroupedTableRowData;
+    rowIndex: number;
+    _rowId: string;
+    isGroupHeader: boolean;
+    isSeparator: boolean;
+    constructor(grid: DataGrid, rowIndex: number, x: number, y: number, height: number, data: GroupedTableRowData);
+    /**
+     * Draw the group row
+     */
+    draw(): void;
+    /**
+     * Draw group header row
+     */
+    private drawGroupHeader;
+    /**
+     * Draw expand/collapse arrow
+     */
+    private drawExpandArrow;
+    /**
+     * Draw group name (supports string or array)
+     */
+    private drawGroupName;
+    /**
+     * Draw count badge
+     */
+    private drawCountBadge;
+    /**
+     * Draw separator row
+     */
+    private drawSeparator;
+    /**
+     * Check if point is inside the expand arrow area
+     */
+    isInsideExpandArrow(mouseX: number, mouseY: number): boolean;
+    /**
+     * Check if this row is visible in the viewport
+     */
+    isVerticalVisibleOnBody(): boolean;
+    /**
+     * Check if mouse is inside vertical body boundary
+     */
+    isInsideVerticaBodyBoundary(mouseX: number, mouseY: number): boolean;
+    /**
+     * Handle click on group row
+     */
+    handleClick(mouseX: number, mouseY: number): boolean;
+    /**
+     * Placeholder methods for compatibility with Row interface
+     */
+    rePaint(): void;
+    resizeColumn(_colIndex: number, _diffWidth: number): void;
+    checked: boolean;
+    handleCheck(_checked?: boolean): void;
+    isInVerticalAutofill(_mouseX: number, _mouseY: number): boolean;
+    handleAutofill(_x: number, _y: number): void;
+    handleStartAutofill(_x: number, _y: number): void;
+    isInsideVerticaTableBoundary(mouseX: number, mouseY: number): boolean;
+    mouseMove(_x: number, _y: number): void;
+    mouseDown(_x: number, _y: number): void;
+    click(x: number, y: number): void;
+    dbClick(_x: number, _y: number): void;
+    rowHeader: {
+        handleCheck: (_val: boolean) => void;
+    };
+    allCells: any[];
+    cells: any[];
+    fixedCells: any[];
+}
+export default GroupRow;

package/dist/types/core/Header.d.ts

@@ -0,0 +1,40 @@
+import Context from "./Context";
+import ColumnHeader from "./ColumnHeader";
+import type DataGrid from "./DataGrid";
+interface CheckOption {
+    checked?: boolean;
+    indeterminate?: boolean;
+}
+declare class Header extends Context {
+    checked: boolean;
+    indeterminate: boolean;
+    allColumnHeaders: ColumnHeader[];
+    fixedColumnHeaders: ColumnHeader[];
+    columnHeaders: ColumnHeader[];
+    resizeTarget: ColumnHeader | null;
+    resizeOriginalX: number;
+    resizeOriginalWidth: number;
+    isResizing: boolean;
+    constructor(grid: DataGrid, x: number, y: number);
+    paint(): void;
+    mouseDown(x: number, y: number, e?: {
+        ctrlKey?: boolean;
+        metaKey?: boolean;
+        shiftKey?: boolean;
+    }): void;
+    resizing(x: number, _y: number): void;
+    endResize(): void;
+    /**
+     * 根据鼠标X坐标和Y坐标查找对应的列头
+     * 支持嵌套子列：如果鼠标在子表头行，返回子表头；否则返回父表头或普通列
+     * @param mouseX 鼠标X坐标
+     * @param mouseY 可选的鼠标Y坐标，用于精确匹配嵌套子列行
+     * @param topLevelOnly 是否只返回顶层列头（普通列和嵌套父列），用于跨列拖拽
+     */
+    getColAtPosition(mouseX: number, mouseY?: number, topLevelOnly?: boolean): ColumnHeader | null;
+    handleCheck(opt?: CheckOption): void;
+    resizeColumn(colIndex: number, diffWidth: number): void;
+    resizeAllColumn(fellWidth: number): void;
+    draw(): void;
+}
+export default Header;

package/dist/types/core/History.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 数据历史堆栈
+ */
+import type DataGrid from "./DataGrid";
+interface HistoryData {
+    before: {
+        colIndex: number;
+        rowIndex: number;
+        value: any;
+    };
+    after: {
+        colIndex: number;
+        rowIndex: number;
+        value: any;
+    };
+    type: "single" | "multiple";
+}
+declare class Histories {
+    grid: DataGrid;
+    history: HistoryData[];
+    historyIndex: number;
+    constructor(grid: DataGrid);
+    pushState(data: HistoryData): void;
+    backState(): void;
+    forwardState(): void;
+}
+export default Histories;

package/dist/types/core/ImageManager.d.ts

@@ -0,0 +1,94 @@
+import GifAnimationManager from './GifAnimationManager';
+/**
+ * Image Manager - 管理图片加载和缓存
+ */
+declare class ImageManager {
+    private static instance;
+    private imageCache;
+    private loadingImages;
+    private gifImages;
+    private gifAnimationManager;
+    private redrawCallbacks;
+    private editIcon;
+    private constructor();
+    /**
+     * Load edit icon
+     */
+    private loadEditIcon;
+    /**
+     * Get edit icon
+     * @returns HTMLImageElement or null if not loaded
+     */
+    getEditIcon(): HTMLImageElement | null;
+    static getInstance(): ImageManager;
+    /**
+     * Load image with caching
+     * @param src Image source URL
+     * @returns Promise that resolves to HTMLImageElement
+     */
+    loadImage(src: string): Promise<HTMLImageElement>;
+    /**
+     * Get cached image synchronously
+     * @param src Image source URL
+     * @returns HTMLImageElement or null if not cached
+     */
+    getCachedImage(src: string): HTMLImageElement | null;
+    /**
+     * Check if image is cached
+     * @param src Image source URL
+     * @returns true if image is cached
+     */
+    isCached(src: string): boolean;
+    /**
+     * Clear all cached images
+     */
+    clearCache(): void;
+    /**
+     * Remove specific image from cache
+     * @param src Image source URL
+     */
+    removeFromCache(src: string): void;
+    /**
+     * Check if image is GIF format
+     * @param src Image source URL
+     * @returns true if image is GIF
+     */
+    private isGif;
+    /**
+     * Get GIF canvas for drawing
+     * @param src Image source URL
+     * @returns Canvas element with current GIF frame or null
+     */
+    getGifCanvas(src: string): HTMLCanvasElement | null;
+    /**
+     * Check if image is animated GIF
+     * @param src Image source URL
+     * @returns true if image is GIF
+     */
+    isAnimatedImage(src: string): boolean;
+    /**
+     * Check if there are any GIF images loaded
+     * @returns true if there are GIF images
+     */
+    hasGifImages(): boolean;
+    /**
+     * Register a callback to be called when GIF frames update
+     * @param callback Function to call on animation frame
+     */
+    onAnimationFrame(callback: () => void): void;
+    /**
+     * Unregister animation frame callback
+     * @param callback Function to remove
+     */
+    offAnimationFrame(callback: () => void): void;
+    /**
+     * Trigger redraw callbacks
+     */
+    private triggerRedraw;
+    /**
+     * Get GIF animation manager instance
+     * @returns GifAnimationManager instance
+     */
+    getGifManager(): GifAnimationManager;
+}
+export default ImageManager;

package/dist/types/core/NestedGrid.d.ts

@@ -0,0 +1,177 @@
+/**
+ * NestedGrid - 嵌套表格类
+ * 用于在单元格内渲染子表格
+ */
+import type DataGrid from "./DataGrid";
+import Paint from "./Paint";
+interface NestedColumn {
+    title: string;
+    key: string;
+    width?: number;
+    align?: string;
+    type?: string;
+    options?: any[];
+}
+interface NestedData {
+    [key: string]: any;
+}
+interface NestedGridOptions {
+    columns: NestedColumn[];
+    data: NestedData[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    parentGrid: DataGrid;
+    parentCell: any;
+    displayRows?: number;
+}
+declare class NestedGrid {
+    columns: NestedColumn[];
+    data: NestedData[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    parentGrid: DataGrid;
+    parentCell: any;
+    painter: Paint;
+    rowHeight: number;
+    scrollY: number;
+    hoveredCell: {
+        col: number;
+        row: number;
+    } | null;
+    hoverRowIndex: number;
+    selectedCell: {
+        col: number;
+        row: number;
+    } | null;
+    editingCell: {
+        col: number;
+        row: number;
+    } | null;
+    displayRows?: number;
+    expanded: boolean;
+    expandButtonHeight: number;
+    expandButtonHovered: boolean;
+    private redrawScheduled;
+    private redrawTimer;
+    private offscreenCanvas;
+    private offscreenCtx;
+    private cacheValid;
+    private lastDataHash;
+    progressDrag: {
+        isDragging: boolean;
+        cell: {
+            col: number;
+            row: number;
+        } | null;
+        startValue: number;
+        currentValue: number;
+    };
+    constructor(options: NestedGridOptions);
+    getColumnWidth(index: number): number;
+    getCellBounds(colIndex: number, rowIndex: number): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    getRequiredHeight(): number;
+    getVisibleRowCount(): number;
+    needExpandButton(): boolean;
+    isMouseInsideAbsolute(mouseX: number, mouseY: number): boolean;
+    isMouseInside(mouseX: number, mouseY: number): boolean;
+    isMouseOnExpandButton(mouseX: number, mouseY: number): boolean;
+    getCellAtPosition(mouseX: number, mouseY: number): {
+        col: number;
+        row: number;
+    } | null;
+    handleMouseMove(mouseX: number, mouseY: number): boolean;
+    private isProgressCell;
+    private isMouseOnProgressBar;
+    handleMouseDown(mouseX: number, mouseY: number): boolean;
+    private handleProgressDragMove;
+    handleMouseUp(_mouseX: number, _mouseY: number): boolean;
+    isMouseOnEditIcon(mouseX: number, mouseY: number, cell: {
+        col: number;
+        row: number;
+    }): boolean;
+    isCellEditable(colIndex: number): boolean;
+    getSelectLabel(colIndex: number, value: any): string;
+    /**
+     * 处理点击事件，返回点击信息
+     * @param mouseX 鼠标相对于嵌套表格的 X 坐标
+     * @param mouseY 鼠标相对于嵌套表格的 Y 坐标
+     * @returns 点击信息对象，如果没有点击到有效区域则返回 null
+     */
+    handleClick(mouseX: number, mouseY: number): {
+        type: 'expand' | 'cell' | 'editIcon' | 'booleanToggle';
+        cell?: {
+            row: number;
+            col: number;
+        };
+        needsRedraw?: boolean;
+    } | null;
+    /**
+     * Check if mouse is on the boolean checkbox area within a cell
+     */
+    private isMouseOnBooleanCheckbox;
+    /**
+     * 获取单元格的编辑信息
+     * @param colIndex 列索引
+     * @param rowIndex 行索引
+     * @returns 单元格编辑信息
+     */
+    getCellEditInfo(colIndex: number, rowIndex: number): {
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        column: NestedColumn;
+        value: any;
+        displayValue: string;
+        rowData: NestedData;
+    };
+    /**
+     * 启动编辑（已废弃，编辑器启动逻辑已移至 Events.ts）
+     * 保留此方法是为了兼容性
+     */
+    startEdit(colIndex: number, rowIndex: number): void;
+    updateParentRowHeight(): void;
+    updateRowHeight(newRowHeight: number): void;
+    finishEdit(value: any): void;
+    cancelEdit(): void;
+    draw(): void;
+    clearOtherNestedGridsSelection(): void;
+    /**
+     * 性能优化：确保离屏 Canvas 存在且尺寸正确
+     */
+    private ensureOffscreenCanvas;
+    /**
+     * 性能优化：计算数据哈希，用于检测数据变化
+     * 使用简化的哈希方法，避免深度比较的性能开销
+     */
+    private computeDataHash;
+    /**
+     * 使缓存失效（数据变化时调用）
+     */
+    invalidateCache(): void;
+    private getDisplayValue;
+    private drawPersonCell;
+    private drawStatusCell;
+    private drawProgressCell;
+    private drawDatetimeCell;
+    private drawBooleanCell;
+    private drawPlaceholderText;
+    private drawRoundedRect;
+    private truncateText;
+    private getPersonInitial;
+    private hashString;
+    private scheduleRedraw;
+    updatePosition(x: number, y: number): void;
+}
+export default NestedGrid;