feat(ui): pass routed editor to custom-command execute (SD-2844)#3039
Merged
caio-pizzol merged 1 commit intomainfrom Apr 30, 2026
Merged
feat(ui): pass routed editor to custom-command execute (SD-2844)#3039caio-pizzol merged 1 commit intomainfrom
caio-pizzol merged 1 commit intomainfrom
Conversation
Custom commands previously had to reach the Document API through a structural cast on superdoc.activeEditor. The execute callback now receives a third argument — editor — typed as SuperDocEditorLike and resolved late-bound at execute time so it tracks header/footer focus the same way every other ui.* mutation does. Also widens SuperDocEditorLike.doc to include a typed insert(input, options) signature. The BYO-UI custom-command pattern (Insert clause, AI-generated text) is the immediate use case; other doc-API mutation methods stay loose unless a similar pattern lands. Drops the structural cast from the BYO-UI demo's InsertClauseButton. The canonical custom-commands docs snippet can simplify the same way once this lands and ships in a patch.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Contributor
|
🎉 This PR is included in vscode-ext v2.3.0-next.70 |
Contributor
|
🎉 This PR is included in @superdoc-dev/mcp v0.3.0-next.25 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in @superdoc-dev/react v1.2.0-next.68 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc v1.30.0-next.27 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-cli v0.8.0-next.43 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-sdk v1.8.0-next.29 |
caio-pizzol
added a commit
that referenced
this pull request
May 1, 2026
…, #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.
caio-pizzol
added a commit
that referenced
this pull request
May 1, 2026
…, #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.
caio-pizzol
added a commit
that referenced
this pull request
May 1, 2026
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.
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.
Custom commands previously reached the Document API through a structural cast on `superdoc.activeEditor`. The `execute` callback now receives a third argument:
```ts
execute: ({ payload, superdoc, editor }) => {
if (!editor) return false;
return editor.doc?.insert?.({ ... })?.success === true;
}
```
`editor` is typed as `SuperDocEditorLike | null` and resolved late-bound at execute time, so it tracks header/footer focus the same way every other `ui.*` mutation does.
Review: backwards-compatibility — `execute` callbacks that destructure `{ payload, superdoc }` ignore `editor`, so this is additive. Worth confirming the `SDMutationReceipt` choice (`Receipt` would also fit; the doc-api uses `SDMutationReceipt` for `insert` specifically).
Verified: 158/158 super-editor UI tests; superdoc + @superdoc-dev/react builds clean; BYO-UI demo builds clean.
Once merged, the BYO-UI docs PR (#3034) drops the structural-cast snippet on `custom-commands.mdx` in favor of `editor.doc?.insert?.(...)`.