Document opening a list or virtual list at a row

resources/views/docs/mobile/4/edge-components/list.md

@@ -37,6 +37,8 @@ Pair with [`<native:list-item>`](#list-item) for Material3 list rows, or use any
 - `on-refresh` - Component method called on pull-to-refresh (optional, string) [iOS]
 - `on-end-reached` - Component method called when the user nears the end of the list (optional, string)
 - `end-reached-buffer` <x-docs.version-badge package="mobile-ui" since="0.7" /> - Number of items from the end at which `on-end-reached` is triggered (optional, integer, default: `3`)
+- `auto-scroll-to` <x-docs.version-badge package="mobile-ui" since="0.9" /> - Index of the row to open the list at,
+  counting from `0`. Negative values turn it off. See [Opening at a row](#opening-at-a-row) (optional, integer)
 
 
 ## Children
@@ -317,6 +319,35 @@ here just gives the demo enough rows to scroll before the end-reached trigger fi
 A buffer of `5` triggers `loadMore()` when the list is within five items of the end. When omitted, the buffer defaults to `3`.
 @endverbatim
 
+### Opening at a row
+
+<x-docs.version-badge package="mobile-ui" since="0.9" />
+
+Use `auto-scroll-to` to open a list with a given row at the top. It's useful for a deep link to a record, a screen
+restored after a relaunch, or a row the user has just added.
+
+@verbatim
+```blade static
+<native:list :auto-scroll-to="$openAt">
+    @foreach ($posts as $post)
+        <native:list-item native:key="post-{{ $post->id }}" :headline="$post->title" />
+    @endforeach
+</native:list>
+```
+@endverbatim
+
+Rows count from `0` in the order they're written. In a list with [sections](#list-section), the rows count straight
+through the sections, and section headers and footers don't count.
+
+The list jumps to the row when it's created, and scrolls to it again, animated, only when the index changes. A
+re-render that keeps the same index leaves the list where the user scrolled it. If the row hasn't loaded yet, for
+example while `on-end-reached` fetches the next page, the list scrolls to it when it arrives.
+
+Content changes on their own don't apply the index again. To scroll to the same row a second time, render once with a
+negative index, then set the row again in a later render.
+
+To open a [virtual list](virtual-list#opening-at-a-row) at a row, its window has to hold that row as well.
+
 ## Testing a list
 
 In a [component test](../testing/introduction), target a row's callbacks by the expression you wrote in the template.
@@ -359,6 +390,7 @@ NativeList::make(
 - `onRefresh(string $method)` - Pull-to-refresh handler
 - `onEndReached(string $method)` - End-reached handler
 - `endReachedBuffer(int $items)` - Number of items from the end at which the end-reached handler is triggered (default: `3`)
+- `autoScrollTo(int $index)` - Open the list at row `$index`. See [Opening at a row](#opening-at-a-row)
 
 ### `ListItem` methods
 

resources/views/docs/mobile/4/edge-components/virtual-list.md

@@ -33,6 +33,8 @@ scrolls, and the next render emits the new slice.
 - `estimated-row-height` - Estimated row height in dp, used to size the scroll extent before rows measure
   (optional, float, default: `56`).
 - `overscan` - Extra rows built beyond the visible window to smooth fast scrolling (optional, int, default: `30`).
+- `auto-scroll-to` <x-docs.version-badge package="mobile-ui" since="0.9" /> - Absolute index of the row to open the
+  list at. Negative values turn it off. See [Opening at a row](#opening-at-a-row) (optional, int).
 
 `<native:virtual-list />` is self-closing — the `item` view is the row template, not slot content.
 
@@ -43,7 +45,7 @@ state (defaulting to a `0–79` first-paint window) and the `setVirtualWindow()`
 at:
 
 ```php
-use Native\Mobile\Edge\Traits\HasVirtualListWindow;
+use Native\Mobile\Edge\Concerns\HasVirtualListWindow;
 
 class ContactsScreen extends NativeComponent
 {
@@ -69,6 +71,41 @@ The row view renders one item by absolute index:
 ```
 @endverbatim
 
+## Opening at a row
+
+<x-docs.version-badge since="4.7" />
+
+A virtual list draws only the rows inside its window, so to open it at a row, the window has to hold that row. Call
+`scrollVirtualListTo()` from the trait, for example in `mount()`, and pass `$virtualScrollTo` to the list's
+`auto-scroll-to`:
+
+```php
+public function mount(int $contact): void
+{
+    $this->scrollVirtualListTo($contact);
+}
+```
+
+@verbatim
+```blade static
+<native:virtual-list
+    :count="$total"
+    :from="$virtualWindowFrom"
+    :to="$virtualWindowTo"
+    :auto-scroll-to="$virtualScrollTo"
+    item="native.rows.contact"
+    on-window-change="setVirtualWindow" />
+```
+@endverbatim
+
+`scrollVirtualListTo(int $index)` moves the window to start a quarter of its size above the row, keeps its size, and
+sets `$virtualScrollTo` to the row. `$virtualScrollTo` is `null` until you call it. The row is in the same render
+that scrolls to it, so the list opens on the row itself rather than a placeholder.
+
+`auto-scroll-to` behaves as it does on [`<native:list>`](list#opening-at-a-row): the list scrolls when it's created
+and again when the index changes, and a re-render that keeps the same index leaves the list where the user scrolled
+it.
+
 <aside>
 
 One virtual list per screen for now. For small collections, plain [`<native:list>`](list) is simpler — reach for