@fluidframework/react 0.41.4 → 2.62.0

package/src/reactSharedTreeView.tsx

@@ -0,0 +1,327 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	PureDataObjectFactory,
+	TreeDataObject,
+	createDataObjectKind,
+} from "@fluidframework/aqueduct/internal";
+import type { IFluidLoadable } from "@fluidframework/core-interfaces";
+import type { IFluidDataStoreFactory } from "@fluidframework/runtime-definitions/internal";
+import type { SharedObjectKind } from "@fluidframework/shared-object-base";
+import type {
+	SchemaCompatibilityStatus,
+	TreeViewConfiguration,
+	TreeFieldFromImplicitField,
+	TreeView,
+	ImplicitFieldSchema,
+	InsertableTreeFieldFromImplicitField,
+} from "@fluidframework/tree";
+import { configuredSharedTree, FormatValidatorBasic } from "@fluidframework/tree/internal";
+import * as React from "react";
+
+import { toPropTreeNode, type PropTreeValue } from "./propNode.js";
+
+/**
+ * Opt into extra validation to detect encoding bugs and data corruption.
+ * As long as this is an experimental package, opting into extra validation (at a small perf and bundle size cost) seems reasonable.
+ */
+const SharedTree = configuredSharedTree({
+	jsonValidator: FormatValidatorBasic,
+});
+
+/**
+ * Defines a DataObject for a {@link @fluidframework/tree#SharedTree} with a built in {@link @fluidframework/tree#TreeViewConfiguration}.
+ * @param treeConfiguration - See {@link IReactTreeDataObject.config}.
+ * @param createInitialTree - Function which populates the tree with initial data on document create.
+ * @returns A {@link @fluidframework/fluid-static#DataObjectClass} to allow easy use of a SharedTree in a ContainerSchema.
+ * @alpha
+ */
+export function treeDataObject<TSchema extends ImplicitFieldSchema>(
+	treeConfiguration: TreeViewConfiguration<TSchema>,
+	createInitialTree: () => InsertableTreeFieldFromImplicitField<TSchema>,
+): SharedObjectKind<IReactTreeDataObject<TSchema> & IFluidLoadable> {
+	return treeDataObjectInternal(treeConfiguration, createInitialTree);
+}
+
+/**
+ * Defines a DataObject for a {@link @fluidframework/tree#SharedTree} with a built in {@link @fluidframework/tree#TreeViewConfiguration}.
+ * @param treeConfiguration - See {@link IReactTreeDataObject.config}.
+ * @param createInitialTree - Function which populates the tree with initial data on document create.
+ * @returns A {@link @fluidframework/fluid-static#DataObjectClass} to allow easy use of a SharedTree in a ContainerSchema.
+ * @internal
+ */
+export function treeDataObjectInternal<TSchema extends ImplicitFieldSchema>(
+	treeConfiguration: TreeViewConfiguration<TSchema>,
+	createInitialTree: () => InsertableTreeFieldFromImplicitField<TSchema>,
+): SharedObjectKind<IReactTreeDataObject<TSchema> & IFluidLoadable & TreeDataObject> & {
+	readonly factory: IFluidDataStoreFactory;
+} {
+	class SchemaAwareTreeDataObject extends ReactTreeDataObject<TSchema> {
+		public override readonly config = treeConfiguration;
+
+		public static readonly factory = new PureDataObjectFactory<ReactTreeDataObject<TSchema>>(
+			`TreeDataObject`,
+			SchemaAwareTreeDataObject,
+			[SharedTree.getFactory()],
+			{},
+		);
+
+		#treeView: TreeView<TSchema> | undefined;
+
+		/**
+		 * The schema-aware view of the tree.
+		 */
+		public get treeView(): TreeView<TSchema> {
+			if (this.#treeView === undefined) {
+				throw new Error("treeView has not been initialized.");
+			}
+			return this.#treeView;
+		}
+
+		/**
+		 * Converts the underlying ITree into a typed TreeView using the provided schema configuration.
+		 *
+		 * @param tree - The ITree instance to view.
+		 * @returns A typed TreeView using the TodoList schema.
+		 */
+		private initializeView(): void {
+			this.#treeView = this.tree.viewWith(this.config);
+		}
+
+		protected override async initializingFirstTime(): Promise<void> {
+			this.initializeView();
+			this.treeView.initialize(createInitialTree());
+		}
+
+		protected override async initializingFromExisting(): Promise<void> {
+			this.initializeView();
+		}
+	}
+	return createDataObjectKind(SchemaAwareTreeDataObject);
+}
+
+/**
+ * A schema-aware tree-backed DataObject, extended with a React Component to view the tree.
+ * @remarks Allows for the Tree's schema to be baked into the container schema.
+ * @sealed @alpha
+ */
+export interface IReactTreeDataObject<TSchema extends ImplicitFieldSchema> {
+	/**
+	 * The configuration used to initialize new documents, as well as to interpret (schematize) existing ones.
+	 *
+	 * @remarks
+	 * The fact that a single view schema is provided here (on the data object) makes it impossible to try and apply multiple different schema.
+	 * Since the view schema currently does not provide any adapters for handling differences between view and stored schema,
+	 * it's also impossible for this single view schema to handle multiple different stored schema.
+	 * Therefore, with this current API, two different applications (or different versions of the same application)
+	 * with differing stored schema requirements (as implied by their view schema) can not collaborate on the same tree.
+	 * The only schema evolution that's currently possible is upgrading the schema to one that supports a superset of what the old schema allowed,
+	 * and collaborating between clients which have view schema that exactly correspond to that stored schema.
+	 * Future work on tree as well as these utilities should address this limitation.
+	 */
+	readonly config: TreeViewConfiguration<TSchema>;
+
+	/**
+	 * The schema-aware view of the tree.
+	 */
+	readonly treeView: TreeView<TSchema>;
+
+	/**
+	 * React component which handles schematizing trees.
+	 * This includes displaying errors when the document can not be viewed using the view schema.
+	 *
+	 * @privateRemarks
+	 * This is exposed as a member rather than a free function since type inference for the schema doesn't work when used as a free function,
+	 * and thus making it a member avoids the user of this from having to explicitly provide the type parameter.
+	 * This is an arrow function not a method so it gets the correct this when not called as a member.
+	 */
+	readonly TreeViewComponent: (props: TreeViewProps<TSchema>) => React.JSX.Element;
+}
+
+/**
+ * React props for viewing a tree.
+ * @input @alpha
+ */
+export interface TreeViewProps<TSchema extends ImplicitFieldSchema> {
+	/**
+	 * Component to display the tree content.
+	 */
+	readonly viewComponent: React.FC<{
+		root: PropTreeValue<TreeFieldFromImplicitField<TSchema>>;
+	}>;
+
+	/**
+	 * Component to display instead of the {@link TreeViewProps.viewComponent}
+	 * when tree content is not compatible with the {@link @fluidframework/tree#TreeViewConfiguration}.
+	 *
+	 * @defaultValue Component which describes the situation (in English) and allows the user to upgrade the schema to match the {@link @fluidframework/tree#TreeViewConfiguration} if possible.
+	 */
+	readonly errorComponent?: React.FC<SchemaIncompatibleProps>;
+
+	// TODO: Once its possible to query the status of individual schema upgrades, provide more options here for handling such cases.
+}
+
+/**
+ * Generic DataObject for shared trees.
+ * @internal
+ */
+export abstract class ReactTreeDataObject<
+		TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
+	>
+	extends TreeDataObject
+	implements IReactTreeDataObject<TSchema>
+{
+	public abstract readonly config: TreeViewConfiguration<TSchema>;
+
+	#treeView: TreeView<TSchema> | undefined;
+
+	/**
+	 * The schema-aware view of the tree.
+	 */
+	public get treeView(): TreeView<TSchema> {
+		if (this.#treeView === undefined) {
+			throw new Error("treeView has not been initialized.");
+		}
+		return this.#treeView;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/explicit-function-return-type
+	public readonly TreeViewComponent = ({
+		viewComponent,
+		errorComponent,
+	}: TreeViewProps<TSchema>) =>
+		TreeViewComponent<TSchema>({
+			tree: this,
+			viewComponent,
+			errorComponent,
+		});
+}
+
+function useViewCompatibility<TSchema extends ImplicitFieldSchema>(
+	view: TreeView<TSchema>,
+): SchemaCompatibilityStatus {
+	const [compatibility, setCompatibility] = React.useState<SchemaCompatibilityStatus>(
+		view.compatibility,
+	);
+
+	React.useEffect(() => {
+		const updateCompatibility = (): void => {
+			setCompatibility(view.compatibility);
+		};
+
+		updateCompatibility();
+		return view.events.on("schemaChanged", updateCompatibility);
+	}, [view]);
+
+	return compatibility;
+}
+
+function useViewRoot<TSchema extends ImplicitFieldSchema>(
+	view: TreeView<TSchema>,
+): TreeFieldFromImplicitField<TSchema> | undefined {
+	const [root, setRoot] = React.useState<TreeFieldFromImplicitField<TSchema> | undefined>(
+		undefined,
+	);
+
+	React.useEffect(() => {
+		const updateRoot = (): void => {
+			if (view.compatibility.canView) {
+				setRoot(view.root);
+			} else {
+				setRoot(undefined);
+			}
+		};
+
+		updateRoot();
+		return view.events.on("rootChanged", updateRoot);
+	}, [view]);
+
+	return root;
+}
+
+/**
+ * React component which handles schematizing trees.
+ * This includes displaying errors when the document can not be schematized.
+ * @alpha
+ */
+export function TreeViewComponent<TSchema extends ImplicitFieldSchema>({
+	tree,
+	viewComponent: ViewComponent,
+	errorComponent,
+}: TreeViewProps<TSchema> & {
+	tree: Pick<IReactTreeDataObject<TSchema>, "treeView">;
+}): React.JSX.Element {
+	const view = tree.treeView;
+
+	const compatibility = useViewCompatibility(view);
+	const root = useViewRoot(view);
+	const upgradeSchema = React.useCallback((): void => view.upgradeSchema(), [view]);
+
+	// Note: this policy is on the stricter side and ensures that clients will only be able to submit edits when their view schema
+	// supports exactly the same documents as the stored schema.
+	// A realistic production application using this strategy would need to take steps to attempt to open the document using
+	// several different view schemas in order to ensure that their users don't temporarily lose access to documents while
+	// code rollout is in progress.
+	// Alternative policies can be implemented, see "Schema Evolvability" in SharedTree's README for more information.
+	if (!compatibility.isEquivalent) {
+		const Error = errorComponent ?? TreeErrorComponent;
+		return <Error compatibility={compatibility} upgradeSchema={upgradeSchema} />;
+	}
+
+	if (root === undefined) {
+		return <div>View not set</div>;
+	}
+
+	return <ViewComponent root={toPropTreeNode(root)} />;
+}
+
+/**
+ * React Props for displaying when the opened document is incompatible with the required view schema.
+ * @alpha
+ */
+export interface SchemaIncompatibleProps {
+	/**
+	 * Information about the view schema's compatibility with the stored schema.
+	 */
+	readonly compatibility: SchemaCompatibilityStatus;
+	/**
+	 * Callback to request that the stored schema in the document be upgraded.
+	 */
+	readonly upgradeSchema: () => void;
+}
+
+/**
+ * React component which displays schema errors and allows upgrading schema when possible.
+ */
+function TreeErrorComponent({
+	compatibility,
+	upgradeSchema,
+}: {
+	compatibility: SchemaCompatibilityStatus;
+	upgradeSchema: () => void;
+}): React.JSX.Element {
+	// eslint-disable-next-line unicorn/prefer-ternary
+	if (compatibility.canUpgrade) {
+		return (
+			<div>
+				<div>
+					Document is incompatible with current version of the application, but the document
+					format can be updated. This may prevent other versions of the application from
+					opening this document.
+				</div>
+				<button onClick={upgradeSchema}>Upgrade</button>;
+			</div>
+		);
+	} else {
+		return (
+			<div>
+				Document is incompatible with current version of the application, and the document
+				format cannot be updated. The document is likely from a newer or otherwise incompatible
+				version of the application, or a different application.
+			</div>
+		);
+	}
+}

package/src/simpleIdentifier.ts

@@ -0,0 +1,31 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+let counter = 0;
+
+const idMap = new WeakMap<object, number>();
+
+/**
+ * Associates a unique number with an object.
+ * @remarks
+ * The ID number is tied to the object identity, not the object's contents; modifying the object will not cause it to get a different ID.
+ *
+ * This can be handy for generating {@link https://react.dev/learn/rendering-lists#where-to-get-your-key | keys for React lists} from TreeNodes.
+ *
+ * Most cases which could use this function should just use the objects themselves instead of getting IDs from them, since the objects will have the same equality as the IDs.
+ * For example, if storing data associated with the objects in a map, using the object as the key is more efficient than getting an ID from it and using that.
+ * This functions exists to deal with the edge case where you would like to use object identity, but you can't.
+ * React keys are an examples of such a case, since React does not allow objects as keys.
+ * @alpha
+ */
+export function objectIdNumber(object: object): number {
+	const id = idMap.get(object);
+	if (id !== undefined) {
+		return id;
+	}
+	counter++;
+	idMap.set(object, counter);
+	return counter;
+}