fix(playground-ui): make popup portal container resolution null-safe (#17560)

## Summary
Follow-up hardening to #17556. Base UI's `FloatingPortal` treats
`container={null}` as *"not ready — render nothing"*, while `undefined`
means *"portal to `document.body`"*. Our `PortalContainerContext`
defaulted to `null`, so popups opened outside a `SideDialog` (the model
& provider pickers live in the chat composer, which has no
`PortalContainerProvider` ancestor) resolved their portal container to
`null` and mounted to no DOM node — they opened in state but rendered
nowhere.

## Change
- `usePortalContainer(container?)` now resolves `explicit → provider →
undefined` and **never returns `null`**; the "no container" sentinel is
`undefined` to match Base UI's contract.
- Dropped the scattered `?? undefined` band-aids in `Combobox`,
`Select`, `Popover`, and `DropdownMenu` — they now just call
`usePortalContainer(container)`.

## Tests
- `portal-container.test.tsx` guards the resolver contract (never
`null`; normalizes a `null` provider; explicit wins).
- `combobox.test.tsx` asserts the popup portals into `document.body`.
- Verified these fail under the old `null`-leaking behavior (combobox
open/select tests go red) and pass with the fix.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## ELI5

Imagine a magical doorway that decides where popup menus (like dropdowns
and options) should appear on the screen. This PR fixes a broken doorway
that prevented popups from showing up when opened outside certain
panels—now the doorway always works and shows popups in the right place
(the main document area) as a fallback.

## Problem

Base UI's FloatingPortal treats `container={null}` as "not ready —
render nothing" while `undefined` means "portal to document.body". The
PortalContainerContext was defaulting to `null`, which caused popups
opened outside a SideDialog (such as model and provider pickers in the
chat composer) to fail rendering because there was no valid DOM node to
attach to.

## Solution

The `usePortalContainer` hook was redesigned to:
- Accept an optional `container` parameter that can explicitly override
the default behavior
- Resolve the final portal target with precedence: explicit argument →
context provider value → `undefined`
- Never return `null`; always return `undefined` as the "no container"
sentinel to match Base UI's expectations

The PortalContainerContext now treats `undefined` as the default (fall
back to document.body) and normalizes any incoming `null` values to
`undefined`.

## Changes Made

- **portal-container.tsx**: Added `PortalContainer` type, updated
`usePortalContainer` to accept an optional container override and
exclude null from its return type, and normalized null values in the
provider context
- **Combobox, Select, Popover, and DropdownMenu**: Replaced manual
fallback logic (`container ?? portalContainer ?? undefined`) with direct
calls to `usePortalContainer(container)`
- **portal-container.test.tsx**: Added comprehensive tests asserting the
resolver contract (never returns null, normalizes null provider to
undefined, explicit values override provider values)
- **combobox.test.tsx**: Added test verifying popups mount into
`document.body` when no portal container provider is present

## Testing

Tests were added to verify the contract of the portal-container resolver
and confirm that popups now mount correctly when opened outside a
SideDialog. Tests were verified to fail under the previous null-leaking
behavior and pass with the fix.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: damien-schneider

.changeset/proud-gifts-appear.md

@@ -0,0 +1,5 @@
+---
+'@mastra/playground-ui': patch
+---
+
+Fixed dropdown, combobox, select, and popover popups silently failing to render when opened outside a side panel (most visibly the model and provider pickers in the chat composer). The shared portal-container resolver now always falls back to the document body instead of leaking an unrenderable value.

packages/playground-ui/src/ds/components/Combobox/combobox.test.tsx

@@ -45,6 +45,20 @@ describe('Combobox', () => {
     expect(screen.getByRole('option', { name: 'Google' })).toBeTruthy();
   });
 
+  it('portals the popup into document.body when there is no portal container provider', async () => {
+    const { container } = renderCombobox();
+
+    fireEvent.click(screen.getByRole('combobox'));
+
+    // The regression: outside a SideDialog the portal container resolved to
+    // `null`, which Base UI's FloatingPortal reads as "render nothing", so the
+    // popup never mounted. It must land in document.body, outside the trigger's
+    // own subtree.
+    const option = await screen.findByRole('option', { name: 'OpenAI' });
+    expect(document.body.contains(option)).toBe(true);
+    expect(container.contains(option)).toBe(false);
+  });
+
   it('selects an item and fires onValueChange with the selected value', async () => {
     const onValueChange = vi.fn();
     renderCombobox({ onValueChange });

packages/playground-ui/src/ds/components/Combobox/combobox.tsx

@@ -60,8 +60,7 @@ export function Combobox({
 
   // Default to the nearest SideDialog/Drawer popup so the list stays
   // interactive inside a modal drawer; an explicit `container` still wins.
-  const portalContainer = usePortalContainer();
-  const resolvedContainer = container ?? portalContainer ?? undefined;
+  const resolvedContainer = usePortalContainer(container);
 
   const handleSelect = (item: ComboboxOption | null) => {
     if (item) {

packages/playground-ui/src/ds/components/DropdownMenu/dropdown-menu.tsx

@@ -79,9 +79,9 @@ const DropdownMenuSubContent = React.forwardRef<HTMLDivElement, DropdownMenuSubC
   ({ className, align = 'start', alignOffset = -4, side = 'right', sideOffset = 0, ...props }, ref) => {
     // Default to the nearest SideDialog/Drawer popup so the submenu stays
     // interactive inside a modal drawer.
-    const portalContainer = usePortalContainer();
+    const resolvedContainer = usePortalContainer();
     return (
-      <MenuPrimitive.Portal container={portalContainer ?? undefined}>
+      <MenuPrimitive.Portal container={resolvedContainer}>
         <MenuPrimitive.Positioner
           align={align}
           alignOffset={alignOffset}
@@ -111,8 +111,7 @@ const DropdownMenuContent = React.forwardRef<HTMLDivElement, DropdownMenuContent
   ({ className, container, align = 'start', alignOffset = 0, side = 'bottom', sideOffset = 8, ...props }, ref) => {
     // Default to the nearest SideDialog/Drawer popup so the menu stays
     // interactive inside a modal drawer; an explicit `container` still wins.
-    const portalContainer = usePortalContainer();
-    const resolvedContainer = container ?? portalContainer ?? undefined;
+    const resolvedContainer = usePortalContainer(container);
     return (
       <MenuPrimitive.Portal container={resolvedContainer}>
         <MenuPrimitive.Positioner

packages/playground-ui/src/ds/components/Popover/popover.tsx

@@ -34,11 +34,10 @@ const PopoverContent = React.forwardRef<HTMLDivElement, PopoverContentProps>(
     const classNameString = typeof className === 'string' ? className : undefined;
     // Default to the nearest SideDialog/Drawer popup so the content stays
     // interactive inside a modal drawer; an explicit `container` still wins.
-    const portalContainer = usePortalContainer();
-    const resolvedContainer = container ?? portalContainer;
+    const resolvedContainer = usePortalContainer(container);
 
     return (
-      <PopoverPrimitive.Portal container={resolvedContainer ?? undefined}>
+      <PopoverPrimitive.Portal container={resolvedContainer}>
         <PopoverPrimitive.Positioner
           align={align}
           alignOffset={alignOffset}

packages/playground-ui/src/ds/components/Select/select.tsx

@@ -158,10 +158,9 @@ const SelectContent = React.forwardRef<HTMLDivElement, SelectContentProps>(
   ) => {
     // Default to the nearest SideDialog/Drawer popup so the dropdown stays
     // interactive inside a modal drawer; an explicit `container` still wins.
-    const portalContainer = usePortalContainer();
-    const resolvedContainer = container ?? portalContainer;
+    const resolvedContainer = usePortalContainer(container);
     return (
-      <SelectPrimitive.Portal container={resolvedContainer ?? undefined}>
+      <SelectPrimitive.Portal container={resolvedContainer}>
         <SelectPrimitive.Positioner
           className="z-50 outline-none"
           side={side}

packages/playground-ui/src/ds/primitives/portal-container.test.tsx

@@ -0,0 +1,59 @@
+// @vitest-environment jsdom
+import { renderHook } from '@testing-library/react';
+import * as React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { PortalContainerProvider, usePortalContainer } from './portal-container';
+
+/**
+ * These guard the contract that prevented the model-picker regression:
+ * `usePortalContainer` must resolve "no container" to `undefined`, never `null`.
+ *
+ * Base UI's `FloatingPortal` reads `container={undefined}` as "portal to
+ * document.body" but `container={null}` as "not ready — render nothing". If the
+ * resolver ever returns `null` again, dropdowns/combobox popups open in state but
+ * mount to no DOM node, and these tests fail.
+ */
+describe('usePortalContainer', () => {
+  it('returns undefined (NOT null) when there is no provider', () => {
+    const { result } = renderHook(() => usePortalContainer());
+    expect(result.current).toBeUndefined();
+    expect(result.current).not.toBeNull();
+  });
+
+  it('normalizes a null provider value to undefined', () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <PortalContainerProvider container={null}>{children}</PortalContainerProvider>
+    );
+    const { result } = renderHook(() => usePortalContainer(), { wrapper });
+    expect(result.current).toBeUndefined();
+  });
+
+  it('returns the provider container when one is set', () => {
+    const node = document.createElement('div');
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <PortalContainerProvider container={node}>{children}</PortalContainerProvider>
+    );
+    const { result } = renderHook(() => usePortalContainer(), { wrapper });
+    expect(result.current).toBe(node);
+  });
+
+  it('lets an explicit container win over the provider', () => {
+    const provided = document.createElement('div');
+    const explicit = document.createElement('section');
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <PortalContainerProvider container={provided}>{children}</PortalContainerProvider>
+    );
+    const { result } = renderHook(() => usePortalContainer(explicit), { wrapper });
+    expect(result.current).toBe(explicit);
+  });
+
+  it('coerces an explicit null container to undefined (falls back to provider)', () => {
+    const provided = document.createElement('div');
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <PortalContainerProvider container={provided}>{children}</PortalContainerProvider>
+    );
+    const { result } = renderHook(() => usePortalContainer(null), { wrapper });
+    expect(result.current).toBe(provided);
+  });
+});

packages/playground-ui/src/ds/primitives/portal-container.tsx

@@ -1,22 +1,22 @@
 /* eslint-disable react-refresh/only-export-components */
 import * as React from 'react';
 
-/**
- * Lets a modal container (e.g. `SideDialog`'s `Drawer`) advertise a DOM node
- * that nested portaled popups should render into instead of `document.body`.
- *
- * Why this exists: Base UI's modal `Drawer` wraps its contents in a
- * `FloatingFocusManager` with `modal`, which traps focus/interaction inside the
- * drawer's floating element. A popup portaled to `document.body` (the default
- * for `Select`, `Popover`, `DropdownMenu`, `Combobox`) lands *outside* that
- * region and becomes unclickable. Portaling it into a node inside the drawer
- * keeps it within the modal region, so it stays interactive.
- *
- * Portaled components default their portal `container` to this value, so any
- * dropdown placed inside a `SideDialog` works without per-call wiring. A `null`
- * value (the default, outside any provider) means "fall back to document.body".
- */
-const PortalContainerContext = React.createContext<HTMLElement | null>(null);
+/** Anything Base UI's `*.Portal` `container` accepts. */
+export type PortalContainer =
+  | HTMLElement
+  | ShadowRoot
+  | React.RefObject<HTMLElement | ShadowRoot | null>
+  | null
+  | undefined;
+
+// Why: modal SideDialog/Drawer traps focus+clicks inside its region. Popups portal to
+// document.body by default → land outside the trap → unclickable. SideDialog publishes a
+// node inside the trap; popups portal there instead.
+//
+// Sentinel is `undefined`, never `null`: Base UI reads container={undefined} as "portal to
+// body", but container={null} as "not ready, render nothing" — a leaked null opens the popup
+// in state but mounts it nowhere (the model-picker bug).
+const PortalContainerContext = React.createContext<HTMLElement | undefined>(undefined);
 
 export function PortalContainerProvider({
   container,
@@ -25,10 +25,12 @@ export function PortalContainerProvider({
   container: HTMLElement | null;
   children: React.ReactNode;
 }) {
-  return <PortalContainerContext.Provider value={container}>{children}</PortalContainerContext.Provider>;
+  // Accept null for callers; normalize so null never reaches a portal.
+  return <PortalContainerContext.Provider value={container ?? undefined}>{children}</PortalContainerContext.Provider>;
 }
 
-/** Nearest portal container node, or `null` to fall back to `document.body`. */
-export function usePortalContainer(): HTMLElement | null {
-  return React.useContext(PortalContainerContext);
+/** Resolve a popup's portal target: explicit `container` → provider → `undefined` (body). Never null. */
+export function usePortalContainer(container?: PortalContainer): Exclude<PortalContainer, null> {
+  const fromContext = React.useContext(PortalContainerContext);
+  return container ?? fromContext ?? undefined;
 }