feat(headless): implement headless Menu

.changeset/small-carrots-confess.md

@@ -0,0 +1,11 @@
+---
+"@sit-onyx/headless": major
+"sit-onyx": minor
+---
+
+- implemented headless feature: `createNavigationMenu`
+- headless MenuButton:
+  - now takes an `isExpandedRef` and `onToggle` via it's options
+  - `flyout` element is removed as it is not needed
+  - removed hover and focus toggle features and moved them to the onyx component directly as these are non spec features
+- update headless implementation in `sit-onyx`

packages/headless/src/composables/menuButton/TestMenuButton.ct.tsx

@@ -9,6 +9,6 @@ test("menuButton", async ({ mount, page }) => {
     page,
     button: page.getByRole("button"),
     menu: page.locator("ul"),
-    menuItems: await page.locator("li").all(),
+    menuItems: page.getByRole("menuitem"),
   });
 });

packages/headless/src/composables/menuButton/TestMenuButton.vue

@@ -8,20 +8,19 @@ const items = Array.from({ length: 10 }, (_, index) => {
 });
 
 const activeItem = ref<string>();
+const isExpanded = ref(false);
+const onToggle = () => (isExpanded.value = !isExpanded.value);
 
 const {
-  elements: { button, menu, menuItem, listItem, flyout },
-  state: { isExpanded },
-} = createMenuButton({});
+  elements: { button, menu, menuItem, listItem },
+} = createMenuButton({ isExpanded, onToggle });
 </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>
+  <ul v-show="isExpanded" v-bind="menu">
+    <li v-for="item in items" v-bind="listItem" :key="item.value">
+      <a v-bind="menuItem({ active: activeItem === item.value })" href="#">{{ item.label }}</a>
+    </li>
+  </ul>
 </template>

packages/headless/src/composables/menuButton/createMenuButton.ct.ts

@@ -17,7 +17,7 @@ export type MenuButtonTestingOptions = {
   /**
    * List items (at least 3).
    */
-  menuItems: Locator[];
+  menuItems: Locator;
 };
 
 /**
@@ -45,25 +45,26 @@ export const menuButtonTesting = async ({
   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 expect(button, "button must have arial-controls attribute").toHaveAttribute(
+    "aria-controls",
+  );
+  await expect(button, "button must have aria-expanded attribute").toHaveAttribute(
+    "aria-expanded",
+    "false",
+  );
 
   await page.keyboard.press("Tab");
   await expect(button, "Button should be focused when pressing tab key").toBeFocused();
 
+  const firstItem = menuItems.first();
+  const secondItem = menuItems.nth(1);
+  const lastItem = menuItems.last();
+
+  await page.keyboard.press("Enter");
+  await expect(button, "button must have aria-expanded attribute").toHaveAttribute(
+    "aria-expanded",
+    "true",
+  );
   await button.press("ArrowDown");
   await expect(
     firstItem,

packages/headless/src/composables/menuButton/createMenuButton.ts

@@ -1,125 +1,114 @@
-import { computed, ref } from "vue";
+import { computed, unref, type MaybeRef } from "vue";
 import { createBuilder } from "../../utils/builder";
 import { createId } from "../../utils/id";
-import { debounce } from "../../utils/timer";
+
+type CreateMenuButtonOptions = {
+  isExpanded: MaybeRef<boolean>;
+  onToggle: () => void;
+};
 
 /**
  * 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);
+export const createMenuButton = createBuilder(
+  ({ isExpanded: isExpandedRef, onToggle }: CreateMenuButtonOptions) => {
+    const menuId = createId("menu");
+    const buttonId = createId("menu-button");
+    const isExpanded = computed(() => unref(isExpandedRef));
 
-  /**
-   * Debounced expanded state that will only be toggled after a given timeout.
-   */
-  const updateDebouncedExpanded = debounce(
-    (expanded: boolean) => (isExpanded.value = expanded),
-    200,
-  );
+    const focusRelativeItem = (next: "next" | "prev" | "first" | "last") => {
+      const currentMenuItem = document.activeElement as HTMLElement;
 
-  const hoverEvents = computed(() => {
-    return {
-      onMouseover: () => updateDebouncedExpanded(true),
-      onMouseout: () => updateDebouncedExpanded(false),
-      onFocusin: () => (isExpanded.value = true),
-      onFocusout: () => (isExpanded.value = false),
-    };
-  });
+      // 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 focusRelativeItem = (next: "next" | "prev" | "first" | "last") => {
-    const currentMenuItem = document.activeElement as HTMLElement;
+      const menuItems = [...currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]')];
+      let nextIndex = 0;
 
-    // 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;
+      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 menuItems = [...currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]')];
-    let nextIndex = 0;
+      const nextMenuItem = menuItems[nextIndex];
+      nextMenuItem?.focus();
+    };
 
-    if (currentMenuItem) {
-      const currentIndex = menuItems.indexOf(currentMenuItem);
-      switch (next) {
-        case "next":
-          nextIndex = currentIndex + 1;
+    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 "prev":
-          nextIndex = currentIndex - 1;
+        case "End":
+          event.preventDefault();
+          focusRelativeItem("last");
           break;
-        case "first":
-          nextIndex = 0;
+        case " ":
+          event.preventDefault();
+          (event.target as HTMLElement).click();
           break;
-        case "last":
-          nextIndex = menuItems.length - 1;
+        case "Escape":
+          event.preventDefault();
+          isExpanded.value && onToggle();
           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,
-      },
-      listItem: {
-        role: "none",
+    return {
+      elements: {
+        button: computed(
+          () =>
+            ({
+              "aria-controls": menuId,
+              "aria-expanded": isExpanded.value,
+              "aria-haspopup": true,
+              id: buttonId,
+              onKeydown: handleKeydown,
+              onClick: onToggle,
+            }) as const,
+        ),
+        menu: {
+          id: menuId,
+          role: "menu",
+          "aria-labelledby": buttonId,
+          onKeydown: handleKeydown,
+        },
+        listItem: {
+          role: "none",
+        },
+        menuItem: (data: { active?: boolean; disabled?: boolean }) => ({
+          "aria-current": data.active ? "page" : undefined,
+          "aria-disabled": data.disabled,
+          role: "menuitem",
+        }),
       },
-      menuItem: (data: { active?: boolean; disabled?: boolean }) => ({
-        "aria-current": data.active ? "page" : undefined,
-        "aria-disabled": data.disabled,
-        role: "menuitem",
-      }),
-    },
-  };
-});
+    };
+  },
+);

packages/headless/src/composables/navigationMenu/TestMenu.ct.tsx

@@ -0,0 +1,12 @@
+import { test } from "@playwright/experimental-ct-vue";
+import { navigationTesting } from "./createMenu.ct";
+import TestMenu from "./TestMenu.vue";
+
+test("navigationMenu", async ({ mount, page }) => {
+  await mount(<TestMenu />);
+
+  await navigationTesting({
+    buttons: page.getByRole("button"),
+    nav: page.getByRole("navigation"),
+  });
+});

packages/headless/src/composables/navigationMenu/TestMenu.vue

@@ -0,0 +1,16 @@
+<script lang="ts" setup>
+import TestMenuButton from "../menuButton/TestMenuButton.vue";
+import { createNavigationMenu } from "./createMenu";
+
+const {
+  elements: { nav },
+} = createNavigationMenu({ navigationName: "test menu" });
+</script>
+
+<template>
+  <nav v-bind="nav">
+    <TestMenuButton />
+    <TestMenuButton />
+    <TestMenuButton />
+  </nav>
+</template>