From 0dfa8c59591b3879057d68a2525256e52a623282 Mon Sep 17 00:00:00 2001
From: MinamiFunakoshiTR <minami.funakoshi@thomsonreuters.com>
Date: Wed, 26 Mar 2025 15:21:25 -0700
Subject: [PATCH] cleaned up video, controls props

---
 src/components/Video/Video.mdx                |  76 +++++++++++++++++-
 src/components/Video/Video.stories.svelte     |   9 +--
 src/components/Video/Video.svelte             |   5 +-
 src/components/Video/demo/docs/controls.md    |  38 ---------
 src/components/Video/demo/docs/playAndLoop.md |  28 -------
 src/components/Video/demo/docs/withSound.md   |  36 ---------
 .../Video/demo/{videos => }/silent-video.mp4  | Bin
 .../Video/demo/{videos => }/sound-video.mp4   | Bin
 8 files changed, 82 insertions(+), 110 deletions(-)
 delete mode 100644 src/components/Video/demo/docs/controls.md
 delete mode 100644 src/components/Video/demo/docs/playAndLoop.md
 delete mode 100644 src/components/Video/demo/docs/withSound.md
 rename src/components/Video/demo/{videos => }/silent-video.mp4 (100%)
 rename src/components/Video/demo/{videos => }/sound-video.mp4 (100%)

diff --git a/src/components/Video/Video.mdx b/src/components/Video/Video.mdx
index 31d16056..f32a770c 100644
--- a/src/components/Video/Video.mdx
+++ b/src/components/Video/Video.mdx
@@ -6,7 +6,7 @@ import * as VideoStories from './Video.stories.svelte';
 
 # Video
 
-The `Video` component adds video to your page. Can play on load or when the video comes into view and has play/pause controls. Supports videos with or without audio.
+The `Video` component adds a video with various controls to your page. The video can play on load or when the video comes into view. The component supports videos with or without audio, and has options to add a pause/play button or to allow the user to click on the video to pause and play it instead.
 
 ```svelte
 <script>
@@ -23,3 +23,77 @@ The `Video` component adds video to your page. Can play on load or when the vide
 ```
 
 <Canvas of={VideoStories.Demo} />
+
+## Playing and looping
+
+`playVideoWhenInView`, `playVideoThreshold`
+
+- By default, the video will **start playing when 50% of the video element's height is visible on the page**.
+  To control the threshold of visibility at which the video starts playing, add the prop `playVideoThreshold` and set it to a value between 0 and 1,
+  where 0 means that the video will start playing as soon as its top enters the viewport, while 1 means it will start when the whole video is in the viewport.
+
+- If you don't want the video to play when you scroll to it, but **on page load**, add the prop `playVideoWhenInView={false}`. The default of the prop is `true`,
+  which corresponds to the behaviour described above.
+
+`loopVideo`
+
+- By default, the video will **loop**. If you don't want that, add the prop `loopVideo={false}`.
+
+Here is an example of what the same video would look like with a visibility threshold of 0.9 and not looping. Scroll down slowly to observe the behaviour.
+
+```svelte
+<script>
+  import { Video } from '@reuters-graphics/graphics-components';
+</script>
+
+<Video
+  ariaDescription={'Compulsory description of your video for screen readers.'}
+  src={'path-to-video-or-external-url'}
+  width={'normal'}
+  loopVideo={false}
+  playVideoThreshold={0.9}
+/>
+```
+
+<Canvas of={VideoStories.PlayingAndLooping} />
+
+## Audio controls
+
+If you've ever had to put sound on a page in recent years,
+you'll know that auto-playing sound is not allowed by browsers. The user will need to interact with the page first, and it will depend on your
+particular use case how and when you'd like this to happen. This component provides two options to deal with this.
+If you have a video with sound, make sure to add the prop `muteVideo={false}`.
+
+Then you can either:
+
+- `allowSoundToAutoplay={false}` (default) : Don't allow the video to autoplay under any circumstances other than when the user clicks the 'play' on the video. Note that this
+  works whether or not you have the controls visible, i.e. with `showControls` being `true` or `false`, as long as you allow
+  play/pause behaviour with `possibleToPlayPause={true}` (default).
+
+- `allowSoundToAutoplay={true}` : Allow the video to autoplay when it comes into view as long as the user has interacted with the page preivously, i.e. they have clicked/tapped
+  anywhere on the page.
+
+You should keep `playVideoWhenInView={true}` (default). There is no option to autoplay video with sound when the user clicks on the page
+elsewhere if the video is not in view. In other words, you can't start playing sound for a video which is not in view with this component.
+This is probably not a behaviour you'd want anyway.
+
+The example below allows for autoplay if the user has interacted with the page before the video comes into view. To see this, reload the page
+and go to the top. Click anywhere on the page before scrolling down to the video and you should see it autoplay when it comes into view.
+
+```svelte
+<script>
+  import { Video } from '@reuters-graphics/graphics-components';
+</script>
+
+<Video
+  ariaDescription={'Compulsory description of your video for screen readers.'}
+  src={'path-to-video-or-external-url'}
+  width={'normal'}
+  controlsOpacity={1}
+  loopVideo={false}
+  muteVideo={false}
+  allowSoundToAutoplay={true}
+/>
+```
+
+<Canvas of={VideoStories.Audio} />
diff --git a/src/components/Video/Video.stories.svelte b/src/components/Video/Video.stories.svelte
index 5e102cb8..43fc985a 100644
--- a/src/components/Video/Video.stories.svelte
+++ b/src/components/Video/Video.stories.svelte
@@ -9,8 +9,8 @@
 </script>
 
 <script>
