fix: onClose callback triggered too often [ES-2025]

onClose callback now will be triggered only if outside click triggers closing of the dropdown
add useDropdown & SfDropdown examples with proper a11y

Author: FRSgit

.changeset/ten-buckets-help.md

@@ -0,0 +1,5 @@
+---
+'@storefront-ui/vue': major
+---
+
+- \*\*[FIXED][BREAKING] From now on, `onClose` callback in `useDropdown` will be triggered only if outside click triggers closing of the dropdown.

apps/docs/components/content/_components/dropdown.md

@@ -40,6 +40,10 @@ By default, the floating content of `SfDropdown` will be placed below your trigg
 
 The floating content area has an `aria-hidden` attribute that reflects the visibility of the dropdown (`modelValue`). When the dropdown is not open (`modelValue` is `false`), the `aria-hidden` attribute is set to `true`, ensuring that the content is hidden from assistive technologies.
 
+::tip
+This component lets you create many types of custom dropdowns, such as navigation menus, comboboxes, or select lists. However, accessibility depends on how you implement it in your use case. Always ensure users can move through items in the dropdown using arrow keys and/or the Tab key. Additionally, after the dropdown is closed, make sure focus returns to the trigger element.
+::
+
 ## Playground
 
 <Generate style="height: 450px" />

apps/docs/components/content/_hooks/useDropdown.md

@@ -8,40 +8,13 @@
 
 ## Usage
 
+::react-only
 For a minimal example, we can implement a floating element using two properties returned by the `useDropdown` hook.
 
 1. `refs` - An object that contains a `setReference` and `setFloating` function. These functions should be bound to the element that the floating element will be positioned relative to and the floating element itself, respectively.
 2. `style` - An object containing the position styles for your floating element.
 
 By binding these properties to the appropriate elements, we can create a dropdown menu that opens when a button is clicked.
-
-::react-only
-```tsx
-import * as React from 'react';
-import { useDropdown, SfButton } from '@storefront-ui/react';
-
-function Dropdown() {
-  const [isOpen, setOpen] = React.useState(false);
-
-  const close = () => setOpen(false);
-  const toggle = () => setOpen((isOpen) => !isOpen);
-
-  const { refs, style } = useDropdown({ isOpen, onClose: close });
-
-  return (
-    <div ref={refs.setReference} className="w-max">
-      <SfButton onClick={toggle}>Toggle</SfButton>
-      {isOpen && (
-        <ul ref={refs.setFloating} style={style.floating} className="absolute p-2 w-max rounded-sm bg-gray-100">
-          <li>More</li>
-          <li>About</li>
-          <li>Settings</li>
-        </ul>
-      )}
-    </div>
-  );
-}
-```
 ::
 
 ::vue-only
@@ -52,30 +25,19 @@ For a minimal example, we can implement a floating element using three propertie
 3. `style` - An object containing the position styles for your floating element.
 
 By binding these properties to the appropriate elements, we can create a dropdown menu that opens when a button is clicked.
+::
+
+<Showcase showcase-name="useDropdown/UseDropdown">
 
-```vue
-<script lang="ts" setup>
-import { ref } from 'vue';
-import { useDropdown, SfButton } from '@storefront-ui/vue';
-
-const isOpen = ref(false);
-
-const { referenceRef, floatingRef, style } = useDropdown({ isOpen, onClose: () => isOpen.value = false });
-</script>
-
-<template>
-  <div ref="referenceRef" class="w-max">
-    <SfButton @click="isOpen = !isOpen">Toggle</SfButton>
-    <ul v-if="isOpen" ref="floatingRef" :style="style" class="absolute p-2 w-max rounded-sm bg-gray-100">
-      <li>More</li>
-      <li>About</li>
-      <li>Settings</li>
-    </ul>
-  </div>
-</template>
-```
+::react-only
+<<<../../../../preview/next/pages/showcases/useDropdown/UseDropdown.tsx#source
+::
+::vue-only
+<<<../../../../preview/nuxt/pages/showcases/useDropdown/UseDropdown.vue
 ::
 
+</Showcase>
+
 ::tip There are more options!
 For a full list of the possible parameters and return values, see the API section.
 ::

apps/preview/next/pages/showcases/Dropdown/BasicDropdown.tsx

@@ -1,16 +1,27 @@
 import { ShowcasePageLayout } from '../../showcases';
 
 // #region source
