@panelwave/player 1.1.0 → 1.3.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)** ·
@@ -53,7 +53,7 @@ it into a complete reading experience:
 
 Stories are authored in the PanelWave CMS or written by hand against the
 [open JSON Schema](https://github.com/panelwave/schema). The player supports
-manifests up to format 1.6 (video panels, edge-transition inheritance,
+manifests up to format 1.7 (video panels, edge-transition inheritance,
 typography style presets, the infinite canvas, paywall rules unlocked by any
 of several products, each Buy option named and priced from `paywall.products`; 1.5's asset folders and localization blocks are
 authoring metadata the player doesn't need).
@@ -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 |
@@ -205,7 +225,9 @@ navigation stops at the gate. Works without paywall rules aren't affected.
   `extras` rules lock an extras block, never panels.
 - **Age:** `ageGate` / `minimumAge` is checked on top of the rule's
   entitlement. The reader answers the age gate first, then gets the paywall
-  if the purchase or subscription is still missing.
+  if the purchase or subscription is still missing. Age requirements combine
+  across every rule that applies to a panel, so a chapter preview or a free
+  panel rule never skips a work-wide age gate.
 - **Buy / Subscribe:** the overlay offers a Buy option per product of a
   purchase rule and a Subscribe option per tier of a subscription rule (name,
   description and price from the rule), next to Sign in and Maybe later.
@@ -215,6 +237,10 @@ navigation stops at the gate. Works without paywall rules aren't affected.
   pass a new `entitlementSnapshot`; the overlay closes once the reader is
   through. Story keys and swipes do nothing while the paywall or the age
   gate is open.
+- **Custom `entitlementAdapter`:** it decides navigation, not rendering. A
+  panel the adapter refuses still renders (on the initial load the paywall
+  opens over it), so don't rely on an adapter to hide content: strip it on
+  the server (`"x-locked": true`) or pass an `entitlementSnapshot`.
 
 ### Going further