HF-238 - Review "Integration with Angular" guide and demo (#1691)

KrzysztofZie · sequba · GreenFlux · web-flow · commit d4195b56f28b · 2026-06-09T16:30:30.000+02:00
### Context - Added a modern Angular (v20+) section — an example in the same style as the demo: a service exposing a signal, a component using inject() + OnPush, a template with @if/@for, and bootstrap with provideZonelessChangeDetection. - Marked the old example as the older-versions variant (BehaviorSubject + async pipe), while fixing its compatibility: the component is now standalone with imports: [CommonModule], so it works without an NgModule. - Added a path for very old Angular (≤13) — an NgModule-based apps subsection at the end of the "older" section, completing the three tiers: modern → older/standalone → NgModule. - Moved the Demo section right under the modern Angular code (StackBlitz link, without describing the demo's internal standards). - Clarified the "Provider scope" and "Cleanup" notes to state they apply to both variants (they depend on DI scope, not on signals/RxJS). In short: the guide was rewritten to show the modern pattern (matching the demo) while preserving backward compatibility, with a clear split by Angular version. ### How did you test your changes?  ### Types of changes  - [ ] Breaking change (a fix or a feature because of which an existing functionality doesn't work as expected anymore) - [ ] New feature or improvement (a non-breaking change that adds functionality) - [ ] Bug fix (a non-breaking change that fixes an issue) - [ ] Additional language file, or a change to an existing language file (translations) - [x] Change to the documentation ### Related issues: 1. Fixes #... 2. 3. ### Checklist:   - [ ] I have reviewed the guidelines about [Contributing to HyperFormula](https://hyperformula.handsontable.com/guide/contributing.html) and I confirm that my code follows the code style of this project. - [ ] I have signed the [Contributor License Agreement](https://goo.gl/forms/yuutGuN0RjsikVpM2). - [ ] My change is compliant with the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html) standard. - [ ] My change is compatible with Microsoft Excel. - [ ] My change is compatible with Google Sheets. - [ ] I described my changes in the [CHANGELOG.md](https://github.com/handsontable/hyperformula/blob/master/CHANGELOG.md) file. - [ ] My changes require a documentation update. - [ ] My changes require a migration guide.  --- > [!NOTE] > **Low Risk** > Documentation-only changes to the Angular integration guide; no runtime or library code affected. > > **Overview** > Rewrites the **Integration with Angular** guide into a **version-tiered** layout: a new **modern Angular (v20+)** path (signals, `inject()`, OnPush, `@if`/`@for`, `provideZonelessChangeDetection`) and a preserved **older** path (`BehaviorSubject` + `async` pipe). > > The legacy example is updated for **standalone** components (`standalone: true`, `imports: [CommonModule]`) and adds an **`NgModule`-based** subsection for Angular 13 and below. Sample sheet data in snippets changes from `[1, 2, '=A1+B1']` to `[1, 4, '=A1+B1']`. **Provider scope** and **Cleanup** notes now state they apply to both signal and RxJS variants. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 210c1ac. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: Kuba Sekowski <jakub.sekowski@handsontable.com> Co-authored-by: GreenFlux <support@greenflux.us> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Kuba Sekowski <kuba.sekowski.dev@gmail.com> Co-authored-by: krzysztof.zielinski <kzielinski@speednet.pl>
diff --git a/docs/guide/integration-with-angular.md b/docs/guide/integration-with-angular.md
@@ -4,9 +4,111 @@ The HyperFormula API is identical in an Angular app and in plain JavaScript. Thi
 
 Install with `npm install hyperformula`. For other options, see the [client-side installation](client-side-installation.md) section.
 
-## Basic usage
+## Basic usage (modern Angular)
 
-Wrap the engine in an `@Injectable` service backed by a `BehaviorSubject`. Components subscribe to the observable with the `async` pipe, which handles subscription cleanup automatically.
+For modern Angular (v20+) we recommend a service that exposes a **signal**, **standalone** components, the new control flow (`@if` / `@for`) and **zoneless** change detection. Wrap the engine in an `@Injectable` service and expose its values as a read-only signal; the template reads the signal directly and Angular refreshes the view whenever it changes.
+
+```typescript
+// spreadsheet.service.ts
+import { Injectable, signal } from '@angular/core';
+import { HyperFormula, type CellValue } from 'hyperformula';
+
+@Injectable({ providedIn: 'root' })
+export class SpreadsheetService {
+  private readonly hf: HyperFormula;
+
+  private readonly _values = signal<CellValue[][]>([]);
+  readonly values = this._values.asReadonly();
+
+  constructor() {
+    this.hf = HyperFormula.buildFromArray(
+      [
+        [1, 4, '=A1+B1'],
+        // your data rows go here
+      ],
+      {
+        licenseKey: 'gpl-v3',
+        // more configuration options go here
+      }
+    );
+    this._values.set(this.hf.getSheetValues(0));
+  }
+
+  calculate() {
+    this._values.set(this.hf.getSheetValues(0));
+  }
+
+  reset() {
+    this._values.set([]);
+  }
+}
+```
+
+Inject the service with `inject()`, expose its signal, and use `OnPush` change detection:
+
+```typescript
+// spreadsheet.component.ts
+import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
+import { SpreadsheetService } from './spreadsheet.service';
+
+@Component({
+  selector: 'app-spreadsheet',
+  templateUrl: './spreadsheet.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SpreadsheetComponent {
+  private readonly spreadsheetService = inject(SpreadsheetService);
+
+  readonly values = this.spreadsheetService.values;
+
+  runCalculations() {
+    this.spreadsheetService.calculate();
+  }
+
+  reset() {
+    this.spreadsheetService.reset();
+  }
+}
+```
+
+Read the signal in the template with the new control flow:
+
+```html
+<!-- spreadsheet.component.html -->
+<button (click)="runCalculations()">Run calculations</button>
+<button (click)="reset()">Reset</button>
+@if (values().length) {
+  <table>
+    @for (row of values(); track $index) {
+      <tr>
+        @for (cell of row; track $index) {
+          <td>{{ cell }}</td>
+        }
+      </tr>
+    }
+  </table>
+}
+```
+
+Bootstrap the app with zoneless change detection:
+
+```typescript
+// main.ts
+import { provideZonelessChangeDetection } from '@angular/core';
+import { bootstrapApplication } from '@angular/platform-browser';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideZonelessChangeDetection()],
+}).catch((err) => console.error(err));
+```
+
+> Signals require Angular 16+, the new control flow Angular 17+, and `provideZonelessChangeDetection` Angular 20+. For earlier versions, use the `BehaviorSubject` approach below.
+
+
+## Basic usage (older Angular versions)
+
+For broader compatibility — including Angular versions without signals or zoneless change detection — wrap the engine in an `@Injectable` service backed by a `BehaviorSubject`. Components subscribe to the observable with the `async` pipe, which handles subscription cleanup automatically.
 
 ```typescript
 // spreadsheet.service.ts
@@ -24,7 +126,7 @@ export class SpreadsheetService {
   constructor() {
     this.hf = HyperFormula.buildFromArray(
       [
-        [1, 2, '=A1+B1'],
+        [1, 4, '=A1+B1'],
         // your data rows go here
       ],
       {
@@ -45,17 +147,20 @@ export class SpreadsheetService {
 }
 ```
 
-Consume the service from a component and bind `values$ | async` in the template. Declare the component in your `AppModule` alongside `CommonModule`:
+Consume the service from a component and bind `values$ | async` in the template. The component below is **standalone** (the default since Angular 17) and imports `CommonModule` directly, so it works without an `NgModule`. The structural directives `*ngIf` / `*ngFor` and the `async` pipe all come from `CommonModule`:
 
 ```typescript
 // spreadsheet.component.ts
 import { Component } from '@angular/core';
+import { CommonModule } from '@angular/common';
 import { Observable } from 'rxjs';
 import { SpreadsheetService } from './spreadsheet.service';
 import { type CellValue } from 'hyperformula';
 
 @Component({
   selector: 'app-spreadsheet',
+  standalone: true,
+  imports: [CommonModule],
   templateUrl: './spreadsheet.component.html',
 })
 export class SpreadsheetComponent {
@@ -88,10 +193,27 @@ export class SpreadsheetComponent {
 </ng-container>
 ```
 
+### `NgModule`-based apps (Angular 13 and older)
+
+Standalone components require Angular 14 or newer. If your project still uses `NgModule`s (or targets Angular 13 or older), drop the `standalone: true` and `imports` fields from the component above, then declare it in your module and import `CommonModule` there instead:
+
+```typescript
+// app.module.ts
+@NgModule({
+  declarations: [SpreadsheetComponent],
+  imports: [BrowserModule, CommonModule],
+})
+export class AppModule {}
+```
+
+The service and template above are unchanged — only the way the component is wired up differs.
+
 ## Notes
 
 ### Provider scope
 
+The notes below apply to both the modern and older approaches — provider scope and cleanup depend on how the service is registered, not on whether it exposes a signal or a `BehaviorSubject`.
+
 `providedIn: 'root'` makes the service an application-wide singleton — suitable when a single HyperFormula instance is shared across the app. For per-feature or per-component instances (for example, several independent reports on one screen), provide the service at the component level via `providers: [SpreadsheetService]`; the service is then created and destroyed alongside the component.
 
 ### Cleanup
