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

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

@@ -1,124 +1,318 @@
-import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { useMemo } from 'react';
+"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';
+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 } 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
-description, shortcut, href, onClick, active = false, disabled = false, isDisabled: propIsDisabled, isDanger = false, hasSubmenu = false, expanded = false, onToggleExpanded, 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();
+    const stableId = useId();
     const collapsed = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.collapsed) || false;
     const isInSidebar = !!sidebarContext;
-    // Map legacy props
-    const startContent = propStartContent || icon;
-    const actualIsDisabled = propIsDisabled || disabled;
-    // Construct end content
-    let endContent = propEndContent;
-    if (!endContent && badge) {
-        endContent = (jsx(Badge, { color: "neutral", variant: "ghost", size: "sm", children: badge }));
+    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
+    const isAccordionManaged = !!accordionNav;
+    const isControlled = controlledExpanded !== undefined;
+    let isExpanded;
+    if (isControlled) {
+        isExpanded = controlledExpanded;
+    }
+    else if (isAccordionManaged && hasSubmenu) {
+        isExpanded = accordionNav.openId === stableId;
     }
-    if (!endContent && hasSubmenu) {
-        endContent = (jsx(ChevronDownIcon, { className: cn("size-4 transition-transform duration-300", expanded && "rotate-180") }));
+    else {
+        isExpanded = internalExpanded;
     }
+    const handleToggleExpanded = useCallback(() => {
+        if (isControlled) {
+            onToggleExpanded === null || onToggleExpanded === void 0 ? void 0 : onToggleExpanded();
+        }
+        else if (isAccordionManaged) {
+            if (isExpanded) {
+                accordionNav.unregister(stableId);
+            }
+            else {
+                accordionNav.register(stableId);
+            }
+        }
+        else {
+            setInternalExpanded(prev => !prev);
+        }
+    }, [isControlled, isAccordionManaged, isExpanded, onToggleExpanded, accordionNav, stableId]);
+    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;
+        if (notification === true) {
+            return (jsx("span", { className: cn(navItemTheme.notificationDot, customTheme.notificationDot) }));
+        }
+        if (typeof notification === "number" && notification > 0) {
+            return (jsx(Badge, { color: "neutral", variant: "soft", size: "sm", children: notification > 99 ? "99+" : notification }));
+        }
+        return null;
+    }, [notification, customTheme.notificationDot]);
     const theme = useMemo(() => ({
         ...navItemTheme,
         ...customTheme,
-        states: {
-            ...navItemTheme.states,
-            ...customTheme.states,
-        },
-        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)]",
+        states: { ...navItemTheme.states, ...customTheme.states },
+        iconStates: { ...navItemTheme.iconStates, ...customTheme.iconStates },
+        levels: { ...navItemTheme.levels, ...customTheme.levels },
+        collapsed: { ...navItemTheme.collapsed, ...customTheme.collapsed },
+        density: { ...navItemTheme.density, ...customTheme.density },
     }), [customTheme]);
     // Handle click events
     const handleClick = (e) => {
-        if (actualIsDisabled) {
+        if (isDisabled) {
             e.preventDefault();
             return;
         }
-        if (hasSubmenu && onToggleExpanded) {
+        if (hasSubmenu) {
             e.preventDefault();
-            onToggleExpanded();
+            handleToggleExpanded();
             return;
         }
         if (onClick) {
             e.preventDefault();
             onClick();
+            // Close mobile sidebar after clicking a nav item
+            if (isMobile && sidebarContext) {
+                sidebarContext.setMobileOpen(false);
+            }
             return;
         }
-        // If href is provided, let the default navigation happen
+        // Close mobile sidebar after navigation
+        if (href && isMobile && sidebarContext) {
+            sidebarContext.setMobileOpen(false);
+        }
     };
     const isActive = active;
-    // Get state classes
+    const isCollapsedView = isInSidebar && collapsed && !isMobile;
+    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 : "";
-    // Build container classes
-    const containerClasses = cn(theme.baseStyle, getStateClasses(), theme.levels[level], isInSidebar && collapsed && ((_a = theme.collapsed) === null || _a === void 0 ? void 0 : _a.container), dangerClasses, 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(isInSidebar && collapsed ? (_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, { 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,
+        "aria-current": isActive ? "page" : 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 && 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 = (jsxs("div", { ref: ref, className: containerClasses, role: href ? "link" : "button", tabIndex: actualIsDisabled ? -1 : 0, "aria-disabled": actualIsDisabled, "aria-expanded": hasSubmenu ? expanded : 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 && (jsx("div", { className: cn("flex items-center justify-center flex-shrink-0"
-                // Icon size is handled by icon classes
-                ), children: React__default.isValidElement(startContent)
-                    ? React__default.cloneElement(startContent, {
-                        className: cn(iconClasses, startContent.props.className),
-                    })
-                    : startContent })), (!isInSidebar || !collapsed) && (jsxs("div", { className: "flex-1 min-w-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-xs 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-xs text-[var(--color-text-muted)] mt-0.5 truncate", children: description }))] })), endContent && (!isInSidebar || !collapsed) && (jsx("div", { className: "flex items-center justify-center flex-shrink-0", children: endContent })), isInSidebar && collapsed && (jsx("span", { className: "sr-only", children: children }))] }));
-    // Wrap with link if href is provided
-    if (href && !actualIsDisabled) {
-        const LinkContent = (jsx("a", { href: href, className: "block group", children: content }));
-        // Show tooltip in collapsed sidebar mode
-        if (isInSidebar && collapsed && showTooltipWhenCollapsed) {
-            return (jsx(Tooltip, { content: children, placement: "right", children: LinkContent }));
-        }
-        return LinkContent;
-    }
-    // Show tooltip in collapsed sidebar mode
-    if (isInSidebar && collapsed && showTooltipWhenCollapsed) {
-        return (jsx(Tooltip, { content: children, placement: "right", children: content }));
-    }
-    return content;
+    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",
+                    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 = () => {
+        // 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)
+                                    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* (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 || isDropdownOpen, triggerClassName: "block w-full", children: node }));
+    };
+    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,27 +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-all duration-300 w-full rounded-[var(--nav-item-radius)] outline-none group",
-    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-neutral-100",
-        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-neutral-100",
     },
