@portone/docx-editor 0.6.4 → 0.6.6

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 (80) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/CONTRIBUTING.md +4 -4
  3. package/dist/DocxEditor.d.ts +11 -0
  4. package/dist/DocxEditor.js +7 -3
  5. package/dist/core.d.ts +7 -0
  6. package/dist/core.js +2 -0
  7. package/dist/docx/commentOnlyChange.d.ts +4 -4
  8. package/dist/docx/comments/constants.d.ts +7 -0
  9. package/dist/docx/comments/constants.js +13 -1
  10. package/dist/docx/comments/dates.d.ts +22 -0
  11. package/dist/docx/comments/dates.js +102 -0
  12. package/dist/docx/comments/durable.d.ts +22 -0
  13. package/dist/docx/comments/durable.js +138 -0
  14. package/dist/docx/comments/grammar.d.ts +10 -1
  15. package/dist/docx/comments/grammar.js +49 -2
  16. package/dist/docx/comments/model.d.ts +10 -2
  17. package/dist/docx/comments/model.js +38 -8
  18. package/dist/docx/comments/parts.d.ts +53 -7
  19. package/dist/docx/comments/parts.js +163 -20
  20. package/dist/docx/comments/people.d.ts +1 -1
  21. package/dist/docx/comments/people.js +5 -15
  22. package/dist/docx/comments/reading.d.ts +26 -0
  23. package/dist/docx/comments/reading.js +109 -49
  24. package/dist/docx/comments/writing.d.ts +2 -7
  25. package/dist/docx/comments/writing.js +30 -43
  26. package/dist/docx/compareDocx.d.ts +154 -0
  27. package/dist/docx/compareDocx.js +218 -0
  28. package/dist/docx/importParagraph.js +5 -3
  29. package/dist/docx/invariants.js +19 -6
  30. package/dist/docx/packageParts.d.ts +2 -0
  31. package/dist/docx/packageParts.js +5 -1
  32. package/dist/docx/partPlan.d.ts +12 -0
  33. package/dist/docx/partPlan.js +19 -1
  34. package/dist/docx/protectionPolicy.d.ts +33 -5
  35. package/dist/docx/protectionPolicy.js +93 -47
  36. package/dist/docx/sequenceDiff.d.ts +56 -0
  37. package/dist/docx/sequenceDiff.js +252 -0
  38. package/dist/docx/storyProjection.d.ts +2 -0
  39. package/dist/docx/storyProjection.js +10 -9
  40. package/dist/docx/textDiff.d.ts +24 -0
  41. package/dist/docx/textDiff.js +38 -0
  42. package/dist/editor/commands/comments/editing.js +56 -20
  43. package/dist/editor/commands/comments/model.d.ts +3 -1
  44. package/dist/editor/createEditor.d.ts +4 -1
  45. package/dist/editor/createEditor.js +14 -2
  46. package/dist/editor/editRefusal.d.ts +68 -0
  47. package/dist/editor/editRefusal.js +177 -0
  48. package/dist/editor/editorDocument.d.ts +4 -0
  49. package/dist/editor/editorDocument.js +10 -0
  50. package/dist/editor/plugins/commentDecorations.js +6 -2
  51. package/dist/editor/plugins/controlContents.d.ts +24 -0
  52. package/dist/editor/plugins/controlContents.js +260 -0
  53. package/dist/editor/plugins/controlLifecycle.js +3 -5
  54. package/dist/editor/stories/storyState.js +2 -0
  55. package/dist/index.d.ts +2 -0
  56. package/dist/ooxml/errors.d.ts +1 -1
  57. package/dist/ooxml/names.d.ts +2 -0
  58. package/dist/ooxml/names.js +2 -0
  59. package/dist/ooxml/partSplice.d.ts +13 -3
  60. package/dist/ooxml/partSplice.js +45 -18
  61. package/dist/schema/attrRoles.js +3 -1
  62. package/dist/schema/controlAttrs.d.ts +6 -0
  63. package/dist/schema/controlAttrs.js +4 -0
  64. package/dist/schema/docxSchema.js +10 -3
  65. package/dist/schema/guards.d.ts +8 -2
  66. package/dist/schema/guards.js +14 -8
  67. package/dist/schema/locks.d.ts +25 -2
  68. package/dist/schema/locks.js +67 -11
  69. package/dist/schema/protection.js +2 -1
  70. package/dist/styles/classNames.d.ts +2 -0
  71. package/dist/styles/classNames.js +2 -0
  72. package/dist/styles.css +65 -14
  73. package/dist/ui/CommentsPanel.js +8 -13
  74. package/dist/ui/MenuNote.d.ts +12 -0
  75. package/dist/ui/MenuNote.js +14 -0
  76. package/dist/ui/TableMenu.js +38 -19
  77. package/dist/ui/TextMenu.js +31 -25
  78. package/dist/ui/comments/commentDate.d.ts +7 -0
  79. package/dist/ui/comments/commentDate.js +17 -0
  80. package/package.json +7 -7
