@microsoft/live-share-react 1.2.0-preview.1 → 1.2.2-preview.0

package/src/providers/LiveShareProvider.tsx

@@ -12,9 +12,16 @@ import {
     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/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.