016-3: Session UI - SessionStatus + PhaseProgress Components

[frankbria]

Part of #197 - Planning Phase Automation

Scope

This issue covers the frontend components that display session context and phase progress.

Tasks

1. Fix SessionStatus Component (~1h)

• Update web-ui/src/components/SessionStatus.tsx
• Connect to GET /api/projects/:id/session endpoint
• Remove placeholder "Starting new session..." text
• Display:
  • Last session summary
  • Time ago (e.g., "2 hours ago")
  • Next actions list
  • Progress percentage
  • Active blocker count
• Handle loading and error states
• Auto-refresh every 30 seconds

2. Create PhaseProgress Component (~1.5h)

• Create web-ui/src/components/PhaseProgress.tsx
• Display current phase with icon
• Show step X of Y within phase
• Progress bar visualization
• Next action hint
• Phase-specific styling (colors per phase)
• Replace old "RUNNING Phase: planning (Step 1/15)" display

Phase icons:

• discovery: 🔍
• planning: 📋
• development: 🔨
• review: ✅
• complete: 🎉
• shipped: 🚀

Acceptance Criteria

• SessionStatus shows real data from API
• No placeholder text visible
• PhaseProgress shows correct phase and steps
• Step counter resets appropriately per phase
• Components handle loading/error states gracefully

Dependencies

• Requires: 016-1 (session endpoint)

Blocks

• 016-5: TaskReview Component - Task Approval UI #202 (016-6: Integration)

Files

• web-ui/src/components/SessionStatus.tsx (modify)
• web-ui/src/components/PhaseProgress.tsx (new)
• web-ui/__tests__/SessionStatus.test.tsx (modify)
• web-ui/__tests__/PhaseProgress.test.tsx (new)

Effort

~2.5 hours

[traycerai]

Plan

Observations

The codebase already has a functional SessionStatus component that connects to the session endpoint and displays session data with auto-refresh. However, it contains placeholder text for new sessions that needs removal. The Dashboard component currently displays phase information as plain text (Phase: {projectData.phase} (Step {projectData.workflow_step}/15)) which needs to be replaced with a new PhaseProgress component. Existing components like ProgressBar, PhaseIndicator, and DiscoveryProgress provide good patterns for styling, progress visualization, and API integration.

Approach

The implementation focuses on two main tasks: (1) removing the placeholder text from SessionStatus to display only real session data, and (2) creating a new PhaseProgress component that visualizes the current phase with icons, step counters, progress bars, and phase-specific styling. The new component will integrate seamlessly into the Dashboard by replacing the existing plain text phase display. Both components will follow established patterns from existing components for consistency in styling, error handling, and testing.

Implementation Steps

1. Fix SessionStatus Component

File: file:web-ui/src/components/SessionStatus.tsx

Changes Required:

• Remove the conditional rendering for new sessions (lines 94-100)
• Remove the isNewSession check (line 83)
• Always display the full session information (last session, next actions, progress, blockers)
• When session.last_session.summary === 'No previous session', display it as a regular session summary instead of special placeholder text

Specific Updates:

• Delete lines 83-84 (isNewSession check)
• Delete lines 94-100 (new session placeholder rendering)
• Ensure the main session display (lines 102-163) renders for all cases
• The component already handles loading and error states correctly (lines 54-76)

2. Create PhaseProgress Component

File: file:web-ui/src/components/PhaseProgress.tsx (new file)

Component Structure:

PhaseProgress Component
├── Props Interface
│   ├── phase: string (discovery, planning, development, review, complete, shipped)
│   ├── currentStep: number
│   ├── totalSteps: number
│   └── nextAction?: string (optional hint)
├── Phase Configuration Map
│   ├── Phase icons (🔍, 📋, 🔨, ✅, 🎉, 🚀)
│   ├── Phase colors (bg/text/border)
│   └── Phase labels
└── Render Structure
    ├── Phase header (icon + label)
    ├── Step counter (Step X of Y)
    ├── Progress bar (reuse ProgressBar component)
    └── Next action hint (if provided)

