@moderneinc/react-charts 1.1.0 → 1.2.0-next.0d3f64

package/dist/components/chrono-chart/chrono-chart.component.d.ts

@@ -0,0 +1,10 @@
+import { FunctionComponent } from 'react';
+import { ChronoChartProps } from './chrono-chart.types';
+/**
+ * ChronoChart: A dual-mode time-series visualization component.
+ *
+ * Renders either a parliament diagram (point-in-time) or stacked area chart (historical)
+ * with smooth animated transitions between modes. Delegates rendering to MorphChart
+ * while managing mode logic, data transformation, and user interactions.
+ */
+export declare const ChronoChart: FunctionComponent<ChronoChartProps>;

package/dist/components/chrono-chart/chrono-chart.types.d.ts

@@ -0,0 +1,129 @@
+import { TimelineEvent } from '../timeline-chart/timeline-chart.types';
+/**
+ * Represents a data category with visual styling and optional parliament-specific mappings.
+ */
+export type ChronoCategory = {
+    /** Unique identifier for the category */
+    id: string;
+    /** Display label for the category */
+    label: string;
+    /** Color hex code (e.g., '#FF5733') */
+    color: string;
+    /** Optional dash pattern for the stroke (e.g., '5 5' for dashed lines) */
+    strokeDasharray?: string;
+    /** Parliament-specific configuration for special category rendering */
+    parliamentMapping?: {
+        /** Whether this category receives special visual treatment in parliament view */
+        isSpecialCategory: boolean;
+        /** Hatch pattern identifier for special categories */
+        hatchPattern?: string;
+    };
+};
+/**
+ * Complete dataset for the ChronoChart including time series, categories, and metadata.
+ */
+export type ChronoData = {
+    /** Array of time-series data points, each containing a timestamp and category values */
+    timeSeries: Array<{
+        /** Unix timestamp or date number */
+        timestamp: number;
+        /** Map of category IDs to their numeric values at this timestamp */
+        values: Record<string, number>;
+    }>;
+    /** Category definitions with styling and metadata */
+    categories: ChronoCategory[];
+    /** Aggregate information about the dataset */
+    metadata: {
+        /** Total count across all categories */
+        total: number;
+        /** Counts for special categories (optional) */
+        specialCounts?: {
+            notApplicable: number;
+            noLst: number;
+            unavailable: number;
+        };
+    };
+    /** Optional timeline events to display alongside the historical view */
+    events?: TimelineEvent[];
+};
+/**
+ * Props for the ChronoChart component.
+ */
+export type ChronoChartProps = {
+    /** Complete dataset to visualize */
+    data: ChronoData;
+    /**
+     * Index of the time series data point to display in point-in-time mode.
+     * - If set: Chart shows point-in-time view for data at this index
+     * - If undefined: Chart shows historical view (default)
+     * - If data.timeSeries.length === 1: Automatically shows point-in-time mode
+     *
+     * Note: Changing selectedIndex does NOT trigger animation. Animation only
+     * plays when toggling between point-in-time and historical modes.
+     */
+    selectedIndex?: number;
+    /** Chart title displayed at the top */
+    title?: string;
+    /** Chart subtitle displayed below the title */
+    subtitle?: string;
+    /** Whether to show the title/subtitle header section */
+    showHeader?: boolean;
+    /** Chart width in pixels (default: 900) */
+    width?: number;
+    /** Chart height in pixels (default: 600) */
+    height?: number;
+    /** Initial time range for the historical view [startTimestamp, endTimestamp] */
+    timeRange?: [number, number];
+    /** Callback when the time range changes (via brush or other interactions) */
+    onTimeRangeChange?: (range: [number, number]) => void;
+    /** Minimum allowed timestamp for time range selection (constrains brush selection) */
+    minAllowedTime?: number;
+    /** Maximum allowed timestamp for time range selection (constrains brush selection) */
+    maxAllowedTime?: number;
+    /** Enable brush selection for time range in historical mode */
+    enableBrush?: boolean;
+    /** Show the legend/category table */
+    showLegend?: boolean;
+    /** Enable tooltips on hover */
+    showTooltip?: boolean;
+    /** Show background grid lines */
+    showGrid?: boolean;
+    /**
+     * Color for axis labels (dates on x-axis, values on y-axis).
+     * @default undefined (inherits from SVG default, typically black)
+     */
+    axisLabelColor?: string;
+    /**
+     * Font size for axis labels in pixels.
+     * Increase this value when displaying charts at smaller sizes (e.g., in dashboards).
+     * @default 14
+     */
+    axisLabelSize?: number;
+    /** Enable animations when switching between modes */
+    enableAnimation?: boolean;
+    /** Duration of animations in milliseconds */
+    animationDuration?: number;
+    /**
+     * Disable the timeline in historical mode.
+     * By default, the timeline is always shown in historical mode, even when there are no events.
+     * Set this to true to hide the timeline.
+     * @default false
+     */
+    disableTimeline?: boolean;
+    /** Custom function to format timestamps for display */
+    formatDate?: (timestamp: number) => string;
+    /** Custom function to format numeric values for display */
+    formatValue?: (value: number) => string;
+    /** Callback when animation state changes (starting/stopping) */
+    onAnimationStateChange?: (isAnimating: boolean) => void;
+    /** Callback when the GSAP timeline is initialized */
+    onTimelineReady?: (timeline: unknown) => void;
+    /** Callback for animation progress updates */
+    onAnimationProgress?: (progress: number, stage: string) => void;
+    /**
+     * Color for brush selection overlay in historical mode.
+     * Used for both the selection area and drag handles.
+     * @default '#69b3a2'
+     */
+    brushColor?: string;
+};

