@sit-onyx/headless 1.0.0-beta.2 → 1.0.0-beta.20

package/src/composables/tabs/createTabs.ts

@@ -0,0 +1,129 @@
+import { computed, unref, useId, type MaybeRef, type Ref } from "vue";
+import { createBuilder } from "../../utils/builder";
+
+type CreateTabsOptions<TKey extends PropertyKey = PropertyKey> = {
+  /**
+   * Label of the tablist.
+   */
+  label: MaybeRef<string>;
+  /**
+   * Currently selected tab.
+   */
+  selectedTab: Ref<TKey>;
+  /**
+   * Called when the user selects a tab.
+   */
+  onSelect?: (selectedTabValue: TKey) => void;
+};
+
+/**
+ * Composable for implementing accessible tabs.
+ * Based on https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ */
+export const createTabs = createBuilder(<T extends PropertyKey>(options: CreateTabsOptions<T>) => {
+  /**
+   * Map for looking up tab and panel IDs for given tab keys/values defined by the user.
+   * Key = custom value from the user, value = random generated tab and panel ID
+   */
+  const idMap = new Map<T, { tabId: string; panelId: string }>();
+
+  const getId = (value: T) => {
+    if (!idMap.has(value)) {
+      idMap.set(value, { tabId: useId(), panelId: useId() });
+    }
+    return idMap.get(value)!;
+  };
+
+  const handleKeydown = (event: KeyboardEvent) => {
+    const tab = event.target as Element;
+
+    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 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":
+        focusTab("next");
+        break;
+      case "ArrowLeft":
+        focusTab("previous");
+        break;
+      case "Home":
+        focusFirstTab();
+        break;
+      case "End":
+        focusLastTab();
+        break;
+      case "Enter":
+      case " ":
+        {
+          const tabEntry = Array.from(idMap.entries()).find(([, { tabId }]) => tabId === tab.id);
+          if (tabEntry) options.onSelect?.(tabEntry[0]);
+        }
+        break;
+    }
+  };
+
+  return {
+    elements: {
+      tablist: computed(() => ({
+        role: "tablist",
+        "aria-label": unref(options.label),
+        onKeydown: handleKeydown,
+      })),
+      tab: computed(() => {
+        return (data: { value: T; disabled?: boolean }) => {
+          const { tabId: selectedTabId } = getId(unref(options.selectedTab));
+          const { tabId, panelId } = getId(data.value);
+          const isSelected = tabId === selectedTabId;
+
+          return {
+            id: tabId,
+            role: "tab",
+            "aria-selected": isSelected,
+            "aria-controls": panelId,
+            "aria-disabled": data.disabled ? true : undefined,
+            onClick: () => options.onSelect?.(data.value),
+            tabindex: isSelected && !data.disabled ? 0 : -1,
+          } as const;
+        };
+      }),
+      tabpanel: computed(() => {
+        return (data: { value: T }) => {
+          const { tabId, panelId } = getId(data.value);
+
+          return {
+            id: panelId,
+            role: "tabpanel",
+            "aria-labelledby": tabId,
+          } as const;
+        };
+      }),
+    },
+  };
+});

package/src/composables/tooltip/createToggletip.ts

@@ -0,0 +1,58 @@
+import { computed, toRef, toValue, useId, type MaybeRefOrGetter, type Ref } from "vue";
+import { createBuilder } from "../../utils/builder";
+import { useDismissible } from "../helpers/useDismissible";
+
+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 triggerId = useId();
+
+    const _isVisible = toRef(isVisible ?? false);
+
+    useDismissible({ isExpanded: _isVisible });
+
+    const toggle = () => (_isVisible.value = !_isVisible.value);
+
+    return {
+      elements: {
+        /**
+         * The element which controls the toggletip visibility:
+         * Preferably a `button` element.
+         */
+        trigger: computed(() => ({
+          id: triggerId,
+          onClick: toggle,
+          "aria-label": toValue(toggleLabel),
+        })),
+        /**
+         * The element with the relevant toggletip content.
+         * Only simple, textual content is allowed.
+         */
+        tooltip: {
+          onToggle: (e: Event) => {
+            const tooltip = e.target as HTMLDialogElement;
+            _isVisible.value = tooltip.matches(":popover-open");
+          },
+          anchor: triggerId,
+          popover: "auto",
+          role: "status",
+          tabindex: "-1",
+        },
+      },
+      state: {
+        isVisible: _isVisible,
+      },
+    };
+  },
+);

