feat(portal): add PortalProvider for multi-window support in Eclipse Theia (#12)

Introduce PortalProvider context and usePortalRoot hook to configure
portal root elements for floating UI components. This enables proper
rendering of dropdowns, tooltips, and menus in Theia secondary windows.

Changes:
- Add PortalProvider context with usePortalRoot hook
- Update Select, Dropdown, Tooltip, ContextMenu, and ButtonGroup to
  use portal root from context
- Export PortalProvider and related types from main package entry
- Add comprehensive documentation in CLAUDE.md and README.md
- Create dedicated guide pages for VS Code and Eclipse Theia usage
- Update navigation with new guide links

# Conflicts:
#	packages/baukasten/src/components/Tooltip/Tooltip.tsx

Author: praisethemoon

CLAUDE.md

@@ -216,6 +216,9 @@ Current components (exported from `baukasten`):
 - **StatusBar** - VSCode-style status bar
 - **Hero** - Hero section component
 
+**Context Providers:**
+- **PortalProvider** - Configures portal root for multi-window support (Theia secondary windows)
+
 ## Key Technical Details
 
 ### Build System
@@ -593,5 +596,55 @@ export const Button: React.FC<ButtonProps> = ({
        },
      },
    });
-   ```
+ ```
+
+## Multi-Window Support (Eclipse Theia)
+
+### The Portal Problem
+
+Portal-based components (Select, Dropdown, Tooltip, ContextMenu, ButtonGroup) use `FloatingPortal` from `@floating-ui/react` to render floating content. By default, portals render to `document.body` of the main window. In Eclipse Theia's multi-window scenarios, this causes dropdowns opened in secondary/popup windows to appear in the main window instead.
+
+### Solution: PortalProvider
+
+The `PortalProvider` context allows specifying a custom root element for all portal-based components:
+
+```tsx
+import { PortalProvider, Select } from 'baukasten-ui';
+
+function SecondaryWindowContent() {
+const rootRef = useRef<HTMLDivElement>(null);
+const [ready, setReady] = useState(false);
+
+useEffect(() => setReady(true), []);
+
+return (
+ <div ref={rootRef} className="secondary-window-container">
+   {ready && (
+     <PortalProvider root={rootRef.current}>
+       {/* All dropdowns, tooltips, etc. will render in this window */}
+       <Select options={options} />
+       <Dropdown trigger={<Button>Menu</Button>}>
+         <Menu>...</Menu>
+       </Dropdown>
+     </PortalProvider>
+   )}
+ </div>
+);
+}
+```
+
+### Components Using PortalProvider
+
+These components respect the `PortalProvider` context:
+- **Select** - Dropdown options list
+- **Dropdown** - Generic dropdown container
+- **Tooltip** - Hover tooltips
+- **ContextMenu** - Right-click menus
+- **ButtonGroup.Dropdown** - Split button dropdowns
+
+### Implementation Notes
+
+1. **Backward Compatible**: If `PortalProvider` is not used, components fall back to default portal behavior (`document.body`)
+2. **Hook**: Use `usePortalRoot()` hook to access the portal root in custom components
+3. **Context Location**: Defined in `packages/baukasten/src/context/PortalProvider.tsx`
 

packages/baukasten/README.md

