cogsbox-state 0.5.312 → 0.5.314

package/package.json

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

package/src/CogsState.tsx

@@ -1814,22 +1814,18 @@ function createProxyHandler<T>(
                 endIndex: 10,
               });
 
-              // --- State and Lock Management Refs ---
+              // This ref tracks if the user is locked to the bottom.
               const isLockedToBottomRef = useRef(stickToBottom);
-              const isInitialMountRef = useRef(true);
 
-              // Subscribe to shadow state changes for height updates
+              // This state triggers a re-render when item heights change.
               const [shadowUpdateTrigger, setShadowUpdateTrigger] = useState(0);
 
               useEffect(() => {
-                // Subscribe to shadow state updates for this stateKey
                 const unsubscribe = getGlobalStore
                   .getState()
                   .subscribeToShadowState(stateKey, () => {
-                    // Force recalculation when shadow state updates
                     setShadowUpdateTrigger((prev) => prev + 1);
                   });
-
                 return unsubscribe;
               }, [stateKey]);
 
@@ -1839,21 +1835,19 @@ function createProxyHandler<T>(
               ) as any[];
               const totalCount = sourceArray.length;
 
-              // Calculate heights from shadow state
+              // Calculate heights from shadow state. This runs when data or measurements change.
               const { totalHeight, positions } = useMemo(() => {
                 const shadowArray =
                   getGlobalStore.getState().getShadowMetadata(stateKey, path) ||
                   [];
                 let height = 0;
                 const pos: number[] = [];
-
                 for (let i = 0; i < totalCount; i++) {
                   pos[i] = height;
                   const measuredHeight =
                     shadowArray[i]?.virtualizer?.itemHeight;
                   height += measuredHeight || itemHeight;
                 }
-
                 return { totalHeight: height, positions: pos };
               }, [
                 totalCount,
@@ -1863,6 +1857,7 @@ 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);
@@ -1877,36 +1872,27 @@ function createProxyHandler<T>(
                 });
               }, [range.startIndex, range.endIndex, sourceArray, totalCount]);
 
+              // This is the main effect that handles all scrolling and updates.
               useLayoutEffect(() => {
                 const container = containerRef.current;
                 if (!container) return;
 
-                const handleScroll = () => {
-                  const { scrollTop, clientHeight, scrollHeight } = container;
-
-                  // Determine if the user is at the bottom
-                  const isNowAtBottom =
-                    scrollHeight - scrollTop - clientHeight < 1;
-
-                  // If the user scrolls up, unlock. If they scroll back down, re-lock.
-                  isLockedToBottomRef.current = isNowAtBottom;
+                let scrollTimeoutId: NodeJS.Timeout;
 
-                  // Binary search for start index
+                // This function determines what's visible in the viewport.
+                const updateVirtualRange = () => {
+                  if (!container) return;
+                  const { scrollTop } = container;
                   let low = 0,
                     high = totalCount - 1;
                   while (low <= high) {
                     const mid = Math.floor((low + high) / 2);
-                    if (positions[mid]! < scrollTop) {
-                      low = mid + 1;
-                    } else {
-                      high = mid - 1;
-                    }
+                    if (positions[mid]! < scrollTop) low = mid + 1;
+                    else high = mid - 1;
                   }
                   const startIndex = Math.max(0, high - overscan);
-
-                  // Find end index
                   let endIndex = startIndex;
-                  const visibleEnd = scrollTop + clientHeight;
+                  const visibleEnd = scrollTop + container.clientHeight;
                   while (
                     endIndex < totalCount &&
                     positions[endIndex]! < visibleEnd
@@ -1914,53 +1900,54 @@ function createProxyHandler<T>(
                     endIndex++;
                   }
                   endIndex = Math.min(totalCount, endIndex + overscan);
+                  setRange({ startIndex, endIndex });
+                };
 
-                  setRange((prevRange) => {
-                    if (
-                      prevRange.startIndex !== startIndex ||
-                      prevRange.endIndex !== endIndex
-                    ) {
-                      return { startIndex, endIndex };
-                    }
-                    return prevRange;
-                  });
+                // This function handles ONLY user-initiated scrolls.
+                const handleUserScroll = () => {
+                  isLockedToBottomRef.current =
+                    container.scrollHeight -
+                      container.scrollTop -
+                      container.clientHeight <
+                    1;
+                  updateVirtualRange();
                 };
 
-                container.addEventListener("scroll", handleScroll, {
+                container.addEventListener("scroll", handleUserScroll, {
                   passive: true,
                 });
 
-                // --- REFINED STICK-TO-BOTTOM LOGIC ---
-                if (stickToBottom && isLockedToBottomRef.current) {
-                  // Use 'auto' for instant snap on first load, 'smooth' for subsequent updates.
-                  const behavior = isInitialMountRef.current
-                    ? "auto"
-                    : "smooth";
-
-                  container.scrollTo({
-                    top: container.scrollHeight,
-                    behavior,
-                  });
+                // --- THE CORE FIX ---
+                if (stickToBottom) {
+                  // We use a timeout to wait for React to render AND for useMeasure to update heights.
+                  // This is the CRUCIAL part that fixes the race condition.
+                  scrollTimeoutId = setTimeout(() => {
+                    // By the time this runs, `container.scrollHeight` is accurate.
+                    // We only scroll if the user hasn't manually scrolled up in the meantime.
+                    if (isLockedToBottomRef.current) {
+                      container.scrollTo({
+                        top: container.scrollHeight,
+                        behavior: "auto", // ALWAYS 'auto' for an instant, correct jump.
+                      });
+                    }
+                  }, 50); // A small 50ms delay is a robust buffer.
                 }
 
-                // After the first layout effect, it's no longer the initial mount.
-                // queueMicrotask ensures this is set *after* the current render cycle.
-                queueMicrotask(() => {
-                  if (isInitialMountRef.current) {
-                    isInitialMountRef.current = false;
-                  }
-                });
-
-                // Run handleScroll once on setup to set initial range and lock status
-                handleScroll();
+                // Update the visible range on initial load.
+                updateVirtualRange();
 
-                return () =>
-                  container.removeEventListener("scroll", handleScroll);
-              }, [totalCount, positions, overscan, stickToBottom]);
+                // Cleanup function is vital to prevent memory leaks.
+                return () => {
+                  clearTimeout(scrollTimeoutId);
+                  container.removeEventListener("scroll", handleUserScroll);
+                };
+                // This effect re-runs whenever the list size or item heights change.
+              }, [totalCount, positions, stickToBottom]);
 
               const scrollToBottom = useCallback(
                 (behavior: ScrollBehavior = "smooth") => {
                   if (containerRef.current) {
+                    isLockedToBottomRef.current = true;
                     containerRef.current.scrollTo({
                       top: containerRef.current.scrollHeight,
                       behavior,
@@ -1973,6 +1960,7 @@ function createProxyHandler<T>(
               const scrollToIndex = useCallback(
                 (index: number, behavior: ScrollBehavior = "smooth") => {
                   if (containerRef.current && positions[index] !== undefined) {
+                    isLockedToBottomRef.current = false;
                     containerRef.current.scrollTo({
                       top: positions[index],
                       behavior,
@@ -1999,6 +1987,7 @@ function createProxyHandler<T>(
                   },
                 },
               };
+
               return {
                 virtualState,
                 virtualizerProps,