@microsoft/live-share-react 2.0.0-internal.1 → 2.0.0-internal.10

package/bin/cjs/live-hooks/useLivePresence.js

@@ -0,0 +1,170 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLivePresence = useLivePresence;
+const live_share_1 = require("@microsoft/live-share");
+const react_1 = __importDefault(require("react"));
+const index_js_1 = require("../shared-hooks/index.js");
+const index_js_2 = require("../providers/index.js");
+const index_js_3 = require("../internal/index.js");
+/**
+ * React hook for using a Live Share `LivePresence`.
+ *
+ * @remarks
+ * Use this hook if you want to track presence for who is currently using this component, such as
+ * who is online or who is viewing a specific document. With presence, you can sent along any custom
+ * user data. This is useful for rendering a list of users, profile pictures, cursor positions, and more.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
+ * @template TData Optional typing for the custom user presence data object. Default is `object` type.
+ * @param uniqueKey The unique key for `LivePresence`. If one does not yet exist, a new one will be created.
+ * @param initialData Initial presence data object for the user. Can be value or a function to get the value.
+ * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
+ * will be created, otherwise it will use the existing one. Default value is ":<dds-default>"
+ * @returns stateful `localUser`, `otherUsers` list, and `allUsers` list. Also returns a callback method
+ * to update the local user's presence and the `LivePresence` Fluid object.
+ *
+ * @example
+ ```jsx
+import { useLivePresence } from "@microsoft/live-share-react";
+
+// Define a unique key that differentiates this usage of `useLivePresence` from others in your app
+const MY_UNIQUE_KEY = "presence-key";
+
+// Example component for using useLivePresence
+export const MyCustomPresence = () => {
+    const {
+        allUsers,
+        localUser,
+        livePresence,
+        updatePresence,
+    } = useLivePresence(MY_UNIQUE_KEY, {
+        picture: "DEFAULT_PROFILE_PICTURE_URL",
+        readyToStart: false,
+    });
+
+    // Callback to update the user's presence
+    const onToggleReady = () => {
+        updatePresence({
+            ...localUser.data,
+            readyToStart: !localUser.data.readyToStart,
+        });
+    }
+
+    // Render loading UI while loading LivePresence for first time
+    if (!livePresence) return <>Loading...</>;
+
+    // Render presence UI
+    return (
+        {allUsers.map((user) => (
+            <div key={user.userId}>
+                <div>
+                    {user.displayName}
+                </div>
+                <div>
+                    {`Ready: ${user.data.readyToStart}`}
+                </div>
+                {user.isLocalUser && (
+                    <button onClick={onToggleReady}>
+                        {"Toggle ready"}
+                    </button>
+                )}
+            </div>
+        ))}
+    );
+}
+ ```
+ */
+function useLivePresence(uniqueKey, initialData, allowedRoles) {
+    /**
+     * Stateful all user presence list and its non-user-facing setter method.
+     */
+    const [allUsers, setAllUsers] = react_1.default.useState([]);
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    const { dds: livePresence } = (0, index_js_1.useDynamicDDS)(uniqueKey, live_share_1.LivePresence);
+    /**
+     * User facing: list of non-local user's presence objects.
+     */
+    const otherUsers = react_1.default.useMemo(() => {
+        return allUsers.filter((user) => !user.isLocalUser);
+    }, [allUsers]);
+    /**
+     * User facing: local user's presence object.
+     */
+    const localUser = react_1.default.useMemo(() => {
+        return allUsers.find((user) => user.isLocalUser);
+    }, [allUsers]);
+    const onlineUsers = react_1.default.useMemo(() => {
+        return allUsers.filter((user) => user.status === live_share_1.PresenceStatus.online);
+    }, [allUsers]);
+    const { container } = (0, index_js_2.useFluidObjectsContext)();
+    /**
+     * User facing: callback to update the local user's presence.
+     */
+    const updatePresence = react_1.default.useCallback((data) => __awaiter(this, void 0, void 0, function* () {
+        if (!container) {
+            throw new index_js_3.ActionContainerNotJoinedError("livePresence", "updatePresence");
+        }
+        if (livePresence === undefined) {
+            throw new index_js_3.ActionLiveDataObjectUndefinedError("livePresence", "updatePresence");
+        }
+        if (!livePresence.isInitialized) {
+            throw new index_js_3.ActionLiveDataObjectInitializedError("livePresence", "updatePresence");
+        }
+        return yield livePresence.update(data);
+    }), [container, livePresence]);
+    /**
+     * Setup change listeners and start `LivePresence` if needed
+     */
+    react_1.default.useEffect(() => {
+        if (livePresence === undefined)
+            return;
+        const onPresenceChanged = () => {
+            const updatedLocalUsers = [];
+            livePresence === null || livePresence === void 0 ? void 0 : livePresence.getUsers().forEach((user) => {
+                updatedLocalUsers.push(user);
+            });
+            setAllUsers(updatedLocalUsers);
+        };
+        livePresence.on("presenceChanged", onPresenceChanged);
+        if (livePresence.initializeState ===
+            live_share_1.LiveDataObjectInitializeState.needed) {
+            livePresence.initialize(isInitialDataCallback(initialData)
+                ? initialData()
+                : initialData, allowedRoles);
+        }
+        onPresenceChanged();
+        return () => {
+            livePresence === null || livePresence === void 0 ? void 0 : livePresence.off("presenceChanged", onPresenceChanged);
+        };
+    }, [livePresence]);
+    return {
+        localUser,
+        otherUsers,
+        allUsers,
+        onlineUsers,
+        livePresence,
+        updatePresence,
+    };
+}
+function isInitialDataCallback(value) {
+    return typeof value === "function";
+}
+//# sourceMappingURL=useLivePresence.js.map

