@djangocfg/layouts 2.1.591 → 2.1.593

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 {

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

@@ -1,27 +1,11 @@
 /**
- * Sidebar Keyboard Navigation Hook
- *
- * Global shortcuts:
- * - Ctrl/Cmd + B  → toggle sidebar expanded/collapsed (desktop)
- * - Escape        → close mobile drawer / hover overlay
- *
- * Focus-trap navigation inside the sidebar:
- * - ArrowDown / ArrowUp  → move focus between focusable items
- * - Home                 → first focusable item
- * - End                  → last focusable item
- * - Enter / Space        → activate (native behaviour, no override)
+ * Sidebar focus navigation (ArrowUp/Down, Home, End between focusable rows).
+ * Cmd/Ctrl+B belongs to `SidebarProvider`; the mobile drawer closes itself on Escape.
  */
 
 'use client';
 
-import { useCallback, useEffect, useRef } from 'react';
-
-import { useSidebar } from '@djangocfg/ui-core/components';
-
-interface UseSidebarKeyboardOptions {
-  /** Whether keyboard shortcuts are active */
-  enabled?: boolean;
-}
+import { useCallback, useRef } from 'react';
 
 const FOCUSABLE_SELECTOR = [
   'a[href]',
@@ -29,83 +13,39 @@ const FOCUSABLE_SELECTOR = [
   '[tabindex]:not([tabindex="-1"])',
 ].join(', ');
 
-export function useSidebarKeyboard({ enabled = true }: UseSidebarKeyboardOptions = {}) {
-  const { toggleSidebar, setOpenMobile, isMobile, openMobile } = useSidebar();
+export function useSidebarKeyboard() {
   const sidebarRef = useRef<HTMLElement | null>(null);
 
-  // ---------------------------------------------------------------------------
-  // Global shortcuts (Ctrl/Cmd+B, Escape)
-  // ---------------------------------------------------------------------------
-
-  useEffect(() => {
-    if (!enabled) return;
-
-    const onKeyDown = (e: KeyboardEvent) => {
-      // Ctrl/Cmd + B → toggle sidebar
-      if ((e.ctrlKey || e.metaKey) && e.key === 'b') {
-        e.preventDefault();
-        if (isMobile) {
-          setOpenMobile(!openMobile);
-        } else {
-          toggleSidebar();
-        }
+  const handleSidebarKeyDown = useCallback((e: React.KeyboardEvent<HTMLElement>) => {
+    const root = sidebarRef.current;
+    if (!root) return;
+
+    const focusables = Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+      (el) => el.offsetParent !== null,
+    );
+    const current = focusables.indexOf(document.activeElement as HTMLElement);
+    if (current === -1) return;
+
+    let next = current;
+    switch (e.key) {
+      case 'ArrowDown':
+        next = (current + 1) % focusables.length;
+        break;
+      case 'ArrowUp':
+        next = (current - 1 + focusables.length) % focusables.length;
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = focusables.length - 1;
+        break;
+      default:
         return;
-      }
-
-      // Escape → close mobile drawer or hover overlay
-      if (e.key === 'Escape') {
-        if (isMobile && openMobile) {
-          setOpenMobile(false);
-        }
-      }
-    };
-
-    window.addEventListener('keydown', onKeyDown);
-    return () => window.removeEventListener('keydown', onKeyDown);
-  }, [enabled, isMobile, openMobile, setOpenMobile, toggleSidebar]);
-
-  // ---------------------------------------------------------------------------
-  // Focus navigation inside sidebar (arrow keys, Home, End)
-  // ---------------------------------------------------------------------------
-
-  const handleSidebarKeyDown = useCallback(
-    (e: React.KeyboardEvent<HTMLElement>) => {
-      if (!sidebarRef.current) return;
-
-      const focusables = Array.from(
-        sidebarRef.current.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
-      ).filter((el) => !el.hasAttribute('disabled') && el.offsetParent !== null);
-
-      const currentIndex = focusables.indexOf(document.activeElement as HTMLElement);
-      if (currentIndex === -1) return;
-
-      let nextIndex = currentIndex;
-
-      switch (e.key) {
-        case 'ArrowDown':
-          e.preventDefault();
-          nextIndex = (currentIndex + 1) % focusables.length;
-          break;
-        case 'ArrowUp':
-          e.preventDefault();
-          nextIndex = (currentIndex - 1 + focusables.length) % focusables.length;
-          break;
-        case 'Home':
-          e.preventDefault();
-          nextIndex = 0;
-          break;
-        case 'End':
-          e.preventDefault();
-          nextIndex = focusables.length - 1;
-          break;
-        default:
-          return;
-      }
-
-      focusables[nextIndex]?.focus();
-    },
-    [],
-  );
+    }
+    e.preventDefault();
+    focusables[next]?.focus();
+  }, []);
 
   const setSidebarRef = useCallback((node: HTMLElement | null) => {
     sidebarRef.current = node;

package/src/layouts/PrivateLayout/hooks/useSidebarPeek.tsx

@@ -0,0 +1,151 @@
+/**
+ * Peek: while the sidebar is collapsed, hovering its trigger zone floats the
+ * full sidebar over the page. The panel keeps itself open while the pointer is
+ * on it, or while a menu opened from it (account, workspace switcher) is open.
+ */
+
+'use client';
+
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import { useSidebar } from '@djangocfg/ui-core/components';
+
+// Opens on entry with no delay, then stays at least MIN_OPEN_MS even if the
+// pointer only grazed the zone, so a user who didn't notice it still sees it.
+const MIN_OPEN_MS = 900;
+const CLOSE_DELAY_MS = 300;
+
+interface PointerHandlers {
+  onPointerEnter: (e: React.PointerEvent) => void;
+  onPointerLeave: (e: React.PointerEvent) => void;
+}
+
+export interface SidebarPeek {
+  /** True while the sidebar is collapsed on desktop: the trigger zone shows. */
+  enabled: boolean;
+  open: boolean;
+  zoneProps: PointerHandlers;
+  panelProps: PointerHandlers;
+  close: () => void;
+  /** Keep the panel open while something launched from it is open. */
+  pin: (pinned: boolean) => void;
+}
+
+const PeekContext = createContext<SidebarPeek | null>(null);
+
+export function useSidebarPeek(): SidebarPeek | null {
+  return useContext(PeekContext);
+}
+
+/** Pins the peek panel for as long as `active` is true. */
+export function usePeekPin(active: boolean): void {
+  const peek = useContext(PeekContext);
+  const pin = peek?.pin;
+  useEffect(() => {
+    if (!pin) return;
+    pin(active);
+    return () => pin(false);
+  }, [pin, active]);
+}
+
+interface SidebarPeekProviderProps {
+  pathname: string;
+  children: React.ReactNode;
+}
+
+export function SidebarPeekProvider({ pathname, children }: SidebarPeekProviderProps) {
+  const { state, isMobile } = useSidebar();
+  const enabled = !isMobile && state === 'collapsed';
+
+  const [open, setOpen] = useState(false);
+  const pinned = useRef(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const openedAt = useRef(0);
+
+  const cancel = useCallback(() => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+  }, []);
+
+  const scheduleClose = useCallback(() => {
+    cancel();
+    if (pinned.current) return;
+    const grace = openedAt.current + MIN_OPEN_MS - Date.now();
+    timer.current = setTimeout(() => setOpen(false), Math.max(CLOSE_DELAY_MS, grace));
+  }, [cancel]);
+
+  const show = useCallback(() => {
+    cancel();
+    setOpen((was) => {
+      if (!was) openedAt.current = Date.now();
+      return true;
+    });
+  }, [cancel]);
+
+  const close = useCallback(() => {
+    cancel();
+    setOpen(false);
+  }, [cancel]);
+
+  const pin = useCallback(
+    (value: boolean) => {
+      pinned.current = value;
+      if (!value) scheduleClose();
+    },
+    [scheduleClose],
+  );
+
+  // Hover is a mouse affordance; touch taps the trigger to dock instead.
+  const zoneProps = useMemo<PointerHandlers>(
+    () => ({
+      onPointerEnter: (e) => {
+        if (e.pointerType !== 'mouse') return;
+        show();
+      },
+      onPointerLeave: scheduleClose,
+    }),
+    [show, scheduleClose],
+  );
+
+  const panelProps = useMemo<PointerHandlers>(
+    () => ({
+      onPointerEnter: show,
+      onPointerLeave: scheduleClose,
+    }),
+    [show, scheduleClose],
+  );
+
+  useEffect(() => {
+    if (!enabled) close();
+  }, [enabled, close]);
+
+  useEffect(() => {
+    close();
+  }, [pathname, close]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') close();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, close]);
+
+  useEffect(() => cancel, [cancel]);
+
+  const value = useMemo<SidebarPeek>(
+    () => ({ enabled, open: enabled && open, zoneProps, panelProps, close, pin }),
+    [enabled, open, zoneProps, panelProps, close, pin],
+  );
+
+  return <PeekContext.Provider value={value}>{children}</PeekContext.Provider>;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Sidebar width: the user drags the edge, the choice is remembered.
+ *
+ * The width is one CSS variable (`--sidebar-width`) on the provider, so the
+ * docked sidebar, its spacer and the peek panel all follow it with no prop
+ * plumbing.
+ */
+
+'use client';
+
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import type { CSSProperties } from 'react';
+
+const STORAGE_KEY = 'cfg.layouts.sidebar-width';
+const DEFAULT_WIDTH = 256; // 16rem
+const MIN_WIDTH = 224; // 14rem
+const MAX_WIDTH = 384; // 24rem
+
+const clamp = (px: number) => Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, Math.round(px)));
+
+function readStored(): number | null {
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    const px = raw ? Number(raw) : NaN;
+    return Number.isFinite(px) ? clamp(px) : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface SidebarWidth {
+  enabled: boolean;
+  width: number;
+  min: number;
+  max: number;
+  dragging: boolean;
+  setWidth: (px: number) => void;
+  setDragging: (value: boolean) => void;
+  reset: () => void;
+  /** CSS variables for the provider element. */
+  style: CSSProperties | undefined;
+}
+
+export function useSidebarWidth(enabled: boolean): SidebarWidth {
+  const [width, setWidthState] = useState(DEFAULT_WIDTH);
+  const [dragging, setDragging] = useState(false);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const stored = readStored();
+    if (stored) setWidthState(stored);
+  }, [enabled]);
+
+  // Persist once the drag ends, not on every pointer move.
+  useEffect(() => {
+    if (!enabled || dragging) return;
+    try {
+      if (width === DEFAULT_WIDTH) window.localStorage.removeItem(STORAGE_KEY);
+      else window.localStorage.setItem(STORAGE_KEY, String(width));
+    } catch {
+      // Storage unavailable: the width simply lasts for the session.
+    }
+  }, [enabled, dragging, width]);
+
+  const setWidth = useCallback((px: number) => setWidthState(clamp(px)), []);
+  const reset = useCallback(() => setWidthState(DEFAULT_WIDTH), []);
+
+  const style = useMemo<CSSProperties | undefined>(
+    () => (enabled ? ({ '--sidebar-width': `${width}px` } as CSSProperties) : undefined),
+    [enabled, width],
+  );
+
+  return useMemo(
+    () => ({ enabled, width, min: MIN_WIDTH, max: MAX_WIDTH, dragging, setWidth, setDragging, reset, style }),
+    [enabled, width, dragging, setWidth, reset, style],
+  );
+}
+
+export const SidebarWidthContext = createContext<SidebarWidth | null>(null);
+
+export function useSidebarWidthContext(): SidebarWidth | null {
+  return useContext(SidebarWidthContext);
+}