@trackunit/react-form-components 1.11.17 → 1.11.19

package/index.esm.js

@@ -1,9 +1,9 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { useNamespaceTranslation, registerTranslations, NamespaceTrans } from '@trackunit/i18n-library-translation';
 import { Temporal } from '@js-temporal/polyfill';
-import { IconButton, Icon, Tooltip, cvaMenu, cvaMenuList, Tag, useIsTextTruncated, ZStack, MenuItem, useMeasure, useDebounce, Spinner, useMergeRefs, useScrollBlock, Text, Heading, useIsFirstRender } from '@trackunit/react-components';
+import { IconButton, Icon, Tooltip, cvaMenu, cvaMenuList, Tag, useIsTextTruncated, ZStack, MenuItem, useMeasure, useDebounce, useMergeRefs, Spinner, useScrollBlock, Text, Heading, useIsFirstRender } from '@trackunit/react-components';
 import { themeSpacing } from '@trackunit/ui-design-tokens';
-import { forwardRef, useRef, useEffect, useImperativeHandle, useCallback, useState, isValidElement, cloneElement, useLayoutEffect, useReducer, useMemo, createContext, useContext } from 'react';
+import { forwardRef, useRef, useEffect, useImperativeHandle, useCallback, useState, cloneElement, isValidElement, useLayoutEffect, useReducer, useMemo, createContext, useContext } from 'react';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { titleCase } from 'string-ts';
 import { useCopyToClipboard } from 'usehooks-ts';
