@portone/docx-editor 0.1.1 → 0.2.1

package/dist/editor/plugins/imagePaste.js

@@ -3,6 +3,7 @@ import { isHistoryTransaction } from "prosemirror-history";
 import { Plugin, PluginKey } from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
 import { replacementShut } from "../../schema/locks.js";
+import { editsShut } from "../../schema/protectionState.js";
 import {
   hasResolvableClipboardImages,
   resolveClipboardImages
@@ -222,7 +223,9 @@ function imagePaste() {
     props: {
       decorations: (state) => imagePasteKey.getState(state)?.decorations,
       handlePaste(view, event) {
-        if (replacementShut(view.state.selection, view.state.doc)) return false;
+        if (editsShut(view.state) || replacementShut(view.state.selection, view.state.doc)) {
+          return false;
+        }
         if (view.state.selection.ranges.length > 1) return false;
         const html = event.clipboardData?.getData("text/html") ?? "";
         if (!hasResolvableClipboardImages(view.dom.ownerDocument, html)) {

package/dist/editor/plugins/keymap.d.ts

@@ -1,5 +1,15 @@
 /**
  * Keys not handled here are taken by ProseMirror's base keymap.
  */
-import type { Command } from "prosemirror-state";
+import { type Command, Plugin } from "prosemirror-state";
+/**
+ * Keeps undo and redo on their keys where the keymap above cannot reach them.
+ *
+ * A view that took editing away drops every keydown before the keymap plugin sees it
+ * (`view.editable || !(event.type in editHandlers)` in prosemirror-view), so a commenter, who is
+ * given no caret, would have no way to take a comment back. A DOM handler is asked ahead of that
+ * check. An editable view leaves the keys to the keymap plugin, which would otherwise run them a
+ * second time.
+ */
+export declare function historyKeys(): Plugin;
 export declare const docxKeymap: Record<string, Command>;

package/dist/editor/plugins/keymap.js

@@ -1,6 +1,8 @@
 // src/editor/plugins/keymap.ts
 import { chainCommands } from "prosemirror-commands";
 import { undoInputRule } from "prosemirror-inputrules";
+import { keydownHandler } from "prosemirror-keymap";
+import { Plugin } from "prosemirror-state";
 import { goToNextCell } from "prosemirror-tables";
 import { canSplit } from "prosemirror-transform";
 import { toParagraphFormat } from "../../model/format.js";
@@ -55,6 +57,25 @@ var preserveTableFollowingParagraph = (state) => {
   const paragraphIndex = $from.index(0);
   return paragraphIndex > 0 && state.doc.child(paragraphIndex - 1).type.spec.tableRole === "table";
 };
+var historyKeymap = {
+  "Mod-z": undo,
+  "Mod-y": redo,
+  "Shift-Mod-z": redo
+};
+function historyKeys() {
+  const runHistoryKeys = keydownHandler(historyKeymap);
+  return new Plugin({
+    props: {
+      handleDOMEvents: {
+        keydown: (view, event) => {
+          if (view.editable || !runHistoryKeys(view, event)) return false;
+          event.preventDefault();
+          return true;
+        }
+      }
+    }
+  });
+}
 var docxKeymap = {
   Enter: chainCommands(leaveEmptyListItem, splitParagraph),
   "Shift-Enter": insertLineBreak,
@@ -62,9 +83,7 @@ var docxKeymap = {
   "Mod-Enter": insertPageBreak,
   // The paragraph keeps adjacent tables separate without changing imported documents.
   Backspace: chainCommands(preserveTableFollowingParagraph, undoInputRule),
-  "Mod-z": undo,
-  "Mod-y": redo,
-  "Shift-Mod-z": redo,
+  ...historyKeymap,
   "Mod-b": toggleBold,
   "Mod-i": toggleItalic,
   "Mod-u": toggleUnderline,
@@ -90,5 +109,6 @@ var docxKeymap = {
   "Shift-ArrowRight": moveAcrossTab("right", true)
 };
 export {
-  docxKeymap
+  docxKeymap,
+  historyKeys
 };

package/dist/editor/plugins/lockedContent.d.ts

@@ -1,6 +1,8 @@
 /**
- * Rejects transactions disallowed by `schema/locks`. A rejected IME edit also ends the browser
- * composition on the next frame so ProseMirror cannot remain stuck in composing state.
+ * Rejects transactions no guard `schema/guards` registers would let through, the locks the document
+ * carries and the protection the editor runs under (`schema/protection`) among them. A rejected IME
+ * edit also ends the browser composition on the next frame so ProseMirror cannot remain stuck in
+ * composing state.
  */
 import { Plugin } from "prosemirror-state";
 export declare function lockedContent(): Plugin;

package/dist/editor/plugins/lockedContent.js

@@ -1,6 +1,6 @@
 // src/editor/plugins/lockedContent.ts
 import { Plugin } from "prosemirror-state";
-import { transactionAllowed } from "../../schema/locks.js";
+import { transactionAllowed } from "../../schema/guards.js";
 function endComposition(view) {
   if (!view.composing) return;
   const marks = view.state.storedMarks ?? view.state.selection.$from.marks();
@@ -30,7 +30,7 @@ function lockedContent() {
       };
     },
     filterTransaction(tr, state) {
-      const allowed = transactionAllowed(tr, state.doc);
+      const allowed = transactionAllowed(tr, state);
       if (!allowed) afterRefusal();
       return allowed;
     }

package/dist/editor/plugins/tableContextMenu.js

@@ -4,6 +4,7 @@ import {
   PluginKey,
   TextSelection
 } from "prosemirror-state";
+import { editsShut } from "../../schema/protectionState.js";
 var CLOSE = "close";
 var menuKey = new PluginKey("docxEditorTableMenu");
 function isRecord(value) {
@@ -67,7 +68,7 @@ function tableContextMenu() {
     props: {
       handleDOMEvents: {
         contextmenu(view, event) {
-          if (!view.editable) return false;
+          if (editsShut(view.state)) return false;
           const cellPos = cellAtEvent(view, event.target);
           if (cellPos === null) return false;
           event.preventDefault();

package/dist/editor/plugins/textContextMenu.js

@@ -5,6 +5,7 @@ import {
   TextSelection
 } from "prosemirror-state";
 import { CellSelection } from "prosemirror-tables";
+import { editingProtection, editsShut } from "../../schema/protectionState.js";
 var CLOSE = "close";
 var menuKey = new PluginKey("docxEditorTextMenu");
 function isRecord(value) {
@@ -44,6 +45,7 @@ function isInSelection(state, spot) {
   );
 }
 function forTableMenu(view, target, spot) {
+  if (editsShut(view.state)) return false;
   const aboutCells = view.state.selection instanceof CellSelection || !isInSelection(view.state, spot);
   return aboutCells && isInTableCell(view, target);
 }
@@ -71,9 +73,12 @@ function textContextMenu() {
     props: {
       handleDOMEvents: {
         contextmenu(view, event) {
-          if (!view.editable) return false;
+          if (editingProtection(view.state) === "readOnly") return false;
           if (!isInEditor(view, event.target)) return false;
           const spot = clickedSpot(view, event);
+          if (editsShut(view.state) && !isInSelection(view.state, spot)) {
+            return false;
+          }
           if (forTableMenu(view, event.target, spot)) return false;
           event.preventDefault();
           view.dispatch(openMenu(view.state, event, spot));

package/dist/index.d.ts

@@ -22,6 +22,8 @@ export type { CellFormat, CellVerticalAlign, DocumentDefaults, HighlightName, Li
 export type { DocxExportErrorCode, DocxImportErrorCode, } from "./ooxml/errors";
 export { DocxExportError, DocxImportError } from "./ooxml/errors";
 export { docxSchema } from "./schema";
+/** Whose comments the panel offers to edit, which `DocxEditorMode` takes */
+export type { EditableComments } from "./schema/protection";
 /**
  * The lists the built-in pickers offer. They are exported so that a toolbar of your own can
  * offer the same ones without writing them out again; the pickers themselves read these very

package/dist/numbering/listTemplate.js

@@ -1,4 +1,6 @@
 // src/numbering/listTemplate.ts
+import { elementXml } from "../ooxml/element.js";
+import { wName } from "../ooxml/names.js";
 var LEVEL_COUNT = 9;
 var MAX_ILVL = LEVEL_COUNT - 1;
 var NUMBER_CYCLE = [
@@ -51,25 +53,45 @@ function nextNumId(used, kind) {
   return listKindOf(from) === kind ? from : from + 1;
 }
 function indXml(indent) {
-  const attrs = [
-    ["w:left", indent?.startTwips],
-    ["w:right", indent?.endTwips],
-    ["w:hanging", indent?.hangingTwips],
-    ["w:firstLine", indent?.firstLineTwips]
-  ].filter((entry) => typeof entry[1] === "number").map(([name, value]) => `${name}="${value}"`).join(" ");
-  return attrs === "" ? "" : `<w:pPr><w:ind ${attrs}/></w:pPr>`;
+  const slots = [
+    ["left", indent?.startTwips ?? null],
+    ["right", indent?.endTwips ?? null],
+    ["hanging", indent?.hangingTwips ?? null],
+    ["firstLine", indent?.firstLineTwips ?? null]
+  ];
+  const attrs = slots.filter((slot) => slot[1] !== null).map(([name, twips]) => [wName(name), `${twips}`]);
+  if (attrs.length === 0) return "";
+  return elementXml(wName("pPr"), [], [elementXml(wName("ind"), attrs)]);
 }
 function levelXml(ilvl, level) {
   const ind = indXml(level.indent);
-  return `<w:lvl w:ilvl="${ilvl}"><w:start w:val="${level.start}"/><w:numFmt w:val="${level.format}"/><w:lvlText w:val="${level.text}"/><w:lvlJc w:val="left"/>${ind}</w:lvl>`;
+  return elementXml(
+    wName("lvl"),
+    [[wName("ilvl"), `${ilvl}`]],
+    [
+      elementXml(wName("start"), [[wName("val"), `${level.start}`]]),
+      elementXml(wName("numFmt"), [[wName("val"), level.format]]),
+      elementXml(wName("lvlText"), [[wName("val"), level.text]]),
+      elementXml(wName("lvlJc"), [[wName("val"), "left"]]),
+      ind
+    ]
+  );
 }
 function abstractNumXml(abstractNumId, kind) {
   const levels = TEMPLATES[kind].levels;
   const body = Array.from(levels.entries()).map(([ilvl, level]) => levelXml(ilvl, level)).join("");
-  return `<w:abstractNum w:abstractNumId="${abstractNumId}">${body}</w:abstractNum>`;
+  return elementXml(
+    wName("abstractNum"),
+    [[wName("abstractNumId"), `${abstractNumId}`]],
+    [body]
+  );
 }
 function numXml(numId, abstractNumId) {
-  return `<w:num w:numId="${numId}"><w:abstractNumId w:val="${abstractNumId}"/></w:num>`;
+  return elementXml(
+    wName("num"),
+    [[wName("numId"), `${numId}`]],
+    [elementXml(wName("abstractNumId"), [[wName("val"), `${abstractNumId}`]])]
+  );
 }
 export {
   LEVEL_COUNT,

package/dist/ooxml/element.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 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.
+ */
+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 attributes with the 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.
+ */
+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;
+/**
+ * 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;
+/**
+ * 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

@@ -0,0 +1,49 @@
+// src/ooxml/element.ts
+import { NAMESPACES, 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 withAttr(attrs, name, value) {
+  if (value === null) return withoutAttrs(attrs, [name]);
+  const at = attrs.findIndex(([attr]) => localPart(attr) === 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 openTagXml(name, rawAttrs) {
+  return rawAttrs ? `<${name} ${rawAttrs}>` : `<${name}>`;
+}
+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,
+  withAttr,
+  withoutAttrs,
+  xmlnsAttr
+};

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;

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.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,7 @@ 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";
+var PICTURE_URI = NAMESPACES.pic;
 function childOf(el, name) {
   return el ? childByLocalName(el, name) : null;
 }
@@ -82,8 +83,8 @@ 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";
+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}`;

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/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
+};