docx-kit 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,683 +0,0 @@
-import { n as ERROR_CODES, t as DocxKitError } from "./errors-c9CC63Ti.js";
-import { n as dataUrlToUint8Array, t as createImageRun } from "./image-6yS25Ggr.js";
-import { Paragraph } from "docx";
-//#region src/types/style.ts
-/**
-* Define a type-safe stylesheet.
-*
-* `fontSize` defaults to pt when passed as a bare number.
-*
-* @param styles - — The stylesheet object
-* @returns The same stylesheet with `const` type inference
-*
-* @example
-* ```ts
-* const styles = defineStyles({
-*   title: { fontSize: 28, fontWeight: 'bold' },
-*   body:  { fontSize: 12, lineHeight: 1.5 },
-* })
-* ```
-*/
-function defineStyles(styles) {
-	return styles;
-}
-//#endregion
-//#region src/types/plugin.ts
-/**
-* Define a type-safe plugin with full inference.
-*
-* @param plugin - — The plugin definition object
-* @returns The same plugin with `const` type inference
-*
-* @example
-* ```ts
-* const myPlugin = definePlugin<'badge', { text: string }>({
-*   name: 'badge',
-*   render: async (opts, ctx) => {
-*     // ... render logic
-*     return new Paragraph({ text: opts.text })
-*   },
-* })
-* ```
-*/
-function definePlugin(plugin) {
-	return plugin;
-}
-//#endregion
-//#region src/builder/DocxBuilder.ts
-/**
-* Fluent document builder.
-*
-* Use `createDocx()` to instantiate, then chain `.h1()`, `.p()`, `.table()`,
-* etc. to build content. Call `.save()`, `.toBlob()`, `.toBuffer()`, or
-* `.toBase64()` to export the document.
-*
-* @template TStyles — Inferred stylesheet type from `config.styles`
-* @template TPlugins — Accumulated plugin registry (built via `.use()`)
-*/
-var DocxBuilder = class {
-	config;
-	nodes = [];
-	pendingSetups = [];
-	pluginMap = /* @__PURE__ */ new Map();
-	constructor(config = {}) {
-		this.config = config;
-	}
-	/**
-	* Add a raw DSL node to the document.
-	*
-	* @param node - — Any block-level node
-	* @returns The builder (for chaining)
-	*
-	* @example
-	* ```ts
-	* doc.add({ type: 'heading', level: 2, text: 'Section' })
-	* doc.add({ type: 'pageBreak' })
-	* ```
-	*/
-	add(node) {
-		this.nodes.push(node);
-		return this;
-	}
-	/**
-	* Add a level-1 heading.
-	*
-	* @param text - — Heading text
-	* @param options - — Optional style overrides (className, id, style)
-	* @returns The builder (for chaining)
-	*
-	* @example
-	* ```ts
-	* doc.h1('Introduction', { className: 'title' })
-	* ```
-	*/
-	h1(text, options = {}) {
-		return this.add({
-			level: 1,
-			text,
-			type: "heading",
-			...options
-		});
-	}
-	/**
-	* Add a level-2 heading.
-	*
-	* @param text - — Heading text
-	* @param options - — Optional style overrides
-	* @returns The builder (for chaining)
-	*/
-	h2(text, options = {}) {
-		return this.add({
-			level: 2,
-			text,
-			type: "heading",
-			...options
-		});
-	}
-	/**
-	* Add a level-3 heading.
-	*
-	* @param text - — Heading text
-	* @param options - — Optional style overrides
-	* @returns The builder (for chaining)
-	*/
-	h3(text, options = {}) {
-		return this.add({
-			level: 3,
-			text,
-			type: "heading",
-			...options
-		});
-	}
-	/**
-	* Add a level-4 heading.
-	*
-	* @param text - — Heading text
-	* @param options - — Optional style overrides
-	* @returns The builder (for chaining)
-	*/
-	h4(text, options = {}) {
-		return this.add({
-			level: 4,
-			text,
-			type: "heading",
-			...options
-		});
-	}
-	/**
-	* Add a level-5 heading.
-	*
-	* @param text - — Heading text
-	* @param options - — Optional style overrides
-	* @returns The builder (for chaining)
-	*/
-	h5(text, options = {}) {
-		return this.add({
-			level: 5,
-			text,
-			type: "heading",
-			...options
-		});
-	}
-	/**
-	* Add a level-6 heading.
-	*
-	* @param text - — Heading text
-	* @param options - — Optional style overrides
-	* @returns The builder (for chaining)
-	*/
-	h6(text, options = {}) {
-		return this.add({
-			level: 6,
-			text,
-			type: "heading",
-			...options
-		});
-	}
-	/**
-	* Add an image node.
-	*
-	* @param options - — Image node options (data, width, height, etc.)
-	* @returns The builder (for chaining)
-	*
-	* @example
-	* ```ts
-	* doc.image({ data: imageBytes, width: 400, height: 300 })
-	* ```
-	*/
-	image(options) {
-		return this.add({
-			type: "image",
-			...options
-		});
-	}
-	/**
-	* Add a paragraph.
-	*
-	* @param text - — Paragraph text content
-	* @param options - — Optional style overrides (className, id, style)
-	* @returns The builder (for chaining)
-	*
-	* @example
-	* ```ts
-	* doc.p('Hello world', { className: 'body', style: { textAlign: 'center' } })
-	* ```
-	*/
-	p(text, options = {}) {
-		return this.add({
-			text,
-			type: "paragraph",
-			...options
-		});
-	}
-	/**
-	* Add a forced page break.
-	*
-	* @returns The builder (for chaining)
-	*
-	* @example
-	* ```ts
-	* doc.h1('Chapter 1').pageBreak().h1('Chapter 2')
-	* ```
-	*/
-	pageBreak() {
-		return this.add({ type: "pageBreak" });
-	}
-	/**
-	* Invoke a registered plugin.
-	*
-	* @param name - — Plugin name (must match a previously registered plugin)
-	* @param options - — Plugin-specific options
-	* @param style - — Optional inline style for the plugin's container
-	* @returns The builder (for chaining)
-	*
-	* @example
-	* ```ts
-	* doc.use(qrcodePlugin()).plugin('qrcode', { text: 'https://example.com' })
-	* ```
-	*/
-	plugin(name, options, style) {
-		return this.add({
-			name,
-			options,
-			style,
-			type: "plugin"
-		});
-	}
-	/**
-	* Save the document to a file (Node.js only).
-	*
-	* **⚠️ Not available in browser environments.**
-	* Use {@link toBlob} and trigger a download instead.
-	*
-	* @param filename - — Output file path (e.g. `"report.docx"`)
-	*
-	* @example
-	* ```ts
-	* await doc.save('output.docx')
-	* ```
-	*/
-	async save(filename) {
-		const { saveDocument } = await import("./fs-DF8ug9Wi.js").then((n) => n.t);
-		return saveDocument(await this.toDocument(), filename);
-	}
-	/**
-	* Add a table.
-	*
-	* @param options - — Table node options (columns, data, style, etc.)
-	* @returns The builder (for chaining)
-	*
-	* @example
-	* ```ts
-	* doc.table({
-	*   columns: [
-	*     { key: 'name', title: 'Name' },
-	*     { key: 'value', title: 'Value', align: 'right' },
-	*   ],
-	*   data: [{ name: 'Revenue', value: '$1.2M' }],
-	*   headerCellStyle: { fontWeight: 'bold' },
-	* })
-	* ```
-	*/
-	table(options) {
-		return this.add({
-			type: "table",
-			...options
-		});
-	}
-	/**
-	* Export the document as a base64-encoded string.
-	*
-	* @returns Base64-encoded .docx data
-	*
-	* @example
-	* ```ts
-	* const b64 = await doc.toBase64()
-	* // Send b64 over HTTP or store in a database
-	* ```
-	*/
-	async toBase64() {
-		const { packToBase64String } = await import("./pack-0Jsv03Sk.js");
-		return packToBase64String(await this.toDocument());
-	}
-	/**
-	* Export the document as a `Blob` (browser-friendly).
-	*
-	* @returns A `Blob` containing the .docx binary
-	*
-	* @example
-	* ```ts
-	* const blob = await doc.toBlob()
-	* const url = URL.createObjectURL(blob)
-	* ```
-	*/
-	async toBlob() {
-		const { packToBlob } = await import("./pack-0Jsv03Sk.js");
-		return packToBlob(await this.toDocument());
-	}
-	/**
-	* Export the document as a `Uint8Array` (alias for {@link toUint8Array}).
-	*
-	* **Note:** Despite the name, this returns a standard `Uint8Array`,
-	* not a Node.js `Buffer`. Prefer using {@link toUint8Array} for clarity.
-	*
-	* @returns Raw .docx bytes
-	*
-	* @example
-	* ```ts
-	* const bytes = await doc.toBuffer()
-	* fs.writeFileSync('output.docx', bytes)
-	* ```
-	*/
-	async toBuffer() {
-		return this.toUint8Array();
-	}
-	/**
-	* Compile and return the internal `docx` {@link Document} instance.
-	*
-	* Useful if you need to further manipulate the document with the
-	* raw `docx` library before packaging.
-	*
-	* @returns A `docx` `Document` object
-	*/
-	async toDocument() {
-		await Promise.all(this.pendingSetups);
-		this.pendingSetups.length = 0;
-		const { compileDocument } = await import("./compileDocument-BvuU28Yj.js");
-		return compileDocument({
-			config: this.config,
-			nodes: this.nodes,
-			plugins: this.pluginMap
-		});
-	}
-	/**
-	* Serialize the builder state to a JSON-friendly object.
-	*
-	* Useful for debugging, serialization, or AI-driven document generation.
-	*
-	* @returns The config + content node array as a plain object
-	*/
-	toJSON() {
-		return {
-			...this.config,
-			content: this.nodes
-		};
-	}
-	/**
-	* Export the document as a `Uint8Array` (browser & Node.js).
-	*
-	* This is the preferred cross-platform export method.
-	*
-	* @returns Raw .docx bytes
-	*
-	* @example
-	* ```ts
-	* const bytes = await doc.toUint8Array()
-	* // In Node.js: import { writeFileSync } from 'node:fs'
-	* // In browser: trigger a download
-	* ```
-	*/
-	async toUint8Array() {
-		const { packToBuffer } = await import("./pack-0Jsv03Sk.js");
-		return packToBuffer(await this.toDocument());
-	}
-	/**
-	* Register a plugin.
-	*
-	* The plugin's name and options type are accumulated into the builder's
-	* type-level plugin registry, enabling type-safe `.plugin()` calls.
-	*
-	* @param plugin - — The plugin definition returned by `definePlugin()`
-	* @returns The builder with the plugin type merged into `TPlugins`
-	*
-	* @example
-	* ```ts
-	* const doc = createDocx()
-	*   .use(qrcodePlugin())
-	*   .plugin('qrcode', { text: 'https://example.com' })
-	* ```
-	*/
-	use(plugin) {
-		this.pluginMap.set(plugin.name, plugin);
-		if (plugin.setup) this.pendingSetups.push(Promise.resolve(plugin.setup()));
-		return this;
-	}
-};
-//#endregion
-//#region src/plugins/qrcode/index.ts
-/**
-* QR Code plugin — embeds a QR code image in the document.
-*
-* Uses the `qrcode` package (peer dependency) to generate
-* a QR code PNG and renders it as an inline `ImageRun`.
-*
-* @module plugins/qrcode
-*
-* @example
-* ```ts
-* const doc = createDocx()
-*   .use(qrcodePlugin())
-*   .h1('Scan Me')
-*   .plugin('qrcode', { text: 'https://example.com', caption: 'Visit us' })
-*   .save('qrcode.docx')
-* ```
-*/
-/**
-* Create a QRCode plugin instance.
-*
-* The plugin dynamically imports the `qrcode` package at render time,
-* keeping it an optional peer dependency of docx-kit core.
-*
-* @returns A configured DocxPlugin for `'qrcode'`
-*
-* @example
-* ```ts
-* import { createDocx, qrcodePlugin } from 'docx-kit'
-*
-* const doc = createDocx()
-*   .use(qrcodePlugin())
-*   .plugin('qrcode', {
-*     text: 'https://example.com',
-*     size: 256,
-*     errorCorrectionLevel: 'H',
-*     caption: 'Scan to visit',
-*   })
-* ```
-*/
-function qrcodePlugin() {
-	return definePlugin({
-		name: "qrcode",
-		async render(options) {
-			const QRCode = (await import("qrcode")).default ?? await import("qrcode");
-			const size = options.size ?? 128;
-			const paragraphs = [new Paragraph({ children: [createImageRun({
-				data: await dataUrlToUint8Array(await QRCode.toDataURL(options.text, {
-					errorCorrectionLevel: options.errorCorrectionLevel ?? "M",
-					margin: options.margin ?? 1,
-					width: size
-				})),
-				height: size,
-				type: "png",
-				width: size
-			})] })];
-			if (options.caption) paragraphs.push(new Paragraph({ text: options.caption }));
-			return paragraphs;
-		}
-	});
-}
-//#endregion
-//#region src/plugins/echarts/index.ts
-/**
-* ECharts plugin — embeds interactive ECharts charts as static images.
-*
-* Renders charts in the browser via the DOM. For Node.js rendering,
-* a custom canvas/SVG implementation is needed (not built-in).
-*
-* @module plugins/echarts
-*
-* @example
-* ```ts
-* const doc = createDocx()
-*   .use(echartsPlugin())
-*   .h1('Sales Chart')
-*   .plugin('echarts', {
-*     option: {
-*       title: { text: 'Monthly Sales' },
-*       xAxis: { data: ['Jan', 'Feb', 'Mar'] },
-*       yAxis: {},
-*       series: [{ type: 'bar', data: [120, 200, 150] }],
-*     },
-*     width: 640,
-*     height: 360,
-*     caption: 'Figure 1: Monthly sales data',
-*   })
-*   .save('chart.docx')
-* ```
-*/
-/**
-* Create an ECharts plugin instance.
-*
-* The plugin renders charts using the browser DOM. In Node.js
-* environments, it throws an error prompting the user to provide
-* a server-side canvas implementation.
-*
-* @returns A configured DocxPlugin for `'echarts'`
-*
-* @example
-* ```ts
-* import { createDocx, echartsPlugin } from 'docx-kit'
-*
-* const doc = createDocx()
-*   .use(echartsPlugin())
-*   .plugin('echarts', {
-*     option: {
-*       title: { text: 'Revenue' },
-*       xAxis: { type: 'category', data: ['Q1', 'Q2', 'Q3', 'Q4'] },
-*       yAxis: { type: 'value' },
-*       series: [{ data: [820, 932, 901, 1347], type: 'line' }],
-*     },
-*     caption: 'Quarterly revenue trend',
-*   })
-* ```
-*/
-function echartsPlugin() {
-	return definePlugin({
-		name: "echarts",
-		async render(options) {
-			const width = options.width ?? 640;
-			const height = options.height ?? 360;
-			const imageType = options.imageType ?? "png";
-			const renderer = options.renderer ?? "canvas";
-			const image = await renderEChartsToImage(options.option, {
-				height,
-				imageType,
-				renderer,
-				width
-			});
-			const paragraphs = [new Paragraph({ children: [createImageRun({
-				data: image.data,
-				height,
-				type: image.type,
-				width
-			})] })];
-			if (options.caption) paragraphs.push(new Paragraph({ text: options.caption }));
-			return paragraphs;
-		}
-	});
-}
-/**
-* Render an ECharts option to an image.
-*
-* Automatically selects browser or Node.js rendering based on
-* whether the `window` global is available.
-*
-* @param option - — Full ECharts option object
-* @param config - — Render dimensions and format
-* @returns Rendered image data and type
-*/
-async function renderEChartsToImage(option, config) {
-	if (typeof window !== "undefined") return renderInBrowser(option, config);
-	return renderInNode(option, config);
-}
-/**
-* Browser-side ECharts rendering.
-*
-* Creates a hidden DOM container, renders the chart, and extracts
-* the image as a base64 data-URL.
-*/
-async function renderInBrowser(option, config) {
-	const echarts = await import("echarts");
-	const container = document.createElement("div");
-	container.style.cssText = `width:${config.width}px;height:${config.height}px;position:fixed;left:-99999px;`;
-	document.body.append(container);
-	const chart = echarts.init(container, void 0, {
-		height: config.height,
-		renderer: config.renderer,
-		width: config.width
-	});
-	chart.setOption(option);
-	const dataUrl = chart.getDataURL({
-		backgroundColor: "#ffffff",
-		pixelRatio: 2,
-		type: config.imageType === "svg" ? "svg" : "png"
-	});
-	chart.dispose();
-	container.remove();
-	return {
-		data: await dataUrlToUint8Array(dataUrl),
-		type: config.imageType
-	};
-}
-/**
-* Node.js-side ECharts rendering (not built-in).
-*
-* Requires a server-side canvas or SVG DOM implementation
-* (e.g. `node-canvas` + `echarts`). Throws an error prompting
-* the user to provide a custom render function when used
-* outside the browser.
-*/
-async function renderInNode(_option, _config) {
-	throw new DocxKitError(ERROR_CODES.PLUGIN_RENDER_FAILED, "ECharts Node renderer is not built-in. Use a server-side canvas implementation (e.g. node-canvas + echarts) and provide a custom render function. See https://github.com/ntnyq/docx-kit for alternatives.");
-}
-//#endregion
-//#region src/builder/createDocx.ts
-/**
-* Factory functions for creating `DocxBuilder` instances.
-*
-* Two entry points are provided:
-* - `createDocx()` — Fluent builder API with chaining
-* - `renderDocx()` — JSON-schema driven (AI-friendly / serializable)
-*
-* @module builder/createDocx
-*/
-/**
-* Create a new DocxBuilder with optional configuration.
-*
-* This is the primary entry point for the fluent builder API.
-* Chain `.h1()`, `.p()`, `.table()`, etc. and call `.save()`
-* or `.toBlob()` to export.
-*
-* @param config - — Document configuration (page, styles, metadata, theme, defaults)
-* @returns A new `DocxBuilder` instance
-*
-* @example
-* ```ts
-* const styles = defineStyles({
-*   title: { fontSize: 28, fontWeight: 'bold' },
-*   body:  { fontSize: 12, lineHeight: 1.5 },
-* })
-*
-* const doc = createDocx({
-*   styles,
-*   page: { size: 'A4', margin: '20mm' },
-*   metadata: { title: 'Report', creator: 'docx-kit' },
-* })
-*
-* await doc
-*   .h1('Annual Report', { className: 'title' })
-*   .p('Lorem ipsum...', { className: 'body' })
-*   .save('report.docx')
-* ```
-*/
-function createDocx(config = {}) {
-	return new DocxBuilder(config);
-}
-/**
-* Render a document from a JSON schema (AI-friendly / serializable DSL).
-*
-* Unlike `createDocx()`, this accepts a single JSON-serializable object
-* with `content` (node array), optional `styles`, and optional `page` config.
-* Ideal for AI-driven document generation or API integrations.
-*
-* @param schema - — The `DocxSchema` object
-* @returns A `DocxBuilder` instance (ready to export)
-*
-* @example
-* ```ts
-* const blob = await renderDocx({
-*   page: { size: 'A4', margin: '20mm' },
-*   styles: {
-*     h1: { fontSize: 24, fontWeight: 'bold' },
-*     p:  { fontSize: 12 },
-*   },
-*   content: [
-*     { type: 'heading',  level: 1, text: 'Report', className: 'h1' },
-*     { type: 'paragraph', text: 'This is a report generated via JSON DSL.', className: 'p' },
-*     { type: 'pageBreak' },
-*     {
-*       type: 'table',
-*       columns: [{ key: 'name', title: 'Name' }, { key: 'value', title: 'Value' }],
-*       data: [{ name: 'Revenue', value: '$1.2M' }],
-*     },
-*   ],
-* }).toBlob()
-* ```
-*/
-function renderDocx(schema) {
-	const { content, ...config } = schema;
-	const builder = new DocxBuilder(config);
-	for (const node of content) builder.add(node);
-	return builder;
-}
-//#endregion
-export { DocxBuilder, DocxKitError, ERROR_CODES, createDocx, dataUrlToUint8Array, definePlugin, defineStyles, echartsPlugin, qrcodePlugin, renderDocx };