docx 7.1.0 → 7.3.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "docx",
-  "version": "7.1.0",
+  "version": "7.3.0",
   "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": {
     "pretest": "rimraf ./build",
-    "test": "mocha -r ts-node/register -r tsconfig-paths/register \"src/**/*.ts\"",
+    "test": "cross-env TS_NODE_PROJECT=\"tsconfig.spec.json\" mocha -r ts-node/register -r tsconfig-paths/register \"src/**/*.ts\"",
     "test.coverage": "nyc npm test",
     "test.watch": "npm test -- --watch",
     "prepublishOnly": "npm run build --production",
@@ -16,9 +16,10 @@
     "typedoc": "rimraf ./build && typedoc src/index.ts --tsconfig tsconfig.typedoc.json",
     "style": "prettier -l \"src/**/*.ts\"",
     "style.fix": "npm run style -- --write",
-    "fix-types": "ts-node scripts/types-absolute-fixer.ts",
+    "fix-types": "ts-node --skip-project scripts/types-absolute-fixer.ts",
     "e2e": "ts-node scripts/e2e.ts",
     "serve.docs": "cd docs && docsify serve",
+    "extract": "ts-node --project tsconfig.spec.json scripts/extract-document.ts",
     "ts-node": "ts-node --skip-project"
   },
   "pre-commit": [
@@ -48,7 +49,7 @@
   ],
   "types": "./build/index.d.ts",
   "dependencies": {
-    "@types/node": "^16.0.0",
+    "@types/node": "^17.0.0",
     "jszip": "^3.1.5",
     "nanoid": "^3.1.20",
     "xml": "^1.0.1",
@@ -62,12 +63,17 @@
   "homepage": "https://github.com/dolanmiu/docx#readme",
   "devDependencies": {
     "@types/chai": "^4.2.15",
+    "@types/glob": "^7.1.4",
     "@types/mocha": "^9.0.0",
+    "@types/prompt": "^1.1.1",
     "@types/request-promise": "^4.1.42",
+    "@types/shelljs": "^0.8.9",
     "@types/sinon": "^10.0.0",
+    "@types/unzipper": "^0.10.4",
     "@types/webpack": "^5.0.0",
     "buffer": "^6.0.3",
     "chai": "^3.5.0",
+    "cross-env": "^7.0.3",
     "docsify-cli": "^4.3.0",
     "glob": "^7.1.2",
     "jszip": "^3.1.5",
@@ -82,15 +88,16 @@
     "request-promise": "^4.2.2",
     "rimraf": "^3.0.2",
     "shelljs": "^0.8.4",
-    "sinon": "^11.0.0",
+    "sinon": "^12.0.1",
     "stream-browserify": "^3.0.0",
     "ts-loader": "^9.0.0",
-    "ts-node": "^9.0.0",
+    "ts-node": "^10.2.1",
     "tsconfig-paths": "^3.9.0",
     "tslint": "^6.1.3",
     "tslint-immutable": "^6.0.1",
     "typedoc": "^0.22.3",
-    "typescript": "4.4.3",
+    "typescript": "4.5.4",
+    "unzipper": "^0.10.11",
     "webpack": "^5.28.0",
     "webpack-cli": "^4.6.0"
   },

package/src/export/packer/next-compiler.ts

@@ -44,14 +44,9 @@ export class Compiler {
     public compile(file: File, prettifyXml?: boolean): JSZip {
         const zip = new JSZip();
         const xmlifiedFileMapping = this.xmlifyFile(file, prettifyXml);
+        const map = new Map<string, IXmlifyedFile | IXmlifyedFile[]>(Object.entries(xmlifiedFileMapping));
 
-        for (const key in xmlifiedFileMapping) {
-            if (!xmlifiedFileMapping[key]) {
-                continue;
-            }
-
-            const obj = xmlifiedFileMapping[key] as IXmlifyedFile | IXmlifyedFile[];
-
+        for (const [, obj] of map) {
             if (Array.isArray(obj)) {
                 for (const subFile of obj) {
                     zip.file(subFile.path, subFile.data);

package/src/export/packer/packer.spec.ts

@@ -12,7 +12,7 @@ describe("Packer", () => {
     beforeEach(() => {
         file = new File({
             creator: "Dolan Miu",
-            revision: "1",
+            revision: 1,
             lastModifiedBy: "Dolan Miu",
             sections: [
                 {

package/src/file/core-properties/properties.spec.ts

@@ -38,7 +38,7 @@ describe("Properties", () => {
                 keywords: "test docx",
                 description: "testing document",
                 lastModifiedBy: "the author",
-                revision: "123",
+                revision: 123,
             });
             const tree = new Formatter().format(properties);
             expect(Object.keys(tree)).to.deep.equal(["cp:coreProperties"]);

package/src/file/core-properties/properties.ts

@@ -17,7 +17,7 @@ export interface IPropertiesOptions {
     readonly keywords?: string;
     readonly description?: string;
     readonly lastModifiedBy?: string;
-    readonly revision?: string;
+    readonly revision?: number;
     readonly externalStyles?: string;
     readonly styles?: IStylesOptions;
     readonly numbering?: INumberingOptions;
@@ -89,7 +89,7 @@ export class CoreProperties extends XmlComponent {
             this.root.push(new StringContainer("cp:lastModifiedBy", options.lastModifiedBy));
         }
         if (options.revision) {
-            this.root.push(new StringContainer("cp:revision", options.revision));
+            this.root.push(new StringContainer("cp:revision", String(options.revision)));
         }
         this.root.push(new TimestampElement("dcterms:created"));
         this.root.push(new TimestampElement("dcterms:modified"));

package/src/file/document/body/section-properties/properties/doc-grid.spec.ts

@@ -0,0 +1,30 @@
+import { expect } from "chai";
+
+import { Formatter } from "export/formatter";
+
+import { DocumentGrid, DocumentGridType } from ".";
+
+describe("DocumentGrid", () => {
+    describe("#constructor()", () => {
+        it("should create documentGrid with specified linePitch", () => {
+            const docGrid = new DocumentGrid(360);
+            const tree = new Formatter().format(docGrid);
+
+            expect(tree["w:docGrid"]).to.deep.equal({ _attr: { "w:linePitch": 360 } });
+        });
+
+        it("should create documentGrid with specified linePitch and type", () => {
+            const docGrid = new DocumentGrid(360, undefined, DocumentGridType.LINES);
+            const tree = new Formatter().format(docGrid);
+
+            expect(tree["w:docGrid"]).to.deep.equal({ _attr: { "w:linePitch": 360, "w:type": "lines" } });
+        });
+
+        it("should create documentGrid with specified linePitch,charSpace and type", () => {
+            const docGrid = new DocumentGrid(346, -1541, DocumentGridType.LINES_AND_CHARS);
+            const tree = new Formatter().format(docGrid);
+
+            expect(tree["w:docGrid"]).to.deep.equal({ _attr: { "w:linePitch": 346, "w:charSpace": -1541, "w:type": "linesAndChars" } });
+        });
+    });
+});

package/src/file/document/body/section-properties/properties/doc-grid.ts

@@ -16,22 +16,36 @@ import { XmlAttributeComponent, XmlComponent } from "file/xml-components";
 //     <xsd:attribute name="linePitch" type="ST_DecimalNumber"/>
 //     <xsd:attribute name="charSpace" type="ST_DecimalNumber"/>
 // </xsd:complexType>
+
+export enum DocumentGridType {
+    DEFAULT = "default",
+    LINES = "lines",
+    LINES_AND_CHARS = "linesAndChars",
+    SNAP_TO_CHARS = "snapToChars",
+}
 export interface IDocGridAttributesProperties {
+    readonly type?: DocumentGridType;
     readonly linePitch?: number;
+    readonly charSpace?: number;
 }
 
 export class DocGridAttributes extends XmlAttributeComponent<IDocGridAttributesProperties> {
     protected readonly xmlKeys = {
+        type: "w:type",
         linePitch: "w:linePitch",
+        charSpace: "w:charSpace",
     };
 }
 
 export class DocumentGrid extends XmlComponent {
-    constructor(linePitch: number) {
+    constructor(linePitch: number, charSpace?: number, type?: DocumentGridType) {
         super("w:docGrid");
+
         this.root.push(
             new DocGridAttributes({
+                type: type,
                 linePitch: decimalNumber(linePitch),
+                charSpace: charSpace ? decimalNumber(charSpace) : undefined,
             }),
         );
     }

package/src/file/document/body/section-properties/properties/index.ts

@@ -7,6 +7,7 @@ export * from "./page-number";
 export * from "./page-borders";
 export * from "./page-margin";
 export * from "./page-borders";
+export * from "./page-text-direction";
 export * from "./line-number";
 export * from "./section-type";
 export * from "./header-footer-reference";

package/src/file/document/body/section-properties/properties/page-text-direction.spec.ts

@@ -0,0 +1,22 @@
+import { expect } from "chai";
+
+import { Formatter } from "export/formatter";
+import { PageTextDirection, PageTextDirectionType } from "./page-text-direction";
+
+describe("PageTextDirection", () => {
+    describe("#constructor()", () => {
+        it("should set the direction of the text flow to top-to-bottom-right-to-left", () => {
+            const textDirection = new PageTextDirection(PageTextDirectionType.TOP_TO_BOTTOM_RIGHT_TO_LEFT);
+
+            const tree = new Formatter().format(textDirection);
+
+            expect(tree).to.deep.equal({
+                "w:textDirection": {
+                    _attr: {
+                        "w:val": "tbRl",
+                    },
+                },
+            });
+        });
+    });
+});

package/src/file/document/body/section-properties/properties/page-text-direction.ts

@@ -0,0 +1,22 @@
+import { XmlAttributeComponent, XmlComponent } from "file/xml-components";
+
+export enum PageTextDirectionType {
+    LEFT_TO_RIGHT_TOP_TO_BOTTOM = "lrTb",
+    TOP_TO_BOTTOM_RIGHT_TO_LEFT = "tbRl",
+}
+
+class PageTextDirectionAttributes extends XmlAttributeComponent<{ readonly val: PageTextDirectionType }> {
+    protected readonly xmlKeys = { val: "w:val" };
+}
+
+export class PageTextDirection extends XmlComponent {
+    constructor(value: PageTextDirectionType) {
+        super("w:textDirection");
+
+        this.root.push(
+            new PageTextDirectionAttributes({
+                val: value,
+            }),
+        );
+    }
+}

package/src/file/document/body/section-properties/section-properties.spec.ts

@@ -9,8 +9,10 @@ import { NumberFormat } from "file/shared/number-format";
 import { VerticalAlign } from "file/vertical-align";
 
 import { PageOrientation } from "./properties";
+import { DocumentGridType } from "./properties/doc-grid";
 import { LineNumberRestartFormat } from "./properties/line-number";
 import { PageBorderOffsetFrom } from "./properties/page-borders";
+import { PageTextDirectionType } from "./properties/page-text-direction";
 import { SectionType } from "./properties/section-type";
 import { sectionMarginDefaults, sectionPageSizeDefaults, SectionProperties } from "./section-properties";
 
@@ -63,6 +65,7 @@ describe("SectionProperties", () => {
                 },
                 grid: {
                     linePitch: convertInchesToTwip(0.25),
+                    type: DocumentGridType.LINES,
                 },
                 headerWrapperGroup: {
                     default: new HeaderWrapper(media, 100),
@@ -99,7 +102,7 @@ describe("SectionProperties", () => {
             expect(tree["w:sectPr"][5]).to.deep.equal({ "w:cols": { _attr: { "w:space": 208, "w:sep": true, "w:num": 2 } } });
             expect(tree["w:sectPr"][6]).to.deep.equal({ "w:vAlign": { _attr: { "w:val": "top" } } });
             expect(tree["w:sectPr"][7]).to.deep.equal({ "w:titlePg": {} });
-            expect(tree["w:sectPr"][8]).to.deep.equal({ "w:docGrid": { _attr: { "w:linePitch": 360 } } });
+            expect(tree["w:sectPr"][8]).to.deep.equal({ "w:docGrid": { _attr: { "w:linePitch": 360, "w:type": "lines" } } });
         });
 
         it("should create section properties with no options", () => {
@@ -258,5 +261,19 @@ describe("SectionProperties", () => {
                 "w:lnNumType": { _attr: { "w:countBy": 2, "w:distance": 4, "w:restart": "continuous", "w:start": 2 } },
             });
         });
+
+        it("should create section properties with text flow direction", () => {
+            const properties = new SectionProperties({
+                page: {
+                    textDirection: PageTextDirectionType.TOP_TO_BOTTOM_RIGHT_TO_LEFT,
+                },
+            });
+            const tree = new Formatter().format(properties);
+            expect(Object.keys(tree)).to.deep.equal(["w:sectPr"]);
+            const type = tree["w:sectPr"].find((item) => item["w:textDirection"] !== undefined);
+            expect(type).to.deep.equal({
+                "w:textDirection": { _attr: { "w:val": "tbRl" } },
+            });
+        });
     });
 });

package/src/file/document/body/section-properties/section-properties.ts

@@ -15,6 +15,7 @@ import { IPageBordersOptions, PageBorders } from "./properties/page-borders";
 import { IPageMarginAttributes, PageMargin } from "./properties/page-margin";
 import { IPageNumberTypeAttributes, PageNumberType } from "./properties/page-number";
 import { IPageSizeAttributes, PageOrientation, PageSize } from "./properties/page-size";
+import { PageTextDirection, PageTextDirectionType } from "./properties/page-text-direction";
 import { SectionType, Type } from "./properties/section-type";
 
 export interface IHeaderFooterGroup<T> {
@@ -29,6 +30,7 @@ export interface ISectionPropertiesOptions {
         readonly margin?: IPageMarginAttributes;
         readonly pageNumbers?: IPageNumberTypeAttributes;
         readonly borders?: IPageBordersOptions;
+        readonly textDirection?: PageTextDirectionType;
     };
     readonly grid?: IDocGridAttributesProperties;
     readonly headerWrapperGroup?: IHeaderFooterGroup<HeaderWrapper>;
@@ -108,8 +110,9 @@ export class SectionProperties extends XmlComponent {
             } = {},
             pageNumbers = {},
             borders,
+            textDirection,
         } = {},
-        grid: { linePitch = 360 } = {},
+        grid: { linePitch = 360, charSpace, type: gridType } = {},
         headerWrapperGroup = {},
         footerWrapperGroup = {},
         lineNumbers,
@@ -152,7 +155,11 @@ export class SectionProperties extends XmlComponent {
             this.root.push(new OnOffElement("w:titlePg", titlePage));
         }
 
-        this.root.push(new DocumentGrid(linePitch));
+        if (textDirection) {
+            this.root.push(new PageTextDirection(textDirection));
+        }
+
+        this.root.push(new DocumentGrid(linePitch, charSpace, gridType));
     }
 
     private addHeaderFooterGroup(

package/src/file/document/document-background/document-background.spec.ts

@@ -6,14 +6,12 @@ import { DocumentBackground } from "./document-background";
 
 describe("DocumentBackground", () => {
     describe("#constructor()", () => {
-        it("should create a DocumentBackground with no options and set color to auto", () => {
+        it("should create a DocumentBackground with no options", () => {
             const documentBackground = new DocumentBackground({});
             const tree = new Formatter().format(documentBackground);
             expect(tree).to.deep.equal({
                 "w:background": {
-                    _attr: {
-                        "w:color": "FFFFFF",
-                    },
+                    _attr: {},
                 },
             });
         });

package/src/file/document/document-background/document-background.ts

@@ -26,7 +26,7 @@ import { XmlAttributeComponent, XmlComponent } from "file/xml-components";
 // </xsd:simpleType>
 
 export class DocumentBackgroundAttributes extends XmlAttributeComponent<{
-    readonly color: string;
+    readonly color?: string;
     readonly themeColor?: string;
     readonly themeShade?: string;
     readonly themeTint?: string;
@@ -68,7 +68,7 @@ export class DocumentBackground extends XmlComponent {
 
         this.root.push(
             new DocumentBackgroundAttributes({
-                color: hexColorValue(options.color ? options.color : "FFFFFF"),
+                color: options.color === undefined ? undefined : hexColorValue(options.color),
                 themeColor: options.themeColor,
                 themeShade: options.themeShade === undefined ? undefined : uCharHexNumber(options.themeShade),
                 themeTint: options.themeTint === undefined ? undefined : uCharHexNumber(options.themeTint),

package/src/file/document/document.spec.ts

@@ -40,9 +40,7 @@ describe("Document", () => {
                     },
                     {
                         "w:background": {
-                            _attr: {
-                                "w:color": "FFFFFF",
-                            },
+                            _attr: {},
                         },
                     },
                     { "w:body": {} },

package/src/file/file.ts

@@ -57,7 +57,7 @@ export class File {
         this.coreProperties = new CoreProperties({
             ...options,
             creator: options.creator ?? "Un-named",
-            revision: options.revision ?? "1",
+            revision: options.revision ?? 1,
             lastModifiedBy: options.lastModifiedBy ?? "Un-named",
         });
 

package/src/file/numbering/level.spec.ts

@@ -0,0 +1,25 @@
+import { expect } from "chai";
+
+import { LevelFormat, LevelSuffix } from ".";
+import { AlignmentType } from "..";
+
+import { Level } from "./level";
+
+describe("Level", () => {
+    describe("#constructor", () => {
+        it("should throw an error if level exceeds 9", () => {
+            expect(
+                () =>
+                    new Level({
+                        level: 10,
+                        format: LevelFormat.BULLET,
+                        text: "test",
+                        alignment: AlignmentType.BOTH,
+                        start: 3,
+                        style: { run: {}, paragraph: {} },
+                        suffix: LevelSuffix.SPACE,
+                    }),
+            ).to.throw();
+        });
+    });
+});

package/src/file/numbering/level.ts

@@ -161,6 +161,12 @@ export class LevelBase extends XmlComponent {
         this.root.push(this.paragraphProperties);
         this.root.push(this.runProperties);
 
+        if (level > 9) {
+            throw new Error(
+                "Level cannot be greater than 9. Read more here: https://answers.microsoft.com/en-us/msoffice/forum/all/does-word-support-more-than-9-list-levels/d130fdcd-1781-446d-8c84-c6c79124e4d7",
+            );
+        }
+
         this.root.push(
             new LevelAttributes({
                 ilvl: decimalNumber(level),

package/src/file/paragraph/formatting/unordered-list.spec.ts

@@ -5,21 +5,17 @@ import { Formatter } from "export/formatter";
 import { NumberProperties } from "./unordered-list";
 
 describe("NumberProperties", () => {
-    let numberProperties: NumberProperties;
-
-    beforeEach(() => {
-        numberProperties = new NumberProperties(5, 10);
-    });
-
     describe("#constructor()", () => {
         it("should create a Number Properties with correct root key", () => {
+            const numberProperties = new NumberProperties(5, 9);
+
             const tree = new Formatter().format(numberProperties);
             expect(tree).to.deep.equal({
                 "w:numPr": [
                     {
                         "w:ilvl": {
                             _attr: {
-                                "w:val": 10,
+                                "w:val": 9,
                             },
                         },
                     },
@@ -33,5 +29,9 @@ describe("NumberProperties", () => {
                 ],
             });
         });
+
+        it("should throw an error if level exceeds 9", () => {
+            expect(() => new NumberProperties(5, 10)).to.throw();
+        });
     });
 });

package/src/file/paragraph/formatting/unordered-list.ts

@@ -11,6 +11,13 @@ export class NumberProperties extends XmlComponent {
 class IndentLevel extends XmlComponent {
     constructor(level: number) {
         super("w:ilvl");
+
+        if (level > 9) {
+            throw new Error(
+                "Level cannot be greater than 9. Read more here: https://answers.microsoft.com/en-us/msoffice/forum/all/does-word-support-more-than-9-list-levels/d130fdcd-1781-446d-8c84-c6c79124e4d7",
+            );
+        }
+
         this.root.push(
             new Attributes({
                 val: level,

package/src/file/paragraph/links/bookmark-attributes.ts

@@ -1,7 +1,7 @@
 import { XmlAttributeComponent } from "file/xml-components";
 
 export class BookmarkStartAttributes extends XmlAttributeComponent<{
-    readonly id: string;
+    readonly id: number;
     readonly name: string;
 }> {
     protected readonly xmlKeys = {
@@ -11,7 +11,7 @@ export class BookmarkStartAttributes extends XmlAttributeComponent<{
 }
 
 export class BookmarkEndAttributes extends XmlAttributeComponent<{
-    readonly id: string;
+    readonly id: number;
 }> {
     protected readonly xmlKeys = {
         id: "w:id",

package/src/file/paragraph/links/bookmark.spec.ts

@@ -36,6 +36,6 @@ describe("Bookmark", () => {
 
     it("should create a bookmark with the correct attributes on the bookmark end element", () => {
         const newJson = Utility.jsonify(bookmark);
-        expect(newJson.end.root[0].root.id).to.be.a("string");
+        expect(newJson.end.root[0].root.id).to.be.a("number");
     });
 });

package/src/file/paragraph/links/bookmark.ts

@@ -1,5 +1,5 @@
 // http://officeopenxml.com/WPbookmark.php
-import { uniqueId } from "convenience-functions";
+import { uniqueNumericId } from "convenience-functions";
 import { XmlComponent } from "file/xml-components";
 
 import { ParagraphChild } from "../paragraph";
@@ -11,7 +11,7 @@ export class Bookmark {
     public readonly end: BookmarkEnd;
 
     constructor(options: { readonly id: string; readonly children: ParagraphChild[] }) {
-        const linkId = uniqueId();
+        const linkId = uniqueNumericId();
 
         this.start = new BookmarkStart(options.id, linkId);
         this.children = options.children;
@@ -19,8 +19,40 @@ export class Bookmark {
     }
 }
 
+// <xsd:element name="bookmarkStart" type="CT_Bookmark"/>
+// <xsd:element name="bookmarkEnd" type="CT_MarkupRange"/>
+
+// <xsd:complexType name="CT_Bookmark">
+//   <xsd:complexContent>
+//     <xsd:extension base="CT_BookmarkRange">
+//     <xsd:attribute name="name" type="s:ST_String" use="required"/>
+//     </xsd:extension>
+//   </xsd:complexContent>
+// </xsd:complexType>
+
+// <xsd:complexType name="CT_BookmarkRange">
+//   <xsd:complexContent>
+//     <xsd:extension base="CT_MarkupRange">
+//       <xsd:attribute name="colFirst" type="ST_DecimalNumber" use="optional"/>
+//       <xsd:attribute name="colLast" type="ST_DecimalNumber" use="optional"/>
+//     </xsd:extension>
+//   </xsd:complexContent>
+// </xsd:complexType>
+
+// <xsd:complexType name="CT_MarkupRange">
+//   <xsd:complexContent>
+//     <xsd:extension base="CT_Markup">
+//       <xsd:attribute name="displacedByCustomXml" type="ST_DisplacedByCustomXml" use="optional"/>
+//     </xsd:extension>
+//   </xsd:complexContent>
+// </xsd:complexType>
+
+// <xsd:complexType name="CT_Markup">
+//   <xsd:attribute name="id" type="ST_DecimalNumber" use="required"/>
+// </xsd:complexType>
+
 export class BookmarkStart extends XmlComponent {
-    constructor(id: string, linkId: string) {
+    constructor(id: string, linkId: number) {
         super("w:bookmarkStart");
 
         const attributes = new BookmarkStartAttributes({
@@ -32,7 +64,7 @@ export class BookmarkStart extends XmlComponent {
 }
 
 export class BookmarkEnd extends XmlComponent {
-    constructor(linkId: string) {
+    constructor(linkId: number) {
         super("w:bookmarkEnd");
 
         const attributes = new BookmarkEndAttributes({

package/src/file/paragraph/paragraph.spec.ts

@@ -22,6 +22,9 @@ describe("Paragraph", () => {
         stub(convenienceFunctions, "uniqueId").callsFake(() => {
             return "test-unique-id";
         });
+        stub(convenienceFunctions, "uniqueNumericId").callsFake(() => {
+            return -101;
+        });
     });
 
     after(() => {
@@ -716,7 +719,7 @@ describe("Paragraph", () => {
                 {
                     "w:bookmarkStart": {
                         _attr: {
-                            "w:id": "test-unique-id",
+                            "w:id": -101,
                             "w:name": "test-id",
                         },
                     },
@@ -738,7 +741,7 @@ describe("Paragraph", () => {
                 {
                     "w:bookmarkEnd": {
                         _attr: {
-                            "w:id": "test-unique-id",
+                            "w:id": -101,
                         },
                     },
                 },