@cronus-ui/ui 0.6.0

package/dist/charts/gauge.js

@@ -0,0 +1,307 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ParentSize } from "@visx/responsive";
+import { motion, useReducedMotion } from "motion/react";
+import { useId, useMemo } from "react";
+import { cn } from "../lib/cn.js";
+import { defaultChartStatFlowFormat } from "./chart-stat-flow.js";
+import { GaugeLabelLayout, GaugeLabelShell, } from "./gauge-label-layout.js";
+import { collectGaugeDefsElements, createNotchPath, DEFAULT_ACTIVE_FILL_OPACITY, DEFAULT_ACTIVE_GRADIENT, DEFAULT_INACTIVE_FILL_OPACITY, DEFAULT_LINEAR_GAUGE_HEIGHT, interpolateGaugeHex, resolveGaugeActiveFill, resolveGaugeBgFill, } from "./notch-gauge-shared.js";
+import { PieCenterShell } from "./pie-center-shell.js";
+const DEFAULT_NOTCH_ENTER_TRANSITION = {
+    type: "spring",
+    stiffness: 300,
+    damping: 20,
+};
+function GaugeNotchSvg({ notches, width, height, notchCornerRadius, cornerDepth, geometryScrubbing, notchTransition, stagger, defsChildren, useThemePaletteGradient, themeActiveGradientId, resolvedInactiveFillOpacity, resolvedActiveFillOpacity, resolveBgFill, resolveActiveFill, }) {
+    return (_jsxs("svg", { "aria-hidden": "true", className: "block w-full overflow-visible", height: height, viewBox: `0 0 ${width} ${height}`, width: width, children: [defsChildren.length > 0 || useThemePaletteGradient ? (_jsxs("defs", { children: [useThemePaletteGradient ? (_jsxs("linearGradient", { id: themeActiveGradientId, x1: "0%", x2: "100%", y1: "0%", y2: "0%", children: [_jsx("stop", { offset: "0%", stopColor: "var(--chart-1)" }), _jsx("stop", { offset: "100%", stopColor: "var(--chart-5)" })] })) : null, defsChildren] })) : null, notches.map((notch) => {
+                const pathD = createNotchPath(notch.points, notchCornerRadius, cornerDepth);
+                if (geometryScrubbing) {
+                    return (_jsx("path", { d: pathD, fill: resolveBgFill(notch.index), fillOpacity: resolvedInactiveFillOpacity }, `bg-${notch.index}`));
+                }
+                return (_jsx(motion.path, { animate: { opacity: 1, scale: 1 }, d: pathD, fill: resolveBgFill(notch.index), fillOpacity: resolvedInactiveFillOpacity, initial: { opacity: 0, scale: 0 }, style: {
+                        transformOrigin: `${notch.xCenter}px ${notch.yCenter}px`,
+                    }, transition: {
+                        ...notchTransition,
+                        delay: notch.index * 0.015 * stagger,
+                    } }, `bg-${notch.index}`));
+            }), notches
+                .filter((n) => n.isActive)
+                .map((notch) => {
+                const pathD = createNotchPath(notch.points, notchCornerRadius, cornerDepth);
+                if (geometryScrubbing) {
+                    return (_jsx("path", { d: pathD, fill: resolveActiveFill(notch), fillOpacity: resolvedActiveFillOpacity }, `active-${notch.index}`));
+                }
+                return (_jsx(motion.path, { animate: { opacity: 1, scale: 1 }, d: pathD, fill: resolveActiveFill(notch), fillOpacity: resolvedActiveFillOpacity, initial: { opacity: 0, scale: 0 }, style: {
+                        transformOrigin: `${notch.xCenter}px ${notch.yCenter}px`,
+                    }, transition: {
+                        ...notchTransition,
+                        delay: (0.3 + notch.index * 0.02) * stagger,
+                    } }, `active-${notch.index}`));
+            })] }));
+}
+function useGaugeFillState(props) {
+    const { useGradient = false, activeGradient, inactiveGradient, inactiveFill, activeFill, inactiveFillOpacity, activeFillOpacity, children, totalNotches = 40, } = props;
+    const themeActiveGradientId = `gauge-theme-active-${useId().replace(/:/g, "")}`;
+    const defsChildren = useMemo(() => collectGaugeDefsElements(children), [children]);
+    const hasCustomInactive = inactiveFill !== undefined && inactiveFill.length > 0;
+    const hasCustomActive = activeFill !== undefined && activeFill.length > 0;
+    const activeGrad0 = activeGradient?.[0] ?? DEFAULT_ACTIVE_GRADIENT[0];
+    const activeGrad1 = activeGradient?.[1] ?? DEFAULT_ACTIVE_GRADIENT[1];
+    const inactiveGrad0 = inactiveGradient?.[0] ?? activeGrad0;
+    const inactiveGrad1 = inactiveGradient?.[1] ?? activeGrad1;
+    const useThemePaletteGradient = useGradient && activeGradient === undefined;
+    return {
+        themeActiveGradientId,
+        defsChildren,
+        hasCustomInactive,
+        hasCustomActive,
+        activeGrad0,
+        activeGrad1,
+        inactiveGrad0,
+        inactiveGrad1,
+        useThemePaletteGradient,
+        resolvedActiveFillOpacity: activeFillOpacity ?? DEFAULT_ACTIVE_FILL_OPACITY,
+        resolvedInactiveFillOpacity: inactiveFillOpacity ?? DEFAULT_INACTIVE_FILL_OPACITY,
+        totalNotches,
+    };
+}
+function GaugeArcInner(props) {
+    const { value, totalNotches = 40, spacing = 25, notchCornerRadius = 0, uniformWidth = false, width, height, startAngle = 135, endAngle = 405, useGradient = false, centerValue, defaultLabel = "Total", prefix, suffix, formatOptions = defaultChartStatFlowFormat, inactiveFill, activeFill, notchLengthPercent = 100, enterTransition, enterStaggerScale = 1, } = props;
+    const prefersReducedMotion = useReducedMotion();
+    const fillState = useGaugeFillState(props);
+    const notchTransition = prefersReducedMotion
+        ? { duration: 0 }
+        : (enterTransition ?? DEFAULT_NOTCH_ENTER_TRANSITION);
+    const stagger = Math.max(0.25, Math.min(2.5, enterStaggerScale));
+    const size = Math.min(width, height);
+    const centerX = width / 2;
+    const centerY = height / 2;
+    const outerRadius = size * 0.42;
+    const innerRadiusBase = size * 0.28;
+    const defaultRadialDepth = outerRadius - innerRadiusBase;
+    const depthFactor = Math.min(100, Math.max(5, notchLengthPercent)) / 100;
+    const notchLength = defaultRadialDepth * depthFactor;
+    const innerRadius = outerRadius - notchLength;
+    const activeNotches = Math.round((value / 100) * totalNotches);
+    const totalAngle = endAngle - startAngle;
+    const availableAngle = totalAngle * (1 - spacing / 100);
+    const notchAngle = totalNotches > 0 ? availableAngle / totalNotches : 0;
+    const gapDen = totalNotches - 1 > 0 ? totalNotches - 1 : 1;
+    const gapAngle = (totalAngle * (spacing / 100)) / gapDen;
+    const notches = useMemo(() => {
+        return Array.from({ length: totalNotches }, (_, i) => {
+            const angle = startAngle + i * (notchAngle + gapAngle) + notchAngle / 2;
+            const radians = (angle * Math.PI) / 180;
+            const arcNotchWidth = notchAngle * 0.8;
+            const halfWidth = (arcNotchWidth * Math.PI) / 180 / 2;
+            const x1 = centerX + Math.cos(radians - halfWidth) * outerRadius;
+            const y1 = centerY + Math.sin(radians - halfWidth) * outerRadius;
+            const x2 = centerX + Math.cos(radians + halfWidth) * outerRadius;
+            const y2 = centerY + Math.sin(radians + halfWidth) * outerRadius;
+            let x3;
+            let y3;
+            let x4;
+            let y4;
+            if (uniformWidth) {
+                const perpX = Math.cos(radians);
+                const perpY = Math.sin(radians);
+                x3 = x2 - perpX * notchLength;
+                y3 = y2 - perpY * notchLength;
+                x4 = x1 - perpX * notchLength;
+                y4 = y1 - perpY * notchLength;
+            }
+            else {
+                x3 = centerX + Math.cos(radians + halfWidth) * innerRadius;
+                y3 = centerY + Math.sin(radians + halfWidth) * innerRadius;
+                x4 = centerX + Math.cos(radians - halfWidth) * innerRadius;
+                y4 = centerY + Math.sin(radians - halfWidth) * innerRadius;
+            }
+            const denom = totalNotches > 1 ? totalNotches - 1 : 1;
+            const gradientColor = useGradient && !fillState.useThemePaletteGradient
+                ? interpolateGaugeHex(fillState.activeGrad0, fillState.activeGrad1, i / denom)
+                : "var(--chart-1)";
+            return {
+                index: i,
+                points: { x1, y1, x2, y2, x3, y3, x4, y4 },
+                isActive: i < activeNotches,
+                gradientColor,
+                xCenter: centerX,
+                yCenter: centerY,
+            };
+        });
+    }, [
+        totalNotches,
+        notchAngle,
+        gapAngle,
+        centerX,
+        centerY,
+        outerRadius,
+        innerRadius,
+        activeNotches,
+        startAngle,
+        uniformWidth,
+        notchLength,
+        useGradient,
+        fillState.useThemePaletteGradient,
+        fillState.activeGrad0,
+        fillState.activeGrad1,
+    ]);
+    const resolveBgFill = (notchIndex) => resolveGaugeBgFill({
+        notchIndex,
+        totalNotches,
+        hasCustomInactive: fillState.hasCustomInactive,
+        inactiveFill,
+        useThemePaletteGradient: fillState.useThemePaletteGradient,
+        useGradient,
+        inactiveGrad0: fillState.inactiveGrad0,
+        inactiveGrad1: fillState.inactiveGrad1,
+        arcTrackFill: "var(--border)",
+        linearTrackFill: "var(--chart-background)",
+        linearMode: false,
+    });
+    const resolveActiveFill = (notch) => resolveGaugeActiveFill({
+        notch,
+        hasCustomActive: fillState.hasCustomActive,
+        activeFill,
+        useThemePaletteGradient: fillState.useThemePaletteGradient,
+        themeActiveGradientId: fillState.themeActiveGradientId,
+        useGradient,
+        activeFillSolid: "var(--chart-1)",
+    });
+    const showCenter = centerValue != null;
+    return (_jsxs("div", { className: "relative w-full", style: { height, width }, children: [_jsx(GaugeNotchSvg, { cornerDepth: notchLength, defsChildren: fillState.defsChildren, geometryScrubbing: false, height: height, notchCornerRadius: notchCornerRadius, notches: notches, notchTransition: notchTransition, resolveActiveFill: resolveActiveFill, resolveBgFill: resolveBgFill, resolvedActiveFillOpacity: fillState.resolvedActiveFillOpacity, resolvedInactiveFillOpacity: fillState.resolvedInactiveFillOpacity, stagger: stagger, themeActiveGradientId: fillState.themeActiveGradientId, useThemePaletteGradient: fillState.useThemePaletteGradient, width: width }), showCenter ? (_jsx("div", { className: "pointer-events-none absolute inset-0 flex flex-col items-center justify-center", style: { paddingTop: size * 0.08 }, children: _jsx(PieCenterShell, { centerValue: centerValue, contextSize: size, defaultLabel: defaultLabel, formatOptions: formatOptions, innerRadiusPx: Math.max(size * 0.2, 52), prefix: prefix, suffix: suffix }) })) : null] }));
+}
+function GaugeLinearInner(props) {
+    const { value, totalNotches = 40, spacing = 25, notchCornerRadius = 0, uniformWidth = true, width, height, useGradient = false, centerValue, defaultLabel = "Total", prefix, suffix, formatOptions = defaultChartStatFlowFormat, labelPlacement = "top", labelAlign = "start", inactiveFill, activeFill, notchLengthPercent = 100, notchWidthPercent = 80, enterTransition, enterStaggerScale = 1, geometryScrubbing = false, } = props;
+    const prefersReducedMotion = useReducedMotion();
+    const fillState = useGaugeFillState(props);
+    const notchTransition = prefersReducedMotion
+        ? { duration: 0 }
+        : (enterTransition ?? DEFAULT_NOTCH_ENTER_TRANSITION);
+    const stagger = Math.max(0.25, Math.min(2.5, enterStaggerScale));
+    const centerY = height / 2;
+    const depthFactor = Math.min(100, Math.max(5, notchLengthPercent)) / 100;
+    const outerOffset = (height / 2) * depthFactor;
+    const taperRatio = 28 / 42;
+    const innerOffset = uniformWidth ? outerOffset : outerOffset * taperRatio;
+    const notchDepth = uniformWidth ? outerOffset * 2 : outerOffset - innerOffset;
+    const cornerVerticalDepth = uniformWidth ? notchDepth : outerOffset * 2;
+    const widthFactor = Math.min(100, Math.max(10, notchWidthPercent)) / 100;
+    const activeNotches = Math.round((value / 100) * totalNotches);
+    const availableWidth = width * (1 - spacing / 100);
+    const slotWidth = totalNotches > 0 ? availableWidth / totalNotches : 0;
+    const gapDen = totalNotches - 1 > 0 ? totalNotches - 1 : 1;
+    const gapWidth = (width * (spacing / 100)) / gapDen;
+    const notches = useMemo(() => {
+        return Array.from({ length: totalNotches }, (_, i) => {
+            const xCenter = i * (slotWidth + gapWidth) + slotWidth / 2;
+            const halfWidth = (slotWidth * widthFactor) / 2;
+            let x1;
+            let y1;
+            let x2;
+            let y2;
+            let x3;
+            let y3;
+            let x4;
+            let y4;
+            if (uniformWidth) {
+                const halfHeight = notchDepth / 2;
+                x1 = xCenter - halfWidth;
+                y1 = centerY - halfHeight;
+                x2 = xCenter + halfWidth;
+                y2 = centerY - halfHeight;
+                x3 = xCenter + halfWidth;
+                y3 = centerY + halfHeight;
+                x4 = xCenter - halfWidth;
+                y4 = centerY + halfHeight;
+            }
+            else {
+                x1 = xCenter - halfWidth;
+                y1 = centerY - outerOffset;
+                x2 = xCenter + halfWidth;
+                y2 = centerY - outerOffset;
+                const innerHalfWidth = halfWidth * (innerOffset / outerOffset);
+                x3 = xCenter + innerHalfWidth;
+                y3 = centerY + outerOffset;
+                x4 = xCenter - innerHalfWidth;
+                y4 = centerY + outerOffset;
+            }
+            const denom = totalNotches > 1 ? totalNotches - 1 : 1;
+            const gradientColor = useGradient && !fillState.useThemePaletteGradient
+                ? interpolateGaugeHex(fillState.activeGrad0, fillState.activeGrad1, i / denom)
+                : "var(--chart-1)";
+            return {
+                index: i,
+                points: { x1, y1, x2, y2, x3, y3, x4, y4 },
+                isActive: i < activeNotches,
+                gradientColor,
+                xCenter,
+                yCenter: centerY,
+            };
+        });
+    }, [
+        totalNotches,
+        slotWidth,
+        gapWidth,
+        centerY,
+        outerOffset,
+        innerOffset,
+        activeNotches,
+        uniformWidth,
+        notchDepth,
+        widthFactor,
+        useGradient,
+        fillState.useThemePaletteGradient,
+        fillState.activeGrad0,
+        fillState.activeGrad1,
+    ]);
+    const resolveBgFill = (notchIndex) => resolveGaugeBgFill({
+        notchIndex,
+        totalNotches,
+        hasCustomInactive: fillState.hasCustomInactive,
+        inactiveFill,
+        useThemePaletteGradient: fillState.useThemePaletteGradient,
+        useGradient,
+        inactiveGrad0: fillState.inactiveGrad0,
+        inactiveGrad1: fillState.inactiveGrad1,
+        arcTrackFill: "var(--border)",
+        linearTrackFill: "var(--chart-background)",
+        linearMode: true,
+    });
+    const resolveActiveFill = (notch) => resolveGaugeActiveFill({
+        notch,
+        hasCustomActive: fillState.hasCustomActive,
+        activeFill,
+        useThemePaletteGradient: fillState.useThemePaletteGradient,
+        themeActiveGradientId: fillState.themeActiveGradientId,
+        useGradient,
+        activeFillSolid: "var(--chart-1)",
+    });
+    const label = centerValue == null ? null : (_jsx(GaugeLabelShell, { align: labelAlign, centerValue: centerValue, defaultLabel: defaultLabel, formatOptions: formatOptions, prefix: prefix, suffix: suffix }));
+    const track = (_jsx("div", { className: "relative w-full", style: { height, width }, children: _jsx(GaugeNotchSvg, { cornerDepth: cornerVerticalDepth, defsChildren: fillState.defsChildren, geometryScrubbing: geometryScrubbing, height: height, notchCornerRadius: notchCornerRadius, notches: notches, notchTransition: notchTransition, resolveActiveFill: resolveActiveFill, resolveBgFill: resolveBgFill, resolvedActiveFillOpacity: fillState.resolvedActiveFillOpacity, resolvedInactiveFillOpacity: fillState.resolvedInactiveFillOpacity, stagger: stagger, themeActiveGradientId: fillState.themeActiveGradientId, useThemePaletteGradient: fillState.useThemePaletteGradient, width: width }) }));
+    return (_jsx(GaugeLabelLayout, { align: labelAlign, label: label, placement: labelPlacement, children: track }));
+}
+function GaugeInner(props) {
+    if (props.orientation === "linear") {
+        return _jsx(GaugeLinearInner, { ...props });
+    }
+    return _jsx(GaugeArcInner, { ...props });
+}
+export function Gauge({ width: widthProp, height: heightProp, className, minWidth, orientation = "arc", linearHeight, ...props }) {
+    const isLinear = orientation === "linear";
+    const resolvedMinWidth = minWidth ?? (isLinear ? 200 : 300);
+    const resolvedLinearHeight = linearHeight ?? DEFAULT_LINEAR_GAUGE_HEIGHT;
+    if (isLinear) {
+        if (widthProp != null) {
+            return (_jsx("div", { "data-slot": "gauge-chart", className: cn("relative w-full max-w-full", className), style: { width: widthProp }, children: _jsx(GaugeInner, { height: heightProp ?? resolvedLinearHeight, orientation: "linear", width: widthProp, ...props }) }));
+        }
+        return (_jsx("div", { className: cn("relative w-full min-w-0 max-w-full", className), "data-slot": "gauge-chart", children: _jsx("div", { className: "w-full min-w-0", style: { minWidth: resolvedMinWidth }, children: _jsx(ParentSize, { debounceTime: 10, children: ({ width }) => width > 0 ? (_jsx(GaugeInner, { height: resolvedLinearHeight, orientation: "linear", width: width, ...props })) : null }) }) }));
+    }
+    if (widthProp != null && heightProp != null) {
+        return (_jsx("div", { className: cn("relative inline-flex max-w-full", className), "data-slot": "gauge-chart", children: _jsx(GaugeInner, { height: heightProp, orientation: "arc", width: widthProp, ...props }) }));
+    }
+    return (_jsx("div", { className: cn("relative w-full max-w-full", className), "data-slot": "gauge-chart", style: { minWidth: resolvedMinWidth }, children: _jsx("div", { className: "mx-auto aspect-[21/16] w-full max-w-[560px]", children: _jsx(ParentSize, { debounceTime: 10, children: ({ width, height }) => width > 0 && height > 0 ? (_jsx(GaugeInner, { height: height, orientation: "arc", width: width, ...props })) : null }) }) }));
+}
+Gauge.displayName = "Gauge";
+//# sourceMappingURL=gauge.js.map

