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

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

@@ -2,6 +2,7 @@ import { ReactNode, HTMLAttributes } from 'react';
 export type SidebarSide = 'left' | 'right';
 export type SidebarVariant = 'sidebar' | 'floating' | 'inset';
 export type SidebarUserStatus = 'online' | 'offline' | 'away' | 'busy';
+export type SidebarDensity = 'comfortable' | 'compact';
 export interface SidebarContextValue {
     collapsed: boolean;
     setCollapsed: (collapsed: boolean) => void;
@@ -12,6 +13,7 @@ export interface SidebarContextValue {
     };
     side: SidebarSide;
     variant: SidebarVariant;
+    density: SidebarDensity;
     /** Whether the sidebar is currently showing as mobile overlay */
     isMobileOpen: boolean;
     setMobileOpen: (open: boolean) => void;
@@ -29,6 +31,11 @@ export interface SidebarProps extends React.HTMLAttributes<HTMLDivElement> {
      * @default "sidebar"
      */
     variant?: SidebarVariant;
+    /**
+     * Navigation density
+     * @default "comfortable"
+     */
+    density?: SidebarDensity;
     /**
      * Whether the sidebar is collapsed by default
      * @default false
@@ -65,7 +72,7 @@ export interface SidebarProps extends React.HTMLAttributes<HTMLDivElement> {
     /**
      * Children components
      */
-    children: ReactNode;
+    children?: ReactNode;
     /**
      * Custom theme overrides
      */
@@ -103,6 +110,10 @@ export interface SidebarNavProps extends React.HTMLAttributes<HTMLDivElement> {
      * @default false
      */
     accordion?: boolean;
+    /**
+     * Navigation density. Inherits from Sidebar when omitted.
+     */
+    density?: SidebarDensity;
     children: ReactNode;
 }
 export interface SidebarNavGroupProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -157,13 +168,123 @@ export interface SidebarUserProfileProps extends React.HTMLAttributes<HTMLDivEle
      * Content to render when the profile is clicked (e.g. dropdown menu)
      */
     dropdownContent?: ReactNode;
+    /**
+     * Custom content for the expandable region, replacing the default name/email block.
+     * The avatar and all collapse choreography (reveal animation, tooltip, dropdown
+     * placement) are preserved — only the text area is overridden. Copy-paste friendly.
+     */
+    children?: ReactNode;
 }
 export interface SidebarLogoProps extends HTMLAttributes<HTMLDivElement> {
-    /** Always-visible icon/mark (shown in both expanded and collapsed states) */
-    icon: ReactNode;
-    /** Text shown only when expanded — animates in/out automatically */
+    /**
+     * Logo shown when the sidebar is **expanded**. Accepts any node — an `<img>`,
+     * an inline `<svg>`, or composed JSX (e.g. a mark + wordmark). Preferred
+     * over the legacy `icon` + `text` API.
+     */
+    expanded?: ReactNode;
+    /**
+     * Logo shown when the sidebar is **collapsed**. Typically a square mark
+     * (image, SVG, or JSX). If omitted, falls back to `expanded`, then to the
+     * legacy `icon` prop.
+     */
+    collapsed?: ReactNode;
+    /**
+     * Convenience: image URL for the expanded logo. Rendered as an `<img>` with
+     * sensible defaults (`h-8 w-auto object-contain`). Use `expandedImageClassName`
+     * to override sizing / object-fit. Ignored when `expanded` (ReactNode) is set.
+     */
+    expandedSrc?: string;
+    /**
+     * Convenience: image URL for the collapsed logo. Rendered as an `<img>` in a
+     * 36×36 (`size-9`) slot — matching the nav icon track — with `object-cover`
+     * by default. Use `collapsedImageClassName` to switch to `object-contain`,
+     * adjust border-radius, etc. Ignored when `collapsed` (ReactNode) is set.
+     */
+    collapsedSrc?: string;
+    /** ClassName forwarded to the auto-rendered `<img>` for `expandedSrc`. */
+    expandedImageClassName?: string;
+    /** ClassName forwarded to the auto-rendered `<img>` for `collapsedSrc`. */
+    collapsedImageClassName?: string;
+    /** Alt text for any auto-rendered `<img>` (both `expandedSrc` and `collapsedSrc`). */
+    alt?: string;
+    /**
+     * Legacy: always-visible icon/mark. Shown in both states; the `text` prop
+     * fades in alongside it when expanded. Use `expanded` / `collapsed` instead
+     * for full control (especially for image/SVG logos that differ per state).
+     */
+    icon?: ReactNode;
+    /**
+     * Legacy: text rendered to the right of `icon` when expanded — animates
+     * in/out on collapse. Use `expanded` instead for full control.
+     */
     text?: ReactNode;
 }
+export interface SidebarSearchProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** Controlled value */
+    value?: string;
+    /** Uncontrolled initial value */
+    defaultValue?: string;
+    /**
+     * Fires on every keystroke. Consumers wire this to render results wherever
+     * they like (popover, command palette, side panel). The Sidebar tree itself
+     * is NOT filtered.
+     */
+    onChange?: (value: string) => void;
+    /** @default "Search…" */
+    placeholder?: string;
+    /** @default 'sm' */
+    size?: "sm" | "md";
+    /** Override the leading icon (defaults to MagnifyingGlassIcon). */
+    iconStart?: ReactNode;
+    /** Tooltip + aria-label for the collapsed-mode icon button. @default "Search" */
+    collapsedLabel?: string;
+    /** Hide the collapsed-mode icon button entirely. @default false */
+    hideWhenCollapsed?: boolean;
+    /** Forwarded to the underlying Input's group wrapper — use for background
+     * overrides on custom sidebar surfaces (e.g. `bg-transparent`). */
+    inputGroupClassName?: string;
+}
+export interface SidebarCardTheme {
+    /** Outer wrapper applied in both styled and unstyled modes — must carry
+     * `overflow-hidden` so the height collapse animation clips children. */
+    wrapperStyle: string;
+    /** Default container chrome (rounded / surface bg / border / padding).
+     * Skipped when the consumer sets `unstyled`. */
+    baseStyle: string;
+}
+export interface SidebarCardThemeOverrides {
+    wrapperStyle?: string;
+    baseStyle?: string;
+}
+export interface SidebarCardProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+    className?: string;
+    /**
+     * Drop the default container styling (rounded / bg / border / padding)
+     * so consumers can put an edge-to-edge image, a custom panel, or any
+     * non-card-shaped content inside without fighting the default chrome.
+     * The disappear-on-collapse animation is unchanged.
+     * @default false
+     */
+    unstyled?: boolean;
+    theme?: SidebarCardThemeOverrides;
+}
+export interface SidebarProviderProps {
+    children: React.ReactNode;
+    defaultCollapsed?: boolean;
+    collapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    mobileBreakpoint?: number;
+    mobileOpen?: boolean;
+    onMobileOpenChange?: (open: boolean) => void;
+    width?: {
+        expanded?: number;
+        collapsed?: number;
+    };
+    side?: SidebarSide;
+    variant?: SidebarVariant;
+    density?: SidebarDensity;
+}
 export interface SidebarTheme {
     baseStyle: string;
     variants: {
@@ -172,8 +293,6 @@ export interface SidebarTheme {
     sides: {
         [K in SidebarSide]: string;
     };
-    collapsed: string;
-    expanded: string;
     mobileOverlay: string;
     mobileBackdrop: string;
 }
@@ -185,8 +304,6 @@ export interface SidebarThemeOverrides {
     sides?: Partial<{
         [K in SidebarSide]: string;
     }>;
-    collapsed?: string;
-    expanded?: string;
     mobileOverlay?: string;
     mobileBackdrop?: string;
 }

package/dist/components/core/Sidebar/SidebarCard.d.ts

@@ -0,0 +1,25 @@
+import React from "react";
+import { SidebarCardProps } from "./Sidebar.types";
+/**
+ * A collapse-aware container for arbitrary sidebar content — promo CTAs,
+ * storage meters, tip-of-the-day, banner images, anything. Renders its
+ * children when the sidebar is expanded and **disappears entirely** when
+ * the sidebar collapses (smooth height + opacity exit via AnimatePresence).
+ *
+ * Composition is open: drop in raw text, an `<img>`, a `<Button>`,
+ * `<Progress>`, or any custom JSX. There are intentionally no sub-parts
+ * (`Sidebar.Card.Header`/`.Body`/…) because the whole card vanishes
+ * together — granular slots add ceremony with no payoff.
+ *
+ * @example
+ * <Sidebar.Card>
+ *   <p className="text-sm">Upgrade for unlimited projects.</p>
+ *   <Button size="sm" className="mt-2 w-full">Upgrade</Button>
+ * </Sidebar.Card>
+ *
+ * @example Edge-to-edge image (no default container chrome):
+ * <Sidebar.Card unstyled>
+ *   <img src="/promo.jpg" alt="" className="w-full rounded-[var(--card-radius)]" />
+ * </Sidebar.Card>
+ */
+export declare const SidebarCard: React.ForwardRefExoticComponent<SidebarCardProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/Sidebar/SidebarCard.js

@@ -0,0 +1,68 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default, { useMemo, useState, useEffect } from 'react';
+import { AnimatePresence, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { sidebarCardTheme } from './SidebarCard.theme.js';
+import { useSidebarCollapsed } from './SidebarContext.js';
+
+// Sidebar.Card mount is sequenced relative to the sidebar's collapse/expand
+// animation. On collapse → the card exits immediately (popLayout + slide/fade
+// in parallel with the rail narrowing). On expand → the card mount is delayed
+// until the sidebar's spring has settled, so the card lays out at its FINAL
+// expanded width on first render and the text never reflows mid-animation.
+// 260ms ≈ the spring's 99% settle time (stiffness 320, damping 34) — see
+// Sidebar.tsx's SIDEBAR_TRANSITION comment for the underlying math.
+const MOUNT_DELAY_MS = 260;
+/**
+ * A collapse-aware container for arbitrary sidebar content — promo CTAs,
+ * storage meters, tip-of-the-day, banner images, anything. Renders its
+ * children when the sidebar is expanded and **disappears entirely** when
+ * the sidebar collapses (smooth height + opacity exit via AnimatePresence).
+ *
+ * Composition is open: drop in raw text, an `<img>`, a `<Button>`,
+ * `<Progress>`, or any custom JSX. There are intentionally no sub-parts
+ * (`Sidebar.Card.Header`/`.Body`/…) because the whole card vanishes
+ * together — granular slots add ceremony with no payoff.
+ *
+ * @example
+ * <Sidebar.Card>
+ *   <p className="text-sm">Upgrade for unlimited projects.</p>
+ *   <Button size="sm" className="mt-2 w-full">Upgrade</Button>
+ * </Sidebar.Card>
+ *
+ * @example Edge-to-edge image (no default container chrome):
+ * <Sidebar.Card unstyled>
+ *   <img src="/promo.jpg" alt="" className="w-full rounded-[var(--card-radius)]" />
+ * </Sidebar.Card>
+ */
+const SidebarCard = React__default.forwardRef(({ children, className, unstyled = false, theme: customTheme, ...props }, ref) => {
+    const { isCollapsedView } = useSidebarCollapsed();
+    const theme = useMemo(() => ({ ...sidebarCardTheme, ...customTheme }), [customTheme]);
+    // Card is visible when expanded. Hide immediately on collapse (so the
+    // AnimatePresence exit + popLayout reflow happens in parallel with the
+    // rail narrowing). On expand, wait for the sidebar spring to settle
+    // before mounting — see `MOUNT_DELAY_MS` rationale.
+    const [shouldShow, setShouldShow] = useState(!isCollapsedView);
+    useEffect(() => {
+        if (isCollapsedView) {
+            setShouldShow(false);
+            return;
+        }
+        const id = setTimeout(() => setShouldShow(true), MOUNT_DELAY_MS);
+        return () => clearTimeout(id);
+    }, [isCollapsedView]);
+    // Strip drag/animation DOM handlers that collide with motion's prop types
+    // (same pattern the other Sidebar pieces use, e.g. Sidebar.tsx:54-61).
+    const { onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...motionSafeProps } = props;
+    return (
+    // `mode="popLayout"` removes the exiting card from the layout flow
+    // immediately so siblings (footer, nav rows below) snap into their new
+    // positions without waiting on the card's exit animation.
+    jsx(AnimatePresence, { initial: false, mode: "popLayout", children: shouldShow && (jsx(motion.div, { ref: ref, initial: { opacity: 0, x: -16 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: -16 }, transition: { duration: 0.2, ease: [0.4, 0, 0.2, 1] }, className: cn(theme.wrapperStyle, 
+            // Default card chrome (rounded / bg / border / p-3) unless the
+            // consumer opts out. className wins per shadcn rules.
+            !unstyled && theme.baseStyle, className), ...motionSafeProps, children: children }, "sidebar-card")) }));
+});
+SidebarCard.displayName = "SidebarCard";
+
+export { SidebarCard };

package/dist/components/core/Sidebar/SidebarCard.theme.d.ts

@@ -0,0 +1,8 @@
+import { SidebarCardTheme } from "./Sidebar.types";
+/**
+ * Default theme for `<Sidebar.Card>`. Small surface — the component itself
+ * only renders a single styled wrapper that disappears on collapse, so the
+ * theme just holds the default outer chrome. Set `unstyled` on the card to
+ * skip it entirely (e.g. for full-bleed images).
+ */
+export declare const sidebarCardTheme: SidebarCardTheme;

package/dist/components/core/Sidebar/SidebarCard.theme.js

@@ -0,0 +1,18 @@
+/**
+ * Default theme for `<Sidebar.Card>`. Small surface — the component itself
+ * only renders a single styled wrapper that disappears on collapse, so the
+ * theme just holds the default outer chrome. Set `unstyled` on the card to
+ * skip it entirely (e.g. for full-bleed images).
+ */
+const sidebarCardTheme = {
+    // Card chrome — surface bg, hairline border, sidebar-tuned padding (p-3 is
+    // tighter than core/Card's p-6 because the rail is narrow). `overflow-hidden`
+    // keeps any children clipped to the rounded corners.
+    baseStyle: "rounded-[var(--card-radius)] bg-[var(--color-surface)] border border-[var(--color-border)] p-3 overflow-hidden",
+    // Wrapper applied in both styled + unstyled modes. Empty by default —
+    // the slide/fade animation lives on motion.div itself, not on this layer,
+    // so no overflow trickery needed here.
+    wrapperStyle: "",
+};
+
+export { sidebarCardTheme };

package/dist/components/core/Sidebar/SidebarContent.js

@@ -1,14 +1,18 @@
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
-import { useSidebarContext } from './SidebarContext.js';
+import { useSidebarCollapsed, useSidebarDensity } from './SidebarContext.js';
+import { ScrollArea } from '../ScrollArea/ScrollArea.js';
+import '../ScrollArea/smooth/SmoothScrollEngine.js';
 
 const SidebarContent = React__default.forwardRef(({ children, className, ...props }, ref) => {
-    const sidebarContext = useSidebarContext();
-    const collapsed = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.collapsed) || false;
-    const isMobile = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.isMobile) || false;
-    const isCollapsedView = collapsed && !isMobile;
-    return (jsx("div", { ref: ref, className: cn("flex-1 overflow-y-auto overflow-x-hidden py-3 transition-all duration-200", isCollapsedView ? "px-2" : "px-2.5", className), ...props, children: children }));
+    const { isCollapsedView } = useSidebarCollapsed();
+    const density = useSidebarDensity();
+    return (jsx(ScrollArea, { ref: ref, type: "none", size: "thin", className: "flex-1 min-h-0", ...props, children: jsx("div", { className: cn("py-3 transition-[padding] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)]", density === "compact" && "py-2", 
+            // Collapsed px-3 (12) on a 60px rail leaves a 36px interior — every
+            // child row (NavItem, Sidebar.Search) is exactly 36px wide, matching
+            // the 36×36 hit-area target.
+            isCollapsedView ? "px-3" : "px-2.5", className), children: children }) }));
 });
 SidebarContent.displayName = "SidebarContent";
 

package/dist/components/core/Sidebar/SidebarContext.d.ts

@@ -1,6 +1,22 @@
 import React from 'react';
-import { SidebarContextValue } from './Sidebar.types';
+import { SidebarContextValue, SidebarDensity, SidebarProviderProps } from './Sidebar.types';
 export declare const useSidebarContext: () => SidebarContextValue | null;
+export declare const useSidebarDensity: () => SidebarDensity;
+export declare const SidebarDensityProvider: React.FC<{
+    children: React.ReactNode;
+    density?: SidebarDensity;
+}>;
+/**
+ * Derived collapsed-view state, shared by all Sidebar sub-components.
+ * Returns falsy defaults outside a Sidebar so it can be called unconditionally.
+ */
+export declare const useSidebarCollapsed: () => {
+    collapsed: boolean;
+    isMobile: boolean;
+    isMobileOpen: boolean;
+    /** Collapsed desktop rail — true only when collapsed AND not the mobile overlay */
+    isCollapsedView: boolean;
+};
 /** Accordion nav context: allows SidebarNav to coordinate which submenu is open */
 interface AccordionNavContextValue {
     openId: string | null;
@@ -12,20 +28,5 @@ export declare const AccordionNavProvider: React.FC<{
     children: React.ReactNode;
     accordion?: boolean;
 }>;
-interface SidebarProviderProps {
-    children: React.ReactNode;
-    defaultCollapsed?: boolean;
-    collapsed?: boolean;
-    onCollapsedChange?: (collapsed: boolean) => void;
-    mobileBreakpoint?: number;
-    mobileOpen?: boolean;
-    onMobileOpenChange?: (open: boolean) => void;
-    width?: {
-        expanded?: number;
-        collapsed?: number;
-    };
-    side?: 'left' | 'right';
-    variant?: 'sidebar' | 'floating' | 'inset';
-}
 export declare const SidebarProvider: React.FC<SidebarProviderProps>;
 export {};

package/dist/components/core/Sidebar/SidebarContext.js

@@ -1,12 +1,42 @@
 import { jsx, Fragment } from 'react/jsx-runtime';
 import { createContext, useContext, useState, useCallback, useMemo, useEffect } from 'react';
+import { useMediaQuery } from '../../../hooks/useMediaQuery.js';
 
 const SidebarContext = createContext(null);
+const SidebarDensityContext = createContext(null);
 const useSidebarContext = () => {
     const context = useContext(SidebarContext);
     // Return null if not in sidebar context (allows NavItem to work elsewhere)
     return context;
 };
+const useSidebarDensity = () => {
+    var _a;
+    const navDensity = useContext(SidebarDensityContext);
+    const sidebarContext = useContext(SidebarContext);
+    return (_a = navDensity !== null && navDensity !== void 0 ? navDensity : sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.density) !== null && _a !== void 0 ? _a : 'comfortable';
+};
+const SidebarDensityProvider = ({ children, density }) => {
+    if (!density)
+        return jsx(Fragment, { children: children });
+    return (jsx(SidebarDensityContext.Provider, { value: density, children: children }));
+};
+/**
+ * Derived collapsed-view state, shared by all Sidebar sub-components.
+ * Returns falsy defaults outside a Sidebar so it can be called unconditionally.
+ */
+const useSidebarCollapsed = () => {
+    var _a, _b, _c;
+    const context = useContext(SidebarContext);
+    const collapsed = (_a = context === null || context === void 0 ? void 0 : context.collapsed) !== null && _a !== void 0 ? _a : false;
+    const isMobile = (_b = context === null || context === void 0 ? void 0 : context.isMobile) !== null && _b !== void 0 ? _b : false;
+    return {
+        collapsed,
+        isMobile,
+        isMobileOpen: (_c = context === null || context === void 0 ? void 0 : context.isMobileOpen) !== null && _c !== void 0 ? _c : false,
+        /** Collapsed desktop rail — true only when collapsed AND not the mobile overlay */
+        isCollapsedView: collapsed && !isMobile,
+    };
+};
 const AccordionNavContext = createContext(null);
 const useAccordionNavContext = () => useContext(AccordionNavContext);
 const AccordionNavProvider = ({ children, accordion = false }) => {
@@ -22,26 +52,18 @@ const AccordionNavProvider = ({ children, accordion = false }) => {
         return jsx(Fragment, { children: children });
     return (jsx(AccordionNavContext.Provider, { value: value, children: children }));
 };
-const SidebarProvider = ({ children, defaultCollapsed = false, collapsed: controlledCollapsed, onCollapsedChange, mobileBreakpoint = 1024, mobileOpen: controlledMobileOpen, onMobileOpenChange, width = {}, side = 'left', variant = 'sidebar', }) => {
+const SidebarProvider = ({ children, defaultCollapsed = false, collapsed: controlledCollapsed, onCollapsedChange, mobileBreakpoint = 1024, mobileOpen: controlledMobileOpen, onMobileOpenChange, width = {}, side = 'left', variant = 'sidebar', density = 'comfortable', }) => {
     const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed);
     const [internalMobileOpen, setInternalMobileOpen] = useState(false);
-    const [isMobile, setIsMobile] = useState(false);
-    // Detect mobile breakpoint
+    // Detect mobile breakpoint via the shared (SSR-safe) media-query hook
+    const isMobile = useMediaQuery(`(max-width: ${mobileBreakpoint - 1}px)`);
+    // Close the mobile drawer when leaving the mobile breakpoint
     useEffect(() => {
-        if (typeof window === 'undefined')
-            return;
-        const mql = window.matchMedia(`(max-width: ${mobileBreakpoint - 1}px)`);
-        const handler = (e) => {
-            setIsMobile(e.matches);
-            if (!e.matches) {
-                setInternalMobileOpen(false);
-                onMobileOpenChange === null || onMobileOpenChange === void 0 ? void 0 : onMobileOpenChange(false);
-            }
-        };
-        handler(mql);
-        mql.addEventListener('change', handler);
-        return () => mql.removeEventListener('change', handler);
-    }, [mobileBreakpoint, onMobileOpenChange]);
+        if (!isMobile) {
+            setInternalMobileOpen(false);
+            onMobileOpenChange === null || onMobileOpenChange === void 0 ? void 0 : onMobileOpenChange(false);
+        }
+    }, [isMobile, onMobileOpenChange]);
     // Collapsed state
     const isCollapsedControlled = controlledCollapsed !== undefined;
     const collapsed = isCollapsedControlled ? controlledCollapsed : internalCollapsed;
@@ -76,15 +98,16 @@ const SidebarProvider = ({ children, defaultCollapsed = false, collapsed: contro
         toggleCollapsed,
         width: {
             expanded: width.expanded || 280,
-            collapsed: width.collapsed || 64,
+            collapsed: width.collapsed || 60,
         },
         side,
         variant,
+        density,
         isMobileOpen,
         setMobileOpen,
         isMobile,
-    }), [collapsed, setCollapsed, toggleCollapsed, width.expanded, width.collapsed, side, variant, isMobileOpen, setMobileOpen, isMobile]);
+    }), [collapsed, setCollapsed, toggleCollapsed, width.expanded, width.collapsed, side, variant, density, isMobileOpen, setMobileOpen, isMobile]);
     return (jsx(SidebarContext.Provider, { value: contextValue, children: children }));
 };
 
