78f19cde7d
- Canvas: Infinite zoomable workspace with LOD and navigation - Spotlight: Fuzzy search with type filters and view shortcuts - Krate: Window group container with non-overlapping placement - Detail Window: YAML/Describe/Logs/Shell views with maximize - Top Bar: Cluster info, user presence, admin toggle - Admin Drawer: Multi-user presence and spectate functionality - Minimap: Browse and navigate canvas overview - Collection Window: List/tree views with filtering and sorting - Shell/Logs: Real-time terminal and log streaming - Backend: Go service with K8s API, WebSocket handlers, CRDT sync - Architecture: Full project structure and tech stack
138 lines
4.5 KiB
Markdown
138 lines
4.5 KiB
Markdown
# Spotlight Search Feature Specification
|
||
|
||
## Overview
|
||
The spotlight is the global search overlay that allows users to find any Kubernetes object or existing krate. It provides fuzzy-ranked search results with quick view shortcuts.
|
||
|
||
## Core Responsibilities
|
||
- Display search results ranked by fuzzy matching
|
||
- Support typed filters (Tab to cycle through types)
|
||
- Provide view shortcuts (Logs, Shell, Describe, YAML)
|
||
- Auto-close after keyboard idle and open selected object
|
||
|
||
## UI Components
|
||
|
||
### Layout
|
||
- Full-screen backdrop: `rgba(7,9,13,.55)`, `backdrop-filter: blur(2px)`
|
||
- Search panel: `width: min(660px, 93vw)`, `top: 15%`, centered horizontally
|
||
- Panel: `background: rgba(16,20,28,.97)`, `border: 1px solid rgba(140,165,200,.26)`, `border-radius: 14px`
|
||
|
||
### Sections (top→bottom)
|
||
1. **Input row** (~52px):
|
||
- `⌕` glyph (accent color)
|
||
- Optional type-filter pill
|
||
- Input field (`font-size: 18px`, IBM Plex Sans)
|
||
- Optional Tab ghost hint
|
||
|
||
2. **Type chips row** (scrollable):
|
||
- All / deploy / svc / pods / secrets / config / sts / crd / namespace / ns
|
||
- Scrollable horizontally on small screens
|
||
- Shows selected filter as pill
|
||
|
||
3. **Results list** (`max-height: 48vh, overflow: auto`):
|
||
- Each row: shape glyph + name + subtext (type · ns/namespace) + CRD badge + type badge
|
||
- Selected row highlight: accent background
|
||
- Scrollbar styled (8px, rgba(140,165,200,.18))
|
||
|
||
4. **View chips** (expanded on selected row only):
|
||
- `⌥L logs · ⌥S shell · ⌥D describe · ⌥Y yaml`
|
||
- Only available views shown (YAML and Describe always shown; Logs and Shell for pods/deployments/daemonsets/statefulsets)
|
||
- Click to open that view for selected result
|
||
|
||
5. **Footer**:
|
||
- `↑↓ pick · ⌥L/S/D/Y open views · ⏎ open default · ⇥ filter type · esc done`
|
||
|
||
## Fuzzy Search Algorithm
|
||
|
||
### Scoring Formula
|
||
```
|
||
Score = character-match score × 10 + type boost
|
||
```
|
||
|
||
### Type Boosts
|
||
- CRD: 60
|
||
- Deployment: 50
|
||
- StatefulSet: 48
|
||
- Service: 46
|
||
- DaemonSet: 44
|
||
- Ingress: 42
|
||
- Secret: 24
|
||
- ConfigMap: 22
|
||
- PVC: 18
|
||
- Pod: 16
|
||
|
||
### Character Matching
|
||
- Sequential character match
|
||
- Bonus for consecutive matches: +3
|
||
- Bonus for word-boundary starts: +5
|
||
|
||
### Results
|
||
- Capped at 8 results
|
||
- Debounce: 16ms (one animation frame) for performance with large datasets
|
||
|
||
## Type Filter
|
||
|
||
### Tab Quick-Filter
|
||
- Typing type alias (e.g., `pod`, `svc`) shows ghost hint: `⇥ Pods`
|
||
- Tab locks filter as pill
|
||
- Backspace removes filter (only when empty query and filter active)
|
||
- Tab cycles through type filters (most-recently-opened first)
|
||
|
||
## View Shortcuts
|
||
|
||
### Key Mapping
|
||
All use **⌥ (Alt/Option)**, NOT Ctrl (reserved for terminal):
|
||
- `⌥L` = logs
|
||
- `⌥S` = shell
|
||
- `⌥D` = describe
|
||
- `⌥Y` = yaml
|
||
|
||
### Implementation
|
||
- Use `event.code` (layout-safe, e.g., `KeyL`), not `event.key`
|
||
- Multiple views can be opened before closing spotlight
|
||
- Views stack as windows in one krate
|
||
|
||
## Keyboard Navigation
|
||
|
||
| Key | Context | Action |
|
||
|---|---|---|
|
||
| ↑ / ↓ | Spotlight | Navigate results |
|
||
| Tab | Spotlight | Apply type filter / cycle filters |
|
||
| Backspace | Spotlight (empty query, filter active) | Clear type filter |
|
||
| Enter | Spotlight (result selected) | Open default view + close |
|
||
| ⌥L/S/D/Y | Spotlight | Open that view for selected result |
|
||
| Esc | Spotlight | Close spotlight |
|
||
|
||
## Auto-Close Behavior
|
||
- After 500ms of keyboard idle (no more keypresses)
|
||
- Spotlight closes automatically
|
||
- Camera flies to the newly created krate
|
||
- Debounce timer resets on each keypress
|
||
|
||
## Search Results Include
|
||
- **Existing krates** (jump to working set, camera flies there)
|
||
- **Namespace results** (`ns/payments`) → opens collection window
|
||
- **Category results** (`All Pods`, `All Services`) → opens collection window
|
||
- **Kubernetes objects**: pods, deployments, services, secrets, configmaps, etc.
|
||
|
||
## State
|
||
```typescript
|
||
interface SpotlightState {
|
||
open: boolean;
|
||
query: string;
|
||
filterType: string | null;
|
||
sel: number; // selected result index
|
||
navigated: boolean; // true after ↑/↓ press
|
||
session: { // tracks views opened before closing
|
||
kid: string;
|
||
objId: string;
|
||
views: string[];
|
||
} | null;
|
||
}
|
||
```
|
||
|
||
## Gotchas
|
||
1. **Fuzzy search speed**: For real clusters with thousands of objects, debounce by 16ms or run in Web Worker
|
||
2. **View shortcuts**: Must use `event.code` for layout safety across OS/keyboard layouts
|
||
3. **Auto-close timer**: Reset on each keypress, don't close during active typing
|
||
4. **Pre-seeding**: All printable characters (not just letters) should pre-seed spotlight
|