Phase Configuration:

• discovery: Icon 🔍, Blue theme (bg-blue-100, text-blue-800, border-blue-300)
• planning: Icon 📋, Purple theme (bg-purple-100, text-purple-800, border-purple-300)
• development: Icon 🔨, Green theme (bg-green-100, text-green-800, border-green-300)
• review: Icon ✅, Yellow theme (bg-yellow-100, text-yellow-800, border-yellow-300)
• complete: Icon 🎉, Gray theme (bg-gray-100, text-gray-800, border-gray-300)
• shipped: Icon 🚀, Indigo theme (bg-indigo-100, text-indigo-800, border-indigo-300)

Implementation Details:

• Use TypeScript with proper type definitions
• Import and reuse ProgressBar component from file:web-ui/src/components/ProgressBar.tsx
• Calculate progress percentage: (currentStep / totalSteps) * 100
• Handle edge cases: step 0, step > totalSteps, missing nextAction
• Add data-testid attributes for testing: phase-progress, phase-icon, step-counter, next-action-hint
• Follow the styling patterns from PhaseIndicator and DiscoveryProgress

Visual Layout:

┌─────────────────────────────────────────────┐
│ 🔨 Development Phase                        │
│                                             │
│ Step 5 of 15                                │
│ ████████████░░░░░░░░░░░░░░░░░░░░ 33%       │
│                                             │
│ 💡 Next: Implement user authentication      │
└─────────────────────────────────────────────┘

3. Integrate PhaseProgress into Dashboard

File: file:web-ui/src/components/Dashboard.tsx

Changes Required:

• Import the new PhaseProgress component at the top (line ~30)
• Replace lines 283-285 (current phase display) with PhaseProgress component
• Map backend phase names to component phase names:
  • active → development
  • Keep others as-is (discovery, planning, review, complete)
  • Handle shipped if backend adds it in the future

Integration Code Location:

• Current location: Lines 279-298 (header section)
• Replace the <span> element at lines 283-285
• Pass props: phase={mappedPhase}, currentStep={projectData.workflow_step}, totalSteps={15}
• Optional: Pass nextAction if available from project data

Phase Mapping Logic:

const mappedPhase = projectData.phase === 'active' ? 'development' : projectData.phase;

4. Update SessionStatus Tests

File: file:web-ui/__tests__/components/SessionStatus.test.tsx

Test Updates Required:

• Update "new session state" tests (lines 89-125) to expect regular session display instead of placeholder
• Remove assertions for "🚀 Starting new session..." text
• Add assertions that "No previous session" summary is displayed as regular text
• Ensure all existing tests for loading, error, and existing session states still pass
• Verify auto-refresh behavior remains unchanged

Specific Test Changes:

• Lines 104-105: Change expectation from placeholder to regular summary display
• Lines 122-123: Update to verify "No previous session" appears in summary section
• Keep all other tests unchanged (they test correct functionality)

5. Create PhaseProgress Tests

File: file:web-ui/__tests__/PhaseProgress.test.tsx (new file)

Test Coverage:

Rendering Tests:

• Renders correct icon for each phase (discovery, planning, development, review, complete, shipped)
• Displays correct phase label
• Shows step counter in format "Step X of Y"
• Renders progress bar with correct percentage
• Displays next action hint when provided
• Hides next action hint when not provided

Phase-Specific Styling Tests:

• Each phase has correct background color class
• Each phase has correct text color class
• Each phase has correct border color class

Edge Cases:

• Handles step 0 correctly
• Handles step > totalSteps (caps at 100%)
• Handles missing/undefined nextAction
• Handles unknown phase (fallback to default styling)

Accessibility Tests:

• Has proper ARIA labels
• Progress bar has role="progressbar"
• Semantic HTML structure

Example Test Structure:

