myrole-docx-editor 0.1.4 → 0.2.0

package/README.md

@@ -87,6 +87,8 @@ editor.setZoom(1.25)             editor.setTheme('dark')          editor.setRead
 editor.showPanel('variables')    editor.fileName('contrat.docx')  editor.pages()
 editor.variables.tags()          editor.variables.preview(true, values)
 editor.comments()                editor.showComments(false)
+editor.addComment('Review', 'Author')  // nonempty body selection → ID or null
+editor.updateComment(id, 'Updated')   editor.deleteComment(id)
 editor.on('change' | 'selection' | 'render' | 'save' | 'load' | 'zoom', fn)
 await editor.saveNow()           editor.isDirty()                 editor.saveState()
 editor.fitZoom('width')          // or 'page'; follows host resizing
@@ -106,6 +108,34 @@ overrides covering more than half the paragraph, preserving local emphasis,
 character styles and structural XML. `styleId: null` restores the document's
 default style; `'Normal'` selects that named style. Unknown IDs are ignored.
 
+```ts
+const editing = editor.editor
+if (!editing) throw new Error('Load a document first')
+editing.selectRange({ para: 2, off: 0 }, { para: 2, off: 8 })
+editing.setLink('https://example.org')        // selected text; null removes the current link
+const styleId = editing.defineStyle('My heading') // create and apply from the selection
+if (styleId) editing.defineStyle('My heading', styleId) // update the same style
+editing.setList(true)                        // numbered; false for bullets; null removes it
+editing.setListLevel(1)                      // levels 0–8
+editing.restartList(1)                       // body list, from the current item
+editing.undo()
+```
+
+These actions are also available in the ribbon and refuse edits in read-only
+mode. Comments, styles, links and numbering definitions participate in undo/redo,
+including their package relationships. Classic comments support creation on a
+nonempty body range, editing and deletion, without threaded replies or resolution.
+Documents with extended/threaded comment metadata remain readable; their comment
+writes are refused to preserve the linked metadata.
+Links support HTTP(S), mailto and `#bookmark`, within one paragraph and inline
+container. Styles created here are paragraph styles. List restart currently
+requires a body list with direct numbering properties.
+
+Header/footer addresses use `{ para, off, part: 'word/header1.xml' }` (or the
+actual part name). Enter, Backspace/Delete and range deletion stay in that part;
+undo retains the story. Splitting inside a complex field, revision or content
+control is refused without altering the document.
+
 ## Display and context actions
 
 **Document brut**, under **Affichage** and **Réglages**, shows the original
@@ -189,3 +219,32 @@ const { pages } = await renderDocx(url, hiddenDiv)   // HTMLCanvasElement[]
 
 `pnpm build` writes `dist/` (ESM, one chunk per entry, types) and packs the
 fonts. CI publishes on a `v*` tag; see `.gitlab-ci.yml` at the repository root.
+
+## Exclusive editing
+
+An optional `lock` adapter supplies `acquire(sessionId)`, `renew(sessionId)`,
+`release(sessionId)` and `read(sessionId)`. Acquire and renew return
+`{ acquired: true, ttlMs }` or `{ acquired: false, owner?: string }`. Read returns
+fresh `Uint8Array` document bytes after acquisition. Configure one adapter per
+document and remount the editor when the document identity changes.
+
+```tsx
+<DocxEditor
+  src={initialDocument}
+  lock={documentLockAdapter}
+  onSave={(bytes, {lockId}) => saveWithVerifiedLock(bytes, lockId)}
+  onLockState={state => console.log(state.status)}
+/>
+```
+
+The SDK stays read-only until ownership is confirmed, renews the lease, retries
+occupied sessions and suspends editing on connection loss or expiration. The
+server must reject every write without a valid lease; a `409` error thrown from
+`onSave` also suspends editing. The banner identifies the blocking user, offers
+retry and finishes the session with save-before-release. Unsaved changes survive
+a lost lease in the open editor and can be downloaded for recovery.
+
+`editor.lock` exposes `state()`, `acquire()` and `release()` (or is `null` when
+locking is disabled). `destroy()` attempts final saving and release; the server
+must expire abandoned sessions because browser shutdown is not reliable.
+Read-only viewers acquire nothing. React exports `DOCX_LOCKING_VERSION = 1`.