@microsoft/live-share-react 1.0.0-preview.10

package/src/shared-hooks/index.ts

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

package/src/shared-hooks/useDynamicDDS.ts

@@ -0,0 +1,71 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import React from "react";
+import { FluidObject, IFluidLoadable } from "@fluidframework/core-interfaces";
+import { useFluidObjectsContext } from "../providers";
+import { LoadableObjectClass } from "fluid-framework";
+
+/**
+ * Hook to gets or creates a DDS that corresponds to a given uniqueKey string.
+ * @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.
+ * @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>(
+    uniqueKey: string,
+    loadableObjectClass: LoadableObjectClass<T>,
+    onFirstInitialize?: (dds: T) => void,
+): {
+    dds: T | undefined;
+    error: Error | undefined;
+} {
+    const [dds, setDDS] = React.useState<T>();
+    const [error, setError] = React.useState<Error>();
+    /**
+     * Import container and DDS object register callbacks from AzureProvider.
+     */
+    const {
+        container,
+        clientRef,
+    } = useFluidObjectsContext();
+
+    /**
+     * 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.
+     */
+    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) {
+                    setDDS(dds);
+                }
+            } catch (error: unknown) {
+                if (error instanceof Error) {
+                    setError(error);
+                } else {
+                    setError(new Error("useDynamicDDS: an unknown error occurred while getting the DDS"));
+                }
+            }
+        };
+        onGetDDS();
+        return () => {
+            mounted = false;
+        };
+    }, [container, uniqueKey, onFirstInitialize]);
+
+    return {
+        dds,
+        error,
+    };
+}

package/src/shared-hooks/useSharedMap.ts

