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

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

@@ -1,12 +0,0 @@
-import { test } from "@playwright/experimental-ct-vue";
-import TestTabs from "./TestTabs.vue";
-import { tabsTesting } from "./createTabs.testing";
-
-test("tabs", async ({ mount, page }) => {
-  const component = await mount(<TestTabs />);
-
-  await tabsTesting({
-    page,
-    tablist: component.getByRole("tablist"),
-  });
-});

package/src/composables/tabs/TestTabs.vue

@@ -1,28 +0,0 @@
-<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>
-      <button v-bind="tab({ value: 'tab-3' })" type="button">Tab 3</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 v-if="selectedTab === 'tab-3'" v-bind="tabpanel({ value: 'tab-3' })">Tab content 3</div>
-  </div>
-</template>

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

@@ -1,151 +0,0 @@
-import { expect } from "@playwright/experimental-ct-vue";
-import type { Locator, Page } from "@playwright/test";
-
-export type TabsTestingOptions = {
-  page: Page;
-  /**
-   * Locator of the tabs component. Must have at least 3 tabs where the first one is initially selected.
-   */
-  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 firstTab = options.tablist.getByRole("tab").first();
-  const secondTab = options.tablist.getByRole("tab").nth(1);
-  const lastTab = options.tablist.getByRole("tab").last();
-
-  const { tabId, panelId } = await expectTabAttributes(firstTab, true);
-  await expectPanelAttributes(options.page.locator(`#${panelId}`), tabId);
-
-  // ACT (switch tab)
-  await secondTab.click();
-
-  const { tabId: tabId2, panelId: panelId2 } = await expectTabAttributes(secondTab, true);
-  await expectPanelAttributes(options.page.locator(`#${panelId2}`), tabId2);
-  await expect(secondTab, "second tab should be focused").toBeFocused();
-
-  await expect(options.page.getByRole("tabpanel"), "should hide previous panel").toHaveCount(1);
-
-  // keyboard support
-  await options.page.keyboard.press("ArrowLeft");
-  await expect(firstTab, "should focus previous tab when pressing arrow left").toBeFocused();
-
-  await options.page.keyboard.press("End");
-  await expect(lastTab, "should focus last tab when pressing End").toBeFocused();
-
-  await options.page.keyboard.press("ArrowRight");
-  await expect(
-    firstTab,
-    "should focus first tab when last tab is focused and pressing arrow right",
-  ).toBeFocused();
-
-  await options.page.keyboard.press("ArrowRight");
-  await expect(secondTab, "should focus next tab when pressing arrow right").toBeFocused();
-
-  await options.page.keyboard.press("Home");
-  await expect(firstTab, "should focus first tab when pressing Home").toBeFocused();
-
-  await options.page.keyboard.press("ArrowLeft");
-
-  await expect(
-    lastTab,
-    "should focus last tab when first tab is focused and pressing arrow left",
-  ).toBeFocused();
-
-  // should select when pressing Enter
-  await options.page.keyboard.press("Enter");
-  const { tabId: tabIdLast, panelId: panelIdLast } = await expectTabAttributes(lastTab, true);
-  await expectPanelAttributes(options.page.locator(`#${panelIdLast}`), tabIdLast);
-
-  // should select when pressing Space
-  await firstTab.focus();
-  await options.page.keyboard.press("Space");
-  const { tabId: tabIdFirst, panelId: panelIdFirst } = await expectTabAttributes(firstTab, true);
-  await expectPanelAttributes(options.page.locator(`#${panelIdFirst}`), tabIdFirst);
-
-  // should skip disabled tabs when using the keyboard
-  await firstTab.click();
-  await secondTab.evaluate((element) => (element.ariaDisabled = "true"));
-  await expect(secondTab, "should disable second tab when setting aria-disabled").toBeDisabled();
-
-  await options.page.keyboard.press("ArrowRight");
-  await expect(secondTab, "should not focus second tab if its aria-disabled").not.toBeFocused();
-  await expect(
-    options.tablist.getByRole("tab").nth(2),
-    "should focus next tab after disabled one when pressing arrow right",
-  ).toBeFocused();
-
-  await options.page.keyboard.press("ArrowLeft");
-  await expect(
-    firstTab,
-    "should focus tab before disabled one when pressing arrow left",
-  ).toBeFocused();
-
-  await secondTab.evaluate((element) => (element.ariaDisabled = null));
-  await firstTab.evaluate((element) => (element.ariaDisabled = "true"));
-  await options.page.keyboard.press("Home");
-  await expect(
-    secondTab,
-    "should focus second tab when pressing Home if first tab is disabled",
-  ).toBeFocused();
-
-  await firstTab.evaluate((element) => (element.ariaDisabled = null));
-  await lastTab.evaluate((element) => (element.ariaDisabled = "true"));
-  await firstTab.focus();
-  await options.page.keyboard.press("End");
-  await expect(
-    options.tablist.getByRole("tab").nth(-2),
-    "should focus second last tab when pressing End if last tab is disabled",
-  ).toBeFocused();
-};
-
-/**
- * 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

@@ -1,129 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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,71 +0,0 @@
-import { computed, toRef, toValue, useId, type MaybeRefOrGetter, type Ref } from "vue";
-import { createBuilder } from "../../utils/builder";
-import { useDismissible } from "../helpers/useDismissible";
-
-export type CreateTooltipOptions = {
-  /**
-   * Number of milliseconds to use as debounce when showing/hiding the tooltip.
-   */
-  debounce: MaybeRefOrGetter<number>;
-  isVisible?: Ref<boolean>;
-};
-
-/**
- * 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;
-
-  /**
-   * Debounced visible state that will only be toggled after a given timeout.
-   */
-  const debouncedVisible = computed({
-    get: () => _isVisible.value,
-    set: (newValue) => {
-      clearTimeout(timeout);
-      timeout = setTimeout(() => {
-        _isVisible.value = newValue;
-      }, toValue(debounce));
-    },
-  });
-
-  const hoverEvents = {
-    onMouseover: () => (debouncedVisible.value = true),
-    onMouseout: () => (debouncedVisible.value = false),
-    onFocusin: () => (_isVisible.value = true),
-    onFocusout: () => (_isVisible.value = false),
-  };
-
-  useDismissible({ isExpanded: _isVisible });
-
-  return {
-    elements: {
-      /**
-       * The element which controls the tooltip visibility on hover.
-       */
-      trigger: {
-        "aria-describedby": tooltipId,
-        ...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,
-      },
-    },
-    state: {
-      isVisible: _isVisible,
-    },
-  };
-});

