feat(android): add position to TableView scrollToIndex (#13505)

* feat(android): add position to TableView scrollToIndex

* fix(docs): add deprecation info

android/modules/ui/src/java/ti/modules/titanium/ui/TableViewProxy.java

@@ -12,6 +12,7 @@
 
 import org.appcelerator.kroll.KrollDict;
 import org.appcelerator.kroll.annotations.Kroll;
+import org.appcelerator.titanium.TiApplication;
 import org.appcelerator.titanium.TiC;
 import org.appcelerator.titanium.TiDimension;
 import org.appcelerator.titanium.proxy.TiViewProxy;
@@ -21,6 +22,8 @@
 import android.view.View;
 
 import androidx.recyclerview.selection.SelectionTracker;
+import androidx.recyclerview.widget.LinearLayoutManager;
+import androidx.recyclerview.widget.LinearSmoothScroller;
 import androidx.recyclerview.widget.RecyclerView;
 
 import ti.modules.titanium.ui.widget.TiUITableView;
@@ -812,6 +815,14 @@ public void scrollToIndex(int index, @Kroll.argument(optional = true) KrollDict
 	{
 		final TiTableView tableView = getTableView();
 		final boolean animated = animation == null || animation.optBoolean(TiC.PROPERTY_ANIMATED, true);
+		final int position = animation != null ? animation.optInt(TiC.PROPERTY_POSITION, 0) : 0;
+		final RecyclerView.SmoothScroller smoothScrollerToTop =
+			new LinearSmoothScroller(TiApplication.getAppCurrentActivity())
+			{
+				@Override
+				protected int getVerticalSnapPreference()
+				{ return LinearSmoothScroller.SNAP_TO_START; }
+			};
 
 		if (tableView != null) {
 			final RecyclerView recyclerView = tableView.getRecyclerView();
@@ -823,9 +834,19 @@ public void scrollToIndex(int index, @Kroll.argument(optional = true) KrollDict
 					final int rowAdapterIndex = tableView.getAdapterIndex(index);
 					final Runnable action = () -> {
 						if (animated) {
-							recyclerView.smoothScrollToPosition(rowAdapterIndex);
+							if (position == ListViewScrollPositionModule.TOP) {
+								smoothScrollerToTop.setTargetPosition(rowAdapterIndex);
+								recyclerView.getLayoutManager().startSmoothScroll(smoothScrollerToTop);
+							} else {
+								recyclerView.smoothScrollToPosition(rowAdapterIndex);
+							}
 						} else {
-							recyclerView.scrollToPosition(rowAdapterIndex);
+							if (position == ListViewScrollPositionModule.TOP) {
+								((LinearLayoutManager) recyclerView.getLayoutManager())
+									.scrollToPositionWithOffset(rowAdapterIndex, 0);
+							} else {
+								recyclerView.scrollToPosition(rowAdapterIndex);
+							}
 						}
 					};
 

android/modules/ui/src/java/ti/modules/titanium/ui/TableViewScrollPositionModule.java

@@ -0,0 +1,31 @@
+/**
+ * Appcelerator Titanium Mobile
+ * Copyright (c) 2009-2020 by Appcelerator, Inc. All Rights Reserved.
+ * Licensed under the terms of the Apache Public License
+ * Please see the LICENSE included with this distribution for details.
+ */
+package ti.modules.titanium.ui;
+
+import org.appcelerator.kroll.KrollModule;
+import org.appcelerator.kroll.annotations.Kroll;
+
+import ti.modules.titanium.ui.UIModule;
+
+@Kroll.module(parentModule = UIModule.class)
+public class TableViewScrollPositionModule extends KrollModule
+{
+	@Kroll.constant
+	public static final int TOP = 1;
+	@Kroll.constant
+	public static final int BOTTOM = 2;
+	@Kroll.constant
+	public static final int MIDDLE = 3;
+	@Kroll.constant
+	public static final int NONE = 0;
+
+	@Override
+	public String getApiName()
+	{
+		return "Ti.UI.TableViewScrollPositionModule";
+	}
+}

apidoc/Titanium/UI/ListViewScrollPosition.yml

@@ -6,7 +6,7 @@ summary: |
     `deleteSectionAt`, `insertSectionAt` and `replaceSectionAt` methods.
 extends: Titanium.Proxy
 platforms: [android, iphone, ipad, macos]
-since: {android: "10.2.0", iphone: "5.4.0", ipad: "5.4.0", macos: "9.2.0"}
+since: 11.1.0
 excludes:
     properties: [bubbleParent]
     methods: [addEventListener, applyProperties, fireEvent, removeEventListener]

apidoc/Titanium/UI/TableView.yml

@@ -1823,8 +1823,8 @@ properties:
   - name: position
     summary: Specifies what position to scroll the selected row to.
     type: Number
-    constants: Titanium.UI.iOS.TableViewScrollPosition.*
-    default: <Titanium.UI.iOS.TableViewScrollPosition.NONE>
+    constants: Titanium.UI.TableViewScrollPosition.*
+    default: <Titanium.UI.TableViewScrollPosition.NONE>
 
 ---
 name: TableViewIndexEntry

apidoc/Titanium/UI/TableViewScrollPosition.yml

@@ -0,0 +1,29 @@
+---
+name: Titanium.UI.TableViewScrollPosition
+summary: |
+    A set of constants for the position value that can be used for the `position` property of
+    <Titanium.UI.TableView> when invoking `scrollToIndex`.
+extends: Titanium.Proxy
+platforms: [android, iphone, ipad, macos]
+since: 11.1.0
+createable: false
+properties:
+  - name: BOTTOM
+    summary: The table view scrolls the row of interest to the bottom of the visible table view.
+    type: Number
+    permission: read-only
+
+  - name: MIDDLE
+    summary: The table view scrolls the row of interest to the middle of the visible table view.
+    type: Number
+    permission: read-only
+
+  - name: NONE
+    summary: The table view scrolls the row of interest to be fully visible with a minimum of movement. If the row is already fully visible, no scrolling occurs. For example, if the row is above the visible area, the behavior is identical to that specified by `TOP`. This is the default.
+    type: Number
+    permission: read-only
+
+  - name: TOP
+    summary: The table view scrolls the row of interest to the top of the visible table view.
+    type: Number
+    permission: read-only

apidoc/Titanium/UI/iOS/ListViewScrollPosition.yml

@@ -1,7 +1,10 @@
 ---
 name: Titanium.UI.iOS.ListViewScrollPosition
+deprecated:
+    since: 11.1.0
+    notes: Use [Titanium.UI.ListViewScrollPosition](Titanium.UI.ListViewScrollPosition) instead.
 summary: |
-    A set of constants for the position value that can be used for the `position` property of 
+    A set of constants for the position value that can be used for the `position` property of
     <ListViewAnimationProperties> when invoking the ListView's `scrollToItem`, `appendSection`,
     `deleteSectionAt`, `insertSectionAt` and `replaceSectionAt` methods.
 extends: Titanium.Proxy
@@ -16,20 +19,20 @@ properties:
     summary: The list view scrolls the row of interest to the bottom of the visible list view.
     type: Number
     permission: read-only
-    
+
   - name: MIDDLE
     summary: The list view scrolls the row of interest to the middle of the list table view.
     type: Number
     permission: read-only
-    
+
   - name: NONE
     summary: |
         The table view scrolls the row of interest to be fully visible with a minimal movement.
         If the row is already fully visible, no scrolling occurs. For example, if the row is above the
         visible area, the behavior is identical to that specified by `TOP`. This is the default.
     type: Number
     permission: read-only
-    
+
   - name: TOP
     summary: The list view scrolls the row of interest to the top of the visible list view.
     type: Number

apidoc/Titanium/UI/iOS/TableViewScrollPosition.yml

@@ -1,7 +1,10 @@
 ---
 name: Titanium.UI.iOS.TableViewScrollPosition
+deprecated:
+    since: 11.1.0
+    notes: Use [Titanium.UI.ListViewScrollPosition](Titanium.UI.ListViewScrollPosition) instead.
 summary: |
-    A set of constants for the position value that can be used for the `position` property of 
+    A set of constants for the position value that can be used for the `position` property of
     <Titanium.UI.TableView> when invoking `scrollToIndex`.
 extends: Titanium.Proxy
 platforms: [iphone, ipad, macos]
@@ -12,17 +15,17 @@ properties:
     summary: The table view scrolls the row of interest to the bottom of the visible table view.
     type: Number
     permission: read-only
-    
+
   - name: MIDDLE
     summary: The table view scrolls the row of interest to the middle of the visible table view.
     type: Number
     permission: read-only
-    
+
   - name: NONE
     summary: The table view scrolls the row of interest to be fully visible with a minimum of movement. If the row is already fully visible, no scrolling occurs. For example, if the row is above the visible area, the behavior is identical to that specified by `TOP`. This is the default.
     type: Number
     permission: read-only
-    
+
   - name: TOP
     summary: The table view scrolls the row of interest to the top of the visible table view.
     type: Number