vim-web 0.3.44-dev.61 → 0.3.44-dev.63

package/dist/types/core-viewers/shared/selection.d.ts

@@ -1,45 +1,105 @@
 import { ISignal } from "ste-signals";
 import { IVimObject, IVim } from "./vim";
 import { THREE } from "../..";
-export interface ISelection<T extends IVimObject> {
-    select(object: T | T[]): void;
-    toggle(object: T | T[]): void;
-    add(object: T | T[]): void;
-    remove(object: T | T[]): void;
-    clear(): void;
-    getAll(): T[];
-    GetFromVim(vim: IVim<T>): T[];
-    removeFromVim(vim: IVim<T>): void;
-    getBoundingBox(): Promise<THREE.Box3>;
-    count(): number;
-    any(): boolean;
-    has(object: T): boolean;
-    onSelectionChanged: ISignal;
-}
 export interface ISelectionAdapter<T extends IVimObject> {
     outline(object: T, state: boolean): void;
 }
-export declare class Selection<T extends IVimObject> implements ISelection<T> {
+/**
+ * Represents a selection manager that supports adding, removing, toggling, and querying selected objects.
+ * The selection change signal is debounced to dispatch only once per animation frame.
+ */
+export declare class Selection<T extends IVimObject> {
     private _onSelectionChanged;
     private _selection;
     private _adapter;
+    /**
+     * If true, reselecting the currently selected single object will toggle it instead of doing nothing.
+     */
+    toggleOnRepeatSelect: boolean;
+    /**
+     * If true, the selection manager is enabled and can modify the selection.
+     */
+    enabled: boolean;
+    /**
+     * Creates a new Selection manager.
+     * @param adapter - Adapter responsible for visual selection feedback.
+     */
     constructor(adapter: ISelectionAdapter<T>);
+    /**
+     * Checks whether a specific object is currently selected.
+     * @param object - The object to check.
+     * @returns `true` if the object is selected; otherwise, `false`.
+     */
     has(object: T): boolean;
+    /**
+     * Returns the number of selected objects.
+     * @returns The count of selected items.
+     */
     count(): number;
+    /**
+     * Checks if there is at least one selected object.
+     * @returns `true` if the selection is not empty.
+     */
     any(): boolean;
+    /**
+     * Signal that fires when the selection changes.
+     */
     get onSelectionChanged(): ISignal;
-    private _dispatchIfChanged;
+    /**
+     * Normalizes a value to an array of objects.
+     * @param oneOrMore - A single object or an array of objects.
+     * @returns An array of objects.
+     */
+    private toArray;
+    /**
+     * Replaces the current selection with the given object(s).
+     * If `toggleOnRepeatSelect` is true and the object is already the only selected one, it toggles it instead.
+     * @param objectOrObjects - Object(s) to select, or `undefined` to clear the selection.
+     */
     select(object: T): void;
     select(objects: T[]): void;
+    /**
+     * Toggles the selection state of the given object(s).
+     * @param objectOrObjects - Object(s) to toggle.
+     */
     toggle(object: T): void;
     toggle(objects: T[]): void;
+    /**
+     * Adds the given object(s) to the selection.
+     * @param objectOrObjects - Object(s) to add.
+     */
     add(object: T): void;
     add(objects: T[]): void;
+    /**
+     * Removes the given object(s) from the selection.
+     * @param objectOrObjects - Object(s) to remove.
+     */
     remove(object: T): void;
     remove(objects: T[]): void;
+    /**
+     * Clears the entire selection.
+     */
     clear(): void;
+    /**
+     * Returns an array of all currently selected objects.
+     * @returns An array of selected objects.
+     */
     getAll(): T[];
-    GetFromVim(vim: IVim<T>): T[];
+    /**
+     * Returns all selected objects belonging to a specific VIM model.
+     * @param vim - The VIM instance to filter by.
+     * @returns An array of selected objects from the specified VIM.
+     */
+    getFromVim(vim: IVim<T>): T[];
+    /**
+     * Removes all selected objects that belong to a specific VIM model.
+     * @param vim - The VIM instance to remove selections from.
+     */
     removeFromVim(vim: IVim<T>): void;
+    /**
+     * Computes the bounding box that contains all selected objects.
+     * Skips objects that do not implement `getBoundingBox()`.
+     * @returns A promise resolving to the combined bounding box.
+     */
     getBoundingBox(): Promise<THREE.Box3>;
 }

package/dist/types/utils/debounce.d.ts

@@ -1 +1,30 @@
+import { ISignal } from 'ste-signals';
 export declare function debounce<T extends (...args: any[]) => void>(func: T, delay: number): [(...args: Parameters<T>) => void, () => void];
+/**
+ * A debounced signal that dispatches at most once per animation frame.
+ */
+export declare class DebouncedSignal {
+    private _dispatcher;
+    private _frameRequestId;
+    /**
+     * Indicates whether a dispatch is currently scheduled.
+     *
+     * @returns `true` if a dispatch is scheduled; otherwise `false`.
+     */
+    get isScheduled(): boolean;
+    /**
+     * Returns the signal interface that subscribers can listen to.
+     *
+     * @returns An `ISignal` that is dispatched once per frame when requested.
+     */
+    get signal(): ISignal;
+    /**
+     * Schedules the signal to be dispatched on the next animation frame.
+     * Has no effect if a dispatch is already scheduled.
+     */
+    requestDispatch(): void;
+    /**
+     * Cancels a scheduled signal dispatch if one exists.
+     */
+    cancel(): void;
+}

package/dist/vim-web.iife.js

@@ -50687,6 +50687,48 @@ void main() {
       }, delay);
     }, () => clearTimeout(timeoutId)];
   }
