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

package/src/shared-hooks/useSharedMap.ts

@@ -1,159 +1,159 @@
-/*!
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import React from "react";
-import { isEntries, isJSON, isMap } from "../utils";
-import { IUseSharedMapResults, SharedMapInitialData } from "../types";
-import { useDynamicDDS } from "./useDynamicDDS";
-import { SharedMap } from "fluid-framework";
-import { useFluidObjectsContext } from "../providers";
-import {
-    ActionContainerNotJoinedError,
-    ActionLiveDataObjectUndefinedError,
-} from "../internal";
-
-/**
- * React hook for using a Fluid `SharedMap`.
- *
- * @remarks
- * 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`
- * will be created, otherwise it will use the existing one.
- * @param initialData a JS Map, entries array, or JSON object to insert into the `SharedMap` when creating
- * the DDS for the first time.
- * @returns stateful `map` entries, `setEntry` callback, `deleteEntry` callback, and the Fluid `sharedMap`.
- */
-export function useSharedMap<TData = any>(
-    uniqueKey: string,
-    initialData?: SharedMapInitialData<TData>
-): IUseSharedMapResults<TData> {
-    /**
-     * Stateful readonly map (user facing) with most recent values from `SharedMap` and its setter method.
-     */
-    const [map, setMap] = React.useState<ReadonlyMap<string, TData>>(
-        getInitialData<TData>(initialData)
-    );
-
-    const onFirstInitialize = React.useCallback(
-        (newDDS: SharedMap): void => {
-            /**
-             * Callback method to set the `initialData` into the map when the `SharedMap` is first created.
-             * Only should be used as a prop to useDynamicDDS.
-             */
-            getInitialData(initialData).forEach((value, key) => {
-                newDDS.set(key, value);
-            });
-        },
-        [initialData]
-    );
-    /**
-     * User facing: dynamically load the SharedMap DDS for the given unique key.
-     */
-    const { dds: sharedMap } = useDynamicDDS<SharedMap>(
-        uniqueKey,
-        SharedMap,
-        onFirstInitialize
-    );
-
-    const { container } = useFluidObjectsContext();
-
-    /**
-     * User facing: set a value to the Fluid `SharedMap`.
-     */
-    const setEntry = React.useCallback(
-        (key: string, value: TData) => {
-            if (!container) {
-                throw new ActionContainerNotJoinedError(
-                    "sharedMap",
-                    "setEntry"
-                );
-            }
-            if (sharedMap === undefined) {
-                throw new ActionLiveDataObjectUndefinedError(
-                    "sharedMap",
-                    "setEntry"
-                );
-            }
-            sharedMap.set(key, value);
-        },
-        [container, sharedMap]
-    );
-
-    /**
-     * User facing: delete a value from the Fluid `SharedMap`.
-     */
-    const deleteEntry = React.useCallback(
-        (key: string) => {
-            if (!container) {
-                throw new ActionContainerNotJoinedError(
-                    "sharedMap",
-                    "deleteEntry"
-                );
-            }
-            if (sharedMap === undefined) {
-                throw new ActionLiveDataObjectUndefinedError(
-                    "sharedMap",
-                    "deleteEntry"
-                );
-            }
-            sharedMap.delete(key);
-        },
-        [container, sharedMap]
-    );
-
-    // Setup change listeners, initial values, etc.
-    React.useEffect(() => {
-        if (!sharedMap) return;
-
-        // Register valueChanged listener for `SharedMap`.
-        const onValueChanged = () => {
-            setMap(new Map<string, TData>(sharedMap.entries()));
-        };
-        sharedMap.on("valueChanged", onValueChanged);
-        // Get initial values from `SharedMap`.
-        onValueChanged();
-
-        return () => {
-            // Cleanup on component unmount.
-            sharedMap?.off("valueChanged", onValueChanged);
-        };
-    }, [sharedMap]);
-
-    return {
-        map,
-        setEntry,
-        deleteEntry,
-        sharedMap,
-    };
-}
-
-/**
- * Helper method for converting different initial data props into a Map<string, TData> to insert into the Fluid SharedMap
- * @template TData Optional typing for objects stored in the SharedMap. Default is `object` type.
- * @param initialData a JS Map, entries array, or JSON object.
- * @returns A Map<string, TData> with the entries provided.
- */
-function getInitialData<TData>(
-    initialData: SharedMapInitialData<TData>
-): Map<string, TData> {
-    if (isMap(initialData)) {
-        return initialData;
-    } else if (isEntries(initialData)) {
-        return new Map<string, TData>(initialData);
-    } else if (isJSON(initialData)) {
-        const values: (readonly [string, TData])[] = Object.keys(
-            initialData
-        ).map((key) => {
-            return [key, initialData[key]];
-        });
-        return new Map<string, TData>(values);
-    }
-    return new Map<string, TData>();
-}
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import React from "react";
+import { isEntries, isJSON, isMap } from "../utils";
+import { IUseSharedMapResults, SharedMapInitialData } from "../types";
+import { useDynamicDDS } from "./useDynamicDDS";
+import { SharedMap } from "fluid-framework";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
+
+/**
+ * React hook for using a Fluid `SharedMap`.
+ *
+ * @remarks
+ * 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`
+ * will be created, otherwise it will use the existing one.
+ * @param initialData a JS Map, entries array, or JSON object to insert into the `SharedMap` when creating
+ * the DDS for the first time.
+ * @returns stateful `map` entries, `setEntry` callback, `deleteEntry` callback, and the Fluid `sharedMap`.
+ */
+export function useSharedMap<TData = any>(
+    uniqueKey: string,
+    initialData?: SharedMapInitialData<TData>
+): IUseSharedMapResults<TData> {
+    /**
+     * Stateful readonly map (user facing) with most recent values from `SharedMap` and its setter method.
+     */
+    const [map, setMap] = React.useState<ReadonlyMap<string, TData>>(
+        getInitialData<TData>(initialData)
+    );
+
+    const onFirstInitialize = React.useCallback(
+        (newDDS: SharedMap): void => {
+            /**
+             * Callback method to set the `initialData` into the map when the `SharedMap` is first created.
+             * Only should be used as a prop to useDynamicDDS.
+             */
+            getInitialData(initialData).forEach((value, key) => {
+                newDDS.set(key, value);
+            });
+        },
+        [initialData]
+    );
+    /**
+     * User facing: dynamically load the SharedMap DDS for the given unique key.
+     */
+    const { dds: sharedMap } = useDynamicDDS<SharedMap>(
+        uniqueKey,
+        SharedMap,
+        onFirstInitialize
+    );
+
+    const { container } = useFluidObjectsContext();
+
+    /**
+     * User facing: set a value to the Fluid `SharedMap`.
+     */
+    const setEntry = React.useCallback(
+        (key: string, value: TData) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "sharedMap",
+                    "setEntry"
+                );
+            }
+            if (sharedMap === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "sharedMap",
+                    "setEntry"
+                );
+            }
+            sharedMap.set(key, value);
+        },
+        [container, sharedMap]
+    );
+
+    /**
+     * User facing: delete a value from the Fluid `SharedMap`.
+     */
+    const deleteEntry = React.useCallback(
+        (key: string) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "sharedMap",
+                    "deleteEntry"
+                );
+            }
+            if (sharedMap === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "sharedMap",
+                    "deleteEntry"
+                );
+            }
+            sharedMap.delete(key);
+        },
+        [container, sharedMap]
+    );
+
+    // Setup change listeners, initial values, etc.
+    React.useEffect(() => {
+        if (!sharedMap) return;
+
+        // Register valueChanged listener for `SharedMap`.
+        const onValueChanged = () => {
+            setMap(new Map<string, TData>(sharedMap.entries()));
+        };
+        sharedMap.on("valueChanged", onValueChanged);
+        // Get initial values from `SharedMap`.
+        onValueChanged();
+
+        return () => {
+            // Cleanup on component unmount.
+            sharedMap?.off("valueChanged", onValueChanged);
+        };
+    }, [sharedMap]);
+
+    return {
+        map,
+        setEntry,
+        deleteEntry,
+        sharedMap,
+    };
+}
+
+/**
+ * Helper method for converting different initial data props into a Map<string, TData> to insert into the Fluid SharedMap
+ * @template TData Optional typing for objects stored in the SharedMap. Default is `object` type.
+ * @param initialData a JS Map, entries array, or JSON object.
+ * @returns A Map<string, TData> with the entries provided.
+ */
+function getInitialData<TData>(
+    initialData: SharedMapInitialData<TData>
+): Map<string, TData> {
+    if (isMap(initialData)) {
+        return initialData;
+    } else if (isEntries(initialData)) {
+        return new Map<string, TData>(initialData);
+    } else if (isJSON(initialData)) {
+        const values: (readonly [string, TData])[] = Object.keys(
+            initialData
+        ).map((key) => {
+            return [key, initialData[key]];
+        });
+        return new Map<string, TData>(values);
+    }
+    return new Map<string, TData>();
+}

