@sit-onyx/headless 0.1.0-alpha.7 → 1.0.0-alpha.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/headless",
   "description": "Headless composables for Vue",
-  "version": "0.1.0-alpha.7",
+  "version": "1.0.0-alpha.11",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",

package/src/composables/comboBox/SelectOnlyCombobox.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import { createComboBox } from "./createComboBox";
+
+const options = ["a", "b", "c", "d"];
+const isExpanded = ref(false);
+const comboboxRef = ref<HTMLElement>();
+const activeOption = ref("");
+const selectedOption = ref("");
+const selectedIndex = computed<number | undefined>(() => {
+  const index = options.indexOf(activeOption.value);
+  return index !== -1 ? index : undefined;
+});
+
+const onActivateFirst = () => (activeOption.value = options[0]);
+const onActivateLast = () => (activeOption.value = options[options.length - 1]);
+const onActivateNext = () => {
+  if (selectedIndex.value === undefined) {
+    return onActivateFirst();
+  }
+  activeOption.value = options[selectedIndex.value + (1 % (options.length - 1))];
+};
+const onActivatePrevious = () => (activeOption.value = options[(selectedIndex.value ?? 0) - 1]);
+const onSelect = (newValue: string) => (selectedOption.value = newValue);
+const onToggle = () => (isExpanded.value = !isExpanded.value);
+const onTypeAhead = () => {};
+
+const comboBox = createComboBox({
+  inputValue: selectedOption,
+  autocomplete: "none",
+  label: "some label",
+  listLabel: "List",
+  activeOption,
+  isExpanded,
+  templateRef: comboboxRef,
+  onToggle,
+  onTypeAhead,
+  onActivateFirst,
+  onActivateLast,
+  onActivateNext,
+  onActivatePrevious,
+  onSelect,
+});
+
+const {
+  elements: { input, listbox, button, option },
+} = comboBox;
+
+defineExpose({ comboBox });
+</script>
+
+<template>
+  <div ref="comboboxRef">
+    <input v-bind="input" readonly @keydown.arrow-down="isExpanded = true" />
+
+    <button v-bind="button">
+      <template v-if="isExpanded">⬆️</template>
+      <template v-else>⬇️</template>
+    </button>
+    <ul v-bind="listbox" :class="{ hidden: !isExpanded }" style="width: 400px">
+      <li
+        v-for="e in options"
+        :key="e"
+        v-bind="option({ value: e, label: e, disabled: false, selected: e === selectedOption })"
+        :class="{ active: e === activeOption }"
+      >
+        {{ e }}
+      </li>
+    </ul>
+  </div>
+</template>
+
+<style>
+.hidden {
+  display: none;
+}
+.active {
+  outline: 2px solid black;
+}
+[aria-selected="true"] {
+  background-color: red;
+}
+</style>

package/src/composables/comboBox/TestCombobox.ct.tsx

@@ -1,6 +1,7 @@
 import { test } from "@playwright/experimental-ct-vue";
 import TestCombobox from "./TestCombobox.vue";
