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

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

@@ -0,0 +1,187 @@
+# useMutateGeneric
+
+## Description
+A configurable React Query mutation hook that abstracts CRUD operations for Okapi endpoints. Provides atomic control over POST/PUT/DELETE operations with deep customization while maintaining FOLIO API conventions.
+
+**Key Features**:
+- Auto-generated endpoint URLs
+- Built-in error swallowing (silent catch unless overridden)
+- Type-safe mutation separation
+- Query key hierarchy management
+- Full lifecycle event hooks
+
+---
+
+## Basic Usage
+```jsx
+const { post, put, delete: destroy } = useMutateGeneric({
+  endpoint: 'users',
+  queryKey: ['user-management']
+});
+
+// Create user
+const handleCreate = (userData) => post(userData);
+
+// Update user
+const handleUpdate = (updatedUser) => put(updatedUser);
+
+// Delete user
+const handleDelete = (userId) => destroy(userId);
+```
+
+**Note**: By default:
+- Errors are caught but not thrown (silent failure)
+- POST goes to `/endpoint`
+- PUT/DELETE go to `/endpoint/{id}`
+
+---
+
+## Advanced Use Cases
+
+### 1. Custom Endpoint Structure
+```jsx
+// Custom endpoint for legacy system
+useMutateGeneric({
+  endpoint: 'v2/inventory',
+  endpointMutators: {
+    put: (data) => `legacy-inventory/${data.legacyId}?version=1.2`
+  }
+});
+```
+
+### 2. Payload Transformation
+```jsx
+// Add audit metadata to payload
+useMutateGeneric({
+  payloadMutators: {
+    post: (data) => ({
+      json: {
+        ...data,
+        metadata: {
+          createdBy: getCurrentUserId(),
+          createdDate: new Date().toISOString()
+        }
+      }
+    })
+  }
+});
+```
+
+### 3. Custom Promise Handling
+```jsx
+// Directly override HTTP method
+useMutateGeneric({
+  promiseReturns: {
+    post: (data, ky) => ky.custom('PATCH', 'custom-endpoint', { data })
+  }
+});
+```
+
+### 4. Full Mutation Control
+```jsx
+// Access loading states and errors
+const {
+  post: postMutation // Returns full mutation object
+} = useMutateGeneric({
+  returnQueryObject: { post: true }
+});
+
+// Usage
+postMutation.mutateAsync(data);
+console.log('Loading:', postMutation.isLoading);
+```
+
+---
+
+## Configuration Options
+
+### Core Parameters
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `endpoint` | string | ✓ | - | Base API path (e.g., `'circulation/loans'`) |
+| `queryKey` | array | ✓ | - | React Query root key (e.g., `['loans']`) |
+
+### Operation-Specific Parameters (post/put/delete)
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `endpointMutators.{op}` | `(data) => string` | [See below] | Generates final endpoint URL |
+| `payloadMutators.{op}` | `(data) => object` | Returns `{ json: data }` | Shapes request payload |
+| `promiseReturns.{op}` | `(data, ky) => Promise` | Standard CRUD | Full control over fetch implementation |
+| `queryKeyMutators.{op}` | `() => array` | Appends operation type | Custom query key construction |
+| `afterQueryCalls.{op}` | `(response) => void` | - | Success side effects |
+| `catchQueryCalls.{op}` | `(error) => void` | Silent catch | Custom error handling |
+| `returnQueryObject.{op}` | boolean | `false` | Returns full mutation object |
+
+**Default Endpoint Mutators**:
+- POST: `() => endpoint`
+- PUT: `(data) => ${endpoint}/${data.id}`
+- DELETE: `(id) => ${endpoint}/${id}`
+
+---
+
+## How It Works
+
+### Architecture Flow
+1. **Hook Initialization**
+    - Receives base configuration
+    - Creates three isolated `useMutation` instances (post/put/delete)
+
+2. **Request Execution**
+   ```mermaid
+   graph TD
+   A[User calls post(data)] --> B[Apply payloadMutators]
+   B --> C[Build endpoint via endpointMutators]
+   C --> D[Execute promiseReturns with ky]
+   D --> E[Trigger afterQueryCalls]
+   E --> F[Update React Query cache]
+   ```
+
+3. **Error Handling**
+    - Errors bubble through `catchQueryCalls`
+    - Uncaught errors are swallowed unless `catchQueryCalls` re-throws
+
+4. **Cache Management**
+    - Automatic query key generation via `queryKeyMutators`
+    - No automatic cache invalidation (must use `useQueryClient`)
+
+---
+
+## Critical Implementation Notes
+
+### 1. Error Handling Philosophy
+- Default: Fails silently (prevents uncaught promise warnings)
+- To surface errors:
+  ```js
+  useMutateGeneric({
+    catchQueryCalls: {
+      post: (error) => {
+        showErrorToast(error); 
+        throw error; // Propagate to UI errorBoundary if necessary
+      }
+    }
+  });
+  ```
+
+### 2. Type Safety
+- No runtime validation of payload shapes
+- Recommend validation in `payloadMutators`:
+  ```js
+  payloadMutators: {
+    post: (data) => {
+      const safeData = ItemSchema.parse(data);
+      return { json: safeData };
+    }
+  }
+  ```
+
+### 3. Performance Considerations
+- Each operation creates isolated mutation instances
+- Avoid excessive re-renders by memoizing config objects
+- For bulk operations, prefer direct ky usage
+
+---
+
+## When Not to Use
+- **Simple GET requests**: Use `useQuery` directly
+- **Non-Okapi APIs**: Lacks built-in auth headers
+  - However this can be achieved by overriding the fetch method with `promiseReturns`

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

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

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

