gridjs-spreadsheet 26.6.2 → 26.7.0

package/angular.d.ts

@@ -0,0 +1,67 @@
+import type {
+  AfterViewInit,
+  ElementRef,
+  EventEmitter,
+  NgZone,
+  OnChanges,
+  OnDestroy,
+  SimpleChanges,
+} from '@angular/core';
+import type * as i0 from '@angular/core';
+import type Spreadsheet from 'gridjs-spreadsheet';
+import type { GridJsAdapter } from './shared';
+
+export declare class GridJsSpreadsheetComponent implements AfterViewInit, OnChanges, OnDestroy {
+  apiBase: string;
+  data: Record<string, any> | null;
+  loader: (() => Promise<Record<string, any>> | Record<string, any>) | null;
+  mode: 'edit' | 'read';
+  locale: string;
+  token: string;
+  height: string;
+  showToolbar: boolean;
+  showContextmenu: boolean;
+  ready: EventEmitter<{ instance: Spreadsheet; adapter: GridJsAdapter }>;
+  change: EventEmitter<any[]>;
+  error: EventEmitter<any>;
+  cellSelected: EventEmitter<any[]>;
+  cellEdited: EventEmitter<any[]>;
+  sheetSelected: EventEmitter<any[]>;
+  sheetLoaded: EventEmitter<any[]>;
+  constructor(zone: NgZone, platformId: object, elementRef: ElementRef<HTMLElement>);
+  ngAfterViewInit(): void;
+  ngOnChanges(changes: SimpleChanges): void;
+  ngOnDestroy(): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<GridJsSpreadsheetComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<
+    GridJsSpreadsheetComponent,
+    'gridjs-spreadsheet',
+    never,
+    {
+      apiBase: { alias: 'apiBase'; required: false };
+      data: { alias: 'data'; required: false };
+      loader: { alias: 'loader'; required: false };
+      mode: { alias: 'mode'; required: false };
+      locale: { alias: 'locale'; required: false };
+      token: { alias: 'token'; required: false };
+      height: { alias: 'height'; required: false };
+      showToolbar: { alias: 'showToolbar'; required: false };
+      showContextmenu: { alias: 'showContextmenu'; required: false };
+    },
+    {
+      ready: 'ready';
+      change: 'change';
+      error: 'error';
+      cellSelected: 'cellSelected';
+      cellEdited: 'cellEdited';
+      sheetSelected: 'sheetSelected';
+      sheetLoaded: 'sheetLoaded';
+    },
+    never,
+    never,
+    true,
+    never
+  >;
+}
+
+export default GridJsSpreadsheetComponent;

package/angular.js

