@amazon-devices/shopify__react-native-performance-lists-profiler 1.1.1758683737

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Amazon.com, Inc. or its affiliates.  All rights reserved.
+
+These materials are licensed as "Program Materials" under the Program Materials License Agreement (the "Agreement").  The Agreement is available at https://developer.amazon.com/support/legal/pml.  See the Agreement for the specific terms and conditions of the Agreement.  Capitalized terms not defined in this file have the meanings given to them in the Agreement.  
+
+If you do not agree to the above terms and conditions, you may not use any file in this package. 
+
+YOUR USE OF THE PROGRAM MATERIALS IN OR ASSOCIATED WITH THIS PACKAGE IS AT YOUR SOLE RISK.  IN NO EVENT WILL AMAZON BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, CONSEQUENTIAL, SPECIAL, INCIDENTAL, OR PUNITIVE DAMAGES (INCLUDING FOR ANY LOSS OF GOODWILL, BUSINESS INTERRUPTION, LOST PROFITS OR DATA, OR COMPUTER FAILURE OR MALFUNCTION) ARISING FROM OR RELATING TO SUCH PROGRAM MATERIALS, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, EVEN IF AMAZON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS AND DISCLAIMERS APPLY EXCEPT TO THE EXTENT PROHIBITED BY APPLICABLE LAW.

package/README.kepler.md

