@microsoft/live-share-react 1.0.0-preview.5

package/src/live-hooks/useLiveTimer.ts

@@ -0,0 +1,184 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    ITimerConfig,
+    LiveTimerEvents,
+    UserMeetingRole,
+    LiveTimer,
+} from "@microsoft/live-share";
+import React from "react";
+import {
+    IUseLiveTimerResults,
+    OnPauseTimerAction,
+    OnPlayTimerAction,
+    OnStartTimerAction,
+    OnTimerDidFinishAction,
+    OnTimerDidPauseAction,
+    OnTimerDidPlayAction,
+    OnTimerDidStartAction,
+    OnTimerTickAction,
+} from "../types";
+import { useDynamicDDS } from "../shared-hooks";
+
+export function useLiveTimer(
+    uniqueKey: string,
+    allowedRoles?: UserMeetingRole[],
+    tickRate?: number,
+    onTick?: OnTimerTickAction,
+    onStart?: OnTimerDidStartAction,
+    onPause?: OnTimerDidPauseAction,
+    onPlay?: OnTimerDidPlayAction,
+    onFinish?: OnTimerDidFinishAction,
+): IUseLiveTimerResults {
+    /**
+     * User facing: Stateful timer config.
+     */
+    const [timerConfig, setTimerConfig] = React.useState<ITimerConfig>();
+    /**
+     * User facing: Stateful time remaining.
+     */
+    const [milliRemaining, setMilliRemaining] = React.useState<number>();
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    const { dds: liveTimer } = useDynamicDDS<LiveTimer>(uniqueKey, LiveTimer);
+
+    /**
+     * User facing: callback to send event through `LiveTimer`
+     */
+    const start: OnStartTimerAction = React.useCallback(
+        (duration: number): void => {
+            if (liveTimer?.isInitialized === undefined) {
+                console.error(
+                    new Error("Cannot call start when liveTimer is undefined")
+                );
+                return;
+            }
+            if (!liveTimer.isInitialized) {
+                console.error(
+                    new Error(
+                        "Cannot call start while liveTimer is not started"
+                    )
+                );
+                return;
+            }
+            liveTimer?.start(duration);
+        },
+        [liveTimer?.isInitialized]
+    );
+
+    /**
+     * User facing: callback to send event through `LiveTimer`
+     */
+    const play: OnPlayTimerAction = React.useCallback((): void => {
+        if (liveTimer?.isInitialized === undefined) {
+            console.error(
+                new Error("Cannot call play when liveTimer is undefined")
+            );
+            return;
+        }
+        if (!liveTimer.isInitialized) {
+            console.error(
+                new Error("Cannot call play while liveTimer is not started")
+            );
+            return;
+        }
+        liveTimer?.play();
+    }, [liveTimer?.isInitialized]);
+
+    /**
+     * User facing: callback to send event through `LiveTimer`
+     */
+    const pause: OnPauseTimerAction = React.useCallback((): void => {
+        if (liveTimer?.isInitialized === undefined) {
+            console.error(
+                new Error("Cannot call pause when liveTimer is undefined")
+            );
+            return;
+        }
+        if (!liveTimer.isInitialized) {
+            console.error(
+                new Error("Cannot call pause while liveTimer is not started")
+            );
+            return;
+        }
+        liveTimer?.pause();
+    }, [liveTimer?.isInitialized]);
+
+    /**
+     * Setup change listeners and start `LiveTimer` if needed
+     */
+    React.useEffect(() => {
+        if (liveTimer === undefined)
+            return;
+        // Register event listeners
+        const onTimerConfigChange = (config: ITimerConfig) => {
+            setTimerConfig(config);
+        };
+        const onDidStart = (config: ITimerConfig) => {
+            onTimerConfigChange(config);
+            onStart?.(config);
+            setMilliRemaining(config.duration);
+        };
+        const onDidFinish = (config: ITimerConfig) => {
+            onTimerConfigChange(config);
+            onFinish?.(config);
+            setMilliRemaining(0);
+        };
+        const onDidPlay = (config: ITimerConfig) => {
+            onTimerConfigChange(config);
+            onPlay?.(config);
+        };
+        const onDidPause = (config: ITimerConfig) => {
+            onTimerConfigChange(config);
+            onPause?.(config);
+        };
+        const onDidTick = (milliseconds: number) => {
+            setMilliRemaining(milliseconds);
+            onTick?.(milliseconds);
+        };
+        liveTimer.on(LiveTimerEvents.started, onDidStart);
+        liveTimer.on(LiveTimerEvents.finished, onDidFinish);
+        liveTimer.on(LiveTimerEvents.played, onDidPlay);
+        liveTimer.on(LiveTimerEvents.paused, onDidPause);
+        liveTimer.on(LiveTimerEvents.onTick, onDidTick);
+        if (!liveTimer.isInitialized) {
+            // Start live event
+            liveTimer.initialize(allowedRoles);
+        }
+
+        return () => {
+            // on unmount, remove event listeners
+            liveTimer?.off(LiveTimerEvents.started, onDidStart);
+            liveTimer?.off(LiveTimerEvents.finished, onDidFinish);
+            liveTimer?.off(LiveTimerEvents.played, onDidPlay);
+            liveTimer?.off(LiveTimerEvents.paused, onDidPause);
+            liveTimer?.off(LiveTimerEvents.onTick, onDidTick);
+        };
+    }, [liveTimer, onTick, onStart, onFinish, onPlay, onPause]);
+
+    /**
+     * Change tick rate if changes in props
+     */
+    React.useEffect(() => {
+        if (
+            tickRate !== undefined &&
+            liveTimer?.tickRate !== undefined &&
+            tickRate !== liveTimer?.tickRate
+        ) {
+            liveTimer.tickRate = tickRate;
+        }
+    }, [tickRate, liveTimer?.tickRate]);
+
+    return {
+        liveTimer,
+        milliRemaining,
+        pause,
+        play,
+        start,
+        timerConfig,
+    };
+}

