@cronus-ui/ui 0.6.0

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

@@ -0,0 +1,21 @@
+export interface HeatmapCellsProps {
+    /** Corner radius for each cell. Default: 2 */
+    cornerRadius?: number;
+    /** Override the default GitHub-style green color scale. */
+    colorScale?: (count: number | null | undefined) => string;
+    /** Opacity for inactive cells while hovering. Default: 0.3 */
+    inactiveOpacity?: number;
+    /** Scale for inactive cells while hovering. Default: 1 */
+    inactiveScale?: number;
+    /** Scale for the highlighted cell while hovering. Default: 1 */
+    activeScale?: number;
+    /** Per-row opacity multiplier (display row index). Default: 1 */
+    rowOpacity?: number | readonly number[];
+    /** Pointer hover + dimming. Default: true */
+    interactive?: boolean;
+    /** Hide out-of-range bins (GitHub-style ghost cells). Default: true */
+    hideGhostCells?: boolean;
+}
+export declare const HeatmapCells: import("react").MemoExoticComponent<({ cornerRadius, colorScale: colorScaleProp, inactiveOpacity, inactiveScale, activeScale, rowOpacity, interactive, hideGhostCells, }: HeatmapCellsProps) => import("react").JSX.Element>;
+export default HeatmapCells;
+//# sourceMappingURL=heatmap-cells.d.ts.map

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

