box-annotations 5.1.0 → 5.2.0

package/src/store/creator/selectors.ts

@@ -1,4 +1,5 @@
 import { AppState } from '../types';
+import { MEDIA_LOCATION_INDEX } from '../../constants';
 import { CreatorItem, CreatorItemDrawing, CreatorItemHighlight, CreatorItemRegion, CreatorStatus } from './types';
 
 type State = Pick<AppState, 'creator'>;
@@ -9,6 +10,18 @@ export const getCreatorReferenceId = (state: State): string | null => state.crea
 export const getCreatorStaged = (state: State): CreatorItem | null => state.creator.staged;
 export const getCreatorStagedForLocation = (state: State, location: number): CreatorItem | null => {
     const staged = getCreatorStaged(state);
+    // The location is typically a page and this selector was originally meant to only return the staged annotation
+    // (those that have been drawn but not saved) that belong to the page specified by the location. For documents, 
+    // the annotator creates new sets of managers(highlights, drawings, regions) for each page with the current 
+    // page number being the location e.g. page 4 of 10. This selector prevents a staged annotation from staying on 
+    // the screen when a user navigates to a different page. By default, the location value for managers is 1 which is  
+    // why this selector works for images. Video annotations will not work this way because they reference a timestamp, not a page,
+    // and the drawing canvas is the video player which has no pages. In this case, we just need to get the staged annotation and do the 
+    // locaton check for MEDIA_LOCATION_INDEX. The MEDIA_LOCATION_INDEX is a special value, set in the manager, that is used to indicate that 
+    // the this is actually a staged video annotation with a timestamp as its location.
+    if (location === MEDIA_LOCATION_INDEX) {
+        return staged;
+    }
     return staged && staged.location === location ? staged : null;
 };
 export const getCreatorStatus = (state: State): CreatorStatus => state.creator.status;

package/src/test-utils/videoAnnotations.tsx

