@fluidframework/tree 2.1.0-281041 → 2.2.0

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

@@ -5,23 +5,23 @@
 
 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 {
-	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,
@@ -34,7 +34,6 @@ import type {
 } from "../typed-schema/index.js";
 
 import type { FlexTreeContext } from "./context.js";
-import type { FlexTreeNodeEvents } from "./treeEvents.js";
 
 /**
  * An anchor slot which records the {@link FlexTreeNode} associated with that anchor, if there is one.
@@ -44,7 +43,6 @@ export const flexTreeSlot = anchorSlot<FlexTreeNode>();
 
 /**
  * Indicates that an object is a flex tree.
- * @internal
  */
 export const flexTreeMarker = Symbol("flexTreeMarker");
 
@@ -57,7 +55,6 @@ export function isFlexTreeNode(t: unknown): t is FlexTreeNode {
 }
 
 /**
- * @internal
  */
 export enum FlexTreeEntityKind {
 	Node,
@@ -77,8 +74,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> {
 	/**
@@ -95,16 +90,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;
-
-	/**
-	 * Gets the {@link TreeStatus} of this tree.
-	 *
-	 * @remarks
-	 * For non-root fields, this is the status of the parent node, since fields do not have a separate lifetime.
-	 */
-	treeStatus(): TreeStatus;
+	readonly context?: FlexTreeContext;
 
 	/**
 	 * Iterate through all nodes/fields in this field/node.
@@ -156,8 +144,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;
@@ -167,14 +153,6 @@ export interface FlexTreeNode extends FlexTreeEntity<FlexTreeNodeSchema> {
 	 */
 	readonly value?: TreeValue;
 
-	/**
-	 * {@inheritDoc ISubscribable#on}
-	 */
-	on<K extends keyof FlexTreeNodeEvents>(
-		eventName: K,
-		listener: FlexTreeNodeEvents[K],
-	): () => void;
-
 	/**
 	 * Gets a field of this node, if it is not empty.
 	 */
@@ -231,8 +209,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;
@@ -286,36 +262,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.
@@ -376,30 +327,6 @@ export interface FlexTreeMapNode<in out TSchema extends FlexMapNodeSchema>
 		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.
 	 *
@@ -414,51 +341,6 @@ export interface FlexTreeMapNode<in out TSchema extends FlexMapNodeSchema>
 	>;
 }
 
-/**
- * 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.
  *
@@ -477,8 +359,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;
@@ -490,7 +370,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;
@@ -508,8 +387,6 @@ export interface FlexTreeLeafNode<in out TSchema extends LeafNodeSchema> extends
  *
  * 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
@@ -521,7 +398,6 @@ export type FlexTreeObjectNodeTyped<TSchema extends FlexObjectNodeSchema> =
  *
  * @privateRemarks
  * TODO: Support custom field keys.
- * @internal
  */
 export type FlexTreeObjectNodeFields<TFields extends FlexObjectNodeFields> =
 	FlexTreeObjectNodeFieldsInner<
@@ -545,8 +421,6 @@ export type FlexTreeObjectNodeFields<TFields extends FlexObjectNodeFields> =
  * @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<
 	{
@@ -572,23 +446,20 @@ export type FlexTreeObjectNodeFieldsInner<TFields extends FlexObjectNodeFields>
 		// 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;
+			: never]: (content: FlexibleNodeContent) => 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",
-	"on",
 	"parentField",
 	"schema",
-	"treeStatus",
 	"tryGetField",
 	"type",
 	"value",
@@ -602,7 +473,6 @@ export const reservedObjectNodeFieldPropertyNames = [
  * 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",
@@ -613,14 +483,12 @@ export const reservedObjectNodeFieldPropertyNamePrefixes = [
 
 /**
  * {@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];
@@ -636,8 +504,6 @@ export type ReservedObjectNodeFieldPropertyNamePrefixes =
  * 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
@@ -648,8 +514,6 @@ export type PropertyNameFromFieldKey<T extends string> =
 
 /**
  * Field kinds that allow value assignment.
- *
- * @internal
  */
 export type AssignableFieldKinds = typeof FieldKinds.optional | typeof FieldKinds.required;
 
@@ -658,36 +522,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.
@@ -695,7 +544,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];
 
@@ -714,7 +562,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 {
@@ -752,189 +599,7 @@ export interface FlexTreeSequenceField<in out TTypes extends FlexAllowedTypes>
 	/**
 	 * 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>>;
 
@@ -951,12 +616,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>;
 }
 
 /**
@@ -971,12 +636,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
@@ -985,7 +650,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"],
@@ -994,7 +658,6 @@ export type FlexTreeTypedField<TSchema extends FlexFieldSchema> = FlexTreeTypedF
 
 /**
  * Helper for implementing {@link FlexTreeTypedField}.
- * @internal
  */
 export type FlexTreeTypedFieldInner<
 	Kind extends FlexFieldKind,
@@ -1009,7 +672,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>
@@ -1018,18 +680,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
+				? FlexTreeObjectNodeTyped<TSchema>
+				: FlexTreeNode;
 
 // #endregion
 
@@ -1040,7 +699,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,
@@ -1050,7 +708,6 @@ export type FlexTreeUnboxField<
 
 /**
  * Helper for implementing FlexTreeUnboxField.
- * @internal
  */
 export type FlexTreeUnboxFieldInner<
 	Kind extends FlexFieldKind,
@@ -1070,7 +727,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>,
@@ -1089,7 +745,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
@@ -1102,22 +757,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
+				? FlexTreeObjectNodeTyped<TSchema>
+				: FlexTreeUnknownUnboxed;
 
 /**
  * Unboxed tree type for unknown schema cases.
- * @internal
  */
 export type FlexTreeUnknownUnboxed = TreeValue | FlexTreeNode;