feat(select): initial form logic

Author: thejackshelton

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

@@ -0,0 +1,37 @@
+import { component$, useStyles$ } from '@builder.io/qwik';
+import {
+  Select,
+  SelectListbox,
+  SelectOption,
+  SelectPopover,
+  SelectTrigger,
+  SelectValue,
+} from '@qwik-ui/headless';
+import styles from '../snippets/select.css?inline';
+
+export default component$(() => {
+  useStyles$(styles);
+  const users = ['Tim', 'Ryan', 'Jim', 'Jessie', 'Abby'];
+
+  return (
+    <form preventdefault:submit>
+      <Select required class="select" aria-label="hero">
+        <SelectTrigger class="select-trigger">
+          <SelectValue placeholder="Select an option" />
+        </SelectTrigger>
+        <SelectPopover class="select-popover">
+          <SelectListbox class="select-listbox">
+            {users.map((user) => (
+              <SelectOption key={user}>{user}</SelectOption>
+            ))}
+          </SelectListbox>
+        </SelectPopover>
+      </Select>
+      <label style={{ display: 'flex', flexDirection: 'column' }}>
+        Your favorite cat name
+        <input />
+      </label>
+      <button type="submit">Submit my form!</button>
+    </form>
+  );
+});

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

@@ -11,9 +11,7 @@ import { statusByComponent } from '~/_state/component-statuses';
 
 Reveals a list of options to choose from, often triggered by a button.
 
-<div data-testid="select-hero-test">
-  <Showcase name="hero" />
-</div>
+<Showcase name="hero" />
 
 ## ✨ Features
 
@@ -137,9 +135,7 @@ You are in full control of how the data is rendered. Map over the data, or rende
 
 ### Passing a distinct value
 
-<div data-testid="select-option-value-test">
-  <Showcase name="option-value" />
-</div>
+<Showcase name="option-value" />
 
 Sometimes we want to display one thing to the user, but pass another value to the option.
 
@@ -149,9 +145,7 @@ By adding the `value` prop to the `<SelectOption />` component, we can pass a di
 
 ### Handling selection changes
 
-<div data-testid="select-change-test">
-  <Showcase name="change-value" />
-</div>
+<Showcase name="change-value" />
 
 We can listen to changes in the selected value by using the `onChange$` prop. It provides an argument that is the new selected value.
 
