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

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

@@ -1,9 +1,7 @@
-import React from "react";
-import { ModalProps, ModalContextValue } from "./Modal.types";
-export declare const ModalContext: React.Context<ModalContextValue | undefined>;
-export declare const useModalContext: () => ModalContextValue;
+import { ModalProps } from "./Modal.types";
+export { ModalContext, useModalContext } from "./ModalContext";
 export declare const Modal: {
-    ({ isOpen, onClose, size, closeOnOverlayClick, closeOnEsc, showCloseButton, role, children, className, theme: themeOverrides, ...props }: ModalProps): import("react/jsx-runtime").JSX.Element;
+    ({ isOpen, onClose, size, closeOnOverlayClick, closeOnEsc, showCloseButton, role, children, className, theme: themeOverrides, elevation, lift, ...props }: ModalProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 } & {
     Header: {

package/dist/components/core/Modal/Modal.js

@@ -1,24 +1,24 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import { createContext, useId, useState, useEffect, useMemo, useContext } from 'react';
+import { useId, useState, useEffect, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { Overlay } from '../../effects/Overlay/Overlay.js';
 import { modalTheme, modalSizeVariants } from './Modal.theme.js';
 import { modalContentAnimations, modalOverlayAnimations } from './Modal.animations.js';
+import { ModalContext } from './ModalContext.js';
+export { useModalContext } from './ModalContext.js';
 import { ModalHeader } from './ModalHeader.js';
 import { ModalTitle } from './ModalTitle.js';
 import { ModalSubtitle } from './ModalSubtitle.js';
 import { ModalBody } from './ModalBody.js';
 import { ModalFooter } from './ModalFooter.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
-// Create context for Modal components
-const ModalContext = createContext(undefined);
-const useModalContext = () => {
-    const ctx = useContext(ModalContext);
-    if (!ctx)
-        throw new Error("Modal compound components must be used within <Modal>");
-    return ctx;
-};
-const ModalRoot = ({ isOpen, onClose, size = "md", closeOnOverlayClick = true, closeOnEsc = true, showCloseButton = true, role = "dialog", children, className, theme: themeOverrides, ...props }) => {
+const ModalRoot = ({ isOpen, onClose, size = "md", closeOnOverlayClick = true, closeOnEsc = true, showCloseButton = true, role = "dialog", children, className, theme: themeOverrides, elevation, lift, ...props }) => {
+    // Grounded backdrop overlay: a Modal covers the viewport, so it paints a FIXED rung 4
+    // regardless of where its <Modal> JSX sits (a Modal declared inside a Card must not
+    // inherit the Card's rung). Content inside still lifts relative to the modal.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 4, ground: true, elevation, lift });
     // Generate unique IDs for ARIA linkage
     const id = useId();
     const titleId = `${id}-title`;
@@ -35,10 +35,10 @@ const ModalRoot = ({ isOpen, onClose, size = "md", closeOnOverlayClick = true, c
     const SIZE_TOKENS = ["sm", "md", "lg", "xl", "full"];
     const isSizeToken = SIZE_TOKENS.includes(size);
     // Merge theme with overrides
-    const theme = {
+    const theme = useMemo(() => ({
         ...modalTheme,
         ...(themeOverrides || {}),
-    };
+    }), [themeOverrides]);
     // Context value
     const contextValue = useMemo(() => ({
         isOpen,
@@ -54,10 +54,10 @@ const ModalRoot = ({ isOpen, onClose, size = "md", closeOnOverlayClick = true, c
         titleId,
         subtitleId,
     }), [isOpen, onClose, size, isSizeToken, closeOnOverlayClick, closeOnEsc, showCloseButton, theme, isBodyScrollable, setIsBodyScrollable, titleId, subtitleId]);
-    return (jsx(Overlay, { isOpen: isOpen, onClose: onClose, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, position: "center", role: role, ariaModal: true, ariaLabelledBy: titleId, ariaDescribedBy: subtitleId, contentClassName: cn(theme.container, isSizeToken ? modalSizeVariants[size] : size, className), animations: {
+    return (jsx(Overlay, { isOpen: isOpen, onClose: onClose, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, position: "center", role: role, ariaModal: true, ariaLabelledBy: titleId, ariaDescribedBy: subtitleId, contentClassName: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), theme.container, isSizeToken ? modalSizeVariants[size] : size, className), animations: {
             overlay: modalOverlayAnimations,
             content: modalContentAnimations,
-        }, ...props, children: jsx(ModalContext.Provider, { value: contextValue, children: children }) }));
+        }, ...props, children: jsx(ModalContext.Provider, { value: contextValue, children: jsx(SurfaceProvider, { level: surfaceLevel, children: children }) }) }));
 };
 ModalRoot.displayName = "Modal";
 // Attach compound subcomponents
@@ -69,4 +69,4 @@ const Modal = Object.assign(ModalRoot, {
     Footer: ModalFooter,
 });
 
-export { Modal, ModalContext, useModalContext };
+export { Modal, ModalContext };

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

@@ -1,20 +1,22 @@
 const modalTheme = {
     // Note: overlay styling is now handled by the shared Overlay component
     overlay: "",
-    container: "relative w-full max-h-[calc(100vh-2rem)] rounded-[var(--modal-radius)] shadow-2xl shadow-black/30 flex flex-col my-4 min-h-0 overflow-hidden bg-[var(--color-surface-raised)]/80 ring-6 !ring-white/10 border border-[var(--color-border)]",
+    // bg comes from the relative-elevation engine (surfaceClasses) at runtime so a modal
+    // lifts above its host substrate; keep the dramatic shadow + ring + border + radius here.
+    container: "relative w-full max-h-[calc(100vh-2rem)] rounded-[var(--modal-radius)] shadow-2xl shadow-black/30 flex flex-col my-4 min-h-0 overflow-hidden ring-6 !ring-white/10 border border-[var(--color-border)]",
     header: "flex items-start justify-between p-4 pb-0 shrink-0 border-b border-transparent gap-6 relative",
     headerContent: "flex flex-col items-start gap-2 flex-1",
     title: "text-base leading-6 font-semibold text-[var(--color-text-primary)]",
-    subtitle: "text-sm text-[var(--color-text-muted)] mt-0.5",
+    subtitle: "text-sm text-[var(--color-text-secondary)] mt-0.5",
     body: "flex-1 overflow-y-auto p-4 pb-3",
     footer: "flex items-center justify-end gap-2 p-3 py-2 border-t border-transparent",
 };
 // Size variants for the modal container
 const modalSizeVariants = {
     sm: "max-w-sm mx-4 sm:mx-0",
-    md: "max-w-md mx-4 sm:mx-0",
-    lg: "max-w-lg mx-4 sm:mx-0",
-    xl: "max-w-xl mx-4 sm:mx-0",
+    md: "max-w-lg mx-4 sm:mx-0",
+    lg: "max-w-2xl mx-4 sm:mx-0",
+    xl: "max-w-4xl mx-4 sm:mx-0",
     full: "max-w-full mx-4",
 };
 

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export type ModalSizeToken = "sm" | "md" | "lg" | "xl" | "full";
 /** Preset size token or any arbitrary Tailwind width class, e.g. `"w-80"`, `"w-[50vw]"` */
 export type ModalSize = ModalSizeToken | (string & {});
@@ -53,6 +54,13 @@ export interface ModalProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "
     children: React.ReactNode;
     className?: string;
     theme?: ModalThemeOverrides;
+    /**
+     * 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 modal's base rung. */
+    lift?: boolean;
     /**
      * Force dark mode styling for the component. Use when placing the component
      * on a dark background while the page is in light mode. This applies the

package/dist/components/core/Modal/ModalBody.js

@@ -1,7 +1,8 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { useRef, useCallback, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';
-import { useModalContext } from './Modal.js';
+import { useModalContext } from './ModalContext.js';
 
 const ModalBody = ({ children, className, ...props }) => {
     const { theme, setIsBodyScrollable } = useModalContext();

package/dist/components/core/Modal/ModalContext.d.ts

@@ -0,0 +1,3 @@
+import { ModalContextValue } from "./Modal.types";
+export declare const ModalContext: import("react").Context<ModalContextValue | undefined>;
+export declare const useModalContext: () => ModalContextValue;

package/dist/components/core/Modal/ModalContext.js

@@ -0,0 +1,16 @@
+"use client";
+import { createContext, useContext } from 'react';
+
+// Lives in its own module (not Modal.tsx) so sub-components — and external
+// providers like ModalStack/AlertDialog — can consume the context without
+// importing Modal.tsx, which imports the sub-components back (circular dep).
+// Modal.tsx re-exports both names, so `from "../Modal/Modal"` keeps working.
+const ModalContext = createContext(undefined);
+const useModalContext = () => {
+    const ctx = useContext(ModalContext);
+    if (!ctx)
+        throw new Error("Modal compound components must be used within <Modal>");
+    return ctx;
+};
+
+export { ModalContext, useModalContext };

package/dist/components/core/Modal/ModalFooter.js

@@ -1,10 +1,11 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useModalContext } from './Modal.js';
+import { useModalContext } from './ModalContext.js';
 
 const ModalFooter = ({ children, className, ...props }) => {
     const { theme, isBodyScrollable } = useModalContext();
-    return (jsx("div", { className: cn(theme.footer, isBodyScrollable && "border-border", className), ...props, children: children }));
+    return (jsx("div", { className: cn(theme.footer, isBodyScrollable && "border-[var(--color-border)]", className), ...props, children: children }));
 };
 ModalFooter.displayName = "Modal.Footer";
 

package/dist/components/core/Modal/ModalHeader.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useModalContext } from './Modal.js';
+import { useModalContext } from './ModalContext.js';
 import { Button } from '../Button/Button.js';
 import 'react';
 import { XMarkIcon } from '@heroicons/react/24/outline';
@@ -8,7 +9,7 @@ import { XMarkIcon } from '@heroicons/react/24/outline';
 const ModalHeader = ({ children, icon, showCloseButton, className, ...props }) => {
     const { onClose, showCloseButton: contextShowCloseButton, theme, isBodyScrollable, } = useModalContext();
     const shouldShowCloseButton = showCloseButton !== null && showCloseButton !== void 0 ? showCloseButton : contextShowCloseButton;
-    return (jsxs("div", { className: cn(theme.header, isBodyScrollable && "border-[var(--color-border)] relative", className), ...props, children: [jsxs("div", { className: cn(theme.headerContent), children: [icon && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-secondary)]", children: icon })), jsx("div", { className: "flex-1", children: children })] }), shouldShowCloseButton && (jsx("div", { className: "", children: jsx(Button, { color: "neutral", variant: "soft", iconOnly: true, size: "sm", onClick: onClose, "aria-label": "Close modal", className: "rounded-full", children: jsx(XMarkIcon, { className: "size-5" }) }) }))] }));
+    return (jsxs("div", { className: cn(theme.header, isBodyScrollable && "border-[var(--color-border)] relative", className), ...props, children: [jsxs("div", { className: cn(theme.headerContent), children: [icon && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-secondary)]", children: icon })), jsx("div", { className: "flex-1", children: children })] }), shouldShowCloseButton && (jsx("div", { className: "", children: jsx(Button, { color: "neutral", variant: "outline", iconOnly: true, size: "sm", onClick: onClose, "aria-label": "Close modal", className: "rounded-full shrink-0", children: jsx(XMarkIcon, { className: "size-4" }) }) }))] }));
 };
 ModalHeader.displayName = "Modal.Header";
 

package/dist/components/core/Modal/ModalSubtitle.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useModalContext } from './Modal.js';
+import { useModalContext } from './ModalContext.js';
 
 const ModalSubtitle = ({ children, className, ...props }) => {
     const { theme, subtitleId } = useModalContext();

package/dist/components/core/Modal/ModalTitle.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useModalContext } from './Modal.js';
+import { useModalContext } from './ModalContext.js';
 
 const ModalTitle = ({ children, className, as: Tag = 'h2', ...props }) => {
     const { theme, titleId } = useModalContext();

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

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Back modal — iOS-style scale-down when the front modal opens.
  */

package/dist/components/core/ModalStack/ModalStack.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { Children, isValidElement, useCallback, cloneElement } from 'react';
 import { motion, AnimatePresence } from 'motion/react';
@@ -39,7 +40,7 @@ const ModalStackRoot = ({ isOpen, onClose, closeOnOverlayClick = true, closeOnEs
             onClose();
         }
     }, [isFrontOpen, frontOnClose, onClose]);
-    return (jsx(Overlay, { isOpen: isOpen, onClose: handleClose, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, position: "center", role: "dialog", ariaModal: true, animations: {
+    return (jsx(Overlay, { isOpen: isOpen, onClose: handleClose, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, position: "center", animations: {
             overlay: modalOverlayAnimations,
             content: MODAL_STACK_CONTENT_ANIMATION,
         }, contentClassName: className, children: jsxs("div", { className: "relative flex items-center justify-center w-full", children: [backModal && (jsx(motion.div, { className: "w-full flex items-center justify-center", variants: backModalAnimations, initial: "initial", animate: isFrontOpen ? "stacked" : "idle", exit: "exit", style: { originY: 0 }, children: cloneElement(backModal, {

package/dist/components/core/ModalStack/ModalStackModal.js

@@ -1,18 +1,21 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { useId, useState, useEffect } from 'react';
+import { useId, useState, useMemo, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';
-import { ModalContext } from '../Modal/Modal.js';
+import '../Modal/Modal.js';
 import { modalTheme, modalSizeVariants } from '../Modal/Modal.theme.js';
+import { SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 import { ArrowLeftIcon } from '@heroicons/react/24/outline';
 import { modalStackTheme } from './ModalStack.theme.js';
-import { Button } from '../Button/Button.js';
+import { Link } from '../Link/Link.js';
+import { ModalContext } from '../Modal/ModalContext.js';
 
 const ModalStackModal = ({ size = "md", showCloseButton = true, showBackButton = false, onClose, onBack, children, className, theme: themeOverrides, _stackOnClose, _isBackModal, }) => {
     const id = useId();
     const titleId = `${id}-title`;
     const subtitleId = `${id}-subtitle`;
     const [isBodyScrollable, setIsBodyScrollable] = useState(false);
-    const closeHandler = onClose || _stackOnClose || (() => { });
+    const closeHandler = useMemo(() => onClose || _stackOnClose || (() => { }), [onClose, _stackOnClose]);
     const backHandler = onBack || onClose || (() => { });
     // Reset scroll state when modal becomes hidden (back modal pushed back)
     useEffect(() => {
@@ -21,15 +24,20 @@ const ModalStackModal = ({ size = "md", showCloseButton = true, showBackButton =
         }
     }, [_isBackModal]);
     // Merge theme with overrides
-    const theme = {
+    const theme = useMemo(() => ({
         ...modalTheme,
         ...(themeOverrides || {}),
-    };
-    const contextValue = {
+    }), [themeOverrides]);
+    // Grounded backdrop overlays: the modal surface bg now comes from the relative-elevation
+    // engine (modalTheme.container no longer carries a bg). The front modal sits one rung above
+    // the back modal so the stack reads as two distinct elevations; content inside lifts from there.
+    const surfaceLevel = _isBackModal ? 4 : 5;
+    const isSizeToken = ["sm", "md", "lg", "xl", "full"].includes(size);
+    const contextValue = useMemo(() => ({
         isOpen: true,
         onClose: closeHandler,
         size,
-        isSizeToken: ["sm", "md", "lg", "xl", "full"].includes(size),
+        isSizeToken,
         closeOnOverlayClick: true,
         closeOnEsc: true,
         showCloseButton,
@@ -38,8 +46,8 @@ const ModalStackModal = ({ size = "md", showCloseButton = true, showBackButton =
         setIsBodyScrollable,
         titleId,
         subtitleId,
-    };
-    return (jsx(ModalContext.Provider, { value: contextValue, children: jsxs("div", { className: cn(theme.container, modalSizeVariants[size], className), role: "dialog", "aria-modal": "true", "aria-labelledby": titleId, "aria-describedby": subtitleId, children: [showBackButton && (jsx("div", { className: cn(modalStackTheme.backButton), children: jsxs(Button, { onClick: backHandler, "aria-label": "Go back", variant: "link", size: "sm", children: [jsx(ArrowLeftIcon, { className: "size-4" }), "Back"] }) })), children] }) }));
+    }), [closeHandler, size, isSizeToken, showCloseButton, theme, isBodyScrollable, setIsBodyScrollable, titleId, subtitleId]);
+    return (jsx(ModalContext.Provider, { value: contextValue, children: jsx("div", { className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), theme.container, modalSizeVariants[size], className), role: "dialog", "aria-modal": "true", "aria-labelledby": titleId, "aria-describedby": subtitleId, children: jsxs(SurfaceProvider, { level: surfaceLevel, children: [showBackButton && (jsx("div", { className: cn(modalStackTheme.backButton), children: jsxs(Link, { onClick: backHandler, "aria-label": "Go back", size: "sm", children: [jsx(ArrowLeftIcon, { className: "size-4" }), "Back"] }) })), children] }) }) }));
 };
 ModalStackModal.displayName = "ModalStack.Modal";
 

package/dist/components/core/NavItem/NavItem.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import React__default, { useId, useRef, useState, useCallback, useEffect, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -199,6 +200,7 @@ const NavItem = React__default.forwardRef(({ children, startContent, endContent,
         className: cn("relative overflow-hidden", containerClasses),
         "aria-disabled": isDisabled || undefined,
         "aria-expanded": hasSubmenu ? isExpanded : undefined,
+        "aria-current": isActive ? "page" : undefined,
         "data-active": isActive,
         "data-disabled": isDisabled,
         "data-level": level,
@@ -269,8 +271,18 @@ const NavItem = React__default.forwardRef(({ children, startContent, endContent,
                                 mass: 0.7,
                             }, className: "ml-2", children: jsx(NavItem, { level: Math.min((level + 1), 2), startContent: item.startContent, active: item.active, isDisabled: item.isDisabled, notification: item.notification, href: item.href, onClick: item.onClick, className: "px-2.5", children: item.children }) })] }, idx))) }) })) })) : null;
     const renderContent = () => {
-        if (hasSubmenu && items && items.length > 0) {
-            return (jsxs(Dropdown, { isOpen: isCollapsedView ? isDropdownOpen : false, onOpenChange: isCollapsedView ? setIsDropdownOpen : undefined, placement: "right-start", offset: 8, selectionMode: "single", selectedKeys: activeKeys, children: [jsx("div", { onMouseEnter: isCollapsedView ? handleMouseEnter : undefined, onMouseLeave: isCollapsedView ? handleMouseLeave : undefined, className: "w-full", children: jsx(Dropdown.Trigger, { children: content }) }), isCollapsedView && (jsx(Dropdown.Menu, { onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: items.map((item, idx) => {
+        // The Dropdown wrapper only exists to power the collapsed-rail hover
+        // flyout (Dropdown.Menu below). In the expanded sidebar the
+        // self-contained submenu (the `submenu` node rendered alongside this
+        // content, further down) already owns the open/closed UI — wrapping
+        // `content` in `Dropdown.Trigger` there would gain nothing, and
+        // `Dropdown.Trigger` unconditionally clones its child with
+        // `"aria-expanded": isOpen` (DropdownTrigger.tsx), which would clobber
+        // the real `isExpanded`-derived `aria-expanded` already set on `content`
+        // via `interactionProps` with Dropdown's own hardcoded-false `isOpen`.
+        // So: only reach for Dropdown when actually in the collapsed view.
+        if (hasSubmenu && items && items.length > 0 && isCollapsedView) {
+            return (jsxs(Dropdown, { isOpen: isDropdownOpen, onOpenChange: setIsDropdownOpen, placement: "right-start", offset: 8, selectionMode: "single", selectedKeys: activeKeys, children: [jsx("div", { onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, className: "w-full", children: jsx(Dropdown.Trigger, { children: content }) }), jsx(Dropdown.Menu, { onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: items.map((item, idx) => {
                             const itemKey = `sub-item-${idx}`;
                             const subNotificationElement = (() => {
                                 if (item.notification === undefined || item.notification === false)
@@ -284,7 +296,7 @@ const NavItem = React__default.forwardRef(({ children, startContent, endContent,
                                 return null;
                             })();
                             return (jsx(Dropdown.Item, { itemKey: itemKey, startContent: item.startContent, endContent: subNotificationElement, isDisabled: item.isDisabled, onAction: () => handleItemAction(item), className: "hover:bg-[var(--color-surface-hover)] dark:hover:bg-[var(--color-surface-hover)]", children: item.children }, idx));
-                        }) }))] }));
+                        }) })] }));
         }
         return content;
     };

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

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useState, useEffect, useMemo } from 'react';
 import { SignalSlashIcon, CheckCircleIcon } from '@heroicons/react/24/solid';

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

@@ -12,7 +12,7 @@ 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",
+    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",

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,6 +1,6 @@
 const pageHeadingTheme = {
     baseStyle: "flex flex-col pb-6 mb-6",
-    headerStyle: "flex items-center gap-4",
+    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",

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;

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

@@ -1,11 +1,12 @@
+"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" }), typeof label === 'string'
+    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] }));
 });

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 (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.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,20 +9,20 @@ 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
      */