@forgeroute/ui 0.3.11 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeroute/ui",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "peerDependencies": {
     "@angular/common": ">=22.0.0",
     "@angular/core": ">=22.0.0",

package/types/forgeroute-ui-pdf.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from "@angular/core";
-import { InjectionToken } from "@angular/core";
+import { EnvironmentProviders, InjectionToken } from "@angular/core";
 import { PDFDocumentProxy } from "pdfjs-dist";
 /** Where pdf.js finds its worker script. Provide it once in the app (`{ provide: PDF_VIEWER_WORKER_SRC, useValue: '/assets/pdf.worker.min.mjs' }`). */
 export declare const PDF_VIEWER_WORKER_SRC: InjectionToken<string>;
@@ -37,7 +37,7 @@ export interface PdfViewerRenderedEvent {
   pageWidths: number[];
 }
 type PdfJsModule = typeof import('pdfjs-dist');
-type Status = 'idle' | 'loading' | 'ready' | 'error';
+type Status = 'idle' | 'loading' | 'ready' | 'error' | 'unsupported';
 interface PageView {
   number: number;
   cssWidth: number;
@@ -57,6 +57,33 @@ interface FieldView {
   height: number;
   fontPx: number;
 }
+/**
+ * Language features the pdf.js modern build calls WITHOUT a polyfill or guard on the path every document takes, found by reading
+ * `pdfjs-dist/build/pdf.mjs` + `pdf.worker.mjs` of 5.7.284 (this library's dev copy) and 6.2.108 (the apps' copy). The `legacy/` build
+ * polyfills them; this component imports the modern one. Details and the evidence per feature: docs/pdf-viewer.md.
+ *
+ * - `Promise.withResolvers`, `Promise.try`: the main-thread API and the worker message handler (every message).
+ * - `Map.prototype.getOrInsertComputed`: per-page intent state and the object store on every render (6.x also in the message handler).
+ * - `Math.sumPrecise`: the worker, when it builds a font's name / glyf tables (every document with text).
+ * - `Iterator`: pdf.js 6.x touches `Iterator.prototype` while the module loads, so a browser without the global cannot even import it.
+ * - `URL.parse`: opening a document by URL (the stream choice and the worker origin check).
+ *
+ * Left out on purpose: `Worker` and `structuredClone` (pdf.js falls back to a main-thread worker that only needs one of them),
+ * `OffscreenCanvas` / `Float16Array` (feature-tested by pdf.js), `Uint8Array.fromBase64` / `toBase64` and `Iterator` helpers (XFA / editor / text-layer paths only).
+ */
+export declare const PDF_VIEWER_REQUIRED_FEATURES: readonly ["Promise.withResolvers", "Promise.try", "Map.prototype.getOrInsertComputed", "Math.sumPrecise", "Iterator", "URL.parse"];
+export type PdfViewerRequiredFeature = typeof PDF_VIEWER_REQUIRED_FEATURES[number];
+/**
+ * Names of the required features `scope` (default: the global object) lacks; [] = pdf.js can run. Synchronous and
+ * side-effect free. `URL.parse` is only needed to open a URL, so it is skipped when `needsUrl` is false (bytes are given).
+ */
+export declare function findMissingPdfFeatures(scope?: object, needsUrl?: boolean): PdfViewerRequiredFeature[];
+/** Emitted by `loadFailed` when the browser lacks a feature pdf.js needs (nothing was loaded). */
+export declare class PdfViewerUnsupportedError extends Error {
+  readonly missing: readonly PdfViewerRequiredFeature[];
+  readonly reason: "unsupported-browser";
+  constructor(missing: readonly PdfViewerRequiredFeature[]);
+}
 /**
  * Renders every page of a PDF into a canvas (crisp on high-density screens), with optional labelled boxes overlaid in PDF coordinates.
  * Needs `pdfjs-dist` (loaded on first use, so it stays out of bundles that never show a PDF).
@@ -77,7 +104,11 @@ interface FieldView {
  * - `httpHeaders` and `withCredentials` apply to `src` only; they are not used when `data` is given.
  * - `fields[].id` is only a display / test hook; duplicates are tolerated. `httpHeaders` is compared by content, but a stable reference is still preferred.
  * - The worker-missing message is fixed text and ignores `errorText`, because it is a setup problem for the developer.
- * - Needs pdf.js 5 (`pdfjs-dist` >= 5), which needs Safari 17.4+; the legacy pdf.js build is not supported by this component.
+ * - Needs pdf.js 5 (`pdfjs-dist` >= 5); the legacy pdf.js build is not supported by this component.
+ * - Browser check: before pdf.js is imported, the viewer checks (once per load, synchronously) that the browser has the features
+ *   `PDF_VIEWER_REQUIRED_FEATURES` lists. Without them it shows `unsupportedText` (role="status") and, when `src` is a URL, an
+ *   "Open the document" link (new tab); `loadFailed` emits a `PdfViewerUnsupportedError` (`reason: 'unsupported-browser'`, `missing`).
+ *   `[checkBrowserSupport]="false"` skips the check. See docs/pdf-viewer.md.
  * - The public typings reference `pdfjs-dist` types: apps that type-check the library without `pdfjs-dist` installed need `skipLibCheck` or the
  *   package (the same trade-off as `@forgeroute/ui/charts` and chart.js).
  */
@@ -100,6 +131,12 @@ export declare class PdfViewerComponent {
   readonly ariaLabel: import("@angular/core").InputSignal<string>;
   readonly loadingText: import("@angular/core").InputSignal<string>;
   readonly errorText: import("@angular/core").InputSignal<string>;
+  /** Shown when the browser cannot run pdf.js (see `checkBrowserSupport`). */
+  readonly unsupportedText: import("@angular/core").InputSignal<string>;
+  /** Text of the link that opens `src` in a new tab on such a browser. */
+  readonly openText: import("@angular/core").InputSignal<string>;
+  /** Check for the browser features pdf.js needs before loading it; false = always try to load. */
+  readonly checkBrowserSupport: import("@angular/core").InputSignal<boolean>;
   readonly loaded: import("@angular/core").OutputEmitterRef<PdfViewerLoadedEvent>;
   readonly loadFailed: import("@angular/core").OutputEmitterRef<unknown>;
   readonly pagesRendered: import("@angular/core").OutputEmitterRef<PdfViewerRenderedEvent>;
@@ -107,7 +144,11 @@ export declare class PdfViewerComponent {
   private readonly pageSizes;
   private readonly containerWidth;
   private readonly customError;
+  /** The URL the "Open the document" link points at: `src` when no bytes are given. */
+  protected readonly openUrl: import("@angular/core").Signal<string>;
   protected readonly errorMessage: import("@angular/core").Signal<string>;
+  /** What the always-present live region announces: loading progress, or why no preview is shown (a live region that already exists is announced reliably; one inserted with its text is not). */
+  protected readonly liveText: import("@angular/core").Signal<string>;
   /** Changes exactly when some canvas bitmap changes size (and so is cleared). */
   private readonly drawKey;
   private readonly effectiveWidth;
@@ -131,6 +172,8 @@ export declare class PdfViewerComponent {
   constructor();
   /** Test seam: loads pdf.js on first use so apps that never show a PDF do not bundle or fetch it. */
   protected loadPdfJs(): Promise<PdfJsModule>;
+  /** Test seam: the required features this browser lacks. */
+  protected missingFeatures(needsUrl: boolean): readonly PdfViewerRequiredFeature[];
   private resolvedRatio;
   private widthFor;
   private startLoad;
@@ -198,9 +241,37 @@ export declare class PdfViewerComponent {
       "required": false;
       "isSignal": true;
     };
+    "unsupportedText": {
+      "alias": "unsupportedText";
+      "required": false;
+      "isSignal": true;
+    };
+    "openText": {
+      "alias": "openText";
+      "required": false;
+      "isSignal": true;
+    };
+    "checkBrowserSupport": {
+      "alias": "checkBrowserSupport";
+      "required": false;
+      "isSignal": true;
+    };
   }, {
     "loaded": "loaded";
     "loadFailed": "loadFailed";
     "pagesRendered": "pagesRendered";
   }, never, never, true, never>;
-}
+}
+export interface ForgeroutePdfOptions {
+  /** URL of the pdf.js worker script every `ui-pdf-viewer` in the app uses, e.g. `'/pdf.worker.min.mjs'`. Must not be blank. */
+  workerSrc: string;
+}
+/**
+ * Sets the pdf.js worker location once for the whole app (provides `PDF_VIEWER_WORKER_SRC`):
+ *
+ *   providers: [provideForgeroutePdf({ workerSrc: '/pdf.worker.min.mjs' })]
+ *
+ * A `workerSrc` input on a viewer still wins over this value. Throws at provide time when `workerSrc` is blank, because a viewer
+ * without a worker can only show "PDF worker is not configured.".
+ */
+export declare function provideForgeroutePdf(options: ForgeroutePdfOptions): EnvironmentProviders;