@itwin/unified-selection/CHANGELOG.md

Package for managing unified selection in iTwin.js applications.

# @itwin/unified-selection

## 1.7.5

### Patch Changes

- [#1358](https://github.com/iTwin/presentation/pull/1358): Bump dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.14

## 1.7.4

### Patch Changes

- [#1353](https://github.com/iTwin/presentation/pull/1353): `HiliteSetProvider`: Fix transient elements not being included in the hilite set and causing an error. Transient element keys are now correctly recognized and emitted without querying the iModel for class hierarchy information.

## 1.7.3

### Patch Changes

- [#1338](https://github.com/iTwin/presentation/pull/1338): Bump iTwin.js core dependencies to `^5.9.1`.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.13

## 1.7.2

### Patch Changes

- [#1330](https://github.com/iTwin/presentation/pull/1330): `computeSelection`: Yield transient element IDs as selectable instance keys with the `TRANSIENT_ELEMENT_CLASSNAME` class name, instead of silently dropping them. This ensures transient selections are preserved in the computed selection result.

## 1.7.1

### Patch Changes

- [#1313](https://github.com/iTwin/presentation/pull/1313): Bump dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.12

## 1.7.0

### Minor Changes

- [#1285](https://github.com/iTwin/presentation/pull/1285): Make `imodelKey` prop optional when calling `SelectionStorage` methods.

  While the package is designed to work with iModels' selection as the first class citizen, it can be used in other contexts as well. In those cases, the `imodelKey` prop is not relevant and should not be required. This change makes it optional and defaults to an empty string when not supplied.

### Patch Changes

- [#1286](https://github.com/iTwin/presentation/pull/1286): Bump dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.11

## 1.6.8

### Patch Changes

- [#1242](https://github.com/iTwin/presentation/pull/1242): Bump dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.10

## 1.6.7

### Patch Changes

- [#1215](https://github.com/iTwin/presentation/pull/1215): Update dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.9

## 1.6.6

### Patch Changes

- [#1208](https://github.com/iTwin/presentation/pull/1208): Bump dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.8

## 1.6.5

### Patch Changes

- [#1168](https://github.com/iTwin/presentation/pull/1168): Bump dependencies.
- [#1161](https://github.com/iTwin/presentation/pull/1161): Bump iTwin.js dependencies to `^5.5.0`.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.7

## 1.6.4

### Patch Changes

- [#1152](https://github.com/iTwin/presentation/pull/1152): Bump dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.6

## 1.6.3

### Patch Changes

- [#1139](https://github.com/iTwin/presentation/pull/1139): Bump dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.5

## 1.6.2

### Patch Changes

- [#1124](https://github.com/iTwin/presentation/pull/1124): Bump dependencies.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.4

## 1.6.1

### Patch Changes

- [#1088](https://github.com/iTwin/presentation/pull/1088): Fix restart tokens not being unique when they need to, causing queries to be cancelled.

## 1.6.0

### Minor Changes

- [#1083](https://github.com/iTwin/presentation/pull/1083): Added optional `componentId` to `ComputeSelectionProps`. This id is used as part of a `restartToken` when executing ECSQL queries inside the function. Restart token is used to cancel duplicate queries. The provided `componentId` should be unique and not shared across different components.

## 1.5.2

### Patch Changes

- [#1077](https://github.com/iTwin/presentation/pull/1077): Fix `enableUnifiedSelectionSyncWithIModel` not updating selection & hilite sets, after selection set is changed directly in a way that doesn't cause a selection storage change.

  A specific example:

  1. `enableUnifiedSelectionSyncWithIModel` is set up to use `assembly` selection scope.
  2. User clicks on an assembly part in the graphics view, causing its parent element (assembly) to be added to selection storage, and selection & hilite sets to be updated with all assembly parts.
  3. User clicks on another part of the same assembly, causing selection storage to remain unchanged (still contains the assembly), and selection & hilite sets to NOT be updated with all assembly parts. As a result, the latter sets now contain only the newly clicked part, which is incorrect.

## 1.5.1

### Patch Changes

- [#1039](https://github.com/iTwin/presentation/pull/1039): Bump iTwin.js core dependencies to `^5.1.1`.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.3

## 1.5.0

### Minor Changes

- [#1018](https://github.com/iTwin/presentation/pull/1018): Fixed `enableUnifiedSelectionSyncWithIModel` not using (and not being able to use) the underlying hilite set provider of the given custom `CachingHiliteSetProvider`, causing selection synchronization to work incorrectly in cases when items were added or removed to iModel's selection set.

  - Introduced `IModelHiliteSetProvider` interface and a factory function `createIModelHiliteSetProvider` that creates an instance of it. Functionality-wise these are very similar to `CachingHiliteSetProvider` and `createCachingHiliteSetProvider` but the new type provides access to the underlying hilite set provider of the given iModel. And the naming better represents the purpose of the type.
  - Deprecated `CachingHiliteSetProvider` and `createCachingHiliteSetProvider` in favor of the above.
  - For the `enableUnifiedSelectionSyncWithIModel` function, deprecated the `cachingHiliteSetProvider` prop in favor of the newly added `imodelHiliteSetProvider`.

  The migration is straightforward:

  ```typescript
  // before:
  enableUnifiedSelectionSyncWithIModel({
    imodelAccess,
    selectionStorage,
    activeScopeProvider,
    cachingHiliteSetProvider: createCachingHiliteSetProvider({
      selectionStorage,
      imodelProvider: () => imodelAccess,
      createHiliteSetProvider: () =>
        createMyCustomHiliteSetProvider({ imodelAccess }),
    }),
  });

  // after:
  enableUnifiedSelectionSyncWithIModel({
    imodelAccess,
    selectionStorage,
    activeScopeProvider,
    imodelHiliteSetProvider: createIModelHiliteSetProvider({
      selectionStorage,
      imodelProvider: () => imodelAccess,
      createHiliteSetProvider: () =>
        createMyCustomHiliteSetProvider({ imodelAccess }),
    }),
  });
  ```

## 1.4.2

### Patch Changes

- [#982](https://github.com/iTwin/presentation/pull/982): Update itwinjs-core dependencies to v5.0.0
- Updated dependencies:
  - @itwin/presentation-shared@1.2.2

## 1.4.1

### Patch Changes

- [#909](https://github.com/iTwin/presentation/pull/909): Do not use `dev` versions of `@itwin/*` packages.
- Updated dependencies:
  - @itwin/presentation-shared@1.2.1

## 1.4.0

### Minor Changes

- [#901](https://github.com/iTwin/presentation/pull/901): Export `SelectionScope` type to make it easier for consumers to define "active scope" type.

  APIs that use this type:

  - The `scope` prop of `computeSelection` function.
  - Return type of `activeScopeProvider` callback prop of `enableUnifiedSelectionSyncWithIModel` function.

- [#895](https://github.com/iTwin/presentation/pull/895): `createCachingHiliteSetProvider`: Added a `createHiliteSetProvider` prop to allow using custom hilite sets for given iModel selections.

### Patch Changes

- [#884](https://github.com/iTwin/presentation/pull/884): Fix `enableUnifiedSelectionSyncWithIModel` not properly syncing `SelectionSet` and `SelectionStorage` with 4.x `itwinjs-core`.

  When the selection change was made by a tool in graphics view (through the `SelectionSet`), the `SelectionStorage` was updated correctly, but the `IModelConnection.hiliteSet` - wasn't. As a result, clearing selection through graphics view wouldn't clear the hilite set and keep the elements hilited.

## 1.3.0

### Minor Changes

- [#841](https://github.com/iTwin/presentation/pull/841): Add `Selectables.load` function to load instance keys from the `Selectables` object.

  Example usage:

  ```ts
  const selectables = Selectables.create([
    // add instance key
    { className: "BisCore:Element", id: "0x1" },

    // add custom selectable
    {
      identifier: "custom",
      async *loadInstanceKeys() {
        yield { className: "BisCore:Element", id: "0x2" };
      },
    },
  ]);

  // logs: { className: "BisCore:Element", id: "0x1" }, { className: "BisCore:Element", id: "0x2" }
  for await (const key of Selectables.load(selectables)) {
    console.log(key);
  }
  ```

## 1.2.1

### Patch Changes

- [#828](https://github.com/iTwin/presentation/pull/828): Polyfill `Symbol.dispose` and `Symbol.asyncDispose` to make sure that code using the upcoming JS recource management API works in all environments.

## 1.2.0

### Minor Changes

- [#800](https://github.com/iTwin/presentation/pull/800): Add support for Models and SubCategories selection that's going to be available in `@itwin/core-frontend` version `5`.

  The changes in `@itwin/core-frontend` allow us to stop manually syncing `HiliteSet` with `SelectionSet` and rely on automatic syncing instead.

- [#800](https://github.com/iTwin/presentation/pull/800): `computeSelection`: Broadened the type of `elementIds` prop from `Id64String[]` to `Id64Arg`.
- [#802](https://github.com/iTwin/presentation/pull/802): Prefer `Symbol.dispose` over `dispose` for disposable objects.

  The package contained a number of types for disposable objects, that had a requirement of `dispose` method being called on them after they are no longer needed. In conjunction with the `using` utility from `@itwin/core-bentley`, usage of such objects looked like this:

  ```ts
  class MyDisposable() {
    dispose() {
      // do some cleanup
    }
  }
  using(new MyDisposable(), (obj) => {
    // do something with obj, it'll get disposed when the callback returns
  });
  ```

  In version `5.2`, TypeScript [introduced](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management) `Disposable` type and `using` declarations (from the upcoming [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) feature in ECMAScript). Now we're making use of those new utilities in this package (while still supporting the old `dispose` method), which allows using `MyDisposable` from the above snippet like this:

  ```ts
  using obj = new MyDisposable();
  // do something with obj, it'll get disposed when it goes out of scope
  ```

## 1.1.2

### Patch Changes

- Updated dependencies:
  - @itwin/presentation-shared@1.2.0

## 1.1.1

### Patch Changes

- [#765](https://github.com/iTwin/presentation/pull/765): Fixed transient element keys handling in unified selection storage.

## 1.1.0

### Minor Changes

- [#740](https://github.com/iTwin/presentation/pull/740): Define `type` and `exports` attributes in `package.json`.

  The change moves this package a step closer towards dropping CommonJS support - it's now transpiled from ESM to CommonJS instead of the opposite.

  In addition, the `exports` attribute has been added to `package.json` to prohibit access to APIs that are not intended to be used by external consumers.

### Patch Changes

- [#758](https://github.com/iTwin/presentation/pull/758): Promote `@beta` APIs to `@public`.
- Updated dependencies:
  - @itwin/presentation-shared@1.1.0

## 1.0.1

### Patch Changes

- [#730](https://github.com/iTwin/presentation/pull/730): Fix provider returned by `createHiliteSetProvider` in some cases not caching class hierarchy check results, resulting in duplicate checks for the same classes.

## 1.0.0

### Major Changes

- [#727](https://github.com/iTwin/presentation/pull/727): 1.0 release.

  The APIs are now considered stable and ready for production use.

### Patch Changes

- Updated dependencies:
  - @itwin/presentation-shared@1.0.0

## 0.5.1

### Patch Changes

- Updated dependencies:
  - @itwin/presentation-shared@0.5.0

## 0.5.0

### Minor Changes

- [#693](https://github.com/iTwin/presentation/pull/693): Selection events API cleanup:
  - Remove the second `StorageSelectionChangesListener` argument, which represented the `SelectionStorage` where the selection change happened. As a replacement, added it as a property to `StorageSelectionChangeEventArgs`, which is the first and now the only argument of the listener.
  - Remove `SelectionChangeEvent` interface in favor of `Event<StorageSelectionChangesListener>`.

### Patch Changes

- [#693](https://github.com/iTwin/presentation/pull/693): API documentation improvements:

  - Add warnings to interfaces which are not supposed to be extended or implemented by consumers. Objects of such interfaces are only supposed to be created by functions in this package. As such, adding required members to these interfaces is not considered a breaking change.
  - Changed `string` to `Id64String` where appropriate, to make it clear that the string is expected to be a valid Id64 string. Note that this is not a breaking change, as `Id64String` is just a type alias for `string`.

- [#695](https://github.com/iTwin/presentation/pull/695): Bump `iTwin.js` core package dependency versions to `4.8.0`
- Updated dependencies:
  - @itwin/presentation-shared@0.4.1

## 0.4.6

### Patch Changes

- Updated dependencies:
  - @itwin/presentation-shared@0.4.0

## 0.4.5

### Patch Changes

- [#657](https://github.com/iTwin/presentation/pull/657): Updated `enableUnifiedSelectionSyncWithIModel` to batch iModel selection changes before synchronizing with `SelectionStorage`.
- [#655](https://github.com/iTwin/presentation/pull/655): Remove exposed internal APIs.
- Updated dependencies:
  - @itwin/presentation-shared@0.3.2

## 0.4.4

### Patch Changes

- Updated dependencies:
  - @itwin/presentation-shared@0.3.1

## 0.4.3

### Patch Changes

- Updated dependencies:
  - @itwin/presentation-shared@0.3.0

## 0.4.2

### Patch Changes

- [#581](https://github.com/iTwin/presentation/pull/581): Bump `itwinjs-core` dependencies to `^4.6.0`
- [#570](https://github.com/iTwin/presentation/pull/570): Reduced main thread blocking when computing hilite sets and selection based on selection scope.
- Updated dependencies:
  - @itwin/presentation-shared@0.2.0

## 0.4.1

### Patch Changes

- Updated dependencies:
  - @itwin/presentation-shared@0.1.1

## 0.4.0

### Minor Changes

- [#558](https://github.com/iTwin/presentation/pull/558): Switched from `ECSchemaProvider` to `ECClassHierarchyInspector`, where appropriate.

  Some of the APIs were accepting `ECSchemaProvider` as a parameter and used it to only inspect class hierarchy. This change switches them to accept `ECClassHierarchyInspector` instead - this reduces the surface area of the API and makes it more clear that only class hierarchy is being inspected, while also possibly improving performance.

  This is a breaking change for the following APIs:

  - `createHiliteSetProvider` prop `imodelAccess`.
  - `createCachingHiliteSetProvider` prop `imodelProvider`.
  - `enableUnifiedSelectionSyncWithIModel` prop `imodelAccess`.

  Migration example:

  ```ts
  import {
    createECSqlQueryExecutor,
    createECSchemaProvider,
  } from "@itwin/presentation-core-interop";
  import { createCachingECClassHierarchyInspector } from "@itwin/presentation-shared";
  import { createHiliteSetProvider } from "@itwin/unified-selection";

  // before:
  const hiliteProvider = createHiliteSetProvider({
    imodelAccess: {
      ...createECSqlQueryExecutor(imodel),
      ...createECSchemaProvider(MyAppFrontend.getSchemaContext(imodel)),
    },
  });

  // after:
  const hiliteProvider = createHiliteSetProvider({
    imodelAccess: {
      ...createECSqlQueryExecutor(imodel),
      ...createCachingECClassHierarchyInspector({
        schemaProvider: createECSchemaProvider(
          MyAppFrontend.getSchemaContext(imodel)
        ),
        cacheSize: 100,
      }),
    },
  });
  ```

### Patch Changes

- [#557](https://github.com/iTwin/presentation/pull/557): Fixed `computeSelection` returning duplicate selectables when using `Functional` selection scope and non-3D elements.

## 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

- [#491](https://github.com/iTwin/presentation/pull/491): Initial package release.