@fluidframework/tree 2.81.0-374083 → 2.81.1

package/src/feature-libraries/sequence-field/sequenceFieldCodecV3.ts

@@ -7,7 +7,6 @@ import type { TAnySchema } from "@sinclair/typebox";
 
 import { DiscriminatedUnionDispatcher, type IJsonCodec } from "../../codec/index.js";
 import type {
-	ChangeAtomId,
 	ChangeEncodingContext,
 	EncodedRevisionTag,
 	RevisionTag,
@@ -19,14 +18,9 @@ import {
 } from "../modular-schema/index.js";
 
 import { Changeset as ChangesetSchema, type Encoded } from "./formatV3.js";
-import {
-	decodeSequenceChangeset,
-	encodeRevisionWithContext,
-	encodeSequenceChangeset,
-	makeV2CodecHelpers,
-	tryGetEncodedCellRename,
-} from "./sequenceFieldCodecV2.js";
+import { makeV2CodecHelpers } from "./sequenceFieldCodecV2.js";
 import type { Changeset, Mark, MarkEffect, Rename } from "./types.js";
+import { isNoopMark } from "./utils.js";
 
 export function makeV3Codec(
 	revisionTagCodec: IJsonCodec<
@@ -43,55 +37,46 @@ export function makeV3Codec(
 > {
 	const {
 		changeAtomIdCodec: atomIdCodec,
-		encodeMarkEffect: encodeV2MarkEffect,
+		markEffectCodec: markEffectV2Codec,
 		decoderLibrary: decoderLibraryV2,
 	} = makeV2CodecHelpers(revisionTagCodec);
 
-	function encodeMarkEffect(
-		mark: Mark,
-		context: FieldChangeEncodingContext,
-	): Encoded.MarkEffect {
-		const encoded = encodeV2MarkEffect(mark, context);
-		const encodedRenameId = tryGetEncodedCellRename(encoded);
-		if (encodedRenameId !== undefined) {
-			return {
-				rename: {
-					idOverride: encodedRenameId,
-				},
-			};
-		}
-
-		return encoded;
-	}
-
-	function decodeMarkEffect(
-		encoded: Encoded.MarkEffect,
-		count: number,
-		cellId: ChangeAtomId | undefined,
-		context: FieldChangeEncodingContext,
-	): MarkEffect {
-		return decoderLibrary.dispatch(encoded, count, cellId, context);
-	}
+	const markEffectCodec: IJsonCodec<
+		MarkEffect,
+		Encoded.MarkEffect,
+		Encoded.MarkEffect,
+		ChangeEncodingContext
+	> = {
+		encode(effect: MarkEffect, context: ChangeEncodingContext): Encoded.MarkEffect {
+			const type = effect.type;
+			switch (type) {
+				case "Rename": {
+					return {
+						rename: {
+							idOverride: atomIdCodec.encode(effect.idOverride, context),
+						},
+					};
+				}
+				default: {
+					return markEffectV2Codec.encode(effect, context);
+				}
+			}
+		},
+		decode(encoded: Encoded.MarkEffect, context: ChangeEncodingContext): MarkEffect {
+			return decoderLibrary.dispatch(encoded, context);
+		},
+	};
 
 	const decoderLibrary = new DiscriminatedUnionDispatcher<
 		Encoded.MarkEffect,
-		/* args */ [
-			count: number,
-			cellId: ChangeAtomId | undefined,
-			context: FieldChangeEncodingContext,
-		],
+		/* args */ [context: ChangeEncodingContext],
 		MarkEffect
 	>({
 		...decoderLibraryV2,
-		rename(
-			encoded: Encoded.Rename,
-			count: number,
-			cellId: ChangeAtomId | undefined,
-			context: FieldChangeEncodingContext,
-		): Rename {
+		rename(encoded: Encoded.Rename, context: ChangeEncodingContext): Rename {
 			return {
 				type: "Rename",
-				idOverride: atomIdCodec.decode(encoded.idOverride, context.baseContext),
+				idOverride: atomIdCodec.decode(encoded.idOverride, context),
 			};
 		},
 	});
@@ -106,19 +91,48 @@ export function makeV3Codec(
 		encode: (
 			changeset: Changeset,
 			context: FieldChangeEncodingContext,
-		): JsonCompatibleReadOnly & Encoded.Changeset<NodeChangeSchema> =>
-			encodeSequenceChangeset(
-				changeset,
-				context,
-				(revision) =>
-					encodeRevisionWithContext(revision, context.baseContext, revisionTagCodec),
-				atomIdCodec,
-				encodeMarkEffect,
-			),
+		): JsonCompatibleReadOnly & Encoded.Changeset<NodeChangeSchema> => {
+			const jsonMarks: Encoded.Changeset<NodeChangeSchema> = [];
+			for (const mark of changeset) {
+				const encodedMark: Encoded.Mark<NodeChangeSchema> = {
+					count: mark.count,
+				};
+				if (!isNoopMark(mark)) {
+					encodedMark.effect = markEffectCodec.encode(mark, context.baseContext);
+				}
+				if (mark.cellId !== undefined) {
+					encodedMark.cellId = atomIdCodec.encode(mark.cellId, context.baseContext);
+				}
+				if (mark.changes !== undefined) {
+					encodedMark.changes = context.encodeNode(mark.changes);
+				}
+				jsonMarks.push(encodedMark);
+			}
+			return jsonMarks;
+		},
 		decode: (
 			changeset: Encoded.Changeset<NodeChangeSchema>,
 			context: FieldChangeEncodingContext,
-		): Changeset => decodeSequenceChangeset(changeset, context, atomIdCodec, decodeMarkEffect),
+		): Changeset => {
+			const marks: Changeset = [];
+			for (const mark of changeset) {
+				const decodedMark: Mark = {
+					count: mark.count,
+				};
+
+				if (mark.effect !== undefined) {
+					Object.assign(decodedMark, markEffectCodec.decode(mark.effect, context.baseContext));
+				}
+				if (mark.cellId !== undefined) {
+					decodedMark.cellId = atomIdCodec.decode(mark.cellId, context.baseContext);
+				}
+				if (mark.changes !== undefined) {
+					decodedMark.changes = context.decodeNode(mark.changes);
+				}
+				marks.push(decodedMark);
+			}
+			return marks;
+		},
 		encodedSchema: ChangesetSchema(EncodedNodeChangeset),
 	};
 }

package/src/feature-libraries/sequence-field/sequenceFieldEditor.ts

@@ -9,17 +9,20 @@ import type { ChangesetLocalId, RevisionTag } from "../../core/index.js";
 import type { FieldEditor, NodeId } from "../modular-schema/index.js";
 
 import { MarkListFactory } from "./markListFactory.js";
-import type { Attach, CellId, CellMark, Changeset, Detach, Mark, MarkList } from "./types.js";
+import type {
+	CellId,
+	CellMark,
+	Changeset,
+	Insert,
+	Mark,
+	MarkList,
+	MoveIn,
+	MoveOut,
+} from "./types.js";
 import { splitMark } from "./utils.js";
 
 export interface SequenceFieldEditor extends FieldEditor<Changeset> {
-	insert(
-		index: number,
-		count: number,
-		cellId: CellId,
-		revision: RevisionTag,
-		moveId: ChangesetLocalId,
-	): Changeset;
+	insert(index: number, count: number, firstId: CellId, revision: RevisionTag): Changeset;
 	remove(index: number, count: number, id: ChangesetLocalId, revision: RevisionTag): Changeset;
 	revive(
 		index: number,
@@ -88,15 +91,14 @@ export const sequenceFieldEditor = {
 	insert: (
 		index: number,
 		count: number,
-		cellId: CellId,
+		firstId: CellId,
 		revision: RevisionTag | undefined,
-		moveId: ChangesetLocalId,
 	): Changeset => {
-		const mark: CellMark<Attach> = {
+		const mark: CellMark<Insert> = {
 			type: "Insert",
-			id: moveId,
+			id: firstId.localId,
 			count,
-			cellId,
+			cellId: firstId,
 			revision,
 		};
 		return markAtIndex(index, mark);
@@ -116,7 +118,7 @@ export const sequenceFieldEditor = {
 		revision: RevisionTag | undefined,
 	): Changeset => {
 		assert(detachEvent.revision !== undefined, 0x724 /* Detach event must have a revision */);
-		const mark: CellMark<Attach> = {
+		const mark: CellMark<Insert> = {
 			type: "Insert",
 			id: detachEvent.localId,
 			count,
@@ -135,14 +137,14 @@ export const sequenceFieldEditor = {
 		revision: RevisionTag | undefined,
 	): Changeset {
 		const moveIn: Mark = {
-			type: "Insert",
+			type: "MoveIn",
 			id: detachCellId,
 			count,
 			cellId: attachCellId,
 			revision,
 		};
 		const moveOut: Mark = {
-			type: "Remove",
+			type: "MoveOut",
 			id: detachCellId,
 			count,
 			revision,
@@ -157,7 +159,7 @@ export const sequenceFieldEditor = {
 		revision: RevisionTag,
 	): Changeset {
 		const moveOut: Mark = {
-			type: "Remove",
+			type: "MoveOut",
 			id: detachCellId,
 			count,
 			revision,
@@ -173,7 +175,7 @@ export const sequenceFieldEditor = {
 		revision: RevisionTag,
 	): Changeset {
 		const moveIn: Mark = {
-			type: "Insert",
+			type: "MoveIn",
 			id: moveId,
 			count,
 			cellId: attachCellId,
@@ -190,16 +192,16 @@ export const sequenceFieldEditor = {
 		attachCellId: CellId,
 		revision: RevisionTag | undefined,
 	): Changeset {
-		const moveOut: CellMark<Detach> = {
-			type: "Remove",
+		const moveOut: CellMark<MoveOut> = {
+			type: "MoveOut",
 			id: attachCellId.localId,
-			cellRename: detachCellId,
+			idOverride: detachCellId,
 			count,
 			revision,
 		};
 
-		const returnTo: CellMark<Attach> = {
-			type: "Insert",
+		const returnTo: CellMark<MoveIn> = {
+			type: "MoveIn",
 			id: attachCellId.localId,
 			count,
 			cellId: attachCellId,
@@ -214,8 +216,8 @@ function moveMarksToMarkList(
 	sourceIndex: number,
 	count: number,
 	destIndex: number,
-	detach: CellMark<Detach>,
-	attach: CellMark<Attach>,
+	detach: CellMark<MoveOut>,
+	attach: CellMark<MoveIn>,
 ): MarkList {
 	if (count === 0) {
 		return [];

package/src/feature-libraries/sequence-field/sequenceFieldToDelta.ts

@@ -5,61 +5,162 @@
 
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
-import type { DeltaFieldChanges, DeltaMark } from "../../core/index.js";
+import {
+	type DeltaDetachedNodeChanges,
+	type DeltaDetachedNodeRename,
+	type DeltaMark,
+	areEqualChangeAtomIds,
+} from "../../core/index.js";
 import { getLast, hasSome, type Mutable } from "../../util/index.js";
 import { nodeIdFromChangeAtom } from "../deltaUtils.js";
-import type { ToDelta } from "../modular-schema/index.js";
+import type { FieldChangeDelta, ToDelta } from "../modular-schema/index.js";
 
+import { isMoveIn, isMoveOut } from "./moveEffectTable.js";
 import { type MarkList, NoopMarkType } from "./types.js";
 import {
 	areInputCellsEmpty,
 	areOutputCellsEmpty,
-	getAttachedRootId,
-	getDetachedRootId,
+	getDetachedNodeId,
+	getEndpoint,
 	getInputCellId,
+	isAttachAndDetachEffect,
 } from "./utils.js";
 
 export function sequenceFieldToDelta(
 	change: MarkList,
 	deltaFromChild: ToDelta,
-): DeltaFieldChanges {
-	const deltaMarks: DeltaMark[] = [];
+): FieldChangeDelta {
+	const local: DeltaMark[] = [];
+	const global: DeltaDetachedNodeChanges[] = [];
+	const rename: DeltaDetachedNodeRename[] = [];
 
 	for (const mark of change) {
 		const deltaMark: Mutable<DeltaMark> = { count: mark.count };
 		const inputCellId = getInputCellId(mark);
 		const changes = mark.changes;
-		if (changes !== undefined && inputCellId === undefined) {
+		if (changes !== undefined) {
 			const nestedDelta = deltaFromChild(changes);
 			if (nestedDelta.size > 0) {
-				deltaMark.fields = nestedDelta;
+				if (inputCellId === undefined) {
+					deltaMark.fields = nestedDelta;
+				} else {
+					global.push({
+						id: nodeIdFromChangeAtom(inputCellId),
+						fields: nestedDelta,
+					});
+				}
 			}
 		}
 		if (!areInputCellsEmpty(mark) && !areOutputCellsEmpty(mark)) {
 			// Since each cell is associated with exactly one node,
 			// the cell starting end ending populated means the cell content has not changed.
-			deltaMarks.push(deltaMark);
+			local.push(deltaMark);
+		} else if (isAttachAndDetachEffect(mark)) {
+			assert(
+				inputCellId !== undefined,
+				0x81e /* AttachAndDetach mark should have defined input cell ID */,
+			);
+			// The cell starting and ending empty means the cell content has not changed,
+			// unless transient content was inserted/attached.
+			if (isMoveIn(mark.attach) && isMoveOut(mark.detach)) {
+				assert(
+					mark.changes === undefined,
+					0x81f /* AttachAndDetach moves should not have changes */,
+				);
+				continue;
+			}
+
+			const outputId = getDetachedNodeId(mark.detach);
+			assert(
+				outputId !== undefined,
+				0x820 /* AttachAndDetach mark should have defined output cell ID */,
+			);
+			const oldId = nodeIdFromChangeAtom(
+				isMoveIn(mark.attach) ? getEndpoint(mark.attach) : inputCellId,
+			);
+			if (!areEqualChangeAtomIds(inputCellId, outputId)) {
+				rename.push({
+					count: mark.count,
+					oldId,
+					newId: nodeIdFromChangeAtom(outputId),
+				});
+			}
+			if (deltaMark.fields) {
+				global.push({
+					id: oldId,
+					fields: deltaMark.fields,
+				});
+			}
 		} else {
 			const type = mark.type;
 			// Inline into `switch(mark.type)` once we upgrade to TS 4.7
 			switch (type) {
+				case "MoveIn": {
+					local.push({
+						attach: nodeIdFromChangeAtom(getEndpoint(mark)),
+						count: mark.count,
+					});
+					break;
+				}
 				case "Remove": {
-					const newDetachId = getDetachedRootId(mark);
+					const newDetachId = getDetachedNodeId(mark);
 					if (inputCellId === undefined) {
 						deltaMark.detach = nodeIdFromChangeAtom(newDetachId);
-						deltaMarks.push(deltaMark);
+						local.push(deltaMark);
+					} else {
+						const oldId = nodeIdFromChangeAtom(inputCellId);
+						// Removal of already removed content is only a no-op if the detach IDs are different.
+						if (!areEqualChangeAtomIds(inputCellId, newDetachId)) {
+							rename.push({
+								count: mark.count,
+								oldId,
+								newId: nodeIdFromChangeAtom(newDetachId),
+							});
+						}
+						// In all cases, the nested changes apply
+						if (deltaMark.fields) {
+							global.push({
+								id: oldId,
+								fields: deltaMark.fields,
+							});
+						}
+					}
+					break;
+				}
+				case "MoveOut": {
+					// The move destination will look for the detach ID of the source, so we can ignore `finalEndpoint`.
+					const detachId = nodeIdFromChangeAtom(getDetachedNodeId(mark));
+					if (inputCellId === undefined) {
+						deltaMark.detach = detachId;
+						local.push(deltaMark);
+					} else {
+						// Move sources implicitly restore their content
+						rename.push({
+							count: mark.count,
+							oldId: nodeIdFromChangeAtom(inputCellId),
+							newId: detachId,
+						});
 					}
 					break;
 				}
 				case "Insert": {
-					const buildId = nodeIdFromChangeAtom(getAttachedRootId(mark));
+					assert(
+						inputCellId !== undefined,
+						0x821 /* Active Insert marks must have a CellId */,
+					);
+					const buildId = nodeIdFromChangeAtom(inputCellId);
 					deltaMark.attach = buildId;
-					deltaMarks.push(deltaMark);
+					if (deltaMark.fields) {
+						// Nested changes are represented on the node in its starting location
+						global.push({ id: buildId, fields: deltaMark.fields });
+						delete deltaMark.fields;
+					}
+					local.push(deltaMark);
 					break;
 				}
 				case NoopMarkType: {
 					if (inputCellId === undefined) {
-						deltaMarks.push(deltaMark);
+						local.push(deltaMark);
 					}
 					break;
 				}
@@ -77,8 +178,8 @@ export function sequenceFieldToDelta(
 		}
 	}
 	// Remove trailing no-op marks
-	while (hasSome(deltaMarks)) {
-		const lastMark = getLast(deltaMarks);
+	while (hasSome(local)) {
+		const lastMark = getLast(local);
 		if (
 			lastMark.attach !== undefined ||
 			lastMark.detach !== undefined ||
@@ -86,8 +187,17 @@ export function sequenceFieldToDelta(
 		) {
 			break;
 		}
-		deltaMarks.pop();
+		local.pop();
 	}
-
-	return deltaMarks;
+	const delta: Mutable<FieldChangeDelta> = {};
+	if (local.length > 0) {
+		delta.local = local;
+	}
+	if (global.length > 0) {
+		delta.global = global;
+	}
+	if (rename.length > 0) {
+		delta.rename = rename;
+	}
+	return delta;
 }

package/src/feature-libraries/sequence-field/sequenceKind.ts

@@ -0,0 +1,40 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Multiplicity, forbiddenFieldKindIdentifier } from "../../core/index.js";
+import {
+	sequenceIdentifier,
+	identifierFieldIdentifier,
+	requiredIdentifier,
+	optionalIdentifier,
+} from "../fieldKindIdentifiers.js";
+import { FlexFieldKind } from "../modular-schema/index.js";
+
+import { sequenceFieldChangeHandler } from "./sequenceFieldChangeHandler.js";
+import type { SequenceFieldEditor } from "./sequenceFieldEditor.js";
+
+interface Sequence
+	extends FlexFieldKind<
+		SequenceFieldEditor,
+		typeof sequenceIdentifier,
+		Multiplicity.Sequence
+	> {}
+
+/**
+ * 0 or more items.
+ */
+export const sequence: Sequence = new FlexFieldKind(
+	sequenceIdentifier,
+	Multiplicity.Sequence,
+	{
+		changeHandler: sequenceFieldChangeHandler,
+		allowMonotonicUpgradeFrom: new Set([
+			requiredIdentifier,
+			optionalIdentifier,
+			identifierFieldIdentifier,
+			forbiddenFieldKindIdentifier,
+		]),
+	},
+);

package/src/feature-libraries/sequence-field/types.ts

@@ -54,6 +54,7 @@ export interface NoopMark {
 export interface HasRevisionTag {
 	/**
 	 * The revision this mark is part of.
+	 * Only set for marks in fields which are a composition of multiple revisions.
 	 */
 	revision?: RevisionTag;
 }
@@ -70,14 +71,8 @@ export interface HasRevisionTag {
  * Carries a `MoveId` in case it is rebased over the content being moved out, in which case this mark
  * will transform into a pair of returns which will move the content back into this cell.
  */
-export interface Attach extends HasMoveId, HasRevisionTag {
+export interface Insert extends HasMoveId, HasRevisionTag {
 	type: "Insert";
-
-	// XXX: Use this ID as main ID when serializing
-	/**
-	 * This field should only be used if the attach is a pin.
-	 */
-	detachCellId?: ChangeAtomId;
 }
 
 export interface HasMoveFields extends HasMoveId, HasRevisionTag {
@@ -89,37 +84,76 @@ export interface HasMoveFields extends HasMoveId, HasRevisionTag {
 }
 
 /**
- * Removes nodes from their cells.
- * Always brings about the desired outcome: the targeted nodes are removed from their cells.
- * Note that this may not require any changes if targeted nodes are already removed when this mark is applied.
+ * Fills empty cells with content that is moved out from another cell.
+ * Always brings about the desired outcome: the nodes being moved are in the target cells.
+ * Note that this may not require any changes if these nodes are already in the target cells when this mark is applied.
  *
- * Rebasing this mark never causes it to target different set of nodes.
- * Rebasing this mark can cause it to clear a different set of cells.
+ * Rebasing this mark never causes it to move-in a different set of nodes.
+ * Rebasing this mark never causes it to fill a different set of cells
+ * (though the way those cells are identified may change).
+ *
+ * Only ever targets empty cells. It transforms into a idempotent Insert if the target cells are not empty.
  */
-export interface Detach extends HasRevisionTag {
-	readonly type: "Remove";
-	readonly id: ChangesetLocalId;
-
-	/**
-	 * The ID the cell should be set to when this detach is applied.
-	 * If not set, this the same as the detach ID.
-	 * This applies to the cell where the node is being detached from,
-	 * or the last cell the node occupied if it is already detached.
-	 *
-	 * This field is used to represent the composition of a pin and a detach.
-	 * The composition will be the second detach but with the pin's detachId as detachCellId.
-	 */
-	detachCellId?: ChangeAtomId;
+export interface MoveIn extends HasMoveFields {
+	type: "MoveIn";
+}
 
+export interface DetachFields {
 	/**
-	 * When set, this represents a rename of this cell to be applied after the detach.
-	 * Note that this does not affect the ID associated with the detached node.
+	 * When set, the detach should use the `CellId` specified in this object to characterize the cell being emptied.
 	 *
 	 * This is used in two situations:
 	 * - to restore the prior ID of a cell in a rollback changeset
 	 * - to represent the impact of a detach composed with a rename
 	 */
-	readonly cellRename?: CellId;
+	readonly idOverride?: CellId;
+}
+
+/**
+ * Removes nodes from their cells.
+ * Always brings about the desired outcome: the targeted nodes are removed from their cells.
+ * Note that this may not require any changes if targeted nodes are already removed when this mark is applied.
+ *
+ * Rebasing this mark never causes it to target different set of nodes.
+ * Rebasing this mark can cause it to clear a different set of cells.
+ */
+export interface Remove extends HasRevisionTag, DetachFields {
+	type: "Remove";
+	id: ChangesetLocalId;
+}
+
+/**
+ * Removes nodes from their cells so they can be moved into other cells.
+ * Always brings about the desired outcome: the targeted nodes are removed from their cells.
+ * Note that this may not require any changes if targeted nodes are already removed when this mark is applied.
+ *
+ * Rebasing this mark never causes it to target different set of nodes.
+ * Rebasing this mark can cause it to clear a different set of cells.
+ */
+export interface MoveOut extends HasMoveFields, DetachFields {
+	type: "MoveOut";
+}
+
+export type Attach = Insert | MoveIn;
+
+export type Detach = Remove | MoveOut;
+
+/**
+ * Fills then empties cells.
+ *
+ * Only ever targets empty cells.
+ *
+ * As a matter of normalization, we only use an AttachAndDetach to represent MoveIn ○ Remove.
+ *
+ * We do NOT use AttachAndDetach to represent the following compositions:
+ * - Insert/Revive ○ Remove (represented by a Remove)
+ * - Insert/Revive ○ MoveOut (represented by a MoveOut)
+ * - MoveIn ○ MoveOut (represented by a Rename)
+ */
+export interface AttachAndDetach {
+	type: "AttachAndDetach";
+	attach: Attach;
+	detach: Detach;
 }
 
 /**
@@ -135,11 +169,7 @@ export interface Rename {
 	readonly idOverride: CellId;
 }
 
-export interface Pin extends CellMark<Attach> {
-	cellId: undefined;
-}
-
-export type MarkEffect = NoopMark | Attach | Detach | Rename;
+export type MarkEffect = NoopMark | Attach | Detach | AttachAndDetach | Rename;
 
 export type CellMark<TMark> = TMark & HasMarkFields;