Expose public state for sliver widgets and improve docs

ParseLiveSliverListWidget and ParseLiveSliverGridWidget now expose public State classes with refreshData and loadMoreData methods, accessible via GlobalKey for parent control. Documentation and README updated to reflect new usage patterns. Minor code cleanup and formatting improvements applied throughout.

Author: pastordee

PR_CHECKLIST.md

@@ -15,30 +15,29 @@
 - [x] **Sync with Server**: `syncLocalCacheWithServer()` syncs data to server
 
 ### Widget Offline Support
-- [x] **ParseLiveList**: `offlineMode` parameter enables local caching
-- [x] **ParseLiveSliverList**: `offlineMode` parameter enables local caching
-- [x] **ParseLiveSliverGrid**: `offlineMode` parameter enables local caching
-- [x] **ParseLivePageView**: `offlineMode` parameter enables local caching
+- [x] **ParseLiveListWidget**: `offlineMode` parameter enables local caching
+- [x] **ParseLiveSliverListWidget**: `offlineMode` parameter enables local caching
+- [x] **ParseLiveSliverGridWidget**: `offlineMode` parameter enables local caching
+- [x] **ParseLiveListPageView**: `offlineMode` parameter enables local caching
 
 ### Offline Features
 - [x] **Cache Configuration**: `cacheSize` parameter controls memory usage
 - [x] **Lazy Loading**: `lazyLoading` parameter loads data on-demand
 - [x] **Preloaded Columns**: `preloadedColumns` parameter specifies initial fields
-- [x] **Connectivity Detection**: Automatic detection of online/offline status
+- [x] **Connectivity Detection**: Automatic detection of online/offline status via mixin
 - [x] **Fallback to Cache**: Uses cached data when offline
 
 ## ✅ Code Quality
 
-### Compilation
-- [x] No compilation errors
-- [x] Only harmless unused method warnings (4 total)
-- [x] No type errors or mismatches
+### Static Analysis
+- [x] `dart analyze` - No issues in dart package
+- [x] `flutter analyze` - No issues in flutter package
+- [x] Linting fixes applied (unnecessary brace in string interpolation)
+- [x] Removed unnecessary import
 
-### Dependencies
-- [x] Git dependency correctly configured: `parse_server_sdk 8.1.0`
-- [x] Meta dependency compatible: `^1.16.0`
-- [x] All transitive dependencies resolved
-- [x] Compatible with Flutter test framework
+### Tests
+- [x] All 17 flutter package tests pass
+- [x] All 167 dart package tests pass
 
 ## ✅ New Widgets Documentation
 
@@ -49,54 +48,37 @@
 - [x] Added Table of Contents with proper anchors
 - [x] Comprehensive offline caching method examples
 - [x] Configuration parameter documentation
+- [x] GlobalKey pattern for controlling sliver widgets
 
 ### Documented Widgets
-- [x] **ParseLiveList**: Traditional ListView widget example
-- [x] **ParseLiveSliverList**: Sliver-based list widget example
-- [x] **ParseLiveSliverGrid**: Sliver-based grid widget example
-- [x] **ParseLivePageView**: PageView widget example
-
-### Documented Features
-- [x] Real-time updates via live query subscriptions
-- [x] Pagination support
-- [x] Lazy loading support
-- [x] Custom child builders
-- [x] Error handling and loading states
-- [x] Offline caching capabilities
-- [x] LRU memory management
+- [x] **ParseLiveListWidget**: Traditional ListView widget example
+- [x] **ParseLiveSliverListWidget**: Sliver-based list widget example with GlobalKey
+- [x] **ParseLiveSliverGridWidget**: Sliver-based grid widget example with GlobalKey
+- [x] **ParseLiveListPageView**: PageView widget example
+
+### Public API Exposed
+- [x] `ParseLiveSliverListWidgetState` - Public state class for list control
+- [x] `ParseLiveSliverGridWidgetState` - Public state class for grid control
+- [x] `refreshData()` - Public method to refresh widget data
+- [x] `loadMoreData()` - Public method to load more data when paginated
+- [x] `hasMoreData` - Public getter for pagination status
+- [x] `loadMoreStatus` - Public getter for load more status
 
 ## ✅ File Status
 
