Popover Glass

1/**
2 * PopoverGlass Component
3 *
4 * Floating glass-themed container for tooltips, dropdowns, and contextual overlays.
5 * Provides compound and legacy APIs for maximum flexibility.
6 *
7 * ## Features
8 * - Theme-aware glassmorphism styling (glass/light/aurora)
9 * - Compound component API (PopoverGlass.Root, Trigger, Content, Anchor, Close)
10 * - Legacy API for backward compatibility
11 * - Arrow pointer with glass styling (optional)
12 * - 12 positioning options (4 sides × 3 alignments)
13 * - Smooth animations with fade-in effect
14 * - ESC key and click-outside to close
15 * - Focus trap for accessibility
16 * - Customizable width and padding via className
17 * - Portal rendering for z-index isolation
18 *
19 * ## Sub-Components
20 * - **PopoverGlass.Root** (or `PopoverGlass`) - Context provider with open/close state
21 * - **PopoverGlassTrigger** - Trigger element (supports asChild pattern)
22 * - **PopoverGlassAnchor** - Optional anchor for positioning
23 * - **PopoverGlassContent** - Content container with glass styling
24 * - **PopoverGlassLegacy** - Legacy wrapper API (backward compatible)
25 *
26 * ## CSS Variables
27 * Customize appearance via theme CSS variables:
28 * - `--popover-bg` - Background color (glass theme: `rgba(255,255,255,0.08)`)
29 * - `--popover-border` - Border color (glass theme: `rgba(255,255,255,0.15)`)
30 * - `--popover-shadow` - Box shadow with glow effect
31 * - `--popover-arrow-bg` - Arrow pointer background color
32 * - `--blur-md` - Backdrop blur amount (default: `16px`)
33 *
34 * @example Compound API (recommended)
35 * ```tsx
36 * import { PopoverGlass, PopoverGlassTrigger, PopoverGlassContent } from 'shadcn-glass-ui'
37 *
38 * <PopoverGlass>
39 *   <PopoverGlassTrigger asChild>
40 *     <ButtonGlass>Open Popover</ButtonGlass>
41 *   </PopoverGlassTrigger>
42 *   <PopoverGlassContent side="top">
43 *     <div className="p-4">
44 *       <h3 style={{ color: 'var(--text-primary)' }}>Title</h3>
45 *       <p style={{ color: 'var(--text-secondary)' }}>Content</p>
46 *     </div>
47 *   </PopoverGlassContent>
48 * </PopoverGlass>
49 * ```
50 *
51 * @example Legacy API (backward compatible)
52 * ```tsx
53 * import { PopoverGlassLegacy } from 'shadcn-glass-ui'
54 *
55 * <PopoverGlassLegacy
56 *   trigger={<ButtonGlass>Open</ButtonGlass>}
57 *   side="top"
58 * >
59 *   <div className="p-4">Content</div>
60 * </PopoverGlassLegacy>
61 * ```
62 *
63 * @example Controlled state
64 * ```tsx
65 * const [open, setOpen] = useState(false)
66 *
67 * <PopoverGlass open={open} onOpenChange={setOpen}>
68 *   <PopoverGlassTrigger>Open</PopoverGlassTrigger>
69// … truncated