@itwin/unified-selection - npm Package Compare versions

Comparing version 0.4.6 to 0.5.0

CHANGELOG.md

 # @itwin/unified-selection
 
+## 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
@@ -4,0 +24,0 @@

lib/cjs/unified-selection.d.ts

@@ -7,3 +7,3 @@ export * from "./unified-selection/Selectable";
 export { enableUnifiedSelectionSyncWithIModel } from "./unified-selection/EnableUnifiedSelectionSyncWithIModel";
-export { StorageSelectionChangeType, StorageSelectionChangeEventArgs, StorageSelectionChangesListener, SelectionChangeEvent, } from "./unified-selection/SelectionChangeEvent";
+export { StorageSelectionChangeType, StorageSelectionChangeEventArgs, StorageSelectionChangesListener } from "./unified-selection/SelectionChangeEvent";
 //# sourceMappingURL=unified-selection.d.ts.map

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

@@ -17,2 +17,6 @@ import { ECClassHierarchyInspector, ECSqlQueryExecutor } from "@itwin/presentation-shared";
  *
+ * **Warning:** 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.
+ *
+ * @see `createCachingHiliteSetProvider`
  * @beta
@@ -19,0 +23,0 @@ */

lib/cjs/unified-selection/HiliteSetProvider.d.ts

@@ -0,1 +1,2 @@
+import { Id64String } from "@itwin/core-bentley";
 import { ECClassHierarchyInspector, ECSqlQueryExecutor } from "@itwin/presentation-shared";
@@ -5,9 +6,15 @@ import { Selectables } from "./Selectable";
  * A set of model, subcategory and element ids that can be used for specifying hilite.
+ *
+ * **Warning:** 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.
+ *
  * @see https://www.itwinjs.org/reference/core-frontend/selectionset/hiliteset/
+ * @see `HiliteSetProvider`
+ * @see `createHiliteSetProvider`
  * @beta
  */
 export interface HiliteSet {
-    models: string[];
-    subCategories: string[];
-    elements: string[];
+    models: Id64String[];
+    subCategories: Id64String[];
+    elements: Id64String[];
 }
@@ -25,4 +32,7 @@ /**
  *
- * @beta Used in public API as a return value. Not expected to be created / extended by package
+ * **Warning:** 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.
+ *
+ * @see `createHiliteSetProvider`
+ * @beta
  */
