@microsoft/live-share-react 1.4.0-preview.0 → 2.0.0-internal.10

package/bin/esm/live-hooks/useLiveFollowMode.d.ts

@@ -0,0 +1,163 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+import { UserMeetingRole } from "@microsoft/live-share";
+import { IUseLiveFollowModeResults } from "../types/index.js";
+/**
+ * React hook for using a Live Share `LiveFollowMode`.
+ *
+ * @remarks
+ * Use this hook if you want to add the ability to follow specific users or let a user present to everyone in the session.
+ * Each user has their own `stateValue`, which is the value other users will reference when that user is presenting or being followed.
+ * The `state` response includes the user's `value` that the local user is "following", whether it be their own or someone else's.
+ * 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 `LiveFollowMode`. If one does not yet exist, a new one will be created.
+ * @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 declare function useLiveFollowMode<TData = any>(uniqueKey: string, initialData: TData | (() => TData), allowedRoles?: UserMeetingRole[]): IUseLiveFollowModeResults<TData>;
+//# sourceMappingURL=useLiveFollowMode.d.ts.map

package/bin/esm/live-hooks/useLiveFollowMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveFollowMode.d.ts","sourceRoot":"","sources":["../../../src/live-hooks/useLiveFollowMode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEH,eAAe,EAKlB,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0JG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAG,GAAG,EACzC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,KAAK,GAAG,CAAC,MAAM,KAAK,CAAC,EAClC,YAAY,CAAC,EAAE,eAAe,EAAE,GACjC,yBAAyB,CAAC,KAAK,CAAC,CA+QlC"}

package/bin/{live-hooks → esm/live-hooks}/useLiveFollowMode.js

@@ -13,9 +13,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { LiveDataObjectInitializeState, LiveFollowMode, } from "@microsoft/live-share";
 import React from "react";
-import { useDynamicDDS } from "../shared-hooks";
-import { useFluidObjectsContext } from "../providers";
-import { ActionContainerNotJoinedError, ActionLiveDataObjectInitializedError, ActionLiveDataObjectUndefinedError, } from "../internal";
+import { useDynamicDDS } from "../shared-hooks/index.js";
+import { useFluidObjectsContext } from "../providers/index.js";
+import { ActionContainerNotJoinedError, ActionLiveDataObjectInitializedError, ActionLiveDataObjectUndefinedError, } from "../internal/index.js";
 /**
  * React hook for using a Live Share `LiveFollowMode`.
  *
@@ -31,6 +31,145 @@ import { ActionContainerNotJoinedError, ActionLiveDataObjectInitializedError, Ac
  * @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(uniqueKey, initialData, allowedRoles) {
     /**
@@ -48,11 +187,15 @@ export function useLiveFollowMode(uniqueKey, initialData, allowedRoles) {
     /**
      * 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();
     /**
      * User facing: callback to update the local user's custom data for their follow state.

package/bin/esm/live-hooks/useLiveFollowMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveFollowMode.js","sourceRoot":"","sources":["../../../src/live-hooks/useLiveFollowMode.ts"],"names":[],"mappings":"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"}

package/bin/esm/live-hooks/useLivePresence.d.ts

@@ -0,0 +1,76 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+import { UserMeetingRole, LivePresenceData } from "@microsoft/live-share";
+import { IUseLivePresenceResults } from "../types/index.js";
+/**
+ * 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 Initial presence data object for the user. Can be value or a function to get the value.
+ * @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.
+ *
+ * @example
+ ```jsx
+import { useLivePresence } from "@microsoft/live-share-react";
+
+// Define a unique key that differentiates this usage of `useLivePresence` from others in your app
+const MY_UNIQUE_KEY = "presence-key";
+
+// Example component for using useLivePresence
+export const MyCustomPresence = () => {
+    const {
+        allUsers,
+        localUser,
+        livePresence,
+        updatePresence,
+    } = useLivePresence(MY_UNIQUE_KEY, {
+        picture: "DEFAULT_PROFILE_PICTURE_URL",
+        readyToStart: false,
+    });
+
+    // Callback to update the user's presence
+    const onToggleReady = () => {
+        updatePresence({
+            ...localUser.data,
+            readyToStart: !localUser.data.readyToStart,
+        });
+    }
+
+    // Render loading UI while loading LivePresence for first time
+    if (!livePresence) return <>Loading...</>;
+
+    // Render presence UI
+    return (
+        {allUsers.map((user) => (
+            <div key={user.userId}>
+                <div>
+                    {user.displayName}
+                </div>
+                <div>
+                    {`Ready: ${user.data.readyToStart}`}
+                </div>
+                {user.isLocalUser && (
+                    <button onClick={onToggleReady}>
+                        {"Toggle ready"}
+                    </button>
+                )}
+            </div>
+        ))}
+    );
+}
+ ```
+ */
+export declare function useLivePresence<TData extends LivePresenceData = any>(uniqueKey: string, initialData: TData | (() => TData), allowedRoles?: UserMeetingRole[]): IUseLivePresenceResults<TData>;
+//# sourceMappingURL=useLivePresence.d.ts.map

