@forgeroute/ui 0.3.7 → 0.3.9

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@forgeroute/ui",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "peerDependencies": {
     "@angular/common": ">=22.0.0",
     "@angular/core": ">=22.0.0",
     "@angular/forms": ">=22.0.0",
     "@angular/router": ">=22.0.0",
     "@angular/platform-browser": ">=22.0.0",
-    "chart.js": ">=4.0.0"
+    "chart.js": ">=4.0.0",
+    "pdfjs-dist": ">=5.0.0"
   },
   "peerDependenciesMeta": {
     "@angular/forms": {
@@ -15,6 +16,9 @@
     },
     "chart.js": {
       "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
     }
   },
   "publishConfig": {
@@ -40,6 +44,10 @@
     "./charts": {
       "types": "./types/forgeroute-ui-charts.d.ts",
       "default": "./fesm2022/forgeroute-ui-charts.mjs"
+    },
+    "./pdf": {
+      "types": "./types/forgeroute-ui-pdf.d.ts",
+      "default": "./fesm2022/forgeroute-ui-pdf.mjs"
     }
   },
   "sideEffects": false,

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

@@ -0,0 +1,206 @@
+import * as i0 from "@angular/core";
+import { 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>;
+/** Colour of an overlay badge. */
+export type PdfViewerTone = 'blue' | 'green' | 'amber' | 'red' | 'slate';
+/** A labelled box drawn over a page. Positions are PDF points with the origin at the page's bottom-left corner. */
+export interface PdfViewerField {
+  id: string;
+  /** 1-based page number; a field on a page that does not exist is ignored. */
+  page: number;
+  /** Bottom-left corner of the box, in PDF points. */
+  x: number;
+  y: number;
+  /** Size in PDF points. Without a width the box fits its label; the default height is 14. */
+  width?: number;
+  height?: number;
+  label: string;
+  tone?: PdfViewerTone;
+}
+export interface PdfViewerLoadedEvent {
+  pageCount: number;
+  /** Every page's size in PDF points at scale 1. */
+  pages: {
+    width: number;
+    height: number;
+  }[];
+  /** The loaded pdf.js document, so the host can read text content. The viewer destroys it when it is replaced or the viewer goes away. */
+  document: PDFDocumentProxy;
+}
+export interface PdfViewerRenderedEvent {
+  pageCount: number;
+  /** CSS px per PDF point of the first page. */
+  scale: number;
+  /** Displayed (CSS px) width of every page. */
+  pageWidths: number[];
+}
+type PdfJsModule = typeof import('pdfjs-dist');
+type Status = 'idle' | 'loading' | 'ready' | 'error';
+interface PageView {
+  number: number;
+  cssWidth: number;
+  cssHeight: number;
+  canvasWidth: number;
+  canvasHeight: number;
+  fields: FieldView[];
+}
+interface FieldView {
+  id: string;
+  label: string;
+  tone: PdfViewerTone;
+  left: number;
+  top: number;
+  width: number | null;
+  maxWidth: number;
+  height: number;
+  fontPx: number;
+}
+/**
+ * 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).
+ *
+ *   <ui-pdf-viewer [data]="buffer()" [fields]="badges()" ariaLabel="Contract preview" (loaded)="onLoaded($event)" />
+ *   <ui-pdf-viewer src="/files/contract.pdf" [httpHeaders]="{ Authorization: 'Bearer ' + token }" />
+ *
+ * - `src` / `data`: a URL, or the bytes (`data` wins). The bytes are copied, so your buffer stays usable.
+ * - `workerSrc` or the `PDF_VIEWER_WORKER_SRC` token: the pdf.js worker URL. Without either the viewer shows "PDF worker is not configured."
+ * - `maxPageWidth` (default 700): pages are drawn this wide, or the container's width when narrower; never larger.
+ * - `pixelRatio`: canvas pixels per CSS pixel; default is the screen's ratio between 1 and 3.
+ * - `fields`: badges positioned in PDF points (origin bottom-left); they scale with the page.
+ * - `loaded` / `pagesRendered` / `loadFailed`: see the event types. A new `src` / `data` replaces the document; a slow older load never paints.
+ *   A page that fails to draw after `loaded` also emits `loadFailed`, shows the error state and destroys the document that `loaded` handed to the host.
+ * - A page's canvas never exceeds 16,000,000 pixels (Safari limit); the pixel ratio is lowered for such a page, its CSS size is unchanged.
+ * - All canvases together never exceed 48,000,000 pixels (iOS Safari limits total canvas memory): a long document is drawn at a lower
+ *   density, the same for every page and never below 1 pixel per CSS pixel. CSS sizes are unchanged.
+ * - `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.
+ * - 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).
+ */
+export declare class PdfViewerComponent {
+  /** PDF URL. Ignored while `data` is set. */
+  readonly src: import("@angular/core").InputSignal<string | null>;
+  /** PDF bytes. Wins over `src`. */
+  readonly data: import("@angular/core").InputSignal<ArrayBuffer | Uint8Array<ArrayBufferLike> | null>;
+  /** Request headers for `src`. Changes are detected by content, but pass a stable reference when you can. */
+  readonly httpHeaders: import("@angular/core").InputSignal<Record<string, string>>;
+  readonly withCredentials: import("@angular/core").InputSignal<boolean>;
+  /** pdf.js worker URL; falls back to the `PDF_VIEWER_WORKER_SRC` token. */
+  readonly workerSrc: import("@angular/core").InputSignal<string>;
+  /** Widest a page is drawn, in CSS px. */
+  readonly maxPageWidth: import("@angular/core").InputSignal<number>;
+  /** Canvas pixels per CSS pixel; null = the screen's ratio, limited to 1..3. */
+  readonly pixelRatio: import("@angular/core").InputSignal<number | null>;
+  readonly fields: import("@angular/core").InputSignal<PdfViewerField[]>;
+  /** Accessible name of the viewer. */
+  readonly ariaLabel: import("@angular/core").InputSignal<string>;
+  readonly loadingText: import("@angular/core").InputSignal<string>;
+  readonly errorText: import("@angular/core").InputSignal<string>;
+  readonly loaded: import("@angular/core").OutputEmitterRef<PdfViewerLoadedEvent>;
+  readonly loadFailed: import("@angular/core").OutputEmitterRef<unknown>;
+  readonly pagesRendered: import("@angular/core").OutputEmitterRef<PdfViewerRenderedEvent>;
+  protected readonly status: import("@angular/core").WritableSignal<Status>;
+  private readonly pageSizes;
+  private readonly containerWidth;
+  private readonly customError;
+  protected readonly errorMessage: import("@angular/core").Signal<string>;
+  /** Changes exactly when some canvas bitmap changes size (and so is cleared). */
+  private readonly drawKey;
+  private readonly effectiveWidth;
+  protected readonly views: import("@angular/core").Signal<PageView[]>;
+  private readonly host;
+  private readonly injector;
+  private readonly tokenWorkerSrc;
+  private readonly isBrowser;
+  private readonly headersKey;
+  /** Bumped by every new load, replacement and destroy; an async step whose token no longer matches stops. */
+  private loadToken;
+  /** Bumped by every (re)draw so only the newest draw paints. */
+  private drawToken;
+  private doc;
+  private loadingTask;
+  private pageProxies;
+  private renderTasks;
+  private observer;
+  private frame;
+  private lastDrawKey;
+  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>;
+  private resolvedRatio;
+  private widthFor;
+  private startLoad;
+  private fail;
+  private scheduleDraw;
+  private draw;
+  private onResize;
+  private cancelRenders;
+  private teardown;
+  private destroyDoc;
+  static ɵfac: i0.ɵɵFactoryDeclaration<PdfViewerComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<PdfViewerComponent, "ui-pdf-viewer", never, {
+    "src": {
+      "alias": "src";
+      "required": false;
+      "isSignal": true;
+    };
+    "data": {
+      "alias": "data";
+      "required": false;
+      "isSignal": true;
+    };
+    "httpHeaders": {
+      "alias": "httpHeaders";
+      "required": false;
+      "isSignal": true;
+    };
+    "withCredentials": {
+      "alias": "withCredentials";
+      "required": false;
+      "isSignal": true;
+    };
+    "workerSrc": {
+      "alias": "workerSrc";
+      "required": false;
+      "isSignal": true;
+    };
+    "maxPageWidth": {
+      "alias": "maxPageWidth";
+      "required": false;
+      "isSignal": true;
+    };
+    "pixelRatio": {
+      "alias": "pixelRatio";
+      "required": false;
+      "isSignal": true;
+    };
+    "fields": {
+      "alias": "fields";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "loadingText": {
+      "alias": "loadingText";
+      "required": false;
+      "isSignal": true;
+    };
+    "errorText": {
+      "alias": "errorText";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "loaded": "loaded";
+    "loadFailed": "loadFailed";
+    "pagesRendered": "pagesRendered";
+  }, never, never, true, never>;
+}