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",
+        "Xmlable",
-        "falsey",
-        "aiueo",
-        "iroha",
-        "aiueo",
-        "iroha",
-        "chosung",
-        "Abjad",
-        "Initializable",
-        "rels",
-        "dolan",
-        "xmlify",
-        "Xmlifyed",
         "xmlified",
-        "datas",
+        "xmlify",
-        "jszip",
+        "Xmlifyed"
-        "rsid",
-        "NUMPAGES",
-        "ATLEAST",
-        "ooxml",
-        "clippy",
-        "docsify"
     ],
     "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"
+    ]
 }

.nycrc

@@ -1,7 +1,7 @@
 {
   "check-coverage": true,
   "statements": 99.87,
-  "branches": 98.29,
+  "branches": 98.21,
   "functions": 100,
   "lines": 99.86,
   "include": [

demo/26-paragraph-borders.ts

@@ -25,6 +25,17 @@ const doc = new Document({
                         },
                     },
                 }),
+                new Paragraph({
+                    text: "",
+                    border: {
+                        top: {
+                            color: "auto",
+                            space: 1,
+                            style: BorderStyle.SINGLE,
+                            size: 6,
+                        },
+                    },
+                }),
                 new Paragraph({
                     children: [
                         new TextRun({

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/87-template-document.ts

@@ -0,0 +1,15 @@
+// Patch a document with patches
+// Import from 'docx' rather than '../build' if you install from npm
+import * as fs from "fs";
+import { patchDocument, PatchType, TextRun } from "../build";
+
+patchDocument(fs.readFileSync("demo/assets/simple-template-2.docx"), {
+    patches: {
+        name: {
+            type: PatchType.PARAGRAPH,
+            children: [new TextRun("Max")],
+        },
+    },
+}).then((doc) => {
+    fs.writeFileSync("My Document.docx", doc);
+});

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.0",
+  "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": {
@@ -28,9 +28,7 @@
     "lint"
   ],
   "files": [
-    "src",
+    "build"
-    "build",
-    "template"
   ],
   "repository": {
     "type": "git",
@@ -61,15 +59,14 @@
   "bugs": {
     "url": "https://github.com/dolanmiu/docx/issues"
   },
-  "homepage": "https://github.com/dolanmiu/docx#readme",
+  "homepage": "https://docx.js.org",
   "devDependencies": {
     "@types/chai": "^4.2.15",
     "@types/chai-as-promised": "^7.1.5",
-    "@types/glob": "^8.0.0",
     "@types/mocha": "^10.0.0",
     "@types/prompt": "^1.1.1",
     "@types/request-promise": "^4.1.42",
-    "@types/shelljs": "^0.8.9",
+    "@types/shelljs": "^0.8.11",
     "@types/sinon": "^10.0.0",
     "@types/unzipper": "^0.10.4",
     "@types/webpack": "^5.0.0",
@@ -107,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/character-style.ts

@@ -8,7 +8,6 @@ export interface IBaseCharacterStyleOptions extends IStyleOptions {
 
 export interface ICharacterStyleOptions extends IBaseCharacterStyleOptions {
     readonly id: string;
-    readonly name?: string;
 }
 
 export class StyleForCharacter extends Style {

src/file/styles/style/paragraph-style.ts

@@ -9,7 +9,6 @@ export interface IBaseParagraphStyleOptions extends IStyleOptions {
 
 export interface IParagraphStyleOptions extends IBaseParagraphStyleOptions {
     readonly id: string;
-    readonly name?: string;
 }
 
 export class StyleForParagraph extends Style {

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/from-docx.spec.ts

@@ -206,8 +206,7 @@ const MOCK_XML = `
 describe("from-docx", () => {
     describe("patchDocument", () => {
         describe("document.xml and [Content_Types].xml", () => {
-            before(() => {
+            beforeEach(() => {
-                sinon.createStubInstance(JSZip, {});
                 sinon.stub(JSZip, "loadAsync").callsFake(
                     () =>
                         new Promise<JSZip>((resolve) => {
@@ -220,7 +219,7 @@ describe("from-docx", () => {
                 );
             });
 
-            after(() => {
+            afterEach(() => {
                 (JSZip.loadAsync as unknown as sinon.SinonStub).restore();
             });
 
@@ -292,8 +291,7 @@ describe("from-docx", () => {
         });
 
         describe("document.xml and [Content_Types].xml with relationships", () => {
-            before(() => {
+            beforeEach(() => {
-                sinon.createStubInstance(JSZip, {});
                 sinon.stub(JSZip, "loadAsync").callsFake(
                     () =>
                         new Promise<JSZip>((resolve) => {
@@ -307,7 +305,7 @@ describe("from-docx", () => {
                 );
             });
 
-            after(() => {
+            afterEach(() => {
                 (JSZip.loadAsync as unknown as sinon.SinonStub).restore();
             });
 
@@ -322,6 +320,14 @@ describe("from-docx", () => {
                                     data: Buffer.from(""),
                                     transformation: { width: 100, height: 100 },
                                 }),
+                                new ExternalHyperlink({
+                                    children: [
+                                        new TextRun({
+                                            text: "Google Link",
+                                        }),
+                                    ],
+                                    link: "https://www.google.co.uk",
+                                }),
                             ],
                         },
                     },
@@ -331,8 +337,7 @@ describe("from-docx", () => {
         });
 
         describe("document.xml", () => {
-            before(() => {
+            beforeEach(() => {
-                sinon.createStubInstance(JSZip, {});
                 sinon.stub(JSZip, "loadAsync").callsFake(
                     () =>
                         new Promise<JSZip>((resolve) => {
@@ -344,7 +349,45 @@ describe("from-docx", () => {
                 );
             });
 
-            after(() => {
+            afterEach(() => {
+                (JSZip.loadAsync as unknown as sinon.SinonStub).restore();
+            });
+
+            it("should throw an error if the content types is not found", () =>
+                expect(
+                    patchDocument(Buffer.from(""), {
+                        patches: {
+                            // eslint-disable-next-line @typescript-eslint/naming-convention
+                            image_test: {
+                                type: PatchType.PARAGRAPH,
+                                children: [
+                                    new ImageRun({
+                                        data: Buffer.from(""),
+                                        transformation: { width: 100, height: 100 },
+                                    }),
+                                ],
+                            },
+                        },
+                    }),
+                ).to.eventually.be.rejected);
+        });
+
+        describe("Images", () => {
+            beforeEach(() => {
+                sinon.stub(JSZip, "loadAsync").callsFake(
+                    () =>
+                        new Promise<JSZip>((resolve) => {
+                            const zip = new JSZip();
+
+                            zip.file("word/document.xml", MOCK_XML);
+                            zip.file("word/document.bmp", "");
+
+                            resolve(zip);
+                        }),
+                );
+            });
+
+            afterEach(() => {
                 (JSZip.loadAsync as unknown as sinon.SinonStub).restore();
             });
 

src/patcher/from-docx.ts

@@ -68,7 +68,14 @@ export const patchDocument = async (data: InputDataType, options: PatchDocumentO
     const hyperlinkRelationshipAdditions: IHyperlinkRelationshipAddition[] = [];
     let hasMedia = false;
 
+    const binaryContentMap = new Map<string, Buffer>();
+
     for (const [key, value] of Object.entries(zipContent.files)) {
+        if (!key.endsWith(".xml") && !key.endsWith(".rels")) {
+            binaryContentMap.set(key, await value.async("nodebuffer"));
+            continue;
+        }
+
         const json = toJson(await value.async("text"));
         if (key.startsWith("word/") && !key.endsWith(".xml.rels")) {
             const context: IContext = {
@@ -196,6 +203,10 @@ export const patchDocument = async (data: InputDataType, options: PatchDocumentO
         zip.file(key, output);
     }
 
+    for (const [key, value] of binaryContentMap) {
+        zip.file(key, value);
+    }
+
     for (const { stream, fileName } of file.Media.Array) {
         zip.file(`word/media/${fileName}`, stream);
     }

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;
                 }
             }

src/patcher/paragraph-token-replacer.spec.ts

@@ -71,6 +71,156 @@ describe("paragraph-token-replacer", () => {
             });
         });
 
+        it("should handle case where it cannot find any text to replace", () => {
+            const output = replaceTokenInParagraphElement({
+                paragraphElement: {
+                    name: "w:p",
+                    attributes: {
+                        "w14:paraId": "2499FE9F",
+                        "w14:textId": "27B4FBC2",
+                        "w:rsidR": "00B51233",
+                        "w:rsidRDefault": "007B52ED",
+                        "w:rsidP": "007B52ED",
+                    },
+                    elements: [
+                        {
+                            type: "element",
+                            name: "w:pPr",
+                            elements: [{ type: "element", name: "w:pStyle", attributes: { "w:val": "Title" } }],
+                        },
+                        {
+                            type: "element",
+                            name: "w:r",
+                            elements: [
+                                {
+                                    type: "element",
+                                    name: "w:t",
+                                    attributes: { "xml:space": "preserve" },
+                                    elements: [{ type: "text", text: "Hello " }],
+                                },
+                            ],
+                        },
+                        {
+                            type: "element",
+                            name: "w:r",
+                            attributes: { "w:rsidR": "007F116B" },
+                            elements: [
+                                {
+                                    type: "element",
+                                    name: "w:t",
+                                    attributes: { "xml:space": "preserve" },
+                                    elements: [{ type: "text", text: "{{name}} " }],
+                                },
+                            ],
+                        },
+                        {
+                            type: "element",
+                            name: "w:r",
+                            elements: [{ type: "element", name: "w:t", elements: [{ type: "text", text: "World" }] }],
+                        },
+                    ],
+                },
+                renderedParagraph: {
+                    text: "Hello {{name}} World",
+                    runs: [
+                        { text: "Hello ", parts: [{ text: "Hello ", index: 0, start: 0, end: 5 }], index: 1, start: 0, end: 5 },
+                        { text: "{{name}} ", parts: [{ text: "{{name}} ", index: 0, start: 6, end: 14 }], index: 2, start: 6, end: 14 },
+                        { text: "World", parts: [{ text: "World", index: 0, start: 15, end: 19 }], index: 3, start: 15, end: 19 },
+                    ],
+                    index: 0,
+                    path: [0, 1, 0, 0],
+                },
+                originalText: "{{name}}",
+                replacementText: "John",
+            });
+
+            expect(output).to.deep.equal({
+                attributes: {
+                    "w14:paraId": "2499FE9F",
+                    "w14:textId": "27B4FBC2",
+                    "w:rsidP": "007B52ED",
+                    "w:rsidR": "00B51233",
+                    "w:rsidRDefault": "007B52ED",
+                },
+                elements: [
+                    {
+                        elements: [
+                            {
+                                attributes: {
+                                    "w:val": "Title",
+                                },
+                                name: "w:pStyle",
+                                type: "element",
+                            },
+                        ],
+                        name: "w:pPr",
+                        type: "element",
+                    },
+                    {
+                        elements: [
+                            {
+                                attributes: {
+                                    "xml:space": "preserve",
+                                },
+                                elements: [
+                                    {
+                                        text: "Hello ",
+                                        type: "text",
+                                    },
+                                ],
+                                name: "w:t",
+                                type: "element",
+                            },
+                        ],
+                        name: "w:r",
+                        type: "element",
+                    },
+                    {
+                        attributes: {
+                            "w:rsidR": "007F116B",
+                        },
+                        elements: [
+                            {
+                                attributes: {
+                                    "xml:space": "preserve",
+                                },
+                                elements: [
+                                    {
+                                        text: "John ",
+                                        type: "text",
+                                    },
+                                ],
+                                name: "w:t",
+                                type: "element",
+                            },
+                        ],
+                        name: "w:r",
+                        type: "element",
+                    },
+                    {
+                        elements: [
+                            {
+                                attributes: {
+                                    "xml:space": "preserve",
+                                },
+                                elements: [
+                                    {
+                                        text: "World",
+                                        type: "text",
+                                    },
+                                ],
+                                name: "w:t",
+                                type: "element",
+                            },
+                        ],
+                        name: "w:r",
+                        type: "element",
+                    },
+                ],
+                name: "w:p",
+            });
+        });
+
         // Try to fill rest of test coverage
         // it("should replace token in paragraph", () => {
         //     const output = replaceTokenInParagraphElement({

src/patcher/paragraph-token-replacer.ts

@@ -30,9 +30,15 @@ export const replaceTokenInParagraphElement = ({
             switch (replaceMode) {
                 case ReplaceMode.START:
                     if (startIndex >= start) {
-                        const partToReplace = run.text.substring(Math.max(startIndex, start), Math.min(endIndex, end) + 1);
+                        const offsetStartIndex = startIndex - start;
+                        const offsetEndIndex = Math.min(endIndex, end) - start;
+                        const partToReplace = run.text.substring(offsetStartIndex, offsetEndIndex + 1);
                         // We use a token to split the text if the replacement is within the same run
                         // If not, we just add text to the middle of the run later
+                        if (partToReplace === "") {
+                            continue;
+                        }
+
                         const firstPart = text.replace(partToReplace, replacementText);
                         patchTextElement(paragraphElement.elements![run.index].elements![index], firstPart);
                         replaceMode = ReplaceMode.MIDDLE;

src/patcher/util.ts

@@ -7,7 +7,7 @@ import { Text } from "@file/paragraph/run/run-components/text";
 const formatter = new Formatter();
 
 export const toJson = (xmlData: string): Element => {
-    const xmlObj = xml2js(xmlData, { compact: false }) as Element;
+    const xmlObj = xml2js(xmlData, { compact: false, captureSpacesBetweenElements: true }) as Element;
     return xmlObj;
 };
 

tsconfig.typedoc.json

@@ -1,5 +1,8 @@
 {
     "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "allowSyntheticDefaultImports": true
+    },
     "typedocOptions": {
         "out": "docs/api",
         "exclude": "test",