@100mslive/react-sdk 0.0.16 → 0.0.18-alpha.0

package/src/hooks/useVideoList.ts

@@ -0,0 +1,162 @@
+import { HMSPeer, HMSTrack, HMSTrackID, selectTracksMap } from '@100mslive/hms-video-store';
+import React, { useMemo } from 'react';
+import {
+  calculateLayoutSizes,
+  chunkElements,
+  getModeAspectRatio,
+  getVideoTracksFromPeers,
+  TrackWithPeer,
+} from '../utils/layout';
+import { useHMSVanillaStore } from '../primitives/HmsRoomProvider';
+import { useResizeDetector } from 'react-resize-detector';
+
+export interface useVideoListInput {
+  /**
+   * peers is the list of all peers you need to display
+   */
+  peers: HMSPeer[];
+  /**
+   * Max tiles in a  page. Overrides maxRowCount and maxColCount
+   */
+  maxTileCount?: number;
+  /**
+   * Max rows in a  page. Only applied if maxTileCount is not present
+   */
+  maxRowCount?: number;
+  /**
+   * Max columns in a  page. Only applied if maxTileCount and maxRowCount are not present
+   */
+  maxColCount?: number;
+  /**
+   * A function which tells whether to show the screenShare for a peer who is screensharing. A peer is passed
+   * and a boolean value is expected.
+   * This can be useful if there are multiple screenShares in the room where you may want to show the main one in the
+   * center view and others in video list along side other tiles. No screenShare is included by default.
+   * e.g. includeScreenShare = (peer) => return peer.id !== mainScreenSharingPeer.id
+   */
+  includeScreenShareForPeer?: (peer: HMSPeer) => boolean;
+  /**
+   * Aspect ratio of VideoTiles, ideally this should be the same as the aspect ratio selected for
+   * capture in the dashboard template.
+   */
+  aspectRatio?: { width: number; height: number };
+  /**
+   * By default this will be true. Only publishing(audio/video/screen) peers in the passed in peer list
+   * will be filtered. If you wish to show all peers, pass false for this.
+   */
+  filterNonPublishingPeers?: boolean;
+  /**
+   * Height that would be subtracted from the parent's height to give the available height, use case: if your pagination is inside the parent component then offsetY would be the height of pagination
+   */
+  offsetY?: number;
+}
+
+export interface useVideoListTile extends TrackWithPeer {
+  width: number;
+  height: number;
+}
+
+export interface useVideoResult {
+  /**
+   * This returns a list of all pages with every page containing the list of all tiles on it.
+   */
+  pagesWithTiles: useVideoListTile[][];
+  /**
+   * add the ref to the element going to render the video list, this is used to measure the available
+   * space/dimensions in order to calculate the best fit
+   */
+  ref: React.MutableRefObject<any>;
+}
+
+const DEFAULTS = {
+  aspectRatio: {
+    width: 1,
+    height: 1,
+  },
+};
+
+/**
+ * This hook can be used to build a paginated gallery view of video tiles. You can give the hook
+ * a list of all the peers which need to be shown and it tells you how to structure the UI by giving
+ * a list of pages with every page having a list of video tiles.
+ * Please check the documentation of input and output types for more details.
+ */
+export const useVideoList = ({
+  peers,
+  maxTileCount,
+  maxColCount,
+  maxRowCount,
+  includeScreenShareForPeer = () => false,
+  aspectRatio = DEFAULTS.aspectRatio,
+  filterNonPublishingPeers = true,
+  offsetY = 0,
+}: useVideoListInput): useVideoResult => {
+  const { width = 0, height = 0, ref } = useResizeDetector();
+  const store = useHMSVanillaStore();
+  // using vanilla store as we don't need re-rendering everytime something in a track changes
+  const tracksMap: Record<HMSTrackID, HMSTrack> = store.getState(selectTracksMap);
+  const tracksWithPeer: TrackWithPeer[] = getVideoTracksFromPeers(
+    peers,
+    tracksMap,
+    includeScreenShareForPeer,
+    filterNonPublishingPeers,
+  );
+  const finalAspectRatio = useMemo(() => {
+    if (aspectRatio) {
+      return aspectRatio;
+    }
+    const modeAspectRatio = getModeAspectRatio(tracksWithPeer);
+    // Default to 1 if there are no video tracks
+    return {
+      width: modeAspectRatio || 1,
+      height: 1,
+    };
+  }, [aspectRatio, tracksWithPeer]);
+  const count = tracksWithPeer.length;
+  const {
+    tilesInFirstPage,
+    defaultWidth,
+    defaultHeight,
+    lastPageWidth,
+    lastPageHeight,
+    isLastPageDifferentFromFirstPage,
+  } = useMemo(
+    () =>
+      calculateLayoutSizes({
+        count,
+        parentWidth: Math.floor(width),
+        parentHeight: Math.floor(height) - Math.min(height, offsetY),
+        maxTileCount,
+        maxRowCount,
+        maxColCount,
+        aspectRatio: finalAspectRatio,
+      }),
+    [count, width, height, maxTileCount, maxRowCount, maxColCount, finalAspectRatio, offsetY],
+  );
+  const chunkedTracksWithPeer = useMemo(
+    () =>
+      chunkElements<TrackWithPeer>({
+        elements: tracksWithPeer,
+        tilesInFirstPage,
+        onlyOnePage: false,
+        isLastPageDifferentFromFirstPage,
+        defaultWidth,
+        defaultHeight,
+        lastPageWidth,
+        lastPageHeight,
+      }),
+    [
+      tracksWithPeer,
+      tilesInFirstPage,
+      isLastPageDifferentFromFirstPage,
+      defaultWidth,
+      defaultHeight,
+      lastPageWidth,
+      lastPageHeight,
+    ],
+  );
+  return {
+    pagesWithTiles: chunkedTracksWithPeer,
+    ref,
+  };
+};

