@flikk/ui 1.0.0-beta.1

package/dist/components/charts/utils/chart-validation.d.ts

@@ -0,0 +1,98 @@
+import { ChartDataPoint, ChartConfig } from '../types/chart.types';
+/**
+ * Validation errors that can occur in chart components
+ */
+export interface ChartValidationError {
+    type: 'data' | 'config' | 'props' | 'calculation';
+    message: string;
+    field?: string;
+}
+/**
+ * Result of chart validation
+ */
+export interface ChartValidationResult {
+    isValid: boolean;
+    errors: ChartValidationError[];
+    warnings: ChartValidationError[];
+}
+/**
+ * Safe math operations to prevent division by zero and other edge cases
+ */
+export declare class SafeMath {
+    /**
+     * Safe division that returns 0 when dividing by zero
+     */
+    static divide(numerator: number, denominator: number, fallback?: number): number;
+    /**
+     * Safe percentage calculation
+     */
+    static percentage(value: number, total: number, fallback?: number): number;
+    /**
+     * Safe Math.max that handles empty arrays
+     */
+    static max(values: number[], fallback?: number): number;
+    /**
+     * Safe Math.min that handles empty arrays
+     */
+    static min(values: number[], fallback?: number): number;
+    /**
+     * Safe scale calculation for chart positioning
+     */
+    static scale(value: number, min: number, max: number, targetMin?: number, targetMax?: number): number;
+    /**
+     * Clamp a value between min and max
+     */
+    static clamp(value: number, min: number, max: number): number;
+}
+/**
+ * Validates chart data array
+ */
+export declare function validateChartData(data: unknown): ChartValidationResult;
+/**
+ * Validates chart configuration
+ */
+export declare function validateChartConfig(config: unknown): ChartValidationResult;
+/**
+ * Validates that data and config are compatible
+ */
+export declare function validateDataConfigCompatibility(data: ChartDataPoint[], config: ChartConfig): ChartValidationResult;
+/**
+ * Sanitizes chart data by removing invalid entries and normalizing values
+ */
+export declare function sanitizeChartData(data: ChartDataPoint[]): ChartDataPoint[];
+/**
+ * Calculates safe min/max values for chart scales using nice tick boundaries.
+ */
+export declare function calculateSafeScaleRange(data: ChartDataPoint[], config: ChartConfig, options?: {
+    minValue?: number;
+    maxValue?: number;
+    includeZero?: boolean;
+    padding?: number;
+    symmetric?: boolean;
+}): {
+    min: number;
+    max: number;
+    hasValidData: boolean;
+};
+/**
+ * Heckbert's "nice numbers" algorithm.
+ * Returns a "nice" number approximately equal to x.
+ * When round=true, rounds to nearest nice number; when false, ceiling.
+ * Nice numbers are from the {1, 2, 5} × 10^n sequence.
+ */
+export declare function niceNum(x: number, round?: boolean): number;
+/**
+ * Generate uniformly-spaced "nice" tick values for a given data range.
+ * Uses Heckbert's algorithm to produce ticks from the {1,2,5}×10^n sequence.
+ * Zero naturally falls on the grid when the range spans zero — no injection needed.
+ */
+export declare function generateNiceTicks(dataMin: number, dataMax: number, desiredTickCount?: number): {
+    ticks: number[];
+    niceMin: number;
+    niceMax: number;
+    step: number;
+};
+/**
+ * Comprehensive chart validation that combines all checks
+ */
+export declare function validateChart(data: unknown, config: unknown): ChartValidationResult;

package/dist/components/charts/utils/chart-validation.js

