@sit-onyx/headless 1.0.0-alpha.8 → 1.0.0-beta.0

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.8",
+  "version": "1.0.0-beta.0",
   "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.ct";
 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

@@ -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,4 +1,4 @@
-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";
@@ -12,8 +12,13 @@ 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"];
 
@@ -54,8 +59,10 @@ export type CreateComboboxOptions<
   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;
+  onToggle?: (preventFocus?: boolean) => void;
   /**
    * Hook when an option is (un-)selected.
    */
@@ -115,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));
@@ -124,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);
@@ -171,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 === " ") {
@@ -191,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);
     };
 
@@ -217,7 +228,7 @@ export const createComboBox = createBuilder(
       queryComponent: () => templateRef.value,
       onOutsideClick() {
         if (!isExpanded.value) return;
-        onToggle?.();
+        onToggle?.(true);
       },
     });
 
@@ -231,6 +242,8 @@ export const createComboBox = createBuilder(
         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.
@@ -253,7 +266,7 @@ export const createComboBox = createBuilder(
          */
         button: computed(() => ({
           tabindex: "-1",
-          onClick: onToggle,
+          onClick: () => onToggle?.(),
         })),
       },
     };

package/src/composables/listbox/createListbox.ts

@@ -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.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,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.ct.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/outsideClick.ts

@@ -28,7 +28,7 @@ export const useOutsideClick = (options: UseOutsideClickOptions) => {
     const component = options.queryComponent();
     if (!component || !(event.target instanceof Node)) return;
 
-    const isOutsideClick = !event.composedPath().includes(component);
+    const isOutsideClick = !component.contains(event.target);
     if (isOutsideClick) options.onOutsideClick();
   };
 

package/src/index.ts

@@ -1,5 +1,6 @@
 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";

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";