@impulse-ui-native/flat-list 17.1.0 → 17.2.0

package/README.md

@@ -19,7 +19,7 @@ import {
 } from "@impulse-ui-native/flat-list";
 
 function OptionsList({ options, selectedIndex, rowHeight, renderItem }) {
-  const initialScroll = useFlatListInitialScroll({
+  const { scrollToInitialIndex, ...initialScroll } = useFlatListInitialScroll({
     itemSize: rowHeight,
     initialScrollIndex: selectedIndex,
   });
@@ -28,7 +28,7 @@ function OptionsList({ options, selectedIndex, rowHeight, renderItem }) {
 }
 ```
 
-The hook returns only native `initialScrollIndex` and a stable `getItemLayout`. FlatList itself performs initial scrolling and virtualization. `FlatList` is the native component, so all native props, callbacks, and refs work directly.
+Destructure `scrollToInitialIndex` before spreading the remaining result onto the list. The remaining props are a list `ref`, native `initialScrollIndex`, and a stable `getItemLayout`. Call `scrollToInitialIndex()` to reposition an existing list without animation, using the latest target index. FlatList itself performs initial scrolling and virtualization. `FlatList` is the native component, so all native props, callbacks, and refs work directly.
 
 | Hook option          | Meaning                                                                            |
 | -------------------- | ---------------------------------------------------------------------------------- |
@@ -39,7 +39,7 @@ The hook returns only native `initialScrollIndex` and a stable `getItemLayout`.
 
 Use the same size for rendered rows and `itemSize`. For multiple columns, use the native row index, not an individual item index. For rows with different known sizes, provide your own accurate native `getItemLayout` instead of this fixed-size helper.
 
-Initial positioning follows native FlatList's mount behavior. Remount the list when a fresh initial position is needed, and mount it after asynchronously loaded data is available. Changing the selected value after initialization does not scroll an existing list.
+Initial positioning follows native FlatList's mount behavior. For asynchronous data, mount the list after data is available, or call `scrollToInitialIndex()` once the target row is available and the list has laid out. Changing the target index alone does not scroll an existing list; call the method explicitly when repositioning is intended. An omitted or negative target is ignored. If you supply your own list ref, use its native scrolling methods instead.
 
 Exports: `FlatList`, `useFlatListInitialScroll`, `FlatListProps`, `FlatListRef`, and `UseFlatListInitialScrollOptions`.
 

package/dist/hooks/index.d.mts

@@ -1,3 +1,4 @@
 export { useFlatListInitialScroll } from './use-flat-list-initial-scroll.hook.mjs';
 import 'react-native';
+import 'react';
 import '../types/flat-list.types.mjs';

package/dist/hooks/use-flat-list-initial-scroll.hook.d.mts

@@ -1,13 +1,16 @@
-import 'react-native';
+import { FlatList } from 'react-native';
+import * as react from 'react';
 import { UseFlatListInitialScrollOptions } from '../types/flat-list.types.mjs';
 
 declare function useFlatListInitialScroll<Item>(options: UseFlatListInitialScrollOptions): {
+    ref: react.RefObject<FlatList<Item> | null>;
     initialScrollIndex: number | undefined;
     getItemLayout: (data: Readonly<ArrayLike<Item>> | undefined, index: number) => {
         length: number;
         offset: number;
         index: number;
     };
+    scrollToInitialIndex: () => void;
 };
 
 export { useFlatListInitialScroll };

package/dist/hooks/use-flat-list-initial-scroll.hook.js

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 function useFlatListInitialScroll(options) {
   const {
     itemSize,
@@ -6,6 +6,13 @@ function useFlatListInitialScroll(options) {
     separatorSize = 0,
     headerSize = 0
   } = options;
+  const ref = useRef(null);
+  const scrollToInitialIndex = useCallback(() => {
+    if (initialScrollIndex == null || initialScrollIndex < 0) {
+      return;
+    }
+    ref.current?.scrollToIndex({ index: initialScrollIndex, animated: false });
+  }, [initialScrollIndex]);
   const getItemLayout = useCallback(
     (_, index) => ({
       length: itemSize,
@@ -14,7 +21,12 @@ function useFlatListInitialScroll(options) {
     }),
     [itemSize, separatorSize, headerSize]
   );
-  return { initialScrollIndex: initialScrollIndex ?? void 0, getItemLayout };
+  return {
+    ref,
+    initialScrollIndex: initialScrollIndex ?? void 0,
+    getItemLayout,
+    scrollToInitialIndex
+  };
 }
 export {
   useFlatListInitialScroll

package/dist/hooks/use-flat-list-initial-scroll.hook.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/hooks/use-flat-list-initial-scroll.hook.ts"],"sourcesContent":["import type { FlatListProps } from \"react-native\";\nimport { useCallback } from \"react\";\n\nimport type { UseFlatListInitialScrollOptions } from \"../types\";\n\nexport function useFlatListInitialScroll<Item>(\n  options: UseFlatListInitialScrollOptions,\n) {\n  const {\n    itemSize,\n    initialScrollIndex,\n    separatorSize = 0,\n    headerSize = 0,\n  } = options;\n\n  const getItemLayout = useCallback<\n    NonNullable<FlatListProps<Item>[\"getItemLayout\"]>\n  >(\n    (_, index) => ({\n      length: itemSize,\n      offset: headerSize + (itemSize + separatorSize) * index,\n      index,\n    }),\n    [itemSize, separatorSize, headerSize],\n  );\n\n  return { initialScrollIndex: initialScrollIndex ?? undefined, getItemLayout };\n}\n"],"mappings":"AACA,SAAS,mBAAmB;AAIrB,SAAS,yBACd,SACA;AACA,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA,gBAAgB;AAAA,IAChB,aAAa;AAAA,EACf,IAAI;AAEJ,QAAM,gBAAgB;AAAA,IAGpB,CAAC,GAAG,WAAW;AAAA,MACb,QAAQ;AAAA,MACR,QAAQ,cAAc,WAAW,iBAAiB;AAAA,MAClD;AAAA,IACF;AAAA,IACA,CAAC,UAAU,eAAe,UAAU;AAAA,EACtC;AAEA,SAAO,EAAE,oBAAoB,sBAAsB,QAAW,cAAc;AAC9E;","names":[]}
+{"version":3,"sources":["../../src/hooks/use-flat-list-initial-scroll.hook.ts"],"sourcesContent":["import type { FlatList, FlatListProps } from \"react-native\";\r\nimport { useCallback, useRef } from \"react\";\r\n\r\nimport type { UseFlatListInitialScrollOptions } from \"../types\";\r\n\r\nexport function useFlatListInitialScroll<Item>(\r\n  options: UseFlatListInitialScrollOptions,\r\n) {\r\n  const {\r\n    itemSize,\r\n    initialScrollIndex,\r\n    separatorSize = 0,\r\n    headerSize = 0,\r\n  } = options;\r\n\r\n  const ref = useRef<FlatList<Item>>(null);\r\n\r\n  const scrollToInitialIndex = useCallback(() => {\r\n    if (initialScrollIndex == null || initialScrollIndex < 0) {\r\n      return;\r\n    }\r\n\r\n    ref.current?.scrollToIndex({ index: initialScrollIndex, animated: false });\r\n  }, [initialScrollIndex]);\r\n\r\n  const getItemLayout = useCallback<\r\n    NonNullable<FlatListProps<Item>[\"getItemLayout\"]>\r\n  >(\r\n    (_, index) => ({\r\n      length: itemSize,\r\n      offset: headerSize + (itemSize + separatorSize) * index,\r\n      index,\r\n    }),\r\n    [itemSize, separatorSize, headerSize],\r\n  );\r\n\r\n  return {\r\n    ref,\r\n    initialScrollIndex: initialScrollIndex ?? undefined,\r\n    getItemLayout,\r\n    scrollToInitialIndex,\r\n  };\r\n}\r\n"],"mappings":"AACA,SAAS,aAAa,cAAc;AAI7B,SAAS,yBACd,SACA;AACA,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA,gBAAgB;AAAA,IAChB,aAAa;AAAA,EACf,IAAI;AAEJ,QAAM,MAAM,OAAuB,IAAI;AAEvC,QAAM,uBAAuB,YAAY,MAAM;AAC7C,QAAI,sBAAsB,QAAQ,qBAAqB,GAAG;AACxD;AAAA,IACF;AAEA,QAAI,SAAS,cAAc,EAAE,OAAO,oBAAoB,UAAU,MAAM,CAAC;AAAA,EAC3E,GAAG,CAAC,kBAAkB,CAAC;AAEvB,QAAM,gBAAgB;AAAA,IAGpB,CAAC,GAAG,WAAW;AAAA,MACb,QAAQ;AAAA,MACR,QAAQ,cAAc,WAAW,iBAAiB;AAAA,MAClD;AAAA,IACF;AAAA,IACA,CAAC,UAAU,eAAe,UAAU;AAAA,EACtC;AAEA,SAAO;AAAA,IACL;AAAA,IACA,oBAAoB,sBAAsB;AAAA,IAC1C;AAAA,IACA;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.mts

@@ -1,3 +1,4 @@
 export { FlatList, FlatListProps } from 'react-native';
 export { useFlatListInitialScroll } from './hooks/use-flat-list-initial-scroll.hook.mjs';
 export { FlatListRef, UseFlatListInitialScrollOptions } from './types/flat-list.types.mjs';
+import 'react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impulse-ui-native/flat-list",
-  "version": "17.1.0",
+  "version": "17.2.0",
   "description": "Native FlatList and a small hook for initial positioning with known row sizes.",
   "keywords": [
     "react-native",