What changed in React Chrono from 2 to 3

What's Changed

• Cleanup: removed ladle, sonar by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/595
• Cleanup + Minor enhancements to the Timeline card + minor doc updates by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/598

Full Changelog: https://github.com/prabhuignoto/react-chrono/compare/3.3.2...3.3.3

What's Changed

• Migrate from pnpm to Bun by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/590
• Fix: Auto-select-first timeline card in horizontal mode by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/593

Full Changelog: https://github.com/prabhuignoto/react-chrono/compare/3.3.1...3.3.2

What's Changed

• fix gaps between timeline blocks when there are few timeline items by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/582
• [ImgBot] Optimize images by @imgbot[bot] in https://github.com/prabhuignoto/react-chrono/pull/581
• feat: add collapsible demo sidebar by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/583
• Docs/readme update and benchmark setup by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/584

Full Changelog: https://github.com/prabhuignoto/react-chrono/compare/3.3.0...3.3.1

Features

• Add read more/expand functionality to ContentDisplay component with overflow detection
• Enhance dynamic item updates with improved state preservation and scroll position tracking
• Add theme and line width customization for horizontal timeline
• Improve dark mode synchronization in TimelineContextProvider

Improvements

• Refactor design token system: consolidate semantic tokens, deprecate legacy imports
• Improve focus behavior in timeline component with better initial render handling
• Update CSS styles for media details expanded/minimized states
• Enhance timeline card styles and nested timeline layout
• Optimize component re-renders with memoization and useCallback

Bug Fixes

