export IPropertiesOptions for use by other libraries or code using docx library (#2979)

* export IPropertiesOptions for use by other libraries or code using docx library

* fixes #2978: export OutputTypes

* Export file in main index file

* Move type export to inside

---------

Co-authored-by: Dolan Miu <dolan_miu@hotmail.com>

README.md

@@ -14,6 +14,7 @@
 [![Known Vulnerabilities][snky-image]][snky-url]
 [![PRs Welcome][pr-image]][pr-url]
 [![codecov][codecov-image]][codecov-url]
+[![Docx.js Editor][docxjs-editor-image]][docxjs-editor-url]
 
 <p align="center">
     <img src="https://i.imgur.com/QeL1HuU.png" alt="drawing"/>
@@ -64,6 +65,10 @@ More [here](https://github.com/dolanmiu/docx/tree/master/demo)
 
 Please refer to the [documentation at https://docx.js.org/](https://docx.js.org/) for details on how to use this library, examples and much more!
 
+# Playground
+
+Experience `docx` in action through [Docx.js Editor][docxjs-editor-url], an interactive playground where you can code and preview the results in real-time.
+
 # Examples
 
 Check the [demo folder](https://github.com/dolanmiu/docx/tree/master/demo) for examples.
@@ -115,3 +120,5 @@ Made with 💖
 [patreon-url]: https://www.patreon.com/dolanmiu
 [browserstack-image]: https://user-images.githubusercontent.com/2917613/54233552-128e9d00-4505-11e9-88fb-025a4e04007c.png
 [browserstack-url]: https://www.browserstack.com
+[docxjs-editor-image]: https://img.shields.io/badge/Docx.js%20Editor-2b579a.svg?style=flat&amp;logo=javascript&amp;logoColor=white
+[docxjs-editor-url]: https://docxjs-editor.vercel.app/

docs/usage/packers.md

@@ -2,7 +2,7 @@
 
 > Packers are the way in which `docx` turns your code into `.docx` format. It is completely decoupled from the `docx.Document`.
 
-Packers works in both a node and browser environment (Angular etc). Now, the packer returns a `Buffer`, `Blob`, `string`, `base64 string`, or `Stream`. It is up to you to take that and persist it with node's `fs`, send it down as a downloadable file, or anything else you wish. As of `version 4+`, this library will not have options to export to PDF.
+Packers works in both a node and browser environment (Angular etc). Now, the packer returns a `Buffer`, `Blob`, `string`, `base64 string`, `ArrayBuffer`, or `Stream`. It is up to you to take that and persist it with node's `fs`, send it down as a downloadable file, or anything else you wish. As of `version 4+`, this library will not have options to export to PDF.
 
 ### Export as Buffer
 
@@ -41,6 +41,16 @@ Packer.toBlob(doc).then((blob) => {
 });
 ```
 
+### Export as ArrayBuffer
+
+This may be useful when working in a Node.js worker.
+
+```ts
+Packer.toArrayBuffer(doc).then((arrayBuffer) => {
+    port.postMessage(arrayBuffer, [arrayBuffer]);
+});
+```
+
 ### Export as a Stream
 
 ```ts
@@ -63,3 +73,13 @@ Packer.toString(doc, true, overrides).then((string) => {
     console.log(string);
 });
 ```
+
+### Export to arbitrary formats
+
+You can also use the lower-level `Packer.pack` method to export to any specified type.
+
+```ts
+Packer.pack(doc, 'string').then((string) => {
+    console.log(string);
+});
+```

package.json

@@ -61,7 +61,7 @@
         "@types/node": "^22.7.5",
         "hash.js": "^1.1.7",
         "jszip": "^3.10.1",
-        "nanoid": "^5.0.4",
+        "nanoid": "^5.1.3",
         "xml": "^1.0.1",
         "xml-js": "^1.6.8"
     },
@@ -79,8 +79,8 @@
         "@types/xml": "^1.0.8",
         "@typescript-eslint/eslint-plugin": "^8.8.1",
         "@typescript-eslint/parser": "^8.8.1",
-        "@vitest/coverage-v8": "^2.1.8",
-        "@vitest/ui": "^2.1.2",
+        "@vitest/coverage-v8": "^3.0.8",
+        "@vitest/ui": "^3.0.8",
         "cspell": "^8.2.3",
         "docsify-cli": "^4.3.0",
         "eslint": "^9.13.0",
@@ -95,7 +95,7 @@
         "glob": "^11.0.0",
         "inquirer": "^12.0.0",
         "jiti": "^2.3.3",
-        "jsdom": "^25.0.1",
+        "jsdom": "^26.0.0",
         "pre-commit": "^1.2.2",
         "prettier": "^3.1.1",
         "tsconfig-paths": "^4.0.0",
@@ -106,9 +106,9 @@
         "unzipper": "^0.12.3",
         "vite": "^6.0.1",
         "vite-plugin-dts": "^4.2.4",
-        "vite-plugin-node-polyfills": "^0.22.0",
+        "vite-plugin-node-polyfills": "^0.23.0",
         "vite-tsconfig-paths": "^5.0.1",
-        "vitest": "^2.1.8"
+        "vitest": "^3.0.8"
     },
     "engines": {
         "node": ">=10"

src/file/index.ts

@@ -21,3 +21,4 @@ export * from "./vertical-align";
 export * from "./checkbox";
 export * from "./fonts";
 export * from "./textbox";
+export { type IPropertiesOptions } from "./core-properties";

src/file/paragraph/formatting/spacing.ts

@@ -24,7 +24,7 @@ class SpacingAttributes extends XmlAttributeComponent<ISpacingProperties> {
         line: "w:line",
         lineRule: "w:lineRule",
         beforeAutoSpacing: "w:beforeAutospacing",
-        afterAutoSpacing: "w:afterAutoSpacing",
+        afterAutoSpacing: "w:afterAutospacing",
     };
 }
 

src/file/paragraph/math/bar/index.ts

@@ -0,0 +1,2 @@
+export * from "./math-bar";
+export * from "./math-bar-properties";

src/file/paragraph/math/bar/math-bar-pos.ts

@@ -0,0 +1,11 @@
+// https://www.datypic.com/sc/ooxml/e-m_pos-1.html
+import { Attributes, XmlComponent } from "@file/xml-components";
+
+export class MathBarPos extends XmlComponent {
+    // TODO: Use correct types rather than any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    public constructor(attributes: any) {
+        super("m:pos");
+        this.root.push(new Attributes(attributes));
+    }
+}

src/file/paragraph/math/bar/math-bar-properties.spec.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+
+import { Formatter } from "@export/formatter";
+
+import { MathBarProperties } from "./math-bar-properties";
+describe("MathBarProperties", () => {
+    describe("#constructor()", () => {
+        it("should create a MathBarProperties with top key", () => {
+            const mathBarProperties = new MathBarProperties("top");
+
+            const tree = new Formatter().format(mathBarProperties);
+
+            expect(tree).to.deep.equal({
+                "m:barPr": [
+                    {
+                        "m:pos": {
+                            _attr: {
+                                "w:val": "top",
+                            },
+                        },
+                    },
+                ],
+            });
+        });
+        it("should create a MathBarProperties with bottom key", () => {
+            const mathBarProperties = new MathBarProperties("bot");
+
+            const tree = new Formatter().format(mathBarProperties);
+
+            expect(tree).to.deep.equal({
+                "m:barPr": [
+                    {
+                        "m:pos": {
+                            _attr: {
+                                "w:val": "bot",
+                            },
+                        },
+                    },
+                ],
+            });
+        });
+    });
+});

src/file/paragraph/math/bar/math-bar-properties.ts

@@ -0,0 +1,11 @@
+// https://www.datypic.com/sc/ooxml/e-m_barPr-1.html
+import { XmlComponent } from "@file/xml-components";
+
+import { MathBarPos } from "./math-bar-pos";
+
+export class MathBarProperties extends XmlComponent {
+    public constructor(type: string) {
+        super("m:barPr");
+        this.root.push(new MathBarPos({ val: type }));
+    }
+}

src/file/paragraph/math/bar/math-bar.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+
+import { Formatter } from "@export/formatter";
+
+import { MathBar } from "./math-bar";
+import { MathRun } from "../math-run";
+
+describe("MathBar", () => {
+    describe("#constructor()", () => {
+        it("should create a MathBar with correct root key", () => {
+            const mathBar = new MathBar({ type: "top", children: [new MathRun("text")] });
+            const tree = new Formatter().format(mathBar);
+
+            expect(tree).to.deep.equal({
+                "m:bar": [
+                    {
+                        "m:barPr": [
+                            {
+                                "m:pos": {
+                                    _attr: {
+                                        "w:val": "top",
+                                    },
+                                },
+                            },
+                        ],
+                    },
+                    {
+                        "m:e": [
+                            {
+                                "m:r": [{ "m:t": ["text"] }],
+                            },
+                        ],
+                    },
+                ],
+            });
+        });
+    });
+});

src/file/paragraph/math/bar/math-bar.ts

@@ -0,0 +1,18 @@
+// https://www.datypic.com/sc/ooxml/e-m_bar-1.html
+import { XmlComponent } from "@file/xml-components";
+
+import { MathBarProperties } from "./math-bar-properties";
+import type { MathComponent } from "../math-component";
+import { MathBase } from "../n-ary";
+
+type MathBarOption = {
+    readonly type: "top" | "bot";
+    readonly children: readonly MathComponent[];
+};
+export class MathBar extends XmlComponent {
+    public constructor(options: MathBarOption) {
+        super("m:bar");
+        this.root.push(new MathBarProperties(options.type));
+        this.root.push(new MathBase(options.children));
+    }
+}

src/file/paragraph/math/script/pre-sub-super-script/math-pre-sub-super-script-function.ts

@@ -2,7 +2,7 @@
 import { XmlComponent } from "@file/xml-components";
 
 import { MathPreSubSuperScriptProperties } from "./math-pre-sub-super-script-function-properties";
-import { MathComponent } from "../../math-component";
+import type { MathComponent } from "../../math-component";
 import { MathBase, MathSubScriptElement, MathSuperScriptElement } from "../../n-ary";
 
 export type IMathPreSubSuperScriptOptions = {

src/util/index.ts

@@ -1,2 +1,3 @@
 export * from "./convenience-functions";
 export * from "./values";
+export type * from "./output-type";