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

package/dist/components/core/Calendar/Calendar.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default, { useState, useEffect, useMemo, useCallback } from 'react';
+import React__default, { useState, useCallback, useEffect, useMemo } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
 import { calendarTheme } from './Calendar.theme.js';
@@ -7,8 +8,8 @@ import { calendarAnimations } from './Calendar.animations.js';
 import { cn } from '../../../utils/cn.js';
 import { Select } from '../../forms/Select/Select.js';
 import '../../forms/Select/Select.theme.js';
-import { getMonthName, isDateDisabled as isDateDisabled$1, isSameDay } from './calendar.utils.js';
 import { Button } from '../Button/Button.js';
+import { getMonthName, isDateDisabled as isDateDisabled$1, isSameDay } from './calendar.utils.js';
 
 /**
  * Constants for date utilities
@@ -146,6 +147,21 @@ const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultVal
     });
     // Track range selection state (for range mode)
     const [rangeSelectionState, setRangeSelectionState] = useState('start');
+    // Roving tabindex (WAI-ARIA APG date-picker grid pattern): exactly one day
+    // button is Tab-reachable at a time. Tracks the index of that day within
+    // the currently-rendered `calendarDays` grid.
+    const [focusedIndex, setFocusedIndex] = useState(0);
+    // Refs to the rendered day buttons, keyed by their index in `calendarDays`,
+    // so arrow-key navigation can imperatively move focus.
+    const dayButtonRefs = React__default.useRef(new Map());
+    const registerDayButtonRef = useCallback((index, el) => {
+        if (el) {
+            dayButtonRefs.current.set(index, el);
+        }
+        else {
+            dayButtonRefs.current.delete(index);
+        }
+    }, []);
     // Determine the selected value (controlled vs uncontrolled)
     const selectedValue = value !== undefined ? value : internalValue;
     // Keep range selection state in sync with current selection to avoid misinterpreting clicks
@@ -282,6 +298,65 @@ const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultVal
         maxDate,
         customIsDateDisabled,
     ]);
+    // Reset the roving tabindex target whenever the visible month changes —
+    // prefer the selected day, then today, then the first day of the month.
+    // Deliberately does NOT depend on `selectedValue`/`calendarDays` so that
+    // picking a date (without changing month) doesn't fight in-grid arrow-key
+    // navigation that already moved the roving target elsewhere.
+    useEffect(() => {
+        const selectedIdx = calendarDays.findIndex((d) => d.isSelected);
+        if (selectedIdx >= 0) {
+            setFocusedIndex(selectedIdx);
+            return;
+        }
+        const todayIdx = calendarDays.findIndex((d) => d.isToday);
+        if (todayIdx >= 0) {
+            setFocusedIndex(todayIdx);
+            return;
+        }
+        const firstCurrentIdx = calendarDays.findIndex((d) => d.isCurrentMonth);
+        setFocusedIndex(firstCurrentIdx >= 0 ? firstCurrentIdx : 0);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [currentYear, currentMonth]);
+    // Arrow-key navigation for the day grid (roving tabindex). Moves focus by
+    // ±1 day (ArrowLeft/ArrowRight) or ±7 days / one week (ArrowUp/ArrowDown).
+    // A target outside the currently-rendered grid — or a cell hidden by
+    // showOtherMonthDays={false} — is a no-op rather than crossing into a
+    // different visible month.
+    const handleDayKeyDown = useCallback((event, index) => {
+        var _a;
+        let delta = 0;
+        switch (event.key) {
+            case "ArrowLeft":
+                delta = -1;
+                break;
+            case "ArrowRight":
+                delta = 1;
+                break;
+            case "ArrowUp":
+                delta = -7;
+                break;
+            case "ArrowDown":
+                delta = 7;
+                break;
+            default:
+                return;
+        }
+        const targetIndex = index + delta;
+        if (targetIndex < 0 || targetIndex >= calendarDays.length)
+            return;
+        const targetDay = calendarDays[targetIndex];
+        if (!targetDay.isCurrentMonth && !showOtherMonthDays)
+            return;
+        event.preventDefault();
+        // Move the roving target in the SAME (act-wrapped) keydown handler,
+        // not only via the target's onFocus. onFocus is a second event fired by
+        // .focus() and may land in a later microtask that a synchronous
+        // assertion (or a parallel-loaded test runner) hasn't flushed yet;
+        // setting it directly here keeps the tabIndex update in this batch.
+        setFocusedIndex(targetIndex);
+        (_a = dayButtonRefs.current.get(targetIndex)) === null || _a === void 0 ? void 0 : _a.focus();
+    }, [calendarDays, showOtherMonthDays]);
     // Navigation handlers
     const navigateToPreviousMonth = useCallback(() => {
         if (onNavigatePrev === null)
@@ -371,7 +446,9 @@ const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultVal
             }
         }
     }, [minDate, maxDate, customIsDateDisabled, currentMonth, currentYear, onViewDateChange, mode, value, onChange, selectedValue, rangeSelectionState]);
-    return (jsxs("div", { ref: ref, className: cn(calendarTheme.baseStyle, className), ...props, children: [jsxs("div", { className: calendarTheme.headerStyle, children: [onNavigatePrev !== null && (jsx(Button, { onClick: navigateToPreviousMonth, "aria-label": "Previous month", disabled: !canNavigateToPrev, iconOnly: true, variant: "link", color: "neutral", size: "sm", children: jsx(ChevronLeftIcon, { className: "size-4", strokeWidth: 2 }) })), onNavigatePrev === null && jsx("div", { className: "w-8" }), resolvedHeaderMode === 'static' ? (jsxs("h2", { className: calendarTheme.titleStyle, children: [getMonthName(viewDate, months), " ", currentYear] })) : (jsxs("div", { className: calendarTheme.headerDropdownsStyle, children: [(resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableMonthDropdown)) && (jsx(Select, { value: currentMonth.toString(), onChange: handleMonthChange, options: monthOptions, displayValue: currentAbbreviatedMonth, size: "sm", className: "font-medium" })), (resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableYearDropdown)) && (jsx(Select, { value: currentYear.toString(), onChange: handleYearChange, options: yearOptions, size: "sm", className: "font-medium" }))] })), onNavigateNext !== null && (jsx(Button, { onClick: navigateToNextMonth, "aria-label": "Next month", disabled: !canNavigateToNext, iconOnly: true, variant: "link", color: "neutral", size: "sm", children: jsx(ChevronRightIcon, { className: "size-4", strokeWidth: 2 }) })), onNavigateNext === null && jsx("div", { className: "w-8" })] }), jsx("div", { className: calendarTheme.weekdaysStyle, children: weekdays.map((day) => (jsx("div", { className: calendarTheme.weekdayStyle, children: day }, day))) }), jsx("div", { className: calendarTheme.daysGridStyle, children: calendarDays.map((day, index) => {
+    return (jsxs("div", { ref: ref, className: cn(calendarTheme.baseStyle, className), ...props, children: [jsxs("div", { className: calendarTheme.headerStyle, children: [onNavigatePrev !== null && (jsx(Button, { onClick: navigateToPreviousMonth, "aria-label": "Previous month", disabled: !canNavigateToPrev, iconOnly: true, variant: "ghost", color: "neutral", size: "sm", children: jsx(ChevronLeftIcon, { className: "size-4", strokeWidth: 2 }) })), onNavigatePrev === null && jsx("div", { className: "w-8" }), resolvedHeaderMode === 'static' ? (jsxs("h2", { className: calendarTheme.titleStyle, children: [getMonthName(viewDate, months), " ", currentYear] })) : (jsxs("div", { className: calendarTheme.headerDropdownsStyle, children: [(resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableMonthDropdown)) && (jsx(Select, { value: currentMonth.toString(), onChange: handleMonthChange, options: monthOptions, displayValue: currentAbbreviatedMonth, size: "sm", className: "font-medium" })), (resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableYearDropdown)) && (jsx(Select, { value: currentYear.toString(), onChange: handleYearChange, options: yearOptions, size: "sm", className: "font-medium" }))] })), onNavigateNext !== null && (jsx(Button, { onClick: navigateToNextMonth, "aria-label": "Next month", disabled: !canNavigateToNext, iconOnly: true, variant: "ghost", color: "neutral", size: "sm", children: jsx(ChevronRightIcon, { className: "size-4", strokeWidth: 2 }) })), onNavigateNext === null && jsx("div", { className: "w-8" })] }), jsx("div", { className: calendarTheme.weekdaysStyle, children: weekdays.map((day, i) => (
+                // Index in the key: default labels (e.g. M,T,W,T,F,S,S) repeat, so `day` alone is not unique.
+                jsx("div", { className: calendarTheme.weekdayStyle, children: day }, `${day}-${i}`))) }), jsx("div", { className: calendarTheme.daysGridStyle, children: calendarDays.map((day, index) => {
                     var _a;
                     const dayNumber = day.date.getDate();
                     const isInStrip = day.isRangeStart || day.isRangeEnd || day.isInRange;
@@ -400,7 +477,13 @@ const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultVal
                     if (!day.isCurrentMonth && !showOtherMonthDays) {
                         return jsx("div", {}, day.date.toISOString());
                     }
-                    return (jsx("div", { className: cn("flex items-center justify-center", isInStrip && calendarTheme.rangeCellStyle), "data-range-pos": rangePos, children: jsxs(motion.button, { type: "button", onClick: () => handleDateSelect(day.date), disabled: day.isDisabled, className: cn(calendarTheme.dayButtonStyle, (_a = calendarTheme.dayButtonSizes) === null || _a === void 0 ? void 0 : _a[size]), "data-selected": day.isSelected, "data-range-start": day.isRangeStart, "data-range-end": day.isRangeEnd, "data-in-range": day.isInRange, "data-today": day.isToday && !day.isSelected && !day.isRangeStart && !day.isRangeEnd, "data-disabled": day.isDisabled, "data-other-month": !day.isCurrentMonth, "aria-label": `Select ${day.date.toLocaleDateString()}`, variants: shouldReduceMotion ? {} : calendarAnimations.dayButton, whileHover: shouldReduceMotion ? undefined : (!day.isDisabled ? "hover" : undefined), whileTap: shouldReduceMotion ? undefined : (!day.isDisabled ? "tap" : undefined), children: [jsx("time", { dateTime: day.date.toISOString().split("T")[0], children: dayNumber }), day.isToday && (jsx(motion.span, { className: "absolute z-10 bottom-1 left-1/2 -translate-x-1/2 w-1 h-1 bg-[var(--color-primary)] rounded-full", variants: shouldReduceMotion ? {} : calendarAnimations.todayDot, initial: shouldReduceMotion ? undefined : "initial", animate: shouldReduceMotion ? undefined : "animate" }))] }) }, day.date.toISOString()));
+                    return (jsx("div", { className: cn("flex items-center justify-center", isInStrip && calendarTheme.rangeCellStyle), "data-range-pos": rangePos, children: jsxs(motion.button, { ref: (el) => registerDayButtonRef(index, el), type: "button", onClick: () => {
+                                // Clicking a day makes it the roving-tabindex target
+                                // directly (same act batch as the click), independent of
+                                // the onFocus round-trip.
+                                setFocusedIndex(index);
+                                handleDateSelect(day.date);
+                            }, onKeyDown: (e) => handleDayKeyDown(e, index), onFocus: () => setFocusedIndex(index), tabIndex: index === focusedIndex ? 0 : -1, disabled: day.isDisabled, className: cn(calendarTheme.dayButtonStyle, (_a = calendarTheme.dayButtonSizes) === null || _a === void 0 ? void 0 : _a[size]), "data-selected": day.isSelected, "data-range-start": day.isRangeStart, "data-range-end": day.isRangeEnd, "data-in-range": day.isInRange, "data-today": day.isToday && !day.isSelected && !day.isRangeStart && !day.isRangeEnd, "data-disabled": day.isDisabled, "data-other-month": !day.isCurrentMonth, "aria-label": `Select ${day.date.toLocaleDateString()}`, variants: shouldReduceMotion ? {} : calendarAnimations.dayButton, whileHover: shouldReduceMotion ? undefined : (!day.isDisabled ? "hover" : undefined), whileTap: shouldReduceMotion ? undefined : (!day.isDisabled ? "tap" : undefined), children: [jsx("time", { dateTime: day.date.toISOString().split("T")[0], children: dayNumber }), day.isToday && (jsx(motion.span, { className: "absolute z-10 bottom-1 left-1/2 -translate-x-1/2 w-1 h-1 bg-[var(--color-primary)] rounded-full", variants: shouldReduceMotion ? {} : calendarAnimations.todayDot, initial: shouldReduceMotion ? undefined : "initial", animate: shouldReduceMotion ? undefined : "animate" }))] }) }, day.date.toISOString()));
                 }) })] }));
 });
 Calendar.displayName = "Calendar";

package/dist/components/core/Calendar/CalendarMini/CalendarMini.animations.js

@@ -1,3 +1,4 @@
+"use client";
 const monthTransitionVariants = {
     enter: (direction) => ({
         x: direction > 0 ? 20 : -20,

package/dist/components/core/Calendar/CalendarMini/CalendarMini.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
 import { useReducedMotion, motion, AnimatePresence } from 'motion/react';
@@ -7,6 +8,7 @@ import { isCurrentMonth, isDateDisabled, isSameDay } from '../calendar.utils.js'
 import { monthTransitionVariants, dateRowTransitionVariants } from './CalendarMini.animations.js';
 import { calendarMiniTheme } from './CalendarMini.theme.js';
 import { Button } from '../../Button/Button.js';
+import { Link } from '../../Link/Link.js';
 
 /**
  * Generate array of months centered around current month
@@ -209,7 +211,7 @@ const CalendarMini = React__default.forwardRef(({ selectedDate, currentMonth, on
                                             }), className: "flex gap-4", children: months.map((month, index) => {
                                                 const isActive = isMonthActive(month);
                                                 return (jsx("button", { onClick: () => handleMonthClick(month), onKeyDown: (e) => handleKeyDown(e, () => handleMonthClick(month)), "data-state": isActive ? "active" : undefined, className: cn(mergedTheme.monthItemStyle, !isActive && "opacity-60"), role: "tab", "aria-selected": isActive, "aria-label": `${formatMonth(month)} ${month.getFullYear()}`, type: "button", children: formatMonth(month) }, `${month.getFullYear()}-${month.getMonth()}`));
-                                            }) }, `${activeMonth.getFullYear()}-${activeMonth.getMonth()}`) }) }) }), showTodayButton && !isTodayVisible && (jsx(Button, { size: "sm", variant: "link", onClick: handleTodayClick, "aria-label": "Jump to today", className: "mr-7", children: "Today" }))] }), jsx("div", { className: "relative overflow-hidden", style: {
+                                            }) }, `${activeMonth.getFullYear()}-${activeMonth.getMonth()}`) }) }) }), showTodayButton && !isTodayVisible && (jsx(Link, { size: "sm", onClick: handleTodayClick, "aria-label": "Jump to today", className: "mr-7", children: "Today" }))] }), jsx("div", { className: "relative overflow-hidden", style: {
                             maskImage: "linear-gradient(to right, transparent, black 16px, black calc(100% - 16px), transparent)",
                             WebkitMaskImage: "linear-gradient(to right, transparent, black 16px, black calc(100% - 16px), transparent)",
                         }, children: jsx("div", { className: cn(mergedTheme.dateRowStyle), role: "list", "aria-label": "Date selection", children: jsx(AnimatePresence, { mode: "popLayout", initial: false, custom: direction, children: jsx(motion.div, { custom: direction, ...(enableAnimations && {

package/dist/components/core/Card/Card.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import React__default, { useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -7,8 +8,14 @@ import { CardTitle } from './CardTitle.js';
 import { CardSubtitle } from './CardSubtitle.js';
 import { CardBody } from './CardBody.js';
 import { CardFooter } from './CardFooter.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
-const CardRoot = React__default.forwardRef(({ children, className, theme: customTheme = {}, darkMode = false, title, subtitle, actions, footer, ...props }, ref) => {
+const CardRoot = React__default.forwardRef(({ children, className, theme: customTheme = {}, darkMode = false, title, subtitle, actions, footer, elevation, lift, ...props }, ref) => {
+    // Relative elevation: a Card lifts two rungs above its host substrate (base = 3, so a
+    // standalone card on the floor reads rung 3). shadow:true (the engine default) supplies the
+    // hairline ring + doubling shadow — the ONLY elevation cue in light mode, where rungs 3–8 are
+    // all white; without it a nested (or floor-resting) white card would be edgeless.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 3, offset: 2, elevation, lift });
     const theme = useMemo(() => ({
         ...cardTheme,
         ...customTheme,
@@ -17,7 +24,7 @@ const CardRoot = React__default.forwardRef(({ children, className, theme: custom
     // Slot-prop mode: any header/footer slot composes Header/Body/Footer for us.
     // Otherwise children render raw — the compound API path, unchanged.
     const managed = hasHeader || Boolean(footer);
-    return (jsx("div", { ref: ref, className: cn(theme.baseStyle, darkMode && "dark", className), ...props, children: managed ? (jsxs(Fragment, { children: [hasHeader && (jsxs(CardHeader, { className: actions ? "flex-row items-start justify-between gap-4" : undefined, children: [(title || subtitle) && (jsxs("div", { className: "flex flex-col", children: [title && jsx(CardTitle, { children: title }), subtitle && jsx(CardSubtitle, { children: subtitle })] })), actions && (jsx("div", { className: "flex items-center gap-2 shrink-0", children: actions }))] })), children != null && jsx(CardBody, { children: children }), footer && jsx(CardFooter, { children: footer })] })) : (children) }));
+    return (jsx("div", { ref: ref, className: cn(surfaceClasses(surfaceLevel), theme.baseStyle, darkMode && "dark", className), ...props, children: jsx(SurfaceProvider, { level: surfaceLevel, children: managed ? (jsxs(Fragment, { children: [hasHeader && (jsxs(CardHeader, { className: actions ? "flex-row items-start justify-between gap-4" : undefined, children: [(title || subtitle) && (jsxs("div", { className: "flex flex-col", children: [title && jsx(CardTitle, { children: title }), subtitle && jsx(CardSubtitle, { children: subtitle })] })), actions && (jsx("div", { className: "flex items-center gap-2 shrink-0", children: actions }))] })), children != null && jsx(CardBody, { children: children }), footer && jsx(CardFooter, { className: "justify-end gap-2", children: footer })] })) : (children) }) }));
 });
 CardRoot.displayName = 'Card';
 // Create compound component with proper typing

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

@@ -1,5 +1,7 @@
 const cardTheme = {
-    baseStyle: "rounded-[var(--card-radius)] overflow-hidden bg-[var(--color-surface)] border-0 border-[var(--color-border)]",
+    // bg comes from the relative-elevation engine (surfaceClasses) at runtime so a card
+    // nested in a higher surface (e.g. a Modal) lifts; keep radius + overflow + border here.
+    baseStyle: "rounded-[var(--card-radius)] overflow-hidden border-0 border-[var(--color-border)]",
     headerStyle: "flex flex-col p-6 items-start",
     titleStyle: "text-base font-semibold leading-none text-[var(--color-text-primary)]",
     subtitleStyle: "text-sm text-[var(--color-text-secondary)] mt-2",

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

@@ -1,4 +1,5 @@
 import { HTMLAttributes, ReactNode, ForwardRefExoticComponent, RefAttributes } from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export interface CardTheme {
     baseStyle: string;
     headerStyle: string;
@@ -45,6 +46,13 @@ export interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, "title">
      * `ReactNode`, so it is excluded from the generative schema like `actions`.
      */
     footer?: ReactNode;
