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

package/src/lib/hooks/README.md

@@ -15,85 +15,14 @@ const data = useRefdata({
 ```
 
 ### Props
-Name | Type | Description | default | required
---- | --- | --- | --- | ---
-endpoint | string | The endpoint to fetch refdataValues from | | ✓ |
-desc | string | The refdataCategory (usually of the form `DomainClass.Field`) | | ✕ |
-queryParams | object | A set of queryParameters to hand to react-query's `useQuery` | | ✕ |
-returnQueryObject | bool | A switch to return the entirety of the queryObject from useQuery. If `false`, the data will be destructured, if `true` the return will be the full object returned by react-query's `useQuery` | false | ✕ |
-options | object | An object of the shape SASQ_MAP (See generateKiwtQuery) to pass to the generateKiwtQuery inside. Any passed desc "d" will be passed as a filter `DescKey.${d}`, with DescKey acting as FilterName, assuming `filterKeys: { DescKey: "desc" }` in options, so `desc==${d}` is passed directly to the backend. | `{filterKeys: {DescKey: "desc" }, stats: false, max: 100}` | ✕ |
+| Name              | Type   | Description                                                                                                                                                                                                                                                                                                  | default                                                    | required |
+|-------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|----------|
+| endpoint          | string | The endpoint to fetch refdataValues from                                                                                                                                                                                                                                                                     |                                                            | ✓        |
+| desc              | string | The refdataCategory (usually of the form `DomainClass.Field`)                                                                                                                                                                                                                                                |                                                            | ✕        |
+| queryParams       | object | A set of queryParameters to hand to react-query's `useQuery`                                                                                                                                                                                                                                                 |                                                            | ✕        |
+| returnQueryObject | bool   | A switch to return the entirety of the queryObject from useQuery. If `false`, the data will be destructured, if `true` the return will be the full object returned by react-query's `useQuery`                                                                                                               | false                                                      | ✕        |
+| options           | object | An object of the shape SASQ_MAP (See generateKiwtQuery) to pass to the generateKiwtQuery inside. Any passed desc "d" will be passed as a filter `DescKey.${d}`, with DescKey acting as FilterName, assuming `filterKeys: { DescKey: "desc" }` in options, so `desc==${d}` is passed directly to the backend. | `{filterKeys: {DescKey: "desc" }, stats: false, max: 100}` | ✕        |
 
-## useMutateRefdataValue
-A hook for mutations (Create/Delete/Edit) of refdataValues.
-
-### Basic Usage
-```javascript
-import { useMutateRefdataValue } from '@k-int/stripes-kint-components'
-...
-const { delete } = useMutateRefdataValue({
-  endpoint: 'oa/refdata',
-  id: '1234-abcd-5678',
-});
-```
-
-### Props
-Name | Type | Description | default | required
---- | --- | --- | --- | ---
-afterQueryCalls | object | An object of the form `{delete: func1, put: func2}` where `func1`/`func2` are functions to be called after the `delete`/`put`. This is for ease of use, you can alternatively manually use a `.then()` on the functions returned from this hook. | | ✓ |
-catchQueryCalls | object | An object of the form `{delete: func1, put: func2}` where `func1`/`func2` are functions to be called with a HTTPError object when the `delete`/`put` calls fail. This is for ease of use, you can alternatively manually use a `.catch()` on the functions returned from this hook. | | ✕ |
-endpoint | string | The refdata endpoint | | ✕ |
-id | string | The id of the refdata whose values are to be mutated | | ✕ |
-queryParams | object | An object of the form `{delete: obj1, put: obj2}`, where `obj1`/`obj2` are set of queryParameters to hand to react-query's `useMutation` for the delete/put operations respectively | | ✕ |
-returnQueryObject | object | An object of the form `{delete: bool1, put: bool2}` containing switches to return the entirety of the queryObject from useMutation for `delete` and `put` respectively. If `false`, the mutateAsync function will be destructured, if `true` the return will be the full object returned by react-query's `useMutation` | {put: false, delete: false} | ✕ |
-
-### Example
-```javascript
-...
-const { delete, put } = useMutateRefdataValue({
-  afterQueryCalls: {
-    delete: json => setContentData(json?.values ?? []),
-    put: json => setContentData(json?.values ?? [])
-  },
-  endpoint: 'oa/refdata',
-  id: refdata?.id,
-  queryParams: {
-    delete: {
-      enabled: !!refdata
-    },
-    put: {
-      enabled: !!refdata
-    }
-  }
-});
-...
-```
-
-This block will destructure two `mutateAsync` functions, `delete` and `put`. After a call to either of them the `json` returned will be used in a function call `setContentData`.
-
-The calls will only be enabled if `refdata` is truthy.
-
-`put` will return a function `put(data)` and will make a `put` call to add the `data` to the values of the given refdata id. In practice this means calling `put` as follows:
-```javascript
-put({
-  value: 'testValue'
-  label: 'testLabel'
-})
-```
-for a new refdataValue, or
-```javascript
-put({
-  id: <id of the refdataValue to edit>
-  value: 'testValue2'
-  label: 'testLabel 2'
-})
-```
-to edit an existing value.
-
-
-`delete` will return a function `delete(data)` and will make a `put` call to glue `_delete: true` to the given value. In practice this means calling `delete` as follows:
-```javascript
-delete(<ID of refdata value to remove>)
-```
 
 ## useActiveElement
 A hook which returns the currently focused element in the document, `active`, as well as a function `hasParent`.
@@ -145,9 +74,9 @@ return (
 ```
 
 ### Props
-Name | Type | Description | default | required
---- | --- | --- | --- | ---
-helpers | object | An object of the form `{helperKey1: Component1, helperKey2: Component1}` where `Component1`/`Component1` are components to be rendered when the url contains query `helper=helperKey1` or `helper=helperKey2` respectively | | ✓ |
+| Name    | Type   | Description                                                                                                                                                                                                                | default | required |
+|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|----------|
+| helpers | object | An object of the form `{helperKey1: Component1, helperKey2: Component1}` where `Component1`/`Component1` are components to be rendered when the url contains query `helper=helperKey1` or `helper=helperKey2` respectively |         | ✓        |
 
 ## useKiwtSASQuery
 A hook which sets up a basic queryGetter and querySetter for use with SASQ, as well as setting up the query object itself. Will often be used with the `generateKiwtQuery` function from `utils`.
@@ -285,34 +214,10 @@ export default Test
 ```
 
 ### Props
-Name | Type | Description | default | required
---- | --- | --- | --- | ---
-name | String | The name of the fieldArray, used to hook into the final form state for that field. | | ✓ |
-submitWholeDeletedObject | bool | a boolean flag to ensure that a deleted object is sent whole to the backend, rather than just as an id. | false | ✕ |
-
-## useAppSettings
-A hook for fetching AppSetting values
-### Basic usage
-```javascript
-import { useAppSettings } from '@k-int/stripes-kint-components'
-...
-const data = useAppSettings({ 
-  endpoint: 'oa/settings/appSettings'
-});
-...
-```
-
-This will return a list of AppSettings. If a `keyName` is passed, this will instead return a single AppSetting object.
-
-### Props
-Name | Type | Description | default | required
---- | --- | --- | --- | ---
-endpoint | string | The endpoint to fetch AppSettings from | | ✓ |
-sectionName | string | A string representing a section of AppSettings to filter on | | ✕ |
-keyName | string | A string representing an individual key of an AppSettings to filter on. The presence of this prop will change the output shape from Array to Object. It is not strictly necessary to use `keyName` in conjunction with `sectionName`, but keys are not guaranteed to be unique between sections. In addition it may marginally improve performance to use both, even if a key is unique, so it is recommended. | | ✕ |
-queryParams | object | A set of queryParameters to hand to react-query's `useQuery` | | ✕ |
-returnQueryObject | bool | A switch to return the entirety of the queryObject from useQuery. If `false`, the data will be destructured, if `true` the return will be the full object returned by react-query's `useQuery` | false | ✕ |
-options | object | An object of the shape SASQ_MAP (See generateKiwtQuery) to pass to the generateKiwtQuery inside. The default | `{perPage: 100, stats: false, filters: [{path: 'section', value: sectionName }, {path: 'key', value: keyName }]}` | ✕ |
+| Name                     | Type   | Description                                                                                             | default | required |
+|--------------------------|--------|---------------------------------------------------------------------------------------------------------|---------|----------|
+| name                     | String | The name of the fieldArray, used to hook into the final form state for that field.                      |         | ✓        |
+| submitWholeDeletedObject | bool   | a boolean flag to ensure that a deleted object is sent whole to the backend, rather than just as an id. | false   | ✕        |
 
 ## useMutateGeneric
 
@@ -336,15 +241,15 @@ updateObject({ id: 456, name: 'Updated Object' }) // Updates the object with id
 
 ### Props
 
-| Name | Type | Description | Default                                                                                                                        | Required |
-|---|---|---|--------------------------------------------------------------------------------------------------------------------------------|---|
-| afterQueryCalls | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1(responseData)`, `func2(responseData)`, and `func3(responseData)` are functions to be called *after* the corresponding mutation is successful. `responseData` is the data returned by the API call. | `{}`                                                                                                                           | ✕ |
-| catchQueryCalls | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1(error)`, `func2(error)`, and `func3(error)` are functions to be called *if* the corresponding mutation fails. `error` is the HTTPError object. | `{}`                                                                                                                           | ✕ |
-| endpoint | string | The base endpoint for the API calls. |                                                                                                                                | ✓ |
-| endpointMutators | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1(id)`, `func2()`, and `func3(data)` are functions that modify the endpoint for each operation.  Defaults to appending the id for `delete` and `put`, and using the base endpoint for `post`. | `{ delete: (id) => "${endpoint}/${id}", post: () => endpoint, put: (data) => "${endpoint}/${data.id}" }`                        | ✕ |
-| payloadMutators | object | An object of the form `{ post: func1, put: func2 }` where `func1(data)` and `func2(data)` are functions that modify the payload for the `post` and `put` operations. Defaults to wrapping the data in a `json` object. | `{ post: (data) => ({ json: data }), put: (data) => ({ json: data }) }`                                                        | ✕ |
-| promiseReturns | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1(id, ky)`, `func2(data, ky)`, and `func3(data, ky)` are functions that define the promise return for each operation. Allows full control over the `ky` call.  `id` is the id for delete, `data` is the data being sent for post/put, and `ky` is the `ky` instance. | `{ delete: (id, ky) => ky.delete(...).json(), post: (data, ky) => ky.post(...).json(), put: (data, ky) => ky.put(...).json() }` | ✕ |
-| queryKey | array | The query key to be used with `react-query`.  **Must be an array.** | `[]`                                                                                                                           | ✓ |
-| queryKeyMutators | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1()`, `func2()`, and `func3()` are functions that return the query key for each mutation. | `{ delete: () => [...queryKey, 'delete'], post: () => [...queryKey, 'create'], put: () => [...queryKey, 'edit'] }`             | ✕ |
-| queryParams | object | An object of the form `{ delete: obj1, post: obj2, put: obj3 }` where `obj1`, `obj2`, and `obj3` are the query parameters for each operation. | `{}`                                                                                                                           | ✕ |
-| returnQueryObject | object | An object of the form `{ delete: bool1, post: bool2, put: bool3 }` containing switches to return the entire query object from `useMutation` for each operation. If `false` (the default), the `mutateAsync` function will be returned; if `true`, the full object (including `mutate`, `isLoading`, `error`, etc.) will be returned. | `{ delete: false, post: false, put: false }`                                                                                   | ✕ |
+| Name              | Type   | Description                                                                                                                                                                                                                                                                                                                                        | Default                                                                                                                         | Required |
+|-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|----------|
+| afterQueryCalls   | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1(responseData)`, `func2(responseData)`, and `func3(responseData)` are functions to be called *after* the corresponding mutation is successful. `responseData` is the data returned by the API call.                                                                 | `{}`                                                                                                                            | ✕        |
+| catchQueryCalls   | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1(error)`, `func2(error)`, and `func3(error)` are functions to be called *if* the corresponding mutation fails. `error` is the HTTPError object.                                                                                                                     | `{}`                                                                                                                            | ✕        |
+| endpoint          | string | The base endpoint for the API calls.                                                                                                                                                                                                                                                                                                               |                                                                                                                                 | ✓        |
+| endpointMutators  | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1(id)`, `func2()`, and `func3(data)` are functions that modify the endpoint for each operation.  Defaults to appending the id for `delete` and `put`, and using the base endpoint for `post`.                                                                        | `{ delete: (id) => "${endpoint}/${id}", post: () => endpoint, put: (data) => "${endpoint}/${data.id}" }`                        | ✕        |
+| payloadMutators   | object | An object of the form `{ post: func1, put: func2 }` where `func1(data)` and `func2(data)` are functions that modify the payload for the `post` and `put` operations. Defaults to wrapping the data in a `json` object.                                                                                                                             | `{ post: (data) => ({ json: data }), put: (data) => ({ json: data }) }`                                                         | ✕        |
+| promiseReturns    | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1(id, ky)`, `func2(data, ky)`, and `func3(data, ky)` are functions that define the promise return for each operation. Allows full control over the `ky` call.  `id` is the id for delete, `data` is the data being sent for post/put, and `ky` is the `ky` instance. | `{ delete: (id, ky) => ky.delete(...).json(), post: (data, ky) => ky.post(...).json(), put: (data, ky) => ky.put(...).json() }` | ✕        |
+| queryKey          | array  | The query key to be used with `react-query`.  **Must be an array.**                                                                                                                                                                                                                                                                                | `[]`                                                                                                                            | ✓        |
+| queryKeyMutators  | object | An object of the form `{ delete: func1, post: func2, put: func3 }` where `func1()`, `func2()`, and `func3()` are functions that return the query key for each mutation.                                                                                                                                                                            | `{ delete: () => [...queryKey, 'delete'], post: () => [...queryKey, 'create'], put: () => [...queryKey, 'edit'] }`              | ✕        |
+| queryParams       | object | An object of the form `{ delete: obj1, post: obj2, put: obj3 }` where `obj1`, `obj2`, and `obj3` are the query parameters for each operation.                                                                                                                                                                                                      | `{}`                                                                                                                            | ✕        |
+| returnQueryObject | object | An object of the form `{ delete: bool1, post: bool2, put: bool3 }` containing switches to return the entire query object from `useMutation` for each operation. If `false` (the default), the `mutateAsync` function will be returned; if `true`, the full object (including `mutate`, `isLoading`, `error`, etc.) will be returned.               | `{ delete: false, post: false, put: false }`                                                                                    | ✕        |

package/src/lib/hooks/__mocks__/index.js

@@ -1,14 +1,14 @@
 import refdata from '../../../../test/jest/refdata';
 import customProperties from '../../../../test/jest/customProperties';
 
-import useKintIntl from '../useKintIntl';
+import useKintIntl from '../intlHooks/useKintIntl';
 
 /* EXAMPLE Grab actual hooks for anything not mocked here */
 const hooks = jest.requireActual('../index');
 
 // We have to do this up here too so that our passed useKintIntl
 // ALSO has a mocked useIntlKeyStore... I think anyway
-jest.mock('../useIntlKeyStore', () => () => () => 'ui-test-implementor');
+jest.mock('../intlHooks/useIntlKeyStore', () => () => () => 'ui-test-implementor');
 
 module.exports = {
   ...hooks,

package/src/lib/hooks/index.js

@@ -8,9 +8,6 @@ export { default as useQIndex } from './useQIndex';
 export { default as useKiwtFieldArray } from './useKiwtFieldArray';
 export { default as useCustomProperties } from './useCustomProperties';
 export { default as useInvalidateRefdata } from './useInvalidateRefdata';
-export { default as useKintIntl } from './useKintIntl';
-export { default as useIntlKeyStore } from './useIntlKeyStore';
-export { default as useIntlKey } from './useIntlKey';
 export { default as useSASQQueryMeta } from './useSASQQueryMeta';
 export { default as useModConfigEntries } from './useModConfigEntries';
 export { default as useActionListRef } from './useActionListRef';
@@ -22,3 +19,5 @@ export { default as useMutateCustomProperties } from './useMutateCustomPropertie
 export { default as useMutateModConfigEntry } from './useMutateModConfigEntry';
 
 export { default as usePrevNextPagination } from './usePrevNextPagination';
+
+export * from './intlHooks';

package/src/lib/hooks/intlHooks/README.md

@@ -0,0 +1,31 @@
+# Internationalization (intl) Hooks
+
+This suite of hooks provides a standardized way to handle internationalization across components while respecting module boundaries. The system allows:
+
+1. **Root Module Configuration** - Set default intl keys/namespaces at application root
+2. **Component-Level Overrides** - Customize translations per-component via `intlKey`/`intlNS` props
+3. **Automatic Key Resolution** - Components automatically find translations without hardcoded paths
+
+## Key Components
+
+1. **[useIntlKeyStore](./useIntlKeyStore/README.md)** - Global store for managing intl keys
+2. **[useIntlKey](./useIntlKey/README.md)** - Hook for resolving intl keys
+3. **[useKintIntl](./useKintIntl/README.md)** - Enhanced intl formatting hook
+
+## Core Principles
+
+- **No Library Translations** - Parent modules provide all translations
+- **Explicit Key Management** - Required key configuration prevents silent failures
+- **Namespace Isolation** - Prevents key collisions between modules
+- **Override Support** - Components can bypass default keys when needed
+
+## Implementation Benefits
+
+- ✅ Avoids duplicated translation efforts
+- ✅ Maintains Lokalise compatibility
+- ✅ Enables component reuse across modules
+- ✅ Provides clear error messaging for missing config
+- ✅ Supports both simple and complex i18n scenarios
+
+## Developer note
+This clearly isn't an ideal solution, but it is the best one we could come up with at the time. Each module implementing kint-components can either set up a global key store telling kint-components where to look for their intl keys in general, or set this on a component by component case via the `intlKey` and `intlNS` props used throughout kint-components

package/src/lib/hooks/intlHooks/index.js

@@ -0,0 +1,3 @@
+export { default as useIntlKeyStore } from './useIntlKeyStore';
+export { default as useIntlKey } from './useIntlKey';
+export { default as useKintIntl } from './useKintIntl';

package/src/lib/hooks/intlHooks/useIntlKey/README.md

@@ -0,0 +1,23 @@
+# useIntlKey
+
+## Purpose
+Resolves internationalization keys with fallback logic.
+
+## Resolution Order
+1. Directly passed `intlKey` prop
+2. Namespace lookup via `intlNS` prop
+3. Default namespace from `useNamespace`
+
+## Error Handling
+Throws error if:
+- No key passed directly
+- No key found in registry
+- Namespace not registered
+
+## Usage
+```jsx
+const Component = ({ intlKey, intlNS }) => {
+  const resolvedKey = useIntlKey(intlKey, intlNS);
+  // Uses resolved key for translations
+};
+```

package/src/lib/hooks/intlHooks/useIntlKey/index.js

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

package/src/lib/hooks/{useIntlKey.js → intlHooks/useIntlKey/useIntlKey.js}

@@ -1,4 +1,4 @@
-import useIntlKeyStore from './useIntlKeyStore';
+import useIntlKeyStore from '../useIntlKeyStore';
 
 const useIntlKey = (passedIntlKey, passedIntlNS) => {
   const getKey = useIntlKeyStore(state => state.getKey);

package/src/lib/hooks/intlHooks/useIntlKeyStore/README.md

@@ -0,0 +1,32 @@
+# useIntlKeyStore
+
+## Purpose
+Global state management for internationalization keys using Zustand.
+
+## Key Features
+- Namespace-key pair storage
+- Automatic namespace resolution
+- Hook-safe operations
+
+## Initial Setup
+```jsx
+// App root component
+import useIntlKeyStore from './useIntlKeyStore';
+
+const App = () => {
+  const { addKey } = useIntlKeyStore();
+  
+  useEffect(() => {
+    addKey('moduleBaseKey', 'myModuleNamespace');
+  }, [addKey]);
+
+  return (...);
+};
+```
+
+## Store Methods
+| Method       | Parameters          | Description                          |
+|--------------|---------------------|--------------------------------------|
+| `addKey`     | `(key, namespace)`  | Registers namespace-key pair         |
+| `removeKey`  | `(namespace)`       | Removes namespace registration       |
+| `getKey`     | `(namespace)`       | Retrieves key for namespace          |

package/src/lib/hooks/intlHooks/useIntlKeyStore/index.js

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

package/src/lib/hooks/intlHooks/useKintIntl/README.md

@@ -0,0 +1,42 @@
+# useKintIntl
+
+## Purpose
+Enhanced internationalization hook that extends `react-intl`'s `useIntl` with automatic key resolution and override support.
+
+## Key Features
+- Automatic key prefixing with module-specific base path
+- Fallback message support
+- Type-safe override validation
+- Message existence checking
+
+## Basic Usage
+```jsx
+const MyComponent = () => {
+  const { formatKintMessage } = useKintIntl('myComponent', 'myModule');
+  
+  return (
+    <div>
+      {formatKintMessage({ id: 'greeting' })}
+    </div>
+  );
+};
+```
+
+## Override Behavior
+Component-level overrides take precedence:
+```jsx
+<MyComponent 
+  intlKey="customKey" 
+  intlNS="customNamespace"
+/>
+```
+
+## Methods
+### `formatKintMessage(options, values)`
+- `options.id`: Relative translation key (auto-prefixed)
+- `options.overrideValue`: Direct string or alternate translation key
+- `options.fallbackMessage`: Fallback text if translation missing
+- `values`: Injection values for placeholders
+
+### `messageExists(key)`
+Checks if translation exists for resolved key

package/src/lib/hooks/intlHooks/useKintIntl/index.js

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

package/src/lib/hooks/{useKintIntl.js → intlHooks/useKintIntl/useKintIntl.js}

@@ -1,5 +1,5 @@
 import { useIntl } from 'react-intl';
-import useIntlKey from './useIntlKey';
+import useIntlKey from '../useIntlKey';
 
 /* A hook to enrich the intl object we get from useIntl */
 const useKintIntl = (passedIntlKey, passedIntlNS) => {

package/src/lib/hooks/useInvalidateRefdata/README.md

@@ -0,0 +1,72 @@
+# useInvalidateRefdata
+
+## Reference Data Cache Management Hook
+A specialized utility for maintaining reference data consistency across the application.
+Part of the reference data management ecosystem, designed to work with [`useMutateRefdataCategory`](../useMutateRefdataCategory/README.md) and [`useMutateRefdataValue`](../useMutateRefdataValue/README.md).
+
+## Basic Usage
+```jsx
+const RefdataUpdater = () => {
+  const invalidate = useInvalidateRefdata('license_types');
+
+  const handleUpdate = async () => {
+    await updateLicenseTypes();
+    invalidate(); // Triggers cache refresh
+  };
+
+  return <Button onClick={handleUpdate}>Refresh Data</Button>;
+};
+```
+
+### 2. Query Key Structure
+Uses centralized key generator [`refdataQueryKey`](../../utils/refdataQueryKey/README.md):
+```js
+refdataQueryKey('media_formats') => ['stripes-kint-components', 'refdata', 'media_formats']
+```
+
+## Parameters
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `desc` | string | ✕ | - | Reference data category descriptor |
+
+## Advanced Usage
+
+### Batch Invalidation
+```jsx
+const invalidateMedia = useInvalidateRefdata('media_types');
+const invalidateLicenses = useInvalidateRefdata('license_types');
+
+const handleGlobalRefresh = async () => {
+  await Promise.all([
+    invalidateMedia(),
+    invalidateLicenses()
+  ]);
+};
+```
+
+### Conditional Invalidation
+```jsx
+const RefdataForm = ({ category }) => {
+  const invalidate = useInvalidateRefdata(category?.type);
+
+  const handleSubmit = async (data) => {
+    await saveCategory(data);
+    if (category) invalidate();
+  };
+};
+```
+
+## Integration Notes
+
+### Performance Considerations
+- Prefer targeted invalidations over global refresh
+- Combine with mutation hooks for automatic invalidation
+- Avoid in tight loops - debounce if needed
+
+### Error Handling
+- Safe to call multiple times
+- Fails silently if no active queries match
+- Returns promise for error chaining:
+```js
+invalidate().catch(error => logger.error('Refresh failed', error));
+```

package/src/lib/hooks/useInvalidateRefdata/index.js

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

package/src/lib/hooks/{useInvalidateRefdata.js → useInvalidateRefdata/useInvalidateRefdata.js}

@@ -1,6 +1,6 @@
 import { useQueryClient } from 'react-query';
 
-import { refdataQueryKey } from '../utils';
+import { refdataQueryKey } from '../../utils';
 
 const useInvalidateRefdata = (desc) => {
   const queryClient = useQueryClient();

package/src/lib/hooks/useMutateCustomProperties/README.md

@@ -0,0 +1,88 @@
+# useMutateCustomProperties
+
+## Purpose-Specific Mutation Hook
+A specialized abstraction of [`useMutateGeneric`](./useMutateGeneric.md) optimized for managing custom properties configurations in FOLIO. Designed for operations targeting specific resource identifiers with enforced endpoint structure.
+
+```mermaid
+graph TD
+  A[useMutateCustomProperties] --> B[useMutateGeneric]
+  B --> C[Pre-configured Endpoints]
+  B --> D[Standardized Query Keys]
+```
+
+## When to Use
+- Managing custom properties for **single-resource endpoints**
+- Operations requiring fixed ID in URL paths
+- Standardizing cache keys for property-related mutations
+
+## Key Differentiators
+|| useMutateGeneric | useMutateCustomProperties |
+|---|---|---|
+| **Endpoint Structure** | Configurable | Enforced `/endpoint/{id}` |
+| **Query Key** | Customizable | Auto-generated hierarchy |
+| **ID Handling** | Manual in calls | Built into configuration |
+
+## Usage Example
+```jsx
+const CustomPropertiesEditor = ({ recordId }) => {
+  const { post, put } = useMutateCustomProperties({
+    endpoint: 'configurations/custom-properties',
+    id: recordId
+  });
+
+  const saveProperty = (property) => 
+    property.id ? put(property) : post(property);
+
+  return <PropertyForm onSubmit={saveProperty} />;
+};
+```
+
+## Required Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `endpoint` | string | Base API path (e.g., `'license/custom-properties'`) |
+| `id` | string | Unique resource identifier for URL construction |
+
+## Default Behavior
+1. **Endpoint Construction**
+   ```js
+   // PUT/DELETE endpoints
+   `${endpoint}/${id}`
+   ```
+2. **Query Key Structure**
+   ```js
+   ['stripes-kint-components', 'useMutateCustomProperties', id]
+   ```
+
+## Customization
+While providing opinionated defaults, maintains full compatibility with [`useMutateGeneric`](./useMutateGeneric.md) configuration:
+
+```jsx
+// Override delete endpoint while keeping other defaults
+useMutateCustomProperties({
+  endpoint: 'inventory/types',
+  id: 'BOOK',
+  endpointMutators: {
+    delete: () => `inventory/legacy-types/${id}?version=2`
+  }
+});
+```
+
+## Error Handling
+Inherits the [error handling characteristics](./useMutateGeneric.md#error-handling-philosophy) of the base hook. Recommended pattern:
+
+```jsx
+useMutateCustomProperties({
+  catchQueryCalls: {
+    post: (error) => {
+      logger.error('Custom property creation failed', error);
+      throw error; // Propagate to error boundary
+    }
+  }
+});
+```
+
+## Performance Notes
+- Cache keys automatically include the `id` parameter
+- Memoize configurations when using multiple instances
+- Prefer single instance per resource ID lifecycle

package/src/lib/hooks/useMutateCustomProperties/index.js

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

package/src/lib/hooks/{useMutateCustomProperties.js → useMutateCustomProperties/useMutateCustomProperties.js}

@@ -1,4 +1,4 @@
-import useMutateGeneric from './useMutateGeneric';
+import useMutateGeneric from '../useMutateGeneric';
 
 const useMutateCustomProperties = ({
   endpoint,