@moderneinc/react-charts 1.2.0 → 1.3.0-next.bc5134

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

@@ -1,5 +1,6 @@
 import { RefObject } from 'react';
 import { ChartConfig, HoveredData, ProcessedDataItem } from '../parliament-chart.types';
+import { ArcSweepDirection } from '../utils/parliament-animation';
 type UseParliamentChartProps = {
     containerRef: RefObject<HTMLDivElement>;
     processedData: ProcessedDataItem[];
@@ -12,11 +13,14 @@ type UseParliamentChartProps = {
     setActivePartyName: (name: string | null) => void;
     chartConfig: ChartConfig;
     seatSize: number;
+    shouldAnimate?: boolean;
+    animationDirection?: ArcSweepDirection;
+    onAnimationComplete?: () => void;
 };
 /**
  * Hook that manages parliament chart rendering and interactivity.
  * Generates SVG visualization with seat circles and handles hover states
  * for displaying repository statistics.
  */
-export declare const useParliamentChart: ({ containerRef, processedData, totalRepositories, arcAngle, useEnhanced, maxSeats, setHoveredData, activePartyName, setActivePartyName, chartConfig, seatSize }: UseParliamentChartProps) => void;
+export declare const useParliamentChart: ({ containerRef, processedData, totalRepositories, arcAngle, useEnhanced, maxSeats, setHoveredData, activePartyName, setActivePartyName, chartConfig, seatSize, shouldAnimate, animationDirection, onAnimationComplete }: UseParliamentChartProps) => void;
 export {};

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

@@ -1,4 +1,5 @@
 import { ParliamentChartTheme } from '../../theme/default-colors';
+import { ArcSweepDirection } from './utils/parliament-animation';
 type ParliamentDataSeries = {
     value: number;
     label: string;
@@ -12,6 +13,10 @@ export type ParliamentChartProps = {
     arcAngle?: number;
     useEnhanced?: boolean;
     theme?: ParliamentChartTheme;
+    showTable?: boolean;
+    shouldAnimate?: boolean;
+    animationDirection?: ArcSweepDirection;
+    onAnimationComplete?: () => void;
 };
 export type ProcessedDataItem = {
     id: string | number;

package/dist/components/parliament-chart/utils/parliament-animation.d.ts

@@ -0,0 +1,13 @@
+export type ArcSweepDirection = 'left-to-right' | 'right-to-left';
+/**
+ * Animates the parliament chart with an arc sweep reveal effect.
+ * Creates a clipPath that progressively reveals or collapses seats.
+ *
+ * @param svgElement - The SVG element containing the parliament chart
+ * @param arcAngle - The arc angle in degrees (e.g., 200)
+ * @param radius - The radius of the parliament arc
+ * @param direction - Direction of the sweep: 'left-to-right' (expand) or 'right-to-left' (collapse)
+ * @param duration - Animation duration in milliseconds (default: 900ms)
+ * @param onComplete - Optional callback fired when animation completes
+ */
+export declare function animateArcSweep(svgElement: SVGSVGElement, arcAngle: number, radius: number, direction?: ArcSweepDirection, duration?: number, onComplete?: () => void): void;

package/dist/components/stacked-area-with-timeline/hooks/use-stacked-area-with-timeline.hook.d.ts

@@ -0,0 +1,53 @@
+import { RefObject } from 'react';
+import { D3StackedAreaCategory } from '../../d3-stacked-area-chart/d3-stacked-area-chart.types';
+import { HoveredData, HoveredMarker, HoveredTimelineEvent, StackedAreaDataPoint, TimelineEvent } from '../stacked-area-with-timeline.types';
+type UseStackedAreaWithTimelineOptions = {
+    containerRef: RefObject<SVGSVGElement | null>;
+    data: StackedAreaDataPoint[];
+    categories: D3StackedAreaCategory[];
+    width: number;
+    height: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    timelineEvents?: TimelineEvent[];
+    showTimeline?: boolean;
+    timelineHeight?: number;
+    timelineOffset?: number;
+    timeRange?: [number, number];
+    showGrid?: boolean;
+    showAxes?: boolean;
+    axisLabelColor?: string;
+    axisLabelSize?: number;
+    enableBrush?: boolean;
+    onTimeRangeChange?: (range: [number, number]) => void;
+    minAllowedTime?: number;
+    maxAllowedTime?: number;
+    brushColor?: string;
+    formatDate?: (timestamp: number) => string;
+    formatValue?: (value: number) => string;
+    markers?: Array<{
+        timestamp: number;
+        label?: string;
+        color?: string;
+    }>;
+    onHoveredDataChange?: (data: HoveredData) => void;
+    hoveredCategory?: string | null;
+    onTimelineEventHover?: (event: HoveredTimelineEvent) => void;
+};
+type VisibleMarker = {
+    timestamp: number;
+    label?: string;
+    color?: string;
+    x: number;
+};
+type UseStackedAreaWithTimelineResult = {
+    hoveredTimelineEvent: HoveredTimelineEvent;
+    hoveredMarker: HoveredMarker;
+    visibleMarkers: VisibleMarker[];
+};
+export declare const useStackedAreaWithTimeline: ({ containerRef, data, categories, width, height, margin, timelineEvents, showTimeline, timelineHeight, timelineOffset, timeRange, showGrid, showAxes, axisLabelColor, axisLabelSize, enableBrush, onTimeRangeChange, minAllowedTime, maxAllowedTime, brushColor, formatDate, formatValue, markers, onHoveredDataChange, hoveredCategory, onTimelineEventHover }: UseStackedAreaWithTimelineOptions) => UseStackedAreaWithTimelineResult;
+export {};

package/dist/components/stacked-area-with-timeline/stacked-area-with-timeline.component.d.ts

@@ -0,0 +1,3 @@
+import { FunctionComponent } from 'react';
+import { StackedAreaWithTimelineProps } from './stacked-area-with-timeline.types';
+export declare const StackedAreaWithTimeline: FunctionComponent<StackedAreaWithTimelineProps>;

package/dist/components/stacked-area-with-timeline/stacked-area-with-timeline.types.d.ts

@@ -0,0 +1,97 @@
+import { D3StackedAreaCategory } from '../d3-stacked-area-chart/d3-stacked-area-chart.types';
+export type StackedAreaDataPoint = {
+    timestamp: number;
+    values: Record<string, number>;
+};
+export type TimelineEvent = {
+    timestamp: number;
+    eventName: string;
+    color?: string;
+};
+export type HoveredData = {
+    label: string;
+    value: number;
+    color: string;
+} | null;
+export type HoveredTimelineEvent = {
+    timestamp: number;
+    eventName: string;
+    x: number;
+} | null;
+export type HoveredMarker = {
+    timestamp: number;
+    label?: string;
+    color?: string;
+    x: number;
+} | null;
+export type StackedAreaWithTimelineProps = {
+    /** Time series data points */
+    data: StackedAreaDataPoint[];
+    /** Category definitions (colors, labels, data keys) */
+    categories: D3StackedAreaCategory[];
+    /** Timeline events to display below the chart */
+    timelineEvents?: TimelineEvent[];
+    /** Show the timeline track (default: true if timelineEvents provided) */
+    showTimeline?: boolean;
+    /** Height of the timeline track in pixels (default: 40) */
+    timelineHeight?: number;
+    /** Vertical space between chart and timeline in pixels (default: 35) */
+    timelineOffset?: number;
+    /** Chart width in pixels (default: 900) */
+    width?: number;
+    /** Chart height in pixels, not including timeline (default: 400) */
+    height?: number;
+    /** Chart margins */
+    margin?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Show grid lines (default: true) */
+    showGrid?: boolean;
+    /** Show axes (default: true) */
+    showAxes?: 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 for smaller chart displays (e.g., dashboards).
+     * @default 14
+     */
+    axisLabelSize?: number;
+    /** Custom date formatter for x-axis */
+    formatDate?: (timestamp: number) => string;
+    /** Custom value formatter for y-axis */
+    formatValue?: (value: number) => string;
+    /** Time range to display [start, end] timestamps */
+    timeRange?: [number, number];
+    /** Enable brush selection for zooming/panning */
+    enableBrush?: boolean;
+    /** Callback when time range changes via brush */
+    onTimeRangeChange?: (range: [number, number]) => void;
+    /** Minimum allowed timestamp for brush constraint */
+    minAllowedTime?: number;
+    /** Maximum allowed timestamp for brush constraint */
+    maxAllowedTime?: number;
+    /**
+     * Color for brush selection overlay.
+     * @default '#69b3a2'
+     */
+    brushColor?: string;
+    /** Event markers (vertical lines on the main chart) */
+    markers?: Array<{
+        timestamp: number;
+        label?: string;
+        color?: string;
+    }>;
+    /** Callback when a category is hovered */
+    onHoveredDataChange?: (data: HoveredData) => void;
+    /** Currently hovered category (for external highlighting control) */
+    hoveredCategory?: string | null;
+    /** Callback when a timeline event is hovered */
+    onTimelineEventHover?: (event: HoveredTimelineEvent) => void;
+};

package/dist/components/stacked-area-with-timeline/utils/render-timeline-track.d.ts

@@ -0,0 +1,46 @@
+import { ScaleTime } from 'd3-scale';
+import { Selection } from 'd3-selection';
+import { HoveredTimelineEvent, TimelineEvent } from '../stacked-area-with-timeline.types';
+type RenderTimelineTrackOptions = {
+    /** D3 SVG selection */
+    svg: Selection<SVGSVGElement, unknown, null, undefined>;
+    /** Timeline events to display */
+    events: TimelineEvent[];
+    /** D3 time scale for x-axis */
+    xScale: ScaleTime<number, number>;
+    /** Height of the main chart area (timeline renders below this) */
+    chartHeight: number;
+    /** Width of the chart area */
+    chartWidth: number;
+    /** Height of the timeline track */
+    timelineHeight: number;
+    /** Vertical offset between chart and timeline */
+    timelineOffset: number;
+    /** Optional instance ID for unique CSS classes */
+    instanceId?: string;
+    /** Callback when an event is hovered */
+    setHoveredTimelineEvent: (event: HoveredTimelineEvent) => void;
+    /** Enable brush selection on timeline */
+    enableBrush?: boolean;
+    /** Callback when time range changes via brush */
+    onTimeRangeChange?: (range: [number, number]) => void;
+    /** Minimum allowed timestamp for brush constraint */
+    minAllowedTime?: number;
+    /** Maximum allowed timestamp for brush constraint */
+    maxAllowedTime?: number;
+    /** Color for brush selection overlay */
+    brushColor?: string;
+    /** CSS selector for the main chart group (default: '.main-chart-group') */
+    mainGroupSelector?: string;
+};
+/**
+ * Renders an interactive timeline track below a chart
+ *
+ * Features:
+ * - Event markers as vertical colored lines
+ * - Hover interactions with width expansion
+ * - Optional brush selection with constraint bounds
+ * - Double-click to reset to full time range
+ */
+export declare function renderTimelineTrack({ svg, events, xScale, chartHeight, chartWidth, timelineHeight, timelineOffset, instanceId, setHoveredTimelineEvent, enableBrush, onTimeRangeChange, minAllowedTime, maxAllowedTime, brushColor, mainGroupSelector }: RenderTimelineTrackOptions): void;
+export {};

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

@@ -3,12 +3,20 @@ export type TimelineEvent = {
     date: Date;
     timestamp: number;
     eventName: string;
+    /**
+     * Optional color for the event marker.
+     * If not provided, defaults to #2F42FF (Digital Blue 500).
+     * Accepts any valid CSS color string.
+     */
+    color?: string;
     [key: string]: unknown;
 };
 export type TimelineSelection = {
     start: number | null;
     end: number | null;
 };
+export type DragHandleType = 'start' | 'end' | 'body' | null;
+type DragHandleVariant = 'arrow' | 'grip';
 export type TimelineChartSlotProps = {
     /** Props for the header container (Stack) */
     header?: StackProps;
@@ -26,6 +34,10 @@ export type TimelineChartSlotProps = {
     event?: BoxProps;
     /** Props for the selection highlight overlay (Box) */
     selection?: BoxProps;
+    /** Props for the start drag handle (Box) */
+    startHandle?: BoxProps;
+    /** Props for the end drag handle (Box) */
+    endHandle?: BoxProps;
     /** Props for the hover tooltip container (Box) */
     tooltip?: BoxProps;
     /** Props for the tooltip event name Typography component */
@@ -42,6 +54,13 @@ export type TimelineChartProps = {
     selectedRange?: TimelineSelection;
     /** Height of the timeline container in pixels (default: 32) */
     height?: number;
+    /** Margin around the timeline drawable area (for alignment with other charts) */
+    margin?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
     /** Custom date formatter */
     formatDate?: (timestamp: number) => string;
     /** Custom month/year formatter */
@@ -52,6 +71,10 @@ export type TimelineChartProps = {
     monthLabelCount?: number;
     /** Enable zoom with mouse wheel */
     enableZoom?: boolean;
+    /** Drag handle style variant (default: 'arrow') */
+    dragHandleVariant?: DragHandleVariant;
+    /** Color for drag handles (default: '#4B5563' for arrow, '#9CA3AF' for grip) */
+    dragHandleColor?: string;
     /** Show header title and instructions (default: true) */
     showHeader?: boolean;
     /** Custom title for the header */
@@ -66,6 +89,20 @@ export type TimelineChartProps = {
     onVisibleRangeChange?: (range: TimelineSelection) => void;
     /** Controlled visible range (for zoom to selection mode) */
     visibleRange?: TimelineSelection;
+    /**
+     * External time domain control [minTimestamp, maxTimestamp]
+     * Simplified alias for visibleRange that uses tuple format instead of object format.
+     * When provided, overrides automatic domain calculation and controls the visible time range.
+     * Useful for synchronizing multiple charts to show the same time range.
+     * Note: This is converted internally to visibleRange format { start, end }
+     */
+    timeRange?: [number, number] | null;
+    /**
+     * Callback when the visible time range changes
+     * Simplified alias for onVisibleRangeChange that uses tuple format [start, end].
+     * Note: This is converted internally to/from TimelineSelection format { start, end }
+     */
+    onTimeRangeChange?: (range: [number, number]) => void;
     /** Props for individual component slots */
     slotProps?: TimelineChartSlotProps;
 };
@@ -81,12 +118,14 @@ export type UseTimelineChartProps = {
 export type UseTimelineChartReturn = {
     isDragging: boolean;
     dragStart: number | null;
+    dragHandleType: DragHandleType;
     internalSelectedRange: TimelineSelection;
     internalVisibleRange: TimelineSelection;
     hoveredEvent: TimelineEvent | null;
     minDate: number;
     maxDate: number;
     timeSpan: number;
+    timelineContainerRef: React.RefObject<HTMLDivElement>;
     getPositionFromTimestamp: (timestamp: number) => number;
     getTimestampFromPosition: (x: number, containerWidth: number) => number;
     handleMouseDown: (e: React.MouseEvent<HTMLDivElement>) => void;
@@ -94,9 +133,13 @@ export type UseTimelineChartReturn = {
     handleMouseUp: () => void;
     handleWheel: (e: React.WheelEvent<HTMLDivElement>) => void;
     handleDoubleClick: () => void;
+    handleStartHandleMouseDown: (e: React.MouseEvent<HTMLDivElement>) => void;
+    handleEndHandleMouseDown: (e: React.MouseEvent<HTMLDivElement>) => void;
+    handleSelectionBodyMouseDown: (e: React.MouseEvent<HTMLDivElement>) => void;
     setHoveredEvent: (event: TimelineEvent | null) => void;
     getEventsInRange: () => TimelineEvent[];
     resetZoom: () => void;
+    showHandles: boolean;
 };
 export type TimelineSelectedEventsProps = {
     /** Array of selected events to display */
@@ -110,3 +153,4 @@ export type TimelineSelectedEventsProps = {
     /** Primary color for event items */
     primaryColor?: string;
 };
+export {};