{"_id":"@animesh0764/contribution-graph","name":"@animesh0764/contribution-graph","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@animesh0764/contribution-graph","version":"0.1.0","description":"GitHub-style contribution graphs for any application — no dependencies, TypeScript-first","keywords":["contribution","graph","heatmap","github","activity","calendar","streak","react","visualization"],"author":{"name":"Animesh Singh"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Animesh0764/contribution-graph-npm-package.git"},"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.mjs","require":"./dist/react/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"peerDependencies":{"react":">=17.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"devDependencies":{"@types/react":"^18.0.0","@vitest/coverage-v8":"^2.0.0","react":"^18.0.0","tsup":"^8.0.0","typescript":"^5.0.0","vitest":"^2.0.0"},"_id":"@animesh0764/contribution-graph@0.1.0","gitHead":"041b7266878f4a97754f8dfddae66fc066493634","bugs":{"url":"https://github.com/Animesh0764/contribution-graph-npm-package/issues"},"homepage":"https://github.com/Animesh0764/contribution-graph-npm-package#readme","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-uuFt9H0JDALB6VdzGpYj4BBqYzLaj5/1Cor6gljXMBcUP8AEvD4XkA6+wh71d4c+XiUzVcM0RlCWhggMqJoaPA==","shasum":"5a97c02a2ebf6d36afc5caf533f8d7ba0357e422","tarball":"https://registry.npmjs.org/@animesh0764/contribution-graph/-/contribution-graph-0.1.0.tgz","fileCount":19,"unpackedSize":115149,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@animesh0764%2fcontribution-graph@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCo40eKVnND4NGeYa+whDENPI/s6Ldst1+oaMgi8McOVwIhAPBXtcerwXhSaYG/Cj4kSiZv6VYMAUYAn+abfe9sGV6h"}]},"_npmUser":{"name":"animesh0764","email":"animeshbksingh@outlook.com"},"directories":{},"maintainers":[{"name":"animesh0764","email":"animeshbksingh@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/contribution-graph_0.1.0_1780562790378_0.2327065350471298"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-04T08:46:30.219Z","0.1.0":"2026-06-04T08:46:30.510Z","modified":"2026-06-04T08:46:30.898Z"},"maintainers":[{"name":"animesh0764","email":"animeshbksingh@outlook.com"}],"description":"GitHub-style contribution graphs for any application — no dependencies, TypeScript-first","homepage":"https://github.com/Animesh0764/contribution-graph-npm-package#readme","keywords":["contribution","graph","heatmap","github","activity","calendar","streak","react","visualization"],"repository":{"type":"git","url":"git+https://github.com/Animesh0764/contribution-graph-npm-package.git"},"author":{"name":"Animesh Singh"},"bugs":{"url":"https://github.com/Animesh0764/contribution-graph-npm-package/issues"},"license":"MIT","readme":"# contribution-graph\n\nGitHub-style contribution graphs for any application. No dependencies. TypeScript-first.\n\n## Install\n\n```bash\nnpm install @animesh0764/contribution-graph\n```\n\n## Quick start\n\n### Core (framework-agnostic)\n\n```ts\nimport { buildContributionGraph } from '@animesh0764/contribution-graph'\n\nconst data = buildContributionGraph([\n  '2026-01-15',\n  '2026-01-16',\n  { date: '2026-01-17', count: 5 },\n])\n\nconsole.log(data.stats.currentStreak)    // number\nconsole.log(data.stats.totalContributions) // number\n```\n\n### React component\n\n```tsx\nimport { buildContributionGraph } from '@animesh0764/contribution-graph'\nimport { ContributionGraph } from '@animesh0764/contribution-graph/react'\n\nconst data = buildContributionGraph(events)\n\n<ContributionGraph data={data} theme=\"github-dark\" />\n```\n\n## API\n\n### `buildContributionGraph(events, options?)`\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `events` | `ContributionInput[]` | Activity data. Strings (`YYYY-MM-DD`), `Date` objects, or `{ date, count }` objects. |\n| `options` | `ContributionOptions` | Optional config (see below). |\n\n**Returns** `ContributionGraphData`:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `cells` | `ContributionCell[]` | One entry per calendar day in the range (including padding days). |\n| `weeks` | `ContributionWeek[]` | Cells grouped into week columns (ready for rendering). |\n| `monthLabels` | `MonthLabel[]` | Month name + grid column index for positioning labels. |\n| `stats` | `ContributionStats` | Aggregated statistics (see below). |\n| `from` | `string` | Actual aligned start date (`YYYY-MM-DD`). |\n| `to` | `string` | End date used (`YYYY-MM-DD`). |\n| `weekStartsOn` | `0 \\| 1` | `0` = Sunday, `1` = Monday. |\n\n### Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `from` | `string` | 364 days before `to` | Start of the date range (`YYYY-MM-DD`). |\n| `to` | `string` | today | End of the date range (`YYYY-MM-DD`). |\n| `timezone` | `string` | system local | IANA timezone e.g. `'America/New_York'`. |\n| `weekStartsOn` | `0 \\| 1` | `0` | `0` = Sunday (GitHub default), `1` = Monday. |\n\n### `ContributionStats`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `totalContributions` | `number` | Sum of all activity counts in range. |\n| `activeDays` | `number` | Days with at least one contribution. |\n| `currentStreak` | `number` | Consecutive days ending today (or yesterday). |\n| `longestStreak` | `number` | Longest streak of consecutive active days. |\n| `mostActiveDate` | `string \\| null` | Date with the highest single-day count. |\n| `mostActiveCount` | `number` | Count on the most active day. |\n| `weeklyAverage` | `number` | Average contributions per week over the range. |\n| `monthlyBreakdown` | `MonthBreakdown[]` | Per-month totals and active day counts. |\n\n### `ContributionCell`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `date` | `string` | `YYYY-MM-DD`. |\n| `count` | `number` | Activity count for this day. |\n| `level` | `0–4` | Intensity level (0 = no activity, 4 = highest quartile). |\n| `weekIndex` | `number` | Column index in the grid. |\n| `dayOfWeek` | `number` | Row index (0 = first day of week). |\n| `isOutOfRange` | `boolean` | `true` for padding cells outside `[from, to]`. |\n\n## React component\n\n```tsx\nimport { ContributionGraph } from '@animesh0764/contribution-graph/react'\n\n<ContributionGraph\n  data={data}\n  theme=\"github\"          // or \"github-dark\" or a custom theme object\n  blockSize={12}          // px, default 12\n  blockGap={3}            // px, default 3\n  showMonthLabels={true}\n  showWeekdayLabels={true}\n  showTooltip={true}\n  onDayClick={(cell) => console.log(cell)}\n/>\n```\n\n### Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `data` | `ContributionGraphData` | — | Output from `buildContributionGraph`. |\n| `theme` | `'github' \\| 'github-dark' \\| ContributionTheme` | `'github'` | Color theme. |\n| `blockSize` | `number` | `12` | Size of each day square in px. |\n| `blockGap` | `number` | `3` | Gap between squares in px. |\n| `showMonthLabels` | `boolean` | `true` | Show month names above the grid. |\n| `showWeekdayLabels` | `boolean` | `true` | Show Mon/Wed/Fri labels on the left. |\n| `showTooltip` | `boolean` | `true` | Show hover tooltip with date + count. |\n| `onDayClick` | `(cell: ContributionCell) => void` | — | Click handler for day cells. |\n| `style` | `CSSProperties` | — | Inline styles for the container. |\n| `className` | `string` | — | CSS class for the container. |\n\n### Custom theme\n\n```ts\nimport type { ContributionTheme } from '@animesh0764/contribution-graph'\n\nconst myTheme: ContributionTheme = {\n  level0: '#f0f0f0',\n  level1: '#c6e8ff',\n  level2: '#79c9ff',\n  level3: '#1e9cff',\n  level4: '#0065cc',\n  background: '#ffffff',\n  text: '#333333',\n}\n```\n\n## Intensity levels\n\nActivity intensity is computed using a quartile distribution across the active days in your range. This means the colour scale adapts to your data volume: someone who makes 1–5 contributions/day gets the same visual spread as someone who makes 100+/day.\n\n- **Level 0** — no activity\n- **Level 1** — bottom 25% of active days\n- **Level 2** — 25th–50th percentile\n- **Level 3** — 50th–75th percentile\n- **Level 4** — top 25%\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-08308c3d29f7f567bafb373feeec8159"}