@sit-onyx/headless 1.0.0-beta.11 → 1.0.0-beta.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/headless",
   "description": "Headless composables for Vue",
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.13",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -27,8 +27,8 @@
     "vue": ">= 3.5.0"
   },
   "devDependencies": {
-    "@vue/compiler-dom": "3.5.12",
-    "vue": "3.5.12"
+    "@vue/compiler-dom": "3.5.13",
+    "vue": "3.5.13"
   },
   "scripts": {
     "build": "vue-tsc --build --force",

package/src/composables/comboBox/SelectOnlyCombobox.vue

@@ -57,11 +57,11 @@ defineExpose({ comboBox });
       @keydown.arrow-down="isExpanded = true"
     />
 
-    <button v-bind="button">
+    <button v-bind="button" type="button">
       <template v-if="isExpanded">⬆️</template>
       <template v-else>⬇️</template>
     </button>
-    <ul v-bind="listbox" :class="{ hidden: !isExpanded }" style="width: 400px">
+    <ul class="listbox" v-bind="listbox" :class="{ hidden: !isExpanded }">
       <li
         v-for="e in options"
         :key="e"
@@ -84,4 +84,7 @@ defineExpose({ comboBox });
 [aria-selected="true"] {
   background-color: red;
 }
+.listbox {
+  width: 400px;
+}
 </style>

package/src/composables/comboBox/createComboBox.ts

@@ -209,13 +209,13 @@ export const createComboBox = createBuilder(
       return handleNavigation(event);
     };
 
-    const autocompleteInput =
-      autocomplete.value !== "none"
-        ? {
-            "aria-autocomplete": autocomplete.value,
-            type: "text",
-          }
-        : null;
+    const autocompleteInput = computed(() => {
+      if (autocomplete.value === "none") return null;
+      return {
+        "aria-autocomplete": autocomplete.value,
+        type: "text",
+      };
+    });
 
     const {
       elements: { option, group, listbox },
@@ -264,7 +264,7 @@ export const createComboBox = createBuilder(
             activeOption.value != undefined ? getOptionId(activeOption.value) : undefined,
           onInput: handleInput,
           onKeydown: handleKeydown,
-          ...autocompleteInput,
+          ...autocompleteInput.value,
         })),
         /**
          * An optional button to control the visibility of the popup.

package/src/composables/menuButton/TestMenuButton.vue

@@ -18,7 +18,7 @@ const {
 
 <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.ts

@@ -1,141 +1,149 @@
-import { computed, useId, type Ref } from "vue";
+import { computed, useId, watch, 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>;
+  isExpanded: Readonly<Ref<boolean>>;
   onToggle: () => void;
 };
 
 /**
  * Based on https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/
  */
