@danielwh2/contribution-graph 1.0.14

package/dist/contributionGraph.js

@@ -0,0 +1,328 @@
+/**
+ * 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).
+ */
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+dayjs.extend(utc);
+const DEFAULT_COLORS = [
+    "#ebedf0",
+    "#9be9a8",
+    "#40c463",
+    "#30a14e",
+    "#216e39",
+];
+const WEEKDAY_LABELS = ["Mon", "", "Wed", "", "Fri", "", ""];
+const MONTH_LABELS = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+const NS = "http://www.w3.org/2000/svg";
+const ROOT_CLASS = "contribution-graph";
+/** Parse a YYYY-MM-DD string into a UTC midnight Date. */
+export function parseDate(value) {
+    const [y, m, d] = value.split("-").map(Number);
+    return new Date(Date.UTC(y, m - 1, d));
+}
+/** Format a UTC Date as YYYY-MM-DD. */
+export function formatDate(date) {
+    const y = date.getUTCFullYear();
+    const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(date.getUTCDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+}
+/**
+ * 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 function formatHumanDate(date) {
+    return dayjs.utc(date).format("MMM D, YYYY");
+}
+/**
+ * Row index of a UTC date within its week column, given the week-start day.
+ * weekStart=1 (Monday) → Mon=0 … Sun=6; weekStart=0 (Sunday) → Sun=0 … Sat=6.
+ */
+function utcDay(date, weekStart = 1) {
+    return (date.getUTCDay() - weekStart + 7) % 7;
+}
+/** Add n UTC days to a date. */
+function addDays(date, days) {
+    const next = new Date(date.getTime());
+    next.setUTCDate(next.getUTCDate() + days);
+    return next;
+}
+export function resolveOptions(options = {}) {
+    const levels = options.levels ?? 5;
+    const colors = options.colors ?? DEFAULT_COLORS;
+    const showCounts = options.showCounts ?? false;
+    const cellSize = options.cellSize ?? 11;
+    const showLabels = options.showLabels ?? true;
+    return {
+        showCounts,
+        weeks: options.weeks ?? 53,
+        weekStart: options.weekStart === 0 ? 0 : 1,
+        cellSize,
+        cellGap: options.cellGap ?? 3,
+        cellRadius: options.cellRadius ?? 3,
+        colors: colors.length >= levels ? colors : DEFAULT_COLORS,
+        levels,
+        showLabels,
+        showMonthLabels: options.showMonthLabels ?? showLabels,
+        showWeekdayLabels: options.showWeekdayLabels ?? showLabels,
+        labelColor: options.labelColor ?? "#a1a1aa",
+        labelFontSize: options.labelFontSize ?? 11,
+        countColors: options.countColors,
+        countFontSize: options.countFontSize ?? 0,
+        monthLabels: options.monthLabels ?? MONTH_LABELS,
+        weekdayLabels: normalizeWeekdayLabels(options.weekdayLabels),
+        until: normalizeUntil(options.until),
+        tooltip: options.tooltip,
+        onCellClick: options.onCellClick,
+    };
+}
+/** Coerce a weekday-label override to exactly 7 entries (Mon..Sun). */
+function normalizeWeekdayLabels(labels) {
+    if (!labels)
+        return WEEKDAY_LABELS;
+    return Array.from({ length: 7 }, (_, i) => labels[i] ?? "");
+}
+function normalizeUntil(until) {
+    if (until instanceof Date)
+        return new Date(until.getTime());
+    if (typeof until === "string")
+        return parseDate(until);
+    const now = new Date();
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+/**
+ * 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 function computeGrid(data, opts) {
+    const counts = new Map();
+    let max = 0;
+    for (const d of data) {
+        counts.set(d.date, d.count);
+        if (d.count > max)
+            max = d.count;
+    }
+    // End at the last day of the week containing `until`.
+    const end = addDays(opts.until, 6 - utcDay(opts.until, opts.weekStart));
+    // Start `weeks*7 - 1` days earlier, then snap to the week-start day.
+    const rawStart = addDays(end, -(opts.weeks * 7 - 1));
+    const start = addDays(rawStart, -utcDay(rawStart, opts.weekStart));
+    const cells = [];
+    const months = [];
+    const actualWeeks = Math.round((end.getTime() - start.getTime()) / 86400000 / 7) + 1;
+    let lastMonth = start.getUTCMonth();
+    for (let w = 0; w < actualWeeks; w++) {
+        const firstDayOfWeek = addDays(start, w * 7);
+        const month = firstDayOfWeek.getUTCMonth();
+        if (month !== lastMonth && w > 0) {
+            months.push({ label: opts.monthLabels[month], col: w });
+            lastMonth = month;
+        }
+        else if (w === 0) {
+            months.push({ label: opts.monthLabels[month], col: w });
+        }
+        for (let d = 0; d < 7; d++) {
+            const date = addDays(start, w * 7 + d);
+            if (date > end)
+                continue;
+            const key = formatDate(date);
+            const currentDay = data.find(item => item.date === key);
+            const count = counts.get(key) ?? 0;
+            cells.push({
+                date: key,
+                count: currentDay ? currentDay.count : count,
+                level: levelForCount(count, max, opts.levels),
+                color: currentDay?.color,
+                week: w,
+                day: d,
+            });
+        }
+    }
+    return { cells, weeks: actualWeeks, months, max, totalCols: actualWeeks };
+}
+/** Map a count to an intensity level 0..levels-1. */
+export function levelForCount(count, max, levels) {
+    if (count <= 0)
+        return 0;
+    if (max <= 0)
+        return 0;
+    // Even division across the active levels 1..levels-1.
+    const step = max / (levels - 1);
+    let level = Math.ceil(count / step);
+    if (level < 1)
+        level = 1;
+    if (level > levels - 1)
+        level = levels - 1;
+    return level;
+}
+export function normalizeCssColor(value, fallback) {
+    const color = value?.trim();
+    if (!color)
+        return fallback;
+    if (/["'<>;\\]/.test(color) || /url\s*\(/i.test(color))
+        return fallback;
+    if (typeof CSS !== "undefined" && typeof CSS.supports === "function") {
+        return CSS.supports("color", color) ? color : fallback;
+    }
+    if (/^#[0-9a-f]{3,8}$/i.test(color))
+        return color;
+    if (/^[a-z]+$/i.test(color))
+        return color;
+    if (/^(?:rgb|rgba|hsl|hsla)\([\d\s.,%/-]+\)$/i.test(color))
+        return color;
+    return fallback;
+}
+function cellColor(cell, opts) {
+    const paletteFallback = normalizeCssColor(opts.colors[cell.level] ?? opts.colors[0], DEFAULT_COLORS[0]);
+    return normalizeCssColor(cell.color, paletteFallback);
+}
+/**
+ * Render the graph SVG into `element`. Replaces prior content.
+ * Returns the SVG element for callers that need to attach listeners.
+ */
+export function buildGraph(element, data, options = {}) {
+    const opts = resolveOptions(options);
+    const grid = computeGrid(data, opts);
+    const svg = renderSvg(grid, opts);
+    clearGraph(element);
+    element.classList.add(ROOT_CLASS);
+    element.appendChild(svg);
+    if (opts.onCellClick)
+        attachClickHandler(svg, opts.onCellClick);
+    return svg;
+}
+/** Remove the rendered graph and root class. */
+export function clearGraph(element) {
+    element.classList.remove(ROOT_CLASS);
+    element.replaceChildren();
+}
+const LABEL_FONT_FAMILY = "Geist Mono,monospace";
+let measureContext;
+/** Lazily create (and cache) a canvas 2D context for measuring text. */
+function getMeasureContext() {
+    if (measureContext !== undefined)
+        return measureContext;
+    try {
+        const canvas = typeof document !== "undefined" ? document.createElement("canvas") : null;
+        measureContext = canvas?.getContext?.("2d") ?? null;
+    }
+    catch {
+        measureContext = null;
+    }
+    return measureContext;
+}
+/**
+ * Measure the width of the widest label at the given font size. Uses canvas
+ * text metrics when available so the gutter always fits the real glyphs;
+ * falls back to a generous per-character estimate otherwise.
+ */
+function maxLabelWidth(labels, fontSize) {
+    const ctx = getMeasureContext();
+    if (ctx) {
+        ctx.font = `${fontSize}px ${LABEL_FONT_FAMILY}`;
+        let max = 0;
+        for (const label of labels) {
+            if (label)
+                max = Math.max(max, ctx.measureText(label).width);
+        }
+        return max;
+    }
+    const longest = labels.reduce((n, label) => Math.max(n, label.length), 0);
+    return longest * fontSize * 0.65;
+}
+function renderSvg(grid, opts) {
+    const { cellSize, cellGap, cellRadius, showMonthLabels, showWeekdayLabels, labelFontSize } = opts;
+    // Reserve a gutter wide enough for the actual weekday text (+2px breathing
+    // room) plus a gap, so labels never overflow into the cells.
+    const weekdayLabelWidth = showWeekdayLabels
+        ? Math.ceil(maxLabelWidth(opts.weekdayLabels, labelFontSize)) + 2
+        : 0;
+    const labelCol = showWeekdayLabels ? weekdayLabelWidth + cellGap : 0;
+    const labelRow = showMonthLabels ? labelFontSize + cellGap : 0;
+    const step = cellSize + cellGap;
+    const gridWidth = grid.totalCols * step - cellGap;
+    const gridHeight = 7 * step - cellGap;
+    // Month labels are left-anchored at each column; pad only for the last label
+    // so the svg does not end with a large empty strip after the final week.
+    const lastMonthLabel = grid.months[grid.months.length - 1]?.label ?? "";
+    const monthLabelPad = showMonthLabels && lastMonthLabel
+        ? Math.ceil(maxLabelWidth([lastMonthLabel], labelFontSize)) + 2
+        : 0;
+    const width = labelCol + gridWidth + monthLabelPad;
+    const height = labelRow + gridHeight;
+    const labelColor = normalizeCssColor(opts.labelColor, "#a1a1aa");
+    const svg = document.createElementNS(NS, "svg");
+    svg.setAttribute("width", String(width));
+    svg.setAttribute("height", String(height));
+    svg.setAttribute("viewBox", `0 0 ${width} ${height}`);
+    svg.setAttribute("role", "img");
+    svg.setAttribute("aria-label", "Contribution graph");
+    if (showMonthLabels) {
+        for (const m of grid.months) {
+            if (!m.label)
+                continue;
+            const text = document.createElementNS(NS, "text");
+            text.setAttribute("x", String(labelCol + m.col * step));
+            text.setAttribute("y", String(labelFontSize));
+            text.setAttribute("fill", labelColor);
+            text.setAttribute("font-size", String(labelFontSize));
+            text.setAttribute("font-weight", "600");
+            text.setAttribute("font-family", LABEL_FONT_FAMILY);
+            text.textContent = m.label;
+            svg.appendChild(text);
+        }
+    }
+    if (showWeekdayLabels) {
+        for (let d = 0; d < 7; d++) {
+            const label = opts.weekdayLabels[d];
+            if (!label)
+                continue;
+            const text = document.createElementNS(NS, "text");
+            text.setAttribute("x", String(weekdayLabelWidth));
+            text.setAttribute("y", String(labelRow + d * step + cellSize - 1));
+            text.setAttribute("fill", labelColor);
+            text.setAttribute("font-size", String(labelFontSize));
+            text.setAttribute("font-family", LABEL_FONT_FAMILY);
+            text.setAttribute("text-anchor", "end");
+            text.textContent = label;
+            svg.appendChild(text);
+        }
+    }
+    for (const cell of grid.cells) {
+        const rect = document.createElementNS(NS, "rect");
+        rect.setAttribute("x", String(labelCol + cell.week * step));
+        rect.setAttribute("y", String(labelRow + cell.day * step));
+        rect.setAttribute("width", String(cellSize));
+        rect.setAttribute("height", String(cellSize));
+        rect.setAttribute("rx", String(cellRadius));
+        rect.setAttribute("ry", String(cellRadius));
+        rect.setAttribute("fill", cellColor(cell, opts));
+        rect.setAttribute("data-date", cell.date);
+        rect.setAttribute("data-count", String(cell.count));
+        rect.setAttribute("data-level", String(cell.level));
+        svg.appendChild(rect);
+    }
+    return svg;
+}
+function attachClickHandler(svg, handler) {
+    svg.addEventListener("click", (event) => {
+        const target = event.target;
+        const rect = target?.closest?.("rect");
+        if (!rect)
+            return;
+        const date = rect.getAttribute("data-date");
+        const count = Number(rect.getAttribute("data-count") ?? 0);
+        const level = Number(rect.getAttribute("data-level") ?? 0);
+        if (!date)
+            return;
+        handler({ date, count, level, dateLabel: formatHumanDate(date) });
+    });
+}

package/dist/github.d.ts

@@ -0,0 +1,19 @@
+import { type ContributionDay } from "./contributionGraph.js";
+export interface FetchGitHubContributionsOptions {
+    username: string;
+    token?: string;
+    from?: Date | string;
+    to?: Date | string;
+    endpoint?: string;
+    signal?: AbortSignal;
+    fetcher?: typeof fetch;
+    includeGitHubColors?: boolean;
+}
+export interface GitHubContributionsResult {
+    username: string;
+    from: string;
+    to: string;
+    total: number;
+    data: ContributionDay[];
+}
+export declare function fetchGitHubContributions(options: FetchGitHubContributionsOptions): Promise<GitHubContributionsResult>;

package/dist/github.js

@@ -0,0 +1,109 @@
+import { formatDate, parseDate } from "./contributionGraph.js";
+const GITHUB_GRAPHQL_ENDPOINT = "https://api.github.com/graphql";
+const CONTRIBUTIONS_QUERY = `
+  query ContributionGraph($username: String!, $from: DateTime!, $to: DateTime!) {
+    user(login: $username) {
+      contributionsCollection(from: $from, to: $to) {
+        contributionCalendar {
+          totalContributions
+          weeks {
+            contributionDays {
+              date
+              contributionCount
+              color
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+export async function fetchGitHubContributions(options) {
+    const username = options.username.trim();
+    if (!username)
+        throw new Error("GitHub username is required.");
+    const fetcher = options.fetcher ?? globalThis.fetch;
+    if (!fetcher)
+        throw new Error("A fetch implementation is required.");
+    const toDate = normalizeDate(options.to ?? todayUtc());
+    const fromDate = normalizeDate(options.from ?? addUtcDays(toDate, -364));
+    const from = formatDate(fromDate);
+    const to = formatDate(toDate);
+    const endpoint = options.endpoint ?? GITHUB_GRAPHQL_ENDPOINT;
+    const headers = {
+        "Accept": "application/vnd.github+json",
+        "Content-Type": "application/json",
+    };
+    if (options.token) {
+        if (!isGitHubGraphQLEndpoint(endpoint)) {
+            throw new Error("GitHub tokens can only be sent to the official GitHub GraphQL endpoint. Omit token when using a proxy endpoint.");
+        }
+        headers.Authorization = `Bearer ${options.token}`;
+    }
+    const response = await fetcher(endpoint, {
+        method: "POST",
+        headers,
+        signal: options.signal,
+        body: JSON.stringify({
+            query: CONTRIBUTIONS_QUERY,
+            variables: {
+                username,
+                from: `${from}T00:00:00Z`,
+                to: `${to}T23:59:59Z`,
+            },
+        }),
+    });
+    const payload = await readJson(response);
+    if (!response.ok) {
+        throw new Error(`GitHub contributions request failed (${response.status}): ${readError(payload)}`);
+    }
+    if (payload.errors?.length) {
+        throw new Error(`GitHub contributions request failed: ${readError(payload)}`);
+    }
+    const calendar = payload.data?.user?.contributionsCollection?.contributionCalendar;
+    if (!calendar)
+        throw new Error(`GitHub user "${username}" was not found.`);
+    return {
+        username,
+        from,
+        to,
+        total: calendar.totalContributions,
+        data: calendar.weeks.flatMap((week) => week.contributionDays.map((day) => ({
+            date: day.date,
+            count: day.contributionCount,
+            ...(options.includeGitHubColors && day.color ? { color: day.color } : {}),
+        }))),
+    };
+}
+function isGitHubGraphQLEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        return url.protocol === "https:" && url.hostname === "api.github.com" && url.pathname === "/graphql";
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeDate(value) {
+    return value instanceof Date ? new Date(value.getTime()) : parseDate(value);
+}
+function todayUtc() {
+    const now = new Date();
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+function addUtcDays(date, days) {
+    const next = new Date(date.getTime());
+    next.setUTCDate(next.getUTCDate() + days);
+    return next;
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return {};
+    }
+}
+function readError(payload) {
+    return payload.errors?.map((error) => error.message).filter(Boolean).join("; ") || "Unknown error";
+}

package/dist/htmlGraph.d.ts

@@ -0,0 +1,13 @@
+/**
+ * HTML renderer for contribution-graph.
+ *
+ * Renders a CSS-grid of cells for consumers that want HTML layout semantics
+ * instead of SVG while keeping the same date math and customization options.
+ */
+import { type ContributionDay, type ContributionGraphOptions, type ResolvedOptions } from "./contributionGraph.js";
+export interface HtmlGraphHandle {
+    update(data: ContributionDay[], options: ResolvedOptions): void;
+    destroy(): void;
+}
+export declare function buildHtmlGraph(element: HTMLElement, data: ContributionDay[], options?: ContributionGraphOptions): HtmlGraphHandle;
+export declare function clearHtmlGraph(element: HTMLElement): void;

package/dist/htmlGraph.js

@@ -0,0 +1,199 @@
+/**
+ * HTML renderer for contribution-graph.
+ *
+ * Renders a CSS-grid of cells for consumers that want HTML layout semantics
+ * instead of SVG while keeping the same date math and customization options.
+ */
+import { slotText } from "slot-text";
+import { computeGrid, formatHumanDate, normalizeCssColor, resolveOptions, } from "./contributionGraph.js";
+const ROOT_CLASS = "contribution-graph";
+const COUNTS_CLASS = "contribution-graph--counts";
+export function buildHtmlGraph(element, data, options = {}) {
+    const opts = resolveOptions(options);
+    const grid = computeGrid(data, opts);
+    clearHtmlGraph(element);
+    element.classList.add(ROOT_CLASS, COUNTS_CLASS);
+    const container = document.createElement("div");
+    container.className = "cg-grid";
+    applyGridStyles(container, grid, opts);
+    const cells = new Map();
+    renderLabels(container, grid, opts);
+    renderCells(container, grid, opts, cells);
+    element.appendChild(container);
+    let currentClickHandler = opts.onCellClick;
+    const cleanupClickHandler = attachClickHandler(container, () => currentClickHandler);
+    let currentGrid = grid;
+    let currentOpts = opts;
+    return {
+        update(data, options) {
+            currentClickHandler = options.onCellClick;
+            const newGrid = computeGrid(data, options);
+            const sameStructure = newGrid.cells.length === currentGrid.cells.length &&
+                newGrid.cells.every((c, i) => c.date === currentGrid.cells[i].date);
+            if (sameStructure && canUpdateCellsOnly(currentOpts, options)) {
+                updateCounts(newGrid, options, cells);
+            }
+            else {
+                destroyCells(cells);
+                container.replaceChildren();
+                applyGridStyles(container, newGrid, options);
+                renderLabels(container, newGrid, options);
+                renderCells(container, newGrid, options, cells);
+            }
+            currentGrid = newGrid;
+            currentOpts = options;
+        },
+        destroy() {
+            cleanupClickHandler();
+            destroyCells(cells);
+            clearHtmlGraph(element);
+        },
+    };
+}
+export function clearHtmlGraph(element) {
+    element.classList.remove(ROOT_CLASS, COUNTS_CLASS);
+    element.replaceChildren();
+}
+function applyGridStyles(container, grid, opts) {
+    container.style.setProperty("--cg-cell", `${opts.cellSize}px`);
+    container.style.setProperty("--cg-gap", `${opts.cellGap}px`);
+    container.style.setProperty("--cg-radius", `${opts.cellRadius}px`);
+    container.style.gridTemplateColumns = `${opts.showWeekdayLabels ? "auto " : ""}repeat(${grid.totalCols}, ${opts.cellSize}px)`;
+    container.style.gridTemplateRows = `${opts.showMonthLabels ? "auto " : ""}repeat(7, ${opts.cellSize}px)`;
+}
+function renderLabels(container, grid, opts) {
+    const monthRow = 1;
+    const weekdayCol = 1;
+    const colOffset = opts.showWeekdayLabels ? 2 : 1;
+    const rowOffset = opts.showMonthLabels ? 2 : 1;
+    if (opts.showMonthLabels) {
+        for (const m of grid.months) {
+            if (!m.label)
+                continue;
+            const label = document.createElement("span");
+            label.className = "cg-month-label";
+            label.textContent = m.label;
+            label.style.gridColumn = `${m.col + colOffset} / span 3`;
+            label.style.gridRow = String(monthRow);
+            label.style.color = opts.labelColor;
+            label.style.fontSize = `${opts.labelFontSize}px`;
+            container.appendChild(label);
+        }
+    }
+    if (opts.showWeekdayLabels) {
+        for (let d = 0; d < 7; d++) {
+            const text = opts.weekdayLabels[d];
+            if (!text)
+                continue;
+            const label = document.createElement("span");
+            label.className = "cg-weekday-label";
+            label.textContent = text;
+            label.style.gridColumn = String(weekdayCol);
+            label.style.gridRow = `${d + rowOffset}`;
+            label.style.color = opts.labelColor;
+            label.style.fontSize = `${opts.labelFontSize}px`;
+            container.appendChild(label);
+        }
+    }
+}
+function renderCells(container, grid, opts, cells) {
+    const colOffset = opts.showWeekdayLabels ? 2 : 1;
+    const rowOffset = opts.showMonthLabels ? 2 : 1;
+    for (const cell of grid.cells) {
+        const cellEl = document.createElement("div");
+        cellEl.className = "cg-cell";
+        cellEl.dataset.date = cell.date;
+        const count = cell.count;
+        const color = cellColor(cell, opts);
+        cellEl.dataset.count = String(count);
+        cellEl.dataset.level = String(cell.level);
+        cellEl.style.gridColumn = `${cell.week + colOffset}`;
+        cellEl.style.gridRow = `${cell.day + rowOffset}`;
+        cellEl.style.background = color;
+        const entry = { cellEl };
+        if (opts.countFontSize > 0) {
+            const countEl = document.createElement("span");
+            countEl.className = "cg-count";
+            countEl.style.fontSize = `${opts.countFontSize}px`;
+            countEl.style.color = countColor(color, cell.level, opts);
+            cellEl.appendChild(countEl);
+            entry.countEl = countEl;
+            entry.countController = slotText(countEl, String(count), {
+                direction: "up",
+                duration: 220,
+                stagger: 12,
+            });
+        }
+        cells.set(cell.date, entry);
+        container.appendChild(cellEl);
+    }
+}
+function updateCounts(grid, opts, cells) {
+    for (const cell of grid.cells) {
+        const entry = cells.get(cell.date);
+        if (!entry)
+            continue;
+        const count = cell.count;
+        const color = cellColor(cell, opts);
+        entry.cellEl.dataset.count = String(count);
+        entry.cellEl.dataset.level = String(cell.level);
+        entry.cellEl.style.background = color;
+        if (entry.countEl)
+            entry.countEl.style.color = countColor(color, cell.level, opts);
+        entry.countController?.set(String(count), { skipUnchanged: true, direction: "up" });
+    }
+}
+function destroyCells(cells) {
+    for (const entry of cells.values()) {
+        entry.countController?.destroy();
+    }
+    cells.clear();
+}
+function cellColor(cell, opts) {
+    const paletteFallback = normalizeCssColor(opts.colors[cell.level] ?? opts.colors[0], "#ebedf0");
+    return normalizeCssColor(cell.color, paletteFallback);
+}
+function countColor(color, level, opts) {
+    return normalizeCssColor(opts.countColors?.[level], readableTextColor(color));
+}
+function readableTextColor(color) {
+    const hex = color.trim().replace(/^#/, "");
+    if (!/^[0-9a-f]{6}$/i.test(hex))
+        return "#171717";
+    const r = Number.parseInt(hex.slice(0, 2), 16);
+    const g = Number.parseInt(hex.slice(2, 4), 16);
+    const b = Number.parseInt(hex.slice(4, 6), 16);
+    return (r * 0.299 + g * 0.587 + b * 0.114) > 150 ? "#171717" : "#ffffff";
+}
+function canUpdateCellsOnly(prev, next) {
+    return prev.cellSize === next.cellSize &&
+        prev.cellGap === next.cellGap &&
+        prev.cellRadius === next.cellRadius &&
+        prev.showMonthLabels === next.showMonthLabels &&
+        prev.showWeekdayLabels === next.showWeekdayLabels &&
+        prev.labelColor === next.labelColor &&
+        prev.labelFontSize === next.labelFontSize &&
+        prev.countFontSize === next.countFontSize &&
+        (prev.countColors ?? []).join("\u0000") === (next.countColors ?? []).join("\u0000") &&
+        prev.monthLabels.join("\u0000") === next.monthLabels.join("\u0000") &&
+        prev.weekdayLabels.join("\u0000") === next.weekdayLabels.join("\u0000");
+}
+function attachClickHandler(container, getHandler) {
+    const listener = (event) => {
+        const handler = getHandler();
+        if (!handler)
+            return;
+        const target = event.target;
+        const cellEl = target?.closest?.(".cg-cell");
+        if (!cellEl)
+            return;
+        const date = cellEl.dataset.date;
+        if (!date)
+            return;
+        const count = Number(cellEl.dataset.count ?? 0);
+        const level = Number(cellEl.dataset.level ?? 0);
+        handler({ date, count, level, dateLabel: formatHumanDate(date) });
+    };
+    container.addEventListener("click", listener);
+    return () => container.removeEventListener("click", listener);
+}