@microsoft/live-share-react 1.0.0-preview.9 → 1.0.1-preview.1

package/src/live-hooks/useLiveState.ts

@@ -7,14 +7,13 @@ import { LiveState, UserMeetingRole } from "@microsoft/live-share";
 import React from "react";
 import { SetLiveStateAction } from "../types";
 import { useDynamicDDS } from "../shared-hooks";
-
-interface ILiveStateStatus<
-    TState extends string = string,
-    TData extends object = object
-> {
-    state?: TState;
-    data?: TData;
-}
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+    isPrevStateCallback,
+} from "../internal";
 
 /**
  * React hook for using a Live Share `LiveState`.
@@ -24,57 +23,58 @@ interface ILiveStateStatus<
  *
  * @param uniqueKey the unique key for the `LiveEvent`. If one does not yet exist, a new one will be created, otherwise it will use the existing one.
  * @param initialState Optional. the initial state value of type TState
- * @param initialData Optional. the initial data value of type TData
  * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
- * @returns ordered values: first value is the synchronized state value, second is synchronized data value, and third is a setter to change the state/data values.
+ * @returns ordered values: first value is the synchronized state value and the second is a setter to change the state value.
+ * The setter returns a void promise, which will throw if the user does not have the required roles to set.
  */
-export function useLiveState<
-    TState extends string = string,
-    TData extends object = object
->(
+export function useLiveState<TState = any>(
     uniqueKey: string,
-    initialState?: TState,
-    initialData?: TData,
+    initialState: TState,
     allowedRoles?: UserMeetingRole[]
-): [TState | undefined, TData | undefined, SetLiveStateAction<TState, TData>] {
-    const [current, setCurrent] = React.useState<
-        ILiveStateStatus<TState, TData>
-    >({
-        state: initialState,
-        data: initialData,
-    });
+): [TState, SetLiveStateAction<TState>, LiveState<TState> | undefined] {
+    const [currentState, setCurrentState] =
+        React.useState<TState>(initialState);
     /**
      * User facing: dynamically load the DDS for the given unique key.
      */
-    const { dds: liveState } = useDynamicDDS<LiveState<TData>>(
+    const { dds: liveState } = useDynamicDDS<LiveState<TState>>(
         uniqueKey,
-        LiveState<TData>
+        LiveState<TState>
     );
 
+    const { container } = useFluidObjectsContext();
+
     /**
      * Change state callback that is user facing
+     * @param state TState to set
+     * @returns void promise, which will throw if the user does not have the required roles
      */
-    const changeState = React.useCallback(
-        (state: TState, value?: TData | undefined) => {
-            if (!liveState) {
-                console.error(
-                    new Error(
-                        "Cannot call changeState when liveState is undefined"
-                    )
+    const setState = React.useCallback(
+        async (state: TState | ((prevState: TState) => TState)) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "liveState",
+                    "setState"
+                );
+            }
+            if (liveState === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveState",
+                    "setState"
                 );
-                return;
             }
             if (!liveState.isInitialized) {
-                console.error(
-                    new Error(
-                        "Cannot call changeState while liveState is not started"
-                    )
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveState",
+                    "setState"
                 );
-                return;
             }
-            liveState?.changeState(state, value);
+            const valueToSet = isPrevStateCallback<TState>(state)
+                ? state(liveState.state)
+                : state;
+            return await liveState.set(valueToSet);
         },
-        [liveState]
+        [container, liveState]
     );
 
     /**
@@ -83,26 +83,21 @@ export function useLiveState<
     React.useEffect(() => {
         if (liveState === undefined) return;
 
-        const onStateChanged = (state: TState, data: TData | undefined) => {
-            setCurrent({
-                state,
-                data,
-            });
+        const onStateChanged = (state: TState) => {
+            setCurrentState(state);
         };
         liveState.on("stateChanged", onStateChanged);
         if (!liveState.isInitialized) {
-            liveState.initialize(allowedRoles, initialState, initialData);
-            if (liveState.state) {
-                onStateChanged(liveState.state as TState, liveState.data);
-            }
-        } else if (liveState.state) {
-            onStateChanged(liveState.state as TState, liveState.data);
+            liveState.initialize(initialState, allowedRoles);
+        }
+        if (JSON.stringify(liveState.state) !== JSON.stringify(initialState)) {
+            onStateChanged(liveState.state);
         }
 
         return () => {
             liveState?.off("stateChanged", onStateChanged);
         };
-    }, [liveState?.isInitialized]);
+    }, [liveState]);
 
-    return [current?.state, current?.data, changeState];
+    return [currentState, setState, liveState];
 }

package/src/live-hooks/useLiveTimer.ts

@@ -22,6 +22,12 @@ import {
     OnTimerTickAction,
 } from "../types";
 import { useDynamicDDS } from "../shared-hooks";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
 
 export function useLiveTimer(
     uniqueKey: string,
@@ -31,7 +37,7 @@ export function useLiveTimer(
     onStart?: OnTimerDidStartAction,
     onPause?: OnTimerDidPauseAction,
     onPlay?: OnTimerDidPlayAction,
-    onFinish?: OnTimerDidFinishAction,
+    onFinish?: OnTimerDidFinishAction
 ): IUseLiveTimerResults {
     /**
      * User facing: Stateful timer config.
@@ -46,74 +52,77 @@ export function useLiveTimer(
      */
     const { dds: liveTimer } = useDynamicDDS<LiveTimer>(uniqueKey, LiveTimer);
 
+    const { container } = useFluidObjectsContext();
+
     /**
-     * User facing: callback to send event through `LiveTimer`
+     * Callback to send event through `LiveTimer`
+     * @param duration the duration for the timer in milliseconds
+     * @returns void promise that will throw when user does not have required roles
      */
     const start: OnStartTimerAction = React.useCallback(
-        (duration: number): void => {
-            if (liveTimer?.isInitialized === undefined) {
-                console.error(
-                    new Error("Cannot call start when liveTimer is undefined")
+        async (duration: number) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError("liveTimer", "start");
+            }
+            if (liveTimer === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveTimer",
+                    "start"
                 );
-                return;
             }
             if (!liveTimer.isInitialized) {
-                console.error(
-                    new Error(
-                        "Cannot call start while liveTimer is not started"
-                    )
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveTimer",
+                    "start"
                 );
-                return;
             }
-            liveTimer?.start(duration);
+            return await liveTimer.start(duration);
         },
-        [liveTimer?.isInitialized]
+        [container, liveTimer]
     );
 
     /**
-     * User facing: callback to send event through `LiveTimer`
+     * Callback to send event through `LiveTimer`
+     * @returns void promise that will throw when user does not have required roles
      */
-    const play: OnPlayTimerAction = React.useCallback((): void => {
-        if (liveTimer?.isInitialized === undefined) {
-            console.error(
-                new Error("Cannot call play when liveTimer is undefined")
-            );
-            return;
+    const play: OnPlayTimerAction = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError("liveTimer", "play");
+        }
+        if (liveTimer === undefined) {
+            throw new ActionLiveDataObjectUndefinedError("liveTimer", "play");
         }
         if (!liveTimer.isInitialized) {
-            console.error(
-                new Error("Cannot call play while liveTimer is not started")
-            );
-            return;
+            throw new ActionLiveDataObjectInitializedError("liveTimer", "play");
         }
-        liveTimer?.play();
-    }, [liveTimer?.isInitialized]);
+        return await liveTimer.play();
+    }, [container, liveTimer]);
 
     /**
-     * User facing: callback to send event through `LiveTimer`
+     * Callback to send event through `LiveTimer`
+     * @returns void promise that will throw when user does not have required roles
      */
-    const pause: OnPauseTimerAction = React.useCallback((): void => {
-        if (liveTimer?.isInitialized === undefined) {
-            console.error(
-                new Error("Cannot call pause when liveTimer is undefined")
-            );
-            return;
+    const pause: OnPauseTimerAction = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError("liveTimer", "pause");
+        }
+        if (liveTimer === undefined) {
+            throw new ActionLiveDataObjectUndefinedError("liveTimer", "pause");
         }
         if (!liveTimer.isInitialized) {
-            console.error(
-                new Error("Cannot call pause while liveTimer is not started")
+            throw new ActionLiveDataObjectInitializedError(
+                "liveTimer",
+                "pause"
             );
-            return;
         }
-        liveTimer?.pause();
-    }, [liveTimer?.isInitialized]);
+        return await liveTimer.pause();
+    }, [container, liveTimer]);
 
     /**
      * Setup change listeners and start `LiveTimer` if needed
      */
     React.useEffect(() => {
-        if (liveTimer === undefined)
-            return;
+        if (liveTimer === undefined) return;
         // Register event listeners
         const onTimerConfigChange = (config: ITimerConfig) => {
             setTimerConfig(config);

package/src/live-hooks/useMediaSynchronizer.ts

@@ -16,6 +16,11 @@ import {
 import { isExtendedMediaMetadata, isMediaElement, isRefObject } from "../utils";
 import { useDynamicDDS } from "../shared-hooks";
 import { IUseMediaSynchronizerResults } from "../types";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
 
 /**
  * React hook for using a Live Share media `MediaPlayerSynchronizer`.
@@ -24,7 +29,7 @@ import { IUseMediaSynchronizerResults } from "../types";
  * 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 mediaPlayerElement React RefObject containing object/element conforming to IMediaPlayer interface, `IMediaPlayer` object, 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.
@@ -32,7 +37,11 @@ import { IUseMediaSynchronizerResults } from "../types";
  */
 export function useMediaSynchronizer(
     uniqueKey: string,
-    mediaPlayerElementRef: React.RefObject<IMediaPlayer> | string,
+    mediaPlayerElement:
+        | React.RefObject<IMediaPlayer>
+        | IMediaPlayer
+        | string
+        | null,
     initialTrack: Partial<ExtendedMediaMetadata> | string | null,
     allowedRoles?: UserMeetingRole[],
     viewOnly?: boolean
@@ -52,47 +61,99 @@ export function useMediaSynchronizer(
     /**
      * User facing: dynamically load the LiveMediaSession DDS for the given unique key.
      */
-    const { dds: mediaSession } = useDynamicDDS<LiveMediaSession>(uniqueKey, LiveMediaSession);
+    const { dds: mediaSession } = useDynamicDDS<LiveMediaSession>(
+        uniqueKey,
+        LiveMediaSession
+    );
+
+    const { container } = useFluidObjectsContext();
 
     /**
-     * User facing: play callback
+     * Play callback
      */
-    const play = React.useCallback((): void => {
-        mediaSynchronizer?.play();
-    }, [mediaSynchronizer]);
+    const play = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "mediaSynchronizer",
+                "play"
+            );
+        }
+        if (mediaSynchronizer === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "mediaSynchronizer",
+                "play"
+            );
+        }
+        return await mediaSynchronizer.play();
+    }, [container, mediaSynchronizer]);
 
     /**
-     * User facing: pause callback
+     * Pause callback
      */
-    const pause = React.useCallback((): void => {
-        mediaSynchronizer?.pause();
-    }, [mediaSynchronizer]);
+    const pause = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "mediaSynchronizer",
+                "pause"
+            );
+        }
+        if (mediaSynchronizer === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "mediaSynchronizer",
+                "pause"
+            );
+        }
+        return await mediaSynchronizer.pause();
+    }, [container, mediaSynchronizer]);
 
     /**
      * User facing: seek callback
      */
     const seekTo = React.useCallback(
-        (time: number): void => {
-            mediaSynchronizer?.seekTo(time);
+        async (time: number) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "mediaSynchronizer",
+                    "seekTo"
+                );
+            }
+            if (mediaSynchronizer === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "mediaSynchronizer",
+                    "seekTo"
+                );
+            }
+            return await mediaSynchronizer.seekTo(time);
         },