• Fix custom elements in left content (Fixes #520)
• Fix item update handling to differentiate between appends and replacements

What's Changed

• Feat/comprehensive-examples-storybook by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/563
• fix: configure vanilla-extract for Storybook production builds by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/566
• Add-storybook-link by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/567
• fix: improve focus behavior and cleanup code by @prabhuignoto in https://github.com/prabhuignoto/react-chrono/pull/569

Full Changelog: https://github.com/prabhuignoto/react-chrono/compare/3.2.1...3.2.2

• Fix: Enable scrolling during slideshow for proper timeline item centering (#559)
• Modified useTimelineItemNavigation.ts to allow scrolling to trigger regardless of slideshow state, ensuring items are properly centered when navigating during slideshow mode
• Updated visual snapshot for timeline point styling
• CI: Added Dependabot GitHub workflow configuration

🐛 Bug Fixes

Interactive Elements (#490)

Fixed links, buttons, and form inputs not working inside timeline cards. Interactive elements now function correctly without triggering card selection.

Content Alignment (#431)

Added fine-grained control over card content alignment:

content={{ alignment: { horizontal: 'center', vertical: 'center' }}}

Dynamic Loading (#135)

Fixed array mutation bug causing items to be skipped during dynamic loading. All items now load correctly.

Array.map() Pattern (#291)

Timeline now correctly updates when using Array.map() to render children dynamically.

Circular JSON (#463)

Verified hash-based comparison prevents circular structure errors with React components in content.

✨ New Features

Auto Card Height (#498)

Cards can now automatically size based on content: layout={{ cardHeight: 'auto' }}

• Enhanced keyboard navigation across all timeline modes
• Improved focus management and event handling
• Refined focus ring styling on timeline items
• Expanded test coverage and documentation

Full Changelog: https://github.com/prabhuignoto/react-chrono/compare/3.0.0...3.1.0

v3.0.0 - Major Release

🎉 A complete architectural evolution with powerful new features, improved performance, and enhanced developer experience

🏗️ Architecture & Performance

Styling System Migration

• ⚡ Migrated to Vanilla Extract CSS - Replaced styled-components with Vanilla Extract for zero-runtime CSS-in-TypeScript, resulting in significantly improved performance and type-safe styling
• 🎨 Type-Safe Design Tokens - Comprehensive token system with sprinkles utilities for consistent styling across components

Context System Redesign

• 🔄 Unified Context Provider - Consolidated multiple context providers into a single optimized TimelineContextProvider, reducing complexity and improving render performance
• 🚀 Optimized Re-renders - Smart memoization strategies with separated static config, dynamic state, and computed values
• 💡 Enhanced Developer Experience - Simpler API with useTimelineContext() hook replacing multiple context hooks

Build & Tooling Improvements

• 🛠️ Modern Build Pipeline - Updated Vite configuration with enhanced tree-shaking and bundle optimization
• 📊 Code Quality - Added Stylelint configuration, enhanced ESLint rules, and improved TypeScript strict mode compliance

✨ New Features

Grouped Configuration API

<Chrono
  layout={{ cardWidth: 450, responsive: { enabled: true } }}
  interaction={{ keyboardNavigation: true, autoScroll: true }}
  display={{ borderless: false, toolbar: { sticky: true } }}
  animation={{ slideshow: { enabled: true, duration: 4000 } }}
/>

• 📋 Logical Organization - Props grouped into 9 intuitive categories: layout, interaction, content, display, media, animation, style, accessibility, i18n
• 🔄 Backward Compatible - All v2.x props continue to work with automatic mapping to new API
• 💡 Better Autocomplete - Improved IDE support with structured prop hierarchy

Google Fonts Integration

• 🔤 Dynamic Font Loading - Seamless Google Fonts integration with automatic optimization and caching
• 🎯 Granular Control - Configure font families, weights, and styles per element (titles, subtitles, card text)
• ⚡ Performance Optimized - Intelligent font preloading and fallback strategies

Comprehensive Internationalization

• 🌍 40+ Configurable Text Elements - Complete i18n coverage across 11 categories (navigation, search, toolbar, media, accessibility, etc.)
• 📝 Template String Support - Dynamic text interpolation with variables (e.g., "Page {current} of {total}")
• 🔀 Smart Fallbacks - Intelligent default text resolution with only-override-what-you-need approach

Fullscreen Mode

• 🖥️ Cross-Browser Support - Full-screen timeline experience with vendor prefix handling for all major browsers
• ⌨️ Keyboard Shortcuts - ESC to exit, consistent behavior across all modes
• 🎯 Portal Optimization - Proper portal container management for fullscreen-aware components

Enhanced Dark Mode

• 🌙 25+ Theme Properties - Comprehensive dark mode support including button states, shadows, glows, and search highlighting
• 🎨 Automatic Color Adaptation - Intelligent contrast handling for readability
• 🔄 Runtime Theme Switching - Seamless dark/light mode transitions with onThemeChange callback

Advanced UI Controls

• 📌 Sticky Toolbar - Optional sticky positioning for toolbar with configurable placement
• 🔍 Customizable Search - Configurable search input widths and toolbar positioning
• 🎴 Borderless Card Variant - Clean, minimal card design for modern interfaces
• 📏 Text Density Control - Dynamic card remeasurement when switching between compact/detailed views

🎨 UX Improvements

Navigation & Interaction

• ⌨️ Enhanced Keyboard Navigation - Improved focus management with better visual feedback
• 🎯 Smart Popover Positioning - Context-aware popover placement with fullscreen awareness
• 🔄 Smooth Slideshow Transitions - Refined card animations and progress indicators
• 🖱️ Better Touch Support - Optimized touch targets and gesture handling for mobile devices

Visual Refinements

• 🎬 Polished Animations - Smoother card reveals and transitions with respect for prefers-reduced-motion
• 🎨 Improved Icon System - Modernized icon components with consistent sizing (16x16px standard)
• 📐 Layout Enhancements - Better responsive breakpoint behavior and continuous timeline line in vertical mode
• ✨ Text Overlay Improvements - Minimize/maximize controls for text-heavy content

Media Handling

• 📷 Optimized Image Loading - Intersection observer-based lazy loading for better performance
• 🎥 Video Player Controls - Enhanced video playback with proper state management
• 🖼️ Responsive Media Sizing - Automatic media adaptation to card dimensions

🧪 Testing & Quality

Test Infrastructure

• 👁️ Visual Regression - Comprehensive visual testing for UI consistency
• 📊 Improved Coverage - Expanded test suite with integration tests for build output and demo app

Code Quality

• ✅ TypeScript Strict Mode - Enhanced type safety with strict mode compliance across all components
• 🔍 Comprehensive Validation - Theme property validation with edge case coverage
• 📈 Performance Testing - Added performance benchmarks for large datasets

📚 Documentation & Developer Experience

Documentation

• 📖 Enhanced README - Comprehensive documentation with use cases, examples, and migration guides
• 📋 Props Reference - Complete props documentation with type definitions and examples (PROPS-REFERENCE.md)
• 🗺️ Migration Guide - Detailed v2 to v3 migration guide with code examples

Developer Tools

• 🎨 Redesigned Demo Site - Modern demo experience with full-width layouts and interactive examples
• 🔧 Development Commands - Comprehensive pnpm scripts for building, testing, and linting
• 📦 Package Management - Updated to pnpm 10.15.1 for faster installs and better dependency management

🔧 Breaking Changes

⚠️ While all v2.x props remain supported, some internal APIs have changed

• Styled Components Removal - Internal styled-components have been replaced with Vanilla Extract (no impact on public API)
• Context Structure - Internal context structure changed from multiple providers to unified provider (no impact if using public hooks)
• Node.js Requirement - Minimum Node.js version updated to 18+
• TypeScript - Enhanced type definitions may require TypeScript 4.0+ for full support

🐛 Bug Fixes

Navigation & Scrolling

• Fixed slideshow media deadlock preventing smooth transitions
• Resolved keyboard navigation issues with proper focus management
• Fixed auto-scroll behavior in slideshow mode to properly scroll cards into view
• Improved slideshow link-style "read more" button UX

Layout & Rendering

• Fixed kitchen sink page layout inconsistencies
• Resolved nested timeline rendering and icon positioning issues
• Fixed responsive breakpoint behavior for vertical alternating mode
• Corrected popover positioning issues in fullscreen mode

Theme & Styling

• Fixed dark mode text color inconsistencies across components
• Resolved CSS variable fallback issues in text overlay mode
• Fixed timeline card point colors not respecting theme overrides
• Improved contrast and readability in dark mode

Search & Focus

• Fixed search focus management issues
• Resolved search highlight color in dark mode
• Improved search "no results" state handling

🔄 Migration Guide

Seamless Upgrade Path

All existing v2.x code continues to work without changes:

// ✅ v2.x syntax still works
<Chrono
  cardWidth={400}
  disableNavOnKey={false}
  borderLessCards={true}
/>

// 🚀 v3.x grouped API (recommended)
<Chrono
  layout={{ cardWidth: 400 }}
  interaction={{ keyboardNavigation: true }}
  display={{ borderless: true }}
/>

Recommended Actions

1. ✅ Update React to 18.2+ if not already
2. ✅ Review new grouped API for cleaner code organization
3. ✅ Explore new features: Google Fonts, i18n, fullscreen mode
4. ✅ Test dark mode with new theme properties
5. ✅ Update TypeScript definitions if using custom types

📦 Dependencies

Major Updates

• ⬆️ Upgraded all packages to latest stable versions
• ⬆️ React 18+ and React 19 compatibility
• ⬆️ Vite 7.x for improved build performance
• ⬆️ Tailwind CSS 4.x (demo site)

Removed Dependencies

• ❌ Removed unused dependencies for cleaner dependency tree
• ❌ Removed styled-components as peer dependency (still supported for backward compatibility)
• ❌ Removed Cypress and related testing dependencies. we will be moving to playwright pretty soon

🙏 Acknowledgments

Special thanks to all contributors who helped make v3.0 possible through bug reports, feature requests!

🔗 Resources

• 📖 Full Documentation
• 📋 Props Reference
• 🎨 Migration Guide