@trackunit/react-date-and-time-hooks 1.21.19 → 1.21.21

package/index.cjs.js

@@ -106,7 +106,18 @@ const GetAssetTimezoneDocument = {
 
 const customTimeZoneSchema = zod.z.string().nullable();
 /**
+ * Resolves the active timezone based on user preference, custom override, and optional asset location.
  *
+ * Returns `current` (browser or custom override), `preferred` (resolved per user settings
+ * and optional asset), and `assetTimeZone` (fetched from the asset's GPS location).
+ *
+ * **When to use:**
+ * - Use `useTimezone` whenever you need to display or calculate dates in the correct
+ *   timezone — especially on asset-detail pages where the machine's timezone may differ
+ *   from the user's browser timezone.
+ * - Pair with `useDateAndTime` to format dates in the resolved `preferred` timezone.
+ * - Do **not** rely on `Intl.DateTimeFormat().resolvedOptions().timeZone` directly —
+ *   this hook respects the user's preference setting (browser, machine, or custom).
  */
 const useTimezone = ({ assetId } = {}) => {
     const { timeZonePreference } = reactCoreHooks.useCurrentUserTimeZonePreference();
@@ -147,8 +158,18 @@ const useTimezone = ({ assetId } = {}) => {
 };
 
 /**
- * Hook for managing date and time operations.
+ * Hook for locale- and timezone-aware date/time operations including formatting,
+ * arithmetic, comparisons, relative time, and duration formatting.
+ *
+ * ### When to use
+ * Use `useDateAndTime` whenever you need to format, compare, or manipulate dates in a
+ * way that respects the user's locale and timezone.
  *
+ * ### When not to use
+ * - For raw UTC timestamps that never reach the UI — use plain `Date` math or
+ *   `date-and-time-utils` directly.
+ * - For date picker value handling — the date/time components already consume locale
+ *   and timezone internally.
  */
 const useDateAndTime = () => {
     const currentLocale = useLocale();

package/index.esm.js

@@ -104,7 +104,18 @@ const GetAssetTimezoneDocument = {
 
 const customTimeZoneSchema = z.string().nullable();
 /**
+ * Resolves the active timezone based on user preference, custom override, and optional asset location.
  *
+ * Returns `current` (browser or custom override), `preferred` (resolved per user settings
+ * and optional asset), and `assetTimeZone` (fetched from the asset's GPS location).
+ *
+ * **When to use:**
+ * - Use `useTimezone` whenever you need to display or calculate dates in the correct
+ *   timezone — especially on asset-detail pages where the machine's timezone may differ
+ *   from the user's browser timezone.
+ * - Pair with `useDateAndTime` to format dates in the resolved `preferred` timezone.
+ * - Do **not** rely on `Intl.DateTimeFormat().resolvedOptions().timeZone` directly —
+ *   this hook respects the user's preference setting (browser, machine, or custom).
  */
 const useTimezone = ({ assetId } = {}) => {
     const { timeZonePreference } = useCurrentUserTimeZonePreference();
@@ -145,8 +156,18 @@ const useTimezone = ({ assetId } = {}) => {
 };
 
 /**
- * Hook for managing date and time operations.
+ * Hook for locale- and timezone-aware date/time operations including formatting,
+ * arithmetic, comparisons, relative time, and duration formatting.
+ *
+ * ### When to use
+ * Use `useDateAndTime` whenever you need to format, compare, or manipulate dates in a
+ * way that respects the user's locale and timezone.
  *
+ * ### When not to use
+ * - For raw UTC timestamps that never reach the UI — use plain `Date` math or
+ *   `date-and-time-utils` directly.
+ * - For date picker value handling — the date/time components already consume locale
+ *   and timezone internally.
  */
 const useDateAndTime = () => {
     const currentLocale = useLocale();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-date-and-time-hooks",
-  "version": "1.21.19",
+  "version": "1.21.21",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -10,14 +10,14 @@
     "@graphql-codegen/cli": "^5.0.3",
     "@graphql-typed-document-node/core": "^3.2.0",
     "zod": "^3.25.76",
-    "@trackunit/iris-app-api": "1.17.15",
-    "@trackunit/react-core-contexts-test": "1.15.25",
-    "@trackunit/date-and-time-utils": "1.11.113",
-    "@trackunit/shared-utils": "1.13.110",
-    "@trackunit/react-core-hooks": "1.15.25",
-    "@trackunit/react-components": "1.22.16",
-    "@trackunit/react-graphql-hooks": "1.22.16",
-    "@trackunit/iris-app-runtime-core-api": "1.14.24"
+    "@trackunit/iris-app-api": "1.17.17",
+    "@trackunit/react-core-contexts-test": "1.15.27",
+    "@trackunit/date-and-time-utils": "1.11.115",
+    "@trackunit/shared-utils": "1.13.112",
+    "@trackunit/react-core-hooks": "1.15.27",
+    "@trackunit/react-components": "1.22.18",
+    "@trackunit/react-graphql-hooks": "1.22.18",
+    "@trackunit/iris-app-runtime-core-api": "1.14.26"
   },
   "peerDependencies": {
     "@apollo/client": "^3.13.8",

package/src/useDateAndTime.d.ts

@@ -62,8 +62,18 @@ interface UseDateAndTimeReturn {
     formatShortDate: (date: Date | undefined) => string;
 }
 /**
- * Hook for managing date and time operations.
+ * Hook for locale- and timezone-aware date/time operations including formatting,
+ * arithmetic, comparisons, relative time, and duration formatting.
  *
+ * ### When to use
+ * Use `useDateAndTime` whenever you need to format, compare, or manipulate dates in a
+ * way that respects the user's locale and timezone.
+ *
+ * ### When not to use
+ * - For raw UTC timestamps that never reach the UI — use plain `Date` math or
+ *   `date-and-time-utils` directly.
+ * - For date picker value handling — the date/time components already consume locale
+ *   and timezone internally.
  */
 export declare const useDateAndTime: () => UseDateAndTimeReturn;
 export {};

package/src/useTimezone.d.ts

@@ -27,7 +27,18 @@ interface TimezoneProps {
     assetId?: string;
 }
 /**
+ * Resolves the active timezone based on user preference, custom override, and optional asset location.
  *
+ * Returns `current` (browser or custom override), `preferred` (resolved per user settings
+ * and optional asset), and `assetTimeZone` (fetched from the asset's GPS location).
+ *
+ * **When to use:**
+ * - Use `useTimezone` whenever you need to display or calculate dates in the correct
+ *   timezone — especially on asset-detail pages where the machine's timezone may differ
+ *   from the user's browser timezone.
+ * - Pair with `useDateAndTime` to format dates in the resolved `preferred` timezone.
+ * - Do **not** rely on `Intl.DateTimeFormat().resolvedOptions().timeZone` directly —
+ *   this hook respects the user's preference setting (browser, machine, or custom).
  */
 export declare const useTimezone: ({ assetId }?: TimezoneProps) => UseTimezoneReturn;
 export {};