+  class DebouncedSignal {
+    constructor() {
+      __publicField(this, "_dispatcher", new distExports$1.SignalDispatcher());
+      __publicField(this, "_frameRequestId");
+    }
+    /**
+     * Indicates whether a dispatch is currently scheduled.
+     * 
+     * @returns `true` if a dispatch is scheduled; otherwise `false`.
+     */
+    get isScheduled() {
+      return this._frameRequestId !== void 0;
+    }
+    /**
+     * Returns the signal interface that subscribers can listen to.
+     * 
+     * @returns An `ISignal` that is dispatched once per frame when requested.
+     */
+    get signal() {
+      return this._dispatcher.asEvent();
+    }
+    /**
+     * Schedules the signal to be dispatched on the next animation frame.
+     * Has no effect if a dispatch is already scheduled.
+     */
+    requestDispatch() {
+      if (this._frameRequestId !== void 0) return;
+      this._frameRequestId = requestAnimationFrame(() => {
+        this._dispatcher.dispatch();
+        this._frameRequestId = void 0;
+      });
+    }
+    /**
+     * Cancels a scheduled signal dispatch if one exists.
+     */
+    cancel() {
+      if (this._frameRequestId !== void 0) {
+        cancelAnimationFrame(this._frameRequestId);
+        this._frameRequestId = void 0;
+      }
+    }
+  }
   function almostEqual(v1, v2, epsilon = 1e-6) {
     return Math.abs(v1.x - v2.x) < epsilon && Math.abs(v1.y - v2.y) < epsilon;
   }
