feat(tooltip): improve tooltip accessibility [ES-2025]

.changeset/blue-hats-care.md

@@ -0,0 +1,7 @@
+---
+'@storefront-ui/vue': minor
+---
+
+- **[ADDED]** Support for setting `id` attribute on the content in `SfTooltip` component.
+- **[ADDED]** Possibility to open tooltip programatically via `modelValue` prop.
+- **[ADDED]** `useTooltip` now closes tooltip on `Escape` keypress.

.changeset/great-geckos-dance.md

@@ -0,0 +1,11 @@
+---
+'@storefront-ui/vue': major
+---
+
+- **[CHANGED][BREAKING]** Use `useId` method coming from `vue` package instead of custom implementation. To migrate:
+1. Update your `vue` dependency version to at least 3.5.0.
+2. Update every `useId` usage as follows:
+```diff
+-import { useId } from '@storefront-ui/vue';
++import { useId } from 'vue';
+```

.changeset/tricky-rats-buy.md

@@ -0,0 +1,7 @@
+---
+'@storefront-ui/react': minor
+---
+
+- **[ADDED]** Support for passing `id` and `data-testid` attributes to `SfTooltip` component.
+- **[ADDED]** Possibility to open tooltip programatically via `open` prop.
+- **[ADDED]** `useTooltip` now closes tooltip on `Escape` keypress.

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

