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

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

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default, { useRef, useState, useCallback, useEffect } from 'react';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
@@ -5,11 +6,14 @@ import { createPortal } from 'react-dom';
 import { cn } from '../../../utils/cn.js';
 import { useContextMenuContext } from './ContextMenuContext.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
 /**
  * ContextMenuBody - Renders the menu at cursor position with keyboard navigation
  */
-const ContextMenuBody = React__default.forwardRef(({ children, className, animation = true, "aria-label": ariaLabel, ...props }, ref) => {
+const ContextMenuBody = React__default.forwardRef(({ children, className, animation = true, "aria-label": ariaLabel, elevation, lift, ...props }, ref) => {
+    // Relative elevation: lift above the host surface (overlay base = 5).
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const { isOpen, onOpenChange, cursorPosition, contentRef, triggerRef, theme, } = useContextMenuContext();
     const shouldReduceMotion = useReducedMotion();
     const isClient = useIsClient();
@@ -17,11 +21,13 @@ const ContextMenuBody = React__default.forwardRef(({ children, className, animat
     const [focusedIndex, setFocusedIndex] = useState(-1);
     // Initialize position from cursorPosition if available, otherwise use 0,0
     const [position, setPosition] = useState(() => cursorPosition || { x: 0, y: 0 });
-    // Get all menu items (not separators or labels)
+    // Get all menu items (not separators or labels). Checkable items render
+    // role="menuitemcheckbox"/"menuitemradio" instead of "menuitem" (see
+    // ContextMenuItem), so all three roles are included here.
     const getMenuItems = useCallback(() => {
         if (!localRef.current)
             return [];
-        return Array.from(localRef.current.querySelectorAll('[role="menuitem"]:not([data-disabled="true"])'));
+        return Array.from(localRef.current.querySelectorAll('[role="menuitem"]:not([data-disabled="true"]), [role="menuitemcheckbox"]:not([data-disabled="true"]), [role="menuitemradio"]:not([data-disabled="true"])'));
     }, []);
     // Focus a menu item by index
     const focusItem = useCallback((index) => {
@@ -181,7 +187,7 @@ const ContextMenuBody = React__default.forwardRef(({ children, className, animat
         (document.documentElement.classList.contains("dark") ||
             document.body.classList.contains("dark") ||
             document.querySelector(".dark") !== null);
-    const menuContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, className: cn("fixed z-50", isDarkMode && "dark", theme.contentStyle, className), style: {
+    const menuContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, className: cn("fixed z-50", isDarkMode && "dark", surfaceClasses(surfaceLevel, { translucent: true }), theme.contentStyle, className), style: {
                 top: `${position.y}px`,
                 left: `${position.x}px`,
             }, role: "menu", "aria-label": ariaLabel || "Context menu", 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
@@ -190,7 +196,7 @@ const ContextMenuBody = React__default.forwardRef(({ children, className, animat
                     type: "spring",
                     stiffness: 500,
                     damping: 30,
-                }, "data-state": isOpen ? "open" : "closed", ...domProps, children: children })) }));
+                }, "data-state": isOpen ? "open" : "closed", "data-flikkui-portal": "", ...domProps, children: jsx(SurfaceProvider, { level: surfaceLevel, children: children }) })) }));
     // Always use portal for context menus
     const portalTarget = isClient ? document.body : null;
     return portalTarget ? createPortal(menuContent, portalTarget) : null;

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

@@ -1,3 +1,4 @@
+"use client";
 import { createContext, useContext } from 'react';
 
 // Main context menu context

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

@@ -1,7 +1,7 @@
-import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import React__default, { useCallback } from 'react';
 import { CheckIcon } from '@heroicons/react/24/outline';
-import { cn } from '../../../utils/cn.js';
 import { useContextMenuContext } from './ContextMenuContext.js';
 import { MenuItem } from '../MenuItem/MenuItem.js';
 
@@ -9,7 +9,7 @@ import { MenuItem } from '../MenuItem/MenuItem.js';
  * ContextMenuItem - Individual menu item with optional check indicator.
  * Built on shared MenuItem, adds checked state and ContextMenu context integration.
  */
-const ContextMenuItem = React__default.forwardRef(({ children, className, checked = false, disabled = false, isDanger = false, shortcut, onSelect, startContent, endContent, subtitle, ...props }, ref) => {
+const ContextMenuItem = React__default.forwardRef(({ children, className, checked, disabled = false, isDanger = false, shortcut, onSelect, startContent, endContent, subtitle, ...props }, ref) => {
     const { onOpenChange, theme } = useContextMenuContext();
     const handleActivate = useCallback(() => {
         if (disabled)
@@ -17,13 +17,23 @@ const ContextMenuItem = React__default.forwardRef(({ children, className, checke
         onSelect === null || onSelect === void 0 ? void 0 : onSelect();
         onOpenChange(false);
     }, [disabled, onSelect, onOpenChange]);
-    // Combine checked icon with startContent (CheckIcon uses absolute positioning)
-    const hasPrefix = checked || !!startContent;
-    const resolvedStartContent = hasPrefix ? (jsxs(Fragment, { children: [checked && (jsx(CheckIcon, { className: theme.itemCheckedStyle, "aria-hidden": "true" })), startContent] })) : undefined;
+    // An item is "checkable" whenever `checked` is provided (even `false`). The check
+    // occupies the same leading icon slot as `startContent`, so checkable rows align
+    // with icon rows AND the label never shifts when toggled — a `size-4` spacer holds
+    // the gutter while unchecked.
+    const isCheckable = checked !== undefined;
+    const checkIndicator = isCheckable ? (checked ? (jsx(CheckIcon, { className: theme.itemCheckedStyle, "aria-hidden": "true" })) : (jsx("span", { className: "size-4 shrink-0", "aria-hidden": "true" }))) : null;
+    const resolvedStartContent = checkIndicator || startContent ? (jsxs(Fragment, { children: [checkIndicator, startContent] })) : undefined;
     // Build end content: user's endContent OR shortcut display
     const resolvedEndContent = endContent ||
         (shortcut ? (jsx("span", { className: "text-sm text-[var(--color-text-muted)] font-mono", children: shortcut })) : undefined);
-    return (jsx(MenuItem, { ref: ref, role: "menuitem", disabled: disabled, isDanger: isDanger, startContent: resolvedStartContent, endContent: resolvedEndContent, subtitle: subtitle, onActivate: handleActivate, "data-checked": checked, "aria-checked": checked ? "true" : undefined, className: cn(checked && "pl-6", className), theme: {
+    // aria-checked is only a valid attribute on role="menuitemcheckbox" /
+    // "menuitemradio" (not plain "menuitem") — checkable items switch role so
+    // the checked state is announced without an invalid aria-allowed-attr
+    // combination. There's no radio-group-style checkable variant on this
+    // component today, so checkable items always use menuitemcheckbox.
+    const role = isCheckable ? "menuitemcheckbox" : "menuitem";
+    return (jsx(MenuItem, { ref: ref, role: role, disabled: disabled, isDanger: isDanger, startContent: resolvedStartContent, endContent: resolvedEndContent, subtitle: subtitle, onActivate: handleActivate, "data-checked": isCheckable ? checked : undefined, "aria-checked": isCheckable ? (checked ? "true" : "false") : undefined, className: className, theme: {
             baseStyle: theme.itemStyle,
             dangerStyle: theme.itemDangerStyle,
             focusStyle: theme.itemFocusStyle,

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

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

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

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

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

@@ -1,5 +1,6 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import { useState, useRef, useCallback } from 'react';
+import { useState, useRef, useCallback, useMemo } from 'react';
 import { SubMenuContext } from './ContextMenuContext.js';
 
 /**
@@ -28,11 +29,11 @@ const ContextMenuSub = ({ children, className, }) => {
             setIsOpen(false);
         }, 150);
     }, []);
-    const contextValue = {
+    const contextValue = useMemo(() => ({
         isOpen,
         onOpenChange: handleOpenChange,
         triggerRef,
-    };
+    }), [isOpen, handleOpenChange, triggerRef]);
     return (jsx(SubMenuContext.Provider, { value: contextValue, children: jsx("div", { className: className, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: children }) }));
 };
 ContextMenuSub.displayName = "ContextMenuSub";

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

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default, { useRef, useState, useEffect, useCallback } from 'react';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
@@ -5,11 +6,14 @@ import { createPortal } from 'react-dom';
 import { cn } from '../../../utils/cn.js';
 import { useContextMenuContext, useSubMenuContext } from './ContextMenuContext.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
 /**
  * ContextMenuSubBody - Submenu content positioned to the right of trigger
  */
-const ContextMenuSubBody = React__default.forwardRef(({ children, className, animation = true, ...props }, ref) => {
+const ContextMenuSubBody = React__default.forwardRef(({ children, className, animation = true, elevation, lift, ...props }, ref) => {
+    // Relative elevation: lift above the parent menu surface (overlay base = 5).
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const { theme } = useContextMenuContext();
     const { isOpen, triggerRef, onOpenChange } = useSubMenuContext();
     const shouldReduceMotion = useReducedMotion();
@@ -90,7 +94,7 @@ const ContextMenuSubBody = React__default.forwardRef(({ children, className, ani
         (document.documentElement.classList.contains("dark") ||
             document.body.classList.contains("dark") ||
             document.querySelector(".dark") !== null);
-    const submenuContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, className: cn("fixed z-50", isDarkMode && "dark", theme.subContentStyle, className), style: {
+    const submenuContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, className: cn("fixed z-50", isDarkMode && "dark", surfaceClasses(surfaceLevel, { translucent: true }), theme.subContentStyle, className), style: {
                 top: `${position.y}px`,
                 left: `${position.x}px`,
             }, role: "menu", "aria-label": "Submenu", variants: shouldReduceMotion || !animation ? {} : menuVariants, initial: shouldReduceMotion || !animation ? undefined : "hidden", animate: shouldReduceMotion || !animation ? undefined : "visible", exit: shouldReduceMotion || !animation ? undefined : "exit", transition: shouldReduceMotion || !animation
@@ -99,7 +103,7 @@ const ContextMenuSubBody = React__default.forwardRef(({ children, className, ani
                     type: "spring",
                     stiffness: 500,
                     damping: 30,
-                }, "data-state": isOpen ? "open" : "closed", ...domProps, children: children })) }));
+                }, "data-state": isOpen ? "open" : "closed", "data-flikkui-portal": "", ...domProps, children: jsx(SurfaceProvider, { level: surfaceLevel, children: children }) })) }));
     // Always use portal for submenus
     const portalTarget = isClient ? document.body : null;
     return portalTarget ? createPortal(submenuContent, portalTarget) : null;

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

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useRef, useCallback } from 'react';
 import { ChevronRightIcon } from '@heroicons/react/24/outline';
@@ -7,7 +8,7 @@ import { useContextMenuContext, useSubMenuContext } from './ContextMenuContext.j
 /**
  * ContextMenuSubTrigger - Trigger for nested submenu with chevron indicator
  */
-const ContextMenuSubTrigger = React__default.forwardRef(({ children, className, disabled = false, ...props }, ref) => {
+const ContextMenuSubTrigger = React__default.forwardRef(({ children, className, disabled = false, startContent, ...props }, ref) => {
     const { theme } = useContextMenuContext();
     const { isOpen, onOpenChange, triggerRef } = useSubMenuContext();
     const hoverTimeoutRef = useRef(null);
@@ -53,7 +54,7 @@ const ContextMenuSubTrigger = React__default.forwardRef(({ children, className,
             ref.current = el;
         }
     }, [ref, triggerRef]);
-    return (jsxs("div", { ref: handleRef, role: "menuitem", "aria-haspopup": "true", "aria-expanded": isOpen, "aria-disabled": disabled, "data-state": isOpen ? "open" : "closed", "data-disabled": disabled, tabIndex: disabled ? undefined : -1, className: cn(theme.subTriggerStyle, theme.itemFocusStyle, className), onMouseEnter: handleMouseEnter, onKeyDown: handleKeyDown, ...props, children: [jsx("span", { className: "flex-1 truncate", children: children }), jsx(ChevronRightIcon, { className: "absolute right-2 top-1/2 -translate-y-1/2 size-3 text-[var(--color-text-secondary)]", "aria-hidden": "true", strokeWidth: 2 })] }));
+    return (jsxs("div", { ref: handleRef, role: "menuitem", "aria-haspopup": "true", "aria-expanded": isOpen, "aria-disabled": disabled, "data-state": isOpen ? "open" : "closed", "data-disabled": disabled, tabIndex: disabled ? undefined : -1, className: cn(theme.subTriggerStyle, theme.itemFocusStyle, className), onMouseEnter: handleMouseEnter, onKeyDown: handleKeyDown, ...props, children: [startContent && (jsx("div", { className: "flex items-center justify-center flex-shrink-0", children: startContent })), jsx("span", { className: "flex-1 truncate", children: children }), jsx(ChevronRightIcon, { className: "absolute right-2 top-1/2 -translate-y-1/2 size-3 text-[var(--color-text-secondary)]", "aria-hidden": "true", strokeWidth: 2 })] }));
 });
 ContextMenuSubTrigger.displayName = "ContextMenuSubTrigger";
 

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

@@ -1,3 +1,4 @@
+"use client";
 import React__default, { useCallback } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { useContextMenuContext } from './ContextMenuContext.js';
@@ -6,6 +7,7 @@ import { useContextMenuContext } from './ContextMenuContext.js';
  * ContextMenuTrigger - Area that triggers the context menu on right-click
  */
 const ContextMenuTrigger = React__default.forwardRef(({ children, className, disabled = false }, ref) => {
+    var _a;
     const { onOpenChange, triggerRef } = useContextMenuContext();
     // Handle right-click event
     const handleContextMenu = useCallback((e) => {
@@ -41,6 +43,12 @@ const ContextMenuTrigger = React__default.forwardRef(({ children, className, dis
         onContextMenu: handleContextMenu,
         className: cn(child.props.className, className),
         "data-disabled": disabled,
+        // Not all trigger elements (e.g. a plain <div>) are natively
+        // focusable. tabIndex={-1} makes the element programmatically
+        // focusable (for the focus-return-on-close behavior in ContextMenu)
+        // without inserting it into the page's Tab order. Respects an
+        // explicit tabIndex the consumer already set.
+        tabIndex: (_a = child.props.tabIndex) !== null && _a !== void 0 ? _a : -1,
     });
 });
 ContextMenuTrigger.displayName = "ContextMenu.Trigger";

package/dist/components/core/DotSeparator/DotSeparator.js

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

package/dist/components/core/DragDrop/DragDrop.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { createContext, useState, useRef, useCallback, useMemo, useEffect, useContext } from 'react';
 import { motion } from 'motion/react';
@@ -10,15 +11,18 @@ const DragDropContext = createContext(null);
 // Provider
 // ---------------------------------------------------------------------------
 const DragDropProvider = React__default.forwardRef(({ children }, _ref) => {
+    var _a;
     // pointer drag state
     const [activeDrag, setActiveDrag] = useState(null);
     const pointerRef = useRef(null);
     const dropZones = useRef(new Map());
     const groupIdRef = useRef(`dd-${Math.random().toString(36).slice(2)}`);
     // keyboard drag state
-    const [keyboardDragId, setKeyboardDragId] = useState(null);
+    const [keyboardDragData, setKeyboardDragData] = useState(null);
     const [keyboardDragLabel, setKeyboardDragLabel] = useState('');
+    const [keyboardZoneIndex, setKeyboardZoneIndex] = useState(-1);
     const [announcement, setAnnouncement] = useState('');
+    const keyboardDragId = (_a = keyboardDragData === null || keyboardDragData === void 0 ? void 0 : keyboardDragData.id) !== null && _a !== void 0 ? _a : null;
     // Stable ordered list of drop-zone IDs so Arrow-key cycling is deterministic
     const dropZoneOrder = useRef([]);
     const registerDropZone = useCallback((id, element) => {
@@ -34,13 +38,15 @@ const DragDropProvider = React__default.forwardRef(({ children }, _ref) => {
     const setPointer = useCallback((point) => {
         pointerRef.current = point;
     }, []);
-    const startKeyboardDrag = useCallback((id, label) => {
-        setKeyboardDragId(id);
+    const startKeyboardDrag = useCallback((data, label) => {
+        setKeyboardDragData(data);
         setKeyboardDragLabel(label);
+        setKeyboardZoneIndex(-1);
     }, []);
     const endKeyboardDrag = useCallback(() => {
-        setKeyboardDragId(null);
+        setKeyboardDragData(null);
         setKeyboardDragLabel('');
+        setKeyboardZoneIndex(-1);
     }, []);
     const announce = useCallback((message) => {
         // Briefly clear then set to guarantee re-announcement of the same string
@@ -58,10 +64,13 @@ const DragDropProvider = React__default.forwardRef(({ children }, _ref) => {
         unregisterDropZone,
         dropZones: dropZones.current,
         keyboardDragId,
+        keyboardDragData,
         keyboardDragLabel,
         startKeyboardDrag,
         endKeyboardDrag,
         dropZoneOrder,
+        keyboardZoneIndex,
+        setKeyboardZoneIndex,
         announce,
     }), [
         activeDrag,
@@ -69,9 +78,12 @@ const DragDropProvider = React__default.forwardRef(({ children }, _ref) => {
         registerDropZone,
         unregisterDropZone,
         keyboardDragId,
+        keyboardDragData,
         keyboardDragLabel,
         startKeyboardDrag,
         endKeyboardDrag,
+        keyboardZoneIndex,
+        setKeyboardZoneIndex,
         announce,
     ]);
     return (jsxs(DragDropContext.Provider, { value: contextValue, children: [children, jsx("div", { className: "sr-only", "aria-live": "assertive", "aria-atomic": "true", "aria-relevant": "additions text", children: announcement })] }));
@@ -134,14 +146,14 @@ const Draggable = React__default.forwardRef(({ children, dragData, dragLabel, cl
     }, [dragData, onDragEnd, context]);
     // ----- keyboard drag handler (new) --------------------------------------
     const handleKeyDown = useCallback((e) => {
-        var _a, _b, _c;
+        var _a;
         if (disabled)
             return;
         const isGrabbed = context.keyboardDragId === dragData.id;
         if ((e.key === ' ' || e.key === 'Enter') && !isGrabbed) {
             // Initiate keyboard drag
             e.preventDefault();
-            context.startKeyboardDrag(dragData.id, resolvedLabel);
+            context.startKeyboardDrag(dragData, resolvedLabel);
             context.announce(`Grabbed ${resolvedLabel}. Use arrow keys to move between drop zones. Press Space or Enter to drop, or Escape to cancel.`);
             return;
         }
@@ -160,12 +172,16 @@ const Draggable = React__default.forwardRef(({ children, dragData, dragLabel, cl
                 const order = context.dropZoneOrder.current;
                 if (order.length === 0)
                     return;
-                // Find the currently focused drop zone, advance to next
-                const focusedDropId = (_b = document.activeElement) === null || _b === void 0 ? void 0 : _b.getAttribute('data-dropzone-id');
-                const currentIdx = focusedDropId ? order.indexOf(focusedDropId) : -1;
-                const nextIdx = (currentIdx + 1) % order.length;
+                // Advance from the last-known zone index, tracked in React state
+                // (context.keyboardZoneIndex) rather than read off the DOM -- the
+                // element that actually hears Arrow keys is this Draggable, which
+                // never carries `data-dropzone-id` (only Dropzone containers do),
+                // so reading the DOM attribute here always missed.
+                const currentIdx = context.keyboardZoneIndex;
+                const nextIdx = currentIdx === -1 ? 0 : (currentIdx + 1) % order.length;
                 const nextEl = context.dropZones.get(order[nextIdx]);
                 nextEl === null || nextEl === void 0 ? void 0 : nextEl.focus();
+                context.setKeyboardZoneIndex(nextIdx);
                 return;
             }
             if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
@@ -173,15 +189,15 @@ const Draggable = React__default.forwardRef(({ children, dragData, dragLabel, cl
                 const order = context.dropZoneOrder.current;
                 if (order.length === 0)
                     return;
-                const focusedDropId = (_c = document.activeElement) === null || _c === void 0 ? void 0 : _c.getAttribute('data-dropzone-id');
-                const currentIdx = focusedDropId ? order.indexOf(focusedDropId) : 0;
-                const prevIdx = (currentIdx - 1 + order.length) % order.length;
+                const currentIdx = context.keyboardZoneIndex;
+                const prevIdx = currentIdx === -1 ? order.length - 1 : (currentIdx - 1 + order.length) % order.length;
                 const prevEl = context.dropZones.get(order[prevIdx]);
                 prevEl === null || prevEl === void 0 ? void 0 : prevEl.focus();
+                context.setKeyboardZoneIndex(prevIdx);
                 return;
             }
         }
-    }, [disabled, context, dragData.id, resolvedLabel]);
+    }, [disabled, context, dragData, resolvedLabel]);
     const isPointerDragging = ((_a = context.activeDrag) === null || _a === void 0 ? void 0 : _a.id) === dragData.id;
     const isKeyboardGrabbed = context.keyboardDragId === dragData.id;
     return (jsx(motion.div, { ref: (node) => {
@@ -314,6 +330,10 @@ const Droppable = React__default.forwardRef(({ children, acceptedTypes, classNam
             return;
         const order = context.dropZoneOrder.current;
         const zoneIndex = order.indexOf(stableId);
+        // Keep the shared cycling index in sync with whichever zone actually
+        // has focus (whether it got there via Arrow-key cycling or native Tab)
+        // so the next Arrow press continues from the real position.
+        context.setKeyboardZoneIndex(zoneIndex);
         const zoneNumber = zoneIndex === -1 ? '' : ` ${zoneIndex + 1}`;
         context.announce(`Over drop zone${zoneNumber}.`);
     }, [isKeyboardDragActive, context, stableId]);
@@ -324,30 +344,29 @@ const Droppable = React__default.forwardRef(({ children, acceptedTypes, classNam
         if (e.key !== ' ' && e.key !== 'Enter')
             return;
         e.preventDefault();
-        const grabbedId = context.keyboardDragId;
+        const grabbedData = context.keyboardDragData;
         const grabbedLabel = context.keyboardDragLabel;
-        if (!grabbedId)
+        if (!grabbedData)
             return;
-        // Check type acceptance
-        const draggedDragData = { id: grabbedId };
-        if (acceptedTypes && acceptedTypes.length > 0) ;
+        // NOTE: acceptedTypes filtering is intentionally skipped for the
+        // keyboard path to keep it simple; the pointer path already handles it.
         const order = context.dropZoneOrder.current;
         const zoneIndex = order.indexOf(stableId);
         const zoneNumber = zoneIndex === -1 ? '' : ` ${zoneIndex + 1}`;
-        // Fire the drop callback
-        onDrop === null || onDrop === void 0 ? void 0 : onDrop(draggedDragData);
-        // Also fire as a custom event so compound setups with `motion-drop`
-        // listeners on the DOM element are notified
-        if (dropRef.current) {
-            const dropEvent = new CustomEvent('motion-drop', {
-                detail: draggedDragData,
-                bubbles: true,
-            });
-            dropRef.current.dispatchEvent(dropEvent);
-        }
+        // Fire the drop callback exactly once, forwarding the full drag data
+        // (id + type + data) so the payload shape matches a pointer-initiated
+        // drop. Do NOT also redispatch a `motion-drop` CustomEvent here --
+        // Droppable already listens for that event itself (registered just
+        // above, for the pointer-drag path), so redispatching it here would
+        // invoke `onDrop` a second time for the same keyboard action. The
+        // pointer path still relies on the event because Draggable's
+        // `handleDragEnd` hit-tests drop zones from the DOM and has no direct
+        // reference to this Droppable's `onDrop` prop; the keyboard path
+        // already has that reference, so the direct call is sufficient.
+        onDrop === null || onDrop === void 0 ? void 0 : onDrop(grabbedData);
         context.announce(`${grabbedLabel} dropped in position${zoneNumber}.`);
         context.endKeyboardDrag();
-    }, [isKeyboardDragActive, context, stableId, acceptedTypes, onDrop]);
+    }, [isKeyboardDragActive, context, stableId, onDrop]);
     return (jsx(motion.div, { ref: (node) => {
             dropRef.current = node;
             if (typeof ref === 'function') {

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

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Drawer overlay animation variants
  */
@@ -32,8 +33,8 @@ const getDrawerContentAnimations = (position) => {
                 x: 0,
                 transition: {
                     type: "spring",
-                    damping: 40,
-                    stiffness: 300,
+                    stiffness: 280,
+                    damping: 28,
                     mass: 0.8,
                 },
             },
@@ -51,8 +52,8 @@ const getDrawerContentAnimations = (position) => {
                 x: 0,
                 transition: {
                     type: "spring",
-                    damping: 40,
-                    stiffness: 300,
+                    stiffness: 280,
+                    damping: 28,
                     mass: 0.8,
                 },
             },
@@ -70,8 +71,8 @@ const getDrawerContentAnimations = (position) => {
                 y: 0,
                 transition: {
                     type: "spring",
-                    damping: 40,
-                    stiffness: 300,
+                    stiffness: 280,
+                    damping: 28,
                     mass: 0.8,
                 },
             },
@@ -89,8 +90,8 @@ const getDrawerContentAnimations = (position) => {
                 y: 0,
                 transition: {
                     type: "spring",
-                    damping: 40,
-                    stiffness: 300,
+                    stiffness: 280,
+                    damping: 28,
                     mass: 0.8,
                 },
             },

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

@@ -1,7 +1,7 @@
-import { DrawerProps, DrawerContextValue } from "./Drawer.types";
-export declare const useDrawerContext: () => DrawerContextValue;
+import { DrawerProps } from "./Drawer.types";
+export { DrawerContext, useDrawerContext } from "./DrawerContext";
 export declare const Drawer: {
-    ({ isOpen, onClose, title, subtitle, icon, position, size, closeOnOverlayClick, closeOnEsc, showCloseButton, children, className, theme: themeOverrides, scale, closeOnBack, ...props }: DrawerProps): import("react/jsx-runtime").JSX.Element;
+    ({ isOpen, onClose, title, subtitle, icon, position, size, closeOnOverlayClick, closeOnEsc, showCloseButton, children, className, theme: themeOverrides, scale, closeOnBack, elevation, lift, ...props }: DrawerProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 } & {
     Header: {

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

@@ -1,15 +1,19 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { createContext, useId, useMemo, useRef, useEffect, useContext } from 'react';
+import React__default, { useId, useMemo, useRef, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { useScaleBackground } from '../../../hooks/useScaleBackground.js';
 import { Overlay } from '../../effects/Overlay/Overlay.js';
 import { drawerTheme, drawerSizeVariants, drawerPositionVariantsFullWidth, drawerPositionVariantsWithMargin } from './Drawer.theme.js';
 import { drawerOverlayAnimations, getDrawerContentAnimations } from './Drawer.animations.js';
+import { DrawerContext } from './DrawerContext.js';
+export { useDrawerContext } from './DrawerContext.js';
 import { DrawerHeader } from './DrawerHeader.js';
 import { DrawerTitle } from './DrawerTitle.js';
 import { DrawerSubtitle } from './DrawerSubtitle.js';
 import { DrawerBody } from './DrawerBody.js';
 import { DrawerFooter } from './DrawerFooter.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
 /** Manages browser history so the back button closes the drawer instead of navigating. */
 function useCloseOnBack(isOpen, onClose, enabled) {
@@ -34,15 +38,10 @@ function useCloseOnBack(isOpen, onClose, enabled) {
         };
     }, [isOpen, onClose, enabled]);
 }
-// Create context for Drawer components
-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;
-};
-const DrawerRoot = ({ isOpen, onClose, title, subtitle, icon, position = "right", size = "md", closeOnOverlayClick = true, closeOnEsc = true, showCloseButton = true, children, className, theme: themeOverrides, scale = 0.94, closeOnBack = false, ...props }) => {
+const DrawerRoot = ({ isOpen, onClose, title, subtitle, icon, position = "right", size = "md", closeOnOverlayClick = true, closeOnEsc = true, showCloseButton = true, children, className, theme: themeOverrides, scale = 0.94, closeOnBack = false, elevation, lift, ...props }) => {
+    // Grounded backdrop overlay: a Drawer covers the viewport edge, so it paints a FIXED
+    // rung 4 regardless of where its <Drawer> JSX sits. Content inside still lifts relative.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 4, ground: true, elevation, lift });
     // Close drawer on browser back button
     useCloseOnBack(isOpen, onClose, closeOnBack);
     // iOS-style scale background effect
@@ -102,13 +101,13 @@ const DrawerRoot = ({ isOpen, onClose, title, subtitle, icon, position = "right"
     const positionVariant = size === "full"
         ? drawerPositionVariantsFullWidth[position]
         : drawerPositionVariantsWithMargin[position];
-    return (jsx(Overlay, { isOpen: isOpen, onClose: onClose, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, position: "none", role: "dialog", ariaModal: true, ariaLabelledBy: titleId, ariaDescribedBy: subtitleId, contentClassName: cn(theme.container, positionVariant, isSizeToken && size !== "full" && sizeVariant, !isSizeToken && sizeVariant, // raw Tailwind class
+    return (jsx(Overlay, { isOpen: isOpen, onClose: onClose, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, position: "none", role: "dialog", ariaModal: true, ariaLabelledBy: titleId, ariaDescribedBy: subtitleId, contentClassName: cn(surfaceClasses(surfaceLevel, { translucent: false, shadow: false }), theme.container, positionVariant, isSizeToken && size !== "full" && sizeVariant, !isSizeToken && sizeVariant, // raw Tailwind class
         className), animations: {
             overlay: drawerOverlayAnimations,
             content: getDrawerContentAnimations(position),
-        }, ...props, children: jsx(DrawerContext.Provider, { value: contextValue, children: jsxs("div", { className: theme.inner, children: [shouldAutoRenderHeader && (jsxs(DrawerHeader, { icon: icon, children: [title &&
-                                (typeof title === "string" ? (jsx(DrawerTitle, { children: title })) : (title)), subtitle &&
-                                (typeof subtitle === "string" ? (jsx(DrawerSubtitle, { children: subtitle })) : (subtitle))] })), children] }) }) }));
+        }, ...props, children: jsx(DrawerContext.Provider, { value: contextValue, children: jsx(SurfaceProvider, { level: surfaceLevel, children: jsxs("div", { className: theme.inner, children: [shouldAutoRenderHeader && (jsxs(DrawerHeader, { icon: icon, children: [title &&
+                                    (typeof title === "string" ? (jsx(DrawerTitle, { children: title })) : (title)), subtitle &&
+                                    (typeof subtitle === "string" ? (jsx(DrawerSubtitle, { children: subtitle })) : (subtitle))] })), children] }) }) }) }));
 };
 DrawerRoot.displayName = "Drawer";
 // Attach compound subcomponents
@@ -120,4 +119,4 @@ const Drawer = Object.assign(DrawerRoot, {
     Footer: DrawerFooter,
 });
 
-export { Drawer, useDrawerContext };
+export { Drawer, DrawerContext };

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

@@ -1,10 +1,12 @@
 const drawerTheme = {
     // Note: overlay styling is now handled by the shared Overlay component
     overlay: "",
-    container: "fixed bg-[var(--color-surface-raised)] shadow-2xl shadow-black/30 " +
+    // bg comes from the relative-elevation engine (surfaceClasses) at runtime so a drawer
+    // lifts above its host substrate; keep the dramatic shadow + ring + border + radius here.
+    container: "fixed shadow-2xl shadow-black/30 m-3 " +
         "border border-[var(--color-border)] ring-4 ring-white/10 " +
         "flex flex-col overflow-hidden rounded-[var(--drawer-radius)] " +
-        "dark:bg-[var(--color-surface-raised)] dark:ring-white/5",
+        "dark:ring-white/5",
     inner: "h-full flex flex-col",
     header: "flex items-start justify-between p-4 border-b border-[var(--color-border)] shrink-0 text-[var(--color-text-primary)] gap-4",
     headerContent: "flex items-start gap-3 flex-1 min-w-0",
@@ -16,10 +18,10 @@ const drawerTheme = {
 };
 // Position variants with margin support
 const drawerPositionVariantsWithMargin = {
-    left: "left-0 top-0 h-full", // 100vh - 1.5rem top - 1.5rem bottom
-    right: "right-0 top-0 h-full",
-    top: "top-0 left-0 w-full",
-    bottom: "bottom-0 left-0 w-full",
+    left: "left-0 top-0 bottom-0", // 100vh - margins
+    right: "right-0 top-0 bottom-0",
+    top: "top-0 left-0 right-0",
+    bottom: "bottom-0 left-0 right-0",
 };
 // Position variants for full-width/height drawers with consistent margins
 const drawerPositionVariantsFullWidth = {

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export type DrawerPosition = "left" | "right" | "top" | "bottom";
 export type DrawerSizeToken = "sm" | "md" | "lg" | "full";
 /** Preset size token or any arbitrary Tailwind width/height class, e.g. `"w-80"`, `"w-[50vw]"` */
@@ -54,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.

package/dist/components/core/Drawer/DrawerBody.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 DrawerBody = ({ children, className, ...props }) => {
     const { theme } = useDrawerContext();

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;