@@ -1035,10 +1035,54 @@ const IndeterminateIcon = ({ className }) => (jsx("svg", { className: className,
  *
  * Checkboxes are used for multiple choices, not for mutually exclusive choices. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections.
  *
- * _**Do use** checkboxes to allow selection in a form, for filtering, terms and conditions to indicate agreement, and bulk actions in lists or tables._
+ * ### When to use
+ * Use checkboxes to allow selection in a form, for filtering, terms and conditions to indicate agreement, and bulk actions in lists or tables.
  *
- * _**Do not use** checkboxes if the user can only select one option from a list, radio buttons should be used instead of checkboxes._
+ * ### When not to use
+ * Do not use checkboxes if the user can only select one option from a list. Use RadioGroup instead.
  *
+ * @example Basic checkbox
+ * ```tsx
+ * import { Checkbox } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const MyForm = () => {
+ *   const [accepted, setAccepted] = useState(false);
+ *
+ *   return (
+ *     <Checkbox
+ *       label="I accept the terms and conditions"
+ *       checked={accepted}
+ *       onChange={(e) => setAccepted(e.target.checked)}
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Checkbox group for multiple selections
+ * ```tsx
+ * import { Checkbox } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const NotificationSettings = () => {
+ *   const [notifications, setNotifications] = useState({
+ *     email: true,
+ *     sms: false,
+ *     push: true,
+ *   });
+ *
+ *   const handleChange = (key: keyof typeof notifications) => (e: React.ChangeEvent<HTMLInputElement>) => {
+ *     setNotifications((prev) => ({ ...prev, [key]: e.target.checked }));
+ *   };
+ *
+ *   return (
+ *     <div className="flex flex-col gap-2">
+ *       <Checkbox label="Email notifications" checked={notifications.email} onChange={handleChange("email")} />
+ *       <Checkbox label="SMS notifications" checked={notifications.sms} onChange={handleChange("sms")} />
+ *       <Checkbox label="Push notifications" checked={notifications.push} onChange={handleChange("push")} />
+ *     </div>
+ *   );
+ * };
+ * ```
  * @description A reference to the input element is provided as the `ref` prop.
  * @augments props from [React.InputHTMLAttributes](https://reactjs.org/docs/dom-elements.html#input)
  * @param {CheckboxProps} props - The props for the Checkbox component
@@ -2095,9 +2139,41 @@ const isValidHEXColor = (value) => {
     return hexRegex.test(value);
 };
 /**
- * The ColorField component is used to enter color.
- * ColorField validates that user enters a valid color address.
+ * The `<ColorField>` component is used to select and enter colors.
+ * It provides both a color picker and a text input for hex color codes,
+ * with validation ensuring valid hex format (#RRGGBB).
+ *
+ * ### When to use
+ * - Color selection in theming or customization forms
+ * - Brand color configuration
+ * - Any input requiring a valid hex color value
+ *
+ * ### When not to use
+ * - When you need a full color palette with named colors
+ * - When opacity/alpha channel is required (only supports 6-digit hex)
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { ColorField } from "@trackunit/react-form-components";
+ *
+ * const [color, setColor] = useState("#3B82F6");
+ *
+ * <ColorField
+ *   label="Brand Color"
+ *   value={color}
+ *   onChange={(e) => setColor(e.target.value)}
+ * />
+ * ```
+ * @example With validation
+ * ```tsx
+ * import { ColorField } from "@trackunit/react-form-components";
  *
+ * <ColorField
+ *   label="Primary Color"
+ *   helpText="Enter a valid hex color (e.g., #FF5500)"
+ *   required
+ * />
+ * ```
  */
 const ColorField = forwardRef(({ label, id, tip, helpText, errorMessage, helpAddon, className, defaultValue, "data-testid": dataTestId, value: propValue, onChange, isInvalid, onBlur, fieldSize = "medium", style, disabled, readOnly, isWarning, inputClassName, ...inputProps }, ref) => {
     const renderAsDisabled = Boolean(disabled);
@@ -2156,11 +2232,52 @@ const ColorField = forwardRef(({ label, id, tip, helpText, errorMessage, helpAdd
 ColorField.displayName = "ColorField";
 
 /**
- * The date field component is used for entering date values.
+ * The date field component is used for entering date values with a native date picker.
  *
- * _**Do use**_ the DateField for date input.
+ * ### When to use
+ * Use DateField for selecting calendar dates such as birthdates, deadlines, or scheduling.
  *
- * _**Do not use**_ this fields for non-serialized dates. Use TextField instead.
+ * ### When not to use
+ * Do not use DateField for non-serialized dates or free-form date text input. Use TextField instead.
+ *
+ * @example Basic date field
+ * ```tsx
+ * import { DateField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const MyForm = () => {
+ *   const [date, setDate] = useState("");
+ *
+ *   return (
+ *     <DateField
+ *       label="Start Date"
+ *       value={date}
+ *       onChange={(e) => setDate(e.target.value)}
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Date field with constraints
+ * ```tsx
+ * import { DateField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const BookingForm = () => {
+ *   const [checkIn, setCheckIn] = useState("");
+ *   const today = new Date().toISOString().split("T")[0];
+ *
+ *   return (
+ *     <DateField
+ *       label="Check-in Date"
+ *       value={checkIn}
+ *       onChange={(e) => setCheckIn(e.target.value)}
+ *       min={today}
+ *       helpText="Select a date from today onwards"
+ *       required
+ *     />
+ *   );
+ * };
+ * ```
  */
 const DateField = ({ label, id, tip, helpText, errorMessage, helpAddon, isInvalid, className, defaultValue, "data-testid": dataTestId, ref, ...rest }) => {
     const renderAsInvalid = isInvalid === undefined ? Boolean(errorMessage) : isInvalid;
@@ -2228,8 +2345,63 @@ const DropZoneDefaultLabel = () => (jsx(Trans, { components: {
     }, i18nKey: "dropzone.label.default", values: {} }));
 
 /**
- * The Drop Zone can be used to drag and drop files or to browse and select files from the file system.
+ * The `<DropZone>` component provides a drag-and-drop area for file uploads.
+ * Users can either drag files onto the zone or click to browse the file system.
+ *
+ * ### When to use
+ * - Drag-and-drop file upload experience
+ * - Batch file uploads
+ * - When visual feedback during drag is important
+ *
+ * ### When not to use
+ * - Simple single file uploads - use `UploadField` instead
+ * - When form field styling (label, help text) is needed - use `UploadField`
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { DropZone } from "@trackunit/react-form-components";
+ *
+ * <DropZone
+ *   filesSelected={(files) => handleFiles(files)}
+ *   accept="image/*"
+ * />
+ * ```
+ * @example With custom label
+ * ```tsx
+ * import { DropZone } from "@trackunit/react-form-components";
  *
+ * <DropZone
+ *   filesSelected={(files) => handleFiles(files)}
+ *   label={
+ *     <span>
+ *       <strong>Drop files here</strong> or click to browse
+ *     </span>
+ *   }
+ *   accept=".pdf,.doc,.docx"
+ * />
+ * ```
+ * @example Multiple files with size options
+ * ```tsx
+ * import { DropZone } from "@trackunit/react-form-components";
+ *
+ * <DropZone
+ *   filesSelected={(files) => {
+ *     Array.from(files).forEach(file => uploadFile(file));
+ *   }}
+ *   multiple
+ *   size="medium"
+ *   accept="image/png,image/jpeg"
+ * />
+ * ```
+ * @example Disabled state
+ * ```tsx
+ * import { DropZone } from "@trackunit/react-form-components";
+ *
+ * <DropZone
+ *   filesSelected={(files) => handleFiles(files)}
+ *   disabled={isUploading}
+ * />
+ * ```
  * @param {DropZoneProps} props - The props for the DropZone component
  * @returns {ReactElement} DropZone component
  */
@@ -2341,9 +2513,53 @@ const EmailBaseInput = ({ fieldSize = "medium", disabled = false, "data-testid":
 };
 
 /**
- * The EmailField component is used to enter email.
- * EmailField validates that user enters a valid email address.
+ * The `<EmailField>` component is used to enter and validate email addresses.
+ * It automatically validates the format on blur and displays appropriate error messages.
+ *
+ * ### When to use
+ * - Collecting user email addresses in forms
+ * - Contact forms that require email validation
+ * - Any input that must be a valid email format
+ *
+ * ### When not to use
+ * - For general text input - use `TextField` instead
+ * - For URLs - use `UrlField` instead
+ * - For phone numbers - use `PhoneField` instead
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { EmailField } from "@trackunit/react-form-components";
+ *
+ * const [email, setEmail] = useState("");
+ *
+ * <EmailField
+ *   label="Email Address"
+ *   value={email}
+ *   onChange={(e) => setEmail(e.target.value)}
+ *   required
+ * />
+ * ```
+ * @example With help text
+ * ```tsx
+ * import { EmailField } from "@trackunit/react-form-components";
+ *
+ * <EmailField
+ *   label="Work Email"
+ *   helpText="We'll use this to send notifications"
+ *   placeholder="name@company.com"
+ * />
+ * ```
+ * @example With custom error message
+ * ```tsx
+ * import { EmailField } from "@trackunit/react-form-components";
  *
+ * <EmailField
+ *   label="Email"
+ *   value={email}
+ *   onChange={(e) => setEmail(e.target.value)}
+ *   errorMessage={isEmailTaken ? "This email is already registered" : undefined}
+ * />
+ * ```
  */
 const EmailField = ({ label, id, tip, helpText, errorMessage, helpAddon, className, defaultValue, "data-testid": dataTestId, value, onChange, onBlur, isInvalid = false, ref, ...rest }) => {
     const htmlForId = id ? id : "emailField-" + uuidv4();
@@ -2452,9 +2668,63 @@ const FormFieldSelectAdapterMulti = (props) => {
 };
 
 /**
- * MultiSelectField is a custom Select component wrapped in the FormGroup component
- * that allows you to select multiple options from a list.
+ * The `<MultiSelectField>` component allows selecting multiple options from a dropdown list.
+ * It wraps the select input with FormGroup for consistent form styling including label,
+ * help text, and validation.
+ *
+ * ### When to use
+ * - Selecting multiple items from a predefined list (tags, categories, permissions)
+ * - When users need to see and manage all selected items
+ * - Filtering by multiple criteria
+ *
+ * ### When not to use
+ * - Single selection - use `SelectField` instead
+ * - Very long lists - consider a searchable/async variant
+ * - Binary choices - use `Checkbox` or `ToggleSwitchOption` instead
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { MultiSelectField } from "@trackunit/react-form-components";
+ *
+ * const options = [
+ *   { value: "read", label: "Read" },
+ *   { value: "write", label: "Write" },
+ *   { value: "delete", label: "Delete" },
+ * ];
+ *
+ * <MultiSelectField
+ *   label="Permissions"
+ *   options={options}
+ *   value={selectedPermissions}
+ *   onChange={(selected) => setSelectedPermissions(selected)}
+ * />
+ * ```
+ * @example With placeholder and help text
+ * ```tsx
+ * import { MultiSelectField } from "@trackunit/react-form-components";
+ *
+ * <MultiSelectField
+ *   label="Categories"
+ *   options={categoryOptions}
+ *   value={selectedCategories}
+ *   onChange={(selected) => setSelectedCategories(selected)}
+ *   placeholder="Select categories..."
+ *   helpText="Select all that apply"
+ * />
+ * ```
+ * @example With validation
+ * ```tsx
+ * import { MultiSelectField } from "@trackunit/react-form-components";
  *
+ * <MultiSelectField
+ *   label="Required Tags"
+ *   options={tagOptions}
+ *   value={selectedTags}
+ *   onChange={(selected) => setSelectedTags(selected)}
+ *   required
+ *   errorMessage={selectedTags.length === 0 ? "Select at least one tag" : undefined}
+ * />
+ * ```
  * @param {MultiSelectFieldProps} props - The props for the MultiSelectField component
  * @returns {ReactElement} MultiSelectField component
  */
@@ -2516,9 +2786,53 @@ const validateNumber = (number, required = false, min, max) => {
 /**
  * The number field component is used for entering numeric values and includes controls for incrementally increasing or decreasing the value.
  *
- * _**Do use**_ the NumberField when the controls to incrementally increase or decrease makes the task easier for the user.
+ * ### When to use
+ * Use NumberField when the controls to incrementally increase or decrease makes the task easier for the user, such as quantity selectors or numeric settings.
  *
- * _**Do not use**_ this fields for non-serialized numbers. Use TextField instead.
+ * ### When not to use
+ * Do not use NumberField for non-serialized numbers or IDs. Use TextField instead.
+ *
+ * @example Basic number field
+ * ```tsx
+ * import { NumberField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const MyForm = () => {
+ *   const [quantity, setQuantity] = useState(1);
+ *
+ *   return (
+ *     <NumberField
+ *       label="Quantity"
+ *       value={quantity}
+ *       onChange={(e) => setQuantity(Number(e.target.value))}
+ *       min={1}
+ *       max={100}
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Number field with validation
+ * ```tsx
+ * import { NumberField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const TemperatureInput = () => {
+ *   const [temp, setTemp] = useState(20);
+ *
+ *   return (
+ *     <NumberField
+ *       label="Temperature (°C)"
+ *       value={temp}
+ *       onChange={(e) => setTemp(Number(e.target.value))}
+ *       min={-40}
+ *       max={60}
+ *       step={0.5}
+ *       helpText="Enter a value between -40 and 60"
+ *       required
+ *     />
+ *   );
+ * };
+ * ```
  */
 const NumberField = ({ label, id, tip, helpText, errorMessage, helpAddon, isInvalid, maxLength, className, value, "data-testid": dataTestId, defaultValue, onBlur, onChange, ref, ...rest }) => {
     const htmlForId = id ? id : "numberField-" + uuidv4();
@@ -2665,11 +2979,60 @@ const PasswordBaseInput = ({ ref, fieldSize, ...rest }) => {
 };
 
 /**
- * Password fields enter a password or other confidential information. Characters are masked as they are typed.
+ * The `<PasswordField>` component is used to enter passwords or other confidential information.
+ * Characters are masked as they are typed, with an option to toggle visibility.
+ *
+ * ### When to use
+ * - Password input for login or registration forms
+ * - Entering sensitive data that should be obfuscated (API keys, secrets)
+ * - Any confidential text input
+ *
+ * ### When not to use
+ * - Confirming user actions like deletion - use a Checkbox instead
+ * - Non-sensitive text input - use `TextField` instead
+ * - PIN codes - consider a specialized PIN input
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { PasswordField } from "@trackunit/react-form-components";
+ *
+ * const [password, setPassword] = useState("");
  *
- * _**Do use** when the user has to input a password or something that needs to be obfuscated_
+ * <PasswordField
+ *   label="Password"
+ *   value={password}
+ *   onChange={(e) => setPassword(e.target.value)}
+ *   required
+ * />
+ * ```
+ * @example With validation
+ * ```tsx
+ * import { PasswordField } from "@trackunit/react-form-components";
  *
- * _**Do not use** to confirm user actions, such as deleting. Use a checkbox for such flows._
+ * <PasswordField
+ *   label="New Password"
+ *   value={password}
+ *   onChange={(e) => setPassword(e.target.value)}
+ *   helpText="Must be at least 8 characters"
+ *   errorMessage={password.length < 8 ? "Password too short" : undefined}
+ * />
+ * ```
+ * @example Confirm password pattern
+ * ```tsx
+ * import { PasswordField } from "@trackunit/react-form-components";
+ *
+ * <PasswordField
+ *   label="Password"
+ *   value={password}
+ *   onChange={(e) => setPassword(e.target.value)}
+ * />
+ * <PasswordField
+ *   label="Confirm Password"
+ *   value={confirmPassword}
+ *   onChange={(e) => setConfirmPassword(e.target.value)}
+ *   errorMessage={confirmPassword !== password ? "Passwords do not match" : undefined}
+ * />
+ * ```
  */
 const PasswordField = ({ id, label, tip, helpText, helpAddon, errorMessage, isInvalid, maxLength, onChange, className, value, "data-testid": dataTestId, ref, ...rest }) => {
     const renderAsInvalid = isInvalid === undefined ? Boolean(errorMessage) : isInvalid;
@@ -2732,19 +3095,52 @@ const phoneErrorMessage = (phoneNumber, required) => {
 };
 
 /**
- * The PhoneField component is used to enter phone number.
- * It is a wrapper around the PhoneInput component and the FormGroup component.
- * It is used to render a phone number field with a label, a tip, a help text, a help addon and an error message.
+ * The `<PhoneField>` component is used to enter and validate phone numbers.
+ * It includes built-in validation for phone number format and displays appropriate error messages.
  *
- * @param {string} [label] - The label for the component.
- * @param {string} [tip] - The tip for the component.
- * @param {string} [helpText] - The help text for the component.
- * @param {string} [helpAddon] - The help addon for the component.
- * @param {string} [errorMessage] - The error message for the component.
- * @param {string} [defaultValue] - The default value for the component.
- * @param {boolean} [disabled=false] - Whether the component is disabled or not.
- * @param {string} [fieldSize="medium"] - The size of the input field.
- * @param {boolean} [disableAction=false] - Whether the action button is disabled or not.
+ * ### When to use
+ * - Collecting phone numbers in contact forms
+ * - User profile phone number fields
+ * - Any input requiring phone number validation
+ *
+ * ### When not to use
+ * - General text input - use `TextField` instead
+ * - International phone with country selector - consider specialized international phone component
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { PhoneField } from "@trackunit/react-form-components";
+ *
+ * const [phone, setPhone] = useState("");
+ *
+ * <PhoneField
+ *   label="Phone Number"
+ *   value={phone}
+ *   onChange={(e) => setPhone(e.target.value)}
+ *   required
+ * />
+ * ```
+ * @example With help text
+ * ```tsx
+ * import { PhoneField } from "@trackunit/react-form-components";
+ *
+ * <PhoneField
+ *   label="Mobile Phone"
+ *   helpText="Include country code for international numbers"
+ *   placeholder="+1 555 123 4567"
+ * />
+ * ```
+ * @example With custom error handling
+ * ```tsx
+ * import { PhoneField } from "@trackunit/react-form-components";
+ *
+ * <PhoneField
+ *   label="Contact Phone"
+ *   value={phone}
+ *   onChange={(e) => setPhone(e.target.value)}
+ *   errorMessage={isPhoneDuplicate ? "This phone is already registered" : undefined}
+ * />
+ * ```
  */
 const PhoneField = ({ label, id, tip, helpText, isInvalid, errorMessage, value, helpAddon, className, defaultValue, "data-testid": dataTestId, name, onBlur, ref, ...rest }) => {
     const htmlForId = id ? id : "phoneField-" + uuidv4();
@@ -2862,10 +3258,57 @@ const RadioGroupContext = createContext(null);
  *
  * Radio buttons are used for mutually exclusive choices, not for multiple choices. Only one radio button can be selected at a time. When a user chooses a new item, the previous choice is automatically deselected.
  *
- * _**Do use** Radio buttons in forms, settings, or selections in a list._
+ * ### When to use
+ * Use RadioGroup in forms, settings, or selections in a list where only one option can be selected.
+ *
+ * ### When not to use
+ * Do not use RadioGroup if a user can select many options from a list. Use Checkbox instead.
+ *
+ * @example Basic radio group
+ * ```tsx
+ * import { RadioGroup, RadioItem } from "@trackunit/react-form-components";
+ * import { useState, ChangeEvent } from "react";
+ *
+ * const MyForm = () => {
+ *   const [size, setSize] = useState("medium");
+ *
+ *   return (
+ *     <RadioGroup
+ *       id="size-selection"
+ *       label="Select size"
+ *       value={size}
+ *       onChange={(e: ChangeEvent<HTMLInputElement>) => setSize(e.target.value)}
+ *     >
+ *       <RadioItem label="Small" value="small" />
+ *       <RadioItem label="Medium" value="medium" />
+ *       <RadioItem label="Large" value="large" />
+ *     </RadioGroup>
+ *   );
+ * };
+ * ```
+ * @example Inline radio group with descriptions
+ * ```tsx
+ * import { RadioGroup, RadioItem } from "@trackunit/react-form-components";
+ * import { useState, ChangeEvent } from "react";
  *
- * _**Do not use** Radio buttons if a user can select many option from a list, use checkboxes instead of radio buttons._
+ * const PlanSelector = () => {
+ *   const [plan, setPlan] = useState("basic");
  *
+ *   return (
+ *     <RadioGroup
+ *       id="plan-selection"
+ *       label="Choose your plan"
+ *       value={plan}
+ *       onChange={(e: ChangeEvent<HTMLInputElement>) => setPlan(e.target.value)}
+ *       inline
+ *     >
+ *       <RadioItem label="Basic" value="basic" description="$9/month" />
+ *       <RadioItem label="Pro" value="pro" description="$29/month" />
+ *       <RadioItem label="Enterprise" value="enterprise" description="Contact us" />
+ *     </RadioGroup>
+ *   );
+ * };
+ * ```
  * @param {RadioGroupProps} props - The props for the RadioGroup component
  * @returns {ReactElement} RadioGroup component
  */
@@ -3252,8 +3695,69 @@ const CreatableSelectField = ({ allowCreateWhileLoading = false, onCreateOption,
 CreatableSelectField.displayName = "CreatableSelectField";
 
 /**
- * MultiSelect is a custom Select component wrapped in the FormGroup component
+ * SelectField is a dropdown select component wrapped in the FormGroup component for selecting a single option from a list.
+ *
+ * ### When to use
+ * Use SelectField when users need to choose one option from a predefined list of 4 or more items.
+ *
+ * ### When not to use
+ * Do not use SelectField for fewer than 4 options. Use RadioGroup instead for better usability with small option sets.
+ *
+ * @example Basic select field
+ * ```tsx
+ * import { SelectField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const options = [
+ *   { value: "us", label: "United States" },
+ *   { value: "uk", label: "United Kingdom" },
+ *   { value: "de", label: "Germany" },
+ *   { value: "fr", label: "France" },
+ * ];
+ *
+ * const MyForm = () => {
+ *   const [country, setCountry] = useState<{ value: string; label: string } | null>(null);
+ *
+ *   return (
+ *     <SelectField
+ *       label="Country"
+ *       options={options}
+ *       value={country}
+ *       onChange={(option) => setCountry(option)}
+ *       placeholder="Select a country"
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Async select field with search
+ * ```tsx
+ * import { SelectField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const MyAsyncForm = () => {
+ *   const [selected, setSelected] = useState(null);
  *
+ *   const loadOptions = async (inputValue: string) => {
+ *     const response = await fetch(`/api/users?search=${inputValue}`);
+ *     const users = await response.json();
+ *     return users.map((user: { id: string; name: string }) => ({
+ *       value: user.id,
+ *       label: user.name,
+ *     }));
+ *   };
+ *
+ *   return (
+ *     <SelectField
+ *       label="Assign to user"
+ *       isAsync
+ *       loadOptions={loadOptions}
+ *       value={selected}
+ *       onChange={setSelected}
+ *       isClearable
+ *     />
+ *   );
+ * };
+ * ```
  * @param {SelectFieldProps} props - The props for the SelectField component
  */
 function SelectField({ ref, ...props }) {
@@ -3273,12 +3777,54 @@ const TextLengthIndicator = ({ length, maxLength }) => {
 };
 
 /**
- * Use a text area when you need to allow users to enter a large amount of text, such as a comment or a description.
+ * The `<TextAreaField>` component is used for multi-line text input.
+ * Use when you need to allow users to enter a large amount of text, such as comments or descriptions.
+ *
+ * ### When to use
+ * - Longer text inputs like comments, descriptions, or notes
+ * - When the expected input is more than one line
+ * - For free-form text that benefits from a larger input area
+ *
+ * ### When not to use
+ * - Single-line inputs - use `TextField` instead
+ * - Structured data like email or phone - use specialized field components
+ * - Rich text editing - consider a rich text editor component
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { TextAreaField } from "@trackunit/react-form-components";
  *
- * _**Do use** Text areas for larger text inputs, such as comments or descriptions._
+ * const [description, setDescription] = useState("");
  *
- * _**Do not use** Text areas for small text inputs, such as single-line inputs._
+ * <TextAreaField
+ *   label="Description"
+ *   value={description}
+ *   onChange={(e) => setDescription(e.target.value)}
+ *   placeholder="Enter a description..."
+ * />
+ * ```
+ * @example With character limit
+ * ```tsx
+ * import { TextAreaField } from "@trackunit/react-form-components";
+ *
+ * <TextAreaField
+ *   label="Comment"
+ *   maxLength={500}
+ *   helpText="Add any additional notes"
+ *   required
+ * />
+ * ```
+ * @example With validation error
+ * ```tsx
+ * import { TextAreaField } from "@trackunit/react-form-components";
  *
+ * <TextAreaField
+ *   label="Notes"
+ *   value={notes}
+ *   onChange={(e) => setNotes(e.target.value)}
+ *   errorMessage={notes.length < 10 ? "Notes must be at least 10 characters" : undefined}
+ * />
+ * ```
  * @param {TextAreaFieldProps} props - The props for the TextAreaField component
  * @returns {ReactElement} TextAreaField component
  */
@@ -3299,6 +3845,61 @@ TextAreaField.displayName = "TextAreaField";
 
 /**
  * Text fields enable the user to interact with and input content and data. This component can be used for long and short form entries. Allow the size of the text input box to reflect the length of the content you expect the user to enter.
+ *
+ * ### When to use
+ * Use text fields for short-form text input such as names, emails, or search queries.
+ *
+ * ### When not to use
+ * Do not use text fields for multi-line text input. Use TextAreaField instead.
+ *
+ * @example Basic text field
+ * ```tsx
+ * import { TextField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const MyForm = () => {
+ *   const [name, setName] = useState("");
+ *
+ *   return (
+ *     <TextField
+ *       label="Name"
+ *       value={name}
+ *       onChange={(e) => setName(e.target.value)}
+ *       placeholder="Enter your name"
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Text field with validation and help text
+ * ```tsx
+ * import { TextField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const MyForm = () => {
+ *   const [email, setEmail] = useState("");
+ *   const [error, setError] = useState<string | undefined>();
+ *
+ *   const handleBlur = () => {
+ *     if (!email.includes("@")) {
+ *       setError("Please enter a valid email address");
+ *     } else {
+ *       setError(undefined);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <TextField
+ *       label="Email"
+ *       value={email}
+ *       onChange={(e) => setEmail(e.target.value)}
+ *       onBlur={handleBlur}
+ *       errorMessage={error}
+ *       helpText="We'll never share your email"
+ *       required
+ *     />
+ *   );
+ * };
+ * ```
  */
 const TextField = ({ id, label, tip, helpText, helpAddon, errorMessage, isInvalid, maxLength, onChange, className, value, "data-testid": dataTestId, isWarning, ref, ...rest }) => {
     const [valueLength, setValueLength] = useState(value ? `${value}`.length : 0);
@@ -3401,11 +4002,55 @@ const cvaToggleSwitchThumb = cvaMerge(["block", "rounded-full", "bg-white", "asp
 });
 
 /**
- * A checkbox input wrapper with role="switch". Used as an input element for **ToggleSwitchOption**
- * or custom components.
+ * The `<ToggleSwitch>` is a low-level checkbox input wrapper with `role="switch"`.
+ * It renders just the switch control without label or description.
+ *
+ * **Not intended for standalone use** - use `ToggleSwitchOption` instead for forms.
+ * This component is for building custom toggle implementations or wrapping in other components.
+ *
+ * ### When to use
+ * - Building custom toggle components with different layouts
+ * - Integrating a toggle into a component that provides its own label (e.g., menu items)
+ * - Creating specialized switch controls
+ *
+ * ### When not to use
+ * - Standard forms - use `ToggleSwitchOption` instead (includes label/description)
+ * - Multiple selections - use `Checkbox` components instead
+ *
+ * @example Basic usage (in custom component)
+ * ```tsx
+ * import { ToggleSwitch } from "@trackunit/react-form-components";
  *
- * Not intended for standalone use.
+ * const [isEnabled, setIsEnabled] = useState(false);
+ *
+ * <ToggleSwitch
+ *   toggled={isEnabled}
+ *   onChange={(toggled) => setIsEnabled(toggled)}
+ * />
+ * ```
+ * @example Inside a custom wrapper
+ * ```tsx
+ * import { ToggleSwitch } from "@trackunit/react-form-components";
+ *
+ * <div className="flex items-center gap-2">
+ *   <span>Dark Mode</span>
+ *   <ToggleSwitch
+ *     toggled={darkMode}
+ *     onChange={(toggled) => setDarkMode(toggled)}
+ *     size="small"
+ *   />
+ * </div>
+ * ```
+ * @example Disabled state
+ * ```tsx
+ * import { ToggleSwitch } from "@trackunit/react-form-components";
  *
+ * <ToggleSwitch
+ *   toggled={true}
+ *   onChange={() => {}}
+ *   disabled
+ * />
+ * ```
  * @param {ToggleSwitchProps} props - The props for the ToggleSwitch component
  * @returns {ReactElement} ToggleSwitch component
  */
@@ -3452,13 +4097,65 @@ const ToggleSwitch = forwardRef(({ onChange, onClick, preventDefaultOnClick, cla
 ToggleSwitch.displayName = "ToggleSwitch";
 
 /**
- * Use ToggleSwitchOption when you have to only enable/disable a feature.
- * Wrapper component for ToggleSwitch.
+ * The `<ToggleSwitchOption>` component is used for binary on/off settings in forms.
+ * It combines a toggle switch with a label and optional description for complete form integration.
+ *
+ * ### When to use
+ * - Enable/disable feature toggles in settings
+ * - Binary choices where the action takes effect immediately
+ * - Preferences that represent on/off states
+ *
+ * ### When not to use
+ * - Multiple selections from a list - use `Checkbox` components instead
+ * - Mutually exclusive options - use `RadioGroup` instead
+ * - Actions requiring confirmation - use buttons with confirmation dialog
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { ToggleSwitchOption } from "@trackunit/react-form-components";
+ *
+ * const [notifications, setNotifications] = useState(true);
  *
- * _**Do use** ToggleSwitchOption in forms or settings._
+ * <ToggleSwitchOption
+ *   id="notifications"
+ *   label="Enable Notifications"
+ *   toggled={notifications}
+ *   onChange={(toggled) => setNotifications(toggled)}
+ * />
+ * ```
+ * @example With description
+ * ```tsx
+ * import { ToggleSwitchOption } from "@trackunit/react-form-components";
  *
- * _**Do not use** ToggleSwitchOption if a user can select multiple options from a list, use checkboxes instead of toggle._
+ * <ToggleSwitchOption
+ *   id="email-alerts"
+ *   label="Email Alerts"
+ *   description="Receive email notifications for important updates"
+ *   toggled={emailAlerts}
+ *   onChange={(toggled) => setEmailAlerts(toggled)}
+ * />
+ * ```
+ * @example In a settings list
+ * ```tsx
+ * import { ToggleSwitchOption } from "@trackunit/react-form-components";
  *
+ * <div className="space-y-4">
+ *   <ToggleSwitchOption
+ *     id="dark-mode"
+ *     label="Dark Mode"
+ *     description="Use dark theme throughout the application"
+ *     toggled={darkMode}
+ *     onChange={(toggled) => setDarkMode(toggled)}
+ *   />
+ *   <ToggleSwitchOption
+ *     id="auto-save"
+ *     label="Auto-save"
+ *     description="Automatically save changes as you type"
+ *     toggled={autoSave}
+ *     onChange={(toggled) => setAutoSave(toggled)}
+ *   />
+ * </div>
+ * ```
  * @param {ToggleSwitchOptionProps} props - The props for the ToggleSwitchOption component
  * @returns {ReactElement} ToggleSwitchOption component
  */
@@ -3498,7 +4195,53 @@ const UploadInput = ({ disabled, acceptedTypes, nonInteractive, uploadLabel, mul
 UploadInput.displayName = "UploadInput";
 
 /**
- * Upload fields enable the user to upload Files.
+ * The `<UploadField>` component enables users to upload files through a form field.
+ * It wraps the UploadInput with FormGroup for consistent form styling including label,
+ * help text, and error handling.
+ *
+ * ### When to use
+ * - Single file upload in forms (documents, images)
+ * - When you need form field styling (label, validation messages)
+ * - File attachments in form submissions
+ *
+ * ### When not to use
+ * - Drag and drop file uploads - use `DropZone` instead
+ * - Multiple file uploads with preview - consider specialized upload component
+ * - Large file uploads requiring progress indication
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { UploadField } from "@trackunit/react-form-components";
+ *
+ * <UploadField
+ *   label="Upload Document"
+ *   accept=".pdf,.doc,.docx"
+ *   onChange={(file) => handleFileUpload(file)}
+ * />
+ * ```
+ * @example With validation
+ * ```tsx
+ * import { UploadField } from "@trackunit/react-form-components";
+ *
+ * <UploadField
+ *   label="Profile Picture"
+ *   accept="image/*"
+ *   helpText="Max file size: 5MB"
+ *   errorMessage={fileTooLarge ? "File exceeds 5MB limit" : undefined}
+ *   required
+ * />
+ * ```
+ * @example In a form context
+ * ```tsx
+ * import { UploadField } from "@trackunit/react-form-components";
+ *
+ * <UploadField
+ *   label="Attachment"
+ *   tip="Optional supporting document"
+ *   accept=".pdf"
+ *   onChange={(file) => setAttachment(file)}
+ * />
+ * ```
  */
 const UploadField = ({ label, id, tip, helpText, errorMessage, isInvalid, className, value, "data-testid": dataTestId, ref, ...rest }) => {
     const renderAsInvalid = isInvalid || Boolean(errorMessage);
@@ -3550,9 +4293,53 @@ const UrlBaseInput = ({ isInvalid = false, "data-testid": dataTestId, disabled =
 };
 
 /**
- * The UrlField component is used to enter url.
- * UrlField validates that user enters a valid web address.
+ * The `<UrlField>` component is used to enter and validate URLs/web addresses.
+ * It automatically validates the format on blur and displays appropriate error messages.
+ *
+ * ### When to use
+ * - Collecting website URLs in forms
+ * - Social media profile links
+ * - Any input requiring valid URL format
  *
+ * ### When not to use
+ * - General text input - use `TextField` instead
+ * - Email addresses - use `EmailField` instead
+ * - Internal application links - use standard link/routing
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { UrlField } from "@trackunit/react-form-components";
+ *
+ * const [website, setWebsite] = useState("");
+ *
+ * <UrlField
+ *   label="Website"
+ *   value={website}
+ *   onChange={(e) => setWebsite(e.target.value)}
+ *   placeholder="https://example.com"
+ * />
+ * ```
+ * @example With help text
+ * ```tsx
+ * import { UrlField } from "@trackunit/react-form-components";
+ *
+ * <UrlField
+ *   label="Company Website"
+ *   helpText="Enter the full URL including https://"
+ *   required
+ * />
+ * ```
+ * @example With custom validation
+ * ```tsx
+ * import { UrlField } from "@trackunit/react-form-components";
+ *
+ * <UrlField
+ *   label="Documentation URL"
+ *   value={docUrl}
+ *   onChange={(e) => setDocUrl(e.target.value)}
+ *   errorMessage={!docUrl.includes("docs") ? "URL must point to documentation" : undefined}
+ * />
+ * ```
  */
 const UrlField = ({ label, id, tip, helpText, errorMessage, helpAddon, className, defaultValue, "data-testid": dataTestId, isInvalid = false, value, onBlur, ref, ...rest }) => {
     const htmlForId = id ? id : "urlField-" + uuidv4();