@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/browser/modules/word/convert/html/html-import.d.ts

@@ -20,7 +20,7 @@
  * const buffer = await toBuffer(Document.build(h));
  * ```
  */
-import type { BodyContent } from "../../types.js";
+import type { BodyContent, ImageDef } from "../../types.js";
 /** Options for HTML to DOCX conversion. */
 export interface HtmlImportOptions {
     /** Default font size in half-points (default: 24 = 12pt). */
@@ -48,3 +48,34 @@ export interface HtmlImportOptions {
  * @returns Array of BodyContent blocks.
  */
 export declare function htmlToDocxBody(html: string, options?: HtmlImportOptions): BodyContent[];
+/** Result of {@link htmlToDocx}: body content plus the images it references. */
+export interface HtmlToDocxResult {
+    /** Parsed body content blocks. */
+    readonly body: BodyContent[];
+    /**
+     * Images decoded from base64 `data:` URLs in the HTML, each with a unique
+     * rId already referenced by the matching image run in `body`. Merge these
+     * into the document model's `images` array so the pictures are embedded as
+     * real media in the package instead of dropped as placeholders.
+     */
+    readonly images: ImageDef[];
+}
+/**
+ * Convert an HTML string into DOCX body content **and** embedded images.
+ *
+ * Unlike {@link htmlToDocxBody}, this decodes base64 `data:` image URLs into
+ * real {@link ImageDef}s and assigns each a unique rId that the emitted image
+ * runs reference. Merge the returned `images` into your document model so the
+ * pictures are embedded rather than dropped as placeholders.
+ *
+ * @example
+ * ```ts
+ * const { body, images } = htmlToDocx(html);
+ * const doc = Document.create();
+ * for (const item of body) Document.addContent(doc, item);
+ * const built = Document.build(doc);
+ * const final = { ...built, images: [...(built.images ?? []), ...images] };
+ * const bytes = await toBuffer(final);
+ * ```
+ */
+export declare function htmlToDocx(html: string, options?: HtmlImportOptions): HtmlToDocxResult;

package/dist/browser/modules/word/convert/html/html-import.js

@@ -20,6 +20,7 @@
  * const buffer = await toBuffer(Document.build(h));
  * ```
  */
+import { base64ToUint8Array } from "../../../../utils/utils.browser.js";
 import { sanitizeUrl } from "../../core/internal-utils.js";
 import { EMU_PER_PX } from "../../units.js";
 /**
@@ -44,10 +45,7 @@ export function htmlToDocxBody(html, options) {
     const tokens = tokenize(html);
     // Extract <style> rules and merge with user-provided classStyles
     const extractedStyles = extractStyleRules(tokens);
-    const classStyles = {
-        ...extractedStyles,
-        ...(options?.classStyles ?? {})
-    };
+    const classStyles = mergeClassStyles(extractedStyles, options?.classStyles ?? {});
     // Seed the inline context with the caller-supplied defaults so plain text
     // runs actually carry the requested font/size. Without this the options
     // were effectively ignored.
@@ -61,6 +59,40 @@ export function htmlToDocxBody(html, options) {
     parseBlocks(tokens, 0, blocks, initialCtx, classStyles);
     return blocks;
 }
+/**
+ * Convert an HTML string into DOCX body content **and** embedded images.
+ *
+ * Unlike {@link htmlToDocxBody}, this decodes base64 `data:` image URLs into
+ * real {@link ImageDef}s and assigns each a unique rId that the emitted image
+ * runs reference. Merge the returned `images` into your document model so the
+ * pictures are embedded rather than dropped as placeholders.
+ *
+ * @example
+ * ```ts
+ * const { body, images } = htmlToDocx(html);
+ * const doc = Document.create();
+ * for (const item of body) Document.addContent(doc, item);
+ * const built = Document.build(doc);
+ * const final = { ...built, images: [...(built.images ?? []), ...images] };
+ * const bytes = await toBuffer(final);
+ * ```
+ */
+export function htmlToDocx(html, options) {
+    const blocks = [];
+    const tokens = tokenize(html);
+    const extractedStyles = extractStyleRules(tokens);
+    const classStyles = mergeClassStyles(extractedStyles, options?.classStyles ?? {});
+    const images = [];
+    const initialCtx = { imageSink: images };
+    if (options?.defaultFont) {
+        initialCtx.fontFamily = options.defaultFont;
+    }
+    if (options?.defaultFontSize !== undefined) {
+        initialCtx.fontSize = options.defaultFontSize;
+    }
+    parseBlocks(tokens, 0, blocks, initialCtx, classStyles);
+    return { body: blocks, images };
+}
 function tokenize(html) {
     const tokens = [];
     // Strip HTML comments, doctype declarations and SGML processing
@@ -473,6 +505,22 @@ function extractStyleRules(tokens) {
     }
     return result;
 }
