@k-int/stripes-kint-components 5.22.0 → 5.23.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [5.23.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.22.0...v5.23.0) (2025-06-25)
+
+
+### Features
+
+* SearchKeyControl subIndexes ([40036a4](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/commit/40036a4353f24e47480e8060d901ef44c5c3b6ed))
+
 # [5.22.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.21.0...v5.22.0) (2025-06-13)
 
 

package/es/lib/SearchKeyControl/SearchKeyControl.js

@@ -25,9 +25,12 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 
   // Memoise this process so keyState changes if and only if options/qIndex change
   const createKeyState = (0, _react.useCallback)(() => options.reduce((acc, curr) => {
+    // Is in use if URL contains ALL of the indexes
+    const subindexes = (curr?.indexes?.length ?? 0) > 0 ? curr.indexes : [curr.key];
     acc[curr.key] = {
-      inUse: qIndexArray?.includes(curr.key),
-      label: curr.label ?? curr.key
+      inUse: subindexes.every(si => qIndexArray.includes(si)),
+      label: curr.label ?? curr.key,
+      subIndexes: curr.indexes
     };
     return acc;
   }, {}), [options, qIndexArray]);
@@ -48,11 +51,44 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
   } = (0, _hooks.usePrevNextPagination)({
     defaultToPageOne: false
   });
