@portone/docx-editor 0.6.0 → 0.6.1

package/dist/docx/notes/writing.js

@@ -0,0 +1,96 @@
+// src/docx/notes/writing.ts
+import { elementXml } from "../../ooxml/element.js";
+import { wName } from "../../ooxml/names.js";
+import { R_NS } from "../../ooxml/xml.js";
+import { storyEntriesPlanner } from "../storyParts.js";
+var NOTE_CONTENT_TYPES = {
+  footnote: "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml",
+  endnote: "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml"
+};
+var SEPARATORS = [
+  { type: "separator", id: -1 },
+  { type: "continuationSeparator", id: 0 }
+];
+var DECIMAL = /^-?\d+$/;
+function separatorIds(taken) {
+  const held = Array.from(taken).filter((id) => DECIMAL.test(id)).map(Number);
+  return SEPARATORS.reduce((chosen, { id }) => {
+    const used = [...held, ...chosen];
+    return [...chosen, used.includes(id) ? Math.min(0, ...used) - 1 : id];
+  }, []);
+}
+function separatorXml(kind, type, id) {
+  const paragraph = elementXml(
+    wName("p"),
+    [],
+    [
+      elementXml(
+        wName("pPr"),
+        [],
+        [
+          elementXml(wName("spacing"), [
+            [wName("after"), "0"],
+            [wName("line"), "240"],
+            [wName("lineRule"), "auto"]
+          ])
+        ]
+      ),
+      elementXml(wName("r"), [], [elementXml(wName(type), [])])
+    ]
+  );
+  return elementXml(
+    wName(kind),
+    [
+      [wName("type"), type],
+      [wName("id"), String(id)]
+    ],
+    [paragraph]
+  );
+}
+function separatorsXml(kind, taken) {
+  const ids = separatorIds(taken);
+  return SEPARATORS.map(
+    ({ type }, at) => separatorXml(kind, type, ids[at] ?? 0)
+  ).join("");
+}
+function frozenNotes(session, kind) {
+  return new Set(
+    Array.from(session.specialNotes).filter((key) => key.startsWith(`${kind}:`))
+  );
+}
+function referenceIds(doc, kind) {
+  const ids = /* @__PURE__ */ new Set();
+  doc.descendants((node) => {
+    const id = node.attrs.id;
+    if (node.type.name === "noteReference" && node.attrs.kind === kind && typeof id === "string") {
+      ids.add(id);
+    }
+    return true;
+  });
+  return ids;
+}
+function notesPart(kind) {
+  const plural = `${kind}s`;
+  return {
+    name: plural,
+    kind,
+    relType: `${R_NS}/${plural}`,
+    contentType: NOTE_CONTENT_TYPES[kind],
+    stem: plural,
+    root: plural,
+    entry: kind,
+    referencedIds: (doc) => referenceIds(doc, kind),
+    frozenEntries: (session) => frozenNotes(session, kind),
+    prelude: (taken) => separatorsXml(kind, taken)
+  };
+}
+var FOOTNOTES_PART = notesPart("footnote");
+var ENDNOTES_PART = notesPart("endnote");
+var footnotesPlanner = storyEntriesPlanner(FOOTNOTES_PART);
+var endnotesPlanner = storyEntriesPlanner(ENDNOTES_PART);
+export {
+  ENDNOTES_PART,
+  FOOTNOTES_PART,
+  endnotesPlanner,
+  footnotesPlanner
+};

package/dist/docx/partPlan.d.ts

@@ -7,12 +7,15 @@
  * for, so no planner writes either of them itself and none can write over what another declared.
  */
 import type { Node as PMNode } from "prosemirror-model";
