@fluidframework/react 0.41.4 → 2.63.0-358419

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Utilities for using SharedTree with React.
+ * @packageDocumentation
+ */
+export type { IReactTreeDataObject, TreeViewProps, SchemaIncompatibleProps, } from "./reactSharedTreeView.js";
+export { treeDataObject, treeDataObjectInternal, TreeViewComponent, } from "./reactSharedTreeView.js";
+export type { ObservationOptions } from "./useObservation.js";
+export type { NodeRecord, PropTreeNode, PropTreeNodeRecord, PropTreeValue, UnwrapPropTreeNode, UnwrapPropTreeNodeRecord, WrapPropTreeNodeRecord, WrapNodes, IsMappableObjectType, } from "./propNode.js";
+export { toPropTreeNode, toPropTreeRecord, unwrapPropTreeNode, unwrapPropTreeRecord, } from "./propNode.js";
+export { useTree, usePropTreeNode, usePropTreeRecord, useTreeObservations, withTreeObservations, withMemoizedTreeObservations, } from "./useTree.js";
+export { objectIdNumber } from "./simpleIdentifier.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AAEH,YAAY,EACX,oBAAoB,EACpB,aAAa,EACb,uBAAuB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,iBAAiB,GACjB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,YAAY,EACX,UAAU,EACV,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,SAAS,EACT,oBAAoB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,OAAO,EACP,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/lib/index.js

@@ -2,11 +2,8 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export * from "./reactView";
-export * from "./useStateFluid";
-export * from "./useReducerFluid";
-export * from "./createContextFluid";
-export * from "./interface";
-export * from "./syncedDataObject";
-export * from "./syncedObjects";
+export { treeDataObject, treeDataObjectInternal, TreeViewComponent, } from "./reactSharedTreeView.js";
+export { toPropTreeNode, toPropTreeRecord, unwrapPropTreeNode, unwrapPropTreeRecord, } from "./propNode.js";
+export { useTree, usePropTreeNode, usePropTreeRecord, useTreeObservations, withTreeObservations, withMemoizedTreeObservations, } from "./useTree.js";
+export { objectIdNumber } from "./simpleIdentifier.js";
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport * from \"./reactView\";\nexport * from \"./useStateFluid\";\nexport * from \"./useReducerFluid\";\nexport * from \"./createContextFluid\";\nexport * from \"./interface\";\nexport * from \"./syncedDataObject\";\nexport * from \"./syncedObjects\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,iBAAiB,GACjB,MAAM,0BAA0B,CAAC;AAalC,OAAO,EACN,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,OAAO,EACP,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Utilities for using SharedTree with React.\n * @packageDocumentation\n */\n\nexport type {\n\tIReactTreeDataObject,\n\tTreeViewProps,\n\tSchemaIncompatibleProps,\n} from \"./reactSharedTreeView.js\";\nexport {\n\ttreeDataObject,\n\ttreeDataObjectInternal,\n\tTreeViewComponent,\n} from \"./reactSharedTreeView.js\";\nexport type { ObservationOptions } from \"./useObservation.js\";\nexport type {\n\tNodeRecord,\n\tPropTreeNode,\n\tPropTreeNodeRecord,\n\tPropTreeValue,\n\tUnwrapPropTreeNode,\n\tUnwrapPropTreeNodeRecord,\n\tWrapPropTreeNodeRecord,\n\tWrapNodes,\n\tIsMappableObjectType,\n} from \"./propNode.js\";\nexport {\n\ttoPropTreeNode,\n\ttoPropTreeRecord,\n\tunwrapPropTreeNode,\n\tunwrapPropTreeRecord,\n} from \"./propNode.js\";\nexport {\n\tuseTree,\n\tusePropTreeNode,\n\tusePropTreeRecord,\n\tuseTreeObservations,\n\twithTreeObservations,\n\twithMemoizedTreeObservations,\n} from \"./useTree.js\";\nexport { objectIdNumber } from \"./simpleIdentifier.js\";\n"]}

package/lib/package.json

@@ -0,0 +1,4 @@
+{
+	"type": "module",
+	"sideEffects": false
+}

package/lib/propNode.d.ts