@@ -29,0 +39,0 @@ export interface HiliteSetProvider {

lib/cjs/unified-selection/Selectable.d.ts

@@ -0,1 +1,2 @@
+import { Id64String } from "@itwin/core-bentley";
 /**
@@ -12,3 +13,10 @@ * ECInstance selectable
 /**
- * A custom selectable
+ * A custom selectable, which has an identifier, knows how to loads its associated selectable instance keys
+ * and has custom data associated with it.
+ *
+ * An example of such selectable could be an instance grouping node:
+ * - `identifier` could be a GUID, associated with the node,
+ * - `loadInstanceKeys` would know how to load grouped instance keys from the node,
+ * - `data` could be set to the node itself.
+ *
  * @beta
@@ -25,3 +33,3 @@ */
 /**
- * A single selectable that identifies something in an iTwin.js application
+ * A single selectable that identifies something that can be selected in an iTwin.js application.
  * @beta
@@ -31,3 +39,3 @@ */
 /**
- * Type of identifier that can be used to identify selectable in storage.
+ * A type of identifier that can be used to identify a selectable in selection storage.
  * @beta
@@ -49,7 +57,7 @@ */
     /**
-     * Map between `SelectableInstanceKey.className` and a set of selected element IDs.
+     * A map between `SelectableInstanceKey.className` and a set of selected instance IDs.
      */
-    instanceKeys: Map<string, Set<string>>;
+    instanceKeys: Map<string, Set<Id64String>>;
     /**
-     * Map between unique identifier of `CustomSelectable` and the selectable itself.
+     * A map between `CustomSelectable.identifier` and the selectable itself.
      */
@@ -56,0 +64,0 @@ custom: Map<string, CustomSelectable>;

lib/cjs/unified-selection/SelectionChangeEvent.d.ts

@@ -19,4 +19,7 @@ import { Selectables } from "./Selectable";
  *
- * @beta Used in public API as an argument for `StorageSelectionChangesListener`. Not expected to be created / extended by package
- * consumers, may be supplemented with required attributes any time.
+ * **Warning:** Used in public API as an input to consumer-supplied callback. Not expected to be created / extended
+ * by package consumers, may be supplemented with required attributes any time.
+ *
+ * @see `StorageSelectionChangesListener`
+ * @beta
  */
@@ -39,4 +42,6 @@ export interface StorageSelectionChangeEventArgs {
     iModelKey: string;
-    /** The timestamp of when the selection change happened */
+    /** The timestamp of when the selection change happened. */
     timestamp: Date;
+    /** The selection storage where the event happened. */
+    storage: SelectionStorage;
 }
@@ -47,50 +52,7 @@ /**
  */
-export declare type StorageSelectionChangesListener = (args: StorageSelectionChangeEventArgs, storage: SelectionStorage) => void;
-/**
- * An interface that allows subscribing and unsubscribing listeners that
- * are called when a selection has changed.
- * @beta
- */
-export interface SelectionChangeEvent {
-    /**
-     * Registers a Listener to be executed whenever this event is raised
-     * @param listener The function to be executed when the event is raised
-     * @returns A function that will remove this event listener
-     * @beta
-     */
-    addListener(listener: StorageSelectionChangesListener): () => void;
-    /**
-     * Un-register a previously registered listener
-     * @param listener The listener to be unregistered
-     * @beta
-     */
-    removeListener(listener: StorageSelectionChangesListener): void;
-}
-/**
- * An event broadcasted on selection changes.
- * @internal
- */
-export declare class SelectionChangeEventImpl implements SelectionChangeEvent {
-    private _listeners;
-    /**
-     * Registers a Listener to be executed whenever this event is raised
-     * @param listener The function to be executed when the event is raised
-     * @returns A function that will remove this event listener
-     * @beta
-     */
-    addListener(listener: StorageSelectionChangesListener): () => void;
-    /**
-     * Un-register a previously registered listener
-     * @param listener The listener to be unregistered
-     * @beta
-     */
-    removeListener(listener: StorageSelectionChangesListener): void;
-    /**
-     * Raises the event by calling each registered listener with the supplied arguments
-     * @param args Event arguments
-     * @param storage Storage that the selection changed in
-     * @beta
-     */
-    raiseEvent(args: StorageSelectionChangeEventArgs, storage: SelectionStorage): void;
-}
+export type StorageSelectionChangesListener = (
+/** Arguments for the selection change event */
+args: StorageSelectionChangeEventArgs, 
+/** Unused. Temporarily left to avoid a breaking change. */
+_?: any) => void;
 //# sourceMappingURL=SelectionChangeEvent.d.ts.map

lib/cjs/unified-selection/SelectionChangeEvent.js

@@ -7,38 +7,2 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SelectionChangeEventImpl = void 0;
-/**
- * An event broadcasted on selection changes.
- * @internal
- */
-class SelectionChangeEventImpl {
-    _listeners = [];
-    /**
-     * Registers a Listener to be executed whenever this event is raised
-     * @param listener The function to be executed when the event is raised
-     * @returns A function that will remove this event listener
-     * @beta
-     */
-    addListener(listener) {
-        this._listeners.push(listener);
-        return () => this.removeListener(listener);
-    }
-    /**
-     * Un-register a previously registered listener
-     * @param listener The listener to be unregistered
-     * @beta
-     */
-    removeListener(listener) {
-        this._listeners = this._listeners.filter((x) => x !== listener);
-    }
-    /**
-     * Raises the event by calling each registered listener with the supplied arguments
-     * @param args Event arguments
-     * @param storage Storage that the selection changed in
-     * @beta
-     */
-    raiseEvent(args, storage) {
-        this._listeners.forEach((listener) => listener(args, storage));
-    }
-}
-exports.SelectionChangeEventImpl = SelectionChangeEventImpl;
 //# sourceMappingURL=SelectionChangeEvent.js.map

lib/cjs/unified-selection/SelectionStorage.d.ts

@@ -0,3 +1,4 @@
+import { Event } from "@itwin/presentation-shared";
 import { Selectable, Selectables } from "./Selectable";
-import { SelectionChangeEvent } from "./SelectionChangeEvent";
+import { StorageSelectionChangesListener } from "./SelectionChangeEvent";
 /** @beta */
@@ -17,8 +18,11 @@ type IModelKeyProp = {
  *
- * @beta Used in public API as a return value. Not expected to be created / extended by package
+ * **Warning:** 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.
+ *
+ * @see `createStorage`
+ * @beta
  */
 export interface SelectionStorage {
     /** An event that is raised when selection changes. */
-    selectionChangeEvent: SelectionChangeEvent;
+    selectionChangeEvent: Event<StorageSelectionChangesListener>;
     /** Get the selection levels currently stored for the specified iModel. */
@@ -72,2 +76,3 @@ getSelectionLevels(props: IModelKeyProp): number[];
  * **Note:** `clearSelection` should be called upon iModel close to free-up memory:
+ *
  * ```ts
@@ -74,0 +79,0 @@ * import { IModelConnection } from "@itwin/core-frontend";

lib/cjs/unified-selection/SelectionStorage.js

@@ -9,4 +9,4 @@ "use strict";
 exports.createStorage = createStorage;
+const core_bentley_1 = require("@itwin/core-bentley");
 const Selectable_1 = require("./Selectable");
-const SelectionChangeEvent_1 = require("./SelectionChangeEvent");
 /**
@@ -16,2 +16,3 @@ * Creates a selection storage which stores and allows managing application-level selection.
  * **Note:** `clearSelection` should be called upon iModel close to free-up memory:
+ *
  * ```ts
@@ -35,3 +36,3 @@ * import { IModelConnection } from "@itwin/core-frontend";
     constructor() {
-        this.selectionChangeEvent = new SelectionChangeEvent_1.SelectionChangeEventImpl();
+        this.selectionChangeEvent = new core_bentley_1.BeEvent();
     }
@@ -109,2 +110,3 @@ getSelectionLevels(props) {
             timestamp: new Date(),
+            storage: this,
         };
@@ -111,0 +113,0 @@ this.selectionChangeEvent.raiseEvent(event, this);

lib/esm/unified-selection.d.ts

@@ -7,3 +7,3 @@ export * from "./unified-selection/Selectable";
 export { enableUnifiedSelectionSyncWithIModel } from "./unified-selection/EnableUnifiedSelectionSyncWithIModel";
-export { StorageSelectionChangeType, StorageSelectionChangeEventArgs, StorageSelectionChangesListener, SelectionChangeEvent, } from "./unified-selection/SelectionChangeEvent";
+export { StorageSelectionChangeType, StorageSelectionChangeEventArgs, StorageSelectionChangesListener } from "./unified-selection/SelectionChangeEvent";
 //# sourceMappingURL=unified-selection.d.ts.map

lib/esm/unified-selection/CachingHiliteSetProvider.d.ts

@@ -17,2 +17,6 @@ import { ECClassHierarchyInspector, ECSqlQueryExecutor } from "@itwin/presentation-shared";
  *
+ * **Warning:** 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.
+ *
+ * @see `createCachingHiliteSetProvider`
  * @beta
@@ -19,0 +23,0 @@ */

lib/esm/unified-selection/HiliteSetProvider.d.ts

@@ -0,1 +1,2 @@
+import { Id64String } from "@itwin/core-bentley";
 import { ECClassHierarchyInspector, ECSqlQueryExecutor } from "@itwin/presentation-shared";
@@ -5,9 +6,15 @@ import { Selectables } from "./Selectable";
  * A set of model, subcategory and element ids that can be used for specifying hilite.
+ *
+ * **Warning:** 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.
+ *
  * @see https://www.itwinjs.org/reference/core-frontend/selectionset/hiliteset/
+ * @see `HiliteSetProvider`
+ * @see `createHiliteSetProvider`
  * @beta
  */
 export interface HiliteSet {
-    models: string[];
-    subCategories: string[];
-    elements: string[];
+    models: Id64String[];
+    subCategories: Id64String[];
+    elements: Id64String[];
 }
@@ -25,4 +32,7 @@ /**
  *
- * @beta Used in public API as a return value. Not expected to be created / extended by package
+ * **Warning:** 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.
+ *
+ * @see `createHiliteSetProvider`
+ * @beta
  */
@@ -29,0 +39,0 @@ export interface HiliteSetProvider {

lib/esm/unified-selection/Selectable.d.ts

@@ -0,1 +1,2 @@
+import { Id64String } from "@itwin/core-bentley";
 /**
@@ -12,3 +13,10 @@ * ECInstance selectable
 /**
- * A custom selectable
+ * A custom selectable, which has an identifier, knows how to loads its associated selectable instance keys
+ * and has custom data associated with it.
+ *
+ * An example of such selectable could be an instance grouping node:
+ * - `identifier` could be a GUID, associated with the node,
+ * - `loadInstanceKeys` would know how to load grouped instance keys from the node,
+ * - `data` could be set to the node itself.
+ *
  * @beta
@@ -25,3 +33,3 @@ */
 /**
- * A single selectable that identifies something in an iTwin.js application
+ * A single selectable that identifies something that can be selected in an iTwin.js application.
  * @beta
@@ -31,3 +39,3 @@ */
 /**
- * Type of identifier that can be used to identify selectable in storage.
+ * A type of identifier that can be used to identify a selectable in selection storage.
  * @beta
@@ -49,7 +57,7 @@ */
     /**
-     * Map between `SelectableInstanceKey.className` and a set of selected element IDs.
+     * A map between `SelectableInstanceKey.className` and a set of selected instance IDs.
      */
-    instanceKeys: Map<string, Set<string>>;
+    instanceKeys: Map<string, Set<Id64String>>;
     /**
-     * Map between unique identifier of `CustomSelectable` and the selectable itself.
+     * A map between `CustomSelectable.identifier` and the selectable itself.
      */
@@ -56,0 +64,0 @@ custom: Map<string, CustomSelectable>;

lib/esm/unified-selection/SelectionChangeEvent.d.ts

@@ -19,4 +19,7 @@ import { Selectables } from "./Selectable";
  *
- * @beta Used in public API as an argument for `StorageSelectionChangesListener`. Not expected to be created / extended by package
- * consumers, may be supplemented with required attributes any time.
+ * **Warning:** Used in public API as an input to consumer-supplied callback. Not expected to be created / extended
+ * by package consumers, may be supplemented with required attributes any time.
+ *
+ * @see `StorageSelectionChangesListener`
+ * @beta
  */
@@ -39,4 +42,6 @@ export interface StorageSelectionChangeEventArgs {
     iModelKey: string;
-    /** The timestamp of when the selection change happened */
+    /** The timestamp of when the selection change happened. */
     timestamp: Date;
+    /** The selection storage where the event happened. */
+    storage: SelectionStorage;
 }
@@ -47,50 +52,7 @@ /**
  */
-export declare type StorageSelectionChangesListener = (args: StorageSelectionChangeEventArgs, storage: SelectionStorage) => void;
-/**
- * An interface that allows subscribing and unsubscribing listeners that
- * are called when a selection has changed.
- * @beta
- */
-export interface SelectionChangeEvent {
-    /**
-     * Registers a Listener to be executed whenever this event is raised
-     * @param listener The function to be executed when the event is raised
-     * @returns A function that will remove this event listener
-     * @beta
-     */
-    addListener(listener: StorageSelectionChangesListener): () => void;
-    /**
-     * Un-register a previously registered listener
-     * @param listener The listener to be unregistered
-     * @beta
-     */
-    removeListener(listener: StorageSelectionChangesListener): void;
-}
-/**
- * An event broadcasted on selection changes.
- * @internal
- */
-export declare class SelectionChangeEventImpl implements SelectionChangeEvent {
-    private _listeners;
-    /**
-     * Registers a Listener to be executed whenever this event is raised
-     * @param listener The function to be executed when the event is raised
-     * @returns A function that will remove this event listener
-     * @beta
-     */
-    addListener(listener: StorageSelectionChangesListener): () => void;
-    /**
-     * Un-register a previously registered listener
-     * @param listener The listener to be unregistered
-     * @beta
-     */
-    removeListener(listener: StorageSelectionChangesListener): void;
-    /**
-     * Raises the event by calling each registered listener with the supplied arguments
-     * @param args Event arguments
-     * @param storage Storage that the selection changed in
-     * @beta
-     */
-    raiseEvent(args: StorageSelectionChangeEventArgs, storage: SelectionStorage): void;
-}
+export type StorageSelectionChangesListener = (
+/** Arguments for the selection change event */
+args: StorageSelectionChangeEventArgs, 
+/** Unused. Temporarily left to avoid a breaking change. */
+_?: any) => void;
 //# sourceMappingURL=SelectionChangeEvent.d.ts.map

lib/esm/unified-selection/SelectionChangeEvent.js

@@ -5,36 +5,3 @@ /*---------------------------------------------------------------------------------------------
  *--------------------------------------------------------------------------------------------*/
-/**
- * An event broadcasted on selection changes.
- * @internal
- */
-export class SelectionChangeEventImpl {
-    _listeners = [];
-    /**
-     * Registers a Listener to be executed whenever this event is raised
-     * @param listener The function to be executed when the event is raised
-     * @returns A function that will remove this event listener
-     * @beta
-     */
-    addListener(listener) {
-        this._listeners.push(listener);
-        return () => this.removeListener(listener);
-    }
-    /**
-     * Un-register a previously registered listener
-     * @param listener The listener to be unregistered
-     * @beta
-     */
-    removeListener(listener) {
-        this._listeners = this._listeners.filter((x) => x !== listener);
-    }
-    /**
-     * Raises the event by calling each registered listener with the supplied arguments
-     * @param args Event arguments
-     * @param storage Storage that the selection changed in
-     * @beta
-     */
-    raiseEvent(args, storage) {
-        this._listeners.forEach((listener) => listener(args, storage));
-    }
-}
+export {};
 //# sourceMappingURL=SelectionChangeEvent.js.map

lib/esm/unified-selection/SelectionStorage.d.ts

@@ -0,3 +1,4 @@
+import { Event } from "@itwin/presentation-shared";
 import { Selectable, Selectables } from "./Selectable";
-import { SelectionChangeEvent } from "./SelectionChangeEvent";
+import { StorageSelectionChangesListener } from "./SelectionChangeEvent";
 /** @beta */
@@ -17,8 +18,11 @@ type IModelKeyProp = {
  *
- * @beta Used in public API as a return value. Not expected to be created / extended by package
+ * **Warning:** 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.
+ *
+ * @see `createStorage`
+ * @beta
  */
 export interface SelectionStorage {
     /** An event that is raised when selection changes. */
-    selectionChangeEvent: SelectionChangeEvent;
+    selectionChangeEvent: Event<StorageSelectionChangesListener>;
     /** Get the selection levels currently stored for the specified iModel. */
@@ -72,2 +76,3 @@ getSelectionLevels(props: IModelKeyProp): number[];
  * **Note:** `clearSelection` should be called upon iModel close to free-up memory:
+ *
  * ```ts
@@ -74,0 +79,0 @@ * import { IModelConnection } from "@itwin/core-frontend";

lib/esm/unified-selection/SelectionStorage.js

@@ -5,4 +5,4 @@ /*---------------------------------------------------------------------------------------------
  *--------------------------------------------------------------------------------------------*/
+import { BeEvent } from "@itwin/core-bentley";
 import { Selectables } from "./Selectable";
-import { SelectionChangeEventImpl } from "./SelectionChangeEvent";
 /**
@@ -12,2 +12,3 @@ * Creates a selection storage which stores and allows managing application-level selection.
  * **Note:** `clearSelection` should be called upon iModel close to free-up memory:
+ *
  * ```ts
@@ -31,3 +32,3 @@ * import { IModelConnection } from "@itwin/core-frontend";
     constructor() {
-        this.selectionChangeEvent = new SelectionChangeEventImpl();
+        this.selectionChangeEvent = new BeEvent();
     }
@@ -105,2 +106,3 @@ getSelectionLevels(props) {
             timestamp: new Date(),
+            storage: this,
         };
@@ -107,0 +109,0 @@ this.selectionChangeEvent.raiseEvent(event, this);

package.json

 {
   "name": "@itwin/unified-selection",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Package for managing unified selection in iTwin.js applications.",
@@ -31,9 +31,9 @@ "license": "MIT",
   "dependencies": {
-    "@itwin/core-bentley": "^4.6.0",
+    "@itwin/core-bentley": "^4.8.0",
     "rxjs": "^7.8.1",
     "rxjs-for-await": "^1.0.0",
-    "@itwin/presentation-shared": "^0.4.0"
+    "@itwin/presentation-shared": "^0.4.1"
   },
   "devDependencies": {
-    "@itwin/build-tools": "^4.7.1",
+    "@itwin/build-tools": "^4.8.0",
     "@itwin/eslint-plugin": "^4.1.1",
@@ -40,0 +40,0 @@ "@types/chai": "^4.3.16",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Worsened metrics

Total package byte prevSize

416436

decreased by-0.96%

Lines of code

3714

decreased by-2.29%

Dependency changes

• Updated@itwin/core-bentley@^4.8.0

• Updated@itwin/presentation-shared@^0.4.1