@sit-onyx/headless 1.0.0-beta.4 → 1.0.0-beta.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/headless",
   "description": "Headless composables for Vue",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",

package/src/composables/comboBox/createComboBox.ts

@@ -10,6 +10,7 @@ import {
   type ListboxValue,
 } from "../listbox/createListbox";
 
+/** See https://w3c.github.io/aria/#aria-autocomplete */
 export type ComboboxAutoComplete = "none" | "list" | "both";
 
 export const OPENING_KEYS: PressedKey[] = ["ArrowDown", "ArrowUp", " ", "Enter", "Home", "End"];
@@ -19,11 +20,15 @@ export const CLOSING_KEYS: PressedKey[] = [
   "Enter",
   "Tab",
 ];
-const SELECTING_KEYS_SINGLE: PressedKey[] = ["Enter", " "];
-const SELECTING_KEYS_MULTIPLE: PressedKey[] = ["Enter"];
 
-const isSelectingKey = (event: KeyboardEvent, isMultiselect?: boolean) => {
-  const selectingKeys = isMultiselect ? SELECTING_KEYS_MULTIPLE : SELECTING_KEYS_SINGLE;
+const SELECTING_KEYS: PressedKey[] = ["Enter"];
+
+/**
+ * if the a search input is included, space should not be used to select
+ * TODO: idea for the future: move this distinction to the listbox?
+ */
+const isSelectingKey = (event: KeyboardEvent, withSpace?: boolean) => {
+  const selectingKeys = withSpace ? [...SELECTING_KEYS, " "] : SELECTING_KEYS;
   return isKeyOfGroup(event, selectingKeys);
 };
 
@@ -41,6 +46,10 @@ export type CreateComboboxOptions<
    * Labels the listbox which displays the available options. E.g. the list label could be "Countries" for a combobox which is labelled "Country".
    */
   listLabel: MaybeRef<string>;
+  /**
+   * Provides additional description for the listbox which displays the available options.
+   */
+  listDescription?: MaybeRef<string | undefined>;
   /**
    * Controls the opened/visible state of the associated pop-up. When expanded the activeOption can be controlled via the keyboard.
    */
@@ -107,6 +116,7 @@ export const createComboBox = createBuilder(
     multiple: multipleRef,
     label,
     listLabel,
+    listDescription,
     isExpanded: isExpandedRef,
     activeOption,
     onToggle,
@@ -183,7 +193,7 @@ export const createComboBox = createBuilder(
         }
         return onActivateFirst?.();
       }
-      if (isSelectingKey(event, multiple.value)) {
+      if (isSelectingKey(event, autocomplete.value === "none")) {
         return handleSelect(activeOption.value!);
       }
       if (isExpanded.value && isKeyOfGroup(event, CLOSING_KEYS)) {
@@ -213,14 +223,16 @@ export const createComboBox = createBuilder(
       internals: { getOptionId },
     } = createListbox({
       label: listLabel,
+      description: listDescription,
       multiple,
       controlled: true,
       activeOption,
+      isExpanded,
       onSelect: handleSelect,
     });
 
     useOutsideClick({
-      element: templateRef,
+      inside: templateRef,
       onOutsideClick() {
         if (!isExpanded.value) return;
         onToggle?.(true);

package/src/composables/helpers/useDismissible.ts

@@ -0,0 +1,19 @@
+import { computed, type Ref } from "vue";
+import { useGlobalEventListener } from "./useGlobalListener";
+
+type UseDismissibleOptions = { isExpanded: Ref<boolean> };
+
+/**
+ * Composable that sets `isExpanded` to false, when the `Escape` key is pressed.
+ * Addresses the "dismissible" aspect of https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html
+ */
+export const useDismissible = ({ isExpanded }: UseDismissibleOptions) =>
+  useGlobalEventListener({
+    type: "keydown",
+    listener: (e) => {
+      if (e.key === "Escape") {
+        isExpanded.value = false;
+      }
+    },
+    disabled: computed(() => !isExpanded.value),
+  });

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

@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ref } from "vue";
+import { mockVueLifecycle } from "../../utils/vitest";
+import { useOutsideClick } from "./useOutsideClick";
+
+describe("useOutsideClick", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockVueLifecycle();
+  });
+
+  it("should be defined", () => {
+    expect(useOutsideClick).toBeDefined();
+  });
+
+  it("should detect outside clicks", () => {
+    // ARRANGE
+    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 });
+    // ACT
+    const event = new MouseEvent("click", { bubbles: true });
+    outside.value.dispatchEvent(event);
+    // ASSERT
+    expect(onOutsideClick).toHaveBeenCalledTimes(1);
+    expect(onOutsideClick).toBeCalledWith(event);
+  });
+
+  it("should detect outside clicks correctly for multiple inside elements", () => {
+    // ARRANGE
+    const inside = [document.createElement("button"), document.createElement("button")];
+    inside.forEach((e) => document.body.appendChild(e));
+    const outside = ref(document.createElement("button"));
+    document.body.appendChild(outside.value);
+
+    const onOutsideClick = vi.fn();
+    useOutsideClick({ inside, onOutsideClick });
+    // ACT
+    const event = new MouseEvent("click", { bubbles: true });
+    inside[0].dispatchEvent(event);
+    inside[1].dispatchEvent(event);
+    // ASSERT
+    expect(onOutsideClick).not.toHaveBeenCalled();
+
+    // ACT
+    outside.value.dispatchEvent(event);
+    // ASSERT
+    expect(onOutsideClick).toHaveBeenCalledTimes(1);
+    expect(onOutsideClick).toBeCalledWith(event);
+  });
+
+  it("should ignore outside clicks when disabled", 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 disabled = ref(false);
+    const onOutsideClick = vi.fn();
+    useOutsideClick({ inside, disabled, onOutsideClick });
+
+    // ACT
+    const event = new MouseEvent("click", { bubbles: true });
+    outside.value.dispatchEvent(event);
+    // ASSERT
+    expect(onOutsideClick).toHaveBeenCalledTimes(1);
+    expect(onOutsideClick).toBeCalledWith(event);
+
+    // ACT
+    disabled.value = true;
+    await vi.runAllTimersAsync();
+    const event2 = new MouseEvent("click", { bubbles: true });
+    outside.value.dispatchEvent(event2);
+    // ASSERT
+    expect(onOutsideClick).toHaveBeenCalledTimes(1);
+  });
+});

