@trackunit/react-form-components 1.14.25 → 1.14.27

package/index.cjs.js

@@ -2013,8 +2013,16 @@ const CreatableSelect = (props) => {
 };
 
 /**
- * The Label component is used for labels for input fields.
- * This component is **not used directly**, but is part of the FormGroup and Field components.
+ * Label renders a styled `<label>` element for form input fields.
+ * This component is typically **not used directly** — it is rendered internally by `FormGroup` and
+ * all Field components (e.g., `TextField`, `CheckboxField`, `TimeRangeField`). Use it only when
+ * building a custom form group layout that cannot use `FormGroup`.
+ *
+ * ### When to use
+ * Use Label only when constructing a custom form field wrapper that cannot use `FormGroup`.
+ *
+ * ### When not to use
+ * Do not use Label directly for standard form fields — use the appropriate Field component (e.g., `TextField`, `CheckboxField`) which includes Label automatically.
  *
  * @param {LabelProps} props - The props for the Label component
  * @returns {ReactElement} Label component
@@ -2047,9 +2055,27 @@ const cvaFormGroupContainerAfter = cssClassVarianceUtilities.cvaMerge(["flex", "
 const cvaHelpAddon = cssClassVarianceUtilities.cvaMerge(["ml-auto"]);
 
 /**
- * The FormGroup component should be used to wrap any Input element that needs a label.
- * Besides a label the component supplies an optional Tooltip, HelpText and HelpAddon support.
+ * FormGroup wraps an input element with a label, optional tooltip, help text, and validation styling.
+ * It provides consistent form field layout and is used internally by all Field components
+ * (`TextField`, `CheckboxField`, `TimeRangeField`, etc.).
+ *
+ * ### When to use
+ * Use FormGroup when building a custom field component that needs a label, tooltip, or help text.
  *
+ * ### When not to use
+ * Do not use FormGroup directly for standard inputs — use the corresponding Field component
+ * (e.g., `TextField`, `CheckboxField`) which already wraps FormGroup.
+ *
+ * @example Custom field with label, tooltip, and help text
+ * ```tsx
+ * import { FormGroup } from "@trackunit/react-form-components";
+ *
+ * const CustomColorField = () => (
+ *   <FormGroup label="Brand color" tip="Used across the dashboard" helpText="Enter a hex color code">
+ *     <input type="color" />
+ *   </FormGroup>
+ * );
+ * ```
  * @param {FormGroupProps} props - The props for the FormGroup component
  * @returns {ReactElement} FormGroup component
  */