describe('PhaseProgress', () => {
  describe('phase icons', () => {
    it('displays 🔍 for discovery phase', () => { ... });
    it('displays 📋 for planning phase', () => { ... });
    // ... etc
  });
  
  describe('step counter', () => {
    it('displays "Step 5 of 15"', () => { ... });
    it('resets appropriately per phase', () => { ... });
  });
  
  describe('progress bar', () => {
    it('shows correct percentage', () => { ... });
    it('caps at 100% when step exceeds total', () => { ... });
  });
  
  describe('phase-specific styling', () => {
    it('applies blue theme for discovery', () => { ... });
    // ... etc
  });
});

6. Update Dashboard Tests

File: file:web-ui/__tests__/components/Dashboard.test.tsx

Test Updates:

• Update tests that check for phase display text
• Replace assertions for "Phase: planning (Step 1/15)" with PhaseProgress component checks
• Verify PhaseProgress receives correct props from Dashboard
• Ensure phase mapping logic works correctly (active → development)

Component Diagram

sequenceDiagram
    participant D as Dashboard
    participant SS as SessionStatus
    participant PP as PhaseProgress
    participant API as Backend API
    
    D->>SS: Render with projectId
    SS->>API: GET /api/projects/:id/session
    API-->>SS: Session data
    SS->>SS: Display session info (no placeholder)
    
    D->>PP: Render with phase, step, total
    PP->>PP: Map phase to icon/colors
    PP->>PP: Calculate progress %
    PP->>PP: Render phase UI
    
    Note over SS: Auto-refresh every 30s
    SS->>API: GET /api/projects/:id/session
    API-->>SS: Updated session data

Loading

File Summary

Files to Modify:

• file:web-ui/src/components/SessionStatus.tsx - Remove placeholder text
• file:web-ui/src/components/Dashboard.tsx - Integrate PhaseProgress component
• file:web-ui/__tests__/components/SessionStatus.test.tsx - Update tests

Files to Create:

• file:web-ui/src/components/PhaseProgress.tsx - New component
• file:web-ui/__tests__/PhaseProgress.test.tsx - New test file

Dependencies:

• Reuse ProgressBar from file:web-ui/src/components/ProgressBar.tsx
• Follow patterns from PhaseIndicator (file:web-ui/src/components/PhaseIndicator.tsx)
• Use authFetch from file:web-ui/src/lib/api-client.ts (already used in SessionStatus)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase already has a functional `SessionStatus` component that connects to the session endpoint and displays session data with auto-refresh. However, it contains placeholder text for new sessions that needs removal. The `Dashboard` component currently displays phase information as plain text (`Phase: {projectData.phase} (Step {projectData.workflow_step}/15)`) which needs to be replaced with a new `PhaseProgress` component. Existing components like `ProgressBar`, `PhaseIndicator`, and `DiscoveryProgress` provide good patterns for styling, progress visualization, and API integration.

## Approach

The implementation focuses on two main tasks: (1) removing the placeholder text from `SessionStatus` to display only real session data, and (2) creating a new `PhaseProgress` component that visualizes the current phase with icons, step counters, progress bars, and phase-specific styling. The new component will integrate seamlessly into the Dashboard by replacing the existing plain text phase display. Both components will follow established patterns from existing components for consistency in styling, error handling, and testing.

## Implementation Steps

### 1. Fix SessionStatus Component

**File:** `file:web-ui/src/components/SessionStatus.tsx`

**Changes Required:**
- Remove the conditional rendering for new sessions (lines 94-100)
- Remove the `isNewSession` check (line 83)
- Always display the full session information (last session, next actions, progress, blockers)
- When `session.last_session.summary === 'No previous session'`, display it as a regular session summary instead of special placeholder text

**Specific Updates:**
- Delete lines 83-84 (isNewSession check)
- Delete lines 94-100 (new session placeholder rendering)
- Ensure the main session display (lines 102-163) renders for all cases
- The component already handles loading and error states correctly (lines 54-76)

### 2. Create PhaseProgress Component