package/src/index.ts

@@ -0,0 +1,40 @@
+export {
+  HMSRoomProvider,
+  useHMSStore,
+  useHMSActions,
+  useHMSNotifications,
+  useHMSVanillaStore,
+  useHMSVanillaNotifications,
+  useHMSStatsStore,
+} from './primitives/HmsRoomProvider';
+export { usePreviewJoin } from './hooks/usePreviewJoin';
+export { useAVToggle } from './hooks/useAVToggle';
+export { useVideo } from './hooks/useVideo';
+export { useScreenShare } from './hooks/useScreenShare';
+export { useRemoteAVToggle } from './hooks/useRemoteAVToggle';
+export { useVideoList } from './hooks/useVideoList';
+export { useAudioLevelStyles } from './hooks/useAudioLevelStyles';
+export { useDevices, DeviceType } from './hooks/useDevices';
+export { useParticipantList } from './hooks/useParticipantList';
+export { useRecordingStreaming } from './hooks/useRecordingStreaming';
+export { useAutoplayError } from './hooks/useAutoplayError';
+export { useCustomEvent } from './hooks/useCustomEvent';
+// types
+export type { hooksErrHandler } from './hooks/types';
+export type { usePreviewInput, usePreviewResult } from './hooks/usePreviewJoin';
+export type { useVideoListInput, useVideoResult, useVideoListTile } from './hooks/useVideoList';
+export type { useAVToggleResult } from './hooks/useAVToggle';
+export type { useDevicesResult } from './hooks/useDevices';
+export type { useScreenShareResult } from './hooks/useScreenShare';
+export type { useRemoteAVToggleResult } from './hooks/useRemoteAVToggle';
+export type { useRecordingStreamingResult } from './hooks/useRecordingStreaming';
+export type { useParticipantListResult } from './hooks/useParticipantList';
+export type { useVideoInput, useVideoOutput } from './hooks/useVideo';
+export type { useAutoplayErrorResult } from './hooks/useAutoplayError';
+export type { useCustomEventInput, useCustomEventResult } from './hooks/useCustomEvent';
+
+// helpers
+export { throwErrorHandler } from './utils/commons';
+
+// reexport everything from store so app can import everything directly from this
+export * from '@100mslive/hms-video-store';

