@sit-onyx/headless 1.0.0-beta.7 → 1.0.0-beta.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/headless",
   "description": "Headless composables for Vue",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -24,7 +24,11 @@
   },
   "peerDependencies": {
     "typescript": ">= 5",
-    "vue": ">= 3"
+    "vue": ">= 3.5.0"
+  },
+  "devDependencies": {
+    "@vue/compiler-dom": "3.5.12",
+    "vue": "3.5.12"
   },
   "scripts": {
     "build": "vue-tsc --build --force",

package/src/composables/comboBox/TestCombobox.vue

@@ -56,11 +56,11 @@ defineExpose({ comboBox });
   <div ref="comboboxRef">
     <input v-bind="input" v-model="searchTerm" @keydown.arrow-down="isExpanded = true" />
 
-    <button v-bind="button">
-      <template v-if="isExpanded">⬆️</template>
-      <template v-else>⬇️</template>
+    <button v-bind="button" type="button">
+      <template v-if="isExpanded"> ⬆️ </template>
+      <template v-else> ⬇️ </template>
     </button>
-    <ul v-bind="listbox" :class="{ hidden: !isExpanded }" style="width: 400px">
+    <ul v-bind="listbox" :class="{ list: true, hidden: !isExpanded }">
       <li
         v-for="e in filteredOptions"
         :key="e"
@@ -74,6 +74,10 @@ defineExpose({ comboBox });
 </template>
 
 <style>
+.list {
+  width: 400px;
+}
+
 .hidden {
   display: none;
 }

package/src/composables/comboBox/createComboBox.ts

@@ -1,6 +1,5 @@
-import { computed, unref, type MaybeRef, type Ref } from "vue";
+import { computed, unref, useId, type MaybeRef, type Ref } from "vue";
 import { createBuilder } from "../../utils/builder";
-import { createId } from "../../utils/id";
 import { isPrintableCharacter, wasKeyPressed, type PressedKey } from "../../utils/keyboard";
 import { useOutsideClick } from "../helpers/useOutsideClick";
 import { useTypeAhead } from "../helpers/useTypeAhead";
@@ -127,7 +126,7 @@ export const createComboBox = createBuilder(
     onActivatePrevious,
     templateRef,
   }: CreateComboboxOptions<TValue, TAutoComplete, TMultiple>) => {
-    const controlsId = createId("comboBox-control");
+    const controlsId = useId();
 
     const autocomplete = computed(() => unref(autocompleteRef));
     const isExpanded = computed(() => unref(isExpandedRef));

package/src/composables/listbox/createListbox.ts

@@ -1,5 +1,4 @@
-import { computed, nextTick, ref, unref, watchEffect, type MaybeRef, type Ref } from "vue";
-import { createId } from "../..";
+import { computed, nextTick, ref, unref, useId, watchEffect, type MaybeRef, type Ref } from "vue";
 import { createBuilder, type VBindAttributes } from "../../utils/builder";
 import { useTypeAhead } from "../helpers/useTypeAhead";
 
@@ -94,7 +93,7 @@ export const createListbox = createBuilder(
 
     const getOptionId = (value: TValue) => {
       if (!descendantKeyIdMap.has(value)) {
-        descendantKeyIdMap.set(value, createId("listbox-option"));
+        descendantKeyIdMap.set(value, useId());
       }
       return descendantKeyIdMap.get(value)!;
     };

package/src/composables/menuButton/createMenuButton.ts

@@ -1,6 +1,5 @@
-import { computed, type Ref } from "vue";
+import { computed, useId, type Ref } from "vue";
 import { createBuilder, createElRef } from "../../utils/builder";
-import { createId } from "../../utils/id";
 import { debounce } from "../../utils/timer";
 import { useGlobalEventListener } from "../helpers/useGlobalListener";
 
@@ -14,10 +13,10 @@ type CreateMenuButtonOptions = {
  */
 export const createMenuButton = createBuilder(
   ({ isExpanded, onToggle }: CreateMenuButtonOptions) => {
-    const rootId = createId("menu-button-root");
-    const menuId = createId("menu-button-list");
+    const rootId = useId();
+    const menuId = useId();
     const menuRef = createElRef<HTMLElement>();
-    const buttonId = createId("menu-button-button");
+    const buttonId = useId();
 
     useGlobalEventListener({
       type: "keydown",
@@ -106,7 +105,10 @@ export const createMenuButton = createBuilder(
           onMouseout: () => updateDebouncedExpanded(false),
           onFocusout: (event) => {
             // if focus receiving element is not part of the menu button, then close
-            if (document.getElementById(rootId)?.contains(event.relatedTarget as HTMLElement)) {
+            if (
+              rootId &&
+              document.getElementById(rootId)?.contains(event.relatedTarget as HTMLElement)
+            ) {
               return;
             }
             isExpanded.value && onToggle();

package/src/composables/navigationMenu/createMenu.ts

@@ -1,5 +1,4 @@
-import { unref, type MaybeRef } from "vue";
-import { createId } from "../..";
+import { unref, useId, type MaybeRef } from "vue";
 import { createBuilder } from "../../utils/builder";
 import { MathUtils } from "../../utils/math";
 
@@ -15,10 +14,10 @@ type CreateNavigationMenu = {
  * Based on https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/
  */
 export const createNavigationMenu = createBuilder(({ navigationName }: CreateNavigationMenu) => {
-  const navId = createId("nav");
+  const navId = useId();
 
   const getMenuButtons = () => {
-    const nav = document.getElementById(navId);
+    const nav = navId ? document.getElementById(navId) : undefined;
     if (!nav) return [];
     return [...nav.querySelectorAll<HTMLElement>("button[aria-expanded][aria-controls]")];
   };

package/src/composables/tabs/TestTabs.ct.tsx

@@ -0,0 +1,13 @@
+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 />);
+
+  await tabsTesting({
+    page,
+    tablist: component.getByRole("tablist"),
+  });
+});

package/src/composables/tabs/TestTabs.vue

@@ -0,0 +1,26 @@
+<script lang="ts" setup>
+import { ref } from "vue";
+import { createTabs } from "./createTabs";
+
+const selectedTab = ref("tab-1");
+
+const {
+  elements: { tablist, tab, tabpanel },
+} = createTabs({
+  label: "Tablist label",
+  selectedTab,
+  onSelect: (tab) => (selectedTab.value = tab),
+});
+</script>
+
+<template>
+  <div>
+    <div v-bind="tablist">
+      <button v-bind="tab({ value: 'tab-1' })" type="button">Tab 1</button>
+      <button v-bind="tab({ value: 'tab-2' })" type="button">Tab 2</button>
+    </div>
+
+    <div v-if="selectedTab === 'tab-1'" v-bind="tabpanel({ value: 'tab-1' })">Tab content 1</div>
+    <div v-if="selectedTab === 'tab-2'" v-bind="tabpanel({ value: 'tab-2' })">Tab content 2</div>
+  </div>
+</template>

package/src/composables/tabs/createTabs.testing.ts

@@ -0,0 +1,78 @@
+import { expect } from "@playwright/experimental-ct-vue";
+import type { Locator, Page } from "@playwright/test";
+
+export type TabsTestingOptions = {
+  page: Page;
+  /**
+   * Locator of the tabs component.
+   */
+  tablist: Locator;
+};
+
+/**
+ * Playwright utility for executing accessibility testing for tabs.
+ * Will check aria attributes and keyboard shortcuts as defined in https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ */
+export const tabsTesting = async (options: TabsTestingOptions) => {
+  await expect(options.tablist, 'tablist element must have role "tablist"').toHaveRole("tablist");
+  await expect(options.tablist, "tablist must have an accessible label").toHaveAttribute(
+    "aria-label",
+  );
+
+  const activeTab = options.tablist.locator('[aria-selected="true"]');
+  await expect(activeTab, "must have an initially active tab").toBeVisible();
+
+  const { tabId, panelId } = await expectTabAttributes(activeTab, true);
+  await expectPanelAttributes(options.page.locator(`#${panelId}`), tabId);
+
+  // ACT (switch tab)
+  const tab2 = options.tablist.locator('[aria-selected="true"]').first();
+  await tab2.click();
+
+  const { tabId: tabId2, panelId: panelId2 } = await expectTabAttributes(tab2, true);
+  await expectPanelAttributes(options.page.locator(`#${panelId2}`), tabId2);
+
+  await expect(options.page.getByRole("tabpanel"), "should hide previous panel").toHaveCount(1);
+};
+
+/**
+ * Executes accessibility tests for a single tab.
+ *
+ * @param tab Locator of the tab.
+ * @param selected Whether the tab is expected to be selected
+ */
+const expectTabAttributes = async (tab: Locator, selected: boolean) => {
+  await expect(tab, 'tab must have role "tab"').toHaveRole("tab");
+  await expect(tab, "tab must have an ID").toHaveAttribute("id");
+  await expect(tab, 'tab must have "aria-selected" set').toHaveAttribute(
+    "aria-selected",
+    String(selected),
+  );
+  await expect(tab, 'tab must have "aria-controls" set').toHaveAttribute("aria-controls");
+
+  if (selected) {
+    await expect(tab, "selected tab should be focusable").toHaveAttribute("tabindex", "0");
+  } else {
+    await expect(tab, "unselected tab should NOT be focusable").toHaveAttribute("tabindex", "-1");
+  }
+
+  const tabId = (await tab.getAttribute("id"))!;
+  const panelId = (await tab.getAttribute("aria-controls"))!;
+  return { tabId, panelId };
+};
+
+/**
+ * Executes accessibility tests for a single tab panel.
+ *
+ * @param panel Locator of the panel
+ * @param tabId Corresponding tab id
+ */
+const expectPanelAttributes = async (panel: Locator, tabId: string) => {
+  await expect(panel, "panel should be visible").toBeVisible();
+  await expect(panel, 'panel must have role "tabpanel"').toHaveRole("tabpanel");
+  await expect(panel, "panel must have an ID").toHaveAttribute("id");
+  await expect(panel, 'panel must have "aria-labelledby" set').toHaveAttribute(
+    "aria-labelledby",
+    tabId,
+  );
+};

package/src/composables/tabs/createTabs.ts

@@ -0,0 +1,72 @@
+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<PropertyKey, { tabId: string; panelId: string }>();
+
+  const getId = (value: PropertyKey) => {
+    if (!idMap.has(value)) {
+      idMap.set(value, { tabId: useId(), panelId: useId() });
+    }
+    return idMap.get(value)!;
+  };
+
+  return {
+    elements: {
+      tablist: computed(() => ({
+        role: "tablist",
+        "aria-label": unref(options.label),
+      })),
+      tab: computed(() => {
+        return (data: { value: T }) => {
+          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,
+            onClick: () => options.onSelect?.(data.value),
+            tabindex: isSelected ? 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/createTooltip.ts

@@ -1,5 +1,4 @@
-import { computed, toRef, toValue, type MaybeRefOrGetter, type Ref } from "vue";
-import { createId } from "../..";
+import { computed, toRef, toValue, useId, type MaybeRefOrGetter, type Ref } from "vue";
 import { createBuilder } from "../../utils/builder";
 import { useDismissible } from "../helpers/useDismissible";
 
@@ -18,7 +17,7 @@ export type CreateTooltipOptions = {
  * To provide contextual information use the `createToggletip`.
  */
 export const createTooltip = createBuilder(({ debounce, isVisible }: CreateTooltipOptions) => {
-  const tooltipId = createId("tooltip");
+  const tooltipId = useId();
   const _isVisible = toRef(isVisible ?? false);
   let timeout: ReturnType<typeof setTimeout> | undefined;
 

package/src/index.ts

@@ -1,10 +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 * from "./utils/builder";
-export { createId } from "./utils/id";
 export { isPrintableCharacter, wasKeyPressed } from "./utils/keyboard";
 export { debounce } from "./utils/timer";

package/src/playwright.ts

@@ -2,3 +2,4 @@ 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

@@ -50,7 +50,7 @@ export type HeadlessComposable<
  * @example
  * ```ts
  * export const createTooltip = createBuilder(({ initialVisible }: CreateTooltipOptions) => {
- *   const tooltipId = createId("tooltip");
+ *   const tooltipId = useId();
  *   const isVisible = ref(initialVisible);
  *
  *   const hoverEvents = {

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()}`;