myrole-docx-editor 0.1.2 → 0.1.4

package/README.md

@@ -14,13 +14,16 @@ pnpm add myrole-docx-editor
 import { createDocxEditor } from 'myrole-docx-editor'
 
 const editor = createDocxEditor(document.getElementById('app'), {
+  badges: false,                       // original {{ … }} and JSONata text
+  theme: 'light',
   onSave: (bytes) => upload(bytes),     // called after a quiet period, and on tab change
 })
 await editor.load(file)                 // File, Blob, ArrayBuffer, Uint8Array or URL
 ```
 
 The container needs a height (`height: 100vh`, or a flex parent). The SDK
-injects its own stylesheet; nothing else to import.
+injects its own scoped stylesheet; nothing else to import. Multiple instances
+can coexist inside the same application. Call `destroy()` when unmounting.
 
 ## React
 
@@ -41,8 +44,9 @@ function Page({ file }) {
 }
 ```
 
-`src` changes reload the document in place; the other props are read at
-mount. `ref.current` is the same handle `createDocxEditor` returns.
+`src` changes reload the document in place. Theme, read-only state, zoom and
+badge display also respond to prop changes. `ref.current` is the same handle
+`createDocxEditor` returns. `<DocxViewer>` is its read-only companion.
 
 ## Options
 
@@ -50,13 +54,18 @@ mount. `ref.current` is the same handle `createDocxEditor` returns.
 |---|---|---|
 | `chrome` | `'full'` | `'full'` ribbon, rulers, panels · `'viewer'` read-only pages under a slim header · `'none'` pages only |
 | `readOnly` | `false` | the caret moves and the selection copies, nothing edits |
-| `theme` | `'system'` | `'light'`, `'dark'`, `'system'` |
+| `theme` | `'light'` | `'light'`, `'dark'`, `'system'` |
 | `fontsUrl` | next to the bundle | the directory that holds `ttf/` — see Fonts |
-| `onSave` | – | autosave target; the `.docx` bytes |
+| `onSave` | – | async persistence callback; resolving acknowledges saved bytes |
+| `onError`, `onSaveState` | – | save failures and state changes |
+| `draftKey` | – | opt-in IndexedDB recovery; unique per user/document |
+| `saveDelay` | `2000` | autosave debounce in milliseconds |
+| `badges` | `true` | `false` for raw document text, or `{ variables, expressions }` |
 | `onChange`, `onReady` | – | |
 | `zoom` | `1` | |
 | `rulers`, `statusBar` | `true` | |
-| `panel` | `null` | open on `'variables'` or `'inspector'` |
+| `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 |
@@ -64,6 +73,12 @@ mount. `ref.current` is the same handle `createDocxEditor` returns.
 
 ## 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…
@@ -73,6 +88,10 @@ editor.showPanel('variables')    editor.fileName('contrat.docx')  editor.pages()
 editor.variables.tags()          editor.variables.preview(true, values)
 editor.comments()                editor.showComments(false)
 editor.on('change' | 'selection' | 'render' | 'save' | 'load' | 'zoom', fn)
+await editor.saveNow()           editor.isDirty()                 editor.saveState()
+editor.fitZoom('width')          // or 'page'; follows host resizing
+editor.variables.setDisplay(false) // source text without variable/function badges
+await editor.getDraft()          await editor.restoreDraft()      await editor.discardDraft()
 editor.destroy()
 ```
 
@@ -81,11 +100,72 @@ adds a ribbon button, `registerDecorations` adds marks anchored to text,
 `format` / `formatPara` / `setMargins` / `table` / `insertImage` edit the
 model, `undo` / `redo` / `save` do what they say.
 
+`formatPara({ styleId: 'Heading1' })` applies an existing paragraph style to
+the selected paragraphs. It resets direct paragraph formatting and character
+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.
+
+## Display and context actions
+
+**Document brut**, under **Affichage** and **Réglages**, shows the original
+variable/JSONata code without modifying the DOCX. Set `badges: false` to open
+that way. The Variables tab also controls variable and expression badges
+separately. Generated **Aperçu** evaluates tags and remains a separate mode.
+
+The compact ribbon, heading/page navigation and properties pane adapt to the
+component width. Right-click targets text, images, fields or table cells while
+preserving a containing selection. It offers formatting, plain-text copy/cut,
+rich/plain paste, image sizing, table actions, properties and undo. Shift+F10,
+arrow keys and Escape operate the same menu. Browser clipboard restrictions
+fall back to the usual keyboard shortcuts. Read-only commands stay disabled.
+
+`save()` serializes bytes; `saveNow()` waits for persistence, including edits
+made during an upload. Failures retain the dirty state. Without `onSave` or
+`draftKey`, saving downloads a copy and retains the unsaved status. A draft is
+written before upload and removed after success. Recovery is explicit through
+`restoreDraft()`; save before destroying if the host needs upload completion.
+An unsaved document without persistence blocks `load()`; callers may explicitly
+allow replacement using `load(source, { discardChanges: true })`.
+
+## User feedback
+
+Enable **Signaler un manque** with `feedback: true` to export a JSON report locally,
+or provide a submission callback:
+
+```ts
+createDocxEditor(el, {
+  feedback: {
+    onSubmit: async report => {
+      const response = await fetch('/api/feedback', {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(report),
+      })
+      if (!response.ok) throw new Error('Feedback submission failed')
+    },
+  },
+})
+```
+
+The form freezes the file name, visible canvas pages, selection and variable
+badges when opened. Users describe their goal, missing feature and optional
+workaround, and may remove the PNG screenshot. Context includes SDK/browser
+versions, zoom, page/selection positions, display mode and the last 20 SDK
+events. No DOCX bytes, selected text, preview values or global console logs are
+collected; the screenshot can contain visible document text. Submission failures
+keep the form available for retry and notify `onError`.
+
+Feedback is opt-in. `editor.openFeedback()` opens the same form for custom chrome,
+after loading a document. React accepts the same `feedback` option. Import
+`FeedbackReport`, `FeedbackContext` and `FeedbackOptions` from the package for
+typed integrations. The host owns authentication and storage; the SDK sends no
+network request itself.
+
 ## Fonts
 
-The engine measures with 219 subset faces shipped under `fonts/ttf/`
+The engine measures with 228 subset faces shipped under `fonts/ttf/`
 (33 MB, loaded on demand). They are declared at runtime from
-`fontsUrl`, which defaults to `fonts/` next to the bundle. If your bundler
+`fontsUrl`, which defaults to the package’s `fonts/` directory. If your bundler
 does not keep that directory next to the output, serve it yourself:
 
 ```ts