@portone/docx-editor 0.2.1 → 0.4.0

package/dist/numbering/writeNumbering.js

@@ -1,48 +1,37 @@
 // src/numbering/writeNumbering.ts
-import { DocxExportError } from "../ooxml/errors.js";
+import { splicePart } from "../ooxml/partSplice.js";
+import { ST_DecimalNumber } from "../ooxml/simpleTypes.js";
 import { wAttr } from "../ooxml/units.js";
 import { elementChildren, parseXml } from "../ooxml/xml.js";
-import { abstractNumXml, listKindOf, numXml } from "./listTemplate.js";
-function openTagAt(xml, name) {
-  const match = new RegExp(`<(?:[A-Za-z_][\\w.-]*:)?${name}[\\s/>]`).exec(xml);
-  return match ? match.index : null;
+import { abstractNumXml, numberingIdAllocator, numXml } from "./listTemplate.js";
+function abstractNumIds(xml) {
+  return elementChildren(parseXml(xml).documentElement).flatMap((child) => {
+    if (child.localName !== "abstractNum") return [];
+    const id = ST_DecimalNumber.parse(wAttr(child, "abstractNumId"));
+    return id === null ? [] : [id];
+  });
 }
-function closeTagAt(xml, name) {
-  const matches = Array.from(
-    xml.matchAll(new RegExp(`</(?:[A-Za-z_][\\w.-]*:)?${name}\\s*>`, "g"))
-  );
-  return matches.at(-1)?.index ?? null;
-}
-function maxAbstractNumId(xml) {
-  let max = 0;
-  for (const child of elementChildren(parseXml(xml).documentElement)) {
-    if (child.localName !== "abstractNum") continue;
-    const id = Number.parseInt(wAttr(child, "abstractNumId") ?? "", 10);
-    if (Number.isFinite(id)) max = Math.max(max, id);
-  }
-  return max;
-}
-function addListDefinitions(xml, numIds) {
-  if (numIds.length === 0) return xml;
-  const rootEnd = closeTagAt(xml, "numbering");
-  if (rootEnd === null) {
-    throw new DocxExportError(
-      "malformed-xml",
-      "no closing tag found in numbering.xml"
-    );
-  }
-  const numsAt = openTagAt(xml, "numIdMacAtCleanup") ?? rootEnd;
-  const definitionsAt = openTagAt(xml, "num") ?? numsAt;
-  const firstAbstractNumId = maxAbstractNumId(xml) + 1;
-  const additions = [...numIds].sort((a, b) => a - b).map((numId, index) => ({
+function addListDefinitions(xml, lists) {
+  if (lists.size === 0) return xml;
+  const takeId = numberingIdAllocator(abstractNumIds(xml));
+  const additions = [...lists].sort(([left], [right]) => left - right).map(([numId, list]) => ({
     numId,
-    abstractNumId: firstAbstractNumId + index
+    list,
+    abstractNumId: takeId()
   }));
-  const definitions = additions.map(
-    (added) => abstractNumXml(added.abstractNumId, listKindOf(added.numId))
-  ).join("");
-  const nums = additions.map((added) => numXml(added.numId, added.abstractNumId)).join("");
-  return xml.slice(0, definitionsAt) + definitions + xml.slice(definitionsAt, numsAt) + nums + xml.slice(numsAt);
+  return splicePart(xml, {
+    root: "numbering",
+    insert: [
+      ...additions.map((added) => ({
+        name: "abstractNum",
+        xml: abstractNumXml(added.abstractNumId, added.list)
+      })),
+      ...additions.map((added) => ({
+        name: "num",
+        xml: numXml(added.numId, added.abstractNumId)
+      }))
+    ]
+  });
 }
 export {
   addListDefinitions

package/dist/ooxml/childOrder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The order the children of one element go in, per parent.
+ *
+ * A writer that swaps one child of a formatting fragment has to put a child that was not there
+ * into the spot the format lays down, and `wml.xsd` is what lays it down. Each entry below names
+ * the complex type it mirrors, and `childOrder.test.ts` reads that type out of the committed
+ * schema and compares it, so an entry cannot drift from the format it claims to follow.
+ *
+ * Where the type is a sequence the order is the schema's and nothing else. Where it is a choice
+ * the schema fixes no order among the alternatives, so the order here is this package's
+ * convention: the schema's own document order. Mutually exclusive alternatives (a content
+ * control's type, a cell's markup record) are listed in that same order, since only one of them
+ * can ever stand there.
+ *
+ * A name is the local part alone, as `Props` carries it, which is also how the two children
+ * `w:settings` takes from other namespaces (`m:mathPr`, `sl:schemaLibrary`) are spelled here.
+ */
+interface ChildOrder {
+    readonly type: string;
+    readonly order: readonly string[];
+}
+export declare const CHILD_ORDER: Readonly<Record<string, ChildOrder>>;
+/**
+ * The order the children of this parent go in.
+ *
+ * A nested parent is asked for first (`pPr/rPr` is CT_ParaRPr, which puts a track-change record
+ * ahead of what a run's own `w:rPr` holds), so naming the enclosing element is what picks the
+ * right one of two entries for the same element name.
+ *
+ * Throws for a parent no entry covers, because a writer editing an element this registry has
+ * never seen would otherwise place its children by nothing at all.
+ */
+export declare function childOrderOf(name: string, parent?: string): readonly string[];
+export {};

package/dist/ooxml/childOrder.js

@@ -0,0 +1,496 @@
+// src/ooxml/childOrder.ts
+var CHILD_ORDER = {
+  // EG_RPrBase's choice, then rPrChange
+  rPr: {
+    type: "CT_RPr",
+    order: [
+      "rStyle",
+      "rFonts",
+      "b",
+      "bCs",
+      "i",
+      "iCs",
+      "caps",
+      "smallCaps",
+      "strike",
+      "dstrike",
+      "outline",
+      "shadow",
+      "emboss",
+      "imprint",
+      "noProof",
+      "snapToGrid",
+      "vanish",
+      "webHidden",
+      "color",
+      "spacing",
+      "w",
+      "kern",
+      "position",
+      "sz",
+      "szCs",
+      "highlight",
+      "u",
+      "effect",
+      "bdr",
+      "shd",
+      "fitText",
+      "vertAlign",
+      "rtl",
+      "cs",
+      "em",
+      "lang",
+      "eastAsianLayout",
+      "specVanish",
+      "oMath",
+      "rPrChange"
+    ]
+  },
+  // the track-change record first, then EG_RPrBase's choice
+  "pPr/rPr": {
+    type: "CT_ParaRPr",
+    order: [
+      "ins",
+      "del",
+      "moveFrom",
+      "moveTo",
+      "rStyle",
+      "rFonts",
+      "b",
+      "bCs",
+      "i",
+      "iCs",
+      "caps",
+      "smallCaps",
+      "strike",
+      "dstrike",
+      "outline",
+      "shadow",
+      "emboss",
+      "imprint",
+      "noProof",
+      "snapToGrid",
+      "vanish",
+      "webHidden",
+      "color",
+      "spacing",
+      "w",
+      "kern",
+      "position",
+      "sz",
+      "szCs",
+      "highlight",
+      "u",
+      "effect",
+      "bdr",
+      "shd",
+      "fitText",
+      "vertAlign",
+      "rtl",
+      "cs",
+      "em",
+      "lang",
+      "eastAsianLayout",
+      "specVanish",
+      "oMath",
+      "rPrChange"
+    ]
+  },
+  pPr: {
+    type: "CT_PPr",
+    order: [
+      "pStyle",
+      "keepNext",
+      "keepLines",
+      "pageBreakBefore",
+      "framePr",
+      "widowControl",
+      "numPr",
+      "suppressLineNumbers",
+      "pBdr",
+      "shd",
+      "tabs",
+      "suppressAutoHyphens",
+      "kinsoku",
+      "wordWrap",
+      "overflowPunct",
+      "topLinePunct",
+      "autoSpaceDE",
+      "autoSpaceDN",
+      "bidi",
+      "adjustRightInd",
+      "snapToGrid",
+      "spacing",
+      "ind",
+      "contextualSpacing",
+      "mirrorIndents",
+      "suppressOverlap",
+      "jc",
+      "textDirection",
+      "textAlignment",
+      "textboxTightWrap",
+      "outlineLvl",
+      "divId",
+      "cnfStyle",
+      "rPr",
+      "sectPr",
+      "pPrChange"
+    ]
+  },
+  tcPr: {
+    type: "CT_TcPr",
+    order: [
+      "cnfStyle",
+      "tcW",
+      "gridSpan",
+      "hMerge",
+      "vMerge",
+      "tcBorders",
+      "shd",
+      "noWrap",
+      "tcMar",
+      "textDirection",
+      "tcFitText",
+      "vAlign",
+      "hideMark",
+      "headers",
+      "cellIns",
+      "cellDel",
+      "cellMerge",
+      "tcPrChange"
+    ]
+  },
+  // CT_TrPrBase's choice, then the track-change record
+  trPr: {
+    type: "CT_TrPr",
+    order: [
+      "cnfStyle",
+      "divId",
+      "gridBefore",
+      "gridAfter",
+      "wBefore",
+      "wAfter",
+      "cantSplit",
+      "trHeight",
+      "tblHeader",
+      "tblCellSpacing",
+      "jc",
+      "hidden",
+      "ins",
+      "del",
+      "trPrChange"
+    ]
+  },
+  tblPr: {
+    type: "CT_TblPr",
+    order: [
+      "tblStyle",
+      "tblpPr",
+      "tblOverlap",
+      "bidiVisual",
+      "tblStyleRowBandSize",
+      "tblStyleColBandSize",
+      "tblW",
+      "jc",
+      "tblCellSpacing",
+      "tblInd",
+      "tblBorders",
+      "shd",
+      "tblLayout",
+      "tblCellMar",
+      "tblLook",
+      "tblCaption",
+      "tblDescription",
+      "tblPrChange"
+    ]
+  },
+  tcBorders: {
+    type: "CT_TcBorders",
+    order: [
+      "top",
+      "start",
+      "left",
+      "bottom",
+      "end",
+      "right",
+      "insideH",
+      "insideV",
+      "tl2br",
+      "tr2bl"
+    ]
+  },
+  tblBorders: {
+    type: "CT_TblBorders",
+    order: [
+      "top",
+      "start",
+      "left",
+      "bottom",
+      "end",
+      "right",
+      "insideH",
+      "insideV"
+    ]
+  },
+  pBdr: {
+    type: "CT_PBdr",
+    order: ["top", "left", "bottom", "right", "between", "bar"]
+  },
+  tcMar: {
+    type: "CT_TcMar",
+    order: ["top", "start", "left", "bottom", "end", "right"]
+  },
+  tblCellMar: {
+    type: "CT_TblCellMar",
+    order: ["top", "start", "left", "bottom", "end", "right"]
+  },
+  // CT_SdtRun lays the same three down
+  sdt: {
+    type: "CT_SdtBlock",
+    order: ["sdtPr", "sdtEndPr", "sdtContent"]
+  },
+  sdtPr: {
+    type: "CT_SdtPr",
+    order: [
+      "rPr",
+      "alias",
+      "tag",
+      "id",
+      "lock",
+      "placeholder",
+      "temporary",
+      "showingPlcHdr",
+      "dataBinding",
+      "label",
+      "tabIndex",
+      "equation",
+      "comboBox",
+      "date",
+      "docPartObj",
+      "docPartList",
+      "dropDownList",
+      "picture",
+      "richText",
+      "text",
+      "citation",
+      "group",
+      "bibliography"
+    ]
+  },
+  sectPr: {
+    type: "CT_SectPr",
+    order: [
+      "headerReference",
+      "footerReference",
+      "footnotePr",
+      "endnotePr",
+      "type",
+      "pgSz",
+      "pgMar",
+      "paperSrc",
+      "pgBorders",
+      "lnNumType",
+      "pgNumType",
+      "cols",
+      "formProt",
+      "vAlign",
+      "noEndnote",
+      "titlePg",
+      "textDirection",
+      "bidi",
+      "rtlGutter",
+      "docGrid",
+      "printerSettings",
+      "sectPrChange"
+    ]
+  },
+  numPr: {
+    type: "CT_NumPr",
+    order: ["ilvl", "numId", "numberingChange", "ins"]
+  },
+  lvl: {
+    type: "CT_Lvl",
+    order: [
+      "start",
+      "numFmt",
+      "lvlRestart",
+      "pStyle",
+      "isLgl",
+      "suff",
+      "lvlText",
+      "lvlPicBulletId",
+      "legacy",
+      "lvlJc",
+      "pPr",
+      "rPr"
+    ]
+  },
+  abstractNum: {
+    type: "CT_AbstractNum",
+    order: [
+      "nsid",
+      "multiLevelType",
+      "tmpl",
+      "name",
+      "styleLink",
+      "numStyleLink",
+      "lvl"
+    ]
+  },
+  num: {
+    type: "CT_Num",
+    order: ["abstractNumId", "lvlOverride"]
+  },
+  numbering: {
+    type: "CT_Numbering",
+    order: ["numPicBullet", "abstractNum", "num", "numIdMacAtCleanup"]
+  },
+  tblStylePr: {
+    type: "CT_TblStylePr",
+    order: ["pPr", "rPr", "tblPr", "trPr", "tcPr"]
+  },
+  style: {
+    type: "CT_Style",
+    order: [
+      "name",
+      "aliases",
+      "basedOn",
+      "next",
+      "link",
+      "autoRedefine",
+      "hidden",
+      "uiPriority",
+      "semiHidden",
+      "unhideWhenUsed",
+      "qFormat",
+      "locked",
+      "personal",
+      "personalCompose",
+      "personalReply",
+      "rsid",
+      "pPr",
+      "rPr",
+      "tblPr",
+      "trPr",
+      "tcPr",
+      "tblStylePr"
+    ]
+  },
+  settings: {
+    type: "CT_Settings",
+    order: [
+      "writeProtection",
+      "view",
+      "zoom",
+      "removePersonalInformation",
+      "removeDateAndTime",
+      "doNotDisplayPageBoundaries",
+      "displayBackgroundShape",
+      "printPostScriptOverText",
+      "printFractionalCharacterWidth",
+      "printFormsData",
+      "embedTrueTypeFonts",
+      "embedSystemFonts",
+      "saveSubsetFonts",
+      "saveFormsData",
+      "mirrorMargins",
+      "alignBordersAndEdges",
+      "bordersDoNotSurroundHeader",
+      "bordersDoNotSurroundFooter",
+      "gutterAtTop",
+      "hideSpellingErrors",
+      "hideGrammaticalErrors",
+      "activeWritingStyle",
+      "proofState",
+      "formsDesign",
+      "attachedTemplate",
+      "linkStyles",
+      "stylePaneFormatFilter",
+      "stylePaneSortMethod",
+      "documentType",
+      "mailMerge",
+      "revisionView",
+      "trackRevisions",
+      "doNotTrackMoves",
+      "doNotTrackFormatting",
+      "documentProtection",
+      "autoFormatOverride",
+      "styleLockTheme",
+      "styleLockQFSet",
+      "defaultTabStop",
+      "autoHyphenation",
+      "consecutiveHyphenLimit",
+      "hyphenationZone",
+      "doNotHyphenateCaps",
+      "showEnvelope",
+      "summaryLength",
+      "clickAndTypeStyle",
+      "defaultTableStyle",
+      "evenAndOddHeaders",
+      "bookFoldRevPrinting",
+      "bookFoldPrinting",
+      "bookFoldPrintingSheets",
+      "drawingGridHorizontalSpacing",
+      "drawingGridVerticalSpacing",
+      "displayHorizontalDrawingGridEvery",
+      "displayVerticalDrawingGridEvery",
+      "doNotUseMarginsForDrawingGridOrigin",
+      "drawingGridHorizontalOrigin",
+      "drawingGridVerticalOrigin",
+      "doNotShadeFormData",
+      "noPunctuationKerning",
+      "characterSpacingControl",
+      "printTwoOnOne",
+      "strictFirstAndLastChars",
+      "noLineBreaksAfter",
+      "noLineBreaksBefore",
+      "savePreviewPicture",
+      "doNotValidateAgainstSchema",
+      "saveInvalidXml",
+      "ignoreMixedContent",
+      "alwaysShowPlaceholderText",
+      "doNotDemarcateInvalidXml",
+      "saveXmlDataOnly",
+      "useXSLTWhenSaving",
+      "saveThroughXslt",
+      "showXMLTags",
+      "alwaysMergeEmptyNamespace",
+      "updateFields",
+      "hdrShapeDefaults",
+      "footnotePr",
+      "endnotePr",
+      "compat",
+      "docVars",
+      "rsids",
+      "mathPr",
+      "attachedSchema",
+      "themeFontLang",
+      "clrSchemeMapping",
+      "doNotIncludeSubdocsInStats",
+      "doNotAutoCompressPictures",
+      "forceUpgrade",
+      "captions",
+      "readModeInkLockDown",
+      "smartTagType",
+      "schemaLibrary",
+      "shapeDefaults",
+      "doNotEmbedSmartTags",
+      "decimalSymbol",
+      "listSeparator"
+    ]
+  }
+};
+function childOrderOf(name, parent) {
+  const nested = parent === void 0 ? void 0 : CHILD_ORDER[`${parent}/${name}`];
+  const order = nested ?? CHILD_ORDER[name];
+  if (!order) {
+    throw new Error(
+      `no child order is registered for ${name}; add it to CHILD_ORDER`
+    );
+  }
+  return order.order;
+}
+export {
+  CHILD_ORDER,
+  childOrderOf
+};

package/dist/ooxml/conformance.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Which conformance class a package is written in, and whether its main part is one this editor
+ * can write back into. Both are settled once, when the file is opened.
+ *
+ * ECMA-376 defines two document conformance classes, Strict (Part 1 §2.1) and Transitional
+ * (Part 4 §2.1). They describe the same vocabulary under different names: the main document part's
+ * root namespace and the relationship the package reaches it through differ between the two
+ * (Part 1 §11.3.10, Part 4 §9.2.10). This editor supports a subset of Transitional. Strict is
+ * refused explicitly so that its markup is never read using Transitional assumptions.
+ *
+ * A namespace prefix is the producer's own choice and carries no meaning of its own, so readers
+ * identify markup by namespace URI and local name. The WordprocessingML writer emits `w`
+ * (`ooxml/names`), so the main part's root must bind that prefix to the Transitional namespace.
+ */
+/** The WordprocessingML namespace of a Strict main document part (Part 1 §11.3.10) */
+export declare const STRICT_W_NS = "http://purl.oclc.org/ooxml/wordprocessingml/main";
+/** The relationship a Strict package reaches its main document part through (Part 1 §11.3.10) */
+export declare const STRICT_OFFICE_DOCUMENT_REL = "http://purl.oclc.org/ooxml/officeDocument/relationships/officeDocument";
+export type Conformance = "transitional" | "strict";
+/** The class this main part root is written in, null for a root of neither vocabulary */
+export declare function conformanceOf(root: Element): Conformance | null;
+/**
+ * Whether the root binds the prefix every writer emits (`w`) to the WordprocessingML namespace.
+ *
+ * A root has nothing above it to inherit a declaration from, so what it writes itself is the whole
+ * answer. A default namespace or another prefix alone does not bind `w`.
+ */
+export declare function bindsWritingPrefix(root: Element): boolean;

package/dist/ooxml/conformance.js

@@ -0,0 +1,20 @@
+// src/ooxml/conformance.ts
+import { W_NS, W_PREFIX } from "./names.js";
+var STRICT_W_NS = "http://purl.oclc.org/ooxml/wordprocessingml/main";
+var STRICT_OFFICE_DOCUMENT_REL = "http://purl.oclc.org/ooxml/officeDocument/relationships/officeDocument";
+function conformanceOf(root) {
+  if (root.namespaceURI === W_NS) return "transitional";
+  if (root.namespaceURI === STRICT_W_NS) return "strict";
+  return null;
+}
+function bindsWritingPrefix(root) {
+  return Array.from(root.attributes).some(
+    (attr) => attr.name === `xmlns:${W_PREFIX}` && attr.value === W_NS
+  );
+}
+export {
+  STRICT_OFFICE_DOCUMENT_REL,
+  STRICT_W_NS,
+  bindsWritingPrefix,
+  conformanceOf
+};