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

package/dist/components/core/Carousel/Carousel.js

@@ -1,20 +1,21 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useState, useEffect, useCallback, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { carouselTheme } from './Carousel.theme.js';
 import { CarouselContext } from './CarouselContext.js';
-import { CarouselContent } from './CarouselContent.js';
+import { CarouselBody } from './CarouselBody.js';
 import { CarouselItem } from './CarouselItem.js';
 import { CarouselPrevious } from './CarouselPrevious.js';
 import { CarouselNext } from './CarouselNext.js';
 
 const CarouselRoot = React__default.forwardRef(({ orientation = 'horizontal', opts = {}, showControls = false, defaultIndex = 0, onSlideChange, className, children, ...rest }, ref) => {
     const { align = 'start', loop = false, slidesToScroll = 1, draggable = true, dragThreshold = 0.1, } = opts;
-    // Count total slides by looking for CarouselContent and its CarouselItem children
+    // Count total slides by looking for CarouselBody and its CarouselItem children
     const totalSlides = React__default.useMemo(() => {
         let count = 0;
         React__default.Children.forEach(children, (child) => {
-            if (React__default.isValidElement(child) && child.type === CarouselContent) {
+            if (React__default.isValidElement(child) && child.type === CarouselBody) {
                 const contentProps = child.props;
                 count = React__default.Children.count(contentProps.children);
             }
@@ -73,7 +74,7 @@ const CarouselRoot = React__default.forwardRef(({ orientation = 'horizontal', op
 CarouselRoot.displayName = 'Carousel';
 // Create compound component with sub-components
 const Carousel = Object.assign(CarouselRoot, {
-    Content: CarouselContent,
+    Body: CarouselBody,
     Item: CarouselItem,
     Previous: CarouselPrevious,
     Next: CarouselNext,

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

@@ -67,13 +67,13 @@ export interface CarouselProps extends HTMLAttributes<HTMLDivElement> {
      */
     className?: string;
     /**
-     * Children components (CarouselContent, CarouselPrevious, CarouselNext)
+     * Children components (CarouselBody, CarouselPrevious, CarouselNext)
      */
     children?: ReactNode;
 }
-export interface CarouselContentProps extends HTMLAttributes<HTMLDivElement> {
+export interface CarouselBodyProps extends HTMLAttributes<HTMLDivElement> {
     /**
-     * Custom class name for the content container
+     * Custom class name for the body container
      */
     className?: string;
     /**
@@ -106,7 +106,7 @@ export interface CarouselControlProps extends HTMLAttributes<HTMLButtonElement>
     'aria-label'?: string;
 }
 export interface CarouselComponent extends ForwardRefExoticComponent<CarouselProps & RefAttributes<HTMLDivElement>> {
-    Content: ForwardRefExoticComponent<CarouselContentProps & RefAttributes<HTMLDivElement>>;
+    Body: ForwardRefExoticComponent<CarouselBodyProps & RefAttributes<HTMLDivElement>>;
     Item: ForwardRefExoticComponent<CarouselItemProps & RefAttributes<HTMLDivElement>>;
     Previous: ForwardRefExoticComponent<CarouselControlProps & RefAttributes<HTMLButtonElement>>;
     Next: ForwardRefExoticComponent<CarouselControlProps & RefAttributes<HTMLButtonElement>>;

package/dist/components/core/Carousel/CarouselBody.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import { CarouselBodyProps } from './Carousel.types';
+declare const CarouselBody: React.ForwardRefExoticComponent<CarouselBodyProps & React.RefAttributes<HTMLDivElement>>;
+export { CarouselBody };

package/dist/components/core/Carousel/{CarouselContent.js → CarouselBody.js}

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { useReducedMotion, motion } from 'motion/react';
@@ -5,7 +6,7 @@ import { cn } from '../../../utils/cn.js';
 import { useCarouselContext } from './CarouselContext.js';
 import { carouselTheme } from './Carousel.theme.js';
 
-const CarouselContent = React__default.forwardRef(({ className, children, ...props }, ref) => {
+const CarouselBody = React__default.forwardRef(({ className, children, ...props }, ref) => {
     const { currentIndex, orientation, opts, scrollPrev, scrollNext } = useCarouselContext();
     const shouldReduceMotion = useReducedMotion();
     const internalRef = React__default.useRef(null);
@@ -41,12 +42,18 @@ const CarouselContent = React__default.forwardRef(({ className, children, ...pro
                 : { type: 'spring', stiffness: 180, damping: 25, mass: 0.7 }, children: React__default.Children.map(children, (child, index) => {
                 if (!React__default.isValidElement(child))
                     return child;
+                const isActive = index === currentIndex;
                 return React__default.cloneElement(child, {
-                    ...child.props,
-                    'aria-hidden': index !== currentIndex,
+                    'aria-hidden': !isActive,
+                    // inert removes all focusable descendants from tab order and hides
+                    // them from assistive technologies when the slide is not active.
+                    // Must be a genuine boolean — React 19 maps `inert` directly to the
+                    // DOM property, and passing the empty string is treated as `false`
+                    // (the attribute never lands on the element).
+                    inert: !isActive || undefined,
                 });
             }) }) }));
 });
-CarouselContent.displayName = 'Carousel.Content';
+CarouselBody.displayName = 'Carousel.Body';
 
-export { CarouselContent };
+export { CarouselBody };

package/dist/components/core/Carousel/CarouselContext.js

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

package/dist/components/core/Carousel/CarouselNext.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { ChevronRightIcon, ChevronDownIcon } from '@heroicons/react/24/outline';

package/dist/components/core/Carousel/CarouselPrevious.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { ChevronLeftIcon, ChevronUpIcon } from '@heroicons/react/24/outline';

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

@@ -1,2 +1,3 @@
 export { Carousel } from './Carousel';
-export type { CarouselProps, CarouselContentProps, CarouselItemProps, CarouselControlProps, CarouselOptions, CarouselOrientation, } from './Carousel.types';
+export { CarouselBody } from './CarouselBody';
+export type { CarouselProps, CarouselBodyProps, CarouselItemProps, CarouselControlProps, CarouselOptions, CarouselOrientation, } from './Carousel.types';

package/dist/components/core/CommandPalette/CommandItem.js

@@ -1,8 +1,8 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
-import { cn } from '../../../utils/cn.js';
+import { MenuItem } from '../MenuItem/MenuItem.js';
 import { Kbd } from '../Kbd/Kbd.js';
-import { commandPaletteTheme } from './CommandPalette.theme.js';
 
 /**
  * Map string shortcuts to KbdKey types
@@ -100,7 +100,7 @@ const Shortcut = ({ keys }) => {
  * />
  * ```
  */
-const CommandItem = ({ command, index, isHighlighted, contentStart, contentEnd, className, onSelect, onMouseEnter, theme = commandPaletteTheme, }) => {
+const CommandItem = ({ command, index, isHighlighted, contentStart, contentEnd, className, onSelect, onMouseEnter, }) => {
     const handleClick = () => {
         if (!command.disabled) {
             onSelect(command);
@@ -126,7 +126,7 @@ const CommandItem = ({ command, index, isHighlighted, contentStart, contentEnd,
         }
         return null;
     };
-    return (jsxs("div", { "data-command-index": index, "data-highlighted": isHighlighted, "data-disabled": command.disabled || false, className: cn(theme.commandItem, className), onClick: handleClick, onMouseEnter: handleMouseEnter, children: [finalContentStart && (jsx("div", { className: "flex-shrink-0", children: finalContentStart })), jsxs("div", { className: "flex-1 min-w-0", children: [jsx("div", { className: "text-sm  truncate", children: command.label }), command.subtitle && (jsx("div", { className: "text-sm opacity-70 truncate mt-0", children: command.subtitle }))] }), renderContentEnd()] }));
+    return (jsx(MenuItem, { role: "option", selected: isHighlighted, disabled: command.disabled, startContent: finalContentStart, subtitle: command.subtitle, endContent: renderContentEnd(), onActivate: handleClick, onMouseEnter: handleMouseEnter, "aria-selected": isHighlighted, "data-command-index": index, "data-highlighted": isHighlighted, className: className, children: command.label }));
 };
 
 export { CommandItem };

package/dist/components/core/CommandPalette/CommandPalette.animations.js

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Animation variants for CommandPalette modal
  */

package/dist/components/core/CommandPalette/CommandPalette.js

@@ -1,11 +1,15 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useMemo, useState, useRef, useEffect, useCallback } from 'react';
 import { commandPaletteTheme } from './CommandPalette.theme.js';
 import { containerAnimations, overlayAnimations } from './CommandPalette.animations.js';
 import { cn } from '../../../utils/cn.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
 import { CommandItem } from './CommandItem.js';
 import { Overlay } from '../../effects/Overlay/Overlay.js';
+import { ScrollArea } from '../ScrollArea/ScrollArea.js';
+import '../ScrollArea/smooth/SmoothScrollEngine.js';
 
 /**
  * Default filter function for commands
@@ -51,6 +55,32 @@ const groupCommandsByCategory = (commands) => {
         commands: groupCommands,
     }));
 };
+/**
+ * Find the next index in `commands` that is not disabled, starting from
+ * `currentIndex` and moving in `direction` (wrapping around either end).
+ * Returns `currentIndex` unchanged if every command is disabled.
+ */
+const findNextEnabledIndex = (currentIndex, direction, commands) => {
+    var _a;
+    const length = commands.length;
+    if (length === 0)
+        return currentIndex;
+    let index = currentIndex;
+    for (let i = 0; i < length; i++) {
+        index =
+            direction === 1
+                ? index >= length - 1
+                    ? 0
+                    : index + 1
+                : index <= 0
+                    ? length - 1
+                    : index - 1;
+        if (!((_a = commands[index]) === null || _a === void 0 ? void 0 : _a.disabled)) {
+            return index;
+        }
+    }
+    return currentIndex;
+};
 /**
  * CommandPalette Component
  *
@@ -77,7 +107,10 @@ const groupCommandsByCategory = (commands) => {
  * />
  * ```
  */
-const CommandPalette = React__default.forwardRef(({ isOpen, onClose, commands = [], placeholder = "Type a command or search...", emptyMessage = "No results found.", maxHeight = "400px", className = "", overlayClassName = "", theme: themeOverrides, grouped = false, onSearchChange, filterFunction = defaultFilterFunction, closeOnOverlayClick = true, closeOnEsc = true, }, ref) => {
+const CommandPalette = React__default.forwardRef(({ isOpen, onClose, commands = [], placeholder = "Type a command or search...", emptyMessage = "No results found.", maxHeight = "400px", className = "", overlayClassName = "", theme: themeOverrides, grouped = false, onSearchChange, filterFunction = defaultFilterFunction, closeOnOverlayClick = true, closeOnEsc = true, footer, footerClassName, elevation, lift, }, ref) => {
+    // Grounded backdrop overlay: the palette covers the viewport over a backdrop, so it
+    // paints a FIXED rung 5 regardless of where its JSX sits. Content inside lifts relative.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, ground: true, elevation, lift });
     // Merge theme with overrides
     const theme = useMemo(() => ({ ...commandPaletteTheme, ...(themeOverrides || {}) }), [themeOverrides]);
     // State
@@ -95,13 +128,26 @@ const CommandPalette = React__default.forwardRef(({ isOpen, onClose, commands =
         }
         return allCommands.filter((command) => filterFunction(command, searchValue));
     }, [allCommands, searchValue, filterFunction]);
-    // Group filtered commands if needed
+    // Group filtered commands if needed. When the input already arrives as
+    // CommandGroup[], preserve its original group labels/order rather than
+    // re-deriving sections from each item's own `group` field (which would
+    // collapse everything into a single "Other" bucket unless every item
+    // redundantly repeats its group's label).
     const displayCommands = useMemo(() => {
-        if (grouped || isGroupedCommands(commands)) {
+        if (isGroupedCommands(commands)) {
+            const filteredIds = new Set(filteredCommands.map((command) => command.id));
+            return commands
+                .map((group) => ({
+                ...group,
+                commands: group.commands.filter((command) => filteredIds.has(command.id)),
+            }))
+                .filter((group) => group.commands.length > 0);
+        }
+        if (grouped) {
             return groupCommandsByCategory(filteredCommands);
         }
         return filteredCommands;
-    }, [grouped, commands, filteredCommands]);
+    }, [commands, grouped, filteredCommands]);
     // Get flat list of filtered commands for keyboard navigation
     const flatFilteredCommands = useMemo(() => {
         if (isGroupedCommands(displayCommands)) {
@@ -161,11 +207,11 @@ const CommandPalette = React__default.forwardRef(({ isOpen, onClose, commands =
             // Arrow keys navigation
             if (event.key === "ArrowDown") {
                 event.preventDefault();
-                setHighlightedIndex((prev) => prev >= cmds.length - 1 ? 0 : prev + 1);
+                setHighlightedIndex((prev) => findNextEnabledIndex(prev, 1, cmds));
             }
             else if (event.key === "ArrowUp") {
                 event.preventDefault();
-                setHighlightedIndex((prev) => prev <= 0 ? cmds.length - 1 : prev - 1);
+                setHighlightedIndex((prev) => findNextEnabledIndex(prev, -1, cmds));
             }
             else if (event.key === "Enter") {
                 event.preventDefault();
@@ -195,7 +241,7 @@ const CommandPalette = React__default.forwardRef(({ isOpen, onClose, commands =
     // Render commands list
     const renderCommandsList = () => {
         if (flatFilteredCommands.length === 0) {
-            return jsx("div", { className: theme.emptyState, children: emptyMessage });
+            return jsx("div", { className: theme.emptyState, "aria-live": "polite", children: emptyMessage });
         }
         // If grouped, render with group labels
         if (isGroupedCommands(displayCommands)) {
@@ -209,12 +255,12 @@ const CommandPalette = React__default.forwardRef(({ isOpen, onClose, commands =
         // Otherwise render flat list
         return displayCommands.map((command, index) => (jsx(CommandItem, { command: command, index: index, isHighlighted: index === highlightedIndex, onSelect: handleSelectCommand, onMouseEnter: setHighlightedIndex, theme: theme }, command.id)));
     };
-    return (jsxs(Overlay, { ref: ref, isOpen: isOpen, onClose: onClose, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, position: "top", overlayClassName: overlayClassName, contentClassName: cn(theme.container, className), animations: {
+    return (jsx(Overlay, { ref: ref, isOpen: isOpen, onClose: onClose, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, position: "top", overlayClassName: cn(theme.overlay, overlayClassName), contentClassName: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), theme.container, className), animations: {
             overlay: overlayAnimations,
             content: containerAnimations,
-        }, children: [jsx("div", { className: theme.searchWrapper, children: jsxs("div", { className: "flex items-center gap-3", children: [jsx(MagnifyingGlassIcon, { className: "w-5 h-5 text-[var(--color-text-muted)]", strokeWidth: 2 }), jsx("input", { ref: searchInputRef, type: "text", className: theme.searchInput, placeholder: placeholder, value: searchValue, onChange: handleSearchChange, autoComplete: "off", autoCorrect: "off", spellCheck: false })] }) }), jsx("div", { ref: listContainerRef, className: "overflow-y-auto overscroll-contain px-1", style: {
-                    maxHeight: typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight,
-                }, children: renderCommandsList() })] }));
+        }, children: jsxs(SurfaceProvider, { level: surfaceLevel, children: [jsx("div", { className: theme.searchWrapper, children: jsxs("div", { className: "flex items-center gap-3", children: [jsx(MagnifyingGlassIcon, { className: "w-5 h-5 text-[var(--color-text-muted)]", strokeWidth: 2 }), jsx("input", { ref: searchInputRef, type: "text", className: theme.searchInput, placeholder: placeholder, value: searchValue, onChange: handleSearchChange, autoComplete: "off", autoCorrect: "off", spellCheck: false, "aria-label": "Search commands" })] }) }), jsx(ScrollArea, { ref: listContainerRef, type: "hover", className: "overscroll-contain px-1", style: {
+                        maxHeight: typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight,
+                    }, children: jsx("div", { role: "listbox", "aria-label": "Commands", children: renderCommandsList() }) }), footer && (jsx("div", { className: cn(theme.footer, footerClassName), children: footer }))] }) }));
 });
 CommandPalette.displayName = "CommandPalette";
 

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

@@ -1,8 +1,14 @@
 const commandPaletteTheme = {
-    overlay: "fixed inset-0 bg-[var(--overlay-bg)] backdrop-blur-[var(--overlay-blur)] z-50 " +
-        "flex items-start justify-center pt-[min(10vh,4rem)] px-4",
+    // Applied to the Overlay backdrop (positioning/z-index come from Overlay).
+    // Overrides the shared 65%-black scrim (--overlay-bg) with a lighter dim so
+    // real page content sits behind the container — that's what the container's
+    // backdrop-blur frosts into the glass effect. A heavy scrim would leave only
+    // a flat dark layer to blur, making backdrop-blur look like it does nothing.
+    overlay: "",
+    // bg comes from the relative-elevation engine (surfaceClasses) at runtime so the
+    // palette lifts above its host surface; keep the dramatic shadow-2xl + blur + ring + border here.
     container: "relative w-full max-h-[calc(100vh-2rem)] max-w-lg " +
-        "bg-[var(--color-background)] rounded-[var(--modal-radius)] shadow-2xl shadow-black/30 " +
+        "rounded-[var(--modal-radius)] shadow-2xl shadow-black/30 " +
         "border border-[var(--color-border)] ring-4 ring-[var(--color-background)]/20 " +
         "flex flex-col my-4 min-h-0 overflow-hidden " +
         // Dark mode
@@ -11,20 +17,15 @@ const commandPaletteTheme = {
     searchInput: "w-full px-0 py-0 text-sm bg-transparent border-none outline-none " +
         "text-[var(--color-text-primary)] placeholder:text-[var(--color-text-placeholder)] " +
         "focus:outline-none focus:ring-0 " +
-        // Dark mode
-        "dark:text-[var(--color-neutral-200)] dark:placeholder:text-[var(--color-neutral-500)]",
+        // Dark mode — matches Input's controlBaseStyle text/placeholder tokens
+        "dark:text-[var(--color-text-primary)] dark:placeholder:text-[var(--color-neutral-500)]",
     groupLabel: "px-4 py-1 text-xs font-semibold text-[var(--color-text-muted)]/50 uppercase " +
         "dark:text-[var(--color-neutral-500)]",
-    commandItem: "flex items-center gap-3 px-4 py-2 rounded-[var(--radius-base)] cursor-pointer transition-colors " +
-        "hover:bg-[var(--color-primary)] " +
-        "data-[highlighted=true]:bg-[var(--color-primary)] data-[highlighted=true]:hover:bg-[var(--color-primary)] " +
-        "data-[highlighted=true]:text-white " +
-        "data-[disabled=true]:opacity-50 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:hover:bg-transparent " +
-        // Dark mode - adjust hover state
-        "dark:text-[var(--color-neutral-200)] dark:hover:bg-[var(--color-primary-600)] " +
-        "dark:data-[highlighted=true]:bg-[var(--color-primary-600)]",
+    // Command rows render via the shared MenuItem primitive and use its default
+    // styling (subtle highlight + standard padding) — no per-row theme here.
     emptyState: "px-4 py-12 text-center text-sm text-[var(--color-text-muted)] " +
         "dark:text-[var(--color-neutral-500)]",
+    footer: "border-t border-[var(--color-border)] px-4 py-2 text-xs text-[var(--color-text-muted)]font-medium",
 };
 
 export { commandPaletteTheme };

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

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 /**
  * Command item type
  */
@@ -67,6 +68,17 @@ export interface CommandPaletteProps {
     closeOnOverlayClick?: boolean;
     /** Whether pressing Escape should close the palette (default: true) */
     closeOnEsc?: boolean;
+    /** Footer content rendered below the command list (e.g., keyboard hints) */
+    footer?: React.ReactNode;
+    /** Additional class name for the footer */
+    footerClassName?: 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 palette's base rung. */
+    lift?: boolean;
 }
 /**
  * Theme overrides for the CommandPalette component
@@ -82,8 +94,8 @@ export interface CommandPaletteThemeOverrides {
     searchInput?: string;
     /** Style for group labels */
     groupLabel?: string;
-    /** Style for command items (uses data-[highlighted] and data-[disabled] selectors) */
-    commandItem?: string;
     /** Style for empty state */
     emptyState?: string;
+    /** Style for the footer area */
+    footer?: string;
 }

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

@@ -5,11 +5,11 @@ export declare const ContextMenu: {
     displayName: string;
 } & {
     Trigger: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuTriggerProps & React.RefAttributes<HTMLElement>>;
-    Content: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuContentProps & React.RefAttributes<HTMLDivElement>>;
+    Body: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuBodyProps & React.RefAttributes<HTMLDivElement>>;
     Item: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuItemProps & React.RefAttributes<HTMLDivElement>>;
     Sub: React.FC<import("./ContextMenu.types").ContextMenuSubProps>;
     SubTrigger: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuSubTriggerProps & React.RefAttributes<HTMLDivElement>>;
-    SubContent: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuSubContentProps & React.RefAttributes<HTMLDivElement>>;
+    SubBody: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuSubBodyProps & React.RefAttributes<HTMLDivElement>>;
     Separator: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuSeparatorProps & React.RefAttributes<HTMLDivElement>>;
     Label: React.ForwardRefExoticComponent<import("./ContextMenu.types").ContextMenuLabelProps & React.RefAttributes<HTMLDivElement>>;
 };

package/dist/components/core/ContextMenu/ContextMenu.js

@@ -1,13 +1,14 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import { useState, useRef, useCallback, useEffect } from 'react';
+import { useState, useRef, useCallback, useEffect, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { ContextMenuContext } from './ContextMenuContext.js';
 import { ContextMenuTrigger } from './ContextMenuTrigger.js';
-import { ContextMenuContent } from './ContextMenuContent.js';
+import { ContextMenuBody } from './ContextMenuBody.js';
 import { ContextMenuItem } from './ContextMenuItem.js';
 import { ContextMenuSub } from './ContextMenuSub.js';
 import { ContextMenuSubTrigger } from './ContextMenuSubTrigger.js';
-import { ContextMenuSubContent } from './ContextMenuSubContent.js';
+import { ContextMenuSubBody } from './ContextMenuSubBody.js';
 import { ContextMenuSeparator } from './ContextMenuSeparator.js';
 import { ContextMenuLabel } from './ContextMenuLabel.js';
 import { contextMenuTheme } from './ContextMenu.theme.js';
@@ -22,11 +23,11 @@ import { contextMenuTheme } from './ContextMenu.theme.js';
  *   <ContextMenu.Trigger>
  *     <div>Right click here</div>
  *   </ContextMenu.Trigger>
- *   <ContextMenu.Content>
+ *   <ContextMenu.Body>
  *     <ContextMenu.Item shortcut="⌘R">Reload</ContextMenu.Item>
  *     <ContextMenu.Separator />
  *     <ContextMenu.Item checked={true}>Show Bookmarks</ContextMenu.Item>
- *   </ContextMenu.Content>
+ *   </ContextMenu.Body>
  * </ContextMenu>
  * ```
  */
@@ -35,32 +36,54 @@ const ContextMenuRoot = ({ children, className, onOpenChange, theme: themeOverri
     const [cursorPosition, setCursorPosition] = useState(null);
     const contentRef = useRef(null);
     const triggerRef = useRef(null);
+    // Tracks whether the menu was open on the previous render, so the
+    // open->closed transition (Escape, item selection, click-outside) can be
+    // told apart from "never opened yet" and focus only gets moved on close.
+    const wasOpenRef = useRef(false);
     // Handle open state changes
     const handleOpenChange = useCallback((value) => {
         setIsOpen(value);
         onOpenChange === null || onOpenChange === void 0 ? void 0 : onOpenChange(value);
-        // Get cursor position from trigger element when opening
+        // Get cursor position from trigger element data attributes when opening
         if (value && triggerRef.current) {
-            const storedPosition = triggerRef.current.__cursorPosition;
-            if (storedPosition) {
-                setCursorPosition(storedPosition);
+            const x = triggerRef.current.dataset.cursorX;
+            const y = triggerRef.current.dataset.cursorY;
+            if (x && y) {
+                setCursorPosition({ x: Number(x), y: Number(y) });
             }
         }
     }, [onOpenChange]);
+    // Restore focus to the trigger element (the element that was right-clicked
+    // to open the menu) whenever the menu transitions from open to closed —
+    // matches the focus-return pattern used by Modal/CommandPalette (via
+    // useFocusTrap), scoped here to the ContextMenu's own trigger rather than
+    // "whatever had focus before" since a right-click doesn't necessarily focus
+    // the trigger first.
+    useEffect(() => {
+        var _a;
+        if (isOpen) {
+            wasOpenRef.current = true;
+            return;
+        }
+        if (wasOpenRef.current) {
+            wasOpenRef.current = false;
+            (_a = triggerRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+        }
+    }, [isOpen]);
     // Merge theme with overrides
-    const theme = {
+    const theme = useMemo(() => ({
         ...contextMenuTheme,
         ...(themeOverrides || {}),
-    };
+    }), [themeOverrides]);
     // Context value
-    const contextValue = {
+    const contextValue = useMemo(() => ({
         isOpen,
         onOpenChange: handleOpenChange,
         cursorPosition,
         contentRef,
         triggerRef,
         theme,
-    };
+    }), [isOpen, handleOpenChange, cursorPosition, contentRef, triggerRef, theme]);
     // Prevent browser context menu on the entire component
     useEffect(() => {
         const preventContextMenu = (e) => {
@@ -78,11 +101,11 @@ ContextMenuRoot.displayName = "ContextMenu";
 // Export as a unified component with sub-components
 const ContextMenu = Object.assign(ContextMenuRoot, {
     Trigger: ContextMenuTrigger,
-    Content: ContextMenuContent,
+    Body: ContextMenuBody,
     Item: ContextMenuItem,
     Sub: ContextMenuSub,
     SubTrigger: ContextMenuSubTrigger,
-    SubContent: ContextMenuSubContent,
+    SubBody: ContextMenuSubBody,
     Separator: ContextMenuSeparator,
     Label: ContextMenuLabel,
 });

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

@@ -5,21 +5,21 @@ const contextMenuTheme = {
     ...dropdownTheme,
     // Content uses the same styling as Dropdown menu
     contentStyle: dropdownTheme.menuStyle.replace("flex", "flex-col p-1"),
-    // Items use exact same styling as Dropdown items (with space for check icon)
-    itemStyle: `${dropdownTheme.itemBaseStyle} data-[checked=true]:pl-8`,
-    // Checked state - tick icon positioning (absolute left)
-    itemCheckedStyle: "absolute left-2.5 top-1/2 -translate-y-1/2 w-4 h-4 text-[var(--color-text-primary)] " +
-        "dark:text-[var(--color-neutral-200)]",
-    // Submenu trigger - based on Dropdown item style with chevron space
-    subTriggerStyle: `${dropdownTheme.itemBaseStyle} pr-8 data-[state=open]:bg-[var(--color-background-tertiary)] ` +
-        "dark:data-[state=open]:bg-[var(--color-neutral-700)]",
-    // Submenu content - similar to main menu but slightly smaller
-    subContentStyle: "min-w-[180px] max-h-[400px] overflow-y-auto rounded-[var(--dropdown-radius)] border border-[var(--color-border)] " +
-        "bg-[var(--color-background-secondary)] shadow-xl flex flex-col p-1 focus:outline-none " +
-        "dark:bg-[var(--color-neutral-800)] dark:border-[var(--color-neutral-700)]",
-    // Separator - horizontal divider
-    separatorStyle: "h-px bg-[var(--color-border)] my-1 -mx-1 " +
-        "dark:bg-[var(--color-neutral-700)]",
+    // Items use exact same styling as Dropdown items.
+    itemStyle: dropdownTheme.itemBaseStyle,
+    // Checked tick — sits in the leading icon slot (same gutter as startContent icons),
+    // so checkable rows align with icon rows. --color-text-primary flips for dark on its own.
+    itemCheckedStyle: "size-4 shrink-0 text-[var(--color-text-primary)]",
+    // Submenu trigger - based on Dropdown item style with chevron space.
+    // --color-surface-hover is a translucent tint that lightens in dark on its own.
+    subTriggerStyle: `${dropdownTheme.itemBaseStyle} pr-8 data-[state=open]:bg-[var(--color-surface-hover)]`,
+    // Submenu content - floating anchored overlay, matches main dropdown menu.
+    // bg + shadow come from the relative-elevation engine (surfaceClasses) at
+    // runtime so the submenu lifts above its parent menu; keep blur + border here.
+    subContentStyle: "min-w-[180px] max-h-[400px] overflow-y-auto rounded-[var(--dropdown-radius)] border border-[var(--color-border)] ml-1 " +
+        "backdrop-blur-md flex flex-col p-1 focus:outline-none",
+    // Separator - horizontal divider (--color-border flips for dark on its own)
+    separatorStyle: "h-px bg-[var(--color-border)] my-1 -mx-1",
     // Label - section header (matches Dropdown section title)
     labelStyle: dropdownTheme.sectionTitleStyle,
 };

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

@@ -1,5 +1,6 @@
 import React, { ReactNode } from "react";
 import { ContextMenuTheme } from "./ContextMenu.theme";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export interface ContextMenuContextValue {
     isOpen: boolean;
     onOpenChange: (isOpen: boolean) => void;
@@ -26,11 +27,18 @@ export interface ContextMenuTriggerProps {
     className?: string;
     disabled?: boolean;
 }
-export interface ContextMenuContentProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface ContextMenuBodyProps extends React.HTMLAttributes<HTMLDivElement> {
     children: ReactNode;
     className?: string;
     animation?: 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 ContextMenuItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> {
     children: ReactNode;
@@ -52,11 +60,20 @@ export interface ContextMenuSubTriggerProps extends React.HTMLAttributes<HTMLDiv
     children: ReactNode;
     className?: string;
     disabled?: boolean;
+    /** Leading icon, rendered in the same gutter as ContextMenu.Item's startContent. */
+    startContent?: ReactNode;
 }
-export interface ContextMenuSubContentProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface ContextMenuSubBodyProps extends React.HTMLAttributes<HTMLDivElement> {
     children: ReactNode;
     className?: string;
     animation?: boolean;
+    /**
+     * 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 submenu's base rung. */
+    lift?: boolean;
 }
 export interface ContextMenuSeparatorProps extends React.HTMLAttributes<HTMLDivElement> {
     className?: string;

package/dist/components/core/ContextMenu/ContextMenuBody.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { ContextMenuBodyProps } from "./ContextMenu.types";
+/**
+ * ContextMenuBody - Renders the menu at cursor position with keyboard navigation
+ */
+export declare const ContextMenuBody: React.ForwardRefExoticComponent<ContextMenuBodyProps & React.RefAttributes<HTMLDivElement>>;