@cognite/reveal-widget 0.2.0 → 1.48535.0

package/README.md

@@ -9,6 +9,40 @@ This package exposes `RevealWidget` and the types needed to drive it via
 `RevealWidgetController`. More capabilities from the broader Reveal Components toolkit
 will be exposed here incrementally over time.
 
+## Usage tracking (Mixpanel)
+
+`RevealWidget` can report anonymous usage events to a Cognite-owned Mixpanel project. This
+tells us which features of the widget are actually used (loading a resource, styling
+instances, moving the camera, etc.) so we can prioritize development. No event payload
+includes page URLs, referrers, resource IDs, or any other identifying data.
+
+`RevealWidget` requires an `appIdentifier` prop so aggregate usage can be attributed
+correctly. The optional `tracking` prop lets you change where events go:
+
+```tsx
+// Reports to the default Cognite Mixpanel project (the default when `tracking` is omitted).
+<RevealWidget viewerOptions={...} appIdentifier="my-app" />
+
+// Opt out entirely — no events are sent anywhere.
+<RevealWidget viewerOptions={...} appIdentifier="my-app" tracking={{ disabled: true }} />
+
+// Report to your own Mixpanel project instead of Cognite's.
+<RevealWidget
+  viewerOptions={...}
+  appIdentifier="my-app"
+  tracking={{ mixpanelToken: 'your-own-project-token' }}
+/>
+
+// Route events through your own tracking/analytics pipeline instead of Mixpanel.
+<RevealWidget
+  viewerOptions={...}
+  appIdentifier="my-app"
+  tracking={{ usageMetricsTracker: { track: (event, properties) => myOwnTracker(event, properties) } }}
+/>
+```
+
+See `RevealWidgetTrackingProps` for the full set of options.
+
 ## Install
 
 ```bash
@@ -23,7 +57,9 @@ If your bundler doesn't already dedupe singletons across your dependency tree, a
 
 ```ts
 // vite.config.ts
-resolve: { dedupe: ['three', '@cognite/reveal'] }
+resolve: {
+  dedupe: ['three', '@cognite/reveal'];
+}
 ```
 
 ## Usage
@@ -80,7 +116,9 @@ export function ThreeDViewer({
 }) {
   const viewerRef = useRef<ThreeDViewerController>();
 
-  function handleWidgetController(widgetController: RevealWidgetController | undefined) {
+  function handleWidgetController(
+    widgetController: RevealWidgetController | undefined
+  ) {
     viewerRef.current?.dispose();
 
     if (widgetController === undefined) {
@@ -131,24 +169,82 @@ CAD/point cloud/image360 resources resolve to a `Reveal3DResourceHandle` usable
 `styleByInstance`/`getModels()`/`cameraController.focusModel()`; a `'scene'` resource resolves to
 a handle that only supports `.remove()`.
 
+### Loading a scene by location
+
+`controller.addResourceByLocation(location, selectedScene?)` loads the scene configured for a
+location, matched by external ID or name and including its sub-locations. It resolves to a result
+with a `status`:
+
+- `'loaded'`: exactly one scene was found and added; `scene` is its handle
+- `'selection-required'`: several scenes were found and nothing was loaded; `candidates` lists
+  each `{ scene, locationName }`. Call again with the chosen `scene` as `selectedScene`
+- `'not-found'`: no such location, or it has no scene
+
+### Searching mapped assets
+
+`controller.assets.searchMappedAssets({ query?, limit? })` searches the data modeling assets
+mapped to the visible CAD models, point clouds and data model 360 image collections, including
+those of a loaded scene. Classic assets are never searched, so use it with `useCoreDm: true` in
+data-modeling-only projects. `limit` defaults to 100 (maximum 1000). There is no pagination; when
+`hasMore` is true, narrow the search with `query`.
+
+```ts
+const { assets, hasMore } = await controller.assets.searchMappedAssets({
+  query: 'pump',
+});
+await controller.focusInstances([assets[0].instanceId]);
+```
+
+### HTML overlays
+
+`controller.htmlOverlays.add(element, position)` attaches an HTML element to a position in the 3D scene, e.g. to show a notification.
+The element follows the position as the camera moves and is hidden while the position is out of view.
+`position` is `{ x, y, z }` in CDF coordinates, the same ones the coordinates of CDF 3D models and their assets are given in.
+It returns a handle whose `remove()` removes the overlay.
+Removing an overlay right after adding it is safe.
+Adding the same element again moves it to the new position.
+
+The widget sets `position: absolute` on the element, which overlays require.
+Other styling is up to you, e.g. `transform: translate(-50%, -50%)` to center the element on the position, and `pointer-events: none` if it should not interfere with camera navigation.
+
+```ts
+const element = document.createElement('div');
+element.textContent = 'Pump 01 needs attention';
+element.style.transform = 'translate(-50%, -50%)';
+
+const overlay = controller.htmlOverlays.add(element, { x: 10, y: 20, z: 5 });
+
+// Hide or show all overlays without removing them
+controller.htmlOverlays.setVisible(false);
+
+// Remove one overlay, or all of them
+overlay.remove();
+controller.htmlOverlays.clear();
+```
+
+Overlays are removed when the widget unmounts or its controller is replaced.
+
 ### Highlighting instances
 
 Instances (assets) are identified either by classic numeric asset ID or by a data modeling
 `{ externalId, space }` reference:
 
 ```ts
-instanceIds: [1560727417020285]
-instanceIds: [{ externalId: 'CogniteAsset-1022', space: 'my-space' }]
+instanceIds: [1560727417020285];
+instanceIds: [{ externalId: 'CogniteAsset-1022', space: 'my-space' }];
 ```
 
 ### Camera control
 
 ```ts
 controller.cameraController.focusModel(handle); // fit one model
