@portone/docx-editor 0.2.1 → 0.4.0

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[];

package/dist/ooxml/element.js

@@ -1,5 +1,10 @@
 // src/ooxml/element.ts
-import { NAMESPACES, wName } from "./names.js";
+import {
+  NAMESPACES,
+  qualify,
+  W_PREFIX,
+  wName
+} from "./names.js";
 import { escapeXml, localPart } from "./xml.js";
 function attrsText(attrs) {
   return attrs.map(([name, value]) => `${name}="${escapeXml(value)}"`).join(" ");
@@ -13,19 +18,36 @@ function elementXml(name, attrs, children = []) {
 function xmlnsAttr(prefix) {
   return [`xmlns:${prefix}`, NAMESPACES[prefix]];
 }
+function localNameUnder(prefix, name) {
+  if (!name.includes(":")) return name;
+  const local = localPart(name);
+  return name === qualify(prefix, local) ? local : null;
+}
+function wLocalName(name) {
+  return localNameUnder(W_PREFIX, name);
+}
+function wAttrIndex(attrs, localName) {
+  const qualified = attrs.findIndex(([name]) => name === wName(localName));
+  if (qualified !== -1) return qualified;
+  return attrs.findIndex(([name]) => name === localName);
+}
+function wAttrValue(attrs, localName) {
+  const at = wAttrIndex(attrs, localName);
+  return at === -1 ? null : attrs[at][1];
+}
 function withAttr(attrs, name, value) {
   if (value === null) return withoutAttrs(attrs, [name]);
-  const at = attrs.findIndex(([attr]) => localPart(attr) === name);
+  const at = wAttrIndex(attrs, name);
   if (at === -1) return [...attrs, [wName(name), value]];
   return attrs.map(
     (attr, index) => index === at ? [attr[0], value] : attr
   );
 }
-function withoutAttrs(attrs, localNames) {
-  return attrs.filter(([name]) => !localNames.includes(localPart(name)));
-}
-function attrValue(attrs, localName) {
-  return attrs.find(([name]) => localPart(name) === localName)?.[1] ?? null;
+function withoutAttrs(attrs, localNames, prefix = W_PREFIX) {
+  return attrs.filter(([name]) => {
+    const local = localNameUnder(prefix, name);
+    return local === null || !localNames.includes(local);
+  });
 }
 function openTagXml(name, rawAttrs) {
   return rawAttrs ? `<${name} ${rawAttrs}>` : `<${name}>`;
@@ -33,16 +55,13 @@ function openTagXml(name, rawAttrs) {
 function emptyTagXml(name, rawAttrs) {
   return rawAttrs ? `<${name} ${rawAttrs}/>` : `<${name}/>`;
 }
-function attrPairs(el) {
-  return el ? Array.from(el.attributes, (attr) => [attr.name, attr.value]) : [];
-}
 export {
-  attrPairs,
-  attrValue,
   attrsText,
   elementXml,
   emptyTagXml,
   openTagXml,
+  wAttrValue,
+  wLocalName,
   withAttr,
   withoutAttrs,
   xmlnsAttr

package/dist/ooxml/errors.d.ts

@@ -8,14 +8,16 @@
 /**
  * Why a document could not be opened.
  *
+ * - `no-xml-parser`: the runtime has no XML parser to read the package with. The one code here that is about where the call was made rather than about the file
  * - `not-a-docx`: the bytes are not a readable zip container, its entry names are not a package's, or an entry does not hold what it says it does
  * - `too-large`: the package asks to inflate to more than we open
  * - `missing-part`: the package has no main document part to read
  * - `missing-body`: the main part carries no `w:body`
  * - `malformed-xml`: the XML cannot be parsed, declares a DTD, or its markup is inconsistent
+ * - `unsupported-conformance`: the package is an ECMA-376 Strict one, and this editor reads Transitional
  * - `unsupported-content`: the document holds markup we cannot write back out unchanged
  */
-export type DocxImportErrorCode = "not-a-docx" | "too-large" | "missing-part" | "missing-body" | "malformed-xml" | "unsupported-content";
+export type DocxImportErrorCode = "no-xml-parser" | "not-a-docx" | "too-large" | "missing-part" | "missing-body" | "malformed-xml" | "unsupported-conformance" | "unsupported-content";
 /** Thrown when we hit a document whose content cannot be kept safely. We refuse to open it instead of losing it silently */
 export declare class DocxImportError extends Error {
     readonly code: DocxImportErrorCode;
@@ -24,14 +26,13 @@ export declare class DocxImportError extends Error {
 /**
  * Why a document could not be written back out.
  *
- * - `missing-numbering-part`: a new list needs a numbering.xml the document does not have
- * - `missing-content-types`: a new image needs a [Content_Types].xml the package does not have
- * - `unsupported-content`: the document holds a node kind we have no way to serialize
+ * - `missing-content-types`: a part the writer adds, be it an image, a list definition or a comment, needs a [Content_Types].xml the package does not have
+ * - `unsupported-content`: the document holds something no correct file can be written from: a node kind we have no way to serialize, a preserved block standing in two places, which has one original XML to write, or a paragraph in a list nothing defines
  * - `lost-original`: a node that only carries its original XML has lost it
  * - `malformed-xml`: an original XML fragment cannot be read well enough to rewrite
  * - `invalid-table`: the table grid is inconsistent, e.g. a vertical merge outliving its rows
  */
-export type DocxExportErrorCode = "missing-numbering-part" | "missing-content-types" | "unsupported-content" | "lost-original" | "malformed-xml" | "invalid-table";
+export type DocxExportErrorCode = "missing-content-types" | "unsupported-content" | "lost-original" | "malformed-xml" | "invalid-table";
 /** Thrown when an edited document cannot be written back out without losing or corrupting content */
 export declare class DocxExportError extends Error {
     readonly code: DocxExportErrorCode;

package/dist/ooxml/image.d.ts

@@ -10,6 +10,10 @@
  *
  * An imported image holds on to its whole original `<w:drawing>` XML, so an untouched
  * image goes back out byte for byte. A resize rewrites nothing but the two extents.
+ *
+ * `emuToPx` is imported on its own by a builder working in pixels, so nothing here reads
+ * `NAMESPACES` at the top level: a top-level read is an impure statement a bundler keeps,
+ * and it would hold the naming layer in a bundle that wanted one multiplication.
  */
 /**
  * English Metric Units, the unit every DrawingML length is written in.

package/dist/ooxml/image.js

@@ -43,7 +43,6 @@ function toImageExtent(value) {
   const cy = positiveInt(value.cy);
   return cx === null || cy === null ? null : { cx, cy };
 }
-var PICTURE_URI = NAMESPACES.pic;
 function childOf(el, name) {
   return el ? childByLocalName(el, name) : null;
 }
@@ -63,7 +62,7 @@ function readDrawingPicture(drawing) {
   const extent = readExtent(childOf(inline, "extent"));
   if (!extent) return null;
   const graphicData = childOf(childOf(inline, "graphic"), "graphicData");
-  if (!graphicData || graphicData.getAttribute("uri") !== PICTURE_URI) {
+  if (!graphicData || graphicData.getAttribute("uri") !== NAMESPACES.pic) {
     return null;
   }
   const blip = childOf(
@@ -83,13 +82,11 @@ function withExtent(xml, extent) {
   const size = `cx="${extent.cx}" cy="${extent.cy}"`;
   return xml.replace(EXTENT_TAG, (_match, prefix) => `<${prefix ?? ""}extent ${size}/>`).replace(EXT_TAG, (_match, prefix) => `<${prefix ?? ""}ext ${size}/>`);
 }
-var WP_NS = NAMESPACES.wp;
-var A_NS = NAMESPACES.a;
 function imageDrawingXml(image) {
   const size = `cx="${image.extent.cx}" cy="${image.extent.cy}"`;
   const name = `Picture ${image.docPrId}`;
   const descr = image.alt === null ? "" : ` descr="${escapeXml(image.alt)}"`;
-  return `<w:drawing><wp:inline xmlns:wp="${WP_NS}" distT="0" distB="0" distL="0" distR="0"><wp:extent ${size}/><wp:effectExtent l="0" t="0" r="0" b="0"/><wp:docPr id="${image.docPrId}" name="${name}"${descr}/><wp:cNvGraphicFramePr><a:graphicFrameLocks xmlns:a="${A_NS}" noChangeAspect="1"/></wp:cNvGraphicFramePr><a:graphic xmlns:a="${A_NS}"><a:graphicData uri="${PICTURE_URI}"><pic:pic xmlns:pic="${PICTURE_URI}"><pic:nvPicPr><pic:cNvPr id="${image.docPrId}" name="${name}"${descr}/><pic:cNvPicPr/></pic:nvPicPr><pic:blipFill><a:blip xmlns:r="${R_NS}" r:embed="${escapeXml(image.relId)}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext ${size}/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing>`;
+  return `<w:drawing><wp:inline xmlns:wp="${NAMESPACES.wp}" distT="0" distB="0" distL="0" distR="0"><wp:extent ${size}/><wp:effectExtent l="0" t="0" r="0" b="0"/><wp:docPr id="${image.docPrId}" name="${name}"${descr}/><wp:cNvGraphicFramePr><a:graphicFrameLocks xmlns:a="${NAMESPACES.a}" noChangeAspect="1"/></wp:cNvGraphicFramePr><a:graphic xmlns:a="${NAMESPACES.a}"><a:graphicData uri="${NAMESPACES.pic}"><pic:pic xmlns:pic="${NAMESPACES.pic}"><pic:nvPicPr><pic:cNvPr id="${image.docPrId}" name="${name}"${descr}/><pic:cNvPicPr/></pic:nvPicPr><pic:blipFill><a:blip xmlns:r="${R_NS}" r:embed="${escapeXml(image.relId)}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext ${size}/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing>`;
 }
 export {
   EMU_PER_PX,

package/dist/ooxml/names.d.ts

@@ -6,6 +6,13 @@
  * here, and the part a fragment is spliced into declares the same binding, so the prefix is
  * decided once rather than at every call site.
  */
+/** The wordprocessing namespace that every element we read lives in */
+export declare const W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+/**
+ * The relationship namespace. It is both where the `r:embed` attributes live and the base
+ * every relationship type name is built on
+ */
+export declare const R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
 /** The prefix every WordprocessingML element and attribute this package writes carries */
 export declare const W_PREFIX = "w";
 export declare const NAMESPACES: {
@@ -19,6 +26,8 @@ export declare const NAMESPACES: {
     readonly pic: "http://schemas.openxmlformats.org/drawingml/2006/picture";
 };
 export type KnownPrefix = keyof typeof NAMESPACES;
+/** Whether this is a prefix the package has a namespace for, rather than one a document brought */
+export declare function isKnownPrefix(prefix: string): prefix is KnownPrefix;
 /** The name `local` goes out under (`qualify("w15", "commentEx")` -> `w15:commentEx`) */
 export declare function qualify(prefix: KnownPrefix, local: string): string;
 /** `wName("val")` -> `w:val`. The one place the written WordprocessingML prefix is decided */

package/dist/ooxml/names.js

@@ -1,5 +1,6 @@
 // src/ooxml/names.ts
-import { R_NS, W_NS } from "./xml.js";
+var W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+var R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
 var W_PREFIX = "w";
 var NAMESPACES = {
   w: W_NS,
@@ -11,6 +12,9 @@ var NAMESPACES = {
   a: "http://schemas.openxmlformats.org/drawingml/2006/main",
   pic: "http://schemas.openxmlformats.org/drawingml/2006/picture"
 };
+function isKnownPrefix(prefix) {
+  return Object.hasOwn(NAMESPACES, prefix);
+}
 function qualify(prefix, local) {
   return `${prefix}:${local}`;
 }
@@ -22,7 +26,10 @@ function xmlnsDecl(prefix) {
 }
 export {
   NAMESPACES,
+  R_NS,
+  W_NS,
   W_PREFIX,
+  isKnownPrefix,
   qualify,
   wName,
   xmlnsDecl

package/dist/ooxml/partSplice.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Putting children into the root element of a package part, and leaving every byte around them as
+ * the part arrived with.
+ *
+ * A part is text the writers cut and join, never a tree they build again, so the spots to cut at
+ * are found in the text: the root's opening tag past the prolog, and its closing tag counted to
+ * by depth. Searching for the closing tag instead would take a `</Relationships>` inside a
+ * comment for the end of the part, and miss the root altogether when it is written under a
+ * prefix or closes on itself.
+ */
+import type { KnownPrefix } from "./names";
+/** One child to put into a part, named by the local part of its tag so the child order can place it */
+export interface PartChild {
+    name: string;
+    xml: string;
+}
+/**
+ * What goes into a part's root. Every field is optional and they compose: the children are
+ * replaced first, then the inserts are placed among them, then the prepend and the append go on
+ * either end, and last the opening tag is rewritten.
+ */
+export interface PartSplice {
+    /** The root's local name. Any prefix, a self-closing root, a prolog and comments are all handled */
+    root: string;
+    /** Children put at the spot `CHILD_ORDER[root]` lays down, ahead of the first child that order puts after them */
+    insert?: readonly PartChild[];
+    /** Put in as the last children */
+    append?: string;
+    /** Put in right after the opening tag */
+    prepend?: string;
+    /** Written in place of every child */
+    replaceChildren?: string;
+    /**
+     * Rewrites the opening tag, handed as it is about to be written: opened when children go into a
+     * root that closed on itself, else as it arrived.
+     */
+    rootTag?: (open: string) => string;
+}
+/**
+ * Why the part cannot be spliced around its root, or null when it can. The same refusal
+ * `splicePart` throws, so a caller may ask ahead and be answered in the same words.
+ */
+export declare function partRootProblem(xml: string, root: string): string | null;
+/**
+ * The part with the children of `splice` put into its root, and every byte outside what was put
+ * in standing as it arrived. A root that closed on itself is opened to hold them.
+ *
+ * Throws `malformed-xml` naming the part when the root is not there or never closes.
+ */
+export declare function splicePart(xml: string, splice: PartSplice): string;
+/**
+ * The prefix the root's name carries, colon included, so a child written beside the ones the part
+ * holds is spelled the way the root is. Empty for a root written under the default namespace, and
+ * for a part with no root, which the splice that follows refuses.
+ */
+export declare function rootPrefixOf(xml: string): string;
+export interface RootDeclarations {
+    /** The prefixes the root has to bind, and what to bind each to where it does not yet */
+    namespaces: Partial<Record<KnownPrefix, string>>;
+    /** The tokens `mc:Ignorable` has to name, added to the ones it names already */
+    ignorable?: readonly string[];
+}
+/**
+ * The part with its root binding every prefix named and its `mc:Ignorable` naming every token
+ * asked for, each declared once: a matching declaration is preserved, and a conflicting binding is refused.
+ */
+export declare function ensureRootDeclarations(xml: string, declarations: RootDeclarations): string;

package/dist/ooxml/partSplice.js

@@ -0,0 +1,176 @@
+// src/ooxml/partSplice.ts
+import { childOrderOf } from "./childOrder.js";
+import { attrsText } from "./element.js";
+import { DocxExportError } from "./errors.js";
+import { parseAttrs, readTag, rootTagAt } from "./tagScan.js";
+import { localPart } from "./xml.js";
+function closingTagAt(xml, open) {
+  let depth = 1;
+  let at = open.end;
+  for (; ; ) {
+    const lt = xml.indexOf("<", at);
+    if (lt === -1) return null;
+    const tag = readTag(xml, lt);
+    if (tag === null) return null;
+    if (tag.kind === "open") depth += 1;
+    if (tag.kind === "close") {
+      depth -= 1;
+      if (depth === 0) return tag.name === open.name ? lt : null;
+    }
+    at = tag.end;
+  }
+}
+function readRoot(xml, root) {
+  const openAt = rootTagAt(xml);
+  const open = openAt === -1 ? null : readTag(xml, openAt);
+  if (open === null || open.kind === "close" || localPart(open.name) !== root) {
+    return { problem: `the ${root} part has no ${root} root element` };
+  }
+  if (open.kind === "empty") return { root: { openAt, open, closeAt: null } };
+  const closeAt = closingTagAt(xml, open);
+  if (closeAt === null) {
+    return { problem: `the ${root} part has no closing ${root} tag` };
+  }
+  return { root: { openAt, open, closeAt } };
+}
+function partRootProblem(xml, root) {
+  const reading = readRoot(xml, root);
+  return "problem" in reading ? reading.problem : null;
+}
+function directChildren(inner) {
+  const children = [];
+  let depth = 0;
+  let at = 0;
+  for (; ; ) {
+    const lt = inner.indexOf("<", at);
+    if (lt === -1) return children;
+    const tag = readTag(inner, lt);
+    if (tag === null) return children;
+    if (depth === 0 && (tag.kind === "open" || tag.kind === "empty")) {
+      children.push({ name: localPart(tag.name), at: lt });
+    }
+    if (tag.kind === "open") depth += 1;
+    if (tag.kind === "close") depth -= 1;
+    at = tag.end;
+  }
+}
+function insertionAt(children, name, order, root, end) {
+  const target = order.indexOf(name);
+  if (target === -1) {
+    throw new Error(
+      `${name} is not a child the order of ${root} knows; add it to CHILD_ORDER`
+    );
+  }
+  const after = children.find((child) => order.indexOf(child.name) > target);
+  return after === void 0 ? end : after.at;
+}
+function withInserted(inner, inserts, root) {
+  if (inserts.length === 0) return inner;
+  const order = childOrderOf(root);
+  const children = directChildren(inner);
+  const placed = inserts.map((child) => ({
+    at: insertionAt(children, child.name, order, root, inner.length),
+    xml: child.xml,
+    rank: order.indexOf(child.name)
+  })).sort((a, b) => a.at - b.at || a.rank - b.rank);
+  let out = "";
+  let from = 0;
+  for (const { at, xml } of placed) {
+    out += inner.slice(from, at) + xml;
+    from = at;
+  }
+  return out + inner.slice(from);
+}
+function splicePart(xml, splice) {
+  const reading = readRoot(xml, splice.root);
+  if ("problem" in reading) {
+    throw new DocxExportError("malformed-xml", reading.problem);
+  }
+  const { openAt, open, closeAt } = reading.root;
+  const inner = closeAt === null ? "" : xml.slice(open.end, closeAt);
+  const children = (splice.prepend ?? "") + withInserted(
+    splice.replaceChildren ?? inner,
+    splice.insert ?? [],
+    splice.root
+  ) + (splice.append ?? "");
+  const openTag = xml.slice(openAt, open.end);
+  const opened = closeAt === null && children !== "" ? `${openTag.slice(0, -2)}>` : openTag;
+  const head = xml.slice(0, openAt) + (splice.rootTag?.(opened) ?? opened);
+  if (closeAt !== null) return head + children + xml.slice(closeAt);
+  if (children === "") return head + xml.slice(open.end);
+  return `${head}${children}</${open.name}>${xml.slice(open.end)}`;
+}
+function rootNameOf(xml) {
+  const at = rootTagAt(xml);
+  const open = at === -1 ? null : readTag(xml, at);
+  return open === null || open.kind === "close" ? null : open.name;
+}
+function rootPrefixOf(xml) {
+  const name = rootNameOf(xml) ?? "";
+  const colon = name.indexOf(":");
+  return colon === -1 ? "" : name.slice(0, colon + 1);
+}
+var IGNORABLE = /\smc:Ignorable\s*=\s*(["'])([^"']*)\1/;
+function withDeclarations(openTag, { namespaces, ignorable }) {
+  const tag = readTag(openTag, 0);
+  const closeLength = tag?.kind === "empty" ? 2 : 1;
+  const attrs = tag === null ? null : parseAttrs(openTag.slice(tag.nameEnd, tag.end - closeLength));
+  if (tag === null || attrs === null) {
+    throw new DocxExportError(
+      "malformed-xml",
+      "the root element's attributes could not be read"
+    );
+  }
+  const declared = new Map(attrs);
+  const additions = [];
+  for (const [prefix, namespace] of Object.entries(namespaces)) {
+    if (namespace === void 0) continue;
+    const name = `xmlns:${prefix}`;
+    const existing = declared.get(name);
+    if (existing !== void 0 && existing !== namespace) {
+      throw new DocxExportError(
+        "unsupported-content",
+        `the part root binds ${prefix} to a namespace the writer cannot use`
+      );
+    }
+    if (existing === void 0) additions.push([name, namespace]);
+  }
+  const ignoring = IGNORABLE.exec(openTag);
+  let tokens = null;
+  if (ignorable !== void 0 && ignorable.length > 0) {
+    if (ignoring === null) {
+      additions.push(["mc:Ignorable", ignorable.join(" ")]);
+    } else {
+      const had = (attrs.find(([name]) => name === "mc:Ignorable")?.[1] ?? "").split(/\s+/).filter(Boolean);
+      const missing = ignorable.filter((token) => !had.includes(token));
+      if (missing.length > 0) tokens = [...had, ...missing];
+    }
+  }
+  let next = openTag;
+  if (ignoring !== null && tokens !== null) {
+    const rewritten = ` mc:Ignorable=${ignoring[1]}${tokens.join(" ")}${ignoring[1]}`;
+    next = next.slice(0, ignoring.index) + rewritten + next.slice(ignoring.index + ignoring[0].length);
+  }
+  if (additions.length === 0) return next;
+  const end = next.length - closeLength;
+  return `${next.slice(0, end)} ${attrsText(additions)}${next.slice(end)}`;
+}
+function ensureRootDeclarations(xml, declarations) {
+  const root = rootNameOf(xml);
+  if (root === null) {
+    throw new DocxExportError(
+      "malformed-xml",
+      "the part has no root element to declare a namespace on"
+    );
+  }
+  return splicePart(xml, {
+    root: localPart(root),
+    rootTag: (open) => withDeclarations(open, declarations)
+  });
+}
+export {
+  ensureRootDeclarations,
+  partRootProblem,
+  rootPrefixOf,
+  splicePart
+};

package/dist/ooxml/props.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Handles the XML fragments that carry formatting, such as `<w:rPr>`, `<w:pPr>`, and `<w:tcPr>`.
+ *
+ * A fragment is never rebuilt: only the one child a job names is sliced out and swapped, so the
+ * rest (borders, shading, margins) stays as the original text wrote it. OOXML lays down the order
+ * of the children, so the spot to insert a child that was not there is found by that same order.
+ */
+import { type XmlAttr } from "./element";
+export interface PropsChild {
+    /** The name with its namespace prefix stripped off (e.g. `gridSpan`) */
+    name: string;
+    /** This child's original XML fragment exactly as it was */
+    xml: string;
+    /**
+     * Whatever stood between the child before this one and this one: line breaks a producer laid
+     * out, comments, anything that is not an element. Carried so that rewriting one child does not
+     * quietly drop the rest of what the fragment said. Absent rather than empty when nothing did.
+     */
+    before?: string;
+}
+export interface Props {
+    /** The opening tag name exactly as written (e.g. `w:tcPr`) */
+    tag: string;
+    attrs: string | null;
+    children: PropsChild[];
+    /** The same, for what stood between the last child and the closing tag */
+    tail?: string;
+}
+/**
+ * What stood inside a single element, and "" for one that stood empty or cannot be made out.
+ *
+ * The opening tag is read rather than scanned for, so a `>` inside an attribute value does not
+ * pass for the end of it.
+ */
+export declare function innerXml(xml: string): string;
+/**
+ * Splits a formatting fragment into its opening tag and its list of children.
+ * null if its shape cannot be made out (in which case leaving the original untouched is the safe move).
+ */
+export declare function parseProps(xml: string): Props | null;
+/**
+ * With nothing to say, the formatting fragment itself is not written. A fragment holding only
+ * whitespace says nothing; one holding a comment does, so it is written back.
+ */
+export declare function renderProps(props: Props): string;
+/**
+ * Replaces a single child with new XML.
+ *
+ * A null `xml` removes that child. A child that was not there goes into the spot `CHILD_ORDER`
+ * lays down for this fragment's own tag, so the caller names what it is writing and not where it
+ * goes. Naming the element this fragment stands inside picks the right order where one element
+ * carries children in a different order under a different parent (`pPr/rPr`).
+ */
+export declare function setChild(props: Props, name: string, xml: string | null, parent?: string): Props;
+export declare function propsChild(children: readonly PropsChild[], name: string): PropsChild | undefined;
+/**
+ * The opening tag's attributes as pairs, and null when their shape cannot be made out.
+ *
+ * The pairs are worked out on demand rather than kept on `Props`, because an untouched fragment
+ * has to go back out with the spacing, the quoting and the escaping its producer chose. Only a
+ * fragment something writes to passes through `withAttrs`, which is where they are written again.
+ */
+export declare function attrsOf(props: Props): XmlAttr[] | null;
+/** The fragment with these attributes written in place of the ones its opening tag carried */
+export declare function withAttrs(props: Props, attrs: readonly XmlAttr[]): Props;
+/**
+ * One child of a fragment as it was written: the tag, prefix included, so an edited child keeps
+ * the spelling the document chose, and its attributes. A child that is not there has neither, so
+ * no tag with attributes hanging off it can be made.
+ */
+export type ChildElement = {
+    tag: string;
+    attrs: readonly XmlAttr[];
+} | {
+    tag: null;
+    attrs: readonly [];
+};
+/**
+ * The tag and attributes of one child. A child that is not there reads as no tag and no
+ * attributes, and null says its shape cannot be made out, which leaves the caller to back out
+ * rather than write over markup it could not read.
+ */
+export declare function childElement(props: Props, name: string): ChildElement | null;
+/**
+ * Always writes the element, closing it on its own when it holds nothing. Whitespace alone counts
+ * as nothing, the same as `renderProps` reads it, so a pretty-printed fragment emptied of its
+ * children collapses rather than keeping the line breaks that stood between them.
+ */
+export declare function renderElement(props: Props): string;
+/**
+ * An element whose children go in the order `CHILD_ORDER` lays down, whatever order they are
+ * handed in. This is how a fragment written from scratch follows the same order an edited one
+ * is held to, and a child the order does not know is refused the same way.
+ */
+export declare function orderedElement(tag: string, attrs: readonly XmlAttr[], children: readonly PropsChild[]): string;
+/**
+ * Edits one child down a path of names, parsing only the fragments the path runs through and
+ * leaving every other child as the original text wrote it.
+ *
+ * The callback is handed the child the path names, null for one that is not there, and answers
+ * with what it is to become, null to take it away. A container along the path that was not there
+ * is written, and one the edit leaves empty is taken away with it. null when a fragment on the
+ * path cannot be made out, which leaves the caller to back out.
+ */
+export declare function editChild(props: Props, path: readonly [string, ...string[]], edit: (child: Props | null) => Props | null): Props | null;
+/**
+ * Reads a single formatting fragment into an element.
+ *
+ * A fragment carries no namespace declarations, so they are put back on as it is wrapped.
+ * null if its shape cannot be made out, in which case the caller leaves the display values alone.
+ */
+export declare function parsePropsXml(xml: string): Element | null;