@moderneinc/react-charts 1.2.0-next.ceab4e → 1.2.0-next.d03b3a

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

@@ -1,3 +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

@@ -1,31 +1,56 @@
 import { TimelineEvent } from '../timeline-chart/timeline-chart.types';
-export type ChronoMode = 'point-in-time' | 'historical';
+/**
+ * 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: {
-        totalRepositories: number;
+        /** 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.
@@ -37,22 +62,62 @@ export type ChronoChartProps = {
      * 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;
+    /** 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

@@ -1,3 +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

@@ -1,17 +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

@@ -1,9 +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.types.d.ts

@@ -68,9 +68,16 @@ export type D3StackedAreaChartProps = {
         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) */

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

@@ -25,8 +25,11 @@ type UseD3StackedAreaProps = {
         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 }: UseD3StackedAreaProps) => void;
+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

@@ -3,11 +3,12 @@ import { StageDurations } from './types';
  * Calculate stage durations from total animation duration
  *
  * Splits the total duration into proportional stages for smooth timing:
- * - 27% Seats to bar transformation
- * - 3% Pause to appreciate seat-to-bar transition
- * - 25% Bar slide to timeline + axes appear
- * - 25% Other bars grow from baseline
- * - 20% Bars morph to curved areas
+ * - 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
@@ -16,11 +17,12 @@ import { StageDurations } from './types';
  * ```ts
  * const durations = calculateStageDurations(2000);
  * // {
- * //   seatsToBar: 540,           // 27%
- * //   crossFadePause: 60,        // 3%
- * //   barSlideToTimeline: 500,   // 25%
- * //   axesAndBarsGrow: 500,      // 25%
- * //   barsToArea: 400            // 20%
+ * //   seatsToLines: 400,         // 20%
+ * //   seatsToBar: 140,           // 7%
+ * //   crossFadePause: 6,         // 0.3%
+ * //   barSlideToTimeline: 440,   // 22%
+ * //   axesAndBarsGrow: 440,      // 22%
+ * //   barsToArea: 574            // 28.7%
  * // }
  * ```
  */

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

