@forgeroute/ui 0.4.57 → 0.4.58

package/package.json

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

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

@@ -19,6 +19,26 @@ export interface PdfViewerField {
   label: string;
   tone?: PdfViewerTone;
 }
+/** State of a clickable spot over a page. */
+export type PdfViewerHotspotState = 'ready' | 'blocked' | 'signed';
+/** A clickable box drawn over a page (for example "Sign here"). Positions are PDF points with the origin at the page's bottom-left corner. */
+export interface PdfViewerHotspot {
+  id: string;
+  /** 1-based page number; a hotspot on a page that does not exist is ignored. */
+  page: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** `ready` = a button, `blocked` = the same button disabled (shows `blockedLabel`), `signed` = shows `image` instead of a button. */
+  state: PdfViewerHotspotState;
+  label?: string;
+  blockedLabel?: string;
+  ariaLabel?: string;
+  /** The image (a data URL) shown while `state` is `signed`. */
+  image?: string | null;
+  imageAlt?: string;
+}
 export interface PdfViewerLoadedEvent {
   pageCount: number;
   /** Every page's size in PDF points at scale 1. */
@@ -45,6 +65,15 @@ interface PageView {
   canvasWidth: number;
   canvasHeight: number;
   fields: FieldView[];
+  hotspots: HotspotView[];
+}
+interface HotspotView {
+  hotspot: PdfViewerHotspot;
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  fontPx: number;
 }
 interface FieldView {
   id: string;
@@ -96,6 +125,7 @@ export declare class PdfViewerUnsupportedError extends Error {
  * - `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.
+ * - `hotspots`: clickable boxes (e.g. "Sign here") in the same coordinates; `ready` is a button, `blocked` a disabled one, `signed` shows an image. `(hotspotActivate)` gives the id.
  * - `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.
@@ -127,6 +157,8 @@ export declare class PdfViewerComponent {
   /** 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[]>;
+  /** Clickable boxes over the pages (e.g. "Sign here"), in PDF points with the origin bottom-left; `(hotspotActivate)` gives the id of the one clicked. */
+  readonly hotspots: import("@angular/core").InputSignal<PdfViewerHotspot[]>;
   /** Accessible name of the viewer. */
   readonly ariaLabel: import("@angular/core").InputSignal<string>;
   readonly loadingText: import("@angular/core").InputSignal<string>;
@@ -137,6 +169,8 @@ export declare class PdfViewerComponent {
   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>;
+  /** The id of the hotspot that was clicked (only a `ready` hotspot can be). */
+  readonly hotspotActivate: import("@angular/core").OutputEmitterRef<string>;
   readonly loaded: import("@angular/core").OutputEmitterRef<PdfViewerLoadedEvent>;
   readonly loadFailed: import("@angular/core").OutputEmitterRef<unknown>;
   readonly pagesRendered: import("@angular/core").OutputEmitterRef<PdfViewerRenderedEvent>;
@@ -226,6 +260,11 @@ export declare class PdfViewerComponent {
       "required": false;
       "isSignal": true;
     };
+    "hotspots": {
+      "alias": "hotspots";
+      "required": false;
+      "isSignal": true;
+    };
     "ariaLabel": {
       "alias": "ariaLabel";
       "required": false;
@@ -257,6 +296,7 @@ export declare class PdfViewerComponent {
       "isSignal": true;
     };
   }, {
+    "hotspotActivate": "hotspotActivate";
     "loaded": "loaded";
     "loadFailed": "loadFailed";
     "pagesRendered": "pagesRendered";
@@ -274,4 +314,229 @@ export interface ForgeroutePdfOptions {
  * 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;
+export declare function provideForgeroutePdf(options: ForgeroutePdfOptions): EnvironmentProviders;
+/**
+ * A dialog that shows one PDF with Download and Print buttons: the file name as the title, the pages below (`ui-pdf-viewer`), a skeleton
+ * while the host is still fetching the bytes, an alert when the fetch failed. The HOST fetches (so its own auth / interceptors apply) and
+ * passes the bytes:
+ *
+ *   <ui-document-viewer-modal [open]="open()" [fileName]="name()" [data]="bytes()" [loading]="loading()" [error]="error()" (closed)="close()" />
+ *
+ * Download saves the bytes under `fileName`; Print opens the browser's print dialog for them (a new tab when the browser blocks the
+ * hidden print frame). Both are disabled until there are bytes. The pdf.js worker comes from `provideForgeroutePdf` (or `workerSrc`).
+ * Test ids: `document-viewer`, `document-viewer-download`, `document-viewer-print`, `document-viewer-loading`, `document-viewer-error`.
+ */
+export declare class DocumentViewerModalComponent {
+  readonly open: import("@angular/core").InputSignal<boolean>;
+  /** Shown as the dialog title and used as the Download file name. */
+  readonly fileName: import("@angular/core").InputSignal<string>;
+  /** The PDF bytes (null until fetched). */
+  readonly data: import("@angular/core").InputSignal<ArrayBuffer | Uint8Array<ArrayBufferLike> | null>;
+  /** The host is still fetching the bytes: a skeleton shows. */
+  readonly loading: import("@angular/core").InputSignal<boolean>;
+  /** The host's message when the fetch failed (empty = no error). */
+  readonly error: import("@angular/core").InputSignal<string>;
+  readonly loadingText: import("@angular/core").InputSignal<string>;
+  readonly closed: import("@angular/core").OutputEmitterRef<void>;
+  protected readonly hasData: import("@angular/core").Signal<boolean>;
+  private blob;
+  /** Saves the bytes as a PDF named after `fileName`. */
+  protected download(): void;
+  /** Opens the browser's print dialog for the PDF through a hidden frame (a new tab when the browser blocks it). */
+  protected print(): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<DocumentViewerModalComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<DocumentViewerModalComponent, "ui-document-viewer-modal", never, {
+    "open": {
+      "alias": "open";
+      "required": false;
+      "isSignal": true;
+    };
+    "fileName": {
+      "alias": "fileName";
+      "required": false;
+      "isSignal": true;
+    };
+    "data": {
+      "alias": "data";
+      "required": false;
+      "isSignal": true;
+    };
+    "loading": {
+      "alias": "loading";
+      "required": false;
+      "isSignal": true;
+    };
+    "error": {
+      "alias": "error";
+      "required": false;
+      "isSignal": true;
+    };
+    "loadingText": {
+      "alias": "loadingText";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "closed": "closed";
+  }, never, never, true, never>;
+}
+/** Where a signature goes: PDF points, origin at the page's bottom-left corner, page numbers from 1. */
+export interface DocumentSignField {
+  /** Reported back in the result; defaults to the field's position in the list ("1", "2", …). */
+  id?: string;
+  page: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export interface DocumentSignedField {
+  id: string;
+  page: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** The signature image (PNG data URL) that was applied to this field. */
+  signatureImage: string;
+}
+export interface DocumentSignResult {
+  /** The signature image the signer created (the same image is on every field). */
+  signatureDataUrl: string;
+  signedAt: string;
+  fields: DocumentSignedField[];
+}
+/** Every text of the dialog; pass only the ones you want to change (`[texts]="{ title: 'Sign the contract' }"`). */
+export interface DocumentSignTexts {
+  title: string;
+  loading: string;
+  step1: string;
+  namePlaceholder: string;
+  previewEmpty: string;
+  saveSignature: string;
+  change: string;
+  step2: string;
+  signHere: string;
+  addSignatureFirst: string;
+  allSigned: string;
+  cancel: string;
+  complete: string;
+  submitting: string;
+  noFields: string;
+}
+/**
+ * Shows any PDF and collects a signature on it, wherever the host says the signature goes. Generic on purpose: the HOST fetches the
+ * bytes (its own auth, pre-filling, prefilled forms) and says where the signature fields are (`fields`, PDF points, bottom-left origin);
+ * the dialog does the rest: the signer types their name, it becomes a handwriting-style image, the signer clicks each field to apply it,
+ * and `(signed)` reports the image and every field with its position. The host stores the signature however it needs.
+ *
+ *   <ui-document-sign-modal [open]="open()" [data]="bytes()" [fields]="fields()" [loading]="loading()" [error]="error()"
+ *       [signerName]="user.name" [submitting]="saving()" (signed)="save($event)" (closed)="open.set(false)" />
+ *
+ * - `savedSignature` (a data URL, e.g. from the user's profile) skips the typing step; it is scaled down to the standard 600x60 image.
+ *   `(signatureCreated)` gives the new image so the host can keep it for next time.
+ * - Complete is disabled until every field is signed (and while there are no fields); the footer counts "N of M signed".
+ * - "Change" clears the signature and every applied field so the signer can start again.
+ * - `(signed)` does not close the dialog: the host closes it (`[open]="false"`) when its own save succeeded, or shows `error`.
+ * - The pdf.js worker comes from `provideForgeroutePdf` (or the viewer's `workerSrc`).
+ * Test ids: `sign-modal`, `sign-loading`, `sign-error`, `signature-step`, `typed-name-input`, `typed-signature-preview`, `save-typed-signature`,
+ * `redraw-signature`, `apply-step`, `sign-progress`, `sign-cancel`, `sign-complete`, `pdf-hotspot-<field id>`.
+ */
+export declare class DocumentSignModalComponent {
+  readonly open: import("@angular/core").InputSignal<boolean>;
+  /** The PDF bytes (null until the host has them). */
+  readonly data: import("@angular/core").InputSignal<ArrayBuffer | Uint8Array<ArrayBufferLike> | null>;
+  /** Where the signature goes. */
+  readonly fields: import("@angular/core").InputSignal<DocumentSignField[]>;
+  /** The host is still fetching the document: a skeleton shows. */
+  readonly loading: import("@angular/core").InputSignal<boolean>;
+  /** The host's error text (empty = none): shown instead of the document. */
+  readonly error: import("@angular/core").InputSignal<string>;
+  /** Prefills the typed-name box. */
+  readonly signerName: import("@angular/core").InputSignal<string>;
+  /** A signature the signer made before (PNG data URL): used at once, scaled to the standard size. */
+  readonly savedSignature: import("@angular/core").InputSignal<string | null>;
+  /** The host is saving the result: Complete shows a spinner and cannot be pressed twice. */
+  readonly submitting: import("@angular/core").InputSignal<boolean>;
+  /** Texts to change (the rest stay in English). */
+  readonly texts: import("@angular/core").InputSignal<Partial<DocumentSignTexts>>;
+  /** The signer finished: the signature image and every field with its position. The dialog stays open for the host to close. */
+  readonly signed: import("@angular/core").OutputEmitterRef<DocumentSignResult>;
+  /** The signer created a new signature (typed name saved): the host may keep it. */
+  readonly signatureCreated: import("@angular/core").OutputEmitterRef<string>;
+  /** The dialog was dismissed (Cancel, Escape, X, backdrop). */
+  readonly closed: import("@angular/core").OutputEmitterRef<void>;
+  protected readonly t: import("@angular/core").Signal<DocumentSignTexts>;
+  protected readonly typedName: import("@angular/core").WritableSignal<string>;
+  protected readonly signature: import("@angular/core").WritableSignal<string | null>;
+  /** Field id -> the image applied to it. */
+  private readonly applied;
+  /** The fields with their ids filled in ("1", "2", … when the host gave none). */
+  private readonly resolved;
+  protected readonly signedCount: import("@angular/core").Signal<number>;
+  protected readonly allSigned: import("@angular/core").Signal<boolean>;
+  protected readonly hotspots: import("@angular/core").Signal<PdfViewerHotspot[]>;
+  constructor();
+  protected cancel(): void;
+  /** Turns the typed name into a handwriting-style PNG (600x60, left-aligned) and makes it the signature. */
+  protected saveTypedSignature(): Promise<void>;
+  /** Clears the signature and everything applied, so the signer starts again. */
+  protected changeSignature(): void;
+  /** Puts the signature on one field (only possible once there is a signature). */
+  protected apply(fieldId: string): void;
+  protected complete(): void;
+  /** Scales a saved signature down to fit 600x60 (never up), left-aligned and centred vertically, so old oversized images weigh the same as new ones. */
+  private normalize;
+  static ɵfac: i0.ɵɵFactoryDeclaration<DocumentSignModalComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<DocumentSignModalComponent, "ui-document-sign-modal", never, {
+    "open": {
+      "alias": "open";
+      "required": false;
+      "isSignal": true;
+    };
+    "data": {
+      "alias": "data";
+      "required": false;
+      "isSignal": true;
+    };
+    "fields": {
+      "alias": "fields";
+      "required": false;
+      "isSignal": true;
+    };
+    "loading": {
+      "alias": "loading";
+      "required": false;
+      "isSignal": true;
+    };
+    "error": {
+      "alias": "error";
+      "required": false;
+      "isSignal": true;
+    };
+    "signerName": {
+      "alias": "signerName";
+      "required": false;
+      "isSignal": true;
+    };
+    "savedSignature": {
+      "alias": "savedSignature";
+      "required": false;
+      "isSignal": true;
+    };
+    "submitting": {
+      "alias": "submitting";
+      "required": false;
+      "isSignal": true;
+    };
+    "texts": {
+      "alias": "texts";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "signed": "signed";
+    "signatureCreated": "signatureCreated";
+    "closed": "closed";
+  }, never, never, true, never>;
+}