@docx-editor.dev/editor-api 2.24.0 → 2.25.0

package/OFFICE_JS_GUIDE.md

@@ -62,6 +62,29 @@ Supported read-derived proxies can share one `sync()` with their edits. For exam
 
 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.
 
+## Keep writes within one story
+
+A story is the main body, a header, a footer, or another document text container. One `context.sync()` can write only one story. Writes across stories fail with `ConflictingChanges`. Reads from different stories can share a sync.
+
+If the document has a primary header and footer, resolve both objects before formatting them. Then commit each story's writes separately:
+
+```ts
+await runtime.run(async (context) => {
+  const section = context.document.sections.getFirst();
+  await context.sync();
+  const stories = [section.getHeader('Primary'), section.getFooter('Primary')];
+  await context.sync();
+
+  for (const story of stories) {
+    story.font.name = 'Calibri';
+    story.font.size = 10;
+    await context.sync();
+  }
+});
+```
+
+Each write sync creates a separate transaction. Earlier successful transactions remain if a later transaction fails. Linked headers or footers can share content. Re-read that content before making a dependent edit through another section.
+
 ## Preserve Office.js enum property types
 
 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).
@@ -119,14 +142,37 @@ Use `isDocxEditorError(error)` and branch on `error.code`. `error.target` identi
 | Read the current mode | `document.load('changeTrackingMode')`, then sync and read the property |
 | Make an intentional permanent edit | Explicitly set `changeTrackingMode = 'Off'` |
 
