# Quick Switcher Architecture

## Overview

The Quick Switcher provides a command palette-style interface for rapidly navigating between spaces, rooms, and the library using keyboard shortcuts (Cmd+K on macOS, Ctrl+K on Windows/Linux).

## Design Principles

1. **Extensible**: Built to easily support new navigation targets and actions
2. **Keyboard-first**: Optimized for keyboard navigation with fuzzy search
3. **Context-aware**: Shows relevant options based on current location
4. **Performance**: Uses virtualized rendering for large result sets
5. **Accessible**: ARIA-compliant with screen reader support

## Technology Stack

- **cmdk**: A command menu component library by Paco Coursey, used by Linear, Vercel, and others
  - Provides keyboard navigation, fuzzy search, and grouping
  - Built on top of Radix UI primitives
  - Handles focus management and accessibility

## Architecture

### Component Structure

```
QuickSwitcher (components/QuickSwitcher.tsx)
├── Command (from cmdk)
│   ├── Command.Input (search input)
│   ├── Command.List (scrollable results)
│   │   ├── Command.Empty (no results state)
│   │   ├── Command.Group (Spaces)
│   │   ├── Command.Group (Rooms in current space)
│   │   └── Command.Group (Library)
│   └── Command.Item (individual results)
```

### Data Sources

The switcher queries:
- `api.spaces.list` - All spaces user has access to
- `api.rooms.list` - Rooms in the current space (when in a space)
- `api.atoms.listUserAtoms` - User's library items (future)

### Navigation Actions

1. **Go to Space**: Navigate to a space's first room
2. **Go to Room**: Navigate to a specific room in current space
3. **Go to Library**: Navigate to user's library/dashboard

### State Management

- **Open/Close state**: Managed via React state in parent component
- **Keyboard handling**: Global event listener for Cmd/Ctrl+K
- **Search**: Handled internally by cmdk with fuzzy matching

## Usage

### Integration Points

1. **SpacePage** (`/app/space/[id]/page.tsx`):
   - Shows spaces + rooms in current space
   - Navigates between rooms in same space

2. **DashboardPage** (`/app/dashboard/page.tsx`):
   - Shows spaces + library
   - Navigates to spaces

### Keyboard Shortcuts

- `Cmd+K` / `Ctrl+K`: Open quick switcher
- `Escape`: Close quick switcher
- `↑` / `↓`: Navigate results
- `Enter`: Select result
- Type to filter results with fuzzy search

## Future Extensibility

The architecture supports easy addition of:

1. **Actions**: Beyond navigation (create room, invite member, etc.)
2. **Filters**: Filter by room type, space ownership, etc.
3. **Recent items**: Show recently visited spaces/rooms
4. **Custom commands**: User-defined shortcuts
5. **Global search**: Search messages, atoms, members

### Adding New Categories

To add a new category:

1. Add new `Command.Group` in QuickSwitcher component
2. Query data source using Convex hooks
3. Add navigation handler in `onSelect` callback
4. Add appropriate icon and metadata

Example:
```tsx
<Command.Group heading="Members">
  {members?.map((member) => (
    <Command.Item
      key={member._id}
      value={`member-${member.profile?.displayName}`}
      onSelect={() => {/* Navigate to member profile */}}
    >
      <User className="w-4 h-4 mr-2" />
      {member.profile?.displayName}
    </Command.Item>
  ))}
</Command.Group>
```

## Styling

Uses Tailwind CSS with:
- Backdrop blur for glassmorphism effect
- Dark mode support
- Smooth transitions
- Focus indicators for accessibility

## Performance Considerations

- Debounced search (handled by cmdk)
- Limited to 50 results per category by default
- Virtualized scrolling for large lists (cmdk feature)
- Lazy loading of atom data