feat(table-of-contents): cached data

.gitignore

@@ -34,6 +34,7 @@ node_modules
 
 # build
 dist
+build
 
 # Documentation
 docs/api/

demo/28-table-of-contents.ts

@@ -1,7 +1,7 @@
 // Table of contents
 
 import * as fs from "fs";
-import { File, HeadingLevel, Packer, Paragraph, StyleLevel, TableOfContents } from "docx";
+import { Bookmark, File, HeadingLevel, Packer, Paragraph, StyleLevel, TableOfContents } from "docx";
 
 // WordprocessingML docs for TableOfContents can be found here:
 // http://officeopenxml.com/WPtableOfContents.php
@@ -30,15 +30,46 @@ const doc = new File({
     sections: [
         {
             children: [
-                new TableOfContents("Summary", {
-                    hyperlink: true,
-                    headingStyleRange: "1-5",
-                    stylesWithLevels: [new StyleLevel("MySpectacularStyle", 1)],
-                }),
+                new TableOfContents(
+                    "Summary",
+                    {
+                        hyperlink: true,
+                        headingStyleRange: "1-5",
+                        stylesWithLevels: [new StyleLevel("MySpectacularStyle", 1)],
+                    },
+                    [
+                        {
+                            title: "Header #1",
+                            level: 1,
+                            page: 1,
+                            href: "anchorForHeader1",
+                        },
+                        {
+                            title: "Header #2",
+                            level: 1,
+                            page: 2,
+                        },
+                        {
+                            title: "Header #2.1",
+                            level: 2,
+                        },
+                        {
+                            title: "My Spectacular Style #1",
+                            level: 1,
+                            page: 3,
+                        },
+                    ],
+                ),
                 new Paragraph({
                     text: "Header #1",
                     heading: HeadingLevel.HEADING_1,
                     pageBreakBefore: true,
+                    children: [
+                        new Bookmark({
+                            id: "anchorForHeader1",
+                            children: [],
+                        }),
+                    ],
                 }),
                 new Paragraph("I'm a little text very nicely written.'"),
                 new Paragraph({

demo/index.ts

@@ -22,31 +22,38 @@ const getFileNumber = (file: string): number => {
 
 const demoFiles = keys.filter((file) => !isNaN(getFileNumber(file))).sort((a, b) => getFileNumber(a) - getFileNumber(b));
 
-const answers = await inquirer.prompt<Answers>([
-    {
-        type: "list",
-        name: "type",
-        message: "Select demo from a list or via number",
-        choices: ["list", "number"],
-    },
-    {
-        type: "list",
-        name: "demoFile",
-        message: "What demo do you wish to run?",
-        choices: demoFiles,
-        filter: (input) => parseInt(input.split("-")[0], 10),
-        when: (a) => a.type === "list",
-    },
-    {
-        type: "number",
-        name: "demoNumber",
-        message: "What demo do you wish to run? (Enter a number)",
-        default: 1,
-        when: (a) => a.type === "number",
-    },
-]);
-
-const demoNumber = answers.demoNumber ?? answers.demoFile ?? 1;
+const firstArg = process.argv[2];
+const firstArgNumber = Number.parseInt(firstArg, 10);
+let demoNumber: number;
+if (firstArg && !isNaN(firstArgNumber)) {
+    demoNumber = firstArgNumber;
+} else {
+    const answers = await inquirer.prompt<Answers>([
+        {
+            type: "list",
+            name: "type",
+            message: "Select demo from a list or via number",
+            choices: ["list", "number"],
+        },
+        {
+            type: "list",
+            name: "demoFile",
+            message: "What demo do you wish to run?",
+            choices: demoFiles,
+            filter: (input) => parseInt(input.split("-")[0], 10),
+            when: (a) => a.type === "list",
+        },
+        {
+            type: "number",
+            name: "demoNumber",
+            message: "What demo do you wish to run? (Enter a number)",
+            default: 1,
+            when: (a) => a.type === "number",
+        },
+    ]);
+    demoNumber = answers.demoNumber ?? answers.demoFile ?? 1;
+}
+
 const files = fs.readdirSync(dir).filter((fn) => fn.startsWith(demoNumber.toString()));
 
 if (files.length === 0) {

docs/usage/table-of-contents.md

@@ -31,9 +31,9 @@ const doc = new Document({
                     heading: HeadingLevel.HEADING_1,
                     pageBreakBefore: true,
                 }),
-            ]
-        }
-    ]
+            ],
+        },
+    ],
 });
 ```
 
@@ -60,8 +60,52 @@ Here is the list of all options that you can use to generate your tables of cont
 | preserveNewLineInEntries        | boolean      | `\x`             | Preserves newline characters within table entries.                                                                                                                                                                                                                                                                                                                                                               |
 | hideTabAndPageNumbersInWebView  | boolean      | `\z`             | Hides tab leader and page numbers in web page view (§17.18.102).                                                                                                                                                                                                                                                                                                                                                 |
 
+## Cached entries
+
+If you already know what might be in the table, you can provide those entries to the constructor as well, and the table of contents will be populated with that data.
+
+```ts
+const doc = new Document({
+    features: {
+        updateFields: true,
+    },
+    sections: [
+        {
+            children: [
+                new TableOfContents(
+                    "Summary",
+                    {
+                        hyperlink: true,
+                        headingStyleRange: "1-5",
+                    },
+                    // Cached entries
+                    [
+                        {
+                            text: "Header #1",
+                            level: 1,
+                            page: 1,
+                            href: "anchorForHeader1",
+                        },
+                    ],
+                ),
+                new Paragraph({
+                    text: "Header #1",
+                    heading: HeadingLevel.HEADING_1,
+                    pageBreakBefore: true,
+                    children: [
+                        new Bookmark({
+                            id: "anchorForHeader1",
+                        }),
+                    ],
+                }),
+            ],
+        },
+    ],
+});
+```
+
 ## Examples
 
-[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/28-table-of-contents.ts ':include')
+[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/28-table-of-contents.ts ":include")
 
 _Source: https://github.com/dolanmiu/docx/blob/master/demo/28-table-of-contents.ts_