# myliang/x-spreadsheet architecture

> Architecture diagram of the GitHub repository myliang/x-spreadsheet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/myliang/x-spreadsheet
- Repository: https://github.com/myliang/x-spreadsheet

## Overview

##### Project Type and Purpose
- This is a front‑end JavaScript library (x‑spreadsheet) that provides a web‑based spreadsheet component.
- It is not a full‑stack app or microservice suite—it is an embeddable UI component/library distributed via npm/CDN.

##### File Structure
- src/
- algorithm/ – data structures (bitmap, expression parser)
- component/ – React‑style UI widgets (buttons, dropdowns, toolbar items, context menu, editor, sheet, etc.)
- core/ – spreadsheet domain logic (cell model, ranges, history/undo, formula engine, validation, clipboard, merge, auto‑filter, helper utilities)
- locale/ – i18n files (en, de, nl, zh‑cn)
- index.js, index.less – public entry point + styles
- build/ – Webpack configs (dev, prod, locale) + locale_loader script
- dist/ – packaged CSS/JS + locale bundles + example index.html
- docs/ – documentation website build (mirrors dist/)
- test/ – unit tests for core logic & locale
- CI/CD configs – .travis.yml, GitHub workflows, codecov
- package.json – dependencies, scripts

##### README
- Confirms it’s a browser component; shows usage via CDN or npm import.
- Lists features: undo/redo, formatting, formulas, multi‑sheet, print, data validation, etc.
- Mentions integration with SheetJS for XLSX import/export.

##### Main Components
a. UI Layer (component/)
- Toolbar, context menus, sheet grid, cell editor, modal dialogs
- Event emissions: cell‑selected, cell‑edited, etc.
b. Rendering Engine (canvas/)
- Canvas drawing abstractions for grid lines, cell content, selections
c. Core Model & Logic (core/)
- Data model: cell, row, column, sheet, range
- Formula evaluation, history (undo/redo), clipboard, merge, filter, validation
- Helper utilities for formatting, alphabet indices, data proxy
d. Algorithm Utilities (algorithm/)
- Bitmap handling, expression parsing
e. Configuration & Localization (config.js + locale/)
- Default options (mode, toolbar, grid, styles)
- Locale loader for i18n
f. Build & Distribution Pipeline (build/ → dist/, docs/dist/)
- Webpack bundling (dev vs. prod vs. per‑locale)
- Outputs: xspreadsheet.js, xspreadsheet.css, locale bundles, source maps
- NPM package publication, CDN hosting
g. Test & CI/CD
- Unit tests (test/) executed on Travis/ GitHub Actions
- Code coverage (codecov)
h. External Integrations
- SheetJS for XLSX import/export
- Browser environment (DOM, Canvas API)

##### Relationships and Data Flows
- User interacts in Browser → UI Layer components
- UI Layer emits events → Core Model (e.g., cell edit triggers core.updateCell)
- Core Model invokes Algorithm Utilities (formula parsing, validation)
- Configuration & Locale drive both Core and UI for labels, styles, dimensions
- Build Pipeline ingests all src modules → bundles → dist → CDN/NPM → Browser

