@microsoft/live-share-react 1.0.0-preview.22 → 1.0.0-preview.24

package/src/live-hooks/useLivePresence.ts

@@ -12,6 +12,12 @@ import {
 import React from "react";
 import { IUseLivePresenceResults, OnUpdateLivePresenceAction } from "../types";
 import { useDynamicDDS } from "../shared-hooks";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
 
 /**
  * React hook for using a Live Share `LivePresence`.
@@ -24,7 +30,7 @@ import { useDynamicDDS } from "../shared-hooks";
  * @template TData Optional typing for the custom user presence data object. Default is `object` type.
  * @param uniqueKey The unique key for `LivePresence`. If one does not yet exist, a new one
  * @param userId Optional. The unique ID for a user. If none is provided, a random UUID will be generated.
- * @param initialData Optional. Initial presence data object for the user.
+ * @param initialData Optional. Initial presence data object for the user. Can be value or a function to get the value.
  * @param initialPresenceState Optional. Initial status of the user's presence. Default is online.
  * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
  * will be created, otherwise it will use the existing one. Default value is ":<dds-default>"
@@ -33,7 +39,7 @@ import { useDynamicDDS } from "../shared-hooks";
  */
 export function useLivePresence<TData extends object = object>(
     uniqueKey: string,
-    initialData?: TData | undefined,
+    initialData?: TData | (() => TData) | undefined,
     initialPresenceState: PresenceState = PresenceState.online,
     allowedRoles?: UserMeetingRole[]
 ): IUseLivePresenceResults<TData> {
@@ -54,41 +60,41 @@ export function useLivePresence<TData extends object = object>(
     /**
      * User facing: list of non-local user's presence objects.
      */
-    const otherUsers = React.useMemo<LivePresenceUser<TData>[]>(() => {
-        return [...allUsers.filter((user) => !user.isLocalUser)];
-    }, [allUsers]);
+    const otherUsers = allUsers.filter((user) => !user.isLocalUser);
 
     /**
      * User facing: local user's presence object.
      */
-    const localUser = React.useMemo<LivePresenceUser<TData> | undefined>(() => {
-        return allUsers.find((user) => user.isLocalUser);
-    }, [allUsers]);
+    const localUser = allUsers.find((user) => user.isLocalUser);
+
+    const { container } = useFluidObjectsContext();
 
     /**
      * User facing: callback to update the local user's presence.
      */
     const updatePresence: OnUpdateLivePresenceAction<TData> = React.useCallback(
         async (data?: TData | undefined, state?: PresenceState | undefined) => {
-            if (!livePresence) {
-                console.error(
-                    new Error(
-                        "Cannot call updatePresence when presence is undefined"
-                    )
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "livePresence",
+                    "updatePresence"
+                );
+            }
+            if (livePresence === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "livePresence",
+                    "updatePresence"
                 );
-                return;
             }
             if (!livePresence.isInitialized) {
-                console.error(
-                    new Error(
-                        "Cannot call updatePresence while presence is not started"
-                    )
+                throw new ActionLiveDataObjectInitializedError(
+                    "livePresence",
+                    "updatePresence"
                 );
-                return;
             }
             return await livePresence.update(data, state);
         },
-        [livePresence]
+        [container, livePresence]
     );
 
     /**
@@ -108,7 +114,9 @@ export function useLivePresence<TData extends object = object>(
 
         if (!livePresence.isInitialized) {
             livePresence.initialize(
-                initialData,
+                isInitialDataCallback<TData>(initialData)
+                    ? initialData()
+                    : initialData,
                 initialPresenceState,
                 allowedRoles
             );
@@ -129,3 +137,7 @@ export function useLivePresence<TData extends object = object>(
         updatePresence,
     };
 }
+
+function isInitialDataCallback<TData>(value: any): value is () => TData {
+    return typeof value === "function";
+}

package/src/live-hooks/useLiveState.ts

@@ -7,6 +7,13 @@ import { LiveState, UserMeetingRole } from "@microsoft/live-share";
 import React from "react";
 import { SetLiveStateAction } from "../types";
 import { useDynamicDDS } from "../shared-hooks";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+    isPrevStateCallback,
+} from "../internal";
 
 /**
  * React hook for using a Live Share `LiveState`.
@@ -20,11 +27,11 @@ import { useDynamicDDS } from "../shared-hooks";
  * @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>(
     uniqueKey: string,
     initialState: TState,
     allowedRoles?: UserMeetingRole[]
-): [TState, SetLiveStateAction<TState>] {
+): [TState, SetLiveStateAction<TState>, LiveState<TState> | undefined] {
     const [currentState, setCurrentState] =
         React.useState<TState>(initialState);
     /**
@@ -35,32 +42,39 @@ export function useLiveState<TState = any>(
         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 setState = React.useCallback(
-        async (state: TState) => {
-            if (!liveState) {
-                console.error(
-                    new Error(
-                        "Cannot call changeState when liveState is undefined"
-                    )
+        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;
             }
-            return await liveState.set(state);
+            const valueToSet = isPrevStateCallback<TState>(state)
+                ? state(liveState.state)
+                : state;
+            return await liveState.set(valueToSet);
         },
-        [liveState]
+        [container, liveState]
     );
 
     /**
@@ -85,5 +99,5 @@ export function useLiveState<TState = any>(
         };
     }, [liveState]);
 
-    return [currentState, setState];
+    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,
@@ -46,6 +52,8 @@ export function useLiveTimer(
      */
     const { dds: liveTimer } = useDynamicDDS<LiveTimer>(uniqueKey, LiveTimer);
 
+    const { container } = useFluidObjectsContext();
+
     /**
      * Callback to send event through `LiveTimer`
      * @param duration the duration for the timer in milliseconds
@@ -53,23 +61,24 @@ export function useLiveTimer(
      */
     const start: OnStartTimerAction = React.useCallback(
         async (duration: number) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError("liveTimer", "start");
+            }
             if (liveTimer === undefined) {
-                console.error(
-                    new Error("Cannot call start when liveTimer is 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;
             }
             return await liveTimer.start(duration);
         },
-        [liveTimer]
+        [container, liveTimer]
     );
 
     /**
@@ -77,40 +86,37 @@ export function useLiveTimer(
      * @returns void promise that will throw when user does not have required roles
      */
     const play: OnPlayTimerAction = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError("liveTimer", "play");
+        }
         if (liveTimer === undefined) {
-            console.error(
-                new Error("Cannot call play when liveTimer is undefined")
-            );
-            return;
+            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");
         }
         return await liveTimer.play();
-    }, [liveTimer]);
+    }, [container, 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(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError("liveTimer", "pause");
+        }
         if (liveTimer === undefined) {
-            console.error(
-                new Error("Cannot call pause when liveTimer is undefined")
-            );
-            return;
+            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;
         }
         return await liveTimer.pause();
-    }, [liveTimer]);
+    }, [container, liveTimer]);
 
     /**
      * Setup change listeners and start `LiveTimer` if needed

package/src/live-hooks/useMediaSynchronizer.ts

@@ -16,6 +16,12 @@ import {
 import { isExtendedMediaMetadata, isMediaElement, isRefObject } from "../utils";
 import { useDynamicDDS } from "../shared-hooks";
 import { IUseMediaSynchronizerResults } from "../types";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
 
 /**
  * React hook for using a Live Share media `MediaPlayerSynchronizer`.
@@ -57,31 +63,66 @@ export function useMediaSynchronizer(
         LiveMediaSession
     );
 
+    const { container } = useFluidObjectsContext();
+
     /**
      * Play callback
      */
     const play = React.useCallback(async () => {
-        if (!mediaSynchronizer) return;
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "mediaSynchronizer",
+                "play"
+            );
+        }
+        if (mediaSynchronizer === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "mediaSynchronizer",
+                "play"
+            );
+        }
         return await mediaSynchronizer.play();
