react-spreadsheet

The library is organized into several key areas:

• src/index.ts: The main entry point that exports the public API.
• src/Spreadsheet.tsx: The primary component used to render the spreadsheet.
• src/engine: The engine responsible for spreadsheet formula evaluation.
• src/stories/: Contains Storybook stories for interactive testing.
• website/: Contains the Docusaurus-based website code and documentation.

The spreadsheet state is managed using a centralized reducer pattern:

1. Reducer & Actions: State is managed in src/reducer.ts and actions are defined in src/actions.ts.
2. Context: The state is distributed via React Context (defined in src/context.ts).
3. Performance: The library uses use-context-selector to allow components to select only the specific slices of state they need, which prevents unnecessary re-renders across the spreadsheet.

The library relies on several key data structures to manage spreadsheet state and logic:

• Matrix: A 2D matrix of cells representing the spreadsheet data.
• PointRange: Represents a specific range within the spreadsheet.
• Selection: Represents a rectangular selection of cells.
• CellBase: Represents an individual cell.
• Model: Represents the spreadsheet data combined with evaluated formulae cells.
• PointSet: A set of points used specifically for formulae evaluation.

To use react-spreadsheet in your project, install it along with its required peer dependencies: react, react-dom, and scheduler.

npm install react react-dom scheduler react-spreadsheet

To persist user changes and react to data modifications (such as validation or persistence), use the onChange prop. The onChange callback is triggered every time a cell is changed.

In a controlled setup, you should manage the spreadsheet data in your component's state and pass the state setter to onChange.

import { useState } from "react";
import Spreadsheet from "react-spreadsheet";

const App = () => {
  const [data, setData] = useState([
    [{ value: "Vanilla" }, { value: "Chocolate" }, { value: "" }],
    [{ value: "Strawberry" }, { value: "Cookies" }, { value: "" }],
  ]);
  return <Spreadsheet data={data} onChange={setData} />;
};

To generate static content for production, run yarn build. This creates a build directory containing the static files, which can be hosted on any static content hosting service.

$ yarn build

You can deploy the website to the gh-pages branch using the yarn deploy command. You must provide your GitHub username via the GIT_USER environment variable. If using SSH for deployment, set USE_SSH=true.

$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

To check for linting and formatting issues (useful for CI systems like Travis CI or CircleCI), run the yarn ci command.

$ yarn ci

To contribute to or run the project locally, ensure you have Node.js v16 or higher and Yarn installed. Clone the repository and install dependencies using the following commands:

git clone https://github.com/iddan/react-spreadsheet.git;
cd react-spreadsheet;
yarn install;