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

package/src/components/Input/SingleSelect/SingleSelect.tsx

@@ -54,6 +54,46 @@ export type SingleSelectProps = {
   loading?: boolean;
 };
 
+/**
+ * SingleSelect component for single-value selection
+ *
+ * A feature-rich single-select component supporting both local and API-driven options,
+ * with search, pagination, filtering, and flexible display modes.
+ *
+ * @component
+ * @param {SingleSelectProps} props - The select properties
+ * @param {Array<{label: string, subLabel?: string, value: any, icon?: ReactNode}>} [props.options] - Static options array
+ * @param {string} [props.optionsApiEndPoint] - API endpoint for dynamic options loading
+ * @param {any} [props.optionsApiEndpointParams] - Additional parameters for API requests
+ * @param {AxiosInstance} [props.externalAxios] - Custom axios instance for API calls
+ * @param {any} [props.value] - Currently selected value
+ * @param {(value: any) => void} [props.onChange] - Callback fired when selection changes
+ * @param {(option: any) => any} [props.getValue] - Function to extract value from option object
+ * @param {{valueKey: string, isObjectId?: boolean, isInt?: boolean, isFloat?: boolean}} [props.dbValueProps] - Database value mapping properties
+ * @param {{labelKey: string, subLabelKey?: string, useLabelStartCase?: boolean, useSubLabelStartCase?: boolean}} [props.dbLabelProps] - Database label mapping properties
+ * @param {string} [props.label] - Label for the select
+ * @param {string} [props.name] - Name attribute
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether the select is disabled
+ * @param {boolean} [props.loading] - Whether options are loading
+ * @param {boolean} [props.disableClear] - Whether to hide the clear button
+ * @param {boolean} [props.fullWidth] - Whether the select takes full width
+ * @param {'input' | 'filter'} [props.type='input'] - Display type
+ * @param {(event: SyntheticEvent) => void} [props.onOpen] - Callback when menu opens
+ * @param {(event: SyntheticEvent, reason: string) => void} [props.onClose] - Callback when menu closes
+ * @returns {React.ReactElement} The rendered single-select component
+ *
+ * @example
+ * ```tsx
+ * <SingleSelect
+ *   label="Select User"
+ *   value={selectedUser}
+ *   onChange={setSelectedUser}
+ *   options={users}
+ *   required
+ * />
+ * ```
+ */
 export const SingleSelect = ({
   options,
   optionsApiEndPoint,

package/src/components/Input/Switch/Switch.tsx

@@ -7,6 +7,29 @@ export interface SwitchProps
   label?: string;
 }
 
+/**
+ * Switch component for boolean toggle input
+ *
+ * A toggle switch component with optional label support, built on shadcn's Switch.
+ * Renders a label beside the switch if provided.
+ *
+ * @component
+ * @param {SwitchProps} props - The switch properties
+ * @param {string} [props.label] - Optional label text to display next to the switch
+ * @param {boolean} [props.checked] - Whether the switch is checked
+ * @param {(checked: boolean) => void} [props.onCheckedChange] - Callback when switch state changes
+ * @param {boolean} [props.disabled] - Whether the switch is disabled
+ * @returns {React.ReactElement} The rendered switch component
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   label="Enable notifications"
+ *   checked={enabled}
+ *   onCheckedChange={setEnabled}
+ * />
+ * ```
+ */
 export const Switch = React.forwardRef<
   React.ElementRef<typeof ShadcnSwitch>,
   SwitchProps

package/src/components/Input/Tags/Tags.tsx

@@ -9,6 +9,32 @@ export type TagsProps = {
   className?: string;
 };
 
+/**
+ * Tags component for displaying and managing tag badges
+ *
+ * A component that renders a collection of tags/badges with optional delete functionality.
+ * Useful for displaying categories, labels, or removable items.
+ *
+ * @component
+ * @param {TagsProps} props - The tags properties
+ * @param {Array<{label: string, value: any}>} props.tags - Array of tags to display
+ * @param {(deletedChip: any) => void} [props.onDelete] - Callback fired when a tag is deleted
+ * @param {'default' | 'secondary' | 'destructive' | 'outline'} [props.variant='secondary'] - Badge variant style
+ * @param {string} [props.className] - Additional CSS classes for the container
+ * @returns {React.ReactElement} The rendered tags component
+ *
+ * @example
+ * ```tsx
+ * <Tags
+ *   tags={[
+ *     { label: 'React', value: 'react' },
+ *     { label: 'TypeScript', value: 'ts' }
+ *   ]}
+ *   onDelete={handleTagDelete}
+ *   variant="secondary"
+ * />
+ * ```
+ */
 export const Tags = ({
   tags,
   onDelete,

package/src/components/Input/TextField/TextField.tsx

@@ -14,6 +14,41 @@ export type TextFieldProps = {
   helperText?: React.ReactNode;
 } & React.ComponentProps<typeof Input>;
 
+/**
+ * TextField component for text input
+ *
+ * A general-purpose text input field with label support, validation states,
+ * helper/error text, and optional description.
+ *
+ * @component
+ * @param {TextFieldProps} props - The text field properties
+ * @param {React.ReactNode | string} [props.label] - Label for the field
+ * @param {string} [props.name] - Name attribute for the input
+ * @param {string} [props.value] - Current input value
+ * @param {(e: React.ChangeEvent<HTMLInputElement>) => void} [props.onChange] - Callback when value changes
+ * @param {string} [props.placeholder] - Placeholder text
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether the field is disabled
+ * @param {boolean} [props.error] - Whether there's a validation error
+ * @param {React.ReactNode} [props.helperText] - Helper or error text
+ * @param {string} [props.description] - Additional description text
+ * @param {boolean} [props.fullWidth] - Whether the field takes full width
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.HTMLAttributes<HTMLDivElement>} [props.containerProps] - Container attributes
+ * @returns {React.ReactElement} The rendered text field component
+ *
+ * @example
+ * ```tsx
+ * <TextField
+ *   label="Username"
+ *   name="username"
+ *   value={username}
+ *   onChange={(e) => setUsername(e.target.value)}
+ *   placeholder="Enter your username"
+ *   required
+ * />
+ * ```
+ */
 export const TextField = ({
   name,
   label,

package/src/components/Input/Textarea/Textarea.tsx

@@ -14,6 +14,42 @@ export type TextareaProps = {
   helperText?: React.ReactNode;
 } & React.ComponentProps<typeof ShadcnTextarea>;
 
+/**
+ * Textarea component for multi-line text input
+ *
+ * A multi-line text input field with label support, validation states,
+ * helper/error text, and optional description.
+ *
+ * @component
+ * @param {TextareaProps} props - The textarea properties
+ * @param {React.ReactNode | string} [props.label] - Label for the field
+ * @param {string} [props.name] - Name attribute for the textarea
+ * @param {string} [props.value] - Current input value
+ * @param {(e: React.ChangeEvent<HTMLTextAreaElement>) => void} [props.onChange] - Callback when value changes
+ * @param {string} [props.placeholder] - Placeholder text
+ * @param {number} [props.rows] - Number of visible rows
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether the field is disabled
+ * @param {boolean} [props.error] - Whether there's a validation error
+ * @param {React.ReactNode} [props.helperText] - Helper or error text
+ * @param {string} [props.description] - Additional description text
+ * @param {boolean} [props.fullWidth] - Whether the field takes full width
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.HTMLAttributes<HTMLDivElement>} [props.containerProps] - Container attributes
+ * @returns {React.ReactElement} The rendered textarea component
+ *
+ * @example
+ * ```tsx
+ * <Textarea
+ *   label="Comments"
+ *   name="comments"
+ *   value={comments}
+ *   onChange={(e) => setComments(e.target.value)}
+ *   placeholder="Enter your comments..."
+ *   rows={4}
+ * />
+ * ```
+ */
 export const Textarea = ({
   name,
   label,

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

@@ -1,11 +1,41 @@
-import { FileText } from 'lucide-react';
 import React from 'react';
 import { useMediaQuery } from '../../../hooks/useMediaQuery';
-import { Button } from '../../Input/Button/Button';
 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,
@@ -58,22 +88,15 @@ const AppLayoutContent: React.FC<AppLayoutProps> = ({
         }
       />
 
-      <Button
-        className="bg-gradient-to-r from-[#573DAB] to-[#846AD6] rounded-[32px] fixed bottom-4 right-4 z-[999] p-2"
-        onClick={() => window.open('https://docs.campx.in/', '_blank')}
-      >
-        <FileText className="w-8 h-8 text-white" />
-      </Button>
-
       {/* Main Content */}
       <div
         style={{
           height: '100vh',
-          overflow: 'hidden',
+          overflow: 'auto',
           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 };