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

package/src/components/Navigation/ConfirmDialog/ConfirmDialog.tsx

@@ -3,22 +3,86 @@ import { Typography } from '@/shadcn-components/DataDisplay/Typography/Typograph
 import { Button } from '@/shadcn-components/Input/Button/Button';
 import { AnimatedGIFs } from '../../../assets/images/gif';
 
+/**
+ * Type definition for the kind of confirmation dialog
+ */
 export type ConfirmDialogType = 'confirm' | 'delete';
 
+/**
+ * Available max-width sizes for the dialog
+ */
 type MaxWidthSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 
+/**
+ * Props for the ConfirmDialog component
+ */
 export type ConfirmDialogProps = {
+  /** Whether the dialog is open and visible */
   isOpen: boolean;
+  /** Title text displayed in the dialog header */
   title: string;
+  /** Message/description text displayed in the dialog */
   message: string;
+  /** Callback function triggered when the user confirms the action */
   onConfirm: () => void;
+  /** Callback function triggered when the user cancels the dialog */
   onCancel: () => void;
+  /** Type of confirmation dialog - 'confirm' for general confirmations, 'delete' for destructive actions */
   type: ConfirmDialogType;
+  /** Custom text for the confirm button. Defaults to 'Confirm Delete' for delete type, 'Confirm' otherwise */
   confirmButtonText?: string;
+  /** Custom text for the cancel button. Defaults to 'Cancel' */
   cancelButtonText?: string;
+  /** Max-width size class of the dialog. Defaults to 'xl' */
   maxWidth?: MaxWidthSize;
 };
 
