Make the Home activity grid a one-year GitHub-style chart with month labels

[brianlan]

Summary

Rework the Home dashboard activity grid so it shows only the recent year in a GitHub-like week layout and includes month labels aligned to selected week columns.

Background / Context

Issue #305 added a Home dashboard activity grid. The user reports that the current Home activity grid appears to show too much data, roughly two years, and requires horizontal scrolling to view all of it. They want only the recent year and month labels such as Jun, Jul, and Oct, aligned like GitHub’s contribution chart.

Reconnaissance found that the backend Home endpoint already returns 365 days (today - 364 days through today) on the issue #305 implementation. That means the likely fix is in the frontend grid construction/layout, not in expanding or changing the backend date range.

Relevant codebase context from issue #305:

• Home page: frontend/src/pages/HomePage.tsx.
• Existing activity helper builds week columns from returned days.
• Existing grid has weekday labels and activity cells, but no month label row.
• Existing grid uses horizontal overflow.

Problem

The activity grid does not yet match the expected GitHub-style recent-year visualization. It appears too wide, may feel like more than one year of data, and lacks month labels for orientation.

Goal / Expected Behavior

The Home activity grid should:

• Display only the recent year of activity.
• Render as a deterministic GitHub-like week matrix.
• Use Monday through Sunday rows.
• Use week columns, typically about 53 columns for a one-year range.
• Include a month-label row above the grid with abbreviated month names aligned to appropriate columns.
• Avoid unnecessary horizontal scroll on normal desktop widths.
• Allow horizontal scroll only on narrow/mobile widths if needed.

Scope

This issue should cover:

• Fix or replace the frontend week-column builder.
• Add month-label generation and rendering.
• Tighten the activity grid layout so one year fits on normal desktop widths.
• Add tests for recent-year column count and month labels.

Out of Scope

This issue should not cover:

• Changing the backend activity-count semantics.
• Changing the Home summary endpoint range unless a test proves it is not returning exactly one year.
• Adding timezone preferences.
• Adding tooltips beyond existing cell titles.
• Adding drill-down views for activity cells.
• Adding Conquest Rate.
• Fixing the dark-theme bottom background issue.

Chosen Implementation Approach

Keep the backend recent-year range at exactly 365 data days for v1.

On the frontend, construct a deterministic week matrix from the returned activity.days:

• Sort days by date ascending before rendering.
• Align rows by UTC weekday with Monday as row 0 and Sunday as row 6.
• Include only leading/trailing empty cells needed to align the first and last returned dates.
• Do not generate extra columns beyond the one-year range.
• Derive month labels from the rendered columns, placing each abbreviated month label on the first visible week column where that month appears.

Use compact cell and gap sizes so the normal 53-week layout fits within the Home content width on desktop.

Implementation Plan

The implementor should:

1. Update the Home activity-grid helper to sort days and build a bounded one-year week matrix.
2. Ensure the rendered column count reflects the returned one-year range, normally no more than 53 columns for 365 days plus alignment.
3. Add a month-label row above the activity cells.
4. Generate abbreviated English month names from UTC dates.
5. Render labels only where a month first appears in the visible week columns.
6. Keep weekday labels ordered Monday through Sunday.
7. Adjust cell/gap sizing so desktop widths do not require horizontal scroll for a one-year grid.
8. Preserve existing activity count, cell title, and intensity behavior.

Relevant Files / Areas

Likely relevant areas:

• frontend/src/pages/HomePage.tsx
• frontend/src/pages/HomePage.test.tsx
• frontend/tests/theme.spec.ts or other browser tests if layout verification is added there

Suggested verification commands:

cd frontend && npm test -- --run HomePage
cd frontend && npm run test:ui -- theme.spec.ts

Tests Required

The implementor must add or update automated tests covering:

• The activity grid renders no more than the expected recent-year week columns for a 365-day response.
• Month labels render for relevant months.
• Month labels align to week columns rather than cells floating independently.
• Weekday labels remain Monday through Sunday.
• Returned day counts still map to the correct date cells.
• The grid does not duplicate the returned range into an apparent two-year layout.

At minimum, tests should verify:

• A fixed 365-day fixture produces a bounded week-column count.
• Several month labels, such as Jun, Jul, and Oct, appear when included in the fixture range.
• Existing activity-cell data-date and data-count behavior remains intact.

Manual Verification / Self-Check

Before claiming this issue is done, the implementor must:

1. Run the Home page frontend tests.
2. Open the Home page on a normal desktop viewport and verify the grid shows only a recent-year span.
3. Verify month labels appear above appropriate columns.
4. Verify the chart does not require horizontal scroll on normal desktop width.
5. Verify narrow/mobile behavior remains usable if overflow is necessary.
6. Include exact commands and pass/fail results in the PR description.

Suggested verification commands:

cd frontend && npm test -- --run HomePage
cd frontend && npm run test:ui -- theme.spec.ts

Reviewer Acceptance Checklist

The reviewer should verify that:

• The grid represents one recent year, not an apparent two-year range.
• Month labels are visible and aligned like a GitHub contribution chart.
• Weekday rows remain Monday through Sunday.
• The implementation preserves existing count/date mapping.
• Desktop layout avoids unnecessary horizontal scrolling.
• Required tests were added or updated.
• The change is scoped to the activity-grid layout and does not bundle unrelated dashboard work.
• The PR includes self-verification commands and results.

Dependencies

Depends on the Home dashboard from #305 being present in the target branch.

Follow-Up Work

Possible future work, not included here:

• User timezone-aware activity grouping.
• Configurable activity ranges.
• Richer cell hover details.

Definition of Done

This issue is done when:

• The Home activity grid renders a bounded recent-year week matrix.
• Month labels appear above relevant columns.
• Normal desktop layouts do not show an unnecessarily wide, two-year-feeling grid.
• Required automated tests pass.
• Manual verification is documented in the PR.

[brianlan]

Starting work on this issue.