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

package/es/lib/hooks/useMutateRefdataValue/index.js

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

package/es/lib/hooks/{useMutateRefdataValue.js → useMutateRefdataValue/useMutateRefdataValue.js}

@@ -5,8 +5,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _noop = _interopRequireDefault(require("lodash/noop"));
-var _useInvalidateRefdata = _interopRequireDefault(require("./useInvalidateRefdata"));
-var _useMutateGeneric = _interopRequireDefault(require("./useMutateGeneric"));
+var _useInvalidateRefdata = _interopRequireDefault(require("../useInvalidateRefdata"));
+var _useMutateGeneric = _interopRequireDefault(require("../useMutateGeneric"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const useMutateRefdataValue = _ref => {
   let {

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.1",
   "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}
@@ -367,6 +372,10 @@ SASQLookupComponent.propTypes = {
   resultColumns: PropTypes.arrayOf(PropTypes.object),
   rowNavigation: PropTypes.bool,
   sasqProps: PropTypes.object,
+  searchableIndexes: PropTypes.arrayOf(PropTypes.shape({
+    key: PropTypes.string.isRequired,
+    label: PropTypes.string
+  })),
   searchFieldAriaLabel: PropTypes.string,
   searchFieldProps: PropTypes.object
 };

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.