package/src/composables/tooltip/createTooltip.ts

@@ -1,44 +1,26 @@
-import { computed, onBeforeMount, onBeforeUnmount, ref, unref, type MaybeRef } from "vue";
-import { createId } from "../..";
+import { computed, toRef, toValue, useId, type MaybeRefOrGetter, type Ref } from "vue";
 import { createBuilder } from "../../utils/builder";
-import { useOutsideClick } from "../helpers/useOutsideClick";
+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 = ref<HTMLElement>();
-  const tooltipId = createId("tooltip");
-  const _isVisible = ref(false);
+/**
+ * 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 = useId();
+  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 +30,42 @@ 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: {
+        popover: "manual",
         role: "tooltip",
         id: tooltipId,
         tabindex: "-1",
-        ...hoverEvents.value,
-      })),
+        ...hoverEvents,
+      },
     },
     state: {
-      isVisible,
+      isVisible: _isVisible,
     },
   };
 });

package/src/index.ts

@@ -1,8 +1,11 @@
 export * from "./composables/comboBox/createComboBox";
+export * from "./composables/helpers/useGlobalListener";
 export * from "./composables/listbox/createListbox";
 export * from "./composables/menuButton/createMenuButton";
 export * from "./composables/navigationMenu/createMenu";
+export * from "./composables/tabs/createTabs";
+export * from "./composables/tooltip/createToggletip";
 export * from "./composables/tooltip/createTooltip";
-export { createId } from "./utils/id";
+export * from "./utils/builder";
 export { isPrintableCharacter, wasKeyPressed } from "./utils/keyboard";
 export { debounce } from "./utils/timer";

package/src/playwright.ts

@@ -1,3 +1,5 @@
 export * from "./composables/comboBox/createComboBox.testing";
 export * from "./composables/listbox/createListbox.testing";
 export * from "./composables/menuButton/createMenuButton.testing";
+export * from "./composables/navigationMenu/createMenu.testing";
+export * from "./composables/tabs/createTabs.testing";

package/src/utils/builder.ts

@@ -1,19 +1,38 @@
-import type { ComputedRef, HtmlHTMLAttributes, Ref, VNodeRef } from "vue";
+import {
+  computed,
+  shallowRef,
+  type ComponentPublicInstance,
+  type HTMLAttributes,
+  type MaybeRef,
+  type Ref,
+  type WritableComputedOptions,
+  type WritableComputedRef,
+} from "vue";
 import type { IfDefined } from "./types";
 
-export type ElementAttributes = HtmlHTMLAttributes & { ref?: VNodeRef };
+/**
+ * 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<
+  A extends HTMLAttributes = HTMLAttributes,
+  E extends Element = Element,
+> = A & {
+  ref?: VueTemplateRef<E>;
+};
 
-export type IteratedHeadlessElementFunc<T extends Record<string, unknown>> = (
-  opts: T,
-) => ElementAttributes;
+export type IteratedHeadlessElementFunc<
+  A extends HTMLAttributes,
+  T extends Record<string, unknown>,
+> = (opts: T) => VBindAttributes<A>;
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type HeadlessElementAttributes = ElementAttributes | IteratedHeadlessElementFunc<any>;
+export type HeadlessElementAttributes<A extends HTMLAttributes> =
+  | VBindAttributes<A>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the specific type doesn't matter here
+  | IteratedHeadlessElementFunc<A, any>;
 
-export type HeadlessElements = Record<
-  string,
-  HeadlessElementAttributes | ComputedRef<HeadlessElementAttributes>
->;
+export type HeadlessElements = Record<string, MaybeRef<HeadlessElementAttributes<HTMLAttributes>>>;
 
 export type HeadlessState = Record<string, Ref>;
 
@@ -28,6 +47,39 @@ export type HeadlessComposable<
 
 /**
  * We use this identity function to ensure the correct typings of the headless composables
+ * @example
+ * ```ts
+ * export const createTooltip = createBuilder(({ initialVisible }: CreateTooltipOptions) => {
+ *   const tooltipId = useId();
+ *   const isVisible = ref(initialVisible);
+ *
+ *   const hoverEvents = {
+ *     onMouseover: () => (isVisible.value = true),
+ *     onMouseout: () => (isVisible.value = false),
+ *     onFocusin: () => (isVisible.value = true),
+ *     onFocusout: () => (isVisible.value = false),
+ *   };
+ *
+ *   return {
+ *     elements: {
+ *       trigger: {
+ *         "aria-describedby": tooltipId,
+ *         ...hoverEvents,
+ *       },
+ *       tooltip: {
+ *         role: "tooltip",
+ *         id: tooltipId,
+ *         tabindex: "-1",
+ *         ...hoverEvents,
+ *       },
+ *     },
+ *     state: {
+ *       isVisible,
+ *     },
+ *   };
+ * });
+ *
+ * ```
  */
 export const createBuilder = <
   Args extends unknown[] = unknown[],
