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

package/src/components/Input/MultiSelect/MultiSelect.tsx

@@ -42,8 +42,50 @@ export type MultiSelectProps = {
   type?: 'input' | 'filter';
   disableClear?: boolean;
   fullWidth?: boolean;
+  disabled?: boolean;
+  loading?: boolean;
 };
 
+/**
+ * MultiSelect component for multi-value selection
+ *
+ * A feature-rich multi-select component supporting both local and API-driven options,
+ * with search, pagination, filtering, and flexible display modes.
+ *
+ * @component
+ * @param {MultiSelectProps} props - The select properties
+ * @param {Array<{label: string, subLabel?: string, value: any, icon?: ReactNode}>} [props.options] - Static options array
+ * @param {string} [props.optionsApiEndPoint] - API endpoint for dynamic options loading
+ * @param {any} [props.optionsApiEndpointParams] - Additional parameters for API requests
+ * @param {AxiosInstance} [props.externalAxios] - Custom axios instance for API calls
+ * @param {any[]} [props.value] - Currently selected values
+ * @param {(values: any[]) => void} [props.onChange] - Callback fired when selection changes
+ * @param {(option: any) => any} [props.getValue] - Function to extract value from option object
+ * @param {{valueKey: string, isObjectId?: boolean, isInt?: boolean, isFloat?: boolean}} [props.dbValueProps] - Database value mapping properties
+ * @param {{labelKey: string, subLabelKey?: string, useLabelStartCase?: boolean, useSubLabelStartCase?: boolean}} [props.dbLabelProps] - Database label mapping properties
+ * @param {string} [props.label] - Label for the select
+ * @param {string} [props.name] - Name attribute
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether the select is disabled
+ * @param {boolean} [props.loading] - Whether options are loading
+ * @param {boolean} [props.disableClear] - Whether to hide the clear button
+ * @param {boolean} [props.fullWidth] - Whether the select takes full width
+ * @param {'input' | 'filter'} [props.type='input'] - Display type
+ * @param {(event: SyntheticEvent) => void} [props.onOpen] - Callback when menu opens
+ * @param {(event: SyntheticEvent, reason: string) => void} [props.onClose] - Callback when menu closes
+ * @returns {React.ReactElement} The rendered multi-select component
+ *
+ * @example
+ * ```tsx
+ * <MultiSelect
+ *   label="Select Users"
+ *   value={selectedUsers}
+ *   onChange={setSelectedUsers}
+ *   options={users}
+ *   required
+ * />
+ * ```
+ */
 export const MultiSelect = ({
   options,
   optionsApiEndPoint,

package/src/components/Input/MultiSelect/components/MultiSelectFilter.tsx

@@ -46,6 +46,8 @@ export const MultiSelectFilter = ({
   handleClearAll,
   state,
   disableClear = false,
+  disabled = false,
+  loading = false,
 }: MultiSelectFilterProps) => {
   const {
     open,
@@ -101,8 +103,10 @@ export const MultiSelectFilter = ({
 
   return (
     <Popover
-      open={open}
+      open={open && !disabled}
       onOpenChange={(isOpen) => {
+        if (disabled) return;
+
         const syntheticEvent = {
           currentTarget: {},
           target: {},
@@ -115,7 +119,7 @@ export const MultiSelectFilter = ({
         }
       }}
     >
-      <PopoverTrigger asChild>
+      <PopoverTrigger asChild disabled={disabled}>
         <span
           ref={wrapperRef}
           style={{ display: 'inline-block', width: '100%' }}
@@ -125,7 +129,7 @@ export const MultiSelectFilter = ({
             role="combobox"
             aria-expanded={open}
             className="justify-between w-full"
-            disabled={loadingInitialInternalOptions}
+            disabled={disabled || loading || loadingInitialInternalOptions}
           >
             {displayText || label}
             <ChevronDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />

package/src/components/Input/MultiSelect/components/MultiSelectInput.tsx

@@ -55,6 +55,8 @@ export const MultiSelectInput = ({
   state,
   disableClear = false,
   fullWidth,
+  disabled = false,
+  loading = false,
 }: MultiSelectInputProps) => {
   const {
     open,
@@ -88,7 +90,7 @@ export const MultiSelectInput = ({
     .map((val) => internalOptionsMap[val])
     .filter(Boolean);
 
-  if (loadingInitialInternalOptions) {
+  if (loadingInitialInternalOptions || loading) {
     return (
       <TextField
         label={label}
@@ -117,8 +119,10 @@ export const MultiSelectInput = ({
       }}
     >
       <Popover
-        open={open}
+        open={open && !disabled}
         onOpenChange={(isOpen) => {
+          if (disabled) return;
+
           const syntheticEvent = {
             currentTarget: {},
             target: {},
@@ -131,7 +135,7 @@ export const MultiSelectInput = ({
           }
         }}
       >
-        <PopoverTrigger asChild>
+        <PopoverTrigger asChild disabled={disabled}>
           <span
             ref={wrapperRef}
             style={{ display: fullWidth ? 'block' : 'inline-block' }}
@@ -141,6 +145,7 @@ export const MultiSelectInput = ({
               role="combobox"
               aria-expanded={open}
               aria-invalid={!!error}
+              disabled={disabled}
               className={cn(
                 'justify-between font-normal min-h-[40px] h-auto',
                 fullWidth ? 'w-full' : 'w-auto',

package/src/components/Input/OtpInput/OtpInput.tsx

@@ -16,6 +16,35 @@ interface OtpInputProps {
   helperText?: string;
 }
 
+/**
+ * OtpInput component for one-time password entry
+ *
+ * A component that renders a sequence of single-digit input fields for OTP entry,
+ * with auto-focus, paste support, and keyboard navigation.
+ *
+ * @component
+ * @param {OtpInputProps} props - The OTP input properties
+ * @param {number} props.length - Number of OTP digits
+ * @param {(otp: string) => void} props.onChangeOtp - Callback fired when OTP changes
+ * @param {string} [props.label] - Optional label for the OTP input group
+ * @param {string} [props.name] - Name attribute for the inputs
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.error=false] - Whether there's a validation error
+ * @param {string} [props.helperText] - Helper or error text to display
+ * @param {string} [props.containerClassName] - Additional CSS classes for the input container
+ * @param {string} [props.inputClassName] - Additional CSS classes for individual inputs
+ * @returns {React.ReactElement} The rendered OTP input component
+ *
+ * @example
+ * ```tsx
+ * <OtpInput
+ *   length={6}
+ *   onChangeOtp={setOtp}
+ *   label="Enter Verification Code"
+ *   required
+ * />
+ * ```
+ */
 export const OtpInput = ({
   length,
   onChangeOtp,

package/src/components/Input/PasswordField/PasswordField.tsx

@@ -21,6 +21,40 @@ export type PasswordFieldProps = {
   fullWidth?: boolean;
 } & Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'>;
 
+/**
+ * PasswordField component for password input
+ *
+ * A text input field specialized for password entry with visibility toggle,
+ * error states, and helper text support.
+ *
+ * @component
+ * @param {PasswordFieldProps} props - The password field properties
+ * @param {string} [props.label] - Label for the field
+ * @param {string} [props.name] - Name attribute for the input
+ * @param {string} [props.value] - Current input value
+ * @param {(e: React.ChangeEvent<HTMLInputElement>) => void} [props.onChange] - Callback when value changes
+ * @param {string} [props.placeholder='Enter password'] - Placeholder text
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether the field is disabled
+ * @param {boolean} [props.error] - Whether there's a validation error
+ * @param {string} [props.helperText] - Helper or error text
+ * @param {string} [props.description] - Additional description text
+ * @param {boolean} [props.fullWidth] - Whether the field takes full width
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.HTMLAttributes<HTMLDivElement>} [props.containerProps] - Container attributes
+ * @returns {React.ReactElement} The rendered password field component
+ *
+ * @example
+ * ```tsx
+ * <PasswordField
+ *   label="Password"
+ *   name="password"
+ *   value={password}
+ *   onChange={(e) => setPassword(e.target.value)}
+ *   required
+ * />
+ * ```
+ */
 export const PasswordField = ({
   name,
   label,

package/src/components/Input/RadioGroup/RadioGroup.tsx

@@ -22,6 +22,44 @@ export type RadioGroupProps = {
   helperText?: ReactNode;
 };
 
+/**
+ * RadioGroup component for exclusive single-value selection
+ *
+ * A component that renders a group of radio buttons allowing users to select
+ * exactly one value from a set of options, with row or column layout.
+ *
+ * @component
+ * @param {RadioGroupProps} props - The radio group properties
+ * @param {string} props.name - Name attribute for the radio group
+ * @param {Array<{label: ReactNode, value: any, disabled?: boolean}>} props.options - Available radio options
+ * @param {string} [props.label] - Group label text
+ * @param {any} [props.value] - Currently selected value (controlled)
+ * @param {any} [props.defaultValue] - Default selected value (uncontrolled)
+ * @param {(value: any) => void} [props.onChange] - Callback when selection changes
+ * @param {(value: string) => void} [props.onValueChange] - Alternative callback when selection changes
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether all options are disabled
+ * @param {'row' | 'column'} [props.direction='column'] - Layout direction for radio buttons
+ * @param {boolean} [props.error] - Whether there's a validation error
+ * @param {ReactNode} [props.helperText] - Helper or error text
+ * @param {string} [props.className] - Additional CSS classes for the radio container
+ * @param {React.HTMLAttributes<HTMLDivElement>} [props.containerProps] - Container attributes
+ * @returns {React.ReactElement} The rendered radio group component
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup
+ *   name="status"
+ *   label="Select Status"
+ *   value={status}
+ *   onChange={setStatus}
+ *   options={[
+ *     { label: 'Active', value: 'active' },
+ *     { label: 'Inactive', value: 'inactive' }
+ *   ]}
+ * />
+ * ```
+ */
 export const RadioGroup = ({
   label,
   required = false,

package/src/components/Input/SearchBar/SearchBar.tsx

@@ -15,6 +15,32 @@ export type SearchBarProps = {
   inputClassName?: string;
 } & Omit<React.ComponentProps<'input'>, 'onChange' | 'value'>;
 
+/**
+ * SearchBar component for search input
+ *
+ * A search input component with built-in debouncing for efficient search operations,
+ * featuring a search icon and customizable styling.
+ *
+ * @component
+ * @param {SearchBarProps} props - The search bar properties
+ * @param {string} [props.placeholder='Search by Name'] - Placeholder text
+ * @param {string | ReactNode} [props.label] - Optional label above the search input
+ * @param {string} [props.value=''] - Current search value
+ * @param {(value: string) => void} [props.onSearch] - Callback fired when search value changes (debounced)
+ * @param {string} [props.className] - Additional CSS classes for the input wrapper
+ * @param {string} [props.containerClassName] - Additional CSS classes for the container
+ * @param {string} [props.inputClassName] - Additional CSS classes for the input element
+ * @returns {React.ReactElement} The rendered search bar component
+ *
+ * @example
+ * ```tsx
+ * <SearchBar
+ *   label="Search Users"
+ *   placeholder="Enter username..."
+ *   onSearch={handleSearch}
+ * />
+ * ```
+ */
 export const SearchBar = ({
   placeholder = 'Search by Name',
   label,

package/src/components/Input/Select/Select.tsx

@@ -6,6 +6,7 @@ import {
   SelectValue,
   Select as ShadcnSelect,
 } from '@/shadcn-components/Input/Select/Select';
+import { Loader2 } from 'lucide-react';
 import * as React from 'react';
 import { useEffect, useRef, useState } from 'react';
 
@@ -29,8 +30,18 @@ export type SelectProps = {
   className?: string;
   disabled?: boolean;
   fullWidth?: boolean;
+  loading?: boolean;
 };
 
+/**
+ * Helper function to get color CSS classes for select options
+ *
+ * Maps color names to Tailwind CSS classes for styling select options.
+ *
+ * @param {string} [color] - Color name ('red', 'green', 'blue', 'pink', 'yellow', 'orange', 'secondary')
+ * @returns {string} Tailwind CSS classes for the color
+ * @internal
+ */
 const getColorClasses = (
   color?: 'red' | 'green' | 'blue' | 'pink' | 'yellow' | 'orange' | 'secondary',
 ) => {
@@ -54,6 +65,38 @@ const getColorClasses = (
   }
 };
 
+/**
+ * Select component for single-value selection
+ *
+ * A select dropdown component with support for colors, loading states, and flexible sizing.
+ * Built on shadcn's Select component with additional enhancements.
+ *
+ * @component
+ * @param {SelectProps} props - The select properties
+ * @param {Array<{label: React.ReactNode, value: string | number, color?: string}>} props.options - Available select options
+ * @param {(value: string) => void} [props.onChange] - Callback fired when selection changes
+ * @param {string | number} [props.value] - Currently selected value (controlled)
+ * @param {string | number} [props.defaultValue] - Default selected value (uncontrolled)
+ * @param {string} [props.placeholder='Select an option...'] - Placeholder text when no value selected
+ * @param {boolean} [props.disabled] - Whether the select is disabled
+ * @param {boolean} [props.loading] - Whether options are loading
+ * @param {boolean} [props.fullWidth] - Whether the select takes full width
+ * @param {string} [props.className] - Additional CSS classes
+ * @returns {React.ReactElement} The rendered select component
+ *
+ * @example
+ * ```tsx
+ * <Select
+ *   options={[
+ *     { label: 'Option 1', value: 'opt1', color: 'blue' },
+ *     { label: 'Option 2', value: 'opt2', color: 'green' }
+ *   ]}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   placeholder="Choose an option"
+ * />
+ * ```
+ */
 export const Select = ({
   options = [],
   onChange,
@@ -63,6 +106,7 @@ export const Select = ({
   defaultValue,
   disabled = false,
   fullWidth = false,
+  loading = false,
 }: SelectProps) => {
   const wrapperRef = useRef<HTMLDivElement>(null);
 
@@ -111,18 +155,25 @@ export const Select = ({
         </SelectTrigger>
       </div>
       <SelectContent>
-        {options?.map((item, index) => {
-          const itemColorClasses = getColorClasses(item.color);
-          return (
-            <SelectItem
-              key={index}
-              value={item.value.toString()}
-              className={cn(itemColorClasses)}
-            >
-              {item.label}
-            </SelectItem>
-          );
-        })}
+        {loading ? (
+          <div className="flex flex-col items-center justify-center py-8 px-4">
+            <Loader2 className="h-6 w-6 animate-spin text-muted-foreground mb-2" />
+            <p className="text-sm text-muted-foreground">Loading...</p>
+          </div>
+        ) : (
+          options?.map((item, index) => {
+            const itemColorClasses = getColorClasses(item.color);
+            return (
+              <SelectItem
+                key={index}
+                value={item.value.toString()}
+                className={cn(itemColorClasses)}
+              >
+                {item.label}
+              </SelectItem>
+            );
+          })
+        )}
       </SelectContent>
     </ShadcnSelect>
   );

package/src/components/Input/SingleCheckBox/SingleCheckBox.tsx

@@ -18,6 +18,35 @@ export type CheckboxProps = {
   'checked' | 'onChange' | 'onCheckedChange'
 >;
 
+/**
+ * SingleCheckBox component for single checkbox selection
+ *
+ * A checkbox component with label support, validation states, and required field indicators.
+ * Built on Radix UI's checkbox primitive.
+ *
+ * @component
+ * @param {CheckboxProps} props - The checkbox properties
+ * @param {ReactNode} props.label - Label text for the checkbox
+ * @param {boolean} [props.checked] - Whether the checkbox is checked (controlled)
+ * @param {(checked: boolean) => void} [props.onChange] - Callback when checked state changes
+ * @param {string} [props.name] - Name attribute for the checkbox
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether the checkbox is disabled
+ * @param {string} [props.className] - Additional CSS classes for the checkbox
+ * @param {string} [props.labelClassName] - Additional CSS classes for the label
+ * @param {string} [props.containerClassName='flex items-center space-x-2'] - Additional CSS classes for the container
+ * @returns {React.ReactElement} The rendered checkbox component
+ *
+ * @example
+ * ```tsx
+ * <SingleCheckBox
+ *   label="I agree to the terms"
+ *   checked={agreed}
+ *   onChange={setAgreed}
+ *   required
+ * />
+ * ```
+ */
 export const SingleCheckBox = ({
   checked,
   label,

package/src/components/Input/SingleSelect/SingleSelect.tsx

@@ -50,8 +50,50 @@ export type SingleSelectProps = {
   type?: 'input' | 'filter';
   disableClear?: boolean;
   fullWidth?: boolean;
+  disabled?: boolean;
+  loading?: boolean;
 };
 
+/**
+ * SingleSelect component for single-value selection
+ *
+ * A feature-rich single-select component supporting both local and API-driven options,
+ * with search, pagination, filtering, and flexible display modes.
+ *
+ * @component
+ * @param {SingleSelectProps} props - The select properties
+ * @param {Array<{label: string, subLabel?: string, value: any, icon?: ReactNode}>} [props.options] - Static options array
+ * @param {string} [props.optionsApiEndPoint] - API endpoint for dynamic options loading
+ * @param {any} [props.optionsApiEndpointParams] - Additional parameters for API requests
+ * @param {AxiosInstance} [props.externalAxios] - Custom axios instance for API calls
+ * @param {any} [props.value] - Currently selected value
+ * @param {(value: any) => void} [props.onChange] - Callback fired when selection changes
+ * @param {(option: any) => any} [props.getValue] - Function to extract value from option object
+ * @param {{valueKey: string, isObjectId?: boolean, isInt?: boolean, isFloat?: boolean}} [props.dbValueProps] - Database value mapping properties
+ * @param {{labelKey: string, subLabelKey?: string, useLabelStartCase?: boolean, useSubLabelStartCase?: boolean}} [props.dbLabelProps] - Database label mapping properties
+ * @param {string} [props.label] - Label for the select
+ * @param {string} [props.name] - Name attribute
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether the select is disabled
+ * @param {boolean} [props.loading] - Whether options are loading
+ * @param {boolean} [props.disableClear] - Whether to hide the clear button
+ * @param {boolean} [props.fullWidth] - Whether the select takes full width
+ * @param {'input' | 'filter'} [props.type='input'] - Display type
+ * @param {(event: SyntheticEvent) => void} [props.onOpen] - Callback when menu opens
+ * @param {(event: SyntheticEvent, reason: string) => void} [props.onClose] - Callback when menu closes
+ * @returns {React.ReactElement} The rendered single-select component
+ *
+ * @example
+ * ```tsx
+ * <SingleSelect
+ *   label="Select User"
+ *   value={selectedUser}
+ *   onChange={setSelectedUser}
+ *   options={users}
+ *   required
+ * />
+ * ```
+ */
 export const SingleSelect = ({
   options,
   optionsApiEndPoint,

package/src/components/Input/SingleSelect/components/SingleFilter.tsx

@@ -43,6 +43,8 @@ export const SingleFilter = ({
   state,
   disableClear = false,
   fullWidth,
+  disabled = false,
+  loading = false,
 }: SingleFilterProps) => {
   const {
     open,
@@ -82,8 +84,10 @@ export const SingleFilter = ({
 
   return (
     <Popover
-      open={open}
+      open={open && !disabled}
       onOpenChange={(isOpen) => {
+        if (disabled) return;
+
         const syntheticEvent = {
           currentTarget: {},
           target: {},
@@ -96,7 +100,7 @@ export const SingleFilter = ({
         }
       }}
     >
-      <PopoverTrigger asChild>
+      <PopoverTrigger asChild disabled={disabled}>
         <span
           ref={wrapperRef}
           style={{ display: fullWidth ? 'block' : 'inline-block' }}
@@ -106,7 +110,7 @@ export const SingleFilter = ({
             role="combobox"
             aria-expanded={open}
             className={cn('justify-between', fullWidth ? 'w-full' : '')}
-            disabled={loadingInitialInternalOptions}
+            disabled={disabled || loading || loadingInitialInternalOptions}
           >
             {selectedOption ? `${label} = ${selectedOption.label}` : label}
             <ChevronDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />

package/src/components/Input/SingleSelect/components/SingleInput.tsx

@@ -48,6 +48,8 @@ export const SingleInput = ({
   handleScroll,
   state,
   fullWidth,
+  disabled = false,
+  loading = false,
 }: SingleInputProps) => {
   const {
     open,
@@ -77,7 +79,7 @@ export const SingleInput = ({
 
   const selectedOption = internalOptionsMap[value];
 
-  if (loadingInitialInternalOptions) {
+  if (loadingInitialInternalOptions || loading) {
     return (
       <TextField
         label={label}
@@ -103,8 +105,10 @@ export const SingleInput = ({
       }}
     >
       <Popover
-        open={open}
+        open={open && !disabled}
         onOpenChange={(isOpen) => {
+          if (disabled) return;
+
           const syntheticEvent = {
             currentTarget: {},
             target: {},
@@ -117,7 +121,7 @@ export const SingleInput = ({
           }
         }}
       >
-        <PopoverTrigger asChild>
+        <PopoverTrigger asChild disabled={disabled}>
           <span
             ref={wrapperRef}
             style={{ display: fullWidth ? 'block' : 'inline-block' }}
@@ -127,6 +131,7 @@ export const SingleInput = ({
               role="combobox"
               aria-expanded={open}
               aria-invalid={!!error}
+              disabled={disabled}
               className={cn(
                 'justify-between font-normal',
                 fullWidth ? 'w-full' : 'w-auto',

package/src/components/Input/Switch/Switch.tsx

@@ -7,6 +7,29 @@ export interface SwitchProps
   label?: string;
 }
 
+/**
+ * Switch component for boolean toggle input
+ *
+ * A toggle switch component with optional label support, built on shadcn's Switch.
+ * Renders a label beside the switch if provided.
+ *
+ * @component
+ * @param {SwitchProps} props - The switch properties
+ * @param {string} [props.label] - Optional label text to display next to the switch
+ * @param {boolean} [props.checked] - Whether the switch is checked
+ * @param {(checked: boolean) => void} [props.onCheckedChange] - Callback when switch state changes
+ * @param {boolean} [props.disabled] - Whether the switch is disabled
+ * @returns {React.ReactElement} The rendered switch component
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   label="Enable notifications"
+ *   checked={enabled}
+ *   onCheckedChange={setEnabled}
+ * />
+ * ```
+ */
 export const Switch = React.forwardRef<
   React.ElementRef<typeof ShadcnSwitch>,
   SwitchProps

package/src/components/Input/Tags/Tags.tsx

@@ -9,6 +9,32 @@ export type TagsProps = {
   className?: string;
 };
 
+/**
+ * Tags component for displaying and managing tag badges
+ *
+ * A component that renders a collection of tags/badges with optional delete functionality.
+ * Useful for displaying categories, labels, or removable items.
+ *
+ * @component
+ * @param {TagsProps} props - The tags properties
+ * @param {Array<{label: string, value: any}>} props.tags - Array of tags to display
+ * @param {(deletedChip: any) => void} [props.onDelete] - Callback fired when a tag is deleted
+ * @param {'default' | 'secondary' | 'destructive' | 'outline'} [props.variant='secondary'] - Badge variant style
+ * @param {string} [props.className] - Additional CSS classes for the container
+ * @returns {React.ReactElement} The rendered tags component
+ *
+ * @example
+ * ```tsx
+ * <Tags
+ *   tags={[
+ *     { label: 'React', value: 'react' },
+ *     { label: 'TypeScript', value: 'ts' }
+ *   ]}
+ *   onDelete={handleTagDelete}
+ *   variant="secondary"
+ * />
+ * ```
+ */
 export const Tags = ({
   tags,
   onDelete,

package/src/components/Input/TextField/TextField.tsx

@@ -14,6 +14,41 @@ export type TextFieldProps = {
   helperText?: React.ReactNode;
 } & React.ComponentProps<typeof Input>;
 
+/**
+ * TextField component for text input
+ *
+ * A general-purpose text input field with label support, validation states,
+ * helper/error text, and optional description.
+ *
+ * @component
+ * @param {TextFieldProps} props - The text field properties
+ * @param {React.ReactNode | string} [props.label] - Label for the field
+ * @param {string} [props.name] - Name attribute for the input
+ * @param {string} [props.value] - Current input value
+ * @param {(e: React.ChangeEvent<HTMLInputElement>) => void} [props.onChange] - Callback when value changes
+ * @param {string} [props.placeholder] - Placeholder text
+ * @param {boolean} [props.required] - Whether the field is required
+ * @param {boolean} [props.disabled] - Whether the field is disabled
+ * @param {boolean} [props.error] - Whether there's a validation error
+ * @param {React.ReactNode} [props.helperText] - Helper or error text
+ * @param {string} [props.description] - Additional description text
+ * @param {boolean} [props.fullWidth] - Whether the field takes full width
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.HTMLAttributes<HTMLDivElement>} [props.containerProps] - Container attributes
+ * @returns {React.ReactElement} The rendered text field component
+ *
+ * @example
+ * ```tsx
+ * <TextField
+ *   label="Username"
+ *   name="username"
+ *   value={username}
+ *   onChange={(e) => setUsername(e.target.value)}
+ *   placeholder="Enter your username"
+ *   required
+ * />
+ * ```
+ */
 export const TextField = ({
   name,
   label,