@sit-onyx/headless 1.0.0-alpha.9 → 1.0.0-beta.1

package/README.md

@@ -1,7 +1,7 @@
-<div align="center">
+<div align="center" style="text-align: center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-light.svg">
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg">
+    <source media="(prefers-color-scheme: dark)" type="image/svg+xml" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-light.svg">
+    <source media="(prefers-color-scheme: light)" type="image/svg+xml" srcset="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg">
     <img alt="onyx logo" src="https://raw.githubusercontent.com/SchwarzIT/onyx/main/.github/onyx-logo-dark.svg" width="160px">
   </picture>
 </div>
@@ -12,8 +12,6 @@
 
 A composable headless library for Vue created by [Schwarz IT](https://it.schwarz).
 
-> **Work in progress**: This library is currently in early / active development.
-
 <br />
 
 ## Documentation

package/package.json

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

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

@@ -1,7 +1,7 @@
 import { test } from "@playwright/experimental-ct-vue";
-import TestCombobox from "./TestCombobox.vue";
-import { comboboxTesting, comboboxSelectOnlyTesting } from "./createComboBox.ct";
+import { comboboxSelectOnlyTesting, comboboxTesting } from "./createComboBox.testing";
 import SelectOnlyCombobox from "./SelectOnlyCombobox.vue";
+import TestCombobox from "./TestCombobox.vue";
 
 test("combobox", async ({ mount, page }) => {
   await mount(<TestCombobox />);

package/src/composables/comboBox/{createComboBox.ct.ts → createComboBox.testing.ts}

@@ -36,7 +36,7 @@ const expectToClose = async (
  * 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,

package/src/composables/comboBox/createComboBox.ts

@@ -1,19 +1,24 @@
-import { computed, ref, unref, 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 { useOutsideClick } from "../helpers/useOutsideClick";
+import { useTypeAhead } from "../helpers/useTypeAhead";
 import {
   createListbox,
   type CreateListboxOptions,
   type ListboxValue,
 } from "../listbox/createListbox";
-import { useOutsideClick } from "../outsideClick";
-import { useTypeAhead } from "../typeAhead";
 
 export type ComboboxAutoComplete = "none" | "list" | "both";
 
-const OPENING_KEYS: PressedKey[] = ["ArrowDown", "ArrowUp", " ", "Enter", "Home", "End"];
-const CLOSING_KEYS: PressedKey[] = ["Escape", { key: "ArrowUp", altKey: true }, "Enter", "Tab"];
+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"];
 
@@ -117,7 +122,6 @@ export const createComboBox = createBuilder(
     onActivatePrevious,
     templateRef,
   }: CreateComboboxOptions<TValue, TAutoComplete, TMultiple>) => {
-    const inputValid = ref(true);
     const controlsId = createId("comboBox-control");
 
     const autocomplete = computed(() => unref(autocompleteRef));
@@ -126,10 +130,6 @@ export const createComboBox = createBuilder(
 
     const handleInput = (event: Event) => {
       const inputElement = event.target as HTMLInputElement;
-      inputValid.value = inputElement.validity.valid;
-      if (!unref(isExpanded)) {
-        onToggle?.();
-      }
 
       if (autocomplete.value !== "none") {
         onAutocomplete?.(inputElement.value);
@@ -173,6 +173,11 @@ export const createComboBox = createBuilder(
     };
 
     const handleKeydown = (event: KeyboardEvent) => {
+      if (event.key === "Enter") {
+        // prevent submitting on pressing enter when the combo box is used inside a <form>
+        event.preventDefault();
+      }
+
       if (!isExpanded.value && isKeyOfGroup(event, OPENING_KEYS)) {
         onToggle?.();
         if (event.key === " ") {
@@ -193,6 +198,10 @@ export const createComboBox = createBuilder(
         !isExpanded.value && onToggle?.();
         return typeAhead(event);
       }
+      if (autocomplete.value !== "none" && isPrintableCharacter(event.key)) {
+        !isExpanded.value && onToggle?.();
+        return;
+      }
       return handleNavigation(event);
     };
 
@@ -216,7 +225,7 @@ export const createComboBox = createBuilder(
     });
 
     useOutsideClick({
-      queryComponent: () => templateRef.value,
+      element: templateRef,
       onOutsideClick() {
         if (!isExpanded.value) return;
         onToggle?.(true);

package/src/composables/helpers/useGlobalListener.spec.ts

@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ref, type Ref } from "vue";
+import { mockVueLifecycle } from "../../utils/vitest";
+import { useGlobalEventListener } from "./useGlobalListener";
+
+let unmount: () => Promise<void> | undefined;
+
+describe("useGlobalEventListener", () => {
+  let target: Ref<HTMLButtonElement>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    unmount = mockVueLifecycle();
+    target = ref(document.createElement("button"));
+    document.body.appendChild(target.value);
+  });
+
+  it("should be defined", () => {
+    expect(useGlobalEventListener).toBeDefined();
+  });
+
+  it("should listen to global events", () => {
+    // ARRANGE
+    const listener = vi.fn();
+    useGlobalEventListener({ type: "click", listener });
+    // ACT
+    const event = new MouseEvent("click", { bubbles: true });
+    target.value.dispatchEvent(event);
+    // ASSERT
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toBeCalledWith(event);
+  });
+
+  it("should stop to listen to global events after unmount", async () => {
+    // ARRANGE
+    const listener = vi.fn();
+    useGlobalEventListener({ type: "click", listener });
+    // ACT
+    await unmount();
+    expect(listener).toHaveBeenCalledTimes(0);
+    target.value.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    // ASSERT
+    expect(listener).toHaveBeenCalledTimes(0);
+  });
+
+  it("should allow for multiple of the same listener types", async () => {
+    // ARRANGE
+    vi.useFakeTimers();
+    const listener = vi.fn();
+    const disabled = ref(false);
+    const listener2 = vi.fn();
+    useGlobalEventListener({ type: "click", listener, disabled });
+    useGlobalEventListener({ type: "click", listener: listener2 });
+    // ACT
+    target.value.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    // ASSERT
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener2).toHaveBeenCalledTimes(1);
+    // ACT
+    disabled.value = true;
+    await vi.runAllTimersAsync();
+    // ACT
+    target.value.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    // ASSERT
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener2).toHaveBeenCalledTimes(2);
+  });
+
+  it("should not listen to events when disabled", async () => {
+    // ARRANGE
+    vi.useFakeTimers();
+    const disabled = ref(false);
+    const listener = vi.fn();
+    useGlobalEventListener({ type: "click", listener, disabled });
+    // ACT
+    await vi.runAllTimersAsync();
+    target.value.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    // ASSERT
+    expect(listener).toHaveBeenCalledTimes(1);
+    // ACT
+    disabled.value = true;
+    await vi.runAllTimersAsync();
+    target.value.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    // ASSERT
+    expect(listener).toHaveBeenCalledTimes(1);
+    // ACT
+    disabled.value = false;
+    await vi.runAllTimersAsync();
+    target.value.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    // ASSERT
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+});

package/src/composables/helpers/useGlobalListener.ts

@@ -0,0 +1,64 @@
+import { onBeforeMount, onBeforeUnmount, reactive, watchEffect, type Ref } from "vue";
+
+type DocumentEventType = keyof DocumentEventMap;
+type GlobalListener<K extends DocumentEventType = DocumentEventType> = (
+  event: DocumentEventMap[K],
+) => void;
+
+export type UseGlobalEventListenerOptions<K extends DocumentEventType> = {
+  type: K;
+  listener: GlobalListener<K>;
+  disabled?: Ref<boolean>;
+};
+
+const GLOBAL_LISTENERS = reactive(new Map<DocumentEventType, Set<GlobalListener>>());
+
+const updateRemainingListeners = (type: DocumentEventType, remaining?: Set<GlobalListener>) => {
+  if (remaining?.size) {
+    GLOBAL_LISTENERS.set(type, remaining);
+    return;
+  }
+  GLOBAL_LISTENERS.delete(type);
+  document.removeEventListener(type, GLOBAL_HANDLER);
+};
+
+const removeGlobalListener = <K extends DocumentEventType>(
+  type: K,
+  listener: GlobalListener<K>,
+) => {
+  const globalListener = GLOBAL_LISTENERS.get(type);
+  globalListener?.delete(listener as GlobalListener);
+
+  updateRemainingListeners(type, globalListener);
+};
+
+const addGlobalListener = <K extends DocumentEventType>(type: K, listener: GlobalListener<K>) => {
+  const globalListener = GLOBAL_LISTENERS.get(type) ?? new Set();
+  globalListener.add(listener as GlobalListener);
+  GLOBAL_LISTENERS.set(type, globalListener);
+
+  document.addEventListener(type, GLOBAL_HANDLER);
+};
+
+/**
+ * A single and unique function for all event types.
+ * We use the fact that `addEventListener` and `removeEventListener` are idempotent when called with the same function reference.
+ */
+const GLOBAL_HANDLER = (event: Event) => {
+  const type = event.type as DocumentEventType;
+  GLOBAL_LISTENERS.get(type)?.forEach((cb) => cb(event));
+};
+
+export const useGlobalEventListener = <K extends DocumentEventType>({
+  type,
+  listener,
+  disabled,
+}: UseGlobalEventListenerOptions<K>) => {
+  onBeforeMount(() =>
+    watchEffect(() =>
+      disabled?.value ? removeGlobalListener(type, listener) : addGlobalListener(type, listener),
+    ),
+  );
+
+  onBeforeUnmount(() => removeGlobalListener(type, listener));
+};

package/src/composables/helpers/useOutsideClick.ts

@@ -0,0 +1,34 @@
+import { type Ref } from "vue";
+import { useGlobalEventListener } from "./useGlobalListener";
+
+export type UseOutsideClickOptions = {
+  /**
+   * HTML element of the component where clicks should be ignored
+   */
+  element: Ref<HTMLElement | 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 = ({ element, onOutsideClick, disabled }: UseOutsideClickOptions) => {
+  /**
+   * Document click handle that closes then tooltip when clicked outside.
+   * Should only be called when trigger is "click".
+   */
+  const listener = ({ target }: MouseEvent) => {
+    const isOutsideClick = !element.value?.contains(target as HTMLElement);
+    if (isOutsideClick) onOutsideClick();
+  };
+
+  useGlobalEventListener({ type: "click", listener, disabled });
+};

package/src/composables/{typeAhead.spec.ts → helpers/useTypeAhead.spec.ts}

@@ -1,5 +1,5 @@
 import { beforeAll, expect, test, vi } from "vitest";
-import { useTypeAhead } from "./typeAhead";
+import { useTypeAhead } from "./useTypeAhead";
 
 beforeAll(() => {
   vi.useFakeTimers();

package/src/composables/{typeAhead.ts → helpers/useTypeAhead.ts}

@@ -1,5 +1,5 @@
-import { isPrintableCharacter } from "../utils/keyboard";
-import { debounce } from "../utils/timer";
+import { isPrintableCharacter } from "../../utils/keyboard";
+import { debounce } from "../../utils/timer";
 
 /**
  * Enhances typeAhead to combine multiple inputs in quick succession and filter out non-printable characters.

package/src/composables/listbox/TestListbox.ct.tsx

@@ -1,6 +1,6 @@
 import { test } from "@playwright/experimental-ct-vue";
 import TestListbox from "./TestListbox.vue";
-import { listboxTesting } from "./createListbox.ct";
+import { listboxTesting } from "./createListbox.testing";
 
 test("listbox", async ({ mount, page }) => {
   await mount(<TestListbox />);

package/src/composables/listbox/createListbox.ts

@@ -1,7 +1,7 @@
 import { computed, ref, unref, watchEffect, type MaybeRef, type Ref } from "vue";
 import { createId } from "../..";
 import { createBuilder, type HeadlessElementAttributes } from "../../utils/builder";
-import { useTypeAhead } from "../typeAhead";
+import { useTypeAhead } from "../helpers/useTypeAhead";
 
 export type ListboxValue = string | number | boolean;
 
@@ -185,15 +185,24 @@ export const createListbox = createBuilder(
           });
         }),
         option: computed(() => {
-          return (data: { label: string; value: TValue; disabled?: boolean; selected?: boolean }) =>
-            ({
+          return (data: {
+            label: string;
+            value: TValue;
+            disabled?: boolean;
+            selected?: boolean;
+          }) => {
+            const selected = data.selected ?? false;
+
+            return {
               id: getOptionId(data.value),
               role: "option",
               "aria-label": data.label,
               "aria-disabled": data.disabled,
-              [isMultiselect.value ? "aria-checked" : "aria-selected"]: data.selected || false,
+              "aria-checked": isMultiselect.value ? selected : undefined,
+              "aria-selected": !isMultiselect.value ? selected : undefined,
               onClick: () => !data.disabled && options.onSelect?.(data.value),
-            }) as const;
+            } as const;
+          };
         }),
       },
       state: {

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

@@ -0,0 +1,14 @@
+import { test } from "@playwright/experimental-ct-vue";
+import { menuButtonTesting } from "./createMenuButton.testing";
+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,27 @@
+<script lang="ts" setup>
+import { ref } from "vue";
+import { createMenuButton } from "./createMenuButton";
+
+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();
+</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 })" href="#">{{ item.label }}</a>
+      </li>
+    </ul>
+  </div>
+</template>

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

@@ -0,0 +1,109 @@
+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 ({
+  page,
+  button,
+  menu,
+  menuItems,
+}: 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");
+
+  const firstItem = menuItems[0].getByRole("menuitem");
+  const secondItem = menuItems[1].getByRole("menuitem");
+  const lastItem = menuItems[menuItems.length - 1].getByRole("menuitem");
+
+  await page.keyboard.press("Tab");
+  await expect(button, "Button should be focused when pressing tab key").toBeFocused();
+
+  await button.press("ArrowDown");
+  await expect(
+    firstItem,
+    "First item should be focused when pressing arrow down key",
+  ).toBeFocused();
+
+  await menu.press("ArrowDown");
+  await expect(
+    secondItem,
+    "Second item should be focused when pressing arrow down key",
+  ).toBeFocused();
+
+  await menu.press("ArrowUp");
+  await expect(firstItem, "First item should be focused when pressing arrow up key").toBeFocused();
+
+  await menu.press("ArrowRight");
+  await expect(
+    secondItem,
+    "Second item should be focused when pressing arrow right key",
+  ).toBeFocused();
+
+  await menu.press("ArrowLeft");
+  await expect(
+    firstItem,
+    "First item should be focused when pressing arrow left key",
+  ).toBeFocused();
+
+  await page.keyboard.press("Tab");
+  await expect(button, "Button should be focused when pressing tab key").not.toBeFocused();
+
+  await page.keyboard.press("Tab");
+
+  await menu.press("Home");
+  await expect(firstItem, "First item should be focused when pressing home key").toBeFocused();
+
+  await page.keyboard.press("Tab");
+  await expect(button, "Button should be focused when pressing tab key").not.toBeFocused();
+
+  await page.keyboard.press("Tab");
+
+  await menu.press("End");
+  await expect(lastItem, "Last item should be focused when pressing end key").toBeFocused();
+};

package/src/composables/menuButton/createMenuButton.ts

@@ -0,0 +1,133 @@
+import { computed, ref } from "vue";
+import { createBuilder } from "../../utils/builder";
+import { createId } from "../../utils/id";
+import { debounce } from "../../utils/timer";
+
+/**
+ * Based on https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/
+ */
+export const createMenuButton = createBuilder(() => {
+  const menuId = createId("menu");
+  const buttonId = createId("menu-button");
+  const isExpanded = ref(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),
+    };
+  });
+
+  const focusRelativeItem = (next: "next" | "prev" | "first" | "last") => {
+    const currentMenuItem = document.activeElement as HTMLElement;
+
+    // Either the current focus is on a "menuitem", then we can just get the parent menu.
+    // Or the current focus is on the button, then we can get the connected menu using the menuId
+    const currentMenu =
+      currentMenuItem?.closest('[role="menu"]') || document.getElementById(menuId);
+    if (!currentMenu) return;
+
+    const menuItems = [...currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]')];
+    let nextIndex = 0;
+
+    if (currentMenuItem) {
+      const currentIndex = menuItems.indexOf(currentMenuItem);
+      switch (next) {
+        case "next":
+          nextIndex = currentIndex + 1;
+          break;
+        case "prev":
+          nextIndex = currentIndex - 1;
+          break;
+        case "first":
+          nextIndex = 0;
+          break;
+        case "last":
+          nextIndex = menuItems.length - 1;
+          break;
+      }
+    }
+
+    const nextMenuItem = menuItems[nextIndex];
+    nextMenuItem?.focus();
+  };
+
+  const handleKeydown = (event: KeyboardEvent) => {
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowRight":
+        event.preventDefault();
+        focusRelativeItem("next");
+        break;
+      case "ArrowUp":
+      case "ArrowLeft":
+        event.preventDefault();
+        focusRelativeItem("prev");
+        break;
+      case "Home":
+        event.preventDefault();
+        focusRelativeItem("first");
+        break;
+      case "End":
+        event.preventDefault();
+        focusRelativeItem("last");
+        break;
+      case " ":
+        event.preventDefault();
+        (event.target as HTMLElement).click();
+        break;
+    }
+  };
+
+  return {
+    state: { isExpanded },
+    elements: {
+      button: computed(
+        () =>
+          ({
+            "aria-controls": menuId,
+            "aria-expanded": isExpanded.value,
+            "aria-haspopup": true,
+            id: buttonId,
+            ...hoverEvents.value,
+            onKeydown: handleKeydown,
+          }) as const,
+      ),
+      flyout: {
+        ...hoverEvents.value,
+      },
+      menu: {
+        id: menuId,
+        role: "menu",
+        "aria-labelledby": buttonId,
+        onKeydown: handleKeydown,
+      },
+      ...createMenuItem().elements,
+    },
+  };
+});
+
+export const createMenuItem = createBuilder(() => {
+  return {
+    elements: {
+      listItem: {
+        role: "none",
+      },
+      menuItem: (data: { active?: boolean; disabled?: boolean }) => ({
+        "aria-current": data.active ? "page" : undefined,
+        "aria-disabled": data.disabled,
+        role: "menuitem",
+      }),
+    },
+  };
+});

package/src/composables/tooltip/createTooltip.ts

@@ -1,7 +1,7 @@
 import { computed, onBeforeMount, onBeforeUnmount, ref, unref, type MaybeRef } from "vue";
 import { createId } from "../..";
 import { createBuilder } from "../../utils/builder";
-import { useOutsideClick } from "../outsideClick";
+import { useOutsideClick } from "../helpers/useOutsideClick";
 
 export type CreateTooltipOptions = {
   open: MaybeRef<TooltipOpen>;
@@ -22,6 +22,7 @@ export const TOOLTIP_TRIGGERS = ["hover", "click"] as const;
 export type TooltipTrigger = (typeof TOOLTIP_TRIGGERS)[number];
 
 export const createTooltip = createBuilder((options: CreateTooltipOptions) => {
+  const rootRef = ref<HTMLElement>();
   const tooltipId = createId("tooltip");
   const _isVisible = ref(false);
   let timeout: ReturnType<typeof setTimeout> | undefined;
@@ -87,7 +88,7 @@ export const createTooltip = createBuilder((options: CreateTooltipOptions) => {
 
   // close tooltip on outside click
   useOutsideClick({
-    queryComponent: () => document.getElementById(tooltipId)?.parentElement,
+    element: rootRef,
     onOutsideClick: () => (_isVisible.value = false),
     disabled: computed(() => openType.value !== "click"),
   });
@@ -106,6 +107,9 @@ export const createTooltip = createBuilder((options: CreateTooltipOptions) => {
 
   return {
     elements: {
+      root: {
+        ref: rootRef,
+      },
       trigger: computed(() => ({
         "aria-describedby": tooltipId,
         onClick: openType.value === "click" ? handleClick : undefined,

package/src/index.ts

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

package/src/playwright.ts

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

package/src/utils/builder.ts

@@ -1,12 +1,14 @@
-import type { ComputedRef, HtmlHTMLAttributes, Ref } from "vue";
+import type { ComputedRef, HtmlHTMLAttributes, Ref, VNodeRef } from "vue";
 import type { IfDefined } from "./types";
 
+export type ElementAttributes = HtmlHTMLAttributes & { ref?: VNodeRef };
+
 export type IteratedHeadlessElementFunc<T extends Record<string, unknown>> = (
   opts: T,
-) => HtmlHTMLAttributes;
+) => ElementAttributes;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type HeadlessElementAttributes = HtmlHTMLAttributes | IteratedHeadlessElementFunc<any>;
+export type HeadlessElementAttributes = ElementAttributes | IteratedHeadlessElementFunc<any>;
 
 export type HeadlessElements = Record<
   string,
@@ -28,10 +30,10 @@ export type HeadlessComposable<
  * We use this identity function to ensure the correct typings of the headless composables
  */
 export const createBuilder = <
-  P,
-  Elements extends HeadlessElements,
+  Args extends unknown[] = unknown[],
+  Elements extends HeadlessElements = HeadlessElements,
   State extends HeadlessState | undefined = undefined,
   Internals extends object | undefined = undefined,
 >(
-  builder: (props: P) => HeadlessComposable<Elements, State, Internals>,
+  builder: (...args: Args) => HeadlessComposable<Elements, State, Internals>,
 ) => builder;

package/src/utils/math.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest";
+import { MathUtils } from "./math";
+
+describe("MathUtils.clamp", () => {
+  test.each([
+    { number: 1, min: 1, max: 2, result: 1 },
+    { number: 1, min: 2, max: 2, result: 2 },
+    { number: 1, min: 0, max: 0, result: 0 },
+    { number: 1, min: 1, max: 1, result: 1 },
+  ])(
+    "should return $result for key number:$number min:$min max:$max",
+    ({ number, min, max, result }) => expect(MathUtils.clamp(number, min, max)).toBe(result),
+  );
+});

package/src/utils/math.ts

@@ -0,0 +1,6 @@
+export const MathUtils = {
+  /**
+   * Ensures that a given `number` is or is between a given `min` and `max`.
+   */
+  clamp: (number: number, min: number, max: number) => Math.max(Math.min(number, max), min),
+};

package/src/utils/vitest.ts

@@ -0,0 +1,36 @@
+import { vi, type Awaitable } from "vitest";
+
+type Callback = () => Awaitable<void>;
+
+/**
+ * Mocks the following vue lifecycle functions:
+ * - onBeforeMount
+ * - onMounted
+ * - onBeforeUnmount
+ * - onUnmounted
+ *
+ * `onBeforeMount` and `onMounted` callbacks are executed immediately.
+ * `onBeforeUnmount` and `onUnmounted` are executed when the returned callback is run.
+ * @returns a callback to trigger the run of `onBeforeUnmount` and `onUnmounted`
+ */
+export const mockVueLifecycle = () => {
+  const { callbacks } = vi.hoisted(() => ({
+    callbacks: {
+      onBeforeUnmountedCb: null as Callback | null,
+      onUnmountedCb: null as Callback | null,
+    },
+  }));
+
+  vi.mock("vue", async (original) => ({
+    ...((await original()) as typeof import("vue")),
+    onBeforeMount: vi.fn((cb: Callback) => cb()),
+    onMounted: vi.fn((cb: Callback) => cb()),
+    onBeforeUnmount: vi.fn((cb: Callback) => (callbacks.onBeforeUnmountedCb = cb)),
+    onUnmounted: vi.fn((cb: Callback) => (callbacks.onUnmountedCb = cb)),
+  }));
+
+  return async () => {
+    await callbacks.onBeforeUnmountedCb?.();
+    await callbacks.onUnmountedCb?.();
+  };
+};

package/src/composables/outsideClick.ts

@@ -1,52 +0,0 @@
-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);
-  });
-};