@portone/docx-editor 0.2.1 → 0.3.0

package/dist/docx/exportDocx.js

@@ -1,14 +1,27 @@
 // src/docx/exportDocx.ts
-import { toParagraphFormat } from "../model/format.js";
-import { parseNumbering } from "../numbering/parseNumbering.js";
-import { addListDefinitions } from "../numbering/writeNumbering.js";
 import { DocxExportError } from "../ooxml/errors.js";
-import { decodeUtf8, encodeUtf8, parseXml, W_NS } from "../ooxml/xml.js";
+import {
+  encodeUtf8,
+  parseXml,
+  W_NS,
+  withXmlParser
+} from "../ooxml/xml.js";
 import { sameSource } from "../schema/sourceEquality.js";
-import { planCommentParts } from "./comments.js";
+import { commentsPlanner } from "./comments.js";
 import { repackParts } from "./container.js";
+import {
+  fidelityNotesOf
+} from "./fidelity.js";
 import { hyperlinkRefs } from "./hyperlink.js";
+import { withUniqueIdentities } from "./identities.js";
+import { problemsOf } from "./invariants.js";
 import { NO_IMAGE_REFS, planImageMedia } from "./media.js";
+import { numberingPlanner } from "./numberingPlanner.js";
+import { CONTENT_TYPES_PATH, contentTypeWriter } from "./packageParts.js";
+import {
+  assertPartsParse,
+  runPartPlanners
+} from "./partPlan.js";
 import {
   readRelationships,
   relationshipWriter,
@@ -19,7 +32,6 @@ import {
   originalBlock,
   sessionOf
 } from "./session.js";
-import { withUniqueControls } from "./uniqueControls.js";
 function blockXml(node, session, refs) {
   const imported = originalBlock(node, session);
   if (imported && sameSource(node, imported.node)) return imported.xml;
@@ -27,7 +39,7 @@ function blockXml(node, session, refs) {
 }
 function buildDocumentXml(doc, session, refs) {
   const pieces = [session.documentPrefix];
-  withUniqueControls(doc).forEach((child) => {
+  withUniqueIdentities(doc).forEach((child) => {
     pieces.push(blockXml(child, session, refs));
   });
   pieces.push(session.documentSuffix);
@@ -85,80 +97,66 @@ function assertBookmarkPairs(documentXml) {
     );
   }
 }
-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);
+var PART_PLANNERS = [
+  numberingPlanner,
+  commentsPlanner
+];
+function exportDocx(doc, session, options) {
+  return exportDocxReport(doc, session, options).bytes;
 }
-function numIdsIn(node) {
-  const used = /* @__PURE__ */ new Set();
-  collectNumIds(node, used);
-  return used;
+function exportDocxReport(doc, session, options) {
+  return reportThrough(PART_PLANNERS, doc, session, options);
 }
-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 exportThroughPlanners(planners, doc, session, options) {
+  return reportThrough(planners, doc, session, options).bytes;
 }
-function newNumberingPart(doc, session) {
-  const added = newNumIds(doc, session);
-  if (added.length === 0) return null;
-  const path = session.numberingPartPath;
-  const original = path === null ? void 0 : session.parts.get(path);
-  if (path === null || original === void 0) {
-    throw new DocxExportError(
-      "missing-numbering-part",
-      "cannot add a new list to a document that has no numbering.xml"
+function reportThrough(planners, doc, session, options) {
+  return withXmlParser(options?.xmlParser, () => {
+    const store = sessionOf(session);
+    const problem = problemsOf(doc, store)[0];
+    if (problem) throw new DocxExportError(problem.code, problem.message);
+    const approximated = [];
+    const bytes = writeDocx(
+      doc,
+      store,
+      { add: (note) => approximated.push(note) },
+      planners
     );
-  }
-  const { text, hadBom } = decodeUtf8(original);
-  return {
-    path,
-    bytes: encodeUtf8(addListDefinitions(text, added), hadBom)
-  };
+    return {
+      bytes,
+      notes: [...fidelityNotesOf(doc, store.mainPartPath), ...approximated]
+    };
+  });
 }
-function exportDocx(doc, session) {
-  const store = sessionOf(session);
+function writeDocx(doc, store, notes, planners) {
   const relsPath = relsPathOf(store.mainPartPath);
-  const relationships = relationshipWriter(
-    readRelationships(store.parts, relsPath)
-  );
-  const media = planImageMedia(doc, store, relationships);
-  const comments = planCommentParts(
-    doc,
-    store,
-    relationships,
-    media?.parts.get("[Content_Types].xml")
-  );
+  const context = {
+    relationships: relationshipWriter(readRelationships(store.parts, relsPath)),
+    contentTypes: contentTypeWriter(store.parts)
+  };
+  const media = planImageMedia(doc, store, context);
   const documentXml = buildDocumentXml(doc, store, {
     images: media?.refs ?? NO_IMAGE_REFS,
-    links: hyperlinkRefs(relationships)
+    links: hyperlinkRefs(context.relationships),
+    notes
   });
   assertBookmarkPairs(documentXml);
-  const replacements = /* @__PURE__ */ new Map([
-    [store.mainPartPath, encodeUtf8(documentXml, store.documentHadBom)]
-  ]);
-  const numbering = newNumberingPart(doc, store);
-  if (numbering) replacements.set(numbering.path, numbering.bytes);
-  for (const [path, bytes] of media?.parts ?? []) {
-    replacements.set(path, bytes);
-  }
-  for (const [path, bytes] of comments?.parts ?? []) {
-    replacements.set(path, bytes);
-  }
-  const rels = relationships.part(store.parts.get(relsPath));
-  if (rels) replacements.set(relsPath, rels);
-  return repackParts(store.parts, replacements);
+  const parts = runPartPlanners(planners, doc, store, context, media?.parts);
+  const rels = context.relationships.part(store.parts.get(relsPath));
+  if (rels) parts.set(relsPath, rels);
+  const contentTypes = context.contentTypes.part();
+  if (contentTypes) parts.set(CONTENT_TYPES_PATH, contentTypes);
+  assertPartsParse(parts, contentTypes ?? store.parts.get(CONTENT_TYPES_PATH));
+  return repackParts(
+    store.parts,
+    new Map([
+      [store.mainPartPath, encodeUtf8(documentXml, store.documentHadBom)],
+      ...parts
+    ])
+  );
 }
 export {
-  exportDocx
+  exportDocx,
+  exportDocxReport,
+  exportThroughPlanners
 };

package/dist/docx/exportRefs.d.ts

@@ -1,16 +1,19 @@
 /**
  * What the serializers need from the rest of the package while a body is being written: which
- * relationship an inserted image ended up on (`docx/media`), and which one each link's address
- * lives on (`docx/hyperlink`).
+ * relationship an inserted image ended up on (`docx/media`), which one each link's address lives
+ * on (`docx/hyperlink`), and where to record an approximation a writer had to make
+ * (`docx/fidelity`).
  *
  * They travel as one value so that a serializer taking a body apart passes on everything the
  * pieces of it may need, whatever a later kind of content turns out to require.
  */
+import { type FidelityCollector } from "./fidelity";
 import { type LinkRefs } from "./hyperlink";
 import { type ImageRefs } from "./media";
 export interface ExportRefs {
     images: ImageRefs;
     links: LinkRefs;
+    notes: FidelityCollector;
 }
 /** What a serializer called on its own, outside an export, has to work with */
 export declare const NO_EXPORT_REFS: ExportRefs;

package/dist/docx/exportRefs.js

@@ -1,9 +1,11 @@
 // src/docx/exportRefs.ts
+import { NO_FIDELITY_COLLECTOR } from "./fidelity.js";
 import { NO_LINK_REFS } from "./hyperlink.js";
 import { NO_IMAGE_REFS } from "./media.js";
 var NO_EXPORT_REFS = {
   images: NO_IMAGE_REFS,
-  links: NO_LINK_REFS
+  links: NO_LINK_REFS,
+  notes: NO_FIDELITY_COLLECTOR
 };
 export {
   NO_EXPORT_REFS

package/dist/docx/fidelity.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What a document holds that this editor could not model, as a list a host application can read.
+ *
+ * Opening a file quietly hides some markup, stands a placeholder in front of the rest, and a
+ * writer approximates a little more on the way back out. None of that shows on the page, so this
+ * is where it is said out loud: one note per preserved node, plus whatever a write approximated.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+export type FidelitySeverity = 
+/** Carried through whole, with nothing of it on screen */
+"hidden"
+/** Carried through whole behind a placeholder that stands in its place and cannot be edited */
+ | "placeholder"
+/** Written back as something near what arrived rather than as what arrived */
+ | "approximated";
+export type FidelityCode = "preserved-run-content" | "preserved-inline" | "preserved-block" | "range-marker" | "paragraph-demoted" | "table-demoted";
+export interface FidelityNote {
+    severity: FidelitySeverity;
+    code: FidelityCode;
+    /** The package path of the part this is about, or null when the caller holds no session */
+    part: string | null;
+    /** Which block of the body as it was opened this falls in. null for a node made while editing */
+    block: number | null;
+    /** Where the node stands in the document. null for an approximation with no node behind it */
+    pos: number | null;
+    /** The original element, for example `w:bookmarkStart` */
+    element: string;
+}
+/** Where a writer records an approximation it had to make while a body was written */
+export interface FidelityCollector {
+    add(note: FidelityNote): void;
+}
+/** What a serializer called on its own, outside an export, records its approximations to */
+export declare const NO_FIDELITY_COLLECTOR: FidelityCollector;
+/**
+ * One note per preserved node, in document order.
+ *
+ * The nodes carry the original element and the block they came from themselves, so the list is a
+ * projection of the document rather than something an import has to remember alongside it. A
+ * document opened and one edited for an hour are read the same way, and a `pos` is enough to take
+ * a reader to the node the note is about.
+ */
+export declare function fidelityNotesOf(doc: PMNode, part: string | null): FidelityNote[];

package/dist/docx/fidelity.js

@@ -0,0 +1,64 @@
+// src/docx/fidelity.ts
+import { localPart } from "../ooxml/xml.js";
+import { splitBlockKey } from "./session.js";
+var NO_FIDELITY_COLLECTOR = { add: () => {
+} };
+function stringAttr(value) {
+  return typeof value === "string" ? value : null;
+}
+function elementNameOf(xml) {
+  return /^\s*<\s*([^\s/>]+)/.exec(xml)?.[1] ?? null;
+}
+function elementOf(node) {
+  return stringAttr(node.attrs.name) ?? elementNameOf(stringAttr(node.attrs.xml) ?? "");
+}
+function demotedBlock(element) {
+  const name = element === null ? null : localPart(element);
+  if (name === "tbl") return { severity: "placeholder", code: "table-demoted" };
+  if (name === "p") {
+    return { severity: "placeholder", code: "paragraph-demoted" };
+  }
+  return { severity: "placeholder", code: "preserved-block" };
+}
+function preservedBy(node, element) {
+  switch (node.type.name) {
+    case "docxRaw":
+      return demotedBlock(element);
+    case "rawBlock":
+      return { severity: "placeholder", code: "preserved-block" };
+    case "bookmarkBlock":
+      return { severity: "hidden", code: "range-marker" };
+    case "rawInline":
+      return preservedInline(element);
+    default:
+      return null;
+  }
+}
+function preservedInline(element) {
+  const name = element === null ? null : localPart(element);
+  if (name === "r") return null;
+  return name === "bookmarkStart" || name === "bookmarkEnd" ? { severity: "hidden", code: "range-marker" } : { severity: "hidden", code: "preserved-inline" };
+}
+function blockNumberOf(node) {
+  const srcId = stringAttr(node.attrs.srcId);
+  const key = srcId === null ? null : splitBlockKey(srcId);
+  return key?.index ?? null;
+}
+function fidelityNotesOf(doc, part) {
+  const notes = [];
+  let block = null;
+  doc.descendants((node, pos, parent) => {
+    if (parent === doc) block = blockNumberOf(node);
+    const element = elementOf(node);
+    const preserved = preservedBy(node, element);
+    if (preserved) {
+      notes.push({ ...preserved, part, block, pos, element: element ?? "?" });
+    }
+    return true;
+  });
+  return notes;
+}
+export {
+  NO_FIDELITY_COLLECTOR,
+  fidelityNotesOf
+};

package/dist/docx/formatting/attrs.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The derived attrs a paragraph and the run marks inside it carry, worked out from the resolved
+ * hierarchy. Import, the plugin that formats the paragraphs an edit built, the paragraph writers
+ * and the clipboard reader all take them from here, so a paragraph is drawn the same whichever of
+ * them last touched it.
+ */
+import type { Mark } from "prosemirror-model";
+import type { ParagraphFormat, RunFormat } from "../../model/format";
+import type { FormattingContext } from "./context";
+import { type ParagraphPlacement, type ResolvedParagraph } from "./resolve";
+/** The two derived paragraph attrs (`format` and `styleRun` in `schema`) */
+export interface ParagraphAttrs {
+    format: ParagraphFormat | null;
+    styleRun: RunFormat | null;
+}
+export declare function paragraphAttrsOf(paragraph: ResolvedParagraph): ParagraphAttrs;
+export declare function paragraphAttrsFor(pPr: string | null, context: FormattingContext, placement?: ParagraphPlacement | null): ParagraphAttrs;
+/**
+ * The run mark an inline wears under the resolved paragraph, or null when it needs none.
+ *
+ * A mark already there keeps the formatting it wrote down and has its display values read
+ * again, since they were laid over whatever the paragraph wore before. Text carrying no mark
+ * gets one holding nothing but the values the paragraph passes down, so it is drawn the way
+ * import draws a bare `w:r`; such a mark writes no `w:rPr` and changes nothing on the way out.
+ * An inline that is not text and carries no mark is left as it is.
+ */
+export declare function runMarkUnder(mark: Mark | null, isText: boolean, paragraph: ResolvedParagraph, context: FormattingContext): Mark | null;

package/dist/docx/formatting/attrs.js

@@ -0,0 +1,31 @@
+// src/docx/formatting/attrs.ts
+import { docxSchema } from "../../schema/index.js";
+import {
+  resolveParagraph,
+  resolveRun
+} from "./resolve.js";
+function paragraphAttrsOf(paragraph) {
+  return { format: paragraph.format, styleRun: paragraph.styleRun };
+}
+function paragraphAttrsFor(pPr, context, placement = null) {
+  return paragraphAttrsOf(resolveParagraph(pPr, context, placement));
+}
+function runMarkUnder(mark, isText, paragraph, context) {
+  if (mark) {
+    const rPr = mark.attrs.rPr;
+    const format2 = resolveRun(
+      typeof rPr === "string" ? rPr : null,
+      paragraph,
+      context
+    );
+    return mark.type.create({ ...mark.attrs, format: format2 });
+  }
+  if (!isText) return null;
+  const format = resolveRun(null, paragraph, context);
+  return format === null ? null : docxSchema.marks.run.create({ rPr: null, rAttrs: null, format });
+}
+export {
+  paragraphAttrsFor,
+  paragraphAttrsOf,
+  runMarkUnder
+};

package/dist/docx/formatting/context.d.ts

@@ -0,0 +1,31 @@
+import type { RunFormat } from "../../model/format";
+import { type Numbering } from "../../numbering/parseNumbering";
+import { type CompatSettings } from "../documentSettings";
+import { type ThemeFonts } from "../theme";
+import { type StyleTable } from "./styles";
+import type { ParagraphFormatLayer } from "./tabStops";
+/**
+ * Everything a document lays down that the §17.7.2 hierarchy is resolved against.
+ *
+ * Built once when the document is opened and read by every caller that derives a paragraph's or
+ * a run's display values, so that a value is the same whichever path asked for it.
+ */
+export interface FormattingContext {
+    styles: StyleTable;
+    /** The paragraph style a paragraph naming none wears (`w:default="1"`). Null when the document marks none */
+    defaultParagraphStyleId: string | null;
+    defaultTableStyleId: string | null;
+    /** `pPrDefault`, the layer at the base of the hierarchy */
+    paragraphDefaults: ParagraphFormatLayer;
+    /**
+     * `rPrDefault` read in full. It decides what a removed run property falls back to. The default
+     * font and size are supplied through CSS variables; other properties enter derived run values.
+     */
+    runDefaults: RunFormat;
+    numbering: Numbering;
+    themeFonts: ThemeFonts;
+    compat: CompatSettings;
+}
+export declare const NO_FORMATTING: FormattingContext;
+/** The context an opened document resolves against. A document without a styles part lays down nothing */
+export declare function formattingContextOf(styles: Document | null, numbering: Numbering, themeFonts: ThemeFonts, compat?: CompatSettings): FormattingContext;

package/dist/docx/formatting/context.js

@@ -0,0 +1,42 @@
+// src/docx/formatting/context.ts
+import {
+  EMPTY_NUMBERING
+} from "../../numbering/parseNumbering.js";
+import { NO_COMPAT } from "../documentSettings.js";
+import { NO_THEME_FONTS } from "../theme.js";
+import { readDefaultParagraphFormat, readRunDefaults } from "./direct.js";
+import {
+  defaultParagraphStyleIdOf,
+  defaultTableStyleIdOf,
+  NO_STYLES,
+  readStyles
+} from "./styles.js";
+var NO_FORMATTING = {
+  styles: NO_STYLES,
+  defaultParagraphStyleId: null,
+  defaultTableStyleId: null,
+  paragraphDefaults: {},
+  runDefaults: {},
+  numbering: EMPTY_NUMBERING,
+  themeFonts: NO_THEME_FONTS,
+  compat: NO_COMPAT
+};
+function formattingContextOf(styles, numbering, themeFonts, compat = NO_COMPAT) {
+  if (styles === null) {
+    return { ...NO_FORMATTING, numbering, themeFonts, compat };
+  }
+  return {
+    styles: readStyles(styles, themeFonts),
+    defaultParagraphStyleId: defaultParagraphStyleIdOf(styles),
+    defaultTableStyleId: defaultTableStyleIdOf(styles),
+    paragraphDefaults: readDefaultParagraphFormat(styles),
+    runDefaults: readRunDefaults(styles, themeFonts),
+    numbering,
+    themeFonts,
+    compat
+  };
+}
+export {
+  NO_FORMATTING,
+  formattingContextOf
+};

package/dist/docx/formatting/direct.d.ts

@@ -8,11 +8,8 @@
 import { type DocumentDefaults, type LineSpacing, type RunFormat } from "../../model/format";
 import { type ThemeFonts } from "../theme";
 import type { ParagraphFormatLayer } from "./tabStops";
-/**
- * The font names held in a display value.
- * Splits the CSS name list `fontFamilyOf` produced back into individual names.
- */
-export declare function fontNamesOf(cssNames: string | undefined | null): string[];
+/** `w:spacing/@line` counts an automatic line height in 240ths of a line (§17.3.1.33) */
+export declare const LINE_UNITS_PER_LINE = 240;
 /**
  * The line spacing from `w:spacing`.
  * auto means a multiple in 240ths, and the rest are heights pinned down in twips.
@@ -23,6 +20,10 @@ export declare function readRunFormat(rPr: Element | null, themeFonts?: ThemeFon
 export declare const NO_DOCUMENT_DEFAULTS: DocumentDefaults;
 /** Reads the paragraph-property layer at the base of the OOXML hierarchy. */
 export declare function readDefaultParagraphFormat(styles: Document): ParagraphFormatLayer;
+/** Reads the run-property layer at the base of the OOXML hierarchy (`rPrDefault`) in full */
+export declare function readRunDefaults(styles: Document, themeFonts?: ThemeFonts): RunFormat;
+/** The character style a run's formatting points at (`w:rStyle`). null when it points at none */
+export declare function runStyleIdOf(rPr: Element | null): string | null;
 /**
  * Reads the document default font size, font, and line spacing from docDefaults in styles.xml.
  * What is absent is left as null, and the on-screen fallback is decided by the display layer.