🎯 Addon Information

Addon Name: Star History Charts
Category: GitHub Statistics
Difficulty: 🟢 Easy

Reference Links:

• Demo: https://star-history.com
• GitHub: https://github.com/star-history/star-history
• Documentation: https://github.com/star-history/star-history#readme

📝 Description

Star History generates beautiful charts showing the star growth of GitHub repositories over time. Perfect for showcasing project popularity and growth trends.

Example Use Cases:

• Show multiple project star histories side-by-side
• Compare your projects with competitors
• Demonstrate project growth in presentations
• Add visual proof of project success to README

What it looks like:

✅ Implementation Checklist

UI Components

• Add "Star History" collapsible section under "GitHub Statistics"
• Create multi-repository input field (comma-separated)
• Add chart type selector (Date vs Timeline)
• Add theme toggle (Light/Dark)
• Implement live preview component

URL Generation

• Create generateStarHistoryURL() function
• Validate repository format (owner/repo)
• Handle multiple repositories
• Add theme parameter support
• Handle edge cases (invalid repos, too many repos)

Integration

• Add to markdown generator
• Integrate with storage system
• Add StarHistoryConfig type to profile types
• Test with existing GitHub statistics widgets

Preview & Polish

• Implement live preview with actual chart
• Add loading state while preview loads
• Handle preview errors gracefully
• Test in both dark and light themes

Documentation

• Add "How to find repo names" tooltip
• Link to Star History documentation
• Add example in help text

Testing

• Unit tests for URL generation
• Test with 1-5 repositories
• Test with invalid repository names
• Mobile responsive testing
• Accessibility testing

💻 Technical Details

Parameters

Generated URL Format

https://api.star-history.com/svg?repos=owner/repo1,owner/repo2&type=Date&theme=dark

Example Code

// URL Builder Function
interface StarHistoryParams {
  repos: string[];
  type?: 'Date' | 'Timeline';
  theme?: 'light' | 'dark';
}

const generateStarHistoryURL = (params: StarHistoryParams): string => {
  const searchParams = new URLSearchParams({
    repos: params.repos.join(','),
    type: params.type || 'Date',
  });

  if (params.theme === 'dark') {
    searchParams.append('theme', 'dark');
  }

  return `https://api.star-history.com/svg?${searchParams}`;
};

// Validation
const validateRepoFormat = (repo: string): boolean => {
  return /^[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+$/.test(repo);
};

🎨 UI Mockup

📊 GitHub Statistics [Collapse]

  ⭐ Star History
    └─ [ ] Show Star History Chart
    └─ Repositories (comma-separated):
        [owner/repo1, owner/repo2, ...]
        💡 Example: facebook/react, vuejs/vue
    └─ Chart Type: ⚪ Date  ⚪ Timeline
    └─ Theme: ⚪ Light  ⚪ Dark  ⚪ Auto (match profile)
    └─ Preview:
        [Live chart preview or loading state]

    Generated Markdown:
    ```markdown
    [![Star History](https://api.star-history.com/svg?repos=...)]
    ```

📸 Example Output

Markdown (Light Theme)

[![Star History Chart](https://api.star-history.com/svg?repos=facebook/react,vuejs/vue&type=Date)](https://star-history.com/#facebook/react&vuejs/vue&Date)

Markdown (Dark Theme with Picture Tag)

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=facebook/react,vuejs/vue&type=Date&theme=dark" />
  <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=facebook/react,vuejs/vue&type=Date" />
  <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=facebook/react,vuejs/vue&type=Date" />
</picture>

🔍 Acceptance Criteria

• User can enable/disable Star History
• User can enter 1-5 repositories
• Chart type selector works
• Theme selection works
• Live preview updates on input change
• Generated markdown is valid
• Works on mobile devices
• Accessible via keyboard
• Dark/light theme support
• Invalid repo format shows error
• Help tooltip present
• Links to Star History docs

🐛 Edge Cases to Consider

• Invalid repository format (missing slash, special chars)
• Too many repositories (>10)
• Repository doesn't exist
• Private repositories
• Very long repository names
• Empty input
• Whitespace in repo names

📚 Resources

• Similar Implementations: GitHub Stats widgets
• Star History API: No official API docs, URL-based
• Community Examples: https://github.com/rzashakeri/beautify-github-profile

💬 Questions?

Join our Discord for help: https://discord.gg/HHMs7Eg

📝 Notes for Contributors

Good first issue because:

• Simple URL generation (no complex API)
• Clear parameters and format
• No authentication required
• Good documentation available
• Similar patterns exist in codebase

Files to modify:

• src/components/sections/github-stats-section.tsx - Add UI
• src/lib/markdown-generator.ts - Add markdown generation
• src/types/profile.ts - Add StarHistoryConfig type
• src/lib/validations.ts - Add repo format validation

Helpful patterns to reference:

• Look at github-stats.tsx for similar URL generation
• Check existing form components in src/components/forms/
• Follow theme pattern from other GitHub widgets

Testing your implementation:

1. Try with your own repos
2. Test with popular repos (facebook/react, microsoft/vscode)
3. Verify theme switching works
4. Check preview on mobile
5. Test with invalid inputs