package/src/shared-hooks/useSharedState.ts

@@ -1,96 +1,96 @@
-/*!
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the Microsoft Live Share SDK License.
- */
-
-import React from "react";
-import { useFluidObjectsContext } from "../providers";
-import { DisposeSharedStateAction, SetSharedStateAction } from "../types";
-import { v4 as uuid } from "uuid";
-import { isPrevStateCallback } from "../internal";
-
-/**
- * Inspired by React's `useState` hook, `useSharedState` makes it easy to synchronize state in your app.
- *
- * @remarks
- * 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.
- * @param initialState a default state for the `SharedMap`.
- *
- * @returns a stateful value, the function to update it, and an optional dispose method to delete it from the `SharedMap`.
- */
-export function useSharedState<S = any>(
-    uniqueKey: string,
-    initialState: S
-): [S, SetSharedStateAction<S>, DisposeSharedStateAction] {
-    /**
-     * User facing: stateful value and non-user facing setter.
-     */
-    const [localState, setLocalState] = React.useState<S>(initialState);
-    /**
-     * Unique ID reference for the component.
-     */
-    const componentIdRef = React.useRef(uuid());
-    /**
-     * Register set state callbacks from AzureProvider and update/delete callbacks for initial object's `stateMap`.
-     */
-    const {
-        registerSharedSetStateAction,
-        unregisterSharedSetStateAction,
-        updateSharedState,
-        deleteSharedState,
-    } = useFluidObjectsContext();
-
-    /**
-     * User facing: callback to change the shared state.
-     */
-    const setSharedState: SetSharedStateAction<S> = React.useCallback(
-        (state: S | ((prevState: S) => S)) => {
-            setLocalState((prevState) => {
-                const valueToSet = isPrevStateCallback<S>(state)
-                    ? state(prevState)
-                    : state;
-                updateSharedState(uniqueKey, valueToSet);
-                return valueToSet;
-            });
-        },
-        [uniqueKey, setLocalState, updateSharedState]
-    );
-
-    /**
-     * User facing: callback to dispose the shared state from the `stateMap`.
-     */
-    const disposeSharedState: DisposeSharedStateAction =
-        React.useCallback(() => {
-            deleteSharedState(uniqueKey);
-        }, [uniqueKey, deleteSharedState]);
-
-    /**
-     * Once container is available, this effect will register the setter method so that the `S` value
-     * from `stateMap` that matches `uniqueKey` can be passed back to this hook whenever changed.
-     *
-     * @see registerSharedSetStateAction to see how new values from `stateMap` are passed to this hook.
-     * @see unregisterSharedSetStateAction to see how this component stops listening to changes in the `stateMap`.
-     */
-    React.useEffect(() => {
-        registerSharedSetStateAction(
-            uniqueKey,
-            componentIdRef.current,
-            setLocalState
-        );
-        return () => {
-            unregisterSharedSetStateAction(uniqueKey, componentIdRef.current);
-        };
-    }, [
-        uniqueKey,
-        registerSharedSetStateAction,
-        unregisterSharedSetStateAction,
-    ]);
-
-    return [localState, setSharedState, disposeSharedState];
-}
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import React from "react";
+import { useFluidObjectsContext } from "../providers";
+import { DisposeSharedStateAction, SetSharedStateAction } from "../types";
+import { v4 as uuid } from "uuid";
+import { isPrevStateCallback } from "../internal";
+
+/**
+ * Inspired by React's `useState` hook, `useSharedState` makes it easy to synchronize state in your app.
+ *
+ * @remarks
+ * 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.
+ * @param initialState a default state for the `SharedMap`.
+ *
+ * @returns a stateful value, the function to update it, and an optional dispose method to delete it from the `SharedMap`.
+ */
+export function useSharedState<S = any>(
+    uniqueKey: string,
+    initialState: S
+): [S, SetSharedStateAction<S>, DisposeSharedStateAction] {
+    /**
+     * User facing: stateful value and non-user facing setter.
+     */
+    const [localState, setLocalState] = React.useState<S>(initialState);
+    /**
+     * Unique ID reference for the component.
+     */
+    const componentIdRef = React.useRef(uuid());
+    /**
+     * Register set state callbacks from AzureProvider and update/delete callbacks for initial object's `stateMap`.
+     */
+    const {
+        registerSharedSetStateAction,
+        unregisterSharedSetStateAction,
+        updateSharedState,
+        deleteSharedState,
+    } = useFluidObjectsContext();
+
+    /**
+     * User facing: callback to change the shared state.
+     */
+    const setSharedState: SetSharedStateAction<S> = React.useCallback(
+        (state: S | ((prevState: S) => S)) => {
+            setLocalState((prevState) => {
+                const valueToSet = isPrevStateCallback<S>(state)
+                    ? state(prevState)
+                    : state;
+                updateSharedState(uniqueKey, valueToSet);
+                return valueToSet;
+            });
+        },
+        [uniqueKey, setLocalState, updateSharedState]
+    );
+
+    /**
+     * User facing: callback to dispose the shared state from the `stateMap`.
+     */
+    const disposeSharedState: DisposeSharedStateAction =
+        React.useCallback(() => {
+            deleteSharedState(uniqueKey);
+        }, [uniqueKey, deleteSharedState]);
+
+    /**
+     * Once container is available, this effect will register the setter method so that the `S` value
+     * from `stateMap` that matches `uniqueKey` can be passed back to this hook whenever changed.
+     *
+     * @see registerSharedSetStateAction to see how new values from `stateMap` are passed to this hook.
+     * @see unregisterSharedSetStateAction to see how this component stops listening to changes in the `stateMap`.
+     */
+    React.useEffect(() => {
+        registerSharedSetStateAction(
+            uniqueKey,
+            componentIdRef.current,
+            setLocalState
+        );
+        return () => {
+            unregisterSharedSetStateAction(uniqueKey, componentIdRef.current);
+        };
+    }, [
+        uniqueKey,
+        registerSharedSetStateAction,
+        unregisterSharedSetStateAction,
+    ]);
+
+    return [localState, setSharedState, disposeSharedState];
+}