package/src/live-hooks/useMediaSynchronizer.ts

@@ -0,0 +1,200 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { UserMeetingRole } from "@microsoft/live-share";
+import React from "react";
+import {
+    CoordinationWaitPoint,
+    ExtendedMediaMetadata,
+    IMediaPlayer,
+    LiveMediaSession,
+    MediaPlayerSynchronizer,
+    MediaSessionCoordinatorSuspension,
+} from "@microsoft/live-share-media";
+import { isExtendedMediaMetadata, isMediaElement, isRefObject } from "../utils";
+import { useDynamicDDS } from "../shared-hooks";
+import { IUseMediaSynchronizerResults } from "../types";
+
+/**
+ * React hook for using a Live Share media `MediaPlayerSynchronizer`.
+ *
+ * @remarks
+ * Use this hook if you want to synchronize the playback position of a video or audio element during a Live Share session.
+ *
+ * @param uniqueKey uniqueKey value for the `LiveMediaSession` DDS object used by `MediaPlayerSynchronizer`.
+ * @param mediaPlayerElementRef React RefObject containing object/element conforming to IMediaPlayer interface or string id for <video> / <audio> element.
+ * @param initialTrack initial track to load. Either ExtendedMediaMetadata, trackId string, or null.
+ * @param allowedRoles Optional. Array of user roles that are eligible to modify group playback state.
+ * @param viewOnly Optional. Flag for whether or not the media synchronizer should be in viewOnly mode.
+ * @returns IUseMediaSynchronizerResults object.
+ */
+export function useMediaSynchronizer(
+    uniqueKey: string,
+    mediaPlayerElementRef: React.RefObject<IMediaPlayer> | string,
+    initialTrack: Partial<ExtendedMediaMetadata> | string | null,
+    allowedRoles?: UserMeetingRole[],
+    viewOnly?: boolean
+): IUseMediaSynchronizerResults {
+    /**
+     * User facing media synchronizer and non-user facing setter
+     */
+    const [mediaSynchronizer, setMediaSynchronizer] = React.useState<
+        MediaPlayerSynchronizer | undefined
+    >();
+    /**
+     * Suspension object and setter
+     */
+    const [suspension, setSuspension] = React.useState<
+        MediaSessionCoordinatorSuspension | undefined
+    >();
+    /**
+     * User facing: dynamically load the LiveMediaSession DDS for the given unique key.
+     */
+    const { dds: mediaSession } = useDynamicDDS<LiveMediaSession>(uniqueKey, LiveMediaSession);
+
+    /**
+     * User facing: play callback
+     */
+    const play = React.useCallback((): void => {
+        mediaSynchronizer?.play();
+    }, [mediaSynchronizer]);
+
+    /**
+     * User facing: pause callback
+     */
+    const pause = React.useCallback((): void => {
+        mediaSynchronizer?.pause();
+    }, [mediaSynchronizer]);
+
+    /**
+     * User facing: seek callback
+     */
+    const seekTo = React.useCallback(
+        (time: number): void => {
+            mediaSynchronizer?.seekTo(time);
+        },
+        [mediaSynchronizer]
+    );
+
+    /**
+     * User facing: set track callback
+     */
+    const setTrack = React.useCallback(
+        (track: Partial<ExtendedMediaMetadata> | string | null): void => {
+            // TODO: fix force unwrap once synchronizer uses correct types
+            if (isExtendedMediaMetadata(track)) {
+                mediaSynchronizer!.setTrack(track);
+            } else if (typeof track === "string") {
+                mediaSynchronizer!.setTrack({
+                    trackIdentifier: track,
+                } as ExtendedMediaMetadata);
+            }
+        },
+        [mediaSynchronizer]
+    );
+
+    /**
+     * User facing: create a new suspension and set it locally to state
+     */
+    const beginSuspension = React.useCallback(
+        (waitPoint?: CoordinationWaitPoint) => {
+            const suspension =
+                mediaSession?.coordinator.beginSuspension(waitPoint);
+            setSuspension(suspension);
+        },
+        [mediaSession]
+    );
+
+    /**
+     * User facing: if a suspension is active, end it. Called when "Follow presenter" button is clicked.
+     */
+    const endSuspension = React.useCallback(() => {
+        suspension?.end();
+        setSuspension(undefined);
+    }, [suspension]);
+
+    /**
+     * Setup change listeners and start `LiveMediaSession` if needed
+     */
+    React.useEffect(() => {
+        if (mediaSession === undefined || !mediaPlayerElementRef)
+            return;
+        // Query the HTML5 media element from the document and set reference
+        let mediaPlayer: IMediaPlayer | undefined;
+        if (isRefObject<IMediaPlayer>(mediaPlayerElementRef)) {
+            if (!mediaPlayerElementRef.current) return;
+            mediaPlayer = mediaPlayerElementRef.current;
+        } else {
+            const mediaPlayerElement = document.getElementById(
+                mediaPlayerElementRef
+            ) as any;
+            if (!isMediaElement(mediaPlayerElement)) return;
+            mediaPlayer = mediaPlayerElement;
+        }
+        if (initialTrack) {
+            // If supported type and not null, set the initial src
+            if (isExtendedMediaMetadata(initialTrack)) {
+                mediaPlayer.src = initialTrack.trackIdentifier;
+            } else if (typeof initialTrack === "string") {
+                mediaPlayer.src = initialTrack;
+            }
+        }
+        // Begin synchronizing a MediaSynchronizer for the player
+        const synchronizer = mediaSession.synchronize(mediaPlayer);
+        if (viewOnly !== undefined) {
+            // Set synchronizer to view only mode provided by developer
+            synchronizer.viewOnly = viewOnly;
+        }
+
+        if (!mediaSession.isInitialized) {
+            // Start synchronizing the media session
+            mediaSession.initialize(allowedRoles ?? []);
+        } else if (initialTrack) {
+            // If we have already started the media session, the synchronizer won't have initial track
+            // data now that we are remounting.
+            // TODO: if player is loaded twice in one app at once, then this has a chance to disrupt the
+            // group state by resetting the track. MediaPlayerSynchronizer does not currently have a way to
+            // get the current track, so to fix this we need a better solution.
+            if (isExtendedMediaMetadata(initialTrack)) {
+                synchronizer.setTrack(initialTrack);
+            } else if (typeof initialTrack === "string") {
+                synchronizer.setTrack({
+                    trackIdentifier: initialTrack,
+                } as ExtendedMediaMetadata);
+            }
+        }
+        setMediaSynchronizer(synchronizer);
+
+        return () => {
+            synchronizer.removeAllListeners();
+            mediaSession.removeAllListeners();
+            synchronizer?.end();
+        };
+    }, [mediaSession]);
+
+    /**
+     * Change view in media synchronizer only if prop changes
+     */
+    React.useEffect(() => {
+        if (
+            mediaSynchronizer?.viewOnly !== undefined &&
+            viewOnly !== undefined &&
+            mediaSynchronizer.viewOnly !== viewOnly
+        ) {
+            mediaSynchronizer.viewOnly = !!viewOnly;
+        }
+    }, [viewOnly, mediaSynchronizer?.viewOnly]);
+
+    return {
+        suspended: !!suspension,
+        mediaSynchronizer,
+        play,
+        pause,
+        seekTo,
+        setTrack,
+        beginSuspension,
+        endSuspension,
+    };
+}

