feat: expose resolved align to scrollTo offset callback (#373)

The `offset` callback receives `ScrollOffsetInfo`, which now includes the
resolved `align` direction. For `align: 'auto'` it reads `'auto'` on the
first measure pass and settles to `'top'`/`'bottom'` on the pass that
positions the item.

This lets consumers compute direction-dependent offsets (e.g. compensating
for a sticky header only when an item is pinned to the top) without having
to reverse-engineer the direction from `getScrollInfo()` and item position.

Author: aojunhao123

src/hooks/useScrollTo.tsx

@@ -19,6 +19,14 @@ export interface ScrollOffsetInfo {
    * 通过 key 获取元素在虚拟列表中的尺寸范围。
    */
   getSize: GetSize;
+  /**
+   * Resolved align direction. For `auto` this reads `'auto'` on the first
+   * measure pass (before the direction is decided) and settles to
+   * `'top'`/`'bottom'` on the pass that actually positions the item.
+   *
+   * 已解析的对齐方向。auto 在首帧测量时仍是 'auto'，定向后变 'top'/'bottom'。
+   */
+  align: ScrollAlign;
 }
 
 export type ScrollOffset = number | ((info: ScrollOffsetInfo) => number);
@@ -75,7 +83,8 @@ export default function useScrollTo<T>(
       collectHeight();
 
       const { targetAlign, originAlign, index, offset: rawOffset } = syncState;
-      const offset = getOffset(rawOffset, { getSize });
+      const mergedAlign = targetAlign || originAlign;
+      const offset = getOffset(rawOffset, { getSize, align: mergedAlign });
 
       const height = containerRef.current.clientHeight;
       let needCollectHeight = false;
@@ -84,8 +93,6 @@ export default function useScrollTo<T>(
 
       // Go to next frame if height not exist
       if (height) {
-        const mergedAlign = targetAlign || originAlign;
-
         // Get top & bottom
         let stackTop = 0;
         let itemTop = 0;

tests/scroll.test.js

@@ -99,7 +99,12 @@ describe('List.Scroll', () => {
   it('scrollTo null will show the scrollbar', () => {
     jest.useFakeTimers();
     const listRef = React.createRef();
-    const { container } = genList({ itemHeight: 20, height: 100, data: genData(100), ref: listRef });
+    const { container } = genList({
+      itemHeight: 20,
+      height: 100,
+      data: genData(100),
+      ref: listRef,
+    });
     act(() => {
       jest.runAllTimers();
       listRef.current.scrollTo(null);
@@ -211,11 +216,42 @@ describe('List.Scroll', () => {
 
       expect(offset).toHaveBeenCalledWith({
         getSize: expect.any(Function),
+        align: 'top',
       });
       expect(offset).toHaveBeenCalledTimes(2);
       expect(container.querySelector('ul').scrollTop).toEqual(540);
     });
 
+    it('auto align exposes resolved direction to offset callback', () => {
+      const { scrollTo, container } = presetList();
+
+      // Target below viewport → auto pins to bottom
+      scrollTo(0);
+      const belowAligns = [];
+      scrollTo({
+        index: 30,
+        offset: ({ align }) => {
+          belowAligns.push(align);
+          return 0;
+        },
+      });
+      expect(belowAligns).toContain('bottom');
+      expect(container.querySelector('ul').scrollTop).toEqual(520);
+
+      // Target above viewport → auto pins to top
+      scrollTo(800);
+      const aboveAligns = [];
+      scrollTo({
+        index: 30,
+        offset: ({ align }) => {
+          aboveAligns.push(align);
+          return 0;
+        },
+      });
+      expect(aboveAligns).toContain('top');
+      expect(container.querySelector('ul').scrollTop).toEqual(600);
+    });
+
     it('fallbacks invalid function offset to zero', () => {
       const { scrollTo, container } = presetList();
       const offset = jest.fn(() => NaN);
@@ -328,15 +364,13 @@ describe('List.Scroll', () => {
     it('should show scrollbar when element has showScrollBar prop set to true', () => {
       jest.useFakeTimers();
       const listRef = React.createRef();
-      const { container } = genList(
-        {
-          itemHeight: 20,
-          height: 100,
-          data: genData(100),
-          ref: listRef,
-          showScrollBar: true,
-        }
-      );
+      const { container } = genList({
+        itemHeight: 20,
+        height: 100,
+        data: genData(100),
+        ref: listRef,
+        showScrollBar: true,
+      });
       act(() => {
         jest.runAllTimers();
       });