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

package/src/lib/settingsHooks/useSettings/README.md

@@ -0,0 +1,84 @@
+# useSettings
+
+A comprehensive hook that manages the retrieval and configuration of settings data for one or multiple sections. It orchestrates multiple queries with `react-query`, constructs dynamic pages for each settings section, and returns a pre-configured `SettingsComponent` for rendering the settings UI.
+
+## Overview
+
+`useSettings` serves several purposes:
+
+- **Multi-Section Querying:**  
+  It supports both single and multiple settings sections. Depending on the provided props, it dynamically generates query parameters and uses `useQueries` to fetch data for each section.
+
+- **Dynamic Page Generation:**  
+  When queries return data, it extracts unique section names to create dynamic pages. Each page includes a route, localized label, and a component that wraps a `SettingPage` in a `SettingPagePane`.
+
+- **Context and Configuration:**  
+  The hook creates a `SettingsContextProvider` to pass down configuration details (like API endpoints and internationalization keys) to its children. This ensures that each section or page has the necessary context for rendering.
+
+- **Final Settings Component:**  
+  It returns a `SettingsComponent` that wraps the list of pages or sections using the `Settings` component from `@folio/stripes/smart-components`. This component can then be directly rendered in the application.
+
+## Basic Usage
+
+```jsx
+const SettingsContainer = () => {
+  const {
+    isLoading,
+    SettingsComponent,
+    pageList,
+    sections,
+    SettingsContextProvider,
+  } = useSettings({
+    sectionName: 'general',
+    settingEndpoint: '/settings',
+    refdataEndpoint: '/refdata',
+    // Other optional props for customization...
+  });
+
+  if (isLoading) return <div>Loading settings...</div>;
+
+  return <SettingsComponent />;
+};
+```
+
+## Parameters
+
+`useSettings` accepts an optional settings props object (`settingsProps`) that may include the following properties:
+
+| Name                   | Type     | Description                                                                                                                                                                                                                                | Required |
+|------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+| `allowGlobalEdit`      | `boolean`| Global flag to enable or disable editing of settings. Defaults to `true`.                                                                                                                                                                  | ✕        |
+| `dynamicPageExclusions`| `array`  | Array of section names to be excluded from dynamic page generation.                                                                                                                                                                        | ✕        |
+| `intlKey`              | `string` | Base internationalization key for resolving labels.                                                                                                                                                                                        | ✕        |
+| `intlNS`               | `string` | Internationalization namespace.                                                                                                                                                                                                            | ✕        |
+| `labelOverrides`       | `object` | Custom label overrides for specific settings keys.                                                                                                                                                                                         | ✕        |
+| `pages`                | `array`  | If provided, acts as a passthrough configuration for either sections or standalone pages, disabling query execution.                                                                                                                       | ✕        |
+| `persistentPages`      | `array`  | Array of pages that persist regardless of dynamic query results.                                                                                                                                                                           | ✕        |
+| `preventQueries`       | `boolean`| Flag to disable querying if settings data is provided externally.                                                                                                                                                                          | ✕        |
+| `refdataEndpoint`      | `string` | The API endpoint to retrieve reference data for settings.                                                                                                                                                                                  | ✕        |
+| `renderSingleSection`  | `boolean`| When only one section is available, determines if it should be rendered as a single section with its own label.                                                                                                                            | ✕        |
+| `sectionPermission`    | `string` | Permission string that, if provided, restricts the rendering of a section unless the current user has the specified permission.                                                                                                            | ✕        |
+| `sectionRoute`         | `string` | Base route path to be used when constructing dynamic page routes for settings sections.                                                                                                                                                    | ✕        |
+| `sections`             | `array`  | Array of section configuration objects. Each object can override or extend the global settings props for that specific section. This means that the shape here matches more or less the shape for the props of `useSettings` itself.       | ✕        |
+| `settingEndpoint`      | `string` | The base URL endpoint for fetching and updating settings.                                                                                                                                                                                  | ✕        |
+| `templateEndpoint`     | `string` | The endpoint for retrieving settings templates (if applicable).                                                                                                                                                                            | ✕        |
+| `render`               | `func`   | A custom render function for rendering individual setting fields. This function is passed down to the underlying settings components for specialized display logic. See `EditableSettingsList` for more information on how render is used. | ✕        |
+
+## Returns
+
+The hook returns an object containing:
+
+- **`isLoading`** (`boolean`):  
+  Indicates if any of the settings queries are still loading.
+
+- **`pageList`** (`array`):  
+  An array of pages to be rendered by the `Settings` component. This is the final list of pages for a single section, if applicable.
+
+- **`sections`** (`array`):  
+  An array of fully configured sections. Each section includes its own `SettingsContextProvider`, dynamic pages, and additional configuration data.
+
+- **`SettingsComponent`** (`React Component`):  
+  A component pre-configured with the pages and sections that renders the settings UI. This component wraps the settings in the required `Settings` component from `@folio/stripes/smart-components`.
+
+- **`SettingsContextProvider`** (`React Component`):  
+  A context provider component for settings configuration. If only one section is available, it is provided directly; otherwise, it defaults to a pass-through provider.

