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

package/src/live-hooks/useLivePresence.ts

@@ -1,147 +1,147 @@
-/*!
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import {
-    LivePresenceUser,
-    PresenceState,
-    LivePresence,
-    UserMeetingRole,
-    LiveDataObjectInitializeState,
-} from "@microsoft/live-share";
-import React from "react";
-import { IUseLivePresenceResults, OnUpdateLivePresenceAction } from "../types";
-import { useDynamicDDS } from "../shared-hooks";
-import { useFluidObjectsContext } from "../providers";
-import {
-    ActionContainerNotJoinedError,
-    ActionLiveDataObjectInitializedError,
-    ActionLiveDataObjectUndefinedError,
-} from "../internal";
-
-/**
- * React hook for using a Live Share `LivePresence`.
- *
- * @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.
- * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
- *
- * @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 will be created.
- * @param initialData Optional. Initial presence data object for the user. Can be value or a function to get the value.
- * @param initialPresenceState Optional. Initial status of the user's presence. Default is online.
- * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
- * will be created, otherwise it will use the existing one. Default value is ":<dds-default>"
- * @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>(
-    uniqueKey: string,
-    initialData?: TData | (() => TData) | undefined,
-    initialPresenceState: PresenceState = PresenceState.online,
-    allowedRoles?: UserMeetingRole[]
-): 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 = allUsers.filter((user) => !user.isLocalUser);
-
-    /**
-     * User facing: local user's presence object.
-     */
-    const localUser = allUsers.find((user) => user.isLocalUser);
-
-    const { container } = useFluidObjectsContext();
-
-    /**
-     * User facing: callback to update the local user's presence.
-     */
-    const updatePresence: OnUpdateLivePresenceAction<TData> = React.useCallback(
-        async (data?: TData | undefined, state?: PresenceState | undefined) => {
-            if (!container) {
-                throw new ActionContainerNotJoinedError(
-                    "livePresence",
-                    "updatePresence"
-                );
-            }
-            if (livePresence === undefined) {
-                throw new ActionLiveDataObjectUndefinedError(
-                    "livePresence",
-                    "updatePresence"
-                );
-            }
-            if (!livePresence.isInitialized) {
-                throw new ActionLiveDataObjectInitializedError(
-                    "livePresence",
-                    "updatePresence"
-                );
-            }
-            return await livePresence.update(data, state);
-        },
-        [container, livePresence]
-    );
-
-    /**
-     * Setup change listeners and start `LivePresence` if needed
-     */
-    React.useEffect(() => {
-        if (livePresence === undefined) return;
-
-        const onPresenceChanged = () => {
-            const updatedLocalUsers: LivePresenceUser<TData>[] = [];
-            livePresence?.getUsers().forEach((user) => {
-                updatedLocalUsers.push(user);
-            });
-            setAllUsers(updatedLocalUsers);
-        };
-        livePresence.on("presenceChanged", onPresenceChanged);
-
-        if (
-            livePresence.initializeState ===
-            LiveDataObjectInitializeState.needed
-        ) {
-            livePresence.initialize(
-                isInitialDataCallback<TData>(initialData)
-                    ? initialData()
-                    : initialData,
-                initialPresenceState,
-                allowedRoles
-            );
-        } else {
-            onPresenceChanged();
-        }
-
-        return () => {
-            livePresence?.off("presenceChanged", onPresenceChanged);
-        };
-    }, [livePresence]);
-
-    return {
-        localUser,
-        otherUsers,
-        allUsers,
-        livePresence,
-        updatePresence,
-    };
-}
-
-function isInitialDataCallback<TData>(value: any): value is () => TData {
-    return typeof value === "function";
-}
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    LivePresenceUser,
+    PresenceState,
+    LivePresence,
+    UserMeetingRole,
+    LiveDataObjectInitializeState,
+} from "@microsoft/live-share";
+import React from "react";
+import { IUseLivePresenceResults, OnUpdateLivePresenceAction } from "../types";
+import { useDynamicDDS } from "../shared-hooks";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
+
+/**
+ * React hook for using a Live Share `LivePresence`.
+ *
+ * @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.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
+ * @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 will be created.
+ * @param initialData Optional. Initial presence data object for the user. Can be value or a function to get the value.
+ * @param initialPresenceState Optional. Initial status of the user's presence. Default is online.
+ * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
+ * will be created, otherwise it will use the existing one. Default value is ":<dds-default>"
+ * @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>(
+    uniqueKey: string,
+    initialData?: TData | (() => TData) | undefined,
+    initialPresenceState: PresenceState = PresenceState.online,
+    allowedRoles?: UserMeetingRole[]
+): 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 = allUsers.filter((user) => !user.isLocalUser);
+
+    /**
+     * User facing: local user's presence object.
+     */
+    const localUser = allUsers.find((user) => user.isLocalUser);
+
+    const { container } = useFluidObjectsContext();
+
+    /**
+     * User facing: callback to update the local user's presence.
+     */
+    const updatePresence: OnUpdateLivePresenceAction<TData> = React.useCallback(
+        async (data?: TData | undefined, state?: PresenceState | undefined) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "livePresence",
+                    "updatePresence"
+                );
+            }
+            if (livePresence === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "livePresence",
+                    "updatePresence"
+                );
+            }
+            if (!livePresence.isInitialized) {
+                throw new ActionLiveDataObjectInitializedError(
+                    "livePresence",
+                    "updatePresence"
+                );
+            }
+            return await livePresence.update(data, state);
+        },
+        [container, livePresence]
+    );
+
+    /**
+     * Setup change listeners and start `LivePresence` if needed
+     */
+    React.useEffect(() => {
+        if (livePresence === undefined) return;
+
+        const onPresenceChanged = () => {
+            const updatedLocalUsers: LivePresenceUser<TData>[] = [];
+            livePresence?.getUsers().forEach((user) => {
+                updatedLocalUsers.push(user);
+            });
+            setAllUsers(updatedLocalUsers);
+        };
+        livePresence.on("presenceChanged", onPresenceChanged);
+
+        if (
+            livePresence.initializeState ===
+            LiveDataObjectInitializeState.needed
+        ) {
+            livePresence.initialize(
+                isInitialDataCallback<TData>(initialData)
+                    ? initialData()
+                    : initialData,
+                initialPresenceState,
+                allowedRoles
+            );
+        } else {
+            onPresenceChanged();
+        }
+
+        return () => {
+            livePresence?.off("presenceChanged", onPresenceChanged);
+        };
+    }, [livePresence]);
+
+    return {
+        localUser,
+        otherUsers,
+        allUsers,
+        livePresence,
+        updatePresence,
+    };
+}
+
+function isInitialDataCallback<TData>(value: any): value is () => TData {
+    return typeof value === "function";
+}