+import { useRef } from 'react';
 import { SfButton, SfDropdown, useDisclosure } from '@storefront-ui/react';
 
 export default function BasicDropdown() {
   const { isOpen, toggle, close } = useDisclosure();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  const handleClose = () => {
+    close();
+    triggerRef.current?.focus();
+  };
   return (
-    <SfDropdown trigger={<SfButton onClick={toggle}>Toggle</SfButton>} open={isOpen} onClose={close}>
+    <SfDropdown
+      trigger={<SfButton ref={triggerRef}
+      onClick={toggle}>Toggle</SfButton>}
+      open={isOpen} onClose={handleClose}
+    >
       <ul className="p-2 rounded-sm bg-gray-100">
-        <li>More</li>
-        <li>About</li>
-        <li>Settings</li>
+        <li tabIndex={0}>More</li>
+        <li tabIndex={0}>About</li>
+        <li tabIndex={0}>Settings</li>
       </ul>
     </SfDropdown>
   );

apps/preview/next/pages/showcases/useDropdown/UseDropdown.tsx

@@ -0,0 +1,34 @@
+/* eslint-disable jsx-a11y/label-has-associated-control */
+import { ShowcasePageLayout } from '../../showcases';
+// #region source
+import * as React from 'react';
+import { useDropdown, SfButton } from '@storefront-ui/react';
+
+export default function Dropdown() {
+  const [isOpen, setOpen] = React.useState(false);
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
+
+  const close = () => {
+    setOpen(false);
+    triggerRef.current?.focus();
+  };
+  const toggle = () => setOpen((isOpen) => !isOpen);
+
+  const { refs, style } = useDropdown({ isOpen, onClose: close });
+
+  return (
+    <div ref={refs.setReference} className="w-max">
+      <SfButton ref={triggerRef} onClick={toggle}>Toggle</SfButton>
+      {isOpen && (
+        <ul ref={refs.setFloating} style={style} className="absolute p-2 w-max rounded-sm bg-gray-100">
+          <li tabIndex={0}>More</li>
+          <li tabIndex={0}>About</li>
+          <li tabIndex={0}>Settings</li>
+        </ul>
+      )}
+    </div>
+  );
+}
+
+// #endregion source
+Dropdown.getLayout = ShowcasePageLayout;

apps/preview/nuxt/pages/showcases/Dropdown/BasicDropdown.vue

@@ -1,18 +1,26 @@
 <template>
-  <SfDropdown v-model="isOpen">
+  <SfDropdown v-model="isOpen" @update:modelValue="onToggle">
     <template #trigger>
-      <SfButton @click="toggle()">Toggle</SfButton>
+      <SfButton ref="triggerRef" @click="toggle()">Toggle</SfButton>
     </template>
     <ul class="p-2 rounded-sm bg-gray-100">
-      <li>More</li>
-      <li>About</li>
-      <li>Settings</li>
+      <li tabIndex="0">More</li>
+      <li tabIndex="0">About</li>
+      <li tabIndex="0">Settings</li>
     </ul>
   </SfDropdown>
 </template>
 
 <script lang="ts" setup>
 import { SfDropdown, useDisclosure, SfButton } from '@storefront-ui/vue';
+import { templateRef, unrefElement } from '@vueuse/core';
 
 const { isOpen, toggle } = useDisclosure();
+const triggerRef = templateRef('triggerRef');
+
+const onToggle = (isOpen: boolean) => {
+  if (!isOpen) {
+    unrefElement(triggerRef.value)?.focus();
+  }
+};
 </script>

apps/preview/nuxt/pages/showcases/useDropdown/UseDropdown.vue

@@ -0,0 +1,26 @@
+<template>
+  <div ref="referenceRef" class="w-max">
+    <SfButton ref="triggerRef" @click="isOpen = !isOpen">Toggle</SfButton>
+    <ul v-if="isOpen" ref="floatingRef" :style="style" class="absolute p-2 w-max rounded-sm bg-gray-100">
+      <li tabIndex="0">More</li>
+      <li tabIndex="0">About</li>
+      <li tabIndex="0">Settings</li>
+    </ul>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { ref } from 'vue';
+import { useDropdown, SfButton } from '@storefront-ui/vue';
+import { templateRef, unrefElement } from '@vueuse/core';
+
+const isOpen = ref(false);
+const triggerRef = templateRef('triggerRef');
+
+const close = () => {
+  isOpen.value = false;
+  unrefElement(triggerRef.value)?.focus();
+};
+
+const { referenceRef, floatingRef, style } = useDropdown({ isOpen, onClose: close });
+</script>

packages/sfui/frameworks/vue/composables/useDropdown/useDropdown.ts

@@ -13,7 +13,11 @@ export function useDropdown(options: UseDropdownOptions) {
     ...popoverOptions,
   });
 
-  onClickOutside(referenceRef as MaybeElementRef, onClose);
+  onClickOutside(referenceRef as MaybeElementRef, () => {
+    if (toValue(isOpen)) {
+      onClose?.();
+    }
+  });
   onKeyStroke('Escape', onClose, { target: referenceRef as MaybeRefOrGetter<EventTarget | null | undefined> });
 
   return { floatingRef, referenceRef, style };