@sit-onyx/headless 1.0.0-beta.8 → 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.8",
+  "version": "1.0.0-beta.9",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",
@@ -27,8 +27,8 @@
     "vue": ">= 3.5.0"
   },
   "devDependencies": {
-    "@vue/compiler-dom": "^3.5.0",
-    "vue": "^3.5.0"
+    "@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/listbox/createListbox.ts

@@ -93,7 +93,7 @@ export const createListbox = createBuilder(
 
     const getOptionId = (value: TValue) => {
       if (!descendantKeyIdMap.has(value)) {
-        descendantKeyIdMap.set(value, useId() ?? value.toString());
+        descendantKeyIdMap.set(value, useId());
       }
       return descendantKeyIdMap.get(value)!;
     };

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/index.ts

@@ -1,7 +1,9 @@
 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";

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