@portone/docx-editor 0.2.0 → 0.3.0

package/dist/docx/comments/parts.js

@@ -0,0 +1,279 @@
+// src/docx/comments/parts.ts
+import { NAMESPACES } from "../../ooxml/names.js";
+import {
+  attributeByLocalName,
+  isElement,
+  parseXml,
+  serializeXml,
+  W_NS
+} from "../../ooxml/xml.js";
+import { availablePartPath } from "../packageParts.js";
+import {
+  COMMENTS_CONTENT_TYPE,
+  COMMENTS_EXTENDED_CONTENT_TYPE,
+  COMMENTS_EXTENDED_REL_TYPE,
+  COMMENTS_REL_TYPE,
+  PEOPLE_CONTENT_TYPE,
+  PEOPLE_REL_TYPE,
+  W14_NS,
+  W15_NS
+} from "./constants.js";
+import {
+  attributesWithin,
+  COMMENT_ATTRIBUTES,
+  declarationWritten,
+  lastBodyParagraph,
+  readStrictCommentBody,
+  recordedIdentity,
+  wellFormedCommentExtension,
+  wellFormedPerson
+} from "./grammar.js";
+import { commentReferencesIn } from "./model.js";
+import { commentAuthorId } from "./people.js";
+import { lastParagraphId } from "./reading.js";
+var COMMENT_IDENTITY = [
+  "id",
+  "author",
+  "date",
+  "initials"
+];
+function sameAttributes(entry, original, names) {
+  return names.every(
+    (name) => attributeByLocalName(entry, name) === attributeByLocalName(original, name)
+  );
+}
+function wellFormedEntry(entry) {
+  if (entry.namespaceURI === W_NS && entry.localName === "comment") {
+    return attributesWithin(entry, COMMENT_ATTRIBUTES) && readStrictCommentBody(entry) !== null;
+  }
+  if (entry.namespaceURI === W15_NS && entry.localName === "commentEx") {
+    return wellFormedCommentExtension(entry);
+  }
+  if (entry.namespaceURI === W15_NS && entry.localName === "person") {
+    return wellFormedPerson(entry);
+  }
+  return false;
+}
+function withoutThreadKey(entry) {
+  const copy = entry.cloneNode(true);
+  if (!isElement(copy)) return serializeXml(entry);
+  const last = lastBodyParagraph(copy);
+  last?.removeAttributeNS(W14_NS, "paraId");
+  return serializeXml(copy);
+}
+function threadKeyAlone(entry, original) {
+  const before = lastParagraphId(original);
+  const after = lastParagraphId(entry);
+  const kept = before === null || after === before;
+  return kept && withoutThreadKey(entry) === withoutThreadKey(original);
+}
+function entryAllowed(entry, original, authorId, editableComments, people) {
+  if (entry.namespaceURI === W_NS && entry.localName === "comment") {
+    const author = attributeByLocalName(entry, "author");
+    const recorded = author === null ? null : commentAuthorId(people, author);
+    if (original === null) return recorded === authorId;
+    const paraId = lastParagraphId(original);
+    if (!sameAttributes(entry, original, COMMENT_IDENTITY) || paraId !== null && lastParagraphId(entry) !== paraId) {
+      return false;
+    }
+    return editableComments === "all" || recorded === null || recorded === authorId;
+  }
+  if (entry.namespaceURI === W15_NS && entry.localName === "commentEx") {
+    if (original === null) return true;
+    return sameAttributes(entry, original, ["paraId", "paraIdParent"]);
+  }
+  if (entry.namespaceURI === W15_NS && entry.localName === "person") {
+    return original === null && recordedIdentity(entry) === authorId;
+  }
+  return false;
+}
+var TEXT_NODE = 3;
+var COMPATIBILITY = /* @__PURE__ */ new Map([
+  ["xmlns:w14", NAMESPACES.w14],
+  ["xmlns:mc", NAMESPACES.mc]
+]);
+var IGNORABLE = "mc:Ignorable";
+var IGNORED = "w14";
+function isLayout(node) {
+  return node.nodeType === TEXT_NODE && /^[ \t\r\n]*$/.test(node.nodeValue ?? "");
+}
+function surroundingNodes(parent) {
+  return parent === null ? [] : Array.from(parent.childNodes).filter(
+    (node) => !isElement(node) && !isLayout(node)
+  );
+}
+function sameNodes(now, was) {
+  return now.length === was.length && now.every((node, at) => {
+    const original = was[at];
+    return node.nodeType === original.nodeType && node.nodeName === original.nodeName && node.nodeValue === original.nodeValue;
+  });
+}
+function interEntryContentKept(now, was, rewritesContents) {
+  const current = surroundingNodes(now);
+  if (sameNodes(current, surroundingNodes(was))) return true;
+  return rewritesContents && current.length === 0 && was !== null && Array.from(now.children, serializeXml).join("") !== Array.from(was.children, serializeXml).join("");
+}
+function ignorableTokens(value) {
+  return new Set(value.split(/\s+/).filter(Boolean));
+}
+function ignorableKept(now, was) {
+  const gained = ignorableTokens(now);
+  const had = was === null ? /* @__PURE__ */ new Set() : ignorableTokens(was);
+  return Array.from(had).every((token) => gained.has(token)) && Array.from(gained).every((token) => had.has(token) || token === IGNORED);
+}
+function writtenRoot(root, shape) {
+  if (root.namespaceURI !== shape.namespace) return false;
+  if (root.localName !== shape.rootName) return false;
+  return Array.from(root.attributes).every(
+    (attr) => attr.name === IGNORABLE ? ignorableKept(attr.value, null) : declarationWritten(attr) || COMPATIBILITY.get(attr.name) === attr.value
+  );
+}
+function rootKeptAgainst(now, was, shape) {
+  if (was === null) return writtenRoot(now, shape);
+  if (now.nodeName !== was.nodeName) return false;
+  const had = new Map(
+    Array.from(was.attributes, (attr) => [attr.name, attr.value])
+  );
+  const kept = Array.from(now.attributes).every((attr) => {
+    const before = had.get(attr.name) ?? null;
+    if (attr.name === IGNORABLE) return ignorableKept(attr.value, before);
+    if (before === null) return COMPATIBILITY.get(attr.name) === attr.value;
+    return before === attr.value;
+  });
+  return kept && Array.from(had.keys()).every((name) => now.hasAttribute(name));
+}
+function entriesOf(shape, xml, reading) {
+  const entries = /* @__PURE__ */ new Map();
+  if (xml === null) return entries;
+  const strict = reading === "submitted";
+  for (const node of Array.from(parseXml(xml).documentElement.childNodes)) {
+    if (!isElement(node)) continue;
+    const el = node;
+    const named = strict ? el.namespaceURI === shape.namespace && el.localName === shape.localName : el.localName === shape.localName;
+    if (!named) {
+      if (strict) return null;
+      continue;
+    }
+    const id = attributeByLocalName(el, shape.idAttr);
+    if (id === null || entries.has(id)) {
+      if (strict) return null;
+      continue;
+    }
+    entries.set(id, { el, xml: serializeXml(el) });
+  }
+  return entries;
+}
+function arrivedIn(shape, session) {
+  return entriesOf(shape, shape.xmlIn(session), "arrived") ?? /* @__PURE__ */ new Map();
+}
+function storyPart(shape) {
+  return {
+    relType: shape.relType,
+    contentType: shape.contentType,
+    pathIn: shape.pathIn,
+    writePathIn: (session) => shape.pathIn(session) ?? availablePartPath(session.parts, session.mainPartPath, shape.baseName),
+    entriesIn: (session, reading) => entriesOf(shape, shape.xmlIn(session), reading),
+    rootKept: (before, after) => {
+      const submitted = shape.xmlIn(after);
+      if (submitted === null) return true;
+      const arrived = shape.xmlIn(before);
+      const now = parseXml(submitted);
+      const was = arrived === null ? null : parseXml(arrived);
+      return rootKeptAgainst(
+        now.documentElement,
+        was?.documentElement ?? null,
+        shape
+      ) && sameNodes(surroundingNodes(now), surroundingNodes(was)) && interEntryContentKept(
+        now.documentElement,
+        was?.documentElement ?? null,
+        shape.rewritesContents
+      );
+    },
+    referents: shape.referents,
+    wellFormed: wellFormedEntry,
+    anyonesChange: threadKeyAlone,
+    allowed: (entry, original, authorId, options, session) => entryAllowed(
+      entry,
+      original,
+      authorId,
+      options.editableComments,
+      session.comments.people
+    )
+  };
+}
+function referencedCommentIds(doc) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const [id, comment] of commentReferencesIn(doc)) {
+    ids.add(id);
+    for (const reply of comment.replies) ids.add(reply.id);
+  }
+  return ids;
+}
+var commentsShape = {
+  relType: COMMENTS_REL_TYPE,
+  contentType: COMMENTS_CONTENT_TYPE,
+  baseName: "comments",
+  namespace: W_NS,
+  rootName: "comments",
+  rewritesContents: true,
+  localName: "comment",
+  idAttr: "id",
+  xmlIn: (session) => session.comments.xml,
+  pathIn: (session) => session.comments.partPath,
+  referents: (story) => referencedCommentIds(story.doc)
+};
+function commentEntries(story) {
+  return Array.from(
+    arrivedIn(commentsShape, story.session).values(),
+    (entry) => entry.el
+  );
+}
+var commentsPart = storyPart(commentsShape);
+var commentsExtendedPart = storyPart({
+  relType: COMMENTS_EXTENDED_REL_TYPE,
+  contentType: COMMENTS_EXTENDED_CONTENT_TYPE,
+  baseName: "commentsExtended",
+  namespace: W15_NS,
+  rootName: "commentsEx",
+  rewritesContents: true,
+  localName: "commentEx",
+  idAttr: "paraId",
+  xmlIn: (session) => session.comments.extendedXml,
+  pathIn: (session) => session.comments.extendedPartPath,
+  // Thread state stands for a comment, and it is keyed by the comment's own thread key
+  referents: (story) => new Set(
+    commentEntries(story).flatMap((el) => {
+      const key = lastParagraphId(el);
+      return key === null ? [] : [key];
+    })
+  )
+});
+var peoplePart = storyPart({
+  relType: PEOPLE_REL_TYPE,
+  contentType: PEOPLE_CONTENT_TYPE,
+  baseName: "people",
+  namespace: W15_NS,
+  rootName: "people",
+  rewritesContents: false,
+  localName: "person",
+  idAttr: "author",
+  xmlIn: (session) => session.comments.people.xml,
+  pathIn: (session) => session.comments.people.partPath,
+  // An identity stands for a name somebody writes comments under
+  referents: (story) => new Set(
+    commentEntries(story).flatMap((el) => {
+      const author = attributeByLocalName(el, "author");
+      return author === null ? [] : [author];
+    })
+  )
+});
+var COMMENT_STORY_PARTS = [commentsPart, commentsExtendedPart, peoplePart];
+export {
+  COMMENT_STORY_PARTS,
+  commentsExtendedPart,
+  commentsPart,
+  entryAllowed,
+  peoplePart,
+  threadKeyAlone,
+  wellFormedEntry
+};