-controller.cameraController.focusCameraAll();     // fit all models
+controller.cameraController.focusCameraAll(); // fit all models
 await controller.focusInstances([someInstanceId]); // zoom to a specific instance
 ```
 
+If the instance is mapped to an annotation in a 360 image, `focusInstances` enters that image
+instead of moving to a bounding box.
+
 ## Cleaning up
 
 Resources added via `addResource` should be removed when no longer needed:

package/dist/index.d.ts

@@ -1,116 +1,274 @@
-import { PropsWithChildren, ReactElement } from 'react';
-import { CameraState, Cognite3DViewerOptions, NodeAppearance } from '@cognite/reveal';
-import { DmsUniqueIdentifier, ExternalId, Space } from '@cognite/reveal-components/data-providers';
-import { AssetId } from '@cognite/reveal-components/data-providers/cache';
-import { AddReveal3DResource, AllResourceIdentifier, BaseAddOptions, CadAddOptions, NewCadModelStyling as CadModelStyling, CadResourceIdentifier, Classic3DResourceIdentifier, DM3DResourceIdentifier, Image360AddOptions, Image360DMResourceIdentifier, Image360EventsResourceIdentifier, Image360IconCullingOptions, Image360ResourceIdentifier, PointCloudAddOptions, PointCloudResourceIdentifier, SceneAddOptions, SceneResourceIdentifier, ThreeDResourceIdentifier } from '@cognite/reveal-components/data-providers/types';
-import { InstanceId } from '@cognite/reveal-components/utilities';
-import { InstanceStylingGroup } from '@cognite/reveal-components/utilities/modelIds';
-import { TreeIndexStylingGroup } from '@cognite/reveal-components/utilities/styling';
-export type { AddReveal3DResource, AllResourceIdentifier, AssetId, BaseAddOptions, CadAddOptions, CadModelStyling, CadResourceIdentifier, Classic3DResourceIdentifier, DM3DResourceIdentifier, DmsUniqueIdentifier, ExternalId, Image360AddOptions, Image360DMResourceIdentifier, Image360EventsResourceIdentifier, Image360IconCullingOptions, Image360ResourceIdentifier, InstanceId, InstanceStylingGroup, PointCloudAddOptions, PointCloudResourceIdentifier, SceneAddOptions, SceneResourceIdentifier, Space, ThreeDResourceIdentifier, TreeIndexStylingGroup, };
+import type { PropsWithChildren, ReactElement } from "react";
+import type { CameraState, Cognite3DViewerOptions, NodeAppearance } from "@cognite/reveal";
+import type { DmsUniqueIdentifier, ExternalId, Space } from "@cognite/reveal-components/data-providers";
+import type { AssetId } from "@cognite/reveal-components/data-providers/cache";
+import type { AddReveal3DResource, AllResourceIdentifier, BaseAddOptions, CadAddOptions, NewCadModelStyling as CadModelStyling, CadResourceIdentifier, Classic3DResourceIdentifier, DM3DResourceIdentifier, Image360AddOptions, Image360DMResourceIdentifier, Image360EventsResourceIdentifier, Image360IconCullingOptions, Image360ResourceIdentifier, PointCloudAddOptions, PointCloudResourceIdentifier, SceneAddOptions, SceneResourceIdentifier, ThreeDResourceIdentifier } from "@cognite/reveal-components/data-providers/types";
+import { type RevealWidgetTrackingProps } from "@cognite/reveal-components/ui/components";
+import type { InstanceId, UsageMetricsTracker } from "@cognite/reveal-components/utilities";
+import type { InstanceStylingGroup } from "@cognite/reveal-components/utilities/modelIds";
+import type { TreeIndexStylingGroup } from "@cognite/reveal-components/utilities/styling";
+export type { AddReveal3DResource, AllResourceIdentifier, AssetId, BaseAddOptions, CadAddOptions, CadModelStyling, CadResourceIdentifier, Classic3DResourceIdentifier, DM3DResourceIdentifier, DmsUniqueIdentifier, ExternalId, Image360AddOptions, Image360DMResourceIdentifier, Image360EventsResourceIdentifier, Image360IconCullingOptions, Image360ResourceIdentifier, InstanceId, InstanceStylingGroup, UsageMetricsTracker, PointCloudAddOptions, PointCloudResourceIdentifier, RevealWidgetTrackingProps, SceneAddOptions, SceneResourceIdentifier, Space, ThreeDResourceIdentifier, TreeIndexStylingGroup };
 /**
- * Public API surface for the standalone `@cognite/reveal-widget` npm package.
- *
- * `RevealWidget` here is the real, unmodified implementation from
- * `@cognite/reveal-components` — there is no runtime wrapper. `@cognite/reveal-components`
- * is a `dependencies` entry (not `devDependencies`), so it and its own published
- * dependencies (`@cognite/signal-utils`, `@cognite/underscore`) are treated as external
- * and resolved as real npm imports rather than bundled into this package's output. The
- * resource/identifier types above are re-exported directly from
- * `@cognite/reveal-components`'s narrow, already-subpath-exported type barrels
- * (`./data-providers/types`, `./utilities/modelIds`, `./utilities`), which an external
- * consumer resolves normally since that package is published.
- *
- * `Reveal3DResourceHandle`, `RevealWidgetController`, `RevealWidgetCameraController`, and
- * `RevealWidgetProps` below are still hand-declared, because their real counterparts (only
- * reachable via the entangled `./ui/components` export) expose `RevealDomainObject`/
- * `SceneDomainObject` directly in their signatures — too large for API Extractor's type bundler
- * and not meaningful for an external consumer anyway. `src/index.test.ts` has compile-time-only
- * (`// @ts-expect-error`-driven) tests asserting these hand-written types stay structurally
- * compatible with the real implementation — update both together when the real API changes.
- */
+* Public API surface for the standalone `@cognite/reveal-widget` npm package.
+*
+* `RevealWidget` here is the real, unmodified implementation from
+* `@cognite/reveal-components` — there is no runtime wrapper. `@cognite/reveal-components`
+* is a `dependencies` entry, so it and its own published dependencies (`@cognite/signal-utils`,
+* `@cognite/underscore`) are treated as external. The resource/identifier types above are
+* re-exported directly from `@cognite/reveal-components`'s narrow, already-subpath-exported
+* type barrels (`./data-providers/types`, `./utilities/modelIds`, `./utilities`), which an
+* external consumer resolves normally since that package is published.
+*
+* `Reveal3DResourceHandle`, `RevealWidgetController`, `RevealWidgetCameraController`, `RevealWidgetAssets`, `RevealWidgetHtmlOverlays`, and
+* `RevealWidgetProps` below are still hand-declared, because their real counterparts (only
+* reachable via the entangled `./ui/components` export) expose `RevealDomainObject`/
+* `SceneDomainObject` directly in their signatures — too large for API Extractor's type bundler
+* and not meaningful for an external consumer anyway. `src/index.test.ts` has compile-time-only
+* (`// @ts-expect-error`-driven) tests asserting these hand-written types stay structurally
+* compatible with the real implementation — update both together when the real API changes.
+* `RevealWidgetTrackingProps` (and its arms) don't have this problem — they only reference
+* `UsageMetricsTracker`, so they're imported and re-exported directly from `./ui/components`
+* rather than hand-declared.
+*
+* `tracking`/`appIdentifier` (on `RevealWidgetProps`) plumb through to the real `RevealWidget`'s
+* usage-tracking seam, which reports to a dedicated, named `mixpanel-browser` instance *by
+* default* — not Fusion's own `@cognite/metrics`/Mixpanel setup, since `@cognite/reveal-widget`
+* is also consumed outside this monorepo. Pass `tracking: { disabled: true }` to opt out
+* entirely, or `tracking: { mixpanelToken }` (with `appIdentifier`) to report to your own
+* Mixpanel project instead.
+*/
 export declare const Default3DStyles: {
-    Highlighted: {
-        cad: NodeAppearance;
-        pointcloud: NodeAppearance;
-        image360: NodeAppearance;
-    };
+	Highlighted: {
+		cad: NodeAppearance;
+		pointcloud: NodeAppearance;
+		image360: NodeAppearance;
+	};
 };
 /**
- * A narrow, external-facing view of a loaded 3D resource (CAD model, point cloud, image360
- * collection, or scene). This is a type-only narrowing — the actual object returned at runtime
- * by `addResource()`/`getModels()` is still the real `RevealDomainObject`/`SceneDomainObject`.
- * Only `.remove()` is published here to keep the exported type surface minimal.
- */
+* A narrow, external-facing view of a loaded 3D resource (CAD model, point cloud, image360
+* collection, or scene). This is a type-only narrowing — the actual object returned at runtime
+* by `addResource()`/`getModels()` is still the real `RevealDomainObject`/`SceneDomainObject`.
+* Only `.remove()` is published here to keep the exported type surface minimal.
+*/
 export type Reveal3DResourceHandle = {
-    remove(): boolean;
+	remove(): boolean;
+};
+/**
+* A scene that can be loaded for a location, and the (sub-)location it is
+* configured on.
+*/
+export type LocationSceneCandidate = {
+	scene: DmsUniqueIdentifier;
+	locationName: string;
+};
+/**
+* Outcome of `RevealWidgetController.addResourceByLocation`:
+* - `loaded`: the scene was added to the widget
+* - `selection-required`: the location has several scenes (its own and those of
+*   its sub-locations); nothing was loaded, call again with the chosen scene
+* - `not-found`: no such location, or it has no scene
+*/
+export type AddResourceByLocationResult = SceneLoadedForLocation | SceneSelectionRequiredForLocation | SceneNotFoundForLocation;
+export type SceneLoadedForLocation = {
+	status: "loaded";
+	scene: Reveal3DResourceHandle;
+};
+export type SceneSelectionRequiredForLocation = {
+	status: "selection-required";
+	candidates: LocationSceneCandidate[];
+};
+export type SceneNotFoundForLocation = {
+	status: "not-found";
+};
+/**
+* An asset that is mapped to a loaded 3D model.
+*/
+export type MappedAsset = {
+	name: string;
+	description?: string;
+	/** Pass to `styleByInstance` / `focusInstances` to highlight or zoom to the asset */
+	instanceId: InstanceId;
+};
+/**
+* Options for `RevealWidgetAssets.searchMappedAssets`.
+*/
+export type SearchMappedAssetsOptions = {
+	/**
+	* Free-text search on the asset name and description. Not guaranteed to
+	* return all matching assets.
+	*/
+	query?: string;
+	/** Maximum number of assets to return (default 100, maximum 1000) */
+	limit?: number;
+};
+/**
+* Result of `RevealWidgetAssets.searchMappedAssets`.
+*/
+export type SearchMappedAssetsResult = {
+	assets: MappedAsset[];
+	/**
+	* True if there may be more matching assets than were returned. Pagination is
+	* not supported, so use `query` to narrow down the search.
+	*/
+	hasMore: boolean;
+};
+/**
+* Search for the assets mapped to the models in the widget.
+*/
+export type RevealWidgetAssets = {
+	/**
+	* Search the core data model assets that are mapped to the visible CAD models,
+	* point clouds and data model 360 image collections, including those of a
+	* loaded scene. Only data modeling assets are searched, never classic assets,
+	* so this is intended for data-modeling-only projects. Use the returned
+	* `instanceId`s with `styleByInstance` and `focusInstances` to highlight an
+	* asset and zoom to it.
+	*/
+	searchMappedAssets(options?: SearchMappedAssetsOptions): Promise<SearchMappedAssetsResult>;
+};
+/**
+* A position in the CDF coordinate system, i.e. the one the coordinates of
+* CDF 3D models and their assets are given in
+*/
+export type HtmlOverlayPosition = {
+	x: number;
+	y: number;
+	z: number;
+};
+/**
+* A handle to an HTML overlay added to the widget
+*/
+export type HtmlOverlayHandle = {
+	/**
+	* Removes the overlay's element from the widget. Does nothing if
+	* it has already been removed.
+	*/
+	remove(): void;
+};
+/**
+* Attaching HTML elements to positions in the 3D scene of the widget,
+* e.g. to show notifications.
+*/
+export type RevealWidgetHtmlOverlays = {
+	/**
+	* Attaches an HTML element to a position in the scene. The element follows the
+	* position as the camera moves, and is hidden while the position is not in view.
+	*
+	* The widget sets `position: absolute` on the element, which the overlay requires.
+	* Styling such as `transform: translate(-50%, -50%)` to center the element on the
+	* position, and `pointer-events: none` to not interfere with camera navigation,
+	* is up to the caller.
+	*
+	* ```
+	* const overlay = controller.htmlOverlays.add(element, { x: 10, y: 20, z: 5 });
+	*
+	* // during cleanup:
+	* overlay.remove();
+	* ```
+	*
+	* @param element The element to attach. Adding the same element again moves it.
+	* @param position The position in CDF coordinates
+	*/
+	add(element: HTMLElement, position: HtmlOverlayPosition): HtmlOverlayHandle;
+	/**
+	* Removes all the overlays added to the widget
+	*/
+	clear(): void;
+	/**
+	* Hides or shows all the overlays, including ones added later. They are visible by default.
+	*/
+	setVisible(visible: boolean): void;
 };
 export type RevealWidgetCameraController = {
-    /**
-     * Focus all visible models in the scene
-     */
-    focusCameraAll(): void;
-    /**
-     * Focus on a single given 3D model
-     */
-    focusModel(handle: Reveal3DResourceHandle): void;
-    /**
-     * Returns the state of the camera in the Reveal viewer
-     */
-    getCameraState(): Required<CameraState>;
-    /**
-     * Sets the state of the camera
-     */
-    setCameraState(cameraState: CameraState): void;
-    enterNearby360Image(): Promise<void> | undefined;
+	/**
+	* Focus all visible models in the scene
+	*/
+	focusCameraAll(): void;
+	/**
+	* Focus on a single given 3D model
+	*/
+	focusModel(handle: Reveal3DResourceHandle): void;
+	/**
+	* Returns the state of the camera in the Reveal viewer
+	*/
+	getCameraState(): Required<CameraState>;
+	/**
+	* Sets the state of the camera
+	*/
+	setCameraState(cameraState: CameraState): void;
+	enterNearby360Image(): Promise<void> | undefined;
 };
 export type RevealWidgetController = {
-    /**
-     * Access the RevealWidgetCameraController for camera controls
-     */
-    readonly cameraController: RevealWidgetCameraController;
-    /**
-     * Add a 3D resource (i.e. model or scene) to the widget.
-     * Added resources can be removed by calling their `.remove` method.
-     */
-    addResource(resource: AllResourceIdentifier): Promise<Reveal3DResourceHandle>;
-    /**
-     * Get all models added to the RevealWidget
-     */
-    getModels(): Reveal3DResourceHandle[];
-    /**
-     * Get all models added to the RevealWidget that are visible
-     */
-    getVisibleModels(): Reveal3DResourceHandle[];
-    /**
-     * Style the provided instances with the associated styles in the given models, if
-     * the instances are contextualized to the models
-     */
-    styleByInstance(instanceStylingGroups: InstanceStylingGroup[], handles: Reveal3DResourceHandle[]): Promise<void>;
-    /**
-     * Moves the camera to show the provided instances in the visible models in the scene.
-     */
-    focusInstances(instances: InstanceId[]): Promise<void>;
+	/**
+	* Access the RevealWidgetCameraController for camera controls
+	*/
+	readonly cameraController: RevealWidgetCameraController;
+	/**
+	* Access the RevealWidgetAssets for searching the assets mapped to the models
+	*/
+	readonly assets: RevealWidgetAssets;
+	/**
+	* Access the RevealWidgetHtmlOverlays for attaching HTML elements to positions in the scene
+	*/
+	readonly htmlOverlays: RevealWidgetHtmlOverlays;
+	/**
+	* Add a 3D resource (i.e. model or scene) to the widget.
+	* Added resources can be removed by calling their `.remove` method.
+	*/
+	addResource(resource: AllResourceIdentifier): Promise<Reveal3DResourceHandle>;
+	/**
+	* Load a scene from a location (matched by external ID or name). If the
+	* location, including its sub-locations, has exactly one scene it is loaded.
+	* If it has several, nothing is loaded and the candidates are returned so the
+	* caller can ask the user to pick one, then call this method again with
+	* `selectedScene`.
+	*/
+	addResourceByLocation(location: string, selectedScene?: DmsUniqueIdentifier): Promise<AddResourceByLocationResult>;
+	/**
+	* Get all models added to the RevealWidget
+	*/
+	getModels(): Reveal3DResourceHandle[];
+	/**
+	* Get all models added to the RevealWidget that are visible
+	*/
+	getVisibleModels(): Reveal3DResourceHandle[];
+	/**
+	* Style the provided instances with the associated styles in the given models, if
+	* the instances are contextualized to the models
+	*/
+	styleByInstance(instanceStylingGroups: InstanceStylingGroup[], handles: Reveal3DResourceHandle[]): Promise<void>;
+	/**
+	* Moves the camera to show the provided instances in the visible models in the scene.
+	*/
+	focusInstances(instances: InstanceId[]): Promise<void>;
 };
 export type RevealWidgetProps = {
-    /**
-     * Defines the initialization options for the RevealWidget, including the SDK and data modeling status
-     * The user can either specify these separately, or opt for the object
-     * `{ inheritFromRevealContext: true }`, in which case the Widget will assume the existence of
-     * a `RevealContext` mounted above it in the hierarchy.
-     */
-    viewerOptions: (Pick<Cognite3DViewerOptions, 'sdk' | 'onLoading'> & {
-        useCoreDm: boolean;
-    }) | {
-        /**
-         * Disables the RevealWidget's own RevealContext, relying on one defined in the application
-         * layer instead.
-         */
-        inheritFromRevealContext: true;
-    };
-    /**
-     * The widget uses this to set a reference to the widget controller.
-     * The widget calls this with `undefined` when the component unmounts or this callback changes
-     */
-    setControllerRef?: (controller: RevealWidgetController | undefined) => void;
+	/**
+	* Defines the initialization options for the RevealWidget, including the SDK and data modeling status
+	* The user can either specify these separately, or opt for the object
+	* `{ inheritFromRevealContext: true }`, in which case the Widget will assume the existence of
+	* a `RevealContext` mounted above it in the hierarchy.
+	*/
+	viewerOptions: (Pick<Cognite3DViewerOptions, "sdk" | "onLoading"> & {
+		useCoreDm: boolean;
+	}) | {
+		/**
+		* Disables the RevealWidget's own RevealContext, relying on one defined in the application
+		* layer instead.
+		*/
+		inheritFromRevealContext: true;
+	};
+	/**
+	* The widget uses this to set a reference to the widget controller.
+	* The widget calls this with `undefined` when the component unmounts or this callback changes
+	*/
+	setControllerRef?: (controller: RevealWidgetController | undefined) => void;
+	/**
+	* Reports which application is using the widget and which of its features are being triggered
+	* (e.g. adding a resource, moving the camera). See `RevealWidgetTrackingProps` for the options.
+	*/
+	tracking?: RevealWidgetTrackingProps;
+	/** Identifies the host application */
+	appIdentifier: string;
 };
 export declare const RevealWidget: (props: PropsWithChildren<RevealWidgetProps>) => ReactElement;