@@ -0,0 +1,364 @@
+/**
+ * Safe math operations to prevent division by zero and other edge cases
+ */
+class SafeMath {
+    /**
+     * Safe division that returns 0 when dividing by zero
+     */
+    static divide(numerator, denominator, fallback = 0) {
+        if (denominator === 0 || !isFinite(denominator)) {
+            return fallback;
+        }
+        const result = numerator / denominator;
+        return isFinite(result) ? result : fallback;
+    }
+    /**
+     * Safe percentage calculation
+     */
+    static percentage(value, total, fallback = 0) {
+        return this.divide(value * 100, total, fallback);
+    }
+    /**
+     * Safe Math.max that handles empty arrays
+     */
+    static max(values, fallback = 0) {
+        if (!Array.isArray(values) || values.length === 0) {
+            return fallback;
+        }
+        const filtered = values.filter(v => isFinite(v));
+        return filtered.length > 0 ? Math.max(...filtered) : fallback;
+    }
+    /**
+     * Safe Math.min that handles empty arrays
+     */
+    static min(values, fallback = 0) {
+        if (!Array.isArray(values) || values.length === 0) {
+            return fallback;
+        }
+        const filtered = values.filter(v => isFinite(v));
+        return filtered.length > 0 ? Math.min(...filtered) : fallback;
+    }
+    /**
+     * Safe scale calculation for chart positioning
+     */
+    static scale(value, min, max, targetMin = 0, targetMax = 1) {
+        const range = max - min;
+        if (range === 0) {
+            return targetMin + (targetMax - targetMin) / 2; // Return middle of target range
+        }
+        const ratio = this.divide(value - min, range);
+        return targetMin + ratio * (targetMax - targetMin);
+    }
+    /**
+     * Clamp a value between min and max
+     */
+    static clamp(value, min, max) {
+        return Math.min(Math.max(value, min), max);
+    }
+}
+/**
+ * Validates chart data array
+ */
+function validateChartData(data) {
+    const errors = [];
+    const warnings = [];
+    // Check if data exists
+    if (!data) {
+        errors.push({
+            type: 'data',
+            message: 'Chart data is required but was not provided',
+            field: 'data'
+        });
+        return { isValid: false, errors, warnings };
+    }
+    // Check if data is an array
+    if (!Array.isArray(data)) {
+        errors.push({
+            type: 'data',
+            message: 'Chart data must be an array',
+            field: 'data'
+        });
+        return { isValid: false, errors, warnings };
+    }
+    // Check if data is empty
+    if (data.length === 0) {
+        warnings.push({
+            type: 'data',
+            message: 'Chart data array is empty',
+            field: 'data'
+        });
+    }
+    // Validate each data item
+    data.forEach((item, index) => {
+        if (!item || typeof item !== 'object') {
+            errors.push({
+                type: 'data',
+                message: `Data item at index ${index} must be an object`,
+                field: `data[${index}]`
+            });
+            return;
+        }
+        // Check for at least one numeric value
+        const hasNumericValue = Object.values(item).some(value => typeof value === 'number' && isFinite(value));
+        // Only warn about missing numeric values if there are no valid numeric values 
+        // in the entire dataset. Individual items with null/undefined values are 
+        // handled gracefully by chart components (e.g., using averages for bar charts)
+        if (!hasNumericValue) {
+            const allDataHasNumericValues = data.some(dataItem => dataItem && typeof dataItem === 'object' &&
+                Object.values(dataItem).some(value => typeof value === 'number' && isFinite(value)));
+            if (!allDataHasNumericValues) {
+                warnings.push({
+                    type: 'data',
+                    message: `Data item at index ${index} has no valid numeric values`,
+                    field: `data[${index}]`
+                });
+            }
+        }
+    });
+    return { isValid: errors.length === 0, errors, warnings };
+}
+/**
+ * Validates chart configuration
+ */
+function validateChartConfig(config) {
+    const errors = [];
+    const warnings = [];
+    // Check if config exists
+    if (!config) {
+        errors.push({
+            type: 'config',
+            message: 'Chart config is required but was not provided',
+            field: 'config'
+        });
+        return { isValid: false, errors, warnings };
+    }
+    // Check if config is an object
+    if (typeof config !== 'object') {
+        errors.push({
+            type: 'config',
+            message: 'Chart config must be an object',
+            field: 'config'
+        });
+        return { isValid: false, errors, warnings };
+    }
+    // Check if config has any keys
+    const configKeys = Object.keys(config);
+    if (configKeys.length === 0) {
+        warnings.push({
+            type: 'config',
+            message: 'Chart config is empty - no data series will be displayed',
+            field: 'config'
+        });
+    }
+    return { isValid: errors.length === 0, errors, warnings };
+}
+/**
+ * Validates that data and config are compatible
+ */
+function validateDataConfigCompatibility(data, config) {
+    const errors = [];
+    const warnings = [];
+    const configKeys = Object.keys(config);
+    const dataKeys = data.length > 0 ? Object.keys(data[0]) : [];
+    // Check if any config keys exist in data
+    const validKeys = configKeys.filter(key => dataKeys.includes(key) &&
+        data.some(item => typeof item[key] === 'number' && isFinite(item[key])));
+    if (validKeys.length === 0) {
+        errors.push({
+            type: 'config',
+            message: 'No config keys match valid numeric data fields',
+            field: 'config'
+        });
+    }
+    // Warn about config keys that don't exist in data
+    const missingKeys = configKeys.filter(key => !dataKeys.includes(key));
+    missingKeys.forEach(key => {
+        warnings.push({
+            type: 'config',
+            message: `Config key "${key}" not found in data`,
+            field: `config.${key}`
+        });
+    });
+    return { isValid: errors.length === 0, errors, warnings };
+}
+/**
+ * Sanitizes chart data by removing invalid entries and normalizing values
+ */
+function sanitizeChartData(data) {
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    return data
+        .filter(item => item && typeof item === 'object')
+        .map(item => {
+        const sanitized = {};
+        Object.entries(item).forEach(([key, value]) => {
+            if (typeof value === 'number') {
+                // Replace NaN and Infinity with null
+                sanitized[key] = isFinite(value) ? value : null;
+            }
+            else if (typeof value === 'string') {
+                // Keep string values (like names, categories)
+                sanitized[key] = value;
+            }
+            else if (value === null || value === undefined) {
+                // Keep explicit null/undefined
+                sanitized[key] = null;
+            }
+            // Skip other types (objects, arrays, etc.)
+        });
+        return sanitized;
+    });
+}
+/**
+ * Calculates safe min/max values for chart scales using nice tick boundaries.
+ */
+function calculateSafeScaleRange(data, config, options = {}) {
+    const { minValue: propMin, maxValue: propMax, includeZero = true, padding = 0.1, symmetric = false } = options;
+    // If both min and max are provided, use them
+    if (propMin !== undefined && propMax !== undefined) {
+        return {
+            min: propMin,
+            max: propMax,
+            hasValidData: true
+        };
+    }
+    const configKeys = Object.keys(config);
+    const allValues = [];
+    // Extract all numeric values
+    data.forEach(item => {
+        configKeys.forEach(key => {
+            const value = item[key];
+            if (typeof value === 'number' && isFinite(value)) {
+                allValues.push(value);
+            }
+        });
+    });
+    // No valid data found
+    if (allValues.length === 0) {
+        return {
+            min: propMin !== null && propMin !== void 0 ? propMin : 0,
+            max: propMax !== null && propMax !== void 0 ? propMax : 100,
+            hasValidData: false
+        };
+    }
+    let dataMin = propMin !== null && propMin !== void 0 ? propMin : SafeMath.min(allValues);
+    let dataMax = propMax !== null && propMax !== void 0 ? propMax : SafeMath.max(allValues);
+    // Include zero if requested
+    if (includeZero) {
+        dataMin = Math.min(dataMin, 0);
+        dataMax = Math.max(dataMax, 0);
+    }
+    // Add padding if min and max are the same
+    if (dataMin === dataMax) {
+        const absValue = Math.abs(dataMin);
+        const paddingValue = absValue > 0 ? absValue * padding : 1;
+        dataMin -= paddingValue;
+        dataMax += paddingValue;
+    }
+    // Make symmetric when explicitly requested
+    if (symmetric && dataMin < 0 && dataMax > 0) {
+        const absMax = Math.max(Math.abs(dataMin), Math.abs(dataMax));
+        dataMin = -absMax;
+        dataMax = absMax;
+    }
+    // Use nice tick generation to compute boundaries
+    const { niceMin, niceMax } = generateNiceTicks(dataMin, dataMax, 5);
+    return {
+        min: propMin !== null && propMin !== void 0 ? propMin : niceMin,
+        max: propMax !== null && propMax !== void 0 ? propMax : niceMax,
+        hasValidData: true
+    };
+}
+/**
+ * Heckbert's "nice numbers" algorithm.
+ * Returns a "nice" number approximately equal to x.
+ * When round=true, rounds to nearest nice number; when false, ceiling.
+ * Nice numbers are from the {1, 2, 5} × 10^n sequence.
+ */
+function niceNum(x, round = true) {
+    if (x === 0)
+        return 0;
+    const negative = x < 0;
+    const abs = Math.abs(x);
+    const exponent = Math.floor(Math.log10(abs));
+    const fraction = abs / Math.pow(10, exponent);
+    let niceFraction;
+    if (round) {
+        if (fraction < 1.5)
+            niceFraction = 1;
+        else if (fraction < 3)
+            niceFraction = 2;
+        else if (fraction < 7)
+            niceFraction = 5;
+        else
+            niceFraction = 10;
+    }
+    else {
+        if (fraction <= 1)
+            niceFraction = 1;
+        else if (fraction <= 2)
+            niceFraction = 2;
+        else if (fraction <= 5)
+            niceFraction = 5;
+        else
+            niceFraction = 10;
+    }
+    const result = niceFraction * Math.pow(10, exponent);
+    return negative ? -result : result;
+}
+/**
+ * Generate uniformly-spaced "nice" tick values for a given data range.
+ * Uses Heckbert's algorithm to produce ticks from the {1,2,5}×10^n sequence.
+ * Zero naturally falls on the grid when the range spans zero — no injection needed.
+ */
+function generateNiceTicks(dataMin, dataMax, desiredTickCount = 5) {
+    // Handle edge cases
+    if (!isFinite(dataMin) || !isFinite(dataMax)) {
+        return { ticks: [0], niceMin: 0, niceMax: 0, step: 0 };
+    }
+    if (dataMin === dataMax) {
+        // Single value: create a small range around it
+        const padding = dataMin === 0 ? 1 : Math.abs(dataMin) * 0.1;
+        return generateNiceTicks(dataMin - padding, dataMax + padding, desiredTickCount);
+    }
+    const range = niceNum(dataMax - dataMin, false);
+    const step = niceNum(range / Math.max(1, desiredTickCount - 1), true);
+    if (step === 0) {
+        return { ticks: [dataMin], niceMin: dataMin, niceMax: dataMax, step: 0 };
+    }
+    const niceMin = Math.floor(dataMin / step) * step;
+    const niceMax = Math.ceil(dataMax / step) * step;
+    const ticks = [];
+    // Use a small epsilon to handle floating point comparison
+    for (let v = niceMin; v <= niceMax + step * 0.001; v += step) {
+        // Round to remove floating point noise
+        const rounded = Math.round(v * 1e10) / 1e10;
+        ticks.push(rounded);
+    }
+    return { ticks, niceMin, niceMax, step };
+}
+/**
+ * Comprehensive chart validation that combines all checks
+ */
+function validateChart(data, config) {
+    const errors = [];
+    const warnings = [];
+    // Validate data
+    const dataValidation = validateChartData(data);
+    errors.push(...dataValidation.errors);
+    warnings.push(...dataValidation.warnings);
+    // Validate config
+    const configValidation = validateChartConfig(config);
+    errors.push(...configValidation.errors);
+    warnings.push(...configValidation.warnings);
+    // If basic validation passes, check compatibility
+    if (dataValidation.isValid && configValidation.isValid) {
+        const compatibilityValidation = validateDataConfigCompatibility(data, config);
+        errors.push(...compatibilityValidation.errors);
+        warnings.push(...compatibilityValidation.warnings);
+    }
+    return { isValid: errors.length === 0, errors, warnings };
+}
+
+export { SafeMath, calculateSafeScaleRange, generateNiceTicks, niceNum, sanitizeChartData, validateChart, validateChartConfig, validateChartData, validateDataConfigCompatibility };

