summaryrefslogtreecommitdiff
path: root/docs/superpowers/specs/2026-05-17-reference-card-adaptive-design.md
blob: b819e5e654566306bf26d2056a8e2ba61ce46de4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# Reference Card — Adaptive Row Filtering

**Date:** 2026-05-17  
**Status:** Approved

## Problem

The `StatsCard` component (the "Reference" card in the right rail) always renders all 17 ratio rows. For partial tickers — ETFs, tickers with no income statements, or symbols resolved only through fast-info — most ratio fields are null. This produces a wall of muted "Unavailable" text that adds no information and degrades readability.

## Goal

Make the Reference card adaptive: show only rows that have values, and replace suppressed rows with a single brief note so the user understands why data is missing.

## Approach

Filter, don't hide. Keep the full 17-row definition intact in code (it documents what fields the card tracks). At render time, split into visible and suppressed lists. Only render visible rows; show one fallback line if anything was suppressed.

## Design

### Scope

Only `StatsCard` in `frontend/app/page.tsx` changes. No backend changes, no schema changes, no CSS additions.

### Logic

1. Build `referenceRows` as today — 17 rows with `{ label, value, missing }`.
2. Derive `visibleRows = referenceRows.filter(r => !r.missing)`.
3. Compute `suppressedCount = referenceRows.length - visibleRows.length`.
4. Render `visibleRows` via `StatRow`.
5. If `suppressedCount > 0`, append a muted line after the list:  
   `· Statement data incomplete`  
   Use existing `psm-muted-copy` class — no new CSS needed.
6. Edge case: if `visibleRows` is empty, render only the fallback line (no empty `psm-stat-list`).

### What stays the same

- Backend payload shape (`ratios`, `stats`, `meta`) — unchanged.
- All other cards (`ShortInterestCard`, `ProfileCard`, `DataStatusCard`) — unchanged.
- Watchlist, chart, KPI strip, signals — unchanged.
- CSS — no additions.

### Acceptance criteria

- Partial ticker: Reference card shows only available rows + one fallback note at bottom.
- Full ticker: all 17 rows render as before.
- Empty ticker (no rows): fallback note only, no empty list element.
- `npm run lint`, `npm run build`, `pytest` all pass.

## Files changed

- `frontend/app/page.tsx` — `StatsCard` function only (~5 lines)