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

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

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

package/package.json

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

package/src/index.js

@@ -42,6 +42,10 @@ export {
   default as SearchField
 } from './lib/SearchField';
 
+export {
+  default as SearchKeyControl
+} from './lib/SearchKeyControl';
+
 // SASQRoute
 export {
   default as SASQRoute

package/src/lib/NumberField/README.md

@@ -0,0 +1,134 @@
+# NumberField
+
+A controlled input component designed for numeric values, providing parsing, validation, and seamless integration with form libraries like React Final Form. **NumberField** ensures that user input is always treated as a numeric value (or empty string) while maintaining compatibility with browser-native number input validation.
+
+## Features
+
+- **Controlled/Uncontrolled Support:** Works as a controlled component (via `value`) or within form libraries (via `input`).
+- **Automatic Parsing:** Converts user input to a numeric value (float) or empty string.
+- **Form Integration:** Compatible with React Final Form's `Field` component.
+- **Dual Input Handling:** Uses a visible `TextField` for user interaction and a hidden input for form state management.
+- **Validation:** Leverages HTML5 `type="number"` validation with fallback to numeric parsing.
+
+## Basic Usage
+
+### Standalone (Controlled)
+
+```jsx
+import { useState } from 'react';
+import { NumberField } from '@k-int/stripes-kint-components';
+
+const AgeInput = () => {
+  const [age, setAge] = useState('');
+
+  return (
+    <NumberField
+      label="Enter your age"
+      value={age}
+      onChange={(e, value) => setAge(value)}
+      aria-label="Age input"
+    />
+  );
+};
+
+export default AgeInput;
+```
+
+### With React Final Form
+
+```jsx
+import { Field } from 'react-final-form';
+import { NumberField } from '@k-int/stripes-kint-components';
+
+const FormAgeField = () => (
+  <Field
+    name="age"
+    render={({ input }) => (
+      <NumberField
+        label="Age"
+        input={input}
+        aria-label="Form age input"
+      />
+    )}
+  />
+);
+
+export default FormAgeField;
+```
+
+## Props
+
+| Prop        | Type       | Required | Description                                                                                                  |
+|-------------|------------|----------|--------------------------------------------------------------------------------------------------------------|
+| `input`     | `object`   | ✕        | Form library input object (e.g., from React Final Form). Must contain `name`, `onChange`, and `value`.       |
+| `value`     | `number`   | ✕        | Controlled value (use either `input` or `value`, not both).                                                 |
+| `onChange`  | `function` | ✕        | Custom change handler: `(event: React.ChangeEvent, value: number | '') => void`.                               |
+| `onBlur`    | `function` | ✕        | Custom blur handler: `(event: React.FocusEvent) => void`.                                                   |
+| ...TextFieldProps | `any`     | ✕        | All other props passed to underlying [TextField](https://stripes.github.io/stripes-components/TextField).   |
+
+## Behavior Details
+
+### Input Handling
+- **User Input:** Directly manipulates a visible `TextField`
+- **Value Parsing:**
+  ```js
+  const parsedValue = parseFloat(userInput);
+  // Returns number or NaN
+  ```
+- **Form State:** Maintains a hidden `<input>` that always contains:
+    - Valid number (as float)
+    - Empty string (for invalid/empty input)
+
+### Value Propagation
+1. User types "12.5" ➔ `handleUserChange`:
+   ```js
+   parsedValue = 12.5
+   setNumValue(12.5)      // Updates visible field
+   changeField(12.5)     // Updates hidden input
+   ```
+2. Hidden input's `onChange`:
+   ```js
+   input.onChange(12.5)  // Propagates to form library
+   passedOnChange(12.5)  // Notifies custom handler
+   ```
+
+## Integration Notes
+
+### Form Library Requirements
+When using with React Final Form:
+```jsx
+<Field
+  name="quantity"
+  parse={v => v === '' ? undefined : Number(v)}  // Convert empty string to undefined
+  render={({ input }) => (
+    <NumberField
+      input={input}
+      label="Quantity"
+    />
+  )}
+/>
+```
+
+### Styling/Validation
+- Inherits all styling capabilities from `@folio/stripes-components/TextField`
+- Browser-native number validation shown via:
+  ```jsx
+  <NumberField
+    type="number"
+    min={0}
+    max={100}
+    step={0.1}
+  />
+  ```
+
+## Error Handling
+Implement custom error states through form library integrations or wrapper components:
+```jsx
+const ErrorProneField = ({ meta, ...props }) => (
+  <NumberField
+    {...props}
+    error={meta.touched && meta.error}
+    aria-label="Error-prone field"
+  />
+);
+```

package/src/lib/SASQLookupComponent/README.md

@@ -0,0 +1,172 @@
+# SASQLookupComponent
+
+A highly configurable component that renders a lookup view for displaying data in a multi-pane layout. **SASQLookupComponent** combines a search and sort query (SASQ) interface, a filter pane, and a main content pane into a unified view. It leverages components from `@folio/stripes/smart-components` and `@folio/stripes/components` to provide a persistent paneset layout with integrated search, filtering, and pagination.
+
+> **Note:** Detailed documentation for sub-components (such as **SearchAndSortQuery**, **PersistedPaneset**, **CollapseFilterPaneButton**, and **ExpandFilterPaneButton**) is available separately. **SASQLookupComponent** is designed to work seamlessly with these components while allowing for significant customization via its props.
+
+## Basic Usage
+
+Below is an example demonstrating how to use **SASQLookupComponent**. In this example, the component is configured with custom fetch parameters, filtering behavior, and a custom table body for rendering results. The component automatically manages query state, pagination, and filter pane visibility.
+
+```jsx
+import { FormattedMessage } from 'react-intl';
+import { SASQLookupComponent } from '@k-int/stripes-kint-components';
+import CustomFilter from './CustomFilter';
+import CustomTableBody from './CustomTableBody';
+
+const MyLookupView = () => {
+  const fetchParameters = {
+    endpoint: '/api/my-items',
+    SASQ_MAP: {
+      searchKey: 'name',
+      perPage: 25,
+      // Additional SASQ configuration
+    }
+  };
+
+  return (
+    <SASQLookupComponent
+      id="my-lookup"
+      path="/my-lookup"
+      fetchParameters={fetchParameters}
+      FilterComponent={CustomFilter}
+      RenderBody={CustomTableBody}
+      intlKey="myLookup"
+      intlNS="myApp"
+      labelOverrides={{ foundValues: 'Items Found' }}
+      resultColumns={[
+        { propertyPath: 'name', label: <FormattedMessage id="myApp.item.name" /> },
+        { propertyPath: 'status', label: <FormattedMessage id="myApp.item.status" /> }
+      ]}
+      searchFieldAriaLabel="Search items"
+    >
+      {/* Optionally, additional children can be rendered */}
+    </SASQLookupComponent>
+  );
+};
+
+export default MyLookupView;
+```
+
+In this example, **SASQLookupComponent**:
+
+- Uses `fetchParameters` to configure data fetching.
+- Provides a custom filter interface via `FilterComponent`.
+- Renders results using a custom table body (or defaults to an internal **TableBody**).
+- Manages pagination and query state via hooks like `usePrevNextPagination` and `useKiwtSASQuery`.
+
+## Props
+
+| Name                            | Type              | Description                                                                                                                                                                                                                                                                                                                                                         | Default                                   | Required |
+|---------------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|----------|
+| `id`                            | `string`          | A unique identifier for the lookup instance. Used to generate unique keys for query state, persistent paneset, and filter pane visibility in local storage.                                                                                                                                                                                                         |                                           | ✓        |
+| `fetchParameters`               | `object`          | An object that defines the endpoints and SASQ configuration used for fetching data. It must include:<br><br>• **endpoint:** The URL used to fetch the main data set.<br>• **SASQ_MAP:** An object containing settings for search, filter, pagination (e.g., `searchKey`, `perPage`, etc.). Additional keys (such as `itemEndpoint`) can also be provided if needed. | `{}`                                      | ✓        |
+| `FilterComponent`               | `func` or `node`  | A custom component used to render additional filtering options in the filter pane. This component receives props for managing active filters, search state, and resetting filters.                                                                                                                                                                                  | `() => null`                              | ✕        |
+| `FilterPaneHeaderComponent`     | `func` or `node`  | A component rendered at the top of the filter pane. Use this to customize the header area of the filter pane.                                                                                                                                                                                                                                                       | `() => null`                              | ✕        |
+| `filterPaneProps`               | `object`          | Additional props to be passed to the filter pane. These props can customize the appearance and behavior of the filter pane (such as first or last menu elements).                                                                                                                                                                                                   | `{}`                                      | ✕        |
+| `intlKey`                       | `string`          | A base internationalization key used by the internal `useKintIntl` hook to resolve localized messages (e.g., for labels or pane titles).                                                                                                                                                                                                                            |                                           | ✕        |
+| `intlNS`                        | `string`          | An internationalization namespace used by the internal `useKintIntl` hook.                                                                                                                                                                                                                                                                                          |                                           | ✕        |
+| `labelOverrides`                | `object`          | An object for overriding default labels, such as the text for displaying the count of found values.                                                                                                                                                                                                                                                                 | `{}`                                      | ✕        |
+| `lookupQueryNamespaceGenerator` | `func`            | A function that generates a query namespace (an array) for `react-query` based on provided parameters such as `currentPage`, `namespace`, `id`, `query`, etc. This ensures that queries are uniquely identified.                                                                                                                                                    | See default implementation in source code | ✕        |
+| `mainPaneProps`                 | `object`          | Additional props to be passed to the main pane containing the lookup results. This can include custom menu elements or styling.                                                                                                                                                                                                                                     | `{}`                                      | ✕        |
+| `mclProps`                      | `object`          | Custom properties to be passed to the underlying Multi-Column List (MCL) component. These properties are merged with pagination props derived from `usePrevNextPagination`.                                                                                                                                                                                         | `{}`                                      | ✕        |
+| `noSearchField`                 | `bool`            | When set to `true`, the search field is not rendered in the filter pane. Use this if you want to disable search input.                                                                                                                                                                                                                                              | `false`                                   | ✕        |
+| `persistedPanesetProps`         | `object`          | Additional props to be passed to the **PersistedPaneset** component, which manages the persistent layout of the filter and main panes.                                                                                                                                                                                                                              | `{}`                                      | ✕        |
+| `queryParameterGenerator`       | `func`            | A function that takes the SASQ_MAP configuration and current query values to generate an array of query parameters for the fetch call. Defaults to `generateKiwtQuery`.                                                                                                                                                                                             | `generateKiwtQuery`                       | ✕        |
+| `RenderBody`                    | `func` or `node`  | A component used to render the body of the main pane (typically a table). If not provided, the internal **TableBody** component is used.                                                                                                                                                                                                                            | `TableBody`                               | ✕        |
+| `rowNavigation`                 | `bool`            | Flag to enable or disable row navigation. When enabled, clicking on a row triggers navigation to a detailed view.                                                                                                                                                                                                                                                   | `true`                                    | ✕        |
+| `sasqProps`                     | `object`          | Additional props to override or extend the default SASQ query behavior. These props can include custom query values, setters, or getters.                                                                                                                                                                                                                           |                                           | ✕        |
+| `searchableIndexes`             | `arrayOf(object)` | An array of objects defining the options for the search index selection component (`SearchKeyControl`), rendered below the search field. Each object typically has `value` and `label` keys. If empty or omitted, the qindex checkboxes are not shown.                                                                                                              | `[]`                                      | ✕        |
+| `searchFieldAriaLabel`          | `string`          | Accessibility label for the search field.                                                                                                                                                                                                                                                                                                                           |                                           | ✕        |
+| `searchFieldProps`              | `object`          | Additional props to be passed to the **SearchField** component for customizing its behavior or styling.                                                                                                                                                                                                                                                             |                                           | ✕        |
+| `children`                      | `node`, `func`    | Optional children to be rendered below the main pane. These are rendered within the **PersistedPaneset** container.                                                                                                                                                                                                                                                 |                                           | ✕        |
+Below is an additional section for **SASQLookupComponent** documentation that describes the available functionality on the component's ref along with a worked example.
+
+
+## Exposed Ref Functionality
+
+**SASQLookupComponent** uses `forwardRef` and `useImperativeHandle` to expose specific properties to parent components. This allows external components to access certain internal states and query-related information directly. The ref object includes the following properties:
+
+- **`lookupQueryProps`**:  
+  An object containing:
+    - **`data`**: The latest data fetched by the component.
+    - Additional query-related properties returned from `useQuery` (such as loading state, error, etc.).
+
+- **`queryParams`**:  
+  The array of query parameters generated by the component, based on the provided SASQ configuration and current query state. This reflects the current filters, pagination, and search criteria used for the data fetch.
+
+In general is is recommended not to use this functionality, as it represents an antipattern in React to pass information back up to the parents. Instead the implementing developer should try to replace the inner rendered components and do their logic there with the passed information.
+
+
+### Worked Example
+
+Below is a sample usage demonstrating how to access the exposed ref properties:
+
+```jsx
+import { useRef, useEffect } from 'react';
+import { SASQLookupComponent } from '@k-int/stripes-kint-components';
+
+const LookupWithRefExample = () => {
+  // Create a ref to access SASQLookupComponent's exposed methods and properties
+  const lookupRef = useRef();
+
+  useEffect(() => {
+    // When the component mounts or updates, you can access the lookupQueryProps and queryParams
+    if (lookupRef.current) {
+      const { lookupQueryProps, queryParams } = lookupRef.current;
+      console.log('Fetched data:', lookupQueryProps.data);
+      console.log('Current query parameters:', queryParams);
+      
+      // Example: Check if data is loaded and then trigger some side-effect
+      if (!lookupQueryProps.isLoading && lookupQueryProps.data) {
+        // Perform an action with the fetched data
+        console.log('Data is ready for processing');
+      }
+    }
+  }, []);
+
+  const fetchParameters = {
+    endpoint: '/api/my-items',
+    SASQ_MAP: {
+      searchKey: 'name',
+      perPage: 25
+    }
+  };
+
+  return (
+    <SASQLookupComponent
+      id="my-lookup"
+      path="/my-lookup"
+      fetchParameters={fetchParameters}
+      intlKey="myLookup"
+      intlNS="myApp"
+      ref={lookupRef}  // Attach the ref here
+      searchableIndexes={[
+        { key: 'name' },
+        { key: 'description' }
+      ]} // Provide options for search key selection
+    />
+  );
+};
+
+export default LookupWithRefExample;
+```
+
+## How It Works
+
+1. **Query and Pagination Management:**  
++ The component leverages hooks such as `usePrevNextPagination` (for page state), `useKiwtSASQuery` (for search/filter/sort state), and `useQuery` (from `react-query` for data fetching). The query parameters string is generated using the provided `queryParameterGenerator` function based on the `WorkspaceParameters.SASQ_MAP` and the current state from the hooks.
+2. **Filter Pane & Main Pane Layout:**
+    - **Filter Pane:**  
+      + Rendered conditionally based on local storage state (`filterPaneVisible`), it contains a search section (SearchField, SearchKeyControl if `searchableIndexes` are provided, Submit/Reset buttons - unless `noSearchField` is true) and custom filtering options provided via `FilterComponent` and `FilterPaneHeaderComponent`. Buttons for collapsing the pane are included.
+    - **Main Pane:**  
+      + Displays the fetched data using the `RenderBody` component (defaulting to `TableBody`). It integrates pagination controls (via `mclProps` passed to `RenderBody`) and displays record counts in the header. An expand button is shown if the filter pane is collapsed.
+3. **Persistent Layout:**  
+   The component wraps its content in a **PersistedPaneset** which maintains pane states (such as sizes and visibility) across sessions.
+
+4. **Customization and Extensibility:**  
+   Through various props, consumers can inject custom components (`FilterComponent`, `FilterPaneHeaderComponent`, `RenderBody`), override query generation (`queryParameterGenerator`, `lookupQueryNamespaceGenerator`), configure data fetching (`WorkspaceParameters`), pass props down to underlying components (`filterPaneProps`, `mainPaneProps`, `mclProps`, `persistedPanesetProps`, `searchFieldProps`), tweak SASQ behavior (`sasqProps`), and adjust UI elements (`noSearchField`, `labelOverrides`, `searchableIndexes`).
+5. **Ref Forwarding:**  
+   Using `forwardRef` and `useImperativeHandle`, the component exposes certain query properties and generated query parameters to parent components.
+
+This design enables **SASQLookupComponent** to serve as a robust and flexible foundation for building data lookup views with advanced filtering, search, and pagination functionalities.

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.