@@ -0,0 +1,114 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { ErasedType } from "@fluidframework/core-interfaces";
+import type { TreeNode, TreeLeafValue } from "@fluidframework/tree";
+/**
+ * A type erased TreeNode for use in react props.
+ * @remarks
+ * Read content from the node using {@link usePropTreeNode} or {@link usePropTreeRecord}.
+ *
+ * In events where tracking dependencies is not required, the node can be unwrapped using {@link unwrapPropTreeNode}.
+ *
+ * To convert a TreeNode to this type use {@link toPropTreeNode} or {@link toPropTreeRecord}.
+ * @alpha
+ */
+export interface PropTreeNode<T extends TreeNode> extends ErasedType<[T, "PropTreeNode"]> {
+}
+/**
+ * Type TreeNodes in T as {@link PropTreeNode}s.
+ * @remarks
+ * This only handles a few cases (TreeNode, structurally typed objects fields and arrays) and leaves other types as is.
+ * Users which provide other types (e.g. maps) which contain TreeNodes will need to handle wrapping those themselves if the wrapping is desired.
+ *
+ * Users of this should not rely on a given use of TreeNode not being wrapped:
+ * future changes to this API may add more cases which are wrapped, and this will be considered a non-breaking change.
+ * @privateRemarks
+ * Covering all cases is impossible, and trying to cover more with recursive mapped types can break some of the types by losing methods, private members, etc.
+ * To mitigate this IsMappableObjectType is used for objects, and only mappable types, where the mapping actually impacted the type are modified.
+ *
+ * This is intended to cover the common cases, and users can handle other cases manually.
+ * See the tests for this for more details.
+ * @alpha
+ */
+export type WrapNodes<T> = T extends TreeNode ? PropTreeNode<T> : T extends readonly (infer U)[] ? readonly WrapNodes<U>[] : T extends infer U ? IsMappableObjectType<U, {
+    [P in keyof U]: WrapNodes<U[P]>;
+} extends U ? U : {
+    [P in keyof U]: WrapNodes<U[P]>;
+}, T> : T;
+/**
+ * Detect if a type is a simple structural object.
+ * @remarks
+ * This returns the true case if the type is entirely defined by its set of public properties.
+ * More concretely, this indicates if creating a mapped type based on `T`
+ * will be lossy due to details mapped types cannot access.
+ *
+ * This is shallow, and distributes over unions.
+ *
+ * This also returns the true case for primitive types since mapping over them leaves them unchanged if doing so in a generic context:
+ * Mapping over a primitive does not leave them unchanged if done directly (not to a generic type parameter), but this can not detect that behavior.
+ * This is fine as the use for this is to detect when making a mapped type from a generic type parameter would be lossy.
+ * @system @alpha
+ */
+export type IsMappableObjectType<T, True = true, False = false, Mapped = {
+    [P in keyof T]: T[P];
+}> = [Mapped] extends [T] ? ([T] extends [Mapped] ? True : False) : False;
+/**
+ * Casts a node from a {@link PropTreeNode} back to a TreeNode.
+ * @remarks
+ * This should only be done in scenarios where tracking observations is not required (such as event handlers),
+ * or when taking care to handle invalidation manually.
+ * @alpha
+ */
+export declare function unwrapPropTreeNode<T extends TreeNode | TreeLeafValue>(propNode: PropTreeValue<T> | T): T;
+/**
+ * {@link unwrapPropTreeNode} but for a {@link PropTreeNodeRecord}.
+ * @alpha
+ */
+export declare function unwrapPropTreeRecord<T extends PropTreeNodeRecord>(props: T): UnwrapPropTreeNodeRecord<T>;
+/**
+ * {@inheritdoc unwrapPropTreeNode}
+ * @alpha
+ */
+export type UnwrapPropTreeNode<T extends TreeLeafValue | PropTreeNode<TreeNode> | undefined> = T extends PropTreeNode<infer Node> ? Node : T;
+/**
+ * Record that can contain TreeNodes.
+ * @alpha
+ */
+export type NodeRecord = Record<string, TreeNode | TreeLeafValue>;
+/**
+ * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.
+ * @alpha
+ */
+export type WrapPropTreeNodeRecord<T extends NodeRecord> = {
+    readonly [P in keyof T]: PropTreeValue<T[P]>;
+};
+/**
+ * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.
+ * @alpha
+ */
+export type UnwrapPropTreeNodeRecord<T extends PropTreeNodeRecord> = {
+    readonly [P in keyof T]: UnwrapPropTreeNode<T[P]>;
+};
+/**
+ * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.
+ * @alpha
+ */
+export type PropTreeNodeRecord = Record<string, TreeLeafValue | PropTreeNode<TreeNode> | undefined>;
+/**
+ * Type erase a `TreeNode` from a `TreeNode | TreeLeafValue` as a {@link PropTreeNode}.
+ * @alpha
+ */
+export type PropTreeValue<T extends TreeNode | TreeLeafValue | undefined> = T extends TreeNode ? PropTreeNode<T> : T;
+/**
+ * Type erase a TreeNode as a {@link PropTreeNode}.
+ * @alpha
+ */
+export declare function toPropTreeNode<T extends TreeNode | TreeLeafValue>(node: T): PropTreeValue<T>;
+/**
+ * Type erase a {@link NodeRecord} as a {@link PropTreeNodeRecord}.
+ * @alpha
+ */
+export declare function toPropTreeRecord<T extends NodeRecord>(node: T): WrapPropTreeNodeRecord<T>;
+//# sourceMappingURL=propNode.d.ts.map

