# 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