@@ -20,6 +20,8 @@ Learn more about `useTooltip` composable in the [Composables > useTooltip docs](
 
 ### Basic Usage
 
+The tooltip appears on hover and is useful for displaying extra information to desktop users. For accessibility, always set the `id` prop on `SfTooltip` and use the same value for the `aria-describedby` attribute on the child element.
+
 <Showcase showcase-name="Tooltip/BasicTooltip">
 
 ::vue-only
@@ -31,6 +33,21 @@ Learn more about `useTooltip` composable in the [Composables > useTooltip docs](
 
 </Showcase>
 
+### Focusable Tooltip content
+
+For improved accessibility and better support for mobile users, ensure the tooltip’s trigger element is focusable. You can do this by applying a `tabindex` attribute or by using a natively focusable element such as a `button` or `input`. Also, handle the `focus` and `blur` events on the trigger to control the tooltip’s visibility. See the showcase below for a implementation example.
+
+<Showcase showcase-name="Tooltip/FocusableTooltip">
+
+::vue-only
+<<<../../../../preview/nuxt/pages/showcases/Tooltip/FocusableTooltip.vue
+::
+::react-only
+<<<../../../../preview/next/pages/showcases/Tooltip/FocusableTooltip.tsx
+::
+
+</Showcase>
+
 ## Accessibility notes
 
 By default, this component sets `role="tooltip"`.
@@ -48,6 +65,7 @@ By default, this component sets `role="tooltip"`.
 | Prop name | Type                                                     | Default value | Possible values |
 | --------- | -------------------------------------------------------- | ------------- | --------------- |
 | `label`\*   | `string`                                                 |               |                 |
+| `modelValue` | `boolean`                                                | `false`       |                 |
 | `showArrow` | `boolean`                                                | `false`       |                 |
 | `placement` | `SfPopoverPlacement`                                    |               |                 |
 | `arrowSize` | `${number}px` &#124; `${number}em` &#124; `${number}rem` |               |                 |
@@ -56,6 +74,7 @@ By default, this component sets `role="tooltip"`.
 | Prop name | Type                                                     | Default value | Possible values |
 | --------- | -------------------------------------------------------- | ------------- | --------------- |
 | `label`\*   | `string`                                                 |               |                 |
+| `open` | `boolean`                                                | `false`       |                 |
 | `showArrow` | `boolean`                                                | `false`       |                 |
 | `placement` | `SfPopoverPlacement`                                    |               |                 |
 | `arrowSize` | `${number}px` &#124; `${number}em` &#124; `${number}rem` |               |                 |

apps/preview/next/pages/showcases/Tooltip/BasicTooltip.tsx

@@ -1,11 +1,15 @@
 import { ShowcasePageLayout } from '../../showcases';
 // #region source
+import { useId } from 'react';
 import { SfTooltip } from '@storefront-ui/react';
 
 export default function BasicTooltip() {
+  const id = useId();
+  const tooltipId = `${id}-tooltip`;
+
   return (
-    <SfTooltip label="This is a tooltip!">
-      <span>Hover me!</span>
+    <SfTooltip label="This is a tooltip!" id={tooltipId}>
+      <span aria-describedby={tooltipId}>Hover me!</span>
     </SfTooltip>
   );
 }

apps/preview/next/pages/showcases/Tooltip/FocusableTooltip.tsx

@@ -0,0 +1,21 @@
+import { ShowcasePageLayout } from '../../showcases';
+// #region source
+import { useId } from 'react';
+import { SfTooltip, useDisclosure } from '@storefront-ui/react';
+
+export default function BasicTooltip() {
+  const id = useId();
+  const tooltipId = `${id}-tooltip`;
+  const { isOpen, open, close } = useDisclosure();
+
+  return (
+    <SfTooltip label="This is a tooltip!" id={tooltipId} open={isOpen} showArrow placement="right">
+      <span aria-describedby={tooltipId} onFocus={open} onBlur={close} tabIndex={0}>
+        Hover or focus me!
+      </span>
+    </SfTooltip>
+  );
+}
+
+// #endregion source
+BasicTooltip.getLayout = ShowcasePageLayout;

apps/preview/nuxt/pages/showcases/Combobox/ComboboxBasic.vue

@@ -107,7 +107,7 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, watch } from 'vue';
+import { ref, watch, useId } from 'vue';
 import { offset } from '@floating-ui/vue';
 import { unrefElement } from '@vueuse/core';
 import {
@@ -118,7 +118,6 @@ import {
   useDisclosure,
   useDropdown,
   useTrapFocus,
-  useId,
 } from '@storefront-ui/vue';
 
 const inputModel = ref('');

apps/preview/nuxt/pages/showcases/FormFields/FormFieldsRequired.vue

@@ -284,7 +284,7 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, type Ref, watch } from 'vue';
+import { ref, type Ref, watch, useId } from 'vue';
 import {
   SfSwitch,
   SfInput,
@@ -298,7 +298,6 @@ import {
   SfIconExpandMore,
   SfListItem,
   SfIconCheck,
-  useId,
   useTrapFocus,
 } from '@storefront-ui/vue';
 import { unrefElement } from '@vueuse/core';

apps/preview/nuxt/pages/showcases/ProductCard/Details.vue

@@ -112,7 +112,7 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
+import { ref, useId } from 'vue';
 import {
   SfButton,
   SfCounter,
@@ -127,7 +127,6 @@ import {
   SfIconShoppingCart,
   SfIconAdd,
   SfIconRemove,
-  useId,
   SfIconShoppingCartCheckout,
 } from '@storefront-ui/vue';
 import { clamp } from '@storefront-ui/shared';

apps/preview/nuxt/pages/showcases/ProductCard/ProductCardHorizontal.vue

@@ -84,8 +84,8 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
-import { SfLink, SfButton, SfIconSell, SfIconAdd, SfIconRemove, SfIconDelete, useId } from '@storefront-ui/vue';
+import { ref, useId } from 'vue';
+import { SfLink, SfButton, SfIconSell, SfIconAdd, SfIconRemove, SfIconDelete } from '@storefront-ui/vue';
 import { clamp } from '@storefront-ui/shared';
 import { useCounter } from '@vueuse/core';
 

apps/preview/nuxt/pages/showcases/QuantitySelector/OutOfStock.vue

@@ -23,8 +23,8 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
-import { SfButton, SfIconAdd, SfIconRemove, useId } from '@storefront-ui/vue';
+import { ref, useId } from 'vue';
+import { SfButton, SfIconAdd, SfIconRemove } from '@storefront-ui/vue';
 
 const min = ref(1);
 const max = ref(10);

apps/preview/nuxt/pages/showcases/QuantitySelector/QuantitySelector.vue

@@ -40,10 +40,10 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
+import { ref, useId } from 'vue';
 import { clamp } from '@storefront-ui/shared';
 import { useCounter } from '@vueuse/core';
-import { SfButton, SfIconAdd, SfIconRemove, useId } from '@storefront-ui/vue';
+import { SfButton, SfIconAdd, SfIconRemove } from '@storefront-ui/vue';
 
 const min = ref(1);
 const max = ref(10);

apps/preview/nuxt/pages/showcases/QuantitySelector/Rounded.vue

@@ -34,9 +34,9 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
+import { ref, useId } from 'vue';
 import { useCounter } from '@vueuse/core';
-import { SfButton, SfIconAdd, SfIconRemove, useId } from '@storefront-ui/vue';
+import { SfButton, SfIconAdd, SfIconRemove } from '@storefront-ui/vue';
 import { clamp } from '@storefront-ui/shared';
 
 const min = ref(1);

apps/preview/nuxt/pages/showcases/RatingButton/Basic.vue

@@ -6,8 +6,8 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
-import { SfRatingButton, useId } from '@storefront-ui/vue';
+import { ref, useId } from 'vue';
+import { SfRatingButton } from '@storefront-ui/vue';
 const labelId = useId();
 const modelValue = ref();
 </script>

apps/preview/nuxt/pages/showcases/RatingButton/CustomIcon.vue

@@ -21,8 +21,8 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
-import { SfRatingButton, SfIconFavorite, SfIconFavoriteFilled, useId } from '@storefront-ui/vue';
+import { ref, useId } from 'vue';
+import { SfRatingButton, SfIconFavorite, SfIconFavoriteFilled } from '@storefront-ui/vue';
 const labelId = useId();
 const modelValue = ref(2);
 </script>

apps/preview/nuxt/pages/showcases/RatingButton/MaxNumber.vue

@@ -6,8 +6,8 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
-import { SfRatingButton, useId } from '@storefront-ui/vue';
+import { ref, useId } from 'vue';
+import { SfRatingButton } from '@storefront-ui/vue';
 const labelId = useId();
 const modelValue = ref(5);
 </script>

apps/preview/nuxt/pages/showcases/RatingForms/ProductRating.vue

@@ -39,8 +39,8 @@
 </template>
 
 <script lang="ts" setup>
-import { ref } from 'vue';
-import { SfModal, SfButton, SfIconClose, useDisclosure, SfRatingButton, useId } from '@storefront-ui/vue';
+import { ref, useId } from 'vue';
+import { SfModal, SfButton, SfIconClose, useDisclosure, SfRatingButton } from '@storefront-ui/vue';
 
 const { isOpen, open, close } = useDisclosure({ initialValue: true });
 const modelValue = ref();

apps/preview/nuxt/pages/showcases/RatingForms/ProductRatingWithReview.vue

@@ -48,8 +48,8 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, computed } from 'vue';
-import { SfButton, SfRatingButton, SfInput, useId } from '@storefront-ui/vue';
+import { ref, computed, useId } from 'vue';
+import { SfButton, SfRatingButton, SfInput } from '@storefront-ui/vue';
 
 const ratingLabelId = useId();
 const ratingModelValue = ref();

apps/preview/nuxt/pages/showcases/SelectDropdown/SelectDropdownDisabled.vue

@@ -59,15 +59,14 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, type Ref } from 'vue';
+import { ref, type Ref, useId } from 'vue';
 import { unrefElement } from '@vueuse/core';
 import {
   useDropdown,
   useDisclosure,
   SfIconExpandMore,
   SfListItem,
   SfIconCheck,
-  useId,
   useTrapFocus,
 } from '@storefront-ui/vue';
 

apps/preview/nuxt/pages/showcases/SelectDropdown/SelectDropdownError.vue

@@ -59,15 +59,14 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, computed, type Ref } from 'vue';
+import { ref, computed, type Ref, useId } from 'vue';
 import { unrefElement } from '@vueuse/core';
 import {
   useDropdown,
   useDisclosure,
   SfIconExpandMore,
   SfListItem,
   SfIconCheck,
-  useId,
   useTrapFocus,
 } from '@storefront-ui/vue';
 

