@sit-onyx/headless 1.0.0-beta.5 → 1.0.0-beta.6

package/package.json

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

package/src/composables/comboBox/createComboBox.ts

@@ -10,6 +10,7 @@ import {
   type ListboxValue,
 } from "../listbox/createListbox";
 
+/** See https://w3c.github.io/aria/#aria-autocomplete */
 export type ComboboxAutoComplete = "none" | "list" | "both";
 
 export const OPENING_KEYS: PressedKey[] = ["ArrowDown", "ArrowUp", " ", "Enter", "Home", "End"];
@@ -19,11 +20,15 @@ export const CLOSING_KEYS: PressedKey[] = [
   "Enter",
   "Tab",
 ];
-const SELECTING_KEYS_SINGLE: PressedKey[] = ["Enter", " "];
-const SELECTING_KEYS_MULTIPLE: PressedKey[] = ["Enter"];
 
-const isSelectingKey = (event: KeyboardEvent, isMultiselect?: boolean) => {
-  const selectingKeys = isMultiselect ? SELECTING_KEYS_MULTIPLE : SELECTING_KEYS_SINGLE;
+const SELECTING_KEYS: PressedKey[] = ["Enter"];
+
+/**
+ * if the a search input is included, space should not be used to select
+ * TODO: idea for the future: move this distinction to the listbox?
+ */
+const isSelectingKey = (event: KeyboardEvent, withSpace?: boolean) => {
+  const selectingKeys = withSpace ? [...SELECTING_KEYS, " "] : SELECTING_KEYS;
   return isKeyOfGroup(event, selectingKeys);
 };
 
@@ -41,6 +46,10 @@ 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>;
+  /**
+   * Provides additional description for the listbox which displays the available options.
+   */
+  listDescription?: MaybeRef<string | undefined>;
   /**
    * Controls the opened/visible state of the associated pop-up. When expanded the activeOption can be controlled via the keyboard.
    */
@@ -107,6 +116,7 @@ export const createComboBox = createBuilder(
     multiple: multipleRef,
     label,
     listLabel,
+    listDescription,
     isExpanded: isExpandedRef,
     activeOption,
     onToggle,
@@ -183,7 +193,7 @@ export const createComboBox = createBuilder(
         }
         return onActivateFirst?.();
       }
-      if (isSelectingKey(event, multiple.value)) {
+      if (isSelectingKey(event, autocomplete.value === "none")) {
         return handleSelect(activeOption.value!);
       }
       if (isExpanded.value && isKeyOfGroup(event, CLOSING_KEYS)) {
@@ -213,9 +223,11 @@ export const createComboBox = createBuilder(
       internals: { getOptionId },
     } = createListbox({
       label: listLabel,
+      description: listDescription,
       multiple,
       controlled: true,
       activeOption,
+      isExpanded,
       onSelect: handleSelect,
     });
 

package/src/composables/listbox/TestListbox.vue

@@ -30,7 +30,9 @@ const {
   elements: { listbox, option: headlessOption },
 } = createListbox({
   label: "Test listbox",
+  description: "Test description",
   activeOption,
+  isExpanded: true,
   onSelect: (id) => {
     selectedOption.value = selectedOption.value === id ? undefined : id;
   },

package/src/composables/listbox/createListbox.ts

@@ -10,6 +10,10 @@ export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends
    * Aria label for the listbox.
    */
   label: MaybeRef<string>;
+  /**
+   * Aria description for the listbox.
+   */
+  description?: MaybeRef<string | undefined>;
   /**
    * Value of currently (visually) active option.
    */
@@ -19,6 +23,10 @@ export type CreateListboxOptions<TValue extends ListboxValue, TMultiple extends
    * This disables keyboard events and makes the listbox not focusable.
    */
   controlled?: boolean;
+  /**
+   * Controls the opened/visible state of the listbox. When expanded the activeOption can be controlled via the keyboard.
+   */
+  isExpanded?: MaybeRef<boolean>;
   /**
    * Whether the listbox is multiselect.
    */
@@ -77,6 +85,7 @@ export const createListbox = createBuilder(
     options: CreateListboxOptions<TValue, TMultiple>,
   ) => {
     const isMultiselect = computed(() => unref(options.multiple) ?? false);
+    const isExpanded = computed(() => unref(options.isExpanded) ?? false);
 
     /**
      * Map for option IDs. key = option value, key = ID for the HTML element
@@ -97,7 +106,11 @@ export const createListbox = createBuilder(
 
     // scroll currently active option into view if needed
     watchEffect(() => {
-      if (options.activeOption.value == undefined || (!isFocused.value && !options.controlled))
+      if (
+        !isExpanded.value ||
+        options.activeOption.value == undefined ||
+        (!isFocused.value && !options.controlled)
+      )
         return;
       const id = getOptionId(options.activeOption.value);
       document.getElementById(id)?.scrollIntoView({ block: "nearest", inline: "nearest" });
@@ -158,12 +171,14 @@ export const createListbox = createBuilder(
             role: "listbox",
             "aria-multiselectable": isMultiselect.value,
             "aria-label": unref(options.label),
+            "aria-description": options.description,
             tabindex: "-1",
           }
         : {
             role: "listbox",
             "aria-multiselectable": isMultiselect.value,
             "aria-label": unref(options.label),
+            "aria-description": options.description,
             tabindex: "0",
             "aria-activedescendant":
               options.activeOption.value != undefined

package/src/utils/vitest.ts

@@ -1,6 +1,6 @@
-import { vi, type Awaitable } from "vitest";
+import { vi } from "vitest";
 
-type Callback = () => Awaitable<void>;
+type Callback = () => void | (() => Promise<void>);
 
 /**
  * Mocks the following vue lifecycle functions: