# @docen/editor ![npm version](https://img.shields.io/npm/v/@docen/editor) ![npm downloads](https://img.shields.io/npm/dw/@docen/editor) ![npm license](https://img.shields.io/npm/l/@docen/editor) > Assembly layer for docen editors β€” bundles a Fluent UI host with the > @docen/docx Tiptap engine into turnkey web components like ``, > and owns the LeaferJS canvas stage that renders the paginated pages. ## Features - 🧩 **Turnkey editors** β€” `` bundles the Fluent UI host with the @docen/docx engine; `` hosts the @docen/pptx canvas editor - 🎨 **Canvas rendering** β€” Pages render on a LeaferJS canvas (no contenteditable, no DOM text); a viewless Tiptap model drives editing through a textarea bridge - πŸ“„ **Office-style pagination** β€” Fixed-height pages with Word's stacking rules (docGrid pitch, table band split, widow/orphan) from @docen/layout; layout re-runs on every edit - πŸ–ŒοΈ **Fluent UI surfaces** β€” Ribbon (buttons, split/toggle buttons, combobox, galleries, color picker), workspace, task/navigation/format panes, context menu - 🌐 **i18n** β€” Built-in Chinese (zh-CN) and English (en); add more via `registerTranslation` / `localizationInfo`. Switch live from the status bar (cycles every registered locale) or the Options dialog - πŸŒ“ **Light/dark theme** β€” Fluent design tokens drive the chrome; switch via the `theme` attribute - πŸ”„ **DOCX round-trip** β€” Open/save `.docx` through the underlying @docen/docx engine - πŸ”Œ **Add-ins** β€” Plug in ribbon tabs, task panes, and commands without touching host internals ## Installation ```bash # Install with pnpm $ pnpm add @docen/editor # Install with npm $ npm install @docen/editor ``` ## Quick Start `` is a self-contained custom element β€” register the components, apply a theme, and drop it in. ```html ``` Open and save DOCX imperatively: ```typescript const doc = document.querySelector("#doc")!; await doc.openDOCX(file); // File | ArrayBuffer | Uint8Array const output = await doc.saveDOCX(); // β†’ Uint8Array ``` ## API ### Web component: `` A turnkey WYSIWYG document editor. The title bar (brand, auto-save, save/undo/redo, filename menu), ribbon, document area, status bar (page/word count, language indicator, zoom), and panes are all built in. **Attributes** Configuration attributes split by reactivity: - **Reactive** β€” change at runtime and the component re-renders: `editable`, `filename`, `user`, `avatar`, `section-properties`, `styles`, `addins`, `theme`. - **Once** β€” read only on connect (initial value); runtime control goes through methods: `content`, `navigation-pane`, `properties-pane`, `zoom`, `show-marks`. The chrome (title bar, ribbon, status bar, panes) is always shown β€” extend it via add-ins rather than toggling attributes. | Attribute | Default | Description | | -------------------- | ---------- | ---------------------------------------------------------------------- | | `user` | β€” | Display name shown in the header | | `avatar` | β€” | Avatar image URL (omitted β†’ initial-letter avatar) | | `filename` | "Document" | Document name shown in the header and save dialog default | | `content` | β€” | Initial document as Tiptap JSON (once on connect) | | `editable` | `true` | `false` makes the surface read-only (reactive) | | `section-properties` | β€” | JSON section page setup (size, margins, orientation); reactive | | `styles` | β€” | JSON named styles; reactive | | `addins` | β€” | JSON array of external add-ins (ribbon/task-pane data); see Add-ins | | `theme` | `light` | `"light" \| "dark"`; drives the Fluent theme | | `navigation-pane` | β€” | `true` opens the navigation (left) pane on connect (once) | | `properties-pane` | β€” | `true` opens the properties (right) pane on connect (once) | | `zoom` | `100` | Initial zoom percent (once); runtime via `setZoom` | | `show-marks` | `false` | `true` shows page/section-break markers (once); runtime `setShowMarks` | | `lang` | β€” | BCP-47 UI locale (`"zh-CN"` / `"en"` / …); per-instance, reactive | Unwired ribbon commands (skeleton buttons) render visually but are greyed out (`disabled`) β€” the ribbon keeps its full Office shape without dead clicks. **Methods** ```typescript class DocenDocument extends HTMLElement { // Open β€” single entry point auto-detects docx/md from the extension. open(file: File): Promise; // Format-specific loaders (use when the format is known up front, e.g. a // server-fetched docx buffer with no filename). openDOCX(input: File | ArrayBuffer | Uint8Array): Promise; openMarkdown(input: File | string): Promise; saveDOCX(): Promise; saveMarkdown(): string; // Runtime model β€” flat Tiptap JSON (doc > block+). Pages are a rendering // projection (@docen/layout paginates per edit), never stored in the model. // For Tiptap's own getText / setContent / chain, use getEditor(). getJSON(): JSONContent; setJSON(json: JSONContent): void; // The underlying @docen/docx Tiptap Editor β€” the full Tiptap API surface. getEditor(): Editor | undefined; repaginate(): void; // Task-pane visibility (Office.addin.showAsTaskpane / hide equivalent). // `id` is "navigation" | "properties"; flips fire docen:taskpane-visibility-change. showTaskpane(id: TaskPaneId): void; hideTaskpane(id: TaskPaneId): void; getTaskpaneState(id: TaskPaneId): boolean; // Zoom (Office.Document.zoom.set equivalent; clamped 10–500). setZoom(pct: number): void; getZoom(): number; // Editing/formatting marks (page + section-break markers). setShowMarks(on: boolean): void; getShowMarks(): boolean; // Add-in registry β€” register/unregister ribbon + command contributions. addAddin(addin: DocenAddin): void; removeAddin(id: string): void; // Office.context.displayLanguage equivalent β€” read-only current UI locale. readonly displayLanguage: string; } ``` **Events** All events bubble and compose out of the shadow DOM β€” listen on the host element. `docen:save` / `:save-as` / `:open` / `:print` / `:close` are cancelable: call `preventDefault()` to take over the action (otherwise the built-in behavior runs). `docen:save-as` carries `{ format }` (`"docx" | "markdown" | "pdf"`) β€” which Save-As variant the user picked. (`docen:open` is format-agnostic: the host auto-detects docx/md from the chosen file's extension, so it carries no detail.) | Event | When | Detail | | ---------------------------------- | ---------------------------------------------- | ------------------------ | | `docen:ready` | Editor mounted and ready | β€” | | `docen:change` | Document content changed (autosave driver) | `{ dirty }` | | `docen:save` | Save button β€” `preventDefault()` to take over | β€” | | `docen:save-as` | Save As menu β€” `preventDefault()` to take over | `{ format }` | | `docen:open` | Open menu β€” `preventDefault()` to take over | β€” | | `docen:new` | New menu β€” host-only (no built-in action) | β€” | | `docen:print` | Print menu β€” `preventDefault()` to take over | β€” | | `docen:close` | Close menu β€” `preventDefault()` to keep edits | β€” | | `docen:taskpane-visibility-change` | A task pane opened/closed (method or pane βœ•) | `{ id, visibilityMode }` | | `docen:zoom-change` | Zoom changed (button / slider / `setZoom`) | `{ zoom }` | | `docen:marks-change` | Formatting marks toggled | `{ showMarks }` | | `docen:lang-change` | Locale changed (status-bar cycle / Options OK) | `{ lang }` | | `docen:theme-change` | Theme changed | `{ theme }` | **Slots** The properties (right) pane body is slot-driven. The default fallback is the built-in `` (empty state); slot a custom element to take over the pane β€” e.g. show image, table, or paragraph properties depending on the current selection. | Slot | Default | Description | | ------------ | --------------------- | ----------------------------------------------------------- | | `properties` | `` | Right pane body. Slot a component to own the properties UI. | ```html ``` Selection-aware switching is the consumer's responsibility β€” the Office.js model leaves task-pane content + navigation to the add-in. Track the selection (e.g. on `docen:change`) and swap the slotted component (`v-if` / conditional render). The built-in `` is a declarative `radio` / `number` / `color` renderer you can reuse as the slotted content when declarative fields are enough. **Configuration** The component works out-of-box. Collaborative actions (save, open, print) hand off to the host via cancelable events; the UI is extended via add-ins. ```html ``` ```typescript const doc = document.querySelector("#doc")!; // Take over save (skip the built-in picker β†’ route to your storage) doc.addEventListener("docen:save", (event) => { event.preventDefault(); saveToStorage(doc.getJSON()); }); // Autosave on change doc.addEventListener("docen:change", () => scheduleAutosave()); ``` **Add-ins** Plug in ribbon tabs and commands without touching host internals β€” declaratively (JSON attribute, data-only β€” functions can't cross the attribute boundary) or imperatively (full add-in object via `addAddin`). The navigation/format panes are built-in; add-ins contribute ribbon tabs and commands. ```html ``` ```typescript // Imperative: full add-in (commands allowed here) doc.addAddin({ id: "citations", name: "Citations", ribbon: [ { tab: "citations", label: "Citations", groups: [ { id: "tools", label: "Tools", controls: [/* … */], }, ], }, ], }); ``` Ribbon control `event` names route to the engine's native Tiptap commands (`editor.chain().focus().(value).run()`), so a built-in name like `bold` works directly. Override a command by contributing a Tiptap extension whose `addCommands` redefines the same name. ### Web component: `` A turnkey PPTX canvas editor. It parses canonical `PresentationOptions`, paints slides and thumbnails with LeaferJS, and edits selection, geometry, tables, text, notes, transitions, and animations in place. | Method | Description | | ------------------------ | ----------------------------------------------------- | | `openPresentation(data)` | Parse a `DataType` PPTX payload and mount the deck | | `getContent()` | Return a cloned canonical `PresentationOptions` model | | `setContent(content)` | Replace the deck with a cloned canonical model | | `savePresentation()` | Generate a PPTX `Uint8Array` | | `closePresentation()` | Discard the in-memory deck and reset the chrome | | Event | When | Detail | | --------------- | ------------------------------------------------ | -------------------- | | `docen:ready` | Deck mounted | β€” | | `docen:change` | Deck content changed | `{ dirty: true }` | | `docen:open` | Open menu β€” `preventDefault()` to take over | β€” | | `docen:save` | Save button β€” `preventDefault()` to take over | `{ format: "pptx" }` | | `docen:save-as` | Save As menu β€” `preventDefault()` to take over | `{ format: "pptx" }` | | `docen:close` | Close menu β€” `preventDefault()` to keep the deck | β€” | ```typescript const pres = document.querySelector("#pres")!; await pres.openPresentation(file); const output = await pres.savePresentation(); ``` ### Internationalization The host ships with English (`en`, default) and Chinese (`zh-CN`). Every label runs through a single `t(key)` lookup, and the locale resolves **per-instance** from `` (forwarded to the internal workspace) β€” set the attribute and the ribbon, header, status bar, and Options dialog re-localize live, with no dependency on ``. The status-bar language pill cycles every registered locale; the Options dialog renders a `