package/bin/esm/live-hooks/useLivePresence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLivePresence.d.ts","sourceRoot":"","sources":["../../../src/live-hooks/useLivePresence.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGH,eAAe,EAEf,gBAAgB,EAEnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACH,uBAAuB,EAE1B,MAAM,mBAAmB,CAAC;AAS3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS,gBAAgB,GAAG,GAAG,EAChE,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,KAAK,GAAG,CAAC,MAAM,KAAK,CAAC,EAClC,YAAY,CAAC,EAAE,eAAe,EAAE,GACjC,uBAAuB,CAAC,KAAK,CAAC,CAwGhC"}

package/bin/{live-hooks → esm/live-hooks}/useLivePresence.js

@@ -11,11 +11,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { PresenceState, LivePresence, LiveDataObjectInitializeState, } from "@microsoft/live-share";
+import { LivePresence, LiveDataObjectInitializeState, PresenceStatus, } from "@microsoft/live-share";
 import React from "react";
-import { useDynamicDDS } from "../shared-hooks";
-import { useFluidObjectsContext } from "../providers";
-import { ActionContainerNotJoinedError, ActionLiveDataObjectInitializedError, ActionLiveDataObjectUndefinedError, } from "../internal";
+import { useDynamicDDS } from "../shared-hooks/index.js";
+import { useFluidObjectsContext } from "../providers/index.js";
+import { ActionContainerNotJoinedError, ActionLiveDataObjectInitializedError, ActionLiveDataObjectUndefinedError, } from "../internal/index.js";
 /**
  * React hook for using a Live Share `LivePresence`.
  *
@@ -27,14 +27,64 @@ import { ActionContainerNotJoinedError, ActionLiveDataObjectInitializedError, Ac
  *
  * @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 initialData Initial presence data object for the user. Can be value or a function to get the value.
  * @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.
+ *
+ * @example
+ ```jsx
+import { useLivePresence } from "@microsoft/live-share-react";
+
+// Define a unique key that differentiates this usage of `useLivePresence` from others in your app
+const MY_UNIQUE_KEY = "presence-key";
+
+// Example component for using useLivePresence
+export const MyCustomPresence = () => {
+    const {
+        allUsers,
+        localUser,
+        livePresence,
+        updatePresence,
+    } = useLivePresence(MY_UNIQUE_KEY, {
+        picture: "DEFAULT_PROFILE_PICTURE_URL",
+        readyToStart: false,
+    });
+
+    // Callback to update the user's presence
+    const onToggleReady = () => {
+        updatePresence({
+            ...localUser.data,
+            readyToStart: !localUser.data.readyToStart,
+        });
+    }
+
+    // Render loading UI while loading LivePresence for first time
+    if (!livePresence) return <>Loading...</>;
+
+    // Render presence UI
+    return (
+        {allUsers.map((user) => (
+            <div key={user.userId}>
+                <div>
+                    {user.displayName}
+                </div>
+                <div>
+                    {`Ready: ${user.data.readyToStart}`}
+                </div>
+                {user.isLocalUser && (
+                    <button onClick={onToggleReady}>
+                        {"Toggle ready"}
+                    </button>
+                )}
+            </div>
+        ))}
+    );
+}
+ ```
  */
