@sit-onyx/headless 1.0.0-beta.17 → 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.17",
+  "version": "1.0.0-beta.19",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -27,9 +27,9 @@
     "vue": ">= 3.5.0"
   },
   "devDependencies": {
-    "@vue/compiler-dom": "3.5.13",
-    "vue": "3.5.13",
-    "@sit-onyx/shared": "^1.0.0-beta.2"
+    "@vue/compiler-dom": "3.5.16",
+    "vue": "3.5.16",
+    "@sit-onyx/shared": "^1.0.0-beta.3"
   },
   "scripts": {
     "build": "vue-tsc --build --force",

package/src/composables/comboBox/SelectOnlyCombobox.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
-import { computed, ref } from "vue";
+import { computed, ref, useTemplateRef } from "vue";
 import { createComboBox } from "./createComboBox";
 
 const options = ["a", "b", "c", "d"];
 const isExpanded = ref(false);
-const comboboxRef = ref<HTMLElement>();
+const comboboxRef = useTemplateRef("combobox");
 const activeOption = ref("");
 const selectedOption = ref("");
 const selectedIndex = computed<number | undefined>(() => {
@@ -49,7 +49,7 @@ defineExpose({ comboBox });
 </script>
 
 <template>
-  <div ref="comboboxRef">
+  <div ref="combobox">
     <input
       v-bind="input"
       v-model="selectedOption"

package/src/composables/comboBox/TestCombobox.vue

@@ -1,11 +1,11 @@
 <script setup lang="ts">
-import { computed, ref } from "vue";
+import { computed, ref, useTemplateRef } from "vue";
 import { createComboBox } from "./createComboBox";
 
 const options = ["a", "b", "c", "d"];
 const isExpanded = ref(false);
 const searchTerm = ref("");
-const comboboxRef = ref<HTMLElement>();
+const comboboxRef = useTemplateRef("combobox");
 const activeOption = ref("");
 const filteredOptions = computed(() => options.filter((v) => v.includes(searchTerm.value)));
 const selectedIndex = computed<number | undefined>(() => {
@@ -53,7 +53,7 @@ defineExpose({ comboBox });
 </script>
 
 <template>
-  <div ref="comboboxRef">
+  <div ref="combobox">
     <input v-bind="input" v-model="searchTerm" @keydown.arrow-down="isExpanded = true" />
 
     <button v-bind="button" type="button">

package/src/composables/comboBox/createComboBox.ts

@@ -1,6 +1,7 @@
 import { computed, unref, useId, type MaybeRef, type Ref } from "vue";
 import { createBuilder } from "../../utils/builder";
 import { isPrintableCharacter, wasKeyPressed, type PressedKey } from "../../utils/keyboard";
+import type { Nullable } from "../../utils/types";
 import { useOutsideClick } from "../helpers/useOutsideClick";
 import { useTypeAhead } from "../helpers/useTypeAhead";
 import {
@@ -48,7 +49,7 @@ export type CreateComboboxOptions<
   /**
    * Provides additional description for the listbox which displays the available options.
    */
-  listDescription?: MaybeRef<string | undefined>;
+  listDescription?: MaybeRef<Nullable<string>>;
   /**
    * Controls the opened/visible state of the associated pop-up. When expanded the activeOption can be controlled via the keyboard.
    */
@@ -56,11 +57,11 @@ export type CreateComboboxOptions<
   /**
    * If expanded, the active option is the currently highlighted option of the controlled listbox.
    */
-  activeOption: Ref<TValue | undefined>;
+  activeOption: Ref<Nullable<TValue>>;
   /**
    * Template ref to the component root (required to close combobox on outside click).
    */
-  templateRef: Ref<HTMLElement | undefined>;
+  templateRef: Ref<Nullable<HTMLElement>>;
   /**
    * Hook when the popover should toggle.
    *

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

@@ -1,16 +1,23 @@
 import type { Arrayable } from "vitest"; // For an unknown reason removing this import will break the build of "demo-app" and "playground"
 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
    */
-  inside: MaybeRefOrGetter<Arrayable<HTMLElement | undefined>>;
+  inside: MaybeRefOrGetter<Arrayable<Nullable<HTMLElement>>>;
   /**
    * 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.
    */
@@ -21,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/listbox/createListbox.ts

@@ -1,5 +1,6 @@
 import { computed, nextTick, ref, unref, useId, watchEffect, type MaybeRef, type Ref } from "vue";
 import { createBuilder, type VBindAttributes } from "../../utils/builder";
+import type { Nullable } from "../../utils/types";
 import { useTypeAhead } from "../helpers/useTypeAhead";
 
 export type ListboxValue = string | number | boolean;
@@ -12,11 +13,11 @@ export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends
   /**
    * Aria description for the listbox.
    */
-  description?: MaybeRef<string | undefined>;
+  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.
@@ -29,7 +30,7 @@ export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends
   /**
    * Whether the listbox is multiselect.
    */
-  multiple?: MaybeRef<TMultiple | undefined>;
+  multiple?: MaybeRef<Nullable<TMultiple>>;
   /**
    * Hook when an option is selected.
    */

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

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

@@ -2,11 +2,13 @@ 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>>;
   trigger: Readonly<Ref<"hover" | "click">>;
   onToggle: () => void;
+  disabled?: Readonly<Ref<boolean>>;
 };
 
 /**
@@ -15,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();
 
@@ -31,6 +34,7 @@ export const createMenuButton = createBuilder((options: CreateMenuButtonOptions)
   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;
@@ -50,7 +54,9 @@ export const createMenuButton = createBuilder((options: CreateMenuButtonOptions)
     const currentMenu = currentMenuItem?.closest('[role="menu"]') || menuRef.value;
     if (!currentMenu) return;
 
-    const menuItems = [...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) {
@@ -78,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;
@@ -96,6 +100,8 @@ 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();
         break;
@@ -106,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(
         () =>
           ({
@@ -142,6 +145,7 @@ export const createMenuButton = createBuilder((options: CreateMenuButtonOptions)
             onClick: () =>
               options.trigger.value == "click" ? setExpanded(!options.isExpanded.value) : undefined,
             id: buttonId,
+            disabled: options.disabled?.value,
           }) as const,
       ),
       menu: {
@@ -156,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: {
@@ -166,6 +188,7 @@ export const createMenuItems = createBuilder(() => {
         "aria-current": data.active ? "page" : undefined,
         "aria-disabled": data.disabled,
         role: "menuitem",
+        onKeydown,
       }),
     },
   };

package/src/composables/navigationMenu/createMenu.ts

@@ -19,7 +19,7 @@ export const createNavigationMenu = createBuilder(({ navigationName }: CreateNav
   const getMenuButtons = () => {
     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

@@ -2,7 +2,6 @@ import { test } from "@playwright/experimental-ct-vue";
 import TestTabs from "./TestTabs.vue";
 import { tabsTesting } from "./createTabs.testing";
 
-// eslint-disable-next-line playwright/expect-expect
 test("tabs", async ({ mount, page }) => {
   const component = await mount(<TestTabs />);
 

package/src/composables/tooltip/createToggletip.ts

@@ -1,7 +1,6 @@
-import { computed, toRef, toValue, type MaybeRefOrGetter, type Ref } from "vue";
-import { createBuilder, createElRef } from "../../utils/builder";
+import { computed, toRef, toValue, useId, type MaybeRefOrGetter, type Ref } from "vue";
+import { createBuilder } from "../../utils/builder";
 import { useDismissible } from "../helpers/useDismissible";
-import { useOutsideClick } from "../helpers/useOutsideClick";
 
 export type CreateToggletipOptions = {
   toggleLabel: MaybeRefOrGetter<string>;
@@ -17,16 +16,9 @@ export type CreateToggletipOptions = {
  */
 export const createToggletip = createBuilder(
   ({ toggleLabel, isVisible }: CreateToggletipOptions) => {
-    const triggerRef = createElRef<HTMLButtonElement>();
-    const tooltipRef = createElRef<HTMLElement>();
-    const _isVisible = toRef(isVisible ?? false);
+    const triggerId = useId();
 
-    // close tooltip on outside click
-    useOutsideClick({
-      inside: computed(() => [triggerRef.value, tooltipRef.value]),
-      onOutsideClick: () => (_isVisible.value = false),
-      disabled: computed(() => !_isVisible.value),
-    });
+    const _isVisible = toRef(isVisible ?? false);
 
     useDismissible({ isExpanded: _isVisible });
 
@@ -39,7 +31,7 @@ export const createToggletip = createBuilder(
          * Preferably a `button` element.
          */
         trigger: computed(() => ({
-          ref: triggerRef,
+          id: triggerId,
           onClick: toggle,
           "aria-label": toValue(toggleLabel),
         })),
@@ -48,7 +40,12 @@ export const createToggletip = createBuilder(
          * Only simple, textual content is allowed.
          */
         tooltip: {
-          ref: tooltipRef,
+          onToggle: (e: Event) => {
+            const tooltip = e.target as HTMLDialogElement;
+            _isVisible.value = tooltip.matches(":popover-open");
+          },
+          anchor: triggerId,
+          popover: "auto",
           role: "status",
           tabindex: "-1",
         },

package/src/composables/tooltip/createTooltip.ts

@@ -57,6 +57,7 @@ export const createTooltip = createBuilder(({ debounce, isVisible }: CreateToolt
        * Only simple, textual and non-focusable content is allowed.
        */
       tooltip: {
+        popover: "manual",
         role: "tooltip",
         id: tooltipId,
         tabindex: "-1",

package/src/utils/builder.ts

@@ -29,7 +29,7 @@ export type IteratedHeadlessElementFunc<
 
 export type HeadlessElementAttributes<A extends HTMLAttributes> =
   | VBindAttributes<A>
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the specific type doesn't matter here
   | IteratedHeadlessElementFunc<A, any>;
 
 export type HeadlessElements = Record<string, MaybeRef<HeadlessElementAttributes<HTMLAttributes>>>;

package/src/utils/types.ts

@@ -26,3 +26,8 @@ export type IsArray<TValue, TMultiple extends boolean = false> = TMultiple exten
  * A type that can be wrapped in an array.
  */
 export type Arrayable<T> = T | Array<T>;
+
+/**
+ * Either the actual value or a nullish one.
+ */
+export type Nullable<T = never> = T | null | undefined;