package/dist/charts/generate-chart-skeleton-data.d.ts

@@ -0,0 +1,16 @@
+declare const DEFAULT_SKELETON_DATA_KEY = "value";
+declare const DEFAULT_SKELETON_POINT_COUNT = 7;
+export interface GenerateChartSkeletonDataOptions {
+    /** Key used for y values in each row. Default: `"value"`. */
+    dataKey?: string;
+    /** Number of points. Default: 7. */
+    pointCount?: number;
+    /** Start date for the x axis. Default: 2025-01-01. */
+    baseDate?: Date;
+}
+/** Placeholder series used while `status="loading"` and data is empty. */
+export declare function generateChartSkeletonData(options?: GenerateChartSkeletonDataOptions): Record<string, unknown>[];
+/** Skeleton rows that mirror target dates/count with lower magnitudes for Y tween. */
+export declare function generateChartSkeletonFromTarget(targetData: Record<string, unknown>[], dataKey: string): Record<string, unknown>[];
+export { DEFAULT_SKELETON_DATA_KEY, DEFAULT_SKELETON_POINT_COUNT };
+//# sourceMappingURL=generate-chart-skeleton-data.d.ts.map

package/dist/charts/generate-chart-skeleton-data.js

@@ -0,0 +1,25 @@
+const DEFAULT_SKELETON_DATA_KEY = "value";
+const DEFAULT_SKELETON_POINT_COUNT = 7;
+/** Placeholder series used while `status="loading"` and data is empty. */
+export function generateChartSkeletonData(options = {}) {
+    const dataKey = options.dataKey ?? DEFAULT_SKELETON_DATA_KEY;
+    const pointCount = options.pointCount ?? DEFAULT_SKELETON_POINT_COUNT;
+    const baseDate = options.baseDate ?? new Date("2025-01-01");
+    return Array.from({ length: pointCount }, (_, index) => {
+        const date = new Date(baseDate);
+        date.setDate(baseDate.getDate() + index);
+        return {
+            date,
+            [dataKey]: Math.round(110 + Math.sin(index * 1.15) * 36 + index * 9),
+        };
+    });
+}
+/** Skeleton rows that mirror target dates/count with lower magnitudes for Y tween. */
+export function generateChartSkeletonFromTarget(targetData, dataKey) {
+    return targetData.map((row, index) => ({
+        ...row,
+        [dataKey]: Math.round(95 + Math.sin(index * 1.05) * 28 + index * 7),
+    }));
+}
+export { DEFAULT_SKELETON_DATA_KEY, DEFAULT_SKELETON_POINT_COUNT };
+//# sourceMappingURL=generate-chart-skeleton-data.js.map

