@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/esm/modules/word/convert/docx-to-semantic.js

@@ -11,7 +11,8 @@
  * - Hyperlink extraction
  * - Image registration into ConversionContext
  * - Table structure with merge (colSpan/rowSpan)
- * - List/numbering detection (basic)
+ * - List/numbering detection: consecutive numbered paragraphs are aggregated
+ *   into ordered/unordered `list` blocks with nested sub-lists by level
  * - Footnote/endnote reference and content
  * - Math content (text fallback)
  */
@@ -93,6 +94,26 @@ function convertBodyContent(body, doc, ctx, imageMap) {
         const item = body[bodyIndex];
         switch (item.type) {
             case "paragraph":
+                // A run of consecutive list-item paragraphs (each carrying a
+                // numbering reference, and not a heading) is aggregated into a single
+                // semantic `list` block with nested sub-lists driven by the numbering
+                // level. This is what turns Word numbering into real <ul>/<ol> in
+                // HTML and `-`/`1.` markers in Markdown when downstream renderers
+                // consume the IR.
+                if (isListItemParagraph(item)) {
+                    let end = bodyIndex;
+                    while (end < body.length) {
+                        const next = body[end];
+                        if (next.type !== "paragraph" || !isListItemParagraph(next)) {
+                            break;
+                        }
+                        end++;
+                    }
+                    const listParas = body.slice(bodyIndex, end);
+                    blocks.push(...buildListBlocks(listParas, doc, ctx, imageMap));
+                    bodyIndex = end - 1; // loop's ++ advances past the consumed run
+                    break;
+                }
                 blocks.push(convertParagraph(item, doc, ctx, imageMap));
                 break;
             case "table":
@@ -240,6 +261,119 @@ function convertBodyContent(body, doc, ctx, imageMap) {
     return blocks;
 }
 // =============================================================================
+// Internal: List Aggregation
+// =============================================================================
+/**
+ * Whether a body paragraph should render as a list item: it carries a
+ * numbering reference and is not itself a heading (a numbered heading stays a
+ * heading, mirroring the markdown/html renderers).
+ */
+function isListItemParagraph(item) {
+    if (item.type !== "paragraph") {
+        return false;
+    }
+    return item.properties?.numbering !== undefined && detectHeadingLevel(item) === null;
+}
+/**
+ * Resolve a numbering reference to its number format string (e.g. "decimal",
+ * "bullet"). Mirrors the lookup in the markdown/html renderers so the three
+ * surfaces classify ordered vs. unordered lists identically. Defaults to
+ * "bullet" when the numbering definition can't be resolved.
+ */
+function getNumberingFormat(doc, numId, level) {
+    const instance = doc.numberingInstances?.find(n => n.numId === numId);
+    if (!instance) {
+        return "bullet";
+    }
+    const abstractNum = doc.abstractNumberings?.find(a => a.abstractNumId === instance.abstractNumId);
+    if (!abstractNum) {
+        return "bullet";
+    }
+    const levelDef = abstractNum.levels.find(l => l.level === level);
+    return levelDef?.format ?? "bullet";
+}
+/** A number format other than "bullet"/"none" denotes an ordered list. */
+function isOrderedFormat(format) {
+    return format !== "bullet" && format !== "none";
+}
+/**
+ * Build one or more semantic `list` blocks from a contiguous run of list-item
+ * paragraphs. Paragraphs are nested by their numbering `level`; a deeper level
+ * becomes a `subList` of the preceding shallower item. Adjacent items that
+ * switch between ordered and unordered at the same level start a new sibling
+ * list so the ordered/unordered distinction is preserved.
+ */
+function buildListBlocks(paras, doc, ctx, imageMap) {
+    const { blocks } = buildListLevel(paras, 0, 0, doc, ctx, imageMap);
+    return blocks;
+}
+/**
+ * Consume paragraphs starting at `start` that belong to `level` (or deeper),
+ * emitting sibling lists for this level. Deeper-level paragraphs are folded
+ * into the current item's `subList` via recursion. Returns the produced blocks
+ * and the index of the first paragraph that no longer belongs to this level.
+ */
+function buildListLevel(paras, start, level, doc, ctx, imageMap) {
+    const blocks = [];
+    let i = start;
+    let currentOrdered = null;
+    let items = [];
+    const flush = () => {
+        if (items.length > 0 && currentOrdered !== null) {
+            blocks.push({ type: "list", ordered: currentOrdered, items });
+            items = [];
+        }
+    };
+    while (i < paras.length) {
+        const para = paras[i];
+        const num = para.properties?.numbering;
+        // Defensive: callers only pass list-item paragraphs, but guard anyway.
+        if (!num) {
+            break;
+        }
+        if (num.level < level) {
+            // Belongs to a shallower list — let the caller handle it.
+            break;
+        }
+        if (num.level > level) {
+            // Deeper item with no shallower parent at this position: descend and
+            // attach the nested list to the most recent item, or synthesise an
+            // empty item to host it when there is no parent.
+            const { blocks: subBlocks, next } = buildListLevel(paras, i, num.level, doc, ctx, imageMap);
+            const subList = subBlocks[0];
+            if (items.length > 0) {
+                const last = items[items.length - 1];
+                items[items.length - 1] = { ...last, subList };
+            }
+            else if (subList) {
+                // Promote the deeper list to this level when there is no parent item.
+                if (currentOrdered === null && subList.type === "list") {
+                    currentOrdered = subList.ordered;
+                }
+                items.push({ children: [], subList });
+            }
+            i = next;
+            continue;
+        }
+        // num.level === level
+        const format = getNumberingFormat(doc, num.numId, num.level);
+        const ordered = isOrderedFormat(format);
+        if (currentOrdered === null) {
+            currentOrdered = ordered;
+        }
+        else if (ordered !== currentOrdered) {
+            // Ordered/unordered switch at the same level → start a new sibling list.
+            flush();
+            currentOrdered = ordered;
+        }
+        const children = convertParagraphChildren(para.children, doc, ctx, imageMap);
+        items.push({ children });
+        i++;
+    }
+    flush();
+    return { blocks, next: i };
+}
+// =============================================================================
 // Internal: Paragraph Conversion
 // =============================================================================
 function convertParagraph(para, doc, ctx, imageMap) {

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

@@ -20,6 +20,7 @@
  * const buffer = await toBuffer(Document.build(h));
  * ```
  */
+import { base64ToUint8Array } from "../../../../utils/utils.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/esm/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";