@@ -2063,9 +2089,34 @@ const FormGroup = ({ isInvalid = false, isWarning = false, helpText, helpAddon,
 };
 
 /**
- * The checkbox field component is used for entering boolean values.
+ * CheckboxField is a form-ready checkbox that wraps a `Checkbox` inside a `FormGroup`.
+ * It provides a labeled checkbox with support for tooltips, help text, validation, and form group styling.
  *
- * _**Do use**_ the CheckboxField for boolean input.
+ * ### When to use
+ * Use CheckboxField for boolean inputs inside forms — for example, "I agree to terms" or toggling a feature on/off.
+ *
+ * ### When not to use
+ * Do not use CheckboxField for multi-select lists — use checkbox filters or a select component.
+ * For a standalone checkbox without form group wrapping, use `Checkbox` directly.
+ *
+ * @example Checkbox field in a form
+ * ```tsx
+ * import { CheckboxField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const TermsCheckbox = () => {
+ *   const [accepted, setAccepted] = useState(false);
+ *   return (
+ *     <CheckboxField
+ *       label="Terms and Conditions"
+ *       checkboxLabel="I accept the terms"
+ *       checked={accepted}
+ *       onChange={() => setAccepted(!accepted)}
+ *     />
+ *   );
+ * };
+ * ```
+ * @param {CheckboxFieldProps} props - The props for the CheckboxField component
  */
 const CheckboxField = ({ label, id, tip, helpText, helpAddon, isInvalid, className, checked, "data-testid": dataTestId, checkboxLabel, onChange, ref, ...rest }) => {
     const htmlForId = id ? id : "checkboxField-" + sharedUtils.uuidv4();
@@ -3185,8 +3236,33 @@ const PhoneField = ({ label, id, tip, helpText, isInvalid, errorMessage, value,
 PhoneField.displayName = "PhoneField";
 
 /**
- * The PhoneFieldWithController component is a wrapper for the PhoneField component to connect it to react-hook-form.
+ * PhoneFieldWithController wraps `PhoneField` with a `react-hook-form` `Controller`,
+ * connecting the phone number input to form state management. It handles value synchronization,
+ * validation integration, and default value assignment automatically.
  *
+ * ### When to use
+ * Use PhoneFieldWithController when you have a phone number field inside a `react-hook-form` managed form.
+ *
+ * ### When not to use
+ * Do not use PhoneFieldWithController outside of `react-hook-form` — use `PhoneField` directly.
+ *
+ * @example Phone field in a react-hook-form
+ * ```tsx
+ * import { PhoneFieldWithController } from "@trackunit/react-form-components";
+ * import { useForm } from "react-hook-form";
+ *
+ * const ContactForm = () => {
+ *   const { control } = useForm();
+ *   return (
+ *     <PhoneFieldWithController
+ *       control={control}
+ *       name="phone"
+ *       label="Phone number"
+ *     />
+ *   );
+ * };
+ * ```
+ * @param {PhoneFieldWithControllerProps} props - The props for the PhoneFieldWithController component
  */
 const PhoneFieldWithController = ({ control, controllerProps, name, value, ref, ...rest }) => {
     return (jsxRuntime.jsx(reactHookForm.Controller, { control: control, defaultValue: value, name: name, ...controllerProps, render: ({ field }) => jsxRuntime.jsx(PhoneField, { ...rest, ...field, ref: ref }) }));
@@ -3376,8 +3452,26 @@ const cvaTimeRange = cssClassVarianceUtilities.cvaMerge([
 ]);
 
 /**
- * TimeRange is used to create a time range entry.
+ * TimeRange renders a pair of native `<input type="time">` fields for selecting a start and end time.
+ * It provides a controlled time range with `onChange` callback and supports custom separators, disabled state, and validation styling.
  *
+ * ### When to use
+ * Use TimeRange for bare time range inputs inside custom layouts or composed components (e.g., inside Schedule rows).
+ *
+ * ### When not to use
+ * Do not use TimeRange directly in forms that need a label, help text, or validation — use `TimeRangeField` instead.
+ *
+ * @example Basic time range input
+ * ```tsx
+ * import { TimeRange } from "@trackunit/react-form-components";
+ *
+ * const ShiftPicker = () => (
+ *   <TimeRange
+ *     range={{ timeFrom: "09:00", timeTo: "17:00" }}
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {TimeRangeProps} props - The props for the TimeRange component
  * @returns {ReactElement} TimeRange component
  */
@@ -3407,8 +3501,31 @@ const cvaScheduleItem = cssClassVarianceUtilities.cvaMerge([
 const cvaScheduleItemText = cssClassVarianceUtilities.cvaMerge(["flex", "font-bold", "self-center"]);
 
 /**
- * Schedule is used to create a time range entries.
+ * Schedule renders a weekly time-range editor where each row represents a day with an active toggle,
+ * an optional all-day checkbox, and a start/end time range. It is used for defining recurring schedules
+ * such as operating hours, service windows, or geofence active periods.
  *
+ * ### When to use
+ * Use Schedule when users need to configure per-day time ranges — for example, setting working hours for each day of the week.
+ *
+ * ### When not to use
+ * Do not use Schedule for a single time range — use `TimeRangeField`.
+ * Do not use it for date range selection — use `DayRangePicker`.
+ *
+ * @example Weekly operating hours schedule
+ * ```tsx
+ * import { Schedule, ScheduleItem } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const OperatingHours = () => {
+ *   const [schedule, setSchedule] = useState<Array<ScheduleItem>>([
+ *     { key: "mon", label: "Monday", isActive: true, range: { timeFrom: "08:00", timeTo: "17:00" } },
+ *     { key: "tue", label: "Tuesday", isActive: true, range: { timeFrom: "08:00", timeTo: "17:00" } },
+ *     { key: "wed", label: "Wednesday", isActive: false, range: { timeFrom: "", timeTo: "" } },
+ *   ]);
+ *   return <Schedule schedule={schedule} onChange={setSchedule} />;
+ * };
+ * ```
  * @param {ScheduleProps} props - The props for the Schedule component
  * @returns {ReactElement} Schedule component
  */
@@ -3598,9 +3715,44 @@ const cvaSearch = cssClassVarianceUtilities.cvaMerge([
 });
 
 /**
- * The Search component is used to render a search input field.
+ * Search renders a styled search input with a magnifying glass icon, an optional loading spinner,
+ * and a clear button that appears when a value is present. It supports visual variants such as
+ * widening on focus and hiding the border when not focused.
+ *
+ * ### When to use
+ * Use Search for filtering or querying data sets — for example, a search box above a table or list to narrow down results.
+ *
+ * ### When not to use
+ * Do not use Search for multi-filter scenarios — use `FilterBar`.
+ * Do not use it as a general text input — use `TextField`.
+ *
+ * @example Basic search input with change handler
+ * ```tsx
+ * import { Search } from "@trackunit/react-form-components";
+ * import { useState, ChangeEvent } from "react";
+ *
+ * const AssetSearch = () => {
+ *   const [query, setQuery] = useState("");
+ *   return (
+ *     <Search
+ *       value={query}
+ *       onChange={(e: ChangeEvent<HTMLInputElement>) => setQuery(e.target.value)}
+ *       onClear={() => setQuery("")}
+ *       placeholder="Search assets..."
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Compact search that widens on focus
+ * ```tsx
+ * import { Search } from "@trackunit/react-form-components";
  *
+ * const CompactSearch = () => (
+ *   <Search widenInputOnFocus hideBorderWhenNotInFocus placeholder="Search..." />
+ * );
+ * ```
  * @param {SearchProps} props - The props for the Search component
+ * @returns {ReactElement} Search component
  */
 const Search = ({ className, placeholder, value, widenInputOnFocus = false, hideBorderWhenNotInFocus = false, disabled = false, onKeyUp, onChange, onFocus, onBlur, name, onClear, "data-testid": dataTestId, autoComplete = "on", loading = false, inputClassName, iconName = "MagnifyingGlass", style, ref, fieldSize = "medium", id, ...rest }) => {
     const { t } = useTranslation();
@@ -3923,8 +4075,41 @@ const TextField = ({ id, label, tip, helpText, helpAddon, errorMessage, isInvali
 TextField.displayName = "TextField";
 
 /**
- * TimeRangeField Description. <-- Please add a proper Description this is used in Storybook.
+ * TimeRangeField is a form-ready time range input that wraps a `TimeRange` selector inside a `FormGroup`.
+ * It provides a labeled pair of start/end time inputs with support for tooltips, help text, and validation error messages.
+ *
+ * ### When to use
+ * Use TimeRangeField when you need a labeled time range input inside a form — for example, selecting working hours, shift times, or scheduling windows.
+ *
+ * ### When not to use
+ * Do not use TimeRangeField for date ranges — use `DayRangePicker`.
+ * Do not use it outside a form context where you only need a bare time range input — use `TimeRange` directly instead.
  *
+ * @example Basic time range field with a label
+ * ```tsx
+ * import { TimeRangeField } from "@trackunit/react-form-components";
+ *
+ * const ShiftTimeInput = () => (
+ *   <TimeRangeField
+ *     label="Shift hours"
+ *     range={{ timeFrom: "08:00", timeTo: "16:00" }}
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
+ * @example Time range field with validation error
+ * ```tsx
+ * import { TimeRangeField } from "@trackunit/react-form-components";
+ *
+ * const ValidatedShiftInput = () => (
+ *   <TimeRangeField
+ *     label="Working hours"
+ *     range={{ timeFrom: "18:00", timeTo: "06:00" }}
+ *     errorMessage="End time must be after start time."
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {TimeRangeFieldProps} props - The props for the TimeRangeField component
  * @returns {ReactElement} TimeRangeField component
  */
@@ -4189,9 +4374,30 @@ const cvaUploadInputField = cssClassVarianceUtilities.cvaMerge([
 ]);
 
 /**
- * A thin wrapper around the `BaseInput` component for upload input fields.
+ * UploadInput renders a file upload input with a styled button label. It wraps `BaseInput` with `type="file"`
+ * and supports restricting file types, enabling multi-file selection, and disabling interaction.
+ *
+ * **Note:** If you need a label, help text, or validation wrapping, use `UploadField` instead.
  *
- * NOTE: If shown with a label, please use the `UploadField` component instead.
+ * ### When to use
+ * Use UploadInput for bare file upload inputs inside custom layouts or composed form components.
+ *
+ * ### When not to use
+ * Do not use UploadInput in standard forms — use `UploadField` which adds `FormGroup` wrapping with label and validation.
+ *
+ * @example File upload with accepted types
+ * ```tsx
+ * import { UploadInput } from "@trackunit/react-form-components";
+ *
+ * const DocumentUpload = () => (
+ *   <UploadInput
+ *     uploadLabel="Choose file"
+ *     acceptedTypes=".pdf,.docx"
+ *     onChange={(e) => console.log(e.target.files)}
+ *   />
+ * );
+ * ```
+ * @param {UploadInputProps} props - The props for the UploadInput component
  */
 const UploadInput = ({ disabled, acceptedTypes, nonInteractive, uploadLabel, multipleFiles, ref, ...rest }) => (jsxRuntime.jsx("label", { className: "tu-upload-input", children: jsxRuntime.jsx(BaseInput, { accept: acceptedTypes, addonBefore: uploadLabel, disabled: disabled, inputClassName: cvaUploadInputField(), multiple: multipleFiles, onClick: event => {
             // onClick used to work with nonInteractive option

package/index.esm.js

@@ -2012,8 +2012,16 @@ const CreatableSelect = (props) => {
 };
 
 /**
- * The Label component is used for labels for input fields.
- * This component is **not used directly**, but is part of the FormGroup and Field components.
+ * Label renders a styled `<label>` element for form input fields.
+ * This component is typically **not used directly** — it is rendered internally by `FormGroup` and
+ * all Field components (e.g., `TextField`, `CheckboxField`, `TimeRangeField`). Use it only when
+ * building a custom form group layout that cannot use `FormGroup`.
+ *
+ * ### When to use
+ * Use Label only when constructing a custom form field wrapper that cannot use `FormGroup`.
+ *
+ * ### When not to use
+ * Do not use Label directly for standard form fields — use the appropriate Field component (e.g., `TextField`, `CheckboxField`) which includes Label automatically.
  *
  * @param {LabelProps} props - The props for the Label component
  * @returns {ReactElement} Label component
@@ -2046,9 +2054,27 @@ const cvaFormGroupContainerAfter = cvaMerge(["flex", "justify-between", "mt-1",
 const cvaHelpAddon = cvaMerge(["ml-auto"]);
 
 /**
- * The FormGroup component should be used to wrap any Input element that needs a label.
- * Besides a label the component supplies an optional Tooltip, HelpText and HelpAddon support.
+ * FormGroup wraps an input element with a label, optional tooltip, help text, and validation styling.
+ * It provides consistent form field layout and is used internally by all Field components
+ * (`TextField`, `CheckboxField`, `TimeRangeField`, etc.).
+ *
+ * ### When to use
+ * Use FormGroup when building a custom field component that needs a label, tooltip, or help text.
  *
+ * ### When not to use
+ * Do not use FormGroup directly for standard inputs — use the corresponding Field component
+ * (e.g., `TextField`, `CheckboxField`) which already wraps FormGroup.
+ *
+ * @example Custom field with label, tooltip, and help text
+ * ```tsx
+ * import { FormGroup } from "@trackunit/react-form-components";
+ *
+ * const CustomColorField = () => (
+ *   <FormGroup label="Brand color" tip="Used across the dashboard" helpText="Enter a hex color code">
+ *     <input type="color" />
+ *   </FormGroup>
+ * );
+ * ```
  * @param {FormGroupProps} props - The props for the FormGroup component
  * @returns {ReactElement} FormGroup component
  */
@@ -2062,9 +2088,34 @@ const FormGroup = ({ isInvalid = false, isWarning = false, helpText, helpAddon,
 };
 
 /**
- * The checkbox field component is used for entering boolean values.
+ * CheckboxField is a form-ready checkbox that wraps a `Checkbox` inside a `FormGroup`.
+ * It provides a labeled checkbox with support for tooltips, help text, validation, and form group styling.
  *
- * _**Do use**_ the CheckboxField for boolean input.
+ * ### When to use
+ * Use CheckboxField for boolean inputs inside forms — for example, "I agree to terms" or toggling a feature on/off.
+ *
+ * ### When not to use
+ * Do not use CheckboxField for multi-select lists — use checkbox filters or a select component.
+ * For a standalone checkbox without form group wrapping, use `Checkbox` directly.
+ *
+ * @example Checkbox field in a form
+ * ```tsx
+ * import { CheckboxField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const TermsCheckbox = () => {
+ *   const [accepted, setAccepted] = useState(false);
+ *   return (
+ *     <CheckboxField
+ *       label="Terms and Conditions"
+ *       checkboxLabel="I accept the terms"
+ *       checked={accepted}
+ *       onChange={() => setAccepted(!accepted)}
+ *     />
+ *   );
+ * };
+ * ```
+ * @param {CheckboxFieldProps} props - The props for the CheckboxField component
  */
 const CheckboxField = ({ label, id, tip, helpText, helpAddon, isInvalid, className, checked, "data-testid": dataTestId, checkboxLabel, onChange, ref, ...rest }) => {
     const htmlForId = id ? id : "checkboxField-" + uuidv4();
@@ -3184,8 +3235,33 @@ const PhoneField = ({ label, id, tip, helpText, isInvalid, errorMessage, value,
 PhoneField.displayName = "PhoneField";
 
 /**
- * The PhoneFieldWithController component is a wrapper for the PhoneField component to connect it to react-hook-form.
+ * PhoneFieldWithController wraps `PhoneField` with a `react-hook-form` `Controller`,
+ * connecting the phone number input to form state management. It handles value synchronization,
+ * validation integration, and default value assignment automatically.
  *
+ * ### When to use
+ * Use PhoneFieldWithController when you have a phone number field inside a `react-hook-form` managed form.
+ *
+ * ### When not to use
+ * Do not use PhoneFieldWithController outside of `react-hook-form` — use `PhoneField` directly.
+ *
+ * @example Phone field in a react-hook-form
+ * ```tsx
+ * import { PhoneFieldWithController } from "@trackunit/react-form-components";
+ * import { useForm } from "react-hook-form";
+ *
+ * const ContactForm = () => {
+ *   const { control } = useForm();
+ *   return (
+ *     <PhoneFieldWithController
+ *       control={control}
+ *       name="phone"
+ *       label="Phone number"
+ *     />
+ *   );
+ * };
+ * ```
+ * @param {PhoneFieldWithControllerProps} props - The props for the PhoneFieldWithController component
  */
 const PhoneFieldWithController = ({ control, controllerProps, name, value, ref, ...rest }) => {
     return (jsx(Controller, { control: control, defaultValue: value, name: name, ...controllerProps, render: ({ field }) => jsx(PhoneField, { ...rest, ...field, ref: ref }) }));
@@ -3375,8 +3451,26 @@ const cvaTimeRange = cvaMerge([
 ]);
 
 /**
- * TimeRange is used to create a time range entry.
+ * TimeRange renders a pair of native `<input type="time">` fields for selecting a start and end time.
+ * It provides a controlled time range with `onChange` callback and supports custom separators, disabled state, and validation styling.
  *
+ * ### When to use
+ * Use TimeRange for bare time range inputs inside custom layouts or composed components (e.g., inside Schedule rows).
+ *
+ * ### When not to use
+ * Do not use TimeRange directly in forms that need a label, help text, or validation — use `TimeRangeField` instead.
+ *
+ * @example Basic time range input
+ * ```tsx
+ * import { TimeRange } from "@trackunit/react-form-components";
+ *
+ * const ShiftPicker = () => (
+ *   <TimeRange
+ *     range={{ timeFrom: "09:00", timeTo: "17:00" }}
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {TimeRangeProps} props - The props for the TimeRange component
  * @returns {ReactElement} TimeRange component
  */
@@ -3406,8 +3500,31 @@ const cvaScheduleItem = cvaMerge([
 const cvaScheduleItemText = cvaMerge(["flex", "font-bold", "self-center"]);
 
 /**
- * Schedule is used to create a time range entries.
+ * Schedule renders a weekly time-range editor where each row represents a day with an active toggle,
+ * an optional all-day checkbox, and a start/end time range. It is used for defining recurring schedules
+ * such as operating hours, service windows, or geofence active periods.
  *
+ * ### When to use
+ * Use Schedule when users need to configure per-day time ranges — for example, setting working hours for each day of the week.
+ *
+ * ### When not to use
+ * Do not use Schedule for a single time range — use `TimeRangeField`.
+ * Do not use it for date range selection — use `DayRangePicker`.
+ *
+ * @example Weekly operating hours schedule
+ * ```tsx
+ * import { Schedule, ScheduleItem } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const OperatingHours = () => {
+ *   const [schedule, setSchedule] = useState<Array<ScheduleItem>>([
+ *     { key: "mon", label: "Monday", isActive: true, range: { timeFrom: "08:00", timeTo: "17:00" } },
+ *     { key: "tue", label: "Tuesday", isActive: true, range: { timeFrom: "08:00", timeTo: "17:00" } },
+ *     { key: "wed", label: "Wednesday", isActive: false, range: { timeFrom: "", timeTo: "" } },
+ *   ]);
+ *   return <Schedule schedule={schedule} onChange={setSchedule} />;
+ * };
+ * ```
  * @param {ScheduleProps} props - The props for the Schedule component
  * @returns {ReactElement} Schedule component
  */
@@ -3597,9 +3714,44 @@ const cvaSearch = cvaMerge([
 });
 
 /**
- * The Search component is used to render a search input field.
+ * Search renders a styled search input with a magnifying glass icon, an optional loading spinner,
+ * and a clear button that appears when a value is present. It supports visual variants such as
+ * widening on focus and hiding the border when not focused.
+ *
+ * ### When to use
+ * Use Search for filtering or querying data sets — for example, a search box above a table or list to narrow down results.
+ *
+ * ### When not to use
+ * Do not use Search for multi-filter scenarios — use `FilterBar`.
+ * Do not use it as a general text input — use `TextField`.
+ *
+ * @example Basic search input with change handler
+ * ```tsx
+ * import { Search } from "@trackunit/react-form-components";
+ * import { useState, ChangeEvent } from "react";
+ *
+ * const AssetSearch = () => {
+ *   const [query, setQuery] = useState("");
+ *   return (
+ *     <Search
+ *       value={query}
+ *       onChange={(e: ChangeEvent<HTMLInputElement>) => setQuery(e.target.value)}
+ *       onClear={() => setQuery("")}
+ *       placeholder="Search assets..."
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Compact search that widens on focus
+ * ```tsx
+ * import { Search } from "@trackunit/react-form-components";
  *
+ * const CompactSearch = () => (
+ *   <Search widenInputOnFocus hideBorderWhenNotInFocus placeholder="Search..." />
+ * );
+ * ```
  * @param {SearchProps} props - The props for the Search component
+ * @returns {ReactElement} Search component
  */
 const Search = ({ className, placeholder, value, widenInputOnFocus = false, hideBorderWhenNotInFocus = false, disabled = false, onKeyUp, onChange, onFocus, onBlur, name, onClear, "data-testid": dataTestId, autoComplete = "on", loading = false, inputClassName, iconName = "MagnifyingGlass", style, ref, fieldSize = "medium", id, ...rest }) => {
     const { t } = useTranslation();
@@ -3922,8 +4074,41 @@ const TextField = ({ id, label, tip, helpText, helpAddon, errorMessage, isInvali
 TextField.displayName = "TextField";
 
 /**
- * TimeRangeField Description. <-- Please add a proper Description this is used in Storybook.
+ * TimeRangeField is a form-ready time range input that wraps a `TimeRange` selector inside a `FormGroup`.
+ * It provides a labeled pair of start/end time inputs with support for tooltips, help text, and validation error messages.
+ *
+ * ### When to use
+ * Use TimeRangeField when you need a labeled time range input inside a form — for example, selecting working hours, shift times, or scheduling windows.
+ *
+ * ### When not to use
+ * Do not use TimeRangeField for date ranges — use `DayRangePicker`.
+ * Do not use it outside a form context where you only need a bare time range input — use `TimeRange` directly instead.
  *
+ * @example Basic time range field with a label
+ * ```tsx
+ * import { TimeRangeField } from "@trackunit/react-form-components";
+ *
+ * const ShiftTimeInput = () => (
+ *   <TimeRangeField
+ *     label="Shift hours"
+ *     range={{ timeFrom: "08:00", timeTo: "16:00" }}
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
+ * @example Time range field with validation error
+ * ```tsx
+ * import { TimeRangeField } from "@trackunit/react-form-components";
+ *
+ * const ValidatedShiftInput = () => (
+ *   <TimeRangeField
+ *     label="Working hours"
+ *     range={{ timeFrom: "18:00", timeTo: "06:00" }}
+ *     errorMessage="End time must be after start time."
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {TimeRangeFieldProps} props - The props for the TimeRangeField component
  * @returns {ReactElement} TimeRangeField component
  */
@@ -4188,9 +4373,30 @@ const cvaUploadInputField = cvaMerge([
 ]);
 
 /**
- * A thin wrapper around the `BaseInput` component for upload input fields.
+ * UploadInput renders a file upload input with a styled button label. It wraps `BaseInput` with `type="file"`
+ * and supports restricting file types, enabling multi-file selection, and disabling interaction.
+ *
+ * **Note:** If you need a label, help text, or validation wrapping, use `UploadField` instead.
  *
- * NOTE: If shown with a label, please use the `UploadField` component instead.
+ * ### When to use
+ * Use UploadInput for bare file upload inputs inside custom layouts or composed form components.
+ *
+ * ### When not to use
+ * Do not use UploadInput in standard forms — use `UploadField` which adds `FormGroup` wrapping with label and validation.
+ *
+ * @example File upload with accepted types
+ * ```tsx
+ * import { UploadInput } from "@trackunit/react-form-components";
+ *
+ * const DocumentUpload = () => (
+ *   <UploadInput
+ *     uploadLabel="Choose file"
+ *     acceptedTypes=".pdf,.docx"
+ *     onChange={(e) => console.log(e.target.files)}
+ *   />
+ * );
+ * ```
+ * @param {UploadInputProps} props - The props for the UploadInput component
  */
 const UploadInput = ({ disabled, acceptedTypes, nonInteractive, uploadLabel, multipleFiles, ref, ...rest }) => (jsx("label", { className: "tu-upload-input", children: jsx(BaseInput, { accept: acceptedTypes, addonBefore: uploadLabel, disabled: disabled, inputClassName: cvaUploadInputField(), multiple: multipleFiles, onClick: event => {
             // onClick used to work with nonInteractive option

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-form-components",
-  "version": "1.14.25",
+  "version": "1.14.27",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -15,7 +15,7 @@
     "react-hook-form": "7.62.0",
     "tailwind-merge": "^2.0.0",
     "@trackunit/css-class-variance-utilities": "1.11.43",
-    "@trackunit/react-components": "1.17.22",
+    "@trackunit/react-components": "1.17.24",
     "@trackunit/ui-icons": "1.11.42",
     "@trackunit/shared-utils": "1.13.43",
     "@trackunit/ui-design-tokens": "1.11.43",

package/src/components/CheckboxField/CheckboxField.d.ts

@@ -3,16 +3,45 @@ import { CheckboxProps } from "../Checkbox/Checkbox";
 import { FormGroupProps } from "../FormGroup/FormGroup";
 type FormGroupExposedProps = Pick<FormGroupProps, "tip" | "helpText" | "helpAddon">;
 export interface CheckboxFieldProps extends CheckboxProps, FormGroupExposedProps {
+    /**
+     * Text or ReactNode displayed next to the checkbox. This is the clickable label for the checkbox itself
+     * (distinct from the `label` prop which labels the overall form group).
+     */
     checkboxLabel?: string | ReactNode;
     /**
-     * A ref for the component
+     * A ref for the component.
      */
     ref?: Ref<HTMLInputElement>;
 }
 /**
- * The checkbox field component is used for entering boolean values.
+ * CheckboxField is a form-ready checkbox that wraps a `Checkbox` inside a `FormGroup`.
+ * It provides a labeled checkbox with support for tooltips, help text, validation, and form group styling.
+ *
+ * ### When to use
+ * Use CheckboxField for boolean inputs inside forms — for example, "I agree to terms" or toggling a feature on/off.
+ *
+ * ### When not to use
+ * Do not use CheckboxField for multi-select lists — use checkbox filters or a select component.
+ * For a standalone checkbox without form group wrapping, use `Checkbox` directly.
+ *
+ * @example Checkbox field in a form
+ * ```tsx
+ * import { CheckboxField } from "@trackunit/react-form-components";
+ * import { useState } from "react";
  *
- * _**Do use**_ the CheckboxField for boolean input.
+ * const TermsCheckbox = () => {
+ *   const [accepted, setAccepted] = useState(false);
+ *   return (
+ *     <CheckboxField
+ *       label="Terms and Conditions"
+ *       checkboxLabel="I accept the terms"
+ *       checked={accepted}
+ *       onChange={() => setAccepted(!accepted)}
+ *     />
+ *   );
+ * };
+ * ```
+ * @param {CheckboxFieldProps} props - The props for the CheckboxField component
  */
 export declare const CheckboxField: {
     ({ label, id, tip, helpText, helpAddon, isInvalid, className, checked, "data-testid": dataTestId, checkboxLabel, onChange, ref, ...rest }: CheckboxFieldProps): import("react/jsx-runtime").JSX.Element;

package/src/components/FormGroup/FormGroup.d.ts

@@ -9,6 +9,9 @@ export interface FormGroupProps extends CommonProps, Refable<HTMLDivElement> {
      * Content to display in the tooltip when hovering the ? icon next to the label.
      */
     tip?: string | ReactNode;
+    /**
+     * The `id` of the input element this form group labels. Used to associate the `<label>` with the input via `for` attribute.
+     */
     htmlFor?: string;
     /**
      * A string to display under the input element to help the user understand the input.
@@ -23,7 +26,13 @@ export interface FormGroupProps extends CommonProps, Refable<HTMLDivElement> {
      * If true the input is rendered in its invalid state.
      */
     isInvalid?: boolean;
+    /**
+     * The input or field element to render inside the form group, below the label and above the help text.
+     */
     children?: ReactNode;
+    /**
+     * The name of the form field. Passed through to child input components for form submission.
+     */
     name?: string;
     /**
      * If true the input is required with an asterisk prepended to the label.
@@ -36,9 +45,27 @@ export interface FormGroupProps extends CommonProps, Refable<HTMLDivElement> {
     isWarning?: boolean;
 }
 /**
- * The FormGroup component should be used to wrap any Input element that needs a label.
- * Besides a label the component supplies an optional Tooltip, HelpText and HelpAddon support.
+ * FormGroup wraps an input element with a label, optional tooltip, help text, and validation styling.
+ * It provides consistent form field layout and is used internally by all Field components
+ * (`TextField`, `CheckboxField`, `TimeRangeField`, etc.).
+ *
+ * ### When to use
+ * Use FormGroup when building a custom field component that needs a label, tooltip, or help text.
+ *
+ * ### When not to use
+ * Do not use FormGroup directly for standard inputs — use the corresponding Field component
+ * (e.g., `TextField`, `CheckboxField`) which already wraps FormGroup.
+ *
+ * @example Custom field with label, tooltip, and help text
+ * ```tsx
+ * import { FormGroup } from "@trackunit/react-form-components";
  *
+ * const CustomColorField = () => (
+ *   <FormGroup label="Brand color" tip="Used across the dashboard" helpText="Enter a hex color code">
+ *     <input type="color" />
+ *   </FormGroup>
+ * );
+ * ```
  * @param {FormGroupProps} props - The props for the FormGroup component
  * @returns {ReactElement} FormGroup component
  */

package/src/components/Label/Label.d.ts

@@ -24,8 +24,16 @@ export interface LabelProps extends CommonProps, Refable<HTMLLabelElement> {
     isInvalid?: boolean;
 }
 /**
- * The Label component is used for labels for input fields.
- * This component is **not used directly**, but is part of the FormGroup and Field components.
+ * Label renders a styled `<label>` element for form input fields.
+ * This component is typically **not used directly** — it is rendered internally by `FormGroup` and
+ * all Field components (e.g., `TextField`, `CheckboxField`, `TimeRangeField`). Use it only when
+ * building a custom form group layout that cannot use `FormGroup`.
+ *
+ * ### When to use
+ * Use Label only when constructing a custom form field wrapper that cannot use `FormGroup`.
+ *
+ * ### When not to use
+ * Do not use Label directly for standard form fields — use the appropriate Field component (e.g., `TextField`, `CheckboxField`) which includes Label automatically.
  *
  * @param {LabelProps} props - The props for the Label component
  * @returns {ReactElement} Label component

package/src/components/PhoneFieldWithController/PhoneFieldWithController.d.ts

@@ -20,8 +20,33 @@ export interface PhoneFieldWithControllerProps extends PhoneFieldProps {
     ref?: Ref<HTMLInputElement>;
 }
 /**
- * The PhoneFieldWithController component is a wrapper for the PhoneField component to connect it to react-hook-form.
+ * PhoneFieldWithController wraps `PhoneField` with a `react-hook-form` `Controller`,
+ * connecting the phone number input to form state management. It handles value synchronization,
+ * validation integration, and default value assignment automatically.
  *
+ * ### When to use
+ * Use PhoneFieldWithController when you have a phone number field inside a `react-hook-form` managed form.
+ *
+ * ### When not to use
+ * Do not use PhoneFieldWithController outside of `react-hook-form` — use `PhoneField` directly.
+ *
+ * @example Phone field in a react-hook-form
+ * ```tsx
+ * import { PhoneFieldWithController } from "@trackunit/react-form-components";
+ * import { useForm } from "react-hook-form";
+ *
+ * const ContactForm = () => {
+ *   const { control } = useForm();
+ *   return (
+ *     <PhoneFieldWithController
+ *       control={control}
+ *       name="phone"
+ *       label="Phone number"
+ *     />
+ *   );
+ * };
+ * ```
+ * @param {PhoneFieldWithControllerProps} props - The props for the PhoneFieldWithController component
  */
 export declare const PhoneFieldWithController: {
     ({ control, controllerProps, name, value, ref, ...rest }: PhoneFieldWithControllerProps): import("react/jsx-runtime").JSX.Element;

package/src/components/Schedule/Schedule.d.ts

@@ -44,8 +44,31 @@ export interface ScheduleProps extends CommonProps, Refable<HTMLDivElement> {
     onChange: (schedules: Array<ScheduleItem>) => void;
 }
 /**
- * Schedule is used to create a time range entries.
+ * Schedule renders a weekly time-range editor where each row represents a day with an active toggle,
+ * an optional all-day checkbox, and a start/end time range. It is used for defining recurring schedules
+ * such as operating hours, service windows, or geofence active periods.
  *
+ * ### When to use
+ * Use Schedule when users need to configure per-day time ranges — for example, setting working hours for each day of the week.
+ *
+ * ### When not to use
+ * Do not use Schedule for a single time range — use `TimeRangeField`.
+ * Do not use it for date range selection — use `DayRangePicker`.
+ *
+ * @example Weekly operating hours schedule
+ * ```tsx
+ * import { Schedule, ScheduleItem } from "@trackunit/react-form-components";
+ * import { useState } from "react";
+ *
+ * const OperatingHours = () => {
+ *   const [schedule, setSchedule] = useState<Array<ScheduleItem>>([
+ *     { key: "mon", label: "Monday", isActive: true, range: { timeFrom: "08:00", timeTo: "17:00" } },
+ *     { key: "tue", label: "Tuesday", isActive: true, range: { timeFrom: "08:00", timeTo: "17:00" } },
+ *     { key: "wed", label: "Wednesday", isActive: false, range: { timeFrom: "", timeTo: "" } },
+ *   ]);
+ *   return <Schedule schedule={schedule} onChange={setSchedule} />;
+ * };
+ * ```
  * @param {ScheduleProps} props - The props for the Schedule component
  * @returns {ReactElement} Schedule component
  */

package/src/components/Search/Search.d.ts

@@ -68,12 +68,50 @@ export interface SearchProps extends CommonProps, TextBaseInputProps {
      * A custom icon to be displayed in the search box.
      */
     iconName?: IconName;
+    /**
+     * Inline CSS styles applied to the root search container element.
+     */
     style?: CSSProperties;
 }
 /**
- * The Search component is used to render a search input field.
+ * Search renders a styled search input with a magnifying glass icon, an optional loading spinner,
+ * and a clear button that appears when a value is present. It supports visual variants such as
+ * widening on focus and hiding the border when not focused.
+ *
+ * ### When to use
+ * Use Search for filtering or querying data sets — for example, a search box above a table or list to narrow down results.
+ *
+ * ### When not to use
+ * Do not use Search for multi-filter scenarios — use `FilterBar`.
+ * Do not use it as a general text input — use `TextField`.
+ *
+ * @example Basic search input with change handler
+ * ```tsx
+ * import { Search } from "@trackunit/react-form-components";
+ * import { useState, ChangeEvent } from "react";
+ *
+ * const AssetSearch = () => {
+ *   const [query, setQuery] = useState("");
+ *   return (
+ *     <Search
+ *       value={query}
+ *       onChange={(e: ChangeEvent<HTMLInputElement>) => setQuery(e.target.value)}
+ *       onClear={() => setQuery("")}
+ *       placeholder="Search assets..."
+ *     />
+ *   );
+ * };
+ * ```
+ * @example Compact search that widens on focus
+ * ```tsx
+ * import { Search } from "@trackunit/react-form-components";
  *
+ * const CompactSearch = () => (
+ *   <Search widenInputOnFocus hideBorderWhenNotInFocus placeholder="Search..." />
+ * );
+ * ```
  * @param {SearchProps} props - The props for the Search component
+ * @returns {ReactElement} Search component
  */
 export declare const Search: {
     ({ className, placeholder, value, widenInputOnFocus, hideBorderWhenNotInFocus, disabled, onKeyUp, onChange, onFocus, onBlur, name, onClear, "data-testid": dataTestId, autoComplete, loading, inputClassName, iconName, style, ref, fieldSize, id, ...rest }: SearchProps): ReactElement;

package/src/components/TimeRange/TimeRange.d.ts

@@ -44,8 +44,26 @@ export interface TimeRangeProps extends CommonProps, Refable<HTMLDivElement> {
     onChange: (range: TimeRangeInput) => void;
 }
 /**
- * TimeRange is used to create a time range entry.
+ * TimeRange renders a pair of native `<input type="time">` fields for selecting a start and end time.
+ * It provides a controlled time range with `onChange` callback and supports custom separators, disabled state, and validation styling.
  *
+ * ### When to use
+ * Use TimeRange for bare time range inputs inside custom layouts or composed components (e.g., inside Schedule rows).
+ *
+ * ### When not to use
+ * Do not use TimeRange directly in forms that need a label, help text, or validation — use `TimeRangeField` instead.
+ *
+ * @example Basic time range input
+ * ```tsx
+ * import { TimeRange } from "@trackunit/react-form-components";
+ *
+ * const ShiftPicker = () => (
+ *   <TimeRange
+ *     range={{ timeFrom: "09:00", timeTo: "17:00" }}
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {TimeRangeProps} props - The props for the TimeRange component
  * @returns {ReactElement} TimeRange component
  */

package/src/components/TimeRangeField/TimeRangeField.d.ts

@@ -9,8 +9,41 @@ export interface TimeRangeFieldProps extends TimeRangeProps, FormGroupExposedPro
     errorMessage?: string;
 }
 /**
- * TimeRangeField Description. <-- Please add a proper Description this is used in Storybook.
+ * TimeRangeField is a form-ready time range input that wraps a `TimeRange` selector inside a `FormGroup`.
+ * It provides a labeled pair of start/end time inputs with support for tooltips, help text, and validation error messages.
  *
+ * ### When to use
+ * Use TimeRangeField when you need a labeled time range input inside a form — for example, selecting working hours, shift times, or scheduling windows.
+ *
+ * ### When not to use
+ * Do not use TimeRangeField for date ranges — use `DayRangePicker`.
+ * Do not use it outside a form context where you only need a bare time range input — use `TimeRange` directly instead.
+ *
+ * @example Basic time range field with a label
+ * ```tsx
+ * import { TimeRangeField } from "@trackunit/react-form-components";
+ *
+ * const ShiftTimeInput = () => (
+ *   <TimeRangeField
+ *     label="Shift hours"
+ *     range={{ timeFrom: "08:00", timeTo: "16:00" }}
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
+ * @example Time range field with validation error
+ * ```tsx
+ * import { TimeRangeField } from "@trackunit/react-form-components";
+ *
+ * const ValidatedShiftInput = () => (
+ *   <TimeRangeField
+ *     label="Working hours"
+ *     range={{ timeFrom: "18:00", timeTo: "06:00" }}
+ *     errorMessage="End time must be after start time."
+ *     onChange={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {TimeRangeFieldProps} props - The props for the TimeRangeField component
  * @returns {ReactElement} TimeRangeField component
  */

package/src/components/UploadInput/UploadInput.d.ts

@@ -24,9 +24,30 @@ export interface UploadInputProps extends BaseInputExposedProps, CommonProps {
     nonInteractive?: boolean;
 }
 /**
- * A thin wrapper around the `BaseInput` component for upload input fields.
+ * UploadInput renders a file upload input with a styled button label. It wraps `BaseInput` with `type="file"`
+ * and supports restricting file types, enabling multi-file selection, and disabling interaction.
  *
- * NOTE: If shown with a label, please use the `UploadField` component instead.
+ * **Note:** If you need a label, help text, or validation wrapping, use `UploadField` instead.
+ *
+ * ### When to use
+ * Use UploadInput for bare file upload inputs inside custom layouts or composed form components.
+ *
+ * ### When not to use
+ * Do not use UploadInput in standard forms — use `UploadField` which adds `FormGroup` wrapping with label and validation.
+ *
+ * @example File upload with accepted types
+ * ```tsx
+ * import { UploadInput } from "@trackunit/react-form-components";
+ *
+ * const DocumentUpload = () => (
+ *   <UploadInput
+ *     uploadLabel="Choose file"
+ *     acceptedTypes=".pdf,.docx"
+ *     onChange={(e) => console.log(e.target.files)}
+ *   />
+ * );
+ * ```
+ * @param {UploadInputProps} props - The props for the UploadInput component
  */
 export declare const UploadInput: {
     ({ disabled, acceptedTypes, nonInteractive, uploadLabel, multipleFiles, ref, ...rest }: UploadInputProps): import("react/jsx-runtime").JSX.Element;