Skip to content

feat(viewer): ready-made controls for a headless viewer - #10

Open
mkroemer wants to merge 83 commits into
p10node:mainfrom
mkroemer:ui-controller-controls
Open

mkroemer wants to merge 83 commits into
p10node:mainfrom
mkroemer:ui-controller-controls

Conversation

@mkroemer

Copy link
Copy Markdown
Contributor

Builds on the formatting PR (#9) and #8. Until those are merged this PR shows their commits too; the controls part is the last commit.

For a host that wants the engine's controls, but in its own layout around a headless viewer:

const ctl = createViewerController()

<header><ZoomBar controller={ctl} /><FormatBar controller={ctl} /><StatusText controller={ctl} /></header>
<aside><OutlineList controller={ctl} /></aside>
<DocViewer src={file} controller={ctl} headless />
<footer><SheetTabs controller={ctl} /></footer>

ZoomBar, StatusText, OutlineList (headings, sheets or slides), SheetTabs and FormatBar are each driven by the controller alone. They render through the host's components, icons, texts and design tokens like the built-in toolbars (OfficeUIProvider and useThemeRoot outside DocViewer). The views and their built-in chrome are unchanged.

A container of controls gets useThemeRoot(theme, style, { host: true }): sized by its content, not clipping, and stacked above the viewer that follows, so the format bar's size list and overflow menu are not cut off. SheetTabs keeps the focus in the grid, so a formula being typed stays open on the sheet switched to and can point at its cells, as with the built-in tabs.

docs/api.md has a "Ready-made controls" section under headless mode. e2e/chrome.spec.ts mounts them around a headless viewer: status, zoom and the headings outline follow and drive a DOCX, the format bar bolds the selection, sheet tabs switch sheets, and a cross-sheet reference typed across a tab switch. bun run typecheck, bun test and the e2e suite pass in CI.

🤖 Generated with Claude Code

markus-kroemer and others added 9 commits November 14, 2026 21:59
…s props

The viewer's texts come from one typed table, `Strings` (src/react/strings/en.ts),
with a complete German table next to it (de.ts, Swiss spelling, Word / Excel /
PowerPoint terms). `DocViewer`, `mount()` and `<office-viewer>` take `locale`
('en' | 'de', default 'en') and `strings`, a partial table merged over the
locale key by key; `StringsProvider` / `useStrings()` give standalone views the
same texts. Numbers and dates in the UI go through Intl with the table's locale;
the English output is unchanged.

This change converts the top bar, the details rows, the common dialogs, the
zoom control, the shared toolbar controls, the source pane and the picture view.
The shared groups (`edit`, `find`, `table`, `format`) are in the table already,
so the document, sheet and slide views can be converted in separate changes.

A unit test checks that every locale has all keys of `en`, no empty text and no
sharp s in German.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A host can render its own Button, Select, Separator, Dialog and Toast in the
engine's toolbars and dialogs (`components` prop, UIComponentsProvider), for
a design system's controls where design tokens are not enough. Each one left
out keeps the built-in one, whose markup is unchanged.

- every toolbar button goes through Button: Btn, the color, picker and
  overflow toggles, the font size steps; Dropdown/Select through Select
- PromptDialog and ConfirmDialog build their actions and body and render
  them through Dialog; Toast keeps its timer and renders through Toast
- OfficeUIProvider carries icons, components, locale and strings to views
  mounted without DocViewer
- the overflow button's title is its accessible name ("More tools"), so the
  unused "More" text goes
- docs/theming.md "Your own components"; unit tests for each component and
  nested providers; e2e with host components: toolbar, formatting keeps the
  selection, overflow at a narrow width, the link prompt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…xts from the strings table

The document view's status line, toolbar, context menu, outline, find bar, page setup and header / footer dialogs and the tracked-change tooltips take their texts from the docx, pageSetup and headerFooter groups. The Page 1 of 5 footer preset inserts its text in the UI's language. e2e/locale-docx.spec.ts checks the German texts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s from the strings table

The sheet view's status line, document details, sheet tabs, context menu, find options, print notice and the toolbar (number formats, borders, merge, alignment, rotation, rows, functions, sort, view) take their texts from the xlsx group. Number format previews stay as they are. e2e/locale-xlsx.spec.ts checks the German texts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…heir texts from the strings table

The slide view's toolbar, shape and slide menus, status line and present button, the comments panel and its notices, the File menu, the details dialog, the unsupported-file message and the collaboration chip take their texts from the pptx, comments, file and collab groups. The empty text box placeholder is a data-placeholder attribute shown through attr(), so it follows the locale. e2e/locale.spec.ts checks the German bar, File menu, details dialog and slide view, a partial override and the English default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A host that draws its own controls around the document gets
`<DocViewer controller={createViewerController()} headless />`.
`headless` leaves the viewer with the document alone: no top bar, zoom
control, outline panel or button, sheet tabs, slide list or Present
button. While editing, the formatting toolbar keeps its row, and an
explicit `toolbar` brings back the top bar (File menu, comments, Save).

The controller (src/react/controller.ts, framework-free) holds the
state - kind, loading, editing, canEdit, dirty, saving, canUndo/canRedo,
zoom, page, outline (headings, sheets or slides), status - and runs the
commands: setEditing, save, undo, redo, zoomIn/zoomOut/setZoom, goto,
gotoPage, present, print, fileAction, toggleComments. The viewer and its
mounted view publish to it and register their commands; without one from
the host the viewer keeps its own, so nothing else changes. When the
viewer or its view unmounts, its part of the state is cleared, so a
controller that outlives it shows no document.
`useViewerState(ctl)` reads the state in React.

- DOCX: headings are read for the controller whether or not the outline
  panel is open (once edits rest), with the current one, which stays the
  heading jumped to while its page is in view; DocxEditor reports its
  undo/redo history after each step, offered only while editing.
- XLSX: the visible sheets as the outline; undo/redo counted per edit,
  cleared when a sheet is added, deleted, moved, renamed or imported, as
  the worker's history is. A sheet switched to through the controller
  keeps a formula being typed open, for cross-sheet references, as the
  built-in tabs do.
- PPTX: slides titled by their title placeholder, read by a title-only
  worker call (`pptx.titles`, no layout) only while a host subscribes
  (`observed`, `watchObserved`), and kept current as slides are edited;
  symbol-font characters in titles as their Unicode look-alikes. Undo and
  redo through the controller do nothing outside edit mode.
- `onLoad` fires once per opened document, also with an inline callback.
- mount() returns the controller; <office-viewer headless> has .controller.
- e2e harness: PLAYWRIGHT_CHANNEL picks an installed browser.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
One formatting API for documents, cells and slide text, so a host can draw
its own formatting toolbar: `ViewerState.format` (a TextFormat: bold,
italic, underline, strike, font, size, color, highlight, align, list) and
`ViewerController.format(command)`.

- DocxEditor and PptxEditor publish their formatting state to subscribers
  (`subscribeState`) beside the toolbar's `onState`; a subscriber hears the
  current state at once, so a controller attached while text is selected
  reports its format without waiting for the selection to change
- src/react/edit/format.ts maps the editors' states and the active cell's
  CSS to TextFormat and commands to editor calls or cell format patches
- the format is null while viewing, and in a presentation unless text is
  being edited; a command a kind has no use for does nothing
- spreadsheet undo, redo and format commands through the controller run
  only while editing, and canUndo / canRedo follow the editing state
- docs: "Formatting" under headless mode; unit tests for the mappings;
  e2e: bold and size through the controller in a document (saved), bold
  and fill on a cell, and an undo while viewing that leaves the cell as is

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ZoomBar, StatusText, OutlineList, SheetTabs and FormatBar, each driven by a
ViewerController alone, so a host gets the viewer's controls in a layout of
its own around `<DocViewer controller={ctl} headless />`. They render
through the host's components, icons, texts and design tokens like the
built-in toolbars (OfficeUIProvider and useThemeRoot outside DocViewer).
The views and their built-in chrome are unchanged.

A container of controls gets useThemeRoot(theme, style, { host: true }):
sized by its content, not clipping, and stacked above the viewer that
follows, so the format bar's size list and overflow menu are not cut off.

- docs: "Ready-made controls" under headless mode
- e2e (chrome.spec.ts, `chrome` flag in the fixture): status, zoom and the
  headings outline follow and drive a DOCX; the format bar bolds the
  selection; sheet tabs switch sheets, and keep a formula being typed
  open, like the built-in tabs, for a reference to another sheet

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@pierreneter pierreneter left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for rounding the headless work off with ready-made controls.

Two behaviours to fix first:

  1. SheetTabs always prevents mousedown (src/react/chrome.tsx:67); the built-in tabs do that only while a formula that can take a reference is being typed. Type hello in J12 without Enter, click another tab: the edit stays open on the other sheet, and the next cell click commits the text to the first sheet and jumps back to it. Please use the same condition as the built-in tabs.
  2. The FormatBar size box cannot be typed into (src/react/chrome.tsx:106): clicking the input makes format null, so the input is disabled and the list closes; typing 20 and Enter leaves the size as it was. The built-in toolbar has the same flaw, so it is not new, but I'd rather not ship it in a new public control. e2e/chrome.spec.ts:44-53 asserts on that list just before it closes and never picks a size.

Non-blocking: FormatBar takes no className / style unlike the other four, and the justify and list buttons disappear whenever format is null, so the bar reflows on every focus loss.

This also needs #8 fixed before it can merge.

mkroemer and others added 18 commits November 18, 2026 21:04
A host can render its own Button, Select, Separator, Dialog and Toast in the
engine's toolbars and dialogs (`components` prop, UIComponentsProvider), for
a design system's controls where design tokens are not enough. Each one left
out keeps the built-in one, whose markup is unchanged.

- every toolbar button goes through Button: Btn, the color, picker and
  overflow toggles, the font size steps; Dropdown/Select through Select
- PromptDialog and ConfirmDialog build their actions and body and render
  them through Dialog; Toast keeps its timer and renders through Toast
- OfficeUIProvider carries icons, components, locale and strings to views
  mounted without DocViewer
- the overflow button's title is its accessible name ("More tools"), so the
  unused "More" text goes
- docs/theming.md "Your own components"; unit tests for each component and
  nested providers; e2e with host components: toolbar, formatting keeps the
  selection, overflow at a narrow width, the link prompt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
One formatting API for documents, cells and slide text, so a host can draw
its own formatting toolbar: `ViewerState.format` (a TextFormat: bold,
italic, underline, strike, font, size, color, highlight, align, list) and
`ViewerController.format(command)`.

- DocxEditor and PptxEditor publish their formatting state to subscribers
  (`subscribeState`) beside the toolbar's `onState`; a subscriber hears the
  current state at once, so a controller attached while text is selected
  reports its format without waiting for the selection to change
- src/react/edit/format.ts maps the editors' states and the active cell's
  CSS to TextFormat and commands to editor calls or cell format patches
- the format is null while viewing, and in a presentation unless text is
  being edited; a command a kind has no use for does nothing
- spreadsheet undo, redo and format commands through the controller run
  only while editing, and canUndo / canRedo follow the editing state
- docs: "Formatting" under headless mode; unit tests for the mappings;
  e2e: bold and size through the controller in a document (saved), bold
  and fill on a cell, and an undo while viewing that leaves the cell as is

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A host that draws its own controls around the document gets
`<DocViewer controller={createViewerController()} headless />`.
`headless` leaves the viewer with the document alone: no top bar, zoom
control, outline panel or button, sheet tabs, slide list or Present
button. While editing, the formatting toolbar keeps its row, and an
explicit `toolbar` brings back the top bar (File menu, comments, Save).

The controller (src/react/controller.ts, framework-free) holds the
state - kind, loading, editing, canEdit, dirty, saving, canUndo/canRedo,
zoom, page, outline (headings, sheets or slides), status - and runs the
commands: setEditing, save, undo, redo, zoomIn/zoomOut/setZoom, goto,
gotoPage, present, print, fileAction, toggleComments. The viewer and its
mounted view publish to it and register their commands; without one from
the host the viewer keeps its own, so nothing else changes. When the
viewer or its view unmounts, its part of the state is cleared, so a
controller that outlives it shows no document.
`useViewerState(ctl)` reads the state in React.

- DOCX: headings are read for the controller whether or not the outline
  panel is open (once edits rest), with the current one, which stays the
  heading jumped to while its page is in view; DocxEditor reports its
  undo/redo history after each step, offered only while editing.
- XLSX: the visible sheets as the outline; undo/redo counted per edit,
  cleared when a sheet is added, deleted, moved, renamed or imported, as
  the worker's history is. A sheet switched to through the controller
  keeps a formula being typed open, for cross-sheet references, as the
  built-in tabs do.
- PPTX: slides titled by their title placeholder, read by a title-only
  worker call (`pptx.titles`, no layout) only while a host subscribes
  (`observed`, `watchObserved`), and kept current as slides are edited;
  symbol-font characters in titles as their Unicode look-alikes. Undo and
  redo through the controller do nothing outside edit mode.
- `onLoad` fires once per opened document, also with an inline callback.
- mount() returns the controller; <office-viewer headless> has .controller.
- e2e harness: PLAYWRIGHT_CHANNEL picks an installed browser.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mkroemer and others added 18 commits November 20, 2026 08:19
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d lists

- SheetTabs keeps the grid's focus only while a formula being typed can
  take a reference, as the built-in tabs do; other text being typed is
  committed by the click on its own sheet. The view publishes that as the
  controller's new `pointing` state.
- FormatBar's list buttons remove a list when they show as pressed,
  since the list command is now a setter.
- FormatBar takes className and style like the other controls, and keeps
  its buttons in place, disabled, while there is nothing to format, so it
  keeps its width as the focus moves.
- Browser tests: text committed on its own sheet, a list removed, and a
  size typed and entered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d open

OutlineList lists a workbook's sheets too; it takes the grid's focus only when no formula can take a reference, as SheetTabs does. The cross-sheet formula test runs through both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…o outline in headless mode

- Spreadsheet edit results now carry the worker's own undo / redo count
  (`history`). An edit that changes nothing (sorting sorted rows) records
  no step, so counting results made the controller offer undo where there
  was none and drop a redo that was still there. The count stays as the
  fallback for results without it.
- The heading jumped to in a document stays current only until the caret
  goes somewhere else on that page.
- An outline panel open when the viewer turns headless is no longer shown.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…g jumps, headless outline

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… as the toolbar does

A selection made by a row or column header (or of the whole sheet) is
formatted through the controller over its full extent, as the built-in
toolbar formats it, so cells typed there later have the format; before,
only the cells in use got it. The rows and columns are also fitted after
a wrap or number format, as from the toolbar. The grid does not take the
focus from the host's control.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…from #8 and #9

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- After select-all in a long document, a host control formats the whole
  document: the target is the select-all, not the paragraphs shown.
- An edit from a host's control (a list, alignment or clear button) keeps
  the focus there also when its converted paragraphs come back from the
  worker and put the caret back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The outline's slide titles are read once from the file; a title edited while that read runs is newer than its answer, which no longer overwrites it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e scan

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… pass of #8 and #9

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…collaborators

- A host's format commands sent faster than the worker answers go by what
  the earlier ones left: two bold toggles cancel out instead of applying
  bold twice, and a toggle right after clear starts from the cleared
  marks.
- A select-all held while a host's control has the focus stays the whole
  document when a collaborator edits it, instead of shrinking to the
  pages that were shown.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pass of #9

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The format remembered for commands sent faster than the worker answers is dropped for good once the cell's own format has changed, and by undo and redo; an undo that brought back the format it was read from made it count again, so the next toggle did nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…after undo

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…l unanswered

The marks worked out for commands sent faster than the cell shows them are kept while any command is unanswered and until the cell shows those marks, instead of being dropped when the first answer changes the cell; a third quick toggle then starts from the second's result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ggles

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mkroemer

Copy link
Copy Markdown
Contributor Author

Thanks, all fixed:

  1. SheetTabs now prevents mousedown only while a formula being typed can take a reference. The view publishes that as a new controller state, pointing, from the same check the built-in tabs use, and OutlineList uses it too. A new e2e case types hello in J12, clicks another tab, clicks a cell there and checks that J12 on the first sheet shows hello; the =SUM( case now also checks pointing.
  2. The list buttons send null when their list is already on, as the built-in toolbar does. A new case turns a bullet list on and off again.
  3. A new case types 20 into the size box, presses Enter and checks the selection is 20 pt.

Non-blocking ones: FormatBar takes className and style like the other four, and the justify and list buttons stay in place for documents and slides, disabled while there is nothing to format, so the bar keeps its width.

The branch now has #9's current head merged in, including the fixes from the latest round on #8 and #9. I merged rather than rebased so the commits you reviewed keep their hashes, which is also why the two "ready-made controls" commits are still separate. I can squash them before merging if you prefer.

mkroemer and others added 10 commits November 20, 2026 12:44
A formatting command does nothing on a selection that spans a table, and
the sample document has one, so the case could not pass: select-all and
bold left the document as it was. It now replaces the sample with 151
plain paragraphs over several pages, checks that the far pages are not
rendered, and that every paragraph is bold after the host control.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Enter and Escape blurred the box, which left the focus on the page body:
the document lost its selection, so the format bar showed nothing and
was disabled right after setting the size. The box now gives the focus
back to the element it took it from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…l test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…st diagnostics

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A held select-all was dropped as soon as the DOM selection differed from
the one select-all set. The pages rendered around the caret change as
the view re-renders, which moves the DOM selection without the user, so
formatting with a host control then reached only the rendered pages.
It now holds until a click or a key press other than select-all itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ion"

This reverts commit f7c6096. A trace from CI showed the select-all was
not dropped by a selection change after a re-render, as that commit
assumed, but by restore(); the next commit fixes that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ect-all

An edit the worker reports after a select-all rebuilds its paragraph, and
the view then restores the selection around it. restore() dropped the
held select-all on any call, so a host control formatted only the pages
shown. A trace from CI showed this order. restore() now keeps the
select-all when it is handed the selection the select-all holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pt on restore

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mkroemer

Copy link
Copy Markdown
Contributor Author

Correction to my last comment: "all fixed" was premature, two of the new browser tests failed in CI. Both are fixed now and CI is green on #9 and #10.

  • The size box: Enter set the size, but then blurred the box, which left the focus on the page body, so the document lost its selection and the bar went disabled right away. The box now gives the focus back to where it came from (c154f37).
  • The select-all case in feat(viewer): formatting state and commands through the controller #9 could not pass as written: a formatting command does nothing on a selection that spans a table, and sample.docx has one. The test now replaces the sample with plain paragraphs over several pages. With that it showed a real bug: an edit the worker reported after the select-all made the view restore the selection, and restore() dropped the held select-all, so a host control formatted only the rendered pages. restore() now keeps it when it gets back the selection the select-all holds (c6e28fe).

Formatting across a table is a separate, older limitation that this PR doesn't change.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants