@devix-technologies/react-gjirafa-vp-player 1.0.0 → 1.0.2

package/dist/App.d.ts

@@ -0,0 +1,2 @@
+declare function App(): import("react/jsx-runtime").JSX.Element;
+export default App;

package/dist/components/Feedback.d.ts

@@ -0,0 +1,25 @@
+import { ReactNode } from "react";
+/**
+ * Props for the FeedbackMessage component.
+ */
+interface FeedbackMessageProps {
+    type: "error" | "loading" | "success" | "warning";
+    children: ReactNode;
+    className?: string;
+    icon?: ReactNode;
+    action?: ReactNode;
+}
+/**
+ * FeedbackMessage component for displaying various types of messages (error, loading, success, warning).
+ * Can be customized with an icon, action button, and additional styles.
+ *
+ * @param {FeedbackMessageProps} props - The properties for the feedback message.
+ * @param {"error" | "loading" | "success" | "warning"} props.type - The type of message to display.
+ * @param {ReactNode} props.children - The content of the message.
+ * @param {string} [props.className] - Custom class for additional styling.
+ * @param {ReactNode} [props.icon] - Optional icon to display before the message.
+ * @param {ReactNode} [props.action] - Optional action button (e.g., "Retry").
+ * @returns {JSX.Element} The rendered feedback message component.
+ */
+export declare const FeedbackMessage: ({ type, children, className, icon, action }: FeedbackMessageProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/VPPlayer/index.d.ts

@@ -0,0 +1,2 @@
+export { default as VPPlayer } from '../../features/VPPlayer';
+export * from "./ui";

package/dist/components/VPPlayer/ui/index.d.ts

@@ -0,0 +1 @@
+export * from "./styled";

package/dist/components/VPPlayer/ui/styled.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Styled component for the video player container.
+ *
+ * @component
+ * @param {string} [width] - The width of the player (default: "100%").
+ * @param {string} [height] - The height of the player (default: "100%").
+ * @param {string[]} [$hiddenClasses] - CSS class names to hide elements inside the player.
+ * @param {string} [className] - CSS class name for additional styling.
+ */
+export declare const PlayerContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    width?: string;
+    height?: string;
+    $hiddenClasses?: string[];
+    className?: string;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Styled component for the full-screen overlay when the player is active.
+ *
+ * @component
+ * @param {string} [className] - CSS class name for additional styling.
+ */
+export declare const Overlay: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    className?: string;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Styled wrapper for the player, adjusting its size based on viewport width.
+ *
+ * @component
+ * @param {string} [className] - CSS class name for additional styling.
+ */
+export declare const PlayerWrapper: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    className?: string;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/dist/config/index.d.ts

@@ -0,0 +1 @@
+export * from "./vpPlayerConfig";

package/dist/config/vpPlayerConfig.d.ts

@@ -0,0 +1,9 @@
+import { VPPlayerConfig } from '@/interfaces';
+/**
+ * Default configuration for the VP Player.
+ *
+ * @constant
+ * @type {VPPlayerConfig}
+ * @see {@link https://vp.gjirafa.tech/documentation/docs/web-player/setup-the-player/configuration}
+ */
+export declare const defaultVPPlayerConfig: VPPlayerConfig;

package/dist/constants/configs.d.ts

@@ -0,0 +1,22 @@
+import { VPPlayerConfig } from "@/interfaces/config";
+/**
+ * Base configuration for VP Player with common settings.
+ */
+export declare const baseConfig: Partial<VPPlayerConfig>;
+/**
+ * Base configuration with autoplay enabled.
+ */
+export declare const baseConfigWithAutoplay: Partial<VPPlayerConfig>;
+/**
+ * Base configuration for ads with common ad settings.
+ */
+export declare const baseConfigWithAds: Partial<VPPlayerConfig>;
+/**
+ * Generates an ad configuration for VP Player based on provided parameters.
+ * @param breakType - The type of ad break (e.g., "preroll", "postroll", "midroll").
+ * @param adTagUrls - Array of ad tag URLs to use for the ad break.
+ * @param breakTimingType - The timing type for the ad break (e.g., "time", "percentage", "playlist").
+ * @param breakTimingValue - The timing value for the ad break (e.g., 0 for immediate, 2 for playlist index).
+ * @returns A partial VPPlayerConfig with the ad configuration.
+ */
+export declare const getAdConfig: (breakType: "preroll" | "postroll" | "midroll", adTagUrls: string[], breakTimingType?: "time" | "percentage" | "playlist", breakTimingValue?: number) => Partial<VPPlayerConfig>;

package/dist/constants/index.d.ts

@@ -0,0 +1 @@
+export * from "./vpPlayer";

package/dist/constants/storybook.d.ts

@@ -0,0 +1,11 @@
+import { ArgTypes } from "@storybook/react";
+/**
+ * Common Storybook argTypes used across stories.
+ */
+export declare const COMMON_ARGTYPES: Partial<ArgTypes<Record<string, unknown>>>;
+/**
+ * Default API key and project ID for Storybook.
+ */
+export declare const DEFAULT_API_KEY: any;
+export declare const DEFAULT_PLAYLIST_ID = "lzxikggu";
+export declare const DEFAULT_PROJECT_ID = "agmipnxc";

package/dist/constants/styles.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Common styles for Storybook stories.
+ */
+/** Style for vertical playback containers (e.g., VerticalPlayback, VerticalPlaylistPlayback). */
+export declare const VERTICAL_PLAYBACK_STYLE: React.CSSProperties;
+/** Base style for multiple players containers (e.g., MultiplePlayersSideBySide, MultiplePlayersStacked). */
+export declare const MULTIPLE_PLAYERS_BASE_STYLE: React.CSSProperties;
+/** Style for side-by-side multiple players (e.g., MultiplePlayersSideBySide). */
+export declare const MULTIPLE_PLAYERS_SIDE_BY_SIDE_STYLE: React.CSSProperties;
+/** Style for stacked multiple players (e.g., MultiplePlayersStacked). */
+export declare const MULTIPLE_PLAYERS_STACKED_STYLE: React.CSSProperties;

package/dist/constants/urls.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Constants for video URLs used across the application and Storybook stories.
+ */
+/** URL for the Big Buck Bunny video */
+export declare const BIG_BUCK_BUNNY_URL = "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4";
+/** URL for the Elephants Dream video */
+export declare const ELEPHANTS_DREAM_URL = "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4";
+/** URL for the Pexels vertical video */
+export declare const PEXELS_VERTICAL_VIDEO_URL = "https://videos.pexels.com/video-files/4678261/4678261-hd_1080_1920_25fps.mp4";
+/** URL for the Pexels thumbnail */
+export declare const PEXELS_THUMBNAIL_URL = "https://images.pexels.com/videos/4678261/pexels-photo-4678261.jpeg?auto=compress&cs=tinysrgb&w=600";
+/**
+ * Constants for ad tag URLs used in Storybook stories.
+ */
+/** Ad tag URL for linear ads */
+export declare const AD_TAG_LINEAR_URL = "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=";
+/** Ad tag URL for skippable linear ads */
+export declare const AD_TAG_SKIPPABLE_LINEAR_URL = "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=";

package/dist/constants/vpPlayer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generates the URL for fetching a single video by projectId and videoId.
+ * @param {string} projectId - The project ID.
+ * @param {string} videoId - The video ID.
+ * @returns {string} - The complete API URL for single video fetch.
+ */
+export declare const getSingleVideoUrl: (projectId: string, videoId: string) => string;
+/**
+* Generates the URL for fetching a playlist by projectId and playlistId.
+* @param {string} projectId - The project ID.
+* @param {string} playlistId - The playlist ID.
+* @returns {string} - The complete API URL for playlist fetch.
+*/
+export declare const getPlaylistUrl: (projectId: string, playlistId: string) => string;
+/**
+* Generates the URL for loading the VP Player script by version.
+* @param {string} playerVersion - The version of the VP Player script (e.g., 'latest', 'v2.1.1').
+* @returns {string} - The complete URL for the player script.
+*/
+export declare const getPlayerScriptUrl: (playerVersion: string) => string;
+/**
+ * Generates a full player DOM element ID based on provided playerId and videoId.
+ * Falls back to "default" if playerId is not provided.
+ *
+ * @param playerId - Base identifier for the player.
+ * @param videoId - Optional video identifier.
+ * @returns Full DOM element ID string.
+ */
+export declare const generatePlayerId: (playerId?: string, videoId?: string) => string;

package/dist/contexts/VPPlayerContext.d.ts

@@ -0,0 +1,53 @@
+import React from "react";
+import { VPPlayerProps } from "@/interfaces";
+/**
+ * Interface defining the parameters for initializing the VPPlayer.
+ *
+ * @interface PlayerParams
+ */
+interface PlayerParams {
+    playerId?: string;
+    videoId?: string;
+    projectId?: string;
+    videoUrl?: string;
+    playlistId?: string;
+    scriptUrl?: string;
+    version?: string | null;
+    config?: VPPlayerProps["config"];
+    thumbnailUrl?: string;
+    isReels?: boolean;
+    hiddenClasses?: string[];
+    apiKey?: string;
+    className?: string;
+}
+/**
+ * Interface defining the context for VPPlayer.
+ *
+ * @interface VPPlayerContextType
+ */
+interface VPPlayerContextType {
+    showPlayer: (params: PlayerParams) => void;
+    hidePlayer: () => void;
+    isPlayerVisible: boolean;
+    playerParams: PlayerParams | null;
+}
+/**
+ * VPPlayerProvider component provides context for managing the VPPlayer state.
+ *
+ * @function
+ * @param {Object} props - The component props.
+ * @param {React.ReactNode} props.children - The child components.
+ * @returns {JSX.Element} The provider component for VPPlayer.
+ */
+export declare const VPPlayerProvider: React.FC<{
+    children: React.ReactNode;
+}>;
+/**
+ * Hook for accessing the VPPlayer context.
+ *
+ * @function
+ * @throws {Error} If used outside of the VPPlayerProvider.
+ * @returns {VPPlayerContextType} The VPPlayer context.
+ */
+export declare const useVPPlayer: () => VPPlayerContextType;
+export {};

package/dist/contexts/index.d.ts

@@ -0,0 +1 @@
+export * from "./VPPlayerContext";

package/dist/features/VPPlayer.d.ts

@@ -0,0 +1,27 @@
+import { VPPlayerProps } from "@/interfaces";
+/**
+ * Video Player Component for rendering a video player with overlay and responsive behavior.
+ * Handles initialization of the player and displays loading/error states.
+ *
+ * @function
+ * @param {VPPlayerProps} props - The properties for configuring the video player.
+ * @param {string} props.playerId - Unique identifier for the player instance.
+ * @param {string} [props.videoId] - ID of the video to be played.
+ * @param {string} [props.version] - Version of the player.
+ * @param {string} [props.videoUrl] - Direct video URL (bypasses API calls).
+ * @param {string} [props.projectId] - Project ID associated with the video.
+ * @param {string} [props.playlistId] - Playlist ID if playing a collection of videos.
+ * @param {string} [props.scriptUrl] - URL of the video player script.
+ * @param {object} [props.config={}] - Configuration settings for the player.
+ * @param {string} [props.apiKey] - API key for authentication (if required).
+ * @param {boolean} [props.isReels=false] - Determines if the player should behave as a short-video reel.
+ * @param {string[]} [props.hiddenClasses=[]] - CSS classes to hide player elements.
+ * @param {function} [props.onClose] - Callback triggered when the player is closed.
+ * @param {boolean} [props.isPlayerVisible=false] - Controls the initial visibility of the player.
+ * @param {string} [props.className] - CSS class name for additional styling.
+ * @returns {JSX.Element} The rendered video player component.
+ */
+declare const VPPlayer: ({ playerId, videoId, version, videoUrl, projectId, playlistId, scriptUrl, config, apiKey, isReels, hiddenClasses, onClose, className, }: VPPlayerProps & {
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;
+export default VPPlayer;

package/dist/features/index.d.ts

@@ -0,0 +1 @@
+export { default as VPPlayer } from './VPPlayer';

package/dist/features/stories/ads/Ads.stories.d.ts

@@ -0,0 +1,13 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { VPPlayer } from "@/components/VPPlayer";
+declare const meta: Meta<typeof VPPlayer>;
+export default meta;
+type Story = StoryObj<typeof VPPlayer>;
+export declare const SingleVideoOnePrerollAd: Story;
+export declare const SingleVideoOnePostrollAd: Story;
+export declare const SingleVideoMultiplePrerollAds: Story;
+export declare const PlaylistOnePrerollEveryAd: Story;
+export declare const PlaylistOneMidrollAd: Story;
+export declare const PlaylistOnePostrollAddEveryVideo: Story;
+export declare const PlaylistMultiplePrerollAdsEveryVideo: Story;
+export declare const PlaylistMultipleMidrollAds: Story;

package/dist/features/stories/context/Context.stories.d.ts

@@ -0,0 +1,10 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { VPPlayer } from "@/components/VPPlayer";
+declare const meta: Meta<typeof VPPlayer>;
+export default meta;
+type Story = StoryObj<typeof VPPlayer>;
+export declare const NoControlsSingleVideo: Story;
+export declare const IsReelsWithContextPlaylistHiddenElements: Story;
+export declare const IsReelsWithContextModalCentered: Story;
+export declare const ContextWrapperModal: Story;
+export declare const ContextCustomizedPortalPlayer: Story;

package/dist/features/stories/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./playback/Playback.stories";
+export * from "./ads/Ads.stories";
+export * from "./context/Context.stories";

package/dist/features/stories/playback/Playback.stories.d.ts

@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { VPPlayer } from "@/components/VPPlayer";
+declare const meta: Meta<typeof VPPlayer>;
+export default meta;
+type Story = StoryObj<typeof VPPlayer>;
+export declare const SingleVideoProvidedFile: Story;
+export declare const SingleVideoAPI: Story;
+export declare const PlaylistProvided: Story;
+export declare const PlaylistAPI: Story;
+export declare const HorizontalPlayback: Story;
+export declare const VerticalPlayback: Story;
+export declare const VerticalPlaylistPlayback: Story;
+export declare const FloatingVideo: Story;
+export declare const MultiplePlayersSideBySide: Story;
+export declare const MultiplePlayersStacked: Story;

package/dist/fixtures/index.d.ts

@@ -0,0 +1 @@
+export * from "./playlist";

package/dist/fixtures/playlist.d.ts

@@ -0,0 +1,11 @@
+export declare const playlist: {
+    state: boolean;
+    playlistVideoIndex: number;
+    videos: {
+        videoId: string;
+        title: string;
+        file: string;
+        thumbnailUrl: string;
+        duration: number;
+    }[];
+};

package/dist/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { useVPPlayerScript } from './useVPPlayerScript';
+export { useVideoData } from './useVideoData';
+export { useVPPlayerLogic } from './useVPPlayerLogic';

package/dist/hooks/useVPPlayerLogic.d.ts

@@ -0,0 +1,16 @@
+import { VPPlayerInstance, VPPlayerProps } from "@/interfaces";
+/**
+ * Custom hook to manage VP Player logic, including fetching video data,
+ * initializing the player, and handling lifecycle events.
+ *
+ * @function
+ * @param {VPPlayerProps} props - The properties required to configure the VP Player.
+ * @returns {Object} An object containing player references, script loading status, loading state, and errors.
+ */
+export declare const useVPPlayerLogic: ({ playerId, videoId: propVideoId, version, videoUrl, projectId, playlistId, scriptUrl, config, apiKey, isReels, }: VPPlayerProps) => {
+    playerRef: import("react").RefObject<HTMLDivElement | null>;
+    playerInstanceRef: import("react").RefObject<VPPlayerInstance | null>;
+    isScriptLoaded: boolean;
+    isLoading: boolean;
+    error: string | null;
+};

package/dist/hooks/useVPPlayerScript.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Custom hook to dynamically load the VP Player script into the document.
+ * It ensures that the script is only loaded once and provides a loading state.
+ *
+ * @function
+ * @param {string | null} [version] - The version of the VP Player script to load (defaults to "latest").
+ * @param {string} [scriptUrl] - Custom script URL (if provided, it overrides the version-based URL).
+ * @returns {{ isLoaded: boolean; error: string | null }} Indicates load success and any error message.
+ */
+export declare const useVPPlayerScript: (version?: string | null, scriptUrl?: string) => {
+    isLoaded: boolean;
+    error: string | null;
+};

package/dist/hooks/useVideoData.d.ts

@@ -0,0 +1,21 @@
+import { VideoDataResult } from "@/types";
+/**
+ * Custom hook for fetching video data, including playback URLs and playlists.
+ * Supports retry logic, timeout, error handling, and in-memory caching.
+ *
+ * @function
+ * @param {Object} params - The parameters for fetching video data.
+ * @param {string} [params.projectId] - The project ID required for API calls.
+ * @param {string} [params.videoId] - The video ID to fetch a single video's playback URL.
+ * @param {string} [params.playlistId] - The playlist ID to fetch a list of videos.
+ * @param {string} [params.videoUrl] - The direct video URL (skips API call if provided).
+ * @param {string} [params.apiKey] - The API key for authentication (optional, defaults to environment variable).
+ * @returns {VideoDataResult} - Result object with URL, playlist, loading and error states
+ */
+export declare const useVideoData: ({ projectId, videoId, playlistId, videoUrl, apiKey, }: {
+    projectId?: string;
+    videoId?: string;
+    playlistId?: string;
+    videoUrl?: string;
+    apiKey?: string;
+}) => VideoDataResult;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './features/VPPlayer';
+export * from './contexts';