GSB-Construction/docs/PLAN-task-progress-bars.md

Task Progress Overview — Stacked Multi-Segment Progress Bars

Enhance the Project Show Overview tab and Index listing to display detailed task progress with stacked status bars (Pending / In Progress / Completed) and a main progress bar that only tracks completed tasks.

Proposed Changes

Backend — TaskController

---

[MODIFY] TaskController.php

updateProjectCompletion() — Change from avg(completion_percentage) to count-based:

$completed = $tasks->where('status', 'completed')->count();
$total = $tasks->count();
$project->update(['completion_percentage' => $total > 0 ? round(($completed / $total) * 100, 2) : 0]);

store() — Add $this->updateProjectCompletion($project) after creating a new task, so adding a task re-dilutes the progress denominator.

destroy() — Add $this->updateProjectCompletion($project) after deleting a task, so removing a task recalculates progress.

---

Backend — ProjectController

[MODIFY] ProjectController.php

show() — Compute and pass taskStats to the frontend:

'taskStats' => [
    'total'       => $project->tasks->count(),
    'pending'     => $project->tasks->where('status', 'pending')->count(),
    'in_progress' => $project->tasks->where('status', 'in_progress')->count(),
    'completed'   => $project->tasks->where('status', 'completed')->count(),
],

Tasks are already eager-loaded, so this adds zero extra queries.

---

Frontend — Show.tsx Overview Tab

[MODIFY] Show.tsx

Replace the current single green progress bar (lines 218-224) with:

1. Main Progress Header

Progress    3 / 10 tasks completed    30%
████████████░░░░░░░░░░░░░░░░░░░░░░░░░

• Green bar, width = completed / total * 100
• Shows {completed} / {total} tasks completed label

2. Stacked Segment Bar

[▓▓▓▓▓▓▓▓▓▓▓▓▓▓████████████░░░░░░░░░░]
 [completed]    [in-progress] [pending]

• Three adjacent colored segments in a single bar:
  • Green (emerald-500) = completed %
  • Blue (blue-500) = in-progress %
  • Gray (gray-300) = pending %
• Height h-2, purely visual distribution overview

3. Status Detail Rows

● Completed    ████████████████          3 tasks (30%)
● In Progress  ████████░░░░░░░░          3 tasks (30%)
● Pending      ░░░░░░░░░░░░░░░░          4 tasks (40%)

• Each row: colored dot, label, mini progress bar, count + percentage
• Small text text-xs, compact layout with gap-2

Implementation notes:

• Data from taskStats prop (computed server-side)
• Zero-task edge case: show "No tasks yet" message
• Smooth CSS transitions on bar widths

---

Frontend — Index.tsx Progress Cell

[MODIFY] Index.tsx

Minor change: the existing mini progress bar in the table (line 176-184) already uses completion_percentage which will now reflect the count-based formula. No changes needed — it will automatically show correct values from the backend change.

---

Verification Plan

Manual Verification

1. Create a project with 5 tasks. Verify progress = 0%.
2. Complete 2 tasks → progress should show 40% (2/5).
3. Add a new task (now 6 total) → progress drops to 33% (2/6).
4. Delete a pending task (now 5 total) → progress returns to 40% (2/5).
5. Check that the stacked bar and detail rows update correctly on each action.
6. Verify the Index listing mini-bar also reflects the count-based percentage.