@djangocfg/layouts 2.1.319 → 2.1.321

package/src/layouts/PrivateLayout/README.md

@@ -0,0 +1,129 @@
+# PrivateLayout
+
+Authenticated app shell — collapsible sidebar (icon-rail vs expanded) + scrollable content area.
+
+```tsx
+<PrivateLayout
+  sidebar={sidebar}
+  header={header}
+  pathname={usePathname()}
+  visual={{ variant: 'boxed', inset: 12, radius: '2xl', border: true }}
+>
+  {children}
+</PrivateLayout>
+```
+
+The auth guard redirects to `header.authPath` when there's no session. Pass `requireAuth={false}` to render without it (static showcases / playground).
+
+---
+
+## Visual variants
+
+`boxed` (default) — `<SidebarInset>` becomes a rounded card; the wrapper paints `bg-sidebar` so the brand colour bleeds to the viewport edges. Mobile (<md) degrades to full-bleed automatically.
+
+`full-bleed` — content stretches edge-to-edge next to the sidebar (legacy look). Opt in with `visual={{ variant: 'full-bleed' }}`.
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `variant` | `'full-bleed' \| 'boxed'` | `'boxed'` | Switch between the two shells. |
+| `inset` | `number \| { x?: number; y?: number }` | `12` | Gap (px) between the card and the viewport edges (md+). |
+| `radius` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'` | `'2xl'` | Card corner radius. |
+| `background` | `'sidebar' \| 'muted' \| 'card' \| 'background'` | `'sidebar'` | Canvas colour painted *behind* the boxed card. |
+| `border` | `boolean` | `true` | 1px border on the card. |
+| `maxWidth` | `'none' \| '7xl' \| 'screen-xl' \| 'screen-2xl'` | `'none'` | Optional inner content width cap. |
+
+---
+
+## Sidebar config
+
+`SidebarConfig` (passed as `sidebar` prop):
+
+| Field | Type | Notes |
+|---|---|---|
+| `groups` | `SidebarGroupConfig[]` | Nav items grouped under labels. Set `group.label = ''` to render flat (no header). |
+| `homeHref` | `string` | Brand link target. |
+| `menuStart` / `menuEnd` | `ReactNode` | Free slots above / below `groups` in the scrollable column. |
+| `menuStartShowOnCollapsed` / `menuEndShowOnCollapsed` | `boolean` | Keep slots visible on the icon rail. |
+| `footer` | `ReactNode` | Custom footer node above the account block. |
+| `activeIndicator` | `'background' \| 'rail' \| 'both'` | Active item visual. Default `'background'` (legacy). `'rail'` paints a 2px primary stripe on the right edge (Vercel-style). |
+| `groupLabelStyle` | `'uppercase' \| 'plain'` | Label typography. Default `'uppercase'` (legacy ultra-light caps). Collapsible groups always render `plain`. |
+| `featured` | `SidebarFeaturedConfig` | Accent-tinted CTA tile rendered below groups (Mailersend-style). |
+
+`SidebarGroupConfig`:
+
+| Field | Type | Notes |
+|---|---|---|
+| `label` | `string` | Group title. Empty string → flat group (no header). |
+| `items` | `SidebarItem[]` | Nav links. |
+| `dynamic` | `boolean` | Hide group when `items` is empty (for extension-driven groups). |
+| `collapsible` | `boolean` | Render as accordion. Label becomes a clickable trigger; auto-expanded if a child is active. Disabled on the icon rail. |
+| `defaultOpen` | `boolean` | Initial open state for collapsible groups. |
+| `icon` | `string \| LucideIcon` | Icon for the trigger (collapsible only). |
+| `hideItemIcons` | `boolean` | Hide per-item icons inside the group. Defaults to `true` when `collapsible`. |
+
+`SidebarItem`:
+
+| Field | Type | Notes |
+|---|---|---|
+| `label`, `href`, `icon`, `tooltip` | — | Standard nav item fields. |
+| `badge` | `string \| number` | Trailing badge content. |
+| `badgeVariant` | `'count' \| 'pill'` | Visual style. `'pill'` is accent-tinted (e.g. "lite"/"new"); `'count'` is neutral (default). |
+
+`SidebarFeaturedConfig`:
+
+| Field | Type | Notes |
+|---|---|---|
+| `icon`, `label`, `href` | — | Tile content. |
+| `badge` | `string` | Inline pill (e.g. "lite"). |
+| `accent` | `'green' \| 'blue' \| 'amber' \| 'primary'` | Tile tint. Default `'green'`. |
+
+---
+
+## Header / account footer
+
+`HeaderConfig` (passed as `header` prop):
+
+| Field | Type | Notes |
+|---|---|---|
+| `brand`, `title`, `brandIcon`, `brandLetter` | — | Sidebar header brand. |
+| `groups` | `UserMenuGroup[]` | Account links rendered inside the footer dropdown. |
+| `authPath` | `string` | Sign-in redirect target. |
+| `userPlan` | `string` | Subtitle under the display name (e.g. `"Max plan"`). |
+| `footerSecondaryAction` | `{ icon, href?, onClick?, ariaLabel, pulse? }` | Optional secondary icon button inside the footer trigger (e.g. "Get apps" with pulsing dot). |
+
+The footer button opens a popover (`DropdownMenu`, `side="top"`) with: email, account links, **Language** (opens fullscreen `LocaleSwitcherDialog` if `LayoutI18nProvider` is mounted), **Theme** (cycles `light → dark → system`), and **Log out**. In dev mode the footer renders a `Guest (dev)` placeholder when there's no authenticated user, so debug controls stay reachable; in production the block hides itself.
+
+---
+
+## Sample
+
+```tsx
+const sidebar: SidebarConfig = {
+  homeHref: '/',
+  activeIndicator: 'rail',
+  groupLabelStyle: 'plain',
+  groups: [
+    {
+      label: 'Email',
+      collapsible: true,
+      icon: 'Mail',
+      defaultOpen: true,
+      items: [
+        { label: 'Domains',  href: '/email/domains' },
+        { label: 'Activity', href: '/email/activity' },
+      ],
+    },
+    { label: 'SMS', collapsible: true, icon: 'Smartphone', items: [...] },
+  ],
+  featured: { icon: 'Sparkles', label: 'Marketing', href: '/marketing', badge: 'lite', accent: 'green' },
+};
+
+const header: HeaderConfig = {
+  title: 'Dashboard',
+  brandIcon: 'Layers',
+  authPath: '/auth',
+  userPlan: 'Pro plan',
+  footerSecondaryAction: { icon: 'Download', href: '/apps', ariaLabel: 'Get apps', pulse: true },
+  groups: [{ title: 'Account', items: [{ label: 'Settings', href: '/settings' }] }],
+};
+```

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

