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

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

@@ -12,8 +12,8 @@ const offlineIndicatorTheme = {
         banner: "w-full left-0 right-0 px-4 py-1 justify-center rounded-none shadow-real-lg",
         toast: "px-3 py-2 rounded-[var(--radius-base)] shadow-real-lg",
     },
-    offline: "bg-[var(--color-neutral-900)]/90 backdrop-blur-sm text-white",
-    online: "bg-[var(--color-success)]/90 backdrop-blur-sm text-white",
+    offline: "bg-[var(--color-neutral-900)]/90 backdrop-blur-sm text-[var(--color-neutral-100)]",
+    online: "bg-[var(--color-success)]/90 backdrop-blur-sm text-[var(--color-success-contrast)]",
     icon: "size-4 flex-shrink-0",
     message: "text-xs font-medium",
     queueCount: "text-xs opacity-80 ml-1",

package/dist/components/core/PageHeading/PageHeading.js

@@ -1,4 +1,5 @@
-import { jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { pageHeadingTheme } from './PageHeading.theme.js';
@@ -8,12 +9,16 @@ import { PageHeadingTitle } from './PageHeadingTitle.js';
 import { PageHeadingSubtitle } from './PageHeadingSubtitle.js';
 import { PageHeadingActions } from './PageHeadingActions.js';
 
-const PageHeadingRoot = React__default.forwardRef(({ children, className, separator = true, theme: customTheme = {}, ...props }, ref) => {
+const PageHeadingRoot = React__default.forwardRef(({ children, className, separator = true, title, subtitle, actions, theme: customTheme = {}, ...props }, ref) => {
     const theme = useMemo(() => ({
         ...pageHeadingTheme,
         ...customTheme,
     }), [customTheme]);
-    return (jsx("div", { ref: ref, className: cn(theme.baseStyle, separator && theme.separatorStyle, className), ...props, children: children }));
+    // Slot-prop mode: any header slot (title/subtitle/actions) composes the
+    // compound parts for us — one render path (reuses the real sub-components).
+    // Otherwise children render raw — the compound API path, unchanged.
+    const hasHeader = Boolean(title || subtitle || actions);
+    return (jsx("div", { ref: ref, className: cn(theme.baseStyle, separator && theme.separatorStyle, className), ...props, children: hasHeader ? (jsxs("div", { className: theme.headerStyle, children: [(title || subtitle) && (jsxs("div", { className: "min-w-0 flex-1", children: [title && jsx(PageHeadingTitle, { children: title }), subtitle && jsx(PageHeadingSubtitle, { children: subtitle })] })), actions && jsx(PageHeadingActions, { children: actions })] })) : (children) }));
 });
 PageHeadingRoot.displayName = "PageHeading";
 // Create compound component with proper typing

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

@@ -1,8 +1,8 @@
 const pageHeadingTheme = {
     baseStyle: "flex flex-col pb-6 mb-6",
-    headerStyle: "flex items-center gap-4",
-    titleStyle: "text-2xl font-semibold tracking-tight text-[var(--color-text-primary)]",
-    subtitleStyle: "text-sm text-[var(--color-text-muted)] mt-1",
+    headerStyle: "flex flex-col items-start sm:flex-row sm:items-center gap-4",
+    titleStyle: "text-xl font-bold  text-[var(--color-text-primary)]",
+    subtitleStyle: "text-sm text-[var(--color-text-secondary)] mt-1",
     actionsStyle: "sm:ml-auto flex items-center gap-2 shrink-0",
     iconStyle: "flex items-center justify-center shrink-0 text-[var(--color-text-muted)]",
     separatorStyle: "border-b border-[var(--color-border)] mt-4",

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

@@ -17,9 +17,20 @@ export interface PageHeadingThemeOverrides {
     iconStyle?: string;
     separatorStyle?: string;
 }
-export interface PageHeadingProps extends HTMLAttributes<HTMLDivElement> {
+export interface PageHeadingProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     children?: ReactNode;
     className?: string;
+    /**
+     * Heading title (serializable slot). Setting any slot-prop
+     * (`title`/`subtitle`/`actions`) switches PageHeading into managed mode —
+     * it composes the compound parts internally. Setting none renders
+     * `children` raw (pure compound mode).
+     */
+    title?: ReactNode;
+    /** Secondary line under the title (serializable slot). */
+    subtitle?: ReactNode;
+    /** Right-aligned actions next to the title. */
+    actions?: ReactNode;
     /** Show bottom separator. @default true */
     separator?: boolean;
     theme?: PageHeadingThemeOverrides;
@@ -42,7 +53,7 @@ export interface PageHeadingIconProps extends HTMLAttributes<HTMLDivElement> {
 }
 export interface PageHeadingBackButtonProps {
     /** Text label next to the back arrow. @default "Back" */
-    label?: string;
+    label?: ReactNode;
     onClick?: () => void;
     className?: string;
 }

package/dist/components/core/PageHeading/PageHeadingBackButton.js

@@ -1,11 +1,14 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
 import { ArrowLeftIcon } from '@heroicons/react/20/solid';
-import { Button } from '../Button/Button.js';
+import { Link } from '../Link/Link.js';
 
 const PageHeadingBackButton = React__default.forwardRef(({ label = "Back", onClick, className, ...props }, ref) => {
-    return (jsxs(Button, { ref: ref, variant: "link", color: "neutral", size: "sm", onClick: onClick, className: cn("mb-2 w-fit", className), ...props, children: [jsx(ArrowLeftIcon, { className: "size-4" }), label] }));
+    return (jsxs(Link, { ref: ref, color: "neutral", size: "sm", onClick: onClick, className: cn("mb-2 w-fit", className), ...props, children: [jsx(ArrowLeftIcon, { className: "size-4" }), typeof label === 'string'
+                ? jsx("span", { children: label })
+                : label] }));
 });
 PageHeadingBackButton.displayName = "PageHeadingBackButton";
 

package/dist/components/core/Pagination/Pagination.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useMemo, useCallback } from 'react';
 import { paginationTheme } from './Pagination.theme.js';
@@ -77,14 +78,19 @@ const Pagination = React__default.forwardRef(({ currentPage, totalPages, onPageC
     }
     const isFirstPage = currentPage === 1;
     const isLastPage = currentPage === totalPages;
-    return (jsxs("nav", { ref: ref, role: "navigation", "aria-label": "Pagination Navigation", className: cn(theme.baseStyle, className), ...props, children: [showFirstLast && (jsxs(PaginationItem, { size: size, isDisabled: isFirstPage, onClick: () => handlePageChange(1), "aria-label": "Go to first page", children: [jsx(ChevronDoubleLeftIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "First" })] })), showPrevNext && (jsxs(PaginationItem, { size: size, isDisabled: isFirstPage, onClick: () => handlePageChange(currentPage - 1), "aria-label": `Go to previous page (${currentPage - 1})`, children: [jsx(ChevronLeftIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Previous" })] })), paginationRange.map((pageNumber, index) => {
+    // Clamp the page numbers used in Previous/Next aria-labels so a disabled
+    // button at a boundary never announces an out-of-range page (e.g. "(0)"
+    // on page 1, or "(totalPages + 1)" on the last page).
+    const previousPageLabelNumber = Math.max(currentPage - 1, 1);
+    const nextPageLabelNumber = Math.min(currentPage + 1, totalPages);
+    return (jsxs("nav", { ref: ref, role: "navigation", "aria-label": "Pagination Navigation", className: cn(theme.baseStyle, className), ...props, children: [showFirstLast && (jsxs(PaginationItem, { size: size, isDisabled: isFirstPage, onClick: () => handlePageChange(1), "aria-label": "Go to first page", children: [jsx(ChevronDoubleLeftIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "First" })] })), showPrevNext && (jsxs(PaginationItem, { size: size, isDisabled: isFirstPage, onClick: () => handlePageChange(currentPage - 1), "aria-label": `Go to previous page (${previousPageLabelNumber})`, children: [jsx(ChevronLeftIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Previous" })] })), paginationRange.map((pageNumber, index) => {
                 if (pageNumber === "...") {
-                    return (jsxs(PaginationItem, { size: size, variant: "ellipsis", isDisabled: true, "aria-label": "More pages", role: "separator", children: [jsx("span", { "aria-hidden": "true", children: "\u2026" }), jsx("span", { className: "sr-only", children: "More pages" })] }, `ellipsis-${index}`));
+                    return (jsx("span", { role: "separator", "aria-hidden": "true", children: "\u2026" }, `ellipsis-${index}`));
                 }
                 const page = pageNumber;
                 const isActive = page === currentPage;
                 return (jsxs(PaginationItem, { size: size, variant: "page", isActive: isActive, onClick: () => handlePageChange(page), "aria-label": isActive ? `Page ${page}, current page` : `Go to page ${page}`, children: [page, isActive && jsx("span", { className: "sr-only", children: "(current)" })] }, page));
-            }), showPrevNext && (jsxs(PaginationItem, { size: size, isDisabled: isLastPage, onClick: () => handlePageChange(currentPage + 1), "aria-label": `Go to next page (${currentPage + 1})`, children: [jsx(ChevronRightIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Next" })] })), showFirstLast && (jsxs(PaginationItem, { size: size, isDisabled: isLastPage, onClick: () => handlePageChange(totalPages), "aria-label": "Go to last page", children: [jsx(ChevronDoubleRightIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Last" })] }))] }));
+            }), showPrevNext && (jsxs(PaginationItem, { size: size, isDisabled: isLastPage, onClick: () => handlePageChange(currentPage + 1), "aria-label": `Go to next page (${nextPageLabelNumber})`, children: [jsx(ChevronRightIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Next" })] })), showFirstLast && (jsxs(PaginationItem, { size: size, isDisabled: isLastPage, onClick: () => handlePageChange(totalPages), "aria-label": "Go to last page", children: [jsx(ChevronDoubleRightIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Last" })] }))] }));
 });
 Pagination.displayName = "Pagination";
 

package/dist/components/core/Pagination/Pagination.theme.d.ts

@@ -1,13 +1,5 @@
-import { PaginationSize } from "./Pagination.types";
-/**
- * Simplified theme structure for the Pagination component with unified item styling
- */
-export interface PaginationTheme {
-    baseStyle: string;
-    itemStyle: string;
-    itemSizes: Record<PaginationSize, string>;
-    ellipsisStyle: string;
-}
+import { PaginationTheme } from "./Pagination.types";
+export type { PaginationTheme } from "./Pagination.types";
 /**
  * Default theme for the Pagination component using modern neutral colors
  */

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

@@ -13,15 +13,15 @@ const paginationTheme = {
         // Base state - light
         "cursor-pointer bg-white border border-transparent text-[var(--color-text-muted)] " +
         // Base state - dark
-        "dark:bg-[var(--color-neutral-800)] dark:text-[var(--color-neutral-400)] dark:border-transparent " +
+        "dark:bg-transparent dark:text-[var(--color-text-secondary)] dark:border-transparent " +
         // Hover state - light
-        "hover:text-[var(--color-text-primary)] hover:bg-neutral-50 hover:border-[var(--color-border)] " +
+        "hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] hover:border-[var(--color-border)] " +
         // Hover state - dark
-        "dark:hover:bg-[var(--color-neutral-700)] dark:hover:text-[var(--color-neutral-200)] dark:hover:border-[var(--color-neutral-600)] " +
+        "dark:hover:bg-[var(--color-surface-hover)] dark:hover:text-[var(--color-text-primary)] dark:hover:border-[var(--color-border)]/0 " +
         // Active state - light
         "data-[active=true]:bg-white data-[active=true]:border-[var(--color-border)] data-[active=true]:text-[var(--color-text-primary)] " +
         // Active state - dark (uses primary color accent)
-        "dark:data-[active=true]:bg-[var(--color-primary-900)] dark:data-[active=true]:border-[var(--color-primary-700)] dark:data-[active=true]:text-[var(--color-primary-300)] " +
+        "dark:data-[active=true]:bg-[var(--color-neutral-800)] dark:data-[active=true]:border-none dark:data-[active=true]:text-[var(--color-text-primary)] " +
         // Disabled state
         "data-[disabled=true]:opacity-50 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:pointer-events-none",
     // Unified item sizes

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

@@ -1,5 +1,4 @@
 import React from "react";
-import { PaginationTheme } from "./Pagination.theme";
 /**
  * Pagination component props
  * @property {number} currentPage - The current active page number (1-based)
@@ -31,6 +30,17 @@ export interface PaginationProps extends React.HTMLAttributes<HTMLDivElement> {
     theme?: Partial<PaginationTheme>;
 }
 export type PaginationSize = "sm" | "md";
+/**
+ * Simplified theme structure for the Pagination component with unified item styling
+ * (declared here, not in Pagination.theme.ts, so types→theme imports never
+ * happen — keeps the theme/types import graph one-directional)
+ */
+export interface PaginationTheme {
+    baseStyle: string;
+    itemStyle: string;
+    itemSizes: Record<PaginationSize, string>;
+    ellipsisStyle: string;
+}
 /**
  * Internal pagination item props
  */

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

@@ -1,19 +1,10 @@
-/**
- * Animation variants for Pill component
- *
- * Reuses Badge's proven animation patterns with spring physics
- * for natural, responsive interactions.
- */
-/**
- * Main pill animation variants
- * Uses spring physics for smooth, natural motion
- */
+"use client";
 /**
  * Tap/click animation variant
  * Subtle scale down on press for tactile feedback
  */
 const pillTapVariant = {
-    scale: 0.98,
+    scale: 0.975,
     transition: {
         duration: 0.1,
         type: 'spring',

package/dist/components/core/Pill/Pill.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useState, useEffect, useCallback } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
@@ -40,9 +41,17 @@ import { cn } from '../../../utils/cn.js';
  * </Pill>
  * ```
  */
-const Pill = React__default.forwardRef(({ children, size = "md", iconStart, selected = false, onSelect, readOnly = false, className, theme = {}, onClick, ...props }, ref) => {
-    // ========== State Management ==========
+const Pill = React__default.forwardRef((props, ref) => {
     var _a, _b;
+    const { children, size = "md", iconStart, selected = false, onSelect, readOnly = false, className, theme = {}, onClick, ...restProps } = props;
+    // Detect whether the consumer *explicitly* passed `selected` (even
+    // `selected={undefined}` counts as not-passed) — checking the raw props
+    // object, BEFORE the `selected = false` default above is applied, so a
+    // plain `<Pill>` with no `selected` prop at all never trips the
+    // dev-warning below just because the destructured default made it look
+    // "set".
+    const hasExplicitSelected = "selected" in props && props.selected !== undefined;
+    // ========== State Management ==========
     const [isSelected, setIsSelected] = useState(selected);
     useEffect(() => {
         setIsSelected(selected);
@@ -55,12 +64,12 @@ const Pill = React__default.forwardRef(({ children, size = "md", iconStart, sele
     // ========== Development Warnings ==========
     useEffect(() => {
         if (process.env.NODE_ENV !== "production") {
-            if (selected !== undefined && !onSelect) {
+            if (hasExplicitSelected && !onSelect) {
                 // eslint-disable-next-line no-console
                 console.warn('[Pill] Component has "selected" prop but missing "onSelect" handler. The pill will not be interactive.');
             }
         }
-    }, [selected, onSelect]);
+    }, [hasExplicitSelected, onSelect]);
     // ========== Event Handlers ==========
     const handleClick = useCallback((e) => {
         if (readOnly) {
@@ -111,7 +120,7 @@ const Pill = React__default.forwardRef(({ children, size = "md", iconStart, sele
         // Accessibility
         role: isSelectable && !readOnly ? "button" : undefined, tabIndex: isInteractive ? 0 : undefined, "aria-pressed": isSelectable && !readOnly ? isSelected : undefined, "aria-readonly": readOnly || undefined, 
         // Animation
-        whileTap: isInteractive && !shouldReduceMotion ? pillTapVariant : undefined, ...props, children: [renderStartIcon(), children] }));
+        whileTap: isInteractive && !shouldReduceMotion ? pillTapVariant : undefined, ...restProps, children: [renderStartIcon(), children] }));
 });
 Pill.displayName = "Pill";
 

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

@@ -9,26 +9,26 @@ const pillTheme = {
      * Base pill style - structure and default colors (no hover)
      */
     baseStyle: "inline-flex items-center justify-center font-medium rounded-full select-none whitespace-nowrap " +
-        "ring-1 bg-white transition-all duration-300 " +
+        "ring-1 bg-[var(--color-surface)] transition-all duration-300 " +
         "text-[var(--color-text-primary)] ring-[var(--color-border)] " +
-        "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] " +
-        "dark:bg-[var(--color-background-secondary)]",
+        "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)]",
     /**
-     * Hover state - applied only when interactive and NOT selected
+     * Hover state - applied only when interactive and NOT selected.
+     * Uses the single shared interaction tint + interaction edge (both mode-aware,
+     * darken-in-light / lighten-in-dark) — no bespoke per-step neutral colors. See CLAUDE §3.
      */
-    hoverStyle: "hover:bg-[var(--color-neutral-100)] hover:ring-[var(--color-neutral-300)] " +
-        "dark:hover:bg-[var(--color-neutral-800)] dark:hover:ring-[var(--color-neutral-500)]",
+    hoverStyle: "hover:bg-[var(--color-surface-hover)] hover:ring-[var(--color-border-hover)]",
     /**
      * Selected state - applied when selected
      */
-    selectedStyle: "bg-[var(--color-primary)]/5 ring-[var(--color-primary)] text-[var(--color-primary)] " +
-        "dark:bg-[var(--color-primary)]/20 dark:text-[var(--color-primary-300)] ",
+    selectedStyle: "bg-[var(--color-primary)]/5 ring-[var(--color-primary)]/20 text-[var(--color-primary)] " +
+        "dark:bg-[var(--color-primary)]/10  ",
     /**
      * Size variants
      */
     sizes: {
-        sm: "text-xs px-2 py-0.5 gap-0.5",
-        md: "text-sm px-2.5 py-1 gap-1",
+        sm: "text-xs px-2.5 py-0.5 gap-0.5",
+        md: "text-sm px-2.5 py-0.5 gap-1",
         lg: "text-sm px-3 py-1 gap-1.5",
     },
     /**

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

@@ -1,6 +1,6 @@
 import React from "react";
 import { PopoverRootProps as PopoverProps } from "./Popover.types";
 export declare const Popover: (({ children, className, isOpen: controlledIsOpen, defaultIsOpen, onOpenChange, placement, offset, triggerType, closeOnClickOutside, closeOnEsc, preventClose, hasBackdrop, theme: themeOverrides, darkMode, ...props }: PopoverProps) => import("react/jsx-runtime").JSX.Element) & {
-    Trigger: React.ForwardRefExoticComponent<Omit<import("./Popover.types").PopoverTriggerProps, "ref"> & React.RefAttributes<any>>;
-    Content: React.ForwardRefExoticComponent<import("./Popover.types").PopoverContentProps & React.RefAttributes<HTMLDivElement>>;
+    Trigger: React.ForwardRefExoticComponent<Omit<import("./Popover.types").PopoverTriggerProps, "ref"> & React.RefAttributes<HTMLElement>>;
+    Body: React.ForwardRefExoticComponent<import("./Popover.types").PopoverBodyProps & React.RefAttributes<HTMLDivElement>>;
 };

package/dist/components/core/Popover/Popover.js

@@ -1,9 +1,10 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import { useId, useState, useRef, useCallback } from 'react';
+import { useId, useState, useRef, useCallback, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { PopoverContext } from './PopoverContext.js';
 import { PopoverTrigger } from './PopoverTrigger.js';
-import { PopoverContent } from './PopoverContent.js';
+import { PopoverBody } from './PopoverBody.js';
 import { popoverTheme } from './Popover.theme.js';
 
 /**
@@ -16,9 +17,9 @@ import { popoverTheme } from './Popover.theme.js';
  *   <Popover.Trigger>
  *     <Button>Open Popover</Button>
  *   </Popover.Trigger>
- *   <Popover.Content>
+ *   <Popover.Body>
  *     <div>Popover content</div>
- *   </Popover.Content>
+ *   </Popover.Body>
  * </Popover>
  * ```
  */
@@ -41,12 +42,12 @@ const PopoverRoot = ({ children, className, isOpen: controlledIsOpen, defaultIsO
         onOpenChange === null || onOpenChange === void 0 ? void 0 : onOpenChange(value);
     }, [isControlled, onOpenChange]);
     // Merge theme with overrides
-    const theme = {
+    const theme = useMemo(() => ({
         ...popoverTheme,
         ...(themeOverrides || {}),
-    };
+    }), [themeOverrides]);
     // Context value
-    const contextValue = {
+    const contextValue = useMemo(() => ({
         isOpen,
         onOpenChange: handleOpenChange,
         triggerRef,
@@ -60,13 +61,13 @@ const PopoverRoot = ({ children, className, isOpen: controlledIsOpen, defaultIsO
         hasBackdrop,
         theme,
         contentId,
-    };
-    return (jsx(PopoverContext.Provider, { value: contextValue, children: jsx("div", { className: cn("popover", darkMode && "dark", className), "data-state": isOpen ? "open" : "closed", "data-backdrop": hasBackdrop ? "true" : "false", ...props, children: children }) }));
+    }), [isOpen, handleOpenChange, triggerRef, contentRef, placement, offset, triggerType, closeOnClickOutside, closeOnEsc, preventClose, hasBackdrop, theme, contentId]);
+    return (jsx(PopoverContext.Provider, { value: contextValue, children: jsx("div", { className: cn("popover contents", darkMode && "dark", className), "data-state": isOpen ? "open" : "closed", "data-backdrop": hasBackdrop ? "true" : "false", ...props, children: children }) }));
 };
 // Export as a unified component
 const Popover = Object.assign(PopoverRoot, {
     Trigger: PopoverTrigger,
-    Content: PopoverContent,
+    Body: PopoverBody,
 });
 
 export { Popover };

package/dist/components/core/Popover/Popover.theme.d.ts

@@ -3,7 +3,7 @@
  */
 export interface PopoverTheme {
     baseStyle: string;
-    contentStyle: string;
+    bodyStyle: string;
 }
 /**
  * Default theme for the Popover component

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

@@ -4,8 +4,10 @@
 const popoverTheme = {
     // Base styles for the popover
     baseStyle: "z-50 outline-none",
-    // Content styles
-    contentStyle: "bg-[var(--color-surface)] border border-[var(--color-border)] rounded-[var(--popover-radius)] shadow-real-xl p-4 max-w-[min(24rem,calc(100vw-2rem))] dark:bg-[var(--color-background-secondary)] ",
+    // Body styles. bg + shadow come from the relative-elevation engine
+    // (surfaceClasses) at runtime so a nested popover lifts above its host; keep
+    // the frosted blur + border + radius + padding here.
+    bodyStyle: "backdrop-blur-md border border-[var(--color-border)] rounded-[var(--popover-radius)] p-4 max-w-[min(24rem,calc(100vw-2rem))]",
 };
 
 export { popoverTheme };

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

@@ -1,5 +1,6 @@
 import React, { ReactNode } from "react";
 import { PopoverTheme } from "./Popover.theme";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export type PopoverPlacement = "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end";
 export type PopoverTriggerType = "click" | "hover";
 export interface PopoverContextValue {
@@ -44,10 +45,27 @@ export interface PopoverTriggerProps {
     className?: string;
     [key: string]: unknown;
 }
-export interface PopoverContentProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface PopoverBodyProps extends React.HTMLAttributes<HTMLDivElement> {
     children: ReactNode;
     animation?: boolean;
     portal?: boolean;
+    /** Cap the body to the viewport-available height (space below/above the
+     *  trigger, computed by the positioning hook; falls back to 400px) and add
+     *  `overflow-y-auto`, so tall content scrolls inside the popover instead of
+     *  extending past the viewport unreachably. `max-height` + `auto` means short
+     *  popovers show no scrollbar. Set `false` to opt out (uncapped, may overflow).
+     *  @default true */
+    scrollable?: boolean;
+    /** Custom max-height when scrollable is true (e.g. "300px", "20rem").
+     *  Overrides the default viewport-aware height. */
+    maxHeight?: 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 popover's base rung. */
+    lift?: boolean;
 }
 /**
  * Theme overrides for the Popover component
@@ -55,6 +73,6 @@ export interface PopoverContentProps extends React.HTMLAttributes<HTMLDivElement
 export interface PopoverThemeOverrides {
     /** Base style for the popover */
     baseStyle?: string;
-    /** Content style for the popover */
-    contentStyle?: string;
+    /** Body style for the popover */
+    bodyStyle?: string;
 }

package/dist/components/core/Popover/PopoverBody.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+import { PopoverBodyProps } from "./Popover.types";
+/**
+ * PopoverBody component displays the body/content of the popover
+ */
+declare const PopoverBody: React.ForwardRefExoticComponent<PopoverBodyProps & React.RefAttributes<HTMLDivElement>>;
+export { PopoverBody };

package/dist/components/core/Popover/PopoverBody.js

@@ -0,0 +1,134 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import React__default, { useRef, useEffect, useCallback } from 'react';
+import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
+import { createPortal } from 'react-dom';
+import { cn } from '../../../utils/cn.js';
+import { usePopoverContext } from './PopoverContext.js';
+import { useClickOutside } from '../../../hooks/useClickOutside.js';
+import '../../../theme/ThemeContext.js';
+import { useSurfaceElevation, surfaceClasses, SurfaceProvider } from '../../../theme/SurfaceContext.js';
+import { getOverlayMenuVariants, overlayBackdropAnimations } from '../../../theme/animations.js';
+import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
+import { Overlay } from '../../effects/Overlay/Overlay.js';
+import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useDarkMode } from '../../../hooks/useDarkMode.js';
+
+/**
+ * PopoverBody component displays the body/content of the popover
+ */
+const PopoverBody = React__default.forwardRef(({ children, className, animation = true, portal = true, scrollable = true, maxHeight, 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, triggerRef, contentRef, placement, offset, triggerType, closeOnClickOutside, closeOnEsc, preventClose, hasBackdrop, theme, contentId, } = usePopoverContext();
+    const shouldReduceMotion = useReducedMotion();
+    const localRef = useRef(null);
+    // Use the same positioning hook as Select/Tooltip (now supports all 12 placements)
+    const { position, cssVariables, contentRef: portalContentRef, isReady, actualPlacement, } = useSelectPortal({
+        triggerRef,
+        isOpen: isOpen || false,
+        placement,
+        offset: offset || 8,
+        autoWidth: true,
+        onClose: () => {
+            if (!preventClose)
+                onOpenChange(false);
+        },
+        stickyTracking: true,
+    });
+    // Click outside detection (active when no backdrop — with backdrop, Overlay handles it)
+    useClickOutside(localRef, (e) => {
+        var _a, _b, _c;
+        if (hasBackdrop)
+            return; // Overlay handles click-outside via backdrop
+        if (e.target === triggerRef.current ||
+            ((_a = triggerRef.current) === null || _a === void 0 ? void 0 : _a.contains(e.target))) {
+            return;
+        }
+        // Ignore clicks that land inside any FlikkUI overlay portal (a nested
+        // Select/Tooltip/Dropdown/Popover renders to document.body, outside our
+        // content ref — without this it would count as an outside click and
+        // dismiss the popover). See the `data-flikkui-portal` convention.
+        if ((_c = (_b = e.target) === null || _b === void 0 ? void 0 : _b.closest) === null || _c === void 0 ? void 0 : _c.call(_b, "[data-flikkui-portal]")) {
+            return;
+        }
+        if (closeOnClickOutside && !preventClose) {
+            onOpenChange(false);
+        }
+    });
+    // Escape key handling (active when no backdrop — with backdrop, Overlay handles it)
+    useEffect(() => {
+        if (hasBackdrop)
+            return; // Overlay handles escape key
+        const handleKeyDown = (e) => {
+            if (closeOnEsc && e.key === "Escape" && !preventClose) {
+                onOpenChange(false);
+            }
+        };
+        document.addEventListener("keydown", handleKeyDown);
+        return () => {
+            document.removeEventListener("keydown", handleKeyDown);
+        };
+    }, [hasBackdrop, closeOnEsc, onOpenChange, preventClose]);
+    // Combine refs
+    const handleRef = useCallback((el) => {
+        localRef.current = el;
+        if (typeof ref === "function") {
+            ref(el);
+        }
+        else if (ref) {
+            ref.current = el;
+        }
+        if (contentRef) {
+            contentRef.current = el;
+        }
+        if (portalContentRef &&
+            typeof portalContentRef === "object" &&
+            "current" in portalContentRef) {
+            portalContentRef.current =
+                el;
+        }
+    }, [ref, contentRef, portalContentRef]);
+    const isDarkMode = useDarkMode();
+    const isClient = useIsClient();
+    // Extract DOM props to avoid type conflicts with Framer Motion
+    const { onDrag, onDragStart, onDragEnd, onAnimationStart, onAnimationEnd, ...domProps } = props;
+    const side = (actualPlacement || placement || "bottom").split("-")[0];
+    const transformOrigin = side === "top" ? "bottom" : side === "left" ? "right" : side === "right" ? "left" : "top";
+    const contentClasses = cn(surfaceClasses(surfaceLevel, { translucent: true }), theme.baseStyle, theme.bodyStyle, "popover-content", scrollable && "overflow-y-auto", className);
+    const contentPositionStyle = {
+        ...cssVariables,
+        position: "fixed",
+        top: `${position.top}px`,
+        left: `${position.left}px`,
+        transformOrigin,
+        ...(scrollable && {
+            maxHeight: maxHeight || "var(--select-content-available-height, 400px)",
+        }),
+    };
+    const popoverVariants = getOverlayMenuVariants(side, {
+        scale: 0.97,
+        shift: 6,
+    });
+    // When hasBackdrop is true, delegate backdrop + escape + click-outside to Overlay
+    if (hasBackdrop) {
+        return (jsx(Overlay, { ref: handleRef, isOpen: isOpen, onClose: () => {
+                if (!preventClose)
+                    onOpenChange(false);
+            }, closeOnOverlayClick: closeOnClickOutside && !preventClose, closeOnEsc: closeOnEsc && !preventClose, enableScrollLock: false, enableFocusTrap: true, position: "none", role: "dialog", ariaModal: true, contentClassName: contentClasses, contentStyle: contentPositionStyle, animations: animation && !shouldReduceMotion && isReady
+                ? {
+                    overlay: overlayBackdropAnimations,
+                    content: popoverVariants,
+                }
+                : undefined, children: jsx("div", { id: contentId, "data-state": isOpen ? "open" : "closed", "data-placement": placement, "data-trigger": triggerType, ...domProps, children: jsx(SurfaceProvider, { level: surfaceLevel, children: children }) }) }));
+    }
+    // Without backdrop: manual portal + positioning + escape + click-outside
+    const popoverContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, id: contentId, className: cn("fixed z-50", contentClasses), style: contentPositionStyle, variants: shouldReduceMotion || !animation ? {} : popoverVariants, initial: shouldReduceMotion || !animation ? undefined : "hidden", animate: shouldReduceMotion || !animation ? undefined : (isReady ? "visible" : "hidden"), exit: shouldReduceMotion || !animation ? undefined : "exit", transition: shouldReduceMotion || !animation ? { duration: 0 } : undefined, "data-state": isOpen ? "open" : "closed", "data-placement": placement, "data-trigger": triggerType, onClick: (e) => e.stopPropagation(), ...domProps, children: jsx(SurfaceProvider, { level: surfaceLevel, children: children }) })) }));
+    if (portal && isClient) {
+        return createPortal(jsx("div", { "data-flikkui-portal": "", className: isDarkMode ? "dark" : undefined, children: popoverContent }), document.body);
+    }
+    return popoverContent;
+});
+PopoverBody.displayName = "Popover.Body";
+
+export { PopoverBody };

package/dist/components/core/Popover/PopoverContext.js

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

package/dist/components/core/Popover/PopoverTrigger.d.ts

@@ -1,3 +1,3 @@
 import React from "react";
 import { PopoverTriggerProps } from "./Popover.types";
-export declare const PopoverTrigger: React.ForwardRefExoticComponent<Omit<PopoverTriggerProps, "ref"> & React.RefAttributes<any>>;
+export declare const PopoverTrigger: React.ForwardRefExoticComponent<Omit<PopoverTriggerProps, "ref"> & React.RefAttributes<HTMLElement>>;