@@ -163,9 +157,7 @@ We can select an initial uncontrolled value by passing the `value` prop to the `
 
 ### Uncontrolled / Initial value
 
-<div data-testid="select-uncontrolled-test">
-  <Showcase name="uncontrolled" />
-</div>
+<Showcase name="uncontrolled" />
 
 The above example passes one of the option values "Jessie" as the initial value. As a result, the matching value is selected and focused.
 
@@ -175,9 +167,7 @@ The above example passes one of the option values "Jessie" as the initial value.
 
 We can pass reactive state by using the `bind:value` prop to the `<Select />` root component.
 
-<div data-testid="select-controlled-test">
-  <Showcase name="controlled" />
-</div>
+<Showcase name="controlled" />
 
 `bind:value` is a signal prop, it allows us to programmatically control the selected value of the select component.
 
@@ -187,19 +177,15 @@ We can pass reactive state by using the `bind:value` prop to the `<Select />` ro
 
 To combine some of our previous knowledge, let's use the `onChange$` handler and `bind:value` prop in tandem.
 
-<div data-testid="select-controlled-value-test">
-  <Showcase name="controlled-value" />
-</div>
+<Showcase name="controlled-value" />
 
 In the above example, we can programmatically change the selected value by clicking on the "Change to Abby" button.
 
 This allows us to update the signal value and trigger the `onChange$` handler.
 
 ### Disabled options
 
-<div data-testid="select-disabled-test">
-  <Showcase name="disabled" />
-</div>
+<Showcase name="disabled" />
 
 Options can be disabled by adding the `disabled` prop to the `<SelectOption />` component.
 
@@ -209,9 +195,7 @@ Disabled options are not selectable or focusable. They are also skipped when usi
 
 A common use case is the addition of options dynamically. For example, an infinite scrolling list of users.
 
-<div data-testid="select-add-users-test">
-  <Showcase name="add-users" />
-</div>
+<Showcase name="add-users" />
 
 Clicking the `Add Users` button adds a couple new users mapped to the list. Taking this further, we could grab more data from the server and add it to the list, or even hitting a database to get more users.
 
@@ -221,9 +205,7 @@ Clicking the `Add Users` button adds a couple new users mapped to the list. Taki
 
 The select offers a typeahead feature that allows users to quickly find options by typing.
 
-<div data-testid="select-typeahead-test">
-  <Showcase name="typeahead" />
-</div>
+<Showcase name="typeahead" />
 
 It reduces the need to scroll through the available options. Typeahead is particularly handy for expected data sets, such as a list of countries.
 
@@ -233,29 +215,23 @@ It reduces the need to scroll through the available options. Typeahead is partic
 
 We may want to handle the open / close of the listbox. For example, we may want to show a loading indicator when the listbox is open.
 
-<div data-testid="select-open-change-test">
-  <Showcase name="open-change" />
-</div>
+<Showcase name="open-change" />
 
 To do that, we can use the `onOpenChange$` prop. A parameter is passed to the handler, which is a boolean indicating whether the listbox is open or closed.
 
 ### Looping
 
 To loop through the options, we can use the `loop` boolean prop on the `<Select />` root component.
 
-<div data-testid="select-loop-test">
-  <Showcase name="loop" />
-</div>
+<Showcase name="loop" />
 
 - Pressing the down arrow key will move focus to the first option in the list.
 
 - Pressing the up arrow key will move focus to the last option in the list.
 
 ### Grouped options
 
-<div data-testid="select-group-test">
-  <Showcase name="group" />
-</div>
+<Showcase name="group" />
 
 The `<SelectGroup />` and `<SelectLabel />` components are used to group and label options.
 
@@ -265,9 +241,7 @@ Wrap the options in a group, add a Label, and you're good to go!
 
 Because focus remains on the select trigger when the listbox is open, it's important to handle scrolling in the listbox.
 
-<div data-testid="select-scroll-test">
-  <Showcase name="scrollable" />
-</div>
+<Showcase name="scrollable" />
 
 The native `scrollIntoView` method is used to scroll the options into view when the user highlights an option.
 
@@ -279,16 +253,18 @@ To customize the scroll behavior, add the `scrollOptions` prop to the `<Select /
 
 We can provide a custom placeholder to the `<SelectValue />` component by adding the `placeholder` prop.
 
-<div data-testid="select-wrong-value-test">
-  <Showcase name="wrong-value" />
-</div>
+<Showcase name="wrong-value" />
 
 When a value is not selected, the placeholder is displayed. The example above shows a placeholder fallback when the value is not selected.
 
 The consumer misspelled the the value, and so the fallback is displayed.
 
 > Side note: would appreciate some help on TypeScript to make misspelled option values a thing of the past. Ideally, a union of the user's passed in options.
 
+## Forms
+
+<Showcase name="form" />
+
 ## Example CSS
 
 Every code example uses the following CSS:

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

@@ -9,12 +9,13 @@
 import { component$, useContext } from '@builder.io/qwik';
 import { Opt } from './select-inline';
 import SelectContextId from './select-context';
