@sit-onyx/headless 0.1.0-alpha.7 → 0.1.0

package/src/composables/listbox/createListbox.ts

@@ -1,209 +0,0 @@
-import { computed, ref, unref, watchEffect, type MaybeRef, type Ref } from "vue";
-import { createId } from "../..";
-import { createBuilder, type HeadlessElementAttributes } from "../../utils/builder";
-import { useTypeAhead } from "../typeAhead";
-
-export type ListboxValue = string | number | boolean;
-
-export type ListboxModelValue<
-  TValue extends ListboxValue = ListboxValue,
-  TMultiple extends boolean = false,
-> = TMultiple extends true ? TValue[] : TValue;
-
-export type CreateListboxOptions<
-  TValue extends ListboxValue = ListboxValue,
-  TMultiple extends boolean = false,
-> = {
-  /**
-   * Aria label for the listbox.
-   */
-  label: MaybeRef<string>;
-  /**
-   * Value of currently selected option.
-   */
-  selectedOption: Ref<ListboxModelValue<TValue, TMultiple> | undefined>;
-  /**
-   * Value of currently (visually) active option.
-   */
-  activeOption: Ref<TValue | undefined>;
-  /**
-   * Wether the listbox is controlled from the outside, e.g. by a combobox.
-   * This disables keyboard events and makes the listbox not focusable.
-   */
-  controlled?: boolean;
-  /**
-   * Whether the listbox is multiselect.
-   */
-  multiple?: MaybeRef<TMultiple | undefined>;
-  /**
-   * Hook when an option is selected.
-   */
-  onSelect?: (value: TValue) => void;
-  /**
-   * Hook when the first option should be activated.
-   */
-  onActivateFirst?: () => void;
-  /**
-   * Hook when the last option should be activated.
-   */
-  onActivateLast?: () => void;
-  /**
-   * Hook when the next option should be activated.
-   */
-  onActivateNext?: (currentValue: TValue) => void;
-  /**
-   * Hook when the previous option should be activated.
-   */
-  onActivatePrevious?: (currentValue: TValue) => void;
-  /**
-   * Hook when the first option starting with the given label should be activated.
-   */
-  onTypeAhead?: (label: string) => void;
-};
-
-/**
- * Composable for creating a accessibility-conform listbox.
- * For supported keyboard shortcuts, see: https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/
- */
-export const createListbox = createBuilder(
-  <TValue extends ListboxValue = ListboxValue, TMultiple extends boolean = false>(
-    options: CreateListboxOptions<TValue, TMultiple>,
-  ) => {
-    const isMultiselect = computed(() => unref(options.multiple) ?? false);
-
-    /**
-     * Map for option IDs. key = option value, key = ID for the HTML element
-     */
-    const descendantKeyIdMap = new Map<TValue, string>();
-
-    const getOptionId = (value: TValue) => {
-      if (!descendantKeyIdMap.has(value)) {
-        descendantKeyIdMap.set(value, createId("listbox-option"));
-      }
-      return descendantKeyIdMap.get(value)!;
-    };
-
-    /**
-     * Whether the listbox element is focused.
-     */
-    const isFocused = ref(false);
-
-    // scroll currently active option into view if needed
-    watchEffect(() => {
-      if (options.activeOption.value == undefined || (!isFocused.value && !options.controlled))
-        return;
-      const id = getOptionId(options.activeOption.value);
-      document.getElementById(id)?.scrollIntoView({ block: "nearest", inline: "nearest" });
-    });
-
-    const typeAhead = useTypeAhead((inputString) => options.onTypeAhead?.(inputString));
-
-    const handleKeydown = (event: KeyboardEvent) => {
-      switch (event.key) {
-        case " ":
-          event.preventDefault();
-          if (options.activeOption.value != undefined) {
-            // TODO: don't call onSelect if the option is disabled
-            options.onSelect?.(options.activeOption.value);
-          }
-          break;
-
-        case "ArrowUp":
-          event.preventDefault();
-          // if no option is active yet, activate the last option
-          if (options.activeOption.value == undefined) {
-            options.onActivateLast?.();
-            return;
-          }
-
-          options.onActivatePrevious?.(options.activeOption.value);
-          break;
-
-        case "ArrowDown":
-          event.preventDefault();
-          // if no option is active yet, activate the first option
-          if (options.activeOption.value == undefined) {
-            options.onActivateFirst?.();
-            return;
-          }
-
-          options.onActivateNext?.(options.activeOption.value);
-          break;
-
-        case "Home":
-          event.preventDefault();
-          options.onActivateFirst?.();
-          break;
-
-        case "End":
-          event.preventDefault();
-          options.onActivateLast?.();
-          break;
-
-        default:
-          // if printable characters are pressed, the first option/text starting with the typed characters should be active
-          typeAhead(event);
-      }
-    };
-
-    const listbox = computed<HeadlessElementAttributes>(() =>
-      options.controlled
-        ? {
-            role: "listbox",
-            "aria-multiselectable": isMultiselect.value,
-            "aria-label": unref(options.label),
-            tabindex: "-1",
-          }
-        : {
-            role: "listbox",
-            "aria-multiselectable": isMultiselect.value,
-            "aria-label": unref(options.label),
-            tabindex: "0",
-            "aria-activedescendant":
-              options.activeOption.value != undefined
-                ? getOptionId(options.activeOption.value)
-                : undefined,
-            onFocus: () => (isFocused.value = true),
-            onBlur: () => (isFocused.value = false),
-            onKeydown: handleKeydown,
-          },
-    );
-
-    return {
-      elements: {
-        listbox,
-        group: computed(() => {
-          return (options: { label: string }) => ({
-            role: "group",
-            "aria-label": options.label,
-          });
-        }),
-        option: computed(() => {
-          return (data: {
-            label: string;
-            value: TValue;
-            selected?: boolean;
-            disabled?: boolean;
-          }) => {
-            const isSelected = data.selected ?? false;
-            return {
-              id: getOptionId(data.value),
-              role: "option",
-              "aria-label": data.label,
-              "aria-checked": isMultiselect.value ? isSelected : undefined,
-              "aria-selected": !isMultiselect.value ? isSelected : undefined,
-              "aria-disabled": data.disabled,
-              onClick: () => !data.disabled && options.onSelect?.(data.value),
-            } as const;
-          };
-        }),
-      },
-      state: {
-        isFocused,
-      },
-      internals: {
-        getOptionId,
-      },
-    };
-  },
-);

