Fix iOS extraContentPadding scroll desync by using atomic contentOffsetY

Author: trcoffman

src/components/KeyboardChatScrollView/index.tsx

@@ -69,6 +69,7 @@ const KeyboardChatScrollView = forwardRef<
       scroll,
       layout,
       size,
+      contentOffsetY,
       inverted,
       keyboardLiftBehavior,
       freeze,

src/components/KeyboardChatScrollView/useExtraContentPadding/__tests__/contentOffsetY.spec.ts

@@ -0,0 +1,140 @@
+import { sv } from "../../../../__fixtures__/sv";
+import {
+  createRender,
+  mockScrollTo,
+  reactionEffect,
+} from "../__fixtures__/setup";
+
+describe("useExtraContentPadding — contentOffsetY (iOS atomic path)", () => {
+  it("should set contentOffsetY instead of scrollTo on grow (non-inverted)", () => {
+    const render = createRender();
+    const contentOffsetY = sv(100);
+
+    render({
+      extraContentPadding: sv(20),
+      keyboardPadding: sv(300),
+      scroll: sv(100),
+      layout: sv({ width: 390, height: 800 }),
+      size: sv({ width: 390, height: 2000 }),
+      contentOffsetY,
+      inverted: false,
+      keyboardLiftBehavior: "always",
+      freeze: false,
+    });
+
+    reactionEffect(20, 0);
+
+    expect(contentOffsetY.value).toBe(120);
+    expect(mockScrollTo).not.toHaveBeenCalled();
+  });
+
+  it("should set contentOffsetY instead of scrollTo on grow (inverted)", () => {
+    const render = createRender();
+    const contentOffsetY = sv(5);
+
+    render({
+      extraContentPadding: sv(20),
+      keyboardPadding: sv(300),
+      scroll: sv(5),
+      layout: sv({ width: 390, height: 800 }),
+      size: sv({ width: 390, height: 2000 }),
+      contentOffsetY,
+      inverted: true,
+      keyboardLiftBehavior: "always",
+      freeze: false,
+    });
+
+    reactionEffect(20, 0);
+
+    expect(contentOffsetY.value).toBe(-15);
+    expect(mockScrollTo).not.toHaveBeenCalled();
+  });
+
+  it("should set contentOffsetY instead of scrollTo on shrink (non-inverted)", () => {
+    const render = createRender();
+    const contentOffsetY = sv(1220);
+
+    render({
+      extraContentPadding: sv(0),
+      keyboardPadding: sv(300),
+      scroll: sv(1220),
+      layout: sv({ width: 390, height: 800 }),
+      size: sv({ width: 390, height: 2000 }),
+      contentOffsetY,
+      inverted: false,
+      keyboardLiftBehavior: "always",
+      freeze: false,
+    });
+
+    reactionEffect(0, 20);
+
+    expect(contentOffsetY.value).toBe(1200);
+    expect(mockScrollTo).not.toHaveBeenCalled();
+  });
+
+  it("should clamp contentOffsetY to maxScroll (non-inverted)", () => {
+    const render = createRender();
+    const contentOffsetY = sv(1490);
+
+    render({
+      extraContentPadding: sv(50),
+      keyboardPadding: sv(300),
+      scroll: sv(1490),
+      layout: sv({ width: 390, height: 800 }),
+      size: sv({ width: 390, height: 2000 }),
+      contentOffsetY,
+      inverted: false,
+      keyboardLiftBehavior: "always",
+      freeze: false,
+    });
+
+    // delta = 50, scroll + delta = 1540, maxScroll = 2000 - 800 + 300 + 50 = 1550
+    reactionEffect(50, 0);
+
+    expect(contentOffsetY.value).toBe(1540);
+    expect(mockScrollTo).not.toHaveBeenCalled();
+  });
+
+  it("should clamp contentOffsetY to -totalPadding (inverted)", () => {
+    const render = createRender();
+    const contentOffsetY = sv(-280);
+
+    render({
+      extraContentPadding: sv(50),
+      keyboardPadding: sv(300),
+      scroll: sv(-280),
+      layout: sv({ width: 390, height: 800 }),
+      size: sv({ width: 390, height: 2000 }),
+      contentOffsetY,
+      inverted: true,
+      keyboardLiftBehavior: "always",
+      freeze: false,
+    });
+
+    // delta = 50, target = -280 - 50 = -330, clamp to -350
+    reactionEffect(50, 0);
+
+    expect(contentOffsetY.value).toBe(-330);
+    expect(mockScrollTo).not.toHaveBeenCalled();
+  });
+
+  it("should fall back to scrollTo when contentOffsetY is undefined", () => {
+    const render = createRender();
+
+    render({
+      extraContentPadding: sv(20),
+      keyboardPadding: sv(300),
+      scroll: sv(100),
+      layout: sv({ width: 390, height: 800 }),
+      size: sv({ width: 390, height: 2000 }),
+      contentOffsetY: undefined,
+      inverted: false,
+      keyboardLiftBehavior: "always",
+      freeze: false,
+    });
+
+    reactionEffect(20, 0);
+
+    expect(mockScrollTo).toHaveBeenCalledWith(expect.anything(), 0, 120, false);
+  });
+});

src/components/KeyboardChatScrollView/useExtraContentPadding/index.ts

@@ -19,6 +19,8 @@ type UseExtraContentPaddingOptions = {
   layout: SharedValue<{ width: number; height: number }>;
   /** Total content dimensions. */
   size: SharedValue<{ width: number; height: number }>;
+  /** IOS only — when provided, sets contentOffset atomically with contentInset. */
+  contentOffsetY?: SharedValue<number>;
   inverted: boolean;
   keyboardLiftBehavior: KeyboardLiftBehavior;
   freeze: boolean;
@@ -47,6 +49,7 @@ function useExtraContentPadding(options: UseExtraContentPaddingOptions): void {
     scroll,
     layout,
     size,
+    contentOffsetY,
     inverted,
     keyboardLiftBehavior,
     freeze,
@@ -104,15 +107,24 @@ function useExtraContentPadding(options: UseExtraContentPaddingOptions): void {
       if (inverted) {
         const target = Math.max(scroll.value - effectiveDelta, -currentTotal);
 
-        scrollTo(scrollViewRef, 0, target, false);
+        if (contentOffsetY) {
+          // eslint-disable-next-line react-compiler/react-compiler
+          contentOffsetY.value = target;
+        } else {
+          scrollTo(scrollViewRef, 0, target, false);
+        }
       } else {
         const maxScroll = Math.max(
           size.value.height - layout.value.height + currentTotal,
           0,
         );
         const target = Math.min(scroll.value + effectiveDelta, maxScroll);
 
-        scrollTo(scrollViewRef, 0, target, false);
+        if (contentOffsetY) {
+          contentOffsetY.value = target;
+        } else {
+          scrollTo(scrollViewRef, 0, target, false);
+        }
       }
     },
     [inverted, keyboardLiftBehavior, freeze],