@@ -0,0 +1,331 @@
+# @amazon-devices/shopify__react-native-performance-lists-profiler
+
+## Getting Started
+
+`@amazon-devices/shopify__react-native-performance-lists-profiler` is an extension library atop [@shopify/react-native-performance-navigation](../react-native-performance-navigation/getting-started) that provides utilities for profiling the `FlatList` and `FlashList` components.
+
+### Installation
+
+1. Add the JavaScript library dependency in the `package.json` file:
+```json
+"dependencies": {
+  ...
+  "@amazon-devices/react-navigation__native": "^7.0.0",
+  "@amazon-devices/react-navigation__stack": "^7.0.0",
+  "@amazon-devices/shopify__flash-list": "^2.0.0",
+  "@shopify/react-native-performance-lists-profiler": "npm:@amazon-devices/shopify__react-native-performance-lists-profiler@^1.1.0",
+  "@amazon-devices/keplerscript-turbomodule-api": "^1.0.0"
+},
+```
+
+2. Reinstall dependencies using `npm install` command.
+
+## Usage Examples
+
+```js
+import React, {
+  createContext,
+  ReactNode,
+  useCallback,
+  useContext,
+  useState,
+} from 'react';
+import {
+  Button,
+  FlatList,
+  ListRenderItem,
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { NavigationContainer } from '@amazon-devices/react-navigation__native';
+import {
+  createStackNavigator,
+  StackScreenProps,
+} from '@amazon-devices/react-navigation__stack';
+import {
+  FlashListPerformanceView,
+  FlatListPerformanceView,
+  ListsProfiler,
+} from '@shopify/react-native-performance-lists-profiler';
+import {
+  FlashList,
+  ListRenderItem as FlashListRenderItem,
+} from '@amazon-devices/shopify__flash-list';
+
+interface BlankArea {
+  start: number;
+  end: number;
+}
+
+interface ListsProfilerContextType {
+  listName: string;
+  tti: number | undefined;
+  blankArea: BlankArea | undefined;
+  resetContext: () => void;
+  onInteractive: (tti: number, listName: string) => void;
+  onBlankArea: (start: number, end: number, listName: string) => void;
+}
+
+const ListsProfilerContext = createContext<ListsProfilerContextType | null>(
+  null,
+);
+
+interface ListsProfilerContextProviderProps {
+  children: ReactNode;
+}
+
+const ListsProfilerContextProvider = ({
+  children,
+}: ListsProfilerContextProviderProps) => {
+  const [listName, setListName] = useState('');
+  const [tti, setTti] = useState<number>();
+  const [blankArea, setBlankArea] = useState<BlankArea>();
+
+  const resetContext = useCallback(() => {
+    setListName('');
+    setTti(undefined);
+    setBlankArea(undefined);
+  }, []);
+
+  const onInteractive = useCallback((tti: number, listName: string) => {
+    setTti(tti);
+    setListName(listName);
+  }, []);
+
+  const onBlankArea = useCallback(
+    (start: number, end: number, listName: string) => {
+      setBlankArea({ start, end });
+      setListName(listName);
+    },
+    [],
+  );
+
+  return (
+    <ListsProfilerContext.Provider
+      value={{
+        listName,
+        tti,
+        blankArea,
+        resetContext,
+        onInteractive,
+        onBlankArea,
+      }}
+    >
+      {children}
+    </ListsProfilerContext.Provider>
+  );
+};
+
+type StackParamList = {
+  FlashListScreen: undefined;
+  FlatListScreen: undefined;
+  HomeScreen: undefined;
+};
+
+const Stack = createStackNavigator<StackParamList>();
+
+const NavigationTree = () => {
+  const { onInteractive, onBlankArea } = useContext(
+    ListsProfilerContext,
+  ) as ListsProfilerContextType;
+
+  return (
+    <ListsProfiler onInteractive={onInteractive} onBlankArea={onBlankArea}>
+      <NavigationContainer>
+        <Stack.Navigator initialRouteName="HomeScreen">
+          <Stack.Screen
+            name="HomeScreen"
+            component={HomeScreen}
+            options={{ headerShown: false }}
+          />
+          <Stack.Screen name="FlatListScreen" component={FlatListScreen} />
+          <Stack.Screen name="FlashListScreen" component={FlashListScreen} />
+        </Stack.Navigator>
+      </NavigationContainer>
+    </ListsProfiler>
+  );
+};
+
+const HomeScreen = ({
+  navigation,
+}: StackScreenProps<StackParamList, 'HomeScreen'>) => {
+  const { resetContext } = useContext(
+    ListsProfilerContext,
+  ) as ListsProfilerContextType;
+
+  const onNavigate =
+    (screenName: 'FlatListScreen' | 'FlashListScreen') => () => {
+      resetContext();
+      navigation.navigate(screenName);
+    };
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.text}>FlatList Example</Text>
+      <Button title="FlatListScreen" onPress={onNavigate('FlatListScreen')} />
+      <Text style={styles.text}>FlashList Example</Text>
+      <Button title="FlashListScreen" onPress={onNavigate('FlashListScreen')} />
+    </View>
+  );
+};
+
+export interface Item {
+  bgColor: string;
+  title: string;
+  height: number;
+}
+
+const listData = Array.from({ length: 1000 }, (_, i) => ({
+  title: `Item ${i + 1}`,
+  bgColor: `#${Math.floor(Math.random() * 16777215).toString(16)}`,
+  height: Math.floor(Math.random() * (140 - 60) + 60),
+}));
+
+interface ListItemProps {
+  item: Item;
+}
+
+const ListItem = ({ item }: ListItemProps) => {
+  return (
+    <TouchableOpacity
+      style={{ backgroundColor: item.bgColor, height: item.height }}
+    >
+      <Text style={styles.itemText}>{item.title}</Text>
+    </TouchableOpacity>
+  );
+};
+
+const DataDisplay = () => {
+  const { listName, tti, blankArea } = useContext(
+    ListsProfilerContext,
+  ) as ListsProfilerContextType;
+
+  return (
+    <View style={styles.display}>
+      <Text style={styles.text}>List name: {listName}</Text>
+      <View style={styles.spacer} />
+      <Text style={styles.text}>TTI: {tti ?? 'n/a'}</Text>
+      <View style={styles.spacer} />
+      <Text style={styles.text}>
+        Blank area:{' '}
+        {blankArea ? JSON.stringify(blankArea, undefined, 0) : 'n/a'}
+      </Text>
+    </View>
+  );
+};
+
+const FlatListScreen = () => {
+  const renderItem: ListRenderItem<Item> = useCallback(
+    ({ item }) => <ListItem item={item} />,
+    [],
+  );
+
+  return (
+    <View style={styles.listContainer}>
+      <DataDisplay />
+      <FlatListPerformanceView listName="flatlist">
+        <FlatList data={listData} renderItem={renderItem} />
+      </FlatListPerformanceView>
+    </View>
+  );
+};
+
+const FlashListScreen = () => {
+  const renderItem: FlashListRenderItem<Item> = useCallback(
+    ({ item }) => <ListItem item={item} />,
+    [],
+  );
+
+  return (
+    <View style={styles.listContainer}>
+      <DataDisplay />
+      <FlashListPerformanceView listName="flashlist">
+        <FlashList data={listData} renderItem={renderItem} />
+      </FlashListPerformanceView>
+    </View>
+  );
+};
+
+export const App = () => {
+  return (
+    <ListsProfilerContextProvider>
+      <NavigationTree />
+    </ListsProfilerContextProvider>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: '#fff',
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  display: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingVertical: 20,
+  },
+  itemText: {
+    fontSize: 24,
+    color: '#fff',
+    fontWeight: '500',
+  },
+  listContainer: {
+    flex: 1,
+  },
+  spacer: {
+    width: 32,
+  },
+  text: {
+    fontSize: 30,
+    fontWeight: '500',
+  },
+});
+```
+
+## API Reference
+
+Check out the dedicated documentation for info about this library, API reference and more: [Official react-native-performance-lists-profiler documentation](https://shopify.github.io/react-native-performance/docs/guides/react-native-performance-lists-profiler)
+
+### Components
+
+| Component | Description | Platform support |
+| --------- | ----------- | ---------------- |
+| ListsProfiler | A component used for collecting the performance metrics. Should be mounted high in the app tree | All |
+| FlatListPerformanceView | A wrapper for `FlatList` component that enables performance metrics collection | All |
+| FlashListPerformanceView | A wrapper for `FlashList` component that enables performance metrics collection | All |
+
+#### ListsProfiler props
+
+| Prop | Description | Platform support |
+| ---- | ----------- | ---------------- |
+| onInteractive | Callback triggered when the profiled list becomes interactive, can be used to process the profiling results in a custom manner. It has two parameters:  `TTI` - represents the time-to-interactive, `listName` - name of the list defined in the performance view | All |
+| onBlankArea | Callback triggered on each frame the list is scrolled - even if there is currently no blank space, can be used to process the profiling results in a custom manner. It has three parameters: `offsetStart` - visible blank space on top of the screen (while going up). If value is greater than 0, it's visible to user, `offsetEnd` - visible blank space at the end of the screen (while going down). If value is greater than 0, it's visible to user, `listName` - name of the list defined in the performance view | All |
+
+#### FlatListPerformanceView
+
+| Prop | Description | Platform support |
+| ---- | ----------- | ---------------- |
+| listName | The name of the list which will be used in the callbacks `onInteractive` and `onBlankArea` | All |
+| onInteractive | Callback triggered when the profiled list becomes interactive, can be used directly on `FlatListPerformanceView` if you want to avoid using `ListsProfiler`. It has two parameters:  `TTI` - represents the time-to-interactive, `listName` - name of the list defined in `FlatListPerformanceView` | All |
+| onBlankArea | Callback triggered on each frame the list is scrolled - even if there is currently no blank space, can be used directly on `FlatListPerformanceView` if you want to avoid using `ListsProfiler`. It has three parameters: `offsetStart` - visible blank space on top of the screen (while going up). If value is greater than 0, it's visible to user, `offsetEnd` - visible blank space at the end of the screen (while going down). If value is greater than 0, it's visible to user, `listName` - name of the list defined in `FlatListPerformanceView`| All |
+
+#### FlashListPerformanceView
+
+| Prop | Description | Platform support |
+| ---- | ----------- | ---------------- |
+| listName | The name of the list which will be used in the callbacks `onInteractive` and `onBlankArea` | All |
+
+## Known Issues
+
+* The documentation of the upstream version of the library mistakingly states that `FlashListPerformanceView` API is the same as `FlatListPerformanceView` - `onInteractive` and `onBlankArea` can only be directly used with `FlatListPerformanceView`.
+
+## Supported Versions
+
+| Package version  | Based on | @amazon-devices/react-native-kepler version |
+| ---------------- | -------- | --------------------------------- |
+| 2.0.x    | @shopify/react-native-performance-lists-profiler v1.1.0   | 2.0.x            |

package/README.md

@@ -0,0 +1,7 @@
+# react-native-performance-lists-profiler
+
+Extension library atop [@shopify/react-native-performance-navigation](../react-native-performance-navigation/getting-started). Contains utilities for profiling the `FlatList` and `FlashList` components.
+
+## Usage & installation
+
+Please refer to [documentation](https://shopify.github.io/react-native-performance/docs/guides/react-native-performance-lists-profiler/) to see more information and usage examples.

package/ReactNativePerformanceListsProfiler.podspec

@@ -0,0 +1,30 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name             = "ReactNativePerformanceListsProfiler"
+  s.version          = package['version']
+  s.summary          = package['description']
+  s.homepage         = package['homepage']
+  s.license          = package['license']
+  s.author           = package['author']
+  s.platform         = :ios, '11.0'
+  s.source           = { :git => 'https://github.com/shopify/react-native-performance.git', :tag => 'v#{s.version}' }
+  s.source_files     = 'ios/**/*.{h,m,swift}'
+  s.exclude_files    = 'ios/**/*Tests.{h,m,swift}'
+  s.requires_arc     = true
+  s.swift_version    = '5.0'
+
+  # Dependencies
+  s.dependency 'React-Core'
+
+  # Remote Pods
+
+  # Tests spec
+  s.test_spec "Tests" do |test_spec|
+    test_spec.source_files = 'ios/**/*Tests.{h, m,swift}'
+    test_spec.framework = 'XCTest'
+  end
+end
+