@@ -0,0 +1,132 @@
+/*!
+ * 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";
+
+/**
+ * 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.
+ *
+ * @template TData Optional typing for objects stored in the SharedMap. Default is `object` 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 extends object = object>(
+    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);
+
+    /**
+     * User facing: set a value to the Fluid `SharedMap`.
+     */
+    const setEntry = React.useCallback(
+        (key: string, value: TData) => {
+            if (!sharedMap) {
+                console.error(
+                    new Error("Cannot call set when sharedMap is undefined")
+                );
+                return;
+            }
+            sharedMap.set(key, value);
+        },
+        [sharedMap]
+    );
+
+    /**
+     * User facing: delete a value from the Fluid `SharedMap`.
+     */
+    const deleteEntry = React.useCallback(
+        (key: string) => {
+            if (!sharedMap) {
+                console.error(
+                    new Error("Cannot call remove when sharedMap is undefined")
+                );
+                return;
+            }
+            sharedMap.delete(key);
+        },
+        [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

@@ -0,0 +1,85 @@
+/*!
+ * 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";
+
+/**
+ * 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.).
+ *
+ * @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>(
+    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(
+        (updatedState: S) => {
+            setLocalState(updatedState);
+            updateSharedState(uniqueKey, updatedState);
+        },
+        [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];
+}

package/src/shared-hooks/useTaskManager.ts

@@ -0,0 +1,82 @@
+import React from "react";
+import { useDynamicDDS } from "./useDynamicDDS";
+import { TaskManager  } from "@fluid-experimental/task-manager";
+import { DynamicObjectRegistry } from "@microsoft/live-share";
+
+// Register TaskManager as dynamic object
+DynamicObjectRegistry.registerObjectClass(TaskManager, TaskManager.getFactory().type);
+
+/**
+ * A hook for joining a queue to lock tasks for a given id. Guaranteed to have only one user assigned to a task at a time.
+ * 
+ * @param uniqueKey the unique key for the TaskManager DDS
+ * @param taskId the task id to lock
+ * @returns stateful data about the status of the task lock
+ */
+export const useTaskManager = (uniqueKey: string, taskId?: string): {
+    lockedTask: boolean;
+    taskManager: TaskManager | undefined;
+} => {
+    /**
+     * TaskId currently in queue for
+     */
+    const currentTaskIdRef = React.useRef<string | undefined>(undefined);
+    /**
+     * Stateful boolean that is true when the user is currently assigned the task
+     */
+    const [lockedTask, setLockedTask] = React.useState<boolean>(false);
+
+    /**
+     * User facing: dynamically load the TaskManager DDS for the given unique key.
+     */
+    const { dds: taskManager } = useDynamicDDS<TaskManager>(uniqueKey, TaskManager);
+
+    /**
+     * When the task id changes, lock the task. When the task id is undefined, abandon the task.
+     */
+    React.useEffect(() => {
+        let mounted = true;
+        if (taskManager) {
+            if (taskId && currentTaskIdRef.current !== taskId) {
+                if (currentTaskIdRef.current) {
+                    taskManager.abandon(currentTaskIdRef.current);
+                    setLockedTask(false);
+                }
+                currentTaskIdRef.current = taskId;
+                const onLockTask = async () => {
+                    try {
+                        await taskManager.lockTask(taskId);
+                        if (mounted) {
+                            setLockedTask(true);
+                        }
+                    } catch {
+                        if (mounted) {
+                            setLockedTask(false);
+                            currentTaskIdRef.current = undefined;
+                        }
+                    }
+                }
+                onLockTask();
+            } else if (!taskId && currentTaskIdRef.current) {
+                taskManager.abandon(currentTaskIdRef.current);
+                setLockedTask(false);
+                currentTaskIdRef.current = undefined;
+            }
+        }
+        /**
+         * When the component unmounts, abandon the task if it is still locked
+         */
+        return () => {
+            mounted = false;
+            if (currentTaskIdRef.current) {
+                taskManager?.abandon(currentTaskIdRef.current);
+            }
+            currentTaskIdRef.current = undefined;
+        }
+    }, [taskManager, taskId]);
+
+    return {
+        lockedTask,
+        taskManager,
+    };
+};

package/src/types/ActionTypes.ts

@@ -0,0 +1,75 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import React from "react";
+import { IFluidLoadable } from "@fluidframework/core-interfaces";
+import { LoadableObjectClass } from "fluid-framework";
+import { ITimerConfig, PresenceState } from "@microsoft/live-share";
+
+// React actions
+export type SetSharedStateAction<T> = (state: T) => void;
+export type SetLocalStateAction = React.Dispatch<React.SetStateAction<any>>;
+
+// Fluid actions
+export type RegisterDDSSetStateAction = <T extends IFluidLoadable>(
+    uniqueKey: string,
+    componentId: string,
+    objectClass: LoadableObjectClass<T>,
+    setLocalStateAction: SetLocalStateAction,
+    onDidFirstInitialize?: (dds: T) => void
+) => void;
+
+export type UnregisterDDSSetStateAction = (
+    uniqueKey: string,
+    componentId: string
+) => void;
+
+export type RegisterSharedSetStateAction = (
+    uniqueKey: string,
+    componentId: string,
+    setLocalStateAction: SetLocalStateAction
+) => void;
+
+export type UnregisterSharedSetStateAction = (
+    uniqueKey: string,
+    componentId: string
+) => void;
+
+export type UpdateSharedStateAction = (uniqueKey: string, value: any) => void;
+
+export type DeleteSharedStateAction = (uniqueKey: string) => void;
+export type DisposeSharedStateAction = () => void;
+
+// Live Share actions
+
+export type SetLiveStateAction<TState = undefined> = (
+    state: TState,
+) => void;
+
+export type SendLiveEventAction<TEvent> = (event: TEvent) => void;
+
+export type OnReceivedLiveEventAction<TEvent> = (
+    event: TEvent,
+    local: boolean
+) => void;
+
+export type OnUpdateLivePresenceAction<TData extends object = object> = (
+    state?: PresenceState | undefined,
+    data?: TData | undefined
+) => void;
+
+export type OnStartTimerAction = (
+    duration: number
+) => void;
+
+export type OnPlayTimerAction = () => void;
+
+export type OnPauseTimerAction = () => void;
+
+export type OnTimerTickAction = (milliRemaining: number) => void;
+export type OnTimerDidStartAction = (timerConfig: ITimerConfig) => void;
+export type OnTimerDidPauseAction = (timerConfig: ITimerConfig) => void;
+export type OnTimerDidPlayAction = (timerConfig: ITimerConfig) => void;
+export type OnTimerDidFinishAction = (timerConfig: ITimerConfig) => void;

package/src/types/PropTypes.ts

@@ -0,0 +1,10 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+export type SharedMapInitialData<T> =
+    | Map<string, T>
+    | readonly (readonly [string, T])[]
+    | { [key: string]: T }
+    | undefined;

package/src/types/ResultTypes.ts

@@ -0,0 +1,187 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import { AzureContainerServices } from "@fluidframework/azure-client";
+import {
+    ITimerConfig,
+    LivePresenceUser,
+    LiveEvent,
+    LivePresence,
+    LiveTimer,
+} from "@microsoft/live-share";
+import { InkingManager, LiveCanvas } from "@microsoft/live-share-canvas";
+import {
+    CoordinationWaitPoint,
+    ExtendedMediaMetadata,
+    MediaPlayerSynchronizer,
+} from "@microsoft/live-share-media";
+import { IFluidContainer, SharedMap } from "fluid-framework";
+import { IReceiveLiveEvent } from "../interfaces";
+import {
+    OnPauseTimerAction,
+    OnPlayTimerAction,
+    OnStartTimerAction,
+    OnUpdateLivePresenceAction,
+    SendLiveEventAction,
+} from "./ActionTypes";
+
+export interface IAzureContainerResults {
+    /**
+     * Fluid Container.
+     */
+    container: IFluidContainer;
+    /**
+     * Azure container services which has information such as current socket connections.
+     */
+    services: AzureContainerServices;
+}
+
+export interface ILiveShareContainerResults extends IAzureContainerResults {
+    /**
+     * Whether the local user/client initially created the container.
+     */
+    created: boolean;
+}
+
+export interface IUseSharedMapResults<TData> {
+    /**
+     * Stateful map of most recent values from `SharedMap`.
+     */
+    map: ReadonlyMap<string, TData>;
+    /**
+     * Callback method to set/replace new entries in the `SharedMap`.
+     */
+    setEntry: (key: string, value: TData) => void;
+    /**
+     * Callback method to delete an existing entry in the `SharedMap`.
+     */
+    deleteEntry: (key: string) => void;
+    /**
+     * The Fluid `SharedMap` object, should you want to use it directly.
+     */
+    sharedMap: SharedMap | undefined;
+}
+
+export interface IUseLiveEventResults<TEvent extends object = object> {
+    /**
+     * The most recent event that has been received in the session.
+     */
+    latestEvent: IReceiveLiveEvent<TEvent> | undefined;
+    /**
+     * All received events since initializing this component, sorted from oldest -> newest.
+     */
+    allEvents: IReceiveLiveEvent<TEvent>[];
+    /**
+     * Callback method to send a new event to users in the session.
+     */
+    sendEvent: SendLiveEventAction<TEvent>;
+    /**
+     * The `LiveEvent` object, should you want to use it directly.
+     */
+    liveEvent: LiveEvent | undefined;
+}
+
+export interface IUseLiveTimerResults {
+    /**
+     * The current timer configuration.
+     */
+    timerConfig: ITimerConfig | undefined;
+    /**
+     * The time remaining in milliseconds.
+     */
+    milliRemaining: number | undefined;
+    /**
+     * The `LiveTimer` object, should you want to use it directly.
+     */
+    liveTimer: LiveTimer | undefined;
+    /**
+     * Start timer callback.
+     */
+    start: OnStartTimerAction;
+    /**
+     * Play timer callback.
+     */
+    play: OnPlayTimerAction;
+    /**
+     * Pause timer callback.
+     */
+    pause: OnPauseTimerAction;
+}
+
+export interface IUseLivePresenceResults<TData extends object = object> {
+    /**
+     * The local user's presence object.
+     */
+    localUser: LivePresenceUser<TData> | undefined;
+    /**
+     * List of non-local user's presence objects.
+     */
+    otherUsers: LivePresenceUser<TData>[];
+    /**
+     * List of all user's presence objects.
+     */
+    allUsers: LivePresenceUser<TData>[];
+    /**
+     * Live Share `LivePresence` object, should you want to use it directly.
+     */
+    livePresence: LivePresence<TData> | undefined;
+    /**
+     * Callback method to update the local user's presence.
+     */
+    updatePresence: OnUpdateLivePresenceAction<TData>;
+}
+
+export interface IUseMediaSynchronizerResults {
+    /**
+     * Stateful boolean on whether the session has an active suspension.
+     */
+    suspended: boolean;
+    /**
+     * Callback to initiate a play action for the group media session.
+     */
+    play: () => void;
+    /**
+     * Callback to initiate a pause action for the group media session.
+     */
+    pause: () => void;
+    /**
+     * Callback to initiate a seek action for the group media session.
+     *
+     * @param time timestamp of the video in seconds to seek to
+     */
+    seekTo: (time: number) => void;
+    /**
+     * Callback to change the track for the group media session.
+     * @param track media metadata object, track src string, or null
+     */
+    setTrack: (track: Partial<ExtendedMediaMetadata> | string | null) => void;
+    /**
+     * Begin a new suspension. If a wait point is not set, the suspension will only impact the
+     * local user.
+     *
+     * @param waitPoint Optional. Point in track to set the suspension at.
+     * @see CoordinationWaitPoint
+     */
+    beginSuspension: (waitPoint?: CoordinationWaitPoint) => void;
+    /**
+     * End the currently active exception.
+     */
+    endSuspension: () => void;
+    /**
+     * Live Share `MediaPlayerSynchronizer` object, should you want to use it directly.
+     */
+    mediaSynchronizer: MediaPlayerSynchronizer | undefined;
+}
+
+export interface IUseLiveCanvasResults {
+    /**
+     * Inking manager for the canvas, which is synchronized by `liveCanvas`. It is set when loaded and undefined while loading.
+     */
+    inkingManager: InkingManager | undefined;
+    /**
+     * Live Canvas data object which synchronizes inking & cursors in the session. It is set when loaded and undefined while loading.
+     */
+    liveCanvas: LiveCanvas | undefined;
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from "./ActionTypes";
+export * from "./ResultTypes";
+export * from "./PropTypes";

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from "./type-check";