Version bump

fix: added unique numeric id creator to avoid numbering render errors

.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.3",
   "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/drawing/anchor/anchor.spec.ts

@@ -41,11 +41,11 @@ const createAnchor = (drawingOptions: IDrawingOptions): Anchor =>
 
 describe("Anchor", () => {
     before(() => {
-        stub(convenienceFunctions, "uniqueNumericId").callsFake(() => 0);
+        stub(convenienceFunctions, "docPropertiesUniqueNumericId").callsFake(() => 0);
     });
 
     after(() => {
-        (convenienceFunctions.uniqueNumericId as SinonStub).restore();
+        (convenienceFunctions.docPropertiesUniqueNumericId as SinonStub).restore();
     });
 
     let anchor: Anchor;

src/file/drawing/doc-properties/doc-properties.ts

@@ -2,7 +2,7 @@
 import { IContext, IXmlableObject, NextAttributeComponent, XmlComponent } from "@file/xml-components";
 import { ConcreteHyperlink } from "@file/paragraph";
 
-import { uniqueNumericId } from "@util/convenience-functions";
+import { docPropertiesUniqueNumericId } from "@util/convenience-functions";
 
 import { createHyperlinkClick } from "./doc-properties-children";
 
@@ -32,7 +32,7 @@ export class DocProperties extends XmlComponent {
             new NextAttributeComponent({
                 id: {
                     key: "id",
-                    value: uniqueNumericId(),
+                    value: docPropertiesUniqueNumericId(),
                 },
                 name: {
                     key: "name",

src/file/drawing/drawing.spec.ts

@@ -31,11 +31,11 @@ const createDrawing = (drawingOptions?: IDrawingOptions): Drawing =>
 
 describe("Drawing", () => {
     before(() => {
-        stub(convenienceFunctions, "uniqueNumericId").callsFake(() => 0);
+        stub(convenienceFunctions, "docPropertiesUniqueNumericId").callsFake(() => 0);
     });
 
     after(() => {
-        (convenienceFunctions.uniqueNumericId as SinonStub).restore();
+        (convenienceFunctions.docPropertiesUniqueNumericId as SinonStub).restore();
     });
 
     let currentBreak: Drawing;

src/file/numbering/numbering.spec.ts

@@ -8,11 +8,13 @@ import { Numbering } from "./numbering";
 
 describe("Numbering", () => {
     before(() => {
-        stub(convenienceFunctions, "uniqueNumericId").callsFake(() => 0);
+        stub(convenienceFunctions, "abstractNumUniqueNumericId").callsFake(() => 0);
+        stub(convenienceFunctions, "concreteNumUniqueNumericId").callsFake(() => 0);
     });
 
     after(() => {
-        (convenienceFunctions.uniqueNumericId as SinonStub).restore();
+        (convenienceFunctions.abstractNumUniqueNumericId as SinonStub).restore();
+        (convenienceFunctions.concreteNumUniqueNumericId as SinonStub).restore();
     });
 
     describe("#constructor", () => {

src/file/numbering/numbering.ts

@@ -2,7 +2,7 @@
 // https://stackoverflow.com/questions/58622437/purpose-of-abstractnum-and-numberinginstance
 import { AlignmentType } from "@file/paragraph";
 import { IContext, IXmlableObject, XmlComponent } from "@file/xml-components";
-import { convertInchesToTwip, uniqueNumericId } from "@util/convenience-functions";
+import { abstractNumUniqueNumericId, concreteNumUniqueNumericId, convertInchesToTwip } from "@util/convenience-functions";
 
 import { DocumentAttributes } from "../document/document-attributes";
 import { AbstractNumbering } from "./abstract-numbering";
@@ -55,7 +55,7 @@ export class Numbering extends XmlComponent {
             }),
         );
 
-        const abstractNumbering = new AbstractNumbering(uniqueNumericId(), [
+        const abstractNumbering = new AbstractNumbering(abstractNumUniqueNumericId(), [
             {
                 level: 0,
                 format: LevelFormat.BULLET,
@@ -176,7 +176,7 @@ export class Numbering extends XmlComponent {
         this.abstractNumberingMap.set("default-bullet-numbering", abstractNumbering);
 
         for (const con of options.config) {
-            this.abstractNumberingMap.set(con.reference, new AbstractNumbering(uniqueNumericId(), con.levels));
+            this.abstractNumberingMap.set(con.reference, new AbstractNumbering(abstractNumUniqueNumericId(), con.levels));
             this.referenceConfigMap.set(con.reference, con.levels);
         }
     }
@@ -209,7 +209,7 @@ export class Numbering extends XmlComponent {
         const firstLevelStartNumber = referenceConfigLevels && referenceConfigLevels[0].start;
 
         const concreteNumberingSettings = {
-            numId: uniqueNumericId(),
+            numId: concreteNumUniqueNumericId(),
             abstractNumId: abstractNumbering.id,
             reference,
             instance,

src/file/paragraph/links/bookmark.ts

@@ -1,6 +1,6 @@
 // http://officeopenxml.com/WPbookmark.php
 import { XmlComponent } from "@file/xml-components";
-import { uniqueNumericId } from "@util/convenience-functions";
+import { bookmarkUniqueNumericId } from "@util/convenience-functions";
 
 import { ParagraphChild } from "../paragraph";
 import { BookmarkEndAttributes, BookmarkStartAttributes } from "./bookmark-attributes";
@@ -11,7 +11,7 @@ export class Bookmark {
     public readonly end: BookmarkEnd;
 
     public constructor(options: { readonly id: string; readonly children: readonly ParagraphChild[] }) {
-        const linkId = uniqueNumericId();
+        const linkId = bookmarkUniqueNumericId();
 
         this.start = new BookmarkStart(options.id, linkId);
         this.children = options.children;

src/file/paragraph/paragraph.spec.ts

@@ -20,12 +20,12 @@ import { TextRun } from "./run";
 describe("Paragraph", () => {
     before(() => {
         stub(convenienceFunctions, "uniqueId").callsFake(() => "test-unique-id");
-        stub(convenienceFunctions, "uniqueNumericId").callsFake(() => -101);
+        stub(convenienceFunctions, "bookmarkUniqueNumericId").callsFake(() => -101);
     });
 
     after(() => {
         (convenienceFunctions.uniqueId as SinonStub).restore();
-        (convenienceFunctions.uniqueNumericId as SinonStub).restore();
+        (convenienceFunctions.bookmarkUniqueNumericId as SinonStub).restore();
     });
 
     describe("#constructor()", () => {

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/paragraph/run/image-run.spec.ts

@@ -11,12 +11,12 @@ import { ImageRun } from "./image-run";
 describe("ImageRun", () => {
     before(() => {
         stub(convenienceFunctions, "uniqueId").callsFake(() => "test-unique-id");
-        stub(convenienceFunctions, "uniqueNumericId").callsFake(() => 0);
+        stub(convenienceFunctions, "docPropertiesUniqueNumericId").callsFake(() => 0);
     });
 
     after(() => {
         (convenienceFunctions.uniqueId as SinonStub).restore();
-        (convenienceFunctions.uniqueNumericId as SinonStub).restore();
+        (convenienceFunctions.docPropertiesUniqueNumericId as SinonStub).restore();
     });
 
     describe("#constructor()", () => {

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

src/util/convenience-functions.spec.ts

@@ -1,6 +1,6 @@
 import { expect } from "chai";
 
-import { convertInchesToTwip, convertMillimetersToTwip, uniqueId, uniqueNumericId } from "./convenience-functions";
+import { convertInchesToTwip, convertMillimetersToTwip, uniqueId, uniqueNumericIdCreator } from "./convenience-functions";
 
 describe("Utility", () => {
     describe("#convertMillimetersToTwip", () => {
@@ -17,8 +17,9 @@ describe("Utility", () => {
         });
     });
 
-    describe("#uniqueNumericId", () => {
+    describe("#uniqueNumericIdCreator", () => {
         it("should generate a unique incrementing ID", () => {
+            const uniqueNumericId = uniqueNumericIdCreator();
             expect(uniqueNumericId()).to.not.be.undefined;
         });
     });

src/util/convenience-functions.ts

@@ -1,12 +1,19 @@
 import { nanoid } from "nanoid/non-secure";
 
-let currentCount = 0;
-
 // Twip - twentieths of a point
 export const convertMillimetersToTwip = (millimeters: number): number => Math.floor((millimeters / 25.4) * 72 * 20);
 
 export const convertInchesToTwip = (inches: number): number => Math.floor(inches * 72 * 20);
 
-export const uniqueNumericId = (): number => ++currentCount;
+export const uniqueNumericIdCreator = (initial = 0): (() => number) => {
+    let currentCount = initial;
+
+    return () => ++currentCount;
+};
+
+export const abstractNumUniqueNumericId = uniqueNumericIdCreator();
+export const concreteNumUniqueNumericId = uniqueNumericIdCreator(1); // Setting initial to 1 as we have numId = 1 for "default-bullet-numbering"
+export const docPropertiesUniqueNumericId = uniqueNumericIdCreator();
+export const bookmarkUniqueNumericId = uniqueNumericIdCreator();
 
 export const uniqueId = (): string => nanoid().toLowerCase();