package/dist/components/chrono-chart/components/category-table.component.d.ts

@@ -0,0 +1,13 @@
+import { FunctionComponent } from 'react';
+import { CategoryTableProps } from './category-table.types';
+/**
+ * CategoryTable displays a legend/data table for ChronoChart categories.
+ *
+ * The table adapts its columns based on the display mode:
+ * - Point-in-time: Shows current count and percentage for each category
+ * - Historical: Shows last value, maximum, and minimum across the time series
+ *
+ * Special categories (N/A, Data Missing, No LST) use hatch patterns instead of
+ * solid colors to distinguish them from regular data categories.
+ */
+export declare const CategoryTable: FunctionComponent<CategoryTableProps>;

package/dist/components/chrono-chart/components/category-table.types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Type definitions for the CategoryTable component.
+ *
+ * The CategoryTable displays a legend/data table showing all categories with their
+ * values, percentages, and colors. It supports both point-in-time and historical modes.
+ */
+/**
+ * Represents a single category row in the table.
+ */
+export type CategoryTableItem = {
+    /** Unique identifier for the category */
+    id: string;
+    /** Display label for the category */
+    label: string;
+    /** Current value: "#" column in point-in-time mode OR "Last" column in historical mode */
+    value: number;
+    /** Percentage of total (displayed in point-in-time mode only) */
+    percentage: number;
+    /** Color hex code for the category's visual representation */
+    color: string;
+    /** Optional tooltip text providing additional context */
+    tooltip?: string;
+    /** Maximum value across time series (historical mode only) */
+    max?: number;
+    /** Minimum value across time series (historical mode only) */
+    min?: number;
+};
+/**
+ * Props for the CategoryTable component.
+ */
+export type CategoryTableProps = {
+    /** Array of category items to display in the table */
+    categories: CategoryTableItem[];
+    /** Currently hovered category ID for highlighting, or null if none */
+    activeCategory: string | null;
+    /** Callback when user hovers over or leaves a category row */
+    onCategoryHover: (categoryId: string | null) => void;
+    /** Display mode affecting which columns are shown */
+    mode: 'point-in-time' | 'historical';
+    /** Whether the table is visible (affects opacity/display) */
+    visible?: boolean;
+};

package/dist/components/chrono-chart/utils/data-transformer.d.ts

