@uktrade/react-component-library 0.10.1 → 0.11.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/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;
@@ -21,10 +22,13 @@ export declare function useApi<T>(key: QueryKey, queryFn: () => Promise<T>): {
     };
 };
 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>;
+    mutation: import("@tanstack/react-query").UseMutationResult<T, Error, void, unknown>;
+    state: {
+        data: T | undefined;
+        isLoading: boolean;
+        isError: boolean;
+        error: Error | null;
+        mutate: import("@tanstack/react-query").UseMutateFunction<T, Error, void, 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,CAAC,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;;;;;;;;;EAa7D"}

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,26 @@ 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, // Full React Query object
+        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.11.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/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 } from "./ApiProvider";
+
+export function createApiHooks<Paths extends {}>(
+  client: ReturnType<typeof createApiClient<Paths>>
+) {
+  // type GetParams<P extends PathsWithMethod<Paths, "get">> =
+  //   Parameters<typeof client.GET<P>>[1];
+
+  return {
+    get: <P extends PathsWithMethod<Paths, "get">>(
+      path: P,
+      params?: any // GetParams<P> More work to be done to fight openapi-fetch’s internal generics!!!!
+    ) => {
+      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  // GetParams<P> More work to be done to fight openapi-fetch’s internal generics!!!!
+    ) => {
+      return useApi(
+        ["post", path, JSON.stringify(params ?? {})],
+        async () => {
+          const res = await client.POST(path, params);
+          if (res.error) throw res.error;
+          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;
+
+  };
+}

package/src/components/ApiQuery/ApiProvider.tsx

@@ -0,0 +1,105 @@
+"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<T>(mutationFn: () => Promise<T>) {
+  const mutation = useMutation({ mutationFn });
+
+  return {
+    mutation, // Full React Query object
+    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";