@portone/docx-editor 0.4.0 → 0.5.0

package/dist/docx/importDocx.d.ts

@@ -3,7 +3,7 @@
  *
  * This module knows nothing about the screen. All it knows is the file and the document model.
  */
-import { type Node as PMNode } from "prosemirror-model";
+import type { Node as PMNode } from "prosemirror-model";
 import { type XmlParser } from "../ooxml/xml";
 import { type FidelityNote } from "./fidelity";
 import { SessionStore } from "./session";

package/dist/docx/importDocx.js

@@ -1,5 +1,4 @@
 // src/docx/importDocx.ts
-import { Fragment } from "prosemirror-model";
 import {
   bindsWritingPrefix,
   conformanceOf,
@@ -16,7 +15,10 @@ import {
   withXmlParser
 } from "../ooxml/xml.js";
 import { docxSchema } from "../schema/index.js";
-import { commentReferencesIn, readComments } from "./comments.js";
+import {
+  commentReferencesIn,
+  readComments
+} from "./comments.js";
 import { openParts } from "./container.js";
 import {
   DEFAULT_TAB_STOP_PT,
@@ -28,26 +30,35 @@ import {
   formattingContextOf,
   NO_DOCUMENT_DEFAULTS,
   readDocumentDefaults,
-  readParagraphStyles,
-  styledParagraph
+  readParagraphStyles
 } from "./formatting.js";
-import { readHeadersFooters } from "./headersFooters.js";
+import { readHeaderFooterStories } from "./headersFooters.js";
 import { readLinkTargets } from "./hyperlink.js";
-import { buildParagraph } from "./importParagraph.js";
-import { buildTable } from "./importTable.js";
+import { NO_IMPORT_SOURCES } from "./importParagraph.js";
 import { readImageSources } from "./media.js";
 import { NUMBERING_REL_TYPE } from "./newLists.js";
 import { readNotes } from "./notes.js";
 import { readPart, relatedPartPath } from "./packageParts.js";
-import { readBodyGeometry } from "./pageGeometry.js";
+import { A4_PORTRAIT } from "./pageGeometry.js";
 import { readRelationships } from "./relationships.js";
 import { scanBody } from "./scan.js";
+import {
+  firstSectPrElement,
+  readSectionProperties,
+  storyReferenceIds
+} from "./sections.js";
 import {
   BODY_STORY_KEY,
   blockKey,
   newSessionId,
   SessionStore
 } from "./session.js";
+import {
+  buildBlock,
+  readStories,
+  storiesByKey,
+  withStyleFormats
+} from "./story.js";
 import { NO_THEME_FONTS, readThemeFonts } from "./theme.js";
 var OFFICE_DOCUMENT_REL = `${R_NS}/officeDocument`;
 var STYLES_REL = `${R_NS}/styles`;
@@ -92,36 +103,6 @@ function assertWritableMainPart(root) {
     );
   }
 }
-function buildBlock(el, srcId, sources, context) {
-  if (el.localName === "bookmarkStart" || el.localName === "bookmarkEnd") {
-    return docxSchema.nodes.bookmarkBlock.create({
-      srcId,
-      name: el.nodeName
-    });
-  }
-  if (el.localName === "p") {
-    const paragraph = buildParagraph(el, srcId, sources);
-    if (paragraph) return paragraph;
-  }
-  if (el.localName === "tbl") {
-    const table = buildTable(el, srcId, sources, context);
-    if (table) return table;
-  }
-  return docxSchema.nodes.docxRaw.create({ srcId, name: el.nodeName });
-}
-function withStyleFormats(node, context) {
-  if (node.type === docxSchema.nodes.paragraph) {
-    return styledParagraph(node, context);
-  }
-  if (node.childCount === 0 || node.type === docxSchema.nodes.table) {
-    return node;
-  }
-  const children = node.children.map(
-    (child) => withStyleFormats(child, context)
-  );
-  if (children.every((child, i) => child === node.child(i))) return node;
-  return node.copy(Fragment.fromArray(children));
-}
 function assertScanMatchesDom(children, scan) {
   if (children.length !== scan.blocks.length) {
     throw new DocxImportError(
@@ -138,16 +119,46 @@ function assertScanMatchesDom(children, scan) {
     }
   });
 }
