@portone/docx-editor 0.2.1 → 0.4.0

package/dist/docx/newLists.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The lists that were started during editing, and the part their definitions are written into.
+ *
+ * Both the writer and the export invariants ask these questions, so they stand apart from the
+ * writer rather than being read off it.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import { type NewList } from "../numbering/parseNumbering";
+import type { SessionStore } from "./session";
+/**
+ * How the main part relates the numbering part, and what the package declares that part to hold.
+ *
+ * The reader finds the part by this relationship and the writer relates a new one under it, so
+ * neither can name it differently from the other.
+ */
+export declare const NUMBERING_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+export declare const NUMBERING_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml";
+/**
+ * The numbering ids that appeared during editing and have no definition.
+ *
+ * An id that was already in use without a definition when the document was opened is left alone,
+ * because exporting such a document without editing it must not disturb numbering.xml.
+ */
+export declare function newNumIds(doc: PMNode, session: SessionStore): number[];
+/** The lists started during editing, split by whether a definition was registered for each */
+export interface StartedLists {
+    /** The definition each list was started with, which is what goes into numbering.xml */
+    readonly defined: ReadonlyMap<number, NewList>;
+    /** The numbers a list was started under that no definition stands behind */
+    readonly unregistered: readonly number[];
+}
+/**
+ * The lists started during editing, each against the definition it was started with.
+ *
+ * The definition is the one the document node carries (`numbering/listRegistry`), which the list
+ * commands and the clipboard record as they start a list. A number carrying none is reported here
+ * rather than written bare, which the export invariants turn into a refusal.
+ */
+export declare function startedLists(doc: PMNode, session: SessionStore): StartedLists;
+/** The numbering part as it was opened, which a new definition is spliced into. null when the document has none */
+export declare function numberingPartOf(session: SessionStore): {
+    path: string;
+    bytes: Uint8Array;
+} | null;
+/**
+ * Whether the definition of a new list has somewhere to go: the numbering part the document was
+ * opened with, or one written from scratch, which only a package that can declare what the new
+ * part holds may take.
+ */
+export declare function canDefineNewList(session: SessionStore): boolean;

package/dist/docx/newLists.js

@@ -0,0 +1,59 @@
+// src/docx/newLists.ts
+import { toParagraphFormat } from "../model/format.js";
+import { NEW_LISTS_ATTR, newListsOf } from "../numbering/listRegistry.js";
+import { parseNumbering } from "../numbering/parseNumbering.js";
+import { R_NS } from "../ooxml/xml.js";
+import { CONTENT_TYPES_PATH } from "./packageParts.js";
+var NUMBERING_REL_TYPE = `${R_NS}/numbering`;
+var NUMBERING_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml";
+function collectNumIds(node, into) {
+  const visit = (candidate) => {
+    if (candidate.type.name !== "paragraph") return true;
+    const numId = toParagraphFormat(candidate.attrs.format)?.numbering?.numId;
+    if (numId !== void 0) into.add(numId);
+    return false;
+  };
+  if (visit(node)) node.descendants(visit);
+}
+function numIdsIn(node) {
+  const used = /* @__PURE__ */ new Set();
+  collectNumIds(node, used);
+  return used;
+}
+function numIdsAtOpen(session) {
+  const used = /* @__PURE__ */ new Set();
+  for (const block of session.blocks) collectNumIds(block.node, used);
+  return used;
+}
+function newNumIds(doc, session) {
+  const defined = parseNumbering(session.numberingXml).lists;
+  const atOpen = numIdsAtOpen(session);
+  return Array.from(numIdsIn(doc)).filter((numId) => !defined.has(numId) && !atOpen.has(numId)).sort((a, b) => a - b);
+}
+function startedLists(doc, session) {
+  const registered = newListsOf(doc.attrs[NEW_LISTS_ATTR]);
+  const defined = /* @__PURE__ */ new Map();
+  const unregistered = [];
+  for (const numId of newNumIds(doc, session)) {
+    const list = registered.get(numId);
+    if (list === void 0) unregistered.push(numId);
+    else defined.set(numId, list);
+  }
+  return { defined, unregistered };
+}
+function numberingPartOf(session) {
+  const path = session.numberingPartPath;
+  const bytes = path === null ? void 0 : session.parts.get(path);
+  return path === null || bytes === void 0 ? null : { path, bytes };
+}
+function canDefineNewList(session) {
+  return numberingPartOf(session) !== null || session.parts.has(CONTENT_TYPES_PATH);
+}
+export {
+  NUMBERING_CONTENT_TYPE,
+  NUMBERING_REL_TYPE,
+  canDefineNewList,
+  newNumIds,
+  numberingPartOf,
+  startedLists
+};

