@k-int/stripes-kint-components 5.20.1 → 5.21.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [5.21.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.20.1...v5.21.0) (2025-06-06)
+
+
+### Bug Fixes
+
+* useKiwtSASQuery use state ([7e4f89c](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/commit/7e4f89c6fb4b0a7a64331f55a4647c5c6a9c3464))
+
+
+### Features
+
+* useSettingSection configurability ([8e7b724](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/commit/8e7b724f442c440b1a3d5b36b95300e4417b4d4e))
+
 ## [5.20.1](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.20.0...v5.20.1) (2025-05-14)
 
 

package/es/lib/hooks/useKiwtSASQuery.js

@@ -13,7 +13,8 @@ const locationQuerySetter = _ref => {
   let {
     location,
     history,
-    nsValues
+    nsValues,
+    state
   } = _ref;
   const {
     pathname,
@@ -24,7 +25,13 @@ const locationQuerySetter = _ref => {
   // Do not push to history if the url didn't change
   // https://issues.folio.org/browse/STSMACOM-637
   if (`${pathname}${search}` !== url) {
-    history.push(url);
+    // Only PUSH to history if we're not doing an initialisation OR changing from external-location
+    // This is the SASQ state being used here
+    if (['external-location', 'init.reset'].includes(state?.changeType)) {
+      history.replace(url);
+    } else {
+      history.push(url);
+    }
   }
 };
 const useKiwtSASQuery = () => {
@@ -42,7 +49,8 @@ const useKiwtSASQuery = () => {
   }
   const querySetter = _ref2 => {
     let {
-      nsValues
+      nsValues,
+      ...rest
     } = _ref2;
     setQuery({
       ...query,
@@ -50,6 +58,7 @@ const useKiwtSASQuery = () => {
       qindex
     });
     locationQuerySetter({
+      ...rest,
       location,
       history,
       nsValues

package/es/lib/hooks/usePrevNextPagination.js

@@ -101,7 +101,9 @@ const usePrevNextPagination = function () {
           ...urlQuery,
           page: 1
         };
-        history.push({
+
+        // We use replace instead of push for the defaulting so we don't add unnecessary history entries
+        history.replace({
           pathname: location.pathname,
           search: `?${_queryString.default.stringify(newQuery)}`
         });

package/es/lib/settingsHooks/useSettingSection/useSettingSection.js

@@ -15,9 +15,9 @@ const useSettingSection = _ref => {
       let {
         queryParams
       } = _ref2;
-      const queryNamespace = ['stripes-kint-components', 'useSetting', 'appSettings', queryParams, sectionName];
-      return queryNamespace;
-    }
+      return ['stripes-kint-components', 'useSetting', 'appSettings', queryParams, sectionName];
+    },
+    getMutateNamespaceGenerator = () => ['stripes-kint-components', 'useSetting', 'putSetting', sectionName]
   } = _ref;
   const ky = (0, _core.useOkapiKy)();
   const queryParams = (0, _utils.generateKiwtQueryParams)({
@@ -32,18 +32,22 @@ const useSettingSection = _ref => {
     stats: false
   }, {});
   const {
-    data: settings = []
+    data: settings = [],
+    ...settingsQuery
   } = (0, _reactQuery.useQuery)(getQueryNamespaceGenerator({
     queryParams
   }), () => ky(`${settingEndpoint}?${queryParams?.join('&')}`).json());
   const {
-    mutateAsync: putSetting
-  } = (0, _reactQuery.useMutation)(['stripes-kint-components', 'useSetting', 'putSetting', sectionName], data => ky.put(`${settingEndpoint}${data.id ? '/' + data.id : ''}`, {
+    mutateAsync: putSetting,
+    ...settingsMutate
+  } = (0, _reactQuery.useMutation)(getMutateNamespaceGenerator(), data => ky.put(`${settingEndpoint}${data.id ? '/' + data.id : ''}`, {
     json: data
   }));
   return {
     handleSubmit: putSetting,
-    settings
+    settings,
+    settingsQuery,
+    settingsMutate
   };
 };
 var _default = exports.default = useSettingSection;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-int/stripes-kint-components",
-  "version": "5.20.1",
+  "version": "5.21.0",
   "description": "Stripes Component library for K-Int specific applications",
   "sideEffects": [
     "*.css"

package/src/lib/hooks/useKiwtSASQuery.js

@@ -4,14 +4,22 @@ import { useLocation, useHistory } from 'react-router-dom';
 import buildUrl from '../utils/buildUrl';
 import useQindex from './useQIndex';
 
-const locationQuerySetter = ({ location, history, nsValues }) => {
+const locationQuerySetter = ({ location, history, nsValues, state }) => {
   const { pathname, search } = location;
   const url = buildUrl(location, nsValues);
 
   // Do not push to history if the url didn't change
   // https://issues.folio.org/browse/STSMACOM-637
-  if (`${pathname}${search}` !== url) {
-    history.push(url);
+  if (
+    `${pathname}${search}` !== url
+  ) {
+    // Only PUSH to history if we're not doing an initialisation OR changing from external-location
+    // This is the SASQ state being used here
+    if (['external-location', 'init.reset'].includes(state?.changeType)) {
+      history.replace(url);
+    } else {
+      history.push(url);
+    }
   }
 };
 
@@ -27,9 +35,9 @@ const useKiwtSASQuery = () => {
     setQuery({ ...query, qindex });
   }
 
-  const querySetter = ({ nsValues }) => {
+  const querySetter = ({ nsValues, ...rest }) => {
     setQuery({ ...query, ...nsValues, qindex });
-    locationQuerySetter({ location, history, nsValues });
+    locationQuerySetter({ ...rest, location, history, nsValues });
   };
   return { query, queryGetter, querySetter };
 };

package/src/lib/hooks/usePrevNextPagination.js

@@ -115,7 +115,8 @@ const usePrevNextPagination = ({
           page: 1
         };
 
-        history.push({
+        // We use replace instead of push for the defaulting so we don't add unnecessary history entries
+        history.replace({
           pathname: location.pathname,
           search: `?${queryString.stringify(newQuery)}`
         });

package/src/lib/settingsHooks/useSettingSection/README.md

@@ -1,14 +1,14 @@
 # useSettingSection
 
-A custom hook that retrieves settings data for a given section and provides a handler to update individual settings. It leverages `react-query` to perform asynchronous data fetching and mutations against a specified settings API endpoint.
+A custom React hook designed for fetching and updating settings data from an API. It leverages `react-query` for robust asynchronous data management and provides flexible control over query and mutation keys.
 
 ## Overview
 
-`useSettingSection` is designed to:
-- **Fetch Settings:**  
-  Use `react-query` to request settings that belong to a specific section, based on a filter that matches the provided `sectionName`. The results are sorted by the setting key.
-- **Update Settings:**  
-  Provide a mutation handler (`handleSubmit`) to update a setting. The mutation performs an HTTP PUT request to the API endpoint with the setting data.
+`useSettingSection` simplifies interaction with a settings API by:
+
+* **Fetching Settings:** It retrieves settings for a specific `sectionName`, automatically filtering and sorting the results. Data is cached and managed efficiently by `react-query`.
+* **Updating Settings:** It provides a mutation handler (`handleSubmit`) to send updates for individual settings, performing an HTTP PUT request to your specified endpoint.
+* **Flexible Key Generation:** Offers optional functions to customize the `react-query` keys for both data fetching and mutations, allowing for fine-grained cache control and query invalidation.
 
 ## Basic Usage
 
@@ -38,17 +38,18 @@ const SettingsEditor = ({ sectionName, settingEndpoint }) => {
 
 ## Parameters
 
-| Name             | Type     | Description                                                                                                                                                                  | Required |
-|------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
-| `sectionName`    | `string` | The name of the settings section to fetch. This is used to filter the settings by matching the section property in the API query.                                           | ✓        |
-| `settingEndpoint`| `string` | The base URL endpoint for the settings API. The hook appends query parameters and, in the case of an update, the setting's ID.                                               | ✓        |
+| Name                           | Type       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Required | Default Value                                                                                                                                                                                                                                                           |
+| :----------------------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sectionName`                  | `string`   | The name of the settings section to fetch. This is used in the `generateKiwtQueryParams` call to filter settings by their `section` property.                                                                                                                                                                                                                                                                                                                      | ✓        | None                                                                                                                                                                                                                                                                |
+| `settingEndpoint`              | `string`   | The base URL endpoint for the settings API (e.g., `/settings-storage/settings`). The hook appends query parameters for fetching and, in the case of an update, the setting's ID for PUT requests.                                                                                                                                                                                                                                                                 | ✓        | None                                                                                                                                                                                                                                                                |
+| `getQueryNamespaceGenerator`   | `function` | An optional function that generates the `react-query` key for the settings query. It receives an object `{ queryParams }` as an argument, where `queryParams` is the array of generated Kiwt query parameters. **Customize this for specific caching behaviors or if you need to append additional identifiers to your query key.** | ✕        | `({ queryParams }) => ['stripes-kint-components', 'useSetting', 'appSettings', queryParams, sectionName]`                                                                                                                                                           |
+| `getMutateNamespaceGenerator`  | `function` | An optional function that generates the `react-query` key for the mutation. **Customize this if you need a specific key for your mutation, for example, to differentiate it from other mutations or target specific invalidations.** | ✕        | `() => ['stripes-kint-components', 'useSetting', 'putSetting', sectionName]`                                                                                                                                                                                          |
 
 ## Returns
 
 An object containing:
 
-- **`settings`** (`array`):  
-  The array of settings retrieved from the API. If the query has not completed or returns no data, it defaults to an empty array.
-
-- **`handleSubmit`** (`function`):  
-  A mutation function that accepts a settings data object and performs an HTTP PUT request to update the setting.
+* **`settings`** (`array`): The array of settings retrieved from the API. Defaults to an empty array if the query has not completed or returns no data.
+* **`handleSubmit`** (`function`): A `react-query` mutation function (`mutateAsync`) that accepts a settings data object (e.g., `{ id: 'uuid', key: 'mySetting', value: 'newValue' }`) and performs an HTTP PUT request to update the setting.
+* **`settingsQuery`** (`object`): The `react-query` result object from the `useQuery` hook. This provides detailed query status (e.g., `isLoading`, `isFetching`, `isError`, `data`, `error`).
+* **`settingsMutate`** (`object`): The `react-query` result object from the `useMutation` hook. This provides detailed mutation status (e.g., `isLoading`, `isError`, `isSuccess`, `data`, `error`).

package/src/lib/settingsHooks/useSettingSection/useSettingSection.js

@@ -5,10 +5,8 @@ import { generateKiwtQueryParams } from '../../utils';
 const useSettingSection = ({
   sectionName,
   settingEndpoint,
-  getQueryNamespaceGenerator = ({ queryParams }) => {
-    const queryNamespace = ['stripes-kint-components', 'useSetting', 'appSettings', queryParams, sectionName];
-    return queryNamespace;
-  },
+  getQueryNamespaceGenerator = ({ queryParams }) => ['stripes-kint-components', 'useSetting', 'appSettings', queryParams, sectionName],
+  getMutateNamespaceGenerator = () => ['stripes-kint-components', 'useSetting', 'putSetting', sectionName]
 }) => {
   const ky = useOkapiKy();
   const queryParams = generateKiwtQueryParams({
@@ -27,19 +25,21 @@ const useSettingSection = ({
     stats: false
   }, {});
 
-  const { data: settings = [] } = useQuery(
+  const { data: settings = [], ...settingsQuery } = useQuery(
     getQueryNamespaceGenerator({ queryParams }),
     () => ky(`${settingEndpoint}?${queryParams?.join('&')}`).json()
   );
 
-  const { mutateAsync: putSetting } = useMutation(
-    ['stripes-kint-components', 'useSetting', 'putSetting', sectionName],
+  const { mutateAsync: putSetting, ...settingsMutate } = useMutation(
+    getMutateNamespaceGenerator(),
     (data) => ky.put(`${settingEndpoint}${data.id ? '/' + data.id : ''}`, { json: data })
   );
 
   return ({
     handleSubmit: putSetting,
-    settings
+    settings,
+    settingsQuery,
+    settingsMutate
   });
 };