feat(select): scrollable features, and config option

Author: thejackshelton

apps/website/src/routes/docs/headless/select/examples/group.tsx

@@ -10,10 +10,8 @@ import {
 } from '@qwik-ui/headless';
 
 export default component$(() => {
-  const usersSig = useSignal<string[]>(['Tim', 'Ryan', 'Jim', 'Jessie', 'Abby']);
-  const animalsSig = useSignal<string[]>(['Dog', 'Cat', 'Bird', 'Fish', 'Snake']);
-  // const animalId = useId();
-  // const usersId = useId();
+  const usersSig = useSignal<string[]>(['Tim', 'Ryan', 'Jim', 'Abby']);
+  const animalsSig = useSignal<string[]>(['Dog', 'Cat', 'Bird']);
 
   return (
     <Select class="relative min-w-40">

apps/website/src/routes/docs/headless/select/examples/scrollable.tsx

@@ -0,0 +1,47 @@
+import { component$, useSignal } from '@builder.io/qwik';
+import {
+  Select,
+  SelectListbox,
+  SelectOption,
+  SelectTrigger,
+  SelectValue,
+  SelectGroup,
+  SelectLabel,
+} from '@qwik-ui/headless';
+
+export default component$(() => {
+  const usersSig = useSignal<string[]>(['Tim', 'Ryan', 'Jim', 'Jessie', 'Abby']);
+  const animalsSig = useSignal<string[]>(['Dog', 'Cat', 'Bird', 'Fish', 'Snake']);
+
+  return (
+    <Select class="relative min-w-40">
+      <SelectTrigger class="w-full border-2 border-dashed border-red-400">
+        <SelectValue placeholder="Select an option" />
+      </SelectTrigger>
+      <SelectListbox class="absolute z-10 max-h-60 w-full overflow-y-auto border-2 border-dashed border-green-400 bg-slate-900 p-2">
+        <SelectGroup>
+          <SelectLabel class="text-sm text-slate-400">People</SelectLabel>
+          {usersSig.value.map((user) => (
+            <SelectOption
+              class="border-dashed border-blue-400 data-[highlighted]:border-2"
+              key={user}
+            >
+              {user}
+            </SelectOption>
+          ))}
+        </SelectGroup>
+        <SelectGroup>
+          <SelectLabel class="text-sm text-slate-400">Animals</SelectLabel>
+          {animalsSig.value.map((animal) => (
+            <SelectOption
+              class="border-dashed border-blue-400 data-[highlighted]:border-2"
+              key={animal}
+            >
+              {animal}
+            </SelectOption>
+          ))}
+        </SelectGroup>
+      </SelectListbox>
+    </Select>
+  );
+});

apps/website/src/routes/docs/headless/select/index.mdx

@@ -70,6 +70,14 @@ This element is used to create a drop-down list, it's often used in a form, to c
   <Showcase name="group" />
 </div>
 
+## Scrolling
+
+<div data-testid="select-scroll-test">
+  <Showcase name="scrollable" />
+</div>
+
+> Qwik UI does not provide virtual scrolling. However, we have found a [Qwik community member's package](https://github.com/literalpie/qwik-virtual-scroll) that has an implementation of virtual scrolling for Qwik based on [Tanstack Virtual](https://github.com/TanStack/virtual).
+
 ## Building blocks
 
 <CodeSnippet name="building-blocks" />

apps/website/src/routes/docs/headless/select/select.spec.ts

@@ -569,6 +569,21 @@ test.describe('Keyboard Behavior', () => {
       await expect(highlightedOpt).toContainText('dog', { ignoreCase: true });
     });
   });
+
+  test(`GIVEN an open select with multiple groups and a scrollable listbox
+        AND the last option is not visible
+        WHEN the end key is pressed
+        THEN the last option should be visible`, async ({ page }) => {
+    const { getTrigger, getRoot, openListbox } = await setup(page, 'select-scroll-test');
+
+    await openListbox('Enter');
+
+    await getTrigger().focus();
+    await getTrigger().press('End');
+    const lastOption = getRoot().getByRole('option', { includeHidden: false }).last();
+
+    await expect(lastOption).toBeInViewport();
+  });
 });
 
 test.describe('Disabled', () => {

packages/kit-headless/src/components/select/notes.md

@@ -35,7 +35,7 @@ What do they all have in common? How do people use them? What are the most impor
     - [x] Grouped options
     - [x] Typeahead support (user typing / filter)
     - [ ] RTL support
-    - [ ] Scrollable
+    - [x] Scrollable
     - [ ] Aria (controls, roles, etc)
 
 ## Props:

packages/kit-headless/src/components/select/select-context.ts

@@ -19,6 +19,9 @@ export type SelectContext = {
   highlightedIndexSig: Signal<number | null>;
   isListboxOpenSig: Signal<boolean>;
   selectedIndexSig: Signal<number | null>;
+
+  // user configurable
+  scrollOptions?: ScrollIntoViewOptions;
 };
 
 export const groupContextId = createContextId<GroupContext>('Select-Group');

packages/kit-headless/src/components/select/select-option.tsx

@@ -9,6 +9,7 @@ import {
   useComputed$,
 } from '@builder.io/qwik';
 import SelectContextId from './select-context';
+import { isServer } from '@builder.io/qwik/build';
 
 export type SelectOptionProps = PropsOf<'li'> & {
   index?: number;
@@ -52,6 +53,36 @@ export const SelectOption = component$<SelectOptionProps>((props) => {
     }
   });
 
+  useTask$(function scrollableTask({ track, cleanup }) {
+    track(() => context.highlightedIndexSig.value);
+
+    if (isServer) return;
+
+    let observer: IntersectionObserver;
+
+    const checkVisibility = (entries: IntersectionObserverEntry[]) => {
+      const [entry] = entries;
+
+      // if the option is not visible, scroll it into view
+      if (isHighlightedSig.value && !entry.isIntersecting) {
+        optionRef.value?.scrollIntoView(context.scrollOptions);
+      }
+    };
+
+    cleanup(() => observer?.disconnect());
+
+    if (typeof window !== 'undefined') {
+      observer = new IntersectionObserver(checkVisibility, {
+        root: context.listboxRef.value,
+        threshold: 1.0,
+      });
+
+      if (optionRef.value) {
+        observer.observe(optionRef.value);
+      }
+    }
+  });
+
   return (
     <li
       {...rest}

packages/kit-headless/src/components/select/select.tsx

@@ -26,6 +26,8 @@ export type SelectProps = PropsOf<'div'> & {
 
   onChange$?: QRL<() => void>;
   onOpenChange$?: QRL<() => void>;
+
+  scrollOptions?: ScrollIntoViewOptions;
 };
 
 /* root component in select-inline.tsx */
@@ -56,6 +58,10 @@ export const SelectImpl = component$<SelectProps>((props) => {
   const selectedIndexSig = useSignal<number | null>(props._valuePropIndex ?? null);
   const highlightedIndexSig = useSignal<number | null>(props._valuePropIndex ?? null);
   const isListboxOpenSig = useSignal<boolean>(false);
+  const scrollOptions = props.scrollOptions ?? {
+    behavior: 'instant',
+    block: 'nearest',
+  };
 
   // Maps are apparently great for this index accessing. Will learn more about them this week and refactor this to have a more consistent API and eliminate redundancy / duplication.
   useTask$(function controlledValueTask({ track }) {
@@ -93,6 +99,7 @@ export const SelectImpl = component$<SelectProps>((props) => {
     highlightedIndexSig,
     isListboxOpenSig,
     selectedIndexSig,
+    scrollOptions,
   };
 
   useContextProvider(SelectContextId, context);