-export { AccordionNavProvider, SidebarProvider, useAccordionNavContext, useSidebarContext };
+export { AccordionNavProvider, SidebarDensityProvider, SidebarProvider, useAccordionNavContext, useSidebarCollapsed, useSidebarContext, useSidebarDensity };

package/dist/components/core/Sidebar/SidebarFooter.js

@@ -1,14 +1,12 @@
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
-import { useSidebarContext } from './SidebarContext.js';
+import { useSidebarCollapsed, useSidebarDensity } from './SidebarContext.js';
 
 const SidebarFooter = React__default.forwardRef(({ children, className, ...props }, ref) => {
-    const sidebarContext = useSidebarContext();
-    const collapsed = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.collapsed) || false;
-    const isMobile = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.isMobile) || false;
-    const isCollapsedView = collapsed && !isMobile;
-    return (jsx("div", { ref: ref, className: cn("flex-shrink-0 border-t border-[var(--color-border)] transition-all duration-200", isCollapsedView ? "p-2 flex justify-center" : "p-3", className), ...props, children: children }));
+    useSidebarCollapsed();
+    useSidebarDensity();
+    return (jsx("div", { ref: ref, className: cn("flex-shrink-0 border-t border-[var(--color-border)] p-2", className), ...props, children: children }));
 });
 SidebarFooter.displayName = "SidebarFooter";
 

