noob-components/.trellis/spec/plugs-composables/use-sys-dict.md

# useSysDict

> System dictionary management with Vuex store and dynamic callbacks.

## Purpose

Manages system-wide dictionary data, fetching and caching dict values with optional transformation callbacks.

## Signature

```typescript
export function useSysDict(): {
  sysDict: ComputedRef<Record<string, Record<string, string>>>;
  updateDict: (dictIds: string[], registerCallbacks?: Record<string, Callback>) => Promise<void>;
  unregister: (ids: string[]) => void;
}
```

## Types

```typescript
type Callback = () => Record<string, string> | Promise<Record<string, string>>;
```

## Return Value

| Property | Type | Description |
|----------|------|-------------|
| `sysDict` | `ComputedRef<Record<string, Record<string, string>>>` | Reactive dict map |
| `updateDict` | `(ids, callbacks?) => Promise<void>` | Fetch and register dicts |
| `unregister` | `(ids) => void` | Remove dict callbacks |

## SysDict Structure

```typescript
{
  [dictId: string]: {
    [key: string]: string | number;
  }
}
```

## Usage Pattern

```typescript
// Example: plugs/composables/useSysDict.ts
import { useSysDict } from "plugs/composables";

const { sysDict, updateDict, unregister } = useSysDict();

// Fetch multiple dicts with custom handlers
await updateDict(["userStatus", "gender"], {
  userStatus: () => fetchStatusDict(),
  gender: () => ({ M: "Male", F: "Female" }),
});

// Access dict values
const statusMap = sysDict.value.userStatus;

// Unregister when done
unregister(["userStatus"]);
```

## Value Normalization

The `normalize()` function converts string values to numbers when possible:
```typescript
parseInt("123") → 123
parseInt("abc") → "abc" (unchanged)
```

## Key Implementation Details

1. **Callback registration**: Allows custom dict fetch logic via callbacks
2. **Global callback storage**: Uses module-level `callbacks` object for cross-component dict handling
3. **Vuex integration**: Dispatches `getDictMap` for bulk dict fetching

## Vuex Integration

Expects store to have:
- `state.dict` - Dict data map
- `commit("updateDict", [id, normalizedData])` - Update single dict
- `dispatch("getDictMap", dictIds)` - Bulk fetch dicts

## Dependencies

- `vue` - `computed`
- `vuex` - `useStore`

## Anti-patterns

- Do not mutate `sysDict` values directly
- Do not forget to `unregister()` callbacks when component unmounts if using custom callbacks