Floating portals

• Tooltips raised by an interactable’s tooltipText or tooltipContent, which means every control built on InteractableBase.
• The standalone Tooltip surface.
• ContextMenu and VerticalMenu, which are anchored as focusable tooltip content on their trigger.
• Toasts queued with useToast and rendered by ToastContainer.
• The expanded text surface Modal opens when its subtitle is truncated.

import {useState, type ReactNode} from 'react';
import {FloatingPortalRootProvider} from '@wearables-ui-toolkit/mrbd';
import styles from './EmbeddedSurface.module.css';

export function EmbeddedSurface({children}: {children: ReactNode}) {
  const [portalRoot, setPortalRoot] = useState<HTMLDivElement | null>(null);

  return (
    <div className={styles.surface}>
      <FloatingPortalRootProvider root={portalRoot}>
        {children}
      </FloatingPortalRootProvider>
      <div className={styles.overlayLayer} ref={setPortalRoot} />
    </div>
  );
}

.surface {
  position: relative;
  overflow: hidden;
  border-radius: var(--uit-corner-radius-medium);
  background: var(--uit-color-background-window);
}

.overlayLayer {
  position: absolute;
  inset: 0;
  pointer-events: none;
}

import {useFloatingPortalRoot} from '@wearables-ui-toolkit/mrbd';

const portalRoot: HTMLElement | null = useFloatingPortalRoot();

1. The nearest FloatingPortalRootProvider value — including an explicit null, which is honored rather than falling through.
2. document.body when no provider is present.
3. null when there is no document, so server rendering is safe.

import {createPortal} from 'react-dom';
import {useFloatingPortalRoot} from '@wearables-ui-toolkit/mrbd';
import type {ReactNode} from 'react';

function Overlay({children}: {children: ReactNode}) {
  const portalRoot = useFloatingPortalRoot();
  return portalRoot == null ? null : createPortal(children, portalRoot);
}

• Portalled content stays inside the React tree, so context and React event bubbling keep working across the portal boundary. CSS custom properties are the exception — they cascade through the DOM, not the React tree. The design tokens are declared globally, so a portalled surface is themed correctly wherever its root lives, but a token override scoped to one subtree reaches portalled content only when the portal root sits inside that subtree.
• A popup’s position is measured from its anchor’s viewport rectangle and then re-expressed relative to the portal root: fixed positioning when the root is document.body, and absolute positioning offset by the root’s bounding rectangle otherwise. A scoped root and the document body therefore produce the same on-screen placement.
• Placement is a preference, not a guarantee. The positioning system flips or clamps a surface to keep it inside the visible boundary, so never lay out content assuming a specific side.
• Surfaces in the overlay layer are pointer-transparent themselves; only focusable popup content, such as a context menu or a focusable tooltip, takes pointer events back. That is why the layer as a whole can stay pointer-events: none without breaking the popups it hosts.
• Overlay surfaces are dismissed by Escape and system Back before either reaches route navigation, and focus returns to the control that opened them.
• Focus navigation treats a popup as its own scope: arrow keys move within the popup, and leaving it reports a dismissal reason instead of jumping into page content behind it.

• Let App own the portal root in ordinary applications so all overlays share one coordinate and theme context.
• Create a root only when a host region must clip or own the overlay layer, and keep it pointer-transparent.
• Read the root through useFloatingPortalRoot instead of querying the DOM.
• Guard against null before portalling because the root can be unresolved or unavailable during server rendering.

• Fix the underlying layout rather than portalling the toolkit popups into an arbitrary element to escape it.
• Keep one overlay root per region instead of nesting a second root.
• Treat DOM structure, generated class names, and stacking values as private implementation details.
• The overlay layer must remain pointer-transparent; enabling pointer events on it swallows input meant for covered content.