@@ -55194,36 +55236,72 @@ void main() {
     }
   }
   class Selection {
+    /**
+     * Creates a new Selection manager.
+     * @param adapter - Adapter responsible for visual selection feedback.
+     */
     constructor(adapter) {
-      __publicField(this, "_onSelectionChanged", new distExports$1.SignalDispatcher());
+      __publicField(this, "_onSelectionChanged", new DebouncedSignal());
       __publicField(this, "_selection", /* @__PURE__ */ new Set());
       __publicField(this, "_adapter");
+      /**
+       * If true, reselecting the currently selected single object will toggle it instead of doing nothing.
+       */
+      __publicField(this, "toggleOnRepeatSelect", false);
+      /**
+       * If true, the selection manager is enabled and can modify the selection.
+       */
+      __publicField(this, "enabled", true);
       this._adapter = adapter;
     }
+    /**
+     * Checks whether a specific object is currently selected.
+     * @param object - The object to check.
+     * @returns `true` if the object is selected; otherwise, `false`.
+     */
     has(object) {
       return this._selection.has(object);
     }
+    /**
+     * Returns the number of selected objects.
+     * @returns The count of selected items.
+     */
     count() {
       return this._selection.size;
     }
+    /**
+     * Checks if there is at least one selected object.
+     * @returns `true` if the selection is not empty.
+     */
     any() {
       return this._selection.size > 0;
     }
+    /**
+     * Signal that fires when the selection changes.
+     */
     get onSelectionChanged() {
-      return this._onSelectionChanged.asEvent();
+      return this._onSelectionChanged.signal;
     }
-    _dispatchIfChanged(prevSize, modified) {
-      if (modified || this._selection.size !== prevSize) {
-        this._onSelectionChanged.dispatch();
-      }
+    /**
+     * Normalizes a value to an array of objects.
+     * @param oneOrMore - A single object or an array of objects.
+     * @returns An array of objects.
+     */
+    toArray(oneOrMore) {
+      return Array.isArray(oneOrMore) ? oneOrMore : [oneOrMore];
     }
     select(objectOrObjects) {
+      if (!this.enabled) return;
       if (!objectOrObjects) {
         this.clear();
         return;
       }
-      const objects = Array.isArray(objectOrObjects) ? objectOrObjects : [objectOrObjects];
-      if (objects.length === 1 && this._selection.size === 1 && this._selection.has(objects[0])) {
+      const objects = this.toArray(objectOrObjects);
+      const isRepeatSingleSelection = objects.length === 1 && this._selection.size === 1 && this._selection.has(objects[0]);
+      if (isRepeatSingleSelection) {
+        if (this.toggleOnRepeatSelect) {
+          this.toggle(objects);
+        }
         return;
       }
       for (const obj of this._selection) {
@@ -55234,77 +55312,105 @@ void main() {
         this._selection.add(obj);
         this._adapter.outline(obj, true);
       }
-      this._onSelectionChanged.dispatch();
+      this._onSelectionChanged.requestDispatch();
     }
     toggle(objectOrObjects) {
-      const objects = Array.isArray(objectOrObjects) ? objectOrObjects : [objectOrObjects];
-      const prevSize = this._selection.size;
-      let modified = false;
+      if (!this.enabled) return;
+      const objects = this.toArray(objectOrObjects);
+      let changed = false;
       for (const obj of objects) {
         if (this._selection.has(obj)) {
           this._selection.delete(obj);
           this._adapter.outline(obj, false);
-          modified = true;
+          changed = true;
         } else {
           this._selection.add(obj);
           this._adapter.outline(obj, true);
-          modified = true;
+          changed = true;
         }
       }
-      this._dispatchIfChanged(prevSize, modified);
+      if (changed) {
+        this._onSelectionChanged.requestDispatch();
+      }
     }
     add(objectOrObjects) {
-      const objects = Array.isArray(objectOrObjects) ? objectOrObjects : [objectOrObjects];
-      const prevSize = this._selection.size;
-      let anyNew = false;
+      if (!this.enabled) return;
+      const objects = this.toArray(objectOrObjects);
+      let changed = false;
       for (const obj of objects) {
         if (!this._selection.has(obj)) {
           this._selection.add(obj);
           this._adapter.outline(obj, true);
-          anyNew = true;
+          changed = true;
         }
       }
-      this._dispatchIfChanged(prevSize, anyNew);
+      if (changed) {
+        this._onSelectionChanged.requestDispatch();
+      }
     }
     remove(objectOrObjects) {
-      const objects = Array.isArray(objectOrObjects) ? objectOrObjects : [objectOrObjects];
-      const prevSize = this._selection.size;
-      let removedAny = false;
+      if (!this.enabled) return;
+      const objects = this.toArray(objectOrObjects);
+      let changed = false;
       for (const obj of objects) {
         if (this._selection.delete(obj)) {
           this._adapter.outline(obj, false);
-          removedAny = true;
+          changed = true;
         }
       }
-      this._dispatchIfChanged(prevSize, removedAny);
+      if (changed) {
+        this._onSelectionChanged.requestDispatch();
+      }
     }
+    /**
+     * Clears the entire selection.
+     */
     clear() {
-      if (this._selection.size > 0) {
-        for (const obj of this._selection) {
-          this._adapter.outline(obj, false);
-        }
-        this._selection.clear();
-        this._onSelectionChanged.dispatch();
+      if (!this.enabled) return;
+      if (this._selection.size === 0) return;
+      for (const obj of this._selection) {
+        this._adapter.outline(obj, false);
       }
+      this._selection.clear();
+      this._onSelectionChanged.requestDispatch();
     }
+    /**
+     * Returns an array of all currently selected objects.
+     * @returns An array of selected objects.
+     */
     getAll() {
       return [...this._selection];
     }
-    GetFromVim(vim) {
+    /**
+     * Returns all selected objects belonging to a specific VIM model.
+     * @param vim - The VIM instance to filter by.
+     * @returns An array of selected objects from the specified VIM.
+     */
+    getFromVim(vim) {
       return [...this._selection].filter((obj) => obj.vim === vim);
     }
+    /**
+     * Removes all selected objects that belong to a specific VIM model.
+     * @param vim - The VIM instance to remove selections from.
+     */
     removeFromVim(vim) {
-      const prevSize = this._selection.size;
-      let removed = false;
+      let changed = false;
       for (const obj of [...this._selection]) {
         if (obj.vim === vim) {
           this._selection.delete(obj);
           this._adapter.outline(obj, false);
-          removed = true;
+          changed = true;
         }
       }
-      this._dispatchIfChanged(prevSize, removed);
+      if (changed) {
+        this._onSelectionChanged.requestDispatch();
+      }
     }
+    /**
+     * Computes the bounding box that contains all selected objects.
+     * Skips objects that do not implement `getBoundingBox()`.
+     * @returns A promise resolving to the combined bounding box.
+     */
     async getBoundingBox() {
       var _a3;
       const box = new Box3();