docs: add comprehensive TSDoc for YoutubePlayer props and events

.changeset/bumpy-frogs-appear.md

@@ -0,0 +1,8 @@
+---
+"react-native-youtube-bridge": patch
+"@react-native-youtube-bridge/core": patch
+---
+
+docs: add comprehensive TSDoc for YoutubePlayer props and events
+- Improve documentation for player events (`onReady`, `onStateChange`, etc.)
+- Add detailed descriptions for player parameters and configuration

packages/core/src/types/index.ts

@@ -50,51 +50,97 @@ export type PlayerInfo = {
   volume?: number;
 };
 
+/**
+ * @description This parameter specifies the player events.
+ * @see https://developers.google.com/youtube/iframe_api_reference#Events
+ */
 export type PlayerEvents = {
   /**
    * @description Callback function called when the player is ready.
+   * @param {PlayerInfo} playerInfo - The player information.
    */
   onReady?: (playerInfo: PlayerInfo) => void;
+  /**
+   * @description This event fires whenever the player's state changes. The data property of the event object that the API passes to your event listener function will specify an integer that corresponds to the new player state.
+   * @param {PlayerState} state - The new player state.
+   */
   onStateChange?: (state: PlayerState) => void;
+  /**
+   * @description This event fires if an error occurs in the player. The API will pass an event object to the event listener function.
+   * @param {YouTubeError} error - The error object.
+   */
   onError?: (error: YouTubeError) => void;
   /**
    * @description Callback function called at the specified `progressInterval`
    * or when `seekTo` is invoked. Only triggered when `progressInterval` is
    * provided as a positive number.
+   * @param {ProgressData} progress - The progress data.
    */
   onProgress?: (progress: ProgressData) => void;
+  /**
+   * @description This event fires whenever the video playback rate changes. For example, if you call the `setPlaybackRate(suggestedRate)` function, this event will fire if the playback rate actually changes.
+   * @param {number} playbackRate - The new playback rate.
+   */
   onPlaybackRateChange?: (playbackRate: number) => void;
+  /**
+   * @description This event fires whenever the video playback quality changes. It might signal a change in the viewer's playback environment.
+   * @param {PlaybackQuality} quality - The new playback quality.
+   */
   onPlaybackQualityChange?: (quality: PlaybackQuality) => void;
+  /**
+   * @description This event fires any time the browser blocks autoplay or scripted video playback features, collectively referred to as "autoplay".
+   */
   onAutoplayBlocked?: () => void;
 };
 
+/**
+ * @description This parameter specifies the player parameters.
+ * @see https://developers.google.com/youtube/player_parameters
+ */
 export type YoutubePlayerVars = {
   /**
-   * @description If the `muted` is not set to true when activating the `autoplay`,
-   * it may not work properly depending on browser policy. (https://developer.chrome.com/blog/autoplay)
+   * @description This parameter specifies whether the initial video will automatically start to play when the player loads.
+   * - If the `muted` is not set to true when activating the `autoplay`,
+   * - it may not work properly depending on browser policy. (https://developer.chrome.com/blog/autoplay)
    */
   autoplay?: boolean;
   /**
-   * @description If the `controls` is set to true, the player will display the controls.
+   * @description This parameter indicates whether the video player controls are displayed.
+   * - `controls: false` - Player controls do not display in the player.
+   * - `controls: true` (default) - Player controls display in the player.
+   * @default true
    */
   controls?: boolean;
   /**
-   * @description If the `loop` is set to true, the player will loop the video.
+   * @description In the case of a single video player, a setting of 1 causes the player to play the initial video again and again. In the case of a playlist player (or custom player), the player plays the entire playlist and then starts again at the first video.
+   * @default false
    */
   loop?: boolean;
   /**
    * @description If the `muted` is set to true, the player will be muted.
    */
   muted?: boolean;
+  /**
+   * @description This parameter causes the player to begin playing the video at the given number of seconds from the start of the video. The parameter value is a positive integer. Note that similar to the seekTo function, the player will look for the closest keyframe to the time you specify. This means that sometimes the play head may seek to just before the requested time, usually no more than around two seconds.
+   */
   startTime?: number;
+  /**
+   * @description This parameter specifies the time, measured in seconds from the start of the video, when the player should stop playing the video. The parameter value is a positive integer.
+   */
   endTime?: number;
+  /**
+   * @description This parameter controls whether videos play inline or fullscreen on iOS. Valid values are:
+   * - `playsinline: false` - Results in fullscreen playback. This is currently the default value, though the default is subject to change.
+   * - `playsinline: true` - Results in inline playback for mobile browsers and for WebViews created with the `allowsInlineMediaPlayback` property set to `YES`.
+   */
   playsinline?: boolean;
   /**
-   * @description If the `rel` is set to true, the related videos will be displayed.
+   * @description Prior to the change, this parameter indicates whether the player should show related videos when playback of the initial video ends.
+   * After the change, you will not be able to disable related videos. Instead, if the `rel` parameter is set to `false, related videos will come from the same channel as the video that was just played.
    */
   rel?: boolean;
   /**
-   * @description The origin of the player.
+   * @description This parameter provides an extra security measure for the IFrame API and is only supported for IFrame embeds.
    */
   origin?: string;
 };
@@ -105,6 +151,10 @@ export type YoutubePlayerConfig = {
   playerVars?: YoutubePlayerVars;
 } & PlayerEvents;
 
+/**
+ * @description The player controls.
+ * @see https://developers.google.com/youtube/iframe_api_reference#Functions
+ */
 export type PlayerControls = {
   // Playback controls
   play: () => void;

packages/react-native-youtube-bridge/src/types/youtube.ts

@@ -1,13 +1,28 @@
 import type { PlayerEvents, YouTubeSource, YoutubePlayerVars } from '@react-native-youtube-bridge/core';
 import type { CSSProperties } from 'react';
-import type { DimensionValue, StyleProp, ViewStyle } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
 import type { WebViewProps } from 'react-native-webview';
 import type { WebViewSourceUri } from 'react-native-webview/lib/WebViewTypes';
 
 export type YoutubePlayerProps = {
+  /**
+   * @description The source of the video to play.
+   * @example
+   * ```ts
+   * source: 'https://www.youtube.com/watch?v=AbZH7XWDW_k'
+   * source: { videoId: 'AbZH7XWDW_k' }
+   * source: { url: 'https://www.youtube.com/watch?v=AbZH7XWDW_k' }
+   * ```
+   */
   source: YouTubeSource;
-  width?: DimensionValue;
-  height?: DimensionValue;
+  /**
+   * @description The width of the player.
+   */
+  width?: number | 'auto' | `${number}%`;
+  /**
+   * @description The height of the player.
+   */
+  height?: number | 'auto' | `${number}%`;
   /**
    * @description The interval (in milliseconds) at which `onProgress` callback is called.
    */
@@ -29,16 +44,19 @@ export type YoutubePlayerProps = {
   webViewUrl?: string;
   style?: StyleProp<ViewStyle>;
   /**
+   * @description The style of the WebView.
    * @platform ios, android
    */
   webViewStyle?: StyleProp<ViewStyle>;
   /**
+   * @description The props of the WebView.
    * @platform ios, android
    */
   webViewProps?: Omit<WebViewProps, 'ref' | 'source' | 'style' | 'onMessage' | 'javaScriptEnabled' | 'onError'> & {
     source?: Omit<WebViewSourceUri, 'uri'>;
   };
   /**
+   * @description The style of the iframe wrapper.
    * @platform web
    */
   iframeStyle?: CSSProperties;