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

package/src/components/DataDisplay/DataTable/components/TableView.tsx

@@ -87,11 +87,13 @@ const TableView = React.forwardRef<HTMLDivElement, TableViewProps>(
                       index === 0 && 'pl-4 rounded-tl-md',
                       index === headerGroup.headers.length - 1 &&
                         'rounded-tr-md',
+                      (header.column.columnDef.maxSize || header.column.columnDef.size) && 'overflow-hidden text-ellipsis whitespace-nowrap',
                       cellClassName,
                     )}
                     style={{
-                      width:
-                        header.getSize() !== 150 ? header.getSize() : undefined,
+                      width: header.column.columnDef.size ?? (header.getSize() !== 150 ? header.getSize() : undefined),
+                      maxWidth: header.column.columnDef.maxSize ?? undefined,
+                      minWidth: header.column.columnDef.minSize ?? undefined,
                     }}
                   >
                     {header.isPlaceholder ? null : (
@@ -135,10 +137,19 @@ const TableView = React.forwardRef<HTMLDivElement, TableViewProps>(
                   {/* Use visible header columns count to render correct number of skeleton cells */}
                   {table
                     .getHeaderGroups()[0]
-                    ?.headers.map((_: any, cellIndex: number) => (
+                    ?.headers.map((header: any, cellIndex: number) => (
                       <TableCell
                         key={`skeleton-cell-${rowIndex}-${cellIndex}`}
-                        className={cn(cellIndex === 0 && 'pl-4', cellClassName)}
+                        className={cn(
+                          cellIndex === 0 && 'pl-4',
+                          (header.column.columnDef.maxSize || header.column.columnDef.size) && 'overflow-hidden text-ellipsis whitespace-nowrap',
+                          cellClassName
+                        )}
+                        style={{
+                          width: header.column.columnDef.size ?? (header.getSize() !== 150 ? header.getSize() : undefined),
+                          maxWidth: header.column.columnDef.maxSize ?? undefined,
+                          minWidth: header.column.columnDef.minSize ?? undefined,
+                        }}
                       >
                         <Skeleton className="h-4 w-full" />
                       </TableCell>
@@ -162,7 +173,22 @@ const TableView = React.forwardRef<HTMLDivElement, TableViewProps>(
                     {row.getVisibleCells().map((cell: any, index: number) => (
                       <TableCell
                         key={cell.id}
-                        className={cn(index === 0 && 'pl-4', cellClassName)}
+                        className={cn(
+                          index === 0 && 'pl-4',
+                          (cell.column.columnDef.maxSize || cell.column.columnDef.size) && 'overflow-hidden text-ellipsis whitespace-nowrap',
+                          cellClassName
+                        )}
+                        style={{
+                          width: cell.column.columnDef.size ?? (cell.column.getSize() !== 150 ? cell.column.getSize() : undefined),
+                          maxWidth: cell.column.columnDef.maxSize ?? undefined,
+                          minWidth: cell.column.columnDef.minSize ?? undefined,
+                        }}
+                        onClick={(e) => {
+                          // Prevent row click when clicking on checkbox column
+                          if (cell.column.id === 'select') {
+                            e.stopPropagation();
+                          }
+                        }}
                       >
                         {flexRender(
                           cell.column.columnDef.cell,

package/src/components/DataDisplay/EmptyIllustration/EmptyIllustration.tsx

@@ -5,6 +5,37 @@ import {
   TypographyProps,
 } from '../../DataDisplay/Typography/Typography';
 
+/**
+ * Props for EmptyIllustration component
+ * @typedef {Object} EmptyIllustrationProps
+ * @property {string} message - Text message displayed below the empty illustration
+ * @property {TypographyProps} [messageProps] - Typography props for styling the message text
+ * @property {string} [containerClassName] - CSS class for the container div
+ */
+
+/**
+ * EmptyIllustration component for displaying empty state messaging
+ * Shows decorative empty state icon with customizable message
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {string} props.message - Text message to display below illustration
+ * @param {TypographyProps} [props.messageProps] - Typography styling props (variant, className, etc.)
+ * @param {string} [props.containerClassName] - Additional CSS classes for the container
+ * @returns {JSX.Element} Empty state illustration with message
+ *
+ * @example
+ * // Basic empty state
+ * <EmptyIllustration message="No data found" />
+ *
+ * @example
+ * // With custom styling
+ * <EmptyIllustration
+ *   message="No search results match your criteria"
+ *   messageProps={{ variant: "p", className: "text-gray-600" }}
+ *   containerClassName="py-12"
+ * />
+ */
 export const EmptyIllustration = ({
   message,
   messageProps,

package/src/components/DataDisplay/ReactJoyride/ReactJoyride.tsx

@@ -4,6 +4,20 @@ import { Button } from '../../Input/Button/Button';
 import { Typography } from '../Typography/Typography';
 import './CustomJoyRideStyles.css';
 
+/**
+ * Configuration for individual tour step
+ * @typedef {Object} JoyrideStep
+ * @property {string} target - CSS selector for the element to highlight
+ * @property {string | ReactNode} content - Description or content for the step
+ * @property {string} [title] - Title text for the step tooltip
+ * @property {'top' | 'bottom' | 'left' | 'right' | 'center' | 'auto'} [placement='auto'] - Tooltip placement relative to target
+ * @property {boolean} [disableBeacon] - Hide the beacon pulse animation
+ * @property {boolean} [hideCloseButton] - Hide close button in tooltip
+ * @property {boolean} [showProgress] - Display progress indicator
+ * @property {boolean} [showSkipButton] - Show skip button in tooltip
+ * @property {boolean} [spotlightClicks] - Allow clicking inside spotlight area
+ * @property {Record<string, any>} [styles] - Custom styles for tooltip
+ */
 interface JoyrideStep {
   target: string;
   content: string | ReactNode;
@@ -17,6 +31,56 @@ interface JoyrideStep {
   styles?: Record<string, any>;
 }
 
+/**
+ * ReactJoyride component for interactive product tours
+ * Provides guided walkthrough of UI elements with customizable steps
+ *
+ * @component
+ * @param {Object} props - Tour configuration
+ * @param {JoyrideStep[]} props.steps - Array of tour steps with targets, content, and placement
+ * @param {ReactNode} [props.children] - Application content to overlay tour on
+ * @param {string} props.tourName - Unique identifier for the tour (for state management)
+ * @returns {JSX.Element} Tour overlay component with tour trigger button
+ *
+ * @example
+ * // Basic product tour
+ * <ReactJoyRide
+ *   tourName="dashboard-tour"
+ *   steps={[
+ *     {
+ *       target: ".logo",
+ *       title: "Welcome",
+ *       content: "Welcome to our dashboard!",
+ *       placement: "bottom"
+ *     },
+ *     {
+ *       target: ".user-menu",
+ *       title: "Profile",
+ *       content: "Access your profile and settings here",
+ *       placement: "left"
+ *     }
+ *   ]}
+ * >
+ *   <Dashboard />
+ * </ReactJoyRide>
+ *
+ * @example
+ * // Advanced tour with custom placement and styling
+ * <ReactJoyRide
+ *   tourName="feature-tour"
+ *   steps={[
+ *     {
+ *       target: ".new-feature",
+ *       title: "New Feature",
+ *       content: "Check out this exciting new feature",
+ *       placement: "right",
+ *       disableBeacon: false
+ *     }
+ *   ]}
+ * >
+ *   <App />
+ * </ReactJoyRide>
+ */
 export const ReactJoyRide = ({
   steps,
   children,

package/src/components/DataDisplay/Separator/Separator.tsx

@@ -2,6 +2,14 @@ import * as React from 'react';
 
 import { Separator as ShadcnSaperator } from '@/shadcn-components/DataDisplay/Seperator/Seperator';
 
+/**
+ * Props for Separator component
+ * @typedef {Object} SeparatorProps
+ * @property {'horizontal' | 'vertical'} [orientation='horizontal'] - Direction of the separator
+ * @property {boolean} [decorative=true] - If true, renders as non-semantic element for styling
+ * @property {string} [className] - Optional CSS class for custom styling
+ * @extends {React.ComponentPropsWithoutRef<typeof ShadcnSaperator>}
+ */
 interface SeparatorProps
   extends React.ComponentPropsWithoutRef<typeof ShadcnSaperator> {
   orientation?: 'horizontal' | 'vertical';
@@ -9,6 +17,28 @@ interface SeparatorProps
   className?: string;
 }
 
+/**
+ * Separator component for dividing content sections
+ * Renders semantic or decorative separator line
+ *
+ * @component
+ * @param {SeparatorProps} props - Separator configuration
+ * @param {'horizontal' | 'vertical'} [props.orientation='horizontal'] - Direction of the dividing line
+ * @param {boolean} [props.decorative=true] - Whether separator is decorative (non-semantic)
+ * @param {string} [props.className] - Additional CSS classes for styling
+ * @param {...React.ComponentPropsWithoutRef<typeof ShadcnSaperator>} [props] - Additional separator props
+ * @returns {JSX.Element} Separator line element
+ * @example
+ * // Horizontal separator
+ * <Separator />
+ *
+ * @example
+ * // Vertical separator with custom styling
+ * <Separator
+ *   orientation="vertical"
+ *   className="h-12"
+ * />
+ */
 const Separator = React.forwardRef<
   React.ElementRef<typeof ShadcnSaperator>,
   SeparatorProps
@@ -29,4 +59,6 @@ const Separator = React.forwardRef<
   },
 );
 
+Separator.displayName = 'Separator';
+
 export { Separator };

package/src/components/DataDisplay/Skeleton/Skeleton.tsx

@@ -1,3 +1,23 @@
 import { Skeleton as SkeletonUI } from '@/shadcn-components/DataDisplay/Skeleton/Skeleton';
 
+/**
+ * Skeleton component for loading placeholder animations
+ * Re-export of shadcn Skeleton component for use in DataDisplay module
+ *
+ * @component
+ * @param {React.ComponentProps<typeof SkeletonUI>} props - Standard HTML div props with className for styling
+ * @param {string} [props.className] - CSS classes for sizing and styling the skeleton (e.g., "h-12 w-12 rounded-full")
+ * @returns {JSX.Element} Animated skeleton placeholder
+ *
+ * @example
+ * // Skeleton for profile picture
+ * <Skeleton className="h-12 w-12 rounded-full" />
+ *
+ * @example
+ * // Skeleton for content block
+ * <div className="space-y-2">
+ *   <Skeleton className="h-4 w-full" />
+ *   <Skeleton className="h-4 w-3/4" />
+ * </div>
+ */
 export { SkeletonUI as Skeleton };

package/src/components/DataDisplay/StatusCard/StatusCard.tsx

@@ -1,6 +1,14 @@
 import { cn } from '@/lib/utils';
 import { Typography, TypographyProps } from '../Typography/Typography';
 
+/**
+ * Props for StatusCard component
+ * @typedef {Object} StatusCardProps
+ * @property {'green' | 'red' | 'orange' | 'yellow' | 'blue' | 'pink'} color - Color theme for the status card
+ * @property {string} text - Text content to display in the status card
+ * @property {string} [className] - Optional additional CSS classes
+ * @property {TypographyProps['variant']} [typographyVariant='small'] - Typography variant for text styling
+ */
 export type StatusCardProps = {
   color: 'green' | 'red' | 'orange' | 'yellow' | 'blue' | 'pink';
   text: string;
@@ -8,6 +16,34 @@ export type StatusCardProps = {
   typographyVariant?: TypographyProps['variant'];
 };
 
+/**
+ * StatusCard component for displaying colored status badges
+ * Renders status indicators with color-coded backgrounds and text
+ *
+ * @component
+ * @param {StatusCardProps} props - StatusCard configuration
+ * @param {'green' | 'red' | 'orange' | 'yellow' | 'blue' | 'pink'} props.color - Status color (determines styling)
+ * @param {string} props.text - Status text to display
+ * @param {string} [props.className] - Additional CSS classes for custom styling
+ * @param {TypographyProps['variant']} [props.typographyVariant='small'] - Typography variant (h1-h6, p, small, etc.)
+ * @returns {JSX.Element} Colored status badge
+ *
+ * @example
+ * // Active status
+ * <StatusCard
+ *   color="green"
+ *   text="Active"
+ * />
+ *
+ * @example
+ * // Error status with custom styling
+ * <StatusCard
+ *   color="red"
+ *   text="Error"
+ *   typographyVariant="p"
+ *   className="font-bold"
+ * />
+ */
 export const StatusCard = ({
   color,
   text,

package/src/components/DataDisplay/Timeline/Timeline.tsx

@@ -2,18 +2,76 @@ import { cn } from '@/lib/utils';
 import { Info, MinusSquare, PlusSquare, SquareCheck } from 'lucide-react';
 import { ReactNode } from 'react';
 
+/**
+ * Props for individual timeline item
+ * @typedef {Object} TimelineItems
+ * @property {ReactNode} timelineContent - Main content of the timeline item
+ * @property {ReactNode} [timelineOppositeContent] - Optional opposite-side content (for alternate layouts)
+ * @property {'info' | 'success' | 'error' | 'warning'} [variant='info'] - Icon variant for the timeline marker
+ */
 export type TimelineItems = {
   timelineContent: ReactNode;
   timelineOppositeContent?: ReactNode;
   variant?: 'info' | 'success' | 'error' | 'warning';
 };
 
+/**
+ * Props for Timeline component
+ * @typedef {Object} TimelineProps
+ * @property {TimelineItems[]} timelineItems - Array of timeline items to display
+ * @property {'left' | 'right' | 'alternate' | 'alternate-reverse'} [position='right'] - Timeline layout position
+ * @property {string} [className] - Optional CSS class for the timeline container
+ */
 export type TimelineProps = {
   timelineItems: TimelineItems[];
   position?: 'left' | 'right' | 'alternate' | 'alternate-reverse';
   className?: string;
 };
 
+/**
+ * Timeline component for displaying chronological events or steps
+ * Supports multiple layout positions and icon variants per item
+ *
+ * @component
+ * @param {TimelineProps} props - Timeline configuration
+ * @param {TimelineItems[]} props.timelineItems - Array of timeline events with content and optional opposite content
+ * @param {'left' | 'right' | 'alternate' | 'alternate-reverse'} [props.position='right'] - Position of timeline connector
+ *   - 'left': All content on left side
+ *   - 'right': All content on right side
+ *   - 'alternate': Content alternates left/right starting with left
+ *   - 'alternate-reverse': Content alternates left/right starting with right
+ * @param {string} [props.className] - Additional CSS classes for the timeline wrapper
+ * @returns {JSX.Element} Timeline visualization with ordered events
+ *
+ * @example
+ * // Basic timeline (content on right)
+ * <Timeline
+ *   position="right"
+ *   timelineItems={[
+ *     { timelineContent: "Project started", variant: "success" },
+ *     { timelineContent: "First milestone", variant: "info" },
+ *     { timelineContent: "Completed", variant: "success" }
+ *   ]}
+ * />
+ *
+ * @example
+ * // Alternating timeline with opposite content
+ * <Timeline
+ *   position="alternate"
+ *   timelineItems={[
+ *     {
+ *       timelineContent: "Development",
+ *       timelineOppositeContent: "Jan 2024",
+ *       variant: "info"
+ *     },
+ *     {
+ *       timelineContent: "Testing",
+ *       timelineOppositeContent: "Feb 2024",
+ *       variant: "warning"
+ *     }
+ *   ]}
+ * />
+ */
 export const Timeline = ({
   timelineItems,
   position = 'right',

package/src/components/DataDisplay/Typography/Typography.tsx

@@ -4,6 +4,31 @@ import {
   typographyVariants,
 } from '@/shadcn-components/DataDisplay/Typography/Typography';
 
+/**
+ * Typography component wrapper around shadcn Typography
+ * Provides semantic text rendering with predefined variants
+ *
+ * @component
+ * @param {TypographyProps} props - Typography configuration
+ * @param {'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'blockquote' | 'code' | 'lead' | 'large' | 'small' | 'muted'} [props.variant='p'] - Predefined typography variant
+ * @param {React.ReactNode} props.children - Content to render with typography styling
+ * @param {...TypographyProps} [props] - Additional typography props (className, etc.)
+ * @returns {JSX.Element} Styled typography element
+ *
+ * @example
+ * // Heading
+ * <Typography variant="h1">Page Title</Typography>
+ *
+ * @example
+ * // Paragraph with custom class
+ * <Typography variant="p" className="text-gray-600">
+ *   This is a paragraph with custom styling
+ * </Typography>
+ *
+ * @example
+ * // Small text
+ * <Typography variant="small">Small disclaimer text</Typography>
+ */
 export const Typography = ({
   variant = 'p',
   children,

package/src/components/Feedback/Alert/Alert.tsx

@@ -2,6 +2,14 @@ import { AlertDescription, Alert as ShadcnAlert } from '@/shadcn-components/Feed
 import { AlertCircle, CheckCircle2, Info, TriangleAlert } from 'lucide-react';
 import { ReactNode } from 'react';
 
+/**
+ * Props for the Alert component.
+ * @typedef {Object} AlertProps
+ * @property {string | ReactNode} message - The message content to display in the alert
+ * @property {'success' | 'error' | 'info' | 'warning'} [severity] - The severity level of the alert that determines the icon displayed
+ * @property {'default' | 'destructive'} [variant] - The visual variant of the alert. Defaults to 'destructive' if severity is 'error'
+ * @property {string} [className] - Additional CSS classes to apply to the alert component
+ */
 export type AlertProps = {
   message: string | ReactNode;
   severity?: 'success' | 'error' | 'info' | 'warning';
@@ -9,6 +17,13 @@ export type AlertProps = {
   className?: string;
 };
 
+/**
+ * Returns an icon component based on the alert severity level.
+ * @param {AlertProps['severity']} severity - The severity level of the alert
+ * @returns {JSX.Element | null} The icon element corresponding to the severity, or null if no severity is provided
+ * @example
+ * const icon = getIcon('success'); // Returns CheckCircle2 icon
+ */
 const getIcon = (severity: AlertProps['severity']) => {
   switch (severity) {
     case 'success':
@@ -24,6 +39,29 @@ const getIcon = (severity: AlertProps['severity']) => {
   }
 };
 
+/**
+ * Alert component that displays a message with an optional severity-based icon.
+ * Renders a styled alert box with appropriate visual indicators based on severity level.
+ *
+ * @param {AlertProps} props - The component props
+ * @param {string | ReactNode} props.message - The message content to display
+ * @param {'success' | 'error' | 'info' | 'warning'} [props.severity] - The severity level determining icon and styling
+ * @param {'default' | 'destructive'} [props.variant] - The visual variant. Overrides default variant selection
+ * @param {string} [props.className] - Additional CSS classes to apply to the alert
+ * @returns {JSX.Element} The rendered alert component
+ *
+ * @example
+ * // Display a success alert
+ * <Alert message="Operation completed successfully" severity="success" />
+ *
+ * @example
+ * // Display an error alert with custom styling
+ * <Alert
+ *   message="An error occurred"
+ *   severity="error"
+ *   className="mt-4"
+ * />
+ */
 export const Alert = ({
   severity,
   message,

package/src/components/Feedback/Snackbar/Snackbar.tsx

@@ -9,13 +9,33 @@ import { useEffect } from 'react';
 import { Typography } from '../../DataDisplay/Typography/Typography';
 import { Button } from '../../Input/Button/Button';
 
+/**
+ * Severity levels for snackbar alerts.
+ * @typedef {'success' | 'info' | 'warning' | 'error'} Severity
+ */
 export type Severity = 'success' | 'info' | 'warning' | 'error';
 
+/**
+ * Position configuration for snackbar placement on screen.
+ * @typedef {Object} SnackbarPosition
+ * @property {'top' | 'bottom'} vertical - Vertical alignment of the snackbar
+ * @property {'left' | 'center' | 'right'} horizontal - Horizontal alignment of the snackbar
+ */
 export type SnackbarPosition = {
   vertical: 'top' | 'bottom';
   horizontal: 'left' | 'center' | 'right';
 };
 
+/**
+ * Props for the Snackbar component.
+ * @typedef {Object} SnackbarProps
+ * @property {Severity} severity - The severity level of the snackbar (success, info, warning, error)
+ * @property {string} message - The message text to display in the snackbar
+ * @property {boolean} open - Whether the snackbar is visible
+ * @property {Function} [onClose] - Callback function when snackbar is closed. Called with reason ('timeout' or 'clickaway')
+ * @property {SnackbarPosition} [anchorOrigin] - Position configuration for the snackbar placement. Defaults to {vertical: 'top', horizontal: 'center'}
+ * @property {number} [autoHideDuration] - Duration in milliseconds after which the snackbar auto-closes. If not provided, snackbar stays open until manually closed
+ */
 export type SnackbarProps = {
   severity: Severity;
   message: string;
@@ -25,6 +45,40 @@ export type SnackbarProps = {
   autoHideDuration?: number;
 };
 
+/**
+ * Snackbar component for displaying temporary notification messages.
+ * Displays a dismissible notification box with icon and message based on severity.
+ * Auto-hides after specified duration or when close button is clicked.
+ *
+ * @param {SnackbarProps} props - The component props
+ * @param {Severity} props.severity - The severity level of the notification
+ * @param {string} props.message - The message text to display
+ * @param {boolean} props.open - Whether the snackbar is visible
+ * @param {Function} [props.onClose] - Callback when snackbar is closed. Receives close reason as parameter
+ * @param {SnackbarPosition} [props.anchorOrigin] - Position configuration for placement (defaults to top center)
+ * @param {number} [props.autoHideDuration] - Duration in milliseconds before auto-closing (undefined = no auto-close)
+ * @returns {JSX.Element | null} The rendered snackbar component or null if not open
+ *
+ * @example
+ * // Display a success message that auto-hides after 3 seconds
+ * <Snackbar
+ *   severity="success"
+ *   message="Changes saved successfully"
+ *   open={true}
+ *   autoHideDuration={3000}
+ *   onClose={(reason) => console.log('Closed:', reason)}
+ * />
+ *
+ * @example
+ * // Position snackbar at bottom-right
+ * <Snackbar
+ *   severity="info"
+ *   message="New updates available"
+ *   open={isOpen}
+ *   anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+ *   onClose={() => setIsOpen(false)}
+ * />
+ */
 export const Snackbar = ({
   severity,
   message,

package/src/components/Feedback/Spinner/Spinner.tsx

@@ -1,3 +1,18 @@
+/**
+ * Spinner component that displays an animated loading indicator.
+ * Renders a dual-colored rotating spinner with smooth continuous animation.
+ * No props required - it's a simple stateless component.
+ *
+ * @returns {JSX.Element} The rendered spinner component
+ *
+ * @example
+ * // Display a loading spinner
+ * <Spinner />
+ *
+ * @example
+ * // Use in a loading state
+ * {isLoading ? <Spinner /> : <div>Content loaded</div>}
+ */
 export const Spinner = () => {
   return (
     <div className="relative h-10 w-10 scale-[0.4] rounded-full [animation:rotate_1s_linear_infinite] before:absolute before:inset-0 before:box-border before:rounded-full before:border-[5px] before:border-[#7D60D9] before:content-[''] before:[animation:prixClipFix_1.5s_linear_infinite] after:absolute after:inset-0 after:box-border after:rounded-full after:border-[5px] after:border-[#FF3D00] after:content-[''] after:[animation:prixClipFix_1.5s_linear_infinite] after:[transform:rotate3d(90,90,0,180deg)]" />

package/src/components/Feedback/Tooltip/Tooltip.tsx

@@ -1,7 +1,23 @@
-import { ReactNode } from 'react';
+import { ReactNode, useEffect, useRef, useState } from 'react';
 
-import { Tooltip as ShadcnTooltip, TooltipContent, TooltipTrigger } from '@/shadcn-components/Feedback/Tooltip/Tooltip';
+import {
+  Tooltip as ShadcnTooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@/shadcn-components/Feedback/Tooltip/Tooltip';
 
+/**
+ * Props for the Tooltip component.
+ * @typedef {Object} TooltipProps
+ * @property {ReactNode} children - The element that triggers the tooltip on hover
+ * @property {ReactNode} title - The tooltip content to display
+ * @property {'top' | 'right' | 'bottom' | 'left'} [placement] - The direction to place the tooltip relative to the trigger element. Defaults to 'right'
+ * @property {boolean} [arrow] - Whether to display an arrow pointing to the trigger element. Currently not implemented in UI
+ * @property {boolean} [open] - Controlled open state of the tooltip
+ * @property {boolean} [defaultOpen] - Initial open state if tooltip is uncontrolled
+ * @property {Function} [onOpenChange] - Callback fired when tooltip open state changes
+ * @property {number} [delayDuration] - Delay in milliseconds before tooltip appears on hover
+ */
 export type TooltipProps = {
   children: ReactNode;
   title: ReactNode;
@@ -13,6 +29,48 @@ export type TooltipProps = {
   delayDuration?: number;
 };
 
+/**
+ * Tooltip component that displays contextual information on hover.
+ * Wraps the shadcn tooltip component with enhanced positioning and configuration options.
+ * Supports both controlled and uncontrolled modes for tooltip visibility.
+ *
+ * @param {TooltipProps} props - The component props
+ * @param {ReactNode} props.children - The element that triggers the tooltip
+ * @param {ReactNode} props.title - The tooltip content to display
+ * @param {'top' | 'right' | 'bottom' | 'left'} [props.placement] - Tooltip placement direction (defaults to 'right')
+ * @param {boolean} [props.arrow] - Arrow display option (not currently implemented)
+ * @param {boolean} [props.open] - Controlled open state
+ * @param {boolean} [props.defaultOpen] - Initial open state for uncontrolled mode
+ * @param {Function} [props.onOpenChange] - Callback when open state changes
+ * @param {number} [props.delayDuration] - Delay before showing tooltip in milliseconds
+ * @returns {JSX.Element} The rendered tooltip component
+ *
+ * @example
+ * // Basic tooltip with default placement
+ * <Tooltip title="This is a helpful tip">
+ *   <button>Hover me</button>
+ * </Tooltip>
+ *
+ * @example
+ * // Tooltip positioned at bottom with delay
+ * <Tooltip
+ *   title="Additional information"
+ *   placement="bottom"
+ *   delayDuration={500}
+ * >
+ *   <span>Information icon</span>
+ * </Tooltip>
+ *
+ * @example
+ * // Controlled tooltip state
+ * <Tooltip
+ *   title="Controlled tooltip"
+ *   open={isTooltipOpen}
+ *   onOpenChange={setIsTooltipOpen}
+ * >
+ *   <button>Toggle</button>
+ * </Tooltip>
+ */
 export const Tooltip = ({
   children,
   title,
@@ -22,6 +80,14 @@ export const Tooltip = ({
   onOpenChange,
   delayDuration,
 }: TooltipProps) => {
+  const wrapperRef = useRef<HTMLSpanElement>(null);
+
+  // Force re-render on mount to ensure positioning works
+  const [, forceUpdate] = useState({});
+  useEffect(() => {
+    forceUpdate({});
+  }, []);
+
   return (
     <ShadcnTooltip
       open={open}
@@ -29,7 +95,9 @@ export const Tooltip = ({
       onOpenChange={onOpenChange}
       delayDuration={delayDuration}
     >
-      <TooltipTrigger asChild>{children}</TooltipTrigger>
+      <span ref={wrapperRef}>
+        <TooltipTrigger asChild>{children}</TooltipTrigger>
+      </span>
       <TooltipContent side={placement}>{title}</TooltipContent>
     </ShadcnTooltip>
   );