@fluidframework/tree 2.74.0 → 2.81.0-374083

package/src/feature-libraries/default-schema/defaultFieldKinds.ts

@@ -7,13 +7,12 @@ import { fail } from "@fluidframework/core-utils/internal";
 
 import {
 	type ChangeAtomId,
-	type DeltaDetachedNodeId,
+	type DeltaFieldChanges,
 	type FieldKindIdentifier,
 	forbiddenFieldKindIdentifier,
 	Multiplicity,
 } from "../../core/index.js";
 import {
-	type FieldChangeDelta,
 	type FieldChangeHandler,
 	type FieldEditor,
 	type FieldKindConfiguration,
@@ -50,8 +49,7 @@ export const noChangeHandler: FieldChangeHandler<0> = {
 	}),
 	codecsFactory: () => noChangeCodecFamily,
 	editor: { buildChildChanges: () => fail(0xb0d /* Child changes not supported */) },
-	intoDelta: (change, deltaFromChild: ToDelta): FieldChangeDelta => ({}),
-	relevantRemovedRoots: (change): Iterable<DeltaDetachedNodeId> => [],
+	intoDelta: (change, deltaFromChild: ToDelta): DeltaFieldChanges => [],
 	isEmpty: (change: 0) => true,
 	getNestedChanges: (change: 0) => [],
 	createEmpty: () => 0,
@@ -202,15 +200,35 @@ export const fieldKindConfigurations: ReadonlyMap<
 			[identifier.identifier, { kind: identifier, formatVersion: 1 }],
 		]),
 	],
+	[
+		brand(5),
+		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
+			[required.identifier, { kind: required, formatVersion: 2 }],
+			[optional.identifier, { kind: optional, formatVersion: 2 }],
+			[sequence.identifier, { kind: sequence, formatVersion: 3 }],
+			[forbidden.identifier, { kind: forbidden, formatVersion: 1 }],
+			[identifier.identifier, { kind: identifier, formatVersion: 1 }],
+		]),
+	],
+	[
+		brand(101), // Detached roots
+		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
+			[required.identifier, { kind: required, formatVersion: 2 }],
+			[optional.identifier, { kind: optional, formatVersion: 3 }],
+			[sequence.identifier, { kind: sequence, formatVersion: 2 }],
+			[forbidden.identifier, { kind: forbidden, formatVersion: 1 }],
+			[identifier.identifier, { kind: identifier, formatVersion: 1 }],
+		]),
+	],
 ]);
 
-export type ModularChangeFormatVersion = Brand<3 | 4, "ModularChangeFormatVersion">;
+export type ModularChangeFormatVersion = Brand<3 | 4 | 5 | 101, "ModularChangeFormatVersion">;
 export function getCodecTreeForModularChangeFormat(
 	version: ModularChangeFormatVersion,
 ): CodecTree {
 	const dependencies =
 		fieldKindConfigurations.get(version) ?? fail(0xc7c /* Unknown modular change format */);
-	const children: CodecTree[] = Array.from(dependencies.entries()).map(
+	const children: CodecTree[] = [...dependencies.entries()].map(
 		([key, { formatVersion }]) => ({
 			name: `FieldKind:${key}`,
 			version: formatVersion,

package/src/feature-libraries/default-schema/index.ts

@@ -19,14 +19,26 @@ export {
 
 export {
 	type DefaultChangeset,
+	type DetachedRootIds,
+	type DetachedRootIdRange,
 	DefaultChangeFamily,
-	DefaultEditBuilder,
-	type IDefaultEditBuilder,
-	type ValueFieldEditBuilder,
-	type OptionalFieldEditBuilder,
-	type SequenceFieldEditBuilder,
+	type IdBasedChangeFamilyDataEditor,
+	DefaultIdBasedDataEditor,
+	type DataEditor,
+	type RequiredFieldEditor,
+	type OptionalFieldEditor,
+	type SequenceFieldEditor,
 	intoDelta,
+	getBuildsIds,
 	relevantRemovedRoots,
 } from "./defaultEditBuilder.js";
 
+export {
+	type DetachedRootLocation,
+	type DetachedRootsLocation,
+	type Locator,
+	LocationBasedDataEditor,
+	type ILocationBasedDataEditor,
+} from "./locationBasedEditBuilder.js";
+
 export { MappedEditBuilder } from "./mappedEditBuilder.js";

package/src/feature-libraries/default-schema/locationBasedEditBuilder.ts

@@ -0,0 +1,188 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import {
+	type ChangeAtomId,
+	type FieldKey,
+	type FieldUpPath,
+	type UpPath,
+	type TreeChunk,
+	type NormalizedUpPath,
+	type NormalizedFieldUpPath,
+	rootFieldKey,
+	makeDetachedNodeId,
+} from "../../core/index.js";
+
+import type {
+	DetachedRootIds,
+	DataEditor,
+	OptionalFieldEditor,
+	RequiredFieldEditor,
+	SequenceFieldEditor,
+} from "./defaultEditBuilder.js";
+
+export type DetachedRootLocation = FieldKey;
+export type DetachedRootsLocation = readonly DetachedRootRangeLocation[];
+export interface DetachedRootRangeLocation {
+	readonly field: FieldKey;
+	readonly count: number;
+}
+
+export interface Locator {
+	locationFromId(id: ChangeAtomId): DetachedRootLocation;
+	idFromLocation(id: DetachedRootLocation): ChangeAtomId;
+	locationsFromIdRanges(id: DetachedRootIds): DetachedRootsLocation;
+	idRangesFromLocations(id: DetachedRootsLocation): DetachedRootIds;
+}
+
+export type ILocationBasedDataEditor = DataEditor<
+	TreeChunk,
+	DetachedRootLocation,
+	DetachedRootsLocation
+>;
+
+/**
+ * Implementation of {@link DataEditor} based on the default set of supported field kinds.
+ * @sealed
+ */
+export class LocationBasedDataEditor
+	implements DataEditor<TreeChunk, DetachedRootLocation, DetachedRootsLocation>
+{
+	public constructor(
+		private readonly idBasedEditor: DataEditor<TreeChunk, ChangeAtomId, DetachedRootIds>,
+		private readonly locator: Locator,
+	) {}
+
+	public addNodeExistsConstraint(path: UpPath): void {
+		const normal = normalizeUpPath(path, this.locator);
+		this.idBasedEditor.addNodeExistsConstraint(normal);
+	}
+
+	public addNodeExistsConstraintOnRevert(path: UpPath): void {
+		const normal = normalizeUpPath(path, this.locator);
+		this.idBasedEditor.addNodeExistsConstraintOnRevert(normal);
+	}
+
+	public addNoChangeConstraint(): void {
+		this.idBasedEditor.addNoChangeConstraint();
+	}
+
+	public addNoChangeConstraintOnRevert(): void {
+		this.idBasedEditor.addNoChangeConstraintOnRevert();
+	}
+
+	public buildRoots(content: TreeChunk): DetachedRootsLocation {
+		const roots = this.idBasedEditor.buildRoots(content);
+		const locations = this.locator.locationsFromIdRanges(roots);
+		return locations;
+	}
+
+	public valueField(field: FieldUpPath): RequiredFieldEditor<TreeChunk, DetachedRootLocation> {
+		const normal = normalizeFieldUpPath(field, this.locator);
+		const lowLevelEditor = this.idBasedEditor.valueField(normal);
+		const locator = this.locator;
+		const editBuilder = {
+			set: (newContent: TreeChunk): void => {
+				lowLevelEditor.set(newContent);
+			},
+			attach: (newContent: DetachedRootLocation): void => {
+				const changeAtom = locator.idFromLocation(newContent);
+				lowLevelEditor.attach(changeAtom);
+			},
+		};
+		return editBuilder;
+	}
+
+	public optionalField(
+		field: FieldUpPath,
+	): OptionalFieldEditor<TreeChunk, DetachedRootLocation> {
+		const normal = normalizeFieldUpPath(field, this.locator);
+		const lowLevelEditor = this.idBasedEditor.optionalField(normal);
+		const locator = this.locator;
+		const editBuilder = {
+			set: (newContent: TreeChunk | undefined, wasEmpty: boolean): void => {
+				lowLevelEditor.set(newContent, wasEmpty);
+			},
+			attach: (newContent: DetachedRootLocation | undefined, wasEmpty: boolean): void => {
+				if (newContent === undefined) {
+					editBuilder.clear(wasEmpty);
+					return;
+				}
+				const changeAtom = locator.idFromLocation(newContent);
+				lowLevelEditor.attach(changeAtom, wasEmpty);
+			},
+			clear: (wasEmpty: boolean): void => {
+				lowLevelEditor.clear(wasEmpty);
+			},
+		};
+		return editBuilder;
+	}
+
+	public move(
+		sourceField: FieldUpPath,
+		sourceIndex: number,
+		count: number,
+		destinationField: FieldUpPath,
+		destIndex: number,
+	): void {
+		const normalSource = normalizeFieldUpPath(sourceField, this.locator);
+		const normalDestination = normalizeFieldUpPath(destinationField, this.locator);
+		this.idBasedEditor.move(normalSource, sourceIndex, count, normalDestination, destIndex);
+	}
+
+	public sequenceField(
+		field: FieldUpPath,
+	): SequenceFieldEditor<TreeChunk, DetachedRootsLocation> {
+		const normal = normalizeFieldUpPath(field, this.locator);
+		const lowLevelEditor = this.idBasedEditor.sequenceField(normal);
+		const locator = this.locator;
+		const editBuilder = {
+			insert: (index: number, content: TreeChunk): void => {
+				lowLevelEditor.insert(index, content);
+			},
+			attach: (index: number, newContent: DetachedRootsLocation): void => {
+				const range = locator.idRangesFromLocations(newContent);
+				lowLevelEditor.attach(index, range);
+			},
+			remove: (index: number, count: number): void => {
+				lowLevelEditor.remove(index, count);
+			},
+		};
+		return editBuilder;
+	}
+}
+
+function normalizeUpPath(path: UpPath, locator: Locator): NormalizedUpPath {
+	if (path.parent === undefined) {
+		if (path.parentField === rootFieldKey) {
+			return { ...path, parent: undefined, detachedNodeId: undefined };
+		} else {
+			const nodeId = locator.idFromLocation(path.parentField);
+			const detachedNodeId = makeDetachedNodeId(nodeId.revision, nodeId.localId);
+			return { ...path, parent: undefined, detachedNodeId };
+		}
+	} else {
+		return {
+			parent: normalizeUpPath(path.parent, locator),
+			parentField: path.parentField,
+			parentIndex: path.parentIndex,
+		};
+	}
+}
+
+function normalizeFieldUpPath(path: FieldUpPath, locator: Locator): NormalizedFieldUpPath {
+	if (path.parent === undefined) {
+		if (path.field === rootFieldKey) {
+			return { parent: undefined, field: rootFieldKey };
+		} else {
+			throw new UsageError(
+				"Editing only allowed on the root field or on fields under nodes with TreeStatus.InDocument or TreeStatus.Removed status",
+			);
+		}
+	} else {
+		return { parent: normalizeUpPath(path.parent, locator), field: path.field };
+	}
+}

package/src/feature-libraries/default-schema/mappedEditBuilder.ts

@@ -6,30 +6,45 @@
 import type { NormalizedFieldUpPath, NormalizedUpPath } from "../../core/index.js";
 
 import type {
-	IDefaultEditBuilder,
-	OptionalFieldEditBuilder,
-	SequenceFieldEditBuilder,
-	ValueFieldEditBuilder,
+	DataEditor,
+	OptionalFieldEditor,
+	SequenceFieldEditor,
+	RequiredFieldEditor,
 } from "./defaultEditBuilder.js";
 
 /**
  * An IDefaultEditBuilder implementation based on another IDefaultEditBuilder that uses a different content type for insertions.
  */
-export class MappedEditBuilder<TBase, TAdapted> implements IDefaultEditBuilder<TAdapted> {
+export class MappedEditBuilder<TBase, TAdapted, TDetachedRoot, TDetachedRoots>
+	implements DataEditor<TAdapted, TDetachedRoot, TDetachedRoots>
+{
 	public constructor(
-		private readonly baseBuilder: IDefaultEditBuilder<TBase>,
+		private readonly baseBuilder: DataEditor<TBase, TDetachedRoot, TDetachedRoots>,
 		private readonly mapDelegate: (input: TAdapted) => TBase,
 	) {}
-	public valueField(field: NormalizedFieldUpPath): ValueFieldEditBuilder<TAdapted> {
+
+	public buildRoots(content: TAdapted): TDetachedRoots {
+		return this.baseBuilder.buildRoots(this.mapDelegate(content));
+	}
+
+	public valueField(
+		field: NormalizedFieldUpPath,
+	): RequiredFieldEditor<TAdapted, TDetachedRoot> {
 		const baseField = this.baseBuilder.valueField(field);
 		return {
 			set: (newContent: TAdapted): void => {
 				const mappedContent = this.mapDelegate(newContent);
 				baseField.set(mappedContent);
 			},
+			attach: (content: TDetachedRoot): void => {
+				baseField.attach(content);
+			},
 		};
 	}
-	public optionalField(field: NormalizedFieldUpPath): OptionalFieldEditBuilder<TAdapted> {
+
+	public optionalField(
+		field: NormalizedFieldUpPath,
+	): OptionalFieldEditor<TAdapted, TDetachedRoot> {
 		const baseField = this.baseBuilder.optionalField(field);
 		return {
 			set: (newContent: TAdapted | undefined, wasEmpty: boolean): void => {
@@ -37,9 +52,17 @@ export class MappedEditBuilder<TBase, TAdapted> implements IDefaultEditBuilder<T
 					newContent === undefined ? undefined : this.mapDelegate(newContent);
 				baseField.set(mappedContent, wasEmpty);
 			},
+			attach: (content, wasEmpty: boolean): void => {
+				baseField.attach(content, wasEmpty);
+			},
+			clear(wasEmpty: boolean): void {
+				baseField.clear(wasEmpty);
+			},
 		};
 	}
-	public sequenceField(field: NormalizedFieldUpPath): SequenceFieldEditBuilder<TAdapted> {
+	public sequenceField(
+		field: NormalizedFieldUpPath,
+	): SequenceFieldEditor<TAdapted, TDetachedRoots> {
 		const baseField = this.baseBuilder.sequenceField(field);
 		return {
 			insert: (index: number, content: TAdapted): void => {
@@ -49,6 +72,9 @@ export class MappedEditBuilder<TBase, TAdapted> implements IDefaultEditBuilder<T
 			remove: (index: number, count: number): void => {
 				baseField.remove(index, count);
 			},
+			attach: (index: number, detachedContent: TDetachedRoots): void => {
+				baseField.attach(index, detachedContent);
+			},
 		};
 	}
 	public move(
@@ -66,4 +92,10 @@ export class MappedEditBuilder<TBase, TAdapted> implements IDefaultEditBuilder<T
 	public addNodeExistsConstraintOnRevert(path: NormalizedUpPath): void {
 		this.baseBuilder.addNodeExistsConstraintOnRevert(path);
 	}
+	public addNoChangeConstraint(): void {
+		this.baseBuilder.addNoChangeConstraint();
+	}
+	public addNoChangeConstraintOnRevert(): void {
+		this.baseBuilder.addNoChangeConstraintOnRevert();
+	}
 }

package/src/feature-libraries/deltaUtils.ts

@@ -7,14 +7,19 @@ import {
 	type ChangeAtomId,
 	type DeltaDetachedNodeId,
 	type DeltaRoot,
+	makeChangeAtomId,
 	makeDetachedNodeId,
 } from "../core/index.js";
-import type { Mutable } from "../util/index.js";
+import { brand, type Mutable } from "../util/index.js";
 
 export function nodeIdFromChangeAtom(changeAtom: ChangeAtomId): DeltaDetachedNodeId {
 	return makeDetachedNodeId(changeAtom.revision, changeAtom.localId);
 }
 
+export function changeAtomFromDetachedNodeId(changeAtom: DeltaDetachedNodeId): ChangeAtomId {
+	return makeChangeAtomId(brand(changeAtom.minor), changeAtom.major);
+}
+
 /**
  * Converts a `Delta.Root` whose tree content is represented with by `TIn` instances
  * into a `Delta.Root`whose tree content is represented with by `TOut` instances.

package/src/feature-libraries/flex-tree/context.ts

@@ -51,6 +51,8 @@ export interface FlexTreeContext {
 	 * If true, none of the nodes in this context can be used.
 	 */
 	isDisposed(): boolean;
+
+	runInTransaction(fn: () => void): void;
 }
 
 /**
@@ -66,6 +68,14 @@ export interface FlexTreeHydratedContextMinimal {
 	 * The checkout object associated with this context.
 	 */
 	readonly checkout: ITreeCheckout;
+
+	/**
+	 * Returns a new {@link FlexTreeField} that will live as long as the caller allows up to the next call to {@link clear} or disposal of the context.
+	 * @remarks
+	 * Due to limited support for detached fields, not all operations are supported.
+	 * Additionally if the detached field's content is deleted, the field will become out of schema if it is required: it must not be used after that point.
+	 */
+	detachedField?(key: DetachedField, schema: FieldKindIdentifier): FlexTreeField;
 }
 
 /**
@@ -152,6 +162,13 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 		return this.checkout.storedSchema;
 	}
 
+	public runInTransaction(fn: () => void): void {
+		debugAssert(() => !this.disposed || "Disposed");
+		this.checkout.transaction.start();
+		fn();
+		this.checkout.transaction.commit();
+	}
+
 	/**
 	 * Called before editing.
 	 * Clears all cursors so editing can proceed.

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -14,15 +14,14 @@ import {
 } from "../../core/index.js";
 import type {
 	FieldKinds,
-	SequenceFieldEditBuilder,
-	ValueFieldEditBuilder,
-	OptionalFieldEditBuilder,
+	SequenceFieldEditor,
+	RequiredFieldEditor,
+	OptionalFieldEditor,
 } from "../default-schema/index.js";
 import type {
 	MapTreeFieldViewGeneric,
 	MapTreeNodeViewGeneric,
 	MinimalFieldMap,
-	MinimalMapTreeNodeView,
 } from "../mapTreeCursor.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
 
@@ -309,7 +308,7 @@ export type FlexibleFieldContent = readonly FlexibleNodeContent[];
 /**
  * Tree for inserting as a node.
  */
-export type FlexibleNodeContent = MinimalMapTreeNodeView;
+export type FlexibleNodeContent = FlexTreeNode;
 
 /**
  * {@link FlexTreeField} that stores a sequence of children.
@@ -354,7 +353,7 @@ export interface FlexTreeSequenceField extends FlexTreeField {
 	/**
 	 * Get an editor for this sequence.
 	 */
-	readonly editor: SequenceFieldEditBuilder<FlexibleFieldContent>;
+	readonly editor: SequenceFieldEditor<FlexibleFieldContent, readonly FlexTreeNode[]>;
 }
 
 /**
@@ -366,7 +365,7 @@ export interface FlexTreeSequenceField extends FlexTreeField {
 export interface FlexTreeRequiredField extends FlexTreeField {
 	get content(): FlexTreeUnknownUnboxed;
 
-	readonly editor: ValueFieldEditBuilder<FlexibleNodeContent>;
+	readonly editor: RequiredFieldEditor<FlexibleNodeContent, FlexTreeNode>;
 }
 
 /**
@@ -385,7 +384,7 @@ export interface FlexTreeRequiredField extends FlexTreeField {
 export interface FlexTreeOptionalField extends FlexTreeField {
 	get content(): FlexTreeUnknownUnboxed | undefined;
 
-	readonly editor: OptionalFieldEditBuilder<FlexibleNodeContent>;
+	readonly editor: OptionalFieldEditor<FlexibleNodeContent, FlexTreeNode>;
 }
 
 // #endregion

package/src/feature-libraries/flex-tree/lazyField.ts

@@ -9,7 +9,6 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import {
 	type AnchorNode,
 	CursorLocationType,
-	type ExclusiveMapTree,
 	type FieldAnchor,
 	type FieldKey,
 	type FieldKindIdentifier,
@@ -26,18 +25,21 @@ import { disposeSymbol, getOrCreate } from "../../util/index.js";
 import {
 	FieldKinds,
 	MappedEditBuilder,
-	type IDefaultEditBuilder,
-	type OptionalFieldEditBuilder,
-	type SequenceFieldEditBuilder,
-	type ValueFieldEditBuilder,
+	type SequenceFieldEditor,
+	type RequiredFieldEditor,
+	type DataEditor,
+	type OptionalFieldEditor,
+	type DetachedRootLocation,
+	type DetachedRootsLocation,
 } from "../default-schema/index.js";
-import { cursorForMapTreeField } from "../mapTreeCursor.js";
+import { cursorForMapTreeField, type MinimalMapTreeNodeView } from "../mapTreeCursor.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
 
 import type { Context } from "./context.js";
 import {
 	FlexTreeEntityKind,
 	type FlexTreeField,
+	type FlexTreeNode,
 	type FlexTreeOptionalField,
 	type FlexTreeRequiredField,
 	type FlexTreeSequenceField,
@@ -51,7 +53,7 @@ import {
 	flexTreeSlot,
 } from "./flexTreeTypes.js";
 import { LazyEntity } from "./lazyEntity.js";
-import { type LazyTreeNode, getOrCreateHydratedFlexTreeNode } from "./lazyNode.js";
+import { LazyTreeNode, getOrCreateHydratedFlexTreeNode } from "./lazyNode.js";
 import { indexForAt, treeStatusFromAnchorCache } from "./utilities.js";
 import { combineChunks } from "../chunked-forest/index.js";
 
@@ -231,21 +233,29 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 	 */
 	public getFieldPathForEditing(): NormalizedFieldUpPath {
 		if (!this.isFreed()) {
-			if (
-				// Only allow editing if we are the root document field...
-				(this.parent === undefined && this.anchor.fieldKey === rootFieldKey) ||
-				// ...or are under a node in the document
-				(this.parent !== undefined &&
-					treeStatusFromAnchorCache(this.parent.anchorNode) === TreeStatus.InDocument)
-			) {
+			// Only allow editing if we are the root document field...
+			if (this.parent === undefined && this.anchor.fieldKey === rootFieldKey) {
 				return this.getFieldPath();
 			}
+			// ...or are under a node in the document
+			if (this.parent !== undefined) {
+				const status = treeStatusFromAnchorCache(this.parent.anchorNode);
+				if (status === TreeStatus.InDocument || status === TreeStatus.Removed) {
+					return this.getFieldPath();
+				}
+			}
 		}
 
-		throw new UsageError("Editing only allowed on fields with TreeStatus.InDocument status");
+		throw new UsageError(
+			"Editing only allowed on the root field or on fields under nodes with TreeStatus.InDocument or TreeStatus.Removed status",
+		);
 	}
 
-	protected getEditor(): IDefaultEditBuilder<ITreeCursorSynchronous> {
+	protected getEditor(): DataEditor<
+		ITreeCursorSynchronous,
+		DetachedRootLocation,
+		DetachedRootsLocation
+	> {
 		return new MappedEditBuilder(
 			this.context.checkout.editor,
 			(cursor: ITreeCursorSynchronous) =>
@@ -254,6 +264,11 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 	}
 }
 
+function fieldFromNode(node: FlexTreeNode): FieldKey {
+	assert(node instanceof LazyTreeNode, "Invalid tree type");
+	return node.anchorNode.parentField;
+}
+
 export class LazySequence extends LazyField implements FlexTreeSequenceField {
 	public at(index: number): FlexTreeUnknownUnboxed | undefined {
 		const finalIndex = indexForAt(index, this.length);
@@ -268,32 +283,48 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 		return this.map((x) => x);
 	}
 
-	public editor: SequenceFieldEditBuilder<FlexibleFieldContent> = {
+	public editor: SequenceFieldEditor<FlexibleFieldContent, readonly FlexTreeNode[]> = {
 		insert: (index, newContent) => {
 			this.sequenceEditor().insert(index, cursorForMapTreeField(newContent));
 		},
 		remove: (index, count) => {
 			this.sequenceEditor().remove(index, count);
 		},
+		attach: (index, content) => {
+			const contentLocations: DetachedRootsLocation = content.map((node) => ({
+				field: fieldFromNode(node),
+				count: 1,
+			}));
+			this.sequenceEditor().attach(index, contentLocations);
+		},
 	};
 
-	private sequenceEditor(): SequenceFieldEditBuilder<ITreeCursorSynchronous> {
+	private sequenceEditor(): SequenceFieldEditor<
+		ITreeCursorSynchronous,
+		DetachedRootsLocation
+	> {
 		const fieldPath = this.getFieldPathForEditing();
 		return this.getEditor().sequenceField(fieldPath);
 	}
 }
 
 export class LazyValueField extends LazyField implements FlexTreeRequiredField {
-	public editor: ValueFieldEditBuilder<FlexibleNodeContent> = {
+	public editor: RequiredFieldEditor<FlexibleNodeContent, FlexTreeNode> = {
 		set: (newContent) => {
 			this.valueFieldEditor().set(cursorForMapTreeField([newContent]));
 		},
+		attach: (content) => {
+			const root = fieldFromNode(content);
+			this.valueFieldEditor().attach(root);
+		},
 	};
 
-	private valueFieldEditor(): ValueFieldEditBuilder<ITreeCursorSynchronous> {
+	private valueFieldEditor(): RequiredFieldEditor<
+		ITreeCursorSynchronous,
+		DetachedRootLocation
+	> {
 		const fieldPath = this.getFieldPathForEditing();
-		const fieldEditor = this.getEditor().valueField(fieldPath);
-		return fieldEditor;
+		return this.getEditor().valueField(fieldPath);
 	}
 
 	public get content(): FlexTreeUnknownUnboxed {
@@ -302,16 +333,27 @@ export class LazyValueField extends LazyField implements FlexTreeRequiredField {
 }
 
 export class LazyOptionalField extends LazyField implements FlexTreeOptionalField {
-	public editor: OptionalFieldEditBuilder<ExclusiveMapTree> = {
+	public editor: OptionalFieldEditor<MinimalMapTreeNodeView, FlexTreeNode> = {
 		set: (newContent, wasEmpty) => {
 			this.optionalEditor().set(
-				newContent !== undefined ? cursorForMapTreeField([newContent]) : newContent,
+				newContent === undefined ? newContent : cursorForMapTreeField([newContent]),
 				wasEmpty,
 			);
 		},
+		attach: (content, wasEmpty) => {
+			if (content === undefined) {
+				this.optionalEditor().clear(wasEmpty);
+			} else {
+				const root = fieldFromNode(content);
+				this.optionalEditor().attach(root, wasEmpty);
+			}
+		},
+		clear: (wasEmpty) => {
+			this.optionalEditor().clear(wasEmpty);
+		},
 	};
 
-	private optionalEditor(): OptionalFieldEditBuilder<ITreeCursorSynchronous> {
+	private optionalEditor(): OptionalFieldEditor<ITreeCursorSynchronous, DetachedRootLocation> {
 		const fieldPath = this.getFieldPathForEditing();
 		const fieldEditor = this.getEditor().optionalField(fieldPath);
 		return fieldEditor;
@@ -359,16 +401,16 @@ export function unboxedFlexNode(
 	// This avoids O(depth) related costs from getOrCreateHydratedFlexTreeNode in the cached case.
 	const anchor = fieldAnchor.parent;
 	let child: AnchorNode | undefined;
-	if (anchor !== undefined) {
-		const anchorNode = context.checkout.forest.anchors.locate(anchor);
-		assert(anchorNode !== undefined, 0xa4c /* missing anchor */);
-		child = anchorNode.childIfAnchored(fieldAnchor.fieldKey, cursor.fieldIndex);
-	} else {
+	if (anchor === undefined) {
 		child = context.checkout.forest.anchors.find({
 			parent: undefined,
 			parentField: fieldAnchor.fieldKey,
 			parentIndex: cursor.fieldIndex,
 		});
+	} else {
+		const anchorNode = context.checkout.forest.anchors.locate(anchor);
+		assert(anchorNode !== undefined, 0xa4c /* missing anchor */);
+		child = anchorNode.childIfAnchored(fieldAnchor.fieldKey, cursor.fieldIndex);
 	}
 
 	if (child !== undefined) {