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

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

@@ -1,10 +1,20 @@
 const cardTheme = {
-    baseStyle: "rounded-[var(--card-radius)] overflow-hidden bg-white border border-[var(--color-border)] shadow-xs dark:bg-[var(--color-background-secondary)] [&>*+*]:pt-0",
-    headerStyle: "flex flex-col space-y-1.5 p-6",
-    titleStyle: "text-base font-semibold leading-none text-[var(--color-text-primary)]",
-    subtitleStyle: "text-sm text-[var(--color-text-muted)]",
-    contentStyle: "p-6",
-    footerStyle: "flex items-center p-6",
+    // 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 px-[var(--card-px)] py-[var(--card-py)] items-start",
+    // text-[length:...] (not bare text-[var(...)]) is required — see TYPE ROLE
+    // SYSTEM in theme.css for why a bare var() would resolve to color instead.
+    titleStyle: "text-[length:var(--card-title-size)] font-semibold leading-none text-[var(--color-text-primary)]",
+    subtitleStyle: "text-sm text-[var(--color-text-secondary)] mt-2",
+    // Default to full py (top included). [[data-card-region]~&]:pt-0 zeroes the seam
+    // ONLY when an actual region (Header/Body) precedes this one — a general-sibling
+    // selector keyed off data-card-region, not `:first-child`. `:first-child` broke
+    // when a decorative absolutely-positioned sibling (e.g. DotPattern) sat before
+    // Body in the DOM: it still counts as a structural first child even though it
+    // takes no layout space, so Body silently lost its top padding.
+    bodyStyle: "px-[var(--card-px)] py-[var(--card-py)] [[data-card-region]~&]:pt-0",
+    footerStyle: "flex items-center px-[var(--card-px)] py-[var(--card-py)] [[data-card-region]~&]:pt-0",
 };
 
 export { cardTheme };

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