@@ -7,7 +7,7 @@
 
 import React, { ReactNode } from 'react';
 
-import { SidebarTrigger, useSidebar } from '@djangocfg/ui-nextjs/components';
+import { SidebarTrigger, useSidebar } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import type { LayoutVisualConfig } from '../../types';

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

@@ -5,7 +5,13 @@
 
 'use client';
 
-import { Link } from '@djangocfg/ui-core/components';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+  Link,
+} from '@djangocfg/ui-core/components';
+import { ChevronDown } from 'lucide-react';
 import { usePathname as useNextPathname } from 'next/navigation';
 import React from 'react';
 
@@ -23,13 +29,21 @@ import {
   SidebarMenuItem,
   SidebarTrigger,
   useSidebar,
-} from '@djangocfg/ui-nextjs/components';
+} from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { PrivateSidebarAccount } from '../../_components/PrivateSidebarAccount';
 import { LucideIcon } from '../../../components';
 
-import type { HeaderConfig, SidebarItem, SidebarConfig } from '../PrivateLayout';
+import type {
+  HeaderConfig,
+  SidebarActiveIndicator,
+  SidebarConfig,
+  SidebarGroupConfig,
+  SidebarGroupLabelStyle,
+  SidebarItem,
+} from '../PrivateLayout';
+import { SidebarFeatured } from '../../_components/SidebarFeatured';
 
 /** Few items → roomier rows; many items → tighter. Same breakpoints for demo, CarAPIS, etc. */
 const DENSITY_COMFORTABLE_MAX = 6;
