@campxdev/react-blueprint 3.0.0-alpha.5 → 3.0.0-alpha.6

package/src/components/Layout/AppLayout/AppLayout.tsx

@@ -6,6 +6,38 @@ import { Sidebar } from './components/Sidebar/Sidebar';
 import { SidebarProvider, useSidebar } from './context/SidebarContext';
 import { AppLayoutProps } from './types';
 
+/**
+ * AppLayout Component
+ *
+ * Main layout component that provides a persistent sidebar navigation structure with responsive behavior.
+ * Automatically collapses on small screens and wraps content in a SidebarProvider for state management.
+ * Includes a floating help docs button in the bottom-right corner.
+ *
+ * @param {React.ReactNode} children - Main content to render inside the layout
+ * @param {SideMenuItemProps[]} menu - Navigation menu items for the sidebar
+ * @param {ReactNode | ((params: { collapsed: boolean }) => ReactNode)} [actions] - Optional action elements or function that receives collapsed state
+ * @param {string} [mainContainerClassName=''] - Additional CSS classes for the main content container
+ * @param {HelpDocsConfig} [helpDocsConfig] - Configuration for context-based help documentation
+ * @param {boolean} [initialCollapsed] - Initial state of sidebar collapse (auto-determined on small screens)
+ * @param {UserProfilePopupProps} [userProfileParams] - Configuration for user profile popup/menu
+ *
+ * @returns {React.ReactElement} The complete app layout with sidebar and main content area
+ *
+ * @example
+ * ```tsx
+ * <AppLayout
+ *   menu={menuItems}
+ *   userProfileParams={{
+ *     userFullName: "John Doe",
+ *     email: "john@example.com",
+ *     onLogout: handleLogout
+ *   }}
+ *   actions={<ActionButtons />}
+ * >
+ *   <YourContent />
+ * </AppLayout>
+ * ```
+ */
 export const AppLayout: React.FC<AppLayoutProps> = ({
   children,
   menu,
@@ -73,7 +105,7 @@ const AppLayoutContent: React.FC<AppLayoutProps> = ({
           display: 'flex',
           flexDirection: 'column',
         }}
-        className={`w-full p-0 ${mainContainerClassName}`}
+        className={`w-full p-0 bg-background ${mainContainerClassName}`}
       >
         {children}
       </div>

package/src/components/Layout/AppLayout/components/MenuToggleButton.tsx

@@ -9,6 +9,22 @@ interface MenuToggleButtonProps {
   className?: string;
 }
 
+/**
+ * MenuToggleButton Component
+ *
+ * Mobile-only button that toggles the sidebar visibility. This button is hidden on desktop screens
+ * (above 768px width) using the Tailwind media query. Useful for including in page headers
+ * on mobile devices to control sidebar drawer visibility.
+ *
+ * @param {string} [className=''] - Additional CSS classes to apply to the button
+ *
+ * @returns {React.ReactElement} A menu toggle button (empty fragment on desktop)
+ *
+ * @example
+ * ```tsx
+ * <MenuToggleButton className="ml-4" />
+ * ```
+ */
 export const MenuToggleButton: React.FC<MenuToggleButtonProps> = ({
   className = '',
 }) => {

package/src/components/Layout/AppLayout/components/Sidebar/MenuBar.tsx

@@ -17,6 +17,32 @@ const containerVariants = {
   },
 };
 
+/**
+ * MenuBar Component
+ *
+ * Container component that renders the current menu level with optional back navigation.
+ * Displays a header with "Back" button when viewing nested menus and animates menu item
+ * appearance using staggered animations. Supports both collapsed and expanded sidebar states.
+ *
+ * @param {MenuState} currentMenuState - Current menu level state with menu items, title, and path
+ * @param {(params: InternalMenuClickHandlerProps) => void} internalMenuClickHandler - Callback to navigate into nested menus
+ * @param {() => void} previousMenuClickHandler - Callback to navigate back to previous menu level
+ * @param {() => void} [onClose] - Optional callback to close the mobile drawer
+ * @param {boolean} [collapsed] - Whether the sidebar is collapsed
+ * @param {(collapsed: boolean) => void} [setCollapsed] - Function to update sidebar collapse state
+ *
+ * @returns {React.ReactElement} Animated menu container with menu items and optional back button
+ *
+ * @example
+ * ```tsx
+ * <MenuBar
+ *   currentMenuState={menuState}
+ *   internalMenuClickHandler={handleInternalClick}
+ *   previousMenuClickHandler={handleBack}
+ *   collapsed={false}
+ * />
+ * ```
+ */
 export const MenuBar: React.FC<MenuBarProps> = ({
   currentMenuState,
   internalMenuClickHandler,

package/src/components/Layout/AppLayout/components/Sidebar/MenuItem.tsx

@@ -17,6 +17,43 @@ import {
   SubMenuItemContainer,
 } from './StyledComponents';
 
+/**
+ * MenuItem Component
+ *
+ * Renders a single menu item that can be one of three types:
+ * 1. **Internal Menu Item** (has nested menu): Shows a back arrow on hover, opens nested menu on click
+ * 2. **Sub Menu Item** (has expandable sub-items): Shows chevron icon, expands/collapses sub-items below
+ * 3. **Regular Link Item** (direct navigation): Direct link to a route
+ *
+ * Automatically shows tooltips when collapsed and handles drawer closing logic for mobile.
+ * Supports route matching to highlight the active menu item based on current URL.
+ *
+ * @param {number} index - Unique index of the menu item in the list
+ * @param {SideMenuItemProps} menuItem - Menu item configuration with name, path, icon, and optional menu/subMenu
+ * @param {string | null} currentMenuPath - Current path prefix for building full paths (for nested menus)
+ * @param {(params: InternalMenuClickHandlerProps) => void} internalMenuClickHandler - Callback when opening a nested/internal menu
+ * @param {() => void} [onClose] - Optional callback to close the mobile drawer after navigation
+ * @param {boolean} [collapsed] - Whether the sidebar is in collapsed state
+ * @param {(collapsed: boolean) => void} [setCollapsed] - Function to update sidebar collapse state
+ *
+ * @returns {React.ReactElement} Animated menu item with appropriate interactive elements
+ *
+ * @example
+ * ```tsx
+ * <MenuItem
+ *   index={0}
+ *   menuItem={{
+ *     name: "Dashboard",
+ *     path: "/dashboard",
+ *     icon: <DashboardIcon />,
+ *     menu: subMenuItems // For nested menus
+ *   }}
+ *   currentMenuPath="/admin"
+ *   internalMenuClickHandler={handleMenuClick}
+ *   collapsed={false}
+ * />
+ * ```
+ */
 export const MenuItem: React.FC<MenuItemProps> = ({
   index,
   menuItem,
@@ -230,7 +267,20 @@ export const MenuItem: React.FC<MenuItemProps> = ({
   );
 };
 
-// Sub menu item component
+/**
+ * SubMenuItem Component
+ *
+ * Internal component that renders an individual sub-menu item (child item within an expandable menu).
+ * These are leaf nodes that directly navigate to routes. Automatically closes the mobile drawer
+ * on navigation since they are terminal menu items.
+ *
+ * @param {number} index - Unique index of the sub-menu item
+ * @param {{ name: string; path: string }} subMenuItem - Sub-menu item data with name and path
+ * @param {string} subMenuButtonPath - Parent menu's path prefix for building full navigation path
+ * @param {() => void} [onClose] - Optional callback to close the mobile drawer after navigation
+ *
+ * @returns {React.ReactElement} A navigation link for the sub-menu item
+ */
 const SubMenuItem: React.FC<{
   index: number;
   subMenuItem: { name: string; path: string };

package/src/components/Layout/AppLayout/components/Sidebar/Sidebar.tsx

@@ -1,4 +1,5 @@
-import { AnimatePresence, motion } from 'framer-motion';
+import { Sheet, SheetContent } from '@/shadcn-components/Layout/Sheet/Sheet';
+import { motion } from 'framer-motion';
 import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
 import React, { ReactNode, useState } from 'react';
 import { useMediaQuery } from '../../../../../hooks/useMediaQuery';
@@ -6,7 +7,7 @@ import { CampxFullLogoIcon } from '../../../../Assets/Icons/IconComponents/Campx
 import { CampxIcon } from '../../../../Assets/Icons/IconComponents/CampxIcon';
 import { Button } from '../../../../Input/Button/Button';
 import { UserProfilePopup, UserProfilePopupProps } from '../UserProfilePopup';
-import { SideMenuItemProps } from './interfaces';
+import { SideMenuItemProps, SidebarNavigationHook } from './interfaces';
 import { MenuBar } from './MenuBar';
 import { useSidebarNavigation } from './useSidebarNavigation';
 
@@ -14,7 +15,7 @@ interface SidebarProps {
   /** Menu items for navigation */
   menu: SideMenuItemProps[];
   /**User profile Params */
-  userProfileParams: UserProfilePopupProps;
+  userProfileParams?: UserProfilePopupProps;
   /** Whether the sidebar is collapsed */
   collapsed: boolean;
   /** Function to toggle sidebar collapse state */
@@ -23,6 +24,140 @@ interface SidebarProps {
   actions: ReactNode;
 }
 
+interface SidebarContentProps {
+  collapsed: boolean;
+  setCollapsed: (collapsed: boolean) => void;
+  onToggle: () => void;
+  isSmallScreen: boolean;
+  navigation: SidebarNavigationHook;
+  userProfileParams?: UserProfilePopupProps;
+  actions: ReactNode;
+  hovered: boolean;
+  setHovered: (hovered: boolean) => void;
+}
+
+/**
+ * SidebarContent Component
+ * Renders the actual sidebar UI content (header, menu, footer)
+ * This component is reused for both mobile and desktop layouts
+ */
+const SidebarContent: React.FC<SidebarContentProps> = ({
+  collapsed,
+  setCollapsed,
+  onToggle,
+  isSmallScreen,
+  navigation,
+  userProfileParams,
+  actions,
+  hovered,
+  setHovered,
+}) => (
+  <SidebarContainer>
+    {/* Sidebar Header */}
+    <div
+      className={`flex flex-row justify-between items-center h-16 ${
+        collapsed && !isSmallScreen ? '' : 'px-4'
+      } md:h-[54px]`}
+    >
+      {/* Logo - Show icon when collapsed (desktop only), full logo otherwise */}
+      {collapsed && !isSmallScreen ? (
+        <div
+          onClick={() => {
+            setHovered(false);
+            onToggle();
+          }}
+          onMouseEnter={() => setHovered(true)}
+          onMouseLeave={() => setHovered(false)}
+          className="w-full hover:cursor-ew-resize flex justify-center"
+        >
+          {hovered ? <PanelLeftOpen size={20} /> : <CampxIcon size={32} />}
+        </div>
+      ) : (
+        <>
+          <CampxFullLogoIcon />
+          <Button
+            onClick={onToggle}
+            variant="ghost"
+            size="icon-sm"
+            className="hover:cursor-ew-resize"
+          >
+            <PanelLeftClose size={20} />
+          </Button>
+        </>
+      )}
+    </div>
+
+    {/* Menu Content */}
+    <motion.div
+      key={`sidebar-${navigation.currentMenuState.title || 'main'}`}
+      initial={{ x: navigation.menuPosition }}
+      animate={{ x: 0 }}
+      transition={{
+        duration: 0.3,
+        ease: navigation.menuPosition ? 'circOut' : 'circIn',
+      }}
+      className="h-[calc(100%-165px)] w-full"
+      onClick={() => setCollapsed(false)}
+    >
+      <MenuBar
+        currentMenuState={navigation.currentMenuState}
+        menuPosition={navigation.menuPosition}
+        internalMenuClickHandler={navigation.internalMenuClickHandler}
+        previousMenuClickHandler={navigation.previousMenuClickHandler}
+        onClose={isSmallScreen ? onToggle : undefined}
+        collapsed={isSmallScreen ? false : collapsed}
+        setCollapsed={setCollapsed}
+      />
+    </motion.div>
+
+    {/* Footer */}
+    {(actions || userProfileParams) && (
+      <div className="fixed bottom-0 left-0 border-t border-border flex flex-col gap-1">
+        {actions}
+        {userProfileParams && (
+          <UserProfilePopup
+            userFullName={userProfileParams?.userFullName}
+            email={userProfileParams?.email}
+            onLogout={userProfileParams?.onLogout}
+            onAccountClick={userProfileParams?.onAccountClick}
+            profileActions={userProfileParams?.profileActions}
+            collapsed={isSmallScreen ? false : collapsed}
+          />
+        )}
+      </div>
+    )}
+  </SidebarContainer>
+);
+
+/**
+ * Sidebar Component
+ *
+ * Responsive sidebar navigation component that displays differently on mobile and desktop:
+ * - **Mobile**: Renders as a collapsible Sheet drawer
+ * - **Desktop**: Renders as an animated fixed-width sidebar with collapse/expand animation
+ *
+ * Manages menu navigation state, hover effects, and user profile popup. Automatically
+ * handles internal menu navigation and animated transitions between menu levels.
+ *
+ * @param {SideMenuItemProps[]} menu - Navigation menu items with support for nested/internal menus and sub-menus
+ * @param {UserProfilePopupProps} userProfileParams - User profile configuration including name, email, and action handlers
+ * @param {boolean} collapsed - Current collapse state of the sidebar
+ * @param {(collapsed: boolean) => void} setCollapsed - Function to update the collapse state
+ * @param {ReactNode} actions - Action elements to display in the sidebar footer (above user profile)
+ *
+ * @returns {React.ReactElement} Responsive sidebar component (Sheet on mobile, animated div on desktop)
+ *
+ * @example
+ * ```tsx
+ * <Sidebar
+ *   menu={navigationMenu}
+ *   collapsed={sidebarCollapsed}
+ *   setCollapsed={setSidebarCollapsed}
+ *   userProfileParams={userProfile}
+ *   actions={<CustomActions />}
+ * />
+ * ```
+ */
 export const Sidebar: React.FC<SidebarProps> = ({
   menu,
   userProfileParams,
@@ -32,115 +167,49 @@ export const Sidebar: React.FC<SidebarProps> = ({
 }) => {
   const [hovered, setHovered] = useState(false);
   const isSmallScreen = useMediaQuery('(max-width: 768px)');
-  // Use the navigation hook
   const navigation = useSidebarNavigation(menu);
 
   const onToggle = () => {
     setCollapsed(!collapsed);
   };
 
-  return (
-    <>
-      {/* Mobile overlay backdrop */}
-      <AnimatePresence>
-        {!collapsed && isSmallScreen && (
-          <motion.div
-            initial={{ opacity: 0 }}
-            animate={{ opacity: 1 }}
-            exit={{ opacity: 0 }}
-            transition={{ duration: 0.2 }}
-            className="fixed inset-0 bg-black/50 z-[1299]"
-            onClick={onToggle}
-          />
-        )}
-      </AnimatePresence>
+  // Sidebar content component with all shared props
+  const sidebarContent = (
+    <SidebarContent
+      collapsed={collapsed}
+      setCollapsed={setCollapsed}
+      onToggle={onToggle}
+      isSmallScreen={isSmallScreen}
+      navigation={navigation}
+      userProfileParams={userProfileParams}
+      actions={actions}
+      hovered={hovered}
+      setHovered={setHovered}
+    />
+  );
 
-      {/* Persistent Sidebar */}
-      <motion.div
-        animate={{
-          width: collapsed ? '64px' : '250px',
-          x: isSmallScreen && collapsed ? '-100%' : '0%',
-        }}
-        transition={{ duration: 0.3, ease: [0.32, 0.72, 0, 1] }}
-        className={`${
-          isSmallScreen ? 'fixed' : 'relative'
-        } h-screen flex-shrink-0 ${isSmallScreen ? 'z-[1300]' : 'z-1'}`}
-      >
-        <SidebarContainer>
-          {/* Sidebar Header */}
-          <div
-            className={`flex flex-row justify-between items-center h-16  ${
-              collapsed ? '' : 'px-4'
-            } md:h-[54px]`}
-          >
-            {/* Logo - Show icon when collapsed, full logo when expanded */}
-            {collapsed ? (
-              <div
-                onClick={() => {
-                  setHovered(false);
-                  onToggle();
-                }}
-                onMouseEnter={() => setHovered(true)}
-                onMouseLeave={() => setHovered(false)}
-                className="w-full hover:cursor-ew-resize flex justify-center"
-              >
-                {hovered ? (
-                  <PanelLeftOpen size={20} />
-                ) : (
-                  <CampxIcon size={32} />
-                )}
-              </div>
-            ) : (
-              <>
-                <CampxFullLogoIcon />
-                <Button
-                  onClick={onToggle}
-                  variant="ghost"
-                  size="icon-sm"
-                  className="hover:cursor-ew-resize"
-                >
-                  <PanelLeftClose size={20} />
-                </Button>
-              </>
-            )}
-          </div>
+  // Mobile: Wrap with Sheet
+  if (isSmallScreen) {
+    return (
+      <Sheet open={!collapsed} onOpenChange={(open) => setCollapsed(!open)}>
+        <SheetContent side="left" className="w-[250px] p-0 [&>button]:hidden">
+          {sidebarContent}
+        </SheetContent>
+      </Sheet>
+    );
+  }
 
-          {/* Menu Content */}
-          <motion.div
-            key={`sidebar-${navigation.currentMenuState.title || 'main'}`}
-            initial={{ x: navigation.menuPosition }}
-            animate={{ x: 0 }}
-            transition={{
-              duration: 0.3,
-              ease: navigation.menuPosition ? 'circOut' : 'circIn',
-            }}
-            className="h-[calc(100%-165px)] w-full"
-            onClick={() => setCollapsed(false)}
-          >
-            <MenuBar
-              currentMenuState={navigation.currentMenuState}
-              menuPosition={navigation.menuPosition}
-              internalMenuClickHandler={navigation.internalMenuClickHandler}
-              previousMenuClickHandler={navigation.previousMenuClickHandler}
-              onClose={isSmallScreen ? onToggle : undefined}
-              collapsed={collapsed}
-              setCollapsed={setCollapsed}
-            />
-          </motion.div>
-          <div className="fixed bottom-0 left-0 border-t border-border">
-            {actions}
-            <UserProfilePopup
-              userFullName={userProfileParams?.userFullName}
-              email={userProfileParams?.email}
-              onLogout={userProfileParams?.onLogout}
-              onAccountClick={userProfileParams?.onAccountClick}
-              profileActions={userProfileParams?.profileActions}
-              collapsed={collapsed}
-            />
-          </div>
-        </SidebarContainer>
-      </motion.div>
-    </>
+  // Desktop: Wrap with Framer Motion for width animation
+  return (
+    <motion.div
+      animate={{
+        width: collapsed ? '64px' : '250px',
+      }}
+      transition={{ duration: 0.3, ease: [0.32, 0.72, 0, 1] }}
+      className="relative h-screen flex-shrink-0"
+    >
+      {sidebarContent}
+    </motion.div>
   );
 };