@flikk/ui 1.0.0-beta.29 → 1.0.0-beta.30

package/dist/components/charts/BarChart/BarChart.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useId, useState, useEffect, useRef, useMemo } from 'react';
-import { useReducedMotion, motion, AnimatePresence } from 'motion/react';
+import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { useTooltipPosition } from '../hooks/useTooltipPosition.js';
 import { useChartAccessibility } from '../hooks/useChartAccessibility.js';
@@ -11,8 +12,11 @@ import { XAxis } from '../shared/ChartAxis/XAxis.js';
 import { YAxis } from '../shared/ChartAxis/YAxis.js';
 import { HorizontalGrid } from '../shared/ChartGrid/HorizontalGrid.js';
 import { ChartTooltip } from '../shared/ChartTooltip/ChartTooltip.js';
+import { resolveLegendPosition, ChartLegend } from '../shared/ChartLegend/ChartLegend.js';
 import { BAR_CHART_DEFAULTS } from './BarChart.types.js';
 import { X_AXIS_MARGIN } from '../types/chart.types.js';
+import { BAR_GROUP_STAGGER, BAR_SPRING, barEntranceTransition } from '../utils/animation-utils.js';
+import { BarSeriesDefs, BarGlowRing, barStrokeStyle, barFill, barDimOpacity, deriveBarEmphasis } from '../utils/bar-emphasis.js';
 import { ExclamationTriangleIcon } from '@heroicons/react/20/solid';
 
 // Pure helper functions moved to module level to avoid recreation per render
