@nuptechs/nup-xlsx-preview 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,790 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+
+/**
+ * @aspect/nup-xlsx-preview - Types
+ * Ultra-light Excel visualization component
+ */
+interface NupCell {
+    v?: string | number | boolean | null;
+    f?: string;
+    s?: number | string;
+    t?: 's' | 'n' | 'b' | 'e' | 'd';
+}
+interface NupRow {
+    h?: number;
+    hidden?: boolean;
+}
+interface NupCol {
+    w?: number;
+    hidden?: boolean;
+}
+interface NupWorksheet {
+    id: string;
+    name: string;
+    cells: Record<string, NupCell>;
+    rows: Record<number, NupRow>;
+    cols: Record<number, NupCol>;
+    merges?: string[];
+    rowCount: number;
+    colCount: number;
+}
+interface NupThemeConfig {
+    name: string;
+    colors: {
+        background: string;
+        foreground: string;
+        grid: string;
+        headerBackground: string;
+        headerForeground: string;
+        selectionBorder: string;
+        selectionBackground: string;
+        frozenBorder: string;
+    };
+    fonts: {
+        family: string;
+        size: string;
+        headerSize: string;
+    };
+}
+interface NupWorkbook {
+    sheets: NupWorksheet[];
+    activeSheet: number;
+    styles?: Record<string, unknown>;
+    theme?: NupThemeConfig;
+}
+interface PreviewConfig {
+    workbook: NupWorkbook;
+    activeSheet?: number;
+    theme?: NupThemeConfig;
+    width?: number | string;
+    height?: number | string;
+    minRowHeight?: number;
+    maxRowHeight?: number;
+    defaultRowHeight?: number;
+    defaultColWidth?: number;
+    showHeaders?: boolean;
+    showSheetTabs?: boolean;
+    showGridLines?: boolean;
+    showScrollbars?: boolean;
+    selectable?: boolean;
+    resizable?: boolean;
+    searchable?: boolean;
+    copyable?: boolean;
+    contextMenu?: boolean;
+    frozenRows?: number;
+    frozenCols?: number;
+    overscan?: number;
+    recycleNodes?: boolean;
+    ariaLabel?: string;
+    keyboardNavigation?: boolean;
+}
+interface CellClickEvent {
+    cell: NupCell | null;
+    row: number;
+    col: number;
+    cellRef: string;
+    originalEvent: MouseEvent;
+}
+interface SelectionRange {
+    start: {
+        row: number;
+        col: number;
+    };
+    end: {
+        row: number;
+        col: number;
+    };
+    cells: (NupCell | null)[][];
+    cellRefs: string[];
+}
+interface ScrollPosition {
+    scrollTop: number;
+    scrollLeft: number;
+    visibleRows: {
+        start: number;
+        end: number;
+    };
+    visibleCols: {
+        start: number;
+        end: number;
+    };
+}
+interface SearchResult {
+    row: number;
+    col: number;
+    cellRef: string;
+    value: string;
+    matchStart: number;
+    matchEnd: number;
+}
+interface ClipboardData {
+    text: string;
+    html: string;
+    cells: (NupCell | null)[][];
+}
+interface PreviewEvents {
+    onCellClick?: (event: CellClickEvent) => void;
+    onCellDoubleClick?: (event: CellClickEvent) => void;
+    onCellRightClick?: (event: CellClickEvent) => void;
+    onSelectionChange?: (selection: SelectionRange | null) => void;
+    onSheetChange?: (sheetIndex: number) => void;
+    onColumnResize?: (colIndex: number, width: number) => void;
+    onScroll?: (scroll: ScrollPosition) => void;
+    onSearch?: (results: SearchResult[]) => void;
+    onCopy?: (data: ClipboardData) => void;
+}
+interface PreviewInstance {
+    scrollTo(row: number, col: number): void;
+    scrollToCell(cellRef: string): void;
+    select(range: SelectionRange): void;
+    selectCell(cellRef: string): void;
+    selectAll(): void;
+    clearSelection(): void;
+    getSelection(): SelectionRange | null;
+    setActiveSheet(index: number): void;
+    getActiveSheet(): number;
+    search(query: string): SearchResult[];
+    highlightResults(results: SearchResult[]): void;
+    clearHighlights(): void;
+    getWorkbook(): NupWorkbook;
+    getVisibleCells(): (NupCell | null)[][];
+    getCellAt(row: number, col: number): NupCell | null;
+    copySelection(): Promise<void>;
+    setColumnWidth(col: number, width: number): void;
+    autoFitColumn(col: number): void;
+    autoFitAllColumns(): void;
+    refresh(): void;
+    destroy(): void;
+}
+interface CellRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+interface VisibleRange {
+    startRow: number;
+    endRow: number;
+    startCol: number;
+    endCol: number;
+}
+interface MergeInfo {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+    cellRef: string;
+}
+
+/**
+ * Virtual Scroll Engine
+ * High-performance O(1) lookups using pre-computed positions and binary search
+ */
+
+interface VirtualScrollConfig {
+    rows: number;
+    cols: number;
+    rowHeights: Record<number, number>;
+    colWidths: Record<number, number>;
+    defaultRowHeight?: number;
+    defaultColWidth?: number;
+    overscan?: number;
+    frozenRows?: number;
+    frozenCols?: number;
+}
+interface FrozenInfo {
+    rows: number;
+    cols: number;
+    frozenRowsHeight: number;
+    frozenColsWidth: number;
+}
+declare class VirtualScroll {
+    private rowPositions;
+    private colPositions;
+    private rowHeightCache;
+    private colWidthCache;
+    totalHeight: number;
+    totalWidth: number;
+    overscan: number;
+    rowCount: number;
+    colCount: number;
+    frozenRows: number;
+    frozenCols: number;
+    frozenRowsHeight: number;
+    frozenColsWidth: number;
+    constructor(config: VirtualScrollConfig);
+    /**
+     * Get frozen pane info
+     */
+    getFrozenInfo(): FrozenInfo;
+    /**
+     * Binary search to find index at a given scroll position
+     * O(log n) lookup
+     */
+    private binarySearch;
+    /**
+     * Get visible range given scroll position and viewport dimensions
+     * Returns the scrollable (non-frozen) visible range
+     * Frozen rows/cols are rendered separately by the adapter
+     */
+    getVisibleRange(scrollTop: number, scrollLeft: number, viewportHeight: number, viewportWidth: number): VisibleRange;
+    /**
+     * Get frozen rows range (always visible)
+     */
+    getFrozenRowsRange(): {
+        startRow: number;
+        endRow: number;
+    } | null;
+    /**
+     * Get frozen cols range (always visible)
+     */
+    getFrozenColsRange(): {
+        startCol: number;
+        endCol: number;
+    } | null;
+    /**
+     * Get cell rectangle for absolute positioning
+     */
+    getCellRect(row: number, col: number): CellRect;
+    /**
+     * Get row height
+     */
+    getRowHeight(row: number): number;
+    /**
+     * Get column width
+     */
+    getColWidth(col: number): number;
+    /**
+     * Update column width (for resize)
+     */
+    setColWidth(col: number, width: number): void;
+    /**
+     * Find row/col at a given pixel position
+     */
+    getIndexAtPosition(scrollTop: number, scrollLeft: number): {
+        row: number;
+        col: number;
+    };
+    /**
+     * Scroll offset to bring a cell into view
+     */
+    getScrollToPosition(row: number, col: number, viewportHeight: number, viewportWidth: number): {
+        scrollTop: number;
+        scrollLeft: number;
+    };
+}
+
+/**
+ * Selection Handler
+ * Supports click, Shift+Click, Ctrl+Click, and drag selection
+ */
+
+interface SelectionState {
+    anchor: {
+        row: number;
+        col: number;
+    } | null;
+    focus: {
+        row: number;
+        col: number;
+    } | null;
+    ranges: SelectionRange[];
+}
+declare class SelectionHandler {
+    private state;
+    private sheet;
+    private onChange;
+    constructor(sheet: NupWorksheet, onChange?: (selection: SelectionRange | null) => void);
+    /**
+     * Handle cell click
+     */
+    handleClick(row: number, col: number, event: {
+        shiftKey: boolean;
+        ctrlKey: boolean;
+        metaKey: boolean;
+    }): void;
+    /**
+     * Handle drag selection
+     */
+    handleDrag(row: number, col: number): void;
+    /**
+     * Select a specific cell by reference (e.g., "A1")
+     */
+    selectCell(cellRef: string): void;
+    /**
+     * Select a range
+     */
+    selectRange(startRef: string, endRef: string): void;
+    /**
+     * Select all cells
+     */
+    selectAll(): void;
+    /**
+     * Clear selection
+     */
+    clear(): void;
+    /**
+     * Get current selection
+     */
+    getSelection(): SelectionRange | null;
+    /**
+     * Get all selections (for multi-select)
+     */
+    getAllSelections(): SelectionRange[];
+    /**
+     * Check if a cell is selected
+     */
+    isCellSelected(row: number, col: number): boolean;
+    /**
+     * Check if a cell is the anchor (main selected cell)
+     */
+    isAnchor(row: number, col: number): boolean;
+    /**
+     * Update sheet reference
+     */
+    setSheet(sheet: NupWorksheet): void;
+    private updateRanges;
+    private createRange;
+    private notifyChange;
+}
+
+/**
+ * Keyboard Navigation Handler
+ * WCAG AA compliant keyboard navigation for spreadsheet
+ */
+
+interface KeyboardConfig {
+    enabled: boolean;
+    wrapNavigation?: boolean;
+    tabBehavior?: 'cell' | 'element';
+}
+type KeyboardAction = 'move-up' | 'move-down' | 'move-left' | 'move-right' | 'move-page-up' | 'move-page-down' | 'move-home' | 'move-end' | 'move-ctrl-home' | 'move-ctrl-end' | 'select-all' | 'copy' | 'extend-up' | 'extend-down' | 'extend-left' | 'extend-right';
+declare class KeyboardHandler {
+    private selection;
+    private virtualScroll;
+    private config;
+    private onScroll;
+    private onCopy;
+    constructor(selection: SelectionHandler, virtualScroll: VirtualScroll, config: KeyboardConfig, callbacks?: {
+        onScroll?: (row: number, col: number) => void;
+        onCopy?: () => void;
+    });
+    /**
+     * Handle keydown event
+     * Returns true if event was handled
+     */
+    handleKeyDown(event: KeyboardEvent): boolean;
+    private getAction;
+    private executeAction;
+    private extendSelection;
+    private scrollToSelection;
+    /**
+     * Update references
+     */
+    setVirtualScroll(vs: VirtualScroll): void;
+    setSelection(sel: SelectionHandler): void;
+}
+
+/**
+ * Merge Cells Handler
+ * Parses and manages merged cell regions
+ */
+
+declare class MergeHandler {
+    private merges;
+    private mergeMap;
+    constructor(mergeStrings?: string[]);
+    /**
+     * Parse merge strings like "A1:B2" into structured data
+     */
+    private parseMerges;
+    /**
+     * Check if a cell is part of a merge
+     */
+    getMergeAt(row: number, col: number): MergeInfo | null;
+    /**
+     * Check if this cell is the top-left of a merge (the "master" cell)
+     */
+    isMergeMaster(row: number, col: number): boolean;
+    /**
+     * Check if this cell should be hidden (part of merge but not master)
+     */
+    isMergeHidden(row: number, col: number): boolean;
+    /**
+     * Get the master cell for a merged region
+     */
+    getMergeMaster(row: number, col: number): {
+        row: number;
+        col: number;
+    } | null;
+    /**
+     * Get merged cell rectangle (spans multiple cells)
+     */
+    getMergeRect(row: number, col: number, getCellRect: (r: number, c: number) => CellRect): CellRect | null;
+    /**
+     * Get all merges
+     */
+    getAllMerges(): MergeInfo[];
+    /**
+     * Get merges visible in a range
+     */
+    getVisibleMerges(startRow: number, endRow: number, startCol: number, endCol: number): MergeInfo[];
+    /**
+     * Update with new merge strings
+     */
+    update(mergeStrings: string[]): void;
+}
+
+/**
+ * Clipboard Handler
+ * Copy selected cells to clipboard with text and HTML formats
+ */
+
+declare class ClipboardHandler {
+    /**
+     * Copy selection to clipboard
+     */
+    copyToClipboard(selection: SelectionRange): Promise<ClipboardData>;
+    /**
+     * Format selection as text (TSV) and HTML table
+     */
+    formatSelection(selection: SelectionRange): ClipboardData;
+    private getCellValue;
+    private getCellStyle;
+    private escapeHtml;
+    private copyWithExecCommand;
+}
+
+/**
+ * Search Handler
+ * Search and highlight cells matching a query
+ */
+
+interface SearchOptions {
+    caseSensitive?: boolean;
+    regex?: boolean;
+    matchWholeCell?: boolean;
+}
+declare class SearchHandler {
+    private sheet;
+    private results;
+    private currentIndex;
+    constructor(sheet: NupWorksheet);
+    /**
+     * Search for a query in the sheet
+     */
+    search(query: string, options?: SearchOptions): SearchResult[];
+    /**
+     * Get next search result
+     */
+    next(): SearchResult | null;
+    /**
+     * Get previous search result
+     */
+    previous(): SearchResult | null;
+    /**
+     * Get current result
+     */
+    current(): SearchResult | null;
+    /**
+     * Get all results
+     */
+    getResults(): SearchResult[];
+    /**
+     * Get result count
+     */
+    getCount(): number;
+    /**
+     * Get current index (1-based for display)
+     */
+    getCurrentIndex(): number;
+    /**
+     * Check if a cell is a search result
+     */
+    isResult(row: number, col: number): boolean;
+    /**
+     * Check if a cell is the current result
+     */
+    isCurrent(row: number, col: number): boolean;
+    /**
+     * Clear search
+     */
+    clear(): void;
+    /**
+     * Update sheet reference
+     */
+    setSheet(sheet: NupWorksheet): void;
+    private parseCellRef;
+}
+
+/**
+ * Column Resize Handler
+ * Drag-to-resize column widths
+ */
+
+interface ResizeState {
+    isResizing: boolean;
+    colIndex: number;
+    startX: number;
+    startWidth: number;
+}
+declare class ResizeHandler {
+    private state;
+    private virtualScroll;
+    private onChange;
+    private minWidth;
+    private maxWidth;
+    constructor(virtualScroll: VirtualScroll, onChange?: (colIndex: number, width: number) => void, minWidth?: number, maxWidth?: number);
+    /**
+     * Start resize operation
+     */
+    startResize(colIndex: number, clientX: number): void;
+    /**
+     * Handle mouse move during resize
+     */
+    private handleMouseMove;
+    /**
+     * End resize operation
+     */
+    private handleMouseUp;
+    /**
+     * Check if currently resizing
+     */
+    isResizing(): boolean;
+    /**
+     * Get current resize column
+     */
+    getResizeColumn(): number | null;
+    /**
+     * Cancel resize
+     */
+    cancel(): void;
+    /**
+     * Cleanup event listeners
+     */
+    private cleanup;
+    /**
+     * Update virtual scroll reference
+     */
+    setVirtualScroll(vs: VirtualScroll): void;
+    /**
+     * Destroy handler
+     */
+    destroy(): void;
+}
+
+/**
+ * Theme Definitions (JS version)
+ * For programmatic theme access
+ */
+
+declare const themes: {
+    readonly default: {
+        readonly name: "default";
+        readonly colors: {
+            readonly background: "#ffffff";
+            readonly foreground: "#202124";
+            readonly grid: "#e0e0e0";
+            readonly headerBackground: "#f8f9fa";
+            readonly headerForeground: "#5f6368";
+            readonly selectionBorder: "#1a73e8";
+            readonly selectionBackground: "rgba(26, 115, 232, 0.08)";
+            readonly frozenBorder: "#dadce0";
+        };
+        readonly fonts: {
+            readonly family: "'Google Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif";
+            readonly size: "13px";
+            readonly headerSize: "11px";
+        };
+    };
+    readonly excel: {
+        readonly name: "excel";
+        readonly colors: {
+            readonly background: "#ffffff";
+            readonly foreground: "#000000";
+            readonly grid: "#d4d4d4";
+            readonly headerBackground: "#f0f0f0";
+            readonly headerForeground: "#000000";
+            readonly selectionBorder: "#217346";
+            readonly selectionBackground: "rgba(33, 115, 70, 0.1)";
+            readonly frozenBorder: "#9bc2e6";
+        };
+        readonly fonts: {
+            readonly family: "'Calibri', 'Segoe UI', sans-serif";
+            readonly size: "11px";
+            readonly headerSize: "11px";
+        };
+    };
+    readonly modern: {
+        readonly name: "modern";
+        readonly colors: {
+            readonly background: "#fafafa";
+            readonly foreground: "#18181b";
+            readonly grid: "#e4e4e7";
+            readonly headerBackground: "#f4f4f5";
+            readonly headerForeground: "#71717a";
+            readonly selectionBorder: "#3b82f6";
+            readonly selectionBackground: "rgba(59, 130, 246, 0.08)";
+            readonly frozenBorder: "#a1a1aa";
+        };
+        readonly fonts: {
+            readonly family: "'Inter', -apple-system, BlinkMacSystemFont, sans-serif";
+            readonly size: "13px";
+            readonly headerSize: "11px";
+        };
+    };
+    readonly minimal: {
+        readonly name: "minimal";
+        readonly colors: {
+            readonly background: "#ffffff";
+            readonly foreground: "#27272a";
+            readonly grid: "#f4f4f5";
+            readonly headerBackground: "#ffffff";
+            readonly headerForeground: "#a1a1aa";
+            readonly selectionBorder: "#18181b";
+            readonly selectionBackground: "rgba(24, 24, 27, 0.04)";
+            readonly frozenBorder: "#e4e4e7";
+        };
+        readonly fonts: {
+            readonly family: "'SF Pro Display', -apple-system, BlinkMacSystemFont, sans-serif";
+            readonly size: "13px";
+            readonly headerSize: "11px";
+        };
+    };
+    readonly dark: {
+        readonly name: "dark";
+        readonly colors: {
+            readonly background: "#1e1e1e";
+            readonly foreground: "#d4d4d4";
+            readonly grid: "#3c3c3c";
+            readonly headerBackground: "#252526";
+            readonly headerForeground: "#858585";
+            readonly selectionBorder: "#0078d4";
+            readonly selectionBackground: "rgba(0, 120, 212, 0.2)";
+            readonly frozenBorder: "#4a4a4a";
+        };
+        readonly fonts: {
+            readonly family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif";
+            readonly size: "13px";
+            readonly headerSize: "11px";
+        };
+    };
+    readonly midnight: {
+        readonly name: "midnight";
+        readonly colors: {
+            readonly background: "#0d1117";
+            readonly foreground: "#c9d1d9";
+            readonly grid: "#21262d";
+            readonly headerBackground: "#161b22";
+            readonly headerForeground: "#8b949e";
+            readonly selectionBorder: "#58a6ff";
+            readonly selectionBackground: "rgba(88, 166, 255, 0.15)";
+            readonly frozenBorder: "#30363d";
+        };
+        readonly fonts: {
+            readonly family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif";
+            readonly size: "13px";
+            readonly headerSize: "11px";
+        };
+    };
+    readonly accessible: {
+        readonly name: "accessible";
+        readonly colors: {
+            readonly background: "#ffffff";
+            readonly foreground: "#000000";
+            readonly grid: "#000000";
+            readonly headerBackground: "#e6e6e6";
+            readonly headerForeground: "#000000";
+            readonly selectionBorder: "#0000ff";
+            readonly selectionBackground: "rgba(0, 0, 255, 0.15)";
+            readonly frozenBorder: "#000000";
+        };
+        readonly fonts: {
+            readonly family: "Arial, Helvetica, sans-serif";
+            readonly size: "14px";
+            readonly headerSize: "12px";
+        };
+    };
+};
+type ThemeName = keyof typeof themes;
+/**
+ * Get theme by name
+ */
+declare function getTheme(name: ThemeName): NupThemeConfig;
+/**
+ * Apply theme CSS variables to an element
+ */
+declare function applyTheme(element: HTMLElement, theme: NupThemeConfig): void;
+/**
+ * Get theme class name
+ */
+declare function getThemeClass(name: ThemeName): string;
+
+/**
+ * Cell Utilities
+ * Helper functions for cell reference parsing and formatting
+ */
+/**
+ * Convert column index (0-based) to letter(s) (A, B, ..., Z, AA, AB, ...)
+ */
+declare function colIndexToLetter(col: number): string;
+/**
+ * Convert column letter(s) to index (0-based)
+ */
+declare function letterToColIndex(letters: string): number;
+/**
+ * Convert row/col coordinates to cell reference (e.g., 0, 0 -> "A1")
+ */
+declare function coordsToCellRef(row: number, col: number): string;
+/**
+ * Parse cell reference to row/col coordinates (e.g., "A1" -> { row: 0, col: 0 })
+ */
+declare function cellRefToCoords(ref: string): {
+    row: number;
+    col: number;
+} | null;
+/**
+ * Parse range reference (e.g., "A1:B2")
+ */
+declare function parseRange(rangeRef: string): {
+    start: {
+        row: number;
+        col: number;
+    };
+    end: {
+        row: number;
+        col: number;
+    };
+} | null;
+/**
+ * Format number for display
+ */
+declare function formatCellValue(value: unknown, type?: string): string;
+/**
+ * Check if a string looks like a formula
+ */
+declare function isFormula(value: string): boolean;
+
+interface NupSpreadsheetPreviewProps extends Omit<Partial<PreviewConfig>, 'theme'>, PreviewEvents {
+    workbook: NupWorkbook;
+    activeSheet?: number;
+    theme?: NupThemeConfig | ThemeName;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const NupSpreadsheetPreview: react.ForwardRefExoticComponent<NupSpreadsheetPreviewProps & react.RefAttributes<PreviewInstance>>;
+
+/**
+ * Vanilla JS Adapter
+ * @aspect/nup-xlsx-preview Vanilla JS API
+ */
+
+interface CreatePreviewOptions extends Partial<PreviewConfig>, PreviewEvents {
+    workbook: NupWorkbook;
+}
+declare function createSpreadsheetPreview(container: HTMLElement | string, options: CreatePreviewOptions): PreviewInstance;
+
+export { type CellClickEvent, type CellRect, type ClipboardData, ClipboardHandler, type CreatePreviewOptions, type FrozenInfo, type KeyboardAction, type KeyboardConfig, KeyboardHandler, MergeHandler, type MergeInfo, type NupCell, type NupCol, type NupRow, type NupThemeConfig, type NupWorkbook, type NupWorksheet, type PreviewConfig, type PreviewEvents, type PreviewInstance, NupSpreadsheetPreview as ReactSpreadsheetPreview, type NupSpreadsheetPreviewProps as ReactSpreadsheetPreviewProps, ResizeHandler, type ResizeState, type ScrollPosition, SearchHandler, type SearchOptions, type SearchResult, SelectionHandler, type SelectionRange, type SelectionState, type ThemeName, VirtualScroll, type VirtualScrollConfig, type VisibleRange, applyTheme, cellRefToCoords, colIndexToLetter, coordsToCellRef, createSpreadsheetPreview, createSpreadsheetPreview as default, formatCellValue, getTheme, getThemeClass, isFormula, letterToColIndex, parseRange, themes };