016-5: TaskReview Component - Task Approval UI

[frankbria]

Part of #197 - Planning Phase Automation

Scope

This issue creates the TaskReview component where users review and approve the generated task breakdown before development starts.

Tasks

TaskReview Component (~2.5h)

• Create web-ui/src/components/TaskReview.tsx
• Hierarchical tree view: Sprint → Issues → Tasks
• Checkbox for each task to include/exclude
• Issue-level "select all" checkbox
• Effort estimate summary (total tasks, estimated hours)
• "Approve and Start Development" button
• Call POST /api/projects/:id/tasks/approve on approval
• Handle loading state during approval
• Redirect/update UI on successful approval

Component structure:

<TaskReview projectId={projectId}>
  <TaskTree>
    <SprintNode number={1}>
      <IssueNode id="1.1" title="User Authentication">
        <TaskNode id="1.1.1" title="Create login form" checked />
        <TaskNode id="1.1.2" title="Add validation" checked />
        <TaskNode id="1.1.3" title="Implement JWT" checked />
      </IssueNode>
      <IssueNode id="1.2" title="Dashboard">
        ...
      </IssueNode>
    </SprintNode>
  </TaskTree>
  <TaskSummary>
    24 tasks selected | ~18 hours estimated
  </TaskSummary>
  <ApproveButton>
    Approve and Start Development
  </ApproveButton>
</TaskReview>

UI Mockup

┌─────────────────────────────────────────────────┐
│ 📋 Review Task Breakdown                        │
├─────────────────────────────────────────────────┤
│ ▼ Sprint 1                                      │
│   ├─ ☑ 1.1 User Authentication (3 tasks)        │
│   │    ├─ ☑ 1.1.1 Create login form             │
│   │    ├─ ☑ 1.1.2 Add form validation           │
│   │    └─ ☑ 1.1.3 Implement JWT auth            │
│   ├─ ☑ 1.2 Dashboard (5 tasks)                  │
│   │    ├─ ☑ 1.2.1 Create layout component       │
│   │    └─ ...                                   │
│   └─ ☐ 1.3 Settings Page (4 tasks)  ← excluded │
├─────────────────────────────────────────────────┤
│ ✅ 20 tasks selected | ⏱️ ~15h estimated        │
│                                                 │
│ [Approve and Start Development]                 │
└─────────────────────────────────────────────────┘

Acceptance Criteria

• Tree view displays all issues and tasks
• Checkboxes work at task and issue level
• Excluded tasks are tracked correctly
• Summary updates dynamically
• Approval calls API and transitions phase
• UI updates to show development phase started

Dependencies

• Requires: 016-2 (task approval endpoint)

Blocks

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

Files

• web-ui/src/components/TaskReview.tsx (new)
• web-ui/src/components/TaskTree.tsx (new, optional extraction)
• web-ui/__tests__/TaskReview.test.tsx (new)

Effort

~2.5 hours

