simple-super-doc 0.11.4 → 0.11.5

package/README.md

@@ -4,6 +4,10 @@ Browser-only TypeScript library that parses a `.docx` file into a typed
 intermediate representation (IR) and renders it to HTML. Built for document
 editors and viewers that need a faithful, inspectable model of the document.
 
+**▶️ [Try it live](https://rafael-t-santos.github.io/simple-super-doc/)** — drag
+and drop any `.docx` in your browser to see it rendered. Nothing is uploaded;
+parsing and rendering happen entirely on your machine.
+
 - **Typed IR** — `parse()` returns a `DocxDocument` of `Block`s (paragraphs,
   tables) with computed styles, lists, images, and page size. Inspect or
   transform it before rendering.
@@ -140,12 +144,18 @@ following are intentionally out of scope:
 ## Development
 
 ```bash
-npm run typecheck   # tsc --noEmit
-npm test            # vitest
-npm run build       # esm + d.ts into dist/
-npm run build:demo  # IIFE bundle into demo/ for the drag-and-drop demo
+npm run typecheck    # tsc --noEmit
+npm test             # vitest (node) — parser + pure layout heuristics
+npm run test:browser # Playwright (headless Chromium) — page-aware rendering
+npm run build        # esm + d.ts into dist/
+npm run build:demo   # IIFE bundle into demo/ for the drag-and-drop demo
 ```
 
+The two-pass, page-aware pagination (table splitting, per-page footnotes) needs
+a real layout engine, so it's covered by browser tests in
+[`test/browser/`](test/browser/) rather than the node suite. Install the browser
+once with `npx playwright-core install chromium`.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -76,6 +76,8 @@ type ImageRun = {
     heightPx: number;
     isPageBackground?: boolean;
     href?: string;
+    anchorXPx?: number;
+    anchorYPx?: number;
 };
 type TableBlock = {
     type: 'table';
@@ -113,6 +115,7 @@ type ListRef = {
     ordered: boolean;
     start: number;
     format: string;
+    bulletText?: string;
 };
 type ComputedStyle = {
     bold?: boolean;

package/dist/index.js

@@ -290,9 +290,11 @@ function parseNumbering(xml) {
       const ilvl = parseInt(String(lvl.ilvl), 10);
       const fmtNode = lvl.numFmt;
       const startNode = lvl.start;
+      const textNode = lvl.lvlText;
       const format = fmtNode?.val ?? "bullet";
       const start = parseInt(startNode?.val ?? "1", 10);
-      abstractNumMap[id][ilvl] = { format, start: isNaN(start) ? 1 : start };
+      const text = textNode?.val;
+      abstractNumMap[id][ilvl] = { format, start: isNaN(start) ? 1 : start, ...text !== void 0 ? { text } : {} };
     }
   }
   const numMap = {};
@@ -465,7 +467,14 @@ function resolveListRef(pPr, ctx) {
   if (!levelInfo) return void 0;
   const start = numEntry.startOverride ?? levelInfo.start;
   const ordered = levelInfo.format !== "bullet" && levelInfo.format !== "none";
-  return { numId, ilvl, ordered, start, format: levelInfo.format };
+  return {
+    numId,
+    ilvl,
+    ordered,
+    start,
+    format: levelInfo.format,
+    ...levelInfo.text !== void 0 ? { bulletText: levelInfo.text } : {}
+  };
 }
 async function parseRun(r, paraStyle, ctx, href) {
   const rPr = r.rPr;
@@ -513,13 +522,22 @@ async function parseRun(r, paraStyle, ctx, href) {
     if (!rId) return null;
     const resolved = await resolveImage(rId, ctx.relationshipMap, ctx.zip);
     if (!resolved) return null;
+    const offsetPx = (pos) => {
+      const off = pos?.posOffset;
+      const n = off != null ? parseInt(String(off["#text"] ?? off), 10) : NaN;
+      return Number.isNaN(n) ? void 0 : Math.round(n / 9525);
+    };
+    const anchorXPx = anchor ? offsetPx(anchor.positionH) : void 0;
+    const anchorYPx = anchor ? offsetPx(anchor.positionV) : void 0;
     const img = {
       type: "image",
       src: resolved.src,
       widthPx: Math.round(cx / 9525),
       heightPx: Math.round(cy / 9525),
       ...isPageBackground ? { isPageBackground: true } : {},
-      ...href ? { href } : {}
+      ...href ? { href } : {},
+      ...anchorXPx !== void 0 ? { anchorXPx } : {},
+      ...anchorYPx !== void 0 ? { anchorYPx } : {}
     };
     return img;
   }
@@ -540,27 +558,32 @@ async function parseRun(r, paraStyle, ctx, href) {
     }
     return null;
   }
-  const tNode = r.t ?? r.delText;
-  let text = "";
-  if (typeof tNode === "string") {
-    text = tNode;
-  } else if (typeof tNode === "object" && tNode !== null) {
-    const t = tNode;
-    text = String(t["#text"] ?? t._ ?? "");
-  } else if (tNode != null) {
-    text = String(tNode);
-  }
+  const collectText = (node) => {
+    if (node == null) return [];
+    if (Array.isArray(node)) return node.flatMap(collectText);
+    if (typeof node === "string") return [node];
+    if (typeof node === "object") {
+      const t = node;
+      return [String(t["#text"] ?? t._ ?? "")];
+    }
+    return [String(node)];
+  };
+  const segments = collectText(r.t ?? r.delText);
   const tabNode = r.tab;
-  const tabs = Array.isArray(tabNode) ? tabNode.length : "tab" in r ? 1 : 0;
-  const textRun = {
+  const tabCount = Array.isArray(tabNode) ? tabNode.length : "tab" in r ? 1 : 0;
+  const makeRun = (text, tabs, isLast) => ({
     type: "run",
     text,
     style: runStyle,
     ...href ? { href } : {},
-    ...lineBreak ? { lineBreak: true } : {},
+    ...isLast && lineBreak ? { lineBreak: true } : {},
     ...tabs ? { tabs } : {}
-  };
-  return textRun;
+  });
+  if (segments.length <= 1) return makeRun(segments[0] ?? "", tabCount, true);
+  const interleave = tabCount === segments.length - 1;
+  return segments.map(
+    (seg, i) => makeRun(seg, i === 0 ? 0 : interleave ? 1 : i === 1 ? tabCount : 0, i === segments.length - 1)
+  );
 }
 function resolveHyperlinkHref(hl, ctx) {
   const rId = hl.id;
@@ -677,7 +700,7 @@ async function parseParagraph(p, ctx, rawXml) {
       else {
         for (const ir of innerRuns) {
           const run2 = await parseRun(ir, paraStyle, ctx);
-          if (run2 !== null) runs.push(run2);
+          if (run2 !== null) runs.push(...Array.isArray(run2) ? run2 : [run2]);
         }
       }
       continue;
@@ -705,9 +728,11 @@ async function parseParagraph(p, ctx, rawXml) {
     if (fieldStack.some((f) => f.inResult && LIVE_FIELDS.has(f.name))) continue;
     const run = await parseRun(r, paraStyle, ctx, href);
     if (run !== null) {
-      if (deleted && run.type === "run") run.deleted = true;
-      if (inserted && run.type === "run") run.inserted = true;
-      runs.push(run);
+      for (const rn of Array.isArray(run) ? run : [run]) {
+        if (deleted && rn.type === "run") rn.deleted = true;
+        if (inserted && rn.type === "run") rn.inserted = true;
+        runs.push(rn);
+      }
     }
   }
   const segments = [[]];
@@ -1268,12 +1293,19 @@ function renderRun(run, parent, skipLeadingTabs = false) {
     target = a;
   }
   if (run.type === "image") {
+    const ir = run;
     const img = document.createElement("img");
-    setImageSrc(img, run.src);
-    img.width = run.widthPx;
-    img.height = run.heightPx;
+    setImageSrc(img, ir.src);
+    img.width = ir.widthPx;
+    img.height = ir.heightPx;
     img.style.display = "inline-block";
     img.style.maxWidth = "100%";
+    if (inHeaderFooter && ir.anchorXPx !== void 0) {
+      img.style.position = "absolute";
+      img.style.left = `${ir.anchorXPx}px`;
+      img.style.top = `${ir.anchorYPx ?? 0}px`;
+      img.style.maxWidth = "none";
+    }
     target.appendChild(img);
     return;
   }
@@ -1386,6 +1418,7 @@ function ensureLineBox(el) {
   }
 }
 var inTableCell = false;
+var inHeaderFooter = false;
 var currentPageNumber = 0;
 var FOOTNOTE_SEPARATOR_H = 12;
 function footnoteNumbersIn(el) {
@@ -1434,7 +1467,10 @@ function renderFooter(doc, pageDiv, pageNum, pm, footerPx) {
   const el = document.createElement("div");
   el.className = "ssd-footer";
   el.style.cssText = `position:absolute;left:${pm.left}px;right:${pm.right}px;bottom:${footerPx}px`;
+  const prevHF = inHeaderFooter;
+  inHeaderFooter = true;
   renderBlocks(footer, el);
+  inHeaderFooter = prevHF;
   pageDiv.appendChild(el);
   currentPageNumber = prev;
 }
@@ -1451,7 +1487,10 @@ function renderHeader(doc, pageDiv, pageNum, pm, headerPx) {
   const el = document.createElement("div");
   el.className = "ssd-header";
   el.style.cssText = `position:absolute;left:${pm.left}px;right:${pm.right}px;top:${headerPx}px`;
+  const prevHF = inHeaderFooter;
+  inHeaderFooter = true;
   renderBlocks(header, el);
+  inHeaderFooter = prevHF;
   pageDiv.appendChild(el);
   currentPageNumber = prev;
 }
@@ -1478,8 +1517,14 @@ function renderParagraph(block) {
   const p = document.createElement("p");
   p.style.cssText = paragraphCss(block.style);
   if (block.style.rtl) p.dir = "rtl";
-  const stops = block.style.tabStops;
+  let stops = block.style.tabStops;
   const hasTabRun = block.runs.some((r) => r.type === "run" && (r.tabs ?? 0) > 0);
+  if (inHeaderFooter && hasTabRun && !stops?.some((s) => s.val === "right" || s.val === "center" || s.val === "decimal")) {
+    stops = [
+      { posPx: 0, val: "center", leader: "none" },
+      { posPx: 0, val: "right", leader: "none" }
+    ];
+  }
   const alignStop = stops?.some((s) => s.val === "right" || s.val === "center" || s.val === "decimal");
   if (hasTabRun && stops && alignStop) {
     renderTabbedParagraph(block, p, stops);
@@ -1594,6 +1639,12 @@ var LIST_STYLE = {
   bullet: "disc",
   none: "none"
 };
+function listStyleTypeFor(format, bulletText) {
+  if (format === "bullet" && bulletText && /^[\x20-\x7E]+$/.test(bulletText)) {
+    return `"${bulletText.replace(/[\\"]/g, "\\$&")}"`;
+  }
+  return LIST_STYLE[format];
+}
 function renderBlocks(blocks, container) {
   let stack = [];
   const closeLists = () => {
@@ -1602,13 +1653,13 @@ function renderBlocks(blocks, container) {
   };
   for (const block of blocks) {
     if (block.type === "paragraph" && block.list) {
-      const { numId, ordered, start, ilvl, format } = block.list;
+      const { numId, ordered, start, ilvl, format, bulletText } = block.list;
       if (stack.length > 0 && stack[0].numId !== numId) closeLists();
       while (stack.length > ilvl + 1) stack.pop();
       while (stack.length < ilvl + 1) {
         const listEl = document.createElement(ordered ? "ol" : "ul");
         if (ordered) listEl.start = start;
-        const styleType = LIST_STYLE[format];
+        const styleType = listStyleTypeFor(format, bulletText);
         if (styleType) listEl.style.listStyleType = styleType;
         const indent = block.style.indentLeft ?? 24;
         listEl.style.margin = "0";
@@ -1721,25 +1772,29 @@ function renderPlainPaginated(doc, container, pw, ph, pm, pageOffset = 0) {
       for (; ; ) {
         pageDiv.appendChild(table);
         const th = table.offsetHeight;
-        if (used + th <= contentH - reserve) {
+        const pieceRefs = footnoteNumbersIn(table);
+        const pieceReserve = fnReserve(pieceRefs, pageHasFn);
+        if (used + th <= contentH - reserve - pieceReserve) {
           used += th;
+          recordFootnotes(pieceRefs, pieceReserve);
           break;
         }
-        const rest = splitTableRows(table, contentH - reserve - used);
+        const rest = splitTableRows(table, contentH - reserve - pieceReserve - used);
         if (!rest) {
           if (used === 0) {
             used += th;
+            recordFootnotes(pieceRefs, pieceReserve);
             break;
           }
           pageDiv.removeChild(table);
           pageDiv = newPage();
           continue;
         }
+        const fitRefs = footnoteNumbersIn(table);
+        recordFootnotes(fitRefs, fnReserve(fitRefs, pageHasFn));
         pageDiv = newPage();
         table = rest;
       }
-      const refs2 = footnoteNumbersIn(table);
-      recordFootnotes(refs2, fnReserve(refs2, pageHasFn));
       continue;
     }
     const h = heights[i];
@@ -2198,8 +2253,13 @@ async function resolvePart(documentXml, relationshipMap, zip, ctx, kind, parseXm
 }
 async function resolveRid(rId, relationshipMap, zip, ctx, parseXml) {
   if (!rId || !relationshipMap[rId]) return void 0;
-  const xml = await readEntry(zip, `word/${relationshipMap[rId].target}`, false);
-  return xml ? parseXml(xml, ctx) : void 0;
+  const target = relationshipMap[rId].target;
+  const xml = await readEntry(zip, `word/${target}`, false);
+  if (!xml) return void 0;
+  const base = target.replace(/^.*\//, "");
+  const partRelsXml = await readEntry(zip, `word/_rels/${base}.rels`, false);
+  const partCtx = partRelsXml ? { ...ctx, relationshipMap: parseRelationships(partRelsXml) } : ctx;
+  return parseXml(xml, partCtx);
 }
 async function resolveNotes(xml, kind, refIds, ctx) {
   if (!xml || refIds.length === 0) return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-super-doc",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "description": "Faithful DOCX renderer with exposed typed IR for building document editors",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,6 +22,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
     "prepublishOnly": "npm run build && npm run typecheck && npm test",
     "postversion": "git push origin HEAD --follow-tags"
   },
@@ -51,6 +52,8 @@
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
+    "esbuild": "^0.27.7",
+    "playwright-core": "^1.61.1",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"