docs(byo-ui): Bring Your Own UI section + cross-links from built-in modules (SD-2669)#3034
Merged
caio-pizzol merged 24 commits intomainfrom May 1, 2026
Merged
docs(byo-ui): Bring Your Own UI section + cross-links from built-in modules (SD-2669)#3034caio-pizzol merged 24 commits intomainfrom
caio-pizzol merged 24 commits intomainfrom
Conversation
Contributor
|
📖 Docs preview: https://superdoc-caio-sd-2669-byo-ui-docs.mintlify.app |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 90cc684869
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
This was referenced Apr 30, 2026
caio-pizzol
force-pushed
the
caio/sd-2669-byo-ui-docs
branch
from
b578fb1 to
5147b16
Compare
caio-pizzol
added a commit
that referenced
this pull request
May 1, 2026
- api-reference.mdx: ui.toolbar.execute(id, payload?) was signature
syntax, not valid TS. Split into two valid call forms with prose.
- core/react/overview.mdx: drop the <Tip> block per AGENTS.md rule
('Don't add Tips, Warnings, or deep explanations in overview
pages'). Cross-link kept as plain inline paragraph.
Adds a new top-level "Build Your Own UI" group between Modules and Solutions in docs.json, plus 10 stub pages mapping one-to-one to controller domains: overview, react-setup, toolbar-and-commands, custom-commands, comments, review, selection-and-viewport, document-control, reference-demo, api-reference. The stub pages include frontmatter, a one-line value statement, and a Note callout pointing at SD-2669 for status. Stubs land first so cross-doc callouts on the existing Modules pages can link to stable URLs while the content is being written. Overview is filled in to anchor the layer model (Document API / superdoc/ui / built-in modules) and link to every page in the section.
Rewrites the overview to lead with one sentence, the layer model table, and a 15-line code snippet showing useSuperDocCommand bound to a button. Adds icons to the CardGroup so the section index reads at a glance. Sweeps em dashes from every stub. Brand voice rules ban them in favor of hyphens, periods, or split sentences. Adds superdoc/ui and superdoc/ui/react to the docs import allowlist so future pages in this section pass the import validator. Mintlify validate passes.
Fills in: - React setup: provider, onReady, hooks table, common pitfalls - Toolbar and commands: per-button binding, payloads, built-in id table - Custom commands: register, getState, execute, override, namespacing - Comments: list, add from selection, capture-based composer, threads - Selection and viewport: selection slice, capture, scrollIntoView, getRect - Document control: setMode (Edit/Suggest), export, replaceFile - Reference demo: what it covers, how to read it, what it deliberately doesn't do - API reference: handwritten skeleton mirroring page order review.mdx and api-reference.mdx will be revisited after the ui.review → ui.trackChanges rename lands as a separate PR. All pages follow brand voice rules: code-first, short sentences, no em dashes, public APIs only. Trade-offs called out per page. Mintlify validate passes; import validator green.
…urface Mirrors the controller-side rename in #3029 / superdoc 1.30.1: 'ui.review' is gone and 'ui.trackChanges' takes its place. - Rename review.mdx → track-changes.mdx and rewrite for the tracked-changes-only surface (items, total, activeId). - Document the merged comments + changes feed as a consumer-side composition pattern with useSuperDocComments + useSuperDocTrackChanges. - Update docs.json nav, overview card grid, react-setup hook table, api-reference handle + types, and reference-demo coverage table.
Adds <Tip> callouts on the four pages a consumer hits before they realize there's a custom-UI path: modules/comments, modules/track-changes, modules/toolbar/headless, and core/react/overview. Each one routes them to the relevant Build Your Own UI page so they don't fight the built-in module before discovering useSuperDocComments / useSuperDocTrackChanges / useSuperDocCommand.
- Custom commands: rewrite execute example to use the public ui.selection.getSnapshot().selectionTarget shape (was passing the wrong target type to editor.doc.insert). Lead with a pure-additive pattern; mark the activeEditor reach as a known escape hatch. - Custom commands: split override into two patterns. Pattern A (sibling + dispatch both) is the default. Pattern B (true override) now actually toggles the mark instead of silently discarding it. - Comments: de-emphasize the reply pattern. Group-by-parent shape is public; posting a reply is filed as a follow-up and points to the reference demo as a temporary workaround. - Track changes: move the merged-feed pattern out of the canonical page and into reference-demo as 'one app-level composition'. Keeps the controller surface tight. - Drop SSO-gated linear.app URLs from public-facing docs; keep ticket IDs as plain text.
Public docs shouldn't promise specific follow-up tickets readers can't see. Each former 'tracked under SD-XXXX' note now describes either how the surface actually works today or a workaround that ships. - comments: post replies via useSuperDocHost() + editor.doc.comments.create (full snippet, not just a pointer to the demo). - custom-commands: drop the 'when SD-2844 lands' framing; the scoped structural cast is the pattern. - selection-and-viewport / track-changes: explain that non-body entities snap because story activation mounts the surface synchronously, and show how to layer your own smooth scroll if needed. - reference-demo: show window.getSelection() rect lookup as the path for floating menus today. - document-control: full transaction-listener snippet for a dirty indicator.
…, #3040 Three workarounds drop now that the controller surface covers them: - comments.mdx: post a reply via ui.comments.reply(parentId, { text }) instead of useSuperDocHost() + editor.doc.comments.create. - custom-commands.mdx: drop the structural cast on superdoc.activeEditor; use the typed editor argument that execute({ payload, superdoc, editor }) now provides. Pattern B's chain-command cast narrowed and called out. - document-control.mdx: drop the transaction-listener snippet; use useSuperDocDocument().dirty directly. Includes the export-button example pattern. Trade-offs trimmed accordingly. API reference updated: useSuperDocDocument now returns dirty; ui.commands.register() execute receives editor; ui.comments.reply listed in the comments handle block.
- api-reference.mdx: ui.toolbar.execute(id, payload?) was signature
syntax, not valid TS. Split into two valid call forms with prose.
- core/react/overview.mdx: drop the <Tip> block per AGENTS.md rule
('Don't add Tips, Warnings, or deep explanations in overview
pages'). Cross-link kept as plain inline paragraph.
Two factual fixes flagged in PR #3034 review: - toolbar-and-commands.mdx: the built-in command id table listed several ids that aren't on PublicToolbarItemId. strike → strikethrough, color → text-color, highlight → highlight-color, and the entire 'Block' row (heading-1/-2/-3, paragraph) is dropped because no block-level commands exist on this surface today. Replaced the table with the actual id set grouped by domain. - comments.mdx: the trade-off note claimed ui.comments.scrollTo is story-aware. CommentAddress is body-scoped in the contract — only TrackedChangeAddress carries a story field — so the call doesn't navigate to header/footer/note comments. Replaced with an honest description and pointer to ui.viewport.scrollIntoView for non-body cases.
caio-pizzol
force-pushed
the
caio/sd-2669-byo-ui-docs
branch
from
0ad76e9 to
5247889
Compare
The BYO acronym is conventional for 'Bring Your Own X' (BYOK, BYOC, BYOD). It also reads more accurately to what consumers actually do: they bring their existing React app + design system and slot SuperDoc behind it, rather than building a UI from scratch. - Section title in docs.json: 'Build Your Own UI' becomes 'Bring Your Own UI'. - URL slugs: /build-your-own-ui/* becomes /bring-your-own-ui/*. - apps/docs/build-your-own-ui/ renamed to apps/docs/bring-your-own-ui/ (10 mdx pages, all internal links updated). - demos/build-your-own-ui/ renamed to demos/bring-your-own-ui/. Demo's package.json name, README heading, the docs reference-demo links, the playwright port-map key, and the ci-demos.yml matrix entry all follow. - Cross-link callouts on /modules/comments, /modules/track-changes, /modules/toolbar/headless, /core/react/overview reworded.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Fixes stale correctness issues and lays out the layer model so existing docs route customers to the right path. Stage 1 — correctness fixes on BYO pages - bring-your-own-ui/reference-demo: drop the 'demo reaches through useSuperDocHost()' prose; replies and custom commands now use the typed surface after #3035 and #3039 shipped. - bring-your-own-ui/custom-commands: Pattern B (override) reframed as an advanced escape hatch with a Warning, since override truly replaces and consumers shouldn't trust the built-in to still run. - modules/track-changes: drop 'merged comments + changes feed' from the BYO callout; the merged-feed pattern moved to reference-demo as an app-level composition. Stage 2 — toolbar IA cleanup - modules/toolbar/overview: replace the two-path table with a three-path decision: Built-in / Bring Your Own UI / Headless toolbar. Recommendation: new React apps reach for BYO first; headless stays supported for non-React and existing integrations. - modules/toolbar/headless: promote the BYO redirect from a Tip to a 'Using React?' section with the supported-vs-recommended framing. - modules/toolbar/examples: drop the React + shadcn and React + MUI examples; redirect React readers to BYO. Vue / Svelte / vanilla examples stay. Stage 3 — onboarding links - getting-started/frameworks/react: add BYO card to Next steps. - getting-started/quickstart: add BYO link inline under the React scenario plus a card in 'What's next'. Stage 4 — authoring guidance + LLM context - AGENTS.md: new 'Layer model' section with explicit recommendation order (Document API > superdoc/ui > Modules > Core). API naming marks superdoc.activeEditor.commands.* as legacy/compat. Source file table extended with the doc-api contract and superdoc/ui. - llms.txt: add Bring Your Own UI link plus a Layer Model section so agents recommend the right surface. Stage 5 — disambiguate track-changes pages without URL renames - modules/track-changes: title 'Track changes module', sidebarTitle 'Track changes module'. - bring-your-own-ui/track-changes: title 'Custom track changes UI', sidebarTitle stays 'Track changes' for nav consistency.
- core/superdoc/events.mdx: leading Note tells React consumers to prefer superdoc/ui subscriptions over manual superdoc.on(...) loops for live UI state. Lifecycle / integration / analytics events stay the documented use case. - llms-full.txt: new Layer Model section after Architecture so agents recommend Document API for mutations, superdoc/ui for custom React UI, and modules for built-in UI. Lists the four common anti-patterns to steer clear of in customer code.
- modules/comments: lead the 'API methods' section with a Note that steers new code to editor.doc.comments.* (mutations) or ui.comments.* (React UI). The activeEditor.commands.* docs stay for backwards compatibility but no longer present as the recommended path. - core/supereditor/overview: was framing SuperEditor as 'Custom UI implementation' and claimed Document API was 'coming soon'. Both outdated. Rewrote 'When to use' as a layer-picker that points custom React UI at Bring Your Own UI, document mutations at the Document API, and SuperEditor at the genuine low-level cases (engine internals, custom extensions, server-side headless).
- core/superdoc/methods: lead the Comments-methods section and the activeEditor property docs with a Note steering new code to ui.comments.* / editor.doc.* / ui.commands.*. addCommentsList / removeCommentsList stay supported for built-in sidebar users; activeEditor.commands stays for backwards compat. - guides/migration/document-api: append a 'Driving custom React UI' section. Migrators dropping editor.commands/state/view from doc mutations also benefit from migrating the UI side to typed hooks in the same pass. Points at the BYO UI overview and the demo.
- getting-started/import-export: post-init insertContent example steers new code to editor.doc.insert; chain command stays for apps already wired to activeEditor.commands.* - modules/toolbar/built-in: top-of-page Tip routes React readers to Bring Your Own UI first; headless stays as the non-React alternative.
- bring-your-own-ui/overview: layer-model diagram showing how Your UI → superdoc/ui/react → superdoc/ui → Document API → engine, with built-in modules as a sibling path also routed through Document API. - bring-your-own-ui/react-setup: provider-tree diagram showing one provider, one controller, many components subscribing per slice. - bring-your-own-ui/comments: capture-sequence diagram for the textarea- composer flow (select, click Comment, capture, focus moves, submit posts via createFromCapture). - getting-started/quickstart: pick-your-surface decision flow at the top of the page so visitors route to AI agents / backend / built-in editor / Bring Your Own UI without reading the section headings.
Felt too much for the BYO surface. Removing the layer-model, provider-tree, and capture-sequence diagrams. Visual story for BYO will land via media assets and embedded demos in a follow-up, not diagrams. Quickstart 'pick your surface' diagram stays — it's site-wide orientation, not BYO-specific.
New snippet at apps/docs/snippets/components/byo-ui-demo.jsx renders a compact 'workspace slice' driven by superdoc/ui: - Custom toolbar (B / I / Comment / Edit-Suggest / Export) wired to ui.commands observables, ui.document.setMode, ui.document.export. - Activity sidebar shows live ui.comments and ui.trackChanges with Resolve / Accept / Reject actions. Empty state with hints when no comments or changes exist. - Selection-capture composer for new comments via ui.selection.capture() + ui.comments.createFromCapture(). - Try-it checklist above the workspace. Loading: lazy behind a 'Launch interactive demo' button so the 5 MB SuperDoc UMD only loads on user gesture. Editor comes from the existing UMD pattern (window.SuperDoc); controller comes from a dynamic import() of superdoc/ui's ESM entry. The embed bridges controller observables into local React state instead of using superdoc/ui/react — that bundle imports React as a bare ESM specifier, which is fragile in Mintlify's runtime. Caption text points React app users at the typed hooks. Pinned to superdoc@1.30.1 (deterministic; floats forward only when we update the snippet). v1 ships overview only; per-domain variants (comments, track-changes, custom-command) come in follow-ups.
Two failures on the deployed preview:
1. MDX runtime can't resolve capital-letter JSX references inside a
snippet ('Expected component Workspace to be defined'). The helper
functions inside byo-ui-demo.jsx need to be inlined into one big
component, no nested <Workspace />, <ToolButton />, etc.
2. The SuperDoc UMD throws 'Identifier fs has already been declared'
on injection, suggesting it's being loaded twice. Likely a baseUrl
mismatch with the existing SuperDocEditor snippet on extension
pages — different URL strings dodge the dedup querySelector.
Per the agreed fallback plan, don't block #3034 on the embed. The
snippet file stays at apps/docs/snippets/components/byo-ui-demo.jsx
for the follow-up PR where we can debug Mintlify's runtime quirks
without delaying the docs launch.
…rop embed snippet
Sidebar IA cleanup. Customer-facing surface goes from 10 entries to 8
(one of which expands to 2 sub-pages):
- Group 'Toolbar and commands' + 'Custom commands' under a 'Toolbar
and commands' parent. URLs unchanged; sidebarTitle on each page set
to 'Built-in' / 'Custom' so the sub-entries don't collide with the
group label. Page titles ('Toolbar and commands', 'Custom commands')
stay verbose at the top of each page.
- Drop the 'Reference demo' page. Most of it duplicated content that
belongs in the demo's own README. The merged-feed pattern, the
'deliberately doesn't do' list, and the three takeaways for your own
UI all moved to demos/bring-your-own-ui/README.md. Overview gets a
one-line callout pointing at the demo on GitHub.
- 'Document control' page sidebarTitle becomes 'Document' — matches
the one-word pattern of Comments / Track changes (each named after
its ui.* slice).
- Drop apps/docs/snippets/components/byo-ui-demo.jsx. The embed work
is captured in SD-2871 and isn't blocking the docs launch.
Final sidebar:
Overview / React setup / Toolbar and commands (Built-in, Custom) /
Comments / Track changes / Selection and viewport / Document /
API reference
actions={false} disables the Mintlify-injected zoom/pan widget on
the 'Pick your surface' diagram. The diagram is small and one-glance
readable; the controls add visual noise without buying anything.
caio-pizzol
changed the title
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.
Adds a top-level Bring Your Own UI section to the docs site covering the new `superdoc/ui` and `superdoc/ui/react` controller surface (shipped in superdoc 1.30.1). Ten pages, one per controller domain, plus cross-link callouts from the existing built-in modules so consumers actually find this surface instead of fighting the built-in UI first.
Review: pages teach one concept per snippet so an agent can copy them safely. Worth a sanity pass on the custom-commands override section and on whether the merged-feed pattern reads as 'app-level composition' rather than canonical surface.
Verified: `pnpm validate`, `pnpm check:imports` (640 MDX files), `pnpm test:examples` (291 doctests) all green on this branch.
Linked: SD-2669 (this work), SD-2667 (umbrella), SD-2843 (canonical examples extraction, downstream).