+import type { FidelityCollector } from "./fidelity";
 import { type ContentTypeWriter } from "./packageParts";
 import { type RelationshipWriter } from "./relationships";
 import type { SessionStore } from "./session";
 export interface PartPlanContext {
     readonly relationships: RelationshipWriter;
     readonly contentTypes: ContentTypeWriter;
+    /** Where a story writer records an approximation it had to make, beside the body writer's */
+    readonly notes: FidelityCollector;
 }
 export interface PartPlanner {
     readonly name: string;

package/dist/docx/partPlanners.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The parts written beside the body, and what each of their planners carries into the file.
+ *
+ * `docx/exportDocx` runs these planners and `docx/invariants` reads what they write off the same
+ * list, so the two cannot disagree about which change has a writer.
+ */
+import type { PartPlanner } from "./partPlan";
+import { type StoryEntriesPart, type StoryWriting } from "./storyParts";
+export declare const PART_PLANNERS: readonly PartPlanner[];
+/** What every planner writes back of the side stories the document holds */
+export declare const STORY_WRITINGS: readonly StoryWriting[];
+/** The parts written one entry per story, which the identity pass walks as one part apiece */
+export declare const STORY_ENTRIES_PARTS: readonly StoryEntriesPart[];

package/dist/docx/partPlanners.js

@@ -0,0 +1,48 @@
+// src/docx/partPlanners.ts
+import { HEADER_FOOTER_KINDS } from "../schema/stories.js";
+import { commentsPlanner } from "./comments.js";
+import { headerFooterPlanner } from "./headersFooters.js";
+import {
+  ENDNOTES_PART,
+  endnotesPlanner,
+  FOOTNOTES_PART,
+  footnotesPlanner
+} from "./notes/writing.js";
+import { numberingPlanner } from "./numberingPlanner.js";
+import {
+  EVERY_STORY_CHANGE,
+  storyEntriesWriting,
+  storyWriting
+} from "./storyParts.js";
+function entriesWriter(planner, part) {
+  return { planner, writes: [storyEntriesWriting(part)], entriesPart: part };
+}
+var PART_WRITERS = [
+  { planner: numberingPlanner, writes: [], entriesPart: null },
+  {
+    planner: commentsPlanner,
+    writes: [storyWriting("comment", EVERY_STORY_CHANGE)],
+    entriesPart: null
+  },
+  {
+    planner: headerFooterPlanner,
+    writes: HEADER_FOOTER_KINDS.map((kind) => storyWriting(kind, ["edited"])),
+    entriesPart: null
+  },
+  entriesWriter(footnotesPlanner, FOOTNOTES_PART),
+  entriesWriter(endnotesPlanner, ENDNOTES_PART)
+];
+var PART_PLANNERS = PART_WRITERS.map(
+  ({ planner }) => planner
+);
+var STORY_WRITINGS = PART_WRITERS.flatMap(
+  ({ writes }) => writes
+);
+var STORY_ENTRIES_PARTS = PART_WRITERS.flatMap(
+  ({ entriesPart }) => entriesPart === null ? [] : [entriesPart]
+);
+export {
+  PART_PLANNERS,
+  STORY_ENTRIES_PARTS,
+  STORY_WRITINGS
+};

package/dist/docx/sections.d.ts

@@ -11,6 +11,7 @@
  * arrived as, and a rewritten child is swapped into the spot `CT_SectPr` lays down.
  */
 import type { Node as PMNode } from "prosemirror-model";
+import { type NoteNumberingProps } from "./notes/reading";
 import { type PageGeometry } from "./pageGeometry";
 export type HeaderFooterVariant = "default" | "first" | "even";
 /** The variants a `w:headerReference` or a `w:footerReference` may name. §17.6.12, §17.6.5 */
@@ -35,6 +36,10 @@ export interface SectionProperties {
     pageNumberStart: number | null;
     /** §17.6.22 `w:type/@w:val`; null when omitted (nextPage) */
     type: "continuous" | "evenPage" | "nextPage" | "oddPage" | "nextColumn" | null;
+    /** §17.11.11 `w:footnotePr`; null where the section counts footnotes as the settings do */
+    footnotePr: Partial<NoteNumberingProps> | null;
+    /** §17.11.5 `w:endnotePr`; null where the section counts endnotes as the settings do */
+    endnotePr: Partial<NoteNumberingProps> | null;
 }
 /** What a section the document does not spell out lays down: the paper every document used to be drawn on */
 export declare const DEFAULT_SECTION: SectionProperties;

package/dist/docx/sections.js

@@ -15,6 +15,7 @@ import {
   R_NS,
   W_NS
 } from "../ooxml/xml.js";
+import { readNoteProps } from "./notes/reading.js";
 import {
   A4_PORTRAIT,
   readPageGeometry
@@ -32,7 +33,9 @@ var DEFAULT_SECTION = {
   footerRefs: NO_REFS,
   titlePg: false,
   pageNumberStart: null,
-  type: null
+  type: null,
+  footnotePr: null,
+  endnotePr: null
 };
 var SECTION_TYPES = [
   "continuous",
@@ -86,7 +89,9 @@ function readSectionProperties(sectPr) {
     footerRefs: storyRefs(sectPr, "footer"),
     titlePg: isOnElement(childByLocalName(sectPr, "titlePg")),
     pageNumberStart: pageNumberStart(sectPr),
-    type: sectionType(sectPr)
+    type: sectionType(sectPr),
+    footnotePr: readNoteProps(childByLocalName(sectPr, "footnotePr")),
+    endnotePr: readNoteProps(childByLocalName(sectPr, "endnotePr"))
   };
 }
 function parseSectionProperties(xml) {

package/dist/docx/serializeParagraph.js

@@ -1,5 +1,9 @@
 // src/docx/serializeParagraph.ts
-import { elementXml, emptyTagXml, openTagXml } from "../ooxml/element.js";
+import {
+  elementXml,
+  emptyTagXml,
+  openTagXml
+} from "../ooxml/element.js";
 import { DocxExportError } from "../ooxml/errors.js";
 import {
   imageDrawingXml,
@@ -85,8 +89,9 @@ function renderInline(node, images) {
     if (typeof original === "string") return original;
     const id = node.attrs.id;
     const name = node.attrs.kind === "endnote" ? "endnoteReference" : "footnoteReference";
+    const customMark = node.attrs.customMarkFollows === true ? [[wName("customMarkFollows"), "1"]] : [];
     if (typeof id === "string") {
-      return elementXml(wName(name), [[wName("id"), id]]);
+      return elementXml(wName(name), [...customMark, [wName("id"), id]]);
     }
     throw new DocxExportError(
       "lost-original",

package/dist/docx/session.d.ts

@@ -14,6 +14,7 @@ import { type StoryKey } from "../schema/stories";
 import type { ImportedComments } from "./comments/reading";
 import { type FormattingContext, type ParagraphStyleOption } from "./formatting";
 import type { HeaderFooterStories } from "./headersFooters";
+import type { NoteNumbering } from "./notes/reading";
 import type { PageGeometry } from "./pageGeometry";
 import type { ImportedStory } from "./story";
 export interface ImportedBlock {
@@ -83,6 +84,10 @@ export declare class SessionStore implements DocxSession, SessionIdentity {
      * instead (`docx/story`), so the two compare the way a body block and its original do.
      */
     readonly stories: ReadonlyMap<StoryKey, ImportedStory>;
+    /** How the settings count each kind of note, which a section may override (`docx/notes/numbering`) */
+    readonly noteNumbering: NoteNumbering;
+    /** The note entries that lay out the page rather than say anything: separators and the continuation notice */
+    readonly specialNotes: ReadonlySet<StoryKey>;
     constructor(opened: Omit<SessionStore, "kind" | "blocksOf">);
     /**
      * The blocks of one story as it arrived, which is what a block key of that story indexes into.

package/dist/docx/session.js

@@ -51,6 +51,10 @@ var SessionStore = class {
    * instead (`docx/story`), so the two compare the way a body block and its original do.
    */
   stories;
+  /** How the settings count each kind of note, which a section may override (`docx/notes/numbering`) */
+  noteNumbering;
+  /** The note entries that lay out the page rather than say anything: separators and the continuation notice */
+  specialNotes;
   constructor(opened) {
     this.sessionId = opened.sessionId;
     this.parts = opened.parts;
@@ -70,6 +74,8 @@ var SessionStore = class {
     this.commentReferenceIds = opened.commentReferenceIds;
     this.headerFooterStories = opened.headerFooterStories;
     this.stories = opened.stories;
+    this.noteNumbering = opened.noteNumbering;
+    this.specialNotes = opened.specialNotes;
   }
   /**
    * The blocks of one story as it arrived, which is what a block key of that story indexes into.

package/dist/docx/storyParts.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The side stories a part beside the body is written from, told apart by what an edit did to each.
+ *
+ * Whether a story has to be written again is one question every story writer asks, so it is asked
+ * here once. A writer answering it for itself would be free to keep a story another writer drops,
+ * and the export invariants would have a third answer of their own.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import type { DocxExportErrorCode } from "../ooxml/errors";
+import { type StoryKey, type StoryKind } from "../schema/stories";
+import { type StoryToSettle } from "./identities";
+import type { PartPlanner } from "./partPlan";
+import type { SessionStore } from "./session";
+import type { ImportedStory } from "./story";
+export type StoryChange = {
+    readonly change: "kept";
+    readonly imported: ImportedStory;
+} | {
+    readonly change: "edited";
+    readonly imported: ImportedStory;
+    readonly current: PMNode;
+} | {
+    readonly change: "removed";
+    readonly imported: ImportedStory;
+} | {
+    readonly change: "added";
+    readonly key: StoryKey;
+    readonly current: PMNode;
+};
+/** The id a key of this kind names */
+export declare function storyIdOf(key: StoryKey, kind: StoryKind): string;
+/** Every story of this kind the package arrived with or the document now holds, in part order then id order */
+export declare function storyChangesOf(doc: PMNode, session: SessionStore, kind: StoryKind): readonly StoryChange[];
+export type StoryChanged = Exclude<StoryChange["change"], "kept">;
+export declare const EVERY_STORY_CHANGE: readonly StoryChanged[];
+/**
+ * What one part writer carries into the file: the kind of story it writes and the changes to one
+ * it writes back. A change it leaves out has nowhere to go, and `docx/invariants` refuses it.
+ */
+export interface StoryWriting {
+    readonly kind: StoryKind;
+    readonly changes: readonly StoryChanged[];
+    /** The stories it writes as the bytes they arrived as, whose change it therefore carries nowhere */
+    frozenEntries(session: SessionStore): ReadonlySet<StoryKey>;
+}
+/** What a part holding one entry per story writes, which is every change to a story of its kind */
+export declare function storyEntriesWriting(part: StoryEntriesPart): StoryWriting;
+/** A writer that takes these changes to every story of the kind, freezing none of them */
+export declare function storyWriting(kind: StoryKind, changes: readonly StoryChanged[]): StoryWriting;
+/**
+ * Every change the document made to a side story that no part writer carries into the file, as the
+ * key it stands under and what was done to it.
+ *
+ * A story changes on the document node whether or not a writer carries it, so a kind with no
+ * writer at all, a change a writer leaves out - a header story added or removed, which the header
+ * writer does not write - and a change to an entry written as it arrived are all reported here
+ * rather than dropped from the file without a word.
+ */
+export declare function unwrittenStoryChanges(writings: readonly StoryWriting[], doc: PMNode, session: SessionStore): readonly {
+    readonly key: StoryKey;
+    readonly change: StoryChanged;
+}[];
+/** A part holding one entry per story, e.g. `w:footnotes` holding a `w:footnote` apiece */
+export interface StoryEntriesPart {
+    readonly name: string;
+    readonly kind: StoryKind;
+    readonly relType: string;
+    readonly contentType: string;
+    /** The file name a part this planner creates takes beside the main part, ahead of any number */
+    readonly stem: string;
+    /** The local name of the part's root element */
+    readonly root: string;
+    /** The local name of the element each story stands in */
+    readonly entry: string;
+    /** The ids the document's references to this part name, which a part this planner creates keeps clear of */
+    referencedIds(doc: PMNode): ReadonlySet<string>;
+    /**
+     * The stories this part writes as the bytes they arrived as, whatever the document now says of
+     * them, and none for a part that writes every story it holds. `docx/invariants` refuses a change
+     * to one before anything is written.
+     */
+    frozenEntries(session: SessionStore): ReadonlySet<StoryKey>;
+    /** The entries a part this planner creates opens with, before any story */
+    prelude(taken: ReadonlySet<string>): string;
+}
+/**
+ * The stories a part is written with, in the order it writes them, and none where no story of its
+ * kind changed and the part is not written at all. The identity pass runs over this list as one
+ * part, and the export invariants ask the same list.
+ */
+export declare function storyEntriesOf(part: StoryEntriesPart, doc: PMNode, session: SessionStore): readonly StoryToSettle[];
+/** One reason the part cannot take the changes its stories went through */
+export interface StoryPartProblem {
+    readonly code: DocxExportErrorCode;
+    readonly message: string;
+}
+/**
+ * Why the part cannot take what the document did to its stories, or none when it can. The part the
+ * package holds is rewritten around its root element, and a part the package lacks is declared in
+ * the content types part, which the export does not write from nothing.
+ */
+export declare function storyEntriesProblems(part: StoryEntriesPart, doc: PMNode, session: SessionStore): readonly StoryPartProblem[];
+/**
+ * A planner for a part holding one entry per story.
+ *
+ * Nothing is written while every story of the kind stands as it arrived, so an untouched package
+ * hands the part back as its own bytes. Once one changed, the part is written in the order it holds
+ * its entries: an untouched entry as it arrived, an edited one again, a removed one not at all,
+ * and every story added since after them in id order. A package holding no such part gets one,
+ * with its relationship, its content type, and the entries `prelude` opens it with.
+ */
+export declare function storyEntriesPlanner(part: StoryEntriesPart): PartPlanner;