@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/components/core/Drawer/Drawer.types.d.ts

@@ -1,10 +1,13 @@
 import React from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export type DrawerPosition = "left" | "right" | "top" | "bottom";
-export type DrawerSize = "md" | "lg" | "full";
+export type DrawerSizeToken = "sm" | "md" | "lg" | "full";
+/** Preset size token or any arbitrary Tailwind width/height class, e.g. `"w-80"`, `"w-[50vw]"` */
+export type DrawerSize = DrawerSizeToken | (string & {});
 export interface DrawerTheme {
     overlay: string;
     container: string;
-    content: string;
+    inner: string;
     header: string;
     headerContent: string;
     title: string;
@@ -15,7 +18,7 @@ export interface DrawerTheme {
 export interface DrawerThemeOverrides {
     overlay?: string;
     container?: string;
-    content?: string;
+    inner?: string;
     header?: string;
     headerContent?: string;
     title?: string;
@@ -39,9 +42,9 @@ export interface DrawerProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     isOpen: boolean;
     onClose: () => void;
     /** Title text displayed in the drawer header */
-    title?: string;
+    title?: React.ReactNode;
     /** Subtitle text displayed below the title */
-    subtitle?: string;
+    subtitle?: React.ReactNode;
     /** Icon displayed to the left of the title/description */
     icon?: React.ReactNode;
     position?: DrawerPosition;
@@ -52,6 +55,13 @@ export interface DrawerProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     children: React.ReactNode;
     className?: string;
     theme?: DrawerThemeOverrides;
+    /**
+     * Pin the surface elevation rung (overrides the automatic relative lift).
+     * A rung number (1–8) or a semantic alias ("surface"/"raised"/"overlay"…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the drawer's base rung. */
+    lift?: boolean;
     /**
      * Scale factor for the background content when the drawer is open.
      * Creates an iOS-style modal presentation where the page scales down.
@@ -60,6 +70,12 @@ export interface DrawerProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
      * @default 0.94
      */
     scale?: number;
+    /**
+     * When enabled, pressing the browser back button closes the drawer
+     * instead of navigating away. Useful for mobile-like UX.
+     * @default false
+     */
+    closeOnBack?: boolean;
 }
 export interface DrawerHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
     children: React.ReactNode;
@@ -70,12 +86,14 @@ export interface DrawerHeaderProps extends React.HTMLAttributes<HTMLDivElement>
 export interface DrawerTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
     children: React.ReactNode;
     className?: string;
+    /** Heading level to render. Defaults to 'h2'. */
+    as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 }
 export interface DrawerSubtitleProps extends React.HTMLAttributes<HTMLParagraphElement> {
     children: React.ReactNode;
     className?: string;
 }
-export interface DrawerContentProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface DrawerBodyProps extends React.HTMLAttributes<HTMLDivElement> {
     children: React.ReactNode;
     className?: string;
 }

package/dist/components/core/Drawer/DrawerBody.d.ts

@@ -0,0 +1,5 @@
+import { DrawerBodyProps } from "./Drawer.types";
+export declare const DrawerBody: {
+    ({ children, className, ...props }: DrawerBodyProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/core/Drawer/{DrawerContent.js → DrawerBody.js}

@@ -1,11 +1,12 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 
-const DrawerContent = ({ children, className, ...props }) => {
+const DrawerBody = ({ children, className, ...props }) => {
     const { theme } = useDrawerContext();
     return (jsx("div", { className: cn(theme.body, className), ...props, children: children }));
 };
-DrawerContent.displayName = "Drawer.Content";
+DrawerBody.displayName = "Drawer.Body";
 
-export { DrawerContent };
+export { DrawerBody };

package/dist/components/core/Drawer/DrawerContext.d.ts

@@ -0,0 +1,3 @@
+import { DrawerContextValue } from "./Drawer.types";
+export declare const DrawerContext: import("react").Context<DrawerContextValue | undefined>;
+export declare const useDrawerContext: () => DrawerContextValue;

package/dist/components/core/Drawer/DrawerContext.js

@@ -0,0 +1,15 @@
+"use client";
+import { createContext, useContext } from 'react';
+
+// Lives in its own module (not Drawer.tsx) so sub-components can consume the
+// context without importing Drawer.tsx, which imports them back (circular dep).
+// Drawer.tsx re-exports `useDrawerContext`, so `from "./Drawer"` keeps working.
+const DrawerContext = createContext(undefined);
+const useDrawerContext = () => {
+    const ctx = useContext(DrawerContext);
+    if (!ctx)
+        throw new Error("Drawer compound components must be used within <Drawer>");
+    return ctx;
+};
+
+export { DrawerContext, useDrawerContext };

package/dist/components/core/Drawer/DrawerFooter.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 
 const DrawerFooter = ({ children, className, ...props }) => {
     const { theme } = useDrawerContext();

package/dist/components/core/Drawer/DrawerHeader.js

@@ -1,13 +1,15 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 import { Button } from '../Button/Button.js';
+import 'react';
 import { XMarkIcon } from '@heroicons/react/24/outline';
 
 const DrawerHeader = ({ children, icon, showCloseButton, className, ...props }) => {
     const { onClose, showCloseButton: contextShowCloseButton, theme, } = useDrawerContext();
     const shouldShowCloseButton = showCloseButton !== null && showCloseButton !== void 0 ? showCloseButton : contextShowCloseButton;
-    return (jsxs("div", { className: cn(theme.header, className), ...props, children: [jsxs("div", { className: cn(theme.headerContent), children: [icon && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-secondary)]", children: icon })), jsx("div", { className: "flex-1 min-w-0", children: children })] }), shouldShowCloseButton && (jsx(Button, { color: "neutral", variant: "ghost", iconOnly: true, size: "sm", onClick: onClose, "aria-label": "Close drawer", className: "rounded-full shrink-0", children: jsx(XMarkIcon, { className: "size-5" }) }))] }));
+    return (jsxs("div", { className: cn(theme.header, className), ...props, children: [jsxs("div", { className: cn(theme.headerContent), children: [icon && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-secondary)]", children: icon })), jsx("div", { className: "flex-1 min-w-0", children: children })] }), shouldShowCloseButton && (jsx(Button, { color: "neutral", variant: "outline", iconOnly: true, size: "sm", onClick: onClose, "aria-label": "Close drawer", className: "rounded-full shrink-0", children: jsx(XMarkIcon, { className: "size-4" }) }))] }));
 };
 DrawerHeader.displayName = "Drawer.Header";
 

package/dist/components/core/Drawer/DrawerSubtitle.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 
 const DrawerSubtitle = ({ children, className, ...props }) => {
     const { theme, subtitleId } = useDrawerContext();

package/dist/components/core/Drawer/DrawerTitle.d.ts

@@ -1,5 +1,5 @@
 import { DrawerTitleProps } from "./Drawer.types";
 export declare const DrawerTitle: {
-    ({ children, className, ...props }: DrawerTitleProps): import("react/jsx-runtime").JSX.Element;
+    ({ children, className, as: Tag, ...props }: DrawerTitleProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/components/core/Drawer/DrawerTitle.js

@@ -1,10 +1,11 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 
-const DrawerTitle = ({ children, className, ...props }) => {
+const DrawerTitle = ({ children, className, as: Tag = 'h2', ...props }) => {
     const { theme, titleId } = useDrawerContext();
-    return (jsx("div", { id: titleId, className: cn(theme.title, className), ...props, children: children }));
+    return (jsx(Tag, { id: titleId, className: cn(theme.title, className), ...props, children: children }));
 };
 DrawerTitle.displayName = "Drawer.Title";
 

package/dist/components/core/Drawer/index.d.ts

@@ -1,2 +1,3 @@
 export { Drawer } from "./Drawer";
-export type { DrawerProps, DrawerPosition, DrawerSize, DrawerThemeOverrides, DrawerHeaderProps, DrawerTitleProps, DrawerSubtitleProps, } from "./Drawer.types";
+export { DrawerBody } from "./DrawerBody";
+export type { DrawerProps, DrawerPosition, DrawerSize, DrawerThemeOverrides, DrawerHeaderProps, DrawerTitleProps, DrawerSubtitleProps, DrawerBodyProps, DrawerFooterProps, } from "./Drawer.types";

package/dist/components/core/Dropdown/Dropdown.d.ts

@@ -5,7 +5,7 @@ export declare const Dropdown: {
     displayName: string;
 } & {
     Trigger: {
-        ({ children, className }: import("./Dropdown.types").DropdownTriggerProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+        ({ children, className }: import("./Dropdown.types").DropdownTriggerProps): React.ReactElement<import("./DropdownTrigger").TriggerChildProps, string | React.JSXElementConstructor<any>>;
         displayName: string;
     };
     Menu: React.ForwardRefExoticComponent<import("./Dropdown.types").DropdownMenuProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/Dropdown/Dropdown.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import { useState, useRef, useCallback } from 'react';
+import { useState, useMemo, useRef, useId, useCallback } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { DropdownContext } from './DropdownContext.js';
 import { DropdownTrigger } from './DropdownTrigger.js';
@@ -35,12 +36,13 @@ const DropdownRoot = ({ children, className, isOpen: controlledIsOpen, defaultIs
     const isControlledOpen = controlledIsOpen !== undefined;
     const isOpen = isControlledOpen ? controlledIsOpen : uncontrolledIsOpen;
     const isControlledSelection = controlledSelectedKeys !== undefined;
-    const selectedKeys = isControlledSelection
-        ? new Set(controlledSelectedKeys)
-        : uncontrolledSelectedKeys;
+    const selectedKeys = useMemo(() => (isControlledSelection ? new Set(controlledSelectedKeys) : uncontrolledSelectedKeys), [isControlledSelection, controlledSelectedKeys, uncontrolledSelectedKeys]);
     // Refs for positioning
     const triggerRef = useRef(null);
     const menuRef = useRef(null);
+    // Generate a stable menu ID for aria-controls
+    const generatedMenuId = useId();
+    const menuId = `dropdown-menu-${generatedMenuId}`;
     // Handle open state changes
     const handleOpenChange = useCallback((value) => {
         if (!isControlledOpen) {
@@ -56,18 +58,19 @@ const DropdownRoot = ({ children, className, isOpen: controlledIsOpen, defaultIs
         onSelectionChange === null || onSelectionChange === void 0 ? void 0 : onSelectionChange(Array.from(keys));
     }, [isControlledSelection, onSelectionChange]);
     // Merge theme with overrides
-    const theme = {
+    const theme = useMemo(() => ({
         ...dropdownTheme,
         ...(themeOverrides || {}),
-    };
+    }), [themeOverrides]);
     // Convert disabled keys array to Set
-    const disabledKeysSet = new Set(disabledKeys);
+    const disabledKeysSet = useMemo(() => new Set(disabledKeys), [disabledKeys]);
     // Context value
-    const contextValue = {
+    const contextValue = useMemo(() => ({
         isOpen,
         onOpenChange: handleOpenChange,
         triggerRef,
         menuRef,
+        menuId,
         placement,
         offset,
         closeOnSelect,
@@ -77,8 +80,23 @@ const DropdownRoot = ({ children, className, isOpen: controlledIsOpen, defaultIs
         onAction,
         onSelectionChange: handleSelectionChange,
         theme,
-    };
-    return (jsx(DropdownContext.Provider, { value: contextValue, children: jsx("div", { className: cn("dropdown", darkMode && "dark", className), "data-state": isOpen ? "open" : "closed", ...props, children: children }) }));
+    }), [
+        isOpen,
+        handleOpenChange,
+        triggerRef,
+        menuRef,
+        menuId,
+        placement,
+        offset,
+        closeOnSelect,
+        disabledKeysSet,
+        selectedKeys,
+        selectionMode,
+        onAction,
+        handleSelectionChange,
+        theme,
+    ]);
+    return (jsx(DropdownContext.Provider, { value: contextValue, children: jsx("div", { className: cn("dropdown contents", darkMode && "dark", className), "data-state": isOpen ? "open" : "closed", ...props, children: children }) }));
 };
 DropdownRoot.displayName = "Dropdown";
 // Export as a unified component with sub-components

package/dist/components/core/Dropdown/Dropdown.theme.js

@@ -1,20 +1,20 @@
 import { menuItemTheme } from '../MenuItem/MenuItem.theme.js';
 
 const dropdownTheme = {
-    // Menu container - similar to Popover but with menu-specific styling
-    menuStyle: "min-w-[200px] max-h-[400px] overflow-y-auto rounded-[var(--dropdown-radius)] border border-[var(--color-border)] bg-white shadow-real-xl focus:outline-none flex disabled:cursor-not-allowed " +
-        "dark:bg-[var(--color-background-secondary)]",
+    // Menu container - similar to Popover but with menu-specific styling.
+    // bg + shadow come from the relative-elevation engine (surfaceClasses) at runtime so
+    // a nested menu lifts above its host; keep the frosted blur + border + radius here.
+    menuStyle: "min-w-[200px] max-h-[400px] overflow-y-auto rounded-[var(--dropdown-radius)] border border-[var(--color-border)] backdrop-blur-md focus:outline-none flex disabled:cursor-not-allowed gap-0.5",
     // Delegate item styles to shared MenuItem theme
     itemBaseStyle: menuItemTheme.baseStyle,
     itemDangerStyle: menuItemTheme.dangerStyle,
     itemFocusStyle: menuItemTheme.focusStyle,
     // Section title styling
-    sectionTitleStyle: "px-2 py-1.5 text-xs font-semibold text-[var(--color-text-muted)] uppercase tracking-tight",
+    sectionTitleStyle: "px-2 py-1.5 text-[11px] font-medium text-[var(--color-text-secondary)] uppercase tracking-tight",
     // Section container styling
     sectionStyle: "py-1",
-    // Separator between sections
-    separatorStyle: "my-1 h-px bg-[var(--color-border)] " +
-        "dark:bg-[var(--color-neutral-700)]",
+    // Separator between sections (--color-border flips for dark mode on its own)
+    separatorStyle: "my-1 h-px bg-[var(--color-border)]",
 };
 
 export { dropdownTheme };

package/dist/components/core/Dropdown/Dropdown.types.d.ts

@@ -1,5 +1,6 @@
 import React, { ReactNode } from "react";
 import { DropdownTheme } from "./Dropdown.theme";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export type DropdownPlacement = "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end";
 export type SelectionMode = "none" | "single" | "multiple";
 export interface DropdownContextValue {
@@ -7,6 +8,7 @@ export interface DropdownContextValue {
     onOpenChange: (isOpen: boolean) => void;
     triggerRef: React.RefObject<HTMLElement | null>;
     menuRef: React.RefObject<HTMLDivElement | null>;
+    menuId: string;
     placement: DropdownPlacement;
     offset: number;
     closeOnSelect: boolean;
@@ -52,6 +54,13 @@ export interface DropdownMenuProps extends React.HTMLAttributes<HTMLDivElement>
     portal?: boolean;
     horizontal?: boolean;
     "aria-label"?: string;
+    /**
+     * Pin the surface elevation rung (overrides the automatic relative lift).
+     * A rung number (1–8) or a semantic alias ("surface"/"raised"/"overlay"…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the menu's base rung. */
+    lift?: boolean;
 }
 export interface DropdownItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color" | "onSelect"> {
     itemKey: string;
@@ -59,16 +68,16 @@ export interface DropdownItemProps extends Omit<React.HTMLAttributes<HTMLDivElem
     className?: string;
     startContent?: ReactNode;
     endContent?: ReactNode;
-    subtitle?: string;
+    subtitle?: ReactNode;
     shortcut?: ReactNode;
     isDisabled?: boolean;
     isDanger?: boolean;
     onAction?: () => void;
 }
-export interface DropdownSectionProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface DropdownSectionProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
     children: ReactNode;
     className?: string;
-    title?: string;
+    title?: ReactNode;
     showDivider?: boolean;
 }
 export interface DropdownSeparatorProps extends React.HTMLAttributes<HTMLDivElement> {

package/dist/components/core/Dropdown/DropdownContext.js

@@ -1,3 +1,4 @@
+"use client";
 import { createContext, useContext } from 'react';
 
 const DropdownContext = createContext(undefined);

package/dist/components/core/Dropdown/DropdownItem.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default, { useCallback } from 'react';
 import { CheckIcon } from '@heroicons/react/16/solid';
@@ -63,12 +64,12 @@ const DropdownItem = React__default.forwardRef(({ itemKey, children, className,
     // Build end content: user's endContent OR selection checkmark
     const resolvedEndContent = endContent ||
         (selectionMode !== "none" ? (jsx("div", { className: cn("flex items-center justify-center flex-shrink-0 w-5 h-5"), children: isSelected && (jsx(CheckIcon, { className: "size-4 text-[var(--color-text-secondary)]" })) })) : undefined);
-    return (jsx(MenuItem, { ref: ref, role: itemRole, disabled: disabled, isDanger: isDanger, startContent: startContent, endContent: resolvedEndContent, subtitle: subtitle, shortcut: shortcut, onActivate: handleActivate, "data-selected": isSelected, ...(selectionMode !== "none" ? { "aria-checked": isSelected } : {}), className: className, theme: {
+    return (jsx(MenuItem, { ref: ref, role: itemRole, disabled: disabled, isDanger: isDanger, startContent: startContent, endContent: resolvedEndContent, subtitle: subtitle, shortcut: shortcut, onActivate: handleActivate, selected: isSelected, ...(selectionMode !== "none" ? { "aria-checked": isSelected } : {}), className: className, theme: {
             baseStyle: theme.itemBaseStyle,
             dangerStyle: theme.itemDangerStyle,
             focusStyle: theme.itemFocusStyle,
         }, ...props, children: children }));
 });
-DropdownItem.displayName = "DropdownItem";
+DropdownItem.displayName = "Dropdown.Item";
 
 export { DropdownItem };

package/dist/components/core/Dropdown/DropdownMenu.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import React__default, { useRef, useState, useCallback, useEffect } from 'react';
+import React__default, { useRef, useState, useEffect, useCallback } from 'react';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
 import { createPortal } from 'react-dom';
 import { cn } from '../../../utils/cn.js';
@@ -7,41 +8,18 @@ import { useDropdownContext } from './DropdownContext.js';
 import { useClickOutside } from '../../../hooks/useClickOutside.js';
 import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
+import '../../../theme/ThemeContext.js';
+import { getOverlayMenuVariants } from '../../../theme/animations.js';
 
-/**
- * Hook to detect dark mode state from document
- */
-const useDarkMode = () => {
-    const [isDark, setIsDark] = useState(false);
-    useEffect(() => {
-        if (typeof document === "undefined")
-            return;
-        const checkDarkMode = () => {
-            const hasDarkClass = document.documentElement.classList.contains("dark") ||
-                document.body.classList.contains("dark") ||
-                document.querySelector(".dark") !== null;
-            setIsDark(hasDarkClass);
-        };
-        checkDarkMode();
-        // Observe class changes on html and body
-        const observer = new MutationObserver(checkDarkMode);
-        observer.observe(document.documentElement, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        observer.observe(document.body, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        return () => observer.disconnect();
-    }, []);
-    return isDark;
-};
 /**
  * DropdownMenu component - renders the menu with keyboard navigation
  */
-const DropdownMenu = React__default.forwardRef(({ children, className, animation = true, portal = true, horizontal = false, "aria-label": ariaLabel, ...props }, ref) => {
-    const { isOpen, onOpenChange, triggerRef, menuRef, placement, offset, theme, } = useDropdownContext();
+const DropdownMenu = React__default.forwardRef(({ children, className, animation = true, portal = true, horizontal = false, "aria-label": ariaLabel, elevation, lift, ...props }, ref) => {
+    // Relative elevation: lift one+ rung above the host surface (overlay base = 5).
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
+    const { isOpen, onOpenChange, triggerRef, menuRef, menuId, placement, offset, theme, } = useDropdownContext();
     // Detect dark mode for portal content
     const isDarkMode = useDarkMode();
     const isClient = useIsClient();
@@ -51,13 +29,30 @@ const DropdownMenu = React__default.forwardRef(({ children, className, animation
     const [typeaheadString, setTypeaheadString] = useState("");
     const typeaheadTimeoutRef = useRef(null);
     // Use the positioning hook from Popover/Select
-    const { position, cssVariables, contentRef: portalContentRef, } = useSelectPortal({
+    const { position, cssVariables, contentRef: portalContentRef, actualPlacement, } = useSelectPortal({
         triggerRef,
         isOpen: isOpen || false,
-        placement: placement,
+        placement,
         offset: offset || 4,
         autoWidth: false,
+        stickyTracking: true,
     });
+    // Escape must close the menu even when focus never entered it — after a
+    // mouse-open, focus stays on the trigger, so the menu's own onKeyDown
+    // (which also handles Escape) never fires.
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const onDocKeyDown = (e) => {
+            var _a;
+            if (e.key !== "Escape")
+                return;
+            onOpenChange(false);
+            (_a = triggerRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+        };
+        document.addEventListener("keydown", onDocKeyDown);
+        return () => document.removeEventListener("keydown", onDocKeyDown);
+    }, [isOpen, onOpenChange, triggerRef]);
     // Get all menu items (not separators or sections)
     const getMenuItems = useCallback(() => {
         if (!localRef.current)
@@ -140,29 +135,48 @@ const DropdownMenu = React__default.forwardRef(({ children, className, animation
     ]);
     // Click outside to close
     useClickOutside(localRef, (e) => {
-        var _a;
+        var _a, _b, _c;
         // Skip if clicking on the trigger element
         if (e.target === triggerRef.current ||
             ((_a = triggerRef.current) === null || _a === void 0 ? void 0 : _a.contains(e.target))) {
             return;
         }
+        // Ignore clicks that land inside any FlikkUI overlay portal (a nested
+        // Select/Tooltip/Dropdown/Popover renders to document.body, outside our
+        // menu's own DOM subtree — without this it would count as an outside
+        // click and dismiss the menu). See the `data-flikkui-portal` convention
+        // (CLAUDE.md §11) — mirrors PopoverBody's bail.
+        if ((_c = (_b = e.target) === null || _b === void 0 ? void 0 : _b.closest) === null || _c === void 0 ? void 0 : _c.call(_b, "[data-flikkui-portal]")) {
+            return;
+        }
         onOpenChange(false);
     });
-    // Focus first item when menu opens
+    // Focus first item when menu opens. Retry until focus actually LANDS:
+    // useSelectPortal keeps the menu `visibility: hidden` until positioning
+    // completes, and focus() on a hidden element is a silent no-op — a
+    // single-shot focus fires inside that window, leaving focus on the
+    // trigger, which kills the whole keyboard layer (arrows, Enter, and
+    // typeahead all hang off focus being inside the menu).
     useEffect(() => {
-        if (isOpen) {
-            // Focus first item after a small delay to allow render
-            requestAnimationFrame(() => {
-                const items = getMenuItems();
-                if (items.length > 0) {
-                    focusItem(0);
-                }
-            });
-        }
-        else {
+        if (!isOpen) {
             setFocusedIndex(-1);
             setTypeaheadString("");
+            return;
         }
+        let raf = 0;
+        let tries = 0;
+        const tryFocus = () => {
+            const items = getMenuItems();
+            if (items.length > 0) {
+                focusItem(0);
+                if (document.activeElement === items[0])
+                    return; // focus landed
+            }
+            if (++tries < 10)
+                raf = requestAnimationFrame(tryFocus);
+        };
+        raf = requestAnimationFrame(tryFocus);
+        return () => cancelAnimationFrame(raf);
     }, [isOpen, getMenuItems, focusItem]);
     // Combine refs
     const handleRef = useCallback((el) => {
@@ -183,43 +197,30 @@ const DropdownMenu = React__default.forwardRef(({ children, className, animation
                 el;
         }
     }, [ref, menuRef, portalContentRef]);
-    // Animation variants
-    const menuVariants = {
-        hidden: {
-            opacity: 0,
-            scale: 0.95,
-            y: -10,
-        },
-        visible: {
-            opacity: 1,
-            scale: 1,
-            y: 0,
-        },
-        exit: {
-            opacity: 0,
-            scale: 0.95,
-            y: -10,
-        },
-    };
+    // Animation variants — enter/exit from the trigger's side. A menu opening
+    // above the trigger slides up into place and scales from its bottom edge;
+    // a hardcoded top-down drop reads backwards there. `actualPlacement` (not
+    // the prop) so a viewport-flipped menu animates from its real side.
+    const side = (actualPlacement || placement || "bottom").split("-")[0];
+    const transformOrigin = side === "top" ? "bottom" : side === "left" ? "right" : side === "right" ? "left" : "top";
+    const menuVariants = getOverlayMenuVariants(side, {
+        scale: 0.97,
+        shift: 6,
+    });
     // Extract DOM props to avoid type conflicts with Framer Motion
     const { onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...domProps } = props;
-    const menuContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, className: cn("fixed z-50", theme.menuStyle, horizontal ? "flex-row p-1" : "flex-col p-1", className), style: {
+    const menuContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, className: cn("fixed z-50", surfaceClasses(surfaceLevel, { translucent: true }), theme.menuStyle, horizontal ? "flex-row p-1" : "flex-col p-1", className), style: {
                 ...cssVariables,
                 top: `${position.top}px`,
                 left: `${position.left}px`,
-            }, role: "menu", "aria-label": ariaLabel || "Menu", "aria-orientation": horizontal ? "horizontal" : "vertical", tabIndex: -1, onKeyDown: handleKeyDown, variants: shouldReduceMotion || !animation ? {} : menuVariants, initial: shouldReduceMotion || !animation ? undefined : "hidden", animate: shouldReduceMotion || !animation ? undefined : "visible", exit: shouldReduceMotion || !animation ? undefined : "exit", transition: shouldReduceMotion || !animation
-                ? { duration: 0 }
-                : {
-                    type: "spring",
-                    stiffness: 500,
-                    damping: 30,
-                }, "data-state": isOpen ? "open" : "closed", "data-placement": placement, ...domProps, children: children })) }));
+                transformOrigin,
+            }, id: menuId, role: "menu", "aria-label": ariaLabel || undefined, "aria-orientation": horizontal ? "horizontal" : "vertical", tabIndex: -1, onKeyDown: handleKeyDown, variants: shouldReduceMotion || !animation ? {} : menuVariants, initial: shouldReduceMotion || !animation ? undefined : "hidden", animate: shouldReduceMotion || !animation ? undefined : "visible", exit: shouldReduceMotion || !animation ? undefined : "exit", transition: shouldReduceMotion || !animation ? { duration: 0 } : undefined, "data-state": isOpen ? "open" : "closed", "data-placement": placement, ...domProps, children: jsx(SurfaceProvider, { level: surfaceLevel, children: children }) })) }));
     // Use portal if specified - wrap with dark class for dark mode support
     if (portal && isClient) {
-        return createPortal(jsx("div", { className: isDarkMode ? "dark" : undefined, children: menuContent }), document.body);
+        return createPortal(jsx("div", { "data-flikkui-portal": "", className: isDarkMode ? "dark" : undefined, children: menuContent }), document.body);
     }
     return menuContent;
 });
-DropdownMenu.displayName = "DropdownMenu";
+DropdownMenu.displayName = "Dropdown.Menu";
 
 export { DropdownMenu };

package/dist/components/core/Dropdown/DropdownSection.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -8,8 +9,10 @@ import { useDropdownContext } from './DropdownContext.js';
  */
 const DropdownSection = React__default.forwardRef(({ children, className, title, showDivider = false, ...props }, ref) => {
     const { theme } = useDropdownContext();
-    return (jsxs(Fragment, { children: [showDivider && jsx("div", { className: theme.separatorStyle, role: "separator" }), jsxs("div", { ref: ref, role: "group", "aria-label": title, className: cn(theme.sectionStyle, className), ...props, children: [title && (jsx("div", { className: theme.sectionTitleStyle, role: "presentation", children: title })), children] })] }));
+    return (jsxs(Fragment, { children: [showDivider && jsx("div", { className: theme.separatorStyle, role: "separator" }), jsxs("div", { ref: ref, role: "group", "aria-label": typeof title === 'string' ? title : undefined, className: cn(theme.sectionStyle, className), ...props, children: [title && (typeof title === 'string'
+                        ? jsx("div", { className: theme.sectionTitleStyle, role: "presentation", children: title })
+                        : title), children] })] }));
 });
-DropdownSection.displayName = "DropdownSection";
+DropdownSection.displayName = "Dropdown.Section";
 
 export { DropdownSection };

package/dist/components/core/Dropdown/DropdownSeparator.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -10,6 +11,6 @@ const DropdownSeparator = React__default.forwardRef(({ className, ...props }, re
     const { theme } = useDropdownContext();
     return (jsx("div", { ref: ref, role: "separator", className: cn(theme.separatorStyle, className), ...props }));
 });
-DropdownSeparator.displayName = "DropdownSeparator";
+DropdownSeparator.displayName = "Dropdown.Separator";
 
 export { DropdownSeparator };