@portone/docx-editor 0.2.0 → 0.3.0

package/dist/ooxml/fragment.js

@@ -0,0 +1,76 @@
+// src/ooxml/fragment.ts
+import {
+  elementChildren,
+  namespaceDecls,
+  parseXml,
+  RESERVED_PREFIXES,
+  W_NS
+} from "./xml.js";
+function ELEMENT(...names) {
+  return { kind: "element", names };
+}
+var ANY_ELEMENT = { kind: "element", names: "any" };
+var ATTRIBUTES = { kind: "attributes" };
+function loneElement(xml) {
+  let root;
+  try {
+    root = parseXml(`<x ${namespaceDecls(xml)}>${xml}</x>`).documentElement;
+  } catch {
+    return null;
+  }
+  if (root.childNodes.length !== 1) return null;
+  const el = elementChildren(root)[0];
+  return el === void 0 || rebindsReservedPrefix(el) ? null : el;
+}
+function isNamed(el, names) {
+  if (!names.includes(el.localName)) return false;
+  const declaration = el.prefix === null ? "xmlns" : `xmlns:${el.prefix}`;
+  for (let scope = el; scope.parentElement !== null; scope = scope.parentElement) {
+    if (scope.hasAttribute(declaration)) return el.namespaceURI === W_NS;
+  }
+  return true;
+}
+function holdsHeadAlone(el, shape) {
+  const closing = loneElement(`<w:${shape.name}>${shape.closedBy}`);
+  if (closing === null) return false;
+  const children = elementChildren(el);
+  const own = children.slice(
+    0,
+    children.length - elementChildren(closing).length
+  );
+  return el.childNodes.length === children.length && own.every((child) => isNamed(child, shape.head));
+}
+function rebindsReservedPrefix(el) {
+  return Array.from(el.attributes).some((attr) => {
+    if (attr.prefix !== "xmlns") return false;
+    const reserved = RESERVED_PREFIXES.get(attr.localName);
+    return reserved !== void 0 && reserved !== attr.value;
+  }) || elementChildren(el).some(rebindsReservedPrefix);
+}
+function holdsShape(shape, value) {
+  switch (shape.kind) {
+    case "element": {
+      const el = loneElement(value);
+      if (el === null) return false;
+      return shape.names === "any" || isNamed(el, shape.names);
+    }
+    case "attributes": {
+      const el = loneElement(`<y ${value}></y>`);
+      return el !== null && el.childNodes.length === 0;
+    }
+    case "openTag": {
+      const el = loneElement(value + shape.closedBy);
+      return el !== null && holdsHeadAlone(el, shape);
+    }
+  }
+}
+function acceptRawXml(shape, value) {
+  if (value === null) return null;
+  return holdsShape(shape, value) ? value : false;
+}
+export {
+  ANY_ELEMENT,
+  ATTRIBUTES,
+  ELEMENT,
+  acceptRawXml
+};

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

@@ -1,4 +1,5 @@
 // src/ooxml/image.ts
