Smart star history views — velocity vs. timeline with auto-detection

[djdarcy]

Smart star history views — velocity vs. timeline with auto-detection

Problem

The current star history chart uses a categorical X-axis where each star event gets equal horizontal spacing. This makes every project's star history look like smooth linear growth regardless of actual velocity — a project getting 10 stars/day and 1 star/week produce curves that look nearly identical.

Users who track their project's momentum (like star-history.com provides) need a time-proportional view where the X-axis represents actual calendar time. This reveals:

• Acceleration phases (steep climbs)
• Deceleration/stagnation (flat plateaus)
• Burst events (sudden spikes)

However, the time-proportional view can also be demoralizing for projects in a plateau phase — long flat sections emphasize inactivity. The current event-based view actually serves these projects better by focusing on when individual stars arrived.

Proposed solution

Add dual star history views with intelligent auto-selection:

Two view modes:

Mode	X-Axis	Best For	Reveals
Velocity	Time-proportional (Chart.js type: 'time')	Growing projects	Acceleration, deceleration, burst patterns
Timeline	Categorical (current)	Plateauing projects	Individual star events, correlation to activity

Auto-selection via growth-phase detection:

Classify the star trajectory by splitting the timeline into thirds and comparing stars-per-day rates:

• accelerating → default to Velocity view (showcase momentum)
• linear → default to Velocity view (linear growth reads well time-proportionally)
• decelerating → default to Timeline view (focus on individual contributions)
• sparse (<10 stars or <30 days) → default to Timeline view

Manual override: Toggle pills above the chart. User's choice remembered in sessionStorage.

Technical approach

1. Add date adapter CDN — chartjs-adapter-date-fns (~5KB bundled), required for Chart.js time scale
2. Modify renderStarChart() to accept a mode parameter, switching between category and time axis types
3. Add detectGrowthPhase() function — segmented rate comparison across timeline thirds
4. Add toggle UI — pill-style buttons with "(auto)" indicator on the default selection
5. Build buildStarChartOptions(mode) — star-chart-specific options function supporting both axis types

Design considerations

• CDN resilience: Feature-detect the date adapter; if missing, hide toggle and use categorical only
• Minimum threshold: Require ≥10 stars and ≥30 days before offering Velocity view
• No new data sources: Both views use the same stargazer API data already fetched
• Toggle pattern reuse: The toggle mechanism established here can be reused for Time-segmented All History view — prevent chart overcrowding #5 (time-segmented history)
• Growth phase visibility: Consider showing a subtle indicator (e.g., "Accelerating" badge) — but keep it non-judgmental

Future evolution

This feature establishes the multi-view architecture for progressive enhancement:

1. This issue: Velocity + Timeline views, auto-select, manual toggle
2. Daily delta view: Bar chart showing stars-per-day (useful for identifying burst events)
3. Yearly segmentation: Navigate star history by year within each view mode
4. Event correlation overlay: Plot commits, releases, and milestones on the star timeline to surface "what caused this growth?" insights
5. Comparative mode: If multi-repo support is added, align timelines for repo comparison

Acceptance criteria

• Two star history views available: Velocity (time-proportional) and Timeline (categorical/event-based)
• Toggle UI (pill buttons) above star chart with clear labeling
• Auto-selection defaults based on growth-phase detection algorithm
• Manual override persists in sessionStorage
• Graceful fallback if date adapter CDN fails (hide toggle, show categorical)
• Minimum data threshold before enabling Velocity view (≥10 stars, ≥30 days)
• Both views use identical underlying data — no additional API calls
• Works with existing star data caching in sessionStorage

Related

• Refs Roadmap #1 — Roadmap Phase 4 (dashboard polish)
• Refs Embeddable charts for READMEs — compete with star-history #3 — Embeddable charts (velocity view is compelling for README embeds)
• Refs Time-segmented All History view — prevent chart overcrowding #5 — Time-segmented history (complementary — segmentation is about data volume, this is about visualization mode)

Analysis

See 2026-02-26__13-13-59__star-history-multi-view-analysis.md for detailed DEV WORKFLOW PROCESS analysis.