# Support Components

This folder contains support widgets for capturing user feedback, bug reports, error reports, contact requests, and resolution surveys. These components are designed to give AI agents maximum context for providing world-class support.

## Component Overview

| Component | Purpose | Key Data |
|-----------|---------|----------|
| **Feedback** | Quick sentiment capture | Sentiment (5-point scale), optional message |
| **Contact** | Contact form with topics | Name, email, topic, message |
| **BugReport** | Structured bug reporting | Title, expected/actual behavior, severity, steps |
| **ErrorReport** | Technical error capture | Description, severity, error details (code, message, stack) |
| **Resolution** | Post-support satisfaction | Resolution status, satisfaction rating (1-5), feedback |

## Common Patterns

### Props Structure
All support components share these props:
- `variant`: `"modal"` | `"popover"` (default: `"modal"`)
- `side`: `"top"` | `"bottom"` | `"left"` | `"right"` (popover position)
- `user`: `{ id?, email?, name? }` - User attribution
- `context`: `Record<string, unknown>` - App-specific context
- `captureMetadata`: `boolean` - Auto-capture URL, timestamp, viewport, userAgent
- `onSubmit`: Callback function
- `apiEndpoint`: Alternative to onSubmit for direct POST

### Auto-Captured Metadata
When `captureMetadata={true}` (default), all components capture:
- `url`: Current page URL
- `timestamp`: ISO 8601 timestamp
- `viewport`: `{ width, height }`
- `userAgent`: Browser user agent string

**Contact component captures additional metadata:**
- `referrer`: Previous page URL
- `pageTitle`: Current page title
- `timeOnPage`: Milliseconds since page load
- `locale`: Browser locale (`navigator.language`)
- `timezone`: User's timezone
- `screenResolution`: Full screen dimensions

**Contact session tracking props** (pass to include in metadata):
- `sessionId`: Unique session identifier for correlation
- `correlationId`: Link to specific flows/conversations
- `appVersion`: Application version for debugging
- `environment`: production, staging, development

### File Structure
Each component follows this structure:
```
component-name/
├── types.ts           # TypeScript interfaces
├── component-trigger.tsx   # Trigger button
├── component-content.tsx   # Form content
├── component.tsx      # Main component (modal/popover wrapper)
├── component.stories.tsx   # Storybook stories
└── index.ts           # Exports
```

## Component Details

### Feedback
**Use for:** Quick satisfaction capture, AI response ratings, feature feedback

```tsx
<Feedback
  variant="popover"
  side="top"
  user={{ id: "user-123", email: "user@example.com" }}
  context={{ conversationId: "conv-456" }}
  onSubmit={(data) => console.log(data)}
/>
```

**Sentiment values:** `very-dissatisfied`, `dissatisfied`, `neutral`, `satisfied`, `very-satisfied`

### Contact
**Use for:** General inquiries, sales requests, support tickets

```tsx
<Contact
  variant="modal"
  topics={["Sales", "Support", "Partnership", "Other"]}
  showCompanyName={true}
  showCompanySize={true}
  rows={[
    ["name", "email"],
    ["companyName", "companySize"],
    ["topic"],
    ["message"]
  ]}
  user={{ id: "user-123", name: "Jane", email: "jane@example.com" }}
  sessionId="session-abc"
  correlationId="conversation-123"
  appVersion="1.2.0"
  environment="production"
  onSubmit={(data) => console.log(data)}
/>
```

**Business fields:** `companyName`, `companySize`, `additionalInfo` (use show/require props)

**Layout:** Use `rows` prop to arrange fields in grid layout (e.g., `[["name", "email"]]` for side-by-side)

### BugReport
**Use for:** User-reported bugs with expected vs actual behavior

```tsx
<BugReport
  variant="modal"
  showStepsToReproduce={true}
  showWorkedBefore={true}
  context={{ featureName: "data-export" }}
  onSubmit={(data) => console.log(data)}
/>
```

**Severity values:** `cosmetic`, `minor`, `major`, `critical`

### ErrorReport
**Use for:** Technical errors, often triggered from error boundaries

```tsx
<ErrorReport
  variant="modal"
  showSeverity={true}
  errorDetails={{
    message: "Cannot read property 'map' of undefined",
    code: "TypeError",
    stack: "..."
  }}
  onSubmit={(data) => console.log(data)}
/>
```

**Severity values:** `low`, `medium`, `high`, `critical`

### Resolution
**Use for:** Post-support satisfaction surveys

```tsx
<Resolution
  variant="modal"
  ticketId="TICKET-12345"
  showFollowUp={true}
  onSubmit={(data) => console.log(data)}
/>
```

**Resolution status:** `yes`, `partially`, `no`
**Satisfaction rating:** `1`, `2`, `3`, `4`, `5`

## Unified Activity Table

`SupportActivityTable` displays all support items in one unified feed for agent dashboards:

```tsx
<SupportActivityTable className="my-4" />
```

Columns: Type, Status, Summary, User, Page, Device, Date

## Agent Integration

### Data Correlation
Agents can correlate support data across submissions using:
- `user.id` / `user.email` - Match user across submissions
- `context` - App-specific identifiers (conversationId, sessionId, etc.)
- `metadata.url` - Page where submission occurred
- `metadata.timestamp` - Temporal correlation

### Triage Logic
| Type | Priority Signal | Routing |
|------|-----------------|---------|
| Feedback | `very-dissatisfied` | Escalate to support |
| Contact | Topic = "Support" | Support queue |
| BugReport | `severity: critical` | Engineering escalation |
| ErrorReport | `severity: critical/high` | On-call engineering |
| Resolution | `resolved: no` + `wantsFollowUp: true` | Re-open ticket |

### Example Agent Workflow
```typescript
// Handle negative feedback
if (feedback.sentiment === 'very-dissatisfied' || feedback.sentiment === 'dissatisfied') {
  // Check for existing user context
  const userHistory = await getUserHistory(feedback.user?.email)

  // Correlate with recent errors
  const recentErrors = await getRecentErrors(feedback.metadata?.url)

  // Generate response with full context
  await createSupportTicket({
    priority: 'high',
    context: { feedback, userHistory, recentErrors }
  })
}
```

## Theme Variables

All components use theme variables for consistent styling:
- Borders: `border-border`, `border-destructive` (errors)
- Text: `text-foreground`, `text-muted-foreground`
- Backgrounds: `bg-background`, `bg-muted`, `bg-primary/10`
- Badge variants: `default`, `secondary`, `destructive`, `warning`, `outline`

## Widths

| Component | Modal | Popover |
|-----------|-------|---------|
| Feedback | 480px | 400px |
| Contact | 480px | 400px |
| BugReport | 520px | 440px |
| ErrorReport | 520px | 440px |
| Resolution | 480px | 440px |