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

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

Types

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

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

Usage Pattern

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

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