**File:** `file:web-ui/src/components/PhaseProgress.tsx` (new file)

**Component Structure:**

```
PhaseProgress Component
├── Props Interface
│   ├── phase: string (discovery, planning, development, review, complete, shipped)
│   ├── currentStep: number
│   ├── totalSteps: number
│   └── nextAction?: string (optional hint)
├── Phase Configuration Map
│   ├── Phase icons (🔍, 📋, 🔨, ✅, 🎉, 🚀)
│   ├── Phase colors (bg/text/border)
│   └── Phase labels
└── Render Structure
    ├── Phase header (icon + label)
    ├── Step counter (Step X of Y)
    ├── Progress bar (reuse ProgressBar component)
    └── Next action hint (if provided)
```

**Phase Configuration:**
- **discovery**: Icon 🔍, Blue theme (`bg-blue-100`, `text-blue-800`, `border-blue-300`)
- **planning**: Icon 📋, Purple theme (`bg-purple-100`, `text-purple-800`, `border-purple-300`)
- **development**: Icon 🔨, Green theme (`bg-green-100`, `text-green-800`, `border-green-300`)
- **review**: Icon ✅, Yellow theme (`bg-yellow-100`, `text-yellow-800`, `border-yellow-300`)
- **complete**: Icon 🎉, Gray theme (`bg-gray-100`, `text-gray-800`, `border-gray-300`)
- **shipped**: Icon 🚀, Indigo theme (`bg-indigo-100`, `text-indigo-800`, `border-indigo-300`)

**Implementation Details:**
- Use TypeScript with proper type definitions
- Import and reuse `ProgressBar` component from `file:web-ui/src/components/ProgressBar.tsx`
- Calculate progress percentage: `(currentStep / totalSteps) * 100`
- Handle edge cases: step 0, step > totalSteps, missing nextAction
- Add `data-testid` attributes for testing: `phase-progress`, `phase-icon`, `step-counter`, `next-action-hint`
- Follow the styling patterns from `PhaseIndicator` and `DiscoveryProgress`

**Visual Layout:**
```
┌─────────────────────────────────────────────┐
│ 🔨 Development Phase                        │
│                                             │
│ Step 5 of 15                                │
│ ████████████░░░░░░░░░░░░░░░░░░░░ 33%       │
│                                             │
│ 💡 Next: Implement user authentication      │
└─────────────────────────────────────────────┘
```

### 3. Integrate PhaseProgress into Dashboard

**File:** `file:web-ui/src/components/Dashboard.tsx`

**Changes Required:**
- Import the new `PhaseProgress` component at the top (line ~30)
- Replace lines 283-285 (current phase display) with `PhaseProgress` component
- Map backend phase names to component phase names:
  - `active` → `development`
  - Keep others as-is (discovery, planning, review, complete)
  - Handle `shipped` if backend adds it in the future

**Integration Code Location:**
- Current location: Lines 279-298 (header section)
- Replace the `<span>` element at lines 283-285
- Pass props: `phase={mappedPhase}`, `currentStep={projectData.workflow_step}`, `totalSteps={15}`
- Optional: Pass `nextAction` if available from project data

**Phase Mapping Logic:**
```typescript
const mappedPhase = projectData.phase === 'active' ? 'development' : projectData.phase;
```

### 4. Update SessionStatus Tests

**File:** `file:web-ui/__tests__/components/SessionStatus.test.tsx`

**Test Updates Required:**
- Update "new session state" tests (lines 89-125) to expect regular session display instead of placeholder
- Remove assertions for "🚀 Starting new session..." text
- Add assertions that "No previous session" summary is displayed as regular text
- Ensure all existing tests for loading, error, and existing session states still pass
- Verify auto-refresh behavior remains unchanged

**Specific Test Changes:**
- Lines 104-105: Change expectation from placeholder to regular summary display
- Lines 122-123: Update to verify "No previous session" appears in summary section
- Keep all other tests unchanged (they test correct functionality)

