@inweb/viewer-core 25.12.0 → 26.1.0

package/src/components/Component.ts

@@ -0,0 +1,33 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import type { IViewer } from "../viewer/IViewer";
+import type { IComponent } from "./IComponents";
+
+export class Component implements IComponent {
+  name = "";
+
+  constructor(viewer: IViewer) {}
+
+  dispose(): void {}
+}

package/src/components/Components.ts

@@ -0,0 +1,71 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import type { IViewer } from "../viewer/IViewer";
+import { IComponent, IComponentProvider, IComponentsMap, IComponentsRegistry } from "./IComponents";
+
+class Components implements IComponentsRegistry {
+  private readonly _components = new Map<string, IComponentProvider>();
+
+  registerComponent(name: string, provider: IComponentProvider): void {
+    this._components.set(name, provider);
+  }
+
+  registerComponentAlias(name: string, alias: string): void {
+    const provider = this.getComponent(name);
+    if (provider) this.registerComponent(alias, (viewer: IViewer) => provider(viewer));
+  }
+
+  getComponent(name: string): IComponentProvider | undefined {
+    return this._components.get(name);
+  }
+
+  getComponents(): IComponentsMap {
+    const map = new Map<string, IComponentProvider>();
+    this._components.forEach((value, key) => map.set(key, value));
+    return map;
+  }
+
+  createComponent(name: string, viewer: IViewer): IComponent | null {
+    const provider = this.getComponent(name);
+    if (!provider) return null;
+
+    const component = provider(viewer);
+    component.name = name;
+
+    return component;
+  }
+}
+
+const _components = new Map<string, Components>();
+
+function componentsRegistry(viewerType = ""): IComponentsRegistry {
+  let result = _components.get(viewerType);
+  if (!result) {
+    result = new Components();
+    _components.set(viewerType, result);
+  }
+  return result;
+}
+
+export { componentsRegistry };

package/src/components/IComponents.ts

@@ -0,0 +1,94 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import type { IViewer } from "../viewer/IViewer";
+
+/**
+ * Defines the component of the viewer.
+ */
+export interface IComponent {
+  /**
+   * The name of the component.
+   */
+  name?: string;
+
+  /**
+   * Releases resources allocated by the component.
+   */
+  dispose(): void;
+}
+
+/**
+ * Defines the component provider function.
+ */
+export interface IComponentProvider {
+  /**
+   * @param viewer - Viewer instance that creates the component.
+   */
+  (viewer: any): IComponent;
+}
+
+export type IComponentsMap = Map<string, IComponentProvider>;
+
+/**
+ * Define the viewer components registry interface.
+ */
+export interface IComponentsRegistry {
+  /**
+   * Binds a component name to a component. Registering a component with an existing name twice
+   * overrides the existing component.
+   *
+   * @param name - Unique name for the component.
+   * @param provider - Component provider.
+   */
+  registerComponent(name: string, provider: IComponentProvider): void;
+
+  /**
+   * Registers an alias for a component.
+   *
+   * @param name - Unique name for the component.
+   * @param alias - Component alias string.
+   */
+  registerComponentAlias(name: string, alias: string): void;
+
+  /**
+   * Returns a list of registered components.
+   */
+  getComponents(): IComponentsMap;
+
+  /**
+   * Returns the specified component or `undefined` when the component doesn't exists.
+   *
+   * @param name - Component name.
+   */
+  getComponent(name: string): IComponentProvider | undefined;
+
+  /**
+   * Creates the component denoted by the given name. Returns `null` if a component with given
+   * name not registered.
+   *
+   * @param name - Component name.
+   * @param viewer - Viewer instance that wants to create the component.
+   */
+  createComponent(name: string, viewer: IViewer): IComponent | null;
+}

package/src/draggers/Dragger.ts

@@ -0,0 +1,33 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import type { IViewer } from "../viewer/IViewer";
+import type { IDragger } from "./IDraggers";
+
+export class Dragger implements IDragger {
+  name = "";
+
+  constructor(viewer: IViewer) {}
+
+  dispose(): void {}
+}

