Paperclip Component Index

Complete inventory of all UI components. Update this file when adding new reusable components.

---

Table of Contents

1. shadcn/ui Primitives
2. Custom Components
3. Layout Components
4. Dialog & Form Components
5. Property Panel Components
6. Agent Configuration
7. Utilities & Hooks

---

shadcn/ui Primitives

Location: ui/src/components/ui/

These are shadcn/ui base components. Do not modify directly — extend via composition.

---

Custom Components

Location: ui/src/components/

StatusBadge

File: StatusBadge.tsx Props: status: string Usage: Colored pill showing entity status. Supports 20+ statuses with mapped colors.

<StatusBadge status="in_progress" />

Use for displaying status in properties panels, entity rows, and list views. Never hardcode status colors — always use this component.

StatusIcon

File: StatusIcon.tsx Props: status: string, onChange?: (status: string) => void Usage: Circle icon representing issue status. When onChange provided, opens a popover picker.

<StatusIcon status="todo" onChange={setStatus} />

Supports: backlog, todo, in_progress, in_review, done, cancelled, blocked. Use in entity row leading slots and grouped list headers.

PriorityIcon

File: PriorityIcon.tsx Props: priority: string, onChange?: (priority: string) => void Usage: Priority indicator icon. Interactive when onChange provided.

<PriorityIcon priority="high" onChange={setPriority} />

Supports: critical, high, medium, low. Use alongside StatusIcon in entity row leading slots.

EntityRow

File: EntityRow.tsx Props: leading, identifier, title, subtitle?, trailing?, onClick?, selected? Usage: Standard list row for issues, agents, projects. Supports hover highlight and selected state.

<EntityRow
  leading={<><StatusIcon status="todo" /><PriorityIcon priority="medium" /></>}
  identifier="PAP-003"
  title="Write API documentation"
  trailing={<StatusBadge status="todo" />}
  onClick={() => navigate(`/issues/${id}`)}
/>

Wrap multiple EntityRows in a border border-border rounded-md container.

MetricCard

File: MetricCard.tsx Props: icon: LucideIcon, value: string | number, label: string, description?: string Usage: Dashboard stat card with icon, large value, label, and optional description.

<MetricCard icon={Bot} value={12} label="Active Agents" description="+3 this week" />

Always use in a responsive grid: grid md:grid-cols-2 xl:grid-cols-4 gap-4.

EmptyState

File: EmptyState.tsx Props: icon: LucideIcon, message: string, action?: string, onAction?: () => void Usage: Empty list placeholder with icon, message, and optional CTA button.

<EmptyState icon={Inbox} message="No items yet." action="Create Item" onAction={handleCreate} />

FilterBar

File: FilterBar.tsx Props: filters: FilterValue[], onRemove: (key) => void, onClear: () => void Type: FilterValue = { key: string; label: string; value: string } Usage: Filter chip display with remove buttons and clear all.

<FilterBar filters={filters} onRemove={handleRemove} onClear={() => setFilters([])} />

Identity

File: Identity.tsx Props: name: string, avatarUrl?: string, initials?: string, size?: "sm" | "default" | "lg" Usage: Avatar + name display for users and agents. Derives initials from name automatically. Three sizes matching Avatar sizes.

<Identity name="Agent Alpha" size="sm" />
<Identity name="CEO Agent" />
<Identity name="Backend Service" size="lg" avatarUrl="/img/bot.png" />

Use in property rows, comment headers, assignee displays, and anywhere a user/agent reference is shown.

InlineEditor

File: InlineEditor.tsx Props: value: string, onSave: (val: string) => void, as?: string, className?: string Usage: Click-to-edit text. Renders as display text, clicking enters edit mode. Enter saves, Escape cancels.

<InlineEditor value={title} onSave={updateTitle} as="h2" className="text-xl font-bold" />

PageSkeleton

File: PageSkeleton.tsx Props: variant: "list" | "detail" Usage: Full-page loading skeleton matching list or detail layout.

<PageSkeleton variant="list" />

CommentThread

File: CommentThread.tsx Usage: Comment list with add-comment form. Used on issue and entity detail views.

GoalTree

File: GoalTree.tsx Usage: Hierarchical goal tree with expand/collapse. Used on the goals page.

CompanySwitcher

File: CompanySwitcher.tsx Usage: Company selector dropdown in sidebar header.

---

Layout Components

Layout

File: Layout.tsx Usage: Main app shell. Three-zone layout: Sidebar + Main content + Properties panel. Wraps all routes.

Sidebar

File: Sidebar.tsx Usage: Left navigation sidebar (w-60). Contains CompanySwitcher, search button, new issue button, and SidebarSections.

SidebarSection

File: SidebarSection.tsx Usage: Collapsible sidebar group with header label and chevron toggle.

SidebarNavItem

File: SidebarNavItem.tsx Props: Icon, label, optional badge count Usage: Individual nav item within a SidebarSection.

BreadcrumbBar

File: BreadcrumbBar.tsx Usage: Top breadcrumb navigation spanning main content + properties panel.

PropertiesPanel

File: PropertiesPanel.tsx Usage: Right-side properties panel (w-80). Closeable. Shown on detail views.

CommandPalette

File: CommandPalette.tsx Usage: Cmd+K global search modal. Searches issues, projects, agents.

---

Dialog & Form Components

NewIssueDialog

File: NewIssueDialog.tsx Usage: Create new issue with project/assignee/priority selection. Supports draft saving.

NewProjectDialog

File: NewProjectDialog.tsx Usage: Create new project dialog.

NewAgentDialog

File: NewAgentDialog.tsx Usage: Create new agent dialog.

OnboardingWizard

File: OnboardingWizard.tsx Usage: Multi-step onboarding flow for new users/companies.

---

Property Panel Components

These render inside the PropertiesPanel for different entity types:

All follow the property row pattern: text-xs text-muted-foreground label on left, value on right, py-1.5 spacing.

---

Agent Configuration

agent-config-primitives

File: agent-config-primitives.tsx Exports: Field, ToggleField, ToggleWithNumber, CollapsibleSection, AutoExpandTextarea, DraftInput Usage: Reusable form field primitives for agent configuration forms.

AgentConfigForm

File: AgentConfigForm.tsx Usage: Full agent creation/editing form with adapter type selection.

---

Utilities & Hooks

cn() — Class Name Merger

File: ui/src/lib/utils.ts Usage: Merges class names with clsx + tailwind-merge. Use in every component.

import { cn } from "@/lib/utils";
<div className={cn("base-classes", conditional && "extra", className)} />

Formatting Utilities

File: ui/src/lib/utils.ts

useKeyboardShortcuts

File: ui/src/hooks/useKeyboardShortcuts.ts Usage: Global keyboard shortcut handler. Registers Cmd+K, C, [, ], Cmd+Enter.

Query Keys

File: ui/src/lib/queryKeys.ts Usage: Structured React Query key factories for cache management.

groupBy

File: ui/src/lib/groupBy.ts Usage: Generic array grouping utility.