@portone/docx-editor 0.1.1 → 0.2.1

package/dist/docx/comments/people.js

@@ -0,0 +1,196 @@
+// src/docx/comments/people.ts
+import { xmlnsAttr } from "../../ooxml/element.js";
+import { DocxExportError } from "../../ooxml/errors.js";
+import { xmlnsDecl } from "../../ooxml/names.js";
+import {
+  attributeByLocalName,
+  childByLocalName,
+  decodeUtf8,
+  elementChildren,
+  encodeUtf8,
+  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 { renderPerson } from "./grammar.js";
+var NO_PEOPLE = {
+  partPath: null,
+  xml: null,
+  hadBom: false,
+  byAuthor: /* @__PURE__ */ new Map()
+};
+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 bytes = parts.get(partPath);
+  if (!bytes) return { ...NO_PEOPLE, partPath };
+  const { text, hadBom } = decodeUtf8(bytes);
+  const root = parseXml(text).documentElement;
+  const ourIds = /* @__PURE__ */ new Map();
+  const byAuthor = /* @__PURE__ */ new Map();
+  for (const el of elementChildren(root)) {
+    if (el.localName !== "person") continue;
+    const author = attributeByLocalName(el, "author");
+    if (author === null) continue;
+    byAuthor.set(author, null);
+    const presence = childByLocalName(el, "presenceInfo");
+    if (presence === null) continue;
+    if (attributeByLocalName(presence, "providerId") !== COMMENT_AUTHOR_PROVIDER)
+      continue;
+    const ids = ourIds.get(author) ?? /* @__PURE__ */ new Set();
+    ids.add(attributeByLocalName(presence, "userId"));
+    ourIds.set(author, ids);
+  }
+  for (const [author, ids] of ourIds) {
+    if (ids.size !== 1) continue;
+    byAuthor.set(author, Array.from(ids)[0] ?? null);
+  }
+  return { partPath, xml: text, hadBom, byAuthor };
+}
+function commentAuthorId(people, author) {
+  return people.byAuthor.get(author) ?? null;
+}
+function unrecordedAuthors(bodies, people) {
+  const unrecorded = /* @__PURE__ */ new Map();
+  for (const body of bodies) {
+    if (body.author === null || body.authorId === null) continue;
+    if (people.byAuthor.has(body.author)) continue;
+    unrecorded.set(body.author, body.authorId);
+  }
+  return unrecorded;
+}
+function w15Prefix(root) {
+  if (root.namespaceURI === W15_NS) {
+    return root.prefix === null ? "" : `${root.prefix}:`;
+  }
+  const declaration = Array.from(root.attributes).find(
+    (attr) => attr.value === W15_NS && (attr.name === "xmlns" || attr.name.startsWith("xmlns:"))
+  );
+  if (declaration === void 0) return null;
+  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]) => renderPerson(author, userId, "w15:", null)
+    );
+    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 persons = Array.from(
+    added,
+    ([author, userId]) => renderPerson(
+      author,
+      userId,
+      prefix ?? "w15:",
+      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);
+}
+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) {
+  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);
+  if (addingPart) {
+    relationships.add({
+      type: PEOPLE_REL_TYPE,
+      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);
+  }
+  return parts;
+}
+export {
+  NO_PEOPLE,
+  commentAuthorId,
+  planPeoplePart,
+  readPeople
+};

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

@@ -1,9 +1,16 @@
 /**
  * Reads comment and comment-extension package parts.
  */
