chore(docs): fix icon, merge provider and focus scope pages (#3356)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: gabrielmfern

apps/docs/docs.json

@@ -172,7 +172,6 @@
                 "pages": [
                   "editor/api-reference/ui/bubble-menu",
                   "editor/api-reference/ui/editor-focus-scope",
-                  "editor/api-reference/ui/editor-focus-scope-provider",
                   "editor/api-reference/ui/inspector",
                   "editor/api-reference/ui/slash-command"
                 ]

apps/docs/editor/api-reference/ui/editor-focus-scope-provider.mdx

@@ -1,34 +1,101 @@
 ---
 title: "EditorFocusScope"
 sidebarTitle: "EditorFocusScope"
-description: "Register portaled UI as part of the editor's focus scope."
-icon: "crosshair"
+description: "Track editor focus across portaled UI with EditorFocusScope and EditorFocusScopeProvider."
+icon: "crosshairs"
 ---
 
 Everything is accessed through a single import:
 
 ```tsx
-import { EditorFocusScope } from '@react-email/editor/ui';
+import {
+  EditorFocusScope,
+  EditorFocusScopeProvider,
+} from '@react-email/editor/ui';
 ```
 
+Use `EditorFocusScopeProvider` to keep the editor's focus and blur behavior in
+sync across registered surfaces, then wrap each portaled surface that should
+still count as being inside the editor UI with `EditorFocusScope`.
+
+<Tip>
+  `Inspector.Root` already renders `EditorFocusScopeProvider` and wraps itself
+  in `EditorFocusScope` by default, so the Inspector handles the editor's focus
+  idiomatically and reliably. Inside a custom inspector, you usually only add
+  `EditorFocusScope` around extra portaled content.
+</Tip>
+
+<h2 id="editor-focus-scope-provider">EditorFocusScopeProvider</h2>
+
+Wrap your editor UI with `EditorFocusScopeProvider` when you need focus-aware
+portals outside the built-in Inspector. The provider must be rendered inside
+the current editor context so it can access the active editor instance.
+
+### Example
+
+```tsx
+import {
+  EditorFocusScope,
+  EditorFocusScopeProvider,
+} from '@react-email/editor/ui';
+import { EditorContent, EditorContext, useEditor } from '@tiptap/react';
+import * as Popover from '@radix-ui/react-popover';
+
+export function MyEditor() {
+  const editor = useEditor({
+    extensions,
+    content,
+  });
+
+  return (
+    <EditorContext.Provider value={{ editor }}>
+      <EditorFocusScopeProvider clearSelectionOnBlur={false}>
+        <EditorContent editor={editor} />
+
+        <Popover.Root>
+          <Popover.Trigger type="button">Theme presets</Popover.Trigger>
+
+          <Popover.Portal>
+            <EditorFocusScope>
+              <Popover.Content sideOffset={8}>
+                <button type="button">Apply preset</button>
+              </Popover.Content>
+            </EditorFocusScope>
+          </Popover.Portal>
+        </Popover.Root>
+      </EditorFocusScopeProvider>
+    </EditorContext.Provider>
+  );
+}
+```
+
+Use `EditorFocusScope` for each portaled surface that should still count as
+being inside the editor UI.
+
+### Props
+
+<ResponseField name="children" type="ReactNode">
+  The editor UI subtree that should share focus tracking.
+</ResponseField>
+
+<ResponseField name="clearSelectionOnBlur" type="boolean" default="true">
+  When focus leaves every registered scope, clear the current selection as part
+  of blur handling. Set this to `false` if you want to preserve the selection
+  when the editor truly loses focus.
+</ResponseField>
+
+## EditorFocusScope
+
 Use `EditorFocusScope` around portaled UI like Radix `Select.Content`,
 `Popover.Content`, or dialog content so moving focus into that portal is still
 treated as staying inside the editor UI.
 
 `EditorFocusScope` must be used inside
-[EditorFocusScopeProvider](/editor/api-reference/ui/editor-focus-scope-provider),
+[`EditorFocusScopeProvider`](/editor/api-reference/ui/editor-focus-scope#editor-focus-scope-provider),
 which tracks registered focus scopes and updates the editor's focus state for
 them.
 
-<Tip>
-  `Inspector.Root` already renders
-  [EditorFocusScopeProvider](/editor/api-reference/ui/editor-focus-scope-provider)
-  and wraps itself in `EditorFocusScope` by default, so the Inspector handles
-  the editor's focus idiomatically and reliably. Inside a custom inspector, you
-  usually only add `EditorFocusScope` around extra portaled content.
-</Tip>
-
-## Example
+### Example
 
 ```tsx
 import { EditorFocusScope, Inspector } from '@react-email/editor/ui';
@@ -68,10 +135,10 @@ import * as Select from '@radix-ui/react-select';
 
 If you are building a focus-aware editor shell outside `Inspector.Root`, wrap
 the editor with
-[EditorFocusScopeProvider](/editor/api-reference/ui/editor-focus-scope-provider)
+[`EditorFocusScopeProvider`](/editor/api-reference/ui/editor-focus-scope#editor-focus-scope-provider)
 and then use `EditorFocusScope` for each portaled surface.
 
-## Props
+### Props
 
 <ResponseField name="children" type="ReactNode">
   The element or subtree to register as an additional editor focus scope. Wrap

apps/docs/editor/api-reference/ui/editor-focus-scope.mdx

@@ -62,7 +62,7 @@ export function MyEditor() {
 
 <Tip>
   `Inspector.Root` already renders
-  [EditorFocusScopeProvider](/editor/api-reference/ui/editor-focus-scope-provider)
+  [EditorFocusScopeProvider](/editor/api-reference/ui/editor-focus-scope#editor-focus-scope-provider)
   and wraps itself in
   [EditorFocusScope](/editor/api-reference/ui/editor-focus-scope) by default,
   so the Inspector handles the editor's focus idiomatically and reliably. Add

apps/docs/editor/api-reference/ui/inspector.mdx

@@ -383,7 +383,7 @@ import * as Select from '@radix-ui/react-select';
 ```
 
 `Inspector.Root` already includes
-[`EditorFocusScopeProvider`](/editor/api-reference/ui/editor-focus-scope-provider),
+[`EditorFocusScopeProvider`](/editor/api-reference/ui/editor-focus-scope#editor-focus-scope-provider),
 and it uses both focus-scope components by default to handle the editor's focus
 idiomatically and reliably. Inside a custom inspector you usually only need to
 add [`EditorFocusScope`](/editor/api-reference/ui/editor-focus-scope) around