[api-minor] Add support for toggling of Optional Content in the viewe…

…r (issue 12096)

*Besides, obviously, adding viewer support:* This patch attempts to improve the general API for Optional Content Groups slightly, by adding a couple of new methods for interacting with the (more complex) data structures of `OptionalContentConfig`-instances. (Thus allowing us to mark some of the data as "private", given that it probably shouldn't be manipulated directly.)

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.

Finally, note that the thumbnails are *purposely* always rendered with all Optional Content Groups at their default visibility state, since that seems the most useful and it's also consistent with other viewers.
To ensure that this works as intended, we'll thus disable the `PDFThumbnailView.setImage` functionality when the Optional Content Groups have been changed in the viewer. (This obviously means that we'll re-render thumbnails instead of using the rendered pages. However, this situation ought to be rare enough for this to not really be a problem.)

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=Ytterligare 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

@@ -27,7 +27,7 @@ class OptionalContentConfig {
     this.name = null;
     this.creator = null;
     this._order = null;
-    this.groups = new Map();
+    this._groups = new Map();
 
     if (data === null) {
       return;
@@ -36,34 +36,34 @@ class OptionalContentConfig {
     this.creator = data.creator;
     this._order = data.order;
     for (const group of data.groups) {
-      this.groups.set(
+      this._groups.set(
         group.id,
         new OptionalContentGroup(group.name, group.intent)
       );
     }
 
     if (data.baseState === "OFF") {
-      for (const group of this.groups) {
+      for (const group of this._groups) {
         group.visible = false;
       }
     }
 
     for (const on of data.on) {
-      this.groups.get(on).visible = true;
+      this._groups.get(on).visible = true;
     }
 
     for (const off of data.off) {
-      this.groups.get(off).visible = false;
+      this._groups.get(off).visible = false;
     }
   }
 
   isVisible(group) {
     if (group.type === "OCG") {
-      if (!this.groups.has(group.id)) {
+      if (!this._groups.has(group.id)) {
         warn(`Optional content group not found: ${group.id}`);
         return true;
       }
-      return this.groups.get(group.id).visible;
+      return this._groups.get(group.id).visible;
     } else if (group.type === "OCMD") {
       // Per the spec, the expression should be preferred if available. Until
       // we implement this, just fallback to using the group policy for now.
@@ -73,44 +73,44 @@ class OptionalContentConfig {
       if (!group.policy || group.policy === "AnyOn") {
         // Default
         for (const id of group.ids) {
-          if (!this.groups.has(id)) {
+          if (!this._groups.has(id)) {
             warn(`Optional content group not found: ${id}`);
             return true;
           }
-          if (this.groups.get(id).visible) {
+          if (this._groups.get(id).visible) {
             return true;
           }
         }
         return false;
       } else if (group.policy === "AllOn") {
         for (const id of group.ids) {
-          if (!this.groups.has(id)) {
+          if (!this._groups.has(id)) {
             warn(`Optional content group not found: ${id}`);
             return true;
           }
-          if (!this.groups.get(id).visible) {
+          if (!this._groups.get(id).visible) {
             return false;
           }
         }
         return true;
       } else if (group.policy === "AnyOff") {
         for (const id of group.ids) {
-          if (!this.groups.has(id)) {
+          if (!this._groups.has(id)) {
             warn(`Optional content group not found: ${id}`);
             return true;
           }
-          if (!this.groups.get(id).visible) {
+          if (!this._groups.get(id).visible) {
             return true;
           }
         }
         return false;
       } else if (group.policy === "AllOff") {
         for (const id of group.ids) {
-          if (!this.groups.has(id)) {
+          if (!this._groups.has(id)) {
             warn(`Optional content group not found: ${id}`);
             return true;
           }
-          if (this.groups.get(id).visible) {
+          if (this._groups.get(id).visible) {
             return false;
           }
         }
@@ -122,6 +122,35 @@ class OptionalContentConfig {
     warn(`Unknown group type ${group.type}.`);
     return true;
   }
+
+  setVisibility(id, visible = true) {
+    if (!this._groups.has(id)) {
+      warn(`Optional content group not found: ${id}`);
+      return;
+    }
+    this._groups.get(id).visible = !!visible;
+  }
+
+  getOrder() {
+    if (!this._groups.size) {
+      return null;
+    }
+    if (this._order) {
+      return this._order.slice();
+    }
+    return Array.from(this._groups.keys());
+  }
+
+  getGroups() {
+    if (!this._groups.size) {
+      return null;
+    }
+    return Object.fromEntries(this._groups);
+  }
+
+  getGroup(id) {
+    return this._groups.get(id) || null;
+  }
 }
 
 export { OptionalContentConfig };

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";
@@ -209,6 +210,8 @@ const PDFViewerApplication = {
   pdfOutlineViewer: null,
   /** @type {PDFAttachmentViewer} */
   pdfAttachmentViewer: null,
+  /** @type {PDFLayerViewer} */
+  pdfLayerViewer: null,
   /** @type {PDFCursorTools} */
   pdfCursorTools: null,
   /** @type {ViewHistory} */
@@ -445,6 +448,7 @@ const PDFViewerApplication = {
 
     this.pdfThumbnailViewer = new PDFThumbnailViewer({
       container: appConfig.sidebar.thumbnailView,
+      eventBus,
       renderingQueue: pdfRenderingQueue,
       linkService: pdfLinkService,
       l10n: this.l10n,
@@ -509,6 +513,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,
@@ -737,6 +747,7 @@ const PDFViewerApplication = {
     this.pdfSidebar.reset();
     this.pdfOutlineViewer.reset();
     this.pdfAttachmentViewer.reset();
+    this.pdfLayerViewer.reset();
 
     if (this.pdfHistory) {
       this.pdfHistory.reset();
@@ -1318,6 +1329,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.optionalContentConfigPromise.then(optionalContentConfig => {
+        this.pdfLayerViewer.render({ optionalContentConfig, pdfDocument });
+      });
     });
 
     this._initializePageLabels(pdfDocument);
@@ -1667,12 +1683,15 @@ const PDFViewerApplication = {
     const pagesOverview = this.pdfViewer.getPagesOverview();
     const printContainer = this.appConfig.printContainer;
     const printResolution = AppOptions.get("printResolution");
+    const optionalContentConfigPromise = this.pdfViewer
+      .optionalContentConfigPromise;
 
     const printService = PDFPrintServiceFactory.instance.createPrintService(
       this.pdfDocument,
       pagesOverview,
       printContainer,
       printResolution,
+      optionalContentConfigPromise,
       this.l10n
     );
     this.printService = printService;
@@ -1748,6 +1767,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);
@@ -1827,6 +1847,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);
@@ -2169,12 +2190,15 @@ function webViewerPageMode({ mode }) {
       view = SidebarView.THUMBS;
       break;
     case "bookmarks":
-    case "outline":
+    case "outline": // non-standard
       view = SidebarView.OUTLINE;
       break;
-    case "attachments":
+    case "attachments": // non-standard
       view = SidebarView.ATTACHMENTS;
       break;
+    case "layers": // non-standard
+      view = SidebarView.LAYERS;
+      break;
     case "none":
       view = SidebarView.NONE;
       break;
@@ -2420,6 +2444,9 @@ function webViewerRotateCw() {
 function webViewerRotateCcw() {
   PDFViewerApplication.rotatePages(-90);
 }
+function webViewerOptionalContentConfig(evt) {
+  PDFViewerApplication.pdfViewer.optionalContentConfigPromise = evt.promise;
+}
 function webViewerSwitchScrollMode(evt) {
   PDFViewerApplication.pdfViewer.scrollMode = evt.mode;
 }
@@ -3013,7 +3040,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

@@ -439,6 +439,7 @@ class BaseViewer {
     const firstPagePromise = pdfDocument.getPage(1);
 
     const annotationStorage = pdfDocument.annotationStorage;
+    const optionalContentConfigPromise = pdfDocument.getOptionalContentConfig();
 
     this._pagesCapability.promise.then(() => {
       this.eventBus.dispatch("pagesloaded", {
@@ -474,6 +475,7 @@ class BaseViewer {
     firstPagePromise
       .then(firstPdfPage => {
         this._firstPageCapability.resolve(firstPdfPage);
+        this._optionalContentConfigPromise = optionalContentConfigPromise;
 
         const scale = this.currentScale;
         const viewport = firstPdfPage.getViewport({ scale: scale * CSS_UNITS });
@@ -486,8 +488,9 @@ class BaseViewer {
             eventBus: this.eventBus,
             id: pageNum,
             scale,
-            annotationStorage,
             defaultViewport: viewport.clone(),
+            annotationStorage,
+            optionalContentConfigPromise,
             renderingQueue: this.renderingQueue,
             textLayerFactory,
             textLayerMode: this.textLayerMode,
@@ -605,6 +608,7 @@ class BaseViewer {
     this._buffer = new PDFPageViewBuffer(DEFAULT_CACHE_SIZE);
     this._location = null;
     this._pagesRotation = 0;
+    this._optionalContentConfigPromise = null;
     this._pagesRequests = new WeakMap();
     this._firstPageCapability = createPromiseCapability();
     this._onePageRenderedCapability = createPromiseCapability();
@@ -1222,6 +1226,50 @@ class BaseViewer {
     });
   }
 
+  /**
+   * @type {Promise<OptionalContentConfig | null>}
+   */
+  get optionalContentConfigPromise() {
+    if (!this.pdfDocument) {
+      return Promise.resolve(null);
+    }
+    if (!this._optionalContentConfigPromise) {
+      // Prevent issues if the getter is accessed *before* the `onePageRendered`
+      // promise has resolved; won't (normally) happen in the default viewer.
+      return this.pdfDocument.getOptionalContentConfig();
+    }
+    return this._optionalContentConfigPromise;
+  }
+
+  /**
+   * @param {Promise<OptionalContentConfig>} promise - A promise that is
+   *   resolved with an {@link OptionalContentConfig} instance.
+   */
+  set optionalContentConfigPromise(promise) {
+    if (!(promise instanceof Promise)) {
+      throw new Error(`Invalid optionalContentConfigPromise: ${promise}`);
+    }
+    if (!this.pdfDocument) {
+      return;
+    }
+    if (!this._optionalContentConfigPromise) {
+      // Ignore the setter *before* the `onePageRendered` promise has resolved,
+      // since it'll be overwritten anyway; won't happen in the default viewer.
+      return;
+    }
+    this._optionalContentConfigPromise = promise;
+
+    for (const pageView of this._pages) {
+      pageView.update(pageView.scale, pageView.rotation, promise);
+    }
+    this.update();
+
+    this.eventBus.dispatch("optionalcontentconfigchanged", {
+      source: this,
+      promise,
+    });
+  }
+
   /**
    * @type {number} One of the values in {ScrollMode}.
    */