@microsoft/live-share-react 1.0.0-preview.5

package/src/live-hooks/useLiveCanvas.ts

@@ -0,0 +1,198 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    CanvasReferencePoint,
+    IBrush,
+    InkingManager,
+    InkingTool,
+    IPoint,
+    IUserInfo,
+    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.
+ *
+ * @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 localUserCursor Optional. Stateful `IUserInfo` object for the local user's metadata 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,
+    localUserCursor?: IUserInfo
+): 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 &&
+            isCursorShared !== undefined
+        ) {
+            liveCanvas.isCursorShared = isCursorShared;
+        }
+    }, [isCursorShared, liveCanvas?.isCursorShared]);
+
+    /**
+     * 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,
+                };
+            };
+        }
+    }, [
+        localUserCursor?.displayName,
+        localUserCursor?.pictureUri,
+        liveCanvas?.onGetLocalUserInfo,
+    ]);
+
+    /**
+     * Return hook response
+     */
+    return {
+        inkingManager,
+        liveCanvas,
+    };
+}

package/src/live-hooks/useLiveEvent.ts

@@ -0,0 +1,117 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    LiveEventEvents,
+    UserMeetingRole,
+    LiveEvent,
+} from "@microsoft/live-share";
+import React from "react";
+import {
+    IUseLiveEventResults,
+    OnReceivedLiveEventAction,
+    SendLiveEventAction,
+} from "../types";
+import { IReceiveLiveEvent } from "../interfaces";
+import { useDynamicDDS } from "../shared-hooks";
+
+/**
+ * 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.
+ *
+ * @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 extends object = object>(
+    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>(uniqueKey, LiveEvent);
+
+    /**
+     * 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"
+                    )
+                );
+                return;
+            }
+            if (!liveEvent.isInitialized) {
+                console.error(
+                    new Error(
+                        "Cannot call emitEvent while liveEvent is not started"
+                    )
+                );
+                return;
+            }
+            liveEvent?.sendEvent(event);
+        },
+        [liveEvent?.isInitialized]
+    );
+
+    /**
+     * Setup change listeners and start `LiveEvent` if needed
+     */
+    React.useEffect(() => {
+        if (liveEvent?.isInitialized === undefined)
+            return;
+        // Register event listener
+        const onEventReceived = (event: any, local: boolean) => {
+            // If developer passed the optional onReceivedEvent callback, we
+            // call it.
+            onReceivedEvent?.(event as TEvent, local);
+            // Set the received event to our local state
+            const received: IReceiveLiveEvent<TEvent> = {
+                event: event as TEvent,
+                local,
+            };
+            allEventsRef.current = [...allEventsRef.current, received];
+            setLatestReceived(received);
+        };
+        liveEvent.on(LiveEventEvents.received, onEventReceived);
+        if (!liveEvent.isInitialized) {
+            // Start live event
+            liveEvent.initialize(allowedRoles);
+        }
+
+        return () => {
+            // on unmount, remove event listeners
+            liveEvent?.off(LiveEventEvents.received, onEventReceived);
+        };
+    }, [liveEvent?.isInitialized]);
+
+    return {
+        latestEvent,
+        allEvents: allEventsRef.current,
+        sendEvent,
+        liveEvent,
+    };
+}

package/src/live-hooks/useLivePresence.ts

