noob-components/.trellis/spec/plugs-composables/use-refresh-flags.md

# useRefreshFlags

> Auto-refresh flag management with Vuex store integration.

## Purpose

Watches refresh flags in Vuex store and triggers callbacks when matching flags are set. Used for coordinated auto-refresh across components.

## Signature

```typescript
export function useRefreshFlags(
  flags: string[],
  cb: () => void | Promise<void>,
  match?: "any" | "all",
  token?: string
): void
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `flags` | `string[]` | required | Flag names to watch |
| `cb` | `() => void \| Promise<void>` | required | Callback when flag matches |
| `match` | `"any" \| "all"` | `"any"` | Match any flag or all flags |
| `token` | `string` | `route.path` | Unique token for this watcher |

## Match Behavior

- **`"any"`**: Trigger when any flag is set and this token hasn't consumed it
- **`"all"`**: Trigger when all flags are set and this token hasn't consumed them

## Vuex Store Structure

Expects `state.refreshFlags` to be a Map structure:
```typescript
state.refreshFlags: Map<string, Set<string>>
// flag name -> Set of tokens that have consumed it
```

## Usage Pattern

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

// Watch for any of these flags
useRefreshFlags(["userUpdated", "roleChanged"], async () => {
  await query();
});

// Watch for all flags
useRefreshFlags(["fetchUsers", "fetchDepartments"], async () => {
  await query();
}, "all");

// With custom token
useRefreshFlags(["refresh"], () => {
  query();
}, "any", "my-unique-component-id");
```

## Key Implementation Details

1. **Token auto-detection**: Uses `route.path` as default token if not provided
2. **Flag consumption**: After callback executes, calls `unsetRefreshFlag` Vuex action to mark flags as consumed by this token
3. **Reactive tracking**: Explicitly accesses `state.refreshFlags` to ensure Vue tracks the dependency

## Dependencies

- `vue` - `watch`
- `vue-router` - `useRoute`
- `vuex` - `useStore`

## Anti-patterns

- Do not use the same token for multiple independent watchers; each logical unit should have unique token
- Do not forget to dispatch `unsetRefreshFlag` for consumed flags (handled automatically)