Merge pull request #17879 from ex37/master

Improve type definitions for the viewer

tsconfig.json

@@ -16,7 +16,7 @@
       "display-node_utils": ["./src/display/node_utils"],
       "fluent-bundle": ["./node_modules/@fluent/bundle/esm/index.js"],
       "fluent-dom": ["./node_modules/@fluent/dom/esm/index.js"],
-      "web-null_l10n": ["../web/genericl10n.js"]
+      "web-null_l10n": ["./web/genericl10n"]
     }
   },
   "files": ["src/pdf.js", "web/pdf_viewer.component.js"]

web/annotation_editor_params.js

@@ -13,8 +13,22 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+
 import { AnnotationEditorParamsType } from "pdfjs-lib";
 
+/**
+ * @typedef {Object} AnnotationEditorParamsOptions
+ * @property {HTMLInputElement} editorFreeTextFontSize
+ * @property {HTMLInputElement} editorFreeTextColor
+ * @property {HTMLInputElement} editorInkColor
+ * @property {HTMLInputElement} editorInkThickness
+ * @property {HTMLInputElement} editorInkOpacity
+ * @property {HTMLButtonElement} editorStampAddImage
+ * @property {HTMLInputElement} editorFreeHighlightThickness
+ * @property {HTMLButtonElement} editorHighlightShowAll
+ */
+
 class AnnotationEditorParams {
   /**
    * @param {AnnotationEditorParamsOptions} options
@@ -25,6 +39,9 @@ class AnnotationEditorParams {
     this.#bindListeners(options);
   }
 
+  /**
+   * @param {AnnotationEditorParamsOptions} options
+   */
   #bindListeners({
     editorFreeTextFontSize,
     editorFreeTextColor,

web/app.js

@@ -13,6 +13,12 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./interfaces.js").IL10n} IL10n */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/api.js").PDFDocumentProxy} PDFDocumentProxy */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/api.js").PDFDocumentLoadingTask} PDFDocumentLoadingTask */
+
 import {
   animationStarted,
   apiPageLayoutToViewerModes,
@@ -96,7 +102,9 @@ const PDFViewerApplication = {
     settled: false,
   },
   appConfig: null,
+  /** @type {PDFDocumentProxy} */
   pdfDocument: null,
+  /** @type {PDFDocumentLoadingTask} */
   pdfLoadingTask: null,
   printService: null,
   /** @type {PDFViewer} */

web/base_tree_viewer.js

@@ -43,14 +43,14 @@ class BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   _dispatchEvent(count) {
     throw new Error("Not implemented: _dispatchEvent");
   }
 
   /**
-   * @private
+   * @protected
    */
   _bindLink(element, params) {
     throw new Error("Not implemented: _bindLink");
@@ -71,7 +71,9 @@ class BaseTreeViewer {
   /**
    * Prepend a button before a tree item which allows the user to collapse or
    * expand all tree items at that level; see `_toggleTreeItem`.
-   * @private
+   * @param {HTMLDivElement} div
+   * @param {boolean|object} [hidden]
+   * @protected
    */
   _addToggleButton(div, hidden = false) {
     const toggler = document.createElement("div");

web/external_services.js

@@ -13,6 +13,8 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./interfaces.js").IL10n} IL10n */
+
 class BaseExternalServices {
   constructor() {
     if (this.constructor === BaseExternalServices) {
@@ -28,6 +30,9 @@ class BaseExternalServices {
 
   reportTelemetry(data) {}
 
+  /**
+   * @returns {Promise<IL10n>}
+   */
   async createL10n() {
     throw new Error("Not implemented: createL10n");
   }

web/grab_to_pan.js

@@ -17,10 +17,15 @@
 // Class name of element which can be grabbed.
 const CSS_CLASS_GRAB = "grab-to-pan-grab";
 
+/**
+ * @typedef {Object} GrabToPanOptions
+ * @property {HTMLElement} element
+ */
+
 class GrabToPan {
   /**
    * Construct a GrabToPan instance for a given HTML element.
-   * @param {Element} options.element
+   * @param {GrabToPanOptions} options
    */
   constructor({ element }) {
     this.element = element;

web/password_prompt.js

@@ -13,6 +13,8 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./overlay_manager.js").OverlayManager} OverlayManager */
+
 import { PasswordResponses } from "pdfjs-lib";
 
 /**

web/pdf_attachment_viewer.js

@@ -13,6 +13,10 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+// eslint-disable-next-line max-len
+/** @typedef {import("./download_manager.js").DownloadManager} DownloadManager */
+
 import { BaseTreeViewer } from "./base_tree_viewer.js";
 import { getFilenameFromUrl } from "pdfjs-lib";
 import { waitOnEventOrTimeout } from "./event_utils.js";
@@ -27,6 +31,7 @@ import { waitOnEventOrTimeout } from "./event_utils.js";
 /**
  * @typedef {Object} PDFAttachmentViewerRenderParameters
  * @property {Object|null} attachments - A lookup table of attachment objects.
+ * @property {boolean} [keepRenderedCapability]
  */
 
 class PDFAttachmentViewer extends BaseTreeViewer {
@@ -56,7 +61,7 @@ class PDFAttachmentViewer extends BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   async _dispatchEvent(attachmentsCount) {
     this._renderedCapability.resolve();
@@ -87,7 +92,7 @@ class PDFAttachmentViewer extends BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   _bindLink(element, { content, filename }) {
     element.onclick = () => {

web/pdf_cursor_tools.js

@@ -13,6 +13,8 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+
 import { AnnotationEditorType, shadow } from "pdfjs-lib";
 import { CursorTool, PresentationModeState } from "./ui_utils.js";
 import { GrabToPan } from "./grab_to_pan.js";

web/pdf_document_properties.js

@@ -13,6 +13,12 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+/** @typedef {import("./interfaces.js").IL10n} IL10n */
+/** @typedef {import("./overlay_manager.js").OverlayManager} OverlayManager */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/api.js").PDFDocumentProxy} PDFDocumentProxy */
+
 import { getPageSizeInches, isPortraitOrientation } from "./ui_utils.js";
 import { PDFDateString } from "pdfjs-lib";
 

web/pdf_layer_viewer.js

@@ -13,6 +13,12 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/optional_content_config.js").OptionalContentConfig} OptionalContentConfig */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/api.js").PDFDocumentProxy} PDFDocumentProxy */
+
 import { BaseTreeViewer } from "./base_tree_viewer.js";
 
 /**
@@ -25,7 +31,7 @@ import { BaseTreeViewer } from "./base_tree_viewer.js";
  * @typedef {Object} PDFLayerViewerRenderParameters
  * @property {OptionalContentConfig|null} optionalContentConfig - An
  *   {OptionalContentConfig} instance.
- * @property {PDFDocument} pdfDocument - A {PDFDocument} instance.
+ * @property {PDFDocumentProxy} pdfDocument - A {PDFDocument} instance.
  */
 
 class PDFLayerViewer extends BaseTreeViewer {
@@ -48,7 +54,7 @@ class PDFLayerViewer extends BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   _dispatchEvent(layersCount) {
     this.eventBus.dispatch("layersloaded", {
@@ -58,7 +64,7 @@ class PDFLayerViewer extends BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   _bindLink(element, { groupId, input }) {
     const setVisibility = () => {
@@ -97,7 +103,7 @@ class PDFLayerViewer extends BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   _addToggleButton(div, { name = null }) {
     super._addToggleButton(div, /* hidden = */ name === null);

web/pdf_outline_viewer.js

@@ -13,6 +13,13 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+// eslint-disable-next-line max-len
+/** @typedef {import("./download_manager.js").DownloadManager} DownloadManager */
+/** @typedef {import("./interfaces.js").IPDFLinkService} IPDFLinkService */
+// eslint-disable-next-line max-len
+/** @typedef {import("../src/display/api.js").PDFDocumentProxy} PDFDocumentProxy */
+
 import { BaseTreeViewer } from "./base_tree_viewer.js";
 import { SidebarView } from "./ui_utils.js";
 
@@ -27,7 +34,7 @@ import { SidebarView } from "./ui_utils.js";
 /**
  * @typedef {Object} PDFOutlineViewerRenderParameters
  * @property {Array|null} outline - An array of outline objects.
- * @property {PDFDocument} pdfDocument - A {PDFDocument} instance.
+ * @property {PDFDocumentProxy} pdfDocument - A {PDFDocument} instance.
  */
 
 class PDFOutlineViewer extends BaseTreeViewer {
@@ -75,7 +82,7 @@ class PDFOutlineViewer extends BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   _dispatchEvent(outlineCount) {
     this._currentOutlineItemCapability = Promise.withResolvers();
@@ -98,7 +105,7 @@ class PDFOutlineViewer extends BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   _bindLink(
     element,
@@ -162,7 +169,7 @@ class PDFOutlineViewer extends BaseTreeViewer {
   }
 
   /**
-   * @private
+   * @protected
    */
   _addToggleButton(div, { count, items }) {
     let hidden = false;

web/pdf_presentation_mode.js

@@ -13,6 +13,9 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+/** @typedef {import("./pdf_viewer.js").PDFViewer} PDFViewer */
+
 import {
   normalizeWheelEventDelta,
   PresentationModeState,

web/pdf_print_service.js

@@ -13,6 +13,9 @@
  * limitations under the License.
  */
 
+// eslint-disable-next-line max-len
+/** @typedef {import("./interfaces.js").IPDFPrintServiceFactory} IPDFPrintServiceFactory */
+
 import {
   AnnotationMode,
   PixelsPerInch,

web/pdf_sidebar.js

@@ -13,6 +13,9 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+/** @typedef {import("./interfaces.js").IL10n} IL10n */
+
 import {
   docStyle,
   PresentationModeState,

web/secondary_toolbar.js

@@ -13,6 +13,8 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+
 import {
   CursorTool,
   ScrollMode,

web/toolbar.js

@@ -13,6 +13,8 @@
  * limitations under the License.
  */
 
+/** @typedef {import("./event_utils.js").EventBus} EventBus */
+
 import { AnnotationEditorType, ColorPicker, noContextMenu } from "pdfjs-lib";
 import {
   DEFAULT_SCALE,