Add alt text for screen readers to describe video content (#784)

marinaaisa · web-flow · commit a5b6ef95f89e · 2024-03-14T07:47:25.000+01:00
* [rdar://120903895] Render a hidden description with unique id for AX purposes if video provides an alt text

* [rdar://120903895] Add a description reference to Control Button in ReplayableVideoAsset

* [rdar://120903895] Add a description reference to video in VideoAsset

* [rdar://120903895] Update license headers

* [rdar://120903895] Replace id || null with alt ? id : null

* [rdar://120903895] Add `aria-label`, `aria-roledescription` and `aria-controls` to the video

* [rdar://120903895] Address feedback

* [rdar://120903895] Fix failing test

* [rdar://120903895] Move description

* [rdar://120903895] Change text for custom-controls

* [rdar://120903895] Delete wrong test
diff --git a/src/components/Asset.vue b/src/components/Asset.vue
@@ -1,7 +1,7 @@
 <!--
   This source file is part of the Swift.org open source project
 
-  Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+  Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
   Licensed under Apache License v2.0 with Runtime Library Exception
 
   See https://swift.org/LICENSE.txt for license information
@@ -105,11 +105,13 @@ export default {
     videoProps() {
       return {
         variants: this.asset.variants,
-        showsControls: this.showsVideoControls,
+        showsDefaultControls: this.showsVideoControls,
         muted: this.videoMuted,
         autoplays: this.prefersReducedMotion ? false : this.videoAutoplays,
         posterVariants: this.videoPoster ? this.videoPoster.variants : [],
         deviceFrame: this.deviceFrame,
+        alt: this.asset.alt,
+        id: this.identifier,
       };
     },
     assetListeners() {
diff --git a/src/components/ReplayableVideoAsset.vue b/src/components/ReplayableVideoAsset.vue
@@ -1,7 +1,7 @@
 <!--
   This source file is part of the Swift.org open source project
 
-  Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+  Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
   Licensed under Apache License v2.0 with Runtime Library Exception
 
   See https://swift.org/LICENSE.txt for license information
@@ -14,18 +14,21 @@
       ref="asset"
       :variants="variants"
       :autoplays="autoplays"
-      :showsControls="showsControls"
+      :showsDefaultControls="showsDefaultControls"
       :muted="muted"
       :posterVariants="posterVariants"
       :deviceFrame="deviceFrame"
+      :alt="alt"
+      :id="id"
       @pause="onPause"
       @playing="onVideoPlaying"
       @ended="onVideoEnd"
     />
     <a
-      v-if="!showsControls"
+      v-if="!showsDefaultControls"
       class="control-button"
       href="#"
+      :aria-controls="id"
       @click.prevent="togglePlayStatus"
     >
       {{ text }}
@@ -55,7 +58,15 @@ export default {
       type: Array,
       required: true,
     },
-    showsControls: {
+    alt: {
+      type: String,
+      required: false,
+    },
+    id: {
+      type: String,
+      required: true,
+    },
+    showsDefaultControls: {
       type: Boolean,
       default: () => false,
     },
@@ -110,7 +121,7 @@ export default {
     onPause() {
       const { video } = this.$refs.asset.$refs;
       // if the video pauses, and we are hiding the controls, show the replay button
-      if (!this.showsControls && this.isPlaying) {
+      if (!this.showsDefaultControls && this.isPlaying) {
         this.isPlaying = false;
       }
       this.videoEnded = video.ended;
diff --git a/src/components/VideoAsset.vue b/src/components/VideoAsset.vue
@@ -1,7 +1,7 @@
 <!--
   This source file is part of the Swift.org open source project
 
-  Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+  Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
   Licensed under Apache License v2.0 with Runtime Library Exception
 
   See https://swift.org/LICENSE.txt for license information
@@ -15,29 +15,42 @@
     :should-wrap="!!deviceFrame"
     :device="deviceFrame"
   >
-    <video
-      ref="video"
-      :key="videoAttributes.url"
-      :controls="showsControls"
-      :data-orientation="orientation"
-      :autoplay="autoplays"
-      :poster="normalisedPosterPath"
-      :muted="muted"
-      :width="optimalWidth"
-      playsinline
-      @loadedmetadata="setOrientation"
-      @playing="$emit('playing')"
-      @pause="$emit('pause')"
-      @ended="$emit('ended')"
-    >
-      <!--
-        Many browsers do not support the `media` attribute for `<source>` tags
-        within a video specifically, so this implementation for dark theme assets
-        is handled with JavaScript media query listeners unlike the `<source>`
-        based implementation being used for image assets.
-      -->
-      <source :src="normalizePath(videoAttributes.url)">
-    </video>
+    <div>
+      <video
+        ref="video"
+        :key="videoAttributes.url"
+        :id="id"
+        :controls="showsDefaultControls"
+        :data-orientation="orientation"
+        :autoplay="autoplays"
+        :poster="normalisedPosterPath"
+        :muted="muted"
+        :width="optimalWidth"
+        :aria-roledescription="$t('video.title')"
+        :aria-label="!showsDefaultControls ? $t('video.custom-controls') : null"
+        :aria-describedby="alt ? altTextId : null"
+        playsinline
+        @loadedmetadata="setOrientation"
+        @playing="$emit('playing')"
+        @pause="$emit('pause')"
+        @ended="$emit('ended')"
+      >
+        <!--
+          Many browsers do not support the `media` attribute for `<source>` tags
+          within a video specifically, so this implementation for dark theme assets
+          is handled with JavaScript media query listeners unlike the `<source>`
+          based implementation being used for image assets.
+        -->
+        <source :src="normalizePath(videoAttributes.url)">
+      </video>
+      <span
+        v-if="alt"
+        :id="altTextId"
+        class="visuallyhidden"
+      >
+        {{ $t('video.description', { alt }) }}
+      </span>
+    </div>
   </ConditionalWrapper>
 </template>
 
@@ -62,7 +75,7 @@ export default {
       type: Array,
       required: true,
     },
-    showsControls: {
+    showsDefaultControls: {
       type: Boolean,
       default: () => false,
     },
@@ -83,6 +96,14 @@ export default {
       type: String,
       required: false,
     },
+    alt: {
+      type: String,
+      required: false,
+    },
+    id: {
+      type: String,
+      required: true,
+    },
   },
   data: () => ({
     appState: AppStore.state,
@@ -93,6 +114,7 @@ export default {
     DeviceFrameComponent: () => DeviceFrame,
     preferredColorScheme: ({ appState }) => appState.preferredColorScheme,
     systemColorScheme: ({ appState }) => appState.systemColorScheme,
+    altTextId: ({ id }) => `${id}-alt`,
     userPrefersDark: ({
       preferredColorScheme,
       systemColorScheme,
diff --git a/src/lang/locales/en-US.json b/src/lang/locales/en-US.json
@@ -3,10 +3,13 @@
   "continue-viewing": "Continue viewing in English",
   "language": "Language",
   "video": {
+    "title": "Video",
     "replay": "Replay",
     "play": "Play",
     "pause": "Pause",
-    "watch": "Watch intro video"
+    "watch": "Watch intro video",
+    "description": "Content description of this video: {alt}",
+    "custom-controls": "Custom controls are available below"
   },
   "tutorials": {
     "title": "Tutorial | Tutorials",
diff --git a/tests/unit/components/Asset.spec.js b/tests/unit/components/Asset.spec.js
@@ -1,7 +1,7 @@
 /**
  * This source file is part of the Swift.org open source project
  *
- * Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ * Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  * Licensed under Apache License v2.0 with Runtime Library Exception
  *
  * See https://swift.org/LICENSE.txt for license information
@@ -17,6 +17,7 @@ import ReplayableVideoAsset from 'docc-render/components/ReplayableVideoAsset.vu
 const video = {
   type: 'video',
   poster: 'image',
+  alt: 'Text describing this video',
   variants: [
     {
       url: 'foo.mp4',
@@ -93,7 +94,7 @@ describe('Asset', () => {
     const videoAsset = wrapper.find(ReplayableVideoAsset);
     expect(videoAsset.props('variants')).toBe(video.variants);
     expect(videoAsset.props('posterVariants')).toBe(image.variants);
-    expect(videoAsset.props('showsControls')).toBe(false);
+    expect(videoAsset.props('showsDefaultControls')).toBe(false);
     expect(videoAsset.props('autoplays')).toBe(false);
 
     // Check that 'ended' events emitted by a `VideoAsset` are re-emitted.
@@ -102,9 +103,12 @@ describe('Asset', () => {
   });
 
   it('renders a `ReplayableVideoAsset` without poster variants', () => {
-    const videoAsset = mountAsset('video', { video }).find(ReplayableVideoAsset);
+    const identifier = 'video';
+    const videoAsset = mountAsset(identifier, { video }).find(ReplayableVideoAsset);
     expect(videoAsset.props('variants')).toBe(video.variants);
     expect(videoAsset.props('posterVariants')).toEqual([]);
+    expect(videoAsset.props('id')).toBe(identifier);
+    expect(videoAsset.props('alt')).toBe(video.alt);
   });
 
   it('passes down `deviceFrame` to `ReplayableVideoAsset`', () => {
@@ -119,29 +123,37 @@ describe('Asset', () => {
   });
 
   it('renders a `VideoAsset` for video with `showsReplayButton=false`', () => {
+    const identifier = 'video';
+
     const wrapper = shallowMount(Asset, {
       propsData: {
-        identifier: 'video',
+        identifier,
         showsReplayButton: false,
         showsVideoControls: true,
       },
       provide: {
         store: {
-          state: { references: { video } },
+          state: { references: { [identifier]: video } },
         },
       },
     });
 
     const videoAsset = wrapper.find(VideoAsset);
-    expect(videoAsset.props('variants')).toBe(video.variants);
-    expect(videoAsset.props('showsControls')).toBe(true);
-    expect(videoAsset.props('muted')).toBe(false);
+    expect(videoAsset.props()).toEqual(expect.objectContaining({
+      variants: video.variants,
+      showsDefaultControls: true,
+      muted: false,
+      id: identifier,
+      alt: video.alt,
+    }));
   });
 
   it('renders a `ReplayableVideoAsset` with deviceFrame', () => {
+    const identifier = 'video';
+
     const wrapper = shallowMount(Asset, {
       propsData: {
-        identifier: 'video',
+        identifier,
         showsReplayButton: true,
         showsVideoControls: true,
         deviceFrame: 'phone',
@@ -159,8 +171,10 @@ describe('Asset', () => {
       deviceFrame: 'phone',
       muted: false,
       posterVariants: [],
-      showsControls: true,
+      showsDefaultControls: true,
       variants: video.variants,
+      id: identifier,
+      alt: video.alt,
     });
   });
 
@@ -181,7 +195,7 @@ describe('Asset', () => {
 
     const videoAsset = wrapper.find(ReplayableVideoAsset);
     expect(videoAsset.props('variants')).toBe(video.variants);
-    expect(videoAsset.props('showsControls')).toBe(true);
+    expect(videoAsset.props('showsDefaultControls')).toBe(true);
     expect(videoAsset.props('muted')).toBe(false);
     expect(videoAsset.props('autoplays')).toBe(true);
   });
@@ -202,7 +216,7 @@ describe('Asset', () => {
     });
 
     const videoAsset = wrapper.find(ReplayableVideoAsset);
-    expect(videoAsset.props('showsControls')).toBe(true);
+    expect(videoAsset.props('showsDefaultControls')).toBe(true);
     expect(videoAsset.props('muted')).toBe(false);
   });
 
diff --git a/tests/unit/components/ReplayableVideoAsset.spec.js b/tests/unit/components/ReplayableVideoAsset.spec.js
@@ -1,7 +1,7 @@
 /**
  * This source file is part of the Swift.org open source project
  *
- * Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ * Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  * Licensed under Apache License v2.0 with Runtime Library Exception
  *
  * See https://swift.org/LICENSE.txt for license information
@@ -22,7 +22,9 @@ const posterVariants = [{ traits: ['dark', '1x'], url: 'https://www.example.com/
 const propsData = {
   variants,
   posterVariants,
-  showsControls: false,
+  showsDefaultControls: false,
+  alt: 'Text describing this video',
+  id: 'video.mp4',
 };
 describe('ReplayableVideoAsset', () => {
   const mountWithProps = props => shallowMount(ReplayableVideoAsset, {
@@ -64,20 +66,34 @@ describe('ReplayableVideoAsset', () => {
     const video = wrapper.find(VideoAsset);
     expect(video.props('variants')).toBe(variants);
     expect(video.props('posterVariants')).toBe(posterVariants);
-    expect(video.props('showsControls')).toBe(false);
+    expect(video.props('showsDefaultControls')).toBe(false);
     expect(video.props('autoplays')).toBe(false);
+    expect(video.props('id')).toBe(propsData.id);
+    expect(video.props('alt')).toBe(propsData.alt);
     expect(wrapper.find('.control-button').exists()).toBe(true);
   });
 
-  it('does not show the `.control-button` if `showsControls` is `true`', () => {
+  it('does not show the `.control-button` if `showsDefaultControls` is `true`', () => {
     const wrapper = mountWithProps({
-      showsControls: true,
+      showsDefaultControls: true,
     });
     const video = wrapper.find(VideoAsset);
-    expect(video.props('showsControls')).toBe(true);
+    expect(video.props('showsDefaultControls')).toBe(true);
     expect(wrapper.find('.control-button').exists()).toBe(false);
   });
 
+  it('adds an aria-controls referring to the video id in `.control-button`', () => {
+    const wrapper = mountWithProps();
+    const controlButton = wrapper.find('.control-button');
+    expect(controlButton.attributes('aria-controls')).toBe(propsData.id);
+  });
+
+  it('does not add a description reference to `.control-button` if alt is not provided', () => {
+    const wrapper = mountWithProps({ alt: null });
+    const controlButton = wrapper.find('.control-button');
+    expect(controlButton.attributes()).not.toHaveProperty('aria-describedby');
+  });
+
   it('changes the control button text, while the video is changing states', async () => {
     const wrapper = mountWithProps();
 
diff --git a/tests/unit/components/VideoAsset.spec.js b/tests/unit/components/VideoAsset.spec.js
