@fluidframework/tree 2.10.0-304831 → 2.10.0-306579

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

@@ -1096,7 +1096,7 @@ export function arraySchema<
 				// Since proxy reports this as a "non-configurable" property, it must exist on the underlying object used as the proxy target, not as an inherited property.
 				// This should not get used as the proxy should intercept all use.
 				Object.defineProperty(instance, "length", {
-					value: NaN,
+					value: Number.NaN,
 					writable: true,
 					enumerable: false,
 					configurable: false,

package/src/simple-tree/core/treeNodeKernel.ts

@@ -95,7 +95,7 @@ function isHydrated(state: HydrationState): state is HydratedState {
  * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
  * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
  */
-export class TreeNodeKernel implements Listenable<KernelEvents> {
+export class TreeNodeKernel {
 	private disposed = false;
 
 	/**
@@ -205,9 +205,9 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 		this.#hydrationState = {
 			anchorNode,
 			offAnchorNode: new Set([
-				anchorNode.on("afterDestroy", () => this.dispose()),
+				anchorNode.events.on("afterDestroy", () => this.dispose()),
 				// TODO: this should be triggered on change even for unhydrated nodes.
-				anchorNode.on("childrenChanging", () => {
+				anchorNode.events.on("childrenChanging", () => {
 					this.generationNumber += 1;
 				}),
 			]),
@@ -221,7 +221,7 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 					this.#hydrationState.offAnchorNode.add(
 						// Argument is forwarded between matching events, so the type should be correct.
 						// eslint-disable-next-line @typescript-eslint/no-explicit-any
-						anchorNode.on(eventName, (arg: any) => events.emit(eventName, arg)),
+						anchorNode.events.on(eventName, (arg: any) => events.emit(eventName, arg)),
 					);
 				}
 			}
@@ -248,13 +248,11 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 		return treeStatusFromAnchorCache(this.#hydrationState.anchorNode);
 	}
 
-	public on<K extends keyof KernelEvents>(eventName: K, listener: KernelEvents[K]): Off {
+	public get events(): Listenable<KernelEvents> {
 		// Retrieve the correct events object based on whether this node is pre or post hydration.
-		const events: Listenable<KernelEvents> = isHydrated(this.#hydrationState)
-			? this.#hydrationState.anchorNode
+		return isHydrated(this.#hydrationState)
+			? this.#hydrationState.anchorNode.events
 			: this.#unhydratedEvents.value;
-
-		return events.on(eventName, listener);
 	}
 
 	public dispose(): void {
@@ -339,7 +337,7 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 			off();
 		};
 		anchorForgetters.set(this.node, forget);
-		const off = anchorNode.on("afterDestroy", forget);
+		const off = anchorNode.events.on("afterDestroy", forget);
 		return anchorNode;
 	}
 

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,

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/proxies.ts

@@ -172,7 +172,7 @@ function bindProxies(proxies: RootedProxyPaths[], forest: IForestSubscription):
 	if (proxies.length > 0) {
 		// Creating a new array emits one event per element in the array, so listen to the event once for each element
 		let i = 0;
-		const off = forest.on("afterRootFieldCreated", (fieldKey) => {
+		const off = forest.events.on("afterRootFieldCreated", (fieldKey) => {
 			// Non null asserting here because of the length check above
 			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 			(proxies[i]!.rootPath as Mutable<UpPath>).parentField = fieldKey;

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,
@@ -473,9 +476,34 @@ function evaluateLazySchema(value: LazyItem<TreeNodeSchema>): TreeNodeSchema {
 }
 
 /**
- * Types allowed in a field.
+ * Types of {@link TreeNode|TreeNodes} or {@link TreeLeafValue|TreeLeafValues} allowed at a location in a tree.
  * @remarks
+ * Used by {@link TreeViewConfiguration} for the root and various kinds of {@link TreeNodeSchema} to specify their allowed child types.
+ *
+ * Use {@link SchemaFactory} to access leaf schema or declare new composite schema.
+ *
  * Implicitly treats a single type as an array of one type.
+ *
+ * Arrays of schema can be used to specify multiple types are allowed, which result in unions of those types in the Tree APIs.
+ *
+ * When saved into variables, avoid type-erasing the details, as doing so loses the compile time schema awareness of APIs derived from the types.
+ *
+ * When referring to types that are declared after the definition of the `ImplicitAllowedTypes`, the schema can be wrapped in a lambda to allow the forward reference.
+ * See {@link ValidateRecursiveSchema} for details on how to structure the `ImplicitAllowedTypes` instances when constructing recursive schema.
+ *
+ * @example Explicit use with strong typing
+ * ```typescript
+ * const sf = new SchemaFactory("myScope");
+ * const childTypes = [sf.number, sf.string] as const satisfies ImplicitAllowedTypes;
+ * const config = new TreeViewConfiguration({ schema: childTypes });
+ * ```
+ *
+ * @example Forward reference
+ * ```typescript
+ * const sf = new SchemaFactory("myScope");
+ * class A extends sf.array("example", [() => B]) {}
+ * class B extends sf.array("Inner", sf.number) {}
+ * ```
  * @public
  */
 export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;

package/src/simple-tree/treeNodeValid.ts

@@ -103,7 +103,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 			// would not see the stored `constructorCached`, and the validation above against multiple derived classes would not work.
 
 			// This is not just an alias of `this`, but a reference to the item in the prototype chain being walked, which happens to start at `this`.
-			// eslint-disable-next-line @typescript-eslint/no-this-alias
+			// eslint-disable-next-line @typescript-eslint/no-this-alias, unicorn/no-this-assignment
 			let schemaBase: typeof TreeNodeValid = this;
 			while (!Object.prototype.hasOwnProperty.call(schemaBase, "constructorCached")) {
 				schemaBase = Reflect.getPrototypeOf(schemaBase) as typeof TreeNodeValid;
@@ -300,7 +300,7 @@ function formattedReference(
 	object: unknown,
 	config?: DevtoolsFormatter.ObjectConfig,
 ): DevtoolsFormatter.Item {
-	if (typeof object === "undefined") {
+	if (object === undefined) {
 		return ["span", "undefined"];
 	} else if (object === "null") {
 		return ["span", "null"];

package/src/util/nestedMap.ts

@@ -4,6 +4,7 @@
  */
 
 import { oob } from "@fluidframework/core-utils/internal";
+
 import type { MapGetSet } from "./utils.js";
 
 /**