@djangocfg/layouts 2.1.356 → 2.1.357

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

@@ -0,0 +1,71 @@
+/**
+ * Sidebar Slots Component
+ *
+ * Renders optional content slots: menuStart, menuEnd, featured CTA, footer.
+ */
+
+'use client';
+
+import React, { memo, useMemo } from 'react';
+
+import { SidebarFeatured } from './SidebarFeatured';
+import { usePrivateLayoutContext } from '../context';
+import { useShellVisualState } from '../hooks';
+
+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;
+
+  return (
+    <>
+      {menuStartSlot}
+      {featuredSlot}
+      {menuEndSlot}
+      {footerExtra}
+    </>
+  );
+}
+
+/**
+ * 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

@@ -4,3 +4,7 @@
 
 export { PrivateSidebar } from './PrivateSidebar';
 export { PrivateContent } from './PrivateContent';
+export { SidebarBrand } from './SidebarBrand';
+export { SidebarNavGroup } from './SidebarNavGroup';
+export { SidebarNavItem } from './SidebarNavItem';
+export { SidebarSlots } from './SidebarSlots';

package/src/layouts/PrivateLayout/context.tsx

@@ -0,0 +1,211 @@
+/**
+ * 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
+ */
+
+'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
+// ============================================================================
+
+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;
+  /** Whether the sidebar is temporarily hover-expanded overlay */
+  isHoverExpanded: 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 */
+  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 {
+  const ctx = useContext(PrivateLayoutContext);
+  if (!ctx) {
+    throw new Error('usePrivateLayoutContext must be used within a PrivateLayoutProvider');
+  }
+  return ctx;
+}
+
+// ============================================================================
+// Provider Props
+// ============================================================================
+
+interface PrivateLayoutProviderProps {
+  children: React.ReactNode;
+  sidebar: SidebarConfig | undefined;
+  header: HeaderConfig | undefined;
+  pathname: string;
+  isMobile: boolean;
+  state: 'expanded' | 'collapsed';
+  isHoverExpanded?: boolean;
+}
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export function PrivateLayoutProvider({
+  children,
+  sidebar,
+  header,
+  pathname,
+  isMobile,
+  state,
+  isHoverExpanded = false,
+}: PrivateLayoutProviderProps) {
+  const homeHref = sidebar?.homeHref || '/';
+  const brandTitle = header?.title?.trim() || 'Dashboard';
+  const brandMonogram = (
+    header?.brandLetter?.trim().charAt(0) ||
+    brandTitle.charAt(0) ||
+    'D'
+  ).toUpperCase();
+
+  const allItems = useMemo(
+    () => sidebar?.groups.flatMap((g) => g.items) ?? [],
+    [sidebar?.groups],
+  );
+
+  const density: NavDensity = sidebar?.density ?? 'default';
+  const isExpanded = state === 'expanded';
+  const isCollapsed = state === 'collapsed';
+
+  /** Expanded or hover-expanded: follow item-count tier; collapsed rail: fixed `default` sizing so icons stay uniform. */
+  const menuNav = isCollapsed && !isHoverExpanded ? RAIL_NAV : DENSITY[density];
+
+  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 collapsedRail = !isMobile && isCollapsed && !isHoverExpanded;
+
+  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,
+      isHoverExpanded,
+      density,
+      menuNav,
+      activeIndicator,
+      groupLabelStyle,
+      allItems,
+      isActive,
+      showMenuStart,
+      showMenuEnd,
+      showFeatured,
+      homeHref,
+      brandTitle,
+      brandMonogram,
+    }),
+    [
+      sidebar,
+      header,
+      pathname,
+      isMobile,
+      isExpanded,
+      isCollapsed,
+      isHoverExpanded,
+      density,
+      menuNav,
+      activeIndicator,
+      groupLabelStyle,
+      allItems,
+      isActive,
+      showMenuStart,
+      showMenuEnd,
+      showFeatured,
+      homeHref,
+      brandTitle,
+      brandMonogram,
+    ],
+  );
+
+  return (
+    <PrivateLayoutContext.Provider value={value}>
+      {children}
+    </PrivateLayoutContext.Provider>
+  );
+}

package/src/layouts/PrivateLayout/density.ts

@@ -0,0 +1,48 @@
+/**
+ * Nav Density Tokens
+ *
+ * Density presets for sidebar navigation items.
+ * The active preset is chosen via the `density` prop on `SidebarConfig`;
+ * when omitted it defaults to `'default'`.
+ */
+
+export type NavDensity = 'comfortable' | 'default' | 'compact';
+
+export const DENSITY = {
+  comfortable: {
+    menu: 'gap-1.5',
+    group: 'gap-2',
+    groupPad: 'px-2 py-1',
+    label:
+      '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',
+    headerRowInset: 'pl-2',
+  },
+  default: {
+    menu: 'gap-1',
+    group: 'gap-1.5',
+    groupPad: 'px-2 py-1',
+    label:
+      '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-1.5',
+  },
+  compact: {
+    menu: 'gap-0.5',
+    group: 'gap-0.5',
+    groupPad: 'px-2 py-0.5',
+    label:
+      '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-1.5',
+  },
+} as const;
+
+/** Icon rail: always the same geometry — ignore comfortable/compact. */
+export const RAIL_NAV = DENSITY.default;

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

@@ -0,0 +1,13 @@
+/**
+ * PrivateLayout Hooks
+ */
+
+export { useAuthGuard } from './useAuthGuard';
+export { useLayoutVisual } from './useLayoutVisual';
+export {
+  useHoverExpand,
+  blockSidebarCollapse,
+  allowSidebarCollapse,
+} from './useHoverExpand';
+export { useShellVisualState } from './useShellVisualState';
+export { useSidebarKeyboard } from './useSidebarKeyboard';

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

