box-annotations 5.2.1-beta.2 → 5.2.1-beta.5

package/i18n/en-US.js

@@ -4,6 +4,8 @@ export default {
   "ba.annotationsLoadError": "We’re sorry, the annotations failed to load for this file.",
   "ba.annotationsPost": "Post",
   "ba.annotationsSave": "Save",
+  "ba.boundingBoxHighlight.viewNextReference": "View next reference",
+  "ba.boundingBoxHighlight.viewPrevReference": "View previous reference",
   "ba.popup.reply.comment": "Comment",
   "ba.popup.reply.field": "Type a comment",
   "ba.popups.cancel": "Cancel",

package/i18n/en-US.properties

@@ -8,6 +8,10 @@ ba.annotationsLoadError = We’re sorry, the annotations failed to load for this
 ba.annotationsPost = Post
 # Label for the save button
 ba.annotationsSave = Save
+# Aria label for the button to view the next reference
+ba.boundingBoxHighlight.viewNextReference = View next reference
+# Aria label for the button to view the previous reference
+ba.boundingBoxHighlight.viewPrevReference = View previous reference
 # Aria label description for reply popup
 ba.popup.reply.comment = Comment
 # Aria label description for annotation comment field

package/i18n/json/src/components/BoundingBoxHighlight/messages.json

@@ -0,0 +1 @@
+[{"id":"ba.boundingBoxHighlight.viewNextReference","description":"Aria label for the button to view the next reference","defaultMessage":"View next reference"},{"id":"ba.boundingBoxHighlight.viewPrevReference","description":"Aria label for the button to view the previous reference","defaultMessage":"View previous reference"}]

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "box-annotations",
-    "version": "5.2.1-beta.2",
+    "version": "5.2.1-beta.5",
     "description": "Box Annotations",
     "author": "Box (https://www.box.com/)",
     "license": "SEE LICENSE IN LICENSE",

package/src/@types/events.ts

@@ -9,7 +9,11 @@ enum Event {
     ANNOTATIONS_INITIALIZED = 'annotations_initialized',
     ANNOTATIONS_MODE_CHANGE = 'annotations_mode_change',
     COLOR_SET = 'annotations_color_set',
+    BOUNDING_BOX_HIGHLIGHTS_SET = 'bounding_box_highlights_set',
+    BOUNDING_BOX_HIGHLIGHT_NAVIGATE = 'bounding_box_highlight_navigate',
+    BOUNDING_BOX_HIGHLIGHT_SELECT = 'bounding_box_highlight_select',
     VISIBLE_SET = 'annotations_visible_set',
+    VIEW_MODE_SET = 'view_mode_set',
 }
 
 // Existing legacy events, don't rename

package/src/boundingBoxHighlight/BoundingBoxHighlightContainer.tsx

@@ -0,0 +1,33 @@
+import { connect } from 'react-redux';
+import { BoundingBoxHighlightList } from '../components/BoundingBoxHighlight';
+import withProviders from '../common/withProviders';
+import {
+    AppState,
+    BoundingBox,
+    getBoundingBoxHighlights,
+    getBoundingBoxHighlightsForPage,
+    getSelectedBoundingBoxHighlightId,
+    navigateBoundingBoxHighlightAction,
+    setSelectedBoundingBoxHighlightAction,
+} from '../store';
+
+export type Props = {
+    location: number;
+};
+
+const mapStateToProps = (state: AppState, { location }: Props): {
+    allBoundingBoxes: BoundingBox[];
+    boundingBoxes: BoundingBox[];
+    selectedId: string | null;
+} => ({
+    allBoundingBoxes: getBoundingBoxHighlights(state),
+    boundingBoxes: getBoundingBoxHighlightsForPage(state, location),
+    selectedId: getSelectedBoundingBoxHighlightId(state),
+});
+
+const mapDispatchToProps = {
+    onNavigate: navigateBoundingBoxHighlightAction,
+    onSelect: setSelectedBoundingBoxHighlightAction,
+};
+
+export default connect(mapStateToProps, mapDispatchToProps)(withProviders(BoundingBoxHighlightList));

package/src/boundingBoxHighlight/BoundingBoxHighlightManager.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import * as ReactDOM from 'react-dom/client';
+import BaseManager, { Props } from '../common/BaseManager';
+import BoundingBoxHighlightContainer from './BoundingBoxHighlightContainer';
+
+export default class BoundingBoxHighlightManager extends BaseManager {
+    decorate(): void {
+        this.reactEl.classList.add('ba-Layer--boundingBoxHighlight');
+        this.reactEl.dataset.testid = 'ba-Layer--boundingBoxHighlight';
+    }
+
+    render(props: Props): void {
+        if (!this.root) {
+            this.root = ReactDOM.createRoot(this.reactEl);
+        }
+
+        this.root.render(<BoundingBoxHighlightContainer location={this.location} {...props} />);
+    }
+}

package/src/boundingBoxHighlight/index.ts

@@ -0,0 +1 @@
+export { default as BoundingBoxHighlightManager } from './BoundingBoxHighlightManager';

package/src/common/BaseAnnotator.ts

@@ -7,7 +7,10 @@ import EventEmitter from './EventEmitter';
 import i18n from '../utils/i18n';
 import messages from '../messages';
 import { Event, IntlOptions, LegacyEvent, Permissions } from '../@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;
@@ -37,6 +40,8 @@ export type Options = {
     hasTouch?: boolean;
     initialColor?: string;
     initialMode?: store.Mode;
+    /** View mode: annotations and bounding boxes are mutually exclusive. Defaults to 'annotations'. */
+    initialViewMode?: ViewMode;
     intl: IntlOptions;
     locale?: string;
     token: string;
@@ -72,6 +77,7 @@ export default class BaseAnnotator extends EventEmitter {
         fileOptions,
         initialColor,
         initialMode,
+        initialViewMode = 'annotations',
         intl,
         token,
     }: Options) {
@@ -93,6 +99,7 @@ export default class BaseAnnotator extends EventEmitter {
                 fileVersionId: fileOptionsVersionId ?? fileVersionId,
                 isCurrentFileVersion: !fileOptionsVersionId || fileOptionsVersionId === currentFileVersionId,
                 permissions: file.permissions,
+                viewMode: initialViewMode,
             },
         };
 
@@ -109,6 +116,10 @@ export default class BaseAnnotator extends EventEmitter {
         this.addListener(Event.ANNOTATION_REMOVE, this.handleRemove);
         this.addListener(Event.COLOR_SET, this.handleSetColor);
         this.addListener(Event.VISIBLE_SET, this.handleSetVisible);
+        this.addListener(Event.BOUNDING_BOX_HIGHLIGHTS_SET, this.handleSetBoundingBoxHighlights);
+        this.addListener(Event.BOUNDING_BOX_HIGHLIGHT_NAVIGATE, this.handleNavigateBoundingBoxHighlight);
+        this.addListener(Event.BOUNDING_BOX_HIGHLIGHT_SELECT, this.handleSelectBoundingBoxHighlight);
+        this.addListener(Event.VIEW_MODE_SET, this.handleSetViewMode);
 
         // Load any required data at startup
         this.hydrate();
@@ -134,14 +145,10 @@ export default class BaseAnnotator extends EventEmitter {
         this.removeListener(Event.ANNOTATION_REMOVE, this.handleRemove);
         this.removeListener(Event.COLOR_SET, this.handleSetColor);
         this.removeListener(Event.VISIBLE_SET, this.handleSetVisible);
-    }
-
-    public getActiveId(): string | null {
-        return store.getActiveAnnotationId(this.store.getState());
-    }
-
-    public getAnnotationContainerEl(): HTMLElement | null {
-        return this.containerEl ?? null;
+        this.removeListener(Event.BOUNDING_BOX_HIGHLIGHTS_SET, this.handleSetBoundingBoxHighlights);
+        this.removeListener(Event.BOUNDING_BOX_HIGHLIGHT_NAVIGATE, this.handleNavigateBoundingBoxHighlight);
+        this.removeListener(Event.BOUNDING_BOX_HIGHLIGHT_SELECT, this.handleSelectBoundingBoxHighlight);
+        this.removeListener(Event.VIEW_MODE_SET, this.handleSetViewMode);
     }
 
     public init(scale = 1, rotation = 0): void {
@@ -170,10 +177,6 @@ export default class BaseAnnotator extends EventEmitter {
         return getProp(this.features, feature, false);
     }
 
-    public isPopupOpen(): boolean {
-        return !!this.containerEl?.querySelector('.ba-Popup');
-    }
-
     public removeAnnotation = (annotationId: string): void => {
         this.store.dispatch(store.removeAnnotationAction(annotationId));
     };
@@ -183,6 +186,88 @@ export default class BaseAnnotator extends EventEmitter {
         // Called by box-content-preview
     }
 
+    public 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 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;
+    }
+
+    /**
+     * Sets the bounding box highlights to display. This replaces all existing bounding boxes.
+     * Triggers a re-render.
+     *
+     * Note: Bounding boxes are only visible when viewMode is set to 'boundingBoxes'.
+     *
+     * @param {BoundingBox[]} boundingBoxes - Array of bounding box definitions with coordinates and page numbers
+     */
+    public setBoundingBoxHighlights(boundingBoxes: BoundingBox[]): void {
+        this.store.dispatch(store.setBoundingBoxHighlightsAction(boundingBoxes));
+        this.render();
+    }
+
+    /**
+     * Sets the view mode for the annotator. Annotations and bounding boxes are mutually exclusive.
+     * Triggers a re-render.
+     *
+     * Side effects:
+     * - Switching to 'boundingBoxes': Clears active annotation ID
+     * - Switching to 'annotations': Clears selected bounding box ID
+     *
+     * @param {ViewMode} viewMode - Either 'annotations' (default) or 'boundingBoxes'
+     */
+    public setViewMode(viewMode: ViewMode): void {
+        this.store.dispatch(store.setViewModeAction(viewMode));
+        this.render();
+    }
+
+    /**
+     * Selects a bounding box highlight and scrolls to it. Pass null to deselect.
+     *
+     * Note: For programmatic navigation (prev/next), use the navigateBoundingBoxHighlightAction
+     * which emits BOUNDING_BOX_HIGHLIGHT_NAVIGATE events.
+     *
+     * @param {string | null} highlightId - The ID of the bounding box to select, or null to clear selection
+     */
+    public selectBoundingBoxHighlight(highlightId: string | null): void {
+        this.store.dispatch(store.setSelectedBoundingBoxHighlightAction(highlightId));
+        if (highlightId) {
+            this.scrollToBoundingBoxHighlight(highlightId);
+        }
+    }
+
     public setActiveId(annotationId: string | null): void {
         this.store.dispatch(store.setActiveAnnotationIdAction(annotationId));
     }
@@ -235,6 +320,22 @@ export default class BaseAnnotator extends EventEmitter {
         this.setColor(color);
     };
 
+    protected handleSetBoundingBoxHighlights = (boundingBoxes: BoundingBox[]): void => {
+        this.setBoundingBoxHighlights(boundingBoxes);
+    };
+
+    protected handleNavigateBoundingBoxHighlight = (highlightId: string): void => {
+        this.scrollToBoundingBoxHighlight(highlightId);
+    };
+
+    protected handleSelectBoundingBoxHighlight = (highlightId: string | null): void => {
+        this.selectBoundingBoxHighlight(highlightId);
+    };
+
+    protected handleSetViewMode = ({ viewMode }: { viewMode: ViewMode }): void => {
+        this.setViewMode(viewMode);
+    };
+
     protected hydrate(): void {
         // Redux dispatch method signature doesn't seem to like async actions
         this.store.dispatch<any>(store.fetchAnnotationsAction()); // eslint-disable-line @typescript-eslint/no-explicit-any

package/src/components/BoundingBoxHighlight/BoundingBoxHighlightList.scss

@@ -0,0 +1,8 @@
+.ba-BoundingBoxHighlightList {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+}

package/src/components/BoundingBoxHighlight/BoundingBoxHighlightList.tsx

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import BoundingBoxHighlightRect from './BoundingBoxHighlightRect';
+import { BoundingBox } from '../../store/boundingBoxHighlights/types';
+import './BoundingBoxHighlightList.scss';
+
+type Props = {
+    /**
+     * All bounding box highlights in the document.
+     */
+    allBoundingBoxes: BoundingBox[];
+    /**
+     * Bounding boxes on the current page.
+     */
+    boundingBoxes: BoundingBox[];
+    /**
+     * Callback invoked to navigate to the previous or next bounding box highlight.
+     */
+    onNavigate?: (id: string) => void;
+    /**
+     * Callback invoked when the user clicks on a bounding box highlight.
+     */
+    onSelect?: (id: string) => void;
+    /**
+     * The ID of the selected bounding box highlight.
+     */
+    selectedId: string | null;
+};
+
+const BoundingBoxHighlightList = ({
+    allBoundingBoxes,
+    boundingBoxes,
+    onNavigate,
+    onSelect,
+    selectedId,
+}: Props): React.ReactElement | null => {
+    const total = allBoundingBoxes.length;
+
+    if (total === 0) {
+        return null;
+    }
+
+    const selectedIndex = allBoundingBoxes.findIndex(h => h.id === selectedId);
+    const prevId = selectedIndex > 0 ? allBoundingBoxes[selectedIndex - 1].id : undefined;
+    const nextId = selectedIndex < total - 1 ? allBoundingBoxes[selectedIndex + 1].id : undefined;
+
+    return (
+        <div className="ba-BoundingBoxHighlightList" data-testid="ba-BoundingBoxHighlightList">
+            {boundingBoxes.map(bbox => {
+                return (
+                    <BoundingBoxHighlightRect
+                        key={bbox.id}
+                        boundingBox={bbox}
+                        currentIndex={selectedIndex}
+                        isSelected={selectedId === bbox.id}
+                        nextId={nextId}
+                        onNavigate={onNavigate}
+                        onSelect={onSelect}
+                        prevId={prevId}
+                        total={total}
+                    />
+                );
+            })}
+        </div>
+    );
+};
+
+export default React.memo(BoundingBoxHighlightList);

package/src/components/BoundingBoxHighlight/BoundingBoxHighlightNav.scss

@@ -0,0 +1,73 @@
+$ba-BoundingBoxHighlightNav-bg: #fff;
+$ba-BoundingBoxHighlightNav-shadow: 0 6px 20px rgba(0, 0, 0, .1);
+$ba-BoundingBoxHighlightNav-arrow: #909090;
+$ba-BoundingBoxHighlightNav-border: #e8e8e8;
+$ba-BoundingBoxHighlightNav-counter: #222;
+
+.ba-BoundingBoxHighlightNav {
+    position: absolute;
+    bottom: 100%;
+    left: 50%;
+    z-index: 1;
+    display: flex;
+    gap: 4px;
+    align-items: center;
+    margin-bottom: 6px;
+    padding: 3px;
+    white-space: nowrap;
+    background: $ba-BoundingBoxHighlightNav-bg;
+    border: 1px solid $ba-BoundingBoxHighlightNav-border;
+    border-radius: 20px;
+    box-shadow: $ba-BoundingBoxHighlightNav-shadow;
+    transform: translateX(-50%);
+    cursor: default;
+    pointer-events: auto;
+}
+
+.ba-BoundingBoxHighlightNav-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    line-height: 1;
+    background: transparent;
+    border: none;
+    border-radius: 50%;
+    cursor: pointer;
+    transition: background-color 150ms ease;
+
+    svg {
+        path {
+            fill: $ba-BoundingBoxHighlightNav-arrow;
+        }
+    }
+
+    &:hover:not(:disabled) {
+        background: rgba(0, 0, 0, .06);
+    }
+
+    &:active:not(:disabled) {
+        background: rgba(0, 0, 0, .12);
+    }
+
+    &:disabled {
+        cursor: default;
+
+        svg {
+            path {
+                fill: $ba-BoundingBoxHighlightNav-border;
+            }
+        }
+    }
+}
+
+.ba-BoundingBoxHighlightNav-counter {
+    padding: 0 4px;
+    color: $ba-BoundingBoxHighlightNav-counter;
+    font-weight: normal;
+    font-size: 15px;
+    font-family: Lato, Arial, sans-serif;
+    user-select: none;
+}

package/src/components/BoundingBoxHighlight/BoundingBoxHighlightNav.tsx

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import { useIntl } from 'react-intl';
+import ChevronLeft from '../../icons/ChevronLeft';
+import ChevronRight from '../../icons/ChevronRight';
+import messages from './messages';
+import './BoundingBoxHighlightNav.scss';
+
+type Props = {
+    currentIndex: number;
+    total: number;
+    onPrev: (event: React.MouseEvent) => void;
+    onNext: (event: React.MouseEvent) => void;
+};
+
+const BoundingBoxHighlightNav = ({ currentIndex, total, onPrev, onNext }: Props): JSX.Element => {
+    const intl = useIntl();
+    const isPrevDisabled = currentIndex === 0;
+    const isNextDisabled = currentIndex === total - 1;
+
+    return (
+        <div className="ba-BoundingBoxHighlightNav" data-testid="ba-BoundingBoxHighlightNav">
+            <button
+                aria-label={intl.formatMessage(messages.ariaLabelViewPrevReference)}
+                className="ba-BoundingBoxHighlightNav-btn"
+                data-testid="ba-BoundingBoxHighlightNav-prev"
+                disabled={isPrevDisabled}
+                onClick={onPrev}
+                type="button"
+            >
+                <ChevronLeft width={20} height={20} />
+            </button>
+            <span className="ba-BoundingBoxHighlightNav-counter">
+                {currentIndex + 1} / {total}
+            </span>
+            <button
+                aria-label={intl.formatMessage(messages.ariaLabelViewNextReference)}
+                className="ba-BoundingBoxHighlightNav-btn"
+                data-testid="ba-BoundingBoxHighlightNav-next"
+                disabled={isNextDisabled}
+                onClick={onNext}
+                type="button"
+            >
+                <ChevronRight width={20} height={20} />
+            </button>
+        </div>
+    );
+};
+
+export default BoundingBoxHighlightNav;

package/src/components/BoundingBoxHighlight/BoundingBoxHighlightRect.scss

@@ -0,0 +1,22 @@
+$ba-BoundingBoxHighlight-color: #0061d5;
+$ba-BoundingBoxHighlight-bgColor--default: rgba($ba-BoundingBoxHighlight-color, .05);
+$ba-BoundingBoxHighlight-bgColor--hover: rgba($ba-BoundingBoxHighlight-color, .16);
+$ba-BoundingBoxHighlight-bgColor--selected: rgba($ba-BoundingBoxHighlight-color, .1);
+
+.ba-BoundingBoxHighlightRect {
+    position: absolute;
+    box-sizing: border-box;
+    background-color: $ba-BoundingBoxHighlight-bgColor--default;
+    border: 2px solid rgba($ba-BoundingBoxHighlight-color, .2);
+    border-radius: 8px;
+    outline: none;
+    cursor: pointer;
+    transition: background-color 200ms ease, border-color 200ms ease, box-shadow 200ms ease;
+    pointer-events: auto;
+
+    &.is-selected {
+        background-color: $ba-BoundingBoxHighlight-bgColor--selected;
+        border-color: $ba-BoundingBoxHighlight-color;
+        box-shadow: 0 0 0 2px rgba($ba-BoundingBoxHighlight-color, .3), 0 4px 12px rgba(0, 0, 0, .15);
+    }
+}

package/src/components/BoundingBoxHighlight/BoundingBoxHighlightRect.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react';
+import classNames from 'classnames';
+import BoundingBoxHighlightNav from './BoundingBoxHighlightNav';
+import { BoundingBox } from '../../store/boundingBoxHighlights/types';
+import './BoundingBoxHighlightRect.scss';
+
+type Props = {
+    boundingBox: BoundingBox;
+    currentIndex: number;
+    isSelected?: boolean;
+    onNavigate?: (id: string) => void;
+    onSelect?: (id: string) => void;
+    total: number;
+    prevId?: string;
+    nextId?: string;
+};
+
+const BoundingBoxHighlightRect = ({
+    boundingBox,
+    currentIndex,
+    isSelected,
+    onNavigate,
+    onSelect,
+    total,
+    prevId,
+    nextId,
+}: Props): JSX.Element => {
+    const { id, x, y, width, height } = boundingBox;
+
+    const style: React.CSSProperties = {
+        display: 'block',
+        left: `${x}%`,
+        top: `${y}%`,
+        width: `${width}%`,
+        height: `${height}%`,
+    };
+
+    const handleClick = (event: React.MouseEvent): void => {
+        event.stopPropagation();
+        onSelect?.(id);
+    };
+
+    const handlePrev = (event: React.MouseEvent): void => {
+        event.stopPropagation();
+        if (prevId) {
+            onNavigate?.(prevId);
+        }
+    };
+
+    const handleNext = (event: React.MouseEvent): void => {
+        event.stopPropagation();
+        if (nextId) {
+            onNavigate?.(nextId);
+        }
+    };
+
+    return (
+        <div
+            className={classNames('ba-BoundingBoxHighlightRect', { 'is-selected': isSelected })}
+            data-testid={`ba-BoundingBoxHighlightRect-${id}`}
+            onClick={handleClick}
+            role="presentation"
+            style={style}
+        >
+            {isSelected && total > 1 && (
+                <BoundingBoxHighlightNav
+                    currentIndex={currentIndex}
+                    onNext={handleNext}
+                    onPrev={handlePrev}
+                    total={total}
+                />
+            )}
+        </div>
+    );
+};
+
+export default BoundingBoxHighlightRect;

package/src/components/BoundingBoxHighlight/index.ts

@@ -0,0 +1,4 @@
+export { default as BoundingBoxHighlightList } from './BoundingBoxHighlightList';
+export { default as BoundingBoxHighlightNav } from './BoundingBoxHighlightNav';
+export { default as BoundingBoxHighlightRect } from './BoundingBoxHighlightRect';
+export type { BoundingBox } from '../../store/boundingBoxHighlights/types';

package/src/components/BoundingBoxHighlight/messages.ts

@@ -0,0 +1,14 @@
+import { defineMessages } from 'react-intl';
+
+export default defineMessages({
+    ariaLabelViewNextReference: {
+        id: 'ba.boundingBoxHighlight.viewNextReference',
+        description: 'Aria label for the button to view the next reference',
+        defaultMessage: 'View next reference',
+    },
+    ariaLabelViewPrevReference: {
+        id: 'ba.boundingBoxHighlight.viewPrevReference',
+        description: 'Aria label for the button to view the previous reference',
+        defaultMessage: 'View previous reference',
+    },
+});