package/src/draggers/Draggers.ts

@@ -0,0 +1,71 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import type { IViewer } from "../viewer/IViewer";
+import { IDragger, IDraggerProvider, IDraggersMap, IDraggersRegistry } from "./IDraggers";
+
+class DraggersRegistry implements IDraggersRegistry {
+  private readonly _draggers = new Map<string, IDraggerProvider>();
+
+  registerDragger(name: string, provider: IDraggerProvider): void {
+    this._draggers.set(name, provider);
+  }
+
+  registerDraggerAlias(name: string, alias: string): void {
+    const provider = this.getDragger(name);
+    if (provider) this.registerDragger(alias, (viewer: IViewer) => provider(viewer));
+  }
+
+  getDragger(name: string): IDraggerProvider | undefined {
+    return this._draggers.get(name);
+  }
+
+  getDraggers(): IDraggersMap {
+    const map = new Map<string, IDraggerProvider>();
+    this._draggers.forEach((value, key) => map.set(key, value));
+    return map;
+  }
+
+  createDragger(name: string, viewer: IViewer): IDragger | null {
+    const provider = this.getDragger(name);
+    if (!provider) return null;
+
+    const dragger = provider(viewer);
+    dragger.name = name;
+
+    return dragger;
+  }
+}
+
+const _draggersRegistry = new Map<string, DraggersRegistry>();
+
+function draggersRegistry(viewerType = ""): IDraggersRegistry {
+  let result = _draggersRegistry.get(viewerType);
+  if (!result) {
+    result = new DraggersRegistry();
+    _draggersRegistry.set(viewerType, result);
+  }
+  return result;
+}
+
+export { draggersRegistry };

package/src/draggers/IDraggers.ts

@@ -0,0 +1,110 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import type { IViewer } from "../viewer/IViewer";
+
+/**
+ * Defines the dragger interface for the viewer.
+ */
+export interface IDragger {
+  /**
+   * The name of the dragger. Use this name to activate dragger using
+   * {@link Viewer.setActiveDragger | Viewer.setActiveDragger()}
+   */
+  name?: string;
+
+  /**
+   * Deprecated since `25.12`. Use costructor instead to initialize dragger.
+   *
+   * @deprecated
+   */
+  initialize?(): void;
+
+  /**
+   * Releases resources allocated by the dragger.
+   */
+  dispose(): void;
+
+  /**
+   * Deprecated since `25.12`. Instead, register an `update` event listener for the viewer and
+   * update the dragger preview in the event handler.
+   *
+   * @deprecated
+   */
+  updatePreview?(): void;
+}
+
+/**
+ * Dragger provider is a function that creates a dragger instance for the specified viewer.
+ */
+export interface IDraggerProvider {
+  /**
+   * @param viewer - Viewer instance that creates the dragger.
+   */
+  (viewer: any): IDragger;
+}
+
+export type IDraggersMap = Map<string, IDraggerProvider>;
+
+/**
+ * Defines the viewer draggers registry interface.
+ */
+export interface IDraggersRegistry {
+  /**
+   * Binds a dragger name to a dragger provider. Registering a dragger with an existing name
+   * twice overrides the existing dragger.
+   *
+   * @param name - Unique name for the dragger.
+   * @param provider - Dragger provider.
+   */
+  registerDragger(name: string, provider: IDraggerProvider): void;
+
+  /**
+   * Registers an alias for a dragger.
+   *
+   * @param name - Unique name for the dragger.
+   * @param alias - Dragger alias string.
+   */
+  registerDraggerAlias(name: string, alias: string): void;
+
+  /**
+   * Returns a list of registered draggers.
+   */
+  getDraggers(): IDraggersMap;
+
+  /**
+   * Returns the specified dragger provider or `undefined` when the dragger doesn't exists.
+   *
+   * @param name - Dragger name.
+   */
+  getDragger(name: string): IDraggerProvider | undefined;
+
+  /**
+   * Creates the dragger denoted by the given name. Returns `null` if a dragger with given name
+   * not registered.
+   *
+   * @param name - Dragger name.
+   * @param viewer - Viewer instance that wants to create the dragger.
+   */
+  createDragger(name: string, viewer: IViewer): IDragger | null;
+}

