@madgex/design-system-ce 5.6.1 → 5.6.3

package/components/combobox/Combobox.ce.vue

@@ -1,18 +1,19 @@
+<!-- eslint-disable vue/multi-word-component-names -->
 <template>
   <div
     class="mds-combobox"
-    :class="{ 'mds-combobox--active': !listBoxHidden }"
-    @keydown.down="hiddenGuard(onKeyDown)"
-    @keydown.up="hiddenGuard(onKeyUp)"
-    @keydown.home="hiddenGuard(onKeyHome)"
-    @keydown.end="hiddenGuard(onKeyEnd)"
-    @keydown.esc="makeInactive"
+    :class="{ 'mds-combobox--active': expanded }"
+    @keydown.down="handleKeyDown"
+    @keydown.up="handleKeyUp"
+    @keydown.home="handleKeyHome"
+    @keydown.end="handleKeyEnd"
+    @keydown.esc="handleKeyEsc"
     @keydown.enter="handleKeyDownEnter"
   >
     <input
       :id="comboboxid"
-      ref="comboInput"
-      :value="inputValue"
+      ref="$comboInput"
+      :value="searchValue"
       class="mds-form-control"
       autocomplete="off"
       type="text"
@@ -23,291 +24,293 @@
       :aria-expanded="ariaExpanded"
       aria-autocomplete="list"
       :aria-describedby="describedbyId"
-      :aria-activedescendant="selectedOptionId"
+      :aria-activedescendant="getOptionIdByIndex(selectedIndex)"
       :aria-invalid="ariaInvalid"
       @input="handleInput"
       @change="handleChange"
-      @blur="onInputBlur"
+      @blur="handleBlur"
       @focus="handleFocus"
     />
-
     <ComboboxClear v-if="searchValue.length > 0" @clear="handleClear" />
-    <ListBox :id="listBoxId" :hidden="listBoxHidden" :aria-labelledby="`${comboboxid}-label`" :is-loading="isLoading">
+    <ListBox :id="listBoxId" :hidden="!expanded" :aria-labelledby="`${comboboxid}-label`" :is-loading="isLoading">
       <ListBoxOption
         v-for="(option, index) in visibleOptions"
-        :id="`${optionId}-${index}`"
+        :id="getOptionIdByIndex(index)"
         :key="index"
-        :option="option"
-        :focused="selectedOption?.value === option?.value"
+        :option-label="getOptionLabel(option)"
+        :focused="selectedIndex === index"
         :search-value="searchValue"
-        @mousedown="clickOption(option)"
+        @mousedown="handleMouseDownOption(option)"
       />
     </ListBox>
-    <div aria-live="polite" role="status" class="mds-visually-hidden">{{ resultCountMessage }}</div>
+    <ComboboxAriaLive
+      :visible-options="visibleOptions"
+      :expanded="expanded"
+      :results-message="i18nText.resultsMessage"
+      :results-message_plural="i18nText.resultsMessage_plural"
+    />
+    <!-- No default <slot/> used, so fallback child content is destroyed on mount -->
+    <!-- target-inputs <slot/> so we can easily find inputs to populate with option selection -->
+    <span ref="$targetInputs"><slot name="target-inputs"></slot></span>
   </div>
 </template>
 
-<script>
+<script setup>
+import { computed, provide, ref, useTemplateRef } from 'vue';
+import safeGet from 'just-safe-get';
+import debounce from 'just-debounce-it';
+import Bourne from '@hapi/bourne';
 import ComboboxClear from './ComboboxClear.vue';
 import ListBox from './ListBox.vue';
 import ListBoxOption from './ListBoxOption.vue';