-import { comboboxTesting } from "./createComboBox.ct";
+import { comboboxTesting, comboboxSelectOnlyTesting } from "./createComboBox.ct";
+import SelectOnlyCombobox from "./SelectOnlyCombobox.vue";
 
 test("combobox", async ({ mount, page }) => {
   await mount(<TestCombobox />);
@@ -11,3 +12,13 @@ test("combobox", async ({ mount, page }) => {
 
   await comboboxTesting(page, listbox, combobox, button, options);
 });
+
+test("select only combobox", async ({ mount, page }) => {
+  await mount(<SelectOnlyCombobox />);
+  const listbox = page.getByRole("listbox");
+  const combobox = page.getByRole("combobox");
+
+  await comboboxSelectOnlyTesting(page, listbox, combobox, (loc) =>
+    loc.evaluate((e) => e.classList.contains("active")),
+  );
+});

package/src/composables/comboBox/TestCombobox.vue

@@ -2,33 +2,43 @@
 import { computed, ref } from "vue";
 import { createComboBox } from "./createComboBox";
 
-const elements = ["a", "b", "c", "d"];
+const options = ["a", "b", "c", "d"];
 const isExpanded = ref(false);
-const inputValue = ref("");
+const searchTerm = ref("");
+const comboboxRef = ref<HTMLElement>();
 const activeOption = ref("");
+const filteredOptions = computed(() => options.filter((v) => v.includes(searchTerm.value)));
 const selectedIndex = computed<number | undefined>(() => {
-  const index = elements.indexOf(activeOption.value);
+  const index = filteredOptions.value.indexOf(activeOption.value);
   return index !== -1 ? index : undefined;
 });
 
-const onActivateFirst = () => (activeOption.value = elements[0]);
-const onActivateLast = () => (activeOption.value = elements[elements.length - 1]);
+const onActivateFirst = () => (activeOption.value = filteredOptions.value[0]);
+const onActivateLast = () =>
+  (activeOption.value = filteredOptions.value[filteredOptions.value.length - 1]);
 const onActivateNext = () => {
   if (selectedIndex.value === undefined) {
     return onActivateFirst();
   }
-  activeOption.value = elements[selectedIndex.value + (1 % (elements.length - 1))];
+  activeOption.value =
+    filteredOptions.value[selectedIndex.value + (1 % (filteredOptions.value.length - 1))];
 };
-const onActivatePrevious = () => (activeOption.value = elements[(selectedIndex.value ?? 0) - 1]);
-const onSelect = (newValue: string) => (inputValue.value = newValue);
+const onActivatePrevious = () =>
+  (activeOption.value = filteredOptions.value[(selectedIndex.value ?? 0) - 1]);
+const onSelect = (newValue: string) => (searchTerm.value = newValue);
+const onAutocomplete = (input: string) => (searchTerm.value = input);
 const onToggle = () => (isExpanded.value = !isExpanded.value);
 
 const comboBox = createComboBox({
+  inputValue: searchTerm,
+  autocomplete: "list",
+  label: "some label",
   listLabel: "List",
   activeOption,
-  inputValue,
   isExpanded,
+  templateRef: comboboxRef,
   onToggle,
+  onAutocomplete,
   onActivateFirst,
   onActivateLast,
   onActivateNext,
@@ -37,29 +47,23 @@ const comboBox = createComboBox({
 });
 
 const {
-  elements: { input, label, listBox, button, option },
+  elements: { input, listbox, button, option },
 } = comboBox;
 
 defineExpose({ comboBox });
 </script>
+
 <template>
-  <div>
-    <label v-bind="label">
-      some label:
-      <input
-        v-bind="input"
-        @keydown.arrow-down="isExpanded = true"
-        @keydown.esc="isExpanded = false"
-      />
-    </label>
+  <div ref="comboboxRef">
+    <input v-bind="input" @keydown.arrow-down="isExpanded = true" />
 
     <button v-bind="button">
       <template v-if="isExpanded">⬆️</template>
       <template v-else>⬇️</template>
     </button>
-    <ul v-bind="listBox" :class="{ hidden: !isExpanded }" style="width: 400px">
+    <ul v-bind="listbox" :class="{ hidden: !isExpanded }" style="width: 400px">
       <li
-        v-for="e in elements"
+        v-for="e in filteredOptions"
         :key="e"
         v-bind="option({ value: e, label: e, disabled: false })"
         :style="{ 'background-color': e === activeOption ? 'red' : undefined }"
@@ -69,6 +73,7 @@ defineExpose({ comboBox });
     </ul>
   </div>
 </template>
+
 <style>
 .hidden {
   display: none;

package/src/composables/comboBox/createComboBox.ct.ts

@@ -1,11 +1,42 @@
-import { expect } from "@playwright/experimental-ct-vue";
+import { expect, test } from "@playwright/experimental-ct-vue";
 import type { Locator, Page } from "@playwright/test";
 
+const expectToOpen = async (
+  keyCombo: string,
+  combobox: Locator,
+  listbox: Locator,
+  checkActive?: () => Promise<boolean>,
+) => {
+  await closeCombobox(combobox, listbox);
+  await combobox.press(keyCombo);
+  await expect(listbox, `Listbox should be opened after pressing ${keyCombo}.`).toBeVisible();
+  if (checkActive) {
+    const active = await checkActive();
+    expect(active, "Given option should be active").toBeTruthy();
+  }
+};
+
+const expectToClose = async (
+  keyCombo: string,
+  combobox: Locator,
+  listbox: Locator,
+  selectedLocator?: () => Locator,
+) => {
+  await openCombobox(combobox, listbox);
+  await combobox.press(keyCombo);
+  await expect(listbox, `Listbox should be closed after pressing ${keyCombo}.`).toBeHidden();
+  await expect(combobox).toBeFocused();
+  await openCombobox(combobox, listbox);
+  if (selectedLocator) {
+    await expectToBeSelected(selectedLocator());
+  }
+};
+
 /**
  * Test an implementation of the combobox based on https://w3c.github.io/aria/#combobox
  */
 export const comboboxTesting = async (
-  page: Page,
+  _page: Page,
   listbox: Locator,
   combobox: Locator,
   button: Locator,
@@ -56,8 +87,7 @@ export const comboboxTesting = async (
 
   // open and select first option
   await combobox.focus();
-  await page.keyboard.press("ArrowDown");
-  await page.keyboard.press("ArrowDown");
+  expectToOpen("ArrowDown", combobox, listbox);
 
   const firstId = await (await firstElement.elementHandle())!.getAttribute("id");
   expect(typeof firstId).toBe("string");
@@ -69,4 +99,70 @@ export const comboboxTesting = async (
     combobox,
     "When a descendant of the popup element is active, authors MAY ensure that the focus remains on the combobox element",
   ).toBeFocused();
+
+  // Single Select Pattern
+};
+
+const closeCombobox = async (combobox: Locator, listbox: Locator) => {
+  await combobox.press("Escape");
+  return expect(listbox, "Listbox should be collapsed again").toBeHidden();
+};
+
+const openCombobox = async (combobox: Locator, listbox: Locator) => {
+  await combobox.press("Home");
+  return expect(listbox, "Listbox should be open again").toBeVisible();
+};
+
+const expectToBeSelected = async (selectedItem: Locator) =>
+  expect(selectedItem, "Option should be selected").toHaveAttribute("aria-selected", "true");
+
+export type CheckLocator = (option: Locator) => Promise<boolean>;
+
+/**
+ * Test an implementation of the combobox based on https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/
+ */
+export const comboboxSelectOnlyTesting = async (
+  page: Page,
+  listbox: Locator,
+  combobox: Locator,
+  isActive: CheckLocator,
+) => {
+  await expect(listbox, "Initial state of a combobox is collapsed.").toBeHidden();
+
+  await combobox.focus();
+
+  await test.step("Test opening keys", async () => {
+    await expectToOpen("ArrowUp", combobox, listbox, () =>
+      isActive(page.getByRole("option").first()),
+    );
+    await expectToOpen("Alt+ArrowDown", combobox, listbox);
+    await expectToOpen("Space", combobox, listbox);
+    await expectToOpen("Enter", combobox, listbox);
+    await expectToOpen("Home", combobox, listbox, () => isActive(page.getByRole("option").first()));
+    await expectToOpen("End", combobox, listbox, () => isActive(page.getByRole("option").last()));
+    await expectToOpen("ArrowDown", combobox, listbox);
+    await expectToOpen("a", combobox, listbox);
+  });
+
+  await test.step("Selecting with Enter", async () => {
+    await expectToClose("Enter", combobox, listbox, () => page.getByRole("option").first());
+    await expectToClose(" ", combobox, listbox, () => page.getByRole("option").first());
+    await expectToClose("Escape", combobox, listbox, () => page.getByRole("option").first());
+  });
+
+  await test.step("Activating with End", async () => {
+    await openCombobox(combobox, listbox);
+    await combobox.press("End");
+    const active = await isActive(listbox.getByRole("option").last());
+    expect(active, "Given option should be active").toBeTruthy();
+    await expect(combobox).toBeFocused();
+  });
+
+  await test.step("Activating with Home", async () => {
+    await openCombobox(combobox, listbox);
+    await combobox.press("Home");
+    const active = await isActive(listbox.getByRole("option").first());
+    expect(active, "Given option should be active").toBeTruthy();
+    await expect(combobox).toBeFocused();
+  });
 };

package/src/composables/comboBox/createComboBox.ts

@@ -1,16 +1,42 @@
-import { computed, ref, type MaybeRef, type Ref } from "vue";
+import { computed, unref, type MaybeRef, type Ref } from "vue";
 import { createBuilder } from "../../utils/builder";
 import { createId } from "../../utils/id";
+import { isPrintableCharacter, wasKeyPressed, type PressedKey } from "../../utils/keyboard";
 import {
   createListbox,
   type CreateListboxOptions,
   type ListboxValue,
 } from "../listbox/createListbox";
+import { useOutsideClick } from "../outsideClick";
+import { useTypeAhead } from "../typeAhead";
+
+export type ComboboxAutoComplete = "none" | "list" | "both";
+
+export const OPENING_KEYS: PressedKey[] = ["ArrowDown", "ArrowUp", " ", "Enter", "Home", "End"];
+export const CLOSING_KEYS: PressedKey[] = [
+  "Escape",
+  { key: "ArrowUp", altKey: true },
+  "Enter",
+  "Tab",
+];
+const SELECTING_KEYS_SINGLE: PressedKey[] = ["Enter", " "];
+const SELECTING_KEYS_MULTIPLE: PressedKey[] = ["Enter"];
+
+const isSelectingKey = (event: KeyboardEvent, isMultiselect?: boolean) => {
+  const selectingKeys = isMultiselect ? SELECTING_KEYS_MULTIPLE : SELECTING_KEYS_SINGLE;
+  return isKeyOfGroup(event, selectingKeys);
+};
+
+const isKeyOfGroup = (event: KeyboardEvent, group: PressedKey[]) =>
+  group.some((key) => wasKeyPressed(event, key));
 
 export type CreateComboboxOptions<
-  TValue extends ListboxValue = ListboxValue,
+  TValue extends ListboxValue,
+  TAutoComplete extends ComboboxAutoComplete,
   TMultiple extends boolean = false,
 > = {
+  autocomplete: MaybeRef<TAutoComplete>;
+  label: MaybeRef<string>;
   /**
    * Labels the listbox which displays the available options. E.g. the list label could be "Countries" for a combobox which is labelled "Country".
    */
@@ -18,33 +44,75 @@ export type CreateComboboxOptions<
   /**
    * The current value of the combobox. Is updated when an option from the controlled listbox is selected or by typing into it.
    */
-  inputValue: Ref<TValue | undefined>;
+  inputValue: Ref<string | undefined>;
   /**
    * Controls the opened/visible state of the associated pop-up. When expanded the activeOption can be controlled via the keyboard.
    */
-  isExpanded: Ref<boolean>;
+  isExpanded: MaybeRef<boolean>;
   /**
    * If expanded, the active option is the currently highlighted option of the controlled listbox.
    */
   activeOption: Ref<TValue | undefined>;
+  /**
+   * Template ref to the component root (required to close combobox on outside click).
+   */
+  templateRef: Ref<HTMLElement | undefined>;
   /**
    * Hook when the popover should toggle.
+   *
+   * @param preventFocus If `true`, the parent combobox should not be focused (e.g. on outside click).
    */
-  onToggle?: () => void;
-} & Pick<
-  CreateListboxOptions<TValue, TMultiple>,
-  "onActivateFirst" | "onActivateLast" | "onActivateNext" | "onActivatePrevious" | "onSelect"
->;
-
-// TODO: https://w3c.github.io/aria/#aria-autocomplete
-// TODO: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
-// TODO: button as optional
+  onToggle?: (preventFocus?: boolean) => void;
+  /**
+   * Hook when an option is (un-)selected.
+   */
+  onSelect?: (value: TValue) => void;
+  /**
+   * Hook when the first option should be activated.
+   */
+  onActivateFirst?: () => void;
+  /**
+   * Hook when the last option should be activated.
+   */
+  onActivateLast?: () => void;
+  /**
+   * Hook when the next option should be activated.
+   */
+  onActivateNext?: (currentValue: TValue) => void;
+  /**
+   * Hook when the previous option should be activated.
+   */
+  onActivatePrevious?: (currentValue: TValue) => void;
+} & (TAutoComplete extends Exclude<ComboboxAutoComplete, "none">
+  ? { onAutocomplete: (input: string) => void }
+  : { onAutocomplete?: undefined }) &
+  (TAutoComplete extends "none"
+    ? { onTypeAhead: (input: string) => void }
+    : { onTypeAhead?: undefined }) &
+  Pick<
+    CreateListboxOptions<TValue, TMultiple>,
+    | "onActivateFirst"
+    | "onActivateLast"
+    | "onActivateNext"
+    | "onActivatePrevious"
+    | "onSelect"
+    | "multiple"
+  >;
 
 export const createComboBox = createBuilder(
-  <TValue extends ListboxValue = ListboxValue, TMultiple extends boolean = false>({
-    listLabel,
+  <
+    TValue extends ListboxValue,
+    TAutoComplete extends ComboboxAutoComplete,
+    TMultiple extends boolean = false,
+  >({
     inputValue,
-    isExpanded,
+    autocomplete: autocompleteRef,
+    onAutocomplete,
+    onTypeAhead,
+    multiple: multipleRef,
+    label,
+    listLabel,
+    isExpanded: isExpandedRef,
     activeOption,
     onToggle,
     onSelect,
@@ -52,49 +120,43 @@ export const createComboBox = createBuilder(
     onActivateLast,
     onActivateNext,
     onActivatePrevious,
-  }: CreateComboboxOptions<TValue, TMultiple>) => {
-    const inputValid = ref(true);
+    templateRef,
+  }: CreateComboboxOptions<TValue, TAutoComplete, TMultiple>) => {
     const controlsId = createId("comboBox-control");
-    const labelId = createId("comboBox-label");
+
+    const autocomplete = computed(() => unref(autocompleteRef));
+    const isExpanded = computed(() => unref(isExpandedRef));
+    const multiple = computed(() => unref(multipleRef));
 
     const handleInput = (event: Event) => {
       const inputElement = event.target as HTMLInputElement;
-      inputValue.value = inputElement.value as TValue;
-      inputValid.value = inputElement.validity.valid;
+
+      if (autocomplete.value !== "none") {
+        onAutocomplete?.(inputElement.value);
+      }
     };
 
-    const handleBlur = () => {
-      if (isExpanded.value) {
+    const typeAhead = useTypeAhead((inputString) => onTypeAhead?.(inputString));
+
+    const handleSelect = (value: TValue) => {
+      onSelect?.(value);
+      if (!unref(multiple)) {
         onToggle?.();
       }
     };
 
-    const handleKeydown = (event: KeyboardEvent) => {
-      if (!isExpanded.value) {
-        return;
-      }
+    const handleNavigation = (event: KeyboardEvent) => {
       switch (event.key) {
-        case "Enter":
-          event.preventDefault();
-          if (activeOption.value) {
-            onSelect?.(activeOption.value);
-            inputValue.value = activeOption.value;
-          }
-          break;
-        case "Escape":
-          event.preventDefault();
-          onToggle?.();
-          break;
         case "ArrowUp":
           event.preventDefault();
-          if (!activeOption.value) {
+          if (activeOption.value == undefined) {
             return onActivateLast?.();
           }
           onActivatePrevious?.(activeOption.value);
           break;
         case "ArrowDown":
           event.preventDefault();
-          if (!activeOption.value) {
+          if (activeOption.value == undefined) {
             return onActivateFirst?.();
           }
           onActivateNext?.(activeOption.value);
@@ -110,30 +172,73 @@ export const createComboBox = createBuilder(
       }
     };
 
+    const handleKeydown = (event: KeyboardEvent) => {
+      if (!isExpanded.value && isKeyOfGroup(event, OPENING_KEYS)) {
+        onToggle?.();
+        if (event.key === " ") {
+          event.preventDefault();
+        }
+        if (event.key === "End") {
+          return onActivateLast?.();
+        }
+        return onActivateFirst?.();
+      }
+      if (isSelectingKey(event, multiple.value)) {
+        return handleSelect(activeOption.value!);
+      }
+      if (isExpanded.value && isKeyOfGroup(event, CLOSING_KEYS)) {
+        return onToggle?.();
+      }
+      if (autocomplete.value === "none" && isPrintableCharacter(event.key)) {
+        !isExpanded.value && onToggle?.();
+        return typeAhead(event);
+      }
+      if (autocomplete.value !== "none" && isPrintableCharacter(event.key)) {
+        !isExpanded.value && onToggle?.();
+        return;
+      }
+      return handleNavigation(event);
+    };
+
+    const autocompleteInput =
+      autocomplete.value !== "none"
+        ? {
+            "aria-autocomplete": autocomplete.value,
+            type: "text",
+          }
+        : null;
+
     const {
       elements: { option, group, listbox },
       internals: { getOptionId },
     } = createListbox({
       label: listLabel,
+      multiple,
       controlled: true,
       activeOption,
-      selectedOption: activeOption,
-      onSelect,
+      onSelect: handleSelect,
+    });
+
+    useOutsideClick({
+      queryComponent: () => templateRef.value,
+      onOutsideClick() {
+        if (!isExpanded.value) return;
+        onToggle?.(true);
+      },
     });
 
     return {
       elements: {
         option,
         group,
-        label: {
-          id: labelId,
-        },
         /**
          * The listbox associated with the combobox.
          */
-        listBox: computed(() => ({
+        listbox: computed(() => ({
           ...listbox.value,
           id: controlsId,
+          // preventDefault to not lose focus of the combobox
+          onMousedown: (e) => e.preventDefault(),
         })),
         /**
          * An input that controls another element, that can dynamically pop-up to help the user set the value of the input.
@@ -144,18 +249,19 @@ export const createComboBox = createBuilder(
           role: "combobox",
           "aria-expanded": isExpanded.value,
           "aria-controls": controlsId,
-          "aria-labelledby": labelId,
-          "aria-activedescendant": activeOption.value ? getOptionId(activeOption.value) : undefined,
+          "aria-label": unref(label),
+          "aria-activedescendant":
+            activeOption.value != undefined ? getOptionId(activeOption.value) : undefined,
           onInput: handleInput,
           onKeydown: handleKeydown,
-          onBlur: handleBlur,
+          ...autocompleteInput,
         })),
         /**
          * An optional button to control the visibility of the popup.
          */
         button: computed(() => ({
           tabindex: "-1",
-          onClick: onToggle,
+          onClick: () => onToggle?.(),
         })),
       },
     };

package/src/composables/listbox/TestListbox.vue

@@ -30,7 +30,6 @@ const {
   elements: { listbox, option: headlessOption },
 } = createListbox({
   label: "Test listbox",
-  selectedOption,
   activeOption,
   onSelect: (id) => {
     selectedOption.value = selectedOption.value === id ? undefined : id;

package/src/composables/listbox/createListbox.ts

@@ -5,23 +5,11 @@ import { useTypeAhead } from "../typeAhead";
 
 export type ListboxValue = string | number | boolean;
 
-export type ListboxModelValue<
-  TValue extends ListboxValue = ListboxValue,
-  TMultiple extends boolean = false,
-> = TMultiple extends true ? TValue[] : TValue;
-
-export type CreateListboxOptions<
-  TValue extends ListboxValue = ListboxValue,
-  TMultiple extends boolean = false,
-> = {
+export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends boolean = false> = {
   /**
    * Aria label for the listbox.
    */
   label: MaybeRef<string>;
-  /**
-   * Value of currently selected option.
-   */
-  selectedOption: Ref<ListboxModelValue<TValue, TMultiple> | undefined>;
   /**
    * Value of currently (visually) active option.
    */
@@ -58,15 +46,34 @@ export type CreateListboxOptions<
   /**
    * Hook when the first option starting with the given label should be activated.
    */
-  onTypeAhead?: (label: string) => void;
-};
+  onTypeAhead?: (key: string) => void;
+} & (
+  | {
+      /**
+       * Optional aria label for the listbox.
+       */
+      label?: MaybeRef<string>;
+      /**
+       * Wether the listbox is controlled from the outside, e.g. by a combobox.
+       * This disables keyboard events and makes the listbox not focusable.
+       */
+      controlled: true;
+    }
+  | {
+      /**
+       * Aria label for the listbox.
+       */
+      label: MaybeRef<string>;
+      controlled?: false;
+    }
+);
 
 /**
  * Composable for creating a accessibility-conform listbox.
  * For supported keyboard shortcuts, see: https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/
  */
 export const createListbox = createBuilder(
-  <TValue extends ListboxValue = ListboxValue, TMultiple extends boolean = false>(
+  <TValue extends ListboxValue, TMultiple extends boolean = false>(
     options: CreateListboxOptions<TValue, TMultiple>,
   ) => {
     const isMultiselect = computed(() => unref(options.multiple) ?? false);
@@ -103,7 +110,6 @@ export const createListbox = createBuilder(
         case " ":
           event.preventDefault();
           if (options.activeOption.value != undefined) {
-            // TODO: don't call onSelect if the option is disabled
             options.onSelect?.(options.activeOption.value);
           }
           break;
@@ -182,17 +188,18 @@ export const createListbox = createBuilder(
           return (data: {
             label: string;
             value: TValue;
-            selected?: boolean;
             disabled?: boolean;
+            selected?: boolean;
           }) => {
-            const isSelected = data.selected ?? false;
+            const selected = data.selected ?? false;
+
             return {
               id: getOptionId(data.value),
               role: "option",
               "aria-label": data.label,
-              "aria-checked": isMultiselect.value ? isSelected : undefined,
-              "aria-selected": !isMultiselect.value ? isSelected : undefined,
               "aria-disabled": data.disabled,
+              "aria-checked": isMultiselect.value ? selected : undefined,
+              "aria-selected": !isMultiselect.value ? selected : undefined,
               onClick: () => !data.disabled && options.onSelect?.(data.value),
             } as const;
           };

package/src/composables/menuButton/TestMenuButton.ct.tsx

@@ -0,0 +1,14 @@
+import { test } from "@playwright/experimental-ct-vue";
+import { menuButtonTesting } from "./createMenuButton.ct";
+import TestMenuButton from "./TestMenuButton.vue";
+
+test("menuButton", async ({ mount, page }) => {
+  await mount(<TestMenuButton />);
+
+  await menuButtonTesting({
+    page,
+    button: page.getByRole("button"),
+    menu: page.locator("ul"),
+    menuItems: await page.locator("li").all(),
+  });
+});

package/src/composables/menuButton/TestMenuButton.vue

@@ -0,0 +1,33 @@
+<script lang="ts" setup>
+import { createMenuButton } from "./createMenuButton";
+import { ref } from "vue";
+
+const items = Array.from({ length: 10 }, (_, index) => {
+  const id = index + 1;
+  return { label: `Item ${id}`, value: `/href-${id}` };
+});
+
+const activeItem = ref<string>();
+
+const {
+  elements: { button, menu, menuItem, listItem, flyout },
+  state: { isExpanded },
+} = createMenuButton({
+  onSelect: (value) => {
+    activeItem.value = value;
+  },
+});
+</script>
+
+<template>
+  <button v-bind="button">Toggle nav menu</button>
+  <div v-bind="flyout">
+    <ul v-show="isExpanded" v-bind="menu">
+      <li v-for="item in items" v-bind="listItem" :key="item.value" title="item">
+        <a v-bind="menuItem({ active: activeItem === item.value, value: item.value })">{{
+          item.label
+        }}</a>
+      </li>
+    </ul>
+  </div>
+</template>

package/src/composables/menuButton/createMenuButton.ct.ts

@@ -0,0 +1,54 @@
+import { expect } from "@playwright/experimental-ct-vue";
+import type { Locator, Page } from "@playwright/test";
+
+export type MenuButtonTestingOptions = {
+  /**
+   * Playwright page.
+   */
+  page: Page;
+  /**
+   * Locator for the button element.
+   */
+  button: Locator;
+  /**
+   * Menu, e.g. a `<ul>` element.
+   */
+  menu: Locator;
+  /**
+   * List items (at least 3).
+   */
+  menuItems: Locator[];
+};
+
+/**
+ * Playwright utility for executing accessibility testing for a navigation menu.
+ * Will check aria attributes and keyboard shortcuts as defined in https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-links.
+ */
+export const menuButtonTesting = async ({ button, menu }: MenuButtonTestingOptions) => {
+  const menuId = await menu.getAttribute("id");
+  expect(menuId).toBeDefined();
+  await expect(
+    button,
+    "navigation menu should have set the list ID to the aria-controls",
+  ).toHaveAttribute("aria-controls", menuId!);
+
+  await expect(
+    button,
+    'navigation menu should have an "aria-haspopup" attribute set to true',
+  ).toHaveAttribute("aria-haspopup", "true");
+
+  await expect(button).toBeVisible();
+
+  // ensure correct navigation menu aria attributes
+  await expect(
+    button,
+    'flyout menu must have an "aria-expanded" attribute set to false',
+  ).toHaveAttribute("aria-expanded", "false");
+
+  button.hover();
+
+  await expect(
+    button,
+    'flyout menu must have an "aria-expanded" attribute set to true',
+  ).toHaveAttribute("aria-expanded", "true");
+};

package/src/composables/menuButton/createMenuButton.ts

@@ -0,0 +1,69 @@
+import { computed, ref } from "vue";
+import { createBuilder } from "../../utils/builder";
+import { createId } from "../../utils/id";
+import { debounce } from "../../utils/timer";
+
+export type CreateMenuButtonOptions = {
+  /**
+   * Called when a menu item is selected (via mouse or keyboard).
+   */
+  onSelect: (value: string) => void;
+};
+
+export const createMenuButton = createBuilder((options: CreateMenuButtonOptions) => {
+  const menuId = createId("menu");
+  const buttonId = createId("menu-button");
+  const isExpanded = ref<boolean>(false);
+
+  /**
+   * Debounced expanded state that will only be toggled after a given timeout.
+   */
+  const updateDebouncedExpanded = debounce(
+    (expanded: boolean) => (isExpanded.value = expanded),
+    200,
+  );
+
+  const hoverEvents = computed(() => {
+    return {
+      onMouseover: () => updateDebouncedExpanded(true),
+      onMouseout: () => updateDebouncedExpanded(false),
+      onFocusin: () => (isExpanded.value = true),
+      onFocusout: () => (isExpanded.value = false),
+    };
+  });
+
+  return {
+    state: { isExpanded },
+    elements: {
+      button: computed(
+        () =>
+          ({
+            "aria-controls": menuId,
+            "aria-expanded": isExpanded.value,
+            "aria-haspopup": true,
+            id: buttonId,
+            ...hoverEvents.value,
+          }) as const,
+      ),
+      listItem: {
+        role: "none",
+      },
+      flyout: {
+        ...hoverEvents.value,
+      },
+      menu: {
+        id: menuId,
+        role: "menu",
+        "aria-labelledby": buttonId,
+      },
+      menuItem: (data: { active?: boolean; value: string }) => ({
+        "aria-current": data.active ? "page" : undefined,
+        role: "menuitem",
+        tabindex: -1,
+        onClick: () => {
+          options.onSelect(data.value);
+        },
+      }),
+    },
+  };
+});

package/src/composables/outsideClick.ts

@@ -0,0 +1,52 @@
+import { onBeforeMount, onBeforeUnmount, watchEffect, type Ref } from "vue";
+
+export type UseOutsideClickOptions = {
+  /**
+   * Function that returns the HTML element of the component where outside clicks should be listened to.
+   */
+  queryComponent: () => ReturnType<typeof document.querySelector> | undefined;
+  /**
+   * Callback when an outside click occurred.
+   */
+  onOutsideClick: () => void;
+  /**
+   * If `true`, event listeners will be removed and no outside clicks will be captured.
+   */
+  disabled?: Ref<boolean>;
+};
+
+/**
+ * Composable for listening to click events that occur outside of a component.
+ * Useful to e.g. close flyouts or tooltips.
+ */
+export const useOutsideClick = (options: UseOutsideClickOptions) => {
+  /**
+   * Document click handle that closes then tooltip when clicked outside.
+   * Should only be called when trigger is "click".
+   */
+  const handleDocumentClick = (event: MouseEvent) => {
+    const component = options.queryComponent();
+    if (!component || !(event.target instanceof Node)) return;
+
+    const isOutsideClick = !event.composedPath().includes(component);
+    if (isOutsideClick) options.onOutsideClick();
+  };
+
+  // add global document event listeners only on/before mounted to also work in server side rendering
+  onBeforeMount(() => {
+    watchEffect(() => {
+      if (options.disabled?.value) {
+        document.removeEventListener("click", handleDocumentClick);
+      } else {
+        document.addEventListener("click", handleDocumentClick);
+      }
+    });
+  });
+
+  /**
+   * Clean up global event listeners to prevent dangling events.
+   */
+  onBeforeUnmount(() => {
+    document.removeEventListener("click", handleDocumentClick);
+  });
+};

package/src/composables/tooltip/createTooltip.ts

@@ -1,14 +1,7 @@
-import {
-  computed,
-  onBeforeMount,
-  onBeforeUnmount,
-  ref,
-  unref,
-  watchEffect,
-  type MaybeRef,
-} from "vue";
+import { computed, onBeforeMount, onBeforeUnmount, ref, unref, type MaybeRef } from "vue";
 import { createId } from "../..";
 import { createBuilder } from "../../utils/builder";
+import { useOutsideClick } from "../outsideClick";
 
 export type CreateTooltipOptions = {
   open: MaybeRef<TooltipOpen>;
@@ -92,41 +85,23 @@ export const createTooltip = createBuilder((options: CreateTooltipOptions) => {
     _isVisible.value = false;
   };
 
-  /**
-   * Document click handle that closes then tooltip when clicked outside.
-   * Should only be called when trigger is "click".
-   */
-  const handleDocumentClick = (event: MouseEvent) => {
-    const tooltipParent = document.getElementById(tooltipId)?.parentElement;
-    if (!tooltipParent || !(event.target instanceof Node)) return;
-
-    const isOutsideClick = !tooltipParent.contains(event.target);
-    if (isOutsideClick) _isVisible.value = false;
-  };
+  // close tooltip on outside click
+  useOutsideClick({
+    queryComponent: () => document.getElementById(tooltipId)?.parentElement,
+    onOutsideClick: () => (_isVisible.value = false),
+    disabled: computed(() => openType.value !== "click"),
+  });
 
   // add global document event listeners only on/before mounted to also work in server side rendering
   onBeforeMount(() => {
     document.addEventListener("keydown", handleDocumentKeydown);
-
-    /**
-     * Registers keydown and click handlers when trigger is "click" to close
-     * the tooltip.
-     */
-    watchEffect(() => {
-      if (openType.value === "click") {
-        document.addEventListener("click", handleDocumentClick);
-      } else {
-        document.removeEventListener("click", handleDocumentClick);
-      }
-    });
   });
 
   /**
    * Clean up global event listeners to prevent dangling events.
    */
   onBeforeUnmount(() => {
-    document.addEventListener("keydown", handleDocumentKeydown);
-    document.addEventListener("click", handleDocumentClick);
+    document.removeEventListener("keydown", handleDocumentKeydown);
   });
 
   return {

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./composables/comboBox/createComboBox";
 export * from "./composables/listbox/createListbox";
 export * from "./composables/tooltip/createTooltip";
+export * from "./composables/menuButton/createMenuButton";
 export { createId } from "./utils/id";
+export { isPrintableCharacter, wasKeyPressed } from "./utils/keyboard";

package/src/playwright.ts

@@ -1,2 +1,3 @@
 export * from "./composables/comboBox/createComboBox.ct";
 export * from "./composables/listbox/createListbox.ct";
+export * from "./composables/menuButton/createMenuButton.ct";

package/src/utils/keyboard.spec.ts

@@ -1,5 +1,40 @@
 import { expect, test } from "vitest";
-import { isPrintableCharacter } from "./keyboard";
+import { isPrintableCharacter, wasKeyPressed } from "./keyboard";
+
+test.each([
+  // ARRANGE
+  { input: [{ key: "m", code: "KeyM" }, "m"], expected: true },
+  { input: [{ key: "m", code: "KeyM" }, "m"], expected: true },
+  { input: [{ key: "m", code: "KeyM" }, { key: "m" }], expected: true },
+  { input: [{ key: "m", code: "KeyM" }, { code: "KeyM" }], expected: true },
+  {
+    input: [{ key: "m", code: "KeyM", altKey: false }, { code: "KeyM" }],
+    expected: true,
+  },
+  {
+    input: [
+      { key: "m", code: "KeyM" },
+      { code: "KeyM", altKey: true },
+    ],
+    expected: false,
+  },
+  {
+    input: [
+      { key: "m", code: "KeyM", shiftKey: true },
+      { code: "KeyM", shiftKey: false },
+    ],
+    expected: false,
+  },
+] as { input: Parameters<typeof wasKeyPressed>; expected: boolean }[])(
+  "should return $expected for event $input.0 and pressed key $input.1",
+  ({ input: [event, wasPressed], expected }) => {
+    // ACT
+    const result = wasKeyPressed(new KeyboardEvent("keydown", event), wasPressed);
+
+    // ASSERT
+    expect(result).toBe(expected);
+  },
+);
 
 test.each([
   // ARRANGE

package/src/utils/keyboard.ts

@@ -1,3 +1,26 @@
+import { isSubsetMatching } from "./object";
+
+export type PressedKey =
+  | string
+  | Partial<Pick<KeyboardEvent, "altKey" | "key" | "ctrlKey" | "metaKey" | "shiftKey" | "code">>;
+
+/**
+ * Check if a specified key was pressed.
+ * @param event The KeyboardEvent
+ * @param key The key, either the [key property](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) as a string (e.g. "m")
+ * or an object with the relevant key parameters, e.g. `{ key: "m", altKey: true }`
+ * @returns true, if the key was pressed with the specified parameters
+ */
+export const wasKeyPressed = (event: KeyboardEvent, key: PressedKey) => {
+  if (typeof key === "string") {
+    return event.key === key;
+  }
+  return isSubsetMatching(
+    { altKey: false, ctrlKey: false, metaKey: false, shiftKey: false, ...key },
+    event,
+  );
+};
+
 /**
  * Check if the `key` property of a KeyboardEvent is a printable character.
  *

package/src/utils/object.spec.ts

@@ -0,0 +1,33 @@
+import { expect, test } from "vitest";
+import { isSubsetMatching } from "./object";
+
+const referenceObj = { a: 42, b: "foo", c: null, d: true };
+
+test.each([
+  // ARRANGE
+  { label: "with the same key-values", compareObj: { ...referenceObj } },
+  {
+    label: "with additional key-values in compared object",
+    compareObj: { d: true, b: "foo", c: null, a: 42, f: 23 },
+  },
+  { label: "with undefined keys", compareObj: { ...referenceObj, e: undefined } },
+])("should return true for objects $label", ({ compareObj }) => {
+  // ACT
+  const result = isSubsetMatching(referenceObj, compareObj);
+
+  // ASSERT
+  expect(result).toBeTruthy();
+});
+
+test.each([
+  // ARRANGE
+  { label: "only having a single entry", compareObj: { foo: 42 } },
+  { label: "a value", compareObj: { ...referenceObj, a: 0 } },
+  { label: "a value", compareObj: { ...referenceObj, a: undefined } },
+])("should return false when objects differ by $label", ({ compareObj }) => {
+  // ACT
+  const result = isSubsetMatching(referenceObj, compareObj);
+
+  // ASSERT
+  expect(result).toBeFalsy();
+});

package/src/utils/object.ts

@@ -0,0 +1,8 @@
+/**
+ * Check if every entry of a subset exists and matches the entry of a target object.
+ * @returns `true`, if target contains the subset
+ */
+export const isSubsetMatching = (subset: object, target: object) =>
+  Object.entries(subset).every(
+    ([key, value]) => (target as Record<string, unknown>)[key] === value,
+  );

package/src/utils/types.ts

@@ -1,8 +1,23 @@
-export type IfDefined<Key extends string, T> =
-  T extends NonNullable<unknown>
+/**
+ * Adds the entry with the key `Key` and the value of type `TValue` to a record when it is defined.
+ * Then the entry is either undefined or exists without being optional.
+ * @example
+ * ```ts
+ * const _no_error: IfDefined<"b", number> & { a: number } = { a: 1, b: 2 };
+ * // Error: Object literal may only specify known properties, and 'b' does not exist in type '{ a: number; }'.
+ * const _error: IfDefined<"b", undefined> & { a: number } = { a: 1, b: 2 };
+ * ```
+ */
+export type IfDefined<Key extends string, TValue> =
+  TValue extends NonNullable<unknown>
     ? {
-        [key in Key]: T;
+        [key in Key]: TValue;
       }
-    : {
-        [key in Key]?: undefined;
-      };
+    : unknown;
+
+/**
+ * Wraps type `TValue` in an array, if `TMultiple` is true.
+ */
+export type IsArray<TValue, TMultiple extends boolean = false> = TMultiple extends true
+  ? TValue[]
+  : TValue;