@cronus-ui/ui 0.6.0

package/dist/charts/heatmap/heatmap-chart.js

@@ -0,0 +1,275 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ParentSize } from "@visx/responsive";
+import { scaleLinear, scaleTime } from "@visx/scale";
+import { useReducedMotion } from "motion/react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { cn } from "../../lib/cn.js";
+import { ChartLoadingLabel } from "../chart-loading-label.js";
+import { DEFAULT_CHART_STATUS, resolveRestingChartPhase, } from "../chart-phase.js";
+import { HEATMAP_DEFAULT_ENTER_DURATION_MS, HEATMAP_DEFAULT_ENTER_TRANSITION, HEATMAP_DEFAULT_LOADING_CELL_MAX_OPACITY, HEATMAP_DEFAULT_LOADING_CELL_RANDOMNESS, HEATMAP_LOADING_CHART_OPACITY, HEATMAP_LOADING_CONCEAL_MS, } from "./heatmap-animation.js";
+import { buildHeatmapColorScaleFromStyles, buildHeatmapFillScale, resolveHeatmapLevelStyles, } from "./heatmap-colors.js";
+import { HeatmapInteractionRoot, HeatmapProvider, useHeatmap, useHeatmapInteraction, } from "./heatmap-context.js";
+import { HeatmapPatternDefs } from "./heatmap-pattern-defs.js";
+import { resolveHeatmapSeparatorConfigWithData } from "./heatmap-resolve-separator.js";
+import { filterHeatmapColumns, getHeatmapColumnXOffset, getHeatmapPlotInnerWidth, getHeatmapSeparatorCount, getHeatmapTimeExtent, rotateHeatmapColumnBins, } from "./heatmap-utils.js";
+const DEFAULT_MARGIN = { top: 28, right: 16, bottom: 0, left: 40 };
+function computeHeatmapDimensions({ width, parentHeight, margin, columnCount, rowCount, binSize, layout, separator, }) {
+    const innerWidth = Math.max(width - margin.left - margin.right, 0);
+    const availableHeight = Math.max(parentHeight - margin.top - margin.bottom, 0);
+    const separatorCount = separator ? getHeatmapSeparatorCount(separator) : 0;
+    const totalSpacing = separatorCount * (separator?.spacing ?? 0);
+    let binWidth;
+    let binHeight;
+    if (binSize > 0) {
+        binWidth = binSize;
+        binHeight = binSize;
+    }
+    else if (layout === "fluid") {
+        const cellSize = Math.max((innerWidth - totalSpacing) / columnCount, 0);
+        binWidth = cellSize;
+        binHeight = cellSize;
+    }
+    else {
+        const cellSize = Math.min(Math.max((innerWidth - totalSpacing) / columnCount, 0), availableHeight / rowCount);
+        binWidth = cellSize;
+        binHeight = cellSize;
+    }
+    const plotInnerWidth = getHeatmapPlotInnerWidth(columnCount, binWidth, separator);
+    const innerHeight = rowCount * binHeight;
+    const height = layout === "fluid"
+        ? margin.top + innerHeight + margin.bottom
+        : Math.max(parentHeight, margin.top + innerHeight + margin.bottom);
+    const chartWidth = binSize > 0 && layout === "fluid" ? margin.left + plotInnerWidth + margin.right : width;
+    return {
+        binWidth,
+        binHeight,
+        innerWidth: plotInnerWidth,
+        innerHeight,
+        height,
+        width: chartWidth,
+    };
+}
+function HeatmapChartInner({ width, height: parentHeight, data, xDomain, sizingColumnCount: sizingColumnCountProp, margin, binSize, gap, layout, colorScale, fillScale, levelStyles, chartStatus, chartPhase, isLoaded, revealEpoch, animationDuration, enterTransition, enterStaggerScale, animateCells, loadingOpacity, showLoadingCells, loadingCellMaxOpacity, loadingCellRandomness, revealMode, loadingLabel, showLoadingLabel, columnSeparators, weekStartDay, children, }) {
+    const containerRef = useRef(null);
+    const filteredData = useMemo(() => filterHeatmapColumns(data, xDomain), [data, xDomain]);
+    const visibleData = useMemo(() => rotateHeatmapColumnBins(filteredData, weekStartDay), [filteredData, weekStartDay]);
+    const visibleColumnCount = Math.max(visibleData.length, 1);
+    const columnCount = xDomain && sizingColumnCountProp != null
+        ? Math.max(sizingColumnCountProp, 1)
+        : visibleColumnCount;
+    const rowCount = Math.max(visibleData[0]?.bins.length ?? 7, 1);
+    const separatorLayout = useMemo(() => resolveHeatmapSeparatorConfigWithData(children, visibleData, columnSeparators), [children, columnSeparators, visibleData]);
+    const { binWidth, binHeight, innerWidth, innerHeight, height, width: chartWidth, } = useMemo(() => computeHeatmapDimensions({
+        width,
+        parentHeight,
+        margin,
+        columnCount,
+        rowCount,
+        binSize,
+        layout,
+        separator: separatorLayout,
+    }), [binSize, columnCount, layout, margin, parentHeight, rowCount, separatorLayout, width]);
+    const xScale = useMemo(() => (columnIndex) => columnIndex * binWidth + getHeatmapColumnXOffset(columnIndex, separatorLayout), [binWidth, separatorLayout]);
+    const yScale = useMemo(() => (rowIndex) => rowIndex * binHeight, [binHeight]);
+    const timeExtent = useMemo(() => getHeatmapTimeExtent(data), [data]);
+    const timeXScale = useMemo(() => {
+        const domain = timeExtent ?? [new Date(), new Date()];
+        return scaleTime({
+            domain,
+            range: [0, innerWidth],
+        });
+    }, [innerWidth, timeExtent]);
+    const brushYScale = useMemo(() => scaleLinear({
+        domain: [0, 1],
+        range: [innerHeight, 0],
+    }), [innerHeight]);
+    const contextValue = useMemo(() => ({
+        data: visibleData,
+        width: chartWidth,
+        height,
+        innerWidth,
+        innerHeight,
+        margin,
+        binWidth,
+        binHeight,
+        gap,
+        weekStartDay,
+        xScale,
+        yScale,
+        separatorLayout,
+        timeXScale,
+        brushYScale,
+        isReady: chartWidth >= 10 && height >= 10,
+        colorScale,
+        fillScale,
+        levelStyles,
+        containerRef,
+        chartStatus,
+        chartPhase,
+        isLoaded,
+        revealEpoch,
+        animationDuration,
+        enterTransition,
+        enterStaggerScale,
+        animateCells,
+        loadingOpacity,
+        showLoadingCells,
+        loadingCellMaxOpacity,
+        loadingCellRandomness,
+        revealMode,
+        loadingLabel,
+        showLoadingLabel,
+    }), [
+        animateCells,
+        animationDuration,
+        binHeight,
+        binWidth,
+        brushYScale,
+        chartPhase,
+        chartStatus,
+        chartWidth,
+        colorScale,
+        fillScale,
+        enterStaggerScale,
+        enterTransition,
+        gap,
+        height,
+        innerHeight,
+        innerWidth,
+        isLoaded,
+        loadingCellMaxOpacity,
+        loadingCellRandomness,
+        loadingLabel,
+        levelStyles,
+        loadingOpacity,
+        margin,
+        revealMode,
+        separatorLayout,
+        showLoadingCells,
+        showLoadingLabel,
+        revealEpoch,
+        timeXScale,
+        visibleData,
+        weekStartDay,
+        xScale,
+        yScale,
+    ]);
+    if (chartWidth < 10 || height < 10) {
+        return null;
+    }
+    return (_jsx(HeatmapProvider, { value: contextValue, children: _jsx(HeatmapInteractionRoot, { children: _jsx(HeatmapChartSurface, { layout: layout, children: children }) }) }));
+}
+function HeatmapChartSurface({ layout, children }) {
+    const { containerRef, height, width, margin, levelStyles, chartPhase, loadingOpacity, loadingLabel, showLoadingLabel, } = useHeatmap();
+    const { clearInteraction } = useHeatmapInteraction();
+    const reducedOpacity = chartPhase === "loading" || chartPhase === "exitingReady" ? loadingOpacity : 1;
+    return (_jsxs("div", { "data-slot": "heatmap-chart", className: cn("relative w-full", layout === "fill" && "h-full"), onPointerLeave: clearInteraction, ref: containerRef, style: { opacity: reducedOpacity }, children: [_jsxs("svg", { "aria-hidden": "true", height: height, width: width, children: [_jsx(HeatmapPatternDefs, { levelStyles: levelStyles }), _jsx("g", { transform: `translate(${margin.left},${margin.top})`, children: children })] }), showLoadingLabel && loadingLabel?.trim() ? (_jsx("div", { className: "pointer-events-none absolute", style: {
+                    top: margin.top,
+                    left: margin.left,
+                    width: Math.max(width - margin.left - margin.right, 0),
+                    height: Math.max(height - margin.top - margin.bottom, 0),
+                }, children: _jsx(ChartLoadingLabel, { exiting: chartPhase !== "loading", text: loadingLabel }) })) : null] }));
+}
+function useHeatmapChartLifecycle({ chartStatus, animationDuration, revealSignature = "", animate, }) {
+    const reducedMotion = useReducedMotion();
+    const [chartPhase, setChartPhase] = useState(() => resolveRestingChartPhase(chartStatus));
+    const [isLoaded, setIsLoaded] = useState(() => chartStatus === "ready" && (!animate || animationDuration <= 0));
+    const [revealEpoch, setRevealEpoch] = useState(0);
+    const [revealMode, setRevealMode] = useState(null);
+    const prevStatusRef = useRef(chartStatus);
+    const phaseRef = useRef(chartPhase);
+    phaseRef.current = chartPhase;
+    const animateCells = animate && !reducedMotion;
+    const animateEnter = animateCells && animationDuration > 0;
+    const finishReveal = useCallback(() => {
+        setIsLoaded(true);
+        setChartPhase("ready");
+        setRevealMode(null);
+    }, []);
+    const beginReveal = useCallback(() => {
+        setRevealMode("enter");
+        setRevealEpoch((epoch) => epoch + 1);
+        setIsLoaded(false);
+        setChartPhase("revealing");
+        if (!animateEnter) {
+            finishReveal();
+        }
+    }, [animateEnter, finishReveal]);
+    useLayoutEffect(() => {
+        const prevStatus = prevStatusRef.current;
+        if (prevStatus === chartStatus) {
+            return;
+        }
+        prevStatusRef.current = chartStatus;
+        if (chartStatus === "ready" && prevStatus === "loading") {
+            setRevealMode("fromLoading");
+            setIsLoaded(false);
+            setChartPhase("revealing");
+            return;
+        }
+        if (chartStatus === "loading" && prevStatus === "ready") {
+            setRevealMode(null);
+            setIsLoaded(false);
+            setChartPhase("exitingReady");
+        }
+    }, [chartStatus]);
+    useEffect(() => {
+        if (chartPhase !== "exitingReady") {
+            return;
+        }
+        const timer = window.setTimeout(() => {
+            setChartPhase("loading");
+        }, HEATMAP_LOADING_CONCEAL_MS);
+        return () => window.clearTimeout(timer);
+    }, [chartPhase]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: revealSignature replays enter
+    useEffect(() => {
+        if (!animateEnter) {
+            setIsLoaded(true);
+            setChartPhase(resolveRestingChartPhase(chartStatus));
+            return;
+        }
+        if (chartStatus !== "ready") {
+            return;
+        }
+        if (phaseRef.current !== "ready") {
+            return;
+        }
+        beginReveal();
+    }, [animateEnter, animationDuration, beginReveal, chartStatus, revealSignature]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: revealEpoch replays finish timer
+    useEffect(() => {
+        if (!animateEnter || chartPhase !== "revealing") {
+            return;
+        }
+        const finishTimer = window.setTimeout(finishReveal, animationDuration);
+        return () => window.clearTimeout(finishTimer);
+    }, [animateEnter, animationDuration, chartPhase, finishReveal, revealEpoch]);
+    return {
+        chartPhase,
+        isLoaded,
+        revealEpoch,
+        revealMode,
+        animateCells,
+    };
+}
+export function HeatmapChart({ data, xDomain, sizingColumnCount, layout = "fluid", margin: marginProp, binSize = 0, gap = 2, colorScale: colorScaleProp, levelColors, levelStyles: levelStylesProp, aspectRatio, className = "", status = DEFAULT_CHART_STATUS, loadingLabel, animationDuration = HEATMAP_DEFAULT_ENTER_DURATION_MS, enterTransition = HEATMAP_DEFAULT_ENTER_TRANSITION, revealSignature = "", enterStaggerScale = 1, animate = true, loadingOpacity = HEATMAP_LOADING_CHART_OPACITY, showLoadingCells = true, loadingCellMaxOpacity = HEATMAP_DEFAULT_LOADING_CELL_MAX_OPACITY, loadingCellRandomness = HEATMAP_DEFAULT_LOADING_CELL_RANDOMNESS, columnSeparators, weekStartDay = 0, children, }) {
+    const margin = { ...DEFAULT_MARGIN, ...marginProp };
+    const levelStyles = useMemo(() => resolveHeatmapLevelStyles(levelColors, levelStylesProp), [levelColors, levelStylesProp]);
+    const colorScale = useMemo(() => colorScaleProp ?? buildHeatmapColorScaleFromStyles(levelStyles), [colorScaleProp, levelStyles]);
+    const fillScale = useMemo(() => buildHeatmapFillScale(levelStyles), [levelStyles]);
+    const { chartPhase, isLoaded, revealEpoch, revealMode, animateCells } = useHeatmapChartLifecycle({
+        chartStatus: status,
+        animationDuration,
+        revealSignature,
+        animate,
+    });
+    const showLoadingLabel = Boolean(loadingLabel?.trim() &&
+        status === "loading" &&
+        (chartPhase === "loading" || chartPhase === "exitingReady"));
+    return (_jsx("div", { className: cn("relative w-full", layout === "fill" && "h-full min-h-0", className), "data-slot": "heatmap-chart", style: aspectRatio ? { aspectRatio } : undefined, children: _jsx(ParentSize, { children: ({ width, height: parentHeight }) => (_jsx(HeatmapChartInner, { animateCells: animateCells, animationDuration: animationDuration, binSize: binSize, chartPhase: chartPhase, chartStatus: status, colorScale: colorScale, columnSeparators: columnSeparators, data: data, enterStaggerScale: enterStaggerScale, enterTransition: enterTransition, fillScale: fillScale, gap: gap, height: parentHeight, isLoaded: isLoaded, layout: layout, levelStyles: levelStyles, loadingCellMaxOpacity: loadingCellMaxOpacity, loadingCellRandomness: loadingCellRandomness, loadingLabel: loadingLabel, loadingOpacity: loadingOpacity, margin: margin, revealEpoch: revealEpoch, revealMode: revealMode, showLoadingCells: showLoadingCells, showLoadingLabel: showLoadingLabel, sizingColumnCount: sizingColumnCount, weekStartDay: weekStartDay, width: width, xDomain: xDomain, children: children })) }) }));
+}
+HeatmapChart.displayName = "HeatmapChart";
+export default HeatmapChart;
+//# sourceMappingURL=heatmap-chart.js.map

package/dist/charts/heatmap/heatmap-colors.d.ts

@@ -0,0 +1,70 @@
+import type { PatternPresetId } from "../pattern-preset.js";
+/** Default Less → More scale using {@link CHART_SCALE_VARS}. */
+export declare const HEATMAP_DEFAULT_LEVEL_COLORS: readonly ["var(--chart-scale-01)", "var(--chart-scale-02)", "var(--chart-scale-03)", "var(--chart-scale-04)", "var(--chart-scale-05)"];
+export type HeatmapLevelColors = readonly [string, string, string, string, string];
+export type HeatmapLevelFillMode = "solid" | "pattern";
+export interface HeatmapLevelStyle {
+    color: string;
+    fillMode?: HeatmapLevelFillMode;
+    pattern?: PatternPresetId;
+    patternColor?: string;
+    patternScale?: number;
+    patternStrokeWidth?: number;
+    patternRadius?: number;
+    patternComplement?: boolean;
+    patternFill?: string;
+    patternTileBackground?: string;
+    patternOpacity?: number;
+    patternDotsFill?: boolean;
+}
+export type HeatmapLevelStyles = readonly [
+    HeatmapLevelStyle,
+    HeatmapLevelStyle,
+    HeatmapLevelStyle,
+    HeatmapLevelStyle,
+    HeatmapLevelStyle
+];
+export declare const HEATMAP_DEFAULT_LEVEL_STYLES: readonly [{
+    readonly color: "var(--chart-scale-01)";
+    readonly fillMode: "solid";
+    readonly pattern: "none";
+}, {
+    readonly color: "var(--chart-scale-02)";
+    readonly fillMode: "solid";
+    readonly pattern: "none";
+}, {
+    readonly color: "var(--chart-scale-03)";
+    readonly fillMode: "solid";
+    readonly pattern: "none";
+}, {
+    readonly color: "var(--chart-scale-04)";
+    readonly fillMode: "solid";
+    readonly pattern: "none";
+}, {
+    readonly color: "var(--chart-scale-05)";
+    readonly fillMode: "solid";
+    readonly pattern: "none";
+}];
+export declare function heatmapLevelPatternId(level: number): string;
+export declare function isHeatmapLevelPattern(style: HeatmapLevelStyle): boolean;
+export declare function heatmapPatternStrokeFallback(color: string): string;
+export declare function heatmapLevelPatternRenderOptions(style: HeatmapLevelStyle): {
+    color: string;
+    tileBackground: string;
+    scale: number;
+    strokeWidth: number | undefined;
+    radius: number | undefined;
+    complement: boolean | undefined;
+    fill: string | undefined;
+    dotFill: boolean | undefined;
+};
+export declare function heatmapLevelCellFillOpacity(style: HeatmapLevelStyle): number;
+export declare function levelColorsFromStyles(levelStyles: HeatmapLevelStyles): HeatmapLevelColors;
+export declare function levelStylesFromColors(levelColors: HeatmapLevelColors): HeatmapLevelStyles;
+export declare function resolveHeatmapLevelStyles(levelColors?: HeatmapLevelColors, levelStyles?: HeatmapLevelStyles): HeatmapLevelStyles;
+export declare function buildHeatmapColorScale(levelColors: HeatmapLevelColors): (count: number | null | undefined) => string;
+export declare function buildHeatmapColorScaleFromStyles(levelStyles: HeatmapLevelStyles): (count: number | null | undefined) => string;
+export declare function buildHeatmapFillScale(levelStyles: HeatmapLevelStyles): (count: number | null | undefined) => string;
+export declare const defaultHeatmapColorScale: (count: number | null | undefined) => string;
+export declare const defaultHeatmapFillScale: (count: number | null | undefined) => string;
+//# sourceMappingURL=heatmap-colors.d.ts.map

package/dist/charts/heatmap/heatmap-colors.js

@@ -0,0 +1,113 @@
+import { CHART_SCALE_VARS } from "../chart-scale.js";
+import { getHeatmapContributionLevel } from "./heatmap-utils.js";
+/** Default Less → More scale using {@link CHART_SCALE_VARS}. */
+export const HEATMAP_DEFAULT_LEVEL_COLORS = CHART_SCALE_VARS;
+export const HEATMAP_DEFAULT_LEVEL_STYLES = [
+    {
+        color: HEATMAP_DEFAULT_LEVEL_COLORS[0],
+        fillMode: "solid",
+        pattern: "none",
+    },
+    {
+        color: HEATMAP_DEFAULT_LEVEL_COLORS[1],
+        fillMode: "solid",
+        pattern: "none",
+    },
+    {
+        color: HEATMAP_DEFAULT_LEVEL_COLORS[2],
+        fillMode: "solid",
+        pattern: "none",
+    },
+    {
+        color: HEATMAP_DEFAULT_LEVEL_COLORS[3],
+        fillMode: "solid",
+        pattern: "none",
+    },
+    {
+        color: HEATMAP_DEFAULT_LEVEL_COLORS[4],
+        fillMode: "solid",
+        pattern: "none",
+    },
+];
+export function heatmapLevelPatternId(level) {
+    return `heatmap-level-${level}`;
+}
+export function isHeatmapLevelPattern(style) {
+    return style.fillMode === "pattern" && style.pattern != null && style.pattern !== "none";
+}
+export function heatmapPatternStrokeFallback(color) {
+    return `color-mix(in oklch, ${color} 45%, white)`;
+}
+export function heatmapLevelPatternRenderOptions(style) {
+    const preset = style.pattern ?? "diagonal";
+    let defaultScale = 1;
+    if (preset === "cross") {
+        defaultScale = 1.33;
+    }
+    return {
+        color: style.patternColor?.trim() ||
+            (preset === "accent" ? "#e879f9" : heatmapPatternStrokeFallback(style.color)),
+        tileBackground: style.patternTileBackground?.trim() || style.color,
+        scale: style.patternScale ?? defaultScale,
+        strokeWidth: style.patternStrokeWidth,
+        radius: style.patternRadius,
+        complement: style.patternComplement,
+        fill: style.patternFill?.trim() || undefined,
+        dotFill: style.patternDotsFill,
+    };
+}
+export function heatmapLevelCellFillOpacity(style) {
+    if (!isHeatmapLevelPattern(style)) {
+        return 1;
+    }
+    return style.patternOpacity ?? 1;
+}
+export function levelColorsFromStyles(levelStyles) {
+    return [
+        levelStyles[0].color,
+        levelStyles[1].color,
+        levelStyles[2].color,
+        levelStyles[3].color,
+        levelStyles[4].color,
+    ];
+}
+export function levelStylesFromColors(levelColors) {
+    return [
+        { color: levelColors[0], fillMode: "solid", pattern: "none" },
+        { color: levelColors[1], fillMode: "solid", pattern: "none" },
+        { color: levelColors[2], fillMode: "solid", pattern: "none" },
+        { color: levelColors[3], fillMode: "solid", pattern: "none" },
+        { color: levelColors[4], fillMode: "solid", pattern: "none" },
+    ];
+}
+export function resolveHeatmapLevelStyles(levelColors, levelStyles) {
+    if (levelStyles) {
+        return levelStyles;
+    }
+    if (levelColors) {
+        return levelStylesFromColors(levelColors);
+    }
+    return HEATMAP_DEFAULT_LEVEL_STYLES;
+}
+export function buildHeatmapColorScale(levelColors) {
+    return buildHeatmapColorScaleFromStyles(levelStylesFromColors(levelColors));
+}
+export function buildHeatmapColorScaleFromStyles(levelStyles) {
+    return (count) => {
+        const level = getHeatmapContributionLevel(count ?? 0);
+        return levelStyles[level]?.color ?? levelStyles[0].color;
+    };
+}
+export function buildHeatmapFillScale(levelStyles) {
+    return (count) => {
+        const level = getHeatmapContributionLevel(count ?? 0);
+        const style = levelStyles[level] ?? levelStyles[0];
+        if (isHeatmapLevelPattern(style)) {
+            return `url(#${heatmapLevelPatternId(level)})`;
+        }
+        return style.color;
+    };
+}
+export const defaultHeatmapColorScale = buildHeatmapColorScale(HEATMAP_DEFAULT_LEVEL_COLORS);
+export const defaultHeatmapFillScale = buildHeatmapFillScale(HEATMAP_DEFAULT_LEVEL_STYLES);
+//# sourceMappingURL=heatmap-colors.js.map

package/dist/charts/heatmap/heatmap-context.d.ts

@@ -0,0 +1,109 @@
+import type { scaleLinear, scaleTime } from "@visx/scale";
+import type { Transition } from "motion/react";
+import { type Dispatch, type ReactNode, type RefObject, type SetStateAction } from "react";
+import type { Margin } from "../chart-context.js";
+import type { ChartPhase, ChartStatus } from "../chart-phase.js";
+import { type HeatmapLevelStyles } from "./heatmap-colors.js";
+import type { HeatmapSeparatorLayout, HeatmapWeekStartDay } from "./heatmap-utils.js";
+type HeatmapTimeScale = ReturnType<typeof scaleTime<number>>;
+type HeatmapLinearScale = ReturnType<typeof scaleLinear<number>>;
+export interface HeatmapBin {
+    count: number;
+    bin: number;
+    date: Date;
+}
+export interface HeatmapColumn {
+    bin: number;
+    bins: HeatmapBin[];
+}
+export interface HeatmapTooltipData {
+    column: number;
+    row: number;
+    count: number;
+    date: Date;
+    x: number;
+    y: number;
+}
+export interface HeatmapInteractionContextValue {
+    hoveredCell: {
+        column: number;
+        row: number;
+    } | null;
+    hoveredLegendLevel: number | null;
+    tooltipData: HeatmapTooltipData | null;
+    setHoveredCell: (cell: {
+        column: number;
+        row: number;
+    } | null) => void;
+    setHoveredLegendLevel: (level: number | null) => void;
+    setTooltipData: Dispatch<SetStateAction<HeatmapTooltipData | null>>;
+    clearInteraction: () => void;
+}
+export interface HeatmapContextValue {
+    data: HeatmapColumn[];
+    width: number;
+    height: number;
+    innerWidth: number;
+    innerHeight: number;
+    margin: Margin;
+    binWidth: number;
+    binHeight: number;
+    gap: number;
+    weekStartDay: HeatmapWeekStartDay;
+    xScale: (columnIndex: number) => number;
+    yScale: (rowIndex: number) => number;
+    separatorLayout: HeatmapSeparatorLayout | null;
+    timeXScale: HeatmapTimeScale;
+    brushYScale: HeatmapLinearScale;
+    isReady: boolean;
+    colorScale: (count: number | null | undefined) => string;
+    fillScale: (count: number | null | undefined) => string;
+    levelStyles: HeatmapLevelStyles;
+    containerRef: RefObject<HTMLDivElement | null>;
+    chartStatus: ChartStatus;
+    chartPhase: ChartPhase;
+    isLoaded: boolean;
+    revealEpoch: number;
+    animationDuration: number;
+    enterTransition?: Transition;
+    enterStaggerScale: number;
+    animateCells: boolean;
+    loadingOpacity: number;
+    showLoadingCells: boolean;
+    loadingCellMaxOpacity: number;
+    loadingCellRandomness: number;
+    revealMode: HeatmapRevealMode;
+    loadingLabel?: string;
+    showLoadingLabel: boolean;
+}
+/** How cells transition into view after loading or on first mount. */
+export type HeatmapRevealMode = "enter" | "fromLoading" | null;
+export declare function HeatmapInteractionProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function HeatmapProvider({ children, value, }: {
+    children: ReactNode;
+    value: HeatmapContextValue;
+}): import("react").JSX.Element;
+export declare function useHeatmap(): HeatmapContextValue;
+export declare function useHeatmapInteraction(): HeatmapInteractionContextValue;
+export declare function useHeatmapInteractionOptional(): HeatmapInteractionContextValue | null;
+/** Clears hover state when the pointer leaves chart + legend. */
+export declare function HeatmapInteractionBoundary({ children, className, }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/** Nests a provider only when one is not already present upstream. */
+export declare function HeatmapInteractionRoot({ children }: {
+    children: ReactNode;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+/** @deprecated Use {@link HEATMAP_DEFAULT_LEVEL_COLORS} */
+export declare const heatmapCssVars: {
+    readonly empty: "var(--chart-scale-01)";
+    readonly level1: "var(--chart-scale-02)";
+    readonly level2: "var(--chart-scale-03)";
+    readonly level3: "var(--chart-scale-04)";
+    readonly level4: "var(--chart-scale-05)";
+};
+export {};
+//# sourceMappingURL=heatmap-context.d.ts.map

package/dist/charts/heatmap/heatmap-context.js

@@ -0,0 +1,69 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useState, } from "react";
+import { cn } from "../../lib/cn.js";
+import { HEATMAP_DEFAULT_LEVEL_COLORS } from "./heatmap-colors.js";
+const HeatmapContext = createContext(null);
+const HeatmapInteractionContext = createContext(null);
+export function HeatmapInteractionProvider({ children }) {
+    const [hoveredCell, setHoveredCell] = useState(null);
+    const [hoveredLegendLevel, setHoveredLegendLevel] = useState(null);
+    const [tooltipData, setTooltipData] = useState(null);
+    const clearInteraction = useCallback(() => {
+        setHoveredCell(null);
+        setHoveredLegendLevel(null);
+        setTooltipData(null);
+    }, []);
+    const value = useMemo(() => ({
+        hoveredCell,
+        hoveredLegendLevel,
+        tooltipData,
+        setHoveredCell,
+        setHoveredLegendLevel,
+        setTooltipData,
+        clearInteraction,
+    }), [clearInteraction, hoveredCell, hoveredLegendLevel, tooltipData]);
+    return (_jsx(HeatmapInteractionContext.Provider, { value: value, children: children }));
+}
+export function HeatmapProvider({ children, value, }) {
+    return _jsx(HeatmapContext.Provider, { value: value, children: children });
+}
+export function useHeatmap() {
+    const context = useContext(HeatmapContext);
+    if (!context) {
+        throw new Error("useHeatmap must be used within a HeatmapProvider");
+    }
+    return context;
+}
+export function useHeatmapInteraction() {
+    const context = useContext(HeatmapInteractionContext);
+    if (!context) {
+        throw new Error("useHeatmapInteraction must be used within a HeatmapInteractionProvider");
+    }
+    return context;
+}
+export function useHeatmapInteractionOptional() {
+    return useContext(HeatmapInteractionContext);
+}
+/** Clears hover state when the pointer leaves chart + legend. */
+export function HeatmapInteractionBoundary({ children, className, }) {
+    const { clearInteraction } = useHeatmapInteraction();
+    return (_jsx("div", { className: cn("size-full min-h-0 min-w-0", className), onPointerLeave: clearInteraction, children: children }));
+}
+/** Nests a provider only when one is not already present upstream. */
+export function HeatmapInteractionRoot({ children }) {
+    const existing = useContext(HeatmapInteractionContext);
+    if (existing) {
+        return children;
+    }
+    return _jsx(HeatmapInteractionProvider, { children: children });
+}
+/** @deprecated Use {@link HEATMAP_DEFAULT_LEVEL_COLORS} */
+export const heatmapCssVars = {
+    empty: HEATMAP_DEFAULT_LEVEL_COLORS[0],
+    level1: HEATMAP_DEFAULT_LEVEL_COLORS[1],
+    level2: HEATMAP_DEFAULT_LEVEL_COLORS[2],
+    level3: HEATMAP_DEFAULT_LEVEL_COLORS[3],
+    level4: HEATMAP_DEFAULT_LEVEL_COLORS[4],
+};
+//# sourceMappingURL=heatmap-context.js.map

package/dist/charts/heatmap/heatmap-legend-gradient.d.ts

@@ -0,0 +1,20 @@
+import type { HeatmapLevelStyles } from "./heatmap-colors.js";
+export interface HeatmapLegendGradientProps {
+    levels: readonly number[];
+    levelStyles: HeatmapLevelStyles;
+    cellSize: number;
+    gap: number;
+    cornerRadius: number;
+    gradientSpan: number;
+    highlightedLevel: number | null;
+    isDimming: boolean;
+    inactiveOpacity: number;
+    inactiveScale: number;
+    activeScale: number;
+    isInteractive: boolean;
+    onEnter: (level: number) => void;
+    onLeave: () => void;
+}
+export declare const HeatmapLegendGradient: import("react").MemoExoticComponent<({ levels, levelStyles, cellSize, gap, cornerRadius, gradientSpan, highlightedLevel, isDimming, inactiveOpacity, inactiveScale, activeScale, isInteractive, onEnter, onLeave, }: HeatmapLegendGradientProps) => import("react").JSX.Element>;
+export default HeatmapLegendGradient;
+//# sourceMappingURL=heatmap-legend-gradient.d.ts.map