### 5. Create PhaseProgress Tests

**File:** `file:web-ui/__tests__/PhaseProgress.test.tsx` (new file)

**Test Coverage:**

**Rendering Tests:**
- Renders correct icon for each phase (discovery, planning, development, review, complete, shipped)
- Displays correct phase label
- Shows step counter in format "Step X of Y"
- Renders progress bar with correct percentage
- Displays next action hint when provided
- Hides next action hint when not provided

**Phase-Specific Styling Tests:**
- Each phase has correct background color class
- Each phase has correct text color class
- Each phase has correct border color class

**Edge Cases:**
- Handles step 0 correctly
- Handles step > totalSteps (caps at 100%)
- Handles missing/undefined nextAction
- Handles unknown phase (fallback to default styling)

**Accessibility Tests:**
- Has proper ARIA labels
- Progress bar has role="progressbar"
- Semantic HTML structure

**Example Test Structure:**
```typescript
describe('PhaseProgress', () => {
  describe('phase icons', () => {
    it('displays 🔍 for discovery phase', () => { ... });
    it('displays 📋 for planning phase', () => { ... });
    // ... etc
  });
  
  describe('step counter', () => {
    it('displays "Step 5 of 15"', () => { ... });
    it('resets appropriately per phase', () => { ... });
  });
  
  describe('progress bar', () => {
    it('shows correct percentage', () => { ... });
    it('caps at 100% when step exceeds total', () => { ... });
  });
  
  describe('phase-specific styling', () => {
    it('applies blue theme for discovery', () => { ... });
    // ... etc
  });
});
```

### 6. Update Dashboard Tests

**File:** `file:web-ui/__tests__/components/Dashboard.test.tsx`

**Test Updates:**
- Update tests that check for phase display text
- Replace assertions for "Phase: planning (Step 1/15)" with PhaseProgress component checks
- Verify PhaseProgress receives correct props from Dashboard
- Ensure phase mapping logic works correctly (active → development)

## Component Diagram

```mermaid
sequenceDiagram
    participant D as Dashboard
    participant SS as SessionStatus
    participant PP as PhaseProgress
    participant API as Backend API
    
    D->>SS: Render with projectId
    SS->>API: GET /api/projects/:id/session
    API-->>SS: Session data
    SS->>SS: Display session info (no placeholder)
    
    D->>PP: Render with phase, step, total
    PP->>PP: Map phase to icon/colors
    PP->>PP: Calculate progress %
    PP->>PP: Render phase UI
    
    Note over SS: Auto-refresh every 30s
    SS->>API: GET /api/projects/:id/session
    API-->>SS: Updated session data
```

## File Summary

**Files to Modify:**
- `file:web-ui/src/components/SessionStatus.tsx` - Remove placeholder text
- `file:web-ui/src/components/Dashboard.tsx` - Integrate PhaseProgress component
- `file:web-ui/__tests__/components/SessionStatus.test.tsx` - Update tests

**Files to Create:**
- `file:web-ui/src/components/PhaseProgress.tsx` - New component
- `file:web-ui/__tests__/PhaseProgress.test.tsx` - New test file

**Dependencies:**
- Reuse `ProgressBar` from `file:web-ui/src/components/ProgressBar.tsx`
- Follow patterns from `PhaseIndicator` (`file:web-ui/src/components/PhaseIndicator.tsx`)
- Use `authFetch` from `file:web-ui/src/lib/api-client.ts` (already used in SessionStatus)

---

Execution Information

Branch: main
Commit: 02f1413

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#38 - fix(e2e): Improve Playwright test pass rate from 18% to 57% [merged]
#51 - feat: Add TaskStats component to Dashboard Overview tab [merged]
#93 - fix(e2e): Fix dashboard and metrics tests for tab-based UI rendering [merged]
#194 - Fix PRD generation progress tracking UI [merged]
#196 - fix(discovery): Synchronize PRD buttons and fix state persistence on tab revisit [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!