@portone/docx-editor 0.2.1 → 0.3.0

package/dist/numbering/writeNumbering.d.ts

@@ -1,10 +1,9 @@
 /**
  * Splices the definitions of newly started lists into the original numbering.xml.
  *
- * Not one character of the original is altered; new elements are merely slotted in at
- * two places.
- * OOXML requires the definitions (`abstractNum`) to come before the numbers (`num`), so
- * the definitions go in front of the first number and the numbers go at the very end.
+ * Not one character of the original is altered; new elements are merely slotted in.
+ * OOXML requires the definitions (`abstractNum`) to come before the numbers (`num`), and
+ * `CHILD_ORDER.numbering` is what places each where it belongs among what the part holds.
  */
 /**
  * numbering.xml with a standard template definition added for every list number.

package/dist/numbering/writeNumbering.js

@@ -1,18 +1,8 @@
 // src/numbering/writeNumbering.ts
-import { DocxExportError } from "../ooxml/errors.js";
+import { splicePart } from "../ooxml/partSplice.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;
-}
-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)) {
@@ -24,25 +14,24 @@ function maxAbstractNumId(xml) {
 }
 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) => ({
     numId,
     abstractNumId: firstAbstractNumId + index
   }));
-  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, listKindOf(added.numId))
+      })),
+      ...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/element.d.ts

@@ -5,8 +5,12 @@
  * arrived with is carried around as its original text, and an edit swaps out one element or one
  * attribute of it. Rebuilding a parsed element instead would rewrite markup nobody touched.
  *
- * An attribute is matched by its local part rather than by its written name, so a document that
- * bound the WordprocessingML namespace to a prefix of its own is edited in the spelling it chose.
+ * An attribute is read and written as the WordprocessingML attribute of a local name: the one
+ * spelled under the `w` prefix, which `RESERVED_PREFIXES` pins to that namespace in every fragment,
+ * or failing that an unprefixed one, which is what `wAttr` accepted off a parsed fragment too. An
+ * attribute another prefix qualifies belongs to some other vocabulary, so it is neither read as the
+ * formatting value nor written over when it happens to share the local name (`x:val` beside
+ * `w:val`). The two readers below are named for which of those they answer.
  */
 import { type KnownPrefix } from "./names";
 /** One attribute as it is written: the whole name, prefix included, and the value before escaping */
@@ -26,16 +30,30 @@ export declare function elementXml(name: string, attrs: readonly XmlAttr[], chil
  * the prefix itself.
  */
 export declare function xmlnsAttr(prefix: KnownPrefix): XmlAttr;
+/** The same for the WordprocessingML vocabulary, which is the one almost everything is written in */
+export declare function wLocalName(name: string): string | null;
 /**
- * The attributes with the one of this local name written as `value`, or removed when it is null.
+ * The value of the WordprocessingML attribute of this local name, and null for an element that
+ * carries none. An attribute of the same local name under another prefix is not it.
+ */
+export declare function wAttrValue(attrs: readonly XmlAttr[], localName: string): string | null;
+/**
+ * The attributes with the WordprocessingML one of this local name written as `value`, or removed
+ * when it is null.
  *
  * One already there keeps the slot it sat in and the name it was written under, so an edited
  * element reads as the original did. One that is not there yet goes on the end under the `w`
- * prefix.
+ * prefix, and one of the same local name under another prefix stands untouched beside it.
  */
 export declare function withAttr(attrs: readonly XmlAttr[], name: string, value: string | null): XmlAttr[];
-export declare function withoutAttrs(attrs: readonly XmlAttr[], localNames: readonly string[]): XmlAttr[];
-export declare function attrValue(attrs: readonly XmlAttr[], localName: string): string | null;
+/**
+ * The attributes without the ones of these local names, in either spelling.
+ *
+ * The names are read under the WordprocessingML vocabulary unless another prefix is named, which
+ * is what reaches the handful of attributes Word writes beside it: `w14:paraId` is a name under
+ * `w14` and no more a `w:` attribute than `x:val` is.
+ */
+export declare function withoutAttrs(attrs: readonly XmlAttr[], localNames: readonly string[], prefix?: KnownPrefix): XmlAttr[];
 /**
  * An opening tag whose attributes are the ones the original wrote.
  *
@@ -45,8 +63,3 @@ export declare function attrValue(attrs: readonly XmlAttr[], localName: string):
 export declare function openTagXml(name: string, rawAttrs: string | null): string;
 /** The same for an element that closes on its own */
 export declare function emptyTagXml(name: string, rawAttrs: string | null): string;
-/**
- * The attributes of a parsed element as pairs, for a caller that still holds the element rather
- * than its text.
- */
-export declare function attrPairs(el: Element | null): XmlAttr[];