@@ -37,3 +89,47 @@ export const createBuilder = <
 >(
   builder: (...args: Args) => HeadlessComposable<Elements, State, Internals>,
 ) => builder;
+
+type VueTemplateRefElement<E extends Element> = E | (ComponentPublicInstance & { $el: E }) | null;
+type VueTemplateRef<E extends Element> = Ref<VueTemplateRefElement<E>>;
+
+declare const HeadlessElRefSymbol: unique symbol;
+type HeadlessElRef<E extends Element> = WritableComputedRef<E> & {
+  /**
+   * type differentiator
+   * ensures that only `createElRef` can be used for headless element ref bindings
+   */
+  [HeadlessElRefSymbol]: true;
+};
+
+/**
+ * Creates a special writeable computed that references a DOM Element.
+ * Vue Component references will be unwrapped.
+ * @example
+ * ```ts
+ * createBuilder() => {
+ *  const buttonRef = createElRef<HtmlButtonElement>();
+ *  return {
+ *    elements: {
+ *      button: {
+ *        ref: buttonRef,
+ *      },
+ *    }
+ *  };
+ * });
+ * ```
+ */
+export function createElRef<E extends Element>(): HeadlessElRef<E>;
+export function createElRef<
+  E extends Element,
+  V extends VueTemplateRefElement<E> = VueTemplateRefElement<E>,
+>() {
+  const elementRef = shallowRef<E>();
+
+  return computed({
+    set: (element: V) => {
+      elementRef.value = element != null && "$el" in element ? element.$el : (element as E);
+    },
+    get: () => elementRef.value,
+  } as WritableComputedOptions<E>);
+}

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;
 };

package/src/utils/types.ts

@@ -21,3 +21,13 @@ export type IfDefined<Key extends string, TValue> =
 export type IsArray<TValue, TMultiple extends boolean = false> = TMultiple extends true
   ? TValue[]
   : TValue;
+
+/**
+ * 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;

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:

package/src/utils/id.ts

@@ -1,14 +0,0 @@
-/**
- * Returns a unique global id string
- */
-// ⚠️ we make use of an IIFE to encapsulate the globalCounter so it can never accidentally be used somewhere else.
-const nextId = (() => {
-  let globalCounter = 1;
-  return () => globalCounter++;
-})();
-
-/**
- * Creates a globally unique string using a counter.
- * The given name is the prefix.
- */
-export const createId = (name: string) => `${name}-${nextId()}`;