Expose editor for flex fields (microsoft#22170)

## Description

This unifies the editing API of the flex layer by directly exposing the
field editor. Sequence fields already do this, however, they expose an
editor that uses cursors for new content. This updates the editor
exposed by sequence fields to accept MapTrees as new content, and
introduces the same pattern for value and optional fields. The flex
layer now translates from the MapTrees to cursors, rather than it being
done externally. This is part of a continued effort to simplify and
reduce the API surface of the flex layer.

This also removes the content setter from value/optional fields, since
it is now redundant with the editor.

Author: noencke

packages/dds/tree/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -121,15 +121,15 @@ export interface IDefaultEditBuilder {
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	valueField(field: FieldUpPath): ValueFieldEditBuilder;
+	valueField(field: FieldUpPath): ValueFieldEditBuilder<ITreeCursorSynchronous>;
 
 	/**
 	 * @param field - the optional field which is being edited under the parent node
 	 * @returns An object with methods to edit the given field of the given parent.
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	optionalField(field: FieldUpPath): OptionalFieldEditBuilder;
+	optionalField(field: FieldUpPath): OptionalFieldEditBuilder<ITreeCursorSynchronous>;
 
 	/**
 	 * @param field - the sequence field which is being edited under the parent node
@@ -138,7 +138,7 @@ export interface IDefaultEditBuilder {
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	sequenceField(field: FieldUpPath): SequenceFieldEditBuilder;
+	sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<ITreeCursorSynchronous>;
 
 	/**
 	 * Moves a subsequence from one sequence field to another sequence field.
@@ -183,7 +183,7 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		this.modularBuilder.addNodeExistsConstraint(path);
 	}
 
-	public valueField(field: FieldUpPath): ValueFieldEditBuilder {
+	public valueField(field: FieldUpPath): ValueFieldEditBuilder<ITreeCursorSynchronous> {
 		return {
 			set: (newContent: ITreeCursorSynchronous): void => {
 				const fillId = this.modularBuilder.generateId();
@@ -207,7 +207,7 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		};
 	}
 
-	public optionalField(field: FieldUpPath): OptionalFieldEditBuilder {
+	public optionalField(field: FieldUpPath): OptionalFieldEditBuilder<ITreeCursorSynchronous> {
 		return {
 			set: (newContent: ITreeCursorSynchronous | undefined, wasEmpty: boolean): void => {
 				const detachId = this.modularBuilder.generateId();
@@ -329,7 +329,7 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		}
 	}
 
-	public sequenceField(field: FieldUpPath): SequenceFieldEditBuilder {
+	public sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<ITreeCursorSynchronous> {
 		return {
 			insert: (index: number, content: ITreeCursorSynchronous): void => {
 				const length =
@@ -386,36 +386,36 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 
 /**
  */
-export interface ValueFieldEditBuilder {
+export interface ValueFieldEditBuilder<TContent> {
 	/**
 	 * Issues a change which replaces the current newContent of the field with `newContent`.
 	 * @param newContent - the new content for the field.
 	 * The cursor can be in either Field or Node mode and must represent exactly one node.
 	 */
-	set(newContent: ITreeCursorSynchronous): void;
+	set(newContent: TContent): void;
 }
 
 /**
  */
-export interface OptionalFieldEditBuilder {
+export interface OptionalFieldEditBuilder<TContent> {
 	/**
 	 * Issues a change which replaces the current newContent of the field with `newContent`
 	 * @param newContent - the new content for the field.
 	 * If provided, the cursor can be in either Field or Node mode and must represent exactly one node.
 	 * @param wasEmpty - whether the field is empty when creating this change
 	 */
-	set(newContent: ITreeCursorSynchronous | undefined, wasEmpty: boolean): void;
+	set(newContent: TContent | undefined, wasEmpty: boolean): void;
 }
 
 /**
  */
-export interface SequenceFieldEditBuilder {
+export interface SequenceFieldEditBuilder<TContent> {
 	/**
 	 * Issues a change which inserts the `newContent` at the given `index`.
 	 * @param index - the index at which to insert the `newContent`.
 	 * @param newContent - the new content to be inserted in the field. Cursor can be in either Field or Node mode.
 	 */
-	insert(index: number, newContent: ITreeCursorSynchronous): void;
+	insert(index: number, newContent: TContent): void;
 
 	/**
 	 * Issues a change which removes `count` elements starting at the given `index`.

packages/dds/tree/src/feature-libraries/flex-map-tree/mapTreeNode.ts

@@ -50,7 +50,12 @@ import {
 } from "../typed-schema/index.js";
 import { type FlexImplicitAllowedTypes, normalizeAllowedTypes } from "../schemaBuilderBase.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
-import { FieldKinds, type SequenceFieldEditBuilder } from "../default-schema/index.js";
+import {
+	FieldKinds,
+	type OptionalFieldEditBuilder,
+	type SequenceFieldEditBuilder,
+	type ValueFieldEditBuilder,
+} from "../default-schema/index.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 // #region Nodes
@@ -431,18 +436,23 @@ class EagerMapTreeRequiredField<T extends FlexAllowedTypes>
 	extends EagerMapTreeField<T>
 	implements FlexTreeRequiredField<T>
 {
+	public get editor(): ValueFieldEditBuilder<ExclusiveMapTree> {
+		throw unsupportedUsageError("Setting a required field");
+	}
+
 	public get content(): FlexTreeUnboxNodeUnion<T> {
 		return unboxedUnion(this.schema, this.mapTrees[0] ?? oob(), { parent: this, index: 0 });
 	}
-	public set content(_: FlexTreeUnboxNodeUnion<T>) {
-		throw unsupportedUsageError("Setting an optional field");
-	}
 }
 
 class EagerMapTreeOptionalField<T extends FlexAllowedTypes>
 	extends EagerMapTreeField<T>
 	implements FlexTreeOptionalField<T>
 {
+	public get editor(): OptionalFieldEditBuilder<ExclusiveMapTree> {
+		throw unsupportedUsageError("Setting an optional field");
+	}
+
 	public get content(): FlexTreeUnboxNodeUnion<T> | undefined {
 		return this.mapTrees.length > 0
 			? unboxedUnion(this.schema, this.mapTrees[0] ?? oob(), {
@@ -451,15 +461,16 @@ class EagerMapTreeOptionalField<T extends FlexAllowedTypes>
 				})
 			: undefined;
 	}
-	public set content(_: FlexTreeUnboxNodeUnion<T> | undefined) {
-		throw unsupportedUsageError("Setting an optional field");
-	}
 }
 
 class EagerMapTreeSequenceField<T extends FlexAllowedTypes>
 	extends EagerMapTreeField<T>
 	implements FlexTreeSequenceField<T>
 {
+	public get editor(): SequenceFieldEditBuilder<ExclusiveMapTree[]> {
+		throw unsupportedUsageError("Editing an array");
+	}
+
 	public at(index: number): FlexTreeUnboxNodeUnion<T> | undefined {
 		const i = indexForAt(index, this.length);
 		if (i === undefined) {
@@ -480,12 +491,8 @@ class EagerMapTreeSequenceField<T extends FlexAllowedTypes>
 		}
 	}
 
-	public sequenceEditor(): SequenceFieldEditBuilder {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-
 	public getFieldPath(): FieldUpPath {
-		throw unsupportedUsageError("Editing a sequence");
+		throw unsupportedUsageError("Editing an array");
 	}
 }
 

packages/dds/tree/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -12,7 +12,12 @@ import {
 	anchorSlot,
 } from "../../core/index.js";
 import type { Assume, FlattenKeys } from "../../util/index.js";
-import type { FieldKinds, SequenceFieldEditBuilder } from "../default-schema/index.js";
+import type {
+	FieldKinds,
+	SequenceFieldEditBuilder,
+	ValueFieldEditBuilder,
+	OptionalFieldEditBuilder,
+} from "../default-schema/index.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
 import type {
 	Any,
@@ -686,7 +691,7 @@ export interface FlexTreeSequenceField<in out TTypes extends FlexAllowedTypes>
 	/**
 	 * Get an editor for this sequence.
 	 */
-	sequenceEditor(): SequenceFieldEditBuilder;
+	editor: SequenceFieldEditBuilder<FlexibleFieldContent>;
 
 	boxedIterator(): IterableIterator<FlexTreeTypedNodeUnion<TTypes>>;
 
@@ -707,7 +712,8 @@ export interface FlexTreeSequenceField<in out TTypes extends FlexAllowedTypes>
 export interface FlexTreeRequiredField<in out TTypes extends FlexAllowedTypes>
 	extends FlexTreeField {
 	get content(): FlexTreeUnboxNodeUnion<TTypes>;
-	set content(content: FlexibleNodeContent);
+
+	editor: ValueFieldEditBuilder<FlexibleNodeContent>;
 }
 
 /**
@@ -726,7 +732,8 @@ export interface FlexTreeRequiredField<in out TTypes extends FlexAllowedTypes>
 export interface FlexTreeOptionalField<in out TTypes extends FlexAllowedTypes>
 	extends FlexTreeField {
 	get content(): FlexTreeUnboxNodeUnion<TTypes> | undefined;
-	set content(newContent: FlexibleNodeContent | undefined);
+
+	editor: OptionalFieldEditBuilder<FlexibleNodeContent>;
 }
 
 // #endregion

packages/dds/tree/src/feature-libraries/flex-tree/lazyField.ts

@@ -7,9 +7,11 @@ import { assert } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
+	type ExclusiveMapTree,
 	type FieldAnchor,
 	type FieldKey,
 	type FieldUpPath,
+	type ITreeCursorSynchronous,
 	type ITreeSubscriptionCursor,
 	type TreeNavigationResult,
 	inCursorNode,
@@ -37,7 +39,6 @@ import {
 	type FlexTreeTypedField,
 	type FlexTreeTypedNodeUnion,
 	type FlexTreeUnboxNodeUnion,
-	type FlexibleNodeContent,
 	TreeStatus,
 	flexTreeMarker,
 	flexTreeSlot,
@@ -54,7 +55,7 @@ import { type LazyTreeNode, makeTree } from "./lazyNode.js";
 import { unboxedUnion } from "./unboxed.js";
 import { indexForAt, treeStatusFromAnchorCache } from "./utilities.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { cursorForMapTreeNode } from "../mapTreeCursor.js";
+import { cursorForMapTreeField, cursorForMapTreeNode } from "../mapTreeCursor.js";
 
 /**
  * Reuse fields.
@@ -297,10 +298,21 @@ export class LazySequence<TTypes extends FlexAllowedTypes>
 		return this.map((x) => x);
 	}
 
-	public sequenceEditor(): SequenceFieldEditBuilder {
+	public editor: SequenceFieldEditBuilder<ExclusiveMapTree[]> = {
+		insert: (index, newContent) => {
+			this.sequenceEditor().insert(index, cursorForMapTreeField(newContent));
+		},
+		remove: (index, count) => {
+			this.sequenceEditor().remove(index, count);
+		},
+		move: (sourceIndex, count, destIndex) => {
+			this.sequenceEditor().move(sourceIndex, count, destIndex);
+		},
+	};
+
+	private sequenceEditor(): SequenceFieldEditBuilder<ITreeCursorSynchronous> {
 		const fieldPath = this.getFieldPathForEditing();
-		const fieldEditor = this.context.checkout.editor.sequenceField(fieldPath);
-		return fieldEditor;
+		return this.context.checkout.editor.sequenceField(fieldPath);
 	}
 }
 
@@ -317,13 +329,15 @@ export class ReadonlyLazyValueField<TTypes extends FlexAllowedTypes>
 		super(context, schema, cursor, fieldAnchor);
 	}
 
+	public editor: ValueFieldEditBuilder<ExclusiveMapTree> = {
+		set: (newContent) => {
+			assert(false, "Unexpected set of readonly field");
+		},
+	};
+
 	public get content(): FlexTreeUnboxNodeUnion<TTypes> {
 		return this.atIndex(0);
 	}
-
-	public set content(newContent: FlexibleNodeContent) {
-		fail("cannot set content in readonly field");
-	}
 }
 
 export class LazyValueField<TTypes extends FlexAllowedTypes>
@@ -339,7 +353,13 @@ export class LazyValueField<TTypes extends FlexAllowedTypes>
 		super(context, schema, cursor, fieldAnchor);
 	}
 
-	private valueFieldEditor(): ValueFieldEditBuilder {
+	public override editor: ValueFieldEditBuilder<ExclusiveMapTree> = {
+		set: (newContent) => {
+			this.valueFieldEditor().set(cursorForMapTreeNode(newContent));
+		},
+	};
+
+	private valueFieldEditor(): ValueFieldEditBuilder<ITreeCursorSynchronous> {
 		const fieldPath = this.getFieldPathForEditing();
 		const fieldEditor = this.context.checkout.editor.valueField(fieldPath);
 		return fieldEditor;
@@ -348,11 +368,6 @@ export class LazyValueField<TTypes extends FlexAllowedTypes>
 	public override get content(): FlexTreeUnboxNodeUnion<TTypes> {
 		return this.atIndex(0);
 	}
-
-	public override set content(newContent: FlexibleNodeContent) {
-		assert(newContent !== undefined, "Cannot set a required field to undefined");
-		this.valueFieldEditor().set(cursorForMapTreeNode(newContent));
-	}
 }
 
 export class LazyIdentifierField<TTypes extends FlexAllowedTypes>
@@ -382,7 +397,16 @@ export class LazyOptionalField<TTypes extends FlexAllowedTypes>
 		super(context, schema, cursor, fieldAnchor);
 	}
 
-	private optionalEditor(): OptionalFieldEditBuilder {
+	public editor: OptionalFieldEditBuilder<ExclusiveMapTree> = {
+		set: (newContent, wasEmpty) => {
+			this.optionalEditor().set(
+				newContent !== undefined ? cursorForMapTreeNode(newContent) : newContent,
+				wasEmpty,
+			);
+		},
+	};
+
+	private optionalEditor(): OptionalFieldEditBuilder<ITreeCursorSynchronous> {
 		const fieldPath = this.getFieldPathForEditing();
 		const fieldEditor = this.context.checkout.editor.optionalField(fieldPath);
 		return fieldEditor;
@@ -391,13 +415,6 @@ export class LazyOptionalField<TTypes extends FlexAllowedTypes>
 	public get content(): FlexTreeUnboxNodeUnion<TTypes> | undefined {
 		return this.length === 0 ? undefined : this.atIndex(0);
 	}
-
-	public set content(newContent: FlexibleNodeContent | undefined) {
-		this.optionalEditor().set(
-			newContent !== undefined ? cursorForMapTreeNode(newContent) : undefined,
-			this.length === 0,
-		);
-	}
 }
 
 export class LazyForbiddenField<TTypes extends FlexAllowedTypes> extends LazyField<

packages/dds/tree/src/feature-libraries/flex-tree/lazyNode.ts

@@ -338,7 +338,7 @@ export class LazyMap<TSchema extends FlexMapNodeSchema>
 
 		if (fieldSchema.kind === FieldKinds.optional) {
 			const optionalField = field as FlexTreeOptionalField<FlexAllowedTypes>;
-			optionalField.content = content?.[0];
+			optionalField.editor.set(content?.[0], optionalField.length === 0);
 		} else {
 			assert(fieldSchema.kind === FieldKinds.sequence, 0x807 /* Unexpected map field kind */);
 
@@ -477,7 +477,7 @@ function buildStructClass<TSchema extends FlexObjectNodeSchema>(
 						key,
 						fieldSchema,
 					) as FlexTreeOptionalField<FlexAllowedTypes>;
-					field.content = newContent;
+					field.editor.set(newContent, field.length === 0);
 				};
 				break;
 			}
@@ -488,7 +488,7 @@ function buildStructClass<TSchema extends FlexObjectNodeSchema>(
 						key,
 						fieldSchema,
 					) as FlexTreeRequiredField<FlexAllowedTypes>;
-					field.content = newContent;
+					field.editor.set(newContent);
 				};
 				break;
 			}

packages/dds/tree/src/feature-libraries/index.ts

@@ -51,6 +51,7 @@ export {
 	cursorForMapTreeField,
 	cursorForMapTreeNode,
 	mapTreeFromCursor,
+	mapTreeFieldFromCursor,
 } from "./mapTreeCursor.js";
 export { MemoizedIdRangeAllocator, type IdRange } from "./memoizedIdRangeAllocator.js";
 export { buildForest } from "./object-forest/index.js";

packages/dds/tree/src/feature-libraries/mapTreeCursor.ts

@@ -76,3 +76,11 @@ export function mapTreeFromCursor(cursor: ITreeCursor): ExclusiveMapTree {
 
 	return node;
 }
+
+/**
+ * Extract an array of MapTrees (a field) from the contents of the given ITreeCursor's current field.
+ */
+export function mapTreeFieldFromCursor(cursor: ITreeCursor): ExclusiveMapTree[] {
+	assert(cursor.mode === CursorLocationType.Fields, "must start at field");
+	return mapCursorField(cursor, mapTreeFromCursor);
+}