Version bump

build(deps-dev): bump @typescript-eslint/parser from 5.56.0 to 5.57.1

.cspell.json

@@ -4,34 +4,40 @@
     "version": "0.2",
     // language - current active spelling language
     "language": "en_US",
-    "dictionaries": ["en_US", "typescript", "softwareTerms", "fonts", "npm"],
+    "dictionaries": [
+        "en_US",
+        "typescript",
+        "softwareTerms",
+        "fonts",
+        "npm"
+    ],
     // words - list of words to be always considered correct
     "words": [
-        "Xmlable",
+        "Abjad",
+        "aiueo",
+        "ATLEAST",
+        "chosung",
+        "clippy",
+        "datas",
+        "docsify",
+        "dolan",
+        "falsey",
+        "Initializable",
+        "iroha",
+        "jsonify",
+        "jszip",
+        "NUMPAGES",
+        "odttf",
+        "ooxml",
+        "panose",
+        "rels",
+        "rsid",
         "twip",
         "twips",
-        "jsonify",
-        "falsey",
-        "aiueo",
-        "iroha",
-        "aiueo",
-        "iroha",
-        "chosung",
-        "Abjad",
-        "Initializable",
-        "rels",
-        "dolan",
-        "xmlify",
-        "Xmlifyed",
+        "Xmlable",
         "xmlified",
-        "datas",
-        "jszip",
-        "rsid",
-        "NUMPAGES",
-        "ATLEAST",
-        "ooxml",
-        "clippy",
-        "docsify"
+        "xmlify",
+        "Xmlifyed"
     ],
     "ignoreRegExpList": [
         "/\"w:.+\"/",
@@ -51,10 +57,15 @@
         "/<element name=\"[a-z]+\"/gi",
         "/<attribute name=\"[a-z]+\"/gi"
     ],
-    "ignorePaths": ["package.json", "docs/api"],
+    "ignorePaths": [
+        "package.json",
+        "docs/api"
+    ],
     "allowCompoundWords": true,
     // flagWords - list of words to be always considered incorrect
     // This is useful for offensive words and common spelling errors.
     // For example "hte" should be "the"
-    "flagWords": ["hte"]
+    "flagWords": [
+        "hte"
+    ]
 }

demo/73-comments.ts

@@ -32,6 +32,55 @@ const doc = new Document({
                     }),
                 ],
             },
+            {
+                id: 1,
+                author: "Bob Ross",
+                date: new Date(),
+                children: [
+                    new Paragraph({
+                        children: [
+                            new TextRun({
+                                text: "Some initial text content",
+                            }),
+                        ],
+                    }),
+                    new Paragraph({
+                        children: [
+                            new TextRun({
+                                text: "comment text content",
+                            }),
+                        ],
+                    }),
+                ],
+            },
+            {
+                id: 2,
+                author: "John Doe",
+                date: new Date(),
+                children: [
+                    new Paragraph({
+                        children: [
+                            new TextRun({
+                                text: "Hello World",
+                            }),
+                        ],
+                    }),
+                ],
+            },
+            {
+                id: 3,
+                author: "Beatriz",
+                date: new Date(),
+                children: [
+                    new Paragraph({
+                        children: [
+                            new TextRun({
+                                text: "Another reply",
+                            }),
+                        ],
+                    }),
+                ],
+            },
         ],
     },
     sections: [
@@ -53,6 +102,32 @@ const doc = new Document({
                         }),
                     ],
                 }),
+                new Paragraph({
+                    children: [
+                        new CommentRangeStart(1),
+                        new CommentRangeStart(2),
+                        new CommentRangeStart(3),
+                        new TextRun({
+                            text: "Some text which need commenting",
+                            bold: true,
+                        }),
+                        new CommentRangeEnd(1),
+                        new TextRun({
+                            children: [new CommentReference(1)],
+                            bold: true,
+                        }),
+                        new CommentRangeEnd(2),
+                        new TextRun({
+                            children: [new CommentReference(2)],
+                            bold: true,
+                        }),
+                        new CommentRangeEnd(3),
+                        new TextRun({
+                            children: [new CommentReference(3)],
+                            bold: true,
+                        }),
+                    ],
+                }),
             ],
         },
     ],

demo/88-template-document.ts

@@ -0,0 +1,31 @@
+// Patch a document with patches
+// Import from 'docx' rather than '../build' if you install from npm
+import * as fs from "fs";
+import { IPatch, patchDocument, PatchType, TextRun } from "../build";
+
+export const font = "Trebuchet MS";
+export const getPatches = (fields: { [key: string]: string }) => {
+    const patches: { [key: string]: IPatch } = {};
+
+    for (const field in fields) {
+        patches[field] = {
+            type: PatchType.PARAGRAPH,
+            children: [new TextRun({ text: fields[field], font })],
+        };
+    }
+
+    return patches;
+};
+
+const patches = getPatches({
+    name: "Mr",
+    table_heading_1: "John",
+    item_1: "Doe",
+    paragraph_replace: "Lorem ipsum paragraph",
+});
+
+patchDocument(fs.readFileSync("demo/assets/simple-template.docx"), {
+    patches,
+}).then((doc) => {
+    fs.writeFileSync("My Document.docx", doc);
+});

demo/89-template-document.ts

