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

package/bin/utils/type-check.d.ts

@@ -1,15 +1,15 @@
-/*!
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-import { ExtendedMediaMetadata, IMediaPlayer } from "@microsoft/live-share-media";
-import React from "react";
-export declare function isRefObject<T>(value: any): value is React.RefObject<T>;
-export declare function isMediaElement(value: any): value is IMediaPlayer;
-export declare function isExtendedMediaMetadata(value: any): value is ExtendedMediaMetadata;
-export declare function isMap(value: any): value is Map<string, any>;
-export declare function isEntries(value: any): value is readonly (readonly [string, any])[];
-export declare function isJSON(value: any): value is {
-    [key: string]: any;
-};
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+import { ExtendedMediaMetadata, IMediaPlayer } from "@microsoft/live-share-media";
+import React from "react";
+export declare function isRefObject<T>(value: any): value is React.RefObject<T>;
+export declare function isMediaElement(value: any): value is IMediaPlayer;
+export declare function isExtendedMediaMetadata(value: any): value is ExtendedMediaMetadata;
+export declare function isMap(value: any): value is Map<string, any>;
+export declare function isEntries(value: any): value is readonly (readonly [string, any])[];
+export declare function isJSON(value: any): value is {
+    [key: string]: any;
+};
 //# sourceMappingURL=type-check.d.ts.map

package/bin/utils/type-check.js

@@ -1,54 +1,54 @@
-/*!
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-export function isRefObject(value) {
-    return value.current === null || !!value.current;
-}
-export function isMediaElement(value) {
-    if (value) {
-        return (value.currentSrc !== undefined &&
-            value.currentTime !== undefined &&
-            value.duration !== undefined &&
-            value.ended !== undefined &&
-            value.muted !== undefined &&
-            value.paused !== undefined &&
-            value.playbackRate !== undefined &&
-            value.src !== undefined &&
-            value.volume !== undefined &&
-            value.load !== undefined &&
-            value.pause !== undefined &&
-            value.play !== undefined &&
-            value.addEventListener !== undefined &&
-            value.removeEventListener !== undefined);
-    }
-    return false;
-}
-export function isExtendedMediaMetadata(value) {
-    return value === null || !!(value === null || value === void 0 ? void 0 : value.trackIdentifier);
-}
-export function isMap(value) {
-    return value instanceof Map;
-}
-export function isEntries(value) {
-    try {
-        const tryValue = value;
-        if (typeof tryValue[0][0] === "string") {
-            return true;
-        }
-        return false;
-    }
-    catch (error) {
-        return false;
-    }
-}
-export function isJSON(value) {
-    try {
-        const tryValue = value;
-        return Object.keys(tryValue).length > 0;
-    }
-    catch (error) {
-        return false;
-    }
-}
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+export function isRefObject(value) {
+    return value.current === null || !!value.current;
+}
+export function isMediaElement(value) {
+    if (value) {
+        return (value.currentSrc !== undefined &&
+            value.currentTime !== undefined &&
+            value.duration !== undefined &&
+            value.ended !== undefined &&
+            value.muted !== undefined &&
+            value.paused !== undefined &&
+            value.playbackRate !== undefined &&
+            value.src !== undefined &&
+            value.volume !== undefined &&
+            value.load !== undefined &&
+            value.pause !== undefined &&
+            value.play !== undefined &&
+            value.addEventListener !== undefined &&
+            value.removeEventListener !== undefined);
+    }
+    return false;
+}
+export function isExtendedMediaMetadata(value) {
+    return value === null || !!(value === null || value === void 0 ? void 0 : value.trackIdentifier);
+}
+export function isMap(value) {
+    return value instanceof Map;
+}
+export function isEntries(value) {
+    try {
+        const tryValue = value;
+        if (typeof tryValue[0][0] === "string") {
+            return true;
+        }
+        return false;
+    }
+    catch (error) {
+        return false;
+    }
+}
+export function isJSON(value) {
+    try {
+        const tryValue = value;
+        return Object.keys(tryValue).length > 0;
+    }
+    catch (error) {
+        return false;
+    }
+}
 //# sourceMappingURL=type-check.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/live-share-react",
-  "version": "1.0.0-preview.9",
+  "version": "1.0.1-preview.1",
   "description": "Build collaborative React apps using Microsoft's Fluid & Live Share frameworks with ease.",
   "author": "Microsoft",
   "license": "SEE LICENSE IN LICENSE",
@@ -12,26 +12,30 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@fluidframework/azure-client": "~1.0.2",
-    "@fluid-experimental/task-manager": "~1.2.3",
-    "@microsoft/live-share": "1.0.0-preview.9",
-    "@microsoft/live-share-canvas": "1.0.0-preview.9",
-    "@microsoft/live-share-media": "1.0.0-preview.9",
-    "@microsoft/live-share-turbo": "1.0.0-preview.9",
-    "fluid-framework": "~1.2.3",
+    "@microsoft/live-share-turbo": "1.0.1-preview.1",
     "url": "^0.11.0",
-    "uuid": "^8.3.2"
+    "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.12.3",
-    "@fluidframework/test-client-utils": "~1.2.3",
+    "@babel/core": "^7.21.8",
+    "@fluidframework/azure-client": "^1.1.1",
+    "@fluidframework/test-client-utils": "^1.3.6",
+    "@microsoft/live-share": "1.0.1",
+    "@microsoft/live-share-canvas": "1.0.1",
+    "@microsoft/live-share-media": "1.0.1",
     "@types/react": "^18.0.0",
     "@types/react-dom": "^18.0.0",
-    "@types/uuid": "^8.3.4",
-    "babel-loader": "^7.1.5",
-    "typescript": "^4.6.4"
+    "@types/uuid": "^9.0.1",
+    "babel-loader": "^9.1.2",
+    "fluid-framework": "^1.3.6",
+    "typescript": "^5.0.4"
   },
   "peerDependencies": {
+    "@fluidframework/azure-client": "^1.0.0",
+    "@microsoft/live-share": "1.0.1",
+    "@microsoft/live-share-canvas": "1.0.1",
+    "@microsoft/live-share-media": "1.0.1",
+    "fluid-framework": "^1.2.3",
     "react": "^16.8.0 || ^17 || ^18",
     "react-dom": "^16.8.0 || ^17 || ^18"
   },

package/src/interfaces/LiveInterfaceExtensions.ts

@@ -3,7 +3,24 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-export interface IReceiveLiveEvent<TEvent extends object = object> {
-    event: TEvent;
+/**
+ * Object response for a received event
+ */
+export interface IReceiveLiveEvent<TEvent = any> {
+    /**
+     * The value of the event that was sent
+     */
+    value: TEvent;
+    /**
+     * True if the local client was the one to send this event
+     */
     local: boolean;
+    /**
+     * Client ID of the user that sent the event
+     */
+    clientId: string;
+    /**
+     * Server timestamp at which the event was sent
+     */
+    timestamp: number;
 }