package/src/providers/AzureProvider.tsx

@@ -0,0 +1,177 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    IFluidContainer,
+    LoadableObjectClassRecord,
+} from "fluid-framework";
+import React from "react";
+import {
+    AzureClientProps,
+    AzureContainerServices,
+} from "@fluidframework/azure-client";
+import { IAzureContainerResults } from "../types";
+import {
+    ISharedStateRegistryResponse,
+    useSharedStateRegistry,
+} from "../internal-hooks";
+import {
+    AzureTurboClient,
+    IFluidTurboClient,
+} from "@microsoft/live-share-turbo";
+
+interface IFluidContext extends ISharedStateRegistryResponse {
+    clientRef: React.MutableRefObject<IFluidTurboClient>;
+    container: IFluidContainer | undefined;
+    services: AzureContainerServices | undefined;
+    joinError: Error | undefined;
+    getContainer: (
+        containerId: string,
+        initialObjects?: LoadableObjectClassRecord
+    ) => Promise<IAzureContainerResults>;
+    createContainer: (
+        initialObjects?: LoadableObjectClassRecord,
+        onInitializeContainer?: (container: IFluidContainer) => void
+    ) => Promise<IAzureContainerResults>;
+}
+
+export const FluidContext = React.createContext<IFluidContext>(
+    {} as IFluidContext
+);
+
+export const useFluidObjectsContext = (): IFluidContext => {
+    const context = React.useContext(FluidContext);
+    return context;
+};
+
+interface IAzureProviderProps {
+    children?: React.ReactNode;
+    clientOptions: AzureClientProps;
+    containerId?: string;
+    createOnLoad?: boolean;
+    initialObjects?: LoadableObjectClassRecord;
+    joinOnLoad?: boolean;
+}
+
+/**
+ * React Context provider component for using Fluid data objects & joining/creating a Fluid document `AzureClient`.
+ */
+export const AzureProvider: React.FC<IAzureProviderProps> = (
+    props
+) => {
+    const startedRef = React.useRef<boolean>(false);
+    const clientRef = React.useRef<AzureTurboClient>(
+        new AzureTurboClient(props.clientOptions)
+    );
+    const [results, setResults] = React.useState<
+        IAzureContainerResults | undefined
+    >();
+    const [joinError, setJoinError] = React.useState<Error | undefined>();
+
+    const stateRegistryCallbacks = useSharedStateRegistry(results);
+
+    /**
+     * Get the container for a given containerId using AzureClient
+     */
+    const getContainer = React.useCallback(
+        async (
+            containerId: string,
+            initialObjects?: LoadableObjectClassRecord
+        ): Promise<IAzureContainerResults> => {
+            return new Promise(async (resolve, reject) => {
+                try {
+                    const results: IAzureContainerResults =
+                        await clientRef.current.getContainer(
+                            containerId,
+                            initialObjects
+                        );
+                    setResults(results);
+                    resolve(results);
+                } catch (error: any) {
+                    if (error instanceof Error) {
+                        setJoinError(error);
+                    }
+                    reject(error);
+                }
+            });
+        },
+        [props.containerId, setResults]
+    );
+
+    /**
+     * Create container callback to create a new container using AzureClient
+     */
+    const createContainer = React.useCallback(
+        async (
+            initialObjects?: LoadableObjectClassRecord,
+            onInitializeContainer?: (container: IFluidContainer) => void
+        ): Promise<IAzureContainerResults> => {
+            return new Promise(async (resolve, reject) => {
+                try {
+                    const results: IAzureContainerResults =
+                        await clientRef.current.createContainer(initialObjects);
+                    if (onInitializeContainer) {
+                        onInitializeContainer(results.container);
+                    }
+                    const containerId = await results.container.attach();
+                    window.location.hash = containerId;
+                    setResults(results);
+                    resolve(results);
+                } catch (error: any) {
+                    if (error instanceof Error) {
+                        setJoinError(error);
+                    }
+                    reject(error);
+                }
+            });
+        },
+        [props.containerId, setResults]
+    );
+
+    /**
+     * Joins a container if `props.joinOnLoad` is true and `props.containerId` is known. Creates a new container if `props.createOnLoad` is true
+     * and `props.containerId` is not known.
+     */
+    React.useEffect(() => {
+        // This hook should only be called once, so we use a ref to track if it has been called.
+        // This is a workaround for the fact that useEffect is called twice on initial render in React V18.
+        // We are not doing this here for backwards compatibility. View the README for more information.
+        if (
+            results?.container?.connectionState !== undefined ||
+            startedRef.current
+        )
+            return;
+        startedRef.current = true;
+        if (props.containerId && props.joinOnLoad) {
+            getContainer(props.containerId, props.initialObjects);
+        } else if (!props.containerId && props.createOnLoad) {
+            createContainer(props.initialObjects);
+        }
+    }, [
+        results?.container?.connectionState,
+        props.containerId,
+        props.createOnLoad,
+        props.joinOnLoad,
+        props.initialObjects,
+        getContainer,
+        createContainer,
+    ]);
+
+    return (
+        <FluidContext.Provider
+            value={{
+                clientRef,
+                container: results?.container,
+                services: results?.services,
+                joinError,
+                createContainer,
+                getContainer,
+                ...stateRegistryCallbacks,
+            }}
+        >
+            {props.children}
+        </FluidContext.Provider>
+    );
+};