package/dist/components/charts/utils/color-utils.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Color utilities for chart components
+ * Handles color extraction, manipulation, and theme integration
+ */
+/**
+ * Extracts the fill color class from a combined class string
+ * @param classString - Combined class string like "fill-primary-base stroke-primary-base"
+ * @returns The fill class or empty string
+ */
+export declare function extractFillClass(classString: string): string;
+/**
+ * Extracts the stroke color class from a combined class string
+ * @param classString - Combined class string like "fill-primary-base stroke-primary-base"
+ * @returns The stroke class or empty string
+ */
+export declare function extractStrokeClass(classString: string): string;
+/**
+ * Converts a Tailwind color class to a CSS variable
+ * @param colorClass - Tailwind color class like "fill-primary-base"
+ * @returns CSS variable string like "var(--color-primary-500)"
+ */
+export declare function colorClassToVariable(colorClass: string): string;
+/**
+ * Combines multiple Tailwind classes into a single class string
+ * @param classes - Array of class strings
+ * @returns Combined class string
+ */
+export declare function combineClasses(...classes: (string | undefined | null)[]): string;
+/**
+ * Creates a color class string for chart elements
+ * @param baseColor - Base color (e.g., "primary", "warning")
+ * @param type - Type of element ("fill", "stroke", "both")
+ * @param shade - Color shade (e.g., "base", "400", "500")
+ * @returns Tailwind class string
+ */
+export declare function createColorClass(baseColor: string, type?: 'fill' | 'stroke' | 'both', shade?: string): string;
+/**
+ * Generates a series of color classes for multiple data series
+ * @param baseColors - Array of base color names
+ * @param type - Type of element ("fill", "stroke", "both")
+ * @param shade - Color shade
+ * @returns Array of color class strings
+ */
+export declare function generateSeriesColors(baseColors: string[], type?: 'fill' | 'stroke' | 'both', shade?: string): string[];
+/**
+ * Default color palette for charts
+ */
+export declare const DEFAULT_CHART_COLORS: readonly ["primary", "warning", "success", "danger"];
+/**
+ * Extended color palette for charts with more options
+ */
+export declare const EXTENDED_CHART_COLORS: readonly ["primary", "warning", "success", "danger", "info", "purple", "pink", "indigo"];
+/**
+ * Minimal color palette for subtle charts
+ */
+export declare const MINIMAL_CHART_COLORS: readonly ["neutral", "slate", "gray", "zinc"];
+/**
+ * Generate a color palette for charts
+ */
+export declare function generateColorPalette(count: number, baseHue?: number): string[];
+/**
+ * Get contrast color (black or white) based on background color
+ */
+export declare function getContrastColor(backgroundColor: string): string;
+/**
+ * Convert HSL to hex color
+ */
+export declare function hslToHex(h: number, s: number, l: number): string;
+/**
+ * Lighten or darken a color
+ */
+export declare function adjustColorBrightness(color: string, amount: number): string;
+/**
+ * Comprehensive color mapping that handles all chart color class variations
+ * Returns CSS variable references to match actual chart element colors
+ * Only uses CSS variables that actually exist in the project
+ */
+export declare const getColorValue: (colorClass: string) => string;