+    // 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 aspect-square",
+        container: "!gap-0 !px-2 !py-2",
         icon: "size-5",
     },
+    density: {
+        compact: "px-2 py-1.5 text-[13px]",
+    },
+    notificationDot: "size-2 rounded-full bg-[var(--color-primary)]",
 };
 
 export { navItemTheme };

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

@@ -1,15 +1,31 @@
 import { ReactNode } from "react";
-export interface NavItemProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface NavItemSubmenuItem {
+    /** Label text */
+    children: ReactNode;
+    /** Link href */
+    href?: string;
+    /** Click handler */
+    onClick?: () => void;
+    /** Whether this sub-item is active */
+    active?: boolean;
+    /** Whether this sub-item is disabled */
+    isDisabled?: boolean;
+    /** Notification count/dot on the sub-item */
+    notification?: number | boolean;
+    /** Start content (icon) for the sub-item */
+    startContent?: ReactNode;
+}
+export interface NavItemProps extends React.HTMLAttributes<HTMLElement> {
     /**
      * Content of the navigation item
      */
     children: ReactNode;
     /**
-     * Start content (icon), replaces `icon`
+     * Start content (icon)
      */
     startContent?: ReactNode;
     /**
-     * End content (badge/arrow), replaces `badge`
+     * End content (badge/arrow)
      */
     endContent?: ReactNode;
     /**
@@ -21,15 +37,9 @@ export interface NavItemProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     shortcut?: string;
     /**
-     * Legacy icon prop (mapped to startContent)
-     * @deprecated Use startContent instead
-     */
-    icon?: ReactNode;
-    /**
-     * Legacy badge prop (mapped to endContent)
-     * @deprecated Use endContent instead
+     * Notification indicator. Pass a number for a count badge, or true for a dot.
      */
-    badge?: string | number;
+    notification?: number | boolean;
     /**
      * Link href (for navigation)
      */
@@ -49,28 +59,31 @@ export interface NavItemProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     isDisabled?: boolean;
     /**
-     * Alias for isDisabled
-     * @deprecated Use isDisabled
-     */
-    disabled?: boolean;
-    /**
-     * Whether the item represents a danger action
-     */
-    isDanger?: boolean;
-    /**
-     * Whether the item has a submenu
+     * Whether the item has a submenu (manual mode).
+     * If `items` is provided, this is set automatically.
      * @default false
      */
     hasSubmenu?: boolean;
     /**
-     * Whether the submenu is expanded (for multi-level navigation)
+     * Whether the submenu is expanded (controlled mode for manual submenus).
      * @default false
      */
     expanded?: boolean;
     /**
-     * Callback when submenu is toggled
+     * Callback when submenu is toggled (manual mode)
      */
     onToggleExpanded?: () => void;
+    /**
+     * Self-contained submenu items. When provided, NavItem manages its own
+     * expand/collapse state internally. Children items automatically get
+     * level={parentLevel + 1}.
+     */
+    items?: NavItemSubmenuItem[];
+    /**
+     * Whether the self-contained submenu is expanded by default
+     * @default false
+     */
+    defaultExpanded?: boolean;
     /**
      * Nesting level for indentation (0, 1, 2)
      * @default 0
@@ -94,14 +107,14 @@ export interface NavItemTheme {
         default: string;
         active: string;
         disabled: string;
-        hover: string;
     };
-    iconStates?: {
-        default?: string;
-        active?: string;
-        disabled?: string;
-        hover?: string;
+    iconStates: {
+        default: string;
+        active: string;
+        disabled: string;
     };
+    /** Keyboard focus-visible ring */
+    focusStyle: string;
     levels: {
         0: string;
         1: string;
@@ -111,6 +124,10 @@ export interface NavItemTheme {
         container: string;
         icon: string;
     };
+    density: {
+        compact: string;
+    };
+    notificationDot: string;
 }
 export interface NavItemThemeOverrides {
     baseStyle?: string;
@@ -120,14 +137,13 @@ export interface NavItemThemeOverrides {
         default: string;
         active: string;
         disabled: string;
-        hover: string;
     }>;
     iconStates?: Partial<{
         default: string;
         active: string;
         disabled: string;
-        hover: string;
     }>;
+    focusStyle?: string;
     levels?: Partial<{
         0: string;
         1: string;
@@ -137,32 +153,8 @@ export interface NavItemThemeOverrides {
         container: string;
         icon: string;
     }>;
-    danger?: string;
-}
-export interface NavItemTheme {
-    baseStyle: string;
-    icon: string;
-    text: string;
-    states: {
-        default: string;
-        active: string;
-        disabled: string;
-        hover: string;
-    };
-    iconStates?: {
-        default?: string;
-        active?: string;
-        disabled?: string;
-        hover?: string;
-    };
-    levels: {
-        0: string;
-        1: string;
-        2: string;
-    };
-    collapsed: {
-        container: string;
-        icon: string;
-    };
-    danger?: string;
+    density?: Partial<{
+        compact: string;
+    }>;
+    notificationDot?: string;
 }

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

@@ -1,2 +1,2 @@
 export { NavItem } from './NavItem';
-export type { NavItemProps, NavItemTheme, NavItemThemeOverrides } from './NavItem.types';
+export type { NavItemProps, NavItemSubmenuItem, NavItemTheme, NavItemThemeOverrides } from './NavItem.types';

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';