Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
[![CI](https://github.com/p10node/office-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/p10node/office-engine/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/npm/l/@p10node/office-engine)](LICENSE)

View + edit **DOCX / XLSX / PPTX** directly in the browser, open and edit **DOC / XLS / PPT** (Office 97-2003), **RTF** and **OpenDocument** (ODT / ODS / ODP), view Apple **Pages**, **Keynote** and **Numbers** files and Microsoft **Visio** drawings, open **CSV**, text, Markdown, HTML and SVG as editable sheets / documents, and draw **Mermaid**, **PlantUML** and **Graphviz** diagrams (no server, no extra library). Loads progressively like Google Docs, handles heavy files, one-line React embed, saves back to the original format.
View + edit **DOCX / XLSX / PPTX** directly in the browser, open and edit **DOC / XLS / PPT** (Office 97-2003), **RTF** and **OpenDocument** (ODT / ODS / ODP), view Apple **Pages**, **Keynote** and **Numbers** files and Microsoft **Visio** drawings, open **CSV**, text, Markdown, HTML and SVG as editable sheets / documents and source code with syntax colors, and draw **Mermaid**, **PlantUML** and **Graphviz** diagrams (no server, no extra library). Loads progressively like Google Docs, handles heavy files, one-line React embed, saves back to the original format.

**Zero runtime dependencies, zero servers.** Parsing, layout, formulas, diagrams and ZIP are all in the library, running in a Web Worker: nothing leaves the browser.

Expand Down Expand Up @@ -74,7 +74,8 @@ Also online at [p10node.github.io/office-engine](https://p10node.github.io/offic
- **CSV, text, Markdown, HTML, SVG**: `.csv` / `.tsv` open as a workbook (streamed: a million rows in about 2 s; past 12 million cells the rows are read from the file as they are shown, so there is no row limit), `.txt` / `.md` / `.html` as a document, `.svg` / `.svgz` as a picture (`.gz` files are unpacked first), from any `src` (file, Blob, URL); format from the extension, MIME type or content; UTF-8 / UTF-16 / Windows-1252; editable. Markdown, HTML and SVG are saved back in their own format (CSV and text as `.xlsx` / `.docx`)
- **Diagrams as code**: `.mmd` (Mermaid), `.puml` (PlantUML), `.dot` / `.gv` (Graphviz) open as a document with the drawing; ` ```mermaid ` / ` ```plantuml ` / ` ```dot ` blocks in Markdown and `<pre class="mermaid">` in HTML are drawn too. Drawn by a built-in layout engine in the worker: no server, no network, no dependency
- **Code side by side**: Markdown, HTML, SVG and diagram files show their source next to the document (**Code** button); edit it and the document is rebuilt as you type; edit the document and the Markdown / HTML is built again from it
- **File menu**: new, open (also DOC / XLS / PPT / RTF / OpenDocument / Pages / Keynote / Numbers / Visio / CSV / text / Markdown / HTML / SVG / diagrams), import CSV, rename, download as PDF / HTML / text / CSV, document details, print
- **Syntax highlighting**: Markdown code blocks are colored by their fence's language (JavaScript / TypeScript / JSX, JSON, Python, CSS, HTML / XML, YAML, shell, SQL, Go, Rust, Java, C / C++ / C#, and more), stay editable, and are saved back with their language and exact code; the colors are only drawn, never stored. Source files (`main.ts`, `script.py`, `config.json`…, or any text with the `language` prop) open in a **code view** with line numbers, in light and dark, editable and saved as plain text. One built-in tokenizer, no dependency ([Features](docs/features.md#syntax-highlighting))
- **File menu**: new, open (also DOC / XLS / PPT / RTF / OpenDocument / Pages / Keynote / Numbers / Visio / CSV / text / Markdown / HTML / SVG / diagrams / source code), import CSV, rename, download as PDF / HTML / text / CSV, document details, print
- **Comments**: threads with replies, resolve, edit / delete, @mentions; on DOCX text, XLSX cells and PPTX slides, stored in the file the way Word, Excel and PowerPoint store them
- **Real-time collaboration**: live edits, avatars, collaborators' cursors, offline edits sync on reconnect
- **Dark mode and theming**: `theme="dark"` or `"auto"` (follows the OS), or a theme object with design tokens for colors, type and shape ([Theming](docs/theming.md)); documents keep their own colors
Expand Down Expand Up @@ -104,7 +105,7 @@ The renderers also ship on their own, to show diagrams and Markdown in any page
| [`@p10node/mermaid`](packages/mermaid) | Mermaid → SVG | 26 KB |
| [`@p10node/plantuml`](packages/plantuml) | PlantUML → SVG (no Java) | 29 KB |
| [`@p10node/graphviz`](packages/graphviz) | Graphviz DOT → SVG (no WebAssembly) | 16 KB |
| [`@p10node/markdown`](packages/markdown) | Markdown → safe HTML, diagram code blocks drawn | 39 KB |
| [`@p10node/markdown`](packages/markdown) | Markdown → safe HTML, diagram blocks drawn, code blocks colored | 54 KB |

```ts
import { render } from '@p10node/mermaid'
Expand Down
21 changes: 16 additions & 5 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,9 @@ CSS is auto-injected, no import needed (or import `@p10node/office-engine/styles

| Prop | Type | Default | Notes |
|--------------------|------------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------|
| `src` | `File \| Blob \| ArrayBuffer \| string \| URL` | – | Office (also 97-2003); OpenDocument; RTF; Pages / Keynote / Numbers; Visio; CSV / TSV, text, Markdown, HTML, diagrams |
| `src` | `File \| Blob \| ArrayBuffer \| string \| URL` | – | Office (also 97-2003); OpenDocument; RTF; Pages / Keynote / Numbers; Visio; CSV / TSV, text, Markdown, HTML, diagrams, source code |
| `name` | `string` | auto | Display name; its extension also tells the format of a `Blob` / `ArrayBuffer` |
| `language` | `string` | – | The file is source code in this language (`'typescript'`, `'ts'`, `'python'`, `'c++'`…): a text file opens in the code view, colored in it, whatever its name / MIME type say (an unknown language: plain code). Without it, `main.ts`, `script.py`, `config.json`… are told by their extension or MIME type |
| `toolbar` | `boolean` | `true` | Top bar (name, status, progress) |
| `toolbarExtra` | `ReactNode` | – | Extra buttons on the right of the toolbar |
| `zoom` | `number \| 'fit'` | `'fit'` | Initial zoom (docx/pptx) |
Expand All @@ -73,7 +74,7 @@ CSS is auto-injected, no import needed (or import `@p10node/office-engine/styles
| `icons` | `Icons` | built-in | Your own icons: a map by `IconName` or a resolver `(name, { size }) => node`; see [Icons](#icons) |
| `onRename` | `(name) => void` | – | File → Rename result (extension included) |
| `onClose` | `() => void` | – | Adds File → Close |
| `onSave` | `(blob, name) => void` | download | Receives saved file (downloads by default): the Office file, or a Markdown / HTML / SVG file as itself |
| `onSave` | `(blob, name) => void` | download | Receives saved file (downloads by default): the Office file, or a Markdown / HTML / SVG / source file as itself |
| `onDirtyChange` | `(dirty) => void` | – | Whether there are unsaved changes |
| `collab` | `CollabOptions` | – | Real-time collaboration, see [collaboration](collaboration.md) |
| `comments` | `CommentOptions \| false` | `{}` | Comments (see below); `false` hides them |
Expand Down Expand Up @@ -205,7 +206,7 @@ import { IconsProvider, XlsxView } from '@p10node/office-engine'
</script>
```

`<office-viewer>`: attributes `src`, `name`, `editable`, `toolbar="false"`, `thumbnails="false"`, `save="false"`, `download="false"`, `file-menu="false"`, `open="false"`, `capture-select-all="false"`, `theme="dark"` (or `"auto"`), `collab` / `room` / `user` / `base` (real-time collaboration; `user` also writes the comments), `comments="false"`; properties `.file = File` and `.icons` (map or resolver, as `icons` above); events `load`, `error`, `comment` (`detail`: a `CommentEvent`).
`<office-viewer>`: attributes `src`, `name`, `language` (a source file's, as the prop), `editable`, `toolbar="false"`, `thumbnails="false"`, `save="false"`, `download="false"`, `file-menu="false"`, `open="false"`, `capture-select-all="false"`, `theme="dark"` (or `"auto"`), `collab` / `room` / `user` / `base` (real-time collaboration; `user` also writes the comments), `comments="false"`; properties `.file = File` and `.icons` (map or resolver, as `icons` above); events `load`, `error`, `comment` (`detail`: a `CommentEvent`).

## Core API (no React)

Expand All @@ -215,7 +216,8 @@ import { DocumentClient } from '@p10node/office-engine/core'
const doc = await DocumentClient.open(fileOrUrl, { onProgress: console.log })
doc.kind // 'docx' | 'xlsx' | 'pptx'
doc.info.from // 'pages' / 'keynote' / 'numbers' / 'visio': an Apple or Visio file, converted to docx / pptx / xlsx / pptx (view only)
doc.info.imported // 'csv' / 'tsv' / 'text' / 'markdown' / 'html' / 'svg' / 'mermaid' / 'plantuml' / 'graphviz': a plain file, built as xlsx / docx (editable)
doc.info.imported // 'csv' / 'tsv' / 'text' / 'markdown' / 'html' / 'svg' / 'mermaid' / 'plantuml' / 'graphviz' / 'code': a plain file, built as xlsx / docx (editable)
doc.info.language // 'code' (a source file): its language, 'typescript' / 'python' / 'json'… (the hint's own word when it is not one the highlighter knows)
doc.info.converted // 'doc' / 'xls' / 'ppt' / 'rtf' / 'odt' / 'ods' / 'odp': converted to docx / xlsx / pptx (editable, saved as such)
doc.info.ext // 'xlsm' / 'xltx' / 'docm' / 'dotx' / 'pptm' / 'potx' / 'ppsx' …: the file is that variant, and is saved as it (undefined: plain docx / xlsx / pptx)
doc.on('docx:blocks', (blocks) => {}) // docx: streamed blocks
Expand All @@ -233,13 +235,21 @@ await doc.call('xlsx.text', 0, ',') // the sheet as CSV (a Blob; '\t' for TSV),
// open(src, { residentCells: 12_000_000 }): cells of a CSV / TSV kept in memory; the other rows are read from the file as they are shown
// open(src, { encoding: 'windows-1258' }): the encoding of a text file (CSV, TSV, text, Markdown, HTML…), a TextDecoder label; without it the
// byte order mark, the declared charset, UTF-8, then (Vietnamese text) Windows-1258, then Windows-1252 decide. An unknown label is an error
// open(src, { language: 'python' }): a text file is source code in this language (as the `language` prop)
// the worker also emits `warning` ({ text }) when a file opened but not whole: a CSV with more than 16,384 columns (the viewer shows it as a message)
const comments = await doc.call('comments.list') // DocComment[]: threads are roots + replies (threadsOf)
doc.on('comment', ({ id, c }) => {}) // a comment set / deleted (c null), here or by a collaborator
await doc.call('comments.set', c.id, { ...c, done: true }) // XLSX / PPTX threads carry their place (`at`)
const blob = await doc.call('save') // edited file
await doc.call('plain.source') // text of a Markdown / HTML / diagram file (null for other files)
await doc.call('plain.source') // text of a Markdown / HTML / diagram / source file (null for other files)
await doc.call('plain.original') // a source file's bytes as opened (null for other files)
doc.destroy()

// syntax colors, DOM-free (the tokenizer of the code view, the Markdown code blocks and @p10node/markdown)
import { highlight, highlightLines, languageOf } from '@p10node/office-engine/core'
highlight('ts', 'const a = 1') // [['k', 'const'], ['', ' a = '], ['n', '1']]: c comment, k keyword, s string, n number / constant,
// f function, y type, a attribute / property, t tag, m meta, o operator ('' plain)
languageOf('c++') // 'cpp' (undefined: a language it does not color)
```

## Standalone packages
Expand All @@ -253,6 +263,7 @@ renderPage() // <pre class="mermaid">, <code class="language-dot">… of the pag

import { render as markdown } from '@p10node/markdown'
el.innerHTML = markdown(text) // safe HTML; ```mermaid / ```plantuml / ```dot drawn
el.innerHTML = markdown(text, { highlight: true }) // and code blocks colored: <span class="hl-keyword">…
```

## CSP
Expand Down
Loading