@sit-onyx/headless 1.0.0-beta.21 → 1.0.0-beta.23

package/src/composables/listbox/createListbox.ts

@@ -1,234 +0,0 @@
-import { computed, nextTick, ref, unref, useId, watchEffect, type MaybeRef, type Ref } from "vue";
-import { createBuilder, type VBindAttributes } from "../../utils/builder.js";
-import type { Nullable } from "../../utils/types.js";
-import { useTypeAhead } from "../helpers/useTypeAhead.js";
-
-export type ListboxValue = string | number | boolean;
-
-export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends boolean = false> = {
-  /**
-   * Aria label for the listbox.
-   */
-  label: MaybeRef<string>;
-  /**
-   * Aria description for the listbox.
-   */
-  description?: MaybeRef<Nullable<string>>;
-  /**
-   * Value of currently (visually) active option.
-   */
-  activeOption: Ref<Nullable<TValue>>;
-  /**
-   * Wether the listbox is controlled from the outside, e.g. by a combobox.
-   * This disables keyboard events and makes the listbox not focusable.
-   */
-  controlled?: boolean;
-  /**
-   * Controls the opened/visible state of the listbox. When expanded the activeOption can be controlled via the keyboard.
-   */
-  isExpanded?: MaybeRef<boolean>;
-  /**
-   * Whether the listbox is multiselect.
-   */
-  multiple?: MaybeRef<Nullable<TMultiple>>;
-  /**
-   * Hook when an option is selected.
-   */
-  onSelect?: (value: TValue) => void;
-  /**
-   * Hook when the first option should be activated.
-   */
-  onActivateFirst?: () => void;
-  /**
-   * Hook when the last option should be activated.
-   */
-  onActivateLast?: () => void;
-  /**
-   * Hook when the next option should be activated.
-   */
-  onActivateNext?: (currentValue: TValue) => void;
-  /**
-   * Hook when the previous option should be activated.
-   */
-  onActivatePrevious?: (currentValue: TValue) => void;
-  /**
-   * Hook when the first option starting with the given label should be activated.
-   */
-  onTypeAhead?: (key: string) => void;
-} & (
-  | {
-      /**
-       * Optional aria label for the listbox.
-       */
-      label?: MaybeRef<string>;
-      /**
-       * Wether the listbox is controlled from the outside, e.g. by a combobox.
-       * This disables keyboard events and makes the listbox not focusable.
-       */
-      controlled: true;
-    }
-  | {
-      /**
-       * Aria label for the listbox.
-       */
-      label: MaybeRef<string>;
-      controlled?: false;
-    }
-);
-
-/**
- * Composable for creating a accessibility-conform listbox.
- * For supported keyboard shortcuts, see: https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/
- */
-export const createListbox = createBuilder(
-  <TValue extends ListboxValue, TMultiple extends boolean = false>(
-    options: CreateListboxOptions<TValue, TMultiple>,
-  ) => {
-    const isMultiselect = computed(() => unref(options.multiple) ?? false);
-    const isExpanded = computed(() => unref(options.isExpanded) ?? false);
-
-    /**
-     * Map for option IDs. key = option value, key = ID for the HTML element
-     */
-    const descendantKeyIdMap = new Map<TValue, string>();
-
-    const getOptionId = (value: TValue) => {
-      if (!descendantKeyIdMap.has(value)) {
-        descendantKeyIdMap.set(value, useId());
-      }
-      return descendantKeyIdMap.get(value)!;
-    };
-
-    /**
-     * Whether the listbox element is focused.
-     */
-    const isFocused = ref(false);
-
-    // scroll currently active option into view if needed
-    watchEffect(async () => {
-      if (
-        !isExpanded.value ||
-        options.activeOption.value == undefined ||
-        (!isFocused.value && !options.controlled)
-      ) {
-        return;
-      }
-
-      const id = getOptionId(options.activeOption.value);
-      await nextTick();
-      document.getElementById(id)?.scrollIntoView({ block: "nearest", inline: "nearest" });
-    });
-
-    const typeAhead = useTypeAhead((inputString) => options.onTypeAhead?.(inputString));
-
-    const handleKeydown = (event: KeyboardEvent) => {
-      switch (event.key) {
-        case " ":
-          event.preventDefault();
-          if (options.activeOption.value != undefined) {
-            options.onSelect?.(options.activeOption.value);
-          }
-          break;
-
-        case "ArrowUp":
-          event.preventDefault();
-          // if no option is active yet, activate the last option
-          if (options.activeOption.value == undefined) {
-            options.onActivateLast?.();
-            return;
-          }
-
-          options.onActivatePrevious?.(options.activeOption.value);
-          break;
-
-        case "ArrowDown":
-          event.preventDefault();
-          // if no option is active yet, activate the first option
-          if (options.activeOption.value == undefined) {
-            options.onActivateFirst?.();
-            return;
-          }
-
-          options.onActivateNext?.(options.activeOption.value);
-          break;
-
-        case "Home":
-          event.preventDefault();
-          options.onActivateFirst?.();
-          break;
-
-        case "End":
-          event.preventDefault();
-          options.onActivateLast?.();
-          break;
-
-        default:
-          // if printable characters are pressed, the first option/text starting with the typed characters should be active
-          typeAhead(event);
-      }
-    };
-
-    const listbox = computed<VBindAttributes>(() =>
-      options.controlled
-        ? {
-            role: "listbox",
-            "aria-multiselectable": isMultiselect.value,
-            "aria-label": unref(options.label),
-            "aria-description": options.description,
-            tabindex: "-1",
-          }
-        : {
-            role: "listbox",
-            "aria-multiselectable": isMultiselect.value,
-            "aria-label": unref(options.label),
-            "aria-description": options.description,
-            tabindex: "0",
-            "aria-activedescendant":
-              options.activeOption.value != undefined
-                ? getOptionId(options.activeOption.value)
-                : undefined,
-            onFocus: () => (isFocused.value = true),
-            onBlur: () => (isFocused.value = false),
-            onKeydown: handleKeydown,
-          },
-    );
-
-    return {
-      elements: {
-        listbox,
-        group: computed(() => {
-          return (options: { label: string }) => ({
-            role: "group",
-            "aria-label": options.label,
-          });
-        }),
-        option: computed(() => {
-          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,
-              "aria-checked": isMultiselect.value ? selected : undefined,
-              "aria-selected": !isMultiselect.value ? selected : undefined,
-              onClick: () => !data.disabled && options.onSelect?.(data.value),
-            } as const;
-          };
-        }),
-      },
-      state: {
-        isFocused,
-      },
-      internals: {
-        getOptionId,
-      },
-    };
-  },
-);

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

