@flikk/ui 1.0.0-beta.25 → 1.0.0-beta.27

package/dist/components/core/MenuItem/MenuItem.js

@@ -9,12 +9,15 @@ import { menuItemTheme } from './MenuItem.theme.js';
  * Handles visual layout, base styling, keyboard activation, and focus tracking.
  * Context-specific behavior (selection, checked state) is handled by consumers.
  */
-const MenuItem = React__default.forwardRef(({ children, className, startContent, endContent, subtitle, shortcut, disabled = false, isDanger = false, onActivate, theme: themeOverrides, role = "menuitem", ...props }, ref) => {
+const MenuItem = React__default.forwardRef(({ children, className, startContent, endContent, subtitle, shortcut, disabled = false, isDanger = false, selected = false, onActivate, theme: themeOverrides, role = "menuitem", ...props }, ref) => {
     const [isFocused, setIsFocused] = useState(false);
     const theme = {
         ...menuItemTheme,
         ...themeOverrides,
     };
+    // Resolve state to plain utility classes (not data-[state] variants) so a
+    // consumer `className` always wins the cascade. See MenuItem.theme.ts.
+    const stateKey = disabled ? "disabled" : selected ? "selected" : "default";
     const handleClick = useCallback(() => {
         if (disabled)
             return;
@@ -26,7 +29,7 @@ const MenuItem = React__default.forwardRef(({ children, className, startContent,
             handleClick();
         }
     }, [handleClick]);
-    return (jsxs("div", { ref: ref, role: role, tabIndex: disabled ? undefined : -1, "aria-disabled": disabled, "data-focused": isFocused, "data-disabled": disabled, className: cn(theme.baseStyle, theme.focusStyle, isDanger && theme.dangerStyle, className), onClick: handleClick, onKeyDown: handleKeyDown, onFocus: () => setIsFocused(true), onBlur: () => setIsFocused(false), ...props, children: [startContent && (jsx("div", { className: "flex items-center justify-center flex-shrink-0", children: startContent })), jsxs("div", { className: "flex-1 min-w-0", children: [jsxs("div", { className: "flex items-center justify-between gap-2", children: [jsx("span", { className: "truncate", children: children }), shortcut && (jsx("span", { className: "ml-auto flex-shrink-0", children: shortcut }))] }), subtitle && (typeof subtitle === 'string'
+    return (jsxs("div", { ref: ref, role: role, tabIndex: disabled ? undefined : -1, "aria-disabled": disabled, "data-focused": isFocused, "data-disabled": disabled, "data-selected": selected, className: cn(theme.baseStyle, theme.states[stateKey], isFocused && !disabled && !selected && theme.focusedStyle, isDanger && theme.dangerStyle, theme.focusStyle, className), onClick: handleClick, onKeyDown: handleKeyDown, onFocus: () => setIsFocused(true), onBlur: () => setIsFocused(false), ...props, children: [startContent && (jsx("div", { className: "flex items-center justify-center flex-shrink-0", children: startContent })), jsxs("div", { className: "flex-1 min-w-0", children: [jsxs("div", { className: "flex items-center justify-between gap-2", children: [jsx("span", { className: "truncate", children: children }), shortcut && (jsx("span", { className: "ml-auto flex-shrink-0", children: shortcut }))] }), subtitle && (typeof subtitle === 'string'
                         ? jsx("div", { className: theme.subtitleStyle, children: subtitle })
                         : subtitle)] }), endContent && (jsx("div", { className: "flex items-center justify-center ml-2", children: endContent }))] }));
 });

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

@@ -1,5 +1,11 @@
 export interface MenuItemTheme {
     baseStyle: string;
+    states: {
+        default: string;
+        selected: string;
+        disabled: string;
+    };
+    focusedStyle: string;
     dangerStyle: string;
     focusStyle: string;
     subtitleStyle: string;

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

@@ -1,25 +1,28 @@
 const menuItemTheme = {
-    // Base item styling with hover, focus, and disabled states
-    baseStyle: "relative flex items-center gap-2 px-3 py-1.5 text-sm font-[500] text-[var(--color-text-primary)] cursor-pointer outline-none select-none rounded-[var(--radius-base)] transition-colors duration-300 " +
-        "hover:bg-[var(--color-background-secondary)] focus:bg-[var(--color-background-secondary)] " +
-        "data-[focused=true]:bg-[var(--color-background-secondary)] " +
-        "data-[selected=true]:bg-[var(--color-primary)]/5 data-[selected=true]:text-[var(--color-primary)] " +
-        "mb-px last-of-type:mb-0 " +
-        "data-[disabled=true]:opacity-60 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:pointer-events-none " +
-        // Dark mode
-        " " +
-        " " +
-        "dark:data-[focused=true]:bg-[var(--color-background-secondary)] " +
-        "dark:hover:bg-[var(--color-neutral-700)] " +
-        "dark:data-[selected=true]:bg-[var(--color-neutral-600)]/50 dark:data-[selected=true]:text-[var(--color-text-primary)]",
+    // Structural base only — layout, spacing, radius, transition. No state colors:
+    // those are resolved in JS (see `states`) so a consumer `className` always wins.
+    baseStyle: "relative flex items-center gap-2 px-3 py-1.5 text-sm font-[500] cursor-pointer outline-none select-none rounded-[var(--radius-base)] transition-colors duration-300 mb-px last-of-type:mb-0",
+    // State styling resolved in JS to plain utility classes so `className` overrides
+    // win (data-[state] variants carry attribute-selector specificity and can't be
+    // overridden by a plain className — see Button.theme.ts / NavItem.theme.ts for
+    // the same rationale). data-* attributes are still emitted as hooks for
+    // consumer CSS + tests, just not used for styling here.
+    states: {
+        default: "text-[var(--color-text-primary)] hover:bg-[var(--color-surface-hover)]",
+        selected: "bg-[var(--color-primary)]/5 text-[var(--color-primary)] " +
+            "dark:bg-white/10 dark:text-[var(--color-text-primary)]",
+        disabled: "opacity-60 cursor-not-allowed pointer-events-none",
+    },
+    // Keyboard-focus highlight (item received roving focus) — same fill as hover.
+    focusedStyle: "bg-[var(--color-surface-hover)]",
     // Danger item styling (e.g., Delete actions)
     dangerStyle: "text-[var(--color-danger)] hover:bg-[var(--color-danger)] hover:text-[var(--color-danger-contrast)] " +
         "dark:text-[var(--color-danger-400)] dark:hover:bg-[var(--color-danger-600)] dark:hover:text-[var(--color-danger-contrast)]",
     // Focus visible styling for keyboard navigation
-    focusStyle: "focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 " +
-        "dark:focus-visible:ring-[var(--color-primary-400)] dark:focus-visible:ring-offset-[var(--color-neutral-900)]",
+    focusStyle: "focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-background)] " +
+        "dark:focus-visible:ring-[var(--color-primary-400)]",
     // Description text below the label
-    subtitleStyle: "text-xs text-[var(--color-text-muted)] mt-0.5 truncate",
+    subtitleStyle: "text-sm text-[var(--color-text-secondary)]/80 mt-0.5 truncate",
 };
 
 export { menuItemTheme };

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

@@ -17,6 +17,8 @@ export interface MenuItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     disabled?: boolean;
     /** Whether the item has danger/destructive styling */
     isDanger?: boolean;
+    /** Whether the item is in a selected state (drives selected styling) */
+    selected?: boolean;
     /** Called on click or Enter/Space keyboard activation */
     onActivate?: () => void;
     /** Theme overrides for styling */

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

@@ -54,7 +54,7 @@ const messageTheme = {
     linkStyle: "flex flex-col rounded-lg border border-[var(--color-border)] overflow-hidden text-xs max-w-xs",
     // Reactions styles
     reactionsContainerStyle: "flex flex-wrap items-center gap-1.5 mt-1.5",
-    reactionPillStyle: "inline-flex items-center gap-1 rounded-full border border-[var(--color-border)] bg-[var(--color-background-secondary)] px-2 py-0.5 text-xs cursor-pointer transition-colors hover:bg-[var(--color-background-tertiary)]",
+    reactionPillStyle: "inline-flex items-center gap-1 rounded-full border border-[var(--color-border)] bg-[var(--color-background-secondary)] px-2 py-0.5 text-xs cursor-pointer transition-colors hover:bg-[var(--color-surface-hover)]",
     reactionPillActiveStyle: "border-[var(--color-primary-200)] bg-[var(--color-primary-50)] text-[var(--color-primary)]",
     // Reply/quote styles
     replyStyle: "border-l-2 border-[var(--color-border)] pl-2.5 mb-2 text-xs text-[var(--color-text-muted)]",

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

@@ -3,7 +3,7 @@ const modalTheme = {
     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",
     containerVariants: {
-        default: "bg-white ring-4 !ring-white/10 dark:bg-[var(--color-background-secondary)] border border-[var(--color-border)]",
+        default: "bg-[var(--color-surface-raised)] ring-4 !ring-white/10 dark:bg-[var(--color-surface-raised)] border border-[var(--color-border)]",
         translucent: "bg-gradient-to-b from-[var(--color-background)]/90 to-[var(--color-background)]/70 backdrop-blur-xl ring-4 ring-white/20 border-t border-[var(--color-border)]",
     },
     header: "flex items-start justify-between p-6 pb-0 shrink-0 border-b border-transparent gap-6 relative",

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

@@ -1,3 +1,3 @@
 import React from "react";
 import { NavItemProps } from "./NavItem.types";
-export declare const NavItem: React.ForwardRefExoticComponent<NavItemProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavItem: React.ForwardRefExoticComponent<NavItemProps & React.RefAttributes<HTMLElement>>;

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

@@ -1,17 +1,22 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import React__default, { useId, useState, useCallback, useMemo } from 'react';
+import React__default, { useId, useRef, useState, useCallback, useEffect, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
+import { Dropdown } from '../Dropdown/Dropdown.js';
+import '../Dropdown/DropdownTrigger.js';
+import '../Dropdown/DropdownMenu.js';
+import '../Dropdown/DropdownItem.js';
+import '../Dropdown/DropdownSection.js';
+import '../Dropdown/DropdownSeparator.js';
+import '../Dropdown/Dropdown.theme.js';
 import { navItemTheme } from './NavItem.theme.js';
-import { useSidebarContext, useAccordionNavContext } from '../Sidebar/SidebarContext.js';
+import { useSidebarContext, useAccordionNavContext, useSidebarDensity } from '../Sidebar/SidebarContext.js';
 import { Tooltip } from '../Tooltip/Tooltip.js';
 import '../Tooltip/Tooltip.animations.js';
 import { Badge } from '../Badge/Badge.js';
 import { ChevronDownIcon } from '@heroicons/react/20/solid';
 import { AnimatePresence, motion } from 'motion/react';
 
-const NavItem = React__default.forwardRef(({ children, startContent: propStartContent, endContent: propEndContent, icon, // Legacy
-badge, // Legacy
-notification, description, shortcut, href, onClick, active = false, disabled = false, isDisabled: propIsDisabled, isDanger = false, hasSubmenu: propHasSubmenu = false, expanded: controlledExpanded, onToggleExpanded, items, defaultExpanded = false, level = 0, showTooltipWhenCollapsed = true, className, theme: customTheme = {}, ...props }, ref) => {
+const NavItem = React__default.forwardRef(({ children, startContent, endContent, notification, description, shortcut, href, onClick, active = false, isDisabled = false, hasSubmenu: propHasSubmenu = false, expanded: controlledExpanded, onToggleExpanded, items, defaultExpanded = false, level = 0, showTooltipWhenCollapsed = true, className, theme: customTheme = {}, ...props }, ref) => {
     var _a, _b;
     const sidebarContext = useSidebarContext();
     const accordionNav = useAccordionNavContext();
@@ -19,8 +24,53 @@ notification, description, shortcut, href, onClick, active = false, disabled = f
     const collapsed = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.collapsed) || false;
     const isInSidebar = !!sidebarContext;
     const isMobile = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.isMobile) || false;
+    const density = useSidebarDensity();
+    const defaultExpandedRegisteredRef = useRef(false);
     // Self-managed submenu state
     const [internalExpanded, setInternalExpanded] = useState(defaultExpanded);
+    // Dropdown open state for collapsed sidebar hover submenu
+    const [isDropdownOpen, setIsDropdownOpen] = useState(false);
+    const hoverTimeoutRef = useRef(null);
+    const handleMouseEnter = useCallback(() => {
+        if (hoverTimeoutRef.current) {
+            clearTimeout(hoverTimeoutRef.current);
+            hoverTimeoutRef.current = null;
+        }
+        setIsDropdownOpen(true);
+    }, []);
+    const handleMouseLeave = useCallback(() => {
+        if (hoverTimeoutRef.current) {
+            clearTimeout(hoverTimeoutRef.current);
+        }
+        hoverTimeoutRef.current = setTimeout(() => {
+            setIsDropdownOpen(false);
+        }, 150);
+    }, []);
+    useEffect(() => {
+        return () => {
+            if (hoverTimeoutRef.current) {
+                clearTimeout(hoverTimeoutRef.current);
+            }
+        };
+    }, []);
+    // Resolve active keys for Dropdown selection mode
+    const activeKeys = useMemo(() => {
+        if (!items)
+            return [];
+        return items
+            .map((item, idx) => (item.active ? `sub-item-${idx}` : null))
+            .filter((key) => key !== null);
+    }, [items]);
+    const handleItemAction = useCallback((item) => {
+        if (item.isDisabled)
+            return;
+        if (item.onClick) {
+            item.onClick();
+        }
+        else if (item.href) {
+            window.location.href = item.href;
+        }
+    }, []);
     // Determine if this item has a submenu
     const hasSubmenu = propHasSubmenu || (items && items.length > 0);
     // Determine expanded state: controlled vs accordion vs internal
@@ -52,15 +102,21 @@ notification, description, shortcut, href, onClick, active = false, disabled = f
             setInternalExpanded(prev => !prev);
         }
     }, [isControlled, isAccordionManaged, isExpanded, onToggleExpanded, accordionNav, stableId]);
-    // Map legacy props
-    const startContent = propStartContent || icon;
-    const actualIsDisabled = propIsDisabled || disabled;
-    // Build end content
-    let endContent = propEndContent;
-    if (!endContent && badge) {
-        endContent = (jsx(Badge, { color: "neutral", variant: "soft", size: "sm", children: badge }));
-    }
-    // Notification element
+    useEffect(() => {
+        if (!defaultExpandedRegisteredRef.current &&
+            !isControlled &&
+            isAccordionManaged &&
+            hasSubmenu &&
+            defaultExpanded &&
+            accordionNav.openId === null) {
+            defaultExpandedRegisteredRef.current = true;
+            accordionNav.register(stableId);
+        }
+    }, [accordionNav, defaultExpanded, hasSubmenu, isAccordionManaged, isControlled, stableId]);
+    // Whether there is an active notification (dot or non-zero count)
+    const hasNotification = notification === true ||
+        (typeof notification === "number" && notification > 0);
+    // Expanded view: a dot for boolean, a count Badge for numbers
     const notificationElement = useMemo(() => {
         if (notification === undefined || notification === false)
             return null;
@@ -68,10 +124,10 @@ notification, description, shortcut, href, onClick, active = false, disabled = f
             return (jsx("span", { className: cn(navItemTheme.notificationDot, customTheme.notificationDot) }));
         }
         if (typeof notification === "number" && notification > 0) {
-            return (jsx("span", { className: cn(navItemTheme.notificationBadge, customTheme.notificationBadge), children: notification > 99 ? "99+" : notification }));
+            return (jsx(Badge, { color: "neutral", variant: "soft", size: "sm", children: notification > 99 ? "99+" : notification }));
         }
         return null;
-    }, [notification, customTheme.notificationDot, customTheme.notificationBadge]);
+    }, [notification, customTheme.notificationDot]);
     const theme = useMemo(() => ({
         ...navItemTheme,
         ...customTheme,
@@ -79,11 +135,11 @@ notification, description, shortcut, href, onClick, active = false, disabled = f
         iconStates: { ...navItemTheme.iconStates, ...customTheme.iconStates },
         levels: { ...navItemTheme.levels, ...customTheme.levels },
         collapsed: { ...navItemTheme.collapsed, ...customTheme.collapsed },
-        danger: customTheme.danger || navItemTheme.danger || "text-[var(--color-danger)] hover:bg-[var(--color-danger-50)]",
+        density: { ...navItemTheme.density, ...customTheme.density },
     }), [customTheme]);
     // Handle click events
     const handleClick = (e) => {
-        if (actualIsDisabled) {
+        if (isDisabled) {
             e.preventDefault();
             return;
         }
@@ -108,80 +164,143 @@ notification, description, shortcut, href, onClick, active = false, disabled = f
     };
     const isActive = active;
     const isCollapsedView = isInSidebar && collapsed && !isMobile;
-    // Get state classes
+    const isHoveredOrDropdownOpen = isCollapsedView ? isDropdownOpen : (hasSubmenu && isExpanded);
+    // State styling resolved in JS to plain utility classes so `className` overrides win
+    // (data-[active]/data-[disabled] are still emitted below as styling/test hooks)
     const getStateClasses = () => {
-        if (actualIsDisabled)
+        if (isDisabled)
             return theme.states.disabled;
         if (isActive)
             return theme.states.active;
         return theme.states.default;
     };
-    // Danger overrides
-    const dangerClasses = isDanger ? theme.danger : "";
-    // Active indicator
-    const activeIndicatorClasses = isActive && level === 0 ? theme.activeIndicator : "";
-    const containerClasses = cn(theme.baseStyle, getStateClasses(), theme.levels[level], isCollapsedView && ((_a = theme.collapsed) === null || _a === void 0 ? void 0 : _a.container), dangerClasses, activeIndicatorClasses, className);
-    // Get icon state classes
+    const containerClasses = cn(theme.baseStyle, theme.focusStyle, getStateClasses(), theme.levels[level], density === "compact" && theme.density.compact, hasSubmenu && isExpanded && !isActive && "text-[var(--color-text-primary)]", isCollapsedView && ((_a = theme.collapsed) === null || _a === void 0 ? void 0 : _a.container), isHoveredOrDropdownOpen && "bg-[var(--color-surface-hover)] text-[var(--color-text-primary)]", className);
     const getIconStateClasses = () => {
-        var _a, _b, _c;
-        if (actualIsDisabled)
-            return (_a = theme.iconStates) === null || _a === void 0 ? void 0 : _a.disabled;
+        if (isDisabled)
+            return theme.iconStates.disabled;
         if (isActive)
-            return (_b = theme.iconStates) === null || _b === void 0 ? void 0 : _b.active;
-        return (_c = theme.iconStates) === null || _c === void 0 ? void 0 : _c.default;
+            return theme.iconStates.active;
+        return theme.iconStates.default;
     };
-    // Build icon classes
-    const iconClasses = cn(isCollapsedView ? (_b = theme.collapsed) === null || _b === void 0 ? void 0 : _b.icon : theme.icon, getIconStateClasses());
+    const iconClasses = cn(theme.icon, getIconStateClasses(), hasSubmenu && isExpanded && !isActive && "opacity-100", isCollapsedView && ((_b = theme.collapsed) === null || _b === void 0 ? void 0 : _b.icon), isHoveredOrDropdownOpen && "opacity-100");
     const textClasses = cn(theme.text);
     // Chevron for submenu
-    const chevron = hasSubmenu && !isCollapsedView ? (jsx(ChevronDownIcon, { className: cn("size-4 transition-transform duration-200 text-[var(--color-text-muted)]", isExpanded && "rotate-180") })) : null;
-    // Content component
-    const content = (jsxs("div", { ref: ref, className: containerClasses, role: href ? "link" : "button", tabIndex: actualIsDisabled ? -1 : 0, "aria-disabled": actualIsDisabled, "aria-expanded": hasSubmenu ? isExpanded : undefined, "data-active": isActive, "data-disabled": actualIsDisabled, "data-level": level, onClick: handleClick, onKeyDown: (e) => {
-            if (e.key === "Enter" || e.key === " ") {
-                e.preventDefault();
-                handleClick(e);
-            }
-        }, ...props, children: [startContent && (jsxs("div", { className: "flex items-center justify-center flex-shrink-0 relative", children: [React__default.isValidElement(startContent)
+    const chevron = hasSubmenu && !isCollapsedView ? (jsx(ChevronDownIcon, { strokeWidth: 2, className: cn("size-4 transition-transform duration-200 text-[var(--color-text-muted)]", isExpanded && "text-[var(--color-text-primary)]", isExpanded && "rotate-180") })) : null;
+    // Strip drag/animation DOM handlers that collide with motion's prop types.
+    // `onSubmit`/`onSubmitCapture` are stripped too: NavItem renders as either
+    // `motion.a` or `motion.button`, but `NavItemProps extends HTMLAttributes<HTMLElement>`
+    // types these as `SubmitEventHandler<HTMLElement>`. Under react@canary types
+    // (e.g. Next 16 consumers building from source), `SubmitEvent` gains a
+    // T-dependent field, so the generic-element handler is no longer assignable to
+    // motion's element-specific `HTMLMotionProps<"a">` — a build-time type error.
+    // A NavItem never submits a form, so dropping these is behaviour-neutral.
+    const { onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, onSubmit, onSubmitCapture, ...motionSafeProps } = props;
+    const interactionProps = {
+        className: cn("relative overflow-hidden", containerClasses),
+        "aria-disabled": isDisabled || undefined,
+        "aria-expanded": hasSubmenu ? isExpanded : undefined,
+        "data-active": isActive,
+        "data-disabled": isDisabled,
+        "data-level": level,
+        onClick: handleClick,
+        whileHover: isDisabled ? undefined : (isCollapsedView ? { scale: 1.05 } : undefined),
+        whileTap: isDisabled ? undefined : { scale: 0.98 },
+        transition: { type: "spring", stiffness: 400, damping: 25 },
+        // Note: tried Framer Motion's canonical `layout` + `LayoutGroup` +
+        // `mode="popLayout"` pattern for the row's height shrink — transforms
+        // *do* fire (verified via getComputedStyle), but the parent Sidebar's
+        // concurrent `motion.aside` width animation re-triggers measurements
+        // every frame, which keeps resetting the layout animation before it
+        // settles. The row visibly freezes mid-transform. Animating the inner
+        // motion.div's height directly (see AnimatePresence below) sidesteps the
+        // concurrent-measurement problem and produces a smooth ~200ms shrink.
+        ...motionSafeProps,
+    };
+    const innerContent = (jsxs(Fragment, { children: [startContent && (jsxs("div", { className: "flex items-center justify-center flex-shrink-0 relative", children: [React__default.isValidElement(startContent)
                         ? React__default.cloneElement(startContent, {
                             className: cn(iconClasses, startContent.props.className),
                         })
-                        : startContent, isCollapsedView && notificationElement && (jsx("span", { className: "absolute -top-1 -right-1", children: notificationElement }))] })), jsx("div", { "aria-hidden": isCollapsedView || undefined, style: {
-                    display: 'grid',
-                    gridTemplateColumns: isCollapsedView ? '0fr' : '1fr',
-                    overflow: 'hidden',
-                    flex: '1 1 auto',
-                    opacity: isCollapsedView ? 0 : 1,
-                    transition: 'grid-template-columns 0.18s cubic-bezier(0.4,0,0.2,1), opacity 0.12s ease-out',
-                }, children: jsxs("div", { style: { overflow: 'hidden', minWidth: 0 }, children: [jsxs("div", { className: "flex items-center justify-between gap-2", children: [jsx("span", { className: cn("truncate", textClasses), children: children }), shortcut && (jsx("kbd", { className: "hidden group-hover:inline-block text-sm text-[var(--color-text-muted)] font-sans border border-[var(--color-border)] rounded px-1.5 py-0.5", children: shortcut }))] }), description && (jsx("div", { className: "text-sm text-[var(--color-text-muted)] mt-0.5 truncate", children: description }))] }) }), jsx("div", { style: {
-                    display: 'grid',
-                    gridTemplateColumns: isCollapsedView ? '0fr' : '1fr',
-                    overflow: 'hidden',
-                    flexShrink: 0,
-                    opacity: isCollapsedView ? 0 : 1,
-                    transition: 'grid-template-columns 0.18s cubic-bezier(0.4,0,0.2,1), opacity 0.12s ease-out',
-                }, children: jsxs("div", { className: "flex items-center gap-1.5", style: { overflow: 'hidden', minWidth: 0 }, children: [notificationElement, endContent, chevron] }) }), isCollapsedView && (jsx("span", { className: "sr-only", children: children }))] }));
+                        : startContent, isCollapsedView && hasNotification && (jsx("span", { className: cn("absolute -top-0.5 -right-0.5 ring-2 ring-[var(--color-surface)]", navItemTheme.notificationDot, customTheme.notificationDot), "aria-hidden": "true" }))] })), jsx(AnimatePresence, { initial: false, children: !isCollapsedView && (jsxs(motion.div, { initial: { opacity: 0, x: -4, height: 0 }, animate: { opacity: 1, x: 0, height: "auto" }, exit: { opacity: 0, x: -4, height: 0 }, transition: {
+                        opacity: { duration: 0.15, ease: [0.4, 0, 0.2, 1] },
+                        x: { duration: 0.2, ease: [0.4, 0, 0.2, 1] },
+                        height: { duration: 0.2, ease: [0.4, 0, 0.2, 1] },
+                    }, className: "flex-1 min-w-0 flex flex-col overflow-hidden whitespace-nowrap", children: [jsxs("span", { className: "flex items-center justify-between gap-2 w-full min-w-0", children: [jsx("span", { className: cn("truncate flex-1 min-w-0", textClasses), children: children }), jsxs("span", { className: "flex items-center gap-1.5 flex-shrink-0 ml-2", children: [shortcut && (jsx("kbd", { className: "hidden group-hover:inline-flex h-[18px] items-center text-[10px] text-[var(--color-text-muted)] font-sans border border-[var(--color-border)] rounded px-1.5 leading-none flex-shrink-0", children: shortcut })), notificationElement, endContent, chevron] })] }), description && (jsx("span", { className: "block text-xs text-[var(--color-text-muted)] mt-0.5 truncate w-full", children: description }))] }, "expanded-content")) }), isCollapsedView && (jsxs("span", { className: "sr-only", children: [children, typeof notification === "number" && notification > 0
+                        ? ` (${notification} unread)`
+                        : notification === true
+                            ? " (unread)"
+                            : null] }))] }));
+    // Content component
+    const content = href && !hasSubmenu ? (jsx(motion.a, { ref: ref, href: isDisabled ? undefined : href, tabIndex: isDisabled ? -1 : undefined, ...interactionProps, children: innerContent })) : (jsx(motion.button, { ref: ref, type: "button", disabled: isDisabled, ...interactionProps, children: innerContent }));
     // Self-contained submenu
     const submenu = hasSubmenu && items && items.length > 0 && !isCollapsedView ? (jsx(AnimatePresence, { initial: false, children: isExpanded && (jsx(motion.div, { initial: "collapsed", animate: "open", exit: "collapsed", variants: {
-                open: { opacity: 1, height: "auto" },
-                collapsed: { opacity: 0, height: 0 },
-            }, transition: { duration: 0.2, ease: "easeInOut" }, className: "overflow-hidden", children: items.map((item, idx) => (jsx(NavItem, { level: Math.min((level + 1), 2), startContent: item.startContent, active: item.active, isDisabled: item.isDisabled, badge: item.badge, notification: item.notification, href: item.href, onClick: item.onClick, children: item.children }, idx))) })) })) : null;
-    // Wrap with link if href is provided
-    const renderWrapped = (node) => {
-        if (href && !actualIsDisabled) {
-            return (jsx("a", { href: href, className: "block group", children: node }));
-        }
-        return node;
+                open: {
+                    opacity: 1,
+                    height: "auto",
+                    transition: {
+                        height: { duration: 0.18, ease: "easeOut" },
+                        opacity: { duration: 0.12 },
+                    },
+                },
+                collapsed: {
+                    opacity: 0,
+                    height: 0,
+                    transition: {
+                        height: { duration: 0.16, ease: "easeInOut" },
+                        opacity: { duration: 0.1 },
+                    },
+                },
+            }, className: "overflow-hidden", children: jsx("div", { className: "relative space-y-0.5 pl-6", children: items.map((item, idx) => (jsxs(motion.div, { className: "relative", children: [idx < items.length - 1 && (jsx(motion.span, { initial: { opacity: 0, scaleY: 0 }, animate: { opacity: 1, scaleY: 1 }, exit: { opacity: 0, scaleY: 0 }, transition: {
+                                delay: idx * 0.055,
+                                duration: 0.16,
+                                ease: "easeOut",
+                            }, className: "absolute left-[-6px] top-1/2 h-[calc(100%+0.125rem)] w-px origin-top bg-[var(--color-neutral-400)] dark:bg-[var(--color-neutral-600)]", "aria-hidden": "true" })), jsx(motion.span, { initial: { opacity: 0, scale: 0.5 }, animate: { opacity: 1, scale: 1 }, exit: { opacity: 0, scale: 0.5 }, transition: {
+                                delay: idx * 0.055,
+                                type: "spring",
+                                stiffness: 520,
+                                damping: 30,
+                                mass: 0.6,
+                            }, className: cn("absolute left-[-8.5px] top-1/2 z-10 size-1.5 -translate-y-1/2 rounded-full", item.active
+                                ? "bg-[var(--color-primary)]"
+                                : "bg-[var(--color-neutral-400)] dark:bg-[var(--color-neutral-600)]"), "aria-hidden": "true" }), jsx(motion.div, { initial: { opacity: 0, x: -6 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: -6 }, transition: {
+                                delay: idx * 0.055 + 0.035,
+                                type: "spring",
+                                stiffness: 460,
+                                damping: 34,
+                                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) => {
+                            const itemKey = `sub-item-${idx}`;
+                            const subNotificationElement = (() => {
+                                if (item.notification === undefined || item.notification === false)
+                                    return null;
+                                if (item.notification === true) {
+                                    return (jsx("span", { className: cn(theme.notificationDot, customTheme.notificationDot) }));
+                                }
+                                if (typeof item.notification === "number" && item.notification > 0) {
+                                    return (jsx(Badge, { color: "neutral", variant: "soft", size: "sm", children: item.notification > 99 ? "99+" : item.notification }));
+                                }
+                                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;
     };
     // Always render Tooltip when in a sidebar (keeps tree structure stable across
     // collapse/expand so CSS transitions aren't interrupted by DOM remounts).
-    // The tooltip is disabled when not in collapsed view.
+    // The tooltip is *disabled* (not unmounted) when out of collapsed view or while
+    // the dropdown flyout is open — unmounting it would swap the stable `block w-full`
+    // wrapper for the Dropdown's `display:contents` root, which drops the nav's
+    // `space-y-1` top margin and shifts every item below it up on hover.
     const renderWithTooltip = (node) => {
         if (!isInSidebar || !showTooltipWhenCollapsed) {
             return node;
         }
-        return (jsx(Tooltip, { content: children, placement: "right", disabled: !isCollapsedView, triggerClassName: "block w-full", children: node }));
+        return (jsx(Tooltip, { content: children, placement: "right", disabled: !isCollapsedView || isDropdownOpen, triggerClassName: "block w-full", children: node }));
     };
-    return (jsxs(Fragment, { children: [renderWithTooltip(renderWrapped(content)), submenu] }));
+    return (jsxs("div", { className: "flex flex-col gap-0.5 w-full", children: [renderWithTooltip(renderContent()), submenu] }));
 });
 NavItem.displayName = "NavItem";
 

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

@@ -1,30 +1,49 @@
 const navItemTheme = {
-    baseStyle: "relative flex items-center gap-2 px-2 py-1.5 text-sm font-medium cursor-pointer select-none transition-colors duration-150 w-full rounded-[var(--nav-item-radius)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] group overflow-hidden",
-    icon: "size-4 text-[var(--color-text-secondary)]",
+    baseStyle: "group relative flex items-center gap-3 px-2.5 py-2 text-sm font-medium cursor-pointer select-none w-full rounded-[var(--nav-item-radius)] outline-none overflow-hidden transition-[padding,gap,height,background-color,border-color,color,box-shadow] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)] text-left",
+    icon: "size-5",
     text: "flex-1 min-w-0 truncate",
+    // State styling resolved in JS to plain utility classes so `className` overrides win
+    // (data-[state] variants carry attribute-selector specificity and can't be overridden
+    //  by a plain className — see Button.theme.ts for the same rationale).
     states: {
-        default: "text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)]",
-        active: "bg-[var(--color-primary)]/10 text-[var(--color-primary)] font-semibold",
+        default: "text-[var(--color-text-secondary)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text-primary)]",
+        active: "bg-[var(--color-primary)]/10 text-[var(--color-primary)] dark:text-[var(--color-text-primary)] dark:bg-white/10",
         disabled: "opacity-60 cursor-not-allowed pointer-events-none text-[var(--color-text-placeholder)]",
-        hover: "hover:bg-[var(--color-background-secondary)]",
     },
+    // Icons inherit the item's text color via `currentColor` — we only adjust
+    // opacity so the icon reads slightly lighter than the label by default.
     iconStates: {
-        default: "text-[var(--color-text-secondary)] group-hover:text-[var(--color-text-primary)]",
-        active: "text-[var(--color-primary)]",
+        default: "opacity-70 group-hover:opacity-100",
+        active: "opacity-100",
         disabled: "opacity-60",
     },
+    // Keyboard focus ring
+    focusStyle: "focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-background)] " +
+        "dark:focus-visible:ring-[var(--color-primary-400)]",
     levels: {
         0: "",
-        1: "pl-6",
+        1: "pl-11",
         2: "pl-10",
     },
+    // Collapsed override gives every nav row a uniform 36×36 square hit-area.
+    // CRITICAL: this uses PADDING-based centering, not `justify-center`, so the
+    // expanded↔collapsed transition is one continuous animation of the padding
+    // + gap properties (which are CSS-transitionable). Toggling `justify-*`
+    // would cause a frame-0 flex-layout snap — the label appears at its final
+    // position instead of sliding in via AnimatePresence.
+    //
+    // On a 60px rail (Sidebar.Content px-3 → 36px interior, NavItem w-full):
+    //   !px-2 (8 each) + size-5 icon (20) = 8 + 20 + 8 = 36 → centered icon.
+    //   baseStyle's py-2 (8 each) + icon 20 = 36 → square height.
+    // !py-2 is repeated explicitly so the compact density's py-1.5 doesn't win.
     collapsed: {
-        container: "!gap-0 justify-center !p-2",
+        container: "!gap-0 !px-2 !py-2",
         icon: "size-5",
     },
-    activeIndicator: "before:absolute before:left-0 before:top-1/2 before:-translate-y-1/2 before:h-5 before:w-[3px] before:rounded-full before:bg-[var(--color-primary)]",
-    notificationDot: "size-2 rounded-full bg-[var(--color-danger)]",
-    notificationBadge: "min-w-[18px] h-[18px] px-1 text-[10px] font-semibold rounded-full bg-[var(--color-danger)] text-[var(--color-danger-contrast)] flex items-center justify-center leading-none",
+    density: {
+        compact: "px-2 py-1.5 text-[13px]",
+    },
+    notificationDot: "size-2 rounded-full bg-[var(--color-primary)]",
 };
 
 export { navItemTheme };