package/bin/cjs/live-hooks/useLivePresence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLivePresence.js","sourceRoot":"","sources":["../../../src/live-hooks/useLivePresence.ts"],"names":[],"mappings":"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"}

package/bin/{live-hooks → cjs/live-hooks}/useLiveState.d.ts

@@ -3,7 +3,7 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 import { LiveState, UserMeetingRole } from "@microsoft/live-share";
-import { SetLiveStateAction } from "../types";
+import { SetLiveStateAction } from "../types/index.js";
 /**
  * React hook for using a Live Share `LiveState`.
  *
@@ -16,6 +16,51 @@ import { SetLiveStateAction } from "../types";
  * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
  * @returns ordered values: first value is the synchronized state value and the second is a setter to change the state value.
  * The setter returns a void promise, which will throw if the user does not have the required roles to set.
+ *
+ * @example
+ ```jsx
+import { useLiveState } from "@microsoft/live-share-react";
+
+const planets = [
+  "Mercury",
+  "Venus",
+  "Earth",
+  "Mars",
+  "Jupiter",
+  "Saturn",
+  "Uranus",
+  "Neptune",
+];
+
+// Define a unique key that differentiates this usage of `useLiveState` from others in your app
+const MY_UNIQUE_KEY = "selected-planet-key";
+
+// Example component for using useLiveState
+export const MyCustomState = () => {
+  const [planet, setPlanet, liveState] = useLiveState(MY_UNIQUE_KEY, planets[0]);
+
+  // Render loading UI when creating LiveState instance for first time
+  if (!liveState) return <>Loading...</>;
+
+  // Render UI
+  return (
+    <div>
+      {`Current planet: ${planet}`}
+      {"Select a planet below:"}
+      {planets.map((planet) => (
+        <button
+          key={planet}
+          onClick={() => {
+            setPlanet(planet);
+          }}
+        >
+          {planet}
+        </button>
+      ))}
+    </div>
+  );
+};
+ ```
  */
 export declare function useLiveState<TState = any>(uniqueKey: string, initialState: TState, allowedRoles?: UserMeetingRole[]): [TState, SetLiveStateAction<TState>, LiveState<TState> | undefined];
 //# sourceMappingURL=useLiveState.d.ts.map

package/bin/cjs/live-hooks/useLiveState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveState.d.ts","sourceRoot":"","sources":["../../../src/live-hooks/useLiveState.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEH,SAAS,EACT,eAAe,EAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAUvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAG,GAAG,EACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,eAAe,EAAE,GACjC,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAwErE"}

package/bin/cjs/live-hooks/useLiveState.js

@@ -0,0 +1,134 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLiveState = useLiveState;
+const live_share_1 = require("@microsoft/live-share");
+const react_1 = __importDefault(require("react"));
+const index_js_1 = require("../shared-hooks/index.js");
+const index_js_2 = require("../providers/index.js");
+const index_js_3 = require("../internal/index.js");
+/**
+ * React hook for using a Live Share `LiveState`.
+ *
+ * @remarks
+ * Use this hook if you want to synchronize app state that will reset when all users leave the session.
+ * This hook can only be used in a child component of `<LiveShareProvider>` or `<AzureProvider>`.
+ *
+ * @param uniqueKey the unique key for the `LiveEvent`. If one does not yet exist, a new one will be created, otherwise it will use the existing one.
+ * @param initialState Optional. the initial state value of type TState
+ * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
+ * @returns ordered values: first value is the synchronized state value and the second is a setter to change the state value.
+ * The setter returns a void promise, which will throw if the user does not have the required roles to set.
+ *
+ * @example
+ ```jsx
+import { useLiveState } from "@microsoft/live-share-react";
+
+const planets = [
+  "Mercury",
+  "Venus",
+  "Earth",
+  "Mars",
+  "Jupiter",
+  "Saturn",
+  "Uranus",
+  "Neptune",
+];
+
+// Define a unique key that differentiates this usage of `useLiveState` from others in your app
+const MY_UNIQUE_KEY = "selected-planet-key";
+
+// Example component for using useLiveState
+export const MyCustomState = () => {
+  const [planet, setPlanet, liveState] = useLiveState(MY_UNIQUE_KEY, planets[0]);
+
+  // Render loading UI when creating LiveState instance for first time
+  if (!liveState) return <>Loading...</>;
+
+  // Render UI
+  return (
+    <div>
+      {`Current planet: ${planet}`}
+      {"Select a planet below:"}
+      {planets.map((planet) => (
+        <button
+          key={planet}
+          onClick={() => {
+            setPlanet(planet);
+          }}
+        >
+          {planet}
+        </button>
+      ))}
+    </div>
+  );
+};
+ ```
+ */
+function useLiveState(uniqueKey, initialState, allowedRoles) {
+    const [currentState, setCurrentState] = react_1.default.useState(initialState);
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    const { dds: liveState } = (0, index_js_1.useDynamicDDS)(uniqueKey, (live_share_1.LiveState));
+    const { container } = (0, index_js_2.useFluidObjectsContext)();
+    /**
+     * Change state callback that is user facing
+     * @param state TState to set
+     * @returns void promise, which will throw if the user does not have the required roles
+     */
+    const setState = react_1.default.useCallback((state) => __awaiter(this, void 0, void 0, function* () {
+        if (!container) {
+            throw new index_js_3.ActionContainerNotJoinedError("liveState", "setState");
+        }
+        if (liveState === undefined) {
+            throw new index_js_3.ActionLiveDataObjectUndefinedError("liveState", "setState");
+        }
+        if (!liveState.isInitialized) {
+            throw new index_js_3.ActionLiveDataObjectInitializedError("liveState", "setState");
+        }
+        const valueToSet = (0, index_js_3.isPrevStateCallback)(state)
+            ? state(liveState.state)
+            : state;
+        return yield liveState.set(valueToSet);
+    }), [container, liveState]);
+    /**
+     * Setup change listeners and start `LiveState` if needed
+     */
+    react_1.default.useEffect(() => {
+        if (liveState === undefined)
+            return;
+        const onStateChanged = (state) => {
+            setCurrentState(state);
+        };
+        liveState.on("stateChanged", onStateChanged);
+        if (liveState.initializeState === live_share_1.LiveDataObjectInitializeState.needed) {
+            liveState
+                .initialize(initialState, allowedRoles)
+                .then(() => onStateChanged(liveState.state));
+        }
+        else {
+            onStateChanged(liveState.state);
+        }
+        return () => {
+            liveState === null || liveState === void 0 ? void 0 : liveState.off("stateChanged", onStateChanged);
+        };
+    }, [liveState]);
+    return [currentState, setState, liveState];
+}
+//# sourceMappingURL=useLiveState.js.map

package/bin/cjs/live-hooks/useLiveState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveState.js","sourceRoot":"","sources":["../../../src/live-hooks/useLiveState.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;AA4EH,oCA4EC;AAtJD,sDAI+B;AAC/B,kDAA0B;AAE1B,uDAAyD;AACzD,oDAA+D;AAC/D,mDAK8B;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,SAAgB,YAAY,CACxB,SAAiB,EACjB,YAAoB,EACpB,YAAgC;IAEhC,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GACjC,eAAK,CAAC,QAAQ,CAAS,YAAY,CAAC,CAAC;IACzC;;OAEG;IACH,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAA,wBAAa,EACpC,SAAS,EACT,CAAA,sBAAiB,CAAA,CACpB,CAAC;IAEF,MAAM,EAAE,SAAS,EAAE,GAAG,IAAA,iCAAsB,GAAE,CAAC;IAE/C;;;;OAIG;IACH,MAAM,QAAQ,GAAG,eAAK,CAAC,WAAW,CAC9B,CAAO,KAA+C,EAAE,EAAE;QACtD,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,MAAM,IAAI,wCAA6B,CACnC,WAAW,EACX,UAAU,CACb,CAAC;QACN,CAAC;QACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,6CAAkC,CACxC,WAAW,EACX,UAAU,CACb,CAAC;QACN,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,CAAC;YAC3B,MAAM,IAAI,+CAAoC,CAC1C,WAAW,EACX,UAAU,CACb,CAAC;QACN,CAAC;QACD,MAAM,UAAU,GAAG,IAAA,8BAAmB,EAAS,KAAK,CAAC;YACjD,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC;YACxB,CAAC,CAAC,KAAK,CAAC;QACZ,OAAO,MAAM,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC,CAAA,EACD,CAAC,SAAS,EAAE,SAAS,CAAC,CACzB,CAAC;IAEF;;OAEG;IACH,eAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACjB,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO;QAEpC,MAAM,cAAc,GAAG,CAAC,KAAa,EAAE,EAAE;YACrC,eAAe,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC,CAAC;QACF,SAAS,CAAC,EAAE,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QAC7C,IACI,SAAS,CAAC,eAAe,KAAK,0CAA6B,CAAC,MAAM,EACpE,CAAC;YACC,SAAS;iBACJ,UAAU,CAAC,YAAY,EAAE,YAAY,CAAC;iBACtC,IAAI,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACJ,cAAc,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,OAAO,GAAG,EAAE;YACR,SAAS,aAAT,SAAS,uBAAT,SAAS,CAAE,GAAG,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QACnD,CAAC,CAAC;IACN,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC/C,CAAC"}

