@k-int/stripes-kint-components 5.9.0 → 5.11.0

package/src/lib/utils/README.md

@@ -1,73 +1,143 @@
-# util
-A collection of useful util functions
+# Utility Functions
 
 ## generateKiwtQuery
-A util function for generating a "KIWT" (K-Int Web-Toolkit) style backend query from a SASQ query object
-### Basic usage
-```
-import { generateKiwtQuery } 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'
-    }
+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.
+
+### Basic Usage
+
+```javascript
+import { generateKiwtQuery } from '@k-int/stripes-kint-components';
+
+const nsValues = {
+  query: 'test',
+  filters: 'requestStatus.completed,journalVolume.test1,startDate.startDate>=2021-10-28',
+  sort: '-title' // Example of sorting by title in descending order
+};
+
+const options = {
+  searchKey: 'request.name',
+  filterKeys: {
+    requestStatus: 'requestStatus.value',
+    journalVolume: 'journalVolume'
+  },
+  sortKeys: {
+    title: 'item.title' // Example of mapping 'title' to 'item.title' for sorting
   }
+};
 
-  const queryString = generateKiwtQuery(options, nsValues)
+const queryString = generateKiwtQuery(options, nsValues);
 
-  // We'd expect queryString === "?match=request.name&term=test&filters=requestStatus.value==completed&filters=journalVolume==test1&filters=startDate%3E=2021-10-28&stats=true"
-...
+// queryString will be:
+//?match=request.name&term=test&filters=requestStatus.value==completed&filters=journalVolume==test1&filters=startDate%3E=2021-10-28&sort=item.title;desc&stats=true
 ```
 
 ### Props
-Name | Type | Description | default | required
---- | --- | --- | --- | ---
-options | object | An object with keys: `searchKey`, `filterKeys`, `sortKeys` and `stats`, which maps the incoming nsValues objects 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 actual query parameters to become the mapped KIWT query | | ✓ |
-encode | boolean | A boolean prop which determines if each query param chunk will be encoded using encodeURIComponent or not | true | ✕ |
+
+| 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. 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
-A util function for generating an array of "KIWT" (K-Int Web-Toolkit) style backend query parameters from a SASQ query object
-### Basic usage
-```
-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'
-    }
+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);
 
-  const queryArray = generateKiwtQueryParams(options, nsValues)
-
-  // We'd expect queryArray === [
-    "match=request.name",
-    "term=test",
-    "filters=requestStatus.value==completed",
-    "filters=journalVolume==test1",
-    "filters=startDate%3E=2021-10-28",
-    "stats=true"
-  ]
-...
+// 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 objects to an KIWT query array. You can also pass arbitrary `key`/`value` pairs to append `key==value` onto the query. | | ✓ |
-nsValues | object | An object containing the actual query parameters to become the mapped KIWT query | | ✓ |
-encode | boolean | A boolean prop which determines if each query param chunk will be encoded using encodeURIComponent or not | true | ✕ |
+
+| 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/test/helpers/test-implementor-translations.json

@@ -76,5 +76,8 @@
   "edit": "Edit",
   "save": "Save",
   "cancel": "Cancel",
-  "apply": "Apply"
+  "apply": "Apply",
+  "tags": "Tags",
+  "numberOfTags": "{count, number} {count, plural, one {Tag} other {Tags}}",
+  "newTagCreated": "New tag created"
 }