feat(Media): support ref for video element (#1297)

Author: mournfulCoroner

.storybook/stories/documentation/Types.mdx

@@ -57,6 +57,7 @@ import { Meta } from '@storybook/blocks';
 - `ariaLabel?: string` — ARIA label for accessibility
 - `contain?: boolean` — Whether video should be contained within bounds
 - `onVideoEnd?: () => void` — Callback when video ends
+- `ref?: React.Ref<HTMLVideoElement | null>` — Ref for video element
 
 ---
 

memory-bank/usage/media.md

@@ -64,7 +64,7 @@ graph TD
     - `ImageObjectProps`: `{src: string, alt?: string, disableCompress?: boolean, hide?: boolean | Partial<Record<'desktop' | 'mobile' | 'tablet', boolean>>, fetchPriority?: 'high' | 'low' | 'auto', loading?: 'eager' | 'lazy', 'aria-describedby'?: string}`
     - `ImageDeviceProps`: `{desktop: string, mobile: string, tablet?: string, alt?: string, disableCompress?: boolean, hide?: boolean | Partial<Record<'desktop' | 'mobile' | 'tablet', boolean>>, fetchPriority?: 'high' | 'low' | 'auto', loading?: 'eager' | 'lazy', 'aria-describedby'?: string}`
   - `video`: MediaVideoProps - video configuration
-    - `{src: string[], type?: 'default' | 'player', loop?: boolean | {start: number, end?: number}, muted?: boolean, autoplay?: boolean, elapsedTime?: number, playButton?: PlayButtonProps, controls?: 'default' | 'custom', customControlsOptions?: CustomControlsOptions, ariaLabel?: string, contain?: boolean, onVideoEnd?: () => void}`
+    - `{src: string[], type?: 'default' | 'player', loop?: boolean | {start: number, end?: number}, muted?: boolean, autoplay?: boolean, elapsedTime?: number, playButton?: PlayButtonProps, controls?: 'default' | 'custom', customControlsOptions?: CustomControlsOptions, ariaLabel?: string, contain?: boolean, onVideoEnd?: () => void, ref?: React.Ref<HTMLVideoElement | null>}`
     - `PlayButtonProps`: `{type?: 'default' | 'text', theme?: 'blue' | 'grey', text?: string, className?: string}`
     - `CustomControlsOptions`: `{type?: 'with-mute-button' | 'with-play-pause-button', muteButtonShown?: boolean, positioning?: 'left' | 'right' | 'center'}`
   - `youtube`: string - YouTube video ID
@@ -593,6 +593,39 @@ The Media component integrates seamlessly with the page-constructor theme system
 />
 ```
 
+### Video with Ref for Programmatic Control
+
+```tsx
+const videoRef = React.useRef<HTMLVideoElement>(null);
+
+const handlePlay = () => {
+  if (videoRef.current) {
+    videoRef.current.play();
+  }
+};
+
+const handlePause = () => {
+  if (videoRef.current) {
+    videoRef.current.pause();
+  }
+};
+
+const handleSeek = () => {
+  if (videoRef.current) {
+    videoRef.current.currentTime = 10; // Seek to 10 seconds
+  }
+};
+
+<Media
+  video={{
+    src: ['/path/to/video.mp4'],
+    controls: MediaVideoControlsType.Default,
+    ref: videoRef,
+  }}
+  height={400}
+/>;
+```
+
 ### Background Media with Parallax
 
 ```tsx

src/components/Media/Video/Video.tsx

@@ -46,6 +46,8 @@ const Video = (props: VideoAllProps) => {
 
     const ref = React.useRef<HTMLVideoElement>(null);
 
+    React.useImperativeHandle(video.ref, () => ref.current, []);
+
     React.useEffect(() => {
         if (ref && ref.current) {
             const {loop} = video;

src/components/ReactPlayer/ReactPlayer.tsx

@@ -41,7 +41,7 @@ const ReactPlayer =
         : _ReactPlayer;
 
 export interface ReactPlayerBlockProps
-    extends Omit<MediaVideoProps, 'loop' | 'src'>,
+    extends Omit<MediaVideoProps, 'loop' | 'src' | 'ref'>,
         ClassNameProps {
     src: string | string[];
     previewImgUrl?: string;

src/models/constructor-items/common.ts

@@ -190,6 +190,7 @@ export interface MediaVideoProps extends AnalyticsEventsBase {
     ariaLabel?: string;
     contain?: boolean;
     onVideoEnd?: () => void;
+    ref?: React.Ref<HTMLVideoElement | null>;
 }
 
 // links