-        [mediaSynchronizer]
+        [container, 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
+        async (track: Partial<ExtendedMediaMetadata> | string | null) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "mediaSynchronizer",
+                    "setTrack"
+                );
+            }
+            if (mediaSynchronizer === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "mediaSynchronizer",
+                    "setTrack"
+                );
+            }
             if (isExtendedMediaMetadata(track)) {
-                mediaSynchronizer!.setTrack(track);
+                return await mediaSynchronizer.setTrack(track);
             } else if (typeof track === "string") {
-                mediaSynchronizer!.setTrack({
+                return await mediaSynchronizer.setTrack({
                     trackIdentifier: track,
                 } as ExtendedMediaMetadata);
             }
         },
-        [mediaSynchronizer]
+        [container, mediaSynchronizer]
     );
 
     /**
@@ -119,18 +180,20 @@ export function useMediaSynchronizer(
      * Setup change listeners and start `LiveMediaSession` if needed
      */
     React.useEffect(() => {
-        if (mediaSession === undefined || !mediaPlayerElementRef)
-            return;
+        if (mediaSession === undefined || !mediaPlayerElement) return;
+        let mounted = true;
         // 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
+        if (isRefObject<IMediaPlayer>(mediaPlayerElement)) {
+            if (!mediaPlayerElement.current) return;
+            mediaPlayer = mediaPlayerElement.current;
+        } else if (typeof mediaPlayerElement === "string") {
+            const mediaElement = document.getElementById(
+                mediaPlayerElement
             ) as any;
-            if (!isMediaElement(mediaPlayerElement)) return;
+            if (!isMediaElement(mediaElement)) return;
+            mediaPlayer = mediaElement;
+        } else {
             mediaPlayer = mediaPlayerElement;
         }
         if (initialTrack) {
@@ -152,27 +215,31 @@ export function useMediaSynchronizer(
             // 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);
-            }
+            mediaSession.onLocalUserAllowed(async () => {
+                if (!mounted) return;
+                try {
+                    if (isExtendedMediaMetadata(initialTrack)) {
+                        await synchronizer.setTrack(initialTrack);
+                    } else if (typeof initialTrack === "string") {
+                        await synchronizer.setTrack({
+                            trackIdentifier: initialTrack,
+                        } as ExtendedMediaMetadata);
+                    }
+                } catch (err) {
+                    console.error(err);
+                }
+            });
         }
         setMediaSynchronizer(synchronizer);
 
         return () => {
+            mounted = false;
             synchronizer.removeAllListeners();
             mediaSession.removeAllListeners();
             synchronizer?.end();
+            mediaSession?.dispose();
         };
-    }, [mediaSession]);
+    }, [mediaSession, mediaPlayerElement]);
 
     /**
      * Change view in media synchronizer only if prop changes

package/src/providers/AzureProvider.tsx

@@ -3,10 +3,7 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-import {
-    IFluidContainer,
-    LoadableObjectClassRecord,
-} from "fluid-framework";
+import { IFluidContainer, LoadableObjectClassRecord } from "fluid-framework";
 import React from "react";
 import {
     AzureClientProps,
@@ -16,7 +13,7 @@ import { IAzureContainerResults } from "../types";
 import {
     ISharedStateRegistryResponse,
     useSharedStateRegistry,
-} from "../internal-hooks";
+} from "../internal";
 import {
     AzureTurboClient,
     IFluidTurboClient,
@@ -58,9 +55,7 @@ interface IAzureProviderProps {
 /**
  * React Context provider component for using Fluid data objects & joining/creating a Fluid document `AzureClient`.
  */
