xertica-ui 2.1.2 → 2.1.3

package/components/layout/sidebar/sidebar.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useRef, useEffect } from "react";
+import React, { useState, useRef, useEffect, createContext, useContext } from "react";
 import { motion, AnimatePresence } from "framer-motion";
 import {
   Menu,
@@ -31,10 +31,12 @@ import { XerticaLogo } from '../../brand/xertica-logo';
 import { XerticaXLogo } from '../../brand/xertica-xlogo';
 import { Button } from '../../ui/button';
 import { useOptionalLayout } from "../../../contexts/LayoutContext";
+import { useSidebar } from "./use-sidebar";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal tooltip styled for the sidebar
+// ─────────────────────────────────────────────────────────────────────────────
 
-/**
- * Tooltip content styled for the sidebar.
- */
 function SidebarTooltipContent({
   className,
   sideOffset = 0,
@@ -61,7 +63,10 @@ function SidebarTooltipContent({
   );
 }
 
-// Interface for Route Config (copied/imported type)
+// ─────────────────────────────────────────────────────────────────────────────
+// Public interfaces
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
  * Contextual action menu item for routes and groups.
  */
@@ -98,7 +103,7 @@ export interface RouteConfig {
   children?: RouteConfig[];
 }
 
-interface NavigationItem {
+export interface NavigationItem {
   path: string;
   label: string;
   icon?: any;
@@ -159,9 +164,9 @@ export interface SidebarProps {
   /** Callback to toggle expansion state (defaults to LayoutContext toggle if available) */
   onToggle?: () => void;
   /** Authenticated user info */
-  user?: { 
-    name?: string; 
-    email?: string; 
+  user?: {
+    name?: string;
+    email?: string;
     avatar?: string;
   } | null;
   /** Logout callback */
@@ -194,73 +199,173 @@ export interface SidebarProps {
   width?: number;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Compound Component Context
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface SidebarContextValue {
+  expanded: boolean;
+  isMobileViewport: boolean;
+  onToggle: () => void;
+  navigate: (path: string) => void;
+  location: { pathname: string };
+  width: number;
+}
+
+const SidebarContext = createContext<SidebarContextValue | null>(null);
+
+function useSidebarContext() {
+  const ctx = useContext(SidebarContext);
+  if (!ctx) {
+    throw new Error("Sidebar compound components must be used within <Sidebar.Root>");
+  }
+  return ctx;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Compound Sub-components
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
- * Primary navigation sidebar component.
- *
- * @description
- * Manages desktop/mobile responsive navigation rendering with two variants:
- * - `"default"` — simple flat or grouped route list.
- * - `"assistant"` — advanced variant with fixed areas, search, filters, and grouped navigation.
+ * Root container for the Sidebar. Provides context to all sub-components.
+ * Use this when building a fully custom sidebar layout.
  *
- * This component is autonomous: it works out-of-the-box using local state or
- * integrates automatically with `LayoutContext` if wrapped in `LayoutProvider`.
- *
- * @ai-rules
- * 1. NEVER recreate the sidebar with raw Tailwind classes — always use this component.
- * 2. Use `variant="assistant"` for AI/tool sidebars; use `variant="default"` for standard navigation.
- * 3. Supports `Ctrl+B` keyboard shortcut automatically via `LayoutProvider`.
+ * @example
+ * <Sidebar.Root expanded={expanded} onToggle={toggle} width={280}>
+ *   <Sidebar.Header logo={<MyLogo />} />
+ *   <Sidebar.Nav navigationGroups={groups} />
+ *   <Sidebar.Footer user={user} onLogout={logout} />
+ * </Sidebar.Root>
  */
-export function Sidebar({
+function SidebarRoot({
   expanded: expandedProp,
   onToggle: onToggleProp,
-  user,
-  onLogout = () => {},
-  onSettingsClick,
-  location: locationProp,
   navigate: navigateProp,
-  routes,
-  logo,
-  logoCollapsed,
-  variant = "default",
-  fixedArea,
-  search,
-  navigationGroups = [],
-  footer,
-  showFooter,
+  location: locationProp,
   width: widthProp,
-}: SidebarProps) {
+  children,
+  className,
+}: {
+  expanded?: boolean;
+  onToggle?: () => void;
+  navigate?: (path: string) => void;
+  location?: { pathname: string };
+  width?: number;
+  children: React.ReactNode;
+  className?: string;
+}) {
   const layoutContext = useOptionalLayout();
-
   const [localExpanded, setLocalExpanded] = useState(false);
   const [isMobileViewport, setIsMobileViewport] = useState(false);
-  
+
   const expanded = expandedProp !== undefined ? expandedProp : (layoutContext?.sidebarExpanded ?? localExpanded);
   const onToggle = onToggleProp || (layoutContext?.toggleSidebar || (() => setLocalExpanded(prev => !prev)));
-  const width = widthProp !== undefined ? widthProp : (layoutContext?.sidebarWidth ?? 256);
-  
-  // Safe navigation fallback
+  const width = widthProp !== undefined ? widthProp : (layoutContext?.sidebarWidth ?? 280);
   const navigate = navigateProp || ((path: string) => {
     if (typeof window !== 'undefined') window.location.href = path;
   });
-
-  // Safe location fallback
   const location = locationProp || (typeof window !== 'undefined' ? window.location : { pathname: '/' });
-  const {
-    showUser = true,
-    showSettings = true,
-    showLogout = true,
-  } = footer || {};
 
-  const displayFooter = showFooter !== undefined ? showFooter : variant === "default";
+  useEffect(() => {
+    const checkViewport = () => setIsMobileViewport(window.innerWidth < 768);
+    checkViewport();
+    window.addEventListener("resize", checkViewport);
+    return () => window.removeEventListener("resize", checkViewport);
+  }, []);
+
+  return (
+    <SidebarContext.Provider value={{ expanded, isMobileViewport, onToggle, navigate, location, width }}>
+      <TooltipProvider delayDuration={300}>
+        <style>{`
+          @media (max-width: 767px) {
+            [style*="padding-left"].flex-1,
+            [style*="paddingLeft"].flex-1 {
+              padding-left: 0 !important;
+            }
+          }
+        `}</style>
+        <div
+          className={cn(
+            "bg-sidebar text-sidebar-foreground transition-all duration-300 ease-in-out flex flex-col z-50",
+            expanded
+              ? "fixed inset-0 md:fixed md:inset-y-0 md:left-0"
+              : "fixed inset-y-0 left-0 w-20 -translate-x-full md:translate-x-0",
+            className
+          )}
+          style={expanded && !isMobileViewport ? { width: `${width}px` } : undefined}
+        >
+          {children}
+        </div>
+      </TooltipProvider>
+    </SidebarContext.Provider>
+  );
+}
+
+/**
+ * Toggle button + logo header area for the Sidebar.
+ */
+function SidebarHeader({
+  logo,
+  logoCollapsed,
+}: {
+  logo?: React.ReactNode;
+  logoCollapsed?: React.ReactNode;
+}) {
+  const { expanded, onToggle } = useSidebarContext();
+
+  return (
+    <>
+      {/* Menu Toggle Button */}
+      <div className="flex-shrink-0 p-[14px] pt-[13px] pr-[14px] pb-[12px] pl-[14px]">
+        <button
+          onClick={onToggle}
+          className="w-full h-10 flex items-center gap-3 px-3 justify-center rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+          aria-label={expanded ? "Recolher menu" : "Expandir menu"}
+        >
+          {expanded ? (
+            <ArrowLeft className="w-5 h-5" />
+          ) : (
+            <Menu className="w-5 h-5" />
+          )}
+        </button>
+      </div>
+
+      {/* Logo */}
+      <div className="flex-shrink-0 px-4 py-4">
+        <div className="flex items-center h-10 justify-center">
+          <div className="flex items-center justify-center flex-shrink-0">
+            {expanded ? (
+              logo || <XerticaLogo className="h-5 w-auto" variant="white" />
+            ) : (
+              logoCollapsed || <XerticaXLogo className="h-5 w-auto" variant="white" />
+            )}
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}
+
+/**
+ * Navigation area for the Sidebar (default variant).
+ * Renders grouped or flat navigation items with overflow handling.
+ */
+function SidebarNav({
+  navigationGroups = [],
+  routes = [],
+  variant = "default",
+}: {
+  navigationGroups?: RouteGroup[];
+  routes?: RouteConfig[];
+  variant?: "default" | "assistant";
+}) {
+  const { expanded, navigate, location, onToggle } = useSidebarContext();
   const navRef = useRef<HTMLDivElement>(null);
   const [localActiveItem, setLocalActiveItem] = useState<string | null>(null);
   const [hasOverflow, setHasOverflow] = useState(false);
   const [visibleItems, setVisibleItems] = useState<NavigationItem[]>([]);
   const [overflowItems, setOverflowItems] = useState<NavigationItem[]>([]);
-  const [openSubmenu, setOpenSubmenu] = useState<string | null>(null);
-  const [isFilterOpen, setIsFilterOpen] = useState(false);
 
-  // Label translations map
   const labelTranslations: Record<string, string> = {
     home: "Início",
     dashboard: "Painel",
@@ -274,21 +379,14 @@ export function Sidebar({
     children: route.children,
   }));
 
-  const isSettingsActive = location.pathname === "/settings";
-
-  // Detect vertical overflow to handle extra items
   useEffect(() => {
     if (typeof window === "undefined") return;
     const checkOverflow = () => {
       if (!navRef.current) return;
       if (variant === "assistant") return;
-
-      setIsMobileViewport(window.innerWidth < 768);
-
       const navHeight = navRef.current.clientHeight;
-      const itemHeight = 44; // h-10 + gap
+      const itemHeight = 44;
       const maxVisibleItems = Math.floor(navHeight / itemHeight);
-
       if (navigationItems.length > maxVisibleItems) {
         setHasOverflow(true);
         setVisibleItems(navigationItems.slice(0, maxVisibleItems - 1));
@@ -299,17 +397,14 @@ export function Sidebar({
         setOverflowItems([]);
       }
     };
-
     checkOverflow();
     window.addEventListener("resize", checkOverflow);
     return () => window.removeEventListener("resize", checkOverflow);
-  }, [navigationItems.length]);
+  }, [navigationItems.length, variant]);
 
   const handleNavigate = (path: string) => {
     setLocalActiveItem(path);
     navigate(path);
-    setOpenSubmenu(null);
-    // Close menu on mobile after navigation
     if (typeof window !== "undefined" && window.innerWidth < 768) {
       onToggle();
     }
@@ -324,10 +419,70 @@ export function Sidebar({
     actions: route.actions,
   });
 
+  const renderActionItems = (actions: ActionMenuItem[]): React.ReactNode => {
+    return actions.map((action, idx) => {
+      const Icon = action.icon;
+      if (action.children && action.children.length > 0) {
+        return (
+          <DropdownMenuSub key={idx}>
+            <DropdownMenuSubTrigger>
+              {Icon && <Icon className="mr-2 h-4 w-4" />}
+              <span>{action.label}</span>
+            </DropdownMenuSubTrigger>
+            <DropdownMenuPortal>
+              <DropdownMenuSubContent className="w-48 bg-popover border-border">
+                {renderActionItems(action.children)}
+              </DropdownMenuSubContent>
+            </DropdownMenuPortal>
+          </DropdownMenuSub>
+        );
+      }
+      return (
+        <DropdownMenuItem
+          key={idx}
+          className={cn(
+            "flex items-center gap-2",
+            action.variant === "destructive" ? "text-destructive focus:text-destructive" : ""
+          )}
+          onClick={(e) => {
+            e.stopPropagation();
+            action.onClick?.(null);
+          }}
+        >
+          {Icon && <Icon className="h-4 w-4 flex-shrink-0" />}
+          <span>{action.label}</span>
+        </DropdownMenuItem>
+      );
+    });
+  };
+
+  const renderAssistantActionMenu = (actions?: ActionMenuItem[], isHeader: boolean = false) => {
+    if (!actions || actions.length === 0) return null;
+    return (
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button
+            variant="ghost"
+            size="icon"
+            className={cn(
+              "h-8 w-8 text-sidebar-foreground/80 hover:bg-sidebar-foreground/20 hover:text-sidebar-foreground rounded-full transition-all",
+              !isHeader && "opacity-0 group-hover/item:opacity-100"
+            )}
+            aria-label="Mais opções"
+          >
+            <MoreVertical className="h-4 w-4" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-48 bg-popover border-border p-1">
+          {renderActionItems(actions)}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    );
+  };
+
   const renderDefaultItem = (item: NavigationItem) => {
     const Icon = item.icon;
     const hasChildren = item.children && item.children.length > 0;
-
     const activeClass = item.active
       ? "bg-sidebar-foreground/15 text-sidebar-foreground shadow-sm"
       : "text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground";
@@ -408,7 +563,6 @@ export function Sidebar({
 
   const renderDefaultGroup = (group: RouteGroup) => {
     const GroupIcon = group.icon;
-
     if (!expanded) {
       return (
         <div key={group.id} className="space-y-1">
@@ -416,7 +570,6 @@ export function Sidebar({
         </div>
       );
     }
-
     return (
       <div key={group.id}>
         {(group.label || GroupIcon) && (
@@ -440,70 +593,6 @@ export function Sidebar({
     );
   };
 
-  const renderActionItems = (actions: ActionMenuItem[]) => {
-    return actions.map((action, idx) => {
-      const Icon = action.icon;
-
-      if (action.children && action.children.length > 0) {
-        return (
-          <DropdownMenuSub key={idx}>
-            <DropdownMenuSubTrigger>
-              {Icon && <Icon className="mr-2 h-4 w-4" />}
-              <span>{action.label}</span>
-            </DropdownMenuSubTrigger>
-            <DropdownMenuPortal>
-              <DropdownMenuSubContent className="w-48 bg-popover border-border">
-                {renderActionItems(action.children)}
-              </DropdownMenuSubContent>
-            </DropdownMenuPortal>
-          </DropdownMenuSub>
-        );
-      }
-
-      return (
-        <DropdownMenuItem
-          key={idx}
-          className={cn(
-            "flex items-center gap-2",
-            action.variant === "destructive" ? "text-destructive focus:text-destructive" : ""
-          )}
-          onClick={(e) => {
-            e.stopPropagation();
-            action.onClick?.(null);
-          }}
-        >
-          {Icon && <Icon className="h-4 w-4 flex-shrink-0" />}
-          <span>{action.label}</span>
-        </DropdownMenuItem>
-      );
-    });
-  };
-
-  const renderAssistantActionMenu = (actions?: ActionMenuItem[], isHeader: boolean = false) => {
-    if (!actions || actions.length === 0) return null;
-
-    return (
-      <DropdownMenu>
-        <DropdownMenuTrigger asChild>
-          <Button
-            variant="ghost"
-            size="icon"
-            className={cn(
-              "h-8 w-8 text-sidebar-foreground/80 hover:bg-sidebar-foreground/20 hover:text-sidebar-foreground rounded-full transition-all",
-              !isHeader && "opacity-0 group-hover/item:opacity-100"
-            )}
-            aria-label="Mais opções"
-          >
-            <MoreVertical className="h-4 w-4" />
-          </Button>
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="end" className="w-48 bg-popover border-border p-1">
-          {renderActionItems(actions)}
-        </DropdownMenuContent>
-      </DropdownMenu>
-    );
-  };
-
   const renderAssistantGroup = (group: RouteGroup) => {
     const isAnyItemActive = group.items.some(item =>
       location.pathname === item.path || location.pathname.startsWith(item.path + "/")
@@ -512,18 +601,12 @@ export function Sidebar({
 
     if (!expanded) {
       if (!GroupIcon) return null;
-
       return (
         <div key={group.id} className="py-2 flex justify-center">
           <Tooltip>
             <TooltipTrigger asChild>
               <button
-                onClick={() => {
-                  // If we click a category when closed, we could either expand 
-                  // or navigate to the first item. 
-                  // For now, let's just trigger the onToggle to show items.
-                  onToggle();
-                }}
+                onClick={() => onToggle()}
                 aria-label={group.label}
                 className={cn(
                   "h-10 w-10 flex items-center justify-center rounded-[var(--radius-button)] transition-all duration-200",
@@ -563,7 +646,6 @@ export function Sidebar({
             const isRouteActive = location.pathname === item.path || location.pathname.startsWith(item.path + "/");
             const isActive = isRouteActive || localActiveItem === item.path;
             const Icon = item.icon;
-
             return (
               <div
                 key={item.path}
@@ -596,354 +678,411 @@ export function Sidebar({
     );
   };
 
-  return (
-    <TooltipProvider delayDuration={300}>
-      {/* Mobile Responsiveness Override embedded in Sidebar */}
-      <style>{`
-        @media (max-width: 767px) {
-          [style*="padding-left"].flex-1,
-          [style*="paddingLeft"].flex-1 {
-            padding-left: 0 !important;
-          }
-        }
-      `}</style>
-      {/* Sidebar */}
-      <div
-        className={`bg-sidebar text-sidebar-foreground transition-all duration-300 ease-in-out flex flex-col z-50 ${expanded
-          ? "fixed inset-0 md:fixed md:inset-y-0 md:left-0"
-          : "fixed inset-y-0 left-0 w-20 -translate-x-full md:translate-x-0"
-          }`}
-        style={expanded && !isMobileViewport ? { width: `${width}px` } : undefined}
-      >
-        {/* Menu Toggle Button */}
-        <div className="flex-shrink-0 p-[14px] pt-[13px] pr-[14px] pb-[12px] pl-[14px]">
-          <button
-            onClick={onToggle}
-            className="w-full h-10 flex items-center gap-3 px-3 justify-center rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
-            aria-label={expanded ? "Recolher menu" : "Expandir menu"}
-          >
-            {expanded ? (
-              <ArrowLeft className="w-5 h-5" />
-            ) : (
-              <Menu className="w-5 h-5" />
-            )}
-          </button>
-        </div>
+  if (variant === "assistant") {
+    return (
+      <div className="flex-1 min-h-0 overflow-hidden">
+        <ScrollArea className="h-full px-4">
+          {navigationGroups.map(group => renderAssistantGroup(group))}
+        </ScrollArea>
+      </div>
+    );
+  }
 
-        {/* Logo */}
-        <div className="flex-shrink-0 px-4 py-4">
-          <div
-            className={`flex items-center h-10 ${expanded ? "justify-center" : "justify-center"}`}
-          >
-            <div className="flex items-center justify-center flex-shrink-0">
-              {expanded ? (
-                logo || (
-                  <XerticaLogo
-                    className="h-5 w-auto"
-                    variant="white"
-                  />
-                )
-              ) : (
-                logoCollapsed || (
-                  <XerticaXLogo
-                    className="h-5 w-auto"
-                    variant="white"
-                  />
-                )
-              )}
-            </div>
+  return (
+    <div className="flex-1 min-h-0 overflow-hidden">
+      <nav className="h-full px-4 py-4 overflow-hidden" ref={navRef}>
+        {navigationGroups && navigationGroups.length > 0 ? (
+          <div className="space-y-3">
+            {navigationGroups.map((group) => (
+              <React.Fragment key={group.id}>
+                {renderDefaultGroup(group)}
+              </React.Fragment>
+            ))}
           </div>
-        </div>
-
-        {/* Assistant-specific Header (Search/Fixed Area) - Always fixed when present */}
-        {variant === "assistant" && ((fixedArea && fixedArea.show) || (search && search.show)) && (
-          <div className="flex-shrink-0 px-4 pb-4 space-y-4 border-b border-sidebar-border/30 mb-2">
-            {fixedArea?.show && fixedArea.content && expanded && (
-              <div className="animate-in fade-in slide-in-from-top-1 duration-300">
-                {fixedArea.content}
-              </div>
+        ) : (
+          <div className="space-y-1">
+            {(hasOverflow ? visibleItems : navigationItems).map((item) =>
+              renderDefaultItem(item)
             )}
-            {search?.show && expanded && (
-              <>
-                <div className="flex items-center gap-2">
-                  <div className="relative flex-1">
-                    <SearchIcon className="absolute left-2.5 top-1/2 -translate-y-1/2 h-4 w-4 text-sidebar-foreground/50" />
-                    <Input
-                      type="text"
-                      placeholder={search.placeholder || "Buscar..."}
-                      aria-label={search.placeholder || "Buscar..."}
-                      value={search.value}
-                      onChange={(e) => search.onChange?.(e.target.value)}
-                      className="w-full h-9 bg-sidebar-foreground/10 border-sidebar-border text-sidebar-foreground placeholder:text-sidebar-foreground/50 pl-9 focus-visible:ring-1 focus-visible:ring-sidebar-foreground/30 focus-visible:ring-offset-0"
-                    />
+            {hasOverflow && (
+              <Popover>
+                <PopoverTrigger asChild>
+                  <button
+                    className={
+                      expanded
+                        ? "w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+                        : "w-full h-10 flex items-center justify-center px-0 rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+                    }
+                    aria-label="Mais opções"
+                  >
+                    <MoreVertical className="w-5 h-5 flex-shrink-0" />
+                    {expanded && (
+                      <span className="truncate text-sidebar-foreground">Mais opções</span>
+                    )}
+                  </button>
+                </PopoverTrigger>
+                <PopoverContent
+                  side="right"
+                  align="start"
+                  className="w-56 p-2 bg-popover border border-border rounded-[var(--radius-card)] shadow-lg"
+                  sideOffset={8}
+                >
+                  <div className="space-y-1">
+                    {overflowItems.map((item) => {
+                      const Icon = item.icon;
+                      return (
+                        <button
+                          key={item.path}
+                          onClick={() => handleNavigate(item.path)}
+                          className="w-full h-9 flex items-center gap-2 px-3 rounded-[var(--radius-button)] transition-all duration-200 text-popover-foreground/80 hover:bg-accent hover:text-accent-foreground text-left"
+                        >
+                          {Icon && <Icon className="w-4 h-4 flex-shrink-0" />}
+                          <span className="truncate">{item.label}</span>
+                        </button>
+                      );
+                    })}
                   </div>
-                  {search.filter?.show && search.filter.content && (
-                    <Button
-                      variant="ghost"
-                      size="icon"
-                      onClick={() => setIsFilterOpen(!isFilterOpen)}
-                      className={cn(
-                        "h-9 w-9 text-sidebar-foreground transition-all duration-200",
-                        isFilterOpen ? "bg-sidebar-foreground/20" : "hover:bg-sidebar-foreground/15"
-                      )}
-                      aria-label={isFilterOpen ? "Fechar filtros" : "Abrir filtros"}
-                    >
-                      {search.filter.icon || <Filter className="h-4 w-4" />}
-                    </Button>
-                  )}
-                </div>
-
-                <AnimatePresence>
-                  {isFilterOpen && search.filter?.show && search.filter.content && (
-                    <motion.div
-                      initial={{ height: 0, opacity: 0 }}
-                      animate={{ height: "auto", opacity: 1 }}
-                      exit={{ height: 0, opacity: 0 }}
-                      transition={{ duration: 0.2 }}
-                      className="overflow-hidden"
-                    >
-                      <div className="pt-2 border-t border-sidebar-border/20">
-                        {search.filter.content}
-                      </div>
-                    </motion.div>
-                  )}
-                </AnimatePresence>
-              </>
-            )}
-            {(!expanded && (fixedArea?.show || search?.show)) && (
-              <div className="flex flex-col items-center gap-4 py-2">
-                {fixedArea?.show && fixedArea.icon && (
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <button
-                        onClick={() => fixedArea.onClick?.()}
-                        className="h-10 w-10 flex items-center justify-center rounded-[var(--radius-button)] bg-primary text-primary-foreground shadow-sm hover:bg-primary/90 transition-all"
-                        aria-label="Nova Conversa"
-                      >
-                        {React.isValidElement(fixedArea.icon) ? fixedArea.icon : <fixedArea.icon className="h-5 w-5" />}
-                      </button>
-                    </TooltipTrigger>
-                    <SidebarTooltipContent side="right">Nova Conversa</SidebarTooltipContent>
-                  </Tooltip>
-                )}
-                {search?.show && (
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <button
-                        className="h-10 w-10 flex items-center justify-center rounded-[var(--radius-button)] text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
-                        aria-label="Buscar"
-                      >
-                        <SearchIcon className="h-5 w-5" />
-                      </button>
-                    </TooltipTrigger>
-                    <SidebarTooltipContent side="right">Buscar</SidebarTooltipContent>
-                  </Tooltip>
-                )}
-              </div>
+                </PopoverContent>
+              </Popover>
             )}
           </div>
         )}
+      </nav>
+    </div>
+  );
+}
 
-        {/* Main Content Area - Scrollable */}
-        <div className="flex-1 min-h-0 overflow-hidden">
-          {variant === "default" ? (
-            <nav className="h-full px-4 py-4 overflow-hidden" ref={navRef}>
-              {navigationGroups && navigationGroups.length > 0 ? (
-                <div className="space-y-3">
-                  {navigationGroups.map((group, idx) => (
-                    <React.Fragment key={group.id}>
-    {renderDefaultGroup(group)}
-                    </React.Fragment>
-                  ))}
-                </div>
-              ) : (
-                <div className="space-y-1">
-                  {(hasOverflow ? visibleItems : navigationItems).map((item) =>
-                    renderDefaultItem(item)
-                  )}
+/**
+ * Assistant-specific search + fixed area header for the Sidebar.
+ */
+function SidebarSearch({
+  fixedArea,
+  search,
+}: {
+  fixedArea?: SidebarFixedAreaConfig;
+  search?: SidebarSearchConfig;
+}) {
+  const { expanded } = useSidebarContext();
+  const [isFilterOpen, setIsFilterOpen] = useState(false);
 
-                  {hasOverflow && (
-                    <Popover>
-                      <PopoverTrigger asChild>
-                        <button
-                          className={
-                            expanded
-                              ? "w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
-                              : "w-full h-10 flex items-center justify-center px-0 rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
-                          }
-                          aria-label="Mais opções"
-                        >
-                          <MoreVertical className="w-5 h-5 flex-shrink-0" />
-                          {expanded && (
-                            <span className="truncate text-sidebar-foreground">
-                              Mais opções
-                            </span>
-                          )}
-                        </button>
-                      </PopoverTrigger>
-                      <PopoverContent
-                        side="right"
-                        align="start"
-                        className="w-56 p-2 bg-popover border border-border rounded-[var(--radius-card)] shadow-lg"
-                        sideOffset={8}
-                      >
-                        <div className="space-y-1">
-                          {overflowItems.map((item) => {
-                            const Icon = item.icon;
-                            return (
-                              <button
-                                key={item.path}
-                                onClick={() => handleNavigate(item.path)}
-                                className="w-full h-9 flex items-center gap-2 px-3 rounded-[var(--radius-button)] transition-all duration-200 text-popover-foreground/80 hover:bg-accent hover:text-accent-foreground text-left"
-                              >
-                                {Icon && <Icon className="w-4 h-4 flex-shrink-0" />}
-                                <span className="truncate">{item.label}</span>
-                              </button>
-                            );
-                          })}
-                        </div>
-                      </PopoverContent>
-                    </Popover>
-                  )}
-                </div>
-              )}
-            </nav>
-          ) : (
-            <ScrollArea className="h-full px-4">
-              {navigationGroups.map(group => renderAssistantGroup(group))}
-            </ScrollArea>
-          )}
-        </div>
+  if (!((fixedArea && fixedArea.show) || (search && search.show))) return null;
 
-        {/* Sidebar Footer - User settings */}
-        {displayFooter && (showUser || showSettings || showLogout) && (
-          <div className="flex-shrink-0 p-4 space-y-2">
-            {/* User avatar */}
-            {showUser && (
-              !expanded ? (
-                <Tooltip>
-                  <TooltipTrigger asChild>
-                    <button
-                      className="w-full h-10 flex items-center justify-center px-0 rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
-                      aria-label="Perfil do usuário"
-                    >
-                      <Avatar className="w-7 h-7 flex-shrink-0">
-                        <AvatarImage src={user?.avatar} alt={user?.name || "User"} />
-                        <AvatarFallback className="bg-sidebar-foreground/15 text-sidebar-foreground text-xs">
-                          {user?.name ? user.name.charAt(0).toUpperCase() : "U"}
-                        </AvatarFallback>
-                      </Avatar>
-                    </button>
-                  </TooltipTrigger>
-                  <SidebarTooltipContent side="right" sideOffset={0}>
-                    <p>{user?.name || "Perfil"}</p>
-                  </SidebarTooltipContent>
-                </Tooltip>
-              ) : (
-                <button
-                  className="w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
-                >
-                  <Avatar className="w-7 h-7 flex-shrink-0">
-                    <AvatarImage src={user?.avatar} alt={user?.name || "User"} />
-                    <AvatarFallback className="bg-sidebar-foreground/15 text-sidebar-foreground text-xs">
-                      {user?.name ? user.name.charAt(0).toUpperCase() : "U"}
-                    </AvatarFallback>
-                  </Avatar>
-                  <span className="text-sidebar-foreground truncate">
-                    {user?.name || "Perfil"}
-                  </span>
-                </button>
-              )
+  return (
+    <div className="flex-shrink-0 px-4 pb-4 space-y-4 border-b border-sidebar-border/30 mb-2">
+      {fixedArea?.show && fixedArea.content && expanded && (
+        <div className="animate-in fade-in slide-in-from-top-1 duration-300">
+          {fixedArea.content}
+        </div>
+      )}
+      {search?.show && expanded && (
+        <>
+          <div className="flex items-center gap-2">
+            <div className="relative flex-1">
+              <SearchIcon className="absolute left-2.5 top-1/2 -translate-y-1/2 h-4 w-4 text-sidebar-foreground/50" />
+              <Input
+                type="text"
+                placeholder={search.placeholder || "Buscar..."}
+                aria-label={search.placeholder || "Buscar..."}
+                value={search.value}
+                onChange={(e) => search.onChange?.(e.target.value)}
+                className="w-full h-9 bg-sidebar-foreground/10 border-sidebar-border text-sidebar-foreground placeholder:text-sidebar-foreground/50 pl-9 focus-visible:ring-1 focus-visible:ring-sidebar-foreground/30 focus-visible:ring-offset-0"
+              />
+            </div>
+            {search.filter?.show && search.filter.content && (
+              <Button
+                variant="ghost"
+                size="icon"
+                onClick={() => setIsFilterOpen(!isFilterOpen)}
+                className={cn(
+                  "h-9 w-9 text-sidebar-foreground transition-all duration-200",
+                  isFilterOpen ? "bg-sidebar-foreground/20" : "hover:bg-sidebar-foreground/15"
+                )}
+                aria-label={isFilterOpen ? "Fechar filtros" : "Abrir filtros"}
+              >
+                {search.filter.icon || <Filter className="h-4 w-4" />}
+              </Button>
             )}
-
-            {/* Settings Button */}
-            {showSettings && (
-              !expanded ? (
-                <Tooltip>
-                  <TooltipTrigger asChild>
-                    <button
-                      onClick={() => {
-                        if (onSettingsClick) {
-                          onSettingsClick();
-                        } else {
-                          navigate("/settings");
-                        }
-                        if (typeof window !== "undefined" && window.innerWidth < 768) {
-                          onToggle();
-                        }
-                      }}
-                      className={"w-full h-10 flex items-center justify-center px-0 rounded-[var(--radius-button)] transition-all duration-200 " +
-                        (isSettingsActive
-                          ? "bg-sidebar-foreground/15 text-sidebar-foreground shadow-sm"
-                          : "text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground")
-                      }
-                      aria-label="Configurações"
-                    >
-                      <Settings className="w-5 h-5 flex-shrink-0" />
-                    </button>
-                  </TooltipTrigger>
-                  <SidebarTooltipContent side="right" sideOffset={0}>
-                    <p>Configurações</p>
-                  </SidebarTooltipContent>
-                </Tooltip>
-              ) : (
+          </div>
+          <AnimatePresence>
+            {isFilterOpen && search.filter?.show && search.filter.content && (
+              <motion.div
+                initial={{ height: 0, opacity: 0 }}
+                animate={{ height: "auto", opacity: 1 }}
+                exit={{ height: 0, opacity: 0 }}
+                transition={{ duration: 0.2 }}
+                className="overflow-hidden"
+              >
+                <div className="pt-2 border-t border-sidebar-border/20">
+                  {search.filter.content}
+                </div>
+              </motion.div>
+            )}
+          </AnimatePresence>
+        </>
+      )}
+      {(!expanded && (fixedArea?.show || search?.show)) && (
+        <div className="flex flex-col items-center gap-4 py-2">
+          {fixedArea?.show && fixedArea.icon && (
+            <Tooltip>
+              <TooltipTrigger asChild>
                 <button
-                  onClick={() => {
-                    if (onSettingsClick) {
-                      onSettingsClick();
-                    } else {
-                      navigate("/settings");
-                    }
-                    if (typeof window !== "undefined" && window.innerWidth < 768) {
-                      onToggle();
-                    }
-                  }}
-                  className={
-                    isSettingsActive
-                      ? "w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200 bg-sidebar-foreground/15 text-sidebar-foreground shadow-sm"
-                      : "w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
-                  }
+                  onClick={() => fixedArea.onClick?.()}
+                  className="h-10 w-10 flex items-center justify-center rounded-[var(--radius-button)] bg-primary text-primary-foreground shadow-sm hover:bg-primary/90 transition-all"
+                  aria-label="Nova Conversa"
                 >
-                  <Settings className="w-5 h-5 flex-shrink-0" />
-                  <span className="truncate text-sidebar-foreground">
-                    Configurações
-                  </span>
+                  {React.isValidElement(fixedArea.icon) ? fixedArea.icon : <fixedArea.icon className="h-5 w-5" />}
                 </button>
-              )
-            )}
-
-            {/* Logout Button */}
-            {showLogout && (
-              !expanded ? (
-                <Tooltip>
-                  <TooltipTrigger asChild>
-                    <button
-                      onClick={onLogout}
-                      className="w-full h-10 flex items-center justify-center px-0 rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
-                      aria-label="Sair"
-                    >
-                      <LogOut className="w-5 h-5 flex-shrink-0" />
-                    </button>
-                  </TooltipTrigger>
-                  <SidebarTooltipContent side="right" sideOffset={0}>
-                    <p>Sair</p>
-                  </SidebarTooltipContent>
-                </Tooltip>
-              ) : (
+              </TooltipTrigger>
+              <SidebarTooltipContent side="right">Nova Conversa</SidebarTooltipContent>
+            </Tooltip>
+          )}
+          {search?.show && (
+            <Tooltip>
+              <TooltipTrigger asChild>
                 <button
-                  onClick={onLogout}
-                  className="w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+                  className="h-10 w-10 flex items-center justify-center rounded-[var(--radius-button)] text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+                  aria-label="Buscar"
                 >
-                  <LogOut className="w-5 h-5 flex-shrink-0" />
-                  <span className="truncate text-sidebar-foreground">
-                    Sair
-                  </span>
+                  <SearchIcon className="h-5 w-5" />
                 </button>
-              )
+              </TooltipTrigger>
+              <SidebarTooltipContent side="right">Buscar</SidebarTooltipContent>
+            </Tooltip>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Footer area for the Sidebar with user info, settings, and logout.
+ */
+function SidebarFooter({
+  user,
+  onLogout = () => { },
+  onSettingsClick,
+  showUser = true,
+  showSettings = true,
+  showLogout = true,
+}: {
+  user?: { name?: string; email?: string; avatar?: string } | null;
+  onLogout?: () => void;
+  onSettingsClick?: () => void;
+  showUser?: boolean;
+  showSettings?: boolean;
+  showLogout?: boolean;
+}) {
+  const { expanded, navigate, location, onToggle } = useSidebarContext();
+  const isSettingsActive = location.pathname === "/settings";
+
+  const handleSettingsClick = () => {
+    if (onSettingsClick) {
+      onSettingsClick();
+    } else {
+      navigate("/settings");
+    }
+    if (typeof window !== "undefined" && window.innerWidth < 768) {
+      onToggle();
+    }
+  };
+
+  return (
+    <div className="flex-shrink-0 p-4 space-y-2">
+      {showUser && (
+        !expanded ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                className="w-full h-10 flex items-center justify-center px-0 rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+                aria-label="Perfil do usuário"
+              >
+                <Avatar className="w-7 h-7 flex-shrink-0">
+                  <AvatarImage src={user?.avatar} alt={user?.name || "User"} />
+                  <AvatarFallback className="bg-sidebar-foreground/15 text-sidebar-foreground text-xs">
+                    {user?.name ? user.name.charAt(0).toUpperCase() : "U"}
+                  </AvatarFallback>
+                </Avatar>
+              </button>
+            </TooltipTrigger>
+            <SidebarTooltipContent side="right" sideOffset={0}>
+              <p>{user?.name || "Perfil"}</p>
+            </SidebarTooltipContent>
+          </Tooltip>
+        ) : (
+          <button className="w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground">
+            <Avatar className="w-7 h-7 flex-shrink-0">
+              <AvatarImage src={user?.avatar} alt={user?.name || "User"} />
+              <AvatarFallback className="bg-sidebar-foreground/15 text-sidebar-foreground text-xs">
+                {user?.name ? user.name.charAt(0).toUpperCase() : "U"}
+              </AvatarFallback>
+            </Avatar>
+            <span className="text-sidebar-foreground truncate">{user?.name || "Perfil"}</span>
+          </button>
+        )
+      )}
+
+      {showSettings && (
+        !expanded ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                onClick={handleSettingsClick}
+                className={cn(
+                  "w-full h-10 flex items-center justify-center px-0 rounded-[var(--radius-button)] transition-all duration-200",
+                  isSettingsActive
+                    ? "bg-sidebar-foreground/15 text-sidebar-foreground shadow-sm"
+                    : "text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+                )}
+                aria-label="Configurações"
+              >
+                <Settings className="w-5 h-5 flex-shrink-0" />
+              </button>
+            </TooltipTrigger>
+            <SidebarTooltipContent side="right" sideOffset={0}>
+              <p>Configurações</p>
+            </SidebarTooltipContent>
+          </Tooltip>
+        ) : (
+          <button
+            onClick={handleSettingsClick}
+            className={cn(
+              "w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200",
+              isSettingsActive
+                ? "bg-sidebar-foreground/15 text-sidebar-foreground shadow-sm"
+                : "text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
             )}
-          </div>
-        )}
-      </div>
-    </TooltipProvider>
+          >
+            <Settings className="w-5 h-5 flex-shrink-0" />
+            <span className="truncate text-sidebar-foreground">Configurações</span>
+          </button>
+        )
+      )}
+
+      {showLogout && (
+        !expanded ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                onClick={onLogout}
+                className="w-full h-10 flex items-center justify-center px-0 rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+                aria-label="Sair"
+              >
+                <LogOut className="w-5 h-5 flex-shrink-0" />
+              </button>
+            </TooltipTrigger>
+            <SidebarTooltipContent side="right" sideOffset={0}>
+              <p>Sair</p>
+            </SidebarTooltipContent>
+          </Tooltip>
+        ) : (
+          <button
+            onClick={onLogout}
+            className="w-full h-10 flex items-center gap-3 px-3 justify-start rounded-[var(--radius-button)] transition-all duration-200 text-sidebar-foreground/80 hover:bg-sidebar-foreground/15 hover:text-sidebar-foreground"
+          >
+            <LogOut className="w-5 h-5 flex-shrink-0" />
+            <span className="truncate text-sidebar-foreground">Sair</span>
+          </button>
+        )
+      )}
+    </div>
   );
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Sidebar component (backward-compatible monolithic API)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Primary navigation sidebar component.
+ *
+ * @description
+ * Manages desktop/mobile responsive navigation rendering with two variants:
+ * - `"default"` — simple flat or grouped route list.
+ * - `"assistant"` — advanced variant with fixed areas, search, filters, and grouped navigation.
+ *
+ * This component is autonomous: it works out-of-the-box using local state or
+ * integrates automatically with `LayoutContext` if wrapped in `LayoutProvider`.
+ *
+ * For advanced customization, use the Compound Component API:
+ * `<Sidebar.Root>`, `<Sidebar.Header>`, `<Sidebar.Search>`, `<Sidebar.Nav>`, `<Sidebar.Footer>`
+ *
+ * @ai-rules
+ * 1. NEVER recreate the sidebar with raw Tailwind classes — always use this component.
+ * 2. Use `variant="assistant"` for AI/tool sidebars; use `variant="default"` for standard navigation.
+ * 3. Supports `Ctrl+B` keyboard shortcut automatically via `LayoutProvider`.
+ */
+export function Sidebar({
+  expanded: expandedProp,
+  onToggle: onToggleProp,
+  user,
+  onLogout = () => { },
+  onSettingsClick,
+  location: locationProp,
+  navigate: navigateProp,
+  routes,
+  logo,
+  logoCollapsed,
+  variant = "default",
+  fixedArea,
+  search,
+  navigationGroups = [],
+  footer,
+  showFooter,
+  width: widthProp,
+}: SidebarProps) {
+  const {
+    showUser = true,
+    showSettings = true,
+    showLogout = true,
+  } = footer || {};
+
+  const displayFooter = showFooter !== undefined ? showFooter : variant === "default";
+
+  return (
+    <SidebarRoot
+      expanded={expandedProp}
+      onToggle={onToggleProp}
+      navigate={navigateProp}
+      location={locationProp}
+      width={widthProp}
+    >
+      <SidebarHeader logo={logo} logoCollapsed={logoCollapsed} />
+
+      {variant === "assistant" && (
+        <SidebarSearch fixedArea={fixedArea} search={search} />
+      )}
+
+      <SidebarNav
+        navigationGroups={navigationGroups}
+        routes={routes}
+        variant={variant}
+      />
+
+      {displayFooter && (showUser || showSettings || showLogout) && (
+        <SidebarFooter
+          user={user}
+          onLogout={onLogout}
+          onSettingsClick={onSettingsClick}
+          showUser={showUser}
+          showSettings={showSettings}
+          showLogout={showLogout}
+        />
+      )}
+    </SidebarRoot>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Attach Compound Components to Sidebar namespace
+// ─────────────────────────────────────────────────────────────────────────────
+
+Sidebar.Root = SidebarRoot;
+Sidebar.Header = SidebarHeader;
+Sidebar.Search = SidebarSearch;
+Sidebar.Nav = SidebarNav;
+Sidebar.Footer = SidebarFooter;
+
+// Re-export hook for headless usage
+export { useSidebar } from "./use-sidebar";
+export type { UseSidebarProps } from "./use-sidebar";