@k-int/stripes-kint-components 5.12.0 → 5.14.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [5.14.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.13.0...v5.14.0) (2025-02-19)
+
+
+### Features
+
+* Added filterConfig options to generateKiwtQueryParams ([8502b91](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/commit/8502b91beef93065a24c1b1ab6ed4b73759b851d))
+
+# [5.13.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.12.0...v5.13.0) (2025-02-17)
+
+
+### Features
+
+* On rendering SASQLookupComponent, do not fetch resources until a query is provided ([00c45a5](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/commit/00c45a54307d1564d15e6d1268fc067c2c04994e))
+
 # [5.12.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.11.0...v5.12.0) (2025-02-13)
 
 

package/es/lib/SASQLookupComponent/SASQLookupComponent.js

@@ -77,7 +77,7 @@ const SASQLookupComponent = /*#__PURE__*/(0, _react.forwardRef)((props, ref) =>
   } = (0, _reactQuery.useQuery)(queryNamespace, () => {
     return ky.get(`${fetchParameters.endpoint}${queryParams}`).json();
   }, {
-    enabled: !!currentPage
+    enabled: (!!query?.filters || !!query?.query) && !!currentPage
   });
   (0, _react.useEffect)(() => {
     if (count !== data?.totalRecords) {

package/es/lib/utils/generateKiwtQuery.js

@@ -4,11 +4,10 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _generateKiwtQueryParams = _interopRequireDefault(require("./generateKiwtQueryParams"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _generateKiwtQueryParams = require("./generateKiwtQueryParams");
 const generateKiwtQuery = function (options, nsValues) {
   let encode = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
-  const paramsArray = (0, _generateKiwtQueryParams.default)(options, nsValues, encode);
+  const paramsArray = (0, _generateKiwtQueryParams.generateKiwtQueryParams)(options, nsValues, encode);
   return paramsArray.length ? '?' + paramsArray.join('&') : '';
 };
 var _default = exports.default = generateKiwtQuery;

package/es/lib/utils/{generateKiwtQueryParams.js → generateKiwtQueryParams/generateKiwtQueryParams.js}

@@ -134,8 +134,11 @@ const generateKiwtQueryParams = function (options, nsValues) {
       if (filterConfigEntry) {
         // We have a direct mapping instruction, use it
         const filterString = filterValues.map(v => {
-          const fceValue = filterConfigEntry?.values?.find(fce => fce.name === v)?.value;
-          return `${filterName}==${fceValue ?? v}`;
+          const fcValueEntry = filterConfigEntry?.values?.find(fce => fce.name === v) ?? {};
+          const fceValue = fcValueEntry.value ?? v;
+          // This is especially useful where comparator acts strangely for a single value, such as `filters=foo isNotSet`
+          const fceComparator = fcValueEntry.comparator ?? '==';
+          return `${filterKey ?? filterName}${fceComparator}${fceValue ?? v}`;
         }).join('||');
         paramsArray.push(`filters=${conditionalEncodeURIComponent(filterString, encode)}`);
       } else if (!filterKey) {

package/es/lib/utils/generateKiwtQueryParams/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "generateKiwtQueryParams", {
+  enumerable: true,
+  get: function () {
+    return _generateKiwtQueryParams.default;
+  }
+});
+var _generateKiwtQueryParams = _interopRequireDefault(require("./generateKiwtQueryParams"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/es/lib/utils/index.js

@@ -36,7 +36,7 @@ Object.defineProperty(exports, "generateKiwtQuery", {
 Object.defineProperty(exports, "generateKiwtQueryParams", {
   enumerable: true,
   get: function () {
-    return _generateKiwtQueryParams.default;
+    return _generateKiwtQueryParams.generateKiwtQueryParams;
   }
 });
 Object.defineProperty(exports, "groupCustomPropertiesByCtx", {
@@ -136,7 +136,7 @@ Object.defineProperty(exports, "typedownQueryKey", {
   }
 });
 var _generateKiwtQuery = _interopRequireDefault(require("./generateKiwtQuery"));
-var _generateKiwtQueryParams = _interopRequireDefault(require("./generateKiwtQueryParams"));
+var _generateKiwtQueryParams = require("./generateKiwtQueryParams");
 var _selectorSafe = _interopRequireDefault(require("./selectorSafe"));
 var _buildUrl = _interopRequireDefault(require("./buildUrl"));
 var _refdataOptions = _interopRequireDefault(require("./refdataOptions"));

package/package.json

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

package/src/lib/SASQLookupComponent/SASQLookupComponent.js

@@ -93,7 +93,7 @@ const SASQLookupComponent = forwardRef((props, ref) => {
       return ky.get(`${fetchParameters.endpoint}${queryParams}`).json();
     },
     {
-      enabled: !!currentPage,
+      enabled: (!!query?.filters || !!query?.query) && !!currentPage,
     }
   );
 

package/src/lib/utils/README.md

@@ -3,7 +3,7 @@
 ## generateKiwtQuery
 
 The `generateKiwtQuery` function generates a URL query string in "KIWT" (K-Int Web Toolkit) style from a SASQ (Search and Sort Query) object. It handles search terms, filters, sorting, and other parameters, making it easy to construct complex query strings for backend APIs.
-
+This component calls and then joins the output of `generateKiwtQueryParams`. For more granular information on how this works, see the generateKiwtQueryParams README.
 ### Basic Usage
 
 ```javascript
@@ -39,105 +39,3 @@ const queryString = generateKiwtQuery(options, nsValues);
 | options | object | An object with keys: `searchKey`, `filterKeys`, `sortKeys`, and `stats`, which maps the incoming `nsValues` object to a KIWT query. You can also pass arbitrary `key`/`value` pairs to append `key==value` onto the query. |  | ✓ |
 | nsValues | object | An object containing the query parameters.  Can contain `query`, `filters`, and `sort`, as well as any other arbitrary parameters. |  | ✓ |
 | encode | boolean | A boolean indicating whether to URL-encode the values. | `true` | ✕ |
-
-## generateKiwtQueryParams
-
-The `generateKiwtQueryParams` function is similar to `generateKiwtQuery`, but instead of returning a string, it returns an array of query parameters. This can be useful for more advanced use cases where you need to manipulate the parameters before constructing the final query string.
-
-### Basic Usage
-
-```javascript
-import { generateKiwtQueryParams } from '@k-int/stripes-kint-components';
-
-const nsValues = {
-  query: 'test',
-  filters: 'requestStatus.completed,journalVolume.test1,startDate.startDate>=2021-10-28'
-};
-
-const options = {
-  searchKey: 'request.name',
-  filterKeys: {
-    requestStatus: 'requestStatus.value',
-    journalVolume: 'journalVolume'
-  }
-};
-
-const queryArray = generateKiwtQueryParams(options, nsValues);
-
-// queryArray will be:
-// [
-//   "match=request.name",
-//   "term=test",
-//   "filters=requestStatus.value==completed",
-//   "filters=journalVolume==test1",
-//   "filters=startDate%3E=2021-10-28",
-//   "stats=true"
-// ]
-```
-
-### Props
-
-| Name | Type | Description | Default | Required |
-|---|---|---|---|---|
-| options | object | An object with keys: `searchKey`, `filterKeys`, `sortKeys`, and `stats`, which maps the incoming `nsValues` object to a KIWT query array. You can also pass arbitrary `key`/`value` pairs to append `key==value` onto the query. |  | ✓ |
-| nsValues | object | An object containing the query parameters. Can contain `query`, `filters`, and `sort`, as well as any other arbitrary parameters. |  | ✓ |
-| encode | boolean | A boolean indicating whether to URL-encode the values. | `true` | ✕ |
-
-
-### Options Parameter Structure
-
-The `options` parameter is a powerful tool for customizing the query string generation. It has the following key elements:
-
-*   **Search:**
-    *   `searchKey`: Specifies the field to search on. If using SASQ, the corresponding value in `nsValues.query` will be used as the search term. Otherwise, you can directly specify the search term using the `term` key in `options`.
-*   **Filters:** See the "Filters Object Structure" section below for details.
-*   **Sorting:**
-    *   `sortKeys`: An object mapping sort field names from `nsValues.sort` to their corresponding backend keys.
-    *   `sort`: An array of sort objects. Each object can have `path` (field to sort on) and `direction` (`asc` or `desc`).
-*   **Statistics:**
-    *   `stats`: A boolean value indicating whether to include the `stats=true` parameter.
-*   **Other parameters:** Any other key-value pairs in the `options` object will be directly added as query parameters.
-
-
-### Filters Object Structure
-
-The `filters` option in the `options` parameter allows you to define complex filter expressions using an array of filter objects. Each filter object can have the following properties:
-
-*   **path:** The path to the field to filter on (e.g., `item.title`).
-*   **comparator:** *(Optional)* The comparator to use for the filter (e.g., `==`, `!=`, `>`, `<`). Defaults to `==`.
-*   **value:** A single value to filter on.
-*   **values:** An array of values to filter on. If present, this property takes precedence over `value`, and an `OR` condition is implied between the values.
-*   **groupValues:** An object defining nested filter groups with `AND` or `OR` logic. This property allows for building complex nested filters. See the explanation below.
-
-#### Nested Filter Groups (`groupValues`)
-
-The `groupValues` property enables the creation of nested filter expressions with `AND` and `OR` logic. It is an object with either `AND` or `OR` properties (or both, with `AND` taking precedence). The value of these properties should be an array of filter objects, allowing for recursive nesting.
-
-```javascript
-// Example: (status==active AND type==local) OR (status==pending)
-const filters = [
-  {
-    groupValues: {
-      OR: [
-        {
-          groupValues: {
-            AND: [
-              { path: 'item.status', value: 'active' },
-              { path: 'item.type', value: 'local' },
-            ],
-          }
-        },
-        { path: 'item.status', value: 'pending' },
-      ]
-    },
-  },
-];
-```
-
-This structure allows you to express complex filter logic in a clear and organized way.
-
-### Key Takeaways
-
-*   `generateKiwtQuery` provides a flexible way to construct URL query strings for backend APIs, especially when working with Stripes SASQ.
-*   The `options` parameter offers fine-grained control over the query generation process, allowing for complex filtering, sorting, and other customizations.
-*   `generateKiwtQueryParams` is useful for advanced use cases where you need to manipulate the parameters before constructing the final query string.

package/src/lib/utils/generateKiwtQuery.js

@@ -1,4 +1,4 @@
-import generateKiwtQueryParams from './generateKiwtQueryParams';
+import { generateKiwtQueryParams } from './generateKiwtQueryParams';
 
 const generateKiwtQuery = (options, nsValues, encode = true) => {
   const paramsArray = generateKiwtQueryParams(options, nsValues, encode);

package/src/lib/utils/generateKiwtQueryParams/README.md

@@ -0,0 +1,199 @@
+# generateKiwtQueryParams
+
+The `generateKiwtQueryParams` function is similar to `generateKiwtQuery`, but instead of returning a string, it returns an array of query parameters. This can be useful for more advanced use cases where you need to manipulate the parameters before constructing the final query string.
+
+## Basic Usage
+
+```javascript
+import { generateKiwtQueryParams } from '@k-int/stripes-kint-components';
+
+const nsValues = {
+  query: 'test',
+  filters: 'requestStatus.completed,journalVolume.test1,startDate.startDate>=2021-10-28'
+};
+
+const options = {
+  searchKey: 'request.name',
+  filterKeys: {
+    requestStatus: 'requestStatus.value',
+    journalVolume: 'journalVolume'
+  }
+};
+
+const queryArray = generateKiwtQueryParams(options, nsValues);
+
+// queryArray will be:
+// [
+//   "match=request.name",
+//   "term=test",
+//   "filters=requestStatus.value==completed",
+//   "filters=journalVolume==test1",
+//   "filters=startDate%3E=2021-10-28",
+//   "stats=true"
+// ]
+```
+
+## Props
+
+| Name | Type | Description | Default | Required |
+|---|---|---|---|---|
+| options | object | An object with keys: `searchKey`, `filterKeys`, `sortKeys`, and `stats`, which maps the incoming `nsValues` object to a KIWT query array. You can also pass arbitrary `key`/`value` pairs to append `key==value` onto the query. |  | ✓ |
+| nsValues | object | An object containing the query parameters. Can contain `query`, `filters`, and `sort`, as well as any other arbitrary parameters. |  | ✓ |
+| encode | boolean | A boolean indicating whether to URL-encode the values. | `true` | ✕ |
+
+
+## Options Parameter Structure
+
+The `options` parameter is a powerful tool for customizing the query string generation manually. It has the following key elements:
+
+*   **Search:**
+    *   `searchKey`: Specifies the field to search on. If using SASQ, the corresponding value in `nsValues.query` will be used as the search term. Otherwise, you can directly specify the search term using the `term` key in `options`.
+*   **Filters:** See the "Filters Object Structure" section below for details.
+*   **Sorting:**
+    *   `sortKeys`: An object mapping sort field names from `nsValues.sort` to their corresponding backend keys.
+    *   `sort`: An array of sort objects. Each object can have `path` (field to sort on) and `direction` (`asc` or `desc`).
+*   **Statistics:**
+    *   `stats`: A boolean value indicating whether to include the `stats=true` parameter.
+*   **Other parameters:** Any other key-value pairs in the `options` object will be directly added as query parameters.
+
+
+### Filters Object Structure
+
+The `filters` option in the `options` parameter allows you to define complex filter expressions using an array of filter objects. Each filter object can have the following properties:
+
+*   **path:** The path to the field to filter on (e.g., `item.title`).
+*   **comparator:** *(Optional)* The comparator to use for the filter (e.g., `==`, `!=`, `>`, `<`). Defaults to `==`.
+*   **value:** A single value to filter on.
+*   **values:** An array of values to filter on. If present, this property takes precedence over `value`, and an `OR` condition is implied between the values.
+*   **groupValues:** An object defining nested filter groups with `AND` or `OR` logic. This property allows for building complex nested filters. See the explanation below.
+
+### Nested Filter Groups (`groupValues`)
+
+The `groupValues` property enables the creation of nested filter expressions with `AND` and `OR` logic. It is an object with either `AND` or `OR` properties (or both, with `AND` taking precedence). The value of these properties should be an array of filter objects, allowing for recursive nesting.
+
+```javascript
+// Example: (status==active AND type==local) OR (status==pending)
+const filters = [
+  {
+    groupValues: {
+      OR: [
+        {
+          groupValues: {
+            AND: [
+              { path: 'item.status', value: 'active' },
+              { path: 'item.type', value: 'local' },
+            ],
+          }
+        },
+        { path: 'item.status', value: 'pending' },
+      ]
+    },
+  },
+];
+```
+
+This structure allows you to express complex filter logic in a clear and organized way.
+
+## nsValues options
+
+In addition to the manual filtering capabilities, `generateKiwtQueryParams` supports advanced filtering options including custom comparators and dynamic filter key overrides for the `query` nsValues passed by SASQ. These features enable you to generate complex query expressions more easily.
+
+### Custom Comparators & Filter Key Overrides
+  When using the older `nsValues.filters` string (e.g., `"requestStatus.completed,journalVolume.test1"`), you can use `filterConfig` to customize how filters are interpreted:
+
+    - **Mapping Filter Names:**  
+      Each entry in `filterConfig` should include a `name` field that matches the filter name parsed from `nsValues.filters`.
+
+    - **Overriding Values and Comparators:**  
+      Optionally, a `values` array can be provided for more granular control. For each possible value, you can specify:
+        - A replacement value.
+        - A custom comparator to be used instead of the default `'=='`.
+
+  For example, if you want the filter `status` to use a comparator like `isNotSet` for a certain value, your configuration might look like this:
+
+  ```javascript
+  const options = {
+    filterKeys: { status: 'requestStatus.value' },
+    filterConfig: [
+      {
+        name: 'status',
+        values: [
+          { name: 'notSet', value: '', comparator: ' isNotSet' },
+          { name: 'isNotActive', value: 'active', comparator: '!=' },
+          // other value mappings... Any not present will be evaluated as is
+        ]
+      }
+    ]
+  };
+  ```
+
+  With this configuration, the generated query parameter for various nsValues.filters would be:
+
+| nsValues.filters | outcome |
+| -- | -- |
+| status.notSet | `filters=requestStatus.value isNotSet` |
+| status.wibble | `filters=requestStatus.value==wibble` |
+| status.isNotActive | `filters=requestStatus.value!=active` |
+
+
+
+
+### Dynamic Date Example with `moreThanToday`
+
+You can also dynamically set filter values based on runtime data. For instance, if you want to filter records where a date field is greater than or equal to today’s date, you can calculate the date value first and then reference it in your `filterConfig`:
+
+```javascript
+// Dynamically calculate today's date in YYYY-MM-DD format
+const today = new Date().toISOString().split('T')[0];
+
+const filterConfig = [
+  {
+    name: 'startDate',
+    values: [
+      {
+        name: 'moreThanToday',
+        value: today,
+        comparator: '>='
+      }
+    ]
+  }
+];
+
+const options = {
+  filterConfig,
+};
+
+const nsValues = {
+  // When 'startDate.moreThanToday' is encountered, it will use the filterConfig mapping
+  filters: 'startDate.moreThanToday'
+};
+
+const queryArray = generateKiwtQueryParams(options, nsValues);
+console.log(queryArray);
+// Example output (URL encoded):
+// [
+//   "filters=startDate%3E%3D2025-02-19", // The date value will reflect today's date
+//   "stats=true"
+// ]
+```
+
+In this example, when `nsValues.filters` contains `startDate.moreThanToday`, the function looks up the corresponding configuration in `filterConfig`, uses the dynamically calculated date stored in `today`, and applies the comparator `>=` to produce a query parameter like:
+
+```
+filters=startDate>=2025-02-19
+```
+
+This approach makes it easy to filter records based on dynamic criteria, such as dates relative to the current day.
+
+### How It Works
+
+- **For `options.filters` (object-based filtering):**  
+  The function handles nested filters, groups (using `groupValues` with `AND`/`OR` logic), and applies the specified comparators. This provides full flexibility when building complex queries.
+
+- **For Legacy SASQ `nsValues.filters` (string-based filtering):**  
+  The code splits the incoming comma-separated string into individual filters. For each filter:
+    - It checks if there’s a matching entry in `filterConfig`.
+    - If found, it applies the mapping from `filterConfig` and uses the comparator specified there (or defaults to `'=='`).
+    - If no mapping exists and no filter key is provided in `filterKeys`, the raw value is passed to the backend.
+
+By utilizing these advanced filtering options, you can tailor your query string generation to meet complex backend requirements while maintaining clarity and control over your filter logic.

package/src/lib/utils/{generateKiwtQueryParams.js → generateKiwtQueryParams/generateKiwtQueryParams.js}

@@ -129,8 +129,11 @@ const generateKiwtQueryParams = (options, nsValues, encode = true) => {
       if (filterConfigEntry) {
         // We have a direct mapping instruction, use it
         const filterString = filterValues.map(v => {
-          const fceValue = filterConfigEntry?.values?.find(fce => fce.name === v)?.value;
-          return `${filterName}==${fceValue ?? v}`;
+          const fcValueEntry = filterConfigEntry?.values?.find(fce => fce.name === v) ?? {};
+          const fceValue = fcValueEntry.value ?? v;
+          // This is especially useful where comparator acts strangely for a single value, such as `filters=foo isNotSet`
+          const fceComparator = fcValueEntry.comparator ?? '==';
+          return `${filterKey ?? filterName}${fceComparator}${fceValue ?? v}`;
         }).join('||');
 
         paramsArray.push(`filters=${conditionalEncodeURIComponent(filterString, encode)}`);

package/src/lib/utils/generateKiwtQueryParams/index.js

@@ -0,0 +1 @@
+export { default as generateKiwtQueryParams } from './generateKiwtQueryParams';

package/src/lib/utils/index.js

@@ -1,5 +1,5 @@
 export { default as generateKiwtQuery } from './generateKiwtQuery';
-export { default as generateKiwtQueryParams } from './generateKiwtQueryParams';
+export { generateKiwtQueryParams } from './generateKiwtQueryParams';
 export { default as selectorSafe } from './selectorSafe';
 
 export { default as buildUrl } from './buildUrl';