docx-kit 0.0.0 → 0.1.0

package/dist/browser.d.ts

@@ -0,0 +1,67 @@
+//#region src/browser/dom.d.ts
+/**
+ * Browser DOM utilities — base64 decoding and Blob/image handling.
+ *
+ * @module browser/dom
+ */
+/**
+ * Decode a base64 data-URL to raw bytes using the browser `atob` API.
+ *
+ * Strips the `"data:*;base64,"` prefix, decodes the base64 string
+ * via `atob()`, and populates a `Uint8Array` from each character's
+ * code point.
+ *
+ * @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/browser'
+ *
+ * const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
+ * ```
+ */
+declare function dataUrlToUint8Array(dataUrl: string): Promise<Uint8Array>;
+/**
+ * Normalize image data for `ImageRun` — converts `Blob` to `Uint8Array`.
+ *
+ * In the browser, image data often arrives as a `Blob` (e.g. from
+ * `<input type="file">` or `fetch()`). `ImageRun` expects raw bytes,
+ * so we convert via `Blob.arrayBuffer()`.
+ *
+ * @param data - — The raw image data (Blob, Uint8Array, ArrayBuffer, string)
+ * @returns Normalized data suitable for `ImageRun`
+ *
+ * @example
+ * ```ts
+ * import { normalizeImageData } from 'docx-kit/browser'
+ *
+ * const file = document.querySelector('input[type=file]').files[0]
+ * const data = await normalizeImageData(file) // Blob → Uint8Array
+ * ```
+ */
+declare function normalizeImageData(data: unknown): Promise<string | ArrayBuffer | Uint8Array>;
+//#endregion
+//#region src/browser.d.ts
+/**
+ * ### ❌ `saveDocument()` — Not available in browsers
+ *
+ * Browsers do not provide direct filesystem access for security reasons.
+ * To trigger a file download in the browser, use `doc.toBlob()` with
+ * `URL.createObjectURL()` and a temporary `<a>` element:
+ *
+ * ```ts
+ * const blob = await doc.toBlob()
+ * const url = URL.createObjectURL(blob)
+ * const a = document.createElement('a')
+ * a.href = url
+ * a.download = 'output.docx'
+ * a.click()
+ * URL.revokeObjectURL(url)
+ * ```
+ *
+ * @deprecated This API is not available in browsers. Use `doc.toBlob()` instead.
+ */
+declare const saveDocument: never;
+//#endregion
+export { dataUrlToUint8Array, normalizeImageData, saveDocument };

package/dist/browser.js

@@ -0,0 +1,54 @@
+//#region src/browser/dom.ts
+/**
+* Browser DOM utilities — base64 decoding and Blob/image handling.
+*
+* @module browser/dom
+*/
+/**
+* Decode a base64 data-URL to raw bytes using the browser `atob` API.
+*
+* Strips the `"data:*;base64,"` prefix, decodes the base64 string
+* via `atob()`, and populates a `Uint8Array` from each character's
+* code point.
+*
+* @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/browser'
+*
+* const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
+* ```
+*/
+async function dataUrlToUint8Array(dataUrl) {
+	const base64 = dataUrl.split(",")[1];
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+/**
+* Normalize image data for `ImageRun` — converts `Blob` to `Uint8Array`.
+*
+* In the browser, image data often arrives as a `Blob` (e.g. from
+* `<input type="file">` or `fetch()`). `ImageRun` expects raw bytes,
+* so we convert via `Blob.arrayBuffer()`.
+*
+* @param data - — The raw image data (Blob, Uint8Array, ArrayBuffer, string)
+* @returns Normalized data suitable for `ImageRun`
+*
+* @example
+* ```ts
+* import { normalizeImageData } from 'docx-kit/browser'
+*
+* const file = document.querySelector('input[type=file]').files[0]
+* const data = await normalizeImageData(file) // Blob → Uint8Array
+* ```
+*/
+async function normalizeImageData(data) {
+	if (typeof Blob !== "undefined" && data instanceof Blob) return new Uint8Array(await data.arrayBuffer());
+	return data;
+}
+//#endregion
+export { dataUrlToUint8Array, normalizeImageData };