@cognite/reveal-widget 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# @cognite/reveal-widget
+
+A React component for embedding an interactive [Cognite Reveal](https://cognitedata.github.io/reveal)
+3D viewer in your application: `RevealWidget`. It loads and renders CAD models, point clouds,
+360° image collections, and CDF scenes, and lets you highlight and focus specific instances
+(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
+will be exposed here incrementally over time.
+
+## Install
+
+```bash
+npm install @cognite/reveal-widget @cognite/reveal @cognite/sdk react react-dom
+```
+
+`react`, `react-dom`, `@cognite/reveal`, and `@cognite/sdk` are peer dependencies — install
+versions matching what your app already uses. Everything else the widget needs installs
+automatically as a regular dependency.
+
+If your bundler doesn't already dedupe singletons across your dependency tree, add:
+
+```ts
+// vite.config.ts
+resolve: { dedupe: ['three', '@cognite/reveal'] }
+```
+
+## Usage
+
+`RevealWidget` hands you a `RevealWidgetController` via `setControllerRef`. Rather than
+reacting to prop changes through `useEffect`, wrap it in your own class and drive it
+imperatively — e.g. from event handlers elsewhere in your app (a click on an asset in a list,
+a button press, etc.):
+
+```tsx
+import { useRef } from 'react';
+import type { CogniteClient } from '@cognite/sdk';
+import {
+  Default3DStyles,
+  RevealWidget,
+  type Reveal3DResourceHandle,
+  type RevealWidgetController,
+  type ThreeDResourceIdentifier,
+  type InstanceId,
+} from '@cognite/reveal-widget';
+
+class ThreeDViewerController {
+  private model: Reveal3DResourceHandle | undefined;
+
+  constructor(private readonly widgetController: RevealWidgetController) {}
+
+  async loadModel(resource: ThreeDResourceIdentifier): Promise<void> {
+    this.model = await this.widgetController.addResource(resource);
+    this.widgetController.cameraController.focusModel(this.model);
+  }
+
+  async highlightAsset(instanceId: InstanceId): Promise<void> {
+    if (this.model === undefined) return;
+    await this.widgetController.styleByInstance(
+      [{ instanceIds: [instanceId], style: Default3DStyles.Highlighted }],
+      [this.model]
+    );
+    await this.widgetController.focusInstances([instanceId]);
+  }
+
+  dispose(): void {
+    this.model?.remove();
+  }
+}
+
+export function ThreeDViewer({
+  sdk,
+  resource,
+  onReady,
+}: {
+  sdk: CogniteClient;
+  resource: ThreeDResourceIdentifier;
+  onReady: (viewer: ThreeDViewerController | undefined) => void;
+}) {
+  const viewerRef = useRef<ThreeDViewerController>();
+
+  function handleWidgetController(widgetController: RevealWidgetController | undefined) {
+    viewerRef.current?.dispose();
+
+    if (widgetController === undefined) {
+      viewerRef.current = undefined;
+      onReady(undefined);
+      return;
+    }
+
+    const viewer = new ThreeDViewerController(widgetController);
+    void viewer.loadModel(resource);
+    viewerRef.current = viewer;
+    onReady(viewer);
+  }
+
+  return (
+    <div style={{ width: '100%', height: '70vh', position: 'relative' }}>
+      <RevealWidget
+        viewerOptions={{ sdk, useCoreDm: true }}
+        setControllerRef={handleWidgetController}
+      />
+    </div>
+  );
+}
+
+// Elsewhere, e.g. from a click handler in whatever renders a list of assets:
+// viewer.highlightAsset({ externalId: 'CogniteAsset-1022', space: 'my-space' });
+```
+
+`RevealWidget` wraps its own Reveal context internally — don't wrap it in another provider from
+this package.
+
+### Loading resources
+
+`controller.addResource(...)` accepts CAD models, point clouds, 360° image collections, or
+scenes, identified by `type` and `sourceType`:
+
+```ts
+{ type: 'cad',        sourceType: 'classic', modelId: number, revisionId: number }
+{ type: 'cad',        sourceType: 'cdm',     externalId: string, space: string }
+{ type: 'pointcloud', sourceType: 'classic', modelId: number, revisionId: number }
+{ type: 'pointcloud', sourceType: 'cdm',     externalId: string, space: string }
+{ type: 'image360',   sourceType: 'dm' | 'cdm', externalId: string, space: string }
+{ type: 'image360',   sourceType: 'events',  siteId: string }
+{ type: 'scene',                              externalId: string, space: string }
+```
+
+CAD/point cloud/image360 resources resolve to a `Reveal3DResourceHandle` usable with
+`styleByInstance`/`getModels()`/`cameraController.focusModel()`; a `'scene'` resource resolves to
+a handle that only supports `.remove()`.
+
+### 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' }]
+```
+
+### Camera control
+
+```ts
+controller.cameraController.focusModel(handle); // fit one model
+controller.cameraController.focusCameraAll();     // fit all models
+await controller.focusInstances([someInstanceId]); // zoom to a specific instance
+```
+
+## Cleaning up
+
+Resources added via `addResource` should be removed when no longer needed:
+
+```ts
+const handle = await controller.addResource(resource);
+// ...later:
+handle.remove();
+```

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+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 { }