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

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

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

@@ -31,7 +31,18 @@ type ButtonProps = {
   onClick?: () => void;
 } & React.HTMLAttributes<HTMLButtonElement>;
 
-// Main sidebar container
+/**
+ * SidebarContainer Component
+ *
+ * Main container for the sidebar with flex layout, rounded corners, and overflow hidden.
+ * Serves as the root wrapper for all sidebar content including header, menu, and footer.
+ *
+ * @param {React.ReactNode} children - Content to render inside the sidebar
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Additional HTML div attributes
+ *
+ * @returns {React.ReactElement} A flex container for sidebar content
+ */
 export const SidebarContainer: React.FC<BaseProps> = ({
   children,
   className,
@@ -50,7 +61,19 @@ export const SidebarContainer: React.FC<BaseProps> = ({
   );
 };
 
-// Menu bar container with scrolling
+/**
+ * MenuBarContainer Component
+ *
+ * Scrollable container for menu items with custom scrollbar styling. Includes responsive
+ * design with different width and margin behavior on mobile vs desktop. Custom scrollbar
+ * uses theme colors with thin width.
+ *
+ * @param {React.ReactNode} children - Menu items to render inside the container
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Additional HTML div attributes
+ *
+ * @returns {React.ReactElement} A vertically scrollable menu container
+ */
 export const MenuBarContainer: React.FC<BaseProps> = ({
   children,
   className,
@@ -77,7 +100,19 @@ export const MenuBarContainer: React.FC<BaseProps> = ({
   );
 };
 
-// Menu header with back button
+/**
+ * MenuHeaderContainer Component
+ *
+ * Header container for displaying nested menu titles with back navigation.
+ * Provides fixed height with flex layout for centered or start-aligned content.
+ * Includes hover background effect.
+ *
+ * @param {React.ReactNode} children - Header content (typically back button and title)
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Additional HTML div attributes
+ *
+ * @returns {React.ReactElement} A header container for menu navigation
+ */
 export const MenuHeaderContainer: React.FC<BaseProps> = ({
   children,
   className,
@@ -96,7 +131,18 @@ export const MenuHeaderContainer: React.FC<BaseProps> = ({
   );
 };
 
-// Menu item containers
+/**
+ * MenuItemContainer Component
+ *
+ * Wrapper container for individual menu items with flex centering and rounded corners.
+ * Provides consistent spacing and layout for menu items.
+ *
+ * @param {React.ReactNode} children - Menu item content
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Additional HTML div attributes
+ *
+ * @returns {React.ReactElement} A centered flex container for a menu item
+ */
 export const MenuItemContainer: React.FC<BaseProps> = ({
   children,
   className,
@@ -109,6 +155,18 @@ export const MenuItemContainer: React.FC<BaseProps> = ({
   );
 };
 
+/**
+ * MenuItemButton Component
+ *
+ * Styled button for menu items with flex layout, whitespace handling, and rounded appearance.
+ * Based on Button component with ghost variant and custom padding.
+ *
+ * @param {React.ReactNode} children - Button content (icon and/or text)
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLButtonElement>} props - Additional button attributes
+ *
+ * @returns {React.ReactElement} A styled button for menu navigation
+ */
 export const MenuItemButton: React.FC<ButtonProps> = ({
   children,
   className,
@@ -128,6 +186,18 @@ export const MenuItemButton: React.FC<ButtonProps> = ({
   );
 };
 
+/**
+ * MenuItemIcon Component
+ *
+ * Container for menu item icons with flex centering and right margin.
+ * Ensures icons are properly sized and aligned within menu items.
+ *
+ * @param {React.ReactNode} children - Icon element
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Additional HTML div attributes
+ *
+ * @returns {React.ReactElement} A centered flex container for an icon
+ */
 export const MenuItemIcon: React.FC<BaseProps> = ({
   children,
   className,
@@ -143,7 +213,20 @@ export const MenuItemIcon: React.FC<BaseProps> = ({
   );
 };
 
-// Link components for navigation
+/**
+ * MenuLink Component
+ *
+ * React Router Link component styled as a menu item. Shows different background color
+ * when the route matches the current location. Includes hover effects and transitions.
+ *
+ * @param {boolean} [match] - Whether the link destination matches current route
+ * @param {string} [to=''] - Route path to navigate to
+ * @param {React.ReactNode} children - Link content
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {any} props - Additional Link properties
+ *
+ * @returns {React.ReactElement} A styled navigation link
+ */
 export const MenuLink: React.FC<StyledLinkButtonProps> = ({
   match,
   to = '',
@@ -167,7 +250,20 @@ export const MenuLink: React.FC<StyledLinkButtonProps> = ({
   );
 };
 
-// Sub menu containers
+/**
+ * SubMenuContainer Component
+ *
+ * Container for sub-menu items that can expand/collapse or navigate.
+ * Shows different background color when active/matched. Used for menu items
+ * with expandable sub-items or internal navigation.
+ *
+ * @param {boolean} [match] - Whether the sub-menu is currently active/matched
+ * @param {React.ReactNode} children - Sub-menu content
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {any} props - Additional HTML attributes
+ *
+ * @returns {React.ReactElement} A styled container for sub-menu items
+ */
 export const SubMenuContainer: React.FC<StyledLinkButtonProps> = ({
   match,
   children,
@@ -189,7 +285,19 @@ export const SubMenuContainer: React.FC<StyledLinkButtonProps> = ({
   );
 };
 
-// Sub menu items
+/**
+ * SubMenuItemContainer Component
+ *
+ * Container for a list of sub-menu items that appear below a parent menu item.
+ * Includes left border, gap spacing, and left margin for visual hierarchy.
+ * Used to display expandable/collapsible sub-menu items.
+ *
+ * @param {React.ReactNode} children - Sub-menu item elements
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Additional HTML div attributes
+ *
+ * @returns {React.ReactElement} A flex column container for sub-menu items
+ */
 export const SubMenuItemContainer: React.FC<BaseProps> = ({
   children,
   className,
@@ -208,7 +316,18 @@ export const SubMenuItemContainer: React.FC<BaseProps> = ({
   );
 };
 
-// Hover icons
+/**
+ * HoverIcon Component
+ *
+ * Container for icons that appear on hover within menu items.
+ * Hidden by default and shown only when parent element is hovered.
+ *
+ * @param {React.ReactNode} children - Icon element to show on hover
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Additional HTML div attributes
+ *
+ * @returns {React.ReactElement} A hidden flex container that shows on hover
+ */
 export const HoverIcon: React.FC<BaseProps> = ({
   children,
   className,
@@ -227,7 +346,18 @@ export const HoverIcon: React.FC<BaseProps> = ({
   );
 };
 
-// Animation wrapper
+/**
+ * AnimationWrapper Component
+ *
+ * Generic wrapper component for content that may have animation effects.
+ * Provides full width and height to accommodate animated children.
+ *
+ * @param {React.ReactNode} children - Content to wrap with animation support
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Additional HTML div attributes
+ *
+ * @returns {React.ReactElement} A full-size flex container for animated content
+ */
 export const AnimationWrapper: React.FC<BaseProps> = ({
   children,
   className,

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

@@ -29,6 +29,40 @@ export interface UserProfilePopupProps {
   collapsed?: boolean;
 }
 
+/**
+ * UserProfilePopup Component
+ *
+ * User profile dropdown menu component displayed in the sidebar footer. Shows user avatar/initials,
+ * and provides a menu with Account section, optional Active Devices, custom profile actions, and Logout.
+ * Automatically adapts layout when sidebar is collapsed (centered alignment, avatar only).
+ *
+ * @param {string} userFullName - User's full name (required, used for avatar text and display)
+ * @param {string} [email=''] - User's email address (shown in account section)
+ * @param {React.ReactNode[]} [profileActions=[]] - Custom menu items to include in the dropdown
+ * @param {() => void} [onLogout] - Callback handler when user clicks logout
+ * @param {string} [profileUrl] - URL to user's profile image (uses initials fallback if not provided)
+ * @param {string} [avatarClassName=''] - Additional CSS classes for the avatar component
+ * @param {boolean} [showActiveDevices=false] - Whether to show the "Active Devices" menu item
+ * @param {() => void} [onActiveDevicesClick] - Callback handler when user clicks active devices
+ * @param {() => void} [onAccountClick] - Callback handler when user clicks the account section
+ * @param {boolean} [collapsed] - Whether the sidebar is in collapsed state (affects layout)
+ *
+ * @returns {React.ReactElement} A dropdown menu anchored to user avatar with profile options
+ *
+ * @example
+ * ```tsx
+ * <UserProfilePopup
+ *   userFullName="Jane Smith"
+ *   email="jane@example.com"
+ *   profileUrl="/avatar.jpg"
+ *   showActiveDevices={true}
+ *   onLogout={handleLogout}
+ *   onAccountClick={navigateToSettings}
+ *   onActiveDevicesClick={showDevices}
+ *   collapsed={false}
+ * />
+ * ```
+ */
 export const UserProfilePopup: React.FC<UserProfilePopupProps> = ({
   collapsed,
   userFullName,
@@ -96,7 +130,7 @@ export const UserProfilePopup: React.FC<UserProfilePopupProps> = ({
           label={
             <div className="flex flex-col gap-1 flex-1">
               Account
-              <div className="flex flex-row items-center justify-between">
+              <div className="flex flex-row items-center justify-between gap-4">
                 <div className="flex flex-row gap-2">
                   <CircularAvatar
                     text={userFullName}

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

@@ -13,6 +13,27 @@ interface SidebarProviderProps {
   initialCollapsed?: boolean;
 }
 
+/**
+ * SidebarProvider Component
+ *
+ * React Context provider that manages global sidebar collapse state and provides methods
+ * to toggle and set the collapse state. Wraps the application or specific layout sections
+ * to enable sidebar state management across the component tree.
+ *
+ * @param {React.ReactNode} children - Child components that will have access to sidebar context
+ * @param {boolean} [initialCollapsed=false] - Initial collapsed state of the sidebar
+ *
+ * @returns {React.ReactElement} Context provider wrapping children with sidebar state
+ *
+ * @example
+ * ```tsx
+ * <SidebarProvider initialCollapsed={isMobile}>
+ *   <AppLayout>
+ *     <Content />
+ *   </AppLayout>
+ * </SidebarProvider>
+ * ```
+ */
 export const SidebarProvider: React.FC<SidebarProviderProps> = ({
   children,
   initialCollapsed = false,
@@ -30,6 +51,33 @@ export const SidebarProvider: React.FC<SidebarProviderProps> = ({
   );
 };
 
+/**
+ * useSidebar Hook
+ *
+ * Custom React hook to access the sidebar context state and methods.
+ * Must be used within a SidebarProvider component, otherwise it throws an error.
+ *
+ * @returns {{
+ *   collapsed: boolean;
+ *   toggleSidebar: () => void;
+ *   setCollapsed: (collapsed: boolean) => void;
+ * }} Object containing sidebar state and methods to control it
+ *
+ * @throws {Error} If used outside of SidebarProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { collapsed, toggleSidebar, setCollapsed } = useSidebar();
+ *
+ *   return (
+ *     <button onClick={toggleSidebar}>
+ *       {collapsed ? 'Expand' : 'Collapse'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export const useSidebar = () => {
   const context = useContext(SidebarContext);
   if (!context) {

package/src/components/Layout/AppLayout/types.ts

@@ -22,7 +22,7 @@ export interface AppLayoutProps {
   menu: SideMenuItemProps[];
 
   /**User profile parameters */
-  userProfileParams: UserProfilePopupProps;
+  userProfileParams?: UserProfilePopupProps;
 
   /** Switchers section customization - receives collapsed state */
   actions?: ReactNode | ((params: { collapsed: boolean }) => ReactNode);