package/src/index.ts

@@ -23,11 +23,16 @@
 
 export * from "./commands/Commands";
 export * from "./commands/ICommands";
+export * from "./draggers/Dragger";
+export * from "./draggers/Draggers";
+export * from "./draggers/IDraggers";
+export * from "./components/Component";
+export * from "./components/Components";
+export * from "./components/IComponents";
 export * from "./options/IOptions";
 export * from "./options/Options";
 export * from "./options/OptionsEvents";
 export * from "./viewer/CanvasEvents";
-export * from "./viewer/IDragger";
 export * from "./viewer/IViewer";
 export * from "./viewer/IViewpoint";
 export * from "./viewer/ViewerEvents";

package/src/viewer/IViewer.ts

@@ -25,7 +25,8 @@ import { IEventEmitter } from "@inweb/eventemitter2";
 import { Assembly, Client, File, Model } from "@inweb/client";
 import { ICommandService } from "../commands/ICommands";
 import { IOptions } from "../options/IOptions";
-import { IDragger } from "./IDragger";
+import { IDragger } from "../draggers/IDraggers";
+import { IComponent } from "../components/IComponents";
 import { IViewpoint } from "./IViewpoint";
 
 /**
@@ -79,9 +80,27 @@ export interface IViewer extends IEventEmitter, ICommandService {
 
   /**
    * List of names of available draggers.
+   *
+   * The following draggers are available by default:
+   *
+   * - `Pan`
+   * - `Orbit`
+   * - `Zoom`
+   * - `MeasureLine`
+   * - `CuttingPlaneXAxis`
+   * - `CuttingPlaneYAxis`
+   * - `CuttingPlaneZAxis`
+   * - `Walk`
+   *
+   * For a quick reference on how to implement your own dragger, see {@link IDragger}.
    */
   draggers: string[];
 
+  /**
+   * List of names of available components.
+   */
+  components: string[];
+
   /**
    * Initializes the viewer it with the specified canvas. Call {@link dispose | dispose()} to
    * release allocated resources.
@@ -285,6 +304,11 @@ export interface IViewer extends IEventEmitter, ICommandService {
    */
   resetActiveDragger(): void;
 
+  /**
+   * Returns the component reference, or `null` if there is no component with the specified name.
+   */
+  getComponent(name: string): IComponent | null;
+
   /**
    * Sets the viewer state to the specified viewpoint.
    *

package/src/viewer/IViewpoint.ts

@@ -415,9 +415,9 @@ export interface IColoring {
 }
 
 /**
- * Defines the component in the model.
+ * Defines the entity in the model.
  */
