spa/.planning/phase-2-live-map/07-event-picker.md

# Task 2.7 — Event picker (subscription driver)

**Phase:** 2 — Live monitoring map
**Status:** ⬜ Not started
**Depends on:** 2.4.
**Wiki refs:** `docs/wiki/synthesis/processor-ws-contract.md` §"Subscription model"; `docs/wiki/synthesis/directus-schema-draft.md`.

## Goal

Let the operator pick which event to monitor. The picker reads the events the user has access to from Directus (via TanStack Query), drives the WS subscription via `client.subscribe('event:<id>')`, applies the snapshot to the position store, and switches subscriptions cleanly when the user changes events.

After this task, the live map is operator-driven — no hardcoded event id, no dev-only sample data.

## Deliverables

- **`src/data/events.ts`** — TanStack Query hook + types:
  ```ts
  export type EventSummary = {
    id: string;
    name: string;
    slug: string;
    discipline: 'rally' | 'time-trial' | 'regatta' | 'trail-run' | 'hike';
    starts_at: string;
    ends_at: string;
    organization_id: string;
  };

  export function useUserEvents(): UseQueryResult<EventSummary[]>;
  ```
  Fetches `/items/events?fields=id,name,slug,discipline,starts_at,ends_at,organization_id&sort=-starts_at`. Directus's RLS handles "what events does this user have access to" via the cookie. Stale time 5 minutes.
- **`src/ui/components/event-picker.tsx`** — `<EventPicker />` component. Top-of-page dropdown showing the events list. Selected event highlights. On select, calls a callback (passed in by the monitor route).
- **`src/routes/_authed/monitor.tsx`** updated — orchestrates the picker → subscribe → snapshot → store flow:
  ```tsx
  function MonitorPage() {
    const activeEventId = usePositionStore((s) => s.activeEventId);
    const setActiveEvent = useActiveEventOrchestration();
    return (
      <>
        <header className="absolute top-3 left-3 z-10">
          <EventPicker activeEventId={activeEventId} onChange={setActiveEvent} />
        </header>
        <MapView>
          <MapPositions />
          <MapTrails />
          <MapDefaultCamera />
          <MapSelectedDevice />
        </MapView>
        <BasemapSwitcher />
        <ConnectionChip />   {/* 2.9 */}
      </>
    );
  }
  ```
- **`src/live/active-event.ts`** — `useActiveEventOrchestration()` hook that wraps:
  1. Unsubscribe from the previous event's topic if any.
  2. Subscribe to the new event's topic.
  3. On `subscribed`, call `usePositionStore.applySnapshot(eventId, snapshot)`.
  4. On error, surface a toast (or inline alert) — wrong event id, no permission, etc.
  5. Persist the selected event id to localStorage so reload returns to the same event.
- **`src/live/index.ts`** — re-export `useActiveEventOrchestration`.

## Specification

### Filter for "events the user is meaningfully looking at"

The naive query `GET /items/events` returns every event in every org the user belongs to. For a multi-tenant pilot with one org and a handful of events, that's fine — sort by `starts_at DESC` and the most recent shows first.

For a future where the user is in multiple orgs with dozens of past events: filter by date window:

```ts
const oneWeekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
const url = `/api/items/events?filter[ends_at][_gte]=${oneWeekAgo}&fields=...&sort=-starts_at`;
```

Defaults the picker to "events that ended in the last week or are still ongoing." Document the decision; for the dogfood it's overkill but harmless.

### Picker UI

A small dropdown / combobox in the top-left of the monitor page. shadcn's `Popover` + `Command` primitives (or a vanilla `<select>` for v1 — keep it boring).

For v1 a vanilla button + popover list is fine:

```tsx
<button className="...">
  {activeEvent?.name ?? 'Select event'}
  <ChevronDown />
</button>
<Popover>
  <ul>
    {events.map((e) => (
      <li key={e.id} onClick={() => onChange(e.id)}>
        <span>{e.name}</span>
        <span className="text-xs text-muted-foreground">
          {formatDate(e.starts_at)} · {e.discipline}
        </span>
      </li>
    ))}
  </ul>
</Popover>
```

### Active-event orchestration

```ts
export function useActiveEventOrchestration() {
  const setActiveEventInStore = usePositionStore((s) => s.applySnapshot);
  const clearStore = usePositionStore((s) => s.clearForEvent);
  const activeEventId = usePositionStore((s) => s.activeEventId);

  return useCallback(async (eventId: string | null) => {
    const client = getLiveClient();

    // Tear down the previous subscription.
    if (activeEventId) {
      await client.unsubscribe(`event:${activeEventId}`).catch(() => {});
      clearStore();
    }

    if (!eventId) return;

    // Subscribe to the new one.
    const result = await client.subscribe(`event:${eventId}`);
    if (!result.ok) {
      // Surface to UI (toast or inline error).
      console.warn('subscribe failed', result);
      return;
    }
    setActiveEventInStore(eventId, result.snapshot);
    localStorage.setItem('trm-active-event-id', eventId);
  }, [activeEventId, clearStore, setActiveEventInStore]);
}
```

### Auto-select on first mount

```ts
useEffect(() => {
  const saved = localStorage.getItem('trm-active-event-id');
  if (saved && events.some((e) => e.id === saved)) {
    void setActiveEvent(saved);
  } else if (events.length > 0) {
    // Auto-select the most recent.
    void setActiveEvent(events[0].id);
  }
}, [events]);
```

So the user lands on `/monitor` and the picker auto-fills with the last-used event (or the most recent). They can switch via the picker.

### What this task does NOT include

- **Multi-event view.** Subscribing to two events simultaneously isn't supported by v1. The picker is single-select.
- **Event creation / editing.** That's the Directus admin UI's job; the SPA only consumes events.
- **Event-list filtering / search.** Linear list sorted by date is enough for the dogfood. Add search if the list grows past ~20 events.
- **"All events" mode.** No "everything everywhere" view. Always one event at a time.

## Acceptance criteria

- [ ] `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm build` clean.
- [ ] `/monitor` shows the event picker top-left, populated with the user's accessible events.
- [ ] On first visit, the most recent event is auto-selected; markers appear within ~1s as the snapshot arrives.
- [ ] Switching events: the previous event's markers disappear, the new event's markers appear, no leftover state.
- [ ] Reloading the page restores the previously selected event.
- [ ] Selecting an event the user doesn't have permission for surfaces a clear error (the WS returns `error/forbidden`); the picker stays on the previous event.
- [ ] Logging out clears the localStorage-saved event id (handled by Phase 1's logout-clears-cache flow — the event id key follows the same lifecycle).

## Risks / open questions

- **`useUserEvents` and Directus RLS.** Directus filters server-side based on the user's permission policies. Phase 4 of `trm/directus` (permissions) is the gate for "user X sees only events from their orgs." Until then, all authenticated users see all events. Acceptable for dogfood; Phase 4 closes it.
- **Multi-org users.** Picker doesn't group by organization. With one org per pilot user, that's fine. For multi-org users (post-Phase-4), add a sub-header in the picker.
- **Event time window.** Defaulted to "ended in the last week or ongoing." Operators reviewing post-event data more than a week old need to bump the window — defer until they ask.
- **Active-event persistence + logout.** localStorage `trm-active-event-id` survives logout if not explicitly cleared. Update Phase 1's `performLogout` to clear it (or namespace the key under a session-scoped storage key).

## Done

(Filled in when the task lands.)