package/dist/charts/grid.d.ts

@@ -0,0 +1,58 @@
+export interface GridProps {
+    /** Show horizontal grid lines. Default: true */
+    horizontal?: boolean;
+    /** Show vertical grid lines. Default: false */
+    vertical?: boolean;
+    /** Number of horizontal grid lines. Default: 5 */
+    numTicksRows?: number;
+    /** Number of vertical grid lines. Default: 10 */
+    numTicksColumns?: number;
+    /** Explicit tick values for horizontal grid lines. Overrides numTicksRows. */
+    rowTickValues?: number[];
+    /** Grid line stroke color. Default: var(--chart-grid) */
+    stroke?: string;
+    /** Grid stroke while loading chrome is active. Falls back to `stroke`. */
+    loadingStroke?: string;
+    /** Grid line stroke opacity. Default: 1 */
+    strokeOpacity?: number;
+    /** Grid line stroke width. Default: 1 */
+    strokeWidth?: number;
+    /** Grid line dash array. Default: "4,4" for dashed lines */
+    strokeDasharray?: string;
+    /** Horizontal row values rendered with alternate styling (e.g. zero baseline). */
+    highlightRowValues?: number[];
+    /** Stroke for highlighted rows. Default: var(--chart-foreground-muted) */
+    highlightRowStroke?: string;
+    /** Stroke opacity for highlighted rows. Default: 1 */
+    highlightRowStrokeOpacity?: number;
+    /** Stroke width for highlighted rows. Default: 1 */
+    highlightRowStrokeWidth?: number;
+    /** Dash array for highlighted rows. Default: solid line */
+    highlightRowStrokeDasharray?: string;
+    /** Enable horizontal fade effect on grid rows (fades at left/right). Default: true */
+    fadeHorizontal?: boolean;
+    /** Enable vertical fade effect on grid columns (fades at top/bottom). Default: false */
+    fadeVertical?: boolean;
+    /** Omit the first and last horizontal grid lines. Default: false */
+    hideHorizontalEdgeLines?: boolean;
+    /** Omit the first and last vertical grid lines. Default: false */
+    hideVerticalEdgeLines?: boolean;
+    /** Y-scale for horizontal grid lines. Default: primary (`"left"`) axis. */
+    yAxisId?: string | number;
+    /** Animate a shimmer band across horizontal grid lines. Default: false */
+    shimmer?: boolean;
+    /** Shimmer band stroke (color and opacity via color-mix or oklch alpha). */
+    shimmerStroke?: string;
+    /** Shimmer band width in pixels. Default: 140 */
+    shimmerLength?: number;
+    /** Shimmer speed multiplier (higher = faster). Default: 1 */
+    shimmerSpeed?: number;
+    /** Match loop timing to the loading line pulse (cycle + inter-loop pause). */
+    shimmerSync?: boolean;
+}
+export declare function Grid({ horizontal, vertical, numTicksRows, numTicksColumns, rowTickValues, stroke, loadingStroke, strokeOpacity, strokeWidth, strokeDasharray, highlightRowValues, highlightRowStroke, highlightRowStrokeOpacity, highlightRowStrokeWidth, highlightRowStrokeDasharray, fadeHorizontal, fadeVertical, hideHorizontalEdgeLines, hideVerticalEdgeLines, yAxisId, shimmer, shimmerStroke, shimmerLength, shimmerSpeed, shimmerSync, }: GridProps): import("react").JSX.Element;
+export declare namespace Grid {
+    var displayName: string;
+}
+export default Grid;
+//# sourceMappingURL=grid.d.ts.map

