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 an `OptionalContentConfig` related JSDoc-comment in the API.

src/core/obj.js

@@ -355,6 +355,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"))
@@ -367,6 +428,8 @@ class Catalog {
         : null,
       on: parseOnOff(config.get("ON")),
       off: parseOnOff(config.get("OFF")),
+      order: parseOrder(config.get("Order")),
+      groups: null,
     };
   }
 

src/display/api.js

@@ -778,9 +778,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();

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,