package/bin/{live-hooks → cjs/live-hooks}/useLiveTimer.d.ts

@@ -3,7 +3,7 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 import { UserMeetingRole } from "@microsoft/live-share";
-import { IUseLiveTimerResults, OnTimerDidFinishAction, OnTimerDidPauseAction, OnTimerDidPlayAction, OnTimerDidStartAction, OnTimerTickAction } from "../types";
+import { IUseLiveTimerResults, OnTimerDidFinishAction, OnTimerDidPauseAction, OnTimerDidPlayAction, OnTimerDidStartAction, OnTimerTickAction } from "../types/index.js";
 /**
  * React hook for using Live Share's `LiveTimer` DDS.
  *
@@ -20,6 +20,61 @@ import { IUseLiveTimerResults, OnTimerDidFinishAction, OnTimerDidPauseAction, On
  * @param onPlay Optional. event handler callback for when the timer is resumed.
  * @param onFinish Optional. event handler callback for when the timer finishes.
  * @returns results and callbacks exposed via the hook.
+ *
+ * @example
+ ```jsx
+import { useLiveTimer } from "@microsoft/live-share-react";
+
+// Define a unique key that differentiates this usage of `useLiveTimer` from others in your app
+const MY_UNIQUE_KEY = "timer-key";
+
+// Example component for using useLiveTimer
+export function CountdownTimer() {
+    const {
+        milliRemaining,
+        timerConfig,
+        liveTimer,
+        start,
+        pause,
+        play,
+    } = useLiveTimer("TIMER-ID");
+
+    // Render loading UI when creating LiveTimer instance for first time
+    if (!liveTimer) return <>Loading...</>;
+
+    return (
+        <div>
+            <button
+                onClick={() => {
+                    start(60 * 1000);
+                }}
+            >
+                {timerConfig === undefined ? "Start" : "Reset"}
+            </button>
+            {timerConfig !== undefined && (
+                <button
+                    onClick={() => {
+                        if (timerConfig.running) {
+                            pause();
+                        } else {
+                            play();
+                        }
+                    }}
+                >
+                    {timerConfig.running ? "Pause" : "Play"}
+                </button>
+            )}
+            {milliRemaining !== undefined && (
+                <p>
+                {`${Math.round(milliRemaining / 1000)} / ${
+                    Math.round(timerConfig.duration) / 1000
+                }`}
+                </p>
+            )}
+        </div>
+    );
+}
+ ```
  */
 export declare function useLiveTimer(uniqueKey: string, allowedRoles?: UserMeetingRole[], tickRate?: number, onTick?: OnTimerTickAction, onStart?: OnTimerDidStartAction, onPause?: OnTimerDidPauseAction, onPlay?: OnTimerDidPlayAction, onFinish?: OnTimerDidFinishAction): IUseLiveTimerResults;
 //# sourceMappingURL=useLiveTimer.d.ts.map

package/bin/cjs/live-hooks/useLiveTimer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveTimer.d.ts","sourceRoot":"","sources":["../../../src/live-hooks/useLiveTimer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGH,eAAe,EAGlB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACH,oBAAoB,EAIpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACpB,MAAM,mBAAmB,CAAC;AAS3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,wBAAgB,YAAY,CACxB,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,eAAe,EAAE,EAChC,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,qBAAqB,EAC/B,OAAO,CAAC,EAAE,qBAAqB,EAC/B,MAAM,CAAC,EAAE,oBAAoB,EAC7B,QAAQ,CAAC,EAAE,sBAAsB,GAClC,oBAAoB,CA8JtB"}