Add support for toggling of Optional Content in the viewer (issue 12096)

By utilizing not just the "raw" Optional Content Groups, but the data from the `/Order` array when available, we can thus display the Layers in a proper tree-structure with collapsible headings for PDF documents that utilizes that feature.

Note that it's possible to reset all Optional Content Groups to their default visibility state, simply by double-clicking on the Layers-button in the sidebar.
(Currently that's indicated in the Layers-button tooltip, which is obviously easy to overlook, however it's probably the best we can do for now without adding more buttons, or even a dropdown-toolbar, to the sidebar.)

Also, the current Layers-button icons are a little rough around the edges, quite literally, but given that the viewer will soon have its UI modernized anyway they hopefully suffice in the meantime.

To give users *full* control of the visibility of the various Optional Content Groups, even those which according to the `/Order` array should not (by default) be toggleable in the UI, this patch will place those under a *custom* heading which:
 - Is collapsed by default, and placed at the bottom of the Layers-tree, to be a bit less obtrusive.
 - Uses a slightly different formatting, compared to the "regular" headings.
 - Is localizable.

l10n/en-US/viewer.properties

@@ -137,17 +137,20 @@ print_progress_close=Cancel
 # (the _label strings are alt text for the buttons, the .title strings are
 # tooltips)
 toggle_sidebar.title=Toggle Sidebar
-toggle_sidebar_notification.title=Toggle Sidebar (document contains outline/attachments)
+toggle_sidebar_notification2.title=Toggle Sidebar (document contains outline/attachments/layers)
 toggle_sidebar_label=Toggle Sidebar
 document_outline.title=Show Document Outline (double-click to expand/collapse all items)
 document_outline_label=Document Outline
 attachments.title=Show Attachments
 attachments_label=Attachments
+layers.title=Show Layers (double-click to reset all layers to the default state)
+layers_label=Layers
 thumbs.title=Show Thumbnails
 thumbs_label=Thumbnails
 findbar.title=Find in Document
 findbar_label=Find
 
+additional_layers=Additional Layers
 # LOCALIZATION NOTE (page_canvas): "{{page}}" will be replaced by the page number.
 page_canvas=Page {{page}}
 # Thumbnails panel item (tooltip and alt text for images)

l10n/sv-SE/viewer.properties

@@ -137,17 +137,20 @@ print_progress_close=Avbryt
 # (the _label strings are alt text for the buttons, the .title strings are
 # tooltips)
 toggle_sidebar.title=Visa/dölj sidofält
-toggle_sidebar_notification.title=Visa/dölj sidofält (dokument innehåller översikt/bilagor)
+toggle_sidebar_notification2.title=Visa/dölj sidofält (dokument innehåller översikt/bilagor/lager)
 toggle_sidebar_label=Visa/dölj sidofält
 document_outline.title=Visa dokumentdisposition (dubbelklicka för att expandera/komprimera alla objekt)
 document_outline_label=Dokumentöversikt
 attachments.title=Visa Bilagor
 attachments_label=Bilagor
+layers.title=Visa lager (dubbelklicka för att återställa alla lager till ursrungligt läge)
+layers_label=Lager
 thumbs.title=Visa miniatyrer
 thumbs_label=Miniatyrer
 findbar.title=Sök i dokument
 findbar_label=Sök
 
+additional_layers=Ytterliggare lager
 # LOCALIZATION NOTE (page_canvas): "{{page}}" will be replaced by the page number.
 page_canvas=Sida {{page}}
 # Thumbnails panel item (tooltip and alt text for images)

src/display/optional_content_config.js

@@ -122,6 +122,28 @@ class OptionalContentConfig {
     warn(`Unknown group type ${group.type}.`);
     return true;
   }