+/**
+ * Merge two class→style maps. For classes present in both, the declarations
+ * are concatenated (extracted `<style>` rules first, caller-supplied overrides
+ * last) so the later source wins per CSS cascade while still preserving
+ * properties only declared by the other source. A plain `{ ...a, ...b }`
+ * would discard the extracted rule entirely whenever the caller supplies the
+ * same class name, silently dropping e.g. `font-style`/`color` from `<style>`.
+ */
+function mergeClassStyles(extracted, overrides) {
+    const merged = { ...extracted };
+    for (const [name, style] of Object.entries(overrides)) {
+        const existing = merged[name];
+        merged[name] = existing ? `${existing}; ${style}` : style;
+    }
+    return merged;
+}
 /**
  * Parse HTML-style attributes from the inside of a start tag, e.g.
  * `class="x" id='y' disabled href=foo`.
@@ -1133,6 +1181,17 @@ function parseBlocks(tokens, start, blocks, parentCtx, classStyles) {
             return i + 1; // consumed the close tag
         }
         if (tok.type === "text") {
+            // In block context, text nodes that are pure inter-element whitespace
+            // (the newlines/indentation between block tags in pretty-printed HTML)
+            // carry no content and must be ignored — otherwise every gap between
+            // <p>/<table>/<div> tags would emit a spurious empty paragraph (and
+            // the contained newline would be rendered as a <w:br/> soft break).
+            // Whitespace that sits between inline runs is preserved by the inline
+            // parser, which handles it separately.
+            if (tok.value.trim() === "") {
+                i++;
+                continue;
+            }
             if (!pendingInline) {
                 pendingInline = { runs: [], ctx: parentCtx };
             }
@@ -1461,7 +1520,7 @@ function parseInlineTag(tokens, idx, runs, ctx, classStyles) {
             runs.push({ content: [{ type: "break" }] });
         }
         else if (tag === "img") {
-            const imgContent = buildImageContent(tok.attrs);
+            const imgContent = buildImageContent(tok.attrs, ctx);
             if (imgContent) {
                 runs.push({ content: [imgContent] });
             }
@@ -1534,13 +1593,15 @@ function parseInlineTag(tokens, idx, runs, ctx, classStyles) {
                 i++;
             }
             else if (t.type === "close") {
+                // Mismatched close tag — close the hyperlink here but do NOT
+                // consume the token; let the caller handle the block boundary.
                 const hyperlink = {
                     type: "hyperlink",
                     url: safeHref ?? "",
                     children: innerRuns
                 };
                 runs.push(hyperlink);
-                return i + 1;
+                return i;
             }
             else {
                 const childRuns = [];
@@ -1581,7 +1642,12 @@ function parseInlineTag(tokens, idx, runs, ctx, classStyles) {
             i++;
         }
         else if (t.type === "close") {
-            return i + 1;
+            // Mismatched close tag (e.g. </p> while inside an unclosed <strong>).
+            // Do NOT consume it — return the current index so the caller can
+            // handle it. Consuming a block-level close here would swallow the
+            // parent paragraph boundary and pull all following block content
+            // into this run, breaking page breaks, tables, etc.
+            return i;
         }
         else {
             i = parseInlineTag(tokens, i, runs, newCtx, classStyles);
@@ -1660,6 +1726,15 @@ function parseListItem(tokens, start, blocks, ctx, ordered, level, classStyles)
         }
         // Text content
         if (tok.type === "text") {
+            // Skip structural whitespace: the indentation/newlines that sit between
+            // a nested <ul>/<ol> and the closing </li> (or at the very start of the
+            // item) are not real content. Emitting them as runs would otherwise
+            // produce a spurious empty list-item paragraph. Whitespace *between*
+            // real inline content is preserved because `children` is non-empty then.
+            if (tok.value.trim() === "" && children.length === 0) {
+                i++;
+                continue;
+            }
             children.push(makeRun(tok.value, ctx));
             i++;
             continue;
@@ -2064,7 +2139,7 @@ function mapCssBorderStyle(cssStyle) {
 // Image content builder
 // =============================================================================
 /** Build InlineImageContent from img attributes or return undefined if not applicable. */
