@djangocfg/layouts 2.1.591 → 2.1.592

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

@@ -1,13 +1,11 @@
 /**
- * Sidebar Nav Item Component
- *
- * Individual navigation item with icon, label, badge, and active state.
- * Memoized with shallow item comparison so badge number changes still re-render.
+ * Sidebar Nav Item — icon, label, optional badge. Active state is a surface
+ * plus `aria-current`; weight never changes, so labels do not jump.
  */
 
 'use client';
 
-import React, { memo, useMemo } from 'react';
+import React, { memo } from 'react';
 
 import {
   Link,
@@ -19,7 +17,6 @@ import { cn } from '@djangocfg/ui-core/lib';
 
 import { LucideIcon } from '../../../components';
 import { usePrivateLayoutContext } from '../context';
-import { useShellVisualState } from '../hooks';
 import type { SidebarItem } from '../types';
 
 interface SidebarNavItemProps {
@@ -27,111 +24,51 @@ interface SidebarNavItemProps {
   hideItemIcons?: boolean;
 }
 
-function SidebarNavItemRaw({ item, hideItemIcons }: SidebarNavItemProps) {
-  const { isActive, menuNav } = usePrivateLayoutContext();
-  const { content } = useShellVisualState();
-
-  const tooltipText = item.tooltip ?? item.label;
-
-  const itemIcon = useMemo(
-    () =>
-      !hideItemIcons && item.icon ? (
-        <LucideIcon icon={item.icon} className={menuNav.iconClass} />
-      ) : null,
-    [hideItemIcons, item.icon, menuNav.iconClass],
-  );
-
-  const hasBadge = Boolean(item.badge);
+const ITEM_CLASS = cn(
+  'rounded-lg border-0 font-normal shadow-none transition-colors duration-150',
+  'text-sidebar-foreground/90 hover:bg-sidebar-accent/70 hover:text-sidebar-foreground',
+  'data-[active=true]:bg-sidebar-accent data-[active=true]:font-normal data-[active=true]:text-sidebar-foreground',
+  '[&>svg]:text-sidebar-foreground/80 [&>svg]:opacity-100 hover:[&>svg]:text-sidebar-foreground',
+  'data-[active=true]:[&>svg]:text-sidebar-foreground',
+);
 
-  const collapsedBadgeDot = useMemo(
-    () =>
-      !content.showBadgeText && hasBadge ? (
-        <span className="absolute right-1 top-1 flex h-2 w-2">
-          <span className="inline-flex h-full w-full rounded-full bg-primary" />
-        </span>
-      ) : null,
-    [content.showBadgeText, hasBadge],
-  );
-
-  const expandedBadgeNode = useMemo(
-    () =>
-      content.showBadgeText && hasBadge ? (
-        <SidebarMenuBadge
-          className={cn(
-            item.badgeVariant === 'pill'
-              ? 'bg-primary/15 text-primary px-1.5 rounded-md font-medium'
-              : undefined,
-          )}
-        >
-          {item.badge}
-        </SidebarMenuBadge>
-      ) : null,
-    [content.showBadgeText, hasBadge, item.badgeVariant, item.badge],
-  );
-
-  const isItemActive = isActive(item.href);
-
-  const buttonClass = useMemo(
-    () =>
-      cn(
-        'group/nav relative border-0 font-medium shadow-none transition-colors',
-        'text-sidebar-foreground/80',
-        'data-[active=true]:font-semibold data-[active=true]:text-sidebar-accent-foreground',
-        'hover:bg-sidebar-accent/70 hover:text-sidebar-accent-foreground',
-        '[&>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',
-        hideItemIcons && 'pl-8',
-        content.showLabels && '[&>span]:!inline !p-2 !justify-start',
-      ),
-    [hideItemIcons, content.showLabels],
-  );
+function SidebarNavItemRaw({ item, hideItemIcons }: SidebarNavItemProps) {
+  const { isActive, geometry } = usePrivateLayoutContext();
+  const active = isActive(item.href);
 
   return (
     <SidebarMenuItem>
       <SidebarMenuButton
         asChild
-        isActive={isItemActive}
-        size={menuNav.buttonSize}
-        tooltip={content.showTooltips ? tooltipText : undefined}
-        className={buttonClass}
+        isActive={active}
+        className={cn(ITEM_CLASS, geometry.item, hideItemIcons && 'pl-8')}
       >
-        <Link href={item.href}>
-          {itemIcon}
+        <Link href={item.href} aria-current={active ? 'page' : undefined}>
+          {!hideItemIcons && item.icon ? <LucideIcon icon={item.icon} /> : null}
           <span>{item.label}</span>
-          {expandedBadgeNode}
+          {item.badge ? (
+            <SidebarMenuBadge
+              className={cn(
+                item.badgeVariant === 'pill' && 'rounded-md bg-primary/15 px-1.5 font-medium text-primary',
+              )}
+            >
+              {item.badge}
+            </SidebarMenuBadge>
+          ) : null}
         </Link>
       </SidebarMenuButton>
-      {collapsedBadgeDot}
     </SidebarMenuItem>
   );
 }
 
-/**
- * Shallow equality for SidebarItem — compares primitive fields so that
- * badge number changes (e.g. 3 → 5) still trigger a re-render, but
- * object-reference churn from parent re-renders is ignored.
- */
-function itemShallowEqual(a: SidebarItem, b: SidebarItem): boolean {
-  return (
-    a.href === b.href &&
-    a.label === b.label &&
-    a.icon === b.icon &&
-    a.badge === b.badge &&
-    a.badgeVariant === b.badgeVariant &&
-    a.tooltip === b.tooltip
-  );
-}
-
-/**
- * Memoised leaf component. Re-renders only when:
- * - `hideItemIcons` changes, or
- * - any field inside `item` changes (badge count, label, href, etc.).
- * Parent re-renders with the same item data are skipped.
- */
-export const SidebarNavItem = memo(SidebarNavItemRaw, (prev, next) => {
-  return (
-    prev.hideItemIcons === next.hideItemIcons &&
-    itemShallowEqual(prev.item, next.item)
-  );
-});
+const itemEqual = (a: SidebarItem, b: SidebarItem) =>
+  a.href === b.href &&
+  a.label === b.label &&
+  a.icon === b.icon &&
+  a.badge === b.badge &&
+  a.badgeVariant === b.badgeVariant;
+
+export const SidebarNavItem = memo(
+  SidebarNavItemRaw,
+  (prev, next) => prev.hideItemIcons === next.hideItemIcons && itemEqual(prev.item, next.item),
+);

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

@@ -0,0 +1,34 @@
+/**
+ * Peek panel: the full sidebar floated over the page while it is collapsed.
+ * Opened and held by `SidebarPeekProvider`.
+ */
+
+'use client';
+
+import React from 'react';
+
+import { useSidebarPeek } from '../hooks';
+import { SidebarBody } from './SidebarBody';
+import { SidebarResizeHandle } from './SidebarResizeHandle';
+
+export function SidebarPeek() {
+  const peek = useSidebarPeek();
+  if (!peek?.open) return null;
+
+  return (
+    <div
+      data-sidebar="peek"
+      role="complementary"
+      aria-label="Navigation"
+      {...peek.panelProps}
+      className={[
+        'fixed bottom-2 left-2 top-2 z-50 flex w-(--sidebar-width) flex-col overflow-hidden',
+        'rounded-xl border border-sidebar-border bg-sidebar text-sidebar-foreground shadow-2xl',
+        'animate-in fade-in-0 slide-in-from-left-4 duration-150',
+      ].join(' ')}
+    >
+      <SidebarBody />
+      <SidebarResizeHandle />
+    </div>
+  );
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Drag handle on the sidebar's right edge. Pointer drag, arrow keys and
+ * double-click-to-reset; the width itself lives in `useSidebarWidth`.
+ */
+
+'use client';
+
+import React, { useRef } from 'react';
+
+import { useSidebarWidthContext } from '../hooks';
+
+const KEY_STEP = 16;
+
+export function SidebarResizeHandle() {
+  const sidebarWidth = useSidebarWidthContext();
+  const origin = useRef<{ x: number; width: number } | null>(null);
+
+  if (!sidebarWidth?.enabled) return null;
+  const { width, min, max, dragging, setWidth, setDragging, reset } = sidebarWidth;
+
+  const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    if (e.button !== 0) return;
+    e.currentTarget.setPointerCapture(e.pointerId);
+    origin.current = { x: e.clientX, width };
+    setDragging(true);
+  };
+
+  const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    if (!origin.current) return;
+    setWidth(origin.current.width + e.clientX - origin.current.x);
+  };
+
+  const endDrag = () => {
+    origin.current = null;
+    setDragging(false);
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    const next =
+      e.key === 'ArrowLeft' ? width - KEY_STEP
+      : e.key === 'ArrowRight' ? width + KEY_STEP
+      : e.key === 'Home' ? min
+      : e.key === 'End' ? max
+      : null;
+    if (next === null) return;
+    e.preventDefault();
+    e.stopPropagation();
+    setWidth(next);
+  };
+
+  return (
+    <div
+      role="separator"
+      aria-orientation="vertical"
+      aria-label="Resize sidebar"
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-valuenow={width}
+      tabIndex={0}
+      data-dragging={dragging || undefined}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={endDrag}
+      onPointerCancel={endDrag}
+      onDoubleClick={reset}
+      onKeyDown={onKeyDown}
+      className={[
+        'absolute inset-y-0 right-0 z-20 hidden w-2 cursor-col-resize touch-none outline-none md:block',
+        // 2px primary line on the border; fades in after a short hover delay.
+        'after:absolute after:inset-y-0 after:right-0 after:w-0.5 after:bg-transparent',
+        'after:transition-colors after:duration-150',
+        'hover:after:bg-primary/70 hover:after:delay-100 focus-visible:after:bg-primary data-[dragging]:after:bg-primary',
+      ].join(' ')}
+    />
+  );
+}

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

@@ -1,71 +1,32 @@
 /**
- * Sidebar Slots Component
- *
- * Renders optional content slots: menuStart, menuEnd, featured CTA, footer.
+ * Optional slots around the nav groups: menuStart, featured, menuEnd, footer.
  */
 
 'use client';
 
-import React, { memo, useMemo } from 'react';
+import React, { memo } from 'react';
 
-import { SidebarFeatured } from './SidebarFeatured';
 import { usePrivateLayoutContext } from '../context';
-import { useShellVisualState } from '../hooks';
+import { SidebarFeatured } from './SidebarFeatured';
+
+const SLOT = 'w-full min-w-0 shrink-0 px-2';
 
 function SidebarSlotsRaw() {
   const { sidebar } = usePrivateLayoutContext();
-  const { content } = useShellVisualState();
-
-  const menuStartSlot = useMemo(
-    () =>
-      sidebar?.menuStart ? (
-        <div className="w-full min-w-0 shrink-0 px-2">{sidebar.menuStart}</div>
-      ) : null,
-    [sidebar?.menuStart],
-  );
-
-  const menuEndSlot = useMemo(
-    () =>
-      sidebar?.menuEnd ? (
-        <div className="w-full min-w-0 shrink-0 px-2">{sidebar.menuEnd}</div>
-      ) : null,
-    [sidebar?.menuEnd],
-  );
-
-  const featuredSlot = useMemo(
-    () =>
-      sidebar?.featured ? (
-        <div className="w-full min-w-0 shrink-0 px-2">
-          <SidebarFeatured config={sidebar.featured} />
-        </div>
-      ) : null,
-    [sidebar?.featured],
-  );
-
-  const footerExtra = useMemo(
-    () =>
-      sidebar?.footer ? (
-        <div className="mb-2">{sidebar.footer}</div>
-      ) : null,
-    [sidebar?.footer],
-  );
-
-  if (content.hideSlots) return null;
+  if (!sidebar) return null;
 
   return (
     <>
-      {menuStartSlot}
-      {featuredSlot}
-      {menuEndSlot}
-      {footerExtra}
+      {sidebar.menuStart ? <div className={SLOT}>{sidebar.menuStart}</div> : null}
+      {sidebar.featured ? (
+        <div className={SLOT}>
+          <SidebarFeatured config={sidebar.featured} />
+        </div>
+      ) : null}
+      {sidebar.menuEnd ? <div className={SLOT}>{sidebar.menuEnd}</div> : null}
+      {sidebar.footer ? <div className={SLOT}>{sidebar.footer}</div> : null}
     </>
   );
 }
 
-/**
- * Memoised slots wrapper. Skips re-renders when the sidebar config object
- * reference stays the same. The slot ReactNodes themselves (menuStart,
- * menuEnd, footer) are *not* deeply compared — they remain reactive because
- * the consumer is expected to pass a new ReactNode when slot content changes.
- */
 export const SidebarSlots = memo(SidebarSlotsRaw);

package/src/layouts/PrivateLayout/components/index.ts

@@ -6,8 +6,4 @@ export { PrivateSidebar } from './PrivateSidebar';
 export { PrivateContent } from './PrivateContent';
 export { ForbiddenState } from './ForbiddenState';
 export type { ForbiddenStateProps } from './ForbiddenState';
-export { SidebarBrand } from './SidebarBrand';
 export { SidebarBrandSwitcher } from './SidebarBrandSwitcher';
-export { SidebarNavGroup } from './SidebarNavGroup';
-export { SidebarNavItem } from './SidebarNavItem';
-export { SidebarSlots } from './SidebarSlots';

package/src/layouts/PrivateLayout/context.tsx

@@ -1,76 +1,31 @@
 /**
  * PrivateLayout Context
  *
- * Provides UI state for the private layout shell:
- * - sidebar state (collapsed/expanded, mobile)
- * - nav density based on item count
- * - active indicator style
- * - group label style
- * - current pathname
+ * What the sidebar parts share: config, the active-route check, brand
+ * identity and the row geometry for the current form factor.
  */
 
 'use client';
 
 import React, { createContext, useContext, useMemo } from 'react';
 
-import type {
-  HeaderConfig,
-  SidebarActiveIndicator,
-  SidebarConfig,
-  SidebarGroupLabelStyle,
-  SidebarItem,
-} from './types';
-
-import { DENSITY, RAIL_NAV } from './density';
-import type { NavDensity } from './density';
-
-// ============================================================================
-// Context Type
-// ============================================================================
+import { NAV_GEOMETRY } from './geometry';
+import type { NavGeometry } from './geometry';
+import type { HeaderConfig, SidebarConfig, SidebarItem } from './types';
 
 export interface PrivateLayoutContextValue {
-  /** Sidebar configuration */
   sidebar: SidebarConfig | undefined;
-  /** Header configuration */
   header: HeaderConfig | undefined;
-  /** Current pathname for active highlighting */
   pathname: string;
-  /** Whether the sidebar is in mobile mode */
   isMobile: boolean;
-  /** Whether the sidebar is expanded (vs collapsed icon rail) */
-  isExpanded: boolean;
-  /** Whether the sidebar is collapsed to icon rail */
-  isCollapsed: boolean;
-  /** Nav density based on total item count */
-  density: NavDensity;
-  /** Density tokens for the current state */
-  menuNav: (typeof DENSITY)[NavDensity];
-  /** Active indicator style */
-  activeIndicator: SidebarActiveIndicator;
-  /** Group label style */
-  groupLabelStyle: SidebarGroupLabelStyle;
-  /** All nav items flattened */
+  geometry: NavGeometry;
   allItems: SidebarItem[];
-  /** Check if a href is active */
   isActive: (href: string) => boolean;
-  /** Whether menuStart slot should be shown */
-  showMenuStart: boolean;
-  /** Whether menuEnd slot should be shown */
-  showMenuEnd: boolean;
-  /** Whether featured CTA should be shown */
-  showFeatured: boolean;
-  /** Home href */
   homeHref: string;
-  /** Brand title derived from header */
   brandTitle: string;
-  /** Brand monogram derived from header/title */
   brandMonogram: string;
 }
 
-// ============================================================================
-// Context
-// ============================================================================
-
 const PrivateLayoutContext = createContext<PrivateLayoutContextValue | null>(null);
 
 export function usePrivateLayoutContext(): PrivateLayoutContextValue {
@@ -81,30 +36,20 @@ export function usePrivateLayoutContext(): PrivateLayoutContextValue {
   return ctx;
 }
 
-// ============================================================================
-// Provider Props
-// ============================================================================
-
 interface PrivateLayoutProviderProps {
   children: React.ReactNode;
   sidebar: SidebarConfig | undefined;
   header: HeaderConfig | undefined;
   pathname: string;
   isMobile: boolean;
-  state: 'expanded' | 'collapsed';
 }
 
-// ============================================================================
-// Provider
-// ============================================================================
-
 export function PrivateLayoutProvider({
   children,
   sidebar,
   header,
   pathname,
   isMobile,
-  state,
 }: PrivateLayoutProviderProps) {
   const homeHref = sidebar?.homeHref || '/';
   const brandTitle = header?.title?.trim() || 'Dashboard';
@@ -119,12 +64,7 @@ export function PrivateLayoutProvider({
     [sidebar?.groups],
   );
 
-  const density: NavDensity = sidebar?.density ?? 'default';
-  const isExpanded = state === 'expanded';
-  const isCollapsed = state === 'collapsed';
-
-  const menuNav = isCollapsed ? RAIL_NAV : DENSITY[density];
-
+  // The most specific item wins: `/a` is not active on `/a/b` when `/a/b` is its own item.
   const isActive = React.useCallback(
     (href: string) => {
       const matches = pathname === href || pathname.startsWith(`${href}/`);
@@ -139,66 +79,21 @@ export function PrivateLayoutProvider({
     [pathname, allItems],
   );
 
-  const collapsedRail = !isMobile && isCollapsed;
-
-  const hasMenuStart = sidebar?.menuStart != null && sidebar.menuStart !== false;
-  const hasMenuEnd = sidebar?.menuEnd != null && sidebar.menuEnd !== false;
-
-  const showMenuStart =
-    hasMenuStart && (!collapsedRail || sidebar?.menuStartShowOnCollapsed === true);
-  const showMenuEnd =
-    hasMenuEnd && (!collapsedRail || sidebar?.menuEndShowOnCollapsed === true);
-  const showFeatured = Boolean(sidebar?.featured) && !collapsedRail;
-
-  const activeIndicator = sidebar?.activeIndicator ?? 'background';
-  const groupLabelStyle = sidebar?.groupLabelStyle ?? 'uppercase';
-
   const value = useMemo(
     () => ({
       sidebar,
       header,
       pathname,
       isMobile,
-      isExpanded,
-      isCollapsed,
-      density,
-      menuNav,
-      activeIndicator,
-      groupLabelStyle,
+      geometry: isMobile ? NAV_GEOMETRY.mobile : NAV_GEOMETRY.desktop,
       allItems,
       isActive,
-      showMenuStart,
-      showMenuEnd,
-      showFeatured,
       homeHref,
       brandTitle,
       brandMonogram,
     }),
-    [
-      sidebar,
-      header,
-      pathname,
-      isMobile,
-      isExpanded,
-      isCollapsed,
-      density,
-      menuNav,
-      activeIndicator,
-      groupLabelStyle,
-      allItems,
-      isActive,
-      showMenuStart,
-      showMenuEnd,
-      showFeatured,
-      homeHref,
-      brandTitle,
-      brandMonogram,
-    ],
+    [sidebar, header, pathname, isMobile, allItems, isActive, homeHref, brandTitle, brandMonogram],
   );
 
-  return (
-    <PrivateLayoutContext.Provider value={value}>
-      {children}
-    </PrivateLayoutContext.Provider>
-  );
+  return <PrivateLayoutContext.Provider value={value}>{children}</PrivateLayoutContext.Provider>;
 }

package/src/layouts/PrivateLayout/geometry.ts

@@ -0,0 +1,17 @@
+/**
+ * Sidebar row geometry. Two sizes only: a pointer-sized desktop row and a
+ * 44px touch row for the mobile drawer.
+ */
+
+export const NAV_GEOMETRY = {
+  desktop: {
+    item: 'h-8 gap-2.5 px-2.5 text-base [&>svg]:size-4',
+    label: 'h-7 px-2.5 text-xs',
+  },
+  mobile: {
+    item: 'h-11 gap-3 px-3 text-lg [&>svg]:size-5',
+    label: 'h-8 px-3 text-sm',
+  },
+} as const;
+
+export type NavGeometry = (typeof NAV_GEOMETRY)[keyof typeof NAV_GEOMETRY];

package/src/layouts/PrivateLayout/hooks/index.ts

@@ -4,6 +4,7 @@
 
 export { useAuthGuard } from './useAuthGuard';
 export { useLayoutVisual } from './useLayoutVisual';
-export { useShellVisualState } from './useShellVisualState';
 export { useSidebarKeyboard } from './useSidebarKeyboard';
 export { useSidebarDefaultOpen } from './useSidebarDefaultOpen';
+export { SidebarPeekProvider, usePeekPin, useSidebarPeek } from './useSidebarPeek';
+export { SidebarWidthContext, useSidebarWidth, useSidebarWidthContext } from './useSidebarWidth';

package/src/layouts/PrivateLayout/hooks/useLayoutVisual.ts

@@ -12,7 +12,7 @@ import type { LayoutVisualConfig } from '../../types';
 export function resolveProviderStyle(
   visual: LayoutVisualConfig | undefined,
 ): React.CSSProperties | undefined {
-  if ((visual?.variant ?? 'boxed') !== 'boxed') return undefined;
+  if ((visual?.variant ?? 'full-bleed') !== 'boxed') return undefined;
   const inset = normaliseInset(visual?.inset);
   return {
     ['--app-shell-inset-x' as string]: `${inset.x}px`,
@@ -47,7 +47,7 @@ const BOXED_RADIUS_REM: Record<NonNullable<LayoutVisualConfig['radius']>, string
 };
 
 export function resolveInsetClassName(visual: LayoutVisualConfig | undefined): string {
-  if ((visual?.variant ?? 'boxed') !== 'boxed') return 'flex flex-col';
+  if ((visual?.variant ?? 'full-bleed') !== 'boxed') return 'flex flex-col';
   const border = visual?.border ?? true;
   return border ? `${BOXED_INSET_CLASS} ${BOXED_INSET_BORDER_CLASS}` : BOXED_INSET_CLASS;
 }
@@ -75,7 +75,7 @@ export function resolveProviderClassName(
   // the inner scroll-area (PrivateContent) is the only scroll surface. Without
   // this, SidebarProvider grows via min-h-svh and the whole page scrolls.
   const base = 'h-svh overflow-hidden';
-  if ((visual?.variant ?? 'boxed') !== 'boxed') return base;
+  if ((visual?.variant ?? 'full-bleed') !== 'boxed') return base;
   // `max-md:!bg-background` neutralises shadcn-sidebar's built-in
   // `has-[[data-variant=inset]]:bg-sidebar` below md so the mobile Drawer shell
   // doesn't paint the whole viewport with the canvas tint.
@@ -100,7 +100,7 @@ export interface LayoutVisualResult {
 
 export function useLayoutVisual(visual: LayoutVisualConfig | undefined): LayoutVisualResult {
   return useMemo(() => {
-    const variant = visual?.variant ?? 'boxed';
+    const variant = visual?.variant ?? 'full-bleed';
     const sidebarVariant = variant === 'boxed' ? 'inset' : 'sidebar';
 
     return {