@danielwh2/contribution-graph 1.0.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Belyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# contribution-graph
+
+<p>
+  <a href="https://www.npmjs.com/package/contribution-graph"><img src="https://img.shields.io/npm/v/contribution-graph?color=cb3837&label=npm" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/framework-agnostic-22c55e" alt="framework agnostic">
+  <img src="https://img.shields.io/badge/bundle-7kB-8b5cf6" alt="bundle size">
+  <img src="https://img.shields.io/badge/react-✓-61dafb" alt="react">
+  <img src="https://img.shields.io/badge/vue-✓-42b883" alt="vue">
+  <img src="https://img.shields.io/badge/solid-✓-2c4f7c" alt="solid">
+  <img src="https://img.shields.io/badge/svelte-✓-ff3e00" alt="svelte">
+  <img src="https://img.shields.io/badge/typescript-✓-3178c6" alt="typescript">
+</p>
+
+Framework-agnostic GitHub-style contribution heatmap for any app.
+
+Render a year of activity into any element as a crisp SVG or HTML grid — week
+columns, day rows, month labels, weekday labels, intensity colors, smooth
+slot-text tooltips, custom cell colors, and click handlers.
+
+## 📦 Install
+
+```bash
+npm install contribution-graph
+```
+
+```bash
+pnpm add contribution-graph
+```
+
+```bash
+bun add contribution-graph
+```
+
+```bash
+yarn add contribution-graph
+```
+
+## 🚀 Quick start
+
+```ts
+import "contribution-graph/style.css";
+import { contributionGraph } from "contribution-graph";
+
+const data = [
+  { date: "2026-06-01", count: 3 },
+  { date: "2026-06-02", count: 7 },
+  // ...one entry per day with contributions
+];
+
+const graph = contributionGraph(document.querySelector("#graph")!, data, {
+  until: "2026-06-22",
+  onCellClick: (day) => console.log(day.date, day.count),
+});
+
+graph.set(newData); // update
+graph.destroy();    // clean up
+```
+
+Import the CSS once, pass your data, get a heatmap. That's it.
+
+## 🧩 API
+
+```ts
+interface ContributionDay {
+  date: string;   // YYYY-MM-DD
+  count: number;
+  color?: string; // optional per-cell color override
+}
+
+interface ContributionGraphController {
+  readonly element: HTMLElement;
+  set(data: ContributionDay[], options?: ContributionGraphOptions): void;
+  destroy(): void;
+}
+
+function contributionGraph(
+  element: HTMLElement,
+  data: ContributionDay[],
+  options?: ContributionGraphOptions,
+): ContributionGraphController;
+```
+
+| Method | What it does |
+| --- | --- |
+| `set(data, options?)` | Re-render with new data and/or options |
+| `destroy()` | Remove the graph and clean up listeners |
+
+## ⚛️ React
+
+```tsx
+import "contribution-graph/style.css";
+import { ContributionGraph } from "contribution-graph/react";
+
+<ContributionGraph
+  data={data}
+  options={{ until: "2026-06-22", onCellClick: (day) => alert(day.date) }}
+/>
+```
+
+## 💚 Vue
+
+```vue
+<script setup lang="ts">
+import "contribution-graph/style.css";
+import { ContributionGraph } from "contribution-graph/vue";
+</script>
+
+<template>
+  <ContributionGraph :data="data" :options="{ until: '2026-06-22' }" />
+</template>
+```
+
+## 🔷 Solid
+
+```tsx
+import "contribution-graph/style.css";
+import { contributionGraph } from "contribution-graph/solid";
+
+<div use:contributionGraph={{ data, options: { until: "2026-06-22" } }} />
+```
+
+## 🧡 Svelte
+
+```svelte
+<script lang="ts">
+  import "contribution-graph/style.css";
+  import { contributionGraph } from "contribution-graph/svelte";
+</script>
+
+<div use:contributionGraph={{ data, options: { until: "2026-06-22" } }} />
+```
+
+## ⚙️ Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `weeks` | `53` | Number of week columns |
+| `cellSize` | `11` | Cell size in px |
+| `cellGap` | `3` | Gap between cells in px |
+| `cellRadius` | `3` | Cell corner radius in px |
+| `colors` | GitHub greens | Colors from least to most active (length = `levels`) |
+| `levels` | `5` | Intensity levels including the empty level |
+| `showLabels` | `true` | Show month and weekday labels |
+| `labelColor` | `#8b949e` | Label text color |
+| `labelFontSize` | `11` | Label font size in px |
+| `until` | today (UTC) | End date of the range, `Date` or `YYYY-MM-DD` |
+| `tooltip` | — | `(day) => string \| null` for smooth popup tooltips |
+| `onCellClick` | — | `(day) => void` — `day` has `date`, `count`, `level` |
+| `showCounts` | `false` | Use HTML cells. Pair with `countFontSize` to show in-cell counts |
+| `countColors` | auto-contrasted | Text colors per level for in-cell count labels |
+| `countFontSize` | `0` | Count label font size in px. `0` hides in-cell counts |
+| `monthLabels` | `["Jan", "Feb", ...]` | Array of 12 month labels. Use `""` to hide a month |
+| `weekdayLabels` | `["Mon", "", "Wed", ...]` | Array of 7 weekday labels (Mon..Sun). Use `""` to hide a row |
+| `weekStart` | `1` | First day of each column: `0` = Sunday, `1` = Monday |
+| `hud` | `false` | Wrap the graph in the cinematic "GIT COMMITS" HUD (see below) |
+| `profile` | `false` | Wrap the graph in a sleek luxury GitHub profile widget (see below) |
+
+### 💎 Profile mode (Luxury)
+
+Set `profile: { username: "yourname" }` to wrap the component in a stunning dark-mode GitHub profile card. It mimics the classic GitHub UI but elevates it with a deep `#0d1117` background, floating drop shadows, a smooth glowing effect on the activity cells, and a bold activity count.
+
+```ts
+import "contribution-graph/style.css";
+
+contributionGraph(el, data, {
+  profile: { username: "zzzzshawn" },
+  until: "2026-06-22"
+});
+```
+
+### 🛰️ HUD mode
+
+Set `hud: true` to render the graph inside a cinematic heads-up display: a
+corner-bracketed glass panel over an animated teal→ember glitch backdrop, with
+auto-computed week stats and commit streak rolling in via
+[slot-text](https://www.npmjs.com/package/slot-text).
+
+```ts
+import "contribution-graph/style.css";
+import "slot-text/style.css"; // required — powers the rolling numbers
+
+contributionGraph(el, data, { hud: true, until: "2026-06-22" });
+```
+
+The HUD derives everything it shows straight from your data — **this week** and
+**last week** totals, the delta %, and the current **day streak** (with delta
+coloring: green when up, amber when down). It applies its own monochrome,
+Sunday-first, single-letter-weekday defaults; any explicit option above still
+overrides them (e.g. pass `colors` for a different ramp, or `cellSize`). The
+whole HUD is scoped inside the host element, so size and place it like any
+other block.
+
+### 🎨 Custom colors
+
+```ts
+contributionGraph(el, data, {
+  colors: ["#ebedf0", "#c6e48b", "#7bc96f", "#239a3b", "#196127"],
+  levels: 5,
+});
+```
+
+Any palette works — pass 5 colors for 5 levels, 4 for 4, etc. The first color
+is always the "no contributions" color.
+
+To override the color of **individual specific cells**, pass a `color` string in your data:
+
+```ts
+const data = [
+  { date: "2026-06-21", count: 12 },
+  { date: "2026-06-22", count: 50, color: "#ff0000" }, // specific override
+];
+```
+
+### GitHub contribution data
+
+GitHub's contribution calendar is available through the official GraphQL API. Use the exported helper to fetch and normalize it into `ContributionDay[]`:
+
+```ts
+import { contributionGraph, fetchGitHubContributions } from "contribution-graph";
+
+const result = await fetchGitHubContributions({
+  username: "octocat",
+  token: process.env.GITHUB_TOKEN,
+  from: "2026-01-01",
+  to: "2026-12-31",
+});
+
+contributionGraph(el, result.data, {
+  until: result.to,
+});
+```
+
+For browser apps, do not ship a GitHub token to users. Call `fetchGitHubContributions()` from your server with `token`, or call a safe server proxy from the browser with `endpoint` and no token. The helper only sends `token` to GitHub's official GraphQL endpoint:
+
+```ts
+const result = await fetchGitHubContributions({
+  username: "octocat",
+  endpoint: "/api/github-contributions",
+});
+```
+
+If you want to preserve GitHub's per-day colors instead of using your palette, set `includeGitHubColors: true`.
+
+### 💬 Tooltips
+
+```ts
+contributionGraph(el, data, {
+  tooltip: (day) =>
+    day.count === 0
+      ? `No contributions on ${day.dateLabel}`
+      : `${day.count} contributions on ${day.dateLabel}`,
+});
+```
+
+Each `day` carries `date` (raw `YYYY-MM-DD`), `count`, `level`, and
+`dateLabel` — a human-readable UTC date produced with
+[dayjs](https://dayjs.dev) (e.g. `Jun 22, 2026`). Return `null` to disable
+the tooltip for a given day.
+
+### 🖱️ Click handling
+
+```ts
+contributionGraph(el, data, {
+  onCellClick: (day) => {
+    console.log(day.date, day.dateLabel, day.count, day.level);
+  },
+});
+```
+
+### 🔢 HTML mode and optional count labels
+
+Set `showCounts: true` to render cells as HTML elements instead of SVG. Counts
+stay hidden by default for compact graphs. Add `countFontSize` to show animated
+in-cell count labels powered by [slot-text](https://www.npmjs.com/package/slot-text).
+
+```ts
+import "contribution-graph/style.css";
+import "slot-text/style.css";
+import { contributionGraph } from "contribution-graph";
+
+const graph = contributionGraph(el, data, {
+  showCounts: true,
+  countFontSize: 9,
+  until: "2026-06-22",
+});
+
+graph.set(newData);
+```
+
+Text colors auto-contrast with the cell background. Override with `countColors`:
+
+```ts
+contributionGraph(el, data, {
+  showCounts: true,
+  countFontSize: 9,
+  colors: ["#ebedf0", "#9be9a8", "#40c463", "#30a14e", "#216e39"],
+  countColors: ["#57606a", "#1f2328", "#1f2328", "#ffffff", "#ffffff"],
+});
+```
+
+## 📅 Date handling
+
+All date math uses **UTC** so graphs render identically in every timezone.
+Weeks start on **Sunday** (GitHub convention). The range ends at `until` and is
+snapped back so the first column begins on a Sunday. Days beyond `until` in the
+final week are omitted.
+
+Data entries are matched by `YYYY-MM-DD`; days with no entry default to count 0.
+Human-readable labels (tooltip/click `day.dateLabel`) are formatted with dayjs
+in UTC mode via the exported `formatHumanDate` helper.
+
+## 📝 Notes
+
+- Browser-only DOM utility with no framework runtime dependency.
+- Smooth tooltips and optional in-cell count labels are powered by `slot-text`.
+- React, Vue, Solid, and Svelte are optional peer dependencies — plain JS users
+  don't need them.
+- Import `contribution-graph/style.css` once before rendering. Import
+  `slot-text/style.css` when you use the animated tooltip or count label styles.
+- Low-level helpers also exported: `buildGraph`, `clearGraph`, `buildHtmlGraph`,
+  `clearHtmlGraph`, `buildHudGraph`, `clearHudGraph`, `computeGrid`,
+  `levelForCount`, `parseDate`, `formatDate`, `formatHumanDate`,
+  `resolveOptions`, `fetchGitHubContributions`.
+
+## License
+
+MIT

package/dist/contributionGraph.d.ts

@@ -0,0 +1,150 @@
+/**
+ * contribution-graph core — GitHub-style heatmap renderer.
+ *
+ * Renders an SVG contribution graph into a host element. All date math uses
+ * UTC to stay timezone-stable; weeks start on Sunday (GitHub convention).
+ * Human-readable date labels are produced with dayjs (UTC mode).
+ */
+export interface ContributionDay {
+    /** ISO date: YYYY-MM-DD. */
+    date: string;
+    /** Number of contributions that day. */
+    count: number;
+    /** Optional custom color for this specific cell. Overrides the level-based color. */
+    color?: string;
+}
+export interface ContributionGraphOptions {
+    /** Number of week columns (default 53). */
+    weeks?: number;
+    /** First day of each week column: 0 = Sunday, 1 = Monday (default 1). */
+    weekStart?: 0 | 1;
+    /** Cell size in px (default 11). */
+    cellSize?: number;
+    /** Gap between cells in px (default 3). */
+    cellGap?: number;
+    /** Cell corner radius in px (default 2). */
+    cellRadius?: number;
+    /** Colors from least to most active, length = levels (default GitHub greens). */
+    colors?: string[];
+    /** Number of intensity levels including the empty level (default 5). */
+    levels?: number;
+    /** Show month and weekday labels (default true). */
+    showLabels?: boolean;
+    /** Show month labels along the top (default follows showLabels). */
+    showMonthLabels?: boolean;
+    /** Show weekday labels along the left (default follows showLabels). */
+    showWeekdayLabels?: boolean;
+    /** Label text color (default "#8b949e"). */
+    labelColor?: string;
+    /** Label font size in px (default 10). */
+    labelFontSize?: number;
+    /** End date of the range, as Date or ISO string (default today, UTC). */
+    until?: Date | string;
+    /** Custom tooltip text. Return null to disable the tooltip. */
+    tooltip?: (day: ContributionDayContext) => string | null;
+    /** Called when a cell is clicked. */
+    onCellClick?: (day: ContributionDayContext) => void;
+    /** Render HTML cells instead of SVG cells (default false). */
+    showCounts?: boolean;
+    /** Text colors per level for optional count labels (default: auto-contrasted). */
+    countColors?: string[];
+    /** Count label font size in px. Set 0 to hide labels (default 0). */
+    countFontSize?: number;
+    /** Array of 12 month labels. Empty strings hide the month. */
+    monthLabels?: string[];
+    /**
+     * Array of 7 weekday labels, row order Mon..Sun. Empty strings hide that row's
+     * label (default ["Mon", "", "Wed", "", "Fri", "", ""]).
+     */
+    weekdayLabels?: string[];
+    /**
+     * Wrap the graph in the cinematic "GIT COMMITS" HUD: corner-bracketed glass
+     * panel, animated glitch backdrop, auto-computed week stats + streak, and
+     * rolling numbers. Applies its own monochrome, Sunday-first defaults which
+     * any explicit option above still overrides (default false).
+     */
+    hud?: boolean;
+    /**
+     * Wrap the graph in a luxury GitHub profile widget.
+     */
+    profile?: boolean | {
+        username?: string;
+    };
+}
+/** Parse a YYYY-MM-DD string into a UTC midnight Date. */
+export declare function parseDate(value: string): Date;
+/** Format a UTC Date as YYYY-MM-DD. */
+export declare function formatDate(date: Date): string;
+/**
+ * Format a YYYY-MM-DD date as a human-readable label in UTC, e.g.
+ * "Jun 22, 2026". Used for tooltip/click-handler context so consumers don't
+ * have to format ISO strings themselves.
+ */
+export declare function formatHumanDate(date: string): string;
+/**
+ * A contribution day augmented with the context callbacks receive: the
+ * intensity level and a human-readable date label.
+ */
+export interface ContributionDayContext extends ContributionDay {
+    /** Intensity level 0..levels-1. */
+    level: number;
+    /** Human-readable date label, e.g. "Jun 22, 2026" (UTC). */
+    dateLabel: string;
+}
+export interface ResolvedOptions {
+    weeks: number;
+    weekStart: 0 | 1;
+    cellSize: number;
+    cellGap: number;
+    cellRadius: number;
+    colors: string[];
+    levels: number;
+    showLabels: boolean;
+    showMonthLabels: boolean;
+    showWeekdayLabels: boolean;
+    labelColor: string;
+    labelFontSize: number;
+    until: Date;
+    showCounts: boolean;
+    countColors?: string[];
+    countFontSize: number;
+    monthLabels: string[];
+    weekdayLabels: string[];
+    tooltip?: (day: ContributionDayContext) => string | null;
+    onCellClick?: (day: ContributionDayContext) => void;
+}
+export declare function resolveOptions(options?: ContributionGraphOptions): ResolvedOptions;
+export interface GridCell extends ContributionDay {
+    /** Intensity level 0..levels-1. */
+    level: number;
+    /** Column index (week). */
+    week: number;
+    /** Row index (day of week, 0 = Sunday). */
+    day: number;
+}
+export interface Grid {
+    cells: GridCell[];
+    weeks: number;
+    /** Month label entries: { label, xOffset } relative to the grid start. */
+    months: {
+        label: string;
+        col: number;
+    }[];
+    max: number;
+    totalCols: number;
+}
+/**
+ * Build the grid for a date range ending at `opts.until`, spanning `opts.weeks`
+ * week columns. The range is snapped back so the first column starts on Monday.
+ */
+export declare function computeGrid(data: ContributionDay[], opts: ResolvedOptions): Grid;
+/** Map a count to an intensity level 0..levels-1. */
+export declare function levelForCount(count: number, max: number, levels: number): number;
+export declare function normalizeCssColor(value: string | undefined, fallback: string): string;
+/**
+ * Render the graph SVG into `element`. Replaces prior content.
+ * Returns the SVG element for callers that need to attach listeners.
+ */
+export declare function buildGraph(element: HTMLElement, data: ContributionDay[], options?: ContributionGraphOptions): SVGElement;
+/** Remove the rendered graph and root class. */
+export declare function clearGraph(element: HTMLElement): void;