Skip to content

feat(viewer): replaceable UI components for toolbars and dialogs - #7

Open
mkroemer wants to merge 5 commits into
p10node:mainfrom
mkroemer:ui-primitives
Open

mkroemer wants to merge 5 commits into
p10node:mainfrom
mkroemer:ui-primitives

Conversation

@mkroemer

Copy link
Copy Markdown
Contributor

Builds on #6 (UI texts), #5 (icons) and #4 (theming). Until those are merged this PR shows their commits too; the components part is the last commit.

This lets a host render the toolbars and dialogs with its own design system's controls, for when design tokens are not enough. Each component a host leaves out keeps the built-in one, whose markup is unchanged.

<DocViewer
  src={file}
  editable
  components={{
    Button: ({ title, icon, label, children, active, expanded, disabled, onClick, onMouseDown }) => (
      <MyIconButton tooltip={title} aria-label={title} pressed={active} aria-expanded={expanded}
        disabled={disabled} onClick={onClick} onMouseDown={onMouseDown}>
        {icon}{label}{children}
      </MyIconButton>
    ),
    Separator: () => <MyDivider vertical />,
  }}
/>

There are five: Button, Select, Separator, Dialog and Toast, with typed props (ButtonProps, SelectProps, DialogProps, ToastProps).

  • Every toolbar button goes through Button: the plain buttons, the toggles that open the color, table and border pickers, the overflow button and the font size steps. The dropdowns go through Select.
  • PromptDialog and ConfirmDialog build their body and actions and render them through Dialog; Toast keeps its timer and renders through Toast.
  • components is a prop of DocViewer, and UIComponentsProvider gives it to views mounted on their own. OfficeUIProvider carries icons, components, locale and strings in one provider.
  • The overflow menu measures each toolbar item from a wrapper of its own, so a host component needs no ref.
  • The overflow button's title is now its accessible name ("More tools"), so the unused "More" text is gone from the strings table.

The one thing a host component has to get right is the focus: the document must keep it while a toolbar control is used, or the command loses its selection. docs/theming.md ("Your own components") says how, for Button (pass onMouseDown on) and Select (open on mouse down, handle keys without focusing the list), and lists every prop.

test/ui.test.tsx covers each component and nested providers. e2e/components.spec.ts runs the viewer with host components: the toolbar renders them, formatting through a host button keeps the selection, the overflow menu still works at a narrow width, and the link prompt opens and submits through a host dialog. bun run typecheck, bun test and the e2e suite pass in CI.

🤖 Generated with Claude Code

markus-kroemer and others added 3 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>

@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.

Thank you, the five components are a sensible set and the built-in markup is otherwise unchanged.

One regression for hosts that pass no components, so I can't merge it yet:

  • DefaultDialog (src/react/ui.tsx:124) no longer puts de-dialog-extra on the prompt's extra button, and DialogAction has no field for it. .de-dialog-extra { margin-right: auto } is dead, so "Remove link" in the edit-link prompt moves from the left edge to beside Cancel / OK. The "built-in markup is unchanged" test in test/ui.test.tsx leaves the dialogs out, so nothing catches it. Please restore the class (an extra flag on DialogAction would do) and add the dialogs to that test.

Non-blocking:

  • A host Select gets IconNames in its options, but Icon is not exported, so it cannot draw the built-in icons.
  • docs/theming.md defines Button and Separator inline in JSX, which remounts every toolbar button on each host render. Please hoist them in the example.

@mkroemer

Copy link
Copy Markdown
Contributor Author
  • Restored de-dialog-extra through DialogAction.extra, with regression coverage for action order, styling, and link removal.
  • Exported Icon so host Select components can render option icons using host overrides or built-in fallbacks.
  • Hoisted custom component definitions in docs/theming.md to avoid remounting controls on each host render.

I also found that toolbar overflow reserved a fixed 34px for “More tools,” which could clip wider host buttons. It now measures the rendered button’s width, with regression coverage.

Verification: 553 unit tests, typecheck, library/SDK builds, package checks, and the full CI browser suite pass. Current main is merged.

@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, all three points are done: de-dialog-extra is back through DialogAction.extra and the dialogs are in the markup test, Icon is exported, and the docs example is hoisted.

Two things in the new code (line numbers are at 8fa9681):

  1. src/react/edit/Toolbar.tsx:615: the More wrapper is measured after the row has already squeezed it, because .de-ebar-morewrap (styles.css:686) can shrink. Host More button <button>More tools</button>, 600px row, 17 items: in Chromium the wrapper is squeezed to 56px (natural width 78px), the effect stores 56, the cut stays the same and the label wraps. The e2e fixture gives the button a fixed width: 140, which cannot shrink, so the test passes. flex: none on the wrapper fixes it.
  2. src/react/common/Dialog.tsx:48: the prompt's primary action is { primary: true, submit: true } with no onClick. It only works when the host renders it as a submit button inside a form. A host Dialog that puts actions in a footer outside the form (MUI DialogActions, a Radix footer) gets an OK button that does nothing. Giving the action onClick: done, and skipping onClick for submit buttons in DefaultDialog, covers both.

It also needs a rebase onto main (conflicts in docs/api.md and src/react/DocViewer.tsx), and at its current head it conflicts with #6 in four files. See my note on #9 about the order of the stack.

Non-blocking:

  • The overflow effect has no deps and calls getBoundingClientRect() on every toolbar render. It also changes the built-in toolbar: the reserve was 34 and the built-in wrapper measures 28, so one more item can fit and the slack is gone. Rendering More in the measuring pass and measuring it with the items needs no guess and no second effect.
  • Item widths are cached by sig (type name and title), which does not change when components does, for example through mount().update({ components }). The cut is then computed from the old widths.
  • A host Select that portals its list cannot be used inside the overflow popover or a Pop: useDismiss (Toolbar.tsx:239) checks DOM containment, so the popover closes on mousedown and onChange never fires. That deserves a line in the docs at least.
  • Dialog.tsx:25: PromptDialog focuses and selects its input in a mount-only effect. With a host Dialog that mounts its children one pass later, nothing is focused and the rename text is not preselected. A callback ref would do.
  • SelectProps.icon is an IconName string while ButtonProps.icon is a node, and the docs table for Select leaves out icon, className and what label: null means. A host that writes {p.icon}{p.label} as for Button shows the literal name.
  • docs/theming.md:113 says the size list goes through Select, but SizeBox has its own listbox. The Page setup, Header / footer and Details dialogs and the border-picker buttons keep the built-in markup as well.
  • src/react/ui.tsx:106: a nested OfficeUIProvider without locale resets the texts to English, while icons and components merge with the outer one. And { ...outer, ...components } lets an explicit undefined erase the outer component.
  • docs/theming.md:110: the new table is not column-aligned.

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