From 109c1e3224e9e9209e6d82137776a0362cf8a9cd Mon Sep 17 00:00:00 2001
From: Robert Reinhard <robert.reinhard@goodness.inc>
Date: Wed, 14 Aug 2024 08:03:11 -0700
Subject: [PATCH] Updating docs

---
 packages/contentful/README.md                 | 10 ++++++++--
 packages/next/README.md                       | 12 ++++++++---
 packages/react/README.md                      | 20 ++++++++++++-------
 .../react/src/LazyVideo/LazyVideoClient.tsx   | 13 +++++++-----
 packages/react/src/ReactVisual.tsx            |  1 +
 packages/sanity-next/README.md                |  9 ++++++++-
 6 files changed, 47 insertions(+), 18 deletions(-)

diff --git a/packages/contentful/README.md b/packages/contentful/README.md
index 9e9529d..9ce04fb 100644
--- a/packages/contentful/README.md
+++ b/packages/contentful/README.md
@@ -4,6 +4,7 @@ Renders Contentful images and videos into a container.  Features:
 
 - Automatically defines a loader functions for generating srcsets
 - Supports responsive image and video assets
+- Adds play/pause toggle for videos for [ADA compliance](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html)
 
 ## Install
 
@@ -112,13 +113,18 @@ For more examples, read [the Cypress component tests](./cypress/component).
 | Prop | Type | Description
 | -- | -- | --
 | `paused` | `boolean` | Disables autoplay of videos. This prop is reactive, unlike the `paused` property of the html `<video>` tag.  You can set it to `true` to pause a playing video or set it to `false` to play a paused video.
-
+| `onPause` | `Function` | Invoked whenever the video fires a [pause event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause_event).
+| `onPlay` | `Function` | Invoked whenever the video fires a [play event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play_event).
+| `playIcon` | `ComponentType` | Replace the play icon used with accessibility controls.
+| `pauseIcon` | `ComponentType` | Replace the pause icon used with accessibility controls.
 
 ### Accessibility
 
 | Prop | Type | Description
 | -- | -- | --
-| `alt` | `string` | Sets the  alt attribute or aria-label value, depending on asset type.
+| `alt` | `string` | Sets the alt attribute or aria-label value, depending on asset type.
+| `hideAccessibilityControls` | `boolean` | Removes the play/pause toggle on videos.
+| `accessibilityControlsPosition` | [`PositionOption`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L61-L70) | Controls the position of the accessibility controls.  Defaults to `bottom left`.
 
 ### Theming
 
diff --git a/packages/next/README.md b/packages/next/README.md
index 76f8313..8ab6c27 100644
--- a/packages/next/README.md
+++ b/packages/next/README.md
@@ -5,6 +5,7 @@ Renders images and videos into a container.  Features:
 - Uses `next/image` to render images
 - Easily render assets using aspect ratios
 - Videos are lazyloaded (unless `priority` flag is set)
+- Adds play/pause toggle for videos for [ADA compliance](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html)
 
 ## Install
 
