@portone/docx-editor 0.2.0 → 0.3.0

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

@@ -0,0 +1,65 @@
+/**
+ * Writing one element out as text, and merging the attributes of one.
+ *
+ * Everything here works on strings, because that is what the writers hold: a fragment the file
+ * 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 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 */
+export type XmlAttr = readonly [name: string, value: string];
+/** `a="b" c="d"`. Empty for no attributes, so an opening tag needs no separator of its own */
+export declare function attrsText(attrs: readonly XmlAttr[]): string;
+/**
+ * `<name a="b"/>`, or `<name a="b">children</name>` for an element that holds something.
+ *
+ * Attribute values are escaped here; children are spliced in as they are, being markup already, so
+ * a caller writing text as a child escapes it itself. An element handed no child at all closes on
+ * its own, which means a caller that wants an empty pair of tags passes the empty text as a child.
+ */
+export declare function elementXml(name: string, attrs: readonly XmlAttr[], children?: readonly string[]): string;
+/**
+ * The namespace declaration a fragment carries when the part it is spliced into does not declare
+ * 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 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, 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[];
+/**
+ * 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.
+ *
+ * The text is spliced in exactly as it arrived rather than parsed and written again, so the
+ * spelling, the order, and the escaping a producer chose all survive being edited.
+ */
+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;

package/dist/ooxml/element.js

@@ -0,0 +1,68 @@
+// src/ooxml/element.ts
+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(" ");
+}
+function elementXml(name, attrs, children = []) {
+  const text = attrsText(attrs);
+  const open = text === "" ? `<${name}` : `<${name} ${text}`;
+  if (children.length === 0) return `${open}/>`;
+  return `${open}>${children.join("")}</${name}>`;
+}
+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 = 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, 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}>`;
+}
+function emptyTagXml(name, rawAttrs) {
+  return rawAttrs ? `<${name} ${rawAttrs}/>` : `<${name}/>`;
+}
+export {
+  attrsText,
+  elementXml,
+  emptyTagXml,
+  openTagXml,
+  wAttrValue,
+  wLocalName,
+  withAttr,
+  withoutAttrs,
+  xmlnsAttr
+};

package/dist/ooxml/errors.d.ts

@@ -8,6 +8,7 @@
 /**
  * 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
@@ -15,7 +16,7 @@
  * - `malformed-xml`: the XML cannot be parsed, declares a DTD, or its markup is inconsistent
  * - `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-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;
@@ -26,7 +27,7 @@ export declare class DocxImportError extends Error {
  *
  * - `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
+ * - `unsupported-content`: the document holds a node kind we have no way to serialize, or a preserved block standing in two places, which has one original XML to write
  * - `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

package/dist/ooxml/fragment.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The gate a raw OOXML string passes through on its way from the DOM into a node or mark attr.
+ *
+ * A preserved fragment goes back out the way it came, spliced into a slot the writer opens and
+ * closes around it (`docx/serializeParagraph`), so a fragment that closes that slot itself, opens
+ * a sibling beside it, or lays text down beside what it holds writes something the editor never
+ * modelled into the exported file. What stands inside the element it carries is that element's own
+ * and travels with it. Reading one back is the only place such a string can arrive from outside,
+ * so every attr that carries one is read through here and a fragment that does not hold its shape
+ * is turned down rather than corrected.
+ *
+ * A refusal is not an error: `getAttrs` answers `false` with it, which drops the parse rule and
+ * leaves ProseMirror to settle the content one level plainer. Demotion, not contamination.
+ */
+/**
+ * What a raw XML string has to look like to be let into the attr that carries it.
+ *
+ * `element` is a whole element: a properties fragment, a drawing, an annotation reference.
+ * `attributes` is what stood inside an opening tag, as `attrString` writes it.
+ * `openTag` is an opening tag with everything it wrapped cut away, which the writer puts back by
+ * appending the closing text `closedBy` names. `head` is what may still stand between the two:
+ * the property elements the tag carries ahead of its content, by local name.
+ */
+export type RawXmlShape = {
+    kind: "element";
+    names: readonly string[] | "any";
+} | {
+    kind: "attributes";
+} | {
+    kind: "openTag";
+    name: string;
+    closedBy: string;
+    head: readonly string[];
+};
+/** A single element by local name, rejecting an explicitly foreign namespace */
+export declare function ELEMENT(...names: string[]): RawXmlShape;
+/**
+ * A single element of any name, in any namespace.
+ *
+ * What import could not model keeps its own XML (`rawInline`, `rawBlock`), and that is a
+ * `m:oMathPara`, a `mc:AlternateContent`, a `w:ins`, a bookmark: naming the ones allowed would
+ * turn a document the editor reads today into a demoted one.
+ */
+export declare const ANY_ELEMENT: RawXmlShape;
+/** The attributes of an opening tag, with neither the tag nor anything it held */
+export declare const ATTRIBUTES: RawXmlShape;
+/**
+ * The value if it holds the shape, null if there was none, `false` if it does not.
+ *
+ * The three answers are what `getAttrs` needs: a value to carry, an absent attr, and a rule to
+ * give up on.
+ */
+export declare function acceptRawXml(shape: RawXmlShape, value: string | null): string | null | false;