docs(custom-ui): cover the controller surface shipped in SD-2936 stack#3173
Merged
caio-pizzol merged 3 commits intomainfrom May 5, 2026
Merged
docs(custom-ui): cover the controller surface shipped in SD-2936 stack#3173caio-pizzol merged 3 commits intomainfrom
caio-pizzol merged 3 commits intomainfrom
Conversation
Brings the Custom UI docs up to parity with what's shipped on
superdoc/ui (SD-2943, SD-2954, SD-2945, SD-2944).
- New editor/custom-ui/context-menu.mdx walks the right-click flow:
disableContextMenu, contextAt({ x, y }), getContextMenuItems(context),
invoke(), predicate examples for entity/selection/click-point.
- selection-and-viewport.mdx expanded for seven previously
undocumented methods: ui.selection.restore (with reason table),
getRects, getAnchorRect, ui.viewport.getHost, entityAt, positionAt,
contextAt.
- custom-commands.mdx: execute now { payload, superdoc, editor, context };
shortcut, contextMenu contribution, commands.has, commands.require
documented.
- api-reference.mdx: new methods + ContextMenuContribution,
ContextMenuWhenInput, ContextMenuItem with invoke,
SelectionAnchorRectOptions, SelectionRestoreResult, ViewportEntityHit,
ViewportPositionHit, ViewportContext.
- overview.mdx: Card for context-menu plus three-surfaces recipe.
- Built-in context-menu page corrects disableContextMenu semantics and
points to the new custom-ui flow.
- navigation.mdx reframed around ui.comments.scrollTo /
trackChanges.scrollTo / viewport.scrollIntoView at the top.
- comments and track-changes cross-link to theming.
- packages/superdoc/AGENTS.md gains a Custom UI (React) section.
Contributor
|
📖 Docs preview: https://superdoc-caio-docs-custom-ui-coverage.mintlify.app |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Four accuracy fixes against the shipped surface:
- packages/superdoc/AGENTS.md: comments.create takes { target, text },
not { target, content }. Updated both the table row and the
programmatic-access example so AI agents copying this guidance
don't hit a schema rejection.
- track-changes.mdx: theming variables ship as --sd-tracked-changes-*
(e.g. --sd-tracked-changes-insert-background,
--sd-tracked-changes-delete-border), not --sd-track-change-*.
Cited the concrete prefixes a customizer will look for.
- context-menu.mdx: ui.commands has no public execute(id) method.
Documented the actual dispatch shapes:
ui.commands.get(id)?.execute(...), ui.commands.require(id).execute(...),
and ui.toolbar.execute(id, payload) for built-ins.
- navigation.mdx: trackChanges.next() / previous() advance activeId
and return the new id but don't move the viewport on their own;
pair them with scrollTo to navigate. Narrowed the story-aware claim
to trackChanges.scrollTo only; comments.scrollTo is body-scoped
today.
Brand-voice pass on the new content: tightened the context-menu lede
to shorter sentences, replaced one em-dash range glyph in the
keyboard-syntax line with "through".
The page now jumps from the frontmatter description straight into Quick start. The previous prose-then-code lede duplicated the work the description and Quick start already do (orient + show the shape), and the developer-register pattern in brand voice is "show first, tell second" — the code in Quick start IS the lede on a how-to page like this one.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings the public Custom UI docs up to parity with what's actually shipped on `superdoc/ui` after the SD-2936 stack (SD-2943, SD-2954, SD-2945, SD-2944). Net: nine pages updated, one new page, one consumer-facing AGENTS.md section, ~580 lines of new docs.
The biggest gap was the right-click context bundle. A reader who landed on the docs trying to build a custom right-click menu found the deprecated `built-in-ui/context-menu.mdx` (which incorrectly described `disableContextMenu` as suppressing all menus) and nothing about `ui.viewport.contextAt`, `getContextMenuItems`, `ContextMenuItem.invoke()`, or the `context` parameter in `execute`. New `editor/custom-ui/context-menu.mdx` walks the full flow end-to-end with predicate examples for the three subjects (entity, selection, click point) and a worked example mirroring `demos/custom-ui`.
Other notable gaps closed: `ui.selection.restore` was marked "planned" but shipped in SD-2929 / fixed in SD-2954; `ui.selection.getRects` / `getAnchorRect` (the floating bubble menu pattern) were undocumented; `ui.viewport.entityAt` / `getHost` / `positionAt` were undocumented; the `shortcut` field on `register` was undocumented; `execute` examples showed the pre-SD-2945 signature without `context`; `disableContextMenu` was misrepresented; theming had no cross-link from comments / track-changes.
Verified: `pnpm run check:imports` (642 files), `pnpm run check:icons` (Lucide), `pnpm run test:examples` -> 291 passed (+14 new doctests).