@redseed/redseed-ui-vue3 8.41.0 → 8.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@redseed/redseed-ui-vue3",
-    "version": "8.41.0",
+    "version": "8.42.0",
     "description": "RedSeed UI Vue 3 components",
     "main": "index.js",
     "repository": "https://github.com/redseedtraining/redseed-ui",

package/src/components/FormField/FormFieldCombobox.vue

@@ -1,9 +1,10 @@
 <script setup>
-import { ref, computed, onMounted, onUnmounted, watch, useAttrs } from 'vue'
+import { ref, computed, onMounted, onUnmounted, watch, useAttrs, useId } from 'vue'
 import { onClickOutside } from '@vueuse/core'
 import FormFieldSlot from './FormFieldSlot.vue'
 import { ChevronDownIcon, CheckIcon } from '@heroicons/vue/24/outline'
 import { useFormFieldA11y } from '../../composables/useFormFieldA11y.js'
+import { useDropdownPosition } from '../../composables/useDropdownPosition.js'
 
 defineOptions({
     inheritAttrs: false,
@@ -39,10 +40,23 @@ const props = defineProps({
     navigable: {
         type: Boolean,
         default: false
+    },
+    // Opt-in (default off): on touch devices, render a native text input backed
+    // by a <datalist> instead of the custom floating dropdown. Sidesteps the
+    // floating-dropdown positioning entirely on mobile and gives the native
+    // picker UX, mirroring FormFieldSelect's native <select> swap. Exploratory:
+    // a <datalist> can't express the async/loading/grouped/navigable states, so
+    // the native path only engages for the plain synchronous-options case; with
+    // searchFunction or navigable set it stays on the (now overlap-safe) custom
+    // dropdown even on touch. Default-off keeps every existing consumer's
+    // behaviour unchanged. See useNativeMobile below.
+    nativeMobile: {
+        type: Boolean,
+        default: false
     }
 })
 
-const emit = defineEmits(['input', 'change', 'keyup-enter', 'navigate'])
+const emit = defineEmits(['input', 'change', 'keyup-enter', 'navigate', 'reject'])
 
 const attrs = useAttrs()
 const { inputId, ariaDescribedby, ariaInvalid } = useFormFieldA11y()
@@ -55,13 +69,34 @@ const comboboxElement = ref(null)
 const dropdownElement = ref(null)
 const highlightedIndex = ref(-1)
 
+// Native-on-touch (opt-in via the nativeMobile prop) — see the prop comment.
+const isMobileDevice = ref(false)
+const nativeInputElement = ref(null)
+const nativeText = ref('')
+
 // Async search state
 const isLoading = ref(false)
 const searchError = ref(null)
 const asyncOptions = ref([])
 const debounceTimeout = ref(null)
 
-const effectiveId = computed(() => inputId.value || attrs.id)
+// Stable fallback so the listbox/datalist/option IDs (and the native <input
+// list>/<datalist id> association) never collapse to `undefined-...` when a
+// consumer supplies neither an injected inputId nor an explicit id attr.
+const fallbackId = useId()
+const effectiveId = computed(() => inputId.value || attrs.id || fallbackId)
+
+// Engage the native <datalist> path only when opted in, on a touch device, and
+// for the plain synchronous-options case a <datalist> can actually represent
+// (no async search, no navigate-on-click). Otherwise the custom dropdown — now
+// overlap-safe via useDropdownPosition — renders on every viewport as before.
+const useNativeMobile = computed(() =>
+    props.nativeMobile
+    && isMobileDevice.value
+    && !props.searchFunction
+    && !props.navigable
+)
+const datalistId = computed(() => `${effectiveId.value}-datalist`)
 
 // Live region announcement for screen readers
 const liveAnnouncement = computed(() => {
@@ -166,6 +201,12 @@ function toggleDropdown() {
 }
 
 function open() {
+    // In native mode there is no floating dropdown — the browser owns the
+    // <datalist> suggestions, so just focus the native input.
+    if (useNativeMobile.value) {
+        nativeInputElement.value?.focus()
+        return
+    }
     isOpen.value = true
     searchText.value = ''
     hasEdited.value = false
@@ -326,57 +367,101 @@ onClickOutside(comboboxElement, () => {
     }
 })
 
-function calculateDropdownPosition() {
-    if (!dropdownElement.value || !inputElement.value) return
-
-    const bounding = inputElement.value.getBoundingClientRect()
-    const viewportHeight = window.innerHeight
-    const dropdownElementHeight = dropdownElement.value.offsetHeight
-    const spaceAboveInput = bounding.top
-    const spaceBelowInput = viewportHeight - bounding.bottom
+// Desktop / non-native dropdown positioning — shared with FormFieldSelect and
+// FormFieldSearchAsync via useDropdownPosition (no more top:0 overlap, #220).
+// 'match' locks the listbox to the input width, preserving prior behaviour.
+const { calculateDropdownPosition } = useDropdownPosition(
+    dropdownElement,
+    inputElement,
+    isOpen,
+    { widthMode: 'match' },
+)
+
+// --- Native (datalist) value handling ----------------------------------------
+// The native <input>'s text is semi-controlled via nativeText so typing isn't
+// clobbered on re-render. We keep it in sync with the model (external changes /
+// initial value) and resolve the typed-or-picked label back to an option value
+// on commit, preserving allowCustomValue semantics.
+function syncNativeText() {
+    const selected = props.options.find(option => option.value === model.value)
+    nativeText.value = selected ? selected.label : (model.value ?? '')
+}
 
-    dropdownElement.value.style.width = `${bounding.width}px`
-    dropdownElement.value.style.left = `${bounding.left}px`
+function handleNativeInput(event) {
+    nativeText.value = event.target.value
+    emit('input', event)
+}
 
-    if (spaceAboveInput <= dropdownElementHeight && spaceBelowInput <= dropdownElementHeight) {
-        dropdownElement.value.style.top = '0'
-        dropdownElement.value.style.bottom = 'auto'
-        return
-    } else if (spaceBelowInput > dropdownElementHeight) {
-        dropdownElement.value.style.top = `${bounding.bottom + window.scrollY}px`
-        dropdownElement.value.style.bottom = 'auto'
-        return
-    } else if (spaceAboveInput > dropdownElementHeight) {
-        dropdownElement.value.style.top = 'auto'
-        dropdownElement.value.style.bottom = `${spaceBelowInput + bounding.height + 8 - window.scrollY}px`
-        return
+function handleNativeChange(event) {
+    const text = event.target.value
+    const matched = props.options.find(option => option.label === text)
+    if (matched) {
+        model.value = matched.value
+        emit('change', matched.value)
+    } else if (props.allowCustomValue) {
+        model.value = text
+        emit('change', text)
+    } else {
+        // Unknown option and custom values disallowed — revert to last valid.
+        // The native datalist gives no "no results" affordance of its own, so
+        // emit `reject` (with the discarded text) to let the consumer surface
+        // feedback rather than the field silently snapping back.
+        emit('reject', text)
+        syncNativeText()
     }
 }
 
-function handleScroll(event) {
-    if (dropdownElement.value?.contains(event.target)) return
-    calculateDropdownPosition()
+watch(model, syncNativeText, { immediate: true })
+
+// Touch detection drives the native path. Decide it *reactively* rather than
+// with a once-at-mount read (#176): the old approach rendered the wrong control
+// on initial mobile / emulated load and never corrected when the pointer type
+// changed (e.g. Chrome device-emulation toggled on/off). We listen to
+// matchMedia('(pointer: coarse)') so the decision updates live, OR'd with the
+// touch-capability flags as a fallback where pointer media queries are absent.
+let coarsePointerQuery = null
+function updateIsMobileDevice() {
+    const coarsePointer = coarsePointerQuery?.matches ?? false
+    isMobileDevice.value = coarsePointer
+        || 'ontouchstart' in window
+        || navigator.maxTouchPoints > 0
 }
 
-watch(isOpen, (nowOpen) => {
-    if (nowOpen) {
-        window.addEventListener('scroll', handleScroll, { capture: true, passive: true })
-    } else {
-        window.removeEventListener('scroll', handleScroll, { capture: true })
+// Subscribe to live pointer-type changes. Prefer the modern addEventListener,
+// but fall back to the deprecated addListener/removeListener so legacy Safari /
+// WebViews — the very browsers this reactive path exists to support — still
+// update instead of silently no-op'ing under an `addEventListener?.` optional chain.
+function subscribePointerQuery() {
+    if (coarsePointerQuery?.addEventListener) {
+        coarsePointerQuery.addEventListener('change', updateIsMobileDevice)
+    } else if (coarsePointerQuery?.addListener) {
+        coarsePointerQuery.addListener(updateIsMobileDevice)
     }
-})
+}
+function unsubscribePointerQuery() {
+    if (coarsePointerQuery?.removeEventListener) {
+        coarsePointerQuery.removeEventListener('change', updateIsMobileDevice)
+    } else if (coarsePointerQuery?.removeListener) {
+        coarsePointerQuery.removeListener(updateIsMobileDevice)
+    }
+}
 
 onMounted(() => {
-    window.addEventListener('resize', calculateDropdownPosition)
+    coarsePointerQuery = window.matchMedia?.('(pointer: coarse)') ?? null
+    updateIsMobileDevice()
+    subscribePointerQuery()
 })
 
 onUnmounted(() => {
-    window.removeEventListener('resize', calculateDropdownPosition)
-    window.removeEventListener('scroll', handleScroll, { capture: true })
+    unsubscribePointerQuery()
 })
 
 defineExpose({
     focus() {
+        if (useNativeMobile.value) {
+            nativeInputElement.value?.focus()
+            return
+        }
         inputElement.value?.focus()
     },
     open,
@@ -405,7 +490,9 @@ defineExpose({
             <slot name="prefix"></slot>
         </div>
 
+        <!-- Desktop / non-native: styled input driving the custom floating dropdown -->
         <input
+            v-if="!useNativeMobile"
             ref="inputElement"
             role="combobox"
             :aria-activedescendant="isOpen && dropdownContent === 'options' && highlightedIndex >= 0 ? `${effectiveId}-option-${highlightedIndex}` : undefined"
@@ -432,9 +519,39 @@ defineExpose({
             @click="!isOpen && open()"
         >
 
+        <!-- Native (touch, opt-in): plain text input backed by a <datalist>.
+             The browser owns suggestion display, so there's no floating
+             dropdown to overlap the input. -->
+        <input
+            v-if="useNativeMobile"
+            ref="nativeInputElement"
+            :list="datalistId"
+            :aria-describedby="ariaDescribedby"
+            :aria-invalid="ariaInvalid"
+            :aria-required="$attrs.required || undefined"
+            :value="nativeText"
+            :autocomplete="$attrs.autocomplete"
+            :autofocus="$attrs.autofocus"
+            :disabled="$attrs.disabled"
+            :id="effectiveId"
+            :name="$attrs.name"
+            :placeholder="$slots.placeholder ? '' : 'Type to search or select...'"
+            :required="$attrs.required"
+            type="text"
+            @input="handleNativeInput"
+            @change="handleNativeChange"
+        >
+        <datalist v-if="useNativeMobile" :id="datalistId">
+            <option
+                v-for="option in options"
+                :key="option.value"
+                :value="option.label"
+            ></option>
+        </datalist>
+
         <!-- Placeholder slot for custom placeholder rendering -->
         <div
-            v-if="$slots.placeholder && !displayText && !isOpen"
+            v-if="$slots.placeholder && !displayText && !isOpen && !useNativeMobile"
             class="rsui-form-field-combobox__placeholder"
             aria-hidden="true"
             @click="open()"
@@ -442,7 +559,7 @@ defineExpose({
             <slot name="placeholder"></slot>
         </div>
 
-        <Teleport to="body">
+        <Teleport to="body" v-if="!useNativeMobile">
             <transition
                 enter-active-class="enter-active-class"
                 enter-from-class="enter-from-class"

package/src/components/FormField/FormFieldSearchAsync.vue

@@ -1,9 +1,10 @@
 <script setup>
-import { ref, computed, onMounted, onUnmounted, watch, useAttrs } from 'vue'
+import { ref, computed, watch, useAttrs } from 'vue'
 import { onClickOutside } from '@vueuse/core'
 import FormFieldSlot from './FormFieldSlot.vue'
 import { MagnifyingGlassIcon } from '@heroicons/vue/24/outline'
 import { useFormFieldA11y } from '../../composables/useFormFieldA11y.js'
+import { useDropdownPosition } from '../../composables/useDropdownPosition.js'
 
 defineOptions({
     inheritAttrs: false,
@@ -242,56 +243,23 @@ onClickOutside(rootElement, () => {
     if (isOpen.value) close()
 })
 
-// Measure the whole field box (icon prefix + input), not the inner <input> —
-// the input sits to the right of the prefix and is narrower, so anchoring to
-// it would leave the dropdown shifted right and narrower than the field.
-function calculateDropdownPosition() {
-    if (!dropdownElement.value || !fieldElement.value) return
-
-    const bounding = fieldElement.value.getBoundingClientRect()
-    const viewportHeight = window.innerHeight
-    const dropdownHeight = dropdownElement.value.offsetHeight
-    const spaceAbove = bounding.top
-    const spaceBelow = viewportHeight - bounding.bottom
-
-    dropdownElement.value.style.width = props.dropdownWidth != null
-        ? (typeof props.dropdownWidth === 'number' ? `${props.dropdownWidth}px` : props.dropdownWidth)
-        : `${bounding.width}px`
-    dropdownElement.value.style.left = `${bounding.left}px`
-
-    if (spaceAbove <= dropdownHeight && spaceBelow <= dropdownHeight) {
-        dropdownElement.value.style.top = '0'
-        dropdownElement.value.style.bottom = 'auto'
-    } else if (spaceBelow > dropdownHeight) {
-        dropdownElement.value.style.top = `${bounding.bottom + window.scrollY}px`
-        dropdownElement.value.style.bottom = 'auto'
-    } else if (spaceAbove > dropdownHeight) {
-        dropdownElement.value.style.top = 'auto'
-        dropdownElement.value.style.bottom = `${spaceBelow + bounding.height + 8 - window.scrollY}px`
-    }
-}
-
-function handleScroll(event) {
-    if (dropdownElement.value?.contains(event.target)) return
-    calculateDropdownPosition()
-}
-
-watch(isOpen, (nowOpen) => {
-    if (nowOpen) {
-        window.addEventListener('scroll', handleScroll, { capture: true, passive: true })
-    } else {
-        window.removeEventListener('scroll', handleScroll, { capture: true })
-    }
-})
-
-onMounted(() => {
-    window.addEventListener('resize', calculateDropdownPosition)
-})
-
-onUnmounted(() => {
-    window.removeEventListener('resize', calculateDropdownPosition)
-    window.removeEventListener('scroll', handleScroll, { capture: true })
-})
+// Positioning shared with FormFieldSelect / FormFieldCombobox via
+// useDropdownPosition (no more top:0 overlap, #221). Anchor to the whole field
+// box (icon prefix + input), not the inner <input> — the input sits to the
+// right of the prefix and is narrower, so anchoring to it would leave the
+// dropdown shifted right and narrower than the field. 'match' locks the listbox
+// to the field width; the dropdownWidth prop (when set) overrides it.
+const { calculateDropdownPosition } = useDropdownPosition(
+    dropdownElement,
+    fieldElement,
+    isOpen,
+    {
+        widthMode: 'match',
+        getWidthOverride: () => props.dropdownWidth != null
+            ? (typeof props.dropdownWidth === 'number' ? `${props.dropdownWidth}px` : props.dropdownWidth)
+            : null,
+    },
+)
 
 defineExpose({
     focus() {

package/src/components/FormField/FormFieldSelect.vue

@@ -4,6 +4,7 @@ import { onClickOutside } from '@vueuse/core'
 import FormFieldSlot from './FormFieldSlot.vue'
 import { ChevronDownIcon, CheckIcon } from '@heroicons/vue/24/outline'
 import { useFormFieldA11y } from '../../composables/useFormFieldA11y.js'
+import { useDropdownPosition } from '../../composables/useDropdownPosition.js'
 
 defineOptions({
     inheritAttrs: false,
@@ -145,103 +146,57 @@ onClickOutside(formFieldSelectElement, () => close())
 // Anchor dropdown to the visible trigger (button on desktop, select on mobile)
 const anchorElement = computed(() => triggerElement.value || selectElement.value)
 
-function calculateDropdownPosition() {
-    if (!dropdownElement.value || !anchorElement.value) return
-
-    // Preserve scrollTop before the reset so scroll-chaining (wheel past the
-    // list's boundary chains to the page, triggering this handler) cannot snap
-    // the list back to the top when maxHeight is cleared and a reflow occurs.
-    const savedScrollTop = dropdownElement.value.scrollTop
-
-    // Reset inline positioning before measuring so a previously-applied
-    // max-height (from an earlier constrained open) doesn't pollute the
-    // offsetHeight read below. Without this, a subsequent re-open after
-    // window resize would see the *capped* height and pick the wrong branch.
-    dropdownElement.value.style.maxHeight = ''
-    dropdownElement.value.style.top = ''
-    dropdownElement.value.style.bottom = ''
-
-    const bounding = anchorElement.value.getBoundingClientRect()
-    const dropdownElementHeight = dropdownElement.value.offsetHeight
-    const viewportHeight = window.innerHeight
-    const spaceAbove = bounding.top
-    const spaceBelow = viewportHeight - bounding.bottom
-
-    dropdownElement.value.style.minWidth = `${bounding.width}px`
-
-    /**
-     * Clamp the dropdown to the viewport horizontally.
-     * First cap maxWidth to the full viewport minus margins, then shift
-     * left if the dropdown's natural width would overflow the right edge.
-     * This keeps the popover fully visible for triggers near the right
-     * edge (e.g. fixed-width filter selects in ListControl).
-     */
-    const viewportWidth = window.innerWidth
-    const safeMargin = 16
-    dropdownElement.value.style.maxWidth = `${viewportWidth - safeMargin * 2}px`
-
-    // Temporarily position at trigger left so we can measure actual width
-    dropdownElement.value.style.left = `${bounding.left}px`
-    const dropdownWidth = dropdownElement.value.offsetWidth
-    const rightOverflow = (bounding.left + dropdownWidth + safeMargin) - viewportWidth
-
-    // Shift left if the dropdown overflows the right edge
-    if (rightOverflow > 0) {
-        const clampedLeft = Math.max(safeMargin, bounding.left - rightOverflow)
-        dropdownElement.value.style.left = `${clampedLeft}px`
-    }
-
-    // The dropdown has `mt-2` (8px) in CSS, so 8px gets consumed by the
-    // visual gap to the trigger; subtract another 8px for breathing room
-    // from the viewport edge (sub-pixel rounding + box-shadow ink).
-    const verticalOffset = 16
-
-    if (spaceBelow > dropdownElementHeight) {
-        dropdownElement.value.style.top = `${bounding.bottom + window.scrollY}px`
-        dropdownElement.value.style.bottom = 'auto'
-        dropdownElement.value.scrollTop = savedScrollTop
-        return
-    } else if (spaceAbove > spaceBelow) {
-        dropdownElement.value.style.top = 'auto'
-        dropdownElement.value.style.bottom = `${spaceBelow + bounding.height + 8 - window.scrollY}px`
-        dropdownElement.value.style.maxHeight = `${spaceAbove - verticalOffset}px`
-        dropdownElement.value.scrollTop = savedScrollTop
-        return
-    } else {
-        dropdownElement.value.style.top = `${bounding.bottom + window.scrollY}px`
-        dropdownElement.value.style.bottom = 'auto'
-        dropdownElement.value.style.maxHeight = `${spaceBelow - verticalOffset}px`
-        dropdownElement.value.scrollTop = savedScrollTop
-        return
-    }
+// Shared with FormFieldCombobox / FormFieldSearchAsync — see useDropdownPosition.
+// 'min' lets the listbox grow wider than the trigger (long option labels) while
+// never being narrower, and clamps to the viewport.
+const { calculateDropdownPosition } = useDropdownPosition(
+    dropdownElement,
+    anchorElement,
+    isOpen,
+    { widthMode: 'min' },
+)
+
+// Decide the native-<select> swap *reactively* rather than with a once-at-mount
+// read (#176): the old approach rendered the wrong control on initial mobile /
+// emulated load and never corrected when the pointer type changed (e.g. Chrome
+// device-emulation toggled on/off). We listen to matchMedia('(pointer: coarse)')
+// so the decision updates live, OR'd with the touch-capability flags as a
+// fallback where pointer media queries are absent.
+let coarsePointerQuery = null
+function updateIsMobileDevice() {
+    const coarsePointer = coarsePointerQuery?.matches ?? false
+    isMobileDevice.value = coarsePointer
+        || 'ontouchstart' in window
+        || navigator.maxTouchPoints > 0
 }
 
-function handleResize() {
-    calculateDropdownPosition()
-}
-
-function handleScroll(event) {
-    if (dropdownElement.value?.contains(event.target)) return
-    calculateDropdownPosition()
+// Subscribe to live pointer-type changes. Prefer the modern addEventListener,
+// but fall back to the deprecated addListener/removeListener so legacy Safari /
+// WebViews — the very browsers this reactive path exists to support — still
+// update instead of silently no-op'ing under an `addEventListener?.` optional chain.
+function subscribePointerQuery() {
+    if (coarsePointerQuery?.addEventListener) {
+        coarsePointerQuery.addEventListener('change', updateIsMobileDevice)
+    } else if (coarsePointerQuery?.addListener) {
+        coarsePointerQuery.addListener(updateIsMobileDevice)
+    }
 }
-
-watch(isOpen, (nowOpen) => {
-    if (nowOpen) {
-        window.addEventListener('scroll', handleScroll, { capture: true, passive: true })
-    } else {
-        window.removeEventListener('scroll', handleScroll, { capture: true })
+function unsubscribePointerQuery() {
+    if (coarsePointerQuery?.removeEventListener) {
+        coarsePointerQuery.removeEventListener('change', updateIsMobileDevice)
+    } else if (coarsePointerQuery?.removeListener) {
+        coarsePointerQuery.removeListener(updateIsMobileDevice)
     }
-})
+}
 
 onMounted(() => {
-    isMobileDevice.value = 'ontouchstart' in window
-        || (navigator.maxTouchPoints && navigator.maxTouchPoints > 0)
-    window.addEventListener('resize', handleResize)
+    coarsePointerQuery = window.matchMedia?.('(pointer: coarse)') ?? null
+    updateIsMobileDevice()
+    subscribePointerQuery()
 })
 
 onUnmounted(() => {
-    window.removeEventListener('resize', handleResize)
-    window.removeEventListener('scroll', handleScroll, { capture: true })
+    unsubscribePointerQuery()
 })
 
 defineExpose({

package/src/components/Tooltip/Tooltip.vue

@@ -164,13 +164,23 @@ function closeOnEscape(e) {
     }
 }
 
+// Close when the page scrolls — the trigger moves but the fixed-position popup
+// does not recalculate, causing visual detachment.
+function closeOnScroll() {
+    if (isOpen.value) {
+        close()
+    }
+}
+
 onMounted(() => {
     document.addEventListener('keydown', closeOnEscape)
     document.addEventListener('click', closeOnClickOutside)
+    window.addEventListener('scroll', closeOnScroll, { passive: true, capture: true })
 })
 onUnmounted(() => {
     document.removeEventListener('keydown', closeOnEscape)
     document.removeEventListener('click', closeOnClickOutside)
+    window.removeEventListener('scroll', closeOnScroll, { capture: true })
     clearTimeout(hoverTimeout)
 })
 </script>

package/src/composables/useDropdownPosition.js

@@ -0,0 +1,154 @@
+import { watch, onUnmounted, unref } from 'vue'
+
+/**
+ * Shared positioning logic for the teleported dropdowns used by
+ * FormFieldSelect, FormFieldCombobox and FormFieldSearchAsync.
+ *
+ * All three teleport their option list to <body> and position it manually
+ * against their trigger. The collision maths was originally hand-copied into
+ * each component and then only FormFieldSelect was fixed (PR #212), so the
+ * three diverged — FormFieldCombobox (#220) and FormFieldSearchAsync (#221)
+ * kept a `top: 0` fallback that pins the dropdown over its own input when the
+ * list is too tall to fit above or below the trigger (most visibly inside a
+ * vertically-centred Modal). This composable is FormFieldSelect's proven
+ * approach lifted out so a single fix lands everywhere at once.
+ *
+ * What it does on each (re)measure:
+ *   - Resets inline maxHeight/top/bottom before reading offsetHeight, so a cap
+ *     applied during an earlier constrained open can't poison the branch
+ *     decision on re-open.
+ *   - Preserves scrollTop across the reflow (scroll-chaining past the list's
+ *     edge re-fires this handler and would otherwise snap the list to the top).
+ *   - Clamps horizontally to the viewport, shifting left if the natural width
+ *     would overflow the right edge.
+ *   - Picks the side with the most room when the list fits neither gap, clamps
+ *     max-height to that gap, anchors to the matching trigger edge, and lets
+ *     the existing CSS `overflow` scroll the list. There is no `top: 0` branch.
+ *
+ * It also owns the scroll (capture) + resize listeners that keep the open
+ * dropdown anchored, wiring them off the shared `isOpen` ref.
+ *
+ * @param {import('vue').Ref<HTMLElement|null>} dropdownRef  the teleported list element
+ * @param {import('vue').Ref<HTMLElement|null>} anchorRef    the element to anchor to (trigger/input/field)
+ * @param {import('vue').Ref<boolean>} isOpenRef             reactive open state
+ * @param {object} [options]
+ * @param {'min'|'match'} [options.widthMode='min']  'min' sets min-width to the anchor width
+ *        (dropdown may grow wider, e.g. Select); 'match' locks width to the anchor width
+ *        (Combobox/SearchAsync).
+ * @param {() => (string|null)} [options.getWidthOverride] returns an explicit CSS width that
+ *        wins over widthMode (e.g. SearchAsync's `dropdownWidth` prop), or null to defer.
+ * @param {number} [options.verticalOffset=16] px subtracted from the available gap when clamping
+ *        max-height (visual gap to trigger + breathing room from the viewport edge).
+ * @returns {{ calculateDropdownPosition: () => void }}
+ */
+export function useDropdownPosition(dropdownRef, anchorRef, isOpenRef, options = {}) {
+    const {
+        widthMode = 'min',
+        getWidthOverride = () => null,
+        verticalOffset = 16,
+    } = options
+
+    function calculateDropdownPosition() {
+        const dropdown = dropdownRef.value
+        const anchor = unref(anchorRef)
+        if (!dropdown || !anchor) return
+
+        // Preserve scrollTop before the reset so scroll-chaining (wheel past the
+        // list's boundary chains to the page, triggering this handler) cannot snap
+        // the list back to the top when maxHeight is cleared and a reflow occurs.
+        const savedScrollTop = dropdown.scrollTop
+
+        // Reset inline positioning before measuring so a previously-applied
+        // max-height (from an earlier constrained open) doesn't pollute the
+        // offsetHeight read below. Without this, a subsequent re-open after
+        // window resize would see the *capped* height and pick the wrong branch.
+        dropdown.style.maxHeight = ''
+        dropdown.style.top = ''
+        dropdown.style.bottom = ''
+
+        const bounding = anchor.getBoundingClientRect()
+        const dropdownHeight = dropdown.offsetHeight
+        const viewportHeight = window.innerHeight
+        const spaceAbove = bounding.top
+        const spaceBelow = viewportHeight - bounding.bottom
+
+        // Width: lock to the anchor ('match'), float wider but no narrower
+        // ('min'), or honour an explicit override (e.g. SearchAsync dropdownWidth).
+        const widthOverride = getWidthOverride()
+        if (widthOverride != null) {
+            dropdown.style.width = widthOverride
+        } else if (widthMode === 'match') {
+            dropdown.style.width = `${bounding.width}px`
+        } else {
+            dropdown.style.minWidth = `${bounding.width}px`
+        }
+
+        /**
+         * Clamp the dropdown to the viewport horizontally.
+         * First cap maxWidth to the full viewport minus margins, then shift
+         * left if the dropdown's natural width would overflow the right edge.
+         * This keeps the popover fully visible for triggers near the right
+         * edge (e.g. fixed-width filter selects in ListControl).
+         */
+        const viewportWidth = window.innerWidth
+        const safeMargin = 16
+        dropdown.style.maxWidth = `${viewportWidth - safeMargin * 2}px`
+
+        // Position at the anchor's left so we can measure actual width, then
+        // shift left if it overflows the right edge.
+        dropdown.style.left = `${bounding.left}px`
+        const dropdownWidth = dropdown.offsetWidth
+        const rightOverflow = (bounding.left + dropdownWidth + safeMargin) - viewportWidth
+        if (rightOverflow > 0) {
+            const clampedLeft = Math.max(safeMargin, bounding.left - rightOverflow)
+            dropdown.style.left = `${clampedLeft}px`
+        }
+
+        if (spaceBelow > dropdownHeight) {
+            // Fits below: anchor under the trigger.
+            dropdown.style.top = `${bounding.bottom + window.scrollY}px`
+            dropdown.style.bottom = 'auto'
+        } else if (spaceAbove > spaceBelow) {
+            // More room above: anchor above the trigger, clamp to the gap.
+            dropdown.style.top = 'auto'
+            dropdown.style.bottom = `${spaceBelow + bounding.height + 8 - window.scrollY}px`
+            dropdown.style.maxHeight = `${spaceAbove - verticalOffset}px`
+        } else {
+            // More room below (or equal): anchor under the trigger, clamp to the gap.
+            // Never pin to top:0 over the trigger — let CSS overflow scroll the list.
+            dropdown.style.top = `${bounding.bottom + window.scrollY}px`
+            dropdown.style.bottom = 'auto'
+            dropdown.style.maxHeight = `${spaceBelow - verticalOffset}px`
+        }
+
+        dropdown.scrollTop = savedScrollTop
+    }
+
+    function handleScroll(event) {
+        // Ignore scrolls originating inside the dropdown's own list — only
+        // reposition when the page/ancestors scroll the trigger.
+        if (dropdownRef.value?.contains(event.target)) return
+        calculateDropdownPosition()
+    }
+
+    // Scroll AND resize are wired off `isOpen`: a closed dropdown has nothing to
+    // reposition, and leaving a resize listener registered for the component's
+    // whole lifetime forces an offsetHeight reflow on every (hidden) dropdown on
+    // every resize tick — needless layout thrash that scales with field count.
+    watch(isOpenRef, (nowOpen) => {
+        if (nowOpen) {
+            window.addEventListener('scroll', handleScroll, { capture: true, passive: true })
+            window.addEventListener('resize', calculateDropdownPosition)
+        } else {
+            window.removeEventListener('scroll', handleScroll, { capture: true })
+            window.removeEventListener('resize', calculateDropdownPosition)
+        }
+    })
+
+    onUnmounted(() => {
+        window.removeEventListener('resize', calculateDropdownPosition)
+        window.removeEventListener('scroll', handleScroll, { capture: true })
+    })
+
+    return { calculateDropdownPosition }
+}