@@ -1,14 +0,0 @@
-import { test } from "@playwright/experimental-ct-vue";
-import { menuButtonTesting } from "./createMenuButton.testing.js";
-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: page.getByRole("menuitem"),
-  });
-});

package/src/composables/menuButton/TestMenuButton.vue

@@ -1,29 +0,0 @@
-<script lang="ts" setup>
-import { ref } from "vue";
-import { createMenuButton } from "./createMenuButton.js";
-
-const items = Array.from({ length: 10 }, (_, index) => {
-  const id = index + 1;
-  return { label: `Item ${id}`, value: `/href-${id}` };
-});
-
-const activeItem = ref<string>();
-const isExpanded = ref(false);
-const onToggle = () => (isExpanded.value = !isExpanded.value);
-const trigger = ref<"click" | "hover">("hover");
-
-const {
-  elements: { root, button, menu, menuItem, listItem },
-} = createMenuButton({ isExpanded, onToggle, trigger });
-</script>
-
-<template>
-  <div v-bind="root">
-    <button v-bind="button" type="button">Toggle nav menu</button>
-    <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>
-  </div>
-</template>

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

@@ -1,91 +0,0 @@
-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) => {
-  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, "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,
-    "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 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

@@ -1,206 +0,0 @@
-import { computed, toValue, useId, watch, type MaybeRef, type Ref } from "vue";
-import { createBuilder, createElRef } from "../../utils/builder.js";
-import { debounce } from "../../utils/timer.js";
-import { useGlobalEventListener } from "../helpers/useGlobalListener.js";
-import { useOutsideClick } from "../helpers/useOutsideClick.js";
-
-type CreateMenuButtonOptions = {
-  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((options: CreateMenuButtonOptions) => {
-  const rootId = useId();
-  const menuId = useId();
-  const rootRef = createElRef<HTMLElement>();
-  const menuRef = createElRef<HTMLElement>();
-  const buttonId = useId();
-
-  const position = computed(() => toValue(options.position) ?? "bottom");
-
-  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 "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":
-        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 {
-      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;
-    }
-  };
-
-  return {
-    elements: {
-      listItem: {
-        role: "none",
-      },
-      menuItem: (data: { active?: boolean; disabled?: boolean }) => ({
-        "aria-current": data.active ? "page" : undefined,
-        "aria-disabled": data.disabled,
-        role: "menuitem",
-        onKeydown,
-      }),
-    },
-  };
-});

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

@@ -1,12 +0,0 @@
-import { test } from "@playwright/experimental-ct-vue";
-import { navigationTesting } from "./createMenu.testing.js";
-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

@@ -1,16 +0,0 @@
-<script lang="ts" setup>
-import TestMenuButton from "../menuButton/TestMenuButton.vue";
-import { createNavigationMenu } from "./createMenu.js";
-
-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

@@ -1,37 +0,0 @@
-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

@@ -1,55 +0,0 @@
-import { unref, useId, type MaybeRef } from "vue";
-import { createBuilder } from "../../utils/builder.js";
-import { MathUtils } from "../../utils/math.js";
-
-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 Array.from(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;
-          }
-        },
-      },
-    },
-  };
-});