box-annotations 5.1.0 → 5.2.0

package/package.json

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

package/src/@types/model.ts

@@ -1,5 +1,6 @@
 /* eslint-disable no-use-before-define */
 import { Permissions } from './api';
+import { TARGET_TYPE } from '../constants';
 
 // New Data Model Types
 export interface Annotation {
@@ -37,10 +38,17 @@ export type Dimensions = {
 };
 
 export interface Page {
-    type: 'page';
+    type: TARGET_TYPE.PAGE;
     value: number;
 }
 
+export interface Frame {
+    type: TARGET_TYPE.FRAME;
+    value: number;
+}
+
+export type Location = Page | Frame;
+
 export interface Path {
     clientId?: string;
     points: Array<Position>;
@@ -93,7 +101,7 @@ export interface Stroke {
 export type Target = TargetDrawing | TargetHighlight | TargetPoint | TargetRegion;
 
 export interface TargetDrawing {
-    location: Page;
+    location: Location;
     path_groups: Array<PathGroup>;
     type: 'drawing';
 }
@@ -106,12 +114,12 @@ export interface TargetHighlight {
 }
 
 export interface TargetPoint extends Position {
-    location: Page;
+    location: Location;
     type: 'point';
 }
 
 export interface TargetRegion {
-    location: Page;
+    location: Location;
     shape: Rect;
     type: 'region';
 }

package/src/BoxAnnotations.ts

@@ -4,6 +4,7 @@ import BaseAnnotator from './common/BaseAnnotator';
 import ImageAnnotator from './image/ImageAnnotator';
 import DocumentAnnotator from './document/DocumentAnnotator';
 import { IntlOptions, Permissions, PERMISSIONS, Type } from './@types';
+import MediaAnnotator from './media/MediaAnnotator';
 
 type Annotator = {
     CONSTRUCTOR: typeof BaseAnnotator;
@@ -60,6 +61,12 @@ const ANNOTATORS: Annotator[] = [
         TYPES: [Type.region],
         VIEWERS: ['Image'],
     },
+    {
+        CONSTRUCTOR: MediaAnnotator,
+        NAME: 'Media',
+        TYPES: [Type.region],
+        VIEWERS: ['Dash','MP4'],
+    },
 ];
 
 class BoxAnnotations {

package/src/common/BaseManager.ts

@@ -2,13 +2,15 @@ import * as ReactDOM from 'react-dom/client';
 import { IntlShape } from 'react-intl';
 import { Store } from 'redux';
 import { applyResinTags } from '../utils/resin';
+import { TARGET_TYPE } from '../constants';
 
 export type ResinTags = Record<string, unknown>;
 
 export type Options = {
     location?: number;
     referenceEl: HTMLElement;
-    resinTags?: ResinTags;
+    resinTags?: Record<string, unknown>;
+    targetType?: TARGET_TYPE;
 };
 
 export type Props = {
@@ -30,13 +32,19 @@ export default class BaseManager implements Manager {
 
     root: ReactDOM.Root | null = null;
 
-    constructor({ location = 1, referenceEl, resinTags = {} }: Options) {
+    targetType: TARGET_TYPE;
+
+    referenceEl: HTMLElement;
+
+    constructor({ location = 1, referenceEl, resinTags = {}, targetType = TARGET_TYPE.PAGE }: Options) {
         this.location = location;
         this.reactEl = this.insert(referenceEl, {
             ...resinTags,
             feature: 'annotations',
         });
 
+        this.referenceEl = referenceEl;
+        this.targetType = targetType;
         this.root = ReactDOM.createRoot(this.reactEl);
 
         this.decorate();

package/src/constants.ts

@@ -0,0 +1,23 @@
+export const ANNOTATOR_EVENT = {
+    fetch: 'annotationsfetched',
+    error: 'annotationerror',
+    scale: 'scaleannotations',
+    setVisibility: 'annotationsetvisibility',
+};
+
+export const MOUSE_PRIMARY = 1;
+
+/**
+ * This is the default location index for video annotations.
+ * Documents have locations that represent a page but that doesn't apply to 
+ * videos as they have no pages. The annnotations managers take  locations as
+ * parameters so we need to provide a default value that indicates that this is a 
+ * video annotation.
+ */
+export const MEDIA_LOCATION_INDEX = -1;
+
+
+export enum TARGET_TYPE {
+    FRAME = 'frame',
+    PAGE = 'page',
+}

package/src/drawing/DrawingAnnotations.tsx

@@ -10,6 +10,8 @@ import PopupDrawingToolbar, { PopupBaseRef } from '../components/Popups/PopupDra
 import { AnnotationDrawing, PathGroup } from '../@types';
 import { CreatorItemDrawing, CreatorStatus } from '../store';
 import './DrawingAnnotations.scss';
+import { TARGET_TYPE } from '../constants';
+import useVideoTiming from '../utils/useVideoTiming';
 
 export type Props = {
     activeAnnotationId: string | null;
@@ -29,6 +31,8 @@ export type Props = {
     setupDrawing: (location: number) => void;
     stashedPathGroups: Array<PathGroup>;
     undoDrawingPathGroup: () => void;
+    targetType: TARGET_TYPE;
+    referenceEl?: HTMLElement;
 };
 
 const DrawingAnnotations = (props: Props): JSX.Element => {
@@ -50,6 +54,8 @@ const DrawingAnnotations = (props: Props): JSX.Element => {
         setupDrawing,
         stashedPathGroups,
         undoDrawingPathGroup,
+        targetType,
+        referenceEl,
     } = props;
     const [isDrawing, setIsDrawing] = React.useState<boolean>(false);
     const [stagedRootEl, setStagedRootEl] = React.useState<DrawingSVGRef | null>(null);
@@ -60,6 +66,13 @@ const DrawingAnnotations = (props: Props): JSX.Element => {
     const stagedGroupRef = React.useRef<SVGGElement>(null);
     const { current: drawingSVGGroup } = stagedGroupRef;
 
+    const { isVideoSeeking, getCurrentVideoLocation } = useVideoTiming({
+        targetType,
+        referenceEl,
+        activeAnnotationId,
+        annotations,
+    });
+
     const handleAnnotationActive = (annotationId: string | null): void => {
         setActiveAnnotationId(annotationId);
     };
@@ -72,8 +85,16 @@ const DrawingAnnotations = (props: Props): JSX.Element => {
     const handleRedo = (): void => {
         redoDrawingPathGroup();
     };
+
+    const getCurrentLocation = (): number => { 
+        if (targetType === TARGET_TYPE.FRAME) {
+            return getCurrentVideoLocation();
+        }
+        return location;
+    };
     const handleReply = (): void => {
-        setStaged({ location, pathGroups: drawnPathGroups });
+        const annotationLocation = getCurrentLocation();
+        setStaged({ location: annotationLocation, pathGroups: drawnPathGroups });
         setStatus(CreatorStatus.staged);
     };
     const handleStart = (): void => {
@@ -95,11 +116,27 @@ const DrawingAnnotations = (props: Props): JSX.Element => {
         }
     }, [drawnPathGroups]);
 
+  
+    let annotationsToShow: AnnotationDrawing[] = [];
+    // For video annotations, we only show the active annotation and we wait for the video 
+    // to seek to the annotation location before showing it. This prevents annoations from being
+    // shown on the incorrect frame while the video is seeking.
+    if (targetType === TARGET_TYPE.FRAME ) {
+        if (!isVideoSeeking && activeAnnotationId) {
+            annotationsToShow = annotations.filter(annotation => annotation.id === activeAnnotationId);
+        }
+    } else {
+        annotationsToShow = annotations;
+    }
+
+    
+
+
     return (
         <>
             <DrawingList
                 activeId={activeAnnotationId}
-                annotations={annotations}
+                annotations={annotationsToShow}
                 className="ba-DrawingAnnotations-list"
                 onSelect={handleAnnotationActive}
             />

package/src/drawing/DrawingManager.tsx

@@ -14,6 +14,6 @@ export default class DrawingListManager extends BaseManager {
             this.root = ReactDOM.createRoot(this.reactEl);
         }
 
-        this.root.render(<DrawingAnnotationsContainer location={this.location} {...props} />);
+        this.root.render(<DrawingAnnotationsContainer referenceEl={this.referenceEl} targetType={this.targetType} location={this.location} {...props} />);
     }
 }

package/src/drawing/actions.ts

@@ -2,16 +2,18 @@ import { AppThunkDispatch, AppState, getCreatorStatus, CreatorStatus } from '../
 import { createAnnotationAction } from '../store/annotations';
 import { getFileVersionId } from '../store/options';
 import { PathGroup } from '../@types';
+import { TARGET_TYPE } from '../constants';
 import { resetDrawingAction, setDrawingLocationAction } from '../store/drawing';
 
 export type CreateArg = {
     location: number;
     message: string;
     pathGroups: Array<PathGroup>;
+    targetType: TARGET_TYPE;
 };
 
 export const createDrawingAction = (arg: CreateArg) => (dispatch: AppThunkDispatch, getState: () => AppState) => {
-    const { location, message, pathGroups } = arg;
+    const { location, message, pathGroups, targetType } = arg;
     const state = getState();
     const newAnnotation = {
         description: {
@@ -23,7 +25,7 @@ export const createDrawingAction = (arg: CreateArg) => (dispatch: AppThunkDispat
         },
         target: {
             location: {
-                type: 'page' as const,
+                type: targetType,
                 value: location,
             },
             path_groups: pathGroups,

package/src/highlight/actions.ts

@@ -2,6 +2,7 @@ import { AppThunkDispatch, AppState } from '../store';
 import { createAnnotationAction } from '../store/annotations';
 import { getFileVersionId } from '../store/options';
 import { Rect } from '../@types';
+import { TARGET_TYPE } from '../constants';
 
 export type CreateArg = {
     location: number;
@@ -23,7 +24,7 @@ export const createHighlightAction = (arg: CreateArg) => (dispatch: AppThunkDisp
         },
         target: {
             location: {
-                type: 'page' as const,
+                type: TARGET_TYPE.PAGE as const,
                 value: location,
             },
             shapes,

package/src/media/MediaAnnotator.scss

@@ -0,0 +1,20 @@
+.bp-media {
+    .ba-Layer {
+        position: absolute;
+        white-space: initial; // Overrides white-space: no-wrap inherited .bp-image
+        text-align: initial; // Overrides text-align: center inherited .bp-image
+        pointer-events: none;
+    }
+
+    // Applied to img element, which is managed by Preview SDK
+    .ba-is-drawing {
+        user-select: none; // Prevent visible selection highlight
+    }
+
+    // Raise the rendering order to override the stacking context created by the
+    // transform applied to each of the managers' react mount element to account for
+    // rotation
+    .ba-Layer--popup {
+        z-index: 4;
+    }
+}

package/src/media/MediaAnnotator.ts

@@ -0,0 +1,140 @@
+import { Unsubscribe } from 'redux';
+import BaseAnnotator, { Options } from '../common/BaseAnnotator';
+import PopupManager from '../popup/PopupManager';
+import { DrawingManager } from '../drawing';
+import { RegionCreationManager, RegionManager } from '../region';
+import { CreatorStatus, getCreatorStatus } from '../store/creator';
+import { getAnnotation, getFileId, getIsCurrentFileVersion, getRotation } from '../store';
+import { Manager } from '../common/BaseManager';
+import './MediaAnnotator.scss';
+import { MEDIA_LOCATION_INDEX, TARGET_TYPE } from '../constants';
+
+export const CSS_IS_DRAWING_CLASS = 'ba-is-drawing';
+export const VIDEO_PARENT_SELECTOR = '.bp-media';
+
+export default class MediaAnnotator extends BaseAnnotator {
+    annotatedEl?: HTMLElement;
+
+    managers: Set<Manager> = new Set();
+
+    storeHandler?: Unsubscribe;
+
+    constructor(options: Options) {
+        super(options);
+
+        // Subscribe to the store so that the annoator can capture changes to the creator status
+        this.storeHandler = this.store.subscribe(this.handleStore);
+    }
+
+    destroy(): void {
+
+        // If the store handler is present, unsubscribe from the store.
+        if (this.storeHandler) {
+            this.storeHandler();
+        }
+
+        if (this.managers) {
+            this.managers.forEach(manager => manager.destroy());
+        }
+
+        super.destroy();
+    }
+
+    getAnnotatedElement(): HTMLElement | null | undefined {
+        return this.containerEl?.querySelector(VIDEO_PARENT_SELECTOR);
+    }
+
+
+    addManagers(referenceEl: HTMLVideoElement, resinTags: { fileid: string|null; iscurrent: boolean }): void {
+        this.managers.add(new PopupManager({ location: MEDIA_LOCATION_INDEX, referenceEl, resinTags, targetType: TARGET_TYPE.FRAME }));
+        this.managers.add(new DrawingManager({ location: MEDIA_LOCATION_INDEX, referenceEl, resinTags, targetType: TARGET_TYPE.FRAME }));
+        this.managers.add(new RegionManager({ location: MEDIA_LOCATION_INDEX, referenceEl, resinTags, targetType: TARGET_TYPE.FRAME }));
+        this.managers.add(new RegionCreationManager({ location: MEDIA_LOCATION_INDEX, referenceEl, resinTags, targetType: TARGET_TYPE.FRAME }));
+    }
+
+    getManagers(parentEl: HTMLElement, referenceEl: HTMLVideoElement): Set<Manager> {
+        const fileId = getFileId(this.store.getState());
+        const isCurrentFileVersion = getIsCurrentFileVersion(this.store.getState());
+        const resinTags = { fileid: fileId, iscurrent: isCurrentFileVersion };
+        this.managers.forEach(manager => {
+            if (!manager.exists(parentEl)) {
+                manager.destroy();
+                this.managers.delete(manager);
+            }
+        });
+
+        if (this.managers.size === 0) {
+            this.addManagers(referenceEl, resinTags);
+        }
+
+        return this.managers;
+    }
+
+  
+
+    // returns the actual video element
+    getReference(): HTMLVideoElement | null | undefined {
+        return this.annotatedEl?.querySelector('video');
+    }
+
+    handleStore = (): void => {
+        const referenceEl = this.getReference();
+
+        if (!referenceEl) {
+            return;
+        }
+
+        if (getCreatorStatus(this.store.getState()) === CreatorStatus.started) {
+            referenceEl.classList.add(CSS_IS_DRAWING_CLASS);
+        } else {
+            referenceEl.classList.remove(CSS_IS_DRAWING_CLASS);
+        }
+    };
+
+    render(): void {
+        const referenceEl = this.getReference();
+        const rotation = getRotation(this.store.getState()) || 0;
+
+        if (!this.annotatedEl || !referenceEl) {
+            return;
+        }
+
+        this.getManagers(this.annotatedEl, referenceEl).forEach(manager => {
+            manager.style({
+                height: `${referenceEl.offsetHeight}px`,
+                left: `${referenceEl.offsetLeft}px`,
+                top: `${referenceEl.offsetTop}px`,
+                transform: `rotate(${rotation}deg)`,
+                width: `${referenceEl.offsetWidth}px`,
+            });
+            manager.render({
+                intl: this.intl,
+                store: this.store,
+            });
+        });
+
+        this.postRender();
+    }
+
+    // This function gets called by the client. We are using the name scrollToAnnotation to match 
+    // the other annotators as the client calls this function when it wants to show an annoation on the
+    // preview. The only difference is that we are using the video element's currentTime to scroll to the 
+    // annotation instead of the scrollLeft and scrollTop of the parent element.
+    scrollToAnnotation(annotationId: string | null): void {
+        if (!annotationId) {
+            return;
+        }
+
+        const annotation = getAnnotation(this.store.getState(), annotationId);
+        const annotationLocation = annotation?.target.location.value ?? 0
+        const video = this.getReference();
+        if (!annotation || !video || !this.annotatedEl) {
+            return;
+        }
+  
+        video.pause();
+        video.currentTime = annotationLocation / 1000;
+        
+    }
+}
+

package/src/popup/PopupLayer.tsx

@@ -14,6 +14,7 @@ import {
 } from '../store';
 import { PopupReference } from '../components/Popups/Popper';
 import './PopupLayer.scss';
+import { TARGET_TYPE } from '../constants';
 
 export type Props = {
     createDrawing?: (arg: DrawingCreateArg) => void;
@@ -28,6 +29,7 @@ export type Props = {
     setMessage: (message: string) => void;
     staged?: CreatorItem | null;
     status: CreatorStatus;
+    targetType: TARGET_TYPE;
 };
 
 const modeStagedMap: { [M in Mode]?: (staged: CreatorItem | null) => boolean } = {
@@ -49,6 +51,7 @@ const PopupLayer = (props: Props): JSX.Element | null => {
         setMessage,
         staged,
         status,
+        targetType,
     } = props;
 
     const [reference, setReference] = React.useState<PopupReference | null>(null);
@@ -70,11 +73,11 @@ const PopupLayer = (props: Props): JSX.Element | null => {
         }
 
         if (isCreatorStagedHighlight(staged)) {
-            createHighlight({ ...staged, message });
+            createHighlight({ ...staged, message, targetType });
         } else if (isCreatorStagedRegion(staged)) {
-            createRegion({ ...staged, message });
+            createRegion({ ...staged, message, targetType });
         } else if (isCreatorStagedDrawing(staged)) {
-            createDrawing({ ...staged, message });
+            createDrawing({ ...staged, message, targetType });
         }
     };
 
@@ -82,6 +85,7 @@ const PopupLayer = (props: Props): JSX.Element | null => {
         setReference(referenceId ? document.querySelector(`[data-ba-reference-id="${referenceId}"]`) : null);
     }, [referenceId]);
 
+
     return (
         <>
             {canCreate && canReply && reference && staged && (

package/src/popup/PopupManager.tsx

@@ -13,7 +13,7 @@ export default class PopupManager extends BaseManager {
         if (!this.root) {
             this.root = ReactDOM.createRoot(this.reactEl);
         }
-
-        this.root.render(<PopupContainer location={this.location} {...props} />);
+       
+        this.root.render(<PopupContainer location={this.location}  {...props} targetType={this.targetType} />);
     }
 }

package/src/region/RegionAnnotations.tsx

@@ -2,24 +2,45 @@ import * as React from 'react';
 import RegionList from './RegionList';
 import { AnnotationRegion } from '../@types';
 import './RegionAnnotations.scss';
+import useVideoTiming from '../utils/useVideoTiming';
+import { TARGET_TYPE } from '../constants';
 
-type Props = {
+export type Props = {
     activeAnnotationId: string | null;
     annotations: AnnotationRegion[];
     setActiveAnnotationId: (annotationId: string | null) => void;
+    referenceEl?: HTMLElement;
+    targetType: TARGET_TYPE;
 };
 
 const RegionAnnotations = (props: Props): JSX.Element => {
-    const { activeAnnotationId, annotations, setActiveAnnotationId } = props;
+    const { activeAnnotationId, annotations, setActiveAnnotationId, referenceEl, targetType } = props;
+    const { isVideoSeeking } = useVideoTiming({
+        targetType,
+        referenceEl,
+        activeAnnotationId: activeAnnotationId || null,
+        annotations: annotations || [],
+    });
 
     const handleAnnotationActive = (annotationId: string | null): void => {
         setActiveAnnotationId(annotationId);
     };
 
+    let annotationsToShow: AnnotationRegion[] = []
+  
+    if (targetType === TARGET_TYPE.FRAME) {
+        if (!isVideoSeeking && activeAnnotationId) {
+            annotationsToShow = annotations.filter(annotation => annotation.id === activeAnnotationId);
+        }
+    } else {
+        annotationsToShow = annotations;
+    }
+    
+
     return (
         <RegionList
             activeId={activeAnnotationId}
-            annotations={annotations}
+            annotations={annotationsToShow}
             className="ba-RegionAnnotations-list"
             onSelect={handleAnnotationActive}
         />

package/src/region/RegionCreation.tsx

@@ -4,6 +4,8 @@ import RegionRect, { RegionRectRef } from './RegionRect';
 import { Rect } from '../@types';
 import { CreatorItemRegion, CreatorStatus } from '../store/creator';
 import './RegionCreation.scss';
+import { TARGET_TYPE } from '../constants';
+import { getVideoCurrentTimeInMilliseconds } from '../utils/useVideoTiming';
 
 type Props = {
     isCreating: boolean;
@@ -14,6 +16,8 @@ type Props = {
     setStaged: (staged: CreatorItemRegion | null) => void;
     setStatus: (status: CreatorStatus) => void;
     staged?: CreatorItemRegion | null;
+    targetType: TARGET_TYPE;
+    referenceEl?: HTMLElement;
 };
 
 type State = {
@@ -45,8 +49,10 @@ export default class RegionCreation extends React.PureComponent<Props, State> {
     };
 
     handleStop = (shape: Rect): void => {
-        const { location, setStaged, setStatus } = this.props;
-        setStaged({ location, shape });
+        const { location, setStaged, setStatus, targetType, referenceEl } = this.props;
+        const annotationLocation = targetType !== TARGET_TYPE.FRAME ? location : getVideoCurrentTimeInMilliseconds(referenceEl as HTMLVideoElement);
+
+        setStaged({ location: annotationLocation, shape });
         setStatus(CreatorStatus.staged);
     };
 

package/src/region/RegionCreationManager.tsx

@@ -14,6 +14,6 @@ export default class RegionManager extends BaseManager {
             this.root = ReactDOM.createRoot(this.reactEl);
         }
 
-        this.root.render(<RegionCreationContainer location={this.location} {...props} />);
+        this.root.render(<RegionCreationContainer targetType={this.targetType} referenceEl={this.referenceEl} location={this.location} {...props} />);
     }
 }

package/src/region/RegionManager.tsx

@@ -14,6 +14,6 @@ export default class RegionListManager extends BaseManager {
             this.root = ReactDOM.createRoot(this.reactEl);
         }
 
-        this.root.render(<RegionAnnotationsContainer location={this.location} {...props} />);
+        this.root.render(<RegionAnnotationsContainer location={this.location} referenceEl={this.referenceEl} targetType={this.targetType} {...props} />);
     }
 }

package/src/region/actions.ts

@@ -2,15 +2,17 @@ import { AppThunkDispatch, AppState } from '../store';
 import { createAnnotationAction } from '../store/annotations';
 import { getFileVersionId } from '../store/options';
 import { Rect } from '../@types';
+import { TARGET_TYPE } from '../constants';
 
 export type CreateArg = {
     location: number;
     message: string;
     shape: Rect;
+    targetType: TARGET_TYPE;
 };
 
 export const createRegionAction = (arg: CreateArg) => (dispatch: AppThunkDispatch, getState: () => AppState) => {
-    const { location, message, shape } = arg;
+    const { location, message, shape, targetType } = arg;
     const state = getState();
     const newAnnotation = {
         description: {
@@ -22,7 +24,7 @@ export const createRegionAction = (arg: CreateArg) => (dispatch: AppThunkDispatc
         },
         target: {
             location: {
-                type: 'page' as const,
+                type: targetType,
                 value: location,
             },
             shape,

package/src/store/annotations/selectors.ts

@@ -1,12 +1,20 @@
 import getProp from 'lodash/get';
 import { Annotation } from '../../@types';
 import { AppState } from '../types';
+import { MEDIA_LOCATION_INDEX } from '../../constants';
 
 type State = Pick<AppState, 'annotations'>;
 
 export const getActiveAnnotationId = ({ annotations }: State): string | null => annotations.activeId;
 export const getAnnotation = ({ annotations }: State, id: string): Annotation | undefined => annotations.byId[id];
 export const getAnnotations = ({ annotations }: State): Annotation[] => [...Object.values(annotations.byId)];
-export const getAnnotationsForLocation = (state: State, location: number): Annotation[] =>
-    getAnnotations(state).filter(annotation => getProp(annotation, 'target.location.value') === location);
+export const getAnnotationsForLocation = (state: State, location: number): Annotation[] => {
+    const annotations = getAnnotations(state);
+    // For video annotations the location will be -1 by default as there is no page number for videos. We will return all of the annotations
+    // and the component will filter them by the current play time of the video.
+    if (location === MEDIA_LOCATION_INDEX) {
+        return annotations;
+    }
+    return annotations.filter(annotation => getProp(annotation, 'target.location.value') === location);
+};
 export const getIsInitialized = ({ annotations }: State): boolean => annotations.isInitialized;