@lotics/docx 0.1.0

package/src/parse/numbering.ts

@@ -0,0 +1,187 @@
+import {
+  parseXml,
+  getAttr,
+  getChildren,
+  getTagName,
+  type XmlElement,
+} from "@lotics/ooxml/xml";
+import {
+  EMPTY_NUMBERING_TABLE,
+  type AbstractNum,
+  type Justification,
+  type LvlOverride,
+  type Num,
+  type NumberFormat,
+  type NumberingLevel,
+  type NumberingTable,
+} from "../model/numbering_table";
+import {
+  extractParagraphProperties,
+  extractRunProperties,
+} from "../model/properties";
+
+function isNumberFormat(value: string): value is NumberFormat {
+  return (
+    value === "decimal" ||
+    value === "decimalZero" ||
+    value === "lowerLetter" ||
+    value === "upperLetter" ||
+    value === "lowerRoman" ||
+    value === "upperRoman" ||
+    value === "bullet" ||
+    value === "none"
+  );
+}
+
+function isJustification(value: string): value is Justification {
+  return value === "left" || value === "center" || value === "right";
+}
+
+function parseIntOrDefault(v: string | undefined, fallback: number): number {
+  if (v === undefined) return fallback;
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function parseIntOrNull(v: string | undefined): number | null {
+  if (v === undefined) return null;
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+function parseLevel(el: XmlElement): NumberingLevel {
+  const ilvl = parseIntOrDefault(getAttr(el, "w:ilvl"), 0);
+  let start = 1;
+  let numFmt: NumberFormat = "decimal";
+  let lvlText = "";
+  let lvlJc: Justification = "left";
+  let lvlRestart: number | null = null;
+  let paragraphProperties: NumberingLevel["paragraphProperties"] = null;
+  let runProperties: NumberingLevel["runProperties"] = null;
+  let suff: "tab" | "space" | "nothing" = "tab";
+
+  for (const child of getChildren(el)) {
+    const tag = getTagName(child);
+    switch (tag) {
+      case "w:start":
+        start = parseIntOrDefault(getAttr(child, "w:val"), 1);
+        break;
+      case "w:numFmt": {
+        const v = getAttr(child, "w:val");
+        if (v && isNumberFormat(v)) numFmt = v;
+        break;
+      }
+      case "w:lvlText":
+        lvlText = getAttr(child, "w:val") ?? "";
+        break;
+      case "w:lvlJc": {
+        const v = getAttr(child, "w:val");
+        if (v && isJustification(v)) lvlJc = v;
+        break;
+      }
+      case "w:lvlRestart":
+        lvlRestart = parseIntOrNull(getAttr(child, "w:val"));
+        break;
+      case "w:pPr":
+        paragraphProperties = extractParagraphProperties(getChildren(child));
+        break;
+      case "w:rPr":
+        runProperties = extractRunProperties(getChildren(child));
+        break;
+      case "w:suff": {
+        const v = getAttr(child, "w:val");
+        if (v === "tab" || v === "space" || v === "nothing") suff = v;
+        break;
+      }
+    }
+  }
+
+  return {
+    ilvl,
+    start,
+    numFmt,
+    lvlText,
+    lvlJc,
+    lvlRestart,
+    paragraphProperties,
+    runProperties,
+    suff,
+  };
+}
+
+function parseAbstractNum(el: XmlElement): AbstractNum | null {
+  const idAttr = getAttr(el, "w:abstractNumId");
+  const id = parseIntOrNull(idAttr);
+  if (id === null) return null;
+
+  const levels = new Map<number, NumberingLevel>();
+  for (const child of getChildren(el)) {
+    if (getTagName(child) !== "w:lvl") continue;
+    const level = parseLevel(child);
+    levels.set(level.ilvl, level);
+  }
+  return { abstractNumId: id, levels };
+}
+
+function parseLvlOverride(el: XmlElement): LvlOverride | null {
+  const ilvl = parseIntOrNull(getAttr(el, "w:ilvl"));
+  if (ilvl === null) return null;
+  let startOverride: number | null = null;
+  let level: NumberingLevel | null = null;
+  for (const child of getChildren(el)) {
+    const tag = getTagName(child);
+    if (tag === "w:startOverride") {
+      startOverride = parseIntOrNull(getAttr(child, "w:val"));
+    } else if (tag === "w:lvl") {
+      level = parseLevel(child);
+    }
+  }
+  return { ilvl, startOverride, level };
+}
+
+function parseNum(el: XmlElement): Num | null {
+  const numIdAttr = getAttr(el, "w:numId");
+  const numId = parseIntOrNull(numIdAttr);
+  if (numId === null) return null;
+
+  let abstractNumId: number | null = null;
+  const overrides = new Map<number, LvlOverride>();
+  for (const child of getChildren(el)) {
+    const tag = getTagName(child);
+    if (tag === "w:abstractNumId") {
+      abstractNumId = parseIntOrNull(getAttr(child, "w:val"));
+    } else if (tag === "w:lvlOverride") {
+      const ovr = parseLvlOverride(child);
+      if (ovr) overrides.set(ovr.ilvl, ovr);
+    }
+  }
+  if (abstractNumId === null) return null;
+  return { numId, abstractNumId, overrides };
+}
+
+export function parseNumberingTable(
+  parts: ReadonlyMap<string, Uint8Array>,
+): NumberingTable {
+  const bytes = parts.get("word/numbering.xml");
+  if (!bytes) return EMPTY_NUMBERING_TABLE;
+
+  const xml = new TextDecoder("utf-8").decode(bytes);
+  const parsed = parseXml(xml);
+  const numberingEl = parsed.find((el) => getTagName(el) === "w:numbering");
+  if (!numberingEl) return EMPTY_NUMBERING_TABLE;
+
+  const abstractNums = new Map<number, AbstractNum>();
+  const nums = new Map<number, Num>();
+  for (const child of getChildren(numberingEl)) {
+    const tag = getTagName(child);
+    if (tag === "w:abstractNum") {
+      const a = parseAbstractNum(child);
+      if (a) abstractNums.set(a.abstractNumId, a);
+    } else if (tag === "w:num") {
+      const n = parseNum(child);
+      if (n) nums.set(n.numId, n);
+    }
+  }
+
+  return { abstractNums, nums };
+}

package/src/parse/parser.ts

@@ -0,0 +1,184 @@
+import JSZip from "jszip";
+import {
+  parseXml,
+  getTagName,
+  getChildren,
+  findChild,
+  getAttr,
+  getTextContent,
+  isTextNode,
+  type XmlElement,
+} from "@lotics/ooxml/xml";
+import type {
+  Block,
+  Body,
+  BodySectPr,
+  DocxDocument,
+  Inline,
+  OpaqueBlock,
+  OpaqueInline,
+  OpaqueRunChild,
+  Paragraph,
+  Run,
+  RunChild,
+  TextNode,
+} from "../model/types";
+
+export async function parseDocx(buffer: Uint8Array): Promise<DocxDocument> {
+  const zip = await JSZip.loadAsync(buffer);
+
+  const parts = new Map<string, Uint8Array>();
+  const filePromises: Promise<void>[] = [];
+  zip.forEach((path, file) => {
+    if (file.dir) return;
+    filePromises.push(
+      file.async("uint8array").then((bytes) => {
+        parts.set(path, bytes);
+      }),
+    );
+  });
+  await Promise.all(filePromises);
+
+  const documentBytes = parts.get("word/document.xml");
+  if (!documentBytes) {
+    throw new Error("Invalid .docx: missing word/document.xml");
+  }
+
+  const documentXml = new TextDecoder("utf-8").decode(documentBytes);
+  const parsed = parseXml(documentXml);
+
+  const docEl = parsed.find((el) => getTagName(el) === "w:document");
+  if (!docEl) {
+    throw new Error("Invalid .docx: missing <w:document>");
+  }
+
+  const documentAttrs: Record<string, string> = {};
+  const rawAttrs = docEl[":@"] as Record<string, string> | undefined;
+  if (rawAttrs) {
+    for (const [k, v] of Object.entries(rawAttrs)) {
+      documentAttrs[k] = v;
+    }
+  }
+
+  const bodyEl = findChild(docEl, "w:body");
+  if (!bodyEl) {
+    throw new Error("Invalid .docx: missing <w:body>");
+  }
+
+  const body = parseBody(bodyEl);
+
+  return {
+    parts,
+    documentAttrs,
+    body,
+  };
+}
+
+function parseBody(bodyEl: XmlElement): Body {
+  const children: Block[] = [];
+  for (const childEl of getChildren(bodyEl)) {
+    if (isTextNode(childEl)) continue;
+    children.push(parseBlock(childEl));
+  }
+  return { children };
+}
+
+function parseBlock(el: XmlElement): Block {
+  const tag = getTagName(el);
+  if (tag === "w:p") return parseParagraph(el);
+  if (tag === "w:sectPr") return parseBodySectPr(el);
+  return parseOpaqueBlock(el);
+}
+
+export function parseBlockXml(el: XmlElement): Block {
+  return parseBlock(el);
+}
+
+function parseParagraph(el: XmlElement): Paragraph {
+  const properties: XmlElement[] = [];
+  const content: Inline[] = [];
+  let propertiesSeen = false;
+
+  for (const child of getChildren(el)) {
+    if (isTextNode(child)) continue;
+    const tag = getTagName(child);
+    if (tag === "w:pPr") {
+      propertiesSeen = true;
+      for (const propEl of getChildren(child)) {
+        if (isTextNode(propEl)) continue;
+        properties.push(propEl);
+      }
+      continue;
+    }
+    content.push(parseInline(child));
+  }
+
+  return {
+    kind: "paragraph",
+    properties: propertiesSeen ? properties : null,
+    content,
+  };
+}
+
+function parseInline(el: XmlElement): Inline {
+  const tag = getTagName(el);
+  if (tag === "w:r") return parseRun(el);
+  return parseOpaqueInline(el);
+}
+
+function parseRun(el: XmlElement): Run {
+  const properties: XmlElement[] = [];
+  const content: RunChild[] = [];
+  let propertiesSeen = false;
+
+  for (const child of getChildren(el)) {
+    if (isTextNode(child)) continue;
+    const tag = getTagName(child);
+    if (tag === "w:rPr") {
+      propertiesSeen = true;
+      for (const propEl of getChildren(child)) {
+        if (isTextNode(propEl)) continue;
+        properties.push(propEl);
+      }
+      continue;
+    }
+    content.push(parseRunChild(child));
+  }
+
+  return {
+    kind: "run",
+    properties: propertiesSeen ? properties : null,
+    content,
+  };
+}
+
+function parseRunChild(el: XmlElement): RunChild {
+  const tag = getTagName(el);
+  if (tag === "w:t") return parseText(el);
+  return parseOpaqueRunChild(el);
+}
+
+function parseText(el: XmlElement): TextNode {
+  const preserveSpace = getAttr(el, "xml:space") === "preserve";
+  return {
+    kind: "text",
+    value: getTextContent(el),
+    preserveSpace,
+  };
+}
+
+function parseBodySectPr(el: XmlElement): BodySectPr {
+  return { kind: "body_sect_pr", xml: el };
+}
+
+function parseOpaqueBlock(el: XmlElement): OpaqueBlock {
+  return { kind: "opaque_block", xml: el };
+}
+
+function parseOpaqueInline(el: XmlElement): OpaqueInline {
+  return { kind: "opaque_inline", xml: el };
+}
+
+function parseOpaqueRunChild(el: XmlElement): OpaqueRunChild {
+  return { kind: "opaque_run_child", xml: el };
+}

package/src/parse/relationships.ts

@@ -0,0 +1,83 @@
+import {
+  parseXml,
+  getAttr,
+  getChildren,
+  getTagName,
+} from "@lotics/ooxml/xml";
+
+export type Relationship = {
+  id: string;
+  type: string;
+  target: string;
+  targetMode: string | null;
+};
+
+export type RelationshipMap = ReadonlyMap<string, Relationship>;
+
+const REL_TYPE_HYPERLINK = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+const REL_TYPE_IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+
+export function isHyperlinkRelationship(rel: Relationship | undefined): boolean {
+  return rel?.type === REL_TYPE_HYPERLINK;
+}
+
+export function isImageRelationship(rel: Relationship | undefined): boolean {
+  return rel?.type === REL_TYPE_IMAGE;
+}
+
+export function parseDocumentRelationships(
+  parts: ReadonlyMap<string, Uint8Array>,
+): RelationshipMap {
+  const bytes = parts.get("word/_rels/document.xml.rels");
+  if (!bytes) return new Map();
+
+  const xml = new TextDecoder("utf-8").decode(bytes);
+  const parsed = parseXml(xml);
+  const relsEl = parsed.find((el) => getTagName(el) === "Relationships");
+  if (!relsEl) return new Map();
+
+  const out = new Map<string, Relationship>();
+  for (const child of getChildren(relsEl)) {
+    if (getTagName(child) !== "Relationship") continue;
+    const id = getAttr(child, "Id");
+    const type = getAttr(child, "Type");
+    const target = getAttr(child, "Target");
+    if (!id || !type || !target) continue;
+    out.set(id, {
+      id,
+      type,
+      target,
+      targetMode: getAttr(child, "TargetMode") ?? null,
+    });
+  }
+  return out;
+}
+
+/**
+ * Resolves a relationship target into the absolute part path within the ZIP,
+ * given that the relationship file lives at `word/_rels/document.xml.rels`.
+ * Internal targets are relative to the document's base directory (`word/`).
+ */
+export function resolveInternalPartPath(target: string): string {
+  if (target.startsWith("/")) return target.slice(1);
+  return `word/${target}`;
+}
+
+export function resolveHyperlinkUrl(
+  relationships: RelationshipMap,
+  relId: string,
+): string | null {
+  const rel = relationships.get(relId);
+  if (!rel || !isHyperlinkRelationship(rel)) return null;
+  return rel.target;
+}
+
+export function resolveImagePartPath(
+  relationships: RelationshipMap,
+  relId: string,
+): string | null {
+  const rel = relationships.get(relId);
+  if (!rel || !isImageRelationship(rel)) return null;
+  return resolveInternalPartPath(rel.target);
+}
+

package/src/parse/sections.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect } from "vitest";
+import { parseXml, getTagName, findChild } from "@lotics/ooxml/xml";
+import {
+  parseBodySections,
+  parseSectionProperties,
+} from "./sections";
+import type { Body } from "../model/types";
+
+const NS = `xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"`;
+
+function sectPr(xml: string) {
+  return parseXml(`<w:sectPr ${NS}>${xml}</w:sectPr>`)[0];
+}
+
+describe("parseSectionProperties", () => {
+  it("returns Letter portrait defaults when sectPr is empty", () => {
+    const props = parseSectionProperties(sectPr(""));
+    expect(props.pageSize).toEqual({
+      width: 12240,
+      height: 15840,
+      orientation: "portrait",
+    });
+    expect(props.margins).toEqual({
+      top: 1440,
+      right: 1440,
+      bottom: 1440,
+      left: 1440,
+      header: 720,
+      footer: 720,
+      gutter: 0,
+    });
+    expect(props.columns.count).toBe(1);
+    expect(props.type).toBe("nextPage");
+  });
+
+  it("parses A4 landscape with custom margins", () => {
+    const props = parseSectionProperties(
+      sectPr(`
+        <w:pgSz w:w="16838" w:h="11906" w:orient="landscape"/>
+        <w:pgMar w:top="720" w:right="1080" w:bottom="720" w:left="1080"
+                 w:header="360" w:footer="360" w:gutter="0"/>
+      `),
+    );
+    expect(props.pageSize).toEqual({
+      width: 16838,
+      height: 11906,
+      orientation: "landscape",
+    });
+    expect(props.margins.top).toBe(720);
+    expect(props.margins.left).toBe(1080);
+  });
+
+  it("parses two equal-width columns with separator", () => {
+    const props = parseSectionProperties(
+      sectPr(`<w:cols w:num="2" w:space="720" w:sep="1"/>`),
+    );
+    expect(props.columns).toEqual({
+      count: 2,
+      space: 720,
+      equalWidth: true,
+      separator: true,
+      columns: [],
+    });
+  });
+
+  it("parses unequal columns with explicit widths", () => {
+    const props = parseSectionProperties(
+      sectPr(`
+        <w:cols w:num="2" w:equalWidth="0">
+          <w:col w:w="3000" w:space="720"/>
+          <w:col w:w="6000"/>
+        </w:cols>
+      `),
+    );
+    expect(props.columns.equalWidth).toBe(false);
+    expect(props.columns.columns).toEqual([
+      { width: 3000, space: 720 },
+      { width: 6000, space: null },
+    ]);
+  });
+
+  it("parses header/footer references with types", () => {
+    const props = parseSectionProperties(
+      sectPr(`
+        <w:headerReference w:type="default" r:id="rId7"/>
+        <w:headerReference w:type="first" r:id="rId8"/>
+        <w:footerReference w:type="default" r:id="rId9"/>
+        <w:titlePg/>
+      `),
+    );
+    expect(props.titlePage).toBe(true);
+    expect(props.headerRefs).toEqual([
+      { type: "default", relationshipId: "rId7" },
+      { type: "first", relationshipId: "rId8" },
+    ]);
+    expect(props.footerRefs).toEqual([
+      { type: "default", relationshipId: "rId9" },
+    ]);
+  });
+
+  it("parses section type", () => {
+    const props = parseSectionProperties(
+      sectPr(`<w:type w:val="continuous"/>`),
+    );
+    expect(props.type).toBe("continuous");
+  });
+});
+
+describe("parseBodySections", () => {
+  it("synthesizes a default section when body has no sectPr", () => {
+    const body: Body = {
+      children: [
+        { kind: "paragraph", properties: null, content: [] },
+        { kind: "paragraph", properties: null, content: [] },
+      ],
+    };
+    const sections = parseBodySections(body);
+    expect(sections).toHaveLength(1);
+    expect(sections[0].blockStartIndex).toBe(0);
+    expect(sections[0].blockEndIndex).toBe(1);
+    expect(sections[0].properties.pageSize.orientation).toBe("portrait");
+  });
+
+  it("captures the body-level final sectPr", () => {
+    const body: Body = {
+      children: [
+        { kind: "paragraph", properties: null, content: [] },
+        {
+          kind: "body_sect_pr",
+          xml: sectPr(`<w:pgSz w:w="11906" w:h="16838"/>`),
+        },
+      ],
+    };
+    const sections = parseBodySections(body);
+    expect(sections).toHaveLength(1);
+    expect(sections[0].blockStartIndex).toBe(0);
+    expect(sections[0].blockEndIndex).toBe(0);
+    expect(sections[0].properties.pageSize.width).toBe(11906);
+  });
+
+  it("captures multi-section docs (sectPr nested in paragraph pPr)", () => {
+    const inlineSect = sectPr(`<w:type w:val="continuous"/>`);
+    const finalSect = sectPr(`<w:pgSz w:w="11906" w:h="16838"/>`);
+
+    const body: Body = {
+      children: [
+        { kind: "paragraph", properties: null, content: [] },
+        {
+          kind: "paragraph",
+          properties: [inlineSect],
+          content: [],
+        },
+        { kind: "paragraph", properties: null, content: [] },
+        { kind: "body_sect_pr", xml: finalSect },
+      ],
+    };
+
+    const sections = parseBodySections(body);
+    expect(sections).toHaveLength(2);
+    expect(sections[0]).toMatchObject({
+      blockStartIndex: 0,
+      blockEndIndex: 1,
+      properties: { type: "continuous" },
+    });
+    expect(sections[1]).toMatchObject({
+      blockStartIndex: 2,
+      blockEndIndex: 2,
+    });
+    expect(sections[1].properties.pageSize.width).toBe(11906);
+  });
+
+  it("ignores non-sectPr children inside paragraph properties", () => {
+    const props = parseXml(
+      `<w:pPr ${NS}><w:pStyle w:val="Heading1"/></w:pPr>`,
+    )[0];
+    expect(getTagName(props)).toBe("w:pPr");
+    const innerChildren = findChild(props, "w:pStyle");
+    expect(innerChildren).toBeDefined();
+
+    const body: Body = {
+      children: [
+        {
+          kind: "paragraph",
+          properties: [findChild(props, "w:pStyle")!],
+          content: [],
+        },
+      ],
+    };
+    const sections = parseBodySections(body);
+    expect(sections).toHaveLength(1);
+  });
+});