@impulse-ui-native/flat-list 0.0.0-stage → 9.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ImpulseUI Native contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @impulse-ui-native/flat-list
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native React Native FlatList and a small hook for initial positioning with known row sizes.
+
+## Installation
+
+```sh
+pnpm add @impulse-ui-native/flat-list
+```
+
+React and React Native are peer dependencies. No theme provider is required. The toolkit also exports this package.
+
+## Usage
+
+```tsx
+import {
+  FlatList,
+  useFlatListInitialScroll,
+} from "@impulse-ui-native/flat-list";
+
+function OptionsList({ options, selectedIndex, rowHeight, renderItem }) {
+  const initialScroll = useFlatListInitialScroll({
+    itemSize: rowHeight,
+    initialScrollIndex: selectedIndex,
+  });
+
+  return <FlatList {...initialScroll} data={options} renderItem={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.
+
+| Hook option          | Meaning                                                                            |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| `itemSize`           | Actual fixed row height, or item width for a horizontal list. Include row padding. |
+| `initialScrollIndex` | Native initial row index. Omit when no target is selected.                         |
+| `separatorSize`      | Separator height/width, default 0.                                                 |
+| `headerSize`         | Known header height/width included in offsets, default 0.                          |
+
+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.
+
+Exports: `FlatList`, `useFlatListInitialScroll`, `FlatListProps`, `FlatListRef`, and `UseFlatListInitialScrollOptions`.

package/dist/components/index.d.mts

@@ -0,0 +1 @@
+export { FlatList } from 'react-native';

package/dist/components/index.js

@@ -0,0 +1,5 @@
+import { FlatList } from "react-native";
+export {
+  FlatList
+};
+//# sourceMappingURL=index.js.map

package/dist/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/index.ts"],"sourcesContent":["export { FlatList } from \"react-native\";\n"],"mappings":"AAAA,SAAS,gBAAgB;","names":[]}

package/dist/hooks/index.d.mts

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

package/dist/hooks/index.js

@@ -0,0 +1,5 @@
+import { useFlatListInitialScroll } from "./use-flat-list-initial-scroll.hook";
+export {
+  useFlatListInitialScroll
+};
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/hooks/index.ts"],"sourcesContent":["export { useFlatListInitialScroll } from \"./use-flat-list-initial-scroll.hook\";\n"],"mappings":"AAAA,SAAS,gCAAgC;","names":[]}

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

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

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

@@ -0,0 +1,22 @@
+import { useCallback } from "react";
+function useFlatListInitialScroll(options) {
+  const {
+    itemSize,
+    initialScrollIndex,
+    separatorSize = 0,
+    headerSize = 0
+  } = options;
+  const getItemLayout = useCallback(
+    (_, index) => ({
+      length: itemSize,
+      offset: headerSize + (itemSize + separatorSize) * index,
+      index
+    }),
+    [itemSize, separatorSize, headerSize]
+  );
+  return { initialScrollIndex, getItemLayout };
+}
+export {
+  useFlatListInitialScroll
+};
+//# sourceMappingURL=use-flat-list-initial-scroll.hook.js.map

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

@@ -0,0 +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, 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,cAAc;AAC7C;","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+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';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./components";
+export * from "./hooks";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./components\";\nexport * from \"./hooks\";\nexport type * from \"./types\";\n"],"mappings":"AAAA,cAAc;AACd,cAAc;","names":[]}

package/dist/types/flat-list.types.d.mts

@@ -0,0 +1,13 @@
+import { FlatList } from 'react-native';
+export { FlatListProps } from 'react-native';
+
+type FlatListRef<Item> = FlatList<Item>;
+interface UseFlatListInitialScrollOptions {
+    /** Known row height for vertical lists, or width for horizontal lists. */
+    itemSize: number;
+    initialScrollIndex?: number | null;
+    separatorSize?: number;
+    headerSize?: number;
+}
+
+export type { FlatListRef, UseFlatListInitialScrollOptions };

package/dist/types/flat-list.types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=flat-list.types.js.map

package/dist/types/flat-list.types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types/index.d.mts

@@ -0,0 +1,2 @@
+export { FlatListRef, UseFlatListInitialScrollOptions } from './flat-list.types.mjs';
+export { FlatListProps } from 'react-native';

package/dist/types/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@impulse-ui-native/flat-list",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "9.0.0",
+  "description": "Native FlatList and a small hook for initial positioning with known row sizes.",
+  "keywords": [
+    "react-native",
+    "flat-list",
+    "virtualization",
+    "scroll"
+  ],
+  "license": "MIT",
+  "source": "src/index.ts",
+  "module": "dist/index.js",
+  "types": "dist/index.d.mts",
+  "react-native": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "react-native": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/react": "~19.2.14",
+    "eslint": "^9.38.0",
+    "prettier": "^3.6.2",
+    "react": "19.2.3",
+    "react-native": "0.86.2",
+    "typescript": "~6.0.3",
+    "@impulse-ui-native/eslint-config": "1.0.0",
+    "@impulse-ui-native/tsconfig": "1.0.0",
+    "@impulse-ui-native/prettier-config": "1.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.73"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "prettier": "@impulse-ui-native/prettier-config",
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "pnpm exec eslint . --fix",
+    "format": "prettier --write \"./**/*.{ts,tsx,js,jsx,json,md}\" --ignore-path ../../.prettierignore"
+  }
 }