package/src/primitives/HmsRoomProvider.ts

@@ -0,0 +1,203 @@
+import React, { createContext, PropsWithChildren, useContext, useEffect, useState } from 'react';
+import {
+  HMSReactiveStore,
+  HMSStore,
+  HMSActions,
+  HMSNotification,
+  HMSNotifications,
+  HMSStatsStore,
+  HMSStats,
+  HMSStoreWrapper,
+  HMSNotificationTypes,
+} from '@100mslive/hms-video-store';
+import create from 'zustand';
+import { HMSContextProviderProps, makeHMSStoreHook, hooksErrorMessage, makeHMSStatsStoreHook } from './store';
+import { isBrowser } from '../utils/isBrowser';
+
+export interface HMSRoomProviderProps {
+  actions?: HMSActions;
+  store?: HMSStoreWrapper;
+  notifications?: HMSNotifications;
+  stats?: HMSStats;
+  /**
+   * if true this will enable webrtc stats collection
+   */
+  isHMSStatsOn?: boolean;
+}
+
+/**
+ * only one context is being created currently. This would need to be changed if multiple
+ * rooms have to be supported, where every room will have its own context, provider, store and actions.
+ */
+const HMSContext = createContext<HMSContextProviderProps | null>(null);
+
+let providerProps: HMSContextProviderProps;
+/**
+ * top level wrapper for using react sdk hooks. This doesn't have any mandatory arguments, if you are already
+ * initialising the sdk on your side, you can pass in the primitives from there as well to use hooks for
+ * react part of your code.
+ * @constructor
+ */
+// eslint-disable-next-line complexity
+export const HMSRoomProvider: React.FC<PropsWithChildren<HMSRoomProviderProps>> = ({
+  children,
+  actions,
+  store,
+  notifications,
+  stats,
+  isHMSStatsOn = false,
+}) => {
+  if (!providerProps) {
+    // adding a dummy function for setstate and destroy because zustan'd create expects them
+    // to be present but we don't expose them from the store.
+    const errFn = () => {
+      throw new Error('modifying store is not allowed');
+    };
+    if (actions && store) {
+      providerProps = {
+        actions: actions,
+        store: create<HMSStore>({
+          ...store,
+          setState: errFn,
+          destroy: errFn,
+        }),
+      };
+      if (notifications) {
+        providerProps.notifications = notifications;
+      }
+      if (stats) {
+        providerProps.statsStore = create<HMSStatsStore>({
+          getState: stats.getState,
+          subscribe: stats.subscribe,
+          setState: errFn,
+          destroy: errFn,
+        });
+      }
+    } else {
+      const hmsReactiveStore = new HMSReactiveStore();
+      providerProps = {
+        actions: hmsReactiveStore.getActions(),
+        store: create<HMSStore>({
+          ...hmsReactiveStore.getStore(),
+          setState: errFn,
+          destroy: errFn,
+        }), // convert vanilla store in react hook
+        notifications: hmsReactiveStore.getNotifications(),
+      };
+
+      if (isHMSStatsOn) {
+        const stats = hmsReactiveStore.getStats();
+        providerProps.statsStore = create<HMSStatsStore>({
+          getState: stats.getState,
+          subscribe: stats.subscribe,
+          setState: errFn,
+          destroy: errFn,
+        });
+      }
+    }
+  }
+
+  useEffect(() => {
+    if (isBrowser) {
+      window.addEventListener('beforeunload', () => providerProps.actions.leave());
+      window.addEventListener('onunload', () => providerProps.actions.leave());
+    }
+  }, []);
+
+  return React.createElement(HMSContext.Provider, { value: providerProps }, children);
+};
+
+/**
+ * `useHMSStore` is a read only hook which can be passed a selector to read data.
+ * The hook can only be used in a component if HMSRoomProvider is present in its ancestors.
+ */
+export const useHMSStore = makeHMSStoreHook(HMSContext);
+
+export const useHMSStatsStore = makeHMSStatsStoreHook(HMSContext);
+
+/**
+ * `useHMSVanillaStore` is a read only hook which returns the vanilla HMSStore.
+ * Usage:
+ * ```
+ * const hmsStore = useHMSVanillaStore();
+ * const dominantSpeaker = hmsStore.getState(selectDominantSpeaker);
+ * ```
+ *
+ * Note: There's no need to use the vanilla hmsStore in React components.
+ * This is used in rare cases where the store needs to be accessed outside a React component.
+ * For almost every case, `useHMSStore` would get the job done.
+ */
+export const useHMSVanillaStore = () => {
+  const HMSContextConsumer = useContext(HMSContext);
+  if (!HMSContextConsumer) {
+    throw new Error(hooksErrorMessage);
+  }
+
+  return HMSContextConsumer.store;
+};
+
+/*
+ * `useHMSVanillaNotifications` returns the vanilla HMSNotifications object. This makes it a bit easier to ensure
+ * a notification is processed only once in your components. The other way is to use the hook version and put
+ * the component high enough in the chain.
+ * Usage:
+ * ```
+ * useEffect(() => {
+ *   const unsub = notifications.onNotification((notification) => {
+ *     console.log(notification);
+ *   }, notificationType);
+ *   return unsub;
+ * }, [])
+ * ```
+ */
+export const useHMSVanillaNotifications = () => {
+  const HMSContextConsumer = useContext(HMSContext);
+  if (!HMSContextConsumer) {
+    throw new Error(hooksErrorMessage);
+  }
+  return HMSContextConsumer.notifications;
+};
+
+/*
+ * `useHMSActions` is a write only hook which can be used to dispatch actions.
+ */
+export const useHMSActions = () => {
+  const HMSContextConsumer = useContext(HMSContext);
+  if (!HMSContextConsumer) {
+    throw new Error(hooksErrorMessage);
+  }
+  return HMSContextConsumer.actions;
+};
+
+/**
+ * `useHMSNotifications` is a read only hook which gives the latest notification(HMSNotification) received.
+ * @param type can be a string or an array of string for the types of notifications to listen to. If an array is passed
+ * either declare it outside the functional component or use a useMemo to make sure its reference stays same across
+ * rerenders for performance reasons.
+ */
+export const useHMSNotifications = (type?: HMSNotificationTypes | HMSNotificationTypes[]) => {
+  const HMSContextConsumer = useContext(HMSContext);
+  const [notification, setNotification] = useState<HMSNotification | null>(null);
+
+  if (!HMSContextConsumer) {
+    throw new Error(hooksErrorMessage);
+  }
+
+  useEffect(() => {
+    if (!HMSContextConsumer.notifications) {
+      return;
+    }
+    const unsubscribe = HMSContextConsumer.notifications.onNotification(
+      (notification: HMSNotification) => setNotification(notification),
+      type,
+    );
+    return unsubscribe;
+  }, [HMSContextConsumer.notifications, type]);
+
+  return notification;
+};
+
+export const useIsHMSStatsOn = () => {
+  const HMSContextConsumer = useContext(HMSContext);
+  return Boolean(HMSContextConsumer?.statsStore);
+};

