@trackunit/react-date-and-time-components 1.16.28 → 1.16.30

package/index.cjs.js

@@ -94,17 +94,35 @@ const setupLibraryTranslations = () => {
 
 const MS_PER_HOUR = 60 * 60 * 1000;
 /**
- * DateTime component
+ * DateTime renders a locale-aware, formatted date and/or time inside a semantic `<time>` element.
+ * It supports absolute formatting via `TemporalFormat` presets (e.g., `DateTimeFormat.DATE`, `DateTimeFormat.DATE_LONG_TIME`)
+ * and relative "time ago" display via the `fromNow` prop. Timezone-aware formatting is available through the `timezone` prop.
  *
- * @param { DateTimeProps } props - The properties for the DateTime component.
- * @param props.value Date | string | number | null | undefined
- * @param props.format DateTimeFormat | TemporalFormat | string
- * @param props.className string
- * @param props.fromNow boolean
- * @param props.withTitle boolean
- * @param props.titleFormat string
- * @param props.timezone TimeZone
- * @param props.subtle boolean
+ * ### When to use
+ * Use DateTime whenever you need to display a date, time, or relative timestamp in the UI — for example, "Last seen 3 hours ago" or "Feb 17, 2026".
+ *
+ * ### When not to use
+ * Do not use DateTime for date input or selection — use `DayRangePicker` or `TimeRangeField`.
+ * Do not use for duration formatting (e.g., "2h 30m") — use dedicated duration utilities instead.
+ *
+ * @example Displaying a formatted date
+ * ```tsx
+ * import { DateTime } from "@trackunit/react-date-and-time-components";
+ * import { DateTimeFormat } from "@trackunit/shared-utils";
+ *
+ * const AssetLastService = () => (
+ *   <DateTime value="2026-01-15T10:30:00Z" format={DateTimeFormat.DATE_LONG} />
+ * );
+ * ```
+ * @example Showing relative time
+ * ```tsx
+ * import { DateTime } from "@trackunit/react-date-and-time-components";
+ *
+ * const LastSeenLabel = ({ lastSeen }: { lastSeen: Date }) => (
+ *   <DateTime value={lastSeen} fromNow />
+ * );
+ * ```
+ * @param {DateTimeProps} props - The props for the DateTime component
  */
 const DateTime = ({ value, format, className, fromNow = false, withTitle = false, titleFormat, timezone, "data-testid": dataTestId, subtle = false, ref, }) => {
     const { t } = useTranslation();
@@ -222,8 +240,29 @@ const DayPicker = ({ onDaySelect, disabledDays, selectedDay, language, className
 };
 
 /**
- * The DayRangePicker component should be used when the user needs to select a range of dates.
+ * DayRangePicker renders an interactive calendar that allows the user to select a start and end date.
+ * It supports disabled days, timezone-aware display, locale configuration, and an optional cancel button.
+ * The selected range is returned via the `onRangeSelect` callback as a `DateRange` object.
+ *
+ * ### When to use
+ * Use DayRangePicker when the user needs a visual calendar to pick a custom date range — for example,
+ * selecting a reporting period or scheduling an event spanning multiple days.
  *
+ * ### When not to use
+ * Do not use DayRangePicker for quick preset ranges (e.g., "Last 7 days") — use `DayRangeSelect` which includes preset options and a calendar fallback.
+ * Do not use it for time selection — use `TimeRangeField`.
+ *
+ * @example Selecting a date range
+ * ```tsx
+ * import { DayRangePicker } from "@trackunit/react-date-and-time-components";
+ *
+ * const ReportDatePicker = () => (
+ *   <DayRangePicker
+ *     language="en"
+ *     onRangeSelect={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {DayRangePickerProps} props - The props for the DayRangePicker component
  * @returns {ReactElement} DayRangePicker component
  */
@@ -591,7 +630,29 @@ const isTemporalDirection = (direction) => {
 };
 
 /**
- * Day range select component.
+ * DayRangeSelect is a popover-based date range picker with preset temporal options (e.g., "Last 7 days", "Next 30 days")
+ * and an optional custom calendar picker. Users can search for presets by typing natural language queries like "last 3 months".
+ * It supports configurable allowed directions, timezone handling, and max day limits.
+ *
+ * ### When to use
+ * Use DayRangeSelect when users need to choose a date range from predefined presets or a custom calendar — for example,
+ * filtering dashboard data by time period or selecting a reporting window.
+ *
+ * ### When not to use
+ * Do not use DayRangeSelect for a standalone calendar without presets — use `DayRangePicker`.
+ * Do not use it for time-only selection — use `TimeRangeField`.
+ *
+ * @example Date range select with default presets
+ * ```tsx
+ * import { DayRangeSelect } from "@trackunit/react-date-and-time-components";
+ *
+ * const ReportFilter = () => (
+ *   <DayRangeSelect
+ *     onRangeSelect={(selection) => console.log(selection)}
+ *   />
+ * );
+ * ```
+ * @param {DayRangeSelectProps} props - The props for the DayRangeSelect component
  */
 const DayRangeSelect = ({ className, "data-testid": dataTestId, disabled, selectedDateRange, onRangeSelect, allowedDirection = undefined, initialDateRangeOptions, showDateRangeSearch = true, showCustomDateRangeOption = true, timezone, maxDaysInRange, size = "medium", fullWidth = false, actionButton, popoverPlacement = "bottom-start", }) => {
     const [t] = useTranslation();

package/index.esm.js

@@ -92,17 +92,35 @@ const setupLibraryTranslations = () => {
 
 const MS_PER_HOUR = 60 * 60 * 1000;
 /**
- * DateTime component
+ * DateTime renders a locale-aware, formatted date and/or time inside a semantic `<time>` element.
+ * It supports absolute formatting via `TemporalFormat` presets (e.g., `DateTimeFormat.DATE`, `DateTimeFormat.DATE_LONG_TIME`)
+ * and relative "time ago" display via the `fromNow` prop. Timezone-aware formatting is available through the `timezone` prop.
  *
- * @param { DateTimeProps } props - The properties for the DateTime component.
- * @param props.value Date | string | number | null | undefined
- * @param props.format DateTimeFormat | TemporalFormat | string
- * @param props.className string
- * @param props.fromNow boolean
- * @param props.withTitle boolean
- * @param props.titleFormat string
- * @param props.timezone TimeZone
- * @param props.subtle boolean
+ * ### When to use
+ * Use DateTime whenever you need to display a date, time, or relative timestamp in the UI — for example, "Last seen 3 hours ago" or "Feb 17, 2026".
+ *
+ * ### When not to use
+ * Do not use DateTime for date input or selection — use `DayRangePicker` or `TimeRangeField`.
+ * Do not use for duration formatting (e.g., "2h 30m") — use dedicated duration utilities instead.
+ *
+ * @example Displaying a formatted date
+ * ```tsx
+ * import { DateTime } from "@trackunit/react-date-and-time-components";
+ * import { DateTimeFormat } from "@trackunit/shared-utils";
+ *
+ * const AssetLastService = () => (
+ *   <DateTime value="2026-01-15T10:30:00Z" format={DateTimeFormat.DATE_LONG} />
+ * );
+ * ```
+ * @example Showing relative time
+ * ```tsx
+ * import { DateTime } from "@trackunit/react-date-and-time-components";
+ *
+ * const LastSeenLabel = ({ lastSeen }: { lastSeen: Date }) => (
+ *   <DateTime value={lastSeen} fromNow />
+ * );
+ * ```
+ * @param {DateTimeProps} props - The props for the DateTime component
  */
 const DateTime = ({ value, format, className, fromNow = false, withTitle = false, titleFormat, timezone, "data-testid": dataTestId, subtle = false, ref, }) => {
     const { t } = useTranslation();
@@ -220,8 +238,29 @@ const DayPicker = ({ onDaySelect, disabledDays, selectedDay, language, className
 };
 
 /**
- * The DayRangePicker component should be used when the user needs to select a range of dates.
+ * DayRangePicker renders an interactive calendar that allows the user to select a start and end date.
+ * It supports disabled days, timezone-aware display, locale configuration, and an optional cancel button.
+ * The selected range is returned via the `onRangeSelect` callback as a `DateRange` object.
+ *
+ * ### When to use
+ * Use DayRangePicker when the user needs a visual calendar to pick a custom date range — for example,
+ * selecting a reporting period or scheduling an event spanning multiple days.
  *
+ * ### When not to use
+ * Do not use DayRangePicker for quick preset ranges (e.g., "Last 7 days") — use `DayRangeSelect` which includes preset options and a calendar fallback.
+ * Do not use it for time selection — use `TimeRangeField`.
+ *
+ * @example Selecting a date range
+ * ```tsx
+ * import { DayRangePicker } from "@trackunit/react-date-and-time-components";
+ *
+ * const ReportDatePicker = () => (
+ *   <DayRangePicker
+ *     language="en"
+ *     onRangeSelect={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {DayRangePickerProps} props - The props for the DayRangePicker component
  * @returns {ReactElement} DayRangePicker component
  */
@@ -589,7 +628,29 @@ const isTemporalDirection = (direction) => {
 };
 
 /**
- * Day range select component.
+ * DayRangeSelect is a popover-based date range picker with preset temporal options (e.g., "Last 7 days", "Next 30 days")
+ * and an optional custom calendar picker. Users can search for presets by typing natural language queries like "last 3 months".
+ * It supports configurable allowed directions, timezone handling, and max day limits.
+ *
+ * ### When to use
+ * Use DayRangeSelect when users need to choose a date range from predefined presets or a custom calendar — for example,
+ * filtering dashboard data by time period or selecting a reporting window.
+ *
+ * ### When not to use
+ * Do not use DayRangeSelect for a standalone calendar without presets — use `DayRangePicker`.
+ * Do not use it for time-only selection — use `TimeRangeField`.
+ *
+ * @example Date range select with default presets
+ * ```tsx
+ * import { DayRangeSelect } from "@trackunit/react-date-and-time-components";
+ *
+ * const ReportFilter = () => (
+ *   <DayRangeSelect
+ *     onRangeSelect={(selection) => console.log(selection)}
+ *   />
+ * );
+ * ```
+ * @param {DayRangeSelectProps} props - The props for the DayRangeSelect component
  */
 const DayRangeSelect = ({ className, "data-testid": dataTestId, disabled, selectedDateRange, onRangeSelect, allowedDirection = undefined, initialDateRangeOptions, showDateRangeSearch = true, showCustomDateRangeOption = true, timezone, maxDaysInRange, size = "medium", fullWidth = false, actionButton, popoverPlacement = "bottom-start", }) => {
     const [t] = useTranslation();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-date-and-time-components",
-  "version": "1.16.28",
+  "version": "1.16.30",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,14 +8,14 @@
   },
   "dependencies": {
     "react": "19.0.0",
-    "@trackunit/react-components": "1.17.22",
+    "@trackunit/react-components": "1.17.24",
     "@trackunit/date-and-time-utils": "1.11.44",
-    "@trackunit/react-date-and-time-hooks": "1.13.28",
+    "@trackunit/react-date-and-time-hooks": "1.13.30",
     "@trackunit/css-class-variance-utilities": "1.11.43",
     "@trackunit/ui-icons": "1.11.42",
     "@trackunit/shared-utils": "1.13.43",
     "@trackunit/i18n-library-translation": "1.12.28",
-    "@trackunit/react-form-components": "1.14.25",
+    "@trackunit/react-form-components": "1.14.27",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
     "react-calendar": "^6.0.0"

package/src/DayPicker/DayRangePicker.d.ts

@@ -38,8 +38,29 @@ export interface DayRangePickerProps extends CommonProps, Refable<HTMLDivElement
     classNameCalendar?: string;
 }
 /**
- * The DayRangePicker component should be used when the user needs to select a range of dates.
+ * DayRangePicker renders an interactive calendar that allows the user to select a start and end date.
+ * It supports disabled days, timezone-aware display, locale configuration, and an optional cancel button.
+ * The selected range is returned via the `onRangeSelect` callback as a `DateRange` object.
  *
+ * ### When to use
+ * Use DayRangePicker when the user needs a visual calendar to pick a custom date range — for example,
+ * selecting a reporting period or scheduling an event spanning multiple days.
+ *
+ * ### When not to use
+ * Do not use DayRangePicker for quick preset ranges (e.g., "Last 7 days") — use `DayRangeSelect` which includes preset options and a calendar fallback.
+ * Do not use it for time selection — use `TimeRangeField`.
+ *
+ * @example Selecting a date range
+ * ```tsx
+ * import { DayRangePicker } from "@trackunit/react-date-and-time-components";
+ *
+ * const ReportDatePicker = () => (
+ *   <DayRangePicker
+ *     language="en"
+ *     onRangeSelect={(range) => console.log(range)}
+ *   />
+ * );
+ * ```
  * @param {DayRangePickerProps} props - The props for the DayRangePicker component
  * @returns {ReactElement} DayRangePicker component
  */

package/src/DayRangeSelect/DayRangeSelect.d.ts

@@ -64,6 +64,28 @@ export type DayRangeSelectProps = CommonProps & {
     popoverPlacement?: PopoverPlacement;
 };
 /**
- * Day range select component.
+ * DayRangeSelect is a popover-based date range picker with preset temporal options (e.g., "Last 7 days", "Next 30 days")
+ * and an optional custom calendar picker. Users can search for presets by typing natural language queries like "last 3 months".
+ * It supports configurable allowed directions, timezone handling, and max day limits.
+ *
+ * ### When to use
+ * Use DayRangeSelect when users need to choose a date range from predefined presets or a custom calendar — for example,
+ * filtering dashboard data by time period or selecting a reporting window.
+ *
+ * ### When not to use
+ * Do not use DayRangeSelect for a standalone calendar without presets — use `DayRangePicker`.
+ * Do not use it for time-only selection — use `TimeRangeField`.
+ *
+ * @example Date range select with default presets
+ * ```tsx
+ * import { DayRangeSelect } from "@trackunit/react-date-and-time-components";
+ *
+ * const ReportFilter = () => (
+ *   <DayRangeSelect
+ *     onRangeSelect={(selection) => console.log(selection)}
+ *   />
+ * );
+ * ```
+ * @param {DayRangeSelectProps} props - The props for the DayRangeSelect component
  */
 export declare const DayRangeSelect: ({ className, "data-testid": dataTestId, disabled, selectedDateRange, onRangeSelect, allowedDirection, initialDateRangeOptions, showDateRangeSearch, showCustomDateRangeOption, timezone, maxDaysInRange, size, fullWidth, actionButton, popoverPlacement, }: DayRangeSelectProps) => import("react/jsx-runtime").JSX.Element;

package/src/dateTime/DateTime.d.ts

@@ -2,26 +2,73 @@ import { TemporalFormat } from "@trackunit/date-and-time-utils";
 import { CommonProps, Refable } from "@trackunit/react-components";
 import { TimeZone } from "../index";
 export interface DateTimeProps extends CommonProps, Refable<HTMLTimeElement> {
+    /**
+     * The date/time value to display. Accepts a `Date` object, an ISO 8601 string, or a Unix timestamp in milliseconds.
+     * When `null` or `undefined`, the current date/time is used.
+     */
     value: Date | string | number | null | undefined;
+    /**
+     * Display format using a `TemporalFormat` configuration object. Use presets from `DateTimeFormat`
+     * (e.g., `DateTimeFormat.DATE`, `DateTimeFormat.DATE_LONG_TIME`, `DateTimeFormat.TIME_SHORT`).
+     */
     format?: TemporalFormat;
+    /**
+     * When true, displays a relative time string (e.g., "3 hours ago") instead of the formatted date.
+     *
+     * @default false
+     */
     fromNow?: boolean;
+    /**
+     * When true, adds a native HTML `title` attribute with the formatted date so the full value is shown on hover.
+     *
+     * @default false
+     */
     withTitle?: boolean;
+    /**
+     * Custom `TemporalFormat` for the hover `title` attribute. Only used when `withTitle` is true.
+     */
     titleFormat?: TemporalFormat;
+    /**
+     * A `TimeZone` object to format the date in a specific timezone rather than the user's local timezone.
+     */
     timezone?: TimeZone;
+    /**
+     * When true, renders the text in a muted neutral color for less visual emphasis.
+     *
+     * @default false
+     */
     subtle?: boolean;
 }
 export declare const MS_PER_HOUR: number;
 /**
- * DateTime component
+ * DateTime renders a locale-aware, formatted date and/or time inside a semantic `<time>` element.
+ * It supports absolute formatting via `TemporalFormat` presets (e.g., `DateTimeFormat.DATE`, `DateTimeFormat.DATE_LONG_TIME`)
+ * and relative "time ago" display via the `fromNow` prop. Timezone-aware formatting is available through the `timezone` prop.
  *
- * @param { DateTimeProps } props - The properties for the DateTime component.
- * @param props.value Date | string | number | null | undefined
- * @param props.format DateTimeFormat | TemporalFormat | string
- * @param props.className string
- * @param props.fromNow boolean
- * @param props.withTitle boolean
- * @param props.titleFormat string
- * @param props.timezone TimeZone
- * @param props.subtle boolean
+ * ### When to use
+ * Use DateTime whenever you need to display a date, time, or relative timestamp in the UI — for example, "Last seen 3 hours ago" or "Feb 17, 2026".
+ *
+ * ### When not to use
+ * Do not use DateTime for date input or selection — use `DayRangePicker` or `TimeRangeField`.
+ * Do not use for duration formatting (e.g., "2h 30m") — use dedicated duration utilities instead.
+ *
+ * @example Displaying a formatted date
+ * ```tsx
+ * import { DateTime } from "@trackunit/react-date-and-time-components";
+ * import { DateTimeFormat } from "@trackunit/shared-utils";
+ *
+ * const AssetLastService = () => (
+ *   <DateTime value="2026-01-15T10:30:00Z" format={DateTimeFormat.DATE_LONG} />
+ * );
+ * ```
+ * @example Showing relative time
+ * ```tsx
+ * import { DateTime } from "@trackunit/react-date-and-time-components";
+ *
+ * const LastSeenLabel = ({ lastSeen }: { lastSeen: Date }) => (
+ *   <DateTime value={lastSeen} fromNow />
+ * );
+ * ```
+ * @param {DateTimeProps} props - The props for the DateTime component
  */
 export declare const DateTime: ({ value, format, className, fromNow, withTitle, titleFormat, timezone, "data-testid": dataTestId, subtle, ref, }: DateTimeProps) => import("react/jsx-runtime").JSX.Element;