@flikk/ui 1.0.0-beta.1

package/dist/components/charts/hooks/useChartScales.js

@@ -0,0 +1,151 @@
+import { useMemo } from 'react';
+import { useChartValidation } from './useChartValidation.js';
+
+/**
+ * Unified hook for chart scale calculations
+ * Handles both bar and line charts with consistent logic
+ */
+function useChartScales(options) {
+    const { data, config, chartType = 'bar', stacked = false, minValue: propMinValue, maxValue: propMaxValue, includeZero = true, innerWidth = 600, categoryGap = 8, } = options;
+    // Use validation hook for data sanitization and safe calculations
+    const { validation, sanitizedData, isValid, hasWarnings, safeScale, safeMath, } = useChartValidation(data, config, {
+        autoSanitize: true,
+        logWarnings: true,
+    });
+    // Get all data keys from config
+    const dataKeys = Object.keys(config || {});
+    // Calculate Y-axis scale
+    const yScale = useMemo(() => {
+        // Start with base scale calculation
+        let scaleRange = safeScale.calculateRange({
+            minValue: propMinValue,
+            maxValue: propMaxValue,
+            includeZero,
+        });
+        // For stacked bar charts, recalculate max as sum of all values per category
+        if (chartType === 'bar' && stacked && propMaxValue === undefined && sanitizedData.length > 0) {
+            const maxStackedTotal = sanitizedData.reduce((maxTotal, item) => {
+                const currentTotal = dataKeys.reduce((sum, key) => {
+                    const value = item[key];
+                    return sum + (typeof value === "number" && isFinite(value) ? value : 0);
+                }, 0);
+                return Math.max(maxTotal, currentTotal);
+            }, 0);
+            scaleRange = safeScale.calculateRange({
+                minValue: propMinValue,
+                maxValue: maxStackedTotal,
+                includeZero,
+            });
+        }
+        // For combo charts with stacked bars, also handle stacking
+        if (chartType === 'combo' && propMaxValue === undefined && sanitizedData.length > 0) {
+            // Separate bar and line series
+            const barKeys = dataKeys.filter((key) => {
+                const seriesConfig = config[key];
+                return !(seriesConfig === null || seriesConfig === void 0 ? void 0 : seriesConfig.type) || seriesConfig.type === 'bar';
+            });
+            const lineKeys = dataKeys.filter((key) => {
+                const seriesConfig = config[key];
+                return (seriesConfig === null || seriesConfig === void 0 ? void 0 : seriesConfig.type) === 'line';
+            });
+            // Calculate max for bars (stacked if needed)
+            const maxBarValue = stacked && barKeys.length > 0
+                ? sanitizedData.reduce((maxTotal, item) => {
+                    const barTotal = barKeys.reduce((sum, key) => {
+                        const value = item[key];
+                        return sum + (typeof value === "number" && isFinite(value) ? value : 0);
+                    }, 0);
+                    return Math.max(maxTotal, barTotal);
+                }, 0)
+                : sanitizedData.reduce((max, item) => {
+                    const barMax = Math.max(...barKeys.map(key => {
+                        const value = item[key];
+                        return typeof value === "number" && isFinite(value) ? value : 0;
+                    }));
+                    return Math.max(max, barMax);
+                }, 0);
+            // Calculate max for lines
+            const maxLineValue = lineKeys.length > 0
+                ? sanitizedData.reduce((max, item) => {
+                    const lineMax = Math.max(...lineKeys.map(key => {
+                        const value = item[key];
+                        return typeof value === "number" && isFinite(value) ? value : 0;
+                    }));
+                    return Math.max(max, lineMax);
+                }, 0)
+                : 0;
+            // Use the maximum of both
+            const combinedMax = Math.max(maxBarValue, maxLineValue);
+            scaleRange = safeScale.calculateRange({
+                minValue: propMinValue,
+                maxValue: combinedMax,
+                includeZero,
+            });
+        }
+        return scaleRange;
+    }, [
+        sanitizedData,
+        dataKeys,
+        config,
+        chartType,
+        stacked,
+        propMinValue,
+        propMaxValue,
+        includeZero,
+        safeScale,
+    ]);
+    // Calculate X-axis scale
+    const xScale = useMemo(() => {
+        const dataLength = sanitizedData.length;
+        if (dataLength === 0) {
+            return {
+                categoryWidth: 0,
+                totalWidth: 0,
+                pointPosition: () => 0,
+            };
+        }
+        // For bar charts
+        if (chartType === 'bar' || chartType === 'combo') {
+            const totalCategoryGap = Math.max(0, (dataLength - 1) * categoryGap);
+            const availableWidth = Math.max(0, innerWidth - totalCategoryGap);
+            const categoryWidth = safeMath.divide(availableWidth, dataLength, 0);
+            return {
+                categoryWidth,
+                totalWidth: availableWidth + totalCategoryGap,
+                pointPosition: (index) => index * (categoryWidth + categoryGap),
+            };
+        }
+        // For line charts - points spread evenly across width
+        if (chartType === 'line') {
+            const categoryWidth = dataLength === 1 ? innerWidth : innerWidth / (dataLength - 1);
+            return {
+                categoryWidth,
+                totalWidth: innerWidth,
+                pointPosition: (index) => {
+                    if (dataLength === 1)
+                        return innerWidth / 2;
+                    return (index / (dataLength - 1)) * innerWidth;
+                },
+            };
+        }
+        // Default fallback
+        return {
+            categoryWidth: innerWidth / Math.max(1, dataLength),
+            totalWidth: innerWidth,
+            pointPosition: (index) => (index / Math.max(1, dataLength)) * innerWidth,
+        };
+    }, [sanitizedData.length, chartType, categoryGap, innerWidth, safeMath]);
+    return {
+        scales: {
+            y: yScale,
+            x: xScale,
+        },
+        sanitizedData,
+        isValid,
+        hasWarnings,
+        safeMath,
+        safeScale,
+    };
+}
+
+export { useChartScales };

package/dist/components/charts/hooks/useChartTheme.d.ts

@@ -0,0 +1,16 @@
+import { ChartConfig, ChartThemeConfig, ChartVariant, ChartThemeOverrides } from '../types/chart.types';
+interface UseChartThemeProps {
+    config: ChartConfig;
+    variant?: ChartVariant;
+    theme?: ChartThemeOverrides;
+}
+export declare function useChartTheme({ config, variant, theme }: UseChartThemeProps): {
+    getSeriesColor: (dataKey: string, index: number) => string;
+    getColorClass: (type: "grid" | "axis" | "text" | "background" | "hover" | "disabled") => string;
+    getOpacityClass: (type: "default" | "hover" | "disabled") => string;
+    getTransitionClass: (type: "default" | "hover") => string;
+    resolvedTheme: ChartThemeConfig;
+    chartColors: Record<string, string>;
+    getThemeValue: (key: string) => string;
+};
+export {};

package/dist/components/charts/hooks/useChartTheme.js

@@ -0,0 +1,105 @@
+import { useMemo } from 'react';
+import { chartTheme } from '../theme/chart.theme.js';
+
+function useChartTheme({ config, variant = 'default', theme }) {
+    const resolvedTheme = useMemo(() => {
+        var _a, _b, _c;
+        // Merge default theme with overrides
+        const mergedTheme = {
+            ...chartTheme,
+            baseStyle: {
+                ...chartTheme.baseStyle,
+                ...((theme === null || theme === void 0 ? void 0 : theme.baseStyle) || {}),
+                colors: {
+                    ...chartTheme.baseStyle.colors,
+                    ...(((_a = theme === null || theme === void 0 ? void 0 : theme.baseStyle) === null || _a === void 0 ? void 0 : _a.colors) || {}),
+                },
+                opacity: {
+                    ...chartTheme.baseStyle.opacity,
+                    ...(((_b = theme === null || theme === void 0 ? void 0 : theme.baseStyle) === null || _b === void 0 ? void 0 : _b.opacity) || {}),
+                },
+                transitions: {
+                    ...chartTheme.baseStyle.transitions,
+                    ...(((_c = theme === null || theme === void 0 ? void 0 : theme.baseStyle) === null || _c === void 0 ? void 0 : _c.transitions) || {}),
+                },
+            },
+            variants: {
+                ...chartTheme.variants,
+                ...theme === null || theme === void 0 ? void 0 : theme.variants,
+            },
+        };
+        return mergedTheme;
+    }, [theme]);
+    const getSeriesColor = useMemo(() => {
+        return (dataKey, index) => {
+            var _a, _b, _c;
+            // Add null check for config
+            if (!config || typeof config !== 'object') {
+                // Use base series colors as fallback
+                const seriesColors = resolvedTheme.baseStyle.colors.series;
+                return seriesColors[index % seriesColors.length];
+            }
+            // Priority 1: Check if config has a specific color for this dataKey
+            if ((_a = config[dataKey]) === null || _a === void 0 ? void 0 : _a.color) {
+                return config[dataKey].color;
+            }
+            // Priority 2: Use variant colors if available
+            const variantColors = (_c = (_b = resolvedTheme.variants) === null || _b === void 0 ? void 0 : _b[variant]) === null || _c === void 0 ? void 0 : _c.colors;
+            if (variantColors && variantColors.length > 0) {
+                return variantColors[index % variantColors.length];
+            }
+            // Priority 3: Use base series colors
+            const seriesColors = resolvedTheme.baseStyle.colors.series;
+            return seriesColors[index % seriesColors.length];
+        };
+    }, [config, variant, resolvedTheme]);
+    const getColorClass = useMemo(() => {
+        return (type) => {
+            return resolvedTheme.baseStyle.colors[type];
+        };
+    }, [resolvedTheme]);
+    const getOpacityClass = useMemo(() => {
+        return (type) => {
+            return resolvedTheme.baseStyle.opacity[type];
+        };
+    }, [resolvedTheme]);
+    const getTransitionClass = useMemo(() => {
+        return (type) => {
+            return resolvedTheme.baseStyle.transitions[type];
+        };
+    }, [resolvedTheme]);
+    // Generate CSS variables for dynamic colors (for cases where Tailwind classes aren't enough)
+    const chartColors = useMemo(() => {
+        const colors = {};
+        // Add null check for config
+        if (!config || typeof config !== 'object') {
+            return colors;
+        }
+        Object.entries(config).forEach(([key, value]) => {
+            if (value === null || value === void 0 ? void 0 : value.color) {
+                colors[`--color-${key}`] = value.color;
+            }
+            else if ((value === null || value === void 0 ? void 0 : value.theme) && typeof value.theme === 'string') {
+                // Handle theme-based colors
+                colors[`--color-${key}`] = value.theme;
+            }
+        });
+        return colors;
+    }, [config]);
+    const getThemeValue = (key) => {
+        return `var(--color-${key})`;
+    };
+    return {
+        // New theme utilities
+        getSeriesColor,
+        getColorClass,
+        getOpacityClass,
+        getTransitionClass,
+        resolvedTheme,
+        // Legacy utilities (for backward compatibility)
+        chartColors,
+        getThemeValue,
+    };
+}
+
+export { useChartTheme };

package/dist/components/charts/hooks/useChartValidation.d.ts

@@ -0,0 +1,74 @@
+import { SafeMath, type ChartValidationResult, type ChartValidationError } from '../utils/chart-validation';
+import { ChartDataPoint } from '../types/chart.types';
+interface UseChartValidationOptions {
+    /**
+     * Whether to sanitize data automatically
+     */
+    autoSanitize?: boolean;
+    /**
+     * Whether to log validation warnings to console
+     */
+    logWarnings?: boolean;
+    /**
+     * Custom error handler for validation errors
+     */
+    onValidationError?: (errors: ChartValidationError[]) => void;
+    /**
+     * Custom warning handler for validation warnings
+     */
+    onValidationWarning?: (warnings: ChartValidationError[]) => void;
+}
+interface UseChartValidationReturn {
+    /**
+     * Validation result
+     */
+    validation: ChartValidationResult;
+    /**
+     * Sanitized data (if autoSanitize is true)
+     */
+    sanitizedData: ChartDataPoint[];
+    /**
+     * Whether the chart data is valid and safe to render
+     */
+    isValid: boolean;
+    /**
+     * Whether there are any validation warnings
+     */
+    hasWarnings: boolean;
+    /**
+     * Safe scale calculation utilities
+     */
+    safeScale: {
+        calculateRange: (options?: {
+            minValue?: number;
+            maxValue?: number;
+            includeZero?: boolean;
+            padding?: number;
+        }) => {
+            min: number;
+            max: number;
+            hasValidData: boolean;
+        };
+    };
+    /**
+     * Safe math utilities
+     */
+    safeMath: typeof SafeMath;
+    /**
+     * Manual validation trigger
+     */
+    revalidate: () => void;
+}
+/**
+ * Hook for comprehensive chart validation and error handling
+ */
+export declare function useChartValidation(data: unknown, config: unknown, options?: UseChartValidationOptions): UseChartValidationReturn;
+/**
+ * Simplified hook for basic chart validation
+ */
+export declare function useChartDataValidation(data: unknown, config: unknown): UseChartValidationReturn;
+/**
+ * Hook for production chart validation (no console warnings)
+ */
+export declare function useChartValidationProduction(data: unknown, config: unknown, onError?: (errors: ChartValidationError[]) => void): UseChartValidationReturn;
+export {};

package/dist/components/charts/hooks/useChartValidation.js