-export function useLivePresence(uniqueKey, initialData, initialPresenceState = PresenceState.online, allowedRoles) {
+export function useLivePresence(uniqueKey, initialData, allowedRoles) {
     /**
      * Stateful all user presence list and its non-user-facing setter method.
      */
@@ -42,20 +92,27 @@ export function useLivePresence(uniqueKey, initialData, initialPresenceState = P
     /**
      * User facing: dynamically load the DDS for the given unique key.
      */
-    const { dds: livePresence } = useDynamicDDS(uniqueKey, (LivePresence));
+    const { dds: livePresence } = useDynamicDDS(uniqueKey, LivePresence);
     /**
      * 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 onlineUsers = React.useMemo(() => {
+        return allUsers.filter((user) => user.status === PresenceStatus.online);
+    }, [allUsers]);
     const { container } = useFluidObjectsContext();
     /**
      * User facing: callback to update the local user's presence.
      */
-    const updatePresence = React.useCallback((data, state) => __awaiter(this, void 0, void 0, function* () {
+    const updatePresence = React.useCallback((data) => __awaiter(this, void 0, void 0, function* () {
         if (!container) {
             throw new ActionContainerNotJoinedError("livePresence", "updatePresence");
         }
@@ -65,7 +122,7 @@ export function useLivePresence(uniqueKey, initialData, initialPresenceState = P
         if (!livePresence.isInitialized) {
             throw new ActionLiveDataObjectInitializedError("livePresence", "updatePresence");
         }
-        return yield livePresence.update(data, state);
+        return yield livePresence.update(data);
     }), [container, livePresence]);
     /**
      * Setup change listeners and start `LivePresence` if needed
@@ -85,7 +142,7 @@ export function useLivePresence(uniqueKey, initialData, initialPresenceState = P
             LiveDataObjectInitializeState.needed) {
             livePresence.initialize(isInitialDataCallback(initialData)
                 ? initialData()
-                : initialData, initialPresenceState, allowedRoles);
+                : initialData, allowedRoles);
         }
         onPresenceChanged();
         return () => {
@@ -96,6 +153,7 @@ export function useLivePresence(uniqueKey, initialData, initialPresenceState = P
         localUser,
         otherUsers,
         allUsers,
+        onlineUsers,
         livePresence,
         updatePresence,
     };

package/bin/esm/live-hooks/useLivePresence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLivePresence.js","sourceRoot":"","sources":["../../../src/live-hooks/useLivePresence.ts"],"names":[],"mappings":"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"}

package/bin/esm/live-hooks/useLiveState.d.ts

@@ -0,0 +1,66 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+import { LiveState, UserMeetingRole } from "@microsoft/live-share";
+import { SetLiveStateAction } from "../types/index.js";
+/**
+ * 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.
+ *
+ * @example
+ ```jsx
+import { useLiveState } from "@microsoft/live-share-react";
+
+const planets = [
+  "Mercury",
+  "Venus",
+  "Earth",
+  "Mars",
+  "Jupiter",
+  "Saturn",
+  "Uranus",
+  "Neptune",
+];
+
+// Define a unique key that differentiates this usage of `useLiveState` from others in your app
+const MY_UNIQUE_KEY = "selected-planet-key";
+
+// Example component for using useLiveState
+export const MyCustomState = () => {
+  const [planet, setPlanet, liveState] = useLiveState(MY_UNIQUE_KEY, planets[0]);
+
+  // Render loading UI when creating LiveState instance for first time
+  if (!liveState) return <>Loading...</>;
+
+  // Render UI
+  return (
+    <div>
+      {`Current planet: ${planet}`}
+      {"Select a planet below:"}
+      {planets.map((planet) => (
+        <button
+          key={planet}
+          onClick={() => {
+            setPlanet(planet);
+          }}
+        >
+          {planet}
+        </button>
+      ))}
+    </div>
+  );
+};
+ ```
+ */
+export declare function useLiveState<TState = any>(uniqueKey: string, initialState: TState, allowedRoles?: UserMeetingRole[]): [TState, SetLiveStateAction<TState>, LiveState<TState> | undefined];
+//# sourceMappingURL=useLiveState.d.ts.map

package/bin/esm/live-hooks/useLiveState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveState.d.ts","sourceRoot":"","sources":["../../../src/live-hooks/useLiveState.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEH,SAAS,EACT,eAAe,EAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAUvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAG,GAAG,EACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,eAAe,EAAE,GACjC,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAwErE"}