+import ComboboxAriaLive from './ComboboxAriaLive.vue';
+
+/*
+ * as this is a Web Component, all props are string-ish types, hence why `options` is JSON parsed, see `parsedPropOptions`.
+ * https://vuejs.org/guide/extras/web-components.html#props
+ */
+const props = defineProps({
+  comboboxid: { type: String, required: true },
+  placeholder: { type: String, default: '' },
+  name: { type: [String, Boolean], default: false },
+  value: { type: String, default: '' },
+  options: { type: String, default: '[]' },
+  iconpath: { type: String, default: '/assets/icons.svg' },
+  dataAriaInvalid: { type: String, default: '' },
+  i18n: { type: String, default: '' },
+  describedbyId: { type: String, default: '' },
+  minSearchCharacters: { type: Number, default: 2 },
+  /** the api endpoint to fetch options on search input */
+  apiUrl: { type: String, default: undefined },
+  /** the query key name for the api endpoint */
+  apiQueryKey: { type: String, default: 'searchText' },
+  /** where to grab an array of options on api response, e.g. `data.options` would be an array of options, empty to use api response as array */
+  apiOptionsPath: { type: String, default: undefined },
+  /** where to grab the visual label from the option object e.g. 'label' or 'title' or 'nested.object.label' */
+  optionLabelPath: { type: String, default: 'label' },
+});
+
+const $comboInput = useTemplateRef('$comboInput');
+const $targetInputs = useTemplateRef('$targetInputs');
+
+const expanded = ref(false);
+/** `selectedIndex` aka "highlighted option", set by using keyboard controls */
+const selectedIndex = ref(null);
+const searchValue = ref(props.value);
+const isLoading = ref(false);
+/** used if apiUrl is set, otherwise `parsedPropOptions` is used */
+const apiOptions = ref([]);
+
+// as props must be string-ish types, we parse the `options` into a real array
+const parsedPropOptions = computed(() => {
+  try {
+    return Bourne.parse(props.options);
+  } catch (e) {
+    console.error(e);
+    return [];
+  }
+});
+
+const i18nText = computed(() => {
+  return props.i18n
+    ? JSON.parse(props.i18n)
+    : {
+        loadingText: 'Loading',
+        resultsMessage: '{count} result available',
+        resultsMessage_plural: '{count} results available',
+        clearInput: 'clear input',
+      };
+});
+
+const visibleOptions = computed(() => {
+  if (!props.apiUrl) {
+    return parsedPropOptions.value.filter((opt) =>
+      getOptionLabel(opt).toLowerCase().includes(searchValue.value.toLowerCase()),
+    );
+  }
+
+  return apiOptions.value;
+});
+const listBoxId = computed(() => {
+  return `${props.comboboxid}-listbox`;
+});
+
+/** generate an DOM `id` for a option, based on index number */
+function getOptionIdByIndex(index) {
+  if (typeof index === 'number' && index > -1) {
+    return `${props.comboboxid}-option-${index}`;
+  }
+  return undefined;
+}
 
