docs(custom-ui): add Controller setup page (SD-2929)#3136
Merged
caio-pizzol merged 3 commits intomainfrom May 5, 2026
Merged
Conversation
The Custom UI docs section was React-only. Customers building with
Vue, Svelte, Angular, or vanilla TypeScript had no entry point that
described the framework-agnostic controller surface, even though
that surface is the actual product (the React hooks are sugar over
it).
Adds editor/custom-ui/controller-setup.mdx covering:
- When to read this page vs React setup
- createSuperDocUI({ superdoc })
- ui.<domain>.observe(snapshot => ...) shape (and the wrapped
subscribe alias)
- ui.createScope() for lifecycle, with auto-cascade on ui.destroy()
- scope.add / scope.register / scope.on
- BUILT_IN_COMMAND_IDS / ui.commands.has(id) / ui.commands.require(id)
for config-driven id validation
- Tiny vanilla skeleton in one file
- Common pitfalls: forgetting ui.destroy(), reading live selection
at submit time, built-in UI overlap
Wires the page into the Custom UI nav between React setup and
Toolbar and commands. Adds a Tip callout on react-setup.mdx pointing
non-React readers here.
This is the docs gap the audit surfaced: examples were drifting
toward 'framework matrix' coverage because there was no docs page
that owned the framework-agnostic story. With this page in place,
focused examples (selection-capture, configurable-toolbar) can land
linked from a real docs home.
Contributor
|
📖 Docs preview: https://superdoc-caio-sd-2929-controller-setup-docs.mintlify.app |
… (SD-2929) The Custom UI section grew to 11 pages with this PR's controller-setup addition. That's nearly twice the next-biggest Editor subsection (Built-in UI / SuperDoc, both 6 pages). A flat list at that size is hard to scan, and the existing Toolbar and commands subgroup with a single child of the same name was already awkward. Restructure into four sub-groups that match how customers actually read the section: - Setup (react-setup, controller-setup): the React vs framework- agnostic choice is the first decision a reader makes. - Commands and controls (toolbar-and-commands, custom-commands, document-control): wiring the chrome that drives the editor. - Review workflows (comments, track-changes): the two surfaces a reviewer-style sidebar consumes. - Selection and navigation (selection-and-viewport, navigation): positioning utilities that the surfaces above lean on. Overview stays at the top as the layer model; api-reference stays at the bottom as reference, not a learning path. The previous Toolbar and commands subgroup (which had a child of the same name) goes away; document-control moves out of the trailing-utility cluster into Commands and controls where it belongs. Also tightens the controller-setup page description: 'The framework- agnostic path under React' kept React as the implicit center, which inverts the actual relationship. Reframed as 'Use Custom UI without React' so the controller is the subject, not the alternative.
Reversed the sub-grouped nav from the previous commit. Custom UI is
11 pages, which is on the line but not over it — every other Editor
subsection (SuperDoc, React, Built-in UI, Spell check, Theming, PDF)
reads as a flat list. Sub-groups would break that convention without
materially helping discoverability for either teach-flow readers or
return-lookup readers.
The teach-flow ordering carries the structure instead:
overview → react-setup → controller-setup → toolbar-and-commands
→ custom-commands → comments → selection-and-viewport
→ track-changes → document-control → navigation → api-reference
Selection-and-viewport sits immediately after comments because the
capture / focus-loss problem is the concrete case that motivates the
selection mechanics page. The previous Toolbar and commands subgroup
(awkwardly named the same as one of its children) is gone; the two
pages now sit at the top level next to each other.
Reverts only the nav restructure from 8125da9. Keeps the controller-
setup page itself, the Tip callout on react-setup, and the
controller-setup description fix from earlier in this PR.
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
1 participant
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.
The Custom UI docs section was React-only. Customers on Vue, Svelte, Angular, or vanilla TypeScript had no entry point that described the framework-agnostic controller surface, even though that surface is the actual product. The React hooks are sugar over it.
Adds `editor/custom-ui/controller-setup.mdx` covering: when to read this vs React setup, `createSuperDocUI({ superdoc })`, the `observe(snapshot => ...)` shape, `ui.createScope()` lifecycle with cascade on `ui.destroy()`, `scope.add/register/on`, command discovery (`BUILT_IN_COMMAND_IDS`, `has`, `require`), a one-file vanilla skeleton, and the three pitfalls (missing destroy, live-selection-at-submit, built-in UI overlap).
Wires into the Custom UI nav between React setup and Toolbar and commands. Adds a Tip callout on `react-setup.mdx` pointing non-React readers here.