Add label for transaction commits for undo/redo grouping.

packages/dds/tree/api-report/tree.alpha.api.md

@@ -890,6 +890,7 @@ export interface RunTransaction {
 
 // @alpha @input
 export interface RunTransactionParams {
+    readonly label?: unknown;
     readonly preconditions?: readonly TransactionConstraint[];
 }
 

packages/dds/tree/src/core/index.ts

@@ -173,6 +173,7 @@ export {
 	type GraphCommit,
 	CommitKind,
 	type CommitMetadata,
+	type CommitMetadataAlpha,
 	type RevisionTag,
 	RevisionTagSchema,
 	RevisionTagCodec,

packages/dds/tree/src/core/rebase/index.ts

@@ -12,6 +12,7 @@ export {
 	type GraphCommit,
 	CommitKind,
 	type CommitMetadata,
+	type CommitMetadataAlpha,
 	type RevisionTag,
 	RevisionTagSchema,
 	type EncodedRevisionTag,

packages/dds/tree/src/core/rebase/types.ts

@@ -183,6 +183,18 @@ export interface CommitMetadata {
 	readonly isLocal: boolean;
 }
 
+/**
+ * Extended commit metadata that includes an optional user-provided label.
+ * @alpha
+ */
+export interface CommitMetadataAlpha extends CommitMetadata {
+	/**
+	 * Optional label provided by the user when commit was created.
+	 * This can be used by undo/redo to group or classify edits.
+	 */
+	label?: unknown;
+}
+
 /**
  * Creates a new graph commit object. This is useful for creating copies of commits with different parentage.
  * @param parent - the parent of the new commit

packages/dds/tree/src/shared-tree/schematizingTreeView.ts

@@ -296,33 +296,43 @@ export class SchematizingSimpleTreeView<
 			addConstraintsToTransaction(this.checkout, constraintsOnRevert, constraints);
 		};
 
-		this.checkout.transaction.start();
-
-		// Validate preconditions before running the transaction callback.
-		addConstraints(false /* constraintsOnRevert */, params?.preconditions);
-		const transactionCallbackStatus = transaction();
-		const rollback = transactionCallbackStatus?.rollback;
-		const value = (
-			transactionCallbackStatus as TransactionCallbackStatus<TSuccessValue, TFailureValue>
-		)?.value;
-
-		if (rollback === true) {
-			this.checkout.transaction.abort();
-			return value !== undefined
-				? { success: false, value: value as TFailureValue }
-				: { success: false };
-		}
+		const executeTransaction = ():
+			| TransactionResultExt<TSuccessValue, TFailureValue>
+			| TransactionResult => {
+			this.checkout.transaction.start();
 
-		// Validate preconditions on revert after running the transaction callback and was successful.
-		addConstraints(
-			true /* constraintsOnRevert */,
-			transactionCallbackStatus?.preconditionsOnRevert,
-		);
+			// Validate preconditions before running the transaction callback.
+			addConstraints(false /* constraintsOnRevert */, params?.preconditions);
+			const transactionCallbackStatus = transaction();
+			const rollback = transactionCallbackStatus?.rollback;
+			const value = (
+				transactionCallbackStatus as TransactionCallbackStatus<TSuccessValue, TFailureValue>
+			)?.value;
+
+			if (rollback === true) {
+				this.checkout.transaction.abort();
+				return value !== undefined
+					? { success: false, value: value as TFailureValue }
+					: { success: false };
+			}
+
+			// Validate preconditions on revert after running the transaction callback and was successful.
+			addConstraints(
+				true /* constraintsOnRevert */,
+				transactionCallbackStatus?.preconditionsOnRevert,
+			);
 
-		this.checkout.transaction.commit();
-		return value !== undefined
-			? { success: true, value: value as TSuccessValue }
-			: { success: true };
+			this.checkout.transaction.commit();
+
+			return value !== undefined
+				? { success: true, value: value as TSuccessValue }
+				: { success: true };
+		};
+
+		if (params?.label !== undefined) {
+			return this.checkout.runWithTransactionLabel(params.label, () => executeTransaction());
+		}
+		return executeTransaction();
 	}
 
 	private ensureUndisposed(): void {

packages/dds/tree/src/shared-tree/treeCheckout.ts

@@ -20,7 +20,6 @@ import {
 	type AnchorSetRootEvents,
 	type ChangeFamily,
 	CommitKind,
-	type CommitMetadata,
 	type DeltaVisitor,
 	type DetachedFieldIndex,
 	type IEditableForest,
@@ -48,6 +47,7 @@ import {
 	type TreeNodeStoredSchema,
 	LeafNodeStoredSchema,
 	diffHistories,
+	type CommitMetadataAlpha,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -122,7 +122,7 @@ export interface CheckoutEvents {
 	 * @param getRevertible - a function provided that allows users to get a revertible for the change. If not provided,
 	 * this change is not revertible.
 	 */
-	changed(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
+	changed(data: CommitMetadataAlpha, getRevertible?: RevertibleAlphaFactory): void;
 
 	/**
 	 * Fired when a new branch is created from this checkout.
@@ -370,6 +370,9 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 	private editLock: EditLock;
 
+	// User-defined label associated with the transaction whose commit is currently being produced for this checkout.
+	public transactionLabel?: unknown;
+
 	private readonly views = new Set<TreeView<ImplicitFieldSchema>>();
 
 	/**
@@ -421,6 +424,18 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		this.registerForBranchEvents();
 	}
 
+	public runWithTransactionLabel<TLabel, TResult>(
+		label: TLabel,
+		fn: (label: TLabel) => TResult,
+	): TResult {
+		this.transactionLabel = label;
+		try {
+			return fn(label);
+		} finally {
+			this.transactionLabel = undefined;
+		}
+	}
+
 	private registerForBranchEvents(): void {
 		this.#transaction.branch.events.on("afterChange", this.onAfterBranchChange);
 		this.#transaction.activeBranchEvents.on("afterChange", this.onAfterChange);
@@ -532,12 +547,22 @@ export class TreeCheckout implements ITreeCheckoutFork {
 						};
 
 				let withinEventContext = true;
-				this.#events.emit("changed", { isLocal: true, kind }, getRevertible);
+				const metaData: CommitMetadataAlpha = {
+					isLocal: true,
+					kind,
+					label: this.transactionLabel,
+				};
+				this.#events.emit("changed", metaData, getRevertible);
 				withinEventContext = false;
 			}
 		} else if (this.isRemoteChangeEvent(event)) {
 			// TODO: figure out how to plumb through commit kind info for remote changes
-			this.#events.emit("changed", { isLocal: false, kind: CommitKind.Default });
+			const metaData: CommitMetadataAlpha = {
+				isLocal: false,
+				kind: CommitKind.Default,
+				label: this.transactionLabel,
+			};
+			this.#events.emit("changed", metaData);
 		}
 	};
 

packages/dds/tree/src/simple-tree/api/transactionTypes.ts

@@ -123,4 +123,12 @@ export interface RunTransactionParams {
 	 * this client and ignored by all other clients.
 	 */
 	readonly preconditions?: readonly TransactionConstraint[];
+	/**
+	 * An optional user-defined label for this transaction.
+	 *
+	 * This label is associated with the commit produced by this transaction, and is surfaced through {@link CommitMetadataAlpha.label},
+	 * in the `commitApplied` event.
+	 *
+	 */
+	readonly label?: unknown;
 }

packages/dds/tree/src/simple-tree/api/tree.ts

@@ -6,7 +6,7 @@
 import type { IFluidLoadable, IDisposable, Listenable } from "@fluidframework/core-interfaces";
 
 import type {
-	CommitMetadata,
+	CommitMetadataAlpha,
 	RevertibleAlphaFactory,
 	RevertibleFactory,
 } from "../../core/index.js";
@@ -508,7 +508,7 @@ export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied">
 	 * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,
 	 * this change is not revertible.
 	 */
-	changed(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
+	changed(data: CommitMetadataAlpha, getRevertible?: RevertibleAlphaFactory): void;
 
 	/**
 	 * Fired when:
@@ -527,7 +527,7 @@ export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied">
 	 * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
 	 * this commit is not revertible.
 	 */
-	commitApplied(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
+	commitApplied(data: CommitMetadataAlpha, getRevertible?: RevertibleAlphaFactory): void;
 }
 
 /**
@@ -571,7 +571,7 @@ export interface TreeViewEvents {
 	 * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
 	 * this commit is not revertible.
 	 */
-	commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+	commitApplied(data: CommitMetadataAlpha, getRevertible?: RevertibleFactory): void;
 }
 
 /**