@nexterajs/report-viewer 0.0.1 → 0.1.0

package/types/nexterajs-report-viewer.d.ts

@@ -6,7 +6,7 @@ import { Subject } from 'rxjs';
  * The version of the viewer protocol this package speaks: the `protocol` member of every
  * `AngularViewerData` answer from `Nextera.Report.AspNetCore`.
  */
-declare const NXR_VIEWER_PROTOCOL = 1;
+declare const NXE_VIEWER_PROTOCOL = 1;
 
 /**
  * The viewer options as `Nextera.Report.AspNetCore` sends them in the AngularViewerData answer: every
@@ -14,21 +14,21 @@ declare const NXR_VIEWER_PROTOCOL = 1;
  * colours, where `null` means the theme's colour.
  */
 /** How pages are laid out. */
-type NxrViewMode = 'SinglePage' | 'Continuous' | 'MultiplePages';
+type NxeViewMode = 'SinglePage' | 'Continuous' | 'MultiplePages';
 /** Horizontal placement; `Default` is the viewer's usual placement for the element. */
-type NxrContentAlignment = 'Left' | 'Center' | 'Right' | 'Default';
+type NxeContentAlignment = 'Left' | 'Center' | 'Right' | 'Default';
 /** One toolbar, or page navigation and zoom in a second bar. */
-type NxrToolbarDisplayMode = 'Simple' | 'Separated';
+type NxeToolbarDisplayMode = 'Simple' | 'Separated';
 /** What opens a toolbar menu. */
-type NxrShowMenuMode = 'Click' | 'Hover';
+type NxeShowMenuMode = 'Click' | 'Hover';
 /** Which input the controls are sized for. */
-type NxrInterfaceType = 'Auto' | 'Mouse' | 'Touch' | 'Mobile';
+type NxeInterfaceType = 'Auto' | 'Mouse' | 'Touch' | 'Mobile';
 /** Where the server keeps the rendered report between requests. */
-type NxrCacheMode = 'None' | 'ObjectCache' | 'ObjectSession' | 'StringCache' | 'StringSession';
+type NxeCacheMode = 'None' | 'ObjectCache' | 'ObjectSession' | 'StringCache' | 'StringSession';
 /** A kept report's priority when the server's memory cache compacts. */
-type NxrCacheItemPriority = 'Low' | 'BelowNormal' | 'Normal' | 'AboveNormal' | 'High' | 'NotRemovable';
+type NxeCacheItemPriority = 'Low' | 'BelowNormal' | 'Normal' | 'AboveNormal' | 'High' | 'NotRemovable';
 /** The host's action names, each put in place of `{action}` in the component's `requestUrl`. */