[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

#49 - feat: Add inline dependency rendering to TaskTreeView [merged]
#51 - feat: Add TaskStats component to Dashboard Overview tab [merged]
#169 - feat(dashboard): Add dedicated tabs for Tasks, Quality Gates, and Metrics [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!

[traycerai]

Plan

Observations

The codebase uses a hierarchical work breakdown structure (Sprint → Issues → Tasks) with existing TaskTreeView component for monitoring. The project uses Next.js 14 with React 18, TypeScript, Tailwind CSS, shadcn/ui components, and axios for API calls. Testing uses Jest with React Testing Library. The planning phase automation requires a new TaskReview component distinct from the existing TaskTreeView, as it needs checkbox selection and approval capabilities. The task approval endpoint (POST /api/projects/:id/tasks/approve) will be created in issue 016-2.

Approach

Create a new TaskReview component that displays a hierarchical tree view with checkboxes for task selection, building upon patterns from the existing TaskTreeView component. The component will support issue-level and task-level selection, display effort estimates, and handle the approval workflow. Use native HTML checkboxes styled with Tailwind CSS to maintain consistency with the existing UI patterns. Implement comprehensive tests following the established testing patterns. The component will integrate with the task approval API endpoint and handle phase transitions.

Implementation Steps

1. Create TaskReview Component Structure

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

Create the main TaskReview component with the following structure:

• Accept projectId prop (number or string)
• Implement state management for:
  • Selected task IDs (Set)
  • Expanded sprint/issue nodes (Set)
  • Loading state during approval
  • Error state for API failures
• Use functional component with React hooks (useState, useEffect, useCallback)
• Follow the existing component patterns from TaskTreeView (memo, displayName)

2. Implement Data Fetching

Fetch task breakdown data using the existing API patterns:

• Use axios via file:web-ui/src/lib/api.ts patterns
• Call GET /api/projects/${projectId}/issues?include=tasks to fetch the hierarchical data
• Handle loading states and error states
• Parse the IssuesResponse type from file:web-ui/src/types/api.ts
• Group issues by sprint number (extract from issue_number like "1.1" → Sprint 1)

3. Build Hierarchical Tree UI

Create the tree structure with three levels:

Sprint Level:

• Display sprint number (e.g., "Sprint 1")
• Show expand/collapse button (▶/▼)
• Display aggregate statistics (total issues, total tasks)
• Use Tailwind classes for styling: border, rounded-lg, bg-card

Issue Level:

• Display issue number and title (e.g., "1.1 User Authentication")
• Show checkbox for selecting all tasks in the issue
• Display task count for the issue (e.g., "3 tasks")
• Show expand/collapse button for tasks
• Use indentation with ml-4 or pl-4 for hierarchy

Task Level:

• Display task number and title (e.g., "1.1.1 Create login form")
• Show individual checkbox for task selection
• Display task description if available
• Use deeper indentation with ml-8 or pl-8
• Apply visual styling based on selection state

4. Implement Checkbox Selection Logic

Individual Task Selection:

• Handle onChange event for task checkboxes
• Update selectedTaskIds Set
• When task is checked/unchecked, update parent issue checkbox state (indeterminate if partial)

Issue-Level Selection:

• "Select All" checkbox for each issue
• When checked: add all task IDs from that issue to selectedTaskIds
• When unchecked: remove all task IDs from that issue
• Support indeterminate state (some but not all tasks selected)
• Use HTML checkbox indeterminate property via ref

Default State:

• Initialize with all tasks selected by default
• User can uncheck tasks to exclude them

5. Create Summary Section

Display dynamic summary at the bottom:

• Count selected tasks: selectedTaskIds.size
• Calculate estimated hours: sum effort estimates from selected tasks
• Format: "24 tasks selected | ~18 hours estimated"
• Use icons: ✅ for tasks, ⏱️ for hours
• Style with Tailwind: border-t, pt-4, text-lg, font-medium

6. Implement Approval Button

Create the approval action button:

• Use Button component from file:web-ui/src/components/ui/button.tsx
• Label: "Approve and Start Development"
• Variant: "default" (primary styling)
• Size: "lg" for prominence
• Disable when loading or no tasks selected
• Show loading spinner during API call

7. Integrate Task Approval API

API Call Implementation:

• Add new method to file:web-ui/src/lib/api.ts:

  approveTaskBreakdown: (projectId: number, taskIds: string[]) =>
    api.post(`/api/projects/${projectId}/tasks/approve`, { task_ids: taskIds })

• Handle the approval flow:
  1. Set loading state
  2. Call POST /api/projects/${projectId}/tasks/approve with selected task IDs
  3. Handle success: show success message, trigger phase transition
  4. Handle errors: display error message, keep user on page
  5. Clear loading state

Response Handling:

• On success: redirect to project dashboard or show success state
• Update project phase from 'planning' to 'active'
• Consider using router.push() for navigation (Next.js App Router)

8. Add Error Handling and Loading States

Loading State:

• Show skeleton loader or spinner while fetching data
• Disable all interactions during approval
• Display loading text: "Approving task breakdown..."

Error States:

• Network errors: "Failed to load task breakdown. Please try again."
• Approval errors: "Failed to approve tasks. Please try again."
• Empty state: "No tasks available for approval."
• Use Tailwind alert styling: bg-destructive/10, text-destructive

9. Implement Accessibility Features

Follow WCAG guidelines and existing patterns from TaskTreeView:

• Add role="tree" to the container
• Add role="treeitem" to each node
• Use aria-expanded for expand/collapse buttons
• Use aria-checked for checkboxes
• Add aria-label for icon buttons
• Ensure keyboard navigation works (Tab, Space, Enter)
• Add focus indicators with focus-visible:ring-2

10. Create Comprehensive Tests

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

Follow the testing patterns from file:web-ui/__tests__/components/TaskTreeView.test.tsx:

Test Categories:

1. Rendering Tests:

   • Renders tree view with sprints, issues, and tasks
   • Displays task counts and effort estimates
   • Shows approval button
   • Handles empty state

2. Selection Tests:

   • Individual task checkbox toggles selection
   • Issue-level checkbox selects/deselects all tasks
   • Indeterminate state for partial selection
   • Summary updates dynamically with selection changes

3. Expansion Tests:

   • Sprint nodes expand/collapse
   • Issue nodes expand/collapse
   • Expand/collapse icons update correctly

4. Approval Flow Tests:

   • Approval button calls API with correct task IDs
   • Loading state displays during approval
   • Success handling and navigation
   • Error handling displays error message
   • Button disabled when no tasks selected

5. Accessibility Tests:

   • ARIA attributes present
   • Keyboard navigation works
   • Focus management

6. Edge Cases:

   • Empty task list
   • All tasks excluded
   • API errors
   • Network failures

Test Setup:

• Mock axios API calls using jest.mock()
• Use @testing-library/react for rendering
• Use @testing-library/user-event for interactions
• Follow existing test patterns for consistency

11. Add TypeScript Types

Extend or create types in file:web-ui/src/types/api.ts:

// If not already present, add:
export interface TaskApprovalRequest {
  task_ids: string[];
}

export interface TaskApprovalResponse {
  success: boolean;
  message: string;
  approved_count: number;
  project_phase: ProjectPhase;
}

Define component props interface:

export interface TaskReviewProps {
  projectId: number | string;
  onApprovalSuccess?: () => void;
  onApprovalError?: (error: Error) => void;
}

12. Style with Tailwind CSS

Follow existing styling patterns from TaskTreeView:

• Use semantic color classes: bg-card, text-foreground, border-border
• Apply hover states: hover:bg-muted/50
• Use spacing utilities: p-4, gap-3, space-y-2
• Add transitions: transition-colors
• Style checkboxes with accent-primary for brand consistency
• Use rounded-lg for cards, rounded-md for smaller elements

13. Integration Considerations

Parent Component Integration:

• TaskReview should be used in the project planning phase view
• Conditionally render based on project phase === 'planning'
• After approval, update parent component state or refetch project data

Navigation Flow:

• After successful approval, navigate to project dashboard
• Use Next.js router: import { useRouter } from 'next/navigation'
• Call router.push(\/projects/${projectId}`)` on success

14. Optional: Extract Reusable Components

If the component becomes too large, consider extracting:

• TaskTree.tsx: Reusable tree structure component
• SprintNode.tsx: Sprint-level node component
• IssueNode.tsx: Issue-level node component with checkbox
• TaskNode.tsx: Task-level node component with checkbox

This extraction is optional and should only be done if it improves maintainability.

Component Architecture Diagram

sequenceDiagram
    participant User
    participant TaskReview
    participant API
    participant ProjectDashboard

    User->>TaskReview: Load component
    TaskReview->>API: GET /api/projects/:id/issues?include=tasks
    API-->>TaskReview: IssuesResponse with tasks
    TaskReview->>TaskReview: Group by sprint, initialize all selected
    TaskReview-->>User: Display tree with checkboxes

    User->>TaskReview: Toggle task checkbox
    TaskReview->>TaskReview: Update selectedTaskIds
    TaskReview->>TaskReview: Update summary (count, hours)
    TaskReview-->>User: Show updated summary

    User->>TaskReview: Click "Approve and Start Development"
    TaskReview->>TaskReview: Set loading state
    TaskReview->>API: POST /api/projects/:id/tasks/approve
    API-->>TaskReview: Success response
    TaskReview->>TaskReview: Clear loading state
    TaskReview->>ProjectDashboard: Navigate to dashboard
    ProjectDashboard-->>User: Show active phase

Loading

File Summary

New Files:

• file:web-ui/src/components/TaskReview.tsx - Main component
• file:web-ui/__tests__/components/TaskReview.test.tsx - Component tests

Modified Files:

• file:web-ui/src/lib/api.ts - Add approveTaskBreakdown method
• file:web-ui/src/types/api.ts - Add TaskApprovalRequest/Response types (if needed)

Dependencies:

• Requires issue 016-2 (task approval endpoint) to be completed first
• Uses existing types from file:web-ui/src/types/api.ts (Issue, Task, IssuesResponse)
• Uses existing Button component from file:web-ui/src/components/ui/button.tsx
• Uses existing API client patterns from file:web-ui/src/lib/api.ts

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses a hierarchical work breakdown structure (Sprint → Issues → Tasks) with existing TaskTreeView component for monitoring. The project uses Next.js 14 with React 18, TypeScript, Tailwind CSS, shadcn/ui components, and axios for API calls. Testing uses Jest with React Testing Library. The planning phase automation requires a new TaskReview component distinct from the existing TaskTreeView, as it needs checkbox selection and approval capabilities. The task approval endpoint (POST /api/projects/:id/tasks/approve) will be created in issue 016-2.

## Approach

Create a new TaskReview component that displays a hierarchical tree view with checkboxes for task selection, building upon patterns from the existing TaskTreeView component. The component will support issue-level and task-level selection, display effort estimates, and handle the approval workflow. Use native HTML checkboxes styled with Tailwind CSS to maintain consistency with the existing UI patterns. Implement comprehensive tests following the established testing patterns. The component will integrate with the task approval API endpoint and handle phase transitions.

## Implementation Steps

### 1. Create TaskReview Component Structure

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

Create the main TaskReview component with the following structure:
- Accept `projectId` prop (number or string)
- Implement state management for:
  - Selected task IDs (Set<string>)
  - Expanded sprint/issue nodes (Set<string>)
  - Loading state during approval
  - Error state for API failures
- Use functional component with React hooks (useState, useEffect, useCallback)
- Follow the existing component patterns from TaskTreeView (memo, displayName)

### 2. Implement Data Fetching

Fetch task breakdown data using the existing API patterns:
- Use axios via `file:web-ui/src/lib/api.ts` patterns
- Call GET `/api/projects/${projectId}/issues?include=tasks` to fetch the hierarchical data
- Handle loading states and error states
- Parse the IssuesResponse type from `file:web-ui/src/types/api.ts`
- Group issues by sprint number (extract from issue_number like "1.1" → Sprint 1)

### 3. Build Hierarchical Tree UI

Create the tree structure with three levels:

**Sprint Level**:
- Display sprint number (e.g., "Sprint 1")
- Show expand/collapse button (▶/▼)
- Display aggregate statistics (total issues, total tasks)
- Use Tailwind classes for styling: `border`, `rounded-lg`, `bg-card`

**Issue Level**:
- Display issue number and title (e.g., "1.1 User Authentication")
- Show checkbox for selecting all tasks in the issue
- Display task count for the issue (e.g., "3 tasks")
- Show expand/collapse button for tasks
- Use indentation with `ml-4` or `pl-4` for hierarchy

**Task Level**:
- Display task number and title (e.g., "1.1.1 Create login form")
- Show individual checkbox for task selection
- Display task description if available
- Use deeper indentation with `ml-8` or `pl-8`
- Apply visual styling based on selection state

### 4. Implement Checkbox Selection Logic

**Individual Task Selection**:
- Handle onChange event for task checkboxes
- Update selectedTaskIds Set
- When task is checked/unchecked, update parent issue checkbox state (indeterminate if partial)

**Issue-Level Selection**:
- "Select All" checkbox for each issue
- When checked: add all task IDs from that issue to selectedTaskIds
- When unchecked: remove all task IDs from that issue
- Support indeterminate state (some but not all tasks selected)
- Use HTML checkbox indeterminate property via ref

**Default State**:
- Initialize with all tasks selected by default
- User can uncheck tasks to exclude them

### 5. Create Summary Section

Display dynamic summary at the bottom:
- Count selected tasks: `selectedTaskIds.size`
- Calculate estimated hours: sum effort estimates from selected tasks
- Format: "24 tasks selected | ~18 hours estimated"
- Use icons: ✅ for tasks, ⏱️ for hours
- Style with Tailwind: `border-t`, `pt-4`, `text-lg`, `font-medium`

### 6. Implement Approval Button

Create the approval action button:
- Use Button component from `file:web-ui/src/components/ui/button.tsx`
- Label: "Approve and Start Development"
- Variant: "default" (primary styling)
- Size: "lg" for prominence
- Disable when loading or no tasks selected
- Show loading spinner during API call

### 7. Integrate Task Approval API

**API Call Implementation**:
- Add new method to `file:web-ui/src/lib/api.ts`:
  ```typescript
  approveTaskBreakdown: (projectId: number, taskIds: string[]) =>
    api.post(`/api/projects/${projectId}/tasks/approve`, { task_ids: taskIds })
  ```
- Handle the approval flow:
  1. Set loading state
  2. Call POST `/api/projects/${projectId}/tasks/approve` with selected task IDs
  3. Handle success: show success message, trigger phase transition
  4. Handle errors: display error message, keep user on page
  5. Clear loading state

**Response Handling**:
- On success: redirect to project dashboard or show success state
- Update project phase from 'planning' to 'active'
- Consider using router.push() for navigation (Next.js App Router)

### 8. Add Error Handling and Loading States

**Loading State**:
- Show skeleton loader or spinner while fetching data
- Disable all interactions during approval
- Display loading text: "Approving task breakdown..."

**Error States**:
- Network errors: "Failed to load task breakdown. Please try again."
- Approval errors: "Failed to approve tasks. Please try again."
- Empty state: "No tasks available for approval."
- Use Tailwind alert styling: `bg-destructive/10`, `text-destructive`

### 9. Implement Accessibility Features

Follow WCAG guidelines and existing patterns from TaskTreeView:
- Add `role="tree"` to the container
- Add `role="treeitem"` to each node
- Use `aria-expanded` for expand/collapse buttons
- Use `aria-checked` for checkboxes
- Add `aria-label` for icon buttons
- Ensure keyboard navigation works (Tab, Space, Enter)
- Add focus indicators with `focus-visible:ring-2`

### 10. Create Comprehensive Tests

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

Follow the testing patterns from `file:web-ui/__tests__/components/TaskTreeView.test.tsx`:

**Test Categories**:
1. **Rendering Tests**:
   - Renders tree view with sprints, issues, and tasks
   - Displays task counts and effort estimates
   - Shows approval button
   - Handles empty state

2. **Selection Tests**:
   - Individual task checkbox toggles selection
   - Issue-level checkbox selects/deselects all tasks
   - Indeterminate state for partial selection
   - Summary updates dynamically with selection changes

3. **Expansion Tests**:
   - Sprint nodes expand/collapse
   - Issue nodes expand/collapse
   - Expand/collapse icons update correctly

4. **Approval Flow Tests**:
   - Approval button calls API with correct task IDs
   - Loading state displays during approval
   - Success handling and navigation
   - Error handling displays error message
   - Button disabled when no tasks selected

5. **Accessibility Tests**:
   - ARIA attributes present
   - Keyboard navigation works
   - Focus management

6. **Edge Cases**:
   - Empty task list
   - All tasks excluded
   - API errors
   - Network failures

**Test Setup**:
- Mock axios API calls using jest.mock()
- Use @testing-library/react for rendering
- Use @testing-library/user-event for interactions
- Follow existing test patterns for consistency

### 11. Add TypeScript Types

Extend or create types in `file:web-ui/src/types/api.ts`:

```typescript
// If not already present, add:
export interface TaskApprovalRequest {
  task_ids: string[];
}

export interface TaskApprovalResponse {
  success: boolean;
  message: string;
  approved_count: number;
  project_phase: ProjectPhase;
}
```

Define component props interface:
```typescript
export interface TaskReviewProps {
  projectId: number | string;
  onApprovalSuccess?: () => void;
  onApprovalError?: (error: Error) => void;
}
```

### 12. Style with Tailwind CSS

Follow existing styling patterns from TaskTreeView:
- Use semantic color classes: `bg-card`, `text-foreground`, `border-border`
- Apply hover states: `hover:bg-muted/50`
- Use spacing utilities: `p-4`, `gap-3`, `space-y-2`
- Add transitions: `transition-colors`
- Style checkboxes with `accent-primary` for brand consistency
- Use `rounded-lg` for cards, `rounded-md` for smaller elements

### 13. Integration Considerations

**Parent Component Integration**:
- TaskReview should be used in the project planning phase view
- Conditionally render based on project phase === 'planning'
- After approval, update parent component state or refetch project data

**Navigation Flow**:
- After successful approval, navigate to project dashboard
- Use Next.js router: `import { useRouter } from 'next/navigation'`
- Call `router.push(\`/projects/\${projectId}\`)` on success

### 14. Optional: Extract Reusable Components

If the component becomes too large, consider extracting:
- `TaskTree.tsx`: Reusable tree structure component
- `SprintNode.tsx`: Sprint-level node component
- `IssueNode.tsx`: Issue-level node component with checkbox
- `TaskNode.tsx`: Task-level node component with checkbox

This extraction is optional and should only be done if it improves maintainability.

## Component Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant TaskReview
    participant API
    participant ProjectDashboard

    User->>TaskReview: Load component
    TaskReview->>API: GET /api/projects/:id/issues?include=tasks
    API-->>TaskReview: IssuesResponse with tasks
    TaskReview->>TaskReview: Group by sprint, initialize all selected
    TaskReview-->>User: Display tree with checkboxes

    User->>TaskReview: Toggle task checkbox
    TaskReview->>TaskReview: Update selectedTaskIds
    TaskReview->>TaskReview: Update summary (count, hours)
    TaskReview-->>User: Show updated summary

    User->>TaskReview: Click "Approve and Start Development"
    TaskReview->>TaskReview: Set loading state
    TaskReview->>API: POST /api/projects/:id/tasks/approve
    API-->>TaskReview: Success response
    TaskReview->>TaskReview: Clear loading state
    TaskReview->>ProjectDashboard: Navigate to dashboard
    ProjectDashboard-->>User: Show active phase
```

## File Summary

**New Files**:
- `file:web-ui/src/components/TaskReview.tsx` - Main component
- `file:web-ui/__tests__/components/TaskReview.test.tsx` - Component tests

**Modified Files**:
- `file:web-ui/src/lib/api.ts` - Add approveTaskBreakdown method
- `file:web-ui/src/types/api.ts` - Add TaskApprovalRequest/Response types (if needed)

**Dependencies**:
- Requires issue 016-2 (task approval endpoint) to be completed first
- Uses existing types from `file:web-ui/src/types/api.ts` (Issue, Task, IssuesResponse)
- Uses existing Button component from `file:web-ui/src/components/ui/button.tsx`
- Uses existing API client patterns from `file:web-ui/src/lib/api.ts`

---

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.