apps/preview/nuxt/pages/showcases/SelectDropdown/SelectDropdownPreselected.vue

@@ -53,15 +53,14 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, type Ref } from 'vue';
+import { ref, type Ref, useId } from 'vue';
 import { unrefElement } from '@vueuse/core';
 import {
   useDropdown,
   useDisclosure,
   SfIconExpandMore,
   SfListItem,
   SfIconCheck,
-  useId,
   useTrapFocus,
 } from '@storefront-ui/vue';
 

apps/preview/nuxt/pages/showcases/SelectDropdown/SelectDropdownWithPlaceholder.vue

@@ -53,15 +53,14 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, type Ref } from 'vue';
+import { ref, type Ref, useId } from 'vue';
 import { unrefElement } from '@vueuse/core';
 import {
   useDropdown,
   useDisclosure,
   SfIconExpandMore,
   SfListItem,
   SfIconCheck,
-  useId,
   useTrapFocus,
 } from '@storefront-ui/vue';
 

apps/preview/nuxt/pages/showcases/Tooltip/BasicTooltip.vue

@@ -1,9 +1,15 @@
 <template>
   <div class="mt-12">
-    <SfTooltip label="This is a tooltip!"> Hover me! </SfTooltip>
+    <SfTooltip label="This is a tooltip!" :id="tooltipId">
+      <span :aria-describedby="tooltipId"> Hover me! </span>
+    </SfTooltip>
   </div>
 </template>
 
 <script setup lang="ts">
+import { useId } from 'vue';
 import { SfTooltip } from '@storefront-ui/vue';
+
+const id = useId();
+const tooltipId = `${id}-tooltip`;
 </script>

apps/preview/nuxt/pages/showcases/Tooltip/FocusableTooltip.vue

@@ -0,0 +1,14 @@
+<template>
+  <SfTooltip label="This is a tooltip!" :id="tooltipId" v-model="isOpen" show-arrow placement="right">
+    <span :aria-describedby="tooltipId" @focus="open" @blur="close" tabindex="0"> Hover or focus me! </span>
+  </SfTooltip>
+</template>
+
+<script setup lang="ts">
+import { useId } from 'vue';
+import { SfTooltip, useDisclosure } from '@storefront-ui/vue';
+
+const id = useId();
+const tooltipId = `${id}-tooltip`;
+const { isOpen, open, close } = useDisclosure();
+</script>

packages/sfui/frameworks/nuxt/src/module.ts

@@ -56,8 +56,7 @@ export default defineNuxtModule<ModuleOptions>({
       if (key.startsWith('Sf') && (storefrontUi[key].__name || storefrontUi[key].name)) {
         components.push(key);
       } else if (key.startsWith('use')) {
-        // `useId` is already available in nuxtjs, we omit `useId` because of duplication warning
-        if (key !== 'useId') composables.push(key);
+        composables.push(key);
       }
     });