docx 7.8.1 → 8.0.0

package/src/file/table/table-properties/table-float-properties.ts

@@ -1,5 +1,5 @@
-import { StringEnumValueElement, XmlAttributeComponent, XmlComponent } from "@file/xml-components";
-import { signedTwipsMeasureValue, twipsMeasureValue } from "@util/values";
+import { NextAttributeComponent, StringEnumValueElement, XmlComponent } from "@file/xml-components";
+import { PositiveUniversalMeasure, signedTwipsMeasureValue, twipsMeasureValue, UniversalMeasure } from "@util/values";
 
 export enum TableAnchorType {
     MARGIN = "margin",
@@ -35,7 +35,7 @@ export enum OverlapType {
     OVERLAP = "overlap",
 }
 
-export interface ITableFloatOptions {
+export type ITableFloatOptions = {
     /* cSpell:disable */
     /**
      * Specifies the horizontal anchor or the base object from which the horizontal positioning in the
@@ -55,7 +55,7 @@ export interface ITableFloatOptions {
      * If relativeHorizontalPosition is also specified, then the absoluteHorizontalPosition attribute is ignored.
      * If the attribute is omitted, the value is assumed to be zero.
      */
-    readonly absoluteHorizontalPosition?: number | string;
+    readonly absoluteHorizontalPosition?: number | UniversalMeasure;
 
     /**
      * Specifies a relative horizontal position for the table, relative to the horizontalAnchor attribute.
@@ -86,7 +86,7 @@ export interface ITableFloatOptions {
      * If relativeVerticalPosition is also specified, then the absoluteVerticalPosition attribute is ignored.
      * If the attribute is omitted, the value is assumed to be zero.
      */
-    readonly absoluteVerticalPosition?: number | string;
+    readonly absoluteVerticalPosition?: number | UniversalMeasure;
 
     /**
      * Specifies a relative vertical position for the table, relative to the verticalAnchor attribute.
@@ -104,27 +104,27 @@ export interface ITableFloatOptions {
      * Specifies the minimum distance to be maintained between the table and the top of text in the paragraph
      * below the table. The value is in twentieths of a point. If omitted, the value is assumed to be zero.
      */
-    readonly bottomFromText?: number | string;
+    readonly bottomFromText?: number | PositiveUniversalMeasure;
 
     /**
      * Specifies the minimum distance to be maintained between the table and the bottom edge of text in the paragraph
      * above the table. The value is in twentieths of a point. If omitted, the value is assumed to be zero.
      */
-    readonly topFromText?: number | string;
+    readonly topFromText?: number | PositiveUniversalMeasure;
 
     /**
      * Specifies the minimum distance to be maintained between the table and the edge of text in the paragraph
      * to the left of the table. The value is in twentieths of a point. If omitted, the value is assumed to be zero.
      */
-    readonly leftFromText?: number | string;
+    readonly leftFromText?: number | PositiveUniversalMeasure;
 
     /**
      * Specifies the minimum distance to be maintained between the table and the edge of text in the paragraph
      * to the right of the table. The value is in twentieths of a point. If omitted, the value is assumed to be zero.
      */
-    readonly rightFromText?: number | string;
+    readonly rightFromText?: number | PositiveUniversalMeasure;
     readonly overlap?: OverlapType;
-}
+};
 
 // <xsd:complexType name="CT_TblPPr">
 //     <xsd:attribute name="leftFromText" type="s:ST_TwipsMeasure"/>
@@ -139,51 +139,65 @@ export interface ITableFloatOptions {
 //     <xsd:attribute name="tblpY" type="ST_SignedTwipsMeasure"/>
 // </xsd:complexType>
 
-export class TableFloatOptionsAttributes extends XmlAttributeComponent<ITableFloatOptions> {
-    protected readonly xmlKeys = {
-        horizontalAnchor: "w:horzAnchor",
-        verticalAnchor: "w:vertAnchor",
-        absoluteHorizontalPosition: "w:tblpX",
-        relativeHorizontalPosition: "w:tblpXSpec",
-        absoluteVerticalPosition: "w:tblpY",
-        relativeVerticalPosition: "w:tblpYSpec",
-        bottomFromText: "w:bottomFromText",
-        topFromText: "w:topFromText",
-        leftFromText: "w:leftFromText",
-        rightFromText: "w:rightFromText",
-    };
-}
-
 export class TableFloatProperties extends XmlComponent {
     public constructor({
-        leftFromText,
-        rightFromText,
-        topFromText,
-        bottomFromText,
+        horizontalAnchor,
+        verticalAnchor,
         absoluteHorizontalPosition,
+        relativeHorizontalPosition,
         absoluteVerticalPosition,
-        ...options
+        relativeVerticalPosition,
+        bottomFromText,
+        topFromText,
+        leftFromText,
+        rightFromText,
+        overlap,
     }: ITableFloatOptions) {
         super("w:tblpPr");
         this.root.push(
-            new TableFloatOptionsAttributes({
-                leftFromText: leftFromText === undefined ? undefined : twipsMeasureValue(leftFromText),
-                rightFromText: rightFromText === undefined ? undefined : twipsMeasureValue(rightFromText),
-                topFromText: topFromText === undefined ? undefined : twipsMeasureValue(topFromText),
-                bottomFromText: bottomFromText === undefined ? undefined : twipsMeasureValue(bottomFromText),
-                absoluteHorizontalPosition:
-                    absoluteHorizontalPosition === undefined ? undefined : signedTwipsMeasureValue(absoluteHorizontalPosition),
-                absoluteVerticalPosition:
-                    absoluteVerticalPosition === undefined ? undefined : signedTwipsMeasureValue(absoluteVerticalPosition),
-                ...options,
+            new NextAttributeComponent<Omit<ITableFloatOptions, "overlap">>({
+                leftFromText: { key: "w:leftFromText", value: leftFromText === undefined ? undefined : twipsMeasureValue(leftFromText) },
+                rightFromText: {
+                    key: "w:rightFromText",
+                    value: rightFromText === undefined ? undefined : twipsMeasureValue(rightFromText),
+                },
+                topFromText: { key: "w:topFromText", value: topFromText === undefined ? undefined : twipsMeasureValue(topFromText) },
+                bottomFromText: {
+                    key: "w:bottomFromText",
+                    value: bottomFromText === undefined ? undefined : twipsMeasureValue(bottomFromText),
+                },
+                absoluteHorizontalPosition: {
+                    key: "w:tblpX",
+                    value: absoluteHorizontalPosition === undefined ? undefined : signedTwipsMeasureValue(absoluteHorizontalPosition),
+                },
+                absoluteVerticalPosition: {
+                    key: "w:tblpY",
+                    value: absoluteVerticalPosition === undefined ? undefined : signedTwipsMeasureValue(absoluteVerticalPosition),
+                },
+                horizontalAnchor: {
+                    key: "w:horzAnchor",
+                    value: horizontalAnchor === undefined ? undefined : horizontalAnchor,
+                },
+                relativeHorizontalPosition: {
+                    key: "w:tblpXSpec",
+                    value: relativeHorizontalPosition,
+                },
+                relativeVerticalPosition: {
+                    key: "w:tblpYSpec",
+                    value: relativeVerticalPosition,
+                },
+                verticalAnchor: {
+                    key: "w:vertAnchor",
+                    value: verticalAnchor,
+                },
             }),
         );
 
-        if (options.overlap) {
+        if (overlap) {
             // <xsd:complexType name="CT_TblOverlap">
             //     <xsd:attribute name="val" type="ST_TblOverlap" use="required"/>
             // </xsd:complexType>
-            this.root.push(new StringEnumValueElement<OverlapType>("w:tblOverlap", options.overlap));
+            this.root.push(new StringEnumValueElement<OverlapType>("w:tblOverlap", overlap));
         }
     }
 }

package/src/file/table/table-row/table-row-height.ts

@@ -1,5 +1,5 @@
 import { XmlAttributeComponent, XmlComponent } from "@file/xml-components";
-import { twipsMeasureValue } from "@util/values";
+import { PositiveUniversalMeasure, twipsMeasureValue } from "@util/values";
 
 // <xsd:complexType name="CT_Height">
 //     <xsd:attribute name="val" type="s:ST_TwipsMeasure"/>
@@ -30,7 +30,7 @@ export class TableRowHeightAttributes extends XmlAttributeComponent<{
 }
 
 export class TableRowHeight extends XmlComponent {
-    public constructor(value: number | string, rule: HeightRule) {
+    public constructor(value: number | PositiveUniversalMeasure, rule: HeightRule) {
         super("w:trHeight");
 
         this.root.push(

package/src/file/table/table-row/table-row-properties.ts

@@ -28,6 +28,7 @@
 //     </xsd:complexContent>
 // </xsd:complexType>
 import { IgnoreIfEmptyXmlComponent, OnOffElement } from "@file/xml-components";
+import { PositiveUniversalMeasure } from "@util/values";
 
 import { HeightRule, TableRowHeight } from "./table-row-height";
 
@@ -35,7 +36,7 @@ export interface ITableRowPropertiesOptions {
     readonly cantSplit?: boolean;
     readonly tableHeader?: boolean;
     readonly height?: {
-        readonly value: number | string;
+        readonly value: number | PositiveUniversalMeasure;
         readonly rule: HeightRule;
     };
 }

package/src/file/table/table-width.ts

@@ -1,6 +1,6 @@
 // http://officeopenxml.com/WPtableWidth.php
-import { XmlAttributeComponent, XmlComponent } from "@file/xml-components";
-import { measurementOrPercentValue } from "@util/values";
+import { NextAttributeComponent, XmlComponent } from "@file/xml-components";
+import { measurementOrPercentValue, Percentage, UniversalMeasure } from "@util/values";
 
 // <xsd:simpleType name="ST_TblWidth">
 //   <xsd:restriction base="xsd:string">
@@ -25,14 +25,10 @@ export enum WidthType {
 //     <xsd:attribute name="w" type="ST_MeasurementOrPercent"/>
 //     <xsd:attribute name="type" type="ST_TblWidth"/>
 // </xsd:complexType>
-export interface ITableWidthProperties {
-    readonly size: string | number;
+export type ITableWidthProperties = {
+    readonly size: number | Percentage | UniversalMeasure;
     readonly type?: WidthType;
-}
-
-class TableWidthAttributes extends XmlAttributeComponent<ITableWidthProperties> {
-    protected readonly xmlKeys = { type: "w:type", size: "w:w" };
-}
+};
 
 export class TableWidthElement extends XmlComponent {
     public constructor(name: string, { type = WidthType.AUTO, size }: ITableWidthProperties) {
@@ -42,6 +38,12 @@ export class TableWidthElement extends XmlComponent {
         if (type === WidthType.PERCENTAGE && typeof size === "number") {
             tableWidthValue = `${size}%`;
         }
-        this.root.push(new TableWidthAttributes({ type: type, size: measurementOrPercentValue(tableWidthValue) }));
+
+        this.root.push(
+            new NextAttributeComponent<ITableWidthProperties>({
+                type: { key: "w:type", value: type },
+                size: { key: "w:w", value: measurementOrPercentValue(tableWidthValue) },
+            }),
+        );
     }
 }

package/src/file/table/table.ts

@@ -1,5 +1,5 @@
 // http://officeopenxml.com/WPtableGrid.php
-import { XmlComponent } from "@file/xml-components";
+import { FileChild } from "@file/file-child";
 
 import { AlignmentType } from "../paragraph";
 import { TableGrid } from "./grid";
@@ -34,7 +34,7 @@ export interface ITableOptions {
     readonly visuallyRightToLeft?: boolean;
 }
 
-export class Table extends XmlComponent {
+export class Table extends FileChild {
     public constructor({
         rows,
         width,

package/src/file/table-of-contents/table-of-contents.ts

@@ -3,13 +3,13 @@
 import { Paragraph } from "@file/paragraph";
 import { Run } from "@file/paragraph/run";
 import { Begin, End, Separate } from "@file/paragraph/run/field";
-import { XmlComponent } from "@file/xml-components";
+import { FileChild } from "@file/file-child";
 import { FieldInstruction } from "./field-instruction";
 import { StructuredDocumentTagContent } from "./sdt-content";
 import { StructuredDocumentTagProperties } from "./sdt-properties";
 import { ITableOfContentsOptions } from "./table-of-contents-properties";
 
-export class TableOfContents extends XmlComponent {
+export class TableOfContents extends FileChild {
     public constructor(alias: string = "Table of Contents", properties?: ITableOfContentsOptions) {
         super("w:sdt");
         this.root.push(new StructuredDocumentTagProperties(alias));

package/src/file/xml-components/base.ts

@@ -5,6 +5,8 @@ import { IXmlableObject } from "./xmlable-object";
 export interface IContext {
     readonly file: File;
     readonly viewWrapper: IViewWrapper;
+    // eslint-disable-next-line functional/prefer-readonly-type
+    readonly stack: IXmlableObject[];
 }
 
 export abstract class BaseXmlComponent {

package/src/file/xml-components/default-attributes.ts

@@ -1,16 +1,16 @@
 import { BaseXmlComponent, IContext } from "./base";
-import { IXmlableObject } from "./xmlable-object";
+import { IXmlableObject, IXmlAttribute } from "./xmlable-object";
 
 export type AttributeMap<T> = { readonly [P in keyof T]: string };
 
+export type AttributeData = { readonly [key: string]: boolean | number | string };
+export type AttributePayload<T> = { readonly [P in keyof T]: { readonly key: string; readonly value: T[P] } };
+
 export abstract class XmlAttributeComponent<T extends object> extends BaseXmlComponent {
-    // tslint:disable-next-line:readonly-keyword
-    protected readonly root: T;
     protected readonly xmlKeys?: AttributeMap<T>;
 
-    public constructor(properties: T) {
+    public constructor(private readonly root: T) {
         super("_attr");
-        this.root = properties;
     }
 
     public prepForXml(_: IContext): IXmlableObject {
@@ -26,3 +26,16 @@ export abstract class XmlAttributeComponent<T extends object> extends BaseXmlCom
         return { _attr: attrs };
     }
 }
+
+export class NextAttributeComponent<T extends AttributeData> extends BaseXmlComponent {
+    public constructor(private readonly root: AttributePayload<T>) {
+        super("_attr");
+    }
+
+    public prepForXml(_: IContext): IXmlableObject {
+        const attrs = Object.values<{ readonly key: string; readonly value: string | boolean | number }>(this.root)
+            .filter(({ value }) => value !== undefined)
+            .reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {} as IXmlAttribute);
+        return { _attr: attrs };
+    }
+}

package/src/file/xml-components/imported-xml-component.spec.ts

@@ -62,7 +62,7 @@ describe("ImportedXmlComponent", () => {
     describe("#prepForXml()", () => {
         it("should transform for xml", () => {
             // tslint:disable-next-line: no-object-literal-type-assertion
-            const converted = importedXmlComponent.prepForXml({} as IContext);
+            const converted = importedXmlComponent.prepForXml({ stack: [] } as unknown as IContext);
             expect(converted).to.deep.equal({
                 "w:test": [
                     {

package/src/file/xml-components/simple-elements.spec.ts

@@ -0,0 +1,41 @@
+import { expect } from "chai";
+
+import { Formatter } from "@export/formatter";
+
+import { BuilderElement } from "./simple-elements";
+
+describe("BuilderElement", () => {
+    describe("#constructor()", () => {
+        it("should create a simple BuilderElement", () => {
+            const element = new BuilderElement({
+                name: "test",
+            });
+
+            const tree = new Formatter().format(element);
+            expect(tree).to.deep.equal({
+                test: {},
+            });
+        });
+
+        it("should create a simple BuilderElement with attributes", () => {
+            const element = new BuilderElement<{ readonly testAttr: string }>({
+                name: "test",
+                attributes: {
+                    testAttr: {
+                        key: "w:testAttr",
+                        value: "test",
+                    },
+                },
+            });
+
+            const tree = new Formatter().format(element);
+            expect(tree).to.deep.equal({
+                test: {
+                    _attr: {
+                        "w:testAttr": "test",
+                    },
+                },
+            });
+        });
+    });
+});

package/src/file/xml-components/simple-elements.ts

@@ -1,6 +1,6 @@
-import { Attributes, XmlComponent } from "@file/xml-components";
+import { AttributeData, AttributePayload, Attributes, NextAttributeComponent, XmlComponent } from "@file/xml-components";
 
-import { hpsMeasureValue } from "@util/values";
+import { hpsMeasureValue, PositiveUniversalMeasure } from "@util/values";
 
 // This represents element type CT_OnOff, which indicate a boolean value.
 //
@@ -26,8 +26,13 @@ export class OnOffElement extends XmlComponent {
 // <xsd:complexType name="CT_HpsMeasure">
 //     <xsd:attribute name="val" type="ST_HpsMeasure" use="required"/>
 // </xsd:complexType>
+
+// <xsd:simpleType name="ST_HpsMeasure">
+//     <xsd:union memberTypes="s:ST_UnsignedDecimalNumber s:ST_PositiveUniversalMeasure" />
+// </xsd:simpleType>
+
 export class HpsMeasureElement extends XmlComponent {
-    public constructor(name: string, val: number | string) {
+    public constructor(name: string, val: number | PositiveUniversalMeasure) {
         super(name);
         this.root.push(new Attributes({ val: hpsMeasureValue(val) }));
     }
@@ -35,6 +40,11 @@ export class HpsMeasureElement extends XmlComponent {
 
 // This represents element type CT_String, which indicate a string value.
 //
+// <xsd:complexType name="CT_Empty"/>
+export class EmptyElement extends XmlComponent {}
+
+// This represents element type CT_Empty, which indicate aan empty element.
+//
 // <xsd:complexType name="CT_String">
 //     <xsd:attribute name="val" type="s:ST_String" use="required"/>
 // </xsd:complexType>
@@ -70,3 +80,19 @@ export class StringContainer extends XmlComponent {
         this.root.push(val);
     }
 }
+
+export class BuilderElement<T extends AttributeData> extends XmlComponent {
+    public constructor(options: {
+        readonly name: string;
+        readonly attributes?: AttributePayload<T>;
+        readonly children?: readonly XmlComponent[];
+    }) {
+        super(options.name);
+
+        if (options.attributes) {
+            this.root.push(new NextAttributeComponent(options.attributes));
+        }
+
+        // TODO: Children
+    }
+}

package/src/file/xml-components/xml-component.ts

@@ -12,7 +12,15 @@ export abstract class XmlComponent extends BaseXmlComponent {
         this.root = new Array<BaseXmlComponent | string>();
     }
 
+    // This method is called by the formatter to get the XML representation of this component.
+    // It is called recursively for all child components.
+    // It is a serializer to be used in the xml library.
+    // https://www.npmjs.com/package/xml
+    // Child components can override this method to customize the XML representation, or execute side effects.
     public prepForXml(context: IContext): IXmlableObject | undefined {
+        // Mutating the stack is required for performance reasons
+        // eslint-disable-next-line functional/immutable-data
+        context.stack.push(this);
         const children = this.root
             .map((comp) => {
                 if (comp instanceof BaseXmlComponent) {
@@ -21,6 +29,9 @@ export abstract class XmlComponent extends BaseXmlComponent {
                 return comp;
             })
             .filter((comp) => comp !== undefined); // Exclude undefined
+
+        // eslint-disable-next-line functional/immutable-data
+        context.stack.pop();
         // If we only have a single IXmlableObject in our children array and it
         // represents our attributes, use the object itself as our children to
         // avoid an unneeded XML close element.

package/src/index.ts

@@ -3,5 +3,5 @@
 export { File as Document } from "./file";
 export * from "./file";
 export * from "./export";
-export * from "./import-dotx";
 export * from "./util";
+export * from "./patcher";

package/src/patcher/content-types-manager.spec.ts

@@ -0,0 +1,51 @@
+import { expect } from "chai";
+import { appendContentType } from "./content-types-manager";
+
+describe("content-types-manager", () => {
+    describe("appendContentType", () => {
+        it("should append a content type", () => {
+            const element = {
+                type: "element",
+                name: "xml",
+                elements: [
+                    {
+                        type: "element",
+                        name: "Types",
+                        elements: [
+                            {
+                                type: "element",
+                                name: "Default",
+                            },
+                        ],
+                    },
+                ],
+            };
+            appendContentType(element, "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml", "docx");
+
+            expect(element).to.deep.equal({
+                elements: [
+                    {
+                        elements: [
+                            {
+                                name: "Default",
+                                type: "element",
+                            },
+                            {
+                                attributes: {
+                                    ContentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml",
+                                    Extension: "docx",
+                                },
+                                name: "Default",
+                                type: "element",
+                            },
+                        ],
+                        name: "Types",
+                        type: "element",
+                    },
+                ],
+                name: "xml",
+                type: "element",
+            });
+        });
+    });
+});

package/src/patcher/content-types-manager.ts

@@ -0,0 +1,16 @@
+import { Element } from "xml-js";
+
+import { getFirstLevelElements } from "./util";
+
+export const appendContentType = (element: Element, contentType: string, extension: string): void => {
+    const relationshipElements = getFirstLevelElements(element, "Types");
+    // eslint-disable-next-line functional/immutable-data
+    relationshipElements.push({
+        attributes: {
+            ContentType: contentType,
+            Extension: extension,
+        },
+        name: "Default",
+        type: "element",
+    });
+};