package/src/composables/helpers/useOutsideClick.ts

@@ -1,15 +1,17 @@
-import { type Ref } from "vue";
+import type { Arrayable } from "vitest";
+import { toValue, type Ref } from "vue";
+import type { MaybeReactiveSource } from "../../utils/types";
 import { useGlobalEventListener } from "./useGlobalListener";
 
 export type UseOutsideClickOptions = {
   /**
    * HTML element of the component where clicks should be ignored
    */
-  element: Ref<HTMLElement | undefined>;
+  inside: MaybeReactiveSource<Arrayable<HTMLElement | undefined>>;
   /**
    * Callback when an outside click occurred.
    */
-  onOutsideClick: () => void;
+  onOutsideClick: (event: MouseEvent) => void;
   /**
    * If `true`, event listeners will be removed and no outside clicks will be captured.
    */
@@ -20,14 +22,18 @@ 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 = ({ element, onOutsideClick, disabled }: UseOutsideClickOptions) => {
+export const useOutsideClick = ({ inside, onOutsideClick, disabled }: UseOutsideClickOptions) => {
   /**
    * Document click handle that closes then tooltip when clicked outside.
    * Should only be called when trigger is "click".
    */
-  const listener = ({ target }: MouseEvent) => {
-    const isOutsideClick = !element.value?.contains(target as HTMLElement);
-    if (isOutsideClick) onOutsideClick();
+  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);
   };
 
   useGlobalEventListener({ type: "click", listener, disabled });

package/src/composables/listbox/TestListbox.vue

@@ -30,7 +30,9 @@ const {
   elements: { listbox, option: headlessOption },
 } = createListbox({
   label: "Test listbox",
+  description: "Test description",
   activeOption,
+  isExpanded: true,
   onSelect: (id) => {
     selectedOption.value = selectedOption.value === id ? undefined : id;
   },

package/src/composables/listbox/createListbox.ts

@@ -10,6 +10,10 @@ export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends
    * Aria label for the listbox.
    */
   label: MaybeRef<string>;
+  /**
+   * Aria description for the listbox.
+   */
+  description?: MaybeRef<string | undefined>;
   /**
    * Value of currently (visually) active option.
    */
@@ -19,6 +23,10 @@ export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends
    * 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.
    */
@@ -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
@@ -97,7 +106,11 @@ export const createListbox = createBuilder(
 
     // scroll currently active option into view if needed
     watchEffect(() => {
-      if (options.activeOption.value == undefined || (!isFocused.value && !options.controlled))
+      if (
+        !isExpanded.value ||
+        options.activeOption.value == undefined ||
+        (!isFocused.value && !options.controlled)
+      )
         return;
       const id = getOptionId(options.activeOption.value);
       document.getElementById(id)?.scrollIntoView({ block: "nearest", inline: "nearest" });
@@ -158,12 +171,14 @@ export const createListbox = createBuilder(
             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/tooltip/createToggletip.ts

@@ -0,0 +1,61 @@
+import { computed, toRef, toValue, type MaybeRefOrGetter, type Ref } from "vue";
+import { createBuilder, createElRef } from "../../utils/builder";
+import { useDismissible } from "../helpers/useDismissible";
+import { useOutsideClick } from "../helpers/useOutsideClick";
+
+export type CreateToggletipOptions = {
+  toggleLabel: MaybeRefOrGetter<string>;
+  isVisible?: Ref<boolean>;
+};
+
+/**
+ * Create a toggletip as described in https://inclusive-components.design/tooltips-toggletips/
+ * Its visibility is toggled on click.
+ * Therefore a toggletip MUST NOT be used to describe the associated trigger element.
+ * Commonly this pattern uses a button with the ⓘ as the trigger element.
+ * To describe the associated element use `createTooltip`.
+ */
+export const createToggletip = createBuilder(
+  ({ toggleLabel, isVisible }: CreateToggletipOptions) => {
+    const triggerRef = createElRef<HTMLButtonElement>();
+    const tooltipRef = createElRef<HTMLElement>();
+    const _isVisible = toRef(isVisible ?? false);
+
+    // close tooltip on outside click
+    useOutsideClick({
+      inside: computed(() => [triggerRef.value, tooltipRef.value]),
+      onOutsideClick: () => (_isVisible.value = false),
+      disabled: computed(() => !_isVisible.value),
+    });
+
+    useDismissible({ isExpanded: _isVisible });
+
+    const toggle = () => (_isVisible.value = !_isVisible.value);
+
+    return {
+      elements: {
+        /**
+         * The element which controls the toggletip visibility:
+         * Preferably a `button` element.
+         */
+        trigger: computed(() => ({
+          ref: triggerRef,
+          onClick: toggle,
+          "aria-label": toValue(toggleLabel),
+        })),
+        /**
+         * The element with the relevant toggletip content.
+         * Only simple, textual content is allowed.
+         */
+        tooltip: {
+          ref: tooltipRef,
+          role: "status",
+          tabindex: "-1",
+        },
+      },
+      state: {
+        isVisible: _isVisible,
+      },
+    };
+  },
+);

package/src/composables/tooltip/createTooltip.ts

@@ -1,44 +1,27 @@
-import { computed, onBeforeMount, onBeforeUnmount, ref, unref, type MaybeRef } from "vue";
+import { computed, toRef, toValue, type MaybeRefOrGetter, type Ref } from "vue";
 import { createId } from "../..";
-import { createBuilder, createElRef } from "../../utils/builder";
-import { useOutsideClick } from "../helpers/useOutsideClick";
+import { createBuilder } from "../../utils/builder";
+import { useDismissible } from "../helpers/useDismissible";
 
 export type CreateTooltipOptions = {
-  open: MaybeRef<TooltipOpen>;
+  /**
+   * Number of milliseconds to use as debounce when showing/hiding the tooltip.
+   */
+  debounce: MaybeRefOrGetter<number>;
+  isVisible?: Ref<boolean>;
 };
 
-export type TooltipOpen =
-  | TooltipTrigger
-  | boolean
-  | {
-      type: "hover";
-      /**
-       * Number of milliseconds to use as debounce when showing/hiding the tooltip
-       */
-      debounce: number;
-    };
-
-export const TOOLTIP_TRIGGERS = ["hover", "click"] as const;
-export type TooltipTrigger = (typeof TOOLTIP_TRIGGERS)[number];
-
-export const createTooltip = createBuilder((options: CreateTooltipOptions) => {
-  const rootRef = createElRef<HTMLElement>();
+/**
+ * Create a tooltip as described in https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role
+ * Its visibility is toggled on hover or focus.
+ * A tooltip MUST be used to describe the associated trigger element. E.g. The usage with the ⓘ would be incorrect.
+ * To provide contextual information use the `createToggletip`.
+ */
+export const createTooltip = createBuilder(({ debounce, isVisible }: CreateTooltipOptions) => {
   const tooltipId = createId("tooltip");
-  const _isVisible = ref(false);
+  const _isVisible = toRef(isVisible ?? false);
   let timeout: ReturnType<typeof setTimeout> | undefined;
 
-  const debounce = computed(() => {
-    const open = unref(options.open);
-    if (typeof open !== "object") return 200;
-    return open.debounce;
-  });
-
-  const openType = computed(() => {
-    const open = unref(options.open);
-    if (typeof open !== "object") return open;
-    return open.type;
-  });
-
   /**
    * Debounced visible state that will only be toggled after a given timeout.
    */
@@ -48,82 +31,41 @@ export const createTooltip = createBuilder((options: CreateTooltipOptions) => {
       clearTimeout(timeout);
       timeout = setTimeout(() => {
         _isVisible.value = newValue;
-      }, debounce.value);
+      }, toValue(debounce));
     },
   });
 
-  /**
-   * Whether the tooltip should be currently visible.
-   * If openMode is set as boolean it will prefer it over the hover/click state.
-   */
-  const isVisible = computed(() => {
-    if (typeof openType.value === "boolean") return openType.value;
-    return debouncedVisible.value;
-  });
-
-  /**
-   * Toggles the tooltip if element is clicked.
-   */
-  const handleClick = () => {
-    _isVisible.value = !_isVisible.value;
-  };
-
-  const hoverEvents = computed(() => {
-    if (openType.value !== "hover") return;
-    return {
-      onMouseover: () => (debouncedVisible.value = true),
-      onMouseout: () => (debouncedVisible.value = false),
-      onFocusin: () => (_isVisible.value = true),
-      onFocusout: () => (_isVisible.value = false),
-    };
-  });
-
-  /**
-   * Closes the tooltip if Escape is pressed.
-   */
-  const handleDocumentKeydown = (event: KeyboardEvent) => {
-    if (event.key !== "Escape") return;
-    _isVisible.value = false;
+  const hoverEvents = {
+    onMouseover: () => (debouncedVisible.value = true),
+    onMouseout: () => (debouncedVisible.value = false),
+    onFocusin: () => (_isVisible.value = true),
+    onFocusout: () => (_isVisible.value = false),
   };
 
-  // close tooltip on outside click
-  useOutsideClick({
-    element: rootRef,
-    onOutsideClick: () => (_isVisible.value = false),
-    disabled: computed(() => openType.value !== "click"),
-  });
-
-  // add global document event listeners only on/before mounted to also work in server side rendering
-  onBeforeMount(() => {
-    document.addEventListener("keydown", handleDocumentKeydown);
-  });
-
-  /**
-   * Clean up global event listeners to prevent dangling events.
-   */
-  onBeforeUnmount(() => {
-    document.removeEventListener("keydown", handleDocumentKeydown);
-  });
+  useDismissible({ isExpanded: _isVisible });
 
   return {
     elements: {
-      root: {
-        ref: rootRef,
-      },
-      trigger: computed(() => ({
+      /**
+       * The element which controls the tooltip visibility on hover.
+       */
+      trigger: {
         "aria-describedby": tooltipId,
-        onClick: openType.value === "click" ? handleClick : undefined,
-        ...hoverEvents.value,
-      })),
-      tooltip: computed(() => ({
+        ...hoverEvents,
+      },
+      /**
+       * The element describing the tooltip.
+       * Only simple, textual and non-focusable content is allowed.
+       */
+      tooltip: {
         role: "tooltip",
         id: tooltipId,
         tabindex: "-1",
-        ...hoverEvents.value,
-      })),
+        ...hoverEvents,
+      },
     },
     state: {
-      isVisible,
+      isVisible: _isVisible,
     },
   };
 });

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./composables/comboBox/createComboBox";
 export * from "./composables/listbox/createListbox";
 export * from "./composables/menuButton/createMenuButton";
 export * from "./composables/navigationMenu/createMenu";
+export * from "./composables/tooltip/createToggletip";
 export * from "./composables/tooltip/createTooltip";
 export * from "./utils/builder";
 export { createId } from "./utils/id";

package/src/utils/builder.ts

@@ -11,7 +11,8 @@ import {
 import type { IfDefined } from "./types";
 
 /**
- * `v-bind`able attributes as they are provided by the headless composables.
+ * Properties as they can be used by `v-bind` on an HTML element.
+ * This includes generic html attributes and the vue reserved `ref` property.
  * `ref` is restricted to be a `HeadlessElRef` which only can by created through `createElRef`.
  */
 export type VBindAttributes<

package/src/utils/types.ts

@@ -1,3 +1,5 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
 /**
  * Adds the entry with the key `Key` and the value of type `TValue` to a record when it is defined.
  * Then the entry is either undefined or exists without being optional.
@@ -21,3 +23,8 @@ export type IfDefined<Key extends string, TValue> =
 export type IsArray<TValue, TMultiple extends boolean = false> = TMultiple extends true
   ? TValue[]
   : TValue;
+
+/**
+ * Type for any kind of ref source. Preferably used in combination with vue's `toValue` method
+ */
+export type MaybeReactiveSource<T> = MaybeRefOrGetter<T> | ComputedRef<T>;

package/src/utils/vitest.ts

@@ -1,6 +1,6 @@
-import { vi, type Awaitable } from "vitest";
+import { vi } from "vitest";
 
-type Callback = () => Awaitable<void>;
+type Callback = () => void | (() => Promise<void>);
 
 /**
  * Mocks the following vue lifecycle functions: