docx-kit 0.0.0 → 0.1.0

package/dist/node.d.ts

@@ -0,0 +1,77 @@
+import { Document } from "docx";
+
+//#region src/node/fs.d.ts
+/**
+ * Save a compiled document to a file on disk.
+ *
+ * Uses `Packer.toBuffer()` to produce the .docx binary, then
+ * writes via `node:fs/promises`. This function is **Node.js only**.
+ *
+ * @param doc - — A compiled `docx` `Document` instance
+ * @param filename - — Output file path (e.g. `"report.docx"`)
+ *
+ * @example
+ * ```ts
+ * import { saveDocument } from 'docx-kit/node'
+ *
+ * const doc = await compileDocument({ ... })
+ * await saveDocument(doc, 'report.docx')
+ * ```
+ */
+declare function saveDocument(doc: Document, filename: string): Promise<void>;
+//#endregion
+//#region src/node/dataUrl.d.ts
+/**
+ * Node.js base64 data-URL decoder (uses `Buffer` from `node:buffer`).
+ *
+ * @module node/dataUrl
+ */
+/**
+ * Decode a base64 data-URL to raw bytes using Node.js `Buffer`.
+ *
+ * Strips the `"data:*;base64,"` prefix and decodes via
+ * `Buffer.from(base64, 'base64')`.
+ *
+ * @param dataUrl - — A base64 data-URI string (e.g. `"data:image/png;base64,iVBO..."`)
+ * @returns Raw bytes as `Uint8Array`
+ *
+ * @example
+ * ```ts
+ * import { dataUrlToUint8Array } from 'docx-kit/node'
+ *
+ * const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
+ * ```
+ */
+declare function dataUrlToUint8Array(dataUrl: string): Promise<Uint8Array>;
+//#endregion
+//#region src/node.d.ts
+/**
+ * ### ❌ `echartsPlugin()` — Not available in Node.js
+ *
+ * The ECharts plugin requires a browser `window` and `document` to
+ * render charts into a DOM container. Node.js has no native DOM.
+ *
+ * **Workarounds:**
+ * - Use a server-side canvas library (e.g. `node-canvas` + `echarts`)
+ * - Pre-render charts on the client and pass the image data to docx-kit
+ *
+ * @deprecated This API is not available in Node.js. See workarounds above.
+ */
+declare const echartsPlugin: never;
+/**
+ * ### ❌ `normalizeImageData()` — Not built-in for Node.js
+ *
+ * This utility converts `Blob` instances to `Uint8Array`. While `Blob`
+ * is available in Node.js ≥ 18, it is rarely the carrier for image data
+ * in Node workflows (most users work with `Buffer` or file paths directly).
+ *
+ * If you need Blob→Uint8Array in Node.js, use:
+ * ```ts
+ * const bytes = new Uint8Array(await blob.arrayBuffer())
+ * ```
+ *
+ * @deprecated Use inline `new Uint8Array(await blob.arrayBuffer())` instead.
+ */
+declare const normalizeImageData: never;
+//#endregion
+export { dataUrlToUint8Array, echartsPlugin, normalizeImageData, saveDocument };

package/dist/node.js

@@ -0,0 +1,30 @@
+import { n as saveDocument } from "./fs-DF8ug9Wi.js";
+//#region src/node/dataUrl.ts
+/**
+* Node.js base64 data-URL decoder (uses `Buffer` from `node:buffer`).
+*
+* @module node/dataUrl
+*/
+/**
+* Decode a base64 data-URL to raw bytes using Node.js `Buffer`.
+*
+* Strips the `"data:*;base64,"` prefix and decodes via
+* `Buffer.from(base64, 'base64')`.
+*
+* @param dataUrl - — A base64 data-URI string (e.g. `"data:image/png;base64,iVBO..."`)
+* @returns Raw bytes as `Uint8Array`
+*
+* @example
+* ```ts
+* import { dataUrlToUint8Array } from 'docx-kit/node'
+*
+* const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
+* ```
+*/
+async function dataUrlToUint8Array(dataUrl) {
+	const { Buffer } = await import("node:buffer");
+	const base64 = dataUrl.split(",")[1];
+	return new Uint8Array(Buffer.from(base64, "base64"));
+}
+//#endregion
+export { dataUrlToUint8Array, saveDocument };

package/dist/pack-0Jsv03Sk.js

