@microsoft/live-share-react 2.0.0-internal.1 → 2.0.0-internal.11

package/src/live-hooks/useLiveCanvas.ts

@@ -3,18 +3,16 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-import {
-    CanvasReferencePoint,
-    IBrush,
-    InkingManager,
-    InkingTool,
-    IPoint,
-    LiveCanvas,
-} from "@microsoft/live-share-canvas";
+import { InkingManager, LiveCanvas } from "@microsoft/live-share-canvas";
 import React from "react";
-import { useDynamicDDS } from "../shared-hooks";
-import { IUseLiveCanvasResults } from "../types";
-import { isRefObject } from "../utils";
+import { useDynamicDDS } from "../shared-hooks/index.js";
+import {
+    IUseLiveCanvasOptionalProps,
+    IUseLiveCanvasResults,
+} from "../types/index.js";
+import { isRefObject } from "../utils/index.js";
+import { getRawNode } from "../shared-hooks/internals/tree-node-utils.js";
+import { LiveDataObjectInitializeState } from "@microsoft/live-share";
 
 /**
  * React hook for using a Live Share Canvas `LiveCanvas` and `InkingManager`.
@@ -26,27 +24,72 @@ import { isRefObject } from "../utils";
  *
  * @param uniqueKey the unique key for the `LiveCanvas`. If one does not yet exist, a new one.
  * @param canvasElementRef the HTML div element ref or document ID that `InkingManager` will use for canvas-based collaboration.
- * @param active Optional. Stateful boolean that will activate/de-activate `InkingManager` accordingly.
- * @param tool Optional. Stateful enum for what tool to use in the `InkingManager`.
- * @param lineBrush Optional. Stateful lineBrush object for the selected lineBrush options to use in `InkingManager`.
- * @param offset Optional. Stateful offset point to use in the `InkingManager`. Gets the viewport offset. Defaults to 0,0.
- * @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 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`.
+ * @param props Optional. Other optional props.
+ * @param props.active Optional. Stateful boolean that will activate/de-activate `InkingManager` accordingly.
+ * @param props.tool Optional. Stateful enum for what tool to use in the `InkingManager`.
+ * @param props.lineBrush Optional. Stateful lineBrush object for the selected lineBrush options to use in `InkingManager`.
+ * @param props.offset Optional. Stateful offset point to use in the `InkingManager`. Gets the viewport offset. Defaults to 0,0.
+ * @param props.scale Optional. Stateful scale number to use in the `InkingManager`. Defaults to 1 and must be greater than 0.
+ * @param props.referencePoint Optional. Stateful reference point enum to use in the `InkingManger`. Defaults to "center".
+ * @param props.isCursorShared Optional. Stateful boolean flag for whether cursor should be shared in `LiveCanvas`. Defaults to false.
+ * @param props.localUserPictureUrl Optional. url string for the local user to display alongside their cursor. Defaults to undefined.
+ * @param props.node Optional. A Fluid `LiveCanvasTree` `TreeNode` instance to swap out the underlying storage solution for strokes.
+ * To learn more, look at Fluid's [SharedTree](https://fluidframework.com/docs/data-structures/tree/) documentation.
+ * @param allowedRoles Optional. The user roles that are allowed to start/stop/pause the timer.
+ *
+ * @returns `IUseLiveCanvasResults` object that contains the `liveCanvas` data object and `inkingManager`.
+ * 
+ * @example
+ ```jsx
+import { useLiveCanvas } from "@microsoft/live-share-react";
+import { InkingTool } from "@microsoft/live-share-canvas";
+import { useRef } from "react";
+
+// Unique identifier that distinguishes this useLiveCanvas from others in your app
+const UNIQUE_KEY = "CUSTOM-LIVE-CANVAS";
+
+// Example component
+export function ExampleLiveCanvas() {
+    const liveCanvasRef = useRef(null);
+    const { liveCanvas, inkingManager } = useLiveCanvas(
+        "CUSTOM-LIVE-CANVAS",
+        liveCanvasRef,
+    );
+
+    return (
+        <div style={{ position: "absolute"}}>
+            <div
+                ref={liveCanvasRef}
+                // Best practice is to not define inline styles
+                style={{ width: "556px", height: "224px" }}
+            />
+            {!!liveCanvas && (
+                <div>
+                    <button
+                        onClick={() => {
+                            inkingManager.tool = InkingTool.pen;
+                        }}
+                    >
+                        {"Pen"}
+                    </button>
+                    <button
+                        onClick={() => {
+                            inkingManager.tool = InkingTool.laserPointer;
+                        }}
+                    >
+                        {"Laser pointer"}
+                    </button>
+                </div>
+            )}
+        </div>
+    );
+};
+ ```
  */
 export function useLiveCanvas(
     uniqueKey: string,
     canvasElementRef: React.RefObject<HTMLElement | null> | string,
-    active?: boolean,
-    tool?: InkingTool,
-    lineBrush?: IBrush,
-    offset?: IPoint,
-    scale?: number,
-    referencePoint?: CanvasReferencePoint,
-    isCursorShared?: boolean,
-    localUserPictureUrl?: string
+    props?: IUseLiveCanvasOptionalProps
 ): IUseLiveCanvasResults {
     /**
      * User facing: inking manager instance
@@ -61,103 +104,132 @@ export function useLiveCanvas(
         LiveCanvas
     );
 
+    // This should change less frequently then node if they are using `useTreeNode`
+    // We need the raw node anyways to apply event listeners
+    const rawNode = getRawNode(props?.node);
+
     /**
      * Setup the InkingManager and LiveCanvas
      */
+    React.useEffect(
+        () => {
+            // if the component is already listening or liveCanvas is not yet initialized, return
+            if (!liveCanvas) return;
+            // get the canvas element from the ref or document
+            let htmlElement: HTMLElement | null;
+            if (isRefObject(canvasElementRef)) {
+                htmlElement = canvasElementRef.current;
+            } else {
+                htmlElement = document.getElementById(canvasElementRef);
+            }
+            if (htmlElement === null) return;
+            // Clear out existing nodes
+            function removeAllChildren(node: HTMLElement | ChildNode) {
+                node.childNodes.forEach((childNode) => {
+                    removeAllChildren(childNode);
+                    childNode.remove();
+                });
+            }
+            removeAllChildren(htmlElement);
+            // Create the InkingManager and initialize the liveCanvas with it
+            const inkingManager = new InkingManager(htmlElement);
+            setInkingManager(inkingManager);
+            liveCanvas.initialize(inkingManager, props?.allowedRoles, rawNode);
+
+            // cleanup function to be called when the component is unmount
+            return () => {
+                inkingManager.removeAllListeners();
+            };
+        },
+        // Intentionally ommitting rawNode from deps because we only want to initialize once,
+        // whereas rawNode may change many times.
+        [liveCanvas, props?.allowedRoles]
+    );
+
+    /**
+     * Set the node if it changes while LiveCanvas is initialized
+     */
     React.useEffect(() => {
-        // if the component is already listening or liveCanvas is not yet initialized, return
-        if (!liveCanvas) return;
-        // get the canvas element from the ref or document
-        let htmlElement: HTMLElement | null;
-        if (isRefObject(canvasElementRef)) {
-            htmlElement = canvasElementRef.current;
-        } else {
-            htmlElement = document.getElementById(canvasElementRef);
-        }
-        if (htmlElement === null) return;
-        // Create the InkingManager and initialize the liveCanvas with it
-        const inkingManager = new InkingManager(htmlElement);
-        setInkingManager(inkingManager);
-        liveCanvas.initialize(inkingManager);
-
-        // cleanup function to be called when the component is unmount
-        return () => {
-            // liveCanvas.dispose();
-            inkingManager.removeAllListeners();
-        };
-    }, [liveCanvas]);
+        if (
+            !rawNode ||
+            liveCanvas?.initializeState !==
+                LiveDataObjectInitializeState.succeeded
+        )
+            return;
+        liveCanvas.setTreeNode(rawNode);
+    }, [liveCanvas, rawNode]);
 
     /**
      * Activate or deactivate the inkingManager based on the 'active' prop
      */
     React.useEffect(() => {
-        if (inkingManager && active !== undefined) {
-            if (active) {
+        if (inkingManager && props?.active !== undefined) {
+            if (props?.active) {
                 inkingManager.activate();
             } else {
                 inkingManager.deactivate();
             }
         }
-    }, [active, inkingManager]);
+    }, [props?.active, inkingManager]);
 
     /**
      * Sets the tool of the inkingManager based on the 'tool' prop
      */
     React.useEffect(() => {
-        if (inkingManager && tool !== undefined) {
-            inkingManager.tool = tool;
+        if (inkingManager && props?.tool !== undefined) {
+            inkingManager.tool = props.tool;
         }
-    }, [tool, inkingManager]);
+    }, [props?.tool, inkingManager]);
 
     /**
      * Sets the offset of the inkingManager based on the 'offset' prop
      */
     React.useEffect(() => {
-        if (inkingManager && offset !== undefined) {
+        if (inkingManager && props?.offset !== undefined) {
             inkingManager.offset = {
-                x: offset.x,
-                y: offset.y,
+                x: props?.offset.x,
+                y: props?.offset.y,
             };
         }
-    }, [offset?.x, offset?.y, inkingManager]);
+    }, [props?.offset?.x, props?.offset?.y, inkingManager]);
 
     /**
      * Sets the scale of the inkingManager based on the 'scale' prop
      */
     React.useEffect(() => {
-        if (inkingManager && scale !== undefined) {
-            inkingManager.scale = scale;
+        if (inkingManager && props?.scale !== undefined) {
+            inkingManager.scale = props?.scale;
         }
-    }, [scale, inkingManager]);
+    }, [props?.scale, inkingManager]);
 
     /**
      * Sets the referencePoint of the inkingManager based on the 'referencePoint' prop
      */
     React.useEffect(() => {
-        if (inkingManager && referencePoint !== undefined) {
-            inkingManager.referencePoint = referencePoint;
+        if (inkingManager && props?.referencePoint !== undefined) {
+            inkingManager.referencePoint = props?.referencePoint;
         }
-    }, [referencePoint, inkingManager]);
+    }, [props?.referencePoint, inkingManager]);
 
     /**
      * Sets the lineBrush of the inkingManager based on the 'lineBrush' prop
      */
     React.useEffect(() => {
-        if (inkingManager && lineBrush) {
+        if (inkingManager && props?.lineBrush) {
             inkingManager.lineBrush = {
-                color: lineBrush.color,
-                tip: lineBrush.tip,
-                tipSize: lineBrush.tipSize,
-                type: lineBrush.type,
-                endArrow: lineBrush.endArrow,
+                color: props.lineBrush.color,
+                tip: props.lineBrush.tip,
+                tipSize: props.lineBrush.tipSize,
+                type: props.lineBrush.type,
+                endArrow: props.lineBrush.endArrow,
             };
         }
     }, [
-        lineBrush?.color,
-        lineBrush?.tip,
-        lineBrush?.tipSize,
-        lineBrush?.type,
-        lineBrush?.endArrow,
+        props?.lineBrush?.color,
+        props?.lineBrush?.tip,
+        props?.lineBrush?.tipSize,
+        props?.lineBrush?.type,
+        props?.lineBrush?.endArrow,
         inkingManager,
     ]);
 
@@ -165,21 +237,21 @@ export function useLiveCanvas(
      * Sets the isCursorShared of the liveCanvas based on the 'isCursorShared' prop
      */
     React.useEffect(() => {
-        if (liveCanvas && isCursorShared !== undefined) {
-            liveCanvas.isCursorShared = isCursorShared;
+        if (liveCanvas && props?.isCursorShared !== undefined) {
+            liveCanvas.isCursorShared = props.isCursorShared;
         }
-    }, [isCursorShared, liveCanvas]);
+    }, [props?.isCursorShared, liveCanvas]);
 
     /**
      * Sets the onGetLocalUserInfo method of the liveCanvas based on the 'localUserCursor' prop
      */
     React.useEffect(() => {
-        if (liveCanvas && localUserPictureUrl) {
+        if (liveCanvas && props?.localUserPictureUrl) {
             liveCanvas.onGetLocalUserPictureUrl = (): string | undefined => {
-                return localUserPictureUrl;
+                return props.localUserPictureUrl;
             };
         }
-    }, [localUserPictureUrl, liveCanvas]);
+    }, [props?.localUserPictureUrl, liveCanvas]);
 
     /**
      * Return hook response

package/src/live-hooks/useLiveEvent.ts

@@ -14,15 +14,15 @@ import {
     IUseLiveEventResults,
     OnReceivedLiveEventAction,
     SendLiveEventAction,
-} from "../types";
-import { IReceiveLiveEvent } from "../interfaces";
-import { useDynamicDDS } from "../shared-hooks";
+} from "../types/index.js";
+import { IReceiveLiveEvent } from "../interfaces/index.js";
+import { useDynamicDDS } from "../shared-hooks/index.js";
 import {
     ActionContainerNotJoinedError,
     ActionLiveDataObjectInitializedError,
     ActionLiveDataObjectUndefinedError,
-} from "../internal";
-import { useFluidObjectsContext } from "../providers";
+} from "../internal/index.js";
+import { useFluidObjectsContext } from "../providers/index.js";
 
 /**
  * React hook for using a Live Share `LiveEvent`.
@@ -38,6 +38,42 @@ import { useFluidObjectsContext } from "../providers";
  * @param allowedRoles Optional. The meeting roles eligible to send events through this object.
  * @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.
+ * 
+ * @example
+ ```jsx
+import { useLiveEvent } from "@microsoft/live-share-react";
+
+const emojis = ["❤️", "😂", "👍", "👎"];
+
+// Define a unique key that differentiates this usage of `useLiveEvent` from others in your app
+const MY_UNIQUE_KEY = "event-key";
+
+// Example component for using useLiveEvent
+export const MyCustomEvent = () => {
+  const { latestEvent, liveEvent, sendEvent } = useLiveEvent(MY_UNIQUE_KEY);
+
+  // Render loading UI when creating LiveEvent instance for first time
+  if (!liveEvent) return <>Loading...</>;
+
+  // Render UI
+  return (
+    <div>
+      {`Latest event: ${latestEvent?.value}, from local user: ${latestEvent?.local}`}
+      {"Select a planet below:"}
+      {emojis.map((emoji) => (
+        <button
+          key={emoji}
+          onClick={() => {
+            sendEvent(emoji);
+          }}
+        >
+          {emoji}
+        </button>
+      ))}
+    </div>
+  );
+};
+ ```
  */
 export function useLiveEvent<TEvent = any>(
     uniqueKey: string,
@@ -68,7 +104,7 @@ export function useLiveEvent<TEvent = any>(
      * User facing: callback to send event through `LiveEvent`
      */
     const sendEvent: SendLiveEventAction<TEvent> = React.useCallback(
-        async (event: TEvent) => {
+        async (event: TEvent, targetClientId?: string) => {
             if (!container) {
                 throw new ActionContainerNotJoinedError(
                     "liveEvent",
@@ -87,7 +123,7 @@ export function useLiveEvent<TEvent = any>(
                     "sendEvent"
                 );
             }
-            return await liveEvent.send(event);
+            return await liveEvent.send(event, targetClientId);
         },
         [container, liveEvent]
     );

package/src/live-hooks/useLiveFollowMode.ts

@@ -12,14 +12,14 @@ import {
     IFollowModeState,
 } from "@microsoft/live-share";
 import React from "react";
-import { useDynamicDDS } from "../shared-hooks";
-import { useFluidObjectsContext } from "../providers";
+import { useDynamicDDS } from "../shared-hooks/index.js";
+import { useFluidObjectsContext } from "../providers/index.js";
 import {
     ActionContainerNotJoinedError,
     ActionLiveDataObjectInitializedError,
     ActionLiveDataObjectUndefinedError,
-} from "../internal";
-import { IUseLiveFollowModeResults } from "../types";
+} from "../internal/index.js";
+import { IUseLiveFollowModeResults } from "../types/index.js";
 
 /**
  * React hook for using a Live Share `LiveFollowMode`.
@@ -36,6 +36,145 @@ import { IUseLiveFollowModeResults } from "../types";
  * @param initialData The initial value for the local user's `stateValue`.
  * @param allowedRoles Optional. The user roles that are allowed to present to use `startPresenting()` or `stopPresenting()`.
  * @returns `IUseLiveFollowModeResults` results, which contains React stateful objects and callbacks.
+ * 
+ * @example
+ ```jsx
+ import { FollowModeType } from "@microsoft/live-share";
+import { useLiveFollowMode } from "@microsoft/live-share-react";
+// As an example, we will use a fake component to denote what a 3D viewer might look like in an app
+import { Example3DModelViewer } from "./components";
+
+// Define a unique key that differentiates this usage of `useLiveFollowMode` from others in your app
+const MY_UNIQUE_KEY = "follow-mode-key";
+
+// Define the initial stateValue for the local user (optional).
+const startingCameraPosition = {
+    x: 0,
+    y: 0,
+    z: 0,
+};
+
+// Example component for using useLiveFollowMode
+export function MyLiveFollowMode() {
+    const {
+        state,
+        localUser,
+        otherUsers,
+        allUsers,
+        liveFollowMode,
+        update,
+        startPresenting,
+        stopPresenting,
+        beginSuspension,
+        endSuspension,
+        followUser,
+        stopFollowing,
+    } = useLiveFollowMode(MY_UNIQUE_KEY, startingCameraPosition);
+
+    // Example of an event listener for a camera position changed event.
+    // For something like a camera change event, you should use a debounce function.
+    function onCameraPositionChanged(position, isUserAction) {
+        // Broadcast change to other users so that they have their latest camera position
+        update(position);
+        // If the local user changed the position while following another user, we want to suspend.
+        // Note: helps to distinguish changes initiated by the local user (e.g., drag mouse) separately from other change events.
+        if (!isUserAction) return;
+        switch (state.type) {
+            case FollowModeType.followPresenter:
+            case FollowModeType.followUser: {
+                // This will trigger a "stateChanged" event update for the local user only.
+                followMode.beginSuspension();
+                break;
+            }
+            default: {
+                // No need to suspend for other types
+                break;
+            }
+        }
+    }
+
+    // Can optionally get the relevant user's presence object
+    const followingUser = liveFollowMode?.getUser(state.followingUserId);
+
+    // Render loading UI when creating LiveFollowMode instance for first time
+    if (!liveFollowMode) return <>Loading...</>;
+
+    // Render UI
+    return (
+        <div>
+            {state.type === FollowModeType.local && (
+                <div>
+                    <p>{""}</p>
+                    <button onClick={startPresenting}>
+                        {"Start presenting"}
+                    </button>
+                </div>
+            )}
+            {state.type === FollowModeType.activeFollowers && (
+                <div>
+                    <p>{`${state.otherUsersCount} users are following you`}</p>
+                    <button onClick={startPresenting}>
+                        {"Present to all"}
+                    </button>
+                </div>
+            )}
+            {state.type === FollowModeType.activePresenter && (
+                <div>
+                    <p>{`You are actively presenting to everyone`}</p>
+                    <button onClick={stopPresenting}>
+                        {"Stop presenting"}
+                    </button>
+                </div>
+            )}
+            {state.type === FollowModeType.followPresenter && (
+                <div>
+                    <p>{`${followingUser?.displayName} is presenting to everyone`}</p>
+                    <button onClick={startPresenting}>{"Take control"}</button>
+                </div>
+            )}
+            {state.type === FollowModeType.suspendFollowPresenter && (
+                <div>
+                    <p>{`${followingUser?.displayName} is presenting to everyone`}</p>
+                    <button onClick={endSuspension}>
+                        {"Sync to presenter"}
+                    </button>
+                </div>
+            )}
+            {state.type === FollowModeType.followUser && (
+                <div>
+                    <p>{`You are following ${followingUser?.displayName}`}</p>
+                    <button onClick={stopFollowing}>{"Stop following"}</button>
+                </div>
+            )}
+            {state.type === FollowModeType.suspendFollowUser && (
+                <div>
+                    <p>{`You were following ${followingUser?.displayName}`}</p>
+                    <button onClick={stopFollowing}>
+                        {"Resume following"}
+                    </button>
+                </div>
+            )}
+            <div>
+                <p>{"Follow a specific user:"}</p>
+                {otherUsers.map((user) => (
+                    <button
+                        onClick={() => {
+                            followUser(user.userId);
+                        }}
+                        key={user.userId}
+                    >
+                        {user.displayName}
+                    </button>
+                ))}
+            </div>
+            <Example3DModelViewer
+                cameraPosition={state.value}
+                onCameraPositionChanged={onCameraPositionChanged}
+            />
+        </div>
+    );
+};
+ ```
  */
 export function useLiveFollowMode<TData = any>(
     uniqueKey: string,
@@ -63,12 +202,16 @@ export function useLiveFollowMode<TData = any>(
     /**
      * User facing: list of non-local user's presence objects.
      */
-    const otherUsers = allUsers.filter((user) => !user.isLocalUser);
+    const otherUsers = React.useMemo(() => {
+        return allUsers.filter((user) => !user.isLocalUser);
+    }, [allUsers]);
 
     /**
      * User facing: local user's presence object.
      */
-    const localUser = allUsers.find((user) => user.isLocalUser);
+    const localUser = React.useMemo(() => {
+        return allUsers.find((user) => user.isLocalUser);
+    }, [allUsers]);
 
     const { container } = useFluidObjectsContext();