+import { NAMESPACES } from "./names.js";
 import { childByLocalName, escapeXml, R_NS } from "./xml.js";
 var EMU_PER_PX = 9525;
 function emuToPx(emu) {
@@ -42,7 +43,6 @@ function toImageExtent(value) {
   const cy = positiveInt(value.cy);
   return cx === null || cy === null ? null : { cx, cy };
 }
-var PICTURE_URI = "http://schemas.openxmlformats.org/drawingml/2006/picture";
 function childOf(el, name) {
   return el ? childByLocalName(el, name) : null;
 }
@@ -62,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(
@@ -82,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 = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
-var A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main";
 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

@@ -0,0 +1,27 @@
+/**
+ * The namespace prefixes the writer spells out, and the namespace each one stands for.
+ *
+ * Reading is another matter: a document may bind these prefixes to names of its own, so an element
+ * that arrived in the file is looked up by its local part. What this package writes is settled
+ * 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 prefix every WordprocessingML element and attribute this package writes carries */
+export declare const W_PREFIX = "w";
+export declare const NAMESPACES: {
+    readonly w: "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+    readonly r: "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+    readonly w14: "http://schemas.microsoft.com/office/word/2010/wordml";
+    readonly w15: "http://schemas.microsoft.com/office/word/2012/wordml";
+    readonly mc: "http://schemas.openxmlformats.org/markup-compatibility/2006";
+    readonly wp: "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+    readonly a: "http://schemas.openxmlformats.org/drawingml/2006/main";
+    readonly pic: "http://schemas.openxmlformats.org/drawingml/2006/picture";
+};
+export type KnownPrefix = keyof typeof NAMESPACES;
+/** 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 */
+export declare function wName(local: string): string;
+/** The declaration a part root carries for one prefix, ready to write inside an opening tag */
+export declare function xmlnsDecl(prefix: KnownPrefix): string;

package/dist/ooxml/names.js

@@ -0,0 +1,29 @@
+// src/ooxml/names.ts
+import { R_NS, W_NS } from "./xml.js";
+var W_PREFIX = "w";
+var NAMESPACES = {
+  w: W_NS,
+  r: R_NS,
+  w14: "http://schemas.microsoft.com/office/word/2010/wordml",
+  w15: "http://schemas.microsoft.com/office/word/2012/wordml",
+  mc: "http://schemas.openxmlformats.org/markup-compatibility/2006",
+  wp: "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+  a: "http://schemas.openxmlformats.org/drawingml/2006/main",
+  pic: "http://schemas.openxmlformats.org/drawingml/2006/picture"
+};
+function qualify(prefix, local) {
+  return `${prefix}:${local}`;
+}
+function wName(local) {
+  return qualify(W_PREFIX, local);
+}
+function xmlnsDecl(prefix) {
+  return `xmlns:${prefix}="${NAMESPACES[prefix]}"`;
+}
+export {
+  NAMESPACES,
+  W_PREFIX,
+  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: one the root declares already is left as it was written.
+ */
+export declare function ensureRootDeclarations(xml: string, declarations: RootDeclarations): string;

package/dist/ooxml/partSplice.js

@@ -0,0 +1,169 @@
+// 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 Set(attrs.map(([name]) => name));
+  const additions = [];
+  for (const [prefix, namespace] of Object.entries(namespaces)) {
+    if (namespace !== void 0 && !declared.has(`xmlns:${prefix}`)) {
+      additions.push([`xmlns:${prefix}`, 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/precedence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which attribute beats which when an element writes down both.
+ *
+ * OOXML records the same setting twice over in several places: a font slot beside the theme
+ * reference that overrules it, a color beside the theme color, an indent in twips beside the same
+ * indent counted in characters. Writing one of a pair while leaving the other standing means
+ * writing a value Word will not show, so the one that would win is dropped as the other is written.
+ *
+ * The table is keyed by the local names of the owning element and the attribute together, because
+ * neither is enough on its own: `color` is an attribute of `w:shd` but an element of its own whose
+ * value sits in `w:val`, and `left` is an attribute of `w:ind` but an element of `w:tcMar`.
+ */
+import { type XmlAttr } from "./element";
+/**
+ * The attributes that override the named one when both are there, so writing the named one drops
+ * them (§17.3.1.12 ind, §17.3.2.26 rFonts, §17.3.2.6 color, §17.3.5 shd, §17.3.1.33 spacing).
+ *
+ * The border sides are the children of `w:tcBorders`, each of them a CT_Border that records a
+ * color of its own.
+ */
+export declare const OVERRIDING_ATTRS: Readonly<Record<`${string}/${string}`, readonly string[]>>;
+/** What writing `element`'s `name` drops along with it. Empty for a pair nothing overrides */
+export declare function overridingAttrs(element: string, name: string): readonly string[];
+/**
+ * `withAttr` with the attributes the new value would be fighting with dropped as it is written.
+ *
+ * This is how an attribute is meant to be written, so that a writer added later cannot forget the
+ * drop. A caller that means to leave an overriding attribute standing says so by reaching for
+ * `withAttr` instead.
+ */
+export declare function setAttr(attrs: readonly XmlAttr[], element: string, name: string, value: string | null): XmlAttr[];

package/dist/ooxml/precedence.js

@@ -0,0 +1,51 @@
+// src/ooxml/precedence.ts
+import { withAttr, withoutAttrs } from "./element.js";
+var THEME_COLOR = [
+  "themeColor",
+  "themeTint",
+  "themeShade"
+];
+var NO_OVERRIDES = [];
+var OVERRIDING_ATTRS = {
+  "rFonts/ascii": ["asciiTheme"],
+  "rFonts/hAnsi": ["hAnsiTheme"],
+  "rFonts/eastAsia": ["eastAsiaTheme"],
+  // This is the slot whose capitalization varies from document to document
+  "rFonts/cs": ["cstheme", "csTheme"],
+  "color/val": THEME_COLOR,
+  "shd/color": THEME_COLOR,
+  "shd/fill": ["themeFill", "themeFillTint", "themeFillShade"],
+  "ind/left": ["leftChars"],
+  "ind/start": ["startChars"],
+  "ind/right": ["rightChars"],
+  "ind/end": ["endChars"],
+  "ind/hanging": ["hangingChars"],
+  "ind/firstLine": ["firstLineChars"],
+  "spacing/before": ["beforeLines"],
+  "spacing/after": ["afterLines"],
+  "top/color": THEME_COLOR,
+  "start/color": THEME_COLOR,
+  "left/color": THEME_COLOR,
+  "bottom/color": THEME_COLOR,
+  "end/color": THEME_COLOR,
+  "right/color": THEME_COLOR,
+  "insideH/color": THEME_COLOR,
+  "insideV/color": THEME_COLOR,
+  "tl2br/color": THEME_COLOR,
+  "tr2bl/color": THEME_COLOR
+};
+function overridingAttrs(element, name) {
+  return OVERRIDING_ATTRS[`${element}/${name}`] ?? NO_OVERRIDES;
+}
+function setAttr(attrs, element, name, value) {
+  return withAttr(
+    withoutAttrs(attrs, overridingAttrs(element, name)),
+    name,
+    value
+  );
+}
+export {
+  OVERRIDING_ATTRS,
+  overridingAttrs,
+  setAttr
+};

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;