@djangocfg/layouts 2.1.356 → 2.1.358

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]);
+}

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

@@ -0,0 +1,207 @@
+/**
+ * Shell Visual State Hook
+ *
+ * Centralizes ALL visual decisions for the sidebar + content pair:
+ * - sidebar state: expanded | hover-overlay | collapsed-rail
+ * - layout variant: boxed (inset) | full-bleed
+ * - what to show/hide in each state
+ * - CSS modifiers for sidebar root, inner shell, and content inset
+ *
+ * Every component reads from this hook — no scattered ternaries.
+ */
+
+'use client';
+
+import { useMemo } from 'react';
+
+import { usePrivateLayoutContext } from '../context';
+import type { LayoutVisualConfig } from '../../types';
+
+// ============================================================================
+// State flags
+// ============================================================================
+
+export interface ShellVisualFlags {
+  /** Mobile drawer mode */
+  isMobile: boolean;
+  /** Persistent expanded (user toggled or default open) */
+  isExpanded: boolean;
+  /** Collapsed to icon rail */
+  isCollapsed: boolean;
+  /** Temporary hover-expand overlay on desktop rail */
+  isHoverOverlay: boolean;
+  /** True only in desktop collapsed rail without hover */
+  isRail: boolean;
+}
+
+// ============================================================================
+// Content visibility flags
+// ============================================================================
+
+export interface ShellContentFlags {
+  /** Nav item text labels visible */
+  showLabels: boolean;
+  /** Group section headers visible */
+  showGroupLabels: boolean;
+  /** Badges render as full text (false = dot only) */
+  showBadgeText: boolean;
+  /** Tooltips on nav items (only when labels hidden) */
+  showTooltips: boolean;
+  /** Account footer in compact avatar-only mode */
+  isAccountCompact: boolean;
+  /** menuStart / menuEnd / featured slots hidden */
+  hideSlots: boolean;
+}
+
+// ============================================================================
+// Chrome flags
+// ============================================================================
+
+export interface ShellChromeFlags {
+  /** Sidebar casts a shadow (overlay mode) */
+  showShadow: boolean;
+  /** Right border/separator on sidebar */
+  showBorder: boolean;
+  /** Internal right padding inside sidebar (overlay breathing room) */
+  needsInternalPadding: boolean;
+  /** Content inset should have margin to make room for sidebar */
+  contentHasSidebarGap: boolean;
+  /** Sidebar width is fixed to icon-rail */
+  isRailWidth: boolean;
+}
+
+// ============================================================================
+// CSS modifiers
+// ============================================================================
+
+export interface ShellModifiers {
+  /** Classes for the shadcn <Sidebar> root (fixed container) */
+  sidebarRoot: string[];
+  /** Classes for the inner div[data-sidebar=sidebar] */
+  sidebarInner: string[];
+  /** Classes for the shadcn <SidebarContent> */
+  sidebarContent: string[];
+}
+
+// ============================================================================
+// Combined result
+// ============================================================================
+
+export interface ShellVisualState {
+  flags: ShellVisualFlags;
+  content: ShellContentFlags;
+  chrome: ShellChromeFlags;
+  modifiers: ShellModifiers;
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+export function useShellVisualState(
+  layoutVariant?: LayoutVisualConfig['variant'],
+): ShellVisualState {
+  const { isMobile, isExpanded, isCollapsed, isHoverExpanded } =
+    usePrivateLayoutContext();
+
+  const isRail = !isMobile && isCollapsed && !isHoverExpanded;
+  const isHoverOverlay = !isMobile && isCollapsed && isHoverExpanded;
+  const variant = layoutVariant ?? 'boxed';
+
+  return useMemo(() => {
+    // ------------------------------------------------------------------------
+    // Content visibility
+    // ------------------------------------------------------------------------
+    const showLabels = isExpanded || isHoverOverlay;
+    const showGroupLabels = showLabels;
+    const showBadgeText = showLabels;
+    const showTooltips = isRail;
+    const isAccountCompact = isRail;
+    const hideSlots = isRail;
+
+    // ------------------------------------------------------------------------
+    // Chrome
+    // ------------------------------------------------------------------------
+    // Only hover-overlay is an overlay — it needs shadow + border + padding.
+    // Persistent expanded is part of the layout flow — no shadow.
+    const showShadow = isHoverOverlay;
+    const showBorder = isHoverOverlay;
+    const needsInternalPadding = isHoverOverlay;
+
+    // Content gap: only persistent expanded pushes the inset.
+    // Hover-overlay is temporary — content must NOT shift.
+    // Collapsed rail also leaves a gap (the rail itself is narrow but present).
+    const contentHasSidebarGap = isExpanded || isRail;
+    const isRailWidth = isRail;
+
+    // ------------------------------------------------------------------------
+    // Modifiers
+    // ------------------------------------------------------------------------
+    const sidebarRoot: string[] = [];
+    const sidebarInner: string[] = [];
+    const sidebarContent: string[] = [];
+
+    if (isHoverOverlay) {
+      sidebarRoot.push('z-50', '!w-[var(--sidebar-width)]', 'min-w-[var(--sidebar-width)]');
+      // Allow scroll inside hover-expanded overlay — shadcn hardcodes
+      // overflow-hidden on div[data-sidebar=sidebar]; override it here.
+      sidebarInner.push('!overflow-auto');
+      // Extra right padding on content so text doesn't hug the right edge
+      sidebarContent.push('!overflow-auto', 'pr-4');
+
+      if (showShadow) {
+        sidebarInner.push(
+          'shadow-[4px_0_24px_-4px_rgba(0,0,0,0.08)]',
+          'dark:shadow-[4px_0_24px_-4px_rgba(0,0,0,0.25)]',
+        );
+      }
+      if (showBorder) {
+        sidebarInner.push('border-r', 'border-sidebar-border/30');
+      }
+      // Hide the shadcn gradient border line on hover overlay
+      sidebarInner.push('[&>div[aria-hidden]]:hidden');
+    }
+
+    // Boxed variant: inner sidebar gets rounded corners when persistent expanded
+    if (variant === 'boxed' && isExpanded) {
+      sidebarInner.push('rounded-sm');
+    }
+
+    return {
+      flags: {
+        isMobile,
+        isExpanded,
+        isCollapsed,
+        isHoverOverlay,
+        isRail,
+      },
+      content: {
+        showLabels,
+        showGroupLabels,
+        showBadgeText,
+        showTooltips,
+        isAccountCompact,
+        hideSlots,
+      },
+      chrome: {
+        showShadow,
+        showBorder,
+        needsInternalPadding,
+        contentHasSidebarGap,
+        isRailWidth,
+      },
+      modifiers: {
+        sidebarRoot,
+        sidebarInner,
+        sidebarContent,
+      },
+    };
+  }, [
+    isMobile,
+    isExpanded,
+    isCollapsed,
+    isHoverOverlay,
+    isRail,
+    variant,
+  ]);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Reads the sidebar open/closed state from the cookie written by shadcn-sidebar.
+ * Falls back to `true` (expanded) when no cookie exists.
+ *
+ * Must run on the client — returns `true` during SSR.
+ */
+
+const SIDEBAR_COOKIE_NAME = 'sidebar_state';
+
+export function useSidebarDefaultOpen(): boolean {
+  if (typeof document === 'undefined') return true;
+
+  const match = document.cookie
+    .split('; ')
+    .find((row) => row.startsWith(`${SIDEBAR_COOKIE_NAME}=`));
+
+  if (!match) return true;
+
+  const value = match.split('=')[1];
+  return value === 'true';
+}

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

@@ -0,0 +1,115 @@
+/**
+ * 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)
+ */
+
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+
+import { useSidebar } from '@djangocfg/ui-core/components';
+
+interface UseSidebarKeyboardOptions {
+  /** Whether keyboard shortcuts are active */
+  enabled?: boolean;
+}
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+
+export function useSidebarKeyboard({ enabled = true }: UseSidebarKeyboardOptions = {}) {
+  const { toggleSidebar, setOpenMobile, isMobile, openMobile } = useSidebar();
+  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();
+        }
+        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();
+    },
+    [],
+  );
+
+  const setSidebarRef = useCallback((node: HTMLElement | null) => {
+    sidebarRef.current = node;
+  }, []);
+
+  return { setSidebarRef, handleSidebarKeyDown };
+}