-    }, [mediaSynchronizer]);
+    }, [container, mediaSynchronizer]);
 
     /**
      * Pause callback
      */
     const pause = React.useCallback(async () => {
-        if (!mediaSynchronizer) return;
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "mediaSynchronizer",
+                "pause"
+            );
+        }
+        if (mediaSynchronizer === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "mediaSynchronizer",
+                "pause"
+            );
+        }
         return await mediaSynchronizer.pause();
-    }, [mediaSynchronizer]);
+    }, [container, mediaSynchronizer]);
 
     /**
      * User facing: seek callback
      */
     const seekTo = React.useCallback(
         async (time: number) => {
-            if (!mediaSynchronizer) return;
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "mediaSynchronizer",
+                    "seekTo"
+                );
+            }
+            if (mediaSynchronizer === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "mediaSynchronizer",
+                    "seekTo"
+                );
+            }
             return await mediaSynchronizer.seekTo(time);
         },
-        [mediaSynchronizer]
+        [container, mediaSynchronizer]
     );
 
     /**
@@ -89,7 +130,18 @@ export function useMediaSynchronizer(
      */
     const setTrack = React.useCallback(
         async (track: Partial<ExtendedMediaMetadata> | string | null) => {
-            if (!mediaSynchronizer) return;
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "mediaSynchronizer",
+                    "setTrack"
+                );
+            }
+            if (mediaSynchronizer === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "mediaSynchronizer",
+                    "setTrack"
+                );
+            }
             if (isExtendedMediaMetadata(track)) {
                 return await mediaSynchronizer.setTrack(track);
             } else if (typeof track === "string") {
@@ -98,7 +150,7 @@ export function useMediaSynchronizer(
                 } as ExtendedMediaMetadata);
             }
         },