+
+  toggleVisibility(id, visible = true) {
+    if (!this.groups.has(id)) {
+      warn(`Optional content group not found: ${id}`);
+      return;
+    }
+    this.groups.get(id).visible = !!visible;
+  }
+
+  getGroups() {
+    if (!this.groups.size) {
+      return null;
+    }
+    if (this.order) {
+      return this.order.slice();
+    }
+    return Array.from(this.groups.keys());
+  }
+
+  getGroup(id) {
+    return this.groups.get(id);
+  }
 }
 
 export { OptionalContentConfig };

src/pdf.js

@@ -52,6 +52,7 @@ import {
 import { AnnotationLayer } from "./display/annotation_layer.js";
 import { apiCompatibilityParams } from "./display/api_compatibility.js";
 import { GlobalWorkerOptions } from "./display/worker_options.js";
+import { OptionalContentConfig } from "./display/optional_content_config.js";
 import { renderTextLayer } from "./display/text_layer.js";
 import { SVGGraphics } from "./display/svg.js";
 
@@ -160,6 +161,8 @@ export {
   apiCompatibilityParams,
   // From "./display/worker_options.js":
   GlobalWorkerOptions,
+  // From "./display/optional_content_config.js":
+  OptionalContentConfig,
   // From "./display/text_layer.js":
   renderTextLayer,
   // From "./display/svg.js":

web/app.js

@@ -64,6 +64,7 @@ import { PDFDocumentProperties } from "./pdf_document_properties.js";
 import { PDFFindBar } from "./pdf_find_bar.js";
 import { PDFFindController } from "./pdf_find_controller.js";
 import { PDFHistory } from "./pdf_history.js";
+import { PDFLayerViewer } from "./pdf_layer_viewer.js";
 import { PDFLinkService } from "./pdf_link_service.js";
 import { PDFOutlineViewer } from "./pdf_outline_viewer.js";
 import { PDFPresentationMode } from "./pdf_presentation_mode.js";
@@ -208,6 +209,8 @@ const PDFViewerApplication = {
   pdfOutlineViewer: null,
   /** @type {PDFAttachmentViewer} */
   pdfAttachmentViewer: null,
+  /** @type {PDFLayerViewer} */
+  pdfLayerViewer: null,
   /** @type {PDFCursorTools} */
   pdfCursorTools: null,
   /** @type {ViewHistory} */
@@ -508,6 +511,12 @@ const PDFViewerApplication = {
       downloadManager,
     });
 
+    this.pdfLayerViewer = new PDFLayerViewer({
+      container: appConfig.sidebar.layersView,
+      eventBus,
+      l10n: this.l10n,
+    });
+
     this.pdfSidebar = new PDFSidebar({
       elements: appConfig.sidebar,
       pdfViewer: this.pdfViewer,
@@ -735,6 +744,7 @@ const PDFViewerApplication = {
     this.pdfSidebar.reset();
     this.pdfOutlineViewer.reset();
     this.pdfAttachmentViewer.reset();
+    this.pdfLayerViewer.reset();
 
     if (this.pdfHistory) {
       this.pdfHistory.reset();
@@ -1269,6 +1279,11 @@ const PDFViewerApplication = {
       pdfDocument.getAttachments().then(attachments => {
         this.pdfAttachmentViewer.render({ attachments });
       });
+      // Ensure that the layers accurately reflects the current state in the
+      // viewer itself, rather than the default state provided by the API.
+      pdfViewer.getOptionalContentConfig().then(optionalContentConfig => {
+        this.pdfLayerViewer.render({ optionalContentConfig, pdfDocument });
+      });
     });
 
     this._initializePageLabels(pdfDocument);
@@ -1610,12 +1625,14 @@ const PDFViewerApplication = {
     const pagesOverview = this.pdfViewer.getPagesOverview();
     const printContainer = this.appConfig.printContainer;
     const printResolution = AppOptions.get("printResolution");
+    const optionalContentConfigPromise = this.pdfViewer.getOptionalContentConfig();
 
     const printService = PDFPrintServiceFactory.instance.createPrintService(
       this.pdfDocument,
       pagesOverview,
       printContainer,
       printResolution,
+      optionalContentConfigPromise,
       this.l10n
     );
     this.printService = printService;
@@ -1686,6 +1703,7 @@ const PDFViewerApplication = {
     eventBus._on("scalechanged", webViewerScaleChanged);
     eventBus._on("rotatecw", webViewerRotateCw);
     eventBus._on("rotateccw", webViewerRotateCcw);
+    eventBus._on("optionalcontentconfig", webViewerOptionalContentConfig);
     eventBus._on("switchscrollmode", webViewerSwitchScrollMode);
     eventBus._on("scrollmodechanged", webViewerScrollModeChanged);
     eventBus._on("switchspreadmode", webViewerSwitchSpreadMode);
@@ -1761,6 +1779,7 @@ const PDFViewerApplication = {
     eventBus._off("scalechanged", webViewerScaleChanged);
     eventBus._off("rotatecw", webViewerRotateCw);
     eventBus._off("rotateccw", webViewerRotateCcw);
+    eventBus._off("optionalcontentconfig", webViewerOptionalContentConfig);
     eventBus._off("switchscrollmode", webViewerSwitchScrollMode);
     eventBus._off("scrollmodechanged", webViewerScrollModeChanged);
     eventBus._off("switchspreadmode", webViewerSwitchSpreadMode);
@@ -2322,6 +2341,10 @@ function webViewerRotateCw() {
 function webViewerRotateCcw() {
   PDFViewerApplication.rotatePages(-90);
 }
+function webViewerOptionalContentConfig(evt) {
+  PDFViewerApplication.pdfViewer.optionalContentConfig =
+    evt.optionalContentConfig;
+}
 function webViewerSwitchScrollMode(evt) {
   PDFViewerApplication.pdfViewer.scrollMode = evt.mode;
 }
@@ -2868,7 +2891,7 @@ function apiPageModeToSidebarView(mode) {
     case "UseAttachments":
       return SidebarView.ATTACHMENTS;
     case "UseOC":
-    // Not implemented, since we don't support Optional Content Groups yet.
+      return SidebarView.LAYERS;
   }
   return SidebarView.NONE; // Default value.
 }

web/base_viewer.js

@@ -13,6 +13,7 @@
  * limitations under the License.
  */
 
+import { createPromiseCapability, OptionalContentConfig } from "pdfjs-lib";
 import {
   CSS_UNITS,
   DEFAULT_SCALE,
@@ -38,7 +39,6 @@ import {
 } from "./ui_utils.js";
 import { PDFRenderingQueue, RenderingStates } from "./pdf_rendering_queue.js";
 import { AnnotationLayerBuilder } from "./annotation_layer_builder.js";
-import { createPromiseCapability } from "pdfjs-lib";
 import { PDFPageView } from "./pdf_page_view.js";
 import { SimpleLinkService } from "./pdf_link_service.js";
 import { TextLayerBuilder } from "./text_layer_builder.js";
@@ -436,6 +436,11 @@ class BaseViewer {
     const firstPagePromise = pdfDocument.getPage(1);
 
     const annotationStorage = pdfDocument.annotationStorage;
+    const optionalContentConfigPromise = pdfDocument
+      .getOptionalContentConfig()
+      .then(optionalContentConfig => {
+        return (this._optionalContentConfig = optionalContentConfig);
+      });
 
     this._pagesCapability.promise.then(() => {
       this.eventBus.dispatch("pagesloaded", {
@@ -483,8 +488,9 @@ class BaseViewer {
             eventBus: this.eventBus,
             id: pageNum,
             scale,
-            annotationStorage,
             defaultViewport: viewport.clone(),
+            annotationStorage,
+            optionalContentConfigPromise,
             renderingQueue: this.renderingQueue,
             textLayerFactory,
             textLayerMode: this.textLayerMode,
@@ -602,6 +608,7 @@ class BaseViewer {
     this._buffer = new PDFPageViewBuffer(DEFAULT_CACHE_SIZE);
     this._location = null;
     this._pagesRotation = 0;
+    this._optionalContentConfig = null;
     this._pagesRequests = new WeakMap();
     this._firstPageCapability = createPromiseCapability();
     this._onePageRenderedCapability = createPromiseCapability();
@@ -1219,6 +1226,53 @@ class BaseViewer {
     });
   }
 
+  /**
+   * @type {OptionalContentConfig}
+   */
+  get optionalContentConfig() {
+    return this._optionalContentConfig;
+  }
+
+  /**
+   * @param {OptionalContentConfig} val - An {OptionalContentConfig} instance.
+   */
+  set optionalContentConfig(val) {
+    if (!(val instanceof OptionalContentConfig)) {
+      throw new Error(`Invalid optionalContentConfig: ${val}`);
+    }
+    if (!this.pdfDocument) {
+      return;
+    }
+    if (!this._optionalContentConfig) {
+      // Ignore the setter *before* the `onePageRendered` promise has resolved,
+      // since it'd be overwritten anyway; won't happen in the default viewer.
+      return;
+    }
+    this._optionalContentConfig = val;
+
+    const optionalContentConfigPromise = Promise.resolve(val);
+    for (const pageView of this._pages) {
+      pageView.update(
+        pageView.scale,
+        pageView.rotation,
+        optionalContentConfigPromise
+      );
+    }
+    this.update();
+  }
+
+  async getOptionalContentConfig() {
+    if (!this.pdfDocument) {
+      throw new Error("getOptionalContentConfig - setDocument was not called.");
+    }
+    if (!this._optionalContentConfig) {
+      // Prevent issues if the method is called *before* the `onePageRendered`
+      // promise has resolved; won't happen in the default viewer.
+      return this.pdfDocument.getOptionalContentConfig();
+    }
+    return this._optionalContentConfig;
+  }
+
   /**
    * @type {number} One of the values in {ScrollMode}.
    */

web/firefox_print_service.js

@@ -23,7 +23,8 @@ function composePage(
   pageNumber,
   size,
   printContainer,
-  printResolution
+  printResolution,
+  optionalContentConfigPromise
 ) {
   const canvas = document.createElement("canvas");
 
@@ -58,6 +59,7 @@ function composePage(
           viewport: pdfPage.getViewport({ scale: 1, rotation: size.rotation }),
           intent: "print",
           annotationStorage: pdfDocument.annotationStorage,
+          optionalContentConfigPromise,
         };
         return pdfPage.render(renderContext).promise;
       })
@@ -84,12 +86,15 @@ function FirefoxPrintService(
   pdfDocument,
   pagesOverview,
   printContainer,
-  printResolution
+  printResolution,
+  optionalContentConfigPromise = null
 ) {
   this.pdfDocument = pdfDocument;
   this.pagesOverview = pagesOverview;
   this.printContainer = printContainer;
   this._printResolution = printResolution || 150;
+  this._optionalContentConfigPromise =
+    optionalContentConfigPromise || pdfDocument.getOptionalContentConfig();
 }
 
 FirefoxPrintService.prototype = {
@@ -99,6 +104,7 @@ FirefoxPrintService.prototype = {
       pagesOverview,
       printContainer,
       _printResolution,
+      _optionalContentConfigPromise,
     } = this;
 
     const body = document.querySelector("body");
@@ -110,7 +116,8 @@ FirefoxPrintService.prototype = {
         /* pageNumber = */ i + 1,
         pagesOverview[i],
         printContainer,
-        _printResolution
+        _printResolution,
+        _optionalContentConfigPromise
       );
     }
   },
@@ -135,13 +142,15 @@ PDFPrintServiceFactory.instance = {
     pdfDocument,
     pagesOverview,
     printContainer,
-    printResolution
+    printResolution,
+    optionalContentConfigPromise
   ) {
     return new FirefoxPrintService(
       pdfDocument,
       pagesOverview,
       printContainer,
-      printResolution
+      printResolution,
+      optionalContentConfigPromise
     );
   },
 };