@trackunit/react-form-components 1.11.18 → 1.11.20

package/src/components/SelectField/SelectField.d.ts

@@ -1,8 +1,69 @@
 import { ReactElement } from "react";
 import { BaseOptionType, SelectFieldProps } from "./FormFieldSelectAdapter";
 /**
- * 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
  */
 export declare function SelectField<TOption extends BaseOptionType, TIsAsync extends boolean = false>({ ref, ...props }: SelectFieldProps<TOption, TIsAsync>): ReactElement;

package/src/components/TextAreaField/TextAreaField.d.ts

@@ -19,12 +19,54 @@ export interface TextAreaFieldProps extends TextAreaBaseInputProps, FormGroupExp
     ref?: Ref<HTMLTextAreaElement>;
 }
 /**
- * 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.
  *
- * _**Do use** Text areas for larger text inputs, 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
  *
- * _**Do not use** Text areas for small text inputs, such as single-line inputs._
+ * ### 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";
+ *
+ * const [description, setDescription] = useState("");
+ *
+ * <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
  */

package/src/components/TextField/TextField.d.ts

@@ -14,6 +14,61 @@ export interface TextFieldProps extends TextBaseInputProps, FormGroupExposedProp
 }
 /**
  * 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
+ *     />
+ *   );
+ * };
+ * ```
  */
 export declare const TextField: {
     ({ id, label, tip, helpText, helpAddon, errorMessage, isInvalid, maxLength, onChange, className, value, "data-testid": dataTestId, isWarning, ref, ...rest }: TextFieldProps): import("react/jsx-runtime").JSX.Element;

package/src/components/ToggleSwitch/ToggleSwitch.d.ts

@@ -40,11 +40,55 @@ export interface ToggleSwitchProps extends CommonProps, MappedOmit<InputHTMLAttr
     preventDefaultOnClick?: boolean;
 }
 /**
- * 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.
+ * **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";
+ *
+ * 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
  */

package/src/components/ToggleSwitchOption/ToggleSwitchOption.d.ts

@@ -15,13 +15,65 @@ export interface ToggleSwitchOptionProps extends ToggleSwitchProps {
     suffix?: ReactElement;
 }
 /**
- * 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.
  *
- * _**Do use** ToggleSwitchOption in forms or settings._
+ * ### When to use
+ * - Enable/disable feature toggles in settings
+ * - Binary choices where the action takes effect immediately
+ * - Preferences that represent on/off states
  *
- * _**Do not use** ToggleSwitchOption if a user can select multiple options from a list, use checkboxes instead of toggle._
+ * ### 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);
+ *
+ * <ToggleSwitchOption
+ *   id="notifications"
+ *   label="Enable Notifications"
+ *   toggled={notifications}
+ *   onChange={(toggled) => setNotifications(toggled)}
+ * />
+ * ```
+ * @example With description
+ * ```tsx
+ * import { ToggleSwitchOption } from "@trackunit/react-form-components";
+ *
+ * <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
  */

package/src/components/UploadField/UploadField.d.ts

@@ -8,7 +8,53 @@ export interface UploadFieldProps extends UploadInputProps, FormGroupExposedProp
     errorMessage?: string;
 }
 /**
- * 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)}
+ * />
+ * ```
  */
 export declare const UploadField: {
     ({ label, id, tip, helpText, errorMessage, isInvalid, className, value, "data-testid": dataTestId, ref, ...rest }: UploadFieldProps): import("react/jsx-runtime").JSX.Element;

package/src/components/UrlField/UrlField.d.ts

@@ -8,9 +8,53 @@ export interface UrlFieldProps extends FormGroupExposedProps, UrlBaseInputProps
     errorMessage?: string;
 }
 /**
- * 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}
+ * />
+ * ```
  */
 export declare const UrlField: {
     ({ label, id, tip, helpText, errorMessage, helpAddon, className, defaultValue, "data-testid": dataTestId, isInvalid, value, onBlur, ref, ...rest }: UrlFieldProps): import("react/jsx-runtime").JSX.Element;