@@ -0,0 +1,174 @@
+import { isPlatformBrowser } from '@angular/common';
+import {
+  ElementRef,
+  EventEmitter,
+  NgZone,
+  PLATFORM_ID,
+} from '@angular/core';
+import * as i0 from '@angular/core';
+import { createGridJsAdapter } from './shared.js';
+
+function clonePlain(value) {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+function importGridJs() {
+  return import('gridjs-spreadsheet');
+}
+
+export class GridJsSpreadsheetComponent {
+  apiBase = '';
+  data = null;
+  loader = null;
+  mode = 'edit';
+  locale = 'en';
+  token = '';
+  height = 'calc(100vh - 96px)';
+  showToolbar = true;
+  showContextmenu = true;
+
+  ready = new EventEmitter();
+  change = new EventEmitter();
+  error = new EventEmitter();
+  cellSelected = new EventEmitter();
+  cellEdited = new EventEmitter();
+  sheetSelected = new EventEmitter();
+  sheetLoaded = new EventEmitter();
+
+  adapter = null;
+  viewReady = false;
+  lastMountKey = '';
+
+  constructor(zone, platformId, elementRef) {
+    this.zone = zone;
+    this.isBrowser = isPlatformBrowser(platformId);
+    this.hostElement = elementRef.nativeElement;
+  }
+
+  ngAfterViewInit() {
+    this.viewReady = true;
+    void this.mountIfNeeded();
+  }
+
+  ngOnChanges(changes) {
+    if (changes.token && !changes.token.firstChange && this.adapter && this.token) {
+      this.adapter.refreshToken(this.token);
+    }
+    if (this.viewReady) {
+      void this.mountIfNeeded();
+    }
+  }
+
+  ngOnDestroy() {
+    this.adapter?.destroy();
+    this.adapter = null;
+    if (this.hostElement) {
+      this.hostElement.innerHTML = '';
+    }
+  }
+
+  async mountIfNeeded() {
+    if (!this.isBrowser || !this.hostElement || (!this.data && !this.loader)) return;
+
+    const mountKey = [
+      this.data?.uniqueid || this.data?.filename || 'loader',
+      this.apiBase,
+      this.mode,
+      this.locale,
+      String(this.showToolbar),
+      String(this.showContextmenu),
+    ].join('|');
+
+    if (mountKey === this.lastMountKey && this.adapter) return;
+    this.lastMountKey = mountKey;
+
+    this.adapter?.destroy();
+    this.hostElement.innerHTML = '';
+
+    try {
+      const plainData = this.data ? clonePlain(this.data) : undefined;
+      this.adapter = await this.zone.runOutsideAngular(() => createGridJsAdapter({
+        container: this.hostElement,
+        apiBase: this.apiBase,
+        data: plainData,
+        loader: this.loader,
+        mode: this.mode,
+        locale: this.locale,
+        token: this.token,
+        showToolbar: this.showToolbar,
+        showContextmenu: this.showContextmenu,
+        callbacks: {
+          ready: (instance, activeAdapter) => this.zone.run(() => this.ready.emit({ instance, adapter: activeAdapter })),
+          change: (...args) => this.zone.run(() => this.change.emit(args)),
+          error: payload => this.zone.run(() => this.error.emit(payload)),
+          cellSelected: (...args) => this.zone.run(() => this.cellSelected.emit(args)),
+          cellEdited: (...args) => this.zone.run(() => this.cellEdited.emit(args)),
+          sheetSelected: (...args) => this.zone.run(() => this.sheetSelected.emit(args)),
+          sheetLoaded: (...args) => this.zone.run(() => this.sheetLoaded.emit(args)),
+        },
+        dependencies: {
+          importJSZip: () => import('jszip'),
+          importGridJs,
+        },
+      }));
+    } catch (error) {
+      this.error.emit({ type: 'mountError', error });
+    }
+  }
+}
+
+// Partial compilation format (ɵɵngDeclareFactory / ɵɵngDeclareComponent).
+// Angular's linker re-compiles these declarations at the consuming application's
+// build time, so they remain compatible across Angular major versions.
+// Do NOT use ɵɵdefineComponent here — that is a private, fully-linked runtime
+// format that is not guaranteed to be stable across Angular releases.
+GridJsSpreadsheetComponent.ɵfac = /* @__PURE__ */ i0.ɵɵngDeclareFactory({
+  minVersion: '12.0.0',
+  version: '16.0.0',
+  ngImport: i0,
+  type: GridJsSpreadsheetComponent,
+  deps: [
+    { token: NgZone },
+    { token: PLATFORM_ID },
+    { token: ElementRef },
+  ],
+  target: i0.ɵɵFactoryTarget.Component,
+});
+
+GridJsSpreadsheetComponent.ɵcmp = /* @__PURE__ */ i0.ɵɵngDeclareComponent({
+  minVersion: '14.0.0',
+  version: '16.0.0',
+  type: GridJsSpreadsheetComponent,
+  isStandalone: true,
+  selector: 'gridjs-spreadsheet',
+  inputs: {
+    apiBase: 'apiBase',
+    data: 'data',
+    loader: 'loader',
+    mode: 'mode',
+    locale: 'locale',
+    token: 'token',
+    height: 'height',
+    showToolbar: 'showToolbar',
+    showContextmenu: 'showContextmenu',
+  },
+  outputs: {
+    ready: 'ready',
+    change: 'change',
+    error: 'error',
+    cellSelected: 'cellSelected',
+    cellEdited: 'cellEdited',
+    sheetSelected: 'sheetSelected',
+    sheetLoaded: 'sheetLoaded',
+  },
+  usesOnChanges: true,
+  ngImport: i0,
+  template: '',
+  styles: [':host{display:block;width:100%;background:#fff;}'],
+  changeDetection: i0.ChangeDetectionStrategy.Default,
+});
+
+export default GridJsSpreadsheetComponent;

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>;
+}