package/lib/propNode.d.ts.map

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

package/lib/propNode.js

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Casts a node from a {@link PropTreeNode} back to a TreeNode.
+ * @remarks
+ * This should only be done in scenarios where tracking observations is not required (such as event handlers),
+ * or when taking care to handle invalidation manually.
+ * @alpha
+ */
+export function unwrapPropTreeNode(propNode) {
+    return propNode;
+}
+/**
+ * {@link unwrapPropTreeNode} but for a {@link PropTreeNodeRecord}.
+ * @alpha
+ */
+export function unwrapPropTreeRecord(props) {
+    return props;
+}
+/**
+ * Type erase a TreeNode as a {@link PropTreeNode}.
+ * @alpha
+ */
+export function toPropTreeNode(node) {
+    return node;
+}
+/**
+ * Type erase a {@link NodeRecord} as a {@link PropTreeNodeRecord}.
+ * @alpha
+ */
+export function toPropTreeRecord(node) {
+    return node;
+}
+//# sourceMappingURL=propNode.js.map

package/lib/propNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propNode.js","sourceRoot":"","sources":["../src/propNode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA6EH;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CACjC,QAA8B;IAE9B,OAAO,QAAa,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CACnC,KAAQ;IAER,OAAO,KAAoC,CAAC;AAC7C,CAAC;AAgDD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAqC,IAAO;IACzE,OAAO,IAAmC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAuB,IAAO;IAC7D,OAAO,IAA4C,CAAC;AACrD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ErasedType } from \"@fluidframework/core-interfaces\";\nimport type { TreeNode, TreeLeafValue } from \"@fluidframework/tree\";\n\n/**\n * A type erased TreeNode for use in react props.\n * @remarks\n * Read content from the node using {@link usePropTreeNode} or {@link usePropTreeRecord}.\n *\n * In events where tracking dependencies is not required, the node can be unwrapped using {@link unwrapPropTreeNode}.\n *\n * To convert a TreeNode to this type use {@link toPropTreeNode} or {@link toPropTreeRecord}.\n * @alpha\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-interface\nexport interface PropTreeNode<T extends TreeNode> extends ErasedType<[T, \"PropTreeNode\"]> {}\n\n/**\n * Type TreeNodes in T as {@link PropTreeNode}s.\n * @remarks\n * This only handles a few cases (TreeNode, structurally typed objects fields and arrays) and leaves other types as is.\n * Users which provide other types (e.g. maps) which contain TreeNodes will need to handle wrapping those themselves if the wrapping is desired.\n *\n * Users of this should not rely on a given use of TreeNode not being wrapped:\n * future changes to this API may add more cases which are wrapped, and this will be considered a non-breaking change.\n * @privateRemarks\n * Covering all cases is impossible, and trying to cover more with recursive mapped types can break some of the types by losing methods, private members, etc.\n * To mitigate this IsMappableObjectType is used for objects, and only mappable types, where the mapping actually impacted the type are modified.\n *\n * This is intended to cover the common cases, and users can handle other cases manually.\n * See the tests for this for more details.\n * @alpha\n */\nexport type WrapNodes<T> = T extends TreeNode\n\t? PropTreeNode<T>\n\t: T extends readonly (infer U)[]\n\t\t? readonly WrapNodes<U>[]\n\t\t: // `T extends (infer U)` distributes over unions, allowing WrapNodes<A|B> to be WrapNodes<A> | WrapNodes<B>.\n\t\t\tT extends infer U\n\t\t\t? IsMappableObjectType<\n\t\t\t\t\tU,\n\t\t\t\t\t{\n\t\t\t\t\t\t[P in keyof U]: WrapNodes<U[P]>;\n\t\t\t\t\t} extends U\n\t\t\t\t\t\t? // Returning U in this case (when assignable to the mapped type) avoids flatting named interfaces when they are unchanged.\n\t\t\t\t\t\t\tU\n\t\t\t\t\t\t: {\n\t\t\t\t\t\t\t\t[P in keyof U]: WrapNodes<U[P]>;\n\t\t\t\t\t\t\t},\n\t\t\t\t\tT\n\t\t\t\t>\n\t\t\t: T;\n\n/**\n * Detect if a type is a simple structural object.\n * @remarks\n * This returns the true case if the type is entirely defined by its set of public properties.\n * More concretely, this indicates if creating a mapped type based on `T`\n * will be lossy due to details mapped types cannot access.\n *\n * This is shallow, and distributes over unions.\n *\n * This also returns the true case for primitive types since mapping over them leaves them unchanged if doing so in a generic context:\n * Mapping over a primitive does not leave them unchanged if done directly (not to a generic type parameter), but this can not detect that behavior.\n * This is fine as the use for this is to detect when making a mapped type from a generic type parameter would be lossy.\n * @system @alpha\n */\nexport type IsMappableObjectType<\n\tT,\n\tTrue = true,\n\tFalse = false,\n\tMapped = {\n\t\t[P in keyof T]: T[P];\n\t},\n> = [Mapped] extends [T] ? ([T] extends [Mapped] ? True : False) : False;\n\n/**\n * Casts a node from a {@link PropTreeNode} back to a TreeNode.\n * @remarks\n * This should only be done in scenarios where tracking observations is not required (such as event handlers),\n * or when taking care to handle invalidation manually.\n * @alpha\n */\nexport function unwrapPropTreeNode<T extends TreeNode | TreeLeafValue>(\n\tpropNode: PropTreeValue<T> | T,\n): T {\n\treturn propNode as T;\n}\n\n/**\n * {@link unwrapPropTreeNode} but for a {@link PropTreeNodeRecord}.\n * @alpha\n */\nexport function unwrapPropTreeRecord<T extends PropTreeNodeRecord>(\n\tprops: T,\n): UnwrapPropTreeNodeRecord<T> {\n\treturn props as UnwrapPropTreeNodeRecord<T>;\n}\n\n/**\n * {@inheritdoc unwrapPropTreeNode}\n * @alpha\n */\nexport type UnwrapPropTreeNode<T extends TreeLeafValue | PropTreeNode<TreeNode> | undefined> =\n\tT extends PropTreeNode<infer Node> ? Node : T;\n\n/**\n * Record that can contain TreeNodes.\n * @alpha\n */\nexport type NodeRecord = Record<string, TreeNode | TreeLeafValue>;\n\n/**\n * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.\n * @alpha\n */\nexport type WrapPropTreeNodeRecord<T extends NodeRecord> = {\n\treadonly [P in keyof T]: PropTreeValue<T[P]>;\n};\n\n/**\n * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.\n * @alpha\n */\nexport type UnwrapPropTreeNodeRecord<T extends PropTreeNodeRecord> = {\n\treadonly [P in keyof T]: UnwrapPropTreeNode<T[P]>;\n};\n\n/**\n * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.\n * @alpha\n */\nexport type PropTreeNodeRecord = Record<\n\tstring,\n\tTreeLeafValue | PropTreeNode<TreeNode> | undefined\n>;\n\n/**\n * Type erase a `TreeNode` from a `TreeNode | TreeLeafValue` as a {@link PropTreeNode}.\n * @alpha\n */\nexport type PropTreeValue<T extends TreeNode | TreeLeafValue | undefined> = T extends TreeNode\n\t? PropTreeNode<T>\n\t: T;\n\n/**\n * Type erase a TreeNode as a {@link PropTreeNode}.\n * @alpha\n */\nexport function toPropTreeNode<T extends TreeNode | TreeLeafValue>(node: T): PropTreeValue<T> {\n\treturn node as unknown as PropTreeValue<T>;\n}\n\n/**\n * Type erase a {@link NodeRecord} as a {@link PropTreeNodeRecord}.\n * @alpha\n */\nexport function toPropTreeRecord<T extends NodeRecord>(node: T): WrapPropTreeNodeRecord<T> {\n\treturn node as unknown as WrapPropTreeNodeRecord<T>;\n}\n"]}

