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

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,

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: {