fix(directory): Add clearInternal event and mark it as internal (#25927)

The standard clear event has the below limitation. It does not tell you
which subdirectory was cleared.

- It's emitted on the root SharedDirectory for all clear operations
- But it does NOT include the path of which directory was cleared

The event only provides:
- local: Whether it was a local or remote operation
- target: SharedDirectory itself

This limitation came to notice while adding event testing for directory:
#25477. The oracle needs
to track the state of every directory in the tree (root and all
subdirectories). When a clear operation happens:

- Without path information: The oracle would have to clear ALL
directories in its model, even though only one specific directory was
cleared
- Can't distinguish: A clear on /subdir1 vs /subdir2 vs root (/) would
all look the same

This change adds a new event `clearInternal` which takes in the absolute
path and it is marked as internal.


[AB#54326](https://dev.azure.com/fluidframework/internal/_workitems/edit/54326)

Author: sonalideshpandemsft

packages/dds/map/src/directory.ts

@@ -40,7 +40,7 @@ import type {
 	IDirectoryEvents,
 	IDirectoryValueChanged,
 	ISharedDirectory,
-	ISharedDirectoryEvents,
+	ISharedDirectoryEventsInternal,
 	IValueChanged,
 } from "./interfaces.js";
 import type {
@@ -402,7 +402,7 @@ interface SequenceData {
  * @sealed
  */
 export class SharedDirectory
-	extends SharedObject<ISharedDirectoryEvents>
+	extends SharedObject<ISharedDirectoryEventsInternal>
 	implements ISharedDirectory
 {
 	/**
@@ -1570,6 +1570,7 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
 		if (!this.directory.isAttached()) {
 			this.sequencedStorageData.clear();
 			this.directory.emit("clear", true, this.directory);
+			this.directory.emit("clearInternal", this.absolutePath, true, this.directory);
 			return;
 		}
 
@@ -1581,6 +1582,7 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
 		this.pendingStorageData.push(pendingClear);
 
 		this.directory.emit("clear", true, this.directory);
+		this.directory.emit("clearInternal", this.absolutePath, true, this.directory);
 		const op: IDirectoryOperation = {
 			type: "clear",
 			path: this.absolutePath,
@@ -1907,6 +1909,7 @@ class SubDirectory extends TypedEventEmitter<IDirectoryEvents> implements IDirec
 			// is no optimistically-applied local pending clear that would supersede this remote clear.
 			if (!this.pendingStorageData.some((entry) => entry.type === "clear")) {
 				this.directory.emit("clear", local, this.directory);
+				this.directory.emit("clearInternal", this.absolutePath, local, this.directory);
 			}
 
 			// For pending set operations, emit valueChanged events

packages/dds/map/src/interfaces.ts

@@ -277,6 +277,28 @@ export interface IDirectoryEvents extends IEvent {
 	(event: "undisposed", listener: (target: IEventThisPlaceHolder) => void);
 }
 
+/**
+ * Internal events for {@link ISharedDirectory}.
+ * @internal
+ */
+export interface ISharedDirectoryEventsInternal extends ISharedDirectoryEvents {
+	/**
+	 * Emitted when the {@link ISharedDirectory} is cleared.
+	 *
+	 * @remarks Listener parameters:
+	 *
+	 * - `path` - The absolute path to the directory that was cleared.
+	 *
+	 * - `local` - Whether the clear originated from this client.
+	 *
+	 * - `target` - The {@link ISharedDirectory} itself.
+	 */
+	(
+		event: "clearInternal",
+		listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void,
+	);
+}
+
 /**
  * Provides a hierarchical organization of map-like data structures as SubDirectories.
  * The values stored within can be accessed like a map, and the hierarchy can be navigated using path syntax.