feat: add isMenuOpen prop to programatically control menu state (#182)

* feat: add isMenuOpen prop to programatically control menu state

Fixes #161

Add an option to programmatically control the menu open state.

* Add a new prop `isMenuOpen` to `src/Select.vue` to control the menu open state.
* Update the `openMenu` and `closeMenu` methods to use the `isMenuOpen` prop.
* Add a watcher to sync the `menuOpen` state with the `isMenuOpen` prop.
* Update the documentation in `docs/props.md` to include the new `isMenuOpen` prop.
* Add tests in `src/Select.spec.ts` to verify the functionality of the `isMenuOpen` prop.

---

For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/TotomInc/vue3-select-component/issues/161?shareId=XXXX-XXXX-XXXX-XXXX).

* fix: improve input keydown space detection

* fix(select): watch props.isMenuOpen should be immediate

* feat(select): emit menuOpened and menuClosed, ensure closeMenu/openMenu are called internally

* feat(docs): add menu-closed and menu-opened events

* feat(docs): add controlled menu demo

Author: TotomInc

docs/.vitepress/config.ts

@@ -53,6 +53,7 @@ export default defineConfig({
           { text: "Disabled options", link: "/demo/disabled-options" },
           { text: "With menu-header", link: "/demo/with-menu-header" },
           { text: "With complex menu filter", link: "/demo/with-complex-menu-filter.md" },
+          { text: "Controlled Menu", link: "/demo/controlled-menu" },
         ],
       },
     ],

docs/demo/controlled-menu.md

@@ -0,0 +1,62 @@
+---
+title: 'Controlled Menu'
+---
+
+# Controlled Menu
+
+Control the menu open state programmatically with the `isMenuOpen` prop.
+
+<script setup>
+import { ref } from "vue";
+
+import VueSelect from "../../src";
+
+const selected = ref("");
+const isMenuOpen = ref(false);
+</script>
+
+<button type="button" @click="isMenuOpen = !isMenuOpen">
+  Toggle menu ({{ isMenuOpen ? "opened" : "closed" }})
+</button>
+
+<VueSelect
+  v-model="selected"
+  :options="[
+    { label: 'Option #1', value: 'option_1' },
+    { label: 'Option #2', value: 'option_2' },
+    { label: 'Option #3', value: 'option_3' },
+  ]"
+  :is-menu-open="isMenuOpen"
+  @menu-opened="isMenuOpen = true"
+  @menu-closed="isMenuOpen = false"
+/>
+
+## Demo source-code
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import VueSelect from "vue3-select-component";
+
+const selected = ref("");
+const isMenuOpen = ref(false);
+</script>
+
+<template>
+  <button type="button" @click="isMenuOpen = !isMenuOpen">
+    Toggle menu ({{ isMenuOpen ? "opened" : "closed" }})
+  </button>
+
+  <VueSelect
+    v-model="selected"
+    :options="[
+      { label: 'Option #1', value: 'option_1' },
+      { label: 'Option #2', value: 'option_2' },
+      { label: 'Option #3', value: 'option_3' },
+    ]"
+    :is-menu-open="isMenuOpen"
+    @menu-opened="isMenuOpen = true"
+    @menu-closed="isMenuOpen = false"
+  />
+</template>
+```

docs/events.md

@@ -65,3 +65,31 @@ Search value is cleared when the menu is closed. This will trigger an empty stri
   />
 </template>
 ```
+
+## `@menu-opened`
+
+Emitted when the menu is opened.
+
+```vue
+<template>
+  <VueSelect
+    v-model="selectedValue"
+    :options="options"
+    @menu-opened="() => console.log('menu opened')"
+  />
+</template>
+```
+
+## `@menu-closed`
+
+Emitted when the menu is closed.
+
+```vue
+<template>
+  <VueSelect
+    v-model="selectedValue"
+    :options="options"
+    @menu-closed="() => console.log('menu closed')"
+  />
+</template>
+```

docs/props.md

@@ -226,6 +226,10 @@ Resolves option data to a string to compare options and specify value attributes
 
 This function can be used if you don't want to use the standard `option.value` as the value of the option.
 
-::: warning
-If you are using TypeScript, TODO.
-:::
+## isMenuOpen
+
+**Type**: `boolean`
+
+**Default**: `undefined`
+
+A prop to control the menu open state programmatically. When set to `true`, the menu will be open. When set to `false`, the menu will be closed.

src/Select.spec.ts

