feat(client): encapsulated support for Presence (#25790)

Expose getPresenceFromDataStoreContext API to allow
Presence use in the encapsulated API model.

In this minimal implementation, Presence can be
injected on demand, but all injection requests
are expected to be from the same module.

Future changes:
- Add loader era initialization - new API
- Expand compat boundaries and checks where it is
possible that runtime package might be mismatched.

Add example use to @fluid-example/app-integration-external-views that
shows cursors.


[AB#51457](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/51457)

Author: jason-ha

examples/.eslintrc.data.cjs

@@ -8,8 +8,8 @@
 
 const importInternalModulesAllowed = [
 	// Allow import of Fluid Framework external API exports.
-	"@fluidframework/*/{beta,alpha,legacy}",
-	"fluid-framework/{beta,alpha,legacy}",
+	"@fluidframework/*/{beta,alpha,legacy,legacy/alpha}",
+	"fluid-framework/{beta,alpha,legacy,legacy/alpha}",
 
 	// Experimental package APIs and exports are unknown, so allow any imports from them.
 	"@fluid-experimental/**",

examples/view-integration/external-views/package.json

@@ -52,6 +52,7 @@
 		"@fluidframework/datastore-definitions": "workspace:~",
 		"@fluidframework/local-driver": "workspace:~",
 		"@fluidframework/map": "workspace:~",
+		"@fluidframework/presence": "workspace:~",
 		"@fluidframework/runtime-definitions": "workspace:~",
 		"@fluidframework/runtime-utils": "workspace:~",
 		"@fluidframework/server-local-server": "^7.0.0",
@@ -83,6 +84,7 @@
 		"process": "^0.11.10",
 		"puppeteer": "^23.6.0",
 		"rimraf": "^4.4.0",
+		"tinylicious": "^7.0.0",
 		"ts-jest": "^29.1.1",
 		"ts-loader": "^9.5.1",
 		"typescript": "~5.4.5",

examples/view-integration/external-views/src/app.ts

@@ -21,7 +21,8 @@ import { createElement } from "react";
 // eslint-disable-next-line import/no-internal-modules
 import { createRoot } from "react-dom/client";
 
-import { DiceRollerContainerRuntimeFactory, type IDiceRoller } from "./container/index.js";
+import { DiceRollerContainerRuntimeFactory, type EntryPoint } from "./container/index.js";
+import { renderCursorPresence } from "./cursor.js";
 import { DiceRollerView } from "./view.js";
 
 const service = getSpecifiedServiceFromWebpack();
@@ -76,13 +77,16 @@ if (location.hash.length === 0) {
 	});
 }
 
-const diceRoller = (await container.getEntryPoint()) as IDiceRoller;
+const { diceRoller, presence } = (await container.getEntryPoint()) as EntryPoint;
 
 // Render view
 const appDiv = document.getElementById("app") as HTMLDivElement;
 const appRoot = createRoot(appDiv);
 appRoot.render(createElement(DiceRollerView, { diceRoller }));
 
+const cursorContentDiv = document.getElementById("cursor-position") as HTMLDivElement;
+renderCursorPresence(presence, cursorContentDiv);
+
 // Update url and tab title
 location.hash = id;
 document.title = id;

examples/view-integration/external-views/src/container/diceRoller/diceRoller.ts

@@ -12,13 +12,14 @@ import type {
 	IFluidDataStoreRuntime,
 } from "@fluidframework/datastore-definitions/legacy";
 import { MapFactory, type ISharedMap, type IValueChanged } from "@fluidframework/map/legacy";
+import { getPresenceFromDataStoreContext } from "@fluidframework/presence/legacy/alpha";
 import type {
 	IFluidDataStoreChannel,
 	IFluidDataStoreContext,
 	IFluidDataStoreFactory,
 } from "@fluidframework/runtime-definitions/legacy";
 
-import type { IDiceRoller, IDiceRollerEvents } from "./interface.js";
+import type { EntryPoint, IDiceRoller, IDiceRollerEvents } from "./interface.js";
 
 // This key is where we store the value in the ISharedMap.
 const diceValueKey = "dice-value";
@@ -71,9 +72,14 @@ export class DiceRollerFactory implements IFluidDataStoreFactory {
 		context: IFluidDataStoreContext,
 		existing: boolean,
 	): Promise<IFluidDataStoreChannel> {
-		const provideEntryPoint = async (entryPointRuntime: IFluidDataStoreRuntime) => {
+		const provideEntryPoint = async (
+			entryPointRuntime: IFluidDataStoreRuntime,
+		): Promise<EntryPoint> => {
 			const map = (await entryPointRuntime.getChannel(mapId)) as ISharedMap;
-			return new DiceRoller(map);
+			return {
+				diceRoller: new DiceRoller(map),
+				presence: getPresenceFromDataStoreContext(context),
+			};
 		};
 
 		const runtime: FluidDataStoreRuntime = new FluidDataStoreRuntime(

examples/view-integration/external-views/src/container/diceRoller/index.ts

@@ -4,7 +4,8 @@
  */
 
 export { DiceRollerFactory } from "./diceRoller.js";
-export {
+export type {
+	EntryPoint,
 	IDiceRoller,
 	IDiceRollerEvents,
 } from "./interface.js";

examples/view-integration/external-views/src/container/diceRoller/interface.ts

@@ -4,6 +4,7 @@
  */
 
 import type { IEvent, IEventProvider } from "@fluidframework/core-interfaces";
+import type { Presence } from "@fluidframework/presence/beta";
 
 /**
  * IDiceRollerEvents describes the events for an IDiceRoller.
@@ -31,3 +32,11 @@ export interface IDiceRoller {
 	 */
 	roll: () => void;
 }
+
+/**
+ * The entry point interface for the Dice Roller container.
+ */
+export interface EntryPoint {
+	readonly diceRoller: IDiceRoller;
+	readonly presence: Presence;
+}

examples/view-integration/external-views/src/container/index.ts

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-export {
+export type {
+	EntryPoint,
 	IDiceRoller,
 	IDiceRollerEvents,
 } from "./diceRoller/index.js";

examples/view-integration/external-views/src/cursor.ts

@@ -0,0 +1,54 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { Presence, StatesWorkspaceSchema } from "@fluidframework/presence/beta";
+import { StateFactory } from "@fluidframework/presence/beta";
+
+const schema = {
+	cursor: StateFactory.latest({
+		local: { x: 0, y: 0 },
+	}),
+} as const satisfies StatesWorkspaceSchema;
+
+export function renderCursorPresence(presence: Presence, div: HTMLDivElement) {
+	const cursorStates = presence.states.getWorkspace("name:app-cursor", schema).states.cursor;
+
+	const onRemotePositionChanged = () => {
+		div.innerHTML = "";
+
+		const rect = div.getBoundingClientRect();
+		for (const data of cursorStates.getRemotes()) {
+			if (data.attendee.getConnectionStatus() === "Connected") {
+				const posDiv = document.createElement("div");
+				posDiv.textContent = `/${data.attendee.attendeeId}`;
+				posDiv.style.position = "absolute";
+				// Make sure the cursor positions do not block interaction with the app
+				posDiv.style.pointerEvents = "none";
+				// X is center based for approximate alignment with other clients
+				posDiv.style.left = `${data.value.x + rect.width / 2}px`;
+				posDiv.style.top = `${data.value.y - 16}px`;
+				posDiv.style.fontWeight = "bold";
+				div.appendChild(posDiv);
+			}
+		}
+	};
+
+	onRemotePositionChanged();
+	cursorStates.events.on("remoteUpdated", onRemotePositionChanged);
+	// When an attendee disconnects, also update the cursor positions.
+	presence.attendees.events.on("attendeeDisconnected", onRemotePositionChanged);
+	presence.attendees.events.on("attendeeConnected", onRemotePositionChanged);
+
+	// Listen to the local mousemove event and update the local position in the cursor state.
+	window.addEventListener("mousemove", (e) => {
+		// Alert all connected clients that there has been a change to this client's mouse position
+		const rect = div.getBoundingClientRect();
+		cursorStates.local = {
+			// base X on center of div for approximate alignment with other clients
+			x: e.clientX - rect.left - rect.width / 2,
+			y: e.clientY,
+		};
+	});
+}

examples/view-integration/external-views/src/index.html

@@ -10,5 +10,6 @@
 	</head>
 	<body style="margin: 0; height: 100%">
 		<div id="app" style="min-height: 100%"></div>
+		<div id="cursor-position"></div>
 	</body>
 </html>

examples/view-integration/external-views/tests/app.ts

@@ -28,6 +28,7 @@ import { v4 as uuid } from "uuid";
 
 import {
 	DiceRollerContainerRuntimeFactory,
+	type EntryPoint,
 	type IDiceRoller,
 } from "../src/container/index.js";
 import { DiceRollerView } from "../src/view.js";
@@ -75,7 +76,7 @@ async function createContainerAndRenderInElement(element: HTMLDivElement): Promi
 		});
 	}
 
-	const diceRoller = (await container.getEntryPoint()) as IDiceRoller;
+	const { diceRoller } = (await container.getEntryPoint()) as EntryPoint;
 	const render = (diceRoller: IDiceRoller) => {
 		const appRoot = createRoot(element);
 		appRoot.render(createElement(DiceRollerView, { diceRoller }));