feat(bounding-box): support bounding box highlights in ImageAnnotator (#740)

dlasecki-box · web-flow · commit 43039365f866 · 2026-04-16T19:52:18.000+02:00
* feat(bounding-box): support for rendering bounding boxes on images
diff --git a/src/common/BaseAnnotator.ts b/src/common/BaseAnnotator.ts
@@ -7,9 +7,10 @@ import EventEmitter from './EventEmitter';
 import i18n from '../utils/i18n';
 import messages from '../messages';
 import { Event, IntlOptions, LegacyEvent, Permissions } from '../@types';
-import { BoundingBox } from '../store/boundingBoxHighlights/types';
+import { BoundingBox, getBoundingBoxHighlights } from '../store/boundingBoxHighlights';
 import { ViewMode } from '../store/options/types';
 import { Features } from '../BoxAnnotations';
+import { scrollToLocation } from '../utils/scroll';
 import './BaseAnnotator.scss';
 
 export type Container = string | HTMLElement;
@@ -185,9 +186,43 @@ export default class BaseAnnotator extends EventEmitter {
         // Called by box-content-preview
     }
 
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     public scrollToBoundingBoxHighlight(highlightId: string | null): void {
-        // Implemented in DocumentAnnotator
+        if (!highlightId || !this.annotatedEl) {
+            return;
+        }
+
+        const highlights = getBoundingBoxHighlights(this.store.getState());
+        const highlight = highlights.find((h: BoundingBox) => h.id === highlightId);
+
+        if (!highlight) {
+            return;
+        }
+
+        const referenceEl = this.getScrollReferenceForHighlight(highlight);
+        if (!referenceEl) {
+            return;
+        }
+
+        const offsets = {
+            x: highlight.x + highlight.width / 2,
+            y: highlight.y + highlight.height / 2,
+        };
+
+        scrollToLocation(this.annotatedEl, referenceEl, {
+            offsets: this.getAdjustedScrollOffsets(offsets),
+            smooth: true,
+        });
+    }
+
+    /** Returns the element to scroll relative to for the given bounding box highlight. */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    protected getScrollReferenceForHighlight(_highlight: BoundingBox): HTMLElement | null | undefined {
+        return undefined; // Must be implemented in child class
+    }
+
+    /** Adjusts scroll offsets before passing to scrollToLocation (e.g. to apply rotation). */
+    protected getAdjustedScrollOffsets(offsets: { x: number; y: number }): { x: number; y: number } {
+        return offsets;
     }
 
     /**
diff --git a/src/document/DocumentAnnotator.ts b/src/document/DocumentAnnotator.ts
@@ -12,7 +12,7 @@ import { BoundingBoxHighlightManager } from '../boundingBoxHighlight';
 import { centerRegion, isRegion, RegionCreationManager, RegionManager } from '../region';
 import { Event } from '../@types';
 import { getAnnotation } from '../store/annotations';
-import { getBoundingBoxHighlights, BoundingBox } from '../store/boundingBoxHighlights';
+import { BoundingBox } from '../store/boundingBoxHighlights';
 import { getSelection } from './docUtil';
 import { Manager } from '../common/BaseManager';
 import { getFileId, getIsCurrentFileVersion, getViewMode, Mode } from '../store';
@@ -235,28 +235,7 @@ export default class DocumentAnnotator extends BaseAnnotator {
         }
     }
 
-    scrollToBoundingBoxHighlight(highlightId: string | null): void {
-        if (!highlightId || !this.annotatedEl) {
-            return;
-        }
-
-        const highlights = getBoundingBoxHighlights(this.store.getState());
-        const highlight = highlights.find((h: BoundingBox) => h.id === highlightId);
-
-        if (!highlight) {
-            return;
-        }
-
-        const pageEl = this.getPage(highlight.pageNumber);
-        if (!pageEl) {
-            return;
-        }
-
-        const offsets = {
-            x: highlight.x + highlight.width / 2,
-            y: highlight.y + highlight.height / 2,
-        };
-
-        scrollToLocation(this.annotatedEl, pageEl, { offsets, smooth: true });
+    protected getScrollReferenceForHighlight(highlight: BoundingBox): HTMLElement | undefined {
+        return this.getPage(highlight.pageNumber);
     }
 }
diff --git a/src/image/ImageAnnotator.ts b/src/image/ImageAnnotator.ts
@@ -1,22 +1,28 @@
 import { Unsubscribe } from 'redux';
 import BaseAnnotator, { Options } from '../common/BaseAnnotator';
 import PopupManager from '../popup/PopupManager';
+import { BoundingBoxHighlightManager } from '../boundingBoxHighlight';
 import { centerDrawing, DrawingManager, isDrawing } from '../drawing';
 import { centerRegion, isRegion, RegionCreationManager, RegionManager } from '../region';
 import { CreatorStatus, getCreatorStatus } from '../store/creator';
-import { getAnnotation, getFileId, getIsCurrentFileVersion, getRotation } from '../store';
+import { getAnnotation, getFileId, getIsCurrentFileVersion, getRotation, getViewMode } from '../store';
 import { getRotatedPosition } from '../utils/rotate';
 import { Manager } from '../common/BaseManager';
 import { scrollToLocation } from '../utils/scroll';
 import './ImageAnnotator.scss';
 
+import type { ViewMode } from '../store/options/types';
+
 export const CSS_IS_DRAWING_CLASS = 'ba-is-drawing';
 
 export default class ImageAnnotator extends BaseAnnotator {
     annotatedEl?: HTMLElement;
 
     managers: Set<Manager> = new Set();
 
+    /** Tracks which view mode the current managers were created for. Used to destroy/recreate when switching. */
+    private managersViewMode: ViewMode | null = null;
+
     storeHandler?: Unsubscribe;
 
     constructor(options: Options) {
@@ -41,10 +47,18 @@ export default class ImageAnnotator extends BaseAnnotator {
         return this.containerEl?.querySelector('.bp-image');
     }
 
+    /** Destroys all managers and clears the cache. Call when switching view modes. */
+    private clearManagers(): void {
+        this.managers.forEach(manager => manager.destroy());
+        this.managers.clear();
+        this.managersViewMode = null;
+    }
+
     getManagers(parentEl: HTMLElement, referenceEl: HTMLElement): Set<Manager> {
         const fileId = getFileId(this.store.getState());
         const isCurrentFileVersion = getIsCurrentFileVersion(this.store.getState());
         const resinTags = { fileid: fileId, iscurrent: isCurrentFileVersion };
+        const viewMode = getViewMode(this.store.getState());
 
         this.managers.forEach(manager => {
             if (!manager.exists(parentEl)) {
@@ -54,6 +68,11 @@ export default class ImageAnnotator extends BaseAnnotator {
         });
 
         if (this.managers.size === 0) {
+            if (viewMode === 'boundingBoxes') {
+                this.managers.add(new BoundingBoxHighlightManager({ location: 1, referenceEl, resinTags }));
+                return this.managers;
+            }
+
             this.managers.add(new PopupManager({ referenceEl, resinTags }));
             this.managers.add(new DrawingManager({ referenceEl, resinTags }));
             this.managers.add(new RegionManager({ referenceEl, resinTags }));
@@ -84,11 +103,17 @@ export default class ImageAnnotator extends BaseAnnotator {
     render(): void {
         const referenceEl = this.getReference();
         const rotation = getRotation(this.store.getState()) || 0;
+        const viewMode = getViewMode(this.store.getState());
 
         if (!this.annotatedEl || !referenceEl) {
             return;
         }
 
+        if (this.managersViewMode !== null && this.managersViewMode !== viewMode) {
+            this.clearManagers();
+        }
+        this.managersViewMode = viewMode;
+
         this.getManagers(this.annotatedEl, referenceEl).forEach(manager => {
             manager.style({
                 height: `${referenceEl.offsetHeight}px`,
@@ -107,6 +132,27 @@ export default class ImageAnnotator extends BaseAnnotator {
         this.postRender();
     }
 
+    public postRender(): void {
+        // DeselectManager is only needed for annotation creation; skip in bounding box mode.
+        if (getViewMode(this.store.getState()) === 'boundingBoxes') {
+            if (this.deselectManager) {
+                this.deselectManager.destroy();
+                this.deselectManager = null;
+            }
+            return;
+        }
+        super.postRender();
+    }
+
+    protected getScrollReferenceForHighlight(): HTMLElement | null | undefined {
+        return this.getReference();
+    }
+
+    protected getAdjustedScrollOffsets(offsets: { x: number; y: number }): { x: number; y: number } {
+        const rotation = getRotation(this.store.getState()) || 0;
+        return getRotatedPosition(offsets, rotation);
+    }
+
     scrollToAnnotation(annotationId: string | null): void {
         if (!annotationId) {
             return;
diff --git a/src/image/__tests__/ImageAnnotator-test.ts b/src/image/__tests__/ImageAnnotator-test.ts
@@ -4,8 +4,11 @@ import ImageAnnotator, { CSS_IS_DRAWING_CLASS } from '../ImageAnnotator';
 import PopupManager from '../../popup/PopupManager';
 import RegionCreationManager from '../../region/RegionCreationManager';
 import RegionManager from '../../region/RegionManager';
+import { BoundingBoxHighlightManager } from '../../boundingBoxHighlight';
 import { Annotation } from '../../@types';
 import { CreatorStatus, fetchAnnotationsAction, setStatusAction } from '../../store';
+import { setViewModeAction } from '../../store/options';
+import { setBoundingBoxHighlightsAction } from '../../store/boundingBoxHighlights';
 import { annotations as drawings } from '../../drawing/__mocks__/drawingData';
 import { annotations as regions } from '../../region/__mocks__/data';
 import { scrollToLocation } from '../../utils/scroll';
@@ -14,6 +17,7 @@ jest.mock('../../common/DeselectManager');
 jest.mock('../../popup/PopupManager');
 jest.mock('../../region/RegionCreationManager');
 jest.mock('../../region/RegionManager');
+jest.mock('../../boundingBoxHighlight');
 jest.mock('../../utils/scroll');
 
 describe('ImageAnnotator', () => {
@@ -123,6 +127,16 @@ describe('ImageAnnotator', () => {
             expect(mockManager.destroy).not.toHaveBeenCalled();
             expect(managers.values().next().value).toEqual(mockManager);
         });
+
+        test('should create only BoundingBoxHighlightManager when viewMode is boundingBoxes', () => {
+            annotator.store.dispatch(setViewModeAction('boundingBoxes'));
+
+            const managers = annotator.getManagers(getParent(), getImage());
+            const managerArray = Array.from(managers);
+
+            expect(managerArray).toHaveLength(1);
+            expect(managerArray[0]).toBeInstanceOf(BoundingBoxHighlightManager);
+        });
     });
 
     describe('getReference()', () => {
@@ -227,6 +241,97 @@ describe('ImageAnnotator', () => {
             expect(annotator.deselectManager).toBeInstanceOf(DeselectManager);
             expect(annotator.deselectManager!.render).toHaveBeenCalled();
         });
+
+        test('should not instantiate DeselectManager when in bounding box mode', () => {
+            annotator.annotatedEl = getParent();
+            annotator.store.dispatch(setViewModeAction('boundingBoxes'));
+
+            annotator.render();
+
+            expect(annotator.deselectManager).toBeNull();
+        });
+
+        test('should destroy existing DeselectManager when switching to bounding box mode', () => {
+            annotator.annotatedEl = getParent();
+
+            annotator.render();
+            expect(annotator.deselectManager).toBeInstanceOf(DeselectManager);
+
+            const destroySpy = annotator.deselectManager!.destroy as jest.Mock;
+
+            annotator.store.dispatch(setViewModeAction('boundingBoxes'));
+            annotator.render();
+
+            expect(destroySpy).toHaveBeenCalled();
+            expect(annotator.deselectManager).toBeNull();
+        });
+
+        test('should clear all managers when view mode changes', () => {
+            annotator.annotatedEl = getParent();
+
+            const destroySpy = jest.fn();
+            const existingSpy = jest.fn().mockReturnValue(true);
+            const mgr = { destroy: destroySpy, exists: existingSpy, render: jest.fn(), style: jest.fn() };
+            annotator.managers = new Set([mgr]);
+
+            // First render keeps managers because exists() returns true
+            annotator.render();
+
+            expect(annotator.managers.size).toBe(1);
+
+            annotator.store.dispatch(setViewModeAction('boundingBoxes'));
+            annotator.render();
+
+            expect(destroySpy).toHaveBeenCalled();
+        });
+    });
+
+    describe('scrollToBoundingBoxHighlight()', () => {
+        const boundingBoxes = [
+            { id: 'box-1', x: 10, y: 20, width: 30, height: 40, pageNumber: 1 },
+            { id: 'box-2', x: 50, y: 60, width: 70, height: 80, pageNumber: 1 },
+        ];
+
+        beforeEach(() => {
+            annotator.annotatedEl = getParent();
+            annotator.store.dispatch(setBoundingBoxHighlightsAction(boundingBoxes));
+        });
+
+        test('should call scrollToLocation with center offsets and smooth scrolling', () => {
+            jest.spyOn(annotator, 'getReference').mockImplementation(getImage);
+
+            annotator.scrollToBoundingBoxHighlight('box-1');
+
+            expect(scrollToLocation).toHaveBeenCalledWith(getParent(), getImage(), {
+                offsets: { x: 25, y: 40 },
+                smooth: true,
+            });
+        });
+
+        test('should do nothing if highlightId is null', () => {
+            annotator.scrollToBoundingBoxHighlight(null);
+            expect(scrollToLocation).not.toHaveBeenCalled();
+        });
+
+        test('should do nothing if annotatedEl is not defined', () => {
+            annotator.annotatedEl = undefined;
+            annotator.scrollToBoundingBoxHighlight('box-1');
+            expect(scrollToLocation).not.toHaveBeenCalled();
+        });
+
+        test('should do nothing if highlight is not found in the store', () => {
+            jest.spyOn(annotator, 'getReference').mockImplementation(getImage);
+
+            annotator.scrollToBoundingBoxHighlight('nonexistent');
+            expect(scrollToLocation).not.toHaveBeenCalled();
+        });
+
+        test('should do nothing if reference element is not defined', () => {
+            jest.spyOn(annotator, 'getReference').mockReturnValue(undefined);
+
+            annotator.scrollToBoundingBoxHighlight('box-1');
+            expect(scrollToLocation).not.toHaveBeenCalled();
+        });
     });
 
     describe('scrollToAnnotation()', () => {
