@microsoft/live-share-react 2.0.0-internal.5 → 2.0.0-internal.7

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();
 

package/src/live-hooks/useLivePresence.ts

@@ -5,20 +5,24 @@
 
 import {
     LivePresenceUser,
-    PresenceState,
     LivePresence,
     UserMeetingRole,
     LiveDataObjectInitializeState,
+    LivePresenceData,
+    PresenceStatus,
 } from "@microsoft/live-share";
 import React from "react";
-import { IUseLivePresenceResults, OnUpdateLivePresenceAction } from "../types";
-import { useDynamicDDS } from "../shared-hooks";
-import { useFluidObjectsContext } from "../providers";
+import {
+    IUseLivePresenceResults,
+    OnUpdateLivePresenceAction,
+} from "../types/index.js";
+import { useDynamicDDS } from "../shared-hooks/index.js";
+import { useFluidObjectsContext } from "../providers/index.js";
 import {
     ActionContainerNotJoinedError,
     ActionLiveDataObjectInitializedError,
     ActionLiveDataObjectUndefinedError,
-} from "../internal";
+} from "../internal/index.js";
 
 /**
  * React hook for using a Live Share `LivePresence`.
@@ -31,17 +35,66 @@ import {
  *
  * @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<TData extends object = object>(
+export function useLivePresence<TData extends LivePresenceData = any>(
     uniqueKey: string,
-    initialData?: TData | (() => TData) | undefined,
-    initialPresenceState: PresenceState = PresenceState.online,
+    initialData: TData | (() => TData),
     allowedRoles?: UserMeetingRole[]
 ): IUseLivePresenceResults<TData> {
     /**
@@ -55,18 +108,26 @@ export function useLivePresence<TData extends object = object>(
      */
     const { dds: livePresence } = useDynamicDDS<LivePresence<TData>>(
         uniqueKey,
-        LivePresence<TData>
+        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();
 
@@ -74,7 +135,7 @@ export function useLivePresence<TData extends object = object>(
      * User facing: callback to update the local user's presence.
      */
     const updatePresence: OnUpdateLivePresenceAction<TData> = React.useCallback(
-        async (data?: TData | undefined, state?: PresenceState | undefined) => {
+        async (data: TData) => {
             if (!container) {
                 throw new ActionContainerNotJoinedError(
                     "livePresence",
@@ -93,7 +154,7 @@ export function useLivePresence<TData extends object = object>(
                     "updatePresence"
                 );
             }
-            return await livePresence.update(data, state);
+            return await livePresence.update(data);
         },
         [container, livePresence]
     );
@@ -121,7 +182,6 @@ export function useLivePresence<TData extends object = object>(
                 isInitialDataCallback<TData>(initialData)
                     ? initialData()
                     : initialData,
-                initialPresenceState,
                 allowedRoles
             );
         }
@@ -136,11 +196,14 @@ export function useLivePresence<TData extends object = object>(
         localUser,
         otherUsers,
         allUsers,
+        onlineUsers,
         livePresence,
         updatePresence,
     };
 }
 
-function isInitialDataCallback<TData>(value: any): value is () => TData {
+function isInitialDataCallback<TData extends LivePresenceData>(
+    value: any
+): value is () => TData {
     return typeof value === "function";
 }

package/src/live-hooks/useLiveState.ts

@@ -9,15 +9,15 @@ import {
     UserMeetingRole,
 } from "@microsoft/live-share";
 import React from "react";
-import { SetLiveStateAction } from "../types";
-import { useDynamicDDS } from "../shared-hooks";
-import { useFluidObjectsContext } from "../providers";
+import { SetLiveStateAction } from "../types/index.js";
+import { useDynamicDDS } from "../shared-hooks/index.js";
+import { useFluidObjectsContext } from "../providers/index.js";
 import {
     ActionContainerNotJoinedError,
     ActionLiveDataObjectInitializedError,
     ActionLiveDataObjectUndefinedError,
     isPrevStateCallback,
-} from "../internal";
+} from "../internal/index.js";
 
 /**
  * React hook for using a Live Share `LiveState`.
@@ -31,6 +31,51 @@ import {
  * @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 function useLiveState<TState = any>(
     uniqueKey: string,

package/src/live-hooks/useLiveTimer.ts

@@ -21,14 +21,14 @@ import {
     OnTimerDidPlayAction,
     OnTimerDidStartAction,
     OnTimerTickAction,
-} from "../types";
-import { useDynamicDDS } from "../shared-hooks";
-import { useFluidObjectsContext } from "../providers";
+} from "../types/index.js";
+import { useDynamicDDS } from "../shared-hooks/index.js";
+import { useFluidObjectsContext } from "../providers/index.js";
 import {
     ActionContainerNotJoinedError,
     ActionLiveDataObjectInitializedError,
     ActionLiveDataObjectUndefinedError,
-} from "../internal";
+} from "../internal/index.js";
 
 /**
  * React hook for using Live Share's `LiveTimer` DDS.
@@ -46,6 +46,61 @@ import {
  * @param onPlay Optional. event handler callback for when the timer is resumed.
  * @param onFinish Optional. event handler callback for when the timer finishes.
  * @returns results and callbacks exposed via the hook.
+ * 
+ * @example
+ ```jsx
+import { useLiveTimer } from "@microsoft/live-share-react";
+
+// Define a unique key that differentiates this usage of `useLiveTimer` from others in your app
+const MY_UNIQUE_KEY = "timer-key";
+
+// Example component for using useLiveTimer
+export function CountdownTimer() {
+    const {
+        milliRemaining,
+        timerConfig,
+        liveTimer,
+        start,
+        pause,
+        play,
+    } = useLiveTimer("TIMER-ID");
+
+    // Render loading UI when creating LiveTimer instance for first time
+    if (!liveTimer) return <>Loading...</>;
+
+    return (
+        <div>
+            <button
+                onClick={() => {
+                    start(60 * 1000);
+                }}
+            >
+                {timerConfig === undefined ? "Start" : "Reset"}
+            </button>
+            {timerConfig !== undefined && (
+                <button
+                    onClick={() => {
+                        if (timerConfig.running) {
+                            pause();
+                        } else {
+                            play();
+                        }
+                    }}
+                >
+                    {timerConfig.running ? "Pause" : "Play"}
+                </button>
+            )}
+            {milliRemaining !== undefined && (
+                <p>
+                {`${Math.round(milliRemaining / 1000)} / ${
+                    Math.round(timerConfig.duration) / 1000
+                }`}
+                </p>
+            )}
+        </div>
+    );
+}
+ ```
  */
 export function useLiveTimer(
     uniqueKey: string,

package/src/live-hooks/useMediaSynchronizer.ts

@@ -16,14 +16,18 @@ import {
     MediaPlayerSynchronizer,
     MediaSessionCoordinatorSuspension,
 } from "@microsoft/live-share-media";
-import { isExtendedMediaMetadata, isMediaElement, isRefObject } from "../utils";
-import { useDynamicDDS } from "../shared-hooks";
-import { IUseMediaSynchronizerResults } from "../types";
-import { useFluidObjectsContext } from "../providers";
+import {
+    isExtendedMediaMetadata,
+    isMediaElement,
+    isRefObject,
+} from "../utils/index.js";
+import { useDynamicDDS } from "../shared-hooks/index.js";
+import { IUseMediaSynchronizerResults } from "../types/index.js";
+import { useFluidObjectsContext } from "../providers/index.js";
 import {
     ActionContainerNotJoinedError,
     ActionLiveDataObjectUndefinedError,
-} from "../internal";
+} from "../internal/index.js";
 
 /**
  * React hook for using a Live Share media `MediaPlayerSynchronizer`.
@@ -39,6 +43,67 @@ import {
  * @param viewOnly Optional. Flag for whether or not the media synchronizer should be in viewOnly mode.
  * @param canSendPositionUpdates Optional. Controls whether or not the local client is allowed to send position updates to the group.
  * @returns IUseMediaSynchronizerResults object.
+ * 
+ * @example
+ ```jsx
+import { useMediaSynchronizer } from "@microsoft/live-share-react";
+import { UserMeetingRole } from "@microsoft/live-share";
+import { MediaPlayerSynchronizerEvents } from "@microsoft/live-share-media";
+import { useRef, useEffect } from "react";
+
+const ALLOWED_ROLES = [UserMeetingRole.organizer, UserMeetingRole.presenter];
+
+const INITIAL_TRACK = "<YOUR_VIDEO_URL>";
+
+// Define a unique key that distinguishes this `useMediaSynchronizer` from others in your app
+const UNIQUE_KEY = "MEDIA-SESSION-ID";
+
+export function VideoPlayer() {
+  const videoRef = useRef(null);
+  const { play, pause, seekTo, mediaSynchronizer } = useMediaSynchronizer(
+    UNIQUE_KEY,
+    videoRef,
+    INITIAL_TRACK,
+    ALLOWED_ROLES
+  );
+
+  // Listen for groupaction events (optional)
+  useEffect(() => {
+    // Listen for player group actions for errors (e.g., play error)
+    const onGroupAction = (evt: IMediaPlayerSynchronizerEvent) => {
+      // See which user made the change (e.g., to display a notification)
+      const clientInfo = await synchronizer.mediaSession.getClientInfo(evt.details.clientId);
+    };
+    mediaSynchronizer?.addEventListener(
+      MediaPlayerSynchronizerEvents.groupaction,
+      onGroupAction
+    );
+    return () => {
+      mediaSynchronizer?.removeEventListener(
+        MediaPlayerSynchronizerEvents.groupaction,
+        onGroupAction
+      );
+    };
+  }, [mediaSynchronizer]);
+
+  return (
+    <div>
+      <video ref={videoRef} />
+      <button onClick={play}>
+        Play
+      </button>
+      <button onClick={pause}>
+        Pause
+      </button>
+      <button onClick={() => {
+        seekTo(0);
+      }}>
+        Start over
+      </button>
+    </div>
+  );
+}
+ ```
  */
 export function useMediaSynchronizer(
     uniqueKey: string,