package/src/internal/errors.ts

@@ -0,0 +1,48 @@
+/**
+ * @hidden
+ */
+class UseLiveDataObjectActionError extends Error {
+    constructor(ddsName: string, functionName: string, message: string) {
+        super(
+            `use${toFirstLetterUppercase(ddsName)} ${functionName}: ${message}`
+        );
+    }
+}
+
+/**
+ * @hidden
+ */
+export class ActionContainerNotJoinedError extends UseLiveDataObjectActionError {
+    constructor(ddsName: string, functionName: string) {
+        super(ddsName, functionName, "container has not yet been joined");
+    }
+}
+
+/**
+ * @hidden
+ */
+export class ActionLiveDataObjectUndefinedError extends UseLiveDataObjectActionError {
+    constructor(ddsName: string, functionName: string) {
+        super(
+            ddsName,
+            functionName,
+            `${ddsName} is undefined, which means it is still being dynamically created`
+        );
+    }
+}
+
+/**
+ * @hidden
+ */
+export class ActionLiveDataObjectInitializedError extends UseLiveDataObjectActionError {
+    constructor(ddsName: string, functionName: string) {
+        super(ddsName, functionName, `${ddsName} is not initialized`);
+    }
+}
+
+/**
+ * @hidden
+ */
+function toFirstLetterUppercase(word: string) {
+    return word[0].toUpperCase() + word.substring(1);
+}

