@portone/docx-editor 0.6.5 → 0.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/CONTRIBUTING.md +4 -4
  3. package/dist/core.d.ts +7 -0
  4. package/dist/core.js +2 -0
  5. package/dist/docx/commentOnlyChange.d.ts +4 -4
  6. package/dist/docx/comments/constants.d.ts +7 -0
  7. package/dist/docx/comments/constants.js +13 -1
  8. package/dist/docx/comments/dates.d.ts +22 -0
  9. package/dist/docx/comments/dates.js +102 -0
  10. package/dist/docx/comments/durable.d.ts +22 -0
  11. package/dist/docx/comments/durable.js +138 -0
  12. package/dist/docx/comments/grammar.d.ts +10 -1
  13. package/dist/docx/comments/grammar.js +49 -2
  14. package/dist/docx/comments/model.d.ts +10 -2
  15. package/dist/docx/comments/model.js +38 -8
  16. package/dist/docx/comments/parts.d.ts +53 -7
  17. package/dist/docx/comments/parts.js +163 -20
  18. package/dist/docx/comments/people.d.ts +1 -1
  19. package/dist/docx/comments/people.js +5 -15
  20. package/dist/docx/comments/reading.d.ts +26 -0
  21. package/dist/docx/comments/reading.js +109 -49
  22. package/dist/docx/comments/writing.d.ts +2 -7
  23. package/dist/docx/comments/writing.js +30 -43
  24. package/dist/docx/compareDocx.d.ts +154 -0
  25. package/dist/docx/compareDocx.js +218 -0
  26. package/dist/docx/fidelity.js +2 -4
  27. package/dist/docx/importParagraph.js +6 -9
  28. package/dist/docx/invariants.js +19 -6
  29. package/dist/docx/packageParts.d.ts +2 -0
  30. package/dist/docx/packageParts.js +5 -1
  31. package/dist/docx/partPlan.d.ts +12 -0
  32. package/dist/docx/partPlan.js +19 -1
  33. package/dist/docx/protectionPolicy.d.ts +33 -5
  34. package/dist/docx/protectionPolicy.js +93 -47
  35. package/dist/docx/runProps.d.ts +3 -0
  36. package/dist/docx/runProps.js +9 -0
  37. package/dist/docx/sequenceDiff.d.ts +56 -0
  38. package/dist/docx/sequenceDiff.js +252 -0
  39. package/dist/docx/serializeParagraph.js +29 -3
  40. package/dist/docx/storyProjection.d.ts +2 -0
  41. package/dist/docx/storyProjection.js +10 -9
  42. package/dist/docx/textDiff.d.ts +24 -0
  43. package/dist/docx/textDiff.js +38 -0
  44. package/dist/editor/blockControlEdits.js +4 -4
  45. package/dist/editor/commands/comments/editing.js +59 -22
  46. package/dist/editor/commands/comments/model.d.ts +3 -1
  47. package/dist/editor/createEditor.js +6 -9
  48. package/dist/editor/editorDocument.d.ts +4 -0
  49. package/dist/editor/editorDocument.js +10 -0
  50. package/dist/editor/formatSource.d.ts +17 -0
  51. package/dist/editor/formatSource.js +74 -0
  52. package/dist/editor/plugins/caretFormat.d.ts +10 -0
  53. package/dist/editor/plugins/caretFormat.js +39 -0
  54. package/dist/editor/plugins/commentDecorations.js +6 -2
  55. package/dist/editor/plugins/controlContents.d.ts +5 -0
  56. package/dist/editor/plugins/controlContents.js +120 -13
  57. package/dist/editor/plugins/emptyRunPointer.d.ts +9 -0
  58. package/dist/editor/plugins/emptyRunPointer.js +22 -0
  59. package/dist/editor/plugins/inlinePlugins.d.ts +6 -0
  60. package/dist/editor/plugins/inlinePlugins.js +19 -0
  61. package/dist/editor/stories/storyState.js +4 -8
  62. package/dist/editor/views/runMarkView.d.ts +5 -2
  63. package/dist/editor/views/runMarkView.js +12 -1
  64. package/dist/ooxml/errors.d.ts +1 -1
  65. package/dist/ooxml/names.d.ts +2 -0
  66. package/dist/ooxml/names.js +2 -0
  67. package/dist/ooxml/partSplice.d.ts +13 -3
  68. package/dist/ooxml/partSplice.js +45 -18
  69. package/dist/schema/attrRoles.js +4 -1
  70. package/dist/schema/clipboard.js +3 -0
  71. package/dist/schema/docxSchema.d.ts +1 -1
  72. package/dist/schema/docxSchema.js +52 -4
  73. package/dist/schema/emptyRuns.d.ts +3 -0
  74. package/dist/schema/emptyRuns.js +7 -0
  75. package/dist/schema/locks.d.ts +11 -0
  76. package/dist/schema/locks.js +2 -0
  77. package/dist/schema/protection.js +2 -1
  78. package/dist/styles/classNames.d.ts +4 -0
  79. package/dist/styles/classNames.js +4 -0
  80. package/dist/styles/inlineStyle.d.ts +2 -0
  81. package/dist/styles/inlineStyle.js +10 -4
  82. package/dist/styles.css +15 -0
  83. package/dist/ui/CommentsPanel.js +8 -13
  84. package/dist/ui/comments/commentDate.d.ts +7 -0
  85. package/dist/ui/comments/commentDate.js +17 -0
  86. package/package.json +7 -7
