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

package/src/components/Navigation/DropDownMenu/DropDownMenu.tsx

@@ -7,20 +7,93 @@ import {
 } from '@/shadcn-components/Navigation/DropdownMenu/DropdownMenu';
 import { ReactNode, useEffect, useRef, useState } from 'react';
 
+/**
+ * Props for the DropdownMenu component
+ */
 export type DropdownMenuProps = {
+  /** Function that renders the dropdown trigger element. Receives open callback to open the dropdown */
   anchor: (props: { open: (e: any) => void }) => ReactNode;
+  /** Array of menu items or a function that returns menu items. Can be static or dynamic */
   menu?: ReactNode[] | ((props: { close: () => void }) => ReactNode[]);
+  /** Custom slot for rendering the entire menu content. Takes precedence over menu when useMenuSlot is true */
   menuSlot?: (props: { close: () => void }) => ReactNode;
+  /** Whether to use menuSlot instead of menu items. Defaults to false */
   useMenuSlot?: boolean;
+  /** Optional CSS class names for the menu content container */
   menuContentClassName?: string;
+  /** Optional CSS class names for the menu list wrapper div */
   menuListClassName?: string;
+  /** Optional React element or component to render above the menu items */
   menuHeader?: ReactNode;
+  /** Optional React element or component to render below the menu items */
   menuFooter?: ReactNode;
+  /** Optional async callback fired when the menu is scrolled, useful for infinite scroll */
   handleMenuScroll?: (event: any) => Promise<void>;
+  /** Horizontal alignment of the dropdown menu relative to the trigger. Defaults to 'end' */
   align?: 'start' | 'center' | 'end';
+  /** Vertical placement of the dropdown menu relative to the trigger. Defaults to 'bottom' */
   side?: 'top' | 'right' | 'bottom' | 'left';
 };
 
