@itwin/unified-selection 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # @itwin/unified-selection
 
+## 0.3.0
+
+### Minor Changes
+
+- [#530](https://github.com/iTwin/presentation/pull/530): Added `enableUnifiedSelectionSyncWithIModel` for enabling synchronization between iModel's tool selection and unified selection storage.
+- [#544](https://github.com/iTwin/presentation/pull/544): Breaking API changes
+
+  - The type of ECSQL query executor's `createQueryReader` function was changed from:
+
+    ```ts
+    // createQueryReader(ecsql: string, bindings?: ECSqlBinding[], config?: ECSqlQueryReaderOptions): ECSqlQueryReader;
+    // usage:
+    const reader = executor.createQueryReader(
+      `
+        WITH RECURSIVE
+        ChildElements(ECInstanceId) AS (
+          SELECT ECInstanceId FROM bis.Element WHERE Parent.Id = ?
+          UNION ALL
+          SELECT c.ECInstanceId FROM bis.Element c JOIN ChildElements p ON c.Parent.Id = p.ECInstanceId
+        )
+        SELECT * FROM ChildElements
+      `,
+      [{ type: "id", value: "0x1" }],
+      { rowFormat: "Indexes" },
+    );
+    ```
+
+    to:
+
+    ```ts
+    // createQueryReader(query: { ctes?: string; ecsql: string; bindings?: ECSqlBinding[] }, config?: ECSqlQueryReaderOptions): ECSqlQueryReader;
+    // usage:
+    const reader = executor.createQueryReader(
+      {
+        ctes: [
+          `
+          ChildElements(ECInstanceId) AS (
+              SELECT ECInstanceId FROM bis.Element WHERE Parent.Id = ?
+              UNION ALL
+              SELECT c.ECInstanceId FROM bis.Element c JOIN ChildElements p ON c.Parent.Id = p.ECInstanceId
+          )
+        `,
+        ],
+        ecsql: "SELECT * FROM ChildElements",
+        bindings: [{ type: "id", value: "0x1" }],
+      },
+      { rowFormat: "Indexes" },
+    );
+    ```
+
+    This makes the API consistent with other Presentation packages and allows additional manipulation on ECSQL, which was not possible previously when ECSQL contained CTEs.
+
+    The change affects the following public APIs:
+
+    - `computeSelection` (`queryExecutor` prop),
+    - `createHiliteSetProvider` (previously `queryExecutor` prop, now `imodelAccess` prop),
+    - `createCachingHiliteSetProvider` (`iModelProvider` prop).
+
+  - `createHiliteSetProvider` function props `queryExecutor` and `schemaProvider` were merged into a single `imodelAccess` prop with merged type.
+
+    Previously:
+
+    ```ts
+    createHiliteSetProvider({
+      queryExecutor: createECSqlQueryExecutor(iModel),
+      schemaProvider: createECSchemaProvider(iModel),
+    });
+    ```
+
+    Now:
+
+    ```ts
+    createHiliteSetProvider({
+      imodelAccess: {
+        ...createECSqlQueryExecutor(iModel),
+        ...createECSchemaProvider(iModel),
+      },
+    });
+    ```
+
+  - `createCachingHiliteSetProvider` function prop `iModelProvider` was changed to return an object of merged type `ECSchemaProvider & ECSqlQueryExecutor` rather than `{ queryExecutor: ECSqlQueryExecutor; schemaProvider: ECSchemaProvider }`.
+
+    Previously:
+
+    ```ts
+    createCachingHiliteSetProvider({
+      selectionStorage,
+      iModelProvider: (key) => ({
+        queryExecutor: createECSqlQueryExecutor(iModel),
+        schemaProvider: createECSchemaProvider(iModel),
+      }),
+    });
+    ```
+
+    Now:
+
+    ```ts
+    createCachingHiliteSetProvider({
+      selectionStorage,
+      iModelProvider: (key) => ({
+        ...createECSqlQueryExecutor(iModel),
+        ...createECSchemaProvider(iModel),
+      }),
+    });
+    ```
+
+- [#551](https://github.com/iTwin/presentation/pull/551): Changed `iModel` in attribute names to `imodel`. The change was made to be consistent with other Presentation packages and affects the following APIs:
+
+  - `SelectionStorage` methods now accept `imodelKey` prop rather than `iModelKey`. It's `selectionChangeEvent` is also now raised with `imodelKey` prop in `StorageSelectionChangeEventArgs`.
+  - `CachingHiliteSetProvider.getHiliteSet` now accepts an `imodelKey` prop rather than `iModelKey`.
+  - `createCachingHiliteSetProvider` props now accept `imodelProvider` callback rather than `iModelProvider`.
+
+- [#553](https://github.com/iTwin/presentation/pull/553): Expose types from `@itwin/presentation-shared` rather than having our own copies.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @itwin/presentation-shared@0.1.0
+
+## 0.2.0
+
+### Minor Changes
+
+- [#488](https://github.com/iTwin/presentation/pull/488): Added API for getting hilite sets for `Selectables` and active `SelectionStorage` selection.
+
+### Patch Changes
+
+- [#495](https://github.com/iTwin/presentation/pull/495): Added license field to `package.json`.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -32,14 +32,14 @@ const unifiedSelection = createStore();
 
 // the store should to be cleaned up when iModels are closed to free up memory, e.g.:
 import { IModelConnection } from "@itwin/core-frontend";
-IModelConnection.onClose.addListener((iModel) => {
-  unifiedSelection.clearStorage(iModel.key);
+IModelConnection.onClose.addListener((imodel) => {
+  unifiedSelection.clearStorage(imodel.key);
 });
 
 // add a demo selection listener
 import { Selectables } from "@itwin/unified-selection";
-unifiedSelection.selectionChangeEvent.addListener(({ iModelKey, source, changeType, selectables }) => {
-  const suffix = `in ${iModelKey} iModel from ${source} component`;
+unifiedSelection.selectionChangeEvent.addListener(({ imodelKey, source, changeType, selectables }) => {
+  const suffix = `in ${imodelKey} iModel from ${source} component`;
   const numSelectables = Selectables.size(selectables);
   switch (changeType) {
     case "add":
@@ -58,8 +58,8 @@ unifiedSelection.selectionChangeEvent.addListener(({ iModelKey, source, changeTy
 });
 
 // in some component
-MyComponent.onECInstanceSelected((iModel: IModelConnection, key: { className: string; id: Id64String }) => {
-  unifiedSelection.addToSelection({ iModelKey: iModel.key, source: "MyComponent", selectables: [key] });
+MyComponent.onECInstanceSelected((imodel: IModelConnection, key: { className: string; id: Id64String }) => {
+  unifiedSelection.addToSelection({ imodelKey: imodel.key, source: "MyComponent", selectables: [key] });
 });
 ```
 
@@ -88,3 +88,101 @@ With that in mind, the above components _A_, _B_ and _C_ can be configured as fo
 - _Component A_ only cares about top level selection. Whenever something is selected in the component, unified selection is updated at the top level. Similarly, whenever unified selection changes, the component only reacts if that happened at the top level.
 - _Component B_ reloads its content if the selection changes at the top level. Row selection is handled using lower level, so selecting a row doesn't affect _Component A's_ selection or _Component B's_ content.
 - _Component C_ reloads its content no matter the selection level.
+
+### Hilite sets
+
+> **Note:** hilite = highlight
+
+`@itwin/core-frontend` contains a concept called the [HiliteSet](https://www.itwinjs.org/reference/core-frontend/selectionset/hiliteset/). This concept is tightly related to unified selection, because, generally, we want selected elements to be highlighted in the application's graphics views. The `HiliteSet` object contains IDs of 3 types of elements: [GeometricModel](https://www.itwinjs.org/reference/core-backend/models/geometricmodel/), [SubCategory](https://www.itwinjs.org/reference/core-backend/categories/subcategory/) and [GeometricElement](https://www.itwinjs.org/reference/core-backend/elements/geometricelement/). On the other hand, the unified selection API allows selecting other kinds of elements too, so IDs of these elements need to be mapped to the supported ones. The rules are as follows:
+
+- for `BisCore.Subject` return IDs of all geometric models that are recursively under that Subject,
+- for `BisCore.Model` just return its ID,
+- for `BisCore.PhysicalPartition` just return ID of a model that models it,
+- for `BisCore.Category` return IDs of all its _SubCategories_,
+- for `BisCore.SubCategory` just return its ID,
+- for `BisCore.GeometricElement` return ID of its own and all its child elements recursively.
+
+So for example when unified selection contains a Subject, the hilite set for it will contain all models under that Subject, it's child Subjects, their child Subjects, etc. Given such hilite set, the viewport component hilites all elements in those models.
+
+The `@itwin/unified-selection` package delivers APIs for creating a `HiliteSet` or retrieving it for _current_ selection in a `SelectionStorage`:
+
+```ts
+// Components may want to get a hilite set for arbitrary set of Selectables - use `createHiliteSetProvider` for that.
+import { IModelConnection } from "@itwin/core-frontend";
+import { createECSqlQueryExecutor, createECSchemaProvider } from "@itwin/presentation-core-interop";
+import { createHiliteSetProvider } from "@itwin/unified-selection";
+const hiliteProvider = createHiliteSetProvider({
+  imodelAccess: {
+    ...createECSchemaProvider(imodel),
+    ...createECSqlQueryExecutor(imodel),
+  },
+});
+const hiliteSet = await hiliteProvider.getHiliteSet({ selectables });
+
+// Some others may want to get a hilite set for _current_ selection in storage - use `createCachingHiliteSetProvider` for that. It's
+// recommended to keep a single instance of this provider per application as it caches hilite sets per each iModel's selection.
+import { createCachingHiliteSetProvider } from "@itwin/unified-selection";
+const selectionHiliteProvider = createCachingHiliteSetProvider({
+  selectionStorage,
+  imodelProvider: (imodelKey: string) => getIModelByKey(imodelKey),
+});
+const selectionHiliteSet = await selectionHiliteProvider.getHiliteSet({ imodel.key });
+// The caching provider registers a selection change listener and should be disposed, in case its lifetime
+// is shorter than that of `SelectionStorage`, to unregister the listener.
+selectionHiliteProvider.dispose();
+```
+
+#### Selection scopes
+
+Selection scopes allow decoupling of what gets picked and what gets selected. Without selection scopes, whenever a user picks an element in the viewport, its ID goes straight into unified selection storage. With selection scopes we can modify that and add something different. The input to the selection scopes' processor is a query executor, element IDs, and the scope to apply, and the output is an iterator of `SelectableInstanceKey`. We get the input when the user picks some elements in the viewport, run that through the selection scope processor and put the output into unified selection storage.
+
+Here are the scopes we support at the moment:
+
+- `element` - return key of selected element.
+- `category` - return key of geometric element's category.
+- `model` - return key of element's model.
+- `functional` - return key of element's related functional element. For `BisCore.GeometricElement3d` the related functional element is found using the `Functional.PhysicalElementFulfillsFunction` relationship. For `BisCore.GeometricElement2d` the nearest functional element is searched for using the `Functional.DrawingGraphicRepresentsFunctionalElement` relationship - if the given element has a related functional element, it will be returned, otherwise the element's parent will be checked and if it also does not have a related functional, then the parent of the parent will be checked until no more ancestors can be traversed or a functional element is found. Regardless whether it is an `BisCore.GeometricElement2d` or `BisCore.GeometricElement3d` if no functional element is found then the element itself will be returned.
+
+The `@itwin/unified-selection` package delivers a `computeSelection` function for computing which elements should be added into unified selection storage based on the given element ID's and a specified selection scope:
+
+```ts
+import { computeSelection } from "@itwin/unified-selection";
+import { IModelConnection } from "@itwin/core-frontend";
+import { createECSqlQueryExecutor } from "@itwin/presentation-core-interop";
+const queryExecutor = createECSqlQueryExecutor(imodel);
+const selection = computeSelection({ queryExecutor, elementIds, scope: "element" });
+```
+
+`element` and `functional` scopes additionally allow selecting assembly elements by specifying the `ancestorLevel` property in the selection scope argument of `computeSelection` function. The `ancestorLevel` property specifies how far "up" we should walk to find the target element. When not specified or `0`, the target element matches the request element. When set to `1`, the target element matches the direct parent element. When `2`, the target element is the parent of the parent element, and so on. In all situations when this is `> 0`, we're not walking further than the last existing element, for example, when `ancestorLevel = 1` (direct parent element is requested), but the request element doesn't have a parent, the request element is returned as the result. A negative value would result in the top-most element to be returned.
+
+For the `functional` scope, the `ancestorLevel` property is used as follows: if an element is a `BisCore.GeometricElement3d` element, its ancestor is selected based on the given `ancestorLevel` the same as with non-functional elements, and then the resulting element's related functional element will be returned (using the `Functional.PhysicalElementFulfillsFunction` relationship), or if it does not have one, then the resulting element will be returned. For `BisCore.GeometricElement2d` elements, the nearest related functional element is found in the same way it is done when the `ancestorLevel` property is not provided, and then the ancestor of that element is returned (based on the provided value of `ancestorLevel`).
+
+```ts
+import { computeSelection } from "@itwin/unified-selection";
+import { IModelConnection } from "@itwin/core-frontend";
+import { createECSqlQueryExecutor } from "@itwin/presentation-core-interop";
+const queryExecutor = createECSqlQueryExecutor(imodel);
+// Returns the parent element, or the element itself if it does not have a parent, for each element specified in `elementIds` argument.
+const selection = computeSelection({ queryExecutor, elementIds, scope: { id: "element", ancestorLevel: 1 } });
+```
+
+## iModel selection synchronization with unified selection
+
+The `@itwin/unified-selection` package delivers a `enableUnifiedSelectionSyncWithIModel` function to enable selection synchronization between an iModel and a `SelectionStorage`. When called, it returns a cleanup function that should be used to disable the synchronization. There should only be one active synchronization between a single iModel and a `SelectionStorage` at a given time. For example, this function could be used inside a `useEffect` hook in a component that holds an iModel:
+
+```ts
+import { createECSqlQueryExecutor, createECSchemaProvider } from "@itwin/presentation-core-interop";
+useEffect(() => {
+  return enableUnifiedSelectionSyncWithIModel({
+    imodelAccess: {
+      ...createECSqlQueryExecutor(imodel),
+      ...createECSchemaProvider(imodel),
+      key: imodel.key,
+      hiliteSet: imodel.hilited,
+      selectionSet: imodel.selectionSet,
+    },
+    selectionStorage,
+    activeScopeProvider: () => "element",
+  });
+}, [imodel]);
+```

package/lib/cjs/unified-selection/CachingHiliteSetProvider.d.ts

@@ -0,0 +1,33 @@
+import { ECSchemaProvider, ECSqlQueryExecutor } from "@itwin/presentation-shared";
+import { HiliteSet } from "./HiliteSetProvider";
+import { SelectionStorage } from "./SelectionStorage";
+/**
+ * Props for creating a `CachingHiliteSetProvider` instance.
+ * @internal Not exported through barrel, but used in public API as an argument. May be supplemented with optional attributes any time.
+ */
+export interface CachingHiliteSetProviderProps {
+    selectionStorage: SelectionStorage;
+    imodelProvider: (imodelKey: string) => ECSchemaProvider & ECSqlQueryExecutor;
+}
+/**
+ * Defines return value of `createCachingHiliteSetProvider`.
+ *
+ * @beta Used in public API as a return value. Not expected to be created / extended by package
+ * consumers, may be supplemented with required attributes any time.
+ */
+export interface CachingHiliteSetProvider {
+    /** Get the current hilite set iterator for the specified imodel */
+    getHiliteSet(props: {
+        /** iModel to get hilite set for */
+        imodelKey: string;
+    }): AsyncIterableIterator<HiliteSet>;
+    /** Disposes the cache. */
+    dispose(): void;
+}
+/**
+ * Creates a hilite set provider that caches hilite set for current selection for given iModel so any subsequent
+ * hilite set requests for the same iModel don't cost until selection in given selection storage changes.
+ * @beta
+ */
+export declare function createCachingHiliteSetProvider(props: CachingHiliteSetProviderProps): CachingHiliteSetProvider;
+//# sourceMappingURL=CachingHiliteSetProvider.d.ts.map

package/lib/cjs/unified-selection/CachingHiliteSetProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachingHiliteSetProvider.d.ts","sourceRoot":"","sources":["../../../src/unified-selection/CachingHiliteSetProvider.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAA2B,SAAS,EAAqB,MAAM,qBAAqB,CAAC;AAE5F,OAAO,EAAuC,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3F;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC5C,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,gBAAgB,GAAG,kBAAkB,CAAC;CAC9E;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,YAAY,CAAC,KAAK,EAAE;QAClB,mCAAmC;QACnC,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAErC,0BAA0B;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,6BAA6B,GAAG,wBAAwB,CAE7G"}

package/lib/cjs/unified-selection/CachingHiliteSetProvider.js

@@ -0,0 +1,62 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCachingHiliteSetProvider = void 0;
+const rxjs_1 = require("rxjs");
+const rxjs_for_await_1 = require("rxjs-for-await");
+const HiliteSetProvider_1 = require("./HiliteSetProvider");
+const SelectionStorage_1 = require("./SelectionStorage");
+/**
+ * Creates a hilite set provider that caches hilite set for current selection for given iModel so any subsequent
+ * hilite set requests for the same iModel don't cost until selection in given selection storage changes.
+ * @beta
+ */
+function createCachingHiliteSetProvider(props) {
+    return new CachingHiliteSetProviderImpl(props);
+}
+exports.createCachingHiliteSetProvider = createCachingHiliteSetProvider;
+class CachingHiliteSetProviderImpl {
+    _selectionStorage;
+    _hiliteSetProviders = new Map();
+    _cache = new Map();
+    _removeListener;
+    _imodelProvider;
+    constructor(props) {
+        this._selectionStorage = props.selectionStorage;
+        this._imodelProvider = props.imodelProvider;
+        this._removeListener = this._selectionStorage.selectionChangeEvent.addListener((args) => {
+            this._cache.delete(args.imodelKey);
+            if (args.changeType === "clear" && args.source === SelectionStorage_1.IMODEL_CLOSE_SELECTION_CLEAR_SOURCE) {
+                this._hiliteSetProviders.delete(args.imodelKey);
+            }
+        });
+    }
+    getHiliteSet({ imodelKey }) {
+        const imodelAccess = this._imodelProvider(imodelKey);
+        const provider = this.getHiliteSetProvider(imodelKey, imodelAccess);
+        let hiliteSet = this._cache.get(imodelKey);
+        if (!hiliteSet) {
+            const selectables = this._selectionStorage.getSelection({ imodelKey });
+            hiliteSet = (0, rxjs_1.from)(provider.getHiliteSet({ selectables })).pipe((0, rxjs_1.shareReplay)({ refCount: true }));
+            this._cache.set(imodelKey, hiliteSet);
+        }
+        return (0, rxjs_for_await_1.eachValueFrom)(hiliteSet);
+    }
+    dispose() {
+        this._removeListener();
+        this._hiliteSetProviders = new Map();
+        this._cache = new Map();
+    }
+    getHiliteSetProvider(imodelKey, imodelAccess) {
+        let provider = this._hiliteSetProviders.get(imodelKey);
+        if (!provider) {
+            provider = (0, HiliteSetProvider_1.createHiliteSetProvider)({ imodelAccess });
+            this._hiliteSetProviders.set(imodelKey, provider);
+        }
+        return provider;
+    }
+}
+//# sourceMappingURL=CachingHiliteSetProvider.js.map

package/lib/cjs/unified-selection/CachingHiliteSetProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachingHiliteSetProvider.js","sourceRoot":"","sources":["../../../src/unified-selection/CachingHiliteSetProvider.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AAEhG,+BAAqD;AACrD,mDAA+C;AAE/C,2DAA4F;AAE5F,yDAA2F;AA4B3F;;;;GAIG;AACH,SAAgB,8BAA8B,CAAC,KAAoC;IACjF,OAAO,IAAI,4BAA4B,CAAC,KAAK,CAAC,CAAC;AACjD,CAAC;AAFD,wEAEC;AAED,MAAM,4BAA4B;IACxB,iBAAiB,CAAmB;IACpC,mBAAmB,GAAG,IAAI,GAAG,EAA6B,CAAC;IAC3D,MAAM,GAAG,IAAI,GAAG,EAAiC,CAAC;IAClD,eAAe,CAAa;IAC5B,eAAe,CAA+D;IAEtF,YAAY,KAAoC;QAC9C,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,gBAAgB,CAAC;QAChD,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,cAAc,CAAC;QAC5C,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,IAAqC,EAAE,EAAE;YACvH,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACnC,IAAI,IAAI,CAAC,UAAU,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,KAAK,sDAAmC,EAAE,CAAC;gBACvF,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAClD,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAEM,YAAY,CAAC,EAAE,SAAS,EAAyB;QACtD,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;QACpE,IAAI,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAE3C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;YACvE,SAAS,GAAG,IAAA,WAAI,EAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAA,kBAAW,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAC/F,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,IAAA,8BAAa,EAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAEM,OAAO;QACZ,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,mBAAmB,GAAG,IAAI,GAAG,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;IAC1B,CAAC;IAEO,oBAAoB,CAAC,SAAiB,EAAE,YAAmD;QACjG,IAAI,QAAQ,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,IAAA,2CAAuB,EAAC,EAAE,YAAY,EAAE,CAAC,CAAC;YACrD,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF","sourcesContent":["/*---------------------------------------------------------------------------------------------\n * Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n * See LICENSE.md in the project root for license terms and full copyright notice.\n *--------------------------------------------------------------------------------------------*/\n\nimport { from, Observable, shareReplay } from \"rxjs\";\nimport { eachValueFrom } from \"rxjs-for-await\";\nimport { ECSchemaProvider, ECSqlQueryExecutor } from \"@itwin/presentation-shared\";\nimport { createHiliteSetProvider, HiliteSet, HiliteSetProvider } from \"./HiliteSetProvider\";\nimport { StorageSelectionChangeEventArgs } from \"./SelectionChangeEvent\";\nimport { IMODEL_CLOSE_SELECTION_CLEAR_SOURCE, SelectionStorage } from \"./SelectionStorage\";\n\n/**\n * Props for creating a `CachingHiliteSetProvider` instance.\n * @internal Not exported through barrel, but used in public API as an argument. May be supplemented with optional attributes any time.\n */\nexport interface CachingHiliteSetProviderProps {\n  selectionStorage: SelectionStorage;\n  imodelProvider: (imodelKey: string) => ECSchemaProvider & ECSqlQueryExecutor;\n}\n\n/**\n * Defines return value of `createCachingHiliteSetProvider`.\n *\n * @beta Used in public API as a return value. Not expected to be created / extended by package\n * consumers, may be supplemented with required attributes any time.\n */\nexport interface CachingHiliteSetProvider {\n  /** Get the current hilite set iterator for the specified imodel */\n  getHiliteSet(props: {\n    /** iModel to get hilite set for */\n    imodelKey: string;\n  }): AsyncIterableIterator<HiliteSet>;\n\n  /** Disposes the cache. */\n  dispose(): void;\n}\n\n/**\n * Creates a hilite set provider that caches hilite set for current selection for given iModel so any subsequent\n * hilite set requests for the same iModel don't cost until selection in given selection storage changes.\n * @beta\n */\nexport function createCachingHiliteSetProvider(props: CachingHiliteSetProviderProps): CachingHiliteSetProvider {\n  return new CachingHiliteSetProviderImpl(props);\n}\n\nclass CachingHiliteSetProviderImpl implements CachingHiliteSetProvider {\n  private _selectionStorage: SelectionStorage;\n  private _hiliteSetProviders = new Map<string, HiliteSetProvider>();\n  private _cache = new Map<string, Observable<HiliteSet>>();\n  private _removeListener: () => void;\n  private _imodelProvider: (imodelKey: string) => ECSchemaProvider & ECSqlQueryExecutor;\n\n  constructor(props: CachingHiliteSetProviderProps) {\n    this._selectionStorage = props.selectionStorage;\n    this._imodelProvider = props.imodelProvider;\n    this._removeListener = this._selectionStorage.selectionChangeEvent.addListener((args: StorageSelectionChangeEventArgs) => {\n      this._cache.delete(args.imodelKey);\n      if (args.changeType === \"clear\" && args.source === IMODEL_CLOSE_SELECTION_CLEAR_SOURCE) {\n        this._hiliteSetProviders.delete(args.imodelKey);\n      }\n    });\n  }\n\n  public getHiliteSet({ imodelKey }: { imodelKey: string }): AsyncIterableIterator<HiliteSet> {\n    const imodelAccess = this._imodelProvider(imodelKey);\n    const provider = this.getHiliteSetProvider(imodelKey, imodelAccess);\n    let hiliteSet = this._cache.get(imodelKey);\n\n    if (!hiliteSet) {\n      const selectables = this._selectionStorage.getSelection({ imodelKey });\n      hiliteSet = from(provider.getHiliteSet({ selectables })).pipe(shareReplay({ refCount: true }));\n      this._cache.set(imodelKey, hiliteSet);\n    }\n\n    return eachValueFrom(hiliteSet);\n  }\n\n  public dispose(): void {\n    this._removeListener();\n    this._hiliteSetProviders = new Map();\n    this._cache = new Map();\n  }\n\n  private getHiliteSetProvider(imodelKey: string, imodelAccess: ECSchemaProvider & ECSqlQueryExecutor) {\n    let provider = this._hiliteSetProviders.get(imodelKey);\n    if (!provider) {\n      provider = createHiliteSetProvider({ imodelAccess });\n      this._hiliteSetProviders.set(imodelKey, provider);\n    }\n    return provider;\n  }\n}\n"]}

package/lib/cjs/unified-selection/EnableUnifiedSelectionSyncWithIModel.d.ts

@@ -0,0 +1,90 @@
+import { ECSchemaProvider, ECSqlQueryExecutor } from "@itwin/presentation-shared";
+import { CachingHiliteSetProvider } from "./CachingHiliteSetProvider";
+import { ComputeSelectionProps } from "./SelectionScope";
+import { SelectionStorage } from "./SelectionStorage";
+import { CoreIModelHiliteSet, CoreIModelSelectionSet } from "./types/IModel";
+/**
+ * Props for `enableUnifiedSelectionSyncWithIModel`.
+ * @internal Not exported through barrel, but used in public API as an argument. May be supplemented with optional attributes any time.
+ */
+export interface EnableUnifiedSelectionSyncWithIModelProps {
+    /**
+     * Provides access to different iModel's features: query executing, metadata access, selection and hilite sets.
+     * It's recommended to use `@itwin/presentation-core-interop` to create `ECSqlQueryExecutor` and `ECSchemaProvider` from
+     * [IModelConnection](https://www.itwinjs.org/reference/core-frontend/imodelconnection/imodelconnection/) and map its `key`,
+     * `hilited` and `selectionSet` attributes like this:
+     *
+     * ```ts
+     * import { createECSqlQueryExecutor, createECSchemaProvider } from "@itwin/presentation-core-interop";
+     * import { IModelConnection } from "@itwin/core-frontend";
+     *
+     * const imodel: IModelConnection = ...
+     * const imodelAccess = {
+     *   ...createECSqlQueryExecutor(imodel),
+     *   ...createECSchemaProvider(MyAppFrontend.getSchemaContext(imodel)),
+     *   key: imodel.key,
+     *   hiliteSet: imodel.hilited,
+     *   selectionSet: imodel.selectionSet,
+     * };
+     * ```.
+     */
+    imodelAccess: ECSqlQueryExecutor & ECSchemaProvider & {
+        /** Key of the iModel. Generally taken from `IModelConnection.key`. */
+        readonly key: string;
+        /** The set of currently hilited elements taken from `IModelConnection.hilited`. */
+        readonly hiliteSet: CoreIModelHiliteSet;
+        /** The set of currently selected elements taken from `IModelConnection.selectionSet`. */
+        readonly selectionSet: CoreIModelSelectionSet;
+    };
+    /** Selection storage to synchronize IModel's tool selection with. */
+    selectionStorage: SelectionStorage;
+    /** Active scope provider. */
+    activeScopeProvider: () => ComputeSelectionProps["scope"];
+    /**
+     * A caching hilite set provider used to retrieve hilite sets for an iModel. If not provided, a new `CachingHiliteSetProvider`
+     * will be created for the given iModel using the provided `imodelAccess`.
+     * If the consuming application already has a `CachingHiliteSetProvider` defined, it should be provided instead
+     * to reuse the cache and avoid creating new providers for each iModel.
+     */
+    cachingHiliteSetProvider?: CachingHiliteSetProvider;
+}
+/**
+ * Enables synchronization between iModel selection and unified selection.
+ * @returns function for disposing the synchronization.
+ * @beta
+ */
+export declare function enableUnifiedSelectionSyncWithIModel(props: EnableUnifiedSelectionSyncWithIModelProps): () => void;
+/**
+ * A handler that syncs selection between unified selection storage
+ * (`SelectionStorage`) and an iModel (`iModel.selectionSet`, `iModel.hilited`).
+ * @internal
+ */
+export declare class IModelSelectionHandler {
+    private _selectionSourceName;
+    private _imodelAccess;
+    private _selectionStorage;
+    private _hiliteSetProvider;
+    private _cachingHiliteSetProvider;
+    private _activeScopeProvider;
+    private _isSuspended;
+    private _cancelOngoingChanges;
+    private _unifiedSelectionListenerDisposeFunc;
+    private _imodelListenerDisposeFunc;
+    private _hasCustomCachingHiliteSetProvider;
+    constructor(props: EnableUnifiedSelectionSyncWithIModelProps);
+    dispose(): void;
+    /** Temporarily suspends tool selection synchronization until the returned `IDisposable` is disposed. */
+    suspendIModelToolSelectionSync(): {
+        dispose: () => boolean;
+    };
+    private handleUnifiedSelectionChange;
+    private onUnifiedSelectionChanged;
+    private applyCurrentHiliteSet;
+    private addHiliteSet;
+    private removeHiliteSet;
+    private onIModelSelectionChanged;
+    private handleIModelSelectionChange;
+    private getSelectionSetChangeIds;
+    private idArgToIds;
+}
+//# sourceMappingURL=EnableUnifiedSelectionSyncWithIModel.d.ts.map

package/lib/cjs/unified-selection/EnableUnifiedSelectionSyncWithIModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnableUnifiedSelectionSyncWithIModel.d.ts","sourceRoot":"","sources":["../../../src/unified-selection/EnableUnifiedSelectionSyncWithIModel.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,wBAAwB,EAAkC,MAAM,4BAA4B,CAAC;AAItG,OAAO,EAAoB,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAA0D,MAAM,gBAAgB,CAAC;AAErI;;;GAGG;AACH,MAAM,WAAW,yCAAyC;IACxD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,EAAE,kBAAkB,GAC9B,gBAAgB,GAAG;QACjB,sEAAsE;QACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,mFAAmF;QACnF,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;QACxC,yFAAyF;QACzF,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAAC;KAC/C,CAAC;IAEJ,qEAAqE;IACrE,gBAAgB,EAAE,gBAAgB,CAAC;IAEnC,6BAA6B;IAC7B,mBAAmB,EAAE,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE1D;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,yCAAyC,GAAG,MAAM,IAAI,CAGjH;AAED;;;;GAIG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,oBAAoB,CAAU;IAEtC,OAAO,CAAC,aAAa,CAA4D;IACjF,OAAO,CAAC,iBAAiB,CAAmB;IAC5C,OAAO,CAAC,kBAAkB,CAAoB;IAC9C,OAAO,CAAC,yBAAyB,CAA2B;IAC5D,OAAO,CAAC,oBAAoB,CAAuC;IAEnE,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,qBAAqB,CAAuB;IACpD,OAAO,CAAC,oCAAoC,CAAa;IACzD,OAAO,CAAC,0BAA0B,CAAa;IAC/C,OAAO,CAAC,kCAAkC,CAAU;gBAEjC,KAAK,EAAE,yCAAyC;IAuB5D,OAAO;IASd,wGAAwG;IACjG,8BAA8B;;;IAQrC,OAAO,CAAC,4BAA4B;IA6BpC,OAAO,CAAC,yBAAyB,CAU/B;IAEF,OAAO,CAAC,qBAAqB;IAmB7B,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,wBAAwB,CAa9B;YAEY,2BAA2B;IAiBzC,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,UAAU;CASnB"}