@trackunit/react-graphql-hooks 1.22.17 → 1.22.19

package/index.cjs.js

@@ -56,6 +56,14 @@ const setupLibraryTranslations = () => {
  * This hook prevents UI flickering during refetches by returning the previous data
  * when new data is loading, unless stableData is set to false.
  *
+ * ### When to use
+ * Use `useLazyQuery` when the query should fire on a user action (button click, form
+ * submit, or after a precondition is met), not on mount.
+ *
+ * ### When not to use
+ * - When data should load immediately on render — use `useQuery`.
+ * - For Relay-style cursor-paginated lists — use `usePaginationQuery`.
+ *
  * @example
  * ```tsx
  * // Basic usage with stable data and polling loading (both are defaults)
@@ -541,6 +549,13 @@ const usePaginationQuery = (document, props) => {
  * This hook prevents UI flickering during refetches by returning the previous data
  * when new data is loading, unless stableData is set to false.
  *
+ * ### When to use
+ * Use `useQuery` for any GraphQL query that should execute on mount and render data.
+ *
+ * ### When not to use
+ * - When the query should fire on a user action — use `useLazyQuery`.
+ * - For Relay-style cursor-paginated lists — use `usePaginationQuery`.
+ *
  * @example
  * ```tsx
  * // Basic usage with stable data and polling loading (both are defaults)

package/index.esm.js

@@ -54,6 +54,14 @@ const setupLibraryTranslations = () => {
  * This hook prevents UI flickering during refetches by returning the previous data
  * when new data is loading, unless stableData is set to false.
  *
+ * ### When to use
+ * Use `useLazyQuery` when the query should fire on a user action (button click, form
+ * submit, or after a precondition is met), not on mount.
+ *
+ * ### When not to use
+ * - When data should load immediately on render — use `useQuery`.
+ * - For Relay-style cursor-paginated lists — use `usePaginationQuery`.
+ *
  * @example
  * ```tsx
  * // Basic usage with stable data and polling loading (both are defaults)
@@ -539,6 +547,13 @@ const usePaginationQuery = (document, props) => {
  * This hook prevents UI flickering during refetches by returning the previous data
  * when new data is loading, unless stableData is set to false.
  *
+ * ### When to use
+ * Use `useQuery` for any GraphQL query that should execute on mount and render data.
+ *
+ * ### When not to use
+ * - When the query should fire on a user action — use `useLazyQuery`.
+ * - For Relay-style cursor-paginated lists — use `usePaginationQuery`.
+ *
  * @example
  * ```tsx
  * // Basic usage with stable data and polling loading (both are defaults)

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@trackunit/react-graphql-hooks",
-  "version": "1.22.17",
+  "version": "1.22.19",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/i18n-library-translation": "1.18.17",
-    "@trackunit/shared-utils": "1.13.111",
+    "@trackunit/i18n-library-translation": "1.18.19",
+    "@trackunit/shared-utils": "1.13.113",
     "es-toolkit": "^1.39.10",
-    "@trackunit/react-components": "1.22.17"
+    "@trackunit/react-components": "1.22.19"
   },
   "peerDependencies": {
     "@apollo/client": "^3.13.8",

package/src/useLazyQuery.d.ts

@@ -22,6 +22,14 @@ export interface LazyQueryProps<TData, TVariables extends ApolloOperationVariabl
  * This hook prevents UI flickering during refetches by returning the previous data
  * when new data is loading, unless stableData is set to false.
  *
+ * ### When to use
+ * Use `useLazyQuery` when the query should fire on a user action (button click, form
+ * submit, or after a precondition is met), not on mount.
+ *
+ * ### When not to use
+ * - When data should load immediately on render — use `useQuery`.
+ * - For Relay-style cursor-paginated lists — use `usePaginationQuery`.
+ *
  * @example
  * ```tsx
  * // Basic usage with stable data and polling loading (both are defaults)

package/src/useQuery.d.ts

@@ -23,6 +23,13 @@ export interface QueryProps<TData, TVariables extends ApolloOperationVariables =
  * This hook prevents UI flickering during refetches by returning the previous data
  * when new data is loading, unless stableData is set to false.
  *
+ * ### When to use
+ * Use `useQuery` for any GraphQL query that should execute on mount and render data.
+ *
+ * ### When not to use
+ * - When the query should fire on a user action — use `useLazyQuery`.
+ * - For Relay-style cursor-paginated lists — use `usePaginationQuery`.
+ *
  * @example
  * ```tsx
  * // Basic usage with stable data and polling loading (both are defaults)