+import { VisuallyHidden } from '../../utils/visually-hidden';
 
 export type AriaHiddenSelectProps = {
   /**
    * Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete).
    */
-  autoComplete?: string;
+  autoComplete?: AutoFill;
 
   /** The text label for the select. */
   label?: string;
@@ -24,40 +25,46 @@ export type AriaHiddenSelectProps = {
 
   /** Sets the disabled state of the select and input. */
   disabled?: boolean;
+
+  required?: boolean;
 };
 
 export type SelectDataProps = {
   options: Opt[] | undefined;
 };
 
-// export function useHiddenSelect(props: AriaHiddenSelectProps) {
-//   const { autoComplete, name, disabled } = props;
-// }
-
 export const HiddenSelect = component$(
   (props: AriaHiddenSelectProps & SelectDataProps) => {
-    const { label, options } = props;
+    const { label, options, autoComplete, name, required, disabled } = props;
     const context = useContext(SelectContextId);
 
     // TODO: make conditional logic to show either input or select based on the size of the options.
     return (
-      <div>
-        <label>
-          {label}
-          <select>
-            <option />
-            {options?.map((opt: Opt) => (
-              <option
-                value={opt.value}
-                selected={context.selectedIndexSig.value === opt.index}
-                key={opt.value}
-              >
-                {opt.displayValue}
-              </option>
-            ))}
-          </select>
-        </label>
-      </div>
+      <VisuallyHidden>
+        <div aria-hidden="true">
+          <label>
+            {label}
+            <select
+              tabIndex={-1}
+              autocomplete={autoComplete}
+              disabled={disabled}
+              required={required}
+              name={name}
+            >
+              <option />
+              {options?.map((opt: Opt) => (
+                <option
+                  value={opt.value}
+                  selected={context.selectedIndexSig.value === opt.index}
+                  key={opt.value}
+                >
+                  {opt.displayValue}
+                </option>
+              ))}
+            </select>
+          </label>
+        </div>
+      </VisuallyHidden>
     );
   },
 );

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

@@ -103,6 +103,7 @@ export const SelectOption = component$<SelectOptionProps>((props) => {
       data-selected={isSelectedSig.value ? '' : undefined}
       data-highlighted={isHighlightedSig.value ? '' : undefined}
       data-disabled={disabled ? '' : undefined}
+      data-option
       role="option"
     >
       <Slot />

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

@@ -15,22 +15,24 @@ export function createTestDriver<T extends DriverLocator>(rootLocator: T) {
     return getRoot().getByRole('listbox');
   };
 
-  const getOptions = (options?: { evenIfHidden?: boolean }) => {
-    return getRoot().getByRole('option', { includeHidden: options?.evenIfHidden });
+  // we use data-option so that it doesn't grab native select options.
+  const getOptions = () => {
+    return getRoot().locator('[data-option]');
   };
 
-  const getOptionsLength = async (options?: { evenIfHidden?: boolean }) => {
-    return getOptions({ evenIfHidden: options?.evenIfHidden }).count();
+  const getOptionsLength = async () => {
+    return getOptions().count();
   };
 
   const getOptionAt = (index: number | 'last') => {
     if (index === 'last') return getOptions().last();
     return getOptions().nth(index);
+    //
   };
 
   const getHiddenOptionAt = (index: number | 'last') => {
-    if (index === 'last') return getOptions({ evenIfHidden: true }).last();
-    return getOptions({ evenIfHidden: true }).nth(index);
+    if (index === 'last') return getOptions().last();
+    return getOptions().nth(index);
   };
 
   const getValueElement = () => {

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

@@ -105,7 +105,7 @@ test.describe('Mouse Behavior', () => {
 
     await page.getByRole('button', { name: 'Add Users' }).click();
 
-    await expect(d.getOptions({ evenIfHidden: true })).toHaveCount(8);
+    await expect(d.getOptions()).toHaveCount(8);
 
     await d.openListbox('click');
     const expectedValue = 'Bob';
@@ -608,11 +608,9 @@ test.describe('Keyboard Behavior', () => {
       // ideally want to refactor this so that even if the test example is changed, the test will still pass, getting it more programmatically.
       const { getRoot, getTrigger } = await setup(page, 'hero');
       await getTrigger().focus();
-      await getTrigger().press('j');
-      const firstJOption = getRoot().getByRole('option', {
-        name: 'Jim',
-        includeHidden: true,
-      });
+      const char = 'j';
+      await getTrigger().press(char);
+      const firstJOption = getRoot().locator('li', { hasText: char }).nth(0);
       await expect(firstJOption).toHaveAttribute('aria-selected', 'true');
       await expect(firstJOption).toHaveAttribute('data-highlighted');
     });