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

package/.nycrc.json

@@ -0,0 +1,10 @@
+{
+  "cache": false,
+  "extension": [".ts"],
+  "check-coverage": true,
+  "include": ["src/**"],
+  "statements": 90,
+  "branches": 90,
+  "functions": 95,
+  "lines": 90
+}

package/LICENSE

@@ -0,0 +1,87 @@
+MICROSOFT SOFTWARE LICENSE TERMS 
+
+MICROSOFT LIVE SHARE SDK – PRE-RELEASE VERSION 
+________________________________________
+
+These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW.  BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS. 
+
+1. INSTALLATION AND USE RIGHTS.  
+	a) General. You may install and use any number of copies of the software to develop and test your applications, solely for the purpose stated in 1(b) below and otherwise for your internal business purposes. 
+	b) Purpose. The use of this license provided under these terms is specifically limited to developing applications that interact solely within the Microsoft Teams Ecosystem. You may distribute the software according to Section 3 of these terms.  
+	c) Third Party Components. The software may include third party components with separate legal notices or governed by other agreements, as may be described in the ThirdPartyNotices file(s) accompanying the software. 
+	d) Microsoft Terms of Use. Some features of the software provide access to, or rely on, online services. The use of those services (but not the software) is governed by separate terms. This includes the Microsoft APIs Terms of Use which can be found at https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use and the Supplemental Terms of Use for Microsoft Azure which can be found at https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms. Please read them. The services may not be available in all regions. 
+
+2. PRE-RELEASE SOFTWARE.  The software is a pre-release version, and comes with no warranties as provided under Section 13.  It may not operate correctly.  We may change or discontinue the software at any time without notice.  We may also choose not to make this software generally commercially available.  It may be different from the commercially released version.  
+
+3. DISTRIBUTABLE CODE. The software contains code you are permitted to distribute (i.e. make available for third parties) in applications you develop, as described in this Section.  
+	a) Distribution Rights. The code and test files are distributable if included with the software.  
+		i. Third Party Distribution. You may permit distributors of your applications to copy and distribute any of this distributable code you elect to distribute with your applications. 
+	b) Distribution Requirements. For any code you distribute, you must: 
+		i. adhere to the Purpose stated in Section 1(b); and  
+		ii. indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your applications, except to the extent that any claim is based solely on the unmodified distributable code. 
+	c) Distribution Restrictions. You may not: 
+		i. use Microsoft’s trademarks or trade dress in your application in any way that suggests your application comes from or is endorsed by Microsoft; or 
+		ii. modify or distribute the source code of any distributable code so that any part of it becomes subject to any license that requires that the distributable code, any other part of the software, or any of Microsoft’s other intellectual property be disclosed or distributed in source code form, or that others have the right to modify it. 
+
+4. SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to): 
+	a) remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software;software; 
+	b) use the software in any way that is against the law or to create or propagate malware; or 
+	c) share, publish, distribute, or lease the software (except for any distributable code, subject to the terms above), provide the software as a stand-alone offering for others to use, or transfer the software or this agreement to any third party. 
+
+5. Data Protection. There are also some features in the software that may enable you to collect data from users of your applications. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to and obtaining consent from users of your applications. You can learn more about data collection and use in the help documentation and the privacy statement at https://aka.ms/privacy. Your use of the software operates as your consent to these practices.  
+
+6. CODE OF CONDUCT. By agreeing to these license terms, you’re agreeing that, when using the software, you will follow these rules: 
+	a) Don’t do anything illegal.
+	b) Don’t engage in any activity that exploits, harms, or threatens to harm children.  
+	c) Don’t send spam. Spam is unwanted or unsolicited bulk email, postings, contact requests, SMS (text messages), or instant messages.
+	d) Don’t publicly display or use the software to share inappropriate content or material (involving, for example, nudity, bestiality, pornography, offensive language, graphic violence, or criminal activity).  
+	e) Don’t engage in activity that is fraudulent, false or misleading (e.g., asking for money under false pretenses, impersonating someone else, manipulating the software to increase play count, or affect rankings, ratings, or comments). 
+	f) Don’t circumvent any restrictions on access to or availability of the software. 
+	g) Don’t engage in activity that is harmful to you, the software, or others (e.g., transmitting viruses, stalking, posting terrorist content, communicating hate speech, or advocating violence against others). 
+	h) Don’t infringe upon the rights of others (e.g., unauthorized sharing of copyrighted music or other copyrighted material, resale or other distribution of Bing maps, or photographs). 
+	i) Don’t engage in activity that violates the privacy of others. 
+	j) Don’t help others break these rules. 
+
+7. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit https://aka.ms/exporting. 
+
+8. SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind. 
+
+9. ENTIRE AGREEMENT. This agreement, terms referenced herein, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software.  
+
+10. APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles, except that the FAA governs everything related to arbitration. If you acquired the software in any other country, its laws apply, except that the FAA governs everything related to arbitration. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court (excluding arbitration). If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court (excluding arbitration). 
+
+11. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you: 
+	a. Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights. 
+	b. Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software. 
+	c. Germany and Austria. 
+		• Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software. 
+		• Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law. 
+		• Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence. 
+
+12. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. 
+
+13. PRE-RELEASE DISCLAIMER. AS A PRE-RELEASE VERSION, THIS SOFTWARE AND UNDERLYING SERVICES, ARE PROVIDED "AS-IS," "WITH ALL FAULTS," AND "AS AVAILABLE," AND ARE EXCLUDED FROM THE SERVICE LEVEL AGREEMENTS AND LIMITED WARRANTY. Pre-release versions may not be covered by customer support, and may be subject to reduced or different security, compliance and privacy commitments, as further explained in the Microsoft Privacy Statement, Microsoft Azure Trust Center, the Product Terms, the DPA, and any additional notices provided with the software. Where applicable, the following terms in the DPA do not apply to Previews: Processing of Personal Data; GDPR, Data Security.  
+
+14. LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT, OR INCIDENTAL DAMAGES. 
+
+	This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law. 
+	
+	It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages. 
+	
+	Please note: As this software is distributed in Canada, some of the clauses in this agreement are provided below in French. 
+
+	Remarque: Ce logiciel étant distribué au Canada, certaines des clauses dans ce contrat sont fournies ci-dessous en français. 
+
+	EXONÉRATION DE GARANTIE. Le logiciel visé par une licence est offert « tel quel ». Toute utilisation de ce logiciel est à votre seule risque et péril. Microsoft n’accorde aucune autre garantie expresse. Vous pouvez bénéficier de droits additionnels en vertu du droit local sur la protection des consommateurs, que ce contrat ne peut modifier. La ou elles sont permises par le droit locale, les garanties implicites de qualité marchande, d’adéquation à un usage particulier et d’absence de contrefaçon sont exclues. 
+
+	LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES DOMMAGES. Vous pouvez obtenir de Microsoft et de ses fournisseurs une indemnisation en cas de dommages directs uniquement à hauteur de 5,00 $ US. Vous ne pouvez prétendre à aucune indemnisation pour les autres dommages, y compris les dommages spéciaux, indirects ou accessoires et pertes de bénéfices. 
+
+	Cette limitation concerne: 
+
+	•	tout ce qui est relié au logiciel, aux services ou au contenu (y compris le code) figurant sur des sites Internet tiers ou dans des programmes tiers; et 
+
+	•	les réclamations au titre de violation de contrat ou de garantie, ou au titre de responsabilité stricte, de négligence ou d’une autre faute dans la limite autorisée par la loi en vigueur. 
+
+	Elle s’applique également, même si Microsoft connaissait ou devrait connaître l’éventualité d’un tel dommage. Si votre pays n’autorise pas l’exclusion ou la limitation de responsabilité pour les dommages indirects, accessoires ou de quelque nature que ce soit, il se peut que la limitation ou l’exclusion ci-dessus ne s’appliquera pas à votre égard. 
+
+	EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques. Vous pourriez avoir d’autres droits prévus par les lois de votre pays. Le présent contrat ne modifie pas les droits que vous confèrent les lois de votre pays si celles-ci ne le permettent pas. 