-### New Files
-- [x] `parse_live_sliver_list.dart` - Sliver list widget
-- [x] `parse_live_sliver_grid.dart` - Sliver grid widget
-- [x] `parse_live_page_view.dart` - PageView widget
-- [x] `parse_cached_live_list.dart` - LRU cache implementation
-- [x] `parse_offline_object.dart` (dart package) - Offline extension methods
+### New Files (Flutter Package)
+- [x] `lib/src/utils/parse_live_sliver_list.dart` - Sliver list widget
+- [x] `lib/src/utils/parse_live_sliver_grid.dart` - Sliver grid widget
+- [x] `lib/src/utils/parse_live_page_view.dart` - PageView widget
+- [x] `lib/src/utils/parse_cached_live_list.dart` - LRU cache implementation
+- [x] `lib/src/mixins/connectivity_handler_mixin.dart` - Connectivity handling mixin
+
+### New Files (Dart Package)
+- [x] `lib/src/objects/parse_offline_object.dart` - Offline extension methods
 
 ### Modified Files
-- [x] `README.md` - Updated with comprehensive documentation
-- [x] `pubspec.yaml` (dart) - Fixed meta dependency version
-- [x] `parse_live_list.dart` - Enhanced with offline support
-
-## ✅ Testing
-
-### Offline Mode Tests
-- [x] Single object save/load
-- [x] Batch object save
-- [x] Load all objects
-- [x] Object existence check
-- [x] Object update in cache
-- [x] Get all object IDs
-- [x] Remove from cache
-- [x] Clear cache
-- [x] Sync with server
-
-### Widget Tests
-- [x] All widgets compile without errors
-- [x] Offline mode parameter properly implemented
-- [x] Cache size parameter properly implemented
-- [x] Lazy loading parameter properly implemented
+- [x] `packages/flutter/README.md` - Updated with comprehensive documentation
+- [x] `packages/flutter/lib/parse_server_sdk_flutter.dart` - Exports new files
 
 ## 📋 Ready for Pull Request
 

packages/dart/lib/src/objects/parse_offline_object.dart

