@fluidframework/tree 2.1.0 → 2.3.0-288113

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

@@ -5,28 +5,27 @@
 
 import {
 	type AnchorNode,
+	type ExclusiveMapTree,
 	type FieldKey,
 	type FieldUpPath,
-	type ITreeCursorSynchronous,
 	type TreeValue,
 	anchorSlot,
 } from "../../core/index.js";
-import type { Assume, FlattenKeys } from "../../util/index.js";
-import type { FieldKinds, SequenceFieldEditBuilder } from "../default-schema/index.js";
-import type { FlexFieldKind } from "../modular-schema/index.js";
+import type { Assume } from "../../util/index.js";
 import type {
-	AllowedTypesToFlexInsertableTree,
-	InsertableFlexField,
-} from "../schema-aware/index.js";
+	FieldKinds,
+	SequenceFieldEditBuilder,
+	ValueFieldEditBuilder,
+	OptionalFieldEditBuilder,
+} from "../default-schema/index.js";
+import type { FlexFieldKind } from "../modular-schema/index.js";
 import type {
 	Any,
 	FlexAllowedTypes,
-	FlexFieldNodeSchema,
 	FlexFieldSchema,
 	FlexList,
 	FlexListToUnion,
 	FlexMapNodeSchema,
-	FlexObjectNodeFields,
 	FlexObjectNodeSchema,
 	FlexTreeNodeSchema,
 	LazyItem,
@@ -43,7 +42,6 @@ export const flexTreeSlot = anchorSlot<FlexTreeNode>();
 
 /**
  * Indicates that an object is a flex tree.
- * @internal
  */
 export const flexTreeMarker = Symbol("flexTreeMarker");
 
@@ -56,7 +54,6 @@ export function isFlexTreeNode(t: unknown): t is FlexTreeNode {
 }
 
 /**
- * @internal
  */
 export enum FlexTreeEntityKind {
 	Node,
@@ -76,8 +73,6 @@ export enum FlexTreeEntityKind {
  * TODO:
  * Design and document iterator invalidation rules and ordering rules.
  * Providing a custom iterator type with place anchor semantics would be a good approach.
- *
- * @internal
  */
 export interface FlexTreeEntity<out TSchema = unknown> {
 	/**
@@ -94,8 +89,9 @@ export interface FlexTreeEntity<out TSchema = unknown> {
 
 	/**
 	 * A common context of a "forest" of FlexTrees.
+	 * @remarks This is `undefined` for unhydrated nodes or fields that have not yet been inserted into the tree.
 	 */
-	readonly context: FlexTreeContext;
+	readonly context?: FlexTreeContext;
 
 	/**
 	 * Iterate through all nodes/fields in this field/node.
@@ -147,8 +143,6 @@ export enum TreeStatus {
  * All content in the tree is accessible without down-casting, but if the schema is known,
  * the schema aware API may be more ergonomic.
  * All editing is actually done via {@link FlexTreeField}s: the nodes are immutable other than that they contain mutable fields.
- *
- * @internal
  */
 export interface FlexTreeNode extends FlexTreeEntity<FlexTreeNodeSchema> {
 	readonly [flexTreeMarker]: FlexTreeEntityKind.Node;
@@ -214,8 +208,6 @@ export interface FlexTreeNode extends FlexTreeEntity<FlexTreeNodeSchema> {
  * Down-casting (via {@link FlexTreeField.is}) is required to access Schema-Aware APIs, including editing.
  * All content in the tree is accessible without down-casting, but if the schema is known,
  * the schema aware API may be more ergonomic.
- *
- * @internal
  */
 export interface FlexTreeField extends FlexTreeEntity<FlexFieldSchema> {
 	readonly [flexTreeMarker]: FlexTreeEntityKind.Field;
@@ -269,36 +261,11 @@ export interface FlexTreeField extends FlexTreeEntity<FlexFieldSchema> {
  * and that sequence can be used to insert new items into the field.
  * Additionally empty fields (those containing no nodes) are not distinguished from fields which do not exist.
  * This differs from JavaScript Maps which have a subtle distinction between storing undefined as a value in the map and deleting an entry from the map.
- *
- * @internal
  */
 export interface FlexTreeMapNode<in out TSchema extends FlexMapNodeSchema>
 	extends FlexTreeNode {
 	readonly schema: TSchema;
 
-	/**
-	 * The number of elements in the map.
-	 *
-	 * @remarks
-	 * All fields under a map implicitly exist, but `size` will count only the fields which contain one or more nodes.
-	 */
-	readonly size: number;
-
-	/**
-	 * Checks whether a value exists for the given key.
-	 * @param key - Which map entry to look up.
-	 *
-	 * @remarks
-	 * All fields under a map implicitly exist, but `has` will only return true if there are one or more nodes present in the given field.
-	 */
-	has(key: string): boolean;
-
-	/**
-	 * Get the value associated with `key`.
-	 * @param key - which map entry to look up.
-	 */
-	get(key: string): FlexTreeUnboxField<TSchema["info"]>;
-
 	/**
 	 * Get the field for `key`.
 	 * @param key - which map entry to look up.
@@ -341,107 +308,11 @@ export interface FlexTreeMapNode<in out TSchema extends FlexMapNodeSchema>
 	 */
 	entries(): IterableIterator<[FieldKey, FlexTreeUnboxField<TSchema["info"], "notEmpty">]>;
 
-	/**
-	 * Executes a provided function once per each key/value pair in the map.
-	 * @param callbackFn - The function to run for each map entry
-	 * @param thisArg - If present, `callbackFn` will be bound to `thisArg`
-	 *
-	 * @privateRemarks
-	 * TODO: This should run over fields in insertion order if we want to match the javascript foreach spec.
-	 */
-	forEach(
-		callbackFn: (
-			value: FlexTreeUnboxField<TSchema["info"], "notEmpty">,
-			key: FieldKey,
-			map: FlexTreeMapNode<TSchema>,
-		) => void,
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		thisArg?: any,
-	): void;
-
-	/**
-	 * Adds or updates an entry in the map with a specified `key` and a `value`.
-	 *
-	 * @param key - The key of the element to add to the map.
-	 * @param value - The value of the element to add to the map.
-	 */
-	set(key: string, value: FlexibleFieldContent<TSchema["info"]>): void;
-
-	/**
-	 * Removes the specified element from this map by its `key`.
-	 *
-	 * @remarks
-	 * Note: unlike JavaScript's Map API, this method does not return a flag indicating whether or not the value was
-	 * deleted.
-	 *
-	 * @privateRemarks
-	 * Regarding the choice to not return a boolean: Since this data structure is distributed in nature, it isn't
-	 * possible to tell whether or not the item was deleted as a result of this method call. Returning a "best guess"
-	 * is more likely to create issues / promote bad usage patterns than offer useful information.
-	 *
-	 * @param key - The key of the element to remove from the map.
-	 */
-	delete(key: string): void;
-
-	/**
-	 * Iterate through all fields in the map.
-	 *
-	 * @remarks
-	 * No mutations to the current view of the shared tree are permitted during iteration.
-	 * To iterate over the unboxed values of the map, use `Symbol.Iterator()`.
-	 */
-	boxedIterator(): IterableIterator<FlexTreeTypedField<TSchema["info"]>>;
-
 	[Symbol.iterator](): IterableIterator<
 		[FieldKey, FlexTreeUnboxField<TSchema["info"], "notEmpty">]
 	>;
 }
 
-/**
- * A {@link FlexTreeNode} that wraps a single {@link FlexTreeField} (which is placed under the {@link EmptyKey}).
- *
- * @remarks
- * A FieldNode is mostly identical to a struct node with a single field using the {@link EmptyKey}, but provides access to it via a field named "content".
- *
- * There are several use-cases where it makes sense to use a field node.
- * Here are a few:
- * - When it's necessary to differentiate between an empty sequence, and no sequence.
- * One case where this is needed is encoding Json.
- * - When polymorphism over {@link FlexFieldSchema} (and not just a union of {@link FlexAllowedTypes}) is required.
- * For example when encoding a schema for a type like
- * `Foo[] | Bar[]`, `Foo | Foo[]` or `Optional<Foo> | Optional<Bar>` (Where `Optional` is the Optional field kind, not TypeScript's `Optional`).
- * Since this schema system only allows `|` of {@link FlexTreeNodeSchema} (and only when declaring a {@link FlexFieldSchema}), see {@link SchemaBuilderBase.field},
- * these aggregate types are most simply expressed by creating fieldNodes for the terms like `Foo[]`, and `Optional<Foo>`.
- * Note that these are distinct from types like `(Foo | Bar)[]` and `Optional<Foo | Bar>` which can be expressed as single fields without extra nodes.
- * - When a distinct merge identity is desired for a field.
- * For example, if the application wants to be able to have an optional node or a sequence which it can pass around, edit and observe changes to,
- * in some cases (like when the content is moved to a different parent) this can be more flexible if a field node is introduced
- * to create a separate logical entity (node) which wraps the field.
- * This can even be useful with value fields to wrap terminal nodes if a stable merge
- * - When a field (such as a {@link FlexTreeSequenceField}) is desired in a location where {@link FlexTreeNode}s are required
- * (like the member of a union or the child of another {@link FlexTreeField}).
- * This can is typically just a different perspective on one of the above cases.
- * For example:
- * `Sequence<Foo> | Sequence<Bar>` or `OptionalField<Sequence<Foo>>` can't be expressed as simple fields
- * (unlike `Sequence<Foo | Bar>` or `OptionalField<Foo>` which can be done as simple fields).
- * Instead {@link FlexTreeFieldNode}s can be use to achieve something similar, more like:
- * `FieldNode<Sequence<Foo>> | FieldNode<Sequence<Bar>>` or `OptionalField<FieldNode<Sequence<Foo>>>`.
- *
- * @privateRemarks
- * FieldNodes do not unbox to their content, so in schema aware APIs which do unboxing, the FieldNode will NOT be skipped over.
- * This is a change from the old behavior to simplify unboxing and prevent cases where arbitrary deep chains of field nodes could unbox omitting information about the tree depth.
- * @internal
- */
-export interface FlexTreeFieldNode<in out TSchema extends FlexFieldNodeSchema>
-	extends FlexTreeNode {
-	readonly schema: TSchema;
-
-	/**
-	 * The content this field node wraps.
-	 */
-	readonly content: FlexTreeUnboxField<TSchema["info"]>;
-}
-
 /**
  * A {@link FlexTreeNode} that behaves like an "object" or "struct", providing properties to access its fields.
  *
@@ -449,7 +320,6 @@ export interface FlexTreeFieldNode<in out TSchema extends FlexFieldNodeSchema>
  *
  * @remarks
  * ObjectNodes require complex typing, and have been split into two parts for implementation purposes.
- * See {@link FlexTreeObjectNodeTyped} for the schema aware extensions to this that provide access to the fields.
  *
  * These "Objects" resemble "Structs" from a wide variety of programming languages
  * (Including Algol 68, C, Go, Rust, C# etc.).
@@ -460,8 +330,6 @@ export interface FlexTreeFieldNode<in out TSchema extends FlexFieldNodeSchema>
  * The name "Record" is avoided (in favor of Object) here because it has less precise connotations for most TypeScript developers.
  * For example, TypeScript has a built in `Record` type, but it requires all of the fields to have the same type,
  * putting its semantics half way between this library's "Object" schema and {@link FlexTreeMapNode}.
- *
- * @internal
  */
 export interface FlexTreeObjectNode extends FlexTreeNode {
 	readonly schema: FlexObjectNodeSchema;
@@ -473,7 +341,6 @@ export interface FlexTreeObjectNode extends FlexTreeNode {
  * @remarks
  * Leaves are immutable and have no children.
  * Leaf unboxes its content, so in schema aware APIs which do unboxing, the Leaf itself will be skipped over and its value will be returned directly.
- * @internal
  */
 export interface FlexTreeLeafNode<in out TSchema extends LeafNodeSchema> extends FlexTreeNode {
 	readonly schema: TSchema;
@@ -484,153 +351,8 @@ export interface FlexTreeLeafNode<in out TSchema extends LeafNodeSchema> extends
 	readonly value: TreeValue<TSchema["info"]>;
 }
 
-/**
- * An {@link FlexTreeObjectNode} with schema aware accessors for its fields.
- *
- * @privateRemarks
- *
- * The corresponding implementation logic for this lives in `LazyTree.ts` under `buildStructClass`.
- * If you change the signature here, you will need to update that logic to match.
- *
- * @internal
- */
-export type FlexTreeObjectNodeTyped<TSchema extends FlexObjectNodeSchema> =
-	FlexObjectNodeSchema extends TSchema
-		? FlexTreeObjectNode
-		: FlexTreeObjectNode & FlexTreeObjectNodeFields<TSchema["info"]>;
-
-/**
- * Properties to access an object node's fields. See {@link FlexTreeObjectNodeTyped}.
- *
- * @privateRemarks
- * TODO: Support custom field keys.
- * @internal
- */
-export type FlexTreeObjectNodeFields<TFields extends FlexObjectNodeFields> =
-	FlexTreeObjectNodeFieldsInner<
-		FlattenKeys<
-			{
-				// When the key does not need to be escaped, map it from the input TFields in a way that doesn't break navigate to declaration
-				[key in keyof TFields as key extends PropertyNameFromFieldKey<key & string>
-					? key
-					: never]: TFields[key];
-			} & {
-				[key in keyof TFields as key extends PropertyNameFromFieldKey<key & string>
-					? never
-					: PropertyNameFromFieldKey<key & string>]: TFields[key];
-			}
-		>
-	>;
-
-/**
- * Properties to access an object node's fields. See {@link FlexTreeObjectNodeTyped}.
- *
- * @privateRemarks
- * TODO: Do we keep assignment operator + "setFoo" methods, or just use methods?
- * Inconsistency in the API experience could confusing for consumers.
- *
- * @internal
- */
-export type FlexTreeObjectNodeFieldsInner<TFields extends FlexObjectNodeFields> = FlattenKeys<
-	{
-		// boxed fields (TODO: maybe remove these when same as non-boxed version?)
-		readonly [key in keyof TFields as `boxed${Capitalize<key & string>}`]: FlexTreeTypedField<
-			TFields[key]
-		>;
-	} & {
-		// Add getter only (make property readonly) when the field is **not** of a kind that has a logical set operation.
-		// If we could map to getters and setters separately, we would preferably do that, but we can't.
-		// See https://github.com/microsoft/TypeScript/issues/43826 for more details on this limitation.
-		readonly [key in keyof TFields as TFields[key]["kind"] extends AssignableFieldKinds
-			? never
-			: key]: FlexTreeUnboxField<TFields[key]>;
-	} & {
-		// Add setter (make property writable) when the field is of a kind that has a logical set operation.
-		// If we could map to getters and setters separately, we would preferably do that, but we can't.
-		// See https://github.com/microsoft/TypeScript/issues/43826 for more details on this limitation.
-		-readonly [key in keyof TFields as TFields[key]["kind"] extends AssignableFieldKinds
-			? key
-			: never]: FlexTreeUnboxField<TFields[key]>;
-	} & {
-		// Setter method (when the field is of a kind that has a logical set operation).
-		readonly [key in keyof TFields as TFields[key]["kind"] extends AssignableFieldKinds
-			? `set${Capitalize<key & string>}`
-			: never]: (content: FlexibleFieldContent<TFields[key]>) => void;
-	}
->;
-
-/**
- * Reserved object node field property names to avoid collisions with the rest of the object node API.
- * @internal
- */
-export const reservedObjectNodeFieldPropertyNames = [
-	"anchorNode",
-	"constructor",
-	"context",
-	"is",
-	"parentField",
-	"schema",
-	"tryGetField",
-	"type",
-	"value",
-	"boxedIterator",
-	"iterator",
-	"getBoxed",
-] as const;
-
-/**
- * Reserved object node field property names prefixes.
- * These are reserved to avoid collisions with properties derived from field other field names.
- *
- * Field names starting with these must be followed by a lowercase letter, or be escaped.
- * @internal
- */
-export const reservedObjectNodeFieldPropertyNamePrefixes = [
-	"set",
-	"boxed",
-	"field",
-	"Field",
-] as const;
-
-/**
- * {@link reservedObjectNodeFieldPropertyNamePrefixes} as a type union.
- * @internal
- */
-export type ReservedObjectNodeFieldPropertyNames =
-	(typeof reservedObjectNodeFieldPropertyNames)[number];
-
-/**
- * {@link reservedObjectNodeFieldPropertyNamePrefixes} as a type union.
- * @internal
- */
-export type ReservedObjectNodeFieldPropertyNamePrefixes =
-	(typeof reservedObjectNodeFieldPropertyNamePrefixes)[number];
-
-/**
- * Convert an object node's field key into an escaped string usable as a property name.
- *
- * @privateRemarks
- * TODO:
- * Collisions are still possible.
- * For example fields named "foo" and "Foo" would both produce a setter "setFoo".
- * Consider naming schemes to avoid this, ensure that there is a good workaround for these cases.
- * Another approach would be to support custom field names (separate from keys),
- * and do the escaping (if needed) when creating the flex tree schema (both when manually creating them and when doing so automatically):
- * this would enable better intellisense for escaped fields, as well as allow the feature of custom field property names.
- *
- * @internal
- */
-export type PropertyNameFromFieldKey<T extends string> =
-	T extends ReservedObjectNodeFieldPropertyNames
-		? `field${Capitalize<T>}`
-		: T extends `${ReservedObjectNodeFieldPropertyNamePrefixes}${Capitalize<string>}`
-			? `field${Capitalize<T>}`
-			: T;
-
 /**
  * Field kinds that allow value assignment.
- *
- * @internal
  */
 export type AssignableFieldKinds = typeof FieldKinds.optional | typeof FieldKinds.required;
 
@@ -639,36 +361,21 @@ export type AssignableFieldKinds = typeof FieldKinds.optional | typeof FieldKind
 // #region Field Kinds
 
 /**
- * Strongly typed tree literals for inserting as the content of a field.
- *
- * If a cursor is provided, it must be in Fields mode.
- * @internal
+ * Typed tree for inserting as the content of a field.
  */
-export type FlexibleFieldContent<TSchema extends FlexFieldSchema> =
-	| InsertableFlexField<TSchema>
-	| ITreeCursorSynchronous;
+export type FlexibleFieldContent = ExclusiveMapTree[];
 
 /**
- * Strongly typed tree literals for inserting as a node.
- *
- * If a cursor is provided, it must be in Nodes mode.
- * @internal
+ * Tree for inserting as a node.
  */
-export type FlexibleNodeContent<TTypes extends FlexAllowedTypes> =
-	| AllowedTypesToFlexInsertableTree<TTypes>
-	| ITreeCursorSynchronous;
+export type FlexibleNodeContent = ExclusiveMapTree;
 
 /**
- * Strongly typed tree literals for inserting a subsequence of nodes.
+ * Tree for inserting a subsequence of nodes.
  *
  * Used to insert a batch of 0 or more nodes into some location in a {@link FlexTreeSequenceField}.
- *
- * If a cursor is provided, it must be in Fields mode.
- * @internal
  */
-export type FlexibleNodeSubSequence<TTypes extends FlexAllowedTypes> =
-	| Iterable<AllowedTypesToFlexInsertableTree<TTypes>>
-	| ITreeCursorSynchronous;
+export type FlexibleNodeSubSequence = ExclusiveMapTree[];
 
 /**
  * Type to ensures two types overlap in at least one way.
@@ -676,7 +383,6 @@ export type FlexibleNodeSubSequence<TTypes extends FlexAllowedTypes> =
  * Examples:
  * CheckTypesOverlap\<number | boolean, number | object\> = number | boolean
  * CheckTypesOverlap\<number | boolean, string | object\> = never
- * @internal
  */
 export type CheckTypesOverlap<T, TCheck> = [Extract<T, TCheck> extends never ? never : T][0];
 
@@ -695,7 +401,6 @@ export type CheckTypesOverlap<T, TCheck> = [Extract<T, TCheck> extends never ? n
  * TODO:
  * Add anchor API that can actually hold onto locations in a sequence.
  * Currently only nodes can be held onto with anchors, and this does not replicate the behavior implemented for editing.
- * @internal
  */
 export interface FlexTreeSequenceField<in out TTypes extends FlexAllowedTypes>
 	extends FlexTreeField {
@@ -722,200 +427,12 @@ export interface FlexTreeSequenceField<in out TTypes extends FlexAllowedTypes>
 	 */
 	map<U>(callbackfn: (value: FlexTreeUnboxNodeUnion<TTypes>, index: number) => U): U[];
 
-	/**
-	 * Calls the provided callback function on each child of this sequence, and returns an array that contains the results.
-	 * @param callbackfn - A function that accepts the child and its index.
-	 */
-	mapBoxed<U>(callbackfn: (value: FlexTreeTypedNodeUnion<TTypes>, index: number) => U): U[];
-
 	readonly length: number;
 
 	/**
 	 * Get an editor for this sequence.
 	 */
-	sequenceEditor(): SequenceFieldEditBuilder;
-
-	/*
-	 * TODO:
-	 * Remove these editing methods and replace their use with use of `sequenceEditor`.
-	 * These editing methods replicate the API exposed by simple-tree, but using flex-tree types.
-	 * As these methods just re-abstract the lower level SequenceFieldEditBuilder API, they add little value.
-	 * Migrating the logic implementing them to simple-tree (and having it just use `sequenceEditor` directly)
-	 * avoids duplicating the API surface (and documentation), as well as makes it simpler to implement the desired user facing validation and errors
-	 * since simple-tree becomes responsible for all the validation and can produce usage errors in terms of the public package API.
-	 */
-	// #region Editing Methods
-
-	/**
-	 * Inserts new item(s) at a specified location.
-	 * @param index - The index at which to insert `value`.
-	 * @param value - The content to insert.
-	 * @throws Throws if `index` is not in the range [0, `list.length`).
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	insertAt(index: number, value: FlexibleNodeSubSequence<TTypes>): void;
-
-	/**
-	 * Inserts new item(s) at the start of the sequence.
-	 * @param value - The content to insert.
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	insertAtStart(value: FlexibleNodeSubSequence<TTypes>): void;
-
-	/**
-	 * Inserts new item(s) at the end of the sequence.
-	 * @param value - The content to insert.
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	insertAtEnd(value: FlexibleNodeSubSequence<TTypes>): void;
-
-	/**
-	 * Removes the item at the specified location.
-	 * @param index - The index at which to remove the item.
-	 * @throws Throws if `index` is not in the range [0, `list.length`).
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	removeAt(index: number): void;
-
-	/**
-	 * Moves the specified item to the start of the sequence.
-	 * @param sourceIndex - The index of the item to move.
-	 * @throws Throws if `sourceIndex` is not in the range [0, `list.length`).
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveToStart(sourceIndex: number): void;
-
-	/**
-	 * Moves the specified item to the start of the sequence.
-	 * @param sourceIndex - The index of the item to move.
-	 * @param source - The source sequence to move the item out of.
-	 * @throws Throws if `sourceIndex` is not in the range [0, `list.length`).
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveToStart(sourceIndex: number, source: FlexTreeSequenceField<FlexAllowedTypes>): void;
-
-	/**
-	 * Moves the specified item to the end of the sequence.
-	 * @param sourceIndex - The index of the item to move.
-	 * @throws Throws if `sourceIndex` is not in the range [0, `list.length`).
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveToEnd(sourceIndex: number): void;
-
-	/**
-	 * Moves the specified item to the end of the sequence.
-	 * @param sourceIndex - The index of the item to move.
-	 * @param source - The source sequence to move the item out of.
-	 * @throws Throws if `sourceIndex` is not in the range [0, `list.length`).
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveToEnd(sourceIndex: number, source: FlexTreeSequenceField<FlexAllowedTypes>): void;
-
-	/**
-	 * Moves the specified item to the desired location in the sequence.
-	 * @param index - The index to move the item to.
-	 * This is based on the state of the sequence before moving the source item.
-	 * @param sourceIndex - The index of the item to move.
-	 * @throws Throws if any of the input indices are not in the range [0, `list.length`).
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveToIndex(index: number, sourceIndex: number): void;
-
-	/**
-	 * Moves the specified item to the desired location in the sequence.
-	 * @param index - The index to move the item to.
-	 * @param sourceIndex - The index of the item to move.
-	 * @param source - The source sequence to move the item out of.
-	 * @throws Throws if any of the input indices are not in the range [0, `list.length`).
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveToIndex(
-		index: number,
-		sourceIndex: number,
-		source: FlexTreeSequenceField<FlexAllowedTypes>,
-	): void;
-
-	/**
-	 * Moves the specified items to the start of the sequence.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @throws Throws if either of the input indices are not in the range [0, `list.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveRangeToStart(sourceStart: number, sourceEnd: number): void;
-
-	/**
-	 * Moves the specified items to the start of the sequence.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @param source - The source sequence to move items out of.
-	 * @throws Throws if the types of any of the items being moved are not allowed in the destination sequence,
-	 * if either of the input indices are not in the range [0, `list.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveRangeToStart(
-		sourceStart: number,
-		sourceEnd: number,
-		source: FlexTreeSequenceField<FlexAllowedTypes>,
-	): void;
-
-	/**
-	 * Moves the specified items to the end of the sequence.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @throws Throws if either of the input indices are not in the range [0, `list.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveRangeToEnd(sourceStart: number, sourceEnd: number): void;
-
-	/**
-	 * Moves the specified items to the end of the sequence.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @param source - The source sequence to move items out of.
-	 * @throws Throws if the types of any of the items being moved are not allowed in the destination sequence,
-	 * if either of the input indices are not in the range [0, `list.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveRangeToEnd(
-		sourceStart: number,
-		sourceEnd: number,
-		source: FlexTreeSequenceField<FlexAllowedTypes>,
-	): void;
-
-	/**
-	 * Moves the specified items to the desired location within the sequence.
-	 * @param index - The index to move the items to.
-	 * This is based on the state of the sequence before moving the source items.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @throws Throws if any of the input indices are not in the range [0, `list.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveRangeToIndex(index: number, sourceStart: number, sourceEnd: number): void;
-
-	/**
-	 * Moves the specified items to the desired location within the sequence.
-	 * @param index - The index to move the items to.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @param source - The source sequence to move items out of.
-	 * @throws Throws if the types of any of the items being moved are not allowed in the destination sequence,
-	 * if any of the input indices are not in the range [0, `list.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 * @deprecated Migrate to using simple-tree layer editing APIs, or directly use the field editors.
-	 */
-	moveRangeToIndex(
-		index: number,
-		sourceStart: number,
-		sourceEnd: number,
-		// FlexTreeSequenceField is invariant over its schema so any is required here.
-		// This use of any can be removed by migrating off this deprecated API and deleting it.
-		// If kept, this function should be fixed by making it generic and constraining it to fields which are safe to move content from.
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		source: FlexTreeSequenceField<any>,
-	): void;
-
-	// #endregion
+	readonly editor: SequenceFieldEditBuilder<FlexibleFieldContent>;
 
 	boxedIterator(): IterableIterator<FlexTreeTypedNodeUnion<TTypes>>;
 
@@ -932,12 +449,12 @@ export interface FlexTreeSequenceField<in out TTypes extends FlexAllowedTypes>
  *
  * @remarks
  * Unboxes its content, so in schema aware APIs which do unboxing, the RequiredField itself will be skipped over and its content will be returned directly.
- * @internal
  */
 export interface FlexTreeRequiredField<in out TTypes extends FlexAllowedTypes>
 	extends FlexTreeField {
 	get content(): FlexTreeUnboxNodeUnion<TTypes>;
-	set content(content: FlexibleNodeContent<TTypes>);
+
+	readonly editor: ValueFieldEditBuilder<FlexibleNodeContent>;
 }
 
 /**
@@ -952,12 +469,12 @@ export interface FlexTreeRequiredField<in out TTypes extends FlexAllowedTypes>
  * TODO:
  * Better centralize the documentation about what kinds of merge semantics are available for field kinds.
  * Maybe link editor?
- * @internal
  */
 export interface FlexTreeOptionalField<in out TTypes extends FlexAllowedTypes>
 	extends FlexTreeField {
 	get content(): FlexTreeUnboxNodeUnion<TTypes> | undefined;
-	set content(newContent: FlexibleNodeContent<TTypes> | undefined);
+
+	readonly editor: OptionalFieldEditBuilder<FlexibleNodeContent>;
 }
 
 // #endregion
@@ -966,7 +483,6 @@ export interface FlexTreeOptionalField<in out TTypes extends FlexAllowedTypes>
 
 /**
  * Schema aware specialization of {@link FlexTreeField}.
- * @internal
  */
 export type FlexTreeTypedField<TSchema extends FlexFieldSchema> = FlexTreeTypedFieldInner<
 	TSchema["kind"],
@@ -975,7 +491,6 @@ export type FlexTreeTypedField<TSchema extends FlexFieldSchema> = FlexTreeTypedF
 
 /**
  * Helper for implementing {@link FlexTreeTypedField}.
- * @internal
  */
 export type FlexTreeTypedFieldInner<
 	Kind extends FlexFieldKind,
@@ -990,7 +505,6 @@ export type FlexTreeTypedFieldInner<
 
 /**
  * Schema aware specialization of {@link FlexTreeNode} for a given {@link FlexAllowedTypes}.
- * @internal
  */
 export type FlexTreeTypedNodeUnion<T extends FlexAllowedTypes> =
 	T extends FlexList<FlexTreeNodeSchema>
@@ -999,18 +513,15 @@ export type FlexTreeTypedNodeUnion<T extends FlexAllowedTypes> =
 
 /**
  * Schema aware specialization of {@link FlexTreeNode} for a given {@link FlexTreeNodeSchema}.
- * @internal
  */
 export type FlexTreeTypedNode<TSchema extends FlexTreeNodeSchema> =
 	TSchema extends LeafNodeSchema
 		? FlexTreeLeafNode<TSchema>
 		: TSchema extends FlexMapNodeSchema
 			? FlexTreeMapNode<TSchema>
-			: TSchema extends FlexFieldNodeSchema
-				? FlexTreeFieldNode<TSchema>
-				: TSchema extends FlexObjectNodeSchema
-					? FlexTreeObjectNodeTyped<TSchema>
-					: FlexTreeNode;
+			: TSchema extends FlexObjectNodeSchema
+				? FlexTreeObjectNode
+				: FlexTreeNode;
 
 // #endregion
 
@@ -1021,7 +532,6 @@ export type FlexTreeTypedNode<TSchema extends FlexTreeNodeSchema> =
  * @remarks
  * Unboxes fields to their content if appropriate for the kind.
  * Recursively unboxes that content (then its content etc.) as well if the node union does unboxing.
- * @internal
  */
 export type FlexTreeUnboxField<
 	TSchema extends FlexFieldSchema,
@@ -1031,7 +541,6 @@ export type FlexTreeUnboxField<
 
 /**
  * Helper for implementing FlexTreeUnboxField.
- * @internal
  */
 export type FlexTreeUnboxFieldInner<
 	Kind extends FlexFieldKind,
@@ -1051,7 +560,6 @@ export type FlexTreeUnboxFieldInner<
  * @remarks
  * Unboxes when not polymorphic.
  * Recursively unboxes that content as well if the node kind does unboxing.
- * @internal
  */
 export type FlexTreeUnboxNodeUnion<TTypes extends FlexAllowedTypes> = TTypes extends readonly [
 	LazyItem<infer InnerType>,
@@ -1070,7 +578,6 @@ export type FlexTreeUnboxNodeUnion<TTypes extends FlexAllowedTypes> = TTypes ext
  * `true` if T is known to be an array of one item.
  * `false` if T is known not to be an array of one item.
  * `boolean` if it is unknown if T is an array of one item or not.
- * @internal
  */
 export type IsArrayOfOne<T extends readonly unknown[]> = T["length"] extends 1
 	? true
@@ -1083,22 +590,18 @@ export type IsArrayOfOne<T extends readonly unknown[]> = T["length"] extends 1
  * @remarks
  * Unboxes if the node kind does unboxing.
  * Recursively unboxes that content as well if it does unboxing.
- * @internal
  */
 export type FlexTreeUnboxNode<TSchema extends FlexTreeNodeSchema> =
 	TSchema extends LeafNodeSchema
 		? TreeValue<TSchema["info"]>
 		: TSchema extends FlexMapNodeSchema
 			? FlexTreeMapNode<TSchema>
-			: TSchema extends FlexFieldNodeSchema
-				? FlexTreeFieldNode<TSchema>
-				: TSchema extends FlexObjectNodeSchema
-					? FlexTreeObjectNodeTyped<TSchema>
-					: FlexTreeUnknownUnboxed;
+			: TSchema extends FlexObjectNodeSchema
+				? FlexTreeObjectNode
+				: FlexTreeUnknownUnboxed;
 
 /**
  * Unboxed tree type for unknown schema cases.
- * @internal
  */
 export type FlexTreeUnknownUnboxed = TreeValue | FlexTreeNode;