cogsbox-state 0.5.339 → 0.5.342

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogsbox-state",
-  "version": "0.5.339",
+  "version": "0.5.342",
   "description": "React state management library with form controls and server sync",
   "type": "module",
   "main": "./dist/index.js",

package/src/CogsState.tsx

@@ -1804,7 +1804,7 @@ function createProxyHandler<T>(
             ): VirtualStateObjectResult<any[]> => {
               const {
                 itemHeight = 50,
-                overscan = 5,
+                overscan = 6, // Keeping your working overscan value
                 stickToBottom = false,
               } = options;
 
@@ -1813,11 +1813,11 @@ function createProxyHandler<T>(
                 startIndex: 0,
                 endIndex: 10,
               });
-
-              // This ref tracks if the user is locked to the bottom.
+              // The MASTER SWITCH for auto-scrolling. Starts true.
               const isLockedToBottomRef = useRef(stickToBottom);
+              // Store the previous item count to detect when new items are added.
+              const prevTotalCountRef = useRef(0);
 
-              // This state triggers a re-render when item heights change.
               const [shadowUpdateTrigger, setShadowUpdateTrigger] = useState(0);
 
               useEffect(() => {
@@ -1835,7 +1835,6 @@ function createProxyHandler<T>(
               ) as any[];
               const totalCount = sourceArray.length;
 
-              // Calculate heights from shadow state. This runs when data or measurements change.
               const { totalHeight, positions } = useMemo(() => {
                 const shadowArray =
                   getGlobalStore.getState().getShadowMetadata(stateKey, path) ||
@@ -1857,7 +1856,6 @@ function createProxyHandler<T>(
                 shadowUpdateTrigger,
               ]);
 
-              // Memoize the virtualized slice of data.
               const virtualState = useMemo(() => {
                 const start = Math.max(0, range.startIndex);
                 const end = Math.min(totalCount, range.endIndex);
@@ -1871,48 +1869,18 @@ function createProxyHandler<T>(
                   validIndices,
                 });
               }, [range.startIndex, range.endIndex, sourceArray, totalCount]);
-              // useEffect(() => {
-              //   if (stickToBottom && totalCount > 0 && containerRef.current) {
-              //     // When count increases, immediately adjust range to show bottom
-              //     const container = containerRef.current;
-              //     const visibleCount = Math.ceil(
-              //       container.clientHeight / itemHeight
-              //     );
-
-              //     // Set range to show the last items including the new one
-              //     setRange({
-              //       startIndex: Math.max(
-              //         0,
-              //         totalCount - visibleCount - overscan
-              //       ),
-              //       endIndex: totalCount,
-              //     });
-
-              //     // Then scroll to bottom after a short delay
-              //     setTimeout(() => {
-              //       container.scrollTop = container.scrollHeight + 9999;
-              //     }, 200);
-              //   }
-              // }, [totalCount]);
-              // This is the main effect that handles all scrolling and updates.
+
+              // This layout effect is for SCROLLING and RANGE updates ONLY.
               useLayoutEffect(() => {
                 const container = containerRef.current;
                 if (!container) return;
 
-                // --- STEP 1: Remember if we were scrolled to the bottom BEFORE this render ---
-                // We check this now, before the new items might have pushed the scrollbar up.
-                const wasScrolledToBottom =
-                  container.scrollHeight -
-                    container.scrollTop -
-                    container.clientHeight <
-                  itemHeight;
+                const hasNewItems = totalCount > prevTotalCountRef.current;
 
                 // This function determines what's visible in the viewport.
                 const updateVirtualRange = () => {
                   if (!container) return;
                   const { scrollTop, clientHeight } = container;
-
-                  // Find the first visible item
                   let low = 0,
                     high = totalCount - 1;
                   while (low <= high) {
@@ -1921,8 +1889,6 @@ function createProxyHandler<T>(
                     else high = mid - 1;
                   }
                   const startIndex = Math.max(0, high - overscan);
-
-                  // Find the last visible item
                   let endIndex = startIndex;
                   const visibleEnd = scrollTop + clientHeight;
                   while (
@@ -1932,50 +1898,78 @@ function createProxyHandler<T>(
                     endIndex++;
                   }
                   endIndex = Math.min(totalCount, endIndex + overscan);
-
-                  // Update the state to render the correct slice
                   setRange({ startIndex, endIndex });
                 };
 
-                // This function handles ONLY user-initiated scrolls.
+                // If new items were added AND we are locked to the bottom, scroll smoothly.
+                if (
+                  stickToBottom &&
+                  hasNewItems &&
+                  isLockedToBottomRef.current
+                ) {
+                  // A timeout is essential for smooth scrolling to work after a render.
+                  const scrollTimeout = setTimeout(() => {
+                    if (container) {
+                      container.scrollTo({
+                        top: container.scrollHeight,
+                        behavior: "smooth",
+                      });
+                    }
+                  }, 50); // A small buffer (50ms) is more robust for measurement to catch up.
+
+                  // Cleanup the timeout if the component unmounts or effect re-runs.
+                  return () => clearTimeout(scrollTimeout);
+                }
+
+                // Always update the visible range.
+                updateVirtualRange();
+              }, [
+                totalCount,
+                positions,
+                totalHeight,
+                stickToBottom,
+                itemHeight,
+              ]); // Dependencies for scrolling/range.
+
+              // This effect is ONLY for handling USER SCROLLS and the initial scroll.
+              useEffect(() => {
+                const container = containerRef.current;
+                if (!container) return;
+
+                // On initial mount, if we need to stick to the bottom, do it instantly.
+                if (isLockedToBottomRef.current) {
+                  container.scrollTop = container.scrollHeight;
+                }
+
                 const handleUserScroll = () => {
-                  // When the user scrolls, update the ref so we know their intent for the *next* update.
-                  isLockedToBottomRef.current =
+                  if (!container) return;
+                  // If the user scrolls up, break the lock.
+                  const isAtBottom =
                     container.scrollHeight -
                       container.scrollTop -
                       container.clientHeight <
                     1;
-                  // Then, just render what's visible at the new position.
-                  updateVirtualRange();
+                  if (!isAtBottom) {
+                    isLockedToBottomRef.current = false;
+                  }
                 };
 
-                // Add the listener for user scrolling.
                 container.addEventListener("scroll", handleUserScroll, {
                   passive: true,
                 });
-
-                // --- STEP 2: Apply the scroll AFTER the render, based on what we remembered ---
-                if (
-                  stickToBottom &&
-                  (isLockedToBottomRef.current || wasScrolledToBottom)
-                ) {
-                  // If we are "locked" OR if we were at the bottom just before this render,
-                  // then scroll to the new bottom. This handles both initial load and new items.
-                  container.scrollTop = container.scrollHeight;
-                }
-
-                // Always calculate the visible range after any potential scroll changes.
-                updateVirtualRange();
-
-                // Cleanup function is vital to prevent memory leaks.
-                return () => {
+                return () =>
                   container.removeEventListener("scroll", handleUserScroll);
-                };
-              }, [totalCount, positions, totalHeight, stickToBottom]);
+              }, []); // This runs only once on mount.
+
+              // After every render, update the previous count ref.
+              useEffect(() => {
+                prevTotalCountRef.current = totalCount;
+              });
 
               const scrollToBottom = useCallback(
                 (behavior: ScrollBehavior = "smooth") => {
                   if (containerRef.current) {
+                    // Re-enable the lock when the user explicitly asks to scroll to bottom.
                     isLockedToBottomRef.current = true;
                     containerRef.current.scrollTo({
                       top: containerRef.current.scrollHeight,
@@ -1989,6 +1983,7 @@ function createProxyHandler<T>(
               const scrollToIndex = useCallback(
                 (index: number, behavior: ScrollBehavior = "smooth") => {
                   if (containerRef.current && positions[index] !== undefined) {
+                    // Scrolling to a specific index should break the lock.
                     isLockedToBottomRef.current = false;
                     containerRef.current.scrollTo({
                       top: positions[index],