package/src/layouts/PrivateLayout/index.ts

@@ -3,6 +3,7 @@
  */
 
 export { PrivateLayout } from './PrivateLayout';
+export { PrivateLayoutProvider, usePrivateLayoutContext } from './context';
 export type {
   PrivateLayoutProps,
   SidebarItem,
@@ -12,5 +13,4 @@ export type {
   SidebarActiveIndicator,
   SidebarGroupLabelStyle,
   SidebarFeaturedConfig,
-} from './PrivateLayout';
-
+} from './types';

package/src/layouts/PrivateLayout/types.ts

@@ -0,0 +1,193 @@
+/**
+ * PrivateLayout Types
+ *
+ * All type definitions for the PrivateLayout component family.
+ */
+
+import type { ReactNode } from 'react';
+import type { LucideIcon } from 'lucide-react';
+
+import type { AppLayoutPublicChrome } from '../AppLayout/AppLayout';
+import type { LayoutVisualConfig } from '../types';
+import type { UserMenuConfig } from '../types';
+
+// ============================================================================
+// Sidebar Item Types
+// ============================================================================
+
+export interface SidebarItem {
+  label: string;
+  href: string;
+  icon?: string | LucideIcon;
+  badge?: string | number;
+  /** Visual style of `badge`: `'count'` (default, neutral pill) or `'pill'` (accent-tinted, e.g. "lite"/"new"). */
+  badgeVariant?: 'count' | 'pill';
+  /** Collapsed rail: shown in tooltip; defaults to `label`. */
+  tooltip?: string;
+}
+
+// ============================================================================
+// Sidebar Group Types
+// ============================================================================
+
+export interface SidebarGroupConfig {
+  /** Group label displayed above items */
+  label: string;
+  /** Items in this group */
+  items: SidebarItem[];
+  /** If true, group is only shown when it has items (for dynamic groups like extensions) */
+  dynamic?: boolean;
+  /** Render group as an accordion (Mailersend/Vercel-style). Label becomes a clickable trigger. */
+  collapsible?: boolean;
+  /** Initial open state for collapsible groups. Auto-expanded if any child is active. Default `false`. */
+  defaultOpen?: boolean;
+  /** Icon for the group trigger (only when `collapsible`). */
+  icon?: string | LucideIcon;
+  /**
+   * Hide per-item icons inside the group. Defaults to `true` when `collapsible`,
+   * `false` otherwise (Mailersend convention: icons live on the trigger, not on children).
+   */
+  hideItemIcons?: boolean;
+}
+
+/** Active-state visual treatment for sidebar nav items. */
+export type SidebarActiveIndicator = 'background' | 'rail' | 'both';
+
+/** Rendering of group labels. `'uppercase'` is the legacy ultra-light caps; `'plain'` is sm bold. */
+export type SidebarGroupLabelStyle = 'uppercase' | 'plain';
+
+// ============================================================================
+// Featured CTA Types
+// ============================================================================
+
+/** Featured CTA tile rendered below groups. */
+export interface SidebarFeaturedConfig {
+  icon?: string | LucideIcon;
+  label: string;
+  href: string;
+  badge?: string;
+  accent?: 'green' | 'blue' | 'amber' | 'primary';
+}
+
+// ============================================================================
+// Sidebar Config
+// ============================================================================
+
+export interface SidebarConfig {
+  /** Grouped items with labels */
+  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;
+  /**
+   * Keep `menuStart` visible when the desktop sidebar is collapsed to the
+   * icon rail. Default `false` — most slot content is full-width and looks
+   * broken at ~56px. Set `true` only when the slot renders well in compact mode.
+   */
+  menuStartShowOnCollapsed?: boolean;
+  /** Same as `menuStartShowOnCollapsed`, but for `menuEnd`. Default `false`. */
+  menuEndShowOnCollapsed?: boolean;
+  /** Custom footer component rendered at the bottom of the sidebar */
+  footer?: ReactNode;
+  /** Active-state visual on nav items. Default `'background'` (legacy). */
+  activeIndicator?: SidebarActiveIndicator;
+  /** Style of group labels. Default `'uppercase'` (legacy). Collapsible groups always use `plain`. */
+  groupLabelStyle?: SidebarGroupLabelStyle;
+  /** Featured CTA tile rendered below all groups, above `menuEnd`. */
+  featured?: SidebarFeaturedConfig;
+  /**
+   * Override the auto-calculated nav density. When omitted density is derived
+   * from total item count (comfortable ≤5, default ≤9, compact >9).
+   */
+  density?: 'comfortable' | 'default' | 'compact';
+}
+
+// ============================================================================
+// Header Config
+// ============================================================================
+
+export interface HeaderConfig {
+  /** Custom header brand node (same idea as PublicNavbar `brand`). */
+  brand?: ReactNode;
+  /** 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 | LucideIcon;
+  /**
+   * 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'];
+  /**
+   * Behaviour of the footer account button.
+   * - `'menu'` (default) — opens a DropdownMenu with account links, locale/theme controls, and sign-out.
+   * - `'dialog'` — opens the global ProfileDialog (managed via Zustand store).
+   */
+  accountAction?: 'menu' | 'dialog';
+  /** Auth page path (for sign in button) */
+  authPath?: string;
+  /** Subtitle under the display name in the sidebar footer (e.g. "Max plan"). */
+  userPlan?: string;
+  /** Optional secondary action button rendered inside the footer trigger (e.g. Get apps download button). */
+  footerSecondaryAction?: {
+    icon: string | LucideIcon;
+    href?: string;
+    onClick?: () => void;
+    ariaLabel: string;
+    /** Show pulsing accent dot on the action (Claude-style "new"). */
+    pulse?: boolean;
+  };
+}
+
+// ============================================================================
+// PrivateLayout Props
+// ============================================================================
+
+export interface PrivateLayoutProps {
+  children: ReactNode;
+  /** Sidebar configuration */
+  sidebar?: SidebarConfig;
+  /** Title + account links (no top navbar — title is used in the sidebar chrome) */
+  header?: HeaderConfig;
+  /**
+   * Path for active nav highlighting. With `@djangocfg/nextjs` i18n routing, pass `usePathname()` from
+   * `@djangocfg/nextjs/i18n/navigation` (no `/[locale]` segment). If omitted, uses `next/navigation` (includes locale).
+   */
+  pathname?: string;
+  /** Content padding */
+  contentPadding?: 'none' | 'default';
+  /**
+   * Content scroll behaviour.
+   * - `'auto'` (default) — the shell scroll-area scrolls vertically.
+   * - `'hidden'` — shell does NOT scroll; use for full-height pages (e.g. Kanban)
+   *   where children manage their own scroll surfaces.
+   */
+  contentScroll?: 'auto' | 'hidden';
+  /**
+   * Visual style of the shell. Defaults to `'boxed'` (inset rounded card on a
+   * sidebar-coloured canvas). Pass `{ variant: 'full-bleed' }` for the legacy
+   * edge-to-edge layout.
+   */
+  visual?: LayoutVisualConfig;
+  /**
+   * Skip the built-in auth guard. Useful for static showcases / playground
+   * embeds where there's no real session. Default `true` (guard on).
+   */
+  requireAuth?: boolean;
+  /** Reserved for `AppLayout` passthrough (`publicChrome`); unused in this layout. */
+  publicChrome?: AppLayoutPublicChrome;
+}