fix(Listbox): prevent page scroll on mount caused by changeHighlight (#2666)

* fix(Listbox): prevent page scroll on mount caused by changeHighlight

The immediate watcher on modelValue calls highlightSelected() on mount,
which triggers el.focus() and el.scrollIntoView(). When the Listbox is
below the fold, this scrolls the entire page down without user interaction.

Pass preventScroll: true to focus() and skip scrollIntoView on the initial
mount invocation, while preserving scroll behavior for subsequent
programmatic changes and all user-driven highlights.

* fix: skip focus and scrollIntoView on first changeHighlight call

Simplify the approach: use a one-shot isInitialHighlight flag that
skips focus() and scrollIntoView() on the very first changeHighlight
invocation (the mount highlight). This covers all code paths including
virtual listbox hooks without any timing dependencies (no rAF, no
window API).

* fix(Listbox): release initial-highlight guard after mount cycle

The one-shot guard skipped focus/scroll on the first changeHighlight call
ever, which could fire at the wrong time for deferred-render consumers
(Combobox/Autocomplete open their listbox later). Release the guard on the
nextTick after the initial mount highlight instead, so only the mount
highlight is suppressed and every later highlight scrolls/focuses normally.

Add tests: Listbox must not scroll the page or steal focus on mount but must
do so on interaction, and Combobox must scroll the selected item into view on
first open.

* test(Listbox): drop unrelated Combobox test and story change

The Combobox test didn't discriminate this fix (it passes on the old
behavior too) and the story tweak only existed to support it. Keep the PR
scoped to the Listbox page-scroll-on-mount fix and its mount test.

* refactor(Listbox): thread scroll intent instead of mount-release guard

Replaces the `isInitialHighlight` flag (released on a later `nextTick`)
with an explicit `scroll` argument threaded through `highlightSelected()`.
The "is this the mount highlight?" decision is now flipped synchronously
in the modelValue watcher, so suppression travels with the call as an
argument rather than via shared state cleared on a subsequent tick — it
no longer depends on nextTick ordering, which differs between a client
mount and SSR hydration.

Behaviour is unchanged: the mount highlight only sets the roving-tabindex
target (no focus, no page scroll), while user navigation and a Combobox
opening its dropdown still focus/scroll as before. `changeHighlight` is
restored to its original form (it already accepts scrollIntoView/focus).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: zernonia <zernonia@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

packages/core/src/Listbox/Listbox.test.ts

@@ -132,6 +132,41 @@ describe('given default Listbox', () => {
   })
 })
 
+describe('given a Listbox on initial mount', () => {
+  let wrapper: VueWrapper<InstanceType<typeof Listbox>>
+  let scrollSpy: ReturnType<typeof vi.fn>
+
+  window.HTMLElement.prototype.releasePointerCapture = vi.fn()
+  window.HTMLElement.prototype.hasPointerCapture = vi.fn()
+
+  beforeEach(async () => {
+    scrollSpy = vi.fn()
+    window.HTMLElement.prototype.scrollIntoView = scrollSpy
+    document.body.innerHTML = ''
+    wrapper = mount(Listbox, { attachTo: document.body })
+    // let the immediate watcher's highlight cycle resolve
+    await nextTick()
+    await nextTick()
+  })
+
+  it('should highlight the first item without scrolling the page or stealing focus', () => {
+    const items = wrapper.findAll('[role=option]')
+    // the item is highlighted for keyboard entry...
+    expect(items[0].attributes('data-highlighted')).toBe('')
+    // ...but the mount highlight must not focus it or scroll it into view,
+    // otherwise a Listbox below the fold scrolls the whole page on load.
+    expect(scrollSpy).not.toHaveBeenCalled()
+    expect(document.activeElement).not.toBe(items[0].element)
+  })
+
+  it('should focus and scroll once the user interacts', async () => {
+    await wrapper.find('[role=listbox]').trigger('focus')
+    const items = wrapper.findAll('[role=option]')
+    expect(document.activeElement).toBe(items[0].element)
+    expect(scrollSpy).toHaveBeenCalled()
+  })
+})
+
 describe('given multiple `true` Listbox', () => {
   const kbd = useKbd()
   let wrapper: VueWrapper<InstanceType<typeof Listbox>>

packages/core/src/Listbox/ListboxRoot.vue

@@ -324,7 +324,7 @@ function handleMultipleReplace(event: KeyboardEvent, targetEl: HTMLElement) {
   }
 }
 
-async function highlightSelected(event?: Event) {
+async function highlightSelected(event?: Event, scroll = true) {
   // highlightSelected is called inside a watch with immediate set to true.
   // This results in code execution during SSR.
   // Ensure this code only runs in a browser environment, since it performs
@@ -339,18 +339,31 @@ async function highlightSelected(event?: Event) {
   else {
     const collection = getCollectionItem()
     const item = collection.find(i => i.dataset.state === 'checked')
+    // On the initial (mount) highlight we only set the roving-tabindex target.
+    // Focusing/scrolling here would scroll the page to a Listbox the user never
+    // interacted with (e.g. one below the fold). Later highlights scroll as before.
+    const focus = scroll ? undefined : false
     if (item)
-      changeHighlight(item)
+      changeHighlight(item, scroll, focus)
     else if (collection.length)
-      changeHighlight(collection[0])
+      changeHighlight(collection[0], scroll, focus)
   }
 }
 
+// `false` until the initial (mount) modelValue highlight has been queued.
+// Flipped synchronously in the watcher so the "is this the mount highlight?"
+// decision never depends on nextTick ordering, which differs between a client
+// mount and SSR hydration. The intent travels with the call as an argument
+// rather than via a shared flag released on a later tick.
+let hasHighlightedOnMount = false
+
 // watch for only programmatic changes
 watch(modelValue, () => {
   if (!isUserAction.value) {
+    const scroll = hasHighlightedOnMount
+    hasHighlightedOnMount = true
     nextTick(() => {
-      highlightSelected()
+      highlightSelected(undefined, scroll)
     })
   }
 }, { immediate: true, deep: true })