package/src/providers/LiveShareProvider.tsx

@@ -0,0 +1,140 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { IFluidContainer, LoadableObjectClassRecord } from "fluid-framework";
+import React from "react";
+import { ILiveShareContainerResults } from "../types";
+import { useSharedStateRegistry } from "../internal-hooks";
+import { ILiveShareClientOptions, ILiveShareHost } from "@microsoft/live-share";
+import { FluidContext } from "./AzureProvider";
+import { LiveShareTurboClient } from "@microsoft/live-share-turbo";
+
+interface ILiveShareContext {
+    created: boolean | undefined;
+    join: (
+        initialObjects?: LoadableObjectClassRecord,
+        onInitializeContainer?: (container: IFluidContainer) => void
+    ) => Promise<ILiveShareContainerResults>;
+}
+
+export const LiveShareContext = React.createContext<ILiveShareContext>(
+    {} as ILiveShareContext
+);
+
+export const useLiveShareContext = (): ILiveShareContext => {
+    const context = React.useContext(LiveShareContext);
+    return context;
+};
+
+interface ILiveShareProviderProps {
+    /**
+     * Optional. React children node for the React Context Provider
+     */
+    children?: React.ReactNode;
+    /**
+     * Optional. Options to pass into LiveShareClient initializer
+     */
+    clientOptions?: ILiveShareClientOptions;
+    /**
+     * Host to initialize LiveShareClient with
+     */
+    host: ILiveShareHost;
+    /**
+     * Optional. Initial Fluid objects to load when the container is first created
+     */
+    initialObjects?: LoadableObjectClassRecord;
+    /**
+     * Optional. Flag to determine whether to join Fluid container on load
+     */
+    joinOnLoad?: boolean;
+}
+
+/**
+ * React Context provider component for using Live Share data objects & joining a Live Share session using `LiveShareClient`.
+ */
+export const LiveShareProvider: React.FC<
+    ILiveShareProviderProps
+> = (props) => {
+    const startedRef = React.useRef(false);
+    const clientRef = React.useRef(
+        new LiveShareTurboClient(props.host, props.clientOptions)
+    );
+    const [results, setResults] = React.useState<
+        ILiveShareContainerResults | undefined
+    >();
+    const [joinError, setJoinError] = React.useState<Error | undefined>();
+
+    const stateRegistryCallbacks = useSharedStateRegistry(results);
+
+    /**
+     * Join container callback for joining the Live Share session
+     */
+    const join = React.useCallback(
+        async (
+            initialObjects?: LoadableObjectClassRecord,
+            onInitializeContainer?: (container: IFluidContainer) => void
+        ): Promise<ILiveShareContainerResults> => {
+            startedRef.current = true;
+            const results: ILiveShareContainerResults =
+                await clientRef.current.join(initialObjects, onInitializeContainer);
+            setResults(results);
+            return results;
+        },
+        []
+    );
+
+    /**
+     * Joins the container on load if `props.joinOnLoad` is true
+     */
+    React.useEffect(() => {
+        // This hook should only be called once, so we use a ref to track if it has been called.
+        // This is a workaround for the fact that useEffect is called twice on initial render in React V18.
+        // We are not doing this here for backwards compatibility. View the README for more information.
+        if (results !== undefined || startedRef.current || !props.joinOnLoad) return;
+        join(props.initialObjects).catch((error) => {
+            console.log(error);
+            if (error instanceof Error) {
+                setJoinError(error);
+            } else {
+                setJoinError(
+                    new Error(
+                        "LiveShareProvider: An unknown error occurred while joining container."
+                    )
+                );
+            }
+        });
+    }, [results, props.joinOnLoad, props.initialObjects, join]);
+
+    return (
+        <LiveShareContext.Provider
+            value={{
+                created: results?.created,
+                join,
+            }}
+        >
+            <FluidContext.Provider
+                value={{
+                    clientRef,
+                    container: results?.container,
+                    services: results?.services,
+                    joinError,
+                    getContainer: async () => {
+                        throw new Error(
+                            "Cannot join new container through getContainer in LiveShareProvider"
+                        );
+                    },
+                    createContainer: async () => {
+                        throw new Error(
+                            "Cannot create new container through createContainer in LiveShareProvider"
+                        );
+                    },
+                    ...stateRegistryCallbacks,
+                }}
+            >
+                {props.children}
+            </FluidContext.Provider>
+        </LiveShareContext.Provider>
+    );
+};

package/src/providers/index.ts

@@ -0,0 +1,2 @@
+export * from "./AzureProvider";
+export * from "./LiveShareProvider";