@djangocfg/layouts 2.1.252 → 2.1.254

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.252",
+  "version": "2.1.254",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -74,14 +74,14 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.252",
-    "@djangocfg/centrifugo": "^2.1.252",
-    "@djangocfg/i18n": "^2.1.252",
-    "@djangocfg/monitor": "^2.1.252",
-    "@djangocfg/debuger": "^2.1.252",
-    "@djangocfg/ui-core": "^2.1.252",
-    "@djangocfg/ui-nextjs": "^2.1.252",
-    "@djangocfg/ui-tools": "^2.1.252",
+    "@djangocfg/api": "^2.1.254",
+    "@djangocfg/centrifugo": "^2.1.254",
+    "@djangocfg/i18n": "^2.1.254",
+    "@djangocfg/monitor": "^2.1.254",
+    "@djangocfg/debuger": "^2.1.254",
+    "@djangocfg/ui-core": "^2.1.254",
+    "@djangocfg/ui-nextjs": "^2.1.254",
+    "@djangocfg/ui-tools": "^2.1.254",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -109,15 +109,15 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.252",
-    "@djangocfg/i18n": "^2.1.252",
-    "@djangocfg/centrifugo": "^2.1.252",
-    "@djangocfg/monitor": "^2.1.252",
-    "@djangocfg/debuger": "^2.1.252",
-    "@djangocfg/typescript-config": "^2.1.252",
-    "@djangocfg/ui-core": "^2.1.252",
-    "@djangocfg/ui-nextjs": "^2.1.252",
-    "@djangocfg/ui-tools": "^2.1.252",
+    "@djangocfg/api": "^2.1.254",
+    "@djangocfg/i18n": "^2.1.254",
+    "@djangocfg/centrifugo": "^2.1.254",
+    "@djangocfg/monitor": "^2.1.254",
+    "@djangocfg/debuger": "^2.1.254",
+    "@djangocfg/typescript-config": "^2.1.254",
+    "@djangocfg/ui-core": "^2.1.254",
+    "@djangocfg/ui-nextjs": "^2.1.254",
+    "@djangocfg/ui-tools": "^2.1.254",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -26,6 +26,8 @@ export interface SidebarItem {
   href: string;
   icon?: string | LucideIconType;
   badge?: string | number;
+  /** Collapsed rail: shown in tooltip; defaults to `label`. */
+  tooltip?: string;
 }
 
 export interface SidebarGroupConfig {
@@ -42,6 +44,16 @@ export interface SidebarConfig {
   groups: SidebarGroupConfig[];
   /** Home link href */
   homeHref?: string;
+  /**
+   * Custom block inside the scrollable nav column, **above** all `groups`
+   * (below the brand header, same horizontal padding as nav).
+   */
+  menuStart?: ReactNode;
+  /**
+   * Custom block inside the scrollable nav column, **below** all `groups`
+   * (above `footer` + account block).
+   */
+  menuEnd?: ReactNode;
   /** Custom footer component rendered at the bottom of the sidebar */
   footer?: ReactNode;
 }
@@ -49,6 +61,16 @@ export interface SidebarConfig {
 export interface HeaderConfig {
   /** Shown next to the logo when the sidebar is expanded */
   title?: string;
+  /**
+   * Brand mark in the sidebar header (Lucide icon name or component).
+   * If omitted, a single-letter monogram from `brandLetter` / `title` is shown.
+   */
+  brandIcon?: string | LucideIconType;
+  /**
+   * Monogram when `brandIcon` is not set (one visible character).
+   * Defaults to the first letter of `title`, uppercased.
+   */
+  brandLetter?: string;
   /** User menu groups (account panel in the sidebar footer) */
   groups?: UserMenuConfig['groups'];
   /** Auth page path (for sign in button) */

package/src/layouts/PrivateLayout/components/PrivateContent.tsx

@@ -22,29 +22,25 @@ export function PrivateContent({
   padding = 'default',
   hasSidebar = true,
 }: PrivateContentProps) {
+  const mobileToolbarClass = cn(
+    'sticky top-0 z-40 flex shrink-0 items-center gap-2 border-b border-border/50 bg-background/95 py-2 pl-2 pr-3 backdrop-blur-md supports-[backdrop-filter]:bg-background/80',
+    'md:hidden',
+  );
+  const scrollAreaClass = cn(
+    'min-h-0 flex-1 overflow-y-auto',
+    padding === 'default' && 'p-4 sm:p-6 lg:p-8',
+  );
+
+  const mobileToolbar = hasSidebar ? (
+    <div className={mobileToolbarClass}>
+      <SidebarTrigger className="shrink-0" aria-label="Open menu" />
+    </div>
+  ) : null;
+
   return (
     <div className="flex min-h-0 min-w-0 flex-1 flex-col">
-      {hasSidebar && (
-        <div
-          className={cn(
-            'sticky top-0 z-40 flex shrink-0 items-center gap-2 border-b border-border/50 bg-background/95 py-2 pl-2 pr-3 backdrop-blur-md supports-[backdrop-filter]:bg-background/80',
-            'md:hidden',
-          )}
-        >
-          <SidebarTrigger
-            className="shrink-0"
-            aria-label="Open menu"
-          />
-        </div>
-      )}
-      <div
-        className={cn(
-          'min-h-0 flex-1 overflow-y-auto',
-          padding === 'default' && 'p-4 sm:p-6 lg:p-8',
-        )}
-      >
-        {children}
-      </div>
+      {mobileToolbar}
+      <div className={scrollAreaClass}>{children}</div>
     </div>
   );
 }

package/src/layouts/PrivateLayout/components/PrivateSidebar.tsx

@@ -41,49 +41,53 @@ function navDensityFromCount(n: number): NavDensity {
 }
 
 /**
- * Nav rows: inactive muted. Light active = neutral pill (readable on white); dark = dark chip.
- * Avoids `sidebar-accent` in light — project tokens often map to near-black and wash out labels.
+ * Nav rows use semantic sidebar tokens so light/dark follows ui-core theme vars.
  */
 const navItemClass = cn(
   'border-0 font-normal shadow-none transition-colors',
-  'text-muted-foreground',
-  'data-[active=true]:font-medium',
-  'data-[active=true]:bg-zinc-200/90 data-[active=true]:text-zinc-900',
-  'dark:data-[active=true]:bg-[#1a1a1a] dark:data-[active=true]:text-zinc-50',
-  'hover:bg-zinc-100/90 hover:text-foreground dark:hover:bg-white/[0.06]',
-  'data-[active=true]:hover:bg-zinc-200 dark:data-[active=true]:hover:bg-[#1a1a1a]',
-  '[&>svg]:shrink-0 [&>svg]:text-muted-foreground [&>svg]:opacity-85',
-  'data-[active=true]:[&>svg]:text-zinc-800 data-[active=true]:[&>svg]:opacity-100',
-  'dark:data-[active=true]:[&>svg]:text-zinc-50',
+  'text-sidebar-foreground/70',
+  'data-[active=true]:font-medium data-[active=true]:bg-sidebar-accent data-[active=true]:text-sidebar-accent-foreground',
+  'hover:bg-sidebar-accent/70 hover:text-sidebar-accent-foreground',
+  'data-[active=true]:hover:bg-sidebar-accent',
+  '[&>svg]:shrink-0 [&>svg]:text-sidebar-foreground/70 [&>svg]:opacity-85',
+  'data-[active=true]:[&>svg]:text-sidebar-accent-foreground data-[active=true]:[&>svg]:opacity-100',
 );
 
 const DENSITY = {
   comfortable: {
     menu: 'gap-1.5',
-    group: 'gap-3',
+    group: 'gap-2',
+    /** Tighter than default SidebarGroup `p-2` (doubles Y between groups). */
+    groupPad: 'px-2 py-1',
     label:
-      'h-7 uppercase text-[10px] font-light leading-none tracking-[0.14em] text-muted-foreground/40',
+      'h-7 uppercase text-[10px] font-light leading-none tracking-[0.14em] text-sidebar-foreground/40',
     buttonSize: 'lg' as const,
     iconClass: 'h-5 w-5',
     extraButton: 'rounded-lg !px-3',
+    /** Extra left inset so brand aligns with nav icons (group p-2 + button px). */
+    headerRowInset: 'pl-3',
   },
   default: {
     menu: 'gap-1',
-    group: 'gap-2',
+    group: 'gap-1.5',
+    groupPad: 'px-2 py-1',
     label:
-      'uppercase text-[9px] font-light leading-none tracking-[0.12em] text-muted-foreground/50',
+      'uppercase text-[9px] font-light leading-none tracking-[0.12em] text-sidebar-foreground/50',
     buttonSize: 'default' as const,
     iconClass: 'h-4 w-4',
     extraButton: 'rounded-lg',
+    headerRowInset: 'pl-2',
   },
   compact: {
     menu: 'gap-0.5',
-    group: 'gap-1',
+    group: 'gap-0.5',
+    groupPad: 'px-2 py-0.5',
     label:
-      'h-6 uppercase text-[8px] font-light leading-none tracking-[0.1em] text-muted-foreground/40',
+      'h-6 uppercase text-[8px] font-light leading-none tracking-[0.1em] text-sidebar-foreground/40',
     buttonSize: 'sm' as const,
     iconClass: 'h-3.5 w-3.5',
     extraButton: 'rounded-md !px-2',
+    headerRowInset: 'pl-2',
   },
 } as const;
 
@@ -104,6 +108,7 @@ export function PrivateSidebar({ sidebar, header, i18n, pathname: pathnameProp }
     if (isMobile) setOpenMobile(false);
   }, [pathname, isMobile, setOpenMobile]);
   const brandTitle = header?.title?.trim() || 'Dashboard';
+  const brandMonogram = (header?.brandLetter?.trim().charAt(0) || brandTitle.charAt(0) || 'D').toUpperCase();
 
   const allItems = React.useMemo(
     () => sidebar.groups.flatMap((g) => g.items),
@@ -113,84 +118,116 @@ export function PrivateSidebar({ sidebar, header, i18n, pathname: pathnameProp }
   const density = React.useMemo(() => navDensityFromCount(allItems.length), [allItems.length]);
   const d = DENSITY[density];
 
-  const isActive = (href: string) => {
-    const matches = pathname === href || pathname.startsWith(`${href}/`);
-    if (!matches) return false;
-    return !allItems.some(
-      (other) =>
-        other.href !== href &&
-        other.href.startsWith(`${href}/`) &&
-        (pathname === other.href || pathname.startsWith(`${other.href}/`)),
-    );
-  };
+  const isActive = React.useCallback(
+    (href: string) => {
+      const matches = pathname === href || pathname.startsWith(`${href}/`);
+      if (!matches) return false;
+      return !allItems.some(
+        (other) =>
+          other.href !== href &&
+          other.href.startsWith(`${href}/`) &&
+          (pathname === other.href || pathname.startsWith(`${other.href}/`)),
+      );
+    },
+    [pathname, allItems],
+  );
 
   const expanded = state === 'expanded';
 
+  const headerRowClass = cn('flex items-center gap-2', d.headerRowInset);
+  const brandMark = header?.brandIcon ? (
+    <LucideIcon icon={header.brandIcon} className="h-4 w-4 text-sidebar-primary-foreground" />
+  ) : (
+    <span className="text-[11px] font-bold leading-none tracking-tight text-sidebar-primary-foreground">
+      {brandMonogram}
+    </span>
+  );
+
+  const showMenuStart = sidebar.menuStart != null && sidebar.menuStart !== false;
+  const showMenuEnd = sidebar.menuEnd != null && sidebar.menuEnd !== false;
+  const menuStartSlot = showMenuStart ? (
+    <div className="w-full min-w-0 shrink-0 px-2">{sidebar.menuStart}</div>
+  ) : null;
+  const menuEndSlot = showMenuEnd ? (
+    <div className="w-full min-w-0 shrink-0 px-2">{sidebar.menuEnd}</div>
+  ) : null;
+
+  const sidebarContentClass = cn('gap-2', d.group);
+
+  const renderedGroups = React.useMemo(() => {
+    const navButtonClass = cn(navItemClass, d.extraButton);
+    const groupLabelClass = cn('px-2', d.label);
+    const sidebarGroupClass = cn('gap-0', d.groupPad);
+
+    return sidebar.groups.map((group) => {
+      if (group.dynamic && group.items.length === 0) return null;
+      const items = group.items.map((item: SidebarItem) => {
+        const iconProp = typeof item.icon === 'string' ? item.icon : item.icon;
+        const tooltipText = item.tooltip ?? item.label;
+        return (
+          <SidebarMenuItem key={item.href}>
+            <SidebarMenuButton
+              asChild
+              isActive={isActive(item.href)}
+              size={d.buttonSize}
+              tooltip={tooltipText}
+              className={navButtonClass}
+            >
+              <Link href={item.href}>
+                {item.icon ? <LucideIcon icon={iconProp} className={d.iconClass} /> : null}
+                <span>{item.label}</span>
+                {item.badge ? <SidebarMenuBadge>{item.badge}</SidebarMenuBadge> : null}
+              </Link>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        );
+      });
+
+      return (
+        <SidebarGroup key={group.label} className={sidebarGroupClass}>
+          <SidebarGroupLabel className={groupLabelClass}>{group.label}</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu className={d.menu}>{items}</SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      );
+    });
+  }, [sidebar.groups, isActive, d]);
+
+  const expandedHeader = (
+    <div className={headerRowClass}>
+      <Link
+        href={homeHref}
+        className="flex min-w-0 flex-1 items-center gap-2 rounded-md py-0.5 outline-none ring-sidebar-ring focus-visible:ring-2"
+      >
+        <div className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-sidebar-primary">{brandMark}</div>
+        <span className="truncate text-sm font-semibold tracking-tight text-sidebar-foreground">{brandTitle}</span>
+      </Link>
+      <SidebarTrigger className="shrink-0" aria-label="Collapse sidebar" />
+    </div>
+  );
+
+  const collapsedHeader = (
+    <div className="flex justify-center py-1">
+      <SidebarTrigger aria-label="Expand sidebar" />
+    </div>
+  );
+
+  const sidebarHeaderContent = expanded ? expandedHeader : collapsedHeader;
+  const footerExtra = sidebar.footer ? <div className="mb-2">{sidebar.footer}</div> : null;
+
   return (
     <Sidebar collapsible="icon">
-      <SidebarHeader className="px-2 py-1.5">
-        {expanded ? (
-          <div className="flex items-center gap-2">
-            <Link
-              href={homeHref}
-              className="flex min-w-0 flex-1 items-center gap-2 rounded-md py-0.5 outline-none ring-sidebar-ring focus-visible:ring-2"
-            >
-              <div className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-primary">
-                <span className="text-[11px] font-bold leading-none tracking-tight text-primary-foreground">
-                  D
-                </span>
-              </div>
-              <span className="truncate text-sm font-semibold tracking-tight text-foreground">
-                {brandTitle}
-              </span>
-            </Link>
-            <SidebarTrigger className="shrink-0" aria-label="Collapse sidebar" />
-          </div>
-        ) : (
-          <div className="flex justify-center py-0.5">
-            <SidebarTrigger aria-label="Expand sidebar" />
-          </div>
-        )}
-      </SidebarHeader>
-
-      <SidebarContent className={cn('gap-2', d.group)}>
-        {sidebar.groups.map((group) => {
-          if (group.dynamic && group.items.length === 0) return null;
-          return (
-            <SidebarGroup key={group.label} className="gap-0">
-              <SidebarGroupLabel className={cn('px-2', d.label)}>{group.label}</SidebarGroupLabel>
-              <SidebarGroupContent>
-                <SidebarMenu className={d.menu}>
-                  {group.items.map((item: SidebarItem) => (
-                    <SidebarMenuItem key={item.href}>
-                      <SidebarMenuButton
-                        asChild
-                        isActive={isActive(item.href)}
-                        size={d.buttonSize}
-                        className={cn(navItemClass, d.extraButton)}
-                      >
-                        <Link href={item.href}>
-                          {item.icon && (
-                            <LucideIcon
-                              icon={typeof item.icon === 'string' ? item.icon : item.icon}
-                              className={d.iconClass}
-                            />
-                          )}
-                          <span>{item.label}</span>
-                          {item.badge && <SidebarMenuBadge>{item.badge}</SidebarMenuBadge>}
-                        </Link>
-                      </SidebarMenuButton>
-                    </SidebarMenuItem>
-                  ))}
-                </SidebarMenu>
-              </SidebarGroupContent>
-            </SidebarGroup>
-          );
-        })}
+      <SidebarHeader className="px-2 pt-2.5 pb-2">{sidebarHeaderContent}</SidebarHeader>
+
+      <SidebarContent className={sidebarContentClass}>
+        {menuStartSlot}
+        {renderedGroups}
+        {menuEndSlot}
       </SidebarContent>
 
       <SidebarFooter className="p-2">
-        {sidebar.footer && <div className="mb-2">{sidebar.footer}</div>}
+        {footerExtra}
         <PrivateSidebarAccount header={header} i18n={i18n} />
       </SidebarFooter>
     </Sidebar>

package/src/layouts/_components/PrivateSidebarAccount.tsx

@@ -39,8 +39,28 @@ export function PrivateSidebarAccount({ header, i18n }: PrivateSidebarAccountPro
   const { user } = useAuth();
   const handleLogout = useLogout();
   const t = useAppT();
-  const { state } = useSidebar();
-  const [open, setOpen] = React.useState(false);
+  const { state, setOpen: setSidebarOpen } = useSidebar();
+  const [accountOpen, setAccountOpen] = React.useState(false);
+  const accountRootRef = React.useRef<HTMLDivElement>(null);
+  const narrow = state === 'collapsed';
+
+  React.useEffect(() => {
+    if (state === 'collapsed') setAccountOpen(false);
+  }, [state]);
+
+  React.useEffect(() => {
+    if (!accountOpen) return;
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const root = accountRootRef.current;
+      if (root && !root.contains(event.target as Node)) {
+        setAccountOpen(false);
+      }
+    };
+
+    document.addEventListener('pointerdown', handlePointerDown);
+    return () => document.removeEventListener('pointerdown', handlePointerDown);
+  }, [accountOpen]);
 
   const signOutLabel = t('layouts.profile.signOut');
 
@@ -56,113 +76,129 @@ export function PrivateSidebarAccount({ header, i18n }: PrivateSidebarAccountPro
   const displayName = user.display_username || user.email || 'User';
   const userInitial = displayName.charAt(0).toUpperCase();
   const userAvatar = user.avatar || '';
-  const narrow = state === 'collapsed';
   const hasEmailOrLinks = Boolean(user.email) || accountLinks.length > 0;
 
+  const triggerClassName = cn(
+    'h-auto min-h-10 w-full gap-2 rounded-md px-2 py-2 text-left hover:bg-sidebar-accent',
+    narrow && 'justify-center px-0',
+  );
+  const chevronClassName = cn(
+    'h-4 w-4 shrink-0 text-sidebar-foreground/65 transition-transform duration-200',
+    accountOpen && 'rotate-180',
+  );
+  const accountPanelClassName = cn(
+    'mt-2 flex flex-col gap-3 rounded-lg border border-sidebar-border/60 bg-sidebar-accent/45 p-3 shadow-sm',
+    'dark:border-sidebar-border dark:bg-sidebar-accent/20',
+  );
+  const accountActionsClassName = cn(
+    'flex min-h-10 items-center gap-2',
+    hasEmailOrLinks && 'border-t border-sidebar-border/50 pt-3',
+  );
+
+  const onAccountTriggerClick = React.useCallback(() => {
+    if (narrow) setSidebarOpen(true);
+  }, [narrow, setSidebarOpen]);
+
+  const accountLinkRows = React.useMemo(
+    () =>
+      accountLinks.map((item) => {
+        const Icon = item.icon;
+        return (
+          <Link
+            key={item.href}
+            href={item.href!}
+            className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm leading-snug text-sidebar-foreground transition-colors hover:bg-sidebar-accent"
+          >
+            {Icon ? <Icon className="h-4 w-4 shrink-0 text-sidebar-foreground/65" /> : null}
+            <span className="truncate">{item.label}</span>
+          </Link>
+        );
+      }),
+    [accountLinks],
+  );
+
+  const emailBlock = user.email ? (
+    <p className="truncate text-xs leading-snug text-sidebar-foreground/65">{user.email}</p>
+  ) : null;
+
+  const accountLinksNav =
+    accountLinks.length > 0 ? (
+      <nav className="flex max-h-40 flex-col gap-0.5 overflow-y-auto" aria-label="Account">
+        {accountLinkRows}
+      </nav>
+    ) : null;
+
+  const expandedTriggerMeta = narrow ? null : (
+    <>
+      <span className="min-w-0 flex-1 truncate text-left text-sm font-medium leading-tight text-sidebar-foreground">
+        {displayName}
+      </span>
+      <ChevronDown className={chevronClassName} aria-hidden />
+    </>
+  );
+
+  const localeThemeGroup = i18n ? (
+    <LocaleSwitcher
+      locale={i18n.locale}
+      locales={i18n.locales}
+      onChange={i18n.onLocaleChange}
+      variant="ghost"
+      size="icon"
+      showTriggerLabel={false}
+      showIcon={false}
+      className="h-8 w-8 shrink-0 text-base leading-none"
+    />
+  ) : null;
+
   return (
-    <Collapsible open={open} onOpenChange={setOpen} className="w-full min-w-0 border-t border-sidebar-border/45 pt-2">
-      <CollapsibleTrigger asChild>
-        <Button
-          type="button"
-          variant="ghost"
-          aria-expanded={open}
-          aria-label={narrow ? 'Account' : undefined}
-          className={cn(
-            'h-auto min-h-10 w-full gap-2 rounded-md px-2 py-2 text-left hover:bg-sidebar-accent',
-            narrow && 'justify-center px-0',
-          )}
-        >
-          <Avatar className="h-8 w-8 shrink-0">
-            <AvatarImage src={userAvatar} alt={displayName} />
-            <AvatarFallback className="text-xs">{userInitial}</AvatarFallback>
-          </Avatar>
-          {!narrow && (
-            <>
-              <span className="min-w-0 flex-1 truncate text-left text-sm font-medium leading-tight">
-                {displayName}
-              </span>
-              <ChevronDown
-                className={cn(
-                  'h-4 w-4 shrink-0 text-muted-foreground transition-transform duration-200',
-                  open && 'rotate-180',
-                )}
-                aria-hidden
-              />
-            </>
-          )}
-        </Button>
-      </CollapsibleTrigger>
-
-      <CollapsibleContent className="overflow-hidden data-[state=closed]:hidden">
-        <div
-          className={cn(
-            'mt-2 flex flex-col gap-3 rounded-lg border border-zinc-200/90 bg-zinc-50/80 p-3 shadow-sm',
-            'dark:border-sidebar-border dark:bg-sidebar-accent/15',
-          )}
-        >
-          {user.email && (
-            <p className="truncate text-xs leading-snug text-muted-foreground">{user.email}</p>
-          )}
-
-          {accountLinks.length > 0 && (
-            <nav className="flex max-h-40 flex-col gap-0.5 overflow-y-auto" aria-label="Account">
-              {accountLinks.map((item) => {
-                const Icon = item.icon;
-                return (
-                  <Link
-                    key={item.href}
-                    href={item.href!}
-                    className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm leading-snug text-zinc-800 transition-colors hover:bg-zinc-200/70 dark:text-foreground dark:hover:bg-sidebar-accent"
-                  >
-                    {Icon && (
-                      <Icon className="h-4 w-4 shrink-0 text-zinc-500 dark:text-muted-foreground" />
-                    )}
-                    <span className="truncate">{item.label}</span>
-                  </Link>
-                );
-              })}
-            </nav>
-          )}
-
-          <div
-            className={cn(
-              'flex min-h-10 items-center gap-2',
-              hasEmailOrLinks && 'border-t border-border/50 pt-3 dark:border-sidebar-border/40',
-            )}
+    <div ref={accountRootRef} className="w-full min-w-0 border-t border-sidebar-border/45 pt-2">
+      <Collapsible open={accountOpen} onOpenChange={setAccountOpen} className="w-full min-w-0">
+        <CollapsibleTrigger asChild>
+          <Button
+            type="button"
+            variant="ghost"
+            aria-expanded={accountOpen}
+            aria-label={narrow ? 'Account' : undefined}
+            className={triggerClassName}
+            onClick={onAccountTriggerClick}
           >
-            <button
-              type="button"
-              onClick={handleLogout}
-              className="flex min-w-0 flex-1 items-center gap-2 rounded-md px-2 py-2 text-left text-sm text-destructive hover:bg-destructive/10"
-            >
-              <LogOut className="h-4 w-4 shrink-0" />
-              <span className="truncate">{signOutLabel}</span>
-            </button>
-            <div
-              className="flex shrink-0 items-center gap-0.5 border-l border-border/50 pl-2 dark:border-sidebar-border/40"
-              role="group"
-              aria-label="Language and theme"
-            >
-              {i18n && (
-                <LocaleSwitcher
-                  locale={i18n.locale}
-                  locales={i18n.locales}
-                  onChange={i18n.onLocaleChange}
-                  variant="ghost"
-                  size="icon"
-                  showTriggerLabel={false}
-                  showIcon={false}
-                  className="h-8 w-8 shrink-0 text-base leading-none"
+            <Avatar className="h-8 w-8 shrink-0">
+              <AvatarImage src={userAvatar} alt={displayName} />
+              <AvatarFallback className="text-xs">{userInitial}</AvatarFallback>
+            </Avatar>
+            {expandedTriggerMeta}
+          </Button>
+        </CollapsibleTrigger>
+
+        <CollapsibleContent className="overflow-hidden data-[state=closed]:hidden">
+          <div className={accountPanelClassName}>
+            {emailBlock}
+            {accountLinksNav}
+
+            <div className={accountActionsClassName}>
+              <button
+                type="button"
+                onClick={handleLogout}
+                className="flex min-w-0 flex-1 items-center gap-2 rounded-md px-2 py-2 text-left text-sm text-destructive hover:bg-destructive/10"
+              >
+                <LogOut className="h-4 w-4 shrink-0" />
+                <span className="truncate">{signOutLabel}</span>
+              </button>
+              <div
+                className="flex shrink-0 items-center gap-0.5 border-l border-sidebar-border/50 pl-2"
+                role="group"
+                aria-label="Language and theme"
+              >
+                {localeThemeGroup}
+                <ThemeToggle
+                  size="compact"
+                  className="h-8 w-8 shrink-0 focus-visible:ring-1 focus-visible:ring-sidebar-ring focus-visible:ring-offset-0"
                 />
-              )}
-              <ThemeToggle
-                size="compact"
-                className="h-8 w-8 shrink-0 focus-visible:ring-1 focus-visible:ring-sidebar-ring focus-visible:ring-offset-0"
-              />
+              </div>
             </div>
           </div>
-        </div>
-      </CollapsibleContent>
-    </Collapsible>
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
   );
 }

package/src/utils/index.ts

@@ -5,4 +5,5 @@
 export * from './config';
 export * from './logger';
 export * from './pathMatcher';
+export * from './sidebarNav';
 

package/src/utils/sidebarNav.ts

@@ -0,0 +1,16 @@
+import type { LucideIcon as LucideIconType } from 'lucide-react';
+
+/**
+ * Maps menu/route `icon` values into `SidebarItem['icon']`.
+ * Supports Lucide icon **name** (`"LayoutDashboard"`), a **Lucide component**, or legacy `{ name: string }`.
+ */
+export function normalizeSidebarNavIcon(icon: unknown): string | LucideIconType | undefined {
+  if (icon == null) return undefined;
+  if (typeof icon === 'string') return icon;
+  if (typeof icon === 'function') return icon as LucideIconType;
+  if (typeof icon === 'object' && icon !== null && 'name' in icon) {
+    const n = (icon as { name?: unknown }).name;
+    if (typeof n === 'string' && n.length > 0) return n;
+  }
+  return undefined;
+}