-function foldTrailingSectPr(scan) {
+function splitTrailingSectPr(scan) {
   const last = scan.blocks.at(-1);
-  if (scan.blocks.length < 2 || !last) return scan;
-  if (localPart(last.name) !== "sectPr") return scan;
+  if (!last || localPart(last.name) !== "sectPr") {
+    return { ...scan, sectPr: null };
+  }
   return {
     prefix: scan.prefix,
     blocks: scan.blocks.slice(0, -1),
-    suffix: last.xml + scan.suffix
+    suffix: scan.suffix,
+    sectPr: last.xml
+  };
+}
+function storyDeps(parts, partPath, sessionId, formatting) {
+  return {
+    session: { sessionId },
+    sources: {
+      ...NO_IMPORT_SOURCES,
+      images: readImageSources(parts, partPath),
+      links: readLinkTargets(parts, partPath),
+      themeFonts: formatting.themeFonts
+    },
+    formatting
   };
 }
+function readCommentStories(comments, parts, sessionId, formatting) {
+  const { partPath, xml } = comments;
+  if (partPath === null || xml === null) return [];
+  return readStories(
+    { kind: "comment", partPath, xml, entryName: "comment", idAttr: "id" },
+    storyDeps(parts, partPath, sessionId, formatting)
+  );
+}
+function readNoteStories(part, kind, parts, sessionId, formatting) {
+  const { partPath, xml } = part;
+  if (partPath === null || xml === null) return [];
+  return readStories(
+    { kind, partPath, xml, entryName: kind, idAttr: "id" },
+    storyDeps(parts, partPath, sessionId, formatting)
+  );
+}
 function importDocx(input, options) {
   return withXmlParser(options?.xmlParser, () => readDocx(input));
 }
@@ -169,8 +180,10 @@ function readDocx(input) {
   }
   const children = elementChildren(body);
   assertScanMatchesDom(children, scanned);
-  const geometry = readBodyGeometry(body);
-  const scan = foldTrailingSectPr(scanned);
+  const firstSectPr = firstSectPrElement(body);
+  const firstSection = firstSectPr ? readSectionProperties(firstSectPr) : null;
+  const geometry = firstSection?.geometry ?? A4_PORTRAIT;
+  const scan = splitTrailingSectPr(scanned);
   const blockElements = children.slice(0, scan.blocks.length);
   const stylesXml = readPart(
     parts,
@@ -214,7 +227,6 @@ function readDocx(input) {
     labels.set(id, label);
     return label;
   };
-  const headersFooters = readHeadersFooters(parts, mainPartPath, body);
   const sources = {
     images: readImageSources(parts, mainPartPath),
     themeFonts,
@@ -224,6 +236,24 @@ function readDocx(input) {
     noteLabel
   };
   const sessionId = newSessionId();
+  const headerFooters = readHeaderFooterStories(
+    parts,
+    mainPartPath,
+    storyReferenceIds(body),
+    (partPath) => storyDeps(parts, partPath, sessionId, formatting)
+  );
+  const stories = storiesByKey([
+    ...readCommentStories(comments, parts, sessionId, formatting),
+    ...readNoteStories(
+      notes.footnotes,
+      "footnote",
+      parts,
+      sessionId,
+      formatting
+    ),
+    ...readNoteStories(notes.endnotes, "endnote", parts, sessionId, formatting),
+    ...headerFooters.stories
+  ]);
   const blockNodes = blockElements.map(
     (el, i) => withStyleFormats(
       buildBlock(
@@ -235,7 +265,25 @@ function readDocx(input) {
       formatting
     )
   );
-  const doc = docxSchema.nodes.doc.create(null, blockNodes);
+  if (blockNodes.length === 0 && scan.sectPr !== null) {
+    blockNodes.push(
+      withStyleFormats(
+        docxSchema.nodes.paragraph.create({
+          srcId: blockKey({ sessionId }, BODY_STORY_KEY, 0)
+        }),
+        formatting
+      )
+    );
+  }
+  const doc = docxSchema.nodes.doc.create(
+    {
+      sectPr: scan.sectPr,
+      stories: Object.fromEntries(
+        Array.from(stories, ([key, story]) => [key, story.doc.toJSON()])
+      )
+    },
+    blockNodes
+  );
   return {
     doc,
     notes: fidelityNotesOf(doc, mainPartPath),
@@ -246,7 +294,10 @@ function readDocx(input) {
       documentPrefix: scan.prefix,
       documentSuffix: scan.suffix,
       documentHadBom: hadBom,
-      blocks: blockNodes.map((node, i) => ({ xml: scan.blocks[i].xml, node })),
+      blocks: blockNodes.map((node, i) => ({
+        xml: scan.blocks[i]?.xml ?? "",
+        node
+      })),
       defaults: stylesDom ? readDocumentDefaults(stylesDom, themeFonts) : NO_DOCUMENT_DEFAULTS,
       defaultTabStopPt,
       geometry,
@@ -256,7 +307,8 @@ function readDocx(input) {
       numberingPartPath,
       comments,
       commentReferenceIds: new Set(commentReferencesIn(doc).keys()),
-      headersFooters
+      headerFooterStories: headerFooters.refs,
+      stories
     })
   };
 }

package/dist/docx/importParagraph.d.ts

@@ -6,10 +6,16 @@
  * A `w:sdt` content control and a `w:hyperlink` standing inside the paragraph are both unwrapped, so
  * the text they hold stays editable, and the wrapper each came in rides along on a mark to go back
  * out around the same text. A control may hold a link; a link holding a control is a nesting the
- * marks cannot record in that order, so the paragraph stays preserved.
+ * marks cannot record in that order, and that control stays whole as one preserved fragment.
+ *
+ * Nothing here demotes a paragraph. What the editor has no model for - a field character, a
+ * tracked insertion, a symbol, a drawing nobody could read - is kept where it stood, inside its
+ * run or beside it, by the rule `docx/importPolicy` gives it for the level it stands at. The
+ * paragraph around it stays editable, which is what a document full of `w:lastRenderedPageBreak`
+ * needs.
  */
 import type { Node as PMNode } from "prosemirror-model";
-import { type ImportedComments } from "./comments";
+import { type ImportedComments } from "./comments/reading";
 import { type LinkTargets } from "./hyperlink";
 import type { ImageSources } from "./media";
 import { type ImportedNotes, type NoteKind } from "./notes";
@@ -28,5 +34,11 @@ export interface ImportSources {
     noteLabel: (kind: NoteKind, id: string) => string;
 }
 export declare const NO_IMPORT_SOURCES: ImportSources;
-/** Moves a paragraph into an editable node. null if it holds content we do not model */
-export declare function buildParagraph(el: Element, srcId: string | null, sources?: ImportSources): PMNode | null;
+/**
+ * Moves a paragraph into an editable node.
+ *
+ * Every paragraph opens editable. A child the reader has no model for, and a control or a link
+ * whose shape it could not put back together, is kept whole where it stood instead of standing
+ * the whole paragraph down.
+ */
+export declare function buildParagraph(el: Element, srcId: string | null, sources?: ImportSources): PMNode;

package/dist/docx/importParagraph.js

@@ -9,16 +9,19 @@ import {
   serializeXml
 } from "../ooxml/xml.js";
 import { docxSchema } from "../schema/index.js";
-import {
-  commentParaId,
-  importedCommentReplies,
-  NO_COMMENTS
-} from "./comments.js";
+import { commentParaId, importedCommentReplies } from "./comments/model.js";
+import { NO_COMMENTS } from "./comments/reading.js";
 import { readParagraphFormat, readRunFormat } from "./formatting.js";
 import {
   NO_LINK_TARGETS,
   readHyperlinkWrapper
 } from "./hyperlink.js";
+import { policyFor } from "./importPolicy.js";
+import {
+  buildPreservedInline,
+  buildPreservedRunContent,
+  preservationOf
+} from "./importPreserved.js";
 import { NO_IMAGES } from "./media.js";
 import { NO_NOTES, noteById } from "./notes.js";
 import { readSdtWrapper } from "./sdt.js";
@@ -47,7 +50,7 @@ function buildImage(el, marks, images) {
     marks
   );
 }
-function buildRunChild(el, marks, images, comments, notes, noteLabel) {
+function buildModelledRunChild(el, marks, images, comments, notes, noteLabel) {
   switch (el.localName) {
     case "t": {
       const text = el.textContent ?? "";
@@ -86,9 +89,6 @@ function buildRunChild(el, marks, images, comments, notes, noteLabel) {
             authorId: comment?.authorId ?? null,
             initials: comment?.initials ?? null,
             date: comment?.date ?? null,
-            text: comment?.text ?? "",
-            commentXml: comment?.xml ?? null,
-            imported: true,
             paraId,
             resolved: comment?.resolved ?? false,
             extensionXml: comment?.extensionXml ?? null,
@@ -114,7 +114,6 @@ function buildRunChild(el, marks, images, comments, notes, noteLabel) {
             kind,
             id,
             label: note ? noteLabel(kind, id) : "?",
-            text: note?.text ?? "",
             customMarkFollows,
             referenceXml: serializeXml(el)
           },
@@ -135,22 +134,30 @@ function buildRunNodes(run, images, themeFonts, comments, notes, noteLabel, wrap
   );
   const nodes = [];
   for (const child of elementChildren(run)) {
-    if (child.localName === "rPr") continue;
-    const built = buildRunChild(
-      child,
-      marks,
-      images,
-      comments,
-      notes,
-      noteLabel
+    const policy = policyFor(child, "r");
+    if (policy.tier === "model") {
+      if (child.localName === "rPr") continue;
+      const built = buildModelledRunChild(
+        child,
+        marks,
+        images,
+        comments,
+        notes,
+        noteLabel
+      );
+      if (built !== null) {
+        nodes.push(...built);
+        continue;
+      }
+    }
+    nodes.push(
+      buildPreservedRunContent(child, marks, preservationOf(policy, "r"))
     );
-    if (built === null) return null;
-    nodes.push(...built);
   }
   if (nodes.length === 0) {
     return [
       docxSchema.nodes.rawInline.create(
-        { xml: serializeXml(run) },
+        { xml: serializeXml(run), element: run.localName },
         null,
         // The wrappers have to close again around this XML on export, so their marks ride along here too
         wrappers
@@ -166,13 +173,6 @@ function nextKey(counts, el) {
   counts.set(el.ownerDocument, key + 1);
   return key;
 }
-var NOTHING_ON_SCREEN = [
-  "bookmarkStart",
-  "bookmarkEnd",
-  "proofErr",
-  "permStart",
-  "permEnd"
-];
 function annotationId(el) {
   return Array.from(el.attributes).find((attribute) => attribute.localName === "id")?.value ?? null;
 }
@@ -190,41 +190,42 @@ var NO_IMPORT_SOURCES = {
   notes: NO_NOTES,
   noteLabel: () => "?"
 };
+function buildModelledWrapperChild(child, sources, wrappers, linkAllowed) {
+  if (child.localName === "r") {
+    return buildRunNodes(
+      child,
+      sources.images,
+      sources.themeFonts,
+      sources.comments,
+      sources.notes,
+      sources.noteLabel,
+      wrappers
+    );
+  }
+  if (child.localName === "hyperlink") {
+    return linkAllowed ? buildHyperlinkNodes(child, sources, wrappers) : null;
+  }
+  const commentMarker = commentRangeNode(child, wrappers);
+  return commentMarker === null ? null : [commentMarker];
+}
 function buildWrappedNodes(content, sources, wrappers, linkAllowed) {
   const nodes = [];
   for (const child of elementChildren(content)) {
-    if (child.localName === "r") {
-      const built = buildRunNodes(
+    const policy = policyFor(child, "wrapper");
+    if (policy.tier === "model") {
+      const built = buildModelledWrapperChild(
         child,
-        sources.images,
-        sources.themeFonts,
-        sources.comments,
-        sources.notes,
-        sources.noteLabel,
-        wrappers
+        sources,
+        wrappers,
+        linkAllowed
       );
-      if (built === null) return null;
-      nodes.push(...built);
-      continue;
-    }
-    if (child.localName === "hyperlink" && linkAllowed) {
-      const built = buildHyperlinkNodes(child, sources, wrappers);
-      if (built === null) return null;
-      nodes.push(...built);
-      continue;
+      if (built !== null) {
+        nodes.push(...built);
+        continue;
+      }
     }
-    const commentMarker = commentRangeNode(child, wrappers);
-    if (commentMarker) {
-      nodes.push(commentMarker);
-      continue;
-    }
-    if (!NOTHING_ON_SCREEN.includes(child.localName)) return null;
     nodes.push(
-      docxSchema.nodes.rawInline.create(
-        { xml: serializeXml(child) },
-        null,
-        wrappers
-      )
+      buildPreservedInline(child, wrappers, preservationOf(policy, "wrapper"))
     );
   }
   if (nodes.length === 0) return null;
@@ -251,48 +252,41 @@ function buildSdtNodes(el, sources) {
   });
   return buildWrappedNodes(wrapper.content, sources, [mark], true);
 }
+function buildModelledParagraphChild(child, sources) {
+  if (child.localName === "r") {
+    return buildRunNodes(
+      child,
+      sources.images,
+      sources.themeFonts,
+      sources.comments,
+      sources.notes,
+      sources.noteLabel
+    );
+  }
+  if (child.localName === "sdt") return buildSdtNodes(child, sources);
+  if (child.localName === "hyperlink") {
+    return buildHyperlinkNodes(child, sources, []);
+  }
+  const commentMarker = commentRangeNode(child);
+  return commentMarker === null ? null : [commentMarker];
+}
 function buildParagraph(el, srcId, sources = NO_IMPORT_SOURCES) {
-  const { images, themeFonts } = sources;
   const inline = [];
   let pPrElement = null;
   for (const child of elementChildren(el)) {
-    if (child.localName === "pPr") {
-      pPrElement = child;
-      continue;
+    const policy = policyFor(child, "p");
+    if (policy.tier === "model") {
+      if (child.localName === "pPr") {
+        pPrElement = child;
+        continue;
+      }
+      const built = buildModelledParagraphChild(child, sources);
+      if (built !== null) {
+        inline.push(...built);
+        continue;
+      }
     }
-    if (child.localName === "r") {
-      const runNodes = buildRunNodes(
-        child,
-        images,
-        themeFonts,
-        sources.comments,
-        sources.notes,
-        sources.noteLabel
-      );
-      if (runNodes === null) return null;
-      inline.push(...runNodes);
-      continue;
-    }
-    if (child.localName === "sdt") {
-      const sdtNodes = buildSdtNodes(child, sources);
-      if (sdtNodes === null) return null;
-      inline.push(...sdtNodes);
-      continue;
-    }
-    if (child.localName === "hyperlink") {
-      const linkNodes = buildHyperlinkNodes(child, sources, []);
-      if (linkNodes === null) return null;
-      inline.push(...linkNodes);
-      continue;
-    }
-    const commentMarker = commentRangeNode(child);
-    if (commentMarker) {
-      inline.push(commentMarker);
-      continue;
-    }
-    inline.push(
-      docxSchema.nodes.rawInline.create({ xml: serializeXml(child) })
-    );
+    inline.push(buildPreservedInline(child, [], preservationOf(policy, "p")));
   }
   return docxSchema.nodes.paragraph.create(
     {

package/dist/docx/importPolicy.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What every WordprocessingML element the readers may meet is worth keeping as, one sub-table per
+ * level of the document.
+ *
+ * A reader used to know a handful of elements and answer `null` for the rest, and that `null`
+ * travelled up through the run and the wrapper until a whole paragraph stood as a placeholder. The
+ * table below turns that around: every level has a narrowest preservation of its own - a run child
+ * stays inside its run, a paragraph child inside its paragraph, a block stays a block - so an
+ * element nobody modelled costs the element and nothing around it.
+ *
+ * Only `tbl` and `tr` have no node to hold a stranger (`table` holds rows, `tableRow` holds
+ * cells), so those two levels demote the table instead, and that is the whole of what demotion is
+ * now: this default and a structure a reader could not take apart.
+ *
+ * A level is a content model of `wml.xsd` rather than an element name, because the same name means
+ * different things in different places: `sdt` is a control the paragraph reader unwraps, a cell
+ * wrapper under `tr`, a block placeholder under the body, and a row wrapper nothing reads. Keys are
+ * Clark names (`{namespace}localName`) so that `m:oMath` and `w:sdt` sit in one map.
+ */
+import type { PreservedDisplay } from "../schema";
+export type { PreservedDisplay };
+export type PreservationTier = 
+/** A reader turns it into an editable node */
+"model"
+/** A range marker: invisible, and its pair and order must survive every edit */
+ | "marker"
+/** A trace the producer regenerates: invisible, and an edit may drop it */
+ | "ignorable"
+/** A `CT_R` child: kept verbatim inside its run, wearing the run mark */
+ | "runContent"
+/** A paragraph child: kept verbatim inside the paragraph */
+ | "inline"
+/** A body or cell child: kept verbatim as a block placeholder */
+ | "block";
+export interface PreservationRule {
+    readonly tier: Exclude<PreservationTier, "model">;
+    readonly display: PreservedDisplay;
+    /** The character a `text` display puts on screen */
+    readonly text?: string;
+    /**
+     * Whether the deletion guard answers for this element: a range marker whose pair must survive,
+     * and a field piece whose begin/separate/end order must survive.
+     */
+    readonly guarded: boolean;
+}
+export type ElementPolicy = {
+    readonly tier: "model";
+} | PreservationRule;
+/** What a level with no node to hold a stranger answers: the container around it is demoted */
+export type DemotionPolicy = {
+    readonly tier: "demote";
+};
+/** The levels a reader walks. Each is a content model of its own in `wml.xsd` */
+export type ContentLevel = "body" | "tbl" | "tr" | "tc" | "p" | "wrapper" | "r";
+export declare function clarkName(el: Element): string;
+export declare const WML_POLICY: Readonly<Record<ContentLevel, ReadonlyMap<string, ElementPolicy>>>;
+/** The levels that have a node of their own to keep a stranger in */
+export type PreservingLevel = Exclude<ContentLevel, "tbl" | "tr">;
+export declare function defaultPreservation(level: PreservingLevel): PreservationRule;
+export declare function policyFor(el: Element, level: ContentLevel): ElementPolicy | DemotionPolicy;
+/**
+ * The text one run child puts on screen, or null for a child that puts nothing there.
+ *
+ * This is where the table's answer becomes text, and a preserved fragment carries it along as the
+ * `text` a reader wrote onto it. Everything reading a story as plain text afterwards - a footnote
+ * body, a comment body, a header - asks `docx/story`'s `storyLeafText` for that same answer rather
+ * than keeping a vocabulary of its own, so the three of them cannot disagree about what a `w:cr`
+ * or a `w:noBreakHyphen` reads as.
+ */
+export declare function runContentText(el: Element): string | null;