package/README.md

@@ -0,0 +1,543 @@
+# Live Share React
+
+Live Share React is designed to make building collaborative apps in React simple and intuitive, all using familiar patterns from functional React.
+
+Here is a simple example of how to get started:
+
+```javascript
+// 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}
+    >
+      <SharedCheckbox />
+    </LiveShareProvider>
+  );
+}
+
+// SharedCheckbox.jsx
+import { useSharedState } from "@microsoft/live-share-react";
+
+export function SharedCheckbox() {
+  const [checked, setChecked] = useSharedState("MY-UNIQUE-ID", false);
+  return (
+    <input
+      type="checkbox"
+      checked={checked}
+      onChange={() => {
+        setChecked(!checked);
+      }}
+    />
+  );
+}
+```
+
+## Getting started
+
+## Installing
+
+To add the latest version of the SDK to your application using NPM:
+
+```bash
+npm install @microsoft/live-share-react --save
+```
+
+or using [Yarn](https://yarnpkg.com/):
+
+```bash
+yarn add @microsoft/live-share-react
+```
+
+### Building package
+
+After cloning the [GitHub repository](https://www.github.com/microsoft/live-share-sdk), navigate to the root folder and perform:
+
+```bash
+npm install
+npm run build
+```
+
+This will use lerna to hoist and build all dependencies.
+
+### Sample app
+
+After installing/building the packages, you can also try out a [working sample here](../../samples/04.live-share-react/).
+
+## Live Share React vs. Vanilla Fluid
+
+Fluid Framework and Live Share are powerful frameworks that can greatly simplify the effort of building collaborative applications, but for many React applications, it can take time to get used to. This experimental package aims to strip away as much of that learning curve as possible.
+
+Where traditional Fluid utilizes a developer-defined object schema with a hierarchal structure, this package abstracts that out on your behalf. While you can still tap into more complicated hierarchies with this library, it is designed to behave more like blob storage / NoSQL.
+
+To use Fluid's distributed-data structures (DDS) or Live Share's live objects, you can simply use the corresponding React hook, providing a unique identifier for that DDS. If no DDS exists when the component is first mounted, we automatically create one for you. Otherwise, we will connect to the existing one.
+
+Much like React itself, this package is opinionated, and it may not be for everyone. To learn more about using Live Share the traditional way, see our [Live Share README](../live-share/README.md).
+
+## Types of hooks
+
+Live Share supports all of the live data structures provided through Live Share, and most of the officially supported DDS's available through Fluid Framework. If you have custom data objects, this package also exposes some underlying APIs for building your own custom React hooks.
+
+Here are the hooks provided by this library:
+
+### useSharedState
+
+Inspired by React's own `useState` hook, `useSharedState` should feel familiar to React developers. Under the hood, this hook uses a Fluid `SharedMap` dedicated for `useSharedState`, listening for changes to the key provided and automatically updating the shared state with any changes. And yes, if two components in the same application use the same key, those components will be in sync with each other!
+
+Since these keys are a `string` you provide while calling `useSharedState`, you can dynamically load these into your app as needed. With this in mind, we've also provided an optional `disposeState` action if the state is no longer relevant to your app. If you don't dispose it, then the data will persist in the container should you access it later (up to the lifetime of the Fluid container).
+
+The following example shows how `useSharedState` can be used to dynamically create collaborative features in your app on the fly:
+
+```javascript
+import { useSharedState } from "@microsoft/live-share-react";
+
+export function CounterCard({ card, onDelete }) {
+  const [count, setCount, disposeCount] = useSharedState(
+    `card-count:${card.id}`,
+    0
+  );
+  return (
+    <div className="card">
+      <h3>{card.title}</h3>
+      <button
+        onClick={() => {
+          setCount(count + 1);
+        }}
+      >
+        {"+1"}
+      </button>
+      <span>{`${count} `}</span>
+      <button
+        onClick={() => {
+          onDelete(card.id);
+          disposeCount();
+        }}
+      >
+        {"Delete"}
+      </button>
+    </div>
+  );
+}
+```
+
+_NOTE:_ While this hook will get you pretty far on its own, carefully consider which of our React hook is best for your scenario.
+
+### useSharedMap
+
+This hook loads a Fluid `SharedMap` corresponding with the key you provide. Compared to `useSharedState`, this hook allows you to render a collection of items with less risk of conflict when multiple users may be writing to the same object simultaneously. For example, rather than storing an entire list of objects in a single key of `useSharedState`, the map allows each item in the list to have its own unique key.
+
+While you write to keys individually, the `map` object exposed through the hook uses React state itself. Lets see an example in action:
+
+```javascript
+import { useSharedMap } from "@microsoft/live-share-react";
+import { v4 as uuid } from "uuid";
+
+export function CardList() {
+  const { map, setEntry, deleteEntry } = useSharedMap("CUSTOM-MAP-ID");
+  return (
+    <div>
+      <h2>{"Cards"}</h2>
+      <button
+        onClick={() => {
+          const id = uuid();
+          setEntry(id, {
+            id,
+            title: "Custom Card",
+          });
+        }}
+      >
+        {"+ Add card"}
+      </button>
+      <div className="flex wrap row hAlign">
+        {[...map.values()].map((cardValue) => (
+          <CounterCard
+            key={cardValue.id}
+            card={cardValue}
+            onDelete={deleteEntry}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### useLivePresence
+
+Presence makes it easy to track which users are currently in the session and assign custom data to them. Unlike other hooks, `useLivePresence` has a default ID set for you, but you can override it with your own if you'd like.
+
+```javascript
+import { useLivePresence } from "@microsoft/live-share-react";
+import { PresenceState } from "@microsoft/live-share";
+
+export function OnlineUsers() {
+  const { localUser, allUsers, updatePresence } = useLivePresence(
+    "CUSTOM-USER-ID", // optional user id
+    { name: "First Last" } // optional custom data object
+  );
+  return (
+    <div>
+      <h1>{"Online Users:"}</h1>
+      <div>
+        {allUsers
+          .filter((user) => user.state === PresenceState.online)
+          .map((user) => (
+            <div key={user.userId}>{user.name}</div>
+          ))}
+      </div>
+      <button
+        onClick={() => {
+          updatePresence(
+            localUser?.state === PresenceState.offline
+              ? PresenceState.online
+              : PresenceState.offline,
+            localUser.data
+          );
+        }}
+      >
+        {`Toggle status`}
+      </button>
+    </div>
+  );
+}
+```
+
+### useLiveState
+
+Unlike `useSharedState`, `useLiveState` is only stateful while one or more users are connected to it. This can make it easy to have state that behaves more closely to a regular React `useState`, when desireable.
+
+This component also features role verification, which allows you to choose the Teams meeting roles which are eligible to edit the state, if needed.
+
+```javascript
+import { useLiveState } from "@microsoft/live-share-react";
+import { UserMeetingRole } from "@microsoft/live-share";
+
+const ALLOWED_ROLES = [UserMeetingRole.organizer, UserMeetingRole.presenter ];
+
+export function AppState() {
+  const [state, data, setState] = useLiveState("CUSTOM-STATE-ID", ALLOWED_ROLES, ExampleAppState.WAITING);
+
+  if (state === ExampleAppState.WAITING) {
+    return (
+      <div>
+        <h2>{"Waiting"}</h2>
+        <button
+          onClick={() => {
+            setState(ExampleAppState.START, {
+              startedBy: "First Last",
+            });
+          }}
+        >
+          {"Start"}
+        </button>
+      </div>
+    );
+  }
+  return (
+    <div>
+      <h2>{`Started by: ${data!.startedBy}`}</h2>
+      <button
+        onClick={() => {
+          setState(ExampleAppState.WAITING, undefined);
+        }}
+      >
+        {"End"}
+      </button>
+    </div>
+  );
+};
+```
+
+### useLiveEvent
+
+If you want to generic JSON between clients that is completely transient, then `useLiveEvent` is a great choice. A good example of that is a reactions feature similar to that in Microsoft Teams meetings, since people joining a meeting late don't need to see reactions from earlier in the meeting.
+
+Here is a simple example:
+
+```javascript
+import { useLiveEvent } from "@microsoft/live-share-react";
+
+export function Reactions() {
+  const { latestEvent, sendEvent } = useLiveEvent("EVENT-ID");
+
+  return (
+    <div>
+      {/* Buttons for sending reactions */}
+      <button
+        onClick={() => {
+          sendEvent({ emoji: "❤️" });
+        }}
+      >
+        {"❤️"}
+      </button>
+      <button
+        onClick={() => {
+          sendEvent({ emoji: "😂" });
+        }}
+      >
+        {"😂"}
+      </button>
+      {/* Show latest reaction */}
+      {latestEvent?.local === false && (
+        <div>{`Received: ${latestEvent?.event.emoji}`}</div>
+      )}
+      {latestEvent?.local === true && (
+        <div>{`Sent: ${latestEvent?.event.emoji}`}</div>
+      )}
+    </div>
+  );
+}
+```
+
+### useLiveTimer
+
+You can use the `useLiveTimer` hook to build a synchronized countdown timer. A good example of that might be a meditation timer or a countdown for a round in a group activity.
+
+Here is a simple example:
+
+```javascript
+import { useLiveTimer } from "@microsoft/live-share-react";
+
+export function CountdownTimer() {
+  const { milliRemaining, timerConfig, start, pause, play } = useLiveTimer("TIMER-ID");
+
+  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>
+  );
+}
+```
+
+### useMediaSynchronizer
+
+If you want to synchronize video content, `@microsoft/live-share-media` is also supported by this package through the `useMediaSynchronizer` hook. Using any `HTMLMediaPlayer` element, or a delegate object matching our `IMediaPlayer` interface, you can easily build watch together capabilities into your app.
+
+Let's see this in action:
+
+```javascript
+import { useMediaSynchronizer } from "@microsoft/live-share-react";
+import { UserMeetingRole } from "@microsoft/live-share";
+import { useRef } from "react";
+
+const ALLOWED_ROLES = [UserMeetingRole.organizer, UserMeetingRole.presenter];
+
+const INITIAL_TRACK =
+  "https://storage.googleapis.com/media-session/big-buck-bunny/trailer.mov";
+
+export function VideoPlayer() {
+  const videoRef = useRef(null);
+  const { play, pause } = useMediaSynchronizer(
+    "MEDIA-SESSION-ID",
+    videoRef,
+    INITIAL_TRACK,
+    ALLOWED_ROLES
+  );
+
+  return (
+    <div>
+      <video ref={videoRef} />
+      <button onClick={play}>{"Play"}</button>
+      <button onClick={pause}>{"Pause"}</button>
+    </div>
+  );
+}
+```
+
+### useLiveCanvas
+
+If you want to add turn-key inking & cursors, use the `useLiveCanvas` hook, powered by `@microsoft/live-share-canvas`.
+
+Let's see this in action:
+
+```javascript
+import { useLiveCanvas } from "@microsoft/live-share-react";
+import { InkingTool } from "@microsoft/live-share-canvas";
+import { useRef } from "react";
+
+export const ExampleLiveCanvas = () => {
+    const liveCanvasRef = useRef(null);
+    const { liveCanvas, inkingManager } = useLiveCanvas(
+        "CUSTOM-LIVE-CANVAS",
+        liveCanvasRef,
+    );
+
+    return (
+        {/** Canvas currently needs to be a child of a parent with absolute styling */}
+        <div style={{ position: "absolute"}}>
+            <div
+                ref={liveCanvasRef}
+                // Best practice is to not define inline styles
+                style={{ width: "556px", height: "224px" }}
+            />
+            {!!liveCanvas && (
+                <div>
+                    <button
+                        onClick={() => {
+                            inkingManager.tool = InkingTool.pen;
+                        }}
+                    >
+                        {"Pen"}
+                    </button>
+                    <button
+                        onClick={() => {
+                            inkingManager.tool = InkingTool.laserPointer;
+                        }}
+                    >
+                        {"Laser pointer"}
+                    </button>
+                </div>
+            )}
+        </div>
+    );
+};
+```
+
+### useTaskManager
+
+If you want to ensure that only one user is responsible for a given task, you can use `useTaskManager`, which uses Fluid's `TaskManager` DDS.
+
+Let's see this in action:
+
+```javascript
+import { useTaskManager } from "@microsoft/live-share-react";
+
+export const ExampleTaskManager = () => {
+    const [taskId, setTaskId] = useState(undefined);
+    const { lockedTask } = useTaskManager(
+        "CUSTOM-TASK-MANAGER",
+        taskId,
+    );
+
+    const displayText = lockedTask
+        ? "You are assigned the task"
+        : "Waiting for task assignment";
+
+    return (
+        <div>
+            {!taskId && (
+                <button
+                    onClick={() => {
+                        setTaskId("task-id")
+                    }}
+                >
+                    {'Join task queue'}
+                </button>
+            )}
+            {taskId && (
+                <button
+                    onClick={() => {
+                        setTaskId(undefined)
+                    }}
+                >
+                    {'Leave task queue'}
+                </button>
+            )}
+            <p>{displayText}</p>
+        </div>
+    );
+};
+```
+
+### Custom Fluid object hooks
+
+If you want to dynamically load a custom Fluid object in your app, use the `useDynamicDDS` to create a custom hook. This is the same hook that Live Share React uses internally within our custom hooks, such as `useLiveEvent`. If you made a custom data object or are using one of Fluid's experimental data structures, you also must register your Fluid `LoadableObjectClass` with `DynamicObjectRegistry.registerObjectClass` to `@microsoft/live-share`, if it is not already.
+
+Implementations may vary for each dynamic object & hook. We will try and update this package periodically with new packages released by Fluid Framework and Live Share, as they are published.
+
+Example:
+
+```javascript
+import { DynamicObjectRegistry } from "@microsoft/live-share";
+import { useDynamicDDS } from "@microsoft/live-share-react";
+import { SharedTree } from "@fluid-experimental/shared-tree";
+import { useCallback } from "react";
+
+// Register the experimental `SharedTree` DDS
+DynamicObjectRegistry.registerObjectClass(SharedTree, "SharedTree");
+
+// Custom useSharedTree hook
+export const useSharedTree = (uniqueKey) => {
+    const onFirstInitialize = useCallback((dds) => {
+        // Set initial values for the newly created SharedTree dds here
+    }. []);
+    const { dds: sharedTree } = useDynamicDDS(uniqueKey, SharedTree, onFirstInitialize);
+    return {
+        sharedTree,
+    };
+}
+```
+
+## Code samples
+
+| Sample name       | Description                                                             | Javascript                                            |
+| ----------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
+| Live Share React  | Simple example with each of our custom Live Share React hooks.          | [View](../../samples/javascript/04.live-share-react)  |
+
+## React version compatibility
+
+This package is compatible with React versions `^16.8.0` and greater, including React v18. In order to ensure compatibility with different versions React, this project does not currently use React Suspense for data fetching on load. We are closely monitoring React guidelines and may post updates as this evolves further. If you have feedback or thoughts on this topic, join the [discussion](https://github.com/microsoft/live-share-sdk/discussions/442).
+
+## Package Compatibility
+
+The Live Share SDK contains dependencies for [@microsoft/teams-js](https://www.npmjs.com/package/@microsoft/teams-js) and [fluid-framework](https://www.npmjs.com/package/fluid-framework) packages among others. Both of these packages are sensitive to the package version your app any libraries use. You will likely run into issues if the package version your app uses doesn't match the version other libraries you depend on use.
+
+**It is critical that your app use the package dependencies listed in the table below.** Lookup the version of the `@microsoft/live-share` you're using and set any other dependencies in your package.json file to match:
+
+| @microsoft/live-share | @microsoft/teams-js  | fluid-framework | @microsoft/live-share-\*   | @fluidframework/azure-client | @microsoft/TeamsFx              | @microsoft/TeamsFx-react        |
+| --------------------- | -------------------- | --------------- | -------------------------- | ---------------------------- | ------------------------------- | ------------------------------- |
+| 1.0.0-preview.5       | ^2.5.0               | ~1.2.3          | 1.0.0-preview.5 (optional) | ~1.0.2 (optional)            | ^2.5.0 (optional)               | ^2.5.0 (optional)               |
+| 1.0.0-preview.3       | 2.0.0-experimental.1 | ~1.2.3          | 1.0.0-preview.3 (optional) | ~1.0.2 (optional)            | 2.0.0-experimental.0 (optional) | 2.0.0-experimental.0 (optional) |
+| ~0.5.1                | 2.0.0-experimental.1 | ~1.2.3          | ~0.5.1 (optional)          | ~1.0.2 (optional)            | 2.0.0-experimental.0 (optional) | 2.0.0-experimental.0 (optional) |
+| ~0.3.1                | 2.0.0-experimental.0 | ~0.59.0         | ~0.3.1 (optional)          | ~0.59.0 (optional)           | 2.0.0-experimental.0 (optional) | 2.0.0-experimental.0 (optional) |
+
+## Contributing
+
+There are several ways you can [contribute](../../CONTRIBUTING.md) to this project:
+
+- [Submit bugs](https://github.com/microsoft/live-share-sdk/issues) and help us verify fixes as they are checked in.
+- Review the source code changes.
+- Engage with other Live Share developers on [StackOverflow](https://stackoverflow.com/questions/tagged/live-share).
+- [Contribute bug fixes](../../CONTRIBUTING.md).
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact opencode@microsoft.com with any additional questions or comments.
+
+## Reporting Security Issues
+
+Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the [MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/default).
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Licensed under a special [Microsoft](../../LICENSE) License.

package/bin/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./providers";
+export * from "./shared-hooks";
+export * from "./live-hooks";
+export * from "./types";
+export * from "./providers";
+export * from "./interfaces";
+//# sourceMappingURL=index.d.ts.map

package/bin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/bin/index.js

@@ -0,0 +1,7 @@
+export * from "./providers";
+export * from "./shared-hooks";
+export * from "./live-hooks";
+export * from "./types";
+export * from "./providers";
+export * from "./interfaces";
+//# sourceMappingURL=index.js.map

package/bin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}