package/CHANGELOG.md CHANGED
@@ -1,5 +1,52 @@
1
1
  # @portone/docx-editor
2
2
 
3
+ ## 0.6.6
4
+
5
+ ### Patch Changes
6
+
7
+ - [#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.
8
+ `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.
9
+ 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.
10
+ 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.
11
+ `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.
12
+ 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.
13
+
14
+ - [#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.
15
+ `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.
16
+
17
+ ## 0.6.5
18
+
19
+ ### Patch Changes
20
+
21
+ - [#182](https://github.com/portone-io/docx-editor/pull/182) [`13e5f9f`](https://github.com/portone-io/docx-editor/commit/13e5f9f42d27c047144f3fb22c00b2ac26dae168) Thanks [@Deea222](https://github.com/Deea222)! - Tell the application when an edit is refused, and let it theme locked content.
22
+
23
+ `DocxEditor` takes `onEditRefused`, called when typing, deleting, pasting,
24
+ dropping or formatting in the document body is turned down. It is handed an
25
+ `EditRefusal`: the rule that refused the edit (`lock`, `protection`,
26
+ `controlEdge`, `preserved` or `section`), what the edit would have done, and,
27
+ for a lock, the controls it reached with their `tag`, `alias`, `id`, lock and
28
+ level. Before this a refused keystroke did nothing at all and said nothing.
29
+
30
+ The right-click menus now say "Locked content can't be edited." when the
31
+ selection, or the table under it, holds locked content, which is why their
32
+ editing entries stand disabled.
33
+
34
+ Four custom properties theme how controls are drawn:
35
+ `--docx-editor-locked-background` and `--docx-editor-locked-outline` for locked
36
+ content, which keeps its yellow tint and orange outline by default, and
37
+ `--docx-editor-control-background` and `--docx-editor-control-outline` for a
38
+ content control that stays editable, which is not marked by default.
39
+
40
+ The yellow now shows over a locked table cell or row whose shading the
41
+ document states as `auto`, which used to hide it, and a cell's own shading
42
+ shows through the tint rather than hiding it.
43
+
44
+ - [#183](https://github.com/portone-io/docx-editor/pull/183) [`2423668`](https://github.com/portone-io/docx-editor/commit/242366886c89e96d633d2bc31312f42aaf37e4fd) Thanks [@Deea222](https://github.com/Deea222)! - Keep an inline content control when everything it holds is written over or deleted.
45
+
46
+ Selecting all of the text inside a content control that stands in a paragraph - a bracketed placeholder a template leaves to be filled in, say - and typing over it used to take the control away: the new text landed beside it as ordinary text, and the tag and id a server looks for when it fills the document in were gone. The same happened with a drag carried past the end of the line, a Shift-click, a triple click, a composition, and a paste. The new text now goes into the control, which keeps its tag, its id, and everything else it states, and what is typed next goes on into it.
47
+
48
+ Deleting everything the control holds now leaves the control in the file with nothing inside it, and text typed right after goes back into it. A control locked against deletion alone (`sdtLocked`) takes all of this, since its contents may be edited; before, deleting or retyping everything it held was refused. A selection that also takes in text outside the control still removes the control with that text, and a control locked against deletion still refuses it.
49
+
3
50
  ## 0.6.4
4
51
 
5
52
  ### 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.
@@ -13,6 +13,7 @@ import { type CSSProperties, type ReactNode } from "react";
13
13
  import { type DocxSource } from "./docx/importDocx";
14
14
  import { type ExportProblem } from "./docx/invariants";
15
15
  import type { CommentAuthor } from "./editor/commands/commentCommands";
16
+ import type { EditRefusal } from "./editor/editRefusal";
16
17
  import { DocxImportError } from "./ooxml/errors";
17
18
  import type { EditableComments } from "./schema/protection";
18
19
  import type { FontFallbacks } from "./styles/fontStack";
@@ -145,6 +146,16 @@ export interface DocxEditorProps {
145
146
  onReady?: (view: EditorView) => void;
146
147
  /** Called every time the editor state changes. This covers cursor and selection moves, not just text edits */
147
148
  onChange?: () => void;
149
+ /**
150
+ * Called when the editor turns down an edit made in the document body: typing, deleting,
151
+ * pasting or dropping into locked content, or anything the `mode` does not take.
152
+ *
153
+ * The editor itself only leaves the document as it was, so this is where an application says
154
+ * why - a toast, a status line - in its own words. It is called once per refused edit, so a key
155
+ * held down calls it repeatedly. A command reporting `false` dispatches nothing and calls
156
+ * nothing.
157
+ */
158
+ onEditRefused?: (refusal: EditRefusal) => void;
148
159
  }
149
160
  /**
150
161
  * `forwardRef` rather than a `ref` prop: React 18 hands a function component no `ref`
@@ -178,7 +178,8 @@ function DocxEditorSurface({
178
178
  className,
179
179
  style,
180
180
  onReady,
181
- onChange
181
+ onChange,
182
+ onEditRefused
182
183
  }, ref) {
183
184
  const { protection, author, editableComments, toolbar, locking } = affordancesOf(mode);
184
185
  const bytes = useDocumentBytes(source);
@@ -209,6 +210,7 @@ function DocxEditorSurface({
209
210
  );
210
211
  const latestOnReady = useLatest(onReady);
211
212
  const latestOnChange = useLatest(onChange);
213
+ const latestOnEditRefused = useLatest(onEditRefused);
212
214
  const selectedZoom = normalizeZoom(zoom ?? uncontrolledZoom);
213
215
  const page = opened?.status === "opened" ? pagePixels(opened.session.geometry) : A4_PAGE_PIXELS;
214
216
  const fitWidth = useFitWidthZoom(rootRef, page.pageWidth);
@@ -237,7 +239,8 @@ function DocxEditorSurface({
237
239
  keptState.current = { of: opened, state };
238
240
  setLive({ view, state });
239
241
  latestOnChange.current?.();
240
- }
242
+ },
243
+ onEditRefused: (refusal) => latestOnEditRefused.current?.(refusal)
241
244
  });
242
245
  viewRef.current = view;
243
246
  keptState.current = { of: opened, state: view.state };
@@ -254,7 +257,8 @@ function DocxEditorSurface({
254
257
  mountedFontFallbacks,
255
258
  mountedPlugins,
256
259
  latestOnReady,
257
- latestOnChange
260
+ latestOnChange,
261
+ latestOnEditRefused
258
262
  ]);
259
263
  const authorId = author?.id ?? null;
260
264
  const mounted = live !== null;
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
  *