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

package/src/live-hooks/useLiveFollowMode.ts

@@ -28,6 +28,7 @@ import { IUseLiveFollowModeResults } from "../types";
  * 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.
  *
@@ -79,19 +80,19 @@ export function useLiveFollowMode<TData = any>(
             if (!container) {
                 throw new ActionContainerNotJoinedError(
                     "liveFollowMode",
-                    "updateState"
+                    "update"
                 );
             }
             if (liveFollowMode === undefined) {
                 throw new ActionLiveDataObjectUndefinedError(
                     "liveFollowMode",
-                    "updateState"
+                    "update"
                 );
             }
             if (!liveFollowMode.isInitialized) {
                 throw new ActionLiveDataObjectInitializedError(
                     "liveFollowMode",
-                    "updateState"
+                    "update"
                 );
             }
             return await liveFollowMode.update(stateValue);
@@ -106,19 +107,19 @@ export function useLiveFollowMode<TData = any>(
         if (!container) {
             throw new ActionContainerNotJoinedError(
                 "liveFollowMode",
-                "updateState"
+                "startPresenting"
             );
         }
         if (liveFollowMode === undefined) {
             throw new ActionLiveDataObjectUndefinedError(
                 "liveFollowMode",
-                "updateState"
+                "startPresenting"
             );
         }
         if (!liveFollowMode.isInitialized) {
             throw new ActionLiveDataObjectInitializedError(
                 "liveFollowMode",
-                "updateState"
+                "startPresenting"
             );
         }
         return await liveFollowMode.startPresenting();

package/src/live-hooks/useLivePresence.ts

@@ -27,6 +27,7 @@ import {
  * 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.

package/src/live-hooks/useLiveState.ts

@@ -24,6 +24,7 @@ import {
  *
  * @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

package/src/live-hooks/useLiveTimer.ts

@@ -30,6 +30,23 @@ import {
     ActionLiveDataObjectUndefinedError,
 } from "../internal";
 
+/**
+ * React hook for using Live Share's `LiveTimer` DDS.
+ *
+ * @remarks
+ * Use this hook to create a synchronized countdown timer in your app or to schedule synchronized tasks.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
+ * @param uniqueKey the unique key for the `LiveTimer`. If one does not yet exist, a new one will be created, otherwise it will use the existing one.
+ * @param allowedRoles Optional. the user roles that are allowed to start/stop/pause the timer.
+ * @param tickRate Optional. the interval in which the `milliRemaining` state should be updated and the `onTick` callback will trigger.
+ * @param onTick Optional. event handler callback for when an active timer ticks.
+ * @param onStart Optional. event handler callback for when the timer is started.
+ * @param onPause Optional. event handler callback for when the timer is paused.
+ * @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.
+ */
 export function useLiveTimer(
     uniqueKey: string,
     allowedRoles?: UserMeetingRole[],

package/src/live-hooks/useMediaSynchronizer.ts

@@ -30,6 +30,7 @@ import {
  *
  * @remarks
  * Use this hook if you want to synchronize the playback position of a video or audio element during a Live Share session.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
  *
  * @param uniqueKey uniqueKey value for the `LiveMediaSession` DDS object used by `MediaPlayerSynchronizer`.
  * @param mediaPlayerElement React RefObject containing object/element conforming to IMediaPlayer interface, `IMediaPlayer` object, or string id for <video> / <audio> element.

package/src/providers/AzureProvider.tsx

@@ -13,42 +13,127 @@ import { IAzureContainerResults } from "../types";
 import {
     ISharedStateRegistryResponse,
     useSharedStateRegistry,
-} from "../internal";
+} from "../shared-hooks";
 import {
     AzureTurboClient,
     IFluidTurboClient,
 } from "@microsoft/live-share-turbo";
 
-interface IFluidContext extends ISharedStateRegistryResponse {
+/**
+ * React Context provider values for `<AzureProvider>` and `<LiveShareProvider>`.
+ *
+ * @remarks
+ * To get the latest values, use the {@link useFluidObjectsContext} hook.
+ */
+export interface IFluidContext extends ISharedStateRegistryResponse {
+    /**
+     * The Fluid Turbo client used for connecting to the Fluid container.
+     */
     clientRef: React.MutableRefObject<IFluidTurboClient>;
+    /**
+     * Stateful Fluid container.
+     */
     container: IFluidContainer | undefined;
+    /**
+     * The Azure container services (e.g., audience).
+     */
     services: AzureContainerServices | undefined;
+    /**
+     * A stateful error object that is set if there was an error connecting to the Fluid container.
+     */
     joinError: Error | undefined;
+    /**
+     * React callback function to connect to an existing Fluid container.
+     *
+     * @remarks
+     * The results will also be set to their stateful counterparts for `container` and `services`.
+     *
+     * @param containerId the containerId to connect to.
+     * @param initialObjects Optional. initial object schema, which should match that passed to `createContainer()`.
+     * @returns promise that returns a results object once complete (e.g., container, services, etc.)
+     */
     getContainer: (
         containerId: string,
         initialObjects?: LoadableObjectClassRecord
     ) => Promise<IAzureContainerResults>;
+    /**
+     * React callback function to create and connect to a new Fluid container.
+     *
+     * @remarks
+     * The results will also be set to their stateful counterparts for `container` and `services`.
+     *
+     * @param initialObjects Optional. The initial object schema to apply to the container.
+     * @param onInitializeContainer Optional. A callback for when the container is first initialized, which is useful for setting default values to objects in `initialObjects`.
+     * @returns promise that returns a results object once complete (e.g., container, services, etc.)
+     */
     createContainer: (
         initialObjects?: LoadableObjectClassRecord,
         onInitializeContainer?: (container: IFluidContainer) => void
     ) => Promise<IAzureContainerResults>;
 }
 
+/**
+ * @hidden
+ */
 export const FluidContext = React.createContext<IFluidContext>(
     {} as IFluidContext
 );
 
+/**
+ * Hook to get the latest React context state for `FluidContext`.
+ *
+ * @remarks
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
+ * @returns current state of `LiveShareContext`
+ */
 export const useFluidObjectsContext = (): IFluidContext => {
     const context = React.useContext(FluidContext);
+    if (!isFluidObjectsContext(context)) {
+        throw new Error(
+            "@microsoft/live-share-react: attempting to use `useFluidObjectsContext()` from a component that is not a child of `<LiveShareProvider>` or `<AzureProvider>`.\nTo fix this error, ensure that you are only using Live Share hooks (e.g., `useLiveState`) from a child component of `<LiveShareProvider>` or `<AzureProvider>`."
+        );
+    }
     return context;
 };
 
-interface IAzureProviderProps {
+/**
+ * Prop types for {@link AzureProvider} component.
+ */
+export interface IAzureProviderProps {
+    /**
+     * Optional. React children node for the React Context Provider.
+     */
     children?: React.ReactNode;
+    /**
+     * Props for initializing a new `AzureClient` instance.
+     */
     clientOptions: AzureClientProps;
+    /**
+     * The `containerId` to connect to when {@link joinOnLoad} is true.
+     *
+     * @remarks
+     * If you pass in an `undefined` value when {@link createOnLoad} is true, a new container will be created.
+     */
     containerId?: string;
+    /**
+     * Flag to control whether or not a new container should be created on first mount.
+     *
+     * @remarks
+     * If no {@link containerId} is set when the component first mounts, setting this to `true` will automatically create a new container.
+     * This prop does not do anything if you are using `<LiveShareProvider>` instead of `<AzureProvider>`.
+     */
     createOnLoad?: boolean;
+    /**
+     * The initial object schema to use when {@link joinOnLoad} or {@link createOnLoad} is true.
+     */
     initialObjects?: LoadableObjectClassRecord;
+    /**
+     * Flag to control whether or not to connect to an existing container on first mount.
+     *
+     * @remarks
+     * Setting this to true will connect to the container if {@link containerId} is provided as a prop.
+     */
     joinOnLoad?: boolean;
 }
 
@@ -170,3 +255,7 @@ export const AzureProvider: React.FC<IAzureProviderProps> = (props) => {
         </FluidContext.Provider>
     );
 };
+
+function isFluidObjectsContext(value: any): value is IFluidContext {
+    return !!value?.clientRef;
+}

package/src/providers/LiveShareProvider.tsx

@@ -5,16 +5,23 @@
 
 import { IFluidContainer, LoadableObjectClassRecord } from "fluid-framework";
 import React from "react";
-import { useSharedStateRegistry } from "../internal";
+import { useSharedStateRegistry } from "../shared-hooks";
 import {
     ILiveShareClientOptions,
     ILiveShareHost,
     ILiveShareJoinResults,
     ITimestampProvider,
 } from "@microsoft/live-share";
-import { FluidContext } from "./AzureProvider";
+import { FluidContext, useFluidObjectsContext } from "./AzureProvider";
 import { LiveShareTurboClient } from "@microsoft/live-share-turbo";
 
+/**
+ * React Context provider values for `<LiveShareProvider>`.
+ *
+ * @remarks
+ * To get the latest values, use the {@link useLiveShareContext} hook.
+ * Use the {@link useFluidObjectsContext} hook for other relevant context values.
+ */
 export interface ILiveShareContext {
     /**
      * True if the local user created the Fluid container
@@ -34,10 +41,14 @@ export interface ILiveShareContext {
      */
     timestampProvider: ITimestampProvider | undefined;
     /**
-     * Join callback method
+     * Join callback method for manually connecting to the Fluid container.
+     *
+     * @remarks
+     * Use this callback if `joinOnLoad` is `false` or `undefined` in {@link ILiveShareProviderProps}.
+     *
      * @param initialObjects Optional. The initial objects for the Fluid container schema.
      * @param onInitializeContainer Optional. Callback for when the container is first created.
-     * @returns `ILiveShareJoinResults`, which includes the Fluid container
+     * @returns Promise with `ILiveShareJoinResults`, which includes the Fluid container
      */
     join: (
         initialObjects?: LoadableObjectClassRecord,
@@ -45,34 +56,57 @@ export interface ILiveShareContext {
     ) => Promise<ILiveShareJoinResults>;
 }
 
+/**
+ * @hidden
+ */
 export const LiveShareContext = React.createContext<ILiveShareContext>(
     {} as ILiveShareContext
 );
 
+/**
+ * Hook to get the latest React context state for `LiveShareContext`.
+ *
+ * @remarks
+ * This hook can only be used in a child component of `<LiveShareProvider>`.
+ * See `useFluidObjectsContext` for other information related to the Live Share session, such as the `container`.
+ *
+ * @returns current state of `LiveShareContext`
+ */
 export const useLiveShareContext = (): ILiveShareContext => {
     const context = React.useContext(LiveShareContext);
+    if (!isLiveShareContext(context)) {
+        throw new Error(
+            "@microsoft/live-share-react: attempting to use `useLiveShareContext()` from a component that is not a child of `<LiveShareProvider>`.\nTo fix this error, ensure that you are only using Live Share hooks (e.g., `useLiveState`) from a child component of `<LiveShareProvider>`."
+        );
+    }
     return context;
 };
 
-interface ILiveShareProviderProps {
+/**
+ * Prop types for {@link LiveShareProvider} component.
+ */
+export interface ILiveShareProviderProps {
     /**
      * Optional. React children node for the React Context Provider
      */
     children?: React.ReactNode;
     /**
-     * Optional. Options to pass into LiveShareClient initializer
+     * Optional. Options for initializing `LiveShareClient`.
      */
     clientOptions?: ILiveShareClientOptions;
     /**
-     * Host to initialize LiveShareClient with
+     * Host to initialize `LiveShareClient` with.
+     *
+     * @remarks
+     * If using the `LiveShareClient` class from `@microsoft/teams-js`, you must ensure that you have first called `teamsJs.app.initialize()` before calling `LiveShareClient.create()`.
      */
     host: ILiveShareHost;
     /**
-     * Optional. Initial Fluid objects to load when the container is first created
+     * The initial object schema to use when {@link joinOnLoad} is true.
      */
     initialObjects?: LoadableObjectClassRecord;
     /**
-     * Optional. Flag to determine whether to join Fluid container on load
+     * Optional. Flag to determine whether to join Fluid container on load.
      */
     joinOnLoad?: boolean;
 }
@@ -168,3 +202,9 @@ export const LiveShareProvider: React.FC<ILiveShareProviderProps> = (props) => {
         </LiveShareContext.Provider>
     );
 };
+
+function isLiveShareContext(value: any): value is ILiveShareContext {
+    return (
+        typeof value?.created === "boolean" && typeof value?.join === "function"
+    );
+}

package/src/shared-hooks/index.ts

@@ -1,3 +1,4 @@
 export * from "./useSharedState";
 export * from "./useSharedMap";
 export * from "./useDynamicDDS";
+export * from "./useSharedStateRegistry";

package/src/shared-hooks/useDynamicDDS.ts

@@ -10,6 +10,10 @@ import { LoadableObjectClass } from "fluid-framework";
 
 /**
  * Hook to gets or creates a DDS that corresponds to a given uniqueKey string.
+ *
+ * @remarks
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
  * @template T Type of Fluid LoadableObjectClass type to load. Must conform to IFluidLoadable interface.
  * @param uniqueKey uniqueKey value for the data object
  * @param loadableObjectClass Fluid LoadableObjectClass<T> to create/load.

package/src/shared-hooks/useSharedMap.ts

@@ -21,6 +21,7 @@ import {
  * The primary benefit of using the `useSharedMap` hook rather than the Fluid `SharedMap`
  * directly is that it integrates nicely with React state and automates repetitive tasks.
  * If you want to use `SharedMap` this hook creates directly, you can do that as well.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
  *
  * @template TData Optional typing for objects stored in the SharedMap. Default is `any` type.
  * @param uniqueKey the unique key for the `SharedMap`. If one does not yet exist, a new `SharedMap`

package/src/shared-hooks/useSharedState.ts

@@ -16,6 +16,7 @@ import { isPrevStateCallback } from "../internal";
  * Values set through this state is automatically attached to a `SharedMap` that the `AzureProvider`
  * creates. If you are synchronizing complex data structures that multiple users will be setting simultaneously,
  * consider using an optimized hook for your data structure (e.g., `useSharedMap`, `useSharedString`, etc.).
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
  *
  * @template S Typing for objects stored associated with the `uniqueKey`.
  * @param uniqueKey the unique key for a `SharedMap`. If you use the same key for multiple components, those components will reference the same state.

package/src/{internal → shared-hooks}/useSharedStateRegistry.ts

@@ -14,6 +14,9 @@ import {
     UpdateSharedStateAction,
 } from "../types";
 
+/**
+ * Response for the {@link useSharedStateRegistry} hook.
+ */
 export interface ISharedStateRegistryResponse {
     /**
      * Register a set state action callback
@@ -36,6 +39,9 @@ export interface ISharedStateRegistryResponse {
 /**
  * Hook used internally to keep track of the SharedSetStateActionMap for each unique key. It sets state values for provided keys and updates components listening to the values.
  *
+ * @remarks
+ * Use this if you are building a custom `LiveShareProvider` or `AzureProvider` implementation in your app.
+ *
  * @param results IAzureContainerResults response or undefined
  * @returns ISharedStateRegistryResponse object
  */