@microsoft/live-share-react 2.0.0-internal.4 → 2.0.0-internal.6

package/src/providers/AzureProvider.tsx

@@ -3,21 +3,19 @@
  * 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 {
     AzureClientProps,
     AzureContainerServices,
 } from "@fluidframework/azure-client";
-import { IAzureContainerResults } from "../types";
+import { IAzureContainerResults } from "../types/index.js";
 import {
     ISharedStateRegistryResponse,
     useSharedStateRegistry,
-} from "../shared-hooks";
-import {
-    AzureTurboClient,
-    IFluidTurboClient,
-} from "@microsoft/live-share-turbo";
+} from "../shared-hooks/index.js";
+import { AzureLiveShareClient } from "@microsoft/live-share";
+import { BaseLiveShareClient } from "@microsoft/live-share/internal";
 
 /**
  * React Context provider values for `<AzureProvider>` and `<LiveShareProvider>`.
@@ -29,7 +27,7 @@ export interface IFluidContext extends ISharedStateRegistryResponse {
     /**
      * The Fluid Turbo client used for connecting to the Fluid container.
      */
-    clientRef: React.MutableRefObject<IFluidTurboClient>;
+    clientRef: React.MutableRefObject<BaseLiveShareClient>;
     /**
      * Stateful Fluid container.
      */
@@ -54,7 +52,7 @@ export interface IFluidContext extends ISharedStateRegistryResponse {
      */
     getContainer: (
         containerId: string,
-        initialObjects?: LoadableObjectClassRecord
+        fluidContainerSchema?: ContainerSchema
     ) => Promise<IAzureContainerResults>;
     /**
      * React callback function to create and connect to a new Fluid container.
@@ -67,7 +65,7 @@ export interface IFluidContext extends ISharedStateRegistryResponse {
      * @returns promise that returns a results object once complete (e.g., container, services, etc.)
      */
     createContainer: (
-        initialObjects?: LoadableObjectClassRecord,
+        fluidContainerSchema?: ContainerSchema,
         onInitializeContainer?: (container: IFluidContainer) => void
     ) => Promise<IAzureContainerResults>;
 }
@@ -125,9 +123,9 @@ export interface IAzureProviderProps {
      */
     createOnLoad?: boolean;
     /**
-     * The initial object schema to use when {@link joinOnLoad} or {@link createOnLoad} is true.
+     * The initial schema to use when {@link joinOnLoad} or {@link createOnLoad} is true.
      */
-    initialObjects?: LoadableObjectClassRecord;
+    fluidContainerSchema?: ContainerSchema;
     /**
      * Flag to control whether or not to connect to an existing container on first mount.
      *
@@ -142,8 +140,8 @@ export interface IAzureProviderProps {
  */
 export const AzureProvider: React.FC<IAzureProviderProps> = (props) => {
     const startedRef = React.useRef<boolean>(false);
-    const clientRef = React.useRef<AzureTurboClient>(
-        new AzureTurboClient(props.clientOptions)
+    const clientRef = React.useRef<AzureLiveShareClient>(
+        new AzureLiveShareClient(props.clientOptions)
     );
     const [results, setResults] = React.useState<
         IAzureContainerResults | undefined
@@ -158,14 +156,14 @@ export const AzureProvider: React.FC<IAzureProviderProps> = (props) => {
     const getContainer = React.useCallback(
         async (
             containerId: string,
-            initialObjects?: LoadableObjectClassRecord
+            fluidContainerSchema?: ContainerSchema
         ): Promise<IAzureContainerResults> => {
             return new Promise(async (resolve, reject) => {
                 try {
                     const results: IAzureContainerResults =
                         await clientRef.current.getContainer(
                             containerId,
-                            initialObjects
+                            fluidContainerSchema
                         );
                     setResults(results);
                     resolve(results);
@@ -185,13 +183,15 @@ export const AzureProvider: React.FC<IAzureProviderProps> = (props) => {
      */
     const createContainer = React.useCallback(
         async (
-            initialObjects?: LoadableObjectClassRecord,
+            fluidContainerSchema?: ContainerSchema,
             onInitializeContainer?: (container: IFluidContainer) => void
         ): Promise<IAzureContainerResults> => {
             return new Promise(async (resolve, reject) => {
                 try {
                     const results: IAzureContainerResults =
-                        await clientRef.current.createContainer(initialObjects);
+                        await clientRef.current.createContainer(
+                            fluidContainerSchema
+                        );
                     if (onInitializeContainer) {
                         onInitializeContainer(results.container);
                     }
@@ -225,16 +225,16 @@ export const AzureProvider: React.FC<IAzureProviderProps> = (props) => {
             return;
         startedRef.current = true;
         if (props.containerId && props.joinOnLoad) {
-            getContainer(props.containerId, props.initialObjects);
+            getContainer(props.containerId, props.fluidContainerSchema);
         } else if (!props.containerId && props.createOnLoad) {
-            createContainer(props.initialObjects);
+            createContainer(props.fluidContainerSchema);
         }
     }, [
         results?.container?.connectionState,
         props.containerId,
         props.createOnLoad,
         props.joinOnLoad,
-        props.initialObjects,
+        props.fluidContainerSchema,
         getContainer,
         createContainer,
     ]);

package/src/providers/LiveShareProvider.tsx

@@ -3,18 +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 { isITeamsJsSdkError } from "../internal";
+import { FluidContext, useFluidObjectsContext } from "./AzureProvider.js";
+import { isITeamsJsSdkError } from "../internal/index.js";
 
 /**
  * React Context provider values for `<LiveShareProvider>`.
@@ -52,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>;
 }
@@ -72,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);
@@ -103,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.
      */
@@ -114,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
@@ -132,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);
@@ -155,7 +257,7 @@ 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);
@@ -178,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];
+}