myrole-docx-editor 0.1.3 → 0.1.5

package/README.md

@@ -65,6 +65,7 @@ badge display also respond to prop changes. `ref.current` is the same handle
 | `zoom` | `1` | |
 | `rulers`, `statusBar` | `true` | |
 | `panel` | `null` | `'navigation'`, `'properties'`, `'variables'` or `'inspector'` |
+| `ui` | all enabled | `{ open: false, export: false, sidePanel: false }` disables file opening, UI exports and right-side panels; configured at mount |
 | `values` | sample set | values for the generated-document preview |
 | `library` | – | `{ fields: [{ path, label?, desc? }], snippets: [{ id, title, code, category?, desc? }], builtinSnippets? }` — offered in the Bibliothèque panel, the ribbon's Variable button and the autocompletion, before what the document already uses |
 | `comments` | `true` | Word's comments as marks on the text; click one for its balloon; « Commentaires » on the Affichage tab toggles them |
@@ -72,6 +73,12 @@ badge display also respond to prop changes. `ref.current` is the same handle
 
 ## Handle
 
+`ui.sidePanel: false` keeps left-side navigation/search available and disables
+right-panel entry points in the toolbar, ribbon, context menu and badges.
+`ui.export: false` requires `onSave` or `draftKey` for Ctrl/⌘S; the host's
+`load`, `save` and `download` APIs remain available. These options configure
+the interface and do not replace server-side permissions.
+
 ```ts
 editor.load(src)                 editor.save(): Uint8Array        editor.download('contrat.docx')
 editor.editor                    // the low-level editor: commands, selection, format, undo…
@@ -182,3 +189,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`.