@fluidframework/tree 2.5.0 → 2.10.0-305357

package/src/simple-tree/api/index.ts

@@ -29,7 +29,16 @@ export {
 } from "./schemaCreationUtilities.js";
 export { treeNodeApi, type TreeNodeApi, tryGetSchema } from "./treeNodeApi.js";
 export { createFromInsertable, cursorFromInsertable, createFromCursor } from "./create.js";
-export type { SimpleTreeSchema } from "./simpleSchema.js";
+export type {
+	SimpleTreeSchema,
+	SimpleNodeSchema,
+	SimpleFieldSchema,
+	SimpleLeafNodeSchema,
+	SimpleMapNodeSchema,
+	SimpleArrayNodeSchema,
+	SimpleObjectNodeSchema,
+	SimpleNodeSchemaBase,
+} from "./simpleSchema.js";
 export {
 	type JsonSchemaId,
 	type JsonSchemaType,

package/src/simple-tree/api/simpleSchema.ts

@@ -5,11 +5,12 @@
 
 import type { ValueSchema } from "../../core/index.js";
 import type { NodeKind } from "../core/index.js";
-import type { FieldKind } from "../schemaTypes.js";
+import type { FieldKind, FieldSchemaMetadata } from "../schemaTypes.js";
 
 /**
  * Base interface for all {@link SimpleNodeSchema} implementations.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
@@ -24,6 +25,7 @@ export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
 /**
  * A {@link SimpleNodeSchema} for an object node.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
@@ -36,6 +38,7 @@ export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Ob
 /**
  * A {@link SimpleNodeSchema} for an array node.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleArrayNodeSchema extends SimpleNodeSchemaBase<NodeKind.Array> {
@@ -51,6 +54,7 @@ export interface SimpleArrayNodeSchema extends SimpleNodeSchemaBase<NodeKind.Arr
 /**
  * A {@link SimpleNodeSchema} for a map node.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleMapNodeSchema extends SimpleNodeSchemaBase<NodeKind.Map> {
@@ -66,6 +70,7 @@ export interface SimpleMapNodeSchema extends SimpleNodeSchemaBase<NodeKind.Map>
 /**
  * A {@link SimpleNodeSchema} for a leaf node.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBase<NodeKind.Leaf> {
@@ -81,6 +86,8 @@ export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBase<NodeKind.Leaf
  * @remarks This definition is incomplete, and references child types by identifiers.
  * To be useful, this generally needs to be used as a part of a complete {@link SimpleTreeSchema}, which
  * contains backing {@link SimpleTreeSchema.definitions} for each referenced identifier.
+ *
+ * @internal
  */
 export type SimpleNodeSchema =
 	| SimpleLeafNodeSchema
@@ -95,6 +102,7 @@ export type SimpleNodeSchema =
  * To be useful, this generally needs to be used as a part of a complete {@link SimpleTreeSchema}, which
  * contains backing {@link SimpleTreeSchema.definitions} for each referenced identifier.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleFieldSchema {
@@ -112,9 +120,9 @@ export interface SimpleFieldSchema {
 	readonly allowedTypes: ReadonlySet<string>;
 
 	/**
-	 * {@inheritDoc FieldSchemaMetadata.description}
+	 * {@inheritDoc FieldSchemaMetadata}
 	 */
-	readonly description?: string | undefined;
+	readonly metadata?: FieldSchemaMetadata | undefined;
 }
 
 /**
@@ -123,6 +131,7 @@ export interface SimpleFieldSchema {
  * @remarks Contains the complete set of schema {@link SimpleTreeSchema.definitions} required to resolve references,
  * which are represented inline with identifiers.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleTreeSchema extends SimpleFieldSchema {

package/src/simple-tree/api/simpleSchemaToJsonSchema.ts

@@ -150,8 +150,8 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 					};
 
 		// Don't include "description" property at all if it's not present in the input.
-		if (value.description !== undefined) {
-			output.description = value.description;
+		if (value.metadata?.description !== undefined) {
+			output.description = value.metadata.description;
 		}
 
 		properties[key] = output;

package/src/simple-tree/api/tree.ts

@@ -522,11 +522,13 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 export interface TreeViewAlpha<
 	in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
 > extends Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">,
-		Omit<TreeBranch, "events"> {
+		TreeBranch {
 	get root(): ReadableField<TSchema>;
 
 	set root(newRoot: InsertableField<TSchema>);
 
+	readonly events: Listenable<TreeViewEvents & TreeBranchEvents>;
+
 	initialize(content: InsertableField<TSchema>): void;
 
 	// Override the base branch method to return a typed view rather than merely a branch.
@@ -619,6 +621,16 @@ export interface TreeBranchEvents {
 	 */
 	schemaChanged(): void;
 
+	/**
+	 * Fired when a change is made to the branch. Includes data about the change that is made which listeners
+	 * can use to filter on changes they care about (e.g. local vs. remote changes).
+	 *
+	 * @param data - information about the change
+	 * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,
+	 * this change is not revertible.
+	 */
+	changed(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+
 	/**
 	 * Fired when:
 	 * - a local commit is applied outside of a transaction

package/src/simple-tree/api/typesUnsafe.ts

@@ -23,7 +23,7 @@ import type {
 	TreeNodeSchema,
 	TreeNodeSchemaCore,
 } from "../core/index.js";
-import type { TreeArrayNodeBase } from "../arrayNode.js";
+import type { TreeArrayNode } from "../arrayNode.js";
 import type { FlexListToUnion, LazyItem } from "../flexList.js";
 
 /*
@@ -238,7 +238,8 @@ export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
  * @system @sealed @public
  */
 export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAllowedTypes>>
-	extends TreeArrayNodeBase<
+	extends TreeArrayNode<
+		TAllowedTypes,
 		TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,
 		InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>
 	> {}

package/src/simple-tree/api/viewSchemaToSimpleSchema.ts

@@ -42,8 +42,8 @@ export function toSimpleTreeSchema(schema: ImplicitFieldSchema): SimpleTreeSchem
 	};
 
 	// Include the "description" property only if it's present on the input.
-	if (normalizedSchema.metadata?.description !== undefined) {
-		output.description = normalizedSchema.metadata.description;
+	if (normalizedSchema.metadata !== undefined) {
+		output.metadata = normalizedSchema.metadata;
 	}
 
 	return output;
@@ -140,9 +140,9 @@ function fieldSchemaToSimpleSchema(schema: FieldSchema): SimpleFieldSchema {
 		allowedTypes,
 	};
 
-	// Don't include "description" property at all if it's not present.
-	if (schema.metadata?.description !== undefined) {
-		result.description = schema.metadata.description;
+	// Don't include "metadata" property at all if it's not present.
+	if (schema.metadata !== undefined) {
+		result.metadata = schema.metadata;
 	}
 
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/simple-tree/arrayNode.ts

@@ -46,6 +46,7 @@ import {
 } from "./core/index.js";
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import { getUnhydratedContext } from "./createContext.js";
+import type { Unenforced } from "./api/index.js";
 
 /**
  * A covariant base type for {@link (TreeArrayNode:interface)}.
@@ -61,15 +62,25 @@ export interface ReadonlyArrayNode<out T = TreeNode | TreeLeafValue>
 		Awaited<TreeNode & WithType<string, NodeKind.Array>> {}
 
 /**
- * A generic array type, used to defined types like {@link (TreeArrayNode:interface)}.
+ * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
  *
- * @privateRemarks
- * Inlining this into TreeArrayNode causes recursive array use to stop compiling.
+ * @typeParam TAllowedTypes - Schema for types which are allowed as members of this array.
+ * @typeParam T - Use Default: Do not specify. Type of values to read from the array.
+ * @typeParam TNew - Use Default: Do not specify. Type of values to write into the array.
+ * @typeParam TMoveFrom - Use Default: Do not specify. Type of node from which children can be moved into this array.
  *
- * @system @sealed @public
+ * @sealed @public
  */
-export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom = ReadonlyArrayNode>
-	extends ReadonlyArrayNode<T> {
+export interface TreeArrayNode<
+	TAllowedTypes extends Unenforced<ImplicitAllowedTypes> = ImplicitAllowedTypes,
+	out T = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? TreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: TreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+	in TNew = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+	in TMoveFrom = ReadonlyArrayNode,
+> extends ReadonlyArrayNode<T> {
 	/**
 	 * Inserts new item(s) at a specified location.
 	 * @param index - The index at which to insert `value`.
@@ -369,20 +380,6 @@ export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom = ReadonlyArrayN
 	values(): IterableIterator<T>;
 }
 
-/**
- * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
- *
- * @typeParam TAllowedTypes - Schema for types which are allowed as members of this array.
- *
- * @sealed @public
- */
-export interface TreeArrayNode<
-	TAllowedTypes extends ImplicitAllowedTypes = ImplicitAllowedTypes,
-> extends TreeArrayNodeBase<
-		TreeNodeFromImplicitAllowedTypes<TAllowedTypes>,
-		InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
-	> {}
-
 /**
  * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
  * @public

package/src/simple-tree/index.ts

@@ -51,7 +51,14 @@ export {
 	type NodeChangedData,
 	TreeBeta,
 	type TreeChangeEventsBeta,
+	type SimpleNodeSchemaBase,
 	type SimpleTreeSchema,
+	type SimpleNodeSchema,
+	type SimpleFieldSchema,
+	type SimpleLeafNodeSchema,
+	type SimpleMapNodeSchema,
+	type SimpleArrayNodeSchema,
+	type SimpleObjectNodeSchema,
 	type JsonSchemaId,
 	type JsonSchemaType,
 	type JsonObjectNodeSchema,
@@ -133,6 +140,7 @@ export {
 	type InsertableField,
 	type Insertable,
 	type UnsafeUnknownSchema,
+	normalizeAllowedTypes,
 	type ApplyKindInput,
 	type InsertableTreeNodeFromAllowedTypes,
 	type Input,
@@ -146,7 +154,6 @@ export {
 export {
 	TreeArrayNode,
 	IterableTreeArrayContent,
-	type TreeArrayNodeBase,
 	type ReadonlyArrayNode,
 } from "./arrayNode.js";
 export {

package/src/simple-tree/leafNodeSchema.ts

@@ -68,8 +68,27 @@ function makeLeaf<Name extends string, const T extends ValueSchema>(
 }
 
 // Leaf schema shared between all SchemaFactory instances.
+/**
+ * @internal
+ */
 export const stringSchema = makeLeaf("string", ValueSchema.String);
+
+/**
+ * @internal
+ */
 export const numberSchema = makeLeaf("number", ValueSchema.Number);
+
+/**
+ * @internal
+ */
 export const booleanSchema = makeLeaf("boolean", ValueSchema.Boolean);
+
+/**
+ * @internal
+ */
 export const nullSchema = makeLeaf("null", ValueSchema.Null);
+
+/**
+ * @internal
+ */
 export const handleSchema = makeLeaf("handle", ValueSchema.FluidHandle);

package/src/simple-tree/schemaTypes.ts

@@ -31,6 +31,7 @@ import { isLazy, type FlexListToUnion, type LazyItem } from "./flexList.js";
 
 /**
  * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
+ * @internal
  */
 export function isTreeNodeSchemaClass<
 	Name extends string,
@@ -366,6 +367,8 @@ export function normalizeFieldSchema(schema: ImplicitFieldSchema): FieldSchema {
  *
  * @remarks Note: this must only be called after all required schemas have been declared, otherwise evaluation of
  * recursive schemas may fail.
+ *
+ * @internal
  */
 export function normalizeAllowedTypes(
 	types: ImplicitAllowedTypes,