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

package/src/lib/EditableSettingsList/SettingField/EditSettingValue/README.md

@@ -0,0 +1,63 @@
+# EditSettingValue
+
+A component responsible for rendering the correct input field when a setting is in edit mode within the `SettingField` component. It selects and configures the appropriate `react-final-form` `<Field>`-wrapped input component (`@folio/stripes/components` `TextField`, `Select`, or a custom `RefdataButtons` component) based on the `settingType` specified in the setting's configuration (`currentSetting` prop).
+
+This component is designed to be rendered by `SettingField` when the `editing` prop is true. It receives form control props (`input`) from the parent `react-final-form` `<Field>` and contextual data (`refdata`, `templates`) needed for specific input types like dropdowns or radio buttons. It ensures that the edited value is correctly bound to the `.value` property of the setting object within the form state.
+
+## Basic Usage
+
+`EditSettingValue` is used internally by the `SettingField` component when its `editing` prop is true. It's not typically instantiated directly in application code but rather chosen dynamically by `SettingField`.
+
+```jsx
+// EditSettingValue is used internally by the SettingField component
+// when its 'editing' prop is true.
+
+// Simplified structure within SettingField's render method:
+import EditSettingValue from './EditSettingValue'; // Adjust path
+import RenderSettingValue from './RenderSettingValue'; // For comparison
+
+const SettingField = ({ editing, input, meta, currentSetting, refdata, templates, ...rest }) => {
+  // ... other logic like fetching refdata/templates ...
+
+  let RenderFunction;
+  if (editing === false) {
+    // When not editing, SettingField uses RenderSettingValue
+    RenderFunction = RenderSettingValue;
+  } else {
+    // When editing is true, SettingField switches to EditSettingValue:
+    RenderFunction = EditSettingValue;
+  }
+
+  return (
+    <Card /* Card setup */ >
+      {/* RenderFunction will be EditSettingValue when editing is true */}
+      <RenderFunction
+        currentSetting={currentSetting}
+        input={input} // Passed from the parent <Field>
+        meta={meta} // Also passed from the parent <Field>
+        refdata={refdata} // Fetched refdata if settingType is 'Refdata'
+        templates={templates} // Fetched templates if settingType is 'Template'
+        {...rest} // Other relevant props like intlKey, intlNS, labelOverrides etc.
+      />
+    </Card>
+  );
+};
+```
+
+The specific input rendered depends on `currentSetting.settingType`:
+* **'Refdata'**: Renders `<Select>` or `<RefdataButtons>` based on the number of options in the `refdata` prop.
+* **'Password'**: Renders `<TextField type="password">`.
+* **'Template'**: Renders `<Select>` populated from the `templates` prop.
+* **Default/Other**: Renders a standard `<TextField>`.
+
+## Props
+
+| Name             | Type     | Description                                                                                                                                                                                                                                                                    | default     | required                            |
+|------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|-------------------------------------|
+| `currentSetting` | `object` | The configuration object for the setting being edited. Its `settingType` property dictates which input component is rendered, and `key` is used for generating labels.                                                                                                         | `undefined` | ✓                                   |
+| `input`          | `object` | Provided by the parent `react-final-form` `<Field>`. Contains the field's `name`, `value`, `onChange`, `onBlur`, etc., connecting the rendered input to the form state. The component uses `input.name` to construct the name for the nested field (e.g., `parentName.value`). | `undefined` | ✓                                   |
+| `intlKey`        | `string` | Base key for internationalization passed to the `useKintIntl` hook, used for generating the `aria-label`.                                                                                                                                                                      | `undefined` | ✕                                   |
+| `intlNS`         | `string` | Namespace for internationalization passed to the `useKintIntl` hook, used for generating the `aria-label`.                                                                                                                                                                     | `undefined` | ✕                                   |
+| `labelOverrides` | `object` | An object potentially containing overrides for specific internationalization message IDs used in this component (e.g., `valueFor`).                                                                                                                                            | `{}`        | ✕                                   |
+| `refdata`        | `array`  | An array of reference data objects (typically `{ id, value, label }`). Expected to be provided if `currentSetting.settingType` is 'Refdata'. Used to populate the `Select` or `RefdataButtons` component.                                                                      | `undefined` | Conditional (✓ for 'Refdata' type)  |
+| `templates`      | `array`  | An array of template objects (expected shape `{ id, name }`). Expected to be provided if `currentSetting.settingType` is 'Template'. Used to populate the `Select` component.                                                                                                  | `undefined` | Conditional (✓ for 'Template' type) |

