@sit-onyx/headless 1.0.0-beta.1 → 1.0.0-beta.10

package/src/composables/menuButton/createMenuButton.ts

@@ -1,123 +1,143 @@
-import { computed, ref } from "vue";
-import { createBuilder } from "../../utils/builder";
-import { createId } from "../../utils/id";
+import { computed, useId, type Ref } from "vue";
+import { createBuilder, createElRef } from "../../utils/builder";
 import { debounce } from "../../utils/timer";
+import { useGlobalEventListener } from "../helpers/useGlobalListener";
+
+type CreateMenuButtonOptions = {
+  isExpanded: Ref<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, onToggle }: CreateMenuButtonOptions) => {
+    const rootId = useId();
+    const menuId = useId();
+    const menuRef = createElRef<HTMLElement>();
+    const buttonId = useId();
 
-  /**
-   * Debounced expanded state that will only be toggled after a given timeout.
-   */
-  const updateDebouncedExpanded = debounce(
-    (expanded: boolean) => (isExpanded.value = expanded),
-    200,
-  );
+    useGlobalEventListener({
+      type: "keydown",
+      listener: (e) => e.key === "Escape" && isExpanded.value && onToggle(),
+      disabled: computed(() => !isExpanded.value),
+    });
 
-  const hoverEvents = computed(() => {
-    return {
-      onMouseover: () => updateDebouncedExpanded(true),
-      onMouseout: () => updateDebouncedExpanded(false),
-      onFocusin: () => (isExpanded.value = true),
-      onFocusout: () => (isExpanded.value = false),
-    };
-  });
+    /**
+     * 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;
+    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;
+      // 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;
+      const menuItems = [...currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]')];
+      let nextIndex = 0;
 
-    if (currentMenuItem) {
-      const currentIndex = menuItems.indexOf(currentMenuItem);
-      switch (next) {
-        case "next":
-          nextIndex = currentIndex + 1;
+      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 "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,
+    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 (
+              rootId &&
+              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,
       },
-      ...createMenuItem().elements,
-    },
-  };
-});
+    };
+  },
+);
 
-export const createMenuItem = createBuilder(() => {
+export const createMenuItems = createBuilder(() => {
   return {
     elements: {
       listItem: {

package/src/composables/navigationMenu/TestMenu.ct.tsx

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

package/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>

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

@@ -0,0 +1,37 @@
+import { expect } from "@playwright/experimental-ct-vue";
+import type { Locator } from "@playwright/test";
+
+export type NavigationMenuTestingOptions = {
+  /**
+   * Locator for the navigation landmark.
+   */
+  nav: Locator;
+  /**
+   * Locator for the button elements.
+   */
+  buttons: 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/disclosure/examples/disclosure-navigation/
+ */
+export const navigationTesting = async ({ nav, buttons }: NavigationMenuTestingOptions) => {
+  /**
+   * Navigation landmark should have label
+   */
+  await expect(nav).toHaveRole("navigation");
+  await expect(nav).toHaveAttribute("aria-label");
+
+  /**
+   * Focus first button
+   */
+  await buttons.first().focus();
+  /**
+   * Move keyboard focus among top-level buttons using arrow keys
+   */
+  await nav.press("ArrowRight");
+  await expect(buttons.nth(1)).toBeFocused();
+  await nav.press("ArrowLeft");
+  await expect(buttons.nth(0)).toBeFocused();
+};

package/src/composables/navigationMenu/createMenu.ts

@@ -0,0 +1,55 @@
+import { unref, useId, type MaybeRef } from "vue";
+import { createBuilder } from "../../utils/builder";
+import { MathUtils } from "../../utils/math";
+
+type CreateNavigationMenu = {
+  /**
+   * Name of the navigation landmark.
+   * Usually this is the name of the website.
+   */
+  navigationName?: MaybeRef<string | undefined>;
+};
+
+/**
+ * Based on https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/
+ */
+export const createNavigationMenu = createBuilder(({ navigationName }: CreateNavigationMenu) => {
+  const navId = useId();
+
+  const getMenuButtons = () => {
+    const nav = navId ? document.getElementById(navId) : undefined;
+    if (!nav) return [];
+    return [...nav.querySelectorAll<HTMLElement>("button[aria-expanded][aria-controls]")];
+  };
+
+  const focusRelative = (trigger: HTMLElement, next: "next" | "previous") => {
+    const menuButtons = getMenuButtons();
+    const index = menuButtons.indexOf(trigger);
+    if (index === -1) return;
+    const nextIndex = MathUtils.clamp(
+      index + (next === "next" ? 1 : -1),
+      0,
+      menuButtons.length - 1,
+    );
+    menuButtons[nextIndex].focus();
+  };
+
+  return {
+    elements: {
+      nav: {
+        "aria-label": unref(navigationName),
+        id: navId,
+        onKeydown: (event) => {
+          switch (event.key) {
+            case "ArrowRight":
+              focusRelative(event.target as HTMLElement, "next");
+              break;
+            case "ArrowLeft":
+              focusRelative(event.target as HTMLElement, "previous");
+              break;
+          }
+        },
+      },
+    },
+  };
+});

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

@@ -0,0 +1,13 @@
+import { test } from "@playwright/experimental-ct-vue";
+import TestTabs from "./TestTabs.vue";
+import { tabsTesting } from "./createTabs.testing";
+
+// eslint-disable-next-line playwright/expect-expect
+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,26 @@
+<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>
+    </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>
+</template>

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

@@ -0,0 +1,79 @@
+import { expect } from "@playwright/experimental-ct-vue";
+import type { Locator, Page } from "@playwright/test";
+
+export type TabsTestingOptions = {
+  page: Page;
+  /**
+   * Locator of the tabs component.
+   */
+  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 activeTab = options.tablist.locator('[aria-selected="true"]');
+  await expect(activeTab, "must have an initially active tab").toBeVisible();
+
+  const { tabId, panelId } = await expectTabAttributes(activeTab, true);
+  await expectPanelAttributes(options.page.locator(`#${panelId}`), tabId);
+
+  // ACT (switch tab)
+  let tab2 = options.tablist.locator('[aria-selected="false"]').first();
+  tab2 = options.tablist.locator(`#${await tab2.getAttribute("id")}`);
+  await tab2.click();
+
+  const { tabId: tabId2, panelId: panelId2 } = await expectTabAttributes(tab2, true);
+  await expectPanelAttributes(options.page.locator(`#${panelId2}`), tabId2);
+
+  await expect(options.page.getByRole("tabpanel"), "should hide previous panel").toHaveCount(1);
+};
+
+/**
+ * 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,
+  );
+};

package/src/composables/tabs/createTabs.ts

@@ -0,0 +1,72 @@
+import { computed, unref, useId, type MaybeRef, type Ref } from "vue";
+import { createBuilder } from "../../utils/builder";
+
+type CreateTabsOptions<TKey extends PropertyKey = PropertyKey> = {
+  /**
+   * Label of the tablist.
+   */
+  label: MaybeRef<string>;
+  /**
+   * Currently selected tab.
+   */
+  selectedTab: Ref<TKey>;
+  /**
+   * Called when the user selects a tab.
+   */
+  onSelect?: (selectedTabValue: TKey) => void;
+};
+
+/**
+ * Composable for implementing accessible tabs.
+ * Based on https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ */
+export const createTabs = createBuilder(<T extends PropertyKey>(options: CreateTabsOptions<T>) => {
+  /**
+   * Map for looking up tab and panel IDs for given tab keys/values defined by the user.
+   * Key = custom value from the user, value = random generated tab and panel ID
+   */
+  const idMap = new Map<T, { tabId: string; panelId: string }>();
+
+  const getId = (value: T) => {
+    if (!idMap.has(value)) {
+      idMap.set(value, { tabId: useId(), panelId: useId() });
+    }
+    return idMap.get(value)!;
+  };
+
+  return {
+    elements: {
+      tablist: computed(() => ({
+        role: "tablist",
+        "aria-label": unref(options.label),
+      })),
+      tab: computed(() => {
+        return (data: { value: T }) => {
+          const { tabId: selectedTabId } = getId(unref(options.selectedTab));
+          const { tabId, panelId } = getId(data.value);
+          const isSelected = tabId === selectedTabId;
+
+          return {
+            id: tabId,
+            role: "tab",
+            "aria-selected": isSelected,
+            "aria-controls": panelId,
+            onClick: () => options.onSelect?.(data.value),
+            tabindex: isSelected ? 0 : -1,
+          } as const;
+        };
+      }),
+      tabpanel: computed(() => {
+        return (data: { value: T }) => {
+          const { tabId, panelId } = getId(data.value);
+
+          return {
+            id: panelId,
+            role: "tabpanel",
+            "aria-labelledby": tabId,
+          } as const;
+        };
+      }),
+    },
+  };
+});