package/dist/docx/comments/people.d.ts

@@ -9,7 +9,8 @@
  * it stands and never appended to. Appending a second person for it would leave a file naming two
  * identities for one name, where a reader keying by name hands one author's comments to the other.
  */
-import { type RelationshipWriter } from "../relationships";
+import type { PartPlanContext } from "../partPlan";
+import type { StoryPartKind } from "../protectionPolicy";
 import type { SessionStore } from "../session";
 import type { CommentReferenceData, CommentReplyData } from "./model";
 export interface ImportedPeople {
@@ -31,9 +32,17 @@ export declare function readPeople(parts: Map<string, Uint8Array>, mainPartPath:
  * record, and for one the part records under more than one identity.
  */
 export declare function commentAuthorId(people: ImportedPeople, author: string): string | null;
+/**
+ * The authors the part records no person for at all, each under the name they write as. A name it
+ * already records is left as it stands, whichever provider recorded it and whatever it resolves to.
+ */
+export declare function unrecordedAuthors(bodies: Iterable<CommentReferenceData | CommentReplyData>, people: ImportedPeople): Map<string, string>;
 /**
  * Plans the people part, its relationship and its content type for every identity the current
  * comments carry that the document has not recorded. Null when it has recorded them all, which
  * leaves the part as it arrived.
+ *
+ * `part` is the description the verifier reads the part back through (`./parts`), so where this
+ * writes it and what it declares it as are the same facts on both sides.
  */
-export declare function planPeoplePart(bodies: Iterable<CommentReferenceData | CommentReplyData>, session: SessionStore, relationships: RelationshipWriter, currentContentTypes: Uint8Array | undefined): ReadonlyMap<string, Uint8Array> | null;
+export declare function planPeoplePart(part: StoryPartKind, bodies: Iterable<CommentReferenceData | CommentReplyData>, session: SessionStore, context: PartPlanContext): ReadonlyMap<string, Uint8Array> | null;

package/dist/docx/comments/people.js

@@ -1,42 +1,28 @@
 // src/docx/comments/people.ts
-import { DocxExportError } from "../../ooxml/errors.js";
+import { xmlnsAttr } from "../../ooxml/element.js";
+import { xmlnsDecl } from "../../ooxml/names.js";
+import { splicePart } from "../../ooxml/partSplice.js";
 import {
+  attributeByLocalName,
   childByLocalName,
   decodeUtf8,
   elementChildren,
   encodeUtf8,
-  escapeXml,
   parseXml
 } from "../../ooxml/xml.js";
-import {
-  directoryOf,
-  readRelationships,
-  relsPathOf,
-  resolveTarget
-} from "../relationships.js";
-import {
-  COMMENT_AUTHOR_PROVIDER,
-  CONTENT_TYPES_PATH,
-  PEOPLE_CONTENT_TYPE,
-  PEOPLE_REL_TYPE,
-  W15_NS
-} from "./constants.js";
-import { withContentType } from "./contentTypes.js";
+import { relatedPartPath } from "../packageParts.js";
+import { directoryOf } from "../relationships.js";
+import { COMMENT_AUTHOR_PROVIDER, PEOPLE_REL_TYPE, W15_NS } from "./constants.js";
+import { renderPerson } from "./grammar.js";
 var NO_PEOPLE = {
   partPath: null,
   xml: null,
   hadBom: false,
   byAuthor: /* @__PURE__ */ new Map()
 };
-function attribute(el, localName) {
-  return Array.from(el.attributes).find((entry) => entry.localName === localName)?.value ?? null;
-}
 function readPeople(parts, mainPartPath) {
-  const relationship = readRelationships(parts, relsPathOf(mainPartPath)).find(
-    (entry) => entry.type === PEOPLE_REL_TYPE && !entry.external
-  );
-  if (!relationship) return NO_PEOPLE;
-  const partPath = resolveTarget(mainPartPath, relationship.target);
+  const partPath = relatedPartPath(parts, mainPartPath, PEOPLE_REL_TYPE);
+  if (partPath === null) return NO_PEOPLE;
   const bytes = parts.get(partPath);
   if (!bytes) return { ...NO_PEOPLE, partPath };
   const { text, hadBom } = decodeUtf8(bytes);
@@ -45,14 +31,15 @@ function readPeople(parts, mainPartPath) {
   const byAuthor = /* @__PURE__ */ new Map();
   for (const el of elementChildren(root)) {
     if (el.localName !== "person") continue;
-    const author = attribute(el, "author");
+    const author = attributeByLocalName(el, "author");
     if (author === null) continue;
     byAuthor.set(author, null);
     const presence = childByLocalName(el, "presenceInfo");
     if (presence === null) continue;
-    if (attribute(presence, "providerId") !== COMMENT_AUTHOR_PROVIDER) continue;
+    if (attributeByLocalName(presence, "providerId") !== COMMENT_AUTHOR_PROVIDER)
+      continue;
     const ids = ourIds.get(author) ?? /* @__PURE__ */ new Set();
-    ids.add(attribute(presence, "userId"));
+    ids.add(attributeByLocalName(presence, "userId"));
     ourIds.set(author, ids);
   }
   for (const [author, ids] of ourIds) {
@@ -64,9 +51,6 @@ function readPeople(parts, mainPartPath) {
 function commentAuthorId(people, author) {
   return people.byAuthor.get(author) ?? null;
 }
-function personXml(author, userId, prefix, declaration) {
-  return `<${prefix}person${declaration} ${prefix}author="${escapeXml(author)}"><${prefix}presenceInfo ${prefix}providerId="${COMMENT_AUTHOR_PROVIDER}" ${prefix}userId="${escapeXml(userId)}"/></${prefix}person>`;
-}
 function unrecordedAuthors(bodies, people) {
   const unrecorded = /* @__PURE__ */ new Map();
   for (const body of bodies) {
@@ -87,106 +71,43 @@ function w15Prefix(root) {
   const prefix = declaration.name.slice("xmlns:".length);
   return prefix === "" ? "" : `${prefix}:`;
 }
-function rootTagStart(xml) {
-  let at = 0;
-  for (; ; ) {
-    const opens = xml.indexOf("<", at);
-    if (opens === -1) return -1;
-    if (xml.startsWith("<!--", opens)) {
-      at = xml.indexOf("-->", opens + 4) + 3;
-      continue;
-    }
-    if (xml.startsWith("<?", opens)) {
-      at = xml.indexOf("?>", opens + 2) + 2;
-      continue;
-    }
-    return opens;
-  }
-}
-function openTagEnd(xml, at) {
-  let quote = null;
-  for (let i = at; i < xml.length; i += 1) {
-    const character = xml[i];
-    if (quote !== null) {
-      if (character === quote) quote = null;
-      continue;
-    }
-    if (character === '"' || character === "'") {
-      quote = character;
-      continue;
-    }
-    if (character === ">") {
-      return { end: i + 1, selfClosing: xml[i - 1] === "/" };
-    }
-  }
-  return null;
-}
-function malformed(detail) {
-  return new DocxExportError("malformed-xml", `the people part ${detail}`);
-}
 function peopleXml(people, added) {
   const xml = people.xml;
   if (xml === null) {
     const persons2 = Array.from(
       added,
-      ([author, userId]) => personXml(author, userId, "w15:", "")
+      ([author, userId]) => renderPerson(author, userId, "w15:", null)
     );
-    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w15:people xmlns:w15="${W15_NS}">${persons2.join("")}</w15:people>`;
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w15:people ${xmlnsDecl("w15")}>${persons2.join("")}</w15:people>`;
   }
-  const root = parseXml(xml).documentElement;
-  if (root.localName !== "people") {
-    throw malformed("has no people root element");
-  }
-  const prefix = w15Prefix(root);
+  const prefix = w15Prefix(parseXml(xml).documentElement);
   const persons = Array.from(
     added,
-    ([author, userId]) => personXml(
+    ([author, userId]) => renderPerson(
       author,
       userId,
       prefix ?? "w15:",
-      prefix === null ? ` xmlns:w15="${W15_NS}"` : ""
+      prefix === null ? xmlnsAttr("w15") : null
     )
   ).join("");
-  const start = rootTagStart(xml);
-  const open = start === -1 ? null : openTagEnd(xml, start);
-  if (open === null) throw malformed("has no people root element");
-  if (open.selfClosing) {
-    return `${xml.slice(0, open.end - 2)}>${persons}</${root.nodeName}>` + xml.slice(open.end);
-  }
-  const close = xml.lastIndexOf(`</${root.nodeName}`);
-  if (close === -1) throw malformed("has no closing people tag");
-  return xml.slice(0, close) + persons + xml.slice(close);
+  return splicePart(xml, { root: "people", append: persons });
 }
-function availablePeoplePath(session) {
-  const directory = directoryOf(session.mainPartPath);
-  for (let suffix = 0; ; suffix += 1) {
-    const name = suffix === 0 ? "people.xml" : `people${suffix + 1}.xml`;
-    const path = directory + name;
-    if (!session.parts.has(path)) return path;
-  }
-}
-function planPeoplePart(bodies, session, relationships, currentContentTypes) {
+function planPeoplePart(part, bodies, session, context) {
   const people = session.comments.people;
   const added = unrecordedAuthors(bodies, people);
   if (added.size === 0) return null;
   const parts = /* @__PURE__ */ new Map();
-  const addingPart = people.partPath === null;
-  const partPath = people.partPath ?? availablePeoplePath(session);
+  const addingPart = part.pathIn(session) === null;
+  const partPath = part.writePathIn(session);
   if (addingPart) {
-    relationships.add({
-      type: PEOPLE_REL_TYPE,
+    context.relationships.add({
+      type: part.relType,
       target: partPath.slice(directoryOf(session.mainPartPath).length)
     });
   }
   parts.set(partPath, encodeUtf8(peopleXml(people, added), people.hadBom));
   if (addingPart || people.xml === null) {
-    const contentTypes = withContentType(
-      session.parts,
-      partPath,
-      PEOPLE_CONTENT_TYPE,
-      currentContentTypes
-    );
-    if (contentTypes) parts.set(CONTENT_TYPES_PATH, contentTypes);
+    context.contentTypes.addOverride(partPath, part.contentType);
   }
   return parts;
 }
@@ -194,5 +115,6 @@ export {
   NO_PEOPLE,
   commentAuthorId,
   planPeoplePart,
-  readPeople
+  readPeople,
+  unrecordedAuthors
 };

package/dist/docx/comments/policy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The protection that takes comments and nothing else, as the policy both the part planners and
+ * the server verifier read (`../protectionPolicy`).
+ */
+type StoryReason = "body-changed" | "comment-not-owned" | "comment-author-forged";
+export declare const commentsPolicy: import("../protectionPolicy").ProtectionPolicy<StoryReason, "comment-markup-rejected">;
+export {};

package/dist/docx/comments/policy.js

@@ -0,0 +1,43 @@
+// src/docx/comments/policy.ts
+import {
+  commentAdditionsBy,
+  commentEditsOwned,
+  commentIdentitiesKept,
+  withoutComments
+} from "../../schema/protection.js";
+import {
+  registerProtectionPolicy
+} from "../protectionPolicy.js";
+import { comparableStory } from "../storyProjection.js";
+import { COMMENT_STORY_PARTS } from "./parts.js";
+var refused = (reason) => ({ ok: false, reason });
+function sameBody(before, after) {
+  const was = comparableStory(before, withoutComments);
+  const now = comparableStory(after, withoutComments);
+  return was !== null && now !== null && was.length === now.length && was.every((block, at) => block === now[at]);
+}
+function commentsStoryKept(before, after, authorId, { editableComments }) {
+  if (!sameBody(before, after)) return refused("body-changed");
+  if (!commentIdentitiesKept(before.doc, after.doc) || !commentAdditionsBy(before.doc, after.doc, authorId)) {
+    return refused("comment-author-forged");
+  }
+  if (!commentEditsOwned(before.doc, after.doc, {
+    protection: "comments",
+    authorId,
+    editableComments
+  })) {
+    return refused("comment-not-owned");
+  }
+  return { ok: true };
+}
+var commentsPolicy = registerProtectionPolicy(
+  {
+    level: "comments",
+    parts: COMMENT_STORY_PARTS,
+    rejectedMarkup: "comment-markup-rejected",
+    storyKept: commentsStoryKept
+  }
+);
+export {
+  commentsPolicy
+};

package/dist/docx/comments/reading.d.ts

@@ -41,11 +41,13 @@ export interface ImportedCommentExtension {
     resolved: boolean;
     xml: string;
 }
+/** The thread key of a comment, which the writer puts on the last paragraph of its body */
+export declare function lastParagraphId(comment: Element): string | null;
 /**
  * Reads the Comments part related from the main document story.
  *
- * The people part is read whether or not there are comments: a document may carry one with no
- * comment left, and a comment added to it then has to be recorded in that part rather than in a
- * second one.
+ * The people part and the extended part are read whether or not there are comments: a document may
+ * carry either with no comment left, and a comment added to it then has to be written into the
+ * part it already has rather than into a second one beside it.
  */
 export declare function readComments(parts: Map<string, Uint8Array>, mainPartPath: string): ImportedComments;