package/dist/charts/grid.js

@@ -0,0 +1,80 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { GridColumns, GridRows } from "@visx/grid";
+import { motion } from "motion/react";
+import { useId } from "react";
+import { chartCssVars, useChartStable, useYScale } from "./chart-context.js";
+import { useGridShimmer } from "./use-grid-shimmer.js";
+import { isLoadingChromePhase, isLoadingGridChromePhase } from "./y-domain-utils.js";
+const DEFAULT_SHIMMER_LENGTH_PX = 140;
+const DEFAULT_SHIMMER_SPEED = 1;
+const DEFAULT_SHIMMER_STROKE = "color-mix(in oklch, var(--foreground) 68%, transparent)";
+function hideEdgeTicks(ticks, hideEdgeLines) {
+    if (!hideEdgeLines || ticks.length <= 2) {
+        return ticks;
+    }
+    return ticks.slice(1, -1);
+}
+function resolveRowTickValues(options) {
+    const { hideHorizontalEdgeLines, numTicksRows, rowTickValues, yScale } = options;
+    const ticks = rowTickValues ?? (yScale.ticks ? yScale.ticks(numTicksRows) : []);
+    const filtered = hideEdgeTicks(ticks, hideHorizontalEdgeLines);
+    if (filtered === ticks && !rowTickValues && !hideHorizontalEdgeLines) {
+        return undefined;
+    }
+    return filtered.length > 0 ? filtered : undefined;
+}
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: grid fade masks and shimmer share one layer tree
+export function Grid({ horizontal = true, vertical = false, numTicksRows = 5, numTicksColumns = 10, rowTickValues, stroke = chartCssVars.grid, loadingStroke, strokeOpacity = 1, strokeWidth = 1, strokeDasharray = "4,4", highlightRowValues, highlightRowStroke = chartCssVars.foregroundMuted, highlightRowStrokeOpacity = 1, highlightRowStrokeWidth = 1, highlightRowStrokeDasharray = "0", fadeHorizontal = true, fadeVertical = false, hideHorizontalEdgeLines = false, hideVerticalEdgeLines = false, yAxisId, shimmer = false, shimmerStroke = DEFAULT_SHIMMER_STROKE, shimmerLength = DEFAULT_SHIMMER_LENGTH_PX, shimmerSpeed = DEFAULT_SHIMMER_SPEED, shimmerSync = false, }) {
+    const { xScale, innerWidth, innerHeight, orientation, barScale, chartPhase } = useChartStable();
+    const yScale = useYScale(yAxisId);
+    const shimmerActive = shimmer && isLoadingChromePhase(chartPhase);
+    const gridStroke = isLoadingGridChromePhase(chartPhase) && loadingStroke != null ? loadingStroke : stroke;
+    const { shimmerEnabled, shimmerTransform } = useGridShimmer({
+        innerWidth,
+        shimmer,
+        shimmerLength,
+        shimmerSpeed,
+        shimmerSync,
+        active: shimmerActive,
+    });
+    // For bar charts, determine which scale to use for grid lines
+    // Horizontal bar charts: vertical grid should use yScale (value scale)
+    // Vertical bar charts: horizontal grid uses yScale (value scale)
+    const isHorizontalBarChart = orientation === "horizontal" && barScale;
+    // For vertical grid lines in horizontal bar charts, use yScale (the value scale)
+    // For time-based charts, use xScale
+    const columnScale = isHorizontalBarChart ? yScale : xScale;
+    const rowTickValuesResolved = resolveRowTickValues({
+        hideHorizontalEdgeLines,
+        numTicksRows,
+        rowTickValues,
+        yScale,
+    });
+    const columnTickValuesResolved = vertical && columnScale && typeof columnScale === "function" && hideVerticalEdgeLines
+        ? (() => {
+            const ticks = columnScale.ticks?.(numTicksColumns) ?? [];
+            const filtered = hideEdgeTicks(ticks, true);
+            return filtered.length > 0 ? filtered : undefined;
+        })()
+        : undefined;
+    const uniqueId = useId();
+    // Horizontal fade mask (for grid rows - fades left/right)
+    const hMaskId = `grid-rows-fade-${uniqueId}`;
+    const hGradientId = `${hMaskId}-gradient`;
+    const shimmerGradientId = `grid-shimmer-${uniqueId}`;
+    // Vertical fade mask (for grid columns - fades top/bottom)
+    const vMaskId = `grid-cols-fade-${uniqueId}`;
+    const vGradientId = `${vMaskId}-gradient`;
+    const horizontalFadeMask = fadeHorizontal ? `url(#${hMaskId})` : undefined;
+    return (_jsxs("g", { className: "chart-grid", children: [horizontal && fadeHorizontal && (_jsxs("defs", { children: [_jsxs("linearGradient", { id: hGradientId, x1: "0%", x2: "100%", y1: "0%", y2: "0%", children: [_jsx("stop", { offset: "0%", style: { stopColor: "white", stopOpacity: 0 } }), _jsx("stop", { offset: "10%", style: { stopColor: "white", stopOpacity: 1 } }), _jsx("stop", { offset: "90%", style: { stopColor: "white", stopOpacity: 1 } }), _jsx("stop", { offset: "100%", style: { stopColor: "white", stopOpacity: 0 } })] }), _jsx("mask", { id: hMaskId, children: _jsx("rect", { fill: `url(#${hGradientId})`, height: innerHeight, width: innerWidth, x: "0", y: "0" }) })] })), horizontal && shimmerEnabled ? (_jsx("defs", { children: _jsxs(motion.linearGradient, { gradientTransform: shimmerTransform, gradientUnits: "userSpaceOnUse", id: shimmerGradientId, x1: 0, x2: shimmerLength, y1: 0, y2: 0, children: [_jsx("stop", { offset: "0%", stopColor: shimmerStroke, stopOpacity: 0 }), _jsx("stop", { offset: "35%", stopColor: shimmerStroke, stopOpacity: 0.45 }), _jsx("stop", { offset: "50%", stopColor: shimmerStroke, stopOpacity: 1 }), _jsx("stop", { offset: "65%", stopColor: shimmerStroke, stopOpacity: 0.45 }), _jsx("stop", { offset: "100%", stopColor: shimmerStroke, stopOpacity: 0 })] }) })) : null, vertical && fadeVertical && (_jsxs("defs", { children: [_jsxs("linearGradient", { id: vGradientId, x1: "0%", x2: "0%", y1: "0%", y2: "100%", children: [_jsx("stop", { offset: "0%", style: { stopColor: "white", stopOpacity: 0 } }), _jsx("stop", { offset: "10%", style: { stopColor: "white", stopOpacity: 1 } }), _jsx("stop", { offset: "90%", style: { stopColor: "white", stopOpacity: 1 } }), _jsx("stop", { offset: "100%", style: { stopColor: "white", stopOpacity: 0 } })] }), _jsx("mask", { id: vMaskId, children: _jsx("rect", { fill: `url(#${vGradientId})`, height: innerHeight, width: innerWidth, x: "0", y: "0" }) })] })), horizontal && (_jsxs("g", { mask: horizontalFadeMask, children: [_jsx(GridRows, { numTicks: rowTickValuesResolved ? undefined : numTicksRows, scale: yScale, stroke: gridStroke, strokeDasharray: strokeDasharray, strokeOpacity: strokeOpacity, strokeWidth: strokeWidth, tickValues: rowTickValuesResolved, width: innerWidth }), shimmerEnabled ? (_jsx(GridRows, { numTicks: rowTickValuesResolved ? undefined : numTicksRows, scale: yScale, stroke: `url(#${shimmerGradientId})`, strokeDasharray: strokeDasharray, strokeOpacity: 1, strokeWidth: strokeWidth, tickValues: rowTickValuesResolved, width: innerWidth })) : null] })), horizontal && highlightRowValues && highlightRowValues.length > 0 ? (_jsx("g", { className: "chart-grid-highlight-rows", children: highlightRowValues.map((value) => {
+                    const y = yScale(value);
+                    if (y == null || !Number.isFinite(y)) {
+                        return null;
+                    }
+                    return (_jsx("line", { stroke: highlightRowStroke, strokeDasharray: highlightRowStrokeDasharray, strokeOpacity: highlightRowStrokeOpacity, strokeWidth: highlightRowStrokeWidth, x1: 0, x2: innerWidth, y1: y, y2: y }, value));
+                }) })) : null, vertical && columnScale && typeof columnScale === "function" && (_jsx("g", { mask: fadeVertical ? `url(#${vMaskId})` : undefined, children: _jsx(GridColumns, { height: innerHeight, numTicks: columnTickValuesResolved ? undefined : numTicksColumns, scale: columnScale, stroke: stroke, strokeDasharray: strokeDasharray, strokeOpacity: strokeOpacity, strokeWidth: strokeWidth, tickValues: columnTickValuesResolved }) }))] }));
+}
+Grid.displayName = "Grid";
+export default Grid;
+//# sourceMappingURL=grid.js.map