+    /**
+     * 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 card's base rung. */
+    lift?: boolean;
     /**
      * Custom class name for the card
      */

package/dist/components/core/CardStack/CardStack.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default, { useMemo, Children, isValidElement, useState, useEffect, useRef, useCallback } from 'react';
 import { useReducedMotion, motion, useMotionValue, useTransform } from 'motion/react';

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

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useState, useEffect, useCallback, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';

package/dist/components/core/Carousel/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';
@@ -46,8 +47,10 @@ const CarouselBody = React__default.forwardRef(({ className, children, ...props
                     'aria-hidden': !isActive,
                     // inert removes all focusable descendants from tab order and hides
                     // them from assistive technologies when the slide is not active.
-                    // The empty string is the correct value for boolean HTML attributes in React.
-                    inert: !isActive ? "" : undefined,
+                    // 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,
                 });
             }) }) }));
 });

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/CommandPalette/CommandItem.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { MenuItem } from '../MenuItem/MenuItem.js';

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,8 +1,10 @@
-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';
@@ -53,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
  *
@@ -79,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, footer, footerClassName, }, 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
@@ -97,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)) {
@@ -163,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();
@@ -211,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: cn(theme.overlay, 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, "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 }))] }));
+        }, 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

@@ -5,8 +5,10 @@ const commandPaletteTheme = {
     // 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-surface-overlay)]/80 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

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
  */
@@ -71,6 +72,13 @@ export interface CommandPaletteProps {
     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

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

@@ -1,5 +1,6 @@
+"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';
@@ -35,6 +36,10 @@ 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);
@@ -48,20 +53,37 @@ const ContextMenuRoot = ({ children, className, onOpenChange, theme: themeOverri
             }
         }
     }, [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) => {

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

@@ -5,18 +5,19 @@ 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. The left padding for the
-    // check icon is applied per-item in ContextMenuItem (className) when checked.
+    // Items use exact same styling as Dropdown items.
     itemStyle: dropdownTheme.itemBaseStyle,
-    // Checked state - tick icon positioning (absolute left).
-    // --color-text-primary flips for dark mode on its own.
-    itemCheckedStyle: "absolute left-2.5 top-1/2 -translate-y-1/2 w-4 h-4 text-[var(--color-text-primary)]",
+    // 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
+    // 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 " +
-        "bg-[var(--color-surface-overlay)]/80 backdrop-blur-md shadow-real-xl flex flex-col p-1 focus:outline-none",
+        "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)

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;
@@ -31,6 +32,13 @@ export interface ContextMenuBodyProps extends React.HTMLAttributes<HTMLDivElemen
     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 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;