package/dist/index.js

@@ -1,10 +1,40 @@
-import { DefaultNodeAppearance as e } from "@cognite/reveal";
-import { RevealWidget as t } from "@cognite/reveal-components/ui/components";
-//#region libs/shared/reveal-widget/src/index.ts
-var n = { Highlighted: {
-	cad: e.Highlighted,
-	pointcloud: e.Highlighted,
-	image360: e.Highlighted
-} }, r = t;
-//#endregion
-export { n as Default3DStyles, r as RevealWidget };
+import { DefaultNodeAppearance } from "@cognite/reveal";
+import { RevealWidget as RevealWidgetComponent } from "@cognite/reveal-components/ui/components";
+/**
+ * Public API surface for the standalone `@cognite/reveal-widget` npm package.
+ *
+ * `RevealWidget` here is the real, unmodified implementation from
+ * `@cognite/reveal-components` — there is no runtime wrapper. `@cognite/reveal-components`
+ * is a `dependencies` entry, so it and its own published dependencies (`@cognite/signal-utils`,
+ * `@cognite/underscore`) are treated as external. The resource/identifier types above are
+ * re-exported directly from `@cognite/reveal-components`'s narrow, already-subpath-exported
+ * type barrels (`./data-providers/types`, `./utilities/modelIds`, `./utilities`), which an
+ * external consumer resolves normally since that package is published.
+ *
+ * `Reveal3DResourceHandle`, `RevealWidgetController`, `RevealWidgetCameraController`, `RevealWidgetAssets`, `RevealWidgetHtmlOverlays`, and
+ * `RevealWidgetProps` below are still hand-declared, because their real counterparts (only
+ * reachable via the entangled `./ui/components` export) expose `RevealDomainObject`/
+ * `SceneDomainObject` directly in their signatures — too large for API Extractor's type bundler
+ * and not meaningful for an external consumer anyway. `src/index.test.ts` has compile-time-only
+ * (`// @ts-expect-error`-driven) tests asserting these hand-written types stay structurally
+ * compatible with the real implementation — update both together when the real API changes.
+ * `RevealWidgetTrackingProps` (and its arms) don't have this problem — they only reference
+ * `UsageMetricsTracker`, so they're imported and re-exported directly from `./ui/components`
+ * rather than hand-declared.
+ *
+ * `tracking`/`appIdentifier` (on `RevealWidgetProps`) plumb through to the real `RevealWidget`'s
+ * usage-tracking seam, which reports to a dedicated, named `mixpanel-browser` instance *by
+ * default* — not Fusion's own `@cognite/metrics`/Mixpanel setup, since `@cognite/reveal-widget`
+ * is also consumed outside this monorepo. Pass `tracking: { disabled: true }` to opt out
+ * entirely, or `tracking: { mixpanelToken }` (with `appIdentifier`) to report to your own
+ * Mixpanel project instead.
+ */ export const Default3DStyles = {
+    Highlighted: {
+        cad: DefaultNodeAppearance.Highlighted,
+        pointcloud: DefaultNodeAppearance.Highlighted,
+        image360: DefaultNodeAppearance.Highlighted
+    }
+};
+export const RevealWidget = RevealWidgetComponent;
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { PropsWithChildren, ReactElement } from 'react';\n\nimport type {\n  CameraState,\n  Cognite3DViewerOptions,\n  NodeAppearance,\n} from '@cognite/reveal';\nimport { DefaultNodeAppearance } from '@cognite/reveal';\nimport type {\n  DmsUniqueIdentifier,\n  ExternalId,\n  Space,\n} from '@cognite/reveal-components/data-providers';\nimport type { AssetId } from '@cognite/reveal-components/data-providers/cache';\nimport type {\n  AddReveal3DResource,\n  AllResourceIdentifier,\n  BaseAddOptions,\n  CadAddOptions,\n  NewCadModelStyling as CadModelStyling,\n  CadResourceIdentifier,\n  Classic3DResourceIdentifier,\n  DM3DResourceIdentifier,\n  Image360AddOptions,\n  Image360DMResourceIdentifier,\n  Image360EventsResourceIdentifier,\n  Image360IconCullingOptions,\n  Image360ResourceIdentifier,\n  PointCloudAddOptions,\n  PointCloudResourceIdentifier,\n  SceneAddOptions,\n  SceneResourceIdentifier,\n  ThreeDResourceIdentifier,\n} from '@cognite/reveal-components/data-providers/types';\nimport {\n  RevealWidget as RevealWidgetComponent,\n  type RevealWidgetTrackingProps,\n} from '@cognite/reveal-components/ui/components';\nimport type {\n  InstanceId,\n  UsageMetricsTracker,\n} from '@cognite/reveal-components/utilities';\nimport type { InstanceStylingGroup } from '@cognite/reveal-components/utilities/modelIds';\nimport type { TreeIndexStylingGroup } from '@cognite/reveal-components/utilities/styling';\n\nexport type {\n  AddReveal3DResource,\n  AllResourceIdentifier,\n  AssetId,\n  BaseAddOptions,\n  CadAddOptions,\n  CadModelStyling,\n  CadResourceIdentifier,\n  Classic3DResourceIdentifier,\n  DM3DResourceIdentifier,\n  DmsUniqueIdentifier,\n  ExternalId,\n  Image360AddOptions,\n  Image360DMResourceIdentifier,\n  Image360EventsResourceIdentifier,\n  Image360IconCullingOptions,\n  Image360ResourceIdentifier,\n  InstanceId,\n  InstanceStylingGroup,\n  UsageMetricsTracker,\n  PointCloudAddOptions,\n  PointCloudResourceIdentifier,\n  RevealWidgetTrackingProps,\n  SceneAddOptions,\n  SceneResourceIdentifier,\n  Space,\n  ThreeDResourceIdentifier,\n  TreeIndexStylingGroup,\n};\n\n/**\n * Public API surface for the standalone `@cognite/reveal-widget` npm package.\n *\n * `RevealWidget` here is the real, unmodified implementation from\n * `@cognite/reveal-components` — there is no runtime wrapper. `@cognite/reveal-components`\n * is a `dependencies` entry, so it and its own published dependencies (`@cognite/signal-utils`,\n * `@cognite/underscore`) are treated as external. The resource/identifier types above are\n * re-exported directly from `@cognite/reveal-components`'s narrow, already-subpath-exported\n * type barrels (`./data-providers/types`, `./utilities/modelIds`, `./utilities`), which an\n * external consumer resolves normally since that package is published.\n *\n * `Reveal3DResourceHandle`, `RevealWidgetController`, `RevealWidgetCameraController`, `RevealWidgetAssets`, `RevealWidgetHtmlOverlays`, and\n * `RevealWidgetProps` below are still hand-declared, because their real counterparts (only\n * reachable via the entangled `./ui/components` export) expose `RevealDomainObject`/\n * `SceneDomainObject` directly in their signatures — too large for API Extractor's type bundler\n * and not meaningful for an external consumer anyway. `src/index.test.ts` has compile-time-only\n * (`// @ts-expect-error`-driven) tests asserting these hand-written types stay structurally\n * compatible with the real implementation — update both together when the real API changes.\n * `RevealWidgetTrackingProps` (and its arms) don't have this problem — they only reference\n * `UsageMetricsTracker`, so they're imported and re-exported directly from `./ui/components`\n * rather than hand-declared.\n *\n * `tracking`/`appIdentifier` (on `RevealWidgetProps`) plumb through to the real `RevealWidget`'s\n * usage-tracking seam, which reports to a dedicated, named `mixpanel-browser` instance *by\n * default* — not Fusion's own `@cognite/metrics`/Mixpanel setup, since `@cognite/reveal-widget`\n * is also consumed outside this monorepo. Pass `tracking: { disabled: true }` to opt out\n * entirely, or `tracking: { mixpanelToken }` (with `appIdentifier`) to report to your own\n * Mixpanel project instead.\n */\nexport const Default3DStyles: {\n  Highlighted: {\n    cad: NodeAppearance;\n    pointcloud: NodeAppearance;\n    image360: NodeAppearance;\n  };\n} = {\n  Highlighted: {\n    cad: DefaultNodeAppearance.Highlighted,\n    pointcloud: DefaultNodeAppearance.Highlighted,\n    image360: DefaultNodeAppearance.Highlighted,\n  },\n};\n\n/**\n * A narrow, external-facing view of a loaded 3D resource (CAD model, point cloud, image360\n * collection, or scene). This is a type-only narrowing — the actual object returned at runtime\n * by `addResource()`/`getModels()` is still the real `RevealDomainObject`/`SceneDomainObject`.\n * Only `.remove()` is published here to keep the exported type surface minimal.\n */\nexport type Reveal3DResourceHandle = {\n  remove(): boolean;\n};\n\n/**\n * A scene that can be loaded for a location, and the (sub-)location it is\n * configured on.\n */\nexport type LocationSceneCandidate = {\n  scene: DmsUniqueIdentifier;\n  locationName: string;\n};\n\n/**\n * Outcome of `RevealWidgetController.addResourceByLocation`:\n * - `loaded`: the scene was added to the widget\n * - `selection-required`: the location has several scenes (its own and those of\n *   its sub-locations); nothing was loaded, call again with the chosen scene\n * - `not-found`: no such location, or it has no scene\n */\nexport type AddResourceByLocationResult =\n  | SceneLoadedForLocation\n  | SceneSelectionRequiredForLocation\n  | SceneNotFoundForLocation;\n\nexport type SceneLoadedForLocation = {\n  status: 'loaded';\n  scene: Reveal3DResourceHandle;\n};\n\nexport type SceneSelectionRequiredForLocation = {\n  status: 'selection-required';\n  candidates: LocationSceneCandidate[];\n};\n\nexport type SceneNotFoundForLocation = { status: 'not-found' };\n\n/**\n * An asset that is mapped to a loaded 3D model.\n */\nexport type MappedAsset = {\n  name: string;\n  description?: string;\n  /** Pass to `styleByInstance` / `focusInstances` to highlight or zoom to the asset */\n  instanceId: InstanceId;\n};\n\n/**\n * Options for `RevealWidgetAssets.searchMappedAssets`.\n */\nexport type SearchMappedAssetsOptions = {\n  /**\n   * Free-text search on the asset name and description. Not guaranteed to\n   * return all matching assets.\n   */\n  query?: string;\n  /** Maximum number of assets to return (default 100, maximum 1000) */\n  limit?: number;\n};\n\n/**\n * Result of `RevealWidgetAssets.searchMappedAssets`.\n */\nexport type SearchMappedAssetsResult = {\n  assets: MappedAsset[];\n  /**\n   * True if there may be more matching assets than were returned. Pagination is\n   * not supported, so use `query` to narrow down the search.\n   */\n  hasMore: boolean;\n};\n\n/**\n * Search for the assets mapped to the models in the widget.\n */\nexport type RevealWidgetAssets = {\n  /**\n   * Search the core data model assets that are mapped to the visible CAD models,\n   * point clouds and data model 360 image collections, including those of a\n   * loaded scene. Only data modeling assets are searched, never classic assets,\n   * so this is intended for data-modeling-only projects. Use the returned\n   * `instanceId`s with `styleByInstance` and `focusInstances` to highlight an\n   * asset and zoom to it.\n   */\n  searchMappedAssets(\n    options?: SearchMappedAssetsOptions\n  ): Promise<SearchMappedAssetsResult>;\n};\n\n/**\n * A position in the CDF coordinate system, i.e. the one the coordinates of\n * CDF 3D models and their assets are given in\n */\nexport type HtmlOverlayPosition = { x: number; y: number; z: number };\n\n/**\n * A handle to an HTML overlay added to the widget\n */\nexport type HtmlOverlayHandle = {\n  /**\n   * Removes the overlay's element from the widget. Does nothing if\n   * it has already been removed.\n   */\n  remove(): void;\n};\n\n/**\n * Attaching HTML elements to positions in the 3D scene of the widget,\n * e.g. to show notifications.\n */\nexport type RevealWidgetHtmlOverlays = {\n  /**\n   * Attaches an HTML element to a position in the scene. The element follows the\n   * position as the camera moves, and is hidden while the position is not in view.\n   *\n   * The widget sets `position: absolute` on the element, which the overlay requires.\n   * Styling such as `transform: translate(-50%, -50%)` to center the element on the\n   * position, and `pointer-events: none` to not interfere with camera navigation,\n   * is up to the caller.\n   *\n   * ```\n   * const overlay = controller.htmlOverlays.add(element, { x: 10, y: 20, z: 5 });\n   *\n   * // during cleanup:\n   * overlay.remove();\n   * ```\n   *\n   * @param element The element to attach. Adding the same element again moves it.\n   * @param position The position in CDF coordinates\n   */\n  add(element: HTMLElement, position: HtmlOverlayPosition): HtmlOverlayHandle;\n  /**\n   * Removes all the overlays added to the widget\n   */\n  clear(): void;\n  /**\n   * Hides or shows all the overlays, including ones added later. They are visible by default.\n   */\n  setVisible(visible: boolean): void;\n};\n\nexport type RevealWidgetCameraController = {\n  /**\n   * Focus all visible models in the scene\n   */\n  focusCameraAll(): void;\n  /**\n   * Focus on a single given 3D model\n   */\n  focusModel(handle: Reveal3DResourceHandle): void;\n  /**\n   * Returns the state of the camera in the Reveal viewer\n   */\n  getCameraState(): Required<CameraState>;\n  /**\n   * Sets the state of the camera\n   */\n  setCameraState(cameraState: CameraState): void;\n  enterNearby360Image(): Promise<void> | undefined;\n};\n\nexport type RevealWidgetController = {\n  /**\n   * Access the RevealWidgetCameraController for camera controls\n   */\n  readonly cameraController: RevealWidgetCameraController;\n  /**\n   * Access the RevealWidgetAssets for searching the assets mapped to the models\n   */\n  readonly assets: RevealWidgetAssets;\n  /**\n   * Access the RevealWidgetHtmlOverlays for attaching HTML elements to positions in the scene\n   */\n  readonly htmlOverlays: RevealWidgetHtmlOverlays;\n  /**\n   * Add a 3D resource (i.e. model or scene) to the widget.\n   * Added resources can be removed by calling their `.remove` method.\n   */\n  addResource(resource: AllResourceIdentifier): Promise<Reveal3DResourceHandle>;\n  /**\n   * Load a scene from a location (matched by external ID or name). If the\n   * location, including its sub-locations, has exactly one scene it is loaded.\n   * If it has several, nothing is loaded and the candidates are returned so the\n   * caller can ask the user to pick one, then call this method again with\n   * `selectedScene`.\n   */\n  addResourceByLocation(\n    location: string,\n    selectedScene?: DmsUniqueIdentifier\n  ): Promise<AddResourceByLocationResult>;\n  /**\n   * Get all models added to the RevealWidget\n   */\n  getModels(): Reveal3DResourceHandle[];\n  /**\n   * Get all models added to the RevealWidget that are visible\n   */\n  getVisibleModels(): Reveal3DResourceHandle[];\n  /**\n   * Style the provided instances with the associated styles in the given models, if\n   * the instances are contextualized to the models\n   */\n  styleByInstance(\n    instanceStylingGroups: InstanceStylingGroup[],\n    handles: Reveal3DResourceHandle[]\n  ): Promise<void>;\n  /**\n   * Moves the camera to show the provided instances in the visible models in the scene.\n   */\n  focusInstances(instances: InstanceId[]): Promise<void>;\n};\n\nexport type RevealWidgetProps = {\n  /**\n   * Defines the initialization options for the RevealWidget, including the SDK and data modeling status\n   * The user can either specify these separately, or opt for the object\n   * `{ inheritFromRevealContext: true }`, in which case the Widget will assume the existence of\n   * a `RevealContext` mounted above it in the hierarchy.\n   */\n  viewerOptions:\n    | (Pick<Cognite3DViewerOptions, 'sdk' | 'onLoading'> & {\n        useCoreDm: boolean;\n      })\n    | {\n        /**\n         * Disables the RevealWidget's own RevealContext, relying on one defined in the application\n         * layer instead.\n         */\n        inheritFromRevealContext: true;\n      };\n  /**\n   * The widget uses this to set a reference to the widget controller.\n   * The widget calls this with `undefined` when the component unmounts or this callback changes\n   */\n  setControllerRef?: (controller: RevealWidgetController | undefined) => void;\n  /**\n   * Reports which application is using the widget and which of its features are being triggered\n   * (e.g. adding a resource, moving the camera). See `RevealWidgetTrackingProps` for the options.\n   */\n  tracking?: RevealWidgetTrackingProps;\n  /** Identifies the host application */\n  appIdentifier: string;\n};\n\nexport const RevealWidget: (\n  props: PropsWithChildren<RevealWidgetProps>\n) => ReactElement = RevealWidgetComponent;\n"],"names":["DefaultNodeAppearance","RevealWidget","RevealWidgetComponent","Default3DStyles","Highlighted","cad","pointcloud","image360"],"mappings":"AAOA,SAASA,qBAAqB,QAAQ,kBAAkB;AA2BxD,SACEC,gBAAgBC,qBAAqB,QAEhC,2CAA2C;AAsClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMC,kBAMT;IACFC,aAAa;QACXC,KAAKL,sBAAsBI,WAAW;QACtCE,YAAYN,sBAAsBI,WAAW;QAC7CG,UAAUP,sBAAsBI,WAAW;IAC7C;AACF,EAAE;AA4PF,OAAO,MAAMH,eAEOC,sBAAsB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cognite/reveal-widget",
-  "version": "0.2.0",
+  "version": "1.48535.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -18,30 +18,35 @@
     "@base-ui/react": "^1.6.0",
     "@floating-ui/react": "^0.24.8",
     "@tabler/icons-react": "^3.35.0",
-    "@tanstack/react-query": "^4.43.0",
+    "@tanstack/react-query": "^5.102.8",
     "dayjs": "^1.11.13",
     "lodash-es": "^4.18.1",
     "ml-matrix": "^6.12.1",
     "random-seed": "^0.3.0",
     "three": "0.184.0",
-    "@cognite/reveal-components": "1.0.1",
-    "@cognite/aura": "0.3.5"
+    "@cognite/reveal-components": "1.48535.0",
+    "@cognite/aura": "1.48535.0"
   },
   "devDependencies": {
     "@cognite/reveal": "4.36.0",
-    "@cognite/sdk": "^10.14.0",
+    "@cognite/sdk": "10.17.0",
     "@microsoft/api-extractor": "^7.58.12",
-    "@nx/eslint-plugin": "22.7.8",
+    "@types/react": "18.3.14",
     "eslint-plugin-check-file": "^2.7.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "vite": "8.2.2",
+    "vite": "8.2.4",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@cognite/reveal": "4.35.3",
-    "@cognite/sdk": "^10.13.0",
+    "@cognite/reveal": "4.36.0",
+    "@cognite/sdk": "10.17.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cognitedata/infrastructure.git",
+    "directory": "lib/ts/shared/reveal-widget"
   }
 }