-interface NxrViewerActions {
+interface NxeViewerActions {
     /** Answers GetReport. */
     getReport: string;
     /** Answers GetPages, Find and UpdateCache, unless the cache mode is `None`. */
@@ -36,28 +36,28 @@ interface NxrViewerActions {
     /** Answers ExportReport; when empty, ExportReport goes where GetPages goes. */
     exportReport: string;
 }
-interface NxrAppearanceOptions {
+interface NxeAppearanceOptions {
     allowMobileMode: boolean;
     allowTouchZoom: boolean;
     backgroundColor: string | null;
     bookmarksTreeWidth: number;
     customCss: string;
     fullScreenMode: boolean;
-    interfaceType: NxrInterfaceType;
+    interfaceType: NxeInterfaceType;
     openLinksWindow: string;
-    pageAlignment: NxrContentAlignment;
+    pageAlignment: NxeContentAlignment;
     pageBorderColor: string | null;
     rightToLeft: boolean;
     scrollbarsMode: boolean;
     showPageShadow: boolean;
     showTooltips: boolean;
 }
-interface NxrToolbarOptions {
-    alignment: NxrContentAlignment;
+interface NxeToolbarOptions {
+    alignment: NxeContentAlignment;
     autoHide: boolean;
     backgroundColor: string | null;
     borderColor: string | null;
-    displayMode: NxrToolbarDisplayMode;
+    displayMode: NxeToolbarDisplayMode;
     fontColor: string | null;
     fontFamily: string;
     menuAnimation: boolean;
@@ -71,7 +71,7 @@ interface NxrToolbarOptions {
     showFirstPageButton: boolean;
     showFullScreenButton: boolean;
     showLastPageButton: boolean;
-    showMenuMode: NxrShowMenuMode;
+    showMenuMode: NxeShowMenuMode;
     showNextPageButton: boolean;
     showOpenButton: boolean;
     showParametersButton: boolean;
@@ -85,78 +85,78 @@ interface NxrToolbarOptions {
     showSignatureButton: boolean;
     showViewModeButton: boolean;
     showZoomButton: boolean;
-    viewMode: NxrViewMode;
+    viewMode: NxeViewMode;
     visible: boolean;
     /** The starting zoom, in percent. */
     zoom: number;
 }
-interface NxrExportOptions {
+interface NxeExportOptions {
     showExportToHtml: boolean;
     showExportToPdf: boolean;
 }
-interface NxrServerOptions {
+interface NxeServerOptions {
     allowAutoUpdateCache: boolean;
-    cacheItemPriority: NxrCacheItemPriority;
-    cacheMode: NxrCacheMode;
+    cacheItemPriority: NxeCacheItemPriority;
+    cacheMode: NxeCacheMode;
     /** Minutes a kept report survives without a request about it. */
     cacheTimeout: number;
     /** Seconds the viewer waits for an answer. */
     requestTimeout: number;
     showServerErrorPage: boolean;
 }
-interface NxrViewerOptions {
+interface NxeViewerOptions {
     /** A Stimulsoft viewer theme name, such as `Office2022WhiteBlue`. */
     theme: string;
     localization: string;
     width: string;
     height: string;
-    actions: NxrViewerActions;
-    appearance: NxrAppearanceOptions;
-    toolbar: NxrToolbarOptions;
-    exports: NxrExportOptions;
-    server: NxrServerOptions;
+    actions: NxeViewerActions;
+    appearance: NxeAppearanceOptions;
+    toolbar: NxeToolbarOptions;
+    exports: NxeExportOptions;
+    server: NxeServerOptions;
 }
 
 /** The value of a request's `nextera_action` field. */
-type NxrViewerAction = 'AngularViewerData' | 'GetReport' | 'GetPages' | 'Find' | 'ExportReport' | 'UpdateCache';
-interface NxrPageSize {
+type NxeViewerAction = 'AngularViewerData' | 'GetReport' | 'GetPages' | 'Find' | 'ExportReport' | 'UpdateCache';
+interface NxePageSize {
     /** 1-based. */
     pageNumber: number;
     widthPoints: number;
     heightPoints: number;
 }
 /** A rectangle on a page, in points from its top left corner. */
-interface NxrBounds {
+interface NxeBounds {
     x: number;
     y: number;
     width: number;
     height: number;
 }
-interface NxrBookmark {
+interface NxeBookmark {
     title: string;
     /** 0-based. */
     pageIndex: number;
-    bounds: NxrBounds;
+    bounds: NxeBounds;
 }
 /** The HTML of consecutive pages, starting at a 0-based index. */
-interface NxrPagesAnswer {
+interface NxePagesAnswer {
     startIndex: number;
     pages: string[];
 }
 /** The answer to GetReport. */
-interface NxrReportAnswer {
+interface NxeReportAnswer {
     reportName: string;
     pageCount: number;
     /** Every page's size, in page order. */
-    pages: NxrPageSize[];
-    bookmarks: NxrBookmark[];
+    pages: NxePageSize[];
+    bookmarks: NxeBookmark[];
     /** The stylesheet every page's HTML needs. */
     pageCss: string;
     /** The pages GetReport was asked for, or null when it was asked for none. */
-    pagesHtml: NxrPagesAnswer | null;
+    pagesHtml: NxePagesAnswer | null;
 }
 /** Why a request failed. */
-interface NxrViewerFailure {
+interface NxeViewerFailure {
     /** The HTTP status of the error answer; 0 when there was none: no answer, a timeout, or an unreadable success answer. */
     status: number;
     /**
@@ -177,9 +177,9 @@ interface NxrViewerFailure {
  * Every caption and message the viewer shows, in its built-in English. A key in PascalCase is the name
  * Stimulsoft's viewer gives the same text, such as `PageOf`; a key in camelCase names a message only this
  * viewer has. The English is this package's own. A later plan lets a host's translation file replace any
- * of them, so code reads them from an `NxrViewerStrings` value wherever one is at hand.
+ * of them, so code reads them from an `NxeViewerStrings` value wherever one is at hand.
  */
-declare const NXR_ENGLISH: {
+declare const NXE_ENGLISH: {
     /** The label before the page-number box. */
     Page: string;
     /** The label between the page-number box and the page count. */
@@ -188,17 +188,29 @@ declare const NXR_ENGLISH: {
     PrevPage: string;
     NextPage: string;
     LastPage: string;
+    /** The save button's caption and tooltip; its menu items are captioned by the format they write. */
+    Save: string;
+    SaveToolTip: string;
+    /** The view-mode button's tooltip, and its menu items, whose captions are the mode names. */
+    ViewModeToolTip: string;
+    SinglePage: string;
+    Continuous: string;
+    MultiplePages: string;
+    /** The zoom button's tooltip; its caption is the current percentage, so it has no key. */
+    ZoomToolTip: string;
+    ZoomOnePage: string;
+    ZoomPageWidth: string;
     errorUnreachable: string;
     errorStatus: string;
     errorTimeout: string;
     errorMalformed: string;
     errorProtocol: string;
 };
-type NxrViewerStrings = Readonly<Record<keyof typeof NXR_ENGLISH, string>>;
+type NxeViewerStrings = Readonly<Record<keyof typeof NXE_ENGLISH, string>>;
 
 /** What the component's `postParametersFunction` is called with: the request's action and its parameters. */
-interface NxrPostParametersData {
-    action: NxrViewerAction;
+interface NxePostParametersData {
+    action: NxeViewerAction;
     [parameter: string]: unknown;
 }
 /**
@@ -206,24 +218,24 @@ interface NxrPostParametersData {
  * Each key of an object it returns becomes a form field of the request, replacing a field of the same
  * name; anything else it returns adds nothing.
  */
-type NxrPostParametersFunction = (data: NxrPostParametersData) => unknown;
+type NxePostParametersFunction = (data: NxePostParametersData) => unknown;
 /** What every request is built from. */
-interface NxrRequestContext {
+interface NxeRequestContext {
     /** The component's `requestUrl`: each request's host action takes the place of `{action}`. */
     requestUrl: string;
     /** The component's `properties`, sent as JSON when truthy. */
     properties: unknown;
     /** The component's `postParametersFunction`. */
-    postParametersFunction: NxrPostParametersFunction | null | undefined;
+    postParametersFunction: NxePostParametersFunction | null | undefined;
     /** The strings failures are described with. */
-    strings: NxrViewerStrings;
+    strings: NxeViewerStrings;
 }
 
 /** The page on screen. */
-interface NxrShownPage {
+interface NxeShownPage {
     /** 0-based. */
     index: number;
-    size: NxrPageSize;
+    size: NxePageSize;
     /** The page's HTML, or null while it has not arrived: while it is on its way, or after its request failed. */
     html: string | null;
 }
@@ -233,7 +245,7 @@ interface NxrShownPage {
  * Every signal changes only in this service's methods and in the answers they handle; nothing reacts to
  * a signal changing. Each viewer provides its own session, so viewers on one page never share state.
  */
-declare class NxrViewerSessionService {
+declare class NxeViewerSessionService {
     private readonly client;
     private readonly optionsState;
     private readonly reportState;
@@ -242,23 +254,29 @@ declare class NxrViewerSessionService {
     private readonly pendingState;
     private readonly failureState;
     /** The options from the last AngularViewerData answer. */
-    readonly options: _angular_core.Signal<NxrViewerOptions | null>;
+    readonly options: _angular_core.Signal<NxeViewerOptions | null>;
     /** The report from the last GetReport answer, or null before one. */
-    readonly report: _angular_core.Signal<NxrReportAnswer | null>;
+    readonly report: _angular_core.Signal<NxeReportAnswer | null>;
     /** The 0-based index of the page on screen. */
     readonly pageIndex: _angular_core.Signal<number>;
     /** The failure on show, until it is dismissed. */
-    readonly failure: _angular_core.Signal<NxrViewerFailure | null>;
+    readonly failure: _angular_core.Signal<NxeViewerFailure | null>;
     /** How many pages the report has; 0 before one is loaded. */
     readonly pageCount: _angular_core.Signal<number>;
     /** Whether a request the user waits for is on its way. Keep-alive requests do not count. */
     readonly busy: _angular_core.Signal<boolean>;
     /** The page on screen, or null before a report. */
-    readonly shownPage: _angular_core.Signal<NxrShownPage | null>;
+    readonly shownPage: _angular_core.Signal<NxeShownPage | null>;
+    /**
+     * Every page of the report, in order, each with its HTML when it has arrived. The page modes that show
+     * more than one page at a time lay these out and ask for the ones that come into view; a page holds its
+     * size, and so its place, before its HTML is here.
+     */
+    readonly allPages: _angular_core.Signal<readonly NxeShownPage[]>;
     /** Emits after each successful GetReport answer. */
     readonly reportLoaded: Subject<void>;
     /** Emits each failure put on show. */
-    readonly failed: Subject<NxrViewerFailure>;
+    readonly failed: Subject<NxeViewerFailure>;
     private context;
     private session;
     /** Every request the user waits for. */
@@ -272,12 +290,24 @@ declare class NxrViewerSessionService {
     private destroyed;
     constructor();
     /** Opens the report the host action names, in place of whatever this viewer showed. */
-    open(context: NxrRequestContext, action: string): void;
+    open(context: NxeRequestContext, action: string): void;
     /**
      * Shows the page at a 0-based index; an index outside the report is ignored. Asking for the page already
      * on screen fetches it again when its HTML is missing, as it is after its request failed.
      */
     goToPage(index: number): void;
+    /**
+     * Asks for a page's HTML without moving the page on screen, for the modes that show several pages at
+     * once and fetch the ones that come into view. A page already here, or already on its way, is left alone.
+     */
+    requestPage(index: number): void;
+    /** Moves the page on screen without asking for it, for scroll tracking, which follows what is drawn. */
+    markCurrentPage(index: number): void;
+    /**
+     * ExportReport: the report as a file, handed to the browser to save. The export never times out, so
+     * it is tracked as a request the user waits for and the toolbar stays disabled until the file is here.
+     */
+    exportTo(format: string): void;
     /** Takes the failure off show. */
     dismissFailure(): void;
     /**
@@ -303,8 +333,8 @@ declare class NxrViewerSessionService {
     /** Stops every request and the keep-alive. */
     private close;
     private connection;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxrViewerSessionService, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NxrViewerSessionService>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeViewerSessionService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NxeViewerSessionService>;
 }
 
 /**
@@ -312,7 +342,7 @@ declare class NxrViewerSessionService {
  * members for zoom, view mode, export, print, email and find arrive with the tasks that implement
  * those; a host that only pages through a report needs these three.
  */
-interface NxrViewerApi {
+interface NxeViewerApi {
     /** The 0-based page on screen. Setting it shows a page inside the report and ignores anything else. */
     currentPage: number;
     /** How many pages the report has; 0 before one is loaded. */
@@ -329,7 +359,7 @@ interface NxrViewerApi {
  *
  * Each viewer provides its own session, so several on a page never share a report or a token.
  */
-declare class NxrReportViewerComponent implements OnChanges {
+declare class NxeReportViewerComponent implements OnChanges {
     /** Each request's URL, with `{action}` in place of the host action it goes to. */
     readonly requestUrl: _angular_core.InputSignal<string>;
     /** The host action that answers the first request, and so names the report to open. */
@@ -345,15 +375,33 @@ declare class NxrReportViewerComponent implements OnChanges {
     /** Styles for the viewer's root element. Width, height and background take precedence over it. */
     readonly style: _angular_core.InputSignal<string | null>;
     /** Called for every request; each key of an object it returns becomes a form field. */
-    readonly postParametersFunction: _angular_core.InputSignal<NxrPostParametersFunction | null>;
+    readonly postParametersFunction: _angular_core.InputSignal<NxePostParametersFunction | null>;
     /** Emits after each report is loaded. */
     readonly loaded: _angular_core.OutputEmitterRef<void>;
     /** Emits every failure the viewer puts on show. */
-    readonly error: _angular_core.OutputEmitterRef<NxrViewerFailure>;
-    protected readonly session: NxrViewerSessionService;
+    readonly error: _angular_core.OutputEmitterRef<NxeViewerFailure>;
+    protected readonly session: NxeViewerSessionService;
     /** Stimulsoft's `api` object: what a host calls to drive the viewer from outside. */
-    readonly api: NxrViewerApi;
+    readonly api: NxeViewerApi;
     private readonly appearance;
+    private readonly pagesBox;
+    private readonly rootBox;
+    /**
+     * The mode the pages are shown in, and the zoom they are drawn at. Both start from the server's
+     * options and are then the user's, until a new report's options arrive and reset them — which is
+     * what `linkedSignal` says and an effect would only imply.
+     */
+    protected readonly viewMode: _angular_core.WritableSignal<NxeViewMode>;
+    protected readonly zoom: _angular_core.WritableSignal<number>;
+    /**
+     * The pages on screen: one in `SinglePage`, the whole report in the modes that scroll through it.
+     * A page carries its size before its HTML arrives, so the list holds its shape while the pages that
+     * come into view are fetched.
+     */
+    protected readonly shownPages: _angular_core.Signal<readonly NxeShownPage[]>;
+    /** Set while a page-navigation scroll is running, so scroll tracking does not fight it. */
+    private scrollingToPage;
+    private scrollSettled;
     protected readonly toolbarVisible: _angular_core.Signal<boolean>;
     protected readonly pageCss: _angular_core.Signal<string>;
     protected readonly showPageShadow: _angular_core.Signal<boolean>;
@@ -364,6 +412,17 @@ declare class NxrReportViewerComponent implements OnChanges {
     protected readonly pagesOverflow: _angular_core.Signal<"auto" | "hidden">;
     protected readonly rootWidth: _angular_core.Signal<string>;
     protected readonly rootBackgroundColor: _angular_core.Signal<string>;
+    /**
+     * The height the viewer was measured to fill, once it is known.
+     *
+     * The report panel is what scrolls, as Stimulsoft's does — its panel measures 836 px against a
+     * 16 513 px report while the document itself does not scroll at all. That needs the viewer to have a
+     * definite height, and a host that asks for `100%` inside a container whose own height is automatic
+     * does not give it one: the viewer would then grow to the whole report, 29 pages of it, and the
+     * page would scroll instead of the panel. So when the height the host asked for cannot resolve, the
+     * viewer measures the room between its top and the bottom of the window and takes that.
+     */
+    private readonly measuredHeight;
     protected readonly rootHeight: _angular_core.Signal<string>;
     constructor();
     /**
@@ -372,6 +431,43 @@ declare class NxrReportViewerComponent implements OnChanges {
      * again. Matching that keeps a host's reload behaviour the same across the swap.
      */
     ngOnChanges(): void;
+    /**
+     * Page navigation. In a mode that scrolls through the whole report the page is reached by scrolling
+     * to it, over 350 ms, which is what Stimulsoft's navigation actions do; in `SinglePage` the page is
+     * simply the one shown.
+     */
+    protected navigateTo(index: number): void;
+    /** The page number is kept and nothing scrolls, as Stimulsoft's view-mode actions leave it. */
+    protected setViewMode(mode: NxeViewMode): void;
+    /** Nothing preserves the scroll offset across a zoom change, so the visible region shifts. */
+    protected setZoom(zoom: number): void;
+    /**
+     * Fit a whole page, or a page's width, in the panel. Stimulsoft computes this once from what is on
+     * screen and stores the number as the zoom; no fit mode is remembered, so a later resize does not
+     * re-fit. The 40 px it subtracts is the panel's padding and the page's margins.
+     */
+    protected fitTo(what: 'page' | 'width'): void;
+    /**
+     * Scrolling asks for the pages that have come into view, and, once it has stopped for 300 ms, moves
+     * the page the toolbar reports to the first one still on screen — Stimulsoft's scroll tracking.
+     */
+    protected onScroll(): void;
+    /** The room on screen changed, so the viewer measures itself against it again. */
+    protected onWindowResize(): void;
+    /** Lets the new layout reach the DOM, then fits the viewer to it and asks for what is on screen. */
+    private afterPagesSettle;
+    /**
+     * Takes the room between the viewer's top and the bottom of the window when the height the host
+     * asked for did not resolve, so the panel inside scrolls rather than the page. Measured before the
+     * height is applied, and again only when the window changes, so it never chases its own answer.
+     */
+    private fitToAvailableRoom;
+    /** Every page whose box meets the panel, plus one either side, so scrolling stays ahead of the eye. */
+    private requestVisiblePages;
+    /** The first page whose bottom is still below the panel's scroll offset. */
+    private trackCurrentPage;
+    /** Stimulsoft animates the panel to the page's top over 350 ms, in steps of about 30 ms. */
+    private scrollToPage;
     /**
      * The getters read the session's signals, so a host that asks between renders gets what is on
      * screen now. Built from a captured session rather than `this`, because `this` inside an object
@@ -379,9 +475,9 @@ declare class NxrReportViewerComponent implements OnChanges {
      */
     private buildApi;
     private context;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxrReportViewerComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxrReportViewerComponent, "nxr-report-viewer", never, { "requestUrl": { "alias": "requestUrl"; "required": false; "isSignal": true; }; "action": { "alias": "action"; "required": false; "isSignal": true; }; "properties": { "alias": "properties"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "backgroundColor": { "alias": "backgroundColor"; "required": false; "isSignal": true; }; "style": { "alias": "style"; "required": false; "isSignal": true; }; "postParametersFunction": { "alias": "postParametersFunction"; "required": false; "isSignal": true; }; }, { "loaded": "loaded"; "error": "error"; }, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeReportViewerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeReportViewerComponent, "nxe-report-viewer", never, { "requestUrl": { "alias": "requestUrl"; "required": false; "isSignal": true; }; "action": { "alias": "action"; "required": false; "isSignal": true; }; "properties": { "alias": "properties"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "backgroundColor": { "alias": "backgroundColor"; "required": false; "isSignal": true; }; "style": { "alias": "style"; "required": false; "isSignal": true; }; "postParametersFunction": { "alias": "postParametersFunction"; "required": false; "isSignal": true; }; }, { "loaded": "loaded"; "error": "error"; }, never, never, true, never>;
 }
 
-export { NXR_VIEWER_PROTOCOL, NxrReportViewerComponent };
-export type { NxrPostParametersData, NxrPostParametersFunction, NxrViewerApi, NxrViewerFailure };
+export { NXE_VIEWER_PROTOCOL, NxeReportViewerComponent };
+export type { NxePostParametersData, NxePostParametersFunction, NxeViewerApi, NxeViewerFailure };