feat(component): ScopeSelector — Multi-Level Scope Picker

[bntvllnt]

Summary

Dropdown selector for choosing a viewing scope across a hierarchy: personal → workspace/team → project. Each level shows contextual icon and label. Used to scope analytics, usage, or settings views to a specific organizational level. A generic pattern for any multi-tenant or workspace-based product.

Proposed API

type Scope =
  | { type: "personal" }
  | { type: "workspace"; workspaceId: string }
  | { type: "project"; workspaceId: string; projectId: string }

<ScopeSelector
  value={scope}
  onChange={setScope}
  scopes={{
    personal: { label: "Personal", icon: User },
    workspaces: workspaces.map(ws => ({
      id: ws.id, label: ws.name, icon: Building2,
    })),
    projects: projects.map(p => ({
      id: p.id, label: p.name, icon: Folder, parentId: p.workspaceId,
    })),
  }}
/>

Requirements

• Three scope levels: personal, workspace, project (configurable labels)
• Discriminated union value type for type-safe scope handling
• Dropdown trigger: icon + label + chevron, compact button style
• Grouped menu sections: personal item, then workspace group, then project group
• Projects filtered by selected workspace (cascading selection)
• Section headers/labels for each group
• Icons per scope level (customizable)
• Truncation on long workspace/project names (max-width)
• Empty state when no workspaces: "No team workspaces yet"
• Controlled component: value + onChange
• Dark mode: standard dropdown styling
• Accessible: dropdown menu with labeled groups, keyboard navigable

Layout

┌──────────────────────────────────────────────────┐
│  Trigger: [👤 Personal ▾]                        │
│                                                  │
│  Dropdown:                                       │
│  ┌────────────────────────────────────────────┐  │
│  │ View usage by                              │  │
│  │ ─────────────                              │  │
│  │ 👤 Personal                                │  │
│  │ ─────────────                              │  │
│  │ Workspaces                                 │  │
│  │ 🏢 Acme Corp                               │  │
│  │ 🏢 Side Project                             │  │
│  │ ─────────────                              │  │
│  │ Projects (in selected workspace)           │  │
│  │ 📁 AI OS                                   │  │
│  │ 📁 Marketing Site                          │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Use Cases

• Analytics dashboard scope filter (personal/team/project)
• Settings page scope selector
• Billing page cost attribution view
• Permission management scope picker
• Audit log filter by organizational level

Composes

• DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, Button

Origin

Extracted from UsageScopeSelector in apps/web-ai-os/app/account/usage/components/usage-scope-selector.tsx in vllnt/vllnt monorepo.