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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sit-onyx/headless",
   "description": "Headless composables for Vue",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "type": "module",
   "author": "Schwarz IT KG",
   "license": "Apache-2.0",

package/src/composables/comboBox/SelectOnlyCombobox.vue

@@ -26,7 +26,6 @@ const onToggle = () => (isExpanded.value = !isExpanded.value);
 const onTypeAhead = () => {};
 
 const comboBox = createComboBox({
-  inputValue: selectedOption,
   autocomplete: "none",
   label: "some label",
   listLabel: "List",
@@ -51,7 +50,12 @@ defineExpose({ comboBox });
 
 <template>
   <div ref="comboboxRef">
-    <input v-bind="input" readonly @keydown.arrow-down="isExpanded = true" />
+    <input
+      v-bind="input"
+      v-model="selectedOption"
+      readonly
+      @keydown.arrow-down="isExpanded = true"
+    />
 
     <button v-bind="button">
       <template v-if="isExpanded">⬆️</template>

package/src/composables/comboBox/TestCombobox.vue

@@ -30,7 +30,6 @@ const onAutocomplete = (input: string) => (searchTerm.value = input);
 const onToggle = () => (isExpanded.value = !isExpanded.value);
 
 const comboBox = createComboBox({
-  inputValue: searchTerm,
   autocomplete: "list",
   label: "some label",
   listLabel: "List",
@@ -55,7 +54,7 @@ defineExpose({ comboBox });
 
 <template>
   <div ref="comboboxRef">
-    <input v-bind="input" @keydown.arrow-down="isExpanded = true" />
+    <input v-bind="input" v-model="searchTerm" @keydown.arrow-down="isExpanded = true" />
 
     <button v-bind="button">
       <template v-if="isExpanded">⬆️</template>

package/src/composables/comboBox/createComboBox.ts

@@ -41,10 +41,6 @@ export type CreateComboboxOptions<
    * Labels the listbox which displays the available options. E.g. the list label could be "Countries" for a combobox which is labelled "Country".
    */
   listLabel: MaybeRef<string>;
-  /**
-   * The current value of the combobox. Is updated when an option from the controlled listbox is selected or by typing into it.
-   */
-  inputValue: Ref<string | undefined>;
   /**
    * Controls the opened/visible state of the associated pop-up. When expanded the activeOption can be controlled via the keyboard.
    */
@@ -105,7 +101,6 @@ export const createComboBox = createBuilder(
     TAutoComplete extends ComboboxAutoComplete,
     TMultiple extends boolean = false,
   >({
-    inputValue,
     autocomplete: autocompleteRef,
     onAutocomplete,
     onTypeAhead,
@@ -250,7 +245,6 @@ export const createComboBox = createBuilder(
          * The input MAY be either a single-line text field that supports editing and typing or an element that only displays the current value of the combobox.
          */
         input: computed(() => ({
-          value: inputValue.value,
           role: "combobox",
           "aria-expanded": isExpanded.value,
           "aria-controls": controlsId,

package/src/composables/listbox/createListbox.ts

@@ -1,6 +1,6 @@
 import { computed, ref, unref, watchEffect, type MaybeRef, type Ref } from "vue";
 import { createId } from "../..";
-import { createBuilder, type HeadlessElementAttributes } from "../../utils/builder";
+import { createBuilder, type VBindAttributes } from "../../utils/builder";
 import { useTypeAhead } from "../helpers/useTypeAhead";
 
 export type ListboxValue = string | number | boolean;
@@ -152,7 +152,7 @@ export const createListbox = createBuilder(
       }
     };
 
-    const listbox = computed<HeadlessElementAttributes>(() =>
+    const listbox = computed<VBindAttributes>(() =>
       options.controlled
         ? {
             role: "listbox",

package/src/composables/menuButton/createMenuButton.ts

@@ -1,5 +1,5 @@
-import { computed, ref, type Ref } from "vue";
-import { createBuilder } from "../../utils/builder";
+import { computed, 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";
@@ -16,7 +16,7 @@ export const createMenuButton = createBuilder(
   ({ isExpanded, onToggle }: CreateMenuButtonOptions) => {
     const rootId = createId("menu-button-root");
     const menuId = createId("menu-button-list");
-    const menuRef = ref<HTMLElement>();
+    const menuRef = createElRef<HTMLElement>();
     const buttonId = createId("menu-button-button");
 
     useGlobalEventListener({

package/src/composables/navigationMenu/createMenu.testing.ts

@@ -22,22 +22,11 @@ export const navigationTesting = async ({ nav, buttons }: NavigationMenuTestingO
    */
   await expect(nav).toHaveRole("navigation");
   await expect(nav).toHaveAttribute("aria-label");
-  /**
-   * Disclosure buttons should have aria attributes
-   */
-  for (const button of await buttons.all()) {
-    await expect(button, "button must have arial-controls attribute").toHaveAttribute(
-      "aria-controls",
-    );
-    await expect(button, "button must have aria-expanded attribute").toHaveAttribute(
-      "aria-expanded",
-    );
-  }
+
   /**
    * Focus first button
    */
-  await nav.press("Tab");
-  await expect(buttons.nth(0)).toBeFocused();
+  await buttons.first().focus();
   /**
    * Move keyboard focus among top-level buttons using arrow keys
    */

package/src/composables/tooltip/createTooltip.ts

@@ -1,6 +1,6 @@
 import { computed, onBeforeMount, onBeforeUnmount, ref, unref, type MaybeRef } from "vue";
 import { createId } from "../..";
-import { createBuilder } from "../../utils/builder";
+import { createBuilder, createElRef } from "../../utils/builder";
 import { useOutsideClick } from "../helpers/useOutsideClick";
 
 export type CreateTooltipOptions = {
@@ -22,7 +22,7 @@ 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 rootRef = createElRef<HTMLElement>();
   const tooltipId = createId("tooltip");
   const _isVisible = ref(false);
   let timeout: ReturnType<typeof setTimeout> | undefined;

package/src/index.ts

@@ -3,6 +3,7 @@ export * from "./composables/listbox/createListbox";
 export * from "./composables/menuButton/createMenuButton";
 export * from "./composables/navigationMenu/createMenu";
 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

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

package/src/utils/builder.ts

@@ -1,19 +1,37 @@
-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 };
+/**
+ * `v-bind`able attributes as they are provided by the headless composables.
+ * `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
+  | 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 +46,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 = createId("tooltip");
+ *   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 +88,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>);
+}