-function buildImageContent(attrs) {
+function buildImageContent(attrs, ctx) {
     const src = attrs["src"] || "";
     const alt = attrs["alt"] || "";
     // Parse width/height from attributes first, then fall back to style
@@ -2083,11 +2158,36 @@ function buildImageContent(attrs) {
     // Convert pixels to EMU
     const widthEmu = (width || 100) * EMU_PER_PX;
     const heightEmu = (height || 100) * EMU_PER_PX;
-    // Both data: and http(s) URLs become placeholders. The DOCX writer needs
-    // a real ImageDef registered in `doc.images` plus a corresponding
-    // relationship; htmlToDocxBody returns BodyContent[] only and cannot do
-    // that registration. We surface the original src in the alt text so the
-    // user can post-process if they need real embedded images.
+    // base64 data: URLs can be decoded and embedded as a real media file when
+    // an image sink is provided (htmlToDocx path). The decoded bytes are
+    // registered as an ImageDef and the run references the assigned rId.
+    if (src.startsWith("data:") && ctx?.imageSink) {
+        const decoded = decodeDataUrlImage(src);
+        if (decoded) {
+            const sink = ctx.imageSink;
+            const index = sink.length;
+            const rId = `htmlImg${index}`;
+            const ext = decoded.mediaType === "jpeg" ? "jpg" : decoded.mediaType;
+            sink.push({
+                data: decoded.data,
+                mediaType: decoded.mediaType,
+                fileName: `image_html_${index}.${ext}`,
+                rId
+            });
+            return {
+                type: "image",
+                rId,
+                width: widthEmu,
+                height: heightEmu,
+                altText: alt || undefined,
+                name: alt || `image${index}`
+            };
+        }
+    }
+    // No sink (htmlToDocxBody only returns BodyContent[] and cannot register
+    // media) or an unsupported/remote source: emit a placeholder with an empty
+    // rId. The renderer treats an empty rId as a placeholder; the original src
+    // is surfaced in the alt text so callers can post-process if needed.
     if (src.startsWith("data:") || src.startsWith("http://") || src.startsWith("https://")) {
         return {
             type: "image",
@@ -2100,6 +2200,54 @@ function buildImageContent(attrs) {
     }
     return undefined;
 }
+/** Decode a `data:image/...;base64,...` URL into bytes + media type. */
+function decodeDataUrlImage(src) {
+    // data:image/png;base64,XXXX
+    const match = /^data:image\/([a-z0-9.+-]+)\s*;\s*base64\s*,(.*)$/is.exec(src);
+    if (!match) {
+        return undefined;
+    }
+    const rawType = match[1].toLowerCase();
+    const b64 = match[2].replace(/\s+/g, "");
+    const mediaType = normalizeImageMediaType(rawType);
+    if (!mediaType) {
+        return undefined;
+    }
+    try {
+        const data = base64ToUint8Array(b64);
+        if (data.length === 0) {
+            return undefined;
+        }
+        return { data, mediaType };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Map a data-URL image subtype to a supported ImageMediaType. */
+function normalizeImageMediaType(subtype) {
+    switch (subtype) {
+        case "png":
+            return "png";
+        case "jpeg":
+        case "jpg":
+            return "jpeg";
+        case "gif":
+            return "gif";
+        case "bmp":
+            return "bmp";
+        case "tiff":
+        case "tif":
+            return "tiff";
+        case "svg+xml":
+        case "svg":
+            return "svg";
+        case "webp":
+            return "webp";
+        default:
+            return undefined;
+    }
+}
 /** Parse an image dimension from HTML attribute value (number or "Npx"). */
 function parseImageDimension(value) {
     if (!value) {
@@ -2228,6 +2376,11 @@ function resolveEffectiveStyle(attrs, classStyles) {
 // Run builder
 // =============================================================================
 function makeRun(text, ctx) {
+    // HTML whitespace handling: outside <pre>/<code>, runs of whitespace
+    // (including the newlines/indentation from source-code line wrapping)
+    // collapse to a single space. Inside <pre>/<code> whitespace is
+    // significant and preserved verbatim.
+    const value = ctx.code ? text : text.replace(/\s+/g, " ");
     const props = {};
     if (ctx.bold) {
         props.bold = true;
@@ -2264,7 +2417,7 @@ function makeRun(text, ctx) {
     }
     const run = {
         ...(Object.keys(props).length > 0 ? { properties: props } : {}),
-        content: [{ type: "text", text }]
+        content: [{ type: "text", text: value }]
     };
     return run;
 }

package/dist/browser/modules/word/convert/html/html.d.ts

@@ -11,5 +11,5 @@
  */
 export { renderToHtml } from "./html-renderer.js";
 export type { HtmlRenderOptions, HtmlRenderResult } from "./html-renderer.js";
-export { htmlToDocxBody } from "./html-import.js";
-export type { HtmlImportOptions } from "./html-import.js";
+export { htmlToDocxBody, htmlToDocx } from "./html-import.js";
+export type { HtmlImportOptions, HtmlToDocxResult } from "./html-import.js";

package/dist/browser/modules/word/convert/html/html.js

@@ -12,4 +12,4 @@
 // HTML → render (DocxDocument → HTML output)
 export { renderToHtml } from "./html-renderer.js";
 // HTML → DOCX import (HTML string → BodyContent[])
-export { htmlToDocxBody } from "./html-import.js";
+export { htmlToDocxBody, htmlToDocx } from "./html-import.js";

package/dist/browser/modules/word/convert/markdown/markdown-import.d.ts

@@ -16,7 +16,7 @@
  *
  * @stability experimental
  */
-import type { BodyContent, DocxDocument } from "../../types.js";
+import type { AbstractNumbering, BodyContent, DocxDocument, FootnoteDef, ImageDef, ImageMediaType, NumberingInstance } from "../../types.js";
 /** Options for Markdown to DOCX conversion. */
 export interface MarkdownImportOptions {
     /** Default font family for body text. */
@@ -33,36 +33,66 @@ export interface MarkdownImportOptions {
 /** Resolved image data for embedding. */
 export interface MarkdownImageData {
     readonly data: Uint8Array;
-    readonly mediaType: "png" | "jpeg" | "gif" | "bmp" | "tiff" | "svg" | "webp";
+    readonly mediaType: ImageMediaType;
     readonly width?: number;
     readonly height?: number;
+    /**
+     * Raster (PNG) fallback for vector images. Required by Word for `svg`
+     * images so non-SVG-aware viewers have something to display. When the
+     * media type is `svg` and this is omitted, the packager synthesizes a
+     * transparent placeholder PNG automatically.
+     */
+    readonly fallbackData?: Uint8Array;
+}
+/**
+ * Result of {@link markdownToDocxBody} — the parsed body content plus the
+ * supporting document-level definitions it references.
+ *
+ * Lists, footnotes and images are *not* self-contained: a list paragraph
+ * references a numbering id, a footnote reference run references a
+ * `FootnoteDef`, and an inline image references an `ImageDef`. Splicing the
+ * `body` alone into a host document that lacks these definitions yields
+ * invalid OOXML. Merge the relevant arrays into the host document (or its
+ * builder state) alongside the body.
+ */
+export interface MarkdownBodyResult {
+    readonly body: BodyContent[];
+    readonly abstractNumberings: AbstractNumbering[];
+    readonly numberingInstances: NumberingInstance[];
+    readonly footnotes: FootnoteDef[];
+    readonly images: ImageDef[];
 }
 /**
  * Convert a Markdown string into a complete DocxDocument.
  *
+ * Supports the full GFM feature set including inline images (embedded via the
+ * `resolveImage` callback) and footnotes (`[^id]` references with `[^id]: …`
+ * definitions). Because image resolution and document packaging are inherently
+ * asynchronous, this function is async.
+ *
  * @param markdown - The GFM Markdown string.
  * @param options - Optional conversion settings.
- * @returns A DocxDocument ready to be packaged.
+ * @returns A Promise resolving to a DocxDocument ready to be packaged.
  */
-export declare function markdownToDocx(markdown: string, options?: MarkdownImportOptions): DocxDocument;
+export declare function markdownToDocx(markdown: string, options?: MarkdownImportOptions): Promise<DocxDocument>;
 /**
- * Convert a Markdown string into an array of DOCX body content blocks.
+ * Convert a Markdown string into DOCX body content plus the supporting
+ * document-level definitions it references.
  *
- * **Caveat — body content is not self-contained.**
- *   - **Lists** (bullet / numbered / task) reference numbering ids that
- *     live in document-level `abstractNumberings` + `numberingInstances`,
- *     which this helper does NOT return.
- *   - **Block quotes** reference the named `Quote` style.
- *   - **Code blocks** reference the named code styles.
+ * **Caveat — body content is not self-contained.** The returned `body` may
+ * reference:
+ *   - **Numbering** (`abstractNumberings` / `numberingInstances`) — used by
+ *     bullet / numbered / task lists.
+ *   - **Footnotes** (`footnotes`) — referenced by footnote-reference runs.
+ *   - **Images** (`images`) — referenced by inline image runs.
+ *   - The named `Quote` / `CodeBlock` styles (for block quotes / code blocks).
  *
- * Splicing markdown that uses any of these constructs into a document that
- * lacks the matching numbering / styles yields invalid OOXML. Either keep
- * the input flat (paragraphs + headings + inline formatting) before
- * splicing, or use the higher-level {@link markdownToDocx} which returns a
- * complete `DocxDocument` with the supporting definitions populated.
+ * Splice the relevant arrays into your host document alongside the body, or
+ * use the higher-level {@link markdownToDocx} which returns a complete
+ * `DocxDocument` with everything populated.
  *
  * @param markdown - The GFM Markdown string.
  * @param options - Optional conversion settings.
- * @returns Array of BodyContent blocks (no numbering / styles attached).
+ * @returns A Promise resolving to the body and its supporting definitions.
  */
-export declare function markdownToDocxBody(markdown: string, options?: MarkdownImportOptions): BodyContent[];
+export declare function markdownToDocxBody(markdown: string, options?: MarkdownImportOptions): Promise<MarkdownBodyResult>;