-  import SilentVideo from './demo/videos/silent-video.mp4';
-  import SoundVideo from './demo/videos/sound-video.mp4';
+  import SilentVideo from './demo/silent-video.mp4';
+  import SoundVideo from './demo/sound-video.mp4';
 </script>
 
 <Story
@@ -51,13 +51,12 @@
     controlsPosition: 'bottom right',
     separateReplayIcon: true,
     loopVideo: false,
-    hoverToSeeControls: true,
   }}
 />
 
 <Story
-  name="Videos with sound"
-  exportName="WithSound"
+  name="Audio controls"
+  exportName="Audio"
   args={{
     ariaDescription: 'Compulsory description of your video for screen readers.',
     src: SoundVideo,
diff --git a/src/components/Video/Video.svelte b/src/components/Video/Video.svelte
index 9759eea0..e20420e3 100644
--- a/src/components/Video/Video.svelte
+++ b/src/components/Video/Video.svelte
@@ -81,7 +81,7 @@
     playVideoWhenInView = true,
     playVideoThreshold = 0.5,
     possibleToPlayPause = true,
-    showControls = false, // true
+    showControls = true,
     separateReplayIcon = false,
     controlsColour = '#333',
     controlsOpacity = 0.5,
@@ -162,7 +162,7 @@
       // clickedOnPauseBtn = paused === true; // so video doesn't autoplay when coming into view again if paused previously
     }}
     style="
-    opacity: {controlsOpacity};
+    opacity: {interactiveControlsOpacity};
     top: {controlsPosition === 'top left' || controlsPosition === 'top right' ?
       `${10}px`
     : controlsPosition === 'center' ?
@@ -338,5 +338,6 @@
     cursor: pointer;
     background-color: transparent;
     border: none;
+    transition: opacity 0.2s;
   }
 </style>