package/CHANGELOG.md CHANGED
@@ -1,5 +1,40 @@
1
1
  # @portone/docx-editor
2
2
 
3
+ ## 0.6.7
4
+
5
+ ### Patch Changes
6
+
7
+ - [#209](https://github.com/portone-io/docx-editor/pull/209) [`55cf73e`](https://github.com/portone-io/docx-editor/commit/55cf73e3f66b3b461b2a42b5a29634e2265b3515) Thanks [@Deea222](https://github.com/Deea222)! - Show and fill a highlighted run that holds no text, the blank a form leaves to be filled in.
8
+
9
+ A run with formatting and no characters, such as a yellow-highlighted empty table cell, used to be kept as invisible XML: nothing showed where the blank was, and text typed there came out unformatted.
10
+ Where the run's own properties paint a highlight or a shading, the editor now draws it as a short box, whose width the `--docx-editor-empty-run-width` property sets.
11
+ Any other empty run still takes no room, including one whose highlight or shading comes only from a style.
12
+
13
+ Clicking the box and typing, composing, or pasting fills it: the text takes the run's formatting, whatever formatting pasted text carried, and the box goes in the same undo step.
14
+ Bookmarks and other markers that draw nothing beside the box do not stop it filling, and a blank of other formatting beside it stays.
15
+ In a content control holding only such a run, the text goes into the control and what is typed next stays in it.
16
+ A blank inside a hyperlink, or in a control whose lock keeps its contents from being edited, is not filled; the text goes beside it in the formatting of the text around it.
17
+
18
+ A blank nobody filled goes back out in the file byte for byte as it came, even when the paragraph around it was edited.
19
+
20
+ Typed text now takes the formatting of the nearest text in its paragraph, the text before the caret or else the text after it, passing over what draws nothing, as Word does.
21
+ Text typed beside a bookmark, a comment's range marker, or a formatted run with no text used to take that element's formatting, which usually meant none.
22
+ In a paragraph with no text, typed text takes the properties of a formatted run with no text in it, including properties nothing draws, such as `w:rtl w:val="0"` that Google Docs writes, and the run's revision ids; such text is no longer drawn with the paragraph style's character formatting alone.
23
+
24
+ ## 0.6.6
25
+
26
+ ### Patch Changes
27
+
28
+ - [#199](https://github.com/portone-io/docx-editor/pull/199) [`e315ab9`](https://github.com/portone-io/docx-editor/commit/e315ab93fff2b33f865ee0fbd0bbb16da97282e0) Thanks [@Deea222](https://github.com/Deea222)! - The comments panel shows when each comment and reply was written in the reader's time zone and browser language, rather than in UTC.
29
+ `DocumentComment.date` and `DocumentCommentReply.date` are now that instant as an ISO 8601 string: the UTC time Word 2019 and later record for a comment where the file has one, and otherwise the comment's clock time read on the reader's clock, which is what Word shows.
30
+ A comment added with `NewComment.date` reads the same instant back, and the saved file records it the way Word does, so Word shows it in each reader's time zone as well.
31
+ A comment written by an earlier version of the editor recorded only a UTC time, so its UTC clock digits are now shown as the reader's local time, as Word shows them: it appears shifted by the reader's UTC offset.
32
+ `onlyCommentsChangedBy` accepts the parts Word records a comment's time in, `commentsIds.xml` and `commentsExtensible.xml`, as the editor writes them, and refuses a returned file that removes an entry of a comment still in it from any comment part.
33
+ Put the server running `onlyCommentsChangedBy` on this release or later before, or together with, the editor, as [the verifier's version rule](https://docx-editor.portone.io/docs/core/verifying-a-commenters-file#how-files-are-compared) asks: an earlier verifier refuses every file in which this editor wrote a new comment.
34
+
35
+ - [#192](https://github.com/portone-io/docx-editor/pull/192) [`de9da98`](https://github.com/portone-io/docx-editor/commit/de9da989b23871ecaa32074813c66c9d7704dd28) Thanks [@Deea222](https://github.com/Deea222)! - `compareDocx` on the core entry lists the paragraphs, tables, comments and package parts that differ between two files.
36
+ `onlyCommentsChangedBy` now also refuses a file that declares a comment content type for anything but a comment part it holds, including by extension, or relates a comment part it does not hold.
37
+
3
38
  ## 0.6.5
4
39
 
5
40
  ### Patch Changes
package/CONTRIBUTING.md CHANGED
@@ -63,10 +63,10 @@ Changes limited to tests, fixtures, scripts, or documentation do not need a chan
63
63
  The public API is the exported names and types of the four entry points - `.`, `./core`, `./commands`, and `./table` - together with the parts of the document model that [What a plugin may rely on](https://docx-editor.portone.io/docs/editor-api/plugins-and-presets#what-a-plugin-may-rely-on) calls stable.
64
64
  An attr that page calls internal is not part of it, and neither is anything under `src/` that no entry point reaches.
65
65
 
66
- Choose `patch` unless the change adds to that surface, takes something out of it, or changes what a part of it means.
67
- Those are `minor` while the package is below 1.0.
68
- A diff to `src/schema/attrRoles.ts` is where to check this: a change to a stable document-model attr is `minor` even when the declaration reports do not change.
69
- A declaration added, removed, or rewritten in `etc/*.api.md` after running `pnpm api:update` is what that looks like; a line that only gains or loses an `(undocumented)` marker is not.
66
+ Choose `patch` unless the change takes something out of that surface or changes what a part of it means.
67
+ Those are `minor` while the package is below 1.0; adding to the surface is `patch`, so a new command, option, or attr ships in a patch release.
68
+ A diff to `src/schema/attrRoles.ts` is where to check this: a stable document-model attr that is removed or renamed, or whose value is read differently, is `minor` even when the declaration reports do not change.
69
+ A declaration removed or rewritten in `etc/*.api.md` after running `pnpm api:update` is what that looks like; a declaration that is only added, or a line that only gains or loses an `(undocumented)` marker, is not.
70
70
  Commit the regenerated report in the same commit as the changeset.
71
71
 
72
72
  The changesets that have landed become a release the way [Releasing](https://github.com/portone-io/docx-editor/blob/main/docs/releasing.md) describes.
package/dist/core.d.ts CHANGED
@@ -12,6 +12,12 @@ import { type DocxBytes, type ImportOptions } from "./docx/importDocx";
12
12
  import type { DocxSession } from "./docx/session";
13
13
  export type { CommentOnlyVerdict } from "./docx/commentOnlyChange";
14
14
  export { onlyCommentsChangedBy } from "./docx/commentOnlyChange";
15
+ /**
16
+ * What differs between two files, block by block, for the case where knowing that something
17
+ * changed is not enough. Each block change carries the `pos` a reader can select it by.
18
+ */
19
+ export type { BlockChange, BlockKind, CommentChange, DocxComparison, PartChange, RowChange, } from "./docx/compareDocx";
20
+ export { compareDocx } from "./docx/compareDocx";
15
21
  export type { ExportOptions } from "./docx/exportDocx";
16
22
  export { exportDocx, exportDocxReport } from "./docx/exportDocx";
17
23
  export type { FidelityCode, FidelityNote, FidelitySeverity, } from "./docx/fidelity";
@@ -26,6 +32,7 @@ export type { ExportPartName, ExportProblem, ExportProblemReason, ExportProblemS
26
32
  export { exportProblems } from "./docx/invariants";
27
33
  export type { DocxSession } from "./docx/session";
28
34
  export { documentNumbering, documentPartPath } from "./docx/session";
35
+ export type { TextEdit } from "./docx/textDiff";
29
36
  export type { CellFormat, CellVerticalAlign, DocumentDefaults, HighlightName, LineSpacing, NumberingRef, ParagraphAlign, ParagraphFormat, RowFormat, RowHeight, RunFormat, TableFormat, TableWidth, TableWidthType, UnderlineKind, VerticalAlign, } from "./model/format";
30
37
  export { toCellFormat, toParagraphFormat, toRowFormat, toRunFormat, toTableFormat, toTableWidth, } from "./model/format";
31
38
  export type { LevelAlign, LevelIndent, LevelSuffix, NewList, NewListLevel, NumberFormat, Numbering, NumberingLevel, NumberingList, NumberingOptions, NumberingStyleLinks, ReadLevelRun, } from "./numbering/parseNumbering";
package/dist/core.js CHANGED
@@ -3,6 +3,7 @@ import {
3
3
  importDocx as openDocx
4
4
  } from "./docx/importDocx.js";
5
5
  import { onlyCommentsChangedBy } from "./docx/commentOnlyChange.js";
6
+ import { compareDocx } from "./docx/compareDocx.js";
6
7
  import { exportDocx, exportDocxReport } from "./docx/exportDocx.js";
7
8
  import { exportProblems } from "./docx/invariants.js";
8
9
  import { documentNumbering, documentPartPath } from "./docx/session.js";
@@ -24,6 +25,7 @@ function importDocx(input, options) {
24
25
  export {
25
26
  DocxExportError,
26
27
  DocxImportError,
28
+ compareDocx,
27
29
  documentNumbering,
28
30
  documentPartPath,
29
31
  docxSchema,
@@ -12,8 +12,8 @@ import type { EditableComments } from "../schema/protection";
12
12
  import type { DocxBytes } from "./importDocx";
13
13
  /**
14
14
  * Why a file is not the one it claims to be. `part-changed`, `relationship-changed` and
15
- * `comment-markup-rejected` name the part they were reached over; the other three are about the
16
- * document story itself.
15
+ * `comment-markup-rejected` name the part they were reached over; `body-changed`,
16
+ * `comment-not-owned` and `comment-author-forged` are about the document story itself.
17
17
  */
18
18
  export type CommentOnlyVerdict = {
19
19
  ok: true;
@@ -29,9 +29,9 @@ export type CommentOnlyVerdict = {
29
29
  * Whether the submitted file differs from the original in nothing but comments, every one of them
30
30
  * added, edited, moved, deleted, replied to or settled by the author with this identity.
31
31
  *
32
- * Every part of the package has to arrive as it left, save for the three a comment is written
32
+ * Every part of the package has to arrive as it left, save for the parts a comment is written
33
33
  * across and the relationship and content type they are declared with; the document story itself
34
- * has to read as it did, comments aside. Those three parts are read entry by entry instead
34
+ * has to read as it did, comments aside. Those parts are read entry by entry instead
35
35
  * (`./comments/policy`), since a comment edit is free to rewrite them and something has to say
36
36
  * what it may have written there. A comment carrying no recorded identity is everyone's to
37
37
  * edit here as it is in the editor (`schema/protection`). A comment that appeared carries this
@@ -2,8 +2,15 @@ export declare const COMMENTS_REL_TYPE = "http://schemas.openxmlformats.org/offi
2
2
  export declare const COMMENTS_EXTENDED_REL_TYPE = "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
3
3
  export declare const COMMENTS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
4
4
  export declare const COMMENTS_EXTENDED_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
5
+ /** [MS-DOCX] §2.1.4 and §2.1.5 spell out no types for these parts; these are the Open XML SDK's */
6
+ export declare const COMMENTS_IDS_REL_TYPE = "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds";
7
+ export declare const COMMENTS_IDS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml";
8
+ export declare const COMMENTS_EXTENSIBLE_REL_TYPE = "http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible";
9
+ export declare const COMMENTS_EXTENSIBLE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml";
5
10
  export declare const W14_NS: "http://schemas.microsoft.com/office/word/2010/wordml";
6
11
  export declare const W15_NS: "http://schemas.microsoft.com/office/word/2012/wordml";
12
+ export declare const W16CID_NS: "http://schemas.microsoft.com/office/word/2016/wordml/cid";
13
+ export declare const W16CEX_NS: "http://schemas.microsoft.com/office/word/2018/wordml/cex";
7
14
  export declare const MC_NS: "http://schemas.openxmlformats.org/markup-compatibility/2006";
8
15
  export declare const PEOPLE_REL_TYPE = "http://schemas.microsoft.com/office/2011/relationships/people";
9
16
  export declare const PEOPLE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
@@ -5,8 +5,14 @@ var COMMENTS_REL_TYPE = `${R_NS}/comments`;
5
5
  var COMMENTS_EXTENDED_REL_TYPE = "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
6
6
  var COMMENTS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
7
7
  var COMMENTS_EXTENDED_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
8
+ var COMMENTS_IDS_REL_TYPE = "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds";
9
+ var COMMENTS_IDS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml";
10
+ var COMMENTS_EXTENSIBLE_REL_TYPE = "http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible";
11
+ var COMMENTS_EXTENSIBLE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml";
8
12
  var W14_NS = NAMESPACES.w14;
9
13
  var W15_NS = NAMESPACES.w15;
14
+ var W16CID_NS = NAMESPACES.w16cid;
15
+ var W16CEX_NS = NAMESPACES.w16cex;
10
16
  var MC_NS = NAMESPACES.mc;
11
17
  var PEOPLE_REL_TYPE = "http://schemas.microsoft.com/office/2011/relationships/people";
12
18
  var PEOPLE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
@@ -15,11 +21,17 @@ export {
15
21
  COMMENTS_CONTENT_TYPE,
16
22
  COMMENTS_EXTENDED_CONTENT_TYPE,
17
23
  COMMENTS_EXTENDED_REL_TYPE,
24
+ COMMENTS_EXTENSIBLE_CONTENT_TYPE,
25
+ COMMENTS_EXTENSIBLE_REL_TYPE,
26
+ COMMENTS_IDS_CONTENT_TYPE,
27
+ COMMENTS_IDS_REL_TYPE,
18
28
  COMMENTS_REL_TYPE,
19
29
  COMMENT_AUTHOR_PROVIDER,
20
30
  MC_NS,
21
31
  PEOPLE_CONTENT_TYPE,
22
32
  PEOPLE_REL_TYPE,
23
33
  W14_NS,
24
- W15_NS
34
+ W15_NS,
35
+ W16CEX_NS,
36
+ W16CID_NS
25
37
  };
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Word writes `w:date` as the author's wall clock with a `Z` it does not mean, and the instant as
3
+ * `w16cex:dateUtc` (`spec/notes/comments.md`).
4
+ */
5
+ /**
6
+ * When the comment was written, as an ISO 8601 instant: `dateUtc` where there is one, else `date`
7
+ * on the runtime's clock. A `date` naming no calendar time comes back as written.
8
+ */
9
+ export declare function commentInstant(date: string | null, dateUtc: string | null): string | null;
10
+ export interface WrittenCommentDates {
11
+ /** `w:date`: the runtime's wall clock */
12
+ date: string;
13
+ dateUtc: string | null;
14
+ }
15
+ /**
16
+ * The dates a comment written at `given`, or now, records, to the second as Word writes them. A
17
+ * `given` naming no writable instant goes into `w:date` as given, with no `dateUtc`.
18
+ */
19
+ export declare function writtenCommentDates(given?: string): WrittenCommentDates;
20
+ export declare function dateWritten(value: string | null): boolean;
21
+ /** Whether some zone's clock could show `date` at `dateUtc`: `xsd:dateTime` offsets reach 14 hours */
22
+ export declare function oneInstant(date: string, dateUtc: string): boolean;
@@ -0,0 +1,102 @@
1
+ // src/docx/comments/dates.ts
2
+ var DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?)?(Z|[+-]\d{2}:\d{2})?$/;
3
+ var WRITTEN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
4
+ function offsetOf(zone) {
5
+ if (zone === void 0) return null;
6
+ if (zone === "Z") return 0;
7
+ const sign = zone.startsWith("-") ? -1 : 1;
8
+ const [hours, minutes] = zone.slice(1).split(":").map(Number);
9
+ return sign * (hours * 60 + minutes);
10
+ }
11
+ function onTheCalendar(fields) {
12
+ const date = /* @__PURE__ */ new Date(0);
13
+ date.setUTCFullYear(fields.year, fields.month - 1, fields.day);
14
+ date.setUTCHours(fields.hour, fields.minute, fields.second);
15
+ return date.getUTCFullYear() === fields.year && date.getUTCMonth() === fields.month - 1 && date.getUTCDate() === fields.day && date.getUTCHours() === fields.hour && date.getUTCMinutes() === fields.minute && date.getUTCSeconds() === fields.second;
16
+ }
17
+ function readDateTime(value) {
18
+ const match = DATE_TIME.exec(value);
19
+ if (match === null) return null;
20
+ const [, year, month, day, hour, minute, second, fraction, zone] = match;
21
+ const fields = {
22
+ year: Number(year),
23
+ month: Number(month),
24
+ day: Number(day),
25
+ hour: Number(hour ?? 0),
26
+ minute: Number(minute ?? 0),
27
+ second: Number(second ?? 0),
28
+ millisecond: Number((fraction ?? "").padEnd(3, "0").slice(0, 3)),
29
+ offsetMinutes: offsetOf(zone)
30
+ };
31
+ const offset = fields.offsetMinutes;
32
+ const zoneInRange = offset === null || Math.abs(offset) <= 14 * 60;
33
+ return zoneInRange && onTheCalendar(fields) ? fields : null;
34
+ }
35
+ function utcInstant(fields) {
36
+ const date = /* @__PURE__ */ new Date(0);
37
+ date.setUTCFullYear(fields.year, fields.month - 1, fields.day);
38
+ date.setUTCHours(
39
+ fields.hour,
40
+ fields.minute - (fields.offsetMinutes ?? 0),
41
+ fields.second,
42
+ fields.millisecond
43
+ );
44
+ return date;
45
+ }
46
+ function floatingInstant(fields) {
47
+ const date = /* @__PURE__ */ new Date(0);
48
+ date.setFullYear(fields.year, fields.month - 1, fields.day);
49
+ date.setHours(fields.hour, fields.minute, fields.second, fields.millisecond);
50
+ return date;
51
+ }
52
+ function commentInstant(date, dateUtc) {
53
+ const utc = dateUtc === null ? null : readDateTime(dateUtc);
54
+ if (utc !== null) return utcInstant(utc).toISOString();
55
+ const floating = date === null ? null : readDateTime(date);
56
+ return floating === null ? date : floatingInstant(floating).toISOString();
57
+ }
58
+ var pad = (value, width) => String(value).padStart(width, "0");
59
+ var runtimeClock = (instant) => ({
60
+ year: instant.getFullYear(),
61
+ month: instant.getMonth() + 1,
62
+ day: instant.getDate(),
63
+ hour: instant.getHours(),
64
+ minute: instant.getMinutes(),
65
+ second: instant.getSeconds()
66
+ });
67
+ var utcClock = (instant) => ({
68
+ year: instant.getUTCFullYear(),
69
+ month: instant.getUTCMonth() + 1,
70
+ day: instant.getUTCDate(),
71
+ hour: instant.getUTCHours(),
72
+ minute: instant.getUTCMinutes(),
73
+ second: instant.getUTCSeconds()
74
+ });
75
+ function writtenForm(clock) {
76
+ const { year, month, day, hour, minute, second } = clock;
77
+ if (year < 1 || year > 9999) return null;
78
+ return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}T${pad(hour, 2)}:${pad(minute, 2)}:${pad(second, 2)}Z`;
79
+ }
80
+ function writtenCommentDates(given) {
81
+ const instant = given === void 0 ? /* @__PURE__ */ new Date() : new Date(given);
82
+ const readable = !Number.isNaN(instant.valueOf());
83
+ const date = readable ? writtenForm(runtimeClock(instant)) : null;
84
+ const dateUtc = readable ? writtenForm(utcClock(instant)) : null;
85
+ return date === null || dateUtc === null ? { date: given ?? instant.toISOString(), dateUtc: null } : { date, dateUtc };
86
+ }
87
+ function dateWritten(value) {
88
+ return value !== null && WRITTEN.test(value) && readDateTime(value) !== null;
89
+ }
90
+ function oneInstant(date, dateUtc) {
91
+ const wall = readDateTime(date);
92
+ const utc = readDateTime(dateUtc);
93
+ if (wall === null || utc === null) return false;
94
+ const apart = utcInstant({ ...wall, offsetMinutes: 0 }).valueOf() - utcInstant(utc).valueOf();
95
+ return Math.abs(apart) <= 14 * 60 * 60 * 1e3;
96
+ }
97
+ export {
98
+ commentInstant,
99
+ dateWritten,
100
+ oneInstant,
101
+ writtenCommentDates
102
+ };
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Writes the ids part and the extensible part, where Word records when a comment was written
3
+ * (`spec/notes/comments.md`). Only entries of comments written or deleted here change.
4
+ */
5
+ import type { Node as PMNode } from "prosemirror-model";
6
+ import { type RootDeclarations } from "../../ooxml/partSplice";
7
+ import { type PartPlanContext } from "../partPlan";
8
+ import type { SessionStore } from "../session";
9
+ import { type DurablePartShape } from "./parts";
10
+ type DurablePartName = DurablePartShape["name"];
11
+ export declare function planDurableParts(doc: PMNode, session: SessionStore, context: PartPlanContext): ReadonlyMap<string, Uint8Array>;
12
+ /** A part that arrived and the planner rewrites, as the export invariants read it */
13
+ export interface RewrittenDurablePart {
14
+ name: DurablePartName;
15
+ path: string;
16
+ xml: string;
17
+ declarations: RootDeclarations;
18
+ /** Why it cannot be rewritten around its root, or null when it can */
19
+ rootProblem: string | null;
20
+ }
21
+ export declare function rewrittenDurableParts(doc: PMNode, session: SessionStore): readonly RewrittenDurablePart[];
22
+ export {};
@@ -0,0 +1,138 @@
1
+ // src/docx/comments/durable.ts
2
+ import { xmlnsDecl } from "../../ooxml/names.js";
3
+ import {
4
+ ensureRootDeclarations,
5
+ partRootProblem,
6
+ splicePart
7
+ } from "../../ooxml/partSplice.js";
8
+ import { encodeUtf8, localPart } from "../../ooxml/xml.js";
9
+ import { CONTENT_TYPES_PATH } from "../packageParts.js";
10
+ import { declarePart } from "../partPlan.js";
11
+ import { renderCommentDate, renderCommentId } from "./grammar.js";
12
+ import {
13
+ commentReferencesIn,
14
+ currentCommentBodies,
15
+ originalThreadIds
16
+ } from "./model.js";
17
+ import {
18
+ commentsExtensiblePart,
19
+ commentsIdsPart
20
+ } from "./parts.js";
21
+ var DURABLE_PARTS = [
22
+ commentsIdsPart,
23
+ commentsExtensiblePart
24
+ ];
25
+ function durableChanges(doc, session) {
26
+ const { comments } = session;
27
+ const current = currentCommentBodies(commentReferencesIn(doc));
28
+ const arrived = new Set(comments.ids.ordered.map((entry) => entry.durableId));
29
+ const written = Array.from(current.values()).flatMap(
30
+ (comment) => comment.durableId === null || comment.dateUtc === null || arrived.has(comment.durableId) ? [] : [
31
+ {
32
+ paraId: comment.paraId,
33
+ durableId: comment.durableId,
34
+ dateUtc: comment.dateUtc
35
+ }
36
+ ]
37
+ );
38
+ const deleted = Array.from(
39
+ originalThreadIds(comments, session.commentReferenceIds)
40
+ ).filter((id) => !current.has(id));
41
+ const deletedKeys = new Set(
42
+ deleted.flatMap((id) => {
43
+ const paraId = comments.byId.get(id)?.paraId;
44
+ return paraId == null ? [] : [paraId];
45
+ })
46
+ );
47
+ const deletedDurableIds = new Set(
48
+ comments.ids.ordered.flatMap(
49
+ (entry) => deletedKeys.has(entry.paraId) ? [entry.durableId] : []
50
+ )
51
+ );
52
+ return {
53
+ commentsIds: {
54
+ added: written.map(({ paraId, durableId }) => ({
55
+ name: commentsIdsPart.shape.localName,
56
+ xml: renderCommentId(paraId, durableId)
57
+ })),
58
+ dropped: deletedKeys
59
+ },
60
+ commentsExtensible: {
61
+ added: written.map(({ durableId, dateUtc }) => ({
62
+ name: commentsExtensiblePart.shape.localName,
63
+ xml: renderCommentDate(durableId, dateUtc)
64
+ })),
65
+ dropped: deletedDurableIds
66
+ }
67
+ };
68
+ }
69
+ function partWritten({ shape }, change, session) {
70
+ if (shape.xmlIn(session) === null) {
71
+ return change.added.length > 0 && session.parts.has(CONTENT_TYPES_PATH);
72
+ }
73
+ return change.added.length > 0 || change.dropped.size > 0;
74
+ }
75
+ function markupOf(shape) {
76
+ return { namespaces: { [shape.prefix]: shape.namespace } };
77
+ }
78
+ function childOrderOf(shape) {
79
+ return shape.closingChild === void 0 ? [shape.localName] : [shape.localName, shape.closingChild];
80
+ }
81
+ function partXml(shape, change, session) {
82
+ const xml = shape.xmlIn(session);
83
+ if (xml === null) {
84
+ const name = `${shape.prefix}:${shape.rootName}`;
85
+ return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><${name} ${xmlnsDecl(shape.prefix)}>` + change.added.map((entry) => entry.xml).join("") + `</${name}>`;
86
+ }
87
+ return ensureRootDeclarations(
88
+ splicePart(xml, {
89
+ root: shape.rootName,
90
+ keep: ({ attrs }) => {
91
+ const key = attrs?.find(([name]) => localPart(name) === shape.idAttr);
92
+ return key === void 0 || !change.dropped.has(key[1]);
93
+ },
94
+ insert: change.added,
95
+ order: childOrderOf(shape)
96
+ }),
97
+ markupOf(shape)
98
+ );
99
+ }
100
+ function planPart(part, change, session, context) {
101
+ if (!partWritten(part, change, session)) return /* @__PURE__ */ new Map();
102
+ const { xml, hadBom } = part.shape.imported(session);
103
+ const path = declarePart(part, session, context, xml);
104
+ return /* @__PURE__ */ new Map([
105
+ [path, encodeUtf8(partXml(part.shape, change, session), hadBom)]
106
+ ]);
107
+ }
108
+ function planDurableParts(doc, session, context) {
109
+ const changes = durableChanges(doc, session);
110
+ return new Map(
111
+ DURABLE_PARTS.flatMap((part) => [
112
+ ...planPart(part, changes[part.shape.name], session, context)
113
+ ])
114
+ );
115
+ }
116
+ function rewrittenDurableParts(doc, session) {
117
+ const changes = durableChanges(doc, session);
118
+ return DURABLE_PARTS.flatMap((part) => {
119
+ const { shape } = part;
120
+ const path = part.pathIn(session);
121
+ const xml = shape.xmlIn(session);
122
+ if (path === null || xml === null) return [];
123
+ if (!partWritten(part, changes[shape.name], session)) return [];
124
+ return [
125
+ {
126
+ name: shape.name,
127
+ path,
128
+ xml,
129
+ declarations: markupOf(shape),
130
+ rootProblem: partRootProblem(xml, shape.rootName)
131
+ }
132
+ ];
133
+ });
134
+ }
135
+ export {
136
+ planDurableParts,
137
+ rewrittenDurableParts
138
+ };
@@ -1,5 +1,5 @@
1
1
  /**
2
- * The shapes this editor writes the three comment parts in, and the reading of those shapes.
2
+ * The shapes this editor writes the comment parts in, and the reading of those shapes.
3
3
  *
4
4
  * Each entry is written here and judged here, so the two halves cannot drift apart: a body written
5
5
  * by hand can be told from one this editor put out only where the writer and the reader agree on
@@ -13,6 +13,9 @@ import type { CommentReferenceData, CommentReplyData } from "./model";
13
13
  export declare const COMMENT_ATTRIBUTES: ReadonlySet<string>;
14
14
  /** The attributes this editor writes on a `w15:commentEx` */
15
15
  export declare const COMMENT_EX_ATTRIBUTES: ReadonlySet<string>;
16
+ /** [MS-DOCX] §2.8.3.1 keeps a durable id greater than 0 and less than 0x7FFFFFFF */
17
+ export declare const HIGHEST_DURABLE_ID = 2147483646;
18
+ export declare function isDurableId(value: string | null): value is string;
16
19
  /**
17
20
  * Whether the namespace declaration is one this editor's writer puts out, its value included.
18
21
  *
@@ -88,12 +91,18 @@ export declare function arrivedEntries(partXml: string | null): ReadonlyMap<stri
88
91
  export declare function withThreadKey(commentXml: string, paraId: string, arrived: Element | null): string;
89
92
  /** Whether this editor's writer could have put out this thread state */
90
93
  export declare function wellFormedCommentExtension(entry: Element): boolean;
94
+ /** Whether this editor's writer could have put out this durable id */
95
+ export declare function wellFormedCommentId(entry: Element): boolean;
96
+ /** Whether this editor's writer could have put out this UTC date */
97
+ export declare function wellFormedCommentDate(entry: Element): boolean;
91
98
  /** Whether this editor's writer could have put out this recorded identity */
92
99
  export declare function wellFormedPerson(entry: Element): boolean;
93
100
  /** The identity a recorded person stands for, and null for an entry recording none */
94
101
  export declare function recordedIdentity(person: Element): string | null;
95
102
  /** The thread state of one comment, as this editor writes it into the extended part */
96
103
  export declare function renderCommentExtension(comment: CommentReferenceData | CommentReplyData): string;
104
+ export declare function renderCommentId(paraId: string, durableId: string): string;
105
+ export declare function renderCommentDate(durableId: string, dateUtc: string): string;
97
106
  /**
98
107
  * The identity this editor records for an author, as it writes it into the people part.
99
108
  *
@@ -7,7 +7,14 @@ import {
7
7
  parseXml,
8
8
  W_NS
9
9
  } from "../../ooxml/xml.js";
10
- import { COMMENT_AUTHOR_PROVIDER, W14_NS, W15_NS } from "./constants.js";
10
+ import {
11
+ COMMENT_AUTHOR_PROVIDER,
12
+ W14_NS,
13
+ W15_NS,
14
+ W16CEX_NS,
15
+ W16CID_NS
16
+ } from "./constants.js";
17
+ import { dateWritten } from "./dates.js";
11
18
  var ELEMENT_NODE = 1;
12
19
  var TEXT_NODE = 3;
13
20
  var XMLNS_NS = "http://www.w3.org/2000/xmlns/";
@@ -23,6 +30,14 @@ var COMMENT_EX_ATTRIBUTES = /* @__PURE__ */ new Set([
23
30
  nameKey(W15_NS, "paraIdParent"),
24
31
  nameKey(W15_NS, "done")
25
32
  ]);
33
+ var COMMENT_ID_ATTRIBUTES = /* @__PURE__ */ new Set([
34
+ nameKey(W16CID_NS, "paraId"),
35
+ nameKey(W16CID_NS, "durableId")
36
+ ]);
37
+ var COMMENT_DATE_ATTRIBUTES = /* @__PURE__ */ new Set([
38
+ nameKey(W16CEX_NS, "durableId"),
39
+ nameKey(W16CEX_NS, "dateUtc")
40
+ ]);
26
41
  var PERSON_ATTRIBUTES = /* @__PURE__ */ new Set([
27
42
  nameKey(W15_NS, "author")
28
43
  ]);
@@ -35,10 +50,18 @@ function threadKeyOrNone(el, localName) {
35
50
  const value = attributeByLocalName(el, localName);
36
51
  return value === null || THREAD_KEY.test(value);
37
52
  }
53
+ var HIGHEST_DURABLE_ID = 2147483646;
54
+ function isDurableId(value) {
55
+ if (value === null || !THREAD_KEY.test(value)) return false;
56
+ const number = Number.parseInt(value, 16);
57
+ return number > 0 && number <= HIGHEST_DURABLE_ID;
58
+ }
38
59
  var WRITTEN_NAMESPACES = /* @__PURE__ */ new Map([
39
60
  ["w", NAMESPACES.w],
40
61
  ["w14", NAMESPACES.w14],
41
- ["w15", NAMESPACES.w15]
62
+ ["w15", NAMESPACES.w15],
63
+ ["w16cid", NAMESPACES.w16cid],
64
+ ["w16cex", NAMESPACES.w16cex]
42
65
  ]);
43
66
  function declarationWritten(attr) {
44
67
  if (!attr.name.startsWith("xmlns:")) return false;
@@ -119,6 +142,12 @@ function wellFormedCommentExtension(entry) {
119
142
  return attributesWithin(entry, COMMENT_EX_ATTRIBUTES) && entry.childNodes.length === 0 && threadKeyOrNone(entry, "paraId") && threadKeyOrNone(entry, "paraIdParent") && // The writer says a thread is settled or open, and nothing else `ST_OnOff` would take
120
143
  ["0", "1", null].includes(attributeByLocalName(entry, "done"));
121
144
  }
145
+ function wellFormedCommentId(entry) {
146
+ return attributesWithin(entry, COMMENT_ID_ATTRIBUTES) && entry.childNodes.length === 0 && THREAD_KEY.test(attributeByLocalName(entry, "paraId") ?? "") && isDurableId(attributeByLocalName(entry, "durableId"));
147
+ }
148
+ function wellFormedCommentDate(entry) {
149
+ return attributesWithin(entry, COMMENT_DATE_ATTRIBUTES) && entry.childNodes.length === 0 && isDurableId(attributeByLocalName(entry, "durableId")) && dateWritten(attributeByLocalName(entry, "dateUtc"));
150
+ }
122
151
  function wellFormedPerson(entry) {
123
152
  if (!attributesWithin(entry, PERSON_ATTRIBUTES)) return false;
124
153
  if (!holdsElementsOnly(entry)) return false;
@@ -141,6 +170,18 @@ function renderCommentExtension(comment) {
141
170
  ...done
142
171
  ]);
143
172
  }
173
+ function renderCommentId(paraId, durableId) {
174
+ return elementXml(qualify("w16cid", "commentId"), [
175
+ [qualify("w16cid", "paraId"), paraId],
176
+ [qualify("w16cid", "durableId"), durableId]
177
+ ]);
178
+ }
179
+ function renderCommentDate(durableId, dateUtc) {
180
+ return elementXml(qualify("w16cex", "commentExtensible"), [
181
+ [qualify("w16cex", "durableId"), durableId],
182
+ [qualify("w16cex", "dateUtc"), dateUtc]
183
+ ]);
184
+ }
144
185
  function renderPerson(author, userId, prefix, declaration) {
145
186
  const declared = declaration === null ? [] : [declaration];
146
187
  return elementXml(
@@ -157,18 +198,24 @@ function renderPerson(author, userId, prefix, declaration) {
157
198
  export {
158
199
  COMMENT_ATTRIBUTES,
159
200
  COMMENT_EX_ATTRIBUTES,
201
+ HIGHEST_DURABLE_ID,
160
202
  arrivedEntries,
161
203
  attributesWithin,
162
204
  declarationWritten,
163
205
  declarationsWritten,
164
206
  holdsElementsAndLayout,
165
207
  holdsElementsOnly,
208
+ isDurableId,
166
209
  isLayoutText,
167
210
  lastBodyParagraph,
168
211
  recordedIdentity,
212
+ renderCommentDate,
169
213
  renderCommentExtension,
214
+ renderCommentId,
170
215
  renderPerson,
216
+ wellFormedCommentDate,
171
217
  wellFormedCommentExtension,
218
+ wellFormedCommentId,
172
219
  wellFormedPerson,
173
220
  withThreadKey
174
221
  };
@@ -13,12 +13,15 @@ export interface CommentReferenceData {
13
13
  author: string | null;
14
14
  authorId: string | null;
15
15
  initials: string | null;
16
+ /** As the file writes it: the author's wall clock (`./dates`) */
16
17
  date: string | null;
17
18
  paraId: string;
18
19
  resolved: boolean;
19
20
  extensionXml: string | null;
20
21
  threadImported: boolean;
21
22
  replies: readonly CommentReplyData[];
23
+ durableId: string | null;
24
+ dateUtc: string | null;
22
25
  }
23
26
  export interface CommentReplyData {
24
27
  id: string;
@@ -29,10 +32,15 @@ export interface CommentReplyData {
29
32
  paraId: string;
30
33
  parentParaId: string;
31
34
  extensionXml: string | null;
35
+ durableId: string | null;
36
+ dateUtc: string | null;
32
37
  }
33
- /** A stable Word paragraph id for a comment created or upgraded by the editor. */
34
- export declare function commentParaId(seed: string): string;
38
+ /** A stable eight-digit hex number below 0x80000000, hashed from the seed */
39
+ export declare function seededHexId(seed: string): string;
35
40
  /** Replies below one referenced comment, in the order of the Comments part. */
36
41
  export declare function importedCommentReplies(comments: ImportedComments, rootId: string): readonly CommentReplyData[];
42
+ export declare function currentCommentBodies(references: ReadonlyMap<string, CommentReferenceData>): ReadonlyMap<string, CommentReferenceData | CommentReplyData>;
43
+ /** These comments and every reply under them, however deep, in the part as it arrived */
44
+ export declare function originalThreadIds(comments: ImportedComments, rootIds: ReadonlySet<string>): ReadonlySet<string>;
37
45
  /** The first reference for each comment id, in document order. */
38
46
  export declare function commentReferencesIn(doc: PMNode): ReadonlyMap<string, CommentReferenceData>;