fix(ui): honor the focus() contract + fix dangling docs reference (SD-3312)

focus now fails with not-ready when setTextSelection is unavailable and
not-reachable when it doesn't place the caret, so { success: true } means the
caret was actually placed (was reported regardless via optional chaining).

Docs: introduce the smartField tag convention inline instead of referencing a
"convention above" that wasn't introduced earlier on the page.

Author: caio-pizzol

apps/docs/editor/custom-ui/content-controls.mdx

@@ -53,7 +53,7 @@ The event tells you *what* is active; `getRect` tells you *where* to draw. `acti
 
 ## How the model works
 
-You build your UI *over* the control, not inside it. SuperDoc owns how the control's content is painted in the document; you turn off its built-in chrome and draw your own (chips, badges, panels) anchored with `getRect`, react with the events, and change content through `editor.doc.contentControls.*`. Custom field types are expressed as a `tag` (the `{ kind: 'smartField', key }` convention above), interpreted by your own UI - the underlying control stays a standard Word SDT so it round-trips to `.docx`.
+You build your UI *over* the control, not inside it. SuperDoc owns how the control's content is painted in the document; you turn off its built-in chrome and draw your own (chips, badges, panels) anchored with `getRect`, react with the events, and change content through `editor.doc.contentControls.*`. Custom field types are expressed as a `tag` - for example `{ kind: 'smartField', key: 'party_name' }`, interpreted by your own UI - the underlying control stays a standard Word SDT so it round-trips to `.docx`.
 
 ## See also
 

packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts

@@ -3924,6 +3924,12 @@ export class PresentationEditor extends EventEmitter {
     const pos = this.#resolveContentControlCaretPos(entityId);
     if (pos == null) return { success: false, reason: 'not-found' };
 
+    // Without setTextSelection the editor can't place the caret, so focus
+    // can't honor its "caret placed" contract — fail before scrolling.
+    if (typeof editor.commands?.setTextSelection !== 'function') {
+      return { success: false, reason: 'not-ready' };
+    }
+
     // Scroll first and honor the result. A focus that can't bring the control
     // into view must not report success (it would leave a caret on a page that
     // never mounted) — matches #scrollToBlockCandidate. Model-aware: mounts a
@@ -3934,10 +3940,13 @@ export class PresentationEditor extends EventEmitter {
     });
     if (!scrolled) return { success: false, reason: 'not-reachable' };
 
-    // Then place the caret inside the control. setTextSelection clamps and
+    // Place the caret inside the control and honor the result — report success
+    // only if the selection was actually placed. setTextSelection clamps and
     // focuses the (hidden) editor view with preventScroll, so keyboard input
     // goes to the control without re-jumping the viewport.
-    editor.commands?.setTextSelection?.({ from: pos, to: pos });
+    if (!editor.commands.setTextSelection({ from: pos, to: pos })) {
+      return { success: false, reason: 'not-reachable' };
+    }
     return { success: true };
   }