gridjs-spreadsheet 26.7.0 → 26.8.0

package/readme.md

@@ -1,14 +1,51 @@
-# gridjs-spreadsheet
+# gridjs-spreadsheet | Lightweight Online Excel Editor & Web Spreadsheet API
 
-`gridjs-spreadsheet` is the browser-side spreadsheet UI for Aspose.Cells GridJs. The package includes the core GridJS runtime, TypeScript declarations, and adapters for React, Vue 3, and Angular.
+> **GridJs-Spreadsheet** is a high-performance, lightweight JavaScript library for building online Excel editors and web-based spreadsheet applications. It provides seamless Excel viewing, editing, and cross-platform deployment with an easy-to-use API.
+>
+> **Now with first-class support for Vue 3, React, and Angular.**
+
+## Why Choose GridJs-Spreadsheet?
+
+Whether you are building a collaborative document platform, a data management tool, or an Excel viewer for your web app, GridJs-Spreadsheet offers a comprehensive solution with a tiny footprint.
+
+- Rich Excel-compatible editing experience — formulas, formatting, charts, images, form controls
+- First-class framework wrappers for **React**, **Vue 3**, and **Angular** — drop-in components with zero boilerplate
+- Full TypeScript declarations for IntelliSense and type safety
+- Server-backed or client-only mode — works with any backend (.NET, Java, Python, Node.js)
+- 17+ UI languages out of the box
+- MIT licensed — free for commercial and open-source projects
+
+## Preview
+
+<img alt="GridJS spreadsheet preview" src="https://unpkg.com/gridjs-spreadsheet@26.7.0/preview.gif">
+
+Quick online demo: <https://products.aspose.app/cells/editor>
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Package Exports](#package-exports)
+- [Usage](#usage)
+  - [Vanilla JavaScript (npm)](#vanilla-javascript-with-npm)
+  - [Vanilla HTML (CDN)](#vanilla-html-with-script-tags)
+  - [React](#react)
+  - [Vue 3](#vue-3)
+  - [Angular](#angular)
+- [Framework Adapter API](#framework-adapter-api)
+- [Core API](#core-api)
+- [Features](#features)
+- [Backend Endpoints](#backend-endpoints)
+- [Example Project](#example-project)
+- [Browser Support](#browser-support)
+- [Version History](#version-history)
+- [Resources](#resources)
+- [License](#license)
 
-Version 26.7.0 also publishes a complete Java example containing five independent frontend demos:
+## About
 
-- React
-- Vue 3
-- Angular
-- Vanilla HTML using npm imports
-- Vanilla HTML using CDN script tags
+GridJs-Spreadsheet allows you to view and edit spreadsheet files directly in the browser. It is developed based on [x-spreadsheet](https://github.com/myliang/x-spreadsheet) and extended with enterprise-grade features including chart rendering, form controls, data redaction, multi-sheet support, and server-side integration APIs.
+
+The package includes the core GridJS runtime, TypeScript declarations, and ready-to-use adapters for **React**, **Vue 3**, and **Angular**.
 
 ## Installation
 
@@ -16,20 +53,33 @@ Version 26.7.0 also publishes a complete Java example containing five independen
 npm install gridjs-spreadsheet
 ```
 
-The framework packages are optional peer dependencies. Install only the framework used by your application.
+The framework packages are optional peer dependencies — install only the framework used by your application:
+
+```bash
+# install for React
+npm install react react-dom
+
+# install for Vue 3
+npm install vue
+
+# install for Angular
+npm install @angular/core @angular/common
+```
 
-## Package exports
+## Package Exports
 
 | Usage | Import |
 | --- | --- |
 | Core runtime | `gridjs-spreadsheet` |
 | Styles | `gridjs-spreadsheet/xspreadsheet.css` |
-| React | `gridjs-spreadsheet/react` |
-| Vue 3 | `gridjs-spreadsheet/vue` |
-| Angular | `gridjs-spreadsheet/angular` |
+| React component | `gridjs-spreadsheet/react` |
+| Vue 3 component | `gridjs-spreadsheet/vue` |
+| Angular component | `gridjs-spreadsheet/angular` |
 | Shared adapter | `gridjs-spreadsheet/shared` |
 
-## Vanilla JavaScript with npm
+## Usage
+
+### Vanilla JavaScript with npm
 
 ```html
 <div id="gridjs-demo"></div>
@@ -46,6 +96,7 @@ const spreadsheet = new Spreadsheet('#gridjs-demo', {
   updateMode: 'server',
   updateUrl: '/GridJs2/UpdateCell',
   mode: 'edit',
+  // Support 17+ languages: en, cn, es, pt, de, ru, nl, ar, fr, id, it, ja, ko, th, tr, vi, cht
   local: 'en',
 });
 
@@ -54,7 +105,7 @@ spreadsheet.setUniqueId(workbookJson.uniqueid);
 spreadsheet.setFileName(workbookJson.filename);
 ```
 
-## Vanilla HTML with script tags
+### Vanilla HTML with script tags
 
 ```html
 <link
@@ -63,7 +114,7 @@ spreadsheet.setFileName(workbookJson.filename);
 >
 
 <script src="https://unpkg.com/jszip@3.10.1/dist/jszip.min.js"></script>
-<script src="https://unpkg.com/gridjs-spreadsheet@26.7.0/xspreadsheet.js"></script>
+<script src="https://unpkg.com/gridjs-spreadsheet/xspreadsheet.js"></script>
 
 <div id="gridjs-demo"></div>
 
@@ -79,7 +130,7 @@ spreadsheet.setFileName(workbookJson.filename);
 </script>
 ```
 
-## React
+### React
 
 ```jsx
 import { useState } from 'react';
@@ -97,13 +148,15 @@ export default function App() {
       locale="en"
       height="600px"
       onReady={(instance, adapter) => console.log('ready', instance, adapter)}
+      onChange={(...args) => console.log('changed', args)}
+      onCellSelected={(...args) => console.log('cell selected', args)}
       onError={(error) => console.error(error)}
     />
   );
 }
 ```
 
-## Vue 3
+### Vue 3
 
 ```vue
 <template>
@@ -113,6 +166,8 @@ export default function App() {
     locale="en"
     height="600px"
     @ready="onReady"
+    @change="onChange"
+    @cell-selected="onCellSelected"
     @error="onError"
   />
 </template>
@@ -124,11 +179,13 @@ import 'gridjs-spreadsheet/xspreadsheet.css';
 
 const sheetData = ref(null);
 const onReady = (instance, adapter) => console.log('ready', instance, adapter);
+const onChange = (...args) => console.log('changed', args);
+const onCellSelected = (...args) => console.log('cell selected', args);
 const onError = error => console.error(error);
 </script>
 ```
 
-## Angular
+### Angular
 
 ```ts
 import { Component } from '@angular/core';
@@ -145,6 +202,8 @@ import { GridJsSpreadsheetComponent } from 'gridjs-spreadsheet/angular';
       locale="en"
       height="600px"
       (ready)="onReady($event)"
+      (change)="onChange($event)"
+      (cellSelected)="onCellSelected($event)"
       (error)="onError($event)"
     />
   `,
@@ -152,6 +211,8 @@ import { GridJsSpreadsheetComponent } from 'gridjs-spreadsheet/angular';
 export class AppComponent {
   sheetData: any = null;
   onReady(event: any) { console.log('ready', event); }
+  onChange(args: any[]) { console.log('changed', args); }
+  onCellSelected(args: any[]) { console.log('cell selected', args); }
   onError(error: any) { console.error(error); }
 }
 ```
@@ -165,77 +226,376 @@ Add the GridJS stylesheet to `angular.json`:
 ]
 ```
 
-## Framework adapter inputs
+## Framework Adapter API
 
 The React, Vue, and Angular adapters share the same configuration model:
 
-| Option | Description |
-| --- | --- |
-| `apiBase` | Optional prefix for GridJS backend endpoints |
-| `data` | Workbook JSON returned by the GridJS backend |
-| `loader` | Function that asynchronously returns workbook JSON |
-| `mode` | `edit` or `read` |
-| `locale` | GridJS UI locale |
-| `token` | Optional authorization token |
-| `height` | Component height |
-| `showToolbar` | Show or hide the toolbar |
-| `showContextmenu` | Show or hide the context menu |
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiBase` | `string` | `''` | Prefix for GridJS backend endpoints |
+| `data` | `object` | `null` | Workbook JSON returned by the GridJS backend |
+| `loader` | `function` | `null` | Async function that returns workbook JSON |
+| `mode` | `'edit' \| 'read'` | `'edit'` | Editing mode |
+| `locale` | `string` | `'en'` | UI language locale |
+| `token` | `string` | `''` | Authorization token for server requests |
+| `height` | `string \| number` | `'calc(100vh - 96px)'` | Component height |
+| `showToolbar` | `boolean` | `true` | Show or hide the toolbar |
+| `showContextmenu` | `boolean` | `true` | Show or hide the context menu |
 
-The adapters expose ready, change, error, cell selection, cell editing, sheet selection, and sheet loading events using each framework's normal event conventions.
+**Events:** All adapters expose `ready`, `change`, `error`, `cellSelected`, `cellEdited`, `sheetSelected`, and `sheetLoaded` events using each framework's normal event conventions.
 
-GridJS requires a browser DOM. Mount the adapters on the client when using an SSR framework.
+> **Note:** GridJS requires a browser DOM. When using SSR frameworks (Next.js, Nuxt, Angular Universal), mount the adapters on the client side only.
 
-## Java example included in the package
+## Core API
 
-The published package contains `example/`, including a Spring Boot backend and all five frontend projects. Copy it to a writable directory before running it:
+The core `Spreadsheet` class provides a rich JavaScript API:
 
-```bash
-npm install gridjs-spreadsheet
-cp -R node_modules/gridjs-spreadsheet/example ./gridjs-example
-cd gridjs-example
+```js
+const xs = new Spreadsheet('#container', options);
+
+// Load data
+xs.loadData(jsonData);
+
+// Bind events
+xs.on('cell-selected', (cell, ri, ci) => { });
+xs.on('cells-selected', (cell, { sri, sci, eri, eci }) => { });
+xs.on('cell-edited', (text, ri, ci) => { });
+xs.on('object-selected', (obj) => { });
+xs.on('cells-updated', (name, cells) => { });
+xs.on('rows-inserted', (ri, n) => { });
+xs.on('columns-inserted', (ci, n) => { });
+xs.on('rows-deleted', (ri, n) => { });
+xs.on('columns-deleted', (ci, n) => { });
+xs.on('cells-deleted', (range) => { });
+
+// Cell operations
+xs.cellText(5, 5, 'Hello');
+xs.cell(ri, ci);
+xs.cellStyle(ri, ci);
+
+// Sheet operations
+xs.setActiveSheet(index);
+xs.setActiveSheetByName('Sheet2');
+xs.setActiveCell(rowIndex, colIndex);
+xs.getData();
+
+// Server integration
+xs.setUniqueId('workbook-id');
+xs.setFileName('report.xlsx');
+xs.refreshToken(token);
+
+// Cleanup
+xs.destroy();
 ```
 
-Start the Java backend in the first terminal:
+Full API documentation: [API Reference](https://docs.aspose.com/cells/net/aspose-cells-gridjs/how-to-use-gridjs-client-api/)
 
-```bash
-./mvnw spring-boot:run -Dmaven.test.skip=true
+### Default Options
+
+```js
+{
+  mode: 'edit',          // 'edit' | 'read'
+  showToolbar: true,
+  showGrid: true,
+  showContextmenu: true,
+  view: {
+    height: () => document.documentElement.clientHeight,
+    width: () => document.documentElement.clientWidth,
+  },
+  row: { len: 100, height: 25 },
+  col: { len: 26, width: 100, indexWidth: 60, minWidth: 60 },
+  style: {
+    bgcolor: '#ffffff',
+    align: 'left',
+    valign: 'middle',
+    textwrap: false,
+    color: '#0a0a0a',
+    font: { name: 'Helvetica', size: 10, bold: false, italic: false },
+  },
+}
 ```
 
-Start a frontend in a second terminal, for example React:
+## Features
+
+### Rich Editing & Formatting
+- Font / Font size / Bold / Italic / Underline / Strikethrough
+- Text color / Alignment / Text wrapping
+- Fill color / Highlight
+- Number format / Rich text support
+- Borders / Conditional formatting
+- Format painter / Clear format
+
+### Data Management & Analysis
+- Full formula support
+- Filter / Sort rows and columns
+- Data validations (including multi-select lists)
+- Copy / Cut / Paste / Autofill — including from MS Excel
+- Merge cells / Freeze panes
+- Insert / Delete rows and columns
+- Resize row height / column width
+- Zoom in / out
+- Search and replace
+- Statistics information in the status bar
+
+### Visuals & Objects
+- Charts rendering (bar, line, pie, area, and more)
+- Conditional formatting icons
+- Shape / Image resize, rotate, and position adjustment
+- Insert / Delete / Copy shapes and images
+- Form controls / ActiveX controls display
+- Insert / Delete form controls
+- Two-color gradient fill effects
+
+### Security & Advanced Tools
+- Data redaction — burn sensitive data permanently
+- Comments — add / edit / delete
+- Hyperlinks — add / delete
+- Print support
+- Localization — 17+ UI languages
+- Mobile responsive compatibility
+- Custom toolbar buttons
+- Lazy loading for large workbooks
+
+## Backend Endpoints
+
+The adapters use the standard Aspose.Cells GridJs endpoints:
+
+- `/GridJs2/UpdateCell` — cell update
+- `/GridJs2/ImageUrl` — image retrieval
+- `/GridJs2/AddImage` — upload local image
+- `/GridJs2/AddImageByURL` — upload image by URL
+- `/GridJs2/CopyImage` — copy image
+- `/GridJs2/Download` — file download
+- `/GridJs2/Ole` — OLE object download
+- `/GridJs2/LazyLoadingStreamJson` — lazy loading
+
+## Example Project
+
+The package includes a complete `example/` directory with a Spring Boot backend and five independent frontend demos (React, Vue 3, Angular, Vanilla npm, Vanilla CDN).
 
 ```bash
-cd react-gridjs
-npm install
-npm run dev
+cp -R node_modules/gridjs-spreadsheet/example ./gridjs-example
+cd gridjs-example
+./mvnw spring-boot:run -Dmaven.test.skip=true
 ```
 
 See [`example/README.md`](example/README.md) for all framework commands, ports, backend configuration, and troubleshooting.
 
-## Backend endpoints
+Additional demos for .NET, Java, and Python:
 
-The adapters use the standard Aspose.Cells GridJs endpoints, including:
+- <https://github.com/aspose-cells/Aspose.Cells.Grid-for-.NET/tree/master/Examples_GridJs>
+- <https://github.com/aspose-cells/Aspose.Cells.Grid-for-Java/tree/master/Examples.GridJs>
+- <https://github.com/aspose-cells/Aspose.Cells.Grid-for-Python-via-.NET/tree/main/Examples.GridJs>
 
-- `/GridJs2/UpdateCell`
-- `/GridJs2/ImageUrl`
-- `/GridJs2/AddImage`
-- `/GridJs2/AddImageByURL`
-- `/GridJs2/CopyImage`
-- `/GridJs2/Download`
-- `/GridJs2/Ole`
-- `/GridJs2/LazyLoadingStreamJson`
+## Browser Support
 
-The example frontend development servers proxy `/GridJs2` and `/gridjsdemo` to the Java backend on port 8080.
+Modern browsers — Chrome, Firefox, Safari, Edge.
 
-## Preview
+## Version History
 
-<img alt="GridJS spreadsheet preview" src="https://unpkg.com/gridjs-spreadsheet@26.7.0/preview.gif">
+<details>
+<summary><strong>v26.8</strong> — Support redaction for entire sheet</summary>
+
+- Support redaction for entire sheet
+- Support redaction for sheet name
+</details>
+
+<details>
+<summary><strong>v26.7.1</strong> — Improve performance for redaction</summary>
+
+- Improve performance for redaction
+</details>
+
+<details>
+<summary><strong>v26.7</strong> — Fix issue for filter in merge area</summary>
+
+- Fix issue for filter in merge area
+</details>
+
+<details>
+<summary><strong>v26.6</strong> — Improve redaction</summary>
+
+- Improve redaction feature
+- Fix redaction font issue
+- Fix redaction transparent view issue
+</details>
+
+<details>
+<summary><strong>v26.5</strong> — Custom toolbar buttons, date picker, filter, print</summary>
+
+- Support add custom buttons in toolbar
+- Improve date picker
+- Improve filter display
+- Improve print
+- Improve scroll in zoom
+</details>
+
+<details>
+<summary><strong>v26.4</strong> — Redaction, shape lock, zoom snap</summary>
+
+- Add redaction features
+- Fix paste scroll issue
+- Support shape lock
+- Support snap to cell area in zoom in/out
+- Add boundary check for redaction
+</details>
+
+<details>
+<summary><strong>v26.3</strong> — Improve filter/validations/charts</summary>
+
+- Improve filter/validations/charts
+</details>
+
+<details>
+<summary><strong>v26.2</strong> — Performance improvement for large rows</summary>
+
+- Improve client performance for large rows
+</details>
+
+<details>
+<summary><strong>v26.1</strong> — Rotated text highlight, more charts</summary>
+
+- Support highlight text with rotation
+- Support more charts rendering in client
+</details>
+
+<details>
+<summary><strong>v25.12</strong> — Sort by color, multi-select validation</summary>
+
+- Support sort by cell color/font color
+- Support add multiple selection validation list
+</details>
+
+<details>
+<summary><strong>v25.11</strong> — Chart fill colors, color picker</summary>
+
+- Support fill color settings for charts
+- Support 'Fill Color' and 'Font Color' button dropdown selection and click to fill
+</details>
+
+<details>
+<summary><strong>v25.10</strong> — Custom toast, modal CSS</summary>
+
+- Support APIs to set customToast
+- Support CSS identify for model window
+</details>
+
+<details>
+<summary><strong>v25.9</strong> — Pattern fill style</summary>
+
+- Support to render pattern style for cell
+</details>
+
+<details>
+<summary><strong>v25.8</strong> — Auto text wrap, textbox font</summary>
+
+- Support automatic text wrapping
+- Support API to apply font setting in textbox control
+</details>
+
+<details>
+<summary><strong>v25.7</strong> — Editable range, worksheet/comment/range APIs</summary>
+
+- Support APIs to enable/disable editable range
+- Support APIs to add/modify/delete worksheet
+- Support APIs to add/modify/delete comment
+- Support APIs to set attribute for range of cells
+- Support APIs to delete for range of cells
+</details>
+
+<details>
+<summary><strong>v25.6</strong> — Resize/hide rows and columns</summary>
+
+- Support APIs for resize rows/columns
+- Support APIs for hide/unhide rows/columns
+</details>
+
+<details>
+<summary><strong>v25.5</strong> — Polish locale, row/column APIs</summary>
+
+- Add support for Polish menus
+- Support APIs for insert/delete rows/columns
+</details>
+
+<details>
+<summary><strong>v25.4</strong> — Status bar statistics</summary>
+
+- Support show statistics information in the lower right corner when cells are selected
+</details>
+
+<details>
+<summary><strong>v25.3</strong> — Shortcut keys, multi-area paste</summary>
+
+- Support more shortcut keys
+- Support pasting the content copied from Excel to multiple target areas
+</details>
+
+<details>
+<summary><strong>v25.2</strong> — Excel paste, auto operations</summary>
+
+- Support copy/paste from MS-Excel
+- Enhancement for automatic operations — extending blank row/column, page scrolling, etc.
+</details>
+
+<details>
+<summary><strong>v25.1</strong> — Excel copy/paste</summary>
+
+- Support copy/paste from MS-Excel
+</details>
+
+<details>
+<summary><strong>v24.12</strong> — HTML nodes, multi-instance, row/column events</summary>
+
+- Support API to show HTML nodes and interact with HTML nodes at specified cell positions
+- Support pre-check event for row/column delete/insert operations
+- Support row/column insert/delete events for client APIs
+- Support events for updating cells
+- Support multiple instances on one page
+</details>
+
+<details>
+<summary><strong>v24.11</strong> — Rich text display</summary>
+
+- Improve the display of rich text cell values
+</details>
+
+<details>
+<summary><strong>v24.10</strong> — Show formulas</summary>
+
+- Support a view option to show formulas
+</details>
+
+<details>
+<summary><strong>v24.9.1</strong> — Initial release</summary>
+
+- Fix bug that fail to insert column in the new added worksheet
+- Fix bug that fail to rename worksheet
+- Support lazy loading
+</details>
 
 ## Resources
 
-- [Aspose.Cells product page](https://products.aspose.com/cells/java/)
-- [Aspose.Cells GridJs documentation](https://docs.aspose.com/cells/java/aspose-cells-gridjs/)
-- [API reference](https://reference.aspose.com/cells/java/com.aspose.gridjs/)
-- [Free support forum](https://forum.aspose.com/c/cells)
+### Documentation
+- [Developer's Guide — .NET / C#](https://docs.aspose.com/cells/net/aspose-cells-gridjs/)
+- [Developer's Guide — Java](https://docs.aspose.com/cells/java/aspose-cells-gridjs/)
+- [Developer's Guide — Python](https://docs.aspose.com/cells/python-net/aspose-cells-gridjs/)
+- [Client API How-To](https://docs.aspose.com/cells/net/aspose-cells-gridjs/how-to-use-gridjs-client-api/)
+
+### Product Links
+- [Aspose.Cells Product Page](https://products.aspose.com/cells)
+- [GridJs Online Demo](https://products.aspose.app/cells/editor)
+- [API Reference — .NET / C#](https://reference.aspose.com/cells/net/aspose.cells.gridjs/)
+- [API Reference — Java](https://reference.aspose.com/cells/java/com.aspose.gridjs/)
+- [API Reference — Python](https://reference.aspose.com/cells/python-net/aspose.cellsgridjs/)
+- [Blog](https://blog.aspose.com/categories/aspose.cells-product-family/)
+
+### Source Code & Samples
+- [.NET Examples](https://github.com/aspose-cells/Aspose.Cells.Grid-for-.NET/tree/main/Examples_GridJs)
+- [Java Examples](https://github.com/aspose-cells/Aspose.Cells.Grid-for-Java/tree/master/Examples.GridJs)
+- [Python Examples](https://github.com/aspose-cells/Aspose.Cells.Grid-for-Python-via-.NET/tree/main/Examples.GridJs)
+
+### Free Support
+- [Aspose.Cells Forum](https://forum.aspose.com/c/cells) — ask questions, request features, report bugs
 
 ## License