-export default {
-  name: 'Combobox',
-  components: {
-    ComboboxClear,
-    ListBox,
-    ListBoxOption,
-  },
-  provide() {
-    return {
-      iconPath: this.iconpath,
-      loadingText: this.i18nText.loadingText,
-      clearInput: this.i18nText.clearInput,
-    };
-  },
-  props: {
-    comboboxid: {
-      type: String,
-      required: true,
-    },
-    placeholder: {
-      type: String,
-      default: '',
-    },
-    name: {
-      type: [String, Boolean],
-      default: false,
-    },
-    value: {
-      type: String,
-      default: '',
-    },
-    options: {
-      type: Array,
-      default: () => [],
-    },
-    filterOptions: {
-      type: Boolean,
-      default: true,
-    },
-    iconpath: {
-      type: String,
-      default: '/assets/icons.svg',
-    },
-    dataAriaInvalid: {
-      type: String,
-      default: '',
-    },
-    i18n: {
-      type: String,
-      default: '',
-    },
-    describedbyId: {
-      type: String,
-      default: ''
-    },
-    minSearchCharacters: {
-      type: Number,
-      default: 2
-    }
-  },
-  emits: ['search', 'select-option', 'clear-all'],
-  data() {
-    return {
-      expanded: false,
-      selected: null,
-      chosen: null,
-      searchValue: this.$props.value,
-      resultCountMessage: null,
-    };
-  },
-  computed: {
-    inputValue() {
-      if (this.chosenOption) {
-        return this.chosenOption.label;
-      }
+const ariaExpanded = computed(() => {
+  // These must be strings to apply as an aria attribute of the same name
+  return expanded.value ? 'true' : 'false';
+});
 
-      return this.searchValue;
-    },
-    selectedOption: {
-      get() {
-        return this.selected;
-      },
-      set(newOption) {
-        this.selected = newOption;
-      },
-    },
-    chosenOption: {
-      get() {
-        return this.chosen;
-      },
-      set(newOption) {
-        this.chosen = newOption;
-        this.selectedOption = newOption;
-        this.$emit('select-option', this.chosen);
-      },
-    },
-    visibleOptions() {
-      if (this.filterOptions) {
-        return this.options.filter((opt) => opt.label.toLowerCase().includes(this.searchValue.toLowerCase()));
-      }
+const ariaInvalid = computed(() => {
+  return props.dataAriaInvalid ? 'true' : 'false';
+});
 
-      return this.options;
-    },
-    listBoxId() {
-      return `${this.comboboxid}-listbox`;
-    },
-    optionId() {
-      return `${this.comboboxid}-option`;
-    },
-    isLoading() {
-      return this.options.length === 0 && this.expanded;
-    },
-    selectedOptionId() {
-      const index = this.visibleOptions.findIndex((obj) => obj.value == this.selectedOption?.value);
+/**
+ * When user chooses an option:
+ * - set search input to chosen option's label
+ * - set any hidden target input values based on option
+ * - close list menu
+ * - reset selectedIndex
+ * @param newOption
+ */
+function chooseOption(newOption) {
+  searchValue.value = getOptionLabel(newOption);
+  setTargetValues(newOption);
+  makeInactive();
+  selectedIndex.value = null;
+}
 
-      if (index > -1) {
-        return `${this.optionId}-${index}`;
-      }
+/**
+ * Update target inputs with value from an option.
+ * If option is not supplied, target input values will be cleared
+ * @param {object?} option
+ */
+function setTargetValues(option) {
+  const targetInputs = Array.from($targetInputs.value?.querySelectorAll('[data-key]'));
+  for (const el of targetInputs) {
+    // if no option, clear target value
+    el.value = option ? safeGet(option, el.getAttribute('data-key')) : '';
+    // ensure external code like htmx reacts to the new value
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+  }
+}
+function makeActive() {
+  expanded.value = true;
+}
+function makeInactive() {
+  expanded.value = false;
+}
+function clearField() {
+  searchValue.value = '';
+  setTargetValues();
+}
 
-      return undefined;
-    },
-    listBoxHidden() {
-      return !this.expanded;
-    },
-    lastOptionIndex() {
-      return this.visibleOptions.length - 1;
-    },
-    ariaExpanded() {
-      // These must be strings to apply as an aria attribute of the same name
-      return this.expanded ? 'true' : 'false';
-    },
-    ariaInvalid() {
-      return this.dataAriaInvalid ? 'true' : 'false';
-    },
-    i18nText() {
-      return this.i18n
-        ? JSON.parse(this.i18n)
-        : {
-            loadingText: 'Loading',
-            resultsMessage: '{count} result available',
-            resultsMessage_plural: '{count} results available',
-            clearInput: 'clear input',
-          };
-    },
-  },
-  mounted() {
-    // TODO: Get rid of this code which couples this to the nunjucks MdsCombobox template!
-    const fallbackInput = this.$el.parentElement?.parentElement?.querySelector('.mds-form-element__fallback input');
-    const fallbackSelect = this.$el.parentElement?.parentElement?.querySelector('.mds-form-element__fallback select');
+/**
+ * if props.apiUrl is set, we fetch options from the API.
+ * `apiOptions` should always be populated with an array of objects.
+ */
+const debouncedFetchApiOptions = debounce(async function fetchApiOptions() {
+  if (!props.apiUrl) return;
+  if (isLoading.value) return; // prevent overlapping fetch
+  const searchQuery = searchValue?.value?.trim();
+  try {
+    isLoading.value = true;
+    let res = await fetch(`${props.apiUrl}?${props.apiQueryKey}=${encodeURIComponent(searchQuery)}`);
+    if (!res.ok) return;
+    res = await res.json();
 
-    if (fallbackInput) fallbackInput.remove();
-    if (fallbackSelect) fallbackSelect.removeAttribute('id');
-  },
-  methods: {
-    makeActive() {
-      this.expanded = true;
-    },
-    makeInactive() {
-      this.expanded = false;
-    },
-    handleInput(event) {
-      // Reset any chosen option if user is typing again
-      this.chosenOption = null;
-      this.searchValue = event.target ? event.target.value : '';
-      this.handleChange();
-      this.$emit('search', this.searchValue);
-      if (this.visibleOptions.length > 0) {
-        this.updateCount();
-      }
-    },
-    handleChange() {
-      if (this.searchValue.length === 0) this.clearField();
-      if (this.searchValue.length >= this.minSearchCharacters) {
-        this.makeActive();
-        this.updateCount();
-      } else {
-        this.makeInactive();
-      }
-    },
-    handleFocus() {
-      this.handleChange();
-      if (this.visibleOptions.length > 1) {
-        this.updateCount();
-      }
-    },
-    handleClear() {
-      this.clearField();
-      this.$refs.comboInput.focus();
-    },
-    clearField() {
-      this.searchValue = '';
-      this.chosenOption = null;
-      this.$emit('clear-all');
-    },
-    clickOption(option = this.selectedOption) {
-      this.chosenOption = option;
-      this.makeInactive();
-    },
-    /* When expanded then enter key down selects an option, otherwise enter key will be native behaviour, eg submit form */
-    handleKeyDownEnter(event) {
-      if (this.expanded) {
-        event.preventDefault();
-        this.chooseOption();
-      }
-    },
-    chooseOption() {
-      this.chosenOption = this.selectedOption;
-      this.makeInactive();
-      this.clearCount();
-    },
-    hiddenGuard(fn) {
-      if (this.listBoxHidden) return;
-      fn.call(this);
-    },
-    onInputBlur() {
-      this.makeInactive();
-      this.clearCount();
-    },
-    onKeyDown() {
-      if (this.selectedOption) {
-        const currentIndex = this.visibleOptions.findIndex((item) => item.value === this.selectedOption.value);
-        const nextIndex = currentIndex === this.lastOptionIndex ? currentIndex : currentIndex + 1;
+    //where is the array of options on the api response?
+    // default to root if props.apiOptionsPath is not set
+    const data = props.apiOptionsPath ? safeGet(res, props.apiOptionsPath) : res;
+    apiOptions.value = data || [];
+  } finally {
+    isLoading.value = false;
+  }
+}, 200);
 
-        this.selectedOption = this.visibleOptions[nextIndex];
-      } else {
-        [this.selectedOption] = this.visibleOptions;
-      }
-    },
-    onKeyUp() {
-      if (this.selectedOption) {
-        const currentIndex = this.visibleOptions.findIndex((item) => item.value === this.selectedOption.value);
-        const nextIndex = currentIndex === 0 ? currentIndex : currentIndex - 1;
+/**
+ * where do we grab the label from the option object?
+ * option.label or option['nested.object.label.path']
+ * @param {object} option
+ * @returns {string} label
+ */
+function getOptionLabel(option) {
+  const label = safeGet(option, props.optionLabelPath);
+  return String(label);
+}
 
-        this.selectedOption = this.visibleOptions[nextIndex];
-      } else {
-        this.selectedOption = this.visibleOptions[this.lastOptionIndex];
-      }
-    },
-    onKeyHome() {
-      [this.selectedOption] = this.visibleOptions;
-    },
-    onKeyEnd() {
-      this.selectedOption = this.visibleOptions[this.lastOptionIndex];
-    },
-    updateCount() {
-      this.clearCount();
-      setTimeout(() => {
-        const message =
-          this.visibleOptions.length === 1 ? this.i18nText.resultsMessage : this.i18nText.resultsMessage_plural;
+/**
+ * - reset selectedIndex
+ * - copies the existing value into `searchValue` (because we manually handle input/change events)
+ * - fetch from api if applicable
+ * @param event input event
+ */
+function handleInput(event) {
+  selectedIndex.value = null;
+  searchValue.value = event.target ? event.target.value : '';
+  handleChange();
+  debouncedFetchApiOptions();
+}
+function handleChange() {
+  if (searchValue.value.length === 0) clearField();
+  if (searchValue.value.length >= props.minSearchCharacters) {
+    makeActive();
+  } else {
+    makeInactive();
+  }
+}
+function handleFocus() {
+  handleChange();
+}
+function handleClear() {
+  clearField();
+  $comboInput.value?.focus();
+}
+/**
+ * As the `Enter` key is handled seperately (see `handleKeyDownEnter`),
+ * we need this handler for mouse clicks on an option
+ * @param option
+ */
+function handleMouseDownOption(option) {
+  chooseOption(option);
+}
+/**
+ *  When expanded then enter key down selects an option,
+ *  otherwise enter key will be native behaviour, eg submit form
+ * @param event
+ */
+function handleKeyDownEnter(event) {
+  if (expanded.value) {
+    event.preventDefault();
+    const selectedOption = visibleOptions.value?.[selectedIndex.value];
+    chooseOption(selectedOption);
+  }
+}
+function handleBlur() {
+  makeInactive();
+}
+/** move down the list, selecting an option  */
+function handleKeyDown() {
+  if (!expanded.value) return;
+  if (selectedIndex.value !== null) {
+    selectedIndex.value = Math.min(selectedIndex.value + 1, visibleOptions.value.length - 1);
+  } else {
+    // nothing selected, start at top of the list
+    selectedIndex.value = 0;
+  }
+}
+/** move up the list, selecting an option  */
+function handleKeyUp() {
+  if (!expanded.value) return;
+  if (selectedIndex.value !== null) {
+    selectedIndex.value = Math.max(selectedIndex.value - 1, 0);
+  } else {
+    // nothing selected, start at bottom of the list
+    selectedIndex.value = visibleOptions.value.length - 1;
+  }
+}
+/** jump to top of list, selecting an option */
+function handleKeyHome() {
+  if (!expanded.value) return;
+  selectedIndex.value = 0;
+}
+/** jump to bottom of list, selecting an option */
+function handleKeyEnd() {
+  if (!expanded.value) return;
+  selectedIndex.value = visibleOptions.value.length - 1;
+}
+function handleKeyEsc() {
+  makeInactive();
+}
 
-        this.resultCountMessage = message.replace('{count}', this.visibleOptions.length);
-      }, 1400);
-    },
-    clearCount() {
-      this.resultCountMessage = null;
-    },
-  },
-};
+provide('iconPath', props.iconpath);
+provide('loadingText', i18nText.value.loadingText);
+provide('clearInput', i18nText.value.clearInput);
 </script>