@@ -0,0 +1,178 @@
+import { ReactWrapper } from 'enzyme';
+import { TARGET_TYPE } from '../constants';
+import useVideoTiming from '../utils/useVideoTiming';
+import { AnnotationDrawing, AnnotationRegion } from '../@types/model';
+
+// Type alias for the list component wrapper
+type ListComponentWrapper = ReactWrapper;
+
+// Mock useVideoTiming hook
+const mockUseVideoTiming = useVideoTiming as jest.MockedFunction<typeof useVideoTiming>;
+
+const mockVideoTimingReturn = {
+    isVideoSeeking: false,
+    getCurrentVideoLocation: jest.fn(),
+};
+
+export interface VideoAnnotationTestConfig {
+    componentName: string;
+    getWrapper: (props: unknown) => ReactWrapper;
+    findListComponent: (wrapper: ReactWrapper) => ListComponentWrapper;
+    videoAnnotations: AnnotationDrawing[]|AnnotationRegion[] ;
+    regularAnnotations: AnnotationDrawing[]|AnnotationRegion[];
+    activeAnnotationId: string;
+    nonExistentAnnotationId: string;
+}
+
+export const createVideoAnnotationTests = (config: VideoAnnotationTestConfig): void => {
+    const {
+        componentName,
+        getWrapper,
+        findListComponent,
+        videoAnnotations,
+        regularAnnotations,
+        activeAnnotationId,
+        nonExistentAnnotationId,
+    } = config;
+
+    beforeEach(() => {
+        mockUseVideoTiming.mockReturnValue(mockVideoTimingReturn);
+    });
+
+    describe(`${componentName} video annotations`, () => {
+        describe('TARGET_TYPE.FRAME target type', () => {
+            test('should show only active annotation when not seeking and active annotation exists', () => {
+                mockVideoTimingReturn.isVideoSeeking = false;
+                
+                const wrapper = getWrapper({
+                    targetType: TARGET_TYPE.FRAME,
+                    annotations: videoAnnotations,
+                    activeAnnotationId,
+                });
+
+                const listComponent = findListComponent(wrapper);
+                const annotations = listComponent.prop('annotations');
+                expect(annotations).toHaveLength(1);
+                expect((annotations as AnnotationDrawing[] | AnnotationRegion[])[0].id).toBe(activeAnnotationId);
+            });
+
+            test('should show no annotations when seeking and active annotation exists', () => {
+                mockVideoTimingReturn.isVideoSeeking = true;
+                
+                const wrapper = getWrapper({
+                    targetType: TARGET_TYPE.FRAME,
+                    annotations: videoAnnotations,
+                    activeAnnotationId,
+                });
+
+                const listComponent = findListComponent(wrapper);
+                expect(listComponent.prop('annotations')).toHaveLength(0);
+            });
+
+            test('should show no annotations when not seeking but no active annotation', () => {
+                mockVideoTimingReturn.isVideoSeeking = false;
+                
+                const wrapper = getWrapper({
+                    targetType: TARGET_TYPE.FRAME,
+                    annotations: videoAnnotations,
+                    activeAnnotationId: null,
+                });
+
+                const listComponent = findListComponent(wrapper);
+                expect(listComponent.prop('annotations')).toHaveLength(0);
+            });
+
+            test('should show no annotations when seeking and no active annotation', () => {
+                mockVideoTimingReturn.isVideoSeeking = true;
+                
+                const wrapper = getWrapper({
+                    targetType: TARGET_TYPE.FRAME,
+                    annotations: videoAnnotations,
+                    activeAnnotationId: null,
+                });
+
+                const listComponent = findListComponent(wrapper);
+                expect(listComponent.prop('annotations')).toHaveLength(0);
+            });
+
+            test('should call useVideoTiming with correct parameters for TARGET_TYPE.FRAME type', () => {
+                const referenceEl = document.createElement('video');
+                
+                getWrapper({
+                    targetType: TARGET_TYPE.FRAME,
+                    annotations: videoAnnotations,
+                    activeAnnotationId,
+                    referenceEl,
+                });
+
+                expect(mockUseVideoTiming).toHaveBeenCalledWith({
+                    targetType: TARGET_TYPE.FRAME,
+                    referenceEl,
+                    activeAnnotationId,
+                    annotations: videoAnnotations,
+                });
+            });
+        });
+
+        describe('useVideoTiming integration', () => {
+            test('should call useVideoTiming hook on component mount', () => {
+                const referenceEl = document.createElement('video');
+                
+                getWrapper({
+                    targetType: TARGET_TYPE.FRAME,
+                    annotations: videoAnnotations,
+                    activeAnnotationId,
+                    referenceEl,
+                });
+
+                expect(mockUseVideoTiming).toHaveBeenCalledTimes(1);
+            });
+
+            test('should pass correct parameters to useVideoTiming for TARGET_TYPE.PAGE type', () => {
+                const referenceEl = document.createElement('div');
+                
+                getWrapper({
+                    targetType: TARGET_TYPE.PAGE,
+                    annotations: regularAnnotations,
+                    activeAnnotationId,
+                    referenceEl,
+                });
+
+                expect(mockUseVideoTiming).toHaveBeenCalledWith({
+                    targetType: TARGET_TYPE.PAGE,
+                    referenceEl,
+                    activeAnnotationId,
+                    annotations: regularAnnotations,
+                });
+            });
+        });
+
+        describe('annotation filtering edge cases', () => {
+            test('should handle empty annotations array for TARGET_TYPE.FRAME type', () => {
+                mockVideoTimingReturn.isVideoSeeking = false;
+                
+                const wrapper = getWrapper({
+                    targetType: TARGET_TYPE.FRAME,
+                    annotations: [],
+                    activeAnnotationId: nonExistentAnnotationId,
+                });
+
+                const listComponent = findListComponent(wrapper);
+                expect(listComponent.prop('annotations')).toHaveLength(0);
+            });
+
+            test('should handle active annotation that does not exist in annotations array', () => {
+                mockVideoTimingReturn.isVideoSeeking = false;
+                
+                const wrapper = getWrapper({
+                    targetType: TARGET_TYPE.FRAME,
+                    annotations: videoAnnotations,
+                    activeAnnotationId: nonExistentAnnotationId,
+                });
+
+                const listComponent = findListComponent(wrapper);
+                expect(listComponent.prop('annotations')).toHaveLength(0);
+            });
+        });
+    });
+};

package/src/utils/useVideoTiming.ts

