@uktrade/react-component-library 0.10.1 → 0.12.0

package/Readme.md

@@ -2,8 +2,6 @@
 
 A collection of reusable React components following GOV.UK design patterns.
 
----
-
 ## Table of Contents
 
 * [Installation](#installation)
@@ -12,9 +10,7 @@ A collection of reusable React components following GOV.UK design patterns.
   * [Build](#build)
   * [Playground](#playground)
 
----
-
-## Installation WIP
+## Installation
 
 ```bash
 npm install @uktrade/react-component-library
@@ -25,20 +21,16 @@ npm install @uktrade/react-component-library
 * `react >= 19`
 * `react-dom >= 19`
 
----
-
 ## Usage
 
 Import components from the package:
 
 ```tsx
-import { SummaryList, SummaryItem } from "react-component-library";
+import { SummaryList, SummaryItem } from "@uktrade/react-component-library";
 ```
 
 You can use them directly in your React applications.
 
----
-
 ## Development
 
 ### Build

package/dist/components/ApiBoundary/ApiBoundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiBoundary.d.ts","sourceRoot":"","sources":["../../../src/components/ApiBoundary/ApiBoundary.tsx"],"names":[],"mappings":"AAKA,UAAU,gBAAgB;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAGD,eAAO,MAAM,WAAW,GAAI,mDAMzB,gBAAgB,4CAuBlB,CAAC"}
+{"version":3,"file":"ApiBoundary.d.ts","sourceRoot":"","sources":["../../../src/components/ApiBoundary/ApiBoundary.tsx"],"names":[],"mappings":"AAKA,UAAU,gBAAgB;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAGD,eAAO,MAAM,WAAW,GAAI,mDAMzB,gBAAgB,4CAwBlB,CAAC"}

package/dist/components/ApiBoundary/ApiBoundary.js

@@ -4,4 +4,4 @@ import { LoadingSpinner } from "../LoadingSpinner/LoadingSpinner";
 import styles from "./ApiBoundary.module.css";
 import { Button } from "../Button";
 /* Boundary for API-related states: loading, success, and error */
-export const ApiBoundary = ({ isLoading, isError, error, onRetry, children, }) => (_jsxs("div", { className: styles.root, "aria-live": "polite", children: [isLoading && _jsx(LoadingSpinner, {}), !isLoading && !isError && children, isError && (_jsxs(_Fragment, { children: [_jsx("div", { className: styles.errorBackdrop }), _jsxs("section", { className: styles.error, children: [_jsx("h2", { className: "govuk-heading-m", children: "Error!" }), _jsx("pre", { className: styles.description, children: typeof error === "string" ? error : JSON.stringify(error, null, 2) }), _jsx(Button, { variant: "warning", onClick: onRetry, children: "Retry" })] })] }))] }));
+export const ApiBoundary = ({ isLoading, isError, error, onRetry, children, }) => (_jsxs("div", { className: styles.root, "aria-live": "polite", children: [isLoading && _jsx(LoadingSpinner, {}), !isLoading && !isError && children, isError && (_jsxs(_Fragment, { children: [_jsx("div", { className: styles.errorBackdrop }), _jsxs("section", { className: styles.error, children: [_jsx("h2", { className: "govuk-heading-m", children: "Error!" }), _jsx("pre", { className: styles.description, children: typeof error === "string" ? error : JSON.stringify(error, null, 2) }), onRetry && (_jsx(Button, { variant: "warning", onClick: onRetry, children: "Retry" }))] })] }))] }));

package/dist/components/ApiQuery/ApiCreateHooks.d.ts

@@ -21,5 +21,45 @@ export declare function createApiHooks<Paths extends {}>(client: ReturnType<type
             refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<any, Error>>;
         };
     };
+    postMutation: <P extends PathsWithMethod<Paths, "post">>(path: P) => {
+        mutation: import("@tanstack/react-query").UseMutationResult<any, unknown, any, unknown>;
+        state: {
+            data: any;
+            isLoading: boolean;
+            isError: boolean;
+            error: unknown;
+            mutate: import("@tanstack/react-query").UseMutateFunction<any, unknown, any, unknown>;
+        };
+    };
+    putMutation: <P extends PathsWithMethod<Paths, "put">>(path: P) => {
+        mutation: import("@tanstack/react-query").UseMutationResult<any, unknown, any, unknown>;
+        state: {
+            data: any;
+            isLoading: boolean;
+            isError: boolean;
+            error: unknown;
+            mutate: import("@tanstack/react-query").UseMutateFunction<any, unknown, any, unknown>;
+        };
+    };
+    patchMutation: <P extends PathsWithMethod<Paths, "patch">>(path: P) => {
+        mutation: import("@tanstack/react-query").UseMutationResult<any, unknown, any, unknown>;
+        state: {
+            data: any;
+            isLoading: boolean;
+            isError: boolean;
+            error: unknown;
+            mutate: import("@tanstack/react-query").UseMutateFunction<any, unknown, any, unknown>;
+        };
+    };
+    deleteMutation: <P extends PathsWithMethod<Paths, "delete">>(path: P) => {
+        mutation: import("@tanstack/react-query").UseMutationResult<any, unknown, any, unknown>;
+        state: {
+            data: any;
+            isLoading: boolean;
+            isError: boolean;
+            error: unknown;
+            mutate: import("@tanstack/react-query").UseMutateFunction<any, unknown, any, unknown>;
+        };
+    };
 };
 //# sourceMappingURL=ApiCreateHooks.d.ts.map

package/dist/components/ApiQuery/ApiCreateHooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiCreateHooks.d.ts","sourceRoot":"","sources":["../../../src/components/ApiQuery/ApiCreateHooks.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,wBAAgB,cAAc,CAAC,KAAK,SAAS,EAAE,EAC7C,MAAM,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;UAMzC,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,QACrC,CAAC,WACE,GAAG;;;;;;;;;;WAYP,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,QACvC,CAAC,WACE,GAAG;;;;;;;;;;EA6CjB"}
+{"version":3,"file":"ApiCreateHooks.d.ts","sourceRoot":"","sources":["../../../src/components/ApiQuery/ApiCreateHooks.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,wBAAgB,cAAc,CAAC,KAAK,SAAS,EAAE,EAC7C,MAAM,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;UAOzC,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,QACrC,CAAC,WACE,GAAG;;;;;;;;;;WAYP,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,QACvC,CAAC,WACE,GAAG;;;;;;;;;;mBAYC,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC;;;;;;;;;;kBAQlD,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;;;;;;;;;;oBAQ9C,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC;;;;;;;;;;qBAQjD,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC;;;;;;;;;;EAQvE"}

package/dist/components/ApiQuery/ApiCreateHooks.js

@@ -1,12 +1,12 @@
 "use client";
 import { createApiClient } from "./ApiCreateClient";
-import { useApi } from "./ApiProvider";
+import { useApi, useApiMutation } from "./ApiProvider";
 export function createApiHooks(client) {
+    // ToDo: Generalize this (params?: any) and fight openapi-fetch’s internal generics to get correct types from PathsWithMethod. Same for the mutation methods.
     // type GetParams<P extends PathsWithMethod<Paths, "get">> =
     //   Parameters<typeof client.GET<P>>[1];
     return {
-        get: (path, params // GetParams<P> More work to be done to fight openapi-fetch’s internal generics!!!!
-        ) => {
+        get: (path, params) => {
             return useApi(["get", path, JSON.stringify(params ?? {})], async () => {
                 const res = await client.GET(path, params);
                 if (res.error)
@@ -14,8 +14,7 @@ export function createApiHooks(client) {
                 return res.data;
             });
         },
-        post: (path, params // GetParams<P> More work to be done to fight openapi-fetch’s internal generics!!!!
-        ) => {
+        post: (path, params) => {
             return useApi(["post", path, JSON.stringify(params ?? {})], async () => {
                 const res = await client.POST(path, params);
                 if (res.error)
@@ -23,33 +22,37 @@ export function createApiHooks(client) {
                 return res.data;
             });
         },
-        // TODO: implement other methods (put, delete), furthermore generalize the mutation method
-        // for all methods (No GET) to avoid React Query’s useQuery from running automatically on mount
-        // Same here (params?: any)
-        // postMutation: <P extends PathsWithMethod<Paths, "post">>(path: P, params?: any) => {
-        //   return useApiMutation(async () => {
-        //     const res = await client.POST(path, params);
-        //     if (res.error) throw res.error;
-        //     return res.data;
-        //   });
-        // },
-        // mutation: <
-        //   M extends "post" | "put" | "patch" | "delete",
-        //   P extends PathsWithMethod<Paths, M>
-        // >(
-        //   method: M,
-        //   path: P,
-        //   params?: any
-        // ) => {
-        //   return useApiMutation(async () => {
-        //     const res = await client[method.toUpperCase() as "POST" | "PUT" | "PATCH" | "DELETE"](path, params);
-        //     if (res.error) throw res.error;
-        //     return res.data;
-        //   });
-        // }
-        // ToDo: Generalize this:
-        // const res = await client.POST(path, params);
-        // if (res.error) throw res.error;
-        // return res.data;
+        postMutation: (path) => {
+            return useApiMutation(async (params) => {
+                const res = await client.POST(path, params);
+                if (res.error)
+                    throw res.error;
+                return res.data;
+            });
+        },
+        putMutation: (path) => {
+            return useApiMutation(async (params) => {
+                const res = await client.PUT(path, params);
+                if (res.error)
+                    throw res.error;
+                return res.data;
+            });
+        },
+        patchMutation: (path) => {
+            return useApiMutation(async (params) => {
+                const res = await client.PATCH(path, params);
+                if (res.error)
+                    throw res.error;
+                return res.data;
+            });
+        },
+        deleteMutation: (path) => {
+            return useApiMutation(async (params) => {
+                const res = await client.DELETE(path, params);
+                if (res.error)
+                    throw res.error;
+                return res.data;
+            });
+        },
     };
 }

package/dist/components/ApiQuery/ApiProvider.d.ts

@@ -1,5 +1,6 @@
-import { type QueryKey } from "@tanstack/react-query";
+import { QueryClient, type QueryKey } from "@tanstack/react-query";
 import type { ReactNode } from "react";
+export declare function getQueryClient(): QueryClient;
 export declare function ApiProvider({ children }: {
     children: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
@@ -20,11 +21,14 @@ export declare function useApi<T>(key: QueryKey, queryFn: () => Promise<T>): {
         refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<import("@tanstack/query-core").NoInfer<T>, Error>>;
     };
 };
-export declare function useApiMutation<T>(mutationFn: () => Promise<T>): {
-    data: T | undefined;
-    isLoading: boolean;
-    isError: boolean;
-    error: Error | null;
-    mutate: import("@tanstack/react-query").UseMutateFunction<T, Error, void, unknown>;
+export declare function useApiMutation<TData, TVariables = void>(mutationFn: (variables: TVariables) => Promise<TData>): {
+    mutation: import("@tanstack/react-query").UseMutationResult<TData, unknown, TVariables, unknown>;
+    state: {
+        data: TData | undefined;
+        isLoading: boolean;
+        isError: boolean;
+        error: unknown;
+        mutate: import("@tanstack/react-query").UseMutateFunction<TData, unknown, TVariables, unknown>;
+    };
 };
 //# sourceMappingURL=ApiProvider.d.ts.map

package/dist/components/ApiQuery/ApiProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiProvider.d.ts","sourceRoot":"","sources":["../../../src/components/ApiQuery/ApiProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAsBvC,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAOhE;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC7B,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;;;;;;;;;EAgBjE;AAWD,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;;;;;;EAU7D"}
+{"version":3,"file":"ApiProvider.d.ts","sourceRoot":"","sources":["../../../src/components/ApiQuery/ApiProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EAIX,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AASvC,wBAAgB,cAAc,gBAa7B;AAMD,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAMhE;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC7B,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAYF,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;;;;;;;;;EAgBjE;AAYD,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,EACrD,UAAU,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,OAAO,CAAC,KAAK,CAAC;;;;;;;;;EAgBtD"}

package/dist/components/ApiQuery/ApiProvider.js

@@ -1,10 +1,13 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { QueryClient, QueryClientProvider, useQuery, useMutation } from "@tanstack/react-query";
-// To avoid cache duplication bugs we make sure to have one single queryClient object
-// per app.
+// To avoid cache duplication bugs we make sure to have
+// one single queryClient object per app.
 let queryClient;
-function getQueryClient() {
+// Creates (once) and returns a shared QueryClient instance for the entire application.
+// React Query relies on a single client to manage caching, retries, and background updates.
+// This function ensures that only one instance is ever created.
+export function getQueryClient() {
     if (!queryClient) {
         // Stores all query state, retries, and caching 
         queryClient = new QueryClient({
@@ -18,12 +21,23 @@ function getQueryClient() {
     }
     return queryClient;
 }
-// Wrapper around `QueryClientProvider`  
+// A React component that wraps the application with React Query’s QueryClientProvider.
+// It injects the singleton QueryClient into React Query’s context so that all hooks (useQuery, useMutation, etc.)
+// share the same cache and configuration.
+// Every component that uses React Query must be rendered inside this provider.
 export function ApiProvider({ children }) {
-    return (
-    // Injects the client into React Query’s context
-    _jsx(QueryClientProvider, { client: getQueryClient(), children: children }));
+    return (_jsx(QueryClientProvider, { client: getQueryClient(), children: children }));
 }
+/*
+A generic wrapper around React Query’s useQuery. It is not tied to GET requests, it is used for any API operation that should
+- run automatically on mount
+- cache results
+- support refetching
+
+It accepts a `key` (unique identifier for the query) and a `queryFn` (function that fetches the data). It returns:
+- `query` — the full React Query query object
+- `state` — a simplified structure with commonly used properties like `data`, `isLoading`, `isError`
+*/
 export function useApi(key, queryFn) {
     // From React Query queryKey and queryFn.
     // `queryKey` is a unique identifier for this query (React Query uses it for caching and refetching).
@@ -40,20 +54,28 @@ export function useApi(key, queryFn) {
         },
     };
 }
-// export function useApi<T>(key: QueryKey, queryFn: () => Promise<T>): ApiQueryState<T> {
-//   const { data, isFetching, isError, error, refetch } = useQuery({
-//     queryKey: key,
-//     queryFn,
-//   });
-//   return { data, isLoading: isFetching, isError, error, refetch };
-// }
+/*
+A wrapper around React Query’s `useMutation` hook for POST/PUT/PATCH/DELETE operations. It is used for:
+- operations that do not run automatically on mount
+- operations that do not cache results
+
+It accepts `mutationFn` as function that performs the mutation request, and It returns:
+
+- `mutation` — the full React Query mutation object
+- `state` — a simplified structure with commonly used properties like `data`, `isLoading`, `isError`
+*/
 export function useApiMutation(mutationFn) {
-    const { data, isPending, isError, error, mutate } = useMutation({ mutationFn });
+    const mutation = useMutation({
+        mutationFn,
+    });
     return {
-        data,
-        isLoading: isPending,
-        isError,
-        error,
-        mutate,
+        mutation,
+        state: {
+            data: mutation.data,
+            isLoading: mutation.isPending,
+            isError: mutation.isError,
+            error: mutation.error,
+            mutate: mutation.mutate,
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uktrade/react-component-library",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "A collection of reusable React components following GOV.UK design patterns.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/components/ApiBoundary/ApiBoundary.tsx

@@ -33,10 +33,11 @@ export const ApiBoundary = ({
             {typeof error === "string" ? error : JSON.stringify(error, null, 2)}
           </pre>
           
-          {/* TODO: Make this button optional since it cannot always be required */}
-          <Button variant="warning" onClick={onRetry}>
-            Retry
-          </Button>
+          {onRetry && (
+            <Button variant="warning" onClick={onRetry}>
+              Retry
+            </Button>
+          )}
         </section>
       </>
     )}

package/src/components/ApiQuery/ApiCreateClient.tsx

@@ -0,0 +1,17 @@
+import createClient from "openapi-fetch";
+import type { ClientOptions } from "openapi-fetch";
+
+// `extends {}` required to fix type error (Type 'Paths' does not satisfy the constraint '{}'.)
+export function createApiClient<Paths extends {}>(
+  options?: ClientOptions
+) {
+  const defaultOptions: Partial<ClientOptions> = {
+    baseUrl: "/api",
+    credentials: "include",
+  };
+
+  // Merge/Override user options with the defaults
+  const finalOptions = { ...defaultOptions, ...options };
+
+  return createClient<Paths>(finalOptions);
+}

package/src/components/ApiQuery/ApiCreateHooks.tsx

@@ -0,0 +1,76 @@
+"use client"
+
+import type { PathsWithMethod } from "openapi-typescript-helpers";
+
+import { createApiClient } from "./ApiCreateClient";
+import { useApi, useApiMutation } from "./ApiProvider";
+
+export function createApiHooks<Paths extends {}>(
+  client: ReturnType<typeof createApiClient<Paths>>
+) {
+  // ToDo: Generalize this (params?: any) and fight openapi-fetch’s internal generics to get correct types from PathsWithMethod. Same for the mutation methods.
+  // type GetParams<P extends PathsWithMethod<Paths, "get">> =
+  //   Parameters<typeof client.GET<P>>[1];
+
+  return {
+    get: <P extends PathsWithMethod<Paths, "get">>(
+      path: P,
+      params?: any
+    ) => {
+      return useApi(
+        ["get", path, JSON.stringify(params ?? {})],
+        async () => {
+          const res = await client.GET(path, params);
+          if (res.error) throw res.error;
+          return res.data;
+        }
+      );
+    },
+
+    post: <P extends PathsWithMethod<Paths, "post">>(
+      path: P,
+      params?: any
+    ) => {
+      return useApi(
+        ["post", path, JSON.stringify(params ?? {})],
+        async () => {
+          const res = await client.POST(path, params);
+          if (res.error) throw res.error;
+          return res.data;
+        }
+      );
+    },
+
+    postMutation: <P extends PathsWithMethod<Paths, "post">>(path: P) => {
+      return useApiMutation(async (params: any) => {
+        const res = await client.POST(path, params);
+        if (res.error) throw res.error;
+        return res.data;
+      });
+    },
+
+    putMutation: <P extends PathsWithMethod<Paths, "put">>(path: P) => {
+      return useApiMutation(async (params: any) => {
+        const res = await client.PUT(path, params);
+        if (res.error) throw res.error;
+        return res.data;
+      });
+    },
+
+    patchMutation: <P extends PathsWithMethod<Paths, "patch">>(path: P) => {
+      return useApiMutation(async (params: any) => {
+        const res = await client.PATCH(path, params);
+        if (res.error) throw res.error;
+        return res.data;
+      });
+    },
+
+    deleteMutation: <P extends PathsWithMethod<Paths, "delete">>(path: P) => {
+      return useApiMutation(async (params: any) => {
+        const res = await client.DELETE(path, params);
+        if (res.error) throw res.error;
+        return res.data;
+      });
+    },
+  };
+}

package/src/components/ApiQuery/ApiProvider.tsx

@@ -0,0 +1,110 @@
+"use client"
+
+import {
+  QueryClient,
+  QueryClientProvider,
+  useQuery,
+  useMutation,
+  type QueryKey
+} from "@tanstack/react-query";
+import type { ReactNode } from "react";
+
+// To avoid cache duplication bugs we make sure to have
+// one single queryClient object per app.
+let queryClient: QueryClient | undefined;
+
+// Creates (once) and returns a shared QueryClient instance for the entire application.
+// React Query relies on a single client to manage caching, retries, and background updates.
+// This function ensures that only one instance is ever created.
+export function getQueryClient() {
+  if (!queryClient) {
+    // Stores all query state, retries, and caching 
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+          refetchOnWindowFocus: false,
+        },
+      },
+    });
+  }
+  return queryClient;
+}
+
+// A React component that wraps the application with React Query’s QueryClientProvider.
+// It injects the singleton QueryClient into React Query’s context so that all hooks (useQuery, useMutation, etc.)
+// share the same cache and configuration.
+// Every component that uses React Query must be rendered inside this provider.
+export function ApiProvider({ children }: { children: ReactNode }) {
+  return (
+    <QueryClientProvider client={getQueryClient()}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+
+export type ApiQueryState<T> = {
+  data?: T;
+  isLoading: boolean;
+  isError: boolean;
+  error?: unknown;
+  refetch: () => void;
+};
+
+/*
+A generic wrapper around React Query’s useQuery. It is not tied to GET requests, it is used for any API operation that should
+- run automatically on mount
+- cache results
+- support refetching
+
+It accepts a `key` (unique identifier for the query) and a `queryFn` (function that fetches the data). It returns:
+- `query` — the full React Query query object  
+- `state` — a simplified structure with commonly used properties like `data`, `isLoading`, `isError`
+*/
+export function useApi<T>(key: QueryKey, queryFn: () => Promise<T>) {
+  // From React Query queryKey and queryFn.
+  // `queryKey` is a unique identifier for this query (React Query uses it for caching and refetching).
+  // `queryFn` is the function that actually fetches the data, API call by using openapi-fetch module.
+  const query = useQuery({ queryKey: key, queryFn });
+
+  return {
+    query, // raw data to make sure you do not block full React Query object from propagating
+    state: {
+      data: query.data, // fetched data
+      isLoading: query.isFetching, // boolean for current fetch in progress
+      isError: query.isError, // boolean for error state
+      error: query.error, // error object if it failed
+      refetch: query.refetch, // function to manually re-run the query
+    },
+  };
+}
+
+/*
+A wrapper around React Query’s `useMutation` hook for POST/PUT/PATCH/DELETE operations. It is used for:
+- operations that do not run automatically on mount
+- operations that do not cache results
+
+It accepts `mutationFn` as function that performs the mutation request, and It returns:
+
+- `mutation` — the full React Query mutation object  
+- `state` — a simplified structure with commonly used properties like `data`, `isLoading`, `isError`
+*/
+export function useApiMutation<TData, TVariables = void>(
+  mutationFn: (variables: TVariables) => Promise<TData>
+) {
+  const mutation = useMutation<TData, unknown, TVariables>({
+    mutationFn,
+  });
+
+  return {
+    mutation,
+    state: {
+      data: mutation.data,
+      isLoading: mutation.isPending,
+      isError: mutation.isError,
+      error: mutation.error,
+      mutate: mutation.mutate,
+    },
+  };
+}
+

package/src/components/ApiQuery/index.ts

@@ -0,0 +1,3 @@
+export * from "./ApiCreateClient";
+export * from "./ApiProvider";
+export * from "./ApiCreateHooks";

package/src/index.ts

@@ -9,4 +9,5 @@ export * from "./components/Button";
 export * from "./components/ButtonGroup";
 export * from "./components/BackLink";
 export * from "./components/LoadingSpinner/LoadingSpinner";
-export * from "./components/ApiBoundary/ApiBoundary";
+export * from "./components/ApiBoundary/ApiBoundary";
+export * from "./components/ApiQuery";