[scroll area] Fix overflow edge rounding (#3888)

Author: atomiks

packages/react/src/scroll-area/root/ScrollAreaRoot.test.tsx

@@ -321,6 +321,43 @@ describe('<ScrollArea.Root />', () => {
       expect(hScrollbar).not.to.have.attribute('data-overflow-x-end');
     });
 
+    it('treats near-edge scroll offsets as fully scrolled', async () => {
+      await render(
+        <ScrollArea.Root data-testid="root" style={{ width: VIEWPORT_SIZE, height: VIEWPORT_SIZE }}>
+          <ScrollArea.Viewport data-testid="viewport" style={{ width: '100%', height: '100%' }}>
+            <ScrollArea.Content data-testid="content">
+              <div style={{ width: SCROLLABLE_CONTENT_SIZE, height: SCROLLABLE_CONTENT_SIZE }} />
+            </ScrollArea.Content>
+          </ScrollArea.Viewport>
+          <ScrollArea.Scrollbar orientation="vertical" data-testid="scrollbar-vertical">
+            <ScrollArea.Thumb />
+          </ScrollArea.Scrollbar>
+          <ScrollArea.Scrollbar orientation="horizontal" data-testid="scrollbar-horizontal">
+            <ScrollArea.Thumb />
+          </ScrollArea.Scrollbar>
+        </ScrollArea.Root>,
+      );
+
+      const root = screen.getByTestId('root');
+      const viewport = screen.getByTestId('viewport');
+
+      const maxScrollTop = viewport.scrollHeight - viewport.clientHeight;
+      const maxScrollLeft = viewport.scrollWidth - viewport.clientWidth;
+
+      fireEvent.scroll(viewport, {
+        target: {
+          scrollTop: maxScrollTop - 0.5,
+          scrollLeft: maxScrollLeft - 0.5,
+        },
+      });
+      await flushMicrotasks();
+
+      expect(root).to.have.attribute('data-overflow-y-start');
+      expect(root).not.to.have.attribute('data-overflow-y-end');
+      expect(root).to.have.attribute('data-overflow-x-start');
+      expect(root).not.to.have.attribute('data-overflow-x-end');
+    });
+
     it('respects overflowEdgeThreshold and exposes scroll metrics', async () => {
       await render(
         <ScrollArea.Root

packages/react/src/scroll-area/utils/scrollEdges.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeScrollOffset, SCROLL_EDGE_TOLERANCE_PX } from './scrollEdges';
+
+describe('normalizeScrollOffset', () => {
+  it('returns 0 when max is non-positive', () => {
+    expect(normalizeScrollOffset(10, 0)).toBe(0);
+    expect(normalizeScrollOffset(10, -5)).toBe(0);
+  });
+
+  it('snaps to the start edge within the tolerance', () => {
+    expect(normalizeScrollOffset(0.5, 10)).toBe(0);
+  });
+
+  it('snaps to the end edge within the tolerance', () => {
+    expect(normalizeScrollOffset(9.5, 10)).toBe(10);
+  });
+
+  it('keeps values away from edges unchanged', () => {
+    expect(normalizeScrollOffset(5, 10)).toBe(5);
+  });
+
+  it('chooses the closest edge when tolerances overlap', () => {
+    const max = SCROLL_EDGE_TOLERANCE_PX;
+
+    expect(normalizeScrollOffset(0, max)).toBe(0);
+    expect(normalizeScrollOffset(max, max)).toBe(max);
+    expect(normalizeScrollOffset(max * 0.4, max)).toBe(0);
+    expect(normalizeScrollOffset(max * 0.6, max)).toBe(max);
+  });
+});

packages/react/src/scroll-area/utils/scrollEdges.ts

@@ -0,0 +1,29 @@
+import { clamp } from '../../utils/clamp';
+
+export const SCROLL_EDGE_TOLERANCE_PX = 1;
+
+export function normalizeScrollOffset(value: number, max: number) {
+  if (max <= 0) {
+    return 0;
+  }
+
+  const clamped = clamp(value, 0, max);
+  const startDistance = clamped;
+  const endDistance = max - clamped;
+  const withinStartTolerance = startDistance <= SCROLL_EDGE_TOLERANCE_PX;
+  const withinEndTolerance = endDistance <= SCROLL_EDGE_TOLERANCE_PX;
+
+  if (withinStartTolerance && withinEndTolerance) {
+    return startDistance <= endDistance ? 0 : max;
+  }
+
+  if (withinStartTolerance) {
+    return 0;
+  }
+
+  if (withinEndTolerance) {
+    return max;
+  }
+
+  return clamped;
+}

packages/react/src/scroll-area/viewport/ScrollAreaViewport.tsx

@@ -17,6 +17,7 @@ import { onVisible } from '../utils/onVisible';
 import { scrollAreaStateAttributesMapping } from '../root/stateAttributes';
 import type { ScrollAreaRoot } from '../root/ScrollAreaRoot';
 import { ScrollAreaViewportCssVars } from './ScrollAreaViewportCssVars';
+import { normalizeScrollOffset } from '../utils/scrollEdges';
 
 // Module-level flag to ensure we only register the CSS properties once,
 // regardless of how many Scroll Area components are mounted.
@@ -137,15 +138,20 @@ export const ScrollAreaViewport = React.forwardRef(function ScrollAreaViewport(
     let scrollLeftFromStart = 0;
     let scrollLeftFromEnd = 0;
     if (!scrollbarXHidden) {
+      let rawScrollLeftFromStart = 0;
       if (direction === 'rtl') {
-        scrollLeftFromStart = clamp(-scrollLeft, 0, maxScrollLeft);
+        rawScrollLeftFromStart = clamp(-scrollLeft, 0, maxScrollLeft);
       } else {
-        scrollLeftFromStart = clamp(scrollLeft, 0, maxScrollLeft);
+        rawScrollLeftFromStart = clamp(scrollLeft, 0, maxScrollLeft);
       }
+      scrollLeftFromStart = normalizeScrollOffset(rawScrollLeftFromStart, maxScrollLeft);
       scrollLeftFromEnd = maxScrollLeft - scrollLeftFromStart;
     }
 
-    const scrollTopFromStart = !scrollbarYHidden ? clamp(scrollTop, 0, maxScrollTop) : 0;
+    const rawScrollTopFromStart = !scrollbarYHidden ? clamp(scrollTop, 0, maxScrollTop) : 0;
+    const scrollTopFromStart = !scrollbarYHidden
+      ? normalizeScrollOffset(rawScrollTopFromStart, maxScrollTop)
+      : 0;
     const scrollTopFromEnd = !scrollbarYHidden ? maxScrollTop - scrollTopFromStart : 0;
     const nextWidth = scrollbarXHidden ? 0 : viewportWidth;
     const nextHeight = scrollbarYHidden ? 0 : viewportHeight;
@@ -223,16 +229,11 @@ export const ScrollAreaViewport = React.forwardRef(function ScrollAreaViewport(
       thumbXEl.style.transform = `translate3d(${thumbOffsetX}px,0,0)`;
     }
 
-    const clampedScrollLeftStart = clamp(scrollLeftFromStart, 0, maxScrollLeft);
-    const clampedScrollLeftEnd = clamp(scrollLeftFromEnd, 0, maxScrollLeft);
-    const clampedScrollTopStart = clamp(scrollTopFromStart, 0, maxScrollTop);
-    const clampedScrollTopEnd = clamp(scrollTopFromEnd, 0, maxScrollTop);
-
     const overflowMetricsPx: Array<[ScrollAreaViewportCssVars, number]> = [
-      [ScrollAreaViewportCssVars.scrollAreaOverflowXStart, clampedScrollLeftStart],
-      [ScrollAreaViewportCssVars.scrollAreaOverflowXEnd, clampedScrollLeftEnd],
-      [ScrollAreaViewportCssVars.scrollAreaOverflowYStart, clampedScrollTopStart],
-      [ScrollAreaViewportCssVars.scrollAreaOverflowYEnd, clampedScrollTopEnd],
+      [ScrollAreaViewportCssVars.scrollAreaOverflowXStart, scrollLeftFromStart],
+      [ScrollAreaViewportCssVars.scrollAreaOverflowXEnd, scrollLeftFromEnd],
+      [ScrollAreaViewportCssVars.scrollAreaOverflowYStart, scrollTopFromStart],
+      [ScrollAreaViewportCssVars.scrollAreaOverflowYEnd, scrollTopFromEnd],
     ];
 
     for (const [cssVar, value] of overflowMetricsPx) {
@@ -266,10 +267,10 @@ export const ScrollAreaViewport = React.forwardRef(function ScrollAreaViewport(
     });
 
     const nextOverflowEdges = {
-      xStart: !scrollbarXHidden && clampedScrollLeftStart > overflowEdgeThreshold.xStart,
-      xEnd: !scrollbarXHidden && clampedScrollLeftEnd > overflowEdgeThreshold.xEnd,
-      yStart: !scrollbarYHidden && clampedScrollTopStart > overflowEdgeThreshold.yStart,
-      yEnd: !scrollbarYHidden && clampedScrollTopEnd > overflowEdgeThreshold.yEnd,
+      xStart: !scrollbarXHidden && scrollLeftFromStart > overflowEdgeThreshold.xStart,
+      xEnd: !scrollbarXHidden && scrollLeftFromEnd > overflowEdgeThreshold.xEnd,
+      yStart: !scrollbarYHidden && scrollTopFromStart > overflowEdgeThreshold.yStart,
+      yEnd: !scrollbarYHidden && scrollTopFromEnd > overflowEdgeThreshold.yEnd,
     };
 
     setOverflowEdges((prev) => {