@panelwave/player 1.1.0 → 1.2.0

package/README.md

@@ -7,7 +7,7 @@ story variables, multilingual text and paywalls, all in one component.
 
 [![npm](https://img.shields.io/npm/v/@panelwave/player.svg)](https://www.npmjs.com/package/@panelwave/player)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/panelwave/player/blob/master/LICENSE)
-[![Angular](https://img.shields.io/badge/Angular-20-red)](https://angular.dev)
+[![Angular](https://img.shields.io/badge/Angular-20%20%7C%2021%20%7C%2022-red)](https://angular.dev)
 
 **[Live demo](https://panelwave.github.io/player/)** ·
 **[Documentation](https://docs.panelwave.org/player/overview)** ·
@@ -64,8 +64,16 @@ authoring metadata the player doesn't need).
 npm install @panelwave/player @ngx-translate/core
 ```
 
-Peer dependencies: `@angular/core` and `@angular/common` **^20**,
-`@ngx-translate/core` **^17**, `rxjs` **^7.8**.
+Peer dependencies: `@angular/core` and `@angular/common` **^20, ^21 or ^22**,
+`@ngx-translate/core` **^17 or ^18**, `rxjs` **^7.8**.
+
+**Angular compatibility.** The package is compiled with Angular 20 in partial
+(linker) mode, so newer Angular versions link it at build time. Every CI run
+installs the packed library into a fresh `ng new` app on Angular 20, 21 and
+22 with ngx-translate 18, and on Angular 20 and 22 with ngx-translate 17
+(strict peer resolution, production build, headless render of a sample
+manifest); the player works with zone.js and zoneless change detection (the
+default for new Angular 21+ apps).
 
 ## Setup
 
@@ -74,13 +82,13 @@ for its UI strings:
 
 ```typescript
 // app.config.ts
-import { ApplicationConfig, importProvidersFrom } from '@angular/core';
+import { ApplicationConfig, inject } from '@angular/core';
 import { HttpClient, provideHttpClient } from '@angular/common/http';
-import { TranslateLoader, TranslateModule, TranslationObject } from '@ngx-translate/core';
+import { TranslateLoader, TranslationObject, provideTranslateService } from '@ngx-translate/core';
 import { Observable } from 'rxjs';
 
 class PlayerTranslateLoader implements TranslateLoader {
-  constructor(private http: HttpClient) {}
+  private readonly http = inject(HttpClient);
   getTranslation(lang: string): Observable<TranslationObject> {
     return this.http.get<TranslationObject>(`./assets/i18n/${lang}.json`);
   }
@@ -89,15 +97,21 @@ class PlayerTranslateLoader implements TranslateLoader {
 export const appConfig: ApplicationConfig = {
   providers: [
     provideHttpClient(),
-    importProvidersFrom(
-      TranslateModule.forRoot({
-        loader: { provide: TranslateLoader, useClass: PlayerTranslateLoader, deps: [HttpClient] },
-      }),
-    ),
+    provideTranslateService({
+      loader: { provide: TranslateLoader, useClass: PlayerTranslateLoader },
+    }),
   ],
 };
 ```
 
+This works with ngx-translate 17 and 18. (`TranslateModule.forRoot()` still
+works on 17 but no longer exists in 18.) Pass the loader as an explicit
+provider as shown: on 18, `provideTranslateLoader(PlayerTranslateLoader)`
+fails in production builds for a plain (non-`@Injectable`) class, because
+18 tells classes from factory functions by their source text, and the
+minified class no longer looks like one ("Class constructor … cannot be
+invoked without 'new'").
+
 **2. Assets and fonts.** Copy the player's UI translations into your app,
 and include the balloon lettering fonts:
 
@@ -117,11 +131,15 @@ Caveat, Anton and 10 more). The commercial Blambot font **Ames Pro** is not
 included. If your works use it, license it from [blambot.com](https://blambot.com)
 and add your own `@font-face`. Otherwise balloons fall back to Comic Neue.
 
+The player depends on `json-logic-js`, a CommonJS module. To silence the
+build warning about it, add `"allowedCommonJsDependencies": ["json-logic-js"]`
+to the same build options.
+
 ## Usage
 
 ```typescript
 import { Component } from '@angular/core';
-import { PlayerShellComponent } from '@panelwave/player';
+import { PlayerShellComponent, type PlayerPanelChangeEvent } from '@panelwave/player';
 
 @Component({
   selector: 'app-reader',
@@ -131,13 +149,15 @@ import { PlayerShellComponent } from '@panelwave/player';
       manifestUrl="/stories/my-story/panelwave.json"
       locale="en-US"
       [showToolbar]="true"
-      (panelChange)="onPanel($event.panel.id)"
+      (panelChange)="onPanel($event)"
       (error)="onError($event)" />
   `,
   styles: `:host { display: block; height: 100dvh; }`,
 })
 export class ReaderComponent {
-  onPanel(id: string) { console.log('now showing', id); }
+  onPanel(e: PlayerPanelChangeEvent) {
+    console.log(`panel ${e.panelId} in chapter ${e.chapter.id} (came from ${e.previousPanelId ?? 'start'})`);
+  }
   onError(err: Error) { console.error(err); }
 }
 ```
@@ -173,7 +193,7 @@ a new `entitlementSnapshot` re-evaluates the gates, and `locale`,
 | Output | Payload | Fires when |
 |---|---|---|
 | `ready` | `void` | The manifest is loaded and the player is ready |
-| `panelChange` | `{ panel, chapter }` | The reader moves to a new panel |
+| `panelChange` | `PlayerPanelChangeEvent`: `{ panel, chapter, panelId, previousPanelId? }` | The reader moves to a new panel. `panelId` is the panel's key in `chapter.panels` (read the id from here: `panel.id` is optional in the format and usually absent); `previousPanelId` is the panel before it, unset for the first panel after a (re)load |
 | `chapterChange` | `Chapter` | A chapter boundary is crossed |
 | `variableChange` | `{ key, value }` | A story variable changes |
 | `localeChange` | `LocaleCode` | The language is switched |