@@ -5,18 +5,20 @@
  * timing and duration calculations.
  */
 /**
- * Animation stage durations for parliament → area morph (4 stages)
+ * Animation stage durations for parliament → area morph (5 stages)
  * Calculated as fractions of total duration for smooth timing
  */
 export type StageDurations = {
-    /** Frame 1→2: Seats directly transform to vertical bar (27% of total) */
+    /** 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 (25% of total) */
+    /** Frame 2→3: Bar slides to timeline + axes/grid appear (22% of total) */
     barSlideToTimeline: number;
-    /** Frame 3→4: Other bars grow from baseline (25% of total) */
+    /** Frame 3→4: Other bars grow from baseline (22% of total) */
     axesAndBarsGrow: number;
-    /** Frame 4→5: Bars morph to curved area (20% of total) */
+    /** 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

@@ -16,6 +16,7 @@ type UseMorphChartProps = {
     timeRange?: [number, number];
     showGrid?: boolean;
     showAxes?: boolean;
+    axisLabelColor?: string;
     formatDate?: (timestamp: number) => string;
     formatValue?: (value: number) => string;
     markers?: Array<{
@@ -37,13 +38,52 @@ type UseMorphChartProps = {
     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, formatDate, formatValue, markers: _markers, arcAngle, parliamentRadius, seatSize, animationDuration, onMorphComplete, onAnimationStateChange, onTimelineReady, onAnimationProgress, onHoveredDataChange, hoveredCategory: externalHoveredCategory, maxSeats, parliamentTimestamp, enableBrush, onTimeRangeChange, showScaleIndicator, reposPerSeat }: UseMorphChartProps) => {
+export declare const useMorphChart: ({ containerRef, data, categories, mode, width, height, margin, timeRange, showGrid, showAxes, axisLabelColor, 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/morph-chart.types.d.ts

@@ -43,10 +43,19 @@ export type MorphChartProps = {
     showGrid?: boolean;
     /** Show axes */
     showAxes?: boolean;
+    /**
+     * Color for axis labels (dates on x-axis, values on y-axis).
+     * @default undefined (inherits from SVG default, typically black)
+     */
+    axisLabelColor?: string;
     /** Enable brush selection */
     enableBrush?: boolean;
     /** Callback when time range changes */
     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;
     /** Format date for axis */
     formatDate?: (timestamp: number) => string;
     /** Format value for axis */
@@ -94,6 +103,24 @@ export type MorphChartProps = {
      * If not provided, defaults to the rightmost (most recent) timestamp.
      */
     parliamentTimestamp?: number;
+    /** Timeline events to display below the x-axis (area mode only) */
+    timelineEvents?: Array<{
+        timestamp: number;
+        eventName: string;
+        color?: string;
+    }>;
+    /** Show timeline track (default: false) */
+    showTimeline?: boolean;
+    /** Timeline track height in pixels (default: 40) */
+    timelineHeight?: number;
+    /** Space between x-axis and timeline in pixels (default: 35) */
+    timelineOffset?: number;
+    /**
+     * Color for brush selection overlay.
+     * Used for both the selection area and drag handles.
+     * @default '#69b3a2'
+     */
+    brushColor?: string;
 };
 /**
  * Seat position in parliament layout

package/dist/components/morph-chart/utils/accordion-generator.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Utility functions for generating accordion-style zig-zag lines
+ * Used in the seats-to-lines animation stage
+ */
+export interface AccordionLinePoint {
+    x: number;
+    y: number;
+    category: string;
+    categoryIndex: number;
+}
+export interface AccordionLineConfig {
+    centerX: number;
+    centerY: number;
+    radius: number;
+    startAngle: number;
+    endAngle: number;
+    amplitude: number;
+    segments: number;
+}
+/**
+ * Generate zig-zag line points for a category's accordion section
+ *
+ * @param config - Configuration for the accordion line
+ * @returns Array of points forming the zig-zag pattern
+ */
+export declare function generateAccordionLine(config: AccordionLineConfig): AccordionLinePoint[];
+/**
+ * Generate accordion lines for all categories
+ *
+ * @param categories - Array of categories with their seat counts
+ * @param parliamentCenter - Center point of the parliament
+ * @param radius - Base radius of the parliament arc
+ * @param arcAngle - Total angle of the parliament arc (in radians)
+ * @returns Map of category to accordion line points
+ */
+export declare function generateCategoryAccordionLines(categories: Array<{
+    name: string;
+    seatCount: number;
+    color: string;
+}>, parliamentCenter: {
+    x: number;
+    y: number;
+}, radius: number, arcAngle?: number): Map<string, AccordionLinePoint[]>;
+/**
+ * Generate a single continuous accordion line for all categories
+ * Creates one connected slinky that spans the entire parliament arc
+ *
+ * @param categories - Array of categories with their seat counts
+ * @param parliamentCenter - Center point of the parliament
+ * @param radius - Base radius of the parliament arc
+ * @param arcAngle - Total angle of the parliament arc (in radians)
+ * @returns Single array of accordion line points with category info
+ */
+export declare function generateContinuousAccordionLine(categories: Array<{
+    name: string;
+    seatCount: number;
+    color: string;
+}>, parliamentCenter: {
+    x: number;
+    y: number;
+}, radius: number, arcAngle?: number): AccordionLinePoint[];
+/**
+ * Create SVG path string from accordion line points
+ *
+ * @param points - Array of accordion line points
+ * @param curved - Whether to use curved lines (true) or sharp zig-zags (false)
+ * @returns SVG path string
+ */
+export declare function createAccordionPath(points: AccordionLinePoint[], curved?: boolean): string;
+/**
+ * Calculate intermediate positions for accordion collapse animation with slinky physics
+ *
+ * @param linePoints - Original accordion line points
+ * @param targetX - Target X position (vertical bar location)
+ * @param targetY - Target Y position (vertical bar location)
+ * @param progress - Animation progress (0-1)
+ * @returns Interpolated points for current progress with wave motion
+ */
+export declare function interpolateAccordionCollapse(linePoints: AccordionLinePoint[], targetX: number, targetY: number, progress: number): AccordionLinePoint[];
+/**
+ * Generate multiple depth layers for slinky 3D effect
+ *
+ * @param config - Base configuration for accordion line
+ * @param numLayers - Number of layers to create (default 3)
+ * @returns Array of accordion line configurations with depth properties
+ */
+export declare function generateLayeredAccordionLines(config: AccordionLineConfig, numLayers?: number): Array<{
+    points: AccordionLinePoint[];
+    depth: number;
+    opacity: number;
+    strokeWidth: number;
+    blur: number;
+}>;
+/**
+ * Generate a single vertical line path for collapsed state
+ *
+ * @param x - X position of the vertical line
+ * @param topY - Top Y position
+ * @param bottomY - Bottom Y position
+ * @returns SVG path string for vertical line
+ */
+export declare function createVerticalLinePath(x: number, topY: number, bottomY: number): string;

package/dist/components/morph-chart/utils/gsap-orchestrator.d.ts

@@ -1,11 +1,13 @@
 import { Selection } from 'd3-selection';
 import { MorphChartCategory } from '../morph-chart.types';
 interface AnimationDurations {
-    seatsToBar: number;
+    seatsToRings: number;
+    ringsToBar: number;
     axesReveal: number;
     barSlide: number;
     barsGrow: number;
     barsToArea: number;
+    ringsHold?: number;
 }
 interface AnimationCallbacks {
     onStageComplete?: (stage: string) => void;
@@ -34,39 +36,76 @@ export declare class GSAPOrchestrator {
     private durations;
     constructor(durations: AnimationDurations, callbacks?: AnimationCallbacks);
     /**
-     * Stage 1: Animate parliament seats collapsing into bar segments
+     * Stage 1a: Animate parliament seats transforming into slinky rings
      *
-     * Transforms the circular parliament layout into a stacked vertical bar.
-     * Each seat morphs from its position in the parliament arc into a rectangular
-     * segment of a bar, maintaining visual continuity through smooth transitions.
+     * Transforms the circular parliament layout into a slinky (spring coil) formation.
+     * This creates a whimsical intermediate state between the circular parliament
+     * and the stacked bar, making the transition more visually engaging.
      *
-     * @param seats - D3 selection of parliament seat rectangles to animate
-     * @param targetPositions - Array of target positions for each seat, where each position defines the final rectangle geometry (x, y, width, height)
+     * @param seats - D3 selection of parliament seat elements to animate
+     * @param baselineY - Y-coordinate of the chart baseline (reference for positioning)
      * @returns this - Returns the orchestrator instance for method chaining
      *
      * @remarks
      * **Visual transformation:**
-     * - Parliament seats (circular arc) → Vertical bar segments (stacked rectangles)
-     * - All seats animate simultaneously (no stagger)
-     * - Uses power2.inOut easing for smooth acceleration/deceleration
+     * - Parliament seats (circular arc) → Slinky rings (elliptical coils)
+     * - Seats morph and fade into overlapping rings
+     * - Rings positioned along the parliament arc initially
+     * - Uses perspective effects for 3D slinky appearance
      *
      * **Data preservation:**
      * - Original seat positions stored in data-orig-* attributes for potential reversal
-     * - Target positions must match seat count (indexed by array position)
+     * - Current dimensions preserved before transformation
      *
      * **Timeline integration:**
-     * - Added at 'seatsToBar' label
-     * - Duration: 30% of total animation (STAGE_DURATION_RATIOS.SEATS_TO_BAR)
+     * - Added at 'seatsToRings' label (first stage)
+     * - Duration: Set by durations.seatsToRings
      * - Triggers onStageComplete callback when starting
      *
      * @example
      * ```ts
      * const seats = svg.selectAll('.parliament-seat');
-     * const targets = calculateBarPositions(seats);
-     * orchestrator.animateSeatsToBar(seats, targets);
+     * const baselineY = height - margin.bottom;
+     * orchestrator.animateSeatsToRings(seats, baselineY);
+     * ```
+     */
+    animateSeatsToRings(seats: Selection<SVGRectElement, unknown, null, undefined>, baselineY: number): GSAPOrchestrator;
+    /**
+     * Stage 1b: Animate slinky rings collapsing into stacked bar
+     *
+     * Transforms the slinky rings created in Stage 1a into a stacked
+     * vertical bar. Rings compress and stack vertically to form rectangular
+     * segments of the final bar, maintaining visual continuity.
+     *
+     * @param seats - D3 selection of ring elements (formerly seats) to animate
+     * @param targetPositions - Array of target positions for each segment, where each position defines the final rectangle geometry (x, y, width, height)
+     * @returns this - Returns the orchestrator instance for method chaining
+     *
+     * @remarks
+     * **Visual transformation:**
+     * - Slinky rings → Stacked bar segments (rectangles)
+     * - Rings compress and flatten into bar segments
+     * - Reposition to stack vertically in correct order
+     * - All segments animate simultaneously (no stagger)
+     * - Uses power2.inOut easing for smooth acceleration/deceleration
+     *
+     * **Data requirements:**
+     * - Target positions must match ring count (indexed by array position)
+     * - Each position defines final x, y, width, height for the bar segment
+     *
+     * **Timeline integration:**
+     * - Added at 'ringsToBar' label (after seatsToRings)
+     * - Duration: Set by durations.ringsToBar
+     * - Triggers onStageComplete callback when starting
+     *
+     * @example
+     * ```ts
+     * const rings = svg.selectAll('.slinky-ring');
+     * const targets = calculateBarPositions(rings);
+     * orchestrator.animateRingsToBar(rings, targets);
      * ```
      */
-    animateSeatsToBar(seats: Selection<SVGRectElement, unknown, null, undefined>, targetPositions: Array<{
+    animateRingsToBar(seats: Selection<SVGRectElement, unknown, null, undefined>, targetPositions: Array<{
         x: number;
         y: number;
         width: number;