@@ -46,16 +60,36 @@ function navDensityFromCount(n: number): NavDensity {
 /**
  * Nav rows use semantic sidebar tokens so light/dark follows ui-core theme vars.
  */
-const navItemClass = cn(
-  'border-0 font-medium shadow-none transition-colors',
+const navItemBaseClass = cn(
+  'group/nav relative border-0 font-medium shadow-none transition-colors',
   'text-sidebar-foreground/80',
-  'data-[active=true]:font-semibold data-[active=true]:bg-sidebar-accent data-[active=true]:text-sidebar-accent-foreground',
+  'data-[active=true]:font-semibold 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',
+  '[&>svg]:transition-transform [&>svg]:duration-200 group-hover/nav:[&>svg]:scale-110 group-active/nav:[&>svg]:scale-95',
   'data-[active=true]:[&>svg]:text-sidebar-accent-foreground data-[active=true]:[&>svg]:opacity-100',
 );
 
+const ACTIVE_INDICATOR_CLASS: Record<SidebarActiveIndicator, string> = {
+  background: cn(
+    'data-[active=true]:bg-sidebar-accent',
+    'data-[active=true]:hover:bg-sidebar-accent',
+  ),
+  rail: cn(
+    'data-[active=true]:after:absolute data-[active=true]:after:right-0',
+    'data-[active=true]:after:top-1.5 data-[active=true]:after:bottom-1.5',
+    'data-[active=true]:after:w-[2px] data-[active=true]:after:rounded-l-full',
+    'data-[active=true]:after:bg-primary',
+  ),
+  both: cn(
+    'data-[active=true]:bg-sidebar-accent data-[active=true]:hover:bg-sidebar-accent',
+    'data-[active=true]:after:absolute data-[active=true]:after:right-0',
+    'data-[active=true]:after:top-1.5 data-[active=true]:after:bottom-1.5',
+    'data-[active=true]:after:w-[2px] data-[active=true]:after:rounded-l-full',
+    'data-[active=true]:after:bg-primary',
+  ),
+};
+
 const DENSITY = {
   comfortable: {
     menu: 'gap-1.5',
@@ -173,45 +207,39 @@ export function PrivateSidebar({ sidebar, header, pathname: pathnameProp, varian
 
   const sidebarContentClass = cn('gap-2', menuNav.group);
 
-  const renderedGroups = React.useMemo(() => {
-    const navButtonClass = cn(navItemClass, menuNav.extraButton);
-    const groupLabelClass = cn('px-2', menuNav.label);
-    const sidebarGroupClass = cn('gap-0', menuNav.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={menuNav.buttonSize}
-              tooltip={tooltipText}
-              className={navButtonClass}
-            >
-              <Link href={item.href}>
-                {item.icon ? <LucideIcon icon={iconProp} className={menuNav.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={menuNav.menu}>{items}</SidebarMenu>
-          </SidebarGroupContent>
-        </SidebarGroup>
-      );
-    });
-  }, [sidebar.groups, isActive, menuNav]);
+  const activeIndicator: SidebarActiveIndicator = sidebar.activeIndicator ?? 'background';
+  const groupLabelStyle: SidebarGroupLabelStyle = sidebar.groupLabelStyle ?? 'uppercase';
+  const navButtonClass = cn(navItemBaseClass, ACTIVE_INDICATOR_CLASS[activeIndicator], menuNav.extraButton);
+  const groupLabelUppercaseClass = cn('px-2', menuNav.label);
+  const groupLabelPlainClass = cn(
+    'px-2 text-sm font-semibold text-sidebar-foreground',
+    'h-7 leading-none',
+  );
+  const sidebarGroupClass = cn('gap-0', menuNav.groupPad);
+
+  const renderedGroups = sidebar.groups.map((group) => {
+    if (group.dynamic && group.items.length === 0) return null;
+    return (
+      <SidebarGroupRenderer
+        key={group.label || `__flat_${group.items.map((i) => i.href).join('|')}`}
+        group={group}
+        isActive={isActive}
+        navButtonClass={navButtonClass}
+        sidebarGroupClass={sidebarGroupClass}
+        groupLabelUppercaseClass={groupLabelUppercaseClass}
+        groupLabelPlainClass={groupLabelPlainClass}
+        groupLabelStyle={groupLabelStyle}
+        menuNav={menuNav}
+        collapsedRail={collapsedRail}
+      />
+    );
+  });
+
+  const featuredSlot = sidebar.featured && !collapsedRail ? (
+    <div className="w-full min-w-0 shrink-0 px-2">
+      <SidebarFeatured config={sidebar.featured} />
+    </div>
+  ) : null;
 
   const expandedHeader = (
     <div className={headerRowClass}>
@@ -305,11 +333,16 @@ export function PrivateSidebar({ sidebar, header, pathname: pathnameProp, varian
   const railExpandHintClass =
     !isMobile && state === 'collapsed' ? 'cursor-pointer' : undefined;
 
+  const sidebarRootClass = cn(
+    railExpandHintClass,
+    '[&>[data-sidebar=sidebar]]:bg-gradient-to-t [&>[data-sidebar=sidebar]]:from-sidebar/85 [&>[data-sidebar=sidebar]]:to-sidebar',
+  );
+
   return (
     <Sidebar
       collapsible="icon"
       variant={variant}
-      className={railExpandHintClass}
+      className={sidebarRootClass}
       onClick={expandOnRailClick}
     >
       <SidebarHeader className={sidebarHeaderClass}>{sidebarHeaderContent}</SidebarHeader>
@@ -317,6 +350,7 @@ export function PrivateSidebar({ sidebar, header, pathname: pathnameProp, varian
       <SidebarContent className={sidebarContentClass}>
         {menuStartSlot}
         {renderedGroups}
+        {featuredSlot}
         {menuEndSlot}
       </SidebarContent>
 
@@ -327,3 +361,136 @@ export function PrivateSidebar({ sidebar, header, pathname: pathnameProp, varian
     </Sidebar>
   );
 }
+
+interface SidebarGroupRendererProps {
+  group: SidebarGroupConfig;
+  isActive: (href: string) => boolean;
+  navButtonClass: string;
+  sidebarGroupClass: string;
+  groupLabelUppercaseClass: string;
+  groupLabelPlainClass: string;
+  groupLabelStyle: SidebarGroupLabelStyle;
+  menuNav: typeof DENSITY[keyof typeof DENSITY];
+  collapsedRail: boolean;
+}
+
+function SidebarGroupRenderer({
+  group,
+  isActive,
+  navButtonClass,
+  sidebarGroupClass,
+  groupLabelUppercaseClass,
+  groupLabelPlainClass,
+  groupLabelStyle,
+  menuNav,
+  collapsedRail,
+}: SidebarGroupRendererProps) {
+  const hasLabel = Boolean(group.label && group.label.trim().length > 0);
+  const isCollapsible = Boolean(group.collapsible) && hasLabel && !collapsedRail;
+  const hideItemIcons = group.hideItemIcons ?? isCollapsible;
+
+  const hasActiveChild = React.useMemo(
+    () => group.items.some((item) => isActive(item.href)),
+    [group.items, isActive],
+  );
+
+  const [open, setOpen] = React.useState<boolean>(
+    isCollapsible ? Boolean(group.defaultOpen) || hasActiveChild : true,
+  );
+
+  React.useEffect(() => {
+    if (isCollapsible && hasActiveChild) setOpen(true);
+  }, [isCollapsible, hasActiveChild]);
+
+  const items = group.items.map((item: SidebarItem) => {
+    const tooltipText = item.tooltip ?? item.label;
+    const itemIcon = !hideItemIcons && item.icon ? (
+      <LucideIcon icon={item.icon} className={menuNav.iconClass} />
+    ) : null;
+    const itemClassName = hideItemIcons
+      ? cn(navButtonClass, 'pl-8')
+      : navButtonClass;
+    const badgeNode = item.badge ? (
+      <SidebarMenuBadge
+        className={item.badgeVariant === 'pill'
+          ? 'bg-primary/15 text-primary px-1.5 rounded-md font-medium'
+          : undefined}
+      >
+        {item.badge}
+      </SidebarMenuBadge>
+    ) : null;
+
+    return (
+      <SidebarMenuItem key={item.href}>
+        <SidebarMenuButton
+          asChild
+          isActive={isActive(item.href)}
+          size={menuNav.buttonSize}
+          tooltip={tooltipText}
+          className={itemClassName}
+        >
+          <Link href={item.href}>
+            {itemIcon}
+            <span>{item.label}</span>
+            {badgeNode}
+          </Link>
+        </SidebarMenuButton>
+      </SidebarMenuItem>
+    );
+  });
+
+  const labelClass = isCollapsible || groupLabelStyle === 'plain'
+    ? groupLabelPlainClass
+    : groupLabelUppercaseClass;
+
+  if (isCollapsible) {
+    const triggerIcon = group.icon ? (
+      <LucideIcon icon={group.icon} className={cn(menuNav.iconClass, 'shrink-0 text-sidebar-foreground/70')} />
+    ) : null;
+    return (
+      <SidebarGroup className={sidebarGroupClass}>
+        <Collapsible open={open} onOpenChange={setOpen} className="w-full">
+          <CollapsibleTrigger asChild>
+            <button
+              type="button"
+              className={cn(
+                'group/trig flex w-full items-center gap-2 rounded-md px-2 py-1.5',
+                'text-sm font-semibold text-sidebar-foreground',
+                'transition-colors hover:bg-sidebar-accent/40',
+                'data-[no-expand]', // marker so rail-expand click handler ignores it (pattern in PrivateSidebar)
+              )}
+              aria-expanded={open}
+              data-no-expand
+            >
+              {triggerIcon}
+              <span className="flex-1 truncate text-left">{group.label}</span>
+              <ChevronDown
+                className={cn(
+                  'h-4 w-4 shrink-0 text-sidebar-foreground/55 transition-transform duration-200',
+                  open && 'rotate-180',
+                )}
+                aria-hidden
+              />
+            </button>
+          </CollapsibleTrigger>
+          <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down">
+            <SidebarGroupContent>
+              <SidebarMenu className={cn(menuNav.menu, 'mt-1')}>{items}</SidebarMenu>
+            </SidebarGroupContent>
+          </CollapsibleContent>
+        </Collapsible>
+      </SidebarGroup>
+    );
+  }
+
+  return (
+    <SidebarGroup className={sidebarGroupClass}>
+      {hasLabel ? (
+        <SidebarGroupLabel className={labelClass}>{group.label}</SidebarGroupLabel>
+      ) : null}
+      <SidebarGroupContent>
+        <SidebarMenu className={menuNav.menu}>{items}</SidebarMenu>
+      </SidebarGroupContent>
+    </SidebarGroup>
+  );
+}

package/src/layouts/PrivateLayout/index.ts

@@ -3,5 +3,14 @@
  */
 
 export { PrivateLayout } from './PrivateLayout';
-export type { PrivateLayoutProps, SidebarItem, SidebarGroupConfig, SidebarConfig, HeaderConfig } from './PrivateLayout';
+export type {
+  PrivateLayoutProps,
+  SidebarItem,
+  SidebarGroupConfig,
+  SidebarConfig,
+  HeaderConfig,
+  SidebarActiveIndicator,
+  SidebarGroupLabelStyle,
+  SidebarFeaturedConfig,
+} from './PrivateLayout';