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
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ Also online at [p10node.github.io/office-engine](https://p10node.github.io/offic
- **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
- **Numbers typed in a locale**: `locale="de-DE"` reads `1,5` and `1.234,5` typed into cells and fields (font size, margins); the whole entry or nothing, saved as the number itself, formulas unchanged ([API](docs/api.md#numbers-typed-in-a-locale))
- **Embed anywhere**: React component, hook, vanilla `mount()`, `<office-viewer>` web component, single `<script>` file

Full list, format coverage and limitations: [Features](docs/features.md).
Expand Down
24 changes: 23 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { DocViewer } from '@p10node/office-engine'
<DocViewer src={file} allowSave={false} allowDownload={false} /> // no Save/Download, no image download
<DocViewer src={file} fileMenu={false} /> // no File menu
<DocViewer src={file} theme="dark" /> // dark chrome; "auto" follows the OS setting
<DocViewer src={file} editable locale="de-DE" /> // numbers typed as 1,5 and 1.234,5
```

### File menu
Expand Down Expand Up @@ -62,6 +63,7 @@ CSS is auto-injected, no import needed (or import `@p10node/office-engine/styles
| `styleTarget` | `Document \| ShadowRoot` | document | Where CSS is injected |
| `injectStyles` | `boolean` | `true` | Inject the stylesheet; false when the page loads `@p10node/office-engine/styles.css` itself |
| `theme` | `'light' \| 'dark' \| 'auto' \| ThemeOptions` | `'light'` | Color scheme of the chrome; `'auto'` follows `prefers-color-scheme`; an object adds token overrides ([Theming](theming.md)). Documents keep their own colors |
| `locale` | `string` | – | BCP 47 tag the numbers typed are read in (`de-DE`: `1,5`); none: a decimal point. [More](#numbers-typed-in-a-locale) |
| `editable` | `boolean` | `false` | Open in edit mode (Pages, Keynote, Numbers and Visio files stay view only) |
| `allowEdit` | `boolean` | `true` | Show Edit/View button |
| `allowSave` | `boolean` | `true` | Show Save/Download button, enable Ctrl+S |
Expand Down Expand Up @@ -190,6 +192,25 @@ import { IconsProvider, XlsxView } from '@p10node/office-engine'
</IconsProvider>
```

### Numbers typed in a locale

`locale` (a BCP 47 tag) says how the numbers a person types are read: into a cell of a sheet, the font size box, the margins and column spacing of Page setup, the size in Header & footer. Its decimal and grouping separators, minus and percent signs and digits come from `Intl.NumberFormat`:

```tsx
<DocViewer src={file} editable locale="de-DE" /> // 1,5 → 1.5; 1.234,5 → 1234.5; 50 % → 0.5; 1.5 stays text
<DocViewer src={file} editable locale="fr-FR" /> // 1 234,5 (any space) → 1234.5
<DocViewer src={file} editable /> // as before: 1.5 and 1,234.5; 1,5 stays text
```

- Without `locale` (or with a tag that is not one, such as `de_DE`) a number has a decimal point and commas grouping by thousands, as before; the browser's language is not used.
- The whole text is read as one number or not at all: `12,5` without a locale is not 12, `1.5` with `de-DE` is not 15. A cell keeps what is not a number as text; a field keeps its previous value (the font size box shows it again, Page setup disables Apply). The rules, grouping included: [Features](features.md#numbers-typed-in-a-locale).
- What is saved is the number (`<v>1.5</v>`), the same in every locale; changing `locale` changes no value of a workbook. A number edited again shows the locale's decimal separator (`1,5` in the formula bar and the cell), which reads back as the same number.
- Formulas are not localized: `=1.5+A1`, `=SUM(1,5)` and the English function names, whatever the locale.
- With `locale`, the Page setup and Header & footer fields are text fields read by the same rules; without it they stay the browser's number fields.
- Collaboration: the tag goes with each cell edit (`locale` of the shared `set` operation), so every participant, and a server replaying the log with `compact`, reads `1,5` the same. Participants should run a version that knows it: an older one reads such an edit with a decimal point.

Without `DocViewer`: `client.call('xlsx.set', sheet, cells, { locale: 'de-DE' })`; `mount(el, { src, locale: 'de-DE' })`; `<office-viewer locale="de-DE">`.

## Without a React build

```html
Expand All @@ -205,7 +226,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`, `editable`, `toolbar="false"`, `thumbnails="false"`, `save="false"`, `download="false"`, `file-menu="false"`, `open="false"`, `capture-select-all="false"`, `theme="dark"` (or `"auto"`), `locale="de-DE"` (numbers typed, see [above](#numbers-typed-in-a-locale)), `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 @@ -225,6 +246,7 @@ doc.on('xlsx:progress', (p) => {})
await doc.call('xlsx.block', 0, 1000, 1100) // formatted cells, rows [1000, 1100)
await doc.call('pptx.slide', 12) // slide model with layout/master/theme resolved
await doc.call('xlsx.set', 0, [{ r: 4, c: 1, input: '=SUM(A1:A4)' }])
await doc.call('xlsx.set', 0, [{ r: 5, c: 1, input: '1.234,5' }], { locale: 'de-DE' }) // numbers typed in a locale: 1234.5
const clip = await doc.call('xlsx.copy', 0, { r0: 0, c0: 0, r1: 9, c1: 2 }) // cells as they are (values, formats, formulas) + `text` for the clipboard
await doc.call('xlsx.sheetOp', 0, { op: 'paste', range: { r0: 20, c0: 0, r1: 29, c1: 2 }, cells: clip.cells, from: { sheet: clip.sheet, r0: 0, c0: 0 } })
await doc.call('xlsx.sheetOp', 0, { op: 'clear', range: { r0: 0, c0: 3, r1: 1048575, c1: 3 } }) // a whole column, every row of it
Expand Down
1 change: 1 addition & 0 deletions docs/collaboration.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@ async function takeSnapshot(room: string) {

- Undo / redo only touches your own changes: a cell someone else typed over since is left as they left it
- A formula typed while someone else inserts / deletes rows or columns, or renames a sheet, is rewritten with that operation (it reads the cells meant)
- A cell edit carries the `locale` its numbers were typed in ([API](api.md#numbers-typed-in-a-locale)): every participant and `compact` read `1,5` typed with `de-DE` as 1.5, whatever their own `locale`. Each replica takes the locale's separators from its own `Intl` data; spaces and apostrophes are read in all their forms, so the usual differences between browser and server versions do not change a value. A participant running an older version reads such an edit with a decimal point
- DOCX rooms are not snapshotted yet (their edits run in the view's editor): newcomers replay the whole history
- Deleting rows / columns can't be undone while collaborating
- One hub process per room; batches not yet flushed (up to 250 ms on S3) are lost if it crashes, and clients ahead of the stored log must reopen
Expand Down
19 changes: 17 additions & 2 deletions docs/features.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ Diagram sources open as a document holding the drawing (an SVG picture, editable

### XLSX

- **Cells**: edit, line break inside a cell or the formula bar (`Alt+Enter` or `Shift+Enter`: the cell wraps and its row grows to show every line), range selection, select all (Ctrl/⌘+A), copy/cut/paste (within a workbook: exact values, formats and formulas, a cut moving the cells and what reads them; from other programs: tab separated text, quoted cells with line breaks included; a whole column or sheet is cleared and copied whole, the rows not shown yet too), fill down/right and the fill handle (drag the corner of the selection down or to the right: one row / column is copied, several are repeated), one copied value pasted into a selection fills it, a paste of HTML only (a table) pastes its cells, a paste that would drop data over merged cells is refused with a message, merging cells that hold data says what was dropped, sort (the rows of the table around the selection, its header left on top; in Excel's order: numbers, text, FALSE, TRUE, errors, cells without anything last in either direction; comments go with their rows; a range holding merged cells is refused with a message), find & replace (match case, entire cell, in formulas). A date or a percentage typed into a cell without a format shows as one; a cell formatted as Text keeps what is typed. `+A1+B1`, `-A1` and `@SUM(A1:A3)` are formulas (what reads a cell or calls a function: `-5` is a number, `- item` is text); `#N/A` and the other error values typed are errors; `1,234,567`, `$50`, `€1,200.50` and `50 ₫` are numbers shown as typed; a number of more than 15 digits (a card number) stays text. A formula typed into a cell without a format shows as what it computes (`=TODAY()`, `=DATE(…)`, `=A1+30` as dates, `=A1` as A1 is shown)
- **Cells**: edit, line break inside a cell or the formula bar (`Alt+Enter` or `Shift+Enter`: the cell wraps and its row grows to show every line), range selection, select all (Ctrl/⌘+A), copy/cut/paste (within a workbook: exact values, formats and formulas, a cut moving the cells and what reads them; from other programs: tab separated text, quoted cells with line breaks included; a whole column or sheet is cleared and copied whole, the rows not shown yet too), fill down/right and the fill handle (drag the corner of the selection down or to the right: one row / column is copied, several are repeated), one copied value pasted into a selection fills it, a paste of HTML only (a table) pastes its cells, a paste that would drop data over merged cells is refused with a message, merging cells that hold data says what was dropped, sort (the rows of the table around the selection, its header left on top; in Excel's order: numbers, text, FALSE, TRUE, errors, cells without anything last in either direction; comments go with their rows; a range holding merged cells is refused with a message), find & replace (match case, entire cell, in formulas). A date or a percentage typed into a cell without a format shows as one; a cell formatted as Text keeps what is typed. `+A1+B1`, `-A1` and `@SUM(A1:A3)` are formulas (what reads a cell or calls a function: `-5` is a number, `- item` is text); `#N/A` and the other error values typed are errors; `1,234,567`, `$50`, `€1,200.50` and `50 ₫` are numbers shown as typed; a number of more than 15 digits (a card number) stays text. With the viewer's `locale` these are read in its separators (`1,5`, `1.234,5`, `50 %` with `de-DE`): see [Numbers typed in a locale](#numbers-typed-in-a-locale). A formula typed into a cell without a format shows as what it computes (`=TODAY()`, `=DATE(…)`, `=A1+30` as dates, `=A1` as A1 is shown)
- **Keyboard**: arrows, `Tab` / `Enter` (after Tabs, Enter returns to the column the row was started in), `Home` / `End` / `Ctrl+Home` / `Ctrl+End`, `Ctrl+Arrow` (to the edge of the block of filled cells), `Shift+Space` / `Ctrl+Space` (select the row / column), `Alt+=` (AutoSum), `Ctrl+;` (today; with Shift the time), `Ctrl+Enter` (the entry into every selected cell), `F4` (cycles `$` on the reference at the caret), `F2`, `Ctrl+S` (also in a cell being edited). Text that comes from an IME (Vietnamese Telex included), a virtual keyboard or an emoji picker starts the edit of the selected cell: the grid keeps a hidden text field for the keyboard, which becomes the cell editor. Its on-screen keyboard is not opened until a cell is edited
- **Sizes**: `Wrap text` and a text rotation grow the rows to show the text (tilted text goes out over the cells to its right, as in Excel); double click on the edge of a column / row fits it; a column left at the default width widens when a number format (date, currency…) would show `####`. A number without a format is shown in what fits its column, measured in the font the browser has (fewer decimals, then the scientific form, `####` last). Pattern fills show as the mix of their colors, diagonal borders are drawn, shrink to fit scales the text; rich text (parts of a cell in fonts of their own) is shown, and typing over it leaves plain text. Not done: zoom; rows of a file that say no height are not fitted to wrapped or turned text when it is opened
- **Formulas**: auto-calculated: the functions of Excel and of Google Sheets but those that ask a service or the application itself (543 of the 568 the two list: [formula-coverage.md](formula-coverage.md) says which, and what differs); shared and array formulas; `LET` and `LAMBDA` (with `MAP`, `REDUCE`, `SCAN`, `BYROW`, `BYCOL`, `MAKEARRAY`); defined names (of the workbook, or local to a sheet), structured references (`Table1[Qty]`, `[@Qty]`), 3-D references (`First:Last!A1`) and the intersection of references (a space: `B2:D4 C1:C9`, `North Q1`); `INDIRECT` / `OFFSET` / `NOW` / `RAND` at every change, `TODAY` / `NOW` / `RAND` also when the file is opened; a workbook that says to compute on load is computed when opened; a formula using a function the engine does not have, or a name the workbook does not, keeps the value the file holds
Expand All @@ -206,7 +206,22 @@ Diagram sources open as a document holding the drawing (an SVG picture, editable

### Toolbar

Single row, buttons that don't fit collapse into `⋮`; custom-drawn dropdowns (font/style preview, number formats with examples, ↑↓/Enter/Esc/type-ahead keys, never steals focus from the document); font size box `− 11 +` accepts direct input; cell borders picked from an icon grid; color pickers have a palette plus a **Custom** row (`+` opens the system color picker, recent custom colors are remembered across sessions). Every icon can be replaced with the host's own set (Lucide, Phosphor or any other) through the `icons` prop, see [API](api.md#icons).
Single row, buttons that don't fit collapse into `⋮`; custom-drawn dropdowns (font/style preview, number formats with examples, ↑↓/Enter/Esc/type-ahead keys, never steals focus from the document); font size box `− 11 +` accepts direct input (one whole number: `12,5` with `de-DE`, `12.5` or `12,5` without a locale; anything else keeps the size it had, see [Numbers typed in a locale](#numbers-typed-in-a-locale)); cell borders picked from an icon grid; color pickers have a palette plus a **Custom** row (`+` opens the system color picker, recent custom colors are remembered across sessions). Every icon can be replaced with the host's own set (Lucide, Phosphor or any other) through the `icons` prop, see [API](api.md#icons).

### Numbers typed in a locale

The viewer's `locale` ([API](api.md#numbers-typed-in-a-locale)) sets how typed numbers are read: in cells, the font size box, the margins and column spacing of Page setup and the size in Header & footer. One parser in the core reads them all, by these rules:

- **Without a locale** (or with a tag that is not one, or one `Intl` has no data for): a decimal point and commas grouping by thousands, exactly as before; the browser's language is never used. `en-US` reads the same.
- **Separators**: the locale's decimal separator, grouping separator, minus sign, percent sign and digits, from `Intl.NumberFormat(locale).formatToParts`. `1,5` in `de-DE`, `fr-FR`, `sv-SE`; `1.5` in `en-US`, `de-CH`, `en-IN`.
- **The whole text**: it is one number or none. A prefix is never read: `12,5` without a locale and `12,5pt` are not 12, `1.2.3` is not 1.2. In a cell what is not a number stays text (as before); in a field the previous value is kept.
- **The font size box, without a locale**: the one exception. It reads a decimal comma as well as a point (`12,5` and `12.5` are 12.5, as before), since a size from 1 to 400 needs no grouping; it still reads the whole text only, so `12pt`, `1.2.5`, `1,2,5`, `1,234` (a comma before three digits could group thousands) and an empty box keep the size it had. With a locale the box follows the locale like the rest: `12,5` is refused in `en-US`. Cells, Page setup and Header & footer have no such exception.
- **Grouping**: only the locale's grouping character, and only between groups of the size the locale writes (3 digits; in India 3 next to the decimal separator, then 2: `12,34,567` in `en-IN`), the same character throughout a number. A locale grouping with a space reads the ordinary space, the no-break space (U+00A0), the narrow no-break space (U+202F) and the thin space (U+2009) alike; one grouping with an apostrophe (`de-CH`) both `'` and `’`. Grouping is optional (`1234,5` = `1.234,5` in `de-DE`) and does not go with an exponent.
- **The other convention's separator is refused, not guessed**: `1,5` in `en-US` (a comma that does not group 3 digits) and `1.5` in `de-DE` (a point that does not) are not numbers, nor is `1,234.5` in `de-DE` (a grouping separator after the decimal one) or `1,234,567` in `en-IN`. A well-formed grouping is read as one: `1.234` in `de-DE` is 1234, as `1,234` is 1234 without a locale; the cell takes the `#,##0` format, which shows it grouped.
- **Forms**: a sign (`-`, `+`, and the locale's own minus such as `−` in `sv-SE`), digits, decimals (`,5` and `5,` in `de-DE`), an exponent (`1,5e3`, `1,5E-3`); in a cell also a percentage, the sign after the number (`12,5%`, and `50 %` where the locale writes a space before the sign: `de-DE`, `fr-FR`; not `%50`, also in Turkish) and an amount with a currency sign (`$ € £ ¥ ₫ ₩ ₹ ₽ ₱ ฿`) before or after it (`1.234,50 €`). Parentheses for negatives, fractions (`1 1/2`) and times are not read as numbers, with or without a locale.
- **Digits**: ASCII digits in every locale, and the locale's own digits where it writes others (Arabic-Indic `١٫٥` in `ar-EG`, Persian, Devanagari, Bengali…), not both in one number; the direction marks such locales write around signs are ignored.
- **Saved values**: a number, as OOXML stores it (`<v>1234.5</v>`), the same whatever the locale; number formats derived from what was typed (`0.0%`, `#,##0.00" €"`) are format codes, the same in every locale. Changing `locale` changes no value of a workbook. A number edited again (formula bar, `F2`) shows the locale's decimal separator and no grouping (`1,5`, `1234,5`), which reads back as the same number.
- **Not localized**: formulas (`=1.5+A1`, `=SUM(1,5)`, English function names and the comma between arguments, whatever the locale), dates typed (`2024-01-15`, `15/01/2024` as before), how cells show their values (their number format, with a point and commas), CSV / TSV files (read by their own rules, see [above](#csv-text-markdown-html-and-svg)), text pasted from other programs, and Find & Replace (it works on the text cells hold, numbers with a point).

### Dark mode

Expand Down
Loading