@trackunit/react-form-components 1.11.17 → 1.11.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-form-components",
-  "version": "1.11.17",
+  "version": "1.11.19",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,12 +14,12 @@
     "zod": "^3.23.8",
     "react-hook-form": "7.62.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/css-class-variance-utilities": "1.10.14",
-    "@trackunit/react-components": "1.14.17",
-    "@trackunit/ui-icons": "1.10.14",
-    "@trackunit/shared-utils": "1.12.14",
-    "@trackunit/ui-design-tokens": "1.10.14",
-    "@trackunit/i18n-library-translation": "1.10.14",
+    "@trackunit/css-class-variance-utilities": "1.10.16",
+    "@trackunit/react-components": "1.14.19",
+    "@trackunit/ui-icons": "1.10.16",
+    "@trackunit/shared-utils": "1.12.16",
+    "@trackunit/ui-design-tokens": "1.10.16",
+    "@trackunit/i18n-library-translation": "1.10.16",
     "string-ts": "^2.0.0",
     "@js-temporal/polyfill": "^0.5.1",
     "es-toolkit": "^1.39.10",

package/src/components/Checkbox/Checkbox.d.ts

@@ -45,10 +45,54 @@ export interface CheckboxProps extends CommonProps, MappedOmit<InputHTMLAttribut
  *
  * 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

package/src/components/ColorField/ColorField.d.ts

@@ -17,9 +17,41 @@ export interface ColorFieldProps extends FormGroupExposedProps, ColorFieldBaseIn
     errorMessage?: string;
 }
 /**
- * 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
+ * />
+ * ```
  */
 export declare const ColorField: import("react").ForwardRefExoticComponent<Omit<ColorFieldProps, "ref"> & import("react").RefAttributes<HTMLInputElement>>;
 export {};

package/src/components/DateField/DateField.d.ts

@@ -13,11 +13,52 @@ export interface DateFieldProps extends DateBaseInputProps, FormGroupExposedProp
     ref?: Ref<HTMLInputElement>;
 }
 /**
- * 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
+ *     />
+ *   );
+ * };
+ * ```
  */
 export declare const DateField: {
     ({ label, id, tip, helpText, errorMessage, helpAddon, isInvalid, className, defaultValue, "data-testid": dataTestId, ref, ...rest }: DateFieldProps): import("react/jsx-runtime").JSX.Element;

package/src/components/DropZone/DropZone.d.ts

@@ -25,8 +25,63 @@ export interface DropZoneProps extends BaseInputExposedProps, CommonProps {
     filesSelected: (file: FileList) => void;
 }
 /**
- * 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
  */

package/src/components/EmailField/EmailField.d.ts

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

package/src/components/MultiSelectField/MultiSelectField.d.ts

@@ -3,9 +3,63 @@ import { GroupBase } from "react-select";
 import { BaseOptionType } from "../SelectField/FormFieldSelectAdapter";
 import { MultiSelectFieldProps } from "./FormFieldSelectAdapterMulti";
 /**
- * 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
  */

package/src/components/NumberField/NumberField.d.ts

@@ -15,9 +15,53 @@ export interface NumberFieldProps extends NumberBaseInputProps, FormGroupExposed
 /**
  * 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
+ *     />
+ *   );
+ * };
+ * ```
  */
 export declare const NumberField: {
     ({ label, id, tip, helpText, errorMessage, helpAddon, isInvalid, maxLength, className, value, "data-testid": dataTestId, defaultValue, onBlur, onChange, ref, ...rest }: NumberFieldProps): import("react/jsx-runtime").JSX.Element;

package/src/components/PasswordField/PasswordField.d.ts

@@ -13,11 +13,60 @@ export interface PasswordFieldProps extends Omit<PasswordBaseInputProps, "obfusc
     ref?: Ref<HTMLInputElement>;
 }
 /**
- * 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.
  *
- * _**Do use** when the user has to input a password or something that needs to be obfuscated_
+ * ### When to use
+ * - Password input for login or registration forms
+ * - Entering sensitive data that should be obfuscated (API keys, secrets)
+ * - Any confidential text input
  *
- * _**Do not use** to confirm user actions, such as deleting. Use a checkbox for such flows._
+ * ### 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("");
+ *
+ * <PasswordField
+ *   label="Password"
+ *   value={password}
+ *   onChange={(e) => setPassword(e.target.value)}
+ *   required
+ * />
+ * ```
+ * @example With validation
+ * ```tsx
+ * import { PasswordField } from "@trackunit/react-form-components";
+ *
+ * <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}
+ * />
+ * ```
  */
 export declare const PasswordField: {
     ({ id, label, tip, helpText, helpAddon, errorMessage, isInvalid, maxLength, onChange, className, value, "data-testid": dataTestId, ref, ...rest }: PasswordFieldProps): import("react/jsx-runtime").JSX.Element;

package/src/components/PhoneField/PhoneField.d.ts

@@ -13,19 +13,52 @@ export interface PhoneFieldProps extends FormGroupExposedProps, PhoneBaseInputPr
     ref?: Ref<HTMLInputElement>;
 }
 /**
- * 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}
+ * />
+ * ```
  */
 export declare const PhoneField: {
     ({ label, id, tip, helpText, isInvalid, errorMessage, value, helpAddon, className, defaultValue, "data-testid": dataTestId, name, onBlur, ref, ...rest }: PhoneFieldProps): import("react/jsx-runtime").JSX.Element;

package/src/components/RadioGroup/RadioGroup.d.ts

@@ -43,10 +43,57 @@ export interface RadioGroupProps<TValue extends string | number> extends CommonP
  *
  * 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.
  *
- * _**Do not use** Radio buttons if a user can select many option from a list, use checkboxes instead of radio buttons._
+ * ### 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";
+ *
+ * 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
  */