cleaned up video, controls props

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} />

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,

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>

src/components/Video/demo/docs/controls.md

@@ -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}"
-/>
-```

src/components/Video/demo/docs/playAndLoop.md

@@ -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}"
-/>
-```

src/components/Video/demo/docs/withSound.md

@@ -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}"
-/>
-```