@@ -0,0 +1,41 @@
+import { MorphChartCategory, MorphChartDataPoint } from '../../morph-chart/morph-chart.types';
+import { ChronoData } from '../chrono-chart.types';
+import { CategoryTableItem } from '../components/category-table.types';
+/**
+ * Extracts the latest values from ChronoData and formats them for display in the category table.
+ *
+ * In point-in-time mode: Returns the latest value for each category
+ * In historical mode: Also includes min/max values across the time series
+ *
+ * @param data - The complete ChronoData dataset
+ * @param mode - Display mode affecting which values are included
+ * @returns Array of formatted category items with values, percentages, and metadata
+ */
+export declare const extractLatestValues: (data: ChronoData, mode?: "point-in-time" | "historical") => CategoryTableItem[];
+/**
+ * Transforms ChronoData format to MorphChart format for visualization.
+ *
+ * This conversion is necessary because ChronoChart uses its own data structure
+ * but delegates rendering to the MorphChart component.
+ *
+ * @param data - The ChronoData to transform
+ * @returns Object containing MorphChart-compatible data points and categories
+ * @throws Error if no data points are available
+ */
+export declare const transformToMorphChart: (data: ChronoData) => {
+    data: MorphChartDataPoint[];
+    categories: MorphChartCategory[];
+};
+/**
+ * Validates the structure and integrity of ChronoData.
+ *
+ * Checks for:
+ * - Non-empty time series and categories
+ * - Required metadata fields
+ * - Proper timestamp ordering (ascending)
+ * - Category presence in data points
+ *
+ * @param data - The ChronoData to validate
+ * @throws Error with descriptive message if validation fails
+ */
+export declare const validateChronoData: (data: ChronoData) => void;

package/dist/components/d3-stacked-area-chart/d3-stacked-area-chart.component.d.ts

@@ -0,0 +1,7 @@
+import { FunctionComponent } from 'react';
+import { D3StackedAreaChartProps } from './d3-stacked-area-chart.types';
+/**
+ * D3-based stacked area chart component
+ * Built for seamless morphing with parliament chart
+ */
+export declare const D3StackedAreaChart: FunctionComponent<D3StackedAreaChartProps>;

package/dist/components/d3-stacked-area-chart/d3-stacked-area-chart.types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * D3-based stacked area chart types
+ * Built for seamless morphing with parliament chart
+ */
+export type D3StackedAreaDataPoint = {
+    timestamp: number;
+    [category: string]: number;
+};
+export type D3StackedAreaCategory = {
+    dataKey: string;
+    label: string;
+    color: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    fillOpacity?: number;
+};
+export type D3StackedAreaChartProps = {
+    /** Array of data points sorted by timestamp */
+    data: D3StackedAreaDataPoint[];
+    /** Array of category definitions */
+    categories: D3StackedAreaCategory[];
+    /** Chart title */
+    title?: string;
+    /** Chart subtitle */
+    subtitle?: string;
+    /** Show header (title and subtitle) */
+    showHeader?: boolean;
+    /** Show legend */
+    showLegend?: boolean;
+    /** Show tooltips on hover */
+    showTooltip?: boolean;
+    /** Chart dimensions */
+    width?: number;
+    height?: number;
+    /** Margins for axes */
+    margin?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Time range for x-axis */
+    timeRange?: [number, number];
+    /** Show grid lines */
+    showGrid?: boolean;
+    /** Show axes (deprecated: use showXAxis and showYAxis instead) */
+    showAxes?: boolean;
+    /** Show X-axis */
+    showXAxis?: boolean;
+    /** Show Y-axis */
+    showYAxis?: boolean;
+    /** Enable animations */
+    enableAnimation?: boolean;
+    /** Animation duration */
+    animationDuration?: number;
+    /** Format date for axis */
+    formatDate?: (timestamp: number) => string;
+    /** Format value for axis */
+    formatValue?: (value: number) => string;
+    /** Callback when time range changes */
+    onTimeRangeChange?: (range: [number, number]) => void;
+    /** Enable brush selection */
+    enableBrush?: boolean;
+    /** Zoom to selection - when true, brush clears after selection and expects chart to zoom via timeRange update */
+    zoomToSelection?: boolean;
+    /** Markers (vertical lines for events) */
+    markers?: Array<{
+        timestamp: number;
+        label?: string;
+        color?: string;
+        strokeDasharray?: string;
+    }>;
+    /** Marker visibility mode: 'hover' shows only nearest marker on hover, 'always' shows all markers */
+    markerVisibilityMode?: 'always' | 'hover';
+    /**
+     * Color for brush selection overlay.
+     * Used for both the selection area and drag handles.
+     * @default '#69b3a2'
+     */
+    brushColor?: string;
+    /** Mode for morphing animation */
+    morphMode?: 'area' | 'parliament' | 'morphing';
+    /** Parliament layout data (for morphing) */
+    parliamentData?: {
+        arcAngle: number;
+        radius: number;
+        seatPositions: Array<{
+            x: number;
+            y: number;
+            category: string;
+        }>;
+    };
+    /** Morph progress (0 = area, 1 = parliament) */
+    morphProgress?: number;
+};

