[unified-selection] Expose clear storage event source name

.changeset/good-ghosts-dress.md

@@ -0,0 +1,20 @@
+---
+"@itwin/unified-selection": minor
+---
+
+Expose `CLEAR_SELECTION_STORAGE_SOURCE` constant that is used as selection change event source when selection storage is cleared. This should allow consumers to detect when selection change happened due to selection storage being cleared.
+
+```ts
+import { createStorage, CLEAR_SELECTION_STORAGE_SOURCE } from "@itwin/unified-selection";
+
+const storage = createStorage();
+storage.selectionChangeEvent.addListener((args) => {
+  if (args.source === CLEAR_SELECTION_STORAGE_SOURCE) {
+    // ignore change if it was caused by clearing selection storage
+  }
+  // handle selection change
+});
+
+// this will trigger the `selectionChangeEvent` with `{ source: CLEAR_SELECTION_STORAGE_SOURCE }`
+storage.clearStorage({ imodelKey: imodel.key });
+```

packages/unified-selection/api/unified-selection.api.md

@@ -28,6 +28,9 @@ interface CachingHiliteSetProviderProps {
     selectionStorage: SelectionStorage;
 }
 
+// @public
+export const CLEAR_SELECTION_STORAGE_SOURCE = "Unified selection storage: clear";
+
 // @public
 export function computeSelection(props: ComputeSelectionProps): AsyncIterableIterator<SelectableInstanceKey>;
 

packages/unified-selection/api/unified-selection.exports.csv

@@ -2,6 +2,7 @@ sep=;
 Release Tag;API Item Type;API Item Name
 public;interface;CachingHiliteSetProvider
 deprecated;interface;CachingHiliteSetProvider
+public;const;CLEAR_SELECTION_STORAGE_SOURCE
 public;function;computeSelection
 public;function;createCachingHiliteSetProvider
 deprecated;function;createCachingHiliteSetProvider

packages/unified-selection/src/test/SelectionStorage.test.ts

@@ -5,7 +5,11 @@
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { SelectableInstanceKey, Selectables } from "../unified-selection/Selectable.js";
-import { createStorage, SelectionStorage } from "../unified-selection/SelectionStorage.js";
+import {
+  CLEAR_SELECTION_STORAGE_SOURCE,
+  createStorage,
+  SelectionStorage,
+} from "../unified-selection/SelectionStorage.js";
 import { createSelectableInstanceKey } from "./_helpers/SelectablesCreator.js";
 
 const generateSelection = (): SelectableInstanceKey[] => {
@@ -36,6 +40,10 @@ describe("SelectionStorage", () => {
       selectionStorage.clearStorage({ imodelKey });
       expect(Selectables.isEmpty(selectionStorage.getSelection({ imodelKey }))).toBe(true);
       expect(listenerSpy, "Expected selectionChange.onSelectionChange to be called").toHaveBeenCalledOnce();
+      expect(listenerSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ source: CLEAR_SELECTION_STORAGE_SOURCE }),
+        selectionStorage,
+      );
     });
   });
 

packages/unified-selection/src/unified-selection.ts

@@ -27,3 +27,4 @@ export {
   StorageSelectionChangeEventArgs,
   StorageSelectionChangesListener,
 } from "./unified-selection/SelectionChangeEvent.js";
+export { CLEAR_SELECTION_STORAGE_SOURCE } from "./unified-selection/SelectionStorage.js";

packages/unified-selection/src/unified-selection/IModelHiliteSetProvider.ts

@@ -10,7 +10,7 @@ import { eachValueFrom } from "rxjs-for-await";
 import { ECClassHierarchyInspector, ECSqlQueryExecutor } from "@itwin/presentation-shared";
 import { createHiliteSetProvider, HiliteSet, HiliteSetProvider } from "./HiliteSetProvider.js";
 import { StorageSelectionChangeEventArgs } from "./SelectionChangeEvent.js";
-import { IMODEL_CLOSE_SELECTION_CLEAR_SOURCE, SelectionStorage } from "./SelectionStorage.js";
+import { CLEAR_SELECTION_STORAGE_SOURCE, SelectionStorage } from "./SelectionStorage.js";
 
 /**
  * Props for creating an `IModelHiliteSetProvider` instance.
@@ -81,7 +81,7 @@ class IModelHiliteSetProviderImpl implements IModelHiliteSetProvider {
     this._removeListener = this._selectionStorage.selectionChangeEvent.addListener(
       (args: StorageSelectionChangeEventArgs) => {
         this._cache.delete(args.imodelKey);
-        if (args.changeType === "clear" && args.source === IMODEL_CLOSE_SELECTION_CLEAR_SOURCE) {
+        if (args.changeType === "clear" && args.source === CLEAR_SELECTION_STORAGE_SOURCE) {
           this._hiliteSetProviders.delete(args.imodelKey);
         }
       },

packages/unified-selection/src/unified-selection/SelectionStorage.ts

@@ -131,8 +131,11 @@ export function createStorage(): SelectionStorage {
   return new SelectionStorageImpl();
 }
 
-/** @internal */
-export const IMODEL_CLOSE_SELECTION_CLEAR_SOURCE = "Unified selection storage: clear";
+/**
+ * The source name used when selection change is caused by clearing the selection storage. Used when change is performed by `clearStorage`.
+ * @public
+ */
+export const CLEAR_SELECTION_STORAGE_SOURCE = "Unified selection storage: clear";
 
 class SelectionStorageImpl implements SelectionStorage {
   private _storage = new Map<string, MultiLevelSelectablesContainer>();
@@ -170,7 +173,7 @@ class SelectionStorageImpl implements SelectionStorage {
 
   public clearStorage(props: IModelKeyProp): void {
     const imodelKey = getIModelKey(props);
-    this.clearSelection({ source: IMODEL_CLOSE_SELECTION_CLEAR_SOURCE, imodelKey });
+    this.clearSelection({ source: CLEAR_SELECTION_STORAGE_SOURCE, imodelKey });
     this._storage.delete(imodelKey);
   }