package/src/composables/tooltip/createTooltip.ts

@@ -1,150 +0,0 @@
-import {
-  computed,
-  onBeforeMount,
-  onBeforeUnmount,
-  ref,
-  unref,
-  watchEffect,
-  type MaybeRef,
-} from "vue";
-import { createId } from "../..";
-import { createBuilder } from "../../utils/builder";
-
-export type CreateTooltipOptions = {
-  open: MaybeRef<TooltipOpen>;
-};
-
-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 tooltipId = createId("tooltip");
-  const _isVisible = ref(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.
-   */
-  const debouncedVisible = computed({
-    get: () => _isVisible.value,
-    set: (newValue) => {
-      clearTimeout(timeout);
-      timeout = setTimeout(() => {
-        _isVisible.value = newValue;
-      }, debounce.value);
-    },
-  });
-
-  /**
-   * 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;
-  };
-
-  /**
-   * Document click handle that closes then tooltip when clicked outside.
-   * Should only be called when trigger is "click".
-   */
-  const handleDocumentClick = (event: MouseEvent) => {
-    const tooltipParent = document.getElementById(tooltipId)?.parentElement;
-    if (!tooltipParent || !(event.target instanceof Node)) return;
-
-    const isOutsideClick = !tooltipParent.contains(event.target);
-    if (isOutsideClick) _isVisible.value = false;
-  };
-
-  // add global document event listeners only on/before mounted to also work in server side rendering
-  onBeforeMount(() => {
-    document.addEventListener("keydown", handleDocumentKeydown);
-
-    /**
-     * Registers keydown and click handlers when trigger is "click" to close
-     * the tooltip.
-     */
-    watchEffect(() => {
-      if (openType.value === "click") {
-        document.addEventListener("click", handleDocumentClick);
-      } else {
-        document.removeEventListener("click", handleDocumentClick);
-      }
-    });
-  });
-
-  /**
-   * Clean up global event listeners to prevent dangling events.
-   */
-  onBeforeUnmount(() => {
-    document.addEventListener("keydown", handleDocumentKeydown);
-    document.addEventListener("click", handleDocumentClick);
-  });
-
-  return {
-    elements: {
-      trigger: computed(() => ({
-        "aria-describedby": tooltipId,
-        onClick: openType.value === "click" ? handleClick : undefined,
-        ...hoverEvents.value,
-      })),
-      tooltip: computed(() => ({
-        role: "tooltip",
-        id: tooltipId,
-        tabindex: "-1",
-        ...hoverEvents.value,
-      })),
-    },
-    state: {
-      isVisible,
-    },
-  };
-});

