gridjs-spreadsheet 26.6.1 → 26.7.0

package/example/README.md

@@ -1,71 +1,272 @@
-[Product Page](https://products.aspose.com/cells/java) | [Docs](https://docs.aspose.com/cells/java/aspose-cells-gridjs/) | [API Reference](https://reference.aspose.com/cells/java/com.aspose.gridjs/) | [Demos](https://products.aspose.app/cells/family/) | [Blog](https://blog.aspose.com/category/cells/) | [Code Samples](https://github.com/aspose-cells/Aspose.Cells-for-Java/tree/master/Examples.GridJs) | [Free Support](https://forum.aspose.com/c/cells) | [Temporary License](https://purchase.aspose.com/temporary-license) | [EULA](https://company.aspose.com/legal/eula) 
+# Aspose.Cells GridJs Java framework examples
 
-Try our [free online apps](https://products.aspose.app/cells/family) demonstrating some of the most popular Aspose.Cells functionality.
+This directory contains one Spring Boot backend shared by five independent frontend demos:
 
-[Aspose.Cells.GridJs for Java](http://www.aspose.com/products/cells/java)  is a lightweight, scalable, and customizable toolkit that provides cross-platform web applications, enables convenient development for editing or viewing Excel/Spreadsheet files, offers simple deployment, and provides easy-to-use APIs.
+| Demo | Directory | Development URL |
+| --- | --- | --- |
+| React | `react-gridjs` | `http://127.0.0.1:5173` |
+| Vue 3 | `vue-gridjs` | `http://127.0.0.1:5174` |
+| Angular | `angular-gridjs` | `http://127.0.0.1:4200` |
+| Vanilla HTML with npm | `vanilla-gridjs/npm` | `http://127.0.0.1:5175` |
+| Vanilla HTML with CDN scripts | `vanilla-gridjs/script` | `http://127.0.0.1:5176` |
 
-This is a  demo to show how we can use GridJs to implment a spreadsheet Editor .
- 
+The frontend files are served by Vite or Angular CLI during development. They are not copied into the Java application. Each development server proxies GridJS API requests to the Java backend on port 8080.
 
-## Preview
+## Requirements
 
- <img alt='demo' src='https://unpkg.com/gridjs-spreadsheet@25.1.0/preview.gif' />
+- Java 8 or newer
+- Node.js 18 or newer
+- npm
+- Angular demo: Node.js 18, 20, or 22
+
+## Configure the Java backend
+
+Edit `src/main/resources/application.properties` when the default local paths do not match your environment:
 
-## How to Run the Examples
-###1.edit the properties in src\main\resources\application.properties to meet your local environment
 ```properties
-# This is the directory contains the spread sheet files
-testconfig.ListDir=/app/wb
+testconfig.ListDir=/path/to/workbooks
+testconfig.CachePath=/path/to/grid_cache
+testconfig.UploadPath=/path/to/upload
+testconfig.AsposeLicensePath=/path/to/license
+```
+
+The repository example already contains local `wb`, `grid_cache`, and `upload` directories for development.
+
+## 1. Start the Java backend
+
+Open the first terminal in this `example` directory.
+
+macOS or Linux:
+
+```bash
+./mvnw spring-boot:run -Dmaven.test.skip=true
+```
+
+Windows:
+
+```bat
+mvnw.cmd spring-boot:run -Dmaven.test.skip=true
+```
+
+Wait until Spring Boot is listening on:
+
+```text
+http://127.0.0.1:8080
+```
+
+Backend health endpoint:
+
+```text
+http://127.0.0.1:8080/gridjsdemo/api/health
+```
+
+The legacy server-rendered Java page remains available at:
+
+```text
+http://127.0.0.1:8080/gridjsdemo/list
+```
+
+## 2. Start a frontend
+
+Open a second terminal. Install dependencies inside the selected frontend folder, then run its npm development command.
 
-# Directory for storing cache files
-testconfig.CachePath=/app/grid_cache
+### React
 
-# Directory for storing upload files
-testconfig.UploadPath=/app/upload
+```bash
+cd react-gridjs
+npm install
+npm run dev
+```
+
+Open `http://127.0.0.1:5173`.
+
+The application imports:
+
+```js
+import { GridJsSpreadsheet } from 'gridjs-spreadsheet/react';
+import 'gridjs-spreadsheet/xspreadsheet.css';
+```
 
-# License file for Aspose.Cells
-testconfig.AsposeLicensePath=/app/license
+### Vue 3
+
+```bash
+cd vue-gridjs
+npm install
+npm run dev
 ```
-###2.run src\main\java\com\aspose\gridjs\demo\GridjsdemoApplication.java
 
-open browser and navigate to view all the files in the directory at http://localhost:8080/gridjsdemo/list
+Open `http://127.0.0.1:5174`.
+
+The application imports:
 
-## Step to run in docker 
+```js
+import { GridJsSpreadsheet } from 'gridjs-spreadsheet/vue';
+import 'gridjs-spreadsheet/xspreadsheet.css';
+```
 
-1. docker build -t gridjs-demo-java .
+### Angular
 
-2. run with aspose license file:
+Use Node.js 18, 20, or 22:
 
 ```bash
-      docker run -d -p 8080:8080  -v C:/path/to/license.txt:/app/license gridjs-demo-java
+cd angular-gridjs
+npm install
+npm run dev
+```
+
+Open `http://127.0.0.1:4200`.
+
+The application imports:
+
+```ts
+import { GridJsSpreadsheetComponent } from 'gridjs-spreadsheet/angular';
 ```
 
-   or just run the demo in trial mode:
-   
+### Vanilla HTML with npm
+
 ```bash
-      docker run -d -p 8080:8080 gridjs-demo-java
+cd vanilla-gridjs/npm
+npm install
+npm run dev
+```
+
+Open `http://127.0.0.1:5175`.
+
+The application imports the GridJS runtime and stylesheet from npm:
+
+```js
+import Spreadsheet from 'gridjs-spreadsheet';
+import JSZip from 'jszip';
+import 'gridjs-spreadsheet/xspreadsheet.css';
+
+window.JSZip = JSZip;
 ```
-      
-3. open browser and enter the url: http://localhost:8080/gridjsdemo/list
 
-## Reference js lib used in the demo project:
-jquery.js    v2.1.1
+### Vanilla HTML with CDN script tags
+
+```bash
+cd vanilla-gridjs/script
+npm install
+npm run dev
+```
 
-jquery-ui.js v1.12.1 
+Open `http://127.0.0.1:5176`.
 
-jquery-ui.css v1.12.1 
+This project loads GridJS and JSZip directly from CDN script tags. npm installs only the Vite development server.
 
-jszip.min.js v3.6.0 
+## Why the frontend can access Java
 
-bootstrap.css   v22.5.5.2
+The frontend applications call relative URLs such as:
 
-quantumui.css   v22.5.5.2
+```text
+/gridjsdemo/api/files
+/gridjsdemo/api/upload
+/GridJs2/DetailStreamJsonWithUid
+/GridJs2/UpdateCell
+/GridJs2/Download
+```
+
+Vite and Angular CLI proxy the `/gridjsdemo` and `/GridJs2` prefixes to `http://127.0.0.1:8080`:
+
+```text
+Browser :5173/:5174/:4200/:5175/:5176
+  -> frontend development proxy
+  -> Java Spring Boot :8080
+  -> Aspose.Cells GridJs service
+  -> JSON response
+  -> frontend GridJS component
+```
+
+The browser sees a same-origin request to its frontend server, so separate CORS configuration is not required for local development.
+
+## Open a workbook directly
+
+After the backend and frontend are running, a workbook can be opened through query parameters:
+
+```text
+http://127.0.0.1:5174/?file=chart.xlsx&demo=permanent&uid=vue-uid-chart-xlsx
+```
+
+Supported demo modes:
+
+- `permanent`: uses a UID-backed GridJS cache.
+- `highlight`: loads the workbook without the persistent UID route.
+
+## Upload file names
+
+Uploaded files use two names:
+
+- `file`: the original name shown in GridJS and used for downloads.
+- `storedFile`: the unique internal filename used by the Java upload directory.
+
+The URL retains both values so a refreshed page can reopen the internal file while continuing to display the original filename.
+
+## Run multiple demos together
+
+Start Java once, then run `npm run dev` in multiple frontend directories. Their ports are different, and their GridJS UIDs use different framework prefixes, so the demos do not conflict.
+
+Stopping one frontend does not stop Java or the other frontend demos. Press `Ctrl+C` in each terminal to stop the corresponding process.
+
+## Production builds
+
+Each frontend can be built independently:
+
+```bash
+npm run build
+```
+
+The output is written to that project's `dist` directory. This example intentionally demonstrates separate frontend development servers; it does not copy the frontend output into Spring Boot.
+
+## npm package version
+
+Each npm-based frontend declares:
+
+```json
+"gridjs-spreadsheet": "latest"
+```
+
+Running `npm install` resolves the npm registry's current latest release. The framework exports used by these demos require `gridjs-spreadsheet` 26.7.0 or newer.
+
+Package lock files are intentionally not published with the example. Users may generate their own lock files when installing dependencies.
+
+## Troubleshooting
+
+### Frontend reports `ECONNREFUSED` or proxy errors
+
+Confirm that Java is running on port 8080 and open the health URL:
+
+```text
+http://127.0.0.1:8080/gridjsdemo/api/health
+```
+
+### A frontend port is already occupied
+
+Stop the existing process using that port. All frontend commands use strict ports to avoid silently opening a different URL.
+
+### Angular rejects the current Node.js version
+
+Use Node.js 18, 20, or 22. Node.js 23 and newer are outside the supported range of the included Angular 18 project.
+
+### Framework import path cannot be resolved
+
+Run `npm install` again and verify that the installed `gridjs-spreadsheet` version is 26.7.0 or newer.
+
+### Trial warning appears in the workbook
+
+Configure `testconfig.AsposeLicensePath` with a valid Aspose.Cells license, or continue using the example in evaluation mode.
+
+## Docker
+
+The Docker configuration runs the Java backend and legacy server-rendered page. The five framework demos remain separate npm development projects.
+
+```bash
+docker build -t gridjs-demo-java .
+docker run -d -p 8080:8080 gridjs-demo-java
+```
 
 ## Resources
 
-+ **Website:** [www.aspose.com](http://www.aspose.com) 
-+ **Product Home:** [Aspose.Cells for Java](http://www.aspose.com/products/cells/java)
-+ **Download:** [Download Aspose.Cells for Java](https://downloads.aspose.com/cells/java)
-+ **Documentation:** [Aspose.Cells for Java Documentation](https://docs.aspose.com/display/cellsjava/Home)
-+ **Forum:** [Aspose.Cells for Java Forum](http://www.aspose.com/community/forums/aspose.cells-product-family/19/showforum.aspx)
-+ **Blog:** [Aspose.Cells for Java Blog](https://blog.aspose.com/category/aspose-products/aspose-cells-product-family/)
+- [Aspose.Cells for Java](https://products.aspose.com/cells/java/)
+- [Aspose.Cells GridJs documentation](https://docs.aspose.com/cells/java/aspose-cells-gridjs/)
+- [GridJs Java API reference](https://reference.aspose.com/cells/java/com.aspose.gridjs/)
+- [Aspose.Cells support forum](https://forum.aspose.com/c/cells)

package/example/angular-gridjs/.nvmrc

@@ -0,0 +1 @@
+22

package/example/angular-gridjs/angular.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "gridjs-angular-demo": {
+      "projectType": "application",
+      "schematics": {},
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:application",
+          "options": {
+            "outputPath": "dist/gridjs-angular-demo",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "polyfills": ["zone.js"],
+            "tsConfig": "tsconfig.app.json",
+            "assets": ["src/favicon.ico"],
+            "allowedCommonJsDependencies": ["gridjs-spreadsheet", "jszip"],
+            "styles": [
+              "node_modules/gridjs-spreadsheet/xspreadsheet.css",
+              "src/styles.css"
+            ],
+            "scripts": []
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "5mb",
+                  "maximumError": "8mb"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "gridjs-angular-demo:build:production"
+            },
+            "development": {
+              "buildTarget": "gridjs-angular-demo:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        }
+      }
+    }
+  },
+  "cli": {
+    "analytics": false
+  }
+}

package/example/angular-gridjs/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "gridjs-angular-java-demo",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "cross-env NG_BUILD_MAX_WORKERS=1 ng serve --host 127.0.0.1 --port 4200 --proxy-config proxy.conf.json",
+    "build": "cross-env NG_BUILD_MAX_WORKERS=1 ng build"
+  },
+  "dependencies": {
+    "@angular/animations": "18.2.14",
+    "@angular/common": "18.2.14",
+    "@angular/compiler": "18.2.14",
+    "@angular/core": "18.2.14",
+    "@angular/platform-browser": "18.2.14",
+    "gridjs-spreadsheet": "latest",
+    "jszip": "^3.10.1",
+    "rxjs": "~7.8.1",
+    "tslib": "^2.6.2",
+    "zone.js": "~0.14.10"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "18.2.21",
+    "@angular/cli": "18.2.21",
+    "@angular/compiler-cli": "18.2.14",
+    "cross-env": "^7.0.3",
+    "typescript": "~5.5.4"
+  },
+  "engines": {
+    "node": ">=18 <23"
+  }
+}

package/example/angular-gridjs/proxy.conf.json

@@ -0,0 +1,12 @@
+{
+  "/GridJs2": {
+    "target": "http://127.0.0.1:8080",
+    "secure": false,
+    "changeOrigin": true
+  },
+  "/gridjsdemo": {
+    "target": "http://127.0.0.1:8080",
+    "secure": false,
+    "changeOrigin": true
+  }
+}

package/example/angular-gridjs/src/app/api.ts

@@ -0,0 +1,7 @@
+// Small fetch() wrapper that turns non-2xx responses into thrown Errors,
+// so callers can just `await fetchJson(url)` and catch failures in one place.
+export async function fetchJson<T>(url: string, options?: RequestInit): Promise<T> {
+  const response = await fetch(url, options);
+  if (!response.ok) throw new Error(response.status + ' ' + response.statusText);
+  return response.json() as Promise<T>;
+}

package/example/angular-gridjs/src/app/app.component.html

@@ -0,0 +1,57 @@
+<!-- A workbook is selected -> render the full-page spreadsheet editor. -->
+<main *ngIf="current; else startPage" class="editor-page">
+  <gridjs-spreadsheet
+    *ngIf="workbookData; else loadingEditor"
+    [data]="workbookData"
+    height="100vh"
+    [showToolbar]="true"
+    [showContextmenu]="true"
+    (ready)="onReady($event)"
+    (change)="logEvent('changed')"
+    (error)="onError($event)"
+    (cellSelected)="logEvent('cell selected ' + (($event && $event[1]) ?? '') + ',' + (($event && $event[2]) ?? ''))"
+    (cellEdited)="logEvent('cell edited ' + (($event && $event[1]) ?? '') + ',' + (($event && $event[2]) ?? ''))"
+    (sheetSelected)="logEvent('sheet ' + (($event && $event[1]) ?? ''))"
+  ></gridjs-spreadsheet>
+  <ng-template #loadingEditor>
+    <div class="editor-loading">{{ status }}</div>
+  </ng-template>
+</main>
+
+<!-- No workbook selected -> render the start page (demo picker + file list + upload). -->
+<ng-template #startPage>
+  <div class="demo-shell">
+    <header class="demo-navbar">
+      <a href="https://docs.aspose.com/cells/java/aspose-cells-gridjs/">Aspose.Cells.GridJs demo for Java</a>
+    </header>
+    <main class="demo-container">
+      <fieldset class="demo-selector">
+        <legend>Select a demo:</legend>
+        <label [class]="demoType === DEMO_PERMANENT ? 'radio-card active' : 'radio-card'">
+          <input type="radio" name="demoType" [checked]="demoType === DEMO_PERMANENT" (change)="demoType = DEMO_PERMANENT" />
+          <span>permanent url load demo</span>
+        </label>
+        <label [class]="demoType === DEMO_HIGHLIGHT ? 'radio-card active' : 'radio-card'">
+          <input type="radio" name="demoType" [checked]="demoType === DEMO_HIGHLIGHT" (change)="demoType = DEMO_HIGHLIGHT" />
+          <span>highlight and custom context menu demo</span>
+        </label>
+      </fieldset>
+      <section class="upload-block">
+        <h4>Upload a local file to start show workbook</h4>
+        <input type="file" accept=".xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" (change)="upload($event)" />
+      </section>
+      <section class="path-block">
+        <h4>The specific file path : {{ directory }}</h4>
+        <h4>Navigate one of the below file to start show workbook</h4>
+      </section>
+      <p class="status-message" role="status">{{ status }}</p>
+      <section class="file-list" aria-label="Workbook files">
+        <p *ngIf="status === 'Ready' && files.length === 0" class="empty-message">No workbooks found in the configured directory.</p>
+        <a *ngFor="let file of files" [href]="'/?file=' + file" class="file-item" (click)="$event.preventDefault(); openFile(file)">
+          <em>{{ file }}</em>
+        </a>
+      </section>
+    </main>
+    <footer class="demo-footer">© 2026 - <a href="https://products.aspose.com/cells/java">Aspose.Cells for Java</a></footer>
+  </div>
+</ng-template>

package/example/angular-gridjs/src/app/app.component.ts

@@ -0,0 +1,153 @@
+import { CommonModule } from '@angular/common';
+import { Component, HostListener, OnInit } from '@angular/core';
+import { GridJsSpreadsheetComponent } from 'gridjs-spreadsheet/angular';
+import { DEMO_PERMANENT, DEMO_HIGHLIGHT, DemoType, WorkbookRef, makeUid, readRoute, pushWorkbookRoute } from './routing';
+import { fetchJson } from './api';
+
+// Root demo component.
+// Renders either:
+//  - the start page (demo picker + sample file list + upload box), or
+//  - the full-page spreadsheet editor once a workbook has been selected.
+// Which one is shown is driven entirely by the URL (see ./routing.ts).
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [CommonModule, GridJsSpreadsheetComponent],
+  templateUrl: './app.component.html',
+})
+export class AppComponent implements OnInit {
+  readonly DEMO_PERMANENT = DEMO_PERMANENT;
+  readonly DEMO_HIGHLIGHT = DEMO_HIGHLIGHT;
+
+  // Sample workbooks listed on the start page.
+  files: string[] = [];
+  directory = '';
+  // The workbook selected via the URL; null means "show the start page".
+  current: WorkbookRef | null = readRoute();
+  // Which demo mode is active (only relevant while on the start page).
+  demoType: DemoType = this.current?.demo || DEMO_PERMANENT;
+  workbookData: any = null;
+  status = 'Loading workbook list...';
+  adapter: any = null;
+
+  async ngOnInit(): Promise<void> {
+    await this.loadFiles();
+    if (this.current) await this.loadWorkbook();
+  }
+
+  // Keeps state in sync when the user navigates with the browser's back/forward buttons.
+  @HostListener('window:popstate')
+  onPopState(): void {
+    this.current = readRoute();
+    if (this.current?.demo) {
+      this.demoType = this.current.demo;
+    }
+    void this.loadWorkbook();
+  }
+
+  logEvent(message: string): void {
+    console.log('[GridJS Event]', message);
+  }
+
+  // Loads the list of sample workbooks available on the server.
+  async loadFiles(): Promise<void> {
+    try {
+      const result = await fetchJson<{ directory: string; files: string[] }>('/gridjsdemo/api/files');
+      this.files = result.files || [];
+      this.directory = result.directory || '';
+      this.status = 'Ready';
+    } catch (error: any) {
+      this.status = 'Failed to load files: ' + error.message;
+    }
+  }
+
+  // Navigates to a workbook: updates the URL and local state together.
+  openWorkbook(workbook: WorkbookRef): void {
+    const normalized = { ...workbook, demo: workbook.demo || this.demoType };
+    pushWorkbookRoute(normalized);
+    this.current = normalized;
+    this.demoType = normalized.demo;
+    void this.loadWorkbook();
+  }
+
+  openFile(file: string): void {
+    this.openWorkbook({ file, storedFile: file, demo: this.demoType, uid: makeUid(file), fromUpload: '' });
+  }
+
+  // Fetches workbook data for the GridJsSpreadsheet component. Which endpoint
+  // is used depends on the demo mode:
+  //  - permanent: uid-based endpoint, backend caches parsed data per uid.
+  //  - highlight: plain endpoint, re-parses the file on every load.
+  async loadWorkbook(): Promise<void> {
+    if (!this.current?.file) {
+      this.workbookData = null;
+      return;
+    }
+    this.workbookData = null;
+    this.adapter = null;
+    this.status = 'Loading ' + this.current.file + '...';
+    try {
+      const demo = this.current.demo || DEMO_PERMANENT;
+      const params = new URLSearchParams({
+        filename: this.current.storedFile || this.current.file,
+        fromUpload: this.current.fromUpload || '',
+      });
+      let endpoint = '/GridJs2/DetailStreamJson';
+      if (this.current.fromUpload) {
+        params.set('uid', this.current.uid || makeUid(this.current.file));
+        endpoint = '/GridJs2/DetailStreamJsonWithUidFromUpload';
+      } else if (demo === DEMO_PERMANENT) {
+        params.set('uid', this.current.uid || makeUid(this.current.file));
+        endpoint = '/GridJs2/DetailStreamJsonWithUid';
+      }
+      const payload = await fetchJson<any>(endpoint + '?' + params);
+      this.workbookData = { ...payload, filename: this.current.file };
+      this.status = 'Loaded ' + this.current.file;
+    } catch (error: any) {
+      this.status = 'Workbook load failed: ' + error.message;
+    }
+  }
+
+  async upload(event: Event): Promise<void> {
+    const input = event.target as HTMLInputElement;
+    const file = input.files?.[0];
+    if (!file) return;
+    const form = new FormData();
+    form.append('file', file);
+    form.append('client', 'angular');
+    this.status = 'Uploading ' + file.name + '...';
+    try {
+      const result = await fetchJson<{ file: string; displayName: string; uid: string; fromUpload: string }>('/gridjsdemo/api/upload', { method: 'POST', body: form });
+      this.logEvent('uploaded ' + result.file);
+      // Newly uploaded files live under the server's uploads dir, flagged with fromUpload=1.
+      this.openWorkbook({
+        file: result.displayName || file.name,
+        storedFile: result.file,
+        demo: this.demoType,
+        uid: result.uid || makeUid(result.file),
+        fromUpload: '1',
+      });
+    } catch (error: any) {
+      this.status = 'Upload failed: ' + error.message;
+    } finally {
+      input.value = '';
+    }
+  }
+
+  // Restores the previously active sheet/cell (from the workbook data) once
+  // the grid has mounted, and points the "open file" link back at the start page.
+  onReady(event: { instance: any; adapter: any }): void {
+    this.adapter = event.adapter;
+    const sheetName = event.adapter.payload?.actname;
+    const row = event.adapter.payload?.actrow;
+    const col = event.adapter.payload?.actcol;
+    event.instance?.setActiveSheetByName?.(sheetName)?.setActiveCell?.(row, col);
+    event.instance?.setOpenFileUrl?.('/');
+    this.logEvent('ready ' + (event.adapter.payload?.filename || this.current?.file));
+  }
+
+  onError(payload: any): void {
+    console.error(payload);
+    this.logEvent('error ' + (payload?.message || payload?.type || 'unknown'));
+  }
+}