package/src/primitives/store.ts

@@ -0,0 +1,59 @@
+import { EqualityChecker, StateSelector } from 'zustand';
+import React, { useContext } from 'react';
+import shallow from 'zustand/shallow';
+import { HMSActions, HMSStore, HMSNotifications, HMSStatsStore, IStoreReadOnly } from '@100mslive/hms-video-store';
+import HMSLogger from '../utils/logger';
+
+export interface IHMSReactStore<S extends HMSStore | HMSStatsStore> extends IStoreReadOnly<S> {
+  <U>(selector: StateSelector<S, U>, equalityFn?: EqualityChecker<U>): U;
+}
+
+export const hooksErrorMessage =
+  'It seems like you forgot to add your component within a top level HMSRoomProvider, please refer to 100ms react docs(https://docs.100ms.live/javascript/v2/features/integration#react-hooks) to check on the required steps for using this hook.';
+
+export interface HMSContextProviderProps {
+  actions: HMSActions; // for actions which may also mutate store
+  store: IHMSReactStore<HMSStore>; // readonly store, don't mutate this
+  notifications?: HMSNotifications;
+  statsStore?: IHMSReactStore<HMSStatsStore>;
+}
+
+export function makeHMSStoreHook(hmsContext: React.Context<HMSContextProviderProps | null>) {
+  const useHMSStore = <StateSlice>(
+    selector: StateSelector<HMSStore, StateSlice>,
+    equalityFn: EqualityChecker<StateSlice> = shallow,
+  ) => {
+    if (!selector) {
+      HMSLogger.w(
+        'fetching full store without passing any selector may have a heavy performance impact on your website.',
+      );
+    }
+    const HMSContextConsumer = useContext(hmsContext);
+    if (!HMSContextConsumer) {
+      throw new Error(hooksErrorMessage);
+    }
+    const useStore = HMSContextConsumer.store;
+    return useStore(selector, equalityFn);
+  };
+  return useHMSStore;
+}
+
+export function makeHMSStatsStoreHook(hmsContext: React.Context<HMSContextProviderProps | null>) {
+  const useHMSStatsStore = <StateSlice>(
+    selector: StateSelector<HMSStatsStore, StateSlice>,
+    equalityFn: EqualityChecker<StateSlice> = shallow,
+  ) => {
+    if (!selector) {
+      HMSLogger.w(
+        'fetching full store without passing any selector may have a heavy performance impact on your website.',
+      );
+    }
+    const HMSContextConsumer = useContext(hmsContext);
+    if (!HMSContextConsumer) {
+      throw new Error(hooksErrorMessage);
+    }
+    const useStore = HMSContextConsumer.statsStore;
+    return useStore?.(selector, equalityFn);
+  };
+  return useHMSStatsStore;
+}

