From 0d933be237662c42e31d83fce857da32b85d8e6a Mon Sep 17 00:00:00 2001
From: Jonas Jenwald <jonas.jenwald@gmail.com>
Date: Thu, 6 Aug 2020 20:59:46 +0200
Subject: [PATCH] Include the `/Order` array, if available, when parsing the
 Optional Content configuration

The `/Order` array is used to improve the display of Optional Content groups in PDF viewers, and it allows a PDF document to e.g. specify that Optional Content groups should be displayed as a (collapsable) tree-structure rather than as just a list.

Note that not all available Optional Content groups must be present in the `/Order` array, and PDF viewers will often (by default) hide those toggles in the UI.
To allow us to improve the UX around toggling of Optional Content groups, in the default viewer, these hidden-by-default groups are thus appended to the parsed `/Order` array under a *custom* nesting level (with `name == null`).

Finally, the patch also slightly tweaks the `OptionalContentConfig` related JSDoc-comments in the API.
---
 src/core/obj.js                        | 63 ++++++++++++++++++++++++++
 src/display/api.js                     | 13 +++---
 src/display/optional_content_config.js |  2 +
 3 files changed, 71 insertions(+), 7 deletions(-)

diff --git a/src/core/obj.js b/src/core/obj.js
index 9139a7bf610400..d110094224d7cc 100644
--- a/src/core/obj.js
+++ b/src/core/obj.js
@@ -315,6 +315,67 @@ class Catalog {
       return onParsed;
     }
 
+    function parseOrder(refs, nestedLevels = 0) {
+      if (!Array.isArray(refs)) {
+        return null;
+      }
+      const order = [];
+
+      for (const value of refs) {
+        if (isRef(value) && contentGroupRefs.includes(value)) {
+          parsedOrderRefs.put(value); // Handle "hidden" groups, see below.
+
+          order.push(value.toString());
+          continue;
+        }
+        // Handle nested /Order arrays (see e.g. issue 9462 and bug 1240641).
+        const nestedOrder = parseNestedOrder(value, nestedLevels);
+        if (nestedOrder) {
+          order.push(nestedOrder);
+        }
+      }
+
+      if (nestedLevels > 0) {
+        return order;
+      }
+      const hiddenGroups = [];
+      for (const groupRef of contentGroupRefs) {
+        if (parsedOrderRefs.has(groupRef)) {
+          continue;
+        }
+        hiddenGroups.push(groupRef.toString());
+      }
+      if (hiddenGroups.length) {
+        order.push({ name: null, order: hiddenGroups });
+      }
+
+      return order;
+    }
+
+    function parseNestedOrder(ref, nestedLevels) {
+      if (++nestedLevels > MAX_NESTED_LEVELS) {
+        warn("parseNestedOrder - reached MAX_NESTED_LEVELS.");
+        return null;
+      }
+      const value = xref.fetchIfRef(ref);
+      if (!Array.isArray(value)) {
+        return null;
+      }
+      const nestedName = xref.fetchIfRef(value[0]);
+      if (typeof nestedName !== "string") {
+        return null;
+      }
+      const nestedOrder = parseOrder(value.slice(1), nestedLevels);
+      if (!nestedOrder || !nestedOrder.length) {
+        return null;
+      }
+      return { name: stringToPDFString(nestedName), order: nestedOrder };
+    }
+
+    const xref = this.xref,
+      parsedOrderRefs = new RefSet(),
+      MAX_NESTED_LEVELS = 10;
+
     return {
       name: isString(config.get("Name"))
         ? stringToPDFString(config.get("Name"))
@@ -327,6 +388,8 @@ class Catalog {
         : null,
       on: parseOnOff(config.get("ON")),
       off: parseOnOff(config.get("OFF")),
+      order: parseOrder(config.get("Order")),
+      groups: null,
     };
   }
 
diff --git a/src/display/api.js b/src/display/api.js
index 571c2449482a36..6ee04e733b41f8 100644
--- a/src/display/api.js
+++ b/src/display/api.js
@@ -773,9 +773,9 @@ class PDFDocumentProxy {
   }
 
   /**
-   * @returns {Promise<OptionalContentConfig | null>} A promise that is resolved
-   *   with an {@link OptionalContentConfig} that has all the optional content
-   *   groups, or `null` if the document does not have any.
+   * @returns {Promise<OptionalContentConfig>} A promise that is resolved with
+   *   an {@link OptionalContentConfig} that contains all the optional content
+   *   groups (assuming that the document has any).
    */
   getOptionalContentConfig() {
     return this._transport.getOptionalContentConfig();
@@ -957,10 +957,9 @@ class PDFDocumentProxy {
  * @property {AnnotationStorage} [annotationStorage] - Storage for annotation
  *   data in forms.
  * @property {Promise<OptionalContentConfig>} [optionalContentConfigPromise] -
- *   A promise that should resolve with an {@link OptionalContentConfig}
- *   created from `PDFDocumentProxy.getOptionalContentConfig`. If `null`,
- *   the configuration will be fetched automatically with the default visibility
- *   states set.
+ *   A promise that resolves with an {@link OptionalContentConfig} created from
+ *   `PDFDocumentProxy.getOptionalContentConfig`. If `null`, the configuration
+ *   will be fetched automatically with the default visibility states set.
  */
 
 /**
diff --git a/src/display/optional_content_config.js b/src/display/optional_content_config.js
index 16308623d12b13..5e14c1284b5924 100644
--- a/src/display/optional_content_config.js
+++ b/src/display/optional_content_config.js
@@ -26,6 +26,7 @@ class OptionalContentConfig {
   constructor(data) {
     this.name = null;
     this.creator = null;
+    this._order = null;
     this.groups = new Map();
 
     if (data === null) {
@@ -33,6 +34,7 @@ class OptionalContentConfig {
     }
     this.name = data.name;
     this.creator = data.creator;
+    this._order = data.order;
     for (const group of data.groups) {
       this.groups.set(
         group.id,