@syncfusion/ej2-spreadsheet/docs/contributing.md

Feature-rich JavaScript Spreadsheet (Excel) control with built-in support for selection, editing, formatting, importing and exporting to Excel

# Contributing Guide

Thank you for contributing to **ej2-spreadsheet**.

This document describes the expected workflow and guidelines for working in this repository, including setup, development commands, contribution rules, and project-specific restrictions for the Spreadsheet component.

---

## Contents

- [Prerequisites](#prerequisites)
- [Project Setup](#project-setup)
- [Run in Development Mode](#run-in-development-mode)
- [Project Structure](#project-structure-summary)
- [Contribution Rules](#contribution-rules)
- [Build for Deployment](#build-for-deployment)
- [Reference Documents](#reference-documents)
---

## Prerequisites

Install the following:

- Node.js (LTS recommended)
- npm (bundled with Node.js)
- Gulp (optional; the project relies on a local Gulp installation)

---

## Project Setup

From the repository root (the folder containing `package.json`):

```bash
cd ej2-spreadsheet-component
npm install -g gulp
npm install
```
This installs TypeScript tooling, build scripts, internal utilities, and demo resources.

## Run in Development Mode

Start the development build and demo server:

```bash
gulp serve
```
What this does:

- Compiles TypeScript (`.ts`) into JavaScript (`.js`)
- Launches the development server via Gulp
- Serves the demo application from `demos/`

### Demo Entry Point

The spreadsheet sample is served using the sample in the demo:

- **Source files:** `demos\spreadsheet\default\default\index.ts`
- **HTML entry:** `demos\spreadsheet\default\default\index.html`


After the build completes, open:

- `http://localhost:3000/demos\spreadsheet\default\default\index.html`

Use this environment to verify changes made in this repo.

## Project Structure

- `src/spreadsheet/`: UI layer: rendering, DOM updates, selection, editing, context menus, dialogs, ribbon, scroll virtualization,  undo/redo, keyboard handling.
- `src/workbook/`: Model layer: workbook, sheet, row, column, cell models; data binding; formatting; import/export JSON model.
- `src/calculate/`: Engine layer: formula parsing, dependency graph maintenance, recalculation engine, custom functions, named ranges, error handling.
- `demos/`: Interactive demo used during `gulp serve` for validation, debugging, and manual testing.

## Contribution Rules
- Strict Refactoring Policy, To maintain stability across the Spreadsheet runtime:
    - Only refactor **newly added code** created for the current fix or feature.

- Code Quality & Style
    - Maintain existing TypeScript patterns, folder structures, and naming conventions.
    - Keep logic localized to the correct subsystem:
        UI-related updates → src/spreadsheet/
        Model updates → src/workbook/
        Formula logic → src/calculate/
    - Prefer strongly typed implementations; avoid any unless required by underlying architecture.
    - Keep diffs minimal and avoid unnecessary moves or renames.

- Feature Development Guidelines
    When adding new functionality:
    - Follow the separation of concerns across UI, model, and engine layers
    - Use workbook APIs for all cell/sheet modifications; do not mutate objects directly.
    - Update the demo under demos/ if the feature requires visual verification or user interaction.
    - Validate behavior with large datasets and multi-sheet workbooks when applicable.

- Bug Fixing Guidelines
    When submitting fixes:
    - Reproduce the bug using a minimal scenario in the demos/ environment.
    - Identify the correct subsystem using the architecture documentation.
    - Apply the smallest viable change (one hypothesis, one insertion point).
    - Validate dependent functionality compared to excel and check the same in the repo also

## Build for Deployment

Create a compiled build without starting the development server:

```bash
gulp build
```

Create a compiled scripts alone without build the whole repo:
```bash
gulp scripts-gen
```

## Reference Documents

- [product.md](product.md) — High-level product definition and feature summary
- [architecture.md](architecture.md) — Component layers, call flow, and subsystem responsibilities
- `spreadsheet-dataflow/*` - Detailed data flow major operations.

These documents are for initial understanding. Do not reload them for every task. Revisit only when explicitly required.