package/src/live-hooks/useLiveState.ts

@@ -1,110 +1,110 @@
-/*!
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import {
-    LiveDataObjectInitializeState,
-    LiveState,
-    UserMeetingRole,
-} from "@microsoft/live-share";
-import React from "react";
-import { SetLiveStateAction } from "../types";
-import { useDynamicDDS } from "../shared-hooks";
-import { useFluidObjectsContext } from "../providers";
-import {
-    ActionContainerNotJoinedError,
-    ActionLiveDataObjectInitializedError,
-    ActionLiveDataObjectUndefinedError,
-    isPrevStateCallback,
-} from "../internal";
-
-/**
- * React hook for using a Live Share `LiveState`.
- *
- * @remarks
- * Use this hook if you want to synchronize app state that will reset when all users leave the session.
- * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
- *
- * @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 allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
- * @returns ordered values: first value is the synchronized state value and the second is a setter to change the state value.
- * The setter returns a void promise, which will throw if the user does not have the required roles to set.
- */
-export function useLiveState<TState = any>(
-    uniqueKey: string,
-    initialState: TState,
-    allowedRoles?: UserMeetingRole[]
-): [TState, SetLiveStateAction<TState>, LiveState<TState> | undefined] {
-    const [currentState, setCurrentState] =
-        React.useState<TState>(initialState);
-    /**
-     * User facing: dynamically load the DDS for the given unique key.
-     */
-    const { dds: liveState } = useDynamicDDS<LiveState<TState>>(
-        uniqueKey,
-        LiveState<TState>
-    );
-
-    const { container } = useFluidObjectsContext();
-
-    /**
-     * Change state callback that is user facing
-     * @param state TState to set
-     * @returns void promise, which will throw if the user does not have the required roles
-     */
-    const setState = React.useCallback(
-        async (state: TState | ((prevState: TState) => TState)) => {
-            if (!container) {
-                throw new ActionContainerNotJoinedError(
-                    "liveState",
-                    "setState"
-                );
-            }
-            if (liveState === undefined) {
-                throw new ActionLiveDataObjectUndefinedError(
-                    "liveState",
-                    "setState"
-                );
-            }
-            if (!liveState.isInitialized) {
-                throw new ActionLiveDataObjectInitializedError(
-                    "liveState",
-                    "setState"
-                );
-            }
-            const valueToSet = isPrevStateCallback<TState>(state)
-                ? state(liveState.state)
-                : state;
-            return await liveState.set(valueToSet);
-        },
-        [container, liveState]
-    );
-
-    /**
-     * Setup change listeners and start `LiveState` if needed
-     */
-    React.useEffect(() => {
-        if (liveState === undefined) return;
-
-        const onStateChanged = (state: TState) => {
-            setCurrentState(state);
-        };
-        liveState.on("stateChanged", onStateChanged);
-        if (
-            liveState.initializeState === LiveDataObjectInitializeState.needed
-        ) {
-            liveState.initialize(initialState, allowedRoles);
-        }
-        if (JSON.stringify(liveState.state) !== JSON.stringify(initialState)) {
-            onStateChanged(liveState.state);
-        }
-
-        return () => {
-            liveState?.off("stateChanged", onStateChanged);
-        };
-    }, [liveState]);
-
-    return [currentState, setState, liveState];
-}
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    LiveDataObjectInitializeState,
+    LiveState,
+    UserMeetingRole,
+} from "@microsoft/live-share";
+import React from "react";
+import { SetLiveStateAction } from "../types";
+import { useDynamicDDS } from "../shared-hooks";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+    isPrevStateCallback,
+} from "../internal";
+
+/**
+ * React hook for using a Live Share `LiveState`.
+ *
+ * @remarks
+ * Use this hook if you want to synchronize app state that will reset when all users leave the session.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
+ * @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 allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
+ * @returns ordered values: first value is the synchronized state value and the second is a setter to change the state value.
+ * The setter returns a void promise, which will throw if the user does not have the required roles to set.
+ */
+export function useLiveState<TState = any>(
+    uniqueKey: string,
+    initialState: TState,
+    allowedRoles?: UserMeetingRole[]
+): [TState, SetLiveStateAction<TState>, LiveState<TState> | undefined] {
+    const [currentState, setCurrentState] =
+        React.useState<TState>(initialState);
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    const { dds: liveState } = useDynamicDDS<LiveState<TState>>(
+        uniqueKey,
+        LiveState<TState>
+    );
+
+    const { container } = useFluidObjectsContext();
+
+    /**
+     * Change state callback that is user facing
+     * @param state TState to set
+     * @returns void promise, which will throw if the user does not have the required roles
+     */
+    const setState = React.useCallback(
+        async (state: TState | ((prevState: TState) => TState)) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "liveState",
+                    "setState"
+                );
+            }
+            if (liveState === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveState",
+                    "setState"
+                );
+            }
+            if (!liveState.isInitialized) {
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveState",
+                    "setState"
+                );
+            }
+            const valueToSet = isPrevStateCallback<TState>(state)
+                ? state(liveState.state)
+                : state;
+            return await liveState.set(valueToSet);
+        },
+        [container, liveState]
+    );
+
+    /**
+     * Setup change listeners and start `LiveState` if needed
+     */
+    React.useEffect(() => {
+        if (liveState === undefined) return;
+
+        const onStateChanged = (state: TState) => {
+            setCurrentState(state);
+        };
+        liveState.on("stateChanged", onStateChanged);
+        if (
+            liveState.initializeState === LiveDataObjectInitializeState.needed
+        ) {
+            liveState.initialize(initialState, allowedRoles);
+        }
+        if (JSON.stringify(liveState.state) !== JSON.stringify(initialState)) {
+            onStateChanged(liveState.state);
+        }
+
+        return () => {
+            liveState?.off("stateChanged", onStateChanged);
+        };
+    }, [liveState]);
+
+    return [currentState, setState, liveState];
+}