@@ -91,6 +91,78 @@ import 'baukasten-ui/dist/baukasten-theia.css';  // For Eclipse Theia
 import 'baukasten-ui/dist/baukasten-web.css';    // For standalone web apps
 ```
 
+## Usage in Eclipse Theia
+
+### Basic Setup
+
+Eclipse Theia applications use the Theia-specific CSS file:
+
+```tsx
+import { Button, Input, Badge } from 'baukasten-ui';
+import 'baukasten-ui/dist/baukasten-base.css';
+import 'baukasten-ui/dist/baukasten-theia.css';
+
+function App() {
+  return (
+    <div>
+      <Button variant="primary">Click me</Button>
+      <Input label="Username" placeholder="Enter username" />
+    </div>
+  );
+}
+```
+
+### Multi-Window Support (Secondary Windows)
+
+When using Baukasten in Theia secondary/popup windows, portal-based components (Select, Dropdown, Tooltip, etc.) need a `PortalProvider` to ensure dropdowns render in the correct window:
+
+```tsx
+import { useRef, useState, useEffect } from 'react';
+import { PortalProvider, Select, Dropdown, Button } from 'baukasten-ui';
+import 'baukasten-ui/dist/baukasten-base.css';
+import 'baukasten-ui/dist/baukasten-theia.css';
+
+function SecondaryWindowContent() {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const [ready, setReady] = useState(false);
+  
+  // Wait for ref to be available
+  useEffect(() => setReady(true), []);
+  
+  return (
+    <div ref={rootRef} style={{ height: '100%' }}>
+      {ready && (
+        <PortalProvider root={rootRef.current}>
+          {/* All portal content will now render in this window */}
+          <Select
+            options={[
+              { value: '1', label: 'Option 1' },
+              { value: '2', label: 'Option 2' },
+            ]}
+            placeholder="Select an option"
+          />
+          
+          <Dropdown trigger={<Button>Open Menu</Button>}>
+            <div>Menu content</div>
+          </Dropdown>
+        </PortalProvider>
+      )}
+    </div>
+  );
+}
+```
+
+**Why is this needed?**
+
+By default, portal-based components render floating content (dropdowns, tooltips) to the main window's `document.body`. In Theia's secondary windows, this causes the content to appear on the wrong window. The `PortalProvider` redirects portal content to the correct window.
+
+**Components that use portals:**
+- `Select` - dropdown options
+- `Dropdown` - dropdown content
+- `Tooltip` - tooltip popups
+- `ContextMenu` - right-click menus
+- `ButtonGroup.Dropdown` - split button menus
+
 ## Components
 
 ### Button

packages/baukasten/src/components/ButtonGroup/ButtonGroup.tsx

@@ -18,6 +18,7 @@ import {
 import { type Size } from '../../styles';
 import { Button, type ButtonVariant } from '../Button';
 import { Icon } from '../Icon';
+import { usePortalRoot } from '../../context';
 import {
   buttonGroup,
   dropdownTriggerWrapper,
@@ -280,6 +281,9 @@ const ButtonGroupDropdown: React.FC<ButtonGroupDropdownProps> = ({
     }
   }, [closeOnClick, isControlled, onOpenChange]);
 
+  // Get portal root from context (for multi-window support)
+  const portalRoot = usePortalRoot();
+
   return (
     <>
       <div
@@ -302,7 +306,7 @@ const ButtonGroupDropdown: React.FC<ButtonGroupDropdownProps> = ({
 
       {/* Portal with transition support for exit animations */}
       {isMounted && (
-        <FloatingPortal>
+        <FloatingPortal root={portalRoot}>
           <FloatingFocusManager context={context} modal={false}>
             <div
               ref={refs.setFloating}

packages/baukasten/src/components/ContextMenu/ContextMenu.tsx

@@ -13,6 +13,7 @@ import {
 } from '@floating-ui/react';
 import { Menu } from '../Menu';
 import type { MenuProps } from '../Menu';
+import { usePortalRoot } from '../../context';
 import { menuWrapper, styledMenu, triggerWrapper } from './ContextMenu.css';
 
 /**
@@ -169,6 +170,9 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
     setIsOpen(false);
   }, []);
 
+  // Get portal root from context (for multi-window support)
+  const portalRoot = usePortalRoot();
+
   return (
     <>
       <div className={triggerWrapper} onContextMenu={handleContextMenu}>
@@ -177,7 +181,7 @@ export const ContextMenu: React.FC<ContextMenuProps> = ({
 
       {/* Portal with transition support for exit animations */}
       {isMounted && (
-        <FloatingPortal>
+        <FloatingPortal root={portalRoot}>
           <FloatingFocusManager context={context} modal={false}>
             <div
               ref={refs.setFloating}

packages/baukasten/src/components/Dropdown/Dropdown.tsx

@@ -15,6 +15,7 @@ import {
   FloatingFocusManager,
   type Placement,
 } from '@floating-ui/react';
+import { usePortalRoot } from '../../context';
 import { dropdownWrapper, triggerWrapper, portalContent } from './Dropdown.css';
 
 /**
@@ -238,6 +239,9 @@ export const Dropdown: React.FC<DropdownProps> = ({
     }
   }, [closeOnClick, isControlled, onOpenChange]);
 
+  // Get portal root from context (for multi-window support)
+  const portalRoot = usePortalRoot();
+
   return (
     <>
       <div
@@ -252,7 +256,7 @@ export const Dropdown: React.FC<DropdownProps> = ({
 
       {/* Portal with transition support for exit animations */}
       {isMounted && (
-        <FloatingPortal>
+        <FloatingPortal root={portalRoot}>
           <FloatingFocusManager context={context} modal={modal}>
             <div
               ref={refs.setFloating}

packages/baukasten/src/components/Select/Select.tsx

@@ -16,6 +16,7 @@ import {
 } from '@floating-ui/react';
 import { type Size } from '../../styles';
 import { Icon } from '../Icon';
+import { usePortalRoot } from '../../context';
 import * as styles from './Select.css';
 
 // Floating UI numeric values (required by Floating UI API)
@@ -535,6 +536,9 @@ export function Select<T = string>({
 
   // Floating UI handles click-outside and position updates automatically via autoUpdate and useDismiss
 
+  // Get portal root from context (for multi-window support)
+  const portalRoot = usePortalRoot();
+
   const containerClassName = className
     ? `${styles.selectContainer({ fullWidth })} ${className}`
     : styles.selectContainer({ fullWidth });
@@ -574,7 +578,7 @@ export function Select<T = string>({
       </button>
 
       {isMounted && (
-        <FloatingPortal>
+        <FloatingPortal root={portalRoot}>
           <div
             ref={refs.setFloating}
             className={`${styles.floatingWrapper}${dropdownClassName ? ` ${dropdownClassName}` : ''}`}

packages/baukasten/src/components/Tooltip/Tooltip.tsx

@@ -16,6 +16,7 @@ import {
   type Placement,
 } from '@floating-ui/react';
 import React, { useRef, useState } from 'react';
+import { usePortalRoot } from '../../context';
 import * as styles from './Tooltip.css';
 
 // Floating UI numeric values (required by Floating UI API)
@@ -207,6 +208,8 @@ export const Tooltip: React.FC<TooltipProps> = ({
     error: 'var(--bk-color-danger)',
     info: 'var(--bk-color-info)',
   }[variant];
+  // Get portal root from context (for multi-window support)
+  const portalRoot = usePortalRoot();
 
   return (
     <>
@@ -219,7 +222,7 @@ export const Tooltip: React.FC<TooltipProps> = ({
       </div>
 
       {isMounted && (
-        <FloatingPortal>
+        <FloatingPortal root={portalRoot}>
           <div
             ref={refs.setFloating}
             style={{