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

package/src/composables/listbox/createListbox.ts

@@ -1,7 +1,7 @@
-import { computed, ref, unref, watchEffect, type MaybeRef, type Ref } from "vue";
-import { createId } from "../..";
-import { createBuilder, type HeadlessElementAttributes } from "../../utils/builder";
-import { useTypeAhead } from "../helpers/useTypeAhead";
+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;
 
@@ -10,19 +10,27 @@ export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends
    * 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<TValue | undefined>;
+  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<TMultiple | undefined>;
+  multiple?: MaybeRef<Nullable<TMultiple>>;
   /**
    * Hook when an option is selected.
    */
@@ -77,6 +85,7 @@ export const createListbox = createBuilder(
     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
@@ -85,7 +94,7 @@ export const createListbox = createBuilder(
 
     const getOptionId = (value: TValue) => {
       if (!descendantKeyIdMap.has(value)) {
-        descendantKeyIdMap.set(value, createId("listbox-option"));
+        descendantKeyIdMap.set(value, useId());
       }
       return descendantKeyIdMap.get(value)!;
     };
@@ -96,10 +105,17 @@ export const createListbox = createBuilder(
     const isFocused = ref(false);
 
     // scroll currently active option into view if needed
-    watchEffect(() => {
-      if (options.activeOption.value == undefined || (!isFocused.value && !options.controlled))
+    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" });
     });
 
@@ -152,18 +168,20 @@ export const createListbox = createBuilder(
       }
     };
 
-    const listbox = computed<HeadlessElementAttributes>(() =>
+    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

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

@@ -1,5 +1,5 @@
 import { test } from "@playwright/experimental-ct-vue";
-import { menuButtonTesting } from "./createMenuButton.testing";
+import { menuButtonTesting } from "./createMenuButton.testing.js";
 import TestMenuButton from "./TestMenuButton.vue";
 
 test("menuButton", async ({ mount, page }) => {

package/src/composables/menuButton/TestMenuButton.vue

@@ -1,6 +1,6 @@
 <script lang="ts" setup>
 import { ref } from "vue";
-import { createMenuButton } from "./createMenuButton";
+import { createMenuButton } from "./createMenuButton.js";
 
 const items = Array.from({ length: 10 }, (_, index) => {
   const id = index + 1;
@@ -10,15 +10,16 @@ const items = Array.from({ length: 10 }, (_, index) => {
 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 });
+} = createMenuButton({ isExpanded, onToggle, trigger });
 </script>
 
 <template>
   <div v-bind="root">
-    <button v-bind="button">Toggle nav menu</button>
+    <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>

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 { debounce } from "../../utils/timer";
-import { useGlobalEventListener } from "../helpers/useGlobalListener";
+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: 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/TestMenu.ct.tsx

@@ -1,5 +1,5 @@
 import { test } from "@playwright/experimental-ct-vue";
-import { navigationTesting } from "./createMenu.testing";
+import { navigationTesting } from "./createMenu.testing.js";
 import TestMenu from "./TestMenu.vue";
 
 test("navigationMenu", async ({ mount, page }) => {

package/src/composables/navigationMenu/TestMenu.vue

@@ -1,6 +1,6 @@
 <script lang="ts" setup>
 import TestMenuButton from "../menuButton/TestMenuButton.vue";
-import { createNavigationMenu } from "./createMenu";
+import { createNavigationMenu } from "./createMenu.js";
 
 const {
   elements: { nav },

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,7 +1,6 @@
-import { unref, type MaybeRef } from "vue";
-import { createId } from "../..";
-import { createBuilder } from "../../utils/builder";
-import { MathUtils } from "../../utils/math";
+import { unref, useId, type MaybeRef } from "vue";
+import { createBuilder } from "../../utils/builder.js";
+import { MathUtils } from "../../utils/math.js";
 
 type CreateNavigationMenu = {
   /**
@@ -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.js";
+
+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.js";
+
+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>