@docx-editor.dev/editor-api 2.20.0 → 2.21.1

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 (3) hide show
  1. package/OFFICE_JS_GUIDE.md +45 -98
  2. package/README.md +44 -89
  3. package/package.json +2 -2
package/OFFICE_JS_GUIDE.md CHANGED
@@ -1,12 +1,10 @@
1
1
  # Office.js patterns for server agents
2
2
 
3
- The public document model follows a documented subset of Word's Office.js API. Host creation,
4
- authentication, collaboration transport, and job lifetime belong outside that model.
3
+ The public document model follows a documented subset of Word's Office.js API. Host creation, authentication, collaboration transport, and job lifetime belong outside that model.
5
4
 
6
5
  ## A complete server example
7
6
 
8
- This function returns a DOCX containing one pending replacement. Supply the agent's author name.
9
- The `finally` block disposes the runtime after the job.
7
+ This function returns a DOCX containing one pending replacement. Supply the agent's author name. The `finally` block disposes the runtime after the job.
10
8
 
11
9
  ```ts
12
10
  import { DocxEditor } from '@docx-editor.dev/editor-api';
@@ -39,14 +37,11 @@ export async function redlineQuote(
39
37
  }
40
38
  ```
41
39
 
42
- The same `run()` block works on `DocxEditor.createCollaborative(...)`. Its commits reach connected
43
- peers through the collaboration session. See the [complete Hocuspocus worker](https://github.com/eigenpal/docx-editor/blob/main/examples/server-agent-review/README.md#copyable-server-integration)
44
- for joining a room, waiting for outbound synchronization, and cleanup.
40
+ The same `run()` block works on `DocxEditor.createCollaborative(...)`. Its commits reach connected peers through the collaboration session. See the [complete Hocuspocus worker](https://github.com/eigenpal/docx-editor/blob/main/examples/server-agent-review/README.md#copyable-server-integration) for joining a room, waiting for outbound synchronization, and cleanup.
45
41
 
46
42
  ## Load deliberately and batch reads
47
43
 
48
- Only load properties you will read. Navigation properties and property assignments do not need a preceding load.
49
- Use `load('items')` before iterating a collection. Queue member loads together, then sync once:
44
+ Only load properties you will read. Navigation properties and property assignments do not need a preceding load. Use `load('items')` before iterating a collection. Queue member loads together, then sync once:
50
45
 
51
46
  ```ts
52
47
  const snapshot = await runtime.run(async (context) => {
@@ -61,30 +56,17 @@ const snapshot = await runtime.run(async (context) => {
61
56
  });
62
57
  ```
63
58
 
64
- This follows Microsoft's [split-loop and correlated-objects guidance](https://learn.microsoft.com/en-us/office/dev/add-ins/concepts/correlated-objects-pattern).
65
- Bound model input and member-property loads. The collection's `items` load still enumerates its members;
66
- slicing the array does not paginate the collection on the server.
59
+ This follows Microsoft's [split-loop and correlated-objects guidance](https://learn.microsoft.com/en-us/office/dev/add-ins/concepts/correlated-objects-pattern). Bound model input and member-property loads. The collection's `items` load still enumerates its members; slicing the array does not paginate the collection on the server.
67
60
 
68
- Supported read-derived proxies can share one `sync()` with their edits. For example,
69
- `body.getRange().insertText(text, 'Replace')` and `table.getCell(0, 0).value = text`
70
- resolve their reads before one atomic write transaction. This can use extra read-only
71
- transport calls. Every phase uses the same revision; concurrent changes cause `StaleDocument`.
61
+ Supported read-derived proxies can share one `sync()` with their edits. For example, `body.getRange().insertText(text, 'Replace')` and `table.getCell(0, 0).value = text` resolve their reads before one atomic write transaction. This can use extra read-only transport calls. Every phase uses the same revision; concurrent changes cause `StaleDocument`.
72
62
 
73
- Proxies returned by insertions require a completed `sync()` before dependent operations.
74
- Do not configure a newly inserted table, image, list, or text range before that sync.
75
- If a prerequisite fails, the runtime commits no queued writes. Completed prerequisite
76
- reads can remain loaded after a later command fails.
63
+ Proxies returned by insertions require a completed `sync()` before dependent operations. Do not configure a newly inserted table, image, list, or text range before that sync. If a prerequisite fails, the runtime commits no queued writes. Completed prerequisite reads can remain loaded after a later command fails.
77
64
 
78
65
  ## Preserve Office.js enum property types
79
66
 
80
- Like Office.js, `Document.changeTrackingMode` and `PageSetup.orientation` use unions
81
- of the enum and its string literals for both reads and writes. Enum constants and
82
- the corresponding string literals are accepted by the type system. This matches
83
- Microsoft's [change-tracking declaration](https://learn.microsoft.com/en-us/javascript/api/word/word.document#word-word-document-changetrackingmode-member)
84
- and [page-orientation declaration](https://learn.microsoft.com/en-us/javascript/api/word/word.pagesetup#word-word-pagesetup-orientation-member).
67
+ Like Office.js, `Document.changeTrackingMode` and `PageSetup.orientation` use unions of the enum and its string literals for both reads and writes. Enum constants and the corresponding string literals are accepted by the type system. This matches Microsoft's [change-tracking declaration](https://learn.microsoft.com/en-us/javascript/api/word/word.document#word-word-document-changetrackingmode-member) and [page-orientation declaration](https://learn.microsoft.com/en-us/javascript/api/word/word.pagesetup#word-word-pagesetup-orientation-member).
85
68
 
86
- Let TypeScript infer a property's type, or use an indexed-access type when saving
87
- its value. An enum-only annotation is narrower than the Office.js property type:
69
+ Let TypeScript infer a property's type, or use an indexed-access type when saving its value. An enum-only annotation is narrower than the Office.js property type:
88
70
 
89
71
  ```ts
90
72
  import { ChangeTrackingMode, type Document } from '@docx-editor.dev/editor-api';
@@ -98,92 +80,57 @@ const mode = await runtime.run(async (context) => {
98
80
  const trackingMine = mode === ChangeTrackingMode.trackMineOnly;
99
81
  ```
100
82
 
101
- For orientation, use `PageSetup['orientation']` in the same way after loading and
102
- syncing that property. Type compatibility does not imply support for every enum
103
- value: `TrackAll` fails with `NotSupported` at `sync()`.
83
+ For orientation, use `PageSetup['orientation']` in the same way after loading and syncing that property. Type compatibility does not imply support for every enum value: `TrackAll` fails with `NotSupported` at `sync()`.
104
84
 
105
85
  ## Give each sync a purpose
106
86
 
107
- A sync either supplies data for the next decision or commits a complete edit. Batch independent reads and writes.
108
- For progressive agent review, one completed suggestion per sync is intentional: peers see each suggestion as it is ready.
109
- For independent edits in different paragraphs, multiple edits can share one sync and one transaction.
110
- Edits that claim the same paragraph can conflict; reconsider their anchors between commits.
87
+ A sync either supplies data for the next decision or commits a complete edit. Batch independent reads and writes. For progressive agent review, one completed suggestion per sync is intentional: peers see each suggestion as it is ready. For independent edits in different paragraphs, multiple edits can share one sync and one transaction. Edits that claim the same paragraph can conflict; reconsider their anchors between commits.
111
88
 
112
- Always await sync. Do not replace sequential syncs with `Promise.all()` or `forEach(async ...)`.
113
- Use an explicit final sync when writes remain queued. Do not add an empty sync after a completed read-only batch.
114
- These conventions follow Microsoft's [application-specific API model](https://learn.microsoft.com/en-us/office/dev/add-ins/develop/application-specific-api-model).
89
+ Always await sync. Do not replace sequential syncs with `Promise.all()` or `forEach(async ...)`. Use an explicit final sync when writes remain queued. Do not add an empty sync after a completed read-only batch. These conventions follow Microsoft's [application-specific API model](https://learn.microsoft.com/en-us/office/dev/add-ins/develop/application-specific-api-model).
115
90
 
116
91
  ## Keep proxy lifetimes clear
117
92
 
118
- Keep document proxies within their `runtime.run()` callback. Return plain text or structured snapshots to the model,
119
- not `Range` or `Paragraph` objects. Do not retain a proxy in a job record or reuse it after its run finishes.
120
- Explicit tracked-object adoption exists for advanced cases; fresh reads are simpler for background workers.
93
+ Keep document proxies within their `runtime.run()` callback. Return plain text or structured snapshots to the model, not `Range` or `Paragraph` objects. Do not retain a proxy in a job record or reuse it after its run finishes. Explicit tracked-object adoption exists for advanced cases; fresh reads are simpler for background workers.
121
94
 
122
- If model generation happens inside a run, commit against the revision that run read. If it happens outside,
123
- keep a validated snapshot and re-anchor in a new run. The example's tool adapter checks both the paragraph snapshot
124
- and document digest. On `StaleDocument`, read again and reconsider the proposal. Recheck the target before retrying.
95
+ If model generation happens inside a run, commit against the revision that run read. If it happens outside, keep a validated snapshot and re-anchor in a new run. The example's tool adapter checks both the paragraph snapshot and document digest. On `StaleDocument`, read again and reconsider the proposal. Recheck the target before retrying.
125
96
 
126
97
  ## Use errors to recover deliberately
127
98
 
128
- Use `isDocxEditorError(error)` and branch on `error.code`. `error.target` identifies the failing public member.
129
- Do not parse message strings. A failed sync does not apply its queued document edits or tracking-mode changes.
130
- Earlier successful syncs remain committed. Failed batches are discarded and are never automatically replayed.
99
+ Use `isDocxEditorError(error)` and branch on `error.code`. `error.target` identifies the failing public member. Do not parse message strings. A failed sync does not apply its queued document edits or tracking-mode changes. Earlier successful syncs remain committed. Failed batches are discarded and are never automatically replayed.
131
100
 
132
- | Code | Next action |
133
- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
134
- | `PropertyNotLoaded` | Load the named property and await sync before reading it. |
135
- | `InvalidObjectPath` | Sync before using a newly returned proxy, or acquire a fresh proxy in a new run. |
136
- | `StaleDocument` | Re-read, re-anchor, and reconsider the model proposal. |
137
- | `ConflictingChanges` | Separate edits that claim the same paragraph and reconsider anchors between commits. |
138
- | `NotSupported` | Check the host, tracking mode, author, and operation against the subset below. |
139
- | `NotImplemented` | Check the documented subset, including pending-revision boundaries. Reconsider the target; do not disable tracking. |
140
- | `InvalidArgument` | Validate the argument and consult the member's JSDoc. |
101
+ | Code | Next action |
102
+ | --- | --- |
103
+ | `PropertyNotLoaded` | Load the named property and await sync before reading it. |
104
+ | `InvalidObjectPath` | Sync before using a newly returned proxy, or acquire a fresh proxy in a new run. |
105
+ | `StaleDocument` | Re-read, re-anchor, and reconsider the model proposal. |
106
+ | `ConflictingChanges` | Separate edits that claim the same paragraph and reconsider anchors between commits. |
107
+ | `NotSupported` | Check the host, tracking mode, author, and operation against the [tracking subset](#tracking-subset). |
108
+ | `NotImplemented` | Check the documented subset, including pending-revision boundaries. Reconsider the target; do not disable tracking. |
109
+ | `InvalidArgument` | Validate the argument and consult the member's JSDoc. |
141
110
 
142
111
  ## Tracking subset
143
112
 
144
- | Intent | Office.js-compatible API |
145
- | ---------------------------------- | ---------------------------------------------------------------------- |
146
- | Track this agent's text edits | `context.document.changeTrackingMode = 'TrackMineOnly'` |
147
- | Insert before or after a range | `range.insertText(text, 'Before')` or `'After'` |
148
- | Replace a range | `range.insertText(text, 'Replace')` |
149
- | Delete range content | `range.delete()` or `range.clear()` |
150
- | Read the current mode | `document.load('changeTrackingMode')`, then sync and read the property |
151
- | Make an intentional permanent edit | Explicitly set `changeTrackingMode = 'Off'` |
152
-
153
- `Off` is the initial runtime mode. Browser tracked writes require the review module; this property does not change the editor UI mode. `TrackMineOnly` needs a configured author and persists for that host session.
154
- It does not change peers' editing modes or persist a document-wide policy. `TrackAll` fails with `NotSupported`. Browser UI modes remain controlled by the editor host.
155
- Tracked edits support inline text in one paragraph, including table cells.
156
- The runtime rejects targets that touch pending revisions.
157
- The runtime rejects tracked deletion or replacement of simple fields containing nested fields or other result containers. Direct result runs remain supported.
158
- The runtime rejects structural and formatting edits while tracking changes. Comments and revision decisions remain available.
159
- Never silently fall back to `Off` when an edit cannot be tracked.
160
-
161
- Standard `insertText('', 'Replace')` means deletion, and an empty insertion is a no-op. Agent tools should require
162
- nonempty insertion/replacement text and expose deletion as an explicit model decision. The shipped worker does this.
163
- The [compatibility manifest](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/compat/manifest.json) records measured members and behavioral differences.
113
+ | Intent | Office.js-compatible API |
114
+ | --- | --- |
115
+ | Track this agent's text edits | `context.document.changeTrackingMode = 'TrackMineOnly'` |
116
+ | Insert before or after a range | `range.insertText(text, 'Before')` or `'After'` |
117
+ | Replace a range | `range.insertText(text, 'Replace')` |
118
+ | Delete range content | `range.delete()` or `range.clear()` |
119
+ | Read the current mode | `document.load('changeTrackingMode')`, then sync and read the property |
120
+ | Make an intentional permanent edit | Explicitly set `changeTrackingMode = 'Off'` |
121
+
122
+ `Off` is the initial runtime mode. Browser tracked writes require the review module; this property does not change the editor UI mode. `TrackMineOnly` needs a configured author and persists for that host session. It does not change peers' editing modes or persist a document-wide policy. `TrackAll` fails with `NotSupported`. Browser UI modes remain controlled by the editor host. Tracked edits support inline text in one paragraph, including table cells. The runtime rejects targets that touch pending revisions. The runtime rejects tracked deletion or replacement of simple fields containing nested fields or other result containers. Direct result runs remain supported. The runtime rejects structural and formatting edits while tracking changes. Comments and revision decisions remain available. Never silently fall back to `Off` when an edit cannot be tracked.
123
+
124
+ Standard `insertText('', 'Replace')` means deletion, and an empty insertion is a no-op. Agent tools should require nonempty insertion/replacement text and expose deletion as an explicit model decision. The shipped worker does this. The [compatibility manifest](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/compat/manifest.json) records measured members and behavioral differences.
164
125
 
165
126
  ## Pictures and page fields
166
127
 
167
- Insert PNG or JPEG images with `range.insertInlinePictureFromBase64(data, 'After')`.
168
- Sync before setting properties on the returned picture. Width and height use points.
169
- New pictures lock the aspect ratio. Set `lockAspectRatio = false` before setting independent dimensions.
170
- Set `altTextDescription` to describe the image. Deletion preserves shared media relationships.
171
-
172
- Insert a page field with `range.insertField('After', 'Page')` or `'NumPages'`.
173
- Sync before using the returned field. `field.code = 'NUMPAGES'` changes its instruction;
174
- `field.updateResult()` computes and stores its result. These calls use separate syncs.
175
- Field updates can share a sync with other field updates. They cannot share a sync with layout-changing writes.
176
-
177
- Headless field calculation requires an explicit `pagination.measurer` when creating the server runtime.
178
- Use measurements from the document's fonts. Browser runtimes use the editor's measured layout.
179
- Without pagination, `updateResult()` fails with `NotSupported`.
180
- Other field instructions remain inert. The authoring subset refuses unsupported field codes and formatting switches.
181
-
182
- Character formatting also supports underline, strikethrough, exact Word-palette highlighting, subscript, and superscript.
183
- `font.underline = 'None'` removes an underline. Setting one script mode to `true` clears the other mode.
184
- The highlight setter keeps Office's pinned `string` type, although Microsoft documents runtime `null` for clearing.
185
- The runtime accepts this clearing value. The runtime rejects unsupported highlight colors.
186
-
187
- The workflow tests cover both hosts and save/reopen:
188
- `model-font-editing.test.ts`, `model-pictures.test.ts`, `model-fields.test.ts`, and `model-picture-field-parity.test.ts`.
189
- The final test includes primary footer creation and a saved `NUMPAGES` result.
128
+ Insert PNG or JPEG images with `range.insertInlinePictureFromBase64(data, 'After')`. Sync before setting properties on the returned picture. Width and height use points. New pictures lock the aspect ratio. Set `lockAspectRatio = false` before setting independent dimensions. Set `altTextDescription` to describe the image. Deletion preserves shared media relationships.
129
+
130
+ Insert a page field with `range.insertField('After', 'Page')` or `'NumPages'`. Sync before using the returned field. `field.code = 'NUMPAGES'` changes its instruction; `field.updateResult()` computes and stores its result. These calls use separate syncs. Field updates can share a sync with other field updates. They cannot share a sync with layout-changing writes.
131
+
132
+ Headless field calculation requires an explicit `pagination.measurer` when creating the server runtime. Use measurements from the document's fonts. Browser runtimes use the editor's measured layout. Without pagination, `updateResult()` fails with `NotSupported`. Other field instructions remain inert. The authoring subset refuses unsupported field codes and formatting switches.
133
+
134
+ Character formatting also supports underline, strikethrough, exact Word-palette highlighting, subscript, and superscript. `font.underline = 'None'` removes an underline. Setting one script mode to `true` clears the other mode. The highlight setter keeps Office's pinned `string` type, although Microsoft documents runtime `null` for clearing. The runtime accepts this clearing value. The runtime rejects unsupported highlight colors.
135
+
136
+ The workflow tests cover both hosts and save/reopen: `model-font-editing.test.ts`, `model-pictures.test.ts`, `model-fields.test.ts`, and `model-picture-field-parity.test.ts`. The final test includes primary footer creation and a saved `NUMPAGES` result.
package/README.md CHANGED
@@ -7,20 +7,16 @@
7
7
  <p align="center">
8
8
  <a href="https://www.npmjs.com/package/@docx-editor.dev/editor-api"><img src="https://img.shields.io/npm/v/@docx-editor.dev/editor-api.svg?style=flat-square&color=3B5BDB" alt="npm version" /></a>
9
9
  <a href="https://www.npmjs.com/package/@docx-editor.dev/editor-api"><img src="https://img.shields.io/npm/dm/@docx-editor.dev/editor-api.svg?style=flat-square&color=3B5BDB" alt="npm downloads" /></a>
10
- <a href="https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/LICENSE.md"><img src="https://img.shields.io/badge/license-EigenPal_Pro_Evaluation_1.0-blue.svg?style=flat-square&color=3B5BDB" alt="license" /></a>
10
+ <a href="https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/LICENSE.md"><img src="https://img.shields.io/badge/license-EigenPal_Pro_License-blue.svg?style=flat-square&color=3B5BDB" alt="EigenPal Pro License" /></a>
11
11
  <a href="https://docx-editor.dev/editor"><img src="https://img.shields.io/badge/Live_Demo-3B5BDB?style=flat-square&logo=vercel&logoColor=white" alt="Demo" /></a>
12
12
  <a href="https://www.docx-editor.dev/docs"><img src="https://img.shields.io/badge/Docs-3B5BDB?style=flat-square&logo=readthedocs&logoColor=white" alt="Documentation" /></a>
13
13
  </p>
14
14
 
15
15
  # @docx-editor.dev/editor-api
16
16
 
17
- `@docx-editor.dev/editor-api` edits DOCX files through a supported subset of Word's
18
- JavaScript object model, including paragraphs, ranges, comments, and revisions.
19
- Use `load()` to queue reads and `sync()` to apply each batch atomically.
17
+ `@docx-editor.dev/editor-api` edits DOCX files through a supported subset of Word's JavaScript object model, including paragraphs, ranges, comments, and revisions. Use `load()` to queue reads and `sync()` to apply each batch atomically.
20
18
 
21
- Run the API on a server over DOCX bytes or in the browser against an open editor.
22
- See [Office.js compatibility](https://www.docx-editor.dev/docs/2.x/editor-api/office-js-api)
23
- for supported members and differences from Word.
19
+ Run the API on a server over DOCX bytes or in the browser against an open editor. See [Office.js compatibility](https://www.docx-editor.dev/docs/2.x/editor-api/office-js-api) for supported members and differences from Word.
24
20
 
25
21
  ```bash
26
22
  npm install @docx-editor.dev/editor-api @docx-editor.dev/core
@@ -30,23 +26,22 @@ Server use requires Node.js `^20.16.0 || >=22.3.0`.
30
26
 
31
27
  ## Guides by task
32
28
 
33
- Start with [Runtime and setup](https://www.docx-editor.dev/docs/2.x/editor-api/runtime) and
34
- [Batching, loading, and errors](https://www.docx-editor.dev/docs/2.x/editor-api/batching-and-errors).
35
-
36
- | Task | Guide |
37
- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
38
- | Read, insert, replace, or remove text | [Text and ranges](https://www.docx-editor.dev/docs/2.x/editor-api/text-and-ranges) |
39
- | Find matches, split paragraphs, or use bookmarks | [Search and navigation](https://www.docx-editor.dev/docs/2.x/editor-api/search-and-navigation) |
40
- | Set fonts, paragraph properties, styles, or links | [Formatting and styles](https://www.docx-editor.dev/docs/2.x/editor-api/formatting) |
41
- | Create and configure lists | [Lists and numbering](https://www.docx-editor.dev/docs/2.x/editor-api/lists) |
42
- | Work with table values, rows, columns, and cells | [Tables and cells](https://www.docx-editor.dev/docs/2.x/editor-api/tables) |
43
- | Insert and resize images | [Inline pictures](https://www.docx-editor.dev/docs/2.x/editor-api/pictures) |
44
- | Calculate PAGE and NUMPAGES | [Fields and pagination](https://www.docx-editor.dev/docs/2.x/editor-api/fields) |
45
- | Set page geometry and edit headers, footers, or notes | [Page layout and stories](https://www.docx-editor.dev/docs/2.x/editor-api/page-layout-and-stories) |
46
- | Fill template controls and edit their metadata | [Content controls](https://www.docx-editor.dev/docs/2.x/editor-api/content-controls) |
47
- | Discuss content and manage threads | [Comments](https://www.docx-editor.dev/docs/2.x/editor-api/comments) |
48
- | Create, inspect, accept, or reject tracked changes | [Tracked changes](https://www.docx-editor.dev/docs/2.x/editor-api/revisions) |
49
- | Find any public object, method, property, or support type | [API member directory](https://www.docx-editor.dev/docs/2.x/editor-api/reference) |
29
+ Start with [Runtime and setup](https://www.docx-editor.dev/docs/2.x/editor-api/runtime) and [Batching, loading, and errors](https://www.docx-editor.dev/docs/2.x/editor-api/batching-and-errors).
30
+
31
+ | Task | Guide |
32
+ | --- | --- |
33
+ | Read, insert, replace, or remove text | [Text and ranges](https://www.docx-editor.dev/docs/2.x/editor-api/text-and-ranges) |
34
+ | Find matches, split paragraphs, or use bookmarks | [Search and navigation](https://www.docx-editor.dev/docs/2.x/editor-api/search-and-navigation) |
35
+ | Set fonts, paragraph properties, styles, or links | [Formatting and styles](https://www.docx-editor.dev/docs/2.x/editor-api/formatting) |
36
+ | Create and configure lists | [Lists and numbering](https://www.docx-editor.dev/docs/2.x/editor-api/lists) |
37
+ | Work with table values, rows, columns, and cells | [Tables and cells](https://www.docx-editor.dev/docs/2.x/editor-api/tables) |
38
+ | Insert and resize images | [Inline pictures](https://www.docx-editor.dev/docs/2.x/editor-api/pictures) |
39
+ | Calculate PAGE and NUMPAGES | [Fields and pagination](https://www.docx-editor.dev/docs/2.x/editor-api/fields) |
40
+ | Set page geometry and edit headers, footers, or notes | [Page layout and stories](https://www.docx-editor.dev/docs/2.x/editor-api/page-layout-and-stories) |
41
+ | Fill template controls and edit their metadata | [Content controls](https://www.docx-editor.dev/docs/2.x/editor-api/content-controls) |
42
+ | Discuss content and manage threads | [Comments](https://www.docx-editor.dev/docs/2.x/editor-api/comments) |
43
+ | Create, inspect, accept, or reject tracked changes | [Tracked changes](https://www.docx-editor.dev/docs/2.x/editor-api/revisions) |
44
+ | Find any public object, method, property, or support type | [API member directory](https://www.docx-editor.dev/docs/2.x/editor-api/reference) |
50
45
 
51
46
  ## On a server
52
47
 
@@ -66,7 +61,7 @@ try {
66
61
  await context.sync(); // Read the matching ranges.
67
62
 
68
63
  for (const match of matches.items) match.insertText('$500k', 'Replace');
69
- await context.sync(); // one atomic batch: all of the writes, or none
64
+ await context.sync(); // Commit all writes in one atomic batch.
70
65
  return matches.items.length;
71
66
  });
72
67
  console.log(`replaced ${filled}`);
@@ -76,18 +71,13 @@ try {
76
71
  }
77
72
  ```
78
73
 
79
- `createServer` finishes its bounded parse before its promise resolves and does not retain the input
80
- `Uint8Array`; you may reuse or transfer that buffer afterward. Every `save()` returns a fresh,
81
- caller-owned `Uint8Array`, so transferring or mutating one result does not affect the runtime or a
82
- later save. Detached edits remain detached until your application explicitly loads the returned
83
- bytes into a live editor.
74
+ `createServer` finishes its bounded parse before its promise resolves and does not retain the input `Uint8Array`; you may reuse or transfer that buffer afterward. Every `save()` returns a fresh, caller-owned `Uint8Array`, so transferring or mutating one result does not affect the runtime or a later save. Detached edits remain detached until your application explicitly loads the returned bytes into a live editor.
84
75
 
85
76
  ## Create tracked changes on a server
86
77
 
87
78
  Start with the [Office.js developer guide](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/OFFICE_JS_GUIDE.md) for a complete server example and batching conventions.
88
79
 
89
- Set `document.changeTrackingMode = 'TrackMineOnly'`, then use standard Word editing methods.
90
- Supply the agent's `author` when opening the server or collaborative runtime:
80
+ Set `document.changeTrackingMode = 'TrackMineOnly'`, then use standard Word editing methods. Supply the agent's `author` when opening the server or collaborative runtime:
91
81
 
92
82
  ```ts
93
83
  await runtime.run(async (context) => {
@@ -104,27 +94,15 @@ await runtime.run(async (context) => {
104
94
  });
105
95
  ```
106
96
 
107
- Use `range.insertText(text, 'Before' | 'After')` for insertions, and `range.delete()` or
108
- `range.clear()` for deletions. `insertText()` returns the inserted range. Mode assignments
109
- and edits commit together at `sync()`; failed batches preserve the previous mode and document.
110
- Load `document.changeTrackingMode` before reading it. `Off` is the initial mode.
97
+ Use `range.insertText(text, 'Before' | 'After')` for insertions, and `range.delete()` or `range.clear()` for deletions. `insertText()` returns the inserted range. Mode assignments and edits commit together at `sync()`; failed batches preserve the previous mode and document. Load `document.changeTrackingMode` before reading it. `Off` is the initial mode.
111
98
 
112
- This is a supported Office.js subset. `TrackMineOnly` applies to this server host and persists
113
- across its `run()` calls. It does not change peers' tracking settings or save a document-wide
114
- tracking policy. `TrackAll` fails with `NotSupported`. Browser tracked writes require the Pro review module;
115
- the runtime setting does not change the editor UI mode.
116
- Tracked text edits support one paragraph, including table-cell text. The runtime rejects targets touching
117
- pending revisions, including text inside a row with a pending insertion or deletion.
118
- The runtime also rejects structural and formatting changes while tracking. Comments and
119
- revision decisions remain available. Set `Off` explicitly when permanent edits are intended.
99
+ This is a supported Office.js subset. `TrackMineOnly` applies to this server host and persists across its `run()` calls. It does not change peers' tracking settings or save a document-wide tracking policy. `TrackAll` fails with `NotSupported`. Browser tracked writes require the Pro review module; the runtime setting does not change the editor UI mode. Tracked text edits support one paragraph, including table-cell text. The runtime rejects targets touching pending revisions, including text inside a row with a pending insertion or deletion. The runtime also rejects structural and formatting changes while tracking. Comments and revision decisions remain available. Set `Off` explicitly when permanent edits are intended.
120
100
 
121
- See the [server-agent review example](../../examples/server-agent-review/README.md) for Hocuspocus,
122
- stale-read handling, and the review lifecycle.
101
+ See the [server-agent review example](../../examples/server-agent-review/README.md) for Hocuspocus, stale-read handling, and the review lifecycle.
123
102
 
124
103
  ## In the browser
125
104
 
126
- Pass an open core, React, or Vue editor to `createBrowser()`. Edits use the editor's
127
- undo history. Save through the owning editor.
105
+ Pass an open core, React, or Vue editor to `createBrowser()`. Edits use the editor's undo history. Save through the owning editor.
128
106
 
129
107
  ```ts
130
108
  import { DocxEditor } from '@docx-editor.dev/editor-api/browser';
@@ -144,33 +122,19 @@ try {
144
122
  }
145
123
  ```
146
124
 
147
- Use the `/browser` entry for an open editor. Use the root entry on servers to exclude
148
- browser rendering code from the bundle.
125
+ Use the `/browser` entry for an open editor. Use the root entry on servers to exclude browser rendering code from the bundle.
149
126
 
150
- Supply `author` for comments, replies, and tracked edits. Browser review writes also
151
- require the Pro review module and an editable document. Handle errors by `code`.
152
- See [Comments](https://www.docx-editor.dev/docs/2.x/editor-api/comments) and
153
- [Tracked changes](https://www.docx-editor.dev/docs/2.x/editor-api/revisions) for supported operations.
127
+ Supply `author` for comments, replies, and tracked edits. Browser review writes also require the Pro review module and an editable document. Handle errors by `code`. See [Comments](https://www.docx-editor.dev/docs/2.x/editor-api/comments) and [Tracked changes](https://www.docx-editor.dev/docs/2.x/editor-api/revisions) for supported operations.
154
128
 
155
129
  ## Resolve revisions in a batch
156
130
 
157
- Use `RevisionCollection.resolve('accept')` or `resolve('reject')` to process supported
158
- changes in one story. To select changes, pass revision objects as the second argument.
159
- API batches don't inherit editor filters. Read `result.value` after `context.sync()`
160
- for resolved and skipped decisions and the remaining count.
131
+ Use `RevisionCollection.resolve('accept')` or `resolve('reject')` to process supported changes in one story. To select changes, pass revision objects as the second argument. API batches don't inherit editor filters. Read `result.value` after `context.sync()` for resolved and skipped decisions and the remaining count.
161
132
 
162
- To require every change in the story to resolve, use `acceptAll()` or `rejectAll()`.
163
- These methods fail if any revision is unsupported. See
164
- [Resolve a batch of changes](https://www.docx-editor.dev/docs/2.x/editor-api/revisions#resolve-a-batch-of-changes)
165
- for examples and result handling.
133
+ To require every change in the story to resolve, use `acceptAll()` or `rejectAll()`. These methods fail if any revision is unsupported. See [Resolve a batch of changes](https://www.docx-editor.dev/docs/2.x/editor-api/revisions#resolve-a-batch-of-changes) for examples and result handling.
166
134
 
167
135
  ## Range snapshots
168
136
 
169
- Ranges retain the paragraph offsets where they were found.
170
- They do not follow later text edits inside those paragraphs, even when their proxies are tracked.
171
- After editing a paragraph, search again before acting on another target there.
172
- Use the range returned by `insertText()` after sync to address its inserted text.
173
- See [Text and ranges](https://www.docx-editor.dev/docs/2.x/editor-api/text-and-ranges) for snapshot and same-batch editing limits.
137
+ Ranges retain the paragraph offsets where they were found. They do not follow later text edits inside those paragraphs, even when their proxies are tracked. After editing a paragraph, search again before acting on another target there. Use the range returned by `insertText()` after sync to address its inserted text. See [Text and ranges](https://www.docx-editor.dev/docs/2.x/editor-api/text-and-ranges) for snapshot and same-batch editing limits.
174
138
 
175
139
  ## Programming model
176
140
 
@@ -181,37 +145,29 @@ See [Text and ranges](https://www.docx-editor.dev/docs/2.x/editor-api/text-and-r
181
145
  - Check `isNullObject` after sync when using a null-object accessor.
182
146
  - Check nullable font values and review dates before using them.
183
147
 
184
- See [Batching, loading, and errors](https://www.docx-editor.dev/docs/2.x/editor-api/batching-and-errors)
185
- for transaction limits, proxy lifetimes, and error recovery.
148
+ See [Batching, loading, and errors](https://www.docx-editor.dev/docs/2.x/editor-api/batching-and-errors) for transaction limits, proxy lifetimes, and error recovery.
186
149
 
187
150
  ## Office.js compatibility
188
151
 
189
- The API implements a documented subset of Word's JavaScript object model.
190
- It runs independently of Office and does not require a Microsoft package.
191
- See [Office.js compatibility](https://www.docx-editor.dev/docs/2.x/editor-api/office-js-api)
192
- for supported operations, runtime differences, and compatibility reports.
152
+ The API implements a documented subset of Word's JavaScript object model. It runs independently of Office and does not require a Microsoft package. See [Office.js compatibility](https://www.docx-editor.dev/docs/2.x/editor-api/office-js-api) for supported operations, runtime differences, and compatibility reports.
193
153
 
194
- Server page-field updates require a measurer configured with font resources.
195
- See [Fields and pagination](https://www.docx-editor.dev/docs/2.x/editor-api/fields)
196
- for setup and a runnable report agent.
154
+ Server page-field updates require a measurer configured with font resources. See [Fields and pagination](https://www.docx-editor.dev/docs/2.x/editor-api/fields) for setup and a runnable report agent.
197
155
 
198
- To upgrade from the former reviewer, bridge, MCP, or chat APIs, see
199
- [Migration](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/MIGRATION.md).
156
+ To upgrade from the former reviewer, bridge, MCP, or chat APIs, see [Migration](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/MIGRATION.md).
200
157
 
201
158
  ## Packages
202
159
 
203
- | Package | Description |
204
- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
205
- | [`@docx-editor.dev/react`](https://www.npmjs.com/package/@docx-editor.dev/react) | React adapter. `<DocxEditor>`, provider primitives, hooks, and compound chrome. |
206
- | [`@docx-editor.dev/core`](https://www.npmjs.com/package/@docx-editor.dev/core) | Framework-agnostic engine: OOXML read/write, canonical document tree, layout, paint. |
207
- | [`@docx-editor.dev/i18n`](https://www.npmjs.com/package/@docx-editor.dev/i18n) | Shared locale strings and types. |
208
- | [`@docx-editor.dev/pro`](https://www.npmjs.com/package/@docx-editor.dev/pro) | Tracked changes, comments, and custom nodes. |
209
- | [`@docx-editor.dev/editor-api`](https://www.npmjs.com/package/@docx-editor.dev/editor-api) | Office.js-compatible editing API: a batching object model, on a server or against an open editor. |
160
+ | Package | Description |
161
+ | --- | --- |
162
+ | [`@docx-editor.dev/react`](https://www.npmjs.com/package/@docx-editor.dev/react) | React adapter. `<DocxEditor>`, provider primitives, hooks, and compound chrome. |
163
+ | [`@docx-editor.dev/core`](https://www.npmjs.com/package/@docx-editor.dev/core) | Framework-agnostic engine: OOXML read/write, canonical document tree, layout, paint. |
164
+ | [`@docx-editor.dev/i18n`](https://www.npmjs.com/package/@docx-editor.dev/i18n) | Shared locale strings and types. |
165
+ | [`@docx-editor.dev/pro`](https://www.npmjs.com/package/@docx-editor.dev/pro) | Tracked changes, comments, and custom nodes. |
166
+ | [`@docx-editor.dev/editor-api`](https://www.npmjs.com/package/@docx-editor.dev/editor-api) | Supported Office.js subset for document editing on a server or in an open editor. |
210
167
 
211
168
  ## License
212
169
 
213
- This package uses the [EigenPal Pro License](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/LICENSE.md).
214
- See [pricing](https://www.docx-editor.dev/pricing) for license and support options.
170
+ This package uses the [EigenPal Pro License](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/LICENSE.md). See [pricing](https://www.docx-editor.dev/pricing) for license and support options.
215
171
 
216
172
  ## Contributing
217
173
 
@@ -219,5 +175,4 @@ Contributions welcome. See [CONTRIBUTING.md](https://github.com/eigenpal/docx-ed
219
175
 
220
176
  ## Commercial support
221
177
 
222
- > [!TIP]
223
- > Questions or custom features? Email **[docx-editor@eigenpal.com](mailto:docx-editor@eigenpal.com)**.
178
+ > [!TIP] Questions or custom features? Email **[docx-editor@eigenpal.com](mailto:docx-editor@eigenpal.com)**.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@docx-editor.dev/editor-api",
3
- "version": "2.20.0",
3
+ "version": "2.21.1",
4
4
  "description": "Document automation for DOCX: a batching object model that drives a document from a server or from an editor already open in a page",
5
5
  "sideEffects": false,
6
6
  "engines": {
@@ -82,6 +82,6 @@
82
82
  "access": "public"
83
83
  },
84
84
  "peerDependencies": {
85
- "@docx-editor.dev/core": "~2.20.0"
85
+ "@docx-editor.dev/core": "~2.21.0"
86
86
  }
87
87
  }