Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
4caec8d
feat(i18n): reconstruct PR6 on main and address locale review
mkroemer Nov 18, 2026
5f63b6d
fix(i18n): preserve defaults and complete clipboard localization
mkroemer Nov 18, 2026
551835d
feat(viewer): replaceable UI components for toolbars and dialogs
markus-kroemer Nov 14, 2026
6181f90
style(viewer): a space between JSX attributes
markus-kroemer Nov 14, 2026
7b79989
fix(viewer): preserve dialog actions and host toolbar layout
mkroemer Nov 17, 2026
8409cf9
fix(ui): measure host controls and preserve prompt and portal actions
mkroemer Nov 18, 2026
695d0ce
fix(ui): inherit nested provider strings and defined components
mkroemer Nov 18, 2026
aedfd2b
test(ui): verify rebuilt provider semantics against production ESM
mkroemer Nov 18, 2026
b24e0a4
fix(ui): retain PR6 string table keys for host compatibility
mkroemer Nov 18, 2026
9f71702
test(ui): require fresh emitted packages for browser coverage
mkroemer Nov 18, 2026
b4d8c85
test(ui): inspect parsed controls instead of serialized markup
mkroemer Nov 18, 2026
d320146
feat(viewer): formatting state and commands through the controller
markus-kroemer Nov 14, 2026
ce01a8f
audit: adapt PR9 format tests to accepted PR8 opt-in controller fixture
mkroemer Nov 17, 2026
8ec37cf
feat(viewer): headless mode and a controller for host-drawn controls
markus-kroemer Nov 14, 2026
86e840a
Fix controller formatting targets, ownership and size validation
mkroemer Nov 17, 2026
8828d77
fix(viewer): preserve controller ownership and enforce action permiss…
mkroemer Nov 17, 2026
6fb537d
fix(viewer): validate converted font-size units before formatting
mkroemer Nov 17, 2026
384677a
fix(xlsx): guard async history publication (#20)
mkroemer Nov 17, 2026
ae8ea01
fix(format): validate commands and preserve host editing targets
mkroemer Nov 18, 2026
9df4ad7
fix: scope controller ownership and complete review follow-ups
mkroemer Nov 18, 2026
d67090d
fix(format): commit a size draft once on Enter or blur
mkroemer Nov 18, 2026
e82eeda
test(controller): verify production locale UI and ownership integration
mkroemer Nov 18, 2026
5f0fa0e
test(format): exercise emitted controller edits and save reopen
mkroemer Nov 18, 2026
20befa2
test(controller): enforce the shared production build guard
mkroemer Nov 18, 2026
20368cd
test(format): require fresh production bundles in host edit tests
mkroemer Nov 18, 2026
e21a9fb
fix(i18n): remove unused toolbar label as reviewed
mkroemer Nov 18, 2026
74d0aa7
docs(controller): clarify mounted viewer ownership and icons
mkroemer Nov 18, 2026
d3dddfe
fix(format): retain logical selections for focused host controls
mkroemer Nov 18, 2026
3422d32
fix(collab): preserve host formatting targets across peer edits
mkroemer Nov 18, 2026
43a5d0e
Merge upstream main (v0.16.0) into ui-strings
markus-kroemer Nov 19, 2026
3a261d7
Merge ui-strings (upstream v0.16.0) into ui-primitives
markus-kroemer Nov 19, 2026
d857fe5
Merge ui-primitives (upstream v0.16.0) into ui-controller
markus-kroemer Nov 19, 2026
a7cf341
Merge ui-controller (upstream v0.16.0) into ui-controller-format
markus-kroemer Nov 19, 2026
04406ad
fix(xlsx): fitting a column after an edit stops once the document is …
markus-kroemer Nov 19, 2026
1086a4f
Merge ui-controller into ui-controller-format: column fit after a clo…
markus-kroemer Nov 19, 2026
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 .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,4 +64,5 @@ jobs:
pip install python-pptx Pillow
python scripts/fixtures.py --large-deck

- run: bun run build
- run: bun run test:e2e
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
- **Translatable UI**: every text of the bars, menus and dialogs from one typed table; only English bundled by default; German available through an optional import with `de-DE` formatting (see [UI texts](docs/api.md#ui-texts)); any text replaceable through `strings`
- **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
208 changes: 206 additions & 2 deletions docs/api.md

Large diffs are not rendered by default.

74 changes: 73 additions & 1 deletion docs/theming.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,9 +69,81 @@ gives the class name and style their root needs:

```tsx
const root = useThemeRoot(theme)
return <div className={root.className} style={root.style}><XlsxView client={client} /></div>
return (
<OfficeUIProvider icons={icons} components={components} locale="de-DE">
<div className={root.className} style={root.style}><XlsxView client={client} /></div>
</OfficeUIProvider>
)
```

`OfficeUIProvider` carries what `DocViewer` takes as `icons`, `components`, `locale` and `strings` to views mounted on
their own. Nested providers inherit the outer texts, icons and components. Local `strings` merge key by key;
an explicit `locale` changes number/date formatting while preserving the inherited texts. Omitted or `undefined`
components and string entries preserve the outer values.

## Your own components

Where tokens are not enough, the toolbars and dialogs render the host's own components: a design system's buttons,
selects and dialogs instead of the built-in ones. Each one left out keeps the built-in one.

```tsx
import { DocViewer, type ButtonProps, type UIComponents } from '@p10node/office-engine'

// Define component types outside the host's render so toolbar controls stay mounted.
function ViewerButton({ title, icon, label, children, active, expanded, disabled, onClick, onMouseDown }: ButtonProps) {
return (
<MyIconButton tooltip={title} aria-label={title} pressed={active} aria-expanded={expanded}
disabled={disabled} onClick={onClick} onMouseDown={onMouseDown}>
{icon}{label}{children}
</MyIconButton>
)
}

function ViewerSeparator() {
return <MyDivider vertical />
}

const components: Partial<UIComponents> = { Button: ViewerButton, Separator: ViewerSeparator }

<DocViewer
src={file}
editable
components={components}
/>
```

| Component | Used for | Props |
| ----------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Button` | every toolbar button, the toggles that open color, table and border pickers, the overflow button | `ButtonProps`: `title`, `icon` (resolved through `icons`), `iconName`, `label`, `children`, `active`, `expanded`, `disabled`, `wide`, `onClick`, `onMouseDown`, `className` (the built-in classes) |
| `Select` | font, style, format and menu dropdowns | `SelectProps`: `title`, `options` (`DropOption`: `value`, `label`, `hint`, `icon`, `disabled`, `sep`, `head`, `style`), `value` (undefined for a command menu), `onChange`, `label` (`null` hides the label for an icon-only trigger), `icon` (an `IconName`, not a resolved node), `className` (extra trigger class), `placeholder`, `width`, `menuWidth`, `disabled`, `alignRight` |
| `Separator` | between toolbar groups | none |
| `Dialog` | prompts (link, rename, …) and confirmations | `DialogProps`: `title`, `kind` (`'alert'` for a question), `children` (the body), `actions` (`label`, `onClick`, `extra` for an auxiliary action such as Remove link, `primary`, `submit`, `autoFocus`), `onSubmit` (the body is a form), `onClose` (Escape, backdrop) |
| `Toast` | short messages at the bottom | `text` (the viewer removes it after a few seconds) |

The font-size input and its list (`SizeBox`), Page setup, Header / footer and Details dialogs, and the buttons
inside border pickers retain the built-in markup. `components` replaces the controls listed above.

A host Dialog can put its footer outside the form: call the action's `onClick` from a regular button. Inside
a form, render `submit` actions as submit buttons and let `onSubmit` run them; do not also call their `onClick`,
which would submit twice. Keep `onClick` for the other actions.

The document must keep the focus while a toolbar control is used, or the command loses its selection:

- `Button`: pass `onMouseDown` to the element. It prevents the default, which keeps the focus.
- `Select`: open on mouse down with the default prevented, and handle its keys without moving the focus into the list.
The built-in one captures the keys at the window while open.

The overflow menu measures each toolbar item from a wrapper of its own, so a host component needs no ref.
It measures the More button in the same pass and remeasures when Button, Select or Separator is replaced.

Host Select lists rendered with React's `createPortal` remain inside their surrounding overflow menu or popover
for outside-click handling. The portal must belong to the same React tree as the Select. An independently
mounted React root or a non-React overlay has no such ownership path; render that list inside the Select's DOM
subtree instead.

A host `Select` can render its trigger and option icons with the exported `Icon`: `<Icon name={option.icon} size={16} />`
(when `option.icon` is set). It uses the viewer's `icons` overrides and falls back to the built-in SVGs.

## Tokens

| Group | Tokens |
Expand Down
10 changes: 10 additions & 0 deletions e2e/app/built-locale.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<!doctype html>
<html><head><meta charset="utf-8"></head><body style="margin:0">
<div id="built" style="height:100vh"></div>
<script type="module">
import * as React from 'react'
import { createRoot } from 'react-dom/client'
window.__events = []
window.__builtRuntime = { React, createRoot }
</script>
</body></html>
2 changes: 2 additions & 0 deletions e2e/app/embed.html
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@
<div id="mounted" style="height: 420px"></div>
<script type="module">
import { mount } from '../../src/embed.ts'
import { de } from '../../src/locales/de.ts'
window.__german = de
window.__wcEvents = []
const wc = document.getElementById('wc')
wc.addEventListener('load', (e) => window.__wcEvents.push(e.detail))
Expand Down
87 changes: 83 additions & 4 deletions e2e/app/main.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,35 @@
* ?src=samples/sample.docx&editable=1&allowSave=0&onSave=1&items=1&close=1&collab=ws://…&room=r
* comments: &me=Ann&meId=u1 (author), &people=1 (mentions: Ann, Bob Stone, Cid), &comments=0 (hidden), &cmOpen=1
* &icons=1: every icon from a host resolver, as `<svg data-host-icon={name}>`
* texts: &locale=de-DE opts into the explicitly imported German table, &fileLabel=… overrides the File label
* &components=1: the host's own Button, Separator, Dialog and Toast (`data-host-*` markers)
* &headless=1: the document alone; the viewer is driven through window.__ctl (its controller) either way
*/
import { useState } from 'react'
import { StrictMode, useState } from 'react'
import { createRoot } from 'react-dom/client'
import { DocViewer, type DocViewerProps, type FileMenuItem } from '../../src'
import { createViewerController, useViewerState, DocViewer, type DocViewerProps, type FileMenuItem, type UIComponents, type ViewerController } from '../../src'
import { de } from '../../src/locales/de'

type Ev = { type: string; [k: string]: unknown }
declare global {
interface Window {
__events: Ev[]
__setProps: (p: Partial<DocViewerProps>) => void
__setLanguage: (language: 'en' | 'de-DE') => void
__german: typeof de
__ctl: ViewerController
__overlap: (phase: number, props?: Partial<DocViewerProps>) => void
}
}
window.__events = []
window.__ctl = createViewerController()
// a host reading the state, as the tests do through snapshot(): views read slide titles only for one
window.__ctl.subscribe(() => {})
const log = (e: Ev) => window.__events.push(e)

const q = new URLSearchParams(location.search)
const flag = (k: string) => (q.has(k) ? q.get(k) !== '0' : undefined)
const texts = q.get('locale') === 'de-DE' || q.get('locale') === 'de' ? de : undefined

async function b64(blob: Blob) {
const bytes = new Uint8Array(await blob.arrayBuffer())
Expand All @@ -33,6 +45,49 @@ const items: FileMenuItem[] = [
{ label: 'Version history', hint: 'beta', onClick: () => log({ type: 'item', label: 'Version history' }) },
]

// plain host components: no engine classes, so nothing of the engine's CSS styles them
const components: Partial<UIComponents> = {
Button: (p) => (
<button type="button" data-host-button="" data-active={p.active || undefined} title={p.title} aria-label={p.title} aria-expanded={p.expanded} disabled={p.disabled} onMouseDown={p.onMouseDown} onClick={p.onClick} style={p.iconName === 'more' ? { width: 140 } : undefined}>
{p.icon}
{p.label}
{p.children}
</button>
),
Separator: () => <i data-host-sep="" />,
Dialog: (p) => {
const actions = p.actions.map((a, i) => (
<button key={i} type={a.submit ? 'submit' : 'button'} data-primary={a.primary || undefined} autoFocus={a.autoFocus} onClick={a.submit && p.onSubmit ? undefined : a.onClick}>
{a.label}
</button>
))
const body = (
<>
<h2>{p.title}</h2>
{p.children}
{actions}
</>
)
return (
<div data-host-dialog="" role={p.kind === 'alert' ? 'alertdialog' : 'dialog'} aria-label={p.title} onKeyDown={(e) => e.key === 'Escape' && p.onClose()}>
{p.onSubmit ? (
<form
onSubmit={(e) => {
e.preventDefault()
p.onSubmit!()
}}
>
{body}
</form>
) : (
body
)}
</div>
)
},
Toast: ({ text }) => <output data-host-toast="">{text}</output>,
}

const initial: DocViewerProps = {
src: q.get('src'),
name: q.get('name') ?? undefined,
Expand All @@ -48,6 +103,10 @@ const initial: DocViewerProps = {
captureSelectAll: flag('captureSelectAll'),
theme: (q.get('theme') as DocViewerProps['theme']) ?? undefined,
injectStyles: flag('injectStyles'),
locale: (texts ? undefined : q.get('locale') as DocViewerProps['locale']) ?? undefined,
strings: q.has('fileLabel') ? { ...texts, file: { ...(texts?.file ?? {}), menu: q.get('fileLabel')! } } : texts,
headless: flag('headless'),
controller: flag('controller') ? window.__ctl : undefined,
onSave: q.has('onSave') ? async (blob, name) => void log({ type: 'save', name, b64: await b64(blob) }) : undefined,
onDirtyChange: (dirty) => log({ type: 'dirty', dirty }),
onRename: (name) => log({ type: 'rename', name }),
Expand All @@ -64,6 +123,7 @@ const initial: DocViewerProps = {
open: flag('cmOpen'),
onEvent: (e) => log({ type: 'comment', action: e.type, id: e.comment.id, text: e.comment.text, thread: e.thread.id, quote: e.quote, mentioned: e.mentioned.map((m) => m.id ?? m.name), participants: e.participants.map((m) => m.id ?? m.name) }),
},
components: q.has('components') ? components : undefined,
icons: q.has('icons')
? (name) => (
<svg data-host-icon={name} viewBox="0 0 24 24">
Expand All @@ -74,10 +134,29 @@ const initial: DocViewerProps = {
collab: q.get('collab') ? { transport: q.get('collab')!, room: q.get('room') ?? 'e2e', base: Number(q.get('base')) || 0, user: { name: q.get('user') ?? 'Tester' } } : undefined,
}

function RenderingHost({ props }: { props: DocViewerProps }) {
const f = useViewerState(window.__ctl).format
return <><input aria-label="React host size" type="number" disabled={!f} defaultValue="" onChange={(e) => window.__ctl.format({ op: 'size', pt: e.currentTarget.valueAsNumber })} />
<DocViewer {...props} onSave={async (blob, name) => { log({ type: 'save', name, b64: await b64(blob) }) }} /></>
}

function App() {
const [props, setProps] = useState(initial)
const [phase, setPhase] = useState(0)
const [nextProps, setNextProps] = useState<Partial<DocViewerProps>>({})
window.__overlap = (phase, next) => {
if (next) setNextProps(next)
setPhase(phase)
}
window.__setProps = (p) => setProps((cur) => ({ ...cur, ...p }))
return <DocViewer {...props} />
window.__setLanguage = (language) => setProps((cur) => ({ ...cur, strings: language === 'de-DE' ? de : undefined }))
const { undo, redo } = window.__ctl
if (q.has('renderHost')) return <RenderingHost props={props} />
return <>
{q.has('hostControls') && <div><button onClick={undo}>Host undo</button><button onClick={redo}>Host redo</button><button onMouseDown={(e) => e.preventDefault()} onClick={() => window.__ctl.goto(window.__ctl.snapshot().outline!.items[1].id)}>Host second sheet</button></div>}
{phase < 2 && <DocViewer key="old" {...props} />}
{phase > 0 && phase < 3 && <DocViewer key="new" {...props} {...nextProps} />}
</>
}

createRoot(document.getElementById('root')!).render(<App />)
createRoot(document.getElementById('root')!).render(q.has('strict') ? <StrictMode><App /></StrictMode> : <App />)
5 changes: 5 additions & 0 deletions e2e/app/ui.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<!doctype html>
<html lang="en">
<head><meta charset="utf-8" /><title>UI regression fixture</title></head>
<body><div id="root"></div><script type="module" src="./ui.tsx"></script></body>
</html>
53 changes: 53 additions & 0 deletions e2e/app/ui.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import { useEffect, useState } from 'react'
import { createRoot } from 'react-dom/client'
import { createPortal } from 'react-dom'
import { PromptDialog } from '../../src/react/common/Dialog'
import { Btn, Dropdown, Pop, ToolbarRow } from '../../src/react/edit/Toolbar'
import { OfficeUIProvider, type ButtonProps, type DialogProps, type SelectProps } from '../../src/react/ui'
import '../../src/react/styles.css'

window.__events = []
const noop = () => {}
function Button(p: ButtonProps) {
return <button type="button" aria-label={p.title} onClick={p.onClick} onMouseDown={p.onMouseDown} style={p.iconName === 'more' ? undefined : { width: 34 }}> {p.iconName === 'more' ? 'More tools' : p.title} </button>
}
function WideButton(p: ButtonProps) {
return <span style={{ display: 'inline-flex', padding: '0 20px' }}><Button {...p} /></span>
}
function DelayedDialog(p: DialogProps) {
const [ready, setReady] = useState(false)
useEffect(() => setReady(true), [])
return <section role="dialog" aria-label={p.title}>
<form onSubmit={(e) => { e.preventDefault(); p.onSubmit?.() }}>{ready && p.children}<button hidden type="submit" /></form>
<footer>{p.actions.map((a) => <button key={a.label} type="button" onClick={a.onClick}>{a.label}</button>)}</footer>
</section>
}
function PortalSelect(p: SelectProps) {
const [open, setOpen] = useState(false)
return <>
<button type="button" aria-label={p.title} onMouseDown={(e) => e.preventDefault()} onClick={() => setOpen((v) => !v)}>{p.title}</button>
{open && createPortal(<div role="listbox" aria-label={p.title} style={{ position: 'fixed', top: 300, left: 10 }}>
{p.options.map((o) => <button key={o.value} role="option" type="button" onMouseDown={(e) => e.preventDefault()} onClick={() => { p.onChange(o.value); setOpen(false) }}>{o.label}</button>)}
</div>, document.body)}
</>
}
const picker = (title: string) => <Dropdown title={title} options={[{ value: 'chosen', label: 'Choose option' }]} onChange={(value) => window.__events.push({ type: 'pick', value, title })} />
function App() {
const [wide, setWide] = useState(false)
const [tick, setTick] = useState(0)
return <OfficeUIProvider components={{ Button: wide ? WideButton : Button, Dialog: new URLSearchParams(location.search).has('defaultDialog') ? undefined : DelayedDialog, Select: PortalSelect }}>
<div className="de-root" style={{ width: 616 }}>
<button onClick={() => setWide((v) => !v)}>Replace components</button>
<button onClick={() => setTick((n) => n + 1)}>Rerender {tick}</button>
<button onMouseDown={(e) => e.stopPropagation()}>Outside with stopped propagation</button>
<ToolbarRow>{Array.from({ length: 17 }, (_, i) => <Btn key={i} title={String(i)} label={String(i)} onClick={noop} />)}</ToolbarRow>
<div data-portal-overflow="" style={{ width: 180 }}><ToolbarRow>
{Array.from({ length: 8 }, (_, i) => <Btn key={i} title={String(i)} label={String(i)} onClick={noop} />)}
{picker('Overflow picker')}
</ToolbarRow></div>
<Pop title="Open popover" icon="table">{() => picker('Popover picker')}</Pop>
<PromptDialog spec={{ title: 'Rename', initial: 'Report', onOk: (value) => window.__events.push({ type: 'submit', value }) }} onClose={() => window.__events.push({ type: 'close' })} />
</div>
</OfficeUIProvider>
}
createRoot(document.getElementById('root')!).render(<App />)
Loading