@@ -0,0 +1,85 @@
+# useMutateRefdataCategory
+
+## Reference Data Mutation Hook
+A specialized abstraction of [`useMutateGeneric`](./useMutateGeneric.md) optimized for managing reference data categories with automatic cache invalidation. Part of the reference data management ecosystem.
+
+```mermaid
+graph TD
+  A[CRUD Operation] --> B[Invalidate Refdata Cache]
+  B --> C[Trigger UI Refresh]
+```
+
+## Key Features
+- **Automatic Cache Busting:** Invalidates reference data cache after mutations
+- **Payload Safeguards:** Enforces empty `values` array for new categories
+- **Query Key Standardization:** Pre-configured cache key structure
+
+## Usage Pattern
+```jsx
+const RefdataCategoryManager = () => {
+  const { post } = useMutateRefdataCategory({
+    endpoint: 'license/refdata',
+    afterQueryCalls: {
+      post: (newCategory) => showToast(`Created ${newCategory.desc}`)
+    }
+  });
+
+  const handleCreate = (categoryData) => post({
+    desc: 'Publication Types',
+    id: 'publication_type'
+  });
+
+  return <Button onClick={handleCreate}>Create Category</Button>;
+};
+```
+
+## Core Enhancements
+
+### 1. Cache Invalidation Pipeline
+Automatic refresh flow after mutations:
+1. Execute mutation (create/update/delete)
+2. Invalidate reference data cache
+3. Trigger dependent queries refresh
+4. Execute custom `afterQuery` handlers
+
+### 2. Payload Enforcement
+New categories receive empty values array:
+```js
+// Input payload
+{ desc: 'Media Formats', id: 'media_format' }
+
+// Actual POST body
+{
+  desc: 'Media Formats',
+  id: 'media_format',
+  values: []
+}
+```
+
+## Configuration
+
+### Inherited Props
+Supports all [`useMutateGeneric` props](../useMutateGeneric/README.md#configuration-options) except:
+
+| Prop                   | Override | Reason                   |
+|------------------------|----------|--------------------------|
+| `payloadMutators.post` | Yes      | Values array enforcement |
+| `queryKey`             | Yes      | Standardized refdata key |
+
+### Special Handling
+```js
+// To bypass empty values array (advanced)
+useMutateRefdataCategory({
+  payloadMutators: {
+    post: (data) => ({ json: data }) // Not recommended
+  }
+});
+```
+
+## Error Handling
+Maintains base hook's [error handling characteristics](./useMutateGeneric.md#error-handling-philosophy) with added complexity:
+- Cache invalidation occurs **before** custom `afterQuery` handlers
+- Failed invalidations log to console but don't block operations
+
+## Integration Requirements
+Uses [`useInvalidateRefdata`](../useInvalidateRefdata/README.md) to handle refdata query cache invalidation automatically.

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

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

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

@@ -1,7 +1,7 @@
 import noop from 'lodash/noop';
 
-import useInvalidateRefdata from './useInvalidateRefdata';
-import useMutateGeneric from './useMutateGeneric';
+import useInvalidateRefdata from '../useInvalidateRefdata';
+import useMutateGeneric from '../useMutateGeneric';
 
 const useMutateRefdataCategory = ({
   afterQueryCalls: {

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

@@ -0,0 +1,154 @@
+# useMutateRefdataValue
+
+## Refdata Value Mutation Hook
+A specialized abstraction of [`useMutateGeneric`](./useMutateGeneric.md) for atomic reference data value operations. Handles value lifecycle management within refdata categories with integrated cache invalidation.
+
+```mermaid
+graph TD
+  A[Value Mutation] --> B[Cache Invalidation]
+  B --> C[Consistent UI State]
+```
+
+## Key Features
+- **Value Lifecycle Management:** Unified create/update/delete operations
+- **Atomic Operations:** Batch-safe value modifications
+- **API handling:** Uses `_delete: true` pattern instead of usual `delete` http calls.
+- **Query Key Standardization:** Automatic cache key generation
+
+## Basic Usage
+```jsx
+const RefdataValueEditor = ({ categoryId }) => {
+  const { post: createValue } = useMutateRefdataValue({
+    endpoint: 'license/refdata',
+    id: categoryId
+  });
+
+  const handleCreate = (valueData) => createValue({
+    value: 'eBook',
+    label: 'Electronic Book'
+  });
+
+  return <ValueForm onSubmit={handleCreate} />;
+};
+```
+
+## Core Enhancements
+
+### 1. Value Operation Patterns
+| Operation | HTTP Method | Payload Structure |
+|-----------|-------------|--------------------|
+| Create | PUT | `{values: [newValue]}` |
+| Update | PUT | `{values: [updatedValue]}` |
+| Delete | PUT | `{values: [{id: valueId, _delete: true}]}` |
+
+### 2. Cache Coherence
+Automatic refresh flow:
+1. Execute value mutation
+2. Invalidate refdata cache
+3. Trigger dependent queries
+4. Execute custom post-hooks
+
+## Configuration
+
+### Essential Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `endpoint` | string | Base refdata endpoint (e.g., `'oa/refdata'`) |
+| `id` | string | Target refdata category ID |
+
+### Inherited Capabilities
+Supports all [`useMutateGeneric` configurations](../useMutateGeneric/README.md#configuration-options) with:
+
+| Aspect | Implementation |
+|--------|----------------|
+| Query Key | `['stripes-kint-components', 'useMutateRefdataValue', id]` |
+| Endpoint Structure | Fixed `${endpoint}/${id}` |
+
+## Advanced Use Cases
+
+### Value Updates
+```jsx
+const { put: updateValue } = useMutateRefdataValue({
+  endpoint: 'inventory/types',
+  id: 'MEDIA_FORMAT'
+});
+
+// Update existing value
+updateValue({
+  id: 'DVD',
+  label: 'Digital Video Disc',
+  value: 'dvd_media'
+});
+```
+
+### Conditional Operations
+```jsx
+useMutateRefdataValue({
+  queryParams: {
+    put: {
+      enabled: !!activeCategory
+    }
+  }
+});
+```
+
+### Error Recovery
+```jsx
+useMutateRefdataValue({
+  catchQueryCalls: {
+    put: (error) => {
+      recovery.saveState();
+      throw error;
+    }
+  }
+});
+```
+
+## Operation Patterns
+
+### Value Creation
+```js
+createValue({
+  value: 'streaming',
+  label: 'Streaming Service'
+});
+```
+
+### Value Deletion
+```js
+deleteValue(refdataId); // Removes value from the refdata category via _delete pattern
+```
+
+## Critical Implementation Notes
+
+1. **Idempotent Design**
+    - All operations use PUT for atomic updates
+    - Multiple changes require sequential calls
+
+2. **Payload Requirements**
+   ```js
+   // Update requires existing ID
+   {
+     id: 'existing_value_id',
+     label: 'Updated Label'
+   }
+   ```
+
+3. **Cache Key Dependencies**
+    - Keys include category ID for isolation
+    - Multiple category instances require separate hooks
+
+4. **Error Handling**
+    - Silent failure by default
+    - Override with `catchQueryCalls`:
+   ```js
+   useMutateRefdataValue({
+     catchQueryCalls: {
+       put: (error) => showErrorToast(error.message)
+     }
+   });
+   ```
+
+## Integration Requirements
+- Uses [`useInvalidateRefdata`](../useInvalidateRefdata/README.md) to handle refdata query cache invalidation automatically.
+- Must be used within React Query provider

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

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

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

@@ -1,7 +1,7 @@
 import noop from 'lodash/noop';
 
-import useInvalidateRefdata from './useInvalidateRefdata';
-import useMutateGeneric from './useMutateGeneric';
+import useInvalidateRefdata from '../useInvalidateRefdata';
+import useMutateGeneric from '../useMutateGeneric';
 
 const useMutateRefdataValue = ({
    afterQueryCalls: {

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

@@ -0,0 +1,24 @@
+# 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 }]}` | ✕        |

package/src/lib/utils/refdataQueryKey/README.md

@@ -0,0 +1,38 @@
+# refdataQueryKey
+
+## Query Key Generator Utility
+A standardized query key factory function for reference data management within the `stripes-kint-components` ecosystem. Ensures consistent cache key structure across all reference data operations.
+
+## Basic Usage
+```jsx
+// Get base refdata key
+const baseKey = refdataQueryKey(); 
+// => ['stripes-kint-components', 'refdata']
+
+// Get category-specific key
+const licenseKey = refdataQueryKey('license_types');
+// => ['stripes-kint-components', 'refdata', 'license_types']
+```
+
+## Parameters
+| Parameter | Type   | Required | Default | Description                        |
+|-----------|--------|----------|---------|------------------------------------|
+| `desc`    | string | ✕        | -       | Reference data category descriptor |
+
+## Return Value Structure
+```js
+['stripes-kint-components', 'refdata', ...(desc ? [desc] : [])]
+```
+
+## Integration Pattern
+Used with React Query operations and cache management:
+```jsx
+// Query
+useQuery(
+  refdataQueryKey('media_formats'),
+  fetchRefdataFunction
+);
+
+// Invalidation
+queryClient.invalidateQueries(refdataQueryKey('media_formats'));
+```

package/src/lib/utils/refdataQueryKey/index.js

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

package/styles/SearchKeyControl.css

@@ -0,0 +1,14 @@
+@import "@folio/stripes-components/lib/variables.css";
+
+.searchKeyControlContainer {
+    /* Remove this top margin, only here for clarity*/
+    margin: var(--gutter-static-two-thirds) 0px;
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: flex-start;
+}
+
+.searchKeyControlElement {
+    width: fit-content;
+    padding: 0 var(--gutter-static-two-thirds) 0 0;
+}