package/src/index.ts

@@ -1,11 +0,0 @@
-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 { isPrintableCharacter, wasKeyPressed } from "./utils/keyboard";
-export { debounce } from "./utils/timer";

package/src/playwright.ts

@@ -1,5 +0,0 @@
-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,135 +0,0 @@
-import {
-  computed,
-  shallowRef,
-  type ComponentPublicInstance,
-  type HTMLAttributes,
-  type MaybeRef,
-  type Ref,
-  type WritableComputedOptions,
-  type WritableComputedRef,
-} from "vue";
-import type { IfDefined } from "./types";
-
-/**
- * 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<
-  A extends HTMLAttributes,
-  T extends Record<string, unknown>,
-> = (opts: T) => VBindAttributes<A>;
-
-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, MaybeRef<HeadlessElementAttributes<HTMLAttributes>>>;
-
-export type HeadlessState = Record<string, Ref>;
-
-export type HeadlessComposable<
-  Elements extends HeadlessElements,
-  State extends HeadlessState | undefined = undefined,
-  Internals extends object | undefined = undefined,
-> = {
-  elements: Elements;
-} & IfDefined<"internals", Internals> &
-  IfDefined<"state", State>;
-
-/**
- * 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[],
-  Elements extends HeadlessElements = HeadlessElements,
-  State extends HeadlessState | undefined = undefined,
-  Internals extends object | undefined = undefined,
->(
-  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/keyboard.spec.ts

@@ -1,53 +0,0 @@
-import { expect, test } from "vitest";
-import { isPrintableCharacter, wasKeyPressed } from "./keyboard";
-
-test.each([
-  // ARRANGE
-  { input: [{ key: "m", code: "KeyM" }, "m"], expected: true },
-  { input: [{ key: "m", code: "KeyM" }, "m"], expected: true },
-  { input: [{ key: "m", code: "KeyM" }, { key: "m" }], expected: true },
-  { input: [{ key: "m", code: "KeyM" }, { code: "KeyM" }], expected: true },
-  {
-    input: [{ key: "m", code: "KeyM", altKey: false }, { code: "KeyM" }],
-    expected: true,
-  },
-  {
-    input: [
-      { key: "m", code: "KeyM" },
-      { code: "KeyM", altKey: true },
-    ],
-    expected: false,
-  },
-  {
-    input: [
-      { key: "m", code: "KeyM", shiftKey: true },
-      { code: "KeyM", shiftKey: false },
-    ],
-    expected: false,
-  },
-] as { input: Parameters<typeof wasKeyPressed>; expected: boolean }[])(
-  "should return $expected for event $input.0 and pressed key $input.1",
-  ({ input: [event, wasPressed], expected }) => {
-    // ACT
-    const result = wasKeyPressed(new KeyboardEvent("keydown", event), wasPressed);
-
-    // ASSERT
-    expect(result).toBe(expected);
-  },
-);
-
-test.each([
-  // ARRANGE
-  { key: "a", expected: true },
-  { key: "🎉", expected: true },
-  { key: "あ", expected: true },
-  { key: " ", expected: true },
-  { key: "Meta", expected: false },
-  { key: "Fn", expected: false },
-])("should return $expected for key $key", ({ key, expected }) => {
-  // ACT
-  const result = isPrintableCharacter(key);
-
-  // ASSERT
-  expect(result).toBe(expected);
-});