@microsoft/live-share-react 1.0.0-preview.11 → 1.0.0-preview.13

package/src/live-hooks/useLiveState.ts

@@ -18,15 +18,15 @@ import { useDynamicDDS } from "../shared-hooks";
  * @param initialState Optional. the initial state value of type TState
  * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
  * @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 = any,
->(
+export function useLiveState<TState = any>(
     uniqueKey: string,
     initialState: TState,
     allowedRoles?: UserMeetingRole[]
 ): [TState, SetLiveStateAction<TState>] {
-    const [currentState, setCurrentState] = React.useState<TState>(initialState);
+    const [currentState, setCurrentState] =
+        React.useState<TState>(initialState);
     /**
      * User facing: dynamically load the DDS for the given unique key.
      */
@@ -37,9 +37,11 @@ export function useLiveState<
 
     /**
      * 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 setState = React.useCallback(
-        (state: TState) => {
+        async (state: TState) => {
             if (!liveState) {
                 console.error(
                     new Error(
@@ -56,7 +58,7 @@ export function useLiveState<
                 );
                 return;
             }
-            liveState.set(state);
+            return await liveState.set(state);
         },
         [liveState]
     );

package/src/live-hooks/useLiveTimer.ts

@@ -31,7 +31,7 @@ export function useLiveTimer(
     onStart?: OnTimerDidStartAction,
     onPause?: OnTimerDidPauseAction,
     onPlay?: OnTimerDidPlayAction,
-    onFinish?: OnTimerDidFinishAction,
+    onFinish?: OnTimerDidFinishAction
 ): IUseLiveTimerResults {
     /**
      * User facing: Stateful timer config.
@@ -47,11 +47,13 @@ export function useLiveTimer(
     const { dds: liveTimer } = useDynamicDDS<LiveTimer>(uniqueKey, LiveTimer);
 
     /**
-     * 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) {
+        async (duration: number) => {
+            if (liveTimer === undefined) {
                 console.error(
                     new Error("Cannot call start when liveTimer is undefined")
                 );
@@ -65,16 +67,17 @@ export function useLiveTimer(
                 );
                 return;
             }
-            liveTimer?.start(duration);
+            return await liveTimer.start(duration);
         },
-        [liveTimer?.isInitialized]
+        [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) {
+    const play: OnPlayTimerAction = React.useCallback(async () => {
+        if (liveTimer === undefined) {
             console.error(
                 new Error("Cannot call play when liveTimer is undefined")
             );
@@ -86,14 +89,15 @@ export function useLiveTimer(
             );
             return;
         }
-        liveTimer?.play();
-    }, [liveTimer?.isInitialized]);
+        return await liveTimer.play();
+    }, [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) {
+    const pause: OnPauseTimerAction = React.useCallback(async () => {
+        if (liveTimer === undefined) {
             console.error(
                 new Error("Cannot call pause when liveTimer is undefined")
             );
@@ -105,15 +109,14 @@ export function useLiveTimer(
             );
             return;
         }
-        liveTimer?.pause();
-    }, [liveTimer?.isInitialized]);
+        return await liveTimer.pause();
+    }, [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

@@ -52,28 +52,34 @@ 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
+    );
 
     /**
-     * User facing: play callback
+     * Play callback
      */
-    const play = React.useCallback((): void => {
-        mediaSynchronizer?.play();
+    const play = React.useCallback(async () => {
+        if (!mediaSynchronizer) return;
+        return await mediaSynchronizer.play();
     }, [mediaSynchronizer]);
 
     /**
-     * User facing: pause callback
+     * Pause callback
      */
-    const pause = React.useCallback((): void => {
-        mediaSynchronizer?.pause();
+    const pause = React.useCallback(async () => {
+        if (!mediaSynchronizer) return;
+        return await mediaSynchronizer.pause();
     }, [mediaSynchronizer]);
 
     /**
      * User facing: seek callback
      */
     const seekTo = React.useCallback(
-        (time: number): void => {
-            mediaSynchronizer?.seekTo(time);
+        async (time: number) => {
+            if (!mediaSynchronizer) return;
+            return await mediaSynchronizer.seekTo(time);
         },
         [mediaSynchronizer]
     );
@@ -82,12 +88,12 @@ export function useMediaSynchronizer(
      * 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 (!mediaSynchronizer) return;
             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);
             }
@@ -119,8 +125,8 @@ export function useMediaSynchronizer(
      * Setup change listeners and start `LiveMediaSession` if needed
      */
     React.useEffect(() => {
-        if (mediaSession === undefined || !mediaPlayerElementRef)
-            return;
+        if (mediaSession === undefined || !mediaPlayerElementRef) return;
+        let mounted = true;
         // Query the HTML5 media element from the document and set reference
         let mediaPlayer: IMediaPlayer | undefined;
         if (isRefObject<IMediaPlayer>(mediaPlayerElementRef)) {
@@ -152,25 +158,29 @@ 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]);
 

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,
@@ -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 {
+    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/useDynamicDDS.ts

@@ -16,10 +16,12 @@ import { LoadableObjectClass } from "fluid-framework";
  * @param onFirstInitialize Optional. Callback function for when the DDS is first loaded
  * @returns the DDS object, which is of type T when loaded and undefined while loading
  */
-export function useDynamicDDS<T extends IFluidLoadable = FluidObject<any> & IFluidLoadable>(
+export function useDynamicDDS<
+    T extends IFluidLoadable = FluidObject<any> & IFluidLoadable
+>(
     uniqueKey: string,
     loadableObjectClass: LoadableObjectClass<T>,
-    onFirstInitialize?: (dds: T) => void,
+    onFirstInitialize?: (dds: T) => void
 ): {
     dds: T | undefined;
     error: Error | undefined;
@@ -29,10 +31,7 @@ export function useDynamicDDS<T extends IFluidLoadable = FluidObject<any> & IFlu
     /**
      * Import container and DDS object register callbacks from AzureProvider.
      */
-    const {
-        container,
-        clientRef,
-    } = useFluidObjectsContext();
+    const { container, clientRef } = useFluidObjectsContext();
 
     /**
      * Once container is available, this effect will register the setter method so that the DDS loaded
@@ -46,7 +45,11 @@ export function useDynamicDDS<T extends IFluidLoadable = FluidObject<any> & IFlu
         // Callback method to set the `initialData` into the map when the DDS is first created.
         const onGetDDS = async () => {
             try {
-                const dds = await clientRef.current.getDDS<T>(uniqueKey, loadableObjectClass, onFirstInitialize);
+                const dds = await clientRef.current.getDDS<T>(
+                    uniqueKey,
+                    loadableObjectClass,
+                    onFirstInitialize
+                );
                 if (mounted) {
                     setDDS(dds);
                 }
@@ -54,7 +57,11 @@ export function useDynamicDDS<T extends IFluidLoadable = FluidObject<any> & IFlu
                 if (error instanceof Error) {
                     setError(error);
                 } else {
-                    setError(new Error("useDynamicDDS: an unknown error occurred while getting the DDS"));
+                    setError(
+                        new Error(
+                            "useDynamicDDS: an unknown error occurred while getting the DDS"
+                        )
+                    );
                 }
             }
         };

package/src/shared-hooks/useSharedMap.ts

@@ -35,19 +35,26 @@ export function useSharedMap<TData extends object = object>(
         getInitialData<TData>(initialData)
     );
 
-    const onFirstInitialize = React.useCallback((newDDS: SharedMap): void => {
-        /**
-         * Callback method to set the `initialData` into the map when the `SharedMap` is first created.
-         * Only should be used as a prop to useDynamicDDS.
-         */
-        getInitialData(initialData).forEach((value, key) => {
-            newDDS.set(key, value);
-        });
-    }, [initialData]);
+    const onFirstInitialize = React.useCallback(
+        (newDDS: SharedMap): void => {
+            /**
+             * Callback method to set the `initialData` into the map when the `SharedMap` is first created.
+             * Only should be used as a prop to useDynamicDDS.
+             */
+            getInitialData(initialData).forEach((value, key) => {
+                newDDS.set(key, value);
+            });
+        },
+        [initialData]
+    );
     /**
      * User facing: dynamically load the SharedMap DDS for the given unique key.
      */
-    const { dds: sharedMap } = useDynamicDDS<SharedMap>(uniqueKey, SharedMap, onFirstInitialize);
+    const { dds: sharedMap } = useDynamicDDS<SharedMap>(
+        uniqueKey,
+        SharedMap,
+        onFirstInitialize
+    );
 
     /**
      * User facing: set a value to the Fluid `SharedMap`.

package/src/shared-hooks/useSharedState.ts

@@ -79,7 +79,11 @@ export function useSharedState<S>(
         return () => {
             unregisterSharedSetStateAction(uniqueKey, componentIdRef.current);
         };
-    }, [uniqueKey, registerSharedSetStateAction, unregisterSharedSetStateAction]);
+    }, [
+        uniqueKey,
+        registerSharedSetStateAction,
+        unregisterSharedSetStateAction,
+    ]);
 
     return [localState, setSharedState, disposeSharedState];
 }

package/src/types/ActionTypes.ts

@@ -6,13 +6,19 @@
 import React from "react";
 import { IFluidLoadable } from "@fluidframework/core-interfaces";
 import { LoadableObjectClass } from "fluid-framework";
-import { ITimerConfig, PresenceState } from "@microsoft/live-share";
+import { ITimerConfig, ILiveEvent, PresenceState } from "@microsoft/live-share";
 
 // React actions
+
 export type SetSharedStateAction<T> = (state: T) => void;
 export type SetLocalStateAction = React.Dispatch<React.SetStateAction<any>>;
 
 // Fluid actions
+
+/**
+ * Callback for UnregisterDDSSetStateAction.
+ * <T extends IFluidLoadable>(uniqueKey: string, componentId: string, objectClass: LoadableObjectClass<T>, setLocalStateAction: SetLocalStateAction, onDidFirstInitialize?: (dds: T) => void) => void
+ */
 export type RegisterDDSSetStateAction = <T extends IFluidLoadable>(
     uniqueKey: string,
     componentId: string,
@@ -21,55 +27,127 @@ export type RegisterDDSSetStateAction = <T extends IFluidLoadable>(
     onDidFirstInitialize?: (dds: T) => void
 ) => void;
 
+/**
+ * Callback for UnregisterDDSSetStateAction.
+ * (uniqueKey: string, componentId: string) => void
+ */
 export type UnregisterDDSSetStateAction = (
     uniqueKey: string,
     componentId: string
 ) => void;
 
+/**
+ * Callback for RegisterSharedSetStateAction.
+ * (uniqueKey: string, componentId: string, setLocalStateAction: SetLocalStateAction) => void
+ */
 export type RegisterSharedSetStateAction = (
     uniqueKey: string,
     componentId: string,
     setLocalStateAction: SetLocalStateAction
 ) => void;
 
+/**
+ * Callback for UnregisterSharedSetStateAction.
+ * (uniqueKey: string, componentId: string) => void
+ */
 export type UnregisterSharedSetStateAction = (
     uniqueKey: string,
     componentId: string
 ) => void;
 
+/**
+ * Callback for UpdateSharedStateAction.
+ * (uniqueKey: string, value: any) => void
+ */
 export type UpdateSharedStateAction = (uniqueKey: string, value: any) => void;
 
+/**
+ * Callback for DeleteSharedStateAction.
+ * (uniqueKey: string) => void
+ */
 export type DeleteSharedStateAction = (uniqueKey: string) => void;
+/**
+ * Callback for DisposeSharedStateAction.
+ * () => void
+ */
 export type DisposeSharedStateAction = () => void;
 
 // Live Share actions
 
+/**
+ * Callback for SetLiveStateAction<TState = undefined>.
+ * (state: TState) => Promise<void>
+ */
 export type SetLiveStateAction<TState = undefined> = (
-    state: TState,
-) => void;
+    state: TState
+) => Promise<void>;
 
-export type SendLiveEventAction<TEvent> = (event: TEvent) => void;
+/**
+ * Callback for SendLiveEventAction<TEvent>.
+ * (event: TEvent) => Promise<void>
+ */
+export type SendLiveEventAction<TEvent> = (
+    event: TEvent
+) => Promise<ILiveEvent<TEvent>>;
 
+/**
+ * Callback for OnReceivedLiveEventAction<TEvent>.
+ * (event: TEvent, local: boolean) => void
+ */
 export type OnReceivedLiveEventAction<TEvent> = (
     event: TEvent,
     local: boolean
 ) => void;
 
+/**
+ * Callback for OnUpdateLivePresenceAction<TData extends object = object>.
+ * (data?: TData | undefined, state?: PresenceState | undefined) => Promise<void>
+ */
 export type OnUpdateLivePresenceAction<TData extends object = object> = (
     data?: TData | undefined,
-    state?: PresenceState | undefined,
-) => void;
+    state?: PresenceState | undefined
+) => Promise<void>;
 
-export type OnStartTimerAction = (
-    duration: number
-) => void;
+/**
+ * Callback for OnStartTimerAction.
+ * (duration: number) => Promise<void>
+ */
+export type OnStartTimerAction = (duration: number) => Promise<void>;
 
-export type OnPlayTimerAction = () => void;
+/**
+ * Callback for OnPlayTimerAction.
+ * () => Promise<void>
+ */
+export type OnPlayTimerAction = () => Promise<void>;
 
-export type OnPauseTimerAction = () => void;
+/**
+ * Callback for OnPauseTimerAction.
+ * () => Promise<void>
+ */
+export type OnPauseTimerAction = () => Promise<void>;
 
+/**
+ * Callback for OnTimerTickAction.
+ * (milliRemaining: number) => void
+ */
 export type OnTimerTickAction = (milliRemaining: number) => void;
+/**
+ * Callback for OnTimerDidStartAction.
+ * (timerConfig: ITimerConfig) => void
+ */
 export type OnTimerDidStartAction = (timerConfig: ITimerConfig) => void;
+/**
+ * Callback for OnTimerDidPauseAction.
+ * (timerConfig: ITimerConfig) => void
+ */
 export type OnTimerDidPauseAction = (timerConfig: ITimerConfig) => void;
+/**
+ * Callback for OnTimerDidPlayAction.
+ * (timerConfig: ITimerConfig) => void
+ */
 export type OnTimerDidPlayAction = (timerConfig: ITimerConfig) => void;
+/**
+ * Callback for OnTimerDidFinishAction.
+ * (timerConfig: ITimerConfig) => void
+ */
 export type OnTimerDidFinishAction = (timerConfig: ITimerConfig) => void;