@@ -0,0 +1,124 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    LivePresenceUser,
+    PresenceState,
+    LivePresence,
+} from "@microsoft/live-share";
+import React from "react";
+import { IUseLivePresenceResults } from "../types";
+import { useDynamicDDS } from "../shared-hooks";
+
+/**
+ * React hook for using a Live Share `LivePresence`.
+ *
+ * @remarks
+ * Use this hook if you want to track presence for who is currently using this component, such as
+ * who is online or who is viewing a specific document. With presence, you can sent along any custom
+ * 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 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 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
+ * 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,
+    initialPresenceState: PresenceState = PresenceState.online,
+    uniqueKey: string = ":<dds-default>"
+): IUseLivePresenceResults<TData> {
+    /**
+     * Stateful all user presence list and its non-user-facing setter method.
+     */
+    const [allUsers, setAllUsers] = React.useState<LivePresenceUser<TData>[]>(
+        []
+    );
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    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]);
+
+    /**
+     * User facing: local user's presence object.
+     */
+    const localUser = React.useMemo<LivePresenceUser<TData> | undefined>(() => {
+        return allUsers.find((user) => user.isLocalUser);
+    }, [allUsers]);
+
+    /**
+     * 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"
+                    )
+                );
+                return;
+            }
+            if (!livePresence.isInitialized) {
+                console.error(
+                    new Error(
+                        "Cannot call updatePresence while presence is not started"
+                    )
+                );
+                return;
+            }
+            livePresence.updatePresence(state, data);
+        },
+        [livePresence]
+    );
+
+    /**
+     * Setup change listeners and start `LivePresence` if needed
+     */
+    React.useEffect(() => {
+        if (livePresence === undefined)
+            return;
+
+        const onPresenceChanged = () => {
+            const updatedLocalUsers: LivePresenceUser<TData>[] = [];
+            livePresence?.forEach((user) => {
+                updatedLocalUsers.push(user);
+            });
+            setAllUsers(updatedLocalUsers);
+        };
+        livePresence.on("presenceChanged", onPresenceChanged);
+
+        if (!livePresence.isInitialized) {
+            livePresence.initialize(userId, initialData, initialPresenceState);
+        } else {
+            onPresenceChanged();
+        }
+
+        return () => {
+            livePresence?.off("presenceChanged", onPresenceChanged);
+        };
+    }, [livePresence]);
+
+    return {
+        localUser,
+        otherUsers,
+        allUsers,
+        livePresence,
+        updatePresence,
+    };
+}

package/src/live-hooks/useLiveState.ts

@@ -0,0 +1,108 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { LiveState, UserMeetingRole } from "@microsoft/live-share";
+import React from "react";
+import { SetLiveStateAction } from "../types";
+import { useDynamicDDS } from "../shared-hooks";
+
+interface ILiveStateStatus<
+    TState extends string = string,
+    TData extends object = object
+> {
+    state?: TState;
+    data?: TData;
+}
+
+/**
+ * React hook for using a Live Share `LiveState`.
+ *
+ * @remarks
+ * Use this hook if you want to synchronize app state that will reset when all users leave the session.
+ *
+ * @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 initialState Optional. the initial state value of type TState
+ * @param initialData Optional. the initial data value of type TData
+ * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
+ * @returns ordered values: first value is the synchronized state value, second is synchronized data value, and third is a setter to change the state/data values.
+ */
+export function useLiveState<
+    TState extends string = string,
+    TData extends object = object
+>(
+    uniqueKey: string,
+    initialState?: TState,
+    initialData?: TData,
+    allowedRoles?: UserMeetingRole[]
+): [TState | undefined, TData | undefined, SetLiveStateAction<TState, TData>] {
+    const [current, setCurrent] = React.useState<
+        ILiveStateStatus<TState, TData>
+    >({
+        state: initialState,
+        data: initialData,
+    });
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    const { dds: liveState } = useDynamicDDS<LiveState<TData>>(
+        uniqueKey,
+        LiveState<TData>
+    );
+
+    /**
+     * Change state callback that is user facing
+     */
+    const changeState = React.useCallback(
+        (state: TState, value?: TData | undefined) => {
+            if (!liveState) {
+                console.error(
+                    new Error(
+                        "Cannot call changeState when liveState is undefined"
+                    )
+                );
+                return;
+            }
+            if (!liveState.isInitialized) {
+                console.error(
+                    new Error(
+                        "Cannot call changeState while liveState is not started"
+                    )
+                );
+                return;
+            }
+            liveState?.changeState(state, value);
+        },
+        [liveState]
+    );
+
+    /**
+     * Setup change listeners and start `LiveState` if needed
+     */
+    React.useEffect(() => {
+        if (liveState === undefined) return;
+
+        const onStateChanged = (state: TState, data: TData | undefined) => {
+            setCurrent({
+                state,
+                data,
+            });
+        };
+        liveState.on("stateChanged", onStateChanged);
+        if (!liveState.isInitialized) {
+            liveState.initialize(allowedRoles, initialState, initialData);
+            if (liveState.state) {
+                onStateChanged(liveState.state as TState, liveState.data);
+            }
+        } else if (liveState.state) {
+            onStateChanged(liveState.state as TState, liveState.data);
+        }
+
+        return () => {
+            liveState?.off("stateChanged", onStateChanged);
+        };
+    }, [liveState?.isInitialized]);
+
+    return [current?.state, current?.data, changeState];
+}