@@ -60,20 +61,25 @@ For more examples, read [the Cypress component tests](./cypress/component).
 | -- | -- | --
 | `priority` | `boolean` | Sets [`next/image`'s `priority`](https://nextjs.org/docs/pages/api-reference/components/image#priority) and videos to not lazy load.
 | `sizes` | `string` | Sets [`next/image`'s `sizes`](https://nextjs.org/docs/pages/api-reference/components/image#sizes) prop.
-| `imageLoader` | `Function` | This is passed through [to `next/image`'s `loader` prop](https://nextjs.org/docs/app/api-reference/components/image#loader).
+| `imageLoader` | [`ImageLoader`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L38-L44) | This is passed through [to `next/image`'s `loader` prop](https://nextjs.org/docs/app/api-reference/components/image#loader).
 
 ### Video
 
 | Prop | Type | Description
 | -- | -- | --
 | `paused` | `boolean` | Disables autoplay of videos. This prop is reactive, unlike the `paused` property of the html `<video>` tag.  You can set it to `true` to pause a playing video or set it to `false` to play a paused video.
-
+| `onPause` | `Function` | Invoked whenever the video fires a [pause event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause_event).
+| `onPlay` | `Function` | Invoked whenever the video fires a [play event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play_event).
+| `playIcon` | `ComponentType` | Replace the play icon used with accessibility controls.
+| `pauseIcon` | `ComponentType` | Replace the pause icon used with accessibility controls.
 
 ### Accessibility
 
 | Prop | Type | Description
 | -- | -- | --
-| `alt` | `string` | Sets the  alt attribute or aria-label value, depending on asset type.
+| `alt` | `string` | Sets the alt attribute or aria-label value, depending on asset type.
+| `hideAccessibilityControls` | `boolean` | Removes the play/pause toggle on videos.
+| `accessibilityControlsPosition` | [`PositionOption`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L61-L70) | Controls the position of the accessibility controls.  Defaults to `bottom left`.
 
 ### Theming
 
diff --git a/packages/react/README.md b/packages/react/README.md
index 0e7186d..aa2bd9e 100644
--- a/packages/react/README.md
+++ b/packages/react/README.md
@@ -7,6 +7,7 @@ Renders images and videos into a container.  Features:
 - Creates `<source>` tags for different MIME types and media queries
 - Easily render assets using aspect ratios
 - Videos are lazyloaded (unless `priority` flag is set)
+- Adds play/pause toggle for videos for [ADA compliance](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html)
 
 ## Install
 
@@ -179,7 +180,7 @@ For more examples, read [the Cypress component tests](./cypress/component).
 | Prop | Type | Description
 | -- | -- | --
 | `expand` | `boolean` | Make the Visual fill it's container via CSS using absolute positioning.
-| `aspect` | `number`, `function` | Force the Visual to a specific aspect ratio.
+| `aspect` | `number`, [`AspectCalculator`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L52-L57) | Force the Visual to a specific aspect ratio.
 | `width` | `number`, `string` | A CSS dimension value or a px number.
 | `height` | `number`, `string` | A CSS dimension value or a px number.
 | `fit` | `string` | An [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) value that is applied to the assets.  Defaults to `cover`.
@@ -191,23 +192,28 @@ For more examples, read [the Cypress component tests](./cypress/component).
 | -- | -- | --
 | `priority` | `boolean` | Disables [`<img loading="lazy>"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading) and prevents videos from lazy loading based on IntersectionObserver.
 | `sizes` | `string` | Sets the `<img sizes>` attribute.
-| `sourceTypes` | `string[]` | Specify image MIME types that will be passed to the `imageLoader` and used to create additional `<source>` tags.  Use this to create `webp` or `avif` sources with a CDN like Contentful.
-| `sourceMedia` | `string[]` | Specify media queries that will be passed to the `imageLoader` and used to create additional `<source>` tags.
-| `imageLoader` | `Function` | Uses syntax that is similar [to `next/image`'s `loader` prop](https://nextjs.org/docs/app/api-reference/components/image#loader).  A srcset is built with a hardcoded list of widths.
-| `videoLoader` | `Function` | Like `imageLoader` but is only passed the `src` and `media` properties.
+| `sourceTypes` | [`SourceType[]`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L72-L78) | Specify image MIME types that will be passed to the `imageLoader` and used to create additional `<source>` tags.  Use this to create `webp` or `avif` sources with a CDN like Contentful.
+| `sourceMedia` | [`SourceType[]`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L80-L83) | Specify media queries that will be passed to the `imageLoader` and used to create additional `<source>` tags.
+| `imageLoader` | [`ImageLoader`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L38-L44) | Uses syntax that is similar [to `next/image`'s `loader` prop](https://nextjs.org/docs/app/api-reference/components/image#loader).  A srcset is built with a hardcoded list of widths.
+| `videoLoader` | [`VideoLoader`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L46-L50) | Like `imageLoader` but is only passed the `src` and `media` properties.
 
 ### Video
 
 | Prop | Type | Description
 | -- | -- | --
 | `paused` | `boolean` | Disables autoplay of videos. This prop is reactive, unlike the `paused` property of the html `<video>` tag.  You can set it to `true` to pause a playing video or set it to `false` to play a paused video.
-
+| `onPause` | `Function` | Invoked whenever the video fires a [pause event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause_event).
+| `onPlay` | `Function` | Invoked whenever the video fires a [play event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play_event).
+| `playIcon` | `ComponentType` | Replace the play icon used with accessibility controls.
+| `pauseIcon` | `ComponentType` | Replace the pause icon used with accessibility controls.
 
 ### Accessibility
 
 | Prop | Type | Description
 | -- | -- | --
-| `alt` | `string` | Sets the  alt attribute or aria-label value, depending on asset type.
+| `alt` | `string` | Sets the alt attribute or aria-label value, depending on asset type.
+| `hideAccessibilityControls` | `boolean` | Removes the play/pause toggle on videos.
+| `accessibilityControlsPosition` | [`PositionOption`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L61-L70) | Controls the position of the accessibility controls.  Defaults to `bottom left`.
 
 ### Theming
 
diff --git a/packages/react/src/LazyVideo/LazyVideoClient.tsx b/packages/react/src/LazyVideo/LazyVideoClient.tsx
index 855664f..b651221 100644
--- a/packages/react/src/LazyVideo/LazyVideoClient.tsx
+++ b/packages/react/src/LazyVideo/LazyVideoClient.tsx
@@ -40,7 +40,8 @@ export default function LazyVideoClient({
   accessibilityControlsPosition,
 }: LazyVideoClientProps): ReactElement {
 
-  // Track the actual video playback state
+  // Track the actual video playback state. Start in a paused state because
+  // even with an autoplay video, it won't actually have started playing yet.
   const [isVideoPaused, setVideoPaused] = useState(true)
 
   // Make a ref to the video so it can be controlled
@@ -82,12 +83,14 @@ export default function LazyVideoClient({
     videoRef.current?.pause();
   };
 
-  // Respond to paused prop and call methods that control the video playback
+  // Trigger pause and play in response to the `paused` prop changing. This is
+  // used to control the video from outside the component.
   useEffect(() => {
     paused ? pause() : play();
   }, [paused]);
 
-  // Update internal play/pause state
+  // Watch for the video element's state changes and sync with the component's
+  // internal paused state.
   useEffect(() => {
     const videoElement = videoRef.current;
 
@@ -130,8 +133,8 @@ export default function LazyVideoClient({
         // Whether to autoplay
         autoPlay={!paused}
         // Load a transparent gif as a poster if an `image` was specified so
-        // the image is used as poster rather than the first frame of video. This
-        // lets us all use responsive poster images (via `next/image`).
+        // the image is used as poster rather than the first frame of video.
+        // This lets us all use responsive poster images (via `next/image`).
         poster={noPoster ? transparentGif : undefined}
         // Straightforward props
         ref={setRefs}
diff --git a/packages/react/src/ReactVisual.tsx b/packages/react/src/ReactVisual.tsx
index 953dca5..c6e6ddc 100644
--- a/packages/react/src/ReactVisual.tsx
+++ b/packages/react/src/ReactVisual.tsx
@@ -58,6 +58,7 @@ export default function ReactVisual(
         dataAttributes: collectDataAttributes(props),
       }}
     >
+
       {/* Render image */}
       {image && (
         <PictureImage
diff --git a/packages/sanity-next/README.md b/packages/sanity-next/README.md
index ba30b7c..919d1d1 100644
--- a/packages/sanity-next/README.md
+++ b/packages/sanity-next/README.md
@@ -6,6 +6,7 @@ Renders Sanity images and videos into a container using Next.js.  Features:
 - Generates responsive images using Sanity CDN
 - Automatically sets aspect ratio, placeholder, and hotspot
 - Videos are lazyloaded (unless `priority` flag is set)
+- Adds play/pause toggle for videos for [ADA compliance](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html)
 
 ## Install
 
@@ -100,12 +101,18 @@ For more examples, read [the Cypress component tests](./cypress/component).
 | Prop | Type | Description
 | -- | -- | --
 | `paused` | `boolean` | Disables autoplay of videos. This prop is reactive, unlike the `paused` property of the html `<video>` tag.  You can set it to `true` to pause a playing video or set it to `false` to play a paused video.
+| `onPause` | `Function` | Invoked whenever the video fires a [pause event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause_event).
+| `onPlay` | `Function` | Invoked whenever the video fires a [play event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play_event).
+| `playIcon` | `ComponentType` | Replace the play icon used with accessibility controls.
+| `pauseIcon` | `ComponentType` | Replace the pause icon used with accessibility controls.
 
 ### Accessibility
 
 | Prop | Type | Description
 | -- | -- | --
-| `alt` | `string` | Sets the  alt attribute or aria-label value, depending on asset type.
+| `alt` | `string` | Sets the alt attribute or aria-label value, depending on asset type.
+| `hideAccessibilityControls` | `boolean` | Removes the play/pause toggle on videos.
+| `accessibilityControlsPosition` | [`PositionOption`](https://github.com/BKWLD/react-visual/blob/eaf2d150efa1187033ba732a350a4db20f260435/packages/react/src/types/reactVisualTypes.ts#L61-L70) | Controls the position of the accessibility controls.  Defaults to `bottom left`.
 
 ### Theming