package/src/lib/EditableSettingsList/SettingField/EditSettingValue/index.js

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

package/src/lib/EditableSettingsList/SettingField/README.md

@@ -0,0 +1,61 @@
+# SettingField
+
+A component designed to render a single setting within a settings list. It handles fetching contextual data (like reference data via `useRefdata` or templates via `useTemplates` based on the setting's configuration), displays the setting's name, help text (`InfoPopover`), and value, and manages the switch between display mode (using `RenderSettingValue`) and edit mode (using `EditSettingValue`).
+
+It is typically used as the `component` prop for a `react-final-form` `<Field>` within the structure provided by `EditableSettingsListFieldArray` and `EditableSettingsList`. It utilizes `@folio/stripes/components` (`Card`, `Button`, `InfoPopover`) for its UI structure and relies on `SettingsContext` to determine API endpoints for fetching related data.
+
+## Basic Usage
+
+`SettingField` is usually rendered internally by the `DefaultField` implementation within `EditableSettingsListField`. It receives props from `react-final-form`'s `<Field>` (like `input`, `meta`) and custom props from `EditableSettingsListField` (like `editing`, `setEditing`, `settingData`, `onSave`).
+
+```jsx
+// SettingField is typically used internally by EditableSettingsListField.
+// The default implementation within EditableSettingsListField looks
+// somewhat like this:
+
+import { Field } from 'react-final-form';
+
+// Inside EditableSettingsListField's render logic (simplified):
+<Field
+  // Props passed down:
+  allowEdit={props.allowEdit}
+  component={SettingField} // <-- Usage of SettingField
+  editing={props.editing}
+  intlKey={props.intlKey}
+  intlNS={props.intlNS}
+  labelOverrides={props.labelOverrides}
+  onSave={props.onSave} // Specific save handler for this row
+  setEditing={props.setEditing} // Function to toggle editing state for this row
+  settingData={props.settingData} // Object containing currentSetting etc.
+
+  // Props provided by Field:
+  name={settingIdentifier} // The name/path for this field within the form
+  // 'input' and 'meta' props are also automatically passed by Field
+/>
+
+// Direct usage is less common but possible if customizing the `render` prop
+// of EditableSettingsListFieldArray or EditableSettingsList.
+
+// Note: The actual rendering of the setting's value in view or edit mode
+// is delegated to the RenderSettingValue and EditSettingValue components,
+// respectively, based on the 'editing' prop and the setting's configuration
+// (currentSetting.settingType).
+```
+
+**Note:** This component requires `SettingsContext` to be available higher up in the component tree to provide `refdataEndpoint` and `templateEndpoint`.
+
+## Props
+
+| Name                         | Type      | Description                                                                                                                                                                                                                                                                                                       | default     | required   |
+|------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|------------|
+| `allowEdit`                  | `boolean` | Controls whether the "Edit"/"Save" button is displayed and if editing is permitted. Passed down from parent components.                                                                                                                                                                                           | `true`      | ✕          |
+| `editing`                    | `boolean` | Determines if the field should render in display mode (`RenderSettingValue`) or edit mode (`EditSettingValue`). This state is typically managed by the parent `EditableSettingsListField`.                                                                                                                        | `undefined` | ✓          |
+| `input`                      | `object`  | Provided by `react-final-form`'s `<Field>`. Contains field state like `value`, `name`, and callbacks like `onChange`, `onBlur`. Crucial for connecting to the form state, passed down to `EditSettingValue`.                                                                                                      | `undefined` | ✓ (by RFF) |
+| `intlKey`                    | `string`  | Base key for internationalization, used by the internal `useKintIntl` hook for fetching labels and messages.                                                                                                                                                                                                      | `undefined` | ✕          |
+| `intlNS`                     | `string`  | Namespace for internationalization, used by the internal `useKintIntl` hook.                                                                                                                                                                                                                                      | `undefined` | ✕          |
+| `labelOverrides`             | `object`  | An object potentially used to override default labels, passed down to `RenderSettingValue`/`EditSettingValue`.                                                                                                                                                                                                    | `{}`        | ✕          |
+| `meta`                       | `object`  | Provided by `react-final-form`'s `<Field>`. Contains metadata about the field state, such as `touched`, `error`, `dirty`, `valid`, etc.                                                                                                                                                                           | `undefined` | ✓ (by RFF) |
+| `onSave`                     | `func`    | Callback function triggered when the "Save" button is clicked (while `editing` is true). It should handle the persistence logic for this *single setting* and is expected to return a `Promise`. The success of the promise determines whether the component switches back to display mode (`setEditing(false)`). | `undefined` | ✓          |
+| `setEditing`                 | `func`    | A function, provided by the parent component (e.g., `EditableSettingsListField`), used to signal a change in the editing state (e.g., `setEditing(true)` when "Edit" is clicked, or `setEditing(false)` after a successful save).                                                                                 | `undefined` | ✓          |
+| `settingData`                | `object`  | An object containing data pertinent to the specific setting being rendered.                                                                                                                                                                                                                                       | `undefined` | ✓          |
+| `settingData.currentSetting` | `object`  | The core configuration object for the setting currently being rendered. Contains properties like `key`, `section`, `settingType`, `vocab`, etc., which drive the component's behavior (fetching data, rendering labels, choosing input types via `EditSettingValue`).                                             | `undefined` | ✓          |

package/src/lib/EditableSettingsList/SettingField/{RenderSettingValue.js → RenderSettingValue/RenderSettingValue.js}

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 
-import { useKintIntl } from '../../hooks';
+import { useKintIntl } from '../../../hooks';
 
 const RenderSettingValue = (props) => {
   const {

package/src/lib/EditableSettingsList/SettingField/{RenderSettingValue.test.js → RenderSettingValue/RenderSettingValue.test.js}

@@ -2,9 +2,9 @@ import React from 'react';
 
 import RenderSettingValue from './RenderSettingValue';
 
-import { renderWithKintHarness } from '../../../../test/jest/helpers';
+import { renderWithKintHarness } from '../../../../../test/jest/helpers';
 
-jest.mock('../../hooks');
+jest.mock('../../../hooks');
 
 const stringSetting = {
   id: '12345',

package/src/lib/EditableSettingsList/SettingField/RenderSettingValue/index.js

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

package/src/lib/EditableSettingsList/SettingField/SettingField.js

@@ -1,4 +1,4 @@
-import React, { useContext, useState } from 'react';
+import { useContext } from 'react';
 import PropTypes from 'prop-types';
 
 import {
@@ -18,16 +18,17 @@ import renderHelpTextCSS from '../../../../styles/renderHelpText.css';
 const SettingField = (settingFieldProps) => {
   const {
     allowEdit = true,
+    editing,
     intlKey: passedIntlKey,
     intlNS: passedIntlNS,
     labelOverrides = {},
     onSave,
+    setEditing,
     settingData: {
       currentSetting
     } = {}
   } = settingFieldProps;
 
-  const [editing, setEditing] = useState(false);
   const kintIntl = useKintIntl(passedIntlKey, passedIntlNS);
   const { refdataEndpoint, templateEndpoint } = useContext(SettingsContext);
 
@@ -39,7 +40,8 @@ const SettingField = (settingFieldProps) => {
     endpoint: refdataEndpoint,
     desc: currentSetting.vocab,
     queryParams: {
-      enabled: !!currentSetting?.vocab && currentSetting.settingType === 'Refdata'
+      enabled: !!currentSetting?.vocab && currentSetting.settingType === 'Refdata',
+      staleTime: 1000 * 60 * 2 // 2 minutes staletime for refdata in settings?
     }
   });
 

package/src/lib/EditableSettingsList/SettingField/SettingField.test.js

@@ -25,50 +25,71 @@ const setting = {
   value: 'diku-shared'
 };
 
-describe('SettingField', () => {
-  let renderComponent;
-  beforeEach(async () => {
-    renderComponent = renderWithKintHarness(
-      <TestForm
-        initialValues={{}}
-        onSubmit={onSubmit}
-      >
-        <Field
-          component={SettingField}
-          name="test"
-          onSave={onSave}
-          settingData={{
-            currentSetting: setting
-          }}
-        />
-      </TestForm>
-    );
-  });
-
-  it('renders RenderSettingValue', async () => {
-    const { getByText } = renderComponent;
-    await waitFor(async () => expect(await getByText('RenderSettingValue')).toBeInTheDocument());
-  });
-
-  test('renders the edit button', () => {
-    Button('Edit').exists();
-  });
+const setEditing = jest.fn();
 
-  it('clicking edit/save works as expected', async () => {
-    const { findByText } = renderComponent;
-    // before clicking on edit button, we should be rendering setting value
-    await waitFor(async () => expect(await findByText('RenderSettingValue')).toBeInTheDocument());
-
-    // Clicking edit button
-    await waitFor(async () => { await Button('Edit').click(); });
-
-    // Should be rendering the "edit" for a setting value
-    await waitFor(async () => expect(await findByText('EditSettingValue')).toBeInTheDocument());
-
-    // Clicking save button
-    await waitFor(async () => { await Button('Save').click(); });
-
-    // Should be rendering the setting value again
-    await waitFor(async () => expect(await findByText('RenderSettingValue')).toBeInTheDocument());
+let renderComponent;
+describe('SettingField', () => {
+  describe.each([
+    {
+      editing: false,
+      expectedRender: 'RenderSettingValue',
+      expectedButton: 'Edit',
+      expectedCallback: setEditing,
+    },
+    {
+      editing: true,
+      expectedRender: 'EditSettingValue',
+      expectedButton: 'Save',
+      expectedCallback: onSave,
+
+    }
+  ])('render SettingField with editing: editing', ({
+    editing,
+    expectedButton,
+    expectedCallback,
+    expectedRender
+  }) => {
+    beforeEach(async () => {
+      setEditing.mockClear();
+      onSave.mockClear();
+      renderComponent = renderWithKintHarness(
+        <TestForm
+          initialValues={{}}
+          onSubmit={onSubmit}
+        >
+          <Field
+            component={SettingField}
+            editing={editing}
+            name="test"
+            onSave={onSave}
+            setEditing={setEditing}
+            settingData={{
+              currentSetting: setting
+            }}
+          />
+        </TestForm>
+      );
+    });
+
+    it(`renders ${expectedRender}`, () => {
+      const { getByText } = renderComponent;
+      expect(getByText(expectedRender)).toBeInTheDocument();
+    });
+
+    test(`renders the ${expectedButton} button`, () => {
+      Button('Edit').exists();
+    });
+
+    describe(`clicking the ${expectedButton} button`, () => {
+      beforeEach(async () => {
+        await waitFor(async () => {
+          await Button(expectedButton).click();
+        });
+      });
+
+      it('fired expected callback', () => {
+        expect(expectedCallback).toHaveBeenCalled();
+      });
+    });
   });
 });

package/src/lib/EditableSettingsList/index.js

@@ -1,3 +1,3 @@
 export { default as EditableSettingsList } from './EditableSettingsList';
 export { default as EditableSettingsListFieldArray } from './EditableSettingsListFieldArray';
-export { SettingField } from './SettingField';
+export { SettingField, RenderSettingValue, EditSettingValue } from './SettingField';

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.