feat(content-controls): support richText type and regenerate NDA demo fixture (SD-3131) (#3275)

* feat(content-controls): support richText type and resolve typeless SDTs per ECMA-376 (SD-3131)

Adds 'richText' to ContentControlType so SuperDoc resolves typeless w:sdt
SDTs to 'richText' per ECMA-376 §17.5.2.26 ("If no type element is
specified, then the nearest ancestor structured document tag shall be
of type richText"). Before, typeless SDTs - which Word emits for
ContentControls.Add(0, range) and the default Add($null, range) - fell
through to 'unknown', blocking customers from inspecting Word-authored
controls by type.

- Detection: typeless sdtPr and explicit <w:richText/> both resolve to
  'richText'. Unmodeled type children (w:equation, w:picture, w:citation,
  w:bibliography, w:docPartList) still return null so resolveControlType
  yields 'unknown' - keeping 'unknown' as "unsupported or unrecognized",
  not "typeless rich-text control".
- Export/create maps: richText: 'w:richText' in both CONTROL_TYPE_SDT_PR_ELEMENTS
  (wrappers) and CONTROL_TYPE_ELEMENT_MAP (converter), plus a 'richText'
  case in buildDefaultTypeSdtPrElement so create.contentControl and setType
  produce valid OOXML.
- text.setValue stays restricted to actual w:text controls.

Tests: 22 in handle-structured-content-node.test.js (10 new), 39 in
content-controls-wrappers, 1189 in conformance - all pass.

* feat(demos): regenerate NDA fixture with plain-text inline fields (SD-3131)

The contract-templates demo fixture had inline smart fields authored as
default rich-text controls (typeless sdtPr), which is why none of them
detected as 'text' - they fell through to 'unknown' before SD-3131 and
resolve as 'richText' after.

Regenerated nda-template.docx with ContentControls.Add(1, range) for the
7 inline smart fields (now <w:text/> in sdtPr, controlType: 'text') while
leaving the 6 block clauses as typeless (controlType: 'richText').
Verified unzip: 13 SDTs total, 7 <w:text/>, 0 explicit <w:richText/>.

Switched per-occurrence field update from replaceContent to text.setValue
to exercise the typed API. Clause replacement stays on replaceContent
because rich-text controls don't have a typed setter.

README/JSDoc updated: "seven inline plain-text + six block rich-text"
(was "thirteen plain-text"). Honest limits section updated to reflect
the API split.

Browser smoke verified: receivingParty fan-out updates 2/2 occurrences
(header + nested), clause replacement decrements "updates available"
correctly, summary line accurate.

Author: caio-pizzol

demos/contract-templates/README.md

@@ -6,12 +6,12 @@ This is a demo: it composes multiple content-control patterns into a product wor
 
 ## What this shows
 
-The starting document is a Mutual NDA at `public/nda-template.docx` with thirteen plain-text content controls already in place: seven inline smart fields across five field keys (Receiving party and Purpose each appear twice — once in the header sentence and once nested inside the Permitted Use clause) plus six block clauses, each with a `w:tag` carrying a JSON payload. On boot, SuperDoc imports the DOCX, parses the SDTs, and the demo reads field values and clause versions straight from the parsed controls.
+The starting document is a Mutual NDA at `public/nda-template.docx` with thirteen content controls already in place: seven inline plain-text controls (smart fields) and six block rich-text controls (reusable clauses). Receiving party and Purpose each appear twice — once in the header sentence and once nested inside the Permitted Use clause. Each control carries a `w:tag` with a JSON payload. On boot, SuperDoc imports the DOCX, parses the SDTs, and the demo reads field values and clause versions straight from the parsed controls.
 
 Three flows of the same primitive, composed into one app:
 
-1. **Smart fields.** Seven inline content controls across five field keys share a `tag` shape (`{ kind: 'smartField', key: 'disclosingParty' }`) per occurrence. Edit a value in the Fields tab; every occurrence of that field updates live via `selectByTag` + `replaceContent`. Receiving party and Purpose appear twice (header sentence and nested inside the Permitted Use clause), so a single edit fans across both locations.
-2. **Versioned reusable clauses.** Six block content controls carry `{ kind: 'reusableSection', sectionId, version }` in their tags. The app reads each live version from `contentControls.list`, compares against the clause library, and surfaces a Review CTA when they diverge. Review expands a card with the current clause text alongside the library clause text plus a Replace with library clause action that calls `replaceContent` + `patch`.
+1. **Smart fields.** Seven inline plain-text content controls across five field keys share a `tag` shape (`{ kind: 'smartField', key: 'disclosingParty' }`) per occurrence. They were authored as Word "Plain Text Content Controls" (`ContentControls.Add(1, range)`), so SuperDoc resolves them as `controlType: 'text'`. Edit a value in the Fields tab; every occurrence of that field updates live via `selectByTag` + per-occurrence `text.setValue`. Receiving party and Purpose appear twice (header sentence and nested inside the Permitted Use clause), so a single edit fans across both locations.
+2. **Versioned reusable clauses.** Six block rich-text content controls carry `{ kind: 'reusableSection', sectionId, version }` in their tags. They were authored as Word "Rich Text Content Controls" (`ContentControls.Add(0, range)`), which produces typeless sdtPr; SuperDoc resolves them as `controlType: 'richText'` per ECMA-376 §17.5.2.26. The app reads each live version from `contentControls.list`, compares against the clause library, and surfaces a Review CTA when they diverge. Review expands a card with the current clause text alongside the library clause text plus a Replace with library clause action that calls `replaceContent` + `patch`.
 3. **Export.** `superdoc.export({ exportedName, isFinalDoc, triggerDownload })` has two buttons: **Export raw DOCX** uses `isFinalDoc: false` to preserve content controls and tags for future template/library updates; **Export clean DOCX** uses `isFinalDoc: true` to flatten controls so the filled values are in place.
 
 Every mutation goes through `editor.doc.*`. The same operation set runs headless via the Node SDK and CLI.
@@ -32,8 +32,8 @@ If you need a **ready-made React component for authoring templates** with conten
 ## Honest limits
 
 - All content controls in the fixture are `unlocked`. Locked controls (`sdtLocked`, `sdtContentLocked`) are not driven programmatically here.
-- Field values are updated through `contentControls.replaceContent` rather than `text.setValue`. `replaceContent` works regardless of how the control's type is detected on import.
-- Clause bodies are plain text. Rich-content clauses (formatting, tables, lists) need a different path: use `doc.insert` with the fragment, then `create.contentControl({ at: range })` to wrap the inserted range with a tag.
+- Smart field values are pushed through `text.setValue` (the typed API for plain-text controls). Clause bodies are pushed through `replaceContent` because rich-text controls don't have a typed setter.
+- Clause bodies in the seeded fixture are single-paragraph plain prose; the rich-text wrapper supports formatting/lists/tables when authored that way, but the demo doesn't exercise those.
 
 ## See also
 

demos/contract-templates/public/nda-template.docx

@@ -3,22 +3,27 @@
  *
  * The document is a Mutual NDA (`public/nda-template.docx`)
  * with content controls already in place:
- *   - Seven inline plain-text SDTs across five field keys (disclosing
- *     party, receiving party, effective date, purpose, term length).
+ *   - Seven inline plain-text content controls across five field keys
+ *     (disclosing party, receiving party, effective date, purpose, term
+ *     length). Authored via Word's `ContentControls.Add(1, range)`, so their
+ *     `w:sdtPr` carries `<w:text/>` and they resolve as `controlType: 'text'`.
  *     Receiving party and Purpose each appear twice: once in the header
  *     sentence and once nested inside the Permitted Use block clause.
- *   - Six block plain-text SDTs (Preamble, Confidentiality, Permitted Use,
- *     Term and Termination, Governing Law, Limitation of Liability). Each
- *     block carries `{ kind: 'reusableSection', sectionId, version }` in
- *     its tag.
+ *   - Six block rich-text content controls (Preamble, Confidentiality,
+ *     Permitted Use, Term and Termination, Governing Law, Limitation of
+ *     Liability). Authored via `ContentControls.Add(0, range)`, which
+ *     produces typeless sdtPr that resolves as `controlType: 'richText'`
+ *     per ECMA-376 §17.5.2.26. Each block carries
+ *     `{ kind: 'reusableSection', sectionId, version }` in its tag.
  *
  * The app:
  *   1. Loads the fixture as its starting document.
  *   2. Reads each field's text and each clause's version from the parsed SDTs.
  *   3. Compares clause versions against the local library and surfaces a
  *      Review CTA on every stale clause with a one-line summary of the change.
  *   4. Field inputs are reactive: typing in a value debounces by ~250ms and
- *      fans the new text to every occurrence via `selectByTag` + `replaceContent`.
+ *      fans the new text to every occurrence via `selectByTag` + per-occurrence
+ *      `text.setValue` (the typed API path for plain-text controls).
  *   5. Review expands a card showing the in-document clause alongside the
  *      library version. Replace with library clause swaps body via
  *      `replaceContent` and bumps the tag version via `patch`.
@@ -58,6 +63,9 @@ type DocumentApi = {
     selectByTag(input: { tag: string }): { items: ContentControlInfo[]; total: number };
     patch(input: { target: ContentControlTarget; tag?: string; alias?: string }): MutationResult;
     replaceContent(input: { target: ContentControlTarget; content: string; format?: 'text' }): MutationResult;
+    text: {
+      setValue(input: { target: ContentControlTarget; value: string }): MutationResult;
+    };
   };
 };
 
@@ -276,11 +284,7 @@ function applyField(key: FieldKey, value: string): void {
   state.values[key] = value;
   const { items } = state.editor.doc.contentControls.selectByTag({ tag: fieldTag(key) });
   for (const ctrl of items) {
-    state.editor.doc.contentControls.replaceContent({
-      target: ctrl.target,
-      content: value,
-      format: 'text',
-    });
+    state.editor.doc.contentControls.text.setValue({ target: ctrl.target, value });
   }
 }
 

demos/contract-templates/src/main.ts

@@ -13,9 +13,16 @@ import type { ReceiptFailure } from '../types/receipt.js';
 // Enums and constants
 // ---------------------------------------------------------------------------
 
-/** Semantic SDT subtype derived from `w:sdtPr` children. */
+/**
+ * Semantic SDT subtype derived from `w:sdtPr` children.
+ *
+ * `richText` covers both explicit `<w:richText/>` and the OOXML default for
+ * sdtPr with no type child (ECMA-376 §17.5.2.26: typeless SDT shall be of
+ * type richText). `unknown` means an unsupported or unrecognized type child.
+ */
 export type ContentControlType =
   | 'text'
+  | 'richText'
   | 'date'
   | 'checkbox'
   | 'comboBox'
@@ -27,6 +34,7 @@ export type ContentControlType =
 
 export const CONTENT_CONTROL_TYPES = [
   'text',
+  'richText',
   'date',
   'checkbox',
   'comboBox',

packages/document-api/src/content-controls/content-controls.types.ts

@@ -7,10 +7,12 @@ import { parseAnnotationMarks } from './handle-annotation-node';
  * @returns {string|null}
  */
 function detectControlType(sdtPr) {
-  if (!sdtPr?.elements) return null;
+  // ECMA-376 §17.5.2.26: an sdtPr with no type child shall be of type richText.
+  if (!sdtPr?.elements) return 'richText';
   const names = sdtPr.elements.map((el) => el.name);
 
   if (names.includes('w:text')) return 'text';
+  if (names.includes('w:richText')) return 'richText';
   if (names.includes('w:date')) return 'date';
   if (names.includes('w14:checkbox') || names.includes('w:checkbox')) return 'checkbox';
   if (names.includes('w:comboBox')) return 'comboBox';
@@ -19,7 +21,16 @@ function detectControlType(sdtPr) {
   if (names.includes('w15:repeatingSectionItem') || names.includes('w:repeatingSectionItem'))
     return 'repeatingSectionItem';
   if (names.includes('w:group')) return 'group';
-  return null;
+
+  // Type-marker children that we don't (yet) model — equation, picture, citation,
+  // bibliography, docPartList. Fall through so resolveControlType yields 'unknown'.
+  const TYPE_CHILD_NAMES = new Set(['w:equation', 'w:picture', 'w:citation', 'w:bibliography', 'w:docPartList']);
+  if (names.some((n) => TYPE_CHILD_NAMES.has(n))) return null;
+
+  // No recognized type child and no unrecognized type child either — sdtPr has
+  // only property children (alias/tag/id/lock/placeholder/...). Per the spec,
+  // that's a richText SDT.
+  return 'richText';
 }
 
 /**

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/sdt/helpers/handle-structured-content-node.js

@@ -224,4 +224,70 @@ describe('handleStructuredContentNode', () => {
       expect(result.attrs.lockMode).toBe('unlocked');
     });
   });
+
+  describe('controlType detection', () => {
+    const detectFrom = (sdtPrElements) => {
+      const node = createNode(sdtPrElements, [{ name: 'w:r', text: 'content' }]);
+      const params = { nodes: [node], nodeListHandler: mockNodeListHandler };
+      parseAnnotationMarks.mockReturnValue({ marks: [] });
+      return handleStructuredContentNode(params).attrs.controlType;
+    };
+
+    it('detects explicit <w:text/> as "text"', () => {
+      expect(detectFrom([{ name: 'w:text' }])).toBe('text');
+    });
+
+    it('detects explicit <w:richText/> as "richText"', () => {
+      expect(detectFrom([{ name: 'w:richText' }])).toBe('richText');
+    });
+
+    it('resolves typeless sdtPr (only property children) as "richText" per ECMA-376 §17.5.2.26', () => {
+      // Real-world case: Word emits this for ContentControls.Add(0, range) and
+      // ContentControls.Add($null, range). The sdtPr carries only properties
+      // (alias/tag/id/placeholder), no type-axis child.
+      const propsOnly = [
+        { name: 'w:alias', attributes: { 'w:val': 'Field' } },
+        { name: 'w:tag', attributes: { 'w:val': 'x' } },
+        { name: 'w:id', attributes: { 'w:val': '123' } },
+        { name: 'w:placeholder', elements: [{ name: 'w:docPart', attributes: { 'w:val': 'default' } }] },
+      ];
+      expect(detectFrom(propsOnly)).toBe('richText');
+    });
+
+    it('detects <w:date/> as "date"', () => {
+      expect(detectFrom([{ name: 'w:date' }])).toBe('date');
+    });
+
+    it('detects <w14:checkbox/> as "checkbox"', () => {
+      expect(detectFrom([{ name: 'w14:checkbox' }])).toBe('checkbox');
+    });
+
+    it('detects <w:comboBox/> as "comboBox"', () => {
+      expect(detectFrom([{ name: 'w:comboBox' }])).toBe('comboBox');
+    });
+
+    it('detects <w:dropDownList/> as "dropDownList"', () => {
+      expect(detectFrom([{ name: 'w:dropDownList' }])).toBe('dropDownList');
+    });
+
+    it('detects <w15:repeatingSection/> as "repeatingSection"', () => {
+      expect(detectFrom([{ name: 'w15:repeatingSection' }])).toBe('repeatingSection');
+    });
+
+    it('detects <w:group/> as "group"', () => {
+      expect(detectFrom([{ name: 'w:group' }])).toBe('group');
+    });
+
+    it('returns null for unmodeled type children so resolveControlType coerces to "unknown"', () => {
+      // detectControlType returns null for unmodeled type elements; resolveControlType
+      // (in sdt-info-builder.ts) coerces null → 'unknown' downstream. Verifies that
+      // 'unknown' keeps its semantics: "unsupported or unrecognized type child",
+      // not "typeless rich-text control".
+      expect(detectFrom([{ name: 'w:bibliography' }])).toBeNull();
+      expect(detectFrom([{ name: 'w:citation' }])).toBeNull();
+      expect(detectFrom([{ name: 'w:equation' }])).toBeNull();
+      expect(detectFrom([{ name: 'w:picture' }])).toBeNull();
+      expect(detectFrom([{ name: 'w:docPartList' }])).toBeNull();
+    });
+  });
 });

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/sdt/helpers/handle-structured-content-node.test.js

@@ -40,6 +40,7 @@ export function translateStructuredContent(params) {
 /** Maps control types to their sdtPr element names for OOXML export. */
 const CONTROL_TYPE_ELEMENT_MAP = {
   text: 'w:text',
+  richText: 'w:richText',
   date: 'w:date',
   checkbox: 'w14:checkbox',
   comboBox: 'w:comboBox',

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/sdt/helpers/translate-structured-content.js

@@ -23,6 +23,7 @@ import { findSdtPrChild, getSdtPrChildAttrs, type SdtPrElement } from './sdt-pro
 
 const VALID_CONTROL_TYPES: readonly string[] = [
   'text',
+  'richText',
   'date',
   'checkbox',
   'comboBox',

packages/super-editor/src/editors/v1/document-api-adapters/helpers/content-controls/sdt-info-builder.ts

@@ -626,6 +626,7 @@ function setLockModeWrapper(
 /** Maps control types to their sdtPr element name. Types not listed have no element. */
 const CONTROL_TYPE_SDT_PR_ELEMENTS: Record<string, string> = {
   text: 'w:text',
+  richText: 'w:richText',
   date: 'w:date',
   checkbox: 'w14:checkbox',
   comboBox: 'w:comboBox',
@@ -785,6 +786,8 @@ function buildDefaultTypeSdtPrElement(controlType: string | undefined): SdtPrEle
   switch (controlType) {
     case 'text':
       return { name: 'w:text', type: 'element' };
+    case 'richText':
+      return { name: 'w:richText', type: 'element' };
     case 'date':
       return {
         name: 'w:date',