refactor(react): one vocabulary and simpler plumbing for portal elements

docs/content/docs/react/components/index.mdx

@@ -17,20 +17,20 @@ BlockNote includes a number of UI Components (like menus and toolbars) that can
 
 ## Configuring Portal Targets
 
-By default, all floating UI elements (toolbars, menus, table handles, etc.) portal into the editor's `bn-container` so they stay scoped to the editor. If your layout needs them to escape — e.g. an `overflow: hidden` ancestor that would clip large dropdowns, or a host modal with its own stacking context — pass a `portalElements` prop to `BlockNoteView`:
+By default, the floating components (formatting toolbar, side menu, slash menu, table handles, etc.) portal into the element that wraps the editor: the editor's `bn-container`, or, when you render `BlockNoteViewEditor` yourself, the element you render it into. So they stay scoped to the editor and clip with it. The menus and popovers a floating component opens render inside that component's wrapper, so they move and hide with it. If your layout needs the floating components to escape, e.g. an `overflow: hidden` ancestor that would clip large dropdowns, or a host modal with its own stacking context, pass a `portalElements` prop to `BlockNoteView`:
 
 ```tsx
 <BlockNoteView
   editor={editor}
   portalElements={{
     // Global default for any element not listed below.
     default: document.body,
-    // Per-element overrides. Values can be HTMLElement, a CSS selector, or null (= document.body).
+    // Per-element overrides. Values can be an HTMLElement or a CSS selector.
     tableHandles: ".bn-container",
   }}
 />
 ```
 
-Keys mirror the default UI flags (`formattingToolbar`, `linkToolbar`, `slashMenu`, `emojiPicker`, `sideMenu`, `filePanel`, `tableHandles`, `comments`). Manually-mounted Controllers also accept a `portalElement` prop that takes precedence over the map. See the [Portal Targets example](/examples/ui-components/portal-elements).
+Keys mirror the default UI flags (`formattingToolbar`, `linkToolbar`, `slashMenu`, `emojiPicker`, `sideMenu`, `filePanel`, `tableHandles`, `comments`). Manually-mounted Controllers also accept a `portalElement` prop that takes precedence over the map. All keys, including `default`, update reactively. See the [Portal Targets example](/examples/ui-components/portal-elements).
 
-Note: changing `portalElements.default` after mount requires remounting the editor (`editor.mount()` consults it once); per-element keys update reactively.
+When a target sits outside the editor's DOM (like `document.body`), BlockNote automatically renders a themed wrapper element inside it, so floating UI keeps the editor's styling and theming wherever it's portalled.

examples/03-ui-components/11-uppy-file-panel/src/FileReplaceButton.tsx

@@ -8,7 +8,7 @@ import {
   useBlockNoteEditor,
   useComponentsContext,
   useDictionary,
-  useMobileToolbarPortal,
+  usePortalElement,
   useSelectedBlocks,
 } from "@blocknote/react";
 import { useCallback, useEffect, useState } from "react";
