Improve grouping of elements for a better description of AX tags in videos (#807)

* Improve how we group videos for AX descriptions

* Delete dots from video indentifier

* Create unique id for custom-controls

* It does not render the reference to the alt id in video-replay-container if alt does not exit

* Escape dots in Jest using a backslash

Author: marinaaisa

src/components/ReplayableVideoAsset.vue

@@ -9,7 +9,18 @@
 -->
 
 <template>
-  <div class="video-replay-container">
+  <div
+    class="video-replay-container"
+    role="group"
+    :aria-roledescription="$t('video.title')"
+    :aria-labelledby="!showsDefaultControls ? ariaLabelledByContainer : null"
+  >
+    <span
+      :id="`${id}-custom-controls`"
+      hidden
+    >
+      {{ $t('video.custom-controls') }}
+    </span>
     <VideoAsset
       ref="asset"
       :variants="variants"
@@ -92,6 +103,9 @@ export default {
       if (this.videoEnded) return this.$t('video.replay');
       return this.isPlaying ? this.$t('video.pause') : this.$t('video.play');
     },
+    ariaLabelledByContainer: ({ id, alt }) => (alt
+      ? `${id}-custom-controls ${id}-alt`
+      : `${id}-custom-controls`),
   },
   data() {
     return {

src/components/VideoAsset.vue

@@ -27,8 +27,7 @@
         :muted="muted"
         :width="optimalWidth"
         :aria-roledescription="$t('video.title')"
-        :aria-label="!showsDefaultControls ? $t('video.custom-controls') : null"
-        :aria-describedby="alt ? altTextId : null"
+        :aria-labelledby="showsDefaultControls && alt ? altTextId : null"
         playsinline
         @loadedmetadata="setOrientation"
         @playing="$emit('playing')"
@@ -46,7 +45,7 @@
       <span
         v-if="alt"
         :id="altTextId"
-        class="visuallyhidden"
+        hidden
       >
         {{ $t('video.description', { alt }) }}
       </span>

src/lang/locales/en-US.json

@@ -8,8 +8,8 @@
     "play": "Play",
     "pause": "Pause",
     "watch": "Watch intro video",
-    "description": "Content description of this video: {alt}",
-    "custom-controls": "Custom controls are available below"
+    "description": "Content description: {alt}",
+    "custom-controls": "Video with custom controls."
   },
   "tutorials": {
     "title": "Tutorial | Tutorials",

tests/unit/components/Asset.spec.js

@@ -8,6 +8,7 @@
  * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
+/* eslint-disable no-useless-escape */
 import { shallowMount } from '@vue/test-utils';
 import Asset from 'docc-render/components/Asset.vue';
 import ImageAsset from 'docc-render/components/ImageAsset.vue';
@@ -20,7 +21,7 @@ const video = {
   alt: 'Text describing this video',
   variants: [
     {
-      url: 'foo.mp4',
+      url: 'foo\.mp4',
       traits: ['2x'],
       size: {
         width: 42,
@@ -63,7 +64,7 @@ describe('Asset', () => {
       alt: 'blah',
       variants: [
         {
-          url: 'foo.png',
+          url: 'foo\.png',
           traits: ['2x'],
           size: {
             width: 42,
@@ -84,7 +85,7 @@ describe('Asset', () => {
       type: 'image',
       variants: [
         {
-          url: 'image.jpg',
+          url: 'image\.jpg',
           traits: ['2x', 'light'],
         },
       ],
@@ -226,7 +227,7 @@ describe('Asset', () => {
       alt: 'blah',
       variants: [
         {
-          url: 'foo.png',
+          url: 'foo\.png',
           traits: ['2x'],
           size: {
             width: 42,

tests/unit/components/ReplayableVideoAsset.spec.js

@@ -24,7 +24,7 @@ const propsData = {
   posterVariants,
   showsDefaultControls: false,
   alt: 'Text describing this video',
-  id: 'video.mp4',
+  id: 'videomp4',
 };
 describe('ReplayableVideoAsset', () => {
   const mountWithProps = props => shallowMount(ReplayableVideoAsset, {
@@ -73,6 +73,39 @@ describe('ReplayableVideoAsset', () => {
     expect(wrapper.find('.control-button').exists()).toBe(true);
   });
 
+  it('renders a video-replay-container as a group with AX aria tags', () => {
+    const wrapper = mountWithProps();
+    const ariaLabelledByContainer = `${propsData.id}-custom-controls ${propsData.id}-alt`;
+
+    const container = wrapper.find('.video-replay-container');
+    expect(container.attributes('role')).toBe('group');
+    expect(container.attributes('aria-labelledby')).toBe(ariaLabelledByContainer);
+
+    const customControlsDescription = wrapper.find(`#${propsData.id}-custom-controls`);
+    expect(customControlsDescription.exists()).toBe(true);
+    expect(customControlsDescription.attributes('hidden')).toBe('hidden');
+    expect(customControlsDescription.text()).toBe('video.custom-controls');
+  });
+
+  it('does not render the reference to the alt id in video-replay-container if alt does not exit', () => {
+    const wrapper = mountWithProps({
+      alt: '',
+    });
+    const ariaLabelledByContainer = `${propsData.id}-custom-controls`;
+
+    const container = wrapper.find('.video-replay-container');
+    expect(container.attributes('aria-labelledby')).toBe(ariaLabelledByContainer);
+  });
+
+  it('renders a video-replay-container without "aria-labelledby" if showsDefaultControls is true', () => {
+    const wrapper = mountWithProps({
+      showsDefaultControls: true,
+    });
+
+    const container = wrapper.find('.video-replay-container');
+    expect(container.attributes()).not.toHaveProperty('aria-labelledby');
+  });
+
   it('does not show the `.control-button` if `showsDefaultControls` is `true`', () => {
     const wrapper = mountWithProps({
       showsDefaultControls: true,

tests/unit/components/VideoAsset.spec.js

@@ -39,7 +39,8 @@ const propsData = {
     { traits: ['dark', '1x'], url: 'https://www.example.com/video~dark.mp4' },
   ],
   alt: 'Text describing this video',
-  id: 'video.mp4',
+  id: 'videomp4',
+  showsDefaultControls: false,
 };
 
 const altTextId = `${propsData.id}-alt`;
@@ -61,21 +62,21 @@ describe('VideoAsset', () => {
   });
 
   it('renders a hidden description with unique id for AX purposes if video provides an alt text', () => {
-    const hiddenDesc = wrapper.find('span.visuallyhidden');
+    const hiddenDesc = wrapper.find('span[hidden=hidden]');
     expect(hiddenDesc.exists()).toBe(true);
     expect(hiddenDesc.attributes('id')).toBe(altTextId);
     expect(hiddenDesc.text()).toBe(`video.description ${propsData.alt}`);
   });
 
-  it('adds a description reference to the `video` with altTextId', () => {
+  it('adds a description reference to the `video` if showsDefaultControls is true', () => {
+    wrapper.setProps({ showsDefaultControls: true });
     const video = wrapper.find('video');
-    expect(video.attributes('aria-describedby')).toBe(altTextId);
+    expect(video.attributes('aria-labelledby')).toBe(altTextId);
   });
 
   it('does not add a description reference to the `video` if alt is not provided', () => {
     wrapper.setProps({ alt: null });
-    const video = wrapper.find('video');
-    expect(video.attributes()).not.toHaveProperty('aria-describedby');
+    expect(wrapper.find('video').attributes()).not.toHaveProperty('aria-labelledby');
   });
 
   it('adds a poster to the `video`, using light by default', async () => {
@@ -158,14 +159,6 @@ describe('VideoAsset', () => {
     expect(source.attributes('controls')).toBe(undefined);
   });
 
-  it('renders an aria-label to indicate how the user should interact with custom controls when `showsDefaultControls=false`', () => {
-    wrapper.setProps({
-      showControls: false,
-    });
-    const video = wrapper.find('video');
-    expect(video.attributes('aria-label')).toBe('video.custom-controls');
-  });
-
   it('forwards `playing`, `pause` and `ended` events', () => {
     const video = wrapper.find('video');