+/**
+ * DropdownMenu component that provides a flexible dropdown menu with trigger element and menu content.
+ *
+ * This component wraps shadcn/ui's DropdownMenu and adds support for dynamic menu items,
+ * header/footer sections, and custom scroll handling. It manages its own open/close state
+ * and provides a convenient API for both static and dynamic menu items.
+ *
+ * @component
+ * @param {DropdownMenuProps} props - The component props
+ * @param {(props: { open: (e: any) => void }) => ReactNode} props.anchor - Render function for the trigger element
+ * @param {ReactNode[] | ((props: { close: () => void }) => ReactNode[])} [props.menu] - Menu items array or function
+ * @param {(props: { close: () => void }) => ReactNode} [props.menuSlot] - Custom menu content renderer
+ * @param {boolean} [props.useMenuSlot=false] - Whether to use menuSlot instead of menu items
+ * @param {string} [props.menuContentClassName] - CSS classes for the menu content container
+ * @param {string} [props.menuListClassName] - CSS classes for the menu list wrapper
+ * @param {ReactNode} [props.menuHeader] - Content to display above the menu items
+ * @param {ReactNode} [props.menuFooter] - Content to display below the menu items
+ * @param {(event: any) => Promise<void>} [props.handleMenuScroll] - Async callback for scroll events
+ * @param {'start' | 'center' | 'end'} [props.align='end'] - Horizontal alignment of the menu
+ * @param {'top' | 'right' | 'bottom' | 'left'} [props.side='bottom'] - Vertical placement of the menu
+ *
+ * @returns {React.ReactElement} A dropdown menu component with trigger and content
+ *
+ * @example
+ * // Simple dropdown with static menu items
+ * <DropdownMenu
+ *   anchor={({ open }) => <button onClick={open}>Actions</button>}
+ *   menu={[
+ *     <button key="1">Edit</button>,
+ *     <button key="2">Delete</button>,
+ *   ]}
+ * />
+ *
+ * @example
+ * // Dropdown with dynamic menu items and header
+ * <DropdownMenu
+ *   anchor={({ open }) => <IconButton icon={<MoreIcon />} onClick={open} />}
+ *   menu={({ close }) => items.map(item => (
+ *     <button key={item.id} onClick={() => { selectItem(item); close(); }}>
+ *       {item.name}
+ *     </button>
+ *   ))}
+ *   menuHeader={<span className="px-2 py-1 text-sm font-semibold">Options</span>}
+ *   align="start"
+ * />
+ *
+ * @example
+ * // Dropdown with infinite scroll
+ * <DropdownMenu
+ *   anchor={({ open }) => <button onClick={open}>Load More</button>}
+ *   menu={filteredItems}
+ *   menuFooter={<span className="text-xs text-muted">Showing {items.length} items</span>}
+ *   handleMenuScroll={async (e) => {
+ *     if (isNearBottom(e)) {
+ *       await loadMoreItems();
+ *     }
+ *   }}
+ * />
+ */
 export const DropdownMenu = ({
   menu = [],
   menuSlot,

package/src/components/Navigation/PreviewFiles/PreviewFiles.tsx

@@ -19,15 +19,69 @@ type FileInfo = {
   url: string;
 };
 
+/**
+ * Props for the PreviewFiles component
+ */
 export type PreviewFilesProps = {
+  /** Array of files or single file to display. Can be File objects or string URLs. Accepts null for empty state */
   files: File[] | File | string[] | string | null;
+  /** Optional label text displayed above the file list */
   label?: string;
+  /** Optional callback fired when files are deleted. Receives remaining files array and deleted file */
   onChange?: (newFiles: File[], deletedFile: File) => void;
+  /** Whether to show download button for each file. Defaults to false */
   showDownload?: boolean;
+  /** Whether to hide the delete button for each file. Defaults to false */
   hideDelete?: boolean;
+  /** Optional CSS class names for the container element */
   className?: string;
 };
 
+/**
+ * PreviewFiles component that displays a list of files with preview, download, and delete functionality.
+ *
+ * This component renders file items in a grid/list format with icons, sizes, and action buttons.
+ * It supports both File objects and URL strings, automatically fetching file information for remote files.
+ * Users can preview files by clicking on them, download them, and delete them from the list.
+ *
+ * @component
+ * @param {PreviewFilesProps} props - The component props
+ * @param {File[] | File | string[] | string | null} props.files - Files to display (File objects or URLs)
+ * @param {string} [props.label] - Optional label text displayed above the file list
+ * @param {(newFiles: File[], deletedFile: File) => void} [props.onChange] - Callback when files are deleted
+ * @param {boolean} [props.showDownload=false] - Whether to show download button
+ * @param {boolean} [props.hideDelete=false] - Whether to hide delete button
+ * @param {string} [props.className] - Optional CSS classes for the container
+ *
+ * @returns {React.ReactElement | null} A div containing the file list, or null if no files
+ *
+ * @example
+ * // Display File objects with delete capability
+ * <PreviewFiles
+ *   files={uploadedFiles}
+ *   label="Uploaded Files"
+ *   onChange={(newFiles, deleted) => setFiles(newFiles)}
+ * />
+ *
+ * @example
+ * // Display remote files with download button
+ * <PreviewFiles
+ *   files={['https://example.com/file1.pdf', 'https://example.com/file2.docx']}
+ *   label="Documents"
+ *   showDownload={true}
+ *   hideDelete={true}
+ * />
+ *
+ * @example
+ * // Mixed files with custom styling
+ * <PreviewFiles
+ *   files={[file1, 'https://example.com/file.pdf']}
+ *   label="Files"
+ *   showDownload={true}
+ *   onChange={handleFileDelete}
+ *   className="bg-gray-50 p-4 rounded-lg"
+ * />
+ */
 export const PreviewFiles = ({
   files,
   label,
@@ -234,6 +288,16 @@ export const PreviewFiles = ({
   );
 };
 
+/**
+ * Formats a file size in bytes to a human-readable string.
+ *
+ * @param {number} size - File size in bytes
+ * @returns {string} Formatted file size (e.g., "1.5 MB", "256 KB")
+ *
+ * @example
+ * formatFileSize(1024) // "1.00 KB"
+ * formatFileSize(1048576) // "1.00 MB"
+ */
 const formatFileSize = (size: number) => {
   if (size < 1024) return `${size} bytes`;
   if (size < 1048576) return `${(size / 1024).toFixed(2)} KB`;
@@ -241,6 +305,15 @@ const formatFileSize = (size: number) => {
   return `${(size / 1073741824).toFixed(2)} GB`;
 };
 
+/**
+ * Returns the appropriate icon component for a file based on its MIME type.
+ *
+ * @param {File | FileInfo} file - File object to get icon for
+ * @returns {React.ReactElement} Icon component for the file type
+ *
+ * @example
+ * getFileIcon(file) // Returns Image icon for image files, FileText for PDFs, etc.
+ */
 const getFileIcon = (file: File | FileInfo) => {
   const IconComponent =
     Object.entries(FILE_TYPE_ICON_MAP).find(([key]) =>
@@ -249,6 +322,16 @@ const getFileIcon = (file: File | FileInfo) => {
   return <IconComponent size={30} />;
 };
 
+/**
+ * Creates a FileInfo object from a URL string, extracting file name and MIME type.
+ *
+ * @param {string} fileUrl - URL of the file
+ * @returns {FileInfo} FileInfo object with name, type, and url
+ *
+ * @example
+ * createFileInfoFromUrl('https://example.com/document.pdf')
+ * // Returns { name: 'document.pdf', type: 'application/pdf', size: 0, url: '...' }
+ */
 const createFileInfoFromUrl = (fileUrl: string): FileInfo => {
   const fileName = fileUrl.split('/').pop() || 'unknown_file';
   const extension = Object.keys(EXTENSION_TO_MIME_TYPE).find((ext) =>
@@ -266,6 +349,16 @@ const createFileInfoFromUrl = (fileUrl: string): FileInfo => {
   };
 };
 
+/**
+ * Fetches the file size for a remote file by making a HEAD request or partial GET request.
+ *
+ * @param {string} url - URL of the file to fetch size for
+ * @returns {Promise<number>} File size in bytes, or 0 if unable to determine
+ *
+ * @example
+ * const size = await fetchFileSizeAsync('https://example.com/file.pdf');
+ * console.log(size); // File size in bytes
+ */
 const fetchFileSizeAsync = async (url: string): Promise<number> => {
   try {
     const response = await fetch(url, { method: 'HEAD' });

package/src/components/Navigation/Stepper/Stepper.tsx

@@ -3,37 +3,83 @@ import HorizontalStepper from './HorizontalStepper';
 import VerticalStepper from './VerticalStepper';
 
 /**
- * Interface for individual step items
+ * Interface for individual step items in the stepper
  */
 export interface StepItem {
-  /** The label text for the step */
+  /** The label text displayed for this step */
   label: string;
-  /** Optional description text shown below the label */
+  /** Optional description text shown below the label for additional context */
   description?: string;
 }
 
 /**
- * Props for the Stepper Variant components
+ * Props for the Stepper variant components (HorizontalStepper and VerticalStepper)
  */
 export interface StepperVariantProps {
-  /** Current active step index (0-based) */
+  /** Current active step index (0-based). Determines which step is highlighted */
   activeStep: number;
   /** Array of step items with labels and optional descriptions */
   steps: StepItem[];
-  /** Additional className for the container */
+  /** Additional CSS class names for the stepper container element */
   containerClassName?: string;
-  /** Callback function called when a step is clicked. Receives the step index as parameter */
+  /** Callback function fired when a step is clicked. Receives the step index (0-based) as parameter */
   onStepClick?: (stepIndex: number) => void;
-  /** Whether to allow navigation by clicking on steps. Defaults to true */
+  /** Whether to allow users to navigate by clicking on steps. Defaults to true */
   allowNavigation?: boolean;
 }
+
+/**
+ * Props for the Stepper component
+ */
 export type StepperProps = StepperVariantProps & {
-  /** Orientation of the stepper - horizontal or vertical */
+  /** Orientation of the stepper layout - 'horizontal' displays steps left-to-right, 'vertical' displays top-to-bottom. Defaults to 'horizontal' */
   orientation?: 'vertical' | 'horizontal';
 };
 
 /**
- * Main Stepper component that handles both horizontal and vertical orientations
+ * Stepper component that displays a progress indicator with multiple steps.
+ *
+ * This is a wrapper component that renders either HorizontalStepper or VerticalStepper
+ * based on the orientation prop. It provides a visual representation of progress through
+ * a sequence of steps, with optional click handlers for step navigation.
+ *
+ * @component
+ * @param {StepperProps} props - The component props
+ * @param {number} props.activeStep - Index of the currently active step (0-based)
+ * @param {StepItem[]} props.steps - Array of steps with label and optional description
+ * @param {'horizontal' | 'vertical'} [props.orientation='horizontal'] - Layout orientation
+ * @param {string} [props.containerClassName] - Optional CSS classes for the container
+ * @param {(stepIndex: number) => void} [props.onStepClick] - Callback when a step is clicked
+ * @param {boolean} [props.allowNavigation=true] - Whether clicking on steps navigates between them
+ *
+ * @returns {React.ReactElement} A HorizontalStepper or VerticalStepper component
+ *
+ * @example
+ * // Horizontal stepper (default)
+ * <Stepper
+ *   activeStep={1}
+ *   steps={[
+ *     { label: 'Step 1', description: 'Enter details' },
+ *     { label: 'Step 2', description: 'Confirm' },
+ *     { label: 'Step 3', description: 'Complete' }
+ *   ]}
+ *   onStepClick={(index) => setActiveStep(index)}
+ * />
+ *
+ * @example
+ * // Vertical stepper with custom styling
+ * <Stepper
+ *   orientation="vertical"
+ *   activeStep={2}
+ *   steps={[
+ *     { label: 'Personal Info' },
+ *     { label: 'Address' },
+ *     { label: 'Payment' },
+ *     { label: 'Review' }
+ *   ]}
+ *   containerClassName="bg-gray-50 p-6 rounded"
+ *   allowNavigation={false}
+ * />
  */
 const Stepper: React.FC<StepperProps> = ({
   orientation = 'horizontal',

package/src/components/Navigation/TabsContainer/TabsContainer.tsx

@@ -6,27 +6,110 @@ import {
   TabsList,
   TabsTrigger,
 } from '@/shadcn-components/Navigation/Tabs/Tabs';
-import { useEffect, useState } from 'react';
+import { CSSProperties, useEffect, useState } from 'react';
 
+/**
+ * Configuration for an individual tab in TabsContainer
+ */
 interface CustomTabProps {
+  /** Unique identifier for the tab. Can be string or number */
   key: string | number;
+  /** Display label or React element for the tab trigger */
   label: React.ReactNode;
+  /** React component or element to render when this tab is active */
   component: React.ReactNode;
+  /** Whether to show a highlight indicator (dot) on the tab trigger. Defaults to false */
   highlight?: boolean;
+  /** Whether the tab is disabled and cannot be selected. Defaults to false */
   disabled?: boolean;
+  /** Optional icon or React element to display before the label */
   icon?: React.ReactNode;
 }
 
+/**
+ * Props for the TabsContainer component
+ */
 export interface TabsContainerProps {
+  /** Array of tab configurations with labels, content, and optional metadata */
   tabs: CustomTabProps[];
+  /** Optional callback fired when a tab is selected. Receives the tab key as parameter */
   onTabChange?: (tabKey: string) => void;
+  /** Index of the tab to show initially. Defaults to 0 (first tab) */
   currentTabIndex?: number;
+  /** Optional CSS class names for the Tabs root element */
   className?: string;
+  /** Optional CSS class names for the TabsList container */
   tabsListClassName?: string;
+  /** Optional CSS class names for each TabsTrigger element */
   tabsTriggerClassName?: string;
+  /** Optional inline styles for the TabsContent container */
+  tabsContainerStyles?: CSSProperties;
+  /** Layout variant - 'fixed' uses viewport height, 'dynamic' uses content height. Defaults to 'fixed' */
   variant?: 'fixed' | 'dynamic';
 }
 
+/**
+ * TabsContainer component that displays tabbed content with a tab list and content area.
+ *
+ * This component provides a responsive tab interface with support for icons, highlights,
+ * disabled states, and two layout modes (fixed height for viewport or dynamic height for content).
+ * It manages tab selection state and provides callbacks for external state management.
+ *
+ * @component
+ * @param {TabsContainerProps} props - The component props
+ * @param {CustomTabProps[]} props.tabs - Array of tab configurations
+ * @param {(tabKey: string) => void} [props.onTabChange] - Callback when a tab is selected
+ * @param {number} [props.currentTabIndex=0] - Initially active tab index
+ * @param {string} [props.className] - CSS classes for the Tabs root
+ * @param {string} [props.tabsListClassName] - CSS classes for the TabsList
+ * @param {string} [props.tabsTriggerClassName] - CSS classes for TabsTrigger elements
+ * @param {CSSProperties} [props.tabsContainerStyles] - Inline styles for TabsContent
+ * @param {'fixed' | 'dynamic'} [props.variant='fixed'] - Layout mode for tab content
+ *
+ * @returns {React.ReactElement} A Tabs component with tab list and content area
+ *
+ * @example
+ * // Basic tabs
+ * <TabsContainer
+ *   tabs={[
+ *     { key: 'tab1', label: 'Overview', component: <OverviewPanel /> },
+ *     { key: 'tab2', label: 'Details', component: <DetailsPanel /> },
+ *   ]}
+ *   onTabChange={(key) => console.log('Selected:', key)}
+ * />
+ *
+ * @example
+ * // Tabs with icons and highlights
+ * <TabsContainer
+ *   tabs={[
+ *     {
+ *       key: 'notifications',
+ *       label: 'Notifications',
+ *       icon: <BellIcon />,
+ *       component: <NotificationsList />,
+ *       highlight: unreadCount > 0
+ *     },
+ *     {
+ *       key: 'settings',
+ *       label: 'Settings',
+ *       icon: <SettingsIcon />,
+ *       component: <SettingsPanel />
+ *     },
+ *   ]}
+ *   variant="dynamic"
+ *   className="min-h-screen"
+ * />
+ *
+ * @example
+ * // Tabs with disabled state
+ * <TabsContainer
+ *   tabs={[
+ *     { key: 'basic', label: 'Basic Info', component: <BasicForm /> },
+ *     { key: 'advanced', label: 'Advanced', component: <AdvancedForm />, disabled: !basicComplete },
+ *   ]}
+ *   currentTabIndex={0}
+ * />
+ */
 export const TabsContainer = ({
   tabs,
   onTabChange,
@@ -34,6 +117,7 @@ export const TabsContainer = ({
   className,
   tabsListClassName,
   tabsTriggerClassName,
+  tabsContainerStyles,
   variant = 'fixed',
 }: TabsContainerProps) => {
   const isSmallScreen = useMediaQuery('(max-width: 768px)');
@@ -88,6 +172,7 @@ export const TabsContainer = ({
                   ? `calc(100vh - 98px)`
                   : `calc(100vh - 80px)`
                 : 'max-content',
+            ...tabsContainerStyles,
           }}
         >
           {component}

package/src/components/Navigation/UploadDialog/UploadDialog.tsx

@@ -6,17 +6,81 @@ import { PreviewFiles } from '../PreviewFiles/PreviewFiles';
 import { LoadingUploadDialogContainer } from './LoadingUploadDialogContainer';
 import { UploadDialogContainer } from './UploadDialogContainer';
 
+/**
+ * Props for the UploadDialog component
+ */
 export type UploadDialogProps = {
+  /** Function that renders the dialog trigger element. Receives open callback to open the dialog */
   anchor: (props: { open: () => void }) => ReactNode;
+  /** Optional callback fired when the dialog opens */
   onDialogOpen?: () => void;
+  /** Optional callback fired when the dialog closes */
   onDialogClose?: () => void;
+  /** Title displayed in the dialog header. Defaults to 'Upload File' */
   title?: string;
+  /** Optional URL to a sample file for download */
   sampleFileUrl?: string;
+  /** Callback function fired when the Upload Now button is clicked. Receives single File or File[] */
   onUpload: (file: File | File[]) => void;
+  /** HTML accept attribute value for the file input (e.g., '.pdf,.doc', 'image/*'). Defaults to all files */
   acceptFileType?: string;
+  /** Whether the upload is currently in progress. Defaults to false */
   loading?: boolean;
 };
 
+/**
+ * UploadDialog component that provides a file upload interface with preview and download sample options.
+ *
+ * This component manages file selection, displays selected file previews with delete capability,
+ * and provides options to download sample files. It supports loading states and file type filtering.
+ * The upload is triggered via an anchor element (trigger) that's configurable.
+ *
+ * @component
+ * @param {UploadDialogProps} props - The component props
+ * @param {(props: { open: () => void }) => ReactNode} props.anchor - Render function for the trigger element
+ * @param {(file: File | File[]) => void} props.onUpload - Callback when upload button is clicked
+ * @param {string} [props.title='Upload File'] - Dialog header title
+ * @param {string} [props.sampleFileUrl] - URL to download a sample file
+ * @param {string} [props.acceptFileType] - File type filter for the input (e.g., '.pdf', 'image/*')
+ * @param {boolean} [props.loading=false] - Whether upload is in progress
+ * @param {() => void} [props.onDialogOpen] - Callback when dialog opens
+ * @param {() => void} [props.onDialogClose] - Callback when dialog closes
+ *
+ * @returns {React.ReactElement} A fragment with the anchor element and Upload Dialog
+ *
+ * @example
+ * // Basic file upload
+ * <UploadDialog
+ *   anchor={({ open }) => <button onClick={open}>Upload</button>}
+ *   title="Upload Document"
+ *   onUpload={(file) => uploadToServer(file)}
+ * />
+ *
+ * @example
+ * // Upload with sample file and type restriction
+ * <UploadDialog
+ *   anchor={({ open }) => <IconButton icon={<UploadIcon />} onClick={open} />}
+ *   title="Upload CSV File"
+ *   acceptFileType=".csv"
+ *   sampleFileUrl="https://example.com/sample.csv"
+ *   onUpload={async (file) => {
+ *     await uploadFile(file);
+ *     setUploadComplete(true);
+ *   }}
+ *   loading={isUploading}
+ *   onDialogClose={() => setIsUploading(false)}
+ * />
+ *
+ * @example
+ * // Image upload with loading state
+ * <UploadDialog
+ *   anchor={({ open }) => <button onClick={open}>Choose Avatar</button>}
+ *   title="Select Avatar"
+ *   acceptFileType="image/*"
+ *   onUpload={(file) => updateAvatar(file)}
+ *   loading={uploadInProgress}
+ * />
+ */
 export const UploadDialog = ({
   onUpload,
   sampleFileUrl,

package/src/shadcn-components/Layout/Sheet/Sheet.tsx

@@ -34,7 +34,7 @@ function SheetOverlay({
     <SheetPrimitive.Overlay
       data-slot="sheet-overlay"
       className={cn(
-        'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50',
+        'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0  bg-black/50',
         className,
       )}
       {...props}
@@ -56,7 +56,7 @@ function SheetContent({
       <SheetPrimitive.Content
         data-slot="sheet-content"
         className={cn(
-          'bg-background data-[state=open]:animate-in data-[state=closed]:animate-out fixed z-50 flex flex-col gap-4 shadow-lg transition ease-in-out data-[state=closed]:duration-300 data-[state=open]:duration-500',
+          'bg-background data-[state=open]:animate-in data-[state=closed]:animate-out fixed  flex flex-col gap-4 shadow-lg transition ease-in-out data-[state=closed]:duration-300 data-[state=open]:duration-500',
           side === 'right' &&
             'data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right inset-y-0 right-0 h-full w-3/4 border-l sm:max-w-sm',
           side === 'left' &&