@@ -17,7 +17,7 @@ async function openMenu(wrapper: ReturnType<typeof mount>, method: "mousedown" |
   }
   else if (method === "focus-space") {
     await wrapper.get("input").trigger("focus");
-    await wrapper.get("input").trigger("keydown", { key: "Space" });
+    await wrapper.get("input").trigger("keydown", { code: "Space" });
   }
   else if (method === "single-value") {
     await wrapper.get(".single-value").trigger("click");
@@ -105,7 +105,7 @@ describe("input + menu interactions behavior", () => {
 
     expect(wrapper.findAll("div[role='option']").length).toBe(options.length);
 
-    await dispatchEvent(wrapper, new MouseEvent("click"));
+    await dispatchEvent(wrapper, new MouseEvent("mousedown"));
 
     expect(wrapper.findAll("div[role='option']").length).toBe(0);
   });
@@ -133,6 +133,22 @@ describe("input + menu interactions behavior", () => {
 
     expect(wrapper.findAll("div[role='option']").length).toBe(0);
   });
+
+  it("should open the menu when isMenuOpen prop is set to true", async () => {
+    const wrapper = mount(VueSelect, { props: { modelValue: null, options, isMenuOpen: true } });
+
+    expect(wrapper.findAll("div[role='option']").length).toBe(options.length);
+  });
+
+  it("should close the menu when isMenuOpen prop is set to false", async () => {
+    const wrapper = mount(VueSelect, { props: { modelValue: null, options, isMenuOpen: true } });
+
+    expect(wrapper.findAll("div[role='option']").length).toBe(options.length);
+
+    await wrapper.setProps({ isMenuOpen: false });
+
+    expect(wrapper.findAll("div[role='option']").length).toBe(0);
+  });
 });
 
 describe("menu on-open focus option", async () => {
@@ -401,7 +417,7 @@ describe("search emit", () => {
     const wrapper = mount(VueSelect, { props: { modelValue: null, options } });
 
     await inputSearch(wrapper, "United");
-    await dispatchEvent(wrapper, new MouseEvent("click"));
+    await dispatchEvent(wrapper, new MouseEvent("mousedown"));
 
     expect(wrapper.emitted("search")).toStrictEqual([["United"], [""]]);
   });

src/Select.vue

@@ -42,6 +42,10 @@ const props = withDefaults(
      * when fetching the options asynchronously.
      */
     isLoading?: boolean;
+    /**
+     * Control the menu open state programmatically.
+     */
+    isMenuOpen?: boolean;
     /**
      * When set to true, focus the first option when the menu is opened.
      * When set to false, no option will be focused.
@@ -98,6 +102,7 @@ const props = withDefaults(
     isSearchable: true,
     isMulti: false,
     isLoading: false,
+    isMenuOpen: undefined,
     shouldAutofocusOption: true,
     closeOnSelect: true,
     teleport: undefined,
@@ -112,6 +117,8 @@ const props = withDefaults(
 const emit = defineEmits<{
   (e: "optionSelected", option: GenericOption): void;
   (e: "optionDeselected", option: GenericOption | null): void;
+  (e: "menuOpened"): void;
+  (e: "menuClosed"): void;
   (e: "search", value: string): void;
 }>();
 
@@ -185,11 +192,14 @@ const openMenu = (options?: { focusInput?: boolean }) => {
   if (options?.focusInput && input.value) {
     input.value.focus();
   }
+
+  emit("menuOpened");
 };
 
 const closeMenu = () => {
   menuOpen.value = false;
   search.value = "";
+  emit("menuClosed");
 };
 
 const toggleMenu = () => {
@@ -218,7 +228,7 @@ const setOption = (option: GenericOption) => {
   search.value = "";
 
   if (props.closeOnSelect) {
-    menuOpen.value = false;
+    closeMenu();
   }
 
   if (input.value) {
@@ -243,8 +253,7 @@ const clear = () => {
     emit("optionDeselected", selectedOptions.value[0]);
   }
 
-  menuOpen.value = false;
-  search.value = "";
+  closeMenu();
 
   if (input.value) {
     input.value.blur();
@@ -303,8 +312,7 @@ const handleNavigation = (e: KeyboardEvent) => {
 
     if (e.key === "Escape") {
       e.preventDefault();
-      menuOpen.value = false;
-      search.value = "";
+      closeMenu();
     }
 
     const hasSelectedValue = props.isMulti ? (selected.value as OptionValue[]).length > 0 : !!selected.value;
@@ -323,33 +331,20 @@ const handleNavigation = (e: KeyboardEvent) => {
   }
 };
 
-/**
- * When pressing space inside the input, open the menu only if the search is
- * empty. Otherwise, the user is typing and we should skip this action.
- *
- * @param e KeyboardEvent
- */
-const handleInputSpace = (e: KeyboardEvent) => {
-  if (!menuOpen.value && search.value.length === 0) {
-    e.preventDefault();
-    e.stopImmediatePropagation();
-    openMenu();
-  }
-};
-
 const handleInputKeydown = (e: KeyboardEvent) => {
   if (e.key === "Tab") {
     closeMenu();
   }
-  else if (e.key === "Space") {
-    handleInputSpace(e);
+  else if (e.code === "Space" && !menuOpen.value && search.value.length === 0) {
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    openMenu();
   }
 };
 
 const handleClickOutside = (event: MouseEvent) => {
   if (container.value && !container.value.contains(event.target as Node)) {
-    menuOpen.value = false;
-    search.value = "";
+    closeMenu();
   }
 };
 
@@ -380,13 +375,26 @@ watch(
   },
 );
 
+watch(
+  () => props.isMenuOpen,
+  (newValue) => {
+    if (newValue) {
+      openMenu({ focusInput: true });
+    }
+    else {
+      closeMenu();
+    }
+  },
+  { immediate: true },
+);
+
 onMounted(() => {
-  document.addEventListener("click", handleClickOutside);
+  document.addEventListener("mousedown", handleClickOutside);
   document.addEventListener("keydown", handleNavigation);
 });
 
 onBeforeUnmount(() => {
-  document.removeEventListener("click", handleClickOutside);
+  document.removeEventListener("mousedown", handleClickOutside);
   document.removeEventListener("keydown", handleNavigation);
 });
 </script>