@@ -0,0 +1,265 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Group } from "@visx/group";
+import { HeatmapRect } from "@visx/heatmap";
+import { animate, motion, useMotionValue } from "motion/react";
+import { memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { transitionWithDelay } from "../motion-utils.js";
+import { computeHeatmapEnterFadeDelayMs, HEATMAP_DEFAULT_ENTER_EASE, HEATMAP_LOADING_BASE_CELL_OPACITY, HEATMAP_LOADING_CONCEAL_MS, heatmapLoadingCellParticipates, resolveHeatmapEnterFadeDurationSec, } from "./heatmap-animation.js";
+import { heatmapLevelCellFillOpacity } from "./heatmap-colors.js";
+import { useHeatmap, useHeatmapInteraction, } from "./heatmap-context.js";
+import { getHeatmapContributionLevel, isHeatmapGhostBin, isHeatmapHoverEffectEnabled, resolveHeatmapDisplayRange, resolveHeatmapHoverStyle, resolveHeatmapRowOpacity, } from "./heatmap-utils.js";
+const HEATMAP_INACTIVE_OPACITY = 0.3;
+/** Smooth tween for inactive opacity + scale on hover. */
+const HEATMAP_INACTIVE_TRANSITION = {
+    duration: 0.22,
+    ease: [0.4, 0, 0.2, 1],
+};
+const HEATMAP_CONCEAL_TRANSITION = {
+    duration: HEATMAP_LOADING_CONCEAL_MS / 1000,
+    ease: HEATMAP_DEFAULT_ENTER_EASE,
+};
+function computeHeatmapCellFaded(isCellHovering, isLevelHovering, hoveredCell, hoveredLegendLevel, cell, count) {
+    if (isCellHovering && hoveredCell) {
+        const isHighlighted = hoveredCell.column === cell.column && hoveredCell.row === cell.row;
+        return { isHighlighted, isDimmed: !isHighlighted };
+    }
+    if (isLevelHovering && hoveredLegendLevel !== null) {
+        const isHighlighted = getHeatmapContributionLevel(count) === hoveredLegendLevel;
+        return { isHighlighted, isDimmed: !isHighlighted };
+    }
+    return { isHighlighted: false, isDimmed: false };
+}
+function syncHeatmapCellLayerOpacities(params) {
+    const { animateCells, chartStatus, dataOpacity, isAwaitingLoadingConceal, isExitingToLoading, isLoadingResting, isReadyResting, isRevealActive, participates, pulseOpacity, readyDataOpacity, shimmerOpacity, showLoadingCellsLayer, showShimmerPulse, staggeredTransition, } = params;
+    if (!animateCells) {
+        if (isReadyResting) {
+            dataOpacity.set(readyDataOpacity);
+            shimmerOpacity.set(0);
+            pulseOpacity.set(0);
+        }
+        else if (chartStatus === "loading") {
+            dataOpacity.set(0);
+            pulseOpacity.set(0);
+            shimmerOpacity.set(participates && showLoadingCellsLayer ? 0 : HEATMAP_LOADING_BASE_CELL_OPACITY);
+        }
+        return;
+    }
+    if (isLoadingResting) {
+        animate(dataOpacity, 0, { duration: 0 });
+        if (!showShimmerPulse) {
+            animate(shimmerOpacity, HEATMAP_LOADING_BASE_CELL_OPACITY, {
+                duration: 0,
+            });
+        }
+        return;
+    }
+    if (isRevealActive) {
+        pulseOpacity.set(0);
+        shimmerOpacity.set(0);
+        animate(dataOpacity, readyDataOpacity, staggeredTransition);
+        return;
+    }
+    if (isAwaitingLoadingConceal || isExitingToLoading) {
+        animate(dataOpacity, 0, HEATMAP_CONCEAL_TRANSITION);
+        animate(shimmerOpacity, 0, { duration: 0 });
+        return;
+    }
+    if (isReadyResting) {
+        animate(dataOpacity, readyDataOpacity, HEATMAP_INACTIVE_TRANSITION);
+        animate(shimmerOpacity, 0, { duration: 0 });
+        pulseOpacity.set(0);
+    }
+}
+const HeatmapMotionCell = memo(function HeatmapMotionCell({ cell, bin, cornerRadius, fillScale, interactive, inactiveOpacity, inactiveScale, activeScale, rowOpacity, hoverState, onEnter, onLeave, }) {
+    const { chartStatus, chartPhase, isLoaded, revealMode, revealEpoch, animationDuration, enterTransition, enterStaggerScale, animateCells, showLoadingCells: showLoadingCellsLayer, loadingCellMaxOpacity, loadingCellRandomness, levelStyles, } = useHeatmap();
+    const levelStyle = levelStyles[getHeatmapContributionLevel(bin.count ?? 0)] ?? levelStyles[0];
+    const targetFill = fillScale(bin.count);
+    const emptyFill = fillScale(0);
+    const patternFillOpacity = heatmapLevelCellFillOpacity(levelStyle);
+    const dataOpacity = useMotionValue(0);
+    /** Orchestration layer: conceal, static loading base. */
+    const shimmerOpacity = useMotionValue(0);
+    /** Pulse loop only — kept separate so stagger tweens don't break re-entry. */
+    const pulseOpacity = useMotionValue(0);
+    const wasShimmerPulsingRef = useRef(false);
+    const isLoadingResting = chartStatus === "loading" && chartPhase === "loading";
+    const isAwaitingLoadingConceal = chartStatus === "loading" && chartPhase === "ready";
+    const isExitingToLoading = chartPhase === "exitingReady";
+    const isRevealActive = chartPhase === "revealing" &&
+        !isLoaded &&
+        (revealMode === "fromLoading" || revealMode === "enter");
+    const isReadyResting = chartStatus === "ready" && chartPhase === "ready" && isLoaded;
+    const participates = useMemo(() => heatmapLoadingCellParticipates(cell.column, cell.row, loadingCellRandomness), [cell.column, cell.row, loadingCellRandomness]);
+    const showShimmerPulse = animateCells && showLoadingCellsLayer && participates && isLoadingResting;
+    const fadeDurationSec = resolveHeatmapEnterFadeDurationSec(enterTransition, animationDuration);
+    const delayMs = computeHeatmapEnterFadeDelayMs({
+        column: cell.column,
+        row: cell.row,
+        revealEpoch,
+        animationDurationMs: animationDuration,
+        enterStaggerScale,
+        fadeDurationSec,
+    });
+    const staggeredTransition = transitionWithDelay(enterTransition, delayMs / 1000);
+    const readyHoverStyle = resolveHeatmapHoverStyle(hoverState.isHighlighted, hoverState.isDimmed, {
+        inactiveOpacity,
+        inactiveScale,
+        activeScale,
+    });
+    const rowOpacityMultiplier = resolveHeatmapRowOpacity(cell.row, rowOpacity);
+    const readyDataOpacity = readyHoverStyle.opacity;
+    const readyScale = isReadyResting ? readyHoverStyle.scale : 1;
+    const transformOrigin = `${cell.x + cell.width / 2}px ${cell.y + cell.height / 2}px`;
+    useEffect(() => {
+        if (!showShimmerPulse) {
+            wasShimmerPulsingRef.current = false;
+            pulseOpacity.set(0);
+            return;
+        }
+        const isFreshLoadingPulse = isLoadingResting && !wasShimmerPulsingRef.current;
+        wasShimmerPulsingRef.current = true;
+        if (isFreshLoadingPulse) {
+            pulseOpacity.set(0);
+        }
+        let cancelled = false;
+        let current;
+        const pulse = async () => {
+            while (!cancelled) {
+                const target = Math.random() * loadingCellMaxOpacity;
+                const duration = 0.35 + Math.random() * 0.85;
+                current = animate(pulseOpacity, target, {
+                    duration,
+                    ease: [0.45, 0, 0.55, 1],
+                });
+                try {
+                    await current;
+                }
+                catch {
+                    break;
+                }
+                if (cancelled) {
+                    break;
+                }
+                await new Promise((resolve) => {
+                    window.setTimeout(resolve, 80 + Math.random() * 420);
+                });
+            }
+        };
+        pulse().catch(() => undefined);
+        return () => {
+            cancelled = true;
+            current?.stop();
+        };
+    }, [isLoadingResting, loadingCellMaxOpacity, pulseOpacity, showShimmerPulse]);
+    useEffect(() => {
+        syncHeatmapCellLayerOpacities({
+            animateCells,
+            chartStatus,
+            dataOpacity,
+            isAwaitingLoadingConceal,
+            isExitingToLoading,
+            isLoadingResting,
+            isReadyResting,
+            isRevealActive,
+            participates,
+            pulseOpacity,
+            readyDataOpacity,
+            shimmerOpacity,
+            showLoadingCellsLayer,
+            showShimmerPulse,
+            staggeredTransition,
+        });
+    }, [
+        animateCells,
+        chartStatus,
+        dataOpacity,
+        isAwaitingLoadingConceal,
+        isExitingToLoading,
+        isLoadingResting,
+        isReadyResting,
+        isRevealActive,
+        participates,
+        pulseOpacity,
+        readyDataOpacity,
+        shimmerOpacity,
+        showLoadingCellsLayer,
+        showShimmerPulse,
+        staggeredTransition,
+    ]);
+    const cellProps = {
+        className: "visx-heatmap-rect",
+        height: cell.height,
+        rx: cornerRadius,
+        ry: cornerRadius,
+        width: cell.width,
+        x: cell.x,
+        y: cell.y,
+    };
+    return (_jsxs(motion.g, { animate: { scale: readyScale }, style: { transformOrigin }, transition: HEATMAP_INACTIVE_TRANSITION, children: [_jsx(motion.rect, { ...cellProps, fill: targetFill, fillOpacity: (cell.opacity ?? 1) * patternFillOpacity * rowOpacityMultiplier, onPointerEnter: () => onEnter(cell.column, cell.row, bin, cell.x, cell.y), onPointerLeave: onLeave, style: {
+                    cursor: interactive ? "pointer" : undefined,
+                    opacity: dataOpacity,
+                } }), _jsx(motion.rect, { ...cellProps, fill: emptyFill, pointerEvents: "none", style: {
+                    opacity: showShimmerPulse ? pulseOpacity : shimmerOpacity,
+                } })] }));
+});
+export const HeatmapCells = memo(function HeatmapCells({ cornerRadius = 2, colorScale: colorScaleProp, inactiveOpacity = HEATMAP_INACTIVE_OPACITY, inactiveScale = 1, activeScale = 1, rowOpacity, interactive = true, hideGhostCells = true, }) {
+    const { data, binWidth, binHeight, gap, margin, xScale, yScale, chartStatus, colorScale: contextColorScale, fillScale: contextFillScale, } = useHeatmap();
+    const colorScale = colorScaleProp ?? contextColorScale;
+    const fillScale = contextFillScale;
+    const cellsInteractive = interactive && chartStatus !== "loading";
+    const { hoveredCell, hoveredLegendLevel, setHoveredCell, setHoveredLegendLevel, setTooltipData } = useHeatmapInteraction();
+    const handleCellEnter = useCallback((column, row, bin, x, y) => {
+        if (!cellsInteractive) {
+            return;
+        }
+        setHoveredLegendLevel(null);
+        setHoveredCell({ column, row });
+        setTooltipData({
+            column,
+            row,
+            count: bin.count,
+            date: bin.date,
+            x: margin.left + x + binWidth / 2,
+            y: margin.top + y + binHeight / 2,
+        });
+    }, [
+        binHeight,
+        binWidth,
+        cellsInteractive,
+        margin.left,
+        margin.top,
+        setHoveredCell,
+        setHoveredLegendLevel,
+        setTooltipData,
+    ]);
+    const handleCellLeave = useCallback(() => {
+        if (!cellsInteractive) {
+            return;
+        }
+        setHoveredCell(null);
+        setTooltipData(null);
+    }, [cellsInteractive, setHoveredCell, setTooltipData]);
+    const inactiveEnabled = isHeatmapHoverEffectEnabled({
+        inactiveOpacity,
+        inactiveScale,
+        activeScale,
+    });
+    const isCellHovering = cellsInteractive && hoveredCell !== null && inactiveEnabled;
+    const isLevelHovering = cellsInteractive && hoveredLegendLevel !== null && inactiveEnabled;
+    const displayRange = useMemo(() => (hideGhostCells ? resolveHeatmapDisplayRange(data) : null), [data, hideGhostCells]);
+    return (_jsx(HeatmapRect, { binHeight: binHeight, bins: (column) => column.bins, binWidth: binWidth, colorScale: (count) => colorScale(typeof count === "number" ? count : count?.valueOf()), count: (bin) => bin.count, data: data, gap: gap, xScale: xScale, yScale: yScale, children: (cells) => (_jsx(Group, { className: "visx-heatmap-rects", children: cells.flatMap((column) => column.map((cell) => {
+                const bin = data[cell.column]?.bins[cell.row];
+                if (!bin) {
+                    return null;
+                }
+                if (displayRange && isHeatmapGhostBin(bin, displayRange)) {
+                    return null;
+                }
+                const hoverState = computeHeatmapCellFaded(isCellHovering, isLevelHovering, hoveredCell, hoveredLegendLevel, cell, bin.count);
+                return (_jsx(HeatmapMotionCell, { activeScale: activeScale, bin: bin, cell: cell, cornerRadius: cornerRadius, fillScale: fillScale, hoverState: hoverState, inactiveOpacity: inactiveOpacity, inactiveScale: inactiveScale, interactive: cellsInteractive, onEnter: handleCellEnter, onLeave: handleCellLeave, rowOpacity: rowOpacity }, `heatmap-cell-${cell.column}-${cell.row}`));
+            })) })) }));
+});
+HeatmapCells.displayName = "HeatmapCells";
+export default HeatmapCells;
+//# sourceMappingURL=heatmap-cells.js.map

package/dist/charts/heatmap/heatmap-chart-loading.d.ts

@@ -0,0 +1,21 @@
+import type { Margin } from "../chart-context.js";
+import type { HeatmapColumn } from "./heatmap-context.js";
+export interface HeatmapChartLoadingProps {
+    /** Target column data used to size the skeleton grid. */
+    data: HeatmapColumn[];
+    /** Visible time range — filters week columns that overlap the domain. */
+    xDomain?: [Date, Date];
+    /** Chart margins */
+    margin?: Partial<Margin>;
+    /** Gap between cells in pixels. Default: 2 */
+    gap?: number;
+    /** Corner radius for each cell. Default: 2 */
+    cornerRadius?: number;
+    /** Centered shimmer label text. Default: "Loading" */
+    label?: string;
+    /** Additional class name for the container */
+    className?: string;
+}
+export declare function HeatmapChartLoading({ data, xDomain, margin, gap, cornerRadius, label, className, }: HeatmapChartLoadingProps): import("react").JSX.Element;
+export default HeatmapChartLoading;
+//# sourceMappingURL=heatmap-chart-loading.d.ts.map

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

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { generateHeatmapSkeletonFromTarget } from "./generate-heatmap-skeleton-data.js";
+import { HeatmapCells } from "./heatmap-cells.js";
+import { HeatmapChart } from "./heatmap-chart.js";
+import { HeatmapXAxis } from "./heatmap-x-axis.js";
+import { HeatmapYAxis } from "./heatmap-y-axis.js";
+export function HeatmapChartLoading({ data, xDomain, margin, gap = 2, cornerRadius = 2, label = "Loading", className = "", }) {
+    const skeletonData = useMemo(() => generateHeatmapSkeletonFromTarget(data), [data]);
+    return (_jsxs(HeatmapChart, { className: className, data: skeletonData, gap: gap, loadingLabel: label, margin: margin, status: "loading", xDomain: xDomain, children: [_jsx(HeatmapCells, { cornerRadius: cornerRadius, interactive: false }), _jsx(HeatmapXAxis, {}), _jsx(HeatmapYAxis, {})] }));
+}
+export default HeatmapChartLoading;
+//# sourceMappingURL=heatmap-chart-loading.js.map

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

@@ -0,0 +1,80 @@
+import type { Transition } from "motion/react";
+import { type ReactNode } from "react";
+import type { Margin } from "../chart-context.js";
+import { type ChartStatus } from "../chart-phase.js";
+import type { HeatmapLevelColors, HeatmapLevelStyles } from "./heatmap-colors.js";
+import { type HeatmapColumn } from "./heatmap-context.js";
+import { type HeatmapSeparatorParsedConfig, type HeatmapWeekStartDay } from "./heatmap-utils.js";
+export type HeatmapLayout = "fluid" | "fill";
+export interface HeatmapChartProps {
+    /** Column data — one entry per week (or category) with row bins inside. */
+    data: HeatmapColumn[];
+    /** Visible time range — filters week columns that overlap the domain. */
+    xDomain?: [Date, Date];
+    /**
+     * Week columns used for cell sizing when `xDomain` is set. Keeps bin height
+     * stable while scrubbing (filtered columns can vary by ±1 at boundaries).
+     */
+    sizingColumnCount?: number;
+    /**
+     * `fluid` — width drives square cells; chart height hugs the grid (GitHub-style).
+     * `fill` — expands cells to fill the parent.
+     */
+    layout?: HeatmapLayout;
+    /** Chart margins */
+    margin?: Partial<Margin>;
+    /** Fixed cell size in pixels. When 0, cells are square and sized to fit the plot. Default: 0 */
+    binSize?: number;
+    /** Gap between cells in pixels. Default: 2 */
+    gap?: number;
+    /** Override the default color scale. */
+    colorScale?: (count: number | null | undefined) => string;
+    /** Per-level colors for the Less → More scale (5 entries). */
+    levelColors?: HeatmapLevelColors;
+    /** Per-level fill styles (color and optional pattern). Takes precedence over `levelColors`. */
+    levelStyles?: HeatmapLevelStyles;
+    /** Optional outer aspect ratio (e.g. "2 / 1"). Omit to fill the parent. */
+    aspectRatio?: string;
+    /** Additional class name for the container */
+    className?: string;
+    /** Fetch / display status. Default: `"ready"`. */
+    status?: ChartStatus;
+    /** Centered label while loading. */
+    loadingLabel?: string;
+    /** Enter animation duration in milliseconds. Default: 1600 */
+    animationDuration?: number;
+    /** Motion enter transition (spring or cubic-bezier tween). */
+    enterTransition?: Transition;
+    /** Signature of motion URL state — triggers enter replay when it changes. */
+    revealSignature?: string;
+    /** Scales wave stagger delays (1 = default). */
+    enterStaggerScale?: number;
+    /** Play enter fade-in / loading shimmer animations. Default: true */
+    animate?: boolean;
+    /** Chart opacity while loading. Default: 0.5 */
+    loadingOpacity?: number;
+    /** Show loading cell shimmer while loading. Default: true */
+    showLoadingCells?: boolean;
+    /** Max opacity loading cells animate toward (0–1). Default: 0.5 */
+    loadingCellMaxOpacity?: number;
+    /** Share of cells that participate in loading shimmer (0–1). Default: 0.65 */
+    loadingCellRandomness?: number;
+    /**
+     * Inserts horizontal gaps between column groups. Overridden when a
+     * {@link HeatmapSeparator} child sets `every` / `spacing`.
+     */
+    columnSeparators?: HeatmapSeparatorParsedConfig;
+    /**
+     * First row of the grid — `0` = Sunday (GitHub default), `1` = Monday, etc.
+     * Rotates column bins for display without reshaping source data.
+     */
+    weekStartDay?: HeatmapWeekStartDay;
+    /** Child components (HeatmapCells, HeatmapXAxis, HeatmapYAxis) */
+    children: ReactNode;
+}
+export declare function HeatmapChart({ data, xDomain, sizingColumnCount, layout, margin: marginProp, binSize, gap, colorScale: colorScaleProp, levelColors, levelStyles: levelStylesProp, aspectRatio, className, status, loadingLabel, animationDuration, enterTransition, revealSignature, enterStaggerScale, animate, loadingOpacity, showLoadingCells, loadingCellMaxOpacity, loadingCellRandomness, columnSeparators, weekStartDay, children, }: HeatmapChartProps): import("react").JSX.Element;
+export declare namespace HeatmapChart {
+    var displayName: string;
+}
+export default HeatmapChart;
+//# sourceMappingURL=heatmap-chart.d.ts.map