-export const AzureProvider: React.FC<IAzureProviderProps> = (
-    props
-) => {
+export const AzureProvider: React.FC<IAzureProviderProps> = (props) => {
     const startedRef = React.useRef<boolean>(false);
     const clientRef = React.useRef<AzureTurboClient>(
         new AzureTurboClient(props.clientOptions)

package/src/providers/LiveShareProvider.tsx

@@ -5,18 +5,44 @@
 
 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 { useSharedStateRegistry } from "../internal";
+import {
+    ILiveShareClientOptions,
+    ILiveShareHost,
+    ILiveShareJoinResults,
+    ITimestampProvider,
+} from "@microsoft/live-share";
 import { FluidContext } from "./AzureProvider";
 import { LiveShareTurboClient } from "@microsoft/live-share-turbo";
 
-interface ILiveShareContext {
-    created: boolean | undefined;
+export interface ILiveShareContext {
+    /**
+     * True if the local user created the Fluid container
+     */
+    created: boolean;
+    /**
+     * True if connected to the Live Share container
+     */
+    joined: boolean;
+    /**
+     * An error that will be defined if there was a problem joining the container, or undefined if not.
+     */
+    joinError: Error | undefined;
+    /**
+     * Live Share timestamp provider. Can be used to `.getTimestamp()` for a global clock value.
+     * This reference timestamp value should be fairly consistent for all users in the session.
+     */
+    timestampProvider: ITimestampProvider | undefined;
+    /**
+     * Join callback method
+     * @param initialObjects Optional. The initial objects for the Fluid container schema.
+     * @param onInitializeContainer Optional. Callback for when the container is first created.
+     * @returns `ILiveShareJoinResults`, which includes the Fluid container
+     */
     join: (
         initialObjects?: LoadableObjectClassRecord,
         onInitializeContainer?: (container: IFluidContainer) => void
-    ) => Promise<ILiveShareContainerResults>;
+    ) => Promise<ILiveShareJoinResults>;
 }
 
 export const LiveShareContext = React.createContext<ILiveShareContext>(
@@ -54,15 +80,13 @@ interface ILiveShareProviderProps {
 /**
  * React Context provider component for using Live Share data objects & joining a Live Share session using `LiveShareClient`.
  */
-export const LiveShareProvider: React.FC<
-    ILiveShareProviderProps
-> = (props) => {
+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
+        ILiveShareJoinResults | undefined
     >();
     const [joinError, setJoinError] = React.useState<Error | undefined>();
 
@@ -75,10 +99,12 @@ export const LiveShareProvider: React.FC<
         async (
             initialObjects?: LoadableObjectClassRecord,
             onInitializeContainer?: (container: IFluidContainer) => void
-        ): Promise<ILiveShareContainerResults> => {
+        ): Promise<ILiveShareJoinResults> => {
             startedRef.current = true;
-            const results: ILiveShareContainerResults =
-                await clientRef.current.join(initialObjects, onInitializeContainer);
+            const results = await clientRef.current.join(
+                initialObjects,
+                onInitializeContainer
+            );
             setResults(results);
             return results;
         },
@@ -92,9 +118,10 @@ export const LiveShareProvider: React.FC<
         // 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;
+        if (results !== undefined || startedRef.current || !props.joinOnLoad)
+            return;
         join(props.initialObjects).catch((error) => {
-            console.log(error);
+            console.error(error);
             if (error instanceof Error) {
                 setJoinError(error);
             } else {
@@ -110,7 +137,10 @@ export const LiveShareProvider: React.FC<
     return (
         <LiveShareContext.Provider
             value={{
-                created: results?.created,
+                created: !!results?.created,
+                timestampProvider: results?.timestampProvider,
+                joined: !!results?.container,
+                joinError,
                 join,
             }}
         >

package/src/shared-hooks/index.ts

@@ -1,4 +1,3 @@
 export * from "./useSharedState";
 export * from "./useSharedMap";
 export * from "./useDynamicDDS";
-export * from "./useTaskManager";