Update documentation (#135)

README.md

@@ -55,7 +55,7 @@ export const MyComponent: React.FC = () => {
 
 - **Compose own UI Controls**
 
-This comes handy when you want to customize controls for the player. [CodeSandbox](https://codesandbox.io/s/core-player-gtlry2?file=/src/App.tsx)  
+This comes handy when you want to customize controls for the player. [CodeSandbox](https://codesandbox.io/s/core-player-gtlry2)  
 *NOTE: Wait the sandbox until installs all dependencies and refresh it in case if it got "staled"*
 
 ```ts
@@ -110,7 +110,7 @@ const PlayButton = () => {
 
 - **Using MediaStore outside of the player**
 All players state is connected to an event emitter. Triggering play, pause, mute, etc will trigger an event, that you can connect too.
-So, subscribing to an event can boost your app and save performance. Code example in [CodeSandbox](https://codesandbox.io/s/media-player-outside-state-oxpko5?file=/src/App.tsx).  
+So, subscribing to an event can boost your app and save performance. Code example in [CodeSandbox](https://codesandbox.io/s/media-player-outside-state-oxpko5).  
 *NOTE: Wait the sandbox until installs all dependencies and refresh it in case if it got "staled"*
 
 ```ts
@@ -120,9 +120,12 @@ import {
   useMediaListener
 } from "@collaborne/media-player";
 
+// `<App />` can control MediaStore not being a children of MediaPlayer
 export default function App() {
+  // mediaContext is a ref value. Use only setters and media listener
   const { mediaContext, setMediaContext } = usePlayerContext();
   const listener = mediaContext?.getListener();
+  // useMediaListener - custom hooks that improves usability of emitted events
   useMediaListener("play", () => alert("Play event was triggered"), listener);
 
   return (
@@ -136,6 +139,20 @@ export default function App() {
 
 ## Documentation
 
+**@collaborne/media-player** categorizes its functionality as follows:
+
+*Note: Functions may belong to multiple categories. For example, the `<VolumeButton />` is both a React Component and a UI Control.*
+
+- React Component
+- UI Controls: Components used to build player UI elements
+- Players: Ready-to-use player implementations
+- Custom Icons: Icons used for player controls
+- React Context
+- Context Providers
+- Hooks: React hooks that simplify package usage
+- MediaStore: Internal player storage
+- Events: Events triggered by player activity, many of which are similar to standard video/audio web events (see [Mozilla Developer Network](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#events)).
+
 Latest changes, types and interfaces [here](https://collaborne.github.io/media-player/docs/).
 
 ## Debugging

src/types/emitters.ts

@@ -9,7 +9,9 @@ export type VoidEventsKey =
 	| 'play'
 	| 'pause'
 	| 'autoplayStart'
+	/**  Emitted each time when player is ready to play(ex: we have bites loaded and ready to play content) */
 	| 'ready'
+	/** Emitted for first time when player is mounted and first bites are ready to be player(it happens only once) */
 	| 'firstReady'
 	| 'ended'
 	| 'mute'
@@ -32,12 +34,16 @@ export type VoidEvents = Record<VoidEventsKey, void>;
  */
 export type ExtendedEvents = {
 	setPlaybackRate: { playbackRate: number };
+	/** See details here: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/seeked_event */
 	seeked: { diffMs: number };
+	/** See details here: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/timeupdate_event */
 	timeupdate: TimeUpdateEvent;
+	/** See details here: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/progress_event */
 	progress: TimeUpdateEvent;
 	showControls: ShowControlsEvent;
 	showPipControls: ShowControlsEvent;
 	durationchange: { duration: number };
+	/** Emitted when an alarm timestamp matched current playing duration  */
 	onTimeAlarm: TimeUpdateEvent;
 };
 

src/types/index.ts

@@ -3,5 +3,4 @@ export * from './react-player';
 export * from './media-state';
 export * from './media-state-external-initializers';
 export * from './media-state-setters';
-export * from './required-and-optional-pick';
 export * from './media-type';

src/types/media-state-setters.ts

@@ -19,7 +19,9 @@ export interface MediaStateSetters {
 	setDuration: (duration: number) => void;
 	requestPip: () => void;
 	exitPip: () => void;
+	/** On the hood it uses Fullscreen api: https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API */
 	requestFullscreen: () => void;
+	/** On the hood it uses Fullscreen api: https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API */
 	exitFullscreen: () => void;
 	/** Setter for tracking fullscreen state. Do not calls `screenfull` methods */
 	setIsFullscreen: (isFullscreen: boolean) => void;
@@ -28,6 +30,7 @@ export interface MediaStateSetters {
 	// Private Methods
 	_setReady: () => void;
 	_handleProgress: (currentTime: number) => void;
+	/** Store media listeners in a getter won't cause subscribing to a changing value of the store */
 	getListener: () => EmitterListeners;
 	setMediaType: (type: MediaType) => void;
 	setIsAudio: (isAudio: boolean) => void;

src/types/media-state.ts

@@ -29,16 +29,16 @@ export interface MediaState {
 	startTime: number;
 	endTime: number;
 	duration: number;
+	/** *Note: Current time changes every 50ms. You can get current time from media listeners too.* */
 	currentTime: number;
 	volume: number;
 	ready: boolean;
 	hasPlayedOrSeeked: boolean;
 	isPip: boolean;
 	showControls: boolean;
 	showPipControls: boolean;
-	/** Did pip mode was triggered by click event */
+	/** PIP can be triggered by click, or when player is not in the viewport. */
 	hasPipTriggeredByClick: boolean;
-	/** Storing wrapper ref of the mediaPlayer */
 	isFullscreen: boolean;
 	/** Current time value for the conditional time in seconds */
 	currentTimeAlarm: number;