package/dist/charts/heatmap/generate-heatmap-skeleton-data.d.ts

@@ -0,0 +1,4 @@
+import type { HeatmapColumn } from "./heatmap-context.js";
+/** Placeholder grid with the same week/day shape as target data (all empty cells). */
+export declare function generateHeatmapSkeletonFromTarget(target: HeatmapColumn[]): HeatmapColumn[];
+//# sourceMappingURL=generate-heatmap-skeleton-data.d.ts.map

package/dist/charts/heatmap/generate-heatmap-skeleton-data.js

@@ -0,0 +1,12 @@
+/** Placeholder grid with the same week/day shape as target data (all empty cells). */
+export function generateHeatmapSkeletonFromTarget(target) {
+    return target.map((column) => ({
+        bin: column.bin,
+        bins: column.bins.map((bin) => ({
+            bin: bin.bin,
+            count: 0,
+            date: bin.date,
+        })),
+    }));
+}
+//# sourceMappingURL=generate-heatmap-skeleton-data.js.map

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

@@ -0,0 +1,41 @@
+import type { Transition } from "motion/react";
+import type { HeatmapColumn } from "./heatmap-context.js";
+/** Default enter duration when no motion props are passed (ms). */
+export declare const HEATMAP_DEFAULT_ENTER_DURATION_MS = 1600;
+/** Default cubic-bezier for heatmap cell enter / loading transitions. */
+export declare const HEATMAP_DEFAULT_ENTER_EASE: readonly [0.85, 0, 0.916, 0.282];
+/** Default enter transition for {@link HeatmapChart}. */
+export declare const HEATMAP_DEFAULT_ENTER_TRANSITION: Transition;
+/** Chart opacity while `status="loading"`. */
+export declare const HEATMAP_LOADING_CHART_OPACITY = 1;
+/** Default max per-cell opacity during loading shimmer. */
+export declare const HEATMAP_DEFAULT_LOADING_CELL_MAX_OPACITY = 0.85;
+/** Default share of cells that participate in loading shimmer (0–1). */
+export declare const HEATMAP_DEFAULT_LOADING_CELL_RANDOMNESS = 1;
+/** Opacity for loading cells that do not participate in shimmer. */
+export declare const HEATMAP_LOADING_BASE_CELL_OPACITY = 0.2;
+/** Duration for ready → loading cell conceal before shimmer resumes (ms). */
+export declare const HEATMAP_LOADING_CONCEAL_MS = 450;
+/** Share of the enter window used for random fade-in delays. */
+export declare const HEATMAP_ENTER_STAGGER_SPREAD = 0.6;
+export declare function heatmapCellSeed(column: number, row: number): number;
+export interface HeatmapLevelRange {
+    min: number;
+    max: number;
+}
+/** Min/max contribution levels present in the dataset. */
+export declare function computeHeatmapLevelRange(data: HeatmapColumn[]): HeatmapLevelRange;
+/** Per-cell fade duration derived from the motion enter transition. */
+export declare function resolveHeatmapEnterFadeDurationSec(enterTransition: Transition | undefined, animationDurationMs: number): number;
+/** Random delay so all cells finish fading in within `animationDurationMs`. */
+export declare function computeHeatmapEnterFadeDelayMs({ column, row, revealEpoch, animationDurationMs, enterStaggerScale, fadeDurationSec, }: {
+    column: number;
+    row: number;
+    revealEpoch: number;
+    animationDurationMs: number;
+    enterStaggerScale: number;
+    fadeDurationSec: number;
+}): number;
+/** Whether a cell participates in loading shimmer for a given randomness (0–1). */
+export declare function heatmapLoadingCellParticipates(column: number, row: number, randomness: number): boolean;
+//# sourceMappingURL=heatmap-animation.d.ts.map

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

