@k-int/stripes-kint-components 5.22.0 → 5.24.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/es/lib/SASQLookupComponent/SASQLookupComponent.js +53 -18
- package/es/lib/SearchKeyControl/SearchKeyControl.js +45 -21
- package/es/lib/utils/generateKiwtQueryParams/generateKiwtQueryParams.js +15 -1
- package/package.json +1 -1
- package/src/lib/SASQLookupComponent/README.md +58 -53
- package/src/lib/SASQLookupComponent/SASQLookupComponent.js +275 -232
- package/src/lib/SearchKeyControl/README.md +55 -30
- package/src/lib/SearchKeyControl/SearchKeyControl.js +34 -18
- package/src/lib/utils/generateKiwtQueryParams/generateKiwtQueryParams.js +15 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,17 @@
|
|
|
1
|
+
# [5.24.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.23.0...v5.24.0) (2025-07-02)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
### Features
|
|
5
|
+
|
|
6
|
+
* SASQLookupComponent -- lookupQueryPromise/lookupResponseTransform properties ([565d1d1](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/commit/565d1d1c3da273d7c207bc9cc5646222537c0cc9))
|
|
7
|
+
|
|
8
|
+
# [5.23.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.22.0...v5.23.0) (2025-06-25)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Features
|
|
12
|
+
|
|
13
|
+
* SearchKeyControl subIndexes ([40036a4](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/commit/40036a4353f24e47480e8060d901ef44c5c3b6ed))
|
|
14
|
+
|
|
1
15
|
# [5.22.0](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/compare/v5.21.0...v5.22.0) (2025-06-13)
|
|
2
16
|
|
|
3
17
|
|
|
@@ -44,6 +44,16 @@ const SASQLookupComponent = /*#__PURE__*/(0, _react.forwardRef)((props, ref) =>
|
|
|
44
44
|
queryNamespace.push(currentPage);
|
|
45
45
|
return queryNamespace;
|
|
46
46
|
},
|
|
47
|
+
lookupQueryPromise = _ref2 => {
|
|
48
|
+
let {
|
|
49
|
+
endpoint,
|
|
50
|
+
ky,
|
|
51
|
+
queryParams
|
|
52
|
+
} = _ref2;
|
|
53
|
+
return ky.get(`${endpoint}${queryParams}`).json();
|
|
54
|
+
},
|
|
55
|
+
lookupResponseTransform = response => response,
|
|
56
|
+
// Function to transform the response from the query
|
|
47
57
|
mainPaneProps = {},
|
|
48
58
|
mclProps = {},
|
|
49
59
|
noResultsProps = {},
|
|
@@ -70,12 +80,16 @@ const SASQLookupComponent = /*#__PURE__*/(0, _react.forwardRef)((props, ref) =>
|
|
|
70
80
|
querySetter: sasqPropsQuerySetter,
|
|
71
81
|
syncToLocation = true
|
|
72
82
|
} = sasqProps ?? {};
|
|
83
|
+
|
|
84
|
+
// We manage our internal state of pagination (URL vs MCL page state) using usePrevNextPagination.
|
|
85
|
+
// Below the queryParameterGenerator can then choose to use the outputs (namely totalRecords and page) as it sees fit.
|
|
73
86
|
const {
|
|
74
87
|
currentPage,
|
|
75
88
|
paginationMCLProps,
|
|
76
89
|
paginationSASQProps
|
|
77
90
|
} = (0, _hooks.usePrevNextPagination)({
|
|
78
91
|
count,
|
|
92
|
+
// totalRecord
|
|
79
93
|
pageSize: fetchParameters.SASQ_MAP?.perPage,
|
|
80
94
|
syncToLocation
|
|
81
95
|
});
|
|
@@ -92,10 +106,14 @@ const SASQLookupComponent = /*#__PURE__*/(0, _react.forwardRef)((props, ref) =>
|
|
|
92
106
|
} = (0, _core.useNamespace)();
|
|
93
107
|
const ky = (0, _core.useOkapiKy)();
|
|
94
108
|
const filterPaneVisibileKey = `${namespace}-${id}-filterPaneVisibility`;
|
|
95
|
-
const queryParams = (0, _react.useMemo)(() => queryParameterGenerator(
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
109
|
+
const queryParams = (0, _react.useMemo)(() => queryParameterGenerator(
|
|
110
|
+
// With Typescript this would be a type of SASQ_MAP, and so totalRecords is a valid property in our new shape
|
|
111
|
+
// In generateKiwtQueryParams we can choose to ignore totalRecords, which while being a valid property is not necessary for KIWT queries
|
|
112
|
+
{
|
|
113
|
+
page: currentPage,
|
|
114
|
+
totalRecords: count,
|
|
115
|
+
...fetchParameters.SASQ_MAP
|
|
116
|
+
}, query ?? {}), [count, currentPage, fetchParameters.SASQ_MAP, query, queryParameterGenerator]);
|
|
99
117
|
const [filterPaneVisible, setFilterPaneVisible] = (0, _hooks.useLocalStorageState)(filterPaneVisibileKey, true);
|
|
100
118
|
const toggleFilterPane = () => setFilterPaneVisible(!filterPaneVisible);
|
|
101
119
|
const {
|
|
@@ -109,10 +127,20 @@ const SASQLookupComponent = /*#__PURE__*/(0, _react.forwardRef)((props, ref) =>
|
|
|
109
127
|
query,
|
|
110
128
|
queryParams
|
|
111
129
|
}), () => {
|
|
112
|
-
return
|
|
130
|
+
return lookupQueryPromise({
|
|
131
|
+
ky,
|
|
132
|
+
queryParams,
|
|
133
|
+
endpoint: fetchParameters.endpoint
|
|
134
|
+
});
|
|
113
135
|
}, {
|
|
114
136
|
enabled: (!!query?.filters || !!query?.query) && !!currentPage,
|
|
115
|
-
...(fetchParameters.queryOptions ?? {})
|
|
137
|
+
...(fetchParameters.queryOptions ?? {}),
|
|
138
|
+
// select is a parameter supported by useQuery to transform the response
|
|
139
|
+
// Could be possible to instead pass this down along with the queryOptions
|
|
140
|
+
// Additionally this is assuming the lookupResponseTransform is a func as opposed to an object
|
|
141
|
+
select: selectData => {
|
|
142
|
+
return lookupResponseTransform(selectData);
|
|
143
|
+
}
|
|
116
144
|
});
|
|
117
145
|
(0, _react.useEffect)(() => {
|
|
118
146
|
if (count !== data?.totalRecords) {
|
|
@@ -169,6 +197,20 @@ const SASQLookupComponent = /*#__PURE__*/(0, _react.forwardRef)((props, ref) =>
|
|
|
169
197
|
setFilterPaneVisible,
|
|
170
198
|
toggleFilterPane
|
|
171
199
|
};
|
|
200
|
+
const renderFirstMenu = () => {
|
|
201
|
+
if (mainPaneFirstMenu) {
|
|
202
|
+
return mainPaneFirstMenu(internalStateProps);
|
|
203
|
+
}
|
|
204
|
+
if (!filterPaneVisible) {
|
|
205
|
+
return /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.PaneMenu, {
|
|
206
|
+
children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_smartComponents.ExpandFilterPaneButton, {
|
|
207
|
+
filterCount: filterCount,
|
|
208
|
+
onClick: toggleFilterPane
|
|
209
|
+
})
|
|
210
|
+
});
|
|
211
|
+
}
|
|
212
|
+
return null;
|
|
213
|
+
};
|
|
172
214
|
return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_smartComponents.PersistedPaneset, {
|
|
173
215
|
appId: namespace,
|
|
174
216
|
id: `${id}-paneset`,
|
|
@@ -238,12 +280,7 @@ const SASQLookupComponent = /*#__PURE__*/(0, _react.forwardRef)((props, ref) =>
|
|
|
238
280
|
})
|
|
239
281
|
}), /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.Pane, {
|
|
240
282
|
defaultWidth: "fill",
|
|
241
|
-
firstMenu:
|
|
242
|
-
children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_smartComponents.ExpandFilterPaneButton, {
|
|
243
|
-
filterCount: filterCount,
|
|
244
|
-
onClick: toggleFilterPane
|
|
245
|
-
})
|
|
246
|
-
}) : null,
|
|
283
|
+
firstMenu: renderFirstMenu(),
|
|
247
284
|
id: `${id}-main-pane`,
|
|
248
285
|
lastMenu: mainPaneLastMenu ? mainPaneLastMenu(internalStateProps) : null,
|
|
249
286
|
noOverflow: true,
|
|
@@ -286,21 +323,19 @@ SASQLookupComponent.propTypes = {
|
|
|
286
323
|
FilterComponent: _propTypes.default.oneOfType([_propTypes.default.func, _propTypes.default.node]),
|
|
287
324
|
FilterPaneHeaderComponent: _propTypes.default.oneOfType([_propTypes.default.func, _propTypes.default.node]),
|
|
288
325
|
queryParameterGenerator: _propTypes.default.func,
|
|
289
|
-
history: _propTypes.default.object,
|
|
290
326
|
id: _propTypes.default.string.isRequired,
|
|
291
327
|
intlKey: _propTypes.default.string,
|
|
292
328
|
intlNS: _propTypes.default.string,
|
|
293
329
|
labelOverrides: _propTypes.default.object,
|
|
294
|
-
|
|
330
|
+
lookupQueryNamespaceGenerator: _propTypes.default.func,
|
|
331
|
+
lookupQueryPromise: _propTypes.default.func,
|
|
332
|
+
lookupResponseTransform: _propTypes.default.func,
|
|
295
333
|
mainPaneProps: _propTypes.default.object,
|
|
296
|
-
match: _propTypes.default.object,
|
|
297
334
|
mclProps: _propTypes.default.object,
|
|
335
|
+
noResultsProps: _propTypes.default.object,
|
|
298
336
|
noSearchField: _propTypes.default.bool,
|
|
299
|
-
path: _propTypes.default.string.isRequired,
|
|
300
337
|
persistedPanesetProps: _propTypes.default.object,
|
|
301
338
|
RenderBody: _propTypes.default.oneOfType([_propTypes.default.func, _propTypes.default.node]),
|
|
302
|
-
resource: _propTypes.default.object,
|
|
303
|
-
resultColumns: _propTypes.default.arrayOf(_propTypes.default.object),
|
|
304
339
|
rowNavigation: _propTypes.default.bool,
|
|
305
340
|
sasqProps: _propTypes.default.object,
|
|
306
341
|
searchableIndexes: _propTypes.default.arrayOf(_propTypes.default.shape({
|
|
@@ -25,9 +25,12 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
|
|
|
25
25
|
|
|
26
26
|
// Memoise this process so keyState changes if and only if options/qIndex change
|
|
27
27
|
const createKeyState = (0, _react.useCallback)(() => options.reduce((acc, curr) => {
|
|
28
|
+
// Is in use if URL contains ALL of the indexes
|
|
29
|
+
const subindexes = (curr?.indexes?.length ?? 0) > 0 ? curr.indexes : [curr.key];
|
|
28
30
|
acc[curr.key] = {
|
|
29
|
-
inUse: qIndexArray
|
|
30
|
-
label: curr.label ?? curr.key
|
|
31
|
+
inUse: subindexes.every(si => qIndexArray.includes(si)),
|
|
32
|
+
label: curr.label ?? curr.key,
|
|
33
|
+
subIndexes: curr.indexes
|
|
31
34
|
};
|
|
32
35
|
return acc;
|
|
33
36
|
}, {}), [options, qIndexArray]);
|
|
@@ -48,11 +51,44 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
|
|
|
48
51
|
} = (0, _hooks.usePrevNextPagination)({
|
|
49
52
|
defaultToPageOne: false
|
|
50
53
|
});
|
|
54
|
+
const handleSearchKeyChange = (0, _react.useCallback)(_ref2 => {
|
|
55
|
+
let {
|
|
56
|
+
e: {
|
|
57
|
+
target: {
|
|
58
|
+
checked: targetIsChecked
|
|
59
|
+
} = {}
|
|
60
|
+
} = {},
|
|
61
|
+
key,
|
|
62
|
+
value
|
|
63
|
+
} = _ref2;
|
|
64
|
+
// Set up which indexes need to change
|
|
65
|
+
const indicesToChange = (value?.subIndexes?.length ?? 0) > 0 ? value.subIndexes : [key];
|
|
66
|
+
|
|
67
|
+
// If false, we must remove from the qIndex
|
|
68
|
+
if (!targetIsChecked) {
|
|
69
|
+
indicesToChange.forEach(ind => {
|
|
70
|
+
const indexOfKey = qIndexArray.indexOf(ind);
|
|
71
|
+
if (indexOfKey > -1) {
|
|
72
|
+
// only splice array when item is found
|
|
73
|
+
qIndexArray.splice(indexOfKey, 1); // 2nd parameter means remove one item only
|
|
74
|
+
}
|
|
75
|
+
});
|
|
76
|
+
} else {
|
|
77
|
+
// If true, we need to add to qIndex
|
|
78
|
+
indicesToChange.forEach(ind => {
|
|
79
|
+
qIndexArray.push(ind);
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
setQIndex(qIndexArray?.join(','));
|
|
83
|
+
if (currentPage) {
|
|
84
|
+
resetPage();
|
|
85
|
+
}
|
|
86
|
+
}, [currentPage, qIndexArray, resetPage, setQIndex]);
|
|
51
87
|
return /*#__PURE__*/(0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {
|
|
52
88
|
children: /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
|
|
53
89
|
className: _SearchKeyControl.default.searchKeyControlContainer,
|
|
54
|
-
children: Object.entries(keyState).map(
|
|
55
|
-
let [key, value] =
|
|
90
|
+
children: Object.entries(keyState).map(_ref3 => {
|
|
91
|
+
let [key, value] = _ref3;
|
|
56
92
|
/* At this point we have "key" corresponding to a searchKey option,
|
|
57
93
|
* and "value" an object of the shape
|
|
58
94
|
{
|
|
@@ -64,23 +100,11 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
|
|
|
64
100
|
checked: value?.inUse,
|
|
65
101
|
className: _SearchKeyControl.default.searchKeyControlElement,
|
|
66
102
|
label: value?.label,
|
|
67
|
-
onChange: e => {
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
// only splice array when item is found
|
|
73
|
-
qIndexArray.splice(indexOfKey, 1); // 2nd parameter means remove one item only
|
|
74
|
-
}
|
|
75
|
-
} else {
|
|
76
|
-
// If true, we need to add to qIndex
|
|
77
|
-
qIndexArray.push(key);
|
|
78
|
-
}
|
|
79
|
-
setQIndex(qIndexArray?.join(','));
|
|
80
|
-
if (currentPage) {
|
|
81
|
-
resetPage();
|
|
82
|
-
}
|
|
83
|
-
}
|
|
103
|
+
onChange: e => handleSearchKeyChange({
|
|
104
|
+
e,
|
|
105
|
+
key,
|
|
106
|
+
value
|
|
107
|
+
})
|
|
84
108
|
}, `search-key-control-${key}`);
|
|
85
109
|
})
|
|
86
110
|
})
|
|
@@ -53,6 +53,18 @@ const buildFilterOptionBlock = function (opf) {
|
|
|
53
53
|
}
|
|
54
54
|
return null;
|
|
55
55
|
};
|
|
56
|
+
|
|
57
|
+
/*
|
|
58
|
+
* GenerateKiwtQueryParams accepts
|
|
59
|
+
* SASQ_MAP shape "options" -- TODO write a TS shape for this
|
|
60
|
+
* SASQ "nsValues" shape "nsValues" -- TODO write a TS shape for this
|
|
61
|
+
* boolean "encode"
|
|
62
|
+
* It then uses these props to generate a query string for sending to KIWT type doTheLookupEndpoints
|
|
63
|
+
*/
|
|
64
|
+
|
|
65
|
+
// For now we can store the "safe to ignore" keys from the normal SASQ_MAP shape here.
|
|
66
|
+
// These will be ignored rather than appended directly to the query as per normal.
|
|
67
|
+
const keysToIgnore = ['totalRecords'];
|
|
56
68
|
const generateKiwtQueryParams = function (options, nsValues) {
|
|
57
69
|
let encode = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
|
|
58
70
|
const {
|
|
@@ -185,7 +197,9 @@ const generateKiwtQueryParams = function (options, nsValues) {
|
|
|
185
197
|
paramsArray.push('stats=true');
|
|
186
198
|
}
|
|
187
199
|
for (const [key, value] of Object.entries(rest)) {
|
|
188
|
-
|
|
200
|
+
if (!keysToIgnore.includes(key)) {
|
|
201
|
+
paramsArray.push(`${key}=${conditionalEncodeURIComponent(value, encode)}`);
|
|
202
|
+
}
|
|
189
203
|
}
|
|
190
204
|
return paramsArray;
|
|
191
205
|
};
|
package/package.json
CHANGED
|
@@ -46,58 +46,64 @@ const MyLookupView = () => {
|
|
|
46
46
|
};
|
|
47
47
|
|
|
48
48
|
export default MyLookupView;
|
|
49
|
-
|
|
49
|
+
````
|
|
50
50
|
|
|
51
51
|
In this example, **SASQLookupComponent**:
|
|
52
52
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
53
|
+
* Uses `fetchParameters` to configure data fetching.
|
|
54
|
+
* Provides a custom filter interface via `FilterComponent`.
|
|
55
|
+
* Renders results using a custom table body (or defaults to an internal **TableBody**).
|
|
56
|
+
* Manages pagination and query state via hooks like `usePrevNextPagination` and `useKiwtSASQuery`.
|
|
57
57
|
|
|
58
58
|
## Props
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
|
|
85
|
-
|
|
59
|
+
| Name | Type | Description | Default | Required |
|
|
60
|
+
|---------------------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|----------|
|
|
61
|
+
| `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. | | ✓ |
|
|
62
|
+
| `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. This is effectively required for data fetching to work.\<br\>• **SASQ\_MAP:** An object containing settings for search, filter, pagination (e.g., `searchKey`, `perPage`, etc.). | `{}` | ✕ |
|
|
63
|
+
| `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` | ✕ |
|
|
64
|
+
| `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` | ✕ |
|
|
65
|
+
| `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). | `{}` | ✕ |
|
|
66
|
+
| `intlKey` | `string` | A base internationalization key used by the internal `useKintIntl` hook to resolve localized messages (e.g., for labels or pane titles). | | ✕ |
|
|
67
|
+
| `intlNS` | `string` | An internationalization namespace used by the internal `useKintIntl` hook. | | ✕ |
|
|
68
|
+
| `labelOverrides` | `object` | An object for overriding default labels, such as the text for displaying the count of found values. | `{}` | ✕ |
|
|
69
|
+
| `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 | ✕ |
|
|
70
|
+
| `lookupQueryPromise` | `func` | A function to execute the data fetching promise. Receives an object with `endpoint`, `ky` (OkapiKy instance), `queryParams`. Should return a Promise that resolves to the fetched data. This is in place to allow for varying fetch methodologies, such as implementing a non-FOLIO ky instance. | See default implementation in source code | ✕ |
|
|
71
|
+
| `lookupResponseTransform` | `func` | A function passed to the "select" prop of react-query useQuery, allowing for direct transformation of the return shape of data. | response => response | ✕ |
|
|
72
|
+
| `mainPaneProps` | `object` | Additional props to be passed to the main pane containing the lookup results. This can include custom menu elements or styling. | `{}` | ✕ |
|
|
73
|
+
| `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`. | `{}` | ✕ |
|
|
74
|
+
| `noResultsProps` | `object` | Props to be passed down to the [NoResultsMessage](https://gitlab.com/knowledge-integration/folio/stripes-kint-components/-/tree/main/src/lib/NoResultsMessage) splash screen component rendered when no results are present from the query. If `component` is passed, this will be rendered with the props available to `NoResultsMessage`. | `{}` | ✕ |
|
|
75
|
+
| `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` | ✕ |
|
|
76
|
+
| `persistedPanesetProps` | `object` | Additional props to be passed to the **PersistedPaneset** component, which manages the persistent layout of the filter and main panes. | `{}` | ✕ |
|
|
77
|
+
| `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` | ✕ |
|
|
78
|
+
| `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` | ✕ |
|
|
79
|
+
| `rowNavigation` | `bool` | Flag to enable or disable row navigation. When enabled, clicking on a row triggers navigation to a detailed view. | `true` | ✕ |
|
|
80
|
+
| `sasqProps` | `object` | Additional props to override or extend the default SASQ query behavior. These props can include custom query values, setters, getters, and `initialSortState`. | | ✕ |
|
|
81
|
+
| `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 `key` and `label` keys. If empty or omitted, the qindex checkboxes are not shown. | `[]` | ✕ |
|
|
82
|
+
| `searchFieldAriaLabel` | `string` | Accessibility label for the search field. | | ✕ |
|
|
83
|
+
| `searchFieldProps` | `object` | Additional props to be passed to the **SearchField** component for customizing its behavior or styling. | `{}` | ✕ |
|
|
84
|
+
| `children` | `node`, `func` | Optional children to be rendered below the main pane. These are rendered within the **PersistedPaneset** container. | | ✕ |
|
|
85
|
+
| `history` | `object` | (Provided by React Router) The history object. | | ✕ |
|
|
86
|
+
| `location` | `object` | (Provided by React Router) The location object. | | ✕ |
|
|
87
|
+
| `match` | `object` | (Provided by React Router) The match object. | | ✕ |
|
|
88
|
+
| `path` | `string` | (Provided by React Router) The path for the current route. | | ✓ |
|
|
89
|
+
| `resource` | `object` | (Provided by Stripes) The resource object, typically containing data and metadata for the current resource. | | ✕ |
|
|
90
|
+
| `resultColumns` | `arrayOf(object)` | An array of objects defining the columns for the MCL component, typically used by `RenderBody` (e.g., `TableBody`). | | ✕ |
|
|
86
91
|
|
|
87
92
|
## Exposed Ref Functionality
|
|
88
93
|
|
|
89
94
|
**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:
|
|
90
95
|
|
|
91
|
-
|
|
96
|
+
* **`lookupQueryProps`**:
|
|
92
97
|
An object containing:
|
|
93
|
-
- **`data`**: The latest data fetched by the component.
|
|
94
|
-
- Additional query-related properties returned from `useQuery` (such as loading state, error, etc.).
|
|
95
98
|
|
|
96
|
-
|
|
97
|
-
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.
|
|
99
|
+
* **`data`**: The latest data fetched by the component.
|
|
98
100
|
|
|
99
|
-
|
|
101
|
+
* Additional query-related properties returned from `useQuery` (such as loading state, error, etc.).
|
|
100
102
|
|
|
103
|
+
* **`queryParams`**:
|
|
104
|
+
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.
|
|
105
|
+
|
|
106
|
+
In general it 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.
|
|
101
107
|
|
|
102
108
|
### Worked Example
|
|
103
109
|
|
|
@@ -117,7 +123,7 @@ const LookupWithRefExample = () => {
|
|
|
117
123
|
const { lookupQueryProps, queryParams } = lookupRef.current;
|
|
118
124
|
console.log('Fetched data:', lookupQueryProps.data);
|
|
119
125
|
console.log('Current query parameters:', queryParams);
|
|
120
|
-
|
|
126
|
+
|
|
121
127
|
// Example: Check if data is loaded and then trigger some side-effect
|
|
122
128
|
if (!lookupQueryProps.isLoading && lookupQueryProps.data) {
|
|
123
129
|
// Perform an action with the fetched data
|
|
@@ -155,19 +161,18 @@ export default LookupWithRefExample;
|
|
|
155
161
|
|
|
156
162
|
## How It Works
|
|
157
163
|
|
|
158
|
-
1.
|
|
159
|
-
|
|
160
|
-
2.
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
3.
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
Using `forwardRef` and `useImperativeHandle`, the component exposes certain query properties and generated query parameters to parent components.
|
|
164
|
+
1. **Query and Pagination Management:**
|
|
165
|
+
* 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 `fetchParameters.SASQ_MAP` and the current state from the hooks.
|
|
166
|
+
2. **Filter Pane & Main Pane Layout:**
|
|
167
|
+
* **Filter Pane:**
|
|
168
|
+
* 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.
|
|
169
|
+
* **Main Pane:**
|
|
170
|
+
* 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.
|
|
171
|
+
3. **Persistent Layout:**
|
|
172
|
+
The component wraps its content in a **PersistedPaneset** which maintains pane states (such as sizes and visibility) across sessions.
|
|
173
|
+
4. **Customization and Extensibility:**
|
|
174
|
+
Through various props, consumers can inject custom components (`FilterComponent`, `FilterPaneHeaderComponent`, `RenderBody`), override query generation (`queryParameterGenerator`, `lookupQueryNamespaceGenerator`), configure data fetching (`fetchParameters`), pass props down to underlying components (`filterPaneProps`, `mainPaneProps`, `mclProps`, `persistedPanesetProps`, `searchFieldProps`), tweak SASQ behavior (`sasqProps`), and adjust UI elements (`noSearchField`, `labelOverrides`, `searchableIndexes`).
|
|
175
|
+
5. **Ref Forwarding:**
|
|
176
|
+
Using `forwardRef` and `useImperativeHandle`, the component exposes certain query properties and generated query parameters to parent components.
|
|
172
177
|
|
|
173
178
|
This design enables **SASQLookupComponent** to serve as a robust and flexible foundation for building data lookup views with advanced filtering, search, and pagination functionalities.
|