xiaodao-spreader 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leeqwind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# xiaodao-spreader
+
+A Vue 3 spreadsheet component based on Canvas 2D, providing an Excel-like editing experience.
+
+![Preview](./img/preview.png)
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Basic Usage
+
+```vue
+<template>
+  <Spreadsheet v-model:data="myData" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import Spreadsheet from './components/spreader/spreader.vue'
+
+const myData = ref([])
+</script>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` (v-model) | `SheetModelData[]` | `[]` | Multi-sheet data (two-way binding) |
+| `rowCount` | `number` | `200` | Total rows per sheet |
+| `colCount` | `number` | `26` | Total columns per sheet |
+| `width` | `number \| string` | — | Component width (pixel value, percentages not supported) |
+| `height` | `number \| string` | — | Component height (pixel value, percentages not supported) |
+| `theme` | `'light' \| 'dark'` | `'light'` | Theme mode |
+| `locale` | `string` | `'zh-CN'` | Language (`'zh-CN'` / `'en-US'`) |
+
+### SheetModelData Type
+
+```typescript
+interface SheetModelData {
+  name: string
+  cells: Record<string, { value: string; style?: Record<string, unknown> }>
+  colWidths?: Record<number, number>   // Column index → width (px), only stores non-default values
+  rowHeights?: Record<number, number>  // Row index → height (px), only stores non-default values
+}
+```
+
+The key of `cells` is a `"col,row"` string format (e.g., `"0,0"` represents A1).
+
+## Features
+
+- **Canvas Rendering**: High DPI support, virtual rendering only draws cells in the visible area
+- **Multiple Sheets**: Tab bar switching, create, rename, duplicate, delete, drag-to-reorder
+- **Formula Engine**: Supports `=SUM(A1:B5)` range summation with dependency tracking and caching
+- **Undo/Redo**: Ctrl+Z / Ctrl+Y, up to 50 steps
+- **Selection**: Click / drag / Shift+Click selection, row/column headers and corner cell for one-click select-all
+- **Editing**: Double-click / F2 / direct input to enter edit mode, formula bar supports formula input
+- **Keyboard Navigation**: Arrow keys / Tab / Enter / Home / End / Ctrl+Home / Ctrl+End
+- **Clipboard**: Ctrl+C/V/X copy, paste, cut (TSV format), formula references automatically offset
+- **Row/Column Operations**: Right-click menu to insert, delete, cut, copy, paste entire rows/columns
+- **Column Width/Row Height Dragging**: Drag header edges to resize
+- **Context Menu**: Independent context menus for cells, row/column headers, corner cell, and tab bar; nested submenu support (e.g., Calculate → Sum)
+- **Theme**: Light / Dark dual theme
+- **Internationalization**: Chinese / English right-click menus
+- **Touch**: Swipe scrolling + double-tap to enter edit mode
+- **Custom Scrollbar**: Physical scrollbar with arrow buttons and draggable thumb
+- **Responsive**: ResizeObserver monitors container size changes
+
+## Tech Stack
+
+- **Framework**: Vue 3 (Composition API + `<script setup>`)
+- **Build**: Vite 5
+- **Language**: TypeScript (strict)
+- **Rendering**: Canvas 2D
+- **Package Manager**: pnpm
+
+## Build
+
+```bash
+pnpm build      # Type check + production build
+pnpm preview    # Preview build output
+pnpm type-check # Type check only
+```
+
+## Design Document
+
+See [DOC.md](./DOC.md) for details on architecture, file structure, data model, rendering pipeline, interaction model, and extension points.

package/dist/style.css