@@ -0,0 +1,79 @@
+import "./fs-DF8ug9Wi.js";
+import { t as DocxKitError } from "./errors-c9CC63Ti.js";
+import { Packer } from "docx";
+//#region src/renderer/pack.ts
+/**
+* Document packaging — converts a `docx` `Document` instance to
+* various output formats (Blob, Buffer, base64, file).
+*
+* These are thin wrappers around the `docx` `Packer` API, with
+* normalization for cross-platform compatibility.
+*
+* @module renderer/pack
+*/
+/**
+* Pack a document to a base64-encoded string.
+*
+* @param doc - — A compiled `docx` `Document` instance
+* @returns Base64-encoded .docx data
+*
+* @example
+* ```ts
+* const doc = await compileDocument({ ... })
+* const b64 = await packToBase64String(doc)
+* ```
+*/
+async function packToBase64String(doc) {
+	try {
+		return await Packer.toBase64String(doc);
+	} catch (err) {
+		throw new DocxKitError("EXPORT_FAILED", "Failed to pack document to base64", err);
+	}
+}
+/**
+* Pack a document to a `Blob` (browser-friendly).
+*
+* @param doc - — A compiled `docx` `Document` instance
+* @returns A `Blob` containing the .docx binary
+*
+* @example
+* ```ts
+* const blob = await packToBlob(doc)
+* const url = URL.createObjectURL(blob)
+* // trigger download in browser
+* ```
+*/
+async function packToBlob(doc) {
+	try {
+		return await Packer.toBlob(doc);
+	} catch (err) {
+		throw new DocxKitError("EXPORT_FAILED", "Failed to pack document to blob", err);
+	}
+}
+/**
+* Pack a document to a `Uint8Array` (browser & Node.js).
+*
+* Normalizes the `Packer.toBuffer()` Node.js Buffer to a
+* standard `Uint8Array` for cross-platform compatibility.
+*
+* @param doc - — A compiled `docx` `Document` instance
+* @returns Raw .docx bytes as `Uint8Array`
+*
+* @example
+* ```ts
+* const bytes = await packToBuffer(doc)
+* // In Node.js:
+* import { writeFileSync } from 'node:fs'
+* writeFileSync('output.docx', bytes)
+* ```
+*/
+async function packToBuffer(doc) {
+	try {
+		const buffer = await Packer.toBuffer(doc);
+		return new Uint8Array(buffer);
+	} catch (err) {
+		throw new DocxKitError("EXPORT_FAILED", "Failed to pack document to buffer", err);
+	}
+}
+//#endregion
+export { packToBase64String, packToBlob, packToBuffer };

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "docx-kit",
   "type": "module",
-  "version": "0.0.0",
-  "packageManager": "pnpm@10.27.0",
-  "description": "TypeScript library for generating Word (.docx) documents easily with rich content, styles, and intuitive, customizable API.",
+  "version": "0.1.0",
+  "description": "CSS-like DOCX API Kit — a type-safe, plugin-extensible DOCX generation library built on dolanmiu/docx.",
   "keywords": [
     "document",
     "docx",
@@ -20,7 +19,10 @@
     "email": "ntnyq13@gmail.com"
   },
   "homepage": "https://github.com/ntnyq/docx-kit#readme",
-  "repository": "ntnyq/docx-kit",
+  "repository": {
+    "type": "git",
+    "url": "ntnyq/docx-kit"
+  },
   "bugs": {
     "url": "https://github.com/ntnyq/docx-kit/issues"
   },
@@ -29,6 +31,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
     }
   },
   "main": "./dist/index.js",
@@ -40,40 +50,53 @@
     "access": "public"
   },
   "sideEffects": false,
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "lint": "eslint",
-    "prepare": "husky",
-    "prepublishOnly": "pnpm run build",
-    "release": "run-s release:check release:version",
-    "release:check": "run-s lint typecheck test",
-    "release:version": "bumpp",
-    "test": "vitest",
-    "typecheck": "tsc --noEmit"
+  "peerDependencies": {
+    "echarts": ">=5.0.0",
+    "qrcode": ">=1.5.0"
+  },
+  "peerDependenciesMeta": {
+    "echarts": {
+      "optional": true
+    },
+    "qrcode": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@ntnyq/utils": "^0.10.0",
-    "docx": "^9.5.1",
-    "echarts": "^6.0.0",
-    "qrcode": "^1.5.4"
+    "docx": "^9.7.1"
   },
   "devDependencies": {
-    "@ntnyq/eslint-config": "^5.9.0",
+    "@ntnyq/eslint-config": "^6.1.5",
     "@ntnyq/prettier-config": "^3.0.1",
-    "@types/node": "^25.0.3",
-    "bumpp": "^10.3.2",
-    "eslint": "^9.39.2",
+    "@types/node": "^25.9.2",
+    "@types/qrcode": "^1.5.6",
+    "bumpp": "^11.1.0",
+    "echarts": "^6.1.0",
+    "eslint": "^10.4.1",
     "husky": "^9.1.7",
-    "nano-staged": "^0.9.0",
-    "npm-run-all2": "^8.0.4",
-    "prettier": "^3.7.4",
-    "tsdown": "^0.19.0-beta.2",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "nano-staged": "^1.0.2",
+    "npm-run-all2": "^9.0.1",
+    "prettier": "^3.8.4",
+    "qrcode": "^1.5.4",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.8"
   },
   "nano-staged": {
     "*.{js,ts,mjs,cjs,md,vue,yml,yaml,toml,json}": "eslint --fix",
     "*.{css,scss,html}": "prettier -uw"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "docs:build": "pnpm -C docs run build",
+    "docs:dev": "pnpm -C docs run dev",
+    "lint": "eslint",
+    "release": "run-s release:check release:version",
+    "release:check": "run-s lint typecheck test",
+    "release:version": "bumpp",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
   }
-}
+}