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

package/src/providers/LiveShareProvider.tsx

@@ -3,17 +3,18 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-import { IFluidContainer, LoadableObjectClassRecord } from "fluid-framework";
+import { ContainerSchema, IFluidContainer } from "fluid-framework";
 import React from "react";
-import { useSharedStateRegistry } from "../shared-hooks";
+import { useSharedStateRegistry } from "../shared-hooks/index.js";
 import {
     ILiveShareClientOptions,
     ILiveShareHost,
     ILiveShareJoinResults,
     ITimestampProvider,
+    LiveShareClient,
 } from "@microsoft/live-share";
-import { FluidContext, useFluidObjectsContext } from "./AzureProvider";
-import { LiveShareTurboClient } from "@microsoft/live-share-turbo";
+import { FluidContext, useFluidObjectsContext } from "./AzureProvider.js";
+import { isITeamsJsSdkError } from "../internal/index.js";
 
 /**
  * React Context provider values for `<LiveShareProvider>`.
@@ -51,7 +52,7 @@ export interface ILiveShareContext {
      * @returns Promise with `ILiveShareJoinResults`, which includes the Fluid container
      */
     join: (
-        initialObjects?: LoadableObjectClassRecord,
+        fluidContainerSchema?: ContainerSchema,
         onInitializeContainer?: (container: IFluidContainer) => void
     ) => Promise<ILiveShareJoinResults>;
 }