package/src/primitives/types.ts

@@ -0,0 +1,6 @@
+import { EqualityChecker, StateSelector } from 'zustand';
+import { HMSStore, IStoreReadOnly, HMSStatsStore } from '@100mslive/hms-video-store';
+
+export interface IHMSReactStore<S extends HMSStore | HMSStatsStore> extends IStoreReadOnly<S> {
+  <U>(selector: StateSelector<S, U>, equalityFn?: EqualityChecker<U>): U;
+}

package/src/utils/commons.ts

@@ -0,0 +1,14 @@
+import { hooksErrHandler } from '../hooks/types';
+import HMSLogger from './logger';
+
+const TAG = 'react-sdk';
+
+export const logErrorHandler: hooksErrHandler = (err: Error, method?: string) => HMSLogger.e(TAG, method, err);
+
+/**
+ * pass in this error handler to get the error thrown back to the UI for further handling, showing toast etc.
+ * @param err
+ */
+export const throwErrorHandler: hooksErrHandler = (err: Error) => {
+  throw err;
+};

package/src/utils/groupBy.ts

@@ -0,0 +1,29 @@
+import { HMSPeer } from '@100mslive/hms-video-store';
+/**
+ * Give array like [
+ * { name: 'peer1', id: 1, roleName: 'role1' },
+ * { name: 'peer2', id: 2, roleName: 'role2' }
+ *]
+ * the output will be
+ * {
+ * 'role1': [{'name': 'peer1', id: 1, roleName: 'role1'}],
+ * 'role2': [{ name: 'peer2', id: 2, roleName: 'role2' }]
+ * }
+ * @param {HMSPeer[]} peers
+ * @returns
+ */
+export const groupByRoles = (peers: HMSPeer[]) => {
+  if (!peers || !Array.isArray(peers) || peers.length === 0) {
+    return {};
+  }
+  return peers.reduce((res: Record<string, HMSPeer[]>, peer) => {
+    if (!peer.roleName) {
+      return res;
+    }
+    if (!res[peer.roleName]) {
+      res[peer.roleName] = [];
+    }
+    res[peer.roleName].push(peer);
+    return res;
+  }, {});
+};

package/src/utils/isBrowser.ts

@@ -0,0 +1 @@
+export const isBrowser = typeof window !== 'undefined';