package/src/internal/index.ts

@@ -0,0 +1,3 @@
+export * from "./useSharedStateRegistry";
+export * from "./errors";
+export * from "./type-guards";

package/src/internal/type-guards.ts

@@ -0,0 +1,9 @@
+/**
+ * @hidden
+ * Used for useLiveState and useSharedState for checking if a value is a prevState callback
+ */
+export function isPrevStateCallback<TState>(
+    value: any
+): value is (value: TState) => TState {
+    return typeof value === "function";
+}

package/src/{internal-hooks → internal}/useSharedStateRegistry.ts

@@ -70,9 +70,8 @@ export const useSharedStateRegistry = (
                 );
             }
             // Set initial values, if known
-            const stateMap = results?.container.initialObjects.TURBO_STATE_MAP as
-                | SharedMap
-                | undefined;
+            const stateMap = results?.container.initialObjects
+                .TURBO_STATE_MAP as SharedMap | undefined;
             const initialValue = stateMap?.get(uniqueKey);
             if (initialValue) {
                 setLocalStateAction(initialValue);
@@ -102,7 +101,8 @@ export const useSharedStateRegistry = (
         (uniqueKey: string, value: any) => {
             if (!results) return;
             const { container } = results;
-            const stateMap = container.initialObjects.TURBO_STATE_MAP as SharedMap;
+            const stateMap = container.initialObjects
+                .TURBO_STATE_MAP as SharedMap;
             stateMap.set(uniqueKey, value);
         },
         [results]
@@ -118,7 +118,8 @@ export const useSharedStateRegistry = (
             let actionsMap =
                 registeredSharedSetStateActionMapRef.current.get(uniqueKey);
             actionsMap?.clear();
-            const stateMap = container.initialObjects.TURBO_STATE_MAP as SharedMap;
+            const stateMap = container.initialObjects
+                .TURBO_STATE_MAP as SharedMap;
             stateMap.delete(uniqueKey);
         },
         [results]

package/src/live-hooks/useLiveCanvas.ts

@@ -9,7 +9,6 @@ import {
     InkingManager,
     InkingTool,
     IPoint,
-    IUserInfo,
     LiveCanvas,
 } from "@microsoft/live-share-canvas";
 import React from "react";
@@ -33,7 +32,7 @@ import { isRefObject } from "../utils";
  * @param scale Optional. Stateful scale number to use in the `InkingManager`. Defaults to 1 and must be greater than 0.
  * @param referencePoint Optional. Stateful reference point enum to use in the `InkingManger`. Defaults to "center".
  * @param isCursorShared Optional. Stateful boolean flag for whether cursor should be shared in `LiveCanvas`. Defaults to false.
- * @param localUserCursor Optional. Stateful `IUserInfo` object for the local user's metadata to display alongside their cursor. Defaults to undefined.
+ * @param localUserPictureUrl Optional. url string for the local user to display alongside their cursor. Defaults to undefined.
  * @returns IUseLiveCanvasResults object that contains the `liveCanvas` data object and `inkingManager`.
  */
 export function useLiveCanvas(
@@ -46,7 +45,7 @@ export function useLiveCanvas(
     scale?: number,
     referencePoint?: CanvasReferencePoint,
     isCursorShared?: boolean,
-    localUserCursor?: IUserInfo
+    localUserPictureUrl?: string
 ): IUseLiveCanvasResults {
     /**
      * User facing: inking manager instance
@@ -56,7 +55,10 @@ export function useLiveCanvas(
     /**
      * User facing: dynamically load the DDS for the given unique key.
      */
-    const { dds: liveCanvas } = useDynamicDDS<LiveCanvas>(uniqueKey, LiveCanvas);
+    const { dds: liveCanvas } = useDynamicDDS<LiveCanvas>(
+        uniqueKey,
+        LiveCanvas
+    );
 
     /**
      * Setup the InkingManager and LiveCanvas
@@ -162,31 +164,21 @@ export function useLiveCanvas(
      * Sets the isCursorShared of the liveCanvas based on the 'isCursorShared' prop
      */
     React.useEffect(() => {
-        if (
-            liveCanvas?.isCursorShared !== undefined &&
-            isCursorShared !== undefined
-        ) {
+        if (liveCanvas && isCursorShared !== undefined) {
             liveCanvas.isCursorShared = isCursorShared;
         }
-    }, [isCursorShared, liveCanvas?.isCursorShared]);
+    }, [isCursorShared, liveCanvas]);
 
     /**
      * Sets the onGetLocalUserInfo method of the liveCanvas based on the 'localUserCursor' prop
      */
     React.useEffect(() => {
-        if (liveCanvas?.onGetLocalUserInfo !== undefined && localUserCursor) {
-            liveCanvas.onGetLocalUserInfo = (): IUserInfo | undefined => {
-                return {
-                    displayName: localUserCursor.displayName,
-                    pictureUri: localUserCursor.pictureUri,
-                };
+        if (liveCanvas && localUserPictureUrl) {
+            liveCanvas.onGetLocalUserPictureUrl = (): string | undefined => {
+                return localUserPictureUrl;
             };
         }
-    }, [
-        localUserCursor?.displayName,
-        localUserCursor?.pictureUri,
-        liveCanvas?.onGetLocalUserInfo,
-    ]);
+    }, [localUserPictureUrl, liveCanvas]);
 
     /**
      * Return hook response

package/src/live-hooks/useLiveEvent.ts

@@ -16,6 +16,12 @@ import {
 } from "../types";
 import { IReceiveLiveEvent } from "../interfaces";
 import { useDynamicDDS } from "../shared-hooks";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
+import { useFluidObjectsContext } from "../providers";
 
 /**
  * React hook for using a Live Share `LiveEvent`.
@@ -31,7 +37,7 @@ import { useDynamicDDS } from "../shared-hooks";
  * @param onReceivedEvent Optional. Callback method to be called when a new notification is received.
  * @returns stateful `latestEvent` & `allEvents` list, `sendEvent` callback, and the `liveEvent` object.
  */
-export function useLiveEvent<TEvent extends object = object>(
+export function useLiveEvent<TEvent = any>(
     uniqueKey: string,
     allowedRoles?: UserMeetingRole[],
     onReceivedEvent?: OnReceivedLiveEventAction<TEvent>
@@ -49,49 +55,62 @@ export function useLiveEvent<TEvent extends object = object>(
     /**
      * User facing: dynamically load the DDS for the given unique key.
      */
-    const { dds: liveEvent } = useDynamicDDS<LiveEvent>(uniqueKey, LiveEvent);
+    const { dds: liveEvent } = useDynamicDDS<LiveEvent<TEvent>>(
+        uniqueKey,
+        LiveEvent<TEvent>
+    );
+
+    const { container } = useFluidObjectsContext();
 
     /**
      * User facing: callback to send event through `LiveEvent`
      */
     const sendEvent: SendLiveEventAction<TEvent> = React.useCallback(
-        (event: TEvent) => {
-            if (liveEvent?.isInitialized === undefined) {
-                console.error(
-                    new Error(
-                        "Cannot call emitEvent when liveEvent is undefined"
-                    )
+        async (event: TEvent) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "liveEvent",
+                    "sendEvent"
+                );
+            }
+            if (liveEvent === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveEvent",
+                    "sendEvent"
                 );
-                return;
             }
             if (!liveEvent.isInitialized) {
-                console.error(
-                    new Error(
-                        "Cannot call emitEvent while liveEvent is not started"
-                    )
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveEvent",
+                    "sendEvent"
                 );
-                return;
             }
-            liveEvent?.sendEvent(event);
+            return await liveEvent.send(event);
         },
-        [liveEvent?.isInitialized]
+        [container, liveEvent]
     );
 
     /**
      * Setup change listeners and start `LiveEvent` if needed
      */
     React.useEffect(() => {
-        if (liveEvent?.isInitialized === undefined)
-            return;
+        if (liveEvent?.isInitialized === undefined) return;
         // Register event listener
-        const onEventReceived = (event: any, local: boolean) => {
+        const onEventReceived = (
+            event: TEvent,
+            local: boolean,
+            clientId: string,
+            timestamp: number
+        ) => {
             // If developer passed the optional onReceivedEvent callback, we
             // call it.
-            onReceivedEvent?.(event as TEvent, local);
+            onReceivedEvent?.(event, local);
             // Set the received event to our local state
             const received: IReceiveLiveEvent<TEvent> = {
-                event: event as TEvent,
+                value: event,
                 local,
+                clientId,
+                timestamp,
             };
             allEventsRef.current = [...allEventsRef.current, received];
             setLatestReceived(received);
@@ -106,7 +125,7 @@ export function useLiveEvent<TEvent extends object = object>(
             // on unmount, remove event listeners
             liveEvent?.off(LiveEventEvents.received, onEventReceived);
         };
-    }, [liveEvent?.isInitialized]);
+    }, [liveEvent]);
 
     return {
         latestEvent,

package/src/live-hooks/useLivePresence.ts

@@ -7,10 +7,17 @@ import {
     LivePresenceUser,
     PresenceState,
     LivePresence,
+    UserMeetingRole,
 } from "@microsoft/live-share";
 import React from "react";
-import { IUseLivePresenceResults } from "../types";
+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`.
@@ -21,20 +28,20 @@ import { useDynamicDDS } from "../shared-hooks";
  * user data. This is useful for rendering a list of users, profile pictures, cursor positions, and more.
  *
  * @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 uniqueKey Optional. The unique key for `LivePresence`. If one does not yet exist, a new one
+ * @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>"
  * @returns stateful `localUser`, `otherUsers` list, and `allUsers` list. Also returns a callback method
  * to update the local user's presence and the `LivePresence` Fluid object.
  */
 export function useLivePresence<TData extends object = object>(
-    userId?: string | undefined,
-    initialData?: TData | undefined,
+    uniqueKey: string,
+    initialData?: TData | (() => TData) | undefined,
     initialPresenceState: PresenceState = PresenceState.online,
-    uniqueKey: string = ":<dds-default>"
+    allowedRoles?: UserMeetingRole[]
 ): IUseLivePresenceResults<TData> {
     /**
      * Stateful all user presence list and its non-user-facing setter method.
@@ -45,58 +52,60 @@ export function useLivePresence<TData extends object = object>(
     /**
      * User facing: dynamically load the DDS for the given unique key.
      */
-    const { dds: livePresence } = useDynamicDDS<LivePresence<TData>>(uniqueKey, LivePresence<TData>);
+    const { dds: livePresence } = useDynamicDDS<LivePresence<TData>>(
+        uniqueKey,
+        LivePresence<TData>
+    );
 
     /**
      * 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 = React.useCallback(
-        (state?: PresenceState | undefined, data?: TData | undefined) => {
-            if (!livePresence) {
-                console.error(
-                    new Error(
-                        "Cannot call updatePresence when presence is undefined"
-                    )
+    const updatePresence: OnUpdateLivePresenceAction<TData> = React.useCallback(
+        async (data?: TData | undefined, state?: PresenceState | 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;
             }
-            livePresence.updatePresence(state, data);
+            return await livePresence.update(data, state);
         },
-        [livePresence]
+        [container, livePresence]
     );
 
     /**
      * Setup change listeners and start `LivePresence` if needed
      */
     React.useEffect(() => {
-        if (livePresence === undefined)
-            return;
+        if (livePresence === undefined) return;
 
         const onPresenceChanged = () => {
             const updatedLocalUsers: LivePresenceUser<TData>[] = [];
-            livePresence?.forEach((user) => {
+            livePresence?.getUsers().forEach((user) => {
                 updatedLocalUsers.push(user);
             });
             setAllUsers(updatedLocalUsers);
@@ -104,7 +113,13 @@ export function useLivePresence<TData extends object = object>(
         livePresence.on("presenceChanged", onPresenceChanged);
 
         if (!livePresence.isInitialized) {
-            livePresence.initialize(userId, initialData, initialPresenceState);
+            livePresence.initialize(
+                isInitialDataCallback<TData>(initialData)
+                    ? initialData()
+                    : initialData,
+                initialPresenceState,
+                allowedRoles
+            );
         } else {
             onPresenceChanged();
         }
@@ -122,3 +137,7 @@ export function useLivePresence<TData extends object = object>(
         updatePresence,
     };
 }
+
+function isInitialDataCallback<TData>(value: any): value is () => TData {
+    return typeof value === "function";
+}