+/**
+ * ConfirmDialog component that displays a modal confirmation dialog with custom title, message, and action buttons.
+ *
+ * This component provides a user-friendly confirmation interface with support for two types:
+ * 'confirm' for general confirmations and 'delete' for destructive operations. The dialog
+ * includes an animated GIF icon that changes based on the dialog type.
+ *
+ * @component
+ * @param {ConfirmDialogProps} props - The component props
+ * @param {boolean} props.isOpen - Whether the dialog is currently open
+ * @param {string} props.title - Dialog title text
+ * @param {string} props.message - Dialog message/body text
+ * @param {() => void} props.onConfirm - Callback fired when the confirm button is clicked
+ * @param {() => void} props.onCancel - Callback fired when the cancel button is clicked or dialog is closed
+ * @param {ConfirmDialogType} props.type - Dialog type ('confirm' or 'delete') which affects styling and default text
+ * @param {string} [props.confirmButtonText] - Custom text for confirm button
+ * @param {string} [props.cancelButtonText] - Custom text for cancel button
+ * @param {MaxWidthSize} [props.maxWidth='xl'] - Maximum width of the dialog
+ *
+ * @returns {React.ReactElement} A Dialog component with header, message, and action buttons
+ *
+ * @example
+ * // Basic confirmation dialog
+ * <ConfirmDialog
+ *   isOpen={isOpen}
+ *   type="confirm"
+ *   title="Confirm Action"
+ *   message="Are you sure you want to proceed?"
+ *   onConfirm={() => handleAction()}
+ *   onCancel={() => setIsOpen(false)}
+ * />
+ *
+ * @example
+ * // Delete confirmation dialog with custom buttons
+ * <ConfirmDialog
+ *   isOpen={deleteOpen}
+ *   type="delete"
+ *   title="Delete Item"
+ *   message="This action cannot be undone. All data will be permanently deleted."
+ *   confirmButtonText="Yes, Delete"
+ *   cancelButtonText="Keep Item"
+ *   onConfirm={() => deleteItem()}
+ *   onCancel={() => setDeleteOpen(false)}
+ *   maxWidth="md"
+ * />
+ */
 export const ConfirmDialog: React.FC<ConfirmDialogProps> = ({
   isOpen,
   title,

package/src/components/Navigation/Dialog/Dialog.tsx

@@ -1,18 +1,73 @@
 import { DialogHeader, Dialog as ShadcnDialog, DialogContent as ShadcnDialogContent, DialogTitle as ShadcnDialogTitle } from '@/shadcn-components/DataDisplay/Dialog/Dialog';
 import { ReactNode } from 'react';
 
+/**
+ * Available max-width sizes for the dialog
+ */
 type MaxWidthSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 
+/**
+ * Props for the Dialog component
+ */
 type DialogProps = {
+  /** Function that renders the dialog content. Receives close callback to allow closing from within content */
   content: (props: { close: () => void }) => ReactNode;
+  /** Optional title displayed in the dialog header */
   title?: string | undefined;
+  /** Callback function triggered when the dialog is closed */
   onClose: () => void;
+  /** Whether the dialog is open and visible */
   open: boolean;
+  /** Optional CSS class names for the dialog content element */
   className?: string;
+  /** Whether to show the close button in the dialog header. Defaults to true */
   showCloseButton?: boolean;
+  /** Max-width size class of the dialog. Defaults to 'lg' */
   maxWidth?: MaxWidthSize;
 };
 
+/**
+ * Dialog component that wraps shadcn/ui Dialog with additional features and sensible defaults.
+ *
+ * This component provides a controlled dialog with optional header, configurable width,
+ * and flexible content rendering with a close callback for self-closing from within the content.
+ *
+ * @component
+ * @param {DialogProps} props - The component props
+ * @param {(props: { close: () => void }) => ReactNode} props.content - Render function for dialog content
+ * @param {() => void} props.onClose - Callback fired when the dialog is closed
+ * @param {boolean} props.open - Whether the dialog is currently open
+ * @param {string} [props.title] - Optional dialog title
+ * @param {string} [props.className] - Optional CSS classes for the dialog content
+ * @param {boolean} [props.showCloseButton=true] - Whether to show the close button
+ * @param {MaxWidthSize} [props.maxWidth='lg'] - Maximum width of the dialog
+ *
+ * @returns {React.ReactElement} A Dialog component with optional header and flexible content
+ *
+ * @example
+ * // Simple dialog with title
+ * <Dialog
+ *   open={isOpen}
+ *   title="Delete Item"
+ *   onClose={() => setIsOpen(false)}
+ *   content={({ close }) => (
+ *     <div>
+ *       <p>Are you sure?</p>
+ *       <button onClick={close}>Cancel</button>
+ *     </div>
+ *   )}
+ * />
+ *
+ * @example
+ * // Dialog without title and custom width
+ * <Dialog
+ *   open={showDialog}
+ *   onClose={handleClose}
+ *   maxWidth="sm"
+ *   showCloseButton={false}
+ *   content={({ close }) => <FormComponent onSubmit={close} />}
+ * />
+ */
 const Dialog = ({
   onClose,
   title,

package/src/components/Navigation/DialogButton/DialogButton.tsx

@@ -1,19 +1,88 @@
-import { DialogHeader, Dialog as ShadcnDialog, DialogContent as ShadcnDialogContent, DialogTitle as ShadcnDialogTitle } from '@/shadcn-components/DataDisplay/Dialog/Dialog';
+import {
+  DialogHeader,
+  Dialog as ShadcnDialog,
+  DialogContent as ShadcnDialogContent,
+  DialogTitle as ShadcnDialogTitle,
+} from '@/shadcn-components/DataDisplay/Dialog/Dialog';
 import { ReactNode, useState } from 'react';
 
+/**
+ * Available max-width sizes for the dialog
+ */
 type MaxWidthSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 
+/**
+ * Props for the DialogButton component
+ */
 export type DialogButtonProps = {
+  /** 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;
+  /** Function that renders the dialog content. Receives close callback to close the dialog */
   content: (props: { close: () => void }) => ReactNode;
+  /** Optional title displayed in the dialog header */
   title?: string | undefined;
+  /** Optional CSS class names for the dialog content element */
   className?: string;
+  /** Whether to show the close button in the dialog header. Defaults to true */
   showCloseButton?: boolean;
+  /** Max-width size class of the dialog. Defaults to 'lg' */
   maxWidth?: MaxWidthSize;
 };
 
+/**
+ * DialogButton component that combines a trigger element and a dialog in a single component.
+ *
+ * This is a convenient wrapper that manages its own open/close state and provides
+ * a clean API for rendering both the trigger (anchor) and the dialog content.
+ * It's useful when you want to bind a button or other trigger element with a dialog
+ * without managing state at the parent level.
+ *
+ * @component
+ * @param {DialogButtonProps} props - The component props
+ * @param {(props: { open: () => void }) => ReactNode} props.anchor - Render function for the trigger element
+ * @param {(props: { close: () => void }) => ReactNode} props.content - Render function for dialog content
+ * @param {string} [props.title] - Optional dialog title
+ * @param {() => void} [props.onDialogOpen] - Optional callback fired when the dialog opens
+ * @param {() => void} [props.onDialogClose] - Optional callback fired when the dialog closes
+ * @param {string} [props.className] - Optional CSS classes for the dialog content
+ * @param {boolean} [props.showCloseButton=true] - Whether to show the close button
+ * @param {MaxWidthSize} [props.maxWidth='lg'] - Maximum width of the dialog
+ *
+ * @returns {React.ReactElement} A fragment containing the anchor element and the Dialog
+ *
+ * @example
+ * // Button that opens a dialog with a form
+ * <DialogButton
+ *   anchor={({ open }) => <button onClick={open}>Edit Profile</button>}
+ *   title="Edit Profile"
+ *   content={({ close }) => (
+ *     <form onSubmit={(e) => { handleSubmit(e); close(); }}>
+ *       <input type="text" placeholder="Name" />
+ *       <button type="submit">Save</button>
+ *     </form>
+ *   )}
+ * />
+ *
+ * @example
+ * // With callbacks and custom styling
+ * <DialogButton
+ *   anchor={({ open }) => <IconButton icon={<EditIcon />} onClick={open} />}
+ *   title="Delete Item"
+ *   maxWidth="sm"
+ *   onDialogOpen={() => console.log('Dialog opened')}
+ *   onDialogClose={() => console.log('Dialog closed')}
+ *   content={({ close }) => (
+ *     <div>
+ *       <p>Are you sure?</p>
+ *       <button onClick={close}>Cancel</button>
+ *     </div>
+ *   )}
+ * />
+ */
 export const DialogButton = ({
   onDialogClose,
   onDialogOpen,

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,
@@ -66,7 +139,7 @@ export const DropdownMenu = ({
       <DropdownMenuContent
         align={align}
         side={side}
-        className={cn('min-w-[200px] z-[2000]', menuContentClassName)}
+        className={cn('min-w-[200px] ', menuContentClassName)}
         sideOffset={5}
         collisionPadding={8}
         // Force Radix to recalculate position

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',