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

package/src/components/Input/DateTimePicker/components/DateTimePickerInput.tsx

@@ -0,0 +1,297 @@
+import { cn } from '@/lib/utils';
+import { Calendar } from '@/shadcn-components/Input/Calendar/Calendar';
+import { Input } from '@/shadcn-components/Input/Input/Input';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/shadcn-components/Input/Popover/Popover';
+import { format as DateFnsFormat } from 'date-fns';
+import { CalendarDays } from 'lucide-react';
+import { cloneElement, useEffect, useMemo, useRef, useState } from 'react';
+import { Typography } from '../../../DataDisplay/Typography/Typography';
+import { Button } from '../../Button/Button';
+import { LabelWrapper } from '../../LabelWrapper/LabelWrapper';
+import { DateTimePickerProps } from '../DateTimePicker';
+
+export const DateTimePickerInput = ({
+  label,
+  name,
+  value,
+  onChange,
+  required = false,
+  format = 'dd MMM yyyy hh:mm a',
+  views = ['year', 'month', 'day', 'hours', 'minutes', 'seconds'],
+  helperText,
+  placeholder = 'Pick a date and time',
+  shortcutsItems = [],
+  openPickerIcon: Icon = <CalendarDays />,
+  containerProps,
+  error,
+  disabled = false,
+  minDate,
+  maxDate,
+  disablePast = false,
+  disableFuture = false,
+  shouldDisableDate,
+  shouldDisableMonth,
+  shouldDisableYear,
+  className,
+  onOpen,
+  onClose,
+  fullWidth,
+  type,
+  ...rest
+}: DateTimePickerProps) => {
+  const [open, setOpen] = useState(false);
+  const [timeValue, setTimeValue] = useState<string>('');
+  const wrapperRef = useRef<HTMLSpanElement>(null);
+
+  // Determine view configurations based on views prop
+  const viewConfig = useMemo(() => {
+    const hasTime =
+      views.includes('hours') ||
+      views.includes('minutes') ||
+      views.includes('seconds');
+    const hasDate =
+      views.includes('day') ||
+      views.includes('month') ||
+      views.includes('year');
+
+    return {
+      showTime: hasTime,
+      showDate: hasDate,
+    };
+  }, [views]);
+
+  // Update time value when value changes
+  useEffect(() => {
+    if (value && viewConfig.showTime) {
+      const hours = value.getHours(),
+        minutes = value.getMinutes(),
+        seconds = value.getSeconds(),
+        timeStr = `${String(hours).padStart(2, '0')}:${String(minutes).padStart(
+          2,
+          '0',
+        )}:${String(seconds).padStart(2, '0')}`;
+      setTimeValue(timeStr);
+    }
+  }, [value, viewConfig.showTime]);
+
+  const formatDateTimeString = (date: Date | undefined) => {
+    if (!date) return '';
+
+    try {
+      return DateFnsFormat(date, format);
+    } catch {
+      return DateFnsFormat(date, 'dd/MM/yyyy hh:mm a');
+    }
+  };
+
+  const handleOpenChange = (newOpen: boolean) => {
+    setOpen(newOpen);
+    if (newOpen && onOpen) {
+      onOpen();
+    } else if (!newOpen && onClose) {
+      onClose();
+    }
+  };
+
+  const handleDateSelect = (date: Date | undefined) => {
+    if (date) {
+      const newDateTime = new Date(date);
+      // Preserve existing time if we have one
+      if (value) {
+        newDateTime.setHours(
+          value.getHours(),
+          value.getMinutes(),
+          value.getSeconds(),
+        );
+      }
+      onChange?.(newDateTime);
+    } else {
+      onChange?.(undefined);
+    }
+  };
+
+  const handleTimeChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const timeStr = e.target.value;
+    setTimeValue(timeStr);
+
+    if (timeStr) {
+      const [hours, minutes, seconds] = timeStr.split(':').map(Number);
+      const newDateTime = value ? new Date(value) : new Date();
+      newDateTime.setHours(hours || 0, minutes || 0, seconds || 0);
+      onChange?.(newDateTime);
+    }
+  };
+
+  const [, forceUpdate] = useState({});
+  useEffect(() => {
+    forceUpdate({});
+  }, []);
+
+  // If only time selection (no date), render native time input directly
+  if (viewConfig.showTime && !viewConfig.showDate) {
+    return (
+      <LabelWrapper
+        label={label}
+        required={required}
+        name={name}
+        containerProps={containerProps}
+      >
+        <Input
+          type="time"
+          step="1"
+          value={timeValue}
+          onChange={handleTimeChange}
+          disabled={disabled}
+          placeholder={placeholder}
+          className={cn(
+            'bg-input-background border-none text-muted-foreground',
+            error && 'border-destructive',
+            className,
+          )}
+          {...rest}
+        />
+
+        {/* Helper Text / Error */}
+        {(helperText || error) && (
+          <Typography
+            variant="small"
+            className={cn('ml-1 mt-1', error && 'text-destructive')}
+          >
+            {typeof error === 'string' ? error : error?.message || helperText}
+          </Typography>
+        )}
+      </LabelWrapper>
+    );
+  }
+
+  return (
+    <LabelWrapper
+      label={label}
+      required={required}
+      name={name}
+      containerProps={{
+        ...(fullWidth && { style: { width: '100%' } }),
+        ...containerProps,
+      }}
+    >
+      <Popover open={open} onOpenChange={handleOpenChange}>
+        <PopoverTrigger asChild>
+          <span
+            ref={wrapperRef}
+            style={{ display: fullWidth ? 'block' : 'inline-block' }}
+          >
+            <Button
+              variant="input"
+              className={cn(
+                'w-full justify-between text-left font-normal',
+                !value && 'text-muted-foreground',
+                error && 'border-destructive',
+                fullWidth ? 'w-full' : 'w-auto',
+                className,
+              )}
+              disabled={disabled}
+              {...rest}
+            >
+              <span>
+                {value ? formatDateTimeString(value) : placeholder}
+              </span>
+              {Icon &&
+                cloneElement(Icon as React.ReactElement, {
+                  className: 'ml-2 h-4 w-4 ',
+                })}
+            </Button>
+          </span>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align="start">
+          <div className="flex flex-col">
+            {/* Shortcuts */}
+            {shortcutsItems.length > 0 && (
+              <div className="border-b p-2">
+                <div className="flex flex-wrap gap-1">
+                  {shortcutsItems.map((shortcut, index) => (
+                    <Button
+                      key={index}
+                      variant="outline"
+                      size="sm"
+                      onClick={() => {
+                        const newDate = shortcut.getValue();
+                        onChange?.(newDate);
+                        setOpen(false);
+                      }}
+                    >
+                      {shortcut.label}
+                    </Button>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {/* Calendar */}
+            {viewConfig.showDate && (
+              <Calendar
+                mode="single"
+                selected={value}
+                onSelect={handleDateSelect}
+                disabled={(date) => {
+                  const today = new Date();
+                  today.setHours(0, 0, 0, 0);
+                  const compareDate = new Date(date);
+                  compareDate.setHours(0, 0, 0, 0);
+
+                  if (minDate) {
+                    const min = new Date(minDate);
+                    min.setHours(0, 0, 0, 0);
+                    if (compareDate < min) return true;
+                  }
+                  if (maxDate) {
+                    const max = new Date(maxDate);
+                    max.setHours(0, 0, 0, 0);
+                    if (compareDate > max) return true;
+                  }
+
+                  if (disablePast && compareDate < today) return true;
+                  if (disableFuture && compareDate > today) return true;
+                  if (shouldDisableDate && shouldDisableDate(date)) return true;
+                  if (shouldDisableMonth && shouldDisableMonth(date))
+                    return true;
+                  if (shouldDisableYear && shouldDisableYear(date)) return true;
+
+                  return false;
+                }}
+                captionLayout={'dropdown'}
+                defaultMonth={value}
+              />
+            )}
+
+            {/* Time Picker */}
+            {viewConfig.showTime && (
+              <div className={cn('p-3', viewConfig.showDate && 'border-t')}>
+                <Input
+                  type="time"
+                  step="1"
+                  value={timeValue}
+                  onChange={handleTimeChange}
+                  className="bg-input-background border-none text-muted-foreground appearance-none [&::-webkit-calendar-picker-indicator]:hidden [&::-webkit-calendar-picker-indicator]:appearance-none"
+                />
+              </div>
+            )}
+          </div>
+        </PopoverContent>
+      </Popover>
+
+      {/* Helper Text / Error */}
+      {(helperText || error) && (
+        <Typography
+          variant="small"
+          className={cn('ml-1 mt-1', error && 'text-destructive')}
+        >
+          {typeof error === 'string' ? error : error?.message || helperText}
+        </Typography>
+      )}
+    </LabelWrapper>
+  );
+};

package/src/components/Input/FileUpload/FileUpload.tsx

@@ -26,6 +26,47 @@ export type FileUploadProps = {
   required?: boolean;
 };
 
+/**
+ * FileUpload component for file selection and management
+ *
+ * A comprehensive file upload component with drag-and-drop support, file validation,
+ * preview capabilities, and file management features.
+ *
+ * @component
+ * @param {FileUploadProps} props - The file upload properties
+ * @param {string} props.label - Label text for the upload field
+ * @param {string} props.name - Name attribute for the input element
+ * @param {File[]} [props.files=[]] - Array of currently selected files
+ * @param {(files: File[]) => void} [props.onChange] - Callback fired when files are selected
+ * @param {(index: number) => void} [props.handleRemove] - Callback to remove a file by index
+ * @param {'image/*' | '.pdf' | '.docx' | '.txt' | '*'} [props.accept='*'] - File type filter
+ * @param {(file: File) => void} [props.onInvalidFile] - Callback fired when an invalid file is selected
+ * @param {string} [props.inputText] - Custom text for the upload prompt
+ * @param {boolean} [props.multiple=true] - Whether multiple files can be selected
+ * @param {boolean} [props.disabled=false] - Whether the upload is disabled
+ * @param {boolean} [props.hideDeleteButton=false] - Whether to hide delete buttons on files
+ * @param {boolean} [props.hideInput=false] - Whether to hide the file input area
+ * @param {string} [props.errorText] - Error message to display
+ * @param {string} [props.className] - Additional CSS classes for the upload area
+ * @param {string} [props.containerClassName] - Additional CSS classes for the container
+ * @param {boolean} [props.showImage] - Whether to show image previews instead of file list
+ * @param {string} [props.previewClassName] - Additional CSS classes for previews
+ * @param {boolean} [props.required] - Whether the field is required
+ * @returns {React.ReactElement} The rendered file upload component
+ *
+ * @example
+ * ```tsx
+ * <FileUpload
+ *   label="Upload Documents"
+ *   name="documents"
+ *   files={files}
+ *   onChange={setFiles}
+ *   accept=".pdf,.docx"
+ *   multiple
+ *   required
+ * />
+ * ```
+ */
 export const FileUpload = ({
   label,
   name = 'file-input',

package/src/components/Input/FormActions/FormActions.tsx

@@ -14,6 +14,43 @@ export interface FormActionsProps {
   showTopBorder?: boolean;
 }
 
+/**
+ * FormActions component for form submission and cancellation
+ *
+ * A component that renders submit and cancel buttons with customizable configurations
+ * and visibility options. Typically used at the bottom of forms.
+ *
+ * @component
+ * @param {FormActionsProps} props - The form actions properties
+ * @param {ButtonConfig} [props.submitButtonProps] - Configuration for the submit button
+ * @param {ButtonConfig} [props.submitButtonProps.show=true] - Whether to show the submit button
+ * @param {string} [props.submitButtonProps.title='Submit'] - Submit button label
+ * @param {() => void} [props.submitButtonProps.onClick] - Callback when submit is clicked
+ * @param {ButtonConfig} [props.cancelButtonProps] - Configuration for the cancel button
+ * @param {ButtonConfig} [props.cancelButtonProps.show=true] - Whether to show the cancel button
+ * @param {string} [props.cancelButtonProps.title='Cancel'] - Cancel button label
+ * @param {() => void} [props.cancelButtonProps.onClick] - Callback when cancel is clicked
+ * @param {string} [props.className] - Additional CSS classes to apply
+ * @param {boolean} [props.showTopBorder=false] - Whether to show a top border
+ * @returns {React.ReactElement} The rendered form actions component
+ *
+ * @example
+ * ```tsx
+ * <FormActions
+ *   submitButtonProps={{
+ *     title: 'Save Changes',
+ *     onClick: handleSubmit,
+ *     variant: 'default'
+ *   }}
+ *   cancelButtonProps={{
+ *     title: 'Discard',
+ *     onClick: handleCancel,
+ *     variant: 'ghost'
+ *   }}
+ *   showTopBorder
+ * />
+ * ```
+ */
 export const FormActions = ({
   submitButtonProps,
   cancelButtonProps,

package/src/components/Input/FormControlWrapper/FormControlWrapper.tsx

@@ -32,6 +32,37 @@ type ControlledElementProps<T extends FieldValues = FieldValues> = {
   [key: string]: any;
 };
 
+/**
+ * FormControlWrapper component for react-hook-form integration
+ *
+ * A wrapper component that integrates react-hook-form's Controller with form elements,
+ * automatically handling field registration, validation, and error display.
+ *
+ * @component
+ * @template T - The form values type from react-hook-form
+ * @param {FormControlWrapperProps<T>} props - The wrapper properties
+ * @param {Control<T>} props.control - React Hook Form control instance from useForm()
+ * @param {ReactNode} props.children - Child form elements to be controlled
+ * @param {string} [props.containerClassName] - Additional CSS classes for the container
+ * @param {FormActionsProps} [props.formActionProps] - Properties for form submit/cancel buttons
+ * @param {boolean} [props.disabled=false] - Whether all controlled fields are disabled
+ * @returns {React.ReactElement} The rendered wrapper with controlled form elements
+ *
+ * @example
+ * ```tsx
+ * const { control, handleSubmit } = useForm();
+ *
+ * <FormControlWrapper
+ *   control={control}
+ *   formActionProps={{
+ *     submitButtonProps: { onClick: handleSubmit(onSubmit) }
+ *   }}
+ * >
+ *   <TextField name="email" label="Email" />
+ *   <PasswordField name="password" label="Password" />
+ * </FormControlWrapper>
+ * ```
+ */
 export function FormControlWrapper<T extends FieldValues = FieldValues>({
   control,
   children,

package/src/components/Input/FormWrapper/FormWrapper.tsx

@@ -6,6 +6,26 @@ type FormWrapperProps = {
   className?: string;
 };
 
+/**
+ * FormWrapper component for layout styling
+ *
+ * A simple wrapper component that provides default styling and spacing for form elements.
+ * Used to maintain consistent form layout and spacing throughout the application.
+ *
+ * @component
+ * @param {FormWrapperProps} props - The wrapper properties
+ * @param {ReactNode} props.children - Child form elements
+ * @param {string} [props.className] - Additional CSS classes to apply
+ * @returns {React.ReactElement} The styled form wrapper container
+ *
+ * @example
+ * ```tsx
+ * <FormWrapper>
+ *   <TextField label="Name" name="name" />
+ *   <TextField label="Email" name="email" />
+ * </FormWrapper>
+ * ```
+ */
 export const FormWrapper = ({ children, className }: FormWrapperProps) => {
   return (
     <div className={cn('flex flex-col gap-3 m-4', className)}>{children}</div>

package/src/components/Input/HelpButton/HelpButton.tsx

@@ -1,6 +1,20 @@
 import { MessageCircleQuestionMark } from 'lucide-react';
 import { Button } from '../../export';
 
+/**
+ * HelpButton component for documentation access
+ *
+ * A button component that opens the help/documentation page in a new window
+ * when clicked. Features a question mark icon.
+ *
+ * @component
+ * @returns {React.ReactElement} The rendered help button
+ *
+ * @example
+ * ```tsx
+ * <HelpButton />
+ * ```
+ */
 const HelpButton = () => {
   return (
     <Button

package/src/components/Input/IconButtons/IconButtons/DeleteButton.tsx

@@ -1,6 +1,22 @@
 import { Trash2 } from 'lucide-react';
 import { Button, ButtonProps } from '../../Button/Button';
 
+/**
+ * DeleteButton component for delete actions
+ *
+ * An icon button with a trash icon for triggering delete/remove actions.
+ * Minimal styling suitable for use in tables and lists.
+ *
+ * @component
+ * @param {ButtonProps} props - Button properties
+ * @param {boolean} [props.disabled] - Whether the button is disabled
+ * @returns {React.ReactElement} The rendered delete button
+ *
+ * @example
+ * ```tsx
+ * <DeleteButton onClick={handleDelete} />
+ * ```
+ */
 export function DeleteButton({ disabled, ...props }: ButtonProps) {
   return (
     <Button size="icon" variant="ghost" disabled={disabled} {...props}>

package/src/components/Input/IconButtons/IconButtons/EditButton.tsx

@@ -1,6 +1,22 @@
 import { Pencil } from 'lucide-react';
 import { Button, ButtonProps } from '../../Button/Button';
 
+/**
+ * EditButton component for edit actions
+ *
+ * An icon button with a pencil icon for triggering edit/modify actions.
+ * Minimal styling suitable for use in tables and lists.
+ *
+ * @component
+ * @param {ButtonProps} props - Button properties
+ * @param {boolean} [props.disabled] - Whether the button is disabled
+ * @returns {React.ReactElement} The rendered edit button
+ *
+ * @example
+ * ```tsx
+ * <EditButton onClick={handleEdit} />
+ * ```
+ */
 export function EditButton({ disabled, ...props }: ButtonProps) {
   return (
     <Button size="icon" variant="ghost" disabled={disabled} {...props}>

package/src/components/Input/IconButtons/IconButtons/RedirectButton.tsx

@@ -1,6 +1,22 @@
 import { SquareArrowOutUpRight } from 'lucide-react';
 import { Button, ButtonProps } from '../../Button/Button';
 
+/**
+ * RedirectButton component for navigation/external link actions
+ *
+ * An icon button with an external link arrow icon for redirecting users
+ * to other pages or external URLs. Minimal styling suitable for use in tables and lists.
+ *
+ * @component
+ * @param {ButtonProps} props - Button properties
+ * @param {boolean} [props.disabled] - Whether the button is disabled
+ * @returns {React.ReactElement} The rendered redirect button
+ *
+ * @example
+ * ```tsx
+ * <RedirectButton onClick={() => window.open(url)} />
+ * ```
+ */
 export function RedirectButton({ disabled, ...props }: ButtonProps) {
   return (
     <Button size="icon" variant="ghost" disabled={disabled} {...props}>

package/src/components/Input/IconButtons/IconButtons/ViewButton.tsx

@@ -1,6 +1,22 @@
 import { Eye } from 'lucide-react';
 import { Button, ButtonProps } from '../../Button/Button';
 
+/**
+ * ViewButton component for view/preview actions
+ *
+ * An icon button with an eye icon for triggering view/preview actions.
+ * Minimal styling suitable for use in tables and lists.
+ *
+ * @component
+ * @param {ButtonProps} props - Button properties
+ * @param {boolean} [props.disabled] - Whether the button is disabled
+ * @returns {React.ReactElement} The rendered view button
+ *
+ * @example
+ * ```tsx
+ * <ViewButton onClick={handleView} />
+ * ```
+ */
 export function ViewButton({ disabled, ...props }: ButtonProps) {
   return (
     <Button size="icon" variant="ghost" disabled={disabled} {...props}>

package/src/components/Input/IconButtons/IconButtons.tsx

@@ -3,6 +3,24 @@ import { EditButton } from './IconButtons/EditButton';
 import { RedirectButton } from './IconButtons/RedirectButton';
 import { ViewButton } from './IconButtons/ViewButton';
 
+/**
+ * IconButtons object namespace
+ *
+ * A collection of common action icon buttons for use in tables and lists.
+ * All buttons are minimal icon-only buttons with consistent styling.
+ *
+ * @namespace IconButtons
+ * @property {typeof DeleteButton} DeleteButton - Button with trash icon for delete actions
+ * @property {typeof EditButton} EditButton - Button with pencil icon for edit actions
+ * @property {typeof ViewButton} ViewButton - Button with eye icon for view/preview actions
+ * @property {typeof RedirectButton} RedirectButton - Button with external link icon for navigation
+ *
+ * @example
+ * ```tsx
+ * <IconButtons.DeleteButton onClick={handleDelete} />
+ * <IconButtons.EditButton onClick={handleEdit} />
+ * ```
+ */
 export const IconButtons = {
   DeleteButton,
   EditButton,

package/src/components/Input/LabelWrapper/LabelWrapper.tsx

@@ -9,6 +9,32 @@ export interface LabelWrapperProps {
   containerProps?: React.HTMLAttributes<HTMLDivElement>;
 }
 
+/**
+ * LabelWrapper component for form field labeling
+ *
+ * A wrapper component that provides consistent label styling and required field indicators.
+ * Automatically handles string labels and custom label elements.
+ *
+ * @component
+ * @param {LabelWrapperProps} props - The wrapper properties
+ * @param {boolean} props.required - Whether the field is required (adds asterisk indicator)
+ * @param {string} [props.name] - Name attribute for the associated label
+ * @param {ReactNode | string} [props.label] - The label text or element
+ * @param {ReactNode} props.children - The form element to be labeled
+ * @param {React.HTMLAttributes<HTMLDivElement>} [props.containerProps] - Additional container attributes
+ * @returns {React.ReactElement} The label and children wrapped in a container
+ *
+ * @example
+ * ```tsx
+ * <LabelWrapper
+ *   label="Email Address"
+ *   name="email"
+ *   required
+ * >
+ *   <Input type="email" />
+ * </LabelWrapper>
+ * ```
+ */
 export const LabelWrapper = ({
   required,
   name,

package/src/components/Input/MultiCheckBox/MultiCheckBox.tsx

@@ -15,6 +15,40 @@ export type MultiCheckboxProps = {
   className?: string;
 };
 
+/**
+ * MultiCheckBox component for multi-value checkbox selection
+ *
+ * A component that renders multiple checkboxes in a row or column layout,
+ * allowing users to select multiple values from a set of options.
+ *
+ * @component
+ * @param {MultiCheckboxProps} props - The checkbox group properties
+ * @param {string} props.label - Group label text
+ * @param {Array<{label: ReactNode, value: any}>} props.options - Available checkbox options
+ * @param {any[]} props.values - Currently selected values
+ * @param {(values: any[]) => void} props.onChange - Callback when selection changes
+ * @param {string} props.name - Name attribute for the checkbox group
+ * @param {boolean} props.required - Whether the field is required
+ * @param {'row' | 'column'} [props.direction='column'] - Layout direction for checkboxes
+ * @param {string} [props.className] - Additional CSS classes for the options container
+ * @param {React.HTMLAttributes<HTMLDivElement>} [props.containerProps] - Additional container attributes
+ * @returns {React.ReactElement} The rendered checkbox group
+ *
+ * @example
+ * ```tsx
+ * <MultiCheckBox
+ *   label="Select Features"
+ *   name="features"
+ *   values={selectedFeatures}
+ *   onChange={setSelectedFeatures}
+ *   required
+ *   options={[
+ *     { label: 'Feature A', value: 'a' },
+ *     { label: 'Feature B', value: 'b' }
+ *   ]}
+ * />
+ * ```
+ */
 export const MultiCheckBox = ({
   name,
   options,