package/lib/public.d.ts

@@ -0,0 +1,15 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluid-tools/build-cli.
+ */
+
+/**
+ * Utilities for using SharedTree with React.
+ * @packageDocumentation
+ */export {}
+

package/lib/reactSharedTreeView.d.ts

@@ -0,0 +1,119 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { TreeDataObject } 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 * as React from "react";
+import { type PropTreeValue } from "./propNode.js";
+/**
+ * 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 declare function treeDataObject<TSchema extends ImplicitFieldSchema>(treeConfiguration: TreeViewConfiguration<TSchema>, createInitialTree: () => InsertableTreeFieldFromImplicitField<TSchema>): SharedObjectKind<IReactTreeDataObject<TSchema> & IFluidLoadable>;
+/**
+ * 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 declare function treeDataObjectInternal<TSchema extends ImplicitFieldSchema>(treeConfiguration: TreeViewConfiguration<TSchema>, createInitialTree: () => InsertableTreeFieldFromImplicitField<TSchema>): SharedObjectKind<IReactTreeDataObject<TSchema> & IFluidLoadable & TreeDataObject> & {
+    readonly factory: IFluidDataStoreFactory;
+};
+/**
+ * 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>;
+}
+/**
+ * Generic DataObject for shared trees.
+ * @internal
+ */
+export declare abstract class ReactTreeDataObject<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> extends TreeDataObject implements IReactTreeDataObject<TSchema> {
+    #private;
+    abstract readonly config: TreeViewConfiguration<TSchema>;
+    /**
+     * The schema-aware view of the tree.
+     */
+    get treeView(): TreeView<TSchema>;
+    readonly TreeViewComponent: ({ viewComponent, errorComponent, }: TreeViewProps<TSchema>) => React.JSX.Element;
+}
+/**
+ * React component which handles schematizing trees.
+ * This includes displaying errors when the document can not be schematized.
+ * @alpha
+ */
+export declare function TreeViewComponent<TSchema extends ImplicitFieldSchema>({ tree, viewComponent: ViewComponent, errorComponent, }: TreeViewProps<TSchema> & {
+    tree: Pick<IReactTreeDataObject<TSchema>, "treeView">;
+}): React.JSX.Element;
+/**
+ * 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;
+}
+//# sourceMappingURL=reactSharedTreeView.d.ts.map

package/lib/reactSharedTreeView.d.ts.map

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

package/lib/reactSharedTreeView.js

@@ -0,0 +1,176 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _ReactTreeDataObject_treeView;
+import { PureDataObjectFactory, TreeDataObject, createDataObjectKind, } from "@fluidframework/aqueduct/internal";
+import { configuredSharedTree, FormatValidatorBasic } from "@fluidframework/tree/internal";
+import * as React from "react";
+import { toPropTreeNode } 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(treeConfiguration, createInitialTree) {
+    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(treeConfiguration, createInitialTree) {
+    var _SchemaAwareTreeDataObject_treeView;
+    class SchemaAwareTreeDataObject extends ReactTreeDataObject {
+        constructor() {
+            super(...arguments);
+            this.config = treeConfiguration;
+            _SchemaAwareTreeDataObject_treeView.set(this, void 0);
+        }
+        /**
+         * The schema-aware view of the tree.
+         */
+        get treeView() {
+            if (__classPrivateFieldGet(this, _SchemaAwareTreeDataObject_treeView, "f") === undefined) {
+                throw new Error("treeView has not been initialized.");
+            }
+            return __classPrivateFieldGet(this, _SchemaAwareTreeDataObject_treeView, "f");
+        }
+        /**
+         * 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.
+         */
+        initializeView() {
+            __classPrivateFieldSet(this, _SchemaAwareTreeDataObject_treeView, this.tree.viewWith(this.config), "f");
+        }
+        async initializingFirstTime() {
+            this.initializeView();
+            this.treeView.initialize(createInitialTree());
+        }
+        async initializingFromExisting() {
+            this.initializeView();
+        }
+    }
+    _SchemaAwareTreeDataObject_treeView = new WeakMap();
+    SchemaAwareTreeDataObject.factory = new PureDataObjectFactory(`TreeDataObject`, SchemaAwareTreeDataObject, [SharedTree.getFactory()], {});
+    return createDataObjectKind(SchemaAwareTreeDataObject);
+}
+/**
+ * Generic DataObject for shared trees.
+ * @internal
+ */
+export class ReactTreeDataObject extends TreeDataObject {
+    constructor() {
+        super(...arguments);
+        _ReactTreeDataObject_treeView.set(this, void 0);
+        // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/explicit-function-return-type
+        this.TreeViewComponent = ({ viewComponent, errorComponent, }) => TreeViewComponent({
+            tree: this,
+            viewComponent,
+            errorComponent,
+        });
+    }
+    /**
+     * The schema-aware view of the tree.
+     */
+    get treeView() {
+        if (__classPrivateFieldGet(this, _ReactTreeDataObject_treeView, "f") === undefined) {
+            throw new Error("treeView has not been initialized.");
+        }
+        return __classPrivateFieldGet(this, _ReactTreeDataObject_treeView, "f");
+    }
+}
+_ReactTreeDataObject_treeView = new WeakMap();
+function useViewCompatibility(view) {
+    const [compatibility, setCompatibility] = React.useState(view.compatibility);
+    React.useEffect(() => {
+        const updateCompatibility = () => {
+            setCompatibility(view.compatibility);
+        };
+        updateCompatibility();
+        return view.events.on("schemaChanged", updateCompatibility);
+    }, [view]);
+    return compatibility;
+}
+function useViewRoot(view) {
+    const [root, setRoot] = React.useState(undefined);
+    React.useEffect(() => {
+        const updateRoot = () => {
+            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({ tree, viewComponent: ViewComponent, errorComponent, }) {
+    const view = tree.treeView;
+    const compatibility = useViewCompatibility(view);
+    const root = useViewRoot(view);
+    const upgradeSchema = React.useCallback(() => 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 React.createElement(Error, { compatibility: compatibility, upgradeSchema: upgradeSchema });
+    }
+    if (root === undefined) {
+        return React.createElement("div", null, "View not set");
+    }
+    return React.createElement(ViewComponent, { root: toPropTreeNode(root) });
+}
+/**
+ * React component which displays schema errors and allows upgrading schema when possible.
+ */
+function TreeErrorComponent({ compatibility, upgradeSchema, }) {
+    // eslint-disable-next-line unicorn/prefer-ternary
+    if (compatibility.canUpgrade) {
+        return (React.createElement("div", null,
+            React.createElement("div", null, "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."),
+            React.createElement("button", { onClick: upgradeSchema }, "Upgrade"),
+            ";"));
+    }
+    else {
+        return (React.createElement("div", null, "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."));
+    }
+}
+//# sourceMappingURL=reactSharedTreeView.js.map

package/lib/reactSharedTreeView.js.map

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

package/lib/simpleIdentifier.d.ts

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * 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 declare function objectIdNumber(object: object): number;
+//# sourceMappingURL=simpleIdentifier.d.ts.map

package/lib/simpleIdentifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simpleIdentifier.d.ts","sourceRoot":"","sources":["../src/simpleIdentifier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQrD"}

package/lib/simpleIdentifier.js

@@ -0,0 +1,29 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+let counter = 0;
+const idMap = new WeakMap();
+/**
+ * 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) {
+    const id = idMap.get(object);
+    if (id !== undefined) {
+        return id;
+    }
+    counter++;
+    idMap.set(object, counter);
+    return counter;
+}
+//# sourceMappingURL=simpleIdentifier.js.map