bullitt/trackbox

Fork 0

Stats: Add Needs attention / stale-data StatCard as a system health signal #36

New issue

Closed

opened 2026-06-27 15:41:15 +02:00 by bullitt · 1 comment

bullitt commented

2026-06-27 15:41:15 +02:00

Owner

Problem

The Stats page has cards for Total, Active, Delivered, Parsers, Events, and Uptime — but no card for "Stalled". In the live instance, 8 out of 10 active shipments are stalled. The stall count is the most actionable health indicator in the system, yet it's invisible on Stats.

Implementation

File: frontend/src/pages/Stats.tsx

Compute the stalled count:

const stalled = shipments.filter(s => s.stalled).length

Add a StatCard after "Active":

<StatCard
  icon={AlertTriangle}  // from lucide-react
  label="Stalled"
  value={stalled}
  sub="need attention"
  color={stalled > 0 ? "text-amber-500" : "text-muted-foreground"}
/>

Import AlertTriangle from lucide-react (add to existing import line).
The Shipment type in frontend/src/lib/api.ts already has stalled?: boolean — confirm the list endpoint returns this field. If not, the backend /api/shipments route must include stalled in the response. Check db.py list_shipments function to confirm.

Acceptance criteria

A "Stalled" card appears in the stat grid
Count matches the number of stalled shipments shown on Dashboard
Card is amber-colored when count > 0, neutral when 0
Counts correctly include all shipments (after fix from #14 for archived)

Brand identity alignment

The brand brief says the dashboard should prioritize shipments requiring attention and data staleness. A Stalled card should be reframed in Trackbox language as Needs attention, Delivery may be delayed, or Carrier data unavailable depending on available semantics.

Brand-compliant implementation notes

Use amber for delayed/stale data and red only for actual exceptions or required user action.
Include a short sublabel such as No new carrier events or Sync failures so the metric is actionable.
Keep the card neutral unless the count is non-zero; status color should be a small semantic accent, not a full-card fill.

Additional acceptance criteria

The card represents an operational health signal, not a vanity metric.
Copy matches Trackbox status language and avoids vague Stalled as the only label.
Count matches the same logic used on Dashboard shipment cards.

Migrated from GitHub issue #15: https://github.com/bullitt186/trackbox/issues/15
Original author: @bullitt186
Original created: 2026-06-27T13:24:31Z
Original labels: ux

## Problem The Stats page has cards for Total, Active, Delivered, Parsers, Events, and Uptime — but no card for "Stalled". In the live instance, 8 out of 10 active shipments are stalled. The stall count is the most actionable health indicator in the system, yet it's invisible on Stats. ## Implementation File: `frontend/src/pages/Stats.tsx` 1. Compute the stalled count: ```ts const stalled = shipments.filter(s => s.stalled).length ``` 2. Add a StatCard after "Active": ```tsx <StatCard icon={AlertTriangle} // from lucide-react label="Stalled" value={stalled} sub="need attention" color={stalled > 0 ? "text-amber-500" : "text-muted-foreground"} /> ``` 3. Import `AlertTriangle` from lucide-react (add to existing import line). 4. The `Shipment` type in `frontend/src/lib/api.ts` already has `stalled?: boolean` — confirm the list endpoint returns this field. If not, the backend `/api/shipments` route must include `stalled` in the response. Check `db.py` `list_shipments` function to confirm. ## Acceptance criteria - A "Stalled" card appears in the stat grid - Count matches the number of stalled shipments shown on Dashboard - Card is amber-colored when count > 0, neutral when 0 - Counts correctly include all shipments (after fix from #14 for archived) ## Brand identity alignment The brand brief says the dashboard should prioritize shipments requiring attention and data staleness. A `Stalled` card should be reframed in Trackbox language as `Needs attention`, `Delivery may be delayed`, or `Carrier data unavailable` depending on available semantics. ## Brand-compliant implementation notes - Use amber for delayed/stale data and red only for actual exceptions or required user action. - Include a short sublabel such as `No new carrier events` or `Sync failures` so the metric is actionable. - Keep the card neutral unless the count is non-zero; status color should be a small semantic accent, not a full-card fill. ## Additional acceptance criteria - The card represents an operational health signal, not a vanity metric. - Copy matches Trackbox status language and avoids vague `Stalled` as the only label. - Count matches the same logic used on Dashboard shipment cards. --- Migrated from GitHub issue #15: https://github.com/bullitt186/trackbox/issues/15 Original author: @bullitt186 Original created: 2026-06-27T13:24:31Z Original labels: ux

bullitt added the

label

2026-06-27 15:41:15 +02:00

bullitt changed title from ~~Stats: Add 'Stalled' StatCard — it's the most important system health signal~~ to Stats: Add Needs attention / stale-data StatCard as a system health signal

2026-06-27 15:46:22 +02:00

bullitt commented

2026-06-27 16:02:48 +02:00

Author

Owner

Implemented in commit bd6b0e7. Added a 'Needs attention' StatCard with the AlertTriangle icon showing the count of active stalled shipments (activeShipments.filter(s => s.stalled).length). The card uses text-amber-500 color when count > 0, neutral otherwise. Sub-label reads 'Stalled or no new events'. The card only renders when count > 0 to avoid visual noise when everything is healthy.

Implemented in commit bd6b0e7. Added a 'Needs attention' StatCard with the AlertTriangle icon showing the count of active stalled shipments (`activeShipments.filter(s => s.stalled).length`). The card uses `text-amber-500` color when count > 0, neutral otherwise. Sub-label reads 'Stalled or no new events'. The card only renders when count > 0 to avoid visual noise when everything is healthy.

bullitt closed this issue

2026-06-27 16:02:48 +02:00

No labels

arch

harness

security

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

bullitt/trackbox#36

No description provided.

Rows
Columns