@@ -51,12 +55,12 @@ const calculateAverageForKey = (sanitizedData, key, safeMathDivide) => {
 };
 const BarChart = ({ data, config, 
 // Standardized display props with defaults
-showGrid = BAR_CHART_DEFAULTS.showGrid, showXAxis = BAR_CHART_DEFAULTS.showXAxis, showYAxis = BAR_CHART_DEFAULTS.showYAxis, minValue: propMinValue, maxValue: propMaxValue, variant = BAR_CHART_DEFAULTS.variant, theme, 
+showGrid = BAR_CHART_DEFAULTS.showGrid, showXAxis = BAR_CHART_DEFAULTS.showXAxis, showYAxis = BAR_CHART_DEFAULTS.showYAxis, legend, minValue: propMinValue, maxValue: propMaxValue, variant = BAR_CHART_DEFAULTS.variant, theme, 
 // Standardized visual props with defaults (renamed from bar-specific names)
 barRadius, radius, // @deprecated Use barRadius instead
 gap = BAR_CHART_DEFAULTS.gap, categoryGap = BAR_CHART_DEFAULTS.categoryGap, 
 // Bar-specific props
-orientation = BAR_CHART_DEFAULTS.orientation, 
+orientation, 
 // Animation props
 showAnimation = BAR_CHART_DEFAULTS.showAnimation, 
 // Placeholder bar props
@@ -93,18 +97,7 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
     // Validate data and config with error handling
     const { validation, sanitizedData, isValid, hasWarnings, safeScale, safeMath, } = useChartValidation(data, config, {
         autoSanitize: true,
-        logWarnings: true,
     });
-    // Early return for invalid data with error message
-    if (!isValid) {
-        return (jsxs("div", { className: cn("chart-container flex flex-col items-center justify-center p-6 border border-border rounded-lg text-2xl", className), role: "alert", "aria-live": "polite", ...props, children: [jsxs("div", { className: "flex flex-col items-center gap-4 mb-1", children: [jsx(ExclamationTriangleIcon, { className: "size-6 text-[var(--color-danger)]" }), jsx("div", { className: "text-base font-semibold text-[var(--color-text-secondary)]", children: "Invalid Chart Data" })] }), jsx("p", { className: "text-base text-[var(--color-text-secondary)]/70 mb-2", children: ((_b = validation.errors[0]) === null || _b === void 0 ? void 0 : _b.message) ||
-                        "Unable to render chart due to data validation errors" }), process.env.NODE_ENV === "development" &&
-                    validation.errors.length > 1 && (jsxs("details", { className: "text-sm text-warning-500", children: [jsxs("summary", { className: "cursor-pointer", children: ["Show all errors (", validation.errors.length, ")"] }), jsx("ul", { className: "mt-2 text-left", children: validation.errors.map((error, index) => (jsxs("li", { children: ["\u2022 ", error.message] }, index))) })] }))] }));
-    }
-    // Early return for empty data
-    if (!sanitizedData || sanitizedData.length === 0) {
-        return (jsx("div", { className: cn("chart-container flex items-center justify-center text-[var(--color-text-muted)]", className), role: "img", "aria-label": "Empty bar chart", ...props, children: jsx("span", { children: "No data available" }) }));
-    }
     // Simple color functions based on direct CSS variables (following guidelines)
     const getSeriesFillColor = (index, key) => {
         var _a, _b, _c;
@@ -134,6 +127,15 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
                 : defaultColors;
         return palette[index % palette.length];
     };
+    const resolvedLegendPosition = resolveLegendPosition(legend, config);
+    const legendItems = Object.keys(config).map((key, index) => {
+        var _a, _b;
+        return ({
+            key,
+            label: (_b = (_a = config[key]) === null || _a === void 0 ? void 0 : _a.label) !== null && _b !== void 0 ? _b : key,
+            color: getSeriesFillColor(index, key),
+        });
+    });
     const containerRef = useRef(null);
     // Bars must not mount before the real container size is known (cold-load bug:
     // motion captures geometry in the 600×400 fallback space, so the entrance
@@ -168,19 +170,17 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
     const innerHeight = Math.max(0, dimensions.height - margin.top - margin.bottom);
     // Get all data keys from config
     const dataKeys = useMemo(() => Object.keys(config || {}), [config]);
-    // Animation timing constant
-    const BAR_STAGGER = 0.05;
-    // Calculate safe scale range
+    // Calculate safe scale range. `safeMath`/`safeScale` tolerate empty/invalid
+    // data by design (they return neutral fallbacks, never throw), so it's safe
+    // to compute this — and every hook below it — unconditionally, regardless of
+    // whether `isValid`/`hasValidData` end up true. The actual branch on those
+    // flags happens once, after all hooks, right before the JSX return.
     const scaleRange = safeScale.calculateRange({
         minValue: propMinValue,
         maxValue: propMaxValue,
         includeZero: true,
     });
     const { min: minValue, max: maxValue, hasValidData } = scaleRange;
-    // If no valid data, show empty state
-    if (!hasValidData) {
-        return (jsx("div", { className: cn("chart-container flex items-center justify-center text-neutral-500", className), role: "img", "aria-label": "Empty bar chart - no valid data", ...props, children: jsx("span", { children: "No valid numeric data available" }) }));
-    }
     // Safe bar width calculations
     const totalCategoryGap = Math.max(0, (sanitizedData.length - 1) * categoryGap);
     const availableWidth = Math.max(0, innerWidth - totalCategoryGap);
@@ -289,9 +289,13 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
         const fillColor = getSeriesFillColor(keyIndex, key);
         const isHovered = hoveredCategory === index;
         const isAnyBarHovered = hoveredCategory !== null;
-        const shouldReduceOpacity = isAnyBarHovered && !isHovered;
         const isFocused = isKeyboardMode && focusedElementIndex === index;
-        const isEmphasized = isHovered || isFocused;
+        const { isEmphasized, shouldReduceOpacity } = deriveBarEmphasis({
+            isHovered,
+            isFocused,
+            isAnyBarHovered,
+            isGradientVariant,
+        });
         // Handle null bars - either skip or show placeholder
         if (isNull) {
             if (!showPlaceholderBars) {
@@ -322,18 +326,13 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
                 placeholderY = margin.top + innerHeight - placeholderHeight;
             }
             const pathD = createRoundedTopBarPath(barX, placeholderY, individualBarWidth, placeholderHeight, resolvedBarRadius);
-            const delay = (index * dataKeys.length + keyIndex) * BAR_STAGGER;
+            const delay = (index * dataKeys.length + keyIndex) * BAR_GROUP_STAGGER;
             return (jsx(motion.path, { d: pathD, initial: shouldAnimate && showAnimation && !shouldReduceMotion
                     ? { scaleY: 0, opacity: 0 }
                     : { scaleY: 1, opacity: 1 }, animate: {
                     scaleY: 1,
                     opacity: 1,
-                }, transition: {
-                    type: "spring",
-                    stiffness: 100,
-                    damping: 20,
-                    delay,
-                }, className: "transition-opacity duration-200", style: {
+                }, transition: { ...BAR_SPRING, delay }, className: "transition-opacity duration-200", style: {
                     originY: 1,
                     transformOrigin: "bottom",
                     fill: `url(#${hatchPatternId})`,
@@ -347,72 +346,44 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
         const pathD = isNegative
             ? createRoundedBottomBarPath(barX, barY, individualBarWidth, barHeight, resolvedBarRadius)
             : createRoundedTopBarPath(barX, barY, individualBarWidth, barHeight, resolvedBarRadius);
-        const delay = (index * dataKeys.length + keyIndex) * BAR_STAGGER;
+        const delay = (index * dataKeys.length + keyIndex) * BAR_GROUP_STAGGER;
         const gradientFill = `url(#${getBarGradientId(keyIndex)})`;
         const shadowFilter = `url(#${getBarShadowId(keyIndex)})`;
         const ringFilter = `url(#${getBarRingId(keyIndex)})`;
         const commonInitial = shouldAnimate && showAnimation && !shouldReduceMotion
             ? { scaleY: 0, opacity: 0 }
             : { scaleY: 1, opacity: 1 };
-        const commonTransition = {
-            type: "spring",
-            stiffness: 100,
-            damping: 20,
-            delay,
-            // Opacity carries both the mount fade-in and the hover dim. On mount it
-            // must wait out the same stagger delay as scaleY — a visible bar at
-            // scaleY≈0 renders as a glowing stub straddling the x-axis. After mount
-            // (hasAnimated), hover dims must respond with no delay. Motion re-reads
-            // this only when the opacity target changes, so the switch is safe.
-            opacity: {
-                type: "tween",
-                duration: 0.25,
-                ease: "easeOut",
-                delay: hasAnimated ? 0 : delay,
-            },
-        };
-        return (jsxs(React__default.Fragment, { children: [jsx(AnimatePresence, { children: isGradientVariant && isEmphasized && (jsx(motion.path, { d: pathD, initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: {
-                            opacity: {
-                                duration: 0.45,
-                                ease: "easeOut",
-                            },
-                        }, fill: "none", stroke: fillColor, strokeWidth: Math.min(14, Math.max(8, individualBarWidth * 0.08)), strokeOpacity: 0.24, strokeLinejoin: "round", vectorEffect: "non-scaling-stroke", filter: ringFilter, style: {
-                            pointerEvents: "none",
-                        } })) }), jsx(motion.path, { d: pathD, initial: commonInitial, animate: {
+        // Spring grow + delayed mount-fade / instant hover-dim opacity. The opacity
+        // contract (mount fade waits out the stagger so a scaleY≈0 bar isn't a
+        // glowing stub; hover dims respond instantly once `hasAnimated`) lives in
+        // the shared helper.
+        const commonTransition = barEntranceTransition(delay, hasAnimated);
+        return (jsxs(React__default.Fragment, { children: [jsx(BarGlowRing, { show: isEmphasized, pathD: pathD, color: fillColor, barWidth: individualBarWidth, filter: ringFilter }), jsx(motion.path, { d: pathD, initial: commonInitial, animate: {
                         scaleY: 1,
                         // Hover dim lives in `animate`, not `style`: motion.path freezes
                         // plain style values at mount and ignores re-render changes
-                        opacity: shouldReduceOpacity ? (isGradientVariant ? 0.42 : 0.9) : 1,
+                        opacity: barDimOpacity(shouldReduceOpacity, isGradientVariant),
                     }, transition: commonTransition, className: cn(isGradientVariant
                         ? "transition-all duration-300 ease-out"
                         : "transition-colors duration-200", !isNull && "cursor-pointer", isFocused && "stroke-2"), style: {
                         originY: isNegative ? 0 : 1,
                         transformOrigin: isNegative ? "top" : "bottom",
-                        fill: isGradientVariant
-                            ? gradientFill
-                            : isNull
-                                ? "var(--color-surface-sunken)"
-                                : shouldReduceOpacity
-                                    ? "var(--color-surface-sunken)"
-                                    : fillColor,
+                        fill: barFill({
+                            isGradientVariant,
+                            gradientFill,
+                            isNull,
+                            shouldReduceOpacity,
+                            fillColor,
+                        }),
                         // Element opacity applies post-filter, so the animated hover dim
                         // fades the shadow along with the bar — no need to toggle it here
                         filter: isGradientVariant ? shadowFilter : undefined,
-                        stroke: isFocused
-                            ? "var(--color-primary)"
-                            : isGradientVariant && isEmphasized
-                                ? fillColor
-                                : isGradientVariant
-                                    ? "rgba(255,255,255,0.24)"
-                                    : "none",
-                        strokeWidth: isFocused
-                            ? 3
-                            : isGradientVariant && isEmphasized
-                                ? 2
-                                : isGradientVariant
-                                    ? 1
-                                    : undefined,
-                        strokeOpacity: isGradientVariant && isEmphasized ? 0.78 : 1,
+                        ...barStrokeStyle({
+                            isFocused,
+                            isEmphasized,
+                            isGradientVariant,
+                            fillColor,
+                        }),
                         strokeLinejoin: "round",
                         vectorEffect: "non-scaling-stroke",
                     }, onMouseEnter: !isNull
@@ -471,54 +442,73 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
                         }
                         : undefined })] }, keyIndex));
     };
-    return (jsx(ChartErrorBoundary, { className: className, showErrorDetails: process.env.NODE_ENV === "development", children: jsxs("div", { ref: containerRef, className: cn("chart-container w-full h-full", darkMode && "dark", className), style: {
+    // --- Every hook above this line runs unconditionally, every render, in the
+    // same order. Only NOW — after the last hook — do we branch on validity, so
+    // a chart going from populated → empty/invalid data (a common loading-state
+    // transition) never changes its hook count mid-lifetime. See react.dev's
+    // Rules of Hooks: "move it before the return."
+    // Invalid data: show an error message
+    if (!isValid) {
+        return (jsxs("div", { className: cn("chart-container flex flex-col items-center justify-center p-6 border border-[var(--color-border)] rounded-lg text-2xl", className), role: "alert", "aria-live": "polite", ...props, children: [jsxs("div", { className: "flex flex-col items-center gap-4 mb-1", children: [jsx(ExclamationTriangleIcon, { className: "size-6 text-[var(--color-danger)]" }), jsx("div", { className: "text-base font-semibold text-[var(--color-text-secondary)]", children: "Invalid Chart Data" })] }), jsx("p", { className: "text-base text-[var(--color-text-secondary)]/70 mb-2", children: ((_b = validation.errors[0]) === null || _b === void 0 ? void 0 : _b.message) ||
+                        "Unable to render chart due to data validation errors" }), process.env.NODE_ENV === "development" &&
+                    validation.errors.length > 1 && (jsxs("details", { className: "text-sm text-warning-500", children: [jsxs("summary", { className: "cursor-pointer", children: ["Show all errors (", validation.errors.length, ")"] }), jsx("ul", { className: "mt-2 text-left", children: validation.errors.map((error, index) => (jsxs("li", { children: ["\u2022 ", error.message] }, index))) })] }))] }));
+    }
+    // Empty data: nothing to plot
+    if (!sanitizedData || sanitizedData.length === 0) {
+        return (jsx("div", { className: cn("chart-container flex items-center justify-center text-[var(--color-text-muted)]", className), role: "img", "aria-label": "Empty bar chart", ...props, children: jsx("span", { children: "No data available" }) }));
+    }
+    // Data present but nothing numeric to scale against
+    if (!hasValidData) {
+        return (jsx("div", { className: cn("chart-container flex items-center justify-center text-neutral-500", className), role: "img", "aria-label": "Empty bar chart - no valid data", ...props, children: jsx("span", { children: "No valid numeric data available" }) }));
+    }
+    return (jsx(ChartErrorBoundary, { className: className, showErrorDetails: process.env.NODE_ENV === "development", children: jsxs("div", { ref: containerRef, className: cn("chart-container w-full h-full flex flex-col", darkMode && "dark", className), style: {
                 width: width !== undefined ? (typeof width === "number" ? `${width}px` : width) : undefined,
                 height: height !== undefined ? (typeof height === "number" ? `${height}px` : height) : undefined,
-            }, ...chartAccessibilityProps, onMouseEnter: handleMouseInteraction, onMouseMove: handleMouseInteraction, ...props, children: [descriptionProps && jsx("div", { ...descriptionProps }), showValidationWarnings && hasWarnings && (jsxs("div", { className: "absolute top-2 left-2 right-2 z-10 p-2 bg-[var(--color-warning-50)] border border-[var(--color-warning-200)] rounded text-sm text-[var(--color-warning)] shadow-sm", children: [jsx("strong", { children: "Chart Warnings:" }), jsx("ul", { className: "mt-1", children: validation.warnings
+            }, ...chartAccessibilityProps, onMouseEnter: handleMouseInteraction, onMouseMove: handleMouseInteraction, ...props, children: [resolvedLegendPosition === "top" && (jsx(ChartLegend, { items: legendItems, className: "shrink-0 pb-2" })), descriptionProps && jsx("div", { ...descriptionProps }), showValidationWarnings && hasWarnings && (jsxs("div", { className: "absolute top-2 left-2 right-2 z-10 p-2 bg-[var(--color-warning-50)] border border-[var(--color-warning-200)] rounded text-sm text-[var(--color-warning)] shadow-sm", children: [jsx("strong", { children: "Chart Warnings:" }), jsx("ul", { className: "mt-1", children: validation.warnings
                                 .filter((warning) => !warning.message.includes("has no valid numeric values"))
-                                .map((warning, index) => (jsxs("li", { children: ["\u2022 ", warning.message] }, index))) }), validation.warnings.some((warning) => warning.message.includes("has no valid numeric values")) && (jsx("div", { className: "mt-2 pt-2 border-t border-[var(--color-warning-200)]", children: jsx("span", { className: "text-[var(--color-warning)]", children: "\u2139\uFE0F Null/undefined values are handled by using averages from other data points" }) }))] })), jsxs("svg", { width: "100%", height: "100%", viewBox: `0 0 ${dimensions.width} ${dimensions.height}`, style: { overflow: isGradientVariant ? "visible" : undefined }, children: [jsxs("defs", { children: [jsxs("pattern", { id: hatchPatternId, patternUnits: "userSpaceOnUse", width: "8", height: "8", children: [jsx("rect", { width: "8", height: "8", fill: "var(--color-neutral-50)" }), jsx("path", { d: "M-2,2 l4,-4\n                   M0,8 l8,-8\n                   M6,10 l4,-4", style: { stroke: "black", strokeWidth: 4, opacity: 0.1 } })] }), isGradientVariant &&
-                                    dataKeys.map((key, index) => {
-                                        const color = getSeriesFillColor(index, key);
-                                        return (jsxs(React__default.Fragment, { children: [jsxs("linearGradient", { id: getBarGradientId(index), x1: "0", y1: "0", x2: "0", y2: "1", children: [jsx("stop", { offset: "0%", stopColor: color, stopOpacity: "0.46" }), jsx("stop", { offset: "14%", stopColor: color, stopOpacity: "0.9" }), jsx("stop", { offset: "42%", stopColor: color, stopOpacity: "1" }), jsx("stop", { offset: "72%", stopColor: color, stopOpacity: "0.96" }), jsx("stop", { offset: "100%", stopColor: color, stopOpacity: "0.82" })] }), jsx("filter", { id: getBarShadowId(index), x: "-35%", y: "-35%", width: "170%", height: "190%", colorInterpolationFilters: "sRGB", children: jsx("feDropShadow", { dx: "0", dy: "10", stdDeviation: "8", floodColor: color, floodOpacity: "0.22" }) }), jsxs("filter", { id: getBarRingId(index), x: "-25%", y: "-25%", width: "150%", height: "165%", colorInterpolationFilters: "sRGB", children: [jsx("feDropShadow", { dx: "0", dy: "0", stdDeviation: "4", floodColor: color, floodOpacity: "0.42" }), jsx("feDropShadow", { dx: "0", dy: "10", stdDeviation: "8", floodColor: color, floodOpacity: "0.18" })] })] }, key));
-                                    })] }), jsx(HorizontalGrid, { show: showGrid, x: margin.left, y: margin.top, width: innerWidth, height: innerHeight, lineCount: 5 }), jsx(YAxis, { show: showYAxis, min: minValue, max: maxValue, x: margin.left, y: margin.top, height: innerHeight, showGrid: false, gridWidth: innerWidth, tickFormatter: (value) => {
-                                if (Math.abs(value) >= 1000)
-                                    return `${(value / 1000).toFixed(0)}k`;
-                                return value.toString();
-                            } }), minValue < 0 && maxValue > 0 && (jsx("line", { x1: margin.left, y1: margin.top + innerHeight - ((0 - minValue) / (maxValue - minValue)) * innerHeight, x2: margin.left + innerWidth, y2: margin.top + innerHeight - ((0 - minValue) / (maxValue - minValue)) * innerHeight, className: "stroke-[var(--color-text-secondary)]", strokeWidth: 1, opacity: 0.6 })), jsx("g", { className: "chart-bars", children: measured &&
-                                (() => {
-                                    // Calculate the zero baseline position (where value=0 maps to in pixel space)
-                                    const range = maxValue - minValue;
-                                    const scaledZero = range > 0
-                                        ? safeMath.scale(0, minValue, maxValue, 0, innerHeight)
-                                        : 0;
-                                    const zeroY = margin.top + innerHeight - scaledZero;
-                                    return sanitizedData.map((item, index) => {
-                                        const x = margin.left + index * (barWidth + categoryGap);
-                                        return (jsx("g", { children: dataKeys.map((key, keyIndex) => {
-                                                const rawValue = item[key];
-                                                const value = typeof rawValue === "number" && isFinite(rawValue)
-                                                    ? rawValue
-                                                    : 0;
-                                                const isNull = rawValue === null ||
-                                                    rawValue === undefined ||
-                                                    (typeof rawValue === "number" && !isFinite(rawValue));
-                                                // For null values, use the average of non-null values
-                                                const actualValue = isNull
-                                                    ? calculateAverageForKey(sanitizedData, key, safeMath.divide)
-                                                    : value;
-                                                const scaledValue = range > 0
-                                                    ? safeMath.scale(actualValue, minValue, maxValue, 0, innerHeight)
-                                                    : 0;
-                                                const barHeight = Math.abs(scaledValue - scaledZero);
-                                                const isNeg = actualValue < 0;
-                                                const barX = x + keyIndex * (individualBarWidth + gap);
-                                                // Positive: bar extends upward from zero baseline
-                                                // Negative: bar extends downward from zero baseline
-                                                const barY = isNeg ? zeroY : zeroY - barHeight;
-                                                return renderBarPath(item, index, key, keyIndex, barX, barY, barHeight, true, isNeg);
-                                            }) }, index));
-                                    });
-                                })() }), jsx(XAxis, { show: showXAxis, data: sanitizedData, x: margin.left, y: margin.top + innerHeight, width: innerWidth, categoryWidth: barWidth, categoryGap: categoryGap })] }), jsx(ChartTooltip, { tooltipRef: tooltipRef, content: tooltipData === null || tooltipData === void 0 ? void 0 : tooltipData.content, active: !!tooltipData, position: tooltipData
+                                .map((warning, index) => (jsxs("li", { children: ["\u2022 ", warning.message] }, index))) }), validation.warnings.some((warning) => warning.message.includes("has no valid numeric values")) && (jsx("div", { className: "mt-2 pt-2 border-t border-[var(--color-warning-200)]", children: jsx("span", { className: "text-[var(--color-warning)]", children: "\u2139\uFE0F Null/undefined values are handled by using averages from other data points" }) }))] })), jsx("div", { className: "relative flex-1 min-h-0", children: jsxs("svg", { width: "100%", height: "100%", viewBox: `0 0 ${dimensions.width} ${dimensions.height}`, style: { overflow: isGradientVariant ? "visible" : undefined }, children: [jsxs("defs", { children: [jsxs("pattern", { id: hatchPatternId, patternUnits: "userSpaceOnUse", width: "8", height: "8", children: [jsx("rect", { width: "8", height: "8", fill: "var(--color-neutral-50)" }), jsx("path", { d: "M-2,2 l4,-4\n                   M0,8 l8,-8\n                   M6,10 l4,-4", style: { stroke: "black", strokeWidth: 4, opacity: 0.1 } })] }), isGradientVariant &&
+                                        dataKeys.map((key, index) => {
+                                            const color = getSeriesFillColor(index, key);
+                                            return (jsx(BarSeriesDefs, { gradientId: getBarGradientId(index), shadowId: getBarShadowId(index), ringId: getBarRingId(index), color: color }, key));
+                                        })] }), jsx(HorizontalGrid, { show: showGrid, x: margin.left, y: margin.top, width: innerWidth, height: innerHeight, lineCount: 5 }), jsx(YAxis, { show: showYAxis, min: minValue, max: maxValue, x: margin.left, y: margin.top, height: innerHeight, showGrid: false, gridWidth: innerWidth, tickFormatter: (value) => {
+                                    if (Math.abs(value) >= 1000)
+                                        return `${(value / 1000).toFixed(0)}k`;
+                                    return value.toString();
+                                } }), minValue < 0 && maxValue > 0 && (jsx("line", { x1: margin.left, y1: margin.top + innerHeight - ((0 - minValue) / (maxValue - minValue)) * innerHeight, x2: margin.left + innerWidth, y2: margin.top + innerHeight - ((0 - minValue) / (maxValue - minValue)) * innerHeight, className: "stroke-[var(--color-text-secondary)]", strokeWidth: 1, opacity: 0.6 })), jsx("g", { className: "chart-bars", children: measured &&
+                                    (() => {
+                                        // Calculate the zero baseline position (where value=0 maps to in pixel space)
+                                        const range = maxValue - minValue;
+                                        const scaledZero = range > 0
+                                            ? safeMath.scale(0, minValue, maxValue, 0, innerHeight)
+                                            : 0;
+                                        const zeroY = margin.top + innerHeight - scaledZero;
+                                        return sanitizedData.map((item, index) => {
+                                            const x = margin.left + index * (barWidth + categoryGap);
+                                            return (jsx("g", { children: dataKeys.map((key, keyIndex) => {
+                                                    const rawValue = item[key];
+                                                    const value = typeof rawValue === "number" && isFinite(rawValue)
+                                                        ? rawValue
+                                                        : 0;
+                                                    const isNull = rawValue === null ||
+                                                        rawValue === undefined ||
+                                                        (typeof rawValue === "number" && !isFinite(rawValue));
+                                                    // For null values, use the average of non-null values
+                                                    const actualValue = isNull
+                                                        ? calculateAverageForKey(sanitizedData, key, safeMath.divide)
+                                                        : value;
+                                                    const scaledValue = range > 0
+                                                        ? safeMath.scale(actualValue, minValue, maxValue, 0, innerHeight)
+                                                        : 0;
+                                                    const barHeight = Math.abs(scaledValue - scaledZero);
+                                                    const isNeg = actualValue < 0;
+                                                    const barX = x + keyIndex * (individualBarWidth + gap);
+                                                    // Positive: bar extends upward from zero baseline
+                                                    // Negative: bar extends downward from zero baseline
+                                                    const barY = isNeg ? zeroY : zeroY - barHeight;
+                                                    return renderBarPath(item, index, key, keyIndex, barX, barY, barHeight, true, isNeg);
+                                                }) }, index));
+                                        });
+                                    })() }), jsx(XAxis, { show: showXAxis, data: sanitizedData, x: margin.left, y: margin.top + innerHeight, width: innerWidth, categoryWidth: barWidth, categoryGap: categoryGap })] }) }), resolvedLegendPosition === "bottom" && (jsx(ChartLegend, { items: legendItems, className: "shrink-0 pt-2" })), jsx(ChartTooltip, { tooltipRef: tooltipRef, content: tooltipData === null || tooltipData === void 0 ? void 0 : tooltipData.content, active: !!tooltipData, position: tooltipData
                         ? { x: tooltipData.x, y: tooltipData.y }
                         : { x: 0, y: 0 } }), children] }) }));
 };

package/dist/components/charts/ChartContainer.d.ts

@@ -4,5 +4,12 @@ interface ChartContextValue {
     config: ChartConfig;
 }
 export declare function useChart(): ChartContextValue;
+/**
+ * Optional variant of `useChart` — returns `null` instead of throwing when
+ * there is no ancestor `ChartContainer`. For components (e.g. Heatmap) that
+ * are documented to work standalone with directly-passed `data`/`config`
+ * props, falling back to the context only when it's actually present.
+ */
+export declare function useOptionalChart(): ChartContextValue | null;
 export declare function ChartContainer({ data, config, className, children, minHeight, width, height, ...props }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/charts/ChartContainer.js

@@ -1,15 +1,18 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { createContext, useContext } from 'react';
 import { cn } from '../../utils/cn.js';
 import { useChartTheme } from './hooks/useChartTheme.js';
 
 const ChartContext = createContext(null);
-function useChart() {
-    const context = useContext(ChartContext);
-    if (!context) {
-        throw new Error('useChart must be used within a ChartContainer');
-    }
-    return context;
+/**
+ * Optional variant of `useChart` — returns `null` instead of throwing when
+ * there is no ancestor `ChartContainer`. For components (e.g. Heatmap) that
+ * are documented to work standalone with directly-passed `data`/`config`
+ * props, falling back to the context only when it's actually present.
+ */
+function useOptionalChart() {
+    return useContext(ChartContext);
 }
 function ChartContainer({ data, config, className, children, minHeight = 200, width = '100%', height, ...props }) {
     // Provide default empty config if none provided
@@ -39,4 +42,4 @@ function ChartContainer({ data, config, className, children, minHeight = 200, wi
             !hasWidthClass && "w-full", className), style: inlineStyles, ...props, children: children }) }));
 }
 
-export { ChartContainer, useChart };
+export { ChartContainer, useOptionalChart };

package/dist/components/charts/{shared/BarRenderer → ComboChart}/BarRenderer.d.ts

@@ -3,7 +3,9 @@ import type { BarRendererProps } from "./BarRenderer.types";
 /**
  * BarRenderer Component
  *
- * Pure bar rendering component that can be used standalone or within ChartContainer.
+ * ComboChart's bar-drawing component. Standalone BarChart has its own,
+ * separate bar-rendering implementation — this one exists so a bar series can
+ * share one coordinate space with a line series inside ComboChartCanvas.
  * Handles both grouped and stacked bar layouts with Framer Motion animations.
  */
 export declare const BarRenderer: React.FC<BarRendererProps>;