angular-wrapper-dev

name: angular-wrapper-dev path: wrappers/angular-wrapper/** description: Use when developing or modifying the @handsontable/angular-wrapper package - Angular components with decorators, NgZone performance optimization, and ng-packagr build system

Angular Wrapper Development

Package location

wrappers/angular-wrapper/

Library source lives under projects/hot-table/src/lib/.

Component architecture

The main HotTableComponent uses Angular @Component with individual @Input() decorators for each Handsontable option. This gives consumers standard Angular template binding for every grid setting.

Lifecycle

• AfterViewInit - creates the Handsontable instance on the DOM element obtained via @ViewChild('container').
• OnChanges - detects input property changes and calls updateSettings() with the new values.
• OnDestroy - calls hot.destroy() and cleans up references.

Performance

NgZone.runOutsideAngular() wraps the Handsontable constructor and most grid operations. This prevents Angular change detection from running on every internal grid event (scroll, render, mouse move), which is critical for performance with large datasets.

Services

• HotSettingsResolver - resolves and merges settings from component inputs, handling priority between individual inputs and the aggregate settings object.
• HotGlobalConfig - provides global default settings that apply to all HotTable instances in the application.

Module system

HotTableModule is the Angular module that declares and exports the component. Consumers add it to their imports array in standalone components.

Build and test

• Build system: ng-packagr 16.
• Tests: Jest with jest-preset-angular.
• Gotcha: Tests require NODE_OPTIONS=--openssl-legacy-provider (already configured in the test script).
• Run tests: npm run test --prefix wrappers/angular-wrapper
• Important: Build core first with npm run build --prefix handsontable. Wrappers consume handsontable/tmp/, not dist/.

Key files

Modern Angular patterns (required for all new and updated examples)

Standalone components

All Angular example components must use standalone: true with HotTableModule in the imports array. Do not use standalone: false or NgModule-based declarations.

import { Component } from '@angular/core';
import { HotTableModule } from '@handsontable/angular-wrapper';

@Component({
  selector: 'app-example1',
  standalone: true,
  imports: [HotTableModule],
  template: `<hot-table [settings]="hotSettings"></hot-table>`,
})
export class AppComponent { ... }

app.config.ts instead of app.module.ts

Replace AppModule (@NgModule) with an ApplicationConfig in app.config.ts. Register Handsontable modules and provide the global license key here:

/* file: app.config.ts */
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { registerAllModules } from 'handsontable/registry';
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';

registerAllModules();

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    {
      provide: HOT_GLOBAL_CONFIG,
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
    },
  ],
};

• provideZoneChangeDetection({ eventCoalescing: true }) is required in every app.config.ts.
• The global HOT_GLOBAL_CONFIG license replaces per-table licenseKey on every <hot-table>. Do not add licenseKey to individual component settings.
• CommonModule and BrowserModule are no longer needed in standalone components.

Template control flow

Use Angular 17+ built-in control flow syntax instead of structural directives:

Example:

@if (isOpen) {
  <ul role="listbox">
    @for (opt of options; track opt.value) {
      <li (click)="select(opt.value)">{{ opt.label }}</li>
    }
  </ul>
}

Type safety

• Use RowObject from handsontable instead of any[] for row data arrays.
• Use typed querySelector: document.querySelector<HTMLInputElement>('#my-input').
• Use non-null assertion on hotInstance where the instance is guaranteed to exist: this.hotTable.hotInstance!.updateSettings(...).
• Use hotInstance!.updateSettings() to change settings at runtime -- never destroy and recreate the Handsontable instance.

import { RowObject } from 'handsontable';

export class AppComponent {
  hotData: RowObject[] = [];
}

Component naming

Name all example components AppComponent, not ExampleNComponent or feature-specific names.

Rules

• No business logic in wrappers. All data transformation and validation belongs in handsontable/src/.
• Cross-platform npm scripts: use Node.js .mjs helpers instead of bash-only constructs. Never use bash-specific syntax (if [ ], mv, && with ||) directly in package.json script entries.
• Never add licenseKey to individual <hot-table> settings in examples -- set it globally via HOT_GLOBAL_CONFIG in app.config.ts.
• Never use standalone: false in new or updated example components.
• Never use *ngIf or *ngFor in new or updated templates -- use @if / @for control flow.