@@ -0,0 +1 @@
+.spreadsheet-outer[data-v-5100e6d6]{flex:1;display:flex;flex-direction:column;overflow:hidden}.formula-bar[data-v-5100e6d6]{display:flex;align-items:start;height:32px;min-height:32px;padding:0;gap:0}.formula-bar__cell-label[data-v-5100e6d6]{width:48px;min-width:48px;height:28px;line-height:28px;text-align:center;font-size:12px;font-weight:600;color:var(--sp-formula-bar-label-color);background:var(--sp-formula-bar-label-bg);border:1px solid var(--sp-formula-bar-label-border);border-radius:2px;-webkit-user-select:none;user-select:none}.formula-bar__input[data-v-5100e6d6]{flex:1;height:28px;border:1px solid var(--sp-formula-bar-input-border);border-radius:2px;outline:none;padding:0 6px;margin-left:4px;font-size:13px;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Microsoft YaHei,sans-serif;color:var(--sp-formula-bar-input-color);background:var(--sp-formula-bar-input-bg)}.formula-bar__input[data-v-5100e6d6]:focus{border-color:var(--sp-formula-bar-input-focus-border);box-shadow:0 0 0 1px var(--sp-formula-bar-input-focus-shadow)}.tab-bar[data-v-5100e6d6]{display:flex;align-items:stretch;height:30px;min-height:30px;background:var(--sp-tab-bar-bg);border-bottom:1px solid var(--sp-tab-bar-border);-webkit-user-select:none;user-select:none;margin-bottom:4px}.tab-list[data-v-5100e6d6]{display:flex;align-items:flex-end;flex:1;overflow:hidden;gap:1px;padding:0 1px}.tab-item[data-v-5100e6d6]{display:flex;align-items:center;height:28px;min-width:0;max-width:120px;padding:0 10px;cursor:pointer;border:1px solid var(--sp-tab-inactive-border);background:var(--sp-tab-inactive-bg);color:var(--sp-tab-inactive-color);font-size:14px;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Microsoft YaHei,sans-serif;white-space:nowrap;transition:background .1s}.tab-item[data-v-5100e6d6]:hover{background:var(--sp-tab-hover-bg)}.tab-item--active[data-v-5100e6d6]{height:28px;background:var(--sp-tab-active-bg);color:var(--sp-tab-active-color);border-color:var(--sp-tab-bar-border) var(--sp-tab-bar-border) var(--sp-tab-active-bg);border-bottom:2px solid var(--sp-tab-active-border);font-size:16px}.tab-item--active[data-v-5100e6d6]:hover{background:var(--sp-tab-active-bg)}.tab-item__name[data-v-5100e6d6]{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.tab-rename-input[data-v-5100e6d6]{width:100%;height:18px;border:none;border-radius:0;outline:none;padding:0;font-size:16px;font-family:inherit;background:var(--sp-tab-active-bg);color:var(--sp-tab-active-color);box-sizing:border-box}.tab-bar__add-btn[data-v-5100e6d6]{width:24px;min-width:24px;height:24px;margin:3px 4px 0 3px;border:none;background:transparent;color:var(--sp-tab-add-btn-color);font-size:16px;line-height:22px;text-align:center;cursor:pointer;padding:0}.tab-bar__add-btn[data-v-5100e6d6]:hover{background:var(--sp-tab-add-btn-hover-bg)}.spreadsheet-wrapper[data-v-5100e6d6]{flex:1;position:relative;overflow:hidden;background:var(--sp-wrapper-bg)}.grid-canvas[data-v-5100e6d6]{position:absolute;top:0;left:0;display:block;outline:none;cursor:cell}.grid-canvas[data-v-5100e6d6]:focus{outline:none}.v-scrollbar[data-v-5100e6d6]{position:absolute;right:0;top:0;width:11px;height:calc(100% - 11px);display:flex;flex-direction:column;background:var(--sp-wrapper-bg)}.h-scrollbar[data-v-5100e6d6]{position:absolute;left:0;bottom:0;height:11px;width:calc(100% - 11px);display:flex;background:var(--sp-wrapper-bg)}.sb-corner[data-v-5100e6d6]{position:absolute;right:0;bottom:0;width:11px;height:11px;background:var(--sp-wrapper-bg)}.sb-btn[data-v-5100e6d6]{width:11px;height:11px;min-width:11px;min-height:11px;border:none;background:var(--sp-scroll-btn-bg, #e8e8e8);display:flex;align-items:center;justify-content:center;cursor:pointer;padding:0;-webkit-user-select:none;user-select:none}.sb-btn[data-v-5100e6d6]:hover{background:var(--sp-scroll-btn-hover-bg, #d0d0d0)}.sb-btn[data-v-5100e6d6]:active{background:var(--sp-scroll-btn-active-bg, #c0c0c0)}.sb-arrow[data-v-5100e6d6]{display:block;width:0;height:0}.sb-arrow--up[data-v-5100e6d6]{border-left:3px solid transparent;border-right:3px solid transparent;border-bottom:4px solid var(--sp-scroll-btn-color, #666)}.sb-arrow--down[data-v-5100e6d6]{border-left:3px solid transparent;border-right:3px solid transparent;border-top:4px solid var(--sp-scroll-btn-color, #666)}.sb-arrow--left[data-v-5100e6d6]{border-top:3px solid transparent;border-bottom:3px solid transparent;border-right:4px solid var(--sp-scroll-btn-color, #666)}.sb-arrow--right[data-v-5100e6d6]{border-top:3px solid transparent;border-bottom:3px solid transparent;border-left:4px solid var(--sp-scroll-btn-color, #666)}.sb-track[data-v-5100e6d6]{flex:1;position:relative;background:var(--sp-scroll-track-bg, rgba(0,0,0,.06))}.sb-track--v[data-v-5100e6d6]{width:11px}.sb-track--h[data-v-5100e6d6]{height:11px}.sb-thumb[data-v-5100e6d6]{position:absolute;border-radius:3px;background:var(--sp-scroll-thumb);cursor:default}.sb-thumb[data-v-5100e6d6]:hover{background:var(--sp-scroll-thumb-hover)}.sb-thumb--v[data-v-5100e6d6]{left:1px;right:1px;min-height:16px}.sb-thumb--h[data-v-5100e6d6]{top:1px;bottom:1px;min-width:16px}.cell-editor[data-v-5100e6d6]{position:absolute;border:2px solid var(--sp-cell-editor-border);outline:none;padding:0 4px;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Microsoft YaHei,sans-serif;font-size:13px;color:var(--sp-cell-editor-color);background:var(--sp-cell-editor-bg);box-shadow:0 0 0 1px var(--sp-cell-editor-shadow);z-index:10;box-sizing:border-box;min-width:0}.context-menu{position:fixed;z-index:10000;background:#fff;border:1px solid #ccc;border-radius:4px;box-shadow:0 2px 8px #00000026;padding:4px 0;min-width:120px;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Microsoft YaHei,sans-serif;font-size:13px}.context-menu__item{padding:6px 20px;cursor:pointer;color:#333;white-space:nowrap;position:relative;display:flex;align-items:center;justify-content:space-between}.context-menu__item:hover{background:#e8f0fe}.context-menu__item--disabled{color:#bbb;cursor:default}.context-menu__item--disabled:hover{background:transparent}.context-menu__arrow{margin-left:16px;margin-right:-5px;width:0;height:0;border-top:3px solid transparent;border-bottom:3px solid transparent;border-left:4px solid #888}.context-submenu{display:none;position:absolute;left:100%;top:-4px;background:#fff;border:1px solid #ccc;border-radius:4px;box-shadow:0 2px 8px #00000026;padding:4px 0;min-width:100px;z-index:10001}.context-submenu--left{left:auto;right:100%}.context-menu__item:hover>.context-submenu{display:block}.context-submenu .context-menu__item{justify-content:flex-start}

package/dist/types/components/spreader/constants.d.ts

@@ -0,0 +1,15 @@
+import type { ThemeColors } from './types';
+export declare const HEADER_WIDTH = 52;
+export declare const HEADER_HEIGHT = 24;
+export declare const DEFAULT_COL_WIDTH = 100;
+export declare const DEFAULT_ROW_HEIGHT = 24;
+export declare const MIN_COL_WIDTH = 30;
+export declare const MIN_ROW_HEIGHT = 24;
+export declare const SB_SIZE = 11;
+export declare const ARROW_SIZE = 11;
+export declare const SCROLL_STEP = 50;
+export declare const UNDO_MAX = 50;
+export declare const i18n: Record<string, Record<string, string>>;
+export declare function t(locale: string, key: string): string;
+export declare const lightTheme: ThemeColors;
+export declare const darkTheme: ThemeColors;

package/dist/types/components/spreader/formula.d.ts

@@ -0,0 +1,36 @@
+import type { CellData } from './types';
+/** 解析区域引用（如 "A1:B5" → {sc, sr, ec, er}） */
+export declare function parseRangeRef(rangeRef: string, colCount: number, rowCount: number): {
+    sc: number;
+    sr: number;
+    ec: number;
+    er: number;
+} | null;
+/** 获取单元格数值（用于公式参数求值），返回 0 表示空或非数值 */
+export declare function getNumericValue(col: number, row: number, cells: Record<string, CellData>, colCount: number, rowCount: number): number;
+export declare function clearEvalCache(): void;
+export declare function getEvalCache(): Map<string, number>;
+/** 对指定单元格公式求值，返回数值结果；若为普通值则尝试解析为数字 */
+export declare function evalFormula(key: string, cells: Record<string, CellData>, colCount: number, rowCount: number): number | null;
+/** 解析公式中引用的单元格列表（用于依赖追踪） */
+export declare function parseFormulaRefs(formula: string, colCount: number, rowCount: number): string[];
+/** 计算单元格显示值（公式则求值，否则返回原值） */
+export declare function computeCellValue(col: number, row: number, cells: Record<string, CellData>, colCount: number, rowCount: number): string;
+/** 将公式中所有单元格引用偏移 dCol, dRow（支持 $ 绝对引用） */
+export declare function shiftFormulaRefs(formula: string, dCol: number, dRow: number, colCount: number, rowCount: number, colToLabelFn: (col: number) => string): string;
+/**
+ * 公式依赖追踪管理器
+ * 正向：formulaKey → [depKey, ...]
+ * 反向：depKey → Set<formulaKey>
+ */
+export declare class FormulaDeps {
+    private deps;
+    private rev;
+    private dirty;
+    clear(key: string): void;
+    set(key: string, newDeps: string[]): void;
+    markDirty(key: string): void;
+    getDirtyAndClear(): Set<string>;
+    /** 从 cells 快照重建所有依赖关系 */
+    rebuild(cells: Record<string, CellData>, colCount: number, rowCount: number): void;
+}

package/dist/types/components/spreader/spreader.vue.d.ts

@@ -0,0 +1,28 @@
+import type { SheetModelData } from './types';
+type __VLS_Props = {
+    rowCount?: number;
+    colCount?: number;
+    width?: number | string;
+    height?: number | string;
+    theme?: 'light' | 'dark';
+    locale?: string;
+};
+type __VLS_PublicProps = {
+    'data'?: SheetModelData[];
+} & __VLS_Props;
+declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:data": (value: SheetModelData[]) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:data"?: ((value: SheetModelData[]) => any) | undefined;
+}>, {
+    rowCount: number;
+    colCount: number;
+    theme: "light" | "dark";
+    locale: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {
+    formulaBarRef: HTMLInputElement;
+    wrapperRef: HTMLDivElement;
+    canvasRef: HTMLCanvasElement;
+    editInputRef: HTMLInputElement;
+}, HTMLDivElement>;
+export default _default;

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

@@ -0,0 +1,4 @@
+import { type ComputedRef } from 'vue';
+import type { ThemeColors } from './types';
+export declare function useTheme(theme: ComputedRef<'light' | 'dark'>): ComputedRef<ThemeColors>;
+export declare function buildOuterStyle(colors: ThemeColors, width: number | string | undefined, height: number | string | undefined, resolveSize: (val: number | string | undefined) => number | null): Record<string, string>;

package/dist/types/components/spreader/types.d.ts

@@ -0,0 +1,115 @@
+export interface CellCoord {
+    col: number;
+    row: number;
+}
+export interface SelectionRange {
+    startCol: number;
+    startRow: number;
+    endCol: number;
+    endRow: number;
+}
+export interface CellData {
+    value: string;
+    style: Record<string, unknown> | null;
+}
+export interface Range {
+    start: number;
+    end: number;
+}
+export interface SpreadsheetOptions {
+    rowCount?: number;
+    colCount?: number;
+    colWidths?: Record<number, number>;
+    rowHeights?: Record<number, number>;
+}
+export interface SpreadsheetData {
+    [cellRef: string]: {
+        value: string;
+        style?: Record<string, unknown>;
+    };
+}
+export interface SheetModelData {
+    name: string;
+    cells: Record<string, {
+        value: string;
+        style?: Record<string, unknown>;
+    }>;
+    colWidths?: Record<number, number>;
+    rowHeights?: Record<number, number>;
+}
+export interface SheetState {
+    id: string;
+    name: string;
+    cells: Record<string, CellData>;
+    selection: SelectionRange | null;
+    activeCell: CellCoord;
+    scrollX: number;
+    scrollY: number;
+    colWidths: number[];
+    rowHeights: number[];
+}
+export interface UndoSnapshot {
+    cells: Record<string, CellData>;
+    colWidths: number[];
+    rowHeights: number[];
+}
+export interface ContextMenuItem {
+    label: string;
+    action?: () => void;
+    disabled?: boolean;
+    children?: ContextMenuItem[];
+}
+export interface ThemeColors {
+    bg: string;
+    gridBg: string;
+    headerBg: string;
+    headerBorder: string;
+    headerText: string;
+    headerSep: string;
+    cornerBg: string;
+    gridLine: string;
+    selectionBg: string;
+    activeCellBorder: string;
+    cellText: string;
+    scrollTrack: string;
+    scrollThumb: string;
+    formulaBarBg: string;
+    formulaBarBorder: string;
+    formulaBarLabelText: string;
+    formulaBarLabelBg: string;
+    formulaBarLabelBorder: string;
+    formulaBarInputBg: string;
+    formulaBarInputBorder: string;
+    formulaBarInputText: string;
+    formulaBarInputFocusBorder: string;
+    formulaBarInputFocusShadow: string;
+    wrapperBg: string;
+    cellEditorBorder: string;
+    cellEditorText: string;
+    cellEditorBg: string;
+    cellEditorShadow: string;
+    tabBarBg: string;
+    tabBarBorder: string;
+    tabActiveBg: string;
+    tabActiveText: string;
+    tabActiveBorder: string;
+    tabInactiveBg: string;
+    tabInactiveText: string;
+    tabInactiveBorder: string;
+    tabHoverBg: string;
+    tabAddBtnColor: string;
+    tabAddBtnHoverBg: string;
+    tabScrollBtnColor: string;
+    tabScrollBtnHoverBg: string;
+    scrollbarThumb: string;
+    scrollbarThumbHover: string;
+    scrollBtnBg: string;
+    scrollBtnColor: string;
+    scrollBtnHoverBg: string;
+    scrollBtnActiveBg: string;
+    scrollTrackBg: string;
+}
+export interface Point {
+    x: number;
+    y: number;
+}

package/dist/types/components/spreader/utils.d.ts

@@ -0,0 +1,26 @@
+import type { CellCoord } from './types';
+/** 列号 → Excel 风格列标签 (0→A, 25→Z, 26→AA) */
+export declare function colToLabel(col: number): string;
+/** Excel 风格列标签 → 列号 (A→0, Z→25, AA→26) */
+export declare function labelToCol(label: string): number;
+/** 解析 CSS 尺寸值，返回像素数值或 null */
+export declare function resolveSize(val: number | string | undefined): number | null;
+/** 写入剪贴板（兼容旧浏览器） */
+export declare function writeClipboardText(text: string): void;
+/** 根据行列索引生成单元格标志符 */
+export declare function cellKey(col: number, row: number): string;
+/** 将单元格引用字符串转为坐标（如 "A1" → {col:0, row:0}） */
+export declare function parseCellRef(ref: string, colCount: number, rowCount: number): CellCoord | null;
+/** 命中测试：根据 X 坐标二分查找所在列 */
+export declare function hitTestCol(x: number, colPositions: number[], colCount: number): number;
+/** 命中测试：根据 Y 坐标二分查找所在行 */
+export declare function hitTestRow(y: number, rowPositions: number[], rowCount: number): number;
+/** 获取 canvas 相对坐标 */
+export declare function getCanvasXY(e: MouseEvent, canvas: HTMLCanvasElement | null): {
+    x: number;
+    y: number;
+};
+/** 网格可视区域宽度（减去列头和滚动条） */
+export declare function gridViewW(viewW: number, sbSize: number): number;
+/** 网格可视区域高度（减去行头和滚动条） */
+export declare function gridViewH(viewH: number, sbSize: number): number;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+import Spreader from './components/spreader/spreader.vue';
+export default Spreader;
+export { Spreader };
+export type { CellCoord, SelectionRange, CellData, Range, SpreadsheetOptions, SpreadsheetData, SheetModelData, SheetState, UndoSnapshot, ContextMenuItem, ThemeColors, Point, } from './components/spreader/types';