package/dist/components/core/Sidebar/SidebarHeader.js

@@ -1,24 +1,27 @@
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default from 'react';
 import { XMarkIcon } from '@heroicons/react/24/outline';
 import { cn } from '../../../utils/cn.js';
-import { useSidebarContext } from './SidebarContext.js';
+import { useSidebarContext, useSidebarCollapsed } from './SidebarContext.js';
 import { SidebarToggle } from './SidebarToggle.js';
 import { Button } from '../Button/Button.js';
 
 const SidebarHeader = React__default.forwardRef(({ logo, showToggle = true, customToggle, children, className, ...props }, ref) => {
     const sidebarContext = useSidebarContext();
-    const collapsed = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.collapsed) || false;
-    const isMobile = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.isMobile) || false;
-    const isMobileOpen = (sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.isMobileOpen) || false;
+    const { isMobile, isMobileOpen } = useSidebarCollapsed();
     // If children are provided, use them instead of default layout
     if (children) {
         return (jsx("div", { ref: ref, className: cn("flex-shrink-0 border-b border-[var(--color-border)]", className), ...props, children: children }));
     }
-    const isCollapsedDesktop = collapsed && !isMobile;
-    return (jsx("div", { ref: ref, className: cn("flex items-center flex-shrink-0 h-14 border-b border-[var(--color-border)] overflow-hidden", isCollapsedDesktop ? "justify-center px-2" : "justify-between px-3", className), ...props, children: isCollapsedDesktop ? (
-        /* Collapsed: only show the toggle (expand) button centered */
-        showToggle && (customToggle || jsx(SidebarToggle, {}))) : (jsxs(Fragment, { children: [jsx("div", { className: "flex items-center min-w-0 flex-1", children: logo }), isMobile && isMobileOpen && (jsx(Button, { variant: "ghost", size: "sm", className: "size-7 p-0 text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)]", onClick: () => sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.setMobileOpen(false), "aria-label": "Close navigation", children: jsx(XMarkIcon, { className: "size-4" }) })), !isMobile && showToggle && (jsx("div", { className: "flex-shrink-0", children: customToggle || jsx(SidebarToggle, {}) }))] })) }));
+    return (jsxs("div", { ref: ref, className: cn("flex items-center flex-shrink-0 h-14 border-b border-[var(--color-border)] overflow-visible relative transition-[padding,background-color,border-color] duration-200 ease-[cubic-bezier(0.4,0,0.2,1)]", 
+        // Padding mirrors Sidebar.Content so the header logo sits on the
+        // same horizontal track as the NavItem rows below it. px-3 (12px)
+        // on the 60px collapsed rail leaves a 36px interior — a 32px logo
+        // (size-8) lands with 2px slack on each side; a 36px logo (size-9)
+        // fills the interior exactly. Left-pinned in both states (no
+        // `justify-*` toggle) so nothing jumps mid-animation. Same value
+        // for collapsed + expanded → no padding transition needed.
+        "px-3", className), ...props, children: [jsx("div", { className: "flex items-center min-w-0 flex-1", children: logo }), isMobile && isMobileOpen && (jsx(Button, { variant: "ghost", size: "sm", className: "size-7 p-0 text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)]", onClick: () => sidebarContext === null || sidebarContext === void 0 ? void 0 : sidebarContext.setMobileOpen(false), "aria-label": "Close navigation", children: jsx(XMarkIcon, { className: "size-4" }) })), !isMobile && showToggle && (customToggle || jsx(SidebarToggle, {}))] }));
 });
 SidebarHeader.displayName = "SidebarHeader";
 