+import { type ImportedPeople } from "./people";
 export interface ImportedComment {
     id: string;
     author: string | null;
+    /**
+     * The identity the people part records for `author` under this editor's provider. Null when it
+     * records none, and null as well when it records that name under more than one identity, which
+     * leaves no way to tell whose comment this is.
+     */
+    authorId: string | null;
     initials: string | null;
     date: string | null;
     text: string;
@@ -24,6 +31,8 @@ export interface ImportedComments {
     extendedXml: string | null;
     extendedHadBom: boolean;
     extendedOrdered: readonly ImportedCommentExtension[];
+    /** The people part as opened, which is where an author's identity is looked up */
+    people: ImportedPeople;
 }
 export declare const NO_COMMENTS: ImportedComments;
 export interface ImportedCommentExtension {
@@ -32,5 +41,13 @@ export interface ImportedCommentExtension {
     resolved: boolean;
     xml: string;
 }
-/** Reads the Comments part related from the main document story. */
+/** 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 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;

package/dist/docx/comments/reading.js

@@ -1,5 +1,6 @@
 // src/docx/comments/reading.ts
 import {
+  attributeByLocalName,
   decodeUtf8,
   elementChildren,
   parseXml,
@@ -8,9 +9,12 @@ import {
 } from "../../ooxml/xml.js";
 import { readRelationships, relsPathOf, resolveTarget } from "../relationships.js";
 import { COMMENTS_EXTENDED_REL_TYPE, COMMENTS_REL_TYPE } from "./constants.js";
-function attribute(el, localName) {
-  return Array.from(el.attributes).find((entry) => entry.localName === localName)?.value ?? null;
-}
+import { lastBodyParagraph } from "./grammar.js";
+import {
+  commentAuthorId,
+  NO_PEOPLE,
+  readPeople
+} from "./people.js";
 function inlineCommentText(node) {
   if (node.localName === "t") return node.textContent ?? "";
   if (node.localName === "tab") return "	";
@@ -31,11 +35,12 @@ var NO_COMMENTS = {
   extendedPartPath: null,
   extendedXml: null,
   extendedHadBom: false,
-  extendedOrdered: []
+  extendedOrdered: [],
+  people: NO_PEOPLE
 };
 function lastParagraphId(comment) {
-  const paragraphs = Array.from(comment.getElementsByTagNameNS(W_NS, "p"));
-  return paragraphs.length === 0 ? null : attribute(paragraphs[paragraphs.length - 1], "paraId");
+  const last = lastBodyParagraph(comment);
+  return last === null ? null : attributeByLocalName(last, "paraId");
 }
 function readCommentExtensions(parts, mainPartPath) {
   const relationship = readRelationships(parts, relsPathOf(mainPartPath)).find(
@@ -67,13 +72,13 @@ function readCommentExtensions(parts, mainPartPath) {
   const ordered = [];
   for (const el of elementChildren(root)) {
     if (el.localName !== "commentEx") continue;
-    const paraId = attribute(el, "paraId");
+    const paraId = attributeByLocalName(el, "paraId");
     if (paraId === null) continue;
     const extension = {
       paraId,
-      parentParaId: attribute(el, "paraIdParent"),
+      parentParaId: attributeByLocalName(el, "paraIdParent"),
       resolved: ["1", "true", "on"].includes(
-        attribute(el, "done")?.toLowerCase() ?? ""
+        attributeByLocalName(el, "done")?.toLowerCase() ?? ""
       ),
       xml: serializeXml(el)
     };
@@ -83,27 +88,37 @@ function readCommentExtensions(parts, mainPartPath) {
   return { partPath, xml: text, hadBom, byParaId, ordered };
 }
 function readComments(parts, mainPartPath) {
+  const people = readPeople(parts, mainPartPath);
+  const extensions = readCommentExtensions(parts, mainPartPath);
+  const aside = {
+    people,
+    extendedPartPath: extensions.partPath,
+    extendedXml: extensions.xml,
+    extendedHadBom: extensions.hadBom,
+    extendedOrdered: extensions.ordered
+  };
   const relationship = readRelationships(parts, relsPathOf(mainPartPath)).find(
     (entry) => entry.type === COMMENTS_REL_TYPE && !entry.external
   );
-  if (!relationship) return NO_COMMENTS;
+  if (!relationship) return { ...NO_COMMENTS, ...aside };
   const partPath = resolveTarget(mainPartPath, relationship.target);
   const bytes = parts.get(partPath);
-  if (!bytes) return { ...NO_COMMENTS, partPath };
+  if (!bytes) return { ...NO_COMMENTS, partPath, ...aside };
   const { text, hadBom } = decodeUtf8(bytes);
   const root = parseXml(text).documentElement;
-  const extensions = readCommentExtensions(parts, mainPartPath);
   const base = elementChildren(root).filter((el) => el.localName === "comment").flatMap((el) => {
-    const id = attribute(el, "id");
+    const id = attributeByLocalName(el, "id");
     if (id === null) return [];
     const paraId = lastParagraphId(el);
     const extension = paraId ? extensions.byParaId.get(paraId) : void 0;
+    const author = attributeByLocalName(el, "author");
     return [
       {
         id,
-        author: attribute(el, "author"),
-        initials: attribute(el, "initials"),
-        date: attribute(el, "date"),
+        author,
+        authorId: author === null ? null : commentAuthorId(people, author),
+        initials: attributeByLocalName(el, "initials"),
+        date: attributeByLocalName(el, "date"),
         text: commentText(el),
         xml: serializeXml(el),
         paraId,
@@ -137,13 +152,11 @@ function readComments(parts, mainPartPath) {
     ordered,
     byId,
     repliesByParentId,
-    extendedPartPath: extensions.partPath,
-    extendedXml: extensions.xml,
-    extendedHadBom: extensions.hadBom,
-    extendedOrdered: extensions.ordered
+    ...aside
   };
 }
 export {
   NO_COMMENTS,
+  lastParagraphId,
   readComments
 };

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

@@ -0,0 +1,44 @@
+/**
+ * Whether every entry of the three comment parts is one this editor wrote, for an author who was
+ * in a position to write it.
+ *
+ * The parts a comment is written across are the ones a submission may rewrite, so the package
+ * comparison (`../commentOnlyChange`) leaves their bytes alone. Something has to read them, or a
+ * file could carry anything at all inside a comment and still be answered as unchanged. What that
+ * reading holds an entry to is two separate questions. Grammar asks whether this editor's writer
+ * could have put the entry out, whoever it belongs to. Permission asks whether this author could
+ * have made the change. Asking them as one would refuse a moderator rewriting somebody else's
+ * comment under `editableComments: "all"`, which is a thing the editor lets them do.
+ */
+import type { EditableComments } from "../../schema/protection";
+import type { CommentOnlyVerdict } from "../commentOnlyChange";
+import type { Story } from "../storyProjection";
+import { type ImportedPeople } from "./people";
+/**
+ * Whether this editor's writer could have put the entry out, whoever it belongs to.
+ *
+ * Shape alone: which attributes it carries and what stands inside it. Who may have written it is
+ * `entryAllowed`'s question. Each kind is read where it is written (`./grammar`).
+ */
+export declare function wellFormedEntry(entry: Element): boolean;
+/**
+ * Whether `authorId` could have written or rewritten this entry.
+ *
+ * Permission alone: whether the shape is one this editor writes is `wellFormedEntry`'s question.
+ * An entry that appeared has to be this author's. One that arrived keeps the identity it arrived
+ * with; settling its thread or replying to it belong to everyone and leave what it says alone,
+ * while rewriting what it says is its author's, a moderator's, or anyone's where no identity was
+ * recorded for it. That last is the rule the editor holds to (`schema/protection`), and the two
+ * have to answer alike or a file the editor wrote would be turned down here.
+ */
+export declare function entryAllowed(entry: Element, original: Element | null, authorId: string, editableComments: EditableComments, people: ImportedPeople): boolean;
+/**
+ * Whether the three comment parts came back holding only entries this editor writes, each of them
+ * one this author was in a position to write.
+ *
+ * This runs after the story has been judged, so a comment rewritten, re-anchored or deleted by the
+ * wrong hand is already named for what it is (`../commentOnlyChange`). What is left to this is
+ * everything the story cannot show: markup forged into a body, an entry nothing refers to, an
+ * identity recorded for somebody else.
+ */
+export declare function commentPartsKept(before: Story, after: Story, authorId: string, editableComments: EditableComments): CommentOnlyVerdict;

package/dist/docx/comments/verifying.js

@@ -0,0 +1,206 @@
+// src/docx/comments/verifying.ts
+import {
+  attributeByLocalName,
+  elementChildren,
+  isElement,
+  parseXml,
+  serializeXml,
+  W_NS
+} from "../../ooxml/xml.js";
+import { W14_NS, W15_NS } from "./constants.js";
+import {
+  attributesWithin,
+  COMMENT_ATTRIBUTES,
+  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 arrivedEntries(xml, localName, idAttr) {
+  const entries = /* @__PURE__ */ new Map();
+  if (xml === null) return entries;
+  for (const el of elementChildren(parseXml(xml).documentElement)) {
+    if (el.localName !== localName) continue;
+    const id = attributeByLocalName(el, idAttr);
+    if (id === null || entries.has(id)) continue;
+    entries.set(id, { el, xml: serializeXml(el) });
+  }
+  return entries;
+}
+function submittedEntries(xml, namespace, localName, idAttr) {
+  if (xml === null) return [];
+  const entries = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const el of elementChildren(parseXml(xml).documentElement)) {
+    if (el.namespaceURI !== namespace || el.localName !== localName)
+      return null;
+    const id = attributeByLocalName(el, idAttr);
+    if (id === null || seen.has(id)) return null;
+    seen.add(id);
+    entries.push({ id, el, xml: serializeXml(el) });
+  }
+  return entries;
+}
+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;
+}
+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;
+}
+function commentEntries(story) {
+  return Array.from(
+    arrivedEntries(story.session.comments.xml, "comment", "id").values(),
+    (entry) => entry.el
+  );
+}
+var COMMENT_PARTS = [
+  {
+    namespace: W_NS,
+    localName: "comment",
+    idAttr: "id",
+    xmlOf: (story) => story.session.comments.xml,
+    pathOf: (story) => story.session.comments.partPath,
+    referents: (story) => referencedCommentIds(story.doc)
+  },
+  {
+    namespace: W15_NS,
+    localName: "commentEx",
+    idAttr: "paraId",
+    xmlOf: (story) => story.session.comments.extendedXml,
+    pathOf: (story) => story.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];
+      })
+    )
+  },
+  {
+    namespace: W15_NS,
+    localName: "person",
+    idAttr: "author",
+    xmlOf: (story) => story.session.comments.people.xml,
+    pathOf: (story) => story.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];
+      })
+    )
+  }
+];
+function partKept(kind, before, after, authorId, editableComments) {
+  const arrived = arrivedEntries(
+    kind.xmlOf(before),
+    kind.localName,
+    kind.idAttr
+  );
+  const submitted = submittedEntries(
+    kind.xmlOf(after),
+    kind.namespace,
+    kind.localName,
+    kind.idAttr
+  );
+  if (submitted === null) return false;
+  const stoodBehindNow = kind.referents(after);
+  const people = after.session.comments.people;
+  for (const entry of submitted) {
+    const original = arrived.get(entry.id);
+    if (original && original.xml === entry.xml) continue;
+    if (!stoodBehindNow.has(entry.id)) return false;
+    if (original && threadKeyAlone(entry.el, original.el)) continue;
+    if (!wellFormedEntry(entry.el) || !entryAllowed(
+      entry.el,
+      original?.el ?? null,
+      authorId,
+      editableComments,
+      people
+    )) {
+      return false;
+    }
+  }
+  const held = new Set(submitted.map((entry) => entry.id));
+  const stoodBehindBefore = kind.referents(before);
+  return Array.from(arrived.keys()).every(
+    (id) => stoodBehindBefore.has(id) || held.has(id)
+  );
+}
+function commentPartsKept(before, after, authorId, editableComments) {
+  for (const kind of COMMENT_PARTS) {
+    const path = kind.pathOf(after) ?? kind.pathOf(before);
+    if (path === null) continue;
+    if (!partKept(kind, before, after, authorId, editableComments)) {
+      return { ok: false, reason: "part-changed", part: path };
+    }
+  }
+  return { ok: true };
+}
+export {
+  commentPartsKept,
+  entryAllowed,
+  wellFormedEntry
+};

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

@@ -7,5 +7,8 @@ import type { SessionStore } from "../session";
 export interface CommentPartChanges {
     parts: ReadonlyMap<string, Uint8Array>;
 }
-/** Plans the Comments part, relationship and content type only when comment state changed. */
+/**
+ * Plans the Comments part, relationship and content type only when comment state changed, and the
+ * people part beside them for an author whose identity the document has yet to record.
+ */
 export declare function planCommentParts(doc: PMNode, session: SessionStore, relationships: RelationshipWriter, currentContentTypes?: Uint8Array): CommentPartChanges | null;