flikkui 0.1.0-beta.11

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

@@ -0,0 +1,87 @@
+import { useChartValidation } from './useChartValidation';
+import type { ChartDataPoint, ChartConfig } from '../types/chart.types';
+export interface UseChartScalesOptions {
+    data: ChartDataPoint[];
+    config: ChartConfig;
+    /**
+     * Chart type - affects how scales are calculated
+     */
+    chartType?: 'bar' | 'line' | 'combo';
+    /**
+     * Whether bars are stacked (affects Y-axis max calculation)
+     */
+    stacked?: boolean;
+    /**
+     * User-provided minimum Y value
+     */
+    minValue?: number;
+    /**
+     * User-provided maximum Y value
+     */
+    maxValue?: number;
+    /**
+     * Whether to include zero in the Y-axis range
+     */
+    includeZero?: boolean;
+    /**
+     * Inner width for X-axis calculations
+     */
+    innerWidth?: number;
+    /**
+     * Gap between categories
+     */
+    categoryGap?: number;
+    /**
+     * Whether to use smart rounding for line charts
+     */
+    useSmartRounding?: boolean;
+}
+export interface ChartScales {
+    /**
+     * Y-axis scale
+     */
+    y: {
+        min: number;
+        max: number;
+        hasValidData: boolean;
+    };
+    /**
+     * X-axis scale info
+     */
+    x: {
+        categoryWidth: number;
+        totalWidth: number;
+        pointPosition: (index: number) => number;
+    };
+}
+export interface UseChartScalesReturn {
+    /**
+     * Calculated scales for X and Y axes
+     */
+    scales: ChartScales;
+    /**
+     * Sanitized data from validation
+     */
+    sanitizedData: ChartDataPoint[];
+    /**
+     * Whether the chart has valid data to render
+     */
+    isValid: boolean;
+    /**
+     * Validation warnings
+     */
+    hasWarnings: boolean;
+    /**
+     * Safe math utilities
+     */
+    safeMath: ReturnType<typeof useChartValidation>['safeMath'];
+    /**
+     * Safe scale utilities
+     */
+    safeScale: ReturnType<typeof useChartValidation>['safeScale'];
+}
+/**
+ * Unified hook for chart scale calculations
+ * Handles both bar and line charts with consistent logic
+ */
+export declare function useChartScales(options: UseChartScalesOptions): UseChartScalesReturn;

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/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/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;
+        };
+    };
+};

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