package/dist/components/d3-stacked-area-chart/hooks/use-d3-stacked-area.hook.d.ts

@@ -0,0 +1,35 @@
+import { RefObject } from 'react';
+import { D3StackedAreaCategory, D3StackedAreaDataPoint } from '../d3-stacked-area-chart.types';
+type UseD3StackedAreaProps = {
+    containerRef: RefObject<SVGSVGElement>;
+    data: D3StackedAreaDataPoint[];
+    categories: D3StackedAreaCategory[];
+    width: number;
+    height: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    timeRange?: [number, number];
+    showGrid?: boolean;
+    showXAxis?: boolean;
+    showYAxis?: boolean;
+    enableBrush?: boolean;
+    zoomToSelection?: boolean;
+    onTimeRangeChange?: (range: [number, number]) => void;
+    formatDate?: (timestamp: number) => string;
+    formatValue?: (value: number) => string;
+    markers?: Array<{
+        timestamp: number;
+        label?: string;
+        color?: string;
+        strokeDasharray?: string;
+    }>;
+    markerVisibilityMode?: 'always' | 'hover';
+    onMarkerHoverChange?: (isHovering: boolean) => void;
+    brushColor?: string;
+};
+export declare const useD3StackedArea: ({ containerRef, data, categories, width, height, margin, timeRange, showGrid, showXAxis, showYAxis, enableBrush, zoomToSelection, onTimeRangeChange, formatDate, formatValue, markers, markerVisibilityMode, onMarkerHoverChange, brushColor }: UseD3StackedAreaProps) => void;
+export {};

package/dist/components/morph-chart/hooks/shared/computations.d.ts

@@ -0,0 +1,29 @@
+import { StageDurations } from './types';
+/**
+ * Calculate stage durations from total animation duration
+ *
+ * Splits the total duration into proportional stages for smooth timing:
+ * - 20% Seats transform to zig-zag lines (accordion shape)
+ * - 7% Lines collapse into vertical bar
+ * - 0.3% Pause to appreciate seat-to-bar transition
+ * - 22% Bar slide to timeline + axes appear
+ * - 22% Other bars grow from baseline
+ * - 28.7% Bars morph to curved areas
+ *
+ * @param totalDuration - Total animation duration in milliseconds
+ * @returns Object with duration for each stage in milliseconds
+ *
+ * @example
+ * ```ts
+ * const durations = calculateStageDurations(2000);
+ * // {
+ * //   seatsToLines: 400,         // 20%
+ * //   seatsToBar: 140,           // 7%
+ * //   crossFadePause: 6,         // 0.3%
+ * //   barSlideToTimeline: 440,   // 22%
+ * //   axesAndBarsGrow: 440,      // 22%
+ * //   barsToArea: 574            // 28.7%
+ * // }
+ * ```
+ */
+export declare function calculateStageDurations(totalDuration: number): StageDurations;

package/dist/components/morph-chart/hooks/shared/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared types for morph animation stages
+ *
+ * These types are used across multiple animation stages for consistent
+ * timing and duration calculations.
+ */
+/**
+ * Animation stage durations for parliament → area morph (5 stages)
+ * Calculated as fractions of total duration for smooth timing
+ */
+export type StageDurations = {
+    /** Frame 0→1: Seats transform to zig-zag lines forming accordion (20% of total) */
+    seatsToLines: number;
+    /** Frame 1→2: Lines collapse into vertical bar (15% of total) */
+    seatsToBar: number;
+    /** Pause after cross-fade to appreciate seat-to-bar transition (3% of total) */
+    crossFadePause: number;
+    /** Frame 2→3: Bar slides to timeline + axes/grid appear (22% of total) */
+    barSlideToTimeline: number;
+    /** Frame 3→4: Other bars grow from baseline (22% of total) */
+    axesAndBarsGrow: number;
+    /** Frame 4→5: Bars morph to curved area (18% of total) */
+    barsToArea: number;
+};

package/dist/components/morph-chart/hooks/use-morph-chart.hook.d.ts