-export const createMenuButton = createBuilder(
-  ({ isExpanded, onToggle }: CreateMenuButtonOptions) => {
-    const rootId = useId();
-    const menuId = useId();
-    const menuRef = createElRef<HTMLElement>();
-    const buttonId = useId();
+export const createMenuButton = createBuilder((options: CreateMenuButtonOptions) => {
+  const rootId = useId();
+  const menuId = useId();
+  const menuRef = createElRef<HTMLElement>();
+  const buttonId = useId();
 
-    useGlobalEventListener({
-      type: "keydown",
-      listener: (e) => e.key === "Escape" && isExpanded.value && onToggle(),
-      disabled: computed(() => !isExpanded.value),
-    });
+  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(
-      (expanded: boolean) => isExpanded.value !== expanded && onToggle(),
-      200,
-    );
+  /**
+   * 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 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 setExpanded = (expanded: boolean, debounced = false) => {
+    if (expanded === options.isExpanded.value) {
+      updateDebouncedExpanded.abort();
+      return;
+    }
+    if (debounced) {
+      updateDebouncedExpanded();
+      return;
+    }
+    options.onToggle();
+  };
 
-      const menuItems = [...currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]')];
-      let nextIndex = 0;
+  const focusRelativeItem = (next: "next" | "prev" | "first" | "last") => {
+    const currentMenuItem = document.activeElement as HTMLElement;
 
-      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;
-        }
-      }
+    // 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 nextMenuItem = menuItems[nextIndex];
-      nextMenuItem?.focus();
-    };
+    const menuItems = [...currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]')];
+    let nextIndex = 0;
 
-    const handleKeydown = (event: KeyboardEvent) => {
-      switch (event.key) {
-        case "ArrowDown":
-        case "ArrowRight":
-          event.preventDefault();
-          focusRelativeItem("next");
-          break;
-        case "ArrowUp":
-        case "ArrowLeft":
-          event.preventDefault();
-          focusRelativeItem("prev");
+    if (currentMenuItem) {
+      const currentIndex = menuItems.indexOf(currentMenuItem);
+      switch (next) {
+        case "next":
+          nextIndex = currentIndex + 1;
           break;
-        case "Home":
-          event.preventDefault();
-          focusRelativeItem("first");
+        case "prev":
+          nextIndex = currentIndex - 1;
           break;
-        case "End":
-          event.preventDefault();
-          focusRelativeItem("last");
+        case "first":
+          nextIndex = 0;
           break;
-        case " ":
-          event.preventDefault();
-          (event.target as HTMLElement).click();
-          break;
-        case "Escape":
-          event.preventDefault();
-          isExpanded.value && onToggle();
+        case "last":
+          nextIndex = menuItems.length - 1;
           break;
       }
-    };
+    }
 
-    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(),
+    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;
+      case "Escape":
+        event.preventDefault();
+        setExpanded(false);
+        break;
+    }
+  };
+
+  return {
+    elements: {
+      root: {
+        id: rootId,
+        onKeydown: handleKeydown,
+        onMouseenter: () => setExpanded(true),
+        onMouseleave: () => setExpanded(false, true),
+        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;
+          }
+          setExpanded(false);
         },
-        ...createMenuItems().elements,
       },
-    };
-  },
-);
+      button: computed(
+        () =>
+          ({
+            "aria-controls": menuId,
+            "aria-expanded": options.isExpanded.value,
+            "aria-haspopup": true,
+            onFocus: () => setExpanded(true),
+            id: buttonId,
+          }) as const,
+      ),
+      menu: {
+        id: menuId,
+        ref: menuRef,
+        role: "menu",
+        "aria-labelledby": buttonId,
+        onClick: () => setExpanded(false),
+      },
+      ...createMenuItems().elements,
+    },
+  };
+});
 
 export const createMenuItems = createBuilder(() => {
   return {

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

@@ -71,6 +71,41 @@ export const tabsTesting = async (options: TabsTestingOptions) => {
   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();
 };
 
 /**

package/src/composables/tabs/createTabs.ts

@@ -37,30 +37,41 @@ export const createTabs = createBuilder(<T extends PropertyKey>(options: CreateT
   const handleKeydown = (event: KeyboardEvent) => {
     const tab = event.target as Element;
 
-    const focusFirstTab = () => {
-      const element = tab.parentElement?.querySelector('[role="tab"]');
+    const enabledTabs = Array.from(
+      tab.parentElement?.querySelectorAll('[role="tab"]') ?? [],
+    ).filter((tab) => tab.ariaDisabled !== "true");
+
+    const currentTabIndex = enabledTabs.indexOf(tab);
+
+    const focusElement = (element?: Element | null) => {
       if (element instanceof HTMLElement) element.focus();
     };
 
-    const focusLastTab = () => {
-      const element = Array.from(tab.parentElement?.querySelectorAll('[role="tab"]') ?? []).at(-1);
-      if (element instanceof HTMLElement) element.focus();
+    const focusFirstTab = () => focusElement(enabledTabs.at(0));
+    const focusLastTab = () => focusElement(enabledTabs.at(-1));
+
+    /**
+     * Focuses the next/previous tab. Will ignore/skip disabled ones.
+     */
+    const focusTab = (direction: "next" | "previous") => {
+      if (currentTabIndex === -1) return;
+      const newIndex = direction === "next" ? currentTabIndex + 1 : currentTabIndex - 1;
+
+      if (newIndex < 0) {
+        return focusLastTab();
+      } else if (newIndex >= enabledTabs.length) {
+        return focusFirstTab();
+      }
+
+      return focusElement(enabledTabs.at(newIndex));
     };
 
     switch (event.key) {
       case "ArrowRight":
-        if (tab.nextElementSibling && tab.nextElementSibling instanceof HTMLElement) {
-          tab.nextElementSibling.focus();
-        } else {
-          focusFirstTab();
-        }
+        focusTab("next");
         break;
       case "ArrowLeft":
-        if (tab.previousElementSibling && tab.previousElementSibling instanceof HTMLElement) {
-          tab.previousElementSibling.focus();
-        } else {
-          focusLastTab();
-        }
+        focusTab("previous");
         break;
       case "Home":
         focusFirstTab();
@@ -86,7 +97,7 @@ export const createTabs = createBuilder(<T extends PropertyKey>(options: CreateT
         onKeydown: handleKeydown,
       })),
       tab: computed(() => {
-        return (data: { value: T }) => {
+        return (data: { value: T; disabled?: boolean }) => {
           const { tabId: selectedTabId } = getId(unref(options.selectedTab));
           const { tabId, panelId } = getId(data.value);
           const isSelected = tabId === selectedTabId;
@@ -96,8 +107,9 @@ export const createTabs = createBuilder(<T extends PropertyKey>(options: CreateT
             role: "tab",
             "aria-selected": isSelected,
             "aria-controls": panelId,
+            "aria-disabled": data.disabled ? true : undefined,
             onClick: () => options.onSelect?.(data.value),
-            tabindex: isSelected ? 0 : -1,
+            tabindex: isSelected && !data.disabled ? 0 : -1,
           } as const;
         };
       }),

package/src/utils/timer.ts

@@ -1,3 +1,5 @@
+import { toValue, type MaybeRefOrGetter } from "vue";
+
 /**
  * Debounces a given callback which will only be called when not called for the given timeout.
  *
@@ -5,11 +7,16 @@
  */
 export const debounce = <TArgs extends unknown[]>(
   handler: (...args: TArgs) => void,
-  timeout: number,
+  timeout: MaybeRefOrGetter<number>,
 ) => {
   let timer: ReturnType<typeof setTimeout> | undefined;
-  return (...lastArgs: TArgs) => {
+
+  const func = (...lastArgs: TArgs) => {
     clearTimeout(timer);
-    timer = setTimeout(() => handler(...lastArgs), timeout);
+    timer = setTimeout(() => handler(...lastArgs), toValue(timeout));
   };
+  /** Abort the currently debounced action, if any. */
+  func.abort = () => clearTimeout(timer);
+
+  return func;
 };