@@ -0,0 +1,49 @@
+export { ChartContainer } from './ChartContainer';
+export { BarChart } from './BarChart';
+export { LineChart } from './LineChart';
+export { AreaChart } from './AreaChart';
+export { DonutChart } from './DonutChart/DonutChart';
+export { MultiSegmentDonutChart } from './DonutChart/MultiSegmentDonutChart';
+export { Heatmap } from './Heatmap';
+export { FunnelChart } from './FunnelChart';
+export { ScatterPlot } from './ScatterPlot';
+export { ComboChart } from './ComboChart';
+export { ActivityRings } from './ActivityRings';
+export { ChartTooltip } from './shared/ChartTooltip';
+export { ChartLegend, ChartLegendContent } from './shared/ChartLegend';
+export { XAxis, YAxis } from './shared/ChartAxis';
+export { ChartText } from './shared/ChartText';
+export { ChartMarker } from './shared/ChartMarker';
+export { ChartCrosshair } from './shared/ChartCrosshair';
+export { HorizontalGrid } from './shared/ChartGrid';
+export { useChartTheme } from './hooks/useChartTheme';
+export { useTooltipPosition } from './hooks/useTooltipPosition';
+export { useChartAccessibility } from './hooks/useChartAccessibility';
+export { useChartValidation } from './hooks/useChartValidation';
+export { generateColorPalette, getContrastColor } from './utils/color-utils';
+export { processHeatmapData, calculateIntensity, createGridMatrix, getDefaultTooltipContent, formatAxisLabel, generateSampleData } from './Heatmap/utils/heatmapUtils';
+export type { ChartDataPoint, ChartConfig, ChartVariant, CurveType, BaseChartProps, StandardChartDisplayProps, StandardVisualProps, BarChartSpecificProps, StandardAxisConfig, ChartThemeOverrides, CHART_DEFAULTS, } from './types/chart.types';
+export type { ChartTooltipProps, ChartTooltipContentProps, } from './shared/ChartTooltip/ChartTooltip.types';
+export type { ChartLegendProps, ChartLegendContentProps, } from './shared/ChartLegend/ChartLegend.types';
+export type { BaseAxisProps, XAxisProps, YAxisProps, AxisTickProps, } from './shared/ChartAxis/ChartAxis.types';
+export type { ChartTextProps, ChartTextTheme, } from './shared/ChartText/ChartText.types';
+export type { ChartMarkerProps, ChartMarkerTheme, } from './shared/ChartMarker/ChartMarker.types';
+export type { ChartCrosshairProps, ChartCrosshairTheme, } from './shared/ChartCrosshair/ChartCrosshair.types';
+export type { HorizontalGridProps, } from './shared/ChartGrid';
+export type { BarChartProps } from './BarChart/BarChart.types';
+export type { LineChartProps } from './LineChart/LineChart.types';
+export type { AreaChartProps } from './AreaChart/AreaChart.types';
+export type { DonutChartProps } from './DonutChart/DonutChart.types';
+export type { MultiSegmentDonutChartProps, DonutSegment } from './DonutChart/MultiSegmentDonutChart.types';
+export type { HeatmapProps } from './Heatmap/Heatmap.types';
+export type { FunnelChartProps, FunnelChartDataPoint } from './FunnelChart/FunnelChart.types';
+export type { ScatterPlotProps, ScatterPlotDataPoint } from './ScatterPlot/ScatterPlot.types';
+export type { ComboChartProps, ComboChartConfig, SeriesType } from './ComboChart/ComboChart.types';
+export type { ActivityRingsProps, RingData, ActivityRingsThemeOverrides } from './ActivityRings/ActivityRings.types';
+export { chartTheme } from './theme/chart.theme';
+export { extractFillClass, extractStrokeClass, colorClassToVariable, combineClasses, createColorClass, generateSeriesColors, DEFAULT_CHART_COLORS, EXTENDED_CHART_COLORS, MINIMAL_CHART_COLORS, } from './utils/color-utils';
+export { validateChart, validateChartData, validateChartConfig, sanitizeChartData, calculateSafeScaleRange, SafeMath } from './utils/chart-validation';
+export { BAR_CHART_DEFAULTS } from './BarChart/BarChart.types';
+export { LINE_CHART_DEFAULTS } from './LineChart/LineChart.types';
+export { AREA_CHART_DEFAULTS } from './AreaChart/AreaChart.types';
+export { ChartErrorBoundary } from './shared/ChartErrorBoundary';

package/dist/components/charts/shared/BarRenderer/BarRenderer.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+import type { BarRendererProps } from "./BarRenderer.types";
+/**
+ * BarRenderer Component
+ *
+ * Pure bar rendering component that can be used standalone or within ChartContainer.
+ * Handles both grouped and stacked bar layouts with Framer Motion animations.
+ */
+export declare const BarRenderer: React.FC<BarRendererProps>;

package/dist/components/charts/shared/BarRenderer/BarRenderer.types.d.ts