@@ -0,0 +1,90 @@
+import { RefObject } from 'react';
+import { HoveredData, MorphChartCategory, MorphChartDataPoint, MorphMode } from '../morph-chart.types';
+type UseMorphChartProps = {
+    containerRef: RefObject<SVGSVGElement>;
+    data: MorphChartDataPoint[];
+    categories: MorphChartCategory[];
+    mode: 'parliament' | 'stacked-area';
+    width: number;
+    height: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    timeRange?: [number, number];
+    showGrid?: boolean;
+    showAxes?: boolean;
+    axisLabelColor?: string;
+    axisLabelSize?: number;
+    formatDate?: (timestamp: number) => string;
+    formatValue?: (value: number) => string;
+    markers?: Array<{
+        timestamp: number;
+        label?: string;
+        color?: string;
+    }>;
+    arcAngle?: number;
+    parliamentRadius?: number;
+    seatSize?: number;
+    animationDuration?: number;
+    onMorphComplete?: () => void;
+    onAnimationStateChange?: (isAnimating: boolean) => void;
+    onTimelineReady?: (timeline: gsap.core.Timeline) => void;
+    onAnimationProgress?: (progress: number, stage: string) => void;
+    onHoveredDataChange?: (data: HoveredData) => void;
+    hoveredCategory?: string | null;
+    maxSeats?: number;
+    parliamentTimestamp?: number;
+    enableBrush?: boolean;
+    onTimeRangeChange?: (range: [number, number]) => void;
+    minAllowedTime?: number;
+    maxAllowedTime?: number;
+    showScaleIndicator?: boolean;
+    reposPerSeat?: number;
+    timelineEvents?: Array<{
+        timestamp: number;
+        eventName: string;
+        color?: string;
+    }>;
+    showTimeline?: boolean;
+    timelineHeight?: number;
+    timelineOffset?: number;
+    brushColor?: string;
+};
+export declare const useMorphChart: ({ containerRef, data, categories, mode, width, height, margin, timeRange, showGrid, showAxes, axisLabelColor, axisLabelSize, formatDate, formatValue, markers, arcAngle, parliamentRadius, seatSize, animationDuration, onMorphComplete, onAnimationStateChange, onTimelineReady, onAnimationProgress, onHoveredDataChange, hoveredCategory: externalHoveredCategory, maxSeats, parliamentTimestamp, enableBrush, onTimeRangeChange, minAllowedTime: minAllowedTimeConstraint, maxAllowedTime: maxAllowedTimeConstraint, showScaleIndicator, reposPerSeat, timelineEvents, showTimeline, timelineHeight, timelineOffset, brushColor }: UseMorphChartProps) => {
+    isMorphing: boolean;
+    currentMode: MorphMode;
+    hoveredCategory: string | null;
+    scaleIndicatorOpacity: number;
+    visibleMarkers: {
+        timestamp: number;
+        label?: string;
+        color?: string;
+        x: number;
+    }[];
+    hoveredMarker: {
+        timestamp: number;
+        label?: string;
+        color?: string;
+        x: number;
+    } | null;
+    setHoveredMarker: import('react').Dispatch<import('react').SetStateAction<{
+        timestamp: number;
+        label?: string;
+        color?: string;
+        x: number;
+    } | null>>;
+    hoveredTimelineEvent: {
+        timestamp: number;
+        eventName: string;
+        x: number;
+    } | null;
+    setHoveredTimelineEvent: import('react').Dispatch<import('react').SetStateAction<{
+        timestamp: number;
+        eventName: string;
+        x: number;
+    } | null>>;
+};
+export {};

package/dist/components/morph-chart/index.d.ts

@@ -0,0 +1,2 @@
+export { MorphChart } from './morph-chart.component';
+export type { AreaLayout, AreaPoint, MorphChartCategory, MorphChartDataPoint, MorphChartProps, MorphMode, ParliamentLayout, SeatPosition } from './morph-chart.types';

package/dist/components/morph-chart/morph-chart.component.d.ts

@@ -0,0 +1,14 @@
+import { FunctionComponent } from 'react';
+import { MorphChartProps } from './morph-chart.types';
+/**
+ * MorphChart - Seamlessly morphs between parliament and stacked area visualizations
+ *
+ * This component uses D3 to create smooth transitions between a parliament chart
+ * (point-in-time view) and a stacked area chart (historical view).
+ *
+ * Key insight: The parliament chart represents the rightmost edge (latest timestamp)
+ * of the stacked area chart. During morphing:
+ * - Parliament → Stacked Area: Seats slide to the right edge, then areas expand leftward
+ * - Stacked Area → Parliament: Areas collapse to the right edge, then seats expand to parliament layout
+ */
+export declare const MorphChart: FunctionComponent<MorphChartProps>;