@k-int/stripes-kint-components 5.17.0 → 5.19.0

package/src/lib/SASQLookupComponent/SASQLookupComponent.js

@@ -28,6 +28,7 @@ import { generateKiwtQuery } from '../utils';
 import { useKintIntl, useKiwtSASQuery, useLocalStorageState, usePrevNextPagination } from '../hooks';
 
 import TableBody from './TableBody';
+import SearchKeyControl from '../SearchKeyControl';
 
 const SASQLookupComponent = forwardRef((props, ref) => {
   const {
@@ -59,8 +60,9 @@ const SASQLookupComponent = forwardRef((props, ref) => {
     RenderBody,
     rowNavigation = true, // Default navigation onRowClick
     sasqProps,
+    searchableIndexes,
     searchFieldAriaLabel,
-    searchFieldProps,
+    searchFieldProps = {},
   } = props;
   const kintIntl = useKintIntl(passedIntlKey, passedIntlNS);
   const [count, setCount] = useState(0);
@@ -236,6 +238,9 @@ const SASQLookupComponent = forwardRef((props, ref) => {
                           value={searchValue.query}
                           {...searchFieldProps}
                         />
+                        {searchableIndexes.length > 0 && (
+                          <SearchKeyControl options={searchableIndexes} />
+                        )}
                         <Button
                           buttonStyle="primary"
                           disabled={!searchValue.query}

package/src/lib/SASQLookupComponent/TableBody/README.md

@@ -0,0 +1,113 @@
+# SASQTableBody
+
+A component that renders a Multi-Column List (MCL) for displaying tabular data with integrated sorting, row navigation, and infinite scrolling. **SASQTableBody** is designed to work within lookup workflows (like **SASQLookupComponent**) but can be used independently. It handles rendering of data, empty states, and integrates with pagination via a `fetchNextPage` callback.
+
+## Basic Usage
+
+Below is an example demonstrating how to use **SASQTableBody** with required props. Additional props are commented for context:
+
+```jsx
+import { useState } from 'react';
+import { SASQTableBody } from '@k-int/stripes-kint-components';
+
+const MyTableView = () => {
+  const [data] = useState({
+    totalRecords: 2,
+    results: [
+      { id: '1', name: 'Item One', status: 'Active' },
+      { id: '2', name: 'Item Two', status: 'Inactive' }
+    ]
+  });
+
+  const query = { sort: 'name' }; // Used for sorting and empty state messages
+  const resultColumns = [
+    { propertyPath: 'name', label: 'Name' },
+    { propertyPath: 'status', label: 'Status' }
+  ];
+
+  const fetchNextPage = ({ pageParam }) => {
+    console.log('Fetching page:', pageParam);
+    // Implement pagination logic here
+  };
+
+  return (
+    <SASQTableBody
+      data={data}
+      query={query}
+      path="/my-items" // Base path for row navigation
+      resultColumns={resultColumns}
+      fetchNextPage={fetchNextPage}
+      // mclProps={{ formatter: { name: (item) => <strong>{item.name}</strong> } }}
+      // rowNavigation={false}
+    />
+  );
+};
+
+export default MyTableView;
+```
+
+### Explanation
+
+- **data:**  
+  Contains `results` (array of items) and `totalRecords` (total items for pagination).
+- **query:**  
+  Provides current search/sort state. Must include `sort` and `query` if applicable.
+- **path:**  
+  Base URL path for constructing row navigation links (e.g., `/my-items/1`).
+- **resultColumns:**  
+  Defines table columns via `propertyPath` (data key) and `label` (header text).
+- **fetchNextPage:**  
+  Called when more data is needed (e.g., scrolling to the bottom).
+
+## Props
+
+| Prop                | Type                                             | Required | Description                                                                                                                                                    |
+|---------------------|--------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `data`              | `{ totalRecords: number, results: object[] }`    | ✓        | Data to display. `results` contains the items, `totalRecords` sets pagination bounds.                                                                          |
+| `query`             | `object`                                         | ✓        | Current query state (e.g., `{ sort: 'name', query: 'search term' }`). Used for sorting and empty state messages.                                               |
+| `path`              | `string`                                         | ✓        | Base path for row URLs. Each row links to `{path}/{rowData.id}`.                                                                                               |
+| `resultColumns`     | `Array<{ propertyPath: string, label: string }>` | ✓        | Columns to render. `propertyPath` accesses the data field, `label` sets the header.                                                                            |
+| `fetchNextPage`     | `({ pageParam: number }) => void`                | ✓        | Callback to load more data. `pageParam` indicates the next page index.                                                                                         |
+| `mclProps`          | `object`                                         | ✕        | Props passed to the underlying [MultiColumnList](https://github.com/folio-org/stripes-components/tree/master/lib/MultiColumnList). Example: `formatter`, `id`. |
+| `rowNavigation`     | `boolean`                                        | ✕        | Enables navigation to detail views on row click. Default: `true`.                                                                                              |
+| `filterPaneVisible` | `boolean`                                        | ✕        | Toggles filter pane visibility in `NoResultsMessage`.                                                                                                          |
+| `toggleFilterPane`  | `() => void`                                     | ✕        | Callback to toggle filter pane. Used in `NoResultsMessage`.                                                                                                    |
+| `intlKey`           | `string`                                         | ✕        | Base key for internationalizing labels. See `useKintIntl`.                                                                                                     |
+| `intlNS`            | `string`                                         | ✕        | Namespace for internationalization. See `useKintIntl`.                                                                                                         |
+| `labelOverrides`    | `object`                                         | ✕        | Overrides default labels (e.g., `{ noResultsFound: 'No items' }`).                                                                                             |
+| `match`             | `object`                                         | ✕        | React Router `match` object. Used to highlight the selected row via URL `id` param.                                                                            |
+| `isLoading`         | `boolean`                                        | ✕        | Shows loading state in `NoResultsMessage`.                                                                                                                     |
+| `isError`           | `boolean`                                        | ✕        | Shows error state in `NoResultsMessage`.                                                                                                                       |
+| `error`             | `object`                                         | ✕        | Error object displayed in `NoResultsMessage`.                                                                                                                  |
+
+## Key Features
+
+1. **Row Navigation:**  
+   When `rowNavigation={true}` (default), clicking a row navigates to `{path}/{rowData.id}`. Uses `react-router` internally.
+
+2. **Sorting:**  
+   Column headers trigger `onSort`, updating the `query.sort` value. The current sort is derived from `query.sort`.
+
+3. **Infinite Scroll:**  
+   `fetchNextPage` is called automatically as the user scrolls. Can alternatively use with pagination logic (e.g., `usePrevNextPagination` props passed to mclProps).
+
+4. **Custom Formatters:**  
+   Pass a `formatter` in `mclProps` to customize cell rendering. Each formatter receives the row data and a `defaultRowUrl`:
+   ```jsx
+   mclProps={{
+     formatter: {
+       name: (item) => <Link to={item.defaultRowUrl}>{item.name}</Link>
+     }
+   }}
+   ```
+
+5. **Empty States:**  
+   `NoResultsMessage` handles loading, errors, and no-results states.
+
+## Integration Notes
+
+- **Parent Components:**  
+  Designed to work within **SASQLookupComponent** (as its default `RenderBody`), but can be used standalone.
+
+- **Routing:**  
+  Must be rendered within a `react-router` context for navigation to work.

package/src/lib/SASQRoute/README.md

@@ -1,33 +1,38 @@
 # SASQRoute
-A component designed to speed up the basic 3-pane layout setup process, SASQRoute is an all in one Routing, SASQ and MCL setup
+
+A component designed to accelerate the setup of a basic 3-pane layout by combining routing, SASQ (Search And Sort Query), and Multi-Column List (MCL) configuration in one place. **SASQRoute** simplifies the process of configuring lookup and view components by automatically setting up the required routes and passing down fetch parameters and custom components.
+
+> **Note:** Although **SASQRoute** is intended to work with the default sub-components—**SASQLookupComponent** and **SASQViewComponent**—you can override them via props. Refer to the documentation for those sub-components for further details.
 
 ## Basic Usage
-```
-import React from 'react';
+
+Below is an example of how to set up **SASQRoute**. In this example, it configures a route that manages both a lookup view and an individual item view within a 3-pane layout. The lookup component renders an MCL with the given `resultColumns`, and clicking on a row navigates to the view route that renders the specified `ViewComponent`.
+
+```jsx
 import { FormattedMessage } from 'react-intl';
 
 import { SASQRoute } from '@k-int/stripes-kint-components';
 import ActionItem from '../components/ActionItem';
 
 const ActionedRoute = ({ path }) => {
-
   const fetchParameters = {
     endpoint: "remote-sync/feedback/done",
     itemEndpoint: "remote-sync/feedback",
     SASQ_MAP: {
       searchKey: 'description',
       filterKeys: {
+        // Additional filter configuration if required
       }
     }
   };
 
   const resultColumns = [
-  { propertyPath: "selected", label: " " },
-  { propertyPath:"description", label: <FormattedMessage id="ui-remote-sync.prop.feedback.description" /> },
-  { propertyPath:"status", label: <FormattedMessage id="ui-remote-sync.prop.feedback.status" /> },
-  { propertyPath:"correlationId", label: <FormattedMessage id="ui-remote-sync.prop.feedback.correlationId" /> },
-  { propertyPath:"caseIndicator", label: <FormattedMessage id="ui-remote-sync.prop.feedback.caseIndicator" /> }
-];
+    { propertyPath: "selected", label: " " },
+    { propertyPath: "description", label: <FormattedMessage id="ui-remote-sync.prop.feedback.description" /> },
+    { propertyPath: "status", label: <FormattedMessage id="ui-remote-sync.prop.feedback.status" /> },
+    { propertyPath: "correlationId", label: <FormattedMessage id="ui-remote-sync.prop.feedback.correlationId" /> },
+    { propertyPath: "caseIndicator", label: <FormattedMessage id="ui-remote-sync.prop.feedback.caseIndicator" /> }
+  ];
 
   return (
     <SASQRoute
@@ -41,15 +46,41 @@ const ActionedRoute = ({ path }) => {
 };
 ```
 
-NOTE - The following prop list is incomplete
+In this example, **SASQRoute**:
+- Configures lookup behavior via `fetchParameters` and the associated `SASQ_MAP`.
+- Uses `resultColumns` to define the columns for the MCL rendered by the lookup component.
+- Sets up routes under the provided `path` for both the lookup and view panes.
+- Renders the `ActionItem` component when an individual row is selected.
+
 ## Props
 
-Name | Type | Description | default | required
---- | --- | --- | --- | ---
-fetchParameters | object | An object containing the parameters needed to make the fetches necessary for both the table and the view components. `endpoint` contains the main fetch endpoint, which regularly will be used for both fetching all data, and also for fetching an individual item (It is assumed that this endpoint will have `/{id}` appended to it.) If `itemEndpoint` is provided that will be used instead (this will also have `/{:id}` appended to it). `SASQ_MAP` is an object of the shape taken by `generateKiwtQuery`  | | ✓ |
-id | string | A unique identifier for this route. IMPORTANT that this is unique, as it drives paneset logic  | | ✓ |
-path | string | The main path for this route. In the above example the path is `remote-sync/actioned`. This component will set up the main 3 pane layout under this path, and also the view pane route under `remote-sync/actioned/:id` | | ✓ |
-resultColumns | array | An array containing objects with a `propertyPath` and `label`. These will be used to drive the MCL columns.  | | ✓ |
-ViewComponent | Element | The component to render on clicking a row entry.  | | ✓ |
+| Name                  | Type                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Default                  | Required |
+|-----------------------|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|----------|
+| `fetchParameters`     | `object`                     | An object containing the parameters needed for data fetching for both the lookup and view components. This should include:<br><br>• **endpoint:** The main fetch endpoint for retrieving all data. The endpoint is typically used for both list and individual item fetches (appending `/{id}` to the endpoint for individual items).<br><br>• **itemEndpoint (optional):** An alternative endpoint for fetching a single item.<br><br>• **SASQ_MAP:** An object defining search and filter configuration. See `generateKiwtQuery` for details. |                          | ✓        |
+| `id`                  | `string`                     | A unique identifier for this route. This identifier is important as it drives pane set logic and must be unique within the application.                                                                                                                                                                                                                                                                                                                                                                                                         |                          | ✓        |
+| `path`                | `string`                     | The base path for this route. **SASQRoute** will set up a 3-pane layout under this path and automatically configure the view route under `{path}/:id`.                                                                                                                                                                                                                                                                                                                                                                                          |                          | ✓        |
+| `resultColumns`       | `array`                      | An array of objects where each object defines a column for the Multi-Column List (MCL) rendered by the lookup component. Each object should contain a `propertyPath` and a `label`. These columns drive the display of data in the list view.                                                                                                                                                                                                                                                                                                   |                          | ✓        |
+| `ViewComponent`       | `element` (or `func`)        | The component to render when a row in the lookup list is selected. This component is displayed in the view pane for showing detailed information about a selected item.                                                                                                                                                                                                                                                                                                                                                                         |                          | ✓        |
+| `children`            | `node`, `element`, or `func` | Optional additional child elements to render within the lookup component. These are rendered inside the **SASQLookupComponent**.                                                                                                                                                                                                                                                                                                                                                                                                                |                          | ✕        |
+| `getPathLookup`       | `func`                       | A function to determine the route for the lookup pane. Defaults to appending `/:id?` to the base `path`. Use this prop to customize the lookup route if needed.                                                                                                                                                                                                                                                                                                                                                                                 | `(path) => ${path}/:id?` | ✕        |
+| `getPathView`         | `func`                       | A function to determine the route for the view pane. Defaults to appending `/:id` to the base `path`. Use this prop to customize the view route if needed.                                                                                                                                                                                                                                                                                                                                                                                      | `(path) => ${path}/:id`  | ✕        |
+| `SASQLookupComponent` | `element` or `func`          | The component to be used for the lookup view. Defaults to the built-in **SASQLookupComponent**. Override this prop to provide a custom lookup component.                                                                                                                                                                                                                                                                                                                                                                                        | `SASQLookupComponent`    | ✕        |
+| `SASQViewComponent`   | `element` or `func`          | The component to be used for the view pane. Defaults to the built-in **SASQViewComponent**. Override this prop to provide a custom view component.                                                                                                                                                                                                                                                                                                                                                                                              | `SASQViewComponent`      | ✕        |
+| `...props`            | `object`                     | Additional props will be passed down to both the lookup and view components. Use these to further customize behavior or appearance as needed.                                                                                                                                                                                                                                                                                                                                                                                                   |                          | ✕        |
+
+## How It Works
+
+1. **Configuration of SASQ_MAP:**  
+   The component extracts and updates the `SASQ_MAP` from `fetchParameters`. If `perPage` is not defined, it defaults to 25. Additionally, it ensures that `stats` is set to `true` before reassigning the object back to `fetchParameters`.
+
+2. **Routing Setup:**
+    - The **lookup route** is configured using the `getPathLookup` function (defaulting to appending `/:id?` to the base `path`). The lookup component (default **SASQLookupComponent**) renders the main Multi-Column List.
+    - Nested within the lookup route is a **view route** configured using the `getPathView` function (defaulting to appending `/:id`). This route renders the view component (default **SASQViewComponent**), which in turn displays the detailed view of a selected item via the passed `ViewComponent`.
+
+3. **Forwarding Refs:**  
+   The component uses `forwardRef` and `useImperativeHandle` to combine the refs of both the lookup and view components, allowing parent components to access methods or properties exposed by these sub-components.
 
+4. **Customizability:**  
+   By overriding default sub-components (`SASQLookupComponent` and `SASQViewComponent`), and by providing custom functions for route paths (`getPathLookup` and `getPathView`), developers can tailor the routing and display behavior to match specific application needs.
 
+This comprehensive setup provided by **SASQRoute** allows for a rapid configuration of complex layouts involving data lookup and detailed views, reducing boilerplate and ensuring consistency across the application.

package/src/lib/SASQViewComponent/README.md

@@ -0,0 +1,132 @@
+# SASQViewComponent
+
+A component that fetches and displays detailed data for a single item within a 3-pane layout. **SASQViewComponent** is typically used as the view pane in conjunction with **SASQLookupComponent** (for list views) via **SASQRoute**. It handles data fetching for individual records and renders content through a customizable `ViewComponent`.
+
+## Basic Usage
+
+**SASQViewComponent** is generally used indirectly through **SASQRoute**. Below is a minimal example showing direct usage (though typically configured via **SASQRoute**):
+
+```jsx
+import { SASQViewComponent } from '@k-int/stripes-kint-components';
+import ItemDetailView from './ItemDetailView';
+
+// In a route configuration (e.g., within a <Route> component)
+const ViewPane = (routeProps) => (
+  <SASQViewComponent
+    fetchParameters={{
+      endpoint: '/api/items', // Default endpoint for individual items
+      itemEndpoint: '/api/items/details' // Optional: override for item-specific endpoint
+    }}
+    ViewComponent={ItemDetailView}
+    {...routeProps}
+  />
+);
+```
+
+In this example, when navigating to a URL like `/items/123`, **SASQViewComponent**:
+1. Fetches data from `/api/items/details/123` (using `itemEndpoint`)
+2. Renders `ItemDetailView` with the fetched data
+3. Provides a default close button to return to the list view
+
+## Props
+
+| Prop                        | Type                                             | Required | Description                                                                                                                                                                                                 |
+|-----------------------------|--------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `fetchParameters`           | `object`                                         | ✓        | Configuration for data fetching. Requires either:<br>• `endpoint`: Base endpoint (appended with `/{id}`)<br>• `itemEndpoint`: Specific endpoint for items (override)                                       |
+| `ViewComponent`             | `Component`                                      | ✓        | Component to render the item details. Receives `resource` (data), `onClose` (close handler), and `queryProps` (loading/error states).                                                                       |
+| `viewQueryNamespaceGenerator` | `function`                                       | ✕        | Generates a unique query key for react-query. Default: Creates a namespace based on component ID and route params.                                                                                         |
+| `id`                        | `string`                                         | ✕        | Unique identifier for the component. Used in query key generation.                                                                                                                                          |
+| `path`                      | `string`                                         | ✓        | Base path for navigation (e.g., `/items`). Used with `history` to return to list view.                                                                                                                      |
+| `history`                   | `object`                                         | ✓        | React Router history object (injected by parent route).                                                                                                                                                    |
+| `location`                  | `object`                                         | ✓        | React Router location object (injected by parent route).                                                                                                                                                   |
+| `match`                     | `object`                                         | ✓        | React Router match object containing route params (e.g., `match.params.id`).                                                                                                                               |
+
+## Key Features
+
+1. **Automatic Data Fetching**  
+   Fetches individual item data when `match.params.id` exists. Uses either:
+   ```js
+   `${itemEndpoint}/${id}`  // If itemEndpoint provided
+   `${endpoint}/${id}`      // If only endpoint provided
+   ```
+
+2. **Query Management**  
+   Uses `react-query` for fetching, caching, and error handling. Exposes query states (`isLoading`, `isError`, etc.) via `queryProps` passed to `ViewComponent`.
+
+3. **Close Behavior**  
+   Provides a default `onClose` handler that navigates back to the parent path (e.g., from `/items/123` to `/items`).
+
+4. **Customizable Query Keys**  
+   Override `viewQueryNamespaceGenerator` to control react-query's cache key structure:
+   ```jsx
+   <SASQViewComponent
+     viewQueryNamespaceGenerator={({ namespace, id }) => [
+       namespace, 
+       'custom-view', 
+       id
+     ]}
+   />
+   ```
+
+5. **Ref Forwarding**  
+   Exposes query data and status via ref:
+   ```jsx
+   const viewRef = useRef();
+   // Access { data, isLoading, ... } via viewRef.current.queryProps
+   ```
+
+## Integration with ViewComponent
+
+Your `ViewComponent` receives these props:
+
+| Prop         | Type      | Description                                                                                     |
+|--------------|-----------|-------------------------------------------------------------------------------------------------|
+| `resource`   | `object`  | Fetched data for the item.                                                                      |
+| `onClose`    | `function`| Callback to close the view pane (returns to list).                                              |
+| `queryProps` | `object`  | Contains `isLoading`, `isError`, `error`, and other react-query states.                        |
+
+Example `ViewComponent` implementation:
+```jsx
+const ItemDetailView = ({ resource, onClose, queryProps }) => {
+  if (queryProps.isLoading) return <Spinner />;
+  if (queryProps.isError) return <Error message={queryProps.error.message} />;
+
+  return (
+    <div>
+      <button onClick={onClose}>Back</button>
+      <h1>{resource.name}</h1>
+      {/* Render other details */}
+    </div>
+  );
+};
+```
+
+## Usage with SASQRoute
+
+Typically used via **SASQRoute** for automatic route configuration:
+```jsx
+<SASQRoute
+  path="/items"
+  fetchParameters={{
+    endpoint: '/api/items',
+    SASQ_MAP: { searchKey: 'name' }
+  }}
+  ViewComponent={ItemDetailView}
+  resultColumns={[...]}
+/>
+```
+This automatically:
+- Creates routes for `/items` (list) and `/items/:id` (detail)
+- Connects the lookup and view components
+- Passes fetched data to `ItemDetailView`
+
+## Edge Cases
+
+- **Missing ID Parameter:**  
+  If `match.params.id` is undefined, no data fetching occurs and `resource` will be `undefined`.
+
+- **Custom Endpoints:**  
+  Use `itemEndpoint` when individual items require a different API path than `{endpoint}/{id}`.
+
+- **Query Key Collisions:**  
+  Override `viewQueryNamespaceGenerator` if multiple SASQViewComponents share the same ID/route.

package/src/lib/SearchKeyControl/README.md

@@ -0,0 +1,70 @@
+# 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.
+
+> **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.
+
+## 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.
+
+```jsx
+import { SearchKeyControl } from '@k-int/stripes-kint-components';
+
+const MySearchForm = () => {
+  const searchKeyOptions = [
+    { key: 'keyword', label: 'Keyword' },
+    { key: 'title', label: 'Title' },
+    { key: 'author', label: 'Author' },
+    { key: 'subject', label: 'Subject' }
+  ];
+
+  return (
+    <div>
+      {/* ... other search form elements ... */}
+      <label>Search Indexes:</label>
+      <SearchKeyControl options={searchKeyOptions} />
+      {/* ... submit button etc ... */}
+    </div>
+  );
+};
+
+export default MySearchForm;
+````
+
+In this example, **SearchKeyControl**:
+
+- 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.
+
+## 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. | `[]`    | ✕        |
+
+
+## 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`).
+
+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.
+
+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.
+
+4.  **Handling Changes:**
+    When a checkbox's state is changed by the user:
+
+  * 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.
+
+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

@@ -0,0 +1,98 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import PropTypes from 'prop-types';
+
+import isEqual from 'lodash/isEqual';
+
+import { Checkbox } from '@folio/stripes/components';
+
+import { usePrevNextPagination, useQIndex } from '../hooks';
+
+import css from '../../../styles/SearchKeyControl.css';
+
+/*
+  IMPORTANT -- This component is controlled by the qIndex, rather than the other way around.
+  It should inject values in/remove values from the qIndex, but not replace the entire thing.
+*/
+const SearchKeyControl = ({
+                            options = []
+                          }) => {
+  // This component expects a qIndex comprising of a comma separated list
+  const [qIndex, setQIndex] = useQIndex();
+  const qIndexArray = useMemo(() => qIndex?.split(',')?.map(index => index.trim()) ?? [], [qIndex]);
+
+  // 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 };
+      return acc;
+    }, {})
+  ), [options, qIndexArray]);
+
+  const [keyState, setKeyState] = useState(createKeyState());
+
+  // Keep keyState up to date as options/qIndex change
+  useEffect(() => {
+    const newKeyState = createKeyState();
+    if (!isEqual(newKeyState, keyState)) {
+      setKeyState(newKeyState);
+    }
+  }, [createKeyState, keyState]);
+
+  // Check to see if page param exists, and if it does then changing qIndex should reset it
+  const { currentPage, resetPage } = usePrevNextPagination({ defaultToPageOne: false });
+
+  return (
+    <>
+      <div className={css.searchKeyControlContainer}>
+        {
+          Object.entries(keyState).map(([key, value]) => {
+            /* At this point we have "key" corresponding to a searchKey option,
+            * and "value" an object of the shape
+              {
+                inUse: a bool determining if it is in use or not,
+                label: the label to display on the checkbox
+              }
+            */
+            return (
+              <Checkbox
+                key={`search-key-control-${key}`}
+                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();
+                  }
+                }}
+              />
+            );
+          })
+        }
+      </div>
+    </>
+  );
+};
+
+SearchKeyControl.propTypes = {
+  options: PropTypes.arrayOf(PropTypes.shape({
+    label: PropTypes.oneOfType([
+      PropTypes.string,
+      PropTypes.node
+    ]).isRequired,
+    key: PropTypes.string.isRequired
+  }))
+};
+
+export default SearchKeyControl;