+  const handleSearchKeyChange = (0, _react.useCallback)(_ref2 => {
+    let {
+      e: {
+        target: {
+          checked: targetIsChecked
+        } = {}
+      } = {},
+      key,
+      value
+    } = _ref2;
+    // Set up which indexes need to change
+    const indicesToChange = (value?.subIndexes?.length ?? 0) > 0 ? value.subIndexes : [key];
+
+    // If false, we must remove from the qIndex
+    if (!targetIsChecked) {
+      indicesToChange.forEach(ind => {
+        const indexOfKey = qIndexArray.indexOf(ind);
+        if (indexOfKey > -1) {
+          // only splice array when item is found
+          qIndexArray.splice(indexOfKey, 1); // 2nd parameter means remove one item only
+        }
+      });
+    } else {
+      // If true, we need to add to qIndex
+      indicesToChange.forEach(ind => {
+        qIndexArray.push(ind);
+      });
+    }
+    setQIndex(qIndexArray?.join(','));
+    if (currentPage) {
+      resetPage();
+    }
+  }, [currentPage, qIndexArray, resetPage, setQIndex]);
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {
     children: /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
       className: _SearchKeyControl.default.searchKeyControlContainer,
-      children: Object.entries(keyState).map(_ref2 => {
-        let [key, value] = _ref2;
+      children: Object.entries(keyState).map(_ref3 => {
+        let [key, value] = _ref3;
         /* At this point we have "key" corresponding to a searchKey option,
         * and "value" an object of the shape
           {
@@ -64,23 +100,11 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
           checked: value?.inUse,
           className: _SearchKeyControl.default.searchKeyControlElement,
           label: value?.label,
-          onChange: e => {
-            // If false, we must remove from the qIndex
-            if (!e.target.checked) {
-              const indexOfKey = qIndexArray.indexOf(key);
-              if (indexOfKey > -1) {
-                // only splice array when item is found
-                qIndexArray.splice(indexOfKey, 1); // 2nd parameter means remove one item only
-              }
-            } else {
-              // If true, we need to add to qIndex
-              qIndexArray.push(key);
-            }
-            setQIndex(qIndexArray?.join(','));
-            if (currentPage) {
-              resetPage();
-            }
-          }
+          onChange: e => handleSearchKeyChange({
+            e,
+            key,
+            value
+          })
         }, `search-key-control-${key}`);
       })
     })

package/package.json

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

package/src/lib/SearchKeyControl/README.md

@@ -1,12 +1,14 @@
 # SearchKeyControl
 
-A component that renders a group of checkboxes allowing users to select one or more search keys (indexes). It directly interacts with the `qIndex` URL parameter (managed via the `useQIndex` hook) to reflect the currently active search indexes.
+A component that renders a group of checkboxes allowing users to select one or more search keys (indexes). It synchronizes its state with the `qIndex` URL parameter (managed via the `useQIndex` hook), updating this parameter by injecting or removing individual keys based on user interactions.
 
-> **Note:** This component is designed to be controlled by the `qIndex` URL parameter rather than receiving explicit `value` or `onChange` props for the entire set of keys. It modifies the `qIndex` parameter by adding or removing individual keys based on checkbox interactions.
+> **Note:** This component is **controlled by the `qIndex` URL parameter** rather than external props like `value` or `onChange`. When users interact with checkboxes, the component modifies the `qIndex` by adding or removing search keys accordingly. It **does not** replace the entire `qIndex` value.
+
+---
 
 ## Basic Usage
 
-Below is an example demonstrating how to use **SearchKeyControl**. You provide an array of `options`, each defining a potential search key with a label. The component automatically reads the current `qIndex` from the URL, determines the checked state of each checkbox, and updates the `qIndex` when checkboxes are toggled.
+Provide an `options` array with each search key to be rendered. Each option includes a `key`, a display `label`, and optionally, an `indexes` array to represent multiple underlying sub-indexes.
 
 ```jsx
 import { SearchKeyControl } from '@k-int/stripes-kint-components';
@@ -16,55 +18,78 @@ const MySearchForm = () => {
     { key: 'keyword', label: 'Keyword' },
     { key: 'title', label: 'Title' },
     { key: 'author', label: 'Author' },
-    { key: 'subject', label: 'Subject' }
+    {
+      key: 'subjectPlus',
+      label: 'Subject (incl. subdivisions)',
+      indexes: ['subject', 'subdivision']
+    }
   ];
 
   return (
     <div>
-      {/* ... other search form elements ... */}
       <label>Search Indexes:</label>
       <SearchKeyControl options={searchKeyOptions} />
-      {/* ... submit button etc ... */}
     </div>
   );
 };
 
 export default MySearchForm;
-````
+```
+
+In this example:
 
-In this example, **SearchKeyControl**:
+* **Checkboxes** are rendered for each `key`, including the composite `subjectPlus`.
+* The `qIndex` URL parameter (e.g. `?qIndex=title,author`) determines the checked state.
+* Clicking a checkbox adds or removes the relevant index or indexes:
 
-- Renders checkboxes for "Keyword", "Title", "Author", and "Subject".
-- Reads the `qIndex` URL parameter (e.g., `?qIndex=keyword,title`).
-- Sets the "Keyword" and "Title" checkboxes as checked based on the example `qIndex`.
-- If the user clicks the "Author" checkbox, the component updates the URL parameter to `?qIndex=keyword,title,author`.
-- If the user then unclicks the "Keyword" checkbox, the URL parameter becomes `?qIndex=title,author`.
-- It also automatically resets pagination (via `usePrevNextPagination`) when the `qIndex` changes.
+    * For simple entries like `"title"`, toggling directly modifies `qIndex`.
+    * For composite entries like `"subjectPlus"`, checking adds both `"subject"` and `"subdivision"`; unchecking removes both.
+* **Pagination is reset** automatically via `usePrevNextPagination()` when the `qIndex` changes.
+
+---
 
 ## Props
 
-| Name      | Type              | Description                                                                                                                                                                                                                        | Default | Required |
-|:----------|:------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
-| `options` | `arrayOf(object)` | An array of objects defining the available search keys. Each object must have: <br>• `key` (string): The value representing the search index. <br/>• `label` (string \| node): The text or element displayed next to the checkbox. | `[]`    | ✕        |
+| Name      | Type              | Description                                                                                                                                                                                                                                                                                 | Default | Required |
+| :-------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ | :------- |
+| `options` | `arrayOf(object)` | Array of search key definitions. Each object must include:<br>• `key` (string): A unique identifier.<br>• `label` (string \| node): The displayed label.<br>• `indexes` (array of strings, optional): One or more sub-indexes that this checkbox controls (defaults to `[key]` if omitted). | `[]`    | ✕        |
 
+---
 
 ## How It Works
 
-1.  **Reading Search Index State:**
-    The component uses the `useQIndex` hook to read the current `qIndex` URL parameter, which is expected to be a comma-separated string of active search keys (e.g., `"keyword,title"`). It memoizes this string split into an array (`qIndexArray`).
+### 1. Reading Search Index State
+
+The component uses `useQIndex()` to retrieve and manage the `qIndex` URL parameter. The value is split into an array of active keys (`qIndexArray`), trimmed for whitespace and memoized.
+
+### 2. Creating Internal State
+
+A `keyState` object maps each option's `key` to:
+
+* `inUse`: A boolean indicating whether all of the entry’s `indexes` are present in `qIndexArray`.
+* `label`: The label to display next to the checkbox.
+* `subIndexes`: The underlying `indexes` array (or `[key]` if not specified).
+
+This mapping is memoized via `useCallback()` and kept in sync with URL state using `useEffect()`.
+
+### 3. Rendering Checkboxes
+
+Each `keyState` entry is rendered as a checkbox using `@folio/stripes/components`' `Checkbox`. Its `checked` state is tied to `inUse`, and its `label` comes from the `label` field.
+
+### 4. Handling Changes
+
+On user interaction:
+
+* If a checkbox is checked:
+
+    * The component **adds** all `subIndexes` for the key to the `qIndexArray`.
+* If a checkbox is unchecked:
 
-2.  **Determining Checkbox State:**
-    It uses `useState`, `useEffect`, `useMemo`, and `useCallback` along with `lodash/isEqual` to create and maintain an internal `keyState` object. This object maps each `key` from the `options` prop to its display `label` and an `inUse` boolean flag. The `inUse` flag is determined by checking if the option's `key` exists within the current `qIndexArray` derived from the `qIndex` URL parameter. This ensures the checkboxes visually reflect the state in the URL.
+    * The component **removes** all `subIndexes` for the key from `qIndexArray`.
 
-3.  **Rendering Checkboxes:**
-    The component iterates over the `keyState` object and renders a `@folio/stripes/components` `Checkbox` for each entry. The `checked` prop of the checkbox is bound to the `inUse` flag from `keyState`, and the `label` is set accordingly.
+The updated array is joined back into a comma-separated string and passed to `setQIndex()` to update the URL.
 
-4.  **Handling Changes:**
-    When a checkbox's state is changed by the user:
+### 5. Pagination Reset
 
-  * The `onChange` handler determines if the key should be added or removed from the list of active keys.
-  * It updates a temporary copy of the `qIndexArray` (either adding the key with `push` or removing it with `splice`).
-  * It calls `setQIndex` (from `useQIndex`) with the modified array joined back into a comma-separated string, which updates the URL parameter.
+If the current page is non-zero (via `usePrevNextPagination`), the component calls `resetPage()` after modifying `qIndex`. This ensures consistency in result navigation after a filter change.
 
-5.  **Pagination Reset:**
-    The component also uses the `usePrevNextPagination` hook. If pagination is active (`currentPage` has a value), it calls `resetPage()` after updating the `qIndex`. This ensures that users are returned to the first page of results when the search indexes change, preventing potentially invalid page numbers for the new search scope.

package/src/lib/SearchKeyControl/SearchKeyControl.js

@@ -23,7 +23,14 @@ const SearchKeyControl = ({
   // Memoise this process so keyState changes if and only if options/qIndex change
   const createKeyState = useCallback(() => (
     options.reduce((acc, curr) => {
-      acc[curr.key] = { inUse: qIndexArray?.includes(curr.key), label: curr.label ?? curr.key };
+      // Is in use if URL contains ALL of the indexes
+      const subindexes = ((curr?.indexes?.length ?? 0) > 0) ? curr.indexes : [curr.key];
+
+      acc[curr.key] = {
+        inUse: subindexes.every(si => qIndexArray.includes(si)),
+        label: curr.label ?? curr.key,
+        subIndexes: curr.indexes
+      };
       return acc;
     }, {})
   ), [options, qIndexArray]);
@@ -41,6 +48,31 @@ const SearchKeyControl = ({
   // Check to see if page param exists, and if it does then changing qIndex should reset it
   const { currentPage, resetPage } = usePrevNextPagination({ defaultToPageOne: false });
 
+  const handleSearchKeyChange = useCallback(({ e: { target: { checked: targetIsChecked } = {} } = {}, key, value }) => {
+    // Set up which indexes need to change
+    const indicesToChange = ((value?.subIndexes?.length ?? 0) > 0) ? value.subIndexes : [key];
+
+    // If false, we must remove from the qIndex
+    if (!targetIsChecked) {
+      indicesToChange.forEach(ind => {
+        const indexOfKey = qIndexArray.indexOf(ind);
+        if (indexOfKey > -1) { // only splice array when item is found
+          qIndexArray.splice(indexOfKey, 1); // 2nd parameter means remove one item only
+        }
+      });
+    } else {
+      // If true, we need to add to qIndex
+      indicesToChange.forEach(ind => {
+        qIndexArray.push(ind);
+      });
+    }
+
+    setQIndex(qIndexArray?.join(','));
+    if (currentPage) {
+      resetPage();
+    }
+  }, [currentPage, qIndexArray, resetPage, setQIndex]);
+
   return (
     <>
       <div className={css.searchKeyControlContainer}>
@@ -59,23 +91,7 @@ const SearchKeyControl = ({
                 checked={value?.inUse}
                 className={css.searchKeyControlElement}
                 label={value?.label}
-                onChange={e => {
-                  // If false, we must remove from the qIndex
-                  if (!e.target.checked) {
-                    const indexOfKey = qIndexArray.indexOf(key);
-                    if (indexOfKey > -1) { // only splice array when item is found
-                      qIndexArray.splice(indexOfKey, 1); // 2nd parameter means remove one item only
-                    }
-                  } else {
-                    // If true, we need to add to qIndex
-                    qIndexArray.push(key);
-                  }
-
-                  setQIndex(qIndexArray?.join(','));
-                  if (currentPage) {
-                    resetPage();
-                  }
-                }}
+                onChange={e => handleSearchKeyChange({ e, key, value })}
               />
             );
           })