package/dist/docx/notes.js

@@ -7,7 +7,7 @@ import {
   R_NS,
   W_NS
 } from "../ooxml/xml.js";
-import { readRelationships, relsPathOf, resolveTarget } from "./relationships.js";
+import { relatedPartPath } from "./packageParts.js";
 var EMPTY_PART = {
   partPath: null,
   ordered: [],
@@ -29,12 +29,8 @@ function noteText(el) {
   return Array.from(el.getElementsByTagNameNS(W_NS, "p")).map(inlineText).join("\n");
 }
 function notePart(parts, mainPartPath, kind) {
-  const relationshipType = `${R_NS}/${kind}s`;
-  const relationship = readRelationships(parts, relsPathOf(mainPartPath)).find(
-    (entry) => entry.type === relationshipType && !entry.external
-  );
-  if (!relationship) return EMPTY_PART;
-  const partPath = resolveTarget(mainPartPath, relationship.target);
+  const partPath = relatedPartPath(parts, mainPartPath, `${R_NS}/${kind}s`);
+  if (partPath === null) return EMPTY_PART;
   const bytes = parts.get(partPath);
   if (!bytes) return { ...EMPTY_PART, partPath };
   const root = parseXml(decodeUtf8(bytes).text).documentElement;

package/dist/docx/numberingPlanner.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The numbering part with the definition every list started during editing was started with
+ * spliced in, and the part itself when the document arrived without one.
+ *
+ * The original text is left as is and only the new definitions go in. A document that has no
+ * numbering part gets one written from scratch, with the relationship that finds it and the
+ * declaration of what it holds asked of the context, so the first list a document takes costs it
+ * nothing outside this planner. Nothing is written when no list was started.
+ */
+import type { PartPlanner } from "./partPlan";
+export declare const numberingPlanner: PartPlanner;

package/dist/docx/numberingPlanner.js

@@ -0,0 +1,50 @@
+// src/docx/numberingPlanner.ts
+import { addListDefinitions } from "../numbering/writeNumbering.js";
+import { elementXml, xmlnsAttr } from "../ooxml/element.js";
+import { NAMESPACES, wName } from "../ooxml/names.js";
+import { ensureRootDeclarations } from "../ooxml/partSplice.js";
+import { decodeUtf8, encodeUtf8 } from "../ooxml/xml.js";
+import {
+  NUMBERING_CONTENT_TYPE,
+  NUMBERING_REL_TYPE,
+  numberingPartOf,
+  startedLists
+} from "./newLists.js";
+import { availablePartPath } from "./packageParts.js";
+import { directoryOf } from "./relationships.js";
+function emptyNumberingPart() {
+  return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' + elementXml(wName("numbering"), [xmlnsAttr("w")]);
+}
+var numberingPlanner = {
+  name: "numbering",
+  plan(doc, session, context) {
+    const { defined } = startedLists(doc, session);
+    if (defined.size === 0) return null;
+    const original = numberingPartOf(session);
+    if (original === null) {
+      const path = session.numberingPartPath ?? availablePartPath(session.parts, session.mainPartPath, "numbering");
+      if (session.numberingPartPath === null) {
+        context.relationships.add({
+          type: NUMBERING_REL_TYPE,
+          target: path.slice(directoryOf(session.mainPartPath).length)
+        });
+      }
+      context.contentTypes.addOverride(path, NUMBERING_CONTENT_TYPE);
+      return /* @__PURE__ */ new Map([
+        [
+          path,
+          encodeUtf8(addListDefinitions(emptyNumberingPart(), defined), false)
+        ]
+      ]);
+    }
+    const { text, hadBom } = decodeUtf8(original.bytes);
+    const rewritten = ensureRootDeclarations(
+      addListDefinitions(text, defined),
+      { namespaces: { w: NAMESPACES.w } }
+    );
+    return /* @__PURE__ */ new Map([[original.path, encodeUtf8(rewritten, hadBom)]]);
+  }
+};
+export {
+  numberingPlanner
+};

package/dist/docx/packageParts.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where a part sits in the package, asked one way by every reader and writer, and the content
+ * types part every part the export adds is declared in.
+ *
+ * A part beside the body is found through the relationship the main part declares for it, and a
+ * part the export adds takes the first name beside the main part that nothing has claimed. Each
+ * reader used to find its part with a lookup of its own, so the rule for what counts as the
+ * related part lived in five places.
+ */
+export declare const CONTENT_TYPES_PATH = "[Content_Types].xml";
+/**
+ * Where the part the main part relates under this type sits. null for no such relationship, and
+ * for one that points outside the package, which no part of it can stand behind.
+ */
+export declare function relatedPartPath(parts: ReadonlyMap<string, Uint8Array>, mainPartPath: string, type: string): string | null;
+/** A part as text, and null for a path there is no part at, so a missing relationship reads as a missing part */
+export declare function readPart(parts: ReadonlyMap<string, Uint8Array>, path: string | null): string | null;
+/** `comments.xml`, then `comments2.xml`, and so on beside the main part: the first name no part of the package has taken */
+export declare function availablePartPath(parts: ReadonlyMap<string, Uint8Array>, mainPartPath: string, stem: string): string;
+/**
+ * The content types part as an export leaves it: what the package declared when it was opened,
+ * and every declaration the planners asked for on top, written once at the end.
+ *
+ * Each writer that added a part used to splice its own declaration in and hand the result to the
+ * next, so what the part came to hold depended on the order they were called in, and a writer
+ * called without the last one's result wrote over its declaration.
+ */
+export interface ContentTypeWriter {
+    /** Declares the type of the one part at this path */
+    addOverride(partPath: string, contentType: string): void;
+    /** Declares the type of every part with this extension */
+    addDefault(extension: string, contentType: string): void;
+    /**
+     * The part with everything added, or null when nothing was added or everything asked for was
+     * declared already. The additions go right after the opening tag, the defaults ahead of the
+     * overrides, whichever order they were asked in.
+     */
+    part(): Uint8Array | null;
+}
+/** XML parts named by OPC content types, even when their URI has no .xml suffix. */
+export declare function declaredXmlParts(types: Uint8Array, paths: Iterable<string>): ReadonlySet<string>;
+export declare function contentTypeWriter(parts: ReadonlyMap<string, Uint8Array>): ContentTypeWriter;

package/dist/docx/packageParts.js

@@ -0,0 +1,135 @@
+// src/docx/packageParts.ts
+import { elementXml } from "../ooxml/element.js";
+import { DocxExportError } from "../ooxml/errors.js";
+import { rootPrefixOf, splicePart } from "../ooxml/partSplice.js";
+import {
+  decodeUtf8,
+  elementChildren,
+  encodeUtf8,
+  parseXml
+} from "../ooxml/xml.js";
+import {
+  directoryOf,
+  readRelationships,
+  relsPathOf,
+  resolveTarget
+} from "./relationships.js";
+var CONTENT_TYPES_PATH = "[Content_Types].xml";
+function relatedPartPath(parts, mainPartPath, type) {
+  const relationship = readRelationships(parts, relsPathOf(mainPartPath)).find(
+    (entry) => entry.type === type && !entry.external
+  );
+  return relationship === void 0 ? null : resolveTarget(mainPartPath, relationship.target);
+}
+function readPart(parts, path) {
+  const bytes = path === null ? void 0 : parts.get(path);
+  return bytes ? decodeUtf8(bytes).text : null;
+}
+function availablePartPath(parts, mainPartPath, stem) {
+  const directory = directoryOf(mainPartPath);
+  const taken = new Set(Array.from(parts.keys(), (path) => path.toLowerCase()));
+  for (let suffix = 0; ; suffix += 1) {
+    const path = `${directory}${stem}${suffix === 0 ? "" : suffix + 1}.xml`;
+    if (!taken.has(path.toLowerCase())) return path;
+  }
+}
+function declaredIn(text) {
+  let root;
+  try {
+    root = parseXml(text).documentElement;
+  } catch (cause) {
+    throw new DocxExportError(
+      "malformed-xml",
+      `${CONTENT_TYPES_PATH} could not be parsed`,
+      { cause }
+    );
+  }
+  const defaults = /* @__PURE__ */ new Set();
+  const overrides = /* @__PURE__ */ new Set();
+  const xmlDefaults = /* @__PURE__ */ new Set();
+  const xmlOverrides = /* @__PURE__ */ new Set();
+  for (const el of elementChildren(root)) {
+    const extension = el.getAttribute("Extension");
+    const partName = el.getAttribute("PartName");
+    const contentType = (el.getAttribute("ContentType") ?? "").split(";")[0].trim().toLowerCase();
+    const xml = contentType === "application/xml" || contentType === "text/xml" || contentType.endsWith("+xml");
+    if (el.localName === "Default" && extension !== null) {
+      defaults.add(extension.toLowerCase());
+      if (xml) xmlDefaults.add(extension.toLowerCase());
+    }
+    if (el.localName === "Override" && partName !== null) {
+      overrides.add(partName.toLowerCase());
+      if (xml) xmlOverrides.add(partName.toLowerCase());
+    }
+  }
+  return { defaults, overrides, xmlDefaults, xmlOverrides };
+}
+function declaredXmlParts(types, paths) {
+  const declared = declaredIn(decodeUtf8(types).text);
+  return new Set(
+    Array.from(paths).filter((path) => {
+      const name = `/${path}`.toLowerCase();
+      if (declared.overrides.has(name)) return declared.xmlOverrides.has(name);
+      const extension = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+      return declared.xmlDefaults.has(extension);
+    })
+  );
+}
+function contentTypeWriter(parts) {
+  const overrides = /* @__PURE__ */ new Map();
+  const defaults = /* @__PURE__ */ new Map();
+  return {
+    addOverride: (partPath, contentType) => {
+      const key = partPath.toLowerCase();
+      if (!overrides.has(key)) overrides.set(key, [partPath, contentType]);
+    },
+    addDefault: (extension, contentType) => {
+      const key = extension.toLowerCase();
+      if (!defaults.has(key)) defaults.set(key, [extension, contentType]);
+    },
+    part: () => {
+      if (overrides.size === 0 && defaults.size === 0) return null;
+      const original = parts.get(CONTENT_TYPES_PATH);
+      if (!original) {
+        throw new DocxExportError(
+          "missing-content-types",
+          `cannot declare a part in a package that has no ${CONTENT_TYPES_PATH}`
+        );
+      }
+      const { text, hadBom } = decodeUtf8(original);
+      const declared = declaredIn(text);
+      const prefix = rootPrefixOf(text);
+      const declarations = [
+        ...Array.from(defaults.values()).filter(
+          ([extension]) => !declared.defaults.has(extension.toLowerCase())
+        ).map(
+          ([extension, contentType]) => elementXml(`${prefix}Default`, [
+            ["Extension", extension],
+            ["ContentType", contentType]
+          ])
+        ),
+        ...Array.from(overrides.values()).filter(
+          ([partPath]) => !declared.overrides.has(`/${partPath}`.toLowerCase())
+        ).map(
+          ([partPath, contentType]) => elementXml(`${prefix}Override`, [
+            ["PartName", `/${partPath}`],
+            ["ContentType", contentType]
+          ])
+        )
+      ];
+      if (declarations.length === 0) return null;
+      return encodeUtf8(
+        splicePart(text, { root: "Types", prepend: declarations.join("") }),
+        hadBom
+      );
+    }
+  };
+}
+export {
+  CONTENT_TYPES_PATH,
+  availablePartPath,
+  contentTypeWriter,
+  declaredXmlParts,
+  readPart,
+  relatedPartPath
+};

package/dist/docx/pageGeometry.d.ts

@@ -21,6 +21,8 @@ export interface PageGeometry {
     marginTopTwips: number;
     marginBottomTwips: number;
 }
+/** CSS calls an inch 96 pixels, and a point is a 72nd of one */
+export declare const PX_PER_PT: number;
 export declare function twipsToPx(twips: number): number;
 /**
  * The paper a document that says nothing is drawn on: A4 portrait with the margins this

package/dist/docx/pageGeometry.js

@@ -1,8 +1,15 @@
 // src/docx/pageGeometry.ts
-import { toNumber, wAttr } from "../ooxml/units.js";
+import {
+  ST_SignedTwipsMeasure,
+  ST_TwipsMeasure,
+  TWIPS_PER_INCH,
+  TWIPS_PER_PT
+} from "../ooxml/simpleTypes.js";
+import { wAttr } from "../ooxml/units.js";
 import { childByLocalName } from "../ooxml/xml.js";
-var TWIPS_PER_CM = 1440 / 2.54;
-var PX_PER_TWIP = 96 / 1440;
+var TWIPS_PER_CM = TWIPS_PER_INCH / 2.54;
+var PX_PER_PT = 96 / 72;
+var PX_PER_TWIP = PX_PER_PT / TWIPS_PER_PT;
 function cm(value) {
   return Math.round(value * TWIPS_PER_CM);
 }
@@ -34,13 +41,14 @@ function readPageGeometry(sectPr) {
   if (!sectPr) return A4_PORTRAIT;
   const pgSz = childByLocalName(sectPr, "pgSz");
   const pgMar = childByLocalName(sectPr, "pgMar");
-  const width = pgSz ? readSize(toNumber(wAttr(pgSz, "w"))) : null;
-  const height = pgSz ? readSize(toNumber(wAttr(pgSz, "h"))) : null;
+  const width = pgSz ? readSize(ST_TwipsMeasure.parse(wAttr(pgSz, "w"))) : null;
+  const height = pgSz ? readSize(ST_TwipsMeasure.parse(wAttr(pgSz, "h"))) : null;
   const readable = width !== null && height !== null;
-  const marginLeft = pgMar ? toNumber(wAttr(pgMar, "left")) : null;
-  const marginRight = pgMar ? toNumber(wAttr(pgMar, "right")) : null;
-  const marginTop = pgMar ? toNumber(wAttr(pgMar, "top")) : null;
-  const marginBottom = pgMar ? toNumber(wAttr(pgMar, "bottom")) : null;
+  const margin = (side) => pgMar ? ST_SignedTwipsMeasure.parse(wAttr(pgMar, side)) : null;
+  const marginLeft = margin("left");
+  const marginRight = margin("right");
+  const marginTop = margin("top");
+  const marginBottom = margin("bottom");
   const geometry = {
     widthTwips: readable ? width : A4_PORTRAIT.widthTwips,
     heightTwips: readable ? height : A4_PORTRAIT.heightTwips,
@@ -79,6 +87,7 @@ function firstSectPrIn(root) {
 export {
   A4_BODY_WIDTH,
   A4_PORTRAIT,
+  PX_PER_PT,
   bodyHeightTwips,
   bodyWidth,
   bodyWidthTwips,

package/dist/docx/paraProps.d.ts

@@ -5,14 +5,12 @@
  * When one paragraph is changed, the formatting we do not touch, such as tab stops and borders,
  * must stay as the original text wrote it. So we never rebuild the fragment; we change it one child
  * at a time, and within a child one attribute at a time.
- * The fragment we operated on is read back with the parser used when opening the document to build
- * the display values, and the style the paragraph points at is layered in the same order as it was
- * then. That way a changed paragraph's display values are the same as they would be after saving
- * and reopening.
+ * What the edited fragment is drawn with is not decided here: the caller hands the fragment to the
+ * resolver (`formatting/resolve`), the same one opening the document uses, so a changed paragraph's
+ * display values are the same as they would be after saving and reopening.
  */
-import type { LineSpacing, NumberingRef, ParagraphAlign, ParagraphFormat, RunFormat } from "../model/format";
+import type { LineSpacing, NumberingRef, ParagraphAlign } from "../model/format";
 import type { LevelIndent } from "../numbering/parseNumbering";
-import { type StyleTable } from "./formatting";
 /** What to do with the indents */
 export type IndentChange = 
 /** Leaves the indents the paragraph wrote down as they are */
@@ -33,32 +31,22 @@ export interface ListChange {
     numbering: NumberingRef | null;
     indent: IndentChange;
 }
-/** The paragraph formatting we operated on, and the display values read back out of it */
+/** The paragraph formatting we operated on. A null `pPr` is a fragment with nothing left in it */
 export interface ParagraphProps {
     pPr: string | null;
-    format: ParagraphFormat | null;
-    /** The character formatting the style the paragraph now wears lays down (`styleRun` in `schema`) */
-    styleRun: RunFormat | null;
 }
-/**
- * Reads the fragment we operated on back along the same path used when opening the document.
- *
- * The values of the style the paragraph wears are laid down underneath (the same order as import),
- * which for a paragraph pointing at no style of its own is the document's default paragraph style.
- */
-export declare function readParagraphProps(pPr: string | null, styles?: StyleTable, defaultStyleId?: string | null): ParagraphFormat | null;
-export declare function withListNumbering(pPr: string | null, change: ListChange, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+export declare function withListNumbering(pPr: string | null, change: ListChange): ParagraphProps | null;
 /**
  * The result of moving the paragraph's own left indent to `leftTwips`.
  * Everything else the indent recorded - the hanging or first-line indent, the right indent -
  * stays as it was.
  */
-export declare function withLeftIndent(pPr: string | null, leftTwips: number, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+export declare function withLeftIndent(pPr: string | null, leftTwips: number): ParagraphProps | null;
 /**
  * The result of changing the line spacing. The space above and below the paragraph is left as it was.
  * `auto` states the multiple in 240ths of a line; the other rules pin the height down in twips.
  */
-export declare function withLineSpacing(pPr: string | null, spacing: LineSpacing, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+export declare function withLineSpacing(pPr: string | null, spacing: LineSpacing): ParagraphProps | null;
 /**
  * The result of pointing the paragraph at a named style.
  * A null id takes the pStyle away, which is how the default style is worn.
@@ -66,9 +54,9 @@ export declare function withLineSpacing(pPr: string | null, spacing: LineSpacing
  * Nothing else in the fragment moves: as in Word, a style is applied by naming it and not by
  * copying its values into the paragraph, so the direct formatting written here keeps beating it.
  */
-export declare function withParagraphStyle(pPr: string | null, styleId: string | null, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+export declare function withParagraphStyle(pPr: string | null, styleId: string | null): ParagraphProps | null;
 /**
  * The result of changing the paragraph alignment.
  * One alignment is always on, so we provide no way to withdraw the setting (the same as Word).
  */
-export declare function withParagraphAlign(pPr: string | null, align: ParagraphAlign, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+export declare function withParagraphAlign(pPr: string | null, align: ParagraphAlign): ParagraphProps | null;