@@ -0,0 +1,85 @@
+import type { ChartDataPoint, ChartConfig } from '../../types/chart.types';
+import type { ChartScales } from '../../hooks/useChartScales';
+import type { ChartDimensions, ChartMargins } from '../ChartContainer';
+export interface BarRendererProps {
+    /**
+     * Chart data
+     */
+    data: ChartDataPoint[];
+    /**
+     * Chart configuration
+     */
+    config: ChartConfig;
+    /**
+     * Calculated scales (from useChartScales or ChartContainer)
+     */
+    scales: ChartScales;
+    /**
+     * Chart dimensions
+     */
+    dimensions: ChartDimensions;
+    /**
+     * Chart margins
+     */
+    margin: ChartMargins;
+    /**
+     * Whether bars are stacked
+     */
+    stacked?: boolean;
+    /**
+     * Bar radius (rounded corners)
+     */
+    radius?: number;
+    /**
+     * Gap between bars in a group
+     */
+    gap?: number;
+    /**
+     * Gap between categories
+     */
+    categoryGap?: number;
+    /**
+     * Whether to show animation
+     */
+    showAnimation?: boolean;
+    /**
+     * Hovered category index
+     */
+    hoveredCategory?: number | null;
+    /**
+     * Set hovered category
+     */
+    onHoverCategory?: (index: number | null) => void;
+    /**
+     * Mouse enter handler for tooltip
+     */
+    onMouseEnter?: (e: React.MouseEvent, content: any, coordinates: any) => void;
+    /**
+     * Mouse move handler for tooltip
+     */
+    onMouseMove?: (e: React.MouseEvent, coordinates: any) => void;
+    /**
+     * Mouse leave handler for tooltip
+     */
+    onMouseLeave?: () => void;
+    /**
+     * Focused element index (keyboard navigation)
+     */
+    focusedElementIndex?: number;
+    /**
+     * Whether in keyboard navigation mode
+     */
+    isKeyboardMode?: boolean;
+    /**
+     * Additional CSS class name
+     */
+    className?: string;
+}
+/**
+ * Animation timing constants
+ */
+export declare const BAR_ANIMATION_TIMING: {
+    readonly STACKED_CATEGORY_DELAY: 0.25;
+    readonly STACKED_SEGMENT_STAGGER: 0.12;
+    readonly GROUPED_BAR_STAGGER: 0.05;
+};

package/dist/components/charts/shared/BarRenderer/index.d.ts

@@ -0,0 +1,3 @@
+export { BarRenderer } from './BarRenderer';
+export type { BarRendererProps } from './BarRenderer.types';
+export { BAR_ANIMATION_TIMING } from './BarRenderer.types';

package/dist/components/charts/shared/ChartAxis/ChartAxis.types.d.ts

@@ -0,0 +1,92 @@
+export interface BaseAxisProps {
+    /** Whether to show the axis */
+    show?: boolean;
+    /** Custom className for styling */
+    className?: string;
+    /** Color of the axis line and text */
+    color?: string;
+    /** Font size for axis labels */
+    fontSize?: number;
+    /** Whether to show tick marks */
+    showTicks?: boolean;
+    /** Length of tick marks */
+    tickLength?: number;
+    /** Spacing between ticks and labels */
+    tickPadding?: number;
+}
+export interface XAxisProps extends BaseAxisProps {
+    /** Data points for the x-axis */
+    data: Array<{
+        name?: string;
+        label?: string;
+        [key: string]: any;
+    }>;
+    /** X position of the axis */
+    x: number;
+    /** Y position of the axis */
+    y: number;
+    /** Width of the axis */
+    width: number;
+    /** Width of each category/bar group */
+    categoryWidth: number;
+    /** Gap between categories */
+    categoryGap?: number;
+    /** Text anchor for labels */
+    textAnchor?: 'start' | 'middle' | 'end';
+    /** Rotation angle for labels */
+    labelRotation?: number;
+    /** Custom label formatter */
+    labelFormatter?: (value: any, index: number) => string;
+    /** Maximum width for labels before truncation */
+    maxLabelWidth?: number;
+    /** Whether tick marks should align directly with the left/right edges (for line/area charts) */
+    alignWithEdge?: boolean;
+}
+export interface YAxisProps extends BaseAxisProps {
+    /** Minimum value for the y-axis */
+    min: number;
+    /** Maximum value for the y-axis */
+    max: number;
+    /** Number of ticks on the y-axis */
+    tickCount?: number;
+    /** X position of the axis */
+    x: number;
+    /** Y position of the axis */
+    y: number;
+    /** Height of the axis */
+    height: number;
+    /** Text anchor for labels */
+    textAnchor?: 'start' | 'middle' | 'end';
+    /** Custom tick formatter */
+    tickFormatter?: (value: number) => string;
+    /** Whether to show grid lines */
+    showGrid?: boolean;
+    /** Width of the chart area for grid lines */
+    gridWidth?: number;
+    /** Custom tick values */
+    ticks?: number[];
+}
+export interface AxisTickProps {
+    /** Value of the tick */
+    value: number | string;
+    /** X position */
+    x: number;
+    /** Y position */
+    y: number;
+    /** Whether to show the tick mark */
+    showTick?: boolean;
+    /** Length of the tick mark */
+    tickLength?: number;
+    /** Text anchor */
+    textAnchor?: 'start' | 'middle' | 'end';
+    /** Custom formatter */
+    formatter?: (value: any) => string;
+    /** Font size */
+    fontSize?: number;
+    /** Color */
+    color?: string;
+    /** Rotation angle */
+    rotation?: number;
+    /** Maximum width before truncation */
+    maxWidth?: number;
+}

