@sit-onyx/headless 1.0.0-beta.12 → 1.0.0-beta.14

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/headless",
   "description": "Headless composables for Vue",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "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/menuButton/TestMenuButton.vue

@@ -1,5 +1,5 @@
 <script lang="ts" setup>
-import { ref } from "vue";
+import { ref, type Ref } from "vue";
 import { createMenuButton } from "./createMenuButton";
 
 const items = Array.from({ length: 10 }, (_, index) => {
@@ -10,10 +10,11 @@ const items = Array.from({ length: 10 }, (_, index) => {
 const activeItem = ref<string>();
 const isExpanded = ref(false);
 const onToggle = () => (isExpanded.value = !isExpanded.value);
+const trigger: Readonly<Ref<"click" | "hover">> = ref("hover");
 
 const {
   elements: { root, button, menu, menuItem, listItem },
-} = createMenuButton({ isExpanded, onToggle });
+} = createMenuButton({ isExpanded, onToggle, trigger });
 </script>
 
 <template>

package/src/composables/menuButton/createMenuButton.ts

@@ -1,141 +1,162 @@
-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>>;
+  trigger: Readonly<Ref<"hover" | "click">>;
   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");
-          break;
-        case "Home":
-          event.preventDefault();
-          focusRelativeItem("first");
+    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;
       }
-    };
+    }
 
-    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;
+    }
+  };
+
+  const triggerEvents = () => {
+    if (options.trigger.value === "click") {
+      return {
+        onClick: () => setExpanded(true),
+      };
+    } else {
+      return {
+        onMouseenter: () => setExpanded(true),
+        onMouseleave: () => setExpanded(false, true),
+      };
+    }
+  };
+
+  return {
+    elements: {
+      root: {
+        id: rootId,
+        onKeydown: handleKeydown,
+        ...triggerEvents(),
+        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/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;
 };