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

package/src/components/Layout/PageContent/PageContent.tsx

@@ -5,9 +5,29 @@ import { ReactNode } from 'react';
 interface PageContentProps {
   children: ReactNode;
   className?: string;
+  styles?: React.CSSProperties;
 }
 
-const PageContent = ({ children, className }: PageContentProps) => {
+/**
+ * PageContent Component
+ *
+ * Main content area wrapper that provides responsive padding, scrolling behavior, and custom scrollbar styling.
+ * Automatically adjusts height based on screen size to account for page header and other UI elements.
+ * Includes thin scrollbar styling using Tailwind's scrollbar utilities.
+ *
+ * @param {React.ReactNode} children - Content to render inside the page content area
+ * @param {string} [className=''] - Additional CSS classes to apply to the container
+ *
+ * @returns {React.ReactElement} A scrollable content container with responsive height and styling
+ *
+ * @example
+ * ```tsx
+ * <PageContent className="bg-white">
+ *   <YourPageContent />
+ * </PageContent>
+ * ```
+ */
+const PageContent = ({ children, className, styles }: PageContentProps) => {
   const isSmallScreen = useMediaQuery('(max-width: 768px)');
 
   return (
@@ -17,9 +37,9 @@ const PageContent = ({ children, className }: PageContentProps) => {
         className,
       )}
       style={{
-        height: isSmallScreen ? 'calc(100vh - 101px)' : `calc(100vh - 90px)`,
-        maxHeight: isSmallScreen ? 'calc(100vh - 101px)' : `calc(100vh - 90px)`,
+        height: isSmallScreen ? 'calc(100vh - 101px)' : `calc(100vh - 80px)`,
         overflowY: 'auto',
+        ...styles,
       }}
     >
       {children}

package/src/components/Layout/PageHeader/PageHeader.tsx

@@ -9,7 +9,10 @@ import { cn } from '@/lib/utils';
 import { EllipsisVertical, Funnel, Plus } from 'lucide-react';
 import { cloneElement, ReactElement, ReactNode } from 'react';
 import { useDispatch } from 'react-redux';
-import { setFilterByNameForUniqueId } from '../../../redux/slices/pageHeaderSlice';
+import {
+  resetStateForUniqueId,
+  setFilterByNameForUniqueId,
+} from '../../../redux/slices/pageHeaderSlice';
 import { SearchBarProps } from '../../Input/SearchBar/SearchBar';
 import { Breadcrumbs } from '../../Navigation/Breadcrumbs/Breadcrumbs';
 import { PageHeaderSearchBar } from './components/SearchBar';
@@ -33,6 +36,52 @@ interface PageHeaderProps {
   };
 }
 
+/**
+ * PageHeader Component
+ *
+ * Header component for page content that displays breadcrumbs and action bar with search,
+ * filter, add button, and custom action menus. Supports Redux integration for maintaining
+ * search and filter state across re-renders. Responsive design with mobile optimization.
+ *
+ * @param {string} [uniqueId] - Optional unique identifier for Redux state management of this header
+ * @param {number} pathTrimCount - Number of path segments to trim from breadcrumb
+ * @param {React.ReactElement} [breadcrumbAction] - Optional element to display next to breadcrumbs
+ * @param {SearchBarProps & { uniqueId?: string; searchText?: string }} [searchBarProps] - Configuration for search bar including placeholder
+ * @param {{
+ *   label?: string;
+ *   startIcon?: React.ReactNode;
+ *   components: React.ReactElement[];
+ * }} [filterButtonProps] - Configuration for filter dropdown with filter components
+ * @param {{
+ *   label?: string;
+ *   onClick: () => void;
+ * }} [addButtonProps] - Configuration for add/create button
+ * @param {{
+ *   menu: React.ReactNode[] | ((props: { close: () => void }) => React.ReactNode[]);
+ * }} [actionProps] - Configuration for additional action menu
+ *
+ * @returns {React.ReactElement} A responsive header with breadcrumbs and action controls
+ *
+ * @example
+ * ```tsx
+ * <PageHeader
+ *   uniqueId="users-list"
+ *   pathTrimCount={1}
+ *   searchBarProps={{
+ *     placeholder: "Search users...",
+ *     uniqueId: "users-list"
+ *   }}
+ *   filterButtonProps={{
+ *     label: "Filters",
+ *     components: [<StatusFilter />, <RoleFilter />]
+ *   }}
+ *   addButtonProps={{
+ *     label: "Add User",
+ *     onClick: handleAddUser
+ *   }}
+ * />
+ * ```
+ */
 const PageHeader = ({
   uniqueId,
   pathTrimCount,
@@ -98,12 +147,24 @@ const PageHeader = ({
               useMenuSlot={true}
               menuSlot={() => (
                 <div className="flex flex-col gap-2 p-1 w-80">
-                  <Typography
-                    variant={'lead'}
-                    className="flex gap-1 items-center p-1 pb-0 text-sm"
-                  >
-                    <Funnel size={16} /> Advanced Filters
-                  </Typography>
+                  <div className="flex justify-between">
+                    <Typography
+                      variant={'lead'}
+                      className="flex gap-1 items-center p-1 pb-0 text-sm"
+                    >
+                      <Funnel size={16} /> Advanced Filters
+                    </Typography>
+                    <Button
+                      variant={'link'}
+                      size={'sm'}
+                      className="text-destructive hover:no-underline"
+                      onClick={() =>
+                        dispatch(resetStateForUniqueId({ uniqueId }))
+                      }
+                    >
+                      Clear
+                    </Button>
+                  </div>
                   <Separator />
                   {filterButtonProps.components.map((component, index) => (
                     <div key={index} className="w-full ">

package/src/components/Layout/PageHeader/components/SearchBar.tsx

@@ -3,6 +3,28 @@ import { setSearchForUniqueId } from '../../../../redux/slices/pageHeaderSlice';
 import { RootState } from '../../../../redux/store';
 import { SearchBar, type SearchBarProps } from '../../../export';
 
+/**
+ * PageHeaderSearchBar Component
+ *
+ * Redux-integrated search bar component that automatically manages search state in Redux store.
+ * The search value is persisted and retrieved using the provided uniqueId, allowing search state
+ * to survive component re-renders and navigation.
+ *
+ * @param {string} [uniqueId='default'] - Unique identifier for Redux state persistence (should match PageHeader uniqueId)
+ * @param {string} [searchText='Search'] - Placeholder text for the search input
+ * @param {SearchBarProps} props - Additional SearchBar component props
+ *
+ * @returns {React.ReactElement} A controlled search bar connected to Redux store
+ *
+ * @example
+ * ```tsx
+ * <PageHeaderSearchBar
+ *   uniqueId="users-list"
+ *   searchText="Search users..."
+ *   onSearch={handleSearch}
+ * />
+ * ```
+ */
 export const PageHeaderSearchBar = ({
   uniqueId = 'default',
   searchText = 'Search',

package/src/components/Layout/UserBox/UserBox.tsx

@@ -5,6 +5,46 @@ import { Typography } from '../../DataDisplay/Typography/Typography';
 import { DropdownMenu } from '../../Navigation/DropDownMenu/DropDownMenu';
 import { DropdownMenuItem } from '../../Navigation/DropDownMenu/DropdownMenuItem';
 
+/**
+ * UserBox Component
+ *
+ * User profile information and dropdown menu component with customizable sections.
+ * Displays user avatar with fallback to initials, supports optional designation,
+ * active devices toggle, custom actions, and logout. Avatar click can trigger
+ * custom handler or open the dropdown menu.
+ *
+ * @param {string} fullName - User's full name (required, used for avatar initials and display)
+ * @param {string} [designation=''] - User's job designation or title (optional)
+ * @param {any[]} [institutionsData] - Optional array of institution data (for future use)
+ * @param {React.ReactNode[]} actions - Array of custom menu item elements to include in dropdown
+ * @param {() => void} [onLogoutClick] - Callback handler when logout menu item is clicked
+ * @param {string} [profileUrl] - URL to user's profile image (uses initials fallback if not provided)
+ * @param {React.ReactNode} [changePassword] - Optional change password component/element
+ * @param {any} [profileSx={}] - Custom styles/className to apply to avatar element
+ * @param {boolean} [avatar=true] - Whether to show the avatar in the account menu section
+ * @param {boolean} [navigationIcon=true] - Whether to show the navigation icon next to account info
+ * @param {boolean} [showActiveDevices=true] - Whether to show the "Active Devices" menu item
+ * @param {() => void} [onAccountClick] - Callback handler when account section is clicked
+ * @param {() => void} [onActiveDevicesClick] - Callback handler when active devices item is clicked
+ * @param {() => void} [onChangeInstitutionClick] - Callback handler for changing institution (future use)
+ * @param {() => void} [onAvatarClick] - Callback handler when avatar is clicked (prevents menu opening if provided)
+ *
+ * @returns {React.ReactElement} A user profile dropdown menu component
+ *
+ * @example
+ * ```tsx
+ * <UserBox
+ *   fullName="John Doe"
+ *   designation="Software Engineer"
+ *   profileUrl="/avatars/john.jpg"
+ *   onLogoutClick={handleLogout}
+ *   onAccountClick={navigateToSettings}
+ *   onActiveDevicesClick={showActiveDevices}
+ *   actions={[<CustomMenuAction1 />, <CustomMenuAction2 />]}
+ *   showActiveDevices={true}
+ * />
+ * ```
+ */
 export default function UserBox({
   fullName,
   onLogoutClick,

package/src/components/Navigation/Breadcrumbs/Breadcrumbs.tsx

@@ -22,12 +22,45 @@ import { ReactElement } from 'react';
 import { getBreadcrumbsCharacter } from '../../../utils/export';
 import { MenuToggleButton } from '../../Layout/AppLayout/components/MenuToggleButton';
 
+/**
+ * Props for the Breadcrumbs component
+ */
 export type BreadcrumbsProps = {
+  /** Number of path segments to trim from the beginning of the current URL path */
   pathTrimCount: number;
+  /** Optional CSS class names for the container element */
   containerClassName?: string;
+  /** Optional React element to render as an action button/component on the right side */
   action?: ReactElement;
 };
 
+/**
+ * Breadcrumbs component that displays a navigation breadcrumb trail based on the current URL path.
+ *
+ * Automatically generates breadcrumb items from the URL pathname and displays them with navigation links.
+ * When there are more than 2 breadcrumb items, it shows the first item, a dropdown menu with middle items,
+ * and the last item to save space.
+ *
+ * @component
+ * @param {BreadcrumbsProps} props - The component props
+ * @param {number} props.pathTrimCount - Number of path segments to trim from the beginning of the URL path
+ * @param {string} [props.containerClassName] - Optional CSS class names to apply to the container div
+ * @param {ReactElement} [props.action] - Optional React element displayed on the right side of the breadcrumb
+ *
+ * @returns {React.ReactElement} A div containing the breadcrumb navigation component with a menu toggle button and breadcrumb list
+ *
+ * @example
+ * // Basic usage
+ * <Breadcrumbs pathTrimCount={1} />
+ *
+ * @example
+ * // With custom action button
+ * <Breadcrumbs
+ *   pathTrimCount={2}
+ *   action={<button>Export</button>}
+ *   containerClassName="bg-gray-50 border-b"
+ * />
+ */
 export const Breadcrumbs = ({
   pathTrimCount,
   containerClassName,
@@ -58,11 +91,22 @@ export const Breadcrumbs = ({
       return breadcrumbItems.map((item, index) => (
         <BreadcrumbItem key={index}>
           {item.isLast ? (
-            <BreadcrumbPage>{item.label}</BreadcrumbPage>
+            <BreadcrumbPage>
+              <Typography variant={'small'} className="text-semibold">
+                {item.label}
+              </Typography>
+            </BreadcrumbPage>
           ) : (
             <>
               <BreadcrumbLink asChild>
-                <Link to={item.path}>{item.label}</Link>
+                <Link to={item.path}>
+                  <Typography
+                    variant={'small'}
+                    className="text-semibold text-muted-foreground"
+                  >
+                    {item.label}
+                  </Typography>
+                </Link>
               </BreadcrumbLink>
               <BreadcrumbSeparator />
             </>
@@ -80,7 +124,10 @@ export const Breadcrumbs = ({
           <BreadcrumbItem>
             <BreadcrumbLink asChild>
               <Link to={firstItem.path}>
-                <Typography variant={'small'} className="text-muted-foreground">
+                <Typography
+                  variant={'small'}
+                  className="text-semibold text-muted-foreground"
+                >
                   {firstItem.label}
                 </Typography>
               </Link>
@@ -104,7 +151,9 @@ export const Breadcrumbs = ({
           </BreadcrumbItem>
           <BreadcrumbItem>
             <BreadcrumbPage>
-              <Typography variant={'small'}>{lastItem.label}</Typography>
+              <Typography variant={'small'} className="text-semibold">
+                {lastItem.label}
+              </Typography>
             </BreadcrumbPage>
           </BreadcrumbItem>
         </>

package/src/components/Navigation/Calendar/Calendar.tsx

@@ -8,6 +8,69 @@ import { cn } from '../../../lib/utils';
 import './Calendar.css';
 import { CalendarProps } from './types';
 
+/**
+ * Calendar component that provides a fully-featured calendar interface with FullCalendar integration.
+ *
+ * This component displays an interactive calendar with support for events, drag-and-drop,
+ * resizing, and various view modes (month, week, day). It offers extensive customization options
+ * for appearance, behavior, and event handling.
+ *
+ * @component
+ * @param {CalendarProps} props - The component props
+ * @param {CalendarEvent[]} [props.events] - Array of calendar events to display. Defaults to empty array
+ * @param {(eventInfo: CalendarEventClickInfo) => void} [props.onEventClick] - Callback fired when an event is clicked
+ * @param {(dropInfo: CalendarEventDropInfo) => void} [props.onEventDrop] - Callback fired when an event is drag-dropped
+ * @param {(resizeInfo: CalendarEventResizeInfo) => void} [props.onEventResize] - Callback fired when an event is resized
+ * @param {(dateInfo: CalendarDateClickInfo) => void} [props.onDateClick] - Callback fired when a date is clicked
+ * @param {(selectInfo: CalendarDateSelectInfo) => void} [props.onDateSelect] - Callback fired when a date range is selected
+ * @param {(events: EventApi[]) => void} [props.onEventsSet] - Callback fired when the list of events changes
+ * @param {CalendarView} [props.initialView='dayGridMonth'] - Initial view mode to display (dayGridMonth, timeGridWeek, timeGridDay, listWeek)
+ * @param {CalendarView[]} [props.views] - Array of available view modes to show in view switcher
+ * @param {CalendarHeaderToolbar | boolean} [props.headerToolbar] - Header toolbar configuration object or false to hide it
+ * @param {boolean} [props.editable=false] - Whether events can be dragged/resized to modify dates
+ * @param {boolean} [props.selectable=false] - Whether users can select date ranges by clicking and dragging
+ * @param {boolean} [props.selectMirror=true] - Whether to show a visual mirror while selecting date ranges
+ * @param {boolean} [props.eventResizable=false] - Whether events can be resized by dragging their edges
+ * @param {boolean} [props.eventDraggable=false] - Whether events can be dragged to change their dates
+ * @param {boolean | number} [props.dayMaxEvents=true] - Maximum number of events to show per day (true for auto, false for unlimited)
+ * @param {string | number} [props.height='auto'] - Height of the calendar (CSS string or number in pixels)
+ * @param {number} [props.aspectRatio] - Aspect ratio for the calendar dimensions
+ * @param {React.HTMLAttributes<HTMLDivElement>} [props.containerProps] - Additional HTML attributes for the container div
+ * @param {string} [props.locale='en'] - Locale/language code for calendar text (e.g., 'en', 'es', 'fr')
+ * @param {string} [props.timezone='local'] - Timezone for displaying dates ('local' or standard timezone identifier)
+ * @param {0 | 1 | 2 | 3 | 4 | 5 | 6} [props.firstDayOfWeek=0] - First day of the week (0=Sunday, 1=Monday, etc.)
+ * @param {(eventInfo: any) => React.ReactNode} [props.eventContent] - Custom render function for event content
+ * @param {(dayInfo: any) => React.ReactNode} [props.dayCellContent] - Custom render function for day cell content
+ * @param {boolean} [props.showNavigationButtons=true] - Whether to show previous/next navigation buttons
+ * @param {boolean} [props.showViewSwitcher=true] - Whether to show view mode selector buttons
+ * @param {boolean} [props.showToday=true] - Whether to show the "today" button
+ * @param {boolean} [props.weekends=true] - Whether to display weekend days
+ * @param {any} [props.businessHours] - Business hours configuration
+ * @param {any} [props.eventConstraint] - Constraint rules for event dragging
+ * @param {any} [props.selectConstraint] - Constraint rules for date selection
+ *
+ * @returns {React.ReactElement} A div container with the FullCalendar component
+ *
+ * @example
+ * // Basic calendar with events
+ * <Calendar
+ *   events={[
+ *     { id: '1', title: 'Meeting', start: '2024-01-15' }
+ *   ]}
+ *   onEventClick={(info) => console.log(info.event.title)}
+ * />
+ *
+ * @example
+ * // Editable calendar with custom height
+ * <Calendar
+ *   events={events}
+ *   editable={true}
+ *   eventDraggable={true}
+ *   eventResizable={true}
+ *   height={600}
+ *   onEventDrop={(info) => updateEventDate(info)}
+ * />
+ */
 export const Calendar: React.FC<CalendarProps> = ({
   events = [],
 

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,78 @@
-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 } 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,
@@ -45,7 +105,7 @@ const Dialog = ({
         showCloseButton={showCloseButton}
       >
         {title && (
-          <DialogHeader className="pl-4 pt-4">
+          <DialogHeader className="pl-4 py-4 border-b">
             <ShadcnDialogTitle>{title}</ShadcnDialogTitle>
           </DialogHeader>
         )}

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

@@ -6,19 +6,83 @@ import {
 } 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,