-`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.
+`Off` is the initial runtime mode. `TrackMineOnly` needs a configured author and persists for that runtime. It does not change peers' editing modes or save a document-wide policy. Browser tracked writes require the review module. The tracking property does not change the editor UI mode. `TrackAll` fails with `NotSupported`.
+
+| Tracked edit | Supported behavior |
+| --- | --- |
+| Range text | Insert, replace, or delete text; adjacent sibling paragraphs work outside collaboration |
+| Font and paragraphs | Track font, paragraph-format, and paragraph-style edits as property revisions |
+| Paragraph insertion | Track inserted text and paragraph marks |
+| Lists | Track creation, membership, and level changes; configure newly proposed definitions |
+| Tables | Track complete insertion, cell values, row additions, and partial row deletions |
+| Content controls | Wrap nonempty ordinary text in `PlainText`, `RichText`, or `DatePicker` controls outside collaboration |
+
+Tracked range edits refuse table and wrapper boundaries. Collaborative tracked range edits must remain within one paragraph. Targets that touch foreign pending revisions refuse. Continuation can extend the runtime author's text and paragraph proposals. Simple fields with nested fields or other result containers refuse tracked deletion and replacement. Direct result runs remain supported.
+
+An author can configure a complete proposed table while it has no foreign revisions. Existing table properties and columns require permanent edits. Tracked table and cell value replacement refuse in collaboration. Row deletion suggestions must leave a row without a pending deletion. Pending row or cell structure revisions refuse tracked row deletion with `NotImplemented`.
+
+Accept keeps a proposed content control. Reject restores the original formatted text. The author can set the pending control's `tag` and `title`. Empty ranges, existing review markup, and other control structure changes refuse.
+
+Established list definitions and page setup refuse tracked writes. Comments and revision decisions remain available. Never silently fall back to `Off` when an edit cannot be tracked.
 
 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.
 
+## Insert table rows
+
+`TableRow.insertRows('Before', count, values)` and `'After'` support ordinary source rows beside unrelated merged headers. Merged source rows and crossing vertical merges refuse. Keep each row insertion as the only write in its sync. Sync before editing returned rows. For more information, see [Tables and cells](https://docx-editor.dev/docs/2.x/editor-api/tables).
+
 ## Pictures and page fields
 
 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.
 
+Use `range.insertField('Before', 'TOC', '\\o "1-3" \\h')` to insert an inert TOC instruction. This call saves no calculated entries. TOC evaluation and code writes refuse.
+
 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.
 
 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.
@@ -134,3 +180,13 @@ Headless field calculation requires an explicit `pagination.measurer` when creat
 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.
 
 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.
+
+## Set document metadata
+
+Use `context.document.properties` for core metadata. The supported string properties are `author`, `title`, `subject`, `keywords`, `comments`, and `category`. Batch independent assignments, then call `context.sync()`. Load explicit property names before reading them. Metadata writes require tracking mode `Off`.
+
+Do not substitute revision author settings for document author metadata. Other document information and custom properties remain unchanged.
+
+Collaborative writes require an existing core-properties part. If the input omits this part, set properties before joining collaboration. Concurrent creation of this package part cannot merge safely.
+
+Load `properties.lastAuthor` to read the last saved author. This property has no setter. To remove all standard property parts, call `document.removeDocumentInformation('DocumentProperties')`, then `context.sync()`. Run this command alone. It removes core, extended, and custom properties, including the last author. It preserves document text, comments, revisions, and media. It does not anonymize their content. Other removal modes, tracked removal, and removal during collaboration refuse with `NotSupported`.

package/dist/browser.d.mts

@@ -21,8 +21,8 @@
  * @packageDocumentation
  * @public
  */
-import { ab as RevisionTextView, G as DocxEditorRuntime, C as CreateServerOptions, D as DocxEditorServerRuntime, a as CreateCollaborativeOptions } from './server-mLIW1Y6U.mjs';
-export { A as Alignment, B as BesideLocation, b as Body, c as BodyInsertParagraphLocation, d as BodyInsertTextLocation, e as Bookmark, f as BookmarkCollection, g as BreakType, h as ChangeTrackingMode, i as ClientObject, j as ClientResult, k as Comment, l as CommentCollection, m as CommentReply, n as CommentReplyCollection, o as ContentControl, p as ContentControlCollection, q as ContentControlLockState, r as ContentControlSubtype, s as ContentControlType, t as ContentControlValue, u as Document, v as DocumentCapabilities, w as DocumentLimits, x as DocumentXmlLimits, y as DocumentZipLimits, z as DocxEditorError, E as DocxEditorErrorCode, F as DocxEditorErrorInit, H as EditorModule, I as Field, J as FieldCollection, K as FieldType, L as FieldTypeLiteral, M as Font, N as HeaderFooterType, O as InlinePicture, P as InlinePictureCollection, Q as InsertLocation, R as List, S as ListBullet, T as ListCollection, U as ListItem, V as ListNumbering, W as LoadOption, X as LoadQueryOptions, Y as NoteItem, Z as NoteItemCollection, _ as NoteItemType, $ as PageOrientation, a0 as PageSetup, a1 as Paragraph, a2 as ParagraphAlignment, a3 as ParagraphCollection, a4 as ParagraphInsertTextLocation, a5 as Range, a6 as RangeCollection, a7 as RangeInsertTextLocation, a8 as RequestContext, a9 as Revision, aa as RevisionCollection, ac as RevisionType, ad as RunCallback, ae as SearchOptions, af as Section, ag as SectionCollection, ah as SelectionMode, ai as ServerPaginationOptions, aj as Table, ak as TableCell, al as TableCellCollection, am as TableCollection, an as TableRow, ao as TableRowCollection, ap as TrackedObjects, aq as UnderlineType, ar as VerticalAlignment, as as isDocxEditorError } from './server-mLIW1Y6U.mjs';
+import { ad as RevisionTextView, H as DocxEditorRuntime, C as CreateServerOptions, D as DocxEditorServerRuntime, a as CreateCollaborativeOptions } from './server-Csjpe214.mjs';
+export { A as Alignment, B as BesideLocation, b as Body, c as BodyInsertParagraphLocation, d as BodyInsertTextLocation, e as Bookmark, f as BookmarkCollection, g as BreakType, h as ChangeTrackingMode, i as ClientObject, j as ClientResult, k as Comment, l as CommentCollection, m as CommentReply, n as CommentReplyCollection, o as ContentControl, p as ContentControlCollection, q as ContentControlLockState, r as ContentControlSubtype, s as ContentControlType, t as ContentControlValue, u as Document, v as DocumentCapabilities, w as DocumentLimits, x as DocumentProperties, y as DocumentXmlLimits, z as DocumentZipLimits, E as DocxEditorError, F as DocxEditorErrorCode, G as DocxEditorErrorInit, I as EditorModule, J as Field, K as FieldCollection, L as FieldType, M as FieldTypeLiteral, N as Font, O as HeaderFooterType, P as InlinePicture, Q as InlinePictureCollection, R as InsertLocation, S as List, T as ListBullet, U as ListCollection, V as ListItem, W as ListNumbering, X as LoadOption, Y as LoadQueryOptions, Z as NoteItem, _ as NoteItemCollection, $ as NoteItemType, a0 as PageOrientation, a1 as PageSetup, a2 as Paragraph, a3 as ParagraphAlignment, a4 as ParagraphCollection, a5 as ParagraphInsertTextLocation, a6 as Range, a7 as RangeCollection, a8 as RangeInsertTextLocation, a9 as RemoveDocInfoType, aa as RequestContext, ab as Revision, ac as RevisionCollection, ae as RevisionType, af as RunCallback, ag as SearchOptions, ah as Section, ai as SectionCollection, aj as SelectionMode, ak as ServerPaginationOptions, al as Table, am as TableCell, an as TableCellCollection, ao as TableCollection, ap as TableRow, aq as TableRowCollection, ar as TrackedObjects, as as UnderlineType, at as VerticalAlignment, au as isDocxEditorError } from './server-Csjpe214.mjs';
 import { EditorCollaborationSession } from '@docx-editor.dev/core/collaboration';
 import { DocxEditorInstance } from '@docx-editor.dev/core/editor';
 export { RevisionBatchEntry, RevisionBatchResult, RevisionBatchSkipReason } from '@docx-editor.dev/core/automation';
@@ -116,4 +116,5 @@ interface DocxEditorNamespace {
  */
 declare const DocxEditor: DocxEditorNamespace;
 
-export { type CreateBrowserOptions, CreateCollaborativeOptions, CreateServerOptions, DocxEditor, type DocxEditorNamespace, DocxEditorRuntime, DocxEditorServerRuntime, RevisionTextView };
+export { CreateCollaborativeOptions, CreateServerOptions, DocxEditor, DocxEditorRuntime, DocxEditorServerRuntime, RevisionTextView };
+export type { CreateBrowserOptions, DocxEditorNamespace };

package/dist/browser.d.ts

@@ -21,8 +21,8 @@
  * @packageDocumentation
  * @public
  */
-import { ab as RevisionTextView, G as DocxEditorRuntime, C as CreateServerOptions, D as DocxEditorServerRuntime, a as CreateCollaborativeOptions } from './server-mLIW1Y6U.js';
-export { A as Alignment, B as BesideLocation, b as Body, c as BodyInsertParagraphLocation, d as BodyInsertTextLocation, e as Bookmark, f as BookmarkCollection, g as BreakType, h as ChangeTrackingMode, i as ClientObject, j as ClientResult, k as Comment, l as CommentCollection, m as CommentReply, n as CommentReplyCollection, o as ContentControl, p as ContentControlCollection, q as ContentControlLockState, r as ContentControlSubtype, s as ContentControlType, t as ContentControlValue, u as Document, v as DocumentCapabilities, w as DocumentLimits, x as DocumentXmlLimits, y as DocumentZipLimits, z as DocxEditorError, E as DocxEditorErrorCode, F as DocxEditorErrorInit, H as EditorModule, I as Field, J as FieldCollection, K as FieldType, L as FieldTypeLiteral, M as Font, N as HeaderFooterType, O as InlinePicture, P as InlinePictureCollection, Q as InsertLocation, R as List, S as ListBullet, T as ListCollection, U as ListItem, V as ListNumbering, W as LoadOption, X as LoadQueryOptions, Y as NoteItem, Z as NoteItemCollection, _ as NoteItemType, $ as PageOrientation, a0 as PageSetup, a1 as Paragraph, a2 as ParagraphAlignment, a3 as ParagraphCollection, a4 as ParagraphInsertTextLocation, a5 as Range, a6 as RangeCollection, a7 as RangeInsertTextLocation, a8 as RequestContext, a9 as Revision, aa as RevisionCollection, ac as RevisionType, ad as RunCallback, ae as SearchOptions, af as Section, ag as SectionCollection, ah as SelectionMode, ai as ServerPaginationOptions, aj as Table, ak as TableCell, al as TableCellCollection, am as TableCollection, an as TableRow, ao as TableRowCollection, ap as TrackedObjects, aq as UnderlineType, ar as VerticalAlignment, as as isDocxEditorError } from './server-mLIW1Y6U.js';
+import { ad as RevisionTextView, H as DocxEditorRuntime, C as CreateServerOptions, D as DocxEditorServerRuntime, a as CreateCollaborativeOptions } from './server-Csjpe214.js';
+export { A as Alignment, B as BesideLocation, b as Body, c as BodyInsertParagraphLocation, d as BodyInsertTextLocation, e as Bookmark, f as BookmarkCollection, g as BreakType, h as ChangeTrackingMode, i as ClientObject, j as ClientResult, k as Comment, l as CommentCollection, m as CommentReply, n as CommentReplyCollection, o as ContentControl, p as ContentControlCollection, q as ContentControlLockState, r as ContentControlSubtype, s as ContentControlType, t as ContentControlValue, u as Document, v as DocumentCapabilities, w as DocumentLimits, x as DocumentProperties, y as DocumentXmlLimits, z as DocumentZipLimits, E as DocxEditorError, F as DocxEditorErrorCode, G as DocxEditorErrorInit, I as EditorModule, J as Field, K as FieldCollection, L as FieldType, M as FieldTypeLiteral, N as Font, O as HeaderFooterType, P as InlinePicture, Q as InlinePictureCollection, R as InsertLocation, S as List, T as ListBullet, U as ListCollection, V as ListItem, W as ListNumbering, X as LoadOption, Y as LoadQueryOptions, Z as NoteItem, _ as NoteItemCollection, $ as NoteItemType, a0 as PageOrientation, a1 as PageSetup, a2 as Paragraph, a3 as ParagraphAlignment, a4 as ParagraphCollection, a5 as ParagraphInsertTextLocation, a6 as Range, a7 as RangeCollection, a8 as RangeInsertTextLocation, a9 as RemoveDocInfoType, aa as RequestContext, ab as Revision, ac as RevisionCollection, ae as RevisionType, af as RunCallback, ag as SearchOptions, ah as Section, ai as SectionCollection, aj as SelectionMode, ak as ServerPaginationOptions, al as Table, am as TableCell, an as TableCellCollection, ao as TableCollection, ap as TableRow, aq as TableRowCollection, ar as TrackedObjects, as as UnderlineType, at as VerticalAlignment, au as isDocxEditorError } from './server-Csjpe214.js';
 import { EditorCollaborationSession } from '@docx-editor.dev/core/collaboration';
 import { DocxEditorInstance } from '@docx-editor.dev/core/editor';
 export { RevisionBatchEntry, RevisionBatchResult, RevisionBatchSkipReason } from '@docx-editor.dev/core/automation';
@@ -116,4 +116,5 @@ interface DocxEditorNamespace {
  */
 declare const DocxEditor: DocxEditorNamespace;
 
-export { type CreateBrowserOptions, CreateCollaborativeOptions, CreateServerOptions, DocxEditor, type DocxEditorNamespace, DocxEditorRuntime, DocxEditorServerRuntime, RevisionTextView };
+export { CreateCollaborativeOptions, CreateServerOptions, DocxEditor, DocxEditorRuntime, DocxEditorServerRuntime, RevisionTextView };
+export type { CreateBrowserOptions, DocxEditorNamespace };