@@ -19,7 +19,7 @@ extension ParseObjectOffline on ParseObject {
   /// Save this object to local storage (CoreStore) for offline access.
   Future<void> saveToLocalCache() async {
     final CoreStore coreStore = ParseCoreData().getStore();
-    final String cacheKey = 'offline_cache_${parseClassName}';
+    final String cacheKey = 'offline_cache_$parseClassName';
     final List<String> cached = await _getStringListAsStrings(coreStore, cacheKey);
     // Remove any existing object with the same objectId
     cached.removeWhere((s) {
@@ -81,7 +81,7 @@ extension ParseObjectOffline on ParseObject {
   /// Remove this object from local storage (CoreStore).
   Future<void> removeFromLocalCache() async {
     final CoreStore coreStore = ParseCoreData().getStore();
-    final String cacheKey = 'offline_cache_${parseClassName}';
+    final String cacheKey = 'offline_cache_$parseClassName';
     final List<String> cached = await _getStringListAsStrings(coreStore, cacheKey);
     cached.removeWhere((s) {
       final jsonObj = json.decode(s);
@@ -105,7 +105,7 @@ extension ParseObjectOffline on ParseObject {
 
   Future<void> updateInLocalCache(Map<String, dynamic> updates) async {
     final CoreStore coreStore = ParseCoreData().getStore();
-    final String cacheKey = 'offline_cache_${parseClassName}';
+    final String cacheKey = 'offline_cache_$parseClassName';
     final List<String> cached = await _getStringListAsStrings(coreStore, cacheKey);
     for (int i = 0; i < cached.length; i++) {
       final jsonObj = json.decode(cached[i]);

packages/flutter/README.md

@@ -156,6 +156,35 @@ CustomScrollView(
 )
 ```
 
+#### Controlling Sliver Widgets with GlobalKey
+
+For sliver widgets, you can use a `GlobalKey` to control refresh and pagination from a parent widget:
+
+```dart
+final gridKey = GlobalKey<ParseLiveSliverGridWidgetState<MyObject>>();
+
+// In your CustomScrollView
+ParseLiveSliverGridWidget<MyObject>(
+  key: gridKey,
+  query: query,
+  pagination: true,
+  offlineMode: true,
+  fromJson: (json) => MyObject().fromJson(json),
+)
+
+// To refresh
+gridKey.currentState?.refreshData();
+
+// To load more (if pagination is enabled)
+gridKey.currentState?.loadMoreData();
+
+// Access status
+final hasMore = gridKey.currentState?.hasMoreData ?? false;
+final status = gridKey.currentState?.loadMoreStatus;
+```
+
+The same pattern works for `ParseLiveSliverListWidget` using `ParseLiveSliverListWidgetState`.
+
 ### ParseLivePageView
 
 A PageView widget for swiping through Parse objects:

packages/flutter/lib/src/mixins/connectivity_handler_mixin.dart

@@ -1,7 +1,6 @@
 import 'dart:async';
 import 'package:connectivity_plus/connectivity_plus.dart';
-import 'package:flutter/foundation.dart';
-import 'package:flutter/material.dart'; // Needed for State
+import 'package:flutter/material.dart'; // Needed for State and debugPrint
 
 /// Mixin to handle connectivity checks and state updates for Parse Live Widgets.
 ///

packages/flutter/lib/src/utils/parse_live_sliver_grid.dart

@@ -1,6 +1,26 @@
 part of 'package:parse_server_sdk_flutter/parse_server_sdk_flutter.dart';
 
 /// A widget that displays a live sliver grid of Parse objects.
+///
+/// This widget is designed to be used inside a [CustomScrollView].
+/// To control refresh and pagination from a parent widget, use a [GlobalKey]:
+/// 
+/// ```dart
+/// final gridKey = GlobalKey<ParseLiveSliverGridWidgetState<MyObject>>();
+/// 
+/// // In your CustomScrollView
+/// ParseLiveSliverGridWidget<MyObject>(
+///   key: gridKey,
+///   query: query,
+///   fromJson: MyObject.fromJson,
+/// ),
+/// 
+/// // To refresh
+/// gridKey.currentState?.refreshData();
+/// 
+/// // To load more (if pagination is enabled)
+/// gridKey.currentState?.loadMoreData();
+/// ```
 class ParseLiveSliverGridWidget<T extends sdk.ParseObject> extends StatefulWidget {
   const ParseLiveSliverGridWidget({
     super.key,
@@ -63,7 +83,7 @@ class ParseLiveSliverGridWidget<T extends sdk.ParseObject> extends StatefulWidge
   final T Function(Map<String, dynamic> json) fromJson;
 
   @override
-  State<ParseLiveSliverGridWidget<T>> createState() => _ParseLiveSliverGridWidgetState<T>();
+  State<ParseLiveSliverGridWidget<T>> createState() => ParseLiveSliverGridWidgetState<T>();
 
   static Widget defaultChildBuilder<T extends sdk.ParseObject>(
       BuildContext context, sdk.ParseLiveListElementSnapshot<T> snapshot, [int? index]) {
@@ -84,7 +104,11 @@ class ParseLiveSliverGridWidget<T extends sdk.ParseObject> extends StatefulWidge
   }
 }
 
-class _ParseLiveSliverGridWidgetState<T extends sdk.ParseObject>
+/// State class for [ParseLiveSliverGridWidget].
+/// 
+/// Exposes [refreshData] and [loadMoreData] methods that can be called
+/// via a [GlobalKey] to control the widget from a parent.
+class ParseLiveSliverGridWidgetState<T extends sdk.ParseObject>
     extends State<ParseLiveSliverGridWidget<T>> with ConnectivityHandlerMixin<ParseLiveSliverGridWidget<T>> {
   CachedParseLiveList<T>? _liveGrid;
   final ValueNotifier<bool> _noDataNotifier = ValueNotifier<bool>(true);
@@ -96,6 +120,12 @@ class _ParseLiveSliverGridWidgetState<T extends sdk.ParseObject>
 
   final Set<int> _loadingIndices = {}; // Used for lazy loading specific items
 
+  /// Whether more data can be loaded.
+  bool get hasMoreData => _hasMoreData;
+  
+  /// Current load more status.
+  LoadMoreStatus get loadMoreStatus => _loadMoreStatus;
+
   // --- Implement Mixin Requirements ---
   @override
   Future<void> loadDataFromServer() => _loadData();
@@ -183,7 +213,11 @@ class _ParseLiveSliverGridWidgetState<T extends sdk.ParseObject>
     }
   }
 
-  Future<void> _loadMoreData() async {
+  /// Loads more data when pagination is enabled.
+  /// 
+  /// Call this method when the user scrolls near the end of the grid.
+  /// Does nothing if offline, already loading, or no more data available.
+  Future<void> loadMoreData() async {
     if (isOffline) {
       debugPrint('$connectivityLogPrefix Cannot load more data while offline.');
       return;
@@ -408,7 +442,11 @@ class _ParseLiveSliverGridWidgetState<T extends sdk.ParseObject>
     debugPrint('$connectivityLogPrefix Finished batch save processing in ${stopwatch.elapsedMilliseconds}ms.');
   }
 
-  Future<void> _refreshData() async {
+  /// Refreshes the data by disposing the current live grid and reloading.
+  /// 
+  /// Use this method when implementing pull-to-refresh or manual refresh.
+  /// Loads from cache if offline, otherwise from server.
+  Future<void> refreshData() async {
     debugPrint('$connectivityLogPrefix Refreshing Grid data...');
     disposeLiveList();
 

packages/flutter/lib/src/utils/parse_live_sliver_list.dart

@@ -1,6 +1,26 @@
 part of 'package:parse_server_sdk_flutter/parse_server_sdk_flutter.dart';
 
 /// A widget that displays a live sliver list of Parse objects.
+///
+/// This widget is designed to be used inside a [CustomScrollView].
+/// To control refresh and pagination from a parent widget, use a [GlobalKey]:
+/// 
+/// ```dart
+/// final listKey = GlobalKey<ParseLiveSliverListWidgetState<MyObject>>();
+/// 
+/// // In your CustomScrollView
+/// ParseLiveSliverListWidget<MyObject>(
+///   key: listKey,
+///   query: query,
+///   fromJson: MyObject.fromJson,
+/// ),
+/// 
+/// // To refresh
+/// listKey.currentState?.refreshData();
+/// 
+/// // To load more (if pagination is enabled)
+/// listKey.currentState?.loadMoreData();
+/// ```
 class ParseLiveSliverListWidget<T extends sdk.ParseObject> extends StatefulWidget {
   const ParseLiveSliverListWidget({
     super.key,
@@ -51,7 +71,7 @@ class ParseLiveSliverListWidget<T extends sdk.ParseObject> extends StatefulWidge
   final T Function(Map<String, dynamic> json) fromJson;
 
   @override
-  State<ParseLiveSliverListWidget<T>> createState() => _ParseLiveSliverListWidgetState<T>();
+  State<ParseLiveSliverListWidget<T>> createState() => ParseLiveSliverListWidgetState<T>();
 
   static Widget defaultChildBuilder<T extends sdk.ParseObject>(
       BuildContext context, sdk.ParseLiveListElementSnapshot<T> snapshot, [int? index]) {
@@ -72,7 +92,11 @@ class ParseLiveSliverListWidget<T extends sdk.ParseObject> extends StatefulWidge
   }
 }
 
-class _ParseLiveSliverListWidgetState<T extends sdk.ParseObject>
+/// State class for [ParseLiveSliverListWidget].
+/// 
+/// Exposes [refreshData] and [loadMoreData] methods that can be called
+/// via a [GlobalKey] to control the widget from a parent.
+class ParseLiveSliverListWidgetState<T extends sdk.ParseObject>
     extends State<ParseLiveSliverListWidget<T>> with ConnectivityHandlerMixin<ParseLiveSliverListWidget<T>> {
   CachedParseLiveList<T>? _liveList;
   final ValueNotifier<bool> _noDataNotifier = ValueNotifier<bool>(true);
@@ -82,6 +106,12 @@ class _ParseLiveSliverListWidgetState<T extends sdk.ParseObject>
   int _currentPage = 0;
   bool _hasMoreData = true;
 
+  /// Whether more data can be loaded.
+  bool get hasMoreData => _hasMoreData;
+  
+  /// Current load more status.
+  LoadMoreStatus get loadMoreStatus => _loadMoreStatus;
+
   @override
   String get connectivityLogPrefix => 'ParseLiveSliverListWidget';
 
@@ -357,7 +387,11 @@ class _ParseLiveSliverListWidgetState<T extends sdk.ParseObject>
     }
   }
 
-  Future<void> _loadMoreData() async {
+  /// Loads more data when pagination is enabled.
+  /// 
+  /// Call this method when the user scrolls near the end of the list.
+  /// Does nothing if offline, already loading, or no more data available.
+  Future<void> loadMoreData() async {
     if (isOffline) {
       debugPrint('$connectivityLogPrefix Cannot load more data while offline.');
       return;
@@ -419,7 +453,11 @@ class _ParseLiveSliverListWidgetState<T extends sdk.ParseObject>
     }
   }
 
-  Future<void> _refreshData() async {
+  /// Refreshes the data by disposing the current live list and reloading.
+  /// 
+  /// Use this method when implementing pull-to-refresh or manual refresh.
+  /// Loads from cache if offline, otherwise from server.
+  Future<void> refreshData() async {
     debugPrint('$connectivityLogPrefix Refreshing data...');
     disposeLiveList();