package/dist/components/charts/utils/color-utils.js

@@ -0,0 +1,135 @@
+/**
+ * Color utilities for chart components
+ * Handles color extraction, manipulation, and theme integration
+ */
+/**
+ * Extracts the fill color class from a combined class string
+ * @param classString - Combined class string like "fill-primary-base stroke-primary-base"
+ * @returns The fill class or empty string
+ */
+function extractFillClass(classString) {
+    const classes = classString.split(' ');
+    const fillClass = classes.find(cls => cls.startsWith('fill-'));
+    return fillClass || '';
+}
+/**
+ * Extracts the stroke color class from a combined class string
+ * @param classString - Combined class string like "fill-primary-base stroke-primary-base"
+ * @returns The stroke class or empty string
+ */
+function extractStrokeClass(classString) {
+    const classes = classString.split(' ');
+    const strokeClass = classes.find(cls => cls.startsWith('stroke-'));
+    return strokeClass || '';
+}
+/**
+ * Converts a Tailwind color class to a CSS variable
+ * @param colorClass - Tailwind color class like "fill-primary-base"
+ * @returns CSS variable string like "var(--color-primary-500)"
+ */
+function colorClassToVariable(colorClass) {
+    // Remove the prefix (fill-, stroke-, bg-, text-, etc.)
+    const colorPart = colorClass.replace(/^(fill-|stroke-|bg-|text-|border-)/, '');
+    // Convert to CSS variable format
+    if (colorPart.includes('-base')) {
+        return `var(--color-${colorPart.replace('-base', '-500')})`;
+    }
+    return `var(--color-${colorPart})`;
+}
+/**
+ * Combines multiple Tailwind classes into a single class string
+ * @param classes - Array of class strings
+ * @returns Combined class string
+ */
+function combineClasses(...classes) {
+    return classes.filter(Boolean).join(' ');
+}
+/**
+ * Creates a color class string for chart elements
+ * @param baseColor - Base color (e.g., "primary", "warning")
+ * @param type - Type of element ("fill", "stroke", "both")
+ * @param shade - Color shade (e.g., "base", "400", "500")
+ * @returns Tailwind class string
+ */
+function createColorClass(baseColor, type = 'both', shade = 'base') {
+    const colorName = `${baseColor}-${shade}`;
+    switch (type) {
+        case 'fill':
+            return `fill-${colorName}`;
+        case 'stroke':
+            return `stroke-${colorName}`;
+        case 'both':
+            return `fill-${colorName} stroke-${colorName}`;
+        default:
+            return `fill-${colorName} stroke-${colorName}`;
+    }
+}
+/**
+ * Generates a series of color classes for multiple data series
+ * @param baseColors - Array of base color names
+ * @param type - Type of element ("fill", "stroke", "both")
+ * @param shade - Color shade
+ * @returns Array of color class strings
+ */
+function generateSeriesColors(baseColors, type = 'both', shade = 'base') {
+    return baseColors.map(color => createColorClass(color, type, shade));
+}
+/**
+ * Default color palette for charts
+ */
+const DEFAULT_CHART_COLORS = [
+    'primary',
+    'warning',
+    'success',
+    'danger',
+];
+/**
+ * Extended color palette for charts with more options
+ */
+const EXTENDED_CHART_COLORS = [
+    'primary',
+    'warning',
+    'success',
+    'danger',
+    'info',
+    'purple',
+    'pink',
+    'indigo',
+];
+/**
+ * Minimal color palette for subtle charts
+ */
+const MINIMAL_CHART_COLORS = [
+    'neutral',
+    'slate',
+    'gray',
+    'zinc',
+];
+/**
+ * Generate a color palette for charts
+ */
+function generateColorPalette(count, baseHue = 200) {
+    const colors = [];
+    const saturation = 70;
+    const lightness = 50;
+    for (let i = 0; i < count; i++) {
+        const hue = (baseHue + (i * 360) / count) % 360;
+        colors.push(`hsl(${hue}, ${saturation}%, ${lightness}%)`);
+    }
+    return colors;
+}
+/**
+ * Get contrast color (black or white) based on background color
+ */
+function getContrastColor(backgroundColor) {
+    // Convert hex to RGB
+    const hex = backgroundColor.replace('#', '');
+    const r = parseInt(hex.substring(0, 2), 16);
+    const g = parseInt(hex.substring(2, 2), 16);
+    const b = parseInt(hex.substring(4, 2), 16);
+    // Calculate luminance
+    const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+    return luminance > 0.5 ? '#000000' : '#ffffff';
+}
+
+export { DEFAULT_CHART_COLORS, EXTENDED_CHART_COLORS, MINIMAL_CHART_COLORS, colorClassToVariable, combineClasses, createColorClass, extractFillClass, extractStrokeClass, generateColorPalette, generateSeriesColors, getContrastColor };

package/dist/components/charts/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { extractFillClass, extractStrokeClass, colorClassToVariable, combineClasses, createColorClass, generateSeriesColors, DEFAULT_CHART_COLORS, EXTENDED_CHART_COLORS, MINIMAL_CHART_COLORS, generateColorPalette, getContrastColor, } from './color-utils';
+export { SafeMath, validateChart, validateChartData, validateChartConfig, validateDataConfigCompatibility, sanitizeChartData, calculateSafeScaleRange, niceNum, generateNiceTicks, type ChartValidationError, type ChartValidationResult, } from './chart-validation';
+export { getSpringAnimation, getUseSpringConfig, getStaggerDelay, SPRING_PRESETS, CIRCULAR_CHART_ANIMATIONS, type SpringConfig, type NoAnimationConfig, type AnimationPreset, } from './animation-utils';
+export { generateLinearPath, generateStepPath, generateStepBeforePath, generateStepAfterPath, generateMonotonePath, generateCurvePath, type Point, } from './path-utils';