@@ -71,6 +72,57 @@ export const LiveShareContext = React.createContext<ILiveShareContext>(
  * See `useFluidObjectsContext` for other information related to the Live Share session, such as the `container`.
  *
  * @returns current state of `LiveShareContext`
+ * 
+ * @example
+ ```jsx
+// LiveShareApp.jsx
+import { LiveShareProvider } from "@microsoft/live-share-react";
+import { LiveShareHost } from "@microsoft/teams-js";
+
+const host = LiveShareHost.create();
+
+export function LiveShareApp() {
+    // Call app.initialize() from teams-js before rendering LiveShareProvider
+
+    return (
+        <LiveShareProvider
+            joinOnLoad={true}
+            host={host}
+        >
+            <LiveShareLoader>
+                <LiveCheckbox />
+            </LiveShareLoader>
+        </LiveShareProvider>
+    );
+}
+
+// LiveShareLoader.jsx
+import { useLiveShareContext } from "@microsoft/live-share-react";
+
+export function LiveShareLoader({ children }) {
+    const { joined, joinError } = useLiveShareContext();
+
+    if (joinError) return <>{joinError.message}</>;
+    if (!joined) return <>Joining Live Share session...</>;
+    return <>{children}</>
+}
+
+// LiveCheckbox.jsx
+import { useLiveState } from "@microsoft/live-share-react";
+
+export function LiveCheckbox() {
+    const [checked, setChecked] = useLiveState("MY-UNIQUE-ID", false);
+    return (
+        <input
+            type="checkbox"
+            checked={checked}
+            onChange={() => {
+                setChecked(!checked);
+            }}
+        />
+    );
+}
+ ```
  */
 export const useLiveShareContext = (): ILiveShareContext => {
     const context = React.useContext(LiveShareContext);
@@ -102,9 +154,9 @@ export interface ILiveShareProviderProps {
      */
     host: ILiveShareHost;
     /**
-     * The initial object schema to use when {@link joinOnLoad} is true.
+     * The schema to use when {@link joinOnLoad} is true.
      */
-    initialObjects?: LoadableObjectClassRecord;
+    fluidContainerSchema?: ContainerSchema;
     /**
      * Optional. Flag to determine whether to join Fluid container on load.
      */
@@ -113,11 +165,62 @@ export interface ILiveShareProviderProps {
 
 /**
  * React Context provider component for using Live Share data objects & joining a Live Share session using `LiveShareClient`.
+ * 
+ * @example
+ ```jsx
+// LiveShareApp.jsx
+import { LiveShareProvider } from "@microsoft/live-share-react";
+import { LiveShareHost } from "@microsoft/teams-js";
+
+const host = LiveShareHost.create();
+
+export function LiveShareApp() {
+    // Call app.initialize() from teams-js before rendering LiveShareProvider
+
+    return (
+        <LiveShareProvider
+            joinOnLoad={true}
+            host={host}
+        >
+            <LiveShareLoader>
+                <LiveCheckbox />
+            </LiveShareLoader>
+        </LiveShareProvider>
+    );
+}
+
+// LiveShareLoader.jsx
+import { useLiveShareContext } from "@microsoft/live-share-react";
+
+export function LiveShareLoader({ children }) {
+    const { joined, joinError } = useLiveShareContext();
+
+    if (joinError) return <>{joinError.message}</>;
+    if (!joined) return <>Joining Live Share session...</>;
+    return <>{children}</>
+}
+
+// LiveCheckbox.jsx
+import { useLiveState } from "@microsoft/live-share-react";
+
+export function LiveCheckbox() {
+    const [checked, setChecked] = useLiveState("MY-UNIQUE-ID", false);
+    return (
+        <input
+            type="checkbox"
+            checked={checked}
+            onChange={() => {
+                setChecked(!checked);
+            }}
+        />
+    );
+}
+ ```
  */
 export const LiveShareProvider: React.FC<ILiveShareProviderProps> = (props) => {
     const startedRef = React.useRef(false);
     const clientRef = React.useRef(
-        new LiveShareTurboClient(props.host, props.clientOptions)
+        new LiveShareClient(props.host, props.clientOptions)
     );
     const [results, setResults] = React.useState<
         ILiveShareJoinResults | undefined
@@ -131,12 +234,12 @@ export const LiveShareProvider: React.FC<ILiveShareProviderProps> = (props) => {
      */
     const join = React.useCallback(
         async (
-            initialObjects?: LoadableObjectClassRecord,
+            fluidContainerSchema?: ContainerSchema,
             onInitializeContainer?: (container: IFluidContainer) => void
         ): Promise<ILiveShareJoinResults> => {
             startedRef.current = true;
             const results = await clientRef.current.join(
-                initialObjects,
+                fluidContainerSchema,
                 onInitializeContainer
             );
             setResults(results);
@@ -154,10 +257,21 @@ export const LiveShareProvider: React.FC<ILiveShareProviderProps> = (props) => {
         // We are not doing this here for backwards compatibility. View the README for more information.
         if (results !== undefined || startedRef.current || !props.joinOnLoad)
             return;
-        join(props.initialObjects).catch((error) => {
+        join(props.fluidContainerSchema).catch((error) => {
             console.error(error);
             if (error instanceof Error) {
                 setJoinError(error);
+            } else if (isITeamsJsSdkError(error)) {
+                setJoinError(
+                    new Error(
+                        `[${error.errorCode}] ${
+                            error.message ??
+                            "An unknown error occurred while joining container."
+                        }`
+                    )
+                );
+            } else if (typeof error == "string") {
+                setJoinError(new Error(error));
             } else {
                 setJoinError(
                     new Error(
@@ -166,7 +280,7 @@ export const LiveShareProvider: React.FC<ILiveShareProviderProps> = (props) => {
                 );
             }
         });
-    }, [results, props.joinOnLoad, props.initialObjects, join]);
+    }, [results, props.joinOnLoad, props.fluidContainerSchema, join]);
 
     return (
         <LiveShareContext.Provider

package/src/providers/index.ts

@@ -1,2 +1,2 @@
-export * from "./AzureProvider";
-export * from "./LiveShareProvider";
+export * from "./AzureProvider.js";
+export * from "./LiveShareProvider.js";

package/src/shared-hooks/index.ts

@@ -1,4 +1,6 @@
-export * from "./useSharedState";
-export * from "./useSharedMap";
-export * from "./useDynamicDDS";
-export * from "./useSharedStateRegistry";
+export * from "./useSharedState.js";
+export * from "./useSharedMap.js";
+export * from "./useDynamicDDS.js";
+export * from "./useSharedStateRegistry.js";
+export * from "./useSharedTree.js";
+export * from "./useTreeNode.js";

package/src/shared-hooks/internals/tree-node-constants.ts

@@ -0,0 +1,2 @@
+export const rawTNodeKey = "[[FluidTreeNode]]";
+export const proxiedChildrenKey = "[[FluidChildNodes]]";

package/src/shared-hooks/internals/tree-node-types.ts

@@ -0,0 +1,26 @@
+import { TreeNode, Tree } from "fluid-framework";
+import { proxiedChildrenKey, rawTNodeKey } from "./tree-node-constants.js";
+
+export interface ICustomProxyHandler<TNode extends TreeNode = TreeNode> {
+    [rawTNodeKey]: TNode;
+    [proxiedChildrenKey]: Record<string, TreeNode>;
+}
+
+export function isProxy(value: any): value is typeof Proxy {
+    return value && value["[[Handler]]"];
+}
+
+export function isCustomProxyHandler<TNode extends TreeNode = TreeNode>(
+    value: any
+): value is ICustomProxyHandler<TNode> {
+    return value?.[rawTNodeKey] !== undefined;
+}
+
+export function isTreeNode(value: any): value is TreeNode {
+    try {
+        Tree.schema(value);
+        return true;
+    } catch (_) {
+        return false;
+    }
+}

package/src/shared-hooks/internals/tree-node-utils.ts

@@ -0,0 +1,269 @@
+import { proxiedChildrenKey, rawTNodeKey } from "./tree-node-constants.js";
+import {
+    ICustomProxyHandler,
+    isCustomProxyHandler,
+    isTreeNode,
+    isProxy,
+} from "./tree-node-types.js";
+import { TreeNode, Tree } from "fluid-framework";
+import { Dispatch, SetStateAction } from "react";
+
+// Exported utils
+
+/**
+ * @internal
+ * Build a proxied version of a node and set its value to the treeMap provided
+ *
+ * @param rawNode the raw proxy node exposed by Fluid
+ * @param treeMap a map where Fluid's proxy node is mapped to our proxied node
+ * @returns TNode instance
+ */
+export function buildProxy<TNode extends TreeNode = TreeNode>(
+    rawNode: TNode,
+    treeMap: WeakMap<TreeNode, TreeNode>
+): TNode {
+    const previousProxy = treeMap.get(rawNode);
+    const previousProxyHandler = previousProxy
+        ? getCustomProxyHandler(previousProxy)
+        : undefined;
+    const proxyHandler: ProxyHandler<TreeNode> & ICustomProxyHandler<TNode> = {
+        // Add some extra stuff into the handler so we can store the original Fluid TreeNode and access it later
+        // Without overriding the rest of the getters in the object.
+        [rawTNodeKey]: rawNode,
+        [proxiedChildrenKey]: previousProxyHandler?.[proxiedChildrenKey] ?? {},
+        get: (target, prop, _) => {
+            if (prop === "[[Handler]]") {
+                return proxyHandler;
+            }
+            if (
+                typeof prop === "string" &&
+                proxyHandler[proxiedChildrenKey][prop]
+            ) {
+                return proxyHandler[proxiedChildrenKey][prop];
+            }
+            // pass in the rawNode so Fluid doesn't get confused by our proxy object and can find the flex node
+            const value = Reflect.get(target, prop, rawNode);
+            return typeof value === "function" &&
+                typeof prop === "string" &&
+                // TODO: need a better way of identifying which types of functions need to be proxied
+                // This is because if a developer uses an array prototype function, we need to return proxied
+                // objects so React can detect changes to those nodes...
+                !["map", "flatMap", "filter", "find", "indexOf"].includes(prop)
+                ? value.bind(rawNode)
+                : value;
+        },
+        set(target, p, newValue, _) {
+            return Reflect.set(target, p, newValue, rawNode);
+        },
+    };
+    const proxy = new Proxy(rawNode, proxyHandler);
+    // Track the proxy for the rawNode
+    treeMap.set(rawNode, proxy);
+    // Set raw node getter so we can access it before things like Tree.on
+    return proxy as TNode;
+}
+
+/**
+ * @internal
+ * Set up listeners for a given TreeNode.
+ * Will recursively call this function for all children nodes of each children until there are no more child nodes.
+ *
+ * @param parentRawNode raw parent node
+ * @param rootNodeForListener root node being listened to in useTreeNode
+ * @param treeMap a map where Fluid's proxy node is mapped to our proxied node
+ * @param unsubscribeListeners list of unsubscribe listeners, where we set the unsubscribe callbacks
+ * @param setProxyNode setter to set the root proxy node listened to in useTreeNode
+ */
+export function setUpListenersForNodeChildren<
+    TNode extends TreeNode = TreeNode,
+>(
+    parentRawNode: TreeNode,
+    rootNodeForListener: TreeNode,
+    treeMap: WeakMap<TreeNode, TreeNode>,
+    unsubscribeListeners: (() => void)[],
+    setProxyNode: Dispatch<SetStateAction<TNode>>
+) {
+    let entries = Object.entries(parentRawNode);
+    for (let i = 0; i < entries.length; i++) {
+        const [key, entry] = entries[i];
+        if (
+            !entry ||
+            ["string", "boolean", "number", "function"].includes(
+                typeof entry
+            ) ||
+            !isTreeNode(entry)
+        ) {
+            continue;
+        }
+        const rawEntry = getRawNode(entry);
+        const onNodeChanged = () => {
+            onTreeNodeChanged(
+                key,
+                rawEntry,
+                rootNodeForListener,
+                treeMap,
+                setProxyNode
+            );
+        };
+        const unsubscribe = Tree.on(rawEntry, "nodeChanged", onNodeChanged);
+        unsubscribeListeners.push(unsubscribe);
+        // Recursively listen to children nodes of this node
+        setUpListenersForNodeChildren(
+            rawEntry,
+            rootNodeForListener,
+            treeMap,
+            unsubscribeListeners,
+            setProxyNode
+        );
+    }
+}
+
+/**
+ * @internal
+ * Fluid only knows how to work with their proxied version of a TreeNode.
+ * We store a reference to that node in our proxied instances so we can easily use it when working with Fluid APIs.
+ *
+ * @param node get the raw node from the proxy
+ * @returns the raw proxied node that Fluid expects
+ */
+export function getRawNode<TNode extends TreeNode | undefined = TreeNode>(
+    node: TNode
+): TNode {
+    if (isProxy(node)) {
+        return getRawNodeFromProxy(node) as TNode;
+    }
+    return node;
+}
+
+// Non public utils
+
+/**
+ * Callback for when a tree node changed
+ *
+ * @param key key where the object is stored in the parent
+ * @param rawNode the raw node that changed
+ * @param rootNodeForListener the root node that is being listened to in useTreeNode
+ * @param treeMap a map where Fluid's proxy node is mapped to our proxied node
+ * @param setProxyNode setter to set the root proxy node listened to in useTreeNode
+ */
+function onTreeNodeChanged<TNode extends TreeNode = TreeNode>(
+    key: string,
+    rawNode: TreeNode,
+    rootNodeForListener: TreeNode,
+    treeMap: WeakMap<TreeNode, TreeNode>,
+    setProxyNode: Dispatch<SetStateAction<TNode>>
+) {
+    const proxyNode = buildProxy(rawNode, treeMap);
+    const parent = Tree.parent(rawNode);
+    if (!parent) {
+        throw new Error(
+            "useTreeNode onTreeNodeChanged: no parent found for rawParentNode"
+        );
+    }
+
+    proxyParentForNode(
+        key,
+        parent,
+        proxyNode,
+        rootNodeForListener,
+        treeMap,
+        setProxyNode
+    );
+}
+
+/**
+ * Proxies the parent and sets reference to the child node that changed.
+ *
+ * @param key key where the object is referenced in its parent node
+ * @param rawParentNode raw parent tree node
+ * @param proxyNode proxied instance of the node that changed
+ * @param rootNodeForListener root node listened to in useTreeNode
+ * @param treeMap a map where Fluid's proxy node is mapped to our proxied node
+ * @param setProxyNode setter to set the root proxy node listened to in useTreeNode
+ */
+function proxyParentForNode<TNode extends TreeNode = TreeNode>(
+    key: string,
+    rawParentNode: TreeNode,
+    proxyNode: TreeNode,
+    rootNodeForListener: TreeNode,
+    treeMap: WeakMap<TreeNode, TreeNode>,
+    setProxyNode: Dispatch<SetStateAction<TNode>>
+) {
+    const parentProxy = buildProxy(rawParentNode, treeMap);
+    let parentProxyHandler = getCustomProxyHandler(parentProxy);
+    if (!parentProxyHandler) {
+        throw new Error(
+            "useTreeNode proxyParentForNode: unexpected error, should always find valid proxy handler"
+        );
+    }
+    parentProxyHandler[proxiedChildrenKey][key] = proxyNode;
+    if (rawParentNode === rootNodeForListener) {
+        setProxyNode(parentProxy as TNode);
+    } else {
+        const parentOfParent = Tree.parent(rawParentNode);
+        if (!parentOfParent) {
+            throw new Error(
+                "useTreeNode proxyParentForNode: no parent found for rawParentNode"
+            );
+        }
+        const parentKey = findKeyOfNode(rawParentNode, parentOfParent);
+        proxyParentForNode(
+            parentKey,
+            parentOfParent,
+            parentProxy,
+            rootNodeForListener,
+            treeMap,
+            setProxyNode
+        );
+    }
+}
+
+/**
+ * Returns key where parent[key] == nodeToCheck
+ *
+ * @param nodeToCheck tree node to check
+ * @param parent parent node where nodeToCheck is a child of
+ * @returns the key for node
+ */
+function findKeyOfNode(nodeToCheck: TreeNode, parent: TreeNode): string {
+    let entries = Object.entries(parent);
+    for (let i = 0; i < entries.length; i++) {
+        const [key, entry] = entries[i];
+        if (
+            !entry ||
+            ["string", "boolean", "number", "function"].includes(
+                typeof entry
+            ) ||
+            !isTreeNode(entry)
+        ) {
+            continue;
+        }
+        if (entry === nodeToCheck) return key;
+    }
+    throw new Error("Did not find node as a child of parent");
+}
+
+// Type utils
+
+/**
+ * Gets the proxy handler for a given TreeNode, assuming `isCustomProxyHandler` returns true.
+ * @param proxy the proxied TreeNode to get the handler for.
+ * @returns the handler if valid, otherwise undefined
+ */
+function getCustomProxyHandler(proxy: TreeNode) {
+    const handler = (proxy as any)["[[Handler]]"];
+    if (isCustomProxyHandler(handler)) {
+        return handler;
+    }
+    return undefined;
+}
+
+/**
+ * Gets the raw node for a given proxied tree node
+ *
+ * @param proxy the proxied TreeNode to get the raw node for
+ * @returns the raw node if valid, otherwise undefined
+ */
+function getRawNodeFromProxy(proxy: TreeNode) {
+    return getCustomProxyHandler(proxy)?.[rawTNodeKey];
+}

package/src/shared-hooks/useDynamicDDS.ts

@@ -5,8 +5,8 @@
 
 import React from "react";
 import { FluidObject, IFluidLoadable } from "@fluidframework/core-interfaces";
-import { useFluidObjectsContext } from "../providers";
-import { LoadableObjectClass } from "fluid-framework";
+import { useFluidObjectsContext } from "../providers/AzureProvider.js";
+import { SharedObjectKind } from "fluid-framework";
 
 /**
  * Hook to gets or creates a DDS that corresponds to a given uniqueKey string.
@@ -14,17 +14,17 @@ import { LoadableObjectClass } from "fluid-framework";
  * @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.
+ * @template T Type of Fluid SharedObjectKind type to load. Must conform to IFluidLoadable interface.
  * @param uniqueKey uniqueKey value for the data object
- * @param loadableObjectClass Fluid LoadableObjectClass<T> to create/load.
+ * @param objectKind Fluid SharedObjectKind<T> to create/load.
  * @param onFirstInitialize Optional. Callback function for when the DDS is first loaded
  * @returns the DDS object, which is of type T when loaded and undefined while loading
  */
 export function useDynamicDDS<
-    T extends IFluidLoadable = FluidObject<any> & IFluidLoadable
+    T extends IFluidLoadable = FluidObject<any> & IFluidLoadable,
 >(
     uniqueKey: string,
-    loadableObjectClass: LoadableObjectClass<T>,
+    objectClass: SharedObjectKind<T>,
     onFirstInitialize?: (dds: T) => void
 ): {
     dds: T | undefined;
@@ -37,24 +37,38 @@ export function useDynamicDDS<
      */
     const { container, clientRef } = useFluidObjectsContext();
 
+    const mountedRef = React.useRef(false);
+    React.useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+
+    const getDDSPromisesRef = React.useRef<Map<string, Promise<T>>>(new Map());
+
     /**
      * Once container is available, this effect will register the setter method so that the DDS loaded
      * from `dynamicObjects` that matches `uniqueKey` can be passed back to this hook. If one does not yet exist,
      * a new DDS is automatically created. If multiple users try to create a DDS at the same time when this component first
-     * mounts, `live-share-turbo` ensures it will ultimately self correct using last-writer wins.
+     * mounts, `live-share` ensures it will ultimately self correct using last-writer wins.
      */
     React.useEffect(() => {
         if (container === undefined) return;
-        let mounted = true;
         // Callback method to set the `initialData` into the map when the DDS is first created.
         const onGetDDS = async () => {
             try {
-                const dds = await clientRef.current.getDDS<T>(
-                    uniqueKey,
-                    loadableObjectClass,
-                    onFirstInitialize
-                );
-                if (mounted) {
+                let getPromise = getDDSPromisesRef.current.get(uniqueKey);
+                if (!getPromise) {
+                    getPromise = clientRef.current.getDDS<T>(
+                        uniqueKey,
+                        objectClass,
+                        onFirstInitialize
+                    );
+                    getDDSPromisesRef.current.set(uniqueKey, getPromise);
+                }
+                const dds = await getPromise;
+                if (mountedRef.current) {
                     setDDS(dds);
                 }
             } catch (error: unknown) {
@@ -70,9 +84,6 @@ export function useDynamicDDS<
             }
         };
         onGetDDS();
-        return () => {
-            mounted = false;
-        };
     }, [container, uniqueKey, onFirstInitialize]);
 
     return {