package/src/composables/tooltip/createToggletip.ts

@@ -0,0 +1,61 @@
+import { computed, toRef, toValue, type MaybeRefOrGetter, type Ref } from "vue";
+import { createBuilder, createElRef } from "../../utils/builder";
+import { useDismissible } from "../helpers/useDismissible";
+import { useOutsideClick } from "../helpers/useOutsideClick";
+
+export type CreateToggletipOptions = {
+  toggleLabel: MaybeRefOrGetter<string>;
+  isVisible?: Ref<boolean>;
+};
+
+/**
+ * Create a toggletip as described in https://inclusive-components.design/tooltips-toggletips/
+ * Its visibility is toggled on click.
+ * Therefore a toggletip MUST NOT be used to describe the associated trigger element.
+ * Commonly this pattern uses a button with the ⓘ as the trigger element.
+ * To describe the associated element use `createTooltip`.
+ */
+export const createToggletip = createBuilder(
+  ({ toggleLabel, isVisible }: CreateToggletipOptions) => {
+    const triggerRef = createElRef<HTMLButtonElement>();
+    const tooltipRef = createElRef<HTMLElement>();
+    const _isVisible = toRef(isVisible ?? false);
+
+    // close tooltip on outside click
+    useOutsideClick({
+      inside: computed(() => [triggerRef.value, tooltipRef.value]),
+      onOutsideClick: () => (_isVisible.value = false),
+      disabled: computed(() => !_isVisible.value),
+    });
+
+    useDismissible({ isExpanded: _isVisible });
+
+    const toggle = () => (_isVisible.value = !_isVisible.value);
+
+    return {
+      elements: {
+        /**
+         * The element which controls the toggletip visibility:
+         * Preferably a `button` element.
+         */
+        trigger: computed(() => ({
+          ref: triggerRef,
+          onClick: toggle,
+          "aria-label": toValue(toggleLabel),
+        })),
+        /**
+         * The element with the relevant toggletip content.
+         * Only simple, textual content is allowed.
+         */
+        tooltip: {
+          ref: tooltipRef,
+          role: "status",
+          tabindex: "-1",
+        },
+      },
+      state: {
+        isVisible: _isVisible,
+      },
+    };
+  },
+);