-        [mediaSynchronizer]
+        [container, mediaSynchronizer]
     );
 
     /**

package/src/providers/AzureProvider.tsx

@@ -13,7 +13,7 @@ import { IAzureContainerResults } from "../types";
 import {
     ISharedStateRegistryResponse,
     useSharedStateRegistry,
-} from "../internal-hooks";
+} from "../internal";
 import {
     AzureTurboClient,
     IFluidTurboClient,

package/src/providers/LiveShareProvider.tsx

@@ -5,7 +5,7 @@
 
 import { IFluidContainer, LoadableObjectClassRecord } from "fluid-framework";
 import React from "react";
-import { useSharedStateRegistry } from "../internal-hooks";
+import { useSharedStateRegistry } from "../internal";
 import {
     ILiveShareClientOptions,
     ILiveShareHost,

package/src/shared-hooks/useSharedMap.ts

@@ -8,6 +8,11 @@ import { isEntries, isJSON, isMap } from "../utils";
 import { IUseSharedMapResults, SharedMapInitialData } from "../types";
 import { useDynamicDDS } from "./useDynamicDDS";
 import { SharedMap } from "fluid-framework";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
 
 /**
  * React hook for using a Fluid `SharedMap`.
@@ -56,20 +61,28 @@ export function useSharedMap<TData extends object = object>(
         onFirstInitialize
     );
 
+    const { container } = useFluidObjectsContext();
+
     /**
      * User facing: set a value to the Fluid `SharedMap`.
      */
     const setEntry = React.useCallback(
         (key: string, value: TData) => {
-            if (!sharedMap) {
-                console.error(
-                    new Error("Cannot call set when sharedMap is undefined")
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "sharedMap",
+                    "setEntry"
+                );
+            }
+            if (sharedMap === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "sharedMap",
+                    "setEntry"
                 );
-                return;
             }
             sharedMap.set(key, value);
         },
-        [sharedMap]
+        [container, sharedMap]
     );
 
     /**
@@ -77,15 +90,21 @@ export function useSharedMap<TData extends object = object>(
      */
     const deleteEntry = React.useCallback(
         (key: string) => {
-            if (!sharedMap) {
-                console.error(
-                    new Error("Cannot call remove when sharedMap is undefined")
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "sharedMap",
+                    "deleteEntry"
+                );
+            }
+            if (sharedMap === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "sharedMap",
+                    "deleteEntry"
                 );
-                return;
             }
             sharedMap.delete(key);
         },
