release 1.13.0 feat: add optional show titles y axes for legends (#63)

Author: jbbjarnason

CHANGELOG.md

@@ -1,3 +1,32 @@
+## 1.13.0 - 2025-11-02
+
+#### 🎨 Legend Enhancements
+
+**Authored by [@jbbjarnason](https://github.com/jbbjarnason)** - Thank you for this contribution!
+
+**Reviewed and documented by maintainer [@rudi-q](https://github.com/rudi-q)**
+
+**New Features:**
+- **Optional Y-Axis Titles in Legends**: Add `showTitles` option to display Y-axis titles alongside legend entries
+  - Improves chart legend readability when multiple Y-axes are present
+  - Optional feature - legends work as before by default
+  - Seamless integration with existing legend styling and layout
+
+**Technical Implementation:**
+- Extended `LegendWidget` to support optional Y-axis title rendering
+- Enhanced `legend.dart` core logic to handle title display
+- Updated chart configuration to expose new option
+- Includes comprehensive test coverage
+
+#### 🧪 Quality Assurance
+
+- Zero breaking changes - fully backward compatible
+- New feature is opt-in
+- All tests passing including new legend test cases
+- Production ready
+
+---
+
 ## 1.12.1 - 2025-11-02
 
 #### 🐛 Bug Fixes

README.md

@@ -1101,7 +1101,7 @@ chart
 
 ## 🧪 Development Status
 
-**Current Version: 1.12.1** - Production ready with boundary clamping for pan operations, programmatic pan controller, interactive floating legends, and intelligent axis bounds
+**Current Version: 1.13.0** - Production ready with optional Y-axis titles in legends, boundary clamping for pan operations, programmatic pan controller, interactive floating legends, and intelligent axis bounds
 
 We're shipping progressively! Each release adds new visualization types while maintaining backward compatibility.
 
@@ -1127,6 +1127,7 @@ We're shipping progressively! Each release adds new visualization types while ma
 - ✅ **v1.10.0** - **Axis titles & bubble size guide** with optional titles for all axes, visual bubble size legends, smart spacing calculations, and bubble legend validation fixes (by [@davidlrichmond](https://github.com/davidlrichmond))
 - ✅ **v1.11.0** - **Programmatic pan controller** for external chart panning control via PanController with panTo() and panReset() methods (by [@jbbjarnason](https://github.com/jbbjarnason))
 - ✅ **v1.12.0** - **Boundary clamping for pan operations** with optional boundaryClampingX and boundaryClampingY to prevent infinite panning beyond data boundaries (by [@jbbjarnason](https://github.com/jbbjarnason))
+- ✅ **v1.13.0** - **Optional Y-axis titles in legends** for improved multi-axis chart readability (by [@jbbjarnason](https://github.com/jbbjarnason))
 
 ## Support This Project
 

doc/features/legends.mdx

@@ -642,6 +642,46 @@ If you were manually creating legends, you can now use the built-in functionalit
   </Accordion>
 </AccordionGroup>
 
+## Y-Axis Titles in Legends
+
+<Info>
+**New in v1.13.0**: Display Y-axis titles alongside legend entries for multi-axis charts!
+</Info>
+
+For dual-axis charts, show axis titles in the legend to clarify which data series maps to which Y-axis:
+
+```dart
+CristalyseChart()
+  .data(dualAxisData)
+  .mapping(x: 'month', y: 'revenue')
+  .mappingY2('conversion_rate')
+  .geomBar(yAxis: YAxis.primary)
+  .geomLine(yAxis: YAxis.secondary)
+  .scaleYContinuous(title: 'Revenue ($K)')
+  .scaleY2Continuous(title: 'Conversion Rate (%)')
+  .legend(
+    position: LegendPosition.bottom,
+    showTitles: true,  // Show axis titles in legend
+  )
+  .build();
+```
+
+**Features**:
+- Displays Y-axis titles alongside respective data series
+- Improves legend readability for multi-axis charts
+- Helps users understand which metric uses which axis
+- Works with all legend positioning options
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `showTitles` | `bool` | `false` | Display Y-axis titles in legend entries |
+
+<Tip>
+**Pro Tip**: Combine `showYAxisTitles` with descriptive axis titles for maximum clarity in multi-axis charts.
+</Tip>
+
 ## What's Next?
 
 - Learn about [Custom Themes](/advanced/custom-themes) to create branded chart experiences

doc/installation.mdx

@@ -26,7 +26,7 @@ If you prefer to add the dependency manually, update your `pubspec.yaml`:
 dependencies:
   flutter:
     sdk: flutter
-  cristalyse: ^1.12.0  # Latest version
+  cristalyse: ^1.13.0  # Latest version
 ```
 
 Then run:
@@ -105,6 +105,7 @@ Cristalyse has minimal dependencies to keep your app lightweight:
 
 | Version | Release Date | Key Features |
 |---------|-------------|--------------|
+| 1.13.0 | November 2025 | Optional Y-axis titles in legends |
 | 1.12.1 | November 2025 | Fixed right padding and secondary Y-axis alignment |
 | 1.12.0 | November 2025 | Boundary clamping for pan operations |
 | 1.11.1 | October 2025 | Fixed Y-axis bounds during X-axis panning |

doc/updates.mdx

@@ -12,6 +12,37 @@ seo:
 
 Stay informed about the latest features, improvements, and fixes in Cristalyse.
 
+<Update label="November 2, 2025" description="v1.13.0">
+  ### 🎨 Legend Enhancements
+  
+  **Authored by [@jbbjarnason](https://github.com/jbbjarnason)** - Thank you for this contribution!
+  
+  **Optional Y-Axis Titles in Legends!**
+  
+  **Legend Enhancements:**
+  - New `showTitles` option to display Y-axis titles alongside legend entries
+  - Improves chart legend readability when multiple Y-axes are present
+  - Optional feature - legends work as before by default
+  - Seamless integration with existing legend styling and layout
+  
+  **Use Cases:**
+  - Multi-axis charts with clearer data context
+  - Better legend readability for complex visualizations
+  - Maintain visual hierarchy with optional titles
+  
+  **Technical Implementation:**
+  - Extended `LegendWidget` to support optional Y-axis title rendering
+  - Enhanced `legend.dart` core logic to handle title display
+  - Updated chart configuration to expose new option
+  - Comprehensive test coverage included
+  
+  **Quality Assurance:**
+  - All existing tests continue to pass
+  - Zero breaking changes - fully backward compatible
+  - New feature is opt-in
+  - Production ready
+</Update>
+
 <Update label="November 2, 2025" description="v1.12.1">
   ### 🐛 Right Padding & Secondary Y-Axis Fixes
 

example/lib/graphs/dual_axis_chart.dart

@@ -26,7 +26,14 @@ Widget buildDualAxisTab(ChartTheme currentTheme,
           height: 400,
           child: CristalyseChart()
               .data(data)
-              .mapping(x: 'month', y: 'revenue') // Primary Y-axis (left)
+              .legend(
+                  position: LegendPosition.right,
+                  interactive: true,
+                  showTitles: true)
+              .mapping(
+                  x: 'month',
+                  y: 'revenue',
+                  color: 'product') // Primary Y-axis (left)
               .mappingY2('conversion_rate') // Secondary Y-axis (right)
               .geomBar(
                   width: sliderValue.clamp(0.1, 1.0),

example/lib/screens/chart_screen.dart

@@ -210,14 +210,21 @@ class _ChartScreenState extends State<ChartScreen>
           seasonalConversion +
           (math.Random().nextDouble() - 0.5) * 2;
 
-      final dataPoint = {
+      final revenuePoint = {
         'month': month,
         'revenue': math.max(80.0, revenue), // Ensure positive revenue
+        'product': 'Product Sales',
+      };
+
+      final conversionPoint = {
+        'month': month,
         'conversion_rate': math.max(10.0,
             math.min(30.0, conversionRate)), // Keep conversion rate reasonable
+        'product': 'Conversion Rate',
       };
 
-      _dualAxisData.add(dataPoint);
+      _dualAxisData.add(revenuePoint);
+      _dualAxisData.add(conversionPoint);
     }
   }
 

example/pubspec.lock

@@ -87,7 +87,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "1.12.1"
+    version: "1.13.0"
   crypto:
     dependency: transitive
     description:

lib/src/core/chart.dart

@@ -828,6 +828,7 @@ class CristalyseChart {
   ///
   /// Automatically generates a legend based on the color mapping column.
   /// Only works when a `color` mapping is defined in `.mapping()`.
+  /// Show titles for y and y2 axes titles for the legend group if showTitles is true.
   ///
   /// Basic usage:
   /// ```dart
@@ -897,6 +898,7 @@ class CristalyseChart {
     bool? interactive,
     Set<String>? hiddenCategories,
     void Function(String category, bool visible)? onToggle,
+    bool? showTitles,
   }) {
     _legendConfig = LegendConfig(
       position: position ?? LegendPosition.topRight,
@@ -913,6 +915,7 @@ class CristalyseChart {
       interactive: interactive ?? false,
       hiddenCategories: hiddenCategories,
       onToggle: onToggle,
+      showTitles: showTitles ?? false,
     );
     return this;
   }

lib/src/core/legend.dart

@@ -75,6 +75,9 @@ class LegendConfig {
   final void Function(String category, bool visible)?
       onToggle; // Callback when legend item is toggled
 
+  /// Whether to show y and y2 axes titles for the legend group
+  final bool showTitles;
+
   const LegendConfig({
     this.position = LegendPosition.topRight,
     this.orientation = LegendOrientation.auto,
@@ -90,6 +93,7 @@ class LegendConfig {
     this.interactive = false,
     this.hiddenCategories,
     this.onToggle,
+    this.showTitles = false,
   });
 
   /// Get the effective orientation based on position
@@ -156,7 +160,8 @@ class LegendConfig {
           borderRadius == other.borderRadius &&
           floatingOffset == other.floatingOffset &&
           floatingDraggable == other.floatingDraggable &&
-          interactive == other.interactive;
+          interactive == other.interactive &&
+          showTitles == other.showTitles;
   // Note: hiddenCategories and onToggle intentionally excluded from equality
 
   @override
@@ -190,6 +195,7 @@ class LegendConfig {
     bool? interactive,
     Set<String>? hiddenCategories,
     void Function(String, bool)? onToggle,
+    bool? showTitles,
   }) {
     return LegendConfig(
       position: position ?? this.position,
@@ -206,6 +212,7 @@ class LegendConfig {
       interactive: interactive ?? this.interactive,
       hiddenCategories: hiddenCategories ?? this.hiddenCategories,
       onToggle: onToggle ?? this.onToggle,
+      showTitles: showTitles ?? this.showTitles,
     );
   }
 }