@sit-onyx/headless 1.0.0-beta.18 → 1.0.0-beta.19

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/headless",
   "description": "Headless composables for Vue",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -27,8 +27,8 @@
     "vue": ">= 3.5.0"
   },
   "devDependencies": {
-    "@vue/compiler-dom": "3.5.13",
-    "vue": "3.5.13",
+    "@vue/compiler-dom": "3.5.16",
+    "vue": "3.5.16",
     "@sit-onyx/shared": "^1.0.0-beta.3"
   },
   "scripts": {

package/src/composables/helpers/useGlobalListener.ts

@@ -3,7 +3,7 @@ import { onBeforeMount, onBeforeUnmount, reactive, watchEffect, type Ref } from
 type DocumentEventType = keyof DocumentEventMap;
 type GlobalListener<K extends DocumentEventType = DocumentEventType> = (
   event: DocumentEventMap[K],
-) => void;
+) => unknown;
 
 export type UseGlobalEventListenerOptions<K extends DocumentEventType> = {
   type: K;

package/src/composables/helpers/useOutsideClick.spec.ts

@@ -13,8 +13,9 @@ describe("useOutsideClick", () => {
     expect(useOutsideClick).toBeDefined();
   });
 
-  it("should detect outside clicks", () => {
+  it("should detect outside clicks", async () => {
     // ARRANGE
+    vi.useFakeTimers();
     const inside = ref(document.createElement("button"));
     document.body.appendChild(inside.value);
     const outside = ref(document.createElement("button"));
@@ -22,12 +23,24 @@ describe("useOutsideClick", () => {
 
     const onOutsideClick = vi.fn();
     useOutsideClick({ inside, onOutsideClick });
+
     // ACT
     const event = new MouseEvent("click", { bubbles: true });
     outside.value.dispatchEvent(event);
+
     // ASSERT
     expect(onOutsideClick).toHaveBeenCalledTimes(1);
     expect(onOutsideClick).toBeCalledWith(event);
+
+    // ACT
+    outside.value.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, key: "Tab" }));
+    await vi.runAllTimersAsync();
+
+    // ASSERT
+    expect(
+      onOutsideClick,
+      "should not trigger on Tab press when checkOnTab option is disabled",
+    ).toHaveBeenCalledTimes(1);
   });
 
   it("should detect outside clicks correctly for multiple inside elements", () => {
@@ -80,4 +93,25 @@ describe("useOutsideClick", () => {
     // ASSERT
     expect(onOutsideClick).toHaveBeenCalledTimes(1);
   });
+
+  it("should detect outside tab via keyboard", async () => {
+    // ARRANGE
+    vi.useFakeTimers();
+    const inside = ref(document.createElement("button"));
+    document.body.appendChild(inside.value);
+    const outside = ref(document.createElement("button"));
+    document.body.appendChild(outside.value);
+
+    const onOutsideClick = vi.fn();
+    useOutsideClick({ inside, onOutsideClick, checkOnTab: true });
+
+    // ACT
+    const event = new KeyboardEvent("keydown", { bubbles: true, key: "Tab" });
+    outside.value.dispatchEvent(event);
+    await vi.runAllTimersAsync();
+
+    // ASSERT
+    expect(onOutsideClick).toHaveBeenCalledTimes(1);
+    expect(onOutsideClick).toBeCalledWith(event);
+  });
 });

package/src/composables/helpers/useOutsideClick.ts

@@ -3,7 +3,7 @@ import { toValue, type MaybeRefOrGetter, type Ref } from "vue";
 import type { Nullable } from "../../utils/types";
 import { useGlobalEventListener } from "./useGlobalListener";
 
-export type UseOutsideClickOptions = {
+export type UseOutsideClickOptions<TCheckOnTab extends boolean | undefined = undefined> = {
   /**
    * HTML element of the component where clicks should be ignored
    */
@@ -11,7 +11,13 @@ export type UseOutsideClickOptions = {
   /**
    * Callback when an outside click occurred.
    */
-  onOutsideClick: (event: MouseEvent) => void;
+  onOutsideClick: (
+    event: TCheckOnTab extends true ? MouseEvent | KeyboardEvent : MouseEvent,
+  ) => void;
+  /**
+   * Whether the outside focus should also be checked when pressing the Tab key.
+   */
+  checkOnTab?: TCheckOnTab;
   /**
    * If `true`, event listeners will be removed and no outside clicks will be captured.
    */
@@ -22,19 +28,42 @@ export type UseOutsideClickOptions = {
  * Composable for listening to click events that occur outside of a component.
  * Useful to e.g. close flyouts or tooltips.
  */
-export const useOutsideClick = ({ inside, onOutsideClick, disabled }: UseOutsideClickOptions) => {
+export const useOutsideClick = <TCheckOnTab extends boolean | undefined>({
+  inside,
+  onOutsideClick,
+  disabled,
+  checkOnTab,
+}: UseOutsideClickOptions<TCheckOnTab>) => {
+  const isOutsideClick = (target: EventTarget | null) => {
+    if (!target) return true;
+    const raw = toValue(inside);
+    const elements = Array.isArray(raw) ? raw : [raw];
+    return !elements.some((element) => element?.contains(target as Node | null));
+  };
+
   /**
    * Document click handle that closes then tooltip when clicked outside.
    * Should only be called when trigger is "click".
    */
-  const listener = (event: MouseEvent) => {
-    const raw = toValue(inside);
-    const elements = Array.isArray(raw) ? raw : [raw];
-    const isOutsideClick = !elements.some((element) =>
-      element?.contains(event.target as HTMLElement),
-    );
-    if (isOutsideClick) onOutsideClick(event);
+  const clickListener = (event: MouseEvent) => {
+    if (isOutsideClick(event.target)) onOutsideClick(event);
   };
 
-  useGlobalEventListener({ type: "click", listener, disabled });
+  useGlobalEventListener({ type: "click", listener: clickListener, disabled });
+
+  if (checkOnTab) {
+    const keydownListener = async (event: KeyboardEvent) => {
+      if (event.key !== "Tab") return;
+
+      // using setTimeout here to guarantee that side effects that might change the document.activeElement have run before checking
+      // the activeElement
+      await new Promise((resolve) => setTimeout(resolve));
+
+      if (isOutsideClick(document.activeElement)) {
+        onOutsideClick(event as Parameters<typeof onOutsideClick>[0]);
+      }
+    };
+
+    useGlobalEventListener({ type: "keydown", listener: keydownListener, disabled });
+  }
 };

package/src/composables/menuButton/TestMenuButton.vue

@@ -1,5 +1,5 @@
 <script lang="ts" setup>
-import { ref, type Ref } from "vue";
+import { ref } from "vue";
 import { createMenuButton } from "./createMenuButton";
 
 const items = Array.from({ length: 10 }, (_, index) => {
@@ -10,7 +10,7 @@ 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 trigger = ref<"click" | "hover">("hover");
 
 const {
   elements: { root, button, menu, menuItem, listItem },

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

@@ -73,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

@@ -2,6 +2,7 @@ import { computed, useId, watch, type Ref } from "vue";
 import { createBuilder, createElRef } from "../../utils/builder";
 import { debounce } from "../../utils/timer";
 import { useGlobalEventListener } from "../helpers/useGlobalListener";
+import { useOutsideClick } from "../helpers/useOutsideClick";
 
 type CreateMenuButtonOptions = {
   isExpanded: Readonly<Ref<boolean>>;
@@ -16,6 +17,7 @@ type CreateMenuButtonOptions = {
 export const createMenuButton = createBuilder((options: CreateMenuButtonOptions) => {
   const rootId = useId();
   const menuId = useId();
+  const rootRef = createElRef<HTMLElement>();
   const menuRef = createElRef<HTMLElement>();
   const buttonId = useId();
 
@@ -52,7 +54,9 @@ export const createMenuButton = createBuilder((options: CreateMenuButtonOptions)
     const currentMenu = currentMenuItem?.closest('[role="menu"]') || menuRef.value;
     if (!currentMenu) return;
 
-    const menuItems = Array.from(currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]'));
+    const menuItems = Array.from(currentMenu.querySelectorAll<HTMLElement>('[role="menuitem"]'))
+      // filter out nested children
+      .filter((item) => item.closest('[role="menu"]') === currentMenu);
     let nextIndex = 0;
 
     if (currentMenuItem) {
@@ -80,12 +84,10 @@ export const createMenuButton = createBuilder((options: CreateMenuButtonOptions)
   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;
@@ -98,6 +100,7 @@ export const createMenuButton = createBuilder((options: CreateMenuButtonOptions)
         focusRelativeItem("last");
         break;
       case " ":
+      case "Enter":
         if (event.target instanceof HTMLInputElement) break;
         event.preventDefault();
         (event.target as HTMLElement).click();
@@ -109,32 +112,29 @@ export const createMenuButton = createBuilder((options: CreateMenuButtonOptions)
     }
   };
 
-  const triggerEvents = () => {
-    if (options.trigger.value === "hover") {
-      return {
-        onMouseenter: () => setExpanded(true),
-        onMouseleave: () => setExpanded(false, true),
-      };
-    }
-  };
+  const triggerEvents = computed(() => {
+    if (options.trigger.value !== "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: {
+      root: computed(() => ({
         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);
-        },
-      },
+        ref: rootRef,
+        ...triggerEvents.value,
+      })),
       button: computed(
         () =>
           ({
@@ -160,7 +160,25 @@ export const createMenuButton = createBuilder((options: CreateMenuButtonOptions)
   };
 });
 
-export const createMenuItems = createBuilder(() => {
+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: {
@@ -170,6 +188,7 @@ export const createMenuItems = createBuilder(() => {
         "aria-current": data.active ? "page" : undefined,
         "aria-disabled": data.disabled,
         role: "menuitem",
+        onKeydown,
       }),
     },
   };

package/src/utils/types.ts

@@ -30,4 +30,4 @@ export type Arrayable<T> = T | Array<T>;
 /**
  * Either the actual value or a nullish one.
  */
-export type Nullable<T> = T | null | undefined;
+export type Nullable<T = never> = T | null | undefined;