##### Important Architectural Patterns
- Component‑based UI (decoupled widgets)
- MVC‑like separation: UI View ↔ Controller (event handlers) ↔ Model (core/)
- Pluggable locale loader (strategy pattern)
- Immutable history stack for undo/redo
- Single‑page asset bundle for easy embedding

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Distribution Pipeline
    subgraph "Build & Distribution"  
        direction TB
        webpackDev["webpack.dev.js"]:::build
        webpackProd["webpack.prod.js"]:::build
        webpackLocale["webpack.locale.js"]:::build
        webpackConfig["webpack.config.js"]:::build
        distBundles["dist Bundles<br/>(xspreadsheet.js, xspreadsheet.css, locale/*.js)"]:::document
        docsDist["docs/dist/"]:::document
    end

    %% Configuration & Localization
    subgraph "Configuration & Localization"
        direction TB
        defaultConfig["src/config.js"]:::config
        localeLoader["build/locale_loader.js"]:::config
        localeFiles["Locale Files<br/>(en.js, de.js, nl.js, zh-cn.js)"]:::cylinder
    end

    %% Algorithm Utilities
    subgraph "Algorithm Utilities"
        direction TB
        bitmap["bitmap.js"]:::algorithm
        expression["expression.js"]:::algorithm
    end

    %% Core Model & Logic
    subgraph "Core Model & Logic"
        direction TB
        cellModel["cell.js"]:::core
        rowModel["row.js"]:::core
        colModel["col.js"]:::core
        cellRange["cell_range.js"]:::core
        selectorCore["selector.js"]:::core
        formulaEngine["formula.js"]:::core
        helperUtils["helper.js"]:::core
        history["history.js"]:::core
        clipboard["clipboard.js"]:::core
        merge["merge.js"]:::core
        autoFilter["auto_filter.js"]:::core
        validation["validation.js"]:::core
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        direction TB
        draw1["draw.js"]:::canvas
        draw2["draw2.js"]:::canvas
    end

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        toolbarDir["Toolbar<br/>& Items"]:::ui
        contextMenu["contextmenu.js"]:::ui
        editorComp["editor.js"]:::ui
        modalComp["modal.js"]:::ui
        sheetGrid["sheet.js"]:::ui
        selectorUI["selector.js"]:::ui
        buttonComp["button.js"]:::ui
        dropdownComp["dropdown.js"]:::ui
    end

    %% External Integrations & Environment
    subgraph "External & CI/CD"
        direction TB
        sheetjs["SheetJS XLSX"]:::external
        browserEnv["Browser DOM & Canvas API"]:::external
        unitTests["Unit Tests (test/)"]:::external
        ciConfig["CI Config (.travis.yml, .github/workflows/)"]:::external
    end

    %% Runtime & Distribution Flow
    distBundles -->|"Published to"| CDN["CDN/NPM"]:::cloud
    docsDist -->|"Documentation hosted"| GitHubPages["GitHub Pages"]:::cloud
    CDN -->|"Loads Bundles"| browserEnv
    browserEnv -->|"Renders UI"| toolbarDir
    browserEnv --> sheetGrid

    %% UI to Core Flow
    toolbarDir -->|"cell-selected, cell-edited events"| cellModel
    contextMenu -->|events| cellModel
    editorComp -->|edit events| cellModel
    sheetGrid -->|"selection events"| cellRange
    selectorUI -->|"selection"| cellRange
    buttonComp -->|actions| cellModel
    dropdownComp -->|actions| cellModel

    %% Core to Algorithm & Rendering
    cellModel -->|"updateCell calls"| formulaEngine
    formulaEngine -->|"parses expressions"| expression
    cellModel -->|"history update"| history
    cellModel -->|"clipboard ops"| clipboard
    cellModel -->|"merge ops"| merge
    cellModel -->|"filter ops"| autoFilter
    validation -->|validates| cellModel
    formulaEngine --> helperUtils
    cellModel --> draw1
    draw1 --> draw2
    draw2 --> toolbarDir

    %% Config & Locale usage
    defaultConfig --> toolbarDir
    defaultConfig --> cellModel
    localeLoader --> localeFiles
    localeFiles --> toolbarDir
    localeFiles --> cellModel

    %% External Integrations
    sheetjs --> dataProxy["data_proxy.js"]:::core
    dataProxy --> cellModel

    %% Build pipeline connections
    webpackDev --> distBundles
    webpackProd --> distBundles
    webpackLocale --> distBundles
    webpackConfig --> webpackDev
    webpackConfig --> webpackProd
    webpackConfig --> webpackLocale

    %% Testing & CI
    unitTests -->|run on| ciConfig
    ciConfig --> webpackConfig

    %% Click Events
    click toolbarDir "https://github.com/myliang/x-spreadsheet/tree/master/src/component/toolbar/"
    click contextMenu "https://github.com/myliang/x-spreadsheet/blob/master/src/component/contextmenu.js"
    click editorComp "https://github.com/myliang/x-spreadsheet/blob/master/src/component/editor.js"
    click modalComp "https://github.com/myliang/x-spreadsheet/blob/master/src/component/modal.js"
    click sheetGrid "https://github.com/myliang/x-spreadsheet/blob/master/src/component/sheet.js"
    click selectorUI "https://github.com/myliang/x-spreadsheet/blob/master/src/component/selector.js"
    click buttonComp "https://github.com/myliang/x-spreadsheet/blob/master/src/component/button.js"
    click dropdownComp "https://github.com/myliang/x-spreadsheet/blob/master/src/component/dropdown.js"
    click draw1 "https://github.com/myliang/x-spreadsheet/blob/master/src/canvas/draw.js"
    click draw2 "https://github.com/myliang/x-spreadsheet/blob/master/src/canvas/draw2.js"
    click cellModel "https://github.com/myliang/x-spreadsheet/blob/master/src/core/cell.js"
    click rowModel "https://github.com/myliang/x-spreadsheet/blob/master/src/core/row.js"
    click colModel "https://github.com/myliang/x-spreadsheet/blob/master/src/core/col.js"
    click cellRange "https://github.com/myliang/x-spreadsheet/blob/master/src/core/cell_range.js"
    click selectorCore "https://github.com/myliang/x-spreadsheet/blob/master/src/core/selector.js"
    click formulaEngine "https://github.com/myliang/x-spreadsheet/blob/master/src/core/formula.js"
    click helperUtils "https://github.com/myliang/x-spreadsheet/blob/master/src/core/helper.js"
    click history "https://github.com/myliang/x-spreadsheet/blob/master/src/core/history.js"
    click clipboard "https://github.com/myliang/x-spreadsheet/blob/master/src/core/clipboard.js"
    click merge "https://github.com/myliang/x-spreadsheet/blob/master/src/core/merge.js"
    click autoFilter "https://github.com/myliang/x-spreadsheet/blob/master/src/core/auto_filter.js"
    click validation "https://github.com/myliang/x-spreadsheet/blob/master/src/core/validation.js"
    click bitmap "https://github.com/myliang/x-spreadsheet/blob/master/src/algorithm/bitmap.js"
    click expression "https://github.com/myliang/x-spreadsheet/blob/master/src/algorithm/expression.js"
    click defaultConfig "https://github.com/myliang/x-spreadsheet/blob/master/src/config.js"
    click localeLoader "https://github.com/myliang/x-spreadsheet/blob/master/build/locale_loader.js"
    click localeFiles "https://github.com/myliang/x-spreadsheet/tree/master/src/locale/"
    click webpackDev "https://github.com/myliang/x-spreadsheet/blob/master/build/webpack.dev.js"
    click webpackProd "https://github.com/myliang/x-spreadsheet/blob/master/build/webpack.prod.js"
    click webpackLocale "https://github.com/myliang/x-spreadsheet/blob/master/build/webpack.locale.js"
    click webpackConfig "https://github.com/myliang/x-spreadsheet/blob/master/build/webpack.config.js"
    click distBundles "https://github.com/myliang/x-spreadsheet/tree/master/dist/"
    click docsDist "https://github.com/myliang/x-spreadsheet/tree/master/docs/dist/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#000
    classDef core fill:#d4edda,stroke:#28a745,color:#000
    classDef algorithm fill:#fff3cd,stroke:#ffc107,color:#000
    classDef build fill:#ffe5b4,stroke:#ff8c00,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef document fill:#f8f9fa,stroke:#adb5bd,color:#000
    classDef cylinder fill:#f1f1f1,stroke:#6c757d,stroke-dasharray: 5 5,color:#000
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef cloud fill:#d1ecf1,stroke:#17a2b8,color:#000
```
