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

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;

package/src/lib/SearchKeyControl/SearchKeyControl.test.js

@@ -0,0 +1,165 @@
+import { useState } from 'react';
+
+import { waitFor } from '@folio/jest-config-stripes/testing-library/react';
+import { renderWithIntl, Checkbox } from '@folio/stripes-erm-testing';
+
+import SearchKeyControl from './SearchKeyControl';
+
+const mockUseQIndex = jest.fn();
+
+jest.mock('../hooks', () => ({
+  ...jest.requireActual('../hooks'),
+  useQIndex: () => mockUseQIndex()
+}));
+
+describe('SearchKeyControl', () => {
+  describe('without initial qIndex', () => {
+    beforeEach(() => {
+      mockUseQIndex.mockImplementation(() => {
+        return useState();
+      });
+
+      renderWithIntl(
+        <SearchKeyControl
+          options={[
+            {
+              label: 'Opt 1',
+              key: 'opt1'
+            },
+            {
+              label: 'Opt 2',
+              key: 'opt2'
+            },
+            {
+              label: 'Opt 3',
+              key: 'opt3'
+            }
+          ]}
+        />
+      );
+    });
+
+    test('renders all Checkboxes', async () => {
+      await Checkbox('Opt 1').exists();
+      await Checkbox('Opt 2').exists();
+      await Checkbox('Opt 3').exists();
+    });
+
+    test('all Checkboxes have expected initial "checked" value', async () => {
+      await Checkbox('Opt 1').has({ checked: false });
+      await Checkbox('Opt 2').has({ checked: false });
+      await Checkbox('Opt 3').has({ checked: false });
+    });
+
+    describe('clicking Opt 2', () => {
+      beforeEach(async () => {
+        await waitFor(async () => {
+          await Checkbox('Opt 2').click();
+        });
+      });
+
+      test('all Checkboxes have expected "checked" value', async () => {
+        await Checkbox('Opt 1').has({ checked: false });
+        await Checkbox('Opt 2').has({ checked: true });
+        await Checkbox('Opt 3').has({ checked: false });
+      });
+    });
+
+    describe('clicking Opt 1 and Opt 2', () => {
+      beforeEach(async () => {
+        await waitFor(async () => {
+          await Checkbox('Opt 1').click();
+          await Checkbox('Opt 2').click();
+        });
+      });
+
+      test('all Checkboxes have expected "checked" value', async () => {
+        await Checkbox('Opt 1').has({ checked: true });
+        await Checkbox('Opt 2').has({ checked: true });
+        await Checkbox('Opt 3').has({ checked: false });
+      });
+    });
+  });
+
+  describe('with initial qIndex', () => {
+    beforeEach(() => {
+      mockUseQIndex.mockImplementation(() => {
+        return useState('opt1,opt3');
+      });
+
+      renderWithIntl(
+        <SearchKeyControl
+          options={[
+            {
+              label: 'Opt 1',
+              key: 'opt1'
+            },
+            {
+              label: 'Opt 2',
+              key: 'opt2'
+            },
+            {
+              label: 'Opt 3',
+              key: 'opt3'
+            }
+          ]}
+        />
+      );
+    });
+
+    test('renders all Checkboxes', async () => {
+      await Checkbox('Opt 1').exists();
+      await Checkbox('Opt 2').exists();
+      await Checkbox('Opt 3').exists();
+    });
+
+    test('all Checkboxes have expected initial "checked" value', async () => {
+      await Checkbox('Opt 1').has({ checked: true });
+      await Checkbox('Opt 2').has({ checked: false });
+      await Checkbox('Opt 3').has({ checked: true });
+    });
+
+    describe('clicking Opt 2', () => {
+      beforeEach(async () => {
+        await waitFor(async () => {
+          await Checkbox('Opt 2').click();
+        });
+      });
+
+      test('all Checkboxes have expected "checked" value', async () => {
+        await Checkbox('Opt 1').has({ checked: true });
+        await Checkbox('Opt 2').has({ checked: true });
+        await Checkbox('Opt 3').has({ checked: true });
+      });
+    });
+
+    describe('clicking Opt 1 and Opt 2', () => {
+      beforeEach(async () => {
+        await waitFor(async () => {
+          await Checkbox('Opt 1').click();
+          await Checkbox('Opt 2').click();
+        });
+      });
+
+      test('all Checkboxes have expected "checked" value', async () => {
+        await Checkbox('Opt 1').has({ checked: false });
+        await Checkbox('Opt 2').has({ checked: true });
+        await Checkbox('Opt 3').has({ checked: true });
+      });
+    });
+
+    describe('clicking Opt 3', () => {
+      beforeEach(async () => {
+        await waitFor(async () => {
+          await Checkbox('Opt 3').click();
+        });
+      });
+
+      test('all Checkboxes have expected "checked" value', async () => {
+        await Checkbox('Opt 1').has({ checked: true });
+        await Checkbox('Opt 2').has({ checked: false });
+        await Checkbox('Opt 3').has({ checked: false });
+      });
+    });
+  });
+});

package/src/lib/SearchKeyControl/index.js

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