@@ -0,0 +1,58 @@
+import { useMemo, useEffect, useCallback } from 'react';
+import { validateChart, sanitizeChartData, calculateSafeScaleRange, SafeMath } from '../utils/chart-validation.js';
+
+/**
+ * Hook for comprehensive chart validation and error handling
+ */
+function useChartValidation(data, config, options = {}) {
+    const { autoSanitize = true, logWarnings = process.env.NODE_ENV === 'development', onValidationError, onValidationWarning, } = options;
+    // Memoized validation result (pure computation only)
+    const validation = useMemo(() => {
+        return validateChart(data, config);
+    }, [data, config]);
+    // Side effects for validation errors and warnings
+    useEffect(() => {
+        if (validation.errors.length > 0 && onValidationError) {
+            onValidationError(validation.errors);
+        }
+        if (validation.warnings.length > 0) {
+            if (logWarnings) {
+                console.warn('Chart validation warnings:', validation.warnings);
+            }
+            if (onValidationWarning) {
+                onValidationWarning(validation.warnings);
+            }
+        }
+    }, [validation, onValidationError, onValidationWarning, logWarnings]);
+    // Sanitized data
+    const sanitizedData = useMemo(() => {
+        if (!autoSanitize || !Array.isArray(data)) {
+            return Array.isArray(data) ? data : [];
+        }
+        return sanitizeChartData(data);
+    }, [data, autoSanitize]);
+    // Safe scale calculation
+    const safeScale = useMemo(() => ({
+        calculateRange: (options) => {
+            const validData = autoSanitize ? sanitizedData : (Array.isArray(data) ? data : []);
+            const validConfig = (config && typeof config === 'object') ? config : {};
+            return calculateSafeScaleRange(validData, validConfig, options);
+        }
+    }), [sanitizedData, data, config, autoSanitize]);
+    // Manual revalidation trigger
+    const revalidate = useCallback(() => {
+        // This will trigger re-computation of the validation memoized value
+        // by updating a dependency (though in this case, we rely on the data/config changes)
+    }, []);
+    return {
+        validation,
+        sanitizedData,
+        isValid: validation.isValid,
+        hasWarnings: validation.warnings.length > 0,
+        safeScale,
+        safeMath: SafeMath,
+        revalidate,
+    };
+}
+
+export { useChartValidation };

package/dist/components/charts/hooks/useTooltipPosition.d.ts

@@ -0,0 +1,98 @@
+export interface TooltipPosition {
+    x: number;
+    y: number;
+}
+export interface TooltipBounds {
+    width: number;
+    height: number;
+    containerRect: DOMRect;
+}
+export interface UseTooltipPositionOptions {
+    /** Container element ref for boundary detection */
+    containerRef: React.RefObject<HTMLElement | HTMLDivElement | null>;
+    /** Padding from container edges (default: 10px) */
+    padding?: number;
+    /** Offset from cursor/element (default: 15px) */
+    offset?: number;
+    /** Whether to use mobile-optimized positioning */
+    isMobile?: boolean;
+    /** Animation configuration for smooth movement */
+    animation?: {
+        /** Animation duration in seconds (default: 0.08) */
+        duration?: number;
+        /** Animation easing (default: "easeOut") */
+        ease?: string | number[];
+        /** Whether to enable smooth animation (default: true) */
+        enabled?: boolean;
+    };
+}
+export interface TooltipData<T = any> {
+    x: number;
+    y: number;
+    content: T;
+}
+export declare function useTooltipPosition({ containerRef, padding, offset, isMobile, animation, }: UseTooltipPositionOptions): {
+    tooltipData: TooltipData<any> | null;
+    tooltipRef: import("react").RefObject<HTMLDivElement | null>;
+    showTooltip: <T>(content: T, position: TooltipPosition) => void;
+    hideTooltip: () => void;
+    updateTooltipPosition: (position: TooltipPosition) => void;
+    handleMouseEnter: <T>(event: React.MouseEvent, content: T, svgCoordinates?: {
+        x: number;
+        y: number;
+        dimensions: {
+            width: number;
+            height: number;
+        };
+    }) => void;
+    handleMouseMove: (event: React.MouseEvent, svgCoordinates?: {
+        x: number;
+        y: number;
+        dimensions: {
+            width: number;
+            height: number;
+        };
+    }) => void;
+    handleMouseLeave: () => void;
+    getMouseTooltipPosition: (event: React.MouseEvent) => TooltipPosition;
+    getSVGTooltipPosition: (event: React.MouseEvent, svgX: number, svgY: number, actualDimensions: {
+        width: number;
+        height: number;
+    }) => TooltipPosition;
+    animationConfig: {
+        animate: {
+            x: number;
+            y: number;
+            opacity: number;
+        } | {
+            opacity: number;
+            x?: undefined;
+            y?: undefined;
+        };
+        transition: {
+            duration: number | undefined;
+            ease: string | number[] | undefined;
+            type: string;
+        } | {
+            duration: number;
+            ease?: undefined;
+            type?: undefined;
+        };
+        initial: {
+            opacity: number;
+        };
+        style: {
+            position: "fixed";
+            left: number;
+            top: number;
+            transform: string;
+            willChange: string;
+        } | {
+            position?: undefined;
+            left?: undefined;
+            top?: undefined;
+            transform?: undefined;
+            willChange?: undefined;
+        };
+    };
+};