lib/src/widget/positions_notifier/item_position.dart (5)

9-10: Add examples to the index parameter documentation.

While the other parameters have detailed documentation, the index parameter could benefit from additional context and examples.

    /// Index of the item.
+   /// 
+   /// Example: In a list of items, if this item is at position 5,
+   /// the index would be 5.
    required int index,

---

12-16: Add visual examples to edge documentation.

The documentation for edge cases is good but could be enhanced with visual examples to better illustrate the concepts.

    /// Distance in proportion of the viewport's main axis length from the
    /// leading edge of the viewport to the leading edge of the item.
    ///
    /// Note: It may be negative if the item is partially visible.
+   /// 
+   /// Example:
+   /// Viewport: |    |
+   /// Item:   |-----|  (partially out of viewport)
+   /// Value: -0.2 (20% of item is outside the viewport)
    required double itemLeadingEdge,

    /// Distance in proportion of the viewport's main axis length from the
    /// leading edge of the viewport to the trailing edge of the item.
    ///
    /// Note: It may be greater than one if the item is partially visible.
+   /// 
+   /// Example:
+   /// Viewport: |    |
+   /// Item:       |-----| (partially out of viewport)
+   /// Value: 1.2 (20% of item extends beyond viewport)
    required double itemTrailingEdge,

Also applies to: 18-22

---

49-61: Add validation for edge cases in isItemVisible.

While the method handles basic cases well, it could benefit from additional validation for edge cases.

   bool isItemVisible({
     required int index,
     bool fullyVisible = true,
   }) {
+    // Validate index is non-negative
+    if (index < 0) return false;
+
     final item = firstWhereOrNull((it) => it.index == index);
     if (item == null) return false; // Item not found.

+    // Validate edge positions are finite
+    if (!item.itemLeadingEdge.isFinite || !item.itemTrailingEdge.isFinite) {
+      return false;
+    }
+
     if (fullyVisible) {
       return item.itemLeadingEdge >= 0 && item.itemTrailingEdge <= 1;
     }

     return item.itemTrailingEdge > 0 && item.itemLeadingEdge < 1;
   }

---

28-34: Add example to topItem documentation.

The method documentation could be enhanced with an example to better illustrate its usage.

   /// Gets the top item in the viewport.
+  /// 
+  /// Example:
+  /// ```dart
+  /// final positions = {ItemPosition(index: 0, itemLeadingEdge: -0.2, itemTrailingEdge: 0.3),
+  ///                   ItemPosition(index: 1, itemLeadingEdge: 0.3, itemTrailingEdge: 0.8)};
+  /// final top = positions.topItem; // Returns the item with index 0
+  /// ```
   ItemPosition? get topItem {

---

37-43: Add example to bottomItem documentation.

Similar to topItem, the documentation could benefit from an example.

   /// Gets the bottom item in the viewport.
+  /// 
+  /// Example:
+  /// ```dart
+  /// final positions = {ItemPosition(index: 1, itemLeadingEdge: 0.3, itemTrailingEdge: 0.8),
+  ///                   ItemPosition(index: 2, itemLeadingEdge: 0.8, itemTrailingEdge: 1.3)};
+  /// final bottom = positions.bottomItem; // Returns the item with index 2
+  /// ```
   ItemPosition? get bottomItem {

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

lib/src/widget/positions_notifier/item_positions_notifier.dart (1)

211-238: ⚠️ Potential issue

Avoid redundant element registration

The element is being registered both in mount and didChangeDependencies, which could lead to duplicate registrations.

This issue was previously identified in an earlier review. The recommendation to remove the redundant registration in didChangeDependencies still applies.

lib/src/widget/positions_notifier/item_positions_notifier.dart (2)

82-102: Optimize position update scheduling

The empty elements check should be done before scheduling the update to avoid unnecessary frame callbacks.

 void _schedulePositionNotificationUpdate() {
-    if (_updateScheduled) return;
+    if (_updateScheduled || _elements.isEmpty) return;
     _updateScheduled = true;
 
     SchedulerBinding.instance.addPostFrameCallback((_) {
-      if (_elements.isNotEmpty) {
-        final positions = <ItemPosition>{};
-        for (final element in _elements) {
-          final position = element.toItemPosition(widget.controller.position);
-          if (position != null) {
-            positions.add(position);
-          }
-        }
-
-        widget.onPositionsChanged?.call(positions);
-      }
+      final positions = <ItemPosition>{};
+      for (final element in _elements) {
+        final position = element.toItemPosition(widget.controller.position);
+        if (position != null) {
+          positions.add(position);
+        }
+      }
+
+      widget.onPositionsChanged?.call(positions);
 
       _updateScheduled = false;
     });

---

188-190: Consider optimizing updateShouldNotify

The current implementation always returns true, which may cause unnecessary rebuilds. Consider implementing a more specific condition based on actual changes to onElementMounted or onElementUnmounted callbacks.

 @override
-bool updateShouldNotify(covariant _RegistryWidget oldWidget) => true;
+bool updateShouldNotify(covariant _RegistryWidget oldWidget) =>
+    oldWidget.onElementMounted != onElementMounted ||
+    oldWidget.onElementUnmounted != onElementUnmounted;

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

CHANGELOG.md (1)

4-4: Enhance the changelog entry with more context.

While the entry correctly documents the new feature, it would be more helpful to users if it included:

• The purpose of the feature (tracking visible items in scrollable lists)
• The benefits it provides (e.g., enabling scroll position-based behaviors)

Consider expanding the entry like this:

-Added `ItemPositionsNotifier` for tracking item positions in scrollable lists.
+Added `ItemPositionsNotifier` for tracking item positions in scrollable lists, enabling developers to monitor which items are currently visible and their positions within the viewport. This can be used to implement features like infinite scrolling, scroll-based animations, or visibility tracking.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro