{
  "title": "52-Week Token Activity Calendar Heatmap",
  "description": "GitHub-style 52-week activity contribution grid for API token volume built with TanStack Charts.",
  "name": "tanstack-charts-heatmap-token-usage",
  "dependencies": [
    "@tanstack/charts",
    "@tanstack/react-charts",
    "d3-scale"
  ],
  "registryDependencies": [
    "card"
  ],
  "type": "registry:block",
  "files": [
    {
      "path": "components/blocks/tanstack-charts/heatmap/token-usage-calendar.tsx",
      "type": "registry:block",
      "content": "import { type ChartPoint, cell, defineChart } from \"@tanstack/charts\";\nimport { motion } from \"@tanstack/charts/motion\";\nimport { tooltip } from \"@tanstack/charts/tooltip\";\nimport { Chart } from \"@tanstack/react-charts/core\";\nimport { useMemo } from \"react\";\n\nimport { scaleBand, scaleOrdinal } from \"d3-scale\";\nimport { CalendarDays } from \"lucide-react\";\n\nimport { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from \"@/components/ui/card\";\n\ninterface CalendarCellDatum {\n    week: number;\n    weekday: string;\n    level: string;\n    dateKey: string;\n    tokens: number;\n}\n\nconst motionRenderer = motion({\n    initial: \"always\",\n    transition: { type: \"spring\", stiffness: 170, damping: 18, mass: 1 },\n});\n\nconst weekdays = [\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\", \"Sun\"];\nconst usageLevels = [\"none\", \"low\", \"medium\", \"high\", \"max\"];\nconst usageColors = [\"var(--border)\", \"var(--chart-1)\", \"var(--chart-2)\", \"var(--chart-3)\", \"var(--chart-4)\"];\n\nconst months = [\"Jan\", \"Feb\", \"Mar\", \"Apr\", \"May\", \"Jun\", \"Jul\", \"Aug\", \"Sep\", \"Oct\", \"Nov\", \"Dec\"];\n\nfunction generateDemoData(): CalendarCellDatum[] {\n    const results: CalendarCellDatum[] = [];\n    const baseDate = new Date(Date.UTC(2024, 0, 1));\n\n    for (let w = 0; w < 52; w++) {\n        for (let d = 0; d < 7; d++) {\n            const date = new Date(baseDate.getTime() + (w * 7 + d) * 24 * 60 * 60 * 1000);\n            const tokens = Math.floor(Math.random() * 120);\n            let level = \"none\";\n            if (tokens > 90) level = \"max\";\n            else if (tokens > 60) level = \"high\";\n            else if (tokens > 30) level = \"medium\";\n            else if (tokens > 5) level = \"low\";\n\n            results.push({\n                week: w,\n                weekday: weekdays[d],\n                level,\n                dateKey: date.toISOString().split(\"T\")[0],\n                tokens,\n            });\n        }\n    }\n    return results;\n}\n\nfunction shadcnTooltipContent<TDatum>(points: readonly ChartPoint<TDatum>[]) {\n    if (points.length === 0) return { title: \"\", rows: [] };\n    const d = points[0].datum as CalendarCellDatum;\n    if (!d) return { title: \"\", rows: [] };\n    return {\n        title: `${d.dateKey} (${d.weekday})`,\n        rows: [{ label: \"Token Usage\", value: `${d.tokens}k tokens`, color: \"var(--chart-1)\" }],\n    };\n}\n\nexport function TokenUsageCalendar() {\n    const data = useMemo(() => generateDemoData(), []);\n    const weekDomain = useMemo(() => Array.from({ length: 52 }, (_, i) => i), []);\n\n    const definition = useMemo(\n        () =>\n            defineChart(\n                {\n                    renderer: motionRenderer,\n                    marks: [\n                        cell(data, {\n                            id: \"calendar-cells\",\n                            x: \"week\",\n                            y: \"weekday\",\n                            color: \"level\",\n                            key: \"dateKey\",\n                            radius: 2,\n                        }),\n                    ],\n                    scales: {\n                        x: {\n                            scale: scaleBand<number>().domain(weekDomain).paddingInner(0.2),\n                            axis: {\n                                line: false,\n                                ticks: {\n                                    values: [0, 4, 8, 13, 17, 21, 26, 30, 34, 39, 43, 47],\n                                    format: (v: number) => months[Math.floor(v / 4.33)] || \"\",\n                                },\n                            },\n                        },\n                        y: {\n                            scale: scaleBand<string>().domain(weekdays).paddingInner(0.2),\n                            axis: {\n                                line: false,\n                                ticks: {\n                                    values: [\"Mon\", \"Wed\", \"Fri\"],\n                                },\n                            },\n                        },\n                    },\n                    color: {\n                        scale: scaleOrdinal<string, string>().domain(usageLevels).range(usageColors),\n                    },\n                    margin: { top: 24, right: 24, bottom: 32, left: 45 },\n                    theme: {\n                        foreground: \"var(--muted-foreground)\",\n                        grid: \"var(--border)\",\n                        background: \"transparent\",\n                    },\n                },\n                {\n                    keyboard: true,\n                    tooltip: {\n                        use: tooltip,\n                        className:\n                            \"font-sans shadow-none rounded-md bg-popover text-popover-foreground border p-2 text-xs\",\n                        anchor: \"pointer\",\n                        placement: \"auto\",\n                        content: (points) => shadcnTooltipContent(points),\n                    },\n                },\n            ),\n        [data, weekDomain],\n    );\n\n    return (\n        <Card className=\"w-full max-w-xl\">\n            <CardHeader>\n                <CardTitle>52-Week Token Activity Calendar Heatmap Grid</CardTitle>\n                <CardDescription>\n                    GitHub/GitLab contribution style matrix tracking daily API token volume\n                </CardDescription>\n            </CardHeader>\n            <CardContent>\n                <div className=\"h-[210px] w-full\">\n                    <Chart\n                        definition={definition}\n                        renderer={motionRenderer}\n                        height={210}\n                        ariaLabel=\"52-Week Token Activity Calendar Heatmap Grid Chart\"\n                    />\n                </div>\n            </CardContent>\n            <CardFooter className=\"flex-col items-start gap-2 text-sm\">\n                <div className=\"flex items-center gap-2 leading-none font-medium\">\n                    Daily token activity intensity mapped across 52 calendar weeks{\" \"}\n                    <CalendarDays className=\"h-4 w-4 text-emerald-500\" />\n                </div>\n                <div className=\"text-muted-foreground leading-none\">\n                    `cell` mark renders discrete categorical grid tiles scaled by ordinal levels\n                </div>\n            </CardFooter>\n        </Card>\n    );\n}\n\nexport default TokenUsageCalendar;\n"
    }
  ],
  "mcp": {
    "description": "Renders responsive data visualization with dark mode styling and customizable tooltips. GitHub-style 52-week activity contribution grid for API token volume built with TanStack Charts. Relies on card. Use when presenting data insights or analytics dashboards.",
    "tags": [
      "chart",
      "tanstack",
      "heatmap"
    ]
  }
}