package/components/combobox/ComboboxAriaLive.vue

@@ -0,0 +1,40 @@
+<template>
+  <div role="status" class="mds-visually-hidden">
+    {{ resultCountMessage }}
+  </div>
+</template>
+
+<script setup>
+import { ref, watch } from 'vue';
+import debounce from 'just-debounce-it';
+
+const props = defineProps({
+  visibleOptions: { type: Array, default: () => [] },
+  expanded: { type: Boolean, default: false },
+  resultsMessage: { type: String },
+  resultsMessage_plural: { type: String },
+});
+
+watch(
+  [() => props.expanded, () => props.visibleOptions],
+  () => {
+    updateResultCount();
+  },
+  { deep: true },
+);
+
+const resultCountMessage = ref(null);
+
+/** debounced so there is a delay, so screen readers react properly to updates  */
+const debounceUpdateResultCountMessage = debounce(function updateResultCountMessage() {
+  const messageTemplate = props.visibleOptions.length === 1 ? props.resultsMessage : props.resultsMessage_plural;
+  resultCountMessage.value = messageTemplate.replace('{count}', props.visibleOptions.length);
+}, 1400);
+/** immediately clear message, then proceed to update message. This process get the best screen reader results */
+function updateResultCount() {
+  resultCountMessage.value = null;
+  if (props.expanded) {
+    debounceUpdateResultCountMessage();
+  }
+}
+</script>

package/components/combobox/ComboboxClear.vue

@@ -13,9 +13,9 @@
   </button>
 </template>
 
-<script>
-export default {
-  name: 'ComboboxClear',
-  inject: ['iconPath', 'clearInput'],
-};
+<script setup>
+import { inject } from 'vue';
+
+const iconPath = inject('iconPath');
+const clearInput = inject('clearInput');
 </script>

package/components/combobox/ListBox.vue

@@ -12,19 +12,14 @@
   </ul>
 </template>
 
-<script>
-export default {
-  name: 'ListBox',
-  props: {
-    hidden: {
-      type: Boolean,
-      default: true,
-    },
-    isLoading: {
-      type: Boolean,
-      default: true,
-    },
-  },
-  inject: ['iconPath', 'loadingText'],
-};
+<script setup>
+import { inject } from 'vue';
+
+defineProps({
+  hidden: { type: Boolean, default: true },
+  isLoading: { type: Boolean, default: true },
+});
+
+const iconPath = inject('iconPath');
+const loadingText = inject('loadingText');
 </script>