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

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;

package/src/types/ResultTypes.ts

@@ -75,6 +75,8 @@ export interface IUseLiveEventResults<TEvent extends object = object> {
     allEvents: IReceiveLiveEvent<TEvent>[];
     /**
      * Callback method to send a new event to users in the session.
+     * @param TEvent to send.
+     * @returns void promise that will throw when user does not have required roles
      */
     sendEvent: SendLiveEventAction<TEvent>;
     /**
@@ -97,15 +99,19 @@ export interface IUseLiveTimerResults {
      */
     liveTimer: LiveTimer | undefined;
     /**
-     * Start timer callback.
+     * 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
      */
     start: OnStartTimerAction;
     /**
-     * Play timer callback.
+     * Callback to send event through `LiveTimer`
+     * @returns void promise that will throw when user does not have required roles
      */
     play: OnPlayTimerAction;
     /**
-     * Pause timer callback.
+     * Callback to send event through `LiveTimer`
+     * @returns void promise that will throw when user does not have required roles
      */
     pause: OnPauseTimerAction;
 }
@@ -129,6 +135,9 @@ export interface IUseLivePresenceResults<TData extends object = object> {
     livePresence: LivePresence<TData> | undefined;
     /**
      * Callback method to update the local user's presence.
+     * @param data Optional. TData to set for user.
+     * @param state Optional. PresenceState to set for user.
+     * @returns void promise that will throw when user does not have required roles
      */
     updatePresence: OnUpdateLivePresenceAction<TData>;
 }
@@ -140,23 +149,28 @@ export interface IUseMediaSynchronizerResults {
     suspended: boolean;
     /**
      * Callback to initiate a play action for the group media session.
+     * @returns void promise that will throw when user does not have required roles
      */
-    play: () => void;
+    play: () => Promise<void>;
     /**
      * Callback to initiate a pause action for the group media session.
+     * @returns void promise that will throw when user does not have required roles
      */
-    pause: () => void;
+    pause: () => Promise<void>;
     /**
      * Callback to initiate a seek action for the group media session.
-     *
      * @param time timestamp of the video in seconds to seek to
+     * @returns void promise that will throw when user does not have required roles
      */
-    seekTo: (time: number) => void;
+    seekTo: (time: number) => Promise<void>;
     /**
      * Callback to change the track for the group media session.
      * @param track media metadata object, track src string, or null
+     * @returns void promise that will throw when user does not have required roles
      */
-    setTrack: (track: Partial<ExtendedMediaMetadata> | string | null) => void;
+    setTrack: (
+        track: Partial<ExtendedMediaMetadata> | string | null
+    ) => Promise<void>;
     /**
      * Begin a new suspension. If a wait point is not set, the suspension will only impact the
      * local user.