diff --git a/src/components/Video/demo/docs/controls.md b/src/components/Video/demo/docs/controls.md
deleted file mode 100644
index 87e8f916..00000000
--- a/src/components/Video/demo/docs/controls.md
+++ /dev/null
@@ -1,38 +0,0 @@
-`showControls`
-
-- By default, the video has a play/pause button, which corresponds to
-  `showControls={true}`. If you don't want these, just set `showControls={false}`.
-  When you do that, the icons themselves will disappear but the functionality of playing and pausing remains and can be done by clicking on the video itself.
-  If you don't want to enable any play/pause functionality, add `possibleToPlayPause={false}`.
-- If you want to show the controls only when the video is hovered, set `hoverToSeeControls={true}`.
-
-`controlsColour`, `controlsOpacity`, `controlsPosition`, `separateReplayIcon`
-
-If you do want to leave the controls, you have a couple of options to style them:
-
-- Set `controlsColour` to a colour of your choosing.
-- Set `controlsOpacity` to a value between `0` and `1` to control the opacity. The default is `0.5`.
-- Change the placement of the controls to one of: `top right`, `top left`, `bottom right`, `bottom left`, `center` by setting `controlsPosition`.
-- Change the play button to a replay button at the end of the video with the option `separateReplayIcon={true}`.
-
-Here is an example with bottom right corner white opaque controls, with a replay button, where you have to hover on the video to see the controls.
-
-```svelte
-<script>
-  import { Video } from '@reuters-graphics/graphics-components';
-</script>
-
-<Video
-  ariaDescription="{'Compulsory description of your video for screen readers.'}"
-  src="{'path-to-video-or-external-url'}"
-  width="{'normal'}"
-  caption="{'Optional caption for your video.'}"
-  playVideoThreshold="{0.1}"
-  controlsColour="{'white'}"
-  controlsOpacity="{1}"
-  controlsPosition="{'bottom right'}"
-  separateReplayIcon="{true}"
-  loopVideo="{false}"
-  hoverToSeeControls="{true}"
-/>
-```
diff --git a/src/components/Video/demo/docs/playAndLoop.md b/src/components/Video/demo/docs/playAndLoop.md
deleted file mode 100644
index 03427fd0..00000000
--- a/src/components/Video/demo/docs/playAndLoop.md
+++ /dev/null
@@ -1,28 +0,0 @@
-`playVideoWhenInView`, `playVideoThreshold`
-
-- By default, the video will **start playing when 50% of the video element's height is visible on the page**.
-  To control the threshold of visibility at which the video starts playing, add the prop `playVideoThreshold` and set it to a value between 0 and 1,
-  where 0 means that the video will start playing as soon as its top enters the viewport, while 1 means it will start when the whole video is in the viewport.
-
-- If you don't want the video to play when you scroll to it, but **on page load**, add the prop `playVideoWhenInView={false}`. The default of the prop is `true`,
-  which corresponds to the behaviour described above.
-
-`loopVideo`
-
-- By default, the video will **loop**. If you don't want that, add the prop `loopVideo={false}`.
-
-Here is an example of what the same video would look like with a visibility threshold of 0.9 and not looping. Scroll down slowly to observe the behaviour.
-
-```svelte
-<script>
-  import { Video } from '@reuters-graphics/graphics-components';
-</script>
-
-<Video
-  ariaDescription="{'Compulsory description of your video for screen readers.'}"
-  src="{'path-to-video-or-external-url'}"
-  width="{'normal'}"
-  loopVideo="{false}"
-  playVideoThreshold="{0.9}"
-/>
-```
diff --git a/src/components/Video/demo/docs/withSound.md b/src/components/Video/demo/docs/withSound.md
deleted file mode 100644
index 50620899..00000000
--- a/src/components/Video/demo/docs/withSound.md
+++ /dev/null
@@ -1,36 +0,0 @@
-If you've ever had to put sound on a page in recent years,
-you'll know that auto-playing sound is not allowed by browsers. The user will need to interact with the page first, and it will depend on your
-particular use case how and when you'd like this to happen. This component provides two options to deal with this.
-If you have a video with sound, make sure to add the prop `muteVideo={false}`.
-
-Then you can either:
-
-- `allowSoundToAutoplay={false}` (default) : Don't allow the video to autoplay under any circumstances other than when the user clicks the 'play' on the video. Note that this
-  works whether or not you have the controls visible, i.e. with `showControls` being `true` or `false`, as long as you allow
-  play/pause behaviour with `possibleToPlayPause={true}` (default).
-
-- `allowSoundToAutoplay={true}` : Allow the video to autoplay when it comes into view as long as the user has interacted with the page preivously, i.e. they have clicked/tapped
-  anywhere on the page.
-
-You should keep `playVideoWhenInView={true}` (default). There is no option to autoplay video with sound when the user clicks on the page
-elsewhere if the video is not in view. In other words, you can't start playing sound for a video which is not in view with this component.
-This is probably not a behaviour you'd want anyway.
-
-The example below allows for autoplay if the user has interacted with the page before the video comes into view. To see this, reload the page
-and go to the top. Click anywhere on the page before scrolling down to the video and you should see it autoplay when it comes into view.
-
-```svelte
-<script>
-  import { Video } from '@reuters-graphics/graphics-components';
-</script>
-
-<Video
-  ariaDescription="{'Compulsory description of your video for screen readers.'}"
-  src="{'path-to-video-or-external-url'}"
-  width="{'normal'}"
-  controlsOpacity="{1}"
-  loopVideo="{false}"
-  muteVideo="{false}"
-  allowSoundToAutoplay="{true}"
-/>
-```
diff --git a/src/components/Video/demo/videos/silent-video.mp4 b/src/components/Video/demo/silent-video.mp4
similarity index 100%
rename from src/components/Video/demo/videos/silent-video.mp4
rename to src/components/Video/demo/silent-video.mp4
diff --git a/src/components/Video/demo/videos/sound-video.mp4 b/src/components/Video/demo/sound-video.mp4
similarity index 100%
rename from src/components/Video/demo/videos/sound-video.mp4
rename to src/components/Video/demo/sound-video.mp4