@@ -0,0 +1,54 @@
+/**
+ * Auth Guard Hook
+ *
+ * Handles authentication check and redirect to login page.
+ */
+
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useRouter } from 'next/navigation';
+
+import { useAuth } from '@djangocfg/api/auth';
+
+interface UseAuthGuardOptions {
+  requireAuth?: boolean;
+  authPath?: string;
+}
+
+interface UseAuthGuardResult {
+  /** Whether auth is still loading or redirecting */
+  isLoading: boolean;
+  /** Whether the user is authenticated (or auth is not required) */
+  isAuthenticated: boolean;
+  /** Loading text for the preloader */
+  loadingText: string;
+}
+
+export function useAuthGuard({
+  requireAuth = true,
+  authPath = '/auth',
+}: UseAuthGuardOptions): UseAuthGuardResult {
+  const { isAuthenticated, isLoading: authLoading, saveRedirectUrl } = useAuth();
+  const router = useRouter();
+  const [isRedirecting, setIsRedirecting] = useState(false);
+
+  useEffect(() => {
+    if (!requireAuth) return;
+    if (!authLoading && !isAuthenticated && !isRedirecting) {
+      const currentUrl = window.location.pathname + window.location.search;
+      saveRedirectUrl(currentUrl);
+      setIsRedirecting(true);
+      router.push(authPath);
+    }
+  }, [requireAuth, isAuthenticated, authLoading, isRedirecting, router, saveRedirectUrl, authPath]);
+
+  const isLoading = requireAuth && (authLoading || isRedirecting || !isAuthenticated);
+  const loadingText = isRedirecting ? 'Redirecting to login...' : 'Authenticating...';
+
+  return {
+    isLoading,
+    isAuthenticated: !requireAuth || isAuthenticated,
+    loadingText,
+  };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Hover Expand Hook
+ *
+ * Manages hover-expand state for collapsed sidebar with debounce.
+ * - enterDelay: ms before expanding on hover (default 250)
+ * - leaveDelay: ms before collapsing on mouse leave (default 150)
+ * - Listens for `sidebar:blockcollapse` / `sidebar:allowcollapse` custom events
+ *   so descendant components (e.g. account dropdown) can block collapse without
+ *   prop drilling or context churn.
+ * - Clears timers on unmount / re-hover to prevent false triggers.
+ */
+
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface UseHoverExpandOptions {
+  /** Delay before expanding on mouse enter (ms). Default 250. */
+  enterDelay?: number;
+  /** Delay before collapsing on mouse leave (ms). Default 150. */
+  leaveDelay?: number;
+  /** Whether hover-expand is enabled (e.g. only on desktop collapsed rail). */
+  enabled?: boolean;
+}
+
+interface UseHoverExpandResult {
+  /** Whether the sidebar is currently hover-expanded */
+  isHoverExpanded: boolean;
+  /** Attach to the sidebar root element */
+  onMouseEnter: () => void;
+  /** Attach to the sidebar root element */
+  onMouseLeave: () => void;
+}
+
+export function useHoverExpand({
+  enterDelay = 250,
+  leaveDelay = 150,
+  enabled = true,
+}: UseHoverExpandOptions = {}): UseHoverExpandResult {
+  const [isHoverExpanded, setIsHoverExpanded] = useState(false);
+  const blockedRef = useRef(false);
+  const enterTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const leaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clearTimers = useCallback(() => {
+    if (enterTimerRef.current) {
+      clearTimeout(enterTimerRef.current);
+      enterTimerRef.current = null;
+    }
+    if (leaveTimerRef.current) {
+      clearTimeout(leaveTimerRef.current);
+      leaveTimerRef.current = null;
+    }
+  }, []);
+
+  useEffect(() => {
+    const onBlock = () => {
+      blockedRef.current = true;
+    };
+    const onAllow = () => {
+      blockedRef.current = false;
+    };
+    window.addEventListener('sidebar:blockcollapse', onBlock);
+    window.addEventListener('sidebar:allowcollapse', onAllow);
+    return () => {
+      window.removeEventListener('sidebar:blockcollapse', onBlock);
+      window.removeEventListener('sidebar:allowcollapse', onAllow);
+    };
+  }, []);
+
+  const onMouseEnter = useCallback(() => {
+    if (!enabled) return;
+    clearTimers();
+    enterTimerRef.current = setTimeout(() => {
+      setIsHoverExpanded(true);
+    }, enterDelay);
+  }, [enabled, enterDelay, clearTimers]);
+
+  const onMouseLeave = useCallback(() => {
+    if (!enabled) return;
+    if (blockedRef.current) return;
+    clearTimers();
+    leaveTimerRef.current = setTimeout(() => {
+      setIsHoverExpanded(false);
+    }, leaveDelay);
+  }, [enabled, leaveDelay, clearTimers]);
+
+  useEffect(() => {
+    return () => clearTimers();
+  }, [clearTimers]);
+
+  return { isHoverExpanded, onMouseEnter, onMouseLeave };
+}
+
+/** Dispatch from any descendant to block sidebar collapse while e.g. a dropdown is open. */
+export function blockSidebarCollapse(): void {
+  window.dispatchEvent(new CustomEvent('sidebar:blockcollapse'));
+}
+
+/** Dispatch when the blocking reason is gone (e.g. dropdown closed). */
+export function allowSidebarCollapse(): void {
+  window.dispatchEvent(new CustomEvent('sidebar:allowcollapse'));
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Layout Visual Hook
+ *
+ * Computes CSS variables and class names for the boxed/full-bleed layout variants.
+ */
+
+import { useMemo } from 'react';
+
+import type { LayoutVisualConfig } from '../../types';
+
+/** CSS variables consumed by the boxed `SidebarInset` (margin + radius). */
+export function resolveProviderStyle(
+  visual: LayoutVisualConfig | undefined,
+): React.CSSProperties | undefined {
+  if ((visual?.variant ?? 'boxed') !== 'boxed') return undefined;
+  const inset = normaliseInset(visual?.inset);
+  return {
+    ['--app-shell-inset-x' as string]: `${inset.x}px`,
+    ['--app-shell-inset-y' as string]: `${inset.y}px`,
+    ['--app-shell-radius' as string]: BOXED_RADIUS_REM[visual?.radius ?? '2xl'],
+  };
+}
+
+/**
+ * Statically-known Tailwind classes for the boxed inset. Margin and radius are
+ * driven by the CSS variables set in `resolveProviderStyle`, so JIT can fully
+ * extract these classes at build time.
+ */
+const BOXED_INSET_CLASS = [
+  'flex flex-col',
+  'md:peer-data-[variant=inset]:my-[var(--app-shell-inset-y)]',
+  'md:peer-data-[variant=inset]:mr-[var(--app-shell-inset-x)]',
+  'md:peer-data-[variant=inset]:rounded-[var(--app-shell-radius)]',
+  'md:peer-data-[variant=inset]:overflow-hidden',
+].join(' ');
+
+const BOXED_INSET_BORDER_CLASS =
+  'md:peer-data-[variant=inset]:border md:peer-data-[variant=inset]:border-border/60';
+
+const BOXED_RADIUS_REM: Record<NonNullable<LayoutVisualConfig['radius']>, string> = {
+  sm: '0.375rem',
+  md: '0.5rem',
+  lg: '0.75rem',
+  xl: '1rem',
+  '2xl': '1.25rem',
+  '3xl': '1.75rem',
+};
+
+export function resolveInsetClassName(visual: LayoutVisualConfig | undefined): string {
+  if ((visual?.variant ?? 'boxed') !== 'boxed') return 'flex flex-col';
+  const border = visual?.border ?? true;
+  return border ? `${BOXED_INSET_CLASS} ${BOXED_INSET_BORDER_CLASS}` : BOXED_INSET_CLASS;
+}
+
+/**
+ * Background painted *behind* the boxed container on md+. On mobile the
+ * canvas tint is dropped because the sidebar is a Drawer — leaking the
+ * canvas colour to the whole viewport just makes the page look dim.
+ *
+ * `bg-sidebar` (the default) overrides shadcn-sidebar's built-in
+ * `has-[&_[data-variant=inset]]:bg-sidebar` only at the breakpoint where
+ * the inset shape actually exists.
+ */
+const BOXED_BG_CLASS: Record<NonNullable<LayoutVisualConfig['background']>, string> = {
+  sidebar: 'md:!bg-sidebar',
+  muted: 'md:!bg-muted',
+  card: 'md:!bg-card',
+  background: 'md:!bg-background',
+};
+
+export function resolveProviderClassName(
+  visual: LayoutVisualConfig | undefined,
+): string | undefined {
+  // h-svh + overflow-hidden: lock the shell to exactly one viewport height so
+  // 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;
+  // `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.
+  return `${base} max-md:!bg-background ${BOXED_BG_CLASS[visual?.background ?? 'sidebar']}`;
+}
+
+function normaliseInset(inset: LayoutVisualConfig['inset']): { x: number; y: number } {
+  if (typeof inset === 'number') return { x: inset, y: inset };
+  return { x: inset?.x ?? 12, y: inset?.y ?? 12 };
+}
+
+export interface LayoutVisualResult {
+  /** CSS variables for the provider */
+  providerStyle: React.CSSProperties | undefined;
+  /** Class name for the provider */
+  providerClassName: string | undefined;
+  /** Class name for the inset */
+  insetClassName: string;
+  /** Sidebar variant for shadcn */
+  sidebarVariant: 'sidebar' | 'inset';
+}
+
+export function useLayoutVisual(visual: LayoutVisualConfig | undefined): LayoutVisualResult {
+  return useMemo(() => {
+    const variant = visual?.variant ?? 'boxed';
+    const sidebarVariant = variant === 'boxed' ? 'inset' : 'sidebar';
+
+    return {
+      providerStyle: resolveProviderStyle(visual),
+      providerClassName: resolveProviderClassName(visual),
+      insetClassName: resolveInsetClassName(visual),
+      sidebarVariant,
+    };
+  }, [visual]);
+}