@@ -0,0 +1,112 @@
+import { useState, useEffect, useCallback } from "react";
+import { TARGET_TYPE } from "../constants";
+
+
+
+export interface UseVideoTimingProps {
+    targetType: TARGET_TYPE;
+    referenceEl?: HTMLElement;
+    activeAnnotationId: string | null;
+    annotations: Array<{ id: string; target: { location: { value: number } } }>;
+}
+
+export interface UseVideoTimingReturnType {
+    isVideoSeeking: boolean;
+    getCurrentVideoLocation: () => number;
+}
+
+export function getVideoCurrentTimeInMilliseconds(video: HTMLVideoElement): number {
+    return (video?.currentTime ?? 0) * 1000;
+}
+
+/**
+ * This hook is used to keep track of when the video is currently seeking and when it has reached
+ * the target time definined in the annotation. This is necessary because we cannot control how long it
+ * takes for the video to seek to the target time and we do not want to display an annotation on the video player 
+ * at the wrong time. For example, if an annotation is defined at being at 20 seconds into the video and
+ * the video just loaded and needs to buffer in order to get to 20 seconds, we do not want the annotation
+ * drawing or region to be shown until the video has finished seeking and is at the correct time. The hook
+ * works by listenting the video seeking, seeked, and timeupdate events and setting the isVideoSeeking state
+ * based on these events. The hook will be used with both video drawing and video region annotations.
+ */
+const useVideoTiming = ({
+    targetType,
+    referenceEl,
+    activeAnnotationId,
+    annotations,
+}: UseVideoTimingProps): UseVideoTimingReturnType => {
+    const [isVideoSeeking, setIsVideoSeeking] = useState<boolean>(false);
+    const [targetVideoTime, setTargetVideoTime] = useState<number | null>(null);
+
+
+    const getCurrentVideoTimeStamp = useCallback((): number => { 
+         return getVideoCurrentTimeInMilliseconds(referenceEl as HTMLVideoElement);
+    }, [referenceEl]);
+
+    // Handle video seeking events
+    useEffect(() => {
+        if (targetType !== TARGET_TYPE.FRAME || !referenceEl) {
+            return undefined;
+        }
+        
+        const handleSeeking = (): void => {
+            setIsVideoSeeking(true);
+        };
+
+        const handleSeeked = (): void => {
+            setIsVideoSeeking(false);
+            setTargetVideoTime(null);
+        };
+
+        const handleTimeUpdate = (): void => {
+            if (isVideoSeeking && targetVideoTime !== null) {
+                const currentVideoTimePosition = getCurrentVideoTimeStamp();
+                const timeDiff = Math.abs(currentVideoTimePosition - targetVideoTime);
+                
+                // Consider the video has reached the target time if within 100ms
+                if (timeDiff <= 100) {
+                    setIsVideoSeeking(false);
+                    setTargetVideoTime(null);
+                }
+            }
+        };
+
+        referenceEl.addEventListener('seeking', handleSeeking);
+        referenceEl.addEventListener('seeked', handleSeeked);
+        referenceEl.addEventListener('timeupdate', handleTimeUpdate);
+
+        return () => {
+            referenceEl.removeEventListener('seeking', handleSeeking);
+            referenceEl.removeEventListener('seeked', handleSeeked);
+            referenceEl.removeEventListener('timeupdate', handleTimeUpdate);
+        };
+    }, [targetType, referenceEl, isVideoSeeking, targetVideoTime, getCurrentVideoTimeStamp]);
+
+    // Set target video time when activeAnnotationId changes
+    useEffect(() => {
+        if (targetType === TARGET_TYPE.FRAME && activeAnnotationId && referenceEl) {
+            const currentVideoTimePosition = getCurrentVideoTimeStamp();
+            
+            // Find the annotation to get its target time
+            const annotation = annotations.find(ann => ann.id === activeAnnotationId);
+            if (annotation) {
+                const annotationTimePosition = annotation.target.location.value;
+                const timeDiff = Math.abs(currentVideoTimePosition - annotationTimePosition);
+                
+                // If the video is not at the annotation's time, set seeking state
+                if (timeDiff > 100) {
+                    setTargetVideoTime(annotationTimePosition);
+                    setIsVideoSeeking(true);
+                }
+            }
+        }
+    }, [activeAnnotationId, targetType, referenceEl, annotations, getCurrentVideoTimeStamp]);
+
+    return {
+        isVideoSeeking,
+        getCurrentVideoLocation: getCurrentVideoTimeStamp,
+    };
+};
+
+export default useVideoTiming;
+

package/src/constants.js

@@ -1,8 +0,0 @@
-export const ANNOTATOR_EVENT = {
-    fetch: 'annotationsfetched',
-    error: 'annotationerror',
-    scale: 'scaleannotations',
-    setVisibility: 'annotationsetvisibility',
-};
-
-export const MOUSE_PRIMARY = 1;