release 1.12.0 feat: boundary clamping, option to disable infinite panning (#62)

Author: jbbjarnason

CHANGELOG.md

@@ -1,3 +1,47 @@
+## 1.12.0 - 2025-11-01
+
+#### 🏔️ Boundary Clamping for Pan Operations
+
+**Authored by [@jbbjarnason](https://github.com/jbbjarnason)** - Thank you for this contribution!
+
+**New Features:**
+- **Boundary Clamping**: Prevent infinite panning beyond data boundaries
+  - New `boundaryClampingX` and `boundaryClampingY` options in `PanConfig`
+  - Clamps pan domain within calculated scale boundaries
+  - Perfect for constrained data exploration and guided navigation
+
+**Technical Implementation:**
+- Scale boundaries tracked via `valuesBoundaries` in `LinearScale`
+- Computed in `LinearScale.computeDomain()` from data values
+- Pan domain clamping applied in `_updatePanDomain()` during interaction
+- Seamless integration with existing pan callbacks and pan controller
+- No changes to default behavior - opt-in feature
+
+**API Example:**
+```dart
+CristalyseChart()
+  .data(timeSeriesData)
+  .mapping(x: 'time', y: 'value')
+  .geomLine()
+  .interaction(
+    pan: PanConfig(
+      enabled: true,
+      boundaryClampingX: true,  // Clamp X-axis panning
+      boundaryClampingY: true,  // Clamp Y-axis panning
+    ),
+  )
+  .build()
+```
+
+#### 🧪 Quality Assurance
+
+- Zero breaking changes - fully backward compatible
+- Default clamping disabled (infinite panning by default)
+- Tested with pan controller and manual pan interactions
+- Production ready
+
+---
+
 ## 1.11.1 - 2025-10-24
 
 #### 🐛 Bug Fixes

README.md

@@ -1101,7 +1101,7 @@ chart
 
 ## 🧪 Development Status
 
-**Current Version: 1.11.1** - Production ready with programmatic pan controller, interactive floating legends, and intelligent axis bounds
+**Current Version: 1.12.0** - Production ready with 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.
 
@@ -1126,6 +1126,7 @@ We're shipping progressively! Each release adds new visualization types while ma
 - ✅ **v1.9.0** - **Interactive & floating legends** with click-to-toggle visibility, custom positioning with offsets, color consistency preservation, and overflow rendering support
 - ✅ **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))
 
 ## Support This Project
 

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.11.1  # Latest version
+  cristalyse: ^1.12.0  # Latest version
 ```
 
 Then run:
@@ -105,6 +105,7 @@ Cristalyse has minimal dependencies to keep your app lightweight:
 
 | Version | Release Date | Key Features |
 |---------|-------------|--------------|
+| 1.12.0 | November 2025 | Boundary clamping for pan operations |
 | 1.11.1 | October 2025 | Fixed Y-axis bounds during X-axis panning |
 | 1.11.0 | October 2025 | Programmatic pan controller with panTo() and panReset() methods |
 | 1.10.3 | October 2025 | Scale padding fix for consistent chart sizing during pan operations |

doc/updates.mdx

@@ -12,6 +12,53 @@ seo:
 
 Stay informed about the latest features, improvements, and fixes in Cristalyse.
 
+<Update label="November 1, 2025" description="v1.12.0">
+  ### 🏔️ Boundary Clamping for Pan Operations
+  
+  **Authored by [@jbbjarnason](https://github.com/jbbjarnason)** - Thank you for this contribution!
+  
+  **Control infinite panning with boundary clamping!**
+  
+  **Boundary Clamping:**
+  - New `boundaryClampingX` and `boundaryClampingY` options in `PanConfig`
+  - Prevents panning beyond data boundaries when enabled
+  - Maintains intuitive pan behavior within configured domain limits
+  - Perfect for constrained data exploration and guided navigation
+  
+  **Use Cases:**
+  - Prevent users from panning too far from relevant data
+  - Create bounded exploration areas for large datasets
+  - Maintain data context during navigation
+  - Improve UX for time-series and scientific visualizations
+  
+  ```dart
+  CristalyseChart()
+    .data(timeSeriesData)
+    .mapping(x: 'time', y: 'value')
+    .geomLine()
+    .interaction(
+      pan: PanConfig(
+        enabled: true,
+        boundaryClampingX: true,  // Clamp X-axis panning
+        boundaryClampingY: true,  // Clamp Y-axis panning
+      ),
+    )
+    .build()
+  ```
+  
+  **Technical Implementation:**
+  - Scale boundaries tracked via `valuesBoundaries` in `LinearScale`
+  - Pan domain clamping applied during interaction handling
+  - Seamless integration with existing pan callbacks and pan controller
+  - No changes to default behavior - opt-in feature
+  
+  **Quality Assurance:**
+  - Zero breaking changes - fully backward compatible
+  - Default clamping disabled (infinite panning by default)
+  - Tested with pan controller and manual pan interactions
+  - Production ready
+</Update>
+
 <Update label="October 24, 2025" description="v1.11.1">
   ### 🐛 Y-axis Bounds Fix During Panning
 

example/lib/graphs/pan_example.dart

@@ -30,6 +30,7 @@ class _PanExampleWidgetState extends State<_PanExampleWidget> {
   int totalPanEvents = 0;
   int activeDataPoints = 0;
   PanController panController = PanController();
+  bool boundaryClamping = false;
 
   @override
   void initState() {
@@ -207,16 +208,32 @@ class _PanExampleWidgetState extends State<_PanExampleWidget> {
                   ));
                 },
                 icon: Icon(Icons.refresh),
-                color: Theme.of(context).primaryColor,
+                color: Theme.of(context).colorScheme.onPrimary,
               ),
               const SizedBox(width: 16),
               IconButton(
                 onPressed: () {
                   panController.panReset();
                 },
                 icon: Icon(Icons.undo),
-                color: Theme.of(context).primaryColor,
+                color: Theme.of(context).colorScheme.onPrimary,
               ),
+              Expanded(
+                child: SwitchListTile(
+                    title: Text(
+                      'Boundary Clamping',
+                      style: TextStyle(
+                          fontWeight: FontWeight.w500,
+                          color: Theme.of(context).colorScheme.onPrimary),
+                      textAlign: TextAlign.right,
+                    ),
+                    value: boundaryClamping,
+                    onChanged: (value) {
+                      setState(() {
+                        boundaryClamping = value;
+                      });
+                    }),
+              )
             ],
           ),
         ),
@@ -262,6 +279,8 @@ class _PanExampleWidgetState extends State<_PanExampleWidget> {
                       onPanEnd: _handlePanEnd,
                       throttle: const Duration(milliseconds: 50),
                       controller: panController,
+                      boundaryClampingX: boundaryClamping,
+                      boundaryClampingY: boundaryClamping,
                     ),
                   )
                   .legend(

lib/src/core/scale.dart

@@ -1,3 +1,4 @@
+import 'dart:math' as math;
 import 'package:flutter/material.dart';
 
 import 'geometry.dart';
@@ -87,13 +88,16 @@ abstract class Scale {
 class LinearScale extends Scale {
   List<double> _domain = [0, 1];
   List<double>? _ticks; // Cached ticks from Wilkinson algorithm
+  List<double> _valuesBoundaries = [0, 1];
 
   LinearScale({super.limits, super.labelFormatter, super.title});
 
   @override
   List<double> get domain => _domain;
   set domain(List<double> value) => _domain = List.from(value);
 
+  List<double> get valuesBoundaries => _valuesBoundaries;
+
   @override
   double scale(dynamic value) {
     // normalize, but do not clamp any values out of bounds
@@ -114,6 +118,10 @@ class LinearScale extends Scale {
         values, effectiveLimits, geometries,
         applyPadding: true);
 
+    if (values.isNotEmpty) {
+      _valuesBoundaries = [values.reduce(math.min), values.reduce(math.max)];
+    }
+
     if (bounds != const Bounds.ignored()) {
       // Use Wilkinson algorithm to extend bounds to nice round numbers
       final screenLength = (range[1] - range[0]).abs();

lib/src/interaction/chart_interactions.dart

@@ -136,6 +136,10 @@ class PanConfig {
   /// The widget will listen/unlisten to this in its lifecycle.
   final PanController? controller;
 
+  /// Whether to clamp the pan to the boundaries of the chart.
+  final bool boundaryClampingX;
+  final bool boundaryClampingY;
+
   const PanConfig({
     this.enabled = true,
     this.onPanUpdate,
@@ -145,6 +149,8 @@ class PanConfig {
     this.updateXDomain = false,
     this.updateYDomain = false,
     this.controller,
+    this.boundaryClampingX = false,
+    this.boundaryClampingY = false,
   });
 }
 

lib/src/widgets/animated_chart_widget.dart

@@ -1252,6 +1252,23 @@ class _AnimatedCristalyseChartWidgetState
     return sizeScale;
   }
 
+  void _updatePanDomain(
+      List<double> domain, double delta, bool clamp, Scale? scale) {
+    final newMin = domain[0] + delta;
+    final newMax = domain[1] + delta;
+    if (clamp && scale != null && scale is LinearScale) {
+      final clampMin = math.min(scale.valuesBoundaries[0], scale.domain[0]);
+      final clampMax = math.max(scale.valuesBoundaries[1], scale.domain[1]);
+      final shouldClamp = newMax > clampMax || newMin < clampMin;
+      if (shouldClamp) {
+        return;
+      }
+    }
+
+    domain[0] = newMin;
+    domain[1] = newMax;
+  }
+
   /// Update pan domains based on delta movement
   void _updatePanDomains(Rect plotArea, Offset delta) {
     if (_panXDomain == null) return;
@@ -1266,13 +1283,8 @@ class _AnimatedCristalyseChartWidgetState
 
     // Update the pan domain progressively - allow infinite panning
     if (widget.interaction.pan?.updateXDomain != false) {
-      // Default to true if not specified
-      final newXMin = _panXDomain![0] + xDataDelta;
-      final newXMax = _panXDomain![1] + xDataDelta;
-
-      // Always allow panning - no blocking, visual clipping will handle boundaries
-      _panXDomain![0] = newXMin;
-      _panXDomain![1] = newXMax;
+      _updatePanDomain(_panXDomain!, xDataDelta,
+          widget.interaction.pan?.boundaryClampingX == true, widget.xScale);
     }
 
     // Optionally handle Y panning too - allow infinite panning
@@ -1282,12 +1294,8 @@ class _AnimatedCristalyseChartWidgetState
       final yDataDelta =
           delta.dy / pixelsPerYUnit; // Positive for natural pan direction
 
-      final newYMin = _panYDomain![0] + yDataDelta;
-      final newYMax = _panYDomain![1] + yDataDelta;
-
-      // Always allow panning - visual clipping will handle boundaries
-      _panYDomain![0] = newYMin;
-      _panYDomain![1] = newYMax;
+      _updatePanDomain(_panYDomain!, yDataDelta,
+          widget.interaction.pan?.boundaryClampingY == true, widget.yScale);
     }
   }
 

pubspec.yaml

@@ -1,6 +1,6 @@
 name: cristalyse
 description: "Cristalyse is a high-performance data visualization library for Dart/Flutter that implements grammar of graphics principles with native rendering capabilities."
-version: 1.11.1
+version: 1.12.0
 homepage: https://cristalyse.com
 documentation: https://docs.cristalyse.com
 repository: https://github.com/rudi-q/cristalyse