fix(@fluid-experimental/tree): Export undo-redo constructs (#23201)

## Description Exports the intended undo-redo surface from experimental SharedTree. Resolves #23028 Co-authored-by: Abram Sanderson <[email protected]>
microsoft · Nov 25, 2024 · e71e434 · e71e434
1 parent 1a4e6bd
commit e71e434
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 0 deletions.
diff --git a/experimental/dds/tree/api-report/experimental-tree.alpha.api.md b/experimental/dds/tree/api-report/experimental-tree.alpha.api.md
@@ -419,6 +419,12 @@ export interface InternalizedChange {
     InternalChangeBrand: '2cae1045-61cf-4ef7-a6a3-8ad920cb7ab3';
 }
 
+// @alpha
+export interface IRevertible {
+    discard(): any;
+    revert(): any;
+}
+
 // @alpha
 export interface ISharedTreeEvents extends ISharedObjectEvents {
     // (undocumented)
@@ -427,6 +433,11 @@ export interface ISharedTreeEvents extends ISharedObjectEvents {
     (event: 'appliedSequencedEdit', listener: SequencedEditAppliedHandler): any;
 }
 
+// @alpha
+export interface IUndoConsumer {
+    pushToCurrentOperation(revertible: IRevertible): any;
+}
+
 // @alpha
 export type LocalCompressedId = number & {
     readonly LocalCompressedId: '6fccb42f-e2a4-4243-bd29-f13d12b9c6d1';
@@ -721,6 +732,13 @@ export interface SharedTreeSummaryBase {
     readonly version: WriteFormat;
 }
 
+// @alpha
+export class SharedTreeUndoRedoHandler {
+    constructor(stackManager: IUndoConsumer);
+    attachTree(tree: SharedTree): void;
+    detachTree(tree: SharedTree): void;
+}
+
 // @alpha
 export enum Side {
     // (undocumented)

diff --git a/experimental/dds/tree/src/UndoRedoHandler.ts b/experimental/dds/tree/src/UndoRedoHandler.ts
@@ -11,25 +11,59 @@ import { EditCommittedEventArguments, SharedTree } from './SharedTree.js';
 // TODO: We temporarily duplicate these contracts from 'framework/undo-redo' to unblock development
 // while we decide on the correct layering for undo.
 
+/**
+ * A revertible change
+ *
+ * @alpha
+ */
 export interface IRevertible {
+	/**
+	 * Revert the change
+	 */
 	revert();
+
+	/**
+	 * Discard the change, freeing any associated resources.
+	 */
 	discard();
 }
 
+/**
+ * A consumer of revertible changes.
+ *
+ * This interface is typically implemented by a stack which may optionally aggregate multiple
+ * changes into one operation.
+ *
+ * @alpha
+ */
 export interface IUndoConsumer {
+	/**
+	 * Push a revertible to the current operation. Invoked for each change on undo consumers subscribed to a SharedTree.
+	 */
 	pushToCurrentOperation(revertible: IRevertible);
 }
 
 /**
  * A shared tree undo redo handler that will add revertible local tree changes to the provided
  * undo redo stack manager
+ *
+ * @alpha
  */
 export class SharedTreeUndoRedoHandler {
 	constructor(private readonly stackManager: IUndoConsumer) {}
 
+	/**
+	 * Attach a shared tree to this handler. Each edit from the tree will invoke `this.stackManager`'s
+	 * {@link IUndoConsumer.pushToCurrentOperation} method with an associated {@link IRevertible}.
+	 */
 	public attachTree(tree: SharedTree) {
 		tree.on(SharedTreeEvent.EditCommitted, this.treeDeltaHandler);
 	}
+
+	/**
+	 * Detach a shared tree from this handler. Edits from the tree will no longer cause `this.stackManager`'s
+	 * {@link IUndoConsumer.pushToCurrentOperation} to be called.
+	 */
 	public detachTree(tree: SharedTree) {
 		tree.off(SharedTreeEvent.EditCommitted, this.treeDeltaHandler);
 	}

diff --git a/experimental/dds/tree/src/index.ts b/experimental/dds/tree/src/index.ts
@@ -188,3 +188,5 @@ export {
 	SharedTreeShim,
 	SharedTreeShimFactory,
 } from './migration-shim/index.js';
+
+export { IRevertible, IUndoConsumer, SharedTreeUndoRedoHandler } from './UndoRedoHandler.js';