@docx-editor.dev/editor-api 2.20.0 → 2.21.0
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.
- package/OFFICE_JS_GUIDE.md +26 -79
- package/README.md +20 -65
- 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,36 +80,23 @@ 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
101
|
| Code | Next action |
|
|
133
102
|
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -150,40 +119,18 @@ Earlier successful syncs remain committed. Failed batches are discarded and are
|
|
|
150
119
|
| Read the current mode | `document.load('changeTrackingMode')`, then sync and read the property |
|
|
151
120
|
| Make an intentional permanent edit | Explicitly set `changeTrackingMode = 'Off'` |
|
|
152
121
|
|
|
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.
|
|
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.
|
|
160
123
|
|
|
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.
|
|
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
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
@@ -14,13 +14,9 @@
|
|
|
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,8 +26,7 @@ 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).
|
|
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).
|
|
35
30
|
|
|
36
31
|
| Task | Guide |
|
|
37
32
|
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
@@ -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,22 +145,15 @@ 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
|
|
|
@@ -210,8 +167,7 @@ To upgrade from the former reviewer, bridge, MCP, or chat APIs, see
|
|
|
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.
|
|
3
|
+
"version": "2.21.0",
|
|
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.
|
|
85
|
+
"@docx-editor.dev/core": "~2.21.0"
|
|
86
86
|
}
|
|
87
87
|
}
|