React Chrono 3.0.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