@@ -0,0 +1,29 @@
+// Patch a document with patches
+// Import from 'docx' rather than '../build' if you install from npm
+import * as fs from "fs";
+import { IPatch, patchDocument, PatchType, TextRun } from "../build";
+
+export const font = "Trebuchet MS";
+export const getPatches = (fields: { [key: string]: string }) => {
+    const patches: { [key: string]: IPatch } = {};
+
+    for (const field in fields) {
+        patches[field] = {
+            type: PatchType.PARAGRAPH,
+            children: [new TextRun({ text: fields[field], font })],
+        };
+    }
+
+    return patches;
+};
+
+const patches = getPatches({
+    salutation: "Mr.",
+    "first-name": "John",
+});
+
+patchDocument(fs.readFileSync("demo/assets/simple-template-3.docx"), {
+    patches,
+}).then((doc) => {
+    fs.writeFileSync("My Document.docx", doc);
+});

docs/index.html

@@ -38,6 +38,7 @@
         <script src="https://unpkg.com/docsify-copy-code@2"></script>
         <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
         <script src="//unpkg.com/prismjs/components/prism-typescript.min.js"></script>
+        <script src="https://unpkg.com/docsify-sign-off-sheet@1.0.0/dist/index.iife.js"></script>
         <script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js" type="text/javascript"></script>
     </body>
 </html>

docs/usage/paragraph.md

@@ -305,4 +305,12 @@ Example: https://github.com/dolanmiu/docx/blob/master/demo/15-page-break-before.
 
 ## Page break control
 
-Paragraphs have `.keepLines()` and `.keepNext()` methods that allow restricting page breaks within and between paragraphs. See [this Microsoft article](https://support.office.com/en-us/article/Keep-lines-and-paragraphs-together-d72af534-926f-4c4b-830a-abfc2daa3bfa) for more details)
+Paragraphs have `keepLines` and `keepNext` properties that allow restricting page breaks within and between paragraphs. See [this Microsoft article](https://support.office.com/en-us/article/Keep-lines-and-paragraphs-together-d72af534-926f-4c4b-830a-abfc2daa3bfa) for more details.
+
+```ts
+const paragraph = new Paragraph({
+    text: "Stay on the same page",
+    keepLines: true,
+    keepNext: true,
+});
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docx",
-  "version": "8.0.1",
+  "version": "8.0.2",
   "description": "Easily generate .docx files with JS/TS with a nice declarative API. Works for Node and on the Browser.",
   "main": "build/index.js",
   "scripts": {
@@ -104,7 +104,7 @@
     "tsconfig-paths": "^4.0.0",
     "tsconfig-paths-webpack-plugin": "^4.0.0",
     "typedoc": "^0.23.2",
-    "typescript": "5.0.2",
+    "typescript": "5.0.3",
     "unzipper": "^0.10.11",
     "webpack": "^5.28.0",
     "webpack-cli": "^5.0.0"

src/file/paragraph/properties.ts

@@ -23,7 +23,13 @@ export interface ILevelParagraphStylePropertiesOptions {
     readonly leftTabStop?: number;
     readonly indent?: IIndentAttributesProperties;
     readonly spacing?: ISpacingProperties;
+    /**
+     * Specifies that the paragraph (or at least part of it) should be rendered on the same page as the next paragraph when possible. If multiple paragraphs are to be kept together but they exceed a page, then the set of paragraphs begin on a new page and page breaks are used thereafter as needed.
+     */
     readonly keepNext?: boolean;
+    /**
+     * Specifies that all lines of the paragraph are to be kept on a single page when possible.
+     */
     readonly keepLines?: boolean;
     readonly outlineLevel?: number;
 }

src/file/styles/style/style.ts

@@ -41,6 +41,13 @@ export interface IStyleAttributes {
 
 export interface IStyleOptions {
     readonly name?: string;
+    /**
+     * Specifies the style upon which the current style is based-that is, the style from which the current style inherits. It is the mechanism for implementing style inheritance.
+     * Note that if the type of the current style must match the type of the style upon which it is based or the basedOn element will be ignored.
+     * However, if the current style is a numbering style, then the `basedOn` element is ignored.
+     *
+     * **WARNING**: You cannot set `basedOn` to be the same as `name`. This is akin to inheriting from itself. This creates a cyclic dependency and cause undesirable behavior.
+     */
     readonly basedOn?: string;
     readonly next?: string;
     readonly link?: string;

src/patcher/paragraph-split-inject.spec.ts

@@ -86,6 +86,59 @@ describe("paragraph-split-inject", () => {
                 ),
             ).to.throw();
         });
+
+        it("should continue if text run doesn't have text", () => {
+            expect(() =>
+                findRunElementIndexWithToken(
+                    {
+                        name: "w:p",
+                        type: "element",
+                        elements: [
+                            {
+                                name: "w:r",
+                                type: "element",
+                                elements: [
+                                    {
+                                        name: "w:t",
+                                        type: "element",
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                    "hello",
+                ),
+            ).to.throw();
+        });
+
+        it("should continue if text run doesn't have text", () => {
+            expect(() =>
+                findRunElementIndexWithToken(
+                    {
+                        name: "w:p",
+                        type: "element",
+                        elements: [
+                            {
+                                name: "w:r",
+                                type: "element",
+                                elements: [
+                                    {
+                                        name: "w:t",
+                                        type: "element",
+                                        elements: [
+                                            {
+                                                type: "text",
+                                            },
+                                        ],
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                    "hello",
+                ),
+            ).to.throw();
+        });
     });
 
     describe("splitRunElement", () => {

src/patcher/paragraph-split-inject.ts

@@ -8,7 +8,11 @@ export const findRunElementIndexWithToken = (paragraphElement: Element, token: s
             const textElement = (element.elements ?? []).filter((e) => e.type === "element" && e.name === "w:t");
 
             for (const text of textElement) {
-                if ((text.elements?.[0].text as string)?.includes(token)) {
+                if (!text.elements?.[0]) {
+                    continue;
+                }
+
+                if ((text.elements[0].text as string)?.includes(token)) {
                     return i;
                 }
             }