package/src/lib/settingsHooks/useSettings/index.js

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

package/src/lib/settingsHooks/{useSettings.js → useSettings/useSettings.js}

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import PropTypes from 'prop-types';
 
 import { useQueries } from 'react-query';
@@ -6,11 +6,11 @@ import { useOkapiKy, useStripes } from '@folio/stripes/core';
 
 import { Settings } from '@folio/stripes/smart-components';
 
-import { SettingPage, SettingPagePane } from '../SettingPage';
-import { SettingsContext } from '../contexts';
+import { SettingPage, SettingPagePane } from '../../SettingPage';
+import { SettingsContext } from '../../contexts';
 
-import { generateKiwtQueryParams, sortByLabel, toCamelCase } from '../utils';
-import { useKintIntl, useIntlKey } from '../hooks';
+import { generateKiwtQueryParams, sortByLabel, toCamelCase } from '../../utils';
+import { useKintIntl, useIntlKey } from '../../hooks';
 
 // TODO work underway to make the settings hook more useful when trying to render multiple sections at a time
 const useSettings = (settingsProps = {}) => {
@@ -30,7 +30,8 @@ const useSettings = (settingsProps = {}) => {
     sections, // if present, should be an array of objects with the SAME shape as the overall props here.
     // If a prop isn't present it can fall back to the "global" prop.
     settingEndpoint,
-    templateEndpoint
+    templateEndpoint,
+    render, // Allow setting-by-setting rendering of fields, to allow for special treatment for a given setting key etc
   } = settingsProps;
 
   const ky = useOkapiKy();
@@ -100,6 +101,7 @@ const useSettings = (settingsProps = {}) => {
   const getDynamicPages = useCallback((qra, sma) => {
     const pagesFromQueryReturn = [...new Set(qra.data?.map(s => s.section))];
     const dynamic = pagesFromQueryReturn.map(page => {
+      const finalRender = sma.render ?? render;
       const finalSectionRoute = sma.sectionRoute ?? sectionRoute;
       const pageRoute = (finalSectionRoute ? `${finalSectionRoute}/` : '') + page;
       return (
@@ -120,6 +122,7 @@ const useSettings = (settingsProps = {}) => {
                 intlKey={passedIntlKey}
                 intlNS={passedIntlNS}
                 labelOverrides={labelOverrides}
+                render={finalRender}
                 sectionName={page}
                 {...props}
               />
@@ -133,7 +136,7 @@ const useSettings = (settingsProps = {}) => {
       pages: pagesFromQueryReturn,
       dynamic,
     };
-  }, [allowGlobalEdit, kintIntl, labelOverrides, passedIntlKey, passedIntlNS, sectionRoute]);
+  }, [allowGlobalEdit, kintIntl, labelOverrides, passedIntlKey, passedIntlNS, render, sectionRoute]);
 
   useEffect(() => {
     // Handle loading

package/es/lib/EditableSettingsList/EditableSettingsListFieldArray.js

@@ -1,57 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-var _react = _interopRequireDefault(require("react"));
-var _propTypes = _interopRequireDefault(require("prop-types"));
-var _reactFinalForm = require("react-final-form");
-var _SettingField = require("./SettingField");
-var _jsxRuntime = require("react/jsx-runtime");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const EditableSettingsListFieldArray = _ref => {
-  let {
-    allowEdit = true,
-    data,
-    fields,
-    intlKey: passedIntlKey,
-    intlNS: passedIntlNS,
-    labelOverrides = {},
-    onSave
-  } = _ref;
-  const handleSave = index => {
-    const setting = fields.value[index];
-    return onSave(setting);
-  };
-  return fields.map((setting, i) => {
-    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactFinalForm.Field, {
-      allowEdit: allowEdit,
-      component: _SettingField.SettingField,
-      "data-testid": `editableSettingsListFieldArray[${i}]`,
-      intlKey: passedIntlKey,
-      intlNS: passedIntlNS,
-      labelOverrides: labelOverrides,
-      name: setting,
-      onSave: () => handleSave(i),
-      settingData: {
-        currentSetting: fields.value[i],
-        ...data
-      }
-    }, setting);
-  });
-};
-EditableSettingsListFieldArray.propTypes = {
-  allowEdit: _propTypes.default.bool,
-  fields: _propTypes.default.object,
-  intlKey: _propTypes.default.string,
-  intlNS: _propTypes.default.string,
-  labelOverrides: _propTypes.default.object,
-  onSave: _propTypes.default.func,
-  data: _propTypes.default.shape({
-    refdatavalues: _propTypes.default.arrayOf(_propTypes.default.object)
-  }),
-  mutators: _propTypes.default.object,
-  initialValues: _propTypes.default.object
-};
-var _default = exports.default = EditableSettingsListFieldArray;

package/src/lib/EditableSettingsList/EditableSettingsListFieldArray.js

@@ -1,58 +0,0 @@
-import React from 'react';
-import PropTypes from 'prop-types';
-import { Field } from 'react-final-form';
-
-import { SettingField } from './SettingField';
-
-const EditableSettingsListFieldArray = ({
-  allowEdit = true,
-  data,
-  fields,
-  intlKey: passedIntlKey,
-  intlNS: passedIntlNS,
-  labelOverrides = {},
-  onSave
-}) => {
-  const handleSave = (index) => {
-    const setting = fields.value[index];
-    return onSave(setting);
-  };
-
-  return (
-    fields.map((setting, i) => {
-      return (
-        <Field
-          key={setting}
-          allowEdit={allowEdit}
-          component={SettingField}
-          data-testid={`editableSettingsListFieldArray[${i}]`}
-          intlKey={passedIntlKey}
-          intlNS={passedIntlNS}
-          labelOverrides={labelOverrides}
-          name={setting}
-          onSave={() => handleSave(i)}
-          settingData={{
-            currentSetting: fields.value[i],
-            ...data
-          }}
-        />
-      );
-    })
-  );
-};
-
-EditableSettingsListFieldArray.propTypes = {
-  allowEdit: PropTypes.bool,
-  fields: PropTypes.object,
-  intlKey: PropTypes.string,
-  intlNS: PropTypes.string,
-  labelOverrides: PropTypes.object,
-  onSave: PropTypes.func,
-  data: PropTypes.shape({
-    refdatavalues: PropTypes.arrayOf(PropTypes.object)
-  }),
-  mutators: PropTypes.object,
-  initialValues: PropTypes.object
-};
-
-export default EditableSettingsListFieldArray;