package/dist/components/charts/shared/ChartAxis/XAxis.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { XAxisProps } from './ChartAxis.types';
+/**
+ * XAxis component for charts
+ * Renders horizontal axis with labels and optional tick marks
+ */
+export declare const XAxis: React.FC<XAxisProps>;

package/dist/components/charts/shared/ChartAxis/YAxis.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { YAxisProps } from './ChartAxis.types';
+/**
+ * YAxis component for charts
+ * Renders vertical axis with labels, optional tick marks, and grid lines
+ */
+export declare const YAxis: React.FC<YAxisProps>;

package/dist/components/charts/shared/ChartAxis/index.d.ts

@@ -0,0 +1,3 @@
+export { XAxis } from './XAxis';
+export { YAxis } from './YAxis';
+export type { BaseAxisProps, XAxisProps, YAxisProps, AxisTickProps, } from './ChartAxis.types';

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

@@ -0,0 +1,85 @@
+import React from "react";
+import { useTooltipPosition } from "../../hooks/useTooltipPosition";
+import type { ChartContainerProps, ChartDimensions, ChartMargins } from "./ChartContainer.types";
+import type { ChartScales } from "../../hooks/useChartScales";
+import type { ChartDataPoint, ChartConfig } from "../../types/chart.types";
+/**
+ * Chart context for sharing state between ChartContainer and Renderers
+ */
+export interface ChartContextValue {
+    /**
+     * Chart data
+     */
+    data: ChartDataPoint[];
+    /**
+     * Chart config
+     */
+    config: ChartConfig;
+    /**
+     * Calculated scales
+     */
+    scales: ChartScales;
+    /**
+     * Chart dimensions
+     */
+    dimensions: ChartDimensions;
+    /**
+     * Chart margins
+     */
+    margin: ChartMargins;
+    /**
+     * Inner width (width - margins)
+     */
+    innerWidth: number;
+    /**
+     * Inner height (height - margins)
+     */
+    innerHeight: number;
+    /**
+     * Hovered category index
+     */
+    hoveredCategory: number | null;
+    /**
+     * Set hovered category
+     */
+    setHoveredCategory: (index: number | null) => void;
+    /**
+     * Hovered point (for line charts)
+     */
+    hoveredPoint: {
+        index: number;
+        key: string;
+    } | null;
+    /**
+     * Set hovered point
+     */
+    setHoveredPoint: (point: {
+        index: number;
+        key: string;
+    } | null) => void;
+    /**
+     * Tooltip handlers
+     */
+    handleMouseEnter: ReturnType<typeof useTooltipPosition>['handleMouseEnter'];
+    handleMouseMove: ReturnType<typeof useTooltipPosition>['handleMouseMove'];
+    handleMouseLeave: ReturnType<typeof useTooltipPosition>['handleMouseLeave'];
+    /**
+     * Keyboard focus index
+     */
+    focusedElementIndex: number;
+    /**
+     * Whether in keyboard navigation mode
+     */
+    isKeyboardMode: boolean;
+}
+/**
+ * Hook to access chart context from renderers
+ */
+export declare const useChartContext: () => ChartContextValue;
+/**
+ * ChartContainer Component
+ *
+ * Manages SVG container, axes, grid, tooltip, dimensions, and provides
+ * context to child rendering components (BarRenderer, LineRenderer, etc.)
+ */
+export declare const ChartContainer: React.FC<ChartContainerProps>;