feat(view): add view=commit_clock — 24-hour polar ring from real comm…

[vivek0369]

PR Title

feat(view): add view=commit_clock — 24-hour polar ring from real commit timestamps

---

📖 Description

This PR introduces a brand-new visualization: view=commit_clock, a 24-hour polar contribution clock powered entirely by real GitHub commit timestamps.

The current radar visualization contains a simulated Night Owl metric generated from deterministic random values:

// Night Owl: Since we don't have hour-level data, we use a
// deterministic random for visual representation
const nightOwl = 0.2 + 0.6 * deterministicRandom(`${seed}:nightowl`);

While visually appealing, this metric does not represent actual user activity.

To provide meaningful insights based on real contribution behavior, this PR adds a dedicated SVG view that analyzes commit timestamps retrieved from the GitHub GraphQL API and visualizes commit frequency across all 24 hours of the day.

Example Usage

---

🎯 Pillar

• 🎨 Pillar 1 — New Theme Design

• 📐 Pillar 2 — Geometric SVG Improvement

• 🕐 Pillar 3 — Timezone Logic Optimization

• 🛠️ Other

---

🚀 What Was Changed

✨ New File — lib/svg/commitClock.ts

Added:

generateCommitClockSVG(hourCounts, stats, params)

Features:

• 24-segment radial contribution clock

• Real commit activity visualization

• Dynamic segment length based on contribution frequency

• Opacity scaling for stronger visual contrast

• Cardinal hour labels (12a, 6a, 12p, 6p)

• Statistics panel:

  • Total sampled commits

  • Peak commit hour

  • Current streak

  • Longest streak

• Theme-aware rendering

• Full support for:

  • bg

  • accent

  • text

  • size

  • radius

  • border

  • hideBackground

• Accessibility support:

  • <title>

  • <desc>

  • aria-labelledby

  • aria-describedby

---

🔄 Modified — lib/github.ts

Added:

fetchCommitHourDistribution()

Functionality:

• Retrieves commit timestamps via GraphQL

• Uses existing retry and token-rotation infrastructure

• Aggregates commits into 24 hourly buckets

• Queries top repositories by contribution volume

• Supports capped concurrency

• Gracefully skips unavailable repositories

---

✅ Modified — lib/validations.ts

Added:

'commit_clock'

to the allowed view enum.

---

✅ Modified — types/index.ts

Added:

view: 'commit_clock'

to BadgeParams.

Updated related JSDoc documentation.

---

✅ Modified — app/api/streak/route.ts

Integrated the new SVG generator and data pipeline.

Workflow:

1. Determine top repositories.

2. Fetch commit timestamps.

3. Build hourly distribution.

4. Generate SVG.

5. Return rendered badge.

---

🎨 Design Decisions

Decision | Reason -- | -- Top 5 repositories | Provides representative commit history while minimizing API cost 100 commits per repository | Good balance between performance and accuracy UTC timestamps | Consistent with GitHub GraphQL data source Silent repository failures | Prevents badge failures caused by private or archived repositories Radial length + opacity encoding | Improves readability at smaller sizes Separate view instead of radar modification | Preserves radar chart semantics while introducing a more powerful visualization

---

🧪 Testing

Local Development

npm run dev

Default View

http://localhost:3000/api/streak?user=YOUR_USERNAME&view=commit_clock

Theme Testing

http://localhost:3000/api/streak?user=YOUR_USERNAME&view=commit_clock&theme=neon
http://localhost:3000/api/streak?user=YOUR_USERNAME&view=commit_clock&theme=dracula

Custom Colors

http://localhost:3000/api/streak?user=YOUR_USERNAME&view=commit_clock&bg=0a0a0a&accent=00ffee&text=ffffff

Size Variants

http://localhost:3000/api/streak?user=YOUR_USERNAME&view=commit_clock&size=small

http://localhost:3000/api/streak?user=YOUR_USERNAME&view=commit_clock&size=large

Validation Test

http://localhost:3000/api/streak?user=YOUR_USERNAME&view=commit_clock_typo

Expected Result:

• Invalid view falls back to default rendering.

• No runtime errors occur.

---

📸 Visual Preview

Add screenshots/GIFs here showing:

• Default theme

• Neon theme

• Dracula theme

• Custom color configuration

• Small and large size variants

---

🔍 Benefits

• Replaces simulated activity metrics with real GitHub data

• Provides meaningful insight into coding habits

• Adds a unique SVG visualization not currently available in CommitPulse

• Maintains compatibility with existing themes and customization options

• Improves transparency and analytical value

---

✅ Checklist

• Read CONTRIBUTING.md

• Tested locally

• Ran npm run format

• Ran npm run lint

• Ran npm run test

• Ran npm run test:coverage

• Conventional Commit format used

• Updated documentation where required

• Added accessibility attributes

• No new TypeScript errors

• Maintains CommitPulse design standards

---

🔗 Related Issue

Closes #5993

Suggested Labels

enhancement

feature

svg

visualization

good first issue

gssoc26

[vercel]

@vivek0369 is attempting to deploy a commit to the jhasourav07's projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

📦 Next.js Bundle Size Report (Gzipped Sizes)

✨ No significant bundle size changes detected.

📊 Summary of Totals

Category	PR Size	Base Size	Difference
Total JS	3649.56 KB	3649.55 KB	+0.01 KB (+0.00%)
Total CSS	287.99 KB	287.99 KB	0 B

[Aamod-Dev]

The \commit_clock\ view is a great addition — replacing the simulated 'Night Owl' metric with actual commit timestamps from \etchCommitHourDistribution\ in \lib/github.ts. The polar ring rendering in \lib/svg/commitClock.ts\ with opacity-scaled segments and peak-hour annotations looks premium. Integration with the route is clean. Nice work!

[Aamod-Dev]

Review

This PR cannot be approved in its current state due to blocking issues (status:blocked label, merge conflicts, needs-rebase label, and/or failing CI checks). Please resolve the blocking issues and re-request review.

Once unblocked, I'm happy to re-review! 💚