package/dist/components/core/Sidebar/SidebarLogo.js

@@ -1,16 +1,47 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
 import { AnimatePresence, motion } from 'motion/react';
-import { useSidebarContext } from './SidebarContext.js';
+import { useSidebarCollapsed } from './SidebarContext.js';
 
-const SidebarLogo = React__default.forwardRef(({ icon, text, className, ...props }, ref) => {
+const SidebarLogo = React__default.forwardRef(({ expanded, collapsed, expandedSrc, collapsedSrc, expandedImageClassName, collapsedImageClassName, alt = "", icon, text, className, ...props }, ref) => {
     var _a, _b;
-    const context = useSidebarContext();
-    const collapsed = (_a = context === null || context === void 0 ? void 0 : context.collapsed) !== null && _a !== void 0 ? _a : false;
-    const isMobile = (_b = context === null || context === void 0 ? void 0 : context.isMobile) !== null && _b !== void 0 ? _b : false;
-    const isCollapsedView = collapsed && !isMobile;
-    return (jsxs("div", { ref: ref, className: cn("flex items-center gap-2 overflow-hidden", className), ...props, children: [jsx("div", { className: "flex-shrink-0", children: icon }), jsx(AnimatePresence, { initial: false, children: !isCollapsedView && text && (jsx(motion.div, { className: "overflow-hidden whitespace-nowrap", initial: { opacity: 0, x: -8 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: -8 }, transition: { duration: 0.15, ease: [0.4, 0, 0.2, 1] }, children: typeof text === "string" ? (jsx("span", { className: "text-lg font-bold text-[var(--color-text-primary)]", children: text })) : (text) }, "logo-text")) })] }));
+    const { isCollapsedView } = useSidebarCollapsed();
+    // Auto-render <img> for the src convenience API. ReactNode props still win
+    // (full control); src is the easy path for plain image/SVG assets.
+    //
+    // Defaults:
+    //  - Collapsed: size-9 (36px) square, object-cover — matches the nav icon
+    //    track so the collapsed logo aligns visually with NavItem rows below.
+    //  - Expanded: h-8 w-auto object-contain — typical wordmark sizing.
+    // Override via `collapsedImageClassName` / `expandedImageClassName`
+    // (tailwind-merge resolves conflicts in favor of the user's classes).
+    const expandedNode = expanded !== null && expanded !== void 0 ? expanded : (expandedSrc ? (jsx("img", { src: expandedSrc, alt: alt, className: cn("h-8 w-auto object-contain", expandedImageClassName) })) : undefined);
+    const collapsedNode = collapsed !== null && collapsed !== void 0 ? collapsed : (collapsedSrc ? (jsx("img", { src: collapsedSrc, alt: alt, className: cn("size-9 object-cover", collapsedImageClassName) })) : undefined);
+    // New API takes precedence: if the user passed `expanded`/`collapsed`
+    // (ReactNode) OR their `*Src` shortcuts, render those (cross-faded).
+    // Otherwise fall back to the legacy icon-plus-animated-text rendering so
+    // existing consumers keep working.
+    const hasNewApi = expandedNode !== undefined || collapsedNode !== undefined;
+    if (hasNewApi) {
+        // Resolve the logo for the current state, falling all the way back to
+        // the legacy `icon` so a partial new-API usage still has something to
+        // show. Per-state fallback: collapsed → expanded → icon, and vice versa.
+        const currentLogo = isCollapsedView
+            ? (_a = collapsedNode !== null && collapsedNode !== void 0 ? collapsedNode : expandedNode) !== null && _a !== void 0 ? _a : icon
+            : (_b = expandedNode !== null && expandedNode !== void 0 ? expandedNode : collapsedNode) !== null && _b !== void 0 ? _b : icon;
+        return (jsx("div", { ref: ref, 
+            // No `overflow-hidden`: would clip wide logos in collapsed mode.
+            // Sidebar itself is `overflow-visible`.
+            className: cn("flex items-center", className), ...props, children: jsx(AnimatePresence, { mode: "wait", initial: false, children: jsx(motion.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: 0.15, ease: [0.4, 0, 0.2, 1] }, className: "flex items-center", children: currentLogo }, isCollapsedView ? "collapsed" : "expanded") }) }));
+    }
+    // Legacy API: icon + animated text.
+    return (jsxs("div", { ref: ref, 
+        // No `overflow-hidden` here — that would clip the icon when the
+        // sidebar is collapsed and horizontal space is tight. The text
+        // collapse animation owns its own `overflow-hidden` on the motion.div
+        // below, which is the only place it's actually needed.
+        className: cn("flex items-center gap-2", className), ...props, children: [jsx("div", { className: "flex-shrink-0", children: icon }), jsx(AnimatePresence, { initial: false, children: !isCollapsedView && text && (jsx(motion.div, { className: "overflow-hidden whitespace-nowrap", initial: { opacity: 0, x: -8 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: -8 }, transition: { duration: 0.15, ease: [0.4, 0, 0.2, 1] }, children: typeof text === "string" ? (jsx("span", { className: "text-base font-semibold tracking-tight text-[var(--color-text-primary)]", children: text })) : (text) }, "logo-text")) })] }));
 });
 SidebarLogo.displayName = "SidebarLogo";
 

package/dist/components/core/Sidebar/SidebarNav.js

@@ -1,10 +1,11 @@
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
-import { AccordionNavProvider } from './SidebarContext.js';
+import { useSidebarDensity, SidebarDensityProvider, AccordionNavProvider } from './SidebarContext.js';
 
-const SidebarNav = React__default.forwardRef(({ accordion = false, children, className, ...props }, ref) => {
-    return (jsx("nav", { ref: ref, className: cn('flex-1 space-y-1 p-4', className), role: "navigation", ...props, children: jsx(AccordionNavProvider, { accordion: accordion, children: children }) }));
+const SidebarNav = React__default.forwardRef(({ accordion = false, density, children, className, ...props }, ref) => {
+    const resolvedDensity = density !== null && density !== void 0 ? density : useSidebarDensity();
+    return (jsx("nav", { ref: ref, className: cn('flex-1', resolvedDensity === 'compact' ? 'space-y-0.5' : 'space-y-1', className), "aria-label": "Sidebar", "data-density": resolvedDensity, ...props, children: jsx(SidebarDensityProvider, { density: density, children: jsx(AccordionNavProvider, { accordion: accordion, children: children }) }) }));
 });
 SidebarNav.displayName = 'SidebarNav';