-export interface IComponent {
+export interface IEntity {
   /**
    * Component original handle in the model.
    */
@@ -505,12 +505,12 @@ export interface IViewpoint {
   /**
    * Selected components.
    */
-  selection?: IComponent[];
+  selection?: IEntity[];
 
   /**
    * Visibility of components.
    */
-  visibility?: IComponent[];
+  visibility?: IEntity[];
 
   /**
    * Colored components.

package/lib/viewer/IDragger.d.ts

@@ -1,53 +0,0 @@
-import type { IViewer } from "./IViewer";
-/**
- * Defines the dragger of the viewer.
- */
-export interface IDragger {
-    /**
-     * The name of the dragger. Use this name to activate dragger using
-     * {@link Viewer.setActiveDragger | Viewer.setActiveDragger()}
-     */
-    name: string;
-    /**
-     * Initializes the dragger instance. Call {@link dispose | dispose()} to release allocated resources.
-     *
-     * This is internal method, called by the {@link Viewer} when the dragger is activated. Do not
-     * call this directly.
-     */
-    initialize(): void;
-    /**
-     * Releases resources allocated in the {@link initialize | initialize()}.
-     *
-     * This is internal method, called by the {@link Viewer} when the dragger is deactivated. Do
-     * not call this directly.
-     */
-    dispose(): void;
-    /**
-     * Updates the dragger preview if exists.
-     *
-     * This is internal method, called by the {@link Viewer} when it updates. Do not call this
-     * method directly unless you are manually updating the viewer.
-     */
-    updatePreview(): void;
-}
-/**
- * Base class for the viewer draggers.
- *
- * To create your own dragger:
- *
- * 1. Define a dragger class inherited from Dragger.
- * 2. Override {@link initialize | initialize()} method to add mouse event listeners using
- *    {@link Viewer.addEventListener | Viewer.addEventListener()}.
- * 3. Define the dragger logic in the event listeners. For example, listen for the `mousemove`
- *    event and zoom in/out when the left mouse button is pressed.
- * 4. Override {@link dispose | dispose()} method to remove mouse event listeners
- *    {@link Viewer.removeEventListener | Viewer.removeEventListener()}.
- * 5. Register dragger class for the viewer instance.
- */
-export declare class Dragger implements IDragger {
-    name: string;
-    constructor(viewer: IViewer);
-    initialize(): void;
-    dispose(): void;
-    updatePreview(): void;
-}

package/src/viewer/IDragger.ts

@@ -1,85 +0,0 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
-// All rights reserved.
-//
-// This software and its documentation and related materials are owned by
-// the Alliance. The software may only be incorporated into application
-// programs owned by members of the Alliance, subject to a signed
-// Membership Agreement and Supplemental Software License Agreement with the
-// Alliance. The structure and organization of this software are the valuable
-// trade secrets of the Alliance and its suppliers. The software is also
-// protected by copyright law and international treaty provisions. Application
-// programs incorporating this software must include the following statement
-// with their copyright notices:
-//
-//   This application incorporates Open Design Alliance software pursuant to a
-//   license agreement with Open Design Alliance.
-//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
-//   All rights reserved.
-//
-// By use of this software, its documentation or related materials, you
-// acknowledge and accept the above terms.
-///////////////////////////////////////////////////////////////////////////////
-
-import type { IViewer } from "./IViewer";
-
-/**
- * Defines the dragger of the viewer.
- */
-export interface IDragger {
-  /**
-   * The name of the dragger. Use this name to activate dragger using
-   * {@link Viewer.setActiveDragger | Viewer.setActiveDragger()}
-   */
-  name: string;
-
-  /**
-   * Initializes the dragger instance. Call {@link dispose | dispose()} to release allocated resources.
-   *
-   * This is internal method, called by the {@link Viewer} when the dragger is activated. Do not
-   * call this directly.
-   */
-  initialize(): void;
-
-  /**
-   * Releases resources allocated in the {@link initialize | initialize()}.
-   *
-   * This is internal method, called by the {@link Viewer} when the dragger is deactivated. Do
-   * not call this directly.
-   */
-  dispose(): void;
-
-  /**
-   * Updates the dragger preview if exists.
-   *
-   * This is internal method, called by the {@link Viewer} when it updates. Do not call this
-   * method directly unless you are manually updating the viewer.
-   */
-  updatePreview(): void;
-}
-
-/**
- * Base class for the viewer draggers.
- *
- * To create your own dragger:
- *
- * 1. Define a dragger class inherited from Dragger.
- * 2. Override {@link initialize | initialize()} method to add mouse event listeners using
- *    {@link Viewer.addEventListener | Viewer.addEventListener()}.
- * 3. Define the dragger logic in the event listeners. For example, listen for the `mousemove`
- *    event and zoom in/out when the left mouse button is pressed.
- * 4. Override {@link dispose | dispose()} method to remove mouse event listeners
- *    {@link Viewer.removeEventListener | Viewer.removeEventListener()}.
- * 5. Register dragger class for the viewer instance.
- */
-export class Dragger implements IDragger {
-  name = "";
-
-  constructor(viewer: IViewer) {}
-
-  initialize(): void {}
-
-  dispose(): void {}
-
-  updatePreview(): void {}
-}