@beinformed/ui 1.65.17 → 1.65.19

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [1.65.19](https://git.beinformed.com/public/nl.beinformed.bi.layout.lib.ui/compare/v1.65.18...v1.65.19) (2026-01-16)
+
+
+### Bug Fixes
+
+* **connector:** handle modularui connector with useModularUIBasic hook ([b44b1c4](https://git.beinformed.com/public/nl.beinformed.bi.layout.lib.ui/commit/b44b1c4bc5230d983331b28094e1811b9ba04ba4))
+* **hooks:** add `useModelSelectors` and deprecate legacy connector methods in favor of equivalent hooks ([db59fd9](https://git.beinformed.com/public/nl.beinformed.bi.layout.lib.ui/commit/db59fd9087fe6dffafcdf429d6e2a0ce40aaf57b))
+* **hooks:** enhance URL normalization, add query handling with `useRef`, and improve reload logic in modularui hooks ([f042c03](https://git.beinformed.com/public/nl.beinformed.bi.layout.lib.ui/commit/f042c0347c4f0609c232dccef73dbb844a8be01c))
+
+## [1.65.18](https://git.beinformed.com/public/nl.beinformed.bi.layout.lib.ui/compare/v1.65.17...v1.65.18) (2026-01-15)
+
+
+### Bug Fixes
+
+* **hooks:** update `removeOnUnmount` default to `true` and clean up unused option in `useModularUIBasic` ([81c6662](https://git.beinformed.com/public/nl.beinformed.bi.layout.lib.ui/commit/81c66624e019f1a14611759ec281ec046a1dea5e))
+
 ## [1.65.17](https://git.beinformed.com/public/nl.beinformed.bi.layout.lib.ui/compare/v1.65.15...v1.65.17) (2026-01-15)
 
 

package/esm/hooks/index.js

@@ -8,6 +8,7 @@ export * from "./useLookup";
 export * from "./useModal";
 export * from "./useModelCatalog";
 export * from "./useModels";
+export * from "./useModelSelectors";
 export * from "./useModularUI";
 export * from "./useModularUIBasic";
 export * from "./useModularUIModel";

package/esm/hooks/index.js.flow

@@ -9,6 +9,7 @@ export * from "./useLookup";
 export * from "./useModal";
 export * from "./useModelCatalog";
 export * from "./useModels";
+export * from "./useModelSelectors";
 export * from "./useModularUI";
 export * from "./useModularUIBasic";
 export * from "./useModularUIModel";

package/esm/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/hooks/index.js"],"sourcesContent":["// @flow\nexport * from \"./useAllFormsOnModel\";\nexport * from \"./useAuthentication\";\nexport * from \"./useContent\";\nexport * from \"./useForm\";\nexport * from \"./useI18n\";\nexport * from \"./useList\";\nexport * from \"./useLookup\";\nexport * from \"./useModal\";\nexport * from \"./useModelCatalog\";\nexport * from \"./useModels\";\nexport * from \"./useModularUI\";\nexport * from \"./useModularUIBasic\";\nexport * from \"./useModularUIModel\";\nexport * from \"./useModularUIRequest\";\nexport * from \"./useNotification\";\nexport * from \"./usePanel\";\nexport * from \"./usePreference\";\nexport * from \"./useProgressIndicator\";\nexport * from \"./useRouter\";\nexport * from \"./useSearch\";\n"],"mappings":"AACA,cAAc,sBAAsB;AACpC,cAAc,qBAAqB;AACnC,cAAc,cAAc;AAC5B,cAAc,WAAW;AACzB,cAAc,WAAW;AACzB,cAAc,WAAW;AACzB,cAAc,aAAa;AAC3B,cAAc,YAAY;AAC1B,cAAc,mBAAmB;AACjC,cAAc,aAAa;AAC3B,cAAc,gBAAgB;AAC9B,cAAc,qBAAqB;AACnC,cAAc,qBAAqB;AACnC,cAAc,uBAAuB;AACrC,cAAc,mBAAmB;AACjC,cAAc,YAAY;AAC1B,cAAc,iBAAiB;AAC/B,cAAc,wBAAwB;AACtC,cAAc,aAAa;AAC3B,cAAc,aAAa","ignoreList":[]}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/hooks/index.js"],"sourcesContent":["// @flow\nexport * from \"./useAllFormsOnModel\";\nexport * from \"./useAuthentication\";\nexport * from \"./useContent\";\nexport * from \"./useForm\";\nexport * from \"./useI18n\";\nexport * from \"./useList\";\nexport * from \"./useLookup\";\nexport * from \"./useModal\";\nexport * from \"./useModelCatalog\";\nexport * from \"./useModels\";\nexport * from \"./useModelSelectors\";\nexport * from \"./useModularUI\";\nexport * from \"./useModularUIBasic\";\nexport * from \"./useModularUIModel\";\nexport * from \"./useModularUIRequest\";\nexport * from \"./useNotification\";\nexport * from \"./usePanel\";\nexport * from \"./usePreference\";\nexport * from \"./useProgressIndicator\";\nexport * from \"./useRouter\";\nexport * from \"./useSearch\";\n"],"mappings":"AACA,cAAc,sBAAsB;AACpC,cAAc,qBAAqB;AACnC,cAAc,cAAc;AAC5B,cAAc,WAAW;AACzB,cAAc,WAAW;AACzB,cAAc,WAAW;AACzB,cAAc,aAAa;AAC3B,cAAc,YAAY;AAC1B,cAAc,mBAAmB;AACjC,cAAc,aAAa;AAC3B,cAAc,qBAAqB;AACnC,cAAc,gBAAgB;AAC9B,cAAc,qBAAqB;AACnC,cAAc,qBAAqB;AACnC,cAAc,uBAAuB;AACrC,cAAc,mBAAmB;AACjC,cAAc,YAAY;AAC1B,cAAc,iBAAiB;AAC/B,cAAc,wBAAwB;AACtC,cAAc,aAAa;AAC3B,cAAc,aAAa","ignoreList":[]}

package/esm/hooks/useModelSelectors.js

@@ -0,0 +1,73 @@
+import { useSelector } from "react-redux";
+import { getAllModelsByInstance, getFirstModelByInstance, getActiveModelByInstance, modelByHref, keyByHref, allKeysByHref, getActiveModels, getAllFinishedModels } from "../redux/_modularui/ModularUISelectors";
+import Href from "../models/href/Href";
+
+/**
+ * Returns all models in the store that are instances of the provided class
+ * and match the current application locale.
+ */
+export const useAllModelsByInstance = instance => {
+  return useSelector(state => getAllModelsByInstance(state, instance));
+};
+
+/**
+ * Returns the first model found in the store that is an instance of the
+ * provided class and matches the current locale.
+ */
+export const useFirstModelByInstance = instance => {
+  return useSelector(state => getFirstModelByInstance(state, instance));
+};
+
+/**
+ * Returns the model instance that is currently "active" based on the URL path.
+ * It checks if the current router location starts with the model's selfhref path.
+ */
+export const useActiveModelByInstance = instance => {
+  return useSelector(state => getActiveModelByInstance(state, instance));
+};
+
+/**
+ * Retrieves a specific model from the store based on its unique Href.
+ * @param {Href | string} href - The Href object or string path of the model.
+ * @returns {ModularUIModel | null} The model matching the href or null.
+ */
+export const useModelByHref = href => {
+  return useSelector(state => modelByHref(state, href));
+};
+
+/**
+ * Returns the unique store key (identifier) for a model associated with a specific Href.
+ * @param {Href | string} href - The Href object or string path.
+ * @returns {string | null | void} The internal key of the model.
+ */
+export const useKeyByHref = href => {
+  return useSelector(state => keyByHref(state, href));
+};
+
+/**
+ * Returns all internal keys found in the store for a specific Href.
+ * Useful if multiple versions/entries exist for the same path.
+ * @param {Href | string} href - The Href object or string path.
+ * @returns {Array<string>} An array of keys.
+ */
+export const useAllKeysByHref = href => {
+  return useSelector(state => allKeysByHref(state, href));
+};
+
+/**
+ * Returns a list of simplified model info (key, href, label, type) for all
+ * models currently active in the navigation context (breadcrumbs).
+ * @returns {Array<{key: string, href: Href, label: string, type: string}>}
+ */
+export const useActiveModels = () => {
+  return useSelector(getActiveModels);
+};
+
+/**
+ * Returns all models in the store that have a status of MODULARUI_STATUS.FINISHED.
+ * @returns {Array<ModularUIModel>} An array of fully loaded models.
+ */
+export const useAllFinishedModels = () => {
+  return useSelector(getAllFinishedModels);
+};
+//# sourceMappingURL=useModelSelectors.js.map

package/esm/hooks/useModelSelectors.js.flow

@@ -0,0 +1,98 @@
+// @flow
+import { useSelector } from "react-redux";
+
+import {
+  getAllModelsByInstance,
+  getFirstModelByInstance,
+  getActiveModelByInstance,
+  modelByHref,
+  keyByHref,
+  allKeysByHref,
+  getActiveModels,
+  getAllFinishedModels,
+} from "../redux/_modularui/ModularUISelectors";
+import type { ModularUIModel } from "../models/types";
+import type { ReduxState } from "../redux/types";
+import Href from "../models/href/Href";
+
+/**
+ * Returns all models in the store that are instances of the provided class
+ * and match the current application locale.
+ */
+export const useAllModelsByInstance = <T>(
+  instance: Class<T>,
+): Array<ModularUIModel> => {
+  return useSelector((state: ReduxState) =>
+    getAllModelsByInstance(state, instance),
+  );
+};
+
+/**
+ * Returns the first model found in the store that is an instance of the
+ * provided class and matches the current locale.
+ */
+export const useFirstModelByInstance = <T>(instance: Class<T>): T | null => {
+  return useSelector((state: ReduxState) =>
+    getFirstModelByInstance(state, instance),
+  );
+};
+
+/**
+ * Returns the model instance that is currently "active" based on the URL path.
+ * It checks if the current router location starts with the model's selfhref path.
+ */
+export const useActiveModelByInstance = <T>(instance: Class<T>): T | null => {
+  return useSelector((state: ReduxState) =>
+    getActiveModelByInstance(state, instance),
+  );
+};
+
+/**
+ * Retrieves a specific model from the store based on its unique Href.
+ * @param {Href | string} href - The Href object or string path of the model.
+ * @returns {ModularUIModel | null} The model matching the href or null.
+ */
+export const useModelByHref = (href: Href | string): null | ModularUIModel => {
+  return useSelector((state: ReduxState) => modelByHref(state, href));
+};
+
+/**
+ * Returns the unique store key (identifier) for a model associated with a specific Href.
+ * @param {Href | string} href - The Href object or string path.
+ * @returns {string | null | void} The internal key of the model.
+ */
+export const useKeyByHref = (href: Href | string): ?string => {
+  return useSelector((state: ReduxState) => keyByHref(state, href));
+};
+
+/**
+ * Returns all internal keys found in the store for a specific Href.
+ * Useful if multiple versions/entries exist for the same path.
+ * @param {Href | string} href - The Href object or string path.
+ * @returns {Array<string>} An array of keys.
+ */
+export const useAllKeysByHref = (href: Href | string): Array<string> => {
+  return useSelector((state: ReduxState) => allKeysByHref(state, href));
+};
+
+/**
+ * Returns a list of simplified model info (key, href, label, type) for all
+ * models currently active in the navigation context (breadcrumbs).
+ * @returns {Array<{key: string, href: Href, label: string, type: string}>}
+ */
+export const useActiveModels = (): Array<{
+  key: string,
+  href: Href,
+  label: string,
+  type: string,
+}> => {
+  return useSelector(getActiveModels);
+};
+
+/**
+ * Returns all models in the store that have a status of MODULARUI_STATUS.FINISHED.
+ * @returns {Array<ModularUIModel>} An array of fully loaded models.
+ */
+export const useAllFinishedModels = (): Array<ModularUIModel> => {
+  return useSelector(getAllFinishedModels);
+};

package/esm/hooks/useModelSelectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useModelSelectors.js","names":["useSelector","getAllModelsByInstance","getFirstModelByInstance","getActiveModelByInstance","modelByHref","keyByHref","allKeysByHref","getActiveModels","getAllFinishedModels","Href","useAllModelsByInstance","instance","state","useFirstModelByInstance","useActiveModelByInstance","useModelByHref","href","useKeyByHref","useAllKeysByHref","useActiveModels","useAllFinishedModels"],"sources":["../../src/hooks/useModelSelectors.js"],"sourcesContent":["// @flow\nimport { useSelector } from \"react-redux\";\n\nimport {\n  getAllModelsByInstance,\n  getFirstModelByInstance,\n  getActiveModelByInstance,\n  modelByHref,\n  keyByHref,\n  allKeysByHref,\n  getActiveModels,\n  getAllFinishedModels,\n} from \"../redux/_modularui/ModularUISelectors\";\nimport type { ModularUIModel } from \"../models/types\";\nimport type { ReduxState } from \"../redux/types\";\nimport Href from \"../models/href/Href\";\n\n/**\n * Returns all models in the store that are instances of the provided class\n * and match the current application locale.\n */\nexport const useAllModelsByInstance = <T>(\n  instance: Class<T>,\n): Array<ModularUIModel> => {\n  return useSelector((state: ReduxState) =>\n    getAllModelsByInstance(state, instance),\n  );\n};\n\n/**\n * Returns the first model found in the store that is an instance of the\n * provided class and matches the current locale.\n */\nexport const useFirstModelByInstance = <T>(instance: Class<T>): T | null => {\n  return useSelector((state: ReduxState) =>\n    getFirstModelByInstance(state, instance),\n  );\n};\n\n/**\n * Returns the model instance that is currently \"active\" based on the URL path.\n * It checks if the current router location starts with the model's selfhref path.\n */\nexport const useActiveModelByInstance = <T>(instance: Class<T>): T | null => {\n  return useSelector((state: ReduxState) =>\n    getActiveModelByInstance(state, instance),\n  );\n};\n\n/**\n * Retrieves a specific model from the store based on its unique Href.\n * @param {Href | string} href - The Href object or string path of the model.\n * @returns {ModularUIModel | null} The model matching the href or null.\n */\nexport const useModelByHref = (href: Href | string): null | ModularUIModel => {\n  return useSelector((state: ReduxState) => modelByHref(state, href));\n};\n\n/**\n * Returns the unique store key (identifier) for a model associated with a specific Href.\n * @param {Href | string} href - The Href object or string path.\n * @returns {string | null | void} The internal key of the model.\n */\nexport const useKeyByHref = (href: Href | string): ?string => {\n  return useSelector((state: ReduxState) => keyByHref(state, href));\n};\n\n/**\n * Returns all internal keys found in the store for a specific Href.\n * Useful if multiple versions/entries exist for the same path.\n * @param {Href | string} href - The Href object or string path.\n * @returns {Array<string>} An array of keys.\n */\nexport const useAllKeysByHref = (href: Href | string): Array<string> => {\n  return useSelector((state: ReduxState) => allKeysByHref(state, href));\n};\n\n/**\n * Returns a list of simplified model info (key, href, label, type) for all\n * models currently active in the navigation context (breadcrumbs).\n * @returns {Array<{key: string, href: Href, label: string, type: string}>}\n */\nexport const useActiveModels = (): Array<{\n  key: string,\n  href: Href,\n  label: string,\n  type: string,\n}> => {\n  return useSelector(getActiveModels);\n};\n\n/**\n * Returns all models in the store that have a status of MODULARUI_STATUS.FINISHED.\n * @returns {Array<ModularUIModel>} An array of fully loaded models.\n */\nexport const useAllFinishedModels = (): Array<ModularUIModel> => {\n  return useSelector(getAllFinishedModels);\n};\n"],"mappings":"AACA,SAASA,WAAW,QAAQ,aAAa;AAEzC,SACEC,sBAAsB,EACtBC,uBAAuB,EACvBC,wBAAwB,EACxBC,WAAW,EACXC,SAAS,EACTC,aAAa,EACbC,eAAe,EACfC,oBAAoB,QACf,wCAAwC;AAG/C,OAAOC,IAAI,MAAM,qBAAqB;;AAEtC;AACA;AACA;AACA;AACA,OAAO,MAAMC,sBAAsB,GACjCC,QAAkB,IACQ;EAC1B,OAAOX,WAAW,CAAEY,KAAiB,IACnCX,sBAAsB,CAACW,KAAK,EAAED,QAAQ,CACxC,CAAC;AACH,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAME,uBAAuB,GAAOF,QAAkB,IAAe;EAC1E,OAAOX,WAAW,CAAEY,KAAiB,IACnCV,uBAAuB,CAACU,KAAK,EAAED,QAAQ,CACzC,CAAC;AACH,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAMG,wBAAwB,GAAOH,QAAkB,IAAe;EAC3E,OAAOX,WAAW,CAAEY,KAAiB,IACnCT,wBAAwB,CAACS,KAAK,EAAED,QAAQ,CAC1C,CAAC;AACH,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMI,cAAc,GAAIC,IAAmB,IAA4B;EAC5E,OAAOhB,WAAW,CAAEY,KAAiB,IAAKR,WAAW,CAACQ,KAAK,EAAEI,IAAI,CAAC,CAAC;AACrE,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,YAAY,GAAID,IAAmB,IAAc;EAC5D,OAAOhB,WAAW,CAAEY,KAAiB,IAAKP,SAAS,CAACO,KAAK,EAAEI,IAAI,CAAC,CAAC;AACnE,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,gBAAgB,GAAIF,IAAmB,IAAoB;EACtE,OAAOhB,WAAW,CAAEY,KAAiB,IAAKN,aAAa,CAACM,KAAK,EAAEI,IAAI,CAAC,CAAC;AACvE,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,eAAe,GAAGA,CAAA,KAKzB;EACJ,OAAOnB,WAAW,CAACO,eAAe,CAAC;AACrC,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAMa,oBAAoB,GAAGA,CAAA,KAA6B;EAC/D,OAAOpB,WAAW,CAACQ,oBAAoB,CAAC;AAC1C,CAAC","ignoreList":[]}

package/esm/hooks/useModularUI.js

@@ -1,4 +1,4 @@
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { useDispatch, useSelector } from "react-redux";
 import { useLocation } from "react-router";
 import { HTTP_METHODS, MODULARUI_STATUS } from "../constants";
@@ -7,17 +7,40 @@ import useDeepCompareEffect from "./useDeepCompareEffect";
 import { useModularUIKey } from "./useModularUIKey";
 import Href from "../models/href/Href";
 /**
- * Core hook to retrieve information for a Be Informed modular ui resource
+ * A custom hook to fetch and manage Be Informed modular UI resources.
+ * It handles automatic data fetching based on URL/query changes, manages Redux state
+ * synchronization, and provides cleanup logic when components unmount.
+ *
+ * @param {string} modelKey - A unique identifier for the type of model being fetched.
+ * @param {string | Href} url - The endpoint URL or Href instance to fetch data from.
+ * @param {RequestModularUIOptions} options - Configuration for the request (method, headers, etc.).
+ * @returns {ModelEntry} The model data retrieved from the Redux store.
  */
 export const useModularUI = (modelKey, url, options = {}) => {
   const dispatch = useDispatch();
-  const href = useMemo(() => url?.toString() || "", [url]);
-  const key = useModularUIKey(modelKey, href);
+
+  // Normalize the URL input into a Href instance to safely access query params and paths
+  const hrefInstance = useMemo(() => new Href(url), [url]);
+  const requestUrl = useMemo(() => hrefInstance.toString(), [hrefInstance]);
+  const currentQueryString = hrefInstance.querystring;
+
+  // Persistence ref to detect if query parameters have changed between renders
+  const prevQueryRef = useRef(currentQueryString);
+
+  // Generate a unique key for the Redux store based on the model type and the full URL
+  const key = useModularUIKey(modelKey, requestUrl);
+
+  // Select the specific piece of state corresponding to this modular UI component
   const model = useSelector(state => state.modularui[key]);
+
+  /**
+   * Memoize request options to prevent unnecessary re-renders.
+   * Merges default settings (GET method, auto-cleanup) with user-provided options.
+   */
   const requestOptions = useMemo(() => {
     const merged = {
       method: HTTP_METHODS.GET,
-      removeOnUnmount: false,
+      removeOnUnmount: true,
       ...options
     };
     if (url instanceof Href) {
@@ -28,14 +51,34 @@ export const useModularUI = (modelKey, url, options = {}) => {
   }, [options, url]);
   const location = useLocation();
   const redirectLocation = location.state?.redirectLocation;
-  const shouldLoad = model == null || model.status === MODULARUI_STATUS.ERROR || (redirectLocation instanceof Href ? redirectLocation?.equals(href) : false) || requestOptions.isReload === true;
 
-  // dispatch loadModularUI
+  /**
+   * Determines if a network request should be initiated.
+   * Logic includes:
+   * - Model doesn't exist yet (Initial load)
+   * - Previous request resulted in an error (Retry)
+   * - The query parameters changed (Filtering/Paging)
+   * - A redirect was triggered specifically for this URL
+   * - Manual 'isReload' flag is passed in options
+   */
+  const shouldLoad = model == null || model.status === MODULARUI_STATUS.ERROR || prevQueryRef.current !== currentQueryString || (redirectLocation instanceof Href ? redirectLocation.equals(requestUrl) : false) || requestOptions.isReload === true;
+
+  // Synchronize the ref after the render cycle determines if we should load
+  useEffect(() => {
+    prevQueryRef.current = currentQueryString;
+  }, [currentQueryString]);
+
+  // Execute the load action. Deep compare is used on options to prevent
+  // infinite loops caused by passing inline object literals.
   useDeepCompareEffect(() => {
-    if (href !== "" && shouldLoad) {
-      dispatch(loadModularUI(key, href, requestOptions));
+    if (requestUrl !== "" && shouldLoad) {
+      dispatch(loadModularUI(key, requestUrl, requestOptions));
     }
-  }, [key, href, requestOptions, shouldLoad]);
+  }, [key, requestUrl, requestOptions, shouldLoad]);
+
+  // Cleanup Effect:
+  // If 'removeOnUnmount' is true, this removes the model data from the Redux store
+  // when the component using this hook is destroyed.
   useEffect(() => {
     if (requestOptions.removeOnUnmount) {
       return () => {

package/esm/hooks/useModularUI.js.flow

@@ -1,5 +1,5 @@
 // @flow
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { useDispatch, useSelector } from "react-redux";
 import { useLocation } from "react-router";
 
@@ -13,10 +13,19 @@ import useDeepCompareEffect from "./useDeepCompareEffect";
 import { useModularUIKey } from "./useModularUIKey";
 
 import Href from "../models/href/Href";
+
 import type { RequestModularUIOptions } from "../utils";
+import type { ModelEntry } from "../redux";
 
 /**
- * Core hook to retrieve information for a Be Informed modular ui resource
+ * A custom hook to fetch and manage Be Informed modular UI resources.
+ * It handles automatic data fetching based on URL/query changes, manages Redux state
+ * synchronization, and provides cleanup logic when components unmount.
+ *
+ * @param {string} modelKey - A unique identifier for the type of model being fetched.
+ * @param {string | Href} url - The endpoint URL or Href instance to fetch data from.
+ * @param {RequestModularUIOptions} options - Configuration for the request (method, headers, etc.).
+ * @returns {ModelEntry} The model data retrieved from the Redux store.
  */
 export const useModularUI = (
   modelKey: string,
@@ -25,15 +34,28 @@ export const useModularUI = (
 ): any => {
   const dispatch = useDispatch();
 
-  const href = useMemo(() => url?.toString() || "", [url]);
-  const key = useModularUIKey(modelKey, href);
+  // Normalize the URL input into a Href instance to safely access query params and paths
+  const hrefInstance = useMemo(() => new Href(url), [url]);
+  const requestUrl = useMemo(() => hrefInstance.toString(), [hrefInstance]);
+  const currentQueryString = hrefInstance.querystring;
+
+  // Persistence ref to detect if query parameters have changed between renders
+  const prevQueryRef = useRef(currentQueryString);
+
+  // Generate a unique key for the Redux store based on the model type and the full URL
+  const key = useModularUIKey(modelKey, requestUrl);
 
+  // Select the specific piece of state corresponding to this modular UI component
   const model = useSelector((state) => state.modularui[key]);
 
+  /**
+   * Memoize request options to prevent unnecessary re-renders.
+   * Merges default settings (GET method, auto-cleanup) with user-provided options.
+   */
   const requestOptions = useMemo(() => {
     const merged = {
       method: HTTP_METHODS.GET,
-      removeOnUnmount: false,
+      removeOnUnmount: true,
       ...options,
     };
 
@@ -47,21 +69,40 @@ export const useModularUI = (
   const location = useLocation();
   const redirectLocation = location.state?.redirectLocation;
 
+  /**
+   * Determines if a network request should be initiated.
+   * Logic includes:
+   * - Model doesn't exist yet (Initial load)
+   * - Previous request resulted in an error (Retry)
+   * - The query parameters changed (Filtering/Paging)
+   * - A redirect was triggered specifically for this URL
+   * - Manual 'isReload' flag is passed in options
+   */
   const shouldLoad =
     model == null ||
     model.status === MODULARUI_STATUS.ERROR ||
+    prevQueryRef.current !== currentQueryString ||
     (redirectLocation instanceof Href
-      ? redirectLocation?.equals(href)
+      ? redirectLocation.equals(requestUrl)
       : false) ||
     requestOptions.isReload === true;
 
-  // dispatch loadModularUI
+  // Synchronize the ref after the render cycle determines if we should load
+  useEffect(() => {
+    prevQueryRef.current = currentQueryString;
+  }, [currentQueryString]);
+
+  // Execute the load action. Deep compare is used on options to prevent
+  // infinite loops caused by passing inline object literals.
   useDeepCompareEffect(() => {
-    if (href !== "" && shouldLoad) {
-      dispatch(loadModularUI(key, href, requestOptions));
+    if (requestUrl !== "" && shouldLoad) {
+      dispatch(loadModularUI(key, requestUrl, requestOptions));
     }
-  }, [key, href, requestOptions, shouldLoad]);
+  }, [key, requestUrl, requestOptions, shouldLoad]);
 
+  // Cleanup Effect:
+  // If 'removeOnUnmount' is true, this removes the model data from the Redux store
+  // when the component using this hook is destroyed.
   useEffect(() => {
     if (requestOptions.removeOnUnmount) {
       return () => {

package/esm/hooks/useModularUI.js.map

@@ -1 +1 @@
-{"version":3,"file":"useModularUI.js","names":["useEffect","useMemo","useDispatch","useSelector","useLocation","HTTP_METHODS","MODULARUI_STATUS","loadModularUI","removeModelByKey","useDeepCompareEffect","useModularUIKey","Href","useModularUI","modelKey","url","options","dispatch","href","toString","key","model","state","modularui","requestOptions","merged","method","GET","removeOnUnmount","origin","contextPath","location","redirectLocation","shouldLoad","status","ERROR","equals","isReload"],"sources":["../../src/hooks/useModularUI.js"],"sourcesContent":["// @flow\nimport { useEffect, useMemo } from \"react\";\nimport { useDispatch, useSelector } from \"react-redux\";\nimport { useLocation } from \"react-router\";\n\nimport { HTTP_METHODS, MODULARUI_STATUS } from \"../constants\";\nimport {\n  loadModularUI,\n  removeModelByKey,\n} from \"../redux/_modularui/ModularUIActions\";\n\nimport useDeepCompareEffect from \"./useDeepCompareEffect\";\nimport { useModularUIKey } from \"./useModularUIKey\";\n\nimport Href from \"../models/href/Href\";\nimport type { RequestModularUIOptions } from \"../utils\";\n\n/**\n * Core hook to retrieve information for a Be Informed modular ui resource\n */\nexport const useModularUI = (\n  modelKey: string,\n  url: string | Href,\n  options: RequestModularUIOptions = (({}: any): RequestModularUIOptions),\n): any => {\n  const dispatch = useDispatch();\n\n  const href = useMemo(() => url?.toString() || \"\", [url]);\n  const key = useModularUIKey(modelKey, href);\n\n  const model = useSelector((state) => state.modularui[key]);\n\n  const requestOptions = useMemo(() => {\n    const merged = {\n      method: HTTP_METHODS.GET,\n      removeOnUnmount: false,\n      ...options,\n    };\n\n    if (url instanceof Href) {\n      merged.origin = merged.origin ?? url.origin;\n      merged.contextPath = merged.contextPath ?? url.contextPath;\n    }\n    return merged;\n  }, [options, url]);\n\n  const location = useLocation();\n  const redirectLocation = location.state?.redirectLocation;\n\n  const shouldLoad =\n    model == null ||\n    model.status === MODULARUI_STATUS.ERROR ||\n    (redirectLocation instanceof Href\n      ? redirectLocation?.equals(href)\n      : false) ||\n    requestOptions.isReload === true;\n\n  // dispatch loadModularUI\n  useDeepCompareEffect(() => {\n    if (href !== \"\" && shouldLoad) {\n      dispatch(loadModularUI(key, href, requestOptions));\n    }\n  }, [key, href, requestOptions, shouldLoad]);\n\n  useEffect(() => {\n    if (requestOptions.removeOnUnmount) {\n      return () => {\n        dispatch(removeModelByKey(key));\n      };\n    }\n  }, [dispatch, key, requestOptions.removeOnUnmount]);\n\n  return model;\n};\n"],"mappings":"AACA,SAASA,SAAS,EAAEC,OAAO,QAAQ,OAAO;AAC1C,SAASC,WAAW,EAAEC,WAAW,QAAQ,aAAa;AACtD,SAASC,WAAW,QAAQ,cAAc;AAE1C,SAASC,YAAY,EAAEC,gBAAgB,QAAQ,cAAc;AAC7D,SACEC,aAAa,EACbC,gBAAgB,QACX,sCAAsC;AAE7C,OAAOC,oBAAoB,MAAM,wBAAwB;AACzD,SAASC,eAAe,QAAQ,mBAAmB;AAEnD,OAAOC,IAAI,MAAM,qBAAqB;AAGtC;AACA;AACA;AACA,OAAO,MAAMC,YAAY,GAAGA,CAC1BC,QAAgB,EAChBC,GAAkB,EAClBC,OAAgC,GAAK,CAAC,CAAiC,KAC/D;EACR,MAAMC,QAAQ,GAAGd,WAAW,CAAC,CAAC;EAE9B,MAAMe,IAAI,GAAGhB,OAAO,CAAC,MAAMa,GAAG,EAAEI,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAACJ,GAAG,CAAC,CAAC;EACxD,MAAMK,GAAG,GAAGT,eAAe,CAACG,QAAQ,EAAEI,IAAI,CAAC;EAE3C,MAAMG,KAAK,GAAGjB,WAAW,CAAEkB,KAAK,IAAKA,KAAK,CAACC,SAAS,CAACH,GAAG,CAAC,CAAC;EAE1D,MAAMI,cAAc,GAAGtB,OAAO,CAAC,MAAM;IACnC,MAAMuB,MAAM,GAAG;MACbC,MAAM,EAAEpB,YAAY,CAACqB,GAAG;MACxBC,eAAe,EAAE,KAAK;MACtB,GAAGZ;IACL,CAAC;IAED,IAAID,GAAG,YAAYH,IAAI,EAAE;MACvBa,MAAM,CAACI,MAAM,GAAGJ,MAAM,CAACI,MAAM,IAAId,GAAG,CAACc,MAAM;MAC3CJ,MAAM,CAACK,WAAW,GAAGL,MAAM,CAACK,WAAW,IAAIf,GAAG,CAACe,WAAW;IAC5D;IACA,OAAOL,MAAM;EACf,CAAC,EAAE,CAACT,OAAO,EAAED,GAAG,CAAC,CAAC;EAElB,MAAMgB,QAAQ,GAAG1B,WAAW,CAAC,CAAC;EAC9B,MAAM2B,gBAAgB,GAAGD,QAAQ,CAACT,KAAK,EAAEU,gBAAgB;EAEzD,MAAMC,UAAU,GACdZ,KAAK,IAAI,IAAI,IACbA,KAAK,CAACa,MAAM,KAAK3B,gBAAgB,CAAC4B,KAAK,KACtCH,gBAAgB,YAAYpB,IAAI,GAC7BoB,gBAAgB,EAAEI,MAAM,CAAClB,IAAI,CAAC,GAC9B,KAAK,CAAC,IACVM,cAAc,CAACa,QAAQ,KAAK,IAAI;;EAElC;EACA3B,oBAAoB,CAAC,MAAM;IACzB,IAAIQ,IAAI,KAAK,EAAE,IAAIe,UAAU,EAAE;MAC7BhB,QAAQ,CAACT,aAAa,CAACY,GAAG,EAAEF,IAAI,EAAEM,cAAc,CAAC,CAAC;IACpD;EACF,CAAC,EAAE,CAACJ,GAAG,EAAEF,IAAI,EAAEM,cAAc,EAAES,UAAU,CAAC,CAAC;EAE3ChC,SAAS,CAAC,MAAM;IACd,IAAIuB,cAAc,CAACI,eAAe,EAAE;MAClC,OAAO,MAAM;QACXX,QAAQ,CAACR,gBAAgB,CAACW,GAAG,CAAC,CAAC;MACjC,CAAC;IACH;EACF,CAAC,EAAE,CAACH,QAAQ,EAAEG,GAAG,EAAEI,cAAc,CAACI,eAAe,CAAC,CAAC;EAEnD,OAAOP,KAAK;AACd,CAAC","ignoreList":[]}
+{"version":3,"file":"useModularUI.js","names":["useEffect","useMemo","useRef","useDispatch","useSelector","useLocation","HTTP_METHODS","MODULARUI_STATUS","loadModularUI","removeModelByKey","useDeepCompareEffect","useModularUIKey","Href","useModularUI","modelKey","url","options","dispatch","hrefInstance","requestUrl","toString","currentQueryString","querystring","prevQueryRef","key","model","state","modularui","requestOptions","merged","method","GET","removeOnUnmount","origin","contextPath","location","redirectLocation","shouldLoad","status","ERROR","current","equals","isReload"],"sources":["../../src/hooks/useModularUI.js"],"sourcesContent":["// @flow\nimport { useEffect, useMemo, useRef } from \"react\";\nimport { useDispatch, useSelector } from \"react-redux\";\nimport { useLocation } from \"react-router\";\n\nimport { HTTP_METHODS, MODULARUI_STATUS } from \"../constants\";\nimport {\n  loadModularUI,\n  removeModelByKey,\n} from \"../redux/_modularui/ModularUIActions\";\n\nimport useDeepCompareEffect from \"./useDeepCompareEffect\";\nimport { useModularUIKey } from \"./useModularUIKey\";\n\nimport Href from \"../models/href/Href\";\n\nimport type { RequestModularUIOptions } from \"../utils\";\nimport type { ModelEntry } from \"../redux\";\n\n/**\n * A custom hook to fetch and manage Be Informed modular UI resources.\n * It handles automatic data fetching based on URL/query changes, manages Redux state\n * synchronization, and provides cleanup logic when components unmount.\n *\n * @param {string} modelKey - A unique identifier for the type of model being fetched.\n * @param {string | Href} url - The endpoint URL or Href instance to fetch data from.\n * @param {RequestModularUIOptions} options - Configuration for the request (method, headers, etc.).\n * @returns {ModelEntry} The model data retrieved from the Redux store.\n */\nexport const useModularUI = (\n  modelKey: string,\n  url: string | Href,\n  options: RequestModularUIOptions = (({}: any): RequestModularUIOptions),\n): any => {\n  const dispatch = useDispatch();\n\n  // Normalize the URL input into a Href instance to safely access query params and paths\n  const hrefInstance = useMemo(() => new Href(url), [url]);\n  const requestUrl = useMemo(() => hrefInstance.toString(), [hrefInstance]);\n  const currentQueryString = hrefInstance.querystring;\n\n  // Persistence ref to detect if query parameters have changed between renders\n  const prevQueryRef = useRef(currentQueryString);\n\n  // Generate a unique key for the Redux store based on the model type and the full URL\n  const key = useModularUIKey(modelKey, requestUrl);\n\n  // Select the specific piece of state corresponding to this modular UI component\n  const model = useSelector((state) => state.modularui[key]);\n\n  /**\n   * Memoize request options to prevent unnecessary re-renders.\n   * Merges default settings (GET method, auto-cleanup) with user-provided options.\n   */\n  const requestOptions = useMemo(() => {\n    const merged = {\n      method: HTTP_METHODS.GET,\n      removeOnUnmount: true,\n      ...options,\n    };\n\n    if (url instanceof Href) {\n      merged.origin = merged.origin ?? url.origin;\n      merged.contextPath = merged.contextPath ?? url.contextPath;\n    }\n    return merged;\n  }, [options, url]);\n\n  const location = useLocation();\n  const redirectLocation = location.state?.redirectLocation;\n\n  /**\n   * Determines if a network request should be initiated.\n   * Logic includes:\n   * - Model doesn't exist yet (Initial load)\n   * - Previous request resulted in an error (Retry)\n   * - The query parameters changed (Filtering/Paging)\n   * - A redirect was triggered specifically for this URL\n   * - Manual 'isReload' flag is passed in options\n   */\n  const shouldLoad =\n    model == null ||\n    model.status === MODULARUI_STATUS.ERROR ||\n    prevQueryRef.current !== currentQueryString ||\n    (redirectLocation instanceof Href\n      ? redirectLocation.equals(requestUrl)\n      : false) ||\n    requestOptions.isReload === true;\n\n  // Synchronize the ref after the render cycle determines if we should load\n  useEffect(() => {\n    prevQueryRef.current = currentQueryString;\n  }, [currentQueryString]);\n\n  // Execute the load action. Deep compare is used on options to prevent\n  // infinite loops caused by passing inline object literals.\n  useDeepCompareEffect(() => {\n    if (requestUrl !== \"\" && shouldLoad) {\n      dispatch(loadModularUI(key, requestUrl, requestOptions));\n    }\n  }, [key, requestUrl, requestOptions, shouldLoad]);\n\n  // Cleanup Effect:\n  // If 'removeOnUnmount' is true, this removes the model data from the Redux store\n  // when the component using this hook is destroyed.\n  useEffect(() => {\n    if (requestOptions.removeOnUnmount) {\n      return () => {\n        dispatch(removeModelByKey(key));\n      };\n    }\n  }, [dispatch, key, requestOptions.removeOnUnmount]);\n\n  return model;\n};\n"],"mappings":"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","ignoreList":[]}

package/esm/hooks/useModularUIBasic.js

@@ -5,13 +5,29 @@ import { useMemo } from "react";
 import { useModularUI } from "./useModularUI";
 import { HTTP_METHODS, MODULARUI_STATUS } from "../constants";
 import { useModularUIKey } from "./useModularUIKey";
-// Helper to create useModularUI options
+
+/**
+ * Configuration options for low-level modular UI requests.
+ */
+
+/**
+ * Configuration options for the useModularUIBasic hook.
+ * Allows for type enforcement, caching control, and reload behavior.
+ */
+
+/**
+ * Internal helper to transform high-level hook options into a configuration
+ * object compatible with the core useModularUI fetcher.
+ * Logic:
+ * 1. Defaults to GET method.
+ * 2. If 'formdata' is present, it switches to POST and assigns 'data'.
+ * 3. Forces 'isReload' if the useReload check returns true.
+ */
 const createUseModularUIOptions = (options, href, mustReload) => {
   const baseOptions = {
     expectedModels: [],
     method: HTTP_METHODS.GET,
     data: undefined,
-    removeOnUnmount: false,
     ...options,
     isReload: mustReload || options.isReload
   };
@@ -22,7 +38,10 @@ const createUseModularUIOptions = (options, href, mustReload) => {
   return baseOptions;
 };
 
-// Helper to validate the model against expectedModels
+/**
+ * Validates that the returned model type matches one of the expected model strings.
+ * Logs a warning to the console if there is a mismatch (useful for debugging UI-backend contracts).
+ */
 const validateModel = (model, expectedModels) => {
   if (expectedModels.length > 0) {
     const isCorrectModel = _includesInstanceProperty(expectedModels).call(expectedModels, model.type);
@@ -33,15 +52,28 @@ const validateModel = (model, expectedModels) => {
 };
 
 /**
- * useModularUIBasic Hook
+ * A simplified abstraction over useModularUI that includes automatic
+ * model validation and smart-reload logic based on router state.
+ *
+ * @param {string} defaultKey - The default identifier for the model.
+ * @param {string | Href} href - The endpoint to fetch.
+ * @param {UseModularUIBasicOptions} options - Extended configuration options.
  */
 export const useModularUIBasic = (defaultKey, href, options = {}) => {
   const memoizedHref = useMemo(() => href.toString(), [href]);
+
+  // Use the key provided in options if available, otherwise fallback to the default
   const key = options.key ?? defaultKey;
+
+  // Determine if we need to bypass cache based on navigation 'reload' signals
   const mustReload = useReload(key, memoizedHref);
+
+  // Memoize options to prevent useModularUI from re-fetching on every parent render
   const modularUIOptions = useMemo(() => createUseModularUIOptions(options, memoizedHref, mustReload), [options, memoizedHref, mustReload]);
   const modularUI = useModularUI(key, href, modularUIOptions);
   const expectedModels = useMemo(() => options.expectedModels ?? [], [options.expectedModels]);
+
+  // Extract and validate the model from the modularUI wrapper object
   return useMemo(() => {
     if (modularUI?.model) {
       validateModel(modularUI.model, expectedModels);
@@ -52,17 +84,30 @@ export const useModularUIBasic = (defaultKey, href, options = {}) => {
 };
 
 /**
- * Check if the model corresponding to a modular ui service should be reloaded
+ * Determines if a model should be reloaded based on the 'reload' timestamp
+ * found in the React Router location state.
+ * This is used for "force refresh" scenarios where a user navigates to a
+ * page and expects fresh data (e.g., after a form submission elsewhere).
+ * @param {string} modelKey - The model type key.
+ * @param {string} url - The resource URL.
+ * @returns {boolean} True if the store data is stale compared to the reload signal.
  */
 export const useReload = (modelKey, url) => {
   const location = useLocation();
   const key = useModularUIKey(modelKey, url);
+
+  // Access the current entry in the Redux store
   const modelEntry = useSelector(state => state.modularui[key]);
   if (modelEntry) {
     const reload = location.state?.reload || 0;
+
+    // If a reload timestamp exists in the router state
     if (reload > 0) {
       const isFullyLoaded = modelEntry?.status === MODULARUI_STATUS.FINISHED;
       const lastModification = modelEntry?.lastModification ?? 0;
+
+      // Trigger reload only if the model is already finished loading
+      // AND the data we have is older than the requested reload time.
       if (isFullyLoaded && lastModification < reload) {
         return true;
       }