docs: add content controls page, examples, and demo (IT-1046)#3265
Merged
Conversation
Customer asked whether SuperDoc supports composable reusable sections and "smart fields" — placeholders that update everywhere when edited centrally. Both map cleanly to Word content controls (OOXML SDT), and the surface is fully wired in the Document API. Ships two narrow examples plus a composed runtime demo, plus a conceptual docs page so the Document API surface gets the same hand-written narrative the Editor extensions already have. - examples/document-api/content-controls/smart-fields/ and reusable-section/ each teach one pattern in isolation, copy-pasteable. - demos/contract-templates/ is a composed workflow that detects stale section versions and applies updates in place. Not yet gallery-ready (homepage: false) pending the lock-mutation fix. - apps/docs/document-api/features/content-controls.mdx is a new home for hand-written feature narratives, slotted under a new Features sidebar group inside Document API. Frames Template Builder and the raw Document API as two valid paths. - Document API path is fully editor.doc.*. The same operation set runs headless via the Node SDK and CLI. Follow-ups: SD-3123 (locked-SDT mutations silently no-op via the legacy command path), SD-3124 (filter-rejected transactions report false success), SD-3125 (imported-controls example with a Word-authored fixture).
Contributor
![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: 6cd05460e6
ℹ️ 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".
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…ne-text (IT-1046) The first pass shipped two examples (smart-fields, reusable-section) that read as demo decompositions: same primitives as demos/contract-templates, ~200 lines each, with markdown seeds and panel chrome. They didn't earn their place against the demo. Replaced with one tight example, modelled on examples/editor/custom-ui/selection-capture: smallest readable form of the canonical create-find-update loop, with a README that distinguishes setup mutations from the teaching surface (selectByTag + text.setValue). Sets the template that future content-control examples copy. - examples/document-api/content-controls/tagged-inline-text/ is the new single example. - Old smart-fields/, reusable-section/, and the parent README.md removed. - features/content-controls.mdx Next steps cards updated to point at the new example. - Manifest and README rows replaced.
Captures the conventions IT-1046 produced so future contributors don't rediscover them. Examples and demos each get a scoped AGENTS.md (with a CLAUDE.md symlink for compat) defining what belongs in each surface, the cross-surface Document API placement rule, and the "don't ship known-bug or unverified paths" rule that drove the lockMode: 'unlocked' choice in the tagged-inline-text example. - examples/README.md and demos/README.md rewritten with clear definitions, contributor checklists, and homepage-readiness criteria. - examples/AGENTS.md (+ CLAUDE.md symlink) covers Document API placement, setup-vs-teaching separation, and verification rules. - demos/AGENTS.md (+ CLAUDE.md symlink) covers composed-workflow criteria and source-vs-live demo distinction. - demos/README.md adds contract-templates to the curated demos table. - demos/contract-templates/README.md calls out its demo status and links back to the tagged-inline-text example. - tagged-inline-text/README.md notes the lockMode: 'unlocked' choice and points at SD-3123. - Both style.css files now read from --sd-* tokens with fallbacks, so examples and demos pick up the host SuperDoc theme.
…1046) Replaces internal-status framing with API guidance. Removes references to engine internals, legacy paths, known bugs, and 'not yet' language. - Lock modes: behavior table, then concrete guidance for programmatic use. - Data binding: describe what the API supports and what to drive instead. - Replacing content: scope replaceContent to plain text and point at doc.insert + contentControls.wrap for richer fragments.
contentControls.wrap takes an existing SDT target, not a selection range. Use create.contentControl with an at: SelectionTarget to wrap an inserted range.
msviderok
pushed a commit
to msviderok/superdoc
that referenced
this pull request
May 16, 2026
…oc-dev#3265) * docs: add content controls page, examples, and demo (IT-1046) Customer asked whether SuperDoc supports composable reusable sections and "smart fields" — placeholders that update everywhere when edited centrally. Both map cleanly to Word content controls (OOXML SDT), and the surface is fully wired in the Document API. Ships two narrow examples plus a composed runtime demo, plus a conceptual docs page so the Document API surface gets the same hand-written narrative the Editor extensions already have. - examples/document-api/content-controls/smart-fields/ and reusable-section/ each teach one pattern in isolation, copy-pasteable. - demos/contract-templates/ is a composed workflow that detects stale section versions and applies updates in place. Not yet gallery-ready (homepage: false) pending the lock-mutation fix. - apps/docs/document-api/features/content-controls.mdx is a new home for hand-written feature narratives, slotted under a new Features sidebar group inside Document API. Frames Template Builder and the raw Document API as two valid paths. - Document API path is fully editor.doc.*. The same operation set runs headless via the Node SDK and CLI. Follow-ups: SD-3123 (locked-SDT mutations silently no-op via the legacy command path), SD-3124 (filter-rejected transactions report false success), SD-3125 (imported-controls example with a Word-authored fixture). * docs: replace content-control examples with one canonical tagged-inline-text (IT-1046) The first pass shipped two examples (smart-fields, reusable-section) that read as demo decompositions: same primitives as demos/contract-templates, ~200 lines each, with markdown seeds and panel chrome. They didn't earn their place against the demo. Replaced with one tight example, modelled on examples/editor/custom-ui/selection-capture: smallest readable form of the canonical create-find-update loop, with a README that distinguishes setup mutations from the teaching surface (selectByTag + text.setValue). Sets the template that future content-control examples copy. - examples/document-api/content-controls/tagged-inline-text/ is the new single example. - Old smart-fields/, reusable-section/, and the parent README.md removed. - features/content-controls.mdx Next steps cards updated to point at the new example. - Manifest and README rows replaced. * docs: add examples/demos contributor guidance and align styles (IT-1046) Captures the conventions IT-1046 produced so future contributors don't rediscover them. Examples and demos each get a scoped AGENTS.md (with a CLAUDE.md symlink for compat) defining what belongs in each surface, the cross-surface Document API placement rule, and the "don't ship known-bug or unverified paths" rule that drove the lockMode: 'unlocked' choice in the tagged-inline-text example. - examples/README.md and demos/README.md rewritten with clear definitions, contributor checklists, and homepage-readiness criteria. - examples/AGENTS.md (+ CLAUDE.md symlink) covers Document API placement, setup-vs-teaching separation, and verification rules. - demos/AGENTS.md (+ CLAUDE.md symlink) covers composed-workflow criteria and source-vs-live demo distinction. - demos/README.md adds contract-templates to the curated demos table. - demos/contract-templates/README.md calls out its demo status and links back to the tagged-inline-text example. - tagged-inline-text/README.md notes the lockMode: 'unlocked' choice and points at SD-3123. - Both style.css files now read from --sd-* tokens with fallbacks, so examples and demos pick up the host SuperDoc theme. * docs: rewrite content-controls limits sections in customer voice (IT-1046) Replaces internal-status framing with API guidance. Removes references to engine internals, legacy paths, known bugs, and 'not yet' language. - Lock modes: behavior table, then concrete guidance for programmatic use. - Data binding: describe what the API supports and what to drive instead. - Replacing content: scope replaceContent to plain text and point at doc.insert + contentControls.wrap for richer fragments. * docs: correct rich-fragment wrap guidance (IT-1046) contentControls.wrap takes an existing SDT target, not a selection range. Use create.contentControl with an at: SelectionTarget to wrap an inserted range.
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.
Customer asked whether SuperDoc supports composable reusable sections and "smart fields" — placeholders that update everywhere when edited centrally. Both map cleanly to Word content controls (OOXML SDT), and the surface is fully wired in the Document API. Ships two narrow examples plus a composed runtime demo, plus a conceptual docs page so the Document API surface gets the same hand-written narrative the Editor extensions already have.
examples/document-api/content-controls/smart-fields/andreusable-section/each teach one pattern in isolation, copy-pasteable.demos/contract-templates/is a composed workflow that detects stale section versions and applies updates in place. Not yet gallery-ready (homepage: false) pending the lock-mutation fix.apps/docs/document-api/features/content-controls.mdxis a new home for hand-written feature narratives, slotted under a new Features sidebar group inside Document API. Frames Template Builder and the raw Document API as two valid paths.editor.doc.*. The same operation set runs headless via the Node SDK and CLI.Follow-ups: SD-3123 (locked-SDT mutations silently no-op via the legacy command path), SD-3124 (filter-rejected transactions report false success), SD-3125 (imported-controls example with a Word-authored fixture).