@aigamo/nostalgic-diva 1.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 VocaDB Devgroup
+Copyright (c) 2023 Aigamo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# Nostalgic Diva
+
+React function components for imperatively controlling embedded players (audio, [Niconico](https://www.nicovideo.jp/), [SoundCloud](https://soundcloud.com/), [Vimeo](https://vimeo.com/) and [YouTube](https://www.youtube.com/)) using refs.
+
+This was originally developed in [VocaDB/vocadb#1101](https://github.com/VocaDB/vocadb/pull/1101) as a part of VocaDB.
+
+NOTE: This is an independent fork of VocaDB/route-sphere.
+
+## Installation
+
+`yarn add @aigamo/nostalgic-diva` or `npm i @aigamo/nostalgic-diva`
+
+## Usage
+
+```tsx
+import {
+	NostalgicDiva,
+	NostalgicDivaProvider,
+	PlayerOptions,
+} from '@aigamo/nostalgic-diva';
+
+// Callbacks
+const handleError = React.useCallback(() => {}, []);
+const handlePlay = React.useCallback(() => {}, []);
+const handlePause = React.useCallback(() => {}, []);
+const handleEnded = React.useCallback(() => {}, []);
+const handleTimeUpdate = React.useCallback(() => {}, []);
+
+// Options
+const options = React.useMemo(
+	(): PlayerOptions => ({
+		onError: handleError,
+		onPlay: handlePlay,
+		onPause: handlePause,
+		onEnded: handleEnded,
+		onTimeUpdate: handleTimeUpdate,
+	}),
+	[handleError, handlePlay, handlePause, handleEnded, handleTimeUpdate],
+);
+
+<NostalgicDivaProvider>
+	<NostalgicDiva
+		// Supported media types:
+		// - "Audio"
+		// - "Niconico"
+		// - "SoundCloud"
+		// - "Vimeo"
+		// - "YouTube"
+		type="Audio"
+		videoId={videoId}
+		options={options}
+	/>
+	;
+</NostalgicDivaProvider>;
+```
+
+```tsx
+import { useNostalgicDiva } from '@aigamo/nostalgic-diva';
+
+const diva = useNostalgicDiva();
+
+// Play
+await diva.play();
+
+// Pause
+await diva.pause();
+
+// Mute
+await diva.setMuted(true);
+
+// Unmute
+await diva.setMuted(false);
+
+// Seek
+await diva.setCurrentTime(seconds);
+```
+
+## Imperative functions
+
+| Function                                         | Description                                                         |
+| ------------------------------------------------ | ------------------------------------------------------------------- |
+| `loadVideo(id: string): Promise<void>`           | Loads a new video into an existing player.                          |
+| `play(): Promise<void>`                          | Plays a video.                                                      |
+| `pause(): Promise<void>`                         | Pauses the playback of a video.                                     |
+| `setCurrentTime(seconds: number): Promise<void>` | Sets the current playback position in seconds.                      |
+| `setVolume(volume: number): Promise<void>`       | Sets the volume level of the player on a scale from 0 to 1.         |
+| `setMuted(muted: boolean): Promise<void>`        | Sets the muted state of the player.                                 |
+| `getDuration(): Promise<number \| undefined>`    | Gets the duration of the video in seconds.                          |
+| `getCurrentTime(): Promise<number \| undefined>` | Gets the current playback position of a video, measured in seconds. |
+
+## Events
+
+| Event                                  | Description                                            |
+| -------------------------------------- | ------------------------------------------------------ |
+| `onError(event: any): void`            | Fired when the player experiences some sort of error.  |
+| `onPlay(): void`                       | Fired when the video plays.                            |
+| `onPause(): void`                      | Fired when the video is paused.                        |
+| `onEnded(): void`                      | Fired when playback reaches the end of a video.        |
+| `onTimeUpdate(event: TimeEvent): void` | Fired when the playback position of the video changes. |
+
+## Lifecycle
+
+1. [PlayerApi.attach](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L84)
+1. [IPlayerApi.loadVideo](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L33)
+1. [PlayerOptions.onLoaded](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L25)
+1. [IPlayerApi.play](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L34)
+1. [PlayerOptions.onPlay](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L26)
+1. [PlayerOptions.onTimeUpdate](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L29)
+1. [IPlayerApi.pause](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L35)
+1. [PlayerOptions.onPause](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L27)
+1. [PlayerOptions.onEnded](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L28)
+1. [PlayerApi.detach](https://github.com/ycanardeau/nostalgic-diva/blob/5cc35c68cf71230f9459804a9dd9e9265cfa2297/src/players/PlayerApi.ts#L111)
+
+The `attach` function is called when switching from another player (Audio, Niconico, SoundCloud and YouTube), and the `detach` function is called when switching to another player. After the `detach` function is called, you cannot use any imperative functions like `loadVideo`, `play`, `pause` and etc.
+
+## References
+
+-   [vocadb/VocaDbWeb/Scripts/ViewModels/PVs/](https://github.com/VocaDB/vocadb/tree/5304e764cf423f07b424e94266e415db40d11f28/VocaDbWeb/Scripts/ViewModels/PVs)
+-   [React Player](https://github.com/cookpete/react-player)
+-   [ニコニコ動画の HTML5 外部プレイヤーを JavaScript で操作する](https://blog.hayu.io/web/create/nicovideo-embed-player-api/)
+-   [Widget API - SoundCloud Developers](https://developers.soundcloud.com/docs/api/html5-widget)
+-   [Player SDK: Reference - Vimeo Developer](https://developer.vimeo.com/player/sdk/reference)
+-   [YouTube Player API Reference for iframe Embeds | YouTube IFrame Player API | Google Developers](https://developers.google.com/youtube/iframe_api_reference)
+-   [How to support Reusable State in Effects · Discussion #18 · reactwg/react-18](https://github.com/reactwg/react-18/discussions/18)
+-   [Synchronizing with Effects](https://beta.reactjs.org/learn/synchronizing-with-effects#how-to-handle-the-effect-firing-twice-in-development)

package/dist/components/AudioPlayer.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { PlayerProps } from './PlayerContainer';
+export declare const AudioPlayer: React.MemoExoticComponent<({ ...props }: PlayerProps) => React.ReactElement>;

package/dist/components/NiconicoPlayer.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { PlayerProps } from './PlayerContainer';
+export declare const NiconicoPlayer: React.MemoExoticComponent<({ ...props }: PlayerProps) => React.ReactElement>;

package/dist/components/NostalgicDiva.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { PlayerOptions, PlayerType } from '../players/PlayerApi';
+interface NostalgicDivaProps {
+    type: PlayerType;
+    videoId: string;
+    options?: PlayerOptions;
+}
+export declare const NostalgicDiva: React.MemoExoticComponent<({ type, videoId, options }: NostalgicDivaProps) => React.ReactElement>;
+export {};

package/dist/components/NostalgicDivaProvider.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import { IPlayerApi } from '../players';
+interface NostalgicDivaContextProps extends IPlayerApi {
+    playerApiRef: React.MutableRefObject<IPlayerApi | undefined>;
+}
+interface NostalgicDivaProviderProps {
+    children?: React.ReactNode;
+}
+export declare const NostalgicDivaProvider: ({ children, }: NostalgicDivaProviderProps) => React.ReactElement;
+export declare const useNostalgicDiva: () => NostalgicDivaContextProps;
+export {};

package/dist/components/PlayerContainer.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { IPlayerApi, Logger, PlayerOptions, PlayerType } from '../players/PlayerApi';
+import { PlayerApiImpl } from '../players/PlayerApiImpl';
+export interface PlayerProps {
+    type: PlayerType;
+    playerApiRef: React.MutableRefObject<IPlayerApi | undefined> | undefined;
+    videoId: string;
+    options: PlayerOptions | undefined;
+}
+interface PlayerContainerProps<TElement extends HTMLElement, TPlayer extends PlayerApiImpl<TElement>> extends PlayerProps {
+    loadScript: (() => Promise<void>) | undefined;
+    playerApiFactory: new (logger: Logger, playerElementRef: React.MutableRefObject<TElement>, options: PlayerOptions | undefined) => TPlayer;
+    children: (playerElementRef: React.MutableRefObject<TElement>, videoId: string) => React.ReactNode;
+}
+export declare const PlayerContainer: <TElement extends HTMLElement, TPlayer extends PlayerApiImpl<TElement>>({ type, playerApiRef, videoId, options, loadScript, playerApiFactory, children, }: PlayerContainerProps<TElement, TPlayer>) => React.ReactElement<PlayerContainerProps<TElement, TPlayer>, string | React.JSXElementConstructor<any>>;
+export {};

package/dist/components/SoundCloudPlayer.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { PlayerProps } from './PlayerContainer';
+export declare const SoundCloudPlayer: React.MemoExoticComponent<({ ...props }: PlayerProps) => React.ReactElement>;

package/dist/components/VimeoPlayer.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { PlayerProps } from './PlayerContainer';
+export declare const VimeoPlayer: React.MemoExoticComponent<({ ...props }: PlayerProps) => React.ReactElement>;

package/dist/components/YouTubePlayer.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { PlayerProps } from './PlayerContainer';
+export declare const YouTubePlayer: React.MemoExoticComponent<({ ...props }: PlayerProps) => React.ReactElement>;

package/dist/components/index.d.ts

@@ -0,0 +1,7 @@
+export * from './AudioPlayer';
+export * from './NiconicoPlayer';
+export * from './NostalgicDiva';
+export * from './NostalgicDivaProvider';
+export * from './SoundCloudPlayer';
+export * from './YouTubePlayer';
+export * from './VimeoPlayer';

package/dist/components/useFirstMountState.d.ts

@@ -0,0 +1 @@
+export declare function useFirstMountState(): boolean;

package/dist/components/usePreviousDistinct.d.ts

@@ -0,0 +1,2 @@
+export type Predicate<T> = (prev: T | undefined, next: T) => boolean;
+export default function usePreviousDistinct<T>(value: T, compare?: Predicate<T>): T | undefined;