@sit-onyx/headless 1.0.0-beta.2 → 1.0.0-beta.20

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

@@ -30,13 +30,6 @@ export const menuButtonTesting = async ({
   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',
@@ -80,18 +73,6 @@ export const menuButtonTesting = async ({
   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();
 

package/src/composables/menuButton/createMenuButton.ts

@@ -1,141 +1,195 @@
-import { computed, ref, type Ref } from "vue";
-import { createBuilder } from "../../utils/builder";
-import { createId } from "../../utils/id";
+import { computed, toValue, useId, watch, type MaybeRef, type Ref } from "vue";
+import { createBuilder, createElRef } from "../../utils/builder";
 import { debounce } from "../../utils/timer";
 import { useGlobalEventListener } from "../helpers/useGlobalListener";
+import { useOutsideClick } from "../helpers/useOutsideClick";
 
 type CreateMenuButtonOptions = {
-  isExpanded: Ref<boolean>;
+  isExpanded: Readonly<Ref<boolean>>;
+  trigger: Readonly<MaybeRef<"hover" | "click">>;
   onToggle: () => void;
+  disabled?: Readonly<Ref<boolean>>;
+  /**
+   * Whether the menu button opens to the top or bottom. Defines the keyboard navigation behavior (e.g. Arrow up and down).
+   *
+   * @default "bottom"
+   */
+  position?: MaybeRef<"top" | "bottom">;
 };
 
 /**
  * Based on https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/
  */
-export const createMenuButton = createBuilder(
-  ({ isExpanded, onToggle }: CreateMenuButtonOptions) => {
-    const rootId = createId("menu-button-root");
-    const menuId = createId("menu-button-list");
-    const menuRef = ref<HTMLElement>();
-    const buttonId = createId("menu-button-button");
-
-    useGlobalEventListener({
-      type: "keydown",
-      listener: (e) => e.key === "Escape" && isExpanded.value && onToggle(),
-      disabled: computed(() => !isExpanded.value),
-    });
-
-    /**
-     * Debounced expanded state that will only be toggled after a given timeout.
-     */
-    const updateDebouncedExpanded = debounce(
-      (expanded: boolean) => isExpanded.value !== expanded && onToggle(),
-      200,
-    );
-
-    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"]') || menuRef.value;
-      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;
-        }
-      }
+export const createMenuButton = createBuilder((options: CreateMenuButtonOptions) => {
+  const rootId = useId();
+  const menuId = useId();
+  const rootRef = createElRef<HTMLElement>();
+  const menuRef = createElRef<HTMLElement>();
+  const buttonId = useId();
 
-      const nextMenuItem = menuItems[nextIndex];
-      nextMenuItem?.focus();
-    };
+  const position = computed(() => toValue(options.position) ?? "bottom");
 
-    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");
+  useGlobalEventListener({
+    type: "keydown",
+    listener: (e) => e.key === "Escape" && setExpanded(false),
+    disabled: computed(() => !options.isExpanded.value),
+  });
+
+  /**
+   * Debounced expanded state that will only be toggled after a given timeout.
+   */
+  const updateDebouncedExpanded = debounce(() => options.onToggle(), 200);
+  watch(options.isExpanded, () => updateDebouncedExpanded.abort()); // manually changing `isExpanded` should abort debounced action
+
+  const setExpanded = (expanded: boolean, debounced = false) => {
+    if (options.disabled?.value) return;
+    if (expanded === options.isExpanded.value) {
+      updateDebouncedExpanded.abort();
+      return;
+    }
+    if (debounced) {
+      updateDebouncedExpanded();
+      return;
+    }
+    options.onToggle();
+  };
+
+  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"]') || menuRef.value;
+    if (!currentMenu) return;
+
+    const menuItems = Array.from(currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]'))
+      // filter out nested children
+      .filter((item) => item.closest('[role="menu"]') === currentMenu);
+    if (position.value === "top") menuItems.reverse();
+    let nextIndex = 0;
+
+    if (currentMenuItem) {
+      const currentIndex = menuItems.indexOf(currentMenuItem);
+      switch (next) {
+        case "next":
+          nextIndex = currentIndex + 1;
           break;
-        case "End":
-          event.preventDefault();
-          focusRelativeItem("last");
+        case "prev":
+          nextIndex = currentIndex - 1;
           break;
-        case " ":
-          event.preventDefault();
-          (event.target as HTMLElement).click();
+        case "first":
+          nextIndex = 0;
           break;
-        case "Escape":
-          event.preventDefault();
-          isExpanded.value && onToggle();
+        case "last":
+          nextIndex = menuItems.length - 1;
           break;
       }
-    };
+    }
 
+    const nextMenuItem = menuItems[nextIndex];
+    nextMenuItem?.focus();
+  };
+
+  const handleKeydown = (event: KeyboardEvent) => {
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        focusRelativeItem(position.value === "bottom" ? "next" : "prev");
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        focusRelativeItem(position.value === "bottom" ? "prev" : "next");
+        break;
+      case "Home":
+        event.preventDefault();
+        focusRelativeItem("first");
+        break;
+      case "End":
+        event.preventDefault();
+        focusRelativeItem("last");
+        break;
+      case " ":
+      case "Enter":
+        if (event.target instanceof HTMLInputElement) break;
+        event.preventDefault();
+        (event.target as HTMLElement).click();
+        break;
+      case "Escape":
+        event.preventDefault();
+        setExpanded(false);
+        break;
+    }
+  };
+
+  const triggerEvents = computed(() => {
+    if (toValue(options.trigger) !== "hover") return;
     return {
-      elements: {
-        root: {
-          id: rootId,
-          onKeydown: handleKeydown,
-          onMouseover: () => updateDebouncedExpanded(true),
-          onMouseout: () => updateDebouncedExpanded(false),
-          onFocusout: (event) => {
-            // if focus receiving element is not part of the menu button, then close
-            if (document.getElementById(rootId)?.contains(event.relatedTarget as HTMLElement)) {
-              return;
-            }
-            isExpanded.value && onToggle();
-          },
-        },
-        button: computed(
-          () =>
-            ({
-              "aria-controls": menuId,
-              "aria-expanded": isExpanded.value,
-              "aria-haspopup": true,
-              onFocus: () => !isExpanded.value && onToggle(),
-              id: buttonId,
-            }) as const,
-        ),
-        menu: {
-          id: menuId,
-          ref: menuRef,
-          role: "menu",
-          "aria-labelledby": buttonId,
-          onClick: () => isExpanded.value && onToggle(),
-        },
-        ...createMenuItems().elements,
-      },
+      onMouseenter: () => setExpanded(true),
+      onMouseleave: () => setExpanded(false, true),
     };
-  },
-);
+  });
+
+  useOutsideClick({
+    inside: rootRef,
+    onOutsideClick: () => setExpanded(false),
+    disabled: computed(() => !options.isExpanded.value),
+    checkOnTab: true,
+  });
+
+  return {
+    elements: {
+      root: computed(() => ({
+        id: rootId,
+        onKeydown: handleKeydown,
+        ref: rootRef,
+        ...triggerEvents.value,
+      })),
+      button: computed(
+        () =>
+          ({
+            "aria-controls": menuId,
+            "aria-expanded": options.isExpanded.value,
+            "aria-haspopup": true,
+            onFocus: () => setExpanded(true, true),
+            onClick: () =>
+              toValue(options.trigger) == "click"
+                ? setExpanded(!options.isExpanded.value)
+                : undefined,
+            id: buttonId,
+            disabled: options.disabled?.value,
+          }) as const,
+      ),
+      menu: {
+        id: menuId,
+        ref: menuRef,
+        role: "menu",
+        "aria-labelledby": buttonId,
+        onClick: () => setExpanded(false),
+      },
+      ...createMenuItems().elements,
+    },
+  };
+});
+
+type CreateMenuItemOptions = {
+  /**
+   * Called when the menu item should be opened (if it has nested children).
+   */
+  onOpen?: () => void;
+};
+
+export const createMenuItems = createBuilder((options?: CreateMenuItemOptions) => {
+  const onKeydown = (event: KeyboardEvent) => {
+    switch (event.key) {
+      case "ArrowRight":
+      case " ":
+      case "Enter":
+        event.preventDefault();
+        options?.onOpen?.();
+        break;
+    }
+  };
 
-export const createMenuItems = createBuilder(() => {
   return {
     elements: {
       listItem: {
@@ -145,6 +199,7 @@ export const createMenuItems = createBuilder(() => {
         "aria-current": data.active ? "page" : undefined,
         "aria-disabled": data.disabled,
         role: "menuitem",
+        onKeydown,
       }),
     },
   };

package/src/composables/navigationMenu/createMenu.testing.ts

@@ -22,22 +22,11 @@ export const navigationTesting = async ({ nav, buttons }: NavigationMenuTestingO
    */
   await expect(nav).toHaveRole("navigation");
   await expect(nav).toHaveAttribute("aria-label");
-  /**
-   * Disclosure buttons should have aria attributes
-   */
-  for (const button of await buttons.all()) {
-    await expect(button, "button must have arial-controls attribute").toHaveAttribute(
-      "aria-controls",
-    );
-    await expect(button, "button must have aria-expanded attribute").toHaveAttribute(
-      "aria-expanded",
-    );
-  }
+
   /**
    * Focus first button
    */
-  await nav.press("Tab");
-  await expect(buttons.nth(0)).toBeFocused();
+  await buttons.first().focus();
   /**
    * Move keyboard focus among top-level buttons using arrow keys
    */

package/src/composables/navigationMenu/createMenu.ts

@@ -1,5 +1,4 @@
-import { unref, type MaybeRef } from "vue";
-import { createId } from "../..";
+import { unref, useId, type MaybeRef } from "vue";
 import { createBuilder } from "../../utils/builder";
 import { MathUtils } from "../../utils/math";
 
@@ -15,12 +14,12 @@ type CreateNavigationMenu = {
  * Based on https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/
  */
 export const createNavigationMenu = createBuilder(({ navigationName }: CreateNavigationMenu) => {
-  const navId = createId("nav");
+  const navId = useId();
 
   const getMenuButtons = () => {
-    const nav = document.getElementById(navId);
+    const nav = navId ? document.getElementById(navId) : undefined;
     if (!nav) return [];
-    return [...nav.querySelectorAll<HTMLElement>("button[aria-expanded][aria-controls]")];
+    return Array.from(nav.querySelectorAll<HTMLElement>("button[aria-expanded][aria-controls]"));
   };
 
   const focusRelative = (trigger: HTMLElement, next: "next" | "previous") => {

package/src/composables/tabs/TestTabs.ct.tsx

@@ -0,0 +1,12 @@
+import { test } from "@playwright/experimental-ct-vue";
+import TestTabs from "./TestTabs.vue";
+import { tabsTesting } from "./createTabs.testing";
+
+test("tabs", async ({ mount, page }) => {
+  const component = await mount(<TestTabs />);
+
+  await tabsTesting({
+    page,
+    tablist: component.getByRole("tablist"),
+  });
+});

package/src/composables/tabs/TestTabs.vue

@@ -0,0 +1,28 @@
+<script lang="ts" setup>
+import { ref } from "vue";
+import { createTabs } from "./createTabs";
+
+const selectedTab = ref("tab-1");
+
+const {
+  elements: { tablist, tab, tabpanel },
+} = createTabs({
+  label: "Tablist label",
+  selectedTab,
+  onSelect: (tab) => (selectedTab.value = tab),
+});
+</script>
+
+<template>
+  <div>
+    <div v-bind="tablist">
+      <button v-bind="tab({ value: 'tab-1' })" type="button">Tab 1</button>
+      <button v-bind="tab({ value: 'tab-2' })" type="button">Tab 2</button>
+      <button v-bind="tab({ value: 'tab-3' })" type="button">Tab 3</button>
+    </div>
+
+    <div v-if="selectedTab === 'tab-1'" v-bind="tabpanel({ value: 'tab-1' })">Tab content 1</div>
+    <div v-if="selectedTab === 'tab-2'" v-bind="tabpanel({ value: 'tab-2' })">Tab content 2</div>
+    <div v-if="selectedTab === 'tab-3'" v-bind="tabpanel({ value: 'tab-3' })">Tab content 3</div>
+  </div>
+</template>

package/src/composables/tabs/createTabs.testing.ts

@@ -0,0 +1,151 @@
+import { expect } from "@playwright/experimental-ct-vue";
+import type { Locator, Page } from "@playwright/test";
+
+export type TabsTestingOptions = {
+  page: Page;
+  /**
+   * Locator of the tabs component. Must have at least 3 tabs where the first one is initially selected.
+   */
+  tablist: Locator;
+};
+
+/**
+ * Playwright utility for executing accessibility testing for tabs.
+ * Will check aria attributes and keyboard shortcuts as defined in https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ */
+export const tabsTesting = async (options: TabsTestingOptions) => {
+  await expect(options.tablist, 'tablist element must have role "tablist"').toHaveRole("tablist");
+  await expect(options.tablist, "tablist must have an accessible label").toHaveAttribute(
+    "aria-label",
+  );
+
+  const firstTab = options.tablist.getByRole("tab").first();
+  const secondTab = options.tablist.getByRole("tab").nth(1);
+  const lastTab = options.tablist.getByRole("tab").last();
+
+  const { tabId, panelId } = await expectTabAttributes(firstTab, true);
+  await expectPanelAttributes(options.page.locator(`#${panelId}`), tabId);
+
+  // ACT (switch tab)
+  await secondTab.click();
+
+  const { tabId: tabId2, panelId: panelId2 } = await expectTabAttributes(secondTab, true);
+  await expectPanelAttributes(options.page.locator(`#${panelId2}`), tabId2);
+  await expect(secondTab, "second tab should be focused").toBeFocused();
+
+  await expect(options.page.getByRole("tabpanel"), "should hide previous panel").toHaveCount(1);
+
+  // keyboard support
+  await options.page.keyboard.press("ArrowLeft");
+  await expect(firstTab, "should focus previous tab when pressing arrow left").toBeFocused();
+
+  await options.page.keyboard.press("End");
+  await expect(lastTab, "should focus last tab when pressing End").toBeFocused();
+
+  await options.page.keyboard.press("ArrowRight");
+  await expect(
+    firstTab,
+    "should focus first tab when last tab is focused and pressing arrow right",
+  ).toBeFocused();
+
+  await options.page.keyboard.press("ArrowRight");
+  await expect(secondTab, "should focus next tab when pressing arrow right").toBeFocused();
+
+  await options.page.keyboard.press("Home");
+  await expect(firstTab, "should focus first tab when pressing Home").toBeFocused();
+
+  await options.page.keyboard.press("ArrowLeft");
+
+  await expect(
+    lastTab,
+    "should focus last tab when first tab is focused and pressing arrow left",
+  ).toBeFocused();
+
+  // should select when pressing Enter
+  await options.page.keyboard.press("Enter");
+  const { tabId: tabIdLast, panelId: panelIdLast } = await expectTabAttributes(lastTab, true);
+  await expectPanelAttributes(options.page.locator(`#${panelIdLast}`), tabIdLast);
+
+  // should select when pressing Space
+  await firstTab.focus();
+  await options.page.keyboard.press("Space");
+  const { tabId: tabIdFirst, panelId: panelIdFirst } = await expectTabAttributes(firstTab, true);
+  await expectPanelAttributes(options.page.locator(`#${panelIdFirst}`), tabIdFirst);
+
+  // should skip disabled tabs when using the keyboard
+  await firstTab.click();
+  await secondTab.evaluate((element) => (element.ariaDisabled = "true"));
+  await expect(secondTab, "should disable second tab when setting aria-disabled").toBeDisabled();
+
+  await options.page.keyboard.press("ArrowRight");
+  await expect(secondTab, "should not focus second tab if its aria-disabled").not.toBeFocused();
+  await expect(
+    options.tablist.getByRole("tab").nth(2),
+    "should focus next tab after disabled one when pressing arrow right",
+  ).toBeFocused();
+
+  await options.page.keyboard.press("ArrowLeft");
+  await expect(
+    firstTab,
+    "should focus tab before disabled one when pressing arrow left",
+  ).toBeFocused();
+
+  await secondTab.evaluate((element) => (element.ariaDisabled = null));
+  await firstTab.evaluate((element) => (element.ariaDisabled = "true"));
+  await options.page.keyboard.press("Home");
+  await expect(
+    secondTab,
+    "should focus second tab when pressing Home if first tab is disabled",
+  ).toBeFocused();
+
+  await firstTab.evaluate((element) => (element.ariaDisabled = null));
+  await lastTab.evaluate((element) => (element.ariaDisabled = "true"));
+  await firstTab.focus();
+  await options.page.keyboard.press("End");
+  await expect(
+    options.tablist.getByRole("tab").nth(-2),
+    "should focus second last tab when pressing End if last tab is disabled",
+  ).toBeFocused();
+};
+
+/**
+ * Executes accessibility tests for a single tab.
+ *
+ * @param tab Locator of the tab.
+ * @param selected Whether the tab is expected to be selected
+ */
+const expectTabAttributes = async (tab: Locator, selected: boolean) => {
+  await expect(tab, 'tab must have role "tab"').toHaveRole("tab");
+  await expect(tab, "tab must have an ID").toHaveAttribute("id");
+  await expect(tab, 'tab must have "aria-selected" set').toHaveAttribute(
+    "aria-selected",
+    String(selected),
+  );
+  await expect(tab, 'tab must have "aria-controls" set').toHaveAttribute("aria-controls");
+
+  if (selected) {
+    await expect(tab, "selected tab should be focusable").toHaveAttribute("tabindex", "0");
+  } else {
+    await expect(tab, "unselected tab should NOT be focusable").toHaveAttribute("tabindex", "-1");
+  }
+
+  const tabId = (await tab.getAttribute("id"))!;
+  const panelId = (await tab.getAttribute("aria-controls"))!;
+  return { tabId, panelId };
+};
+
+/**
+ * Executes accessibility tests for a single tab panel.
+ *
+ * @param panel Locator of the panel
+ * @param tabId Corresponding tab id
+ */
+const expectPanelAttributes = async (panel: Locator, tabId: string) => {
+  await expect(panel, "panel should be visible").toBeVisible();
+  await expect(panel, 'panel must have role "tabpanel"').toHaveRole("tabpanel");
+  await expect(panel, "panel must have an ID").toHaveAttribute("id");
+  await expect(panel, 'panel must have "aria-labelledby" set').toHaveAttribute(
+    "aria-labelledby",
+    tabId,
+  );
+};