@@ -0,0 +1,85 @@
+import { getHeatmapContributionLevel } from "./heatmap-utils.js";
+/** Default enter duration when no motion props are passed (ms). */
+export const HEATMAP_DEFAULT_ENTER_DURATION_MS = 1600;
+/** Default cubic-bezier for heatmap cell enter / loading transitions. */
+export const HEATMAP_DEFAULT_ENTER_EASE = [0.85, 0, 0.916, 0.282];
+/** Default enter transition for {@link HeatmapChart}. */
+export const HEATMAP_DEFAULT_ENTER_TRANSITION = {
+    type: "tween",
+    duration: HEATMAP_DEFAULT_ENTER_DURATION_MS / 1000,
+    ease: HEATMAP_DEFAULT_ENTER_EASE,
+};
+/** Chart opacity while `status="loading"`. */
+export const HEATMAP_LOADING_CHART_OPACITY = 1;
+/** Default max per-cell opacity during loading shimmer. */
+export const HEATMAP_DEFAULT_LOADING_CELL_MAX_OPACITY = 0.85;
+/** Default share of cells that participate in loading shimmer (0–1). */
+export const HEATMAP_DEFAULT_LOADING_CELL_RANDOMNESS = 1;
+/** Opacity for loading cells that do not participate in shimmer. */
+export const HEATMAP_LOADING_BASE_CELL_OPACITY = 0.2;
+/** Duration for ready → loading cell conceal before shimmer resumes (ms). */
+export const HEATMAP_LOADING_CONCEAL_MS = 450;
+/** Share of the enter window used for random fade-in delays. */
+export const HEATMAP_ENTER_STAGGER_SPREAD = 0.6;
+function seededRandom(seed) {
+    let state = seed % 2_147_483_647;
+    if (state <= 0) {
+        state += 2_147_483_646;
+    }
+    return () => {
+        state = (state * 16_807) % 2_147_483_647;
+        return (state - 1) / 2_147_483_646;
+    };
+}
+export function heatmapCellSeed(column, row) {
+    return column * 1009 + row * 9176;
+}
+/** Min/max contribution levels present in the dataset. */
+export function computeHeatmapLevelRange(data) {
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    for (const column of data) {
+        for (const bin of column.bins) {
+            const level = getHeatmapContributionLevel(bin.count);
+            if (level < min) {
+                min = level;
+            }
+            if (level > max) {
+                max = level;
+            }
+        }
+    }
+    if (!(Number.isFinite(min) && Number.isFinite(max))) {
+        return { min: 0, max: 4 };
+    }
+    return { min, max };
+}
+/** Per-cell fade duration derived from the motion enter transition. */
+export function resolveHeatmapEnterFadeDurationSec(enterTransition, animationDurationMs) {
+    if (enterTransition &&
+        "duration" in enterTransition &&
+        typeof enterTransition.duration === "number") {
+        return enterTransition.duration;
+    }
+    return Math.min(0.45, (animationDurationMs / 1000) * 0.3);
+}
+/** Random delay so all cells finish fading in within `animationDurationMs`. */
+export function computeHeatmapEnterFadeDelayMs({ column, row, revealEpoch, animationDurationMs, enterStaggerScale, fadeDurationSec, }) {
+    const random = seededRandom(heatmapCellSeed(column, row) + revealEpoch * 524_287);
+    const fadeMs = fadeDurationSec * 1000;
+    const maxDelayMs = Math.max(0, animationDurationMs - fadeMs);
+    const spreadMs = maxDelayMs * HEATMAP_ENTER_STAGGER_SPREAD * Math.max(enterStaggerScale, 0.25);
+    return random() * spreadMs;
+}
+/** Whether a cell participates in loading shimmer for a given randomness (0–1). */
+export function heatmapLoadingCellParticipates(column, row, randomness) {
+    if (randomness >= 1) {
+        return true;
+    }
+    if (randomness <= 0) {
+        return false;
+    }
+    const random = seededRandom(heatmapCellSeed(column, row) + 73_133);
+    return random() < randomness;
+}
+//# sourceMappingURL=heatmap-animation.js.map