-        [sharedMap]
+        [container, sharedMap]
     );
 
     // Setup change listeners, initial values, etc.

package/src/shared-hooks/useSharedState.ts

@@ -7,6 +7,7 @@ import React from "react";
 import { useFluidObjectsContext } from "../providers";
 import { DisposeSharedStateAction, SetSharedStateAction } from "../types";
 import { v4 as uuid } from "uuid";
+import { isPrevStateCallback } from "../internal";
 
 /**
  * Inspired by React's `useState` hook, `useSharedState` makes it easy to synchronize state in your app.
@@ -48,9 +49,14 @@ export function useSharedState<S>(
      * User facing: callback to change the shared state.
      */
     const setSharedState: SetSharedStateAction<S> = React.useCallback(
-        (updatedState: S) => {
-            setLocalState(updatedState);
-            updateSharedState(uniqueKey, updatedState);
+        (state: S | ((prevState: S) => S)) => {
+            setLocalState((prevState) => {
+                const valueToSet = isPrevStateCallback<S>(state)
+                    ? state(prevState)
+                    : state;
+                updateSharedState(uniqueKey, valueToSet);
+                return valueToSet;
+            });
         },
         [uniqueKey, setLocalState, updateSharedState]
     );

package/src/types/ActionTypes.ts

@@ -10,7 +10,15 @@ import { ITimerConfig, ILiveEvent, PresenceState } from "@microsoft/live-share";
 
 // React actions
 
-export type SetSharedStateAction<T> = (state: T) => void;
+/**
+ * Callback to set shared state
+ */
+export type SetSharedStateAction<TState> = (
+    state: TState | ((prevState: TState) => TState)
+) => void;
+/**
+ * Callback to set local state
+ */
 export type SetLocalStateAction = React.Dispatch<React.SetStateAction<any>>;
 
 // Fluid actions
@@ -79,7 +87,7 @@ export type DisposeSharedStateAction = () => void;
  * (state: TState) => Promise<void>
  */
 export type SetLiveStateAction<TState = undefined> = (
-    state: TState
+    state: TState | ((prevState: TState) => TState)
 ) => Promise<void>;
 
 /**

package/bin/internal-hooks/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./useSharedStateRegistry";
-//# sourceMappingURL=index.d.ts.map

package/bin/internal-hooks/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/internal-hooks/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/bin/internal-hooks/index.js

@@ -1,2 +0,0 @@
-export * from "./useSharedStateRegistry";
-//# sourceMappingURL=index.js.map

package/bin/internal-hooks/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/internal-hooks/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/bin/internal-hooks/useDynamicDDSRegistry.d.ts

@@ -1,14 +0,0 @@
-import { IAzureContainerResults, RegisterDDSSetStateAction, UnregisterDDSSetStateAction } from "../types";
-export interface IDynamicDDSRegistry {
-    registerDDSSetStateAction: RegisterDDSSetStateAction;
-    unregisterDDSSetStateAction: UnregisterDDSSetStateAction;
-}
-/**
- * Hook used internally to keep track of the DDSSetStateActionMap for each unique key. It gets DDS objects for provided keys where they exist and creates
- * them where they do not, providing the DDS objects to components that use them.
- *
- * @param results IAzureContainerResults response or undefined
- * @returns IDynamicDDSRegistry object
- */
-export declare const useDynamicDDSRegistry: (results: IAzureContainerResults | undefined) => IDynamicDDSRegistry;
-//# sourceMappingURL=useDynamicDDSRegistry.d.ts.map

package/bin/internal-hooks/useDynamicDDSRegistry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useDynamicDDSRegistry.d.ts","sourceRoot":"","sources":["../../src/internal-hooks/useDynamicDDSRegistry.ts"],"names":[],"mappings":"AAQA,OAAO,EACH,sBAAsB,EACtB,yBAAyB,EAEzB,2BAA2B,EAC9B,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAChC,yBAAyB,EAAE,yBAAyB,CAAC;IACrD,2BAA2B,EAAE,2BAA2B,CAAC;CAC5D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,YACrB,sBAAsB,GAAG,SAAS,KAC5C,mBAyKF,CAAC"}