@@ -1,10 +1,11 @@
 import { HTMLAttributes, ReactNode, ForwardRefExoticComponent, RefAttributes } from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export interface CardTheme {
     baseStyle: string;
     headerStyle: string;
     titleStyle: string;
     subtitleStyle: string;
-    contentStyle: string;
+    bodyStyle: string;
     footerStyle: string;
 }
 export interface CardThemeOverrides {
@@ -12,14 +13,46 @@ export interface CardThemeOverrides {
     headerStyle?: string;
     titleStyle?: string;
     subtitleStyle?: string;
-    contentStyle?: string;
+    bodyStyle?: string;
     footerStyle?: string;
 }
-export interface CardProps extends HTMLAttributes<HTMLDivElement> {
+export interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     /**
-     * The content to be displayed inside the card
+     * The content to be displayed inside the card. In slot-prop mode (any of
+     * `title`/`subtitle`/`actions`/`footer` set) children render inside an
+     * auto `Card.Body`; otherwise they render raw (compound mode).
      */
     children?: ReactNode;
+    /**
+     * Header title (serializable slot-prop). Renders `Card.Header` + `Card.Title`
+     * internally. Mirrors `Section`. Omit and use the compound `Card.Header`
+     * parts for full control.
+     */
+    title?: ReactNode;
+    /**
+     * Header subtitle (serializable slot-prop). Renders `Card.Subtitle`.
+     */
+    subtitle?: ReactNode;
+    /**
+     * Header-end controls — buttons, links, Segmented, a kebab menu, etc.
+     * Right-aligned next to the title. Holds `ReactNode`, so it is NOT part of
+     * the generative schema (app-code / hand-authored only), like `Section`'s.
+     * For a card whose primary control is a full Tabs bar, compose `Tabs` in the
+     * body instead of overloading this slot.
+     */
+    actions?: ReactNode;
+    /**
+     * Footer content (serializable slot-prop). Renders `Card.Footer`. Holds
+     * `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
      */
@@ -39,28 +72,23 @@ export interface CardProps extends HTMLAttributes<HTMLDivElement> {
 }
 export interface CardComponent extends ForwardRefExoticComponent<CardProps & RefAttributes<HTMLDivElement>> {
     Header: ForwardRefExoticComponent<CardHeaderProps & RefAttributes<HTMLDivElement>>;
-    Title: ForwardRefExoticComponent<CardTitleProps & RefAttributes<HTMLHeadingElement>>;
-    Subtitle: ForwardRefExoticComponent<CardSubtitleProps & RefAttributes<HTMLParagraphElement>>;
-    Content: ForwardRefExoticComponent<CardContentProps & RefAttributes<HTMLDivElement>>;
+    Title: ForwardRefExoticComponent<CardTitleProps & RefAttributes<HTMLDivElement>>;
+    Subtitle: ForwardRefExoticComponent<CardSubtitleProps & RefAttributes<HTMLDivElement>>;
+    Body: ForwardRefExoticComponent<CardBodyProps & RefAttributes<HTMLDivElement>>;
     Footer: ForwardRefExoticComponent<CardFooterProps & RefAttributes<HTMLDivElement>>;
 }
 export interface CardHeaderProps extends HTMLAttributes<HTMLDivElement> {
-    children: ReactNode;
     className?: string;
 }
-export interface CardContentProps extends HTMLAttributes<HTMLDivElement> {
-    children: ReactNode;
+export interface CardBodyProps extends HTMLAttributes<HTMLDivElement> {
     className?: string;
 }
 export interface CardFooterProps extends HTMLAttributes<HTMLDivElement> {
-    children: ReactNode;
     className?: string;
 }
-export interface CardTitleProps extends HTMLAttributes<HTMLHeadingElement> {
-    children: ReactNode;
+export interface CardTitleProps extends HTMLAttributes<HTMLDivElement> {
     className?: string;
 }
-export interface CardSubtitleProps extends HTMLAttributes<HTMLParagraphElement> {
-    children: ReactNode;
+export interface CardSubtitleProps extends HTMLAttributes<HTMLDivElement> {
     className?: string;
 }

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

@@ -0,0 +1,3 @@
+import React from 'react';
+import { CardBodyProps } from './Card.types';
+export declare const CardBody: React.ForwardRefExoticComponent<CardBodyProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,11 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default from 'react';
+import { cn } from '../../../utils/cn.js';
+import { cardTheme } from './Card.theme.js';
+
+const CardBody = React__default.forwardRef(({ children, className, ...props }, ref) => {
+    return (jsx("div", { ref: ref, "data-card-region": "", className: cn(cardTheme.bodyStyle, className), ...props, children: children }));
+});
+CardBody.displayName = 'Card.Body';
+
+export { CardBody };

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

@@ -4,7 +4,7 @@ import { cn } from '../../../utils/cn.js';
 import { cardTheme } from './Card.theme.js';
 
 const CardFooter = React__default.forwardRef(({ children, className, ...props }, ref) => {
-    return (jsx("div", { ref: ref, className: cn(cardTheme.footerStyle, className), ...props, children: children }));
+    return (jsx("div", { ref: ref, "data-card-region": "", className: cn(cardTheme.footerStyle, className), ...props, children: children }));
 });
 CardFooter.displayName = 'CardFooter';
 

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

@@ -4,7 +4,7 @@ import { cn } from '../../../utils/cn.js';
 import { cardTheme } from './Card.theme.js';
 
 const CardHeader = React__default.forwardRef(({ children, className, ...props }, ref) => {
-    return (jsx("div", { ref: ref, className: cn(cardTheme.headerStyle, className), ...props, children: children }));
+    return (jsx("div", { ref: ref, "data-card-region": "", className: cn(cardTheme.headerStyle, className), ...props, children: children }));
 });
 CardHeader.displayName = 'CardHeader';
 

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

@@ -1,3 +1,3 @@
 import React from 'react';
 import { CardSubtitleProps } from './Card.types';
-export declare const CardSubtitle: React.ForwardRefExoticComponent<CardSubtitleProps & React.RefAttributes<HTMLParagraphElement>>;
+export declare const CardSubtitle: React.ForwardRefExoticComponent<CardSubtitleProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,3 +1,3 @@
 import React from 'react';
 import { CardTitleProps } from './Card.types';
-export declare const CardTitle: React.ForwardRefExoticComponent<CardTitleProps & React.RefAttributes<HTMLHeadingElement>>;
+export declare const CardTitle: React.ForwardRefExoticComponent<CardTitleProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,2 +1,2 @@
-export { Card, CardHeader, CardTitle, CardSubtitle, CardContent, CardFooter } from './Card';
-export type { CardProps, CardHeaderProps, CardTitleProps, CardSubtitleProps, CardContentProps, CardFooterProps, CardTheme, CardThemeOverrides } from './Card.types';
+export { Card, CardHeader, CardTitle, CardSubtitle, CardBody, CardFooter } from './Card';
+export type { CardProps, CardHeaderProps, CardTitleProps, CardSubtitleProps, CardBodyProps, CardFooterProps, CardTheme, CardThemeOverrides } from './Card.types';

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,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,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
-import { ChevronRightIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
+import { CaretRight, CaretDown } from '@phosphor-icons/react';
 import { cn } from '../../../utils/cn.js';
 import { useCarouselContext } from './CarouselContext.js';
 import { carouselTheme } from './Carousel.theme.js';
@@ -8,7 +9,7 @@ import { carouselTheme } from './Carousel.theme.js';
 const CarouselNext = React__default.forwardRef(({ className, icon, 'aria-label': ariaLabel, ...props }, ref) => {
     const { scrollNext, canScrollNext, orientation } = useCarouselContext();
     return (jsx("button", { ref: ref, type: "button", onClick: scrollNext, disabled: !canScrollNext, "aria-label": ariaLabel || 'Next slide', className: cn(carouselTheme.button, className), ...props, children: icon ||
-            (orientation === 'horizontal' ? (jsx(ChevronRightIcon, { className: carouselTheme.buttonIcon, "aria-hidden": "true" })) : (jsx(ChevronDownIcon, { className: carouselTheme.buttonIcon, "aria-hidden": "true" }))) }));
+            (orientation === 'horizontal' ? (jsx(CaretRight, { className: carouselTheme.buttonIcon, "aria-hidden": "true" })) : (jsx(CaretDown, { className: carouselTheme.buttonIcon, "aria-hidden": "true" }))) }));
 });
 CarouselNext.displayName = 'Carousel.Next';
 

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

@@ -1,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
-import { ChevronLeftIcon, ChevronUpIcon } from '@heroicons/react/24/outline';
+import { CaretLeft, CaretUp } from '@phosphor-icons/react';
 import { cn } from '../../../utils/cn.js';
 import { useCarouselContext } from './CarouselContext.js';
 import { carouselTheme } from './Carousel.theme.js';
@@ -8,7 +9,7 @@ import { carouselTheme } from './Carousel.theme.js';
 const CarouselPrevious = React__default.forwardRef(({ className, icon, 'aria-label': ariaLabel, ...props }, ref) => {
     const { scrollPrev, canScrollPrev, orientation } = useCarouselContext();
     return (jsx("button", { ref: ref, type: "button", onClick: scrollPrev, disabled: !canScrollPrev, "aria-label": ariaLabel || 'Previous slide', className: cn(carouselTheme.button, className), ...props, children: icon ||
-            (orientation === 'horizontal' ? (jsx(ChevronLeftIcon, { className: carouselTheme.buttonIcon, "aria-hidden": "true" })) : (jsx(ChevronUpIcon, { className: carouselTheme.buttonIcon, "aria-hidden": "true" }))) }));
+            (orientation === 'horizontal' ? (jsx(CaretLeft, { className: carouselTheme.buttonIcon, "aria-hidden": "true" })) : (jsx(CaretUp, { className: carouselTheme.buttonIcon, "aria-hidden": "true" }))) }));
 });
 CarouselPrevious.displayName = 'Carousel.Previous';
 

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 { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
+import { MagnifyingGlass } from '@phosphor-icons/react';
 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, onCommandSelect, }, 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)) {
@@ -144,8 +190,9 @@ const CommandPalette = React__default.forwardRef(({ isOpen, onClose, commands =
         if (command.disabled)
             return;
         command.onSelect();
+        onCommandSelect === null || onCommandSelect === void 0 ? void 0 : onCommandSelect(command.id);
         onClose();
-    }, [onClose]);
+    }, [onClose, onCommandSelect]);
     // Keep refs in sync for keydown handler to avoid re-attaching listener
     const flatFilteredCommandsRef = useRef(flatFilteredCommands);
     flatFilteredCommandsRef.current = flatFilteredCommands;
@@ -161,11 +208,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 +242,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 +256,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(MagnifyingGlass, { className: "w-5 h-5 text-[var(--color-text-muted)]", weight: "bold" }), 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
@@ -10,21 +16,12 @@ const commandPaletteTheme = {
     searchWrapper: "border-b border-[var(--color-border)] px-4 py-3 " + "",
     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)]",
-    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)]",
-    emptyState: "px-4 py-12 text-center text-sm text-[var(--color-text-muted)] " +
-        "dark:text-[var(--color-neutral-500)]",
+        "focus:outline-none focus:ring-0",
+    groupLabel: "px-4 py-1 text-xs font-semibold text-[var(--color-text-muted)]/50 uppercase",
+    // 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)]",
+    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,19 @@ 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;
+    /** Fired with the selected command's id, in addition to that command's own onSelect. */
+    onCommandSelect?: (id: string) => void;
 }
 /**
  * Theme overrides for the CommandPalette component
@@ -82,8 +96,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;
 }