@cognite/reveal-widget 0.1.0 → 0.3.0

package/README.md

@@ -6,9 +6,43 @@ A React component for embedding an interactive [Cognite Reveal](https://cognited
 (assets) within them.
 
 This package exposes `RevealWidget` and the types needed to drive it via
-`RevealWidgetController`. More capabilities from the broader Reveal React Components toolkit
+`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

package/dist/index.d.ts

@@ -1,252 +1,132 @@
-import { CameraState } from '@cognite/reveal';
-import { Cognite3DViewerOptions } from '@cognite/reveal';
-import { Image360AnnotationAppearance } from '@cognite/reveal';
-import type { IndexSet } from '@cognite/reveal';
-import type { Matrix4 } from 'three';
-import { NodeAppearance } from '@cognite/reveal';
-import { PropsWithChildren } from 'react';
-import { ReactElement } from 'react';
-
-export declare type AddReveal3DResource =
-| CadAddOptions
-| PointCloudAddOptions
-| Image360AddOptions;
-
-export declare type AllResourceIdentifier =
-| ThreeDResourceIdentifier
-| SceneResourceIdentifier;
-
-export declare type AssetId = number;
-
-export declare type BaseAddOptions = {
-    transform?: Matrix4;
-    defaultVisible?: boolean;
-};
-
-export declare type CadAddOptions = BaseAddOptions &
-(Classic3DResourceIdentifier | DM3DResourceIdentifier) & {
-    styling?: CadModelStyling;
-    modelCategory: 'model3d';
-};
-
-export declare type CadModelStyling = {
-    default?: NodeAppearance;
-    mapped?: NodeAppearance;
-    nodeGroups?: TreeIndexStylingGroup[];
-};
-
-export declare type CadResourceIdentifier = (
-| Classic3DResourceIdentifier
-| DM3DResourceIdentifier
-) & { type: 'cad' };
-
-export declare type Classic3DResourceIdentifier = {
-    readonly sourceType: 'classic';
-    readonly modelId: number;
-    readonly revisionId: number;
-};
-
-/**
- * Public API surface for the standalone `@cognite/reveal-widget` npm package.
- *
- * `RevealWidget` here is the real, unmodified implementation from
- * `@cognite/reveal-react-components` — there is no runtime wrapper. The resource/identifier
- * types above are re-exported directly from `@cognite/reveal-react-components`'s narrow,
- * already-subpath-exported type barrels (`./data-providers/types`, `./utilities/modelIds`,
- * `./utilities`). `vite.config.ts` sets `bundledPackages: ['@cognite/reveal-react-components']`
- * on the `dts` plugin, which tells API Extractor (used internally for `rollupTypes`) to inline
- * these types' real declarations into `dist/index.d.ts` instead of leaving a bare
- * `import ... from '@cognite/reveal-react-components/...'` that an external consumer couldn't
- * resolve (that package is `private: true` and never 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.
- */
-export declare const Default3DStyles: {
-    Highlighted: {
-        cad: NodeAppearance;
-        pointcloud: NodeAppearance;
-        image360: NodeAppearance;
-    };
-};
-
-export declare type DM3DResourceIdentifier = {
-    readonly sourceType: 'cdm';
-    readonly externalId: string;
-    readonly space: string;
-};
-
-export declare type DmsUniqueIdentifier = {
-    space: Space;
-    externalId: ExternalId;
-};
-
-export declare type ExternalId = string;
-
-export declare type Image360AddOptions = BaseAddOptions &
-(Image360EventsResourceIdentifier | Image360DMResourceIdentifier) & {
-    iconCullingOptions?: Image360IconCullingOptions;
-    modelCategory: 'image360';
-};
-
-export declare type Image360DMResourceIdentifier = {
-    readonly sourceType: 'dm' | 'cdm';
-    readonly externalId: string;
-    readonly space: string;
-};
-
-export declare type Image360EventsResourceIdentifier = {
-    readonly sourceType: 'events';
-    readonly siteId: string;
-};
-
-export declare type Image360IconCullingOptions = {
-    radius?: number;
-    iconCountLimit?: number;
-};
-
-export declare type Image360ResourceIdentifier = (
-| Image360DMResourceIdentifier
-| Image360EventsResourceIdentifier
-) & { type: 'image360' };
-
-export declare type InstanceId = AssetId | DmsUniqueIdentifier;
-
-export declare type InstanceStylingGroup = {
-    instanceIds: (DmsUniqueIdentifier | AssetId)[];
-    style: {
-        cad?: NodeAppearance;
-        pointcloud?: NodeAppearance;
-        image360?: Image360AnnotationAppearance;
-    };
-};
-
-export declare type PointCloudAddOptions = BaseAddOptions &
-(Classic3DResourceIdentifier | DM3DResourceIdentifier) & {
-    styling?: {
-        default?: NodeAppearance;
-        mapped?: NodeAppearance;
-    };
-    modelCategory: 'model3d';
-};
-
-export declare type PointCloudResourceIdentifier = (
-| Classic3DResourceIdentifier
-| DM3DResourceIdentifier
-) & { type: 'pointcloud' };
-
-/**
- * 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 declare type Reveal3DResourceHandle = {
-    remove(): boolean;
-};
-
-export declare const RevealWidget: (props: PropsWithChildren<RevealWidgetProps>) => ReactElement;
-
-export declare 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;
-};
-
-export declare 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>;
-};
-
-export declare 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;
-};
-
-export declare type SceneAddOptions = {
-    sourceType: 'dm';
-    externalId: string;
-    space: string;
-    modelCategory: 'scene';
-};
-
-export declare type SceneResourceIdentifier = {
-    type: 'scene';
-    externalId: string;
-    space: string;
-};
-
-export declare type Space = string;
-
-export declare type ThreeDResourceIdentifier =
-| CadResourceIdentifier
-| PointCloudResourceIdentifier
-| Image360ResourceIdentifier;
-
-export declare type TreeIndexStylingGroup = {
-    treeIndexSet: IndexSet;
-    style: NodeAppearance;
-};
-
-export { }
+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 { RevealWidgetTrackingProps } from '@cognite/reveal-components/ui/components';
+import { InstanceId, UsageMetricsTracker } 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, 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, 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`, 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;
+    };
+};
+/**
+ * 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;
+};
+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;
+};
+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>;
+};
+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;
+    /**
+     * 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;