package/src/composables/typeAhead.spec.ts

@@ -1,29 +0,0 @@
-import { beforeAll, expect, test, vi } from "vitest";
-import { useTypeAhead } from "./typeAhead";
-
-beforeAll(() => {
-  vi.useFakeTimers();
-});
-
-test("useTypeAhead", () => {
-  const spy = vi.fn();
-  const typeAhead = useTypeAhead(spy);
-
-  typeAhead({ key: "a" });
-  expect(spy).toHaveBeenCalledOnce();
-  expect(spy).toHaveBeenLastCalledWith("a");
-
-  typeAhead({ key: "Alt" });
-  expect(spy).toHaveBeenCalledOnce();
-  expect(spy).toHaveBeenLastCalledWith("a");
-
-  typeAhead({ key: "b" });
-  expect(spy).toHaveBeenCalledTimes(2);
-  expect(spy).toHaveBeenLastCalledWith("ab");
-
-  vi.runAllTimers();
-
-  typeAhead({ key: "c" });
-  expect(spy).toBeCalledTimes(3);
-  expect(spy).toHaveBeenLastCalledWith("c");
-});

package/src/composables/typeAhead.ts

@@ -1,26 +0,0 @@
-import { isPrintableCharacter } from "../utils/keyboard";
-import { debounce } from "../utils/timer";
-
-/**
- * Enhances typeAhead to combine multiple inputs in quick succession and filter out non-printable characters.
- *
- * @example
- * ```ts
- * const typeAhead = useTypeAhead((inputString) => console.log("Typed string:", inputString));
- * // ...
- * addEventListener("keydown", typeAhead);
- * ```
- */
-export const useTypeAhead = (callback: (input: string) => void, timeout = 500) => {
-  let inputString = "";
-  const debouncedReset = debounce(() => (inputString = ""), timeout);
-
-  return (event: Pick<KeyboardEvent, "key">) => {
-    if (!isPrintableCharacter(event.key)) {
-      return;
-    }
-    debouncedReset();
-    inputString = `${inputString}${event.key}`;
-    callback(inputString);
-  };
-};

package/src/index.ts

@@ -1,4 +0,0 @@
-export * from "./composables/comboBox/createComboBox";
-export * from "./composables/listbox/createListbox";
-export * from "./composables/tooltip/createTooltip";
-export { createId } from "./utils/id";

package/src/playwright.ts

@@ -1,2 +0,0 @@
-export * from "./composables/comboBox/createComboBox.ct";
-export * from "./composables/listbox/createListbox.ct";

package/src/utils/builder.ts

@@ -1,37 +0,0 @@
-import type { ComputedRef, HtmlHTMLAttributes, Ref } from "vue";
-import type { IfDefined } from "./types";
-
-export type IteratedHeadlessElementFunc<T extends Record<string, unknown>> = (
-  opts: T,
-) => HtmlHTMLAttributes;
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type HeadlessElementAttributes = HtmlHTMLAttributes | IteratedHeadlessElementFunc<any>;
-
-export type HeadlessElements = Record<
-  string,
-  HeadlessElementAttributes | ComputedRef<HeadlessElementAttributes>
->;
-
-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
- */
-export const createBuilder = <
-  P,
-  Elements extends HeadlessElements,
-  State extends HeadlessState | undefined = undefined,
-  Internals extends object | undefined = undefined,
->(
-  builder: (props: P) => HeadlessComposable<Elements, State, Internals>,
-) => builder;

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

package/src/utils/keyboard.spec.ts

@@ -1,18 +0,0 @@
-import { expect, test } from "vitest";
-import { isPrintableCharacter } from "./keyboard";
-
-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);
-});