feat(document-api): support wrapping text ranges via contentControls.create (SD-2566) (#2815)

* feat(document-api): support wrapping text ranges via contentControls.create (SD-2566)

Add optional `at` field (SelectionTarget) to CreateContentControlInput,
enabling callers to wrap arbitrary text ranges in content controls
without dropping down to editor internals. Mutually exclusive with the
existing `target` field.

* fix(document-api): address review findings for contentControls.create at field

- Re-acquire editor command after at selection dispatch to avoid stale
  state bug (CommandService captures state at access time)
- Reorder validation so at/target mutual exclusivity check runs before
  target shape validation for clearer error messages
- Document at + content interaction in JSDoc
- Extract shared validAt constant in tests

* fix(document-api): add at field to create.contentControl contract schema

The objectSchema uses additionalProperties: false, so contract-driven
callers (CLI, SDK) would reject payloads with the new at field.

Author: caio-pizzol

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

@@ -606,6 +606,11 @@ describe('patchRawProperties validates patch op shapes', () => {
 
 describe('create.contentControl validation', () => {
   const createAdapter = { create: mock(noop) } as any;
+  const validAt = {
+    kind: 'selection' as const,
+    start: { kind: 'text' as const, blockId: 'p1', offset: 0 },
+    end: { kind: 'text' as const, blockId: 'p1', offset: 5 },
+  };
 
   it('rejects null input', () => {
     expect(() => executeCreateContentControl(createAdapter, null as any)).toThrow(/non-null object/);
@@ -652,4 +657,43 @@ describe('create.contentControl validation', () => {
     });
     expect(adapter.create).toHaveBeenCalled();
   });
+
+  it('rejects at and target together', () => {
+    expect(() =>
+      executeCreateContentControl(createAdapter, {
+        kind: 'inline',
+        target: validTarget,
+        at: validAt,
+      } as any),
+    ).toThrow(/mutually exclusive/);
+  });
+
+  it('rejects invalid at (missing start)', () => {
+    expect(() =>
+      executeCreateContentControl(createAdapter, {
+        kind: 'inline',
+        at: { kind: 'selection', end: { kind: 'text', blockId: 'p1', offset: 5 } },
+      } as any),
+    ).toThrow(/valid SelectionTarget/);
+  });
+
+  it('rejects invalid at (wrong kind)', () => {
+    expect(() =>
+      executeCreateContentControl(createAdapter, {
+        kind: 'inline',
+        at: { ...validAt, kind: 'bogus' },
+      } as any),
+    ).toThrow(/valid SelectionTarget/);
+  });
+
+  it('accepts valid at (SelectionTarget)', () => {
+    const adapter = { create: mock(noop) } as any;
+    executeCreateContentControl(adapter, {
+      kind: 'inline',
+      at: validAt,
+      tag: 'name',
+      alias: 'Name',
+    });
+    expect(adapter.create).toHaveBeenCalled();
+  });
 });

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

@@ -9,6 +9,7 @@
 import type { MutationOptions } from '../write/write.js';
 import { DocumentApiValidationError } from '../errors.js';
 import { isRecord, isInteger } from '../validation-primitives.js';
+import { isSelectionTarget } from '../validation/selection-target-validator.js';
 import { LOCK_MODES, CONTENT_CONTROL_TYPES, CONTENT_CONTROL_APPEARANCES } from './content-controls.types.js';
 import type { NodeKind } from '../types/base.js';
 import { NODE_KINDS } from '../types/base.js';
@@ -1033,9 +1034,23 @@ export function executeCreateContentControl(
       { field: 'lockMode', value: input.lockMode },
     );
   }
+  if (input.at !== undefined && input.target !== undefined) {
+    throw new DocumentApiValidationError(
+      'INVALID_INPUT',
+      `create.contentControl: "at" and "target" are mutually exclusive — provide one or neither.`,
+      { field: 'at' },
+    );
+  }
   if (input.target !== undefined) {
     validateCCTarget(input.target, 'create.contentControl');
   }
+  if (input.at !== undefined && !isSelectionTarget(input.at)) {
+    throw new DocumentApiValidationError(
+      'INVALID_INPUT',
+      `create.contentControl: "at" must be a valid SelectionTarget with kind "selection", start, and end.`,
+      { field: 'at', value: input.at },
+    );
+  }
   if (input.content !== undefined && typeof input.content !== 'string') {
     throw new DocumentApiValidationError(
       'INVALID_INPUT',

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

@@ -6,6 +6,7 @@
  */
 
 import type { NodeKind } from '../types/base.js';
+import type { SelectionTarget } from '../types/address.js';
 import type { ReceiptFailure } from '../types/receipt.js';
 
 // ---------------------------------------------------------------------------
@@ -206,6 +207,12 @@ export interface CreateContentControlInput {
   kind: NodeKind;
   controlType?: ContentControlType;
   target?: ContentControlTarget;
+  /**
+   * Text range to wrap in the new content control. Mutually exclusive with `target`.
+   * When `content` is also provided, it replaces the selected text inside the new SDT.
+   * When `content` is omitted, the existing text in the range becomes the SDT content.
+   */
+  at?: SelectionTarget;
   tag?: string;
   alias?: string;
   lockMode?: LockMode;

packages/document-api/src/contract/schemas.ts

@@ -2190,6 +2190,7 @@ function buildContentControlSchemas(): Record<ContentControlOperationId, Operati
           kind: { enum: ['block', 'inline'] },
           controlType: { type: 'string' },
           target: contentControlTargetSchema,
+          at: selectionTargetSchema,
           tag: { type: 'string' },
           alias: { type: 'string' },
           lockMode: { enum: ['unlocked', 'sdtLocked', 'contentLocked', 'sdtContentLocked'] },

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/content-controls-wrappers.ts

@@ -13,6 +13,7 @@
  */
 
 import { Fragment, type Node as ProseMirrorNode, type Schema } from 'prosemirror-model';
+import { TextSelection } from 'prosemirror-state';
 import type { Editor } from '../../core/Editor.js';
 import type { ProseMirrorJSON } from '../../core/types/EditorTypes.js';
 import type {
@@ -89,6 +90,7 @@ import type {
 import { DocumentApiAdapterError } from '../errors.js';
 import { executeDomainCommand } from './plan-wrappers.js';
 import { clearIndexCache } from '../helpers/index-cache.js';
+import { resolveSelectionTarget } from '../helpers/selection-target-resolver.js';
 
 // Shared helpers — single source of truth for SDT logic
 import {
@@ -1853,30 +1855,44 @@ function createWrapper(
       return true;
     }
 
+    // When a SelectionTarget is provided, set the editor selection to that
+    // range so insertStructuredContentInline/Block wraps the targeted text.
+    if (input.at) {
+      const { absFrom, absTo } = resolveSelectionTarget(editor, input.at);
+      const { tr } = editor.state;
+      tr.setSelection(TextSelection.create(tr.doc, absFrom, absTo));
+      dispatchTransaction(editor, tr);
+    }
+
+    // Re-acquire the command so it picks up fresh editor state — important
+    // when `at` dispatched a selection change above.
+    const cmd = editor.commands?.[commandName];
+    if (typeof cmd !== 'function') return false;
+
     // Default: delegate to the editor command (inserts at current selection).
     if (contentText !== undefined) {
       if (input.kind === 'block') {
         if (isCheckboxCreate) {
           return Boolean(
-            insertCmd({
+            cmd({
               attrs,
               json: { type: 'paragraph', content: [buildCheckboxTextJson(checkboxSymbol)] },
             }),
           );
         }
         return Boolean(
-          insertCmd({
+          cmd({
             attrs,
             json: { type: 'paragraph', content: [{ type: 'text', text: contentText }] },
           }),
         );
       }
       if (isCheckboxCreate) {
-        return Boolean(insertCmd({ attrs, json: buildCheckboxTextJson(checkboxSymbol) }));
+        return Boolean(cmd({ attrs, json: buildCheckboxTextJson(checkboxSymbol) }));
       }
-      return Boolean(insertCmd({ attrs, text: contentText }));
+      return Boolean(cmd({ attrs, text: contentText }));
     }
-    return Boolean(insertCmd({ attrs }));
+    return Boolean(cmd({ attrs }));
   });
 }