@microsoft/live-share-react 1.3.0-preview.0 → 1.3.1-preview.0

package/src/live-hooks/useLiveCanvas.ts

@@ -1,191 +1,191 @@
-/*!
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import {
-    CanvasReferencePoint,
-    IBrush,
-    InkingManager,
-    InkingTool,
-    IPoint,
-    LiveCanvas,
-} from "@microsoft/live-share-canvas";
-import React from "react";
-import { useDynamicDDS } from "../shared-hooks";
-import { IUseLiveCanvasResults } from "../types";
-import { isRefObject } from "../utils";
-
-/**
- * React hook for using a Live Share Canvas `LiveCanvas` and `InkingManager`.
- *
- * @remarks
- * Use this hook to set up an `LiveCanvas` object, which is used for collaborative inking. It takes several input parameters, including a unique key,
- * a reference to a canvas element, and various settings for the inking tool, brush, and canvas offset and scale.
- * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
- *
- * @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`.
- */
-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
-): IUseLiveCanvasResults {
-    /**
-     * User facing: inking manager instance
-     */
-    const [inkingManager, setInkingManager] = React.useState<InkingManager>();
-
-    /**
-     * User facing: dynamically load the DDS for the given unique key.
-     */
-    const { dds: liveCanvas } = useDynamicDDS<LiveCanvas>(
-        uniqueKey,
-        LiveCanvas
-    );
-
-    /**
-     * 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;
-        // 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]);
-
-    /**
-     * Activate or deactivate the inkingManager based on the 'active' prop
-     */
-    React.useEffect(() => {
-        if (inkingManager && active !== undefined) {
-            if (active) {
-                inkingManager.activate();
-            } else {
-                inkingManager.deactivate();
-            }
-        }
-    }, [active, inkingManager]);
-
-    /**
-     * Sets the tool of the inkingManager based on the 'tool' prop
-     */
-    React.useEffect(() => {
-        if (inkingManager && tool !== undefined) {
-            inkingManager.tool = tool;
-        }
-    }, [tool, inkingManager]);
-
-    /**
-     * Sets the offset of the inkingManager based on the 'offset' prop
-     */
-    React.useEffect(() => {
-        if (inkingManager && offset !== undefined) {
-            inkingManager.offset = {
-                x: offset.x,
-                y: offset.y,
-            };
-        }
-    }, [offset?.x, offset?.y, inkingManager]);
-
-    /**
-     * Sets the scale of the inkingManager based on the 'scale' prop
-     */
-    React.useEffect(() => {
-        if (inkingManager && scale !== undefined) {
-            inkingManager.scale = scale;
-        }
-    }, [scale, inkingManager]);
-
-    /**
-     * Sets the referencePoint of the inkingManager based on the 'referencePoint' prop
-     */
-    React.useEffect(() => {
-        if (inkingManager && referencePoint !== undefined) {
-            inkingManager.referencePoint = referencePoint;
-        }
-    }, [referencePoint, inkingManager]);
-
-    /**
-     * Sets the lineBrush of the inkingManager based on the 'lineBrush' prop
-     */
-    React.useEffect(() => {
-        if (inkingManager && lineBrush) {
-            inkingManager.lineBrush = {
-                color: lineBrush.color,
-                tip: lineBrush.tip,
-                tipSize: lineBrush.tipSize,
-                type: lineBrush.type,
-                endArrow: lineBrush.endArrow,
-            };
-        }
-    }, [
-        lineBrush?.color,
-        lineBrush?.tip,
-        lineBrush?.tipSize,
-        lineBrush?.type,
-        lineBrush?.endArrow,
-        inkingManager,
-    ]);
-
-    /**
-     * Sets the isCursorShared of the liveCanvas based on the 'isCursorShared' prop
-     */
-    React.useEffect(() => {
-        if (liveCanvas && isCursorShared !== undefined) {
-            liveCanvas.isCursorShared = isCursorShared;
-        }
-    }, [isCursorShared, liveCanvas]);
-
-    /**
-     * Sets the onGetLocalUserInfo method of the liveCanvas based on the 'localUserCursor' prop
-     */
-    React.useEffect(() => {
-        if (liveCanvas && localUserPictureUrl) {
-            liveCanvas.onGetLocalUserPictureUrl = (): string | undefined => {
-                return localUserPictureUrl;
-            };
-        }
-    }, [localUserPictureUrl, liveCanvas]);
-
-    /**
-     * Return hook response
-     */
-    return {
-        inkingManager,
-        liveCanvas,
-    };
-}
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    CanvasReferencePoint,
+    IBrush,
+    InkingManager,
+    InkingTool,
+    IPoint,
+    LiveCanvas,
+} from "@microsoft/live-share-canvas";
+import React from "react";
+import { useDynamicDDS } from "../shared-hooks";
+import { IUseLiveCanvasResults } from "../types";
+import { isRefObject } from "../utils";
+
+/**
+ * React hook for using a Live Share Canvas `LiveCanvas` and `InkingManager`.
+ *
+ * @remarks
+ * Use this hook to set up an `LiveCanvas` object, which is used for collaborative inking. It takes several input parameters, including a unique key,
+ * a reference to a canvas element, and various settings for the inking tool, brush, and canvas offset and scale.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
+ * @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`.
+ */
+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
+): IUseLiveCanvasResults {
+    /**
+     * User facing: inking manager instance
+     */
+    const [inkingManager, setInkingManager] = React.useState<InkingManager>();
+
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    const { dds: liveCanvas } = useDynamicDDS<LiveCanvas>(
+        uniqueKey,
+        LiveCanvas
+    );
+
+    /**
+     * 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;
+        // 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]);
+
+    /**
+     * Activate or deactivate the inkingManager based on the 'active' prop
+     */
+    React.useEffect(() => {
+        if (inkingManager && active !== undefined) {
+            if (active) {
+                inkingManager.activate();
+            } else {
+                inkingManager.deactivate();
+            }
+        }
+    }, [active, inkingManager]);
+
+    /**
+     * Sets the tool of the inkingManager based on the 'tool' prop
+     */
+    React.useEffect(() => {
+        if (inkingManager && tool !== undefined) {
+            inkingManager.tool = tool;
+        }
+    }, [tool, inkingManager]);
+
+    /**
+     * Sets the offset of the inkingManager based on the 'offset' prop
+     */
+    React.useEffect(() => {
+        if (inkingManager && offset !== undefined) {
+            inkingManager.offset = {
+                x: offset.x,
+                y: offset.y,
+            };
+        }
+    }, [offset?.x, offset?.y, inkingManager]);
+
+    /**
+     * Sets the scale of the inkingManager based on the 'scale' prop
+     */
+    React.useEffect(() => {
+        if (inkingManager && scale !== undefined) {
+            inkingManager.scale = scale;
+        }
+    }, [scale, inkingManager]);
+
+    /**
+     * Sets the referencePoint of the inkingManager based on the 'referencePoint' prop
+     */
+    React.useEffect(() => {
+        if (inkingManager && referencePoint !== undefined) {
+            inkingManager.referencePoint = referencePoint;
+        }
+    }, [referencePoint, inkingManager]);
+
+    /**
+     * Sets the lineBrush of the inkingManager based on the 'lineBrush' prop
+     */
+    React.useEffect(() => {
+        if (inkingManager && lineBrush) {
+            inkingManager.lineBrush = {
+                color: lineBrush.color,
+                tip: lineBrush.tip,
+                tipSize: lineBrush.tipSize,
+                type: lineBrush.type,
+                endArrow: lineBrush.endArrow,
+            };
+        }
+    }, [
+        lineBrush?.color,
+        lineBrush?.tip,
+        lineBrush?.tipSize,
+        lineBrush?.type,
+        lineBrush?.endArrow,
+        inkingManager,
+    ]);
+
+    /**
+     * Sets the isCursorShared of the liveCanvas based on the 'isCursorShared' prop
+     */
+    React.useEffect(() => {
+        if (liveCanvas && isCursorShared !== undefined) {
+            liveCanvas.isCursorShared = isCursorShared;
+        }
+    }, [isCursorShared, liveCanvas]);
+
+    /**
+     * Sets the onGetLocalUserInfo method of the liveCanvas based on the 'localUserCursor' prop
+     */
+    React.useEffect(() => {
+        if (liveCanvas && localUserPictureUrl) {
+            liveCanvas.onGetLocalUserPictureUrl = (): string | undefined => {
+                return localUserPictureUrl;
+            };
+        }
+    }, [localUserPictureUrl, liveCanvas]);
+
+    /**
+     * Return hook response
+     */
+    return {
+        inkingManager,
+        liveCanvas,
+    };
+}

package/src/live-hooks/useLiveEvent.ts

@@ -1,140 +1,140 @@
-/*!
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import {
-    LiveEventEvents,
-    UserMeetingRole,
-    LiveEvent,
-    LiveDataObjectInitializeState,
-} from "@microsoft/live-share";
-import React from "react";
-import {
-    IUseLiveEventResults,
-    OnReceivedLiveEventAction,
-    SendLiveEventAction,
-} 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`.
- *
- * @remarks
- * Use this hook if you want to send transient JSON objects to everyone connected to the Fluid container,
- * such as when sending push notifications or reactions.
- * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
- *
- * @template TEvent Optional typing for events sent & received. Default is `object` type.
- * @param uniqueKey the unique key for the `LiveEvent`. If one does not yet exist, a new one
- * will be created, otherwise it will use the existing one.
- * @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.
- */
-export function useLiveEvent<TEvent = any>(
-    uniqueKey: string,
-    allowedRoles?: UserMeetingRole[],
-    onReceivedEvent?: OnReceivedLiveEventAction<TEvent>
-): IUseLiveEventResults<TEvent> {
-    /**
-     * Stateful latest event (user facing) and its non-user-facing setter method.
-     */
-    const [latestEvent, setLatestReceived] =
-        React.useState<IReceiveLiveEvent<TEvent>>();
-    /**
-     * Reference for all received/sent events. The current value of this is user-facing. Because
-     * this is always set at the same time as latestEvent, it is effectively a stateful value.
-     */
-    const allEventsRef = React.useRef<IReceiveLiveEvent<TEvent>[]>([]);
-    /**
-     * User facing: dynamically load the DDS for the given unique key.
-     */
-    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(
-        async (event: TEvent) => {
-            if (!container) {
-                throw new ActionContainerNotJoinedError(
-                    "liveEvent",
-                    "sendEvent"
-                );
-            }
-            if (liveEvent === undefined) {
-                throw new ActionLiveDataObjectUndefinedError(
-                    "liveEvent",
-                    "sendEvent"
-                );
-            }
-            if (!liveEvent.isInitialized) {
-                throw new ActionLiveDataObjectInitializedError(
-                    "liveEvent",
-                    "sendEvent"
-                );
-            }
-            return await liveEvent.send(event);
-        },
-        [container, liveEvent]
-    );
-
-    /**
-     * Setup change listeners and start `LiveEvent` if needed
-     */
-    React.useEffect(() => {
-        if (liveEvent?.isInitialized === undefined) return;
-        // Register event listener
-        const onEventReceived = (
-            event: TEvent,
-            local: boolean,
-            clientId: string,
-            timestamp: number
-        ) => {
-            // If developer passed the optional onReceivedEvent callback, we
-            // call it.
-            onReceivedEvent?.(event, local);
-            // Set the received event to our local state
-            const received: IReceiveLiveEvent<TEvent> = {
-                value: event,
-                local,
-                clientId,
-                timestamp,
-            };
-            allEventsRef.current = [...allEventsRef.current, received];
-            setLatestReceived(received);
-        };
-        liveEvent.on(LiveEventEvents.received, onEventReceived);
-        if (
-            liveEvent.initializeState === LiveDataObjectInitializeState.needed
-        ) {
-            // Start live event
-            liveEvent.initialize(allowedRoles);
-        }
-
-        return () => {
-            // on unmount, remove event listeners
-            liveEvent?.off(LiveEventEvents.received, onEventReceived);
-        };
-    }, [liveEvent]);
-
-    return {
-        latestEvent,
-        allEvents: allEventsRef.current,
-        sendEvent,
-        liveEvent,
-    };
-}
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    LiveEventEvents,
+    UserMeetingRole,
+    LiveEvent,
+    LiveDataObjectInitializeState,
+} from "@microsoft/live-share";
+import React from "react";
+import {
+    IUseLiveEventResults,
+    OnReceivedLiveEventAction,
+    SendLiveEventAction,
+} 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`.
+ *
+ * @remarks
+ * Use this hook if you want to send transient JSON objects to everyone connected to the Fluid container,
+ * such as when sending push notifications or reactions.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
+ * @template TEvent Optional typing for events sent & received. Default is `object` type.
+ * @param uniqueKey the unique key for the `LiveEvent`. If one does not yet exist, a new one
+ * will be created, otherwise it will use the existing one.
+ * @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.
+ */
+export function useLiveEvent<TEvent = any>(
+    uniqueKey: string,
+    allowedRoles?: UserMeetingRole[],
+    onReceivedEvent?: OnReceivedLiveEventAction<TEvent>
+): IUseLiveEventResults<TEvent> {
+    /**
+     * Stateful latest event (user facing) and its non-user-facing setter method.
+     */
+    const [latestEvent, setLatestReceived] =
+        React.useState<IReceiveLiveEvent<TEvent>>();
+    /**
+     * Reference for all received/sent events. The current value of this is user-facing. Because
+     * this is always set at the same time as latestEvent, it is effectively a stateful value.
+     */
+    const allEventsRef = React.useRef<IReceiveLiveEvent<TEvent>[]>([]);
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    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(
+        async (event: TEvent) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "liveEvent",
+                    "sendEvent"
+                );
+            }
+            if (liveEvent === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveEvent",
+                    "sendEvent"
+                );
+            }
+            if (!liveEvent.isInitialized) {
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveEvent",
+                    "sendEvent"
+                );
+            }
+            return await liveEvent.send(event);
+        },
+        [container, liveEvent]
+    );
+
+    /**
+     * Setup change listeners and start `LiveEvent` if needed
+     */
+    React.useEffect(() => {
+        if (liveEvent?.isInitialized === undefined) return;
+        // Register event listener
+        const onEventReceived = (
+            event: TEvent,
+            local: boolean,
+            clientId: string,
+            timestamp: number
+        ) => {
+            // If developer passed the optional onReceivedEvent callback, we
+            // call it.
+            onReceivedEvent?.(event, local);
+            // Set the received event to our local state
+            const received: IReceiveLiveEvent<TEvent> = {
+                value: event,
+                local,
+                clientId,
+                timestamp,
+            };
+            allEventsRef.current = [...allEventsRef.current, received];
+            setLatestReceived(received);
+        };
+        liveEvent.on(LiveEventEvents.received, onEventReceived);
+        if (
+            liveEvent.initializeState === LiveDataObjectInitializeState.needed
+        ) {
+            // Start live event
+            liveEvent.initialize(allowedRoles);
+        }
+
+        return () => {
+            // on unmount, remove event listeners
+            liveEvent?.off(LiveEventEvents.received, onEventReceived);
+        };
+    }, [liveEvent]);
+
+    return {
+        latestEvent,
+        allEvents: allEventsRef.current,
+        sendEvent,
+        liveEvent,
+    };
+}