myrole-docx-editor 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# myrole-docx-editor
+
+The MyRole `.docx` engine as an embeddable SDK: a Word-faithful renderer and
+editor on canvas, the template-variables layer, and a Word-like chrome — in
+one call, with a React component.
+
+```sh
+pnpm add myrole-docx-editor
+```
+
+## Vanilla
+
+```ts
+import { createDocxEditor } from 'myrole-docx-editor'
+
+const editor = createDocxEditor(document.getElementById('app'), {
+  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.
+
+## React
+
+```tsx
+import { DocxEditor, useDocxEditor } from 'myrole-docx-editor/react'
+
+function Page({ file }) {
+  const ref = useDocxEditor()
+  return (
+    <DocxEditor
+      ref={ref}
+      src={file}
+      style={{ height: '100vh' }}
+      onSave={(bytes) => upload(bytes)}
+      onReady={(h) => h.showPanel('variables')}
+    />
+  )
+}
+```
+
+`src` changes reload the document in place; the other props are read at
+mount. `ref.current` is the same handle `createDocxEditor` returns.
+
+## Options
+
+| option | default | |
+|---|---|---|
+| `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'` |
+| `fontsUrl` | next to the bundle | the directory that holds `ttf/` — see Fonts |
+| `onSave` | – | autosave target; the `.docx` bytes |
+| `onChange`, `onReady` | – | |
+| `zoom` | `1` | |
+| `rulers`, `statusBar` | `true` | |
+| `panel` | `null` | open on `'variables'` or `'inspector'` |
+| `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 |
+| `maxPages` | – | a guard against a runaway layout |
+
+## Handle
+
+```ts
+editor.load(src)                 editor.save(): Uint8Array        editor.download('contrat.docx')
+editor.editor                    // the low-level editor: commands, selection, format, undo…
+editor.document                  // the OOXML model
+editor.setZoom(1.25)             editor.setTheme('dark')          editor.setReadOnly(true)
+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)
+editor.destroy()
+```
+
+The low-level editor is the same object extensions get: `registerCommand`
+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.
+
+## Fonts
+
+The engine measures with 219 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
+does not keep that directory next to the output, serve it yourself:
+
+```ts
+createDocxEditor(el, { fontsUrl: '/static/docx-fonts/' })   // …/docx-fonts/ttf/*.ttf
+```
+
+Copy `node_modules/myrole-docx-editor/fonts` there, or point at a CDN.
+
+## Read-only render
+
+```ts
+import { renderDocx } from 'myrole-docx-editor'
+const { pages } = await renderDocx(url, hiddenDiv)   // HTMLCanvasElement[]
+```
+
+## Publishing
+
+`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.