@@ -24,7 +24,7 @@ export const FileReplaceButton = () => {
   const dict = useDictionary();
   const Components = useComponentsContext()!;
   // Portal necessary to properly show popover on mobile.
-  const mobileToolbarPortal = useMobileToolbarPortal();
+  const editorPortalElement = usePortalElement();
 
   const editor = useBlockNoteEditor<
     BlockSchema,
@@ -68,7 +68,7 @@ export const FileReplaceButton = () => {
       open={isOpen}
       onOpenChange={setIsOpen}
       position={"bottom"}
-      portalRoot={mobileToolbarPortal ?? undefined}
+      portalElement={editorPortalElement}
     >
       <Components.Generic.Popover.Trigger>
         <Components.FormattingToolbar.Button

examples/03-ui-components/20-portal-elements/README.md

@@ -1,8 +1,8 @@
 # Configuring Portal Targets
 
-By default, BlockNote's floating UI elements (formatting toolbar, slash menu, table handles, etc.) mount inside the editor's `bn-container`. The `portalElements` prop on `BlockNoteView` lets you change that — globally via `default`, or per element by key.
+By default, BlockNote's floating components (formatting toolbar, slash menu, table handles, etc.) mount next to the editor, inside its `bn-container` (or inside whatever you render `BlockNoteViewEditor` into). The `portalElements` prop on `BlockNoteView` lets you change that: globally via `default`, or per component by key. The menus and popovers a floating component opens follow it wherever it mounts.
 
-This example renders two editors side-by-side, both wrapped in a small `overflow: hidden` container. The left editor uses the default — the slash menu is clipped by the editor's bounds. The right editor passes `portalElements={{ default: document.body }}` so floating UI escapes the wrapper and renders fully.
+This example renders two editors side-by-side, both wrapped in a small `overflow: hidden` container. The left editor uses the default, so the slash menu is clipped by the editor's bounds. The right editor passes `portalElements={{ default: document.body }}` so the floating components escape the wrapper and render fully.
 
 ```tsx
 <BlockNoteView editor={editor} portalElements={{ default: document.body }} />

examples/07-collaboration/05-comments/src/SettingsSelect.tsx

@@ -1,4 +1,8 @@
-import { ComponentProps, useComponentsContext } from "@blocknote/react";
+import {
+  ComponentProps,
+  useComponentsContext,
+  usePortalElement,
+} from "@blocknote/react";
 
 // This component is used to display a selection dropdown with a label. By using
 // the useComponentsContext hook, we can create it out of existing components
@@ -9,6 +13,10 @@ export const SettingsSelect = (props: {
   items: ComponentProps["FormattingToolbar"]["Select"]["items"];
 }) => {
   const Components = useComponentsContext()!;
+  // The select's dropdown portals into the editor's portal element, which keeps
+  // it themed and clear of any overflow clipping. The prop is required, so it
+  // can't be left out by accident.
+  const portalElement = usePortalElement();
 
   return (
     <div className={"settings-select"}>
@@ -17,6 +25,7 @@ export const SettingsSelect = (props: {
         <Components.Generic.Toolbar.Select
           className={"bn-select"}
           items={props.items}
+          portalElement={portalElement}
         />
       </Components.Generic.Toolbar.Root>
     </div>

examples/07-collaboration/06-comments-with-sidebar/src/SettingsSelect.tsx

@@ -1,4 +1,8 @@
-import { ComponentProps, useComponentsContext } from "@blocknote/react";
+import {
+  ComponentProps,
+  useComponentsContext,
+  usePortalElement,
+} from "@blocknote/react";
 
 // This component is used to display a selection dropdown with a label. By using
 // the useComponentsContext hook, we can create it out of existing components
@@ -9,6 +13,10 @@ export const SettingsSelect = (props: {
   items: ComponentProps["FormattingToolbar"]["Select"]["items"];
 }) => {
   const Components = useComponentsContext()!;
+  // The select's dropdown portals into the editor's portal element, which keeps
+  // it themed and clear of any overflow clipping. The prop is required, so it
+  // can't be left out by accident.
+  const portalElement = usePortalElement();
 
   return (
     <div className={"settings-select"}>
@@ -17,6 +25,7 @@ export const SettingsSelect = (props: {
         <Components.Generic.Toolbar.Select
           className={"bn-select"}
           items={props.items}
+          portalElement={portalElement}
         />
       </Components.Generic.Toolbar.Root>
     </div>

examples/07-collaboration/11-versioning-yjs13/src/SettingsSelect.tsx

@@ -1,4 +1,8 @@
-import { ComponentProps, useComponentsContext } from "@blocknote/react";
+import {
+  ComponentProps,
+  useComponentsContext,
+  usePortalElement,
+} from "@blocknote/react";
 
 // This component is used to display a selection dropdown with a label. By using
 // the useComponentsContext hook, we can create it out of existing components
@@ -9,6 +13,10 @@ export const SettingsSelect = (props: {
   items: ComponentProps["FormattingToolbar"]["Select"]["items"];
 }) => {
   const Components = useComponentsContext()!;
+  // The select's dropdown portals into the editor's portal element, which keeps
+  // it themed and clear of any overflow clipping. The prop is required, so it
+  // can't be left out by accident.
+  const portalElement = usePortalElement();
 
   return (
     <div className={"settings-select"}>
@@ -17,6 +25,7 @@ export const SettingsSelect = (props: {
         <Components.Generic.Toolbar.Select
           className={"bn-select"}
           items={props.items}
+          portalElement={portalElement}
         />
       </Components.Generic.Toolbar.Root>
     </div>

packages/ariakit/src/menu/Menu.tsx

@@ -13,18 +13,19 @@ import { assertEmpty, mergeCSSClasses } from "@blocknote/core";
 import { ComponentProps } from "@blocknote/react";
 import { createContext, forwardRef, useContext } from "react";
 
-// Threads the `portalRoot` override from `Menu` (the provider) down to
-// `MenuDropdown`, where ariakit's `portalElement` prop actually lives.
-const PortalRootContext = createContext<HTMLElement | null | undefined>(
-  undefined,
-);
+// Hands the `portalElement` prop from `Menu` (the root) down to
+// `MenuDropdown`, where Ariakit takes it.
+const MenuPortalElementContext = createContext<HTMLElement | null>(null);
 
 export const Menu = (props: ComponentProps["Generic"]["Menu"]["Root"]) => {
   const {
     children,
     onOpenChange,
     position,
-    portalRoot,
+    portalElement,
+    // ariakit's `virtualFocus` keeps DOM focus on the editor (roving via
+    // `aria-activedescendant`), so there is no focus to suppress here.
+    preventFocusOnOpen: _preventFocusOnOpen,
     sub: _sub, // unused
     ...rest
   } = props;
@@ -37,9 +38,9 @@ export const Menu = (props: ComponentProps["Generic"]["Menu"]["Root"]) => {
       setOpen={onOpenChange}
       virtualFocus={true}
     >
-      <PortalRootContext.Provider value={portalRoot}>
+      <MenuPortalElementContext.Provider value={portalElement}>
         {children}
-      </PortalRootContext.Provider>
+      </MenuPortalElementContext.Provider>
     </AriakitMenuProvider>
   );
 };
@@ -57,13 +58,16 @@ export const MenuDropdown = forwardRef<
 
   assertEmpty(rest);
 
-  const portalRoot = useContext(PortalRootContext);
+  const portalElement = useContext(MenuPortalElementContext);
 
   return (
     <AriakitMenu
       unmountOnHide={true}
       className={mergeCSSClasses("bn-ak-menu", className || "")}
-      portalElement={portalRoot ?? undefined}
+      // Ariakit falls back to a body-appended div for a missing element, so
+      // don't portal at all until there is one (editor not mounted yet).
+      portal={portalElement !== null}
+      portalElement={portalElement}
       ref={ref}
     >
       {children}

packages/ariakit/src/popover/Popover.tsx

@@ -8,9 +8,9 @@ import { assertEmpty, mergeCSSClasses } from "@blocknote/core";
 import { ComponentProps } from "@blocknote/react";
 import { createContext, forwardRef, useContext } from "react";
 
-const PortalRootContext = createContext<HTMLElement | null | undefined>(
-  undefined,
-);
+// Hands the `portalElement` prop from `Popover` (the root) down to
+// `PopoverContent`, where Ariakit takes it.
+const PopoverPortalElementContext = createContext<HTMLElement | null>(null);
 
 export const PopoverTrigger = forwardRef<
   HTMLButtonElement,
@@ -31,7 +31,7 @@ export const PopoverContent = forwardRef<
 
   assertEmpty(rest);
 
-  const portalRoot = useContext(PortalRootContext);
+  const portalElement = useContext(PopoverPortalElementContext);
 
   return (
     <AriakitPopover
@@ -40,7 +40,10 @@ export const PopoverContent = forwardRef<
         className || "",
         variant === "panel-popover" ? "bn-ak-panel-popover" : "",
       )}
-      portalElement={portalRoot ?? undefined}
+      // Ariakit falls back to a body-appended div for a missing element, so
+      // don't portal at all until there is one (editor not mounted yet).
+      portal={portalElement !== null}
+      portalElement={portalElement}
       ref={ref}
     >
       {children}
@@ -51,7 +54,15 @@ export const PopoverContent = forwardRef<
 export const Popover = (
   props: ComponentProps["Generic"]["Popover"]["Root"],
 ) => {
-  const { children, open, onOpenChange, position, portalRoot, ...rest } = props;
+  const {
+    children,
+    open,
+    onOpenChange,
+    position,
+    portalElement,
+    preventFocusOnOpen: _preventFocusOnOpen, // unused; see Menu.tsx
+    ...rest
+  } = props;
 
   assertEmpty(rest);
 
@@ -61,9 +72,9 @@ export const Popover = (
       setOpen={onOpenChange}
       placement={position}
     >
-      <PortalRootContext.Provider value={portalRoot}>
+      <PopoverPortalElementContext.Provider value={portalElement}>
         {children}
-      </PortalRootContext.Provider>
+      </PopoverPortalElementContext.Provider>
     </AriakitPopoverProvider>
   );
 };

packages/ariakit/src/style.css

@@ -38,7 +38,9 @@
     inset 0 1px 1px 1px var(--shadow);
 }
 
-.bn-toolbar .bn-ak-popover {
+/* Form popovers (link, caption, rename) stack their fields; lists keep the
+   tighter spacing. */
+.bn-ariakit .bn-form-popover {
   gap: 0.5rem;
 }
 

packages/ariakit/src/toolbar/ToolbarSelect.tsx

@@ -16,7 +16,14 @@ export const ToolbarSelect = forwardRef<
   HTMLDivElement,
   ComponentProps["FormattingToolbar"]["Select"]
 >((props, ref) => {
-  const { className, items, isDisabled, portalRoot, ...rest } = props;
+  const {
+    className,
+    items,
+    isDisabled,
+    portalElement,
+    preventFocusOnOpen: _preventFocusOnOpen, // unused; see Menu.tsx
+    ...rest
+  } = props;
 
   assertEmpty(rest);
 
@@ -40,7 +47,10 @@ export const ToolbarSelect = forwardRef<
         className={mergeCSSClasses("bn-ak-popover", className || "")}
         ref={ref}
         gutter={4}
-        portalElement={portalRoot ?? undefined}
+        // Ariakit falls back to a body-appended div for a missing element,
+        // so don't portal at all until there is one (editor not mounted yet).
+        portal={portalElement !== null}
+        portalElement={portalElement}
       >
         {items.map((option) => (
           <AriakitSelectItem